@robota-sdk/agent-cli 3.0.0-beta.7 → 3.0.0-beta.71

package/README.md

@@ -1,17 +1,72 @@
+**Language:** [English](README.md) | [한국어](docs/README-KO.md)
+
+> **Beta software** — currently `3.0.0-beta`. APIs and behavior may change before stable release.
+> Please [report issues](https://github.com/woojubb/robota/issues) to help us improve.
+
 # @robota-sdk/agent-cli
 
-AI coding assistant CLI built on Robota SDK. Loads AGENTS.md/CLAUDE.md for project context and provides tool-calling REPL with Claude Code-compatible permission modes.
+AI coding assistant CLI built on Robota SDK. Loads AGENTS.md/CLAUDE.md for project context and provides a tool-calling REPL with Claude Code-compatible permission modes.
 
-## Installation
+## Why Robota?
+
+|                                                   | Robota | Claude Code | Aider |
+| ------------------------------------------------- | :----: | :---------: | :---: |
+| Multi-provider (Anthropic, OpenAI, Gemini, Qwen…) |   ✅   |     ❌      |  ✅   |
+| Embed SDK in your own app                         |   ✅   |     ❌      |  ❌   |
+| Local models (LM Studio, Ollama via OpenAI API)   |   ✅   |     ❌      |  ✅   |
+| Open source (MIT)                                 |   ✅   |   partial   |  ✅   |
+| Claude Code config compatible (CLAUDE.md, modes)  |   ✅   |      —      |  ❌   |
+
+## Embed in Your App
+
+```typescript
+import { createAgentRuntime } from '@robota-sdk/agent-framework';
+import { createAnthropicProvider } from '@robota-sdk/agent-provider';
+
+const runtime = createAgentRuntime({
+  provider: createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
+});
+const session = runtime.createSession({ permissionMode: 'bypassPermissions' });
+const response = await session.submit('Explain this codebase');
+```
+
+## Prerequisites
+
+Node.js **22 or higher** is required. The TUI renderer ([ink 7.x](https://github.com/vadimdemedes/ink)) requires Node.js 22+.
 
 ```bash
-# Global install
-npm install -g @robota-sdk/agent-cli
+node --version  # Must output v22.x.x or higher
+```
+
+If your version is below 22, upgrade using one of:
+
+```bash
+# nvm
+nvm install 22 && nvm use 22
+
+# Volta
+volta install node@22
+```
+
+## Demo
+
+<!-- TODO: Add demo GIF here -->
+<!-- Run `pnpm demo:record` to capture a demo recording — see docs/demo-script.md for instructions -->
+
+![Demo](./docs/demo.gif)
+
+## Installation
 
-# Or run directly with npx
+```bash
+# Try it now — no install needed
 npx @robota-sdk/agent-cli
+
+# Install globally for persistent use
+npm install -g @robota-sdk/agent-cli
 ```
 
+> **macOS users**: Korean/CJK IME input may crash macOS Terminal.app. Use **[iTerm2](https://iterm2.com/)** instead. This is a known Ink + Terminal.app issue shared with Claude Code.
+
 After installing globally, the `robota` command is available system-wide:
 
 ```bash
@@ -22,9 +77,14 @@ robota -p "List all files"    # Print mode (one-shot, exit after response)
 
 ### Environment Variables
 
-| Variable            | Description       | Required |
-| ------------------- | ----------------- | -------- |
-| `ANTHROPIC_API_KEY` | Anthropic API key | Yes      |
+| Variable            | Description                                              | Provider  |
+| ------------------- | -------------------------------------------------------- | --------- |
+| `ANTHROPIC_API_KEY` | Anthropic API key                                        | Anthropic |
+| `OPENAI_API_KEY`    | OpenAI API key                                           | OpenAI    |
+| `GEMINI_API_KEY`    | Google Gemini API key                                    | Gemini    |
+| `DEEPSEEK_API_KEY`  | DeepSeek API key                                         | DeepSeek  |
+| `DASHSCOPE_API_KEY` | Alibaba Cloud Model Studio key                           | Qwen      |
+| `BRAVE_API_KEY`     | Brave Search API key (optional — enables WebSearch tool) | WebSearch |
 
 Set your key before running:
 
@@ -35,11 +95,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 ## Development Setup (Monorepo)
 
 ```bash
-# 1. Copy .env.example and add your Anthropic API key
-cp packages/agent-cli/.env.example packages/agent-cli/.env
-# Edit .env and set ANTHROPIC_API_KEY=sk-ant-...
-
-# 2. Build dependencies and CLI
+# Build dependencies and CLI
 pnpm build:deps
 pnpm --filter @robota-sdk/agent-cli build
 ```
@@ -50,7 +106,7 @@ pnpm --filter @robota-sdk/agent-cli build
 # From monorepo root
 cd packages/agent-cli
 
-# Development mode (no build needed, auto-loads .env)
+# Development mode (no build needed)
 pnpm dev
 
 # Production mode (requires build)
@@ -70,74 +126,142 @@ robota "prompt"                     # REPL with initial prompt
 robota -p "prompt"                  # Print mode (one-shot, exit after response)
 robota -c                           # Continue last session
 robota -r <session-id>              # Resume session by ID
-robota --model <model>              # Model override (e.g., claude-sonnet-4-6)
+robota --language <lang>            # Response language (ko, en, ja, zh)
 robota --permission-mode <mode>     # plan | default | acceptEdits | bypassPermissions
 robota --max-turns <n>              # Limit agentic turns per interaction
+robota --output-format <fmt>        # text | json | stream-json (print mode)
+robota --system-prompt <text>       # Replace system prompt (print mode)
+robota --append-system-prompt <text> # Append to system prompt (print mode)
+robota --model claude-opus-4-7       # Override provider model for this session
+robota --allowed-tools "Bash,Read"  # Whitelist specific tools
+robota --denied-tools "Bash,Write"  # Blacklist specific tools (denied > allowed)
+robota --reset                      # Delete user settings and exit
+robota --check-update               # Check npm for a newer CLI version and exit
+robota --disable-update-check        # Skip interactive startup update check for this run
 robota --version                    # Show version
 ```
 
-## Built-in Tools
+### CLI Updates
 
-The CLI provides 6 tools that the AI agent can invoke:
+Robota can check npm for a newer `@robota-sdk/agent-cli` version:
 
-| Tool    | Description                          | Primary Argument |
-| ------- | ------------------------------------ | ---------------- |
-| `Bash`  | Execute shell commands               | `command`        |
-| `Read`  | Read file contents with line numbers | `filePath`       |
-| `Write` | Write content to a file              | `filePath`       |
-| `Edit`  | Replace a string in a file           | `filePath`       |
-| `Glob`  | Find files matching a pattern        | `pattern`        |
-| `Grep`  | Search file contents with regex      | `pattern`        |
+```bash
+robota --check-update
+```
 
-## Permission System
+When an update is available, Robota prints the npm global install command:
 
-Every tool call passes through a three-step permission gate before execution:
+```bash
+npm install -g '@robota-sdk/agent-cli@latest'
+```
 
-1. **Deny list** — if any deny pattern matches, the action is blocked immediately
-2. **Allow list** — if any allow pattern matches, the action is auto-approved
-3. **Mode policy** — the active permission mode determines the decision
+Robota does not implement its own updater and does not modify `~/.robota/settings.json` for update checks. Interactive startup checks use a user-level operational cache at `~/.robota/update-check.json` and can be skipped for one run with `--disable-update-check`. Print/headless mode (`robota -p`) does not perform automatic startup update checks so scripted stdout and stderr remain deterministic.
 
-When a tool requires approval, the user sees an interactive prompt:
+### Print Mode Output Formats
 
-```
-[Permission Required] Tool: Bash
-  Arguments: command: rm -rf dist
-Allow? [y/N]
+Print mode (`-p`) supports three output formats via `--output-format`:
+
+| Format        | Description                                                        |
+| ------------- | ------------------------------------------------------------------ |
+| `text`        | Plain text response to stdout (default)                            |
+| `json`        | Single JSON object: `{ type, result, session_id, subtype }`        |
+| `stream-json` | Newline-delimited JSON with `content_block_delta` streaming events |
+
+### Exit Codes (print mode)
+
+| Code | Meaning                                        |
+| ---- | ---------------------------------------------- |
+| 0    | Success                                        |
+| 1    | General error                                  |
+| 2    | Argument error                                 |
+| 3    | Configuration error (missing provider/API key) |
+| 4    | API error                                      |
+| 5    | Tool execution error                           |
+
+### Stdin Pipe
+
+When stdin is piped, the CLI reads it automatically. If a positional prompt is also given, the piped content is appended inside `<stdin>` tags:
+
+```bash
+echo "Explain this error" | robota -p
+cat file.ts | robota -p "Review this code" --output-format json
+git diff | robota -p "Summarize changes" --output-format stream-json
 ```
 
-- Type `y` or `yes` to approve
-- Press Enter or type anything else to deny
+## First-Run Setup
 
-If denied, the AI agent receives a "Permission denied" error and can adjust its approach.
+When no usable settings file exists, the CLI prompts for:
 
-### Permission Modes
+1. **Provider selection** from the providers assembled into the CLI binary
+2. **Provider-specific setup fields** such as model, base URL, and masked API key
+3. **Response language** (ko/en/ja/zh, default: en)
 
-| Mode                | Alias    | Read/Glob/Grep | Write/Edit |  Bash   |
-| ------------------- | -------- | :------------: | :--------: | :-----: |
-| `plan`              | safe     |      auto      |    deny    |  deny   |
-| `default`           | moderate |      auto      |  approve   | approve |
-| `acceptEdits`       | full     |      auto      |    auto    | approve |
-| `bypassPermissions` | —        |      auto      |    auto    |  auto   |
+Creates `~/.robota/settings.json`. Use `robota --reset` to return to first-run state.
 
-- **auto** — tool executes without prompting
-- **approve** — user is prompted to allow or deny
-- **deny** — tool is blocked silently (no prompt shown)
+Provider setup is generated from provider definitions. The default CLI build includes Anthropic,
+OpenAI-compatible, DeepSeek, Gemma, and Qwen providers; other embeddings can inject their own
+provider definitions.
+Interactive setup creates a readable profile key from the selected model id, such as
+`claude-sonnet-4-6` or `gpt-4o`, and appends `-2`, `-3`, etc. when that key already exists. Generated
+profile keys never include API keys or credential hints.
 
-Unknown tools default to `approve` in most modes, `deny` in `plan` mode.
+Inside the TUI, `/provider` and `/provider list` show configured profiles as an interactive picker. Selecting a profile opens command-owned actions for switch, edit, test, duplicate, delete, and cancel. Headless mode prints the same profile list text without opening prompts.
 
-### Changing Mode at Runtime
+Non-interactive/headless mode never prompts. Configure a provider ahead of time with `robota --configure` in an interactive terminal, or use `robota --configure-provider <profile> --type <type> ... --set-current`.
 
-Use the `/mode` slash command in the REPL:
+## Built-in Tools
 
-```
-> /mode                    # Show current mode
-Current permission mode: default
+The AI agent can invoke 8 local tools:
+
+| Tool        | Description                                    | Primary Argument |
+| ----------- | ---------------------------------------------- | ---------------- |
+| `Bash`      | Execute shell commands                         | `command`        |
+| `Read`      | Read file contents with line numbers           | `filePath`       |
+| `Write`     | Write content to a file                        | `filePath`       |
+| `Edit`      | Replace a string in a file                     | `filePath`       |
+| `Glob`      | Find files matching a pattern                  | `pattern`        |
+| `Grep`      | Search file contents with regex                | `pattern`        |
+| `WebFetch`  | Fetch URL content as text                      | `url`            |
+| `WebSearch` | Search the internet (requires `BRAVE_API_KEY`) | `query`          |
+
+> **WebSearch** requires a `BRAVE_API_KEY` environment variable. Without it, the tool returns a setup message instead of results. Get a free key at [brave.com/search/api](https://brave.com/search/api/) (2,000 queries/month free tier).
 
-> /mode plan               # Switch to plan (read-only)
-Permission mode set to: plan
+## Recent TUI Capabilities
+
+- Provider setup and profile management are generated from provider definitions, so the default CLI
+  build can configure, switch, edit, test, duplicate, and delete Anthropic, OpenAI-compatible,
+  DeepSeek, Gemma, and Qwen profiles without provider-specific UI branches.
+- Interactive startup can check npm for newer CLI versions; print/headless mode skips startup update checks to keep scripted output deterministic.
+- Long-running sessions show provider usage summaries, status activity, background job tree rows, and collapsed command-output transcripts.
+- Edit results render as context hunks with markdown-friendly diff blocks.
+- Background subagents are real runtime jobs with transcripts and resumable task snapshots.
+- Explicit multi-agent requests use the `/agent` command module batch path through the SDK runtime.
+
+## Permission System
+
+Every tool call passes through a three-step permission gate:
+
+1. **Deny list** — if any deny pattern matches, the action is blocked
+2. **Allow list** — if any allow pattern matches, the action is auto-approved
+3. **Mode policy** — the active permission mode determines the decision
+
+### Permission Modes
+
+| Mode                | Read/Glob/Grep | Write/Edit |  Bash   |
+| ------------------- | :------------: | :--------: | :-----: |
+| `plan`              |      auto      |    deny    |  deny   |
+| `default`           |      auto      |  approve   | approve |
+| `acceptEdits`       |      auto      |    auto    | approve |
+| `bypassPermissions` |      auto      |    auto    |  auto   |
+
+### Changing Mode at Runtime
+
+Use the `/permissions` slash command:
 
-> /mode bypassPermissions  # Skip all prompts
-Permission mode set to: bypassPermissions
+```
+> /permissions                    # Show current mode and session-approved tools
+> /permissions plan               # Switch to plan (read-only)
+> /permissions bypassPermissions  # Skip all prompts
 ```
 
 Or set it at startup:
@@ -146,7 +270,7 @@ Or set it at startup:
 robota --permission-mode plan
 ```
 
-### Permission Patterns (allow/deny lists)
+### Permission Patterns
 
 Configure in `.robota/settings.json` or `.robota/settings.local.json`:
 
@@ -159,42 +283,167 @@ Configure in `.robota/settings.json` or `.robota/settings.local.json`:
 }
 ```
 
-**Pattern syntax:**
+Pattern syntax: `ToolName` matches any invocation; `ToolName(pattern)` matches on the primary argument with shell-style globs (`*`, `**`).
+
+## Keyboard Controls
+
+| Key        | Action                                                      |
+| ---------- | ----------------------------------------------------------- |
+| Enter      | Submit input                                                |
+| ESC        | Abort current execution (graceful — saves partial response) |
+| Ctrl+C     | Exit process immediately                                    |
+| Up/Down    | Navigate visual lines in wrapped multi-line input           |
+| Arrow keys | Navigate slash command autocomplete, permission prompt      |
+
+## Paste Handling
 
-- `ToolName` — match any invocation of that tool (e.g., `Bash`)
-- `ToolName(pattern)` — match when the primary argument matches the glob (e.g., `Bash(pnpm *)`)
-- `*` — zero or more characters (shell-style)
-- `**` — one or more characters (recursive path matching)
+Bracketed paste mode (DECSET 2004) is enabled on startup. When pasting multiline text, the input area collapses it into a label: `[Pasted text #1 +42 lines]`. Multiple pastes are numbered sequentially. The full content is expanded on submit.
 
-**Evaluation order:** deny patterns are checked first, then allow patterns, then the mode policy. Deny always wins.
+Single-line paste is inserted directly as typed text. Terminals without bracketed paste fall back to heuristic detection.
+
+## Edit Diff Display
+
+After the Edit tool runs, a `DiffBlock` component renders the change inline:
+
+```
+  ✓ Edit(src/provider.ts)
+    │ src/provider.ts
+    │ - const DEFAULT_MAX_TOKENS = 4096;
+    │ + const maxTokens = getModelMaxOutput(modelId);
+```
+
+Removed lines appear in red with `-`, added lines in green with `+`. Diffs longer than 10 lines show the first 8 + a `... and N more lines` summary.
+
+## Session Management
+
+The CLI supports continuing, resuming, forking, and naming sessions.
+
+### CLI Flags
+
+| Flag                  | Description                                      |
+| --------------------- | ------------------------------------------------ |
+| `-c`, `--continue`    | Continue the most recent session                 |
+| `-r`, `--resume <id>` | Resume a specific session by ID                  |
+| `--fork-session <id>` | Fork a session (new session with copied history) |
+| `--name <name>`       | Assign a name to the session at startup          |
+
+### TUI Commands
+
+| Command          | Description                         |
+| ---------------- | ----------------------------------- |
+| `/resume`        | List recent sessions and resume one |
+| `/rename <name>` | Rename the current session          |
+
+### Session Name Display
+
+When a session has a name, it appears in three places:
+
+- **Input border** — session name shown in the input area border
+- **Terminal title** — updated via ANSI escape sequences
+- **StatusBar** — displayed alongside activity, model, and context usage
 
 ## Slash Commands
 
-| Command        | Description                     |
-| -------------- | ------------------------------- |
-| `/help`        | Show help                       |
-| `/clear`       | Clear conversation history      |
-| `/mode [mode]` | Show or change permission mode  |
-| `/resume`      | List and resume a saved session |
-| `/cost`        | Show token usage                |
-| `/model`       | Show current model              |
-| `/exit`        | Exit CLI                        |
+Typing `/` in the TUI opens an autocomplete popup. Arrow keys navigate, Tab inserts without executing, Enter executes. Subcommands (e.g., `/provider list`) show a nested submenu.
+
+### Session & Context
+
+| Command                   | Description                                                            |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `/clear`                  | Clear conversation history                                             |
+| `/compact [instructions]` | Compress context window                                                |
+| `/context`                | Context window details, reference inventory, and auto-compact controls |
+| `/cost`                   | Show session token usage and cost                                      |
+| `/resume`                 | List recent sessions and resume one                                    |
+| `/rename <name>`          | Rename the current session                                             |
+| `/rewind`                 | List, inspect, restore, or rollback edit checkpoints                   |
+
+### Providers & Settings
+
+| Command                  | Description                                                          |
+| ------------------------ | -------------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| `/provider [subcommand]` | Manage provider profiles: `list`, `switch`, `add`, `test`, `current` |
+| `/mode [mode]`           | Show or switch permission mode                                       |
+| `/permissions [mode]`    | Show permission rules or change permission mode                      |
+| `/settings`              | Open transport settings (enable/disable transports)                  |
+| `/language [lang]`       | Set response language (ko, en, ja, zh), saves and restarts           |
+| `/statusline [on         | off                                                                  | reset]` | Configure status-line fields (model, context, git) |
+
+### Tools & Memory
+
+| Command                | Description                                    |
+| ---------------------- | ---------------------------------------------- |
+| `/memory [subcommand]` | Inspect, add, or review project memory entries |
+| `/background`          | List and control background tasks              |
+| `/agent`               | Run and manage background subagent jobs        |
+| `/skills [name]`       | List registered skills or activate one by name |
+| `/plugin [subcommand]` | Plugin management                              |
+
+### Utility
+
+| Command  | Description                                        |
+| -------- | -------------------------------------------------- |
+| `/help`  | Show available commands                            |
+| `/reset` | Delete user settings and return to first-run state |
+| `/exit`  | Exit CLI                                           |
+
+Skill commands discovered from `.agents/skills/` and `.claude/commands/` appear alongside built-in commands.
+
+## Plugin Management
+
+The `/plugin` command opens an interactive TUI or runs plugin operations through the injected plugin command module:
+
+| Subcommand                               | Description                           |
+| ---------------------------------------- | ------------------------------------- |
+| `/plugin` or `/plugin manage`            | Open the plugin manager TUI           |
+| `/plugin install <name>@<marketplace>`   | Install a plugin from a marketplace   |
+| `/plugin uninstall <name>@<marketplace>` | Remove an installed plugin            |
+| `/plugin enable <name>@<marketplace>`    | Enable a disabled plugin              |
+| `/plugin disable <name>@<marketplace>`   | Disable a plugin without uninstalling |
+| `/plugin marketplace add <source>`       | Add a marketplace source              |
+| `/plugin marketplace remove <name>`      | Remove a marketplace source           |
+| `/plugin marketplace update <name>`      | Update a marketplace source           |
+| `/plugin marketplace list`               | List configured marketplace sources   |
 
 ## Configuration
 
-Settings are loaded from (highest priority first):
+Settings are merged in this order, from lowest to highest priority:
 
-1. `.robota/settings.local.json` (local, gitignored)
-2. `.robota/settings.json` (project, shared)
-3. `~/.robota/settings.json` (user global)
+1. `~/.robota/settings.json` (user global)
+2. `~/.claude/settings.json` (user global, Claude Code compatible)
+3. `.robota/settings.json` (project, shared)
+4. `.robota/settings.local.json` (local, gitignored)
+5. `.claude/settings.json` (project, Claude Code compatible)
+6. `.claude/settings.local.json` (local, gitignored, Claude Code compatible)
 
 ```json
 {
   "defaultMode": "default",
-  "provider": {
-    "name": "anthropic",
-    "model": "claude-sonnet-4-6",
-    "apiKey": "$ENV:ANTHROPIC_API_KEY"
+  "language": "en",
+  "currentProvider": "qwen-plus",
+  "providers": {
+    "qwen-plus": {
+      "type": "qwen",
+      "model": "qwen-plus",
+      "apiKey": "$ENV:DASHSCOPE_API_KEY",
+      "baseURL": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+    },
+    "supergemma4-26b-uncensored-v2": {
+      "type": "gemma",
+      "model": "supergemma4-26b-uncensored-v2",
+      "apiKey": "lm-studio",
+      "baseURL": "http://localhost:1234/v1"
+    },
+    "gpt-4o": {
+      "type": "openai",
+      "model": "gpt-4o",
+      "apiKey": "$ENV:OPENAI_API_KEY"
+    },
+    "claude-sonnet-4-6": {
+      "type": "anthropic",
+      "model": "claude-sonnet-4-6",
+      "apiKey": "$ENV:ANTHROPIC_API_KEY"
+    }
   },
   "permissions": {
     "allow": ["Bash(pnpm *)"],
@@ -203,13 +452,27 @@ Settings are loaded from (highest priority first):
 }
 ```
 
-### Environment Variables
+`currentProvider` selects a profile key from `providers`. The key is the stable profile identity, not
+the provider type; multiple profile keys may use the same provider type and model when they represent
+different credentials, endpoints, accounts, or operational defaults. Qwen Model Studio profiles use
+`type: "qwen"` with a DashScope-compatible `baseURL`; the API key is usually stored as
+`$ENV:DASHSCOPE_API_KEY`. DeepSeek profiles use `type: "deepseek"` with
+`https://api.deepseek.com` and `$ENV:DEEPSEEK_API_KEY`. Gemma-family LM Studio models use
+`type: "gemma"` so Robota can apply Gemma-specific channel-marker projection while still talking to
+the OpenAI-compatible `/v1/chat/completions` API through `baseURL`. Generic OpenAI-compatible profiles use
+`type: "openai"` and do not apply provider-specific projection. Use `--provider <profile>` for a
+one-shot invocation override; add `--set-current` only when the selected profile should become the
+persisted default. The legacy single-provider shape remains supported:
 
-| Variable            | Description       | Required |
-| ------------------- | ----------------- | -------- |
-| `ANTHROPIC_API_KEY` | Anthropic API key | Yes      |
-
-Copy `.env.example` to `.env` and set your key. The CLI reads `.env` automatically in dev mode.
+```json
+{
+  "provider": {
+    "name": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "apiKey": "$ENV:ANTHROPIC_API_KEY"
+  }
+}
+```
 
 ## Context Discovery
 
@@ -219,36 +482,73 @@ The CLI automatically discovers and loads:
 - **CLAUDE.md** — same walk-up discovery
 - **Project metadata** — from `package.json`, `tsconfig.json`
 
-All context is assembled into the system prompt for the AI assistant.
+All context is assembled into the system prompt.
+
+Ordinary prompts may also reference workspace-local files with path-like `@file` tokens, for
+example `@AGENTS.md` or `@docs/SPEC.md`. The CLI passes those prompts through unchanged; the SDK
+resolves bounded file content under the active `cwd`, sends the enriched prompt to the model, and
+records a structured file-reference event in the session history.
+
+## Memory Management
+
+- **Message windowing** — React state keeps the most recent 100 messages. Older messages are dropped from the render tree; full history remains in the session store.
+- **Tool state cleanup** — Completed tool execution states are trimmed to the most recent 50 entries.
+- **React.memo** — `MessageItem` uses `React.memo` to skip redundant re-renders.
+
+## Session Logging
+
+Session logs are written to `.robota/logs/{sessionId}.jsonl` in JSONL format by default, capturing structured events for diagnostics and replay. Background task lifecycle/progress events are logged there as they happen. Child-process subagents also write append-only transcripts to `.robota/logs/{sessionId}/subagents/{agentId}.jsonl`, including streaming text deltas while the local provider request is still running.
+
+Resumable session JSON is written to `.robota/sessions/{sessionId}.json` for the current project and includes messages, UI history, the exact system prompt, registered tool schemas, and background task snapshots. High-frequency streaming chunks stay in JSONL transcript files; the session JSON stores task state and transcript paths.
 
 ## Architecture
 
+The CLI is a pure TUI layer. All business logic lives in `@robota-sdk/agent-framework`'s `InteractiveSession`. `useInteractiveSession` is the sole React↔SDK bridge, converting SDK events to React state.
+
 ```
-bin.ts → cli.ts (parseArgs, load config/context, create Session)
-                ├── config/config-loader.ts    — settings file discovery + Zod validation
-                ├── context/context-loader.ts  — AGENTS.md/CLAUDE.md walk-up discovery
-                ├── context/project-detector.ts — package.json/tsconfig detection
-                ├── context/system-prompt-builder.ts — system message assembly
-                ├── session.ts                 — Robota agent wrapper + permission enforcement
-                │   └── permissions/
-                │       ├── permission-gate.ts   — 3-step evaluation (deny → allow → mode)
-                │       ├── permission-mode.ts   — mode × tool policy matrix
-                │       └── permission-prompt.ts — interactive [y/N] prompt
-                ├── tools/                     — 6 built-in tools (Bash, Read, Write, Edit, Glob, Grep)
-                ├── session-store.ts           — JSON file-based session persistence
-                └── ui/                        — Ink TUI components (App, MessageList, InputArea, etc.)
+bin.ts → cli.ts (arg parsing)
+              └── ui/render.tsx → App.tsx (thin JSX shell)
+                    ├── useInteractiveSession  (ONLY React↔SDK bridge)
+                    │   ├── InteractiveSession (SDK)
+                    │   ├── CommandRegistry    (SDK, re-exported by CLI)
+                    │   │   ├── BuiltinCommandSource  (SDK, empty by default)
+                    │   │   ├── agent-command-skills  (/skills command + virtual skill aliases)
+                    │   │   ├── PluginCommandSource   (SDK, plugin skills)
+                    │   │   └── ICommandModule sources (/help, /compact, ...)
+                    │   └── SystemCommandExecutor (SDK)
+                    ├── plugin-hooks-merger.ts (merges plugin hooks into SDK config)
+                    ├── MessageList.tsx
+                    ├── InputArea.tsx          (CjkTextInput, bracketed paste, slash detection)
+                    ├── StatusBar.tsx          (activity, conditional mode, model, context %)
+                    ├── PermissionPrompt.tsx   (arrow-key Allow/Deny)
+                    ├── SlashAutocomplete.tsx  (command popup with scroll)
+                    ├── DiffBlock.tsx          (Edit tool diff display)
+                    ├── MenuSelect.tsx         (arrow-key menu, Plugin TUI)
+                    ├── PluginTUI.tsx          (plugin management screen stack)
+                    ├── TextPrompt.tsx         (text input for Plugin TUI)
+                    └── ConfirmPrompt.tsx      (reusable yes/no prompt)
 ```
 
-Tool calls flow through the permission system:
+## Dependencies
 
-```
-AI agent requests tool call
-  → Session.wrapToolWithPermission() intercepts execute()
-    → evaluatePermission(toolName, args, mode, allow/deny lists)
-      → deny list match? → blocked
-      → allow list match? → auto-approved
-      → mode policy lookup → auto | approve | deny
-    → if 'approve': promptForApproval() → user types y/N
-    → if allowed: original tool.execute() runs
-    → if denied: returns error result to AI agent
-```
+| Package                                | Purpose                                    |
+| -------------------------------------- | ------------------------------------------ |
+| `@robota-sdk/agent-framework`          | Session factory, query, config, context    |
+| `@robota-sdk/agent-core`               | Types (TPermissionMode, TToolArgs)         |
+| `@robota-sdk/agent-transport-headless` | Headless runner for print mode (`-p`)      |
+| `ink` 7, `react` 19.2+                 | TUI rendering                              |
+| `ink-select-input`                     | Arrow-key selection (permission prompt)    |
+| `ink-spinner`                          | Loading spinner                            |
+| `chalk`                                | Terminal colors                            |
+| `ink-text-input`                       | Base text input (extended by CjkTextInput) |
+| `marked`, `marked-terminal`            | Markdown parsing and terminal rendering    |
+| `cli-highlight`                        | Syntax highlighting for code blocks        |
+| `string-width`                         | Unicode-aware string width (CJK support)   |
+
+## Documentation
+
+See [docs/SPEC.md](./docs/SPEC.md) for the full specification, architecture details, and design decisions.
+
+## License
+
+MIT