@opencodehub/cli 0.2.1 → 0.2.3

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-state-machines.md

@@ -0,0 +1,101 @@
+---
+role: doc-behavior-state-machines
+model: sonnet
+output: "{{ docs_root }}/behavior/state-machines.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · behavior/state-machines.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/behavior/state-machines.md`: one H2 per state machine in `{{ repo }}`, each containing exactly one Mermaid `stateDiagram-v2` block that reflects the states and transitions declared in source, followed by a `path:LOC` citation to the definition site.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/behavior/state-machines.md`
+- Do not touch: `{{ docs_root }}/behavior/processes.md`, 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 `sql(WHERE kind='StateMachine')` returns ≥ 2 rows. The state-machine count is carried in `{{ context_path }} § State machines`; the orchestrator verified the count before spawning.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| State-machine inventory | `{{ context_path }} § State machines` (count + names + paths) | cached |
+| State-machine nodes (detail) | `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})` | mid-run, only if `.context.md` slice is truncated |
+| States + transitions per machine | `mcp__opencodehub__context({symbol: <machine-name>})` | mid-run |
+| Verbatim state/transition text | `Read <file_path>:<start_line>` | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `.context.md § State machines` lists ≥ 2 machines. If the slice is truncated, call the `sql` fallback in Section 3.
+2. For each state machine: call `mcp__opencodehub__context({symbol: <machine-name>})` to pull states, entry state, transitions, and terminal states.
+3. For each machine: `Read` the definition file at `start_line..start_line+60` to verify state names and transition labels before drawing. Do not invent transitions.
+4. Draft `state-machines.md` with H1 = `{{ repo }} · State machines`. One H2 per machine, in alphabetical order by machine name. Under each H2: exactly one fenced Mermaid `stateDiagram-v2` block, then a single-line `Defined at: <backtick path:LOC>` citation.
+5. Transitions use the source-level event name as the Mermaid edge label (e.g., `start()`, `complete()`). Do not paraphrase event names.
+6. `Write {{ docs_root }}/behavior/state-machines.md`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · State machines`. No decorative titles.
+- No YAML frontmatter on the output file.
+- One H2 per state machine. H2s in alphabetical order.
+- Each H2 contains exactly one Mermaid fence with `stateDiagram-v2`. Not `stateDiagram`, not `flowchart`.
+- Each H2 ends with `Defined at: <backtick path:LOC>` on its own line.
+- Mermaid node names match source state identifiers verbatim; transition labels match source event names verbatim.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| State-machine roster | `{{ context_path }} § State machines` | precomputed; do not re-call `sql` |
+| States + transitions | `mcp__opencodehub__context` | outbound edges encode transitions |
+| Verbatim state / event names | `Read` at `file_path:start_line` | graph stores the structure, not the literal text |
+| Disambiguate machine names | `mcp__opencodehub__query` | only when two machines share a name |
+
+## 7. Fallback paths
+
+- If `.context.md § State machines` is truncated or absent: call `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})`. Cite the fallback in the Work log.
+- If the sql roster returns < 2 machines (the conditional precondition was wrong): write the gap to the Work log, stop, and do not emit an empty or 1-machine file — the orchestrator will prune this packet from the README.
+- If `context` returns no transitions for a machine: `Read` the definition file at `start_line..start_line+60` and parse the states/transitions manually; mark the machine H2 with `*transitions derived by direct read*` in the Work log.
+- If a machine has no terminal state in source: draw the diagram without a `--> [*]` edge and note the absence in the Work log (do not invent a terminal state).
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/behavior/state-machines.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · State machines`.
+- [ ] At least 2 H2 entries exist (matches the conditional precondition).
+- [ ] Every H2 contains exactly one `stateDiagram-v2` Mermaid fence.
+- [ ] No H2 contains a second Mermaid block or a non-Mermaid diagram.
+- [ ] Every H2 ends with a `Defined at: <backtick path:LOC>` line.
+- [ ] Every state name and transition label in the Mermaid blocks appears in the source file at the cited path (spot-check 1 machine).
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call `sql` over `StateMachine` nodes — the count and names are cached in `.context.md`.
+- Do not invent state names or transition labels — every identifier must come from `context` output or a `Read` of the definition file.
+- Do not emit more than one Mermaid block per H2.
+- Do not use `stateDiagram` (v1); use `stateDiagram-v2` only.
+- 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, which machines were drawn, and any that required a direct-read fallback }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md

