oh-my-agent-web 0.7.0 → 1.0.2

package/README.en.md

@@ -2,78 +2,46 @@
 
 [中文](README.md) · **English**
 
-One line: **an external control surface for the agent you're already running.** The engine keeps running on your own machine; you use the web page to watch it work, manage its tools and models, cut in whenever it drifts, and jump into files or a shell when you need to.
+One line: **an external control surface for the agent you're already running.** The engine keeps running on your own machine; the web page is where you watch it work, manage its tools and models, cut in to correct it whenever you like, and — when the moment comes — read files, open a terminal, or highlight a passage and ask for a change.
 
-Single user, loopback only, and the engine's own on-disk files are the source of truth for conversations — no database, no accounts. One `omaw` process is one person's workbench.
+Single user, loopback only, and **the engine's own on-disk files are always the source of truth for a conversation** — no database, no account system, no second copy of the session in our own store. One `oh-my-agent-web` process is one person's workbench.
 
-![Four subagents running in parallel in one session: projects and sessions on the left, process and tool cards in the middle, file preview on the right](docs/screenshots/01-chat.png)
+![A real session: projects and sessions on the left, thinking blocks and tool cards in the middle, a file preview of the same repo on the right](docs/screenshots/01-chat.png)
 
-```
-npm ci && npm run build && npm start   →   http://127.0.0.1:25257
-```
+> Every screenshot below is the real UI of this repo (the 0.8.0 build) — pi engine + DeepSeek, working on a small `demo-app` project.
+> Directories, commands, the `+6 −1` diff, tokens and cost all come from that actual run — no collages, no mockups.
+> What each shot shows, how it was taken and how it was compressed is in [`docs/screenshots/README.md`](docs/screenshots/README.md).
 
 ---
 
-## Modules
+## Install
 
-The top bar *is* the menu; the sidebar holds projects, sessions and files; the right pane is preview and terminal.
+Requires **Node.js ≥ 22.19** and **npm ≥ 9**; macOS / Linux / Windows all work. You end up with an `oh-my-agent-web` command (short aliases: `aw`, `agent-web` — all equivalent).
 
