mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/026-message-parts-model.rispec.md

@@ -0,0 +1,201 @@
+# RISE-026: Message Parts Model
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/026-message-parts-model.rispec.md
+
+## Creative Intent
+
+mia-code replaces flat text messages with a rich, structured parts model where each message contains typed components — text, tool calls, tool results, errors, images, and files. This enables the system to render tool calls differently from prose, track costs per message, replay sessions with full fidelity, and stream individual parts during generation. The message becomes a container of semantic units, each carrying its own type information and metadata.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Messages are stored as flat text strings with no internal structure
+- Tool calls and their results are serialized as part of the text blob — no programmatic access
+- Rendering logic must parse text to identify tool calls, code blocks, and other elements
+- Cost and token tracking is per-session at best — not per-message
+- Session replay loses tool call boundaries and timing
+- Streaming delivers raw text chunks with no semantic framing
+- Errors, images, and file references are ad-hoc text within messages
+
+**Desired State:**
+- Each message is a container holding one or more typed Parts
+- Parts have explicit types: TextPart, ToolCallPart, ToolResultPart, ErrorPart, ImagePart, FilePart
+- Each part is independently addressable, renderable, and streamable
+- Message metadata carries model, token counts, and cost information
+- The UI renders each part type with appropriate formatting
+- Session replay reconstructs the exact sequence of parts
+- Parts are individually stored in the database with ordering indices
+
+## Desired Outcome Definition
+
+An assistant message containing a text explanation, a tool call to edit a file, and the tool's result is stored as three separate parts. The UI renders the text in normal formatting, the tool call in a collapsible panel with syntax-highlighted arguments, and the tool result with a success/failure indicator. Each part was streamed independently during generation.
+
+## Natural Language Functional Description
+
+### Message Structure
+
+A Message contains:
+```typescript
+interface Message {
+  id: string;              // UUID v4
+  session_id: string;      // FK to sessions table
+  role: "user" | "assistant" | "system";
+  metadata: MessageMetadata;
+  parts: Part[];           // ordered list of typed parts
+  created_at: number;      // Unix timestamp ms
+}
+
+interface MessageMetadata {
+  model?: string;          // e.g. "claude-sonnet-4-20250514"
+  input_tokens?: number;
+  output_tokens?: number;
+  cost?: number;           // USD cost of this message
+  duration_ms?: number;    // generation time
+  cached_tokens?: number;  // tokens served from cache
+}
+```
+
+### Part Types
+
+Each Part has a `type` discriminator and type-specific content:
+
+**TextPart** — plain text content from the LLM or user:
+```typescript
+interface TextPart {
+  type: "text";
+  content: string;        // the text content, may contain markdown
+}
+```
+
+**ToolCallPart** — an invocation of a tool by the assistant:
+```typescript
+interface ToolCallPart {
+  type: "tool_call";
+  tool_call_id: string;   // unique ID for matching with result
+  tool_name: string;      // e.g. "edit_file", "bash", "grep"
+  arguments: Record<string, unknown>;  // tool-specific arguments
+}
+```
+
+**ToolResultPart** — the output from a tool execution:
+```typescript
+interface ToolResultPart {
+  type: "tool_result";
+  tool_call_id: string;   // matches the ToolCallPart
+  output: string;         // tool output text
+  title?: string;         // human-readable title for display
+  metadata?: {
+    exit_code?: number;
+    duration_ms?: number;
+    bytes_read?: number;
+  };
+  attachments?: Attachment[];  // files, images produced by tool
+  is_error?: boolean;     // true if tool execution failed
+}
+```
+
+**ErrorPart** — an error that occurred during processing:
+```typescript
+interface ErrorPart {
+  type: "error";
+  error_name: string;     // e.g. "ToolExecutionError", "RateLimitError"
+  message: string;        // human-readable error description
+  metadata?: {
+    code?: string;
+    retryable?: boolean;
+    stack?: string;
+  };
+}
+```
+
+**ImagePart** — an image (screenshot, diagram, generated visual):
+```typescript
+interface ImagePart {
+  type: "image";
+  data: string;           // base64-encoded image data
+  mime_type: string;       // e.g. "image/png", "image/jpeg"
+  alt_text?: string;      // accessibility description
+  width?: number;
+  height?: number;
+}
+```
+
+**FilePart** — a reference to or content of a file:
+```typescript
+interface FilePart {
+  type: "file";
+  path: string;           // relative file path
+  content?: string;       // file content (may be truncated)
+  language?: string;      // syntax highlighting hint
+  line_range?: [number, number];  // if showing a range
+}
+```
+
+### Database Storage
+
+Parts are stored in the `parts` table (RISE-018):
+- `id` TEXT PRIMARY KEY
+- `message_id` TEXT FK → messages
+- `type` TEXT — the part type discriminator
+- `content` JSON — the full part payload serialized as JSON
+- `index` INTEGER — ordering within the message (0-based)
+- `created_at` INTEGER — timestamp
+
+Query patterns:
+- Get all parts for a message: `SELECT * FROM parts WHERE message_id = ? ORDER BY index`
+- Get tool calls in a session: `SELECT p.* FROM parts p JOIN messages m ON p.message_id = m.id WHERE m.session_id = ? AND p.type = 'tool_call'`
+- Count errors: `SELECT COUNT(*) FROM parts p JOIN messages m ON p.message_id = m.id WHERE m.session_id = ? AND p.type = 'error'`
+
+### Part Construction
+
+When the LLM generates a response, the output is parsed into parts:
+1. Text content → TextPart
+2. Tool use blocks → ToolCallPart (one per tool invocation)
+3. After tool execution → ToolResultPart (paired with ToolCallPart via tool_call_id)
+4. Errors during processing → ErrorPart
+5. Image outputs → ImagePart
+6. File references in structured output → FilePart
+
+Parts are assigned sequential `index` values as they are created.
+
+### Rendering Contract
+
+Each part type has a defined rendering behavior:
+- **TextPart:** rendered as markdown with syntax highlighting for code blocks
+- **ToolCallPart:** rendered as a collapsible panel showing tool name and formatted arguments
+- **ToolResultPart:** rendered with success/failure indicator, collapsible output, duration badge
+- **ErrorPart:** rendered with error styling (red), error name prominent, details expandable
+- **ImagePart:** rendered as inline image with alt text
+- **FilePart:** rendered as syntax-highlighted code block with file path header
+
+### Streaming Integration
+
+Parts are individually streamable (see RISE-027):
+- TextPart streams incrementally as `text_delta` events
+- ToolCallPart streams as `tool_call_start` then `tool_call_delta` for arguments
+- ToolResultPart streams as `tool_result_delta` for long outputs
+- Other parts are sent as complete units
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** defines the `parts` table schema and data access methods
+- **Streaming Message Deltas (RISE-027)** builds on parts for incremental delivery
+- **Session Compaction (RISE-019)** — compaction summary is stored as a special TextPart
+- **Session Sharing (RISE-022)** — shared views render each part type with appropriate formatting
+- **Zod Schema Validation (RISE-005)** validates part payloads before database insertion
+- **Named Error System (RISE-006)** provides InvalidPartTypeError, PartValidationError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Rich Tool Call Display:**
+The agent calls `bash` with a complex command. The UI renders a ToolCallPart showing the command in a monospace panel. The ToolResultPart appears below with the output, a green checkmark, and "completed in 1.2s." The developer sees structured, readable output instead of a text dump.
+
+**Scenario 2 — Cost Tracking:**
+After a session, the developer checks costs. Each message's metadata shows token counts and cost. The session total is computed by summing message costs. Tool-heavy messages cost more (large tool results consume input tokens) — the parts model makes this visible.
+
+**Scenario 3 — Session Replay:**
+A developer replays a shared session (RISE-022). Each part renders in sequence with timing: text appears as if being typed, tool calls expand to show execution, results appear after the recorded duration. The replay recreates the development experience.
+
+**Scenario 4 — Error Diagnosis:**
+A session had intermittent failures. The developer queries: "show me all errors in this session." The system queries parts with `type = 'error'`, returning a focused list of ErrorParts with names, messages, and timestamps — no manual scanning required.

