npm - @opencodehub/cli - Versions diffs - 0.2.1 → 0.2.3 - Mend

@opencodehub/cli 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/dist/plugin-assets/skills/codehub-pr-description/SKILL.md ADDED Viewed

@@ -0,0 +1,122 @@
+---
+name: codehub-pr-description
+description: "Use when the user asks for a PR description, a pull request summary, a merge write-up, or a release note for a branch or diff. Examples: \"write the PR description\", \"summarize this branch for review\", \"draft release notes for HEAD\". Calls `detect_changes` + `verdict` + `owners` + `list_findings_delta` and writes Markdown. DO NOT use for open-ended architecture docs (use `codehub-document`) or onboarding guides (use `codehub-onboarding`). DO NOT use when no diff exists — the skill refuses on a clean tree."
+allowed-tools: "Read, Write, Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*), mcp__opencodehub__detect_changes, mcp__opencodehub__verdict, mcp__opencodehub__owners, mcp__opencodehub__impact, mcp__opencodehub__signature, mcp__opencodehub__list_findings_delta, mcp__opencodehub__api_impact"
+argument-hint: "[--base <rev>] [--head <rev>] [--out <path>]"
+color: teal
+model: sonnet
+---
+# codehub-pr-description
+Generates a Markdown PR body from graph primitives. Linear (no subagents). Sonnet. Refuses on a clean tree.
+## Preconditions
+1. Resolve `--base` (default `main`) and `--head` (default `HEAD`) via `git rev-parse`.
+2. `git diff --name-only <base>..<head>` must return ≥ 1 path. If empty, emit `No diff detected — resolve base/head or stage changes.` and stop.
+## Arguments
+- `--base <rev>` — base revision. Default: `main`.
+- `--head <rev>` — head revision. Default: `HEAD`.
+- `--out <path>` — output path. Default: `.codehub/pr/PR-<branch>.md`.
+## Process
+1. Run the preconditions. On clean tree, refuse and stop.
+2. `mcp__opencodehub__detect_changes({base, head})` — map the diff to affected symbols + processes.
+3. `mcp__opencodehub__verdict({base, head})` — 5-tier merge recommendation with reasons.
+4. `mcp__opencodehub__owners({paths: <changed-files>})` — required reviewers per path.
+5. `mcp__opencodehub__list_findings_delta({base, head})` — new/resolved scanner findings in the diff range.
+6. For any symbol flagged as tier ≥ 3 by verdict: `mcp__opencodehub__impact({symbol, direction: "downstream", depth: 2})` — spell out who breaks.
+7. For public API changes: `mcp__opencodehub__api_impact({route})` when the diff touches a handler.
+8. Assemble the Markdown body using the template below.
+9. `Write` to `<out>`.
+## Output template
+```markdown
+# <branch-name or commit subject>
+## Summary
+2–3 sentences describing what this PR changes and why. Grounded in the
+commit messages + the highest-impact change detected.
+## Verdict
+**Tier <N> — <label>** per `mcp__opencodehub__verdict`.
+Reasons:
+- ... (from verdict.reasons[])
+## Affected surface
+| Category | Count | Details |
+|---|---|---|
+| Files changed | N | `git diff --stat` summary |
+| Symbols added | N | from `detect_changes` |
+| Symbols removed | N | from `detect_changes` |
+| Processes touched | N | from `detect_changes.processes[]` |
+### Top touched files
+| File | Change | Top owner |
+|---|---|---|
+| `packages/foo/src/bar.ts` | +40 / -12 | alice@ |
+| ... | ... | ... |
+## Blast radius
+(Only when verdict tier ≥ 3.)
+- Downstream consumers of `<symbol>`: <count>. See `impact` output.
+- Affected routes: (if `api_impact` returned non-empty)
+## Findings delta
+| Change | Severity | File |
+|---|---|---|
+| new | error | `packages/foo/src/bar.ts:42` |
+| resolved | warn | `packages/other.ts:88` |
+(Or: "No new findings. 2 findings resolved." as a terse summary.)
+## Required reviewers
+- `packages/foo/` — alice@, bob@
+- `packages/other/` — charlie@
+## Test plan
+- [ ] ...
+- [ ] ...
+(Extract TODO-shaped lines from `git log <base>..<head>` or leave a blank checklist for the author to fill in.)
+```
+## Document format rules
+- H1 = the PR title. If the branch name is descriptive, use it; otherwise fall back to the first commit subject.
+- Every file citation uses backtick `path:LOC` form where line information is meaningful.
+- The `Verdict` tier line is always present, even on clean-verdict passes ("Tier 1 — safe to merge").
+- No YAML frontmatter on the output.
+- No emojis.
+## Fallback paths
+- If `verdict` errors: emit "Verdict unavailable — running in degraded mode" in the Verdict section and proceed with the rest.
+- If `list_findings_delta` returns `status: "no_baseline"`: use `list_findings` for the current head and note "No baseline for findings delta; showing current findings only."
+- If `owners` returns `[]` for all paths: omit the Required reviewers section and record `*owners unavailable*` inline.
+## Quality checklist
+- [ ] Preconditions enforced — refused on clean tree.
+- [ ] Verdict tier appears.
+- [ ] Affected surface table present with non-empty rows.
+- [ ] Top touched files table has at least one row with owner.
+- [ ] Blast radius section appears iff verdict tier ≥ 3.
+- [ ] Findings delta has a row for every new/resolved finding, or a "No new findings" summary.
+- [ ] Test plan section exists (may be empty checklist).
+- [ ] Output written to `<out>`; default is `.codehub/pr/PR-<branch>.md`.

