@opencodehub/cli 0.2.2 → 0.2.3

package/dist/plugin-assets/hooks/docs-staleness.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Non-blocking docs-staleness hook — fires after codehub auto-reindex.
+# When .codehub/docs/.docmeta.json exists and the graph_hash in the
+# manifest disagrees with the live hash, emit a systemMessage suggesting
+# /codehub-document --refresh. Never regenerates automatically —
+# regeneration spends LLM credits and requires consent.
+
+set -uo pipefail
+
+# Only fire for git mutations we just auto-reindexed on.
+if ! echo "${CLAUDE_TOOL_INPUT:-}" | grep -qE 'git (commit|merge|rebase|pull)'; then
+  exit 0
+fi
+
+DOCMETA=".codehub/docs/.docmeta.json"
+if [ ! -f "$DOCMETA" ]; then
+  exit 0
+fi
+
+# Extract manifest hash. jq is a soft dependency; fall back to grep.
+if command -v jq >/dev/null 2>&1; then
+  MANIFEST_HASH=$(jq -r '.codehub_graph_hash // empty' "$DOCMETA" 2>/dev/null || true)
+else
+  MANIFEST_HASH=$(grep -o '"codehub_graph_hash":[[:space:]]*"[^"]*"' "$DOCMETA" | head -1 | sed 's/.*"codehub_graph_hash":[[:space:]]*"//;s/"$//')
+fi
+
+if [ -z "${MANIFEST_HASH:-}" ]; then
+  exit 0
+fi
+
+# Live hash via the CLI. Keep timeout short so the hook never blocks the user.
+LIVE_HASH=$(timeout 3 codehub status --format=hash 2>/dev/null | head -1 || true)
+
+if [ -z "${LIVE_HASH:-}" ]; then
+  # CLI not available or timed out; emit nothing.
+  exit 0
+fi
+
+if [ "$MANIFEST_HASH" != "$LIVE_HASH" ]; then
+  # systemMessage format: this text is surfaced to Claude, not the user shell.
+  # Non-blocking — just a hint.
+  printf '{"systemMessage":"Docs at .codehub/docs/ may be stale (graph_hash changed). Run /codehub-document --refresh when convenient."}\n'
+fi
+
+exit 0

package/dist/plugin-assets/hooks.json

