memtrace 0.7.25 → 0.8.0

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

@@ -1,11 +1,18 @@
 ---
 name: memtrace-relationships
-description: "Always use for source-code relationship questions: callers, callees, references, imports, exports, type usages, class hierarchy, inheritance, implementations, overrides, or dependencies between symbols. Do not use Grep, Glob, rg, find, or manual text search for references; Memtrace traverses typed AST graph edges."
+description: "Map source-code relationships between symbols. Use when the user asks about callers, callees, references, imports, exports, type usages, class hierarchy, inheritance, implementations, overrides, or dependencies between symbols. Do not use Grep, Glob, rg, find, or manual text search for references; Memtrace traverses typed AST graph edges."
 allowed-tools:
   - mcp__memtrace__analyze_relationships
   - mcp__memtrace__get_symbol_context
   - mcp__memtrace__find_symbol
   - mcp__memtrace__find_code
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__get_evolution
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -25,49 +32,85 @@ Traverse the code knowledge graph to map relationships between symbols — calle
 | `exporters` | Which files import this module? |
 | `type_usages` | Where is this type/interface referenced? |
 
-> **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 (`depth`, etc.) must be JSON numbers — not strings.
 
+## Graph tool parameters
+
+### `get_symbol_context` (360° view — prefer this first)
+
+Required: `repo_id`, `symbol`
+
+```json
+{ "repo_id": "memdb", "symbol": "validateToken", "file_path": "src/auth.ts" }
+```
+
+Returns: callers, callees, type references, community, processes, cross-repo API callers.
+
+### `analyze_relationships` (targeted traversal)
+
+Required: `repo_id`, `target`, `query_type`
+
+```json
+{
+  "repo_id": "memdb",
+  "target": "validateToken",
+  "query_type": "find_callers",
+  "depth": 3,
+  "file_path": "src/auth.ts"
+}
+```
+
+| Param | Default | Notes |
+|---|---|---|
+| `depth` | **3** (max 10) | Not 2 |
+| `file_path` | — | Disambiguates overloaded names |
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Get the symbol ID
+### 1. Get the symbol name
 
-If you don't have a symbol `id`, find it first:
-- Use `find_symbol` for exact names
-- Use `find_code` for natural-language queries
+Use `find_symbol` or `find_code`. Save **`name`**, **`scope_path`**, and **`file_path`** from results — pass `symbol`/`target` plus optional `file_path` to graph tools.
 
 ### 2. Choose your approach
 
-**Quick 360° view** → Use `get_symbol_context`
-Returns in one call: direct callers, callees, type references, community membership, process membership, and cross-repo API callers.
+**Quick 360° view** → `get_symbol_context` (one call).
 
-**ALWAYS prefer `get_symbol_context` first** — it answers "what does this touch and what touches it?" faster than multiple `analyze_relationships` calls.
-
-**Targeted traversal** → Use `analyze_relationships`
-When you need a specific relationship type at a specific depth:
-- `symbol_id` — the symbol to start from (required)
-- `query_type` — one of the types above (required)
-- `depth` — traversal hops, default 2 (higher = slower but reveals indirect deps)
+**Targeted traversal** → `analyze_relationships` when you need a specific `query_type` at custom `depth`.
 
 ### 3. Interpret results
 
-- **High in_degree** (many callers) → widely-used symbol; changes have large blast radius
-- **High out_degree** (many callees) → complex function; candidate for refactoring
-- **Deep class hierarchy** → check for Liskov violations or fragile base class issues
-- **Cross-repo API callers** → changes require coordination with other teams/services
+Use `get_symbol_context` fields (callers, callees, community, processes) for blast-radius and architecture context. For degree-style metrics on a specific symbol, follow up with `get_impact`.
 
 ### 4. Follow up
 
-After understanding relationships, consider:
-- `get_impact` to quantify the blast radius of a change
-- `get_evolution` to see how this symbol has changed over time
-- `find_dead_code` if you found unreferenced symbols
+- `get_impact(repo_id, target=...)` — quantify blast radius
+- `get_timeline(repo_id, scope_path, file_path)` — full version history
+- `get_evolution(repo_id, from=..., target=...)` — window-scoped activity
+
+## Output
+
+`get_symbol_context` returns the symbol's 360° neighbourhood:
+
+```json
+{
+  "symbol": "validateToken",
+  "callers": ["..."],
+  "callees": ["..."],
+  "type_references": ["..."],
+  "community": "...",
+  "processes": ["..."],
+  "api_callers_cross_repo": ["..."]
+}
+```
+
+`analyze_relationships` returns the symbols/edges matching the requested `query_type` (no degree metrics — see Common Mistakes).
 
