mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/058-rich-tui.rispec.md

@@ -0,0 +1,108 @@
+# RISE-058: Rich Terminal User Interface
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/058-rich-tui.rispec.md
+
+## Creative Intent
+
+mia-code replaces its basic readline-driven interface with a full-featured terminal user interface that treats the terminal as a spatial canvas. Users experience a structured layout — scrollable conversation history, persistent status bar, distinct message bubbles — that makes extended agent sessions legible and navigable. The TUI transforms the terminal from a scroll-only log into an application with panes, focus, and visual hierarchy.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code uses basic readline for input, chalk for colors, and ora for spinners — everything scrolls linearly
+- There is no separation between input area and output area; the input prompt scrolls with agent output
+- Users cannot scroll back through conversation history without terminal scrollback (which mixes mia-code output with other terminal output)
+- No status bar shows session context, active agent, mode, or cost
+- Messages from user and assistant look similar — role distinction relies on text prefixes only
+- Tool execution output is dumped inline with no visual containment or collapsibility
+- The interface assumes infinite vertical scroll and never reclaims vertical space
+
+**Desired State:**
+- The terminal is divided into distinct panes: message history (scrollable), status bar (fixed), input area (fixed at bottom)
+- Messages are rendered as visual bubbles with role indicators — user messages right-aligned or distinctly colored, assistant messages left-aligned
+- Tool execution results appear in collapsible panels that show tool name and can be expanded/collapsed
+- A persistent status bar shows: session title, active agent, current mode (plan/build), model name, and cumulative cost
+- The user can scroll through conversation history independent of input focus
+- The interface adapts to terminal width (minimum 80x24) and degrades gracefully in non-TTY environments
+
+## Desired Outcome Definition
+
+Running `mia-code` in a TTY terminal presents a split-pane layout. The top region shows scrollable message history with role-colored bubbles. The bottom region is a fixed input area that always has focus. A status bar separates them. Tool outputs appear as collapsible panels within the message flow. In non-TTY environments (pipes, CI), mia-code falls back to basic line-by-line output.
+
+## Natural Language Functional Description
+
+### Layout Structure
+
+The TUI divides the terminal into three vertical regions:
+
+1. **Message Pane** — occupies the majority of vertical space. Displays conversation history as styled message blocks. Each message shows a role indicator (🧑 User, 🤖 Assistant, 🔧 Tool). Messages wrap to terminal width with padding. The pane is independently scrollable via keyboard (Page Up/Down, mouse wheel if supported).
+
+2. **Status Bar** — a single fixed line between message pane and input area. Displays: session name or ID, active agent name, current mode (plan/build), model identifier, token count or cost estimate. Updated in real-time as the session progresses.
+
+3. **Input Area** — fixed at the bottom, 1-5 lines tall (auto-expanding for multiline input). Always captures keyboard input. Supports Ctrl+J for newline within input. Enter submits. Shows placeholder text when empty.
+
+### Message Rendering
+
+Each message renders as a block with:
+- Role icon and label (colored per role)
+- Timestamp (dim, right-aligned)
+- Content body with markdown rendering (headers, bold, lists, code blocks)
+- Tool call results in bordered sub-panels with tool name header
+
+### Tool Execution Panels
+
+When a tool executes, a panel appears in the message flow:
+- Header line: tool name + status (running/complete/failed) + elapsed time
+- Body: tool output, initially collapsed for long outputs (>10 lines)
+- Toggle: keyboard shortcut or click to expand/collapse
+- Running tools show a spinner in the header
+
+### Focus Management
+
+- Input area has focus by default — all typing goes to input
+- Ctrl+Up or Page Up switches focus to message pane for scrolling
+- Escape or typing any character returns focus to input
+- Focus indicator: subtle border highlight on the active pane
+
+### Color Theming
+
+Themes are defined as JSON objects mapping semantic roles to terminal colors:
+- `userMessage`, `assistantMessage`, `toolPanel`, `statusBar`, `inputBorder`, `error`, `warning`
+- Built-in themes: `dark` (default), `light`, `monochrome`
+- Custom themes loadable from config: `{"theme": "dark"}` or `{"theme": {"userMessage": "blue", ...}}`
+
+### Responsive Behavior
+
+- At widths below 80 columns: status bar truncates, message padding reduces
+- At widths below 40 columns: falls back to basic linear mode
+- Terminal resize events trigger re-render of all visible content
+- Minimum supported size: 80 columns × 24 rows
+
+### Graceful Degradation
+
+- Non-TTY (piped stdin/stdout): plain text output, no colors, no layout
+- Dumb terminals (TERM=dumb): basic ANSI colors, no cursor positioning
+- Screen readers: message content emitted as plain text blocks
+
+## Supporting Structures
+
+- **Streaming Display (RISE-059)** renders agent responses progressively within the message pane
+- **Permission Prompts (RISE-060)** display inline in the input area as modal prompts
+- **Keybinding System (RISE-063)** provides configurable shortcuts for all TUI interactions
+- **Syntax Highlighting (RISE-062)** colors code blocks within messages
+- **Session Navigation (RISE-061)** provides an overlay navigator within the TUI
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Extended Refactoring Session:**
+A developer runs a 45-minute refactoring session. The TUI keeps the status bar showing elapsed time and token cost. When the agent executes 12 file edits, each appears as a collapsible tool panel. The developer scrolls back to review earlier edits while the agent continues working — input focus stays at the bottom, scroll focus is in the history pane.
+
+**Scenario 2 — Narrow Terminal on a Laptop:**
+A developer uses mia-code in a split-screen terminal at 90 columns. The TUI adapts: status bar shows abbreviated info, message padding narrows, but all functionality remains. They resize to full-width and the layout instantly reflows.
+
+**Scenario 3 — CI Pipeline with No TUI:**
+A CI script pipes a prompt to mia-code: `echo "Review this PR" | mia-code`. The TUI detects non-TTY and emits plain text. No escape sequences, no cursor positioning. The output is clean for log capture.
+
+**Scenario 4 — Custom Theme for Accessibility:**
+A developer with color vision differences creates a custom theme in their config that uses high-contrast colors and distinct patterns (bold, underline) instead of relying solely on color. They set `{"theme": {"userMessage": "bold white", "assistantMessage": "underline cyan"}}` and every session uses their preferred visual style.

