doc-reference-cli

Packet · {{ repo }} · reference/cli.md

Conditional packet. The orchestrator only seeds this packet when project_profile.entry_points for {{ repo }} includes a CLI. If the packet is present on disk, the orchestrator has already confirmed the precondition; do not re-check it as a reason to abort.

1. Objective

Produce {{ docs_root }}/reference/cli.md: one H2 per CLI subcommand (derived from route_map), each with a fenced usage block, a one-sentence description, a `path:LOC` citation, and a bulleted flag list where each flag cites `path:LOC`.

2. Scope

• Create: {{ docs_root }}/reference/cli.md
• Do not touch: any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one. In particular, do not write to {{ docs_root }}/reference/public-api.md — the public-api packet owns that file.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
Project profile (entry points)	{{ context_path }} § Repo profile	cached
CLI subcommand inventory	{{ prefetch_path }} § route_map or mcp__codehub__route_map({repo: "{{ repo }}"})	cached if digest present
Per-command signatures / flags	mcp__codehub__signature({symbol: <id>}) per handler	mid-run (only if cache miss)
Handler source for flag extraction	Read <file> at start_line..start_line+40	mid-run

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Confirm project_profile.entry_points includes a CLI and capture the CLI binary name (e.g., codehub).
2. Pull the route_map digest from .prefetch.md § route_map. If absent, call route_map({repo: "{{ repo }}"}) once and cache the digest in this packet's Work log. Each entry maps a subcommand to its handler path:start_line.
3. For each subcommand, Read the handler file at path:start_line-start_line+40 and extract (a) the usage line as exposed to the CLI library, (b) the full flag list with each flag's source line. Reuse signature({symbol: <handler-id>}) where the flag parser's signature captures the flag set.
4. If the CLI has more than 40 subcommands: group by top-level verb (analyze, query, verdict, …). Emit one H2 per verb group and nest subcommands as H3 within.
5. Draft one H2 per subcommand (or verb group). Format: ## <subcommand>, then a fenced usage block (``` no language), a one-sentence description, a `path:LOC` citation, then a Flags: bullet list with each flag cited `path:LOC`.
6. Order subcommands by the order they appear in route_map; within a verb group, order alphabetically.
7. Write {{ docs_root }}/reference/cli.md with H1 = {{ repo }} · CLI and a one-sentence intro naming the CLI binary before the first H2.