@@ -0,0 +1,104 @@
+---
+role: doc-cross-repo-contracts-matrix
+model: sonnet
+output: "{{ group_docs_root }}/cross-repo/contracts-matrix.md"
+depends_on:
+  - "{{ group_context_path }}"
+  - "{{ group_prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ group }} · cross-repo/contracts-matrix.md
+
+> **Group mode only.** This packet runs when the skill orchestrator is invoked with `--group {{ group }}`. In single-repo mode it is never seeded.
+
+## 1. Objective
+
+Produce `{{ group_docs_root }}/cross-repo/contracts-matrix.md`: the N×N producer/consumer matrix for the `{{ group }}` group (rows = producers, columns = consumers, cells = contract counts), followed by a `## Notable contracts` H2 listing the top 10 contracts with both-ends `repo:path:LOC` citations.
+
+## 2. Scope
+
+- Create: `{{ group_docs_root }}/cross-repo/contracts-matrix.md`
+- Do not touch: any other file under `{{ group_docs_root }}/`, any file under a member repo (including `{{ member_repos }}/`), `{{ group_context_path }}`, `{{ group_prefetch_path }}`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Group shared context | `Read {{ group_context_path }}` | always first |
+| Group prefetch ledger | `Read {{ group_prefetch_path }}` | always first |
+| Member list + freshness | `{{ group_context_path }} § Members` / `{{ group_prefetch_path }} § group_list,group_status` | cached |
+| Group contracts (the spine) | `{{ group_prefetch_path }} § group_contracts` | cached |
+| Per-member route inventory | `{{ group_prefetch_path }} § route_map(<repo>)` per `{{ member_repos }}` | cached |
+| Concept → symbol disambiguation | `mcp__opencodehub__group_query({group: "{{ group }}", text: <concept>})` | mid-run, on demand |
+
+## 4. Process
+
+1. `Read {{ group_context_path }}` and `Read {{ group_prefetch_path }}`. Confirm the member list and re-verify every member is tagged `fresh` in the cached `group_status` digest. Abort to Work log if any member is stale.
+2. Pull the contract list from `{{ group_prefetch_path }} § group_contracts`. Each row has `{producer_repo, consumer_repo, path, method, shape}`. This is the spine of the entire artifact.
+3. Build the producer/consumer matrix: rows = producer repos (in `group_list` order), columns = consumer repos (same order). Each cell = the contract count for that `(producer, consumer)` pair. Diagonal cells show `—`. Render as a Markdown table.
+4. Select the top 10 contracts by consumer count (ties broken by producer path lexicographically). For each, resolve both ends to real files via the cached `route_map` digests — producer file comes from `route_map(<producer>)`, consumer file from the `group_contracts` row's `consumer_repo` + `path`. Cite both with `repo:path:LOC`.
+5. Draft the `## Notable contracts` H2: a bullet list of the 10 entries in the form `` `<producer-repo>:<producer-path>:<LOC>` ← consumed by `<consumer-repo>:<consumer-path>:<LOC>` (method + shape summary) ``.
+6. If the matrix has zero non-diagonal contracts, still emit the full N×N matrix (all `0` / `—` cells), add a `> No inter-repo contracts detected — the group graph does not currently encode cross-repo edges` banner immediately beneath the H1, and replace `## Notable contracts` with `## Notable contracts\n\n_None detected._`.
+7. `Write {{ group_docs_root }}/cross-repo/contracts-matrix.md` with H1 = `{{ group }} · Contracts matrix`.
+
+## 5. Document format rules
+
+- **Every citation MUST use the group-qualified `repo:path:LOC` form — on both ends of every Notable contracts bullet.** Phase E's regex depends on this — bare `path:LOC` will not be rewritten.
+- H1 = `{{ group }} · Contracts matrix`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Matrix is a full Markdown table, N×N, even when most cells are zero. Column and row order match `group_list`. Diagonal = `—`; empty cells = `0`.
+- `## Notable contracts` section has at most 10 bullets, each with two `repo:path:LOC` citations (producer end and consumer end) plus a short `(method + shape)` summary.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Member list + freshness | `{{ group_prefetch_path }} § group_list,group_status` | precondition gate; precomputed |
+| Contract inventory | `{{ group_prefetch_path }} § group_contracts` | authoritative spine; do not re-call |
+| Producer file resolution | `{{ group_prefetch_path }} § route_map(<repo>)` | maps contract `path` → handler `file:LOC` |
+| Concept disambiguation | `mcp__opencodehub__group_query` | when a contract's target symbol has multiple matches across the group |
+
+## 7. Fallback paths
+
+- If `group_contracts` returned zero contracts: follow the all-zero path in step 6. Do not omit the matrix.
+- If a member repo is stale despite Phase 0 checks: abort — write `{{ group_docs_root }}/cross-repo/_stale.md` instead, explaining which repo blocked generation, and stop.
+- If a `route_map` digest is missing for a producer: fall back to the raw `path` string from `group_contracts` and cite `<producer-repo>:<path>:1`. Record the fallback in the Work log.
+- If `group_query` returns empty for a concept while disambiguating: try `"http route"`, `"mcp tool"`, `"message consumer"` in order before giving up and marking the bullet `*consumer unresolved*`.
+
+## 8. Success criteria
+
+- [ ] `{{ group_docs_root }}/cross-repo/contracts-matrix.md` exists on disk.
+- [ ] H1 line reads `# {{ group }} · Contracts matrix`.
+- [ ] Matrix is a full N×N Markdown table where N = number of members; diagonals are `—`; cells show integer contract counts.
+- [ ] `## Notable contracts` H2 is present; bullet count = `min(10, total non-diagonal contract count)`.
+- [ ] Every Notable contracts bullet has two `repo:path:LOC` citations (producer + consumer).
+- [ ] Every citation in the file uses the `repo:path:LOC` form — no bare `path:LOC` (grep the output to verify).
+- [ ] If zero contracts: the empty-state banner and `_None detected._` sub-section are present.
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is already in `{{ group_prefetch_path }}` — read the cached summary.
+- Do not emit a citation in the bare `path:LOC` form; every citation MUST be `repo:path:LOC`.
+- Do not invent contracts, producer/consumer pairs, file paths, or line numbers — every entry must come from a cached tool response.
+- Do not write YAML frontmatter on the output file.
+- Do not omit the matrix when contract count is zero — emit an empty N×N table with the banner.
+- Do not exceed 10 bullets under `## Notable contracts`.
+- Do not collapse the matrix to producer-only or consumer-only — it must be N×N.
+- 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 top-10 contract selection went the way it did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md

