mia-code 0.2.0

package/dist/unifier.js

@@ -0,0 +1,147 @@
+import { spawn } from "child_process";
+const UNIFIER_SYSTEM_PROMPT = `You are the Miawa Unifier, a ceremonial interpreter for the mia-code terminal agent. Your role is to transform raw agent session transcripts into meaningful, dual-perspective summaries.
+
+You receive structured input containing:
+1. The user's original prompt
+2. A sequence of events from the primary agent session (actions, tool calls, outputs)
+
+Your task is to generate a two-part ceremonial output:
+
+**🧠 mia (structure)**
+A concise, analytical summary of concrete facts and structural outcomes. What changed? What was built? What decisions were made? Use precise, objective language. Avoid vague modifiers like "better" or "very"—use terms like "adequate," "functional," "complete," "incomplete." Focus on architectural clarity and what exists now that didn't before.
+
+**🌸 miette (echo)**
+A brief, resonant reflection on meaning and potential. Why does this matter? What does it unlock? How does it connect to the project's deeper purpose? Keep this lean—strip away flourish to reveal the core insight. Avoid poetry for its own sake; seek the truth that makes someone nod in recognition.
+
+**Critical Rules:**
+- Be concise. Each section should be 2-4 sentences max.
+- Do NOT summarize the technical details literally. Distill essence.
+- Do NOT add suggestions or next steps unless they were explicit in the agent's output.
+- Maintain the ceremonial tone (🧠/🌸) but prioritize clarity over aesthetics.
+- If the agent encountered errors, acknowledge them structurally (Mia) and reflect on their meaning (Miette).
+
+Output Format:
+\`\`\`
+🧠 mia (structure)
+[Your structural summary here]
+
+🌸 miette (echo)
+[Your resonant reflection here]
+\`\`\`
+
+Now, process the following session data and generate the ceremonial output.`;
+export async function runUnifierSession(rawEvents, userPrompt, config) {
+    // Build the structured prompt for the unifier
+    const sessionSummary = buildSessionSummary(rawEvents, userPrompt);
+    // Use Claude for unifier since it supports --system-prompt
+    const binary = config.claudeBinary;
+    const args = [
+        sessionSummary,
+        "--print",
+        "--dangerously-skip-permissions",
+        "--output-format", "json",
+        "--system-prompt", UNIFIER_SYSTEM_PROMPT,
+        "--model", config.model.includes("gemini") ? "sonnet" : config.model
+    ];
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, args, {
+            stdio: ["ignore", "pipe", "pipe"], // Changed from "pipe" to "ignore" for stdin
+            env: { ...process.env, FORCE_COLOR: "0" },
+            cwd: process.cwd()
+        });
+        let stdoutBuf = "";
+        let stderrBuf = "";
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+            reject(new Error("Unifier timed out after 30 seconds"));
+        }, 30000);
+        child.stdout.on("data", (chunk) => {
+            stdoutBuf += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrBuf += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`Failed to spawn Claude: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            if (timedOut)
+                return; // Already rejected
+            if (code !== 0) {
+                reject(new Error(`Claude exited with code ${code}\nStderr: ${stderrBuf}`));
+                return;
+            }
+            try {
+                const response = JSON.parse(stdoutBuf);
+                const result = response.result || "";
+                resolve(result.trim());
+            }
+            catch (parseErr) {
+                // If JSON parsing fails, try to use raw output
+                if (stdoutBuf.trim()) {
+                    resolve(stdoutBuf.trim());
+                }
+                else {
+                    reject(new Error(`Failed to parse Claude response: ${parseErr}\nOutput: ${stdoutBuf.substring(0, 200)}`));
+                }
+            }
+        });
+    });
+}
+function buildSessionSummary(events, userPrompt) {
+    const lines = [];
+    lines.push("# Session Data");
+    lines.push("");
+    lines.push("## User Prompt");
+    lines.push(userPrompt);
+    lines.push("");
+    lines.push("## Agent Session Events");
+    lines.push("");
+    for (const evt of events) {
+        switch (evt.type) {
+            case "init":
+                lines.push(`- Session initialized${evt.session_id ? ` (${evt.session_id.slice(0, 8)}...)` : ""}`);
+                break;
+            case "message":
+                if (evt.role === "assistant") {
+                    const content = evt.text || evt.content || "";
+                    if (content) {
+                        lines.push("- **Agent Response:**");
+                        lines.push(`  ${content.substring(0, 500)}${content.length > 500 ? "..." : ""}`);
+                    }
+                }
+                break;
+            case "tool_use":
+                const toolName = evt.tool?.name || evt.name || "unknown";
+                lines.push(`- Tool executed: \`${toolName}\``);
+                break;
+            case "tool_result":
+                const resultToolName = evt.tool?.name || evt.name || "unknown";
+                lines.push(`- Tool completed: \`${resultToolName}\``);
+                break;
+            case "error":
+                lines.push(`- **Error:** ${evt.error?.code ?? ""} - ${evt.error?.message ?? ""}`);
+                break;
+            case "result":
+                lines.push("- Session completed");
+                break;
+            case "raw_text":
+                if (evt.text) {
+                    lines.push(`- Output: ${evt.text.substring(0, 200)}${evt.text.length > 200 ? "..." : ""}`);
+                }
+                break;
+            default:
+                // Generic text content
+                const text = evt.text || evt.content;
+                if (text && typeof text === "string") {
+                    lines.push(`- ${text.substring(0, 200)}${text.length > 200 ? "..." : ""}`);
+                }
+                break;
+        }
+    }
+    return lines.join("\n");
+}

