@maxkle1nz/m1nd 0.9.0-beta.0

package/skills/m1nd-operator/references/routing-playbooks.md

@@ -0,0 +1,172 @@
+# m1nd Routing Playbooks
+
+This file is the operational map: which `m1nd` tools to choose for each kind of job, and in what order.
+
+## Decision Rules
+
+- Start with `m1nd` unless the task is obviously outside its lane.
+- Use `search` when the user already knows the string or regex.
+- Use `glob` when the user knows the path shape but not the contents.
+- Use `view` when the file is already known and bounded reading is enough.
+- Use `seek` when the user knows what the code does but not where it lives.
+- Use `activate` when the user needs a subsystem or neighborhood map.
+- Use `perspective_*` only when navigation state is worth the overhead.
+- Use `impact`, `validate_plan`, and the surgical tools before risky edits.
+- Use `trace` when you already have failure text.
+- Use `document_*` when docs, wiki pages, PDFs, or specs must stay grounded in code.
+- Use daemon, alerts, trails, and locks when the session is long-lived or multi-agent.
+
+## Workflow 1: First Contact With An Unfamiliar Repo
+
+1. `health`
+2. `ingest`
+3. `audit`
+4. `search`, `seek`, or `activate`
+5. `batch_view` or `view`
+6. `coverage_session` if the investigation is getting wide
+
+Choose `audit` when you want the fastest high-level orientation. Choose `activate` after `audit` when the next question is subsystem-shaped. Choose `seek` after `audit` when the next question is intent-shaped.
+
+## Workflow 2: Find The Code That Does X
+
+1. `seek`
+2. `view` or `batch_view`
+3. `activate` if the best result needs neighborhood expansion
+4. `learn` after the result was actually useful
+
+Use this instead of `activate` when you know the job and want a specific implementation surface, not a cluster.
+
+## Workflow 3: Explore A Subsystem Or Topic
+
+1. `warmup` if the session is focused on one area for a while
+2. `activate`
+3. `why` for specific dependencies
+4. `resonate` when you need coherent clusters or refactor boundaries
+5. `learn` after useful results
+
+Use `include_structural_holes` in `activate` or call `missing` separately if the question smells like absence rather than presence.
+
+## Workflow 4: Triage A Bug From Error Output
+
+1. `trace`
+2. `impact` on the strongest suspect if the fix may be risky
+3. `why` for a specific suspect-to-effect chain
+4. `validate_plan`
+5. `surgical_context_v2`
+6. local edit path or `edit_preview` / `edit_commit`
+7. `predict`
+
+Use `trace` instead of manually chasing top stack frames when the runtime output is already available.
+
+## Workflow 5: Plan A Risky Change
+
+1. `seek` or `activate` to find the entry surface
+2. `impact`
+3. `validate_plan`
+4. `surgical_context_v2`
+5. optional `heuristics_surface` for why a file ranks as risky
+6. optional `edit_preview` for two-phase commit
+7. optional `apply_batch` when an external m1nd write path is actually desired
+8. `predict`
+
+Interpretation:
+
+- `impact` tells you what the root file touches
+- `validate_plan` tells you what your proposed change list is missing
+- `surgical_context_v2` gives connected source context in one shot
+- `predict` is the post-edit follow-through check
+
+## Workflow 6: Review Whether A Plan Or PR Is Incomplete
+
+1. `validate_plan`
+2. `impact` for any central modified file
+3. `predict` for changed nodes that still look under-covered
+4. `scan` or `scan_all` if structural quality or safety patterns matter
+5. `heuristics_surface` when you need a reasoned explanation of why a file is risky
+
+This is the review-time route when the important question is not "what changed?" but "what is still missing?"
+
+## Workflow 7: Implement From A Spec, Wiki, Or PDF
+
+1. choose the doc lane:
+   - authored semantic markdown -> `ingest` with `adapter: "light"`
+   - ordinary docs -> `ingest` with `adapter: "universal"` or `adapter: "auto"`
+2. for `universal`, use `document_provider_health` if richer extraction may matter
+3. for `universal`, use `document_resolve`
+4. for `universal`, use `document_bindings`
+5. for `universal`, use `document_drift`
+6. for both lanes, use `search`, `seek`, or `activate` on the merged graph
+7. `impact` or `validate_plan`
+8. `surgical_context_v2`
+
+Use this when a document must be connected to code, not merely quoted or summarized. Use `light` when the spec itself is graph-native. Use `universal` when the source must first be canonicalized.
+
+## Workflow 8: Multi-Repo Questions
+
+1. `federate` when the repo list is already known
+2. `federate_auto` when only import/path/contract evidence suggests sibling repos
+3. `activate`, `seek`, `impact`, or `trace` on the federated graph
+
+Use federation before pretending the current repo is the whole truth.
+
+## Workflow 9: Multi-Agent Exploration
+
+1. Give each agent a stable `agent_id`
+2. Use `perspective_start` per agent when route-state navigation is useful
+3. Use `perspective_branch` for parallel exploration
+4. Use `perspective_compare` to diff findings
+5. Use `trail_save` and `trail_merge` for handoff and convergence
+6. Use `lock_create`, `lock_watch`, `lock_diff`, `lock_rebase`, `lock_release` when concurrent edits or baselines matter
+
+Rules:
+
+- graph learning is shared
+- perspectives are isolated per agent
+- trails are shareable
+- locks are for coordination, not for solo reading
+
+## Workflow 10: Long-Lived Monitoring
+
+1. `daemon_start`
+2. `daemon_status`
+3. `daemon_tick` when an explicit reconciliation pass is needed
+4. `alerts_list`
+5. `alerts_ack`
+6. `persist`
+
+This is the right lane when the task is ongoing drift detection, not one-shot analysis.
+
+## Workflow 11: Session Resume Or Handoff
+
+1. `trail_list`
+2. `trail_resume`
+3. `drift` if the graph may have changed
+4. `warmup` if you only need gentle re-priming
+5. `boot_memory` for tiny durable facts that should stay hot
+
+Use `trail_resume` for real investigation continuity. Use `boot_memory` only for small canonical facts, not full investigative state.
+
+## Workflow 12: Deep Structural Or Risk Analysis
+
+Choose among these when basic search/impact is not enough:
+
+- `hypothesize`: test a structural claim
+- `counterfactual`: simulate node or module removal
+- `differential`: compare two graph snapshots
+- `diverge`: compare against a baseline and surface drift
+- `fingerprint` or `twins`: find structural equivalence
+- `resonate`: find reinforcing clusters
+- `layers` and `layer_inspect`: inspect architectural layering and violations
+- `ghost_edges`: use temporal co-change edges
+- `runtime_overlay`: bring in runtime heat and errors
+- `taint_trace`: follow taint propagation
+- `flow_simulate`: reason about concurrency turbulence
+- `epidemic`, `trust`, `tremor`, `antibody_*`: risk and defect-propagation surfaces
+
+## What Not To Force Through m1nd
+
+- Exact text already known: use `search` or `rg`
+- One known file with a simple question: use `view` or direct read
+- Compiler or test failure truth: use the compiler or test runner
+- Runtime behavior truth: use logs, traces, debugger, or profiler
+- Final local file mutation inside Codex: usually use `apply_patch`