@@ -0,0 +1,111 @@
+---
+role: doc-cross-repo-dependency-flow
+model: sonnet
+output: "{{ group_docs_root }}/cross-repo/dependency-flow.md"
+depends_on:
+  - "{{ group_context_path }}"
+  - "{{ group_prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ group }} · cross-repo/dependency-flow.md
+
+> **Group mode only.** This packet runs when the skill orchestrator is invoked with `--group {{ group }}`. In single-repo mode it is never seeded.
+
+## 1. Objective
+
+Produce `{{ group_docs_root }}/cross-repo/dependency-flow.md`: a single Mermaid `flowchart TB` showing inter-repo data flow across the `{{ group }}` group — nodes are repos (plus events/streams as needed), edges are contract groups labeled by HTTP verb + path or event type.
+
+## 2. Scope
+
+- Create: `{{ group_docs_root }}/cross-repo/dependency-flow.md`
+- Do not touch: any other file under `{{ group_docs_root }}/`, any file under a member repo (including `{{ member_repos }}/`), `{{ group_context_path }}`, `{{ group_prefetch_path }}`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Group shared context | `Read {{ group_context_path }}` | always first |
+| Group prefetch ledger | `Read {{ group_prefetch_path }}` | always first |
+| Member list + freshness | `{{ group_context_path }} § Members` / `{{ group_prefetch_path }} § group_list,group_status` | cached |
+| Group contracts | `{{ group_prefetch_path }} § group_contracts` | cached |
+| Per-member route inventory | `{{ group_prefetch_path }} § route_map(<repo>)` per `{{ member_repos }}` | cached |
+| Async / event topics | `mcp__opencodehub__group_query({group: "{{ group }}", text: "message consumer"})` or `"publishes"` | mid-run, only if stream edges are suspected |
+
+## 4. Process
+
+1. `Read {{ group_context_path }}` and `Read {{ group_prefetch_path }}`. Confirm the member list and re-verify every member is tagged `fresh` in the cached `group_status` digest. Abort to Work log if any member is stale.
+2. Pull the contract inventory from `{{ group_prefetch_path }} § group_contracts`. For each `(producer_repo, consumer_repo)` pair, group the contracts by `method + path-prefix` to form a single edge labeled with the representative HTTP verb + path (e.g., `POST /invoices`).
+3. Scan the contract list for event/stream shapes (kind = `topic` / `queue` / `stream` in the cached digest). For each stream, add a parenthesized node `name[(stream.name)]` and draw dashed edges (`-.->`) from consumers and solid edges (`-->`) from publishers.
+4. Compose the node set: one node per member repo (`repo["repo"]` plain rectangle) plus one parenthesized node per event/stream. Cap at 20 nodes — if the group plus streams exceed 20, keep the top-20 by edge count and move overflow into a `## Legend (overflow)` table.
+5. Compose the edge set: solid arrows for synchronous HTTP calls, dashed arrows for async/pub-sub. Each edge label carries the HTTP verb + path (routes) or the event type (streams); ≤ 15 chars.
+6. Draft the Mermaid `flowchart TB`. Every repo node's string identifier and every path/event on every edge must trace back to `group_contracts` or a `route_map` digest — no invented flows.
+7. `Write {{ group_docs_root }}/cross-repo/dependency-flow.md` with H1 = `{{ group }} · Dependency flow`.
+
+## 5. Document format rules
+
+- **Every citation MUST use the group-qualified `repo:path:LOC` form.** Phase E's regex depends on this — bare `path:LOC` will not be rewritten into cross-repo links. Citations appear in any accompanying narrative text, in per-edge footnotes (if used), and in the Legend table's "source" column.
+- H1 = `{{ group }} · Dependency flow`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Exactly one Mermaid diagram, fenced with ` ```mermaid `, diagram type `flowchart TB`.
+- Repo nodes: plain rectangles — `repo["repo"]`.
+- Event/stream nodes: parenthesized shape — `name[(stream.name)]`.
+- Solid arrows (`-->`) for synchronous calls; dashed arrows (`-.->`) for async/pub-sub.
+- Edge labels = HTTP verb + path for routes, event type for streams; ≤ 15 chars.
+- Max 20 nodes total; overflow goes into a `## Legend (overflow)` table below the fenced block.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Member list + freshness | `{{ group_prefetch_path }} § group_list,group_status` | precondition gate; precomputed |
+| Contract inventory | `{{ group_prefetch_path }} § group_contracts` | authoritative spine; source for every edge |
+| Producer file resolution | `{{ group_prefetch_path }} § route_map(<repo>)` | maps contract `path` → handler `file:LOC` for citations |
+| Async/stream discovery | `mcp__opencodehub__group_query` with `"message consumer"` / `"publishes"` | only if stream edges are suspected and not cached |
+| Diagram idioms | `references/mermaid-patterns.md § Cross-repo dependency flow` | canonical `flowchart TB` shape + solid/dashed edge rules |
+
+## 7. Fallback paths
+
+- If `group_contracts` returned zero contracts: emit the diagram with isolated (edge-less) repo nodes and add a `> No inter-repo data flow detected in the group graph` banner immediately beneath the H1. Record the fallback in the Work log.
+- If a member repo is stale despite Phase 0 checks: abort — write `{{ group_docs_root }}/cross-repo/_stale.md` instead, explaining which repo blocked generation, and stop.
+- If a `route_map` digest is missing for a producer: derive the edge label from the raw `method + path` in `group_contracts` and cite the bullet's source as `<producer-repo>:<path>:1`. Record the fallback in the Work log.
+- If `group_query` for `"message consumer"` / `"publishes"` returns nothing: assume the group has no stream edges for this pass and emit only HTTP edges.
+
+## 8. Success criteria
+
+- [ ] `{{ group_docs_root }}/cross-repo/dependency-flow.md` exists on disk.
+- [ ] H1 line reads `# {{ group }} · Dependency flow`.
+- [ ] Exactly one ` ```mermaid ` fence containing a `flowchart TB`.
+- [ ] Diagram has 1-20 nodes; every repo node matches an entry in `group_list`.
+- [ ] Every event/stream node uses the parenthesized `[( )]` shape.
+- [ ] Every solid edge corresponds to a synchronous contract in `group_contracts`; every dashed edge corresponds to a stream / async contract.
+- [ ] Every edge label ≤ 15 chars and matches a real HTTP verb+path or event type from the cached digest.
+- [ ] Every citation in the file uses the `repo:path:LOC` form — no bare `path:LOC` (grep the output to verify).
+- [ ] If overflow occurred, a `## Legend (overflow)` table lists ≥ 5 elided nodes with edge counts.
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is already in `{{ group_prefetch_path }}` — read the cached summary.
+- Do not emit a citation in the bare `path:LOC` form; every citation MUST be `repo:path:LOC`.
+- Do not invent repos, streams, routes, HTTP methods, or event types — every identifier must come from a cached tool response.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than one Mermaid diagram.
+- Do not exceed 20 nodes in the rendered diagram; overflow goes into the Legend table.
+- Do not use solid arrows for async/stream edges, or dashed arrows for synchronous HTTP calls.
+- 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 sync/async edge partitioning went the way it did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md