package/dist/plugin-assets/skills/opencodehub-debugging/SKILL.md ADDED Viewed

@@ -0,0 +1,144 @@
+---
+name: opencodehub-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\", \"This endpoint returns 500\"."
+---
+# Debugging with OpenCodeHub
+## When to Use
+- "Why is this function failing?"
+- "Trace where this error comes from."
+- "Who calls this method?"
+- "This endpoint returns 500 intermittently."
+- Investigating bugs, errors, test failures, or unexpected behaviour.
+## Workflow
+```
+1. mcp__opencodehub__detect_changes                              → Is this a recent regression?
+2. mcp__opencodehub__query({ query: "<error or symptom>" })      → Find code related to the symptom
+3. mcp__opencodehub__context({ name: "<suspect>" })              → Callers, callees, processes, cochanges
+4. mcp__opencodehub__sql for a process trace                     → Ordered PROCESS_STEP chain
+5. mcp__opencodehub__list_findings                               → SARIF findings that already flagged the area
+6. Read source files only after the graph has narrowed the suspect set
+```
+> If the context envelope warns the index is stale, run `codehub analyze` first — stale graphs point at the wrong suspect.
+## Checklist
+```
+- [ ] Capture the symptom (error text, stack frame, failing assertion, wrong output)
+- [ ] mcp__opencodehub__detect_changes({ scope: "unstaged" | "staged" })
+      — if non-empty, recent edits are the primary suspect
+- [ ] mcp__opencodehub__query for the error text or related concept
+- [ ] mcp__opencodehub__context on the suspect symbol
+- [ ] Read confidenceBreakdown — if unknown > 0, an LSP contradicted a heuristic edge;
+      the suspect may be a stale or dead reference
+- [ ] Review cochanges (git-history signal, NOT call deps) — files historically edited
+      together often point at the hidden collaborator
+- [ ] Trace the execution via mcp__opencodehub__sql on PROCESS_STEP edges
+- [ ] mcp__opencodehub__list_findings to see if a scanner already flagged the area
+- [ ] Read source to confirm root cause
+```
+## Debugging Patterns
+| Symptom              | OpenCodeHub path                                                           |
+| -------------------- | -------------------------------------------------------------------------- |
+| Error message        | `query` for the error text → `context` on every throw site it returned     |
+| Wrong return value   | `context` on the function → trace outgoing CALLS for the data flow         |
+| Intermittent failure | `context` → look for outgoing FETCHES (external I/O) + cochanges           |
+| Performance issue    | `impact` (downstream) → find symbols with many outbound CALLS (hot paths)  |
+| Recent regression    | `detect_changes` → symbols touched in the working tree or staged diff      |
+| Failing scanner gate | `list_findings({ severity: "error" })` → read the rule + the hit line      |
+## Tools
+### `mcp__opencodehub__query` — find code related to the error
+```
+mcp__opencodehub__query({ query: "payment validation error", repo })
+→ results: validatePayment, handlePaymentError, PaymentException
+→ processes: CheckoutFlow (populated when PROCESS_STEP edges exist)
+```
+### `mcp__opencodehub__context` — full context for a suspect
+```
+mcp__opencodehub__context({ name: "validatePayment", repo })
+→ incoming.CALLS: [processCheckout, webhookHandler]
+→ outgoing.CALLS: [verifyCard, fetchRates]          ← fetchRates is external I/O — likely culprit
+→ outgoing.FETCHES: [POST https://api.stripe.com/...]
+→ processes: [{process: "CheckoutFlow", step: 3}]
+→ confidenceBreakdown: {confirmed: 3, heuristic: 1, unknown: 0}
+→ cochanges: [src/payments/refund.ts (lift 4.2)]   (git history, NOT call deps)
+```
+The `cochanges` section frequently surfaces the hidden collaborator a heuristic call graph misses. Always label it as git-history signal so the user does not treat it as a dependency.
+### `mcp__opencodehub__sql` — custom call-chain trace
+Two-hop upstream trace for every caller of `validatePayment`:
+```sql
+WITH direct AS (
+  SELECT from_id, to_id, 1 AS depth
+  FROM relations
+  WHERE type = 'CALLS'
+    AND to_id IN (SELECT id FROM nodes WHERE name = 'validatePayment' AND kind = 'Function')
+),
+indirect AS (
+  SELECT r.from_id, d.to_id, 2 AS depth
+  FROM relations r
+  JOIN direct d ON d.from_id = r.to_id
+  WHERE r.type = 'CALLS'
+)
+SELECT caller.name, caller.file_path, caller.start_line, u.depth
+FROM (SELECT * FROM direct UNION ALL SELECT * FROM indirect) u
+JOIN nodes caller ON caller.id = u.from_id
+ORDER BY u.depth ASC, caller.name;
+```
+### `mcp__opencodehub__list_findings` — scanner hits in the suspect area
+```
+mcp__opencodehub__list_findings({
+  repo,
+  severity: "error",
+  path_prefix: "src/payments"
+})
+→ [{rule, severity, message, file, line, snippet}]
+```
+Use it early — a scanner often has the bug pre-labelled.
+## Example: "Payment endpoint returns 500 intermittently"
+```
+1. mcp__opencodehub__detect_changes({ scope: "staged", repo: "my-app" })
+   → empty. Not a recent regression.
+2. mcp__opencodehub__query({ query: "payment error handling", repo: "my-app" })
+   → results: validatePayment, handlePaymentError, PaymentException
+   → processes: [CheckoutFlow (7 steps), ErrorHandling (4 steps)]
+3. mcp__opencodehub__context({ name: "validatePayment", repo: "my-app" })
+   → outgoing.CALLS: [verifyCard, fetchRates]
+   → outgoing.FETCHES: [GET https://rates.example.com/v1/latest]   ← external I/O
+   → confidenceBreakdown: {confirmed: 3, heuristic: 0, unknown: 0}
+   → cochanges: [src/utils/http-client.ts (lift 5.1)]              ← investigate this file
+4. mcp__opencodehub__list_findings({
+     repo: "my-app",
+     path_prefix: "src/utils/http-client"
+   })
+   → security-rule "missing-request-timeout" at src/utils/http-client.ts:42 (error)
+5. Root cause: `fetchRates` uses a shared HTTP client with no timeout configured;
+   Stripe rate endpoint occasionally hangs, caller returns 500.
+```

package/dist/plugin-assets/skills/opencodehub-exploring/SKILL.md ADDED Viewed

@@ -0,0 +1,120 @@
+---
+name: opencodehub-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of a codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\", \"Where does the request enter the system?\"."
+---
+# Exploring Codebases with OpenCodeHub
+## When to Use
+- "How does authentication work?"
+- "What's the project structure?"
+- "Where is the database logic?"
+- "Show me the request lifecycle."
+- Onboarding to a codebase you have not seen before.
+## Workflow
+```
+1. mcp__opencodehub__list_repos                              → Pick the repo name
+2. READ codehub://repo/{name}/context                        → Stats + staleness envelope
+3. mcp__opencodehub__query({query: "<concept>", repo})       → Hybrid BM25 + vector hits, grouped by process
+4. mcp__opencodehub__context({name: "<symbol>", repo})       → 360-degree view, categorised edges, cochange side-section
+5. mcp__opencodehub__sql for process traces                  → Step ordering from the relations table
+6. Read source files only after the graph has pointed you at the hot spots
+```
+> If the context envelope warns the index is stale, run `codehub analyze` in the terminal first.
+## Checklist
+```
+- [ ] mcp__opencodehub__list_repos — confirm the repo
+- [ ] READ codehub://repo/{name}/context — check freshness
+- [ ] mcp__opencodehub__query for the concept
+- [ ] Scan returned processes (execution flows) before scanning files
+- [ ] mcp__opencodehub__context on the strongest hit
+- [ ] Inspect confidenceBreakdown — prefer confirmed edges for architectural claims
+- [ ] Review cochanges as a secondary signal (git history, NOT call deps)
+- [ ] Follow PROCESS_STEP edges via mcp__opencodehub__sql to trace the flow end-to-end
+- [ ] Read source files for implementation detail only
+```
+## Tools
+### `mcp__opencodehub__query` — hybrid BM25 + vector search, grouped by process
+```
+mcp__opencodehub__query({ query: "payment processing", repo: "my-app", limit: 20 })
+→ results: ranked symbols with file path, kind, score
+→ processes: execution flows that contain the top hits (populated when PROCESS_STEP edges exist)
+→ next_steps: pointer to the next tool
+```
+Use it as the first broad read after the context resource. Prefer it over Grep for concept-level questions.
+### `mcp__opencodehub__context` — 360-degree view of a symbol
+```
+mcp__opencodehub__context({ name: "validateUser", repo: "my-app" })
+→ target: {uid, kind, filePath, startLine}
+→ incoming: categorised by edge type (CALLS, REFERENCES, IMPORTS, METHOD_OVERRIDES, ...)
+→ outgoing: same, in the other direction
+→ processes: [{process, step}]
+→ cochanges: files historically edited with target's file (git history, NOT call deps)
+→ confidenceBreakdown: {confirmed, heuristic, unknown}
+```
+Always read `confidenceBreakdown` before making an architectural claim. If `confirmed` is zero and `unknown` is non-zero, the edges are contradicted by the LSP oracle — report that caveat.
+When a name is ambiguous, `context` returns a ranked candidate list instead of silently picking one. Disambiguate by passing `uid` (preferred) or `{name, file_path, kind}`.
+### `mcp__opencodehub__sql` — trace a named process end-to-end
+```sql
+SELECT r.step, callee.name, callee.file_path, callee.start_line
+FROM relations r
+JOIN nodes proc   ON proc.id = r.from_id
+JOIN nodes callee ON callee.id = r.to_id
+WHERE r.type = 'PROCESS_STEP'
+  AND proc.kind = 'Process'
+  AND proc.name = 'CheckoutFlow'
+ORDER BY r.step ASC;
+```
+## Cross-repo exploration
+When the concept crosses repo boundaries (e.g. a microservice calls another), use the group tools:
+- `mcp__opencodehub__group_list` — discover named groups.
+- `mcp__opencodehub__group_query({ group, query, limit })` — BM25 fan-out across every repo in the group, results tagged with `_repo`.
+- `mcp__opencodehub__group_contracts({ group })` — HTTP contract cross-links (consumer `FETCHES` edge → producer `Route`).
+## Example: "How does payment processing work?"
+```
+1. mcp__opencodehub__list_repos
+   → [{name: "my-app", root: "/Users/.../my-app", nodes: 918}]
+2. READ codehub://repo/my-app/context
+   → 918 symbols, 45 processes, index fresh.
+3. mcp__opencodehub__query({ query: "payment processing", repo: "my-app" })
+   → results: processPayment (Function, src/payments/processor.ts),
+              chargeStripe, validateCard, handleRefund
+   → processes: CheckoutFlow (step_count=7), RefundFlow (step_count=5)
+4. mcp__opencodehub__context({ name: "processPayment", repo: "my-app" })
+   → incoming.CALLS: [checkoutHandler, webhookHandler]
+   → outgoing.CALLS: [validateCard, chargeStripe, saveTransaction]
+   → processes: [{process: "CheckoutFlow", step: 3}]
+   → confidenceBreakdown: {confirmed: 4, heuristic: 1, unknown: 0}
+   → cochanges: [src/payments/refund.ts (lift 4.2), src/webhooks/stripe.ts (lift 3.1)]
+                (git history signal — files often edited together, NOT call deps.)
+5. mcp__opencodehub__sql to dump the ordered CheckoutFlow.
+6. Read src/payments/processor.ts for the actual implementation.
+```

