multica/docs/product-capabilities.md

# 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*