Tool Matrix SSOT

Machine-oriented routing matrix for the current m1nd tool surface.

Source Of Truth

The m1nd-mcp/src/server.rs tool schema registry is the callable surface. tools/list shows the advertised menu, which since 2026-08-01 is a curated subset of it — read The core menu below before treating an unlisted verb as a missing capability.
This matrix is the routing SSOT for the canonical tool surface used by agents and LLMs, and it documents the REGISTRY: a verb with a row here is callable whether or not tools/list lists it.
Any page that advertises a fixed tool count can drift. Treat health.tool_surface_contract (full_registry_tool_count / advertised_tool_count / hidden_tool_count) as counting truth.

By default m1nd advertises a core menu of about 15 verbs, not the whole registry:

	verbs
the owner-ratified core (12)	`north` · `memorize` · `ingest` · `seek` · `search` · `health` · `trust_selftest` · `view` · `impact` · `session_handshake` · `boot_memory` · `surgical_context`
the host-binding floor (3 more)	`help` · `doctor` · `recovery_playbook`

The floor is not an exception to the core — it is why the core can be small. health.tool_surface_contract publishes required_host_visible_tools and tells every host to read a binding missing any of them as degraded_host_tool_surface, so the menu is DERIVED (core ∪ floor) rather than hand-typed, and cannot drift from the contract it has to satisfy.

Nothing was removed. Every other verb in this matrix keeps its handler, its policy route, its authority floor and its dispatch, and answers exactly as before the moment a caller names it. The cut is at advertisement only.

How to reach the rest. help catalogs the FULL registry at every tier: help(intent) or help(stage) routes you to the right verb for what you are doing, and help(tool_name) returns any verb’s schema, listed or not. Operators who want the whole list in the menu set M1ND_TOOL_TIER=full on the server; an unrecognised value falls back to the core, never to the full surface.

Why. Measured over six weeks of real agent traffic (458 calls / 157 sessions): 141 verbs advertised, 13 ever called. 69 verbs sit in prefix families and across all of those families exactly two calls were ever made. Eleven standalone verbs carried 370 of the 458. An independent external evaluator working a foreign 107k-LOC codebase ranked surgical_context in its top three — a verb with one call in six weeks. The verbs were not bad; a 141-item menu is not a menu.

Row Contract

field	meaning
`command`	canonical bare MCP call name returned by `tools/list`
`category`	routing bucket
`core_function`	shortest truthful description of what the tool does
`choose_when`	positive routing trigger
`avoid_when`	disqualifier / better alternative
`required`	minimum required args
`returns`	stable output surface an LLM can plan around
`next`	adjacent tools / likely next hop

Foundation

