memtrace 0.7.25 → 0.8.0

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

@@ -1,135 +1,168 @@
 ---
 name: memtrace-evolution
-description: "Always use for source-code change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timeline questions. Do not use git log, git diff, Grep, or manual file search to reconstruct history; Memtrace has symbol-level temporal memory."
+description: "Trace source-code change history from Memtrace's symbol-level temporal memory. Use when the user asks about change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timelines. Do not use git log, git diff, Grep, or manual file search to reconstruct history. Do NOT use for current-state architecture overviews (use memtrace-codebase-exploration) or for replaying one commit/save's graph diff (use memtrace-episode-replay)."
 allowed-tools:
   - mcp__memtrace__get_evolution
   - mcp__memtrace__get_timeline
   - mcp__memtrace__detect_changes
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__get_changes_since
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__get_episode_replay
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Multi-mode temporal analysis engine that answers "what changed and why should I care?" across arbitrary time windows. Uses Structural Significance Budgeting (SSB) to surface the most important changes without overwhelming you with noise.
+Temporal analysis for "what changed in this repo between two points in time?" Works on both git commits and uncommitted working-tree saves.
 
-This is memtrace's most powerful analytical tool. It implements six distinct scoring algorithms — choose the right one based on what the user needs.
+## Required parameters — read before calling
 
-## Query Modes — Choose the Right Algorithm
+`get_evolution` **always** requires `repo_id` and `from`. There is no `days` parameter.
 
-| Mode | Algorithm | Best For |
-|------|-----------|----------|
-| `compound` | Rank-fusion: 0.50×impact + 0.35×novel + 0.15×recent | **Default.** General-purpose "what changed?" — use when unsure |
-| `impact` | Structural Significance: `sig(n) = in_degree^0.7 × (1 + out_degree)^0.3` | "What broke?" — finds changes with the largest blast radius |
-| `novel` | Change Surprise Index: `surprise(n) = (1 + in_degree) / (1 + change_freq_90d)` | "What's unexpected?" — anomaly detection for rarely-changing code |
-| `recent` | Temporal Proximity: `impact × exp(−0.5 × Δhours)` | "What changed near the incident?" — time-weighted for root cause |
-| `directional` | Asymmetric scoring (added→out_degree, removed→in_degree, modified→impact) | "What was added vs removed?" — structural change direction |
-| `overview` | Fast module-level rollup only | Quick summary — no per-symbol scoring, just module counts |
+| Parameter | Required | Type | Example |
+|---|---|---|---|
+| `repo_id` | yes | string | `"memdb"` |
+| `from` | yes | string | `"90d ago"`, `"2026-04-01T00:00:00Z"`, `"yesterday"` |
+| `to` | no | string | defaults to now; set to incident time when investigating |
+| `mode` | no | string | `"recent"` (default), `"compound"`, `"summary"`, `"overview"` |
+| `target` | no | string | symbol name or file path substring to scope results |
+| `branch` | no | string | branch filter |
 
-> **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 (`limit`, `cursor`, etc.) must be JSON numbers — not strings. Use `limit: 100`, never `limit: "100"`.
 
+### Time-window parameters — do not confuse these tools
 
-## Steps
-
-### 1. Determine the time window
-
-Ask the user or infer:
-- `from` — ISO-8601 start timestamp (required)
-- `to` — ISO-8601 end timestamp (defaults to now)
-- `repo_id` — scope to a repo (call `list_indexed_repositories` if unknown)
+| Tool | Time param | Example | Notes |
+|---|---|---|---|
+| `get_evolution` | **`from`** (required) | `"90d ago"` | optional `to`; **never** pass `days` |
+| `get_changes_since` | **`since`** (required) | `"2026-04-13T10:43:00Z"` | optional `until` |
+| `replay_history` | **`days`** (optional) | `90` | re-walks git history — different tool entirely |
 
-### 2. Choose the mode
+Common failure: `MCP error -32602: missing field 'from'` — you omitted `from` or passed `days` instead.
 
-**Decision tree:**
+```json
+// CORRECT — 90-day overview
+{ "repo_id": "memdb", "from": "90d ago", "mode": "overview" }
 
+// WRONG — days is not a get_evolution parameter
+{ "repo_id": "memdb", "days": 90, "mode": "overview" }
 ```
