docs: refresh the CLI reference for stash 1.1.1, and stop it going stale

[coderdan]

Stacked on #101 — it changes the same generator and the same generated pages. Merge #101 first and GitHub retargets this to main.

The docs are a CLI minor behind, and have been for eleven days

stash 1.1.1 published on 2026-08-20. Production still serves a reference generated from 1.0.0. It is in every production build log:

07:59:21  $ tsx scripts/generate-cli-docs.ts
07:59:29  ⚠ Could not run stash@1.1.1; using cached fixture.
07:59:29  ✓ Generated 14 CLI reference page(s) for stash v1.0.0

npm view stash version resolves 1.1.1 correctly. The next step — npx --yes stash@1.1.1 manifest --json — does not work in the Vercel build sandbox, and the generator fell back to the committed fixture and carried on. Nothing failed, because a fallback that always works cannot fail.

Why the npx invocation fails there is still unknown: the generator ran it with stdio: ["ignore", "pipe", "ignore"], so the reason was discarded. That is fixed below.

What was actually stale

Not just a version stamp. 1.1.1:

• removes db validate — documented today, gone from the CLI
• adds eql preflight — role/permission probe that names the statement each gap blocks
• adds eql verify — catalog comparison that catches a partial EQL install which reports success and then fails at query time

Both new pages carry real prose about managed-Postgres behaviour. Anyone reading the reference for the last eleven days could not find either command.

The build no longer touches the network

generate-docs:cli reads the committed fixture and renders it. What deploys is exactly what is in the repo, and it is reviewable in the diff.

Refreshing the fixture is a separate, explicit step:

bun run generate-docs:cli:refresh

which resolves the latest published CLI, runs it, and rewrites scripts/fixtures/stash-manifest.json. It has no fallback — if it cannot run the CLI it fails — and it inherits stderr rather than discarding it, so a future failure explains itself.

Automating the release follow-through

.github/workflows/cli-manifest.yml, daily, same shape as the EQL pin workflow in #76: compares npm view stash version against the cached manifest, and when they differ, refreshes, regenerates, runs the links check, and opens a PR reporting whether links still resolve.

Not auto-merged, deliberately. A release removes commands as well as adding them — this one dropped db validate — and each removal is a page section that disappears and a URL anchor that stops resolving. The workflow removes the need to remember, not the need to review.

Two things worth knowing:

• ci: open a PR when a new EQL patch release lands #76 is the same automation for EQL and has been open since 28 July. A workflow that opens PRs nobody merges is stale docs with extra steps.
• ci: open a PR when a new EQL patch release lands #76 targets DOCS_BRANCH: v2. That was the docs line when it was written; it is main now. It needs that changed before it will do anything useful.

Also: duplicate headings on the group pages

#101 named the generic headings on single-command pages. The group pages come from a second render path it did not touch, and were worse: eql.mdx carried five identical #### Examples and eight identical #### Flags. That is eight duplicate anchors on one page, and eight chunks a retriever cannot tell apart.

-#### Flags
+#### stash eql verify flags

Verified

generate-docs:cli with no network reproduces the committed pages exactly — the determinism claim, tested rather than asserted. validate-links unchanged at its 9-failure baseline (all pre-existing, in generated integration api-reference dirs absent from a local checkout). types:check and biome check clean.

---

Correction after review

The framing above ("stale for eleven days") understates it. Older build logs show the npx step has never succeeded on Vercel:

2026-08-16  ⚠ Could not run stash@1.0.0; using cached fixture.
2026-08-18  ⚠ Could not run stash@1.1.0; using cached fixture.
2026-08-31  ⚠ Could not run stash@1.1.1; using cached fixture.

The first is a build where the fixture already matched the latest release, so the output was correct and nothing looked wrong. The docs were right by coincidence. 1.1.x did not break anything — it made a pre-existing failure visible.

