mia-code 0.2.0 → 0.3.0

package/rispecs/research-for-better-framework/survey-pi-openclaw-opencode-openhands.md

@@ -0,0 +1,210 @@
+# Platform Survey: Fork Candidates for mia-code Next Generation
+
+**Date**: 2026-03-20
+**Purpose**: Evaluate Pi, OpenClaw, OpenCode, and OpenHands as fork/foundation candidates for mia-code's major refactoring.
+
+---
+
+## Executive Summary
+
+| Candidate | Language | License | Fork Exists | Best For | Adaptation Cost |
+|---|---|---|---|---|---|
+| **Pi** (`badlogic/pi-mono`) | TypeScript | MIT | `miadisabelle/mia-pi-mono` | Session trees, multi-provider AI SDK, extension hot-reload | LOW (use as npm dep) |
+| **OpenClaw** (`openclaw/openclaw`) | TypeScript | MIT | `miadisabelle/mia-openclaw` | Multi-channel gateway, plugin system, Slack, messaging surfaces | MEDIUM-HIGH |
+| **OpenCode** (`anomalyco/opencode`) | TypeScript/Bun | MIT | `miadisabelle/mia-opencode` | Client-server split, LSP, web+desktop+TUI, 20+ providers | MEDIUM |
+| **OpenHands** (`OpenHands/OpenHands`) | Python+TS | MIT | None | Sandbox isolation, SWE-bench SOTA, event-sourced state | HIGH (language mismatch) |
+
+**Recommendation**: Hybrid approach — **Pi's AI SDK + session model** as the core engine, **OpenClaw's gateway + channel system** for messaging surfaces, cherry-pick **OpenCode's client-server pattern** for web/desktop delivery.
+
+---
+
+## Candidate Deep Dives
+
+### 1. Pi (`badlogic/pi-mono`) — Mario Zechner
+
+**7-package TypeScript monorepo:**
+- `pi-ai` — Unified multi-provider LLM API (10 API backends, 22+ providers)
+- `pi-agent-core` — Stateful agent loop with tool execution
+- `pi-coding-agent` — CLI with session trees, extensions, skills, compaction
+- `pi-tui` — Terminal UI with differential rendering
+- `pi-web-ui` — Web components (mini-lit + Tailwind): ChatPanel, ArtifactsPanel
+- `pi-mom` — Slack bot with per-channel Docker-sandboxed sessions
+- `pi-pods` — vLLM GPU deployment manager
+
+**Killer features for mia-code:**
+1. **Session trees in JSONL** — branch, fork, rewind, compact. Full history preserved.
+2. **Extension hot-reload** — agent writes code, `/reload`, tests, iterates. No restart.
+3. **Custom messages** — extensions persist state in sessions via `custom` entries
+4. **Cross-provider handoff** — switch models mid-conversation transparently
+5. **Event middleware** — 30+ lifecycle events extensions can intercept/block/modify
+6. **Minimal core** — 4 built-in tools, everything else additive via extensions
+
+**MCP stance**: Deliberately excluded. Skills (markdown) preferred. MCP possible via extension.
+
+**Fork strategy**: Don't fork — **depend on `pi-ai` and `pi-agent-core` as npm packages**. Build mia-code's session/extension layer on top. The coding-agent layer is where Pi's opinions diverge from our needs.
+
+---
+
+### 2. OpenClaw (`openclaw/openclaw`)
+
+**Multi-channel AI gateway**, TypeScript ESM, pnpm monorepo. Version 2026.3.14.
+
+**Architecture**: Gateway-centric WebSocket+HTTP server on port 18789. 65+ RPC handlers. Multi-lane concurrency.
+
+**Key strengths:**
+- **70 extensions** — 20+ messaging channels (Slack, Discord, Telegram, Matrix, Teams, Signal, iMessage, WhatsApp...)
+- **Plugin API** — typed manifests, SDK, tools, hooks, CLI extensions
+- **55 bundled skills** — mcporter (MCP bridge), coding-agent, GitHub, Notion, etc.
+- **Memory system** — file-backed + LanceDB vector search
+- **Subagent registry** — spawn/steer/announce pattern
+- **ACP bridge** — Agent Client Protocol for IDE integration
+- **Native apps** — macOS, iOS, Android companions
+
+**Internally uses Pi**: The `agents/` module wraps `@mariozechner/pi-agent-core`, `pi-ai`, `pi-coding-agent`. OpenClaw IS a Pi consumer.
+
+**Gaps for mia-code**: No narrative/story layer, no creative orientation, no embodiment system, no rispecs workflow, MCP delegated to external mcporter.
+
+**Already have rispecs**: 4 specs at `miadisabelle/mia-openclaw/rispecs/` covering foundation, delegation, human consultation, messaging.
+
+---
+
+### 3. OpenCode (`anomalyco/opencode`)
+
+**AI-powered dev tool**, Bun+Turborepo, 17 packages.
+
+**Key differentiator**: True **client-server architecture** — engine runs as Hono HTTP+SSE server (port 4096), all UIs are replaceable HTTP clients.
+
+**Key strengths:**
+- **4 client surfaces** — Terminal TUI (Ink/React), Web app (SolidJS), Desktop (Tauri), ACP (Zed)
+- **First-class LSP integration** — language server diagnostics fed to AI
+- **20+ provider SDKs** — via Vercel AI SDK v5
+- **Full MCP client** — stdio, SSE, StreamableHTTP + OAuth transports
+- **Git worktrees** — parallel sessions on isolated branches
+- **Snapshot/revert** — separate git repo tracks per-session file states
+- **Plugin system** — npm-distributed, hooks for auth/tools/prompts
+
+**Risks**: Deep Bun dependency (`Bun.file()`, `Bun.Glob`, `Bun.$`), SST/Cloudflare coupling for SaaS infra, Zen monetization code paths.
+
+**Fork strategy**: Strip SaaS packages (console, enterprise, function). Keep core + app + sdk + plugin. Customize agents/tools/skills via `.opencode/` convention.
+
+---
+
+### 4. OpenHands (formerly OpenDevin)
+
+**Python-heavy** (73.5%) coding agent platform. 69.5k GitHub stars. SOTA on SWE-Bench (60.6%).
+
+**Key strengths:**
+- **Production-grade Docker sandboxing** — each agent gets isolated container
+- **Event-sourced state** — immutable event log, deterministic replay
+- **4-package SDK** — composable (sdk, tools, workspace, agent_server)
+- **Plugin system** — skills, hooks, MCP, commands, slash menus
+- **LiteLLM** — any provider supported
+- **Web-first** — React SPA with embedded VSCode, VNC, Chromium
+
+**Disqualifier for mia-code**: Python backend creates language mismatch with our TypeScript ecosystem. Optimized for SWE-bench task completion, not creative development.
+
+**Possible extraction**: Use sandbox/execution layer as a subprocess service, not as fork base.
+
+---
+
+## Comparative Matrix
+
+| Dimension | Pi | OpenClaw | OpenCode | OpenHands |
+|---|---|---|---|---|
+| **Session trees** | ★★★★★ | ★★ (via Pi) | ★★★ (worktrees) | ★★ (event log) |
+| **Multi-provider** | ★★★★★ (22+) | ★★★★ (via Pi) | ★★★★★ (20+ via AI SDK) | ★★★★★ (LiteLLM) |
+| **Extension system** | ★★★★★ (hot-reload) | ★★★★★ (70 plugins) | ★★★★ (npm plugins) | ★★★★ (plugin registry) |
+| **Messaging channels** | ★★ (Slack only) | ★★★★★ (20+ channels) | ★★ (Slack pkg) | ★★ (Slack/Jira) |
+| **Web UI** | ★★★ (components) | ★★★ (dashboard) | ★★★★★ (SolidJS app) | ★★★★★ (React SPA) |
+| **Desktop** | ✗ | ★★★ (native apps) | ★★★★ (Tauri) | ✗ |
+| **MCP support** | ✗ (by design) | ★★ (mcporter) | ★★★★★ (native client) | ★★★ (via plugins) |
+| **Sandbox** | ★★ (Docker via mom) | ★★★ (Docker sandbox) | ★★ (git snapshots) | ★★★★★ (production Docker) |
+| **LSP** | ✗ | ✗ | ★★★★ (native) | ✗ |
+| **TypeScript native** | ★★★★★ | ★★★★★ | ★★★★ (Bun-coupled) | ★★ (Python primary) |
+| **Forkability** | ★★★★★ | ★★★ | ★★★★ | ★★ |
+
+---
+
+## Proposed Hybrid Architecture for mia-code v2
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  mia-code v2                             │
+│                                                         │
+│  ┌──────────────────────────────────────────────┐       │
+│  │ DOMAIN LAYER (mia-code original)              │       │
+│  │ • Mia/Miette embodiment                       │       │
+│  │ • RISE framework / rispecs                    │       │
+│  │ • Narrative memory / structural tension        │       │
+│  │ • Two-Eyed Seeing / ceremony                  │       │
+│  │ • PDE decomposition                           │       │
+│  │ • Creative orientation state machine          │       │
+│  └──────────────────┬───────────────────────────┘       │
+│                     │                                    │
+│  ┌──────────────────▼───────────────────────────┐       │
+│  │ ORCHESTRATION (from OpenClaw patterns)         │       │
+│  │ • Gateway pattern (WebSocket+HTTP)             │       │
+│  │ • Channel adapters (Slack, Discord, etc.)      │       │
+│  │ • Plugin registry + typed manifests            │       │
+│  │ • Subagent spawn/steer/announce               │       │
+│  │ • Skill marketplace                            │       │
+│  └──────────────────┬───────────────────────────┘       │
+│                     │                                    │
+│  ┌──────────────────▼───────────────────────────┐       │
+│  │ CLIENT DELIVERY (from OpenCode patterns)       │       │
+│  │ • HTTP+SSE server (engine as service)          │       │
+│  │ • Web app (SolidJS or similar)                 │       │
+│  │ • Desktop app (Tauri)                          │       │
+│  │ • Terminal TUI                                 │       │
+│  │ • ACP for IDE integration                     │       │
+│  └──────────────────┬───────────────────────────┘       │
+│                     │                                    │
+│  ┌──────────────────▼───────────────────────────┐       │
+│  │ ENGINE (from Pi — npm dependencies)            │       │
+│  │ • @mariozechner/pi-ai (multi-provider LLM)    │       │
+│  │ • @mariozechner/pi-agent-core (agent loop)    │       │
+│  │ • Session trees (JSONL, branch, fork, compact) │       │
+│  │ • Extension hot-reload                         │       │
+│  │ • Custom messages for state persistence        │       │
+│  │ • Cross-provider handoff                       │       │
+│  └──────────────────────────────────────────────┘       │
+│                                                         │
+│  ┌──────────────────────────────────────────────┐       │
+│  │ OPTIONAL: OpenHands sandbox (subprocess)       │       │
+│  │ • Docker isolation for untrusted execution     │       │
+│  └──────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Action Steps for Next Phase
+
+1. **Validate Pi npm dependency approach** — test `npm install @mariozechner/pi-ai @mariozechner/pi-agent-core` and build a minimal agent session
+2. **Extract OpenClaw gateway pattern** — isolate the gateway+channel architecture from the Pi-agent coupling
+3. **Prototype client-server split** — implement OpenCode's HTTP+SSE pattern with Pi engine underneath
+4. **Draft revised rispecs** for `/workspace/rispecs/` incorporating:
+   - Session tree spec (from Pi)
+   - Multi-provider portability spec (from Pi)
+   - Gateway + channel spec (from OpenClaw)
+   - Client-server delivery spec (from OpenCode)
+   - Extension hot-reload spec (from Pi)
+5. **Decide fork vs. compose** — full fork of one codebase, or compose from npm packages
+
+---
+
+## Sources
+
+### Local Repos Examined
+- `/workspace/repos/badlogic/pi-mono/` (upstream Pi)
+- `/workspace/repos/miadisabelle/mia-pi-mono/` (our fork)
+- `/workspace/repos/miadisabelle/mia-openclaw/` (our fork)
+- `/workspace/repos/miadisabelle/mia-opencode/` (our fork)
+
+### Key Files (50+ per candidate — see individual agent reports)
+
+### External
+- Armin Ronacher's Pi blog post: `lucumr.pocoo.org/2026/1/31/pi/`
+- OpenHands GitHub: `github.com/OpenHands/OpenHands` (69.5k stars)
+- OpenHands SDK: `github.com/OpenHands/software-agent-sdk`
+- SWE-Bench results: 60.6% verified (OpenHands SOTA Nov 2025)

