m1nd-operator

name: m1nd-operator description: Use when the user mentions m1nd or when repo investigation, search, review, docs/spec work, or risky change prep should go through m1nd first before grep, glob, or manual file reads. Covers m1nd-first routing, L1GHT and universal document ingestion, risky edit preparation, document-to-code binding, multi-agent coordination, trails/continuity, daemon alerts, and refreshing the live m1nd tool surface from the local m1nd-mcp binary.

m1nd Operator

This is the deep execution manual that complements the short m1nd-first doctrine.

Use this skill when m1nd should be the first layer of truth for the task.

m1nd is strongest when structure, connected context, blast radius, continuity, docs/code bindings, or multi-agent coordination are the bottleneck. It is not the replacement for rg, the compiler, runtime logs, or the test runner.

Default Stance

Default to m1nd before grep, glob, or manual file reads.

The first question is not "which shell command should I run?" It is "can m1nd answer or narrow this directly from graph structure, connected context, docs, or cross-domain bindings?"

Only skip the m1nd first pass when:

• the user already gave the exact file and exact lines
• the question is pure compiler/test/runtime truth
• the task is a trivial local file action with no search or structural uncertainty

Trained Agent Loop

For unfamiliar repo work, audits, bug hunts, reviews, and risky changes, the measured high-signal pattern is:

1. Establish trust: trust_selftest, or session_handshake with scope set to the intended repo/workspace.
2. Recover before interpreting absence: if trust is not full or retrieval is blocked/empty unexpectedly, follow recovery_playbook.
3. Classify workspace issues precisely: wrong_workspace_binding means rebind, intentional ingest, or federation; it is not graph staleness.
4. Orient cheaply: audit for unfamiliar repos, search for exact text, seek for purpose, activate for connected neighborhoods.
5. Read the runtime contract/envelope before trusting results.
6. Prove final truth with direct source reads, tests, compiler/runtime output, and focused probes.
7. Before edits/reviews, run impact, validate_plan, and usually surgical_context_v2.
8. Record the investigation path: m1nd calls, recovery decisions, files inspected, commands run, and fallback reason.

Internal bug-hunt rounds call this m1nd-trained: graph plus operating doctrine. A visible MCP surface without this loop is only m1nd-basic.

Scope Binding Taxonomy

Before treating a m1nd result as stale, broken, or authoritative, classify the relationship between the requested scope and the active binding:

• full_repo_binding: the active workspace/ingest root is the repo being investigated, or the requested scope is contained by that root. Proceed with normal m1nd-first, then prove final truth directly.
• wrong_workspace_binding: the active workspace is a different repo. Rebind the host with M1ND_WORKSPACE_ROOT=/target/repo, intentionally ingest the target repo, or use federation only for genuine cross-repo work.
• nested_workspace_binding: the active workspace/root is a subdirectory of the requested repo. Retrieval is valid only for that subtree. Rebind or ingest the repo root before repo-wide claims.
• file_level_binding: ingest roots are docs, PRDs, L1GHT files, or generated handoffs inside the repo. Use them as document truth only; they do not prove implementation coverage.

Operational rule: do not keep trying seek, search, or activate against a nested/file-level binding when the task is repo-wide. Upgrade the binding once, run an isolated --workspace-root /target/repo probe, or switch to direct source/test proof and record m1nd_usage_mode=partial_scope_orientation.

Mission Control v0

Use Mission Control when the task needs an agent operating loop rather than another retrieval call: broad reviews, bug hunts, refactors, release checks, or long investigations where agents may repeat searches, drift phases, or turn graph hints into premature conclusions.

The mission loop is deliberately small:

1. mission_start creates the repo-scoped mission, route, budget envelope, starter moves, and non-claims.
2. mission_event records observed actions when available; otherwise mission_next.last_event can carry the latest action.
3. mission_next appends the last event and returns one recommended move plus do_not guardrails.
4. mission_verify treats a conclusion as a candidate claim. Graph-only or inferred evidence is not enough; source reads, tests, compiler/runtime output, or focused probes are required.
5. mission_handoff serializes verified claims, open hypotheses, dead paths, graph anchors, and the next required move for another agent or future session.
6. mission_close emits the proof packet: verified claims, rejected claims, tools observed, event digest, budget consumed, gaps, and non-claims.