command	core_function	choose_when	avoid_when	required	returns	next
`north`	In-session front door: composed pre-orient — binding trust, task context, prior cross-session memory, sufficiency, one `next_move`, `honest_gaps`, and the source of the top focus nodes (`code`: up to 3 files, ~2,000 chars, truncation declared).	Call FIRST, before reading or editing — it orients AND hands back the code, composing trust_selftest + orient + boot_memory + focus + surgical_context/batch_view, so the follow-up read is already in the packet.	Avoid only when you need exactly one composed piece; reach for it directly then. Pass `code: false` for the orientation-only packet.	`agent_id`	`trust_mode; task_context; prior_memory; sufficiency; next_move; honest_gaps; code?; needs_ingest?`	`read code.slices -> impact` (`ingest` first if `needs_ingest`)
`ingest`	Parse a codebase, markdown docs, or JSON domain graph into the semantic graph.	Start or refresh graph truth for a repo, file, docs corpus, or descriptor before higher-order queries.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; path`	`graph_counts; files_scanned; files_parsed; nodes_created; edges_created; elapsed_ms`	`activate -> impact -> why`
`activate`	Spreading activation query — fires signal into the graph and returns a 4D-scored activation pattern.	Use when the query is associative or subsystem-shaped and you want connected structure, not exact text.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; query`	`seeds; activated; ghost_edges; structural_holes; plasticity; elapsed_ms`	`activate -> impact -> why`
`impact`	Blast radius of a code change — BFS-propagated signal strength from a source node.	Use before edits to estimate blast radius.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; node_id`	`blast_radius; total_energy; causal_chains`	`activate -> impact -> why`
`why`	Shortest path between two nodes — understand how A depends on B.	Use to explain how two nodes are connected.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; source; target`	`path; hops; edge_types; path_weight`	`activate -> impact -> why`
`learn`	Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly.	Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; query; feedback; node_ids`	`edges_modified; trust_records_updated; tremor_observations_recorded`	`activate -> impact -> why`
`drift`	What changed in the graph since your last session — structural delta for context recovery.	What changed in the graph since your last session — structural delta for context recovery.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id`	`baseline; changed_nodes; weight_drift; summary`	`activate -> impact -> why`
`health`	Server diagnostics — verify the MCP server is alive and the graph is loaded.	Server diagnostics — verify the MCP server is alive and the graph is loaded.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id`	`node_count; edge_count; sessions; graph_state`	`activate -> impact -> why`
`trust_selftest`	One-call agent trust verdict for binding, graph, and recovery readiness.	Use as the degraded/recovery entry when trust looks off; for normal orientation use `north`.	Avoid treating it as repair or as the default front door; it is diagnostic-only and does not ingest or mutate.	`agent_id`	`verdict; checks; binding_fingerprint; session_handshake; recovery_playbook?`	`north -> ingest -> recovery_playbook`
`session_handshake`	Cheap sub-check for host tool surface and graph trust mode.	Use when `trust_selftest` is unavailable or when you only need the handshake layer.	Avoid using it as a retrieval probe; it does not test semantic results by default.	`agent_id`	`trust_mode; can_ingest; can_retrieve; tool_surface; graph_state`	`trust_selftest -> recovery_playbook -> ingest`
`recovery_playbook`	Ordered recovery steps for empty graphs, degraded hosts, and stale-looking retrieval.	Use when `trust_selftest` or retrieval reports blocked, degraded, or stale-looking state.	Avoid assuming it repaired anything; it only returns next actions.	`agent_id`	`trust_mode; binding_fingerprint; steps; non_claims`	`doctor -> ingest -> session_handshake`
`seek`	Find code by natural language intent — more targeted than `activate` for specific lookups.	Use when you know the purpose of code but not its location.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; query`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`scan`	Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string.	Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; pattern`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`timeline`	Temporal evolution of a node — change history, co-change partners, velocity, stability.	Temporal evolution of a node — change history, co-change partners, velocity, stability.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; node`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`diverge`	Structural drift analysis — compare graph state against a baseline reference.	Structural drift analysis — compare graph state against a baseline reference.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; baseline`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`warmup`	Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance.	Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; task_description`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`federate`	Unify multiple repositories into one graph — cross-repo blast radius and dependency analysis.	Use when you already know the repo list to unify.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id; repos`	`tool-specific JSON payload; inspect API reference / tools/list`	`activate -> impact -> why`
`federate_auto`	Discover candidate sibling repositories from explicit external path references, local manifest/workspace hints, import/package-name evidence, shared API-route signals, or basic contract artifacts and optionally execute federation in one step.	Use when you suspect neighboring repos matter but only have path/import/contract evidence.	Avoid when you already have the exact file/line or only need raw compiler/runtime truth.	`agent_id`	`discovered_repos; suggested_repos; executed; federate_result`	`activate -> impact -> why`

Document Intelligence

command	core_function	choose_when	avoid_when	required	returns	next
`document_resolve`	resolve canonical local artifacts for a universally ingested document	Use when a doc already exists in the graph and you need the local canonical artifact paths.	Avoid when you only need a fresh ingest or raw source text.	`agent_id`	`canonical_markdown_path; canonical_json_path; claims_path; producer; binding_count; drift_summary`	`document_bindings -> document_drift -> view`
`document_provider_health`	report optional provider availability, mode, detail, and install hints	Use before relying on richer HTML/PDF/office extraction or when a provider lane seems to be falling back unexpectedly.	Avoid when provider setup is irrelevant to the current task.	`agent_id`	`python; providers[]`	`ingest -> document_resolve -> auto_ingest_start`
`document_bindings`	show deterministic document-to-code bindings for a universal document	Use when the question is “which code implements this doc?” or “what should I inspect first?”	Avoid when you only need the artifact paths or provider status.	`agent_id`	`bindings[]; source_path`	`document_drift -> impact -> surgical_context_v2`
`document_drift`	detect stale, missing, or ambiguous document/code links	Use after refactors, repo moves, or suspected stale specs.	Avoid before the document has been ingested or bound.	`agent_id`	`findings[]; summary`	`document_bindings -> impact -> timeline`
`auto_ingest_start`	start local-first document watchers for supported roots and formats	Use when a docs/specs/wiki root should stay synchronized with the graph while you work.	Avoid for one-shot ingest or read-only inspection.	`agent_id; roots`	`running; provider_status; bootstrap`	`auto_ingest_status -> auto_ingest_tick -> document_resolve`
`auto_ingest_status`	inspect the document auto-ingest runtime, semantic counts, provider status, and route/fallback counts	Use to monitor watcher state, queue depth, or document runtime telemetry.	Avoid if you only need a direct document refresh or binding result.	`agent_id`	`running; queue_depth; semantic_; provider_; recent_events`	`auto_ingest_tick -> document_drift -> document_provider_health`
`auto_ingest_tick`	drain queued document changes immediately and apply them to the graph	Use when a caller needs deterministic immediate reconciliation instead of waiting for opportunistic ticks.	Avoid when no watched roots are active.	`agent_id`	`ingested_paths; removed_paths; skipped_paths; errored_paths`	`document_resolve -> document_drift -> lock_diff`
`auto_ingest_stop`	stop document watchers and persist manifest state	Use when shutting down or changing watched roots.	Avoid during active watch-driven reconciliation you still need.	`agent_id`	`stopped; manifest_entries`	`auto_ingest_start -> auto_ingest_status`

command	core_function	choose_when	avoid_when	required	returns	next
`perspective_start`	Open a perspective anchored to a node. Perspectives are stateful navigation sessions.	Open a perspective anchored to a node. Perspectives are stateful navigation sessions.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; query`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_routes`	List available navigation routes from the current focus node.	List available navigation routes from the current focus node.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_follow`	Move the perspective focus to a route target.	Move the perspective focus to a route target.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_back`	Navigate backward to the previous focus node.	Navigate backward to the previous focus node.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_peek`	Read source code at the currently focused node (returns file content at the node’s location).	Read source code at the currently focused node (returns file content at the node’s location).	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_inspect`	Deep metadata + 5-factor score breakdown for a route’s target node.	Deep metadata + 5-factor score breakdown for a route’s target node.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_suggest`	AI navigation recommendation — the graph suggests which route to follow next.	AI navigation recommendation — the graph suggests which route to follow next.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_affinity`	Check route relevance to the current investigation.	Check route relevance to the current investigation.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_branch`	Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings.	Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_compare`	Diff two perspectives — shared nodes, unique nodes, divergent findings.	Diff two perspectives — shared nodes, unique nodes, divergent findings.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id; perspective_id_a; perspective_id_b`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_list`	All active perspectives for this agent, with memory usage.	All active perspectives for this agent, with memory usage.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`
`perspective_close`	Release perspective state and free memory.	Release perspective state and free memory.	Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`perspective_routes -> perspective_follow -> perspective_inspect`