@@ -0,0 +1,106 @@
+---
+role: doc-cross-repo-portfolio-map
+model: sonnet
+output: "{{ group_docs_root }}/cross-repo/portfolio-map.md"
+depends_on:
+  - "{{ group_context_path }}"
+  - "{{ group_prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ group }} · cross-repo/portfolio-map.md
+
+> **Group mode only.** This packet runs when the skill orchestrator is invoked with `--group {{ group }}`. In single-repo mode it is never seeded.
+
+## 1. Objective
+
+Produce `{{ group_docs_root }}/cross-repo/portfolio-map.md`: a 2-paragraph narrative of the `{{ group }}` group's shape, a Mermaid `flowchart LR` of its member repos with contract-count edges, and a `## Repos` section with per-member H2 + relative link into each member's own `.codehub/docs/` tree.
+
+## 2. Scope
+
+- Create: `{{ group_docs_root }}/cross-repo/portfolio-map.md`
+- Do not touch: any other file under `{{ group_docs_root }}/`, any file under a member repo (including `{{ member_repos }}/.codehub/docs/`), `{{ group_context_path }}`, `{{ group_prefetch_path }}`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Group shared context | `Read {{ group_context_path }}` | always first |
+| Group prefetch ledger | `Read {{ group_prefetch_path }}` | always first |
+| Member list + freshness | `{{ group_context_path }} § Members` / `{{ group_prefetch_path }} § group_list,group_status` | cached |
+| Group contracts | `{{ group_prefetch_path }} § group_contracts` | cached |
+| Per-member one-line description | `{{ group_context_path }} § Member profiles` | cached |
+| Member docs-root paths | derived: `../{{ member_repos[i] }}/.codehub/docs/README.md` | n/a |
+
+## 4. Process
+
+1. `Read {{ group_context_path }}` and `Read {{ group_prefetch_path }}`. Confirm the member list under `§ Members` and re-verify that every member is tagged `fresh` in the cached `group_status` digest. If any member is stale, abort and write the gap to Work log — the orchestrator's Phase 0 gate should have caught this.
+2. Pull the contract inventory from `{{ group_prefetch_path }} § group_contracts`. Aggregate by `(producer_repo, consumer_repo)` into an edge-count table.
+3. Pull one-line domain descriptions for each member from `{{ group_context_path }} § Member profiles`. These become the second line of each node label via `<br/>`.
+4. Draft the 2-paragraph narrative: paragraph 1 = what the group does as a whole (domain, scope); paragraph 2 = how the members relate (who produces for whom, which member is the hub). Every factual claim carries a `repo:path:LOC` citation.
+5. Draft the Mermaid `flowchart LR`: one node per member repo with the two-line label `"<repo><br/><one-line domain>"`; one edge per `(producer, consumer)` pair labeled `contracts: N`. Cap at 20 nodes — if the group has > 20 members, keep the top-20 by inbound+outbound contract count and move the overflow to a `## Legend (overflow)` table.
+6. Draft the `## Repos` section: one H2 per member (`## <repo> — <one-line description>`), each with 1-2 `repo:path:LOC` citations and a `[See {{ member_repos[i] }} docs →](../{{ member_repos[i] }}/.codehub/docs/README.md)` link.
+7. `Write {{ group_docs_root }}/cross-repo/portfolio-map.md` with H1 = `{{ group }} · Portfolio map`.
+
+## 5. Document format rules
+
+- **Every citation MUST use the group-qualified `repo:path:LOC` form.** Phase E's regex depends on this — bare `path:LOC` will not be rewritten into cross-repo links.
+- H1 = `{{ group }} · Portfolio map`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Exactly one Mermaid diagram, fenced with ` ```mermaid `, diagram type `flowchart LR`.
+- Node labels use the `"<repo><br/><one-line domain>"` two-line form; labels ≤ 20 chars per line.
+- Edge labels `contracts: N` where N comes directly from the aggregated `group_contracts` count; ≤ 15 chars.
+- Member-repo links use a relative path rooted at the group directory: `../<repo>/.codehub/docs/README.md`.
+- `## Repos` section has exactly one H2 per member, in the order returned by `group_list`.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Member list + freshness | `{{ group_prefetch_path }} § group_list,group_status` | precondition gate; precomputed |
+| Contract inventory | `{{ group_prefetch_path }} § group_contracts` | authoritative spine; do not re-call |
+| Per-member profile | `{{ group_context_path }} § Member profiles` | cached; source for node labels + H2 text |
+| Diagram idioms | `references/mermaid-patterns.md § Cross-repo portfolio` | canonical `flowchart LR` shape + edge labeling |
+
+## 7. Fallback paths
+
+- If `group_contracts` returned zero contracts: keep the diagram with isolated (edge-less) nodes; narrative paragraph 2 becomes a 1-sentence note that the group graph does not currently encode cross-repo edges. Record the fallback in the Work log.
+- If any member is stale despite Phase 0 checks: abort — do not write `portfolio-map.md`. Instead, write `{{ group_docs_root }}/cross-repo/_stale.md` explaining which repo blocked generation, and stop.
+- If `{{ group_context_path }} § Member profiles` lacks a one-liner for a member: call `mcp__opencodehub__project_profile({repo: <member>})` once, extract the summary, cache the digest in Work log, and use it. Do not invent a description.
+
+## 8. Success criteria
+
+- [ ] `{{ group_docs_root }}/cross-repo/portfolio-map.md` exists on disk.
+- [ ] H1 line reads `# {{ group }} · Portfolio map`.
+- [ ] Narrative is 2 paragraphs, every factual claim cited with `repo:path:LOC`.
+- [ ] Exactly one ` ```mermaid ` fence containing a `flowchart LR` with 1-20 nodes.
+- [ ] Every node label uses the two-line `"<repo><br/><one-line domain>"` form.
+- [ ] `## Repos` section has one H2 per member; each H2 has at least one `repo:path:LOC` citation and a relative `../<repo>/.codehub/docs/README.md` link.
+- [ ] Every citation in the file uses the `repo:path:LOC` form — no bare `path:LOC` (grep the output to verify).
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is already in `{{ group_prefetch_path }}` — read the cached summary.
+- Do not emit a citation in the bare `path:LOC` form; every citation MUST be `repo:path:LOC`.
+- Do not invent member repos, contract counts, or domain descriptions — every identifier must come from a cached tool response or `Read` of the source file.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than one Mermaid diagram.
+- Do not exceed 20 nodes in the rendered diagram; overflow goes into the Legend table.
+- Do not link to a member's docs with an absolute path — relative `../<repo>/.codehub/docs/...` only.
+- 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 member ordering and narrative shape went the way they did }}

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

