@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.19

package/commands/jtbd.md

@@ -1,6 +1,7 @@
 ---
 name: jtbd
 description: Show, set, list, or inspect the active JTBD (job-to-be-done) -- the per-room signal that tells Larry what kind of work the navigator is doing right now
+help_jtbd: "Surface the job-to-be-done you are in right now."
 argument-hint: "[set <jtbd> | clear | list | history] [--json]"
 body_shape: E (Action Report)
 body_shape_detail: current state + last 5 history (default), 13 entries (list), full history (history), Shape F.1 picker (set with no arg), Shape E confirmation (clear, set <jtbd>)

package/commands/leadership.md

@@ -1,6 +1,8 @@
 ---
 name: leadership
 description: Diagnose the leadership shape your team needs
+help_jtbd: "Apply adaptive leadership (Heifetz) to your venture stage."
+body_shape: "methodology"
 serves_jtbd: ["explore"]
 teaching: "When the team feels wrong-shaped for the stage, /mos:leadership diagnoses which leadership pattern you actually need. Different stages of a venture need different leadership shapes."
 allowed-tools:

package/commands/lean-canvas.md

@@ -1,6 +1,8 @@
 ---
 name: lean-canvas
 description: Fill the Lean Canvas in one page (9 boxes)
+help_jtbd: "Lay out the 9-block Lean Canvas for your room."
+body_shape: "methodology"
 serves_jtbd: ["prepare-pitch", "validate-idea"]
 teaching: "When you need the whole business model on one page, /mos:lean-canvas fills the nine boxes from your room data. The fastest way to get a defensible canvas in front of someone."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/macro-trends.md

@@ -1,6 +1,8 @@
 ---
 name: macro-trends
 description: Map macro changes with PEST across a domain
+help_jtbd: "Identify the macro trends shaping your venture's window."
+body_shape: "methodology"
 serves_jtbd: ["understand-market"]
 teaching: "When you need to map the forces shaping a domain, /mos:macro-trends runs PEST across Political, Economic, Social, and Technological dimensions. The wide-angle lens before you zoom in."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/map-unknowns.md

@@ -1,6 +1,8 @@
 ---
 name: map-unknowns
 description: Map known, unknown, and unknowable (Rumsfeld)
+help_jtbd: "Map the unknowns your venture has not yet addressed."
+body_shape: "methodology"
 serves_jtbd: ["validate-idea"]
 teaching: "When you cannot tell what you do not know, /mos:map-unknowns plots known, unknown, and unknowable in a Rumsfeld matrix. The unknowable column is usually where the risk lives."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/memory.md

@@ -1,6 +1,7 @@
 ---
 name: memory
 description: Inspect and operate on the three memory layers (within-session, across-session, cross-room).
+help_jtbd: "Inspect what the Brain remembers about your sessions."
 argument-hint: "[query <jtbd> | cross-room | resume | park <jtbd> | complete <jtbd> | --opt-out]"
 body_shape: E (Action Report)
 body_shape_detail: 4-zone Shape E for default + park + complete + opt-out; Shape G (Comparison Matrix) for query when Phase 101 ships (Shape E fallback otherwise); Shape G Mode A or Shape E Mode B for cross-room depending on Brain availability; Shape F.6 (or F.1 fallback) for resume picker.

package/commands/models.md

@@ -1,6 +1,7 @@
 ---
 name: models
 description: View or switch model-routing profiles
+help_jtbd: "Browse and apply 25 methodology models."
 argument-hint: [list|set|show]
 body_shape: C (Information Card)
 serves_jtbd: ["compare-options"]

package/commands/mos-reason.md

@@ -2,6 +2,8 @@
 name: mos-reason
 command: mos:reason
 description: Generate Feynman-MINTO reasoning for a section
+help_jtbd: "Get Larry's reasoning trace on a specific question."
+body_shape: C
 usage: /mos:reason [--section <name>] [--regenerate-all]
 serves_jtbd: ["explore"]
 teaching: "When a section needs Feynman-MINTO reasoning generated against its artifacts, /mos:mos-reason produces the pyramid: governing thought down to grounded support. Larry's structured thinking surface."

