docs: add core value propositions and design reference to product capabilities

- Add Section 2: Core Value Propositions for design decision reference - Add primary differentiators, trust-building points, feature priority matrix - Add messaging tone guidelines - Add Exec Approval Protocol (4.3.5) with 4-layer security assessment - Add Channel Integration (4.12) for Telegram and future platforms - Add user-facing value descriptions to all major functional modules - Update section numbering throughout document Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-11 13:46:28 +08:00 · 2026-02-11 13:46:28 +08:00 · 60467c4ad2
commit 60467c4ad2
parent 22db61876b
1 changed files with 282 additions and 83 deletions
--- a/docs/product-capabilities.md
+++ b/docs/product-capabilities.md
@ -1,6 +1,6 @@
 # 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.
+> This document is the single source of truth for all product capabilities. It describes **what exists** and **what value it provides to users**. All subsequent documents (user journeys, UI design, copywriting, design systems) should reference this document.

 ---

@ -19,7 +19,59 @@ Desktop App (standalone, recommended)

 ---

-## 2. User Roles
+## 2. Core Value Propositions
+
+> **Design Reference**: This section summarizes key value propositions for UI/UX design, copywriting, and user communication decisions. Use this as a quick reference when deciding what to emphasize in interfaces and messaging.
+
+### 2.1 Primary Differentiators
+
+These are the core values that distinguish Super Multica. They should be communicated prominently in onboarding, landing pages, and marketing materials.
+
+| Value | User-Facing Message | Technical Basis | Trust Level |
+|-------|---------------------|-----------------|-------------|
+| **Local-First** | "Your data never leaves your computer" | Hub embedded in Desktop, all data stored in `~/.super-multica/` | Core trust point |
+| **Your Keys, Your Control** | "Use your own API keys, switch models anytime" | 10 LLM providers, user-owned credentials | Core trust point |
+| **Safe Execution** | "Every command requires your explicit approval" | 4-layer security assessment + user approval protocol | Core trust point |
+| **Persistent Memory** | "Your agent remembers everything you tell it" | Profile system + Memory tools | Key feature |
+| **Extensible Skills** | "Teach your agent new abilities" | Modular skill system with hot-reload | Key feature |
+| **Multi-Device Access** | "Access from phone, web, anywhere" | Gateway + Device pairing + Telegram integration | Key feature |
+
+### 2.2 Trust-Building Points
+
+These messages should be reinforced throughout the user journey, especially during onboarding and when requesting sensitive permissions.
+
+| Context | What User Worries About | How We Address It |
+|---------|------------------------|-------------------|
+| First launch | "Will this access my files?" | Explicit permission acknowledgment with clear scope |
+| API key entry | "Where is my key stored?" | "Stored locally in `~/.super-multica/credentials.json5`. Never sent to our servers." |
+| Command execution | "What if it runs something dangerous?" | 4-layer safety check + mandatory user approval + allow-once/allow-always options |
+| Memory storage | "What does it remember about me?" | User-controlled, file-based, inspectable at `~/.super-multica/agent-profiles/` |
+| Remote access | "Who can access my agent?" | Device whitelist with explicit approval, one-time tokens, 30s expiry |
+
+### 2.3 Feature Priority Matrix
+
+Use this when designing interfaces to determine information hierarchy and feature prominence.
+
+| Priority | Features | Where to Expose | Design Guidance |
+|----------|----------|-----------------|-----------------|
+| **P0 - Always Visible** | Chat, Provider status, Approval dialogs | Main UI, always accessible | Cannot be hidden or collapsed |
+| **P1 - Primary Features** | Profile selection, Skills list, Session history | Main navigation, 1 click away | Prominent placement |
+| **P2 - Power Features** | Tool policy config, Memory inspection, Multi-provider rotation | Settings or advanced sections | Available but not prominent |
+| **P3 - Developer Features** | Gateway setup, CLI commands, Session JSONL format | Documentation or dev tools | Hidden from casual users |
+
+### 2.4 Messaging Tone Guidelines
+
+| Situation | Tone | Example |
+|-----------|------|---------|
+| Explaining privacy | Reassuring, factual | "All data stays on your machine. We can't access it even if we wanted to." |
+| Requesting permission | Clear, non-alarming | "Multica needs to read files to help you. You control which files." |
+| Command approval | Cautious but not scary | "Review this command before running." (not "DANGER: This could harm your system!") |
+| Error states | Helpful, actionable | "API key invalid. Check your key in Settings → Providers." |
+| Success states | Brief, confident | "Connected." (not "Successfully connected to the server!") |
+
+---
+
+## 3. User Roles

 | Role | Definition | Platform | Authority |
 |------|-----------|----------|-----------|