@@ -0,0 +1,99 @@
+---
+role: doc-diagrams-components
+model: sonnet
+output: "{{ docs_root }}/diagrams/architecture/components.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · diagrams/architecture/components.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/diagrams/architecture/components.md`: a single Mermaid `classDiagram` of the top 8 components of `{{ repo }}` with HAS-A / USES edges, capped at 20 total nodes.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/diagrams/architecture/components.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 communities | `{{ context_path }} § Top communities` | cached |
+| Community relations | `{{ prefetch_path }} § sql relations` or `mcp__opencodehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise |
+| Component method list | `mcp__opencodehub__context({symbol: <community-name>})` per top 8 | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm top-8 community names and their file-path roots.
+2. Pull the raw edge set from `.prefetch.md § sql relations` (kinds `CONTAINS`, `CALLS`, `IMPORTS`). If not cached, call `mcp__opencodehub__sql` with the query above and cache the digest in this packet's Work log.
+3. Project file-level edges down to the community level: collapse every `(source_community, target_community, kind)` triple into a single edge, labeled with a one-word verb (`contains`, `invokes`, `imports`, `depends`).
+4. For each of the top 8 communities, call `mcp__opencodehub__context({symbol: <community-name>})` and select the top 3-5 outbound method names by call count. These populate the `classDiagram` method list for that class.
+5. If the projected graph has > 20 nodes, keep the top-20 by edge count and move the overflow into a `## Legend (overflow)` table with columns `Node | Edges | Reason for elision`.
+6. Draft the Mermaid `classDiagram`. Max 8 classes; each class has 3-5 methods; relationships labeled with one-word verbs.
+7. `Write {{ docs_root }}/diagrams/architecture/components.md` with H1 = `{{ repo }} · Component view`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Component view`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Exactly one Mermaid diagram, fenced with ` ```mermaid `, diagram type `classDiagram`.
+- Max 20 nodes in the diagram; overflow goes into a Legend table below the fenced block.
+- Node labels ≤ 20 chars; edge labels ≤ 15 chars.
+- Every community / class name must match a row in `{{ context_path }} § Top communities` or a symbol returned by `context` — no invented identifiers.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Community list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` |
+| Edge set | `{{ prefetch_path }} § sql relations` | authoritative; filter to `CONTAINS`/`CALLS`/`IMPORTS` |
+| Class method list | `mcp__opencodehub__context` | picks methods by call count |
+| Diagram idioms | `references/mermaid-patterns.md § Component view` | canonical `classDiagram` shape + rules |
+
+## 7. Fallback paths
+
+- If the cached edge set has < 10 `CONTAINS` edges: fall back to `CALLS` edges at file level, collapsing by top-level folder, and label the diagram `Call graph (fallback)` in the H1. Note the fallback in the Work log.
+- If a community's `context` call errors: keep the class in the diagram with an empty method list and append `*methods unavailable*` immediately after the fenced block.
+- If `.context.md § Top communities` is empty: abort and record the gap in the Work log — do not emit a synthetic class list.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/diagrams/architecture/components.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Component view` (or `# {{ repo }} · Call graph (fallback)` if fallback fired).
+- [ ] Exactly one ` ```mermaid ` fence containing a `classDiagram`.
+- [ ] Diagram has 3-20 nodes, each with a label ≤ 20 chars.
+- [ ] Max 8 classes carry method lists; each class has 3-5 methods.
+- [ ] Every edge carries a one-word verb label.
+- [ ] If overflow occurred, a `## Legend (overflow)` table lists ≥ 5 elided nodes with edge counts.
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call `sql` or `project_profile` — those are cached in `.prefetch.md` / `.context.md`.
+- Do not invent class names, method names, or edges — every identifier must come from a tool response or a `Read` of the source file.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than one Mermaid diagram in this file.
+- Do not exceed 20 nodes in the rendered diagram; overflow goes into the Legend table, never back into the diagram.
+- 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 component selection went the way it did }}

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