-## Decision Points
+## Common Mistakes
 
-| Situation | Action |
-|-----------|--------|
-| Need broad context fast | Use `get_symbol_context` (one call, full picture) |
-| Need specific relationship at depth >2 | Use `analyze_relationships` with custom depth |
-| Symbol has many callers | Follow up with `get_impact` before modifying |
-| Found cross-repo API callers | This is a service boundary — coordinate changes |
+| Mistake | Reality |
+|---------|---------|
+| Passing `symbol_id` | Use **`target`** (`analyze_relationships`) or **`symbol`** (`get_symbol_context`) |
+| Assuming default `depth: 2` | Default is **3** |
+| Expecting `in_degree` on `analyze_relationships` results | Use `get_symbol_context` or `get_impact` for centrality/risk context |

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

@@ -1,93 +1,118 @@
 ---
 name: memtrace-search
-description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+allowed-tools:
+  - mcp__memtrace__find_code
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__get_source_window
+  - mcp__memtrace__list_indexed_repositories
+  - Read
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 ## Overview
 
-Find code using hybrid BM25 full-text + semantic vector search with Reciprocal Rank Fusion. Works for both natural-language queries and exact symbol names. This is the primary discovery tool — use it before calling relationship or impact analysis tools.
+Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool — use before relationship or impact analysis.
 
 ## Quick Reference
 
 | Tool | Best For |
 |------|----------|
-| `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
-| `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
-| `get_source_window` | Optional: bounded source read after a Memtrace hit, when your harness lacks `Read(file, offset, limit)`. Otherwise prefer your harness's bounded read with the returned `start_line` / `end_line`. |
+| `find_code` | Natural-language queries, broad searches |
+| `find_symbol` | Exact identifier names |
+| `get_source_window` | Bounded source read when harness lacks `Read(offset, limit)` |
 
-## Steps
+> **Parameter types:** Numbers must be JSON numbers — not strings.
+
+## `find_code` parameters
+
+| Param | Required | Default | Notes |
+|---|---|---|---|
+| `query` | yes | — | Natural language or symbol text |
+| `repo_id` | no | all repos | |
+| `limit` | no | 20 | Max 100 |
+| `file_path` | no | — | Path/directory substring filter |
+| `as_of` | no | now | ISO-8601 time-travel |
+| `include_diagnostics` | no | false | Set true for `id`, `score` in results |
+
+**No `kind` param on `find_code`** — use `find_symbol(kind=...)` to filter by symbol type.
+
+```json
+{ "query": "authentication middleware", "repo_id": "memdb", "limit": 20 }
+```
 
