ci(docs): guard a manual deploy against the published CLI

Deploying on the release tag stopped the site drifting ahead of npm, but
left one way back in: `workflow_dispatch` from main publishes main's
docs, unreleased flags included. That is the drift this workflow exists
to prevent, reachable by one button.

So check it instead of trusting the operator. On a dispatch from a
branch, the job installs the published CLI, regenerates the command
reference from its `--help` via KITE_DOCS_CLI, and fails if the
checked-in reference differs. A prose fix still goes out; a reference
documenting flags nobody can install does not. Dispatching from a `v*`
tag skips the check — CI already proved the reference matches that tag's
source — and CONTRIBUTING now names that as the way to republish.

Verified locally: the check fails against the published 0.7.0 (whose
--help predates the per-command examples) and passes against dist/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pungoyal

.github/workflows/docs.yml

@@ -69,6 +69,21 @@ jobs:
         run: npm run build
         working-directory: docs
 
+      # A manual deploy from a branch is the one path that can publish a command
+      # reference the released package does not match — the drift this workflow
+      # exists to prevent, reachable by one button. So check it rather than trust
+      # the operator: install the published CLI, regenerate the reference from
+      # *its* `--help`, and fail if what would be deployed differs. Dispatching
+      # from a `v*` tag needs no check — CI already proved the reference matches
+      # that tag's source.
+      - name: Verify the command reference matches the published CLI
+        if: github.event_name == 'workflow_dispatch' && !startsWith(github.ref, 'refs/tags/v')
+        run: |
+          npm ci --ignore-scripts
+          npm install --prefix "$RUNNER_TEMP/published" --no-save --ignore-scripts @pungoyal/kite-cli@latest
+          KITE_DOCS_CLI="$RUNNER_TEMP/published/node_modules/@pungoyal/kite-cli/dist/cli.js" \
+            node scripts/generate-command-reference.mjs --check
+
       # Pages plumbing is only meaningful on a real deployment — a tag push or a
       # manual dispatch. A PR or a plain push to main stops at the build above.
       - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

CHANGELOG.md

@@ -44,7 +44,12 @@ While the version is `0.x`, minor releases may contain breaking changes.
   forwards instead of backwards. The site and the npm package now move together
   on the `v*` tag; pull requests and `main` still build the site as a
   dead-link gate, and a documentation fix can be published between releases by
-  running the workflow manually.
+  dispatching the workflow from the release tag.
+
+  Dispatching from `main` instead is guarded rather than forbidden: the job
+  installs the published CLI, regenerates the command reference from *its*
+  `--help`, and refuses to deploy if the checked-in reference differs. Prose
+  fixes go out; unreleased flags cannot ride along.
 
 - **The README is an introduction again, not a second copy of the reference.**
   It had grown a full config-key table, the multi-account walkthrough and

CONTRIBUTING.md

@@ -73,8 +73,19 @@ The `Docs` workflow builds the site on every pull request and every push to
 but **deploys only on a `v*` release tag**. The published site therefore matches
 the published package: `docs/commands.md` is generated from `--help`, so
 deploying from `main` would advertise flags that `npm i -g @pungoyal/kite-cli`
-does not yet ship. To publish a documentation fix between releases, run the
-workflow by hand (**Actions → Docs → Run workflow**, from `main`).
+does not yet ship.
+
+To republish the site between releases, dispatch the workflow **from the release
+tag**, which carries exactly what was published:
+
+```bash
+gh workflow run Docs --ref v0.7.0
+```
+
+Dispatching from `main` is allowed but guarded: the job installs the published
+CLI, regenerates the command reference from *its* `--help`, and fails if the
+checked-in reference differs — so a prose fix goes out fine, while unreleased
+flags cannot ride along.
 
 Links from a docs page to source files or README sections use absolute
 `github.com` URLs (they live outside the site); links between docs pages stay as

scripts/generate-command-reference.mjs

@@ -22,7 +22,11 @@ import stripAnsi from 'strip-ansi';
 const execFileAsync = promisify(execFile);
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-const cli = join(root, 'dist', 'cli.js');
+// Normally the freshly built CLI in dist/. `KITE_DOCS_CLI` points it at another
+// binary — the docs deploy uses it to check the checked-in reference against the
+// *published* package, so a manual deploy cannot put flags on the site that the
+// released CLI does not have.
+const cli = process.env.KITE_DOCS_CLI ?? join(root, 'dist', 'cli.js');
 const outFile = join(root, 'docs', 'commands.md');
 
 const env = {
@@ -137,7 +141,11 @@ async function main() {
       existing = null;
     }
     if (existing !== content) {
-      console.error(`docs/commands.md is out of date. Run \`npm run docs:commands\` and commit the result.`);
+      console.error(
+        process.env.KITE_DOCS_CLI
+          ? `docs/commands.md does not match the help printed by ${cli}.`
+          : 'docs/commands.md is out of date. Run `npm run docs:commands` and commit the result.',
+      );
       process.exit(1);
     }
     console.log('docs/commands.md is up to date.');