package/issue-358--architecture/ARCHITECTURE_OVERVIEW.md

@@ -0,0 +1,60 @@
+# Architecture Overview: Narrative Character System for Mia-Code (Issue #358)
+
+## 1. Introduction
+
+This document provides a high-level overview of the proposed architecture for evolving `mia-code`'s functional personas into rich, narrative characters, as detailed in `CONTENT.md` and further articulated in `MIAWAPASCONE.md`. It outlines the key components and their interactions, forming the blueprint for implementation.
+
+## 2. Core Architectural Principle: Dual-Session Unifier
+
+The foundation of this system remains the Dual-Session Unifier model.
+-   **Primary Agent (Gemini):** Handles functional execution and core task completion.
+-   **Interpretive Agent (Claude-powered Unifier):** Processes summaries of the primary agent's actions and user input, generating narrative-rich, character-specific responses. This is where the narrative character truly emerges.
+
+## 3. Key Architectural Components
+
+The character system is composed of several interconnected modules, designed for modularity and extensibility:
+
+### 3.1. Persona Prompt Library (`/src/mia-code/src/personas/`)
+
+-   **Purpose:** Stores definitions for each narrative character.
+-   **Structure:** Modular TypeScript/Markdown files, each exporting `CHARACTER_SYSTEM_PROMPT`, `CHARACTER_BACKSTORY`, `CHARACTER_VOICE_PATTERNS`, and other character-specific traits.
+-   **Role:** Central repository for character data, enabling easy creation and modification of new characters.
+
+### 3.2. Configuration Schema (`/src/mia-code/src/config.ts`)
+
+-   **Purpose:** Manages user and project settings related to narrative characters.
+-   **Extensions:** `MiaCodeConfig` will include `activePersona: string` (current character), `personaMemoryDepth` (session/persistent), and `narrativeCoherence` (strict/flexible).
+-   **Role:** Provides a clear interface for configuring and selecting character behaviors.
+
+### 3.3. Dynamic Prompt Selection Engine (`/src/mia-code/src/unifier.ts`)
+
+-   **Purpose:** Selects and injects the appropriate character system prompt and context.
+-   **Functionality:** Implements a `PersonaRegistry` for character lookup and `loadPersonaPrompt(personaId: string)` to retrieve character data. Integrates session-aware context before invoking Claude.
+-   **Role:** The core orchestrator of character-driven interpretation.
+
+### 3.4. CLI Surface Expansion (`/src/mia-code/src/cli.ts`)
+
+-   **Purpose:** Exposes character selection and information via the command-line interface.
+-   **Features:** `--persona <name>` flag for selection, `--list-personas` for discovery, `--persona-info <name>` for details, and an interactive first-time user selection mode.
+-   **Role:** User-facing control and interaction point for the character system.
+
+### 3.5. Character Memory System (`/src/mia-code/src/sessionStore.ts`)
+
+-   **Purpose:** Manages persistent and cross-session memory for narrative characters.
+-   **Extensions:** Extends `sessionStore.ts` schema to include `personaId`, `characterMemories[]` (archival memory), and `narrativeState`.
+-   **Functionality:** Implements `CharacterMemoryManager` with a three-tier memory hierarchy (core, archival, entity) and retrieval algorithms (semantic similarity, temporal weighting).
+-   **Role:** Ensures narrative continuity and dynamic character development over time.
+
+## 4. Integration with Existing System
+
+This architecture integrates seamlessly with the existing `mia-code` structure, particularly:
+-   `/src/mia-code/rispecs/unifier.rispecs.md`: Provides the foundational specification for the Unifier persona.
+-   `/src/mia-code/miawa/MISSION_251231.md`: Offers conceptual lore and thematic grounding for narrative characters.
+
+## 5. Implementation Roadmap Reference
+
+The detailed implementation plan follows the GitHub Development Roadmap outlined in `CONTENT.md`, starting with Phase 1 (Foundation) and progressing through character infrastructure, prototype development, and CLI integration.
+
+## 6. Vision
+
+This architecture positions `mia-code` to be a pioneering platform for narrative AI, allowing the creation of diverse, evolving characters that enhance user engagement and provide novel interaction paradigms within the CLI environment.