-### 1. Choose the right search tool
+## `find_symbol` parameters
+
+| Param | Required | Default | Notes |
+|---|---|---|---|
+| `name` | yes | — | Symbol name to search |
+| `repo_id` | no | all repos | |
+| `fuzzy` | no | false | API field exists; currently exact-match in backend |
+| `edit_distance` | no | 2 | Only when fuzzy enabled |
+| `kind` | no | — | `Function`, `Class`, `Method`, etc. |
+| `file_path` | no | — | Path substring filter |
+| `limit` | no | 10 | Max 50 |
+
+```json
+{ "name": "validateToken", "repo_id": "memdb", "file_path": "auth" }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Steps
 
-- **Know the exact name?** → Use `find_symbol` with `fuzzy: true` for typo tolerance
-- **Describing behaviour?** → Use `find_code` with a natural-language query
-- **Searching all repos?** → Omit `repo_id` from either tool
+### 1. Choose the tool
 
-### 2. Execute the search
+- Exact name → `find_symbol`
+- Behaviour description → `find_code`
+- All repos → omit `repo_id`
 
-> **Parameter types:** numbers must be JSON numbers, not strings. `limit: 20` is correct; `limit: "20"` returns `MCP error -32602: expected usize`.
+### 2. Execute search
 
-**`find_code` parameters:**
-- `query` — string, required. Natural-language or exact text.
-- `repo_id` — string, optional. Scope to a single repo (omit to search all).
-- `kind` — string, optional. Filter by symbol type: `"Function"`, `"Class"`, `"Method"`, `"Interface"`, `"APIEndpoint"`, `"APICall"`.
-- `limit` — **integer**, optional. Max results. Default `20`, capped at `100`.
-- `as_of` — string, optional. ISO-8601 timestamp for time-travel search (e.g. `"2026-04-01T00:00:00Z"`).
-- `file_path` — string, optional. File path or directory substring to constrain results (e.g. `"cli/commands"` or `"auth.py"`).
+Result shape: see [Output](#output) below.
 
-**`find_symbol` parameters:**
-- `name` — string, required. Exact or partial symbol name (e.g. `"ValidateToken"`).
-- `fuzzy` — boolean, optional. Enable Levenshtein correction. Default `false`.
-- `edit_distance` — **integer**, optional. Maximum Levenshtein edit distance for fuzzy search. Default `2`, capped at `2`.
-- `repo_id` — string, optional. Scope to a single repo.
-- `kind` — string, optional. Filter by symbol type (e.g. `"Function"`, `"Class"`, `"Variable"`).
-- `file_path` — string, optional. Filter by file path substring.
-- `limit` — **integer**, optional. Max results. Default `10`, capped at `50`.
+### 3. Hand off to graph tools
 
-**Success criteria:** Results include `file_path`, `start_line`, `kind`, and relevance `score`.
+Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
 
-### 3. Use results for next steps
+```json
+{ "repo_id": "memdb", "symbol": "validateToken" }
+{ "repo_id": "memdb", "target": "validateToken", "direction": "both" }
+{ "repo_id": "memdb", "target": "validateToken", "query_type": "find_callers" }
+```
 
-The default next step is a **graph tool** — `get_symbol_context`,
-`analyze_relationships`, or `get_impact`. Those answer "who calls this",
-"what's the blast radius", "what community is it part of" — context no
-file read can give. That's what Memtrace uniquely provides.
+Read source only when editing — bounded `Read(offset, limit)` at returned lines.
 
-Source bytes come last, only when you're about to edit or quote. Use a
-bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`,
-or `get_source_window` if your harness lacks bounded reads. Do not whole-file.
+### Multi-word queries
 
-Save the symbol `id` from results — pass it to:
-- `analyze_relationships` to map callers/callees
-- `get_symbol_context` for a 360-degree view
-- `get_impact` to assess blast radius before changes
+1. Try verbatim `find_code` query.
+2. If weak, fan out: camelCase, snake_case, domain identifiers.
+3. Dedupe top hits by `file_path:start_line`.
 
-### Multi-word natural-language queries
+## Output
 
-When your query is 3+ words and feels descriptive (e.g. "validate auth token", "find HTTP server error"), don't stop at the first `find_code` call:
+One `find_code` / `find_symbol` result entry:
 
-1. First try the verbatim query.
-2. If results look generic or the right doc isn't at rank 1, fan out **in parallel** with up to 3 identifier-shaped reshapes:
-   - camelCase: "validate auth token" → `validateAuthToken`
-   - snake_case: → `validate_auth_token`
-   - Domain-likely identifiers: → `auth_token`, `tokenValidator`, `verifyToken`
-3. Memtrace's tokenizer splits camelCase / snake / kebab at index time, so reshaped queries hit identifier names directly.
-4. Take the union of top-5 from each call, dedupe by `file_path:start_line`.
+```json
+{
+  "name": "validateToken",
+  "kind": "Function",
+  "file_path": "src/auth/token.rs",
+  "start_line": 42,
+  "scope_path": "auth::token"
+}
+```
 
-**Worked examples** (verbatim → reshapes to try in parallel):
-- "validate auth token" → `validateAuthToken`, `validate_auth_token`, `verifyToken`
-- "find http server error" → `findHttpServerError`, `http_error`, `serverError`
-- "render value panel" → `renderValuePanel`, `ValuePanel`, `value_panel`
+`score` (and `id`) appear only with `include_diagnostics: true`.
 
 ## Common Mistakes
 
 | Mistake | Reality |
 |---------|---------|