-User wants to know...
-├── "what changed?"           → compound (default)
-├── "what could have broken?" → impact
-├── "anything unexpected?"    → novel
-├── "what changed near X?"    → recent (set to to incident time)
-├── "what was added/removed?" → directional
-└── "quick summary?"          → overview
-```
-
-### 3. Execute the query
 
-Use the `get_evolution` MCP tool with:
-- `repo_id` — required
-- `from` / `to` — the time window
-- `mode` — one of: compound, impact, novel, recent, directional, overview
+## Query modes — only these four exist
 
-### 4. Interpret results
+| Mode | What you get | Best for |
+|---|---|---|
+| `recent` | Per-episode list with nodes/edges added/removed; paginate with `limit` + `cursor` | Incident timelines, walking commit-by-commit |
+| `compound` | Totals plus `top_changed_files` and `top_touched_symbols` | "What changed?" when you need hotspots |
+| `summary` | Totals plus `first_episode` / `last_episode` metadata | Cheapest window check |
+| `overview` | Alias for `summary` | Same as `summary` |
 
-The response contains:
+Modes **`impact`**, **`novel`**, and **`directional`** are **not implemented** — calling them returns `unknown mode`.
 
-- **`added[]`** — new symbols that appeared in the time window
-- **`removed[]`** — symbols that were deleted
-- **`modified[]`** — symbols that changed
-- **`by_module[]`** — module-level rollup (NEVER truncated — always shows all modules)
-- **`significance_coverage`** — fraction of total significance captured (target: ≥0.80)
-- **`budget_exhausted`** — if true, there were more significant changes than the budget allowed
+### `recent` mode filters (ignored by `compound` / `summary`)
 
-Each symbol includes: `name`, `kind`, `file_path`, `scope_path`, `in_degree`, `out_degree`, and all four scores (`impact`, `novel`, `recent`, `compound`).
+| Param | Purpose |
+|---|---|
+| `file_path` | substring match against episode `touched_files` |
+| `kind` | `"git_commit"` or `"working_tree"` |
+| `limit` | page size (default 100 episodes) |
+| `cursor` | pagination offset; follow `next_cursor` in response |
 
-### 5. Drill deeper
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-- **For a single symbol's full history:** Use `get_timeline` with the symbol name
-- **For diff-based change scope:** Use `detect_changes` when you have a specific diff/patch
-- **For blast radius of a specific change:** Use `get_impact` on high-scoring symbols
+## Steps
 
-## Scoring Algorithms — Detailed Reference
+### 1. Get `repo_id`
 
-### Impact Score (Structural Significance Budgeting)
 ```
-sig(n) = in_degree^0.7 × (1 + out_degree)^0.3
+list_indexed_repositories()
 ```
-- Heavily weights callers (in_degree) — symbols called by many others have high blast radius
-- Mild boost for outbound complexity (out_degree) — complex functions that changed are notable
-- SSB selects the minimum set covering ≥80% of total significance mass
 
-### Novelty Score (Change Surprise Index)
-```
-surprise(n) = (1 + in_degree) / (1 + change_freq_90d)
-```
-- High in_degree + low change frequency = **maximum surprise**
-- A core utility that hasn't changed in 90 days suddenly changing → likely worth investigating
-- Low in_degree + high frequency = routine churn, deprioritized
+### 2. Choose the time window
+
+- `from` — start (required). Relative strings work: `"7d ago"`, `"24 hours ago"`.
+- `to` — end (optional, defaults to now). Set to the incident timestamp when investigating regressions.
+
+If resuming a session and you have a stored timestamp from last time, prefer `get_changes_since(since=...)` — see `memtrace-session-continuity`.
+
+### 3. Choose the mode
 
-### Recent Score (Temporal Proximity Weighting)
 ```