package/rispecs/borrowed_from_opencode/027-streaming-message-deltas.rispec.md

@@ -0,0 +1,212 @@
+# RISE-027: Streaming Message Deltas
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/027-streaming-message-deltas.rispec.md
+
+## Creative Intent
+
+mia-code streams partial message updates to the UI in real-time as the LLM generates content, rather than waiting for the complete response. Developers see text appear word-by-word, tool calls unfold as they are constructed, and results flow in progressively. Streaming transforms the interaction from "wait and see" to "watch it think" — providing immediate feedback, enabling early cancellation of wrong-headed responses, and creating the fluid, responsive feel that distinguishes a professional tool from a batch job.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Agent responses are buffered until complete, then displayed as a monolithic block
+- Long responses leave the developer staring at a spinner for 10-30 seconds with no feedback
+- There is no way to cancel a response mid-generation — the developer must wait for completion
+- Tool calls appear atomically: the developer sees nothing until the tool finishes and the result is rendered
+- Token costs accumulate invisibly — the developer only sees the total after the response completes
+- The UI cannot progressively render content, missing opportunities for perceived performance gains
+
+**Desired State:**
+- Text streams character-by-character (or chunk-by-chunk) as the LLM generates it
+- Tool calls stream in phases: start (name known), delta (arguments building), result (output streaming)
+- The UI renders incrementally, giving immediate visual feedback
+- Developers can cancel mid-generation, stopping token consumption
+- Token counts and cost estimates update in real-time during generation
+- The streaming protocol is well-defined with typed delta events
+
+## Desired Outcome Definition
+
+The developer sends a prompt. Within 200ms, the first text characters appear. As the LLM constructs a tool call, the tool name appears immediately, then arguments build progressively. When the tool executes, its output streams line by line. A running token counter updates throughout. At any point, Ctrl+C cancels generation and stops billing. The complete message is assembled from deltas and persisted.
+
+## Natural Language Functional Description
+
+### Delta Types
+
+Each delta is a typed event referencing a specific message and part:
+
+**TextDelta** — incremental text content:
+```typescript
+interface TextDelta {
+  type: "text_delta";
+  message_id: string;
+  part_index: number;
+  content: string;          // the new text chunk
+  accumulated_length: number; // total text length so far
+}
+```
+
+**ToolCallStart** — a tool invocation begins:
+```typescript
+interface ToolCallStart {
+  type: "tool_call_start";
+  message_id: string;
+  part_index: number;
+  tool_call_id: string;
+  tool_name: string;
+}
+```
+
+**ToolCallDelta** — tool arguments are being built:
+```typescript
+interface ToolCallDelta {
+  type: "tool_call_delta";
+  message_id: string;
+  part_index: number;
+  tool_call_id: string;
+  arguments_delta: string;  // JSON fragment of arguments
+}
+```
+
+**ToolResultStart** — tool execution has begun:
+```typescript
+interface ToolResultStart {
+  type: "tool_result_start";
+  message_id: string;
+  part_index: number;
+  tool_call_id: string;
+  title?: string;
+}
+```
+
+**ToolResultDelta** — streaming tool output:
+```typescript
+interface ToolResultDelta {
+  type: "tool_result_delta";
+  message_id: string;
+  part_index: number;
+  tool_call_id: string;
+  content: string;          // output chunk
+}
+```
+
+**ToolResultEnd** — tool execution completed:
+```typescript
+interface ToolResultEnd {
+  type: "tool_result_end";
+  message_id: string;
+  part_index: number;
+  tool_call_id: string;
+  is_error: boolean;
+  duration_ms: number;
+}
+```
+
+**MetadataDelta** — updated token counts and cost:
+```typescript
+interface MetadataDelta {
+  type: "metadata_delta";
+  message_id: string;
+  input_tokens: number;     // cumulative input tokens
+  output_tokens: number;    // cumulative output tokens
+  cost: number;             // estimated cost so far (USD)
+}
+```
+
+**Complete** — message generation finished:
+```typescript
+interface Complete {
+  type: "complete";
+  message_id: string;
+  final_metadata: MessageMetadata;
+  stop_reason: "end_turn" | "max_tokens" | "tool_use" | "cancelled";
+}
+```
+
+### Streaming Pipeline
+
+The streaming pipeline processes LLM output through these stages:
+
+1. **LLM Stream:** the model provider emits raw chunks (text tokens, tool use blocks)
+2. **Delta Parser:** converts raw chunks into typed Delta events
+3. **Part Assembler:** accumulates deltas into complete Parts for persistence
+4. **Delta Emitter:** sends deltas to connected clients via the event bus (RISE-002)
+5. **Persistence:** when complete, the assembled message and parts are written to the database
+
+```
+LLM API → Delta Parser → Part Assembler → Database
+                ↓
+          Delta Emitter → Event Bus → Client(s)
+```
+
+### Client Rendering
+
+The client receives deltas and updates the display:
+
+- **TextDelta:** append text to the current text block, re-render markdown
+- **ToolCallStart:** create a new tool call panel with the tool name
+- **ToolCallDelta:** progressively render JSON arguments in the panel
+- **ToolResultStart:** show a "running..." indicator beneath the tool call
+- **ToolResultDelta:** append output lines to the result area
+- **ToolResultEnd:** update the indicator to success/failure with duration
+- **MetadataDelta:** update the token/cost counter in the status bar
+- **Complete:** finalize rendering, remove any "generating..." indicators
+
+### Cancellation
+
+At any point during streaming, the developer can cancel:
+
+1. User presses Ctrl+C or clicks cancel
+2. Client sends an abort signal to the server (or locally to the agent)
+3. The abort signal propagates to the LLM API call, stopping generation
+4. The Delta Parser emits a `Complete` event with `stop_reason: "cancelled"`
+5. The Part Assembler finalizes with whatever content was received
+6. Partial content is persisted — the message exists with whatever parts were completed
+7. Token billing stops at the cancellation point
+
+### Delivery Mechanisms
+
+Deltas reach clients through multiple transport options:
+
+**Local (CLI):** deltas flow directly through in-process event bus to the TUI renderer. Zero network overhead.
+
+**SSE (HTTP):** for client-server architecture (RISE-001), deltas are serialized as Server-Sent Events on the `/sessions/:id/events` endpoint. Each delta is a JSON event with a type field.
+
+**WebSocket (future):** for bidirectional communication, deltas flow over WebSocket with the same JSON format.
+
+### Backpressure and Buffering
+
+- If the client cannot render as fast as deltas arrive, a small buffer (default: 100 deltas) absorbs bursts
+- If the buffer fills, deltas are coalesced: multiple TextDeltas merge into one larger chunk
+- MetadataDeltas are sampled: at most one per 500ms reaches the client
+- Coalescing preserves correctness — the final assembled message is identical regardless of delta granularity
+
+### Error Handling During Streaming
+
+- **LLM connection drop:** emit an ErrorPart, then Complete with `stop_reason: "cancelled"`
+- **Tool execution failure:** emit ToolResultEnd with `is_error: true`, continue with next LLM turn
+- **Client disconnect:** streaming continues server-side; deltas are buffered for reconnection
+- **Rate limit:** emit MetadataDelta with rate limit info, pause, then resume streaming
+
+## Supporting Structures
+
+- **Message Parts Model (RISE-026)** defines the Part types that deltas assemble into
+- **Client-Server Architecture (RISE-001)** provides SSE transport for remote streaming
+- **Event Bus (RISE-002)** distributes deltas to all connected clients
+- **Session Persistence (RISE-018)** stores the final assembled message and parts
+- **Structured Logging (RISE-007)** logs streaming metrics: delta count, latency, coalescing events
+- **Named Error System (RISE-006)** provides StreamAbortedError, DeltaParseError, BackpressureError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Instant Feedback:**
+The developer sends a complex prompt. Within 200ms, the first word appears. They immediately see the agent is on the right track — discussing the correct file and approach. Without streaming, they would have waited 15 seconds before seeing anything, wondering if the agent understood.
+
+**Scenario 2 — Early Cancellation:**
+The agent starts generating a response that misunderstands the task. After seeing 3 sentences of wrong-headed approach, the developer hits Ctrl+C. Generation stops, saving ~2000 tokens of wasted output. The developer rephrases and tries again — fast iteration without cost penalty.
+
+**Scenario 3 — Progressive Tool Visualization:**
+The agent calls `grep` to search a codebase. The ToolCallStart appears with "grep" and the search pattern. ToolResultDelta events stream matching lines as grep finds them. The developer sees results populating in real-time, understanding what the agent is finding before the search completes.
+
+**Scenario 4 — Real-Time Cost Monitoring:**
+During an expensive operation (large file analysis), the MetadataDelta updates show token count climbing: 1k, 5k, 10k, 15k. The developer sees costs approaching their budget. At 18k tokens, they cancel — staying within budget. Without streaming cost updates, they would have discovered the overage only after the response completed.