-| Searching without indexing first | Call `list_indexed_repositories` to verify the repo is indexed |
-| Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
-| Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
-| Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |
-| Reading the whole file after a hit | First call `get_symbol_context` for callers/callees. If you still need source, do a bounded `Read(file, offset=start_line, limit=N)` — never whole-file. `get_source_window` is fine if your harness has no bounded read. |
-| Going straight from `find_code` to source read | Memtrace's value is the graph. Default next step is `get_symbol_context` or `get_impact`, not source. |
-| Treating 0 results as permission to grep | 0 results means broaden the Memtrace query, check repo_id/path filters, then reindex if coverage is missing |
-| Assuming a UI subdirectory is unindexed because stats show backend files | If `ui/`, `memtrace-ui/`, or another source directory is under the indexed repo root, diagnose/reindex with Memtrace instead of searching files manually |
+| `find_code(kind=...)` | **`kind` only on `find_symbol`** |
+| Passing symbol `id` to graph tools | Use **`name`** as `symbol` / `target` |
+| Assuming `fuzzy: true` always works | Backend is exact-match today — try spelling variants |
+| Skipping `list_indexed_repositories` | Verify repo is indexed first |

package/installer/skills/workflows/memtrace-change-impact-analysis.md

@@ -1,15 +1,18 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Always use before source-code edits, refactors, API changes, renames, removals, PR reviews, or risk assessments when the user needs to know what will break. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change detection."
+description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers — and produce a risk-rated change plan. Use when the user needs to know what will break before a change: edits, refactors, API changes, renames, removals, PR reviews, or risk assessments. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change history. For a quick blast-radius check on one symbol, use memtrace-impact."
 allowed-tools:
   - mcp__memtrace__find_symbol
   - mcp__memtrace__find_code
   - mcp__memtrace__get_symbol_context
   - mcp__memtrace__get_impact
-  - mcp__memtrace__detect_changes
   - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_timeline
   - mcp__memtrace__analyze_relationships
-  - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -25,11 +28,11 @@ Find the target symbol(s):
 - Use `find_symbol` if the user named specific functions/classes
 - Use `find_code` if the user described behaviour ("the authentication middleware")
 
-Collect symbol IDs for all targets.
+Collect symbol **names** (`name`, `scope_path`, `file_path`) for all targets — graph tools use names, not internal IDs.
 
 ### 2. Get 360° context for each target
 
-For each symbol, call `get_symbol_context`:
+For each symbol, call `get_symbol_context` (`repo_id`, `symbol`, `file_path`):
 - Direct callers and callees
 - Community membership (which module is this in?)
 - Process membership (which execution flows does this participate in?)
@@ -39,7 +42,7 @@ For each symbol, call `get_symbol_context`:
 
 ### 3. Compute blast radius
 
-For each target, call `get_impact` with `direction: both`:
+For each target, call `get_impact` (`repo_id`, `target`) with `direction: "both"`, `depth: 5`:
 - Upstream impact: what depends on this symbol
 - Downstream impact: what this symbol depends on
 - Risk rating: Low / Medium / High / Critical
@@ -54,13 +57,16 @@ For each target, call `get_impact` with `direction: both`:
 
 ### 4. Check temporal stability
 
-Call `get_evolution` with mode `novel` for a 30-day window on the repo:
-- Are any of the target symbols flagged as "rarely changing"? If so, this change is structurally surprising and deserves extra scrutiny.
-- Have the target symbols been changing frequently? High churn + high impact = volatile hotspot.
+Call `get_evolution` (`repo_id`, `from: "30d ago"`, `mode: "compound"`), then `get_timeline` on each target symbol (requires `scope_path` + `file_path` from `find_symbol`):
+- Sparse timeline history + you're about to change it → structurally surprising; extra scrutiny warranted.
+- Target appears in `top_touched_symbols` → high churn + high impact = volatile hotspot.
 
 ### 5. Map affected execution flows
 
-From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` with `query_type: find_callers` at `depth: 3` to trace the full transitive caller chain.
+From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` (`repo_id`, `target`) with `query_type: "find_callers"` at `depth: 3` to trace the full transitive caller chain.
+
+`depth: 3` is a JSON number, not a string — the validator rejects `"3"`.
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ### 6. Produce the risk assessment
 
