@te-river/opencode-team-mode 1.5.6 → 1.5.8

package/README.md

@@ -6,68 +6,108 @@
 [![npm downloads](https://img.shields.io/npm/dm/@te-river/opencode-team-mode.svg)](https://www.npmjs.com/package/@te-river/opencode-team-mode)
 [![license](https://img.shields.io/npm/l/@te-river/opencode-team-mode.svg)](./LICENSE)
 
-> 🤝 **Multi-agent team collaboration plugin for [OpenCode Desktop](https://opencode.ai)**
+> 🤝 **Your OpenCode just hired a team.**
 >
-> Adds a complete team of specialized AI agents — Architect, Implementer, Reviewer, Tester, Researcher — orchestrated by a Team Lead, all accessible via simple slash commands.
+> Six specialized agents — a Lead, an Architect, an Implementer, a Reviewer, a Tester and a Researcher — with governed tools, structured handoffs, and a plan-first approval gate. One plugin, zero config files to copy.
+
+> 💡 **Best for medium-to-large projects.** The governance layer (approval gate, context offload, tool allowlists) is an asset once a codebase has real surface area — and mostly overhead on tiny scripts and one-off questions. Use it where the work is.
+
+---
+
+## TL;DR — skip the docs
+
+> **The lazy path:** paste this to any coding agent and let it do the work:
+>
+> ```text
+> Install the OpenCode plugin @te-river/opencode-team-mode following
+> https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/docs/installation.md
+> Then verify the install using the checks in that guide.
+> ```
+>
+> **The one command to remember afterwards:** `/team-run <task>` — the Team Lead
+> plans it, shows you the plan, waits for your approval, then runs the whole team.
+
+Everything else below is detail. When you're ready for it, here's the map:
+
+**[Why](#-why-teammode) · [The team](#-the-team) · [Install](#-install) · [Usage](#-usage) · [Tools & security](#-governed-tools--security) · [Search](#-web-search-that-actually-works-in-china) · [Config](#️-configuration) · [How it works](#-how-the-team-works) · [FAQ](#-faq) · [Uninstall](#-uninstall)**
 
 ---
 
-## ✨ What is TeamMode?
+## 🤔 Why TeamMode?
 
-TeamMode transforms OpenCode Desktop from a single-agent coding assistant into a **full development team**. Each agent has a distinct role, expertise, and personality — just like a real engineering team.
+Because a single agent doing everything is how you get: a context window stuffed
+with 5000-line file dumps, twenty round-trips to `bash` for what one script could
+do, sub-agents that silently read `.env`, and web "research" that is really just
+the model's imagination.
 
-Instead of one agent trying to do everything, you get:
+TeamMode's answer to each:
+
+| Pain | TeamMode's answer |
+|---|---|
+| 🔥 **Context flooding** | Every governed tool output over 2000 tokens is offloaded to a local run store and replaced by an 80-token preview + an HMAC handle. The agent pages through what it needs — the window never drowns. |
+| 🐌 **Round-trip overhead** | `tm_ptc_run`: the agent writes ONE program that makes N governed calls in a single turn. Zero LLM round-trips during the run. |
+| 🕳️ **Silent side effects** | R6/R2 approval gate: env-var reads and dangerous ops route through OpenCode's official confirmation dialog, auto-rejected after 10 unanswered minutes. The plugin never approves on its own — it only ever rejects. |
+| 🌫️ **Hallucinated research** | Web access is a two-role grant with an allowlisted, governed tool chain. A fact that couldn't be fetched is reported as a gap — never fabricated. |
+
+And the workflow discipline underneath: deterministic routing, a ≤30-line plan
+you approve before ≥2 dispatches execute, structured `STATUS/CHANGES/FINDINGS/
+EVIDENCE/HANDOFF` replies between agents, and static verification (build /
+typecheck / tests) instead of vibes.
+
+That discipline is also why the recommendation is **medium-to-large
+projects**: on a two-file script the team simply has less to govern.
+
+---
+
+## 👥 The team
 
 | Agent | Role | When to use |
 |---|---|---|
-| 🎯 **Team Lead** | Orchestrator | Complex tasks that need planning + multi-step execution |
+| 🎯 **Team Lead** (`@team`) | Orchestrator | Complex tasks that need planning + multi-step execution |
 | 🏗️ **Architect** | System designer | Design docs, module structure, API contracts |
 | 💻 **Implementer** | Code writer | Building features, writing production code |
-| 🔍 **Reviewer** | Dimension-focused auditor | Single-dimension review (completeness / correctness / impact) — ONE reviewer by default; 3 in parallel only for high-risk changes |
-| 🧪 **Tester** | Test engineer | Unit tests, integration tests, edge-case coverage, static verification (build / typecheck / lint / API tests) |
-| 🔎 **Researcher** | Knowledge finder | Local-repo investigation first (code, configs, installed packages, shipped docs); web lookups via user MCP tools or the governed `tm_webfetch` — one of the two network roles (with the Team Lead) |
-
----
+| 🔍 **Reviewer** | Dimension-focused auditor | Single-dimension review by default; 3 in parallel only for high-risk changes |
+| 🧪 **Tester** | Test engineer | Tests with real edge cases; static verification (build / typecheck / lint); governed UI verification via `tm_browser` |
+| 🔎 **Researcher** | Knowledge finder | Local repo first, then the web — one of the two network roles (with the Lead) |
 
-## 🚀 Quick Start
+Out of the box, **Team is your default agent** — new chats open straight into the
+orchestrator (opt-out in [Configuration](#-configuration)).
 
-### Prerequisites
-
-1. **Install OpenCode Desktop** (if you haven't already):
+---
 
-   | Platform | Install command |
-   |---|---|
-   | macOS (Apple Silicon) | `brew install --cask opencode-desktop` |
-   | macOS (Intel) | `brew install --cask opencode-desktop` |
-   | Windows | `scoop bucket add extras && scoop install extras/opencode-desktop` |
-   | Linux | Download from [opencode.ai/download](https://opencode.ai/download) |
+## 📦 Install
 
-   Or install the **CLI/TUI** version:
-   ```bash
-   # one-line script (all platforms)
-   curl -fsSL https://opencode.ai/install | bash
+### Option 1 — Let your agent do it (recommended)
 
-   # or via npm
-   npm install -g opencode-ai
-   ```
+Copy this into any coding agent — it will edit your config, restart-remind you, and verify:
 
-2. **Node.js ≥ 18** (for npm)
+```text
+Install the OpenCode plugin @te-river/opencode-team-mode following
+https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/docs/installation.md
+(If that URL is unreachable — common on mainland-China networks — retry with
+the mirror prefix: https://ghproxy.net/ + the same path.)
+Then verify the install using the checks in that guide.
+```
 
-### Install TeamMode
+(The guide is the complete manual procedure — config file locations, plugin
+entry, restart, verification, update and uninstall. Your agent reads it and
+executes it faithfully; there is nothing else it needs.)
 
-**Option A — One-line installer:**
+### Option 2 — One-line script
 
 macOS / Linux (bash):
+
 ```bash
 curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.sh | bash
 ```
 
 Windows (PowerShell):
+
 ```powershell
 irm https://ghproxy.net/https://raw.githubusercontent.com/Te-River/Opencode-TeamMode/main/scripts/install.ps1 | iex
 ```
 
-**Option B — Manual config:**
+### Option 3 — Manual
 
 Add the plugin to your `opencode.jsonc`:
 
@@ -80,101 +120,54 @@ Add the plugin to your `opencode.jsonc`:
 }
 ```
 
-OpenCode will automatically install the plugin on startup.
-
-> **Tip:** After modifying `opencode.json`, **restart OpenCode Desktop** for changes to take effect.
-
----
+OpenCode installs the plugin on next startup.
 
-## ⚙️ Configuration
+### ⚠️ Read this once, save yourself an hour later
 
-The plugin automatically injects all team agents and commands when OpenCode starts. **No need to manually copy agent files or command definitions.**
+- **Restart to activate.** After touching `opencode.json`, fully quit and restart OpenCode (Desktop: quit from tray, not just the window).
+- **Plugin updates: re-run the installer.** It is idempotent — a re-run re-patches the config (no-op when present), purges the stale plugin cache, and re-resolves any npm-installed copy. This exists because OpenCode caches plugins by spec string and does NOT re-resolve `@latest` when a new version publishes (upstream limitation). Manual recipe, if you prefer:
 
-> ⚠️ **Model choice matters.** Every judgment in the workflow — triage,
-> decomposition, dispatch briefs, synthesis, review-loop verdicts — flows
-> through the **Team Lead**. A weak model in that seat degrades the whole
-> pipeline no matter how strong the specialists are. Pin your best
-> reasoning model to the `team` agent (recipe in
-> [Customization](#customization) below).
+  | OS | Cache location |
+  |---|---|
+  | macOS / Linux | `rm -rf ~/.cache/opencode/packages/@te_river+opencode-team-mode@latest` |
+  | Windows | `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\opencode\cache\packages\@te_river+opencode-team-mode@latest"` |
 
-### Global install (all projects)
+  If you also npm-installed the plugin into `~/.config/opencode`, its package-lock pins the version — run `npm install @te-river/opencode-team-mode@latest` there too. Full recipe (including an agent-driven update prompt): [installation guide, Updating](./docs/installation.md).
+- **Prerequisites:** [OpenCode](https://opencode.ai) (Desktop or CLI) and Node ≥ 18.
 
-To enable TeamMode in every project, add the plugin to your global config:
+### Verify
 
-```jsonc
-// ~/.config/opencode/opencode.jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "@te-river/opencode-team-mode@latest"
-  ]
-}
-```
+Restart, open the agent picker, and look for **team, architect, implementer,
+reviewer, tester, researcher**. That's it — the team is hired.
 
 ---
 
 ## 📖 Usage
 
-### Slash Commands
-
-TeamMode adds six slash commands to OpenCode. Type them in the chat input:
+### Slash commands
 
 | Command | Agent | Description |
 |---|---|---|
-| `/team-plan <task>` | Architect | Create a detailed implementation plan with architecture, file manifest, and task breakdown |
-| `/team-implement <task>` | Implementer | Write production code for a feature or task |
-| `/team-review [scope]` | Reviewer | Audit code for bugs, security issues, and quality problems |
-| `/team-test [scope]` | Tester | Generate comprehensive tests with edge-case coverage |
-| `/team-research <topic>` | Researcher | Investigate the local repository first; web lookups via the governed `tm_browser` / `tm_webfetch`, then user MCP tools |
-| `/team-run <task>` | Team Lead | **Full workflow** — orchestrates all agents end-to-end |
-
-#### Example workflow
-
-```
-# 1. Plan the feature
-/team-plan Add user authentication with OAuth2 and JWT tokens
-
-# 2. Review the plan, then implement
-/team-implement Implement the auth module as planned
-
-# 3. Review the code
-/team-review src/auth/
-
-# 4. Write tests
-/team-test src/auth/
-
-# Or let the team lead handle everything:
-/team-run Add user authentication with OAuth2 and JWT tokens
-```
+| `/team-plan <task>` | Architect | Implementation plan with architecture, file manifest, task breakdown |
+| `/team-implement <task>` | Implementer | Production code for a feature or task |
+| `/team-review [scope]` | Reviewer | Audit for bugs, security issues, quality problems |
+| `/team-test [scope]` | Tester | Comprehensive tests with edge-case coverage |
+| `/team-research <topic>` | Researcher | Local repo first; web via the governed tools |
+| `/team-run <task>` | Team Lead | **The full workflow** — plan → approval → orchestration → verification |
 
-### Agent Picker
+Or `@`-mention agents directly: `@team`, `@architect`, `@implementer`,
+`@reviewer`, `@tester`, `@researcher`.
 
-You can also invoke agents directly using the `@` mention in OpenCode Desktop:
+### What a run feels like
 
-- `@team` — Orchestrate a complex task
-- `@architect` — Design a system or module
-- `@implementer` — Write code
-- `@reviewer` — Review code quality
-- `@tester` — Write tests
-- `@researcher` — Research a topic
+Team is the default agent out of the box, so you just type into a fresh chat:
 
-### Demo
-
-A session transcript, recreated from how the flow actually looks. Team is the
-default agent out of the box (see Configuration to opt out), so the user just
-types into a fresh chat:
-
-> **User:** Add token-bucket rate limiting to our Express API — 100 requests
-> per minute per user, return 429 when exceeded. Don't touch anything under
-> `src/legacy/`.
+> **You:** Add token-bucket rate limiting to our Express API — 100 requests per minute per user, return 429 when exceeded. Don't touch anything under `src/legacy/`.
 
 ```text
 team   Route: product behavior change → implementer → tester → reviewer
        (3 dispatches → approval gate applies)
 
-       Research: read README, src/app.ts, src/middleware/*
-       Blocking questions: none — 1 assumption listed below
-
        PLAN
        Goal: token-bucket limiter, 100 req/min/user, 429 + Retry-After
        Scope: src/middleware/rateLimit.ts (new), src/app.ts (+3 lines)
@@ -183,38 +176,25 @@ team   Route: product behavior change → implementer → tester → reviewer
        Boundary: src/legacy/** untouched
        Approve to proceed?
 
-user   approved, go
+you    approved, go
 
 team   ▸ @implementer — STATUS: done
        CHANGES: src/middleware/rateLimit.ts (new) · src/app.ts (+3)
-       HANDOFF: bucket {tokens, lastRefill}; refill() is a single atomic pass
-       EVIDENCE: tsc clean (output above)
+       EVIDENCE: tsc clean
 
        ▸ @tester — STATUS: done · VERDICT: pass (14/14)
        FINDINGS: burst edge, window expiry, concurrent refill covered;
                  src/legacy/** byte-identical
-       EVIDENCE: vitest 14 passed
 
        ▸ @reviewer — STATUS: done · VERDICT: approve (correctness)
-       FINDINGS: no Critical/Major; 1 Minor (log line noise) noted
 
-team   Done.
-       rate limiter shipped: rateLimit.ts (new) · app.ts (+3) · 14 tests green
+team   Done. rateLimit.ts (new) · app.ts (+3) · 14 tests green
        review: approve · assumption: in-memory only · src/legacy/ untouched
 ```
 
-The only message the user typed was the task and "approved, go". The
-pipeline was a routing-table lookup, execution waited for plan approval,
-and every handoff traveled as a structured skeleton — no file ceremony.
-
-### Desktop-specific features
-
-In **OpenCode Desktop**, you get additional UX benefits:
-
-- 🎨 **Color-coded agents** — Each agent has a distinct color in the chat UI for easy identification.
-- 📋 **Agent picker** — Click the agent dropdown to switch between team agents visually.
-- 🔀 **Parallel sub-tasks** — The Team Lead can dispatch multiple sub-agents simultaneously, with results shown in parallel panels.
-- 📊 **Session history** — All team interactions are saved and searchable in the Desktop session sidebar.
+You typed the task and four words. The plan was a routing-table lookup,
+execution waited for your approval, and every handoff between agents traveled
+as a structured skeleton — nothing landed in your repo, nothing was guessed.
 
 ---
 
@@ -224,385 +204,159 @@ Every tool TeamMode adds runs under ONE governance pipeline: outputs above
 `TM_OFFLOAD_THRESHOLD` tokens never enter the context window — they are
 offloaded to a run store and replaced by a content-aware preview plus an
 HMAC-signed handle that the agent pages through with `tm_fetch` when it
-genuinely needs the payload. Security, memory and web access shipped
-across v1.5.1–v1.5.6; see [CHANGELOG.md](./CHANGELOG.md) for the history.
+genuinely needs the payload.
 
 | Tool | What it does | Roles |
 |---|---|---|
-| `tm_read` / `tm_grep` / `tm_bash` / `tm_fetch` | Governed file read / regex search (host index) / read-only shell (allowlist) / paged handle retrieval | all six agents |
-| `tm_memory` | Project memory store (Markdown + frontmatter): add / search / list / forget | all six agents |
-| `tm_webfetch` | Single governed GET of an allowlisted web page | Lead + Researcher |
-| `tm_browser` | Interactive browser session (headful CDP): open / navigate / read / screenshot / close | Lead + Researcher |
+| `tm_read` / `tm_grep` / `tm_bash` / `tm_fetch` | Governed file read / regex search / read-only shell (allowlist) / paged handle retrieval | all six agents |
+| `tm_memory` | Project + global memory store (Markdown + frontmatter): add / search / list / forget | all six agents |
 | `tm_ptc_run` | Batch orchestration: one program, N governed calls, zero LLM round-trips | all six agents |
+| `tm_search` | Multi-engine web search with extracted, deduplicated hit lists | Lead + Researcher |
+| `tm_webfetch` | Single governed GET of an allowlisted page (search pages auto-extracted) | Lead + Researcher |
+| `tm_browser` | Interactive browser session (headful CDP): open / navigate / read / screenshot / close | Lead + Researcher + Tester (UI verification) |
 
 > **Fixed tool priority ladder (every task): ① TeamMode governed tools
-> (`tm_*`) → ② user MCP/plugin tools → ③ the model's own reasoning
-> (a missing capability is reported as a gap, never fabricated).**  The
-> ladder is also a fallback chain: when a governed tool errors (no browser
-> on this host, blocked host), the agent says so and drops to the next
-> rung instead of giving up.
+> (`tm_*`) → ② user MCP/plugin tools → ③ the model's own reasoning.**
+> It doubles as the fallback chain: when a governed tool errors (no browser
+> on this host, blocked host), the agent says so and drops to the next rung.
 
-Agents are prompted to route every lookup through these tools — scan the
-tool surface, plan the concrete call, expand colloquial or abbreviated
-terms to canonical forms and search both spellings — instead of answering
-from memory or simulating removed tools.
+All governed tools are **parallel-safe**: the host may run a batch of
+`tm_search` / `tm_webfetch` / `tm_fetch` calls concurrently — each call gets
+its own step id and its own payload, and nothing cross-contaminates
+(proven by the parallel test suite).
 
 ### Context governance: offload, handles, previews
 
-**JIT layer-2 tools (`tm_read` / `tm_grep` / `tm_bash` / `tm_fetch`).**
-Large tool outputs are context cost's main driver: every step re-sends the
-whole window. The tm_* tools run the built-in capability under governance
-first: results above `TM_OFFLOAD_THRESHOLD` tokens never enter the window —
-they are written to a local run store and replaced by a handle with a
-content-aware preview (JSON keys / CSV header+shape / log ERROR×N stats /
-code signatures / binary metadata, hard-capped at 80 tokens). When the agent
-actually needs the payload it pages through it with `tm_fetch`, using an
-HMAC-signed, run-scoped, expiring handle. `tm_bash` only allows read-only
-commands (allowlist), and failures come back as structured errors instead of
-raw dumps. Agents are prompted to route every lookup through these tools —
-scan the tool surface, plan the concrete call, expand colloquial or
-abbreviated terms to canonical forms and search both spellings — instead of
-answering from memory or simulating removed tools.
-
-### Project memory (tm_memory)
-
-**Project memory (`tm_memory`) — all agents.**  Durable project facts
-(build commands, environment quirks, architecture decisions, user
-conventions that outlive one conversation) live as Markdown files with
-frontmatter under the same git-aware store
-(`<repo>/.git/opencode-team/memories/<project-slug>/<category>/`) —
-human-editable, never in your working tree.  `add` / `search`
-(deterministic keyword scoring, top 5) / `list` / `forget`; content is
-capped at 4000 chars per memory — task state belongs to the todo list,
-oversized docs to board files.  Agents are prompted to search before
-assuming project conventions and to save hard-won facts for the next
-conversation.
-
-### Web access (tm_browser + tm_webfetch) — network roles only
-
-1. **Governed web tools.**  `tm_browser` — an interactive browser session
-   driving **your own Chromium-family browser** (Edge probed first on
-   Windows) headful via the CDP pipe protocol: open → navigate → read
-   (page text, threshold-governed like tm_read) → screenshot (PNG saved
-   to the run store, only the path enters context) → close.  Isolated
-   temp profile (never your real one); the **domain allowlist is enforced
-   at the network layer** per request (CDP `Fetch.requestPaused` —
-   non-allowlisted hosts get `BlockedByClient`).  Display-less Linux
-   hosts run headless automatically; `TM_BROWSER_HEADLESS` forces either
-   way, `TM_BROWSER_PATH` points at a specific executable.  `tm_webfetch`
-   — a single governed GET of an allowlisted page.  Both ride the same
-   governance as every tm_* tool (threshold offload + content-aware
-   preview + `tm_fetch` handle), so a web page can never flood the
-   context.
-2. **User MCP/plugin tools.**  Browser automation, search or fetch tools
-   from user-configured MCP servers are the fallback for what the
-   governed tools cannot do — the whitelist never touches them.
-3. The other four agents (architect / implementer / reviewer / tester)
-   have NO network grant — web questions are reported as a gap, never
-   simulated.  The built-in webfetch/websearch tools stay removed; remote
-   `.env`-style URLs are refused (R6 red line).
-
-Seeded allowlist hosts (both web tools): `mobile.moegirl.org.cn` (wiki
-term), `search.bilibili.com`, `cn.bing.com`, `www.baidu.com` (search URL
-templates); extend via `TM_WEBFETCH_ALLOWED_DOMAINS` (`"*"` opens every
-host).
-
-Seeded allowlist hosts (both web tools): `mobile.moegirl.org.cn` (wiki
-term), `search.bilibili.com`, `cn.bing.com`, `www.baidu.com` (search URL
-templates); extend via `TM_WEBFETCH_ALLOWED_DOMAINS` (`"*"` opens every
-host).
-
-### Security: R6 + R2 approval gate
-
-**R6 environment protection (now an approval gate).** With TeamMode active,
-the model cannot read environment variables silently. Env-var reads
-(`printenv`, `env`, `Get-ChildItem env:`, …) and env files (`.env`, shell rc
-files) route through OpenCode's **official confirmation dialog**: you get a
-native prompt to approve or deny, and an unanswered prompt is **auto-rejected
-after `TM_ASK_TIMEOUT_MIN` (default 10 min)** — the plugin only ever rejects
-on timeout, never approves on the model's behalf. Env reads that no wildcard
-can express (embedded `$VAR` / `${VAR}` / `$env:` inside another command,
-command substitution, subshell/escaped forms) and the `tm_*` wrapper channel
-stay a **hard block** (no dialog to slip through). tm_* wrappers route through
-the same checks (no backdoor via the wrappers). Audit lines record only tool
-name + pattern category + the verdict (`ask` / `allowed-once` /
-`allowed-always` / `rejected` / `timeout-rejected` / `degraded`) — never
-command text, paths, variable names or values.
-
-**R2 dangerous operations (same dialog).** Delete (`rm`/`del`/`Remove-Item`/
-`rmdir`), git publishing (`git push`/`git commit`), network fetch (`curl`/
-`wget`/`Invoke-WebRequest`/`Invoke-RestMethod`), package installs/publishes
-(`npm install`/`npm publish`/`pip install`/`winget`/`choco`), process/system
-(`taskkill`/`Stop-Process`/`kill`/`shutdown`/`format`) and privilege changes
-(`chmod`/`takeown`/`icacls`) — none are silently allowed. They pop the same
-official dialog and are auto-rejected if you don't answer within the timeout.
-The normal verification stack (`npm test`, `tsc`, `git status`/`diff`) is NOT
-gated, so day-to-day team work runs without interruption.
-
-> ⚠️ **When you approve a dialog, pick "once" — not "always".** Verified on
-> the live host, "always" records a far broader rule than the command you
-> saw: approving `Get-ChildItem env:PATH` with "always" stores `Get-ChildItem
-> *`, so every later `Get-ChildItem` runs with no dialog at all. Only the
-> once-verdict keeps each gated operation individually human-checked.
-> (If you do pick "always" on an env dialog, TeamMode scopes it to the
-> current session — and env-FILE reads such as `cat .env` stay hard-blocked
-> regardless: no dialog ever backs them, so no "always" can consent to them.)
-
-> Deferral is per-session: env reads only route to the dialog in sessions
-> running TeamMode's injected agents (or after such a session has shown one
-> of these dialogs). In any other session (e.g. a stock `build`/`plan` chat)
-> TeamMode's guard keeps hard-blocking env reads, since no dialog would back
-> them there. Within one session, a user prompt routed to a non-injected
-> agent REVOKES that eligibility (the per-turn agent signal rides
-> `message.updated`; the verified host passes NO agent to
-> `tool.execute.before`). Compound commands (`a; b`) are evaluated per segment by the
-> host and approved through one dialog; the guard blocks them outright
-> whenever any segment is an env read.
-
-> The permission protocol was verified against a live `opencode serve` host
-> (1.18.29) via SSE event capture; the Desktop dialog rendering itself is the
-> one leg that still needs eyeballing in a real Desktop session. Headless
-> `opencode run` auto-rejects an unanswered `ask` immediately (there is no
-> human to prompt).
-
-### Repo hygiene & path semantics
-
-> **Repo hygiene.** The offload/trajectory stores live under
-> `<repo>/.git/opencode-team/` (or the OS temp dir outside a git repo) —
-> never your working tree. Every agent is instructed to delete scratch /
-> temporary files it created before reporting done, and to keep throwaway
-> work in the OS temp dir so nothing lands in the repo at all. `tm_read` /
-> `tm_grep` paths are relative to the **project root** (not the agent's
-> working directory).
-
-### Environment variables
-
-| Env var | Default | Purpose |
-|---|---|---|
-| `TM_ENV_PROTECT` | `strict` | R6 mode: `strict` / `standard` / `off` (off also disarms the approval timer) |
-| `TM_ASK_TIMEOUT_MIN` | `10` | minutes before an unanswered R6/R2 confirmation dialog is auto-rejected; minimum 3 minutes (the host's `permission.replied` reaches the plugin ~120 s late on the event bus — shorter values would auto-reject a just-approved request) |
-| `TM_ENV_PROTECT_EXTRA_DENY` | — | extra block patterns (regex list; always a hard block, never dialog-governed) |
-| `TM_OFFLOAD_THRESHOLD` | `2000` | offload threshold (tokens, CJK-aware estimate) |
-| `TM_PREVIEW_MAX_TOKENS` | `80` | preview hard cap |
-| `TM_FETCH_MAX_LINES` | `2000` | tm_fetch page cap |
-| `TM_BLACKBOARD_DIR` | `<repo>/.git/opencode-team/blackboard/` | offloaded payload store (tmpdir fallback outside a git repo; explicit value = absolute or project-relative) |
-| `TM_TRAJECTORY_DIR` | `<repo>/.git/opencode-team/trajectory/` | append-only tool-call ledger (tmpdir fallback outside a git repo) |
-| `TM_BLACKBOARD_TTL` | `7` | store retention (days) |
-| `TM_BASH_READONLY_ALLOWED` | built-in table | tm_bash allowlist |
-| `TM_WEBFETCH_ALLOWED_DOMAINS` | `mobile.moegirl.org.cn, search.bilibili.com, cn.bing.com, www.baidu.com` | tm_webfetch/tm_browser allowlist (`"*"` opens every host; explicit empty = deny all) |
-| `TM_BROWSER_PATH` | auto-detect | tm_browser executable override (Edge/Chrome/Chromium probed per OS) |
-| `TM_BROWSER_HEADLESS` | `auto` | tm_browser: `1` headless (servers/CI) / `0` headful / `auto` (headless only on display-less Linux) |
-| `TM_PTC_MAX_PROGRAM_CHARS` | `4000` | PTC program source length cap (chars) |
-| `TM_PTC_MAX_CALLS` | `20` | PTC per-run bridge-call budget (1–200) |
-| `TM_PTC_MAX_ERRORS` | `3` | PTC per-run error budget (1–50) |
-| `TM_PTC_TIMEOUT_MS` | `60000` | PTC per-run wall-clock timeout (5s–10min) |
-| `TM_PTC_ENGINE` | `auto` | PTC engine: `auto` (worker→inline degrade) / `worker` / `inline` |
-
-### Batch orchestration (tm_ptc_run)
+Large tool outputs are context cost's main driver — every step re-sends the
+whole window. So results above `TM_OFFLOAD_THRESHOLD` tokens are written to a
+local run store (`<repo>/.git/opencode-team/`, never your working tree) and
+replaced by a handle with a content-aware preview: JSON keys / CSV header +
+shape / log ERROR×N stats / code signatures / binary metadata, hard-capped at
+80 tokens. When the agent actually needs the payload, it pages through with
+`tm_fetch` using an HMAC-signed, run-scoped, expiring handle. `tm_bash` only
+allows read-only commands (allowlist), and failures come back as structured
+errors instead of raw dumps.
 
-`tm_ptc_run` lets a specialist agent write **one async program** that makes N
-governed `tm_*` calls in a single turn — zero LLM round-trips during the run,
-only an aggregation summary returns to context.  It is designed for batch
-read-only tasks: multi-file reconnaissance, bulk grep + read aggregation,
-cross-referencing search results.
+### Project + global memory (tm_memory)
 
-#### How it works
+Durable facts — build commands, environment quirks, architecture decisions,
+your conventions — live as human-editable Markdown with frontmatter:
 
-The agent writes a program body using `tm.read(args)`, `tm.grep(args)`,
-`tm.bash(args)`, `tm.fetch(args)` — same args as the four governed tools.
-Each call returns `{ok:true, data}` (governed: inline text or an offload
-handle) or `{ok:false, error:{tool,phase,line?,message}}`.  The program
-`return`s a value; it is JSON-serialized into the aggregation summary.
+- **`project`** (default): `<repo>/.git/opencode-team/memories/…` — per checkout, git-adjacent.
+- **`global`**: `~/.opencode-team/memories/global/` (override `TM_MEMORY_GLOBAL_DIR`) — **follows you across ALL projects**.
 
-Programs containing `require`, `import`, `process`, `globalThis`, `Deno`,
-`Bun`, `fs`, `net`, or `child_process` are rejected before execution (static
-pre-scan, auxiliary guard).
+Actions: `add` / `search` (deterministic keyword scoring) / `list` / `forget`;
+4000 chars per memory. Agents are prompted to search before assuming
+conventions and to save hard-won facts for the next conversation.
 
-#### Budgets (tighten-only)
+### 🌐 Web search that actually works (in China)
 
-The caller may tighten `max_calls`, `max_errors`, and `timeout_ms` — values
-above the `TM_PTC_*` ceilings are clamped down; values below the floor are
-clamped up.  Hitting any budget stops the whole run; produced output is NOT
-lost.
+`tm_search` is the open-ended-lookup front: **one call, one query, clean
+results**. The engine URL is built for you, fetched through the governed
+pipeline, and collapsed into a numbered title+URL hit list — the agent never
+sees raw SERP chrome.
 
-#### Engine (`TM_PTC_ENGINE`)
-
-| Mode | Behavior |
+| Engine | Notes |
 |---|---|
-| `auto` (default) | Tries `worker_threads` first; on engine failure it re-runs the WHOLE program on `node:vm` with a `degraded-engine` mark in the summary (bridged calls are read-only, so a re-run is safe; the fallback starts with fresh budgets under the same wall-clock deadline) |
-| `worker` | Forces the worker engine (engine-error on failure) |
-| `inline` | Forces the `node:vm` engine (script timeout kills pre-await synchronous busy-loops; a busy loop after the first `await` blocks the host event loop irrecoverably — prefer worker/auto) |
-
-The worker engine runs the program in a dedicated thread with `env:{}`
-(process.env emptied), `resourceLimits`, and hard wall-clock `terminate()`.
-All governance (P2 path scope, P3 allowlist, R6, threshold offload, TTL)
-applies to every bridged call — PTC is not a bypass layer.
+| `bing` (default) | cn.bing.com; `bing-int` forces international results (`ensearch=1`) |
+| `sogou` / `so` (360) | CN-native engines, good for CJK content |
+| `baidu` | flakiest (anti-bot) but sometimes the only CN-specific index; failures name alternatives |
+| `bilibili` | video search |
+| `moegirl` | MediaWiki search API — entry titles + snippets, structured |
+| `npm` | registry search → name@version + description, structured |
+| `github` | repo search API → stars + description, structured |
+
+All nine engines are reachable from mainland China **without API keys**, and
+every one of them sits on the seeded domain allowlist. On an empty result
+(an anti-bot shell), the error names the alternative engines instead of
+leaving the agent stuck. Two more channels complete the surface:
+
+- `tm_webfetch` — a known URL, one governed GET. Search-engine pages it
+  fetches are auto-extracted to hit lists too. JSON endpoints like
+  `registry.npmjs.org/<pkg>/latest` pass through untouched.
+- `tm_browser` — JS-rendered pages: your own Chromium-family browser, headful
+  via CDP pipe, isolated temp profile, **domain allowlist enforced at the
+  network layer** per request (`Fetch.requestPaused` → non-allowlisted hosts
+  get `BlockedByClient`).
+
+Seeded allowlist (both tools): `mobile.moegirl.org.cn`, `search.bilibili.com`,
+`cn.bing.com`, `www.bing.com`, `www.baidu.com`, `www.sogou.com`, `www.so.com`,
+`registry.npmjs.org`, `api.github.com`, `raw.githubusercontent.com`,
+`ghproxy.net` (mainland mirror for github raw) — extend via
+`TM_WEBFETCH_ALLOWED_DOMAINS` (`"*"` opens every host). Architect /
+implementer / reviewer have NO network grant — web questions come back as a
+reported gap, never simulated. The tester carries `tm_browser` ONLY, for
+governed UI verification of the project (local dev servers, preview routes);
+open web fetching stays with the two network roles.
+
+**Out-of-allowlist targets are a gate, not a wall.** When a fetch / search /
+browser-open points at a host outside the allowlist, the tool hands the URL
+to OpenCode's **official confirmation dialog** — you decide, once per
+target (an unanswered dialog is auto-rejected on the usual 10-minute timer,
+and the plugin still never self-allows). Every dialog also fires a
+**system toast notification**, so you know something is waiting even when
+you're not staring at the screen. Env-file URLs and non-http(s) schemes
+remain hard-rejected with no dialog — R6 red lines are never consentable.
+
+### Security: the R6 + R2 approval gate
+
+**R6 environment protection.** With TeamMode active, the model cannot read
+environment variables silently. Env reads (`printenv`, `env`, `Get-ChildItem
+env:`, …) and env files (`.env`, shell rc) route through OpenCode's official
+confirmation dialog; unanswered prompts are **auto-rejected after
+`TM_ASK_TIMEOUT_MIN` (default 10 min)**. Env reads no wildcard can express
+(embedded `$VAR` / `${VAR}` / `$env:` inside another command, command
+substitution) and the `tm_*` wrapper channel stay a **hard block** — no dialog
+to slip through. The audit log records only tool name + pattern category +
+verdict — never command text, paths, variable names or values.
+
+**R2 dangerous operations (same dialog).** Delete, git publish, network
+fetch, package install/publish, process/system, privilege changes — none are
+silently allowed. The normal verification stack (`npm test`, `tsc`,
+`git status`) is NOT gated, so day-to-day work runs uninterrupted.
 
-#### Access
-
-`tm_ptc_run` is in the whitelist of **all six** agents (the `team` lead
-included — v1.5.4 revised the original deny ruling).  Every bridged call
-still runs the full governed tm_* pipeline (P2 path scope, P3 allowlist, R6,
-threshold offload + handles, TTL), so batch orchestration is a convenience
-gain, not a governance gap.
-
----
-
-## 🏗️ Architecture
+> ⚠️ **When you approve a dialog, pick "once" — not "always".** Verified on
+> the live host, "always" records a far broader rule than the command you
+> saw: approving `Get-ChildItem env:PATH` with "always" stores `Get-ChildItem
+> *`, so every later `Get-ChildItem` runs with no dialog at all.
 
-```
-opencode-team-mode/
-├── package.json          ← npm package definition
-├── tsconfig.json         ← TypeScript config
-├── src/
-│   ├── index.ts          ← Plugin entry (server(): config + R6 tool.execute.before + approval-gate event + tool segment)
-│   ├── agents.ts         ← Agent structure (modes, colors, temperatures, whitelist matrix)
-│   ├── prompts/          ← The agent prompt strings (lead / specialists / shared) — pinned by tests
-│   ├── commands.ts       ← Command definitions (templates, agent bindings)
-│   ├── blackboard.ts     ← Shared blackboard + TTL auto-cleanup sweeper
-│   ├── envprotect.ts     ← R6 facade → envprotect/ (patterns / bash-classify / path-classify / gate-predicates / hook)
-│   ├── approval-gate.ts  ← Unified approval gate: host-dialog timeout auto-reject (never self-allows)
-│   ├── tm/               ← JIT layer-2 tools: pipelines / result / client-unwrap / shell-bridge / args-schema / tools / guard / preview / store / refs / config / webfetch / memory / browser / ptc/ (9 modules)
-│   └── types.ts          ← Loader-contract type definitions (1.18.x)
-├── scripts/
-│   ├── install.sh        ← One-click installer (bash)
-│   └── install.ps1       ← One-click installer (PowerShell)
-├── pt07/                 ← PT-07 baseline suite (seeded A/B token measurement)
-├── LICENSE               ← Apache 2.0
-├── README.md             ← English documentation
-└── README.zh-CN.md       ← Chinese documentation
-```
+> Deferral to the dialog is per-session: env reads only route to the dialog
+> in sessions running TeamMode's injected agents. In any other session the
+> guard keeps hard-blocking env reads. `headless opencode run` auto-rejects
+> unanswered `ask`s immediately (there is no human to prompt).
 
-### How it works
+### Repo hygiene
 
-1. OpenCode Desktop starts and loads `opencode.json(c)`.
-2. It sees `"@te-river/opencode-team-mode@latest"` in the `plugin` array and loads the npm package.
-3. The loader calls the plugin's `server(input, options)`, which registers a `config` hook; the hook injects 6 agents and 6 commands into the merged config. The same call installs the R6 `tool.execute.before` guard, arms the unified R6/R2 approval gate (official dialog + `TM_ASK_TIMEOUT_MIN` auto-reject, wired through an `event` hook), and registers the governed `tm_*` tools (see [Governed tools & security](#-governed-tools--security) below).
-4. The plugin's `id: "team-mode"` is displayed as the plugin name in the Desktop UI.
-5. Agents and commands are immediately available in the Desktop UI — no file copying needed. User-defined agents with the same name always win (the plugin never clobbers them).
+The offload/trajectory/memory stores live under `<repo>/.git/opencode-team/`
+(or the OS temp dir outside a git repo) — **never your working tree**. Every
+agent is instructed to delete scratch files before reporting done and to keep
+throwaway work in the OS temp dir. A TTL sweeper reclaims old task dirs at
+startup + hourly; the Team Lead never deletes boards itself, so you can audit
+any run.
 
 ---
 
-## 🤖 How the team works
-
-Sub-agents cannot message each other live (platform limitation), so TeamMode
-coordinates them through a **structured reply skeleton**, with a file
-blackboard reserved for oversized output:
-
-- **Reply skeleton (primary channel):** every specialist's final reply starts
-  with `STATUS: / CHANGES: / FINDINGS: / EVIDENCE: / HANDOFF:` and stays ≤50
-  lines. Deliverables at that size travel inline — zero file I/O, nothing to
-  fall out of sync. The lead relays `HANDOFF` verbatim into the next
-  dispatch and machine-checks the skeleton (missing → one retry with it
-  inline, then downgrade and note the violation).
-- **Board files (exception only):** when a full deliverable exceeds ~50 lines
-  (e.g. a complete architecture doc), the dispatch names ONE file:
-  `<repo>/.git/opencode-team/<session-key>/<task-slug>/NN-<role>-<topic>.md`
-  — inside `.git/`, so your working tree and commits are **never polluted**
-  (non-git workspaces fall back to the OS temp dir). Writes are frozen: a
-  revision is a new round-suffixed file (`…-r2.md`); session folders keep a
-  fresh conversation from touching a not-yet-swept board.
-- **No MANIFEST.md:** the lead's state memory is its todo list.
-- **Feedback loop:** Critical/Major findings and product bugs automatically
-  become tracked fix tasks until the deliverable converges (max 2 loops,
-  then escalate to you).
-
-### Deterministic routing, approval gate & adaptive review
-
-- **Routing table:** the lead picks a fixed pipeline row by task shape —
-  question → direct answer; docs-only → implementer; product behavior
-  change → implementer → tester → reviewer; multi-module feature →
-  architect → implementer → tester → reviewer(s); unknown external tech →
-  researcher first. Pipelines have fixed minimums: a product change routed
-  below 3 dispatches is a routing bug, and splitting one request into
-  sub-2-dispatch pieces to dodge the gate is a protocol violation.
-- **Approval gate (count-based):** ≥2 planned dispatches → the lead
-  researches (reading the repo itself; a researcher dispatch only for
-  unknown external tech), presents a ≤30-line plan, and **waits for your
-  approval** before executing anything. 0-1 dispatches run with a 1-2 line
-  notice. A task that grows a second dispatch mid-run pauses for approval.
-  Blocking uncertainties are batched and asked immediately — never guessed,
-  never drip-fed.
-- **Adaptive review:** default is ONE reviewer dispatch (correctness);
-  three parallel dimensions (completeness / correctness / impact) only for
-  high-risk profiles — auth/security surface, cross-module data contracts,
-  public APIs across ≥3 files.
-- **Static verification:** testers verify via build, typecheck, static
-  analysis, and API/unit tests. Improvised browser automation (headless
-  screenshots, DOM stubs) is banned; user-visible frontend changes end with
-  `UI NOT VERIFIED: <what needs manual checking>` unless the project
-  already ships real browser-test tooling.
-- **No-ceremony fast path:** a root cause the lead has already verified
-  (file:line evidence) goes straight to the implementer as a fix spec —
-  investigation dispatches serve unknowns, not ritual.
-- **Brevity discipline:** route selection is a table lookup; user-visible
-  planning text stays ≤5 lines.
-- **Evidence standard (kept):** "done / fixed / passed" claims need
-  verifiable evidence — command output, logs, diffs. Narratives are
-  progress notes, not proof.
-- **Verbatim contracts (kept):** parallel implementers that must
-  interoperate get the exact data contract (endpoints, field names, types)
-  pasted verbatim into every affected dispatch.
-- **Docs sync (CHANGELOG + AGENTS.md):** delivered changes append a
-  CHANGELOG.md entry when one exists, and update AGENTS.md when the change
-  alters what it records (build/test commands, conventions, structure,
-  agent instructions); either file is offered for creation when missing.
-  Reading is deduplicated: the lead reads the README itself (the host does
-  not inject it), uses the host-injected AGENTS.md/CLAUDE.md copy already
-  in context and opens those files only when genuinely absent — and
-  specialists never re-open these docs, since conventions arrive
-  distilled inside their dispatches.
-
-### Triage — questions don't become code edits
-
-The Team Lead classifies every incoming message before acting: a question or
-consult gets an answer (zero file changes, fixes merely proposed and awaiting
-your go-ahead); only explicit action requests enter the workflow. And whenever
-you spell out what may or may not be touched, **those boundaries outrank
-everything else** — the lead restates them in every single dispatch.
-
-### Cleanup — the TTL sweeper is the only path
-
-| Who | When |
-|---|---|
-| Plugin code (in-process sweeper) | At startup + every hour: removes task directories idle **beyond the TTL** |
-
-The Team Lead never deletes task directories — finished boards stay
-readable so you can audit how a run went, and reclamation is pure code
-that never relies on the model remembering to do anything (crashes and
-force-kills leave nothing behind either). The sweeper prunes stale task
-dirs individually under a still-live session, and reclaims an entirely
-idle session folder in one pass. Set `ttlDays` to taste.
+## ⚙️ Configuration
 
-### Configure the TTL
+The plugin injects everything at startup — no agent files to copy.
 
-Default is **5 days**. To choose your own, use the tuple plugin form in
-`opencode.jsonc`:
+> **Model choice matters.** Every judgment — triage, decomposition, dispatch
+> briefs, synthesis, review verdicts — flows through the Team Lead. A weak
+> model in that seat degrades the whole pipeline no matter how strong the
+> specialists are. Pin your best reasoning model to `team`:
 
 ```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    ["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]
-  ]
+  "agent": {
+    "team": { "model": "anthropic/claude-opus-4-5" },      // Lead earns your best model
+    "implementer": { "model": "anthropic/claude-sonnet-4-6" } // specialists tolerate cheaper
+  }
 }
 ```
 
-`ttlDays` accepts any number of days in `(0, 365]`; invalid values silently
-fall back to 5.
-
-### Default agent
-
-By default TeamMode **makes Team your default agent** — new chats open
-directly in the team orchestrator. One side effect comes with the default
-slot: the switcher pins the default agent to the **first position** and
-sorts everything else alphabetically, so the picker order is
-**team, build, plan**. (Want Team below Plan instead? That requires
-giving up the default slot — see the opt-out below; the two are
-mutually exclusive by the server's sort.)
+**Global install** — put the plugin entry in `~/.config/opencode/opencode.jsonc` and every project gets the team.
 
-To opt out (`build` stays the default, picker order **build, plan,
-team**):
+**Keep Team off the default slot:**
 
 ```jsonc
 {
@@ -612,48 +366,64 @@ team**):
 }
 ```
 
-An explicitly configured non-`build` `default_agent` in your own config is
-always respected untouched — the plugin never clobbers it.
-
-**Upgrade note:** v1.4.4 briefly made this promotion opt-in; v1.4.5 restores
-Team-as-default as the shipped behavior. If you pinned `{ "defaultAgent":
-true }` during v1.4.4, you can drop that option (or switch it to `false` to
-opt out).
-
----
-
-## 🔧 Customization
+Your own agents named `team` / `architect` / … always take precedence; the
+plugin never clobbers user definitions. See [Customization](#-customization)
+for overrides, extra agents and disabling roles.
 
-### The Team Lead's model matters most
+### Environment variables
 
-The Lead is the orchestrating brain: it classifies every message, cuts the
-work into packages, writes each dispatch manifest, judges reviewer/tester
-findings, and synthesizes the final deliverable. Quality failures there
-**multiply down the pipeline** — a mediocre Lead mis-decomposes, briefs the
-experts vaguely, and waves weak work through; no specialist can rescue an
-assignment it was never correctly given.
+| Env var | Default | Purpose |
+|---|---|---|
+| `TM_ENV_PROTECT` | `strict` | R6 mode: `strict` / `standard` / `off` (off also disarms the approval timer) |
+| `TM_ASK_TIMEOUT_MIN` | `10` | minutes before an unanswered dialog is auto-rejected (hard floor 3 — the host's reply event reaches the plugin ~120 s late) |
+| `TM_ENV_PROTECT_EXTRA_DENY` | — | extra block patterns (regex; always hard block, never dialog-governed) |
+| `TM_OFFLOAD_THRESHOLD` | `2000` | offload threshold (tokens, CJK-aware estimate) |
+| `TM_PREVIEW_MAX_TOKENS` | `80` | preview hard cap |
+| `TM_FETCH_MAX_LINES` | `2000` | tm_fetch page cap |
+| `TM_BLACKBOARD_DIR` / `TM_TRAJECTORY_DIR` | `<repo>/.git/opencode-team/…` | offload store / trajectory ledger (tmpdir fallback; explicit = absolute or project-relative) |
+| `TM_BLACKBOARD_TTL` | `7` | store retention (days) |
+| `TM_BASH_READONLY_ALLOWED` | built-in table | tm_bash allowlist |
+| `TM_WEBFETCH_ALLOWED_DOMAINS` | the eleven seeded hosts | tm_webfetch / tm_search / tm_browser allowlist (`"*"` opens all; empty = deny all) |
+| `TM_BROWSER_PATH` | auto-detect | tm_browser executable override (Edge/Chrome/Chromium per OS) |
+| `TM_BROWSER_HEADLESS` | `auto` | `1` headless (CI) / `0` headful / `auto` (headless only on display-less Linux) |
+| `TM_MEMORY_GLOBAL_DIR` | `~/.opencode-team/memories/global/` | tm_memory GLOBAL scope store |
+| `TM_PTC_MAX_PROGRAM_CHARS` | `4000` | PTC program source cap |
+| `TM_PTC_MAX_CALLS` | `20` | PTC per-run bridge-call budget (1–200) |
+| `TM_PTC_MAX_ERRORS` | `3` | PTC per-run error budget (1–50) |
+| `TM_PTC_TIMEOUT_MS` | `60000` | PTC per-run wall-clock timeout (5s–10min) |
+| `TM_PTC_ENGINE` | `auto` | `auto` (worker→inline degrade) / `worker` / `inline` |
 
-So run the strongest model you can afford **in the Lead seat**. The other
-roles tolerate cheaper models — they work from tight briefs with scoped
-reading. Pin models per agent:
+---
 
-```jsonc
-{
-  "agent": {
-    // Team Lead — orchestration earns your best model
-    "team": { "model": "anthropic/claude-opus-4-5" },
-    // specialists — cheaper models are usually fine
-    "implementer": { "model": "anthropic/claude-sonnet-4-6" }
-  }
-}
-```
+## 🏗️ How the team works
+
+Sub-agents can't message each other live (platform limitation), so TeamMode
+coordinates them through a **structured reply skeleton** — every specialist
+reply is `STATUS: / CHANGES: / FINDINGS: / EVIDENCE: / HANDOFF:`, ≤50 lines,
+relayed verbatim by the Lead into the next dispatch. Files are the exception,
+not the rule: a deliverable over ~50 lines goes to ONE named board file under
+`<repo>/.git/opencode-team/` (round-suffixed, working tree untouched).
+
+- **Routing table:** question → direct answer; docs-only → implementer;
+  product change → implementer → tester → reviewer; multi-module →
+  architect → implementer → tester → reviewer(s); unknown tech → researcher
+  first. Fixed minimums — a product change routed below 3 dispatches is a
+  routing bug.
+- **Approval gate (count-based):** ≥2 dispatches → plan (≤30 lines) → **your
+  approval** → execute. Blocking questions are batched and asked immediately.
+- **Adaptive review:** one reviewer by default; three parallel dimensions
+  only for high-risk profiles (auth/security, cross-module contracts, public APIs).
+- **Static verification:** build / typecheck / lint / tests. Improvised
+  browser automation is banned; unverified UI work ends with
+  `UI NOT VERIFIED: <what to check>`.
+- **Evidence standard:** "done / fixed / passed" claims need verifiable
+  evidence — output, logs, diffs.
 
-(Model IDs above are placeholders — use whatever your provider exposes.
-Your own `agent.team` definition always takes precedence over the plugin's.)
+---
 
-### Override an agent
+## 🔧 Customization
 
-Add an agent with the same name in your `opencode.json` — your definition takes precedence:
+**Override an agent** — same name in your config wins:
 
 ```jsonc
 {
@@ -666,9 +436,7 @@ Add an agent with the same name in your `opencode.json` — your definition take
 }
 ```
 
-### Add your own agents
-
-TeamMode does not prevent you from adding more agents. Define them alongside the team:
+**Add your own agents** alongside the team:
 
 ```jsonc
 {
@@ -682,38 +450,96 @@ TeamMode does not prevent you from adding more agents. Define them alongside the
 }
 ```
 
-### Disable an agent
+**Disable one:** `"researcher": { "disable": true }`.
 
-```jsonc
-{
-  "agent": {
-    "researcher": { "disable": true }
-  }
-}
-```
+**Board retention** via the tuple form: `["@te-river/opencode-team-mode@latest", { "ttlDays": 7 }]` (valid range (0, 365], invalid values fall back to 5).
 
 ---
 
-## 📦 Publishing to npm
+## ❓ FAQ
+
+**Will this eat my tokens?**
+The opposite is the point. Offload + 80-token previews + PTC batch programs
+exist because a five-agent pipeline naively bolted onto one context window
+*would* eat your tokens. The governance is the token-saver.
+
+**Is the web access safe?**
+It's the most guarded surface in the plugin: two full web roles plus a
+browser-only tester grant, a domain
+allowlist with dialog-gated escapes (you approve any out-of-allowlist
+target in OpenCode's official dialog, with a toast notification), redirects
+re-checked per hop, network-layer enforcement in the browser, env-file URL
+refusal, and every payload rides the same offload governance. No allowlisted
+page can bounce the fetch off-site.
+
+**Why doesn't the plugin auto-update?**
+OpenCode caches plugins by spec string and never re-resolves `@latest`
+(upstream limitation, not ours). **Re-run the installer — that IS the
+update** (it purges the cache and re-resolves npm copies); or delete the
+cache dir by hand. Recipe above and in the
+[installation guide](./docs/installation.md).
+
+**Can agents run tools in parallel?**
+Yes — and they're *engineered* for it: parallel `tm_search` / `tm_webfetch` /
+`tm_fetch` calls get distinct step ids and isolated payloads. A regression
+here fails the test suite before it ever reaches you.
+
+**Does it work in the CLI (TUI), or only Desktop?**
+Both. Desktop adds the color-coded picker and panels; the governed tools and
+the whole workflow are host-agnostic. On display-less Linux, `tm_browser`
+runs headless automatically.
+
+**What happens if I don't answer a confirmation dialog?**
+It auto-rejects after `TM_ASK_TIMEOUT_MIN` (default 10). The plugin never
+self-approves — the only side it can take is yours or nobody's.
 
-If you want to publish your own fork:
+---
 
-```bash
-npm run build        # compile TypeScript → dist/
-npm version patch    # bump version
-npm publish          # publish to npm registry
+## 🗑️ Uninstall
+
+1. Remove the entry from the `"plugin"` array in your config file.
+2. Delete the cache dir (table in [Install](#-read-this-once-save-yourself-an-hour-later)) if you want the disk space back.
+3. Restart OpenCode. The agents, commands and tools are gone; the stores under `<repo>/.git/opencode-team/` (and `~/.opencode-team/` for global memories) are plain files you can delete whenever.
+
+No DLLs were harmed. Nothing was written to your working tree.
+
+---
+
+## 🏛️ Architecture (for the curious)
+
+```
+opencode-team-mode/
+├── src/
+│   ├── index.ts          ← Plugin entry (config + R6 guard + approval gate + tool segment)
+│   ├── agents.ts         ← Agent structure (modes, colors, temperatures, whitelist matrix)
+│   ├── prompts/          ← Agent prompts (lead / specialists / shared) — pinned by tests
+│   ├── commands.ts       ← Slash command definitions
+│   ├── blackboard.ts     ← Shared blackboard + TTL sweeper
+│   ├── envprotect.ts     ← R6 facade (patterns / classifiers / gate predicates / hook)
+│   ├── approval-gate.ts  ← Unified approval gate (dialog timeout auto-reject)
+│   ├── tm/               ← Governed tools: pipelines / store / preview / guard / refs /
+│   │                        webfetch / search / memory / browser / shell-bridge / ptc/ (9 modules)
+│   └── types.ts          ← Loader-contract types (1.18.x)
+├── docs/installation.md  ← The agent-consumable install guide
+├── scripts/              ← One-line installers (bash / PowerShell)
+├── pt07/                 ← PT-07 baseline suite (seeded A/B token measurement)
+└── README.*.md           ← You are here (twice)
 ```
 
+The loader calls `server(input, options)` once: the `config` hook injects the
+six agents and six commands, the same call installs the R6
+`tool.execute.before` guard, arms the approval gate through an `event` hook,
+and registers the `tm_*` tools. User-defined agents with the same name always
+win — the plugin never clobbers.
+
 ---
 
 ## 🤝 Contributing
 
-Contributions are welcome! Areas where we need help:
-
-- 🌐 **Localization** — Translate agent prompts to other languages
-- 🎨 **More agent roles** — DevOps, DBA, Security Specialist, UX Designer
-- 🔧 **Additional commands** — `/team-deploy`, `/team-docs`, `/team-refactor`
-- 📝 **Better prompts** — Improve agent behavior through prompt engineering
+Issues and PRs welcome. Especially wanted: localization of agent prompts,
+more agent roles, more command templates, and real-world reports of the
+search engines' behavior (they rearrange their markup; the extractor filters
+are intentionally loose but not psychic).
 
 ---
 
@@ -725,8 +551,8 @@ Contributions are welcome! Areas where we need help:
 
 ## 🔗 Links
 
-- [npm Package](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode` on npm
+- [npm Package](https://www.npmjs.com/package/@te-river/opencode-team-mode) — `@te-river/opencode-team-mode`
+- [Installation guide](./docs/installation.md) — the complete manual / agent-consumable procedure
 - [OpenCode Desktop](https://opencode.ai) — Official website & download
 - [OpenCode Docs](https://opencode.ai/docs) — Configuration & plugin documentation
 - [OpenCode Plugin API](https://opencode.ai/docs/plugins) — Build your own plugins
-- [OpenCode GitHub](https://github.com/anomalyco/opencode) — Source code for OpenCode itself