-recent(n) = impact(n) × exp(−0.5 × |Δhours to reference|)
+User wants...
+├── per-commit / per-save changelog     → recent
+├── top changed files + symbols         → compound
+├── quick totals only                   → summary or overview
+└── one symbol's full history           → get_timeline (not get_evolution)
 ```
-- Exponential decay from the reference timestamp (the `to` parameter)
-- Changes close to an incident get amplified; older changes fade
-- Best for incident timelines: set `to` to the incident timestamp
 
-### Compound Score (Rank Fusion)
-```
-compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
+### 4. Execute
+
+```json
+// General "what changed lately?"
+{ "repo_id": "memdb", "from": "30d ago", "mode": "compound" }
+
+// Changes in one file last week
+{ "repo_id": "memdb", "from": "7d ago", "mode": "recent", "file_path": "auth.ts", "limit": 50 }
+
+// Incident: 24h before failure until failure time
+{ "repo_id": "memdb", "from": "2026-04-16T13:00:00Z", "to": "2026-04-17T13:00:00Z", "mode": "recent" }
 ```
-- Rank-based fusion avoids scale sensitivity between different score types
-- Impact-dominant but boosted by novelty and recency
-- Best default when you don't have a specific hypothesis
 
-## Auto-overview Safety
+### 5. Interpret results
+
+**`recent` mode** — each entry in `episodes[]`:
+- `episode` — metadata (`source_type`, `reference_time`, `touched_files`, …)
+- `nodes_added`, `nodes_removed`, `edges_added`, `edges_removed`
+
+**`compound` mode:**
+- `totals` — aggregate counts
+- `top_changed_files` — files with most activity
+- `top_touched_symbols` — symbols with most activity
 
-If a time window produces more than 500 candidates and mode is not `overview`, the query **automatically downgrades to overview mode** and returns `auto_overview: true`. This prevents timeouts on wide windows. When you see `auto_overview: true`:
-- Narrow the window, OR
-- Switch to `get_changes_since` (which handles this automatically), OR
-- Use the `by_module` rollup to identify the specific area and query a tighter window
+**`summary` / `overview` mode:**
+- `totals` — episode and node/edge counts
+- `first_episode`, `last_episode` — window boundaries
 
-## Session-Aware Alternative
+### 6. Drill deeper
+
+| Need | Tool |
+|---|---|
+| Full history of one symbol | `get_timeline(repo_id, scope_path, file_path)` |
+| Blast radius of a suspect symbol | `get_impact(repo_id, target)` |
+| What a diff would affect | `detect_changes(repo_id, diff=...)` |
+| Behavioral coupling | `get_cochange_context(repo_id, target=<symbol>)` |
+| Sub-commit tried-and-reverted history | `get_episode_replay` |
+
+## Output
+
+Sample `compound` payload (per-mode field lists: step 5 above):
+
+```json
+{
+  "totals": { "episodes": 42, "nodes_added": 310, "nodes_removed": 95,
+              "edges_added": 541, "edges_removed": 120 },
+  "top_changed_files":   [ /* files ranked by activity */ ],
+  "top_touched_symbols": [ /* symbols ranked by activity */ ]
+}
+```
 
-If you're resuming work after a break and don't know the right `from` timestamp, use `get_changes_since` instead — it accepts a `last_episode_id` anchor and never requires timestamp guessing.
+`recent` returns `episodes[]` + `totals` + `page.next_cursor`; `summary`/`overview` return `totals` + `first_episode`/`last_episode`.
 
-## Common Mistakes
+## Common mistakes
 
 | Mistake | Reality |
-|---------|---------|
-| Using `overview` when user needs details | Overview only gives module-level counts — use `compound` for symbol-level |
-| Ignoring `budget_exhausted` flag | If true, there are more significant changes beyond what was returned — narrow the time window or use module rollup |
-| Not checking `by_module` first | Module rollup is never truncated — scan it to identify which areas changed before diving into symbol-level |
-| Using `recent` without setting `to` | The `to` timestamp is the reference point for proximity weighting — set it to the incident/event time |
-| Guessing timestamps when resuming work | Use `get_changes_since` with a stored `session_anchor` instead — exact episode boundary, no guessing |
+|---|---|
+| Passing `days: 90` | Use `from: "90d ago"` — `days` is only on `replay_history` |
+| Omitting `from` | Required — call fails with `-32602` before any query runs |
+| Using `mode: "novel"` / `"impact"` / `"directional"` | Not implemented — use `compound` + `get_impact` + `get_cochange_context` instead |
+| Expecting `by_module[]` or significance scores | Not in current response shape — use `top_changed_files` from `compound` |
+| Using `overview` when you need file/symbol detail | `overview`/`summary` are totals only — switch to `compound` or `recent` |
+| Using `get_evolution` for one symbol's history | Use `get_timeline` |
+| Guessing timestamps when resuming work | Use `get_changes_since(since=<stored time>)` — see `memtrace-session-continuity` |
+| Applying `file_path` filter in `compound` mode | Filters are ignored in roll-up modes — use `recent` with `file_path` instead |

