@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mos",
   "description": "MindrianOS -- Your AI innovation co-founder. Larry thinks with you through PWS methodology, builds your Data Room as you explore, and chains frameworks intelligently. Install and go.",
-  "version": "1.13.0-beta.17",
+  "version": "1.13.0-beta.21",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian.ai"

package/.mcp.json

@@ -2,7 +2,12 @@
   "mcpServers": {
     "mindrian-os": {
       "command": "node",
-      "args": ["bin/mindrian-mcp-server.cjs"],
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mindrian-mcp-server.cjs"],
+      "alwaysLoad": true
+    },
+    "mindrian-brain": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mindrian-brain-mcp-client.cjs"],
       "alwaysLoad": true
     }
   }

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [1.13.0-beta.21] - 2026-05-20
+
+### Added
+- (next-pre-release Commit B placeholder; Phase 127 Brain MCP Local Stdio Shim work ships here per `.planning/v1.13.1-EXECUTION-PLAN.md` AMENDMENT 2026-05-19)
+
+## [1.13.0-beta.19] - 2026-05-19
+
+### Promoted (2026-05-19 -- v1.13.0 milestone redefinition)
+- **Phase 127 (Brain MCP Local Stdio Shim + Auto-Migration) and Phase 127.1 (Brain GraphRAG Collapse Pinecone -> Neo4j HNSW) PROMOTED from v1.13.1 INTO v1.13.0.** v1.13.0 milestone redefined from "The Closed Loop" (Hooked Fixes + Canon Part 10) to **"The Closed Loop + Brain Goes Native"**. Phase 127 targets v1.13.0-beta.20 (client-side stdio shim, ~3-5 days; Tavily-validated 2026-05-19); Phase 127.1 targets v1.13.0-beta.21 (server-side Neo4j HNSW collapse, ~3-5 days + 20-query non-regression harness >= 80% top-5 overlap). v1.13.0 final cuts after both land. Trade-off: ~2-week ship-date slip, but ONE adoption cycle for "Brain feels native end-to-end" instead of two. v1.13.1 milestone keeps Phases 128/129/130/131 but loses its architectural anchor (renaming pending: "spine repair + lens engine + research workflow", not "Brain native"). External validation in flight via Tavily research agent before /gsd:plan-phase 127 fires. See ROADMAP.md Phase 127 + 127.1 sections, both CONTEXT.md files (frontmatter `milestone:` flipped 2026-05-19), and .planning/v1.13.1-EXECUTION-PLAN.md AMENDMENT block.
+
+### Added (2026-05-17 -- 2026-05-19 endgame work bundled into this beta)
+- **Phase 120 (Breakthrough Scan Category G) shipped 2026-05-17.** 9-of-9 must-haves verified. Hooked Fix 3 (Category G) closed: variable-reward axis ships the highest-nutrition flavor (own-breakthroughs surfaced back at the navigator). 4 detectors (convergence / contradiction-resolved / cross-domain analogy / reverse-salient closed) + F.7 Breakthrough Surface selector (5 verbs: Explore deeper / Confirm / File as decision / Dismiss / Back) + session-start scanner via Phase 109 navigation.cjs chokepoint + D-13..D-15 resurfacing rules + D-19 per-detector dismissal-rate canary + D-17 4-rule voice scaffold + D-18 4-tier ethics fence (HARD_FLOOR / SOFT_BAND / NEUTRAL / GREEN) + SOFT_BAND review queue in rooms-meta.db + 5-component scoring formula + "More breakthroughs (N)" affordance + D-20 LOAD-BEARING SQL invariant (every Breakthrough has a DERIVED_FROM edge by construction; 4 structural enforcement points). 159 unit tests + 4 D-20 e2e + 13 ethics-fence + voice-audit + 3 scaffold harnesses all green. Canon Part 4 cascade vocab honored (8 types; 2026-05-16 dual-graph review rejection sealed -- no ASSOCIATION_LENS / TRANSITION_LENS). Canon Part 8 clean. Canon Part 9 chokepoint preserved (10 modules route through navigation.cjs).
+- **Phase 121 (Trajectory Telemetry) shipped 2026-05-19.** 12-of-12 must-haves verified. Reframed per Canon Part 7 from "greenfield instrumentation" to "consolidation": 4 piecemeal telemetry writers (`mva.jsonl` + `selector.jsonl` + `navigation-bypass.jsonl` + `query-efficiency.jsonl`) collapse to ONE unified `~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl` with `type` discriminator + frozen v1 schema (per-row `schema_version: 1` Number, 15 EVENT_TYPES) + ISO-week rotation + single emit-time-validator chokepoint (7 forbidden-pattern detectors, mirrors proven `mva-telemetry.cjs` shape) + idempotent migration (source-name-prefixed sha256 fingerprint, originals renamed `*.pre-v121.bak`) + `mva-telemetry.cjs` 170 -> 58-line shim delegating to writer with legacy dual-write (Phase 118 byte-functional compat preserved; dual-write retires v1.14.0). 9 capture points wired: selector picks (88.2 + 125), tension engagement (116), auto-explore decisions (117), breakthrough dismissed (120), MVA + Hooked re-score (inherited), empathy audit CLI, room-receipt (119), PostToolUse broad-sweep into separate `command_invocation` bucket (drowning-protected via type discriminator; 100 cmd_inv + 10 selector_pick fixture proves filter-isolation). `docs/TELEMETRY-SCHEMA.md` (364 LOC) frozen v1 spec + SEED-002 ingestion guidance (arXiv 2508.03680). Canon Part 8 adversarial audit (7 gates across 17 telemetry-touching files; zero LOCAL->BRAIN egress) + D-12 silent-observability invariant (4 gates). 19/19 test suites green.
+- **Phase 121.5 re-verify fix 2026-05-19.** `/mos:dogfood-flush` (added by Phase 120) registered in `data/help-groups.json` Infrastructure group. Restores 3 previously-failing 121.5 coherence tests. Capstone coherence invariant holds against the now-complete v1.13.0 surface. `bash tests/run-all-121.5.sh` -> 11/11 suites green.
+- **SEED-003 (Brain Silent Identity) filed 2026-05-19.** Deferred user request to eliminate the API-key step entirely on top of Phase 127's stdio shim. Three architectural options scoped (per-install silent registration / plugin attestation HMAC / anonymous tier + degraded payload).
+
+### Added
+- **`/mos:mos` state-aware router (Phase 121.5-08 Sub-plan J; D-10 LOCKED).** Closes the plugin.json declaration gap flagged in Cluster 5 audit 2026-05-15 (the command was declared but the backing file was absent). The router picks the right next surface for the navigator: no room -> `/mos:onboard`; mostly-empty room -> `/mos:status` with a "suggest next move" hint; populated room -> `/mos:suggest-next`. Backed by `lib/core/state-aware-router.cjs` (pure function, hermetic unit tests in `lib/memory/state-aware-router.test.cjs`). Meets the navigator where they are -- one entrypoint that always does the right thing rather than forcing the user to pick the right `/mos:*` surface. (`commands/mos.md` [new], `lib/core/state-aware-router.cjs` [new], `lib/memory/state-aware-router.test.cjs` [new].)
+- **Soft-alias runner + 5 soft-alias stubs (Phase 121.5-08 Sub-plan J; D-09 LOCKED).** New helper `scripts/soft-alias-runner.cjs` (`softAliasRun` pure function + `emitForLLM` CLI form) returns a JSON envelope `{redirect, deprecation_note, args, ok}` so the LLM can print a single cyan deprecation line (Larry voice, no em-dash) and then transparently invoke the canonical command. Hermetic unit tests in `lib/memory/soft-alias.test.cjs` (45 PASS). (`scripts/soft-alias-runner.cjs` [new], `lib/memory/soft-alias.test.cjs` [new].)
+- **`/mos:doctor --deprecated-usage` (class L, NEW; Phase 121.5-08 Sub-plan J; D-09 final clause).** Scans recent (last-7-days) `~/.claude/projects/.../*.jsonl` session transcripts for `/mos:<deprecated>` patterns and surfaces a per-command "use `/mos:<new>` instead" hint. Pure LOCAL scan -- zero network, zero Brain, zero telemetry egress (Canon Part 8 preserved). Also activated by `--all`. Hermetic unit tests in `lib/memory/doctor-deprecation-surface.test.cjs`. `MINDRIAN_DOCTOR_TRANSCRIPTS_DIR` env-var override for hermetic tests. (`scripts/doctor.cjs`, `commands/doctor.md`, `lib/memory/doctor-deprecation-surface.test.cjs` [new].)
+- **F.1 Next Move selectors wired on `/mos:onboard` Step 6 + `/mos:diagnose` recommendation block (Phase 121.5-08 Sub-plan J; D-12 LOCKED).** Closes Canon Part 3 violations flagged in Cluster 5 audit 2026-05-15: the recommendation surfaces previously rendered as bare prose, bypassing the Decision Gate. Both surfaces now render the canonical 3-verb F.1 vocabulary (Run Methodology / Defer / Free-Text) via AskUserQuestion; the selected verb writes to STATE.md Decisions + creates a typed edge in the local graph. (`commands/onboard.md`, `commands/diagnose.md`.)
+
+### Changed
+- **5 commands deprecate to canonical surfaces (Phase 121.5-08 Sub-plan J; D-09 LOCKED).** All old commands remain functional for v1.13.x (soft-alias stubs with deprecation notes routed through `scripts/soft-alias-runner.cjs`); removal is scheduled v1.14.0. Zero tester breakage during v1.13.x:
+  - `/mos:heal` -> `/mos:doctor --heal-room` (folds into doctor's class E fix engine)
+  - `/mos:query` -> `/mos:graph "<question>"` (terminal natural-language Q&A collapses into the graph translator)
+  - `/mos:organize` -> `/mos:rooms organize <verb>` (portfolio grouping folds under the multi-room surface)
+  - `/mos:hmi-status` -> `/mos:doctor --ui-compliance --json` (D-11 LOCKED; standalone command goes away; functionality lives in doctor class F)
+  - `/mos:visualize` -> `/mos:dashboard --mermaid` (the dashboard already renders Cytoscape; the `--mermaid` flag covers the Mermaid code-block fallback that visualize used to provide)
+- **`/mos:diagnostics` is being renamed to `/mos:fingerprint` in v1.14.0 (no functional change).** The rename kills the diagnose/diagnostics naming ambiguity. Both invocations work in v1.13.x; use `/mos:fingerprint` going forward. (`commands/diagnostics.md` frontmatter `renaming_to: fingerprint`; body prepends a Renamed note before the unchanged 4-algorithm dispatcher.)
+
 ## [1.13.0-beta.17] - 2026-05-15
 
 ### Fixed

package/README.md

@@ -1,97 +1,94 @@
 <div align="center">
-  <img src="https://mindrianos-jsagirs-projects.vercel.app/logo_dark.svg" alt="MindrianOS" width="160" />
+  <img src="https://mindrianos-jsagirs-projects.vercel.app/logo_dark.svg" alt="MindrianOS" width="200" />
 
   # MindrianOS
 
-  **The thinking partner for problems worth solving.**
+  **When you are walking through a problem worth solving and you cannot yet name what is missing, MindrianOS is the thinking partner that walks beside you.**
 
-  Powered by PWS, a well-tested, pedagogically-built innovation methodology by
-  [Prof. Lawrence Aronhime](https://www.linkedin.com/in/lawrence-aronhime-8363894/).
-  Built by [Jonathan Sagir](https://www.linkedin.com/in/jonathansagir/).
+  Powered by PWS (Problems Worth Solving), an innovation methodology built and tested through 20 years of teaching by Prof. Lawrence Aronhime.
+  Engineered by Jonathan Sagir.
 
-  [![Version](https://img.shields.io/badge/v1.13.0-The_Closed_Loop-blue)](CHANGELOG.md)
-  [![License](https://img.shields.io/badge/license-BSL_1.1-orange)](LICENSE)
-  [![Works on](https://img.shields.io/badge/works_on-CLI_+_Desktop_+_Cowork-brightgreen)](#three-surfaces)
+  [![Version](https://img.shields.io/badge/v1.13.0-The_Closed_Loop-1E3A6E)](CHANGELOG.md)
+  [![License](https://img.shields.io/badge/license-BSL_1.1-C8A43C)](LICENSE)
+  [![Works on](https://img.shields.io/badge/CLI_+_Desktop_+_Cowork-2D6B4A)](#three-surfaces)
 
-  [Website](https://mindrianos-jsagirs-projects.vercel.app) |
-  [Marketplace](https://github.com/jsagir/mindrian-marketplace) |
+  [Website](https://mindrianos-jsagirs-projects.vercel.app) ·
+  [Marketplace](https://github.com/jsagir/mindrian-marketplace) ·
   [Brain Access](https://mindrianos-jsagirs-projects.vercel.app/brain-access)
-
 </div>
 
 ---
 
-## The job
-
-You are working on something that matters. A venture. A research direction. A grant. A pivot. The problem you are trying to solve is real, but it is undefined, and you keep getting lost in it. You take notes, but the notes pile up. You have meetings, but you forget what was said two weeks ago. You make decisions, but you cannot remember why.
+## The answer first
 
-The hard part is not writing things down. The hard part is seeing what you cannot see: the contradiction between yesterday's strategy and today's market signal, the assumption that quietly went stale, the connection between two meetings that nobody noticed.
+> When you talk to Larry about what you are working on, MindrianOS turns the conversation into a structured room, remembers your decisions across sessions, and surfaces the contradictions you would otherwise miss.
 
-MindrianOS is built for that. It is the thinking partner that walks beside you while you walk through the wicked problem.
+You do not learn a tool. You talk. The room takes shape underneath the conversation. Whatever you said yesterday is still working for you today.
 
 ---
 
-## How it works
+## How it works (in three pieces)
+
+### Larry is the thinking partner
+
+Larry is the AI you talk to. Larry asks the questions that reframe the problem before you try to solve it, suggests the method that fits where you are, and files what you say into your room without making you stop to organize. You do not have to know the framework names. You describe what you are doing. Larry routes you.
+
+### The Data Room is your venture made legible
 
-You install the plugin. You start talking. The rest takes care of itself.
+Every conversation, every meeting, every decision lands in a folder structure organized by venture stage: the problem, the market, the solution, the team, the money, the IP, the meetings, the opportunities. You open it in your file manager. You back it up like any other folder. You own it.
 
-**Larry is the thinking partner.** Larry is the AI personality you talk to. Larry asks questions, suggests the right methodology for where you are, and quietly files what you say.
+### The room surfaces what you cannot see
+
+Every time you add something new, the system compares it against everything already there. Larry tells you what just changed. What contradicts what. What connects to what. What is now missing. What you stopped checking weeks ago.
+
+You decide: APPROVE, REJECT (with a reason), or DEFER. The reason becomes part of the room. The next scan is smarter.
+
+---
 
-**The Data Room is your venture made legible.** Every conversation, every meeting, every decision lands in a folder structure organized by venture stage: the problem, the market, the solution, the team, the money, the IP, the meetings, the opportunities. You can open it in your file manager. You own it.
+## What v1.13.0 changed (The Closed Loop)
 
-**The intelligence layer surfaces what you cannot see.** Every time you add something to the room, the system scans the rest and tells you what just changed. What contradicts what. What connects to what. What is now missing. What you stopped checking weeks ago.
+Before this release, MindrianOS could file your work and surface intelligence, but the loop did not always close. You would say something, the system would react, and nothing carried forward. v1.13.0 closes the loop:
 
-**Your decisions teach the system.** When the system surfaces something, you decide: APPROVE (it cascades), REJECT (and tell the system why), or DEFER. Your reason becomes part of the room's memory. The next scan is smarter.
+- **Larry leads turn one.** The first thing you see is a conversation, not a command menu.
+- **Your first sentence becomes a room.** Type a venture sentence, get a 30-second brief and a populated room before you have to commit anything else.
+- **Tensions persist across sessions.** Larry remembers what was unresolved and brings it back when relevant.
+- **Every conversation produces an artifact.** A first session leaves you with a real room, not an empty wizard.
+- **Decisions teach the system.** Your approvals, your rejections, your reasons become part of the room's working memory.
 
-**The Brain orchestrates the method.** The Brain orchestrates a pedagogically-built, well-tested curated method for innovation against your current context, surfacing connections, contradictions, and gaps no single mind can hold. Connecting it makes Larry sharper. Not connecting it is fine; the system still teaches you. Either way, your venture data stays on your machine. The Brain only answers methodology questions, never sees your notes.
+Currently shipping as `v1.13.0-beta.19`. Final `v1.13.0` is imminent.
 
 ---
 
-## What you actually do in a session
+## What you do in a session
 
-You talk. You type a few commands when you know the shortcut. You let Larry teach you the methodology when you do not.
+Talk. Type a command when you know the shortcut. Let Larry teach you when you do not.
 
 ```bash
 /mos:new-project          # tell Larry what you are exploring
 /mos:beautiful-question   # reframe the problem before solving it
 /mos:analyze-needs        # who has this problem, how badly, what they have tried
 /mos:lean-canvas          # one-page business model
-/mos:file-meeting         # paste a transcript, Larry files it and surfaces what changed
+/mos:file-meeting         # paste a transcript, Larry files it
 /mos:opportunities        # what grants match this room right now
 /mos:query "what is the weakest assumption in my financial model?"
-/mos:grade                # honest assessment, calibrated against real ventures
+/mos:grade                # honest assessment against real ventures
 ```
 
-You do not have to memorize these. Just describe what you are trying to do; Larry routes you.
+You do not have to memorize these. Describe what you are trying to do. Larry routes you.
 
 ---
 
-## What v1.13.0 changed
-
-This release is called **The Closed Loop**. Before this version, MindrianOS could file your work and surface intelligence, but the loop did not always close: you would say something, the system would react, and then nothing would carry forward to the next session.
+## Why the room compounds
 
-In v1.13.0, the loop closes:
-- **Larry leads turn one.** The first thing you see is a conversation, not a command menu.
-- **The first file you write triggers a background scan.** You will see findings on your next turn: whitespace, contradictions, cross-domain analogies you could borrow from.
-- **Contradictions persist across sessions.** Larry remembers what was unresolved and brings it back when relevant.
-- **Every conversation produces a real artifact.** A first session leaves you with a populated room, not an empty wizard.
-- **Your decisions are graph data.** The room learns from your approvals, your rejections, and the reasons you give.
+Most tools get messier the more you put in. Search ranks worse. Folders bloat. The AI forgets what you told it last session. MindrianOS goes the other way.
 
-It is currently shipping as a release candidate (`v1.13.0-beta.13`). Final `v1.13.0` is imminent.
-
----
-
-## Why this gets better the longer you use it
-
-MindrianOS is a thinking tool that compounds. Most tools get messier the more you put in -- the search ranks worse, the folder gets bigger, the AI forgets what you told it last session. MindrianOS goes the other way.
-
-Here is the mechanism, in plain words: every conversation you have with Larry, every meeting you file, every decision you make and reason you give becomes part of your room. The room is searchable, structured, and remembered across sessions. Every NEW thing you add gets compared against everything already there.
+The mechanism is plain. Everything you say to Larry, every meeting you file, every decision you make and reason you give becomes part of your room. The room is searchable, structured, and remembered. Every NEW entry compares against everything already there.
 
 Day one, you have a folder.
 
 Day thirty, you have a folder that catches the contradiction between yesterday's strategy call and last week's customer interview, because nothing about either was forgotten. Larry brings back the assumption you made in week two when you are about to make a decision in week eight that depends on it. The room finds the connection between two meetings that happened a month apart that nobody remembers being related.
 
-The mechanism is not magic. It is just: nothing forgets, everything compares, and your own past work works for you. The longer you stay, the more the room knows, the more the room can show you what you cannot see on your own.
+Nothing forgets. Everything compares. Your own past work works for you.
 
 ---
 
@@ -125,37 +122,35 @@ mindrian-os update           # marketplace + plugin update
 mindrian-os doctor --all     # diagnose drift, suggest fixes
 ```
 
-### A note on install prompts
-
-Claude Code asks you to approve each shell command during install. 10+ prompts is normal. Pick "always allow" the first time you see one you are happy approving; the rest will not re-prompt.
+A note on install prompts: Claude Code asks you to approve each shell command. 10+ prompts is normal. Pick "always allow" the first time you see one you are happy with; the rest will not re-prompt.
 
 ---
 
 ## Three surfaces
 
-MindrianOS works wherever Claude works. One plugin, three places.
+MindrianOS works wherever Claude works.
 
 | Surface | What it gives you |
 |---------|-------------------|
 | **Claude Code CLI** | Full power. Hooks fire, scripts run, the room is on disk, Larry teaches with visible structure. |
-| **Claude Desktop** | Same Larry, conversational. The Data Room shows up as inline MCP Apps (dashboard, wiki, knowledge graph). |
+| **Claude Desktop** | Same Larry, conversational. The Data Room shows up as inline panels (dashboard, wiki, knowledge graph). |
 | **Cowork** | Same plugin, shared room. Daily briefings, persistent perspectives, multi-user. |
 
 ---
 
 ## The privacy line
 
-MindrianOS reads your workspace and writes only to your rooms (default: `~/MindrianRooms/`) and to session state (`./.mindrian/`). It does not write to the Brain server. Brain queries carry methodology questions only, never your notes, never your decisions, never your meetings.
+MindrianOS reads your workspace and writes only to your rooms (default: `~/MindrianRooms/`) and to session state (`./.mindrian/`). It does not push anything to the Brain. Brain queries carry methodology questions only, never your notes, never your decisions, never your meetings.
 
-If you want zero permission prompts during a session: `claude --dangerously-skip-permissions`. The read/write surface is bounded to your workspace and your rooms, so this is a reasonable choice for a methodology workflow. If you would rather be granular, paste the matcher set from [`docs/settings-template.json`](docs/settings-template.json) into `~/.claude/settings.json`.
+For zero permission prompts during a session: `claude --dangerously-skip-permissions`. The read/write surface is bounded to your workspace and your rooms. For granular control, copy the matcher set from [`docs/settings-template.json`](docs/settings-template.json) into `~/.claude/settings.json`.
 
 ---
 
 ## Why PWS, why Larry
 
-PWS (Problems Worth Solving) is a well-tested, pedagogically-built innovation methodology by Prof. Lawrence Aronhime. It is not a checklist. It is a way of thinking about ventures as wicked problems that need to be reframed before they can be solved, and that demand a working memory because nobody can hold the whole thing in their head.
+PWS (Problems Worth Solving) is not a checklist. It is a way of thinking about ventures as wicked problems that need to be reframed before they can be solved, and that demand a working memory because nobody can hold the whole thing in their head.
 
-Larry is the personality that delivers PWS in your terminal. The teaching is intrinsic; you do not have to know the framework names. Larry asks the question, suggests the move, and shows the chain. You decide.
+Larry is the personality that delivers PWS in your terminal. The teaching is intrinsic. You do not have to know the framework names. Larry asks the question, suggests the move, shows the chain. You decide.
 
 ---
 

package/bin/mindrian-brain-mcp-client.cjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mindrian-brain MCP stdio shim (Phase 127, BRAIN-MCP-127-01)
+ *
+ * Local stdio MCP server that proxies the 6 canonical Brain tools to the
+ * remote Render-hosted Brain via lib/core/brain-client.cjs. Bundled with the
+ * plugin via .mcp.json so every new install gets mindrian-brain auto-loaded
+ * with zero user wiring beyond MINDRIAN_BRAIN_KEY in env / ~/.mindrian.env.
+ *
+ * Canon Part 7: ~85% reuse of brain-client.cjs -- this file is JUST a stdio
+ * transport wrapper. It contains zero network code; every Brain payload is
+ * constructed by brain-client.cjs (which inherits Phase 110 typed-packet
+ * enforcement on its typed-job entry; this shim proxies the 6
+ * tool-surface entry points which carry only generic methodology handles
+ * per Canon Part 8).
+ *
+ * Canon Part 8: adversarial scan against this file's active code MUST return
+ * zero matches for the network-surface token set (delegation property --
+ * every network call lives in brain-client.cjs).
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const path = require('path');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+
+const brainClient = require('../lib/core/brain-client.cjs');
+const { wrapDirective } = require('../lib/core/directive-envelope.cjs');
+const { tier0Response: chokepointTier0 } = require('../lib/core/tier0-messaging.cjs');
+
+const pluginRoot = path.resolve(__dirname, '..');
+const pluginMeta = require('../.claude-plugin/plugin.json');
+const version = pluginMeta.version;
+
+// Tier-0 sentinel -- structured DIRECTOR_NOT_AVAILABLE response. Returned by
+// the 5 tools that surface raw Brain payloads (query/schema/search/stats/write).
+// brain_ask wraps Tier-0 differently (in a DirectiveEnvelope) so Larry's
+// surface reads a uniform shape regardless of tier.
+//
+// Phase 127-02 BRAIN-MCP-127-09 refactor: this is now a one-line passthrough
+// to the single chokepoint at lib/core/tier0-messaging.cjs. The local symbol
+// is preserved so existing tests + tool closures keep their reference.
+// Delegation property: zero duplicate sentinel-shape definition lives here.
+function tier0Response(commandContext) {
+  return chokepointTier0(commandContext);
+}
+
+function asContent(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj) }] };
+}
+
+const server = new McpServer({ name: 'mindrian-brain', version: version });
+
+// -- brain_ask: highest-level entry; wraps response in DirectiveEnvelope.
+server.tool(
+  'brain_ask',
+  'Natural-language methodology question. Returns a DirectiveEnvelope (default mode: GUIDED) carrying the directive content. Auto-routes Pinecone/Neo4j server-side.',
+  { question: z.string().describe('A methodology question (generic framework handles only -- never user artifacts or personal data per Canon Part 8).') },
+  async ({ question }) => {
+    if (!brainClient.isAvailable()) {
+      return asContent(wrapDirective(null, { brain_unreachable: true, command_context: 'brain_ask' }));
+    }
+    const raw = await brainClient.ask(question);
+    if (raw == null) {
+      return asContent(wrapDirective(null, { brain_unreachable: true, command_context: 'brain_ask' }));
+    }
+    const signals = (raw && typeof raw === 'object' && raw.mode_signals) ? raw.mode_signals : {};
+    return asContent(wrapDirective(raw, signals));
+  }
+);
+
+// -- brain_query: raw Cypher (generic methodology handles only).
+server.tool(
+  'brain_query',
+  'Cypher query against the Brain teaching graph. Generic framework handles only (Canon Part 8). Returns { records: [...] } on success.',
+  {
+    cypher: z.string().describe('Cypher query string.'),
+    params: z.record(z.any()).optional().describe('Optional binding map -- generic handles only.'),
+  },
+  async ({ cypher, params }) => {
+    if (!brainClient.isAvailable()) return asContent(tier0Response('brain_query'));
+    const r = await brainClient.query(cypher, params);
+    return asContent(r == null ? tier0Response('brain_query') : r);
+  }
+);
+
+// -- brain_schema: cached 30 min in brain-client; passthrough here.
+server.tool(
+  'brain_schema',
+  'Brain Neo4j schema (labels, relationship types, property keys). Memoized 30 minutes.',
+  {},
+  async () => {
+    if (!brainClient.isAvailable()) return asContent(tier0Response('brain_schema'));
+    const r = await brainClient.schema();
+    return asContent(r == null ? tier0Response('brain_schema') : r);
+  }
+);
+
+// -- brain_search: semantic via Pinecone (smartSearch handles Neo4j fallback).
+server.tool(
+  'brain_search',
+  'Semantic search across the curriculum graph (Pinecone with Neo4j fulltext fallback).',
+  {
+    query: z.string().describe('Search query (generic methodology language -- Canon Part 8).'),
+    namespace: z.string().optional(),
+    topK: z.number().int().min(1).max(50).optional(),
+  },
+  async ({ query, namespace, topK }) => {
+    if (!brainClient.isAvailable()) return asContent(tier0Response('brain_search'));
+    const r = await brainClient.smartSearch(query, { namespace: namespace, topK: topK });
+    return asContent(r == null ? tier0Response('brain_search') : r);
+  }
+);
+
+// -- brain_stats: operational stats passthrough.
+server.tool(
+  'brain_stats',
+  'Brain operational stats (Pinecone index size, last-update markers).',
+  {},
+  async () => {
+    if (!brainClient.isAvailable()) return asContent(tier0Response('brain_stats'));
+    const r = await brainClient.stats();
+    return asContent(r == null ? tier0Response('brain_stats') : r);
+  }
+);
+
+// -- brain_write: admin-tier; not user-surfaced but proxied for parity.
+server.tool(
+  'brain_write',
+  'Write Cypher to the Brain. Admin-tier; requires a write-capable key. Generic methodology framework writes only (Canon Part 8).',
+  { cypher: z.string().describe('Cypher write query (generic methodology only).') },
+  async ({ cypher }) => {
+    if (!brainClient.isAvailable()) return asContent(tier0Response('brain_write'));
+    const r = await brainClient.write(cypher);
+    return asContent(r == null ? tier0Response('brain_write') : r);
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('[mindrian-brain] MCP server v' + version + ' started (stdio)\n');
+}
+
+main().catch((err) => {
+  process.stderr.write('[mindrian-brain] Fatal: ' + (err && err.message ? err.message : String(err)) + '\n');
+  process.exit(1);
+});

package/commands/act.md

@@ -1,6 +1,7 @@
 ---
 name: act
 description: Run Larry's best-pick methodology for your room state
+help_jtbd: "Run the next move Larry recommends, without typing the /mos: command yourself."
 argument-hint: '[--chain] [--swarm] [--dry-run]'
 body_shape: E (Action Report)
 serves_jtbd: ["plan-execution"]

package/commands/admin.md

@@ -1,6 +1,7 @@
 ---
 name: admin
 description: Manage Brain API keys from the admin panel
+help_jtbd: "Inspect plugin internals when you suspect something is off."
 argument-hint: [subcommand]
 body_shape: A (Mondrian Board)
 serves_jtbd: ["audit-room"]

package/commands/analyze-needs.md

@@ -1,6 +1,8 @@
 ---
 name: analyze-needs
 description: Score customer jobs with importance and satisfaction
+help_jtbd: "Surface user needs that change the problem statement."
+body_shape: "methodology"
 serves_jtbd: ["find-problem"]
 teaching: "When you need to know which customer jobs matter most, /mos:analyze-needs scores them by importance versus satisfaction. Best after you have a customer segment defined."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/analyze-systems.md

@@ -1,6 +1,8 @@
 ---
 name: analyze-systems
 description: Decompose a system into layers and leverage points
+help_jtbd: "See how subsystems connect, where they break, where they leverage each other."
+body_shape: "methodology"
 serves_jtbd: ["find-bottleneck"]
 teaching: "When you need to find where leverage lives in a complex system, /mos:analyze-systems decomposes it into layers and surfaces the leverage points. Best when symptoms keep recurring."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/analyze-timing.md

@@ -1,6 +1,8 @@
 ---
 name: analyze-timing
 description: Place a technology on the S-Curve timing clock
+help_jtbd: "Find the timing window your venture sits inside."
+body_shape: "methodology"
 serves_jtbd: ["understand-market"]
 teaching: "When you need to know if your technology is too early, too late, or right on time, /mos:analyze-timing places it on the S-Curve. Best before you commit to a launch window."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/auto-explore.md

@@ -1,5 +1,7 @@
 ---
 description: "Manually trigger auto-explore on a specific file (Desktop fallback when PostToolUse hook does not fire per RESEARCH 4.8)"
+help_jtbd: "Let Larry decompose your domain before you even ask."
+body_shape: "methodology"
 argument-hint: "<file_path>"
 serves_jtbd: ["find-problem", "understand-market", "explore"]
 teaching: "In the moment a new artifact lands, /mos:auto-explore kicks off the same domain decomposition the PostToolUse hook would run. Use it on Desktop when the hook does not fire."

package/commands/beautiful-question.md

@@ -1,6 +1,8 @@
 ---
 name: beautiful-question
 description: Reframe a challenge as Why / What-if / How
+help_jtbd: "Reformulate the problem before solving the wrong one."
+body_shape: "methodology"
 serves_jtbd: ["find-problem", "explore"]
 teaching: "When the framing feels stuck, /mos:beautiful-question reshapes the challenge as Why / What-if / How. The right question unlocks more progress than a better answer."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/brain-derive.md

@@ -1,5 +1,7 @@
 ---
 description: Derive BRAIN.md for section(s) now
+help_jtbd: "Pull the Brain's framework recommendations for your current section."
+body_shape: E
 argument-hint: "[section] [--all] [--cross-room] [--dry-run]"
 serves_jtbd: ["audit-room"]
 teaching: "When a room section drifts from its BRAIN.md derivation, /mos:brain-derive rebuilds the per-section Brain context now. Run after large filings or before a decision gate."

package/commands/build-knowledge.md

@@ -1,6 +1,8 @@
 ---
 name: build-knowledge
 description: Climb Ackoff's DIKW pyramid across the room
+help_jtbd: "Turn your room into a knowledge graph you can query."
+body_shape: "methodology"
 serves_jtbd: ["explore"]
 teaching: "When you have data but not yet wisdom, /mos:build-knowledge climbs Ackoff's DIKW pyramid across the room. Surfaces what you know, what you can decide, and what is still raw."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/build-thesis.md

@@ -1,6 +1,8 @@
 ---
 name: build-thesis
 description: Run the Ten-Questions investment thesis gate
+help_jtbd: "Compose the investment-grade thesis from your room's evidence."
+body_shape: "methodology"
 serves_jtbd: ["decide-pursue", "prepare-pitch"]
 teaching: "When you need to know if this venture is worth pursuing, /mos:build-thesis runs the Ten-Questions investment thesis gate. The output is a defensible go / no-go with reasons."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/causal.md

@@ -1,6 +1,8 @@
 ---
 name: causal
 description: Trace causal edges in the room's graph
+help_jtbd: "Trace cause-and-effect chains across your room's claims."
+body_shape: "methodology"
 argument-hint: [extract|trace|predict]
 serves_jtbd: ["find-problem", "find-bottleneck"]
 teaching: "When you suspect the visible problem is downstream of something else, /mos:causal traces causal edges in the room's graph. Surfaces the upstream causes worth fixing."

package/commands/challenge-assumptions.md

@@ -1,6 +1,8 @@
 ---
 name: challenge-assumptions
 description: Stress-test assumptions with Devil's Advocate
+help_jtbd: "Stress-test the assumptions your room is built on."
+body_shape: "methodology"
 serves_jtbd: ["validate-idea", "surface-contradiction"]
 teaching: "When an idea feels too clean, /mos:challenge-assumptions runs Devil's Advocate against the load-bearing claims. Catches the assumptions you stopped questioning."
 allowed-tools:

package/commands/compare-ventures.md

@@ -1,6 +1,8 @@
 ---
 name: compare-ventures
 description: Compare against ventures that tried this before
+help_jtbd: "Set two or more ventures side-by-side, scored."
+body_shape: "methodology"
 serves_jtbd: ["compare-options"]
 teaching: "When you are weighing your approach against ventures that tried this before, /mos:compare-ventures lines them up on the dimensions that matter. Saves you from re-learning their lessons."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/dashboard.md

@@ -1,7 +1,8 @@
 ---
 name: dashboard
 description: Open the Data Room dashboard (live or snapshot)
-body_shape: raw
+help_jtbd: "Open your room as a browser dashboard, De Stijl grid + graph."
+body_shape: E
 serves_jtbd: ["audit-room", "prepare-pitch"]
 teaching: "When you need to see the whole room at a glance, /mos:dashboard opens the live or snapshot view in De Stijl layout. The fastest way to read room health before a meeting."
 ui_reference: skills/ui-system/SKILL.md

package/commands/deep-grade.md

@@ -1,6 +1,8 @@
 ---
 name: deep-grade
 description: Grade a venture against 100+ calibrated projects
+help_jtbd: "Get the rigorous grading pass (Brain-enriched, 100+ student calibration)."
+body_shape: C
 serves_jtbd: ["audit-room", "compare-options"]
 teaching: "When you need a calibrated grade on the room's quality, /mos:deep-grade scores it against 100+ real student projects. Best after at least three sections are populated."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/diagnose.md

@@ -1,6 +1,8 @@
 ---
 name: diagnose
 description: Classify problem type against the PWS matrix
+help_jtbd: "See where your room is weakest and what to do next."
+body_shape: A
 serves_jtbd: ["decide-pursue"]
 teaching: "When you cannot tell if this is an Ill-Defined or Well-Defined Problem, /mos:diagnose classifies it against the PWS matrix. Knowing the problem type picks the right methodology."
 # --- Phase 122 workflow-layer frontmatter ---
@@ -56,4 +58,22 @@ Move faster than other commands. The user came here because they are stuck on WH
 ## When Complete
 
 Create the artifact using the template from the reference file.
-Offer to route them directly: "Want me to start /mos:[top recommendation] right now?"
+
+## Recommendation (Shape F.1 Next Move per Canon Part 3)
+
+Render the recommendation as a Shape F.1 selector per `skills/ui-system/SKILL.md` Section 2. Do NOT render the recommendation as bare prose -- the F.1 selector IS the Canon Part 3 Decision Gate. Rendering recommendations as prose is the canon violation Cluster 5 audit (2026-05-15) flagged.
+
+```
+[diagnose] -- NEXT MOVE
+LOCAL / BRAIN / SIGNAL
+
+Choose next move:
+
+  1. Run Methodology  -- the specific methodology for the weakest section
+  2. Defer            -- queue for milestone audit
+  3. Free-Text        -- tell Larry what you want
+```
+
+Use AskUserQuestion to surface the selector. The selected verb writes to STATE.md Decisions section AND creates a typed edge in the local graph: `(navigator) -[CHOSE {verb, reason}]-> (current-artifact)`. The 3-verb F.1 vocabulary (Run Methodology / Defer / Free-Text) is the canonical minimum per Canon Part 3; when Brain is reachable and confidence >= 0.7 the "Run Methodology" option may be marked RECOMMENDED (Phase 88.2 invariant).
+
+Phase 121.5-08 Sub-plan J D-12 LOCKED: the recommendation surface on /mos:diagnose MUST render an F.1 selector, not bare prose. Closes the Canon Part 3 violation from the Cluster 5 audit.