package/rispecs/borrowed_from_opencode/059-streaming-display.rispec.md

@@ -0,0 +1,116 @@
+# RISE-059: Streaming Display
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/059-streaming-display.rispec.md
+
+## Creative Intent
+
+mia-code renders agent responses as they arrive, token by token and chunk by chunk, creating a fluid, typewriter-like experience that keeps the developer engaged and informed. Rather than waiting for a complete response to appear as a monolithic block, the streaming display reveals the agent's thinking in real-time — making latency invisible and giving developers the ability to interrupt early if the response heads in the wrong direction.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Agent responses arrive as complete blocks after the full generation finishes — developers stare at an ora spinner
+- There is no visual feedback during generation beyond "thinking..." or a spinner animation
+- Tool call results appear all at once after execution completes
+- Code blocks in responses are rendered only after the entire response is assembled
+- Markdown formatting (headers, bold, lists) is applied post-hoc to completed text
+- Ctrl+C during generation kills the entire process rather than gracefully stopping generation
+- Network latency and generation time are indistinguishable to the user
+
+**Desired State:**
+- Text appears character-by-character or chunk-by-chunk as the LLM generates it
+- Tool calls are announced immediately when the agent decides to call them, with a spinner during execution
+- Code blocks receive progressive syntax highlighting as content streams in
+- Markdown is rendered incrementally — a `#` becomes a header as soon as the line completes
+- Ctrl+C stops generation cleanly, preserving the partial response in the conversation
+- A blinking cursor at the stream's leading edge shows exactly where new content will appear
+- Tool execution shows elapsed time on a live-updating spinner
+
+## Desired Outcome Definition
+
+When the agent generates a response, text appears in the message pane progressively. The user sees words forming in real-time. Tool calls show their name and a spinner while executing, then reveal results. The user can cancel mid-stream with Ctrl+C and the partial response is preserved. Code blocks are syntax-highlighted as they grow. The experience feels immediate and alive.
+
+## Natural Language Functional Description
+
+### Text Streaming
+
+As the LLM produces tokens, the TUI appends them to the current message in the message pane:
+
+1. Each chunk received from the provider API (typically 1-5 tokens) is immediately rendered
+2. The message pane auto-scrolls to keep the latest content visible (unless the user has scrolled up)
+3. A blinking cursor character (▊) appears at the end of the stream to indicate active generation
+4. When generation completes, the cursor disappears and the message finalizes
+
+### Markdown Progressive Rendering
+
+Markdown elements are rendered as they become complete:
+- **Headers**: `#` characters at line start render as styled headers when the line ends (newline received)
+- **Bold/Italic**: opening `**` or `*` buffers until the closing marker arrives, then applies styling
+- **Lists**: `-` or `1.` at line start indents and applies list styling at newline
+- **Code fences**: opening ``` triggers code block mode; content inside receives syntax highlighting progressively; closing ``` ends the block
+- **Links**: `[text](url)` renders as clickable (where terminal supports) once the closing `)` arrives
+
+Incomplete markdown markers are shown as literal characters until their pair arrives.
+
+### Tool Call Display
+
+When the agent emits a tool call:
+1. A tool panel header appears immediately: `🔧 [tool_name] ⏳ 0.0s`
+2. The elapsed time updates every 100ms while the tool runs
+3. Tool parameters are shown in a dimmed sub-line (truncated if long)
+4. When the tool completes, the spinner becomes ✓ (success) or ✗ (failure)
+5. Tool output is revealed progressively if the tool streams output (e.g., bash command output)
+6. Long tool outputs (>10 lines) auto-collapse with a "show more" indicator
+
+### Code Block Streaming
+
+Code blocks receive special treatment during streaming:
+1. When ` ``` ` with a language tag is detected, the block enters code mode
+2. Each new line of code receives syntax highlighting as it arrives
+3. The code block grows visually line by line with proper indentation preserved
+4. Line numbers (if enabled) increment as lines arrive
+5. When the closing ` ``` ` arrives, the block finalizes and a border renders around it
+
+### Streaming Cancellation
+
+Ctrl+C during active streaming:
+1. Sends a cancellation signal to the provider API (aborts the HTTP request)
+2. The partial response up to the cancellation point is preserved in the message history
+3. A `[generation cancelled]` indicator appends to the partial message
+4. The input area re-activates for the next user prompt
+5. The cancelled message is stored in the session — it does not disappear
+
+### Performance Considerations
+
+- Rendering is throttled to 60fps maximum to avoid terminal flicker
+- Large chunks (>1000 characters) are broken into smaller render batches
+- Syntax highlighting runs asynchronously and may lag slightly behind raw text display
+- The message pane only re-renders visible lines; off-screen content is not re-rendered until scrolled into view
+
+### Network Latency Handling
+
+- Time-to-first-token is tracked and displayed in debug mode
+- If no chunk arrives within 5 seconds, a subtle "waiting for response..." indicator appears
+- Connection drops during streaming show an error indicator and offer retry
+
+## Supporting Structures
+
+- **Rich TUI (RISE-058)** provides the message pane and layout where streaming content renders
+- **Syntax Highlighting (RISE-062)** applies language-aware coloring to code blocks during streaming
+- **Event Bus (RISE-002)** delivers streaming chunks from the agent process to the rendering layer
+- **Client-Server Architecture (RISE-001)** enables SSE-based streaming for remote clients
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Watching Code Emerge:**
+A developer asks the agent to implement a sorting algorithm. They watch the function definition appear line by line, with syntax highlighting applied as each line completes. They see the approach forming and can Ctrl+C if the agent picks the wrong algorithm, saving tokens and time.
+
+**Scenario 2 — Long Explanation with Early Insight:**
+The agent begins a detailed explanation. The developer reads the first paragraph as it streams, realizes they already understand, and presses Ctrl+C. The partial explanation is saved. They ask a follow-up question immediately.
+
+**Scenario 3 — Multiple Tool Executions:**
+The agent runs three tools in sequence. Each tool panel appears with its spinner, showing elapsed time. The developer sees `bash ✓ 2.3s`, then `file_read ✓ 0.1s`, then `bash ⏳ 15.2s` — they know the third command is slow and can decide whether to wait or cancel.
+
+**Scenario 4 — Slow Network Connection:**
+A developer on a train with spotty connectivity uses mia-code. The streaming display handles intermittent chunks gracefully — text appears in bursts rather than a steady flow, but no content is lost. The "waiting for response..." indicator appears during gaps, then disappears when chunks resume.

