@mindrian_os/install 1.13.0-beta.19 → 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.19",
+  "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,8 @@
+## [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)

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/doctor.md

@@ -1,8 +1,8 @@
 ---
 name: doctor
-description: Diagnose and optionally repair MindrianOS install — detects install-cache drift, .room-root sentinel gaps, active-room guard silence, surface-verification gaps, ROOM.md/MINTO.md drift, UI Ruling System compliance, and statusline visibility drift
+description: Diagnose and optionally repair MindrianOS install — detects install-cache drift, .room-root sentinel gaps, active-room guard silence, surface-verification gaps, ROOM.md/MINTO.md drift, UI Ruling System compliance, statusline visibility drift, and Brain end-to-end smoke
 help_jtbd: "Diagnose and optionally repair an off-feeling install."
-argument-hint: "[--fix] [--cascade-rooms] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--install-state] [--stale-first-touch] [--deprecated-usage] [--all] [--acceptance] [--pre-tag] [--light-npx] [--json]"
+argument-hint: "[--fix] [--cascade-rooms] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--all] [--acceptance] [--pre-tag] [--light-npx] [--json]"
 body_shape: E (Action Report)
 body_shape_detail: per-class status rows with [before → after] pattern, summary totals, F.1 Next Move selector when drift detected without --fix
 serves_jtbd: ["audit-room"]
@@ -45,6 +45,7 @@ Look at the user's invocation:
 - `/mos:doctor --statusline-visibility` → class G — checks user-settings drift, plugin install integrity, and statusline-mos isolated execution
 - `/mos:doctor --stale-first-touch` → class K (Phase 121.5-05; SEED-007 absorption) — scans `data/first-touch-surfaces.json`-declared greeting surfaces (banner, splash, onboard, sessionstart, operator-update, larry-extended) for stale version literals (older than the running plugin) and U+2014 em-dash violations on surfaces flagged `em_dash_check: true`
 - `/mos:doctor --deprecated-usage` → class L (Phase 121.5-08 Sub-plan J) — scans last-7-days `~/.claude/projects/.../*.jsonl` session transcripts for `/mos:<deprecated>` patterns (heal/query/organize/hmi-status/visualize/diagnostics) and surfaces a per-command "use `/mos:<new>` instead" hint. Pure LOCAL scan; zero network, zero Brain. Also activated by `--all`.
