Publish And Release

This guide answers three practical questions:

1. what gets published
2. what still needs to be configured outside the repo
3. what GitHub Actions already exists in the repo to automate release and docs deployment

What We Publish

The npm package is:

• @kontourai/veritas

The current publish surface is defined in package.json and includes:

• bin/ for the CLI entrypoints
• src/ for implementation logic
• schemas/ for the contract surface
• repo-maps/ for current Repo Map examples
• repo-standards/ for current Repo Standards examples
• docs/ for packaged documentation
• examples/ for canonical examples
• README.md and LICENSE

That means the npm package is not only the CLI binary. It also publishes the schema and example material needed to understand and extend Veritas.

What GitHub Actions Already Does

This repo now ships three core automation lanes:

• CI runs npm run verify, npm test, and the line-coverage gate on Node 20 and Node 22
• Docs Pages builds the Markdown docs into a GitHub Pages site
• Publish NPM verifies on Node 20 and Node 22, then publishes @kontourai/veritas on tag pushes like v0.4.0

What We Need From You

1. GitHub Pages

To make the Pages workflow live, you need repo admin access and should:

1. open GitHub repo settings
2. go to Pages
3. set the source to GitHub Actions

Once that is enabled, the Docs Pages workflow can deploy the generated site to:

• https://kontourai.github.io/veritas/

2. npm Publishing

The checked-in publish workflow is configured for npm trusted publishing through GitHub Actions OIDC.

What you need to do on the npm side:

1. make sure the @kontourai/veritas package name is available to the @kontourai org
2. open the package settings on npmjs.com and add a trusted publisher for GitHub Actions
3. set the publisher to:
   • organization or user: kontourai
   • repository: veritas
   • workflow filename: publish-npm.yml
   • allowed action: npm publish
4. for an already-published package, alternatively configure it from a local authenticated npm CLI with npm 11.15.0 or later:

   npm trust github @kontourai/veritas --repo kontourai/veritas --file publish-npm.yml --allow-publish
   

5. confirm the publishing identity can create or update @kontourai/veritas

Once that is configured, the workflow can publish without storing a long-lived npm publish token in GitHub Actions.

If trusted publishing is temporarily unavailable, the fallback is to restore token-based auth with an NPM_TOKEN secret, but that is intentionally not the default checked-in path.

3. Release Trigger

The current publish workflow triggers on tags matching:

• v*

So the normal release path is:

1. bump package.json version
2. commit the release
3. merge that commit to main
4. create and push a tag like v0.4.0 that points at the main commit you intend to release

Suggested First Publish Checklist

1. Enable GitHub Pages from Actions.
2. Confirm npm trusted publishing is configured for kontourai/veritas and workflow publish-npm.yml.
3. Run the CI workflow on main.
4. Run the Docs Pages workflow once manually.
5. Confirm the package metadata looks right on npm:
   • package name
   • homepage
   • repository
   • bugs URL
   • README rendering
6. Tag the first release and let Publish NPM run.

The current coverage gate enforces at least 80% aggregate line coverage.

Badges

The root README should expose at least:

• npm version badge
• CI badge

If GitHub Pages is enabled, adding a docs badge is also reasonable, but the core two are npm and CI.