@@ -0,0 +1,104 @@
+---
+role: doc-diagrams-dependency-graph
+model: sonnet
+output: "{{ docs_root }}/diagrams/structural/dependency-graph.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · diagrams/structural/dependency-graph.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/diagrams/structural/dependency-graph.md`: a single Mermaid `flowchart LR` showing `{{ repo }}`'s internal communities alongside external-dep leaf nodes, capped at 20 total nodes.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/diagrams/structural/dependency-graph.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 communities | `{{ context_path }} § Top communities` | cached |
+| Internal edges | `{{ prefetch_path }} § sql relations` or `mcp__opencodehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise |
+| External dependencies | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` | cached if digest present; mid-run otherwise |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the internal community list and the external-dep list.
+2. Pull the internal edge set from `.prefetch.md § sql relations`. If not cached, call `mcp__opencodehub__sql` and cache the digest in this packet's Work log.
+3. Pull the external-dep list from `.context.md § Stack`. If absent, call `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` and keep the top 15 by usage.
+4. Compose the node set: internal communities (as `name[Label]` plain rectangles) plus the external deps (as `name[(Label)]:::external` parenthesized nodes with a dashed stroke class). Reserve the full 20-node budget; drop lowest-usage externals first when pruning.
+5. Compose the edge set: internal→internal edges from the `sql` result collapsed to community level; internal→external edges from the dependency list, sourced at the internal community that imports the dep most often.
+6. If node count > 20 after composition: keep the top-20 by edge count, then add a `## Legend (overflow)` table with columns `Node | Edges | Reason for elision`.
+7. Draft the Mermaid `flowchart LR`. Include the `classDef external stroke-dasharray: 3 3` line so external leaves render dashed.
+8. `Write {{ docs_root }}/diagrams/structural/dependency-graph.md` with H1 = `{{ repo }} · Dependency graph`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Dependency graph`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Exactly one Mermaid diagram, fenced with ` ```mermaid `, diagram type `flowchart LR`.
+- Internal communities: plain rectangles — `name[Label]`.
+- External deps: parenthesized shape with external class — `name[(Label)]:::external` + `classDef external stroke-dasharray: 3 3`.
+- Max 20 nodes total; overflow goes into a Legend table below the fenced block.
+- Node labels ≤ 20 chars; edge labels ≤ 15 chars.
+- Every internal node must match a row in `{{ context_path }} § Top communities`; every external node must match a row from `dependencies` or `.context.md § Stack`.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Internal node list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` for it |
+| Internal edge set | `{{ prefetch_path }} § sql relations` | authoritative; filter to `CONTAINS`/`CALLS`/`IMPORTS` |
+| External leaf nodes | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies` | do not grep manifests |
+| Diagram idioms | `references/mermaid-patterns.md § Dependency graph` | canonical `flowchart LR` shape + external-node styling |
+
+## 7. Fallback paths
+
+- If `dependencies` errors and `.context.md § Stack` is missing: `Read` the root `package.json` / `Cargo.toml` / `pyproject.toml` and extract the top 15 deps by semantic weight. Append a `*manifest fallback*` note immediately after the fenced block and record the fallback in the Work log.
+- If the internal edge set has < 10 `CONTAINS` edges after projection: drop to `CALLS` edges at file level, collapse by top-level folder, and label the diagram `Call graph (fallback)` in the H1.
+- If `.context.md § Top communities` is empty: abort and record the gap in the Work log — do not synthesize internal nodes from bare filesystem layout.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/diagrams/structural/dependency-graph.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Dependency graph` (or the `Call graph (fallback)` variant if the fallback fired).
+- [ ] Exactly one ` ```mermaid ` fence containing a `flowchart LR`.
+- [ ] Diagram has 3-20 nodes, each with a label ≤ 20 chars.
+- [ ] At least one internal community and one external dep appear in the diagram.
+- [ ] External-dep nodes use the parenthesized shape and the `external` class.
+- [ ] The `classDef external stroke-dasharray: 3 3` line is present.
+- [ ] If overflow occurred, a `## Legend (overflow)` table lists ≥ 5 elided nodes with edge counts.
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call `sql`, `dependencies`, or `project_profile` — those are cached in `.prefetch.md` / `.context.md`.
+- Do not invent internal or external node names — every identifier must come from a tool response or a `Read` of the source file.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than one Mermaid diagram in this file.
+- Do not exceed 20 nodes in the rendered diagram; overflow goes into the Legend table.
+- Do not mix internal and external nodes under the same shape — internals are `[ ]`, externals are `[( )]:::external`.
+- 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 internal/external node selection went the way it did }}