Evidence rule: a direct mission event only proves a claim when the claim's evidence_refs names the event id or direct source/test/runtime proof. Do not let one direct read bless unrelated graph-only claims.

Operational rule: when mission_next says to switch to direct proof, stop spending graph budget unless you record a dissent event. Mission Control is not a host repair tool, graph correctness proof, or autonomous multi-agent orchestrator.

Bug-hunt rule: do not close only because one finding is verified. When mission_next returns direct_sweep, perform one negative-space sweep over public contracts/docs, boundary values, error paths, async/concurrency behavior, and helper/exported APIs. Feed it back as coverage_sweep, boundary_sweep, or edge_case_sweep before closing.

Short-Audit Route

Use m1nd-short-audit when the task is a small or localized bug hunt, a narrow review, or a tiny repo where source/runtime proof is likely cheaper than deep graph navigation.

The route is:

1. Establish trust with trust_selftest or scoped session_handshake.
2. If needed, perform one bounded recovery/ingest pass.
3. Run one or two cheap orientation calls: audit, search, seek, or activate.
4. Stop graph exploration once suspect files and behaviors are visible.
5. Prove with direct source reads, git diff, tests, compiler/runtime output, and focused probes.
6. Record m1nd_usage_mode=short_audit_orientation when it helped, or recovery_overhead when state repair consumed meaningful time.

For local helper use, prefer the first-class agent CLI:

m1nd agent first-minute \
  --repo /path/to/repo \
  --query "understand this system" \
  --json

m1nd agent next \
  --repo /path/to/repo \
  --query "focused subsystem or bug surface" \
  --json

m1nd agent orient \
  --repo /path/to/repo \
  --query "focused subsystem or bug surface" \
  --mode short \
  --json

Use agent first-minute for first contact, broad architecture/audit requests, or when an agent has not yet loaded the m1nd operating doctrine. It scopes the repo, establishes trust, ingests when needed, runs one bounded orientation pass, returns anchors, and emits do_not guardrails plus a direct-proof handoff.

agent next emits an m1nd-agent-action-envelope-v0 with the first safe move, so use it when you are choosing between scope, trust, orient, context, recover, or direct proof. agent orient returns schema=m1nd-agent-cli-v0, records whether the lane was short_audit_orientation or recovery_overhead, and always tells the agent to switch to direct proof. Use probe_m1nd.py short-audit only as a compatibility fallback when the npm CLI is unavailable, and raw probe_m1nd.py run only when you need a custom sequence of multiple tools.

agent context is anchor-first. Use it after first-minute, next, orient, or a direct source read identifies a concrete file. For broad narrative queries, let it refuse and route back to orientation rather than accepting a plausible but wrong capsule.

For broad audits, hard bug hunts, multi-repo systems, docs/L1GHT work, long-running investigations, security/risk review, or explicit full-system requests, escalate to references/full-spec-agent-os.md. It is the route table for the whole m1nd/L1GHT tool surface; treat it as a router, not a checklist.

Session Companion Routing

Some hosts expose an adjacent session-memory companion, for example DEXT3R. Use that layer when the bottleneck is conversation continuity: north star, prior decisions, open loops, handoff context, workstyle/method friction, or a scoped m1nd flash summary stored with the session.

Do not use that companion as code truth or as a replacement for m1nd's repo binding. The safe routing split is:

• Companion memory: why the work exists, what was already decided, and what open loops remain.
• m1nd agent next: the first safe repo move when choosing between scope, trust, orient, context, recover, or direct proof.
• m1nd MCP tools: graph, docs/L1GHT, impact, validation, mission control, and connected structural context.
• Direct proof: source files, tests, compiler/runtime output, logs, browser smoke, and focused probes.

If the host exposes only the companion wrapper and no direct m1nd MCP tools, classify the session as missing_m1nd_host_tool_surface, not as graph failure. Try the host-neutral CLI before abandoning m1nd for raw local search:

m1nd agent next --repo /path/to/repo --query "current task" --json