package/rispecs/borrowed_from_opencode/060-permission-prompts.rispec.md

@@ -0,0 +1,130 @@
+# RISE-060: Permission Prompts
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/060-permission-prompts.rispec.md
+
+## Creative Intent
+
+mia-code gives developers fine-grained, moment-of-decision control over what the agent is allowed to do. When a permission rule requires user approval, an interactive prompt appears that clearly describes the operation, its scope, and its risk level — and offers a range of responses from "allow once" to "never allow again." The developer stays in command without being overwhelmed by constant interruptions, because their choices accumulate into a personalized permission profile.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Permission rules in mia-code are either "allow" or "deny" — there is no interactive "ask" mode
+- When an operation is denied, the agent simply cannot proceed; the user has no chance to override
+- There is no visual distinction between low-risk operations (reading a file) and high-risk ones (running `rm -rf`)
+- Permission decisions are static — set once in config, never refined through use
+- The developer must anticipate every tool and command the agent might use and pre-configure permissions
+- No mechanism exists to grant temporary session-scoped permissions
+
+**Desired State:**
+- Permission rules support an "ask" mode that pauses execution and prompts the user
+- The prompt shows exactly what the agent wants to do: tool name, operation details, affected paths
+- The user chooses from: allow once (y), deny once (n), always allow (a), never allow (v), session-only (s)
+- "Always" and "never" choices persist to the config file, building the user's permission profile over time
+- "Session" choices persist until the session ends, reducing prompt fatigue for repeated operations
+- Destructive operations (file deletion, arbitrary bash) are visually distinguished from safe ones (file read)
+
+## Desired Outcome Definition
+
+When a permission rule is set to "ask" and the agent invokes that tool, execution pauses. A formatted prompt appears in the input area showing the tool name, the specific operation, and the affected resources. The user presses a single key to respond. Their choice is applied immediately and, for persistent choices, written to config.
+
+## Natural Language Functional Description
+
+### Prompt Display
+
+When a permission check triggers an "ask" prompt, the TUI renders:
+
+```
+┌─ Permission Required ──────────────────────────────┐
+│ Tool: bash                                          │
+│ Command: npm install express                        │
+│                                                     │
+│ [y] Allow once  [n] Deny once  [a] Always allow     │
+│ [v] Never allow [s] Allow for session               │
+└─────────────────────────────────────────────────────┘
+```
+
+The prompt replaces the input area temporarily. All other input is blocked until the user responds.
+
+### Operation Details
+
+The prompt content varies by tool type:
+
+- **bash**: Shows the exact command string. Destructive commands (rm, mv to /dev/null, chmod 777) render with a warning color (yellow/red background).
+- **file_write / file_edit**: Shows the file path and operation type (create, overwrite, append, edit). If the file exists, notes "existing file will be modified."
+- **file_read**: Shows the file path. Rendered in info color (blue/cyan) as low-risk.
+- **glob / grep**: Shows the search pattern and scope directory. Low-risk, info color.
+- **Custom tools**: Show tool name and all parameters in a readable format.
+
+### Response Handling
+
+Each response key triggers a specific action:
+
+| Key | Action | Persistence |
+|-----|--------|-------------|
+| `y` | Allow this specific invocation to proceed | None — next invocation of same tool asks again |
+| `n` | Deny this specific invocation | None — next invocation asks again |
+| `a` | Allow and add a permanent rule to config | Writes to project or global config |
+| `v` | Deny and add a permanent rule to config | Writes to project or global config |
+| `s` | Allow for the remainder of this session | In-memory until session ends |
+
+### Permanent Rule Writing
+
+When the user presses `a` (always) or `v` (never):
+1. The permission rule is added to the nearest writable config (project config if it exists, otherwise global)
+2. The rule is scoped appropriately: bash commands match the command prefix, file operations match the path pattern
+3. Example: allowing `npm install express` adds a rule like `{"bash": {"allow": ["npm install *"]}}`
+4. The user sees a confirmation: "Rule added to .mia-code/config.json"
+
+### Session-Scoped Permissions
+
+When the user presses `s` (session):
+1. The permission is stored in the session's in-memory permission cache
+2. Subsequent identical tool invocations (same tool + same or similar parameters) are auto-allowed
+3. The session permission cache is cleared when the session ends
+4. Session permissions are not written to any file
+
+### Risk-Level Visual Styling
+
+Operations are categorized by risk level:
+- **High risk** (red/yellow): bash commands with side effects, file deletion, network requests to unknown hosts
+- **Medium risk** (yellow): file writes, file edits, directory creation
+- **Low risk** (blue/cyan): file reads, grep, glob, LSP queries
+- **Info** (dim): read-only operations that rarely need restriction
+
+The prompt border color and icon reflect the risk level.
+
+### Keyboard Shortcut Behavior
+
+- Only the documented keys (y, n, a, v, s) are accepted — all other input is ignored
+- Keys are case-insensitive (Y and y both work)
+- No Enter key required — single keypress triggers the action immediately
+- Escape is equivalent to `n` (deny once)
+
+### Timeout Behavior
+
+- If no response is received within a configurable timeout (default: 5 minutes), the operation is denied
+- A countdown timer appears in the prompt after 30 seconds of inactivity
+- Timeout behavior is configurable: `{"permissions": {"askTimeout": 300, "askTimeoutAction": "deny"}}`
+
+## Supporting Structures
+
+- **Agent Permission Rulesets (RISE-011)** define which operations require "ask" vs. "allow" vs. "deny"
+- **Rich TUI (RISE-058)** provides the input area where permission prompts render
+- **Multi-Level Config (RISE-064)** determines where permanent permission rules are written
+- **Keybinding System (RISE-063)** ensures permission prompt keys don't conflict with other bindings
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — First-Time Trust Building:**
+A new user starts mia-code with default permissions set to "ask" for all bash commands. The agent wants to run `git status` — the prompt appears, the user presses `a` to always allow git commands. Over several sessions, they build a personalized permission profile: git always allowed, npm always allowed, rm always denied, everything else asks.
+
+**Scenario 2 — Reviewing a Dangerous Command:**
+The agent decides to run `find / -name "*.log" -delete`. The prompt appears with high-risk red styling. The user sees the full command, recognizes the danger, and presses `n`. The agent receives the denial and proposes a safer alternative.
+
+**Scenario 3 — Repetitive File Edits:**
+The agent needs to edit 15 files in a refactoring. After the first permission prompt for file_edit, the user presses `s` (session). The remaining 14 edits proceed without prompts. In the next session, permission prompts resume.
+
+**Scenario 4 — Team Policy Enforcement:**
+An organization's managed config sets bash commands to "ask" with no override. Even if a developer presses `a`, the managed policy prevents permanent allow rules for bash. The prompt shows: "Organization policy: bash permissions cannot be permanently allowed."

