Lexicon Onboarding Skill

This page is written to be handed to an AI agent on its own. Point yours at this URL and it has everything needed to take a lexicon from nothing to published, without reading the rest of the authoring section first.

Every step is either a command to run or a check to make. Where a step needs depth, it links out. Do the steps in order: later ones assume earlier ones.

The step that is not automatable

Step 6 creates an npm trusted-publisher record by hand on npmjs.com. No command in this repo can do it, and skipping it produces a lexicon that builds, tests, and merges cleanly, then fails at release time with an error that looks like missing credentials. Two packages have already shipped this way. If you do nothing else on this page, do step 6.

What you are building

A lexicon is a plugin that teaches chant about one operational area. It lives in lexicons/<name>/, is published as @intentius/chant-lexicon-<name>, and is versioned in lockstep with core.

1. Scaffold

   Run everything on this page from the repository root.

   npx tsx packages/core/src/cli/main.ts init lexicon <name>
   npm install

   Verify it typechecks before writing anything:

   npx tsc --noEmit -p lexicons/<name>/tsconfig.build.json

   Detail: Scaffold a Lexicon.

2. Implement the plugin

   chant dev check-lexicon lexicons/<name> is the contract, and just check fails on any tier-1 item. Tier 1 wants all of this, so plan for it rather than discovering it at the gate:

   Requirement	Where it lives
   The package exports a LexiconPlugin	src/index.ts
   A Serializer with name, rulePrefix and serialize	src/serializer.ts
   lintRules() returns at least one rule	src/lint/rules/
   postSynthChecks() returns at least one check	src/lint/post-synth/, barrel via npm run generate:barrels
   Every rule id starts with rulePrefix or an extraRulePrefixes entry	ibid.
   completionProvider and hoverProvider registered	src/lsp/completions.ts, src/lsp/hover.ts
   docs() registered	src/codegen/docs.ts plus src/codegen/docs-cli.ts
   dist/manifest.json exists and declares chantVersion	produced by npm run prepack
   At least one example under examples/, and it builds	step 3
   Registered intrinsics are exported, with correct isTag / foldsAsCall	src/index.ts
   MCP tools and resources under one well-formed namespace	src/plugin.ts
   plugin.test.ts and serializer.test.ts exist	src/
   At least one .mdx doc page, reachable from the sidebar, with a diataxis quadrant	docs/pages/

   Depending on the platform you may also want observation, live export, and an emulator. Tier 2 adds auditCatalog() coverage for every post-synth check, three skills, and eight doc pages; it warns rather than failing.

   Detail: Implement Generate, Create a Serializer, Write Lint Rules, Post-Synth Checks, LSP & MCP Providers, Docs Site Setup.

3. Create an example workspace

   npm workspace resolution needs at least one dependent per package, or import("@intentius/chant-lexicon-<name>") fails from packages/core. Create lexicons/<name>/examples/basic-deployment/ with a package.json depending on both @intentius/chant and your lexicon, then add lexicons/<name>/examples/* to the root workspaces array.

   Full package.json shape: CI & Distribution.

4. Wire it into the monorepo

   npx tsx packages/core/src/cli/main.ts dev onboard <name>
   npm install

   This patches six files: the root package.json, the root tsconfig.json paths map, .github/workflows/chant.yml, the publish.yml test-job prepack line, and both smoke Dockerfiles. It is idempotent, and it prints a chant dev check-lexicon report at the end.

   Ignore one line in that printed report. It says to tag the first publish v<version>; that tag matches no workflow trigger. Step 7 has the real commands.

   You do not add a publish step. scripts/publish-packages.sh enumerates every non-private workspace package, so a new lexicon is published the moment it exists.

5. Verify locally

   npx vitest run lexicons/<name>            # your lexicon
   npm run prepack -w @intentius/chant-lexicon-<name>   # generated artifacts + dist/
   just check                                # build, lint, full suite, lexicon contract

   just check is build lint test check-lexicons. The last of those runs scripts/check-lexicons.ts. It loops every lexicons/* directory and runs the full tier-1 set against each one, then runs that lexicon’s own tsconfig.build.json build. Its KNOWN_FAILURES allowlist is currently empty, so every tier-1 check must pass for every lexicon, including yours. A tsc failure is never allowlistable.

   just smoke is separate and local-only. Run it once before the first release, because that is when your test/integration.sh section executes for the first time.

6. Create the npm trusted-publisher record

   Do this before the first release. On npmjs.com, open @intentius/chant-lexicon-<name>, then Settings, Trusted Publisher:

   Field	Value
   Organization / repository	INTENTIUS/chant
   Workflow filename	publish.yml
   Environment	leave empty

   The environment field matters. The publish job declares no environment:, so any value here fails to match the OIDC claims and the record silently does nothing.

   The record is per package. It is not inherited from the organization and not shared with the other lexicons, so a new one is always needed.

   A brand-new package name has to exist on the registry before npm will let you attach a record, so for a first-ever publish the order is: publish once by hand, create the record, and let every release after that go through CI.

7. Release

   just release patch                  # every package, in lockstep
   just release-lexicon <name> patch   # this lexicon only

   Never hand-roll the tag. .github/workflows/publish.yml triggers on chant-v* and lexicon-*-v* only; a bare v0.57.0 tag matches nothing and the release silently never happens.

   Publishing itself is scripts/publish-packages.sh, which enumerates every non-private workspace package. No workflow edit is needed for a new lexicon.

8. Confirm it actually published

   npm view @intentius/chant-lexicon-<name> version
   npm view @intentius/chant-lexicon-<name> dist.attestations

   A version with no attestation did not go out through trusted publishing, which means step 6 is incomplete even if the version number looks right.

When the publish run goes red

scripts/publish-packages.sh never stops at the first failure. Every package gets its attempt, the summary table names the ones that failed, and the run exits non-zero at the end. Re-running is safe: a package already at its version is skipped, so a partial release is recovered by dispatching the workflow again.

Symptom	Cause	Fix
ENEEDAUTH on your package while others publish	No trusted-publisher record	Step 6
registry REFUSED the OIDC exchange: HTTP 404	The registry saying the same thing outright	Step 6
registry ACCEPTED the OIDC exchange but publish still fails	The record is fine	Read the npm error; the auth path is not the problem
EOTP on the NPM_TOKEN fallback	The secret is a publish or granular token, so npm wants a one-time password	Replace it with an npm automation token
Your package sits a version behind the others	An earlier run failed on it	Fix its auth, then re-dispatch publish

Why ENEEDAUTH is misleading here

npm’s OIDC helper is written never to throw. When the token exchange fails it logs at verbose level and returns undefined, so npm publish falls through to ordinary auth and reports a bare ENEEDAUTH. That one error covers both “no record at all” and “a record that does not match this workflow”, and it reads exactly like having no credentials.

scripts/publish-packages.sh replays the exchange and prints the registry’s own status and message, so read that line instead of inferring. A successful exchange answers 201, not 200.

Because the record is matched against the workflow filename, a probe run from any workflow other than publish.yml returns 404 for every package and proves nothing.

Related pages

• Completeness Checklist — what a mature lexicon covers
• Package & Publish — build output and package shape
• CI & Distribution — what each patched file does and why
• Skills — shipping agent skills from your lexicon