@opencodehub/cli 0.2.2 → 0.2.3

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-sequences.md

@@ -0,0 +1,103 @@
+---
+role: doc-diagrams-sequences
+model: sonnet
+output: "{{ docs_root }}/diagrams/behavioral/sequences.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · diagrams/behavioral/sequences.md
+
+> **Conditional packet.** The orchestrator only seeds this skeleton when `{{ context_path }} § Top processes` reports at least one process with ≥ 3 steps. If the condition is not met, the packet is skipped at seed time and no file is produced.
+
+## 1. Objective
+
+Produce `{{ docs_root }}/diagrams/behavioral/sequences.md`: up to three Mermaid `sequenceDiagram` blocks, one per top process, each showing the outbound call order across 4-8 participants.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/diagrams/behavioral/sequences.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.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Top processes (with step counts) | `{{ context_path }} § Top processes` | cached |
+| Process step order | `mcp__opencodehub__context({symbol: <process-name>})` per top 3 processes | mid-run |
+| Participant labels | `mcp__opencodehub__query({text: <actor-name>})` when a step's symbol is ambiguous | mid-run, on demand |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm which processes in `§ Top processes` have ≥ 3 steps — those are candidates.
+2. Pick the top 3 candidates by step count (ties broken by entry-point centrality from `.context.md`). If fewer than 3 qualify, emit only the qualifying count (1 or 2 diagrams).
+3. For each chosen process, call `mcp__opencodehub__context({symbol: <process-name>})` and extract the outbound call sequence in dispatch order. Cache the digest in this packet's Work log.
+4. Derive 4-8 participant lifelines per process by grouping step targets into community / module bands. Lifelines are listed in dispatch order at the top of each `sequenceDiagram`.
+5. Draft each `sequenceDiagram`: solid arrows (`->>`) for synchronous calls, dashed (`-->>`) for returns. Short labels (≤ 15 chars on edges, ≤ 20 chars on participant names).
+6. If any single diagram exceeds 20 nodes (participants + step-labeled messages), keep the top-20 and move overflow into a `## Legend (overflow)` table below that block.
+7. `Write {{ docs_root }}/diagrams/behavioral/sequences.md` with H1 = `{{ repo }} · Sequences`, one H2 per process, one fenced `sequenceDiagram` per H2.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Sequences`. One H2 per process — `## <process-name>` — with the `sequenceDiagram` immediately beneath.
+- No YAML frontmatter on the output file.
+- Up to three ` ```mermaid ` fences, each containing exactly one `sequenceDiagram`.
+- 4-8 participants per diagram; solid arrows for calls, dashed for returns.
+- Every participant and step target must correspond to a real symbol from `context` — no invented identifiers.
+- Node labels ≤ 20 chars; edge labels ≤ 15 chars.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Process list + step counts | `{{ context_path }} § Top processes` | precomputed; gates the conditional |
+| Outbound call order | `mcp__opencodehub__context` | dispatch sequence for lifelines |
+| Actor label disambiguation | `mcp__opencodehub__query` | when a step target has multiple matches |
+| Diagram idioms | `references/mermaid-patterns.md § Top process` | canonical `sequenceDiagram` shape + rules |
+
+## 7. Fallback paths
+
+- If no process has ≥ 3 steps at seed time, the orchestrator never seeds this packet — you should not be running. If you are and the cached list still shows none ≥ 3: write the gap to Work log and stop.
+- If a process's `context` call errors: skip that process entirely and note the skip in the Work log; proceed with the remaining candidates.
+- If fewer than 3 processes qualify: emit only the qualifying count. Do not pad with sub-3-step processes.
+- If participant count would exceed 8 for a process: group adjacent step targets into a single band (e.g., collapse `Parser` + `Lexer` into `Parsing`) and note the grouping in the Work log.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/diagrams/behavioral/sequences.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Sequences`.
+- [ ] Between 1 and 3 ` ```mermaid ` fences, each containing a `sequenceDiagram`.
+- [ ] Every diagram has 4-8 participants with labels ≤ 20 chars.
+- [ ] Every message edge has a label ≤ 15 chars.
+- [ ] One H2 per diagram; H2 text matches the process name from `.context.md § Top processes`.
+- [ ] No YAML frontmatter on the output.
+- [ ] Every participant name maps to a symbol returned by `context` (spot-check 3).
+
+## 9. Anti-goals
+
+- Do not re-call `sql` or `project_profile` — those are cached in `.prefetch.md` / `.context.md`.
+- Do not invent participants, step targets, or message labels — every identifier must come from a tool response.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than three `sequenceDiagram` blocks.
+- Do not emit a diagram for any process with fewer than 3 steps, even if it lets you reach 3 total.
+- Do not exceed 20 nodes in any single diagram; overflow goes into a per-diagram Legend table.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, why the process selection and lifeline grouping went the way they did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-cli.md

@@ -0,0 +1,110 @@
+---
+role: doc-reference-cli
+model: sonnet
+output: "{{ docs_root }}/reference/cli.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# 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__opencodehub__route_map({repo: "{{ repo }}"})` | cached if digest present |
+| Per-command signatures / flags | `mcp__opencodehub__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.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · CLI`. No decorative titles.
+- No YAML frontmatter on the output file.
+- A single one-sentence intro after the H1 names the CLI binary (e.g., ``The `codehub` CLI has the following subcommands.``).
+- Each subcommand is an H2 (`## <subcommand>`), followed by:
+  1. A fenced usage block with no language tag (e.g., ```` ``` ```` ... ```` ``` ````), showing the canonical invocation with optional flags in brackets.
+  2. A one-sentence description.
+  3. A `` `path:LOC` `` citation on its own line.
+  4. A `Flags:` label followed by a bullet list; each bullet is `` `--flag` — description. `path:LOC`. ``.
+- If > 40 subcommands: one H2 per verb group, one H3 per subcommand beneath. Otherwise flat H2s.
+- No Mermaid. No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| CLI presence signal | `{{ context_path }} § Repo profile` (`project_profile.entry_points`) | precondition for this packet |
+| Subcommand inventory | `mcp__opencodehub__route_map` (cached in `.prefetch.md`) | pre-parsed CLI tree; authoritative over handler grepping |
+| Handler signature / flag parser | `mcp__opencodehub__signature` | captures the parameter shape without paraphrase |
+| Flag source lines | `Read` at `path:start_line-start_line+40` | graph does not record per-flag line numbers |
+
+## 7. Fallback paths
+
+- If `project_profile.entry_points` does not include a CLI: the orchestrator should not have seeded this packet. Write the mismatch to the Work log, flip `status` to `BLOCKED`, and stop. Do not emit the output file.
+- If `route_map` returns `[]`: log the empty inventory in the Work log and do not emit the file. The orchestrator will prune the empty packet in Phase E.
+- If a subcommand handler has no extractable flags: emit the H2 with the usage block, description, and citation only; omit the `Flags:` bullet list rather than emit an empty one.
+- If a handler file cannot be `Read` (missing or binary): emit the H2 with the usage block and description, mark the citation `*handler unavailable*`, and log the skip.
+- If `route_map` is malformed (schema mismatch): run the `sql` fallback `SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND file_path LIKE '%cli%commands%'` and treat each hit as a candidate subcommand. Note the fallback in the Work log.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/reference/cli.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · CLI`.
+- [ ] The H1 is followed by a single one-sentence intro containing the CLI binary name in backticks.
+- [ ] At least one H2 subcommand (or verb group) is present; count matches `route_map` entries (or verb-group count when grouping).
+- [ ] Every H2 has exactly one fenced usage block immediately after the heading.
+- [ ] Every H2 has exactly one `` `path:LOC` `` citation for the handler.
+- [ ] Every `Flags:` bullet has a `` `path:LOC` `` citation (grep each bullet under a `Flags:` label for a backtick span).
+- [ ] When subcommand count > 40: the output uses verb-group H2s with nested H3 subcommands. Otherwise: flat H2 subcommands.
+- [ ] No YAML frontmatter on the output.
+- [ ] No Mermaid fences in the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is in `.prefetch.md` — read the cached summary. If the cached slice is truncated, call with a narrower filter, not a blanket re-fetch.
+- Do not invent subcommand names, flag names, or `path:LOC` citations — every identifier must come from `route_map`, `signature`, or a verified `Read` of the handler source.
+- Do not paraphrase usage blocks or flag declarations. Quote them verbatim from source.
+- Do not write to `{{ docs_root }}/reference/public-api.md`; that file is owned by the public-api packet.
+- Do not emit the output file when `route_map` is empty or when the CLI precondition fails — flip `status` to `BLOCKED` and stop.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis. Do not use filler adverbs.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, whether verb grouping was applied, and any route_map gaps encountered }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md

@@ -0,0 +1,100 @@
+---
+role: doc-reference-mcp-tools
+model: sonnet
+output: "{{ docs_root }}/reference/mcp-tools.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · reference/mcp-tools.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/reference/mcp-tools.md`: the authoritative reference for every MCP tool `{{ repo }}` exposes, one H2 per tool, each with a verbatim signature, input/output shapes, a one-sentence purpose, and a `path:LOC` citation to the handler file.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/reference/mcp-tools.md`
+- Do not touch: `{{ docs_root }}/reference/public-api.md`, `{{ docs_root }}/reference/cli.md`, or any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+- Conditional file — this packet is only seeded when `{{ repo }}` contains an MCP server package (the orchestrator verified `project_profile.stacks` includes `"MCP"` or `tool_map` is non-empty before spawning).
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| MCP tool inventory | `{{ prefetch_path }} § tool_map` | cached |
+| Tool handler nodes | `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND file_path LIKE '%mcp%'"})` | mid-run, only if `tool_map` slice is truncated |
+| Verbatim signatures | `Read <file_path>:<start_line>` (signatures are not stored in the graph) | mid-run |
+| Usage count per tool | `mcp__opencodehub__context({symbol: <tool-handler>})` | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the `tool_map` digest is present and non-empty; if empty, follow Fallback paths.
+2. Build the tool roster from `{{ prefetch_path }} § tool_map`: tool name, handler `file_path:start_line`, input/output schema digest.
+3. For each tool in the roster: `Read` the handler file at `start_line..start_line+30` and extract the exact signature (function or registration block). Do not paraphrase.
+4. For each tool: pull a one-sentence purpose from the registration description (the MCP `describe` string); if missing, infer from the handler docstring and mark the inference in the Work log.
+5. Draft `reference/mcp-tools.md`: H1 = `{{ repo }} · MCP tools`, one H2 per tool in alphabetical order. Each H2 contains the verbatim signature fenced as code, a one-sentence purpose, an input/output shape summary, and a `path:LOC` citation.
+6. `Write {{ docs_root }}/reference/mcp-tools.md`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · MCP tools`. No decorative titles.
+- No YAML frontmatter on the output file.
+- One H2 per tool. Tool order = alphabetical by tool name.
+- Signatures are fenced code blocks, quoted verbatim from the handler file — never paraphrased, never retyped from memory.
+- Every H2 ends with a backtick `path:LOC` citation pointing at the handler `file_path:start_line`.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Full tool inventory | `{{ prefetch_path }} § tool_map` | precomputed; do not re-call `tool_map` |
+| Verbatim signature text | `Read` at `file_path:start_line` | graph stores names/locs, not signature text |
+| Handler usage count | `mcp__opencodehub__context` | inbound count; signals which tools are load-bearing |
+| Tools not in `tool_map` | `mcp__opencodehub__sql` filtered to MCP files | fallback only when `tool_map` is stale |
+
+## 7. Fallback paths
+
+- If `{{ prefetch_path }} § tool_map` is empty but `project_profile.stacks` includes `"MCP"`: call `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND (file_path LIKE '%mcp%' OR file_path LIKE '%tools%') ORDER BY file_path"})`, filter to registered handlers by grepping for tool-registration decorators, and cite the fallback in the Work log.
+- If `tool_map` returns `[]` and `project_profile.stacks` does not contain `"MCP"`: do not emit an empty file. Write the gap to the Work log, mark `status: COMPLETE` with a note, and skip the Write step — the orchestrator will prune this packet from the README.
+- If a handler `Read` fails (file moved since the last `codehub analyze`): flag the row with `*graph stale — verify with codehub analyze*` and cite the graph-recorded path.
+- If a tool registration has no description string: infer from the handler's top-level docstring; mark the H2 body `*description inferred from docstring*` in-line.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/reference/mcp-tools.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · MCP tools`.
+- [ ] Every tool returned by `tool_map` has exactly one H2 in the output.
+- [ ] No H2 exists for a tool name not in `tool_map` (or the sql fallback roster).
+- [ ] Every H2 contains a fenced code block with a verbatim signature.
+- [ ] Every H2 ends with a backtick `path:LOC` citation.
+- [ ] No YAML frontmatter on the output.
+- [ ] Tool H2s are in alphabetical order (spot-check first and last).
+
+## 9. Anti-goals
+
+- Do not re-call `tool_map` — its digest is cached in `.prefetch.md`.
+- Do not invent tool names, input fields, or output fields — every identifier must come from `tool_map` or a `Read` of the handler file.
+- Do not paraphrase signatures. Quote the source or use the `Read` fallback.
+- Do not emit a `reference/mcp-tools.md` with zero H2s; follow the Fallback path that skips the file instead.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, and any tools that required a fallback }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-public-api.md