-| Module | Where | What it does |
-|---|---|---|
-| **Conversation** | center | Streaming text + collapsible thinking blocks + tool cards (arguments / full command / output / duration / ok or failed) + a "N steps" process block + a usage footer (tokens / cache / cost) + chips for changed files |
-| **Steer & queue** | composer | Cut in mid-turn and the next message takes effect immediately; queued messages can be retracted; sent messages fold into the process block |
-| **Engines** | top bar picker | pi / Codex / DeepSeek Harness / opencode each with its native loop (not one prompt in four costumes); every session remembers its engine, model and thinking level |
-| **Subagents** | top bar "subagents" + the strip under the conversation | The main agent gets an `Agent` tool and can run several **real sessions** in parallel; run cards show status / duration / tool count / tokens / cost, expand in place for the result, and can be stopped individually. The panel manages templates: tool allowlist, model, thinking level, max turns, concurrency (1–12) |
-| **Models & providers** | top bar "models" | The 41 providers in pi's official catalog work **with just a key** — no base URLs, no hand-copied model IDs. Custom providers expose the api shape (openai-completions / responses / anthropic-messages / codex / typesafe), base URL and custom headers; tick models, batch-test speed, pull the list from `/models`, save a whitelist. **Keys never leave the server** (only the last four digits come back) |
-| **Skills** | top bar "skills" | Installed list with enable/disable and a reader for `SKILL.md` plus the skill's files; **Skill Hub** search and one-click install (200k+ index), install from a Git repo, or create by hand. Enabling means renaming `SKILL.md` — there is no second state file |
-| **MCP** | top bar "MCP" | Edit both `mcp.json` files (global and project; a project entry with the same name wins), enable/disable, pick an exposure level (codemode / deferred / direct / hidden), **test the connection** (real handshake + tool list), OAuth login, browse a marketplace |
-| **Plugins** | top bar "plugins" | pi packages (npm / git / local dir) with four states (loaded / installed / missing / disabled), per-package disabling, plus loose single-file extensions; state comes from pi's own resolution — only install/uninstall/update touch the disk |
-| **File manager** | sidebar "files" | Directory tree (switchable root), search by name, show hidden files, collapse all, upload and download, reveal in Finder; uncommitted changes are dotted in the tree |
-| **File viewer** | right pane (multi-tab) | Markdown / source with line numbers / images / PDF / audio-video streams; select lines and "add to conversation" to use them as context; full screen and draggable width |
-| **Diff** | "diff" at the top of the viewer | Compared against HEAD: a `+285 −78` summary, line-level red/green highlighting, switch between diff and full file; opening from a "changed files" chip lands straight on the diff |
-| **git** | top of the files pane | Branch chip (click to switch local branches, confirms first on a dirty tree), `M` / `U` / `D` markers after filenames |
-| **Terminal** | files pane `>_`, right-pane tab | A real PTY (`node-pty` + xterm.js) sharing the session's cwd, with an optional initial command; on Linux it tells you exactly which build tools are missing |
-| **Push** | top bar "push" | Web Push subscriptions (VAPID); one notification per finished turn — title is the project, body the session, with ❌ for failures and ⏹ for interrupts. Multiple devices, test push, clear all; needs https or localhost |
-| **Voice** | top bar "voice" | Four event sounds (start / finish / error / waiting for approval) with preview and volume; local TTS (the browser's own voices, no network) that can read the final reply, with speed and voice selection |
-| **Settings** | top bar "settings" | Four pages: **UI** (which chunks appear in the top bar and status bar), **general** (saved phrases, etc.), **appearance** (chat font size ×4, content width ×4, six palettes: bright white, warm paper, mist, Tokyo night, mocha, nord), **language** (Chinese / English, applies instantly) |
-| **Sessions** | sidebar | Grouped by directory into "projects"; pin, rename, archive (undoable), delete (renames to `.deleted-<timestamp>`, the file survives). A session *is* the engine's own file — identical to what the CLI shows |
-| **Attachments** | composer | Drag-and-drop upload, `@` file mentions, pasted images; uploads land in the data dir, never in your project |
-| **Mobile** | — | Responsive: the sidebar becomes a drawer, process blocks collapse to a caret, below 400px it switches to the phone layout |
-
-> Every screenshot below comes from a **real, running instance** (taken on this project's own session) — nothing is mocked up.
-
----
+### Install globally with npm (recommended)
 
-## Screens
+```bash
+npm -g install oh-my-agent-web
+```
 
-| | |
-|---|---|
-| ![Answer with a markdown table, changed files and usage](docs/screenshots/02-answer.png) | ![Diff view of a file](docs/screenshots/03-files-diff.png) |
-| **Answer**: markdown, tables, code highlighting, token and cost footer | **Diff**: against HEAD, line-level red/green |
-| ![Embedded terminal](docs/screenshots/04-terminal.png) | ![Models and providers](docs/screenshots/05-models.png) |
-| **Terminal**: a real PTY in the session's cwd | **Models**: the 41 built-ins need only a key; ticked models apply |
-| ![Skills panel](docs/screenshots/06-skills.png) | ![Skill Hub](docs/screenshots/07-skills-hub.png) |
-| **Skills**: installed list, toggles, and `SKILL.md` | **Skill Hub**: search by category, install in one click |
-| ![MCP](docs/screenshots/08-mcp.png) | ![Subagents](docs/screenshots/09-subagents.png) |
-| **MCP**: global and project config, exposure, connection test | **Subagents**: who is running, results, templates and tool allowlists |
-| ![Settings](docs/screenshots/10-settings.png) | ![Plugins](docs/screenshots/11-plugins.png) |
-| **Settings → appearance**: font size, width, six palettes | **Plugins**: load state of pi packages, with toggles |
-
-Two more: [voice (event sounds + local TTS)](docs/screenshots/12-voice.png), [push (subscriptions and devices)](docs/screenshots/13-push.png).
+No version tag means the current release. To pin a version or use a mirror:
 
----
+```bash
+npm -g install oh-my-agent-web@latest
+npm -g install oh-my-agent-web@<version> --registry=https://registry.npmmirror.com
+```
 
-## Quick start
+You get three commands that all point at the same entry point: **`oh-my-agent-web`** (used throughout this README),
+`aw` (the short alias you'll probably type), and `agent-web`.
 
-Requires **Node.js ≥ 22.19** (a hard requirement of `@earendil-works/pi-*` 1.x) and **npm ≥ 9**. macOS / Linux / Windows all work.
+Upgrade and uninstall:
 
 ```bash
-npm ci               # recommended: exact versions from the lockfile (no re-resolution)
-npm run build
-npm start            # foreground; Ctrl-C to quit
+oh-my-agent-web upgrade               # same as npm -g install oh-my-agent-web@latest
+npm -g uninstall oh-my-agent-web      # uninstall; data in ~/.oh-my-agent-web is left alone
 ```
 
-Open <http://127.0.0.1:25257>.
+On Linux, `node-pty` (the embedded terminal) ships prebuilds only for macOS / Windows, so Linux compiles it in place: you need `make`, `g++` and `python3`. When those are missing, both the page and the install script say exactly what's missing — the terminal won't open until then.
 
 ### One-line install (never touches global npm)
 
@@ -89,294 +57,472 @@ Windows (PowerShell):
 powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/main/scripts/install.ps1 | iex"
 ```
 
-The script does four things: **finds a new enough Node** (downloading the official build into `~/.omaw/node` with a sha256 check if needed), **runs `npm install -g --prefix ~/.omaw`** (no system-wide directory, no sudo), **links `omaw` into `~/.local/bin`** (patching PATH if necessary), and **smoke-tests once** (version string plus whether `node-pty` can be required — i.e. whether the terminal will open).
+The script does four things: **finds a new enough Node** (downloads an official build into `~/.oh-my-agent-web/node` and checks its sha256 if needed), **`npm install -g --prefix ~/.oh-my-agent-web`** (never the system-wide prefix, no sudo), **links `aw` / `agent-web` / `oh-my-agent-web` into `~/.local/bin`** (patching PATH if necessary), and **smoke-tests once** (version string + whether `node-pty` can be required, i.e. whether the terminal will open).
 
-| What you want to change | How (`sh` version; the PowerShell version uses env vars) |
-|---|---|
-| Version | `OMAW_VERSION=0.7.0` (or `--version 0.7.0`) |
-| Install location | `OMAW_HOME=/opt/omaw` (or `--home /opt/omaw`) |
-| Registry mirror | `OMAW_REGISTRY=https://registry.npmmirror.com` (or `--registry …`) |
-| Leave PATH alone | `OMAW_NO_PATH=1` (or `--no-modify-path`) |
-| Install build tools | `OMAW_BUILD_TOOLS=1` (or `--with-build-tools`) |
-| Uninstall | `… \| sh -s -- --uninstall` (removes the install dir and symlink only, never your data dir) |
+That `~/.oh-my-agent-web` is also the **data directory**: what gets installed (`node/`, `lib/`, `bin/`) sits next to your `settings.json`, `password`, `uploads/` and `logs/`.
 
-On Linux the script also checks for `make` / `g++` / `python3`: `node-pty` ships prebuilds for macOS / Windows only, so Linux compiles the PTY in place. If the tools are missing it tells you what to install, or you can pass `--with-build-tools` and let it handle that.
+| What you want to change | How (`sh` version; PowerShell uses env vars) |
+|---|---|
+| Version | `OH_MY_AGENT_WEB_VERSION=<version>` (or `--version <version>`) |
+| Install elsewhere | `OH_MY_AGENT_WEB_HOME=/opt/oh-my-agent-web` (or `--home /opt/oh-my-agent-web`) |
+| Registry mirror | `OH_MY_AGENT_WEB_REGISTRY=https://registry.npmmirror.com` (or `--registry …`) |
+| Leave PATH alone | `OH_MY_AGENT_WEB_NO_PATH=1` (or `--no-modify-path`) |
+| Install build tools | `OH_MY_AGENT_WEB_BUILD_TOOLS=1` (or `--with-build-tools`) |
+| Uninstall | `… \| sh -s -- --uninstall` (removes only what was installed; `settings.json` / password / uploads / logs stay) |
 
-> You can also just type `omaw` in your home directory after installing, but the home directory is an unsafe workspace (the file tree, search and the agent's cwd would all be your entire home). In that case it falls back to `<dataDir>/workspace` and prints a note. To point it at a real project use `AGENT_WEB_CWD=/path/to/project`.
+---
 
-### Install as a global command
+## Commands
 
-`oh-my-agent-web` / `omaw` / `agent-web` are three bin names for the same entry point:
+The three commands are completely equivalent; everything below is written as `oh-my-agent-web` (`aw` is its short alias).
 
-```bash
-npm i -g .
-omaw -d              # start in background (logs to <dataDir>/daemon.log)
-omaw status          # pid / port / uptime / engine / session count
-omaw restart -d      # restart after code changes
-omaw stop
-omaw version         # current version; omaw upgrade upgrades to the latest release
-```
+| Command | What it does |
+|---|---|
+| `oh-my-agent-web` | **Start (default)**: runs in the background and opens the browser, handing the terminal straight back; default workspace = current directory |
+| `oh-my-agent-web start -f` | Run in the foreground, logs right in the terminal, `Ctrl-C` to quit |
+| `oh-my-agent-web status` | pid / port / uptime / engine / session count / workspace |
+| `oh-my-agent-web restart` | Stop then start (background by default; `-f` for foreground) |
+| `oh-my-agent-web stop` | Stop the running instance (foreground or background — it reads the lock file in the data dir instead of guessing a port) |
+| `oh-my-agent-web version` | Version string (`-v` / `--version` are synonyms) |
+| `oh-my-agent-web upgrade` | Upgrade to the latest release (it runs `npm -g install oh-my-agent-web@latest`) |
+| `oh-my-agent-web help` | Show help (`-h` / `--help` are synonyms) |
 
-### CLI flags
+### Flags
 
 | Flag | Env var | Default | Notes |
-| --- | --- | --- | --- |
+|---|---|---|---|
 | `-p, --port` | `AGENT_WEB_PORT` | `25257` | Listen port |
-| `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | Bind address; only change it for remote access |
-| `-P, --password` | `AGENT_WEB_PASSWORD` | none | Access password; unset = local machine only |
-| `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | loopback only | Extra allowed domains / LAN IPs (repeatable or comma-separated) |
-| `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | Settings, password, uploads, logs, lock file |
-| — | `AGENT_WEB_CWD` | `process.cwd()` | Default workspace (used before any session exists) |
+| `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | Listen address; only change it for remote access |
+| `-P, --password` | `AGENT_WEB_PASSWORD` | none | Login password; unset = loopback only (a remote first visit asks you to set one) |
+| `-f, --foreground` | — | off (background by default) | Foreground run, logs in the terminal; `-d` / `--detach` is the old spelling and now equals the default |
+| `--no-open` | — | on | Don't open the browser |
+| `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | loopback only | Extra allowed hostnames / LAN IPs (repeatable or comma-separated) |
+| `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | Settings, password, uploads, logs and the lock file live here |
+| — | `AGENT_WEB_CWD` | `process.cwd()` | Default workspace (before any session exists) |
 | — | `AGENT_WEB_ENGINE` | `pi` | Default engine |
-| — | `AGENT_WEB_APPROVAL_MODE` | `allow` | Default approval mode for new sessions; set `ask` to confirm every time |
-| — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 min | Per-turn watchdog timeout |
+| — | `AGENT_WEB_APPROVAL_MODE` | `allow` | Default approval mode for new sessions; `ask` confirms every tool call |
+| — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 minutes | Per-turn watchdog timeout |
 | — | `AGENT_WEB_LOG` | `info` | `debug` / `info` / `warn` / `error` |
 
-> To use it from your phone: `omaw -d -H 0.0.0.0 -P your-password --allow-host your.domain`. If you put a reverse proxy or tunnel in front, make sure it forwards `X-Forwarded-For` (origin checks look at it).
+### Common examples
+
+```bash
+oh-my-agent-web                                    # background + open the page (the usual one)
+oh-my-agent-web -f                                 # foreground, logs in your face, Ctrl-C to quit
+oh-my-agent-web -p 25258                           # different port (when 25257 is taken)
+oh-my-agent-web status && oh-my-agent-web restart  # check, then restart
+oh-my-agent-web stop                               # stop it (works for foreground and background)
+oh-my-agent-web --data-dir ~/agent-web-data             # different data directory
+AGENT_WEB_CWD=~/code/my-proj oh-my-agent-web       # set the default workspace
+oh-my-agent-web -H 0.0.0.0 --allow-host agent.example.com   # allow outside access (first visit asks you to set a password)
+```
+
+> **Reaching it from your phone**: `oh-my-agent-web -H 0.0.0.0 --allow-host your.domain`. The first visit from the phone asks you to **set an access password** (stored as `password` in the data dir; after that you just log in). Reverse proxies / tunnels should pass `X-Forwarded-For` (origin checking looks at it).
+>
+> **Running `oh-my-agent-web` from your home directory** works, but home is an unsafe workspace (the file tree, search and the agent's cwd would be your whole home). In that case it falls back to `<data dir>/workspace` and prints a line about it; to point at a project use `AGENT_WEB_CWD=/path/to/project`.
+
+Each engine also has its own escape hatches (all have defaults; you normally don't touch them): `AGENT_WEB_CODEX_BIN` / `_HOME`, `AGENT_WEB_DSH_BIN` / `_HOME` / `_MODEL` / `_PATCH`, `AGENT_WEB_OPENCODE_BIN` / `_ARGS` / `_MODEL`, `AGENT_WEB_CLAUDE_BIN` / `_ARGS` / `_MODEL` (it auto-detects `claude-code-acp` / `claude-agent-acp` and says so when neither is installed).
+
+---
+
+## What it is, what it isn't
+
+**It is**: a front end that spreads the agent's *process* out in front of you. Thinking blocks, tool calls, changed files, tokens and cost all live in the conversation stream. You can cut in mid-turn, highlight a passage to file a comment on it, or open a scratch chat that never touches disk just to ask one question.
+
+**It is not**: a new agent engine, and it is not a SaaS that moves your sessions into the cloud. It does not rewrite prompts and does not take over tool implementations — what you install is pi / Codex / Claude Code / opencode / DeepSeek Harness, and the workbench just gives them a readable UI, clickable buttons, and a session list that survives restarts.
+
+Three hard rules:
+
+1. **No database**: a conversation *is* the JSONL / thread the engine wrote. The web UI reads it, renames it, and deletes it when asked.
+2. **No pretending**: anything an engine can't do is hidden in the UI (the capability matrix); a panel that can't get data says so, and no other engine's config is passed off as this one's.
+3. **No overreach**: it listens on `127.0.0.1` only by default; exposing it remotely takes all three of `-H`, `-P` and `--allow-host`.
+
+---
+
+## Conversation
+
+**Streaming text + collapsible thinking blocks + tool cards.** A tool card shows arguments, the full command (copyable), output, duration and pass/fail. Thinking and tool calls inside one turn are grouped into "process, N steps" blocks that expand when clicked.
+
+![The footer of one reply: a markdown table, the changed-files chip, and this turn's tokens / cache / cost](docs/screenshots/02-answer.png)
+
+The footer of every reply is the usage **for that turn**: input (cache miss) / output / cache read / cost, with a "Copy" that takes the whole block. The running total for the session is behind the context ring in the status bar (subagents are separate sessions billed separately and are not counted there).
+
+A few things in the conversation are clickable:
+
+- **Changed-files chip**: which files this reply touched (the chip at the bottom of the screenshot above shows `store.ts`); one click lands you straight on the diff in the right pane.
+- **Branch icon**: "Branch from here", which starts a new conversation at this message; the original stays byte-for-byte unchanged.
+- **File paths**: a path like `web/src/App.tsx` in the body opens in the preview.
+
+### Cutting in, queueing, stopping
+
+While a turn is running, the composer does not lock up:
+
+| Action | Meaning |
+|---|---|
+| **Steer** | Takes effect immediately, inserted into the current turn as the next instruction |
+| **Queue** | Wait until this turn ends; you can see what's at the head of the queue and retract anything |
+| **Stop** | Interrupt the turn and keep whatever was already produced |
+
+Steering is pi-only (its SDK has `streamingBehavior: "steer"`). Other engines have no such notion, so the host **degrades it to queueing** rather than firing a second message that would flush the active turn.
 
 ---
 
-## UI tour
+## Notes: highlight a passage and comment on it
+
+**Select some text in the conversation** and a small toolbar floats up: `Add to session` / `Annotate` / `Ask in a temp session`.
+
+<table><tr>
+<td width="50%"><img src="docs/screenshots/14-selection-toolbar.png" alt="The toolbar that floats up after you select a passage"></td>
+<td width="50%"><img src="docs/screenshots/15-annotations.png" alt="After annotating: a numbered badge stays in the body, and a 1-note pill shows up in the composer"></td>
+</tr></table>
+
+"Annotate" attaches a comment to that text. The body keeps a **①②③ numbered badge**, and an "N notes" pill appears in the composer — open it to read, edit or delete each comment, or `Quote it`.
+
+On send it is assembled into a block like this (you can also hit `Quote it` yourself, in which case only your own words go out):
 
 ```
-┌─ top bar: brand · new chat · engine picker · subagent badge · panels · right-pane toggle ─┐
-├────────────┬──────────────────────────────┬──────────────────────┤
-│ sidebar    │ conversation                  │ right pane           │
-│ · projects │ · message stream (thinking    │ · file preview        │
-│ · sessions │   blocks + tool cards)        │   (multi-tab)         │
-│ · archived │ · steer / queued messages     │ · terminal            │
-│ · files    │ · subagent run strip          │ · status bar          │
-│            │ · composer (attachments, /)   │                      │
-└────────────┴──────────────────────────────┴──────────────────────┘
+Note 1:
+> The panel starts at y=0, but the top bar's z-index is 45
+
+This needs to be one sentence shorter
 ```
 
-The sidebar and right pane can both be dragged wider or collapsed; widths persist in `localStorage`. The composer takes `/` slash commands, `@` file mentions, drag-and-drop attachments and pasted images; the chips above it are prompt templates, the thinking toggle and suggested actions.
+Notes are **local anchors**: they locate themselves by "quoted text + surrounding context", so badges still find their place after the body reflows or a stream appends more text. They live in this browser's `localStorage`, isolated per session — never on the server, never in the cloud, invisible from another device.
 
-On narrow screens (mobile UA or ≤400px) the layout switches to overlay drawers and the sidebar collapses shortly after you pick a session. Which chunks appear in the top bar and status bar — and whether process blocks start expanded — are all switchable in settings.
+**Line references in files** are the other road: select lines in the preview (`Shift+click` for a range, `Ctrl/Cmd+click` to add, right-click for the line menu) and "Add to conversation" writes a **path plus line numbers** such as `@web/src/App.tsx:120-138`, leaving the agent to read it.
 
 ---
 
-## Engines
+## Side chat: ask one question and go
+
+![The "side chat" on the right is a channel of its own: never saved, while the main conversation keeps running](docs/screenshots/13-tempchat.png)
+
+The `Temp session` button in the top bar (or the first card on the right pane's landing page) opens another conversation **in the right pane**:
+
+- **Not persisted**: it lives in memory, dies with the tab, never enters the sidebar and leaves no file;
+- the main conversation keeps running; the two don't interrupt each other;
+- to keep it, hit `Save as a regular chat` — only then is a session file written (history the ephemeral chat never had is preserved too);
+- you can have several open at once, each on its own channel and its own tab.
+
+> This depends on the engine having an in-memory session: pi supports it; a Codex thread already lives in Codex's own store, so there is no "save" button. It is not "a new session in a different skin", and it is not a subagent — **an ephemeral chat is a window you opened, a subagent is a subtask the agent dispatched**.
+
+---
+
+## Files, diffs, git, search
+
+The files area sits at the bottom of the sidebar and also works as a tab in the right pane. **The web side is read-only**: you can look, compare, reference and search; editing files in place and saving them is not this layer's job — give that to the agent's tools or the terminal, and use the diff here to review it.
+
+| Capability | Notes |
+|---|---|
+| Directory tree | Switchable root (follow the session / pick a project), lazy loaded, at most 500 entries per directory, `node_modules` / `.git` / `dist` hidden by default, "show hidden files" reveals `.env` and friends |
+| Search by file name | Matches names only, never reads contents, 250 ms debounce, at most 200 hits |
+| Preview | markdown (tables / code highlighting / mermaid), source with line numbers, images, PDF, audio and video streams; multiple tabs, drag to reorder, right-click to close left / right / all, and it can be spread over the full width |
+| Line references | Select lines → "Add to conversation" writes `@path:line`; a text selection can also be "copy selected text" |
+| Reveal in Finder | macOS `open -R`, Windows `explorer.exe /select,`, Linux opens the parent directory |
+| Uncommitted changes | Status dots in the file tree, plus `M` / `U` / `D` after the filename |
+
+### Diff
 
-| Engine | Notes |
-| --- | --- |
-| **pi** (default) | The full plugin / skill ecosystem, lazy tool loading, approval gate, goal mode and subagents; providers and models are managed by this workbench |
-| **Codex** | The official Codex agent (app-server JSON-RPC) with its own loop and sandbox; sessions are shared with Codex Desktop / CLI; approvals are command/file level |
-| **DeepSeek Harness** | The official DeepSeek agent (ACP); model and thinking level are switchable; permissions confirmed one by one |
-| **opencode** | The official opencode agent (ACP) with its own tools / MCP / plugin ecosystem; sessions are shared with the opencode CLI / TUI. **Approvals follow opencode's own `permission` config** (a global allow means you will never be asked) |
-| **fake** | A scripted, zero-token engine used only to exercise the protocol / tools / approvals (`AGENT_WEB_ENGINE=fake`, not shown in the picker by default) |
+![The diff view: against HEAD, a `+6 −1` summary plus line-level red/green](docs/screenshots/03-diff.png)
 
-Capability matrix (`server/engine/registry.ts`):
+The "diff" toggle at the top of the preview is a comparison against `HEAD`: a `+285 −78` summary, line-level red/green, and a switch between "changes only" and the full file. Coming in from a changed-files chip lands directly on the diff.
 
-| Capability | pi | codex | dsh | opencode |
-| --- | :-: | :-: | :-: | :-: |
-| Approvals | ✅ | ✅ | ✅ | per config |
-| Model / thinking level | ✅ | ✅ | ✅ | ✅ |
-| Resume sessions | ✅ | ✅ | ✅ | ✅ |
-| Steering | ✅ | — | — | — |
-| Subagent panel | ✅ | — | — | — |
-| Workbench-managed providers | ✅ | — | — | — |
+### git
 
-A missing engine does not block startup: you only get "not found" when you switch to it.
+The branch chip at the top of the files area lists local branches and switches them (a dirty working tree asks first). It only shells out to `git` for reads and branch switches — it never commits. Committing stays with the agent, or with you in a terminal.
 
-Per-engine escape hatches (all have defaults, usually leave them alone):
+### Content search
 
-| Variable | Purpose |
-| --- | --- |
-| `AGENT_WEB_OPENCODE_BIN` / `_ARGS` / `_MODEL` | opencode binary, extra args (e.g. `--pure` to skip external plugins), preferred model for new sessions (`provider/model`) |
-| `AGENT_WEB_DSH_BIN` / `_HOME` / `_MODEL` / `_PATCH` | DSH binary, data dir, model, patch toggle |
-| `AGENT_WEB_CODEX_BIN` / `_HOME` | Codex binary and data dir |
+"Search file contents" in the toolbar is a full-text search: add a **path mask** (such as `web/src/**`) to narrow it, results show `file:line` plus a snippet of the source, and clicking one jumps to that line. When there are too many hits it truncates at the cap and says so.
 
 ---
 
-## Sessions and on-disk state
+## Terminal
 
-No database: **the engine's own files are always the source of truth** for a conversation. The web UI only reads them, renames them, and deletes them when asked.
+![The right-pane terminal is a real PTY: zsh, colors, git output, and a cwd that matches the session](docs/screenshots/04-terminal.png)
 
-| What | Where |
-| --- | --- |
-| pi sessions | `~/.pi/agent/sessions/<encoded cwd>/<ISO>_<uuid>.jsonl` (first line `{type:"session",id,timestamp,cwd}`) |
-| Codex sessions | Codex's own thread store (via `thread/list \| resume \| delete`) |
-| opencode / DSH sessions | Their own data dirs (opencode lists by cwd; DSH reads the workspace projection under `~/.dsh`) |
-| Session title | pi takes the first user message (reads only the first 60 lines); renaming appends `session_info.name` to the end of the jsonl |
-| Workbench state | `<dataDir>/settings.json`, `approval-rules.json`, `server.lock`, `logs/`, `uploads/`, `push-subscriptions.json`, `vapid-keys.json` |
+The terminal in the right pane is a **real PTY** (`node-pty` + xterm.js): vim / top / Ctrl-C / colors / line editing all behave, the cwd matches the session's project, and you can pass one initial command (the upgrade flow uses exactly that).
+
+Reloading the page does not restore a terminal session (the PTY exits with the page); switching tabs does not break it. On Linux `node-pty` has to be compiled in place, and when the tools are missing the UI says exactly what to install.
 
-"Delete session" **renames to `.deleted-<timestamp>`** (native delete APIs win when the engine has one). The file stays on disk and can be recovered.
+### Built-in web page
+
+The right pane also opens web pages: type a URL and view it in an iframe, with requests going through **a local proxy** (`/web/p/<url>`) — it fetches the document and strips the `X-Frame-Options` / CSP framing restrictions, so sites like Baidu open too. The proxy has boundaries: HTML/CSS documents only, **no cookies in and none out**, a 12 MB upstream cap, and an iframe sandbox without `allow-same-origin`. For sites that need a login or heavy JS, hit `⧉` to jump to the system browser.
+
+---
+
+## Engines: each runs its own native loop
+
+The engines are not "the same prompt in different costumes" — each is that vendor's own agent loop:
+
+| Engine | How it's wired | Notes |
+|---|---|---|
+| **pi** (default) | Native SDK | The full plugin / skill ecosystem, lazy tool loading, the approval gate, subagents, steering; models and providers are managed by this workbench |
+| **Codex** | app-server (JSON-RPC) | Its own loop and sandbox; sessions are shared with Codex Desktop / CLI; approvals are command- and file-level |
+| **DeepSeek Harness** | ACP | Model and thinking level are switchable; permissions confirmed one by one |
+| **opencode** | ACP | Its own tools / MCP / plugin ecosystem; sessions are shared with the opencode CLI / TUI; approvals follow opencode's own `permission` config |
+| **Claude Code** | ACP (the `claude-code-acp` adapter) | Switchable models, per-call tool confirmation; sessions are shared with the `claude` CLI; this ACP surface exposes neither thinking levels nor subagents |
+| **fake** | Built-in scripted engine | Zero tokens, only for exercising the protocol / tools / approval flow (not in the picker by default) |
+
+The differences (the capability matrix in `server/engine/registry.ts`, which the UI uses to hide buttons):
+
+| Capability | pi | codex | dsh | opencode | claude |
+|---|:-:|:-:|:-:|:-:|:-:|
+| Approvals | ✅ | ✅ | ✅ | per config | ✅ |
+| Model / thinking level | ✅ | ✅ | ✅ | ✅ | model only / no levels |
+| Resume past sessions | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Steering | ✅ | — | — | — | — |
+| Subagent panel | ✅ | — | — | — | — |
+| Workbench-managed providers | ✅ | — | — | — | — |
+| Side chat (in memory) | ✅ | — | — | — | — |
+
+**The models / plugins / MCP panels follow the active engine**: switch to Codex and the panels read Codex's own data (`model/list`, `plugin/list`, `config/read`); claude reads `~/.claude.json` and `~/.claude/settings.json`; opencode reads `opencode.json`. A panel that has nothing wired says so instead of borrowing pi's config.
+
+Engines are switched in the **bottom status bar** (not the top bar), and every session remembers its own engine, model and thinking level.
 
 ---
 
 ## Models and providers
 
-The models panel groups providers into two columns: **official built-ins** (the ones pi's catalog has models for) and **custom providers**.
+![The models panel: the providers with a key or a signed-in subscription on the left, and that provider's endpoint, API shape and model allowlist on the right](docs/screenshots/05-models.png)
+
+- **Subscriptions**: OAuth login (9 providers), usable right after signing in — no key to copy by hand.
+- **Official built-ins**: the ones pi's catalog carries models for — **paste one key and it works**; endpoints and model tables come from the catalog.
+- **Bring your own**: change the API shape (openai-completions / responses / anthropic-messages / codex / typesafe), the base URL and custom headers, and add models one by one.
+- Tick models individually (only ticked ones are saved), batch-test connectivity, pull the list from `/models`, and save the ticked set as the allowlist.
 
-- Built-ins need only **an API key** — endpoint and model table come from pi's catalog.
-- Custom providers let you add models, edit base URLs, **import** from another client (actually `GET {baseUrl}/models` and tick the ones you want) and **test each one**.
-- **Keys never leave the server**: the API returns only `hasKey` and the last four digits; writes are serialized inside the process so concurrent edits can't corrupt files.
+**Keys never leave the server**: the API returns only `hasKey` and the last 4 digits; writes are serialized inside the process so concurrent edits can't corrupt a file.
 
-The config truth is spread over three files plus the engine catalog: `~/.pi/agent/models.json` (pi's own writable provider catalog), `models-store.json` (legacy location), `auth.json` (`api_key` or oauth subscription credentials), with the allowlist in `settings.json.enabledModels`.
+The truth is spread across `~/.pi/agent/models.json` (the provider catalog), `models-store.json` (the legacy location) and `auth.json` (`api_key` or OAuth credentials), with the allowlist in `settings.json.enabledModels`.
 
 ---
 
-## Approvals and security model
+## Skills
 
-- Binds `127.0.0.1` by default and validates `Origin` / `Host` (including the `AGENT_WEB_ALLOWED_HOSTS` allowlist, the vite port and LAN addresses).
-- Identity: loopback peer **and** loopback Host → allowed. With no password set, remote requests always get 403. With a password, either the cookie (`agent-web-auth`, 7 days, HttpOnly) or HTTP Basic will do; failed logins are throttled at 20 attempts / 10 minutes.
-- Tools and commands go through approvals: **read-only tools** (read / grep / find / ls) and read-only commands pass automatically, everything else is asked per `scopeKey` (tool + executable name or target directory). Picking "always allow" writes the rule into `approval-rules.json` (atomic write; a corrupt file is treated as empty).
-- When a turn ends, every pending approval for that session is cleared so nothing hangs waiting for a human.
-- Uploaded temp files and session caches live in the data directory, never in your project.
+![The skills panel: installed / enabled / disabled on the left, this skill's SKILL.md summary and its directory files on the right](docs/screenshots/06-skills.png)
 
-> Exposing it remotely is explicit: `-H`, `-P` and `--allow-host` must all be present, or it won't work.
+Reads `~/.agents/skills/<dir>/SKILL.md`; the list parses frontmatter only (no yaml dependency). **Enabling or disabling means renaming `SKILL.md` to `.SKILL.md.disabled`** — there is no second state file, so what you see in the CLI agrees with what you see here.
+
+**Skill Hub**: search by category plus one-click install (200k+ index); it can also install a specific `skills/<name>` from a Git repo, or create one by hand.
 
 ---
 
-## Subagents (parallel, manageable)
+## MCP
 
-The pi engine ships its own subagent implementation (**no pi-subagents plugin required**):
+![The MCP panel: global and project configs, enable/disable and exposure, test connection, OAuth](docs/screenshots/07-mcp.png)
 
-- **How**: the main agent gets an `Agent` tool (`subagent_type` / `prompt` / `description` / `run_in_background`) and can run several at once. Every delegation is **a real pi session** with its own context, session file and tool allowlist.
-- **Where to watch**: run cards appear under the conversation (the strip above the composer) with status, duration, tool count, tokens and cost. Expand one to see the raw result and its session file path, and stop any of them at any time. Switching sessions swaps the strip to that session's runs. A top-bar badge gives the at-a-glance count.
-- **Management**: the panel manages **templates** (built-in explore / general-purpose / plan, each disableable; create / edit / delete your own). Templates live at `~/.pi/agent/agents/*.md` with frontmatter `name / display_name / description / tools / model / thinking / max_turns`; the body is the system prompt — the same format pi uses, so they're readable, editable and git-friendly.
-- **Concurrency**: a cap of 1–12 (default 4) in the panel; extra delegations queue. Turn the master switch off and the model no longer sees the `Agent` tool.
-- **Isolation**: subagents load no skills / plugins / themes / context files by default (fast and predictable). They inherit the parent's model when they don't pin their own. Models registered by extensions fail inside subagents with "specify a model in the template".
+Reads and writes two config files: `~/.pi/agent/mcp.json` (global) and `<workspace>/.pi/mcp.json` (project), where **a project entry with the same name overrides the global one**, and writes preserve indentation and CRLF.
 
-Subagent session files are archived next to the parent session (`<parent session dir>/<parent name>/subagents/`) and never appear in the sidebar.
+- exposure has four levels: **codemode (default) / deferred / direct / hidden**;
+- **Test connection**: a real handshake plus `tools/list`, then disconnect; it reports the connection state and the tool count;
+- OAuth login, pick a server from a marketplace, paste a command / URL / JSON and let it be parsed;
+- **the config is the truth**: pi connects at session start, so edits apply to **new sessions**.
 
 ---
 
-## MCP · plugins · skills
+## Plugins
 
-**MCP**: reads and writes `~/.pi/agent/mcp.json` (global) plus `<workspace>/.pi/mcp.json` (project), where a project entry with the same name overrides the global one. Writes preserve indentation and CRLF.
-Exposure has four levels `codemode | deferred | direct | hidden` and tools are namespaced `mcp__<name>`.
-**The config is the truth** — pi connects at session start, so panel changes apply to **new sessions**. Testing a connection does a real handshake with `@earendil-works/pi-mcp` (`tools/list`) and disconnects immediately; OAuth goes through `pi mcp login`. There's also a marketplace (registry / smithery / github) and a "paste a command / URL / JSON and let it parse" flow.
+![The plugins panel: the four states of a pi package, and disabling per package](docs/screenshots/09-plugins.png)
 
-**Plugins**: these are pi packages — `settings.json`'s `packages` (npm / git / local) plus loose `~/.pi/agent/extensions/` and `<ws>/.pi/extensions/`. State is decided by the pi SDK's `resolve()` (querying **never** triggers `npm install`), with four states: `loaded / installed / missing / disabled`. Disabling writes `autoload:false` and deletes nothing.
+Plugins are pi packages: the `packages` entry in `settings.json` (npm / git / local directory) plus the loose `~/.pi/agent/extensions/` and `<ws>/.pi/extensions/`.
 
-**Skills**: read from `~/.agents/skills/<dir>/SKILL.md`; the list parses frontmatter only (no yaml dependency) and caps the file listing at 200 entries.
-**Toggling = renaming `SKILL.md` to `.SKILL.md.disabled`** — there is no second state file. Skill Hub supports category search plus zip installs, and git clone can target `skills/<name>`.
+State comes from the pi SDK's `resolve()` (**querying never triggers `npm install`**), with four states `loaded / installed / missing / disabled`; disabling per package writes `autoload:false` and deletes nothing.
 
 ---
 
-## Architecture: SSE + RPC, no WebSocket
+## Subagents: run many, manage each
 
-Early versions used WS; today there are **only two HTTP channels** (ADR-0032):
+![The subagents panel: built-in templates, default concurrency, the master switch](docs/screenshots/08-subagents.png)
 
-```
-browser ──GET  /api/events (SSE)──▶ server   snapshot · message_delta · notice
-        ──POST /api/rpc   (JSON)──▶          ClientRequest → { reply } consumed in place
-```
+Once the main agent has the `Agent` tool it can run several subagents in parallel, and each one is **a real session** (its own context, session file and tool allowlist).
 
-- **Downstream**: one full snapshot first, then deltas only. Message text arrives as `message_delta` chunks; structural changes (tool cards, errors, state) push a new snapshot, coalesced in a 60 ms window — snapshots are droppable, events are not. SSE sends a heartbeat every 25 s and supports gzip `Z_SYNC_FLUSH`.
-- **Upstream**: `send_message` (text / attachments / mode), `interrupt`, `approve`, `new_chat`, `switch_conversation`, `set_engine` / `set_model` / `set_thinking_level` / `set_approval_mode`, `cancel_queued`, `rename_session`, and a handful for providers and subagents.
-- **The protocol lives in one place**, `server/protocol.ts`, and the frontend reuses its types; unit tests keep both ends aligned.
-- **The snapshot is the single source of truth**: the frontend's `store.ts` uses `useSyncExternalStore` and replaces state wholesale when a snapshot arrives. Locally it keeps only optimistic state like `preview` / `draft` / `pendingActive`.
+- **Watch**: the subagent card strip above the composer — status, duration, tool count, tokens, cost. "View result" expands the raw result and the session file path in place, and any single run can be stopped. The heading gives the at-a-glance count (`2 running` / `8 finished`).
+- **Manage**: the top-bar "subagents" panel manages **templates** (built in: explore / general-purpose / plan, each disableable; you can also create, edit and delete your own): `name / display_name / description / tools / model / thinking / max_turns`. They land in `~/.pi/agent/agents/*.md`, in the same format as pi's agent files — readable, editable, git-friendly.
+- **Concurrency**: 1–12 (default 4); anything beyond that queues. Turn the master switch off and the model no longer sees the `Agent` tool.
+- **Isolation**: subagents load no skills / plugins / themes / context files by default (fast and predictable); a subagent that doesn't pin a model keeps using the parent session's model.
 
-**Process model**: `cli.ts` parses flags → `session/lock.ts` grabs `<dataDir>/server.lock` (`{pid,port,startedAt}`; a live pid means refuse to start, a dead pid means take over the stale lock) → `runtime.init()` → `listen`. `SIGINT/SIGTERM` and `/api/shutdown` share one graceful shutdown path (flush, disconnect engines, release the lock).
+A subagent's session file is archived next to the parent session (`<parent session dir>/<parent name>/subagents/`) and never shows up in the sidebar's project list.
 
 ---
 
-## Development
+## Push and voice
 
-```bash
-npm run dev          # starts both processes with one command
-```
+<table><tr>
+<td width="50%"><img src="docs/screenshots/11-push.png" alt="Push: local push state, target devices, test push"></td>
+<td width="50%"><img src="docs/screenshots/10-voice.png" alt="Voice: four event sounds plus local TTS"></td>
+</tr></table>
 
-- Externally there is still a single port **25257** (Vite listens and proxies); the backend hides on internal **25258**, so dev and prod use the same URL.
-- Frontend HMR via Vite, backend auto-restart via `tsx --watch`.
-- Phone debugging: `npm run dev -- --host 0.0.0.0`.
+**Push**: Web Push (VAPID) subscriptions, one notification per finished turn — title is the project, body is the session, with a ❌ / ⏹ prefix for failures and interrupts. Multiple devices, a test push, and a one-click clear-all. Needs https or localhost.
 
-| Command | Purpose |
-| --- | --- |
-| `npm test` | `node --test` over `tests/unit/*.test.ts` (22 files, no extra dependencies) |
-| `npm run typecheck` | Two `tsc --noEmit` runs: server + web |
-| `npm run lint` | oxlint over `server` / `web/src` / `scripts` |
-| `npm run format` | Prettier across the repo (`format:check` only checks; `*.md` is deliberately skipped) |
-| `npm run build` | Server `tsc` + frontend `vite build` into `web/dist` |
-| `npm run icons` | Regenerate PWA icons with playwright-core |
+**Voice**: four event sounds (start / finish / error / waiting for approval) with preview and adjustable volume; local TTS reads the final reply using the browser's built-in voices, with adjustable rate and voice, and never touches the network.
 
-CI (`.github/workflows/ci.yml`): `npm ci` → typecheck → lint → test → build, on ubuntu + Node 22.
+---
+
+## Settings
+
+![Settings → Appearance: three font sizes, content width in 4 steps, 6 palettes](docs/screenshots/12-settings.png)
+
+The top bar is the entry point for every panel, and **each entry can be hidden in Settings → Interface** (settings and the split toggle are exempt — they're the only way back to the others). The sidebar and the right pane both drag wider and collapse, and their widths are remembered locally in `localStorage`.
+
+The "settings" button opens five pages:
+
+| Page | Contents |
+|---|---|
+| **Interface** | Which top-bar entries show (text and icon ticked separately), which status-bar chunks show (queue / working / context usage), whether cost shows in the conversation, which blocks sit above the composer (templates / thinking / quick commands), and whether thinking blocks and tool cards start expanded |
+| **General** | The text of your quick phrases and the default thinking level — saved server-side, identical on every device |
+| **Appearance** | Three font sizes (chat body / sidebar project names / sidebar session names, slider 2–20px), content width in 4 steps (720 / 900 / 1100 / full), 6 palettes (bright white, warm paper, mist teal, Tokyo night, mocha, nord), and the top-bar name and logo (hideable, or replaced with your own) |
+| **Language** | Chinese / English, applied immediately |
+| **Shortcuts** | 11 actions, rebindable, clearable and restorable to defaults, plus a cheat sheet |
+
+Appearance, interface and language preferences stay on the device only (`localStorage`, with the `agent-web.` prefix) — one copy per phone, tablet and desktop. Only the quick phrases in "General" are shared across devices.
+
+---
+
+## Mobile
+
+<table><tr>
+<td width="34%"><img src="docs/screenshots/16-mobile.png" alt="Mobile single column: icon-only top-bar entries, 18px composer"></td>
+<td width="34%"><img src="docs/screenshots/17-mobile-drawer.png" alt="On a phone the project sidebar is an overlay drawer"></td>
+</tr></table>
+
+On narrow screens (mobile UA or ≤400px) the layout collapses to a single column:
+
+- the sidebar becomes an overlay drawer (`clamp(260px, 76vw, 340px)`, tap the scrim to close, closes on its own after you pick a session);
+- the top bar wraps, keeps icons only, and scrolls horizontally;
+- the right-pane workspace becomes a full-screen second page that starts below the top bar using `100dvh` (dodging the iOS toolbars);
+- the composer is 18px so iOS doesn't zoom on focus; the model menu becomes a bottom sheet;
+- the status bar scrolls horizontally, and the context-usage popover becomes a full-width sheet.
+
+---
+
+## Sessions: pin, archive, fork, move project
+
+The sidebar groups sessions into "projects" by directory:
+
+| Action | Behaviour |
+|---|---|
+| Pin | Lifts a session or a project to the top |
+| Rename | For pi: append `session_info.name` to the end of the jsonl |
+| Archive | Into "archived", undoable |
+| Delete | Renames to `.deleted-<timestamp>` (the engine's native delete is preferred when it has one) — **the file is still on disk** |
+| Fork | Derive a new session from one message (the title becomes `Branch · …`), the original untouched |
+| Move project | Drag a session row onto another project; the id and history stay, only the `cwd` in the file header changes and the directory is moved |
+
+Sorting is a deliberate choice: **newest-created first inside a group** — a new session lands on top, and updating an old one doesn't move it (sort by last activity instead and a single message in an old session shoots it to the top, dragging the whole list along).
+
+---
 
-### Directory layout
+## Shortcuts and slash commands
+
+**Every shortcut** is rebindable in Settings → Shortcuts (a binding must include `Mod`/`Alt`; bare letters are rejected). On macOS `Mod` is ⌘, elsewhere it's Ctrl.
+
+| Action | Default | Action | Default |
+|---|---|---|---|
+| New session | `Mod+K` | Open right panel | `Mod+Alt+O` |
+| New project | `Mod+M` | Close right panel | `Mod+Alt+W` |
+| Temp session | `Mod+Shift+K` | Toggle left sidebar | `Mod+Alt+L` |
+| Settings | `Mod+Alt+S` | Files | `Mod+Alt+F` |
+| New terminal | `Mod+Alt+T` | Search file contents | `Mod+Shift+F` |
+| Shortcut cheat sheet | `Mod+/` | | |
+
+**Slash commands** pop up when you type `/` in the composer. There are two kinds — `local` ones the workbench runs itself, and `to the agent` ones handed to the engine verbatim as a message:
+
+| Command | Kind | What it does |
+|---|---|---|
+| `/new [first message]` | local | New conversation, optionally with its first message |
+| `/name <name>` | local | Rename the current session |
+| `/model <name>` | local | Switch model (fuzzy match on id or display name) |
+| `/thinking <level>` | local | Set the thinking level (off / low / … / max) |
+| `/copy` | local | Copy the last assistant message |
+| `/session` | local | Message count / tokens / cost for the session |
+| `/resume` | local | Refresh the session list (sessions another terminal just opened) |
+| `/skill <skill name>` | to the agent | Use a skill (the panel lists the installed ones) |
+| `/compact [note]` | to the agent | Compact the context |
+| `/plan [on\|off]` | to the agent | Turn plan mode on or off |
+| `/cwd <path>` | to the agent | Change the working directory |
+
+---
+
+## Architecture: SSE + RPC, no WebSocket
 
 ```
-oh-my-agent-web/
-├─ server/                 Backend (Express 5, TypeScript ESM)
-│  ├─ cli.ts               Command entry: start / stop / restart / status / version / upgrade
-│  ├─ index.ts             Process assembly: middleware, routes, static assets, graceful exit
-│  ├─ protocol.ts          Single source for the protocol (frontend reuses the types)
-│  ├─ engine/              Engine adapters: pi (native SDK) / codex / dsh / opencode (ACP) / fake
-│  │                       plus the capability matrix (registry), catalog, wiring, pi-plugins
-│  ├─ session/             Runtime: runtime, turn-*, approval bridge, rename/delete, lock, settings
-│  ├─ sessions/            HTTP routes for deleting sessions (scanning lives in session/pi-sessions.ts)
-│  ├─ snapshot/            Server state snapshots: state, buildSnapshot, fan-out, 60 ms coalescing
-│  ├─ http/                auth, live-routes (SSE + RPC), aux-routes, compression, file headers
-│  ├─ files/               File tree, preview, search, media streaming, git branches
-│  ├─ terminal/            PTY sessions and their SSE stream
-│  ├─ approval/            Approval scopes and rules
-│  ├─ providers/           Providers / model catalogs / probes / imports / subscription OAuth
-│  ├─ mcp/                 mcp.json read-write, connectivity probe, OAuth, marketplace
-│  ├─ skills/              Skill discovery, toggling, Hub installs
-│  ├─ subagents/           Subagent template storage (`~/.pi/agent/agents/*.md`)
-│  ├─ plugins/             HTTP routes for plugin packages
-│  ├─ push/                Web Push (VAPID)
-│  ├─ markers/             Parsing and stream-filtering `[[action:suggest:…]]` markers
-│  └─ util/                env, paths, spawn-cli (cross-platform), origin, etc.
-├─ web/                    Frontend (React 19 + Vite + TypeScript)
-│  ├─ src/components/      ~70 components: sidebar, message stream, composer, file tree, terminal, panels
-│  ├─ src/styles/          ~45 sectioned CSS files + six theme palettes (no CSS framework)
-│  ├─ src/ws.ts            SSE + RPC client (the name is historical)
-│  └─ src/store.ts         Snapshot store (useSyncExternalStore)
-├─ scripts/                Dev dual-process, installers, prebuild pruning, icon generation
-├─ tests/unit/             node:test unit tests
-├─ docs/adr/README.md      ADR index
-└─ docs/screenshots/       Real screenshots used by the READMEs (PNG 256 colors, ~1.4 MB)
+browser ──GET  /api/events (SSE)──▶ server   one snapshot first, deltas afterwards
+        ──POST /api/rpc   (JSON)──▶         ClientRequest → { reply } consumed in place
 ```
 
-### Code conventions
+- **Downstream**: one complete snapshot first, then deltas only. Text arrives as `message_delta` chunks appended block by block; structural changes (tool cards, errors, state) push a fresh snapshot, coalesced in a 60 ms window — snapshots are droppable, events are not. SSE heartbeats every 25 s.
+- **Upstream**: `send_message`, `interrupt`, `approve`, `new_chat` (optionally with `ephemeral`), `switch_conversation`, `set_engine` / `set_model` / `set_thinking_level` / `set_approval_mode`, `persist_conversation`, `close_ephemeral`, `fork_session`, `move_session`, `cancel_queued`, `rename_session` and more.
+- **The protocol has a single source** in `server/protocol.ts`; the frontend reuses its types, so one definition serves both ends.
+- **The snapshot is the only source of truth**: `store.ts` uses `useSyncExternalStore` and replaces everything when a snapshot arrives. Locally only optimistic state survives (`preview` / `draft` / `pendingActive`).
+- **Each client sees its own session** (ADR-0033): one server, two devices, each parked on a different conversation; bulk data such as the session list is only sent to a client when that client needs it.
 
-- Prettier: **tab indentation**, `printWidth 120`. oxlint runs its default rule set.
-- 400 lines per file is a guardrail; exceeding it means splitting (`cli-info.ts` and `snapshot/*` exist for that reason).
-- **ADR prose lives in the file-header comment of the code it constrains**, not in standalone `docs/` files — anyone editing the code will read it. `docs/adr/README.md` is only an index from number to file. Update that table when you change the code.
+Process model: `cli.ts` parses the flags → `session/lock.ts` grabs `<dataDir>/server.lock` (a live pid refuses to start, a dead pid means taking over a stale lock) → `runtime.init()` → `listen`. `SIGINT` / `SIGTERM` / `/api/shutdown` all go through the same graceful exit (flush, disconnect engines, release the lock).
 
 ---
 
-## Install size: pick the command that fits
+## Where data lives
 
-Most of the dependency tree is frontend build-time weight (`mermaid` alone is 121 MB, plus React) and build tools that only matter on your machine. At runtime the server needs just
-`express` / `web-push` / `node-pty` / `@earendil-works/pi-*` — the browser half already ships as `web/dist`.
-That's why `react` / `mermaid` / `xterm` / `highlight.js` all live in `devDependencies`:
+| Content | Location |
+|---|---|
+| pi sessions | `~/.pi/agent/sessions/<encoded cwd>/<ISO>_<uuid>.jsonl` (first line `{type:"session",id,timestamp,cwd}`) |
+| Codex sessions | Codex's own thread store (`thread/list \| resume \| delete`) |
+| opencode / DSH / claude sessions | Their own data dirs (opencode lists per cwd with `session/list`; DSH reads `~/.dsh`; claude reads `~/.claude`) |
+| Session titles | For pi, the first user message (reads only the first 60 lines); renaming appends `session_info.name` |
+| Workbench state | `<dataDir>/settings.json`, `approval-rules.json`, `server.lock`, `logs/`, `uploads/`, `push-subscriptions.json`, `vapid-keys.json` |
+| Skills / subagent templates / MCP | `~/.agents/skills/`, `~/.pi/agent/agents/`, `~/.pi/agent/mcp.json` |
+| Local UI preferences | Browser `localStorage` (`agent-web.` prefix: theme, font sizes, widths, shortcuts, notes, tabs) |
 
-| Scenario | Command | Packages | Disk |
-|---|---|---|---|
-| Developing / building yourself | `npm ci` | 456 | 547 MB |
-| Already built, just run it | `npm ci --omit=dev` | 192 | **158 MB** (~3 s) |
-| Build then slim down | `npm ci && npm run build && npm prune --omit=dev` | 192 | **158 MB** |
-| Ship to another machine | `npm pack` → `npm i -g ./oh-my-agent-web-*.tgz` | 193 | 223 MB (3.1 MB tarball, README screenshots included) |
+---
 
-Two automatic slimming steps run in `postinstall` (`scripts/prune-prebuilds.mjs`):
+## Security model
 
-- **Keep only the current platform's `node-pty` prebuilds**: the package ships binaries for four platforms, and the two Windows ones alone are 58 MB. Pruning on macOS / Linux takes 62 MB → 5 MB; `npm ci` restores them as-is.
-- Fix the executable bit on `spawn-helper`.
+- Binds `127.0.0.1` by default and validates `Origin` / `Host` (including the `AGENT_WEB_ALLOWED_HOSTS` allowlist, the vite port and LAN addresses).
+- Identity: a loopback peer **and** a loopback Host → allowed. With no password set, remote requests always get 403. With a password, either the cookie (`agent-web-auth`, 7 days, HttpOnly) or HTTP Basic will do; failed logins are throttled at 20 attempts / 10 minutes.
+- Tools and commands go through approvals: **read-only tools** (read / grep / find / ls) and read-only commands pass automatically, everything else is asked per `scopeKey` (tool + executable name or target directory). Choosing "always allow" writes the rule into `approval-rules.json` (atomic write; a corrupt file counts as empty).
+- When a turn ends, every pending approval for that session is cleared, so nothing hangs waiting for a human.
+- Uploaded temp files and session caches live in the data directory, never in your project.
+- The built-in web page's proxy carries no cookies, and its iframe sandbox omits `allow-same-origin` (otherwise remote JS could reach `localStorage` and the RPC endpoint).
 
-> Of the remaining 158 MB, almost everything is pi's model layer: the official SDKs for each provider (`openai` 17.6 MB, `@google/genai` 10.8 MB, `@anthropic-ai/sdk` 9.1 MB, `@aws-sdk/*` + `@smithy/*` 5.2 MB) —
-> all hard dependencies of `@earendil-works/pi-ai`, unavoidable without trimming vendors.
+> Exposing it remotely is an explicit act: `-H`, `-P` and `--allow-host` must all be present — miss one and it stays shut.
 
 ---
 
-## Troubleshooting
+## Development
 
-> **Why `npm ci` and not `npm install`**: this project's direct dependencies are all very new (most within a month of release).
-> `npm install` re-resolves the version ranges from `package.json` against the registry, so if your mirror (corporate Nexus, npmmirror, etc.) hasn't synced those versions yet you get `npm error notarget No matching version found for …`.
-> `npm ci` uses the exact versions from the lockfile and never touches that path.
+From the repo root, run `npm install` first, then:
+
+```bash
+npm run dev          # starts both processes with one command
+```
+
+- Externally there is still a single port **25257** (Vite listens and proxies); the backend hides on internal **25258**, so dev and production use the same address.
+- Frontend HMR via Vite; the backend auto-restarts through `tsx --watch`.
+- Phone debugging: `npm run dev -- --host 0.0.0.0`.
+
+| Command | Purpose |
+|---|---|
+| `npm run typecheck` | Two `tsc --noEmit` runs: server + web |
+| `npm run lint` | oxlint over `server` / `web/src` / `scripts` |
+| `npm run format` | Prettier across the repo (`format:check` only checks; `*.md` is deliberately skipped) |
+| `npm run build` | Server `tsc` + frontend `vite build` into `web/dist` |
+| `npm run icons` | Regenerate the PWA icons with playwright-core |
+
+CI (`.github/workflows/ci.yml`): `npm ci` → typecheck → lint → test → build, on ubuntu + Node 22.
+
+---
+
+## Troubleshooting
 
-Check these in order:
+> **Why `npm ci` and not `npm install`**: the direct dependencies are all very new, and `npm install` re-resolves the version ranges against the registry — if your mirror (corporate Nexus, npmmirror, …) hasn't synced those versions you get `npm error notarget`. `npm ci` uses the exact versions from the lockfile.
 
-1. `npm error notarget No matching version found` → the mirror is behind. Check `npm config get registry`, then retry against the official one: `npm ci --registry=https://registry.npmjs.org/`.
-2. `EBADENGINE` / pi complains about the Node version right at startup → you need Node ≥ 22.19 (`node -v`).
-3. `node-pty` fails to build (mostly on Linux) → prebuilds ship for macOS / Windows only, so Linux compiles it in place and needs `python3`, `make`, `g++`.
-4. Won't start but `omaw status` mentions a stale lock → a previous process didn't exit cleanly; the next `start` takes over automatically. If it's truly stuck, delete `<dataDir>/server.lock`.
-5. Port already in use → `omaw -p 25258`, or run `omaw stop` first.
+1. `npm error notarget No matching version found` → the mirror is behind. Check `npm config get registry`, then fall back to the official one: `npm -g install oh-my-agent-web --registry=https://registry.npmjs.org/`.
+2. `EBADENGINE` / a Node version complaint at startup → you need Node ≥ 22.19 (check with `node -v`).
+3. `node-pty` fails to build (mostly on Linux) → install `python3` / `make` / `g++` before `npm -g install`, or let the one-line installer handle it with `--with-build-tools`.
+4. It won't start but `oh-my-agent-web status` mentions a stale lock → a previous process didn't exit cleanly; the next `start` takes over automatically. If it's truly stuck, delete `<dataDir>/server.lock`.
+5. Port already in use → `oh-my-agent-web -p 25258`, or run `oh-my-agent-web stop` first.
+6. The built-in web page is blank → that site needs a login or heavy scripts, and the proxy does not tunnel cookies; hit `⧉` to use the system browser.
 
-Windows pitfalls we've already hit (shell parsing, killTree, path checks, chmod, CRLF) are catalogued with P0/P1/P2 severities in `WINDOWS-COMPAT.md`.
+Windows differences in shell resolution, process-tree teardown, path handling, permissions and CRLF are all centralised in three modules: `server/util/spawn-cli.ts` (PATH/PATHEXT, `.cmd` via `cmd.exe`, `killTree`), `server/util/paths.ts` and `web/src/path-utils.ts` (separators and absolute paths), and `server/util/file-mode.ts` (`icacls` on Windows). Read those headers before touching cross-platform code.
 
 ---