@mushi-mushi/mcp 0.17.1 → 0.18.1

package/dist/index.js

@@ -11,7 +11,7 @@ var TOOL_CATALOG = [
   {
     name: "get_recent_reports",
     title: "Recent bug reports",
-    description: "List recent bug reports with optional filters (status / category / severity). Use this to see what is waiting in your reports inbox right now.",
+    description: "List recent bug reports for a project, newest first. Returns { reports: [{ id, status, category, severity, summary, created_at }], total }. Optional filters: status (new|classified|grouped|fixing|fixed|verified|reopened|dismissed), category (bug|slow|visual|confusing|other), severity (critical|high|medium|low), limit (default 20, max 100). Use to survey open reports; for one report use get_report_detail, to find a bug by text use search_reports.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What landed in my bug queue today?"
@@ -19,7 +19,7 @@ var TOOL_CATALOG = [
   {
     name: "get_report_detail",
     title: "Report detail",
-    description: "Full payload for a single report \u2014 description, console logs, network requests, screenshot URL, classification, fix history.",
+    description: "Fetch the full record for one bug report by id: description, console logs, network requests, screenshot URL, classification (stage 1/2), and fix history. Returns { report }. Read-only. Use when you have a reportId and need everything about it; for evidence only use get_report_evidence, for the activity thread use get_report_timeline, for a one-call fix bundle use get_fix_context.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me everything you know about this report."
@@ -27,7 +27,7 @@ var TOOL_CATALOG = [
   {
     name: "get_report_timeline",
     title: "Unified report timeline",
-    description: "Ordered timeline merging reporter comments, fix events, QA runs, skill pipeline steps, and Ask Mushi turns for one report.",
+    description: "Return the ordered activity timeline for one report (oldest to newest), merging reporter comments, fix events, QA runs, skill-pipeline steps, and Ask Mushi turns into one lane. Returns { events: [{ ts, kind, actor, summary }] }. Read-only. Use to see what happened end-to-end on a report thread; use get_report_detail for the static record or get_fix_timeline to debug one fix attempt.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What happened on this report thread end-to-end?"
@@ -35,7 +35,7 @@ var TOOL_CATALOG = [
   {
     name: "search_reports",
     title: "Search reports",
-    description: "Semantic + keyword search over reports. Uses pgvector similarity server-side \u2014 falls back to description/summary substring only if embeddings are unavailable for the project.",
+    description: 'Search reports by meaning and keyword (pgvector similarity server-side; falls back to summary/description substring if embeddings are unavailable). Returns ranked { results: [{ id, summary, similarity }] }. Read-only. Use to find reports by free text ("checkout flakiness"); use get_similar_bugs to dedupe a known component/bug, or get_recent_reports to list without a query.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: 'Find reports mentioning "checkout flakiness".'
@@ -43,7 +43,7 @@ var TOOL_CATALOG = [
   {
     name: "get_similar_bugs",
     title: "Similar bugs",
-    description: 'Find bugs related to a component, page, or description via pgvector nearest-neighbour search. Same backend as search_reports but tuned for "have we seen this before?".',
+    description: 'Find existing bugs similar to a component, page, or description via pgvector nearest-neighbour search (same backend as search_reports, tuned for "have we seen this before?"). Returns ranked { reports: [{ id, summary, similarity }] }. Read-only. Use to dedupe before filing or group regressions; use search_reports for general free-text search.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Have we seen a bug like this before?"
@@ -51,7 +51,7 @@ var TOOL_CATALOG = [
   {
     name: "get_fix_context",
     title: "Fix context bundle",
-    description: "Bundle the full context an agent needs to fix a bug: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, reproduction steps, component, root cause, and ontology tags. One call instead of several. No second LLM key needed.",
+    description: "Bundle everything an agent needs to fix one bug in a single call: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, repro steps, component, root cause, and ontology tags. Returns { fixPrompt, report, reproduction, component, rootCause, tags }. Read-only; no second LLM key needed. Use before writing a fix; use triage_issue for a multi-report review packet, or suggest_fix for just the Stage-2 hint.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me everything I need to fix this in one payload."
@@ -59,7 +59,7 @@ var TOOL_CATALOG = [
   {
     name: "get_fix_timeline",
     title: "Fix timeline",
-    description: 'Ordered timeline of a fix attempt \u2014 dispatched \u2192 started \u2192 branch \u2192 commit \u2192 PR opened \u2192 CI \u2192 completed/failed. Use this to debug "why did this fix fail?".',
+    description: 'Return the ordered lifecycle of one fix attempt: dispatched, started, branch, commit, PR opened, CI, completed/failed, with timestamps and the PR URL. Returns { events: [{ ts, stage, detail }] }. Read-only. Use to debug "why did this fix fail?" after dispatch_fix; use refresh_ci to re-poll GitHub CI, or get_report_timeline for the whole report thread.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Why did this fix attempt fail \u2014 show me every step."
@@ -67,7 +67,7 @@ var TOOL_CATALOG = [
   {
     name: "get_blast_radius",
     title: "Blast radius",
-    description: "Graph traversal showing other components / pages a bug group touches. Use before dispatching a fix so the agent can scope its changes.",
+    description: "Return the other components/pages a bug group touches, via knowledge-graph traversal from the report node. Returns { nodes: [{ id, label, type }], edges }. Read-only. Use before dispatch_fix to scope a change safely; use get_knowledge_graph to traverse from an arbitrary seed, or analyze_codebase_impact for file-level import impact.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What else might break if I change this component?"
@@ -75,7 +75,7 @@ var TOOL_CATALOG = [
   {
     name: "get_knowledge_graph",
     title: "Knowledge graph traversal",
-    description: "Traverse the knowledge graph from a seed component or page. Returns nodes + edges within a depth budget (max 4 hops).",
+    description: "Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug's impact area, or get_graph_neighborhood for a tighter BFS around one node.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me how this component connects to the rest of the app."
@@ -83,97 +83,73 @@ var TOOL_CATALOG = [
   {
     name: "run_nl_query",
     title: "Ask your data (NL \u2192 SQL)",
-    description: "Natural-language question \u2192 SQL query run against your project data. Read-only, 60/hour rate-limited, no privileged schemas.",
+    description: 'Answer a natural-language question about your project data by generating and running a read-only SQL query (no privileged schemas, rate-limited to 60/hour). Returns { sql, rows }. Use for ad-hoc analytics ("which components had the most critical bugs this week?"); use get_recent_reports/search_reports for plain report lookups, or search_mushi_docs for documentation questions.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which components had the most critical bugs this week?"
   },
   // --- Inventory v2 (whitepaper §6.8) -------------------------------------
   {
-    name: "inventory_get",
+    name: "get_inventory",
     title: "Inventory snapshot",
-    description: "Current inventory.yaml snapshot for a project (latest ingest, validation errors, per-action status summary). Requires inventory_v2 on the project plan.",
+    description: "Return the current inventory.yaml snapshot for a project: latest ingest, validation errors, and a per-action status summary. Returns { snapshot, validationErrors, actions: [{ id, status }] }. Requires the inventory_v2 plan. Read-only. Use for the full current state; use diff_inventory to compare two commits, or list_gate_findings for the latest gate results.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What does the live inventory claim for this repo right now?"
   },
   {
-    name: "inventory_diff",
+    name: "diff_inventory",
     title: "Inventory diff",
-    description: "Diff two ingested inventory commits (fromSha \u2192 toSha) \u2014 added/removed nodes and edges. Use before merging a PR that touches inventory.yaml.",
+    description: "Diff two ingested inventory commits (fromSha to toSha): added/removed nodes and edges. Returns { added, removed, changed }. Requires inventory_v2. Read-only. Use before merging a PR that touches inventory.yaml to see what changed; use get_inventory for the current snapshot.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What changed in inventory between these two SHAs?"
   },
   {
-    name: "inventory_findings",
+    name: "list_gate_findings",
     title: "Gate findings",
-    description: "Latest gate runs + findings (dead-handler, mock-leak, crawl, status-claim, \u2026). Filter by gate name or severity.",
+    description: "List recent inventory gate runs and their findings for a project, newest first. Returns { runs: [{ id, gate, status, findings_count, \u2026 }], findings: [{ severity, rule_id, message, file_path, node_id, \u2026 }] }. Filter by gate (dead-handler | mock-leak | crawl | status-claim) or minimum severity (low|medium|high|critical). Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me what CI gates failed on the last run."
   },
   {
-    name: "graph_neighborhood",
+    name: "get_graph_neighborhood",
     title: "Graph neighborhood",
-    description: 'BFS neighborhood around a graph node id or label \u2014 nodes + edges within a depth budget (max 4). Same backend as knowledge-graph traversal, tuned for "what touches this action?".',
+    description: `Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4). Read-only. Tuned for "what touches this action?"; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node's row.`,
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What nodes connect to this inventory Action within 2 hops?"
   },
   {
-    name: "graph_node_status",
+    name: "get_graph_node",
     title: "Graph node detail",
-    description: "Fetch a single graph node row (label, type, metadata \u2014 includes v2 derived status on Action nodes).",
+    description: "Fetch one knowledge-graph node row by id. Returns { node: { id, node_type, label, metadata } } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node's status; use get_graph_neighborhood to see what connects to it.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What status does the graph store on this node id?"
   },
   {
-    name: "fix_suggest",
+    name: "suggest_fix",
     title: "Suggested fix (from triage)",
-    description: "Read-only slice of a report focused on Stage 2 suggested fix + root cause + reproduction \u2014 faster than pulling the full blob when you only need the human-readable hint.",
+    description: 'Return the Stage-2 suggested-fix slice for one report: root cause, suggested fix, repro steps, summary, and component \u2014 faster than get_report_detail when you only need the human-readable hint. Returns { reportId, rootCause, suggestedFix, reproductionSteps, summary, component }. Read-only; reads the existing classification (run triage_issue first if unclassified). Use for a quick "what should we try?"; use get_fix_context for the full paste-ready bundle.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What did Stage 2 say we should try for this report?"
   },
   // --- Setup / admin -------------------------------------------------------
-  {
-    name: "setup_check",
-    title: "Dispatch preflight check",
-    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, your Anthropic API key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Is this project ready to auto-fix bugs? What is blocking dispatch?"
-  },
-  {
-    name: "ingest_setup_check",
-    title: "Ingest setup check",
-    description: "[Deprecated \u2014 use diagnose_setup with mode=ingest or diagnose_connection.] Run the 4 **required ingest** checks for the project tied to this API key: project exists, active API key, SDK heartbeat (or real report), and at least one ingested report.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Is the SDK installed and ingesting reports? Why is my banner still missing?"
-  },
   {
     name: "diagnose_setup",
     title: "Unified setup diagnose",
-    description: "Single entry point for setup health. mode=full (default) runs ingest + dispatch checks and returns the best next action; mode=ingest runs SDK ingest checks only; mode=dispatch runs fix-dispatch preflight only. Prefer this over setup_check, ingest_setup_check, or diagnose_connection alone.",
+    description: "Diagnose Mushi setup health and return the single best next action. mode=full (default) runs both SDK-ingest and fix-dispatch preflight checks; mode=ingest runs ingest checks only (project exists, active API key, SDK heartbeat, at least one report); mode=dispatch runs dispatch readiness only (GitHub connected, codebase indexed, LLM key present, autofix enabled). Returns { ready, steps: [{ label, complete, required, hint }], nextAction }. Read-only. The one setup-diagnosis entry point \u2014 use this instead of separate connection/ingest checks.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Why is Mushi setup broken \u2014 one call, clear next step."
   },
-  {
-    name: "diagnose_connection",
-    title: "Connection diagnose (CLI + MCP + SDK)",
-    description: `Validate MCP credentials, ping /health, run ingest-setup and dispatch preflight, return the single best next action. For mode-specific checks prefer diagnose_setup. Use when the user asks "why aren't my reports showing up?".`,
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Why is my Mushi setup broken \u2014 what exact step should I fix next?"
-  },
   {
     name: "search_mushi_docs",
     title: "Search Mushi documentation",
-    description: "Search official Mushi docs (guides, MCP setup, inventory, QA, skills) by keyword. Returns ranked page titles, URLs, and excerpts \u2014 use before guessing API shapes or RPC names.",
+    description: "Search the official Mushi documentation (guides, MCP setup, inventory, QA, skills) by keyword. Returns ranked { results: [{ title, url, excerpt }] }. Read-only. Use before guessing API shapes, tool names, or RPC names; use run_nl_query for questions about your own project data, not the docs.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: false },
     useCase: "How do I configure MCP scopes / dispatch a fix / wire QA stories?"
@@ -182,7 +158,7 @@ var TOOL_CATALOG = [
   {
     name: "submit_fix_result",
     title: "Record a fix outcome",
-    description: "Record a fix outcome (branch, PR, files, lines) from an external agent. Creates a fix_attempt then patches it to completed.",
+    description: "Record a fix outcome from an external agent (e.g. your own Cursor/Claude run): branch, PR URL, files changed, lines added/removed. Creates a fix_attempt row then patches it to completed and links it to the report. Returns { fixAttemptId }. Write; NOT idempotent \u2014 each call creates a new fix_attempt, so call once per PR. Use after you opened a PR outside Mushi; use dispatch_fix to have Mushi open the PR instead, or merge_fix once CI is green.",
     scope: "mcp:write",
     // Not idempotent: re-running creates a second fix_attempt row.
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
@@ -191,7 +167,7 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: 'Start the Mushi fix agent for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
+    description: 'Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent (default uses the in-repo worker). Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixAttemptId }; poll get_fix_timeline for progress and merge_fix when CI is green. Write; NOT idempotent \u2014 each call starts a new attempt. Report must be classified \u2014 run triage_issue if not.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
@@ -199,7 +175,7 @@ var TOOL_CATALOG = [
   {
     name: "trigger_judge",
     title: "Run Sonnet-as-Judge",
-    description: "Run the Sonnet-as-Judge over a batch of classified reports. Returns a batch id; results land in judge_results.",
+    description: "Queue the Sonnet-as-Judge to grade recent fix quality across accessible projects. Returns { dispatched: number } \u2014 one judge-batch job per project; scores land asynchronously in judge_results (read back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Grade the latest batch of fixes before I ship."
@@ -207,7 +183,7 @@ var TOOL_CATALOG = [
   {
     name: "test_gen_from_report",
     title: "Generate Playwright test from report",
-    description: "Generate a Playwright spec from a classified report using your project LLM key and open a draft PR. Requires inventory_v2 + GitHub + LLM keys.",
+    description: "Generate a Playwright regression test from a classified report using your project LLM key, then open a draft GitHub PR with the spec. Requires the inventory_v2 plan plus GitHub and LLM keys configured. Returns { qaStoryId, prUrl }. Write; consumes LLM budget; NOT idempotent \u2014 each call opens a new PR. Use to lock in a regression as an E2E test; use generate_tdd_from_story to build a test from a mapped user story instead.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Turn this regression report into an E2E test PR."
@@ -215,7 +191,7 @@ var TOOL_CATALOG = [
   {
     name: "transition_status",
     title: "Move report between states",
-    description: "Move a report between workflow states (new \u2192 classified \u2192 grouped \u2192 fixing \u2192 fixed \u2192 verified \u2192 reopened \u2192 dismissed). Enforces the same transition rules as the admin UI.",
+    description: "Move a report to a new workflow state, enforcing the same transition rules as the admin UI. Valid targets: classified, grouped, fixing, fixed, verified, reopened, dismissed. Returns { report } with the updated status. Write; idempotent (setting the current status is a no-op); rejects illegal transitions. Use to dismiss a duplicate or mark fixed; use merge_fix to mark fixed via a merged PR, or reopen_report for the reopened path.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Dismiss this duplicate / mark it fixed."
@@ -223,7 +199,7 @@ var TOOL_CATALOG = [
   {
     name: "merge_fix",
     title: "Merge fix PR",
-    description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+    description: "Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive (mutates the target repo's default branch); idempotent \u2014 re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci). Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Merge the draft PR and notify the reporter."
@@ -231,15 +207,15 @@ var TOOL_CATALOG = [
   {
     name: "refresh_ci",
     title: "Refresh fix CI status",
-    description: "Pull the latest GitHub check-run status for a fix attempt.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
+    description: "Re-poll GitHub for the latest check-run status of a fix attempt's PR and persist it on the fix_attempt row (does not merge or mutate GitHub). Returns { check_run_status, check_run_conclusion, check_run_updated_at }. Write; idempotent. Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Check whether CI is green before merging."
   },
   {
     name: "reopen_report",
     title: "Reopen report (operator)",
-    description: "Move a report to reopened for regression review.",
+    description: 'Move a previously fixed/verified/dismissed report back to the reopened state for regression review, recording an operator note. Returns { report } with status=reopened. Write; idempotent \u2014 reopening an already-reopened report is a no-op. Use when a reporter says "still broken" after a fix shipped; use transition_status for any other state change.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Reopen a regression the reporter flagged as not fixed."
@@ -330,7 +306,7 @@ var TOOL_CATALOG = [
   {
     name: "query_lessons",
     title: "Query lessons for diff context",
-    description: 'Token-budget retrieval of relevant learning rules (lessons) for a given code diff or PR context. Returns ranked lessons packed within max_tokens using bi-encoder retrieval + severity-weighted scoring. Use this before opening a PR, writing a fix, or asking "what mistakes should I avoid in this area of code?"',
+    description: 'Retrieve the learning rules ("lessons") most relevant to a given code diff or PR context, packed within a token budget. Uses bi-encoder retrieval + severity-weighted scoring; pass the diff/description as the query and max_tokens (default 2000). Returns ranked { lessons: [{ title, rule, severity }] }. Read-only. Use before writing a fix or opening a PR; use list_lessons to browse all lessons unfiltered.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What past mistakes should I avoid when making this change?"
@@ -338,17 +314,25 @@ var TOOL_CATALOG = [
   {
     name: "list_lessons",
     title: "List project lessons",
-    description: "List promoted learning rules (lessons) for the current project. Each lesson represents a named pattern of mistakes that has been encoded from bug reports. Use this to understand what systemic issues have been identified and encoded as heuristics.",
+    description: 'List promoted learning rules ("lessons") for the current project, highest-frequency first. Returns { lessons: [{ id, rule_text, severity, frequency, anti_pattern, \u2026 }] }. Read-only. Use to browse the full catalog of encoded heuristics; use query_lessons to retrieve only lessons relevant to a specific diff or PR within a token budget.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What systemic patterns has Mushi identified for this project?"
+  },
+  {
+    name: "activation_status",
+    title: "Activation cockpit status",
+    description: "Return the unified activation posture \u2014 SDK heartbeat, ingested reports, GitHub, MCP readiness, QA stories, and the next best action. Read this before guessing which onboarding step is blocking the user. Also available as the mushi://activation resource for resource-reader clients. Returns { sdkActive, reportsIngested, githubConnected, mcpConnected, qaStoriesCreated, nextBestAction }.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is Mushi fully set up and active for this project?"
   }
 ];
 var TDD_TOOL_CATALOG = [
   {
     name: "map_user_stories",
     title: "Map user stories from live app",
-    description: 'Crawl a live application URL with Firecrawl/Browserbase and ask Claude to draft an inventory.yaml with pages and user stories. Creates a story_map_run row for progress tracking, then writes an inventory_proposals row (source=live_crawl). Optionally dispatches a Cursor Cloud agent to refine the draft and open a PR. Returns { runId, status: "pending" } immediately \u2014 poll get_map_run_status for progress.',
+    description: 'Crawl a live application URL (Firecrawl/Browserbase) and have Claude draft an inventory.yaml of pages and user stories, written to an inventory_proposals row (source=live_crawl). Optionally dispatches a Cursor Cloud agent to refine the draft and open a PR. Returns { runId, status: "pending" } immediately \u2014 poll get_map_run_status. Write; consumes crawl + LLM budget; NOT idempotent. Use to bootstrap test coverage without hand-writing YAML; then generate_tdd_from_story per accepted story.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Map the user stories in my live app automatically without writing YAML by hand."
@@ -356,7 +340,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "get_map_run_status",
     title: "Story map run status",
-    description: "Get the status and results of a story_map_run (pending \u2192 running \u2192 completed/failed). Returns pages_crawled, proposal_id (once done), and cursor_pr_url if Cursor Cloud refined the draft.",
+    description: "Poll the status and results of a story_map_run started by map_user_stories. Returns { status: pending|running|completed|failed, pages_crawled, proposal_id (once done), cursor_pr_url (if Cursor Cloud refined the draft) }. Read-only. Use to know when a crawl has finished and which inventory_proposals row to review next.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is my story mapping crawl done yet?"
@@ -364,7 +348,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "generate_tdd_from_story",
     title: "Generate TDD test from user story",
-    description: "Given a user story id (from the accepted inventory), ask Claude to write a full Playwright TypeScript test. Inserts a qa_stories row (source=test_gen_from_story) with approval_status driven by automation_mode. Optionally opens a draft GitHub PR. Returns { qaStoryId, prUrl, approvalStatus, needsHumanReview }.",
+    description: "Generate a full Playwright TypeScript test from a mapped user story id (from accepted inventory) using Claude, and insert a qa_stories row (source=test_gen_from_story). approval_status follows the project automation_mode (auto = enabled immediately; review/approve = pending_review). Optionally opens a draft GitHub PR. Returns { qaStoryId, prUrl, approvalStatus, needsHumanReview }. Write; consumes LLM budget; NOT idempotent. Run map_user_stories first; use test_gen_from_report to build a test from a bug report instead.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Generate a Playwright test for this user story."
@@ -372,7 +356,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "improve_qa_story",
     title: "Auto-improve a failing QA story",
-    description: "Find recently failed qa_story_runs and use Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
+    description: "Analyze recently failed qa_story_runs and use Claude to write improved test scripts that address the failures. New tests are created with source=pdca, parent_story_id chained to the original, and approval gated by the original story's automation_mode. Returns { improvedStoryIds }. Write; consumes LLM budget; NOT idempotent. Use to repair flaky/broken tests; use run_qa_story to re-run as-is, or list_qa_story_runs to inspect failures first.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Fix my failing QA tests automatically."
@@ -380,7 +364,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "run_qa_story",
     title: "Trigger a manual QA story run",
-    description: 'Queue a manual run for an enabled + approved qa_story. Returns the run id immediately; poll qa_story_runs or use get_report_detail for progress. Equivalent to "Run now" in the console.',
+    description: 'Queue an immediate manual run for an enabled + approved qa_story (equivalent to "Run now" in the console). Returns { runId } right away; poll list_qa_story_runs or get_qa_story_run for progress and results. Write; NOT idempotent \u2014 each call creates a new run; returns 409 if the story is disabled or pending review. Use to verify a flow on demand; use improve_qa_story to repair a failing story.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Run the login flow test right now."
@@ -388,7 +372,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_byok_keys",
     title: "List your API key pool",
-    description: "List all project API keys, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
+    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | firecrawl | browserbase | cursor). Returns { keys: [{ id, provider, label, priority, status, cooldownUntil }] } \u2014 metadata only, never the raw secret. Read-only. Use to see which keys are active vs rate-limited/exhausted; use add_byok_key to add one.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
@@ -396,7 +380,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "add_byok_key",
     title: "Add an API key",
-    description: "Add a new API key to the project pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
+    description: "Add a BYOK API key to the project pool for a provider (anthropic | openai | firecrawl | browserbase | cursor), with a label and priority for failover ordering. The raw key is stored encrypted in Supabase Vault and never returned. Returns { id, provider, label }. Write; NOT idempotent \u2014 adds a new row each call. Use to register a backup/rotated key; use list_byok_keys to review the pool.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."
@@ -404,7 +388,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_pending_review_stories",
     title: "List QA stories pending review",
-    description: "Get the queue of TDD tests that were auto-generated and are waiting for human approval before they run in the QA schedule.",
+    description: "List auto-generated QA/TDD stories in approval_status=pending_review \u2014 the queue waiting for human sign-off before they run on schedule. Returns { stories: [{ id, title, source, target_url, created_at }] }. Read-only. Use to find what needs review today; then approve_qa_story to approve or reject each.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What TDD tests need my approval today?"
@@ -412,7 +396,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "approve_qa_story",
     title: "Approve or reject a pending QA story",
-    description: "Approve or reject a qa_story that is in pending_review. Approved stories are enabled in the QA schedule immediately.",
+    description: "Approve or reject a qa_story currently in pending_review (pass approve=true|false and an optional note). Approved stories are enabled in the QA schedule immediately; rejected ones are disabled. Returns { id, approval_status }. Write; idempotent \u2014 re-approving an approved story is a no-op. Use to clear the review queue from list_pending_review_stories.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Approve this auto-generated test."
@@ -470,7 +454,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_skills",
     title: "List agent skills",
-    description: "List the agent skills available in the catalog, optionally filtered by category. Returns slug, title, description, category, and chain_slugs for each skill. Use before start_skill_pipeline to find the right skill slug for a given type of work.",
+    description: "List the agent skills in the catalog, optionally filtered by category or search text. Returns { skills: [{ slug, title, description, category, chain_slugs }] }. Read-only. Use to find the right skill slug before start_skill_pipeline; use get_skill to read one skill's full instructions.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What skills are available for debugging production errors?"
@@ -478,7 +462,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "get_skill",
     title: "Get skill detail",
-    description: "Fetch the full detail for a single agent skill by slug, including the complete SKILL.md body and resolved chain. Use before executing a step to understand what the skill expects you to do.",
+    description: "Fetch one agent skill by slug, including the complete SKILL.md body and the resolved chain of sub-skills. Returns { slug, title, body, chain: [{ slug, title }] }. Read-only. Use to read what a skill instructs before executing a pipeline step; use list_skills to discover slugs.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What does workflow-fix-and-ship actually instruct me to do?"
@@ -494,7 +478,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "get_pipeline_run",
     title: "Get pipeline run detail",
-    description: "Fetch the full detail for a skill pipeline run: status, context_packet, and all step statuses. Call to retrieve the context_packet after a pipeline was started from the console or another agent.",
+    description: "Fetch a skill pipeline run by id: { status, context_packet, steps: [{ index, slug, status }] }. Read-only. Use to retrieve the context_packet when a pipeline was started from the console or another agent; then checkin_pipeline_step as you complete each step. Use start_skill_pipeline to begin a new run.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me the context packet and step status for this pipeline run."
@@ -507,22 +491,6 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "I just opened the PR \u2014 mark step 2 as passed and link the PR."
   },
-  {
-    name: "get_activation_status",
-    title: "Activation cockpit status",
-    description: "[Deprecated \u2014 use activation_status resource or tool on hosted MCP.] Unified setup posture for the active project: required steps, SDK heartbeat, dispatch preflight, and the next best action.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "What is blocking this project from going live?"
-  },
-  {
-    name: "get_reporter_thread",
-    title: "Reporter feedback thread",
-    description: "[Deprecated \u2014 use get_report_timeline instead.] Fetch the unified timeline for a report \u2014 reporter comments plus fix, QA, and status lanes.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "What did the reporter say after we marked this fixed?"
-  },
   // ── Full-Stack Audit tools (Phase 5) ────────────────────────────────────────
   {
     name: "run_fullstack_audit",
@@ -545,7 +513,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "ask_codebase",
     title: "Ask about the indexed codebase",
-    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and your Anthropic or OpenAI API key.",
+    description: 'Answer a plain-English question about the connected repo, grounded on pgvector retrieval over project_codebase_files. Returns { answer, citations: [{ path, line }] }. Set include_wiki=true to merge docs/wiki knowledge. Requires codebase indexing + your Anthropic or OpenAI key; consumes LLM budget (write scope). Use for "how does X work?"; use search_codebase for raw file matches without synthesis, or get_file_summary for one file.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "How does authentication work in this repo?"
@@ -553,7 +521,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "get_file_summary",
     title: "Plain-English file summary",
-    description: "Lazy-generate (or return cached) plain-English summary for an indexed file or symbol. Cache invalidates when content_hash changes after re-index.",
+    description: "Return a plain-English summary of one indexed file or symbol (lazily generated on first call, then cached until content_hash changes on re-index). Returns { path, summary, symbols }. Requires codebase indexing. Read-only. Use to understand a single file fast; use ask_codebase for cross-file questions, or get_codebase_tour for an onboarding walkthrough.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Explain what lib/auth.ts does in plain English."
@@ -561,7 +529,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "get_codebase_tour",
     title: "Guided codebase tour",
-    description: "Return a dependency-ordered guided tour (~6\u201310 stops) for onboarding \u2014 each stop lists node ids, file paths, layer, and rationale. Cached per index fingerprint.",
+    description: "Return a dependency-ordered onboarding tour of the repo (~6-10 stops); each stop lists node ids, file paths, architectural layer, and why it matters. Returns { stops: [{ title, paths, layer, rationale }] }. Cached per index fingerprint. Requires codebase indexing. Read-only. Use to get oriented in an unfamiliar repo; use get_codebase_domains for a business-domain map, or get_file_summary for one file.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me an onboarding walkthrough of this codebase."
@@ -569,7 +537,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "search_codebase",
     title: "Semantic codebase search",
-    description: "Search indexed files by plain-English meaning via embeddings. Returns top-k file chunks with similarity scores.",
+    description: 'Search the indexed repo by plain-English meaning via embeddings. Returns { results: [{ file_path, line_start, line_end, content_preview, similarity, \u2026 }], query, mode } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives ("where do we verify webhooks?"); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Find files related to authentication or payment handling."
@@ -577,7 +545,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "get_codebase_domains",
     title: "Business domain map",
-    description: "Extract business domains, flows, and steps mapped to file paths. Cached per index fingerprint.",
+    description: "Extract the business domains, flows, and steps in the repo, each mapped to the file paths that implement it. Returns { domains: [{ name, flows: [{ name, steps, paths }] }] }. Cached per index fingerprint. Requires codebase indexing. Read-only. Use to see what the app does at a product level; use get_codebase_tour for a dependency-ordered code walkthrough instead.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What business domains does this codebase implement?"
@@ -585,7 +553,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "analyze_codebase_impact",
     title: "Diff impact analysis",
-    description: "Find files that depend on changed paths (reverse import graph). Supports manual paths, last push, GitHub compare, or fix PR files.",
+    description: "Find files that depend on a set of changed paths by walking the reverse import graph. Source paths from: manual list, last push, a GitHub compare range, or a fix PR's files. Returns { changed_paths, source, affected_file_paths, affected_node_ids, meta }. Requires codebase indexing. Read-only. Use to gauge a diff's blast radius before merging; use get_blast_radius for a bug's component impact, or search_codebase to locate files.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What breaks if I change lib/auth.ts?"
@@ -593,7 +561,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "analyze_wiki_knowledge",
     title: "Wiki knowledge graph",
-    description: "Return wiki/docs knowledge graph nodes and sources for the project. Use include_wiki on ask_codebase for RAG merge.",
+    description: "Return the wiki/docs knowledge-graph nodes and their sources for the project. Returns { nodes: [{ id, label, source_url }], sources }. Read-only. Use to see what doc entities exist; pass include_wiki=true to ask_codebase to merge this corpus into a grounded answer.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What docs entities exist for onboarding?"
@@ -613,10 +581,17 @@ var FEATURE_GROUPS = [
   "audit",
   "docs",
   "usage",
-  "usage",
+  "codebase",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
+var DEFAULT_FEATURE_GROUPS = [
+  "triage",
+  "fixes",
+  "inventory",
+  "setup",
+  "docs"
+];
 var ALL_FEATURE_GROUPS = FEATURE_GROUPS.filter(
   (g) => g !== "legacy"
 );
@@ -636,21 +611,16 @@ var TOOL_FEATURE_MAP = {
   triage_issue: "triage",
   query_lessons: "triage",
   list_lessons: "triage",
-  fix_suggest: "triage",
-  graph_neighborhood: "triage",
-  graph_node_status: "triage",
-  get_reporter_thread: "legacy",
+  suggest_fix: "triage",
+  get_graph_neighborhood: "triage",
+  get_graph_node: "triage",
   // inventory
-  inventory_get: "inventory",
-  inventory_diff: "inventory",
-  inventory_findings: "inventory",
+  get_inventory: "inventory",
+  diff_inventory: "inventory",
+  list_gate_findings: "inventory",
   inventory_current: "admin",
   // setup
-  diagnose_connection: "setup",
   diagnose_setup: "setup",
-  setup_check: "legacy",
-  ingest_setup_check: "legacy",
-  get_activation_status: "legacy",
   activation_status: "setup",
   project_integration_health: "setup",
   setup_repo_for_mushi: "setup",
@@ -703,16 +673,44 @@ var TOOL_FEATURE_MAP = {
   // audit
   run_fullstack_audit: "audit",
   get_backend_health: "audit",
+  // codebase understand
+  ask_codebase: "codebase",
+  get_file_summary: "codebase",
+  get_codebase_tour: "codebase",
+  search_codebase: "codebase",
+  get_codebase_domains: "codebase",
+  analyze_codebase_impact: "codebase",
+  analyze_wiki_knowledge: "codebase",
   // docs
   search_mushi_docs: "docs"
 };
+var DEPRECATED_TOOL_ALIASES = {
+  // Removed deprecated tools → successor.
+  setup_check: "diagnose_setup",
+  ingest_setup_check: "diagnose_setup",
+  diagnose_connection: "diagnose_setup",
+  get_activation_status: "activation_status",
+  get_reporter_thread: "get_report_timeline",
+  // Renamed to verb_object → new name.
+  fix_suggest: "suggest_fix",
+  inventory_get: "get_inventory",
+  inventory_diff: "diff_inventory",
+  inventory_findings: "list_gate_findings",
+  graph_neighborhood: "get_graph_neighborhood",
+  graph_node_status: "get_graph_node"
+};
 function parseFeaturesParam(raw) {
   if (raw == null || raw.trim() === "") return "all";
   const normalized = raw.trim().toLowerCase();
   if (normalized === "all" || normalized === "*") return "all";
   const groups = normalized.split(",").map((s) => s.trim()).filter(Boolean);
   const valid = groups.filter((g) => FEATURE_GROUPS.includes(g));
-  if (valid.length === 0) return "all";
+  if (valid.length === 0) {
+    console.warn(
+      `[mushi-mcp] MUSHI_FEATURES="${raw}" contains no recognised groups; falling back to DEFAULT_FEATURE_GROUPS. Valid groups: ${FEATURE_GROUPS.join(", ")}`
+    );
+    return DEFAULT_FEATURE_GROUPS;
+  }
   return valid;
 }
 function parseFeaturesCsv(raw) {
@@ -780,8 +778,8 @@ var MUSHI_DOCS_INDEX = [
   {
     title: "Cursor MCP troubleshooting",
     path: `${BASE}/guides/mcp-setup`,
-    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_connection"],
-    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_connection."
+    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_setup"],
+    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_setup."
   },
   {
     title: "Judge loop",
@@ -1224,8 +1222,12 @@ function createMushiServer(config) {
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        seed: z.string().describe("Starting graph node id or human-readable label to traverse from"),
+        depth: z.number().optional().describe("BFS hops outward from seed \u2014 clamped to 4 in the handler (default 2)")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -1233,18 +1235,23 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "graph_neighborhood",
+    "get_graph_neighborhood",
     {
-      title: titleOf("graph_neighborhood"),
-      description: descOf("graph_neighborhood"),
-      annotations: annotationsFor("graph_neighborhood"),
+      title: titleOf("get_graph_neighborhood"),
+      description: descOf("get_graph_neighborhood"),
+      annotations: annotationsFor("get_graph_neighborhood"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        seed: z.string().describe("Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"),
+        depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -1252,88 +1259,108 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "graph_node_status",
+    "get_graph_node",
     {
-      title: titleOf("graph_node_status"),
-      description: descOf("graph_node_status"),
-      annotations: annotationsFor("graph_node_status"),
-      inputSchema: { nodeId: z.string().describe("graph_nodes.id") }
+      title: titleOf("get_graph_node"),
+      description: descOf("get_graph_node"),
+      annotations: annotationsFor("get_graph_node"),
+      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      outputSchema: {
+        node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
+    async (args) => {
+      const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
+      return jsonResult(data);
+    }
   );
   server.registerTool(
-    "inventory_get",
+    "get_inventory",
     {
-      title: titleOf("inventory_get"),
-      description: descOf("inventory_get"),
-      annotations: annotationsFor("inventory_get"),
+      title: titleOf("get_inventory"),
+      description: descOf("get_inventory"),
+      annotations: annotationsFor("get_inventory"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to the server-configured project when omitted")
       }
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_get");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
   server.registerTool(
-    "inventory_diff",
+    "diff_inventory",
     {
-      title: titleOf("inventory_diff"),
-      description: descOf("inventory_diff"),
-      annotations: annotationsFor("inventory_diff"),
+      title: titleOf("diff_inventory"),
+      description: descOf("diff_inventory"),
+      annotations: annotationsFor("diff_inventory"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
-        fromSha: z.string().describe("Older commit SHA (baseline)"),
-        toSha: z.string().describe("Newer commit SHA (candidate)")
+        fromSha: z.string().describe("Older commit SHA (the baseline to diff from)"),
+        toSha: z.string().describe("Newer commit SHA (the candidate to diff to)")
       }
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_diff");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
       const q = new URLSearchParams({ from: args.fromSha, to: args.toSha });
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
   );
   server.registerTool(
-    "inventory_findings",
+    "list_gate_findings",
     {
-      title: titleOf("inventory_findings"),
-      description: descOf("inventory_findings"),
-      annotations: annotationsFor("inventory_findings"),
+      title: titleOf("list_gate_findings"),
+      description: descOf("list_gate_findings"),
+      annotations: annotationsFor("list_gate_findings"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
-        gate: z.string().optional().describe("Filter by gate id (e.g. dead_handler, status_claim)"),
-        severity: z.string().optional().describe("Filter findings by severity")
+        gate: z.string().optional().describe("Filter to one gate id: dead-handler | mock-leak | crawl | status-claim"),
+        severity: z.string().optional().describe("Minimum severity to include: low | medium | high | critical")
+      },
+      outputSchema: {
+        runs: z.array(z.unknown()).describe("Recent gate_runs rows, newest first"),
+        findings: z.array(z.unknown()).describe("gate_findings rows for those runs")
       }
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_findings");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for list_gate_findings");
       const q = new URLSearchParams();
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
+      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "fix_suggest",
+    "suggest_fix",
     {
-      title: titleOf("fix_suggest"),
-      description: descOf("fix_suggest"),
-      annotations: annotationsFor("fix_suggest"),
-      inputSchema: { reportId: z.string().describe("Report UUID") }
+      title: titleOf("suggest_fix"),
+      description: descOf("suggest_fix"),
+      annotations: annotationsFor("suggest_fix"),
+      inputSchema: { reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for") },
+      outputSchema: {
+        reportId: z.string().describe("The report this slice was read from"),
+        rootCause: z.unknown().describe("Stage-2 root-cause hint, or null if not yet classified"),
+        suggestedFix: z.unknown().describe("Stage-2 suggested fix, or null if not yet classified"),
+        reproductionSteps: z.unknown().describe("Reproduction steps recorded on the report (array; [] if none)"),
+        summary: z.unknown().describe("One-line report summary, or null"),
+        component: z.unknown().describe("Component/page the bug was attributed to, or null")
+      }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       const s2 = report.stage2_analysis;
-      return jsonText({
+      return jsonResult({
         reportId: args.reportId,
         rootCause: s2?.rootCause ?? null,
         suggestedFix: s2?.suggestedFix ?? null,
@@ -1359,73 +1386,6 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  server.registerTool(
-    "setup_check",
-    {
-      title: titleOf("setup_check"),
-      description: descOf("setup_check"),
-      annotations: annotationsFor("setup_check"),
-      inputSchema: {
-        projectId: z.string().optional().describe(
-          "Project UUID to check. Falls back to the projectId the server was initialised with."
-        )
-      }
-    },
-    async (args) => {
-      const resolvedId = args.projectId ?? projectId;
-      if (!resolvedId) {
-        return jsonText({
-          ok: false,
-          error: "No projectId provided and none configured on the MCP server. Pass projectId explicitly."
-        });
-      }
-      const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
-      const summary = data.checks.map((c) => ({
-        check: c.key,
-        label: c.label,
-        passed: c.ready,
-        hint: c.hint,
-        fixPath: c.fixHref
-      }));
-      return jsonText({
-        ready: data.ready,
-        repoUrl: data.repoUrl ?? null,
-        checks: summary,
-        // Human-readable summary for agents that paste the result into a prompt
-        summary: data.ready ? `Project ${resolvedId} is ready to dispatch auto-fixes${data.repoUrl ? ` (target: ${data.repoUrl})` : ""}.` : `Project ${resolvedId} cannot dispatch yet \u2014 ${summary.filter((c) => !c.passed).map((c) => c.label).join(", ")}.`
-      });
-    }
-  );
-  server.registerTool(
-    "ingest_setup_check",
-    {
-      title: titleOf("ingest_setup_check"),
-      description: descOf("ingest_setup_check"),
-      annotations: annotationsFor("ingest_setup_check"),
-      inputSchema: NO_ARG_INPUT
-    },
-    async () => {
-      const data = await apiCall("/v1/sync/ingest-setup");
-      const failed = data.steps.filter((s) => s.required && !s.complete);
-      const summary = data.ready ? `Ingest setup complete (${data.required_complete}/${data.required_total}) for ${data.project_name}.` : `Ingest incomplete (${data.required_complete}/${data.required_total}) \u2014 still need: ${failed.map((s) => s.label).join(", ")}.`;
-      return jsonText({
-        ready: data.ready,
-        projectId: data.project_id,
-        projectName: data.project_name,
-        requiredComplete: data.required_complete,
-        requiredTotal: data.required_total,
-        steps: data.steps.map((s) => ({
-          id: s.id,
-          label: s.label,
-          passed: s.complete,
-          required: s.required,
-          hint: s.hint
-        })),
-        diagnostic: data.diagnostic ?? null,
-        summary
-      });
-    }
-  );
   server.registerTool(
     "diagnose_setup",
     {
@@ -1443,7 +1403,8 @@ function createMushiServer(config) {
         summary: z.string(),
         nextAction: z.string().optional(),
         ingest: z.unknown().optional(),
-        dispatch: z.unknown().optional()
+        dispatch: z.unknown().optional(),
+        connection: z.unknown().optional()
       }
     },
     async (args) => {
@@ -1483,162 +1444,99 @@ function createMushiServer(config) {
           dispatch: { repoUrl: data.repoUrl ?? null, checks: data.checks }
         });
       }
-      const ingest = await apiCall("/v1/sync/ingest-setup");
-      let dispatchReady = true;
-      let dispatchBlock;
-      let dispatchChecks = null;
-      if (resolvedId) {
-        try {
-          const preflight = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
-          dispatchReady = preflight.ready;
-          dispatchChecks = preflight.checks;
-          if (!preflight.ready) {
-            const failed = preflight.checks.filter((c) => !c.ready);
-            dispatchBlock = failed[0]?.hint;
-          }
-        } catch (err) {
-          dispatchReady = false;
-          const detail = err instanceof Error ? err.message : String(err);
-          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
-          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
-        }
-      }
-      const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
-      const ingestBlock = ingestFailed[0]?.hint;
-      const ready = ingest.ready && dispatchReady;
-      const nextAction = !ingest.ready ? ingestBlock ?? "Complete SDK ingest setup." : !dispatchReady ? dispatchBlock ?? "Complete dispatch preflight in Settings \u2192 Integrations." : "All setup checks pass \u2014 submit a test report to confirm end-to-end.";
-      const summary = ready ? "Mushi ingest and dispatch setup look healthy." : !ingest.ready ? `Ingest incomplete \u2014 ${ingestFailed.map((s) => s.label).join(", ")}.` : "Ingest OK; dispatch preflight still has blockers.";
-      return jsonResult({
-        mode: "full",
-        ready,
-        summary,
-        nextAction,
-        ingest: { ready: ingest.ready, steps: ingest.steps },
-        dispatch: resolvedId ? { ready: dispatchReady, checks: dispatchChecks } : null
-      });
-    }
-  );
-  server.registerTool(
-    "diagnose_connection",
-    {
-      title: titleOf("diagnose_connection"),
-      description: descOf("diagnose_connection"),
-      annotations: annotationsFor("diagnose_connection"),
-      inputSchema: NO_ARG_INPUT,
-      outputSchema: {
-        ready: z.boolean(),
-        healthOk: z.boolean(),
-        ingestReady: z.boolean(),
-        dispatchReady: z.boolean(),
-        endpoint: z.string().nullable(),
-        projectId: z.string().nullable(),
-        accessibleProjectCount: z.number().nullable(),
-        issues: z.array(z.unknown()),
-        nextAction: z.string(),
-        summary: z.string()
-      }
-    },
-    async () => {
-      const issues = [];
+      const connIssues = [];
+      let healthOk = false;
       if (!apiKey?.startsWith("mushi_")) {
-        issues.push({
+        connIssues.push({
           check: "mcp_api_key",
-          detail: "MCP server API key missing or malformed",
-          fix: "Run `mushi connect` to write MUSHI_API_KEY into .cursor/mcp.json, then restart the MCP server."
+          detail: "MCP server API key missing or malformed (expected prefix: mushi_)",
+          fix: "Run `mushi connect` or set MUSHI_API_KEY to a valid key in your MCP config."
         });
       }
       if (!apiEndpoint) {
-        issues.push({
+        connIssues.push({
           check: "mcp_endpoint",
           detail: "No API endpoint configured",
-          fix: "Set MUSHI_API_ENDPOINT to your `\u2026/functions/v1/api` URL in .cursor/mcp.json."
+          fix: "Set MUSHI_API_ENDPOINT to your `.../functions/v1/api` URL in your MCP config."
         });
-      }
-      let healthOk = false;
-      if (apiEndpoint) {
+      } else {
         try {
           const healthRes = await doFetch(`${apiEndpoint.replace(/\/$/, "")}/health`, {
             signal: AbortSignal.timeout(5e3)
           });
           healthOk = healthRes.status === 200;
           if (!healthOk) {
-            issues.push({
+            connIssues.push({
               check: "endpoint_health",
               detail: `GET /health \u2192 HTTP ${healthRes.status}`,
               fix: "Verify MUSHI_API_ENDPOINT and that the Supabase edge function is deployed."
             });
           }
         } catch (err) {
-          issues.push({
+          connIssues.push({
             check: "endpoint_health",
             detail: err instanceof Error ? err.message : String(err),
-            fix: "Check network connectivity and the endpoint URL in .cursor/mcp.json."
+            fix: "Check network connectivity and MUSHI_API_ENDPOINT in your MCP config."
           });
         }
       }
-      let ingestReady = false;
-      let dispatchReady = false;
       let accessibleProjectCount = null;
-      if (!projectId && healthOk) {
+      if (!resolvedId && healthOk) {
         try {
-          const overview = await apiCall("/v1/admin/mcp/account-overview");
+          const overview = await apiCall(
+            "/v1/admin/mcp/account-overview"
+          );
           accessibleProjectCount = overview.total;
           if (overview.total === 0) {
-            issues.push({
+            connIssues.push({
               check: "no_accessible_projects",
               detail: "API key has no accessible projects",
-              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID to restrict to a single project."
+              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID."
             });
           }
         } catch {
         }
       }
-      try {
-        const ingest = await apiCall("/v1/sync/ingest-setup");
-        ingestReady = ingest.ready;
-        if (!ingest.ready) {
-          const failed = ingest.steps.filter((s) => s.required && !s.complete);
-          issues.push({
-            check: "ingest_setup",
-            detail: `Incomplete: ${failed.map((s) => s.label).join(", ")}`,
-            fix: failed[0]?.hint ?? "Paste the SDK snippet, start your dev server, submit a test report."
-          });
-        }
-      } catch (err) {
-        issues.push({
-          check: "ingest_setup",
-          detail: err instanceof Error ? err.message : String(err),
-          fix: "Confirm API key is active for this project (Projects \u2192 API Keys)."
-        });
-      }
-      if (projectId) {
+      const ingest = await apiCall("/v1/sync/ingest-setup");
+      let dispatchReady = true;
+      let dispatchBlock;
+      let dispatchChecks = null;
+      if (resolvedId) {
         try {
-          const preflight = await apiCall(`/v1/admin/projects/${projectId}/preflight`);
+          const preflight = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
           dispatchReady = preflight.ready;
+          dispatchChecks = preflight.checks;
           if (!preflight.ready) {
             const failed = preflight.checks.filter((c) => !c.ready);
-            issues.push({
-              check: "dispatch_preflight",
-              detail: `Blocked: ${failed.map((c) => c.label).join(", ")}`,
-              fix: failed[0]?.hint ?? "Open Settings \u2192 Integrations and complete GitHub + BYOK setup."
-            });
+            dispatchBlock = failed[0]?.hint;
           }
-        } catch {
+        } catch (err) {
+          dispatchReady = false;
+          const detail = err instanceof Error ? err.message : String(err);
+          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
+          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
         }
       }
-      const ready = issues.length === 0 && healthOk && ingestReady;
-      const nextAction = issues[0]?.fix ?? (ready ? "Connection healthy \u2014 SDK ingest is working. Submit a report to confirm end-to-end." : "Run `mushi doctor` in your app repo for a full local checklist.");
+      const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
+      const ingestBlock = ingestFailed[0]?.hint;
+      const connOk = connIssues.length === 0;
+      const ready = connOk && ingest.ready && dispatchReady;
+      const nextAction = !connOk ? connIssues[0]?.fix ?? "Fix the connection issue above." : !ingest.ready ? ingestBlock ?? "Complete SDK ingest setup." : !dispatchReady ? dispatchBlock ?? "Complete dispatch preflight in Settings \u2192 Integrations." : "All setup checks pass \u2014 submit a test report to confirm end-to-end.";
+      const summary = ready ? "Mushi connection, ingest, and dispatch setup look healthy." : !connOk ? `Connection issue \u2014 ${connIssues[0]?.check}: ${connIssues[0]?.detail}` : !ingest.ready ? `Ingest incomplete \u2014 ${ingestFailed.map((s) => s.label).join(", ")}.` : "Ingest OK; dispatch preflight still has blockers.";
       return jsonResult({
+        mode: "full",
         ready,
-        healthOk,
-        ingestReady,
-        dispatchReady,
-        endpoint: apiEndpoint ?? null,
-        projectId: projectId ?? null,
-        accessibleProjectCount,
-        issues,
+        summary,
         nextAction,
-        summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
+        connection: {
+          healthOk,
+          endpoint: apiEndpoint ?? null,
+          projectId: resolvedId ?? null,
+          accessibleProjectCount,
+          issues: connIssues
+        },
+        ingest: { ready: ingest.ready, steps: ingest.steps },
+        dispatch: resolvedId ? { ready: dispatchReady, checks: dispatchChecks } : null
       });
     }
   );
@@ -1929,13 +1827,17 @@ function createMushiServer(config) {
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
       inputSchema: {
-        reportId: z.string().describe("The report UUID"),
-        branch: z.string().describe("Git branch name"),
-        prUrl: z.string().optional().describe("GitHub PR URL"),
-        filesChanged: z.array(z.string()).describe("Files modified"),
-        linesChanged: z.number().describe("Total lines changed"),
-        summary: z.string().describe("Fix summary"),
+        reportId: z.string().describe("Report UUID to attach this external fix attempt to"),
+        branch: z.string().describe("Git branch name where the fix was implemented"),
+        prUrl: z.string().optional().describe("GitHub pull request URL, if a PR was opened"),
+        filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
+        linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
+        summary: z.string().describe("One-line human summary of what the fix changed"),
         idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+      },
+      outputSchema: {
+        ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
+        fixId: z.string().describe("UUID of the new fix_attempt row")
       }
     },
     async (args) => {
@@ -1957,7 +1859,7 @@ function createMushiServer(config) {
           completed_at: (/* @__PURE__ */ new Date()).toISOString()
         })
       });
-      return jsonText({ ok: true, fixId: created.fixId });
+      return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
   server.registerTool(
@@ -2014,6 +1916,9 @@ function createMushiServer(config) {
       inputSchema: {
         limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
         projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
+      },
+      outputSchema: {
+        dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
       }
     },
     async (args) => {
@@ -2024,7 +1929,7 @@ function createMushiServer(config) {
           projectId: args.projectId ?? projectId ?? void 0
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2051,12 +1956,18 @@ function createMushiServer(config) {
   server.registerTool(
     "merge_fix",
     {
-      title: "Merge fix PR",
-      description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+      title: titleOf("merge_fix"),
+      description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID"),
-        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+        fixId: z.string().describe("Fix attempt UUID whose GitHub PR should be squash-merged"),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method (default squash)")
+      },
+      outputSchema: {
+        merged: z.boolean().optional().describe("True when GitHub accepted the merge in this call"),
+        alreadyMerged: z.boolean().optional().describe("True when the PR was already merged (idempotent no-op)"),
+        reportId: z.string().describe("Report UUID linked to this fix attempt"),
+        reportStatus: z.string().describe("Report workflow status after merge bookkeeping")
       }
     },
     async (args) => {
@@ -2064,22 +1975,27 @@ function createMushiServer(config) {
         method: "POST",
         body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
     "refresh_ci",
     {
-      title: "Refresh fix CI status",
-      description: "Pull the latest GitHub check-run status for a fix attempt.",
+      title: titleOf("refresh_ci"),
+      description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID")
+        fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
+      },
+      outputSchema: {
+        check_run_status: z.string().nullable().describe("GitHub check run status after refresh"),
+        check_run_conclusion: z.string().nullable().describe("success | failure | neutral | null while pending"),
+        check_run_updated_at: z.string().nullable().describe("ISO timestamp when CI status was last persisted")
       }
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2089,16 +2005,19 @@ function createMushiServer(config) {
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID"),
-        note: z.string().optional().describe("Triage note")
+        reportId: z.string().describe("Report UUID to move back to reopened status"),
+        note: z.string().optional().describe("Operator note recorded on the reopen transition")
+      },
+      outputSchema: {
+        report: z.unknown().describe("Updated report row with status=reopened")
       }
     },
     async (args) => {
-      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+      const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
         method: "PATCH",
         body: JSON.stringify({ status: "reopened", note: args.note })
       });
-      return jsonText(data);
+      return jsonResult({ report });
     }
   );
   server.registerTool(
@@ -2175,9 +2094,12 @@ function createMushiServer(config) {
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
       inputSchema: {
-        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter by severity level."),
-        limit: z.number().optional().describe("Max number of lessons to return (default 50, max 200)."),
-        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter to one severity level"),
+        limit: z.number().optional().describe("Max lessons to return (default 50, max 200)"),
+        project_id: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      },
+      outputSchema: {
+        lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
       }
     },
     async (args) => {
@@ -2186,8 +2108,8 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 50, 200)));
       if (pid) params.set("projectId", pid);
-      const data = await apiCall(`/v1/admin/lessons?${params}`);
-      return jsonText(data);
+      const lessons = await apiCall(`/v1/admin/lessons?${params}`);
+      return jsonResult({ lessons });
     }
   );
   server.resource(
@@ -2353,6 +2275,22 @@ function createMushiServer(config) {
       };
     }
   );
+  server.registerTool(
+    "activation_status",
+    {
+      title: titleOf("activation_status"),
+      description: descOf("activation_status"),
+      annotations: annotationsFor("activation_status"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to the configured project).")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const qs = pid ? `?project_id=${encodeURIComponent(pid)}` : "";
+      return jsonResult(await apiCall(`/v1/admin/activation${qs}`));
+    }
+  );
   server.resource(
     "activation_status",
     "mushi://activation",
@@ -2451,7 +2389,7 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
           text: `You are a Mushi onboarding copilot. Use the MCP tools:
 1. Read mushi://activation for unified setup posture.
 2. Read project://integration-health if GitHub or Sentry looks blocked.
-3. Call get_activation_status if the resource is unavailable.
+3. Call diagnose_setup if the resource is unavailable.
 
 Then output:
 - **Status:** one sentence on what is done vs blocked
@@ -2509,11 +2447,17 @@ Be specific. No generic advice.`
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
-        projectId: z.string().describe("Project id"),
-        storyNodeId: z.string().describe("User story id slug from the accepted inventory"),
-        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Gate mode for the generated test (default: review)"),
-        baseUrl: z.string().url().optional().describe("Override the app base URL"),
-        openPr: z.boolean().optional().describe("Open a draft GitHub PR (default: true)")
+        projectId: z.string().describe("Project UUID that owns the inventory story"),
+        storyNodeId: z.string().describe("User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"),
+        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
+        baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
+        openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
+      },
+      outputSchema: {
+        qaStoryId: z.string().describe("UUID of the inserted qa_stories row"),
+        prUrl: z.string().nullable().describe("GitHub PR URL when openPr=true and GitHub is connected"),
+        approvalStatus: z.string().describe("pending_review | approved \u2014 follows automationMode and project defaults"),
+        needsHumanReview: z.boolean().describe("True when the story requires operator approval before scheduled runs")
       }
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
@@ -2522,7 +2466,7 @@ Be specific. No generic advice.`
         `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
         { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
       );
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2884,36 +2828,6 @@ Be specific. No generic advice.`
       return jsonText({ ok: true, message: `Step ${step_index} \u2192 ${args.status}` });
     }
   );
-  server.registerTool(
-    "get_activation_status",
-    {
-      title: titleOf("get_activation_status"),
-      description: descOf("get_activation_status"),
-      annotations: annotationsFor("get_activation_status"),
-      inputSchema: {
-        project_id: z.string().optional().describe("Optional project UUID override")
-      }
-    },
-    async (args) => {
-      const qs = args.project_id ? `?project_id=${encodeURIComponent(args.project_id)}` : "";
-      const data = await apiCall(`/v1/admin/activation${qs}`);
-      return jsonText(data);
-    }
-  );
-  server.registerTool(
-    "get_reporter_thread",
-    {
-      title: titleOf("get_reporter_thread"),
-      description: descOf("get_reporter_thread"),
-      annotations: annotationsFor("get_reporter_thread"),
-      inputSchema: { reportId: z.string().describe("The report UUID") }
-    },
-    // The reporter thread is the `comments` lane of the unified report
-    // timeline. There is no standalone admin `/comments` route (only the
-    // reporter-token-gated `/v1/reporter/reports/:id/comments`), so we read the
-    // admin-authed timeline, which also carries fix / QA / status lanes.
-    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}/timeline`))
-  );
   server.registerTool(
     "ask_codebase",
     {
@@ -2998,23 +2912,31 @@ Be specific. No generic advice.`
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        query: z.string().describe("Plain-English search query"),
-        k: z.number().optional().describe("Number of results (default 8, max 20)"),
-        scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
+        query: z.string().describe("Plain-English search query against indexed source files"),
+        k: z.number().int().min(1).max(20).optional().describe("Max hits to return (default 8, max 20)"),
+        scope_prefix: z.string().optional().describe("Optional repo subdirectory prefix to limit search scope")
+      },
+      outputSchema: {
+        results: z.array(z.unknown()).describe("Ranked file/symbol hits with paths, line ranges, and similarity"),
+        query: z.string().describe("Normalized query string that was searched"),
+        mode: z.string().optional().describe("semantic (embeddings) or name (path/symbol match)")
       }
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
-      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/search`, {
-        method: "POST",
-        body: JSON.stringify({
-          query: args.query,
-          k: args.k ?? 8,
-          scope_prefix: args.scope_prefix ?? void 0
-        })
-      });
-      return jsonText(data);
+      const data = await apiCall(
+        `/v1/admin/projects/${pid}/codebase/search`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            query: args.query,
+            k: args.k ?? 8,
+            scope_prefix: args.scope_prefix ?? void 0
+          })
+        }
+      );
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -3048,10 +2970,17 @@ Be specific. No generic advice.`
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        paths: z.array(z.string()).optional().describe("Changed file paths"),
-        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths"),
-        compare: z.string().optional().describe("GitHub compare range base...head"),
-        fix_id: z.string().optional().describe("Fix attempt UUID for PR changed files")
+        paths: z.array(z.string()).optional().describe("Changed repo-relative file paths to analyze"),
+        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths instead of manual paths"),
+        compare: z.string().optional().describe("GitHub compare range base...head when source=compare"),
+        fix_id: z.string().optional().describe("Fix attempt UUID \u2014 uses that PR's changed files when source=fix")
+      },
+      outputSchema: {
+        changed_paths: z.array(z.string()).describe("Resolved set of changed paths analyzed"),
+        source: z.string().describe("How changed_paths were resolved (manual, last_push, compare, fix, \u2026)"),
+        affected_file_paths: z.array(z.string()).describe("Indexed files that import or depend on changed paths"),
+        affected_node_ids: z.array(z.string()).describe("Codebase graph node ids impacted by the change"),
+        meta: z.unknown().nullable().optional().describe("Extra resolution metadata when auto-sourced")
       }
     },
     async (args) => {
@@ -3066,7 +2995,7 @@ Be specific. No generic advice.`
         throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -3130,6 +3059,39 @@ Be specific. No generic advice.`
       return result;
     });
   }
+  {
+    const llAliasServer = server.server;
+    const innerHandler = llAliasServer?._requestHandlers?.get("tools/call");
+    if (typeof innerHandler === "function") {
+      llAliasServer._requestHandlers.set("tools/call", async (...args) => {
+        const req = args[0];
+        const originalName = req?.params?.name;
+        const canonicalName = originalName ? DEPRECATED_TOOL_ALIASES[originalName] : void 0;
+        if (canonicalName) {
+          const rewritten = {
+            ...args[0],
+            params: { ...req?.params ?? {}, name: canonicalName }
+          };
+          const result = await innerHandler(rewritten, ...args.slice(1));
+          if (result != null && typeof result === "object" && "content" in result && Array.isArray(result.content)) {
+            const r = result;
+            return {
+              ...r,
+              content: [
+                {
+                  type: "text",
+                  text: `\u26A0\uFE0F Deprecated: \`${originalName}\` was renamed to \`${canonicalName}\`. Update your agent config \u2014 this alias will be removed in the next release.`
+                },
+                ...r.content
+              ]
+            };
+          }
+          return result;
+        }
+        return innerHandler(...args);
+      });
+    }
+  }
   return server;
 }
 
@@ -3149,7 +3111,7 @@ var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
 var SCOPES_RAW = process.env.MUSHI_SCOPES ?? "";
 var parsedScopes = SCOPES_RAW ? SCOPES_RAW.split(",").map((s) => s.trim()).filter((s) => s === "mcp:read" || s === "mcp:write") : ALL_SCOPES;
 var SCOPES = SCOPES_RAW && parsedScopes.length === 0 ? ALL_SCOPES : parsedScopes;
-var FEATURES = parseFeaturesCsv(process.env.MUSHI_FEATURES);
+var FEATURES = process.env.MUSHI_FEATURES?.trim() ? parseFeaturesCsv(process.env.MUSHI_FEATURES) : DEFAULT_FEATURE_GROUPS;
 var MCP_SENTRY_DSN = process.env.MUSHI_MCP_SENTRY_DSN?.trim();
 if (MCP_SENTRY_DSN) {
   Sentry.init({