+- `/mos:doctor --brain-smoke` → class M (Phase 127-02 BRAIN-MCP-127-08): 5-layer Brain end-to-end probe (plugin root resolver, key resolver, HTTPS schema, MCP stdio handshake, e2e brain_schema via the bundled shim). Diagnostic-only; reports the exact failing layer with fail-fast cascade. Detects 12 Phase 126 failure-mode rows in one composable test (the doctor's single Brain smoke).
 - `/mos:doctor --fix` → diagnostic + auto-recovery for any class that supports --fix (class A, B, E, G)
 - `/mos:doctor --json` → machine-readable output (for hooks / regression tests)
 

package/lib/core/directive-envelope.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+/*
+ * Phase 127-00 (Task 1) -- DirectiveEnvelope wrapper module.
+ *
+ * Builds the typed packet returned by `brain_ask` (via the stdio shim) and
+ * consumed by Larry's surface. CANONICAL DEFAULT mode: GUIDED.
+ *
+ * Default: GUIDED per feedback_larry_pedagogical_guided_first.md (HARD RULE).
+ * AUTONOMOUS only on explicit user invitation, non-judgment prep, or explicit
+ * "run" command. Cold start ALWAYS forces GUIDED. Mature-room commit-phase
+ * gates default to HYBRID.
+ *
+ * Canon parts: 2 (Larry pedagogy intrinsic, not Brain-dependent),
+ *   3 (Decision Gate F-shape next_gate handoff), 7 (pure data shaping,
+ *   zero network surface; envelope wrapper sits ABOVE brain-client).
+ *
+ * Constraints: CJS, Node built-ins only, zero new runtime deps, ZERO network
+ * surface (no fetch/http/brain-client require). HARD RULE: no em-dashes.
+ */
+
+const DEFAULT_MODE = 'GUIDED';
+
+/**
+ * Mode classifier. Signal precedence (first match wins; explicit user signals
+ * beat heuristic context):
+ *   1. user_said_just_tell_me | user_said_bottom_line -> AUTONOMOUS
+ *   2. is_first_material | is_cold_start              -> GUIDED (forced)
+ *   3. session_count>=8 + room_mature + in_commit_phase -> HYBRID
+ *   4. is_prep_work && !requires_judgment             -> AUTONOMOUS
+ *   5. user_explicitly_said_run                       -> AUTONOMOUS
+ *   6. default                                        -> GUIDED
+ *
+ * Non-object input is coerced to empty signals (default GUIDED applies).
+ * @param {object} signals
+ * @returns {{mode: string, rationale: string}}
+ */
+function selectMode(signals) {
+  const s = (signals && typeof signals === 'object') ? signals : {};
+
+  // 1. Explicit user invitation (highest precedence).
+  if (s.user_said_just_tell_me || s.user_said_bottom_line) {
+    return { mode: 'AUTONOMOUS', rationale: 'explicit_user_invitation' };
+  }
+
+  // 2. Cold start FORCES GUIDED (per feedback_larry_pedagogical_guided_first.md).
+  if (s.is_first_material || s.is_cold_start) {
+    return { mode: 'GUIDED', rationale: 'cold_start_never_autonomous' };
+  }
+
+  // 3. Mature-room commit-phase: HYBRID for non-trivial methodology run.
+  if (typeof s.session_count === 'number' && s.session_count >= 8
+      && s.room_mature && s.in_commit_phase) {
+    return { mode: 'HYBRID', rationale: 'mature_room_commit_gate' };
+  }
+
+  // 4. Non-judgment prep work.
+  if (s.is_prep_work && !s.requires_judgment) {
+    return { mode: 'AUTONOMOUS', rationale: 'non_judgment_prep_work' };
+  }
+
+  // 5. Explicit execute command.
+  if (s.user_explicitly_said_run) {
+    return { mode: 'AUTONOMOUS', rationale: 'explicit_execute_command' };
+  }
+
+  // 6. Default: GUIDED (Larry pedagogical canon).
+  return { mode: 'GUIDED', rationale: 'default_guided_pedagogical_canon' };
+}
+
+// The 3 documented user-override keys. Frozen template; envelope build
+// shallow-copies so caller mutations do not leak across envelopes.
+const USER_OVERRIDE_TEMPLATE = Object.freeze({
+  'just tell me': 'switch to AUTONOMOUS, run framework end-to-end',
+  'let me think': 'switch to GUIDED, ask the next reframing question',
+  'stop': 'halt, return control',
+});
+
+/**
+ * Build directive body. Pass through Brain-supplied `directive` when present;
+ * otherwise produce a mode-appropriate empty scaffold.
+ * @param {object|null} brainResponse
+ * @param {string} mode
+ * @returns {object}
+ */
+function buildDirective(brainResponse, mode) {
+  // Pass-through if Brain already supplied a typed directive payload.
+  if (brainResponse && typeof brainResponse === 'object'
+      && brainResponse.directive && typeof brainResponse.directive === 'object') {
+    return brainResponse.directive;
+  }
+
+  if (mode === 'AUTONOMOUS') {
+    return { autonomous: { plan: [], framework: null } };
+  }
+  if (mode === 'HYBRID') {
+    return {
+      hybrid: {
+        autonomous_prep: [],
+        guided_commit: { questions: [] },
+        framework: null,
+      },
+    };
+  }
+  // GUIDED default scaffold.
+  return { guided: { questions: [], framework: null, stage: null } };
+}
+
+/**
+ * Build next_gate handoff. Brain-supplied next_gate passes through when its
+ * sub_shape matches F.[1-5]; otherwise defaults to F.1 Next Move (Canon Part 3).
+ * @param {object|null} brainResponse
+ * @returns {{sub_shape: string, options: Array}}
+ */
+function buildNextGate(brainResponse) {
+  if (brainResponse && typeof brainResponse === 'object'
+      && brainResponse.next_gate && typeof brainResponse.next_gate === 'object') {
+    const ng = brainResponse.next_gate;
+    if (typeof ng.sub_shape === 'string' && /^F\.[1-5]$/.test(ng.sub_shape)) {
+      return {
+        sub_shape: ng.sub_shape,
+        options: Array.isArray(ng.options) ? ng.options : [],
+      };
+    }
+  }
+  return { sub_shape: 'F.1', options: [] };
+}
+
+/**
+ * Wrap a Brain response (or null) in a typed DirectiveEnvelope.
+ * brainResponse null/undefined => Tier-0 sentinel (mode GUIDED, rationale
+ * "brain_unreachable", directive.guided.stage "tier_0_brain_unreachable").
+ * Otherwise selectMode applies + directive/next_gate pass through when supplied.
+ * @param {object|null} brainResponse
+ * @param {object} signals
+ * @returns {object} DirectiveEnvelope per CAPABILITY-MAP spec.
+ */
+function wrapDirective(brainResponse, signals) {
+  if (brainResponse === null || brainResponse === undefined) {
+    // Tier-0 sentinel.
+    return {
+      packet_version: '1.0',
+      packet_type: 'DirectiveEnvelope',
+      mode: 'GUIDED',
+      mode_rationale: 'brain_unreachable',
+      directive: {
+        guided: {
+          questions: [],
+          framework: null,
+          stage: 'tier_0_brain_unreachable',
+        },
+      },
+      user_override: Object.assign({}, USER_OVERRIDE_TEMPLATE),
+      next_gate: { sub_shape: 'F.1', options: [] },
+    };
+  }
+
+  const { mode, rationale } = selectMode(signals || {});
+
+  return {
+    packet_version: '1.0',
+    packet_type: 'DirectiveEnvelope',
+    mode: mode,
+    mode_rationale: rationale,
+    directive: buildDirective(brainResponse, mode),
+    user_override: Object.assign({}, USER_OVERRIDE_TEMPLATE),
+    next_gate: buildNextGate(brainResponse),
+  };
+}
+
+module.exports = {
+  DEFAULT_MODE,
+  selectMode,
+  wrapDirective,
+};