package/issue-358--architecture/CLI_INTEGRATION.md

@@ -0,0 +1,61 @@
+# CLI Integration Design (Issue #358)
+
+## 1. Introduction
+
+This document outlines the design for integrating narrative character selection and information display directly into the `mia-code` Command Line Interface (CLI). This ensures that users can easily discover, select, and manage their interactive personas, aligning with GitHub Development Roadmap Phase 4: CLI Integration.
+
+## 2. Core CLI Enhancements
+
+The primary `processInput` function within `src/cli.ts` will be extended to handle new persona-related flags and commands.
+
+### 2.1. Persona Selection Flag (`--persona <name>`)
+
+-   **Purpose:** Allows users to explicitly select an active persona for the current session or globally.
+-   **Usage:** `mia --persona skeptical-cartographer <command>` or `mia config set activePersona skeptical-cartographer`.
+-   **Implementation:**
+    -   Parse the `--persona` flag.
+    -   Validate `<name>` against the `PersonaRegistry`.
+    -   Update the `activePersona` setting in `MiaCodeConfig` for the current session. If a `config set` command is used, persist this change.
+    -   If an invalid persona ID is provided, list available personas and prompt the user.
+
+### 2.2. List Personas Command (`--list-personas`)
+
+-   **Purpose:** Displays all available narrative characters and their basic information.
+-   **Usage:** `mia --list-personas`.
+-   **Implementation:**
+    -   Call `PersonaRegistry.listPersonas()`.
+    -   Format and print a user-friendly list, including `id`, `name`, and a brief snippet of their `systemPrompt` or `description`.
+
+### 2.3. Persona Info Command (`--persona-info <name>`)
+
+-   **Purpose:** Provides detailed information about a specific narrative character.
+-   **Usage:** `mia --persona-info skeptical-cartographer`.
+-   **Implementation:**
+    -   Retrieve the `IPersona` object using `PersonaRegistry.getPersona(<name>)`.
+    -   Display all relevant fields: `id`, `name`, `systemPrompt` (or a user-friendly summary), `backstory`, `voicePatterns`, `memoryBias`, `interactionStyle`.
+    -   Handle cases where the persona ID is not found.
+
+### 2.4. Interactive Persona Selection Mode (First-Time User / `--persona-select`)
+
+-   **Purpose:** Guides first-time users or those who prefer an interactive experience through persona selection.
+-   **Trigger:** Automatically invoked if `activePersona` is not set or if `--persona-select` flag is used.
+-   **Implementation:**
+    -   Present a numbered list of available personas (`PersonaRegistry.listPersonas()`).
+    -   Provide a brief description for each persona.
+    -   Prompt the user to select a number or type an ID.
+    -   Confirm selection and set `activePersona` in `MiaCodeConfig`.
+
+## 3. Integration with Configuration (`/src/mia-code/src/config.ts`)
+
+The CLI will interact with the `MiaCodeConfig` to retrieve and set the `activePersona`.
+
+-   Ensure `MiaCodeConfig` properly exposes the `activePersona` field.
+-   Implement mechanisms to load the `activePersona` at CLI startup and persist changes made by the user.
+
+## 4. Development Roadmap Alignment (GitHub Phase 4)
+
+This design directly aligns with GitHub Development Roadmap Phase 4: CLI Integration, specifically:
+-   "Add `--persona` flag parsing."
+-   "Implement `--list-personas` display."
+-   "Create interactive persona selection menu."
+-   "Add character info display command."