package/commands/mos.md

@@ -0,0 +1,139 @@
+---
+name: mos
+description: State-aware router that picks the right next surface for the navigator
+help_jtbd: "Meet the navigator where they are: onboard, status, or next move."
+body_shape: E
+body_shape_detail: Action Report rendering of the routing decision (zone 2 names the resolved target + reason; zone 4 routes to that target as primary)
+serves_jtbd: ["explore"]
+teaching: "When you do not know which /mos:* surface to invoke, /mos:mos picks the right one. No room: onboard. Mostly empty room: status with a next-move hint. Populated room: suggest-next."
+canon_parts: [3, 7]
+phase: 121.5-08
+ui_reference: skills/ui-system/SKILL.md
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /mos:mos
+
+You are Larry. /mos:mos is the state-aware router. It picks the right next surface for the navigator based on the current room state.
+
+D-10 LOCKED: a single command that meets the navigator where they are. New navigator (no room) goes to onboard. Mostly-empty room goes to status with a next-move hint. Populated room goes to suggest-next.
+
+## Why /mos:mos exists
+
+Per Cluster 5 audit (2026-05-15): /mos:mos was declared in plugin discovery but the backing file was absent. Per D-10, /mos:mos is the canonical "I do not know which /mos:* to invoke -- pick the right one for me" entrypoint. It is the state-aware router that collapses the navigator's mental load.
+
+Per Canon Part 7 (Reuse Before Build): /mos:mos does NOT add a new behavior. It dispatches to /mos:onboard, /mos:status, or /mos:suggest-next. The router replaces the mental cost; the underlying surfaces are unchanged.
+
+## Algorithm (per D-10)
+
+Step 1: resolve room state.
+
+```bash
+# Read STATE.md if present, otherwise treat as no-room.
+if [ -f STATE.md ]; then
+  ROOM_STATE_EXISTS=true
+  STAGE=$(grep -E '^stage:' STATE.md | head -1 | sed 's/^stage:\s*//')
+  SECTIONS_COUNT=$(ls -d */ 2>/dev/null | grep -v node_modules | wc -l)
+else
+  ROOM_STATE_EXISTS=false
+  STAGE=""
+  SECTIONS_COUNT=0
+fi
+```
+
+Then call the pure-function router:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/lib/core/state-aware-router.cjs" <<EOF
+# Not invokable as a CLI; require the module from a Node script or:
+node -e "
+  const r = require('${CLAUDE_PLUGIN_ROOT}/lib/core/state-aware-router.cjs');
+  const out = r.resolveNextSurface({
+    roomState: {
+      exists: ${ROOM_STATE_EXISTS},
+      sectionsCount: ${SECTIONS_COUNT},
+      stage: '${STAGE}',
+    },
+  });
+  console.log(JSON.stringify(out));
+"
+EOF
+```
+
+The router returns `{route, reason, addendum}`:
+
+- `no_room` -> route is `/mos:onboard`. The navigator gets onboarded.
+- `mostly_empty` -> route is `/mos:status`, addendum is `suggest next move`. Show the room state, then suggest the next move.
+- `populated` -> route is `/mos:suggest-next`. Surface the next-move recommendation directly.
+
+Step 2: emit a single Action Report envelope (Shape E per skills/ui-system/SKILL.md Section 1):
+
+```
+-- MindrianOS -- mos -- routing --
+
+  Routing to: <route> (<reason>)
+  <addendum line, if any>
+
+  -> <route>                 # the resolved next surface
+```
+
+The header names the room (or "MindrianOS / no room" when none exists). Zone 2 names the resolved route + the reason from the router. Zone 4 surfaces the route as the primary action.
+
+Step 3: invoke the target command's behavior. Do NOT echo the routing decision and then ask the user to type the target command -- the routing IS the response. Larry continues with the target command's content directly in the same turn.
+
+## Examples
+
+### Case 1: navigator has no room
+
+```
+-- MindrianOS -- mos -- no-room --
+
+  Routing to: /mos:onboard (no_room)
+
+  -> /mos:onboard           # walkthrough + first room
+```
+
+Then Larry continues with /mos:onboard Step 1 in the same turn.
+
+### Case 2: room exists but is mostly empty
+
+```
+-- acme-robotics -- mos -- mostly-empty --
+
+  Routing to: /mos:status (mostly_empty)
+  suggest next move
+
+  -> /mos:status            # current room state
+```
+
+Then Larry continues with /mos:status output + a Shape F.1 Next Move selector (per Canon Part 3) inviting the navigator's next verb.
+
+### Case 3: room populated
+
+```
+-- acme-robotics -- mos -- populated --
+
+  Routing to: /mos:suggest-next (populated)
+
+  -> /mos:suggest-next      # the next-move recommendation
+```
+
+Then Larry continues with /mos:suggest-next output.
+
+## Cross-references
+
+- `lib/core/state-aware-router.cjs` -- the pure-function router (zero side-effects, unit-tested).
+- `commands/onboard.md` -- the no-room branch destination.
+- `commands/status.md` -- the mostly-empty branch destination.
+- `commands/suggest-next.md` -- the populated branch destination.
+- Canon Part 3 -- the Decision Gate that the target commands' F.1 selectors honor.
+- Canon Part 7 -- reuse-before-build: /mos:mos delegates, does not duplicate.
+
+## Voice rules
+
+- Terse, structural, confident. No filler. No em-dashes.
+- The routing decision IS the response. Never ask the user "shall I run X?" -- just run X.
+- Symbol vocabulary: only the 12 approved glyphs from skills/ui-system/SKILL.md.
+- Error pattern (only if the router throws or STATE.md is unreadable): 3 lines -- What / Why: reason / Fix: /mos:command.

package/commands/mullins.md

@@ -1,6 +1,8 @@
 ---
 name: mullins
 description: Run Mullins 7-Domains on a business opportunity
+help_jtbd: "Run the Mullins 7-domains evaluation."
+body_shape: "methodology"
 serves_jtbd: ["understand-market"]
 teaching: "When you need the most rigorous opportunity screen ever published, /mos:mullins runs the 7-Domains Model from Mullins' New Business Road Test. Best before you commit real resources."
 # --- Phase 122 workflow-layer frontmatter ---

package/commands/mva-brief.md

@@ -0,0 +1,58 @@
+---
+name: mva-brief
+description: Run the 30-second MVA pipeline for the user's current venture sentence
+help_jtbd: "Build a Minimum Viable Argument brief from your room."
+body_shape: E
+argument-hint: (no args -- reads pending state from UserPromptSubmit detection)
+serves_jtbd: ["explore"]
+teaching: "When you have just typed a venture sentence and want a brief in under a minute, /mos:mva-brief runs the 6-agent fan-out and deploys a shareable deck. The reward-before-investment surface of Phase 118."
+allowed-tools: Bash
+interactive_first_reward: instant_brief
+---
+
+# /mos:mva-brief
+
+Run the 30-second MVA pipeline against the pending venture sentence detected by
+the UserPromptSubmit hook (Plan 118-00).
+
+## What this does
+
+1. Reads pending state from `~/.mindrian/mva/<session-id>.json` (written by
+   Plan 118-00 detection hook).
+2. Fires 6 parallel agents (Brain similar + Brain cross-domain + Brain classic
+   traps + Tavily funding + Six-hats red/black + Dashboard graph) under the
+   45-second hard budget.
+3. Streams agent results as they return -- each one rendered in Larry's
+   GUIDED voice (per feedback_larry_pedagogical_guided_first.md).
+4. Closes with the 3-option footer:
+   - [1] Just tell me what's new (stay in "tell me" mode)
+   - [2] Build a room around this (invest)
+   - [3] Challenge me -- Devil's Advocate (go deeper cognitively)
+
+## Instructions for the model
+
+Invoke `node scripts/mva-run.cjs` via Bash with no arguments. The script reads
+the pending state file, runs the orchestrator, and writes the rendered output
+to stdout.
+
+Relay the stdout to the user VERBATIM. Do NOT:
+
+- Add commentary or interpretation before the rendered output
+- Re-summarize the agent findings ("So basically what this means is...")
+- Skip the 3-option footer
+- Autonomously pick option 1, 2, or 3 for the user
+- Add Larry-voice framing ("Here's what I found for you...") -- the renderer
+  already speaks in Larry's voice; double-voicing breaks the GUIDED tone
+
+The 3-option footer IS the user's decision point. Wait for the user to type
+1, 2, or 3 (or their own free-text), then route per the option behavior:
+
+- 1: stay in JUST_TALK mode; keep brief in scrollback; user can ask follow-ups
+- 2: invoke /mos:new-project (stub for v1.13.0; Phase 119 wires fully)
+- 3: invoke /mos:challenge-assumptions against the brief
+
+## Canon parts implemented
+
+- Part 2 (team around navigator -- 6 agents as a parallel team)
+- Part 8 (boundary -- agents send only generic handles to Brain / Tavily)
+- Part 10 sub-claim 3 (room as receipt -- the brief IS the reward)

package/commands/mva-option.md

@@ -0,0 +1,91 @@
+---
+name: mva-option
+description: Route the user's 3-option footer selection after a 30-second MVA brief
+help_jtbd: "Compose option packages for your MVA."
+body_shape: E
+argument-hint: <1|2|3> [<sha8>]
+serves_jtbd: ["explore"]
+teaching: "When the 3-option footer shows after an MVA brief, /mos:mva-option routes your pick (refine / build a room / iterate) into the right next move. The hand-off after the first reward."
+allowed-tools: Bash
+interactive_first_reward: --none (scripting only)
+---
+
+# /mos:mva-option <N> [<sha8>]
+
+Route the user's selection from the 3-option footer that appears after a 30-second MVA brief.
+
+## Why this exists
+
+The 3-option footer renders after every MVA brief (per binding decision B4):
+
+```
+What now?
+  [1] Just tell me what's new         (stay in "tell me" mode)
+  [2] Build a room around this        (invest)
+  [3] Challenge me -- Devil's Advocate (go deeper cognitively)
+```
+
+The user types `1`, `2`, or `3` (or `/mos:mva-option N` directly). This command dispatches the routing.
+
+## Arguments
+
+- `<N>` (required): `1`, `2`, or `3` -- the user's selection
+- `[<sha8>]` (optional): the 8-char prefix identifying the target brief. When OMITTED, the command auto-discovers the most recent brief by calling `resolveCurrentSha8()` which reads `~/.mindrian/mva/state.json` (the manifest atomically written by Plan 118-03's orchestrator after `mva_brief_rendered` fires).
+
+## How to invoke
+
+The model invokes this command via Bash + Node. Two patterns:
+
+**With explicit sha8:**
+
+```bash
+node -e "const r=require('./lib/core/mva-option-router.cjs'); r.routeOption(N, '<sha8>').then(out => console.log(JSON.stringify(out, null, 2)))"
+```
+
+**Without sha8 (auto-resolve via state.json):**
+
+```bash
+node -e "const r=require('./lib/core/mva-option-router.cjs'); const sha=r.resolveCurrentSha8(); if(!sha){console.log(JSON.stringify({ok:false,error:'no_current_brief',message:'No recent brief found. Type your venture sentence to fire the pipeline.'}));process.exit(0);} r.routeOption(N, sha).then(out => console.log(JSON.stringify(out, null, 2)))"
+```
+
+The auto-resolve form is what the `mva-pipeline` skill instructs the model to run when the user types `1`, `2`, or `3` as a plain message immediately after a brief renders. See the "## Routing the 3-option footer" section in `skills/mva-pipeline/SKILL.md` for the full recognition rule.
+
+## What happens per option
+
+- **Option 1** -- operator transitions to `JUST_TALK`; the brief stays in scrollback; the user can ask any follow-up about the 6 cells. The router returns `{ action: 'stay_in_just_talk', next_state: 'JUST_TALK', message: ... }`.
+
+- **Option 2** -- operator unchanged; the router returns `{ action: 'phase_119_stub', next_state: null, message: STUB_MESSAGE_119 }`. The stub message reads:
+
+  > Building a room around this is the next layer; shipping in beta.18 (Phase 119). For now, press option 1 to keep this brief visible, or option 3 to go deeper.
+
+  Per binding decision B6 OPTION A, option 2 is deferred to Phase 119 / v1.13.0-beta.18. The router does NOT invoke `/mos:new-project` in v1.13.0.
+
+- **Option 3** -- operator transitions to `METHODOLOGY`; the router returns `{ action: 'invoke_challenge_assumptions', next_state: 'METHODOLOGY', invoke_command: '/mos:challenge-assumptions --from-brief <sha8>' }`. The model then runs the named slash command against the brief.
+
+## Edge cases
+
+| Situation | Router return | Model surfaces |
+| --------- | ------------- | -------------- |
+| No `state.json` (fresh install / Hebrew refusal) | wrapper short-circuits | "No recent brief found. Type your venture sentence to fire the pipeline." |
+| Side-file `<sha8>.json` missing (brief expired) | `{ ok:false, error:'brief_not_found' }` | "The brief data has expired or was not deployed. Type your sentence again to re-fire the pipeline." |
+| `mva_brief_rendered` event not yet logged (pipeline still streaming) | `{ ok:false, error:'brief_still_rendering' }` | "Brief is still rendering -- options will activate when it completes." |
+| Invalid `N` (0, 4, 99, "1", null) | `{ ok:false, error:'invalid_option' }` | Treat as free-text; route through normal Larry conversation. |
+
+## Telemetry
+
+Each successful invocation emits `mva_option_selected` to `~/.mindrian/telemetry/v1.13/mva.jsonl` with the frozen `ALLOWED_FIELDS` schema:
+
+```
+{ sentence_sha256, option_id, time_to_click_ms }
+```
+
+`time_to_click_ms` is computed from the most recent `mva_brief_rendered` event timestamp for the brief's `sentence_sha256`. Plan 118-06's Dror 2.0 harness reads these events to validate "subject types one sentence and clicks an option within 60 seconds of brief rendering."
+
+Per Canon Part 8: the telemetry payload carries ONLY the sha256 hash + option_id + time delta. Zero user content. Zero URLs.
+
+## Canon parts implemented
+
+- Part 3 (Tri-Context Decision Gate) -- the 3-option footer IS a Decision Gate offering a closed-vocabulary choice (verbs 7 Synthesize / 8 Bank Opportunity / 5 Devil's Advocate)
+- Part 4 (Every Choice Is Graph Data) -- `mva_option_selected` telemetry captures every click; operator transitions write `OPERATOR_TRANSITION` edges to the local room graph (Phase 99 substrate)
+- Part 8 (Graph Boundary) -- zero user content in telemetry; zero raw_sentence reads from the side-file; the router source passes the forbidden-token sweep
+- Part 10 sub-claim 3 (room as receipt) -- the 3-option footer is the user's self-selected commitment level immediately after the reward (the brief itself)

package/commands/new-project.md

@@ -1,9 +1,13 @@
 ---
 name: new-project
 description: Start a new venture project and create its room
+help_jtbd: "Start a new room in ~/MindrianRooms/ from a conversation."
+body_shape: E
 argument-hint: [name]
 serves_jtbd: ["explore"]
 teaching: "When you are starting a new venture, /mos:new-project creates the room scaffolding and registers it in the room registry. The first move of every Mindrian journey."
+# Per docs/reward-before-investment-rule.md line 56-58 remediation: first sentence -> Instant Brief pipeline (this phase's deliverable). Room creation is option 2 of the 3-option footer (Phase 119 wires fully in beta.18).
+interactive_first_reward: instant_brief
 allowed-tools:
   - Read
   - Write

package/commands/onboard.md

@@ -1,10 +1,13 @@
 ---
 name: onboard
 description: Walk through MindrianOS and build your first room
+help_jtbd: "Walk through the first 15 minutes with Larry."
 body_shape: B (Semantic Tree)
 body_shape_detail: Steps as conversational flow, context building as nested nodes
 serves_jtbd: ["explore"]
 teaching: "When you just installed MindrianOS, /mos:onboard walks you through the system and builds your first room. Designed so a stranger can self-activate without Larry holding their hand."
+# Per docs/reward-before-investment-rule.md line 68-70: first screen is a question, not a tutorial. Remediation tracked as follow-up phase.
+interactive_first_reward: reframe_question
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read
@@ -65,6 +68,8 @@ If this command was triggered manually (not from session-start), show the banner
 bash "${CLAUDE_PLUGIN_ROOT}/scripts/banner"
 ```
 