@ -28,15 +80,19 @@ Desktop App (standalone, recommended)

 There is no formal role/permission system. The Owner is implicit admin by virtue of running the Hub.

+**User-Facing Value**: "You own your agent. Share access with others while keeping full control."
+
 ---

-## 3. Functional Modules
+## 4. Functional Modules

-### 3.1 Agent Engine
+### 4.1 Agent Engine
+
+> **User-Facing Value**: "Your personal AI assistant that can read files, run commands, search the web, and remember what you tell it."

 The core execution unit. An Agent receives user messages, calls an LLM, executes tools, and returns responses.

-#### 3.1.1 Agent Lifecycle
+#### 4.1.1 Agent Lifecycle

 | State | Description |
 |-------|-------------|
@ -47,7 +103,7 @@ The core execution unit. An Agent receives user messages, calls an LLM, executes

 Each `write()` call is queued. Messages are processed sequentially (one at a time).

-#### 3.1.2 Agent Execution Loop
+#### 4.1.2 Agent Execution Loop

 1. Receive user message via `write(content)`
 2. Resolve API credentials (with auth profile rotation)
@ -58,7 +114,7 @@ Each `write()` call is queued. Messages are processed sequentially (one at a tim
 7. Check context window utilization → compact if needed
 8. Emit events to subscribers (streaming to UI)

-#### 3.1.3 Auth Profile Rotation
+#### 4.1.3 Auth Profile Rotation

 When an API call fails, the system classifies the error and may rotate to a different API key:

@ -75,7 +131,7 @@ Failed profiles enter cooldown. Rotation continues until success or all profiles

 Tracking file: `~/.super-multica/.auth-profiles/usage-stats.json`

-#### 3.1.4 Subagent Spawning
+#### 4.1.4 Subagent Spawning

 Agents can spawn child agents via the `sessions_spawn` tool:

@ -85,7 +141,7 @@ Agents can spawn child agents via the `sessions_spawn` tool:
 - Parameters: task (required), label, model override, cleanup policy (`delete` or `keep`), timeout
 - Results announced back to parent automatically

-#### 3.1.5 Agent Configuration Options
+#### 4.1.5 Agent Configuration Options

 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@ -99,7 +155,9 @@ Agents can spawn child agents via the `sessions_spawn` tool:

 ---

-### 3.2 LLM Providers
+### 4.2 LLM Providers
+
+> **User-Facing Value**: "Use your own API keys. Switch between Claude, GPT, Gemini, and more. Your keys, your choice."

 Ten providers supported. Two auth methods: OAuth (CLI login) and API Key.

@ -126,11 +184,13 @@ Ten providers supported. Two auth methods: OAuth (CLI login) and API Key.

 ---

-### 3.3 Tools
+### 4.3 Tools
+
+> **User-Facing Value**: "Your agent can read files, write code, run commands, search the web, and remember things for you."

 Tools are capabilities the Agent can invoke during execution.

-#### 3.3.1 Built-in Tools
+#### 4.3.1 Built-in Tools

 | Tool | Category | Description |
 |------|----------|-------------|
@ -148,7 +208,7 @@ Tools are capabilities the Agent can invoke during execution.
 | `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)
+#### 4.3.2 Tool Groups (shortcuts for policy)

 | Group | Tools Included |
 |-------|---------------|
@ -159,7 +219,7 @@ Tools are capabilities the Agent can invoke during execution.
 | `group:subagent` | sessions_spawn |
 | `group:core` | read, write, edit, glob, exec, process, web_search, web_fetch |

-#### 3.3.3 Tool Policy System (3 layers)
+#### 4.3.3 Tool Policy System (3 layers)

 | Layer | Scope | Description |
 |-------|-------|-------------|
@ -169,13 +229,63 @@ Tools are capabilities the Agent can invoke during execution.

 **Priority**: Deny always overrides Allow. Empty allow list = deny all.

-#### 3.3.4 Exec Tool Details
+#### 4.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
+#### 4.3.5 Exec Approval Protocol
+
+> **User-Facing Value**: "Every shell command requires your explicit approval. You're always in control."
+
+The exec tool implements a 4-layer security assessment before any command execution:
+
+| Layer | Check | Examples | Result if Failed |
+|-------|-------|----------|------------------|
+| 1. Whitelist | Glob pattern match against allowed commands | `git *`, `npm install` | Skip to next layer |
+| 2. Shell Syntax | Dangerous shell constructs detection | `$(...)`, backticks, pipes to dangerous commands | `dangerous` |
+| 3. Safe Binaries | ~40 known-safe read-only commands | `ls`, `cat`, `grep`, `git status` | `safe` if matched |
+| 4. Danger Patterns | 25+ regex patterns for risky operations | `rm -rf`, `chmod 777`, `curl | sh` | `dangerous` if matched |
+
+**Risk Levels**:
+
+| Level | Meaning | User Action Required |
+|-------|---------|---------------------|
+| `safe` | Read-only or whitelisted command | Auto-approved (configurable) |
+| `needs-review` | Unknown command, not obviously dangerous | User must approve |
+| `dangerous` | Matches danger pattern or shell injection risk | User must approve with warning |
+
+**User Approval Options**:
+
+| Option | Effect | Persistence |
+|--------|--------|-------------|
+| Allow Once | Execute this command only | This execution only |
+| Allow Always | Add to session whitelist | Until session ends |
+| Deny | Block execution | This execution only |
+
+**Approval Flow**:
+
+```
+Agent requests exec("npm install express")
+    ↓
+4-layer security check → "needs-review"
+    ↓
+Desktop shows approval dialog:
+  "The agent wants to run: npm install express"
+  [Allow Once] [Allow Always] [Deny]
+    ↓
+User clicks "Allow Once"
+    ↓
+Command executes, result returned to agent
+```
+
+**Design Guidance**: This is a core trust-building feature. The approval dialog should be:
+- Clear and non-alarming for safe commands
+- Appropriately cautious for dangerous commands
+- Never auto-dismissed or timed out (user must act)
+
+#### 4.3.6 Web Search Details

 - Brave provider: up to 10 results, country filtering, freshness filters (`pd`/`pw`/`pm`/`py`)
 - Perplexity provider: AI-synthesized answers
@ -183,11 +293,13 @@ Tools are capabilities the Agent can invoke during execution.

 ---

-### 3.4 Profile System
+### 4.4 Profile System
+
+> **User-Facing Value**: "Give your agent a personality. Define how it talks, what it knows, and how it works."

 A Profile defines an Agent's identity, personality, knowledge, and configuration.

-#### 3.4.1 Profile File Structure
+#### 4.4.1 Profile File Structure

 ```
 ~/.super-multica/agent-profiles/{profileId}/
@ -204,7 +316,7 @@ A Profile defines an Agent's identity, personality, knowledge, and configuration
        └── SKILL.md
 ```

-#### 3.4.2 Profile Config (config.json)
+#### 4.4.2 Profile Config (config.json)

 ```json
 {
@ -220,7 +332,7 @@ A Profile defines an Agent's identity, personality, knowledge, and configuration
 }
 ```

-#### 3.4.3 Profile Operations
+#### 4.4.3 Profile Operations

 | Operation | CLI | Desktop |
 |-----------|-----|---------|
@ -233,7 +345,7 @@ A Profile defines an Agent's identity, personality, knowledge, and configuration

 **Profile ID rules**: alphanumeric, hyphens, underscores only.

-#### 3.4.4 System Prompt Composition
+#### 4.4.4 System Prompt Composition

 The system prompt is built dynamically from profile files:

@ -253,11 +365,13 @@ The system prompt is built dynamically from profile files:

 ---

-### 3.5 Memory System
+### 4.5 Memory System
+
+> **User-Facing Value**: "Your agent remembers what you tell it. Preferences, facts, context—it's all there next time."

 Agents can persistently store and recall information across sessions.

-#### 3.5.1 Storage
+#### 4.5.1 Storage

 - Location: `~/.super-multica/agent-profiles/{profileId}/memory/`
 - Format: One JSON file per key
@ -265,7 +379,7 @@ Agents can persistently store and recall information across sessions.
 - Dots in keys are escaped as `__DOT__` in filenames
 - Max value size: 1MB

-#### 3.5.2 Entry Format
+#### 4.5.2 Entry Format

 ```json
 {
@ -276,7 +390,7 @@ Agents can persistently store and recall information across sessions.
 }
 ```

-#### 3.5.3 Memory Tools
+#### 4.5.3 Memory Tools

 | Tool | Input | Output |
 |------|-------|--------|
@ -289,11 +403,13 @@ Agents can persistently store and recall information across sessions.

 ---

-### 3.6 Skills System
+### 4.6 Skills System
+
+> **User-Facing Value**: "Teach your agent new tricks. Install skills for Git, code review, and more."

 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)
+#### 4.6.1 Skill File Format (SKILL.md)

 ```yaml
 ---
@ -314,7 +430,7 @@ metadata:
 # Full markdown instructions follow...
 ```

-#### 3.6.2 Skill Sources & Precedence
+#### 4.6.2 Skill Sources & Precedence

 | Source | Location | Precedence |
 |--------|----------|-----------|
@ -324,7 +440,7 @@ metadata:

 Profile skills with the same ID completely replace global/bundled versions.

-#### 3.6.3 Bundled Skills
+#### 4.6.3 Bundled Skills

 | Skill | ID | Description | Requirements |
 |-------|----|-------------|-------------|
@ -333,7 +449,7 @@ Profile skills with the same ID completely replace global/bundled versions.
 | 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
+#### 4.6.4 Eligibility Check Sequence

 1. Explicit disable in config → ineligible
 2. Bundled + not in allowlist → ineligible
@ -347,13 +463,13 @@ Profile skills with the same ID completely replace global/bundled versions.

 Returns human-readable failure reasons (e.g., "Required binary not found: git").

-#### 3.6.5 Skill Invocation
+#### 4.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
+#### 4.6.6 Skill Installation

 ```bash
 multica skills add owner/repo              # Clone entire repository
@ -364,18 +480,20 @@ multica skills add owner/repo -p my-agent  # Install to profile

 ---

-### 3.7 Session Management
+### 4.7 Session Management
+
+> **User-Facing Value**: "Pick up where you left off. Your conversation history is always saved."

 Sessions persist conversation history across interactions.

-#### 3.7.1 Session Storage
+#### 4.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
+#### 4.7.2 Message Format

 Messages follow the LLM API format:

@ -385,13 +503,13 @@ Messages follow the LLM API format:
 {"type": "message", "role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "file contents"}]}
 ```

-#### 3.7.3 Session Metadata
+#### 4.7.3 Session Metadata

 ```json
 {"type": "meta", "provider": "anthropic", "model": "claude-sonnet-4-5", "reasoningMode": "off", "contextWindowTokens": 200000}
 ```

-#### 3.7.4 Context Window Management
+#### 4.7.4 Context Window Management

 | Parameter | Value | Description |
 |-----------|-------|-------------|
@ -404,7 +522,7 @@ Messages follow the LLM API format:
 | Min keep messages | 10 | Never remove below this |
 | Reserve tokens | 1,024 | Reserved for response generation |

-#### 3.7.5 Compaction Modes
+#### 4.7.5 Compaction Modes

 | Mode | Strategy | Speed | Quality |
 |------|----------|-------|---------|
@ -412,7 +530,7 @@ Messages follow the LLM API format:
 | `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
+#### 4.7.6 Session Operations

 | Operation | CLI Command |
 |-----------|-------------|
@ -423,11 +541,11 @@ Messages follow the LLM API format:

 ---

-### 3.8 Hub
+### 4.8 Hub

 The Hub is the central coordinator. It manages agent lifecycle, routes messages, and handles device verification.

-#### 3.8.1 Responsibilities
+#### 4.8.1 Responsibilities

 - Create, list, restore, close agents
 - Persist agent metadata to disk (`~/.super-multica/agents/agents.json`)
@ -435,7 +553,7 @@ The Hub is the central coordinator. It manages agent lifecycle, routes messages,
 - Handle device verification and whitelisting
 - Process RPC requests from connected clients

-#### 3.8.2 Hub RPC Methods
+#### 4.8.2 Hub RPC Methods

 | Method | Description | Error Codes |
 |--------|-------------|-------------|
@ -447,27 +565,27 @@ The Hub is the central coordinator. It manages agent lifecycle, routes messages,
 | `deleteAgent` | Delete agent | - |
 | `updateGateway` | Update Gateway connection | - |

-#### 3.8.3 Hub Singleton
+#### 4.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
+### 4.9 Gateway

 NestJS WebSocket server that enables remote client access to the Hub.

-#### 3.9.1 Purpose
+#### 4.9.1 Purpose

 Bridges remote clients (web/mobile) to the Hub. Not needed for local Desktop use.

-#### 3.9.2 Connection Protocol
+#### 4.9.2 Connection Protocol

 - Transport: Socket.io
 - Path: `/ws`
 - Port: 3000 (default)

-#### 3.9.3 Timeouts
+#### 4.9.3 Timeouts

 | Parameter | Value |
 |-----------|-------|
@ -477,13 +595,13 @@ Bridges remote clients (web/mobile) to the Hub. Not needed for local Desktop use
 | Verify timeout | 30 seconds |
 | Reconnect delay | 1 second |

-#### 3.9.4 Message Routing
+#### 4.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
+#### 4.9.5 Error Codes

 | Code | Meaning |
 |------|---------|
@ -493,11 +611,13 @@ Bridges remote clients (web/mobile) to the Hub. Not needed for local Desktop use

 ---

-### 3.10 Device Pairing & Verification
+### 4.10 Device Pairing & Verification
+
+> **User-Facing Value**: "Scan a QR code to connect from your phone. Approve which devices can access your agent."

 How remote devices (web/mobile) connect to the Owner's Hub.

-#### 3.10.1 QR Code Generation (Desktop)
+#### 4.10.1 QR Code Generation (Desktop)

 The Desktop app generates a QR code containing:

@ -517,7 +637,7 @@ The Desktop app generates a QR code containing:
 - 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)
+#### 4.10.2 Connection Code Formats (accepted by client)

 | Format | Example |
 |--------|---------|
@ -525,7 +645,7 @@ The Desktop app generates a QR code containing:
 | Base64 JSON | Base64-encoded JSON string |
 | URL | `multica://connect?gateway=...&hub=...&agent=...&token=...&exp=...` |

-#### 3.10.3 Verification Flow
+#### 4.10.3 Verification Flow

 ```
 1. Mobile scans QR / pastes code
@ -542,7 +662,7 @@ The Desktop app generates a QR code containing:
 9. If rejected: connection closed
 ```

-#### 3.10.4 Device Whitelist
+#### 4.10.4 Device Whitelist

 - Location: `~/.super-multica/client-devices/whitelist.json`
 - Format:
@ -563,17 +683,17 @@ The Desktop app generates a QR code containing:
 }
 ```

-#### 3.10.5 Reconnection (whitelisted device)
+#### 4.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)
+#### 4.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
+#### 4.10.7 Security Model

 | Aspect | Detail |
 |--------|--------|
@ -587,9 +707,9 @@ Whitelisted devices reconnect without needing a new token or user confirmation.

 ---

-### 3.11 Credentials System
+### 4.11 Credentials System

-#### 3.11.1 Files
+#### 4.11.1 Files

 | File | Purpose | Permissions |
 |------|---------|-------------|
@ -598,7 +718,7 @@ Whitelisted devices reconnect without needing a new token or user confirmation.

 Format: JSON5 (supports comments, trailing commas, unquoted keys).

-#### 3.11.2 credentials.json5 Structure
+#### 4.11.2 credentials.json5 Structure

 ```json5
 {
@ -621,7 +741,7 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).
 }
 ```

-#### 3.11.3 skills.env.json5 Structure
+#### 4.11.3 skills.env.json5 Structure

 ```json5
 {
@ -632,7 +752,7 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).
 }
 ```

-#### 3.11.4 Environment Variable Overrides
+#### 4.11.4 Environment Variable Overrides

 | Variable | Purpose |
 |----------|---------|
@ -642,15 +762,93 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).

 ---

-## 4. Platform Details
+### 4.12 Channel Integration

-### 4.1 Desktop App (Primary)
+> **User-Facing Value**: "Chat with your agent from Telegram, anywhere, anytime. Your agent is always accessible."
+
+Channels enable external messaging platforms to communicate with the Agent. Currently supported: Telegram.
+
+#### 4.12.1 Architecture
+
+```
+External Platform (Telegram)
+    ↓
+Channel Adapter (grammy library)
+    ↓
+Channel Manager (message routing)
+    ↓
+Hub → Agent Engine
+    ↓
+Response routed back via lastRoute
+```
+
+#### 4.12.2 Telegram Channel
+
+| Feature | Description |
+|---------|-------------|
+| **Connection Mode** | Long polling (default) or Webhook |
+| **Bot Setup** | User creates bot via @BotFather, provides token |
+| **Message Handling** | Text messages forwarded to Agent |
+| **Response Routing** | Replies sent back to same Telegram chat |
+| **Message Chunking** | Long responses split into multiple messages (4096 char limit) |
+
+**Setup Flow**:
+
+1. User opens @BotFather in Telegram
+2. Creates new bot with `/newbot`
+3. Copies bot token (format: `123456789:ABCdefGHI...`)
+4. Pastes token in Multica Desktop → Settings → Channels
+5. Bot starts, ready to receive messages
+
+**Status Indicators**:
+
+| Status | Meaning | User Action |
+|--------|---------|-------------|
+| `starting` | Bot initializing | Wait |
+| `running` | Bot active, receiving messages | None |
+| `error` | Connection failed | Check token, retry |
+| `stopped` | Bot disabled | Enable in settings |
+
+#### 4.12.3 Message Path Routing
+
+The system maintains a `lastRoute` to ensure responses go back through the correct channel:
+
+| Message Source | Route | Response Destination |
+|----------------|-------|---------------------|
+| Desktop IPC | `local` | Desktop chat UI |
+| Web/Mobile via Gateway | `gateway:{deviceId}` | Same device via Gateway |
+| Telegram | `telegram:{chatId}` | Same Telegram chat |
+
+**Design Note**: This routing is automatic. Users don't need to understand it, but it enables seamless multi-channel conversations.
+
+#### 4.12.4 Future Extensibility
+
+The channel architecture is designed to support additional platforms:
+
+| Potential Channel | Status | Notes |
+|-------------------|--------|-------|
+| Discord | Planned | Similar bot model to Telegram |
+| Slack | Planned | Workspace app integration |
+| WhatsApp | Considered | Business API required |
+| Email | Considered | IMAP/SMTP integration |
+
+**Design Guidance**: When designing channel settings UI, use a consistent pattern:
+- Platform icon + name
+- Connection status indicator
+- Setup/configure button
+- Disconnect option
+
+---
+
+## 5. Platform Details
+
+### 5.1 Desktop App (Primary)

 **Technology**: Electron + Vite + React 19

 **Window**: 1200x800, context isolation enabled, node integration disabled

-#### 4.1.1 Pages
+#### 5.1.1 Pages

 | Route | Page | Purpose |
 |-------|------|---------|
@ -661,7 +859,7 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).

 **Navigation**: Tab bar at top (Home, Chat, Tools, Skills)

-#### 4.1.2 Home Page Components
+#### 5.1.2 Home Page Components

 | Component | Description |
 |-----------|-------------|
@ -673,7 +871,7 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).
 | Open Chat | Button. Disabled if Hub not connected. |
 | Connect to Remote Agent | Button. Navigate to remote agent connection. |

-#### 4.1.3 Chat Page Modes
+#### 5.1.3 Chat Page Modes

 | Mode | Transport | When Used |
 |------|-----------|-----------|
@ -682,7 +880,7 @@ Format: JSON5 (supports comments, trailing commas, unquoted keys).

 Mode switcher available at top of chat page.

-#### 4.1.4 Desktop IPC Channels
+#### 5.1.4 Desktop IPC Channels

 | Channel | Direction | Purpose |
 |---------|-----------|---------|
@ -693,7 +891,7 @@ Mode switcher available at top of chat page.

 ---

-### 4.2 Web App
+### 5.2 Web App

 **Technology**: Next.js 16 + App Router

@ -710,7 +908,7 @@ Mode switcher available at top of chat page.

 ---

-### 4.3 Mobile App
+### 5.3 Mobile App

 **Technology**: Expo + React Native

@ -724,11 +922,11 @@ Mode switcher available at top of chat page.

 ---

-### 4.4 CLI
+### 5.4 CLI

 **Entry point**: `multica` (alias: `mu`)

-#### 4.4.1 Commands
+#### 5.4.1 Commands

 | Command | Description |
 |---------|-------------|
@ -742,7 +940,7 @@ Mode switcher available at top of chat page.
 | `multica credentials init/show/edit` | Credentials management |
 | `multica dev [service]` | Development servers |

-#### 4.4.2 Interactive Mode Commands
+#### 5.4.2 Interactive Mode Commands

 | Command | Description |
 |---------|-------------|
@ -758,7 +956,7 @@ Mode switcher available at top of chat page.

 **Features**: Autocomplete (Shift+Tab), status bar (session/provider/model), multi-line mode (end with `.`).

-#### 4.4.3 Development Servers
+#### 5.4.3 Development Servers

 | Service | Command | Port |
 |---------|---------|------|
@ -769,11 +967,11 @@ Mode switcher available at top of chat page.

 ---

-## 5. UI Component Library
+## 6. UI Component Library

 Shared package: `@multica/ui`. Used by Desktop, Web, and Mobile.

-### 5.1 Chat Components
+### 6.1 Chat Components

 | Component | Props | Description |
 |-----------|-------|-------------|
@ -785,7 +983,7 @@ Shared package: `@multica/ui`. Used by Desktop, Web, and Mobile.
 | `ChatSkeleton` | (none) | Loading skeleton |
 | `ToolCallItem` | `message` | Tool execution display: status dot, label, subtitle, expandable results |

-### 5.2 Markdown Components
+### 6.2 Markdown Components

 | Component | Props | Description |
 |-----------|-------|-------------|
@ -793,11 +991,11 @@ Shared package: `@multica/ui`. Used by Desktop, Web, and Mobile.
 | `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)
+### 6.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
+### 6.4 Utility Components

 | Component | Description |
 |-----------|-------------|
@ -809,7 +1007,7 @@ button, input, textarea, card, dialog, alert-dialog, dropdown-menu, select, comb

 ---

-## 6. Data Persistence Locations
+## 7. Data Persistence Locations

 | Data | Location | Format | Lifetime |
 |------|----------|--------|----------|
@ -828,7 +1026,7 @@ button, input, textarea, card, dialog, alert-dialog, dropdown-menu, select, comb

 ---

-## 7. Current Limitations
+## 8. Current Limitations

 | Area | Limitation | Notes |
 |------|-----------|-------|
@ -843,5 +1041,6 @@ button, input, textarea, card, dialog, alert-dialog, dropdown-menu, select, comb

 ---

-*Document generated: 2026-02-05*
-*Source: codebase analysis at commit fc6c3e3 on branch feat/mobile-pwa-optimization*
+*Document generated: 2026-02-11*
+*Source: codebase analysis on branch feat/onboarding-check*
+*Updates: Added Core Value Propositions (Section 2), Exec Approval Protocol (4.3.5), Channel Integration (4.12), user-facing value descriptions for all major modules*