@@ -0,0 +1,34 @@
+{
+  "description": "Augment searches with graph context, auto-reindex after git mutations, and flag stale generated docs.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/augment.sh",
+            "timeout": 5,
+            "statusMessage": "Enriching with codehub graph context..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"${CLAUDE_TOOL_INPUT:-}\" | grep -qE 'git (commit|merge|rebase|pull)'; then codehub analyze --incremental --quiet || true; fi"
+          },
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/docs-staleness.sh",
+            "timeout": 4
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugin-assets/skills/codehub-code-pack/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: codehub-code-pack
+description: |
+  Use when the user asks for a deterministic code pack of a repo or
+  group — a 9-item BOM (manifest, skeleton, file-tree, deps,
+  ast-chunks, xrefs, optional embeddings sidecar, findings,
+  licenses + readme) that is byte-identical given the same
+  (commit, tokenizer, budget). Examples: "pack this repo for an
+  LLM", "deterministic code pack", "build a reproducible context
+  pack", "pack the platform group". DO NOT use for one-off repo
+  packing without determinism — `pack_codebase --engine repomix`
+  is the bandwidth-saving fallback for that case (no packHash, no
+  9-item BOM, no reproducibility contract).
+argument-hint: "[<repo-or-group>] [--budget <N>] [--tokenizer <id>]"
+allowed-tools: pack_codebase, list_repos, project_profile, list_findings
+model: sonnet
+---
+
+# codehub-code-pack
+
+Surface the `pack_codebase` MCP tool to a Claude Code agent. Produces a
+**deterministic, 9-item Bill of Materials (BOM)** at `<repo>/.codehub/packs/<packHash>/`
+that is byte-identical given the same `(commit, tokenizer, budget,
+chonkie_version, duckdb_version, grammar_commits)`. The pack is the
+durable artifact agents hand to long-context LLMs, archive in S3 for
+later replay, or diff between commits to prove invariants did not
+change.
+
+## Purpose
+
+The 9-item BOM is the smallest faithful representation of a repo for
+LLM consumption: a manifest pinning every input that could change
+output, a PageRank-ranked skeleton (top symbols first), a file tree,
+a dependency lockfile slice, AST-chunked top files, SCIP-grounded
+cross-refs, an optional embeddings Parquet sidecar, salient SARIF
+findings, and a `LICENSES + README` pair. Determinism is the headline
+property: re-running with identical inputs MUST produce identical
+output bytes (verified by `cmp -s` and the determinism suite — see
+`references/determinism-contract.md`).
+
+`packHash` is `sha256(canonicalJson(manifest_with_packHash_omitted))` —
+it commits to every other field in the manifest, including the
+`fileHash` of every BOM item. Two packs share a `packHash` iff every
+input that the pack emitter looked at is identical.
+
+**When to use this skill vs `pack_codebase --engine repomix`:**
+
+- Use **this skill** when the user wants reproducibility, archival, a
+  pack to feed to a CI replay job, or a pack to compare across
+  commits. Default for any "pack the repo" request unless the user
+  explicitly asks to skip determinism.
+- Use **`pack_codebase --engine repomix`** (no skill required) when
+  the user wants a one-shot bandwidth-saving dump for a single LLM
+  call and explicitly does not need byte-identity. The repomix path
+  remains opt-in through M6 then sunsets in M7.
+
+## Single-repo mode
+
+1. **Pre-check** — call `list_repos`. If the target repo is not
+   indexed, instruct the user to run `codehub analyze` and stop. If
+   `≥ 2` repos are indexed and no `repo` argument was supplied, the
+   per-repo tool will return `AMBIGUOUS_REPO`; retry with one of the
+   `structuredContent.error.choices[].repo_uri` values verbatim
+   (Sourcegraph-style URI, e.g. `github.com/org/repo`, or
+   `local:<hash>`).
+2. **Confirm graph freshness** — call `project_profile` on the
+   resolved repo. If the response carries a `_meta.codehub/staleness`
+   envelope, surface it: tell the user the pack will reflect the last
+   `codehub analyze` run, not HEAD.
+3. **Optional findings preview** — if the user asks for findings in
+   the pack, call `list_findings` to confirm SARIF rows exist.
+4. **Pack** — call `pack_codebase` with `engine: "pack"` (the
+   default). The tool resolves `outDir` to
+   `<repoRoot>/.codehub/packs/<packHash>/` and writes the 9 items
+   plus `manifest.json`.
+5. **Report back** — surface the `packHash`, the `determinismClass`,
+   and the absolute output directory. If `determinismClass` is
+   `best_effort` or `degraded`, name the cause (Anthropic tokenizer
+   rotation hazard, or chonkie native binding unavailable).
+
+The manifest schema is fixed at `schemaVersion: 1`. Required fields:
+`commit`, `repoOriginUrl`, `tokenizerId`, `determinismClass`,
+`budgetTokens`, `pins` (`chonkieVersion`, `duckdbVersion`,
+`grammarCommits`), `files[]`, `packHash`, `schemaVersion`.
+
+## Group mode
+
+1. **Pre-check** — call `list_repos` and `mcp__codehub__group_list` to
+   confirm the named group exists and every member is fresh.
+2. **Fan out** — for each group member, run the single-repo flow
+   above. The orchestrator does this with one `pack_codebase` call
+   per member; pack runs are independent and parallelizable up to the
+   Claude Code subagent ceiling.
+3. **Aggregate** — emit a per-member table of
+   `(repoUri, packHash, determinismClass, outDir)` so the caller can
+   archive or replay each member individually.
+
+`packHash` is **per-repo, not per-group, in v1**. There is no
+`groupPackHash` — a group "pack" is the union of N per-repo BOMs. A
+later milestone may introduce a group-level manifest aggregating
+member packHashes; until then, the v1 contract is N independent
+packs.
+
+## Determinism class
+
+The manifest stamps one of three values; agents must report it
+verbatim when surfacing the pack to the user.
+
+| Class | Meaning | When emitted |
+|-------|---------|--------------|
+| `strict` | Same `(commit, tokenizer, budget, chonkieVersion, duckdbVersion, grammarCommits)` → same `packHash`. The full reproducibility contract holds. | Default path: chonkie native binding loaded, deterministic tokenizer (e.g. local HF tokenizer with pinned hash). |
+| `best_effort` | The tokenizer is an Anthropic API tokenizer (Claude family) — Anthropic may rotate the tokenizer pin behind the model name. Other inputs are still strictly pinned, but a future tokenizer rotation can change the output. | When `tokenizerId` resolves to a Claude model. The BOM verifier MUST warn callers checking byte-identity. |
+| `degraded` | A primitive fallback was used (e.g. line-split chunker because `@chonkiejs/core` failed to load). The pack is still self-consistent and re-runs match locally, but **does not** match a `strict` pack on a different machine. | When chonkie native binding is unavailable on CI platform. |
+
+## 9-item BOM contract
+
+| # | File | Source module | Determinism contract |
+|---|------|---------------|----------------------|
+| 1 | `manifest.json` | `manifest.ts` | RFC 8785 canonical JSON; pack-hash field omitted from preimage; CRLF normalized to LF before hashing content |
+| 2 | `skeleton.jsonl` | `skeleton.ts` | PageRank score DESC, then `id` ASC tiebreak |
+| 3 | `file-tree.jsonl` | `file-tree.ts` | `path` ASC |
+| 4 | `deps.jsonl` | `deps.ts` | `(ecosystem, name, version, id)` lexicographic ASC |
+| 5 | `ast-chunks.jsonl` | `ast-chunker.ts` | chonkie chunker; LF-normalized; degrades to line-split with `determinismClass: degraded` |
+| 6 | `xrefs.jsonl` | `xrefs.ts` | community rows first (`id` ASC), then call rows (`from`, `to`, `id` ASC) |
+| 7 | `embeddings.parquet` | `embeddings-sidecar.ts` | OPTIONAL — absent entirely when no embeddings exist; ZSTD; `ORDER BY (node_id, granularity, chunk_index)` |
+| 8 | `findings.jsonl` | `findings.ts` | severity rank then `ruleId` ASC |
+| 9 | `licenses.md` + `readme.md` | `licenses.ts` + `readme.ts` | alpha-sorted dependency list; static template with manifest-derived header |
+
+`manifest.files[]` lists every emitted item as `{kind, path, fileHash}`
+where `fileHash` is `sha256` hex of the raw bytes. Item 7 is omitted
+from `files[]` when no embeddings exist; do not emit an empty Parquet
+file.
+
+## Verification recipe — proving the pack is deterministic
+
+A caller proves byte-identity by re-running and diffing:
+
+```bash
+# 1. Pin the environment so chonkie/duckdb match.
+node --version
+cat packages/pack/package.json | jq '.dependencies."@chonkiejs/core", .dependencies."@duckdb/node-api"'
+
+# 2. Run the pack twice with identical args.
+codehub code-pack --budget 200000 --tokenizer cl100k_base --out /tmp/packA
+codehub code-pack --budget 200000 --tokenizer cl100k_base --out /tmp/packB
+
+# 3. Tree-diff: this MUST produce no output.
+diff -r /tmp/packA /tmp/packB
+
+# 4. Hashes match.
+jq -r '.pack_hash' /tmp/packA/manifest.json
+jq -r '.pack_hash' /tmp/packB/manifest.json
+
+# 5. Tool-version pins are identical (these MUST match across runs).
+jq '.pins' /tmp/packA/manifest.json
+jq '.pins' /tmp/packB/manifest.json
+```
+
+If `diff -r` reports any byte-level difference, do NOT silently retry
+— inspect `manifest.determinism_class`. `degraded` means chonkie was
+unavailable on at least one run; `best_effort` means the Anthropic
+tokenizer rotated; `strict` mismatch is a determinism bug, file it.
+
+## next_steps
+
+When `packHash` drifts unexpectedly between two runs you believe are
+identical:
+
+1. Compare the two `manifest.json` files field-by-field — the first
+   field that differs identifies the offending input.
+2. Run `mcp__codehub__project_profile` to confirm the index has not
+   been re-analyzed under you (an `analyze` invalidates the previous
+   pack's `commit` field).
+3. If `pins` differs, the local toolchain has changed — pin
+   `@chonkiejs/core` and `@duckdb/node-api` in `package.json`.
+4. If only `files[i].fileHash` differs for a single BOM item, that
+   item's emitter has a determinism bug; raise it in the determinism
+   suite under `packages/pack/src/`.
+5. For deeper review, consult `references/determinism-contract.md`
+   (the spec excerpt) and the determinism test suite at
+   `packages/pack/src/pack-determinism.test.ts`.

package/dist/plugin-assets/skills/codehub-code-pack/references/determinism-contract.md

@@ -0,0 +1,150 @@
+# Determinism contract — auditor reference
+
+Ground truth for the `codehub-code-pack` skill. Cite this file when the
+user disputes a `packHash` mismatch, when a CI determinism gate fails,
+or when a future contributor proposes adding a non-deterministic emitter
+to `@opencodehub/pack`. The reference implementation in
+`packages/pack/src/` is authoritative; this document describes the
+contract that the implementation enforces.
+
+## 9-item code-pack BOM
+
+Every `codehub code-pack` invocation produces a directory of nine BOM
+items plus a manifest. Same `(commit, tokenizer, budget)` → byte-
+identical output:
+
+1. `manifest.json` — pack_hash, commit SHA, tokenizer ID, schema version, counts
+2. PageRank-ranked symbol skeleton
+3. File tree with framework labels
+4. Dependency graph / lockfile slice (exact versions)
+5. Top-N AST-chunked files with byte offsets
+6. SCIP-grounded cross-refs (community clusters + call graph)
+7. Optional embeddings sidecar (`.parquet`)
+8. Salient docstrings / SARIF findings by severity + rule
+9. LICENSES / NOTICES + README.md + full determinism contract
+
+## Invariants
+
+- **graphHash byte-identity** holds before and after every pack-
+  affecting commit — the `DuckDbStore` / `GraphDbStore` parity suite
+  stays green.
+- **packHash byte-identity** — same
+  `(commit, tokenizer, budget, chonkie_version, duckdb_version,
+  grammar_commits)` → same `packHash`. Verified by the determinism
+  suite at `packages/pack/src/pack-determinism.test.ts`.
+- **No banned literals** in tracked source —
+  `bash scripts/check-banned-strings.sh` exits 0 post-commit.
+- **`mise run check`** exits 0 after every commit.
+- **Naming + license** — every new package carries `@opencodehub/<name>`
+  naming, Apache-2.0 license, `type: module`, `tsc --noEmit` clean.
+- **No LLM calls** outside `@opencodehub/summarizer`.
+- **Deterministic output** — every MCP tool and CLI output is
+  alpha-sorted with a lex-stable tiebreak.
+
+## Behavior
+
+### Pack invocation
+
+- `codehub code-pack <repo> --budget <N>` produces a directory
+  containing all 9 BOM items plus `manifest.json` at
+  `<repo>/.codehub/packs/<pack_hash>/`.
+- The `pack_codebase` MCP tool routes through `@opencodehub/pack`. The
+  legacy `repomix` path remains available under an `--engine repomix`
+  opt-in flag for one milestone before removal.
+- Two invocations of `codehub code-pack` with the same
+  `(commit, tokenizer, budget)` produce byte-identical output (`cmp -s`
+  on every file under the output directory).
+- `manifest.json` carries
+  `{commit, repo_origin_url, tokenizer_id, determinism_class,
+  budget_tokens, grammar_commits, chonkie_version, duckdb_version,
+  files[], pack_hash}` with
+  `pack_hash = sha256(canonicalJson(all-other-fields))`.
+- PageRank is computed at request time from the loaded
+  `KnowledgeGraph` via `@opencodehub/analysis` — never at index time.
+
+### Degraded modes
+
+- When `@chonkiejs/core` fails to install or load (native binding
+  unavailable on a CI platform), pack degrades to a line-split
+  fallback and stamps `determinism_class: degraded` in the manifest —
+  it does NOT silently emit byte-different output claiming strict
+  determinism.
+- When `tokenizer_id` names a Claude model, the manifest sets
+  `determinism_class: best_effort`. The BOM verifier warns when asked
+  to check byte-identity against such a pack.
+- When the target repo has no embeddings computed, BOM item #7 (the
+  Parquet sidecar) is absent entirely (not an empty file) and
+  `manifest.files[]` does NOT list a path to it.
+
+### Forbidden
+
+- No LLM calls in `@opencodehub/pack` (enforced by
+  `scripts/check-banned-strings.sh`-style audit + a
+  `no-bedrock-outside-summarizer` test).
+- No writer metadata (DuckDB `created_by`, chonkie writer tags) as
+  top-level fields in `manifest.json` — all tool-version pins live in
+  a single nested `pins: {}` object so the BOM schema is stable across
+  tool upgrades.
+- No tolerance-based PageRank convergence — fixed iterations only.
+- CRLF files on Windows checkouts MUST NOT produce a different
+  `pack_hash` than LF on Linux — ingest normalizes to LF before
+  hashing content.
+
+## packHash construction algorithm
+
+The exact preimage shape that produces `packHash`:
+
+1. Compute `fileHash = sha256_hex(raw_bytes)` for every emitted BOM
+   file (items 2-9 from the contract above). CRLF files are
+   normalized to LF **at ingest** before hashing content — the
+   on-disk bytes after normalization are the bytes that get hashed.
+2. Construct the manifest object with `packHash: ""` as a placeholder
+   and `files[]` populated with `{kind, path, fileHash}` rows in the
+   order they appear in `BomItem.kind` (the type union enumerates a
+   stable order).
+3. Serialize the manifest to RFC 8785-shaped canonical JSON (sorted
+   keys, no whitespace, no trailing newline). All tool-version pins
+   live in a single nested `pins: {}` object — the top-level
+   `manifest.json` schema does not carry writer metadata.
+4. `packHash = sha256_hex(canonicalJson(manifest_with_packHash_omitted))`.
+5. Replace the placeholder. Write `manifest.json` with `packHash` set
+   and `files[]` unchanged. The wire form serializes camelCase TS
+   fields to snake_case keys (`pack_hash`, `determinism_class`,
+   `repo_origin_url`, `tokenizer_id`, `budget_tokens`, `schema_version`)
+   per `packages/pack/src/manifest.ts:84-90`.
+
+The reference implementation is `packages/pack/src/manifest.ts` (the
+`buildManifest()` helper). The serializer reuses
+`packages/core-types/src/graph-hash.ts` `writeCanonicalJson` — the
+same canonical-JSON pattern that `graphHash` uses.
+
+## Determinism class triage
+
+The manifest's `determinism_class` (snake_case on disk, `determinismClass`
+in TS) takes one of three values:
+
+| Class | Trigger | Implication |
+|-------|---------|-------------|
+| `strict` | None of the degraded triggers fire | The byte-identity invariant holds in full: same `(commit, tokenizer, budget, chonkie_version, duckdb_version, grammar_commits)` → same `pack_hash`. |
+| `best_effort` | `tokenizer_id` resolves to a Claude model | The verifier MUST warn callers checking byte-identity. |
+| `degraded` | `@chonkiejs/core` native binding fails to load | Line-split fallback used; pack still self-consistent locally but not portable. |
+
+## Determinism suite location
+
+The byte-identity test suite lives at
+`packages/pack/src/pack-determinism.test.ts`. It runs `generatePack`
+twice against a fixture repo, computes `cmp -s` over every output
+file, and asserts manifest `pack_hash` equality. CI gates on this
+suite.
+
+When debugging a `pack_hash` drift:
+
+1. Re-run with `engine: "pack"` and capture both manifests.
+2. Compare `pins` first — a chonkie or duckdb upgrade in node_modules
+   is the most common cause.
+3. Compare `files[i].file_hash` row-by-row — the first mismatch
+   identifies which BOM emitter is non-deterministic.
+4. Inspect the offending emitter under `packages/pack/src/` (one
+   module per BOM item: `manifest.ts`, `skeleton.ts`, `file-tree.ts`,
+   `deps.ts`, `ast-chunker.ts`, `xrefs.ts`, `embeddings-sidecar.ts`,
+   `findings.ts`, `licenses.ts`, `readme.ts`).