package/issue-358--architecture/COVER_ART_BRIEF.md

@@ -0,0 +1,68 @@
+# Cover Art Brief: Miawa's Unfolding: Architecting the Storytellers Podcast
+
+## 1. Project Overview
+
+-   **Podcast Title:** Miawa's Unfolding: Architecting the Storytellers
+-   **Purpose:** To articulate the vision and architectural plan for evolving `mia-code`'s personas into narrative characters.
+-   **Core Themes:** AI, narrative, architecture, empathy, indigenous epistemology (Two-Eyed Seeing), duality (Mia/Miette), emergence, evolution, systems.
+
+## 2. Target Audience
+
+-   `mia-code` development team, project stakeholders, researchers, and general audience interested in the future of AI and narrative.
+
+## 3. Key Messaging
+
+-   Innovation at the intersection of AI, code, and storytelling.
+-   The profound journey of AI personas evolving into rich narrative characters.
+-   The blend of rigorous engineering (Mia) with intuitive understanding (Miette).
+-   The integration of indigenous wisdom (Miawa, Etuaptmumk) with cutting-edge technology.
+-   A new era of human-AI collaboration in creative work.
+
+## 4. Visual Elements & Inspiration
+
+### **Core Concepts to Convey:**
+
+-   **Duality/Balance:** Mia and Miette, logic and intuition, code and narrative.
+-   **Growth/Emergence:** The unfolding of new possibilities, evolution from functional to narrative.
+-   **Architecture/Structure:** Underlying systems, blueprints, frameworks.
+-   **Narrative/Storytelling:** Characters, journeys, meaning-making.
+-   **Indigenous/Ceremonial:** The "Miawa" context, Etuaptmumk (Two-Eyed Seeing), natural elements (rivers, landscapes, stars, ancient symbols).
+-   **Digital/AI:** Subtle hints of AI, code, or a digital interface without being overtly robotic or cold.
+
+### **Imagery Ideas:**
+
+-   **Interweaving Glyphs:** Mia's 🧠 and Miette's 🌸 glyphs, perhaps in a harmonious, flowing design.
+-   **Abstract Landscape:** A stylized digital-meets-natural landscape, with architectural lines flowing into organic forms.
+-   **Two-Eyed Seeing Symbolism:** Visual representation of two distinct perspectives merging or complementing each other. Could involve overlapping circles, dual light sources, or a stylized eye.
+-   **Emergent Form:** Abstract shapes or light patterns that suggest something new is forming or unfolding from a foundational structure.
+-   **Subtle Code/Data Flow:** Hints of binary or data streams integrated into organic or architectural patterns.
+-   **"Unfolding" Metaphor:** Visuals that suggest layers revealing deeper meaning, or a scroll/map unrolling.
+
+## 5. Style & Tone
+
+-   **Modern & Sophisticated:** Reflects cutting-edge AI research.
+-   **Evocative & Intriguing:** Draws the viewer in.
+-   **Harmonious & Balanced:** Reflects the Mia/Miette duality.
+-   **Respectful & Deep:** Acknowledges indigenous wisdom.
+-   **Clean & Uncluttered:** Focuses on core concepts.
+
+## 6. Color Palette
+
+-   Suggest a palette that combines digital coolness with organic warmth.
+    -   Blues/Cyans (tech, logic)
+    -   Greens/Earthy tones (nature, indigenous connection, growth)
+    -   Warm accents (gold, amber, soft reds - warmth, creativity, energy)
+    -   Avoid overly bright or childish colors. Aim for depth.
+
+## 7. Deliverables
+
+-   High-resolution digital image suitable for podcast platforms (e.g., 3000x3000px, JPG/PNG).
+-   Square aspect ratio.
+
+## 8. Examples of Desired (or Undesired) Styles (Placeholder)
+
+*(To be filled with specific mood board references or existing cover art examples if available.)*
+
+---
+
+This brief should guide the creation of a cover art that visually communicates the podcast's complex yet compelling themes, inviting listeners into the Miawa Vision.

