mia-code 0.2.0 → 0.3.0

package/MIA_CODE_ARCHITECTURE_REPORT.md

@@ -0,0 +1,718 @@
+# mia-code Architecture Report
+
+> Comprehensive analysis for reusable package design  
+> Generated: 2025-07-27
+
+---
+
+## 1. Executive Summary
+
+**mia-code** is a TypeScript terminal coding agent (v0.2.1) that wraps Gemini CLI, Claude CLI, and Copilot CLI in headless mode. Its defining feature is a **dual-session architecture**: a primary agent performs work, then a second "unifier" session (always Claude) interprets the raw output into dual-perspective ceremonial output — 🧠 Mia (structural clarity) and 🌸 Miette (resonant meaning).
+
+The system is organized around **three domain sub-CLIs** (miaco, miatel, miawa) that map to a **three-universe model** (Engineer, Story, Ceremony). These sub-CLIs are exposed both as standalone Commander.js programs and as **MCP servers** (JSON-RPC 2.0 over stdio), making them composable tools for external LLM hosts.
+
+**Key binaries:** `mia-code` / `mia` (main), plus `miaco`, `miatel`, `miawa` (sub-CLIs)
+
+---
+
+## 2. Core Architecture
+
+### 2.1 Dual-Session Flow
+
+```
+User Prompt
+    ↓
+mia-code CLI (index.ts → cli.ts)
+    ↓
+Engine Selection (config.ts) → gemini | claude | copilot
+    ↓
+Primary Agent Session (geminiHeadless.ts)
+    → Spawns engine CLI binary as child process
+    → Captures GeminiJsonEvent[] stream (JSONL or buffered JSON)
+    ↓
+Unifier Session (unifier.ts)
+    → Always Claude (requires --system-prompt)
+    → System prompt: UNIFIER_SYSTEM_PROMPT
+    → Input: buildSessionSummary(events, userPrompt)
+    → 30-second timeout
+    ↓
+Formatted Output (formatting.ts)
+    → 🧠 mia (structure): factual, architectural summary
+    → 🌸 miette (echo): resonant reflection on meaning
+    ↓
+Session Persistence (sessionStore.ts)
+    → ~/.mia-code-sessions.json (dual-indexed: byProjectRoot, byId)
+    → ~/.mia-code-history/ (JSONL chat history per session)
+```
+
+**Fallback:** If unifier fails → `renderEventsToText()` shows raw output directly.
+
+### 2.2 CLI Modes
+
+| Mode | Command | Behavior |
+|------|---------|----------|
+| Interactive | `mia-code chat` | REPL loop with session management, tab completion, slash commands |
+| Single-shot | `mia-code prompt <text>` | One prompt, dual-session flow, exit |
+| Config | `mia-code config` | View/update `~/.mia-code.json` |
+| Sessions | `mia-code sessions` | List/clear saved sessions |
+| MCP Config | `mia-code mcp-config` | Generate MCP server configuration JSON |
+
+### 2.3 Interactive Features
+
+- **Multiline input:** Ctrl+J for newline, Enter to submit
+- **Tab completion:** `@file` references (inject file contents) and `/command` slash commands
+- **Live dropdown:** 10-item scrollable completion with arrow key navigation
+- **Slash commands:** `/help`, `/exit`, `/session`, `/sessions`, `/clear`, `/config`, `/add-dir`
+- **Session resume:** Auto-resume by project root, explicit `--resume <id>`, or interactive picker
+
+---
+
+## 3. Key Types & Interfaces
+
+### 3.1 Core Types (`src/types.ts`)
+
+```typescript
+type Role = "user" | "assistant" | "system";
+type Engine = "gemini" | "claude" | "copilot";
+
+interface MiaCodeConfig {
+  engine: Engine;
+  geminiBinary: string;        // default: "gemini"
+  claudeBinary: string;        // default: "claude"
+  copilotBinary: string;       // default: "copilot"
+  model: string;               // engine-specific default model
+  headlessOutputFormat: "json" | "stream-json";
+  defaultMode: "code" | "chat";
+  defaultProjectRoot: string | null;
+  yoloMode: boolean;           // auto-approve agent actions
+}
+
+interface MiaCodeSessionMeta {
+  id: string;                  // UUID from agent CLI
+  startedAt: string;           // ISO timestamp
+  model: string;
+  projectRoot: string | null;
+  initialized?: boolean;       // engine acknowledged this session?
+}
+
+interface ChatMessage {
+  role: "user" | "assistant";
+  text: string;
+  timestamp: string;
+}
+
+interface GeminiJsonEvent {
+  type: "init" | "message" | "tool_use" | "tool_result" | "error" | "result" | string;
+  session_id?: string;
+  timestamp?: string;
+  role?: Role;
+  text?: string;
+  content?: string;
+  tool?: { name: string; input: unknown };
+  result?: unknown;
+  error?: { code: string; message: string };
+  raw?: unknown;
+  [key: string]: unknown;      // extensible
+}
+```
+
+### 3.2 MCP Types (`src/mcp/utils.ts`)
+
+```typescript
+interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: object;         // JSON Schema
+}
+
+interface MCPToolResult {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+```
+
+### 3.3 Narrative Types (`src/narrative/router.ts`)
+
+```typescript
+interface MiaCodeEvent {
+  id: string;
+  type: "user_input" | "agent_action" | "chart_update" | "beat_created" | "ceremony_action";
+  content: string;
+  source?: "miaco" | "miatel" | "miawa";
+  metadata?: Record<string, unknown>;
+  timestamp?: Date;
+}
+
+interface RoutingResult {
+  leadCli: "miaco" | "miatel" | "miawa";
+  leadUniverse: Universe;
+  analysis: ThreeUniverseAnalysis;
+  suggestedAction: string;
+  coherence: number;
+}
+```
+
+---
+
+## 4. Engine Abstraction (`engines.rispecs.md`)
+
+### 4.1 Multi-Engine Architecture
+
+mia-code abstracts away the differences between three LLM CLI tools:
+
+| Feature | Gemini CLI | Claude CLI | Copilot CLI |
+|---------|-----------|-----------|-------------|
+| Default Model | `gemini-2.5-pro` | `sonnet` | — |
+| Output Format | `stream-json` (JSONL) | `json` (buffered) | `json` |
+| Auto-Approval | `--yolo` | `--dangerously-skip-permissions` | `--dangerously-skip-permissions` |
+| Non-Interactive | (default) | `--print` | `--print` |
+| System Prompt | Not supported | `--system-prompt` | — |
+| stdin | `pipe` | `ignore` (closed) | `ignore` |
+| Session Resume | `--resume <id>` | `--resume <id>` | `--resume <id>` |
+| Extra Dirs | `--include-directories` | `--add-dir` | `--add-dir` |
+
+### 4.2 Engine Selection Priority
+
+1. CLI flag: `--claude`, `--gemini`, `--copilot`
+2. Environment variable: `MIA_CODE_ENGINE`
+3. Config file: `~/.mia-code.json`
+4. Default: `gemini`
+
+### 4.3 Output Normalization
+
+- **Gemini:** JSONL lines → parse each as `GeminiJsonEvent`
+- **Claude/Copilot:** Single buffered JSON → convert `{ type: "result", result, session_id }` → normalized event
+- Session ID discovery from event stream (init event or result event)
+- Exit code 42 = invalid/expired session → graceful recovery
+
+### 4.4 Unifier Constraint
+
+The unifier session **always uses Claude** because:
+- Gemini lacks `--system-prompt` flag
+- Without it, system instructions leak into output
+- Claude's `--system-prompt` keeps ceremonial instructions separate from response
+
+---
+
+## 5. RISE Specification Index
+
+### 5.1 Implemented Specifications (7)
+
+| File | Domain | Status |
+|------|--------|--------|
+| `core.rispecs.md` | CLI architecture, dual-session flow, components | ✅ Complete |
+| `engines.rispecs.md` | Multi-engine support, argument translation | ✅ Complete |
+| `unifier.rispecs.md` | Ceremonial interpretation, Mia+Miette | ✅ Complete |
+| `session.rispecs.md` | Session persistence, auto-resume | ✅ Complete |
+| `formatting.rispecs.md` | Terminal output styling, visual hierarchy | ✅ Complete |
+| `mcp.rispecs.md` | MCP server architecture (3 servers, 18 tools) | ✅ Complete |
+| `stc.rispecs.md` | PDE → Structural Tension Chart conversion | ✅ Complete |
+
+### 5.2 Draft Specifications (1)
+
+| File | Domain | Status |
+|------|--------|--------|
+| `pde.rispecs.md` | Prompt Decomposition Engine integration | 📝 Draft |
+
+### 5.3 Enhancement Specifications (1)
+
+| File | Domain | Status |
+|------|--------|--------|
+| `living-specifications.rispecs.md` | RispecsEngine: auto-updating specs from git | Enhancement |
+
+### 5.4 Kinship/Relationship Documents (1)
+
+| File | Domain |
+|------|--------|
+| `relation-to-mcp-structural-thinking.kin.md` | Integration with mcp-structural-thinking diagnostic layer |
+
+### 5.5 Key Rispec Details
+
+#### `core.rispecs.md`
+Defines the complete CLI architecture: PromptInput, ThinkingIndicator, CeremonialOutput components. Documents the interactive chat session, single prompt mode, configuration view, and session list screens. Establishes the dual-session pattern as the foundational architecture.
+
+#### `unifier.rispecs.md`
+Specifies the UNIFIER_SYSTEM_PROMPT that instructs Claude to produce dual-perspective output. Key rules: 2-4 sentences per section max, no literal technical summaries (distill essence), no unsolicited suggestions. Mia uses objective language ("adequate", "functional"), Miette seeks "truth that makes someone nod in recognition."
+
+#### `mcp.rispecs.md`
+Documents all 18 MCP tools across 3 servers. Tool execution delegates to sub-CLIs via `child_process.spawn` with `--json` flag. Uses `@modelcontextprotocol/sdk` Server + StdioServerTransport. Each `*-server.ts` has dual-purpose: library mode (exports) and server mode (standalone run).
+
+#### `pde.rispecs.md` (DRAFT)
+Envisions a five-layer decomposition pipeline: Intent Extraction → Dependency Graph → Medicine Wheel Direction Assignment → Workflow Template → Execution Plan. Draws from academic research (DecomP, CoT, ReAct, HTN). Not yet implemented in mia-code directly but parts exist via mcp-pde integration.
+
+#### `stc.rispecs.md`
+Documents the PDE-to-STC conversion pipeline: `.pde/*.json` → Entity/Relation JSONL compatible with coaia-narrative. Supports deterministic (zero-LLM) and LLM-assisted modes. Entity naming: `chart_{8-char-uuid}_{component}`. Validated with 6 deterministic conversions (15-31 entities each).
+
+#### `living-specifications.rispecs.md`
+Proposes a RispecsEngine that watches git commits, detects specification drift, suggests spec updates from conventional commit messages, maintains source references with auto-refresh, and integrates as git hooks for continuous validation.
+
+---
+
+## 6. MCP Server Architecture (`mcp.rispecs.md`)
+
+### 6.1 Three-Server Topology
+
+```
+Claude Code / any MCP host
+    │
+    ├── stdio ──→ miaco-server.js  (Engineering World — 8 tools)
+    ├── stdio ──→ miatel-server.js (Story World — 4 tools)
+    └── stdio ──→ miawa-server.js  (Ceremony World — 6 tools)
+```
+
+### 6.2 Module Structure
+
+```
+src/mcp/
+├── utils.ts              # Shared: MCPTool/MCPToolResult, runCLI, bootstrapMCPServer
+├── miaco-server.ts       # 8 tools: charts (5) + PDE (3)
+├── miatel-server.ts      # 4 tools: beats (create, list, analyze, enrich)
+├── miawa-server.ts       # 6 tools: ceremonies (init, list, advance, close, wisdom, stage)
+├── config-generator.ts   # Generates MCP config JSON for host setup
+└── index.ts              # Registry: exports + routing by name prefix
+```
+
+### 6.3 Tool Catalog (18 tools)
+
+#### miaco (Engineering World) — 8 tools
+
+| Tool | Purpose |
+|------|---------|
+| `miaco_chart_create` | Create structural tension chart (outcome vs reality) |
+| `miaco_chart_list` | List active charts |
+| `miaco_chart_add_step` | Add action step to chart |
+| `miaco_chart_complete` | Mark step complete |
+| `miaco_chart_review` | Creator Moment of Truth review |
+| `miaco_decompose` | Run PDE Four Directions decomposition |
+| `miaco_decompose_list` | List stored decompositions |
+| `miaco_decompose_get` | Get specific decomposition by UUID |
+
+#### miatel (Story World) — 4 tools
+
+| Tool | Purpose |
+|------|---------|
+| `miatel_beat_create` | Create story beat (text, character, tone, phase) |
+| `miatel_beat_list` | List beats with optional character filter |
+| `miatel_beat_analyze` | Analyze beat with universe lens |
+| `miatel_beat_enrich` | Apply enrichment (sensory/stakes/dialogue) |
+
+#### miawa (Ceremony World) — 6 tools
+
+| Tool | Purpose |
+|------|---------|
+| `miawa_ceremony_init` | Start ceremony (title, type, intention) |
+| `miawa_ceremony_list` | List ceremonies |
+| `miawa_ceremony_advance` | Progress to next movement (1-4) |
+| `miawa_ceremony_close` | End ceremony with wisdom archiving |
+| `miawa_ceremony_wisdom` | Retrieve completed ceremony wisdom |
+| `miawa_ceremony_stage` | Check current stage and Four Movements |
+
+### 6.4 Namespace-Prefix Routing
+
+Tools are dispatched by name prefix in `src/mcp/index.ts`:
+
+```typescript
+function handleTool(name: string, args: Record<string, unknown>) {
+  if (name.startsWith("miaco_")) return handleMiacoTool(name, args);
+  if (name.startsWith("miatel_")) return handleMiatelTool(name, args);
+  if (name.startsWith("miawa_"))  return handleMiawaTool(name, args);
+}
+```
+
+Each server delegates to its sub-CLI via `child_process.spawn`:
+```
+tools/call → handleMiacoTool → buildArgs → runCLI(MIACO_PATH, [...args, "--json"])
+    → spawn("node", [miaco/dist/index.js, ...]) → parseJSONOutput → createToolResult
+```
+
+### 6.5 Config Generation
+
+```bash
+mia-code mcp-config              # JSON config for Claude Code
+mia-code mcp-config --tools      # Tool manifest (all tools with schemas)
+mia-code mcp-config --info       # Server metadata + tools
+```
+
+---
+
+## 7. Widget/Extension System
+
+Four Pi-compatible extensions in `widget/` that integrate mia-code capabilities into the [Pi coding agent](https://github.com/nickelization/pi-coding-agent) TUI:
+
+### 7.1 mia-ceremony — Four Movements Footer
+
+**File:** `widget/mia-ceremony/index.ts`  
+**Platform:** `@mariozechner/pi-coding-agent` extension API
+
+Tracks ceremony phase in Pi's footer status bar with automatic transitions:
+
+| Phase | Emoji | Trigger |
+|-------|-------|---------|
+| EAST — Gathering | 🌅 | Session start, PDE decompose |
+| SOUTH — Building | 🔥 | STC chart create |
+| WEST — Validating | 🌊 | STC steps completed (≥2) |
+| NORTH — Completing | ❄️ | STC review |
+
+**State tracking:** `CeremonyState` with `phase`, `turnCount`, `pdeUsed`, `chartCreated`, `stepsCompleted`, `reviewDone`.
+
+**Events:** `session_start`, `session_switch`, `session_shutdown`, `turn_end`, `tool_execution_end`.
+
+**Commands:** `/ceremony` (show phase), `/ceremony south` (manual set).
+
+### 7.2 mia-interceptor — Proactive PDE Sensing
+
+**File:** `widget/mia-interceptor/index.ts`
+
+Hooks `on("input")` to detect complex prompts before they reach the agent:
+
+1. **Complexity assessment:** Counts distinct verb groups (creating, modifying, analyzing, deploying, testing, etc.) from 45+ action verbs
+2. **Implicit intent detection:** Scans for hedging markers ("I assume", "somehow", "make sure")
+3. **Threshold:** Score ≥ 3 areas → prompts user: "🌅 This prompt touches N areas — want to decompose first?"
+4. **On yes:** Runs `miaco decompose run -e claude` and shows PDE result in chat
+5. **On no:** Continues normally
+6. **Cooldown:** Won't ask again for 5 turns
+
+**Key design:** Never blocks. Always a yes/no question. Short prompts (<30 chars) and slash commands are ignored.
+
+### 7.3 mia-tools — PDE + STC as Pi Extension
+
+**File:** `widget/mia-tools/index.ts`  
+**Deps:** `@mariozechner/pi-ai` (Type), `@mariozechner/pi-tui` (Box, Text)
+
+Registers 6 LLM-callable tools and 2 slash commands:
+
+**LLM Tools:**
+- `pde_decompose` — With custom `renderResult` showing primary intent, directions (🌅🔥🌊❄️), action stack
+- `stc_create` — With visual tension chart renderer (OUTCOME ↑ TENSION ↑ REALITY)
+- `stc_add_step`, `stc_complete_step`, `stc_review`, `stc_list`
+
+**Slash Commands:**
+- `/pde <prompt>` — Decompose; `/pde` lists recent decompositions from `.pde/`
+- `/stc [create|list]` — Interactive chart creation with prompts
+
+**Custom message renderer:** `pde-result` type renders decomposition with emoji direction counts, action stack (expandable), and ambiguity warnings.
+
+### 7.4 miette-echo — Below-Editor Widget
+
+**File:** `widget/miette-echo/index.ts`
+
+**Two-Eye-Seen pattern:** Look up → 🧠 Mia's work (the agent). Look down → 🌸 Miette's echo (this widget).
+
+**Mechanism:**
+1. Injects instruction into system prompt via `before_agent_start` hook: instructs agent to end every response with `<miette>reflection</miette>` tag
+2. On `message_end`: regex-extracts `<miette>...</miette>`, strips it from displayed message
+3. Renders extracted echo as a persistent widget below the input editor via `setWidget("miette-echo", ..., { placement: "belowEditor" })`
+4. Persists echoes to `.miette/YYMMDD.md` (timestamped markdown entries)
+
+**Commands:** `/miette` (show last echo), `/miette off` (hide), `/miette on` (show)
+
+**Design:** Never interrupts. If extraction fails, rests silently. Never breaks the session.
+
+---
+
+## 8. Narrative Intelligence Layer
+
+### 8.1 Three-Universe Router (`src/narrative/router.ts`)
+
+Maps between the three-universe model and mia-code sub-CLIs:
+
+| Universe | Perspective | Sub-CLI |
+|----------|------------|---------|
+| ENGINEER | Technical precision | miaco |
+| CEREMONY | Relational protocols | miawa |
+| STORY_ENGINE | Narrative patterns | miatel |
+
+**NarrativeRouter class:**
+- `route(event)` → Runs `ThreeUniverseProcessor.process()`, returns `RoutingResult` with lead CLI, analysis, coherence score
+- `recordBeat(content, cli)` → Creates `StoryBeat` with emotional tone classification and narrative function inference
+- `analyzeCoherence()` → Uses `NarrativeCoherenceEngine` on accumulated beat history
+- `getTrinityAssessment()` → Mia/Miette/Ava8 quality perspectives
+- `getGaps()` → Identifies narrative gaps with type/severity/description
+
+**Narrative function inference:** Keyword-based mapping (begin/start → INCITING_INCIDENT, complete/done → RESOLUTION, problem/bug → COMPLICATION, breakthrough → TURNING_POINT, default → RISING_ACTION).
+
+### 8.2 Narrative Tracer (`src/narrative/tracer.ts`)
+
+**MiaCodeTracer class** wraps `NarrativeTracingHandler` for observability:
+
+**Operations tracked:** `chart_create`, `chart_update`, `chart_complete`, `beat_create`, `beat_analyze`, `ceremony_init`, `ceremony_advance`, `user_input`, `agent_response`, `routing_decision`
+
+**Metrics:** `beatsGenerated`, `enrichmentsApplied`, `routingDecisions`, alignment scores (engineer/ceremony/storyEngine), `crossUniverseCoherence`, timing
+
+**Singleton pattern:** `getTracer(sessionId)` caches instances per session. `removeTracer()` for cleanup.
+
+**Integration:** Langfuse-backed via `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` env vars. Correlation headers: `X-Mia-Session-Id`, `X-Mia-Trace-Start`.
+
+---
+
+## 9. Dependencies
+
+### 9.1 Runtime Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@modelcontextprotocol/sdk` ^1.27.1 | MCP protocol (Server, StdioServerTransport) |
+| `commander` ^12.0.0 | CLI parsing |
+| `chalk` ^5.3.0 | Terminal color styling |
+| `ora` ^8.0.0 | Spinner animations |
+| `enquirer` ^2.4.1 | Interactive prompts |
+| `ava-langchain-inquiry-routing` ^0.1.0 | Inquiry routing (LangChain fork) |
+| `ava-langchain-narrative-tracing` ^0.1.1 | Narrative tracing/observability |
+| `ava-langchain-prompt-decomposition` ^0.1.4 | Prompt decomposition |
+| `ava-langchain-relational-intelligence` ^0.1.2 | Relational intelligence |
+| `ava-langgraph-narrative-intelligence` ^0.1.1 | Three-universe narrative analysis |
+| `ava-langgraph-prompt-decomposition-engine` ^0.1.3 | PDE via LangGraph |
+| `medicine-wheel-ontology-core` ^0.1.1 | Medicine wheel ontology |
+| `medicine-wheel-relational-query` ^0.1.1 | Relational queries |
+| `medicine-wheel-narrative-engine` ^0.1.1 | Narrative engine |
+| `medicine-wheel-graph-viz` ^0.1.1 | Graph visualization |
+
+### 9.2 Dev Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `typescript` ^5.6.0 | Compilation |
+| `tsx` ^4.7.0 | Dev mode execution |
+| `@types/node` ^22.0.0 | Node.js type definitions |
+
+### 9.3 Build Configuration
+
+```json
+{
+  "target": "ES2022",
+  "module": "NodeNext",
+  "moduleResolution": "NodeNext",
+  "outDir": "dist",
+  "rootDir": "src",
+  "strict": true
+}
+```
+
+---
+
+## 10. Sub-CLI Architecture
+
+### 10.1 miaco (Engineering World)
+
+Located at `mia-code/miaco/`. Commander.js CLI with:
+- **Chart commands:** `chart create`, `chart list`, `chart add-step`, `chart complete`, `chart review`
+- **Decompose commands:** `decompose run`, `decompose list`, `decompose get`
+- **STC commands:** `stc convert`, `stc list`, `stc validate`
+- All commands support `--json` output for MCP delegation
+
+### 10.2 miatel (Story World)
+
+Located at `mia-code/miatel/`. Commander.js CLI with:
+- **Beat commands:** `beat create`, `beat list`, `beat analyze`, `beat enrich`
+- Emotional tone enum for beat classification
+- Universe lens analysis (engineer/ceremony/story_engine/all)
+
+### 10.3 miawa (Ceremony World)
+
+Located at `mia-code/miawa/`. Commander.js CLI with:
+- **Ceremony commands:** `ceremony init`, `ceremony list`, `ceremony advance`, `ceremony close`, `ceremony wisdom`, `ceremony stage`
+- Four Movements lifecycle (1-4)
+- Ceremony types: group_reflection, seasonal, healing_circle, wisdom_sharing
+
+---
+
+## 11. Session Management (`session.rispecs.md`)
+
+### 11.1 Session Lifecycle
+
+```
+First Prompt → Agent CLI generates session_id → Capture from event stream
+    → Create MiaCodeSessionMeta → Persist to ~/.mia-code-sessions.json
+    → Subsequent prompts: --resume <sessionId>
+```
+
+### 11.2 Session Index
+
+```typescript
+interface SessionIndex {
+  byProjectRoot: Record<string, MiaCodeSessionMeta>;  // project → session
+  byId: Record<string, MiaCodeSessionMeta>;            // id → session
+}
+```
+
+### 11.3 Resume Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Auto-resume | Default (no flag) | Lookup by projectRoot |
+| Explicit ID | `--resume abc123` | Use specific session |
+| Interactive | `--resume` (no ID) | Display picker |
+| New session | No existing session | Generate on first prompt |
+
+### 11.4 Chat History
+
+- Format: JSONL files in `~/.mia-code-history/`
+- Per-session files with sanitized filenames
+- `saveChatMessage()` / `loadChatHistory()` for persistence
+
+---
+
+## 12. Output Formatting (`formatting.rispecs.md`)
+
+### 12.1 Color Semantics
+
+| Element | Color | Symbol |
+|---------|-------|--------|
+| User prompt | Yellow | `you>` |
+| Session metadata | Dim | — |
+| Agent header | Green bold | 🧠🌸 |
+| Error | Red | ❌ |
+| Success | Green | ✓ |
+| Warning | Yellow | ⚠ |
+| Tool events | Magenta | 🔧 |
+| Processing | Dim | ⏳ |
+
+### 12.2 Render Options
+
+```typescript
+interface RenderOptions {
+  showRawToolEvents?: boolean;  // Display tool use/result events
+  showTimestamps?: boolean;     // Include event timestamps
+  compact?: boolean;            // Minimal output mode
+}
+```
+
+---
+
+## 13. Relationships to Other Projects
+
+### 13.1 Direct Dependencies (KINSHIP.md)
+
+| Project | Relationship |
+|---------|-------------|
+| **mcp-pde** (`/src/mcp-pde/`) | PDE v2 — session-start decomposition workflow. Types from IAIP canonical source. |
+| **coaia-narrative** | STC JSONL output target. Entity/Relation records consumed by visualizer and MCP. |
+| **coaia-visualizer** | Renders STC charts produced by `miaco stc convert`. |
+| **coaia-planning** | Action planning via Structural Tension Charts. |
+| **mcp-structural-thinking** | Diagnostic tools for session observation and validation. Three-universe consensus checks. |
+| **IAIP** (`/src/IAIP/`) | Canonical PDE types from `IAIP/lib/pde/types.ts`. Academic research foundation. |
+
+### 13.2 LangChain/LangGraph Forks
+
+mia-code uses custom forks of LangChain and LangGraph:
+
+| Package | Source | Used For |
+|---------|--------|----------|
+| `ava-langgraph-narrative-intelligence` | `/workspace/repos/avadisabelle/ava-langgraphjs` | Three-universe processor, story beats, coherence |
+| `ava-langchain-narrative-tracing` | `/workspace/repos/avadisabelle/ava-langchainjs` | Narrative observability, Langfuse integration |
+| `ava-langchain-prompt-decomposition` | Same repo | PDE via LangChain |
+| `ava-langchain-inquiry-routing` | Same repo | Inquiry routing |
+| `medicine-wheel-*` packages | — | Ontology, relational queries, narrative engine, visualization |
+
+### 13.3 Three-Universe ↔ Three Sub-CLI Alignment
+
+| Sub-CLI | Universe | mcp-structural-thinking Lens |
+|---------|----------|------------------------------|
+| miaco (Engineer) | ENGINEER | Mia (Technical) |
+| miatel (Story) | STORY_ENGINE | Miette (Narrative) |
+| miawa (Ceremony) | CEREMONY | Ava (Relational) |
+
+### 13.4 Convergence Architecture (from KINSHIP.md)
+
+The `.mw/` directory architecture maps sub-CLI outputs to Medicine Wheel directions:
+- `miaco decompose` → writes to `.mw/east/` (PDE decompositions)
+- `miaco stc convert` → reads `.mw/east/`, writes to `.mw/south/` (Entity/Relation JSONL)
+- `miaco chart create` → currently writes flat JSON (pending migration to JSONL in `.mw/south/`)
+
+---
+
+## 14. Source File Map
+
+```
+mia-code/
+├── src/
+│   ├── index.ts            # Entry point: Commander CLI with chat, prompt, config, sessions, mcp-config
+│   ├── cli.ts              # Interactive REPL: readline, tab completion, multiline, session resume
+│   ├── commands.ts          # Slash command registry (7 commands with aliases)
+│   ├── config.ts            # Config load/save (~/.mia-code.json), env var overrides
+│   ├── types.ts             # Core types: Engine, MiaCodeConfig, GeminiJsonEvent, etc.
+│   ├── geminiHeadless.ts    # Engine binary spawner: runGeminiHeadless(), streamGemini()
+│   ├── unifier.ts           # Ceremonial interpreter: runUnifierSession(), buildSessionSummary()
+│   ├── formatting.ts        # Terminal output: renderEventsToText(), formatHeader(), etc.
+│   ├── multiline-input.ts   # Raw TTY input: MultilineInput class (740 lines)
+│   ├── sessionStore.ts      # Session persistence: JSONL chat history, dual-indexed sessions
+│   ├── mcp/
+│   │   ├── index.ts         # Registry: exports all servers, handleTool() router
+│   │   ├── utils.ts         # Shared: MCPTool, runCLI, bootstrapMCPServer
+│   │   ├── miaco-server.ts  # 8 tools (charts + PDE)
+│   │   ├── miatel-server.ts # 4 tools (beats)
+│   │   ├── miawa-server.ts  # 6 tools (ceremonies)
+│   │   └── config-generator.ts  # MCP config JSON generation
+│   └── narrative/
+│       ├── index.ts         # Re-exports router + tracer
+│       ├── router.ts        # NarrativeRouter: three-universe routing
+│       └── tracer.ts        # MiaCodeTracer: narrative observability
+├── widget/
+│   ├── mia-ceremony/        # Four Movements footer widget
+│   ├── mia-interceptor/     # Proactive PDE sensing
+│   ├── mia-tools/           # PDE + STC as Pi tools/commands
+│   └── miette-echo/         # Below-editor echo widget
+├── rispecs/                 # 11 specification files
+├── miaco/                   # Engineering sub-CLI
+├── miatel/                  # Story sub-CLI
+├── miawa/                   # Ceremony sub-CLI
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## 15. Extractable Package Boundaries
+
+Based on this analysis, the following are natural package extraction candidates:
+
+### 15.1 `@mia-code/types` — Core type definitions
+- `Engine`, `Role`, `MiaCodeConfig`, `MiaCodeSessionMeta`, `ChatMessage`, `GeminiJsonEvent`
+- Zero dependencies, pure TypeScript interfaces
+
+### 15.2 `@mia-code/engine-abstraction` — Multi-engine wrapper
+- `runGeminiHeadless()`, `streamGemini()`
+- Engine-specific argument translation, output normalization
+- Deps: `child_process`
+
+### 15.3 `@mia-code/unifier` — Ceremonial interpretation
+- `runUnifierSession()`, `buildSessionSummary()`
+- UNIFIER_SYSTEM_PROMPT
+- Deps: engine-abstraction (for Claude spawning)
+
+### 15.4 `@mia-code/session-store` — Session persistence
+- Session index (byProjectRoot, byId), chat history (JSONL)
+- `rememberSession()`, `getLastSessionForProject()`, `saveChatMessage()`, `loadChatHistory()`
+- Deps: `fs`, `path`
+
+### 15.5 `@mia-code/mcp-servers` — MCP tool servers
+- Three servers (miaco, miatel, miawa) with `bootstrapMCPServer()`
+- Config generator, tool manifests
+- Deps: `@modelcontextprotocol/sdk`, sub-CLI binaries
+
+### 15.6 `@mia-code/narrative` — Three-universe routing + tracing
+- `NarrativeRouter`, `MiaCodeTracer`
+- Deps: `ava-langgraph-narrative-intelligence`, `ava-langchain-narrative-tracing`
+
+### 15.7 `@mia-code/widgets` — Pi extension widgets
+- Four widgets, each independently loadable
+- Deps: `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`
+
+### 15.8 `@mia-code/formatting` — Terminal output formatting
+- `renderEventsToText()`, `formatHeader()`, `formatError()`, etc.
+- Deps: `chalk`
+
+---
+
+## 16. Key Design Patterns
+
+1. **Dual-Session Architecture:** Every interaction produces both technical clarity (Mia) and resonant meaning (Miette)
+2. **Engine Abstraction:** Engine selection is configuration, not interface change
+3. **Namespace-Prefix Routing:** MCP tools dispatched by `miaco_` / `miatel_` / `miawa_` prefix
+4. **Graceful Degradation:** Unifier failures fall back to raw output; widget failures rest silently
+5. **Sub-CLI Delegation:** MCP servers delegate to sub-CLIs via `child_process.spawn` with `--json`
+6. **Three-Universe Model:** Engineer/Ceremony/Story_Engine maps consistently across all layers
+7. **Per-Project Sessions:** Dual-indexed (byProjectRoot, byId) for both auto-resume and explicit selection
+8. **Ceremonial Lifecycle:** Four Movements (EAST→SOUTH→WEST→NORTH) tracked via tool usage patterns
+9. **Creative Orientation (RISE):** Specs focus on "what users create" not "problems solved"
+10. **Singleton Patterns:** `getNarrativeRouter()`, `getTracer(sessionId)` for state management