feat: 文档站英文版（10篇译文 content/en/）+ docs 页多语言机制 + Try Astrion 指向线上实例

2026-09-04 02:57:04 +08:00 · 2026-09-04 02:57:04 +08:00 · d3b9bdbfe1
commit d3b9bdbfe1
parent aba1aae262
24 changed files with 2249 additions and 31 deletions
--- a/content/en/01-quick-start.md
+++ b/content/en/01-quick-start.md
@ -0,0 +1,241 @@
 # Quick Start
 This chapter walks you through running Astrion from scratch: cloning the code, completing the initial configuration, starting the service, and choosing the right runtime shape for your use case.
 ---
 ## 1. System Requirements
 | Dependency | Requirement | Notes |
 |------|------|------|
 | Python | 3.9+ (3.11 recommended) | Backend runtime |
 | Node.js | 18+ | Building the frontend, using the CLI |
 | Docker | Optional | Required only for **web/docker mode**; not needed for host mode |
 | WSL2 | Windows only | Prerequisite for using the host sandbox on Windows |
 Astrion runs on macOS, Linux, and Windows (WSL2). For the differences in sandbox capabilities across the three platforms, see the "Core Concepts" chapter.
 ---
 ## 2. Installation
 ```bash
 # 1. Clone the repository
 git clone https://github.com/JOJO6618/astrion.git
 cd astrion
 # 2. Initialize: create a venv, install dependencies, and run the interactive setup wizard
 #    The wizard asks, in order: work mode → listen address/port → admin account → model API → generate secret keys
 ./setup.sh
 # 3. Build the frontend
 npm install && npm run build
 # 4. (web/docker mode only) Build the sandbox image; see "Choosing a work mode" below
 docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .
 # 5. Start
 ./start.sh
 # Or start manually:
 python -m server.app --port 8091 --thinking-mode
 ```
 After startup, visit `http://localhost:8091` and log in with the admin account you set up in the wizard.
 > The `setup.sh` wizard writes the configuration to `.env` at the repository root. This is a development fallback; for production deployments we recommend using the `settings.json` under the data root or system environment variables instead. See "Configuration priority" below.
 ---
 ## 3. Port and Listen Address
 - **Default port: `8091`** (`WEB_SERVER_PORT`).
 - Listen address (`WEB_SERVER_HOST`):
  - Single-machine personal use: `127.0.0.1` is recommended — listens only on the local loopback, unreachable from the LAN;
  - Multi-user / server deployment: use `0.0.0.0`.
 - The `--port` CLI argument can temporarily override the configuration.
 - Debug mode `WEB_SERVER_DEBUG=1` (also enables the Flask reloader); keep it at `0` in production.
 ---
 ## 4. Data Paths: Where Data Lives and How to Move It
 Astrion's runtime data (conversation records, users, logs, deployment-level config) is **by default stored entirely under your home directory and never pollutes the source tree**:
 ```
 ~/.astrion/astrion/           ← data root (data_root)
 ├── settings.json             ← single configuration file (highest priority)
 ├── config/                   ← deployment-level config (model libraries, etc., shared by host/web)
 ├── host/                     ← host mode data
 │   ├── data/  users/  logs/  api/
 └── web/                      ← web/docker mode data (same structure above)
 ```
 Data is routed automatically by work mode: when `TERMINAL_SANDBOX_MODE=host`, data goes into `host/`; otherwise it goes into `web/`.
 ### Path-Related Environment Variables (priority from high to low)
 | Environment variable | Purpose |
 |----------|------|
 | `DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR` | Override a single directory individually (highest priority) |
 | `ASTRION_DATA_ROOT` | Move the entire data root (default `~/.astrion/astrion`) |
 | `DEPLOY_CONFIG_DIR` | Move just the deployment-level config directory (default `<data root>/config/`) |
 Individual directory variables accept relative paths (resolved relative to the repository root), absolute paths, and `~`.
 ### Configuration priority
 Effective order for same-name configuration: **`<data root>/settings.json` > system environment variables > `.env` at the repository root > code defaults**.
 `.env` does not override existing system environment variables when loaded; `settings.json` is the recommended way to configure production, for example:
 ```json
 {
  "server": { "port": 8091, "host": "127.0.0.1" }
 }
 ```
 ---
 ## 5. Configuring the Main Agent Model
 The main agent's models are registered centrally in **`custom_models.json`**.
 **Placement** (looked up by fallback chain; first hit wins):
 1. `<data root>/config/custom_models.json` (recommended for production)
 2. `config/custom_models.json` inside the repository
 3. `config/custom_models.json.example` inside the repository (seed example)
 **Full field reference**:
 ```json
 {
  "models": [
    {
      "model_name": "Kimi-K3",
      "description": "Model description shown to users",
      "visible": true,
      "url": "${API_BASE_KIMI}",
      "apikey": "${API_KEY_KIMI}",
      "multimodal": "image,video",
      "reasoning_capability": "fast,thinking",
      "reasoning_effort": true,
      "context_window": 1048576,
      "max_output_tokens": 64000,
      "thinkmode_status": {
        "type": "param_toggle",
        "model_id": "k3",
        "fast_extra_parameter":     { "thinking": { "type": "disabled" } },
        "thinking_extra_parameter": { "thinking": { "effort": "max" } }
      },
      "extra_parameter": {},
      "model_description": "Model self-description injected into the system prompt"
    }
  ]
 }
 ```
 | Field | Required | Description |
 |------|------|------|
 | `model_name` | ✅ | Model entry name; shown in the UI and used as the key that other config references |
 | `url` | ✅ | Base API address. **Supports `${environment variable}` references**; don't write secret keys in plain text |
 | `apikey` | ✅ | API key, also supports `${...}` |
 | `description` | | Description text shown in the list |
 | `visible` | | Whether it is visible in the model selection menu |
 | `multimodal` | | `image,video`, etc.; determines whether the input bar allows sending images/videos |
 | `reasoning_capability` | | `fast,thinking`; determines the available thinking mode options |
 | `reasoning_effort` | | Whether the "reasoning effort" slider is supported |
 | `context_window` | | Context window size (tokens); the baseline for compression thresholds and usage statistics |
 | `max_output_tokens` | | Maximum output tokens per response |
 | `thinkmode_status` | | `param_toggle` type: `model_id` is the real model ID; `fast/thinking_extra_parameter` are the extra request parameters attached in each of the two modes respectively |
 | `extra_parameter` | | Extra parameters attached to every request |
 | `model_description` | | Self-description injected into the system prompt |
 **Minimum config** needs only 4 fields: `model_name` / `url` / `apikey` / `thinkmode_status.model_id`; all other fields have defaults.
 > Note: the model entry created by the `setup.sh` wizard in step 5 is exactly the minimum config — `multimodal` is `none` (cannot send images/videos), `context_window` is fixed at 128000, and `max_output_tokens` is 32768. If your model supports multimodality or a larger context, edit `<data root>/config/custom_models.json` manually after running the wizard to fill in the fields.
 **Default model**: when `AGENT_DEFAULT_MODEL` is not set, the first visible model in the list is used; you can also set a per-user default model in the "Models & Thinking" page in Personal Space.
 > Note: the legacy `AGENT_API_*` / `AGENT_THINKING_*` / `AGENT_TITLE_*` environment variables have been removed from the code; configuring them no longer has any effect.
 ---
 ## 6. Configuring Sub Agent Models
 Sub agents (including the three review agents) use a **separate model library**: `sub_agent_models.json`.
 **Placement**: it is read only from the deployment config directory — `<data root>/config/sub_agent_models.json` (can be overridden individually with `SUB_AGENT_MODELS_CONFIG_FILE`). **Without this file, sub agents will fail to start** and report "no usable sub agent model configuration found".
 **Structure**:
 ```json
 {
  "default_model": "deepseek-v4-flash",
  "models": [
    {
      "name": "deepseek-v4-flash",
      "url": "${SUB_AGENT_API_BASE}",
      "apikey": "${SUB_AGENT_API_KEY}",
      "model_id": "deepseek-v4-flash",
      "modes": "fast,thinking",
      "multimodal": "image",
      "max_output": 32000,
      "max_context": 128000,
      "extra_parameter": {},
      "fast_extra_parameter": {},
      "thinking_extra_parameter": {}
    }
  ]
 }
 ```
 Key points:
 - `default_model`: the default entry name; used when `model` is left empty in sub agent / review agent config. If the specified name does not exist, it falls back to the first available entry in the list.
 - Field names are loosely compatible: `name`/`model_name`/`model`, `url`/`base_url`, and `apikey`/`api_key` all work; `modes` set to `fast,thinking` means thinking mode is supported, while just `fast` means fast-only mode.
 - The same `thinkmode_status` structure as the main model library is also supported; you can copy an entry from `custom_models.json`, rename it, and use it directly.
 - `url` / `apikey` also support `${environment variable}` references.
 **Sub agent environment variables**:
 | Variable | Default | Description |
 |------|------|------|
 | `SUB_AGENT_MAX_ACTIVE` | 5 | Maximum number of simultaneously running sub agents |
 | `SUB_AGENT_DEFAULT_TIMEOUT` | 180 (seconds) | Default timeout |
 | `SUB_AGENT_TASKS_BASE_DIR` | `<data root>/<mode>/data/sub_agent_tasks` | Task directory |
 | `SUB_AGENT_PROJECT_RESULTS_DIR` | `<workspace>/sub_agent_results` | Delivery directory (intentionally placed inside the workspace) |
 ---
 ## 7. Choosing a Work Mode: host or docker (web)
 Determined by `TERMINAL_SANDBOX_MODE`; the two modes target completely different scenarios:
 | | **host mode** | **web/docker mode** |
 |---|---|---|
 | Positioning | Local personal use | Multi-user server deployment |
 | Command execution | Host OS sandbox (macOS sandbox-exec / Linux bwrap / Windows WSL2) | Per-user isolated Docker container, executed as a non-privileged uid under restricted permissions |
 | Data directory | `~/.astrion/astrion/host/` | `~/.astrion/astrion/web/` |
 | Prerequisites | No image needed; Windows requires WSL2 first | Must build the image first: `docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .` (the build context must be the repository root) |
 | Image name | — | Specified by `TERMINAL_SANDBOX_IMAGE`; `my-agent-shell:latest` is recommended |
 Recommendations:
 - **Using it alone on your own computer** → `host`. The file manager and local toolchain work directly; the best experience.
 - **Deploying to a server for multiple users** → `docker`. Containers naturally isolate files and processes between users.
 - host mode can also read web mode data (user list, merged workspace display); the reverse is not possible.
 The sandbox image is based on `python:3.11-slim` and ships with a common toolchain: LibreOffice / Pandoc / FFmpeg / Tesseract OCR (with Chinese) / Chromium / Node 20 / docx / pptxgenjs, etc. **The program does not build the image automatically**; you must build it manually once before starting web mode.
 ---
 ## 8. First-Start Checklist
 1. Open `http://localhost:8091` in a browser and log in with the admin account;
 2. Go to Personal Space and confirm the "Models & Thinking" page shows the models you configured;
 3. Send a message and confirm the main agent replies normally;
 4. Have the main agent create a sub agent (or trigger one by saying "help me look up xxx"), and confirm `sub_agent_models.json` is configured correctly;
 5. For web mode, confirm the image has been built and the terminal container starts properly.
 At this point, your Astrion is up and running. Next, we recommend reading "Core Concepts" to understand four sets of concepts — deployment modes, permission modes, execution environments, and work modes — which define the boundaries of Astrion's behavior.
--- a/content/en/02-core-concepts.md
+++ b/content/en/02-core-concepts.md
@ -0,0 +1,111 @@
 # Core Concepts
 Astrion is built on four sets of **mutually orthogonal** concepts. Understanding them is the key to understanding the entire system: any combination of them determines what a task "can do, where it runs, and to what extent".
 | Concept group | Values | Determines | Where to switch |
 |--------|------|----------|------------|
 | **Deployment mode** | host / docker(web) | Where data is stored, and whether commands run on the host or in a container | Environment variable (set at deploy time) |
 | **Permission mode** | readonly / approval / auto_approval / unrestricted | Whether AI tool calls require approval | Permission menu in the input bar (per conversation) |
 | **Execution environment** | sandbox / direct | Whether commands go through the OS sandbox | Permission menu in the input bar (per conversation, host mode only) |
 | **Work mode** | plan / ask / execute | The pace of AI's interaction with you: plan first or act directly | Work mode switcher in the input bar (per conversation) |
 ---
 ## 1. Deployment Mode: Host vs Docker (Web)
 Deployment mode is determined **before startup** by the environment variable `TERMINAL_SANDBOX_MODE` and cannot be switched at runtime.
 - **Host mode**: designed for local personal use. Commands run through the host OS sandbox, and the AI can directly operate on the local directories you have authorized (such as a real project repository). The file manager and local Node/Python toolchains are directly available.
 - **Docker mode (web mode)**: designed for multi-user server deployment. Each user's terminal commands run in an independent Docker container, and files and processes are naturally isolated between users. You need to build the sandbox image first (see "Quick Start").
 The two modes keep completely separate data directories (`~/.astrion/astrion/host/` and `web/`), but host mode **merges and reads** the user and workspace lists from web mode — so historical data from both modes on the same machine is visible.
 > Note: Docker mode also enforces read-only — under restricted permission levels (readonly/approval/auto_approval), commands run inside the container as a non-privileged user (uid 10001), and writes are directly rejected by kernel file permissions. The two-stage "read-only → approval → single writable retry" flow is identical to host mode (see "Execution & Security" for details).
 ## 2. Permission Mode: What the AI Can Do
 Permission mode is a **product-level** switch that determines whether tool calls are intercepted and whether approval is required. It is switched per conversation and can be changed at any time.
 ### Read-only
 - `run_command` is allowed, but runs in a **read-only sandbox**; once the command attempts a write, the operating system directly returns a permission denial (e.g., `Operation not permitted`).
 - Write tools such as `write_file` / `edit_file` are **directly rejected**.
 - Use cases: when you want the AI to only do code review, read-only analysis, or answer questions.
 ### Approval (default)
 - `run_command` follows a **two-stage** flow: first it runs in a read-only sandbox → if a permission denial occurs, an approval request is raised to the frontend → after you approve, **only that command** is retried once in a writable sandbox.
 - The tool returns the final result after the retry; the AI never sees the intermediate denial process.
 - If approval is denied or times out: the command is not executed and nothing is written.
 ### Auto-approval
 - The same "read-only first" flow as approval, except the approver is an **auto-approval agent** (an independent AI whose model and parameters can be configured in Personal Space).
 - `write_file` / `edit_file`: targets inside the workspace execute directly; targets outside the workspace go through auto-approval.
 - When auto-approval is denied, the AI receives a "denied + reason" and continues trying other paths without interrupting the whole round of tasks.
 - You can take over manually at any time: approve / deny / switch to Unrestricted.
 ### Unrestricted
 - The permission layer performs no interception; tools execute directly.
 - At this point the security boundary is entirely determined by the execution environment (see the next section): under sandbox the OS sandbox still provides a safety net, while under direct it is equivalent to running bare.
 ## 3. Execution Environment: Sandbox vs Direct
 The execution environment is a **system-level** switch (switchable in host mode only) that determines whether commands ultimately pass through the OS sandbox:
 - **sandbox (default)**: commands run inside the OS sandbox, and the read/write boundary is limited by "path authorization". When the sandbox is unavailable, critical execution paths are **refused to run** rather than silently falling back to the bare host.
 - **direct (high risk)**: commands run directly on the host with no sandbox restrictions. It is selectable only under the `unrestricted` permission — restricted levels (readonly/approval/auto_approval) and direct are strictly mutually exclusive: switching to direct under a restricted level is rejected, and switching from direct into a restricted level is automatically pushed back to sandbox. It is only recommended to enable it **temporarily** when system-level privileges are clearly needed, and to switch back immediately after use. Once switched, it stays in effect — there is no automatic fallback mechanism.
 ### Sandbox Implementation and Security Level by Platform (Please Read)
 | Platform | Implementation | Security level |
 |------|------|----------|
 | **Windows** | WSL2 | **Full data isolation is achievable** — commands run in an independent WSL2 filesystem. Prerequisite: **install WSL2 yourself first**; the sandbox is unavailable without it |
 | **macOS** | sandbox-exec | **Whitelist-based read model; both reads and writes can be restricted** — by default a process can only read system directories, the workspace, and authorized paths; out-of-bounds reads are directly denied. Inherent cost: file names at the top level of an authorized path's ancestor directories can be listed (file contents remain unreadable) |
 | **Linux** | bubblewrap (bwrap) + seccomp | Writes can be restricted (read-only level is globally read-only), but **reads are still globally readable** and not yet aligned with a whitelist; it has not been tested in practice, so relying on its isolation in production is not recommended |
 This is the official, candid statement of current security capabilities: as a way to **prevent accidental mistakes**, the sandbox is reliable on all three platforms; as a way to **prevent malicious data theft**, macOS (whitelist) and Windows (WSL2) can be trusted, while Linux cannot — for now.
 ### Path Authorization
 In host mode, the sandbox's file access boundary is determined by path authorization, which has two categories:
 - **Read-write paths**: the AI can read and modify them;
 - **Read-only paths**: the AI can view but not modify them.
 Relationship: `readable set = read-write + read-only`; `writable set = read-write`. Maintained in the input bar `+` menu → "Path Authorization". It is recommended to keep authorization minimal: workspace + temporary directory.
 > The read/write identity of a terminal session (terminal family of tools) is **pinned at startup** according to the permission level, execution environment, and sandbox policy at that time: under a restricted level the terminal runs as read-only, and only under `unrestricted` does it run as writable. **Switching the execution environment (sandbox ⇄ direct), toggling the permission level between a restricted level and Unrestricted, or switching the workspace or container closes existing terminal sessions immediately**, after which subsequent operations run in freshly spawned sessions under the new policy.
 ### Network Permissions
 A separate set of switches independent of the file sandbox (also adjustable in Plan mode):
 - **Restricted** (default): only local loopback access is allowed; external networks are unreachable;
 - **Fully open**: all outbound/inbound connections are allowed.
 ## 4. Work Mode: The Pace of AI's Interaction with You
 Work mode controls **when the AI acts and when it asks you first**, and is fully orthogonal to permissions. It can only be switched while idle (switching during a running task returns a 409 notice).
 - **Plan**: the AI only drafts a plan and discusses it with you, without actually changing anything. In this mode, permissions are **locked to read-only** and the execution environment is **locked to sandbox** (enforced on both the UI-disabled side and the backend, except for network permissions). The only exception is writing plan documents under `.astrion/plan/*.md`. Once the plan is written, the AI calls `submit_plan` to ask for your approval; **approving automatically switches to Execute** and restores your previous permission settings.
 - **Ask**: discuss first, then start working. The AI writes its approach and questions in replies and confirms them back and forth with you, acting only after key details are settled. At the execution level there is no difference from Execute — only the pace of interaction differs.
 - **Execute**: the AI works out the plan and fills in details on its own, and starts working directly, asking questions only when it hits a hard blocker (missing information, account credentials required, etc.).
 ### Common Combinations
 | Scenario | Recommended combination |
 |------|----------|
 | Have the AI modify an important project you are maintaining | plan + approval + sandbox |
 | Everyday casual use that prioritizes efficiency | execute + auto_approval + sandbox |
 | Pure Q&A / code review; files must never be touched | any mode + readonly (execution environment automatically locks to sandbox) |
 | Multi-user server deployment | Docker mode (the execution environment concept does not apply) |
 ## 5. Quick Reference: Interaction Rules Between the Four Concept Groups
 1. Plan mode → permissions are forced to readonly, execution environment is forced to sandbox (network permissions remain adjustable);
 2. Restricted permission levels (readonly/approval/auto_approval) → execution environment is automatically locked to sandbox; direct is only available under unrestricted;
 3. Approving a plan → automatically switches to execute and restores the permission and execution environment from before entering plan;
 4. In Docker mode there is no sandbox/direct distinction — the container is the boundary;
 5. Permission mode, execution environment, and work mode are all **per-conversation** state: a new conversation inherits the current input bar values, and the "default permission mode / default work mode" in Personal Space only affects the first construction.
