docs: generate the CLI flag reference from the argument declarations

[oekazuma]

gunshi adoption item 4 (per the approved utilization plan): the docs site's CLI flag reference is now generated from the same define() arg declarations that drive parsing, --help, and shell completion — closing the last hand-maintained home of the flag-drift class.

Shape (investigation-driven)

Only the pages that actually had enumerated per-flag documentation get generated tables: guides/(setup)/cli.md (root analyzer) and guides/(setup)/install.md (install), en+ja, injected between <!-- cli-reference:start/end --> markers ahead of the untouched hand-written per-flag prose sections. Surfaces documented only informally (ci, docs/explain mentions) were deliberately not given generated pages nobody had. Rendered as real Markdown tables directly from the ArgSchema consts rather than generate()'s terminal-formatted block — per @gunshi/docs' own man-page-generation guidance for non-terminal targets — confirmed rendering as proper <table>s in Blume's built HTML.

Mechanics (the established committed-generated pattern, third sibling to gen:docs/gen:rules-index)

• gen:cli-reference script imports the declarations through a new tree-shaken, unexported dist entry (385 bytes; check:publish all green — no public-surface change).
• The drift test imports the consts straight from src under vitest — stronger than the dist route (can't false-pass on a stale build) — and also pins en/ja block identity. Mutation-verified: tampering the committed table fails with a diff naming the regenerate command.
• AGENTS.md now documents the third generated-file pattern alongside its two siblings (edit-flag → regenerate → drift-gate).
• The ja pages embed the same English-description tables for now; the design-doc addendum records that they regenerate from ja resources once the i18n adoption (item 2) lands.

No changeset — docs-site content plus internal generator/test only; zero runtime or public-export change. Gates: full suite (2,711 tests), lint, e2e, smoke, check:publish, and the docs build (183 pages) all green.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added comprehensive generated reference tables for CLI and install options in English and Japanese.
  • Documented supported flags, aliases, accepted values, defaults, targets, and command behavior.
  • Added guidance for regenerating reference tables and preventing manual edits.

• Tests

  • Added checks to ensure documentation tables remain synchronized across languages and with current CLI options.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: be9a8924-c731-4118-b64e-ee4449917541

📥 Commits

Reviewing files that changed from the base of the PR and between 117931b and dc60f7d.

📒 Files selected for processing (12)

• AGENTS.md
• docs/src/content/docs/guides/(setup)/cli.md
• docs/src/content/docs/guides/(setup)/install.md
• docs/src/content/docs/ja/guides/(setup)/cli.md
• docs/src/content/docs/ja/guides/(setup)/install.md
• docs/superpowers/specs/2026-08-10-gunshi-cli-migration-design.md
• packages/cli/package.json
• packages/cli/scripts/cli-reference.mjs
• packages/cli/scripts/gen-cli-reference.mjs
• packages/cli/src/gunshi/registry.ts
• packages/cli/test/cli-reference.test.mjs
• packages/cli/tsup.config.ts

---

📝 Walkthrough

Walkthrough

The CLI argument schemas now generate Markdown reference tables for English and Japanese documentation. A build-only registry supplies the schemas, rendering helpers update marked blocks, and tests detect documentation drift and language mismatches.

Changes

CLI reference generation

Layer / File(s)	Summary
Schema build and generation entry packages/cli/src/gunshi/registry.ts, packages/cli/tsup.config.ts, packages/cli/package.json, docs/superpowers/specs/...	The CLI build exposes ROOT_ARGS and INSTALL_ARGS through a generator-only entry. A package script runs the build and reference generator.
Table rendering and documentation updater packages/cli/scripts/cli-reference.mjs, packages/cli/scripts/gen-cli-reference.mjs, docs/superpowers/specs/...	The generator renders visible argument schemas into Markdown tables, validates markers, updates four documentation pages, and formats descriptions and flag names.
Committed references and drift validation docs/src/content/docs/guides/(setup)/*, docs/src/content/docs/ja/guides/(setup)/*, packages/cli/test/cli-reference.test.mjs, AGENTS.md	English and Japanese pages contain generated CLI and install tables. Tests compare the tables with source schemas and enforce English/Japanese parity. Instructions document regeneration and prohibit manual edits inside generated blocks.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Registry as gunshi-registry
  participant Generator as gen-cli-reference.mjs
  participant Renderer as cli-reference.mjs
  participant Docs as CLI documentation
  Registry-->>Generator: ROOT_ARGS and INSTALL_ARGS
  Generator->>Renderer: Render argument schemas
  Renderer-->>Generator: Markdown reference tables
  Generator->>Docs: Replace generated blocks

Loading

Possibly related PRs

• oekazuma/svelte-vitals#452: Introduces the ROOT_ARGS and INSTALL_ARGS schemas used by this generator.
• oekazuma/svelte-vitals#454: Adds the Gunshi migration schemas consumed by the generated documentation.
• oekazuma/svelte-vitals#198: Adds the --refresh install flag documented by the generated tables.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: generating CLI flag reference documentation from argument declarations.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}