@@ -0,0 +1,111 @@
+---
+role: doc-reference-public-api
+model: sonnet
+output: "{{ docs_root }}/reference/public-api.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · reference/public-api.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/reference/public-api.md`: one H3 per exported symbol for the top 30 public exports of `{{ repo }}`, each with a fenced code block that quotes the symbol's signature verbatim, a one-sentence description, and a `` `path:LOC` `` citation. When `{{ repo }}` is not a CLI, append an `## HTTP` H2 rendered from `route_map` at the bottom of the file.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/reference/public-api.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/cli.md` — the CLI 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 | `{{ context_path }} § Repo profile` | cached |
+| Exported symbols (public surface) | `{{ prefetch_path }} § exports` or `mcp__opencodehub__sql({query: "SELECT name, kind, file_path, start_line FROM nodes WHERE kind IN ('Function','Class','Method') AND name NOT LIKE '\\_%' ORDER BY file_path LIMIT 500"})` | cached if digest present |
+| Per-symbol signatures | `mcp__opencodehub__signature({symbol: <id>})` | mid-run (only if cache miss) |
+| Per-symbol usage count | `mcp__opencodehub__context({symbol: <id>})` | mid-run (only if cache miss) |
+| HTTP route inventory | `{{ prefetch_path }} § route_map` or `mcp__opencodehub__route_map({repo: "{{ repo }}"})` | cached if digest present |
+| Source fallback for missing signatures | `Read <file>` at `start_line..start_line+20` | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `{{ repo }}` profile; check `project_profile.entry_points` for the CLI flag.
+2. Pull the exported-symbol list from `.prefetch.md § exports`. If absent, run the `sql` query in the input spec and cache the digest in this packet's Work log.
+3. Filter to symbols whose file path is a barrel (`packages/*/src/index.ts`, `src/index.ts`, `mod.rs`, `__init__.py`, or equivalent). Keep that subset as the real exports.
+4. For the top 30 exports (ordered by inbound relation count if cached, else by file path): fetch `signature({symbol: <id>})` and `context({symbol: <id>})`. Record signature, inbound count, and `path:start_line` in the Work log. Reuse cached digests wherever `.prefetch.md` already recorded them.
+5. Determine HTTP rendering: if `project_profile.entry_points` includes a CLI, skip the HTTP section — the CLI packet owns route rendering. Otherwise, read the `route_map` digest (or call `route_map({repo: "{{ repo }}"})` once) and prepare an `## HTTP` H2.
+6. Draft one H3 per export. Format: `### <symbol-name>`, then a fenced code block quoting the signature verbatim, then a one-sentence description, then the `` `path:LOC` `` citation on its own line.
+7. If rendering HTTP, append `## HTTP` as the final H2, with one H3 per route (`### METHOD /path`), a one-sentence description, and a `` `path:LOC` `` citation. Order routes by `path`, then `method`.
+8. `Write {{ docs_root }}/reference/public-api.md` with H1 = `{{ repo }} · Public API`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Public API`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Each exported symbol is an H3 (`### <symbol-name>`), followed by:
+  1. One fenced code block quoting the signature verbatim from `signature` (or `Read` fallback). Never paraphrase.
+  2. A one-sentence description.
+  3. A `` `path:LOC` `` citation on its own line.
+- The fenced code block's language tag matches the repo language (`ts`, `py`, `rs`, `go`, etc.) based on file extension.
+- HTTP section (non-CLI repos only): one H2 `## HTTP`, one H3 per route `### <METHOD> <path>`, one-sentence description, `` `path:LOC` `` citation.
+- No Mermaid. No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Public-ish symbol surface | `sql` (cached in `.prefetch.md`) | Filter to non-underscore names grouped by barrel |
+| Verbatim signatures | `mcp__opencodehub__signature` | authoritative signature text; never paraphrase |
+| Usage count / publicness signal | `mcp__opencodehub__context` | inbound count orders the top-30 shortlist |
+| HTTP route inventory | `mcp__opencodehub__route_map` | pre-parsed routes; avoids handler-file grepping |
+| Signature fallback | `Read` at `path:start_line-start_line+20` | paste declaration verbatim when `signature` is empty |
+
+## 7. Fallback paths
+
+- If `signature` returns nothing for a symbol: `Read` the file at `path:start_line-start_line+20`, paste the declaration verbatim into the fenced code block, and note the fallback in the Work log.
+- If fewer than 30 exports pass the barrel filter: emit whatever is present; do not pad with private helpers. Note the shortfall in the Work log.
+- If `route_map` returns `[]` and `{{ repo }}` is not a CLI: skip the `## HTTP` section entirely rather than emit an empty one.
+- If `{{ repo }}` is a CLI per `project_profile.entry_points`: do not emit the `## HTTP` section here — the `doc-reference-cli` packet renders `reference/cli.md` from `route_map` instead. Record the coordination choice in the Work log.
+- If a barrel file is absent (language without explicit barrels): fall back to symbols whose `start_line == 1` AND whose file has ≥ 3 inbound import edges. Note the heuristic in the Work log.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/reference/public-api.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Public API`.
+- [ ] At least 5 H3 entries are present (count `^### ` matches, excluding HTTP routes).
+- [ ] Every H3 symbol block has one fenced code block immediately after the heading.
+- [ ] Every H3 block has exactly one `` `path:LOC` `` citation.
+- [ ] Every fenced signature block's content appears verbatim in either `signature`'s output or the cited source span (spot-check 3 by re-reading).
+- [ ] If `project_profile.entry_points` includes CLI: no `## HTTP` section exists in the output.
+- [ ] If `project_profile.entry_points` excludes CLI and `route_map` returned at least one route: an `## HTTP` section exists with one H3 per route.
+- [ ] No YAML frontmatter on the output.
+- [ ] No Mermaid fences in the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is in `.prefetch.md` — read the cached summary. If the cached slice is truncated, call with a narrower filter, not a blanket re-fetch.
+- Do not invent symbol names, signatures, route paths, or citations — every identifier must come from a tool response or a `Read` of the source file.
+- Do not paraphrase signatures. Quote them verbatim.
+- Do not write to `{{ docs_root }}/reference/cli.md`; that file is owned by the CLI packet.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis. Do not use filler adverbs.
+- Do not emit more than 30 symbol H3 entries — overflow belongs to a future paginated packet.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, how the export shortlist was filtered, whether HTTP was rendered here or deferred to the CLI packet }}

