---
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```text
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.
