Skip to content

Package version-matched CLI documentation - #25

Merged
raghubetina merged 1 commit into
mainfrom
codex/docs-cli-usability
Aug 14, 2026
Merged

Package version-matched CLI documentation#25
raghubetina merged 1 commit into
mainfrom
codex/docs-cli-usability

Conversation

@raghubetina

Copy link
Copy Markdown
Contributor

Summary

  • package the public command, recovery, security, release, and history docs with the exact CLI version
  • verify repository routes separately from package-local routes and fragments
  • define latest as supported stable while a distinct next remains qualification-only
  • add lean entry-page budgets and complete public-topic reachability checks

Verification

  • npm audit: 0 vulnerabilities
  • npm run check: 154/154 tests plus typecheck, lint, format, package allowlist, and packed-package smoke
  • independent documentation review: PASS
  • git diff --check: PASS

No version, release, publication, or dist-tag state changes.

README links pointed into docs that npm omitted, so installed users
could not follow the documented command and recovery routes. Ship the
public documentation graph with each CLI version and verify
package-local links.

Define latest as the supported stable release while a distinct next
candidate remains limited to its named qualification.
@raghubetina
raghubetina merged commit e2118aa into main Aug 14, 2026
4 checks passed
@raghubetina

Copy link
Copy Markdown
Contributor Author

Post-merge review, hosted CI green (154/154 plus packed-package smoke, npm audit clean). The core decision is
packaging the command, recovery, security, release, and history docs inside the npm package so a given install
carries the documentation for exactly its own version, while repository routes are verified separately from
package-local ones. The check script split matters: package-local links must resolve inside the tarball
(offline, post-install), repository links against the working tree, and conflating the two is how packaged
docs end up pointing at files that never shipped.

The latest versus next definition (supported stable versus qualification-only) is consistent with the
skills repo's release policy reviewed earlier in this thread; the two repos now say the same thing, which
closes a drift risk between coordinated release surfaces.

Entry-page byte budgets with reachability checks continue the pattern from cli#24; nothing to flag beyond
noting the budgets will need the occasional deliberate bump as topics grow, which is the intended maintenance
cost of the guard.

@raghubetina

Copy link
Copy Markdown
Contributor Author

Run npm install -g some-cli@1.2.0, then read the project's docs site, and you may be reading instructions
for 2.0.0. Version-skewed documentation is one of the oldest developer-experience failures, and this PR fixes
it the blunt, effective way: ship the docs in the package.

When docs live in the npm tarball, node_modules/@firstdraft.com/cli/docs/ describes exactly the code beside
it, forever. The docs for 0.1.0 are frozen with 0.1.0. No archived-versions dropdown on a website, no "which
docs match my install" detective work; the filesystem answers it.

Shipping docs creates a subtle new failure mode, and the interesting part of this PR is the test split that
handles it. A link in a packaged doc must resolve inside the package after install, with no network and no
repository around it. A link in a repository doc may point anywhere in the repo. So the checks run in two
modes: package-local routes verified against the tarball's file list, repository routes against the working
tree. Without the split, a doc that links to ../test/fixtures/ passes CI in the repo and breaks for every
installed user.

The other definition this PR nails down: latest means supported stable, next means published for
qualification but not yet blessed. Dist-tags are just movable pointers into the same version registry, and
writing down what each pointer promises is the difference between a release process and a pile of published
tarballs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant