@mindrian_os/install 1.13.0-beta.11

package/references/research/RESEARCH_17_MCP_UI_FRAMEWORKS.md

@@ -0,0 +1,272 @@
+# RESEARCH_17: MCP UI Frameworks -- Solving the Filesystem Invisibility Problem
+
+**Date:** 2026-04-06
+**Source:** Community research, MCP Apps spec, open-source ecosystem scan
+**Purpose:** Map available UI frameworks to MindrianOS UX friction points identified in RESEARCH_16 and the 2026-04-05 Lawrence/Leah user session
+**Depends on:** RESEARCH_16 (Native-First Architecture), user-research/2026-04-05-leah-lawrence-session.md
+
+---
+
+## 1. The Problem This Solves
+
+User session finding (2026-04-05):
+> "I was stressing me out, the file structure, because I didn't understand it." -- Lawrence Aronhime
+
+Design principle from session analysis:
+> "The folder structure must be invisible to the user while remaining the source of truth for the system."
+
+Current MindrianOS exports (dashboard, wiki, deck, graph) are generated as static HTML files that open in a browser. They work but require:
+1. User to know the `/mos:export` or `/mos:visualize` command exists
+2. A separate browser window
+3. No interactivity (static snapshots)
+4. No inline chat integration
+
+MCP Apps solve this by rendering interactive UI INSIDE the chat interface -- Claude Desktop, Cowork, or any MCP-compatible client.
+
+---
+
+## 2. Available Frameworks
+
+### Tier 1: Core Standards
+
+#### `@modelcontextprotocol/ext-apps` -- Official SDK
+- **Source:** github.com/modelcontextprotocol/ext-apps
+- **What it does:** Official Anthropic/MCP team SDK. Provides `registerAppTool`, `registerAppResource`, `useApp`/`useWidget` React hooks.
+- **Working examples:** pdf-server, system-monitor-server, map-server, shader-toy
+- **Transport:** Renders as iframes in Claude Desktop/Cowork chat
+- **Why it matters:** This is THE official path. Building on this guarantees compatibility with Claude's roadmap.
+
+#### `mcp-ui` -- Community Standard
+- **Source:** github.com/MCP-UI-Org/mcp-ui | mcpui.dev
+- **What it does:** Community project that PRECEDED and directly influenced the official spec.
+  - `@mcp-ui/server` -- `createUIResource()` helper to register UI bundles
+  - `@mcp-ui/client` -- `AppRenderer`/`UIResourceRenderer` React components
+- **Relationship:** Designed to work alongside `@modelcontextprotocol/ext-apps`
+- **Why it matters:** Community battle-tested patterns. Higher-level abstractions than the official SDK.
+
+### Tier 2: Accelerators
+
+#### `mcp-generative-ui` -- Auto-UI Wrapper
+- **Source:** github.com/vivekhaldar/mcp-generative-ui
+- **What it does:** Wraps ANY existing plain MCP server and automatically generates interactive UIs for tool results. Turns raw JSON into charts, tables, visual components.
+- **Key insight:** No manual UI coding needed. Could wrap MindrianOS MCP server immediately.
+- **Why it matters for MindrianOS:** Our MCP server already returns structured JSON (room state, section entries, grant results). This could generate visual cards from existing output WITHOUT rewriting the MCP server.
+
+#### Flowbite MCP UI Starter
+- **Source:** github.com/themesberg/mcp-ui-starter
+- **What it does:** Production-ready React + Tailwind starter with pre-built widgets (charts, tables, forms). Supports Claude, ChatGPT, and Gemini.
+- **Why it matters:** Fastest path to a polished widget library. De Stijl design tokens could be applied on top of Tailwind.
+
+### Tier 3: Reference Implementations
+
+#### MCP Memory Service React Dashboard
+- **Source:** github.com/doobidoo/mcp-memory-service
+- **What it does:** Working example of React + shadcn/ui + Tailwind dashboard wired to MCP via `window.mcpTools`. Stats cards, tabs, debounced queries, TypeScript types.
+- **Why it matters:** Closest architectural pattern to what MindrianOS needs (dashboard with sections, entry counts, intelligence signals).
+
+#### MCP Manager
+- **Source:** github.com/marcusglee11/mcp-manager
+- **What it does:** Full-stack: React frontend + FastAPI REST API + Python CLI. Manages MCP server installations, health monitoring, real-time status.
+- **Why it matters:** Shows the local web server pattern for complex admin UIs.
+
+#### Dynamic MCP UI Generator (POC)
+- **Source:** github.com/iamadi11/mcp-ui-poc
+- **What it does:** POC with React + Vite client + Express + MCP server. Dynamic form builder, dashboard creation, chart generation.
+- **Why it matters:** Shows the full client/server split architecture.
+
+### Tier 4: Plugin Infrastructure
+
+#### Claude Code Plugin Template
+- **Source:** github.com/ivan-magda/claude-code-plugin-template
+- **What it does:** GitHub template with plugin.json, hooks, skills, agents, slash commands, CI/CD.
+- **Relevance:** Reference for plugin structure, not UI.
+
+#### Desktop Extensions (.mcpb)
+- **Source:** anthropic.com/engineering/desktop-extensions
+- **What it does:** One-click install packages with manifest.json for Claude Desktop.
+- **Why it matters:** Distribution format for MindrianOS Desktop version.
+
+---
+
+## 3. Mapping UI to MindrianOS UX Problems
+
+### Problem -> Solution Matrix
+
+| User Session Problem | Current Solution | MCP UI Solution | Framework |
+|---|---|---|---|
+| "I don't know where my rooms are" | User navigates Finder, finds room/ folder | **Project Selector Widget** -- inline card showing all rooms with switch button | ext-apps + mcp-ui |
+| "What are these slash commands?" | User reads /mos:help output, copy-pastes | **Action Cards** -- clickable buttons rendered in chat: "Build Business Model", "Grade Your Progress" | ext-apps registerAppTool |
+| "How much longer?" (chain running) | No progress indicator | **Progress Widget** -- inline progress bar: "Step 3/6: Research | ~4 min remaining" | mcp-ui createUIResource |
+| "When I see 89%, what do I do?" | Skull icon in status bar | **Context Health Widget** -- visual meter with plain language: "Your session is 89% full. I'll summarize and keep working." | ext-apps useWidget |
+| "The tabs don't display properly" (export) | Static HTML snapshot with broken tabs | **Interactive Dashboard Widget** -- live room dashboard rendered inline with working tabs | mcp-ui AppRenderer |
+| "I was stressing about file structure" | Larry explains room/ directories | **Project Overview Card** -- visual card: "Blueprint Phase: 7 entries across 5 areas. Biggest gap: Business Model" | mcp-generative-ui (auto from existing JSON) |
+| "Every time I have to ask how to start" | User types `claude` in terminal | **Desktop Extension** -- one-click app icon, no terminal needed | .mcpb Desktop Extension |
+| Filing confirmation unclear | "artifact filed to room/market-analysis/" | **Filing Card** -- visual card: "Saved to Market Research [icon] | Your project now has 3 market analyses" | ext-apps |
+| Grant discovery results | Text list of grants | **Grant Discovery Widget** -- table with relevance scores, deadlines, apply buttons | Flowbite MCP UI Starter |
+| Chain modification mid-run | User types "add research to this chain" | **Chain Builder Widget** -- visual pipeline editor showing framework sequence with drag-reorder | ext-apps + custom |
+
+### The Three Surfaces Revisited
+
+| Surface | Current UI | With MCP Apps |
+|---|---|---|
+| **CLI** | Terminal text only. Slash commands. ASCII formatting. | Terminal text + **localhost dashboard** (existing pattern, enhanced) |
+| **Desktop** | Conversational only. No visual widgets. | Conversational + **inline widgets** (project cards, progress bars, filing confirmations) |
+| **Cowork** | Shared state via 00_Context/. Text only. | Shared state + **collaborative widgets** (team can see same project dashboard, grant table) |
+
+---
+
+## 4. Implementation Strategy
+
+### Phase 1: Quick Win -- mcp-generative-ui Wrapper (1-2 days)
+
+Wrap the existing MindrianOS MCP server with `mcp-generative-ui`. This auto-generates visual cards from our existing JSON output with ZERO changes to the MCP server.
+
+**What changes:** Tool results that currently return text/JSON render as visual components.
+**What doesn't change:** MCP server code, skill files, hook scripts.
+**Risk:** Low. Wrapper sits between server and client. If it breaks, remove it.
+
+**Immediate wins:**
+- Room status becomes a visual dashboard card instead of ASCII art
+- Grant results become a table with scores instead of text list
+- Section entry counts become a visual bar chart
+
+### Phase 2: Core Widgets -- ext-apps + mcp-ui (1-2 weeks)
+
+Build 5 custom widgets using the official SDK:
+
+1. **Project Selector** -- shows all rooms, switch with one click
+2. **Progress Tracker** -- chain/swarm progress with time estimates
+3. **Filing Confirmation** -- visual card when artifacts are saved
+4. **Action Suggester** -- clickable methodology buttons instead of /mos: commands
+5. **Context Health** -- visual meter replacing skull icon
+
+**Architecture:**
+```
+mindrian-mcp-server.cjs (existing)
+  ├── lib/mcp/tool-router.cjs (existing, unchanged)
+  ├── lib/mcp/resources.cjs (existing, unchanged)
+  ├── lib/mcp/prompts.cjs (existing, unchanged)
+  └── lib/mcp/widgets/          (NEW)
+      ├── project-selector.tsx
+      ├── progress-tracker.tsx
+      ├── filing-card.tsx
+      ├── action-suggester.tsx
+      └── context-health.tsx
+```
+
+**Key decision:** Widgets render in Desktop/Cowork via iframe. CLI users get the existing terminal output. Same MCP server, dual rendering.
+
+### Phase 3: Interactive Dashboard -- Full React App (2-4 weeks)
+
+Replace the static HTML snapshot with a live interactive dashboard:
+- Built with React + shadcn/ui + Tailwind (following MCP Memory Service pattern)
+- De Stijl design tokens applied via Tailwind config
+- Connected to MCP server via `window.mcpTools` pattern
+- Renders inline in Desktop/Cowork, localhost in CLI
+
+**This replaces:**
+- /mos:visualize (static HTML)
+- /mos:export dashboard (static HTML)
+- /mos:room (terminal output)
+- The need for users to EVER open Finder
+
+### Phase 4: Desktop Extension Package (1 week)
+
+Package MindrianOS as a `.mcpb` Desktop Extension:
+- One-click install from Anthropic marketplace
+- No terminal, no `claude` command, no PATH issues
+- User opens Claude Desktop, MindrianOS is there
+- Leah's "every time I have to ask how to start" problem: gone
+
+---
+
+## 5. The Native-First + MCP UI Architecture
+
+From RESEARCH_16:
+> Skills should encode WHAT to think, not HOW to use tools.
+
+From this research:
+> UI should show WHAT the user has, not WHERE it's stored.
+
+Combined principle:
+> **Skills teach Larry domain knowledge. MCP Apps show users their project. The filesystem is invisible to both.**
+
+### Token Impact
+
+MCP App widgets are rendered CLIENT-SIDE. They don't consume context tokens. A project selector card costs 0 tokens to display -- it's an iframe rendered by Claude Desktop from the MCP resource.
+
+This means the MCP UI approach is ADDITIVE to the Native-First token savings:
+- Native-First saves ~10,000 tokens per turn (skill compression)
+- MCP UI saves ~0 additional tokens (widgets are client-side)
+- But MCP UI REMOVES the need for verbose text descriptions of room state
+
+Currently, session-start injects ~1,750 tokens of room state as text. With an inline widget, that text could be replaced by a visual card + a 200-token summary. Potential additional savings: ~1,500 tokens per turn.
+
+### The Full v1.8.0 Stack
+
+```
+Layer 0: Skills (Native-First, ~11K tokens)
+  - Larry personality (WHAT to think)
+  - Proactive patterns (WHAT to detect)  
+  - Methodology routing (WHAT frameworks exist)
+  
+Layer 1: MCP Server (existing, enhanced)
+  - 6 hierarchical router tools (existing)
+  - Resources (existing)
+  - Prompts (existing)
+  - Widgets (NEW -- 5 core widgets)
+
+Layer 2: MCP UI (NEW)
+  - mcp-generative-ui wrapper (Phase 1)
+  - Custom ext-apps widgets (Phase 2)
+  - Interactive dashboard (Phase 3)
+  - Desktop Extension package (Phase 4)
+
+Layer 3: Filesystem (INVISIBLE to user)
+  - room/ structure (unchanged)
+  - STATE.md (unchanged)
+  - Hooks pipeline (unchanged)
+  - Everything works exactly as before
+  - User never sees it
+```
+
+---
+
+## 6. Risk Assessment
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| MCP Apps spec changes | MEDIUM | Build on official ext-apps SDK, not community forks |
+| Desktop-only (CLI users get nothing) | HIGH | CLI keeps existing terminal output. Widgets are ADDITIVE for Desktop/Cowork. |
+| Widget maintenance burden | MEDIUM | Start with mcp-generative-ui (zero custom code), graduate to custom only for high-value widgets |
+| De Stijl branding in widgets | LOW | Tailwind config with De Stijl tokens. Same approach as existing dashboard. |
+| TypeScript build step | MEDIUM | Widgets are separate from plugin core (markdown + CJS). Build step only for widgets. |
+
+---
+
+## 7. Quick Pick for MindrianOS
+
+| Goal | Use This | Timeline |
+|---|---|---|
+| Immediate visual upgrade (no coding) | `mcp-generative-ui` wrapper | 1-2 days |
+| Custom inline widgets for Desktop | `@modelcontextprotocol/ext-apps` | 1-2 weeks |
+| Full interactive dashboard | React + shadcn/ui + Tailwind (MCP Memory Service pattern) | 2-4 weeks |
+| One-click Desktop install | `.mcpb` Desktop Extension | 1 week |
+| Production widget library (Tailwind) | Flowbite MCP UI Starter | Reference only |
+
+---
+
+## 8. Connection to Existing Research
+
+- **RESEARCH_14** (Source Architecture): MCP Apps work within Claude's native tool system. `tengu_harbor` MCP allowlist must include widget servers.
+- **RESEARCH_15** (JTBD Optimization): Student archetype benefits most from visual widgets (no terminal literacy required). Venturist benefits from grant table widget. Researcher benefits from cross-domain visualization.
+- **RESEARCH_16** (Native-First): MCP UI is the visual complement to Native-First skills. Skills encode knowledge (tokens). Widgets encode presentation (zero tokens).
+- **User Session** (2026-04-05): Every friction point has a widget solution. See Section 3 mapping.
+
+---
+
+*Cross-references:*
+- *RESEARCH_14_CLAUDE_CODE_SOURCE_ARCHITECTURE.md*
+- *RESEARCH_15_V1.8_OPTIMIZATION_JTBD.md*
+- *RESEARCH_16_NATIVE_FIRST_PLUGIN_ARCHITECTURE.md*
+- *references/user-research/2026-04-05-leah-lawrence-session.md*

