memtrace 0.7.25 → 0.8.1

package/installer/skills/commands/memtrace-impact.md

@@ -1,11 +1,15 @@
 ---
 name: memtrace-impact
-description: "Always use before or during source-code changes when the user asks about blast radius, impact, what breaks, risk, upstream callers, downstream dependencies, or consequences of modifying a symbol. Do not use Grep or manual reference search; Memtrace computes transitive graph impact."
+description: "Compute the blast radius of modifying a symbol through transitive graph impact. Use when the user asks about blast radius, impact, what breaks, risk, upstream callers, downstream dependencies, or consequences of modifying a symbol, before or during source-code changes. Do not use Grep or manual reference search; Memtrace computes transitive graph impact. For a full risk-rated plan covering a multi-part change, use memtrace-change-impact-analysis."
 allowed-tools:
   - mcp__memtrace__get_impact
   - mcp__memtrace__detect_changes
   - mcp__memtrace__find_symbol
   - mcp__memtrace__find_code
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -17,26 +21,47 @@ Compute the blast radius of changing a specific symbol. Traces upstream (what de
 
 | Tool | Purpose |
 |------|---------|
-| `get_impact` | Blast radius from a specific symbol (by ID) |
+| `get_impact` | Blast radius from a symbol **name** (`target`) |
 | `detect_changes` | Scope symbols affected by a diff/patch |
 
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`depth`, `limit`, etc.) must be JSON numbers — not strings.
 
+## Required parameters — `get_impact`
+
+| Parameter | Required | Default | Notes |
+|---|---|---|---|
+| `repo_id` | yes | — | |
+| `target` | yes | — | Symbol name (e.g. `"validateToken"`) — **not** `symbol_id` |
+| `direction` | no | `"both"` | `"upstream"` \| `"downstream"` \| `"both"` |
+| `depth` | no | `5` | BFS depth (max 15) |
+| `as_of` | no | now | ISO-8601 for time-travel |
+
+```json
+{ "repo_id": "memdb", "target": "validateToken", "direction": "both", "depth": 5 }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Identify the symbol
+### 1. Identify the symbol name
 
-If you have a symbol name but not its ID:
-- Use `find_symbol` for exact names
-- Use `find_code` for natural-language queries
+If you don't know the exact name:
+- `find_symbol(name="...")` for exact identifiers
+- `find_code(query="...")` for natural-language queries
+
+Use the returned **`name`** (and optional `file_path` hint) — graph tools resolve by name, not internal IDs.
 
 ### 2. Run impact analysis
 
-Use the `get_impact` MCP tool:
-- `symbol_id` — the symbol you plan to change (required)
-- `direction` — `upstream` (what depends on me), `downstream` (what I depend on), or `both` (default)
-- `depth` — traversal hops (default 3)
+```json
+{
+  "repo_id": "memdb",
+  "target": "validateToken",
+  "direction": "upstream",
+  "depth": 5
+}
+```
 
 ### 3. Interpret the risk rating
 
@@ -45,20 +70,43 @@ Use the `get_impact` MCP tool:
 | **Low** | Few dependents, leaf node | Safe to modify; minimal testing needed |
 | **Medium** | Moderate dependents | Test direct callers; review interface contracts |
 | **High** | Many dependents across modules | Coordinate changes; comprehensive test coverage |
-| **Critical** | Core infrastructure, many transitive dependents | Plan migration strategy; consider backward-compatible changes |
+| **Critical** | Core infrastructure, many transitive dependents | Plan migration strategy; backward-compatible changes |
 
 ### 4. For diff-based analysis
 
-When you have an actual code diff (not just a symbol), use `detect_changes`:
-- Scopes all symbols affected by the diff
-- Returns blast radius AND affected processes (execution flows)
-- Useful for PR reviews or pre-commit checks
+When you have an actual code diff, use `detect_changes`:
+
+```json
+{ "repo_id": "memdb", "diff": "<unified git diff text>" }
+```
+
+Or pass `changed_files: ["path/a.rs", "path/b.ts"]` when no diff text is available.
 
 ## Decision Points
 
 | Situation | Action |
 |-----------|--------|
-| Changing a single function | `get_impact` with `direction: both` |
+| Changing a single function | `get_impact` with `direction: "both"` |
 | Reviewing a PR or diff | `detect_changes` with the diff content |
-| Renaming/removing a public API | `get_impact` with `direction: upstream`, high depth |
-| Refactoring internals | `get_impact` with `direction: downstream` to check what you depend on |
+| Renaming/removing a public API | `get_impact` with `direction: "upstream"`, higher `depth` |
+| Refactoring internals | `get_impact` with `direction: "downstream"` |
+
+## Output
+
+`get_impact` returns the blast radius for the target symbol:
+
+| Field | Example / meaning |
+|---|---|
+| Risk rating | `High` — one of `Low` / `Medium` / `High` / `Critical` (interpret via step 3) |
+| Upstream | Transitive dependents (callers/importers) within `depth` hops — what breaks if the target changes |
+| Downstream | Transitive dependencies — what the target relies on |
+
+`detect_changes` returns the set of symbols affected by the supplied `diff` / `changed_files`, plus the affected processes (execution flows).
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Passing `symbol_id` or `name` | Required param is **`target`** |
+| Omitting `repo_id` | Both `repo_id` and `target` are required |
+| Defaulting `depth` to 3 | API default is **5** |

package/installer/skills/commands/memtrace-index.md

@@ -1,11 +1,15 @@
 ---
 name: memtrace-index
-description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
+description: "Index a source-code repo into the Memtrace knowledge graph and poll the job to completion. Use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed. For ongoing watch mode / live re-indexing after the initial index, use memtrace-continuous-memory."
 allowed-tools:
   - mcp__memtrace__index_directory
   - mcp__memtrace__check_job_status
   - mcp__memtrace__list_jobs
   - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -23,6 +27,8 @@ Index a local codebase into the persistent code knowledge graph. This is always
 
 > **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 
 ## Steps
 
@@ -49,7 +55,7 @@ Use the `index_directory` MCP tool:
 
 ### 3. Poll for completion
 
-Use `check_job_status` with the `job_id` every 2–3 seconds.
+Use `check_job_status` with the `job_id` every 2–3 seconds. **The loop must never run unbounded** — hard cap at ~100 polls (~5 minutes). On hitting the cap: stop polling, report the `job_id` and last observed status to the user, and tell them the job keeps running server-side — they (or you, later) can resume with `check_job_status` on that `job_id` or find it via `list_jobs`.
 
 Pipeline stages in order: **scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done**
 
@@ -67,5 +73,16 @@ After indexing completes, call `list_indexed_repositories` to confirm the repo a
 |-------|--------|
 | Path does not exist | Ask user to verify the absolute path |
 | Job status "failed" | Report the error message; suggest `clear_existing: true` for a fresh rebuild |
-| Timeout (job running > 5 min) | Large repos are normal; keep polling. For monorepos, index subdirectories separately |
+| Timeout (job running > 5 min) | Large repos are normal, but respect the poll cap: stop, report `job_id` + last status, resume later via `check_job_status` / `list_jobs`. For monorepos, index subdirectories separately |
 | Already indexed | Use `incremental: true` to update, or skip indexing entirely |
+
+## Output
+
+`index_directory` returns a job handle immediately; `check_job_status` tracks it to a terminal state:
+
+```json
+{ "job_id": "6f9a2c1e-...-uuid" }
+{ "status": "completed" }
+```
+
+While running, the job advances through the pipeline stages listed in step 3; `status = "failed"` carries an error message. The final user-facing report (confirmed via `list_indexed_repositories`) covers: `repo_id`, languages detected, total symbols, total relationships (node/edge counts).

package/installer/skills/commands/memtrace-intent-verification.md

@@ -0,0 +1,81 @@
+---
+name: memtrace-intent-verification
+description: "Verify whether a past decision actually held or was violated, and surface the arc of episodes that implemented that specific decision. Returns a Held | ViolatedAt | CannotProve verdict and the implementing arc from Cortex decision memory. Use when the user asks whether a decision held, was followed, or drifted, or before relying on a decision or reporting drift. Requires a decision_id (from memtrace-decision-recall); do NOT use for free-text decision lookup — use memtrace-decision-recall first. Do not assume a decision was followed; verify it."
+allowed-tools:
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__get_arc
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__why_is_this_here
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+A decision being *recorded* doesn't mean it was *followed*. `verify_intent` checks
+whether a decision held across its arc; `get_arc` returns the episodes that implemented
+it. Use these to confirm a rationale is still in force before relying on it, and to
+detect drift where the code quietly diverged from what was decided.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Quick Reference
+
+| Tool | Purpose | Returns / FactStatus |
+|------|---------|----------------------|
+| `verify_intent` | Did the decision hold across its arc? | `Held` \| `ViolatedAt` \| `CannotProve` |
+| `get_arc` | Arc of episodes implementing the decision | DeterministicallyDerived \| CannotProve |
+
+> **Both take a `decision_id` (uint64), not free text.** Get it from `recall_decision`
+> (see `memtrace-decision-recall`) or from `why_is_this_here` (see `memtrace-provenance`).
+> Do not invent ids.
+
+> **Honesty contract:** verdicts are deterministically defended. `CannotProve` means the
+> decision is invisible or has no implementing episode — *unknown*, not "fine."
+
+## Steps
+
+### 1. Get the decision_id
+
+Run `recall_decision(...)` and take a `decision_id` from a hit, or get one from
+`why_is_this_here(symbol_id)`. These tools do not accept names.
+
+### 2. Verify it held
+
+`verify_intent(decision_id)`:
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| **Held** | The decision held across its arc | Safe to rely on; honor it |
+| **ViolatedAt** | The code drifted from the decision at a point | Surface the drift — it's either a bug or an unrecorded reversal; ask which |
+| **CannotProve** | Decision invisible or no implementing episode | Treat as unknown; don't claim it held |
+
+### 3. Inspect what implemented it
+
+`get_arc(decision_id)` → the episodes reachable by Produced/DerivedFrom edges. This is
+the implementation trail: where the decision actually landed (or where it should have).
+
+### 4. Cross to the code graph for the "what"
+
+The arc names episodes/symbols; to see the current code or its blast radius, hand those
+over to `memtrace-first` / `memtrace-impact`. Decision memory proves *whether it held*;
+the code graph shows *the current state*.
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Relying on a recalled decision for a choice | `verify_intent` first — only trust a `Held` verdict |
+| Auditing whether the codebase follows its own decisions | `verify_intent` per decision; report every `ViolatedAt` |
+| "Where/when was decision D implemented?" | `get_arc(decision_id)` |
+| `verify_intent` returns `ViolatedAt` | Don't silently 'fix' it — it may be a deliberate (unrecorded) reversal; confirm with the user |
+| `verify_intent` returns `CannotProve` | Treat as unknown; fall back to `recall_decision` + the code graph |
+
+## Output
+
+| Call | Returns |
+|------|---------|
+| `verify_intent(decision_id)` | Verdict: `Held` \| `ViolatedAt` (the point where code drifted from the decision) \| `CannotProve` (decision invisible or no implementing episode — unknown, not "fine") |
+| `get_arc(decision_id)` | FactStatus `DeterministicallyDerived` \| `CannotProve`, plus the implementing arc: the episodes reachable by Produced/DerivedFrom edges |

package/installer/skills/commands/memtrace-preflight.md

@@ -0,0 +1,85 @@
+---
+name: memtrace-preflight
+description: "Run a one-call pre-flight check on a single existing symbol before editing it: blast radius (who depends on it), co-change partners (files that historically change with it), complexity, 30-day churn, and a generated verification checklist. Use before modifying any existing function or symbol you did not just write. Do not start editing a non-trivial existing function without a pre-flight check; Memtrace knows the dependency graph and change history. For a full multi-symbol change plan or what-will-break analysis, use memtrace-change-impact-analysis."
+allowed-tools:
+  - mcp__memtrace__preflight_check
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_cochange_context
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+user-invocable: true
+---
+
+## Overview
+
+Pre-flight check: the two minutes before an edit that prevent the bug. One
+`preflight_check` call composes the dependency graph, the bi-temporal change
+history, and the complexity metrics into an actionable radar for a single
+symbol.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `preflight_check` | Full radar for one symbol: blast radius + co-change + churn + checklist |
+| `get_impact` | Deeper blast-radius walk when the radar flags HIGH/CRITICAL |
+| `get_cochange_context` | Wider co-change window when partners look surprising |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers must be
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+> JSON numbers — not strings.
+
+## Steps
+
+### 1. Run the pre-flight check before touching the symbol
+
+`preflight_check` with:
+- `repo_id` — required
+- `symbol` — the function/method name you are about to modify
+
+### 2. Read the checklist — it is generated from the graph, not boilerplate
+
+Each line names something concrete to verify:
+- *"N symbols depend on this"* → run `get_impact` again after your edit and
+  compare `total_affected`; new dependents mean your change leaked wider
+  than intended.
+- *"hotspot: N changes in 30 days"* → keep the edit small and reviewable;
+  hot code punishes large diffs.
+- *"sits in N process flow(s)"* → check the process steps still order
+  correctly after the change.
+- *"last touched by agent session …"* → read the latest episode before
+  assuming the current shape is intentional.
+
+### 3. Treat co-change partners as part of the change
+
+Files that historically changed together with the target usually need
+updating in the same change. If you finish the edit without touching a
+frequent partner, say so explicitly and why.
+
+### 4. After the edit, close the loop
+
+- Re-run `preflight_check` (or `get_impact`) on the symbol.
+- The complexity number should not have grown without a stated reason;
+  if it did, simplify before declaring the work done.
+
+## Verdict guidance
+
+- `risk: CRITICAL/HIGH` — propose the change plan before editing; consider
+  a feature flag or staged rollout.
+- `dependents: 0` — edit freely; note the symbol may be newly added or an
+  entry point.
+
+## Output
+
+`preflight_check` returns one radar for the symbol:
+
+| Field | Meaning |
+|-------|---------|
+| `risk` | verdict, e.g. `HIGH` / `CRITICAL` (see Verdict guidance) |
+| `dependents` | blast radius — count of symbols that depend on the target |
+| co-change partners | files that historically change with it (step 3) |
+| complexity + 30-day churn | current complexity score and recent change count |
+| checklist | generated verification lines, e.g. `"hotspot: 6 changes in 30 days"`, `"sits in 2 process flow(s)"` |

package/installer/skills/commands/memtrace-provenance.md

@@ -0,0 +1,90 @@
+---
+name: memtrace-provenance
+description: "Retrieve the governing decision lineage (why is this here) and the contracts that bind a symbol, from Cortex decision memory. Use before deleting, rewriting, or 'cleaning up' code that looks unused, odd, or redundant, and when the user asks why a symbol exists or what rules constrain it. Symbol-scoped; for free-text decision search use memtrace-decision-recall. Do not infer intent from the diff or assume unfamiliar code is safe to remove."
+allowed-tools:
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__recall_decision
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+Provenance answers **"why is this code here, and what binds it?"** before you change
+it. `why_is_this_here` returns the decision/conversation lineage that governs a symbol
+(its Governs/Produced provenance); `governing_contracts` returns the contract nodes
+that constrain it. Together they stop you from deleting code that closes a past issue
+or violating an invariant nothing in the AST advertises.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Quick Reference
+
+| Tool | Purpose | Returns / FactStatus |
+|------|---------|----------------------|
+| `why_is_this_here` | The governing decision/conversation lineage of a symbol | DeterministicallyDerived \| CannotProve |
+| `governing_contracts` | The contract nodes that constrain a symbol | Contract nodes \| CannotProve |
+| `verify_intent` | Given a returned governing `decision_id` — is that rationale still valid? | Held \| ViolatedAt \| CannotProve |
+
+> **`why_is_this_here` and `governing_contracts` each take a `symbol_id` (uint64 node
+> id), not a name. `verify_intent` takes a `decision_id` (uint64), not a `symbol_id`.**
+> If you only have a name or a question, start with `recall_decision` (free text) — see
+> `memtrace-decision-recall`. ids come from a prior recall/arc result or the Cortex
+> view. Do not invent ids.
+
+> **Honesty contract:** for a symbol no decision produced, `why_is_this_here` returns an
+> honest **CannotProve**; `governing_contracts` returns CannotProve rather than a false
+> "no contracts" verdict. **CannotProve ≠ safe to delete / unconstrained** — it means
+> *unknown*, so fall back to blast-radius and the user.
+
+## Steps
+
+### 1. Get the symbol_id
+
+If you have a name or a "why" question, run `recall_decision(...)` first and take the
+`symbol_id` from the result (or the Cortex view). The id-based tools need a numeric id.
+
+### 2. Ask why it's here
+
+`why_is_this_here(symbol_id)` → the governing decision lineage. This is the *rationale*
+the git blame won't give you: the decision that produced this code and, often, the
+problem it was put there to solve.
+
+### 3. Ask what constrains it
+
+`governing_contracts(symbol_id)` → contracts that must survive any rewrite (invariants,
+interface promises, "must always …" rules). A refactor that breaks one of these is a
+regression even if every test passes.
+
+### 4. Check the rationale still holds
+
+If `why_is_this_here` returns a governing `decision_id`, run `verify_intent(decision_id)`
+(see `memtrace-intent-verification`) — a `ViolatedAt` verdict (or a decision you can see
+was superseded via `recall_decision`) changes whether the code should still look this way.
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Code looks unused/dead and you want to delete it | `why_is_this_here` + `governing_contracts` BEFORE deleting; CannotProve is not a green light |
+| Code is written in a strange/non-obvious way | `why_is_this_here` — there's likely a decision explaining the oddity |
+| About to refactor a symbol's internals | `governing_contracts` — preserve every constraint, not just the test surface |
+| User asks "why is this here?" | `why_is_this_here(symbol_id)`; if you only have a name, `recall_decision` first |
+| All provenance returns CannotProve | Treat as unknown; combine with `memtrace-impact` (blast radius) and ask the user before removing |
+
+## Output
+
+```text
+why_is_this_here(symbol_id: 4821)
+→ DeterministicallyDerived — governing lineage:
+   decision_id 913 (Governs): "Keep retry shim until legacy clients migrate"
+governing_contracts(symbol_id: 4821)
+→ contract node: "writes must always be debounced" (must survive any rewrite)
+— no decision produced the symbol → CannotProve (unknown, NOT unconstrained)
+```
+
+`verify_intent(decision_id)` on a returned lineage id yields Held | ViolatedAt | CannotProve.

package/installer/skills/commands/memtrace-quality.md

@@ -1,69 +1,86 @@
 ---
 name: memtrace-quality
-description: "Always use for source-code quality, dead code, unused functions, zero callers, complexity, cyclomatic complexity, hotspots, refactoring candidates, or code smell questions. Do not use Grep, Glob, rg, or manual reference search for unused code; Memtrace uses graph reachability and complexity metrics."
+description: "Find dead code, complexity hotspots, and refactoring candidates in indexed source code. Use when the user asks about source-code quality, dead code, unused functions, zero callers, complexity, cyclomatic complexity, hotspots, refactoring candidates, or code smell questions. Do not use Grep, Glob, rg, or manual reference search for unused code; Memtrace uses graph reachability and complexity metrics."
 allowed-tools:
   - mcp__memtrace__find_dead_code
   - mcp__memtrace__calculate_cyclomatic_complexity
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__get_repository_stats
+  - mcp__memtrace__get_evolution
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Identify code quality issues using structural graph analysis — dead code (zero callers), complexity hotspots (high out-degree), and repository-wide statistics.
+Code quality via graph analysis — dead code, complexity hotspots, repository stats.
 
 ## Quick Reference
 
-| Tool | Purpose |
-|------|---------|
-| `find_dead_code` | Symbols with zero callers (potentially unused) |
-| `calculate_cyclomatic_complexity` | Complexity score for a specific symbol |
-| `find_most_complex_functions` | Top-N functions by complexity across the repo |
-| `get_repository_stats` | Repo-wide counts: nodes, edges, communities, processes |
+| Tool | Purpose | Required | Key optional |
+|------|---------|----------|--------------|
+| `find_dead_code` | Zero-caller symbols | `repo_id` | `include_tests`, `limit`, `kinds[]` |
+| `find_most_complex_functions` | Ranked complexity hotspots | `repo_id` | **`top_n`** (def 20) — not `limit` |
+| `calculate_cyclomatic_complexity` | Score one symbol | `repo_id`, **`target`** | — |
+| `get_repository_stats` | Repository overview | `repo_id` | `branch` |
 
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+> **Parameter types:** numbers must be JSON numbers — `limit: 20`, never `"20"` (MCP error -32602).
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Get repository overview
+### 1. Repository overview
 
-Use `get_repository_stats` to understand the codebase scale:
-- Node counts by kind (functions, classes, methods, interfaces)
-- Edge counts (calls, imports, extends, type references)
-- Community and process counts
+```json
+{ "repo_id": "memdb" }
+```
 
-### 2. Find dead code
+### 2. Dead code
 
-Use `find_dead_code`:
-- `repo_id` — required
-- `include_tests` — set true to also flag unused test helpers (default false)
+```json
+{ "repo_id": "memdb", "include_tests": false, "limit": 50 }
+```
 
-**Note:** Exported symbols and entry points are excluded by default — the tool won't flag public APIs as "dead" just because they're called externally.
+Exported symbols and entry points excluded by default. Results are candidates, not proof — callers via dynamic dispatch or reflection are invisible to the graph; verify before deleting.
 
-### 3. Find complexity hotspots
+### 3. Complexity hotspots
 
-Use `find_most_complex_functions`:
-- `repo_id` — required
-- `limit` — how many to return (default 10)
+```json
+{ "repo_id": "memdb", "top_n": 10 }
+```
+
+Ordered by call-graph out-degree.
 
-Complexity scoring (based on out-degree — number of callees):
 | Score | Rating | Action |
 |-------|--------|--------|
-| < 5 | Low | No action needed |
-| 5–10 | Medium | Monitor; consider splitting if growing |
-| 10–20 | High | Refactoring candidate; extract helper functions |
-| > 20 | Critical | Immediate attention; this function does too much |
+| <5 | Low | Fine |
+| 5-10 | Medium | Consider simplifying |
+| 10-20 | High | Refactor candidate |
+| >20 | Critical | Refactor priority |
+
+### 4. Single symbol complexity
+
+```json
+{ "repo_id": "memdb", "target": "processOrder" }
+```
 
-### 4. Drill into specific functions
+## Output
 
-Use `calculate_cyclomatic_complexity` on specific symbols flagged by the user or found in step 3.
+| Result | Carries |
+|--------|---------|
+| Dead-code entry (`find_dead_code`) | Symbol name + kind with zero graph callers — e.g. `format_legacy` (Function) |
+| Complexity row (`find_most_complex_functions`) | Symbol, complexity score, risk level — e.g. `processOrder` — 27, Critical |
+| Single score (`calculate_cyclomatic_complexity`) | Cyclomatic complexity for `target` |
+| Stats (`get_repository_stats`) | Node counts by kind, edge counts, community and process counts for `repo_id`/`branch` |
 
 ## Common Mistakes
 
 | Mistake | Reality |
 |---------|---------|
-| Treating all dead code as deletable | Some "dead" code is called via reflection, dynamic dispatch, or external consumers |
-| Ignoring exported symbols in dead code results | If `include_tests: false`, exported symbols are already excluded |
+| `find_most_complex_functions(limit: 10)` | Param is **`top_n`** |
+| `calculate_cyclomatic_complexity(symbol_id=...)` | Required param is **`target`** |
 | Only looking at the highest complexity | Medium-complexity functions that are growing (check `get_evolution`) are often more urgent |