package/installer/skills/commands/memtrace-fleet-publish-intent.md

@@ -1,9 +1,14 @@
 ---
 name: memtrace-fleet-publish-intent
-description: "Use to declare a structural intent BEFORE editing in a fleet — what symbols you'll touch and why — so other agents on your branch coordinate around you. Triggered by: 'I'm about to edit/rename/refactor X', starting any non-trivial edit while other agents share your repo+branch. Returns the graph blast radius, overlapping live intents on your branch, and a shift-left coordination/partition hint. Do not start editing shared symbols without publishing first."
+description: "Declare a structural intent BEFORE editing in a fleet — what symbols you'll touch and why — so other agents on your branch coordinate around you. Use when the user says 'I'm about to edit/rename/refactor X', or when starting any non-trivial edit while other agents share your repo+branch. Returns the graph blast radius, overlapping live intents on your branch, and a shift-left coordination/partition hint. Do not start editing shared symbols without publishing first."
 allowed-tools:
   - mcp__memtrace__fleet_publish_intent
   - mcp__memtrace__fleet_preflight
+  - mcp__memtrace__fleet_record_episode
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 ## Overview
@@ -25,7 +30,18 @@ fleet_publish_intent({
 })
 ```
 
-You get back:
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Output
+
+```json
+{
+  "impact_preview": "…graph blast radius of the touched symbols…",
+  "active_conflicts": [],
+  "coordination": { "would_escalate": false, "suggested_partition": null }
+}
+```
+
 - `impact_preview` — the real graph blast radius of the touched symbols.
 - `active_conflicts` — overlapping live intents **on your branch** (none from other
   branches; coordination is branch-scoped).

package/installer/skills/commands/memtrace-fleet-record-episode.md

@@ -1,10 +1,15 @@
 ---
 name: memtrace-fleet-record-episode
-description: "Use AFTER an edit in a fleet to record it and get its conflict class (A/B/C) against agents on your branch. Triggered by: finishing an edit, 'I just changed X', completing a refactor step while other agents share your repo+branch. Returns conflict_class + replan_hint; a Class C returns an escalation_id and mediation_request that starts the decision loop. Do not finish a coordinated edit without recording it."
+description: "Record an edit you just made in a fleet and get its conflict class (A/B/C) against agents on your branch. Use when you have just finished an edit, when the user says 'I just changed X', or when completing a refactor step while other agents share your repo+branch. Returns conflict_class + replan_hint; a Class C returns an escalation_id and mediation_request that starts the decision loop. Do not finish a coordinated edit without recording it."
 allowed-tools:
   - mcp__memtrace__fleet_record_episode
   - mcp__memtrace__fleet_get_escalation
   - mcp__memtrace__fleet_query_episodes
+  - mcp__memtrace__fleet_submit_verdict
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 ## Overview
@@ -24,6 +29,8 @@ fleet_record_episode({
 })
 ```
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 ## The result: conflict_class
 
 - **A → proceed.** Additive, order-independent.
@@ -45,4 +52,18 @@ never make your edit a Class C.
 - Class A/B → continue.
 - Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
   editing the contested symbols until your directive is `proceed`.
-- Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.
+- Every recorded episode is logged and persists as the fleet's reviewable audit
+  trail. Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.
+
+## Output
+
+```jsonc
+{
+  "conflict_class": "C",        // "A" | "B" | "C"
+  "replan_hint": "re-read auth::verify_token before continuing",
+  // Class C only — absent for A/B:
+  "escalation_id": "esc-01J9...",
+  "mediation_request": { /* each agent's assignment + contested symbols */ },
+  "next_action": "poll fleet_get_escalation until your_directive != wait"
+}
+```