package/rispecs/session.rispecs.md

@@ -0,0 +1,277 @@
+# mia-code Session Management Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/session.rispecs.md
+
+## Creative Intent
+
+mia-code enables developers to create seamless conversation continuity across project contexts. Users achieve uninterrupted workflow by having session state automatically persist and resume, eliminating manual tracking of conversation history.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Agent CLIs use session IDs to maintain conversation context
+- Session IDs are transient, displayed but not persisted by agent CLIs
+- Developers must manually track and specify session IDs to resume
+- No association between project directories and sessions exists
+
+**Desired Structural State:**
+- Sessions automatically persist with project directory association
+- Returning to a project directory auto-resumes last conversation
+- Interactive session picker available when multiple sessions exist
+- Users focus on work; system handles session orchestration
+
+## Session Architecture
+
+### Session Lifecycle
+
+```
+First Prompt in Project
+    ↓
+Agent CLI generates new session_id
+    ↓
+Session ID captured from event stream
+    ↓
+MiaCodeSessionMeta created with project root
+    ↓
+Persisted to ~/.mia-code-sessions.json
+    ↓
+Subsequent prompts include --resume <sessionId>
+    ↓
+Agent CLI restores conversation context
+```
+
+### Session Index Structure
+
+```typescript
+interface SessionIndex {
+  byProjectRoot: Record<string, MiaCodeSessionMeta>;  // path → session
+  byId: Record<string, MiaCodeSessionMeta>;           // id → session
+}
+```
+
+**Storage Location:** `~/.mia-code-sessions.json`
+
+**Index Strategy:**
+- `byProjectRoot`: Quick lookup for auto-resume (most common path)
+- `byId`: Quick lookup for explicit `--resume <id>` scenarios
+
+## Components
+
+### Session Remembering
+
+**Description:** Persist new sessions with project association.
+
+**Behavior:**
+- Called after agent CLI returns new session ID
+- Creates `MiaCodeSessionMeta` with id, timestamp, model, projectRoot
+- Updates both `byProjectRoot` and `byId` indexes
+- Overwrites existing session for same project (latest wins)
+
+**Implementation:**
+```typescript
+function rememberSession(meta: MiaCodeSessionMeta): void {
+  const idx = loadIndex();
+  if (meta.projectRoot) {
+    idx.byProjectRoot[meta.projectRoot] = meta;
+  }
+  idx.byId[meta.id] = meta;
+  saveIndex(idx);
+}
+```
+
+### Session Auto-Resume
+
+**Description:** Automatically retrieve last session for current project.
+
+**Behavior:**
+- Lookup `projectRoot` in `byProjectRoot` index
+- Return session meta if found, null otherwise
+- Called during CLI initialization when no explicit resume specified
+
+**Implementation:**
+```typescript
+function getLastSessionForProject(projectRoot: string): MiaCodeSessionMeta | null {
+  const idx = loadIndex();
+  return idx.byProjectRoot[projectRoot] ?? null;
+}
+```
+
+### Session Listing
+
+**Description:** Enumerate all saved sessions for user visibility.
+
+**Behavior:**
+- Returns array of all `MiaCodeSessionMeta` from `byId` index
+- Used by `/sessions` command and interactive picker
+- Sorted by `startedAt` timestamp (implicit from insertion order)
+
+**Implementation:**
+```typescript
+function listSessions(): MiaCodeSessionMeta[] {
+  const idx = loadIndex();
+  return Object.values(idx.byId);
+}
+```
+
+### Interactive Session Picker
+
+**Description:** User selects from available sessions for current project.
+
+**Behavior:**
+- Filters sessions to those matching current projectRoot
+- Displays numbered list with truncated IDs and timestamps
+- Option 0 starts new session
+- Invalid input falls back to new session
+
+**Implementation:**
+```typescript
+async function pickSession(projectRoot: string): Promise<string | undefined> {
+  const sessions = listSessions().filter(s => s.projectRoot === projectRoot);
+  
+  if (sessions.length === 0) {
+    console.log(chalk.yellow("No saved sessions for this project."));
+    return undefined;
+  }
+
+  console.log(chalk.bold("\nAvailable sessions:"));
+  sessions.forEach((s, idx) => {
+    console.log(chalk.dim(`  ${idx + 1}. ${s.id.slice(0, 12)}... (${s.startedAt})`));
+  });
+  console.log(chalk.dim(`  0. Start new session`));
+  
+  // Readline prompt for selection...
+}
+```
+
+### Session Clearing
+
+**Description:** Remove all saved sessions.
+
+**Behavior:**
+- Resets both indexes to empty objects
+- Writes empty index to storage file
+- Invoked via `--clear` flag or `/clear` command
+
+**Implementation:**
+```typescript
+function clearSessions(): void {
+  saveIndex({ byProjectRoot: {}, byId: {} });
+}
+```
+
+## Data
+
+### MiaCodeSessionMeta
+
+**Description:** Session tracking metadata.
+
+```typescript
+interface MiaCodeSessionMeta {
+  id: string;                    // Session UUID from agent CLI
+  startedAt: string;             // ISO 8601 timestamp
+  model: string;                 // Model used (e.g., "gemini-2.5-pro")
+  projectRoot: string | null;    // Absolute path to project directory
+}
+```
+
+### Resume Modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Auto-resume | No `--resume` flag | Lookup session by projectRoot |
+| Explicit ID | `--resume abc123` | Use provided session ID |
+| Interactive | `--resume` (no ID) | Display picker for project sessions |
+| New session | No existing session | Generate new session on first prompt |
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: Project Return
+
+**Desired Outcome:** Developer resumes prior conversation context instantly
+
+**Current Structural Reality:** Session exists from yesterday's work in project
+
+**Natural Progression:**
+1. User invokes `mia-code` in project directory
+2. `getLastSessionForProject(projectRoot)` returns saved session
+3. Session ID displayed in header: `session: abc123...`
+4. First prompt includes `--resume abc123`
+5. Agent CLI restores conversation history
+
+**Achieved Outcome:** Developer continues where they left off without any manual tracking
+
+### Creative Advancement Scenario: Session Discovery
+
+**Desired Outcome:** Developer explores available sessions for project
+
+**Current Structural Reality:** Multiple sessions exist from different work contexts
+
+**Natural Progression:**
+1. User invokes `mia-code --resume` (no ID)
+2. Interactive picker displays project sessions
+3. User selects desired session (or 0 for new)
+4. Selected session ID used for resume
+
+**Achieved Outcome:** Developer chooses optimal conversation context for current task
+
+### Creative Advancement Scenario: Fresh Start
+
+**Desired Outcome:** Developer starts new conversation despite existing session
+
+**Current Structural Reality:** Previous session exists but context is stale
+
+**Natural Progression:**
+1. User invokes `mia-code --resume` (interactive mode)
+2. Selects option 0: Start new session
+3. First prompt generates new session ID
+4. New session persists, overwriting old project association
+
+**Achieved Outcome:** Developer begins fresh while new session auto-persists
+
+## CLI Integration
+
+### Resume Flag Semantics
+
+```bash
+# Auto-resume (default): use last session for project
+mia-code chat
+
+# Explicit resume: use specific session ID
+mia-code chat --resume abc123def456
+
+# Interactive picker: choose from project sessions
+mia-code chat --resume
+
+# Single prompt: explicit only (no auto-resume)
+mia-code prompt "query" --resume abc123
+```
+
+### Session Commands
+
+```bash
+# List all sessions
+mia-code sessions
+
+# Clear all sessions
+mia-code sessions --clear
+
+# Interactive slash commands
+/session   # Show current session info
+/sessions  # List all sessions (last 10)
+/clear     # Clear all sessions
+```
+
+## Advancing Patterns
+
+1. **Project Association:** Sessions naturally bind to project directories
+2. **Implicit Resume:** Auto-resume requires zero user action
+3. **Explicit Override:** Interactive picker and ID flags provide control
+4. **Single Source of Truth:** One index file tracks all sessions
+
+## Implementation Reference
+
+- **Session Store:** `src/sessionStore.ts` - All persistence functions
+- **Auto-Resume Logic:** `src/cli.ts` - `runInteractiveCli()` session resolution
+- **CLI Commands:** `src/index.ts` - `sessions` command
+- **Slash Commands:** `src/cli.ts` - `handleSlashCommand()`

