Run a complete npm deployment pass for the kendex Pi extension packages under pi-extensions/. An optional package name in $ARGUMENTS limits the audit, the bump, the publish and the tags to that package; with no argument every package is in scope. The catalog policy test and the closing refresh and check read the whole catalog and take no package filter, so a scoped run still validates every package and can update unrelated ones whose merged source changed.

Intent

Find every pi-extensions/*/package.json package whose consumer-facing content changed since its last npm release, then validate it, land its version bump, and tag it; the tag push starts the GitHub workflow, which publishes it from the default branch. Then refresh the installed copies and verify. Leave no dirty or untracked files anywhere.

kendex distribution is independent of npm. kendex update-pi installs the catalog source; npm publishing populates the pi.dev gallery and lets external users run pi install npm:@vanillagreen/<name>. Skipping a publish never breaks kendex consumers.

Hard rules

• Publish only a commit that is on the default branch: the version bump lands through a pull request through the repository's normal gates and merge queue, never a direct push, and its tag names that merged commit after git fetch. The workflow refuses a tag whose commit the default branch does not hold.
• Publish only packages that need a new npm version. Use the scoped name from package.json (@vanillagreen/<name>).
• Per-package release tags are <unscoped-name>-v<version> at the bump commit (example pi-qol-v2.1.0). A version npm already serves is never published again; a missing tag for a served version is a tagging gap, repaired as Audit step 5 says.
• The tag push is the publish. .github/workflows/publish-npm.yml runs on it and dispatches its own publish job on the default branch, which publishes the version the tag names with npm trusted publishing. For a package npm already serves, this pass runs no npm publish and needs no npm login or token; a package npm does not serve yet is the first-release row of Audit step 7. Push one tag per git push: GitHub starts no workflow for a push that carries more than three tags.
• Each package's CHANGELOG.md is the release record. Consumer-facing changes since the last release sit under ### Unreleased; a release renames that heading to the new version. A package whose files changed since its tag with no ### Unreleased entry gets the entry written and merged before any bump.

Skip publish for

• Refactors with no behavior change, internal cleanup, comment or typo fixes.
• README or documentation edits, unless the gallery copy needs them.
• Repository-only files: tests, fixtures, tooling.

Choose the bump by the release-version rule. Write breaking-change entries under the release standard, which also defines compatibility.

Audit

1. Inspect git status --short --branch; the tree must be clean, and HEAD must equal the freshly fetched default-branch ref, so nothing unmerged is audited. Pin that commit as <base> and read every package's files and versions from it.
2. Enumerate the packages in scope: find pi-extensions -maxdepth 2 -name package.json | sort, reading name and version from each.
3. For each package compute the npm version (npm view <name> version), the unreleased entry count (the - lines under ### Unreleased in its CHANGELOG.md), and the tag for its current version. An E404 from that lookup means npm serves no version of the package, which is its own row below; any other lookup failure stops the pass with the error npm printed. Where npm serves a version, place the manifest version against it with kendex version-compare <version> <npm version>, whose verdict is newer, same or older; step 4 acts on older and the rows in step 7 mean newer and same, because a string comparison misreads both a lexical boundary such as 1.10.0 against 1.9.0 and a prerelease identifier.
4. Hold every package's verdict before touching anything. A verdict of older means npm serves a version ahead of the default branch, which no ordinary pass produces: stop there and report the package and both versions. Nothing below runs until every package in scope has a verdict, so one package's repair cannot reach the remote ahead of another package's stop.
5. Repair a tagging gap: when npm already serves the manifest version and its tag is missing, tag that version's bump commit on the fetched default branch and push the tag; a bootstrapped first release is tagged at the commit the admin published it from, not the first commit that set its version. It publishes nothing: where the tag's commit carries the publish workflow, the publish run its push dispatches on the default branch reports publish-npm: served=; find it as in Publish step 3. The tag gives the drift check below a baseline the package would otherwise never reach.
6. Compute the file drift from that tag (git diff --name-only <tag>..<base> -- pi-extensions/<dir>). A package whose version is newer than npm takes its drift from its release commit instead, <release>: the newest commit that set pi-extensions/<dir>/package.json to that version. A tag for its version, where one exists, marks a publish that has not passed yet, so its row below reads the versions and the drift from <release>.
7. Classify each package:
   • npm serves no version: this is the package's first release, which npm trusted publishing cannot make. Stop the pass for that package, publish and tag nothing for it, and report it as needing the one-time bootstrap in the npm-deploy skill § Trusted publishing. The admin who makes it tags the commit it was published from, so the next pass reads it as a served package.
   • version newer than npm: publish it (a bump already merged and not yet published) when its drift from <release> is empty. When the package changed since <release>, bump it again: the workflow refuses a tag whose package directory differs from the default branch's with publish-npm: moved=<tag>.
   • version equals npm and unreleased entries exist: bump it first.
   • version equals npm, no unreleased entry, files changed since the tag: decide whether the change is consumer-facing; if it is, write the entry first; if not, skip and say why.
   • nothing changed: skip.

Documentation freshness check

For each package to bump, compare the changed code to its docs before bumping: README, the settings table in package.json under kendex.extensionManager.settings, and the changelog entries. Fix stale setting keys, config examples, commands, tool names, defaults, behavior claims and install instructions first, through the same pull request. Config examples under kendex.extensionManager.config use the scoped key ("@vanillagreen/pi-web-tools", never "pi-web-tools").

Validation

For every package in scope, before the bump lands, first run that package's setup the way its lane in .github/workflows/skill-tests.yml does, which owns those steps: a pinned peer install for some packages and npm ci for others. A fresh checkout without it stops on a missing module rather than on the package. Then run the strongest validation the package declares that a runner can complete: npm run test:ci when scripts.test:ci exists, which is the catalog's credential-free entry point, else npm run check when scripts.check exists, else the available typecheck, test:unit, test and build scripts. Run node --test pi-extensions/package-policy.test.mjs, which reads the whole catalog whatever the run is scoped to. Do not proceed on a failing validation unless the user explicitly accepts the risk.

Version bump

Land every bump in one pull request: in each package run npm version <new> --no-git-tag-version from its own directory, so a committed package-lock.json follows the manifest, then rename its ### Unreleased heading to ### <new version>; change nothing else. Use the subject chore(pi-extensions): npm release wave version bumps [no-changelog]. Take the PR through review, the review gate, CI and the merge queue, then fetch the default branch again and pin its head as <head>. When this run lands no bump, <head> is <base>.

Publish, tag, refresh, verify

For each package to publish, find its release commit first: <release> as Audit step 6 defines it, read on <head>, which is this run's merged bump where this run bumped that package. A wave mixes packages bumped now with packages bumped in an earlier run, so one commit cannot stand for all of them.

1. When the tag <unscoped-name>-v<version> already exists on the remote (git ls-remote --tags origin refs/tags/<tag> prints a line), from an earlier pass whose publish did not pass, skip the tag and the push: note <since>, dispatch as in step 4, then find and watch the run as in step 3. Otherwise note the time as <since> (date -u +%Y-%m-%dT%H:%M:%SZ), and from the repository checkout tag <release> as <unscoped-name>-v<version> and push that tag alone: git push origin <tag>. The push starts a short run of .github/workflows/publish-npm.yml whose one job dispatches the publish run on the default branch; the publish run does the work. tools/publish-npm --help lists every check it makes and every answer it prints.
2. Check that the tag's commit carries the workflow: git cat-file -e <tag>:.github/workflows/publish-npm.yml. When it fails, the push started no run: dispatch the publish yourself as in step 4 and watch that run.
3. Find the publish run: gh run list --workflow publish-npm.yml --event workflow_dispatch --created ">=<since>" --json databaseId,displayTitle,url --jq 'map(select(.displayTitle == "publish-npm <tag>"))'. Every run of the workflow carries its tag in that title. Read again every 10 seconds; when no run appears within 3 minutes, find the tag's own run with --event push --branch <tag> in place of --event workflow_dispatch, read its log (gh run view <databaseId> --log), and report the publication open with that run's URL. Watch the publish run with gh run watch <databaseId> --exit-status, then confirm npm view <name> version reports the new version, and keep the run URL for the final report.
4. When the publish run fails, read its log (gh run view <databaseId> --log-failed) and fix the cause. A fix under pi-extensions/<dir>, and a run that answers publish-npm: moved=<tag>, need a new version: npm's provenance names the default branch's commit, so the same tag can no longer publish. Land that bump as in Version bump and tag it as in step 1. For any other cause, note a new <since> and run it again against the same tag: gh workflow run publish-npm.yml --ref main -f tag=<tag>; find and watch that run as in step 3. The publish job runs on the default branch alone, so a dispatch from any other ref fails before it starts. A tag already on the remote from an earlier failed run takes this dispatch too, never a second push. Until a run passes, the package's publication stays open in the final report. It blocks nothing else: continue with the other packages and the refresh below.

Then refresh the installed copies, which is a whole-scope pass and can move packages this run did not publish: kendex refresh --global --yes, which fetches the sources the global scope declares and needs --yes because a harness shell has no terminal to ask the write question at; a declared-source fetch there that fails only prints a warning: line and refreshes from the cached copy, so stop the pass on that line and report it rather than reading the check below as proof. Then kendex update-pi --scope global, then kendex update-pi --check --scope global, which must report every package up to date. update-pi finds a second copy itself and prints a pi-shadow-package=<name> block naming the managed copy, the shadow copy and the remedy. Report every block those two runs print, rather than listing Pi's extensions/ directory by hand: the scan matches a loose module file as well as a directory, under any name, by the manifest and entry set rather than the directory name. Confirm git status --short --branch is clean.

Final report

Report the packages audited and how each was classified, the versions published with their npm confirmation and publish run URL, every publication still open with its failed run URL, every first release waiting for its bootstrap, the bump pull request and the tags pushed, the validation commands and their results, the refresh and check results, any shadow copy found, and the final git status.

Trusted publishing

.github/workflows/publish-npm.yml runs on a <unscoped-name>-v<version> tag, and its one job there dispatches the same workflow on main. The dispatched run's publish job publishes with npm trusted publishing: npm gives the job a one-publish credential in exchange for its GitHub identity, so no npm token exists. tools/publish-npm --help lists every check and answer.

• Every package needs, on npmjs.com under its Settings, a GitHub Actions trusted publisher with organization vanillagreencom, repository kendex, workflow filename publish-npm.yml, environment kendex, and the allowed action npm publish ticked. An organization admin sets it once per package.
• The kendex environment deploys from main only (D003), so a branch's edited copy of the workflow or of tools/publish-npm gets no credential, and a tag on unreviewed code only reaches main's copy, which refuses a tag whose commit main does not hold.
• npm matches the workflow by filename. Renaming the file, or calling it from another workflow, breaks every publish until each package's trusted publisher names the new filename; an admin adds a new publisher beside the old and then deletes the old one.
• Trusted publishing cannot make a package's first publish; tools/publish-npm refuses such a package with first-release=<name>. An admin publishes the first version by hand from the fetched main head, sets its trusted publisher, then tags that same commit and pushes the tag.
• gh workflow run publish-npm.yml --ref main -f tag=<unscoped-name>-v<version> runs the publish against an existing tag, for a failed run or a tag whose commit predates the workflow. Either publishes only while the package's directory on main is the same as at the tag; tools/publish-npm refuses a package changed since its tag with moved=<tag>. -f dry_run=true runs every check and publishes nothing.