Before trusting companion output, confirm the companion session is bound to the same repo/project root as the task. If it reports missing scope, wrong project, global-only candidates, unavailable flash, or stale memory, classify it as companion_orientation_only and resume with the host-neutral CLI:

m1nd agent next --repo /path/to/repo --query "current task" --json

Global companion search is candidate discovery only. It can point at useful prior sessions, but it must not override the current repo's m1nd trust loop, source reads, tests, runtime probes, or CI evidence.

Core Rules

• Prefer the live MCP surface over stale prose. If tool names, counts, or parameters matter, run the bundled helper from this skill directory: python3 scripts/probe_m1nd.py tools.
• Keep agent_id stable within one investigation. Change it only when intentionally starting another role or another concurrent investigation.
• Ingest first. Re-ingest after code changes, or use incremental ingest for code repos when appropriate.
• If a m1nd tool call fails with Transport closed, treat it as a host MCP transport death, not as a graph, retrieval, or proof-state failure. Recovery tools cannot run through a closed transport. Verify the local binary with the repo smoke harness, kill stale m1nd-mcp --stdio processes if you own that host, then restart/rebind the MCP client or open a fresh thread. After the host relaunches the transport, run trust_selftest or session_handshake before relying on retrieval.
• If the host is launching an old native runtime, use the external self-update helper first: m1nd update check --channel beta, m1nd update plan --channel beta, then m1nd update apply --channel beta --yes. In live multi-agent sessions, add --no-kill and rebind only the selected host. This helper does not ingest, choose a workspace, repair graph contents, or refresh an already-open client's cached MCP tool list. m1nd restart --source /path/to/m1nd --yes remains the lower-level source-checkout repair path for development builds.
• If the uncertainty is host-specific, run m1nd hosts status --host all --project /path/to/project --json from the CLI before mutating anything. It is read-only and reports agent-pack presence, likely MCP config wiring, runtime/PATH alignment, workspace hints, and host_rebind_proven=false. If host config selects an absolute current managed runtime, a stale m1nd-mcp on PATH is a shadow warning only. If the host launches PATH or config is unknown, stale PATH is actionable. In both cases, confirm with hosts status/hosts plan, then rebind or open a fresh host session; do not claim an already-open client's cached tool list refreshed itself. If the host reports attention, run m1nd hosts plan --host all --project /path/to/project --json for the exact install, config, workspace env, rebind, and verification recipe. Use m1nd hosts apply --host all --project /path/to/project --yes --json only when you want the local mutation step after status/plan. Without --yes it is still a dry-run preview. With --yes, it can install or refresh agent-pack files and write canonical MCP config snippets for known hosts, but it does not prove rebind, refresh cached host tool lists, repair graph state, or remove the manual config step for generic hosts.
• If the live MCP surface exposes trust_selftest, call it first and route by verdict before relying on retrieval. full_trust means proceed with m1nd-first; needs_ingest means ingest the intended repo; orientation_only or degraded_host_tool_surface means use m1nd only for orientation and verify final truth with local files until the binding is refreshed; wrong_workspace_binding means the active graph is healthy but bound to the wrong repo for the requested scope; stale_binding_suspected means compare binding fingerprints and follow the recovery playbook before trusting retrieval.
• If trust_selftest is not exposed but session_handshake is, call the handshake and route by trust_mode as the cheaper sub-check. When the task names a target repo or absolute path, pass it as scope so Context Guard can detect cross-repo binding mistakes before retrieval.
• If the selftest verdict or handshake trust mode is not full_trust, or retrieval returns blocked/zero candidates unexpectedly, call recovery_playbook before inventing the next step. Use its ordered steps and binding_fingerprint to compare host, stdio, HTTP, runtime root, graph paths, generation counters, and ingest roots.
• If a retrieval/orientation response includes agent_runtime_contract, treat it as the authoritative agent-facing envelope for that call. Read trust_mode, session_identity, workspace_binding, graph_identity, and recovery.arguments before interpreting results: [] or modules: []. wrong_workspace_binding means rebind or intentionally ingest/federate the requested workspace; needs_ingest means cold graph; and retrieval_needs_recovery means pass the embedded payload to recovery_playbook before falling back to shell search.
• If a response includes context_guard.wrong_workspace_binding=true, stop the normal stale-graph path. Rebind the MCP host with M1ND_WORKSPACE_ROOT set to requested_workspace_hint, intentionally ingest that workspace on the same binding, or use federate_auto/federate only when the investigation truly spans repos. If the live host cannot be rebound in the current turn, run an isolated local probe with --workspace-root requested_workspace_hint and use that as bounded m1nd orientation before direct source/test proof. Do not treat this as proof that m1nd retrieval is broken.
• If wrong_workspace_binding is reported but the active root or ingest roots are nested inside the requested repo, classify it as nested_workspace_binding or file_level_binding. The graph may be useful for that sub-scope, but it is partial truth; rebind/ingest the repo root before repo-wide claims.
• If trust_selftest or session_handshake reports needs_ingest, or the mini graph_state.node_count is 0 while ingest is available, treat the session as a recoverable cold graph. Do not jump straight to shell fallback. Call ingest on the same MCP binding with the absolute intended repo/workspace path, never a managed runtime/session path such as ~/.codex/m1nd-runtimes/..., ~/.claude/m1nd-runtimes/..., an Antigravity agent runtime, or a generic mcp-runtimes/agent-runtimes folder. Host integrations should prefer M1ND_WORKSPACE_ROOT; m1nd also recognizes common workspace hints from Claude Code, Antigravity, Gemini, Cursor, Windsurf, VS Code, and shell/package-manager env vars. Then rerun session_handshake and one cheap retrieval. Fall back only if ingest is unavailable, ingest fails, or post-ingest retrieval is still blocked and recovery_playbook/doctor confirms stale binding or degraded host surface.
• If the host exposes health but not trust_selftest, session_handshake, or recovery_playbook, read health.tool_surface_contract and health.host_binding_alignment. Treat missing required host-visible tools as degraded_host_tool_surface, then verify with repo-local smokes or direct files until the host refreshes its binding.
• After ingest, sanity-check that retrieval is seeing the same active graph. If seek, search, or activate returns blocked, zero candidates, or an unexpectedly empty graph immediately after a successful ingest, suspect host-binding/session split-brain before blaming the repo or the m1nd core. If the response includes recovery.arguments, pass those arguments directly to recovery_playbook. Otherwise, call recovery_playbook with observed_tool, observed_proof_state, and observed_candidates from the suspicious response before falling back. Let the playbook decide when to call doctor.
• If the host tool surface exposes m1nd but is missing recovery tools such as ingest, classify the session as degraded_host_tool_surface. If doctor is available, call it with observed_tool="tools/list", observed_tool_count, available_tools, and missing_tools. Until the MCP binding is refreshed, use m1nd only as orientation and verify final truth with direct repo files.
• Make m1nd the first investigative step before shell search:
  • exact text need -> try search before rg
  • path pattern need -> try glob before filesystem globbing
  • implementation-by-purpose need -> try seek
  • subsystem/topic/connected neighborhood need -> try activate