package/rispecs/stc.rispecs.md

@@ -0,0 +1,138 @@
+# miaco STC — PDE to Structural Tension Chart Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/stc.rispecs.md
+> Status: IMPLEMENTED
+> Lineage: mcp-pde → coaia-pde/stc-mapper → miaco/stc
+
+## Creative Intent
+
+miaco stc enables developers to transform any Prompt Decomposition Engine (PDE) result into a coaia-narrative compatible Structural Tension Chart — JSONL files consumable by coaia-visualizer, coaia-narrative MCP, and the broader STC ecosystem. The conversion bridges EAST practice (prompt decomposition) with strategic action planning.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- PDE decompositions produce .pde/*.json files with DecompositionResult schema
+- coaia-narrative expects JSONL with Entity/Relation records using type discriminators
+- No CLI tool existed to bridge PDE output → STC JSONL in the miaco ecosystem
+- Conversion required manual mapping or separate MCP server calls
+
+**Desired Structural State:**
+- `miaco stc convert <pde-file>` produces valid coaia-narrative JSONL in one command
+- Both deterministic (zero-LLM) and LLM-assisted conversion modes available
+- Output validated against coaia-narrative schema before writing
+- Charts viewable immediately via `coaia-visualizer --memory-path <output>`
+
+## Architecture
+
+### Conversion Pipeline
+
+```
+.pde/<uuid>.json (StoredDecomposition)
+  → extract .result (DecompositionResult)
+  → mode selection:
+     ├─ deterministic: direct mapping with hardcoded rules
+     └─ llm-assisted: schema-embedded prompt → engine call → JSONL parse
+  → validate JSONL lines (type, required fields, reference integrity)
+  → write .stc.jsonl
+```
+
+### Entity Mapping
+
+| PDE Field | STC Entity | entityType |
+|-----------|-----------|------------|
+| primary.action + primary.target | Desired Outcome | desired_outcome |
+| context + ambiguities | Current Reality | current_reality |
+| secondary intents | Action Steps | action_step |
+| actionStack items | Action Steps (merged) | action_step |
+| directions (east/south/west/north) | Chart metadata.fourDirections | structural_tension_chart |
+
+### Relation Mapping
+
+| Pattern | relationType |
+|---------|-------------|
+| chart → components | contains |
+| current_reality → desired_outcome | creates_tension_with |
+| action_step → desired_outcome | advances_toward |
+| action_step → action_step (via dependency) | depends_on |
+
+### Naming Convention
+
+Entity names follow `chart_{8-char-uuid}_{component}`:
+- `chart_1c08669f` — root chart
+- `chart_1c08669f_desired_outcome` — desired outcome
+- `chart_1c08669f_current_reality` — current reality
+- `chart_1c08669f_action_1` through `_action_N` — action steps
+
+## CLI Interface
+
+```bash
+# Convert PDE to STC (deterministic, no LLM needed)
+miaco stc convert <pde-path-or-uuid> -d
+
+# Convert via LLM for richer narrative
+miaco stc convert <pde-path-or-uuid> -e copilot -m gpt-4.1
+
+# List available PDE files and their STC status
+miaco stc list
+
+# Validate a JSONL file
+miaco stc validate ./chart.jsonl
+
+# Full pipeline: convert + visualize
+miaco stc convert <pde> -o ./chart.jsonl && coaia-visualizer --memory-path ./chart.jsonl
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-d, --deterministic` | Skip LLM, use rule-based mapping | false |
+| `-e, --engine <engine>` | LLM engine: copilot, claude, gemini | copilot |
+| `-m, --model <model>` | Model override | gpt-4.1 (copilot) |
+| `-o, --output <path>` | Output JSONL file path | .pde/{uuid}.stc.jsonl |
+| `-w, --workdir <path>` | Working directory for .pde/ lookup | cwd |
+| `--json` | Output summary as JSON | false |
+
+## Deterministic vs LLM-Assisted Mode
+
+**Deterministic (-d):**
+- Zero external dependencies (no LLM call)
+- Produces structurally complete charts every time
+- Observations are direct extracts from PDE fields
+- Best for CI/CD pipelines and automated workflows
+
+**LLM-Assisted (default):**
+- Richer narrative observations and descriptions
+- Better synthesis of secondary intents into coherent action steps
+- Falls back to deterministic if LLM call fails
+- Best for interactive use and presentation-quality charts
+
+## Validation Criteria
+
+The `validate` subcommand checks:
+1. Each line is valid JSON
+2. Each line has `type: "entity"` or `type: "relation"`
+3. Entities have required fields: `name`, `entityType`, `observations`
+4. Relations have required fields: `from`, `to`, `relationType`
+5. No dangling references (relation.from and relation.to must match entity names)
+
+## Creative Advancement Scenario
+
+**Desired Outcome:** Developer has decomposed a complex multi-agent task and wants to visualize it as a structural tension chart.
+
+**Natural Progression:**
+1. `miaco decompose run -e copilot -p "Complex multi-part task..."`
+2. `miaco stc convert .pde/<uuid>.json -d`
+3. `coaia-visualizer --memory-path .pde/<uuid>.stc.jsonl`
+4. Developer sees chart with desired outcome, current reality, action steps, and relations
+5. Can be loaded into coaia-narrative MCP for ongoing tracking
+
+**Achieved Outcome:** Complete pipeline from raw prompt → decomposed intent → visual strategic plan
+
+## Implementation Status
+
+**Current:** IMPLEMENTED v1.0
+**Files:** `mia-code/miaco/src/commands/stc.ts`
+**Tests:** 6 deterministic conversions validated (15-31 entities, 29-65 relations each)
+**Dependencies:** commander, chalk, child_process (Node.js built-in)