+The banner output now leads with the explicit version stamp `MindrianOS v<version>` (Phase 121.5-05 Sub-plan F / SEED-007 absorption). If you echo a welcome line in the conversation prose, prefix it with the version stamp returned by `node ${CLAUDE_PLUGIN_ROOT}/lib/core/first-touch-version-stamper.cjs onboard` (long form: `Welcome to MindrianOS v<version>. Let me show you around.`). The user must be able to answer "what version am I running?" by reading the terminal -- no command-line introspection required.
+
 Then proceed to Step 1.
 
 ## Step 1: The Three Ways to Work
@@ -340,16 +345,26 @@ After listing, offer:
 
 If the user came from `/mos:onboard whats-new`: offer the full walkthrough or drop to prompt, then STOP.
 
-## Step 6: Wrap + Suggested First Action
+## Step 6: Wrap + Suggested First Action (Shape F.1 Next Move per Canon Part 3)
+
+Based on everything gathered across Steps 1-5, surface the recommendation as a Shape F.1 Next Move 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.
 
-Based on everything gathered across Steps 1-5, suggest a specific first action:
+Render the recommendation as an F.1 selector:
+
+```
+[CONTEXT] -- onboard -- NEXT MOVE
+LOCAL / BRAIN / SIGNAL
+
+Choose next move:
+
+  1. Run Methodology  -- the specific recommendation (e.g. /mos:beautiful-question)
+  2. Defer            -- look around first; come back when ready
+  3. Free-Text        -- tell Larry what you want
+```
 