@@ -70,7 +76,7 @@ Synthesize into a change plan:
 2. **Blast Radius** — number of direct/transitive dependents, risk rating
 3. **Affected Processes** — which execution flows will be impacted
 4. **Cross-Service Impact** — any external callers or consumers
-5. **Stability Signal** — is this code stable (novel) or volatile (frequent changes)?
+5. **Stability Signal** — sparse `get_timeline` history (stable) vs frequent appearance in `top_touched_symbols` (volatile)
 6. **Recommended Approach** — based on risk: direct change, incremental migration, or backward-compatible evolution
 7. **Test Coverage** — which callers/processes to verify after the change
 
@@ -80,6 +86,20 @@ Synthesize into a change plan:
 |-----------|--------|
 | Risk = Critical | Recommend backward-compatible change + deprecation path |
 | Cross-repo callers exist | Flag as requiring multi-service coordination |
-| Symbol has high novelty score | Extra review — this rarely changes; make sure the change is intentional |
+| Symbol has sparse timeline but high impact | Extra review — this rarely changes; make sure the change is intentional |
 | Multiple processes affected | List each affected flow; recommend testing each one |
 | Symbol is a bridge point | Change may disconnect parts of the architecture — verify alternative paths exist |
+
+## Output
+
+The workflow's artifact is the step-6 risk-rated change plan. Compact example:
+
+```text
+Target: AuthService::validateToken (src/auth/service.ts)
+Blast Radius: 4 direct / 23 transitive dependents — Risk: High
+Affected Processes: login-flow, session-refresh
+Cross-Service Impact: 2 cross-repo API callers — needs multi-service coordination
+Stability Signal: appears in top_touched_symbols (volatile hotspot)
+Recommended Approach: incremental migration behind a feature flag
+Test Coverage: all 4 direct callers + both affected processes
+```

package/installer/skills/workflows/memtrace-code-review.md

@@ -1,13 +1,15 @@
 ---
 name: memtrace-code-review
-description: "Always use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection."
-when_to_use: "Triggered by 'review this PR', 'code review this pull request', 'post Memtrace review', 'run memtrace code-review', 'create PR with review', 'GitHub PR review', 'publish review comments', or any request to use Memtrace as a GitHub code reviewer. Use after code is pushed as a PR, and call review_github_pr instead of manually grepping diffs."
-paths: "**/*.{py,js,jsx,ts,tsx,mjs,cjs,rs,go,java,rb,c,cc,cpp,cxx,h,hpp,hh,cs,php,swift,kt,kts,scala,clj,cljs,ex,exs,erl,hrl,ml,mli,fs,fsx,r,jl,lua,dart,m,mm,asm,sql,gql,graphql,proto,sh,bash,zsh,fish,vue,svelte}"
+description: "Review GitHub pull requests with Memtrace's local graph-backed review engine. Use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection. Do not use for local working-tree diffs — that is the built-in /code-review; this skill is for GitHub PRs via review_github_pr."
 allowed-tools:
   - mcp__memtrace__review_github_pr
-  - mcp__memtrace__find_code_review_issues
-  - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
+when_to_use: "Triggered by 'review this PR', 'code review this pull request', 'post Memtrace review', 'run memtrace code-review', 'create PR with review', 'GitHub PR review', 'publish review comments', or any request to use Memtrace as a GitHub code reviewer. Use after code is pushed as a PR, and call review_github_pr instead of manually grepping diffs."
+paths: "**/*.{py,js,jsx,ts,tsx,mjs,cjs,rs,go,java,rb,c,cc,cpp,cxx,h,hpp,hh,cs,php,swift,kt,kts,scala,clj,cljs,ex,exs,erl,hrl,ml,mli,fs,fsx,r,jl,lua,dart,m,mm,asm,sql,gql,graphql,proto,sh,bash,zsh,fish,vue,svelte}"
 ---
 
 ## Overview
@@ -22,6 +24,8 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 4. Default to `minSeverity: "high"` and `maxComments: 5` when posting. For previews, `maxComments: 10` is acceptable.
 5. Pass `repoRoot` when the PR checkout is not the current working directory. Pass `repoId` when the indexed repository id is known.
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 ## Example User Prompts
 
 - "Review this PR with Memtrace: https://github.com/OWNER/REPO/pull/123"