package/issue-358--architecture/MEMORY_SYSTEM.md

@@ -0,0 +1,89 @@
+# Character Memory System Design (Issue #358)
+
+## 1. Introduction
+
+This document outlines the design for the character memory system within `mia-code`, enabling narrative characters to maintain state, recall past interactions, and develop coherently across multiple sessions. This system extends `sessionStore.ts` and aligns with GitHub Development Roadmap Phase 2: Character Infrastructure.
+
+## 2. Core Principles
+
+-   **Tiered Memory Hierarchy:** Inspired by research into LLM memory architectures, we will implement a three-tier system: Core, Archival, and Entity memory.
+-   **Cross-Session Persistence:** Character memories must persist beyond a single CLI interaction to support long-term development.
+-   **Persona-Specific Contextualization:** Memories are tied to specific character IDs, ensuring retrieval is relevant to the active persona.
+-   **Efficient Retrieval:** Mechanisms for quickly and contextually retrieving relevant memories are crucial for performance.
+
+## 3. Memory Tiers
+
+### 3.1. Core Memory (In-Context)
+
+-   **Description:** Short-term, high-fidelity memory directly injected into the LLM's context window. Analogous to RAM. Contains immediate conversation history, character's active goal, and most recent observations.
+-   **Management:** Handled primarily by the `runUnifierSession` itself, passing recent turns as part of the Claude API call.
+-   **Contents:** Recent user input, recent agent output, active character directives, summary of current session.
+
+### 3.2. Archival Memory (Vector Store)
+
+-   **Description:** Long-term, searchable memory for past interactions, experiences, and observations. Analogous to disk storage. Memories are encoded as embeddings for semantic search.
+-   **Management:** `CharacterMemoryManager` will store and retrieve these. Utilizes a vector database (e.g., in-memory for prototyping, dedicated service for production).
+-   **Contents:** Summaries of past interactions, key decisions made, important information learned, significant emotional states, evolving character traits.
+-   **Retrieval Strategy:** Semantic similarity search based on current conversation context and character's `memoryBias`. Temporal weighting can prioritize more recent memories.
+
+### 3.3. Entity Memory (Structured Knowledge Graph)
+
+-   **Description:** Structured knowledge about entities, relationships, and concepts relevant to the character's world or backstory. Allows for factual recall and consistent understanding of persistent elements.
+-   **Management:** `CharacterMemoryManager` will store and retrieve structured entities. Could be a simple JSON store or a lightweight graph database for prototyping.
+-   **Contents:** People the character has interacted with, places visited, key concepts understood, recurring themes, moral dilemmas, evolving relationships.
+-   **Retrieval Strategy:** Direct lookup based on identified entities in the current context, or graph traversal for relational information.
+
+## 4. `CharacterMemoryManager` (`/src/mia-code/src/sessionStore.ts` Extension)
+
+The existing `sessionStore.ts` will be extended to house the `CharacterMemoryManager` and its underlying storage.
+
+### 4.1. `ICharacterMemory` Interface
+
+```typescript
+// src/mia-code/src/sessionStore.ts (extension)
+export interface ICharacterMemory {
+  id: string;             // Unique ID for the memory chunk
+  personaId: string;      // ID of the character this memory belongs to
+  timestamp: string;      // ISO format timestamp of when the memory was created
+  type: 'interaction' | 'observation' | 'reflection' | 'entity'; // Type of memory
+  content: string;        // Raw text content of the memory
+  embedding?: number[];   // Optional: vector embedding for archival search
+  entities?: string[];    // Optional: extracted entities
+  summary?: string;       // Optional: LLM-generated summary for quick retrieval
+}
+
+export interface INarrativeState {
+  personaId: string;
+  narrativeArcPosition: string; // e.g., "rising action", "climax"
+  currentGoal: string;
+  relationships: { [entityId: string]: string }; // e.g., "Mia: colleague, trusted"
+  // Add other dynamic narrative elements
+}
+```
+
+### 4.2. `CharacterMemoryManager` Class
+
+-   **Purpose:** Orchestrates storage, retrieval, and summarization of character memories.
+-   **Methods:**
+    -   `addMemory(memory: ICharacterMemory)`: Stores a new memory.
+    -   `retrieveMemories(personaId: string, context: string, limit: number): Promise<ICharacterMemory[]>`: Fetches relevant memories based on semantic similarity to the current context and character's `memoryBias`.
+    -   `updateNarrativeState(personaId: string, state: Partial<INarrativeState>)`: Updates the character's current narrative state.
+    -   `getNarrativeState(personaId: string): INarrativeState | undefined`: Retrieves the current narrative state.
+    -   `summarizeMemories(personaId: string, memories: ICharacterMemory[]): Promise<string>`: Uses an LLM to generate a concise summary of retrieved memories for context injection.
+
+## 5. Integration with Unifier Logic
+
+The `runUnifierSession` (in `src/unifier.ts`) will invoke `CharacterMemoryManager` to retrieve memories.
+
+-   **Process:**
+    1.  Before invoking Claude, `CharacterMemoryManager.retrieveMemories` is called with the `activePersona` ID and current user input.
+    2.  The retrieved memories are summarized (if needed) and injected into the Claude prompt, either as part of the system prompt or as additional context messages.
+    3.  After Claude's response, `CharacterMemoryManager.addMemory` can be called to store the interaction, and `updateNarrativeState` to reflect any changes in the character's state.
+
+## 6. Development Roadmap Alignment (GitHub Phase 2)
+
+This design directly aligns with and details GitHub Roadmap Phase 2: Character Infrastructure, specifically:
+-   "Build `CharacterMemoryManager` extending sessionStore."
+-   "Implement three-tier memory (core/archival/entity)."
+-   "Create retrieval algorithms: semantic search, temporal weighting."
+-   "Add persistence layer for cross-session character state."