package/rispecs/borrowed_from_opencode/061-session-navigation.rispec.md

@@ -0,0 +1,155 @@
+# RISE-061: Session Navigation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/061-session-navigation.rispec.md
+
+## Creative Intent
+
+mia-code lets developers move between sessions as fluidly as switching browser tabs. A developer working across multiple features, debugging tasks, or code reviews can jump between sessions without losing context — each session preserved exactly where they left it. The session navigator is a first-class TUI component that makes session management a visual, interactive experience rather than a command-line chore.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Session switching requires knowing the session ID and using a command like `/session <id>`
+- There is no visual overview of available sessions — developers must remember or list them manually
+- Session metadata (last activity, message count, project) is not visible at a glance
+- No search or filter capability exists for sessions
+- Creating a new session requires exiting the current context or using a slash command
+- There is no session preview — switching to a session is the only way to see its content
+- Sessions cannot be archived or deleted from within the TUI
+
+**Desired State:**
+- A keyboard shortcut (Ctrl+S) opens an interactive session navigator overlay
+- The navigator shows all sessions in a scrollable list with metadata: title, project, last activity, message count
+- Arrow keys navigate, Enter selects, typing filters the list in real-time
+- Hovering on a session shows a preview of the last few messages
+- Sessions are grouped by project or date for easy browsing
+- The navigator supports creating new sessions and archiving/deleting existing ones
+- Recent sessions (last 5) appear at the top for quick access
+
+## Desired Outcome Definition
+
+Pressing Ctrl+S opens a modal overlay listing all sessions. The developer navigates with arrow keys, filters by typing, sees metadata and previews, and selects a session with Enter. The overlay closes and the TUI switches to the selected session. The developer can also create, archive, or delete sessions from the navigator.
+
+## Natural Language Functional Description
+
+### Navigator Overlay
+
+The session navigator renders as a full-screen overlay on top of the message pane:
+
+```
+┌─ Sessions ──────────────────── Filter: _____________┐
+│                                                      │
+│ ★ Recent                                             │
+│   ▸ Refactor auth module        myapp   2m ago  47msg│
+│     Debug payment webhook       myapp   1h ago  12msg│
+│     Review PR #234              lib     3h ago   8msg│
+│                                                      │
+│ 📁 myapp                                             │
+│     Setup CI pipeline           myapp   1d ago  23msg│
+│     Database migration          myapp   2d ago  31msg│
+│                                                      │
+│ 📁 lib                                               │
+│     Add streaming support       lib     1d ago  55msg│
+│                                                      │
+│ 📦 Archived                                          │
+│     Old debugging session       myapp   7d ago  15msg│
+│                                                      │
+├──────────────────────────────────────────────────────┤
+│ Preview: "Let me refactor the auth middleware to..." │
+│          "I'll update the JWT validation logic..."   │
+└──────────────────────────────────────────────────────┘
+```
+
+### List Rendering
+
+Each session row displays:
+- Selection indicator (▸ for current cursor position)
+- Session title (auto-generated from first prompt or user-set)
+- Project name (derived from project root directory name)
+- Relative time since last activity ("2m ago", "1d ago")
+- Message count
+- Status icon: 🟢 active, 📦 archived, ⚡ currently selected
+
+### Navigation Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Move selection cursor |
+| Enter | Switch to selected session |
+| Ctrl+N | Create new session |
+| Ctrl+D | Archive/delete selected session (with confirmation) |
+| Escape | Close navigator without switching |
+| Any letter | Start filtering by title/project |
+| Backspace | Clear filter character |
+| Tab | Cycle through grouping modes (project, date, status) |
+
+### Filtering
+
+Typing any character while the navigator is open enters filter mode:
+- The filter input appears at the top right of the overlay
+- Sessions are filtered in real-time by matching against title, project name, and session ID
+- Filtering is case-insensitive and supports substring matching
+- Empty filter shows all sessions
+- Filter persists until cleared with Backspace or Escape
+
+### Session Grouping
+
+Sessions can be grouped by three modes (cycled with Tab):
+1. **By project**: sessions under their project root directory name
+2. **By date**: Today, Yesterday, This Week, Older
+3. **By status**: Active, Archived
+
+The current grouping mode is remembered across navigator opens within the same session.
+
+### Session Preview
+
+When the cursor rests on a session for more than 300ms:
+- A preview panel appears at the bottom of the overlay
+- Shows the last 2-3 messages (truncated) from that session
+- Preview updates as the cursor moves
+- Preview can be toggled off with `p` key
+
+### Session Management
+
+**Create new session**: Ctrl+N opens a minimal dialog asking for an optional title and project root. If no project root is specified, the current working directory is used. The new session is created and immediately selected.
+
+**Archive session**: Ctrl+D on a session shows a confirmation prompt ("Archive this session? y/n"). Archived sessions move to the "Archived" group and are hidden by default. They can be shown by switching to "By status" grouping.
+
+**Delete session**: Shift+Ctrl+D permanently deletes a session (with confirmation). This removes the session from storage entirely.
+
+### Quick Access
+
+The `/sessions` slash command also opens the navigator (alternative to Ctrl+S). Additionally:
+- `/sessions recent` shows only the 5 most recent sessions
+- `/sessions <query>` opens the navigator with a pre-filled filter
+
+### Session Metadata Display
+
+The `/session info` command (within an active session) shows extended metadata:
+- Session ID, title, creation time, last activity
+- Message count, total tokens used, estimated cost
+- Model(s) used during the session
+- Project root path
+- Duration (total active time)
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** stores session data that the navigator reads and displays
+- **Rich TUI (RISE-058)** provides the overlay rendering capability for the navigator
+- **Keybinding System (RISE-063)** maps Ctrl+S and other shortcuts to navigator actions
+- **Session Forking (RISE-020)** can be triggered from the navigator to branch from a selected session
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Multi-Feature Development:**
+A developer works on three features across two projects. They press Ctrl+S, see all five sessions grouped by project, and jump between them as needed. Each session preserves its conversation context — no need to re-explain what they're doing.
+
+**Scenario 2 — Finding an Old Discussion:**
+A developer remembers discussing a database schema a few days ago but doesn't remember the session. They open the navigator, type "database", and the filter narrows to two sessions. They hover on each to preview the last messages and find the right one.
+
+**Scenario 3 — Session Cleanup:**
+After a productive week, a developer opens the navigator in "By date" grouping. They see 15 sessions from this week. They archive 10 completed ones with Ctrl+D, keeping the navigator clean for active work.
+
+**Scenario 4 — Quick Resume After Break:**
+A developer returns from lunch. They press Ctrl+S and see their most recent session at the top of the "Recent" group with the timestamp "47m ago". One Enter press and they're back exactly where they left off.