Lock System

command	core_function	choose_when	avoid_when	required	returns	next
`lock_create`	Snapshot a subgraph region.	Snapshot a subgraph region.	Avoid for solo read-only work; use only when coordination or baseline diffs matter.	`agent_id; scope; root_nodes`	`tool-specific JSON payload; inspect API reference / tools/list`	`lock_watch -> lock_diff -> lock_rebase`
`lock_watch`	Register a change strategy on a lock.	Register a change strategy on a lock.	Avoid for solo read-only work; use only when coordination or baseline diffs matter.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`lock_watch -> lock_diff -> lock_rebase`
`lock_diff`	Compare current graph state against the locked baseline. Returns changes since the lock was created.	Compare current graph state against the locked baseline. Returns changes since the lock was created.	Avoid for solo read-only work; use only when coordination or baseline diffs matter.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`lock_watch -> lock_diff -> lock_rebase`
`lock_rebase`	Advance the lock baseline to the current graph state (after reviewing and accepting changes).	Advance the lock baseline to the current graph state (after reviewing and accepting changes).	Avoid for solo read-only work; use only when coordination or baseline diffs matter.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`lock_watch -> lock_diff -> lock_rebase`
`lock_release`	Free lock state and release memory.	Free lock state and release memory.	Avoid for solo read-only work; use only when coordination or baseline diffs matter.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`lock_watch -> lock_diff -> lock_rebase`

Superpowers