Why it fails is still unknown, and the code and workflow now say so rather than asserting a cause. stderr was discarded on every one of those runs (stdio: [..., "ignore"]). What is known: it fails in a consistent ~8 seconds, and npm view in the same script succeeds, so the registry is reachable.

The workflow doubles as the diagnostic. It is the one step that runs the CLI, it inherits stderr, and it fails loudly — so its first run either succeeds on Ubuntu, localising the fault to the Vercel builder, or prints the error the build logs never captured.

---

Update: version pinning

Tried making stash a devDependency of the docs app. It cannot be one: stash needs zod 3, fumadocs needs zod 4, and installing it hoists zod 3 to the root, at which point the frontmatter schema in source.config.ts stops inferring and the docs stop type-checking:

src/app/stack/[[...slug]]/page.tsx(72,7): error TS2322: Type {} is not assignable to type string | TemplateString | undefined.
src/lib/source.ts(62,43): error TS2345: Argument of type {} is not assignable to parameter of type string.

That is the blast-radius objection arriving on day one rather than on some future CLI release. A docs build should not be breakable by the CLI dependency tree.

The rest of the idea holds and is now in:

• The version is pinned in generate-cli-docs.ts, exactly as EQL_RELEASE_TAG pins EQL in generate-eql-docs.ts. What produced the fixture is recorded in the repo and moves by reviewable commit.
• Rendering asserts fixture version == pin, with no network. Bumping one without regenerating the other is the precise drift that shipped a version-old reference, and it now fails the build:

  Error: Cached manifest is stash v1.1.1 but the pin is v9.9.9.
  Run `bun run generate-docs:cli:refresh` and commit the result.
  

• --refresh installs the pinned CLI into a temp directory and runs it from there. No npx anywhere, so the failure that never worked on Vercel stops being load-bearing whether or not it is ever diagnosed.

The workflow bumps the pin and regenerates in one step, since the gate would make a pin-only PR red on arrival.

Verified: both render paths produce byte-identical pages, the gate fires on a simulated bump, the workflow pin-extract and pin-rewrite snippets run correctly against the real file, and types:check and biome check are clean with no new dependencies.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
public-docs	Ready	Preview	Sep 1, 2026 2:51am UTC

[Copilot]

Pull request overview

Refreshes the generated stash CLI reference to match stash v1.1.1 and changes the generation pipeline to be deterministic/offline-by-default by rendering from a committed manifest fixture, with a separate explicit refresh step.

Changes:

• Pin the CLI version in scripts/generate-cli-docs.ts, enforce “fixture version == pin”, and add a --refresh mode that installs/runs the pinned CLI to rewrite the fixture.
• Update the committed CLI manifest fixture and regenerate the CLI reference MDX pages to reflect stash v1.1.1 (including new/removed commands and heading de-duplication).
• Add a scheduled GitHub Actions workflow to detect new stash releases and open a PR that bumps the pin + refreshes the fixture/pages.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
scripts/generate-cli-docs.ts	Pins CLI version, renders from committed fixture by default, adds refresh mode to rewrite fixture, and improves group-page heading uniqueness.
scripts/fixtures/stash-manifest.json	Updates cached CLI manifest from 1.0.0 → 1.1.1 with the new command surface and updated help text.
package.json	Adds generate-docs:cli:refresh script for explicit fixture refresh + regeneration.
content/docs/reference/cli/*.mdx	Regenerates CLI reference pages from the updated manifest (version stamps, new/removed commands, named section headings).
.github/workflows/cli-manifest.yml	Adds scheduled workflow to detect new CLI releases and open/update a refresh PR.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[coderdan]

Fixed in 52f0e70. The comment now says what the variable actually is — read back off the manifest in main() rather than assumed from CLI_VERSION_PIN, since the manifest is what the pages are built from and readFixture() already asserts the two agree.

Gave RUNNER the same treatment while there: it is how a reader invokes the CLI, not how this script obtains it, and those two meanings were easy to conflate — which is how the misleading provenance string in your next comment got written.