package/dist/plugin-assets/skills/opencodehub-guide/SKILL.md ADDED Viewed

@@ -0,0 +1,180 @@
+---
+name: opencodehub-guide
+description: "Use when the user asks about OpenCodeHub itself — available MCP tools, resources, graph schema, or workflow reference. Examples: \"What OpenCodeHub tools are available?\", \"How do I query the code graph?\", \"Show me the schema\"."
+---
+# OpenCodeHub Guide
+Quick reference for every OpenCodeHub MCP tool, MCP resource, and the DuckDB-backed graph schema.
+## Always Start Here
+For any task that touches code understanding, debugging, impact analysis, refactoring, or PR review:
+1. Call `mcp__opencodehub__list_repos` — confirm the repo is indexed and pick a `repo` name.
+2. Read `codehub://repo/{name}/context` — codebase stats and a staleness envelope.
+3. Match the task to a skill below and follow that skill's checklist.
+> If the context envelope reports the index is stale, run `codehub analyze` in the terminal first. If it says weights are missing, run `codehub setup --embeddings` to fetch the 768d gte-modernbert-base ONNX weights.
+## Skills · analysis
+| Task                                          | Skill to read                 |
+| --------------------------------------------- | ----------------------------- |
+| Understand architecture / "How does X work?"  | `opencodehub-exploring`       |
+| Blast radius / "What breaks if I change X?"   | `opencodehub-impact-analysis` |
+| Trace bugs / "Why is X failing?"              | `opencodehub-debugging`       |
+| Rename / extract / split / restructure        | `opencodehub-refactoring`     |
+| Review a PR / "Is this safe to merge?"        | `opencodehub-pr-review`       |
+| Tools, resources, schema reference            | `opencodehub-guide` (here)    |
+## Skills · artifact factory (spec 001)
+These skills produce committed Markdown artifacts — the durable output
+Principal engineers ship. See [ADR 0007](../../../docs/adr/0007-artifact-factory.md)
+for the scope rationale.
+| Task                                          | Skill to invoke               | Trigger phrase                                  |
+| --------------------------------------------- | ----------------------------- | ----------------------------------------------- |
+| Generate the full doc tree (single or group)  | `codehub-document`            | "document this repo", "regenerate architecture docs" |
+| Draft a PR description from the current diff  | `codehub-pr-description`      | "write the PR description", "summarize this branch" |
+| Write an onboarding guide with reading order  | `codehub-onboarding`          | "write ONBOARDING.md", "what should a new hire read first" |
+| Map inter-repo contracts for a group          | `codehub-contract-map`        | "map the contracts", "show the contract matrix for <group>" |
+| Build a deterministic 9-item code-pack BOM    | `codehub-code-pack`           | "pack this repo for an LLM", "deterministic code pack", "pack the platform group" |
+| Draft an ADR (P1 — not yet shipped)           | `codehub-adr` *(P1 backlog)*  | —                                               |
+Fire these directly; do not nest them inside analysis skills. Each is a
+standalone artifact producer with its own preconditions and output path.
+## Tool Inventory (27 MCP tools)
+### Code intelligence (per-repo)
+| Tool                          | What it gives you                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `mcp__opencodehub__list_repos`        | Enumerate indexed repos on this machine                                   |
+| `mcp__opencodehub__query`             | Hybrid BM25 + vector search over symbols, grouped by process              |
+| `mcp__opencodehub__context`           | 360-degree symbol view + `confidenceBreakdown` + `cochanges` side-section |
+| `mcp__opencodehub__impact`            | Blast radius with risk tier + `confidenceBreakdown`                       |
+| `mcp__opencodehub__detect_changes`    | Map an uncommitted or committed diff to affected symbols and flows        |
+| `mcp__opencodehub__rename`            | Graph-assisted multi-file rename; dry-run by default                      |
+| `mcp__opencodehub__sql`               | Read-only DuckDB SQL against the graph (5 s timeout)                      |
+| `mcp__opencodehub__signature`         | Function signature lookup for a target symbol                             |
+### HTTP / RPC surface
+| Tool                          | What it gives you                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `mcp__opencodehub__route_map`         | HTTP route inventory (method, path, handler, middleware)                  |
+| `mcp__opencodehub__tool_map`          | MCP tool inventory exported by this repo                                  |
+| `mcp__opencodehub__shape_check`       | Producer/consumer response-shape mismatches                               |
+| `mcp__opencodehub__api_impact`        | HTTP consumer chain + middleware + affected processes for one route       |
+### Cross-repo (groups)
+| Tool                          | What it gives you                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `mcp__opencodehub__group_list`        | Discover named repo groups                                                |
+| `mcp__opencodehub__group_query`       | BM25 fan-out across a group with reciprocal-rank fusion                   |
+| `mcp__opencodehub__group_status`      | Per-repo staleness + contract freshness for a group                       |
+| `mcp__opencodehub__group_contracts`   | HTTP contract cross-links (consumer FETCHES edge → producer Route)        |
+### Supply-chain / PR review (OpenCodeHub differentiators)
+| Tool                             | What it gives you                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------ |
+| `mcp__opencodehub__verdict`              | 5-tier PR decision (`auto_merge` → `block`) with top drivers           |
+| `mcp__opencodehub__scan`                 | Run Priority-1 scanners (openWorld — spawns child processes)           |
+| `mcp__opencodehub__list_findings`        | Browse SARIF findings produced by `scan` or `ingest-sarif`             |
+| `mcp__opencodehub__list_findings_delta`  | Diff latest scan vs. frozen baseline (new / fixed / unchanged / updated) |
+| `mcp__opencodehub__list_dead_code`       | Unreferenced exported symbols                                          |
+| `mcp__opencodehub__remove_dead_code`     | Scripted removal of dead-code items (dry-run by default)               |
+| `mcp__opencodehub__license_audit`        | Copyleft / unknown / proprietary tier check over dependencies          |
+| `mcp__opencodehub__dependencies`         | External package list (ecosystem + version + manifest path)            |
+| `mcp__opencodehub__owners`               | File/symbol ownership from CODEOWNERS + git blame signal               |
+| `mcp__opencodehub__risk_trends`          | Per-community trend lines and 30-day projections                       |
+| `mcp__opencodehub__project_profile`      | High-level repo summary (languages, stacks, entry points)              |
+## Differentiators to surface in responses
+- **`confidenceBreakdown`** — every `context` and `impact` response carries a `{confirmed, heuristic, unknown}` tally. `confirmed` means a SCIP indexer (scip-typescript / scip-python / scip-go / rust-analyzer / scip-java) has confirmed the edge at confidence ≥ 0.95. `heuristic` is tree-sitter or tier-1/tier-2 inference the SCIP oracle has not confirmed. `unknown` is demoted (≤ 0.2) — a SCIP-confirmed edge exists at the same triple and the heuristic carries a `+scip-unconfirmed` reason suffix. Report this breakdown when an agent is about to take a destructive action based on edges.
+- **`cochanges` side-section** — `context` includes files historically co-edited with the target (by lift, from the dedicated `cochanges` table). This is a **git-history signal, not call dependencies** — label it that way when you report it. It is excluded from the graph hash.
+- **`verdict` + `list_findings` + `list_findings_delta`** — PR review grade is deterministic, not opinion.
+- **`license_audit`** + **`risk_trends`** + **`owners`** — first-class audit workflows without writing SQL.
+## Resource Inventory
+Lightweight reads for navigation (every URI uses the `codehub://` scheme):
+| Resource                                       | Content                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `codehub://repos`                              | Registry list: names, roots, graph hashes   |
+| `codehub://repo/{name}/context`                | Stats + staleness envelope                  |
+| `codehub://repo/{name}/schema`                 | Live node kinds / relation types for `sql`  |
+> Cluster and process navigation resources (`codehub://repo/{name}/clusters`, `codehub://repo/{name}/processes`, etc.) are slated for a later wave. Use `sql` against the `nodes` table filtered to `kind = 'Community'` or `kind = 'Process'` in the meantime.
+## Graph schema
+The graph is a DuckDB-backed store. One unified `nodes` table, one `relations` table, an `embeddings` table, a `cochanges` side table, and `store_meta`.
+**Node kinds** (load-bearing order — new kinds are appended):
+File, Folder, Function, Class, Method, Interface, Constructor, Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Variable, Property, Record, Delegate, Annotation, Template, Module, CodeElement, Community, Process, Route, Tool.
+**Relation types** (append-only):
+CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, PROCESS_STEP, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, REFERENCES, FOUND_IN, DEPENDS_ON, OWNED_BY.
+Cochange edges live in a **separate `cochanges` table**, NOT in `relations`. Do not query `relations` for them.
+## SQL cheat-sheet (use `mcp__opencodehub__sql`)
+All inbound callers of a function by name:
+```sql
+SELECT caller.name, caller.file_path, caller.start_line, r.confidence, r.reason
+FROM relations r
+JOIN nodes caller ON caller.id = r.from_id
+JOIN nodes callee ON callee.id = r.to_id
+WHERE r.type = 'CALLS'
+  AND callee.name = 'validateUser'
+  AND callee.kind = 'Function'
+ORDER BY r.confidence DESC
+LIMIT 50;
+```
+Top communities by cohesion:
+```sql
+SELECT name, inferred_label, cohesion, symbol_count, keywords
+FROM nodes
+WHERE kind = 'Community'
+ORDER BY cohesion DESC
+LIMIT 20;
+```
+Process entry points:
+```sql
+SELECT n.name, n.inferred_label, n.step_count, entry.name AS entry_point
+FROM nodes n
+LEFT JOIN nodes entry ON entry.id = n.entry_point_id
+WHERE n.kind = 'Process'
+ORDER BY n.step_count DESC;
+```
+SCIP-confirmed edges only (for strict impact queries):
+```sql
+SELECT from_id, to_id, type, reason
+FROM relations
+WHERE confidence >= 0.95
+  AND reason LIKE 'scip:%';
+```
+## Invariants agents must respect
+- Every per-repo tool accepts an optional `repo` argument. When exactly one repo is indexed, `repo` is optional. When two or more are indexed and `repo` is omitted, the tool returns `AMBIGUOUS_REPO` — pass `repo` explicitly.
+- Every response may carry `_meta.codehub/staleness` when the index is behind HEAD. Surface that to the user when it is present.
+- Every response includes a `next_steps` array under `structuredContent`. Use it to pick the next tool without guessing.
+- `rename` is dry-run by default — explicitly pass `dry_run: false` to apply edits.
+- `scan` has `openWorldHint: true` — it spawns child processes. Do not invoke it on every turn.