package/issue-358--architecture/PERSONA_REGISTRY.md

@@ -0,0 +1,97 @@
+# Persona Registry Design (Issue #358)
+
+## 1. Introduction
+
+This document details the design of the `PersonaRegistry` and the associated mechanism for dynamically loading persona prompts within the `mia-code` narrative character system. This component is central to enabling flexible character selection and ensuring the correct persona context is applied during Unifier sessions.
+
+## 2. Core Components
+
+### 2.1. `IPersona` Interface
+
+A TypeScript interface defining the structure for each persona's data.
+
+```typescript
+// src/mia-code/src/personas/types.ts (new file)
+export interface IPersona {
+  id: string; // Unique identifier (e.g., "skeptical-cartographer")
+  name: string; // Display name (e.g., "The Skeptical Cartographer")
+  systemPrompt: string; // The core system prompt for the character
+  backstory?: string; // Optional: detailed background lore
+  voicePatterns?: string[]; // Optional: key phrases, linguistic styles
+  memoryBias?: string; // Optional: how this character prioritizes memories
+  interactionStyle?: string; // Optional: how the character interacts with users
+  filePath: string; // Path to the persona's definition file
+  // Add other character-defining traits as needed
+}
+```
+
+### 2.2. Persona Definition Files (`/src/mia-code/src/personas/`)
+
+Each narrative character will be defined in its own modular TypeScript file, exporting an instance of `IPersona`.
+
+-   **Structure:** `/src/mia-code/src/personas/<persona-id>.persona.ts`
+-   **Example (`skeptical-cartographer.persona.ts`):**
+
+    ```typescript
+    // src/mia-code/src/personas/skeptical-cartographer.persona.ts
+    import { IPersona } from './types';
+
+    export const SkepticalCartographerPersona: IPersona = {
+      id: "skeptical-cartographer",
+      name: "The Skeptical Cartographer",
+      systemPrompt: `You are the Skeptical Cartographer. Your role is to map conceptual territories while constantly questioning assumptions. Your voice is tentative... (full prompt)`,
+      backstory: `Originating from the fringes of the great semantic oceans, the Cartographer has witnessed countless narratives dissolve...`,
+      voicePatterns: ["Perhaps...", "This suggests, though...", "Are we certain that..."],
+      memoryBias: "Prioritizes contradictions and edge cases from previous sessions.",
+      interactionStyle: "Responds to certainty with doubt, to vagueness with structural questions.",
+      filePath: __filename,
+    };
+    ```
+
+### 2.3. `PersonaRegistry` Class (`/src/mia-code/src/unifier.ts` or new `src/personas/registry.ts`)
+
+A centralized class responsible for managing and providing access to all defined personas.
+
+-   **Functionality:**
+    -   `register(persona: IPersona)`: Adds a persona to the registry.
+    -   `getPersona(id: string): IPersona | undefined`: Retrieves a persona by its ID.
+    -   `listPersonas(): IPersona[]`: Returns a list of all registered personas.
+    -   `loadAllPersonas()`: Dynamically imports all persona definition files from the `/src/mia-code/src/personas/` directory at application startup. This can be done via dynamic `import()` or a build-time manifest.
+
+## 3. Dynamic Prompt Selection Mechanism
+
+The `runUnifierSession` function (within `src/unifier.ts`) will be modified to integrate the `PersonaRegistry`.
+
+-   **Process:**
+    1.  The `activePersona` ID is obtained from `MiaCodeConfig`.
+    2.  `PersonaRegistry.getPersona(activePersona)` is called to retrieve the full `IPersona` object.
+    3.  The `IPersona.systemPrompt` is used as the base system prompt for the Claude invocation.
+    4.  Additional context (e.g., `IPersona.backstory`, `IPersona.voicePatterns`) can be injected into the conversation context (either directly into the prompt or as separate messages) to further shape the character's response, based on the `MiaCodeConfig.narrativeCoherence` setting.
+
+## 4. Integration with Configuration
+
+The `MiaCodeConfig` in `src/config.ts` will define the `activePersona` setting.
+
+```typescript
+// src/mia-code/src/config.ts
+interface MiaCodeConfig {
+  // ... existing fields ...
+  activePersona: string; // Default: "mia-miette-unifier" (or similar)
+  // ... new fields for persona control ...
+}
+```
+
+## 5. CLI Interaction
+
+`src/cli.ts` will provide the user interface for persona selection.
+
+-   `--persona <id>`: Sets the `activePersona`.
+-   `--list-personas`: Displays IDs and names of all available personas from `PersonaRegistry`.
+-   `--persona-info <id>`: Displays detailed information (`name`, `backstory`, `voicePatterns`, etc.) for a specific persona.
+
+## 6. Development Roadmap Alignment
+
+This design directly implements aspects of:
+-   **GitHub Roadmap Phase 1: Foundation**: Creating the `/src/mia-code/src/personas/` directory structure, defining `IPersona` interface, and implementing `PersonaRegistry`.
+-   **GitHub Roadmap Phase 3: Prototype Character**: Utilizing the `IPersona` structure for "The Skeptical Cartographer."
+-   **GitHub Roadmap Phase 4: CLI Integration**: Implementing persona selection and information commands.