package/rispecs/borrowed_from_opencode/062-syntax-highlighting.rispec.md

@@ -0,0 +1,151 @@
+# RISE-062: Syntax Highlighting
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/062-syntax-highlighting.rispec.md
+
+## Creative Intent
+
+mia-code renders code in agent responses with the same syntax highlighting developers see in their editors. Code blocks are not flat monochrome text — they are language-aware, color-rich displays that make structure visible at a glance. A developer reading a TypeScript function in an agent response can immediately distinguish keywords from identifiers, strings from comments, and types from values, without having to copy the code into an editor first.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Code blocks in agent responses are rendered as plain monochrome text with chalk — no language awareness
+- Developers must mentally parse code structure without visual cues
+- Diff outputs from tool execution use basic green/red coloring but no syntax awareness within the changed lines
+- File content displayed by tools (file_read) has no highlighting at all
+- There is no distinction between a Python code block and a JavaScript one — both look the same
+- Terminal color capabilities (256-color, 24-bit true color) are not utilized beyond basic ANSI
+
+**Desired State:**
+- Code blocks detect their language from markdown fences (```typescript) or content heuristics
+- Keywords, strings, comments, numbers, operators, types, and functions each receive distinct colors
+- Highlighting works in all code-containing contexts: message code blocks, file content displays, diff outputs, tool results
+- A configurable theme system maps syntax categories to terminal colors
+- Highlighting uses the terminal's full color capability (256-color or 24-bit where supported)
+- Large code blocks are highlighted asynchronously to avoid blocking the UI
+
+## Desired Outcome Definition
+
+Every code block in mia-code's output is syntax-highlighted according to its language. The highlighting uses a configurable theme with sensible defaults. Highlighting is applied in message code blocks, file read outputs, diff views, and tool results. Performance remains smooth for large files through asynchronous highlighting.
+
+## Natural Language Functional Description
+
+### Language Detection
+
+Code language is determined in priority order:
+1. **Explicit fence tag**: ` ```typescript `, ` ```python `, ` ```rust ` — the language identifier after the opening fence
+2. **File extension inference**: when displaying file content, the file extension determines the language (`.ts` → TypeScript, `.py` → Python)
+3. **Content heuristic**: if no tag or extension, analyze the first few lines for language markers (shebang lines, import statements, package declarations)
+4. **Fallback**: if language cannot be determined, apply generic highlighting (strings, numbers, comments with common delimiters)
+
+### Supported Languages
+
+At minimum, highlighting supports the languages most common in mia-code usage:
+- TypeScript, JavaScript, JSX, TSX
+- Python, Ruby, Go, Rust, Java, C, C++
+- HTML, CSS, SCSS
+- JSON, YAML, TOML, XML
+- Markdown
+- Shell (bash, zsh, fish)
+- SQL
+- Dockerfile, Makefile
+
+Additional languages are supported through the highlighting library's built-in grammar set.
+
+### Syntax Categories and Default Colors
+
+| Category | Default Dark Theme | Default Light Theme |
+|----------|-------------------|---------------------|
+| Keywords (`if`, `const`, `def`) | Magenta/Purple | Dark Blue |
+| Strings (`"hello"`, `'world'`) | Green | Dark Green |
+| Comments (`// note`, `# todo`) | Dim Gray | Medium Gray |
+| Numbers (`42`, `3.14`) | Yellow | Dark Yellow |
+| Operators (`+`, `=>`, `===`) | Cyan | Dark Cyan |
+| Types (`string`, `int`) | Blue | Dark Blue |
+| Functions (calls and definitions) | Yellow/Gold | Dark Orange |
+| Built-ins (`console`, `print`) | Cyan | Teal |
+| Punctuation (`{`, `)`, `;`) | Default foreground | Default foreground |
+
+### Highlighting Contexts
+
+**Message Code Blocks:**
+Code within ` ``` ` fences in agent messages is highlighted. The language tag (if present) is shown as a dim label above the code block.
+
+**File Content Display:**
+When `file_read` or similar tools display file content, the entire output is highlighted based on the file extension. Line numbers (if enabled) are rendered in dim gray to the left.
+
+**Diff Output:**
+Diff displays combine syntax highlighting with diff-level coloring:
+- Added lines: green background tint + syntax highlighting on the code
+- Removed lines: red background tint + syntax highlighting on the code
+- Context lines: default background + syntax highlighting
+- Diff markers (`+`, `-`, `@@`) are styled distinctly from code content
+
+**Tool Results:**
+Tool outputs that contain code (e.g., grep results, LSP hover information) are highlighted when the language is detectable from context.
+
+### Theme Configuration
+
+Themes are configured in the mia-code config file:
+
+```jsonc
+{
+  "syntaxTheme": "dark", // built-in theme name
+  // OR custom theme:
+  "syntaxTheme": {
+    "keyword": "magenta",
+    "string": "#a8d8a8",   // 24-bit hex color
+    "comment": "gray",
+    "number": "yellow",
+    "operator": "cyan",
+    "type": "blue",
+    "function": "yellow bold"
+  }
+}
+```
+
+Built-in themes: `dark` (default), `light`, `monokai`, `solarized-dark`, `solarized-light`.
+
+### Line Numbers
+
+Line numbers are optional and controlled by config: `{"syntaxHighlight": {"lineNumbers": true}}`. When enabled:
+- Line numbers are right-aligned in dim gray
+- A thin separator (│) divides line numbers from code content
+- Line numbers do not interfere with copy-paste (they are not selectable in supporting terminals)
+
+### Performance
+
+- Highlighting for blocks under 100 lines is synchronous (instant)
+- Blocks over 100 lines are highlighted asynchronously — raw text displays first, highlighting applies after
+- During streaming (RISE-059), highlighting is applied line-by-line as each line completes
+- A highlighting cache stores results for recently displayed blocks to avoid re-highlighting on scroll
+
+### Terminal Capability Detection
+
+The highlighter adapts to terminal capabilities:
+- **24-bit color** (COLORTERM=truecolor): full hex color support, richest themes
+- **256-color**: maps theme colors to nearest 256-color palette entry
+- **16-color**: maps to basic ANSI colors with bold/dim modifiers
+- **No color** (NO_COLOR env var or --no-color flag): no highlighting applied
+
+## Supporting Structures
+
+- **Rich TUI (RISE-058)** provides the rendering surface where highlighted code appears
+- **Streaming Display (RISE-059)** triggers line-by-line highlighting during progressive rendering
+- **Multi-Level Config (RISE-064)** loads theme preferences from the appropriate config level
+- **JSONC Config (RISE-065)** enables comments in theme configuration files
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Reading Generated Code:**
+The agent generates a 50-line TypeScript function. As it streams, each line receives syntax highlighting — keywords in purple, strings in green, types in blue. The developer reads the code naturally, spotting a type error in a highlighted type annotation before the agent finishes.
+
+**Scenario 2 — Reviewing a Diff:**
+The agent runs `git diff` and displays the result. Added lines show green-tinted backgrounds with syntax-highlighted code inside. The developer can see not just what changed, but the syntactic structure of the changes — a renamed variable stands out as a highlighted identifier, not just a text difference.
+
+**Scenario 3 — Matching Editor Theme:**
+A developer who uses Monokai in VS Code sets `{"syntaxTheme": "monokai"}` in their mia-code config. Code blocks in agent responses now use familiar colors. The visual transition between editor and agent terminal feels seamless.
+
+**Scenario 4 — Large File Display:**
+The agent reads a 500-line Python file. The TUI instantly shows the raw text, then syntax highlighting fades in asynchronously — keywords colorize, strings turn green, comments dim out. The effect is barely noticeable (sub-200ms) but prevents any UI stall.