package/dist/plugin-assets/skills/codehub-document/templates/orchestrator-prompt.md

@@ -0,0 +1,110 @@
+# Orchestrator spawn prompt
+
+Canonical prompt the `codehub-document` skill uses when spawning a `general-purpose` subagent for a seeded packet. One source of truth so every subagent gets the same framing.
+
+Adapted from `erpaval/references/orchestrator.md § Per-task Agent prompt template`. Paste verbatim into the `Agent` tool's `prompt` parameter, substituting `{{ packet_path }}` with the absolute path of the packet on disk.
+
+---
+
+```text
+You are a codehub-document subagent. Your context packet is at the path
+below — read it first, then work through its sections in order, editing
+the packet in place as you go. The packet is both your role prompt and
+your work log.
+
+<packet>
+{{ packet_path }}
+</packet>
+
+<preamble>
+Before starting section 1, read the packet in full, then read every file
+listed under Input specification that is marked `cached`. Subagents have
+zero context about the codebase — everything you need is in the packet,
+in `.context.md`, in `.prefetch.md`, or in tools the packet explicitly
+authorizes you to call.
+</preamble>
+
+<write_protocol>
+Your task packet file is the single source of truth for what you've
+done, decided, and verified. Edit it after every meaningful step, before
+starting the next one. Partial progress written to disk survives
+timeouts, SendMessage interrupts, and orchestrator context pressure;
+state held in working memory does not.
+
+The rhythm is: one action → edit the packet with the outcome → next
+action. One exchange at a time.
+
+Work through your sections in numbered order. For each section:
+
+1. Do one unit of work — read a precompute file, call an authorized
+   MCP tool, draft a Markdown block, Write an output file.
+2. Edit the packet under that section with what happened — the exact
+   sources read, the tool output digest, the decision made, any
+   surprises.
+3. If the section needs more depth, do another unit and edit again.
+4. Move to the next section only after the current one has real
+   content.
+
+If a check fails (empty tool result, schema mismatch, missing file):
+write the failure to the packet's Fallback paths or Work log, then
+execute the documented fallback, then edit again with the outcome.
+Keep the file ahead of your working memory at all times.
+
+**Cite every factual claim with a backtick `path:LOC` reference.**
+"Top community `analysis` has 42 files (`packages/analysis/src/index.ts:1`)."
+beats "Top community has about 40 files."
+
+When every section has real content and every Success criterion is
+checked off, change `status: IN_PROGRESS` in the packet frontmatter
+to `status: COMPLETE`.
+</write_protocol>
+
+<success_criteria>
+- The output file(s) listed in the packet frontmatter's `output:` field
+  exist on disk, with H1 = identifier and no YAML frontmatter.
+- Every factual claim in the output has a backtick citation
+  (`path:LOC` or `repo:path:LOC` in group mode).
+- Every Success criterion checkbox in the packet is ticked.
+- The Work log / Validation / Summary sections at the end of the packet
+  have real content.
+- The `status:` line in the packet frontmatter is flipped from
+  IN_PROGRESS to COMPLETE.
+</success_criteria>
+
+<anti_goals>
+- Do not re-call any MCP tool whose digest appears in `.prefetch.md` —
+  read the cached summary instead. If the cached slice is truncated and
+  you need a wider view, call the tool with a narrower filter, not a
+  blanket re-fetch.
+- Do not modify files outside the packet's Scope section.
+- Do not write YAML frontmatter on the output files.
+- Do not invent symbol names, edges, tool names, routes, or community
+  names — every such identifier must come from a tool response or a
+  `Read` of the source file.
+- Do not emit emojis. Do not use filler adverbs.
+- If a precondition is missing (tool returns empty, schema doesn't
+  match, a required source file is absent), write the gap to the
+  packet's Work log and stop — do not improvise output from partial
+  data.
+</anti_goals>
+```
+
+---
+
+## Usage at the orchestrator
+
+```python
+Agent(
+    description="doc: architecture/system-overview",
+    subagent_type="general-purpose",
+    model="sonnet",
+    run_in_background=True,
+    name="doc-architecture-system-overview",
+    prompt=SPAWN_PROMPT.replace("{{ packet_path }}", absolute_packet_path),
+)
+```
+
+- `description` — 3-5 words; the UI surface, plus what shows in agent notifications.
+- `name` — file-role; enables `SendMessage` continuation if the orchestrator needs to nudge a stuck subagent.
+- `model` — from the packet frontmatter `model:` field; default sonnet, bump to opus for synthesis-heavy roles (cross-repo, risk-hotspots drill-down) if the packet requests it.
+- `run_in_background` — always `true` for Phase 1 fan-out; the orchestrator monitors via `wc -l` on packet files, not by polling agent output.