@@ -32,6 +36,7 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 
 - Do not start with generic grep, rg, or manual diff review when `review_github_pr` is available.
 - Do not post comments unless the user explicitly requested publication.
+- After posting comments (`post: true`), record the PR URL and the posted comment IDs in the session output as the audit trail.
 - Do not create benchmark-specific or PR-specific findings. The review must come from general Memtrace detectors, graph evidence, and policy ranking.
 - If the tool reports missing auth, tell the user to run `memtrace auth login`.
 - If the tool reports missing GitHub App installation, tell the user to install Memtrace Code Reviewer on that repository.
@@ -39,10 +44,11 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 
 ## Output
 
-For previews, summarize:
-- PR URL and repository
-- Graph state
-- Number of candidate comments
-- File, line, severity, and message for each finding
+Summarize the `review_github_pr` result with these fields:
 
-For posted reviews, report the PR URL and number of comments posted.
+| Field | Preview (`post: false`) | Posted (`post: true`) |
+|---|---|---|
+| PR URL + repository | yes | yes |
+| Graph state | yes | yes |
+| Findings | count of candidate comments, plus file, line, severity, message per finding | number of comments posted |
+| Posted comment IDs | — | yes — record with the PR URL as the audit trail |

package/installer/skills/workflows/memtrace-codebase-exploration.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-codebase-exploration
-description: "Always use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing."
+description: "Map an indexed source-code repo into a structured overview — scale, communities, central symbols, execution flows, API surface, recent activity. Use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing. Do NOT use for change history / what-changed questions — use memtrace-evolution."
 allowed-tools:
   - mcp__memtrace__index_directory
   - mcp__memtrace__check_job_status
@@ -14,6 +14,10 @@ allowed-tools:
   - mcp__memtrace__get_api_topology
   - mcp__memtrace__get_evolution
   - mcp__memtrace__find_most_complex_functions
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -50,7 +54,11 @@ Each community represents a cohesive module — these are the "areas" of the cod
 
 ### 4. Find the most important symbols
 
-Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
+Call `find_central_symbols` — PageRank over CALLS/REFERENCES edges (no `method` param):
+
+```json
+{ "repo_id": "<repo>", "limit": 15 }
+```
 
 These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
 
@@ -78,13 +86,29 @@ Call `find_api_endpoints` to list all HTTP routes.
 
 ### 8. Recent activity
 
-Call `get_evolution` with mode `overview` and a 30-day window to see which modules have been most active recently.
+Call `get_evolution` to see recent activity:
+
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "overview" }
+```
+
+Check `totals.episode_count` and episode boundaries. For file/symbol hotspots, switch to `compound`:
 
-**Decision:** If the user asks about specific recent changes, switch to mode `compound` for symbol-level detail.
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "compound" }
+```
+
+Review `top_changed_files` and `top_touched_symbols`.
 
 ### 9. Complexity hotspots
 
-Call `find_most_complex_functions` with `limit: 10` to identify potential technical debt.
+Call `find_most_complex_functions`:
+
+```json
+{ "repo_id": "<repo>", "top_n": 10 }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Report Synthesis
 
@@ -98,6 +122,18 @@ Synthesize findings into a structured overview:
 6. **Recent Activity** — what's been changing in the last 30 days
 7. **Technical Debt** — complexity hotspots and potential dead code
 
+## Output
+
+The deliverable is the 7-part overview above. Skeleton (one headline per part):
+
+1. Scale — 2 languages, 4,812 symbols, 19,344 relationships
+2. Architecture — 12 communities; top 5: auth, indexing, api, ui, billing
+3. Critical Infrastructure — `EngineHandle::open` (central AND bridge — flag it)
+4. Execution Flows — 14 processes: 9 HTTP handlers, 3 CLI commands, 2 jobs
+5. API Surface — 42 endpoints; 2 cross-repo service dependencies
+6. Recent Activity — 31 episodes in 30d; hottest file per `top_changed_files`
+7. Technical Debt — top-10 complex functions, highest complexity first
+
 ## Common Mistakes
 
 | Mistake | Reality |