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

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

@@ -1,6 +1,8 @@
 ---
 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."

package/commands/mva-option.md

@@ -1,6 +1,8 @@
 ---
 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."

package/commands/new-project.md

@@ -1,6 +1,8 @@
 ---
 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."

package/commands/onboard.md

@@ -1,6 +1,7 @@
 ---
 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"]
@@ -67,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
@@ -342,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"]