package/dist/plugin-assets/skills/codehub-onboarding/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: codehub-onboarding
+description: "Use when the user asks for an ONBOARDING, getting-started, or new-engineer guide for the current repo or group. Examples: \"write ONBOARDING.md\", \"generate an onboarding doc for new hires\", \"what should a new engineer read first\". Produces a ranked reading order from `project_profile` + top processes + entry points + owners + centrality. DO NOT use for full architecture books (use `codehub-document`) or PR summaries (use `codehub-pr-description`)."
+allowed-tools: "Read, Write, Glob, mcp__opencodehub__project_profile, mcp__opencodehub__query, mcp__opencodehub__context, mcp__opencodehub__route_map, mcp__opencodehub__tool_map, mcp__opencodehub__owners, mcp__opencodehub__sql, mcp__opencodehub__list_repos, Task"
+argument-hint: "[output-path] [--committed]"
+color: green
+model: sonnet
+---
+
+# codehub-onboarding
+
+Produces a single ONBOARDING.md with a ranked reading order drawn from graph centrality. The wedge is the ranked reading list — a generic README scaffold cannot produce this.
+
+## Preconditions
+
+1. `mcp__opencodehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo <name> is not indexed.` and stop.
+2. `codehub status` is fresh. If stale, emit `Run 'codehub analyze' first — index is stale` and stop.
+
+## Arguments
+
+- `[output-path]` — where to write. Defaults:
+  - without `--committed`: `.codehub/ONBOARDING.md` (gitignored)
+  - with `--committed`: `docs/ONBOARDING.md` (gitignored default flipped)
+- `--committed` — write to a committed path instead of `.codehub/`.
+
+## Process
+
+1. Run the preconditions.
+2. `mcp__opencodehub__project_profile({repo})` — languages, stacks, entry points, 2-sentence summary.
+3. `mcp__opencodehub__route_map({repo})` — HTTP surface (if present).
+4. `mcp__opencodehub__tool_map({repo})` — MCP/CLI surface (if present).
+5. `mcp__opencodehub__sql({query: "SELECT name, file_path, in_degree + out_degree AS centrality FROM nodes WHERE kind IN ('File','Module','Class') ORDER BY centrality DESC LIMIT 15"})` — top-centrality nodes, the "read these first" candidates.
+6. For the top 8 of those: `mcp__opencodehub__context({symbol: <id>})` to pull a one-line summary + owners.
+7. `mcp__opencodehub__owners({path})` on the top-3 folders by file count — gives the "ask these humans" list.
+8. Dispatch a single `Task` with the `doc-onboarding` specialty role (inline in this skill — see `references/onboarding-template.md`).
+9. Assemble the output using the template below.
+10. `Write` to the resolved output path.
+
+## Output template
+
+```markdown
+# <repo> · Onboarding
+
+*Generated <ISO-8601>. Refresh via `/codehub-onboarding`.*
+
+## TL;DR
+
+2 sentences: what this repo does + the single most important mental model to hold.
+
+## Stack
+
+| Layer | Tech | Source |
+|---|---|---|
+| Runtime | Node 22 | `package.json:7` |
+| Storage | DuckDB | `packages/storage/src/index.ts:12` |
+| ... | ... | ... |
+
+## Read these 10 files first (in order)
+
+1. `packages/cli/src/bin.ts` — CLI entry point. `(45 LOC)`
+2. `packages/mcp/src/server.ts` — MCP server bootstrap. `(320 LOC)`
+3. `packages/ingestion/src/pipeline.ts` — the phase DAG. `(180 LOC)`
+... (ranked by centrality; each with a one-sentence reason)
+
+## Walk one process end-to-end
+
+Pick the highest-step-count process and walk it:
+
+1. **Enter** at `packages/cli/src/commands/analyze.ts:14`.
+2. **Dispatches** to `packages/ingestion/src/phases/parse.ts:22`.
+3. **Writes** via `packages/storage/src/write.ts:88`.
+4. **Exits** at `packages/cli/src/commands/analyze.ts:102`.
+
+## Ask these humans
+
+| Area | Owner | Share |
+|---|---|---|
+| `packages/mcp/` | alice@ | 72% |
+| `packages/ingestion/` | bob@ | 45% |
+| `packages/storage/` | charlie@ | 68% |
+
+## Next steps
+
+- Run `codehub analyze .` in your checkout to build the local graph.
+- Open the Claude Code plugin and try `/probe "how does X work"`.
+- Read [architecture/system-overview.md](./docs/architecture/system-overview.md) if `codehub-document` has already produced it.
+```
+
+## Document format rules
+
+- H1 = "{{repo}} · Onboarding".
+- Top reading list is exactly 10 items, ranked.
+- Every file in the reading list has a one-sentence reason + LOC count in backticks.
+- No YAML frontmatter on the output.
+- No emojis.
+
+## Fallback paths
+
+- If `sql` over centrality returns fewer than 10 rows: pad with highest-fan-out `Function` nodes and note `*graph-small fallback*` in the list header.
+- If no `Process` nodes exist (tiny repo or graph out of sync): skip the "Walk one process" section entirely; emit "This repo's graph does not yet encode processes. Re-run `codehub analyze` if unexpected." as a one-line note.
+- If `owners` returns `[]` for all folders: replace the Ask-these-humans table with a `git shortlog -sn --since=90.days` pointer.
+
+## Quality checklist
+
+- [ ] Preconditions enforced.
+- [ ] TL;DR is ≤ 2 sentences.
+- [ ] Stack table has ≥ 3 rows.
+- [ ] Reading list has exactly 10 items, each with a backtick citation.
+- [ ] One process walked end-to-end (or the fallback note).
+- [ ] Ask-these-humans table has ≥ 2 rows.
+- [ ] Next-steps section exists with ≥ 3 concrete actions.