command	core_function	choose_when	avoid_when	required	returns	next
`hypothesize`	Test a claim against graph structure using Bayesian path scoring. 89% accuracy validated on 10 live claims against a production codebase.	Test a claim against graph structure using Bayesian path scoring. 89% accuracy validated on 10 live claims against a production codebase.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; claim`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`counterfactual`	Simulate module removal — compute full cascade of what breaks.	Simulate module removal — compute full cascade of what breaks.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; node_ids`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`missing`	Find structural holes — what should exist in a region of the graph but doesn’t.	Find structural holes — what should exist in a region of the graph but doesn’t.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; query`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`resonate`	Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously.	Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`fingerprint`	Find structural twins — nodes with identical or near-identical topology.	Find structural twins — nodes with identical or near-identical topology.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`trace`	Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality.	Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; error_text`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`validate_plan`	Pre-flight risk assessment for a set of planned changes — blast radius, gap count, risk score.	Use before editing or merging to pre-flight risk and test impact.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; actions`	`risk_score; gaps; suggested_additions; heuristic_summary`	`hypothesize -> validate_plan -> trace`
`predict`	Co-change prediction — given a file you just changed, which other files likely need changes too.	Co-change prediction — given a file you just changed, which other files likely need changes too.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; changed_node`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`trail_save`	Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts.	Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; label`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`trail_resume`	Restore exact investigation context — nodes, weights, hypotheses — from a saved trail.	Restore exact investigation context — nodes, weights, hypotheses — from a saved trail.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; trail_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`trail_merge`	Combine two or more agents’ independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses.	Combine two or more agents’ independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; trail_ids`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`trail_list`	Browse all saved investigations with optional filters.	Browse all saved investigations with optional filters.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`
`differential`	Focused structural diff between two graph snapshots — surface what changed structurally between two points in time.	Focused structural diff between two graph snapshots — surface what changed structurally between two points in time.	Avoid for plain text lookup or trivial file reads; these are structural reasoning tools.	`agent_id; snapshot_a; snapshot_b`	`tool-specific JSON payload; inspect API reference / tools/list`	`hypothesize -> validate_plan -> trace`

Superpowers Extended

command	core_function	choose_when	avoid_when	required	returns	next
`antibody_scan`	Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings.	Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`antibody_list`	List all stored antibodies with match history.	List all stored antibodies with match history.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`antibody_create`	Create, disable, enable, or delete an antibody pattern.	Create, disable, enable, or delete an antibody pattern.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`flow_simulate`	Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions).	Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions).	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`epidemic`	SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs.	SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id; infected_nodes`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`tremor`	Change frequency acceleration detection — identifies modules with accelerating change frequency. Acceleration precedes bugs, not just high churn.	Change frequency acceleration detection — identifies modules with accelerating change frequency. Acceleration precedes bugs, not just high churn.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`trust`	Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries.	Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`layers`	Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations.	Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`
`layer_inspect`	Inspect a specific architectural layer: nodes, inter-layer connections, health metrics.	Inspect a specific architectural layer: nodes, inter-layer connections, health metrics.	Avoid before you have a scoped suspect area; these are deeper risk/simulation tools.	`agent_id; level`	`tool-specific JSON payload; inspect API reference / tools/list`	`trust -> tremor -> heuristics_surface`

RETROBUILDER

command	core_function	choose_when	avoid_when	required	returns	next
`ghost_edges`	temporal co-change ghost edges from git history	temporal co-change ghost edges from git history	Avoid without git/runtime/security context; use only when that extra plane matters.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`runtime_overlay -> trace -> impact`
`taint_trace`	taint propagation over graph structure	taint propagation over graph structure	Avoid without git/runtime/security context; use only when that extra plane matters.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`runtime_overlay -> trace -> impact`
`twins`	structural equivalence / near-equivalence discovery	structural equivalence / near-equivalence discovery	Avoid without git/runtime/security context; use only when that extra plane matters.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`runtime_overlay -> trace -> impact`
`refactor_plan`	graph-native refactoring proposals	graph-native refactoring proposals	Avoid without git/runtime/security context; use only when that extra plane matters.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`runtime_overlay -> trace -> impact`
`runtime_overlay`	runtime heat and error overlays from OTel spans	runtime heat and error overlays from OTel spans	Avoid without git/runtime/security context; use only when that extra plane matters.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`runtime_overlay -> trace -> impact`

Surgical

command	core_function	choose_when	avoid_when	required	returns	next
`heuristics_surface`	Explain why a node/file ranked as risky or important.	Explain why a node/file ranked as risky or important.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`surgical_context`	Return complete context for a file in one call: full source, symbol table, callers, callees, and test coverage neighbours. Use before `apply` for single-file edits.	Use before single-file edits.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id; file_path`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`apply`	`apply` now returns `proactive_insights` when a write lands on a risky or historically unstable surface.	Use to write one file and keep the graph coherent.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id; file_path; new_content`	`updated_node_ids; proactive_insights; elapsed_ms`	`heuristics_surface -> batch_view -> apply_batch`
`view`	Fast file reader with line numbers and optional auto-ingest.	Use when you already know the file and need bounded line-numbered reading.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`surgical_context_v2`	Superset of `surgical_context` — returns the target file’s full contents AND source excerpts of all connected files (callers, callees, tests) in one call. Eliminates the need to read multiple files separately. Use before `apply_batch` when editing a file and its callers/tests together.	Use before multi-file edits where connected source context matters.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id; file_path`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`apply_batch`	`apply_batch` now returns `proactive_insights`, and the final `batch_completed` progress event carries the same payload for streaming clients.	Use to write multiple files atomically and optionally verify.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id; edits`	`results; verification; proactive_insights; progress_events`	`heuristics_surface -> batch_view -> apply_batch`
`edit_preview`	Preview a write without touching disk.	Preview a write without touching disk.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`edit_commit`	Commit a previewed edit after confirmation and freshness check.	Commit a previewed edit after confirmation and freshness check.	Avoid before locating the target surface; use seek/search/impact first.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`heuristics_surface -> batch_view -> apply_batch`
`transplant`	Move a top-level Rust `fn` to another file of the same crate by reference: the server computes the widened extent, the dependency trichotomy from call edges, and the re-qualified referencers, then writes atomically and re-ingests.	Use when the change IS a move — you send 4 fields instead of whole file contents, and read the receipt instead of re-reading the files.	Avoid for anything but a top-level `fn` inside one crate, for a destination file that does not exist yet, or when macro-generated references must be followed.	`agent_id; symbol; source_file; dest_file`	`moved_symbol; files_changed; deps_travelled; deps_shared; refs_rewritten; refs_unresolved; state_left_behind; blocks_touched; rustfmt; elapsed_ms`	`surgical_context_v2 -> transplant -> impact`
`transplant_preview`	Stage the whole move without touching disk: per-file plan with base hashes and line deltas, plus the candidate receipt and a 5-minute handle.	Use when the move should be inspected (or approved) before it lands.	Avoid when a one-shot `transplant` is acceptable; the handle expires.	`agent_id; symbol; source_file; dest_file`	`preview_id; ttl_ms; files; candidate; elapsed_ms`	`transplant_preview -> transplant_commit`
`transplant_commit`	Land a staged plan after re-validating the on-disk hash of every planned file; any drift refuses the commit as stale.	Use to redeem a `transplant_preview` handle.	Avoid without `confirm: true`, or after the 5-minute TTL.	`agent_id; preview_id; confirm`	`preview_id; receipt; elapsed_ms`	`transplant_preview -> transplant_commit`

Search & Efficiency

command	core_function	choose_when	avoid_when	required	returns	next
`search`	Unified literal/regex/semantic search — graph-aware grep replacement. Searches both node labels in the graph and file contents on disk, returning results with line context.	Use for exact text, regex, or semantic grep across graph + file content.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id; query`	`results; total_matches; proof_state; next_suggested_tool`	`search/glob -> batch_view -> coverage_session`
`glob`	Graph-aware file globbing over indexed files.	Use when you need files by path pattern, not content.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`search/glob -> batch_view -> coverage_session`
`help`	Self-documenting tool reference with m1nd’s visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions.	Self-documenting tool reference with m1nd’s visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`search/glob -> batch_view -> coverage_session`
`panoramic`	Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts.	Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`modules; critical_alerts; summary`	`search/glob -> batch_view -> coverage_session`
`report`	Session summary — query log, timing statistics, graph size, and the highest-risk heuristic hotspots in the current graph — PLUS `verb_usage`, the durable per-verb call counters this brain has kept across restarts (`answered`, `refused_at_authority_floor`, `refused_at_dispatch`, first/last seen). Provides a markdown-formatted report ready for display or logging.	Session summary, and the one call that answers which verbs this brain is actually used for and how often.	Avoid for write/plan validation; these help orientation and summary, not mutation safety. `verb_usage` carries verb names and counts only — never an agent id, arguments, or anything derived from them.	`agent_id`	`recent_queries; heuristic_hotspots; verb_usage; markdown_summary`	`search/glob -> batch_view -> coverage_session`
`metrics`	Return structural metrics per file/function/module.	Use when you want ranked structural measures, not semantic retrieval.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`entries; summary`	`search/glob -> batch_view -> coverage_session`
`type_trace`	Trace where a type/struct/enum is used across the graph.	Use when following a type across files and callsites.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`usages; file_groups`	`search/glob -> batch_view -> coverage_session`
`diagram`	Generate Mermaid or DOT graph diagrams.	Use when you need a visual graph slice for humans or downstream agents.	Avoid for write/plan validation; these help orientation and summary, not mutation safety.	`agent_id`	`format; diagram; node_count`	`search/glob -> batch_view -> coverage_session`

