Maintaining the CLI Reference
The CLI reference is generated from source, never
hand-written. This page is for contributors who touch
tools/generate-cli-docs.ts, tools/cli-reference-docs.ts, or land near the
generated output paths themselves.
What’s generated, and where
Section titled “What’s generated, and where”reference/cli.mdx— a small, stable index: an overview table plus one short entry per command (heading, one-line description, link to its detail page).reference/cli/<namespace>/<name>.mdx— one page per command, with its full description, worked example, guidance and complete options table. The path comes from the command’s pnpm identity split on:(wu:create→cli/wu/create.mdx,orchestrate:init-status→cli/orchestrate/init-status.mdx).
Every generated file carries an {/* AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY */} marker as its first content line. Never hand-edit a file that
carries that marker — the next pnpm docs:generate overwrites it, and
pnpm docs:validate (run in CI and by wu:prep) fails the build if a
generated file differs from what the generator would produce.
Regenerating
Section titled “Regenerating”Both commands cover the complete generated set: the index, every detail
page (added or removed as commands change), config.mdx, mcp.mdx, and the
CLI package README.md.
If you add, rename, or remove a public command
Section titled “If you add, rename, or remove a public command”Nothing extra to do by hand. The next docs:generate run:
- Adds a new detail page for a newly public command.
- Removes the generated detail page for a command that no longer exists (only if that page still carries the generated marker — a hand-authored file at that path is never touched, and the run refuses instead of silently colliding with it).
- Leaves every unrelated command’s page and the shared index byte-identical if your change only touched one command’s flags or description.
If two commands’ pnpm identities would map to the same detail-page path
(for example a case-only difference), the generator refuses and names both
commands rather than writing either page — rename one of them or extend the
slug mapping in tools/cli-reference-docs.ts.
Linking to a command from other docs
Section titled “Linking to a command from other docs”Prefer linking to the compact index, [wu:create](/reference/cli#wucreate),
for narrative context, or straight to the detail page,
[wu:create](/reference/cli/wu/create), when the full options table is the
point. Both existing forms keep working: index anchors are unchanged, and
this WU’s inventory found the handful of existing deep links elsewhere in
the docs tree already used the index form.
Architecture reference
Section titled “Architecture reference”Architecture decision records live in the repository, not on this public
site. The full design record — why the index/detail split exists, what
alternatives (including build-time-only generation) were considered and
rejected, and the exact output-set safety contract — is
docs/09-architecture-decisions/ADR-035-generated-cli-reference-ownership.md.
See also the repo-local runtime-view note at
docs/06-runtime-view/generated-cli-reference.md for the implementation
walkthrough (extraction into tools/cli-reference-docs.ts, the pure
reconciler, completion staging, and wu:clean-generated scope).