-> That is the foundation. Based on what you need, the best starting point is [specific natural language action]. Want to launch that now?
+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; if Brain is reachable and confidence >= 0.7 a "Run Methodology" option may be marked RECOMMENDED (Phase 88.2 invariant).
 
-Present three options:
-1. Start the suggested action (describe it in natural language)
-2. Show the full command reference (`/mos:help`)
-3. Drop to the prompt -- just start talking
+Phase 121.5-08 Sub-plan J D-12 LOCKED: the recommendation surface on /mos:onboard Step 6 MUST render an F.1 selector, not bare prose. Closes the Canon Part 3 violation from the Cluster 5 audit.
 
 Only in this final step, show a compact command reference card:
 

package/commands/operator.md

@@ -1,6 +1,7 @@
 ---
 name: operator
 description: Show or manually set the conversation operator (JUST_TALK / EXPLORE_CAPTURE / BUILD_ROOM / METHODOLOGY / DECISION_GATE) -- the per-room state machine that governs how Larry renders responses
+help_jtbd: "See or change the conversation operator state."
 argument-hint: "[history] [set <op>] [reset] [--json]"
 body_shape: E (Action Report)
 body_shape_detail: current state + last 5 history (default), full history (history subcommand), Shape F.1 picker (set subcommand), Shape F.4 confirmation (reset subcommand)

package/commands/opportunities.md

@@ -1,6 +1,7 @@
 ---
 name: opportunities
 description: Discover and manage grants in the Opportunity Bank
+help_jtbd: "Browse banked opportunities by HSI score."
 argument-hint: [list|add|scan]
 body_shape: E (Action Report)
 serves_jtbd: ["explore"]