Merge branch 'main' into exec-approvals

docs/product-capabilities.md

@@ -0,0 +1,847 @@
+# Super Multica Product Capabilities
+
+> This document is the single source of truth for all product capabilities. It describes **what exists**, not how to design or how to use it. All subsequent documents (user journeys, UI design, copywriting, design systems) should reference this document.
+
+---
+
+## 1. Product Definition
+
+**Super Multica** is a distributed AI Agent framework. Users can create, customize, and deploy AI Agents with persistent memory, fine-grained capability control, and multi-provider LLM support. Agents run locally on the user's machine; remote access is optional.
+
+**Core architecture**:
+
+```
+Desktop App (standalone, recommended)
+  └─ Hub (embedded, manages agents)
+     └─ Agent Engine (LLM execution, sessions, skills, tools)
+        └─ (Optional) Gateway connection → remote clients (web/mobile)
+```
+
+---
+
+## 2. User Roles
+
+| Role | Definition | Platform | Authority |
+|------|-----------|----------|-----------|
+| **Owner** | Runs the Desktop app, owns Hub and Agents | Desktop (Electron) | Full: create/delete agents, approve devices, configure providers, manage profiles/skills |
+| **Collaborator** | Connects to Owner's Agent via Gateway | Web / Mobile | Limited: chat with agent, view message history. No agent management. |
+
+There is no formal role/permission system. The Owner is implicit admin by virtue of running the Hub.
+
+---
+
+## 3. Functional Modules
+
+### 3.1 Agent Engine
+
+The core execution unit. An Agent receives user messages, calls an LLM, executes tools, and returns responses.
+
+#### 3.1.1 Agent Lifecycle
+
+| State | Description |
+|-------|-------------|
+| Created | AsyncAgent instantiated, assigned UUIDv7 session ID |
+| Idle | Awaiting `write()` call (user message) |
+| Running | Processing message: LLM call → tool execution → response |
+| Closed | Agent terminated, no further messages accepted |
+
+Each `write()` call is queued. Messages are processed sequentially (one at a time).
+
+#### 3.1.2 Agent Execution Loop
+
+1. Receive user message via `write(content)`
+2. Resolve API credentials (with auth profile rotation)
+3. Build/update system prompt from profile
+4. Call LLM provider with message history
+5. If LLM requests tool calls → execute tools → feed results back to LLM → repeat
+6. Save all messages to session storage
+7. Check context window utilization → compact if needed
+8. Emit events to subscribers (streaming to UI)
+
+#### 3.1.3 Auth Profile Rotation
+
+When an API call fails, the system classifies the error and may rotate to a different API key:
+
+| Error Type | Examples | Rotates? |
+|-----------|----------|----------|
+| `auth` | 401, 403, invalid key | Yes |
+| `rate_limit` | 429, rate limit exceeded | Yes |
+| `billing` | Out of credits, quota exceeded | Yes |
+| `timeout` | Connection timeout | Yes |
+| `format` | 400, malformed request | No |
+| `unknown` | Other errors | No |
+
+Failed profiles enter cooldown. Rotation continues until success or all profiles exhausted.
+
+Tracking file: `~/.super-multica/.auth-profiles/usage-stats.json`
+
+#### 3.1.4 Subagent Spawning
+
+Agents can spawn child agents via the `sessions_spawn` tool:
+
+- Subagents get isolated sessions
+- Tool restrictions: `sessions_spawn` denied (no nested spawning)
+- System prompt mode: `minimal` or `none`
+- Parameters: task (required), label, model override, cleanup policy (`delete` or `keep`), timeout
+- Results announced back to parent automatically
+
+#### 3.1.5 Agent Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `profileId` | string | none | Agent profile to load |
+| `provider` | string | `kimi-coding` | LLM provider |
+| `model` | string | provider default | Model within provider |
+| `reasoningMode` | `off` / `on` / `stream` | `off` | Display thinking/reasoning |
+| `compactionMode` | `count` / `tokens` / `summary` | `tokens` | Context compaction strategy |
+| `contextWindowTokens` | number | 200,000 | Override model's context window |
+| `enableSkills` | boolean | `true` | Enable skills system |
+
+---
+
+### 3.2 LLM Providers
+
+Ten providers supported. Two auth methods: OAuth (CLI login) and API Key.
+
+| ID | Display Name | Auth | Default Model | Available Models |
+|----|-------------|------|---------------|------------------|
+| `claude-code` | Claude Code | OAuth | claude-opus-4-5 | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 |
+| `openai-codex` | Codex | OAuth | gpt-5.2 | gpt-5.2, gpt-5.2-codex, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max |
+| `anthropic` | Anthropic | API Key | claude-sonnet-4-5 | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 |
+| `openai` | OpenAI | API Key | gpt-4o | gpt-4o, gpt-4o-mini, o1, o1-mini |
+| `kimi-coding` | Kimi Code | API Key | kimi-k2-thinking | kimi-k2-thinking, k2p5 |
+| `google` | Google AI | API Key | gemini-2.0-flash | gemini-2.0-flash, gemini-1.5-pro |
+| `groq` | Groq | API Key | llama-3.3-70b-versatile | llama-3.3-70b-versatile, mixtral-8x7b-32768 |
+| `mistral` | Mistral | API Key | mistral-large-latest | mistral-large-latest, codestral-latest |
+| `xai` | xAI (Grok) | API Key | grok-beta | grok-beta, grok-vision-beta |
+| `openrouter` | OpenRouter | API Key | anthropic/claude-3.5-sonnet | anthropic/claude-3.5-sonnet, openai/gpt-4o |
+
+**Default provider fallback**: config > credentials.json5 > `kimi-coding`
+
+**OAuth providers** require external CLI login (`claude login` / `codex login`).
+
+**API Key providers** are configured in `~/.super-multica/credentials.json5`.
+
+**Multiple API keys per provider** are supported via auth profiles (e.g., `openai`, `openai:backup`). The system rotates between them on failure.
+
+---
+
+### 3.3 Tools
+
+Tools are capabilities the Agent can invoke during execution.
+
+#### 3.3.1 Built-in Tools
+
+| Tool | Category | Description |
+|------|----------|-------------|
+| `read` | File | Read file contents (with optional offset/limit) |
+| `write` | File | Create or overwrite files |
+| `edit` | File | Make precise edits to existing files |
+| `glob` | File | Find files by pattern (default limit: 100, max: 1000) |
+| `exec` | Runtime | Run shell commands (auto-backgrounds after 10s) |
+| `process` | Runtime | Manage background processes (start, stop, list, output) |
+| `web_search` | Web | Search the web (Brave or Perplexity provider) |
+| `web_fetch` | Web | Fetch and extract URL content (markdown/text, max 50k chars, 15min cache) |
+| `memory_get` | Memory | Read from agent's persistent memory |
+| `memory_set` | Memory | Write to agent's persistent memory (max 1MB per value) |
+| `memory_list` | Memory | List memory entries (default limit: 100, max: 1000) |
+| `memory_delete` | Memory | Delete memory entries |
+| `sessions_spawn` | Subagent | Spawn a child agent for a specific task |
+
+#### 3.3.2 Tool Groups (shortcuts for policy)
+
+| Group | Tools Included |
+|-------|---------------|
+| `group:fs` | read, write, edit, glob |
+| `group:runtime` | exec, process |
+| `group:web` | web_search, web_fetch |
+| `group:memory` | memory_get, memory_set, memory_delete, memory_list |
+| `group:subagent` | sessions_spawn |
+| `group:core` | read, write, edit, glob, exec, process, web_search, web_fetch |
+
+#### 3.3.3 Tool Policy System (3 layers)
+
+| Layer | Scope | Description |
+|-------|-------|-------------|
+| 1. Global | All agents | `allow` / `deny` lists (wildcard supported: `mem*`, `*`) |
+| 2. Provider | Per LLM provider | Narrower restrictions per provider (e.g., deny `exec` for Google) |
+| 3. Subagent | Child agents only | `sessions_spawn` denied by default |
+
+**Priority**: Deny always overrides Allow. Empty allow list = deny all.
+
+#### 3.3.4 Exec Tool Details
+
+- Default yield timeout: 10,000ms (auto-backgrounds if not complete)
+- Supports `timeoutMs` for hard kill (SIGTERM)
+- Output includes: stdout+stderr, exitCode, truncation flag, process ID if backgrounded
+
+#### 3.3.5 Web Search Details
+
+- Brave provider: up to 10 results, country filtering, freshness filters (`pd`/`pw`/`pm`/`py`)
+- Perplexity provider: AI-synthesized answers
+- Default count: 5 results, 1 hour cache
+
+---
+
+### 3.4 Profile System
+
+A Profile defines an Agent's identity, personality, knowledge, and configuration.
+
+#### 3.4.1 Profile File Structure
+
+```
+~/.super-multica/agent-profiles/{profileId}/
+├── soul.md           # Identity: name, role, personality, behavior boundaries
+├── user.md           # User information: name, preferences, context
+├── workspace.md      # Workspace conventions, coding standards, project rules
+├── memory.md         # Long-term knowledge base (read by agent at startup)
+├── config.json       # Optional: provider, model, thinking level, tool policy
+├── memory/           # Key-value persistent memory storage
+│   ├── key1.json
+│   └── key2.json
+└── skills/           # Profile-specific skills (override global)
+    └── {skill-name}/
+        └── SKILL.md
+```
+
+#### 3.4.2 Profile Config (config.json)
+
+```json
+{
+  "name": "Jarvis",
+  "style": "concise and direct",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-5",
+  "thinkingLevel": "medium",
+  "tools": {
+    "allow": ["group:fs", "web_fetch"],
+    "deny": ["exec"]
+  }
+}
+```
+
+#### 3.4.3 Profile Operations
+
+| Operation | CLI | Desktop |
+|-----------|-----|---------|
+| List profiles | `multica profile list` | Via Hub info |
+| Create profile | `multica profile new <id>` | - |
+| Interactive setup | `multica profile setup <id>` | - |
+| View profile | `multica profile show <id>` | - |
+| Edit in file manager | `multica profile edit <id>` | - |
+| Delete profile | `multica profile delete <id>` | - |
+
+**Profile ID rules**: alphanumeric, hyphens, underscores only.
+
+#### 3.4.4 System Prompt Composition
+
+The system prompt is built dynamically from profile files:
+
+| Section | Source | Mode: full | Mode: minimal | Mode: none |
+|---------|--------|-----------|--------------|-----------|
+| Identity | soul.md + config | Yes | Partial | Single line |
+| User | user.md | On-demand | No | No |
+| Workspace | workspace.md | Yes | No | No |
+| Memory | memory.md | On-demand | No | No |
+| Safety | Built-in constitution | Yes | Yes | Yes |
+| Tools | Active tool list | Yes | Core only | No |
+| Skills | Skill instructions | Yes | No | No |
+| Runtime | OS, model, hostname | Yes | Essential | No |
+| Subagent | Task context | If applicable | Yes | Yes |
+
+**Progressive disclosure**: soul.md, user.md, memory.md are loaded on-demand (not injected in full at startup) to save tokens.
+
+---
+
+### 3.5 Memory System
+
+Agents can persistently store and recall information across sessions.
+
+#### 3.5.1 Storage
+
+- Location: `~/.super-multica/agent-profiles/{profileId}/memory/`
+- Format: One JSON file per key
+- Key rules: alphanumeric, underscore, dot, hyphen. Max 128 chars.
+- Dots in keys are escaped as `__DOT__` in filenames
+- Max value size: 1MB
+
+#### 3.5.2 Entry Format
+
+```json
+{
+  "value": "any JSON value",
+  "description": "optional human-readable description",
+  "createdAt": 1717689600000,
+  "updatedAt": 1717689600000
+}
+```
+
+#### 3.5.3 Memory Tools
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `memory_get` | `{ key }` | `{ found, value?, description?, updatedAt? }` |
+| `memory_set` | `{ key, value, description? }` | `{ success, error? }` |
+| `memory_delete` | `{ key }` | `{ success, existed, error? }` |
+| `memory_list` | `{ prefix?, limit? }` | `{ keys[], total, truncated }` |
+
+**Design principle**: Agents cannot "remember" mentally. All persistence must be file-based ("TEXT > BRAIN").
+
+---
+
+### 3.6 Skills System
+
+Skills are modular, self-contained capabilities defined via `SKILL.md` files. They extend what an Agent can do.
+
+#### 3.6.1 Skill File Format (SKILL.md)
+
+```yaml
+---
+name: Skill Name
+description: What this skill does
+version: 1.0.0
+metadata:
+  emoji: "📝"
+  os: [darwin, linux]           # Platform restriction (optional)
+  always: false                 # Skip eligibility checks (optional)
+  tags: [productivity, coding]
+  requires:
+    bins: [node, npm]           # ALL must exist in PATH
+    anyBins: [python3, python]  # At least ONE must exist
+    env: [OPENAI_API_KEY]       # ALL must be set
+    config: [custom.setting]    # Config paths must be truthy
+---
+# Full markdown instructions follow...
+```
+
+#### 3.6.2 Skill Sources & Precedence
+
+| Source | Location | Precedence |
+|--------|----------|-----------|
+| Bundled | `skills/` in project | Lowest |
+| Global (user-installed) | `~/.super-multica/skills/` | Medium |
+| Profile-specific | `~/.super-multica/agent-profiles/{id}/skills/` | Highest (overrides) |
+
+Profile skills with the same ID completely replace global/bundled versions.
+
+#### 3.6.3 Bundled Skills
+
+| Skill | ID | Description | Requirements |
+|-------|----|-------------|-------------|
+| Git Commit Helper | `commit` | Create well-formatted conventional commits | `git` binary |
+| Code Review | `code-review` | Structured code review with security focus | None |
+| Profile Setup | `profile-setup` | Interactive wizard to personalize agent profile | None |
+| Skill Creator | `skill-creator` | Create, edit, manage custom skills | None (always eligible) |
+
+#### 3.6.4 Eligibility Check Sequence
+
+1. Explicit disable in config → ineligible
+2. Bundled + not in allowlist → ineligible
+3. Platform mismatch (OS) → ineligible
+4. `always: true` flag → eligible (skip remaining)
+5. Missing required binary → ineligible
+6. No alternative binary found → ineligible
+7. Missing env var → ineligible
+8. Missing config path → ineligible
+9. All checks pass → eligible
+
+Returns human-readable failure reasons (e.g., "Required binary not found: git").
+
+#### 3.6.5 Skill Invocation
+
+- **User invocation**: `/skillname args` in interactive CLI
+- **Model invocation**: Agent reads skill instructions from system prompt and follows them
+- **Hot reload**: File watcher detects SKILL.md changes, reloads automatically (250ms debounce)
+
+#### 3.6.6 Skill Installation
+
+```bash
+multica skills add owner/repo              # Clone entire repository
+multica skills add owner/repo/skill-name   # Clone single skill
+multica skills add owner/repo@branch       # Specific branch/tag
+multica skills add owner/repo -p my-agent  # Install to profile
+```
+
+---
+
+### 3.7 Session Management
+
+Sessions persist conversation history across interactions.
+
+#### 3.7.1 Session Storage
+
+- Location: `~/.super-multica/sessions/{sessionId}/session.jsonl`
+- Format: JSON Lines (one JSON object per line)
+- Session IDs: UUIDv7 (time-ordered)
+- Each line is either a message entry, meta entry, or compaction entry
+
+#### 3.7.2 Message Format
+
+Messages follow the LLM API format:
+
+```json
+{"type": "message", "role": "user", "content": [{"type": "text", "text": "Hello"}]}
+{"type": "message", "role": "assistant", "content": [{"type": "text", "text": "Hi!"}, {"type": "tool_use", "id": "...", "name": "read", "input": {"path": "/foo"}}]}
+{"type": "message", "role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "file contents"}]}
+```
+
+#### 3.7.3 Session Metadata
+
+```json
+{"type": "meta", "provider": "anthropic", "model": "claude-sonnet-4-5", "reasoningMode": "off", "contextWindowTokens": 200000}
+```
+
+#### 3.7.4 Context Window Management
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Hard minimum | 16,000 tokens | Block execution below this |
+| Warning threshold | 32,000 tokens | Warn if context window smaller |
+| Default context | 200,000 tokens | Fallback if model unknown |
+| Safety margin | 20% | Buffer for estimation inaccuracy |
+| Compaction trigger | 80% utilization | Start compacting |
+| Compaction target | 50% utilization | Target after compaction |
+| Min keep messages | 10 | Never remove below this |
+| Reserve tokens | 1,024 | Reserved for response generation |
+
+#### 3.7.5 Compaction Modes
+
+| Mode | Strategy | Speed | Quality |
+|------|----------|-------|---------|
+| `tokens` (default) | Remove oldest messages until reaching 50% target | Fast | Good (preserves recent context) |
+| `count` | Remove oldest when count > 80, keep last 60 | Fastest | Adequate |
+| `summary` | LLM generates incremental summary of removed messages | Slow (API call) | Best (preserves meaning) |
+
+#### 3.7.6 Session Operations
+
+| Operation | CLI Command |
+|-----------|-------------|
+| List sessions | `multica session list` |
+| View session | `multica session show <id>` (supports partial ID) |
+| Delete session | `multica session delete <id>` |
+| Resume session | `multica --session <id> "continue..."` |
+
+---
+
+### 3.8 Hub
+
+The Hub is the central coordinator. It manages agent lifecycle, routes messages, and handles device verification.
+
+#### 3.8.1 Responsibilities
+
+- Create, list, restore, close agents
+- Persist agent metadata to disk (`~/.super-multica/agents/agents.json`)
+- Route messages between local IPC and remote Gateway
+- Handle device verification and whitelisting
+- Process RPC requests from connected clients
+
+#### 3.8.2 Hub RPC Methods
+
+| Method | Description | Error Codes |
+|--------|-------------|-------------|
+| `verify` | Verify device with token | UNAUTHORIZED, REJECTED |
+| `getAgentMessages` | Fetch message history (default: 50, offset: 0) | INVALID_PARAMS, AGENT_NOT_FOUND |
+| `getHubInfo` | Get Hub ID and status | - |
+| `listAgents` | List all agents | - |
+| `createAgent` | Create new agent | - |
+| `deleteAgent` | Delete agent | - |
+| `updateGateway` | Update Gateway connection | - |
+
+#### 3.8.3 Hub Singleton
+
+One Hub per ecosystem. In Desktop mode, it's embedded in the Electron main process. It generates a persistent Hub ID stored at `~/.super-multica/hub-id`.
+
+---
+
+### 3.9 Gateway
+
+NestJS WebSocket server that enables remote client access to the Hub.
+
+#### 3.9.1 Purpose
+
+Bridges remote clients (web/mobile) to the Hub. Not needed for local Desktop use.
+
+#### 3.9.2 Connection Protocol
+
+- Transport: Socket.io
+- Path: `/ws`
+- Port: 3000 (default)
+
+#### 3.9.3 Timeouts
+
+| Parameter | Value |
+|-----------|-------|
+| Ping interval | 25 seconds |
+| Ping timeout | 20 seconds |
+| RPC default timeout | 10 seconds |
+| Verify timeout | 30 seconds |
+| Reconnect delay | 1 second |
+
+#### 3.9.4 Message Routing
+
+- Each message has `from` (sender device ID) and `to` (target device ID)
+- Gateway validates: sender is registered, `from` matches socket, target exists
+- Supports streaming via `StreamAction` (message_start, message_update, message_end, tool events)
+
+#### 3.9.5 Error Codes
+
+| Code | Meaning |
+|------|---------|
+| NOT_REGISTERED | Sender not registered |
+| INVALID_MESSAGE | `from` field mismatch |
+| DEVICE_NOT_FOUND | Target device not online |
+
+---
+
+### 3.10 Device Pairing & Verification
+
+How remote devices (web/mobile) connect to the Owner's Hub.
+
+#### 3.10.1 QR Code Generation (Desktop)
+
+The Desktop app generates a QR code containing:
+
+```json
+{
+  "type": "multica-connect",
+  "gateway": "http://localhost:3000",
+  "hubId": "uuid",
+  "agentId": "uuid",
+  "token": "random-uuid",
+  "expires": 1694000000000
+}
+```
+
+- Token: one-time use, random UUID
+- Expiry: 30 seconds from generation
+- Auto-refresh: new token generated when expired
+- Also available as URL: `multica://connect?gateway=...&hub=...&agent=...&token=...&exp=...`
+
+#### 3.10.2 Connection Code Formats (accepted by client)
+
+| Format | Example |
+|--------|---------|
+| JSON | `{"type":"multica-connect","gateway":"..."}` |
+| Base64 JSON | Base64-encoded JSON string |
+| URL | `multica://connect?gateway=...&hub=...&agent=...&token=...&exp=...` |
+
+#### 3.10.3 Verification Flow
+
+```
+1. Mobile scans QR / pastes code
+2. Client parses code, validates expiry
+3. Client connects to Gateway via Socket.io
+4. Gateway sends "registered" event
+5. Client auto-sends "verify" RPC with token + device metadata
+6. Hub validates token (one-time, checks expiry)
+7. Hub triggers confirmation dialog on Desktop
+   - Shows: device name (parsed from User-Agent), device ID
+   - Options: "Allow" or "Reject"
+   - Timeout: 60 seconds (auto-reject)
+8. If allowed: device added to whitelist, persisted to disk
+9. If rejected: connection closed
+```
+
+#### 3.10.4 Device Whitelist
+
+- Location: `~/.super-multica/client-devices/whitelist.json`
+- Format:
+
+```json
+{
+  "version": 1,
+  "devices": [{
+    "deviceId": "uuid",
+    "agentId": "uuid",
+    "addedAt": 1694000000000,
+    "meta": {
+      "userAgent": "Mozilla/5.0...",
+      "platform": "Linux",
+      "language": "en-US"
+    }
+  }]
+}
+```
+
+#### 3.10.5 Reconnection (whitelisted device)
+
+Whitelisted devices reconnect without needing a new token or user confirmation. Hub checks `isAllowed(deviceId)` and returns immediately.
+
+#### 3.10.6 Device Management (Desktop)
+
+- View verified devices list with metadata
+- Revoke individual devices (remove from whitelist)
+- No fine-grained permissions (all-or-nothing access)
+
+#### 3.10.7 Security Model
+
+| Aspect | Detail |
+|--------|--------|
+| Token lifetime | 30 seconds |
+| Token usage | One-time (deleted after consumption) |
+| Token storage | In-memory only (lost on Hub restart) |
+| Device ID | Browser: UUID in localStorage. Persistent until cleared. |
+| Whitelist | Persisted to disk. Survives restarts. |
+| Authorization | All verified devices have equal access |
+| Message auth | Hub checks whitelist on every non-verify message |
+
+---
+
+### 3.11 Credentials System
+
+#### 3.11.1 Files
+
+| File | Purpose | Permissions |
+|------|---------|-------------|
+| `~/.super-multica/credentials.json5` | LLM providers + tool API keys | 0o600 |
+| `~/.super-multica/skills.env.json5` | Skill/plugin environment variables | 0o600 |
+
+Format: JSON5 (supports comments, trailing commas, unquoted keys).
+
+#### 3.11.2 credentials.json5 Structure
+
+```json5
+{
+  version: 1,
+  llm: {
+    provider: "openai",           // Default provider
+    providers: {
+      openai: { apiKey: "sk-...", model: "gpt-4o" },
+      anthropic: { apiKey: "sk-ant-...", model: "claude-sonnet-4-5" },
+      "openai:backup": { apiKey: "sk-..." },  // Auth profile for rotation
+    },
+    order: {
+      openai: ["openai", "openai:backup"],  // Rotation order
+    },
+  },
+  tools: {
+    brave: { apiKey: "brv-..." },
+    perplexity: { apiKey: "pplx-...", model: "perplexity/sonar-pro" },
+  },
+}
+```
+
+#### 3.11.3 skills.env.json5 Structure
+
+```json5
+{
+  env: {
+    LINEAR_API_KEY: "lin-...",
+    GITHUB_TOKEN: "ghp_...",
+  },
+}
+```
+
+#### 3.11.4 Environment Variable Overrides
+
+| Variable | Purpose |
+|----------|---------|
+| `SMC_CREDENTIALS_PATH` | Override credentials.json5 path |
+| `SMC_SKILLS_ENV_PATH` | Override skills.env.json5 path |
+| `SMC_CREDENTIALS_DISABLE=1` | Disable credentials loading |
+
+---
+
+## 4. Platform Details
+
+### 4.1 Desktop App (Primary)
+
+**Technology**: Electron + Vite + React 19
+
+**Window**: 1200x800, context isolation enabled, node integration disabled
+
+#### 4.1.1 Pages
+
+| Route | Page | Purpose |
+|-------|------|---------|
+| `/` | Home | Hub status, QR code, provider selector, agent settings, device list |
+| `/chat` | Chat | Message history, chat input, mode switcher (local/remote) |
+| `/tools` | Tools | Tool listing and inspection |
+| `/skills` | Skills | Skill listing and management |
+
+**Navigation**: Tab bar at top (Home, Chat, Tools, Skills)
+
+#### 4.1.2 Home Page Components
+
+| Component | Description |
+|-----------|-------------|
+| QR Code | Left side. Shows connection code with 30s countdown. Refresh/copy link buttons. |
+| Hub Status | Right side. Hub ID, connection state indicator (green/yellow/red). |
+| Agent Settings | Agent name (editable). |
+| Provider Selector | Dropdown showing all providers with availability status. API Key dialog or OAuth dialog based on provider type. |
+| Device List | Verified devices with name, platform, revoke button. |
+| Open Chat | Button. Disabled if Hub not connected. |
+| Connect to Remote Agent | Button. Navigate to remote agent connection. |
+
+#### 4.1.3 Chat Page Modes
+
+| Mode | Transport | When Used |
+|------|-----------|-----------|
+| Local Agent | IPC (Electron) | Desktop user talks directly to embedded agent |
+| Remote Agent | WebSocket via Gateway | Desktop user connects to another Hub's agent |
+
+Mode switcher available at top of chat page.
+
+#### 4.1.4 Desktop IPC Channels
+
+| Channel | Direction | Purpose |
+|---------|-----------|---------|
+| `localChat:send` | Renderer → Main | Send message to agent |
+| `localChat:subscribe` | Renderer → Main | Subscribe to agent events |
+| `hub:device-confirm-request` | Main → Renderer | Show device confirmation dialog |
+| `hub:device-confirm-response` | Renderer → Main | User's allow/reject decision |
+
+---
+
+### 4.2 Web App
+
+**Technology**: Next.js 16 + App Router
+
+**Port**: 3001
+
+**Features**:
+- Always requires Gateway connection (no local agent)
+- Uses shared `@multica/ui` Chat component
+- PWA-capable (service worker, offline page)
+- Responsive layout (mobile-first)
+- Light/dark theme toggle
+
+**Page**: Single page rendering `<Chat />` component with `ConnectPrompt` for initial connection.
+
+---
+
+### 4.3 Mobile App
+
+**Technology**: Expo + React Native
+
+**Status**: Demo/prototype (hardcoded mock messages)
+
+**Features**:
+- QR code scanner for device pairing
+- Keyboard-avoiding input bar
+- Auto-expanding text input (max 120px)
+- Auto-scroll to bottom on new messages
+
+---
+
+### 4.4 CLI
+
+**Entry point**: `multica` (alias: `mu`)
+
+#### 4.4.1 Commands
+
+| Command | Description |
+|---------|-------------|
+| `multica` | Interactive chat mode (default) |
+| `multica run "<prompt>"` | Non-interactive single prompt |
+| `multica chat` | Explicit interactive mode |
+| `multica session list/show/delete` | Session management |
+| `multica profile list/new/setup/show/edit/delete` | Profile management |
+| `multica skills list/status/install/add/remove` | Skill management |
+| `multica tools list/groups/profiles` | Tool inspection |
+| `multica credentials init/show/edit` | Credentials management |
+| `multica dev [service]` | Development servers |
+
+#### 4.4.2 Interactive Mode Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/exit` `/quit` `/q` | Exit |
+| `/clear` | Clear session |
+| `/session` | Show current session ID |
+| `/new` | Start new session |
+| `/multiline` | Toggle multi-line input mode |
+| `/provider` | Show provider status |
+| `/model [name]` | Switch model |
+| `/{skillName} [args]` | Execute skill |
+
+**Features**: Autocomplete (Shift+Tab), status bar (session/provider/model), multi-line mode (end with `.`).
+
+#### 4.4.3 Development Servers
+
+| Service | Command | Port |
+|---------|---------|------|
+| Desktop (default) | `multica dev` | Electron window |
+| Gateway | `multica dev gateway` | 3000 |
+| Web | `multica dev web` | 3001 |
+| All | `multica dev all` | 3000 + 3001 |
+
+---
+
+## 5. UI Component Library
+
+Shared package: `@multica/ui`. Used by Desktop, Web, and Mobile.
+
+### 5.1 Chat Components
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `Chat` | (none, uses stores) | Full chat view: connect prompt + message list + input |
+| `ChatInput` | `onSubmit`, `disabled`, `placeholder` | Tiptap editor. Enter=send, Shift+Enter=newline, IME-safe |
+| `ChatInputRef` | (imperative) | `getText()`, `setText()`, `focus()`, `clear()` |
+| `MessageList` | `messages`, `streamingIds` | Renders messages with markdown, tool calls, streaming |
+| `ConnectPrompt` | (none, uses stores) | QR scan + paste code UI for remote connection |
+| `ChatSkeleton` | (none) | Loading skeleton |
+| `ToolCallItem` | `message` | Tool execution display: status dot, label, subtitle, expandable results |
+
+### 5.2 Markdown Components
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `Markdown` | `children`, `mode` (`minimal`/`full`) | Rendered markdown with syntax highlighting |
+| `StreamingMarkdown` | `content`, `isStreaming`, `mode` | Incremental markdown with animated cursor |
+| `CodeBlock` | (internal) | Syntax-highlighted code block with copy button |
+
+### 5.3 Base UI Components (Shadcn/UI)
+
+button, input, textarea, card, dialog, alert-dialog, dropdown-menu, select, combobox, badge, label, field, input-group, switch, skeleton, separator, sheet, sidebar, tooltip, sonner (toasts)
+
+### 5.4 Utility Components
+
+| Component | Description |
+|-----------|-------------|
+| `QRScannerView` | Camera-based QR scanner |
+| `QRScannerSheet` | Sheet variant of QR scanner |
+| `Spinner` | Animated loading spinner |
+| `ThemeProvider` | Light/dark theme context |
+| `ThemeToggle` | Theme switch button |
+
+---
+
+## 6. Data Persistence Locations
+
+| Data | Location | Format | Lifetime |
+|------|----------|--------|----------|
+| Credentials | `~/.super-multica/credentials.json5` | JSON5 | User-managed |
+| Skills env | `~/.super-multica/skills.env.json5` | JSON5 | User-managed |
+| Agent profiles | `~/.super-multica/agent-profiles/{id}/` | MD + JSON | User-managed |
+| Agent memory | `~/.super-multica/agent-profiles/{id}/memory/` | JSON per key | Agent-managed |
+| Sessions | `~/.super-multica/sessions/{id}/session.jsonl` | JSONL | Until deleted |
+| Agent records | `~/.super-multica/agents/agents.json` | JSON | Persistent |
+| Hub ID | `~/.super-multica/hub-id` | Plain text UUID | Generated once |
+| Device whitelist | `~/.super-multica/client-devices/whitelist.json` | JSON | Until revoked |
+| Auth profile stats | `~/.super-multica/.auth-profiles/usage-stats.json` | JSON | Runtime tracking |
+| Verification tokens | In-memory | Map | Lost on restart |
+| Browser device ID | localStorage: `multica-device` | UUID string | Until cleared |
+| Saved connection | localStorage: `multica-connection` | JSON | Until disconnected |
+
+---
+
+## 7. Current Limitations
+
+| Area | Limitation | Notes |
+|------|-----------|-------|
+| Agent count | Desktop creates 1 primary agent on startup | Hub API supports multi-agent (`createAgent`/`listAgents`), but UI only shows one |
+| Device permissions | All-or-nothing access | No per-device capability restrictions |
+| Role system | No formal RBAC | Owner is implicit admin |
+| Mobile app | Demo/prototype | Hardcoded mock data, no real agent connection |
+| Offline web | PWA shell only | Cannot function without Gateway |
+| Skill marketplace | No registry | Install via GitHub URL only |
+| Real-time collaboration | Single agent, sequential messages | No concurrent message processing |
+| File upload | Not supported | Agent can only read files on Owner's filesystem |
+
+---
+
+*Document generated: 2026-02-05*
+*Source: codebase analysis at commit fc6c3e3 on branch feat/mobile-pwa-optimization*