Publish a tool-matrix SSOT for m1nd routing#81
Conversation
The SCM-aware daemon state now separates immutable startup baseline, moving reconciliation cursor, current HEAD, and last clean ref. This makes the adapter state explicit and gives us the right substrate for future since/clock semantics without changing the public MCP tool surface. Constraint: Preserve the current daemon contract while making SCM state explicit enough for later Watchman-style evolution Rejected: Reusing a single git_since_ref for baseline, cursor, and head | too ambiguous for future SCM-aware behavior Rejected: Adding a dedicated cursor-management tool | premature public surface growth for adapter-internal state Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep baseline immutable, cursor movable, and head observational; later SCM backends should map onto these roles instead of collapsing them again Tested: cargo fmt --check; cargo test -p m1nd-mcp daemon_start_detects_git_root_and_head -- --nocapture; cargo test -p m1nd-mcp daemon_start_prefers_merge_base_when_upstream_exists -- --nocapture; cargo test -p m1nd-mcp daemon_tick_uses_git_changed_set_when_available -- --nocapture; MCP smoke for baseline/head/cursor fields Not-tested: Long-running daemon sessions with upstream movement after startup
This adds a machine-oriented Tool Matrix SSOT derived from the live server surface and links it from the wiki summary, API overview, and README. Constraint: The published wiki currently advertises stale tool counts, so the matrix explicitly anchors count truth in the live server dispatch surface Rejected: Hand-writing a narrative-only tool overview | too easy to drift from the live registry and too weak for LLM-to-LLM routing Rejected: Using the published m1nd.world/wiki count as SSOT | already stale versus the callable surface Confidence: high Scope-risk: narrow Reversibility: clean Directive: When tool counts diverge, update the matrix from the live server surface first and let README/wiki pages point to it instead of inventing new counts Tested: generated matrix from live server/api sources; manual spot-check against API Reference, README, and wiki overview Not-tested: full wiki-build/render pass on the generated page
This adds a machine-oriented Tool Matrix SSOT for m1nd tool routing, updates README/wiki entrypoints to point at it, corrects stale public counts, and refreshes the checked-in wiki build so the published Pages bundle reflects the new source of truth. Constraint: m1nd.world/wiki is currently stale on tool counts, so the SSOT has to anchor in the live server dispatch surface rather than the previously published pages Rejected: Updating README prose without a canonical routing matrix | too weak to serve as LLM-to-LLM SSOT Rejected: Leaving wiki-build stale while updating source docs | would keep Pages inconsistent with the repo truth Confidence: high Scope-risk: narrow Reversibility: clean Directive: Whenever tool counts drift again, regenerate this matrix from the live server surface first, then rebuild wiki pages from source Tested: mdbook build docs/wiki; manual verification of tool-matrix.html and updated overview/summary links; source/registry reconciliation against m1nd-mcp/src/server.rs Not-tested: deployment of the refreshed wiki bundle to the live m1nd.world host
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ce17218e05
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `m1nd_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` | | ||
| | `m1nd_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` | | ||
| | `m1nd_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` | |
There was a problem hiding this comment.
This matrix is marked as the routing SSOT, but the command values use m1nd_* names (for example m1nd_activate) that are not accepted by the live dispatcher; dispatch_tool forwards the raw name and dispatch_core_tool matches canonical names like "activate", "impact", etc. in m1nd-mcp/src/server.rs. Any agent that follows this SSOT verbatim for tools/call will get UnknownTool failures instead of executing the intended tool, so the matrix should list canonical callable names (or clearly separate aliases from callable names).
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a machine-oriented “Tool Matrix SSOT” to the mdBook docs and updates public tool-count language to point at the live dispatch surface, alongside a refreshed checked-in wiki-build/ bundle and a small expansion of daemon git runtime state reporting.
Changes:
- Introduce
docs/wiki/src/tool-matrix.mdand link it from the mdBook summary + API overview as the canonical routing/count SSOT. - Update README/API docs to reflect 89 callable tools based on
m1nd-mcp/src/server.rs. - Refresh
wiki-build/output (new hashed assets, TOC/search/theme JS/CSS, fonts/licenses, and updated rendered pages) and extend daemon git state withgit_head_ref/git_last_clean_ref.
Reviewed changes
Copilot reviewed 36 out of 65 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| wiki-build/tutorials/quickstart.html | Regenerated page; adds Antigravity client snippet and updates hashed asset references. |
| wiki-build/tomorrow-night-4c0ae647.css | New/updated highlight theme CSS in generated build. |
| wiki-build/toc.html | Generated sidebar iframe content updated to include Tool Matrix and new section naming. |
| wiki-build/toc-f77fd02f.js | Generated sidebar JS updated (TOC + “On this page” header expansion behavior). |
| wiki-build/searcher-c2a407aa.js | Generated search JS updated to new searchindex hash. |
| wiki-build/mark-09e88c2c.min.js | Bundled mark.js dependency for search highlighting. |
| wiki-build/highlight-493f70e1.css | Bundled highlight.js CSS. |
| wiki-build/fonts/SOURCE-CODE-PRO-LICENSE.txt | Added/updated font license text in build output. |
| wiki-build/fonts/OPEN-SANS-LICENSE.txt | Added/updated font license text in build output. |
| wiki-build/fonts/fonts-9644e21d.css | Generated font-face CSS for bundled fonts. |
| wiki-build/favicon-de23e50b.svg | Updated favicon asset in build output. |
| wiki-build/favicon-8114d1fc.png | Updated favicon PNG asset in build output. |
| wiki-build/elasticlunr-ef4e11c1.min.js | Bundled elasticlunr dependency for search index. |
| wiki-build/css/variables-8adf115d.css | Generated theme variables CSS update. |
| wiki-build/css/print-9e4910d8.css | Generated print stylesheet update. |
| wiki-build/css/general-2459343d.css | Generated base/content stylesheet update. |
| wiki-build/css/chrome-ae938929.css | Generated UI/chrome stylesheet update. |
| wiki-build/clipboard-1626706a.min.js | Bundled clipboard.js dependency for code copy buttons. |
| wiki-build/book-a0b12cfe.js | Generated mdBook runtime JS (themes/sidebar/search/copy/playground). |
| wiki-build/ayu-highlight-3fdfc3ac.css | Bundled ayu highlight CSS theme. |
| wiki-build/404.html | Generated 404 page updated to new asset hashes + navigation. |
| wiki-build/.nojekyll | Ensures GitHub Pages does not run Jekyll on mdBook output. |
| README.md | Updates tool-surface count statement and links to Tool Matrix SSOT. |
| m1nd-mcp/src/session.rs | Adds daemon git fields to persisted runtime state struct. |
| m1nd-mcp/src/daemon_handlers.rs | Populates/exposes new daemon git fields; updates daemon tests accordingly. |
| docs/wiki/src/tool-matrix.md | Adds the new Tool Matrix SSOT markdown page. |
| docs/wiki/src/SUMMARY.md | Renames API Reference section and adds Tool Matrix link. |
| docs/wiki/src/api-reference/overview.md | Updates tool-count language and links to Tool Matrix SSOT for routing/count truth. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | command | core_function | choose_when | avoid_when | required | returns | next | | ||
| |---|---|---|---|---|---|---| | ||
| | `m1nd_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` | | ||
| | `m1nd_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` | | ||
| | `m1nd_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` | |
There was a problem hiding this comment.
The Tool Matrix rows use m1nd_* command names (e.g., m1nd_ingest), but the canonical MCP tool names exposed by tool_schemas() / dispatch_tool() are unprefixed (e.g., ingest, activate). As written, this SSOT will cause clients/LLMs to attempt calling non-existent tool names unless there is an alias layer. Consider switching the matrix to canonical names (and optionally adding a note that some clients may prefix m1nd_ if supported).
| | field | meaning | | ||
| |---|---| | ||
| | `command` | canonical MCP call name, underscore transport form | | ||
| | `category` | routing bucket | |
There was a problem hiding this comment.
The Row Contract lists a category field, but the tables below don’t include a category column (they start with command | core_function | ...). Either add category to the tables or remove it from the contract so the SSOT schema is internally consistent for machine parsing.
| | `category` | routing bucket | |
| @@ -0,0 +1 @@ | |||
| This file makes sure that Github Pages doesn't process mdBook's output. | |||
There was a problem hiding this comment.
Typo/casing: "Github Pages" should be "GitHub Pages".
| This file makes sure that Github Pages doesn't process mdBook's output. | |
| This file makes sure that GitHub Pages doesn't process mdBook's output. |
| let git_head_ref = state | ||
| .daemon_state | ||
| .git_root | ||
| .as_deref() | ||
| .and_then(|root| git_head_ref(Path::new(root))); | ||
| state.daemon_state.git_baseline_ref = git_baseline_ref.clone(); | ||
| state.daemon_state.git_baseline_kind = git_baseline_kind; | ||
| state.daemon_state.git_since_ref = git_baseline_ref; | ||
| state.daemon_state.git_since_ref = git_baseline_ref.clone(); | ||
| state.daemon_state.git_head_ref = git_head_ref; | ||
| state.daemon_state.git_last_clean_ref = git_baseline_ref; |
There was a problem hiding this comment.
git_last_clean_ref is populated with git_baseline_ref on start (which may be a merge-base) and later overwritten with HEAD on every tick, regardless of whether there are working-tree changes. If this field is meant to represent the last clean (no local diffs) ref, it needs an explicit cleanliness check (e.g., git diff --quiet/git status --porcelain) before updating; otherwise consider renaming to something like git_last_scan_ref/git_last_head_ref to avoid misleading API consumers.
Summary
Why this matters
The wiki and README were no longer enough as a routing source of truth for
m1nd. This change gives us one canonical matrix that an LLM or agent can use to choose the best tool, while also making the published docs explicit about where count truth actually comes from.Validation
m1nd-mcp/src/server.rsmdbook build docs/wikiwiki-build/tool-matrix.html