package/dist/plugin-assets/skills/codehub-contract-map/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: codehub-contract-map
+description: "Use when the user asks for a cross-repo contract map, an API-consumer matrix, or a service-interaction diagram across a repo group. Examples: \"map the HTTP contracts between services\", \"which services call the billing API\", \"show the contract matrix for the platform group\". GROUP MODE ONLY — requires a named group. DO NOT use on a single repo (use `codehub-document` with `reference/public-api.md`). DO NOT use if `mcp__opencodehub__group_list` does not include the group."
+allowed-tools: "Read, Write, mcp__opencodehub__group_list, mcp__opencodehub__group_status, mcp__opencodehub__group_contracts, mcp__opencodehub__group_query, mcp__opencodehub__route_map, mcp__opencodehub__list_repos"
+argument-hint: "<group-name> [--output <path>] [--committed]"
+color: magenta
+model: sonnet
+---
+
+# codehub-contract-map
+
+Standalone group-only skill. Renders `group_contracts` into a Markdown + Mermaid artifact. Fires on direct invocations ("map the contracts") without needing the full `codehub-document` orchestration.
+
+## Preconditions
+
+1. A `<group-name>` positional argument is required. If missing or if `mcp__opencodehub__group_list` does not return the name, refuse with:
+   `Contract map requires a named group — run 'codehub group list' to see registered groups.`
+2. `mcp__opencodehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo.
+
+## Arguments
+
+- `<group-name>` (required positional) — the group to map.
+- `--output <path>` (optional) — override the output path.
+- `--committed` (optional) — write to a committed path instead of `.codehub/`.
+
+Default output path:
+- without `--committed`: `.codehub/groups/<name>/contracts.md` (gitignored)
+- with `--committed`: `docs/<group>/contracts.md`
+
+## Process
+
+1. Run the preconditions. Refuse on missing/unknown group.
+2. `mcp__opencodehub__group_list` — confirm `<group-name>` exists; read member list.
+3. `mcp__opencodehub__group_status({group})` — confirm freshness per member. Abort with named stale repos otherwise.
+4. `mcp__opencodehub__group_contracts({group})` — the spine. Returns `{consumerRepo, consumerRepoUri, consumerSymbol, producerRepo, producerRepoUri, producerRoute, method, path}` per row (legacy `consumerRepo`/`producerRepo` are the registry names; the `*RepoUri` siblings are the Sourcegraph-style cross-repo handle and are the preferred handle going forward).
+5. If `group_contracts` returns `[]` (zero inter-repo contracts): still write the artifact with a `No inter-repo contracts detected` banner and an empty matrix. Do not error.
+6. `mcp__opencodehub__group_query({group, text: "api handlers"})` — disambiguate producer-side locations.
+7. For each member repo: `mcp__opencodehub__route_map({repo})` for handler-path citations.
+8. Build the consumer/producer matrix: rows = producers, columns = consumers, cell = contract count.
+9. Build the Mermaid `flowchart LR` showing inter-repo edges, labeled with contract counts.
+10. Assemble the output using the template below.
+11. `Write` to the resolved output path.
+
+## Output template
+
+### Normal case (contracts exist)
+
+```markdown
+# <group> · Contract map
+
+*Generated <ISO-8601>. Members: <list>. Graph hashes: <list>.*
+
+## Contracts matrix
+
+Rows = producers; columns = consumers. Cell = number of contracts.
+
+|       | billing | core | web |
+|-------|---------|------|-----|
+| billing | —     | 3    | 5   |
+| core  | —       | —    | 12  |
+| web   | —       | —    | —   |
+
+## Flow
+
+```mermaid
+flowchart LR
+  web --> billing : 5
+  web --> core : 12
+  billing --> core : 3
+```
+
+## Notable contracts
+
+- **`web:packages/checkout/src/api.ts:22` → `billing:packages/api/src/handlers/invoice.ts:45`**
+  - Method: `POST /v1/invoices`
+  - Shape: `{amount, userId, idempotencyKey}`
+
+- ... (top 10 contracts with direction, method, path, both-ends citations, shape summary)
+
+## See also (other repos in group)
+
+- [billing docs →](../billing/.codehub/docs/README.md)
+- [core docs →](../core/.codehub/docs/README.md)
+- [web docs →](../web/.codehub/docs/README.md)
+```
+
+### Empty case (zero contracts)
+
+```markdown
+# <group> · Contract map
+
+*Generated <ISO-8601>. Members: <list>.*
+
+**No inter-repo contracts detected.** The group graph does not currently encode cross-repo edges between these repos.
+
+This can mean:
+1. The repos genuinely do not interact (check whether that's expected).
+2. `group_sync` has not yet run for this group — try `codehub group sync <name>`.
+3. The contract surface is not yet captured by scanners (e.g., pub-sub channels that the graph does not model).
+
+## Members
+
+| Repo | Graph hash | Last indexed |
+|---|---|---|
+| billing | sha256:… | 2026-04-27T18:12:04Z |
+| core | sha256:… | 2026-04-27T18:11:02Z |
+| web | sha256:… | 2026-04-27T17:58:41Z |
+
+## Empty matrix
+
+|       | billing | core | web |
+|-------|---------|------|-----|
+| billing | —     | 0    | 0   |
+| core  | —       | —    | 0   |
+| web   | —       | —    | —   |
+```
+
+## Document format rules
+
+- H1 = "{{group}} · Contract map".
+- **Every citation MUST use the group-qualified form**: `` `<repo>:<path>:<LOC>` ``.
+- The Mermaid diagram appears only when there is ≥ 1 inter-repo contract.
+- Matrix table always rendered as an N×N grid, even when most cells are zero.
+- Each member-repo link uses a relative path rooted at the group directory.
+- No YAML frontmatter on the output.
+- No emojis.
+
+## Fallback paths
+
+- If `group_contracts` times out: emit a partial matrix with `*partial — timed out*` in the affected rows; do not error. Record the timeout in a trailing `## Known limitations` section.
+- If `group_query` returns nothing for `"api handlers"`: try `"http route"`, `"mcp tool"`, `"message consumer"` in order.
+- If `route_map` errors for a single member: fall back to citing just `repo:package/path` without the `:LOC` suffix for that member; mark inline as `*route_map unavailable*`.
+
+## Quality checklist
+
+- [ ] `<group-name>` was required; refused if missing.
+- [ ] `group_list` validated the name.
+- [ ] Every member repo was `fresh` per `group_status`; otherwise aborted with named stale repos.
+- [ ] Every citation uses the `repo:path:LOC` form.
+- [ ] Matrix renders as a full N×N grid.
+- [ ] Mermaid diagram appears iff ≥ 1 contract.
+- [ ] Empty case produces an artifact (not an error) with the "No inter-repo contracts detected" banner.
+- [ ] Output path respects `--committed` and `--output`.
+- [ ] "See also (other repos in group)" footer lists every member repo's docs root.