--- a/content/en/03-conversations.md
+++ b/content/en/03-conversations.md
@ -0,0 +1,76 @@
 # Conversations
 This chapter covers the capabilities of "a single conversation" itself: conversation types, thinking mode, goal mode, and the panel features available during a conversation.
 ---
 ## 1. Conversation Types: Regular vs Multi-Agent
 Chosen when creating a conversation and **immutable after creation**:
 - **Regular conversation (agent)**: you converse with one main agent, which can spawn sub agents in the background as needed to get work done.
 - **Multi-agent conversation**: the main agent is fixed as a **Team Leader**, which does not do the work itself but instead creates multiple role-based sub agents (such as Full-Stack Engineer, UI Operator), assigning tasks among them, collecting reports, and making decisions. Sub agents can also communicate with each other, but every exchange is reported to the Team Leader in sync — there is no "backchannel collusion".
 Where to switch: the conversation type selector to the right of `+` on the bottom row of the input bar when the conversation is empty; the sidebar's list filter determines which type of conversations you see in the list.
 For the full multi-agent playbook, see the "Agent Capabilities" chapter.
 ## 2. Thinking Mode and Reasoning Effort
 Two independent switches, both scoped to the current conversation:
 - **Thinking mode**: `fast` / `thinking`. Fast mode prioritizes response speed and skips the reasoning process; Thinking mode uses a reasoning model for the whole conversation. Switchable in the input bar; a default can be set in Personal Space.
 - **Reasoning effort**: a `Default / Low / Medium / High` slider (only appears when `reasoning_effort: true` is set in the model configuration). "Default" means no intensity is specified and the API's own default behavior is used; dragging the slider adjusts the reasoning depth level in real time.
 > A model's multimodal capability (whether it can send images/videos) is determined by the `multimodal` field of that model in `custom_models.json`; the available thinking mode options are determined by `reasoning_capability`.
 ## 3. Goal Mode (Beta)
 > ⚠️ Goal Mode is a **beta feature**: the mechanics are fully usable, but edge cases (token accounting during concurrent conversations, recovery from abnormal interruptions, etc.) are still being polished. Please use it with these expectations in mind and report any issues.
 In a regular conversation, the AI stops after completing the one round of tasks you assigned. **Goal Mode** makes the AI **keep working round after round automatically** toward a long-term goal, until the goal is achieved or the limit is hit.
 **How to use**:
 1. In the input bar `+` menu → "Goal Mode", entering the "ready" state;
 2. Your next message is treated as a **goal** (rather than a regular task);
 3. The AI works continuously toward the goal: after each round it self-evaluates "is the goal achieved?", and if not, it proceeds to the next round;
 4. It stops when the goal is achieved, a limit is hit, or you cancel manually.
 **Stopping conditions** (configurable in Personal Space, multiple selectable):
 - `max_turns`: at most N automatic additional rounds (has a default value, adjustable);
 - `max_tokens`: cumulative (input + output) token cap, disabled by default. Note that this figure is **workspace-level** and approximate when multiple conversations run concurrently.
 **Goal review**: an optional goal-review agent (the `goal_review` entry on the "Review Agents" page in Personal Space) with two review modes:
 - `readonly` (default): the review agent reads the conversation content only to judge goal progress;
 - `active`: it is allowed to run read-only commands for evidence (for example, checking whether a file was actually generated) before drawing conclusions.
 Goal state is persisted independently per conversation (`goal_states/<conversation ID>.json`); switching conversations, compressing context, or restarting the service never loses goal progress.
 ## 4. Conversation Panels: Recap / Usage / Live Terminal
 Three panel-style features in the input bar `+` menu (they are information panels only and **unrelated to the security mechanisms**):
 - **Conversation recap**: opens a recap view of the current conversation, letting you review what was done in this conversation along a timeline.
 - **Usage stats**: a context and token usage panel showing the current conversation's context occupancy and cumulative consumption.
 - **Live terminal**: opens a live terminal panel where you can directly watch the terminal session the AI is currently executing — which command it is running and what the output is. This is an observation window, not a security boundary; for real security controls, see the "Execution & Security" chapter.
 ## 5. Conversation Management
 - **Search**: the search box at the top of the sidebar retrieves conversations by title and content.
 - **Flat / Grouped views**: the sidebar can lay out all conversations flat, or group them by workspace (Personal Space → "Appearance & Display" → sidebar grouping). In grouped mode, workspaces can be pinned and sorted.
 - **Type filter**: the type switcher in the sidebar (Regular / Multi-agent) determines which type of conversations appear in the list.
 - **New conversation button behavior**: configurable in Personal Space — clicking `+` either "navigates to a blank new conversation page" (route) or "immediately creates an empty conversation" (blank).
 - **Auto title**: enabled by default; a title is generated automatically after the first round. Can be disabled in Personal Space.
 ## 6. Conversation Display Modes
 Personal Space → "Appearance & Display" provides three message-stream display modes:
 - **Traditional list**: all messages laid out flat;
 - **Stacked animation**: intermediate blocks such as tool calls are stacked and collapsed, keeping the main thread of the conversation cleaner;
 - **Minimal mode** (default): the most restrained display, showing only the essentials.
 There are also "Full info / Condensed info" controls for how much condensed messages expand, as well as display switches such as the assistant's status avatar (give it a poke for an easter egg).
--- a/content/en/04-input-context.md
+++ b/content/en/04-input-context.md
@ -0,0 +1,89 @@
 # Input & Context
 This chapter covers the two menus in the input bar, file references, uploads, and Astrion's context management system—including the correct use of compression mechanisms.
 ---
 ## 1. `+` Quick Menu (Full Feature List)
 Click `+` on the left side of the input bar to open it. Here's the full list of features:
 | Feature | Description |
 |------|------|
 | New conversation | Start a new conversation (equivalent to `new` / `clear`) |
 | Upload file | Select a local file to upload into the workspace |
 | Send image / Send video | Attach to the message; **disabled when the current model does not support multimodality** (depends on the `multimodal` config) |
 | Compress conversation | Manually trigger a one-time context compression |
 | Select AgentSkill | Insert a skill reference (equivalent to typing the `//` shortcut) |
 | Workflow | Activate a workflow so the agent progresses through a predefined flow |
 | Conversation type | Switch between "Agent / Multi-agent" on an empty conversation (immutable after creation) |
 | Switch work mode | plan / ask / execute |
 | Switch theme | Classic / Light / Dark |
 | Conversation review | Open the review for the current conversation |
 | Usage statistics | Context and token usage panel |
 | Goal mode | Toggle goal mode (Beta, see the "Conversation" chapter) |
 | Personal settings | Open Personal Space |
 | Live terminal | Open the live terminal panel |
 | Switch model | Choose the model used by this conversation |
 | Thinking mode | Switch between fast / thinking |
 | Permission mode | Switch between readonly / approval / auto / unrestricted |
 | Network permission | Restricted / Fully open (also adjustable in plan mode) |
 | Execution environment | sandbox / direct (host mode only) |
 | Switch workspace / project | Switch the workspace bound to the current conversation |
 | Version control | Turn version control on/off for this conversation |
 | Git status bar | Show/hide the Git status bar above the input bar |
 | Path authorization | View and manage sandbox path authorization |
 | Approval panel | View approval records |
 ## 2. `/` Slash Menu
 Type `/` in the input box to trigger the slash shortcut menu, which lets you quickly filter and jump to a category of options by keyword. It currently supports 12 categories: AgentSkills (`//` shortcut), workflow, theme, permission mode, execution environment, model, thinking mode, network permission, work mode, workspace, conversation type, etc.
 Typical usage: `/skill` to pick a skill, `/workflow` to pick a workflow, `/model` to switch models—faster than browsing the `+` menu.
 ## 3. `@` File References
 Type `@` to bring up the file menu and insert a reference to a file/directory from the workspace. Referenced files are provided to the agent as context, which is ideal for "discuss this file" scenarios. Image file references are handled according to multimodality capabilities.
 ## 4. Context Compression: Shallow vs. Deep
 Every long conversation eventually hits the model's context limit. Astrion provides two levels of automatic compression plus manual compression:
 ### Shallow compression (off by default)
 - Mechanism: replaces earlier **tool call results with placeholders** (keeping the most recent N tool results uncompressed), freeing up space immediately.
 - Trigger: fires by default at 80k accumulated tokens (configurable), with additional fine-tuning parameters such as "every N tool calls", "at most N replacements per round", and "keep tool results from the last N user inputs uncompressed".
 - ⚠️ **Important trade-off: shallow compression modifies the history message content, which breaks the provider-side context cache (prompt cache)**—the requests in the rounds after compression will miss the cache, showing up as slower responses and higher costs. This is why it is off by default.
 ### Deep compression (on by default, recommended)
 - Mechanism: performs a **deep summarization** of the whole history; the old context is wholly replaced by a condensed summary so the conversation continues lightweight.
 - Output form is configurable (`deep_compress_form`): `file`—the summary is written to a file, read back at any time when needed (default); `inject`—the full summary is injected directly into the context.
 - Trigger: 150k tokens by default.
 ### The 80% rule for custom thresholds (follow it)
 If you customize the compression trigger threshold, **set it to at least 80% of the model's actual usable context**.
 For example, if a model's actual context is 128k, the trigger threshold should not be lower than roughly 102k. Setting the threshold too low triggers compression frequently: it wastes tokens, repeatedly breaks the context cache, and makes the AI lose detail memory prematurely. Getting the conversation to "fill the window before compressing" is the most cost-effective use.
 > The model's actual context window is determined by the `context_window` of that model in `custom_models.json`; note the difference between "nominal context" and "actual usable context" (some APIs reserve space for output).
 ### Manual compression
 `+` menu → "Compress conversation" can be triggered manually at any time. It's useful when you anticipate starting a new topic and want to proactively free up space.
 ## 5. Context Injection Features
 These features affect the context automatically carried in every round of conversation; they are all configured in Personal Space:
 - **Recent conversation hints** (off by default): when enabled, a new conversation automatically injects a summary of the most recent N historical conversations into the context (N is configurable, 1–30, default 10). Good for continuous workflows like "I've been working on the same project recently"; combine it with the "conversation continuity" personalization setting.
 - **AGENTS.md auto-injection** (off by default): when enabled, the AGENTS.md in the project root is automatically injected into the context, so the AI always works with the project conventions.
 - **Project memory index injection**: the AI's project memory index is injected at most 20 entries by default (starting at 5, settable to unlimited). Memory content is actively accumulated by the AI during work.
 - **Skill hints** (off by default): dynamically suggests potentially relevant skills based on the current task.
 ## 6. Uploads & Multimodality
 - **Upload file**: goes into the workspace; the AI can read and process it later;
 - **Send image/video**: goes directly into the multimodal context with the message;
 - Image compression tiers (Personal Space): `original / 1080p / 720p / 540p`, default original. When sending many large images in a long conversation, consider a lower tier to save context.
--- a/content/en/05-execution-security.md
+++ b/content/en/05-execution-security.md
@ -0,0 +1,86 @@
 # Execution & Security
 This chapter covers how Astrion executes AI-initiated actions safely: the actual behavior of sandbox execution, path authorization, and the approval mechanism. For the four conceptual switches (deployment / permission / execution environment / work mode), see the "Core Concepts" chapter first; this chapter focuses on concrete behavior and day-to-day management.
 > Scope note: the "live terminal" is just an observation panel and is unrelated to the security mechanisms; see the "Conversation" chapter.
 ---
 ## 1. How Commands Are Executed
 ### run_command: two-phase execution
 Take the default recommended `approval` mode as an example. The actual journey of a shell command initiated by the AI is:
 1. **It executes first with read-only identity**—can read but not write (host mode relies on the OS sandbox; docker mode relies on a non-privileged user inside the container);
 2. If the command does not touch any write operation, the result is returned directly, fully transparent;
 3. If it triggers a permission denial (writing files, modifying the system), **it automatically escalates into an approval request to you**;
 4. After you approve, **only this one command** is retried with writable identity; if you reject it or the request times out, it is not executed at all;
 5. The AI receives only the final result; the intermediate process never disturbs its reasoning.
 `auto_approval` mode replaces the approver in step 3 with an auto-approval agent; `unrestricted` mode skips approval and executes directly; in `readonly` mode, write requests are rejected outright. Note that approval **only escalates this one write—it does not expand the read scope**—the only way to read files outside the workspace is path authorization (see section 2).
 ### Terminal sessions: identity pinned, switching closes them
 The read/write identity of persistent terminal sessions (terminal family of tools) is **pinned** at startup according to the current permission tier, execution environment, and sandbox policy: under restricted tiers (readonly/approval/auto_approval) the terminal runs with read-only identity and writes inside the terminal are denied directly by the system (EPERM); only under `unrestricted` is the identity writable. When you **switch the execution environment (sandbox ⇄ direct), switch the permission tier between restricted and unrestricted, or switch workspace or container**, existing terminal sessions are **closed immediately**—they never keep running with the old identity, and subsequent operations run in a freshly spawned session under the new policy. This also means: don't switch these toggles while running long tasks, because the task terminates together with the session.
 ### Sub agents and background commands
 Sub agent terminal processes also go through the execution environment policy: under sandbox they are launched via the host sandbox; under direct they launch directly on the host; in docker mode they execute inside the container. Background commands (`run_in_background`) go through the same read-only/writable sandbox determination as foreground commands—**going to the background does not bypass permissions**.
 ## 2. Day-to-Day Management of Path Authorization
 Entry point: input bar `+` menu → "Path authorization".
 - **Readable and writable paths**: the AI's full working scope, typically your project directory;
 - **Read-only paths**: allow the AI to consult but not modify, e.g., reference docs, online config samples, and other projects' source code.
 Suggested practices:
 1. Keep authorization minimal—only add the directories the current task needs;
 2. Never add sensitive directories (`~/.ssh`, key stores, system directories) under any category;
 3. Adjust promptly when the nature of a task changes. Authorization takes effect immediately (except for new terminal sessions, see above).
 ## 3. Network Permission
 An independent group in the input bar permission menu:
 - **Restricted** (default): loopback only; the AI cannot reach the external network—suited for purely local tasks and prevents data exfiltration;
 - **Fully open**: allows outbound/inbound connections—enable it when the AI needs to search the web, call external APIs, or install dependencies.
 Network permission is independent of the file sandbox and can also be adjusted in plan mode.
 ## 4. Approval Panel
 Entry point: `+` menu → "Approval panel". Here you can see the approval history: which commands/writes were submitted for approval, who approved them (human or the auto-approval agent), and the outcome. In `auto_approval` mode, if you don't want the panel to pop up automatically, there is a toggle in Personal Space (not auto-opened by default).
 ## 5. Forbidden Command List
 The deployment-level config `forbidden_commands.json` (placed in `<data root>/config/`) can define **command patterns that are absolutely forbidden to execute**. Any match is rejected regardless of permission mode. This is the last line of defense—suitable for locking down commands like `rm -rf /` and `shutdown` on server deployments.
 ## 6. A Word of Caution About direct Mode
 `direct` = commands execute directly on the host, **with no sandbox at all**. It is hard-mutually-exclusive with the restricted tiers (readonly/approval/auto_approval)—only `unrestricted` can select direct, and switching from direct into a restricted tier automatically pushes you back to sandbox. There is exactly one legitimate use case: a command genuinely cannot run inside the sandbox (requires system-level permissions) and there is no alternative. In that case:
 1. First switch the permission tier to `unrestricted`, then temporarily switch to direct;
 2. Switch back to sandbox (and the original permission tier) as soon as the command is done;
 3. Note that after direct is switched on, it **persists and does not revert automatically**—forgetting to switch back means running unprotected long-term.
 ## 7. Current Security State of docker Mode
 In docker mode, the isolation boundary between users is the container itself: each user's terminal runs in an independent container, invisible to each other. The permission constraints **inside** the container are also truly enforced:
 - Under restricted tiers (readonly/approval/auto_approval), run_command, background commands, and persistent terminals all execute as a **non-privileged user (uid 10001)** inside the container—the workspace is owned by root, and writes are denied directly by kernel file permissions, without relying on recognizing command text; after approval, only that one command is retried as root;
 - Prerequisites: the workspace is owned by root, there are no globally writable files, and the container does not mount docker.sock (all satisfied by following the official deployment docs);
 - This enforcement holds only on **Linux hosts**—Docker Desktop on a local macOS machine does not enforce uid file permissions, so don't treat container-internal permissions as a security boundary during local development;
 - Multi-user deployments should combine container resource limits, image minimization, and other standard container security practices.
 ## 8. Security Posture by Platform
 Reiterating the conclusion from the "Core Concepts" chapter, because it directly affects how much you should trust the sandbox:
 - **Windows (WSL2)**: full data isolation is achievable, but WSL2 must be installed first;
 - **macOS (sandbox-exec)**: whitelist read model; both writes and reads can be restricted—processes can by default only read system directories, the workspace, and authorized paths; the trade-off is that top-level file names in the ancestor directories of authorized paths can be listed (file contents remain unreadable);
 - **Linux (bwrap+seccomp)**: writes can be restricted, but the read side is still globally readable, not yet aligned to a whitelist, and **not yet tested in practice**—don't rely on its isolation.
 On any platform, the primary value of the sandbox is **preventing accidental operations**; for genuinely sensitive data, layer path authorization minimization, restricted network, and readonly permissions together for comprehensive protection.