package/installer/skills/commands/memtrace-fleet-resolve.md

@@ -1,11 +1,15 @@
 ---
 name: memtrace-fleet-resolve
-description: "Use to act on a Class C decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Triggered by: 'a decision is waiting', 'who should proceed', being handed a mediation_request, acting as a mediator between two agents, or a human choosing a winner in the dashboard."
+description: "Resolve a Class C fleet decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Use when the user says 'a decision is waiting' or 'who should proceed', when you are handed a mediation_request, when acting as a mediator between two agents, or when a human chooses a winner in the dashboard. For the underlying conflict-class model and decision loop, see memtrace-fleet-coordination."
 allowed-tools:
   - mcp__memtrace__fleet_submit_verdict
   - mcp__memtrace__fleet_get_escalation
   - mcp__memtrace__fleet_list_escalations
   - mcp__memtrace__fleet_resolve_escalation
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 ## Overview
@@ -30,6 +34,8 @@ fleet_submit_verdict({
 // kinds: reconcile {merge_plan} | recommend {winner, rationale, confidence} | defer_to_human {question}
 ```
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 The response tells you the `outcome` (`auto_apply` | `human_confirm` |
 `human_required` | `pending`) and `your_directive`.
 
@@ -50,6 +56,10 @@ onto the winner; `review` = read `resolution`.
   decision (pick which agent proceeds) and clear it. Prefer the agent-judge path;
   use this for genuine human/product calls.
 
+Every verdict and resolution persists to the escalation record as the audit
+trail — review any decision later via `fleet_get_escalation` /
+`fleet_list_escalations`.
+
 ## Safety the referee guarantees
 
 - A destructive **removal** (delete/move) is **never** auto-applied — always a human.
@@ -57,3 +67,16 @@ onto the winner; `review` = read `resolution`.
   a non-destructive resolution.
 - So a wrong verdict degrades to "a human reviews a suggestion," never a silent
   bad merge.
+
+## Output
+
+`fleet_submit_verdict` and `fleet_get_escalation` both return the referee's decision:
+
+```jsonc
+{
+  "outcome": "human_confirm",  // auto_apply | human_confirm | human_required | pending
+  "your_directive": "wait",    // wait | proceed | defer | review
+  "resolution": "agent-b proceeds; agent-a rebases onto the wider contract"
+                               // set once the escalation is resolved (directive = review)
+}
+```

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

@@ -1,75 +1,93 @@
 ---
 name: memtrace-graph
-description: "Always use for source-code architecture, important symbols, centrality, PageRank, bridge functions, communities, logical modules, chokepoints, service boundaries, or dependency path questions. Do not use Glob, find, tree, or directory browsing to infer architecture; Memtrace runs graph algorithms over the AST graph."
+description: "Map source-code architecture with graph algorithms — PageRank centrality, bridge symbols, Louvain communities, dependency paths, and execution flows over the AST graph. Use when the user asks about source-code architecture, important symbols, centrality, PageRank, bridge functions, communities, logical modules, chokepoints, service boundaries, or dependency path questions. Do not use Glob, find, tree, or directory browsing to infer architecture; Memtrace runs graph algorithms over the AST graph."
 allowed-tools:
-  - mcp__memtrace__find_bridge_symbols
   - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_bridge_symbols
   - mcp__memtrace__find_dependency_path
   - mcp__memtrace__list_communities
   - mcp__memtrace__list_processes
   - mcp__memtrace__get_process_flow
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank), bridge symbol identification (Tarjan articulation points), shortest-path discovery, and execution flow tracing.
-
-All four algorithm tools (`find_central_symbols`, `find_bridge_symbols`, `find_dependency_path`, `list_communities`) run natively against the MemDB-backed knowledge graph — no Cypher required.
+Graph algorithms over the knowledge graph — communities (Louvain), PageRank centrality, bridge symbols (articulation points), shortest paths, and execution flows.
 
 ## Quick Reference
 
-| Tool | Purpose |
-|------|---------|
-| `find_bridge_symbols` | Architectural chokepoints — symbols whose removal disconnects the graph (Tarjan articulation points) |
-| `find_central_symbols` | Most important symbols by **PageRank** (default) or degree centrality |
-| `find_dependency_path` | Shortest call/import path between two symbols (BFS over typed edges) |
-| `list_communities` | Louvain-detected logical modules/services |
-| `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
-| `get_process_flow` | Trace a single process step-by-step |
+| Tool | Required params | Key optional |
+|------|-----------------|--------------|
+| `find_central_symbols` | `repo_id` | `limit` (def 25), `kinds[]` |
+| `find_bridge_symbols` | `repo_id` | `limit` |
+| `find_dependency_path` | `repo_id`, `source`, `target` | `max_depth` (def 20), `edge_type` |
+| `list_communities` | `repo_id` | `min_size`, `limit` |
+| `list_processes` | `repo_id` | `limit` |
+| `get_process_flow` | `repo_id`, `process` | `branch` |
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
 ### 1. Understand the architecture
 
-Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
+`list_communities` — natural module partitions.
 
 ### 2. Find critical infrastructure
 
-Use `find_central_symbols` to identify the most important symbols:
-- `method: "pagerank"` — importance by link structure (default; same algorithm Google uses)
-- `method: "degree"` — importance by direct connection count
-- `limit` — how many to return
+`find_central_symbols` runs **PageRank** internally. There is **no `method` param** (no degree-centrality switch).
+
+```json
+{ "repo_id": "memdb", "limit": 25, "kinds": ["Function", "Method"] }
+```
+
+### 3. Find chokepoints
+
+```json
+{ "repo_id": "memdb", "limit": 15 }
+```
+
+### 4. Path between two symbols
 
-The PageRank pass walks every CALLS / REFERENCES edge in the repo, distributes rank with the standard 0.85 damping factor, and converges on a stable ordering. The output is sorted by score descending, with each entry carrying `name`, `kind`, `file_path`, `score`, and the `in_degree`/`out_degree` it accumulated during the walk.
+```json
+{
+  "repo_id": "memdb",
+  "source": "handleLogin",
+  "target": "DatabaseClient.query",
+  "max_depth": 20
+}
+```
 
-### 3. Find architectural chokepoints
+Params are **`source`** and **`target`** (symbol names) — not `from`/`to`.
 
-Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph (Tarjan articulation points). These are:
-- **Single points of failure** — if they break, cascading failures occur
-- **Integration points** — good places for interfaces/contracts
-- **Refactoring targets** — often too much responsibility concentrated in one place
+### 5. Execution flows
 
-### 4. Discover the path between two symbols
+```json
+{ "repo_id": "memdb" }
+{ "repo_id": "memdb", "process": "POST /login" }
+```
 
-Use `find_dependency_path` to answer "how does symbol A reach symbol B?" — returns the shortest call/import chain via BFS over typed edges. Useful for:
-- "Why does the auth handler depend on the database client?"
-- "How does this CLI command reach the logging subsystem?"
-- "Confirm symbol X actually transitively depends on Y."
+## Output
 
-### 5. Trace execution flows
+`find_central_symbols` — each result carries the PageRank `score` plus degree counts:
 
-Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
+```json
+[
+  { "name": "DatabaseClient.query", "score": 0.0142, "in_degree": 38, "out_degree": 5 },
+  { "name": "handleLogin", "score": 0.0097, "in_degree": 21, "out_degree": 9 }
+]
+```
 
-Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access, ordered by the indexed `step` property on each STEP_IN_PROCESS edge.
+`find_dependency_path` returns the ordered symbol chain from `source` to `target`; `list_communities` returns module partitions with their member symbols.
 
-## Decision Points
+## Common Mistakes
 
-| Question | Tool |
-|----------|------|
-| "What are the main modules?" | `list_communities` |
-| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
-| "Where are the bottlenecks?" | `find_bridge_symbols` |
-| "How does symbol A reach symbol B?" | `find_dependency_path` |
-| "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
-| "What's the entry point for feature X?" | `list_processes`, then filter by name |
+| Mistake | Reality |
+|---------|---------|
+| `find_central_symbols(method: "degree")` | **No `method` param** — always PageRank |
+| `find_dependency_path(from=..., to=...)` | Use **`source`** and **`target`** |