package/skills/m1nd-operator/references/runtime-and-refresh.md

@@ -0,0 +1,135 @@
+# m1nd Runtime And Refresh Notes
+
+This file captures the local installation facts, the source-of-truth docs that were studied, and how to refresh them later without re-deriving everything.
+
+## Local Installation
+
+Most hosts should point their MCP config at the same native binary:
+
+- MCP server name: `m1nd`
+- Binary name: `m1nd-mcp`
+- Default launch args: `--stdio --no-gui`
+- Optional env override: `M1ND_MCP_BINARY=/absolute/path/to/m1nd-mcp`
+
+Use the bundled helper script to verify the current runtime instead of trusting memory:
+
+```bash
+python3 scripts/probe_m1nd.py tools
+python3 scripts/probe_m1nd.py call health '{"agent_id":"codex-m1nd"}'
+```
+
+## Official Sources Used
+
+Primary source repo:
+
+- [maxkle1nz/m1nd](https://github.com/maxkle1nz/m1nd)
+
+Docs that mattered most:
+
+- `README.md`
+- `EXAMPLES.md`
+- `docs/deployment.md`
+- `docs/wiki/src/tool-matrix.md`
+- `docs/wiki/src/faq.md`
+- `docs/wiki/src/benchmarks.md`
+- `docs/wiki/src/tutorials/quickstart.md`
+- `docs/wiki/src/tutorials/first-query.md`
+- `docs/wiki/src/tutorials/multi-agent.md`
+- `docs/wiki/src/architecture/overview.md`
+- `docs/wiki/src/architecture/graph-engine.md`
+- `docs/wiki/src/architecture/ingest.md`
+- `docs/wiki/src/architecture/mcp-server.md`
+- `docs/wiki/src/concepts/spreading-activation.md`
+- `docs/wiki/src/concepts/hebbian-plasticity.md`
+- `docs/wiki/src/concepts/xlr-noise-cancellation.md`
+- `docs/wiki/src/concepts/structural-holes.md`
+- `docs/wiki/src/api-reference/overview.md`
+- `docs/wiki/src/api-reference/activation.md`
+- `docs/wiki/src/api-reference/analysis.md`
+- `docs/wiki/src/api-reference/memory.md`
+- `docs/wiki/src/api-reference/exploration.md`
+- `docs/wiki/src/api-reference/perspectives.md`
+- `docs/wiki/src/api-reference/lifecycle.md`
+
+Reference timestamp for this study:
+
+- Date: 2026-04-20
+- Official repo commit checked locally: `d4a84000a3ae3b9848f8ce9505fab3ab00acd871`
+- Local clone matched `origin/HEAD` at the time of study. Re-check the live
+  runtime with `tools/list`, `trust_selftest`, or `scripts/probe_m1nd.py` before
+  relying on exact tool counts.
+
+## Important Truth Hierarchy
+
+When sources disagree, use this order:
+
+1. Live `tools/list` from the local binary
+2. `tool-matrix.md`
+3. API reference pages
+4. README, tutorials, FAQ, prose pages
+
+Reason: prose pages in the repo already contain stale counts in some places.
+
+## Count Discrepancy To Remember
+
+Official docs repeatedly describe the current surface as 93 tools.
+
+The local binary on this machine returned 92 canonical tool names via `tools/list` on 2026-04-20.
+
+Operational rule:
+
+- never hardcode the count
+- use the live runtime when counts or exact names matter
+- use the docs for intent, workflow, and semantics
+
+## What m1nd Is Best At
+
+- graph-grounded structural retrieval
+- blast-radius and hidden-neighbor analysis
+- pre-flight validation for risky changes
+- session continuity and cross-agent handoff
+- document-to-code bindings
+- long-lived structural monitoring
+
+## What Still Belongs Elsewhere
+
+- exact text lookup: `search` or `rg`
+- one known file: `view` or direct file read
+- compiler truth: compiler and tests
+- runtime truth: logs, traces, debugger, profiler
+
+## Live Probe Helper
+
+The helper script is intentionally generic so future sessions can refresh the environment quickly.
+
+Examples:
+
+```bash
+python3 scripts/probe_m1nd.py tools
+python3 scripts/probe_m1nd.py call help '{"agent_id":"codex-m1nd","tool_name":"validate_plan"}'
+python3 scripts/probe_m1nd.py call ingest '{"agent_id":"codex-m1nd","path":"/path/to/repo"}'
+python3 scripts/probe_m1nd.py run '[{"name":"ingest","arguments":{"agent_id":"codex-m1nd","path":"/path/to/repo"}},{"name":"activate","arguments":{"agent_id":"codex-m1nd","query":"session management","top_k":5}}]'
+```
+
+Behavior:
+
+- launches the configured local `m1nd-mcp` binary
+- performs MCP `initialize`
+- runs `tools/list` or `tools/call`
+- `run` keeps one `m1nd` process alive across multiple calls so in-memory graph state survives `ingest -> query` flows
+- prints parsed JSON instead of raw MCP envelopes when possible
+
+## Refresh Procedure
+
+When this skill starts feeling stale:
+
+1. Re-clone or pull the official `maxkle1nz/m1nd` repo in a scratch workspace.
+2. Re-read `tool-matrix.md`, `api-reference/overview.md`, `EXAMPLES.md`, `faq.md`, `benchmarks.md`, and any changed API pages.
+3. Run `python3 scripts/probe_m1nd.py tools` against the local installed binary.
+4. Update this skill only where the live runtime or official docs actually changed.
+
+## Host-Specific Note For Codex
+
+At the protocol level, `m1nd`'s canonical tool names are bare names like `activate` and `validate_plan`.
+
+If Codex exposes the MCP server as first-class tools, the host wrapper may namespace them differently, but the underlying routing logic in this skill should still be based on the canonical tool semantics above.

package/skills/m1nd-operator/references/tool-families.md

@@ -0,0 +1,168 @@
+# m1nd Tool Families
+
+This is the compact capability inventory for the current `m1nd` shape. Use the live runtime, not this file, when exact counts or schemas matter.
+
+## Foundation And Search
+
+- `ingest`: load or refresh the graph from code, JSON, memory, or universal docs.
+- `health`: confirm server and graph state.
+- `search`: exact text, regex, or graph-aware semantic search with line context.
+- `glob`: path-pattern search over indexed files.
+- `view`: bounded line-numbered file read.
+- `batch_view`: stable multi-file read surface.
+- `help`: self-documenting tool reference and recovery guidance.
+- `audit`: one-call orientation for unfamiliar repos.
+- `coverage_session`: what this agent has already visited.
+- `cross_verify`: graph-vs-disk verification.
+- `external_references`: explicit paths outside ingest roots.
+- `report`: session summary and savings.
+- `savings`: token-economy report.
+- `metrics`: structural metrics per file/function/module.
+- `type_trace`: follow a type across the graph.
+- `diagram`: generate Mermaid or DOT graph slices.
+- `panoramic`: ranked panorama of file-level risk across the repo.
+
+## Retrieval By Intent, Topic, Or Pattern
+
+- `seek`: find code by intent or purpose.
+- `activate`: find a neighborhood around a topic via spreading activation.
+- `warmup`: prime the graph for a task.
+- `resonate`: find mutually reinforcing clusters.
+- `why`: shortest path and dependency explanation between two nodes.
+- `missing`: surface structural holes or absent abstractions.
+- `scan`: run one structural pattern family.
+- `scan_all`: run all structural patterns in one call.
+- `timeline`: temporal history, churn, velocity, stability, and co-change shape.
+
+## Change-Risk And Plan Validation
+
+- `impact`: blast radius from a node.
+- `predict`: likely co-change partners after an edit.
+- `validate_plan`: pre-flight risk, gaps, missing tests, and suggested additions.
+- `heuristics_surface`: explain why a file or node ranked risky or important.
+- `hypothesize`: test a structural claim.
+- `counterfactual`: simulate node or module removal.
+- `differential`: compare two graph snapshots.
+- `diverge`: compare current graph against a baseline.
+
+## Memory, Learning, And Continuity
+
+- `learn`: reinforce or weaken paths based on feedback.
+- `drift`: see what changed since the last session or baseline.
+- `trail_save`: persist an investigation.
+- `trail_resume`: restore an investigation and re-inject boosts.
+- `trail_list`: browse saved investigations.
+- `trail_merge`: merge investigations across agents or sessions.
+- `persist`: force graph-sidecar persistence.
+- `boot_memory`: store tiny canonical hot-state values.
+
+Rules:
+
+- `learn` is how the graph adapts.
+- `trail_*` is for full investigative continuity.
+- `boot_memory` is for tiny durable facts, not full reasoning trails.
+
+## Stateful Navigation
+
+- `perspective_start`: create a navigable route surface from a query.
+- `perspective_routes`: paginate route options.
+- `perspective_inspect`: expand a route with score breakdown and provenance.
+- `perspective_peek`: preview code or doc content at a route target.
+- `perspective_follow`: move focus to the route target.
+- `perspective_suggest`: ask the graph which route to follow next.
+- `perspective_affinity`: inspect probable affinities for the current route target.
+- `perspective_branch`: fork a perspective for parallel exploration.
+- `perspective_back`: go back one navigation step.
+- `perspective_compare`: diff two perspectives.
+- `perspective_list`: list active perspectives for the agent.
+- `perspective_close`: release perspective state.
+
+Use this family only when navigation state is worth maintaining.
+
+## Docs, Wiki, PDF, And Universal Document Runtime
+
+- `ingest` with `adapter: "light"`: graph-native semantic markdown via the `L1GHT` protocol.
+- `document_resolve`: resolve canonical local artifacts for an ingested document.
+- `document_provider_health`: inspect optional provider availability and install hints.
+- `document_bindings`: map document claims or sections to code.
+- `document_drift`: detect stale, missing, or ambiguous document/code links.
+- `auto_ingest_start`: start local-first document watchers.
+- `auto_ingest_status`: inspect watcher state and provider/runtime counters.
+- `auto_ingest_tick`: force one deterministic document reconciliation pass.
+- `auto_ingest_stop`: stop watchers and persist manifest state.
+
+Use this family when docs must be graph-grounded, not merely read. Distinguish the lanes:
+
+- `light` for authored graph-native semantic markdown
+- `universal` for ordinary docs that need canonicalization and binding/drift surfaces
+
+## Surgical And Write Surfaces
+
+- `surgical_context`: single-file edit context with callers, callees, and neighbors.
+- `surgical_context_v2`: multi-file connected edit context, including source excerpts of related files.
+- `apply`: one-file write through m1nd.
+- `apply_batch`: atomic multi-file write through m1nd.
+- `edit_preview`: two-phase preview without touching disk.
+- `edit_commit`: freshness-checked commit for a preview.
+
+In Codex, prefer this family for analysis and change-prep. Use local `apply_patch` for actual file mutation unless the task explicitly wants or benefits from m1nd's own write lane.
+
+## Multi-Repo And Cross-Boundary Work
+
+- `federate`: combine known repos into one graph.
+- `federate_auto`: discover likely sibling repos from evidence, then optionally federate them.
+
+Use this before acting as if the current repo is the whole system.
+
+## Coordination, Locks, And Monitoring
+
+- `lock_create`: snapshot a region.
+- `lock_watch`: define a watch strategy on a lock.
+- `lock_diff`: compare current state with the lock baseline.
+- `lock_rebase`: accept current state as the new baseline.
+- `lock_release`: free the lock.
+- `daemon_start`: start long-lived structural monitoring.
+- `daemon_stop`: stop monitoring without deleting alert history.
+- `daemon_status`: inspect monitor liveness and counters.
+- `daemon_tick`: force one reconciliation pass.
+- `alerts_list`: list durable daemon or proactive alerts.
+- `alerts_ack`: acknowledge alerts so they stop resurfacing.
+
+Use locks when coordination or baselines matter. Use daemon and alerts when the task is ongoing.
+
+## Extended Risk, Architecture, And RETROBUILDER
+
+- `antibody_scan`: scan for known bug shapes.
+- `antibody_list`: inspect stored antibody patterns.
+- `antibody_create`: create, enable, disable, or delete antibody patterns.
+- `flow_simulate`: concurrency flow simulation.
+- `epidemic`: predict bug spread from known buggy nodes.
+- `tremor`: accelerating change-frequency detection.
+- `trust`: actuarial trust scores from defect history.
+- `layers`: infer architectural layers and violations.
+- `layer_inspect`: inspect a specific layer.
+- `ghost_edges`: temporal co-change ghost edges.
+- `taint_trace`: taint propagation over the graph.
+- `twins`: structural equivalence or near-equivalence.
+- `refactor_plan`: graph-native refactor proposals.
+- `runtime_overlay`: runtime heat and error overlays.
+
+Use these when basic retrieval and blast-radius work are no longer enough.
+
+## Current Live Surface On This Machine
+
+As validated on 2026-04-20 through the installed local binary, `tools/list` returned 92 canonical tool names:
+
+- `activate`, `impact`, `missing`, `why`, `warmup`, `counterfactual`, `predict`, `fingerprint`, `drift`, `learn`
+- `ingest`, `document_resolve`, `document_provider_health`, `document_bindings`, `document_drift`
+- `auto_ingest_start`, `auto_ingest_stop`, `auto_ingest_status`, `auto_ingest_tick`, `resonate`, `health`
+- `perspective_start`, `perspective_routes`, `perspective_inspect`, `perspective_peek`, `perspective_follow`, `perspective_suggest`, `perspective_affinity`, `perspective_branch`, `perspective_back`, `perspective_compare`, `perspective_list`, `perspective_close`
+- `seek`, `scan`, `timeline`, `diverge`
+- `trail_save`, `trail_resume`, `trail_merge`, `trail_list`
+- `hypothesize`, `differential`, `trace`, `validate_plan`, `federate`
+- `antibody_scan`, `antibody_list`, `antibody_create`, `flow_simulate`, `epidemic`, `tremor`, `trust`, `layers`, `layer_inspect`
+- `ghost_edges`, `taint_trace`, `twins`, `refactor_plan`, `runtime_overlay`
+- `heuristics_surface`, `surgical_context`, `apply`, `view`, `batch_view`, `surgical_context_v2`, `apply_batch`, `edit_preview`, `edit_commit`
+- `search`, `glob`, `scan_all`, `cross_verify`, `coverage_session`, `external_references`, `federate_auto`, `help`, `report`, `audit`
+- `daemon_start`, `daemon_stop`, `daemon_status`, `daemon_tick`, `alerts_list`, `alerts_ack`
+- `panoramic`, `savings`, `persist`, `boot_memory`, `metrics`, `type_trace`, `diagram`

package/skills/m1nd-operator/scripts/probe_m1nd.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import sys
+import shutil
+from typing import Any
+
+
+DEFAULT_BINARY = os.environ.get("M1ND_MCP_BINARY") or shutil.which("m1nd-mcp") or "m1nd-mcp"
+DEFAULT_ARGS = shlex.split(os.environ.get("M1ND_MCP_ARGS", "--stdio --no-gui"))
+
+
+class McpClient:
+    def __init__(self, binary: str, extra_args: list[str]) -> None:
+        self.proc = subprocess.Popen(
+            [binary, *extra_args],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        self._initialize()
+
+    def _request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        assert self.proc.stdin is not None
+        assert self.proc.stdout is not None
+        self.proc.stdin.write(json.dumps(payload) + "\n")
+        self.proc.stdin.flush()
+        line = self.proc.stdout.readline()
+        if not line:
+            stderr = ""
+            if self.proc.stderr is not None:
+                stderr = self.proc.stderr.read().strip()
+            raise RuntimeError(f"no response from m1nd-mcp; stderr={stderr}")
+        return json.loads(line)
+
+    def _initialize(self) -> None:
+        response = self._request(
+            {"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {}}
+        )
+        if "error" in response:
+            raise RuntimeError(f"initialize failed: {json.dumps(response, indent=2)}")
+
+    def tools(self) -> dict[str, Any]:
+        return self._request(
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+        )
+
+    def call(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        return self._request(
+            {
+                "jsonrpc": "2.0",
+                "id": 2,
+                "method": "tools/call",
+                "params": {"name": tool_name, "arguments": arguments},
+            }
+        )
+
+    def close(self) -> None:
+        if self.proc.poll() is None:
+            self.proc.terminate()
+            try:
+                self.proc.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+
+
+def parse_embedded_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def print_json(value: Any) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=True))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Probe the local m1nd MCP runtime.")
+    parser.add_argument("--binary", default=DEFAULT_BINARY, help="Path to m1nd-mcp.")
+    parser.add_argument(
+        "--binary-args",
+        default=" ".join(DEFAULT_ARGS),
+        help='Arguments for the binary, default: "--stdio --no-gui".',
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    tools_parser = subparsers.add_parser("tools", help="List the live tool surface.")
+    tools_parser.add_argument(
+        "--names-only", action="store_true", help="Print one tool name per line."
+    )
+
+    call_parser = subparsers.add_parser("call", help="Call one m1nd tool.")
+    call_parser.add_argument("tool_name", help="Canonical tool name, e.g. health.")
+    call_parser.add_argument(
+        "arguments_json",
+        nargs="?",
+        default="{}",
+        help='JSON object with tool arguments, e.g. \'{"agent_id":"codex"}\'.',
+    )
+
+    run_parser = subparsers.add_parser(
+        "run", help="Run multiple tool calls against the same m1nd process."
+    )
+    run_parser.add_argument(
+        "steps_json",
+        help=(
+            "JSON array of step objects, e.g. "
+            '\'[{"name":"ingest","arguments":{"agent_id":"codex","path":"/repo"}}]\''
+        ),
+    )
+
+    args = parser.parse_args()
+
+    binary_args = shlex.split(args.binary_args)
+    client = McpClient(args.binary, binary_args)
+    try:
+        if args.command == "tools":
+            response = client.tools()
+            tools = response["result"]["tools"]
+            if args.names_only:
+                for tool in tools:
+                    print(tool["name"])
+                return 0
+            print_json({"count": len(tools), "names": [tool["name"] for tool in tools]})
+            return 0
+
+        if args.command == "call":
+            try:
+                tool_arguments = json.loads(args.arguments_json)
+            except json.JSONDecodeError as exc:
+                raise SystemExit(f"invalid arguments_json: {exc}") from exc
+            response = client.call(args.tool_name, tool_arguments)
+            result = response.get("result", {})
+            content = result.get("content", [])
+            if content and content[0].get("type") == "text":
+                parsed = parse_embedded_json(content[0].get("text", ""))
+                output = {"isError": result.get("isError", False), "payload": parsed}
+                print_json(output)
+                return 0
+            print_json(response)
+            return 0
+
+        if args.command == "run":
+            try:
+                steps = json.loads(args.steps_json)
+            except json.JSONDecodeError as exc:
+                raise SystemExit(f"invalid steps_json: {exc}") from exc
+            if not isinstance(steps, list):
+                raise SystemExit("steps_json must be a JSON array")
+
+            outputs = []
+            for index, step in enumerate(steps, start=1):
+                if not isinstance(step, dict):
+                    raise SystemExit(f"step {index} must be an object")
+                tool_name = step.get("name")
+                tool_arguments = step.get("arguments", {})
+                if not isinstance(tool_name, str):
+                    raise SystemExit(f"step {index} is missing string field 'name'")
+                if not isinstance(tool_arguments, dict):
+                    raise SystemExit(
+                        f"step {index} field 'arguments' must be a JSON object"
+                    )
+                response = client.call(tool_name, tool_arguments)
+                result = response.get("result", {})
+                content = result.get("content", [])
+                payload: Any = response
+                if content and content[0].get("type") == "text":
+                    payload = {
+                        "isError": result.get("isError", False),
+                        "payload": parse_embedded_json(content[0].get("text", "")),
+                    }
+                outputs.append({"step": index, "name": tool_name, "result": payload})
+            print_json(outputs)
+            return 0
+
+        raise SystemExit(f"unsupported command: {args.command}")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())