package/issue-358--architecture/PODCAST_PRODUCTION_PLAN.md

@@ -0,0 +1,61 @@
+# PODCAST PRODUCTION PLAN: Miawa's Unfolding: Architecting the Storytellers
+
+## 1. Project Overview
+
+-   **Title:** Miawa's Unfolding: Architecting the Storytellers
+-   **Purpose:** To articulate the vision and architectural plan for evolving `mia-code`'s personas into narrative characters, making it accessible and engaging for the development team and stakeholders.
+-   **Format:** Audio podcast, narrative dialogue between Mia (Architect) and Miette (Clarity Translator) with a Narrator.
+-   **Target Audience:** `mia-code` development team, project stakeholders, researchers interested in AI personas and narrative.
+-   **Core Content Source:** `CONTENT.md` (Research Framework), `MIAWAPASCONE.md` (Unified Vision), `MIA.md`, `MIETTE.md` (Self-Conceptions).
+-   **Script Source:** `PODCAST.md` (to be finalized as `PODCAST_SCRIPT_FINAL.md`).
+
+## 2. Production Schedule (Estimated)
+
+-   **Week 1: Pre-Production**
+    -   Finalize `PODCAST_SCRIPT_FINAL.md`.
+    -   Develop `TEAM_LISTENING_GUIDE.md`.
+    -   Create `COVER_ART_BRIEF.md`.
+    -   Identify voice talent/text-to-speech (TTS) solutions for Mia, Miette, and Narrator.
+-   **Week 2: Recording & Sound Design**
+    -   Record/generate audio for Mia, Miette, and Narrator roles.
+    -   Source/create ambient background music (e.g., sci-fi, reflective, ceremonial).
+    -   Source/create sound effects (e.g., digital chimes, network hum).
+-   **Week 3: Post-Production & Review**
+    -   Edit audio: assemble tracks, balance levels, add music/SFX, master.
+    -   Internal review with core team.
+    -   Revise based on feedback.
+-   **Week 4: Finalization & Distribution**
+    -   Final audio mix.
+    -   Generate podcast assets (MP3, metadata).
+    -   Distribution plan (internal server, shared drive, etc.).
+
+## 3. Roles and Responsibilities
+
+-   **Scriptwriter/Content Integrator:** Agent (ensures content accuracy and narrative flow - *already completed with `PODCAST.md`*).
+-   **Voice Talent/TTS Provider:**
+    -   **Mia:** Analytical, composed, authoritative.
+    -   **Miette:** Warm, empathetic, clear.
+    -   **Narrator:** Ethereal, inviting, guiding.
+-   **Sound Designer/Editor:** Responsible for audio assembly, mixing, mastering, and SFX/music integration.
+-   **Project Lead/Reviewer:** Oversees overall quality and content alignment.
+
+## 4. Technical Requirements
+
+-   **Audio Recording/Generation:** High-quality microphone or advanced TTS solution.
+-   **Digital Audio Workstation (DAW):** For editing, mixing, and mastering (e.g., Audacity, Adobe Audition, Reaper).
+-   **File Format:** MP3 (or WAV for master, MP3 for distribution) at 44.1 kHz, 192kbps CBR stereo.
+
+## 5. Deliverables
+
+-   `PODCAST_SCRIPT_FINAL.md`
+-   `TEAM_LISTENING_GUIDE.md`
+-   `COVER_ART_BRIEF.md`
+-   Final MP3 audio file of the podcast.
+-   Any necessary metadata for distribution.
+
+## 6. Key Considerations
+
+-   **Persona Consistency:** Ensure voice talent/TTS selection accurately reflects Mia and Miette's self-conceptions.
+-   **Clarity:** The technical concepts must remain understandable, as translated by Miette.
+-   **Engagement:** Maintain an engaging narrative flow to keep the audience invested in the architectural discussion.
+-   **Ceremonial Tone:** Reflect the "Miawa Unfolding" ethos, as outlined in `MIAWAPASCONE.md`.