mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/019-session-compaction.rispec.md

@@ -0,0 +1,132 @@
+# RISE-019: Session Compaction
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/019-session-compaction.rispec.md
+
+## Creative Intent
+
+mia-code prevents context window overflow by automatically compacting long conversation histories into dense summaries. Developers work in extended sessions without hitting token limits — the system intelligently compresses older messages while preserving the decisions, file changes, and current state that the agent needs to remain effective. Compaction is invisible when it works and manual when you need control.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Conversations grow unboundedly — every message is retained in full
+- Long sessions eventually exceed the model's context window, causing truncation or failure
+- No mechanism exists to summarize or prune old messages
+- Developers must manually start new sessions to "reset" context, losing continuity
+- Tool call outputs (file contents, search results) consume enormous token counts even when their information is superseded by later changes
+- The agent progressively loses coherence as important early decisions scroll out of context
+
+**Desired State:**
+- When a session's message count crosses a configurable threshold, compaction triggers automatically
+- Older messages are summarized into a compact representation that preserves essential context
+- Recent messages remain verbatim, ensuring the agent has full detail for current work
+- Compaction is transparent — the agent continues working as if nothing changed
+- Manual compaction via `/compact` gives developers explicit control
+- Compaction metadata tracks what was compressed and when, enabling audit and debugging
+
+## Desired Outcome Definition
+
+A session with 80 messages automatically compacts: the oldest 60 are replaced by a single summary message, the newest 20 remain intact. The summary captures file modifications, key decisions, resolved errors, and current project state. The agent's next response is informed by the summary as if it had read all 80 messages.
+
+## Natural Language Functional Description
+
+### Compaction Trigger
+
+Compaction activates when:
+1. **Automatic:** message count exceeds `compaction.threshold` (default: 50, configurable)
+2. **Manual:** user types `/compact` command
+3. **Token-based (future):** estimated token count exceeds model's context budget minus a reserve
+
+When triggered, the session's status is set to `"compacting"` to prevent concurrent modifications.
+
+### Compaction Process
+
+1. **Select messages for compaction:** all messages from index 0 to `(total - retainCount)`, where `retainCount` defaults to 20. System messages and the initial user prompt are always included in the summary input.
+
+2. **Build compaction prompt:** send selected messages to a compaction agent (see RISE-017) with instructions:
+   - Summarize the conversation preserving: files created/modified/deleted with their current known states, key architectural decisions and their rationale, errors encountered and how they were resolved, current task state and next steps, any user preferences or constraints expressed.
+   - Output structured summary in a defined format.
+
+3. **Replace old messages:** within a single database transaction:
+   - Delete the selected old messages and their parts from the database
+   - Insert a new system message with role `"system"` and type `"compaction_summary"`
+   - The summary message contains: narrative summary text, structured file change list, decision log entries, compaction metadata
+
+4. **Update session metadata:** record compaction event with timestamp.
+
+5. **Clear compacting status:** session returns to normal operation.
+
+### Summary Structure
+
+The compaction summary message contains structured parts:
+
+```
+{
+  "type": "compaction_summary",
+  "original_message_count": 60,
+  "compacted_at": 1706000000000,
+  "summary_token_count": 1200,
+  "narrative": "Session began with user requesting...",
+  "files_touched": [
+    {"path": "src/auth.ts", "status": "modified", "summary": "Added JWT validation middleware"},
+    {"path": "src/types.ts", "status": "created", "summary": "New type definitions for User and Session"}
+  ],
+  "decisions": [
+    "Chose JWT over session cookies for stateless auth",
+    "Using Zod for runtime validation instead of io-ts"
+  ],
+  "current_state": "Authentication middleware complete, starting route handlers"
+}
+```
+
+### Retain Strategy
+
+Messages retained verbatim after compaction:
+- The most recent `retainCount` messages (default: 20)
+- Any message flagged as `pinned` by the user (future feature)
+- The compaction summary itself (always first message after compaction)
+
+### Configuration
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "threshold": 50,
+    "retainCount": 20,
+    "autoTrigger": true
+  }
+}
+```
+
+### The `/compact` Command
+
+Manual trigger that runs compaction regardless of message count. Useful when:
+- The developer knows context is stale and wants to clean up
+- Switching focus within a session and wanting to reset context weight
+- Debugging compaction behavior
+
+Output: "Compacted {N} messages into summary. {M} recent messages retained."
+
+## Supporting Structures
+
+- **Compaction Agent (RISE-017)** defines the agent persona and prompt for summarization
+- **Session Persistence (RISE-018)** provides transactional message replacement in SQLite
+- **Message Parts Model (RISE-026)** defines the compaction_summary part type
+- **Structured Logging (RISE-007)** logs compaction events with before/after metrics
+- **Named Error System (RISE-006)** provides CompactionError for failures during the process
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Long Refactoring Session:**
+A developer refactors 30 files across 4 hours, generating 120 messages. At message 50, compaction fires: messages 1–30 become a summary capturing all file changes and decisions. At message 100, it fires again: messages 31–80 (including the first summary) compact into a new summary. The agent never loses track of which files were modified.
+
+**Scenario 2 — Manual Compaction for Focus Shift:**
+Midway through a session, the developer shifts from "fix bugs" to "add new feature." They type `/compact` to compress the bug-fixing context, giving the agent maximum context budget for the new feature work.
+
+**Scenario 3 — Compaction Preserves Critical Decisions:**
+The user decided early in the session to use PostgreSQL instead of MySQL. 70 messages later, compaction fires. The summary explicitly records this decision. When the agent generates database code post-compaction, it correctly uses PostgreSQL — the decision survived compression.
+
+**Scenario 4 — Audit Trail:**
+A team lead reviews a compacted session. The compaction metadata shows 60 messages were compressed at timestamp T. The summary lists 8 files modified and 3 key decisions. The lead can assess the session's impact without reading 60 messages.

package/rispecs/borrowed_from_opencode/020-session-forking.rispec.md

@@ -0,0 +1,134 @@
+# RISE-020: Session Forking
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/020-session-forking.rispec.md
+
+## Creative Intent
+
+mia-code lets developers branch conversations the way they branch code. A session fork creates a new timeline from any message point — try an alternative approach without destroying the original path, explore "what if" scenarios with full context, and merge the best ideas back. Forking transforms linear conversations into a tree of possibilities, matching how creative problem-solving actually works.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Sessions are strictly linear — each message follows the previous with no branching
+- To try an alternative approach, developers must start a fresh session and re-explain context
+- There is no mechanism to compare two different approaches to the same problem
+- Failed experiments destroy the working state — there is no "undo the last 10 messages and try something else"
+- Valuable context from the original session must be manually copied or re-described
+- No relationship tracking between sessions that explore the same problem space
+
+**Desired State:**
+- Any message in a session can be a fork point — creating a new session that inherits all context up to that message
+- The forked session has its own independent message history from the fork point forward
+- Parent-child relationships are tracked via `parent_id` in the sessions table
+- Developers can view the fork tree to understand how approaches diverged
+- Forked sessions inherit configuration, permissions, and project context
+- Multiple forks from the same point are allowed — enabling parallel exploration
+
+## Desired Outcome Definition
+
+A developer working in session A reaches message #15 and wants to try a different approach. They fork at message #15: a new session B is created with messages 1–15 copied from A. Session B's `parent_id` points to A. The developer continues in B with the alternative approach while A remains untouched. Later, `/forks` in session A shows session B as a child.
+
+## Natural Language Functional Description
+
+### Fork Creation
+
+Forking is triggered by:
+1. **Command:** `/fork [messageId]` — forks from the specified message, or the last message if omitted
+2. **Programmatic:** `sessionDB.forkSession(sessionId, messageId)` — used by UI or API
+
+The fork process:
+1. Validate that the source session and message exist
+2. Create a new session row with:
+   - New unique `id`
+   - `parent_id` set to source session's `id`
+   - `directory`, `project_id`, `version` copied from source
+   - `title` set to "{source title} (fork)" — can be renamed later
+   - `created_at` set to current timestamp
+3. Copy all messages from the source session where `created_at <= fork_point_message.created_at`
+4. Copy all parts belonging to those messages
+5. Message and part IDs are regenerated (new UUIDs) to avoid conflicts
+6. A system message is appended: "Forked from session {sourceId} at message {messageId}"
+7. Return the new session ID — the client switches to it
+
+### Fork Metadata
+
+Each forked session carries metadata:
+```json
+{
+  "fork": {
+    "source_session_id": "abc-123",
+    "source_message_id": "msg-456",
+    "forked_at": 1706000000000,
+    "fork_depth": 1
+  }
+}
+```
+
+`fork_depth` increments for forks of forks, enabling tree visualization.
+
+### Fork Tree Navigation
+
+**`/forks`** — lists all sessions forked from the current session:
+```
+Session forks:
+  ├─ fix-auth-bug (fork) — 2025-01-23 14:30 — 12 messages
+  ├─ fix-auth-bug (fork 2) — 2025-01-23 15:00 — 8 messages
+  │   └─ fix-auth-bug (fork 2.1) — 2025-01-23 15:30 — 5 messages
+  └─ fix-auth-bug (fork 3) — 2025-01-23 16:00 — 3 messages
+```
+
+**`/sessions --tree`** — shows full session hierarchy for the current project:
+```
+Sessions for /projects/myapp:
+  main-session — 2025-01-23 10:00 — 45 messages
+    ├─ approach-a — 2025-01-23 14:30 — 12 messages
+    └─ approach-b — 2025-01-23 15:00 — 8 messages
+  another-session — 2025-01-24 09:00 — 20 messages
+```
+
+### Inherited Properties
+
+When a session is forked, the child inherits:
+- All messages and parts up to the fork point
+- Session configuration (model, temperature, etc.)
+- Active permission rulesets (RISE-011)
+- Project context (directory, project_id)
+- Snapshot state at the fork point (RISE-021)
+
+The child diverges in:
+- Message history after the fork point
+- Session-specific configuration changes made post-fork
+- File system state (each fork operates on the real filesystem independently)
+
+### Promoting a Fork
+
+`/promote` converts a forked session into an independent top-level session by setting `parent_id` to null. The fork metadata is preserved in session metadata for reference but the session no longer appears as a child in tree views.
+
+### Constraints
+
+- Fork depth is limited to 10 levels to prevent unbounded nesting
+- Forking a compacted session forks the compacted state (summary + retained messages)
+- Forks do not synchronize — changes in the parent do not propagate to children
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** provides the `parent_id` column and transactional message copying
+- **Message Parts Model (RISE-026)** ensures parts are correctly duplicated during fork
+- **Session Compaction (RISE-019)** — compacted sessions fork with their summary intact
+- **Session Revert/Snapshot (RISE-021)** — fork point can reference a snapshot for file state
+- **Named Error System (RISE-006)** provides ForkDepthExceededError, InvalidForkPointError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — A/B Approach Testing:**
+A developer asks the agent to redesign a database schema. At the proposed schema message, they fork twice: fork A explores a normalized approach, fork B explores a denormalized approach. After working through both, the developer compares results and continues in the fork that produced cleaner code.
+
+**Scenario 2 — Safe Experimentation:**
+The agent suggests a risky refactoring. The developer forks before agreeing, then lets the agent proceed in the fork. If the refactoring breaks tests, the developer switches back to the original session with no damage done.
+
+**Scenario 3 — Delegated Subtask:**
+Working on a feature, the developer forks to handle a discovered bug. The bug-fix fork has full context of the feature work (understanding which files are involved) but its own message history focused on the fix. Once the bug is resolved, the developer returns to the feature session.
+
+**Scenario 4 — Teaching and Review:**
+A senior developer forks a junior's session at a decision point to show an alternative approach. Both sessions share the same starting context, making the comparison meaningful and educational.

package/rispecs/borrowed_from_opencode/021-session-revert-snapshot.rispec.md

@@ -0,0 +1,135 @@
+# RISE-021: Session Revert and Snapshots
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/021-session-revert-snapshot.rispec.md
+
+## Creative Intent
+
+mia-code captures file system snapshots before every destructive tool execution, giving developers a time-travel mechanism to undo agent changes at any granularity. Every tool call that touches files becomes reversible. Developers experiment fearlessly — if an agent's edit breaks the build, one command restores the working state. The safety net is always there, invisible until needed.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Tool executions that modify files (write, edit, delete) are permanent and immediate
+- There is no built-in undo — developers must use git to recover from bad agent edits
+- If the project has uncommitted changes, a bad agent edit can destroy work-in-progress
+- Multiple tool calls in a single agent turn cannot be selectively undone
+- The agent cannot revert its own mistakes without the developer manually identifying changed files
+- No snapshot mechanism exists independent of the project's own git repository
+
+**Desired State:**
+- Before each file-modifying tool execution, a snapshot captures the current state of affected files
+- Snapshots are stored in a dedicated hidden git repository (`.mia-code/snapshots/`) separate from the project's git
+- Developers can revert to any snapshot via `/undo` (last change) or `/revert <messageId>` (specific point)
+- Reverts are non-destructive to session history — a revert adds a new message documenting what was restored
+- Snapshot metadata tracks which files were affected, additions/deletions, and diff text
+- The snapshot system works regardless of whether the project uses git
+
+## Desired Outcome Definition
+
+The agent edits 3 files in response to a prompt. Before each edit, a snapshot hash is recorded. The developer sees the changes break tests. They type `/undo` and all 3 files revert to their pre-edit state. A message appears in the session: "Reverted 3 files to snapshot abc123." The session history retains both the original edits and the revert.
+
+## Natural Language Functional Description
+
+### Snapshot Capture
+
+Before any tool execution that modifies the filesystem, the snapshot system:
+
+1. **Identify affected files:** parse the tool call to determine which files will be created, modified, or deleted
+2. **Stage current state:** in the `.mia-code/snapshots/` git repository:
+   - Copy the current version of each affected file into the snapshot repo
+   - `git add` the files
+   - `git write-tree` to create a tree object
+   - Store the tree hash as the snapshot identifier
+3. **Record snapshot metadata** in the session database:
+   ```json
+   {
+     "snapshot_id": "abc123def",
+     "message_id": "msg-789",
+     "tool_call_id": "tc-456",
+     "timestamp": 1706000000000,
+     "files": [
+       {"path": "src/auth.ts", "action": "modify", "size_before": 2048},
+       {"path": "src/types.ts", "action": "create"},
+       {"path": "src/old.ts", "action": "delete", "size_before": 512}
+     ]
+   }
+   ```
+4. **Proceed with tool execution** — the tool runs normally after the snapshot is saved
+
+### Snapshot Storage
+
+The `.mia-code/snapshots/` directory contains a bare-like git repository used solely for snapshot storage:
+- Initialized once per project on first tool execution
+- Uses git's content-addressable storage for efficient deduplication
+- Tree objects reference file blobs — no commits needed (lightweight)
+- Periodic garbage collection removes orphaned snapshots older than 30 days
+- The snapshot repo is excluded from the project's `.gitignore` automatically
+
+### Revert Operations
+
+**`/undo`** — reverts the most recent file-modifying tool execution:
+1. Find the last snapshot in the current session
+2. Restore all files from that snapshot's tree object to the working directory
+3. For files that were created by the tool: delete them
+4. For files that were deleted by the tool: restore them from the snapshot
+5. Append a system message to the session documenting the revert
+
+**`/revert <messageId>`** — reverts to the state before a specific message's tool calls:
+1. Find the snapshot associated with the specified message
+2. Restore files from the snapshot tree to the working directory
+3. If multiple tool calls occurred between the snapshot and now, compute the cumulative diff
+4. Append a system message documenting all files restored
+
+### Revert Message
+
+When a revert occurs, a system message is appended:
+```
+Reverted to snapshot abc123def (before message msg-789):
+  - src/auth.ts: restored (was modified)
+  - src/types.ts: removed (was created)
+  - src/old.ts: restored (was deleted)
+  
+  3 files affected, 45 additions restored, 23 deletions undone.
+```
+
+### Snapshot Browsing
+
+**`/snapshots`** — lists all snapshots in the current session:
+```
+Snapshots:
+  #1  msg-001  2025-01-23 10:05  src/auth.ts (modify)
+  #2  msg-003  2025-01-23 10:12  src/types.ts (create), src/utils.ts (modify)
+  #3  msg-007  2025-01-23 10:30  src/old.ts (delete)
+```
+
+**`/diff <snapshotId>`** — shows the diff between a snapshot and the current file state
+
+### Edge Cases
+
+- **Binary files:** stored in snapshots but diffing is skipped; revert restores the binary blob
+- **New files created by agent:** snapshot records their absence; revert deletes them
+- **Files modified outside mia-code** between snapshot and revert: the revert overwrites with snapshot state; a warning is emitted
+- **Concurrent sessions:** each session maintains its own snapshot chain; cross-session conflicts are the developer's responsibility
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** stores snapshot metadata in the database alongside messages
+- **Message Parts Model (RISE-026)** defines the `snapshot` and `revert` part types
+- **Structured Logging (RISE-007)** logs all snapshot and revert operations
+- **Named Error System (RISE-006)** provides SnapshotNotFoundError, RevertConflictError
+- **Session Forking (RISE-020)** — forks can reference a specific snapshot as their starting file state
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Quick Undo:**
+The agent edits `src/api.ts` and the TypeScript compiler reports errors. The developer types `/undo`. The file reverts instantly. The developer provides better instructions and the agent tries again on the clean file.
+
+**Scenario 2 — Selective Time Travel:**
+Over 20 messages, the agent made changes to 15 files. Message #8 introduced a subtle bug. The developer uses `/revert msg-008` to restore files to their state before message #8, while keeping the full conversation history. They then guide the agent to redo messages 8–20 with the bug avoided.
+
+**Scenario 3 — Fearless Experimentation:**
+The developer asks the agent to "try a completely different architecture for this module." Knowing that `/undo` exists, they let the agent make sweeping changes across 10 files. The experiment fails, and a single `/undo` restores everything. No git stashing, no manual file recovery.
+
+**Scenario 4 — Snapshot as Documentation:**
+Before a demo, the developer runs `/snapshots` to see every file change the agent made during the session. The snapshot list serves as a changelog — showing exactly which files were touched and when, useful for code review or knowledge transfer.

package/rispecs/borrowed_from_opencode/022-session-sharing.rispec.md

@@ -0,0 +1,165 @@
+# RISE-022: Session Sharing
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/022-session-sharing.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to share agent conversations via public URLs — making AI-assisted coding sessions as shareable as gists. A shared session becomes a living document: the conversation, tool calls, code changes, and reasoning are all visible. Teams share debugging sessions, educators share teaching interactions, and open-source contributors share how they built features. Sharing transforms private agent work into collective knowledge.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Session data lives exclusively on the local machine in `~/.mia-code-sessions.json`
+- There is no mechanism to share a session with another person
+- To show someone what the agent did, developers must copy-paste terminal output or screen-record
+- Copy-pasted output loses structure: tool calls, file diffs, and timing are flattened to text
+- No privacy controls exist because sharing does not exist
+- Self-hosted teams cannot run their own sharing infrastructure
+
+**Desired State:**
+- Sessions can be shared via a single command, producing a public URL
+- The shared view preserves full session structure: messages, tool calls with arguments and results, file diffs, timestamps
+- Sharing is opt-in and configurable: disabled, ask-per-session, or automatic
+- Shares can be revoked, removing the public URL
+- The share endpoint is configurable, enabling self-hosted deployments
+- Share metadata (URL, secret, timestamps) is stored locally for management
+
+## Desired Outcome Definition
+
+A developer finishes a productive session and types `/share`. The session data is uploaded to the configured share endpoint. A URL is returned: `https://share.mia-code.dev/s/abc123`. Anyone with the URL can view the conversation in a rich web interface. The developer can later type `/unshare` to revoke access.
+
+## Natural Language Functional Description
+
+### Share Configuration
+
+Sharing behavior is controlled by configuration:
+
+```json
+{
+  "share": {
+    "mode": "ask",
+    "endpoint": "https://share.mia-code.dev/api",
+    "includeToolResults": true,
+    "includeDiffs": true,
+    "redactPatterns": []
+  }
+}
+```
+
+- `mode`: `"disabled"` (never share), `"ask"` (prompt before sharing), `"auto"` (share automatically on session end)
+- `endpoint`: the API base URL for the sharing service
+- `includeToolResults`: whether to include full tool output (may contain sensitive code)
+- `includeDiffs`: whether to include file diffs showing changes
+- `redactPatterns`: regex patterns for content to redact before sharing (e.g., API keys, passwords)
+
+### Share Command
+
+**`/share`** — shares the current session:
+1. If mode is `"disabled"`, print error and exit
+2. If mode is `"ask"`, prompt: "Share this session publicly? [y/N]"
+3. Serialize the session: messages, parts, metadata, file diffs
+4. Apply redaction patterns to all text content
+5. POST to `{endpoint}/sessions` with the serialized payload
+6. Receive response: `{ "url": "https://...", "secret": "del_xyz", "id": "share_abc" }`
+7. Store share metadata in the local session record
+8. Display: "Session shared: https://share.mia-code.dev/s/abc123"
+
+**`/unshare`** — revokes a shared session:
+1. Read the share secret from local session metadata
+2. DELETE to `{endpoint}/sessions/{share_id}` with the secret as authorization
+3. Remove share metadata from local session record
+4. Display: "Share revoked. URL is no longer accessible."
+
+**`/share --update`** — updates an existing share with new messages:
+1. PUT to `{endpoint}/sessions/{share_id}` with updated payload
+2. Display: "Share updated."
+
+### Sync Events (Auto Mode)
+
+When `mode` is `"auto"`, the following events trigger sync:
+- `session.created` — creates the share immediately
+- `message.added` — pushes the new message to the share
+- `session.archived` — marks the share as complete
+- Sync is best-effort: failures are logged but do not interrupt the session
+
+### Share Payload Structure
+
+```json
+{
+  "version": "1.0",
+  "session": {
+    "id": "local-session-id",
+    "title": "Fix authentication bug",
+    "project": "myapp",
+    "created_at": 1706000000000,
+    "model": "claude-sonnet-4-20250514"
+  },
+  "messages": [
+    {
+      "role": "user",
+      "parts": [{"type": "text", "content": "Fix the auth middleware"}],
+      "created_at": 1706000001000
+    },
+    {
+      "role": "assistant",
+      "parts": [
+        {"type": "text", "content": "I'll fix the auth middleware..."},
+        {"type": "tool_call", "name": "edit_file", "args": {"path": "src/auth.ts", "...": "..."}},
+        {"type": "tool_result", "output": "File edited successfully"}
+      ],
+      "metadata": {"model": "claude-sonnet-4-20250514", "tokens": 450},
+      "created_at": 1706000010000
+    }
+  ],
+  "diffs": [
+    {
+      "file": "src/auth.ts",
+      "status": "modified",
+      "additions": 12,
+      "deletions": 3,
+      "patch": "@@ -10,3 +10,12 @@\n-old code\n+new code"
+    }
+  ]
+}
+```
+
+### Privacy and Security
+
+- **Opt-in:** sharing never happens without explicit user action or configuration
+- **Redaction:** configurable regex patterns strip sensitive content before upload
+- **Revocable:** shares can be deleted at any time using the stored secret
+- **No source code by default:** `includeToolResults` can be disabled to share only the conversation, not code content
+- **Self-hosted:** the endpoint is configurable — teams can run their own share server
+- **Expiration:** shares include an optional TTL (default: 30 days, configurable)
+
+### Share Viewer
+
+The share URL resolves to a web interface that renders:
+- Conversation messages with proper formatting
+- Tool calls with collapsible arguments and results
+- File diffs with syntax highlighting
+- Timestamps and model information
+- Session metadata (duration, message count, files changed)
+
+## Supporting Structures
+
+- **Session Persistence (RISE-018)** stores share metadata alongside session data
+- **Message Parts Model (RISE-026)** provides the structured data that makes rich sharing possible
+- **Session Summary Diffs (RISE-023)** generates the diff summary included in shares
+- **Structured Logging (RISE-007)** logs share/unshare events
+- **Named Error System (RISE-006)** provides ShareUploadError, ShareRevokeError, RedactionError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Bug Report with Context:**
+A developer discovers a bug in mia-code's agent behavior. They `/share` the session and paste the URL in a GitHub issue. The maintainer sees the exact conversation, tool calls, and agent reasoning — a complete reproduction case.
+
+**Scenario 2 — Team Knowledge Sharing:**
+A senior developer uses mia-code to implement a complex feature. They share the session in Slack. Junior developers read through the conversation to learn the architectural decisions and coding patterns.
+
+**Scenario 3 — Self-Hosted Enterprise:**
+A company configures `endpoint` to point to their internal share server. Sessions are shared within the company network. No data leaves the corporate infrastructure.
+
+**Scenario 4 — Automatic Session Archive:**
+With `mode: "auto"`, every session is automatically synced to the share endpoint. The team maintains a searchable library of all agent interactions — a collective memory of how the codebase evolved.