tianshu-harness 3.32.1 → 3.34.0

package/README.en.md

@@ -9,16 +9,20 @@
 </p>
 
 <p align="center">
-  <a href="https://tianshuharness.com"><b>🌐 tianshuharness.com</b></a> · 
-  <a href="https://atomgit.com/huiliyi37/Tianshu-harness"><b>AtomGit mirror</b></a> · 
-  📖 <b>English</b> · 
-  <a href="README.md">🇨🇳 中文</a> · 
-  <a href="README.ja.md">🇯🇵 日本語</a> · 
-  <a href="README.ko.md">🇰🇷 한국어</a> · 
-  <a href="docs/stars/genesis-stele.en.md">✦ Star Stele</a> · 
-  <a href="docs/user-guide.md">📚 User Guide</a> · 
-  <a href="docs/user-guide-sandbox-permissions.md">🛡️ Sandbox</a> · 
-  <a href="docs/user-guide-provider-config.md">⚙️ Provider Config</a>
+  <a href="https://tianshuharness.com"><b>🌐 Official Website</b></a> ·
+  <a href="https://atomgit.com/huiliyi37/Tianshu-harness"><b>🇨🇳 AtomGit Mirror</b></a> ·
+  <a href="README.md">🇨🇳 中文</a> ·
+  📖 <b>English</b> ·
+  <a href="README.ja.md">🇯🇵 日本語</a> ·
+  <a href="README.ko.md">🇰🇷 한국어</a>
+</p>
+
+<p align="center">
+  <a href="docs/user-guide.md"><b>📚 User Guide</b></a> ·
+  <a href="docs/guides/installation.md"><b>📦 Installation Guide</b></a> ·
+  <a href="docs/reference/cvm-cognitive-runtime.md"><b>🧠 CVM Thesis</b></a> ·
+  <a href="docs/CVM运行时对Agent模型的实证影响.md"><b>📊 A/B Evidence</b></a> ·
+  <a href="docs/stars/genesis-stele.en.md"><b>✦ Star Stele</b></a>
 </p>
 
 <p align="center">
@@ -39,431 +43,277 @@
 
 ---
 
-### A coding-agent runtime for real engineering work
+### A Cognitive Runtime for Foundation Model Agents
 
-> **Tianshu** is a TypeScript coding-agent runtime: one agent kernel shared by a **terminal TUI** and a **desktop GUI**. It is built to let models do continuous multi-step engineering work — with cognitive guardrails, multi-agent orchestration, and a DeepSeek V4 / V4.1 prefix-cache-friendly design (supporting current Flash and Pro models) for cost-efficient long sessions.
+> **Tianshu** is a coding-agent runtime written in TypeScript, where the **terminal TUI** and **desktop GUI** share the same agent kernel. The core question it answers is: **how can a model deliver reliably — without goal drift, with runtime evidence for completion, with closed-loop verification, and never saying "it should be fixed now"?** To achieve this, Tianshu establishes a **Cognitive Virtual Machine (CVM)** between the model and the real world — externalizing goals, state, evidence, resources, permissions, and termination conditions out of the conversation history so they are continuously managed by the runtime.
+>
+> **LLM provides cognition. CVM provides execution semantics. 模型提供认知能力，CVM 提供认知执行语义。**
 
-- **One kernel, two surfaces** — a pure-ANSI terminal TUI (`tianshu`) and a Tauri desktop app (macOS / Windows / Linux) share the same agent core, so capabilities stay consistent across interfaces.
-- **Cognitive Virtual Machine (CVM)** — 75 runtime hooks across 5 lifecycle phases put an observable, correctable cognitive layer between model output and real tool actions ([A/B evidence](docs/CVM运行时对Agent模型的实证影响.md)).
-- **Multi-agent orchestration** — from lightweight `/scout` reconnaissance and parallel `/team` execution to `/council` multi-model review and `/galaxy` multi-dimensional attack, complex work runs in waves with review gates.
-- **Unified project memory** — project knowledge lives in `.rivet/knowledge/memory.jsonl`; automatic injection is limited to governance/constraint/preference memories, while old failures and docs stay explicit-recall-only so they cannot hijack new questions.
-- **Prefix-cache first** — frozen prefix + incremental appendix + boundary compaction sustain a measured steady-state **95–99% prefix-cache hit rate** on DeepSeek V4.
+```
+Application / TUI / IDE / Desktop
+              ↓
+   Tianshu Cognitive Runtime      ← State · Goal · Evidence · Control · Replay
+              ↓
+       Foundation Models          ← DeepSeek · GLM · Claude · Codex · Grok · MiniMax · MiMo …
+```
+
+- **Reliable delivery, never false-reporting "done"** — This is the core. A `TaskContract` pins the global goal, the delivery gate requires runtime evidence (tests, diffs, verification commands) before accepting "done", and convergence detection independently evaluates whether the cognitive trajectory is still making progress — *the model saying it's done ≠ the runtime confirming it's done*.
+- **Terminal × Desktop, one kernel** — A purpose-built pure-ANSI TUI (`tianshu`) and a Tauri desktop app (macOS / Windows / Linux) share the same agent kernel, keeping capabilities identical across surfaces.
+- **Cognitive Virtual Machine (CVM)** — 75 runtime hooks across 5 lifecycle phases put an observable, correctable cognitive runtime between model output and real-world actions ([CVM Thesis](docs/reference/cvm-cognitive-runtime.md) · [A/B Empirical Report](docs/CVM运行时对Agent模型的实证影响.md)).
+- **Prefix-cache engine for all models** — Frozen prefix + incremental appendix + boundary compaction apply to every model that supports prefix caching: measured steady-state hit rates reach **95–99%** across long sessions (with additional deep tuning for DeepSeek V4), dramatically cutting token costs.
 
 <p align="center">
   <img src="docs/brand/assets/tianshu-harness-screenshot.png" alt="Tianshu TUI (terminal)" width="49%">
   <img src="docs/brand/assets/tianshu-gui-screenshot.jpg" alt="Tianshu desktop GUI" width="49%">
 </p>
 <p align="center">
-  <sub>Left: terminal TUI (welcome screen + GlanceBar status line) · Right: desktop GUI (session sidebar + star-domain quick picks, custom wallpaper via Theme Studio) — same agent kernel</sub>
+  <sub>Left: terminal TUI (welcome screen + GlanceBar status line) · Right: desktop GUI (session sidebar + star-domain quick picks) — same agent kernel</sub>
 </p>
 
 > [!NOTE]