--- a/content/en/06-conversation-assets.md
+++ b/content/en/06-conversation-assets.md
@ -0,0 +1,68 @@
 # Conversation Asset Management
 After the AI modifies files in your workspace, the core questions become "what changed, how do I roll back, and which version is broken". Astrion provides three layers of asset protection: **version control** (conversation-level checkpoints), **modify history** (task-level diffs), and the **Git status bar** (real-time awareness). They are independent of each other and can be layered on top of one another.
 ---
 ## 1. Version Control
 A conversation-level file checkpoint system that gives every round of AI changes a snapshot you can roll back to.
 ### Toggle and Backup Methods
 - Enabled **by default** for new conversations (the default can be changed in Personal Space);
 - A single conversation can be toggled temporarily via the `+` menu → "Version Control";
 - One of two backup methods (choice made in Personal Space):
  - **Shallow backup (default)**: tracks only files edited by the AI via **write_file / edit_file**, backing up the current content automatically before each edit — fast and space-efficient, sufficient for the vast majority of scenarios. ⚠️ Note the boundary: **files changed by the AI through commands run via run_command (such as sed, redirection, script writes) are not within the tracking scope of shallow backup**;
  - **Full backup**: a snapshot of the entire workspace — the most robust, but noticeably slower and more space-hungry on large projects.
 ### Checkpoint Granularity: Per User Message
 - **Each time you manually send a message**, the system records a checkpoint after that message finishes processing, referencing the latest backup version of all tracked files at that time — in other words, the smallest unit you can roll back to is "one manually-sent user message", not a single file edit;
 - Viewing a checkpoint's diff = the difference between that message's snapshot and the previous message's snapshot;
 - **Rolling back** to a checkpoint = restoring all tracked files to their state at that message (overwrite; confirm that current changes are saved elsewhere or committed before rolling back).
 ### Relationship with Other Mechanisms
 - Version control tracks **filesystem state**, which is unrelated to conversation messages;
 - It does not conflict with Git: the AI never commits for you. Version control is another safety net alongside Git, suited to the scenario of "files broke before you had time to commit".
 ## 2. Modify History
 Task-level net modification records, **enabled by default**.
 - After each task round completes, all files edited by the AI in that round are written to disk as a **unified diff** at: `<workspace>/.astrion/modify_history/<conversation ID>/`;
 - One `.diff` file per task; the file name includes a summary of that task's user input and the start time;
 - The "edit summary card" in the conversation shows the list of files edited in that round; clicking it shows the diff. When the card appears is configurable in Personal Space (by default it shows after the work completes; it can also be changed to show in real time during execution).
 ### Manual Recovery with Diff Files
 History files can be operated on directly with git tools:
 ```bash
 cd <workspace>
 git apply <diff-file>     # Redo this change
 git apply -R <diff-file>  # Revert this change
 ```
 Typical scenario: version control was off, Git had no commit, and `git checkout` accidentally overwrote the AI's work — go to modify_history, find the diff for the corresponding task, and `git apply` to recover.
 > This directory is maintained automatically by the system; do not add or remove files in it manually. It can be disabled entirely in Personal Space (when disabled, nothing is written to disk and no prompts are injected).
 ## 3. Git Status Bar
 A status bar above the input bar that shows a real-time summary of the current workspace's Git status (current branch, amount of uncommitted changes, etc.), so you can tell "how dirty the workspace is and how much the AI changed" without leaving the conversation.
 - Shown by default; can be quickly toggled via the `+` menu → "Git Status Bar", with the same setting available in Personal Space;
 - Not shown when the workspace is not a Git repository.
 ## 4. How to Choose Among the Three Layers
 | Need | Layer to use |
 |------|--------|
 | Real-time awareness of workspace changes | Git status bar |
 | Roll back to a point in time in the conversation | Version control |
 | Precisely restore/undo one task round's changes | Modify history diff |
 | Long-term, serious, large-scale development | Still use Git commit — the first three layers are safety nets, not a replacement for version management |
 Recommended practice: for important projects keep "version control on + modify history on + commit regularly"; with all three nets layered, no matter how much the AI churns things up, nothing gets lost.