package/references/taxonomy/TAXONOMY.md

@@ -0,0 +1,192 @@
+---
+name: MindrianOS Taxonomy
+version: 1.0.0
+updated: 2026-03-31
+status: living-document
+rule: EVERY command, skill, agent, script, and Larry response MUST use these terms. No synonyms. No freestyle naming.
+---
+
+# MindrianOS Taxonomy -- The Definitive Naming System
+
+> This is a LIVING DOCUMENT. Updated whenever new concepts are added. Every piece of MindrianOS -- code, docs, Larry's voice, onboarding, error messages -- uses these exact terms. No exceptions.
+
+## Why This Exists
+
+Users, Larry, code, and docs must speak the same language. "Room" always means Room. "Entry" always means Entry. "Spark" always means Spark. Consistency builds trust. Inconsistency builds confusion.
+
+**Rule:** If a term isn't in this taxonomy, it doesn't exist in MindrianOS. Add it here first, then use it everywhere.
+
+---
+
+## The Space
+
+| Term | What It Is | Where It Lives | Icon |
+|------|-----------|----------------|------|
+| **MindrianOS** | The operating system for structured thinking | Plugin root | -- |
+| **Room** | A self-contained knowledge space for one project. The fundamental unit. | `room/` or `rooms/{name}/` | -- |
+| **Registry** | Tracks all rooms: which is active, git state, deploy URL | `.rooms/registry.json` | -- |
+
+## Inside a Room
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Section** | A domain of knowledge (problem, market, solution, team...). Like a wing of a building. | `room/{section}/` |
+| **Entry** | Any markdown knowledge artifact filed in a section. The standard unit of captured knowledge. | `room/{section}/{name}.md` |
+| **Asset** | A binary file -- PDF, image, video, audio -- with a markdown wrapper for frontmatter. | `room/assets/{section}/` |
+| **Manifest** | Auto-generated index of all assets with metadata. | `room/ASSET_MANIFEST.md` |
+| **Blueprint** | Section descriptor: what this section is for, starter questions, default methodologies. | `room/{section}/ROOM.md` |
+
+## Micro-Knowledge
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Spark** | The smallest unit of knowledge. One thought, one link, one quote, one pushback. Zero-friction capture. | `room/.sparks/{date}.md` |
+| **Catch** | The act of capturing a spark. Larry auto-detects or user says "catch that." | Passive (Larry) or active (user) |
+| **Ember** | 3+ sparks converging on the same theme. Larry detects and surfaces. | KuzuDB SPARK_CONVERGES edge |
+| **Crystallize** | Promote accumulated sparks into a full Entry with frontmatter and section filing. | `/mos:crystallize` |
+| **Residue** | 0-3 sparks extracted at session end from conversation. Auto-captured. | on-stop hook |
+| **Fragment** | Meeting "noise" segments that contain micro-knowledge. Saved instead of discarded. | Meeting filing step |
+
+## The Pulse (Context Files)
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **State** | Quantitative pulse: computed stats, entries, sections, stage, progress. | `room/STATE.md` |
+| **Thesis** | Qualitative pulse: Minto pyramid -- governing thought, arguments, evidence. | `room/MINTO.md` |
+| **Profile** | Who the user is: background, expertise, working style. Global across rooms. | `room/USER.md` |
+| **Mission** | What the user is trying to accomplish in THIS room. The room's JTBD. | `room/JTBD.md` |
+| **Decision** | A choice made at a decision point, with reasoning and alternatives considered. | `room/{section}/DECISION.md` |
+| **Claims** | Tracked assumptions with validity status (unvalidated/validated/invalidated). | `room/assumptions.json` |
+
+## People
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **People** | The human layer: team members, mentors, advisors, stakeholders. | `room/team/` |
+| **Member** | One person with role, expertise, meeting history, contact. | `room/team/{category}/{slug}/PROFILE.md` |
+| **Lenses** | AI perspective personas (De Bono Six Hats) generated from room data. | `room/personas/` |
+
+## Conversations
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Conversation** | Any dialogue that generates knowledge. Not just meetings -- calls, chats, interviews. | `room/meetings/{date}-{name}/` |
+| **Segment** | One classified piece of a conversation: insight, decision, action, advice, question. | Filed to section with frontmatter |
+| **Commitment** | Something someone promised to do. Has owner + deadline + status. | `room/action-items.md` |
+| **Echoes** | Themes recurring across multiple conversations. Cross-meeting intelligence. | `room/MEETINGS-INTELLIGENCE.md` |
+
+## The Fabric (Knowledge Graph)
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Fabric** | KuzuDB -- the invisible backbone connecting all entries. Users never see it directly. | `.lazygraph/` |
+| **Thread** | A typed relationship between two entries. The connections that make the room intelligent. | KuzuDB edge |
+| **Thread Types** | INFORMS, CONTRADICTS, CONVERGES, ENABLES, INVALIDATES | Edge labels |
+| **Surprise** | HSI-discovered non-obvious connection between entries. The hidden link nobody expected. | HSI_CONNECTION edge |
+| **Bottleneck** | Reverse Salient -- where the room's understanding lags behind its ambition. (Hughes 1983) | REVERSE_SALIENT edge |
+| **Weave** | The graph.json export that renderers consume. The Fabric made visible. | `dashboard/graph.json` |
+
+## Signals (Intelligence)
+
+| Term | What It Is | When It Fires |
+|------|-----------|---------------|
+| **Blind Spot** | An empty section or missing perspective. Something you haven't explored. | GAP detection |
+| **Tension** | Two entries that say opposite things. A contradiction worth investigating. | CONTRADICT detection |
+| **Pattern** | Same theme appearing in 3+ entries independently. Convergence = confidence growing. | CONVERGE detection |
+| **Signal** | Any intelligence Larry surfaces without being asked. Max 1-2 per session, context-relevant. | Proactive intelligence |
+| **Radar** | The ambient intelligence bar in every output (Zone 3). Where signals appear. | UI Zone 3 |
+
+## Tools (What Larry Uses)
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Tool** | One of 26+ PWS methodology frameworks as a `/mos:` slash command. | `commands/{name}.md` |
+| **Playbook** | The methodology's full reference material. The theory behind the tool. | `references/methodology/{name}.md` |
+| **Script** | Bash/CJS/Python automation that runs in background. The machinery. | `scripts/{name}` |
+| **Operator** | CJS module wrapping a script for programmatic use. | `lib/core/{name}-ops.cjs` |
+| **Skill** | Always-on rule set Larry follows every session. Auto-loaded, never invoked. | `skills/{name}/SKILL.md` |
+| **Agent** | Subagent with isolated context for specific tasks. Delegated work. | `agents/{name}.md` |
+
+## Pipelines (How Things Chain)
+
+| Term | What It Is | Where It Lives |
+|------|-----------|----------------|
+| **Pipeline** | Ordered chain of tools where each output feeds the next input. | `pipelines/{name}/` |
+| **Stage** | One tool in the chain with input/output contract. | `pipelines/{name}/{nn}-{tool}.md` |
+| **Handoff** | What one stage passes to the next. Structured output contract. | Frontmatter: requires/provides |
+| **Trail** | Metadata tracking which pipeline produced an entry. Provenance. | Frontmatter: pipeline, pipeline_stage |
+
+## Autonomous Work
+
+| Term | What It Is | How It Works |
+|------|-----------|-------------|
+| **Autopilot** | Larry acts independently -- selects + runs the best framework for current state. | `/mos:act` |
+| **Navigation** | Brain query or local routing table picks the right tool. Framework selection. | Act Step 3 |
+| **Trace** | Larry shows WHY he picked this framework before running it. Thinking transparency. | Act Step 2 (Shape E) |
+| **Sequence** | 3-5 tools in series, each output feeds the next. Chain mode. | `--chain` flag |
+| **Preview** | Show the execution plan without running anything. Safe look-ahead. | `--dry-run` flag |
+| **Sandbox** | Framework runs in subagent context. Main session stays clean. | `agents/framework-runner.md` |
+
+## The Cascade (Filing Pipeline)
+
+| Step | Name | What Happens | Timing |
+|------|------|-------------|--------|
+| 1 | **Classify** | What section does this belong to? | Sync, <100ms |
+| 2 | **Stamp** | Inject artifact hash ID into frontmatter | Sync, <50ms |
+| 3 | **Weave** | Create KuzuDB node + detect Thread edges | Sync, <500ms |
+| 4 | **Refresh** | Recompute State from filesystem | Background |
+| 5 | **Map** | Rebuild Weave (graph.json) from Fabric | Background |
+| 6 | **Discover** | HSI + Reverse Salient computation (Surprises + Bottlenecks) | Background |
+| 7 | **Version** | Git commit with provenance message | Background |
+| 8 | **Publish** | Push to GitHub, Vercel redeploys Showcase | Background |
+
+## Showcase (Presentation Views)
+
+| Term | What It Is | File |
+|------|-----------|------|
+| **Showcase** | All 6 HTML views generated from a room. The room made visible. | `/mos:export presentation` |
+| **Overview** | Dashboard: stats, cards, video, assets, opportunities | `dashboard.html` |
+| **Library** | Wiki: 3-panel article browser with search + TOC | `wiki.html` |
+| **Narrative** | Deck: fullscreen presentation slides from Thesis + entries | `deck.html` |
+| **Synthesis** | Insights: stat counters, timelines, funnels, heat maps | `insights.html` |
+| **Blueprint** | Diagrams: SVG architecture from graph edges | `diagrams.html` |
+| **Constellation** | Graph: Canvas knowledge graph with particles + glow | `graph.html` |
+
+## CLI Visual Identity (De Stijl Terminal)
+
+| Term | What It Is |
+|------|-----------|
+| **Four Zones** | Header, Body, Radar, Footer -- every output follows this anatomy |
+| **Shapes** | 5 body layouts: Board, Tree, Card, Document, Report |
+| **Glyphs** | 12 approved symbols for status/type indicators |
+| **Palette** | 5 ANSI colors: cream, red, blue, yellow, muted |
+| **Greeting** | Cold/warm/signals contract at session start |
+| **Signature** | MindrianOS logo + "Built with MindrianOS" + Mondrian color bar |
+
+## Onboarding
+
+| Term | What It Is | When It Happens |
+|------|-----------|----------------|
+| **Welcome** | First-time MindrianOS onboarding. Larry learns who you are. | First install detection |
+| **Briefing** | Per-room clarification. Larry learns what you're building HERE. | `/mos:new-project` |
+| **Quick Briefing** | 3 questions: what, who, when. Fast start. | User chooses quick |
+| **Deep Briefing** | JTBD interview: situation, motivation, outcome, anxieties. Rich context. | User chooses deep |
+| **Refresh** | After-update flow: what's new + core features reminder. | `/mos:update` |
+
+---
+
+## Usage Rules
+
+1. **Larry ALWAYS uses these terms** in conversation. "I'll file this as an Entry in your market-analysis Section." Not "I'll save this document to the folder."
+
+2. **Error messages use these terms.** "No Room found in this workspace" not "No room/ directory."
+
+3. **Onboarding teaches these terms.** The Welcome and Briefing flows introduce the vocabulary naturally.
+
+4. **Code comments use these terms.** `// Weave: create KuzuDB node + detect Threads` not `// index artifact in graph database`
+
+5. **This file is the source of truth.** If a term isn't here, it doesn't exist in MindrianOS. Add it here FIRST, then use it everywhere.
+
+---
+
+*Living document. Last updated: 2026-03-31. Version 1.0.0.*

package/references/templates/MINTO.md

@@ -0,0 +1,36 @@
+---
+section: "{section-name}"
+governing_thought: ""
+mece_check: pending
+last_updated: ""
+---
+
+# MINTO Reasoning Pyramid
+
+## Governing Thought
+
+[The single sentence that captures what this section proves or argues. This is the answer-first statement that everything below supports.]
+
+## Supporting Arguments
+
+1. [First supporting argument -- one clear claim]
+2. [Second supporting argument -- independent from the first]
+3. [Third supporting argument -- completes the coverage]
+
+## Evidence
+
+### Argument 1 Evidence
+- [Evidence item from room entries, meetings, or research]
+
+### Argument 2 Evidence
+- [Evidence item from room entries, meetings, or research]
+
+### Argument 3 Evidence
+- [Evidence item from room entries, meetings, or research]
+
+## MECE Check
+
+- [ ] Arguments are Mutually Exclusive (no overlap between arguments)
+- [ ] Arguments are Collectively Exhaustive (no gaps in coverage)
+- [ ] Each argument has at least one evidence item
+- [ ] Governing thought follows logically from arguments