• Treat proof_state, next_suggested_tool, next_suggested_target, and next_step_hint as workflow control signals, not decorative fields.
• Use the cheapest surface that preserves structural truth:
  • exact text -> search
  • path pattern -> glob
  • known file -> view
  • known purpose, unknown location -> seek
  • topic/subsystem/neighborhood -> activate
• For docs/specs/knowledge, decide the lane early:
  • authored as graph-native semantic markdown -> ingest with adapter: "light"
  • ordinary markdown/wiki/HTML/PDF/office docs -> ingest with adapter: "universal" or adapter: "auto"
• Before risky edits, route through impact, validate_plan, and usually surgical_context_v2.
• In Codex, prefer m1nd for analysis, planning, and context. If the task requires local file edits under Codex's editing rules, use apply_patch for the final file mutation unless there is a specific reason to use m1nd's write surfaces.

Fast Routing

• Unfamiliar repo or need a one-call orientation: use audit, then batch_view, coverage_session, or cross_verify as needed.
• Need a subsystem map: use activate.
• Need code by intent: use seek.
• Need why A connects to B: use why.
• Smells like missing validation, abstraction, cleanup, or lock: use missing.
• Have a stacktrace or runtime error text: use trace.
• Need blast radius before editing: use impact.
• Need co-change follow-through after editing: use predict.
• Need plan completeness and missing tests before implementation or review: use validate_plan.
• Need graph-native specs, design notes, or KB docs authored in L1GHT: ingest with adapter: "light" and usually mode: "merge".
• Need regular spec/wiki/PDF/doc alignment with code: ingest with adapter: "universal" or auto, then use document_resolve, document_bindings, and document_drift.
• Need hidden coupling, deep architecture quality, taint/security paths, duplication/refactor seams, or runtime heat: use the RETROBUILDER family. ghost_edges finds historical co-change, taint_trace follows trust boundary/sensitive flow, twins finds structural duplicates, refactor_plan proposes extraction communities, and runtime_overlay overlays span/log heat onto graph nodes. Treat these as hypotheses and anchors until direct source/test/runtime proof confirms them.
• Need stateful navigation instead of stateless retrieval: use perspective_*.
• Need session continuity or handoff: use trail_save, trail_list, trail_resume, trail_merge, and sometimes boot_memory.
• Need background structural monitoring: use daemon_start, daemon_status, daemon_tick, alerts_list, and alerts_ack.
• Need to persist a durable finding across sessions: use memorize with evidence paths pointing at the relevant code; ingest that code first so evidence anchors. Use mission_close(write_light_memory:true) for one-step mission + memory commit.
• Need to check whether memorized claims still cite current code: use cross_verify(check:["evidence_freshness"]); returns stale_evidence[] + count.