--- a/content/en/07-agent-capabilities.md
+++ b/content/en/07-agent-capabilities.md
@ -0,0 +1,156 @@
 # Agent Capabilities
 Astrion's agent capabilities fall into five areas: **sub agents** (delegates dispatched by the main agent), **multi-agent conversation** (a team of roles), **workflows** (predefined process templates), **Skills** (specialized capability packs), and **MCP** (external tool integration). This chapter covers how to use and configure each one.
 ---
 ## 1. Sub Agents
 ### What It Is
 A sub agent is an independent executor dispatched by the main agent **within the same process**: it has its own context, its own model configuration, and an independent lifecycle. The main agent uses it to **process mutually independent tasks in parallel** — typical scenarios: researching three technical approaches at once, or organizing documentation while tests run.
 What it is **not** for: sub agents cannot communicate with each other and cannot see the main conversation history, so collaborative tasks (where A's output is B's input) should be executed sequentially or handed to a single sub agent. Code writing/editing tasks are by default handled directly by the main agent.
 ### How to Use
 Usually you don't need to operate directly — tell the main agent "do X and Y for me at the same time" and it will decide on its own whether to split the work into sub agents. Two ways of running:
 - **Foreground (blocking)**: the main agent pauses and waits for it to finish; suited for fast tasks or scenarios where subsequent steps depend on the result;
 - **Background**: the main agent keeps working or chats with you; when the sub agent finishes, the system notifies you automatically.
 You can watch each sub agent's status and output in real time via the **"Sub Agents" pane in the Quick Dock** on the right side of the conversation area (see "Quick Dock").
 ### Lifecycle & Limits
 - States: `running` → `idle` (context is preserved, can continue the conversation) / terminal states (completed / failed / timed out / terminated);
 - Default concurrency limit: **5** (`SUB_AGENT_MAX_ACTIVE`);
 - Default timeout: **180 seconds**; you can specify a longer timeout for an individual task when creating it (1800+ seconds recommended for large-scale analyses);
 - Outputs are conventionally placed under `sub_agent_results/` in the workspace.
 ### Configuration (Model Library)
 Sub agents use a separate model library, `sub_agent_models.json`; see Section 6 of "Quick Start" for configuration. When creating an individual task, the main agent can specify: the model entry, thinking mode, timeout, max rounds, and more. If not specified, the `default_model` entry is used.
 ## 2. Multi-Agent Conversation
 ### What It Is
 A **conversation type** (chosen at creation time and immutable): the main agent is fixed as Team Leader, responsible for understanding your requirements, breaking down tasks, creating and directing a group of **role-assigned sub agents**, and consolidating their outputs.
 ### Role System
 5 preset roles:
 | Role | Responsibility |
 |------|------|
 | Full-Stack Engineer | Frontend/backend implementation, API design, debugging and integration |
 | UI Operator | UI operations and visual verification |
 | Code Reviewer | Code review |
 | Researcher | Research and information gathering |
 | Brainstormer | Brainstorming and idea exploration |
 A role = `role ID + instance number`, with display names like `Full-Stack Engineer_1`; numbers increment within each role.
 **Custom roles**: Personal Space has a role editor (role list → create/edit). A role definition is a Markdown file with metadata:
 ```markdown
 ---
 id: full-stack-engineer      # Role ID
 name: Full-Stack Engineer    # Display name
 description: One-line role summary  # Team Leader assigns tasks based on this
 model: ""                    # Pin a model (empty = sub-agent model library default)
 thinking_mode: thinking      # fast / thinking
 ---
 (The body is the role's system prompt: responsibilities, working principles, constraints...)
 ```
 ### Communication Mechanics (What You Need to Know)
 - Team Leader sends messages to sub agents in two ways: **assigning work** (non-blocking, keeps doing other things) and **asking** (blocking, waits for one round of reply);
 - Sub agents can ask/answer each other, but **all inter-sub-agent communication is reported to the Team Leader in sync**;
 - Every round of a sub agent's output is reported to the Team Leader in real time and shown in the conversation flow; you can jump in at any time to correct course.
 ### When to Use Multi-Agent
 Good fit: a small project that needs "a coder + a code reviewer + a UI runner" working in division of labor; not a fit: tasks a single thread can finish on its own (it only adds coordination overhead).
 ## 3. Workflows
 ### What It Is
 Write a **predefined process** (stages, review gates, branches, ending conditions) into a `WORKFLOW.md` file and save it as a template; once activated, the agent advances strictly stage by stage, reporting to you or a review agent after each stage, and only moves to the next stage after the review passes.
 ### How to Use
 - Activate: `+` menu → "Workflow", or type `/workflow` to choose;
 - Progression: after each stage, the AI reports automatically and moves to the next stage (when the stage includes a review gate, the review agent checks it; a rejection is sent back to the previous stage with remediation feedback);
 - Branches: at a branch point, the AI presents a menu of paths for you to decide;
 - Exit / check progress: ask the AI to exit the workflow or report current progress at any time;
 - Only one workflow can be active in a conversation at a time.
 ### Built-in Workflows
 | Workflow | Purpose |
 |--------|------|
 | bug-fix-triage | Defect triage and fix process |
 | code-review-pipeline | Code review pipeline |
 | feature-development | Full feature development process |
 | research-report | Research report generation process |
 ### Custom Workflows
 Write one following the `WORKFLOW.md` format of the built-in workflows and drop it into the workflow library directory. It's recommended to just ask the AI in natural language, e.g. "use the workflow-authoring skill to write me an xx workflow" — the system has built-in authoring guidelines and format validation, and the finished workflow is archived automatically and ready to activate.
 Workflow reviews are performed by the **workflow review agent** (`workflow_review`); see "Review Agents" below for configuration.
 ## 4. Skills (Skill Packs)
 ### What It Is
 A Skill = a folder + a `SKILL.md` file (a skill specification with metadata). It captures the experience of "how to do a certain type of task"; when the AI encounters a matching scenario, it reads the skill before acting — like giving the AI an on-the-job training manual.
 ### Built-in Skills (12)
 `agent-build-standard` (Agent architecture guide), `agents-md-writer` (writing AGENTS.md), `docx` (Word documents), `pptx` (PPT), `frontend-design` (frontend design), `ui-aesthetic-design` (UI aesthetics), `skill-creator` (creating new Skills), `workflow-authoring` (writing workflows), `run-command-guide` (command execution guidelines), `terminal-guide` (terminal usage guidelines), `sub-agent-guide` (sub agent guidelines), `mcp-tool-config` (MCP self-service configuration).
 ### How to Use
 - Insert a reference: type `//` or use the `+` menu → "Select AgentSkill" to insert a skill reference into your message;
 - Enable/disable: manage the enabled list on the "Tools & Skills" page in Personal Space;
 - **Strict-guard toggles** (all off by default): you can require "read terminal-guide before using the terminal", "read the guidelines before using run_command in foreground/background mode", and "read sub-agent-guide before dispatching a sub agent" — useful during the learning phase to prevent misuse, and can be turned off once you're experienced;
 - **Skill suggestions** (off by default): dynamically suggests potentially relevant skills based on the current task.
 ### Custom Skills
 Just tell the AI "capture today's process as a skill" and it will create, validate, and archive it following the `skill-creator` guidelines, ready to reuse afterwards. User skills are stored in `.astrion/skills/` in the workspace.
 ## 5. MCP Tool Extensions
 Connect external tool services (databases, browser automation, third-party SaaS...) via [Model Context Protocol](https://modelcontextprotocol.io); after connecting, new tools of the form `mcp__service name__tool name` appear in the AI's tool list.
 - **Config file**: `<data root>/<mode>/data/mcp_servers.json` (can be overridden with `MCP_SERVERS_FILE`);
 - **Master switch**: `MCP_TOOLS_ENABLED` (on by default);
 - Protocol version `2025-06-18`, default 25-second timeout for tool discovery/invocation;
 - **Host mode feature**: you can directly ask the AI to "configure xxx MCP service for me" — the built-in `mcp-tool-config` skill guides it to write the config and make it take effect on its own.
 ## 6. Review Agents (Three)
 Three independent AIs that check key milestones on your behalf, all configured on the "Review Agents" page in Personal Space; **they reuse the sub agent model library**:
 | Review Agent | When It Steps In |
 |------------|----------|
 | `auto_approval` Auto-approval | Under the `auto_approval` permission mode, auto-approves when a command is about to write outside the sandbox or triggers a permission denial |
 | `goal_review` Goal review | In goal mode, evaluates whether each round of work achieved the goal |
 | `workflow_review` Workflow review | At workflow review gates, decides whether to pass or reject |
 Each can be configured with: `model` (leave empty for the model library default), `thinking` (thinking mode), `timeout_seconds`, `max_rounds`, `max_command_timeout`.
 > Tip: for review agents, choose **cheap but stable** models — they are called frequently with fixed task patterns, so flagship models are unnecessary.
 ## 7. Combinatorial Examples
 - **Multi-agent + workflow**: after activating the feature-development workflow, the Team Leader directs the role team through stage-by-stage delivery per the process;
 - **Sub agents + Skills**: insert `//frontend-design` before a research task, and the sub agent works with the design guidelines in mind;
 - **MCP + Quick Dock**: when a browser-automation MCP runs a long task, watch real-time progress in the "Background Commands" pane.
--- a/content/en/08-quick-dock.md
+++ b/content/en/08-quick-dock.md
@ -0,0 +1,33 @@
 # Quick Dock
 A column of floating windows on the right side of the conversation area. It gathers the "interactive artifacts produced during a task" in one place, so you can keep an eye on everything without scrolling through the message stream.
 ---
 ## 1. The Five Windows
 From top to bottom:
 | Window | What it shows | Typical actions |
 |------|----------|------|
 | **Workflow** | The currently active workflow: which stage it is at, review status, pending branches | Check process progress; use alongside branch selection |
 | **Todos** | The AI-created task list (todo): completion status of each item | See how far the AI's execution plan has advanced |
 | **Sub agents** | Running/idle sub agent instances: status, what they are currently doing | Open details to see the output timeline; use the ⋯ menu to **force-close** an out-of-control instance |
 | **Background commands** | Command tasks running in the background: status, elapsed time | Open details to see the full output; force-close from the ⋯ menu |
 | **File records** | Files the AI has edited or created in the current task | ⋯ menu: **download** / **open in file manager** (host mode) / **copy path** |
 ### Details panel
 - Click a sub agent / background command entry → opens the **runner details panel**: outputs and tool calls are interleaved on a real timeline; you can force-close when something runs out of control;
 - Click a file entry → opens the **file preview panel**: view the file content directly. Long lines scroll horizontally by default; in Personal Space you can switch to wrapping by panel width.
 ## 2. Expand and Collapse
 - **Auto-expand when there is content** (default): when any window has content, the whole column expands automatically; when all are empty, it collapses into a thin edge strip that takes up no space;
 - In Personal Space you can switch to **manual expand only** (`quick_dock_auto_expand`), or **hide entirely** (`hide_quick_dock`).
 ## 3. Usage Tips
 - **Watch for runaway processes**: when a sub agent or background command misbehaves, don't shout into the conversation — just use ⋯ → force close;
 - **Watch progress**: during long tasks, the Todos window plus the Sub agents window is your project board;
 - **Collect artifacts**: when the task ends, batch-download or jump to the directory from the File records window — much faster than hunting through cards in the message stream.
--- a/content/en/09-settings.md
+++ b/content/en/09-settings.md
@ -0,0 +1,154 @@
 # Personal Space Settings: The Complete Guide
 Personal Space (input bar `+` menu → "Personal Settings") has 12 tabs in total (admins get 1 more). This chapter explains **every page and every item** — what each setting does, its default value, and when to use it. Anything that can't be explained in one sentence on the settings page is covered in full here.
 > Convention: "default" refers to the default value baked into the code. If you've used the `setup.sh` wizard, some defaults may have been overridden by your choices in the wizard.
 ---
 ## 1. General
 | Setting | Default | Description |
 |--------|------|------|
 | Auto-generate title | On | Automatically generates a conversation title after the first round. When off, new conversations keep the "New Conversation" placeholder name and need manual renaming |
 ## 2. Personalization
 This page decides "what personality the AI adopts when interacting with you".
 | Setting | Default | What It Does & When to Use |
 |--------|------|------------|
 | Enable personalization | Off | Master switch for this page. When off, none of the settings below are injected into prompts |
 | AI's self-name | Empty | What the AI calls itself (≤20 characters), e.g. "Xiao A" |
 | How it addresses you | Empty | What the AI calls you (≤20 characters) |
 | Occupation | Empty | Your occupation (≤20 characters). When filled in, the AI adjusts the depth of its explanations to your background — developers get technical details, business folks get plain language |
 | Tone | Empty | 8 presets: conversational / humorous / blunt / encouraging / poetic / corporate / unconventional / empathetic |
 | Notes | Empty | **The most powerful item**: up to 10 long-term instructions, each up to 2000 characters, injected into every round of conversation. Good for persistent preferences like "always answer in Chinese", "write code comments in English", or "I'm colorblind — avoid red-green palettes in charts" |
 | Communication style | Standard | Standard AI style / human-like chat style / auto (switches by scenario) |
 | Conversation continuity | Medium | High: actively revisits past conversations and memories; medium: balanced; low: each round stands on its own as much as possible. **If you've turned on "Recent conversation hints" but feel the AI keeps bringing up old topics irrelevantly, lower this setting** |
 ## 3. Model & Thinking
 | Setting | Default | Description |
 |--------|------|------|
 | Default model | First visible item in the model library | The model used by default for new conversations; any registered model in the library can be chosen |
 | Default thinking mode | Thinking | fast / thinking. Thinking mode gives higher quality; Fast mode responds faster |
 | Default reasoning effort | Default (no parameter passed) | default / low / medium / high; only takes effect if the model supports `reasoning_effort` |
 > The "defaults" here only affect **new conversations**; for existing conversations, adjust individually with the switcher in the input bar.
 ## 4. Appearance & Display
 | Setting | Default | Description |
 |--------|------|------|
 | Theme | Classic | Classic (warm cream + warm orange) / Bright (cool white + near black) / Night (neutral grays) |
 | Message flow display mode | Minimal mode | Traditional list / stacked animation / minimal mode; minimal mode has an extra "limit max height when expanded" toggle (on by default) |
 | Condensed message display | Full info | Full original content / one-line summary |
 | Hide stacked block dividers | Off | Hides the dividers between stacked blocks for a cleaner look |
 | Show assistant status avatar | On | The status avatar in the conversation area (poke it — there's an easter egg) |
 | Show Git status bar | On | The Git status bar above the input bar |
 | Show custom names | On | Displays the self-name/address name you configured in the UI |
 | Enhanced tool display | On | Structured rendering of tool results; turning it off makes output closer to raw |
 | Auto-open terminal panel | — | Automatically expands the live terminal panel for terminal tasks |
 | Auto-expand Quick Dock | On | Auto-expands Quick Dock when it has content; when off, it can only be opened manually |
 | Hide Quick Dock | Off | Disables Quick Dock entirely |
 | Real-time edit summary | Off | On: shows an edit summary card as the AI edits; off: shows a consolidated summary after each round of work |
 | Wrap file preview | Off | On: the preview panel wraps lines to fit the width; off: long lines scroll horizontally |
 | Group sidebar by workspace | Off | Groups the conversation list by workspace/project; grouping mode supports pinning and sorting workspaces |
 | New conversation button behavior | Navigate to blank page | route: navigate to a blank new-conversation page / blank: immediately create an empty conversation |
 ## 5. Workspace & Permissions
 | Setting | Default | Description |
 |--------|------|------|
 | Default permission mode | Approval | The initial permission mode for new terminals; see "Core Concepts" for the behavior of all four levels |
 | Default work mode | Plan | The initial work mode for new terminals: Plan / Ask / Execute |
 | Hide workspace by default | Off | Collapses workspace info in the UI by default |
 | Auto-inject AGENTS.md | Off | On: each round automatically carries the project-root AGENTS.md, so the AI always works with the project standards in mind. Recommended for long-running projects |
 | Track modifications | On | Writes the net diff of changes to `.astrion/modify_history/` after each round. When off, nothing is written and no prompt is injected |
 | Version control on by default for new conversations | On | Keep this on — it's your file safety net |
 | Version control backup method | Shallow backup | Shallow: only backs up files edited by the AI; full: snapshots the entire workspace (use with care on large projects) |
 | Goal review mode | Read-only conversation | How goal mode is reviewed: readonly — judges from the conversation only / active — allows the review agent to run read-only commands for evidence |
 | Goal max rounds | Has a default | The cap on auto-continuing rounds in goal mode |
 | Goal token ceiling | Disabled | Stops when cumulative input + output tokens reach the limit (1k–100M). Note this is a workspace-level approximate count |
 ## 6. Context
 This page is key to long-conversation quality; **read Section 4 of "Input & Context" before changing anything**.
 | Setting | Default | Description |
 |--------|------|------|
 | Recent conversation hints | Off | On: new conversations automatically receive summaries of the most recent N historical conversations |
 | Number of recent conversations | 10 | The N in the item above; 1–30 |
 | Project memory index limit | 20 entries | Max number of project memory index entries injected (≥5; can be set to unlimited) |
 | Auto shallow compression | Off | ⚠️ **breaks the context cache** — see "Input & Context". Not recommended |
 | Shallow compression trigger tokens | 80000 | When customizing, **at least 80% of the model's actual usable context** |
 | Shallow compression: keep recent tool results | 15 | The most recent N tool results are not compressed |
 | Shallow compression: keep post-user tools | 3 | Tools after the most recent N user inputs are not compressed |
 | Shallow compression: max replacements per round | 10 | Max number of tool results replaced in a single compression |
 | Shallow compression: tool call interval | 10 | Checks whether to trigger every N tool calls |
 | Auto deep compression | On | Recommended to keep on |
 | Deep compression trigger tokens | 150000 | Follows the same 80% rule |
 | Deep compression output form | Generate file | file: writes the summary to a file for on-demand use (recommended) / inject: injects the full summary directly |
 ## 7. Tools & Skills
 | Setting | Default | Description |
 |--------|------|------|
 | Silently disable tools | On | When a tool is disabled, no prompt is injected into the model — cleaner context |
 | Hide tool approval panel | On | Under the auto_approval mode, doesn't auto-pop the approval panel to bother you; off: any approval request pops up immediately |
 | Tool intent description | On | Shows a brief "what it intends to do" note on tool call cards; turning it off makes the message flow more compact |
 | Skill suggestions | Off | Dynamically suggests possibly relevant Skills based on the current task |
 | Strict guard: terminal | Off | On: the AI must read the terminal-guide guidelines before using terminal tools |
 | Strict guard: sub agents | Off | On: must read sub-agent-guide before dispatching sub agents |
 | Strict guard: foreground commands | Off | On: must read the guidelines before run_command in foreground mode |
 | Strict guard: background commands | Off | On: must read the guidelines before run_command in background mode |
 | Enabled Skills list | All | Choose which Skills can be used |
 | Disabled tool categories | None | Disables tools by category (e.g. disabling the web-search category) |
 The four "strict guards" are guardrails for beginners: they force the AI to read usage guidelines before touching high-risk tools, significantly reducing the misoperation rate; once you're experienced, turning them off saves tokens.
 ## 8. Files & Images
 | Setting | Default | Description |
 |--------|------|------|
 | Image compression level | Original | Original / 1080p / 720p / 540p. For long conversations with many large images, consider lowering the level to save context |
 ## 9. Data Management
 A read-only **usage statistics** page: cumulative input/output tokens, total number of conversations, user message count, and tool call count, with manual refresh. It answers questions like "how many tokens did I burn this month".
 ## 10. Speech Model
 Download management for the on-device speech recognition model (SenseVoice int8): about 228MB, **runs locally on the phone only — no network required**, supports mixed Chinese-English speech and automatic punctuation. The page shows download status (not downloaded / downloading with percentage / downloaded / incomplete download), and supports re-download or deletion. This feature targets the Android client.
 ## 11. Sub Agents
 The multi-agent **role editor**: role list, create role, edit role. See Section 2 of "Agent Capabilities" for role fields and format. The 5 preset roles serve as reference, and custom roles are ready to use as soon as you edit them.
 ## 12. Review Agents
 A unified configuration page for the three review agents (auto-approval / goal review / workflow review), each configurable with:
 | Field | Description |
 |------|------|
 | Model | An entry name from the sub agent model library; **leave empty = use `default_model` from the library** |
 | Thinking mode | fast / thinking |
 | Timeout | Max wait time for a single review |
 | Max rounds | Cap on the review agent's own working rounds |
 | Command timeout | Per-command timeout for verification commands run during a review |
 Configuration advice: review tasks follow fixed patterns and are called frequently, so cheap, stable models are enough — no need for flagship ones.
 ## 13. Admin (Visible to Admins Only)
 An admins-only page: user and policy management (the `admin/`-related interfaces). Regular users can't see this page.
 ---
 ## Appendix: How Settings Take Effect
 - All settings are stored in `personalization.json` in the data directory, isolated per user;
 - "Default XX" settings only affect newly created objects (new conversations/new terminals), never existing ones;
 - Display-related settings (theme, display mode, etc.) take effect immediately;
 - Settings that involve prompt injection (personalization, notes, AGENTS.md injection, etc.) take effect from the next round of conversation.
--- a/content/en/10-cli.md
+++ b/content/en/10-cli.md
@ -0,0 +1,36 @@
 # CLI (In Development)
 > ⚠️ The CLI is currently in a **development state under rewrite**; functionality and stability are defined by the Web client. This article only describes its current form, and the behaviors listed may change later.
 ---
 ## 1. What It Is
 A conversation client in the terminal: a TUI built with **React 19 + Ink 6 + TypeScript** that lets you talk to Astrion without opening a browser.
 Key point: the CLI is **not a standalone agent runtime**—it connects to the Astrion Web service running locally on your machine (default `127.0.0.1:8091`). All conversations, tool execution, and permission control go through the backend; the CLI is just a lighter interactive interface.
 ## 2. Startup
 ```bash
 npm --prefix cli install   # install dependencies on first use
 npm run cli                # start; automatically connects to the local 8091 service
 ```
 On startup it clears the screen, connects to the local service, creates a new session, and pins the input area to the bottom. If the current directory is not inside any authorized workspace, it first asks whether to add it as a workspace.
 ## 3. Current Capabilities and Limits
 - Basic conversation, streaming output, tool call display;
 - `/` command system (in design; see the repo's `docs/cli_slash_commands_spec.md`);
 - Thinking content is collapsed by default, showing only "thinking / thinking done";
 - Multimodality, Quick Dock, version control, and other Web-side capabilities are **not yet aligned** in the CLI—use the Web client when you need the full feature set.
 ## 4. For Developers
 ```bash
 npm run cli:typecheck   # type checking
 npm run cli:build       # build (artifacts provide the agents / agents-cli commands)
 ```
 The CLI code lives in `cli/src/` (`App.tsx`, `components.tsx`, `eventMapper.ts`, `api.ts`); contributions welcome.
--- a/demo/content/en/01-quick-start.md
+++ b/demo/content/en/01-quick-start.md
@ -0,0 +1,241 @@
 # Quick Start
 This chapter walks you through running Astrion from scratch: cloning the code, completing the initial configuration, starting the service, and choosing the right runtime shape for your use case.
 ---
 ## 1. System Requirements
 | Dependency | Requirement | Notes |
 |------|------|------|
 | Python | 3.9+ (3.11 recommended) | Backend runtime |
 | Node.js | 18+ | Building the frontend, using the CLI |
 | Docker | Optional | Required only for **web/docker mode**; not needed for host mode |
 | WSL2 | Windows only | Prerequisite for using the host sandbox on Windows |
 Astrion runs on macOS, Linux, and Windows (WSL2). For the differences in sandbox capabilities across the three platforms, see the "Core Concepts" chapter.
 ---
 ## 2. Installation
 ```bash
 # 1. Clone the repository
 git clone https://github.com/JOJO6618/astrion.git
 cd astrion
 # 2. Initialize: create a venv, install dependencies, and run the interactive setup wizard
 #    The wizard asks, in order: work mode → listen address/port → admin account → model API → generate secret keys
 ./setup.sh
 # 3. Build the frontend
 npm install && npm run build
 # 4. (web/docker mode only) Build the sandbox image; see "Choosing a work mode" below
 docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .
 # 5. Start
 ./start.sh
 # Or start manually:
 python -m server.app --port 8091 --thinking-mode
 ```
 After startup, visit `http://localhost:8091` and log in with the admin account you set up in the wizard.
 > The `setup.sh` wizard writes the configuration to `.env` at the repository root. This is a development fallback; for production deployments we recommend using the `settings.json` under the data root or system environment variables instead. See "Configuration priority" below.
 ---
 ## 3. Port and Listen Address
 - **Default port: `8091`** (`WEB_SERVER_PORT`).
 - Listen address (`WEB_SERVER_HOST`):
  - Single-machine personal use: `127.0.0.1` is recommended — listens only on the local loopback, unreachable from the LAN;
  - Multi-user / server deployment: use `0.0.0.0`.
 - The `--port` CLI argument can temporarily override the configuration.
 - Debug mode `WEB_SERVER_DEBUG=1` (also enables the Flask reloader); keep it at `0` in production.
 ---
 ## 4. Data Paths: Where Data Lives and How to Move It
 Astrion's runtime data (conversation records, users, logs, deployment-level config) is **by default stored entirely under your home directory and never pollutes the source tree**:
 ```
 ~/.astrion/astrion/           ← data root (data_root)
 ├── settings.json             ← single configuration file (highest priority)
 ├── config/                   ← deployment-level config (model libraries, etc., shared by host/web)
 ├── host/                     ← host mode data
 │   ├── data/  users/  logs/  api/
 └── web/                      ← web/docker mode data (same structure above)
 ```
 Data is routed automatically by work mode: when `TERMINAL_SANDBOX_MODE=host`, data goes into `host/`; otherwise it goes into `web/`.
 ### Path-Related Environment Variables (priority from high to low)
 | Environment variable | Purpose |
 |----------|------|
 | `DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR` | Override a single directory individually (highest priority) |
 | `ASTRION_DATA_ROOT` | Move the entire data root (default `~/.astrion/astrion`) |
 | `DEPLOY_CONFIG_DIR` | Move just the deployment-level config directory (default `<data root>/config/`) |
 Individual directory variables accept relative paths (resolved relative to the repository root), absolute paths, and `~`.
 ### Configuration priority
 Effective order for same-name configuration: **`<data root>/settings.json` > system environment variables > `.env` at the repository root > code defaults**.
 `.env` does not override existing system environment variables when loaded; `settings.json` is the recommended way to configure production, for example:
 ```json
 {
  "server": { "port": 8091, "host": "127.0.0.1" }
 }
 ```
 ---
 ## 5. Configuring the Main Agent Model
 The main agent's models are registered centrally in **`custom_models.json`**.
 **Placement** (looked up by fallback chain; first hit wins):
 1. `<data root>/config/custom_models.json` (recommended for production)
 2. `config/custom_models.json` inside the repository
 3. `config/custom_models.json.example` inside the repository (seed example)
 **Full field reference**:
 ```json
 {
  "models": [
    {
      "model_name": "Kimi-K3",
      "description": "Model description shown to users",
      "visible": true,
      "url": "${API_BASE_KIMI}",
      "apikey": "${API_KEY_KIMI}",
      "multimodal": "image,video",
      "reasoning_capability": "fast,thinking",
      "reasoning_effort": true,
      "context_window": 1048576,
      "max_output_tokens": 64000,
      "thinkmode_status": {
        "type": "param_toggle",
        "model_id": "k3",
        "fast_extra_parameter":     { "thinking": { "type": "disabled" } },
        "thinking_extra_parameter": { "thinking": { "effort": "max" } }
      },
      "extra_parameter": {},
      "model_description": "Model self-description injected into the system prompt"
    }
  ]
 }
 ```
 | Field | Required | Description |
 |------|------|------|
 | `model_name` | ✅ | Model entry name; shown in the UI and used as the key that other config references |
 | `url` | ✅ | Base API address. **Supports `${environment variable}` references**; don't write secret keys in plain text |
 | `apikey` | ✅ | API key, also supports `${...}` |
 | `description` | | Description text shown in the list |
 | `visible` | | Whether it is visible in the model selection menu |
 | `multimodal` | | `image,video`, etc.; determines whether the input bar allows sending images/videos |
 | `reasoning_capability` | | `fast,thinking`; determines the available thinking mode options |
 | `reasoning_effort` | | Whether the "reasoning effort" slider is supported |
 | `context_window` | | Context window size (tokens); the baseline for compression thresholds and usage statistics |
 | `max_output_tokens` | | Maximum output tokens per response |
 | `thinkmode_status` | | `param_toggle` type: `model_id` is the real model ID; `fast/thinking_extra_parameter` are the extra request parameters attached in each of the two modes respectively |
 | `extra_parameter` | | Extra parameters attached to every request |
 | `model_description` | | Self-description injected into the system prompt |
 **Minimum config** needs only 4 fields: `model_name` / `url` / `apikey` / `thinkmode_status.model_id`; all other fields have defaults.
 > Note: the model entry created by the `setup.sh` wizard in step 5 is exactly the minimum config — `multimodal` is `none` (cannot send images/videos), `context_window` is fixed at 128000, and `max_output_tokens` is 32768. If your model supports multimodality or a larger context, edit `<data root>/config/custom_models.json` manually after running the wizard to fill in the fields.
 **Default model**: when `AGENT_DEFAULT_MODEL` is not set, the first visible model in the list is used; you can also set a per-user default model in the "Models & Thinking" page in Personal Space.
 > Note: the legacy `AGENT_API_*` / `AGENT_THINKING_*` / `AGENT_TITLE_*` environment variables have been removed from the code; configuring them no longer has any effect.
 ---
 ## 6. Configuring Sub Agent Models
 Sub agents (including the three review agents) use a **separate model library**: `sub_agent_models.json`.
 **Placement**: it is read only from the deployment config directory — `<data root>/config/sub_agent_models.json` (can be overridden individually with `SUB_AGENT_MODELS_CONFIG_FILE`). **Without this file, sub agents will fail to start** and report "no usable sub agent model configuration found".
 **Structure**:
 ```json
 {
  "default_model": "deepseek-v4-flash",
  "models": [
    {
      "name": "deepseek-v4-flash",
      "url": "${SUB_AGENT_API_BASE}",
      "apikey": "${SUB_AGENT_API_KEY}",
      "model_id": "deepseek-v4-flash",
      "modes": "fast,thinking",
      "multimodal": "image",
      "max_output": 32000,
      "max_context": 128000,
      "extra_parameter": {},
      "fast_extra_parameter": {},
      "thinking_extra_parameter": {}
    }
  ]
 }
 ```
 Key points:
 - `default_model`: the default entry name; used when `model` is left empty in sub agent / review agent config. If the specified name does not exist, it falls back to the first available entry in the list.
 - Field names are loosely compatible: `name`/`model_name`/`model`, `url`/`base_url`, and `apikey`/`api_key` all work; `modes` set to `fast,thinking` means thinking mode is supported, while just `fast` means fast-only mode.
 - The same `thinkmode_status` structure as the main model library is also supported; you can copy an entry from `custom_models.json`, rename it, and use it directly.
 - `url` / `apikey` also support `${environment variable}` references.
 **Sub agent environment variables**:
 | Variable | Default | Description |
 |------|------|------|
 | `SUB_AGENT_MAX_ACTIVE` | 5 | Maximum number of simultaneously running sub agents |
 | `SUB_AGENT_DEFAULT_TIMEOUT` | 180 (seconds) | Default timeout |
 | `SUB_AGENT_TASKS_BASE_DIR` | `<data root>/<mode>/data/sub_agent_tasks` | Task directory |
 | `SUB_AGENT_PROJECT_RESULTS_DIR` | `<workspace>/sub_agent_results` | Delivery directory (intentionally placed inside the workspace) |
 ---
 ## 7. Choosing a Work Mode: host or docker (web)
 Determined by `TERMINAL_SANDBOX_MODE`; the two modes target completely different scenarios:
 | | **host mode** | **web/docker mode** |
 |---|---|---|
 | Positioning | Local personal use | Multi-user server deployment |
 | Command execution | Host OS sandbox (macOS sandbox-exec / Linux bwrap / Windows WSL2) | Per-user isolated Docker container, executed as a non-privileged uid under restricted permissions |
 | Data directory | `~/.astrion/astrion/host/` | `~/.astrion/astrion/web/` |
 | Prerequisites | No image needed; Windows requires WSL2 first | Must build the image first: `docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .` (the build context must be the repository root) |
 | Image name | — | Specified by `TERMINAL_SANDBOX_IMAGE`; `my-agent-shell:latest` is recommended |
 Recommendations:
 - **Using it alone on your own computer** → `host`. The file manager and local toolchain work directly; the best experience.
 - **Deploying to a server for multiple users** → `docker`. Containers naturally isolate files and processes between users.
 - host mode can also read web mode data (user list, merged workspace display); the reverse is not possible.
 The sandbox image is based on `python:3.11-slim` and ships with a common toolchain: LibreOffice / Pandoc / FFmpeg / Tesseract OCR (with Chinese) / Chromium / Node 20 / docx / pptxgenjs, etc. **The program does not build the image automatically**; you must build it manually once before starting web mode.
 ---
 ## 8. First-Start Checklist
 1. Open `http://localhost:8091` in a browser and log in with the admin account;
 2. Go to Personal Space and confirm the "Models & Thinking" page shows the models you configured;
 3. Send a message and confirm the main agent replies normally;
 4. Have the main agent create a sub agent (or trigger one by saying "help me look up xxx"), and confirm `sub_agent_models.json` is configured correctly;
 5. For web mode, confirm the image has been built and the terminal container starts properly.
 At this point, your Astrion is up and running. Next, we recommend reading "Core Concepts" to understand four sets of concepts — deployment modes, permission modes, execution environments, and work modes — which define the boundaries of Astrion's behavior.
--- a/demo/content/en/02-core-concepts.md
+++ b/demo/content/en/02-core-concepts.md
@ -0,0 +1,111 @@
 # Core Concepts
 Astrion is built on four sets of **mutually orthogonal** concepts. Understanding them is the key to understanding the entire system: any combination of them determines what a task "can do, where it runs, and to what extent".
 | Concept group | Values | Determines | Where to switch |
 |--------|------|----------|------------|
 | **Deployment mode** | host / docker(web) | Where data is stored, and whether commands run on the host or in a container | Environment variable (set at deploy time) |
 | **Permission mode** | readonly / approval / auto_approval / unrestricted | Whether AI tool calls require approval | Permission menu in the input bar (per conversation) |
 | **Execution environment** | sandbox / direct | Whether commands go through the OS sandbox | Permission menu in the input bar (per conversation, host mode only) |
 | **Work mode** | plan / ask / execute | The pace of AI's interaction with you: plan first or act directly | Work mode switcher in the input bar (per conversation) |
 ---
 ## 1. Deployment Mode: Host vs Docker (Web)
 Deployment mode is determined **before startup** by the environment variable `TERMINAL_SANDBOX_MODE` and cannot be switched at runtime.
 - **Host mode**: designed for local personal use. Commands run through the host OS sandbox, and the AI can directly operate on the local directories you have authorized (such as a real project repository). The file manager and local Node/Python toolchains are directly available.
 - **Docker mode (web mode)**: designed for multi-user server deployment. Each user's terminal commands run in an independent Docker container, and files and processes are naturally isolated between users. You need to build the sandbox image first (see "Quick Start").
 The two modes keep completely separate data directories (`~/.astrion/astrion/host/` and `web/`), but host mode **merges and reads** the user and workspace lists from web mode — so historical data from both modes on the same machine is visible.
 > Note: Docker mode also enforces read-only — under restricted permission levels (readonly/approval/auto_approval), commands run inside the container as a non-privileged user (uid 10001), and writes are directly rejected by kernel file permissions. The two-stage "read-only → approval → single writable retry" flow is identical to host mode (see "Execution & Security" for details).
 ## 2. Permission Mode: What the AI Can Do
 Permission mode is a **product-level** switch that determines whether tool calls are intercepted and whether approval is required. It is switched per conversation and can be changed at any time.
 ### Read-only
 - `run_command` is allowed, but runs in a **read-only sandbox**; once the command attempts a write, the operating system directly returns a permission denial (e.g., `Operation not permitted`).
 - Write tools such as `write_file` / `edit_file` are **directly rejected**.
 - Use cases: when you want the AI to only do code review, read-only analysis, or answer questions.
 ### Approval (default)
 - `run_command` follows a **two-stage** flow: first it runs in a read-only sandbox → if a permission denial occurs, an approval request is raised to the frontend → after you approve, **only that command** is retried once in a writable sandbox.
 - The tool returns the final result after the retry; the AI never sees the intermediate denial process.
 - If approval is denied or times out: the command is not executed and nothing is written.
 ### Auto-approval
 - The same "read-only first" flow as approval, except the approver is an **auto-approval agent** (an independent AI whose model and parameters can be configured in Personal Space).
 - `write_file` / `edit_file`: targets inside the workspace execute directly; targets outside the workspace go through auto-approval.
 - When auto-approval is denied, the AI receives a "denied + reason" and continues trying other paths without interrupting the whole round of tasks.
 - You can take over manually at any time: approve / deny / switch to Unrestricted.
 ### Unrestricted
 - The permission layer performs no interception; tools execute directly.
 - At this point the security boundary is entirely determined by the execution environment (see the next section): under sandbox the OS sandbox still provides a safety net, while under direct it is equivalent to running bare.
 ## 3. Execution Environment: Sandbox vs Direct
 The execution environment is a **system-level** switch (switchable in host mode only) that determines whether commands ultimately pass through the OS sandbox:
 - **sandbox (default)**: commands run inside the OS sandbox, and the read/write boundary is limited by "path authorization". When the sandbox is unavailable, critical execution paths are **refused to run** rather than silently falling back to the bare host.
 - **direct (high risk)**: commands run directly on the host with no sandbox restrictions. It is selectable only under the `unrestricted` permission — restricted levels (readonly/approval/auto_approval) and direct are strictly mutually exclusive: switching to direct under a restricted level is rejected, and switching from direct into a restricted level is automatically pushed back to sandbox. It is only recommended to enable it **temporarily** when system-level privileges are clearly needed, and to switch back immediately after use. Once switched, it stays in effect — there is no automatic fallback mechanism.
 ### Sandbox Implementation and Security Level by Platform (Please Read)
 | Platform | Implementation | Security level |
 |------|------|----------|
 | **Windows** | WSL2 | **Full data isolation is achievable** — commands run in an independent WSL2 filesystem. Prerequisite: **install WSL2 yourself first**; the sandbox is unavailable without it |
 | **macOS** | sandbox-exec | **Whitelist-based read model; both reads and writes can be restricted** — by default a process can only read system directories, the workspace, and authorized paths; out-of-bounds reads are directly denied. Inherent cost: file names at the top level of an authorized path's ancestor directories can be listed (file contents remain unreadable) |
 | **Linux** | bubblewrap (bwrap) + seccomp | Writes can be restricted (read-only level is globally read-only), but **reads are still globally readable** and not yet aligned with a whitelist; it has not been tested in practice, so relying on its isolation in production is not recommended |
 This is the official, candid statement of current security capabilities: as a way to **prevent accidental mistakes**, the sandbox is reliable on all three platforms; as a way to **prevent malicious data theft**, macOS (whitelist) and Windows (WSL2) can be trusted, while Linux cannot — for now.
 ### Path Authorization
 In host mode, the sandbox's file access boundary is determined by path authorization, which has two categories:
 - **Read-write paths**: the AI can read and modify them;
 - **Read-only paths**: the AI can view but not modify them.
 Relationship: `readable set = read-write + read-only`; `writable set = read-write`. Maintained in the input bar `+` menu → "Path Authorization". It is recommended to keep authorization minimal: workspace + temporary directory.
 > The read/write identity of a terminal session (terminal family of tools) is **pinned at startup** according to the permission level, execution environment, and sandbox policy at that time: under a restricted level the terminal runs as read-only, and only under `unrestricted` does it run as writable. **Switching the execution environment (sandbox ⇄ direct), toggling the permission level between a restricted level and Unrestricted, or switching the workspace or container closes existing terminal sessions immediately**, after which subsequent operations run in freshly spawned sessions under the new policy.
 ### Network Permissions
 A separate set of switches independent of the file sandbox (also adjustable in Plan mode):
 - **Restricted** (default): only local loopback access is allowed; external networks are unreachable;
 - **Fully open**: all outbound/inbound connections are allowed.
 ## 4. Work Mode: The Pace of AI's Interaction with You
 Work mode controls **when the AI acts and when it asks you first**, and is fully orthogonal to permissions. It can only be switched while idle (switching during a running task returns a 409 notice).
 - **Plan**: the AI only drafts a plan and discusses it with you, without actually changing anything. In this mode, permissions are **locked to read-only** and the execution environment is **locked to sandbox** (enforced on both the UI-disabled side and the backend, except for network permissions). The only exception is writing plan documents under `.astrion/plan/*.md`. Once the plan is written, the AI calls `submit_plan` to ask for your approval; **approving automatically switches to Execute** and restores your previous permission settings.
 - **Ask**: discuss first, then start working. The AI writes its approach and questions in replies and confirms them back and forth with you, acting only after key details are settled. At the execution level there is no difference from Execute — only the pace of interaction differs.
 - **Execute**: the AI works out the plan and fills in details on its own, and starts working directly, asking questions only when it hits a hard blocker (missing information, account credentials required, etc.).
 ### Common Combinations
 | Scenario | Recommended combination |
 |------|----------|
 | Have the AI modify an important project you are maintaining | plan + approval + sandbox |
 | Everyday casual use that prioritizes efficiency | execute + auto_approval + sandbox |
 | Pure Q&A / code review; files must never be touched | any mode + readonly (execution environment automatically locks to sandbox) |
 | Multi-user server deployment | Docker mode (the execution environment concept does not apply) |
 ## 5. Quick Reference: Interaction Rules Between the Four Concept Groups
 1. Plan mode → permissions are forced to readonly, execution environment is forced to sandbox (network permissions remain adjustable);
 2. Restricted permission levels (readonly/approval/auto_approval) → execution environment is automatically locked to sandbox; direct is only available under unrestricted;
 3. Approving a plan → automatically switches to execute and restores the permission and execution environment from before entering plan;
 4. In Docker mode there is no sandbox/direct distinction — the container is the boundary;
 5. Permission mode, execution environment, and work mode are all **per-conversation** state: a new conversation inherits the current input bar values, and the "default permission mode / default work mode" in Personal Space only affects the first construction.
--- a/demo/content/en/03-conversations.md
+++ b/demo/content/en/03-conversations.md
@ -0,0 +1,76 @@
 # Conversations
 This chapter covers the capabilities of "a single conversation" itself: conversation types, thinking mode, goal mode, and the panel features available during a conversation.
 ---
 ## 1. Conversation Types: Regular vs Multi-Agent
 Chosen when creating a conversation and **immutable after creation**:
 - **Regular conversation (agent)**: you converse with one main agent, which can spawn sub agents in the background as needed to get work done.
 - **Multi-agent conversation**: the main agent is fixed as a **Team Leader**, which does not do the work itself but instead creates multiple role-based sub agents (such as Full-Stack Engineer, UI Operator), assigning tasks among them, collecting reports, and making decisions. Sub agents can also communicate with each other, but every exchange is reported to the Team Leader in sync — there is no "backchannel collusion".
 Where to switch: the conversation type selector to the right of `+` on the bottom row of the input bar when the conversation is empty; the sidebar's list filter determines which type of conversations you see in the list.
 For the full multi-agent playbook, see the "Agent Capabilities" chapter.
 ## 2. Thinking Mode and Reasoning Effort
 Two independent switches, both scoped to the current conversation:
 - **Thinking mode**: `fast` / `thinking`. Fast mode prioritizes response speed and skips the reasoning process; Thinking mode uses a reasoning model for the whole conversation. Switchable in the input bar; a default can be set in Personal Space.
 - **Reasoning effort**: a `Default / Low / Medium / High` slider (only appears when `reasoning_effort: true` is set in the model configuration). "Default" means no intensity is specified and the API's own default behavior is used; dragging the slider adjusts the reasoning depth level in real time.
 > A model's multimodal capability (whether it can send images/videos) is determined by the `multimodal` field of that model in `custom_models.json`; the available thinking mode options are determined by `reasoning_capability`.
 ## 3. Goal Mode (Beta)
 > ⚠️ Goal Mode is a **beta feature**: the mechanics are fully usable, but edge cases (token accounting during concurrent conversations, recovery from abnormal interruptions, etc.) are still being polished. Please use it with these expectations in mind and report any issues.
 In a regular conversation, the AI stops after completing the one round of tasks you assigned. **Goal Mode** makes the AI **keep working round after round automatically** toward a long-term goal, until the goal is achieved or the limit is hit.
 **How to use**:
 1. In the input bar `+` menu → "Goal Mode", entering the "ready" state;
 2. Your next message is treated as a **goal** (rather than a regular task);
 3. The AI works continuously toward the goal: after each round it self-evaluates "is the goal achieved?", and if not, it proceeds to the next round;
 4. It stops when the goal is achieved, a limit is hit, or you cancel manually.
 **Stopping conditions** (configurable in Personal Space, multiple selectable):
 - `max_turns`: at most N automatic additional rounds (has a default value, adjustable);
 - `max_tokens`: cumulative (input + output) token cap, disabled by default. Note that this figure is **workspace-level** and approximate when multiple conversations run concurrently.
 **Goal review**: an optional goal-review agent (the `goal_review` entry on the "Review Agents" page in Personal Space) with two review modes:
 - `readonly` (default): the review agent reads the conversation content only to judge goal progress;
 - `active`: it is allowed to run read-only commands for evidence (for example, checking whether a file was actually generated) before drawing conclusions.
 Goal state is persisted independently per conversation (`goal_states/<conversation ID>.json`); switching conversations, compressing context, or restarting the service never loses goal progress.
 ## 4. Conversation Panels: Recap / Usage / Live Terminal
 Three panel-style features in the input bar `+` menu (they are information panels only and **unrelated to the security mechanisms**):
 - **Conversation recap**: opens a recap view of the current conversation, letting you review what was done in this conversation along a timeline.
 - **Usage stats**: a context and token usage panel showing the current conversation's context occupancy and cumulative consumption.
 - **Live terminal**: opens a live terminal panel where you can directly watch the terminal session the AI is currently executing — which command it is running and what the output is. This is an observation window, not a security boundary; for real security controls, see the "Execution & Security" chapter.
 ## 5. Conversation Management
 - **Search**: the search box at the top of the sidebar retrieves conversations by title and content.
 - **Flat / Grouped views**: the sidebar can lay out all conversations flat, or group them by workspace (Personal Space → "Appearance & Display" → sidebar grouping). In grouped mode, workspaces can be pinned and sorted.
 - **Type filter**: the type switcher in the sidebar (Regular / Multi-agent) determines which type of conversations appear in the list.
 - **New conversation button behavior**: configurable in Personal Space — clicking `+` either "navigates to a blank new conversation page" (route) or "immediately creates an empty conversation" (blank).
 - **Auto title**: enabled by default; a title is generated automatically after the first round. Can be disabled in Personal Space.
 ## 6. Conversation Display Modes
 Personal Space → "Appearance & Display" provides three message-stream display modes:
 - **Traditional list**: all messages laid out flat;
 - **Stacked animation**: intermediate blocks such as tool calls are stacked and collapsed, keeping the main thread of the conversation cleaner;
 - **Minimal mode** (default): the most restrained display, showing only the essentials.
 There are also "Full info / Condensed info" controls for how much condensed messages expand, as well as display switches such as the assistant's status avatar (give it a poke for an easter egg).
--- a/demo/content/en/04-input-context.md
+++ b/demo/content/en/04-input-context.md
@ -0,0 +1,89 @@
 # Input & Context
 This chapter covers the two menus in the input bar, file references, uploads, and Astrion's context management system—including the correct use of compression mechanisms.
 ---
 ## 1. `+` Quick Menu (Full Feature List)
 Click `+` on the left side of the input bar to open it. Here's the full list of features:
 | Feature | Description |
 |------|------|
 | New conversation | Start a new conversation (equivalent to `new` / `clear`) |
 | Upload file | Select a local file to upload into the workspace |
 | Send image / Send video | Attach to the message; **disabled when the current model does not support multimodality** (depends on the `multimodal` config) |
 | Compress conversation | Manually trigger a one-time context compression |
 | Select AgentSkill | Insert a skill reference (equivalent to typing the `//` shortcut) |
 | Workflow | Activate a workflow so the agent progresses through a predefined flow |
 | Conversation type | Switch between "Agent / Multi-agent" on an empty conversation (immutable after creation) |
 | Switch work mode | plan / ask / execute |
 | Switch theme | Classic / Light / Dark |
 | Conversation review | Open the review for the current conversation |
 | Usage statistics | Context and token usage panel |
 | Goal mode | Toggle goal mode (Beta, see the "Conversation" chapter) |
 | Personal settings | Open Personal Space |
 | Live terminal | Open the live terminal panel |
 | Switch model | Choose the model used by this conversation |
 | Thinking mode | Switch between fast / thinking |
 | Permission mode | Switch between readonly / approval / auto / unrestricted |
 | Network permission | Restricted / Fully open (also adjustable in plan mode) |
 | Execution environment | sandbox / direct (host mode only) |
 | Switch workspace / project | Switch the workspace bound to the current conversation |
 | Version control | Turn version control on/off for this conversation |
 | Git status bar | Show/hide the Git status bar above the input bar |
 | Path authorization | View and manage sandbox path authorization |
 | Approval panel | View approval records |
 ## 2. `/` Slash Menu
 Type `/` in the input box to trigger the slash shortcut menu, which lets you quickly filter and jump to a category of options by keyword. It currently supports 12 categories: AgentSkills (`//` shortcut), workflow, theme, permission mode, execution environment, model, thinking mode, network permission, work mode, workspace, conversation type, etc.
 Typical usage: `/skill` to pick a skill, `/workflow` to pick a workflow, `/model` to switch models—faster than browsing the `+` menu.
 ## 3. `@` File References
 Type `@` to bring up the file menu and insert a reference to a file/directory from the workspace. Referenced files are provided to the agent as context, which is ideal for "discuss this file" scenarios. Image file references are handled according to multimodality capabilities.
 ## 4. Context Compression: Shallow vs. Deep
 Every long conversation eventually hits the model's context limit. Astrion provides two levels of automatic compression plus manual compression:
 ### Shallow compression (off by default)
 - Mechanism: replaces earlier **tool call results with placeholders** (keeping the most recent N tool results uncompressed), freeing up space immediately.
 - Trigger: fires by default at 80k accumulated tokens (configurable), with additional fine-tuning parameters such as "every N tool calls", "at most N replacements per round", and "keep tool results from the last N user inputs uncompressed".
 - ⚠️ **Important trade-off: shallow compression modifies the history message content, which breaks the provider-side context cache (prompt cache)**—the requests in the rounds after compression will miss the cache, showing up as slower responses and higher costs. This is why it is off by default.
 ### Deep compression (on by default, recommended)
 - Mechanism: performs a **deep summarization** of the whole history; the old context is wholly replaced by a condensed summary so the conversation continues lightweight.
 - Output form is configurable (`deep_compress_form`): `file`—the summary is written to a file, read back at any time when needed (default); `inject`—the full summary is injected directly into the context.
 - Trigger: 150k tokens by default.
 ### The 80% rule for custom thresholds (follow it)
 If you customize the compression trigger threshold, **set it to at least 80% of the model's actual usable context**.
 For example, if a model's actual context is 128k, the trigger threshold should not be lower than roughly 102k. Setting the threshold too low triggers compression frequently: it wastes tokens, repeatedly breaks the context cache, and makes the AI lose detail memory prematurely. Getting the conversation to "fill the window before compressing" is the most cost-effective use.
 > The model's actual context window is determined by the `context_window` of that model in `custom_models.json`; note the difference between "nominal context" and "actual usable context" (some APIs reserve space for output).
 ### Manual compression
 `+` menu → "Compress conversation" can be triggered manually at any time. It's useful when you anticipate starting a new topic and want to proactively free up space.
 ## 5. Context Injection Features
 These features affect the context automatically carried in every round of conversation; they are all configured in Personal Space:
 - **Recent conversation hints** (off by default): when enabled, a new conversation automatically injects a summary of the most recent N historical conversations into the context (N is configurable, 1–30, default 10). Good for continuous workflows like "I've been working on the same project recently"; combine it with the "conversation continuity" personalization setting.
 - **AGENTS.md auto-injection** (off by default): when enabled, the AGENTS.md in the project root is automatically injected into the context, so the AI always works with the project conventions.
 - **Project memory index injection**: the AI's project memory index is injected at most 20 entries by default (starting at 5, settable to unlimited). Memory content is actively accumulated by the AI during work.
 - **Skill hints** (off by default): dynamically suggests potentially relevant skills based on the current task.
 ## 6. Uploads & Multimodality
 - **Upload file**: goes into the workspace; the AI can read and process it later;
 - **Send image/video**: goes directly into the multimodal context with the message;
 - Image compression tiers (Personal Space): `original / 1080p / 720p / 540p`, default original. When sending many large images in a long conversation, consider a lower tier to save context.
--- a/demo/content/en/05-execution-security.md
+++ b/demo/content/en/05-execution-security.md
@ -0,0 +1,86 @@
 # Execution & Security
 This chapter covers how Astrion executes AI-initiated actions safely: the actual behavior of sandbox execution, path authorization, and the approval mechanism. For the four conceptual switches (deployment / permission / execution environment / work mode), see the "Core Concepts" chapter first; this chapter focuses on concrete behavior and day-to-day management.
 > Scope note: the "live terminal" is just an observation panel and is unrelated to the security mechanisms; see the "Conversation" chapter.
 ---
 ## 1. How Commands Are Executed
 ### run_command: two-phase execution
 Take the default recommended `approval` mode as an example. The actual journey of a shell command initiated by the AI is:
 1. **It executes first with read-only identity**—can read but not write (host mode relies on the OS sandbox; docker mode relies on a non-privileged user inside the container);
 2. If the command does not touch any write operation, the result is returned directly, fully transparent;
 3. If it triggers a permission denial (writing files, modifying the system), **it automatically escalates into an approval request to you**;
 4. After you approve, **only this one command** is retried with writable identity; if you reject it or the request times out, it is not executed at all;
 5. The AI receives only the final result; the intermediate process never disturbs its reasoning.
 `auto_approval` mode replaces the approver in step 3 with an auto-approval agent; `unrestricted` mode skips approval and executes directly; in `readonly` mode, write requests are rejected outright. Note that approval **only escalates this one write—it does not expand the read scope**—the only way to read files outside the workspace is path authorization (see section 2).
 ### Terminal sessions: identity pinned, switching closes them
 The read/write identity of persistent terminal sessions (terminal family of tools) is **pinned** at startup according to the current permission tier, execution environment, and sandbox policy: under restricted tiers (readonly/approval/auto_approval) the terminal runs with read-only identity and writes inside the terminal are denied directly by the system (EPERM); only under `unrestricted` is the identity writable. When you **switch the execution environment (sandbox ⇄ direct), switch the permission tier between restricted and unrestricted, or switch workspace or container**, existing terminal sessions are **closed immediately**—they never keep running with the old identity, and subsequent operations run in a freshly spawned session under the new policy. This also means: don't switch these toggles while running long tasks, because the task terminates together with the session.
 ### Sub agents and background commands
 Sub agent terminal processes also go through the execution environment policy: under sandbox they are launched via the host sandbox; under direct they launch directly on the host; in docker mode they execute inside the container. Background commands (`run_in_background`) go through the same read-only/writable sandbox determination as foreground commands—**going to the background does not bypass permissions**.
 ## 2. Day-to-Day Management of Path Authorization
 Entry point: input bar `+` menu → "Path authorization".
 - **Readable and writable paths**: the AI's full working scope, typically your project directory;
 - **Read-only paths**: allow the AI to consult but not modify, e.g., reference docs, online config samples, and other projects' source code.
 Suggested practices:
 1. Keep authorization minimal—only add the directories the current task needs;
 2. Never add sensitive directories (`~/.ssh`, key stores, system directories) under any category;
 3. Adjust promptly when the nature of a task changes. Authorization takes effect immediately (except for new terminal sessions, see above).
 ## 3. Network Permission
 An independent group in the input bar permission menu:
 - **Restricted** (default): loopback only; the AI cannot reach the external network—suited for purely local tasks and prevents data exfiltration;
 - **Fully open**: allows outbound/inbound connections—enable it when the AI needs to search the web, call external APIs, or install dependencies.
 Network permission is independent of the file sandbox and can also be adjusted in plan mode.
 ## 4. Approval Panel
 Entry point: `+` menu → "Approval panel". Here you can see the approval history: which commands/writes were submitted for approval, who approved them (human or the auto-approval agent), and the outcome. In `auto_approval` mode, if you don't want the panel to pop up automatically, there is a toggle in Personal Space (not auto-opened by default).
 ## 5. Forbidden Command List
 The deployment-level config `forbidden_commands.json` (placed in `<data root>/config/`) can define **command patterns that are absolutely forbidden to execute**. Any match is rejected regardless of permission mode. This is the last line of defense—suitable for locking down commands like `rm -rf /` and `shutdown` on server deployments.
 ## 6. A Word of Caution About direct Mode
 `direct` = commands execute directly on the host, **with no sandbox at all**. It is hard-mutually-exclusive with the restricted tiers (readonly/approval/auto_approval)—only `unrestricted` can select direct, and switching from direct into a restricted tier automatically pushes you back to sandbox. There is exactly one legitimate use case: a command genuinely cannot run inside the sandbox (requires system-level permissions) and there is no alternative. In that case:
 1. First switch the permission tier to `unrestricted`, then temporarily switch to direct;
 2. Switch back to sandbox (and the original permission tier) as soon as the command is done;
 3. Note that after direct is switched on, it **persists and does not revert automatically**—forgetting to switch back means running unprotected long-term.
 ## 7. Current Security State of docker Mode
 In docker mode, the isolation boundary between users is the container itself: each user's terminal runs in an independent container, invisible to each other. The permission constraints **inside** the container are also truly enforced:
 - Under restricted tiers (readonly/approval/auto_approval), run_command, background commands, and persistent terminals all execute as a **non-privileged user (uid 10001)** inside the container—the workspace is owned by root, and writes are denied directly by kernel file permissions, without relying on recognizing command text; after approval, only that one command is retried as root;
 - Prerequisites: the workspace is owned by root, there are no globally writable files, and the container does not mount docker.sock (all satisfied by following the official deployment docs);
 - This enforcement holds only on **Linux hosts**—Docker Desktop on a local macOS machine does not enforce uid file permissions, so don't treat container-internal permissions as a security boundary during local development;
 - Multi-user deployments should combine container resource limits, image minimization, and other standard container security practices.
 ## 8. Security Posture by Platform
 Reiterating the conclusion from the "Core Concepts" chapter, because it directly affects how much you should trust the sandbox:
 - **Windows (WSL2)**: full data isolation is achievable, but WSL2 must be installed first;
 - **macOS (sandbox-exec)**: whitelist read model; both writes and reads can be restricted—processes can by default only read system directories, the workspace, and authorized paths; the trade-off is that top-level file names in the ancestor directories of authorized paths can be listed (file contents remain unreadable);
 - **Linux (bwrap+seccomp)**: writes can be restricted, but the read side is still globally readable, not yet aligned to a whitelist, and **not yet tested in practice**—don't rely on its isolation.
 On any platform, the primary value of the sandbox is **preventing accidental operations**; for genuinely sensitive data, layer path authorization minimization, restricted network, and readonly permissions together for comprehensive protection.
--- a/demo/content/en/06-conversation-assets.md
+++ b/demo/content/en/06-conversation-assets.md
@ -0,0 +1,68 @@
 # Conversation Asset Management
 After the AI modifies files in your workspace, the core questions become "what changed, how do I roll back, and which version is broken". Astrion provides three layers of asset protection: **version control** (conversation-level checkpoints), **modify history** (task-level diffs), and the **Git status bar** (real-time awareness). They are independent of each other and can be layered on top of one another.
 ---
 ## 1. Version Control
 A conversation-level file checkpoint system that gives every round of AI changes a snapshot you can roll back to.
 ### Toggle and Backup Methods
 - Enabled **by default** for new conversations (the default can be changed in Personal Space);
 - A single conversation can be toggled temporarily via the `+` menu → "Version Control";
 - One of two backup methods (choice made in Personal Space):
  - **Shallow backup (default)**: tracks only files edited by the AI via **write_file / edit_file**, backing up the current content automatically before each edit — fast and space-efficient, sufficient for the vast majority of scenarios. ⚠️ Note the boundary: **files changed by the AI through commands run via run_command (such as sed, redirection, script writes) are not within the tracking scope of shallow backup**;
  - **Full backup**: a snapshot of the entire workspace — the most robust, but noticeably slower and more space-hungry on large projects.
 ### Checkpoint Granularity: Per User Message
 - **Each time you manually send a message**, the system records a checkpoint after that message finishes processing, referencing the latest backup version of all tracked files at that time — in other words, the smallest unit you can roll back to is "one manually-sent user message", not a single file edit;
 - Viewing a checkpoint's diff = the difference between that message's snapshot and the previous message's snapshot;
 - **Rolling back** to a checkpoint = restoring all tracked files to their state at that message (overwrite; confirm that current changes are saved elsewhere or committed before rolling back).
 ### Relationship with Other Mechanisms
 - Version control tracks **filesystem state**, which is unrelated to conversation messages;
 - It does not conflict with Git: the AI never commits for you. Version control is another safety net alongside Git, suited to the scenario of "files broke before you had time to commit".
 ## 2. Modify History
 Task-level net modification records, **enabled by default**.
 - After each task round completes, all files edited by the AI in that round are written to disk as a **unified diff** at: `<workspace>/.astrion/modify_history/<conversation ID>/`;
 - One `.diff` file per task; the file name includes a summary of that task's user input and the start time;
 - The "edit summary card" in the conversation shows the list of files edited in that round; clicking it shows the diff. When the card appears is configurable in Personal Space (by default it shows after the work completes; it can also be changed to show in real time during execution).
 ### Manual Recovery with Diff Files
 History files can be operated on directly with git tools:
 ```bash
 cd <workspace>
 git apply <diff-file>     # Redo this change
 git apply -R <diff-file>  # Revert this change
 ```
 Typical scenario: version control was off, Git had no commit, and `git checkout` accidentally overwrote the AI's work — go to modify_history, find the diff for the corresponding task, and `git apply` to recover.
 > This directory is maintained automatically by the system; do not add or remove files in it manually. It can be disabled entirely in Personal Space (when disabled, nothing is written to disk and no prompts are injected).
 ## 3. Git Status Bar
 A status bar above the input bar that shows a real-time summary of the current workspace's Git status (current branch, amount of uncommitted changes, etc.), so you can tell "how dirty the workspace is and how much the AI changed" without leaving the conversation.
 - Shown by default; can be quickly toggled via the `+` menu → "Git Status Bar", with the same setting available in Personal Space;
 - Not shown when the workspace is not a Git repository.
 ## 4. How to Choose Among the Three Layers
 | Need | Layer to use |
 |------|--------|
 | Real-time awareness of workspace changes | Git status bar |
 | Roll back to a point in time in the conversation | Version control |
 | Precisely restore/undo one task round's changes | Modify history diff |
 | Long-term, serious, large-scale development | Still use Git commit — the first three layers are safety nets, not a replacement for version management |
 Recommended practice: for important projects keep "version control on + modify history on + commit regularly"; with all three nets layered, no matter how much the AI churns things up, nothing gets lost.
--- a/demo/content/en/07-agent-capabilities.md
+++ b/demo/content/en/07-agent-capabilities.md
@ -0,0 +1,156 @@
 # Agent Capabilities
 Astrion's agent capabilities fall into five areas: **sub agents** (delegates dispatched by the main agent), **multi-agent conversation** (a team of roles), **workflows** (predefined process templates), **Skills** (specialized capability packs), and **MCP** (external tool integration). This chapter covers how to use and configure each one.
 ---
 ## 1. Sub Agents
 ### What It Is
 A sub agent is an independent executor dispatched by the main agent **within the same process**: it has its own context, its own model configuration, and an independent lifecycle. The main agent uses it to **process mutually independent tasks in parallel** — typical scenarios: researching three technical approaches at once, or organizing documentation while tests run.
 What it is **not** for: sub agents cannot communicate with each other and cannot see the main conversation history, so collaborative tasks (where A's output is B's input) should be executed sequentially or handed to a single sub agent. Code writing/editing tasks are by default handled directly by the main agent.
 ### How to Use
 Usually you don't need to operate directly — tell the main agent "do X and Y for me at the same time" and it will decide on its own whether to split the work into sub agents. Two ways of running:
 - **Foreground (blocking)**: the main agent pauses and waits for it to finish; suited for fast tasks or scenarios where subsequent steps depend on the result;
 - **Background**: the main agent keeps working or chats with you; when the sub agent finishes, the system notifies you automatically.
 You can watch each sub agent's status and output in real time via the **"Sub Agents" pane in the Quick Dock** on the right side of the conversation area (see "Quick Dock").
 ### Lifecycle & Limits
 - States: `running` → `idle` (context is preserved, can continue the conversation) / terminal states (completed / failed / timed out / terminated);
 - Default concurrency limit: **5** (`SUB_AGENT_MAX_ACTIVE`);
 - Default timeout: **180 seconds**; you can specify a longer timeout for an individual task when creating it (1800+ seconds recommended for large-scale analyses);
 - Outputs are conventionally placed under `sub_agent_results/` in the workspace.
 ### Configuration (Model Library)
 Sub agents use a separate model library, `sub_agent_models.json`; see Section 6 of "Quick Start" for configuration. When creating an individual task, the main agent can specify: the model entry, thinking mode, timeout, max rounds, and more. If not specified, the `default_model` entry is used.
 ## 2. Multi-Agent Conversation
 ### What It Is
 A **conversation type** (chosen at creation time and immutable): the main agent is fixed as Team Leader, responsible for understanding your requirements, breaking down tasks, creating and directing a group of **role-assigned sub agents**, and consolidating their outputs.
 ### Role System
 5 preset roles:
 | Role | Responsibility |
 |------|------|
 | Full-Stack Engineer | Frontend/backend implementation, API design, debugging and integration |
 | UI Operator | UI operations and visual verification |
 | Code Reviewer | Code review |
 | Researcher | Research and information gathering |
 | Brainstormer | Brainstorming and idea exploration |
 A role = `role ID + instance number`, with display names like `Full-Stack Engineer_1`; numbers increment within each role.
 **Custom roles**: Personal Space has a role editor (role list → create/edit). A role definition is a Markdown file with metadata:
 ```markdown
 ---
 id: full-stack-engineer      # Role ID
 name: Full-Stack Engineer    # Display name
 description: One-line role summary  # Team Leader assigns tasks based on this
 model: ""                    # Pin a model (empty = sub-agent model library default)
 thinking_mode: thinking      # fast / thinking
 ---
 (The body is the role's system prompt: responsibilities, working principles, constraints...)
 ```
 ### Communication Mechanics (What You Need to Know)
 - Team Leader sends messages to sub agents in two ways: **assigning work** (non-blocking, keeps doing other things) and **asking** (blocking, waits for one round of reply);
 - Sub agents can ask/answer each other, but **all inter-sub-agent communication is reported to the Team Leader in sync**;
 - Every round of a sub agent's output is reported to the Team Leader in real time and shown in the conversation flow; you can jump in at any time to correct course.
 ### When to Use Multi-Agent
 Good fit: a small project that needs "a coder + a code reviewer + a UI runner" working in division of labor; not a fit: tasks a single thread can finish on its own (it only adds coordination overhead).
 ## 3. Workflows
 ### What It Is
 Write a **predefined process** (stages, review gates, branches, ending conditions) into a `WORKFLOW.md` file and save it as a template; once activated, the agent advances strictly stage by stage, reporting to you or a review agent after each stage, and only moves to the next stage after the review passes.
 ### How to Use
 - Activate: `+` menu → "Workflow", or type `/workflow` to choose;
 - Progression: after each stage, the AI reports automatically and moves to the next stage (when the stage includes a review gate, the review agent checks it; a rejection is sent back to the previous stage with remediation feedback);
 - Branches: at a branch point, the AI presents a menu of paths for you to decide;
 - Exit / check progress: ask the AI to exit the workflow or report current progress at any time;
 - Only one workflow can be active in a conversation at a time.
 ### Built-in Workflows
 | Workflow | Purpose |
 |--------|------|
 | bug-fix-triage | Defect triage and fix process |
 | code-review-pipeline | Code review pipeline |
 | feature-development | Full feature development process |
 | research-report | Research report generation process |
 ### Custom Workflows
 Write one following the `WORKFLOW.md` format of the built-in workflows and drop it into the workflow library directory. It's recommended to just ask the AI in natural language, e.g. "use the workflow-authoring skill to write me an xx workflow" — the system has built-in authoring guidelines and format validation, and the finished workflow is archived automatically and ready to activate.
 Workflow reviews are performed by the **workflow review agent** (`workflow_review`); see "Review Agents" below for configuration.
 ## 4. Skills (Skill Packs)
 ### What It Is
 A Skill = a folder + a `SKILL.md` file (a skill specification with metadata). It captures the experience of "how to do a certain type of task"; when the AI encounters a matching scenario, it reads the skill before acting — like giving the AI an on-the-job training manual.
 ### Built-in Skills (12)
 `agent-build-standard` (Agent architecture guide), `agents-md-writer` (writing AGENTS.md), `docx` (Word documents), `pptx` (PPT), `frontend-design` (frontend design), `ui-aesthetic-design` (UI aesthetics), `skill-creator` (creating new Skills), `workflow-authoring` (writing workflows), `run-command-guide` (command execution guidelines), `terminal-guide` (terminal usage guidelines), `sub-agent-guide` (sub agent guidelines), `mcp-tool-config` (MCP self-service configuration).
 ### How to Use
 - Insert a reference: type `//` or use the `+` menu → "Select AgentSkill" to insert a skill reference into your message;
 - Enable/disable: manage the enabled list on the "Tools & Skills" page in Personal Space;
 - **Strict-guard toggles** (all off by default): you can require "read terminal-guide before using the terminal", "read the guidelines before using run_command in foreground/background mode", and "read sub-agent-guide before dispatching a sub agent" — useful during the learning phase to prevent misuse, and can be turned off once you're experienced;
 - **Skill suggestions** (off by default): dynamically suggests potentially relevant skills based on the current task.
 ### Custom Skills
 Just tell the AI "capture today's process as a skill" and it will create, validate, and archive it following the `skill-creator` guidelines, ready to reuse afterwards. User skills are stored in `.astrion/skills/` in the workspace.
 ## 5. MCP Tool Extensions
 Connect external tool services (databases, browser automation, third-party SaaS...) via [Model Context Protocol](https://modelcontextprotocol.io); after connecting, new tools of the form `mcp__service name__tool name` appear in the AI's tool list.
 - **Config file**: `<data root>/<mode>/data/mcp_servers.json` (can be overridden with `MCP_SERVERS_FILE`);
 - **Master switch**: `MCP_TOOLS_ENABLED` (on by default);
 - Protocol version `2025-06-18`, default 25-second timeout for tool discovery/invocation;
 - **Host mode feature**: you can directly ask the AI to "configure xxx MCP service for me" — the built-in `mcp-tool-config` skill guides it to write the config and make it take effect on its own.
 ## 6. Review Agents (Three)
 Three independent AIs that check key milestones on your behalf, all configured on the "Review Agents" page in Personal Space; **they reuse the sub agent model library**:
 | Review Agent | When It Steps In |
 |------------|----------|
 | `auto_approval` Auto-approval | Under the `auto_approval` permission mode, auto-approves when a command is about to write outside the sandbox or triggers a permission denial |
 | `goal_review` Goal review | In goal mode, evaluates whether each round of work achieved the goal |
 | `workflow_review` Workflow review | At workflow review gates, decides whether to pass or reject |
 Each can be configured with: `model` (leave empty for the model library default), `thinking` (thinking mode), `timeout_seconds`, `max_rounds`, `max_command_timeout`.
 > Tip: for review agents, choose **cheap but stable** models — they are called frequently with fixed task patterns, so flagship models are unnecessary.
 ## 7. Combinatorial Examples
 - **Multi-agent + workflow**: after activating the feature-development workflow, the Team Leader directs the role team through stage-by-stage delivery per the process;
 - **Sub agents + Skills**: insert `//frontend-design` before a research task, and the sub agent works with the design guidelines in mind;
 - **MCP + Quick Dock**: when a browser-automation MCP runs a long task, watch real-time progress in the "Background Commands" pane.
--- a/demo/content/en/08-quick-dock.md
+++ b/demo/content/en/08-quick-dock.md
@ -0,0 +1,33 @@
 # Quick Dock
 A column of floating windows on the right side of the conversation area. It gathers the "interactive artifacts produced during a task" in one place, so you can keep an eye on everything without scrolling through the message stream.
 ---
 ## 1. The Five Windows
 From top to bottom:
 | Window | What it shows | Typical actions |
 |------|----------|------|
 | **Workflow** | The currently active workflow: which stage it is at, review status, pending branches | Check process progress; use alongside branch selection |
 | **Todos** | The AI-created task list (todo): completion status of each item | See how far the AI's execution plan has advanced |
 | **Sub agents** | Running/idle sub agent instances: status, what they are currently doing | Open details to see the output timeline; use the ⋯ menu to **force-close** an out-of-control instance |
 | **Background commands** | Command tasks running in the background: status, elapsed time | Open details to see the full output; force-close from the ⋯ menu |
 | **File records** | Files the AI has edited or created in the current task | ⋯ menu: **download** / **open in file manager** (host mode) / **copy path** |
 ### Details panel
 - Click a sub agent / background command entry → opens the **runner details panel**: outputs and tool calls are interleaved on a real timeline; you can force-close when something runs out of control;
 - Click a file entry → opens the **file preview panel**: view the file content directly. Long lines scroll horizontally by default; in Personal Space you can switch to wrapping by panel width.
 ## 2. Expand and Collapse
 - **Auto-expand when there is content** (default): when any window has content, the whole column expands automatically; when all are empty, it collapses into a thin edge strip that takes up no space;
 - In Personal Space you can switch to **manual expand only** (`quick_dock_auto_expand`), or **hide entirely** (`hide_quick_dock`).
 ## 3. Usage Tips
 - **Watch for runaway processes**: when a sub agent or background command misbehaves, don't shout into the conversation — just use ⋯ → force close;
 - **Watch progress**: during long tasks, the Todos window plus the Sub agents window is your project board;
 - **Collect artifacts**: when the task ends, batch-download or jump to the directory from the File records window — much faster than hunting through cards in the message stream.
--- a/demo/content/en/09-settings.md
+++ b/demo/content/en/09-settings.md
@ -0,0 +1,154 @@
 # Personal Space Settings: The Complete Guide
 Personal Space (input bar `+` menu → "Personal Settings") has 12 tabs in total (admins get 1 more). This chapter explains **every page and every item** — what each setting does, its default value, and when to use it. Anything that can't be explained in one sentence on the settings page is covered in full here.
 > Convention: "default" refers to the default value baked into the code. If you've used the `setup.sh` wizard, some defaults may have been overridden by your choices in the wizard.
 ---
 ## 1. General
 | Setting | Default | Description |
 |--------|------|------|
 | Auto-generate title | On | Automatically generates a conversation title after the first round. When off, new conversations keep the "New Conversation" placeholder name and need manual renaming |
 ## 2. Personalization
 This page decides "what personality the AI adopts when interacting with you".
 | Setting | Default | What It Does & When to Use |
 |--------|------|------------|
 | Enable personalization | Off | Master switch for this page. When off, none of the settings below are injected into prompts |
 | AI's self-name | Empty | What the AI calls itself (≤20 characters), e.g. "Xiao A" |
 | How it addresses you | Empty | What the AI calls you (≤20 characters) |
 | Occupation | Empty | Your occupation (≤20 characters). When filled in, the AI adjusts the depth of its explanations to your background — developers get technical details, business folks get plain language |
 | Tone | Empty | 8 presets: conversational / humorous / blunt / encouraging / poetic / corporate / unconventional / empathetic |
 | Notes | Empty | **The most powerful item**: up to 10 long-term instructions, each up to 2000 characters, injected into every round of conversation. Good for persistent preferences like "always answer in Chinese", "write code comments in English", or "I'm colorblind — avoid red-green palettes in charts" |
 | Communication style | Standard | Standard AI style / human-like chat style / auto (switches by scenario) |
 | Conversation continuity | Medium | High: actively revisits past conversations and memories; medium: balanced; low: each round stands on its own as much as possible. **If you've turned on "Recent conversation hints" but feel the AI keeps bringing up old topics irrelevantly, lower this setting** |
 ## 3. Model & Thinking
 | Setting | Default | Description |
 |--------|------|------|
 | Default model | First visible item in the model library | The model used by default for new conversations; any registered model in the library can be chosen |
 | Default thinking mode | Thinking | fast / thinking. Thinking mode gives higher quality; Fast mode responds faster |
 | Default reasoning effort | Default (no parameter passed) | default / low / medium / high; only takes effect if the model supports `reasoning_effort` |
 > The "defaults" here only affect **new conversations**; for existing conversations, adjust individually with the switcher in the input bar.
 ## 4. Appearance & Display
 | Setting | Default | Description |
 |--------|------|------|
 | Theme | Classic | Classic (warm cream + warm orange) / Bright (cool white + near black) / Night (neutral grays) |
 | Message flow display mode | Minimal mode | Traditional list / stacked animation / minimal mode; minimal mode has an extra "limit max height when expanded" toggle (on by default) |
 | Condensed message display | Full info | Full original content / one-line summary |
 | Hide stacked block dividers | Off | Hides the dividers between stacked blocks for a cleaner look |
 | Show assistant status avatar | On | The status avatar in the conversation area (poke it — there's an easter egg) |
 | Show Git status bar | On | The Git status bar above the input bar |
 | Show custom names | On | Displays the self-name/address name you configured in the UI |
 | Enhanced tool display | On | Structured rendering of tool results; turning it off makes output closer to raw |
 | Auto-open terminal panel | — | Automatically expands the live terminal panel for terminal tasks |
 | Auto-expand Quick Dock | On | Auto-expands Quick Dock when it has content; when off, it can only be opened manually |
 | Hide Quick Dock | Off | Disables Quick Dock entirely |
 | Real-time edit summary | Off | On: shows an edit summary card as the AI edits; off: shows a consolidated summary after each round of work |
 | Wrap file preview | Off | On: the preview panel wraps lines to fit the width; off: long lines scroll horizontally |
 | Group sidebar by workspace | Off | Groups the conversation list by workspace/project; grouping mode supports pinning and sorting workspaces |
 | New conversation button behavior | Navigate to blank page | route: navigate to a blank new-conversation page / blank: immediately create an empty conversation |
 ## 5. Workspace & Permissions
 | Setting | Default | Description |
 |--------|------|------|
 | Default permission mode | Approval | The initial permission mode for new terminals; see "Core Concepts" for the behavior of all four levels |
 | Default work mode | Plan | The initial work mode for new terminals: Plan / Ask / Execute |
 | Hide workspace by default | Off | Collapses workspace info in the UI by default |
 | Auto-inject AGENTS.md | Off | On: each round automatically carries the project-root AGENTS.md, so the AI always works with the project standards in mind. Recommended for long-running projects |
 | Track modifications | On | Writes the net diff of changes to `.astrion/modify_history/` after each round. When off, nothing is written and no prompt is injected |
 | Version control on by default for new conversations | On | Keep this on — it's your file safety net |
 | Version control backup method | Shallow backup | Shallow: only backs up files edited by the AI; full: snapshots the entire workspace (use with care on large projects) |
 | Goal review mode | Read-only conversation | How goal mode is reviewed: readonly — judges from the conversation only / active — allows the review agent to run read-only commands for evidence |
 | Goal max rounds | Has a default | The cap on auto-continuing rounds in goal mode |
 | Goal token ceiling | Disabled | Stops when cumulative input + output tokens reach the limit (1k–100M). Note this is a workspace-level approximate count |
 ## 6. Context
 This page is key to long-conversation quality; **read Section 4 of "Input & Context" before changing anything**.
 | Setting | Default | Description |
 |--------|------|------|
 | Recent conversation hints | Off | On: new conversations automatically receive summaries of the most recent N historical conversations |
 | Number of recent conversations | 10 | The N in the item above; 1–30 |
 | Project memory index limit | 20 entries | Max number of project memory index entries injected (≥5; can be set to unlimited) |
 | Auto shallow compression | Off | ⚠️ **breaks the context cache** — see "Input & Context". Not recommended |
 | Shallow compression trigger tokens | 80000 | When customizing, **at least 80% of the model's actual usable context** |
 | Shallow compression: keep recent tool results | 15 | The most recent N tool results are not compressed |
 | Shallow compression: keep post-user tools | 3 | Tools after the most recent N user inputs are not compressed |
 | Shallow compression: max replacements per round | 10 | Max number of tool results replaced in a single compression |
 | Shallow compression: tool call interval | 10 | Checks whether to trigger every N tool calls |
 | Auto deep compression | On | Recommended to keep on |
 | Deep compression trigger tokens | 150000 | Follows the same 80% rule |
 | Deep compression output form | Generate file | file: writes the summary to a file for on-demand use (recommended) / inject: injects the full summary directly |
 ## 7. Tools & Skills
 | Setting | Default | Description |
 |--------|------|------|
 | Silently disable tools | On | When a tool is disabled, no prompt is injected into the model — cleaner context |
 | Hide tool approval panel | On | Under the auto_approval mode, doesn't auto-pop the approval panel to bother you; off: any approval request pops up immediately |
 | Tool intent description | On | Shows a brief "what it intends to do" note on tool call cards; turning it off makes the message flow more compact |
 | Skill suggestions | Off | Dynamically suggests possibly relevant Skills based on the current task |
 | Strict guard: terminal | Off | On: the AI must read the terminal-guide guidelines before using terminal tools |
 | Strict guard: sub agents | Off | On: must read sub-agent-guide before dispatching sub agents |
 | Strict guard: foreground commands | Off | On: must read the guidelines before run_command in foreground mode |
 | Strict guard: background commands | Off | On: must read the guidelines before run_command in background mode |
 | Enabled Skills list | All | Choose which Skills can be used |
 | Disabled tool categories | None | Disables tools by category (e.g. disabling the web-search category) |
 The four "strict guards" are guardrails for beginners: they force the AI to read usage guidelines before touching high-risk tools, significantly reducing the misoperation rate; once you're experienced, turning them off saves tokens.
 ## 8. Files & Images
 | Setting | Default | Description |
 |--------|------|------|
 | Image compression level | Original | Original / 1080p / 720p / 540p. For long conversations with many large images, consider lowering the level to save context |
 ## 9. Data Management
 A read-only **usage statistics** page: cumulative input/output tokens, total number of conversations, user message count, and tool call count, with manual refresh. It answers questions like "how many tokens did I burn this month".
 ## 10. Speech Model
 Download management for the on-device speech recognition model (SenseVoice int8): about 228MB, **runs locally on the phone only — no network required**, supports mixed Chinese-English speech and automatic punctuation. The page shows download status (not downloaded / downloading with percentage / downloaded / incomplete download), and supports re-download or deletion. This feature targets the Android client.
 ## 11. Sub Agents
 The multi-agent **role editor**: role list, create role, edit role. See Section 2 of "Agent Capabilities" for role fields and format. The 5 preset roles serve as reference, and custom roles are ready to use as soon as you edit them.
 ## 12. Review Agents
 A unified configuration page for the three review agents (auto-approval / goal review / workflow review), each configurable with:
 | Field | Description |
 |------|------|
 | Model | An entry name from the sub agent model library; **leave empty = use `default_model` from the library** |
 | Thinking mode | fast / thinking |
 | Timeout | Max wait time for a single review |
 | Max rounds | Cap on the review agent's own working rounds |
 | Command timeout | Per-command timeout for verification commands run during a review |
 Configuration advice: review tasks follow fixed patterns and are called frequently, so cheap, stable models are enough — no need for flagship ones.
 ## 13. Admin (Visible to Admins Only)
 An admins-only page: user and policy management (the `admin/`-related interfaces). Regular users can't see this page.
 ---
 ## Appendix: How Settings Take Effect
 - All settings are stored in `personalization.json` in the data directory, isolated per user;
 - "Default XX" settings only affect newly created objects (new conversations/new terminals), never existing ones;
 - Display-related settings (theme, display mode, etc.) take effect immediately;
 - Settings that involve prompt injection (personalization, notes, AGENTS.md injection, etc.) take effect from the next round of conversation.
--- a/demo/content/en/10-cli.md
+++ b/demo/content/en/10-cli.md
@ -0,0 +1,36 @@
 # CLI (In Development)
 > ⚠️ The CLI is currently in a **development state under rewrite**; functionality and stability are defined by the Web client. This article only describes its current form, and the behaviors listed may change later.
 ---
 ## 1. What It Is
 A conversation client in the terminal: a TUI built with **React 19 + Ink 6 + TypeScript** that lets you talk to Astrion without opening a browser.
 Key point: the CLI is **not a standalone agent runtime**—it connects to the Astrion Web service running locally on your machine (default `127.0.0.1:8091`). All conversations, tool execution, and permission control go through the backend; the CLI is just a lighter interactive interface.
 ## 2. Startup
 ```bash
 npm --prefix cli install   # install dependencies on first use
 npm run cli                # start; automatically connects to the local 8091 service
 ```
 On startup it clears the screen, connects to the local service, creates a new session, and pins the input area to the bottom. If the current directory is not inside any authorized workspace, it first asks whether to add it as a workspace.
 ## 3. Current Capabilities and Limits
 - Basic conversation, streaming output, tool call display;
 - `/` command system (in design; see the repo's `docs/cli_slash_commands_spec.md`);
 - Thinking content is collapsed by default, showing only "thinking / thinking done";
 - Multimodality, Quick Dock, version control, and other Web-side capabilities are **not yet aligned** in the CLI—use the Web client when you need the full feature set.
 ## 4. For Developers
 ```bash
 npm run cli:typecheck   # type checking
 npm run cli:build       # build (artifacts provide the agents / agents-cli commands)
 ```
 The CLI code lives in `cli/src/` (`App.tsx`, `components.tsx`, `eventMapper.ts`, `api.ts`); contributions welcome.
--- a/demo/docs.html
+++ b/demo/docs.html
@ -22,20 +22,20 @@
    <nav class="topnav">
      <!-- 「首页」返回链接桌面端隐藏（brand 即返回入口），仅移动端显示（site.css 移动端隐藏全部
           topnav-link，docs.css 里用更高优先级选择器单独放行它） -->
-      <a class="topnav-link docs-back-home" href="/">首页</a>
+      <a class="topnav-link docs-back-home" href="/" data-i18n="docs.home">首页</a>
-      <a class="topnav-link" href="/#features">功能</a>
+      <a class="topnav-link" href="/#features" data-i18n="nav.features">功能</a>
      <a class="topnav-link" href="/#faq">FAQ</a>
-      <a class="topnav-link docs-nav-current" href="/docs.html" aria-current="page">文档</a>
+      <a class="topnav-link docs-nav-current" href="/docs.html" aria-current="page" data-i18n="nav.docs">文档</a>
      <a class="topnav-link" href="https://github.com/JOJO6618/astrion" target="_blank" rel="noopener">GitHub</a>
-      <a class="btn btn-primary btn-sm" href="https://github.com/JOJO6618/astrion" target="_blank" rel="noopener">Try Astrion</a>
+      <a class="btn btn-primary btn-sm" href="https://agent.cyjai.com">Try Astrion</a>
    </nav>
  </div>
 </header>
 <div class="docs-layout">
  <aside class="docs-side">
-    <p class="docs-side-title">文档</p>
+    <p class="docs-side-title" data-i18n="docs.side">文档</p>
-    <nav class="docs-nav" id="docsNav" aria-label="文档目录"></nav>
+    <nav class="docs-nav" id="docsNav" data-i18n-aria="docs.navAria" aria-label="文档目录"></nav>
  </aside>
  <main class="docs-main">
    <article class="docs-content" id="docsContent" aria-live="polite"></article>
@ -43,6 +43,7 @@
 </div>
 <script src="/site-assets/vendor/marked.min.js"></script>
 <script src="/site-assets/i18n.js"></script>
 <script src="/site-assets/docs.js"></script>
 </body>
 </html>
--- a/demo/site-assets/docs.css
+++ b/demo/site-assets/docs.css
@ -61,6 +61,28 @@ body {
  font-weight: 560;
 }
 /* 语言切换：目录末尾成员（桌面端竖排项同风格，上方留白分隔；移动端见 @media chips 化） */
 .docs-lang-toggle {
  display: block;
  width: 100%;
  margin-top: 14px;
  height: 36px;
  padding: 0 12px;
  background: none;
  border: 0;
  border-radius: 6px;
  font-family: inherit;
  font-size: 14px;
  color: var(--text-3);
  text-align: left;
  cursor: pointer;
  transition: color 0.15s ease, background-color 0.15s ease;
 }
 .docs-lang-toggle:hover {
  color: var(--text-1);
  background: rgba(168, 180, 210, 0.06);
 }
 /* ───── 右侧内容 ───── */
 .docs-content {
  max-width: 760px;
@ -252,6 +274,20 @@ body {
    background: rgba(168, 180, 210, 0.14);
    border-color: var(--line-strong);
  }
  /* 语言切换 = chips 条尾部成员（与 chip 同高同形） */
  .docs-lang-toggle {
    flex: none;
    display: inline-flex;
    align-items: center;
    width: auto;
    margin-top: 0;
    height: 32px;
    padding: 0 12px;
    background: var(--bg-panel);
    border: 1px dashed var(--line-strong);
    border-radius: 999px;
    white-space: nowrap;
  }
  /* 内容防超宽：长行断词；表格 display:block 后块内横滚（不顶破页面） */
  .docs-content { max-width: 100%; overflow-wrap: break-word; }
--- a/demo/site-assets/docs.js
+++ b/demo/site-assets/docs.js
@ -1,6 +1,8 @@
 /* ═══════════ 文档页逻辑（docs.html） ═══════════
   hash 路由（#01-quick-start 可直链某篇）+ fetch content/*.md + marked 前端渲染。
-   文档为站点自有的可信 markdown，无需注入消毒。 */
+   文档为站点自有的可信 markdown，无需注入消毒。
   多语言：与主页同一 localStorage（astrion_site_locale）；英文版在 content/en/ 同文件名，
   缺失时回退中文；目录末尾附语言切换按钮（桌面端目录底部 / 移动端 chips 条尾部）。 */
 (function () {
  'use strict';
@ -9,33 +11,87 @@
     切篇/刷新统一回顶，行为可预期。 */
  if ('scrollRestoration' in history) history.scrollRestoration = 'manual';
-  /* 目录标题与 md 一级标题语义一致（08/09 目录用简称，正文原标题保留） */
+  /* 目录标题与 md 一级标题语义一致（08/09 目录用简称，正文原标题保留）；
     titleEn 为英文目录标题 */
  var DOCS = [
-    { id: '01-quick-start', title: '快速上手', file: '01-quick-start.md' },
+    { id: '01-quick-start', title: '快速上手', titleEn: 'Quick Start', file: '01-quick-start.md' },
-    { id: '02-core-concepts', title: '核心概念', file: '02-core-concepts.md' },
+    { id: '02-core-concepts', title: '核心概念', titleEn: 'Core Concepts', file: '02-core-concepts.md' },
-    { id: '03-conversations', title: '对话', file: '03-conversations.md' },
+    { id: '03-conversations', title: '对话', titleEn: 'Conversations', file: '03-conversations.md' },
-    { id: '04-input-context', title: '输入与上下文', file: '04-input-context.md' },
+    { id: '04-input-context', title: '输入与上下文', titleEn: 'Input & Context', file: '04-input-context.md' },
-    { id: '05-execution-security', title: '执行与安全', file: '05-execution-security.md' },
+    { id: '05-execution-security', title: '执行与安全', titleEn: 'Execution & Security', file: '05-execution-security.md' },
-    { id: '06-conversation-assets', title: '对话资产管理', file: '06-conversation-assets.md' },
+    { id: '06-conversation-assets', title: '对话资产管理', titleEn: 'Conversation Assets', file: '06-conversation-assets.md' },
-    { id: '07-agent-capabilities', title: '智能体能力', file: '07-agent-capabilities.md' },
+    { id: '07-agent-capabilities', title: '智能体能力', titleEn: 'Agent Capabilities', file: '07-agent-capabilities.md' },
-    { id: '08-quick-dock', title: '快捷窗口', file: '08-quick-dock.md' },
+    { id: '08-quick-dock', title: '快捷窗口', titleEn: 'Quick Dock', file: '08-quick-dock.md' },
-    { id: '09-settings', title: '个人空间设置', file: '09-settings.md' },
+    { id: '09-settings', title: '个人空间设置', titleEn: 'Personal Space Settings', file: '09-settings.md' },
-    { id: '10-cli', title: 'CLI（开发中）', file: '10-cli.md' }
+    { id: '10-cli', title: 'CLI（开发中）', titleEn: 'CLI (In Development)', file: '10-cli.md' }
  ];
  var DICT = window.SITE_I18N || {};
  var navEl = document.getElementById('docsNav');
  var contentEl = document.getElementById('docsContent');
  var currentId = null;
  var loadSeq = 0; /* 防快速切换时旧响应覆盖新内容 */
-  /* 建左侧目录 */
+  /* 与主页 site.js 同款检测：localStorage 优先 → 浏览器语言（zh 开头中文，否则英文） */
-  DOCS.forEach(function (doc) {
+  function detectLocale() {
-    var a = document.createElement('a');
+    try {
-    a.href = '#' + doc.id;
+      var stored = localStorage.getItem('astrion_site_locale');
-    a.textContent = doc.title;
+      if (stored === 'zh-CN' || stored === 'en-US') return stored;
-    a.dataset.docId = doc.id;
+    } catch (e) {}
-    navEl.appendChild(a);
+    var nav = (navigator.language || '').toLowerCase();
-  });
+    return nav.indexOf('zh') === 0 ? 'zh-CN' : 'en-US';
  }
  var locale = detectLocale();
  function tr(key) {
    var d = DICT[locale] || {};
    return d[key] != null ? d[key] : key;
  }
  /* 顶栏/侧栏等静态 [data-i18n] / [data-i18n-aria] 文案替换 + 页面 title */
  function applyStaticI18n() {
    var d = DICT[locale];
    if (!d) return;
    document.documentElement.setAttribute('lang', locale);
    var i, k, nodes;
    nodes = document.querySelectorAll('[data-i18n]');
    for (i = 0; i < nodes.length; i++) {
      k = nodes[i].getAttribute('data-i18n');
      if (d[k] != null) nodes[i].textContent = d[k];
    }
    nodes = document.querySelectorAll('[data-i18n-aria]');
    for (i = 0; i < nodes.length; i++) {
      k = nodes[i].getAttribute('data-i18n-aria');
      if (d[k] != null) nodes[i].setAttribute('aria-label', d[k]);
    }
    document.title = tr('docs.pageTitle');
  }
  /* 建左侧目录（末尾附语言切换按钮；切语言时整体重建） */
  function buildNav() {
    navEl.innerHTML = '';
    DOCS.forEach(function (doc) {
      var a = document.createElement('a');
      a.href = '#' + doc.id;
      a.textContent = locale === 'en-US' ? doc.titleEn : doc.title;
      a.dataset.docId = doc.id;
      navEl.appendChild(a);
    });
    var langBtn = document.createElement('button');
    langBtn.type = 'button';
    langBtn.className = 'docs-lang-toggle';
    langBtn.textContent = locale === 'zh-CN' ? 'English' : '中文';
    langBtn.setAttribute('aria-label', locale === 'zh-CN' ? 'Switch to English' : '切换为中文');
    langBtn.addEventListener('click', function () {
      locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN';
      try { localStorage.setItem('astrion_site_locale', locale); } catch (e) {}
      applyStaticI18n();
      buildNav();
      renderNav();
      if (currentId) loadDoc(currentId);
    });
    navEl.appendChild(langBtn);
  }
  function docById(id) {
    for (var i = 0; i < DOCS.length; i++) if (DOCS[i].id === id) return DOCS[i];
@ -72,9 +128,17 @@
    currentId = id;
    renderNav();
    var seq = ++loadSeq;
-    contentEl.innerHTML = '<p class="docs-loading">加载中…</p>';
+    contentEl.innerHTML = '<p class="docs-loading">' + tr('docs.loading') + '</p>';
-    fetch('content/' + doc.file)
+    var path = (locale === 'en-US' ? 'content/en/' : 'content/') + doc.file;
    fetch(path)
      .then(function (res) {
        if (!res.ok && locale === 'en-US') {
          /* 英文版缺失时回退中文（保底：单篇未翻译不至于空白） */
          return fetch('content/' + doc.file).then(function (r2) {
            if (!r2.ok) throw new Error('HTTP ' + r2.status);
            return r2.text();
          });
        }
        if (!res.ok) throw new Error('HTTP ' + res.status);
        return res.text();
      })
@ -86,7 +150,8 @@
      })
      .catch(function (err) {
        if (seq !== loadSeq) return;
-        contentEl.innerHTML = '<p class="docs-error">文档加载失败（' + String(err) + '）。请刷新重试。</p>';
+        contentEl.innerHTML = '<p class="docs-error">' +
          tr('docs.loadFailedTpl').replace('{err}', String(err)) + '</p>';
      });
  }
@ -95,6 +160,8 @@
    if (id && id !== currentId) loadDoc(id);
  });
  applyStaticI18n();
  buildNav();
  var first = docIdFromHash();
  if (location.hash !== '#' + first) {
    /* 把默认篇目写进地址栏，刷新/分享行为一致 */
--- a/demo/site-assets/i18n.js
+++ b/demo/site-assets/i18n.js
@ -51,7 +51,14 @@ window.SITE_I18N = {
    'contact.copyAria': '复制邮箱地址',
    'footer.docs': '文档',
-    'footer.demo': '演示'
+    'footer.demo': '演示',
    'docs.home': '首页',
    'docs.side': '文档',
    'docs.navAria': '文档目录',
    'docs.pageTitle': '文档 — Astrion',
    'docs.loading': '加载中…',
    'docs.loadFailedTpl': '文档加载失败（{err}）。请刷新重试。'
  },
  'en-US': {
@ -99,6 +106,13 @@ window.SITE_I18N = {
    'contact.copyAria': 'Copy email address',
    'footer.docs': 'Docs',
-    'footer.demo': 'Demo'
+    'footer.demo': 'Demo',
    'docs.home': 'Home',
    'docs.side': 'Docs',
    'docs.navAria': 'Documentation contents',
    'docs.pageTitle': 'Docs — Astrion',
    'docs.loading': 'Loading…',
    'docs.loadFailedTpl': 'Failed to load document ({err}). Please refresh and try again.'
  }
 };