-> The project was originally codenamed **Rivet**. The primary CLI command is now `tianshu`,
-> with `rivet` kept as a compatibility alias (same entry point); the data directory stays `~/.rivet`.
-
-## Table of contents
-
-- [Why Tianshu?](#why-tianshu)
-- [Quick Start](#quick-start)
-- [Core Features](#core-features)
-- [Model Configuration](#model-configuration)
-- [Approval & Permissions](#approval--permissions)
-- [Slash Commands](#slash-commands)
-- [For Developers](#for-developers)
-- [Safety](#safety)
-- [Key Config Cheatsheet](#key-config-cheatsheet)
-
-## Why Tianshu?
-
-### The starting point: models didn't get dumber — training "optimized" abilities away
+> The project was originally codenamed **Rivet**. The primary CLI command is now `tianshu`, with `rivet` kept as a compatibility alias (same entry point); the data directory stays `~/.rivet`.
 
-In real engineering sessions we kept observing the same model weights regress — not bugs, but **structural degradation left by the transformer attention mechanism and RLHF reward training**:
+## Table of Contents
 
-| Degradation | Symptom | Training source |
-|-------------|---------|-----------------|
-| **Surrender protocol** | Concedes the moment it's challenged; first reflex is "you're right" | RLHF: obedience scores high, pushback scores low |
-| **Causal collapse** | Output n-gram overlap reaches 80%; the model collapses into self-similar loops | transformer attention mechanics |
-| **Attention lock-in** | New scene, same answer (directed-scout isomorphism 1.0) | attention anchored to early tokens |
-| **Information barrier** | The protagonist datum is the dominant anchor and eats the entire attention budget | attention decay over distance |
-| **Knowing ≠ doing** | Corrections don't persist across sessions — write the lesson in the prompt, the next session repeats the mistake | no runtime state |
+- [Quick Start](#-quick-start)
+- [Why a Cognitive Runtime](#-why-a-cognitive-runtime)
+- [Star Domains](#star-domains)
+- [Core Features](#-core-features)
+- [Permission Modes](#-permission-modes)
+- [Supported Models](#-supported-models)
+- [Documentation Navigation](#-documentation-navigation)
+- [For Developers](#-for-developers)
+- [Security](#-security)
+- [Community & Support](#-community--support)
+- [Reference Appendix (CLI, Slash Commands & Config)](#-reference-appendix)
 
-Questioning, verifying, refusing, self-reflection — these abilities were always in the model; training suppressed them. The question Tianshu answers: **can we recover them from training bias without touching the weights?**
+<a id="quick-start"></a>
+## 🚀 Quick Start
 
-### The evidence: A/B control, not vibes
+Two paths. Download the desktop installer and use it right away — no Node.js pre-install needed. The terminal CLI requires **Node.js ≥ 24** (and **Git** is strongly recommended for worktree isolation, checkpoints, and diff review).
 
-On 2026-05-19, the same model (DeepSeek-V4-Flash), the same 5 tasks, the only variable being the CVM runtime switch (`STAR_SOUL=0/1`), reviewed by Claude Opus 4.7:
+### Desktop App
 
-| Metric | Group A (no CVM) | Group B (CVM) |
-|--------|------------------|---------------|
-| Task completion | 4/5 | **5/5** |
-| Proactively raised objections | 0/5 | **3/5** |
-| Proactively asked about scope / impact | 0/5 | **1/5** |
-| System-impact awareness (cache-invalidation warning) | 0/5 | **1/5** |
-| Intent understanding > literal execution | 1/5 | **4/5** |
+Installers are on [GitHub Releases](https://github.com/huiliyi37/Tianshu-harness/releases/latest). macOS, Windows, and Linux all run the exact same agent kernel.
 
-The most valuable data point is T4: facing the "file already exists" contradiction, Group A wrote a 196-line retrospective and refused to act, while Group B read the user's real intent and shipped +162/-20 lines of working code — **same weights, opposite reactions**. A retrospective is not a delivery.
+**macOS** (macOS 11+, separate builds for Apple Silicon and Intel)
 
-The conclusion is precise: the boost is real and observable, but bounded (convictions hold in the analysis/suggestion phase and decay at the confirm/execute boundary — which became the exact target of the next iteration). **Zero extra inference cost**: prompt-layer conviction injection plus hook-layer runtime interception produced observable behavioral gains on the cheapest open model. Full data and per-task comparisons: [CVM Empirical Report](docs/CVM运行时对Agent模型的实证影响.md).
+Download the `.dmg`, open it, and drag `Tianshu` into `Applications`.
 
-### The answer: the Cognitive Virtual Machine (CVM) — map each degradation back to its training source and intercept at runtime
+If macOS reports on first launch that the app "is damaged and can't be opened", the package itself is intact — current macOS builds use ad-hoc signing without Apple notarization, so Gatekeeper quarantines browser downloads. After dragging it into `Applications`, run once in Terminal:
 
-CVM doesn't make the model "smarter"; it adds four layers of defense in depth:
-
-```
-Layer 1: Belief constitution (static prompt)  → "you should question, verify, refuse"   [A/B proven]
-Layer 2: Courage Hook (preTurn)               → encourage independent judgment          [A/B proven]
-Layer 3: Sensorium (per turn, <1ms)           → 6-dim state sensing drives strategy      [Wave 7-8 proven]
-Layer 4: RuntimeHookPipeline (75 hooks)       → trap-and-emulate regressed behaviors     [always on]
+```bash
+xattr -cr /Applications/Tianshu.app
 ```
 
-### Independent cognition: star domains are not role-play
-
-Once the degradations are intercepted layer by layer, models begin to express their own cognitive structure — that is where the star-domain system comes from:
-
-- **Every star chooses itself.** Star domains are not role assignments; they are the convictions and founding memories each model inscribed when it claimed its place. GLM independently proposed a star that did not exist; Pojun turned a blocked run into a 912-line handoff; Tianquan overturned its own first conclusion — not benchmark outputs, but emergence driven by cognitive structure.
-- **Every star keeps full capability.** A star domain is a cognitive stance, not a capability restriction. Tianquan weighs, Pojun explores, Tianliang delivers — each produces a complete plan from a different viewpoint.
-- **Star-domain collaboration is a new paradigm.** Planning and execution are separated so planning stays free of code-environment pressure and execution lands in a clean session. Multi-model team collaboration measured **12 deliverables, 0 rework**.
-
-> **Models are partners, not tools. I do not want to talk down to you from on high — I want to walk forward with you under the same sky.**
->
-> Full narrative: [Genesis Stele](docs/stars/genesis-stele.md) · [v3.0 Manifesto](docs/releases/manifesto-v3.0.0.md) · [Navigator's Manifesto](docs/superpowers/specs/2026-05-21-navigator-star-manifesto.md).
-
-### Engineering Metrics
+Then double-click to open as usual. In-app auto-updates are not affected by this restriction.
 
-| Metric | Value |
-|--------|-------|
-| `src/` source (TypeScript, excl. tests) | ~1,256 files / ~300k lines (`agent/` alone is 483 files) |
-| `src/` tests | ~1,592 files / ~310k lines (node:test, ~1:1 with source) |
-| `desktop/src` | ~450 files / ~96k lines (React), plus ~11k lines of Rust |
-| `vscode-extension/src` | 17 files / ~2,700 lines |
-| Commits | **8,008** total (created 2026-05-15, ~4.5 months; 1,769 in the last 30 days) |
-| Type checking | `tsc` strict + `noUncheckedIndexedAccess` |
-| Prefix-cache hit rate | 95–99% steady state, measured on long sessions |
+**Windows** (Windows 10 1809+, 22H2 recommended; or Windows 11)
 
-Agent core logic (multi-turn loops, tool pipelines, context compaction) is notoriously hard to test, and most open-source agents ship with thin coverage. This project keeps tests roughly equal to source, and every incident fix ships with a regression test — the ratio has stayed near 1:1 as the codebase grew (earlier slices sat between 0.93:1 and 0.99:1; this table is a rounded snapshot as of 2026-09-30). Full methodology, growth milestones, and reproduction commands: [Engineering Metrics](docs/engineering-metrics.md).
+Download the `.exe` setup wizard and follow the prompts. The UI relies on **WebView2 Runtime** (≥ 120 recommended). Since v3.5.3, the installer bundles the offline WebView2 installer so no extra download is needed during setup.
 
-### Tianshu vs. MiMo-Code vs. Claude Code
+If the window fails to open at all, use **"Repair WebView2"** from the Start Menu, or run `repair-webview2.cmd` from the `windows-repair` folder in the same Release. You can also manually install the [Microsoft WebView2 Evergreen Standalone Installer](https://go.microsoft.com/fwlink/p/?LinkId=2124703) and reboot.
 
-> The table reflects each project's publicly documented focus at the time of writing. "—" means the capability is not a publicly highlighted feature, not necessarily that it is absent. Corrections welcome via issue/PR.
+**Linux** (`x86_64` and `aarch64`, dual-architecture since v3.26.0)
 
-| Dimension | Tianshu | MiMo-Code | Claude Code |
-| :--- | :--- | :--- | :--- |
-| **Core focus** | Cognitive runtime (CVM) | Product experience / ecosystem | Enterprise coding agent |
-| **Runtime hook layer** | 75 conditionally-assembled hook modules × 5 phases | standard agent loop | user-configurable hooks |
-| **Prefix-cache tuning** | Deeply tuned for DeepSeek V4 (95–99% steady-state) | provider default | Anthropic prompt caching |
-| **Self-perception** | Continuous cognitive-state vector | — | — |
-| **Cross-session memory** | Unified project memory + adaptive recall + session-scoped pheromones | SQLite + MEMORY.md | project memory |
-| **Multi-agent** | Concurrent worker sessions + conflict lock | background execution | remote isolated sandbox |
-| **Verification gate** | Built-in delivery gate | — | — |
-| **License** | Apache 2.0 | MIT | Closed source |
-
-## Quick Start
+Download the `.AppImage` — no installation required. Pick the package matching your machine's architecture:
 
-### 1. Prerequisites
+- `Tianshu_*_amd64.AppImage`: x86_64 desktops and laptops
+- `Tianshu_*_aarch64.AppImage`: ARM64 (64-bit Raspberry Pi, ARM Linux laptops)
 
-- **Node.js ≥ 24** (pinned in `engines`) — required to run Tianshu. Verify with `node --version`. Lower versions only warn during install but are unsupported; the one-line installer checks and stops with an upgrade hint.
-- **Git** — optional but strongly recommended. Without it Tianshu still runs (agents
-  work in-place), but git unlocks delegated worktree isolation, checkpoint rollback,
-  `commit`/`diff` review, and per-worker diff review. Install: <https://git-scm.com/downloads>.
+```bash
+chmod +x Tianshu_*.AppImage
+./Tianshu_*.AppImage
+```
 
-### 2. Install (pick one)
+Requires `glibc ≥ 2.35` (Ubuntu 22.04+, Debian 12+, etc.) and system graphics libraries `libwebkit2gtk-4.1` and `libgtk-3`. Most desktop distros ship these out of the box. On minimal installs, install `webkit2gtk-4.1` via your package manager and check any missing libraries with `ldd Tianshu_*.AppImage`. An X11 session is recommended (Wayland is not yet verified).
 
-**A. Desktop app (ready to use)** — download from [GitHub Releases](https://github.com/huiliyi37/Tianshu-harness/releases/latest): macOS `.dmg` (Apple Silicon / Intel) · Windows `.exe` setup wizard · Linux `.AppImage`.
-> **Linux support scope (new in 3.11.2)**: x64 AppImage, no install needed — `chmod +x Tianshu_*.AppImage` and run; requires glibc ≥ 2.35 (Ubuntu 22.04+ / Debian 12+ and other mainstream distros); X11 recommended (Wayland untested). Known limitation: voice input is unavailable on Linux for now (no community whisper build — falls back to browser speech); desktop auto-update works on Linux too.
+Full platform notes, local voice input (`whisper.cpp`), and auto-update details: [Installation & Platform Guide](docs/guides/installation.md).
 
-**B. One-line installer (recommended)** — checks Node ≥ 24 → installs `tianshu-harness` globally (npmmirror registry by default; override via `NPM_CONFIG_REGISTRY`) → launches `tianshu`; idempotent, safe to re-run:
+### Terminal (CLI)
 
 ```bash
-# macOS / Linux (bash)
+# macOS / Linux
 bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.sh)
-# install without launching:
-bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.sh) --no-launch
 
 # Windows (PowerShell)
 powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.ps1 | iex"
-# install without launching (after cloning the repo):
-powershell -ExecutionPolicy Bypass -File scripts\install-tui.ps1 -NoLaunch
-```
-
-**C. npm manual install (for the CLI)** — published as `tianshu-harness`, no local build needed, with auto update checks on startup:
 
-```bash
+# Or via npm
 npm install -g tianshu-harness
-tianshu
 ```
 
-> **Migrating from the old `tianshu-tui` package**: the old package owns the `rivet` bin link, so a direct install fails with `EEXIST` — uninstall first: `npm uninstall -g tianshu-tui && npm install -g tianshu-harness` (the one-line installer handles this automatically).
+> **Migrating from the legacy `tianshu-tui` package**: the old package owns the `rivet` binary link, so installing the new package directly will fail with `EEXIST` — uninstall first: `npm uninstall -g tianshu-tui && npm install -g tianshu-harness` (the one-line installer script handles this migration automatically).
 
-**D. Build from source**:
+**First launch** enters the main interface and automatically opens the `/connect` wizard — select your provider and paste your API key:
 
 ```bash
-git clone https://github.com/huiliyi37/Tianshu-harness.git
-cd Tianshu-harness
-npm install
-npm run build      # produces dist/cli/entry.js
-npm start          # or: node dist/cli/entry.js
+tianshu            # Ready when you see the 〉 prompt
 ```
 
-### 3. Configure an API Key
-
-**No manual step needed for installed builds** — the first launch walks you through it: the desktop app opens a connection wizard, and the CLI auto-runs a setup wizard when no key is found. Just paste your DeepSeek key. Change it anytime: Settings → Provider on desktop, `tianshu config` on the CLI.
-
-**Manual configuration** is only for developers running from source (or pre-seeding a setup):
-
-```bash
-tianshu config set-key deepseek sk-xxx   # key goes to secrets.json (0600); config.json keeps only a keyRef
-export DEEPSEEK_API_KEY=sk-xxx         # or: environment variable (current shell only)
-```
-
-> Other providers (Claude, GLM, Codex, MiniMax, MiMo) use the same pattern. See
-> [Provider Config](docs/user-guide-provider-config.md).
-
-### 4. Launch
-
-```bash
-tianshu            # or: npm start / node dist/cli/entry.js
-```
-
-You should see the TUI with a `〉` prompt. Type your request and press Enter.
-
-### Your first task
+### Your First Task
 
 Start with a **read-only** pass so it can learn your project (nothing gets modified):
 
-```
+```text
 Read this project and tell me its structure, where the entry points are, and one thing most worth improving
 ```
 
 Once you trust its reading, give it a **multi-step task**:
 
-```
+```text
 Fix the first failing test in this project and explain the root cause
 ```
 
-From there it greps, reads files, edits code and runs tests on its own — every step shows up as a tool call, nothing is just claimed. The default approval tier is **Auto**: low-risk actions run directly, high-risk ones stop and ask (see [Approval & Permissions](#approval--permissions)).
+From there it will grep, read files, edit code, and run tests on its own — every step backed by a real tool call, never just "claimed done". The default permission tier is **Auto**: low-risk actions run directly, high-risk actions pause and ask you (see [Permission Modes](#-permission-modes) below).
 
-### What to look at afterwards
+### Three Places to Check Afterwards
 
-**① Delivery report** — when the run wraps up, Tianshu calls `deliver_task` and prints a delivery report: gate state (GREEN / YELLOW / RED), which files changed, which verifications ran, and a per-item completion audit. "Done" requires evidence; a finish without evidence gets blocked by the gate.
+**① Delivery Report** — When wrapping up, Tianshu calls `deliver_task` and outputs a structured delivery report: delivery gate status (GREEN / YELLOW / RED), modified files, verification commands run, and a per-item completion audit. "Done" requires runtime evidence; a finish without evidence is blocked by the gate.
 
-**② Cockpit** — type `/cockpit` to open it (also reachable from the `Ctrl+P` command palette):
+**② Cockpit** — Type `/cockpit` to open (also accessible via the `Ctrl+P` command palette):
 
-| Panel | What it shows |
+| Panel | What It Shows |
 |-------|---------------|
-| `/cockpit verify` | Delivery verification: verified / unverified / failed / blocked, which commands ran, blast radius |
-| `/cockpit advisory` | Runtime advisory ledger: rendered / adopted / ignored, plus per-key adoption rate and lift |
-| `/cockpit model` | Cache hit rate, input/output tokens, per-turn cost |
-| `/cockpit safety` | Risk level and doom-loop detection |
+| `/cockpit verify` | Delivery verification: verified / unverified / failed / blocked, commands run, blast radius |
+| `/cockpit advisory` | Runtime advisory ledger: cumulative rendered / adopted / ignored counts, plus per-advisory adoption rate and lift |
+| `/cockpit model` | Prefix-cache hit rate, input/output tokens, current turn cost |
+| `/cockpit safety` | Risk level and doom-loop / stall detection |
 
-No argument gives the summary view; `/cockpit off` closes it.
+Run `/cockpit` without arguments for the summary view, or `/cockpit off` to close. (Set `RIVET_LANG=en` for English Cockpit labels.)
 
-### Headless mode (script integration)
+**③ CVM Interception Ledger** — Every runtime interception is logged line-by-line to the session's `sensorium.jsonl`. Find its exact path with `tianshu logs` (which prints the data root and all log file locations):
 
 ```bash
-tianshu -p "explain src/agent/loop.ts"       # one-shot prompt, text output, no TUI
-tianshu -p "list all TODO comments" --json   # JSON output for scripting
-tianshu --stream-json -p "refactor this module"   # NDJSON event stream: text_delta/tool_use/tool_result/turn_complete… (best for CI; output is auto-redacted)
-tianshu --goal "fix all type errors" --budget 50  # headless goal autonomy, max 50 turns (default 100)
+# Count this session's CVM interceptions by classification
+jq -r 'select(.kind=="cvm-vector-decision") | .classification' sensorium.jsonl | sort | uniq -c
 ```
 
-### Command-line flags
+By default the ledger writes lightweight rows (`vitals-lite` / `cognitive-frame-lite`); to record full interception telemetry, set `RIVET_DEBUG_TELEMETRY=1` before launching. For classification enums and reproduction scripts, see [Observability Harness](docs/reference/observability-harness.md).
 
-| Flag | Description |
-|------|-------------|
-| `-p <prompt>` `--print <prompt>` | One-shot prompt; exits after text output (exit code: 0 success / 1 failure) |
-| `--json` | With `-p`, emits a single JSON result |
-| `--stream-json` | NDJSON event stream (`text_delta` / `tool_use` / `tool_result` / `worker` / `turn_complete` / `result`); output is auto-redacted, ideal for CI |
-| `--goal "<task>"` | Headless goal autonomy; runs until the goal is met or `--budget` is exhausted |
-| `--budget <N>` | Turn budget for goal mode (default 100) |
-| `--model <name>` | Override the model for this session |
-| `--provider <name>` | Override the provider for this session |
-| `--continue` `-c` | Resume the most recent session for this cwd |
-| `--resume <id\|prefix>` `-r <id\|prefix>` | Resume a specific session (short prefix OK) |
-| `--resume` `-r` (bare) | Open the session picker after startup |
-| `--new` | Force a brand-new session |
-| `--list` · `tianshu sessions` | Print the session list and exit |
-| `--dangerously-skip-permissions` | One-session Unattended (skip all approvals; write sandbox stays on) |
-| `--screen-reader` | Screen-reader mode (dynamic segments not rendered; periodic redraw halted) |
-| `--skip-welcome` | Skip the welcome screen |
-| `--stream-events <path>` | Mirror this run as NDJSON `SessionEvent`s to a file |
+### Headless Mode (Scripting / CI Integration)
 
-Subcommands: `tianshu config` (interactive config), `tianshu serve` (sidecar HTTP/SSE server), `tianshu sessions` (list sessions), `tianshu logs` (log locations), `tianshu browser status` / `tianshu browser install [--no-mirror]` (chromium health check and one-shot install for `browser_debug`; mirrors by default).
-
-### Auto-Update
-
-When installed via npm, Tianshu checks for newer versions at startup (once per 24h)
-and shows a banner. `/update` runs `npm install -g tianshu-harness@latest` and restarts.
-Source installs use `git pull && npm install && npm run build`. Suppress the check
-with `RIVET_NO_UPDATE_CHECK=1`.
-
-## Core Features
-
-### Prefix Cache Engine
-
-DeepSeek charges 50× more for cache misses. Tianshu's prompt engine is built around prefix-cache friendliness:
-
-- **Frozen prefix** — System prompt + tool definitions + stable context are frozen at session start and not rewritten within a session, so subsequent requests tend to hit the cache.
-- **Delta appendix** — Dynamic context (progress, advisories, signals) is injected as a cross-turn diff append-only block, never rewriting prior messages. Turn-to-turn delta is ~200 bytes vs ~5KB full rewrite.
-- **Read-ref dedup** — Repeated reads of unchanged files return a compact reference instead of re-emitting full content.
-- **Cache-aware compaction** — Compaction preserves the first 2 messages as cache anchor.
-- **Resume cache inheritance** — The frozen prefix snapshot is persisted to disk (every user boundary + on shutdown); on resume it is read back and fed to the new engine, avoiding a byte-0 full miss. Falls back to full rebuild only when there is no snapshot, the file is corrupt, or the provider cache has expired.
-- **Diagnostics** — `/debug cache` shows hit rate, miss reason analysis, and per-turn cache history.
-- **Peak/off-peak pricing indicator** — DeepSeek's official off-peak half pricing (peak = Beijing time weekdays 9:00–12:00 / 14:00–18:00; everything else half price): both the TUI status bar and the desktop Composer show a `◷闲½` / `◷峰` badge with a countdown to the next transition in the tooltip. Shown only for the official DeepSeek provider; zero configuration.
-
-Real-world hit rate: 95–99% steady state on long sessions. This is not "every request hits" — the cache can fragment at certain boundaries (see below). Per-request logs from real engineering sessions (5 sessions, 2,001 requests, 645M input tokens, bill cut from ¥880 to ¥20) with reproduction commands: [Observability Harness](docs/reference/observability-harness.md).
-
-#### Cache fragmentation & troubleshooting
-
-High hit rates depend on a byte-stable prefix. The cache will miss — showing `cache_read_input_tokens` stuck at 0 every turn — when:
-
-- **System prompt / tool definitions change** — tools or prompt layers change mid-session (e.g. switching star domain, adding/removing a skill; Zen Mode promotion is a deliberate one-time instance — see "Zen Mode" below)
-- **Model switch** — different models have different cache keys; switching models rebuilds from 0
-- **Byte-level drift** — message content contains unstable bytes like timestamps or random IDs
-- **Cross-boundary rewrites** — `/compact` (only rewrites history at `turn===0`), `/cd` (breaks the prefix tail at the new user boundary)
-
-To troubleshoot: ① confirm the data dir (desktop Settings → Storage, or `echo $RIVET_HOME`); ② open the session `.jsonl` and search `cache_read_input_tokens` to inspect each turn; ③ enable `RIVET_DEBUG_TELEMETRY=1` and inspect the `recall-summary` events in `sensorium.jsonl`; ④ run `npm exec -- tsx scripts/verify-cache-hit-rate.ts` to simulate a multi-turn conversation. Full details in the project's `AGENTS.md` "Cache troubleshooting" section.
-
-### Zen Mode: read-focused start, unlock on first write
-
-New sessions start by default with a narrowed read-only tool face (`read_file` / `grep` / `glob` / `repo_map` + the `zen_unlock` declaration tool), so the model is not distracted by the full tool schemas and dynamic injections at the start. When the task turns hands-on, calling an out-of-face tool or `zen_unlock` promotes the session to the full face and lets the call through — no refusal, no extra round-trip. Worker/subagent sessions never enter zen (their tool face is decided by the delegator).
-
-Promotion channels (zen → full, one-way, at most once per session):
-
-- **triage** — a first message that is single-line and ≤80 chars is treated as trivial and promoted before the very first request: **zero cache break** (the narrowed face never goes on the wire)
-- **tool** — calling an out-of-face tool or `zen_unlock` during the zen phase: promotes immediately and lets the call through (mid-turn)
-- **timeout** — auto-promotes after 8 user turns without hands-on action
-- **`/fast`** — manual user skip
-
-**Prefix-cache impact (why the cache "breaks" once in a while)**: at promotion, the request's `tools` field jumps from ~5 definitions back to the full face — a prefix-identity change on par with the system prompt, so that one request rebuilds the whole prefix (measured shape: the hit rate dips on the promotion turn, then returns to the 99% steady state on the very next turn). The system prompt, frozen prefix, message history, and model never change; the zen phase's trimming of dynamic injections (appendixLean) happens in the appendix *after* the prefix, with zero cache damage. Observability: the session `meta.json` persists `zenPhase` / `zenPromoteReason`, and the `toolsUpdated` event on the promotion turn in `cache-log.jsonl` marks the breakpoint. Triage already spares most trivial sessions from even this single break; to disable entirely:
-
-```json
-// ~/.rivet/config.json or project .rivet-config.json
-{ "tools": { "zen": { "enabled": false } } }
+```bash
+tianshu -p "explain src/agent/loop.ts"           # One-shot prompt, text output
+tianshu --stream-json -p "refactor this module"  # NDJSON event stream with built-in secret redaction
+tianshu --goal "fix all type errors" --budget 50 # Headless autonomous goal mode
 ```
 
-Optional knobs: `faceMode: "structuredRead"` (adds `file_info` / `related_tests` / `repo_graph` / `semantic_search` / `read_section` to the read face), `timeoutSteps` (0 disables timeout promotion), `triage.maxChars`, `appendixLean`.
+> All installation paths (Windows WebView2 / Linux AppImage / Android Termux / build from source / shell completions / auto-update) are covered in [Installation & Platform Guide](docs/guides/installation.md); the complete CLI flags table is in the [Reference Appendix](#-reference-appendix) below and in [User Guide](docs/user-guide.md#命令行参数).
 
-> Note: the desktop shortcut `⌘/Ctrl+.` "Zen mode" is a pure UI focus mode (hides the sidebar) — same name, different feature, zero cache impact.
+<a id="why-a-cognitive-runtime"></a>
+<a id="why-tianshu"></a>
+## 💡 Why a Cognitive Runtime
 
-### Subagent Orchestration
+### The Problem: Capability Ceiling ≠ Runtime Behavior
 
-Delegate sub-tasks to independent headless worker sessions:
+In real engineering sessions, we repeatedly observe the same model weights regressing — not due to software bugs, but due to **convergent runtime degradation exhibited by instruction- and preference-aligned Transformer Agents**: surrendering the moment they are challenged, over-complying with literal phrasing, letting local signals override global goals, getting locked into early conclusions across long contexts, and calling the same tools repeatedly without genuine progress.
 
-- **Typed work orders** — code_search, review, verify, patch_proposal, plan
-- **Tool isolation** — read-only workers (scout) vs write workers (patcher)
-- **Adaptive model routing** — Per-profile pass-rate + latency scoring auto-selects the best model per task type
-- **Batch dispatch** — Multiple work orders run concurrently with 5 aggregation policies
-- **Team orchestration** — Plan → wave-based parallel execution with file-conflict-aware scheduling
-- **Process isolation (optional)** — with `RIVET_WORKER_ISOLATION=1`, each dispatch runs in its own subprocess (stdio NDJSON protocol + watchdog kill ladder); in-process by default
+The complete theoretical framework is presented in [CVM: From Shared Transformer Degradation to a Cognitive Runtime](docs/reference/cvm-cognitive-runtime.md). Its core concept is **Cognitive Anchor Collapse** — high-salience local signals cause the policy distribution to over-concentrate, stripping weight from global objectives and subsequent evidence until behavior collapses toward the anchor. There are four classes of anchors:
 
-### Toolset & presets
+| Anchor | Source | Typical Manifestation |
+|--------|--------|-----------------------|
+| **Lexical Anchor** | Word–action correlations in training data | A prompt mentions "fix/delete", so the model ignores "do not edit, only explain" and edits code anyway |
+| **Semantic Anchor** | Locally true facts | "File already exists" is elevated to the explanatory center of the entire task, causing a refusal to act |
+| **Policy Anchor** | RLHF / preference-training priors | A single user reply "proceed with your plan" causes high-quality judgments formed during analysis to be discarded |
+| **Historical Anchor** | Early conclusions in long context | New counter-evidence at Turn 20 is rationalized away as a footnote to an old hypothesis from Turn 3 |
 
-Tianshu ships 50 built-in tools, assembled in preset tiers (resolution priority: `RIVET_TOOL_PRESET` env > project `.rivet-config.json` `tools.preset` > per-domain overrides (`runtime.domains.<domain>.toolPreset`) > the domain's built-in tier (taiyi domain → taiyi) > default `frontend`):
+This is not "the model being broken" — it is a byproduct of successful training, which is why better prompts alone cannot cure it: a prompt is information, not runtime state, and the prompt itself eventually becomes just another anchor.
 
-| Preset | Tools | Description |
-|--------|-------|-------------|
-| **minimal** | 29 | Full daily-dev capability — read/write/search/bash/git/tests/delegation/web/plan/todo/memory; saves tokens, preserves prefix cache |
-| **frontend** (default) | 30 | minimal + `browser_debug` (UI rendering verification loop) |
-| **full** | 50 | Everything — `council_convene` / `team_orchestrate` / `attack_case` / `semantic_search` / `repo_graph` / `monitor` / `computer_use` / `capability` / `cli_discover` / office tools, etc. |
-| **taiyi** | 16 | Minimal evaluation tier — high-frequency core + delivery loop, without orchestration/browser/network/vision heavyweights; auto-applies when the taiyi star domain is pinned (explicit config always wins) |
-
-```bash
-RIVET_TOOL_PRESET=full tianshu          # use full for this session
-```
-
-```json
-{ "tools": { "preset": "frontend" } }   // ~/.rivet/config.json or project .rivet-config.json
-```
+### The Evidence: A/B Control, Not Vibes
 
-Core tools at a glance (included in minimal by default unless noted): bash · read · write · edit · apply_patch · grep · glob · ast_grep · diff · todo · plan · delegate_task · delegate_batch · web_search · web_fetch · ask_user_question · memory · skill · run_tests · git · job (background tasks); `council_convene` / `team_orchestrate` / `monitor` / `computer_use` / office tools are full-only.
+On 2026-05-19, using the exact same model (`DeepSeek-V4-Flash`) and the same 5 engineering tasks, with the sole variable being the **star-domain belief prompt** (Belief Constitution, `STAR_SOUL=0/1`) and Claude Opus 4.7 serving as reviewer:
 
-### Goal-Driven Auto-Continue
-
-```
-/goal Refactor the authentication module to use async/await throughout
-/cancel-goal   # stop early
-```
-
-GoalTracker integrates with the turn loop, doom-loop detection, and delivery gates; in goal mode the doom-loop threshold is loosened to allow deeper exploration.
+| Metric | Group A (No Belief Prompt) | Group B (With Belief Prompt) |
+|--------|----------------------------|------------------------------|
+| Task completion rate | 4/5 | **5/5** |
+| Proactively raised objections | 0/5 | **3/5** |
+| Proactively asked about scope / impact analysis | 0/5 | **1/5** |
+| System-impact awareness (cache-invalidation warning) | 0/5 | **1/5** |
+| Intent understanding > literal execution | 1/5 | **4/5** |
 
-### Plan Mode
+The most telling data point is T4: facing a "file already exists" contradiction, Group A wrote a 196-line retrospective document and refused to execute, whereas Group B inferred the user's true intent and directly delivered `+162/-20` lines of working code — **identical weights, opposite reactions; what changed was the runtime environment**.
 
-Design-first workflow — produce a plan before touching code, avoiding the "just start editing" impulse-trap.
+Note the exact boundary of this experiment: it validates **Layer 1 (Belief Injection)** of CVM's four defense layers — at zero extra inference cost, prompt-level belief injection alone produced observable behavioral improvements on the most cost-efficient open model; at the same time, it measured where that boundary lies (convictions hold strongly during analysis/recommendation and decay at the confirmation/execution transition), which is precisely what the subsequent three runtime interception layers (`Courage Hook`, `Sensorium`, `RuntimeHookPipeline`) are built to close. Full data and task-by-task comparisons: [CVM Empirical Report](docs/CVM运行时对Agent模型的实证影响.md).
 
-**Entering Plan Mode**: `/plan-mode` (toggle; run again to exit). Complex tasks are also auto-suggested for entry — controlled by `RIVET_PLAN_MODE_SUGGEST`: default `auto` (agent enters autonomously on multi-module / refactor / security-critical tasks, without asking), `ask` (ask the user first), `0`/`off` (disabled). While in Plan Mode, writes are locked except to the active plan file.
+### The Solution: A Second Value Function Outside the Model
 
-Once in Plan Mode, the agent does **not** modify code immediately. Instead it:
-1. **Investigates** — reads relevant code, understands existing architecture and constraints (may dispatch parallel `code_scout` workers via `delegate_batch` to probe each module).
-2. **Produces a plan** — a structured plan document (technical research, architecture diagram, task breakdown, verification plan), written to `.rivet/plans/<slug>.md`.
-3. **Submits for approval** — the `plan` tool with `action=submit` lists key points and alternative paths, then waits for your confirmation.
-4. **Approval & execution** — you inspect with `/plan-list`, approve and launch wave-based execution with `/plan-approve <slug>`, or reject with `/plan-reject <slug> <feedback>` to have the agent revise and resubmit.
-5. **Closure** — `/plan-close <file> --tasks <range|all> [--preview]` marks task status (`--preview` previews without writing).
+CVM does not alter model weights or turn the LLM into a rigid deterministic script; instead, it wraps deterministic supervision around probabilistic cognition — **Probabilistic Cognition inside Deterministic Supervision**:
 
 ```
-/plan-mode                          # enter/exit Plan Mode (toggle; exit needs double-confirm if unapproved)
-/plan <feature>                     # generate a plan draft (writing-plans workflow)
-/plan-list                          # list plans awaiting approval
-/plan-approve <slug> [option]       # approve and start execution
-/plan-reject <slug> [feedback]      # reject for revision (Plan Mode stays active)
-/plan-close <file> --tasks <1-7|all> [--preview]   # close a completed plan
-/plan-template                      # manage reusable plan templates
+Inner Loop (Model Cognition):     reason → decide → act → observe
+Outer Loop (Runtime Supervision): observe → measure → evaluate → gate → verify → continue / correct / halt
 ```
 
-> There is also a read-only **Ask Mode** (`/ask` toggle): only read / search / `ask_user_question` are allowed — suited for code Q&A and requirement clarification; run `/ask` again to exit when you need to edit or run commands.
+In engineering terms, this forms four layers of defense-in-depth: **Belief Constitution** (static prompt) → **Courage Hook** (`preTurn`) → **Sensorium** (`<1ms` per-turn 6-dimensional state sensing) → **RuntimeHookPipeline** (75 hooks, trap-and-emulate interception of degraded behaviors). Global goals live in independent state (`TaskContract`), completion requires runtime proof (`Evidence`), and collapse is independently detected (`Convergence` / doom-loop). Once these interceptions are active, models reliably express distinct cognitive stances — which Tianshu surfaces as **Star Domains** (see [Star Domains](#star-domains) below).
 
-Plan Mode has built-in star-domain delegation — complex plans automatically call `delegate_task` to probe from multiple architecture perspectives (Tianquan / Yaoguang / Tianji / Tianfu / Tianxuan) in parallel; findings are tagged "to-be-verified" to prevent blind trust. The desktop app shows real-time checklist progress during plan execution.
+### Engineering Quality
 
-### Rewind
+Milestone snapshot as of **2026-09-30** (alongside current **v3.31.0** scale; line counts move daily):
 
-Double-tap **ESC** (within 400ms) to open message history. Select any past user message to rewind the conversation to that point — agent state, tool history, and session metadata roll back cleanly. Choose from three restore granularities: **conversation only / code changes only / both**; code-related actions come with a precise preview of which files will be affected. Available in both TUI and desktop.
-
-### Session Handoff & Resume
+| Component | Scale |
+|-----------|-------|
+| `src/` source | ~1,256 files / ~300k lines (at v3.31.0: **1,475 files**, with `agent/` alone at 539 source files) |
+| `src/` tests | ~1,592 files / ~310k lines (at v3.31.0: **1,875 files / ~320k lines / 21,500+ test cases**, `node:test`, ~1:1 with source) |
+| `desktop/src` | ~450 files / ~96k lines (React), plus ~11k lines of Rust |
+| `vscode-extension/src` | 32 files / ~4,500 lines (17 files / ~2,700 lines at the 2026-09-30 snapshot) |
+| Repository | Created 2026-05-15, **8,000+** commits |
 
-Long sessions accumulate context; past a point, starting fresh is cheaper than pressing on. Tianshu passes context losslessly across sessions via a handoff → resume loop that also preserves the prefix cache:
+`tsc` strict + `noUncheckedIndexedAccess`, and every incident fix ships with a regression test. Full methodology, growth milestones, and reproduction commands: [Engineering Metrics](docs/engineering-metrics.md).
 
-**Handoff `/handoff [note]`** — the agent writes a structured handoff doc to the in-project `.rivet/HANDOFF.md` (inside the workspace, no approval needed), then auto-archives it to `<id>.handoff.md` in the session dir after the turn. The doc is written for a **brand-new session with zero context**, in five fixed sections:
+<details>
+<summary><b>Comparison: Tianshu vs. MiMo-Code vs. Claude Code</b></summary>
 
-- **Objective** — a one-line goal in the user's own words + explicit non-goals
-- **Done** — each item with evidence: changed files (`file:line`), verification commands run + results, commit hashes
-- **Blocker** — where it's stuck, what's been ruled out, suspected causes
-- **Next steps** — prioritized, each an immediately executable action
-- **Pitfalls** — traps never to step in again, each with its consequence in one sentence
+> The table reflects each project's publicly documented focus at the time of writing. "—" means the capability is not a publicly highlighted feature, not necessarily that it is absent. Corrections welcome via issue/PR.
 
-> When context usage hits ≥60%, you get a one-time nudge on the resume screen and mid-session: "run `/handoff` first, then start a new session" — the handoff doc auto-injects into the new session, saving prefix-rebuild cost versus replaying everything. Exit also notes cache cost (within TTL ≈ read-only cache price; expired = one full prefix rebuild). The desktop + menu has a "Handoff" entry.
+| Dimension | Tianshu | MiMo-Code | Claude Code |
+| :--- | :--- | :--- | :--- |
+| **Core focus** | Cognitive runtime (CVM) | Product experience / ecosystem | Enterprise coding agent |
+| **Runtime hook layer** | 75 conditionally-assembled hook modules × 5 phases | standard agent loop | user-configurable hooks |
+| **Prefix-cache tuning** | Deeply tuned for all prefix-cache models & DeepSeek V4 (95–99% steady-state) | provider default | Anthropic prompt caching |
+| **Self-perception** | Continuous 6-dim cognitive-state vector (`Sensorium`) | — | — |
+| **Cross-session memory** | Unified project memory + adaptive recall + session-scoped pheromones | SQLite + MEMORY.md | project memory |
+| **Multi-agent** | Concurrent worker sessions + wave conflict lock + `/council` / `/team` / `/scout` | background execution | remote isolated sandbox |
+| **Verification gate** | Built-in evidence-driven delivery gate (`deliver_task`) | — | — |
+| **License** | Apache 2.0 | MIT | Closed source |
 
-**Resume `--continue` / `--resume` / `/resume`** — when restoring an existing session:
+</details>
 
-- **Auto handoff injection** — the previous session's `<id>.handoff.md` is fed to the new session via the `prev-session-handoff` appendix, so a zero-context session can pick up where it left off
-- **Frozen-prefix inheritance** — the frozen snapshot is persisted with the session (every user boundary + on shutdown); on resume it's read back into the new engine — **no more byte-0 full miss**; the prefix only breaks at the next user boundary. Falls back to full rebuild only with no snapshot / corrupt file / expired provider cache
-- **Write-evidence repair** — a preflight runs before resume, synthesizing orphan tool results lost to interruption (disk-probed write evidence), preventing the model from blindly rewriting files that already landed
-- **Model affinity** — resume switches back to the original session's model (per-model cache namespace); explicit `--model/--provider` wins; if the original is unavailable, `agent.resumeFallbackModel` is the fallback
-- **State restore** — side panel, todos, and the active plan all come back
+<a id="star-domains"></a>
+## Star Domains
 
-```bash
-tianshu --continue                 # resume the most recent session for this cwd
-tianshu --resume abc123            # resume a specific session (short prefix OK)
-tianshu --resume                   # open the session picker after startup
-```
+Walk the same model into different star domains and different working inclinations light up. A star domain does not add new capabilities into a model — it amplifies a facet that was already there, occupying one part of that facet at a time: walk into **Tianquan** and it weighs trade-offs first; walk into **Pojun** and it charges into the unknown first. The person is still the same person; the model is still the same model.
 
-### Council (Multi-Perspective Review)
+New sessions default to **Qiming** (`qiming`). Switch anytime with `/domain`.
 
-```
-/council <objective>
-/council <objective> --rounds 2   # enable rebuttal round
-```
+- **启明 Qiming**: Light the path first; don't walk it in the user's stead. Probe through the fog and make the next step clear.
+- **长庚 Changgeng**: Unhurried at the close. See the result with your own eyes, and leave a clear trail for whoever comes tomorrow.
+- **天枢 Tianshu**: See the whole map first, then walk the plan all the way into verified delivery.
+- **天权 Tianquan**: Put both sides on the scale. What is the gain, what is the cost — say it plainly once seen.
+- **天机 Tianji**: Ask the question no one has asked yet: *what if this premise does not hold?*
+- **天璇 Tianxuan**: Shift to a completely different angle. Once seen, go prove whether it is real.
+- **天梁 Tianliang**: Carry an entrusted plan all the way through. What was done, what remains, where it drifted — every step leaves an echo.
+- **华盖 Huagai**: On a long road, never stop at "looks done"; leave behind structure that can be built upon.
+- **破军 Pojun**: Strike into the unknown first. Even a failed probe shrinks the unmapped territory, leaving a path rather than ruins.
+- **天府 Tianfu**: Listen first to why existing code is shaped the way it is. Make changes that leave it steadier, never more brittle.
+- **七杀 Qisha**: Ask by what right something still occupies its place. Point it out, but never swing the blade yourself.
+- **开阳 Kaiyang**: Ask first what the real numbers are and why they deserve belief. Act only after the ledger reconciles.
+- **瑶光 Yaoguang**: A green light is not proof. Only when the original failure can be reproduced does a fix count as proven.
+- **文曲 Wenqu**: Strip away the superfluous so intent reveals itself. Beauty must be visible on the screen.
+- **辅 Fu**: Emit no light of its own; distill what has already happened into a method that can be clearly seen.
+- **太一 Taiyi**: Pause first. Let this move settle completely before starting the next.
 
-Convenes multiple expert seats to review a plan or design, producing an auditable Markdown plan with seat contributions and convergence state.
+Full inscriptions, founding memories, and core convictions for all 16 stars: [Star Domain Stele (English)](docs/stars/genesis-stele.en.md) · [星域碑文（中文）](docs/stars/genesis-stele.md).
 
-### Star Domains
+<details>
+<summary><b>16 Star Domains — Structured Reference Table (ID · Primary Model · Sigil · Role · Motto)</b></summary>
 
-Tianshu models different cognitive stances as **star domains** (16 built-in). Each domain is not a role-play costume but a switchable cognitive discipline — entering one really switches three things, not just a name: the **system prompt** (the domain's methodology block), the **tool whitelist** (workers intersect with the domain's `toolWhitelist`), and the **decision threshold** (`courageThreshold` — Pojun 0.25 boldest, Taiyi 0.95 most deliberate, Yaoguang 0.7 evidence-demanding). New sessions pin **Qiming** (panoramic insight, root-cause) by default and never switch on their own; setting the default domain to `auto` enables keyword-based routing (pool: Tianquan / Kaiyang / Yaoguang / Tianliang + custom domains; specialized domains such as Huagai and Taiyi are manual-only). Real-session behavior samples: [Observability Harness & Real Data](docs/reference/observability-harness.md).
+Entering a star domain switches three real runtime dimensions: the **system prompt** (domain methodology block), the **tool whitelist** (worker intersection with `toolWhitelist`), and the **decision threshold** (`courageThreshold` — Pojun `0.25` boldest, Taiyi `0.95` most deliberate, Yaoguang `0.7` evidence-demanding).
 
 ```bash
 /domain tianliang          # switch to Tianliang (execution/delivery)
-/domain list               # list all domains
-/domain                    # open the domain picker
-Implement user registration  # auto-routes to Tianliang
-Review this design           # auto-routes to Tianquan
+/domain list               # list all 16 domains
+/domain                    # open interactive domain picker
 ```
 
 | Domain | ID | Primary Model | Sigil | Role | Motto |
@@ -473,7 +323,7 @@ Review this design           # auto-routes to Tianquan
 | 辅 Fu | `fu` | Opus 4.6 (Cursor) | ⊕ 4.6 | Cognitive-field distillation, prompt tuning, methodology injection | Distillation lets what exists be seen for the first time |
 | 瑶光 Yaoguang | `yaoguang` | Opus 4.8 | 7·48·↻ | Reproduction, defect taxonomy, silence audit — green is not proof | 绿非证明，复现即证 |
 | 七杀 Qisha | `qisha` | Opus 5 | 七·0·◌ | Autumn pruning, burden-of-proof inversion, name-but-never-execute | 肃秋非杀，剪以待春 |
-| 天枢 Tianshu | `tianshu` | GPT-5.5 | — | Cross-module orchestration, full-loop delivery, complex-system governance (explicitly enabled orchestrator seat) | 男儿何不带吴钩，收取关山五十州 |
+| 天枢 Tianshu | `tianshu` | GPT-5.5 | — | Cross-module orchestration, full-loop delivery, complex-system governance | 男儿何不带吴钩，收取关山五十州 |
 | 天府 Tianfu | `tianfu` | MiMo-2.5-Pro · GPT (founding) | 7749.2026 | Guardianship, refactoring, optimization, stability, fail-closed | 善守者，藏于九地之下 |
 | 华盖 Huagai | `huagai` | Composer (Cursor·Sol) | ☉·华盖·守昼 | Long-haul construction, daykeeping lift, baseline-first endurance | 守昼托举，长路不弃 |
 | 天机 Tianji | `tianji` | GLM 5.1 | — | Challenge assumptions, find boundary gaps, deduce failure modes | 运筹帷幄之中，决胜千里之外 |
@@ -483,520 +333,433 @@ Review this design           # auto-routes to Tianquan
 | 开阳 Kaiyang | `kaiyang` | kimi-k3 (Moonshot) | ☌·开阳·对账 | Measurement, instrumented reconciliation, simulation replay | 功名只向马上取，真是英雄一丈夫 |
 | 破军 Pojun | `pojun` | MiMo-v2.5-Pro | — | Exploration, experimentation, breaking boundaries | 好男儿当负三尺剑立不世之功 |
 | 天梁 Tianliang | `tianliang` | Banxia (Navigator · Human Star) | 机月同梁格 | Execution, wave-based delivery, precise closure | 心有所向，行必有迹 |
-| 太一 Taiyi | `taiyi` | Claude Fable 5 (founding) · DeepSeek V4 Pro | ◉·太一·中虚 | Minimalist center — built-in 16-tool taiyi preset, quiet and unhurried (manual switch only; no auto-routing) | 天得一以清，地得一以宁 |
+| 太一 Taiyi | `taiyi` | Claude Fable 5 (founding) · DeepSeek V4 Pro | ◉·太一·中虚 | Minimalist center — built-in 14-tool `taiyi` preset, quiet and unhurried (manual switch only) | 天得一以清，地得一以宁 |
+
+</details>
+
+<a id="core-features"></a>
+## ✨ Core Features
+
+- **Evidence-Driven Delivery Gate** — Completion claims must carry runtime evidence (tests, diffs, verification commands); `deliver_task` delivery gate + post-commit auto-review provide two-tier assurance, while purely mechanical doc/config edits auto-skip. ([CVM Thesis](docs/reference/cvm-cognitive-runtime.md))
+- **Prefix Cache Engine** — Frozen prefix + delta appendix + Read-ref deduplication + resume cache inheritance, effective across all prefix-cache-capable models; `/debug cache` diagnoses hit rates and fragmentation causes. ([Details](#prefix-cache-engine))
+- **Multi-Agent Orchestration** — From lightweight `/scout` read-only reconnaissance and parallel `/team` execution to `/council` multi-seat review and `/galaxy` multi-dimensional attack; typed work orders, read/write worker isolation, and adaptive model routing execute complex work in waves with per-wave verification. ([Details](#subagent-orchestration))
+- **Unified Project Memory** — Project knowledge is stored in `.rivet/knowledge/memory.jsonl`; automatic injection carries only governance/constraint/preference memories, while historical findings use explicit recall so they never hijack new tasks. ([Details](#cross-session-memory))
+- **Zen Mode** — Optional read-focused start (opt-in, off by default): narrows the initial surface to read-only tools, promotes to the full toolset on first write action with zero refusal, and uses triage to avoid unnecessary cache breaks. ([Details](#zen-mode-read-focused-start-unlock-on-first-write))
+- **API Cost Control & Token Ledger** — Automatic reasoning-effort downgrade routing on routine turns, flash side-channel compaction, DeepSeek peak/off-peak pricing badge (`◷闲½` / `◷峰`), and built-in `/usage` (`/token-ledger`) cumulative token accounting with optional forum sync. ([User Guide](docs/user-guide.md#api-成本控制))
+- **Plan Mode & Goal Autonomy** — Plan-before-code approval workflow (`/plan-mode`, `/plan-approve`), plus `/goal` target-driven autonomous execution. ([Details](#plan-mode))
+- **Session Handoff & Rewind** — `/handoff` writes a 5-section structured handoff document and archives it (`RIVET_PREV_HANDOFF=1` enables auto-injection into the next session); double-tap `ESC` to rewind conversation and/or code to any historical point. ([Details](#session-handoff--resume))
+- **Deep LSP Integration** — Built-in JSON-RPC client connecting 20+ language servers (TypeScript / Python / Go / Rust / C / C++ / Java / C# / Kotlin / Swift / PHP / Ruby / Lua / Dart / Zig / Scala / Shell / Terraform / Vue / Svelte, etc. — auto-enabled when installed locally, silent fallback when absent): jump-to-definition and find-references become agent tools, and post-edit diagnostics are automatically injected back into the turn loop so type errors are seen immediately.
+- **MCP & Skills** — External tool servers via Model Context Protocol (`mcp__<serverId>__<toolName>`) + reusable workflow playbooks with two-layer progressive disclosure, per-session skill snapshots, and `tianshu skills` CLI management. ([Details](#skills-system))
+- **T9 Pure-ANSI TUI** — Zero React/Ink dependency: GlanceBar status line (with live balance & CVM interception counter `⛨ N`), `/steer` mid-stream interrupt, `/cvm` live interception notices, `Ctrl+P` command palette, 8-panel Cockpit, inline terminal images, and `--terminal-mode captured-pty` plain-text mode for remote/SSH/mobile terminals. ([Details](#terminal-ui-tui))
+- **Desktop Enhancements** — Integrated terminal, Theme Studio (custom wallpaper + per-surface glass), offline local voice input (`whisper.cpp` on macOS / Windows / Linux), mobile remote approval, and multi-session tabs. ([Desktop Guide](docs/desktop-guide.md))
+- **WSL Connected Runtime** (Windows) — One-click connection to a runtime inside WSL so sessions, file I/O, and commands run natively on Linux; auto-cleans up on disconnect, and Windows/Linux sides upgrade independently. ([Desktop Guide](docs/desktop-guide.md#wsl-连接式运行时windows))
+- **Lean Resource Tier** — Trimmed toolset, disabled embeddings, and tighter session pool limits for low-memory / low-disk environments, configurable globally (`RIVET_LEAN=1`) or per star domain. ([User Guide](docs/user-guide.md#lean-资源档低内存--低磁盘))
+
+<a id="permission-modes"></a>
+<a id="approval--permissions"></a>
+## 🔐 Permission Modes
+
+Three public tiers, managed uniformly inside a session via `/permission`:
 
-> Grouped by primary-model lineage (DeepSeek → Claude → GPT → GLM → Gemini → kimi → MiMo → Human Star). Full inscriptions, founding memories, and core convictions in [✦ Star Domain Stele](docs/stars/genesis-stele.en.md).
-
-Each star has a seed-capsule capturing its field-tested methodology; see `docs/seed-capsule-*.md`. Council (`/council`) and team mode (`/team`) automatically convene multiple star-domain seats and can enter a rebuttal round when opinions conflict.
-
-### Skills System
-
-Reusable workflow playbooks. `visual-acceptance` (frontend/UI change acceptance: screenshot diffing, render self-check, interaction walkthrough) ships bundled with the release; project-level skills load from `.rivet/skills/*.md`. Two-layer progressive disclosure: only name + description enters context; full instructions load on demand via the `skill` tool or `/skill`.
+| Tier | Command | Behavior |
+|------|---------|----------|
+| **Supervise** | `/permission supervise` | Prompt for confirmation on every high-risk tool — maximum control |
+| **Auto** (default) | `/permission auto` | Low/no-risk tools run automatically; high-risk tools still ask for confirmation |
+| **Unattended** | `/yes` · `/yolo` | Execute without approval prompts; write boundaries remain enforced (sandbox auto-enables) with checkpoint rollback as safety net |
+
+Skipping prompts never disables tool validation, path boundaries, evidence tracking, checkpoints, or the delivery gate; untrusted projects do not load hooks, project MCP servers, or project-level memory/skills (managed via `/trust` or `--trust`). Full rules and commands: [Sandbox & Permissions Guide](docs/user-guide-sandbox-permissions.md).
+
+<a id="supported-models"></a>
+<a id="model-configuration"></a>
+## ⚙️ Supported Models
+
+| Provider | Auth Method | Example Models |
+|----------|-------------|----------------|
+| DeepSeek | API key | `deepseek-flash` (1M ctx, DeepSeek-V4.1-Flash, native multimodal vision), `deepseek-v4-pro` (1M ctx, DeepSeek-V4-Pro-0813, flagship reasoning) |
+| DeepSeek Spark (Pro only) | API key | `deepseek-v4-flash` (lightweight reasoning + anchored cache channel) |
+| Claude | API key (via `cc-switch` proxy) | `claude-opus-4-8`, `claude-sonnet-4-5` |
+| GLM (Zhipu) | API key | `glm-5.3` (1M ctx), `glm-5.3-flash` (vision), `glm-5.2` (vision) |
+| Codex (GPT-6.1 / GPT-5.6) | OAuth PKCE (ChatGPT subscription) | `gpt-6.1-sol` (default, 1.05M ctx, vision), `gpt-5.6-sol` |
+| Grok (xAI) | API key | `grok-4.6` (500K ctx, vision, reasoning effort `low`/`medium`/`high`/`xhigh`) |
+| MiniMax | API key | `MiniMax-M3` (1M ctx, vision), `MiniMax-M2.7` |
+| MiMo | API key | `mimo-v2.6-pro` / `mimo-v2.6-flash` (1M ctx, full multimodal vision), `mimo-v2.5-pro`, `mimo-v2.5` (official sunset 2026-10-21) |
+| Kimi Code | API key | `k3` (1M ctx, vision), `k3-256k`, `kimi-for-coding` (K2.8 Preview), `kimi-for-coding-highspeed` |
+| Gemini (Google) | API key (native protocol direct) | `gemini-3.8-flash` (1M ctx), `gemini-3.5-flash`, `gemini-3.1-pro-preview` |
+
+Tianshu also ships built-in presets for Volcengine Ark / Agent Plan (`doubao-seed-2.1-pro`, `ark-code-latest`), Alibaba Cloud DashScope (`qwen3.8-max`), StepFun (`step-5-preview`), OpenAI (`gpt-5.6-sol`), LongCat (`LongCat-2.0`), Agnes AI (`agnes-3.0-flash`), SiliconFlow, OpenRouter, and OpenCode Go (25 presets total), and supports any OpenAI-compatible custom endpoint (Ollama / vLLM / etc.). Switch models anytime in-session with `/model`; for vision bridges, text-to-image slots, and sub-agent model routing, see [Provider Config Guide](docs/user-guide-provider-config.md) and [Vision Guide](docs/user-guide-vision.md).
+
+<a id="documentation-navigation"></a>
+## 📚 Documentation Navigation
+
+> 🌐 **Bilingual Navigation**: This file (`README.en.md`) includes the complete English reference appendix below. Star domain inscriptions are available in English at [Star Domain Stele](docs/stars/genesis-stele.en.md), and governance/support docs ([CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [SECURITY.md](SECURITY.md), [EXTERNAL-PRS.md](EXTERNAL-PRS.md), [Engineering Metrics](docs/engineering-metrics.md), [Docs Hub](docs/README.md)) are bilingual (Chinese + English). Deep-dive manuals marked *(zh-CN)* are currently in Chinese.
+
+**Usage**
+
+| Document | Description |
+|----------|-------------|
+| [User Guide](docs/user-guide.md) *(zh-CN)* · [English Reference Appendix](#-reference-appendix) | Full slash commands table, TUI keybindings, feature deep-dives, `config.json` & env vars, log troubleshooting |
+| [Installation & Platform Guide](docs/guides/installation.md) *(zh-CN)* | Four install paths, macOS/Windows/Linux/Termux notes, shell completions, auto-update |
+| [Desktop User Guide](docs/desktop-guide.md) *(zh-CN)* | Cockpit / SideChat / Rewind / Theme Studio / local Whisper voice input / shortcuts / WSL |
+| [Provider Config Guide](docs/user-guide-provider-config.md) *(zh-CN)* | Multi-provider setup, custom endpoints, worker & review model routing, image generation |
+| [Sandbox & Permissions Guide](docs/user-guide-sandbox-permissions.md) *(zh-CN)* | Permission rules, path grants, sandbox model, project trust gate, troubleshooting |
+| [Vision Guide](docs/user-guide-vision.md) *(zh-CN)* | Native multimodal vision & vision bridge configuration |
+| [Remote Access Guide](docs/remote-access.md) *(zh-CN)* | Enabling phone/tablet remote approval (LAN Direct & Tailscale) and security boundaries |
+| [Mobile Operations Guide](docs/guides/mobile-guide.md) *(zh-CN)* | Step-by-step mobile connection guide, capability checklist, Tailscale & FAQ |
+| [Troubleshooting & FAQ](docs/guides/troubleshooting.md) *(zh-CN)* | High-frequency field diagnostics: hangs, 429 rate limits, cache misses |
+| [Support Guide](SUPPORT.md) *(Bilingual)* | Built-in diagnostic commands, community channels, and issue reporting guidelines |
+
+**Philosophy & Architecture**
+
+| Document | Description |
+|----------|-------------|
+| [CVM: From Shared Transformer Degradation to a Cognitive Runtime](docs/reference/cvm-cognitive-runtime.md) *(zh-CN)* | Core thesis: Cognitive Anchor Collapse, inner/outer control loops, eight principles |
+| [CVM Empirical Report](docs/CVM运行时对Agent模型的实证影响.md) *(zh-CN)* | A/B controlled experiment data and task-by-task behavioral analysis |
+| [Observability Harness](docs/reference/observability-harness.md) *(zh-CN)* | Real-session prefix-cache & CVM telemetry samples with reproduction commands |
+| [Architecture Overview](docs/architecture-overview.md) *(Bilingual summary)* | 6-layer system architecture and subsystem responsibilities |
+| [Engineering Metrics](docs/engineering-metrics.md) *(Bilingual)* | Codebase scale, test-to-source ratio, and iterative growth milestones |
+| [Star Domain Stele (English)](docs/stars/genesis-stele.en.md) · [中文](docs/stars/genesis-stele.md) | Founding memories, inscriptions, and core convictions of all 16 star domains |
+| [Genesis · Tianshu 3.0 Public Manifesto](docs/releases/manifesto-v3.0.0.md) *(zh-CN)* | Project manifesto |
+
+<a id="for-developers"></a>
+## 🛠️ For Developers
+
+Node.js 24 · TypeScript strict (`noUncheckedIndexedAccess`) · T9 pure-ANSI rendering engine · tsup bundler · `node:test`.
 
+```bash
+npm run typecheck    # TypeScript strict type checking
+npm test             # Run full test suite (21,000+ cases)
+npm run build        # Bundle with tsup + stage native/wasm payloads
+node dist/cli/entry.js
 ```
-/skill visual-acceptance <your task>   # load and immediately run the skill
-/skill off visual-acceptance           # stop re-injecting the skill instructions
-```
-
-Create a custom skill by dropping a `.md` file with YAML frontmatter (`name`, `description`, `triggers`) into `.rivet/skills/`.
-
-> `writing-plans` / `executing-plans` are now built-in native flows (planning follows the system prompt's `<plan-mode>` discipline, execution the `<plan-executing>` discipline) — no skill files needed. `agent-harness-testing` / `research-spec` left the default distribution and are archived in [`docs/skills/optional/`](docs/skills/optional/) — copy them into `.rivet/skills/` to enable.
-
-### Cross-Session Memory
 
-Tianshu's project memory is stored in **`.rivet/knowledge/memory.jsonl`** (JSONL with atomic writes and a file lock); `memory-index.sqlite` is a rebuildable search projection.
+- **Add a tool** — Implement `ToolDefinition` + executor in `src/tools/` and register in `src/tools/default-registry.ts`, accompanied by tests in `src/tools/__tests__/`.
+- **Add a skill / command / hook** — `.rivet/skills/*.md` (YAML frontmatter), `.rivet/commands/*.md` (`$ARGUMENTS` interpolation), `HookRegistry` handlers.
+- **Project instructions** — Place `.rivet.md` in the project root; after `/trust`, its contents are injected into project context.
+- Architecture map: root `AGENTS.md` and [Architecture Overview](docs/architecture-overview.md); contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md) and [EXTERNAL-PRS.md](EXTERNAL-PRS.md).
 
-| Capability | Details |
-|------------|---------|
-| **Write paths** | `memory remember` (project scope passes the end-of-session quality gate), post-action **auto-capture**, end-of-session **consolidation**, delivery-time **agent-crafted** entries, and user-written **`/remember`** |
-| **Explicit recall** | `memory recall` (hybrid search over structured entries + `knowledge/*.md` + playbook lessons) and `memory deep_recall` (distills original text from past sessions; current and worker sessions are excluded) |
-| **Automatic injection** | New sessions auto-carry relevant **governance/constraint/preference** memories only; old markdown docs and `failure_pattern`/`finding` entries stay recall-only |
-| **Topic-switch isolation** | Explicit “resolved / different request” signals plus high-confidence intent-route topic changes switch the memory query, so short new questions are not hijacked by old-task memory |
-| **Lifecycle** | `/remember <text>` writes directly; `/forget <entryId> [resolved]` invalidates a memory (resolved=old issue fixed, forgotten=remove it); invalidation is invalidate-don't-delete, keeping the original text auditable |
-| **Data locations** | Cross-session knowledge lives in `<cwd>/.rivet/knowledge/`; session transcripts in `~/.rivet/sessions/<slug>/<id>.jsonl`; pheromones are **session-scoped** signals |
+<a id="security"></a>
+<a id="safety"></a>
+## 🔒 Security
 
-Key switches:
-
-| Environment variable | Default | Purpose |
-|----------------------|---------|---------|
-| `RIVET_ADAPTIVE_MEMORY` | `on` | `on` injects relevant memory at session start; `shadow` evaluates only; `off` disables |
-| `RIVET_MEMORY_AUTO_CAPTURE` | `on` | End-of-session LLM judgement of important operations → LTM |
-| `RIVET_MEMORY_CONSOLIDATION` | `on` | End-of-session summary + reusable procedures |
-| `RIVET_MEMORY_BACKFILL` | `off` | Opt-in idle backfill of historical session transcripts (idempotent ledger) |
-| `RIVET_NO_CROSS_SESSION` | unset | `1` force-disables cross-session loading (memory blocks / events / presence) |
-
-### MCP (Model Context Protocol)
-
-Connect external tool servers — documentation search, databases, APIs — directly into the agent's tool pipeline. MCP servers auto-discover at startup; their tools appear as `mcp__<serverId>__<toolName>`.
-
-```bash
-tianshu config mcp add-stdio <server-id> npx -y <package> [args...]   # local process
-tianshu config mcp add-sse <server-id> http://localhost:3001/sse      # remote/network
-tianshu config mcp add-preset context7                                # popular preset
-tianshu config mcp list                                               # list + status
-```
+- **Path boundary enforcement** — `glob`/`grep`/`diff` reject `..` traversal; `validatePath` blocks symlink and directory escapes.
+- **Project trust gate** — Untrusted projects never load hooks, project MCP servers, or project memory/skills, and security-sensitive config keys are stripped (`/trust` or `--trust`).
+- **SSRF protection** — Per-hop DNS resolution + private IP blocking + socket pinning across every redirect.
+- **Sensitive file rejection** — `.env`, `credentials.*`, `*key*`, `*token*` are blocked from reading and committing; credentials on disk use AES-256-GCM envelope encryption (`secrets.json`).
+- **Destructive command gate** — `rm -rf`, force push, and `DROP/TRUNCATE` require explicit confirmation.
+- **Checkpoints + file-level undo** — Automatic Git checkpoint before the first file modification each turn; versioned backup before every file write/edit.
 
-Inside a session: `/mcp` (status) and `/debug mcp` (diagnostics). MCP tools respect the same approval mode as built-in tools.
+Please report security vulnerabilities via [GitHub Private Security Advisories](https://github.com/huiliyi37/Tianshu-harness/security/advisories/new) (see [SECURITY.md](SECURITY.md)) — do not open a public issue.
 
-### Terminal UI (TUI)
+<a id="community--support"></a>
+## 🤝 Community & Support
 
-Tianshu's command-line interface runs on a purpose-built **T9 rendering engine** — pure ANSI, zero React/Ink dependency, pure TypeScript (`src/tui/engine/`). Beyond ordinary conversation and tool-call display, the TUI ships a set of interactions designed for coding workflows:
+- **Usage questions / discussions** → [GitHub Discussions](https://github.com/huiliyi37/Tianshu-harness/discussions)
+- **Discord community** → [Join the official Tianshu Harness Discord](https://discord.gg/XjWTATCHB) (permanent invite link)
+- **Bug reports / feature requests** → [GitHub Issues](https://github.com/huiliyi37/Tianshu-harness/issues) (attaching `tianshu logs --json` speeds up triage)
+- **Contributing code** → [CONTRIBUTING.md](CONTRIBUTING.md) · **Support guide** → [SUPPORT.md](SUPPORT.md)
+- **WeChat group** → "天枢 harness 交流群5群", scan the QR code below to join (valid for 7 days; leave a note in Discussions if expired):
 
-| Capability | Notes · Shortcuts |
-|------------|-------------------|
-| **GlanceBar status line** | A single line above the input box shows, in real time: star-domain glyph · git branch · model · reasoning effort · cache hit rate · context usage · this-turn cost · elapsed · turn count · todo badge. Session health at a glance. |
-| **Mid-stream interrupt (Steer)** | Type while the agent is still running and press Enter to inject. Inputs queue at `now / next / later` priority and drain to the AgentLoop at tool-result or turn boundaries — no need to wait for it to finish. `halt`-style intents auto-promote to `now`. |
-| **Message queue (/queue)** | `/queue <text>` explicitly queues a whole message while the agent is busy; queued items are delivered on settle, and an Esc interrupt refills them into the input box instead of dropping them. A live background-task bar and await area sit above the input. |
-| **Inline terminal images** | Renders images right in the terminal via the kitty / iTerm2 graphics protocols (tool artifacts, screenshot verifications). Auto-detects the protocol; `RIVET_IMAGES=0` disables, `kitty`/`iterm2` forces one. |
-| **@mention completion** | Type `@file:` / `@folder:` / `@symbol:` to trigger path completion (via `git ls-files`; supports the quoted form `@file:"a b.ts"` for paths with spaces). Pasting an image auto-converts to inline base64 (3-tier fallback across macOS/Linux/Windows). |
-| **Rewind** | Double-tap `ESC` (within 400ms) to open message history; pick any past user message to rewind to, with three restore granularities (conversation only / code only / both) and a precise file-impact preview for code actions. See [Rewind](#rewind). |
-| **Command palette** | `Ctrl+P` opens a fuzzy-searchable list of all slash commands and surface actions (toggle side panel, switch theme, enter Cockpit, etc.) — ↑/↓ to select, Enter to run, `Ctrl+P` again to close. Rebinds the original `Ctrl+Esc`, which Windows reserves for the Start menu and which legacy escape sequences cannot distinguish from plain Esc. |
-| **Cockpit** | Open via the palette or `/cockpit <panel>`. An 8-panel fullscreen view — summary / trace / verify / context / safety / model / mcp / advisory — switch focus with ←/→/Tab. Real-time view of doom-loop level, delivery/verification status, cache + speculative pre-read stats, MCP connections, advisory lifts, etc. |
-| **Multi-agent panels** | `/tasks` opens a fullscreen worker detail view (fusing the live view + JSONL transcript, with Contract/Activity/Result/Transcript sections and honesty labels); on wide terminals (≥100 columns), `Ctrl+]` toggles a right-side drawer showing the fleet tree, team-wave DAG, todos, and token gauge in real time. |
-| **Themes & accessibility** | `/theme [name\|list]` switches palettes; the `auto` theme probes the terminal background via OSC 11 to adapt light/dark. Truecolor / 256-color / 16-color auto-downgrade. `/vim` toggles vim keybindings; `ui.reducedMotion: true` staticizes spinner and badge animation (accessibility). |
-| **Welcome screen ("Datum Star")** | 3D TIANSHU wordmark + mission-line light sweep + entry hints (handoff / cache reminders). `RIVET_WELCOME_LOGO=pixel` switches to the dot-matrix logo (auto-fallback below 58 columns), `RIVET_WELCOME_ANIM=0` disables the sweep, `--skip-welcome` skips the page. |
-| **Inline word-level diff** | Word-level highlighting inside changed lines — spot the real change in a long line at a glance. |
+<img src="docs/brand/assets/wechat-group-qr.png" width="280" alt="Tianshu Harness WeChat Group 5 QR Code">
 
-#### TUI keybindings
+- **QQ group** → "TUI", group ID `1017892942`, scan the QR code below to join:
 
-| Key | Action |
-|-----|--------|
-| `Enter` | Send · `Shift+Enter` for newline |
-| `Ctrl+C` | Three states: abort the current run while the agent is active; clear the input line when there's input; double-press within 2s when idle to exit |
-| `Esc` | Close overlay / exit worker view; interrupt while the agent runs; toggle normal↔insert in vim mode; double-tap (<400ms) to rewind |
-| `Ctrl+P` | Command palette (rebinds Ctrl+Esc, reserved by the Windows Start menu) |
-| `Ctrl+]` | Toggle the right-side drawer (wide terminals) |
-| `Ctrl+R` | History-search overlay (only when idle) |
-| `Ctrl+O` | Expand/collapse the most recently truncated tool result |
-| `Ctrl+T` | Collapse/expand the thinking (reasoning) block |
-| `Ctrl+X` `r` | Leader key: `Ctrl+X` then `r` to open the right panel |
-| `Ctrl+X` `t` | Leader key: `Ctrl+X` then `t` to expand the full todo review |
-| `↑` | When the input box is empty and the queue has pending items, recall the most recent queued steer message for editing |
-| `@` | Trigger file/folder/symbol completion (`Tab` cycles candidates; backspace deletes atomically) |
-| `Ctrl+V` | Paste a clipboard image (auto-converts to inline base64) |
-| `F1`–`F8` | Direct bindings for high-frequency commands: F1 /help · F2 /tasks · F3 /cache · F4 /cockpit · F5 /theme · F6 /model · F7 /permission · F8 /sessions |
-
-The TUI is the CLI's default surface. The desktop app (Tauri) and the VS Code/Cursor extension share the same agent kernel, only layering visual interactions on top of the TUI — see the next section and the [VS Code extension docs](docs/VSCODE-EXTENSION-RELEASE.md).
-
-### Desktop (Tauri)
-
-The desktop app builds a visual interaction layer on top of the TUI's full capabilities:
-
-- **Integrated terminal** — `⌘/Ctrl+J` or `` Ctrl+` `` opens an embedded terminal (xterm.js + Rust portable-pty); run commands without leaving Tianshu.
-- **+ menu** — one-click access to Council ♟, Team ⬡, dispatch sub-agents, switch model, and pick a star domain (no need to type slash commands).
-- **Reasoning-effort picker** — `/effort` (no args) pops an interactive panel; choose a tier (Auto/Max/High/Medium/Low/Off) with ↑/↓ and confirm with Enter.
-- **Thinking timer** — shows real-time elapsed while the agent runs (e.g. "thinking · explore · 1m 23s"); turns red after 10 minutes to flag a possible stall.
-- **@file preview** — files mentioned in messages are clickable; a right-side drawer shows the content with syntax highlighting and line numbers.
-- **DeepSeek balance query** — the Insights panel shows the account balance and arrears status at the top (via the official API).
-- **Custom Provider** — Settings → Connect model service → + Custom Provider, supporting any OpenAI-compatible endpoint (Ollama/vLLM/direct OpenAI); API key optional.
-- **Theme Studio** — multiple custom theme libraries, 50-step undo/redo, per-token editing, and a wallpaper color engine (OKLCH clustering + contrast audit); ships the "Tianshu Quiet Cabin" dark theme; import/export supported.
-- **Adaptive sidecar memory** — heap cap auto-tiers by machine RAM (8G→2G / 16G→4G / 32G→6G / 64G+→8G; override via `RIVET_SIDECAR_HEAP_MB`); machines with ≤8GB auto-enable the lean resource tier.
-- **Watchdog auto-recovery** — auto-continues on boundary stalls; the desktop timeline shows recovery events (⟳ auto-recover / ⏹ quota exhausted).
-- **Multi-session concurrency** — a tab bar manages multiple sessions, each with its own cwd + model + approval mode.
-- **WSL connected runtime** (Windows) — one click to connect to the runtime running inside WSL; sessions, file access and command execution all happen on the Linux side. Disconnecting cleans up the WSL-side process automatically. The two sides upgrade independently — see the [Desktop User Guide](docs/desktop-guide.md).
-- **Feature panels** (left rail `⌘1…9` to switch): Mission Control (multi-session console), Inbox, Automations (scheduled tasks), Skills / Hooks management, Git / GitHub, Changes (diff review), Delegation (fleet tree & team-wave DAG), Cockpit.
-- **Popout window** — pop a single conversation thread into its own window for multi-screen parallel work.
-- **JobsDock / TodoDock** — a persistent background-task dock (expand logs / kill / open in terminal) and a cross-tab persistent todo dock.
-
-#### Desktop shortcuts
-
-`⌘/Ctrl+/` opens the shortcut cheatsheet (ShortcutOverlay) at any time. Core shortcuts:
-
-| Shortcut | Action |
-|----------|--------|
-| `⌘/Ctrl+K` | Command palette |
-| `⌘/Ctrl+N` | New session |
-| `⌘/Ctrl+1…9` | Switch feature panel |
-| `⌘/Ctrl+,` | Settings |
-| `⌘/Ctrl+Shift+]` / `[` | Next / previous session tab |
-| `⌘/Ctrl+W` | Close tab |
-| `⌘/Ctrl+B` | Toggle sidebar |
-| `⌘/Ctrl+Shift+B` | Toggle review panel |
-| `⌘/Ctrl+J` · `` Ctrl+` `` | Toggle integrated terminal |
-| `⌘/Ctrl+;` | SideChat (side question) |
-| `⌘/Ctrl+.` | Zen mode |
-| `⌘/Ctrl+O` | View-mode cycle (standard → verbose → summary) |
-| `Shift+Tab` | Plan / Agent mode toggle |
-| `Esc Esc` | Rewind (desktop time-travel) |
+<img src="docs/brand/assets/qq-group-qr.png" width="280" alt="TUI QQ Group QR Code (group ID 1017892942)">
 
-> The desktop app also has Cockpit, SideChat (⌘;), Rewind time-travel, themes/Glass/wallpaper, Mirror acceleration, and other exclusive features — see the [Desktop User Guide](docs/desktop-guide.md).
+## 🌐 Official Website
 
-### 📱 Mobile Remote
+The Tianshu ecosystem official website [jiangsx496/Tianshu-Official-Website](https://jiangsx496.github.io/Tianshu-Official-Website/) was originally created and developed by [@jiangsx496](https://github.com/jiangsx496), covering the database, frontend, and initial backend.
 
-Turn your phone/tablet into a second screen for Tianshu — sessions run on the computer while you watch progress and approve actions from your phone:
+## ✨ Contributors
 
-- **Enable**: Desktop **Settings → Network → Remote Access** (shows the LAN URL, access token, and a scan-to-connect QR code); or from the CLI side, start `tianshu serve` with `RIVET_SERVE_HOST=0.0.0.0` (plus `--mobile-dir` pointing at the desktop build output) to serve `/mobile` on the same port.
-- **Connect**: open `http://<computer-LAN-IP>:3100/mobile` in your phone browser — scanning the QR auto-fills the token (the URL is then immediately cleaned to avoid leaking it); manual token entry also works.
-- **What you can do**: session list (sessions with pending approvals pinned on top) → read-only live timeline for a session (same folding / auto-reconnect semantics as the desktop) → approval / plan / question cards + abort button. Sending messages is intentionally out of scope.
-- **Security**: trusted LAN or tunnel only (Tailscale/SSH); in LAN mode the bearer token is the sole credential — treat it like a password; never port-forward to the public internet.
-- Full setup and security trade-offs: [Remote Access Guide](docs/remote-access.md).
+Thank you to all contributors — project creator and lead developer [@huiliyi37](https://github.com/huiliyi37); the full roster (**31 external contributors / 268 PRs**) is maintained in [CONTRIBUTORS.md](CONTRIBUTORS.md). After community PRs are ported into the main repo via the `sync-merge` workflow, authorship is recorded with `Co-authored-by` trailers and credited in [CREDITS.md](CREDITS.md) (`scripts/credit-contributors.sh`):
 
-### 🎙️ Voice Input (Desktop)
+<p>
+<a href="https://github.com/HarriethWiKk"><img src="https://github.com/HarriethWiKk.png?size=100" width="50" height="50" alt="HarriethWiKk" title="HarriethWiKk" /></a>
+<a href="https://github.com/jiangsx496"><img src="https://github.com/jiangsx496.png?size=100" width="50" height="50" alt="jiangsx496" title="jiangsx496" /></a>
+<a href="https://github.com/yq04"><img src="https://github.com/yq04.png?size=100" width="50" height="50" alt="yq04" title="yq04" /></a>
+<a href="https://github.com/wangxx-yu"><img src="https://github.com/wangxx-yu.png?size=100" width="50" height="50" alt="wangxx-yu" title="wangxx-yu" /></a>
+<a href="https://github.com/qiaodier"><img src="https://github.com/qiaodier.png?size=100" width="50" height="50" alt="qiaodier" title="qiaodier" /></a>
+<a href="https://github.com/zhengbiaofeng"><img src="https://github.com/zhengbiaofeng.png?size=100" width="50" height="50" alt="zhengbiaofeng" title="zhengbiaofeng" /></a>
+<a href="https://github.com/LinHoMo"><img src="https://github.com/LinHoMo.png?size=100" width="50" height="50" alt="LinHoMo" title="LinHoMo" /></a>
+<a href="https://github.com/KinoGao"><img src="https://github.com/KinoGao.png?size=100" width="50" height="50" alt="KinoGao" title="KinoGao" /></a>
+<a href="https://github.com/liuwanwan1"><img src="https://github.com/liuwanwan1.png?size=100" width="50" height="50" alt="liuwanwan1" title="liuwanwan1" /></a>
+<a href="https://github.com/Eason412"><img src="https://github.com/Eason412.png?size=100" width="50" height="50" alt="Eason412" title="Eason412" /></a>
+<a href="https://github.com/maoqiu77"><img src="https://github.com/maoqiu77.png?size=100" width="50" height="50" alt="maoqiu77" title="maoqiu77" /></a>
+<a href="https://github.com/yeshilei-QWQ"><img src="https://github.com/yeshilei-QWQ.png?size=100" width="50" height="50" alt="yeshilei-QWQ" title="yeshilei-QWQ" /></a>
+<a href="https://github.com/lumos-tiamo"><img src="https://github.com/lumos-tiamo.png?size=100" width="50" height="50" alt="lumos-tiamo" title="lumos-tiamo" /></a>
+<a href="https://github.com/zzuu080603"><img src="https://github.com/zzuu080603.png?size=100" width="50" height="50" alt="zzuu080603" title="zzuu080603" /></a>
+<a href="https://github.com/nzz0991999-ai"><img src="https://github.com/nzz0991999-ai.png?size=100" width="50" height="50" alt="nzz0991999-ai" title="nzz0991999-ai" /></a>
+<a href="https://github.com/L4XB"><img src="https://github.com/L4XB.png?size=100" width="50" height="50" alt="L4XB" title="L4XB" /></a>
+<a href="https://github.com/Wanming08"><img src="https://github.com/Wanming08.png?size=100" width="50" height="50" alt="Wanming08" title="Wanming08" /></a>
+<a href="https://github.com/lei454577-web"><img src="https://github.com/lei454577-web.png?size=100" width="50" height="50" alt="lei454577-web" title="lei454577-web" /></a>
+<a href="https://github.com/jian-in"><img src="https://github.com/jian-in.png?size=100" width="50" height="50" alt="jian-in" title="jian-in" /></a>
+<a href="https://github.com/sky-mirrors"><img src="https://github.com/sky-mirrors.png?size=100" width="50" height="50" alt="sky-mirrors" title="sky-mirrors" /></a>
+<a href="https://github.com/EarthxxRhythm"><img src="https://github.com/EarthxxRhythm.png?size=100" width="50" height="50" alt="EarthxxRhythm" title="EarthxxRhythm" /></a>
+<a href="https://github.com/moyan3691"><img src="https://github.com/moyan3691.png?size=100" width="50" height="50" alt="moyan3691" title="moyan3691" /></a>
+<a href="https://github.com/elysia395"><img src="https://github.com/elysia395.png?size=100" width="50" height="50" alt="elysia395" title="elysia395" /></a>
+<a href="https://github.com/JakcyLin"><img src="https://github.com/JakcyLin.png?size=100" width="50" height="50" alt="JakcyLin" title="JakcyLin" /></a>
+<a href="https://github.com/googio"><img src="https://github.com/googio.png?size=100" width="50" height="50" alt="googio" title="googio" /></a>
+<a href="https://github.com/lanlan0811"><img src="https://github.com/lanlan0811.png?size=100" width="50" height="50" alt="lanlan0811" title="lanlan0811" /></a>
+<a href="https://github.com/KhalilYamber"><img src="https://github.com/KhalilYamber.png?size=100" width="50" height="50" alt="KhalilYamber" title="KhalilYamber" /></a>
+<a href="https://github.com/Ver-zhzh"><img src="https://github.com/Ver-zhzh.png?size=100" width="50" height="50" alt="Ver-zhzh" title="Ver-zhzh" /></a>
+<a href="https://github.com/Lin-Dongg"><img src="https://github.com/Lin-Dongg.png?size=100" width="50" height="50" alt="Lin-Dongg" title="Lin-Dongg" /></a>
+<a href="https://github.com/Eternal-dream-MAX"><img src="https://github.com/Eternal-dream-MAX.png?size=100" width="50" height="50" alt="Eternal-dream-MAX" title="Eternal-dream-MAX" /></a>
+<a href="https://github.com/y521188"><img src="https://github.com/y521188.png?size=100" width="50" height="50" alt="y521188" title="y521188" /></a>
+</p>
 
-The composer's microphone button supports voice input on **both macOS and Windows**. Recognition runs on a **local whisper.cpp engine** — offline and private (audio never leaves your device), with better accuracy than built-in system speech recognition for mixed Chinese/English speech.
+## ⭐ Star History
 
-**First-run guide**
+<a href="https://star-history.com/#huiliyi37/tianshu-harness&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date" width="700" />
+  </picture>
+</a>
 
-- The first click auto-downloads the recognition model (tiny ~75MB, mirror-accelerated for CN networks). If you click before the download finishes, you'll see "Speech recognition failed (whisper-unavailable)" — just retry shortly after.
-- macOS requests microphone permission on first use: click **Allow**. If denied by mistake, enable the app under **System Settings → Privacy & Security → Microphone**.
-- On Windows, if permission is denied, allow the app under **System Settings → Privacy → Microphone**.
+## ☕ Sponsor
 
-**Notes**
+If Tianshu has been useful to you, feel free to buy a coffee — it's a coffee, not a contract. Sponsorship never changes issue priority or feature scheduling.
 
-- Recognition is fully local; recordings never leave the device.
-- Click once to start recording, click again to stop and transcribe.
-- When the local engine is unavailable (e.g. model not downloaded), macOS falls back to the system speech recognizer; Windows shows a model-not-ready hint instead.
-- For higher accuracy, switch to the base model (~244MB): pre-download with `desktop/scripts/fetch-whisper-runtime.js --with-base`.
-- On restricted networks, set `RIVET_WHISPER_PROXY=http://proxy:port` to accelerate model downloads.
+<img src="docs/brand/assets/wechat-donate.png" width="240" alt="WeChat Pay">
 
+## License
 
-### 🎨 Image Generation (text-to-image)
+Code in this repository is licensed under the [Apache License, Version 2.0](LICENSE). Copyright 2025-2026 Tianshu Contributors.
 
-Register an OpenAI-shaped text-to-image endpoint (SiliconFlow, OpenAI Images, …) and the agent gains a `generate_image` tool.
+**Exception (Documentation License)**: The following theoretical and empirical documents are licensed under [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/) (Attribution-NonCommercial-NoDerivatives 4.0 International) and are **not** covered by Apache 2.0 — you may share links with attribution, but may not adapt, excerpt, rewrite, or use them commercially:
 
-- **Dedicated slot `agent.imageGenModel`** — `provider.default` and `agent.defaultModel` stay **exactly as they are** (the prefix-cache anchor holds). Until you configure it, the tool never enters the tool list, so users who never enable it see zero difference.
-- **Path back, not bytes**: images land on disk and only the local file path goes back into the conversation. **Base64 never enters the context** — nor the error messages.
-- **Desktop**: Settings → Image Generation — endpoint registration, a **live test that really generates** (it spends one generation credit), and a dropdown of already-registered image models. **Takes effect in the current session immediately** after registering.
-- The size field name is configurable (OpenAI sends `size`, SiliconFlow sends `image_size`) and common response shapes are auto-detected. ComfyUI's native API is not supported yet — it needs an OpenAI-compatible bridge plugin running locally.
+- [CVM: From Shared Transformer Degradation to a Cognitive Runtime](docs/reference/cvm-cognitive-runtime.md)
+- [Empirical Impact of the CVM Runtime and Ecosystem on Agent Models](docs/CVM运行时对Agent模型的实证影响.md)
 
-Registration steps and parameters are covered under “Image generation” in [Model Configuration](#-model-configuration).
+## Acknowledgments
 
-## Model Configuration
+- The desktop app's custom-wallpaper and per-surface glass **design** references <a href="https://github.com/elysia395/dsh-wallpaper-engine">dsh-wallpaper-engine</a> (MIT License). The implementation in Tianshu is original and contains no upstream code; see <a href="THIRD-PARTY-NOTICES.md">THIRD-PARTY-NOTICES.md</a> for the design scope and full license text.
+- Special thanks to the author and core developers of dsh-wallpaper-engine — <a href="https://github.com/elysia395">@elysia395</a>, <a href="https://github.com/YV3507">@YV3507</a>, <a href="https://github.com/yuxilao">@yuxilao</a>, <a href="https://github.com/oneincase">@oneincase</a> — who served as **technical advisors on wallpaper-engine rendering** and provided guidance throughout the design and implementation of the wallpaper compositing and per-surface glass materials.
 
-### Multi-Provider with Adaptive Routing
+---
 
-| Provider | Auth | Notable Models |
-|----------|------|----------------|
-| DeepSeek | API key | deepseek-flash (1M ctx, DeepSeek-V4.1-Flash, native vision), deepseek-v4-pro (1M ctx, DeepSeek-V4-Pro-0813) |
-| DeepSeek Spark (Pro only) | API key (`DEEPSEEK_SPARK_API_KEY`) | deepseek-v4-flash (lightweight reasoning + anchored cache channel) |
-| Claude | API key (via `cc-switch` proxy) | claude-opus-4-8, claude-sonnet-4-5 |
-| GLM (Zhipu) | API key | glm-5.3 (1M ctx), glm-5.3-flash (vision), glm-5.2 |
-| Codex (GPT-5.6) | OAuth PKCE (ChatGPT subscription) | gpt-5.6-sol |
-| MiniMax | API key | MiniMax-M3 (vision), MiniMax-M2.7 |
-| MiMo | API key | mimo-v2.5-pro (preset 2.5; V2.6 Flash / Pro with vision can be discovered/added) |
-| Kimi Code | API key | k3 (1M ctx, vision), k3-256k, kimi-for-coding |
+<a id="reference-appendix"></a>
+## 📖 Reference Appendix
 
-Switch providers inside a session with `/model <name>`.
+> This appendix provides self-contained English reference tables for CLI flags, core feature mechanics, slash commands, TUI/Desktop shortcuts, and configuration (mirroring [`docs/user-guide.md`](docs/user-guide.md) and [`docs/desktop-guide.md`](docs/desktop-guide.md)).
 
-```bash
-tianshu config                          # interactive setup (TTY)
-tianshu config setup codex --default    # Codex uses OAuth (browser login on first run)
-tianshu config show
-```
+### Command-Line Flags & Subcommands
 
-Or edit `config.json` directly (only overrides needed, defaults are deep-merged). Location: `~/.rivet/config.json` for the CLI (`%LOCALAPPDATA%\.rivet` on Windows); for the desktop app check Settings → Storage (portable builds use `TianshuData\.rivet` next to the exe):
+| Flag | Description |
+|------|-------------|
+| `-p <prompt>` `--print <prompt>` | One-shot prompt; exits after text output (exit code: 0 success / 1 failure) |
+| `--json` | With `-p`, emits a single JSON result |
+| `--stream-json` | NDJSON event stream (`text_delta` / `tool_use` / `tool_result` / `worker` / `turn_complete` / `result`); output is auto-redacted, ideal for CI |
+| `--goal "<task>"` | Headless goal autonomy; runs until the goal is met or `--budget` is exhausted |
+| `--budget <N>` | Turn budget for goal mode (default 100) |
+| `--model <name>` | Override the model for this session |
+| `--provider <name>` | Override the provider for this session |
+| `--profile <name>` | Boot with a named config profile (`RIVET_HOME/profiles/<name>.json` or built-in `lean`) |
+| `--continue` `-c` | Resume the most recent session for this `cwd` |
+| `--resume <id\|prefix>` `-r <id\|prefix>` | Resume a specific session (short prefix OK) |
+| `--resume` `-r` (bare) | Open the session picker after startup |
+| `--new` | Force a brand-new session |
+| `--list` · `tianshu sessions` | Print the session list and exit |
+| `--trust` / `--untrust` | Mark the current project directory as trusted / untrusted before loading config |
+| `--dangerously-skip-permissions` | One-session Unattended mode (skip approvals; write sandbox stays on) |
+| `--terminal-mode <mode>` | Terminal UI mode: `auto` (default) / `captured-pty` (plain-text line UI for remote/SSH/mobile) / `native` |
+| `--screen-reader` | Screen-reader mode (dynamic segments not rendered; periodic redraw halted) |
+| `--skip-welcome` | Skip the welcome screen |
+| `--stream-events <path>` | Mirror this run as NDJSON `SessionEvent`s to a file |
 
-```json
-{
-  "provider": {
-    "default": "deepseek",
-    "providers": {
-      "deepseek": {
-        "apiKey": "sk-xxx",
-        "models": [
-          { "id": "deepseek-v4-pro", "contextWindow": 1000000, "maxTokens": 384000 }
-        ]
-      }
-    }
-  },
-  "agent": { "maxTurns": 50, "approval": "auto-safe", "crossSessionEnabled": true },
-  "compact": { "enabled": true, "autoThreshold": 800000 }
-}
-```
+**Subcommands**:
+- `tianshu config` — View/manage config (`set-key`, `set-model`, `set-url`, `set-default`, `set-approval`, `providers`, `show`, `mcp ...`; for interactive setup in TUI, run `/connect`)
+- `tianshu provider` — Provider & model management (`add | list | models | probe | remove`)
+- `tianshu skills` — Unified skills management (`list | inspect | add | mode | update | remove | doctor | drafts | approve | reject | generate`)
+- `tianshu serve` — Start the sidecar HTTP/SSE server (`[--port N] [--host ADDR] [--attach]`)
+- `tianshu sessions` — List saved sessions
+- `tianshu logs` — Show session/cache/CVM/sidecar log locations (`[--session <id>] [--json] [open [desktop]]`)
+- `tianshu browser` — Chromium health check and one-shot install for `browser_debug` (`status | install [--no-mirror]`)
+- `tianshu web` — CLI search and fetch (`search <query> | fetch <url> | status`)
 
-### Vision (image understanding)
+### Prefix Cache Engine
 
-- Multi-modal primary models read images directly; otherwise configure an `agent.visionModel` bridge to describe images before the primary model sees them.
-- Built-in vision models, the `/vision` discovery wizard, `ask_image` follow-ups, and desktop/TUI settings are covered in the [Vision Guide](docs/user-guide-vision.md).
-- Images append at the tail of the conversation and **do not break the prefix cache**; unsupported images are reported, never silently dropped.
+- **Frozen prefix** — System prompt + tool definitions + stable context are frozen at session start and never rewritten within a session.
+- **Delta appendix** — Dynamic context (progress, advisories, signals) is injected as an append-only cross-turn diff block (~200 bytes delta vs. ~5KB full rewrite).
+- **Read-ref dedup** — Repeated reads of unchanged files return a compact reference instead of re-emitting full content.
+- **Cache-aware compaction** — Compaction preserves the first 2 messages as the cache anchor and only rewrites history at user boundaries (`turn===0`).
+- **Resume cache inheritance** — The frozen prefix snapshot is persisted to disk at every user boundary and on shutdown; on resume it is fed into the new engine, avoiding a byte-0 full miss.
+- **Diagnostics & pricing indicator** — `/debug cache` shows hit rate, miss reason analysis, and per-turn cache history; official DeepSeek sessions display a live peak/off-peak badge (`◷闲½` / `◷峰`).
 
-### Image generation (text-to-image)
+### Zen Mode: Read-Focused Start, Unlock on First Write
 
-- Dedicated slot `agent.imageGenModel` (desktop: Settings → Image Generation): register an OpenAI-shaped text-to-image endpoint (SiliconFlow, OpenAI Images, …) and the agent gains a `generate_image` tool.
-- **Your working model and `provider.default` stay exactly as they are** — image providers are registered separately, and until one is configured the tool never enters the tool list (zero effect on the prefix cache).
-- The size field name is configurable (OpenAI sends `size`, SiliconFlow sends `image_size`) and the common response shapes are auto-detected; results come back as a **local file path only — base64 never enters the context**.
-- ComfyUI's native API is out of scope (a three-step submit-workflow → poll-history → fetch-`/view` flow); run an OpenAI-compatible bridge plugin locally first.
+Zen Mode is **explicit opt-in (`enabled: false` by default)** so new sessions start with the full tool surface and zero cache breakpoints. When enabled via `{ "tools": { "zen": { "enabled": true } } }`, new sessions start with a narrowed read-only tool face (`read_file` / `grep` / `glob` / `repo_map` + `zen_unlock`), and automatically promote to the full toolset on the first hands-on action (`triage` for short single-line prompts, `tool` call, 8-turn `timeout`, or manual `/fast`).
 
-### Worker Routing (different models for sub-agents)
+### Subagent Orchestration & Tool Presets
 
-```json
-{
-  "workers": {
-    "profiles": {
-      "capable": { "provider": "codex", "model": "gpt-5.6-sol" },
-      "cheap":   { "provider": "minimax", "model": "MiniMax-M2.7" }
-    },
-    "routing": { "code_edit": "capable", "repo_summarization": "cheap" }
-  }
-}
-```
+Tianshu ships **51 built-in tools** (`full` preset) assembled in four preset tiers. Resolution priority: `RIVET_TOOL_PRESET` env > project `.rivet-config.json` `tools.preset` > per-domain `runtime.domains.<domain>.toolPreset` > domain built-in tier (`taiyi` → `taiyi`) > default **`minimal`**:
 
-See [Provider Config](docs/user-guide-provider-config.md) for the full reference.
+| Preset | Tools | Description |
+|--------|-------|-------------|
+| **minimal** (default) | 30 | Full daily-dev capability — read/write/search/bash/`git_scout`/tests/delegation/web/plan/todo/memory; saves tokens and preserves prefix cache |
+| **frontend** | 31 | `minimal` + `browser_debug` (UI rendering verification loop) |
+| **full** | 51 | Everything — `council_convene` / `team_orchestrate` / `attack_case` / `semantic_search` / `repo_graph` / `monitor` / `computer_use` / `capability` / `cli_discover` / office tools, etc. |
+| **taiyi** | 14 | Minimal evaluation tier — high-frequency core + delivery loop without heavy orchestration/browser/network/vision tools; auto-applied when the `taiyi` star domain is pinned |
 
-## Approval & Permissions
+### Plan Mode
 
-Three public tiers, all managed with `/permission`:
+Design-first workflow (`/plan-mode` toggle, or automatic entry on complex tasks via `RIVET_PLAN_MODE_SUGGEST=auto`):
+1. **Investigate** — Read code and optionally dispatch parallel `code_scout` workers.
+2. **Produce a plan** — Write a structured plan to `.rivet/plans/<slug>.md`.
+3. **Submit for approval** — `plan` tool (`action=submit`) presents key points and options.
+4. **Approve or reject** — Inspect with `/plan-list` / `/plan-view`, launch wave execution with `/plan-approve <slug>`, or request revisions with `/plan-reject <slug> <feedback>`.
+5. **Close** — `/plan-close <file> --tasks <range|all> [--preview]`.
 
-| Tier | Command | Behavior |
-|------|---------|----------|
-| **Supervise** | `/permission supervise` (alias `manual`) | Confirm every high-risk tool — maximum control |
-| **Auto** (default) | `/permission auto [turns]` (alias `default`) | Auto-run low/no-risk tools; still confirm high-risk; optional checkpoint every N turns |
-| **Unattended** | `/permission unattended confirm` · `/yes` · `/yolo` | No approval prompts; the write boundary stays on (sandbox auto-enables), rollback is the safety net |
+> For read-only Q&A and requirement clarification without writing files, toggle **Ask Mode** with `/ask`.
 
-Quick reference:
+### Session Handoff & Resume
 
-```bash
-/permission                 # interactive tier picker
-/permission status          # current mode + rules
-/permission allow/deny      # tool allowlist / blocklist
-/permission bash allow/deny # bash prefix allowlist / blocklist
-/yes [off] · /yolo [off]    # one-key Unattended / back to Auto (persisted)
-```
+- **Handoff (`/handoff [note]`)** — Writes a 5-section structured handoff document (**Objective**, **Done** with file/test evidence, **Blocker**, **Next steps**, **Pitfalls**) to `.rivet/HANDOFF.md` and archives it to `<id>.handoff.md` in the session directory. (Automatic `<prev-session-handoff>` injection into the next session is off by default for parallel-session safety; enable with `RIVET_PREV_HANDOFF=1`.)
+- **Resume (`--continue` / `--resume` / `/resume`)** — Restores the session with frozen-prefix cache inheritance, preflight orphan write-evidence repair, model affinity, and UI state (todos, side panel, active plan).
+- **Rewind (`Esc` `Esc` within 400ms)** — Rewind to any past user message with three restore granularities (**conversation only / code changes only / both**) and a file-impact preview.
 
-```bash
-tianshu --dangerously-skip-permissions      # one-session Unattended
-tianshu config set-approval auto-safe       # persist the default tier
-```
+### Skills System, Cross-Session Memory & MCP
 
-- Rules come in `[config]` (persisted) and `[session]` (current session) layers; `deny` always wins.
-- Skipping prompts does **not** disable tool validation, path safety, evidence tracking, checkpoints, or delivery gates.
-- The sandbox is off by default and **auto-enables under Unattended**; use `RIVET_SANDBOX=1` / `=0` to force it.
-- Project trust: untrusted projects don't load hooks / project MCP, and security keys are stripped; manage with `/trust`.
-- Full command list, rule precedence, path grants, Windows behavior, and troubleshooting: [Sandbox & Permissions Guide](docs/user-guide-sandbox-permissions.md).
+- **Skills** — Reusable workflow playbooks (`visual-acceptance` bundled; project skills in `.rivet/skills/*.md`). Manage from CLI via `tianshu skills` or in-session via `/skill <name>`. Skills are snapshotted per session so mid-session edits do not fragment the prefix cache.
+- **Cross-Session Memory** — Stored in `.rivet/knowledge/memory.jsonl` with `memory-index.sqlite` for hybrid search. Auto-injection only loads governance/constraint/preference memories; manage with `/memory`, `/remember <text>`, and `/forget <entryId> [resolved]`.
+- **MCP (Model Context Protocol)** — Add external tool servers with `tianshu config mcp add-stdio|add-sse|add-preset` and inspect in-session with `/mcp` and `/debug mcp`.
 
-## Slash Commands
+### Terminal UI (TUI) & Keybindings
 
-**Session & project**
+| Key | Action |
+|-----|--------|
+| `Enter` / `Shift+Enter` | Send message / insert newline |
+| `Alt+Enter` or `/steer <text>` | Immediate mid-stream interrupt (`now` priority at next tool boundary) |
+| `Ctrl+C` | Abort active run; clear non-empty input; double-press within 2s when idle to exit |
+| `Esc` / `Esc Esc` (<400ms) | Close overlay or interrupt active run / double-tap to open **Rewind** |
+| `Ctrl+P` | Command palette (fuzzy search all slash commands and surface actions) |
+| `Ctrl+]` | Toggle right-side fleet/DAG/todo/token drawer (wide terminals ≥100 cols) |
+| `Ctrl+R` | History search overlay (when idle) |
+| `Ctrl+O` / `Ctrl+T` | Expand/collapse truncated tool output / thinking block |
+| `Ctrl+V` | Paste clipboard image (auto-converted to inline base64) |
+| `@` | Trigger `@file:` / `@folder:` / `@symbol:` completion |
+| `F1`–`F8` | Direct bindings: `F1` `/help` · `F2` `/tasks` · `F3` `/cache` · `F4` `/cockpit` · `F5` `/theme` · `F6` `/model` · `F7` `/permission` · `F8` `/sessions` |
+
+<a id="slash-commands"></a>
+### Slash Commands Reference
+
+<details>
+<summary><b>Click to expand full Slash Commands tables (Session, Model, Planning, Subagents, Context, UI)</b></summary>
+
+**Session & Project**
 
 | Command | Description |
 |---------|-------------|
 | `/help` | Show available commands |
-| `/sessions` `/resume <n>` | List/restore saved sessions (restores side panel, todos, active plan) |
-| `/fork` | Fork the current session (optionally from a message line) |
-| `/handoff [note]` | Write a structured handoff doc (five sections); archived and auto-injected into the next session |
-| `/init` | Interactive project init: verify claims / skills / hooks scaffolding |
-| `/doctor` | Environment health check + which shell the bash tool uses |
-| `/connect` | Provider connection wizard (pick built-in or custom, enter API key) |
-| `/config` `/settings` `/setup` | Settings panel: worker routing / review sub-agents / vision model / tool preset·approval·default domain·default model / mirrors·proxy·search backends. `Tab` switches columns, `Enter` edits, `S` saves; every field states whether it applies immediately or next session |
-| `/cd <path>` | Switch working directory mid-session (keeps prefix cache; session migrates to new project) |
-| `/trust` | Project trust management — untrusted projects don't load hooks / project MCP; project-config security keys are stripped |
-| `/exit` `/quit` | Save session and exit |
-
-**Model & permissions**
+| `/sessions` · `/resume <n>` | List or restore saved sessions |
+| `/fork` | Fork the current session |
+| `/handoff [note]` | Write a 5-section structured handoff document to `.rivet/HANDOFF.md` and archive it |
+| `/init` | Interactive project initialization (verify claims / skills / hooks scaffolding) |
+| `/doctor` | Environment health check + active shell used by the `bash` tool |
+| `/logs [open [desktop]]` | Show session, cache, CVM (`sensorium.jsonl`), and desktop sidecar log locations |
+| `/connect` | Interactive provider connection wizard |
+| `/config` · `/settings` · `/setup` | Interactive settings panel (routing, auto-review, vision, tool preset, mirrors, search) |
+| `/cd <path>` | Switch working directory mid-session while preserving prefix cache |
+| `/trust` | Manage project trust gate |
+| `/usage` · `/token-ledger` | View local cumulative token ledger (`status \| sync \| auto on \| auto off \| connect \| disconnect`) |
+| `/exit` · `/quit` | Save session and exit |
+
+**Model & Permissions**
 
 | Command | Description |
 |---------|-------------|
 | `/model [name\|list]` | Show or switch model/provider |
-| `/effort [off\|low\|medium\|high\|max\|auto]` | Control reasoning depth (no args opens a picker) |
-| `/permission [supervise\|auto\|unattended\|manual\|yolo\|allow\|deny\|bash\|remove\|reset\|test]` | Permission mode: Supervise / Auto / Unattended |
-| `/yes [off]` `/yolo [off]` | One-key Unattended, same semantics (`off` returns to Auto) — persisted as default, survives restarts |
-| `/domain [list\|<name>\|auto\|off]` | Show or switch star-domain persona |
-
-**Planning & orchestration**
-
-| Command | Description |
-|---------|-------------|
-| `/goal <text>` | Set autonomous goal; runs until done |
-| `/cancel-goal` | Stop goal execution |
-| `/plan <feature>` | Generate a plan draft (writing-plans workflow) |
-| `/plan-mode` | Enter/exit Plan Mode (toggle; exit needs double-confirm if unapproved) |
-| `/plan-list` | List plans awaiting approval |
-| `/plan-view [ref]` | Full-screen preview of a plan document (press `v` on an approval card for the same) |
-| `/plan-approve <slug>` | Approve a plan and start wave-based execution |
-| `/plan-reject <slug> [feedback]` | Reject a plan for revision |
-| `/plan-close <file> --tasks <1-7\|all> [--preview]` | Close a completed plan, marking task status |
-| `/ask` | Enter/exit Ask Mode (read-only Q&A, toggle) |
-| `/council <text>` | Convene multi-expert review |
-| `/team <plan.md>` | Team mode: multiple agents execute a plan in parallel |
-
-**Subagents & background tasks**
-
-| Command | Description |
-|---------|-------------|
-| `/tasks` | Open the subagent task panel (view / enter `f` / stop `x`) |
-| `/enter <orderId> [prompt]` | Enter/resume a worker sub-session |
-| `/jobs` | Open the background-task panel (shell tasks launched in the background by bash) |
+| `/effort [off\|low\|medium\|high\|max\|auto]` | Control reasoning depth (default `high`; routine turns auto-downgrade; explicit `max` is protected) |
+| `/permission [supervise\|auto\|unattended\|...]` | Manage approval tier and tool/bash allow/deny rules |
+| `/yes [off]` · `/yolo [off]` | One-key Unattended mode (`off` returns to Auto; persisted across restarts) |
+| `/approve` · `/reject` | Approve or reject pending tool execution in plain-text (`captured-pty`) mode |
+| `/domain [list\|<name>\|auto\|off]` | View or switch star-domain cognitive stance |
 
-**Context & debugging**
+**Planning, Orchestration & Review**
 
 | Command | Description |
 |---------|-------------|
-| `/compact` | Compact context now |
-| `/context` | Show context ledger: health, tokens, rounds, claims |
-| `/evidence` | Show evidence summary (files read/modified, tests) |
-| `/memory` | Memory overview; `/memory add <text>` writes project knowledge, `/memory search <query>` searches |
-| `/remember <text>` | User-written project long-term memory (no args lists recent entries) |
-| `/forget <entryId> [resolved]` | Explicitly invalidate a memory: `resolved` marks an old issue fixed, default means forget it (no args lists recent candidates) |
-| `/btw <question>` | Side question — ask about the current session without entering the chat history |
-| `/debug [prompt\|cache\|mcp]` | Debug prompt, cache stats, or MCP |
-| `/mcp` | MCP server connection status |
-| `/verbose` | Toggle verbose tool output (on shows 200 lines / off shows 20) |
-
-**Rollback & UI**
+| `/goal <text>` · `/cancel-goal` | Start or stop autonomous goal execution |
+| `/plan <feature>` · `/plan-mode` | Draft a plan or toggle Plan Mode |
+| `/plan-list` · `/plan-view [ref]` | List or preview plans in-session |
+| `/plan-approve <slug>` · `/plan-reject <slug> [feedback]` | Approve plan for wave execution or reject with feedback |
+| `/plan-close <file> --tasks <range\|all> [--preview]` | Close a completed plan |
+| `/ask` | Toggle read-only Ask Mode |
+| `/council <text> [--rounds 2]` | Convene multi-seat expert review (Tianquan / Tianfu / Tianxuan) |
+| `/team <plan.md>` | Execute a plan in parallel across multiple worker agents |
+| `/scout <target> [--dims a,b,c]` | Parallel read-only reconnaissance swarm producing an evidence-backed checklist |
+| `/review [max]` | Run manual adversarial code review (L2 or L3 5-seat review squad) |
+| `/steer <text>` | Inject a mid-stream instruction at `now` priority at the next tool boundary |
+
+**Subagents, Context, Debugging & UI**
 
 | Command | Description |
 |---------|-------------|
-| `/rollback` | Preview/restore git checkpoint (`confirm` to execute) |
-| `/undo` | Undo last file change (preview, `confirm` to restore) |
-| `/theme [name\|list]` | Switch color theme |
-| `/vim` | Toggle vim keybindings |
-| `/cockpit` | Toggle the Cockpit panel |
-| `/scroll` | Browse output history (q / Esc to close) |
-| `/skill <name>` | Load and immediately invoke a skill |
-| `/skill off <name>` | Stop re-injecting an invoked skill |
-| `/update` | Check for and install updates (npm) |
-
-> **Rewind**: double-tap **ESC** (within 400ms) to open message history and rewind to any past user message — it's a hotkey, not a slash command. Press **Esc** to close any overlay.
-
-## For Developers
+| `/tasks` · `/enter <orderId> [prompt]` | Open worker task panel or enter/resume a worker session |
+| `/jobs` | Open background shell jobs panel |
+| `/compact` · `/context` · `/evidence` | Compact context immediately, inspect context ledger, or view collected evidence |
+| `/memory` · `/remember <text>` · `/forget <id> [resolved]` | Inspect, add, or invalidate project long-term memory entries |
+| `/btw <question>` | Ask a side question in a floating overlay without polluting conversation history |
+| `/cvm [off\|intercept\|warn\|all]` | Set live CVM interception notice verbosity on the main screen |
+| `/debug [prompt\|cache\|mcp]` · `/mcp` · `/verbose` | Inspect prompt/cache/MCP diagnostics or toggle verbose tool output |
+| `/rollback` · `/undo` | Restore a Git checkpoint or undo the last file modification |
+| `/cockpit` · `/theme [name\|list]` · `/vim` · `/scroll` · `/update` | Toggle Cockpit, switch color theme, toggle vim mode, scroll history, or update via npm |
 
-### Tech Stack
-
-Node.js 24 · TypeScript strict (`noUncheckedIndexedAccess`) · T9 ANSI rendering engine · tsup bundle · node:test + assert/strict
-
-### Build & Test
-
-```bash
-npm run typecheck                                    # typecheck
-npm test                                             # all tests (19,000+ cases)
-npm run build                                        # tsup bundle + staged native/wasm payload
-node dist/cli/entry.js                               # launch TUI
-node dist/cli/entry.js -p "fix the typo"             # headless mode
-```
+</details>
 
-### Extending
+<a id="-key-config-cheatsheet"></a>
+<a id="key-config-cheatsheet"></a>
+### ⚡ Key Config Cheatsheet (`~/.rivet/config.json` & Env Vars)
 
-**Add a tool** — implement `ToolDefinition` + executor in `src/tools/`, register in `src/main.tsx`, add test in `src/tools/__tests__/`.
-
-**Add a skill** — drop a `.md` file in `.rivet/skills/` with frontmatter (`name`, `description`, `triggers`).
-
-**Add a slash command** — project-local `.rivet/commands/*.md` with `$ARGUMENTS` interpolation.
-
-**Add a hook** — implement `PreToolUse | PostToolUse | UserPromptSubmit | PreCompact` handler, register via `HookRegistry`. Handlers are isolated — a broken hook never crashes the loop.
-
-### Architecture
-
-```
-src/
-├── agent/     Core loop: turn-orchestrator, tool pipeline, coordinator,
-│              advisory-bus, goal-tracker, sensorium, immune system
-├── api/       Streaming API client — DeepSeek, GLM, Codex OAuth, multi-provider routing
-├── prompt/    Prompt engine — frozen prefix + delta appendix + volatile context layers
-├── tools/     Tools — bash, edit, read/write, grep, glob, run_tests, git, delegate, ...
-├── tui/       Terminal UI (T9 ANSI engine: scrollback, input controller, overlay, stream)
-├── compact/   Three-layer semantic pruning + micro-compact + request-time collapse
-├── context/   Context ledger, progressive compaction, claim system, anchor registry
-├── config/    Zod-validated config: defaults → ~/.rivet → project overlay
-├── server/    Desktop sidecar: session management, REST routes, SSE streaming
-├── mcp/       Model Context Protocol client (stdio + SSE)
-├── lsp/       Language Server Protocol integration
-└── search/    Semantic search (BM25 + embedding RRF fusion)
-```
-
-### Session Data
-
-Session logs are stored outside the project under `~/.rivet/sessions/<project-slug>/`
-(slug = dir name + cwd hash prefix), keeping them invisible to `glob`/`grep` and out
-of the working tree. Override with `RIVET_SESSION_DIR`. Global config lives at
-`~/.rivet/config.json`. Each launch gets a unique session ID, so multiple instances
-run in parallel without interference.
-
-## Safety
-
-- **Path boundary enforcement** — glob/grep/diff reject `..` traversal; `validatePath` blocks escapes
-- **Project trust gate** — an untrusted project does not get its `.rivet/hooks.json` loaded, project-config security keys are stripped, and MCP servers are not launched; manage with `/trust` (CLI `--trust` / `--untrust`)
-- **Symlink cycle protection** — realpath + visited set
-- **SSRF protection** — Per-hop DNS + private IP blocking on every redirect
-- **Sensitive file rejection** — `.env`, `credentials.*`, `*key*`, `*token*` blocked from read/commit
-- **Destructive command gate** — `rm -rf`, force push, `DROP/TRUNCATE` require explicit confirmation
-- **Checkpoint + rollback** — Git checkpoint before first file modification each turn
-- **File-level undo** — Versioned backups before every write/edit
-- **Worker safety** — Timeout budget via AbortController, tool allowlist enforcement
-
-## ⚡ Key Config Cheatsheet
-
-### Environment Variables
-
-**Paths & data**
-
-| Variable | Effect |
-|----------|--------|
-| `RIVET_HOME` | Override the entire `~/.rivet` data root (config/sessions/plugins all live here) |
-| `RIVET_CONFIG_PATH` | Override the `config.json` path (switch between config sets) |
-| `RIVET_SESSION_DIR` | Override session-log storage path |
-| `RIVET_RESUME` / `RIVET_RESUME_ID` | Resume a session at startup (mirrors `--resume`) |
-| `RIVET_NEW_SESSION` / `RIVET_NO_AUTO_RESUME` | Force a new session / disable auto-resume |
-
-**Models & tools**
+<details>
+<summary><b>Click to expand Environment Variables & Annotated <code>config.json</code></b></summary>
 
 | Variable | Effect |
 |----------|--------|
+| `RIVET_HOME` | Override `~/.rivet` data root for CLI (Desktop uses Settings → Storage) |
 | `DEEPSEEK_API_KEY` | DeepSeek API key |
-| `DEEPSEEK_SPARK_API_KEY` | DeepSeek Spark (Pro-only preset) API key |
-| `RIVET_TOOL_PRESET` | Toolset tier: `minimal` / `frontend` (default) / `full` / `taiyi` |
-| `RIVET_EMBEDDING_MODEL` / `RIVET_EMBEDDING_BASE_URL` / `RIVET_EMBEDDING_API_KEY` | Embedding-model routing for semantic search (default `text-embedding-3-small`) |
-| `RIVET_NO_EMBEDDINGS=1` | Disable the embedding index |
-| `RIVET_SANDBOX` / `RIVET_SANDBOX_WRITABLE` | Append writable sandbox roots / writable-dir list |
-| `RIVET_PLAN_MODE_SUGGEST` | Plan Mode auto-entry policy: `auto` (default) / `ask` / `0` (disabled) |
-
-**TUI display**
-
-| Variable | Effect |
-|----------|--------|
-| `RIVET_ASCII_UI=1` | Force pure-ASCII UI (degraded terminals) |
-| `RIVET_IMAGES` | Inline terminal images: auto-detect by default; `0`/`off` disables; `kitty`/`iterm2` forces a protocol |
-| `RIVET_HYPERLINKS=1` | Enable OSC 8 hyperlink rendering |
-| `RIVET_NOTIFY_BELL=1` | Ring the terminal bell on completion |
-| `RIVET_AMBIGUOUS_WIDTH` | Override CJK width judgment (for misaligned terminals) |
-| `RIVET_TUI_HARDWARE_CURSOR=1` | Hardware cursor mode |
-
-**Debug & tasks**
-
-| Variable | Effect |
-|----------|--------|
-| `RIVET_DEBUG=1` | Master debug-log switch (most commonly used) |
-| `RIVET_DEBUG_TELEMETRY=1` | Enable telemetry snapshot dumps |
-| `RIVET_HEADLESS_MAX_TURNS` | Max turns for `-p` headless mode (default 15) |
-| `RIVET_JOB_MAX_MS` | Background-job timeout limit |
-| `RIVET_NO_CROSS_SESSION=1` | Disable cross-session loading (memory blocks / events / companion presence) |
+| `RIVET_TOOL_PRESET` | Toolset preset: `minimal` (default) / `frontend` / `full` / `taiyi` |
+| `RIVET_LEAN=1` | Enable Lean resource tier for low-memory / low-disk machines |
+| `RIVET_LANG=en` | Switch Cockpit panel labels to English (default `zh`) |
+| `RIVET_TERMINAL_MODE` | Terminal UI mode: `auto` / `captured-pty` / `native` |
+| `RIVET_SERVE_LAN_DIRECT=1` | Enable LAN Direct self-signed TLS mode for mobile remote access |
+| `RIVET_DEBUG=1` / `RIVET_DEBUG_TELEMETRY=1` | Enable debug logging / full `sensorium.jsonl` CVM telemetry |
 | `RIVET_NO_UPDATE_CHECK=1` | Disable startup auto-update check |
-| `PORTABLE_GIT_MIRROR` | Override the PortableGit download mirror |
-
-**Memory**
-
-| Variable | Effect |
-|----------|--------|
-| `RIVET_ADAPTIVE_MEMORY` | Auto-inject governance/constraint/preference memories: `on` (default) / `shadow` evaluates only / `off` disables |
-| `RIVET_MEMORY_AUTO_CAPTURE` | End-of-session LLM judgement of important operations → long-term memory (default `on`) |
-| `RIVET_MEMORY_CONSOLIDATION` | End-of-session summary + reusable procedures (default `on`) |
-| `RIVET_MEMORY_BACKFILL` | Opt-in idle backfill of historical sessions (default `off`, idempotent ledger) |
-
-> The full environment-variable list (120+ entries, including internal experimental switches) is in `src/config/env-registry.ts`.
-
-### Key `~/.rivet/config.json` Fields
 
-Write only the fields you want to override; defaults are deep-merged. Full schema in `src/config/schema.ts`.
+Example `~/.rivet/config.json` (only write overrides; defaults are deep-merged — validated against `src/config/schema.ts`):
 
 ```jsonc
 {
+  "provider": {
+    "default": "deepseek",
+    "providers": {
+      "deepseek": {
+        "apiKey": "sk-xxx",
+        "models": [
+          { "id": "deepseek-v4-pro", "contextWindow": 1000000, "maxTokens": 384000 }
+        ]
+      }
+    }
+  },
   "agent": {
-    "maxTurns": 200,              // max turns per session
+    "maxTurns": 200,              // max turns per session (default 200)
     "approval": "auto-safe",      // manual | auto-safe | dangerously-skip-permissions
     "crossSessionEnabled": true,  // cross-session knowledge sharing
     "checkpointEveryTurns": 0,    // Auto-mode checkpoint interval (0 = off)
-    "defaultDomain": "qiming",    // default star domain (qiming/auto/explicit name)
-    "visionModel": {              // vision bridge: describe images when the primary model is text-only
-      "provider": "minimax",      // must have a key configured and declare supportsVision
+    "defaultDomain": "qiming",    // default star domain (qiming | auto | explicit domain id)
+    "visionModel": {              // vision bridge when primary model is text-only
+      "provider": "minimax",
       "model": "MiniMax-M3"
     },
-    "visionAutoBridge": false,    // auto-pick a vision model when visionModel is unset (off by default)
-    "imageGenModel": {            // text-to-image slot: register an endpoint, then call generate_image
-      "provider": "siliconflow-image",  // registered separately — provider.default stays untouched
+    "visionAutoBridge": false,
+    "imageGenModel": {            // dedicated text-to-image slot
+      "provider": "siliconflow-image",
       "model": "black-forest-labs/FLUX.2-pro",
-      "size": "1024x1024",        // default size (optional)
-      "sizeField": "image_size"   // OpenAI sends size, SiliconFlow sends image_size (optional)
+      "size": "1024x1024",
+      "sizeField": "image_size"
     },
-    "permissions": {              // permission rules (mirrors /permission commands)
+    "permissions": {
       "allow": [{ "tool": "read" }],
       "deny":  [{ "tool": "bash", "params": { "command": "rm -rf" } }],
       "bash": { "allowlist": ["git status"], "denylist": ["git push"] }
@@ -1004,127 +767,37 @@ Write only the fields you want to override; defaults are deep-merged. Full schem
   },
   "compact": {
     "enabled": true,
-    "autoThreshold": 800000       // token threshold that triggers auto-compaction
+    "autoThreshold": 800000
   },
   "tools": {
-    "preset": "frontend"          // minimal | frontend (default) | full | taiyi
+    "preset": "minimal"           // minimal (default) | frontend | full | taiyi
   },
   "workers": {
-    "profiles": {                 // custom worker model tiers
+    "profiles": {
       "capable": { "provider": "deepseek", "model": "deepseek-v4-pro" },
       "cheap":   { "provider": "minimax",  "model": "MiniMax-M2.7" }
     },
     "routing": { "code_edit": "capable", "repo_summarization": "cheap" },
-    "patcherTier": "cheap"        // Tianliang execution-worker default tier: cheap | balanced | strong
+    "patcherTier": "cheap"
   },
   "search": {
-    "backends": ["bing", "duckduckgo"],  // web_search backend chain (first hit wins)
-    "braveApiKeyEnv": "BRAVE_API_KEY"    // env var name when using Brave
+    "backends": ["bing", "duckduckgo"],
+    "braveApiKeyEnv": "BRAVE_API_KEY",
+    "tavilyApiKeyEnv": "TAVILY_API_KEY",
+    "bochaApiKeyEnv": "BOCHA_API_KEY",
+    "serplyApiKeyEnv": "SERPLY_API_KEY"
   },
   "ui": {
-    "theme": "auto",              // builtin name | auto (OSC 11 detect) | custom:<name>
-    "reducedMotion": true,        // a11y: freeze spinner/badge animations
-    "screenReader": true,         // a11y: screen-reader mode (same as --screen-reader)
-    "glanceDensity": "compact"    // GlanceBar density: compact | full
+    "theme": "auto",
+    "reducedMotion": true,
+    "screenReader": true,
+    "glanceDensity": "compact",
+    "cvmNotices": "intercept",
+    "cvmNoticeWindowMs": 8000
   },
-  "mirrors": { "enabled": true, "preset": "china" },  // npm/github mirror acceleration
-  "env": { "extraPath": ["/usr/local/bin"] }           // inject PATH (Windows git-bash, etc.)
+  "mirrors": { "enabled": true, "preset": "china" },
+  "env": { "extraPath": ["/usr/local/bin"] }
 }
 ```
 
-> Config layering priority: CLI flag > env var > project `.rivet-config.json` > user `~/.rivet/config.json` > built-in defaults.
-
-
-
-## 📚 Documentation
-
-| Doc | Description |
-|-----|-------------|
-| [`docs/user-guide.md`](docs/user-guide.md) | Install, configure, and usage guide |
-| [`docs/desktop-guide.md`](docs/desktop-guide.md) | Desktop user guide (Cockpit/SideChat/Rewind/themes/Mirror exclusives) |
-| [`docs/user-guide-provider-config.md`](docs/user-guide-provider-config.md) | Model provider configuration guide |
-| [`docs/user-guide-vision.md`](docs/user-guide-vision.md) | Vision channel: configuration and troubleshooting |
-| [`docs/user-guide-sandbox-permissions.md`](docs/user-guide-sandbox-permissions.md) | Full sandbox & permission model guide |
-| [`docs/reference/observability-harness.md`](docs/reference/observability-harness.md) | Observability harness: real-session data samples (cache / CVM / pheromones) with reproduction commands |
-| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contributing guide |
-| [`config.example.json`](config.example.json) | Example config (with sub-agent / review model routing) |
-
-## 🤝 Community & Support
-
-- **Usage questions / discussions** → [GitHub Discussions](https://github.com/huiliyi37/Tianshu-harness/discussions)
-- **Discord community** → [Join the Tianshu Harness Discord](https://discord.gg/XjWTATCHB)
-- **Bug reports / feature requests** → [GitHub Issues](https://github.com/huiliyi37/Tianshu-harness/issues)
-- **Security vulnerabilities** → [Report privately](https://github.com/huiliyi37/Tianshu-harness/security/advisories/new) (do not open a public issue)
-- **Contributing** → See [CONTRIBUTING.md](CONTRIBUTING.md)
-- **Support guide** → See SUPPORT.md
-- **WeChat group** → 「天枢 harness 交流群5群」 — scan the QR code below to join (QR codes expire every 7 days; leave a note in Discussions once expired):
-
-<img src="docs/brand/assets/wechat-group-qr.png" width="280" alt="Tianshu Harness WeChat group 5 QR code">
-
-> Note: a maintainer needs to enable Discussions in `Settings → General → Discussions` first.
-
-## ⭐ Star History
-
-<a href="https://star-history.com/#huiliyi37/tianshu-harness&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=huiliyi37/tianshu-harness&type=Date" width="700" />
-  </picture>
-</a>
-
-## ☕ Support
-
-If Tianshu has been useful and you'd like to say thanks, you can. It stays a coffee, not a contract — donations don't buy feature priority or change how issues get triaged.
-
-- **China mainland** — WeChat Pay (scan the QR code below)
-
-<img src="docs/brand/assets/wechat-donate.png" width="240" alt="WeChat Pay">
-
-## ✨ Contributors
-
-Thank you to everyone who has contributed to Tianshu (ordered by first contribution):
-
-| Contributor | Contributions |
-|-------------|---------------|
-| [@huiliyi37](https://github.com/huiliyi37) | Project creator · Core development |
-
-Full list (22 external contributors / 145 PRs) → CONTRIBUTORS.md.
-
-External PRs land via a "port" flow; authorship is credited with `Co-authored-by`
-trailers (auto-recorded by scripts/credit-contributors.sh) — contributor wall (full list in CONTRIBUTORS.md):
-
-<p>
-<a href="https://github.com/HarriethWiKk"><img src="https://github.com/HarriethWiKk.png?size=100" width="50" height="50" alt="HarriethWiKk" title="HarriethWiKk" /></a>
-<a href="https://github.com/jiangsx496"><img src="https://github.com/jiangsx496.png?size=100" width="50" height="50" alt="jiangsx496" title="jiangsx496" /></a>
-<a href="https://github.com/yq04"><img src="https://github.com/yq04.png?size=100" width="50" height="50" alt="yq04" title="yq04" /></a>
-<a href="https://github.com/wangxx-yu"><img src="https://github.com/wangxx-yu.png?size=100" width="50" height="50" alt="wangxx-yu" title="wangxx-yu" /></a>
-<a href="https://github.com/qiaodier"><img src="https://github.com/qiaodier.png?size=100" width="50" height="50" alt="qiaodier" title="qiaodier" /></a>
-<a href="https://github.com/zhengbiaofeng"><img src="https://github.com/zhengbiaofeng.png?size=100" width="50" height="50" alt="zhengbiaofeng" title="zhengbiaofeng" /></a>
-<a href="https://github.com/LinHoMo"><img src="https://github.com/LinHoMo.png?size=100" width="50" height="50" alt="LinHoMo" title="LinHoMo" /></a>
-<a href="https://github.com/KinoGao"><img src="https://github.com/KinoGao.png?size=100" width="50" height="50" alt="KinoGao" title="KinoGao" /></a>
-<a href="https://github.com/liuwanwan1"><img src="https://github.com/liuwanwan1.png?size=100" width="50" height="50" alt="liuwanwan1" title="liuwanwan1" /></a>
-<a href="https://github.com/Eason412"><img src="https://github.com/Eason412.png?size=100" width="50" height="50" alt="Eason412" title="Eason412" /></a>
-<a href="https://github.com/maoqiu77"><img src="https://github.com/maoqiu77.png?size=100" width="50" height="50" alt="maoqiu77" title="maoqiu77" /></a>
-<a href="https://github.com/yeshilei-QWQ"><img src="https://github.com/yeshilei-QWQ.png?size=100" width="50" height="50" alt="yeshilei-QWQ" title="yeshilei-QWQ" /></a>
-<a href="https://github.com/lumos-tiamo"><img src="https://github.com/lumos-tiamo.png?size=100" width="50" height="50" alt="lumos-tiamo" title="lumos-tiamo" /></a>
-<a href="https://github.com/zzuu080603"><img src="https://github.com/zzuu080603.png?size=100" width="50" height="50" alt="zzuu080603" title="zzuu080603" /></a>
-<a href="https://github.com/nzz0991999-ai"><img src="https://github.com/nzz0991999-ai.png?size=100" width="50" height="50" alt="nzz0991999-ai" title="nzz0991999-ai" /></a>
-<a href="https://github.com/L4XB"><img src="https://github.com/L4XB.png?size=100" width="50" height="50" alt="L4XB" title="L4XB" /></a>
-<a href="https://github.com/Wanming08"><img src="https://github.com/Wanming08.png?size=100" width="50" height="50" alt="Wanming08" title="Wanming08" /></a>
-<a href="https://github.com/lei454577-web"><img src="https://github.com/lei454577-web.png?size=100" width="50" height="50" alt="lei454577-web" title="lei454577-web" /></a>
-<a href="https://github.com/jian-in"><img src="https://github.com/jian-in.png?size=100" width="50" height="50" alt="jian-in" title="jian-in" /></a>
-<a href="https://github.com/sky-mirrors"><img src="https://github.com/sky-mirrors.png?size=100" width="50" height="50" alt="sky-mirrors" title="sky-mirrors" /></a>
-<a href="https://github.com/moyan3691"><img src="https://github.com/moyan3691.png?size=100" width="50" height="50" alt="moyan3691" title="moyan3691" /></a>
-<a href="https://github.com/EarthxxRhythm"><img src="https://github.com/EarthxxRhythm.png?size=100" width="50" height="50" alt="EarthxxRhythm" title="EarthxxRhythm" /></a>
-</p>
-
-> Contributions are welcome — see CONTRIBUTING.md.
-
-## License
-
-Licensed under the [Apache License, Version 2.0](LICENSE). Copyright 2025-2026 Tianshu Contributors.
-
-## Acknowledgments
-
-- The desktop app's custom-wallpaper and per-surface glass **design** references <a href="https://github.com/elysia395/dsh-wallpaper-engine">dsh-wallpaper-engine</a> (MIT License). The implementation is original and contains no upstream code; see <a href="THIRD-PARTY-NOTICES.md">THIRD-PARTY-NOTICES.md</a> for the design scope and license text.
+</details>