Compounding Memory

When you conclude something durable — a verified finding, a design decision, why code is shaped a certain way — persist it with memorize rather than leaving it only in the conversation. The workflow:

1. Ingest the relevant code first (ingest with the target path), so evidence paths resolve to real code nodes.
2. Call memorize with structured claims: label, text, confidence (low/medium/high/certain or 0.0–1.0), ambiguity (optional), and evidence (repo-relative paths).
3. m1nd writes a .light.md under <runtime_root>/agent-memory/, ingests it, and creates grounded_in edges linking claim nodes to the actual code nodes.
4. On the next session start, m1nd auto-loads all agent-memory files (reported in session_handshake.agent_memory). Past findings are in the graph immediately.
5. After code changes, check freshness: cross_verify(check:["evidence_freshness"]) names which memorized claims cite code that has since changed. The ingest result itself also includes memory_freshness after a merge re-ingest.
6. For mission-driven work, mission_close(write_light_memory:true) persists verified claims as L1GHT memory in one step.

Caveat: ingest mode:replace wipes light memory nodes. Prefer mode:merge when re-ingesting code to preserve agent memory.

Read These References

• references/routing-playbooks.md
  • Use for end-to-end workflows by task type: onboarding, bug triage, risky change prep, spec-to-code work, multi-agent sessions, and long-lived monitoring.
• references/tool-families.md
  • Use for the complete capability map grouped by family, including the less obvious tools (antibody_*, runtime_overlay, ghost_edges, flow_simulate, layers, refactor_plan, etc.).
• references/runtime-and-refresh.md
  • Use for local installation facts, current live-surface notes, the docs-vs-runtime count discrepancy, refresh procedure, and the helper script usage.
• references/l1ght-and-docs.md
  • Use for the L1GHT mental model, marker vocabulary, header fields, light vs universal, and mixed code+docs graph workflows.

Local Helper

Use m1nd agent ... whenever the live runtime matters more than remembered docs and you need a host-neutral probe outside a stale MCP client.

m1nd agent scope --repo /path/to/repo --json
m1nd agent trust --repo /path/to/repo --ensure-ingest --json
m1nd agent orient --repo /path/to/repo --query "focused subsystem or bug surface" --mode short --json
m1nd agent recover --repo /path/to/repo --from wrong_workspace_binding --json
m1nd agent doctor --repo /path/to/repo --json

The bundled probe script remains available from this skill directory for low-level MCP calls and compatibility:

python3 scripts/probe_m1nd.py tools
python3 scripts/probe_m1nd.py call health '{"agent_id":"codex-m1nd"}'
python3 scripts/probe_m1nd.py call trust_selftest '{"agent_id":"codex-m1nd"}'
python3 scripts/probe_m1nd.py call session_handshake '{"agent_id":"codex-m1nd","scope":"/path/to/intended/repo"}'
python3 scripts/probe_m1nd.py call recovery_playbook '{"agent_id":"codex-m1nd","observed_tool":"seek","observed_proof_state":"blocked","observed_candidates":0}'
python3 scripts/probe_m1nd.py call help '{"agent_id":"codex-m1nd","tool_name":"validate_plan"}'
python3 scripts/probe_m1nd.py run '[{"name":"ingest","arguments":{"agent_id":"codex-m1nd","path":"/path/to/repo"}},{"name":"seek","arguments":{"agent_id":"codex-m1nd","query":"where retry backoff is decided","top_k":5}}]'

Use m1nd agent orient --repo /path/to/repo --mode short --json when the host MCP session reports wrong_workspace_binding and you cannot restart/rebind that host immediately. This is the preferred fallback before raw shell search: it keeps m1nd useful while avoiding contamination of the open host's active graph. Record the mode as isolated_probe_after_wrong_workspace_binding.

probe_m1nd.py uses an isolated temporary --runtime-dir by default so parallel agent probes do not fight over the same runtime owner lock. If a helper or older skill reports runtime_root ... is already owned by instance, do not classify that as graph staleness or retrieval failure. Rerun with the agent CLI, pass an explicit unique --runtime-dir to the probe helper, or combine custom dependent calls with probe_m1nd.py run so they share one process intentionally. Use --shared-runtime only when debugging shared runtime state. The helper prefers ~/.m1nd/bin/m1nd-mcp over a stale m1nd-mcp earlier on PATH; override with M1ND_MCP_BINARY, M1ND_MCP_BIN, or --binary only when you intentionally want another runtime. For benchmark lanes or tight worktrees, add --no-worktree-artifacts; it launches the runtime from the isolated runtime directory and sets the caller directory as M1ND_WORKSPACE_ROOT, so probe metadata does not appear in the target repo unless the runtime is explicitly configured to write there. If you invoke the helper from a director repo while inspecting another checkout, pass --workspace-root /path/to/that/checkout explicitly.

For the m1nd repo itself, prefer the repo-local agent smoke harness when you need to distinguish a real runtime problem from a host-provided MCP binding problem:

python3 scripts/mcp_agent_smoke.py --repo . --handshake-only --json
python3 scripts/mcp_agent_smoke.py --repo . --handshake-only --handshake-probe --json
python3 scripts/mcp_agent_smoke.py --repo . --json
python3 scripts/mcp_agent_smoke.py --repo . --transport http --json

Use trust_selftest as the cheap default when exposed. The current binary also exposes the sub-check as session_handshake; the harness calls both when available and falls back for older binaries. The default path must stay diagnostic-only: no ingest, no repair, and no retrieval probe by default. recovery_playbook is the in-band next-step surface when the selftest, handshake, or retrieval looks suspicious. Add --handshake-probe only when the task depends on retrieval trust.

That harness proves the minimum trust loop over real Content-Length framed stdio and the HTTP tool API:

initialize -> tools/list -> trust_selftest -> session_handshake -> recovery_playbook when needed -> ingest -> seek -> help -> doctor

What the helper is for:

• confirming the local binary still responds
• listing the live tool surface
• detecting degraded_host_tool_surface when required tools such as ingest, seek, help, recovery_playbook, or doctor are missing
• checking a tool's real response shape without relying on stale wiki prose
• catching graph/session continuity failures before falling back to broad shell search

Working Posture

• Use m1nd when the question is about relationships, not just strings.
• Use m1nd first even when the answer might be textual, because search, seek, and activate can often narrow the surface before any shell reads.
• Use m1nd before big changes when hidden neighbors or missing tests could bite later.
• Use m1nd for continuity when the same investigation spans agents or sessions.
• Fall back to rg, direct file reads, compiler output, and runtime logs when execution truth is the real question.