mia-code 0.2.0 → 0.3.0

package/rispecs/_sync_/miadi-code/stc/SPEC.md

@@ -0,0 +1,397 @@
+# Hierarchical Charting (MultiChartContextManager)
+
+> RISE Framework Specification v1.0
+> Document: miadi-code/rispecs/hierarchical-charting.rispecs.md
+> Status: miadi-code Enhancement
+
+---
+
+## Creative Intent
+
+The MultiChartContextManager empowers users to create complex, nested structural tension charts for orchestrating hierarchical projects. Users achieve clear visibility into multi-level goal structures where master charts telescope into sub-charts, maintaining both overview clarity and actionable detail.
+
+---
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- miadi-code has ChartRegistry for tracking active charts (`src/registry/`)
+- coaia-narrative MCP supports chart creation and telescoping
+- Charts can have parent/child relationships via `parentChart` and `parentActionStep` metadata
+- Current implementation handles one active chart at a time
+- No unified context manager for multi-chart navigation
+- Three-universe analysis applies to single charts, not chart hierarchies
+- STC workspace integration pending (per SPEC.md)
+
+**Desired Structural State:**
+- MultiChartContextManager maintains awareness of entire chart hierarchy
+- Users can zoom in/out of chart levels seamlessly
+- Three-universe analysis can operate at any hierarchy level
+- Cross-chart dependencies tracked and honored
+- Ceremonies cascade through hierarchy (parent completion triggers child review)
+- Visual representation available via coaia-visualizer integration
+
+---
+
+## Core Components
+
+### MultiChartContextManager
+
+**Purpose:** Orchestrate navigation and operations across chart hierarchies.
+
+```typescript
+interface MultiChartContextManager {
+  // Hierarchy Management
+  loadHierarchy(rootChartId: string): Promise<ChartHierarchy>;
+  createSubChart(parentChartId: string, actionStepId: string): Promise<StructuralTensionChart>;
+  
+  // Navigation
+  getCurrentChart(): StructuralTensionChart | null;
+  setCurrentChart(chartId: string): void;
+  zoomIn(actionStepId: string): Promise<void>;
+  zoomOut(): Promise<void>;
+  
+  // Context Awareness
+  getHierarchyPath(): ChartPathNode[];
+  getRelatedCharts(): RelatedChart[];
+  
+  // Operations
+  cascadeProgress(chartId: string): Promise<void>;
+  checkHierarchyObligations(): ObligationReport;
+  
+  // Three-Universe Integration
+  analyzeAtLevel(level: 'master' | 'current' | 'detail'): UniverseAnalysis;
+  
+  // Persistence
+  saveState(): Promise<void>;
+  restoreState(stateId: string): Promise<void>;
+}
+
+interface ChartHierarchy {
+  root: StructuralTensionChart;
+  children: Map<string, ChartHierarchy>;  // chartId -> subtree
+  totalDepth: number;
+  totalCharts: number;
+}
+
+interface ChartPathNode {
+  chartId: string;
+  desiredOutcome: string;
+  level: number;
+  isActive: boolean;
+}
+
+interface RelatedChart {
+  chartId: string;
+  relationship: 'parent' | 'sibling' | 'child' | 'dependency';
+  desiredOutcome: string;
+}
+```
+
+### HierarchyRenderer
+
+**Purpose:** Generate visual representations of chart hierarchies.
+
+```typescript
+interface HierarchyRenderer {
+  // Terminal rendering
+  renderTree(hierarchy: ChartHierarchy): string;
+  renderBreadcrumb(path: ChartPathNode[]): string;
+  renderProgressRollup(hierarchy: ChartHierarchy): string;
+  
+  // JSON for visualizer
+  toVisualizerFormat(hierarchy: ChartHierarchy): VisualizerData;
+}
+
+// Terminal tree output example:
+// ┌─ 📊 Mastery of Terminal Agent Workflows [52%]
+// │  ├── 📋 Engine Abstraction Layer [80%]
+// │  │   ├── ✅ Gemini CLI Integration
+// │  │   └── 🔄 Claude CLI Integration [60%]
+// │  ├── 🔄 Session Persistence [45%]
+// │  └── ⏳ Ceremonial Output Layer [30%]
+// └──────────────────────────────────────────
+
+interface VisualizerData {
+  nodes: VisualizerNode[];
+  edges: VisualizerEdge[];
+  metadata: {
+    rootId: string;
+    levels: number;
+    totalProgress: number;
+  };
+}
+```
+
+### CrossChartDependencyTracker
+
+**Purpose:** Track and enforce dependencies between charts.
+
+```typescript
+interface CrossChartDependencyTracker {
+  // Define dependency
+  addDependency(fromChart: string, toChart: string, type: DependencyType): void;
+  
+  // Query
+  getDependencies(chartId: string): Dependency[];
+  getDependents(chartId: string): Dependency[];
+  
+  // Validation
+  checkDependenciesMet(chartId: string): DependencyCheck;
+  detectCircularDependencies(): CircularDependency[];
+  
+  // Cascade
+  notifyCompletion(chartId: string): CascadeResult;
+}
+
+type DependencyType = 
+  | 'blocks'           // This chart blocks another
+  | 'requires'         // This chart requires another
+  | 'informs'          // Completion of this informs another
+  | 'parallel';        // These can proceed in parallel
+
+interface Dependency {
+  fromChartId: string;
+  toChartId: string;
+  type: DependencyType;
+  description?: string;
+}
+
+interface CascadeResult {
+  triggeredCharts: string[];
+  updatedProgress: Map<string, number>;
+  ceremonies: Ceremony[];
+}
+```
+
+---
+
+## Three-Universe Hierarchical Analysis
+
+### Level-Aware Analysis
+
+```typescript
+interface HierarchicalUniverseAnalysis {
+  // Engineer Universe at hierarchy level
+  engineer: {
+    atMaster: string;     // "Project requires X components"
+    atCurrent: string;    // "Current task needs Y implementation"
+    atDetail: string;     // "Specific step involves Z"
+  };
+  
+  // Ceremony Universe at hierarchy level
+  ceremony: {
+    atMaster: string;     // "Project honors these relationships"
+    atCurrent: string;    // "Current phase maintains these obligations"
+    atDetail: string;     // "Step fulfills this specific ceremony"
+  };
+  
+  // Story Engine at hierarchy level
+  storyEngine: {
+    atMaster: string;     // "The narrative arc of this project"
+    atCurrent: string;    // "Current chapter in the story"
+    atDetail: string;     // "This beat advances the narrative"
+  };
+}
+
+// Usage in prompt processing
+function analyzePromptHierarchically(
+  prompt: string, 
+  manager: MultiChartContextManager
+): HierarchicalUniverseAnalysis {
+  const path = manager.getHierarchyPath();
+  
+  return {
+    engineer: {
+      atMaster: analyzeEngineer(prompt, path[0]),
+      atCurrent: analyzeEngineer(prompt, manager.getCurrentChart()),
+      atDetail: path.length > 2 ? analyzeEngineer(prompt, path[path.length - 1]) : null
+    },
+    // ... ceremony and storyEngine
+  };
+}
+```
+
+---
+
+## Integration with miadi-code
+
+### CLI Commands
+
+```bash
+# View chart hierarchy
+/charts tree
+
+# Navigate hierarchy
+/charts zoom-in <actionStepId>
+/charts zoom-out
+/charts goto <chartId>
+
+# Show current position
+/charts where
+
+# Progress rollup
+/charts progress
+
+# Dependency management
+/charts depend <fromChart> blocks <toChart>
+/charts check-deps
+```
+
+### Interactive Navigation
+
+```typescript
+// In cli.ts
+async function handleChartsCommand(args: string[], manager: MultiChartContextManager) {
+  switch (args[0]) {
+    case 'tree':
+      const hierarchy = await manager.loadHierarchy(manager.getCurrentChart().chartId);
+      console.log(renderer.renderTree(hierarchy));
+      break;
+      
+    case 'zoom-in':
+      await manager.zoomIn(args[1]);
+      console.log(renderer.renderBreadcrumb(manager.getHierarchyPath()));
+      break;
+      
+    case 'where':
+      const path = manager.getHierarchyPath();
+      console.log('📍 Current position:');
+      path.forEach((node, i) => {
+        const indent = '  '.repeat(i);
+        const marker = node.isActive ? '→' : ' ';
+        console.log(`${indent}${marker} ${node.desiredOutcome}`);
+      });
+      break;
+  }
+}
+```
+
+### coaia-visualizer Integration
+
+```typescript
+// Launch visualizer with hierarchy context
+async function launchVisualizerWithHierarchy(manager: MultiChartContextManager) {
+  const hierarchy = await manager.loadHierarchy(manager.getCurrentChart().chartId);
+  const visualizerData = renderer.toVisualizerFormat(hierarchy);
+  
+  // POST to coaia-visualizer API
+  await fetch('http://localhost:3336/api/charts/hierarchy', {
+    method: 'POST',
+    body: JSON.stringify(visualizerData)
+  });
+  
+  // Open in browser
+  exec(`open http://localhost:3336/hierarchy/${hierarchy.root.chartId}`);
+}
+```
+
+---
+
+## Ceremonies for Hierarchy Operations
+
+```typescript
+// When creating a sub-chart
+const telescopeCeremony: Ceremony = {
+  type: 'telescoped',
+  participants: ['miadi', 'user'],
+  intentions: [
+    'Expand action step into detailed chart',
+    'Maintain hierarchy coherence'
+  ],
+  observations: [
+    `Created sub-chart for "${actionStep.description}"`,
+    `Depth level: ${parentChart.level + 1}`,
+    `Parent: ${parentChart.desiredOutcome}`
+  ],
+  timestamp: new Date().toISOString()
+};
+
+// When cascading completion
+const cascadeCeremony: Ceremony = {
+  type: 'hierarchy_cascade',
+  participants: ['multi_chart_manager', 'charts'],
+  intentions: ['Propagate completion through hierarchy'],
+  observations: [
+    `Completed: ${completedChart.desiredOutcome}`,
+    `Updated parent progress: ${parentProgress}%`,
+    `Triggered charts: ${triggeredCharts.join(', ')}`
+  ],
+  timestamp: new Date().toISOString()
+};
+```
+
+---
+
+## API Surface
+
+```typescript
+export class MultiChartContextManager {
+  // Lifecycle
+  static create(mcpClient: MCPClient, chartPath: string): MultiChartContextManager;
+  
+  // Hierarchy
+  loadHierarchy(rootChartId: string): Promise<ChartHierarchy>;
+  getHierarchy(): ChartHierarchy;
+  getHierarchyPath(): ChartPathNode[];
+  
+  // Navigation
+  getCurrentChart(): StructuralTensionChart | null;
+  zoomIn(actionStepId: string): Promise<void>;
+  zoomOut(): Promise<void>;
+  gotoChart(chartId: string): Promise<void>;
+  
+  // Operations
+  createSubChart(actionStepId: string, currentReality: string): Promise<StructuralTensionChart>;
+  updateProgress(chartId: string, progress: number): Promise<void>;
+  markComplete(chartId: string): Promise<CascadeResult>;
+  
+  // Dependencies
+  addDependency(from: string, to: string, type: DependencyType): void;
+  checkDependencies(): ObligationReport;
+  
+  // Visualization
+  renderTree(): string;
+  renderBreadcrumb(): string;
+  toVisualizerFormat(): VisualizerData;
+  
+  // Events
+  onChartChanged(handler: (chart: StructuralTensionChart) => void): Disposable;
+  onHierarchyUpdated(handler: (hierarchy: ChartHierarchy) => void): Disposable;
+}
+
+interface ObligationReport {
+  met: Obligation[];
+  unmet: Obligation[];
+  blocked: string[];  // Charts blocked by unmet obligations
+}
+
+interface Obligation {
+  chartId: string;
+  description: string;
+  type: 'dependency' | 'ceremony' | 'phase_gate';
+}
+```
+
+---
+
+## Success Criteria
+
+✅ MultiChartContextManager tracks entire chart hierarchies
+✅ Navigation (zoom-in, zoom-out, goto) works seamlessly
+✅ Breadcrumb rendering shows current position in hierarchy
+✅ Tree rendering displays full hierarchy with progress
+✅ Dependencies enforced across charts
+✅ Ceremonies cascade through hierarchy on completion
+✅ Three-universe analysis operates at configurable levels
+✅ coaia-visualizer integration for visual hierarchy navigation
+✅ State persistence across sessions
+
+---
+
+## References
+
+- miadi-code registry: `/a/src/Miadi/miadi-code/src/registry/`
+- coaia-narrative chart structure: `/a/src/llms/llms-structural-tension-charts.txt`
+- coaia-visualizer API: `/a/src/coaia-visualizer/`
+- miadi-code SPEC.md: `/a/src/Miadi/miadi-code/rispecs/SPEC.md`

package/rispecs/_sync_/miadi-code/stc/STATUS.md

@@ -0,0 +1,70 @@
+# STC (Structural Tension Charting) - Implementation Status
+
+**Module**: `miadi-code/src/stc/`
+**Version**: 1.1.0
+**Last Updated**: 2026-01-31
+
+---
+
+## Implementation Status: OPERATIONAL ✅
+
+### Core Components
+
+| Component | Status | Location |
+|-----------|--------|----------|
+| Workspace Client | ✅ Complete | `stc/workspace-client.ts` |
+| File Operations | ✅ Complete | `stc/file-operations.ts` |
+| Workspace Config | ✅ Complete | `stc/workspace-config.ts` |
+| Chart Types | ✅ Complete | `stc/types.ts` |
+| Dashboard TUI | ✅ Enhanced | `dashboard.ts` |
+
+### Command Support
+
+| Command | Status | Notes |
+|---------|--------|-------|
+| `/stc config add` | ✅ Working | Maps repo to local path |
+| `/stc config list` | ✅ Working | Shows workspace mappings |
+| `/stc load` | ✅ Working | Loads from STC files |
+| `/stc observe` | ✅ Working | Adds observations to chart |
+| `/stc action` | ✅ Working | Adds action steps |
+| `/dashboard` | ✅ Enhanced | Improved error feedback |
+
+### Dashboard Improvements (v1.1.0)
+
+1. **Prerequisite Checks**: Dashboard now checks for loaded chart before prompting
+2. **Dynamic Menu Hints**: Menu shows availability status for each operation
+3. **Clear Error Messages**: When no chart is loaded, user gets actionable guidance
+
+### Prerequisites for Dashboard Operations
+
+For observation/action features to work:
+
+1. **Workspace must be configured**: Run `/stc config add <owner/repo> <local_path>`
+2. **Miadi Platform must be running**: API server on port 3335
+3. **Chart must be initialized**: Run `/stc sync` or the dashboard will create one
+
+### Test Coverage
+
+- Unit tests: 119 tests passing
+- Dashboard data adapter tests: Comprehensive coverage
+- Integration tests: API workflow validated
+
+---
+
+## Architecture Notes
+
+The STC system uses a layered architecture:
+
+```
+Dashboard TUI (dashboard.ts)
+    ↓
+Workspace Client (stc/workspace-client.ts)
+    ↓ HTTP
+Miadi Platform API (/api/stc/*)
+    ↓
+Chart Manager (lib/stc/chart-manager.ts)
+    ↓
+Local Filesystem (.coaia/*.jsonl)
+```
+
+Charts are stored in `.coaia/` directory as JSONL files with entity/relation records.

package/rispecs/ava-langstack/inquiry-routing-upgrade.spec.md

@@ -0,0 +1,119 @@
+# SPEC — mia-code Inquiry Routing Upgrade
+
+> Consumer: mia-code (`/a/src/mia-code`)
+> Upstream: `ava-langchain-inquiry-routing@0.1.0`, `ava-langgraph-inquiry-routing-engine@0.1.0`
+> Related: `/a/src/mia-code/KINSHIP.md` (LangGraph/LangChain integration section)
+
+## Desired Outcome
+
+mia-code's PDE workflow gains structured inquiry routing: after `pde_decompose` produces a `DecompositionResult`, the result flows through the `InquiryRoutingGraph` to produce classified, relationally-grounded inquiries before agent execution. The `miaco decompose` command outputs both the PDE decomposition and the inquiry routing report. `ceremony_hold` pauses the agent when relational accountability requires human presence.
+
+## Current Reality
+
+- mia-code calls `pde_decompose` → gets `DecompositionResult` → works through action stack manually
+- No structured inquiry generation from PDE output
+- No routing classification — the agent decides per-turn where to search
+- `KINSHIP.md` documents the intent to integrate ava-langchainjs/ava-langgraphjs libraries but inquiry routing is not yet wired
+
+### Existing PDE Types (from `@iaip/mcp-pde`)
+```typescript
+import type { DecompositionResult, StoredDecomposition } from '@iaip/mcp-pde';
+```
+
+### Integration Points (from KINSHIP.md)
+- `src/commands.ts` — `decompose` command (wraps PDE MCP tools)
+- `src/mcp/` — MCP tool generation
+- `src/sessionStore.ts` — session metadata linking
+
+## Structural Tension
+
+mia-code has PDE *decomposition* but not PDE *inquiry routing*. The agent decomposes prompts into structure but then executes without systematic inquiry classification or relational validation. The tension between structured decomposition and ad-hoc execution resolves through the inquiry-routing pipeline.
+
+## Type Mapping: PDE → Inquiry
+
+| PDE Type (`@iaip/mcp-pde`) | Inquiry Type (`ava-langchain-inquiry-routing`) |
+|----|-----|
+| `DecompositionResult` | Input to `InquiryGenerator.generate()` |
+| `DecompositionResult.directions` | Maps to `InquiryBatch.{east,south,west,north}` |
+| `DecompositionResult.ambiguities` | Each `AmbiguityFlag` → `Inquiry` in WEST bucket |
+| `DecompositionResult.context.assumptions` | Each assumption string → `Inquiry` in SOUTH bucket |
+| `StoredDecomposition` | Parallel: `StoredInquiryRoutingSession` |
+| `DecompositionResult.id` | → `Inquiry.pde_id` (traceability link) |
+
+## Architecture
+
+### 1. Add Dependencies
+
+```json
+{
+  "dependencies": {
+    "ava-langchain-inquiry-routing": ">=0.1.0",
+    "ava-langgraph-inquiry-routing-engine": ">=0.1.0"
+  }
+}
+```
+
+### 2. Extend `decompose` Command
+
+In `src/commands.ts`, after PDE decomposition:
+
+```typescript
+import { InquiryRoutingGraph } from "ava-langgraph-inquiry-routing-engine";
+
+// After: const pde = await decompose(prompt);
+const routingGraph = new InquiryRoutingGraph({ enforceCeremony: true });
+const routingState = await routingGraph.invoke(pde.decomposition);
+
+if (routingState.status === "ceremony_hold") {
+  // Surface to user: relational review required
+  presentCeremonyHold(routingState.relationalValidation);
+  return;
+}
+
+// Use dispatch payloads for directed search
+for (const payload of routingState.dispatchPayloads ?? []) {
+  await executeDispatch(payload);
+}
+```
+
+### 3. Session Store Integration
+
+Link inquiry routing sessions to PDE sessions in `src/sessionStore.ts`:
+
+```typescript
+import type { StoredInquiryRoutingSession } from "ava-langgraph-inquiry-routing-engine";
+
+interface SessionMetadata {
+  // ... existing fields
+  inquiryRoutingSession?: StoredInquiryRoutingSession;
+}
+```
+
+### 4. MCP Tool Extension
+
+In `src/mcp/`, expose inquiry routing as MCP tools:
+- `inquiry_route` — run inquiry routing on an existing PDE decomposition
+- `inquiry_status` — check routing state for a session
+
+### 5. `.mw/` Architecture Integration
+
+Per KINSHIP.md convergence role:
+- `miaco decompose` → writes PDE to `.mw/east/`
+- **New:** inquiry routing results write to `.mw/south/` (routed inquiries as JSONL)
+- Dispatch payloads flow to `.mw/north/` (action-ready queries)
+
+## Implementation Notes
+
+- `enforceCeremony: true` is mandatory in mia-code context — the agent must not bypass relational gates
+- Inquiry routing runs synchronously via `InquiryRoutingGraph` (no LangGraph runtime needed)
+- For LangGraph integration: use `createInquiryRoutingStateGraph()` as subgraph in larger pipelines
+- Markdown report from `InquiryFormatter.toMarkdown()` can be written to `.pde/<uuid>-inquiries.md` alongside existing PDE markdown
+
+## RISE Compliance
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| **R**everse-engineer | ✅ Done | mia-code PDE flow analyzed, KINSHIP.md integration points identified |
+| **I**ntent-extract | ✅ Done | Intent: add structured inquiry routing to mia-code's PDE workflow with ceremony gating |
+| **S**pecify | ✅ This document | Type mapping, command extension, session store integration, MCP tools |
+| **E**xport | ⏳ Not started | Requires implementation in mia-code |

package/rispecs/borrowed_from_opencode/001-client-server-architecture.rispec.md

@@ -0,0 +1,98 @@
+# RISE-001: Client-Server Architecture
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/001-client-server-architecture.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to separate agent execution from user interface rendering. Users achieve location-independent agent driving by connecting lightweight clients to a persistent server that manages sessions, tool execution, and agent orchestration. A developer runs the agent on a powerful workstation and drives it from a phone, a tablet, or a second terminal — the interface becomes a window, not a cage.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code runs as a monolithic CLI process — UI rendering, agent execution, session management, and I/O all share one process
+- The TUI (Commander.js + enquirer + ora + chalk) is tightly coupled to the agent loop in `cli.ts` and `commands.ts`
+- Closing the terminal kills the agent mid-operation; there is no way to reconnect
+- Remote access requires SSH into the machine and attaching to a tmux/screen session
+- Only one view into a running session is possible at a time
+- Session state lives in `~/.mia-code-sessions.json`, readable only from the local filesystem
+
+**Desired State:**
+- The mia-code server runs as a long-lived process that accepts connections from any client
+- Agent logic (Gemini/Claude headless execution, unifier interpretation, session persistence) lives entirely server-side
+- Clients are thin renderers: they display events, capture input, and send it to the server
+- Multiple clients can observe the same session simultaneously (pair programming, monitoring)
+- The server survives client disconnection — work continues, and a new client reconnects to live output
+- Headless operation (no client at all) is a natural subset — the server executes prompts from scripts or CI
+
+## Desired Outcome Definition
+
+A running `mia-code serve` process exposes an HTTP API on localhost. A `mia-code connect` client (or any HTTP-capable program) attaches to it. The server manages the full agent lifecycle. Clients come and go without disrupting agent work.
+
+## Natural Language Functional Description
+
+### Server Component
+
+The server starts via `mia-code serve [--port PORT] [--password SECRET]`. It binds to `127.0.0.1` on the specified port (default: `7880`). If a password is provided, every client request must include it as a Bearer token in the Authorization header.
+
+The server exposes these REST endpoints:
+
+- `GET /sessions` — list all sessions with metadata (id, project root, timestamps, model)
+- `POST /sessions` — create a new session, returns session ID
+- `GET /sessions/:id` — get session details including message history
+- `DELETE /sessions/:id` — archive or remove a session
+- `POST /sessions/:id/messages` — send a user prompt to the agent; returns immediately with a message ID
+- `GET /sessions/:id/messages` — retrieve message history with pagination
+- `GET /sessions/:id/events` — SSE (Server-Sent Events) stream for real-time updates
+- `GET /config` — current configuration
+- `PUT /config` — update configuration values
+- `GET /health` — server status, uptime, active sessions count
+
+The SSE event stream (`/sessions/:id/events`) emits typed events:
+- `message.start` — agent begins processing
+- `message.chunk` — streaming text chunk from agent
+- `message.complete` — agent finished, includes full response
+- `tool.start` — tool execution begins (name, parameters)
+- `tool.complete` — tool finished (result, duration)
+- `ceremonial.output` — the 🧠 Mia / 🌸 Miette dual-perspective interpretation
+- `error` — any error during processing
+
+Each event is a JSON object with `type`, `timestamp`, `sessionId`, and a typed `payload`.
+
+### Client Component
+
+The default TUI client starts via `mia-code connect [--server URL] [--password SECRET]`. It renders the same chalk/ora interface users already know, but sources data from the server instead of running agents locally. The client:
+
+1. Connects to the server's SSE endpoint for the active session
+2. Renders incoming events using existing `formatting.ts` logic
+3. Captures user input via `multiline-input.ts` and POSTs to `/sessions/:id/messages`
+4. Handles reconnection automatically if the connection drops
+
+### Session Ownership
+
+The server owns session state. The `sessionStore.ts` module moves from file I/O to an internal server-side store. Clients never read `~/.mia-code-sessions.json` directly — they query the API.
+
+### Authentication
+
+When `--password` is set, the server validates every request. Unauthorized requests receive `401`. This is lightweight security for localhost use — not intended for public exposure.
+
+## Supporting Structures
+
+- **Event Bus (RISE-002)** provides the internal pub/sub that the SSE stream exposes externally
+- **Instance State (RISE-003)** ensures server-side state is scoped per project directory
+- **Structured Logging (RISE-007)** gives the server observable request/response logging
+- **Lazy Initialization (RISE-008)** defers agent process spawning until the first prompt arrives
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Remote Driving from Mobile:**
+A developer starts `mia-code serve --port 7880 --password hunter2` on their workstation. They SSH-tunnel port 7880 to their phone. A simple web client (or curl) sends prompts and receives SSE events. The agent runs with full CPU/memory of the workstation while the developer lounges on the couch.
+
+**Scenario 2 — Headless CI Integration:**
+A CI pipeline calls `curl -X POST http://localhost:7880/sessions -d '{"projectRoot":"/app"}'` to create a session, then sends a prompt asking the agent to review a PR diff. The response streams back as SSE events. No TUI, no terminal, no human in the loop.
+
+**Scenario 3 — Pair Programming Observer:**
+Two developers connect to the same session. Developer A types prompts. Developer B watches the SSE stream in their own terminal. Both see the same agent output in real-time. Developer B can also send messages — the server queues them.
+
+**Scenario 4 — Surviving Disconnection:**
+A developer starts a long refactoring prompt, then their laptop sleeps. The server continues executing. When the laptop wakes, `mia-code connect` reconnects and replays missed events from the message history endpoint.