package/rispecs/borrowed_from_opencode/028-multi-provider-architecture.rispec.md

@@ -0,0 +1,184 @@
+# RISE-028: Multi-Provider Architecture
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/028-multi-provider-architecture.rispec.md
+
+## Creative Intent
+
+mia-code abstracts away the specifics of individual LLM providers behind a unified interface, enabling developers to switch between 20+ providers — OpenAI, Anthropic, Google Gemini, Mistral, Groq, XAI, and more — without changing agent definitions, tool configurations, or workflow logic. Instead of shelling out to CLI binaries with bespoke argument parsing, mia-code communicates through a common provider contract. A developer can start a session with Claude, switch mid-project to GPT for cost reasons, and later deploy with a self-hosted model — all through the same interface. The provider becomes a pluggable detail, not a structural commitment.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- mia-code supports Gemini and Claude by shelling out to their respective CLI binaries (`gemini`, `claude`)
+- Each provider integration is a custom shell script with provider-specific argument formatting
+- Adding a new provider requires writing a new shell integration from scratch
+- No shared interface exists — each provider has its own calling convention, output parsing, and error handling
+- Model selection is tightly coupled to the binary name rather than a provider abstraction
+- There is no fallback mechanism — if the configured CLI binary is unavailable, the session fails
+- Provider capabilities (streaming, vision, function calling) are implicit, not declared
+
+**Desired State:**
+- A common `Provider` interface defines the contract all providers implement
+- 20+ providers are available out of the box, each implementing the same interface
+- Provider configuration lives in `mia-code.json` with a consistent schema
+- Provider selection is explicit in agent config or inferred from the model ID prefix
+- Fallback chains allow automatic failover when a provider is unavailable or rate-limited
+- Custom providers can be added via the OpenAI-compatible API base class
+- Provider capabilities are declared and queryable, enabling intelligent feature gating
+
+## Desired Outcome Definition
+
+A developer configures three providers in `mia-code.json`: Anthropic as primary, OpenAI as fallback, and a local Ollama instance for offline work. When they invoke an agent, the system resolves the model ID to the correct provider, initializes it with stored credentials, and communicates through the unified interface. If Anthropic returns a rate limit error, the system automatically falls through to OpenAI with the equivalent model. The developer sees a brief notification of the fallback but their workflow is uninterrupted.
+
+## Natural Language Functional Description
+
+### Provider Interface
+
+Every provider implements this contract:
+
+```typescript
+interface Provider {
+  id: string;                    // e.g. "anthropic", "openai", "groq"
+  name: string;                  // e.g. "Anthropic", "OpenAI", "Groq"
+  apiEndpoint: string;           // base URL for API calls
+  authMethod: "api_key" | "oauth" | "custom";
+
+  initialize(config: ProviderConfig): Promise<void>;
+  chat(messages: Message[], options: ChatOptions): Promise<AssistantMessage>;
+  stream(messages: Message[], options: StreamOptions): AsyncIterable<Delta>;
+  listModels(): Promise<ModelInfo[]>;
+}
+
+interface ProviderConfig {
+  apiKey?: string;               // direct key or ${ENV_VAR} reference
+  baseURL?: string;              // override default endpoint
+  organizationId?: string;       // for multi-tenant providers
+  projectId?: string;            // for scoped access (Vertex, Bedrock)
+  customHeaders?: Record<string, string>;
+  timeout?: number;              // request timeout in ms (default: 120000)
+  maxRetries?: number;           // retry count (default: 3)
+}
+
+interface ChatOptions {
+  model: string;                 // model ID within this provider
+  temperature?: number;
+  maxTokens?: number;
+  tools?: ToolDefinition[];
+  systemPrompt?: string;
+  stopSequences?: string[];
+  responseFormat?: "text" | "json";
+}
+```
+
+### Supported Providers
+
+The following providers are supported with dedicated implementations:
+
+| Provider | ID | Auth Method | Notable Capabilities |
+|---|---|---|---|
+| OpenAI | `openai` | api_key | GPT-4o, o1, o3, function calling, vision, JSON mode |
+| Anthropic | `anthropic` | api_key | Claude family, extended thinking, cache control |
+| Google Gemini API | `google` | api_key | Gemini 2.5, grounding, long context |
+| Mistral | `mistral` | api_key | Mistral Large, code generation, function calling |
+| Groq | `groq` | api_key | Ultra-fast inference, Llama/Mixtral hosting |
+| XAI | `xai` | api_key | Grok models |
+| DeepInfra | `deepinfra` | api_key | Open model hosting, competitive pricing |
+| Cerebras | `cerebras` | api_key | Wafer-scale inference, extreme speed |
+| Cohere | `cohere` | api_key | Command R+, RAG-optimized, reranking |
+| Azure OpenAI | `azure` | api_key/oauth | Enterprise OpenAI, regional deployments |
+| Google Vertex AI | `vertex` | oauth | Gemini via GCP, enterprise features |
+| Amazon Bedrock | `bedrock` | custom | Multi-model access via AWS, IAM auth |
+| GitHub Copilot | `copilot` | oauth | Copilot API access, GitHub-integrated auth |
+| OpenRouter | `openrouter` | api_key | Multi-model gateway, unified billing |
+| Together.AI | `together` | api_key | Open model hosting, fine-tuning |
+| Custom (OpenAI-compat) | `custom` | api_key | Any OpenAI-compatible endpoint |
+
+### Configuration Schema
+
+Provider configuration in `mia-code.json`:
+
+```json
+{
+  "provider": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}",
+      "baseURL": "https://api.anthropic.com"
+    },
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}"
+    },
+    "custom": {
+      "apiKey": "sk-local-...",
+      "baseURL": "http://localhost:11434/v1",
+      "name": "Local Ollama"
+    }
+  }
+}
+```
+
+### Provider Resolution
+
+When a model ID is specified (e.g. `claude-sonnet-4-20250514`), the system resolves it to a provider:
+
+1. **Explicit provider:** agent config specifies `provider: "anthropic"` — use that provider directly
+2. **Model prefix match:** model ID is looked up in the model registry (RISE-030) which maps models to providers
+3. **Fallback scan:** iterate configured providers, call `listModels()`, find which provider serves this model
+4. **Error:** if no provider serves the model, emit a `ProviderResolutionError` with suggestions
+
+### Fallback Chains
+
+Fallback is configured per-agent or globally:
+
+```json
+{
+  "fallback": ["anthropic", "openai", "custom"],
+  "fallbackTriggers": ["rate_limit", "auth_failure", "server_error"]
+}
+```
+
+When the primary provider returns a triggering error:
+1. Log the failure with provider ID, error type, and model
+2. Select the next provider in the fallback chain
+3. Map the model to an equivalent on the fallback provider (e.g. `claude-sonnet-4-20250514` → `gpt-4o`)
+4. Retry the request on the fallback provider
+5. Notify the developer of the fallback via a status message
+
+### Custom Provider Registration
+
+Developers can register custom providers for OpenAI-compatible endpoints:
+
+```typescript
+interface CustomProviderConfig extends ProviderConfig {
+  id: string;                    // unique custom provider ID
+  name: string;                  // display name
+  models?: ModelInfo[];          // manually declared model list
+  capabilities?: string[];      // e.g. ["streaming", "function_calling"]
+}
+```
+
+Custom providers inherit the OpenAI-compatible base implementation and only need endpoint and auth configuration.
+
+## Supporting Structures
+
+- **Provider Authentication (RISE-029)** handles credential management for each provider
+- **Model Registry (RISE-030)** maps model IDs to providers and capabilities
+- **Provider Transform Pipeline (RISE-032)** normalizes request/response formats per provider
+- **Provider SDK Abstraction (RISE-033)** wraps low-level API communication
+- **Agent Definition Config (RISE-010)** references providers in agent model selection
+- **Named Error System (RISE-006)** provides ProviderResolutionError, ProviderUnavailableError, FallbackExhaustedError
+- **Structured Logging (RISE-007)** logs provider selection, fallback events, and latency metrics
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Seamless Provider Switch:**
+A developer has been using Claude for a complex refactoring session. Anthropic's API goes down for maintenance. mia-code automatically falls back to OpenAI, mapping `claude-sonnet-4-20250514` to `gpt-4o`. The developer sees "⚠ Switched to OpenAI (Anthropic unavailable)" and continues working without restarting the session or reconfiguring anything.
+
+**Scenario 2 — Cost-Optimized Agent Hierarchy:**
+A developer configures the main coding agent with `claude-sonnet-4-20250514` (high capability) and the explore sub-agent with `llama-3.1-70b` on Groq (fast and cheap). Each agent uses its designated provider through the same interface. The developer gets quality where it matters and speed where it doesn't — all through provider configuration, not code changes.
+
+**Scenario 3 — Air-Gapped Development:**
+A developer on a classified network configures a custom provider pointing to a self-hosted vLLM instance at `http://internal-gpu:8000/v1`. They register it as an OpenAI-compatible custom provider with their organization's fine-tuned model. mia-code treats it identically to any cloud provider — same tools, same streaming, same session management.
+
+**Scenario 4 — Provider Evaluation:**
+A team wants to compare Claude vs GPT vs Gemini for their codebase. They configure all three providers and run the same set of tasks, switching the agent's model between runs. Cost tracking (RISE-031) records per-provider expenses. After a week, they have concrete data on quality, speed, and cost per provider — enabling an informed decision.