Audit & Session

command	core_function	choose_when	avoid_when	required	returns	next
`batch_view`	multi-file read surface with stable delimiters and summaries	multi-file read surface with stable delimiters and summaries	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`scan_all`	run all structural patterns in one call	run all structural patterns in one call	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`cross_verify`	graph vs disk verification (`existence`, `loc`, `hash`)	graph vs disk verification (`existence`, `loc`, `hash`)	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`coverage_session`	what this agent has visited so far	what this agent has visited so far	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`external_references`	explicit paths outside ingest roots	explicit paths outside ingest roots	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`audit`	profile-aware one-call audit	profile-aware one-call audit	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`daemon_start`	activate the persisted daemon control plane and set watch roots / poll interval	activate the persisted daemon control plane and set watch roots / poll interval	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`daemon_stop`	stop the daemon control plane without discarding alert history	stop the daemon control plane without discarding alert history	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`tool-specific JSON payload; inspect API reference / tools/list`	`audit -> batch_view -> cross_verify`
`daemon_status`	inspect daemon runtime state, watch roots, and alert counts	Use to inspect daemon liveness, tracked files, and recent tick metrics.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`active; tracked_files; tick_count; last_tick_duration_ms; last_tick_changed_files; last_tick_deleted_files; last_tick_alerts_emitted`	`audit -> batch_view -> cross_verify`
`daemon_tick`	poll watched roots once, incrementally re-ingest changed files, and emit deletion drift alerts	Use when you want one explicit delta-processing pass over watched roots.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`changed_files_detected; deleted_files_detected; files_reingested; alerts_emitted`	`audit -> batch_view -> cross_verify`
`alerts_list`	list persisted daemon/proactive alerts	Use to review durable daemon/proactive alerts.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`alerts; total; active`	`audit -> batch_view -> cross_verify`
`alerts_ack`	acknowledge one or more persisted daemon/proactive alerts	Use after reviewing alerts so they do not keep resurfacing.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`acked; requested; acked_at_ms`	`audit -> batch_view -> cross_verify`
`persist`	Force graph and sidecar state persistence to disk.	Use when you want to force-save graph and sidecars now.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`status; snapshot_path; plasticity_path`	`audit -> batch_view -> cross_verify`
`boot_memory`	Persist small canonical hot-state values next to the graph.	Use for tiny canonical doctrine/state values that should stay hot.	Avoid for tiny one-file questions; these are orchestration and session-shaping tools.	`agent_id`	`action; key; value; entries`	`audit -> batch_view -> cross_verify`

Routing Rules

Pre-orient with north before reading or editing. It is the in-session front door; audit is the deeper structural pass once you are oriented, and the trust_selftest / session_handshake / recovery_playbook trio is the degraded/recovery lane.
Obey the calibrated verdicts instead of overriding them: act / reverify / abstain on retrieval and prediction (abstain = insufficient or uncalibrated — a STOP), closure: blocked on why (unresolved edge), the trust_envelope + sufficiency stop-signal on seek, and trust_band: insufficient_evidence (no evidence, not medium risk).
Prefer the cheapest tool that preserves structural truth.
Use search / glob / view for exact known targets; use seek / activate when the question is semantic or subsystem-shaped.
Use impact, predict, validate_plan, and the surgical tools before risky edits.
Use audit, cross_verify, coverage_session, batch_view, and daemon tools to manage long-running sessions.
Use perspective and lock tools only when stateful navigation or multi-agent coordination is worth the overhead.
Before ending, memorize durable findings with confidence and repo-relative evidence paths so knowledge lives in the same activation space as code.

m1nd Documentation