diff --git a/AGENTS.md b/AGENTS.md
index 33f66bc9..b95b6e69 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,46 +11,46 @@ pnpm build       # build lib, vscode extension, and website
 
 ## Architecture
 
-- **lib/** — Shared React + TailwindCSS frontend library (components, platform abstraction, tests, Storybook)
-- **standalone/** — Tauri desktop app with Node.js sidecar for native PTY via node-pty
-- **vscode-ext/** — VS Code extension wrapping the lib in a webview with native PTY backend
-- **website/** — Marketing website bundling part of the lib as an interactive demo
-- **server/** — Hono coordinating server for remote control: selfhost accounts + passkey auth, WebSocket relay between Pocket clients and Hosts, serves the built Pocket app
-- **server-lib-common/** — Runtime-agnostic security primitives + wire contract shared by `server`, the Host module in `lib`, and the Pocket app
-
-## Project Structure
-
-- `lib/` — Core UI library (pnpm) — Storybook, tests, shared components
-- `lib/src/lib/platform/` — Platform abstraction layer (`PlatformAdapter` interface, fake + VSCode adapters)
-- `standalone/` — Tauri app (Rust + Vite frontend)
-- `standalone/sidecar/` — Node.js PTY manager, bundled as Tauri sidecar
-- `standalone/src-tauri/` — Rust backend that bridges webview ↔ Node.js sidecar
-- `vscode-ext/` — VS Code extension (esbuild, node-pty via forked child process)
-- `website/` — Marketing site (Vite, uses FakePtyAdapter for demo)
-- `server/` — Selfhost server (Hono; accounts in local JSON files, no database)
-- `server-lib-common/` — Shared security + wire contract (bare ES2022 — no DOM or Node types)
-- `lib/src/remote/` — Remote control: `host/` (laptop side), `client/` (phone-side protocol + `RemotePtyAdapter`), `pocket-app/` (Pocket shell), `ws.ts` (shared socket surface)
+- **`lib/`** — Shared React + TailwindCSS frontend library: components, tests, Storybook.
+  - `lib/src/lib/platform/` — platform abstraction (`PlatformAdapter` interface, fake + VSCode adapters)
+  - `lib/src/remote/` — remote control: `host/` (laptop side), `client/` (phone-side protocol + `RemotePtyAdapter`), `pocket-app/` (Pocket shell), `ws.ts` (shared socket surface)
+- **`standalone/`** — Tauri desktop app (Rust + Vite frontend).
+  - `standalone/sidecar/` — Node.js PTY manager (native PTY via node-pty), bundled as the Tauri sidecar
+  - `standalone/src-tauri/` — Rust backend bridging webview ↔ sidecar
+- **`vscode-ext/`** — VS Code extension wrapping the lib in a webview (esbuild; node-pty via forked child process)
+- **`website/`** — Marketing site (Vite) bundling part of the lib as an interactive demo on `FakePtyAdapter`
+- **`server/`** — Selfhost coordinating server for remote control (Hono): accounts + passkey auth in local JSON files (no database), WebSocket relay between Pocket clients and Hosts, serves the built Pocket app
+- **`dor/`** — The `dor` CLI (stricli) staged onto the `PATH` of every Dormouse-launched terminal; talks to its host over a private control socket
+- **`server-lib-common/`** — Security primitives + remote wire contract shared by `server`, the Host module in `lib`, and the Pocket app (bare ES2022 — no DOM or Node types)
+- **`dor-lib-common/`** — Cross-platform external-process spawning (`spawnAndCapture`) shared by `dor` and the `lib` host. Despite the parallel names, the two `*-lib-common` packages are unrelated: `server-lib-common` is remote security/wire, `dor-lib-common` is spawn plumbing.
 
 ## Specs
 
 The primary job of a spec is to be an accurate reference for the current state of the code. Read the relevant spec before modifying a feature it covers — the spec describes invariants, edge cases, and design decisions that are not obvious from the code alone.
 
-- **`docs/specs/glossary.md`** — Canonical vocabulary: the **Surface** model (a Pane's durable occupant — a terminal **Session** or a **browser** surface, with a per-kind axis table), Session states and layers (Process / Registry / View / Link / Activity / Snapshot), the `Window ⊃ Workspace ⊃ Pane ⊃ Surface` containment hierarchy and the Workspace union status, transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state, a surface kind, or a verb.
-- **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, the standalone workspace strip (tabs, switching, lifecycle), session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `standalone/src/AppBar.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode/workspace behavior.
-- **`docs/specs/dor-cli.md`** - the `dor` CLI which is prepended onto the path of every terminal that dormouse launches.
-- **`docs/specs/dor-browser.md`** — The unified `dor` browser surface: a single `BrowserPanel` (`surfaceType: 'browser'`) with a swappable `renderMode` (`ab-screencast` / `ab-popout` / `iframe`). Covers the `dor ab` / `dor agent-browser` screencast viewer that delegates to the user's own agent-browser install (canvas screencast, input forwarding, tabs, pop-out modal) and the `dor iframe` renderer (an `<iframe>` fronted by a host-owned transparent proxy that injects a keyboard side-channel, models focus, and renders real error pages). Builds on the surface handle model in `dor-cli.md`. Read this when touching: `lib/src/components/wall/BrowserPanel.tsx`, `browser-surface.ts`, `browser-url.ts`, `AgentBrowserPanel.tsx`, `IframePanel.tsx`, `SurfacePaneHeader.tsx`, `AgentBrowserScreenModal.tsx`, `lib/src/components/wall/agent-browser-{connection,ports,screen,screenshot-loop,sessions,input}.ts`, `lib/src/lib/agent-browser-tab.ts`, `lib/src/host/agent-browser-host.ts`, `lib/src/host/iframe-proxy.ts`, `iframe-proxy-rewrite.ts`, `lib/src/lib/iframe-proxy-registry.ts`, `lib/src/lib/platform/iframe-proxy-types.ts`, `dor/src/commands/agent-browser.ts`, `dor/src/commands/iframe.ts`, `vscode-ext/src/agent-browser-host.ts`, `vscode-ext/src/iframe-proxy-host.ts`, or the browser surface wiring in `Wall.tsx`.
-- **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle, bell button visual states and interaction, door alert indicators, hardening (a11y, motion, i18n, overflow), notification protocols (`OSC 9` / `OSC 9;4` / `OSC 99` / `OSC 777` / `BEL`), the `ActivityNotification` model, notification text handling and security, the notification preview/detail UI, and the Workspace union projection (ringing/todo/count). Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, `AlertManager` notification/progress paths, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, the `a`/`t` keyboard shortcuts, or TODO notification preview UI. Layout.md defers to this spec for all alert/TODO behavior.
-- **`docs/specs/terminal-state.md`** — Terminal semantic state for CWD, shell prompt/editing/running/finished lifecycle, command runs, terminal title fallback, normalized semantic OSC events (`OSC 7`, `OSC 9;9`, `OSC 133`, `OSC 633`, `OSC 1337`, `OSC 0/2`), title-candidate diagnostics, header derivation, and grouping keys. Read this when touching `terminal-state.ts`, `terminal-state-store.ts`, semantic event parsing in `terminal-protocol.ts`, adapter semantic event forwarding, or derived pane/door labels.
-- **`docs/specs/terminal-escapes.md`** — Registry of every terminal escape sequence Dormouse parses or responds to: supported OSCs with pointers to the spec defining their behavior (alert.md or terminal-state.md), the canonical parsing-location and `pty:data` strip semantics, supported CSI sequences (`CSI > q`, DECSET/DECRST observation, kitty keyboard protocol) and replay-time CSI filtering, iTerm2 self-identification (env vars, fail-inertly rule), and known-unimplemented iTerm2 and clipboard-capable sequences. Read this when touching: OSC parsing at the PTY data boundary, CSI handlers in `terminal-protocol.ts` / `mouse-mode-observer.ts` / `terminal-report-filter.ts`, the iTerm2 identity env vars (`TERM_PROGRAM`, `LC_TERMINAL`), or adding support for a new escape sequence.
-- **`docs/specs/transport.md`** — Adapter-agnostic protocol shared across VS Code, standalone, and fake adapters: PTY lifecycle (decoupled from webview), `replayChunks`/`scrollbackChunks` buffering, reconnection sequence (`dormouse:init` → `pty:list` + `pty:replay`), the full webview ↔ host message protocol, persisted-session types (including the `PersistedWorkspace` / `PersistedWindow` container and its migration), and universal invariants (shell login args, scrollback trailing newline, replay drop-replies-only). Read this when touching: `pty-manager.ts`, `pty-host.js`, `pty-core.js`, `message-router.ts`, `message-types.ts`, `vscode-adapter.ts`, `fake-adapter.ts`, `reconnect.ts`, `session-save.ts`, `session-restore.ts`, `session-types.ts`, or any code crossing the webview/host boundary.
-- **`docs/specs/vscode.md`** — VS Code-specific layer: hosting modes (WebviewView + WebviewPanel), the webview ↔ Workspace mapping and union-status reflection onto native tab icon/title and view badge, extension manifest, VS Code persistence flow (`workspaceState`, `vscode.setState`, `WebviewPanelSerializer`, deactivate ordering, `mergeAlertStates` rule, `retainContextWhenHidden`), theme integration (`--vscode-*` → `--color-*` with the runtime resolver), CSP, build pipeline, and dream-architecture commands. The transport protocol it speaks (PTY lifecycle, message protocol, persisted-session types) lives in `transport.md`. Read this when touching: `extension.ts`, `webview-view-provider.ts`, `session-state.ts`, `webview-html.ts`, the theme resolver/observer in `terminal-theme.ts`, or VS Code commands and context keys.
-- **`docs/specs/tutorial.md`** — Playground tutorial on the website: 3-pane layout, interactive `tut` TUI runner with three sections (keyboard navigation, alerts/TODOs, copy/paste), per-item detection wired to `WallEvent` / activity store / mouse-selection store, single-key `dormouse-tut-v3` localStorage scheme, theme picker, and FakePtyAdapter extensions (`sendOutput`, `pumpActivity`, `setInputHandler`). Read this when touching: `website/src/pages/PlaygroundDesktop.tsx`, `website/src/pages/PocketPlayground.tsx`, `website/src/components/PocketTerminalExperience.tsx`, `website/src/lib/playground-routing.ts`, the `website/src/pages/Playground.tsx` and `website/src/pages/Pocket.tsx` redirect dispatchers, `website/src/lib/tut-runner.ts`, `website/src/lib/tut-detector.ts`, `website/src/lib/tutorial-state.ts`, `website/src/lib/tut-items.ts`, `website/src/lib/tutorial-shell.ts`, `lib/src/components/ThemePicker.tsx`, `lib/src/lib/themes/`, `lib/src/lib/platform/fake-scenarios.ts` (tutorial scenarios), the `WallEvent` union, or the `onApiReady`/`onEvent`/`initialPaneIds` props on Wall.
-- **`docs/specs/theme.md`** — Theme system: two-layer CSS variable strategy, theme data model, conversion pipeline, bundled themes, localStorage store, shared ThemePicker component, standalone AppBar picker, runtime OpenVSX installer. Read this when touching: `lib/src/lib/themes/`, `lib/src/components/ThemePicker.tsx`, `lib/src/theme.css`, `lib/scripts/bundle-themes.mjs`, `standalone/src/AppBar.tsx` (theme picker), `standalone/src/main.tsx` (theme restore), or `website/src/components/SiteHeader.tsx` (themeAware mode).
-- **`docs/specs/mouse-and-clipboard.md`** — Terminal-owned text selection, copy (Raw / Rewrapped), bracketed paste, smart URL/path extension, mouse-reporting override UI (icon + banner), and the state matrix for which layer owns mouse events. Read this when touching: `lib/src/lib/mouse-selection.ts`, `lib/src/lib/mouse-mode-observer.ts`, `lib/src/lib/clipboard.ts`, `lib/src/lib/rewrap.ts`, `lib/src/lib/selection-text.ts`, `lib/src/lib/smart-token.ts`, `lib/src/components/SelectionOverlay.tsx`, `lib/src/components/SelectionPopup.tsx`, the mouse icon / override banner / Cmd+C-V handling in `lib/src/components/Wall.tsx`, or the parser hooks + mouse listeners in `lib/src/lib/terminal-registry.ts`.
-- **`docs/specs/remote-security-model.md`** — The trust model for remote control, built on two independent primitives: passkeys prove fresh user presence (user credentials, never device identities — they sync), and per-browser non-extractable device keys prove long-lived Client identity. The Host's local ACL authorizes the *pair* of a passkey credential and a device key; the pairing ceremony (local approval on the Host) is the only path into it, and the Host — never the Server — makes the final access decision. Covers the connection requirements (all layers must agree), storage durability (iOS PWA guidance), and device-key-loss recovery. Read this first for anything remote; the other three remote specs build on it. Read this when touching: `server-lib-common/src/security/` (deviceKey, challenge, passkey, acl, pairing, connection), `server/src/handshake.ts`, `lib/src/remote/host/{acl,pairing-approval,remote-host}.ts`, or `lib/src/remote/client/{device-key,webauthn}.ts`.
-- **`docs/specs/remote-api.md`** — The protocol a Client speaks after `authorizeConnection`: one protocol at two consumption depths (phone = directory picker + one attached surface; VR = full wall, future). Defines the v1 scope (terminal-only decisions live in server.md), the directory (snapshot-only, `ringing`/`hasTODO`), attach-is-the-resize (the SIGWINCH repaint is the screen transfer — no snapshot format), last-attach-wins size authority with the "tethering to \<device\>" display, and the staged future work (in-flight replay, semantic command scrollback, thumbnails, grants, VR wall, WebRTC). Read this when touching: `server-lib-common/src/remote/wire.ts` (the fixed wire contract), `lib/src/remote/host/remote-api.ts`, `lib/src/remote/client/{pocket-client,remote-adapter}.ts`, or `server/test/harness/fake-host.mjs`.
-- **`docs/specs/server.md`** — The selfhost coordinating server: env config (`DORMOUSE_SETUP_PASSWORD`, `DORMOUSE_ORIGIN`, …), two-JSON-file state (no database), "WebAuthn without a WebAuthn library" (registration via `response.getPublicKey()`, assertions via the same `verifyPasskeyAssertion` the Host uses), the HTTP API, the relay frame flow (pairing and connect sequence diagrams — one host challenge feeds both the passkey assertion and the device signature, so connecting costs one biometric prompt), the Host and Pocket side responsibilities, and "Running the POC" instructions. Read this when touching: `server/src/` (app, relay, handshake, state), `lib/src/remote/host/enrollment.ts`, or the `dev:pocket-server` flow.
-- **`docs/specs/pocket-app.md`** — Pocket app architecture: the remote session is a `PlatformAdapter` (`RemotePtyAdapter` maps the PTY core onto remote-api one-to-one), so Pocket is auth screens + `MobileTerminalUi`/`MobileWall` — the same composition the website playground runs on `FakePtyAdapter`. Covers the `lib/src/remote/` module layout and the same-origin deployment rule (WebAuthn origin binding + Chrome PNA: selfhost server serves the bundle now; CloudFlare static + routed `/api`+`/ws` for SaaS later). Read this when touching: `lib/src/remote/client/remote-adapter.ts`, `lib/src/remote/pocket-app/`, `lib/vite.pocket.config.ts`, or the Pocket static serving in `server/src/app.ts`.
+Each spec's own `Files` / `Code Map` section is the exhaustive file→spec mapping; the touch points below are the load-bearing areas only.
+
+- **`docs/specs/glossary.md`** — Canonical vocabulary: the **Surface** model (terminal **Session** / **browser** surface), the six Session layers and their states, the `Window ⊃ Workspace ⊃ Pane ⊃ Surface` hierarchy and Workspace union status, transition verbs, invariants I1–I10, and the Liskov contract on Registry APIs. Read this first; every other spec defers to it when naming a state, a surface kind, or a verb.
+- **`docs/specs/layout.md`** — Tiling layout and its interaction model: panes/doors, dockview config, passthrough/command modes, command-mode keyboard dispatch, selection overlay, spatial navigation, minimize/reattach, inline rename, kill confirmation, session lifecycle + persistence recovery, pane animations, and the workspaces-rollout ledger (`## Future`). Touch points: `lib/src/components/Wall.tsx` + `components/wall/`, `Baseboard.tsx` / `Door.tsx` / `TerminalPane.tsx`, the registry/lifecycle/persistence modules in `lib/src/lib/`, and any keyboard/navigation/mode/workspace behavior.
+- **`docs/specs/shortcuts.md`** — Quick-reference table of every keyboard shortcut by mode/context. layout.md owns the behavior; update both when a binding changes.
+- **`docs/specs/alert.md`** — The Activity layer: WATCHING / protocol / command-exit alert tracks, attention model, TODO lifecycle, bell + TODO UI states, notification protocols (`OSC 9` / `9;4` / `99` / `777` / `BEL`) with sanitization and security rules, and the Workspace union projection. layout.md defers to it for all alert/TODO behavior. Touch points: `activity-monitor.ts`, `alert-manager.ts`, notification parsing in `terminal-protocol.ts`, the bell/TODO UI in pane headers and Doors.
+- **`docs/specs/terminal-state.md`** — Per-Session semantic state: CWD, prompt/editing/running/finished lifecycle, command runs, title candidates + header derivation, grouping keys, and the keystroke fallback for shells without OSC integration. Touch points: `terminal-state.ts`, `terminal-state-store.ts`, semantic event parsing in `terminal-protocol.ts`, derived pane/door labels.
+- **`docs/specs/terminal-escapes.md`** — Registry of every escape sequence Dormouse parses, answers, or deliberately ignores: OSC/CSI tables pointing at the owning spec, parsing location + `pty:data` strip semantics, replay-time report filtering, iTerm2 identity, and shell-integration injection. Touch points: OSC/CSI parsing at the PTY data boundary, `terminal-report-filter.ts`, `mouse-mode-observer.ts`, `standalone/sidecar/shell-integration/`, or adding any new escape sequence.
+- **`docs/specs/transport.md`** — Adapter-agnostic webview ↔ host protocol: PTY lifecycle + buffering, the reconnection sequence, message contracts, persisted-session types and migrations, and universal adapter invariants. Touch points: `pty-manager.ts` / `pty-host.js` / `pty-core.js`, `message-router.ts` / `message-types.ts`, the platform adapters, `reconnect.ts` / `session-save.ts` / `session-restore.ts` / `session-types.ts`, anything crossing the webview/host boundary.
+- **`docs/specs/mouse-and-clipboard.md`** — Terminal-owned text selection, copy (Raw / Rewrapped), paste tiers + bracketed paste, smart URL/path extension, mouse-reporting override UI, and the state matrix for which layer owns mouse events. Touch points: the mouse/selection/clipboard modules in `lib/src/lib/`, `SelectionOverlay.tsx` / `SelectionPopup.tsx`, `standalone/sidecar/clipboard-ops.js`.
+- **`docs/specs/theme.md`** — Theme system: two-layer CSS variable strategy (`--vscode-*` → `--color-*`), the consumed-token resolver and registry defaults, terminal color contract, theme data + OpenVSX installer, Storybook simulation, and the theme debugger. Touch points: `lib/src/lib/themes/`, `lib/src/theme.css`, `ThemePicker.tsx`, `lib/scripts/bundle-themes.mjs`, theme restore in the hosts.
+- **`docs/specs/dor-cli.md`** — The `dor` CLI staged onto every Dormouse terminal's `PATH`: bundling + env contract, the `spawnAndCapture` rules for external binaries (`dor-lib-common`), host control-socket plumbing, the Surface handle model, and the implemented command set. Touch points: `dor/`, `dor-lib-common/`, control-request routing in each host, the `Wall.tsx` control handler.
+- **`docs/specs/dor-browser.md`** — The unified browser surface: one `BrowserPanel` with swappable `renderMode` (`ab-screencast` / `ab-popout` / `iframe`), canonical params + surface lifetimes, browser chrome, the Display modal + render swaps, the agent-browser connection/input/pop-out stack, and the iframe proxy + shim + CSP boundaries. Builds on the handle model in dor-cli.md. Touch points: `BrowserPanel.tsx` / `AgentBrowserPanel.tsx` / `IframePanel.tsx` / `SurfacePaneHeader.tsx`, the `agent-browser-*` modules in `lib/src/components/wall/`, `lib/src/host/`, the `dor ab` / `dor iframe` commands.
+- **`docs/specs/vscode.md`** — VS Code host layer: WebviewView + WebviewPanel hosting, webview ↔ Workspace mapping and union-status reflection onto native chrome, the persistence flow and its ordering rules, theme integration + OSC color-query answering, CSP, and the build/dogfood pipeline. The transport protocol it speaks lives in transport.md. Touch points: `vscode-ext/src/`, the theme resolver/observer in `terminal-theme.ts`, VS Code commands and context keys.
+- **`docs/specs/standalone.md`** — Standalone (Tauri) host layer: the Rust ↔ Node-sidecar bridge (invoke commands, JSON-lines stdio), the webview boot sequence, the AppBar (shell dropdown, theme picker, window controls), localStorage persistence at the adapter boundary, sidecar shutdown ordering + parent-PID watchdog, file drop, logging, and the build/dev workflow (including the vite-only `beforeDevCommand` caveat). The transport protocol it speaks lives in transport.md. Touch points: `standalone/src-tauri/src/lib.rs`, `standalone/src/` (main, AppBar, tauri-adapter), `standalone/sidecar/main.js`.
+- **`docs/specs/auto-update.md`** — Standalone auto-update: check → user-approved download → install-on-quit, the Baseboard update notice, Windows sidecar teardown (ConPTY file locks), post-install markers, and per-platform quit behavior. Touch points: `standalone/src/updater.ts`, `UpdateBanner.tsx`, the updater config in `tauri.conf.json`.
+- **`docs/specs/mobile-terminal-ui.md`** — The mobile terminal composition (`MobileTerminalUi` / `MobileWall`): stable viewport + keyboard reserve, touch modes (Gestures / Select / Mouse), radial gesture-menu geometry and interaction, input modes, and Type-mode native-keyboard rules. Shipped in the website Pocket playground and reused by the real Pocket app. Touch points: `lib/src/components/MobileTerminalUi.tsx` / `MobileWall.tsx` / `MobileGestureRadialMenu.tsx`, `lib/src/lib/mobile-gesture-menu.ts`.
+- **`docs/specs/tutorial.md`** — Website playground tutorial: device-specific routes, the `tut` runner + detector + progress state, desktop and Pocket profiles, localStorage keys, the lib hooks that exist for tutorial observability, and the mouse/clipboard feature-coverage matrix. Touch points: the playground pages in `website/src/pages/`, `website/src/lib/tut-*.ts`, `PocketTerminalExperience.tsx`, fake-adapter scenario extensions, the `WallEvent` union.
+- **`docs/specs/remote-security-model.md`** — The trust model for remote control: passkeys prove fresh user presence (user credentials — they sync), non-extractable per-browser device keys prove long-lived Client identity, the Host's local ACL authorizes the *pair* via a local-approval pairing ceremony, and the Host — never the Server — makes the final access decision. Read this first for anything remote; the other three remote specs build on it. Touch points: `server-lib-common/src/security/`, `server/src/handshake.ts`, the security modules in `lib/src/remote/host/` and `lib/src/remote/client/`.
+- **`docs/specs/remote-api.md`** — The protocol a Client speaks after `authorizeConnection`: the shipped terminal-only **protocol-v1** (snapshot directory, attach-is-the-resize, last-attach-wins size authority) and the staged remainder (browser surfaces, in-flight replay, semantic scrollback, tethering display, grants, VR Window, WebRTC). Touch points: `server-lib-common/src/remote/wire.ts` (the fixed wire contract), `lib/src/remote/host/remote-api.ts`, `lib/src/remote/client/`.
+- **`docs/specs/server.md`** — The selfhost coordinating server: env config, two-JSON-file state, "WebAuthn without a WebAuthn library", the HTTP API, the relay frame flow (one host challenge feeds both signatures → one biometric prompt per connect), the Host webview CSP for self-host relays (`DORMOUSE_REMOTE_CONNECT_SRC`), Host/Pocket side responsibilities, the testing harness, and instructions for running it end to end. Touch points: `server/src/`, `lib/src/remote/host/enrollment.ts`, the `dev:pocket-server` flow.
+- **`docs/specs/pocket-app.md`** — Pocket app architecture: the remote session is a `PlatformAdapter` (`RemotePtyAdapter`), so Pocket is auth screens + the mobile-terminal-ui composition; the `lib/src/remote/` module layout and the same-origin deployment rule (WebAuthn origin binding + Chrome PNA). Touch points: `lib/src/remote/client/` + `pocket-app/`, `lib/vite.pocket.config.ts`, the Pocket static serving in `server/src/app.ts`.
+- **`docs/specs/deploy.md`** — Release process: the artifact matrix, release checklist, two-stage pipeline (CI builds unsigned + attests; a local script verifies, signs macOS/Windows, and creates the GitHub Release), Tauri updater manifest, changelog flow, and secrets. Touch points: `.github/workflows/release.yml`, `scripts/sign-and-deploy.sh`, `scripts/bump-version.sh`, the updater config in `tauri.conf.json`.
 
 When updating code covered by a spec, update the spec to match. When the two specs overlap (e.g. pane header elements appear in both), layout.md documents placement and sizing while alert.md documents behavior and visual states.
 
@@ -58,9 +58,21 @@ When editing specs, keep them concise but do not replace invariants or edge case
 
 Every spec that uses Session / Pane / Door / baseboard / passthrough vocabulary leads with a `> See \`docs/specs/glossary.md\` for ...` blockquote (see `layout.md`, `alert.md`, `terminal-state.md`). When introducing glossary vocabulary into a spec that lacks the callout, add it in the same edit.
 
+### Spec lifecycle
+
+Specs are written ahead of the code on purpose: a new component's spec starts as a full design (a "dream"), gets cut down to the smallest slice that unblocks the broader system, that slice is implemented, and the uncut remainder is kept because it was expensive to generate and stays useful for planning. These conventions keep that workflow from eroding the rule that a spec's body is an accurate reference for the current code:
+
+- **The fold.** Everything above a spec's `## Future` section describes the code as it is — present tense, anchored with `Source of truth:` pointers. Everything not yet built lives under `## Future`, which is always the last section of the file. A spec with no unbuilt design has no `## Future` section.
+- **Design-stage specs.** A spec for a component that doesn't exist yet keeps its whole design under `## Future` and opens with `> Status: design — nothing here is implemented yet.` It is indexed above like any other spec.
+- **Named scopes.** When a dream is cut down, record the cut as a named scope at the top of `## Future` (e.g. `**Scope: workspaces-rollout**`), listing what remains in staged order. A scope is defined in exactly one spec; other specs link to it by name and never restate its contents. Rollout ledgers live in the owning spec's `## Future`, nowhere else.
+- **Reservations.** When unbuilt design constrains present code — a reserved wire field, a reserved ref grammar, an additive-evolution guarantee — state that constraint in the body, marked `Reserved:`, pointing at the `## Future` item it serves. Test: if deleting the sentence would let someone break future compatibility today, it belongs in the body.
+- **Promotion is part of done.** Implementing a staged item is not finished until its text moves above the fold — rewritten from "will" to "is", with `Source of truth:` added — and the built portion is deleted from `## Future`. Never leave completed plan text (build orders, phase lists) below the fold; delete it — git history keeps the record.
+
+The mechanically checkable parts of these conventions are enforced by `scripts/spec-lint.mjs` (`pnpm lint:specs`, also the first step of the root `pnpm test`): every spec indexed here, `## Future` last, relative links/anchors resolving, and backticked repo paths existing on disk.
+
 ## Design
 
-See [DESIGN.md](DESIGN.md) for full design context. Key principles:
+See [PRODUCT.md](PRODUCT.md) for users, brand personality, and aesthetic direction (including the anti-references), and [DESIGN.md](DESIGN.md) for the full design system — tokens, named rules, and component vocabulary. Key principles:
 
 1. **Native first** — Inside VSCode, feel indistinguishable from a built-in feature. Use the host's theme tokens.
 2. **Information density without intimidation** — Dense for power users, approachable for beginners. Progressive disclosure.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/DESIGN.md b/DESIGN.md
index 6ffcc1b1..f65a20dd 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -134,7 +134,7 @@ This system has no "primary" accent in the brand sense. The closest analogue is
 - **Terminal Background / Foreground** (`var(--vscode-terminal-background)` / `var(--vscode-terminal-foreground)`): the terminal content surface and xterm default text. Orthogonal to the chrome.
 - **Error** (`var(--vscode-terminal-ansiRed)`): destructive actions and kill-confirm letter flash.
 - **Success** (`var(--vscode-terminal-ansiGreen)`): TODO check, theme-store install confirm.
-- **Alarm** (`var(--vscode-terminal-ansiYellow)` initial; runtime-rotated): bell-ringing alert tint. Per-surface OKLCH hue-rotation by `use-dynamic-palette.ts` from the bg the bell sits on, so the alert pops off any header.
+- **Alarm** (`var(--vscode-terminal-ansiYellow)` baseline; runtime-overridden): bell-ringing alert tint. `computeDynamicPalette()` replaces each `--color-alarm-vs-*` token with plain white or black by the OKLab lightness of the bg the bell sits on (active header, inactive header, or door), so the ringing bell stays maximally legible on any surface.
 
 ### Fixed Exception
 - **Window Close Hover** (`#b92a1b`): the only literal color in the whole system. Native OS close-button hover on Windows/Linux chrome buttons; matches the platform convention across themes.
diff --git a/docs/specs/alert.md b/docs/specs/alert.md
index bf4ba346..929bf355 100644
--- a/docs/specs/alert.md
+++ b/docs/specs/alert.md
@@ -48,6 +48,8 @@ These do not count as attention: mere visibility, command-mode selection, hover,
 
 Attention is lost when the attention timer expires, the app loses focus, the attended Session is minimized or destroyed, or another Session becomes attended. `T_USER_ATTENTION` also acts as the minimum runtime for command-exit alerts.
 
+Source of truth: `cfg.alert` in `lib/src/cfg.ts` defines `T_USER_ATTENTION` and the other timer defaults and their purpose.
+
 ## WATCHING Track
 
 WATCHING is the user-controlled output/silence monitor. It starts fresh when enabled and is disposed when disabled. Meaningful output excludes resize redraw noise during `T_RESIZE_DEBOUNCE`; theme changes, remounts, DOM reparenting, selection, and focus changes are not output.
@@ -61,8 +63,6 @@ WATCHING is the user-controlled output/silence monitor. It starts fresh when ena
 | `MIGHT_NEED_ATTENTION` | A busy Session went quiet. Debounce state. |
 | `ALERT_RINGING` | WATCHING observed likely completion while the Session lacked attention. |
 
-Source of truth: `cfg.alert` in `lib/src/cfg.ts` defines timer defaults and their purpose.
-
 Source of truth: `ActivityMonitor` in `lib/src/lib/activity-monitor.ts` implements the transitions. The invariants the implementation must honor:
 
 - Output drives the monitor up the chain `NOTHING_TO_SHOW` -> `MIGHT_BE_BUSY` -> `BUSY`; silence drives it down `BUSY` -> `MIGHT_NEED_ATTENTION` -> `ALERT_RINGING`. The `MIGHT_*` states are debounce windows in both directions.
@@ -135,10 +135,10 @@ Supported keys:
 
 `title` and `body` chunks append to the pending notification. Completion rings once if the sanitized title or body is nonempty. If `i` is omitted, only a complete single-sequence notification is meaningful.
 
-Management payloads do not ring:
+Management payloads contribute no notification content:
 
 - `p=?` sends a support response advertising the support payload defined in `lib/src/lib/terminal-protocol.ts` (`OSC99_SUPPORT_PAYLOAD`).
-- `p=close`, `p=alive`, `p=icon`, and `p=buttons` are consumed or ignored without creating notification UI.
+- `p=close`, `p=alive`, `p=icon`, and `p=buttons` are consumed or ignored without creating notification UI of their own. Like any chunk, one carrying the (default) `d=1` done flag still completes a pending same-`i` notification, which may then ring on its previously accumulated title/body — kitty's done-flag semantics apply regardless of the final chunk's payload type.
 
 Source of truth: `lib/src/lib/terminal-protocol.ts` defines the pending OSC 99 chunk TTL and max-pending-id cap.
 
@@ -177,7 +177,7 @@ Clearing behavior:
 
 > See `docs/specs/glossary.md` for the Workspace / Window containers.
 >
-> **Partially implemented.** The union *projection* is a pure function — `computeWorkspaceUnion(surfaceIds, activitySnapshot)` in `lib/src/lib/workspace-union.ts` (stage 2b). **VS Code surfacing is implemented**: the editor-tab title and the bottom-panel view badge reflect the union (terminal ring/TODO only; `docs/specs/vscode.md`). Still not built: the **standalone strip indicators** (stage 3). A browser Surface's user-set `todo` round-trips to the activity store live and persists across restart (stage 2a), so it is counted by the projection and shows on the surface's door today.
+> The union *projection* is a pure function — `computeWorkspaceUnion(surfaceIds, activitySnapshot)` in `lib/src/lib/workspace-union.ts`. **VS Code surfacing is implemented**: the editor-tab title and the bottom-panel view badge reflect the union (terminal ring/TODO only; `docs/specs/vscode.md`). A browser Surface's user-set `todo` round-trips to the activity store live and persists across restart, so it is counted by the projection and shows on the surface's door today. The **standalone strip indicators** are staged — see `docs/specs/layout.md` `## Future` (workspaces-rollout).
 
 A Workspace projects a **union status** over the attention state of the Surfaces it contains (terminal Sessions and browser Surfaces alike — see `docs/specs/glossary.md`):
 
@@ -193,10 +193,8 @@ Rules:
 
 Where the union surfaces is host-specific:
 
-- **Standalone:** each inactive Workspace's tab in the strip shows the union `ringing` bell and `todo` pill, reusing the Door indicator vocabulary (`bellIconClass`, the TODO pill). The **active** Workspace's tab shows no union indicator — its rings and TODOs are already visible on its own panes and doors. See `docs/specs/layout.md`.
-- **VS Code:** the host reflects the **terminal** portion of each Workspace's union onto the webview's native chrome — an editor tab's icon (and optionally title) and the sidebar view's numeric badge. Browser-surface TODO stays webview-local and is not shown on native chrome until a future webview→host Surface-state channel exists. See `docs/specs/vscode.md`.
-
-This spec fixes the projection and the surfacing rules; the exact visual treatment of the standalone strip is settled in the Storybook UI pass.
+- **Standalone:** the workspace strip that will show per-tab union indicators is staged with the rest of the strip UI — the behavioral rules live in `docs/specs/layout.md` `## Future` (workspaces-rollout). Today a browser Surface's `todo` shows on its own door, and terminal rings/TODOs show on their panes and doors as specified above.
+- **VS Code:** the host reflects the **terminal** portion of each Workspace's union onto the webview's native chrome — an editor tab's icon (and optionally title) and the sidebar view's numeric badge. Browser-surface TODO stays webview-local; surfacing it on native chrome needs the webview→host Surface-state channel staged in `docs/specs/vscode.md` `## Future`. See `docs/specs/vscode.md`.
 
 ## UI Contract
 
@@ -265,6 +263,19 @@ Security requirements:
 - Bell, TODO, preview, and dialog controls must remain keyboard reachable; dialogs trap focus and support `Escape`.
 - Tooltips, dialog copy, and future localized TODO labels must wrap in narrow layouts.
 
+## Files
+
+| File | Role |
+|------|------|
+| `lib/src/lib/activity-monitor.ts` | Per-Session WATCHING state machine (output/silence timers) |
+| `lib/src/lib/alert-manager.ts` | `AlertManager`: protocol + command-exit tracks, attention, TODO, notification storage, status projection |
+| `lib/src/lib/terminal-protocol.ts` | Notification/progress OSC parsing (`OSC 9` / `9;4` / `99` / `777`, BEL), sanitization limits, OSC 99 chunk state |
+| `lib/src/lib/session-activity-store.ts` | React activity snapshot store, primed alert state, platform delegates |
+| `lib/src/lib/workspace-union.ts` | `computeWorkspaceUnion` projection |
+| `lib/src/components/bell-icon-class.ts` | Bell tilt/animation mapping from public status |
+| `lib/src/components/wall/TerminalPaneHeader.tsx` | Bell button, TODO pill, notification preview and dialog |
+| `lib/src/components/Door.tsx` | Door bell + TODO display |
+
 ## References
 
 - iTerm2 proprietary escape codes (OSC 9, OSC 9;4): https://iterm2.com/documentation-escape-codes.html
diff --git a/docs/specs/auto-update.md b/docs/specs/auto-update.md
index e5f18e18..8835aff4 100644
--- a/docs/specs/auto-update.md
+++ b/docs/specs/auto-update.md
@@ -9,7 +9,9 @@ app launch
   │
   ├─ check for post-install markers in localStorage
   │    ├─ success marker → show "Updated to vX.Y.Z" banner (auto-dismisses after 10s)
-  │    ├─ failure marker → show "Update failed." banner with debug action
+  │    ├─ failure marker → show "Update failed" banner with debug action, then STOP —
+  │    │    the update check is skipped this launch (re-prompting for the version that
+  │    │    just failed would unmount an open debug dialog)
   │    └─ no marker → continue
   │
   ├─ wait 5 seconds
@@ -61,7 +63,7 @@ When a notice has follow-up actions, it uses ` · ` as the separator between the
 
 All states are dismissible via [×]. Dismissing an unapproved `available` notice means no update is downloaded or installed in that session. Dismissing a `downloading` or `downloaded` notice hides it for the session only — it does not cancel an already-approved download/install.
 
-The notice matches the Baseboard's existing text style (9px mono, `text-muted`). It's pushed right via `ml-auto` so it doesn't compete with doors or the shortcut hint on the left.
+The notice matches the Baseboard's existing text style (`text-sm font-mono text-muted` — 12px via the theme.css `text-sm` override). It's pushed right via `ml-auto` so it doesn't compete with doors or the shortcut hint on the left.
 
 ### Threading
 
diff --git a/docs/specs/deploy.md b/docs/specs/deploy.md
index d2984852..8c5a4149 100644
--- a/docs/specs/deploy.md
+++ b/docs/specs/deploy.md
@@ -195,9 +195,9 @@ If you edit `CHANGELOG.md` manually outside `/release-notes` and want to preview
 | `OVSX_PAT` | `vscode-extension-publish` GitHub environment secret | OpenVSX publish |
 | `GITHUB_TOKEN` | GitHub Actions (automatic) | Artifact upload |
 | `APPLE_SIGNING_IDENTITY` | Local keychain | macOS codesign |
-| `APPLE_ID` | Local env / prompted | Notarization |
+| `APPLE_ID` | Hardcoded in `sign-and-deploy.sh` | Notarization |
 | `APPLE_SIGN_PASS` | Local env / prompted | Notarization password |
 | `APPLE_TEAM_ID` | Local env / hardcoded | Notarization |
 | `EV_SIGN_PIN` | Local env / prompted | Windows PIV signing |
-| `TAURI_SIGNING_PRIVATE_KEY` | Local env | Tauri update signatures |
+| `TAURI_SIGNING_PRIVATE_KEY` | Local env / prompted | Tauri update signatures |
 | `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Local env / prompted | Tauri update key password |
diff --git a/docs/specs/dor-browser.md b/docs/specs/dor-browser.md
index be4d66ec..d3cd4ee7 100644
--- a/docs/specs/dor-browser.md
+++ b/docs/specs/dor-browser.md
@@ -86,8 +86,8 @@ Surface lifetime owns backing resources:
 - Killing or swapping an agent-browser pane also disposes its surface controller
   (`disposeAgentBrowserSurfaceController`), releasing the connection, screenshot
   loop, CDP observer, timers, and screen registration. This is the immediate
-  per-surface teardown hook Future Work still lists generally; it exists today
-  for agent-browser surfaces.
+  per-surface teardown hook that [Future](#future) still lists generally; it
+  exists today for agent-browser surfaces.
 - Iframe proxy grants are currently reclaimed by the proxy idle sweep, not by an
   immediate per-surface teardown hook.
 
@@ -112,6 +112,10 @@ Header contract:
   HTML title is tooltip/secondary state.
 - Clicking the URL opens an inline editor. `normalizeNavUrl` keeps explicit
   schemes, uses `http://` for bare loopback hosts, and `https://` otherwise.
+  For an iframe-rendered pane a bare remote hostname therefore resolves to
+  `https://`, which the proxy cannot instrument — the pane shows the scheme
+  error with its `dor ab` hint. This is intended: remote sites are steered to
+  the agent-browser renderer rather than silently proxied over plain HTTP.
 - Back, forward, and reload are always enabled. Agent-browser sends native
   `back` / `forward` / `reload`; iframe uses parent-side history and re-resolves
   the proxy on reload/back/forward.
@@ -271,7 +275,9 @@ screenshot through the host's `agentBrowserScreenshot`, and draws that to canvas
 with latest-only backpressure. A capture whose bytes are identical to the last
 displayed frame (a static page the daemon keeps re-pulsing) costs no decode or
 draw; a re-attach bumps a draw generation so a fresh blank canvas still repaints.
-If the host cannot screenshot, it falls back to the stream frame path.
+A host without `agentBrowserScreenshot` renders only the placeholder — stream
+frame bytes are discarded by design (the connection reduces every frame message
+to a `frame-pulse`), so there is no frame-drawing fallback path.
 
 The high-rate `[ab-panel]`/`[agent-browser]` stream and screenshot console
 diagnostics sit behind the `dormouse.flags.abDebugLogs` localStorage flag, read
@@ -493,7 +499,17 @@ Source of truth: `lib/src/lib/platform/types.ts`,
   `standalone/src/tauri-adapter.ts`, `standalone/src-tauri/src/lib.rs`,
   `standalone/sidecar/main.js`.
 
-## Future Work
+## Maintainer checklist
+
+When changing browser-surface behavior:
+
+- `renderMode` is canonical. Never reintroduce `surfaceType: 'iframe' | 'agent-browser'` or `poppedOut` as stored state — extend the `resolveRenderMode` migration instead, and update the kind-mapping table in `docs/specs/glossary.md` if adding a render mode.
+- Every browser panel keeps dockview `renderer: 'always'` — moving iframe DOM reloads it, and moving the screencast canvas mid-click breaks click synthesis.
+- A new agent-browser subcommand must be added to `AGENT_BROWSER_ALLOWED_SUBCOMMANDS` (`lib/src/lib/platform/types.ts`); the host-side allowlist is the security boundary, not the CLI.
+- External-binary spawns go through `spawnAndCapture` (`dor-lib-common`), never raw `child_process` — see `docs/specs/dor-cli.md` → Spawning External Binaries.
+- New kill/swap/teardown paths must run `closeAgentBrowserSession` **and** dispose the surface controller (`disposeAgentBrowserSurfaceController`), and respect the closed-session mark so pop-out auto-revert cannot resurrect a killed session.
+
+## Future
 
 - Stable agent-browser profile/state persistence so pop-out preserves logins,
   cookies, tabs, DOM state, and scroll.
diff --git a/docs/specs/dor-cli.md b/docs/specs/dor-cli.md
index 308273d7..ee95e1a5 100644
--- a/docs/specs/dor-cli.md
+++ b/docs/specs/dor-cli.md
@@ -190,21 +190,18 @@ Invariants:
   `surface:1`, `pane:2`.
 - List output defaults to refs; commands that list handles accept
   `--id-format refs|uuids|both`.
-- Workspace/window refs are defined now that Dormouse supports multiple
-  Workspaces: `workspace:<n>` (and `workspace:<name>` when exactly one Workspace
-  matches) and `window:<n>` select a container. A `--workspace` target flag and
-  `dor workspace` management commands (list / new / rename / close / switch) are
-  the next handles to expose; like every other command they ship with their
-  snapshot-tested help and the control methods that back them, not ahead of them.
+- Reserved: `workspace:<n>` (and `workspace:<name>` when exactly one Workspace
+  matches) and `window:<n>` select a container. The ref grammar is reserved now
+  so surface/pane refs never collide with it; the flag and commands that consume
+  it are staged — see [Future](#future).
 
 ## Current Implemented Commands
 
 Implemented commands call private `surface.*` control methods. `surface.list`
 derives its response from current Dockview panels plus terminal state/activity
-snapshots where available, then returns `workspace:1` and `window:1`. Once
-`surface.list` is made Workspace-aware it tags each surface with the real
-`workspace:<n>` / `window:<n>` membership defined above; until then it reports the
-single active Workspace.
+snapshots where available, then returns `workspace:1` and `window:1` — it
+reports the single active Workspace (Workspace-aware tagging is staged; see
+[Future](#future)).
 
 Command tails captured after `--` are sent as raw argv arrays (`command:
 string[]`); the host — not `dor` — quotes them for the target shell. `dor`
@@ -240,3 +237,16 @@ from `command-detail`.
   unified `browser` surface, see [dor-browser.md](dor-browser.md)
 - `dor list-panes` [impl](../../dor/src/commands/list-panes.ts) [docs](../../dor/test/snapshots/help/list-panes.md)
 - `dor list-pane-surfaces` [impl](../../dor/src/commands/list-pane-surfaces.ts) [docs](../../dor/test/snapshots/help/list-pane-surfaces.md)
+
+## Future
+
+- **Workspace handles and commands** — a `--workspace` target flag and `dor
+  workspace` management commands (list / new / rename / close / switch)
+  consuming the reserved `workspace:<n|name>` / `window:<n>` ref grammar in the
+  handle model above. Like every other command they ship with their
+  snapshot-tested help and the control methods that back them, not ahead of
+  them. Staged with the workspaces rollout (`docs/specs/layout.md` `## Future`,
+  workspaces-rollout).
+- **Workspace-aware `surface.list`** — tags each surface with its real
+  `workspace:<n>` / `window:<n>` membership instead of reporting the single
+  active Workspace.
diff --git a/docs/specs/glossary.md b/docs/specs/glossary.md
index 0f90fadb..436aa023 100644
--- a/docs/specs/glossary.md
+++ b/docs/specs/glossary.md
@@ -11,7 +11,7 @@ A **Surface** is the durable occupant of a Pane — what a user thinks of as "th
 
 A **Session**'s state lives on six orthogonal axes — change one without touching the others. A caller holding a `SessionId` can reason about each axis independently. Unless a passage says "Surface" or "browser Surface," it is describing a Session.
 
-The **Liskov contract**: a Session is substitutable across most operations regardless of which states it currently occupies. `kill` and `rename` work universally. State-gated operations (`write`, `focus`) document their preconditions in glossary terms rather than failing silently.
+The **Liskov contract**: a Session is substitutable across most operations regardless of which states it currently occupies. `kill` and `rename` work universally. State-gated operations (`write`, `focus`) have their preconditions documented in glossary terms (see [Liskov contract](#liskov-contract)).
 
 ## Panes and Surfaces
 
@@ -31,6 +31,17 @@ Today every Pane holds exactly one Surface, but the model reserves multiple Surf
 | `terminal` | — | a PTY + xterm.js instance — i.e. a **Session** |
 | `browser` | `iframe`, `ab-screencast`, `ab-popout` | an iframe proxy grant, or an agent-browser daemon session (`docs/specs/dor-browser.md`) |
 
+Three related enums name a Surface's kind at different layers. This table is the canonical mapping:
+
+| Surface | Persisted `surfaceType` (`docs/specs/transport.md`) | `renderMode` (`docs/specs/dor-browser.md`) | CLI `SurfaceType` (`dor`, legacy/derived) |
+|---|---|---|---|
+| terminal Session | `'terminal'` (the default, omitted from the row) | — | `terminal` |
+| browser, iframe renderer | `'browser'` | `iframe` | `iframe` |
+| browser, screencast renderer | `'browser'` | `ab-screencast` | `agent-browser` |
+| browser, popped-out renderer | `'browser'` | `ab-popout` | `agent-browser` |
+
+For browser Surfaces `renderMode` is canonical; the CLI column is derived from it for backwards-compatible `dor` output and is never stored.
+
 A **Session** runs the full six-axis model below. A **browser Surface** participates only where a web view meaningfully can:
 
 | Axis | Terminal Surface (Session) | Browser Surface |
@@ -78,12 +89,18 @@ The union is **display-only**: it is derived from member Activity, never enters
 
 ### Implementation status
 
-This vocabulary is the target model; it lands in stages, so parts of it are specified ahead of the code. As of this spec:
+This vocabulary is the target model, so parts of it are specified ahead of the code. The Pane / Surface model, surface kinds, and their persistence are live. The Workspace / Window containers are implemented but dormant behind the `dormouse.flags.workspaces` flag (off by default — the app runs one implicit Workspace); the standalone workspace strip and real `switchWorkspace` mounting are not built. The rollout ledger — what remains and in what order — lives in `docs/specs/layout.md` `## Future` (**Scope: workspaces-rollout**); this glossary does not track it.
+
+## Modes
+
+A Wall is always in exactly one input mode. `docs/specs/layout.md` owns the switching gestures and per-mode behavior; these are the canonical names:
 
-- **Implemented, live (stage 2a)** — **Pane** and **Surface** as first-class concepts, the terminal/browser surface kinds and their per-axis participation, `surfaceType` in the persisted snapshot, and the restore/resume handling that keeps browser Surfaces (no stray PTY, saved layout preserved; `docs/specs/transport.md`). A browser Surface's user-set `todo` round-trips to the activity store live and persists across restart — it is saved in the pane's `alert` blob and re-primed on cold restore and resume (`restoreBrowserSurfaceTodo`).
-- **Implemented but dormant behind the `dormouse.flags.workspaces` flag (stage 2b)** — the **Workspace** and **Window** containers: `PersistedWorkspace` / `PersistedWindow` and the migration of a pre-workspace snapshot to a single "Workspace 1" (`readPersistedWindow`); the standalone persisting a `PersistedWindow` (the active Workspace's session wrapped, other Workspaces preserved — `window-persistence.ts`, wired into the standalone adapters); the in-memory workspace model and its container verbs (`createWorkspace` / `closeWorkspace` / `renameWorkspace` / `setActiveWorkspace` in `workspace-store.ts`); and the union projection (`computeWorkspaceUnion`). The flag is **off by default**, so the app persists a bare `PersistedSession` and runs exactly one implicit Workspace — behavior is byte-identical to stage 2a.
-- **Implemented for VS Code chrome** — each webview's union is reflected onto native chrome host-side: the editor-tab title gains a ` 🔔` / ` [TODO]` suffix and the bottom-panel view shows a presence badge (`docs/specs/vscode.md`). Terminal ring/TODO only (browser-surface TODO stays webview-local). Currently always-on in VS Code (the host can't read the localStorage flag).
-- **Not yet implemented (stages 3–4)** — the standalone workspace **strip** and its union **surfacing** (strip indicators); the actual Wall **mount/unmount on `switchWorkspace`** (today the model switches the active id but does not yet re-render the Wall); and lifting the cap so a user can create more than one Workspace. The switching UI is stage 3, real multi-Workspace activation is stage 4. Strip/surfacing passages in the standalone-facing specs are forward-looking until then.
+| Mode | Meaning |
+|---|---|
+| **passthrough** | Keyboard input routes to the selected Session's terminal. Only copy/paste and the mode-switch gesture are intercepted. |
+| **command** | Keyboard input drives navigation and layout commands; the Session receives nothing. |
+
+Do not introduce aliases — "terminal mode", "normal mode", and "navigation mode" all mean one of the two names above.
 
 ## Layers
 
@@ -187,7 +204,7 @@ A system verb is a lifecycle transition driven by the runtime.
 
 ## Liskov contract
 
-Every Registry API declares its layer preconditions. Calls against a gated state fail with a typed error rather than silently no-op.
+Every Registry API has layer preconditions, declared here:
 
 | Category | Valid when | Examples |
 |---|---|---|
@@ -196,7 +213,7 @@ Every Registry API declares its layer preconditions. Calls against a gated state
 | **Process-gated** | `Process = Live` | `write`, `resize` |
 | **Registry-gated** | `Registry = Mounted` | `refit` |
 
-A caller holding a `SessionId` can issue universal operations without branching. Gated operations are explicit: the caller checks the relevant layer first or catches the typed error.
+A caller holding a `SessionId` can issue universal operations without branching. Gated operations are explicit: the caller checks the relevant layer first. Uniform typed-error enforcement of these preconditions is staged — see [Future](#future).
 
 ## Invariants
 
@@ -225,6 +242,9 @@ Use glossary names instead of these. The left column retains a meaning only wher
 | **terminal** | Keeps its meaning for the `xterm.Terminal` instance. Prose meaning "the whole thing" is **Session** (a terminal Surface). |
 | **surface** | A glossary term, not retired: the durable occupant of a Pane (a terminal Session or a browser Surface). Use **Session** only for the terminal kind; use **Surface** when a statement holds for both. |
 | **panel / pane** | Prefer **pane** for the layout slot. Use "panel" only when quoting dockview's own API (`api.panels`, `addPanel`). |
+| **tether** | Remote-control term only: a display showing "tethering to \<device\>" has ceded terminal size authority to a remote viewer (`docs/specs/remote-api.md`). Not a layout term — do not use it for Pane/Door relationships. |
+
+Remote-only vocabulary (**Viewer**, the wire-level `DirectoryEntry` projection) is defined in `docs/specs/remote-api.md` § Terminology.
 
 ## Naming conventions
 
@@ -233,5 +253,9 @@ Use glossary names instead of these. The left column retains a meaning only wher
 - Event kind strings match the verb: `'minimizeChange'`, not `'detachChange'`.
 - A persisted type is `Persisted<Shape>` where `<Shape>` is the glossary noun (`PersistedPane`, `PersistedDoor`, `PersistedWorkspace`, `PersistedWindow`).
 - A handle type is `<Layer>State` (`ActivityState`, not `SessionUiState`).
-- Surface kinds are lowercase strings: the CLI `SurfaceType` is `'terminal' | 'iframe' | 'agent-browser'`; the component-level split is `'terminal' | 'browser'`. A browser Surface records its kind via `surfaceType` on its persisted per-pane record (`docs/specs/transport.md`).
+- Surface kinds are lowercase strings; the kind-enum mapping table in [Panes and Surfaces](#panes-and-surfaces) is canonical for how the persisted `surfaceType`, `renderMode`, and CLI `SurfaceType` relate.
 - Container names are `PascalCase` nouns (`Workspace`, `Window`); their ids are `WorkspaceId` and `WindowId`. Container verbs keep the container as a suffix (`createWorkspace`, `switchWorkspace`) to stay distinct from the layer-agnostic Session `rename`.
+
+## Future
+
+- **Typed precondition errors.** The Liskov contract's enforcement mechanism: a Registry call against a gated state (e.g. `write` on a non-`Live` Process) fails with a typed error naming the violated precondition, instead of relying on each call site's ad-hoc handling.
diff --git a/docs/specs/layout.md b/docs/specs/layout.md
index b4d850b3..6f5b693c 100644
--- a/docs/specs/layout.md
+++ b/docs/specs/layout.md
@@ -20,7 +20,7 @@ non-terminal browser surfaces, the backing browser session remains alive while
 the visible viewer resources are released: no canvas, screencast WebSocket,
 screenshot loop, or input forwarding runs while the surface is a Door.
 
-A **Workspace** is the named group of Surfaces rendered by a single **Wall**, together with their layout (see `docs/specs/glossary.md`). A Window may hold several Workspaces. This spec covers how Workspaces are presented and switched in the standalone app — the tab strip and the one-Wall-per-Workspace mounting below. VS Code maps each Workspace to its own webview instead; see `docs/specs/vscode.md`.
+A **Workspace** is the named group of Surfaces rendered by a single **Wall**, together with their layout (see `docs/specs/glossary.md`). A Window may hold several Workspaces. This spec owns the standalone Workspace presentation; the strip UI and real switching are staged in [Future](#future) (**Scope: workspaces-rollout**). VS Code maps each Workspace to its own webview instead; see `docs/specs/vscode.md`.
 
 ## Shell layout
 
@@ -116,9 +116,9 @@ The mouse-override icon only appears when the inside program has requested mouse
 
 ## Baseboard
 
-Below the content area is the baseboard (`h-7`, 28px). It is visible by default and has no top divider. The dockview area ends 2px above it, leaving a narrow theme-colored gap that keeps rounded pane corners distinct from the baseboard. Its horizontal padding matches the Dockview wrapper's 6px inset, so doors align with the panes above. When empty, it shows keyboard shortcut hints when there are no doors and the container is wider than 350px (currently: `LCmd → RCmd to enter command mode`).
+Below the content area is the baseboard (`h-7`, 28px). It is visible by default and has no top divider. The dockview area ends 2px above it, leaving a narrow theme-colored gap that keeps rounded pane corners distinct from the baseboard. Its horizontal padding matches the Dockview wrapper's 6px inset, so doors align with the panes above. When empty, it shows keyboard shortcut hints when there are no doors and the container is wider than 350px — platform-aware: `LCmd → RCmd to enter command mode` on macOS, `LShift → RShift to enter command mode` elsewhere (`Baseboard.tsx`).
 
-`Wall` accepts `showBaseboard={false}` for constrained embedders such as the website mobile Tether prototype, where a separate bottom navigation owns the area below the terminal and door workflows are outside the prototype scope. The main app shell keeps the default `showBaseboard=true`.
+`Wall` accepts `showBaseboard={false}` for constrained embedders such as the website's mobile Pocket playground, where a separate bottom navigation owns the area below the terminal and door workflows are outside the prototype scope. The main app shell keeps the default `showBaseboard=true`.
 
 When a session is minimized, it becomes a **door** on the baseboard. The door displays the same derived terminal label as the pane header, a TODO badge (if set), and an alert bell icon with activity dot. It uses the bottom edge of the window as its bottom border, with left, top, and right borders using the shared terminal top radius from `lib/src/components/design.tsx` — resembling a mouse hole and matching pane rounding. Door dimensions: `min-w-[68px] max-w-[220px] h-6`.
 
@@ -126,7 +126,7 @@ When a session is minimized, it becomes a **door** on the baseboard. The door di
 
 - **Clicking a door** (in any mode): restores the session into the content area as a pane and enters passthrough mode. The terminal gets focus immediately.
 - **Enter** on a door (command mode): same as clicking — restores and enters passthrough mode.
-- **d** on a door (command mode): restores the session into a pane but stays in command mode. This is the inverse of pressing `d` on a pane (which minimizes it), making `d` a toggle.
+- **m** or **d** on a door (command mode): restores the session into a pane but stays in command mode. This is the inverse of pressing `m`/`d` on a pane (which minimizes it), making them toggles.
 - **x** on a door (command mode): restores the session into a pane, then immediately shows the kill confirmation.
 - **Arrow keys** can navigate to doors from panes (see Navigation).
 
@@ -148,26 +148,12 @@ Extreme case: a single door with a very long title, with more doors on both side
 ## Workspaces
 
 > See `docs/specs/glossary.md` for the Workspace / Window containers and `docs/specs/alert.md` for the union status. VS Code's per-webview mapping is in `docs/specs/vscode.md`.
->
-> **Partially implemented.** The container and model exist behind the `dormouse.flags.workspaces` flag (stage 2b, dormant): the standalone persists a `PersistedWindow` and the workspace model holds the list + active id (`docs/specs/transport.md`, glossary Implementation status). Still **not built**: the **strip UI** below (stage 3) and the actual Wall **mount/unmount when switching** (stage 4) — today `setActiveWorkspace` changes the active id in the model but does not re-render the Wall. The app runs one implicit Workspace with the flag off (the default).
 
 A **Workspace** is one Wall's worth of Surfaces (terminal Sessions and browser surfaces) plus its layout, with a user-facing name. The standalone Window hosts several Workspaces but mounts only one — the **active** Workspace — at a time. Each Workspace owns its own Content (dockview layout) and Baseboard (doors).
 
-### Workspace strip (standalone)
+What exists today lives behind the `dormouse.flags.workspaces` flag (`WORKSPACES_FLAG_KEY` in `lib/src/lib/feature-flags.ts`, **off by default**): the in-memory workspace model and its container verbs (`createWorkspace` / `closeWorkspace` / `renameWorkspace` / `setActiveWorkspace` in `lib/src/lib/workspace-store.ts`), the union projection (`computeWorkspaceUnion` in `lib/src/lib/workspace-union.ts`), and Window persistence (`PersistedWindow`, `docs/specs/transport.md`). `setActiveWorkspace` changes the active id in the model but does not yet re-render the Wall, and the single-Workspace cap is still in place. With the flag off, the app persists a bare `PersistedSession` and runs exactly one implicit Workspace — byte-identical to pre-workspace behavior.
 
-The standalone app bar (`standalone/src/AppBar.tsx`) carries a horizontal **workspace strip**: one tab per Workspace, living in the app bar's draggable region at the top of the window. Each tab shows the Workspace `name` and, for **inactive** Workspaces, the union `ringing` bell and `todo` pill from `docs/specs/alert.md`, reusing the Door indicator vocabulary. The **active** Workspace's tab shows no union indicator: its alerts are already visible on its own panes and doors. Exact tab visuals are settled in the Storybook UI pass.
-
-### Switching
-
-Activating another Workspace (`switchWorkspace`) mounts the target Workspace's Surfaces into the Wall — rebuilding its dockview layout and reattaching its doors — and unmounts the previously active Workspace's Surfaces. For a terminal Surface this reuses the `mount` / `unmount` registry ops: the Registry entry and PTY survive `unmount`, so Process stays `Live`. A browser surface's backing agent-browser session or proxy grant likewise survives while its viewer resources are released. Because a terminal's Activity keeps flowing while unmounted, an inactive Workspace's tab can begin ringing or showing TODO while the user is elsewhere. Mounting must not fire a fresh ring (glossary I8, mirroring the minimize/reattach rule I3).
-
-### Lifecycle
-
-- **Create** (`createWorkspace`): adds a new Workspace, gives it a default name (`Workspace N`), makes it active, and spawns a single fresh pane — matching the empty-state behavior in Session persistence below.
-- **Close** (`closeWorkspace`): `kill`s each member Surface and removes the Workspace. Closing a Workspace that contains touched Surfaces confirms first (reusing the kill-confirm vocabulary); the exact confirmation surface is settled in the Storybook UI pass. The last remaining Workspace cannot be closed — there is always one active Workspace, just as there is always one visible pane (corner case #10).
-- **Rename** (`renameWorkspace`): edits the Workspace `name` only. It does not touch any Surface title or the per-pane inline rename.
-
-Concrete switch/create/close/rename keyboard shortcuts are chosen alongside the Storybook UI pass. Command mode is the natural home for them, following the tmux *window* bindings the rest of the keymap mirrors (a Dormouse Workspace is the analogue of a tmux window).
+The strip UI, real switching, and lifecycle UX are staged in [Future](#future) — this spec's `## Future` is the single rollout ledger for the feature; other specs link here.
 
 ## Modes
 
@@ -177,7 +163,7 @@ Wall starts in `command` mode by default. Embedders may pass `initialMode="passt
 - All keyboard input routes to the active session's xterm.js instance
 - Only the mode-exit gesture (LCmd → RCmd, or LShift → RShift) is intercepted
 - In the VS Code host, selected workbench chords are mirrored: xterm still processes the key, and Dormouse also asks the extension host to run the matching VS Code command. See [the VS Code host spec](vscode.md) for the allowlist.
-- Selection overlay shows 2px solid border with glow
+- Selection overlay shows a 1px solid border
 - Terminal has DOM focus
 
 ### Command mode
@@ -197,6 +183,7 @@ Wall starts in `command` mode by default. Embedders may pass `initialMode="passt
 - Left Cmd keydown, then Right Cmd keydown within 500ms — or the same left-then-right gesture with Shift (Left Shift, then Right Shift within 500ms)
 - Detected via capture-phase `keydown` listener on `e.key === 'Meta'` (or `e.key === 'Shift'`) and `e.location` (1 = left, 2 = right). The Meta and Shift tracks are independent, so a Left Cmd followed by a Right Shift does not trigger.
 - Works even when xterm has DOM focus because listener uses capture phase
+- On keyboards without a right Meta key (common on Windows/Linux laptops), the Shift track is the available gesture; both tracks are always active.
 
 ## Keyboard shortcuts (command mode)
 
@@ -211,7 +198,7 @@ All handled in a single capture-phase `keydown` listener on `window`. Every hand
 | `Enter` | Enter passthrough mode | Restore session + enter passthrough |
 | `,` | Inline rename | — |
 | `x` / `k` | Kill with confirmation | Restore session + kill confirmation |
-| `d` | Minimize to door | Restore session (stay in command) |
+| `m` / `d` | Minimize to door | Restore session (stay in command) |
 | `z` | Toggle maximize/restore | — |
 | `t` | Toggle TODO flag | — |
 | `a` | Dismiss or toggle alert | — |
@@ -224,14 +211,14 @@ When a split is initiated from an existing pane (via `|`/`%`/`-`/`"`, the header
 
 Pressing `x` (or clicking the kill button) enters command mode and shows a pane-centered semi-transparent overlay (`KillConfirmOverlay` → `KillConfirmModal`) with a random lowercase letter (a-z, excluding x). Typing that letter confirms the kill (destroys session, removes pane). Cancel with Escape key, clicking the `[ESC] to cancel` button, or clicking another panel. Any other key triggers a shake animation (400ms `shake-x` keyframe) then auto-dismisses the confirmation.
 
-Untouched sessions skip this confirmation. A newly spawned shell starts `untouched: true`; the first user-originated PTY input flips it to false. Inputs that count include printable keys, Enter, control keys, keyboard CSI such as arrows/history, paste, and file-drop path insertion. Replay-time terminal reports, synthetic terminal reports, and stripped mouse-report-only input do not count. Killing an untouched pane runs the normal kill animation/dispose path immediately. Killing an untouched door first reattaches it only far enough to reuse the same pane removal path, then kills it without showing the confirmation overlay.
+Untouched sessions skip this confirmation. A newly spawned shell starts `untouched: true`; the first user-originated PTY input flips it to false. Inputs that count include printable keys, Enter, control keys, keyboard CSI such as arrows/history, paste, and file-drop path insertion. Replay-shaped terminal reports and stripped mouse-report-only input do not count (the untouched gate checks `inputIsReplayTerminalReport`; the broader synthetic-report check gates input recording and alert attention, not this flag). Killing an untouched pane runs the normal kill animation/dispose path immediately. Killing an untouched door first reattaches it only far enough to reuse the same pane removal path, then kills it without showing the confirmation overlay.
 
 ## Selection overlay
 
-A fixed-positioned element rendered on top of dockview. Covers the active element's area inflated by 3px (half the 6px gap) for panes, or 2px for doors.
+A fixed-positioned element rendered on top of dockview. Covers the active element's area inflated by 3px (half the 6px gap) for panes; doors are not inflated.
 
 - A pane or door can be **active** or **inactive**. Only one element is active at a time.
-- **Passthrough:** `border: 2px solid ${color}` + `box-shadow: 0 0 15px color-mix(in srgb, ${color} 30%, transparent)`
+- **Passthrough:** `border: 1px solid ${color}` — no glow
 - **Command:** animated SVG marching-ants border — rounded rectangle path with `stroke-dasharray` animation (10px segment, 60% dash / 40% gap, 0.4s cycle, 2px stroke)
 - Border radius: shared terminal radius from `lib/src/components/design.tsx`: full `0.5rem` for panes, `0.5rem 0.5rem 0 0` for doors
 - Color from CSS custom property `--mt-selection-terminal`
@@ -304,7 +291,7 @@ The name `<span>` is replaced by an `<input>` with:
 - `stopPropagation` on `mousedown`/`click`/`keydown` to prevent panel click or drag
 - All command-mode shortcuts are bypassed while renaming
 
-User-pin titles must not start with `<idle>` (the sentinel that prefixes the auto-generated header for finished panes), and empty values are also rejected. `<unnamed>` is the default panel placeholder but is otherwise allowed as a deliberate user pin. When the user submits a rejected value, the input still closes (so it is not a blocking dialog) and a small auto-dismissing warning popover anchored under the input names the offending value. The popover dismisses on the next pointerdown, scroll, resize, `Escape`, or after 3s.
+Submitted values are rejected when empty or when they fail the `setTerminalUserTitle` validation that also guards title seeding — no titles starting with the `<idle>` sentinel (`docs/specs/transport.md`). `<unnamed>` is the default panel placeholder but is otherwise allowed as a deliberate user pin. When the user submits a rejected value, the input still closes (so it is not a blocking dialog) and a small auto-dismissing warning popover anchored under the input names the offending value. The popover dismisses on the next pointerdown, scroll, resize, `Escape`, or after 3s.
 
 ## Session lifecycle and terminal registry
 
@@ -383,7 +370,7 @@ Case handling is purely rect-based (measure before and after removal), so 2-pane
 
 ### Auto-spawn delay
 
-When `onDidRemovePanel` triggers the "always keep one pane visible" auto-spawn (see corner case #10), the `api.addPanel` call is deferred by 440ms. This lets the outgoing animation (kill ghost crush, or minimize's selection-overlay slide to the door) complete before the replacement's reveal starts — they play sequentially in the same screen region instead of fighting each other. The deferred spawn re-checks `totalPanels` at fire time and becomes a no-op if anything repopulated the pane area during the delay (e.g. a door reattach). If it does create a replacement pane, that pane spawns with the current default shell selection, matching manual splits and the standalone `[+]` action.
+When `onDidRemovePanel` triggers the "always keep one pane visible" auto-spawn (see corner case #10), the `api.addPanel` call is deferred by 440ms **for the minimize path** — letting the selection-overlay slide to the door finish before the replacement's reveal starts. The kill path uses no extra delay (0ms): kill sequencing is already handled inside `orchestrateKill`, which removes the panel only after the fade's `animationend`. Reduced-motion users also get 0ms. The deferred spawn re-checks `totalPanels` at fire time and becomes a no-op if anything repopulated the pane area during the delay (e.g. a door reattach). If it does create a replacement pane, that pane spawns with the current default shell selection, matching manual splits and the standalone `[+]` action.
 
 The deferred spawn also only calls `selectPane` if selection is null. The kill handler clears selection to null, so the new pane takes focus. The minimize flow sets selection to the just-created door; preserving that door focus across the delay is the point.
 
@@ -398,7 +385,7 @@ The deferred spawn also only calls `selectPane` if selection is null. The kill h
 7. **Asymmetric back-navigation**: breadcrumb tracks last direction + origin for opposite-direction return.
 8. **Center drop merges panels**: intercepted at group-level `model.onWillDrop` and converted to a swap.
 9. **Group drag has null panelId**: falls back to `api.getGroup(groupId).activePanel.id`.
-10. **Auto-spawn on empty**: `onDidRemovePanel` creates a new session whenever the last visible pane is removed, whether or not doors exist — there is always a pane visible. The `addPanel` call is delayed 440ms (see "Auto-spawn delay" under Animations) so the outgoing kill/minimize animation finishes first.
+10. **Auto-spawn on empty**: `onDidRemovePanel` creates a new session whenever the last visible pane is removed, whether or not doors exist — there is always a pane visible. The `addPanel` call is delayed 440ms on the minimize path (see "Auto-spawn delay" under Animations); the kill path is sequenced by `orchestrateKill` instead.
 11. **Door focus survives auto-spawn**: `api.addPanel` auto-activates the new panel, firing `onDidActivePanelChange`. When the current selection is a door (e.g., just-minimized last pane), that listener must not flip `selectedId` to the new pane — otherwise `selectedType === 'door'` + `selectedId === newPaneId` desyncs and the door loses its highlight while the `WorkspaceSelectionOverlay` is stuck on the stale door rect. The listener early-returns when `selectedType === 'door'`.
 
 ## Files
@@ -440,3 +427,34 @@ The deferred spawn also only calls `selectPane` if selection is null. The kill h
 | `lib/src/lib/resume-patterns.ts` | Detects resumable commands (`claude --resume`, etc.) in scrollback |
 | `lib/src/index.css` | Dockview theme overrides — separator/sash/border removal, background flattening |
 | `lib/src/theme.css` | Two-layer VSCode theme token system (`@theme --color-*` → `--vscode-*`) and Tailwind v4 `@theme` integration |
+
+## Maintainer checklist
+
+When changing layout behavior:
+
+- Changing a command-mode binding or the mode-switch gesture: update the shortcut table here **and** `docs/specs/shortcuts.md` in the same edit.
+- Pane-header changes: this spec owns placement and sizing only. Bell/TODO behavior and visual states belong to `docs/specs/alert.md`; the mouse-override icon and banner to `docs/specs/mouse-and-clipboard.md`; the derived label to `docs/specs/terminal-state.md`.
+- Persisted-shape changes (`PersistedPane` / `PersistedDoor` / layout blobs) belong to `docs/specs/transport.md` — add the migration note there.
+- New pane chrome uses tokens from `lib/src/components/design.tsx` (see AGENTS.md Design); never raw color classes.
+- Pane animations stay on `clip-path`, not `transform`, so `getBoundingClientRect` remains accurate for the selection overlay; respect reduced-motion.
+- Anything workspace-strip or switching related stays under `## Future` (workspaces-rollout) until built.
+
+## Future
+
+**Scope: workspaces-rollout** — the remaining stages of the multi-Workspace feature. The model, container verbs, persistence, and union projection are implemented, dormant behind `dormouse.flags.workspaces` (see [Workspaces](#workspaces) above; persisted containers in `docs/specs/transport.md`, union projection in `docs/specs/alert.md`). This ledger is the single home for what remains; other specs link here rather than restating it.
+
+### Stage 3 — workspace strip and switching UI (standalone)
+
+The standalone app bar (`standalone/src/AppBar.tsx`) grows a horizontal **workspace strip**: one tab per Workspace, living in the app bar's draggable region at the top of the window. Each tab shows the Workspace `name` and, for **inactive** Workspaces, the union `ringing` bell and `todo` pill from `docs/specs/alert.md`, reusing the Door indicator vocabulary. The **active** Workspace's tab shows no union indicator: its alerts are already visible on its own panes and doors. Exact tab visuals are settled in the Storybook UI pass.
+
+Concrete switch/create/close/rename keyboard shortcuts are chosen alongside the Storybook UI pass. Command mode is the natural home for them, following the tmux *window* bindings the rest of the keymap mirrors (a Dormouse Workspace is the analogue of a tmux window). `docs/specs/shortcuts.md` lists them once bound.
+
+### Stage 4 — real switching and multi-Workspace activation
+
+Activating another Workspace (`switchWorkspace`) mounts the target Workspace's Surfaces into the Wall — rebuilding its dockview layout and reattaching its doors — and unmounts the previously active Workspace's Surfaces. For a terminal Surface this reuses the `mount` / `unmount` registry ops: the Registry entry and PTY survive `unmount`, so Process stays `Live`. A browser surface's backing agent-browser session or proxy grant likewise survives while its viewer resources are released. Because a terminal's Activity keeps flowing while unmounted, an inactive Workspace's tab can begin ringing or showing TODO while the user is elsewhere. Mounting must not fire a fresh ring (glossary I8, mirroring the minimize/reattach rule I3).
+
+Stage 4 also lifts the single-Workspace cap and wires the lifecycle UX:
+
+- **Create** (`createWorkspace`): adds a new Workspace, gives it a default name (`Workspace N`), makes it active, and spawns a single fresh pane — matching the empty-state behavior in Session persistence above.
+- **Close** (`closeWorkspace`): `kill`s each member Surface and removes the Workspace. Closing a Workspace that contains touched Surfaces confirms first (reusing the kill-confirm vocabulary); the exact confirmation surface is settled in the Storybook UI pass. The last remaining Workspace cannot be closed — there is always one active Workspace, just as there is always one visible pane (corner case #10).
+- **Rename** (`renameWorkspace`): edits the Workspace `name` only. It does not touch any Surface title or the per-pane inline rename.
diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-terminal-ui.md
similarity index 70%
rename from docs/specs/mobile-ui.md
rename to docs/specs/mobile-terminal-ui.md
index f25d62aa..3ff8129a 100644
--- a/docs/specs/mobile-ui.md
+++ b/docs/specs/mobile-terminal-ui.md
@@ -1,61 +1,29 @@
-# Mobile Terminal Website Prototype Spec
+# Mobile Terminal UI
 
 > See `docs/specs/glossary.md` for Session / Pane / Door vocabulary. This spec uses it throughout.
 
-## 1. Overview
-
-This document specifies the `/playground/pocket` mobile terminal prototype.
-
-The prototype tests one core idea:
+The mobile terminal composition: `MobileTerminalUi` (the wrapper owning touch
+modes, input modes, and the keyboard reserve) around `MobileWall` (one visible
+terminal Session at a time, with session switching). The core idea:
 
 ```text
 Stable terminal viewport + mobile session viewport + explicit touch mode + explicit input mode.
 ```
 
-The app should feel like a lightweight mobile terminal playground. It does not
-need remote sessions, SSH, user accounts, or production infrastructure.
-
-The website `/playground/pocket` prototype exposes a small floating theme
-switcher above the terminal. It uses the shared Dormouse `ThemePicker`. On
-desktop, `/playground/pocket` shows a share-to-phone page instead of the
-interactive terminal. The `/pocket` route temporarily redirects to
-`/playground/pocket`; this is a launch-state redirect, not the future real
-tethering environment.
-
-`/playground/pocket` uses the same fake playground terminal stack as
-`/playground/desktop`: `PlaygroundShellRegistry` attaches a `TutorialShell` to
-every spawned pane, and the same fake commands dispatch to browser-side runners.
-The first mobile session auto-runs `tut` with the Pocket tutorial profile; a
-second `changelog` session auto-runs `changelog` for the tutorial's copy/paste
-coverage.
-
-## 2. Prototype Goals
-
-Primary goals:
-
-* Keep the terminal viewport stable when the native phone keyboard opens or closes.
-* Let the user explicitly choose what terminal touches mean.
-* Let the user explicitly choose what appears in the stable reserve area.
-* Show one terminal session at a time on mobile, with session switching available from the reserve controls.
-* Test normal mobile text entry using the native phone keyboard.
-* Provide enough terminal behavior to evaluate typing, Enter, Backspace, arrows, Escape, Tab, and app interruption.
-* Keep the implementation small and easy to iterate on.
-
-Non-goals:
-
-* Remote shell support.
-* SSH support.
-* WebSocket transport.
-* User accounts.
-* Session persistence.
-* Command history storage.
-* A real draft/scratchpad workflow.
-* Mobile split-pane layout.
-* Multi-touch gestures.
-* Production security hardening.
-* Full accessibility implementation.
+Touch modes make pane touches explicit; input modes make the reserve area
+explicit. Desktop `Wall` remains the tiling workspace layout; mobile does not
+expose split-pane layout or multiple Workspaces.
 
-## 3. Core Layout
+Three consumers compose these components today: the website Pocket playground
+(`FakePtyAdapter`; page wiring in `docs/specs/tutorial.md`), the real Pocket
+app (`RemotePtyAdapter`; `docs/specs/pocket-app.md`), and Storybook stories.
+
+> History: this component was designed and validated through the website
+> `/playground/pocket` prototype (originally specced as `mobile-ui.md`; see git
+> history). The prototype's goals and success criteria are retired; the
+> page-level wiring lives in `docs/specs/tutorial.md`.
+
+## Core layout
 
 The mobile UI is split into fixed and flexible regions:
 
@@ -77,26 +45,24 @@ The mobile UI is split into fixed and flexible regions:
 ```
 
 The mobile session header and pane content come from `MobileWall`, a mobile
-composition that displays one active terminal session at a time. Desktop `Wall`
-remains the tiling workspace layout; mobile does not expose split-pane layout or
-multiple Workspaces. The
-mobile wrapper owns the two selectors and the fixed-height reserve. The selector
+composition that displays one active terminal session at a time. The mobile
+wrapper owns the two selectors and the fixed-height reserve. The selector
 block should use one divider between the Touch and Input rows, with no divider
-above Touch and no divider below Input. The mobile session header should not use
-the desktop terminal title corner radius; it is a flush mobile bar. The alert
-bell sits immediately after the title before secondary title detail. The mobile
-header keeps a minimize button, and in the `/playground/pocket` prototype that
-action opens the Sessions reserve instead of creating a desktop Door. The Touch
-row and its selector tray should sit on `terminal-bg` so they read as part of
-the terminal surface above. The Input row and reserve area should sit on
-`header-inactive-bg` with `header-inactive-fg`, so the lower input controls are
-distinct from the terminal while still following the selected theme.
+above Touch and no divider below Input. The mobile session header should not
+use the desktop terminal title corner radius; it is a flush mobile bar. The
+alert bell sits immediately after the title before secondary title detail. The
+mobile header keeps a minimize button; in the website Pocket playground that
+action opens the Sessions reserve instead of creating a desktop Door. The
+Touch row and its selector tray should sit on `terminal-bg` so they read as
+part of the terminal surface above. The Input row and reserve area should sit
+on `header-inactive-bg` with `header-inactive-fg`, so the lower input controls
+are distinct from the terminal while still following the selected theme.
 
 The root height must not be recalculated from `window.visualViewport` on every
-keyboard resize. The reserve area is intentionally stable so the terminal region
-does not bounce while the OS keyboard animates.
+keyboard resize. The reserve area is intentionally stable so the terminal
+region does not bounce while the OS keyboard animates.
 
-## 4. Touch Mode Selector
+## Touch mode selector
 
 The touch selector controls what happens when the user touches the pane content
 area. It is always visible between the terminal content and the input mode
@@ -104,7 +70,7 @@ selector.
 
 The selector must be self-labeling through segmented buttons that include both
 an icon and a short mode label. Icon-only touch controls are too hard to
-discover in this prototype.
+discover.
 
 Source of truth: `TOUCH_MODES` in `lib/src/components/MobileTerminalUi.tsx`
 defines touch-mode button labels and icons.
@@ -140,19 +106,21 @@ touch-scroll fallback.
 Select mode must route touch and pen drags through the shared terminal
 mouse-selection router, not through a mobile-only selection implementation, so
 selection geometry, smart token extension, copy popups, rewrapped copy, and TUI
-mouse-capture override rules match desktop behavior.
+mouse-capture override rules match desktop behavior
+(`docs/specs/mouse-and-clipboard.md`).
 
-Gesture mode intentionally consumes primary mouse/trackpad clicks in addition to
-touch input. This keeps the `/playground/pocket` prototype usable in desktop
-browsers, narrow desktop viewports, and Storybook without a touchscreen. A primary
+Gesture mode intentionally consumes primary mouse/trackpad clicks in addition
+to touch input. This keeps the composition usable in desktop browsers, narrow
+desktop viewports, and Storybook without a touchscreen. A primary
 mouse/trackpad click in pane content must start radial gesture handling, call
-`preventDefault()`, stop propagation, and capture that pointer; it is not passed
-through to the embedded `Wall`, xterm, or dockview for focus, selection, or pane
-interaction. Non-primary mouse buttons are ignored by gesture handling so their
-browser or host behavior can continue. Users who want terminal selection or TUI
-mouse input must choose Select or Mouse mode explicitly.
+`preventDefault()`, stop propagation, and capture that pointer; it is not
+passed through to the embedded `Wall`, xterm, or dockview for focus,
+selection, or pane interaction. Non-primary mouse buttons are ignored by
+gesture handling so their browser or host behavior can continue. Users who
+want terminal selection or TUI mouse input must choose Select or Mouse mode
+explicitly.
 
-## 5. Gesture Mode
+## Gesture mode
 
 Gesture mode is the default pane-content touch behavior. Tapping the pane content
 opens a radial menu offset from the touch origin. The menu should appear in the
@@ -285,9 +253,13 @@ Root gesture menu:
 ```text
 Esc      ⌃C*               ▲                n Backspace
 Quit**                                                     Paste*
+```
 
+```text
                            ◀                ▶
+```
 
+```text
 ⬆︎Tab                     ▼                  y ⬆︎Enter
 Tab Space                                   Enter
 ```
@@ -309,7 +281,7 @@ Source of truth: `MOBILE_TERMINAL_KEY_SEQUENCES` in
 mapping; `MOBILE_GESTURE_GROUPS` and `MOBILE_GESTURE_QUIT_GROUP` in
 `lib/src/lib/mobile-gesture-menu.ts` define root and quit submenu actions.
 
-## 6. Input Mode Selector
+## Input mode selector
 
 The input mode selector controls what appears in the reserve area. It is always
 visible and has four items:
@@ -332,18 +304,23 @@ icons, and placeholder copy.
 | Type | The reserve area displays the Type reserve placeholder copy and focuses the hidden terminal input. Every typed key is echoed into the terminal as it happens. |
 | Draft | The entire reserve area displays the Draft reserve placeholder copy. |
 
-Default input mode is **Type**.
+Default input mode is **Type**. Recent and Draft are placeholder-only today —
+the real features are staged (see [Future](#future)).
 
 Switching to Type should focus the hidden input and open the native keyboard
 where browser policy allows. Switching away from Type should blur the hidden
 input so the app keyboard UI is visible again.
 
-Tapping the **Type** selector must focus the hidden input synchronously during
-the tap/click handler. Do not defer this focus to `requestAnimationFrame` or a
-timer, because mobile browsers may then treat it as no longer user-initiated and
-refuse to open the native keyboard.
+Tapping the **Type** selector focuses the hidden input synchronously during
+the tap/click handler — the user-gesture-linked call is what makes mobile
+browsers open the native keyboard; focus deferred to `requestAnimationFrame`
+or a timer may be treated as not user-initiated and refused. A follow-up
+effect additionally re-asserts focus via rAF and staggered timers as best
+effort — it helps after re-renders, and is the only focus path when Type is
+the initial mode with no tap (where strict browsers may keep the keyboard
+closed until the first real tap).
 
-## 7. Type Mode Input
+## Type mode input
 
 Use a hidden or visually minimal input configured for terminal-style typing:
 
@@ -368,38 +345,7 @@ Required behavior:
 * Input supports mobile keyboard behavior and IME composition.
 * The app does not depend only on `keydown` for text input.
 
-## 8. Terminal Playground Behavior
-
-A fake shell is acceptable for v0.
-
-Minimum useful behavior:
-
-* Echo typed characters.
-* Maintain a command line buffer.
-* Enter submits the current command.
-* Backspace edits the current command.
-* Gesture-generated arrow keys produce visible behavior.
-* Escape and Tab produce visible behavior.
-* When a fake full-screen app such as `ascii-splash`, `splash`, `changelog`, or
-  `tut` is running, `Ctrl+C` sends `\x03` to that app; if the app exits, the
-  terminal returns to the fake shell prompt instead of restarting the app.
-* New panes created from the wall get the same fake shell behavior and prompt as
-  regular `/playground/desktop` panes.
-
-Example commands:
-
-```text
-help
-clear
-echo hello
-ascii-splash
-changelog
-tut
-```
-
-The shell only needs enough behavior to test the mobile controls.
-
-## 9. Keyboard Reserve
+## Keyboard reserve
 
 The keyboard reserve area has a stable height. It should not be recomputed from
 `visualViewport` while the native keyboard animates.
@@ -410,7 +356,7 @@ UI: session list, or the Recent/Type/Draft reserve placeholder copy.
 When the OS keyboard is visible, the OS keyboard may cover or occupy that same
 physical area. This is preferred over resizing the whole app around the keyboard.
 
-## 10. Touch Interactions
+## Touch interactions
 
 Required interactions:
 
@@ -433,89 +379,35 @@ focus to `requestAnimationFrame`, the wrapper must also repeat that blur shortly
 after the touch. The only mobile UI surfaces that should open the native
 keyboard are the Type selector and the Type reserve area.
 
-Not required for v0:
-
-* Long-press key repeat.
-* Multi-touch gestures.
-* Trackpad mode.
-* A full command history UI.
-* A real draft editor.
-
-## 11. Copy And Paste
-
-Keep copy and paste minimal.
+## Copy and paste
 
-Prototype behavior:
+Keep copy and paste minimal:
 
-* Text selection mode should allow the existing terminal selection and copy/paste flows to work.
+* Text selection mode should allow the existing terminal selection and copy/paste flows to work (`docs/specs/mouse-and-clipboard.md`).
 * Let users paste through the native browser/OS paste flow where possible.
 * No custom mobile clipboard manager is required.
 * No multi-line paste review is required.
 
-## 12. Recommended v0 Scope
-
-Build exactly this:
-
-* One mobile terminal playground screen with one visible session at a time.
-* Floating theme switcher using the shared Dormouse theme picker.
-* Touch mode selector:
-
-```text
-Gestures | Select | Mouse
-```
-
-* Input mode selector:
-
-```text
-Sessions | Recent | Type | Draft
-```
-
-* Stable keyboard reserve area.
-* Sessions reserve content: active session rows with alert and TODO state.
-* Recent reserve content: the Recent reserve placeholder copy.
-* Draft reserve content: the Draft reserve placeholder copy.
-* Type mode native mobile keyboard input.
-* Gesture mode radial menu for arrows, navigation keys, Esc, Tab, Enter, simple vim-like keys, confirmed Ctrl+C, confirmed Paste, and Quit breakout.
-* Pocket `tut` starts directly in the Gesture navigation section, uses the title `Dormouse Pocket Tutorial`, and credits gesture items from radial-menu input callbacks rather than from native keyboard input.
-* Simple local playground terminal behavior.
-
-## 13. Prototype Success Criteria
+## Files
 
-The prototype should answer these questions:
+| File | Role |
+|------|------|
+| `lib/src/components/MobileTerminalUi.tsx` | The mobile wrapper: touch/input mode state, selectors, keyboard reserve, hidden Type input, key sequences (`MOBILE_TERMINAL_KEY_SEQUENCES`) |
+| `lib/src/components/MobileWall.tsx` | One-active-session mobile wall composition and session-row helpers (`useMobileWallSessionItems`) |
+| `lib/src/components/MobileGestureRadialMenu.tsx` | Radial menu rendering: keypad layout, group opacity, completion animation |
+| `lib/src/lib/mobile-gesture-menu.ts` | Gesture geometry (radii, option directions) and root/quit action groups |
 
-1. Does the terminal viewport feel stable when the mobile keyboard opens and closes?
-2. Is the touch mode selector understandable and reachable?
-3. Is Gesture mode fast and understandable enough for arrows, navigation keys, and common TUI exits?
-4. Is text selection discoverable and reliable on mobile?
-5. Is Mouse mode useful when a TUI captures mouse events?
-6. Does native keyboard Type mode feel acceptable for terminal text entry?
-7. Does the stable keyboard reserve feel better than resizing the whole UI?
-8. Is the UI too cramped in portrait orientation?
-
-## 14. Future Work
+## Future
 
 Potential later additions:
 
-* Real recent commands.
-* Draft scratchpad.
+* Real recent commands (the Recent reserve is placeholder copy today).
+* Draft scratchpad (the Draft reserve is placeholder copy today).
 * Dual-pane copy/paste.
 * Pinned snippets.
 * Ctrl+D and Ctrl+Z app-key buttons.
 * Alt and modifier behavior.
 * Long-press key repeat.
-* Remote backend PTY.
-* SSH sessions.
-* User accounts.
-* Session persistence.
-* Multi-session support.
-* Production security model.
-
-## 15. Product Principle
-
-The v0 prototype should stay focused:
-
-```text
-Touch modes make pane touches explicit.
-Input modes make the reserve area explicit.
-Everything else waits.
-```
+* Multi-touch gestures.
+* Trackpad mode.
+* Multi-session support (more than one visible session).
diff --git a/docs/specs/mouse-and-clipboard.md b/docs/specs/mouse-and-clipboard.md
index ebb2b58e..b77f8bf5 100644
--- a/docs/specs/mouse-and-clipboard.md
+++ b/docs/specs/mouse-and-clipboard.md
@@ -52,7 +52,7 @@ The temporary override ends on the **next mouse-up event inside the terminal con
 
 **Auto-clear on reporting off.** If the inside program stops requesting mouse reporting (e.g. exits or sends DECRST `?1000l`/`?1002l`/`?1003l`) while either override is active, the override is cleared. The icon and banner are removed because there is no longer anything to override.
 
-**No keyboard activation.** The Mouse icon, No-Mouse icon, and banner buttons are mouse-only. They are not keyboard-activatable.
+**No designed keyboard path.** The Mouse icon, No-Mouse icon, and banner buttons are mouse-first: no keybinding or focus management targets them. They are plain buttons, so focus-based activation is not actively prevented — making them properly keyboard-activatable is listed in §9.1.
 
 ---
 
@@ -66,7 +66,7 @@ Selection is available whenever the terminal is handling mouse events — that i
 - On touch or pen surfaces, a primary pointer tap-and-drag follows the same
   terminal selection path as mouse drag. Non-primary touch pointers are ignored.
 - The selection is rendered by the terminal in a compositor layer **above** the cell grid, not by writing into the grid. This avoids conflicts with programs redrawing the screen.
-- The selection rectangle is drawn as a single perimeter outline tracing the union of selected cells. Color is taken from `--vscode-focusBorder` with fallbacks to terminal foreground and selection background.
+- The selection rectangle is drawn as a single perimeter outline tracing the union of selected cells. Color comes from `--color-focus-ring` (the dynamic pick in `docs/specs/theme.md`: chromatic `focusBorder`, else chromatic active-header background), with a final hardcoded cornflower-blue fallback in `SelectionOverlay.tsx`.
 
 ### 3.2 Selection Shapes
 
@@ -232,9 +232,9 @@ Paste behavior differs by platform to match each OS's native convention.
 |----------------|-----------------------------------------------------------------------------------|
 | **Cmd+V**      | Terminal intercepts and performs a bracketed paste.                               |
 | **Cmd+Shift+V**| Terminal intercepts and performs a bracketed paste. (Alias for Cmd+V.)            |
-| **Ctrl+V**     | Not intercepted. Forwarded to the inside program as the raw control byte `0x16`.  |
+| **Ctrl+V**     | Also intercepted — paste, same as Cmd+V. Not forwarded as the raw control byte `0x16`. |
 
-macOS users have a clean separation: Cmd is the paste modifier, Ctrl passes through to the program.
+The paste chord accepts either modifier on every platform (the interception deliberately shadows readline's `quoted-insert` — see §8.3 for sending a literal `0x16`). Copy keeps the clean macOS separation — only `⌘C` is intercepted, `Ctrl+C` passes through (§4.2) — but paste does not.
 
 #### 8.2.2 Windows and Linux
 
@@ -245,19 +245,19 @@ macOS users have a clean separation: Cmd is the paste modifier, Ctrl passes thro
 
 Because Ctrl+V is needed as both the paste shortcut (universal user expectation) and as the raw control byte `0x16` (for shell `quoted-insert`, vim literal-next, etc.), Ctrl+V is always intercepted; the raw byte is not sent to the inside program by this key. Users needing to send `0x16` can use the shell mechanism in §8.3.
 
-### 8.3 Sending `0x16` on Windows and Linux (Ctrl+Q)
+### 8.3 Sending `0x16` (Ctrl+Q)
 
-Users needing to insert a literal control character at a shell prompt can use the existing readline feature: press **Ctrl+Q**, then the desired key. This is a feature of bash, zsh, fish, and other readline-aware shells; the terminal does nothing special to enable it. The terminal provides no equivalent for programs that do not support Ctrl+Q-style `quoted-insert` (e.g. vim insert mode).
+Because Ctrl+V is intercepted on every platform, users needing to insert a literal control character at a shell prompt use the existing readline feature: press **Ctrl+Q**, then the desired key. This is a feature of bash, zsh, fish, and other readline-aware shells; the terminal does nothing special to enable it. The terminal provides no equivalent for programs that do not support Ctrl+Q-style `quoted-insert` (e.g. vim insert mode).
 
 ### 8.4 Platform Detection
 
-Platform is detected at startup from `navigator.userAgentData.platform` (preferred), `navigator.platform`, or the user-agent string, matched against `/Mac|iPhone|iPad/`. The result is exposed as the `IS_MAC` constant in `lib/src/lib/platform/index.ts` and consulted by every place that selects between Cmd and Ctrl conventions.
+Platform is detected at startup from `navigator.userAgentData.platform` (preferred), `navigator.platform`, or the user-agent string, matched against `/Mac|iPhone|iPad/i`. The result is exposed as the `IS_MAC` constant in `lib/src/lib/platform/index.ts` and consulted where behavior splits by platform — the copy chord (§4.2) and hint strings; the paste chord accepts both modifiers everywhere (§8.2).
 
 ### 8.5 Bracketed Paste
 
 When the inside program has opted in via `\e[?2004h` (tracked as the `bracketedPaste` field on the per-terminal mouse-selection state), the terminal writes `\e[200~`, then the clipboard content, then `\e[201~`, to the PTY. Otherwise the content is written without brackets. This is standard xterm behavior; it allows shells and TUIs to distinguish pasted content from typed input.
 
-The bracketed-paste mode is read at paste time from xterm's public `terminal.modes.bracketedPasteMode`, kept in sync via a parser hook on `CSI ? ... h`/`l` (see `lib/src/lib/mouse-mode-observer.ts`).
+The bracketed-paste mode is read at paste time from the per-terminal mouse-selection state's `bracketedPaste` field, which `lib/src/lib/mouse-mode-observer.ts` keeps in sync with xterm's public `terminal.modes.bracketedPasteMode` via a parser hook on `CSI ? ... h`/`l`.
 
 ### 8.6 Paste Content
 
@@ -265,7 +265,7 @@ Paste reads the clipboard in three tiers, falling through in order:
 
 1. **File references.** The platform adapter checks for OS file references (Finder/Explorer Copy of a file) via the sidecar/extension host. If present, each path is shell-escaped and the space-joined list is written to the PTY with a trailing space so the next token starts cleanly. Files are checked first so that a file-ref clipboard never reaches `navigator.clipboard.readText()` — on macOS WKWebView that call can trigger a native paste-permission popup when the clipboard came from another app.
 2. **Plain text.** `navigator.clipboard.readText()`. If non-empty, the string is written to the PTY (with bracketed-paste wrapping when enabled by the inside program).
-3. **Raw image data.** If neither of the above matches and the clipboard holds image bytes (e.g. a `Cmd+Shift+4` screenshot), the bytes are written to a newly-created private temp directory as `<uuid>.png` and that single path is pasted as in tier 1. On Unix-like systems the temp directory is owner-only and the image file is written owner-readable/writable to avoid exposing clipboard screenshots to other local users.
+3. **Raw image data.** If neither of the above matches and the clipboard holds image bytes (e.g. a `Cmd+Shift+4` screenshot), the bytes are written to a newly-created private temp directory as `<uuid>-clipboard.png` and that single path is pasted as in tier 1. On Unix-like systems the temp directory is owner-only and the image file is written owner-readable/writable to avoid exposing clipboard screenshots to other local users.
 
 Each tier is implemented by one of two backends. The **VSCode build** (all platforms) and the **standalone/Tauri build on macOS and Linux** use a shared Node module (`standalone/sidecar/clipboard-ops.js`) that shells out to the OS-native clipboard tool: `osascript` on macOS, `Get-Clipboard` on Windows, `wl-paste`/`xclip` on Linux — reached through the sidecar (Tauri) or the extension host (VSCode). The **standalone/Tauri build on Windows** instead reads the Win32 clipboard directly in Rust (`standalone/src-tauri/src/clipboard_win.rs`: `CF_HDROP` for file paths, `CF_UNICODETEXT` for text, `CF_DIB` for an image saved as a `.bmp` temp file — note the extension differs from the sidecar path's `.png`), because the sidecar's `Get-Clipboard` spawns a `powershell.exe` child that pops a console window on the windowless GUI process — several per paste. If every tier comes back empty, paste is a silent no-op.
 
@@ -273,7 +273,7 @@ Content-aware transformations, paste history, credential warnings, and middle-cl
 
 ### 8.7 Drag-to-Paste
 
-Dragging files onto a terminal pane mirrors the paste chain above: escaped paths are typed at the current prompt, space-joined with a trailing space. Tauri receives the drop natively via `WindowEvent::DragDrop` and routes paths to the focused pane.
+Dragging files onto a terminal pane mirrors the paste chain above: escaped paths are typed at the current prompt, space-joined with a trailing space. Tauri receives the drop natively via `WindowEvent::DragDrop` and routes paths to the focused pane — but this wiring is **inert today**: `tauri.conf.json` sets `dragDropEnabled: false` (required so HTML5 drag-and-drop inside the webview — dockview pane dragging — keeps working; tauri-apps/tauri#14373, dormouse#38), so the native handler never fires and drag-to-paste is currently unavailable in the standalone build.
 
 Drag-to-paste is **not supported in the VSCode build**: VSCode's `WebviewView` (sidebar/panel) is excluded from external-file drop routing by the workbench, so the webview iframe never receives `dragover`/`drop` events for files dragged from the OS. See §9.2. VSCode users paste instead (§8.1/§8.5).
 
@@ -283,7 +283,26 @@ Right-click and OS Edit-menu paste are not currently implemented; users paste vi
 
 ---
 
-## 9. Out of Scope / Future Considerations
+## Files
+
+| File | Role |
+|------|------|
+| `lib/src/lib/mouse-selection.ts` | Per-terminal selection / override / bracketed-paste state store |
+| `lib/src/lib/mouse-mode-observer.ts` | DECSET/DECRST parser hook; syncs mouse-reporting and bracketed-paste modes |
+| `lib/src/lib/terminal-mouse-router.ts` | Drag routing, smart-token hinting, Alt shape toggle |
+| `lib/src/lib/clipboard.ts` | Copy/paste entry points and the tiered paste chain |
+| `lib/src/lib/rewrap.ts` | Copy Rewrapped transformations |
+| `lib/src/lib/selection-text.ts` | Selected-cell text extraction |
+| `lib/src/lib/smart-token.ts` | URL / path / error-location patterns (`PATTERNS`) |
+| `lib/src/components/SelectionOverlay.tsx` | Perimeter outline and drag hints |
+| `lib/src/components/SelectionPopup.tsx` | Copy popup and shortcut labels |
+| `lib/src/components/wall/MouseOverrideBanner.tsx` | Temporary-override banner |
+| `standalone/sidecar/clipboard-ops.js` | OS-native clipboard tiers (file refs / text / image) for VSCode on all platforms and Tauri on macOS/Linux |
+| `standalone/src-tauri/src/clipboard_win.rs` | Native Win32 clipboard tiers for Tauri on Windows (`CF_HDROP` / `CF_UNICODETEXT` / `CF_DIB`) |
+
+---
+
+## 9. Future
 
 The following are explicitly not implemented today; they may be added in response to user feedback.
 
diff --git a/docs/specs/pocket-app.md b/docs/specs/pocket-app.md
index 2b2483fe..f3278dcd 100644
--- a/docs/specs/pocket-app.md
+++ b/docs/specs/pocket-app.md
@@ -4,7 +4,7 @@ How the phone client (Dormouse Pocket) is structured and deployed. Companion
 to [remote-api.md](./remote-api.md) (the protocol) and
 [server.md](./server.md) (the selfhost server).
 
-# The seam: the remote session is a platform adapter
+## The seam: the remote session is a platform adapter
 
 `lib` renders every Dormouse surface through a `PlatformAdapter`
 (`lib/src/lib/platform/types.ts`). The adapter's PTY core — `writePty`,
@@ -27,10 +27,13 @@ So the Pocket app is NOT a bespoke terminal UI. It is:
 
 — the exact composition the website playground already proves out with
 `FakePtyAdapter` (`website/src/components/PocketTerminalExperience.tsx`).
-One mobile terminal experience in `lib`, three consumers: the website
-playground (fake adapter), the real Pocket (remote adapter), and whatever
-comes later. Everything not in the PTY core no-ops or is absent — the
-interface is designed for capability degradation.
+Source of truth: `lib/src/remote/pocket-app/PocketWall.tsx` composes
+`MobileTerminalUi` + `MobileWall` over the remote adapter. One mobile terminal
+experience in `lib`, three consumers: the website playground (fake adapter),
+the real Pocket (remote adapter), and whatever comes later. Everything not in
+the PTY core no-ops or is absent — the interface is designed for capability
+degradation.
+
 Pocket hides `MobileWall`'s local Kill affordance: remote panes are
 Host-owned, and v1 grants no phone-side kill/layout authority. Closing a local
 xterm view without a Host-side close would leave the Host attachment live and
@@ -48,7 +51,7 @@ connect denial reports an ACL miss (`passkey-not-paired`,
 shows Pair again so expected Host ACL resets, revocations, or browser
 device-key loss recover through the normal pairing ceremony.
 
-# Module layout
+## Module layout
 
 ```
 lib/src/remote/
@@ -64,33 +67,29 @@ lib/src/remote/
 The server (`server/`) stays the only dynamic code: accounts, relay, and
 static serving of the built Pocket bundle.
 
-# Deployment: same-origin, always
+## Deployment: same-origin, always
 
 WebAuthn binds passkeys to the serving origin, and Chrome's Private Network
 Access rules are progressively blocking public-site → private-network fetches.
 Both point the same way: **the Pocket app is always served same-origin with
 its API.** One lib-owned bundle, two deployments:
 
-* **Selfhost (now):** the Node server serves the bundle (`lib/dist-pocket`).
-  Selfhost auth never depends on dormouse.dev existing.
-* **SaaS (later):** CloudFlare serves the static site and routes `/api/*` and
-  `/ws/*` to the dynamic backend (CloudFlare proxies WebSockets). The same
-  bundle mounts at the site origin; rpId is the site's. The dynamic surface
-  is two path prefixes — everything else stays static.
+* **Selfhost (shipped):** the Node server serves the bundle
+  (`lib/dist-pocket`). Selfhost auth never depends on dormouse.dev existing.
+* **SaaS (staged — see [Future](#future)):** CloudFlare serves the static site
+  and routes `/api/*` and `/ws/*` to the dynamic backend (CloudFlare proxies
+  WebSockets). The same bundle mounts at the site origin; rpId is the site's.
+  The dynamic surface is two path prefixes — everything else stays static.
 
 The website keeps its playground and marketing pages fully static in both
 worlds and shares all terminal UI through `lib`; it never duplicates Pocket
 code.
 
-# Phases
-
-1. **RemotePtyAdapter + real Pocket UI** — move the protocol modules to
-   `remote/client/`, add the adapter, rebuild the Pocket entry as
-   auth views + `MobileTerminalUi`/`MobileWall`, delete the bespoke terminal
-   UI from the POC. Protocol and server untouched. The fake host harness
-   grows a synthetic directory + echo terminal so the adapter is testable
-   end-to-end without a real host.
-2. **Dedupe the composition** — extract the thin wiring shared by the
-   website's `PocketTerminalExperience` and the Pocket shell so the two
-   cannot drift.
-3. **CloudFlare routing** — deferred until SaaS; nothing in 1–2 needs rework.
+## Future
+
+1. **Dedupe the composition** — extract the thin wiring shared by the
+   website's `PocketTerminalExperience` and the Pocket shell
+   (`PocketWall.tsx`) so the two cannot drift. Today each wires
+   `MobileTerminalUi` + `MobileWall` independently.
+2. **CloudFlare routing** — the SaaS deployment above; deferred until SaaS.
+   Nothing in the shipped architecture needs rework for it.
diff --git a/docs/specs/remote-api.md b/docs/specs/remote-api.md
index 7fc62434..183735d8 100644
--- a/docs/specs/remote-api.md
+++ b/docs/specs/remote-api.md
@@ -2,108 +2,83 @@
 
 > See `docs/specs/glossary.md` for the canonical Pane / Surface / Session model; this spec uses that vocabulary and adds only remote-specific terms (Viewer, and the wire-level `DirectoryEntry` projection of a pane).
 
-This spec sketches the API a Client uses to view and control a Host's surfaces
-after a session has been authorized by the
-[remote security model](./remote-security-model.md). Nothing here weakens that
-model: every message below travels inside one authorized session, and the Host
-can terminate the session (and every stream in it) at any time.
+The API a Client uses to view and control a Host's surfaces after a session has
+been authorized by the [remote security model](./remote-security-model.md).
+Nothing here weakens that model: every message below travels inside one
+authorized session, and the Host can terminate the session (and every stream in
+it) at any time.
 
-Two consumers, one protocol:
+The protocol is designed for two consumers at different consumption depths —
+one protocol, not two:
 
 * **Phone (Dormouse Pocket)** — the user sees a directory of the Host's active
-  panes (terminal and browser), picks one, and views/controls just that one.
-* **VR headset** — the client runs the entire Dormouse UI remotely: the full
-  wall layout, every surface live at once, each rendered as its own panel in
-  space.
-
-The phone is not a different API — it is a shallow consumer of the same one.
-
-| Capability            | Phone            | VR               |
-| --------------------- | ---------------- | ---------------- |
-| `directory.watch`     | yes (the picker) | optional         |
-| `surface.attach`      | one at a time    | many at once     |
-| `wall.watch` (layout) | no               | yes              |
-| Layout mutations      | no               | yes              |
-| Input                 | to attached pane | to any surface   |
-
-Design principle: **replicate state, don't stream a desktop.** Terminals are
-sent as PTY data and rendered client-side (the Client already ships the
-terminal renderer); browser surfaces are sent as per-surface screencasts. This
-is what makes VR viable — each surface arrives as its own independently
-placeable, independently sized stream — and it makes the phone cheap: one
-attached surface costs one stream.
-
----
-
-# v1 scope
-
-v1 is the smallest protocol that lets a phone **sign in, pick a pane, see it
-live, and type into it** — the phone column of the table above, and only it:
-
-* Hello (version + capabilities)
-* `directory.watch`, snapshot-only (no deltas, no thumbnails)
+  panes, picks one, and views/controls just that one. Shipped.
+* **VR headset** — the client runs the entire Dormouse UI remotely: the Host's
+  whole Window — every Workspace's layout, every surface live at once. Future —
+  see [Future](#future).
+
+| Capability              | Phone            | VR (future)      |
+| ----------------------- | ---------------- | ---------------- |
+| `directory.watch`       | yes (the picker) | optional         |
+| `surface.attach`        | one at a time    | many at once     |
+| `window.watch` (layout) | no               | yes              |
+| Layout mutations        | no               | yes              |
+| Input                   | to attached pane | to any surface   |
+
+Design principle, and a standing constraint on everything staged below:
+**replicate state, don't stream a desktop.** Terminals are sent as PTY data and
+rendered client-side (the Client already ships the terminal renderer); browser
+surfaces will be sent as per-surface screencasts. This is what makes VR viable —
+each surface arrives as its own independently placeable stream — and it makes
+the phone cheap: one attached surface costs one stream.
+
+## v1 scope
+
+**Scope: protocol-v1** — the smallest protocol that lets a phone **sign in,
+pick a pane, see it live, and type into it**. This is the shipped protocol;
+source of truth is `server-lib-common/src/remote/wire.ts` (the fixed wire
+contract) and `lib/src/remote/host/remote-api.ts` (the Host implementation):
+
+* Hello (version + viewer kind)
+* `directory.watch`, snapshot-only (no deltas, no thumbnails), terminal
+  entries only
 * `surface.attach` / `surface.detach`, one attachment per session
-* Terminal: attach-is-the-resize, live data + semantic events,
-  `terminal.write`/`terminal.resize`, last-attach-wins tethering
-* Browser: screencast frames at Host-chosen fixed quality, pointer + key input
+* Terminal: attach-is-the-resize, live data,
+  `terminal.write`/`terminal.resize`, last-attach-wins size authority
 * One implicit grant: every paired session has full input (selfhost is
   single-user), no layout operations
 
-Everything else is future work, staged in likely order of arrival:
-
-1. **In-flight command replay** — first follow-up after v1 (see Terminal)
-2. **Semantic command scrollback** — v2 (see Terminal)
-3. **Directory thumbnails**
-4. **Graded grants + layout mutations** (observe-only viewers, remote
-   split/kill with Host-side confirm)
-5. **The wall: VR** (`wall.watch`, multi-attach, wall lease)
-6. **WebRTC transport + app-layer encryption**
-7. **Audio**
+Everything else — including browser-surface remoting — is staged in
+[Future](#future). Each staged item is additive — a new method, event, or
+optional field — so nothing in the shipped protocol changes shape when it
+lands.
 
-Each future item is additive — a new method, event, or optional field — so
-nothing in the v1 protocol changes shape when it lands.
-
----
-
-# Terminology
+## Terminology
 
 `docs/specs/glossary.md` is canonical for **Pane** and **Surface**; the wire
 shapes reuse the existing surface model (`dor/src/protocol.ts`,
 `dor/src/commands/types.ts`). Remote-specific usage:
 
-* **Surface** — identified on the wire by `surfaceId`; carries `ref`,
-  `paneRef`, `title`, `focused`, `indexInPane`, `selectedInPane`.
+* **Surface** — identified on the wire by `surfaceId`.
 * **Pane** — the phone's picker lists panes; attaching to a pane means
   attaching to its selected surface.
-* **Wall** — the full layout tree (workspaces → windows → panes) plus geometry.
-  Only VR consumes this.
-* **Viewer** — one connected Client session. Multiple viewers may coexist; the
-  Host UI shows who is connected.
+* **Viewer** — one connected Client session. Multiple viewers may coexist.
+* **Window** — the Host's full layout tree (its Workspaces, their Panes and
+  Surfaces) plus geometry, consumed only by VR (future; see
+  [Future](#future)). The glossary reserves **Wall** for the renderer of a
+  single Workspace, so the VR subscription replicates the *Window*.
 
----
+## Transport
 
-# Transport
+### Channels
 
-## Channels
-
-v1 transport is **WebSocket relay only**: one WebSocket per session, relayed
+Transport is **WebSocket relay only**: one WebSocket per session, relayed
 through the Server, bound to the `sessionId` issued by `authorizeConnection`.
-Control messages and media frames share the socket:
-
-* **Control** — requests, responses, and event subscriptions. Terminal data
-  rides here too (it is small and ordering matters).
-* **Media** — browser screencast frames. A dropped frame must be skipped, not
-  queued behind: the Host keeps at most the newest frame per attachment and
-  sends it only when the socket drains, so a slow link degrades to a lower
-  frame rate instead of growing a buffer.
+Control messages ride the socket as JSON; terminal data rides here too (it is
+small and ordering matters). Media channels arrive with browser surfaces
+(future).
 
-Future upgrades, none of which change the API surface: WebRTC rendezvous for
-latency (the Server signals but, per the security model, is never trusted with
-authorization — pin the DTLS fingerprint inside the device-key-signed connect
-payload), and app-layer encryption so the relaying Server sees only
-ciphertext.
-
-## Server deployment modes
+### Server deployment modes
 
 The Server always ships in two modes; the remote API and the security model
 are identical in both — the modes differ only in how accounts come to exist.
@@ -111,13 +86,14 @@ are identical in both — the modes differ only in how accounts come to exist.
 * **Selfhost** — an env-var sets a setup password; presenting it allows the
   system's only user to create their account and register the first passkey.
   Sign-in from then on is passkey-only. No database: accounts, passkey
-  credentials, and revocation state live in local files.
+  credentials, and revocation state live in local files. Shipped
+  (`docs/specs/server.md`). Selfhost is not a stepping stone: it remains a
+  supported mode alongside SaaS permanently.
 * **SaaS multitenant** — anyone can create an account with email + passkey.
+  Future (deployment plumbing staged in `docs/specs/pocket-app.md`
+  `## Future`).
 
-v1 ships selfhost only. Selfhost is not a stepping stone: it remains a
-supported mode alongside SaaS permanently.
-
-## Envelope
+### Envelope
 
 Same shape as the dor control protocol — requests correlated by `requestId`,
 events correlated by `subId`:
@@ -128,57 +104,51 @@ interface RemoteResponse { requestId: string; ok: boolean; result?: object; erro
 interface RemoteEvent    { subId: string; event: string; data: object }
 ```
 
-## Hello
+### Hello
 
-First exchange on the control channel; establishes version and capabilities so
+First exchange on the control channel; establishes version and viewer kind so
 the protocol can grow without breaking older Pockets.
 
 ```ts
 // client → host
-interface ClientHello {
+interface HelloParams {
   protocolVersion: 1;
   viewer: 'phone' | 'vr' | 'desktop';
-  /** What the client can render / wants to do. v1 phones send
-   *  { screencast: ['jpeg'], input: true, wall: false }. */
-  capabilities: {
-    screencast: ReadonlyArray<'jpeg' | 'webp'>;
-    input: boolean;
-    wall: boolean;
-  };
 }
 
 // host → client
-interface HostHello {
+interface HelloResult {
   protocolVersion: 1;
   hostId: string;
-  /** v1: always { input: true, layout: false } — selfhost is single-user, so
+  /** Always { input: true, layout: false } today — selfhost is single-user, so
    *  every paired session is the owner. Graded grants are future work. */
   grants: { input: boolean; layout: boolean };
 }
 ```
 
----
+Reserved: a `capabilities` field on the client hello (what the client can
+render — screencast formats, window support) lands additively when browser
+surfaces arrive; see [Future](#future).
 
-# Directory (the phone's picker)
+## Directory (the phone's picker)
 
 `directory.watch` subscribes to a live, lightweight listing of every pane —
 enough to render the picker and know which pane wants attention, without
 attaching to anything.
 
 ```ts
+/** Terminal-only today: no browser entries. */
 interface DirectoryEntry {
   paneRef: string;
   surfaceId: string;            // the selected surface in the pane
-  type: 'terminal' | 'agent-browser';  // iframe surfaces are not listed (unsupported)
-  title: string;                // derived title, same one the wall header shows
+  type: 'terminal';
+  title: string;                // derived title, same one the Wall's pane header shows
   focused: boolean;             // focused on the host
-  // Terminal-only, from the existing semantic-event model (terminal-state.ts):
+  // From the existing semantic-event model (terminal-state.ts):
   activity?: 'unknown' | 'prompt' | 'editing' | 'running' | 'finished';
   exitCode?: number;
   alive: boolean;               // the PTY process is still alive (see below)
   cwd?: string;
-  // Browser-only:
-  url?: string;
   /** The pane's alert is ringing on the host (alert-manager). */
   ringing: boolean;
   /** The pane has an outstanding TODO waiting for the user. */
@@ -190,11 +160,15 @@ type DirectoryEvent =
 ```
 
 Snapshot-only, deliberately: a directory is dozens of entries at most, so on
-any change the Host coalesces and resends the whole thing. Delta events are a
-future optimization there is no current reason to pay for.
+any change the Host coalesces (150ms window, `DIRECTORY_DEBOUNCE_MS`) and
+resends the whole thing. Delta events are a future optimization there is no
+current reason to pay for.
 
-Thumbnails are future work; in v1 the picker renders from titles, activity,
-and the `ringing`/`hasTODO` badges.
+The picker renders from titles, activity, and the `ringing`/`hasTODO` badges;
+thumbnails are staged (see [Future](#future)). Browser panes are not listed;
+iframe surfaces additionally refuse attachment by design (see
+[Future](#future) for browser remoting — iframe surfaces are not on the
+critical path even there).
 
 `alive` reflects real PTY-process liveness: it is `true` while the pane's
 process is running and `false` once that process has exited. Dormouse keeps an
@@ -208,37 +182,37 @@ shell-integration semantic status, not PTY lifetime. A pane can report
 `alive: true` with an `exitCode` set (a command finished but the shell lives on),
 and a pane reporting `alive: false` may carry no `exitCode` at all.
 
----
-
-# Attaching to a surface
+## Attaching to a surface
 
-`surface.attach { surfaceId, ... }` opens the surface's stream (terminals add
-their dimensions — see below); `surface.detach { surfaceId }` closes it. v1
-allows one attachment per session (the phone's model); lifting that cap for VR
-is future work. Attachment is view-state only with one deliberate exception:
-attaching to a terminal takes size authority.
+`surface.attach { surfaceId, cols, rows }` opens the surface's stream;
+`surface.detach { surfaceId }` closes it. One attachment per session (the
+phone's model); lifting that cap for VR is future work. Attachment is
+view-state only with one deliberate exception: attaching to a terminal takes
+size authority.
 
-## Terminal surfaces
+### Terminal surfaces
 
 Replicated, not screencast: the client renders its own xterm from the same
 data the host UI consumes.
 
-### Attach is the resize (v1)
+#### Attach is the resize
 
 The remote is virtually always a different size than the Host, and a resize is
 exactly what makes a terminal paint itself — so attach carries the client's
 dimensions and there is no snapshot transfer:
 
 1. Client attaches with `{ cols, rows }`.
-2. Host resizes the PTY (last-attach-wins; see Size authority). `SIGWINCH`
-   makes full-screen TUIs repaint completely and shells redraw their prompt
-   line, filling the client's screen from the live stream alone.
-3. If the requested size happens to equal the current size, the Host forces
-   the repaint anyway: `SIGWINCH` alone first (most TUIs refetch size and
-   repaint), then a quick rows±1 bounce if no output follows.
+2. Host resizes the PTY through the existing xterm resize path
+   (last-attach-wins; see Size authority). `SIGWINCH` makes full-screen TUIs
+   repaint completely and shells redraw their prompt line, filling the
+   client's screen from the live stream alone.
+3. If the requested size equals the current size, `terminal.resize` would be a
+   no-op, so the Host bounces the PTY's rows to force one SIGWINCH-driven
+   repaint (`FORCE_REPAINT_BOUNCE_MS`).
 
 Normal-screen history does not regenerate on resize; it is deliberately absent
-from v1 (see Future work below).
+from the shipped protocol (see [Future](#future): in-flight replay, then
+semantic scrollback).
 
 ```ts
 // client → host
@@ -248,16 +222,23 @@ from v1 (see Future work below).
 interface TerminalAttachResult {
   cols: number; rows: number;     // the size the PTY now has
   // Reserved: `inflight` (in-flight replay) and `blocks` (semantic
-  // scrollback) land here additively — see Future work.
+  // scrollback) land here additively — see Future.
 }
 
 // then a stream of:
 type TerminalEvent =
-  | { event: 'terminal.data';     data: { bytes: string /* base64 */ } }
-  | { event: 'terminal.resize';   data: { cols: number; rows: number } }   // another display took authority
-  | { event: 'terminal.semantic'; data: TerminalSemanticEvent }  // cwd/activity/title, as today
+  | { event: 'terminal.data';     data: { bytes: string /* base64url */ } }
   | { event: 'terminal.closed';   data: { exitCode?: number } };
+```
+
+These two are the whole v1 stream. A viewer is not notified when another
+display takes size authority, and semantic state (activity/cwd/title) reaches
+the client only through `directory.snapshot` — the host→client
+`terminal.resize` and `terminal.semantic` events are staged in
+[Future](#future) (item 5) and land additively, since events are dispatched by
+name.
 
+```ts
 // client → host (requires the input grant)
 type TerminalInput =
   | { method: 'terminal.write';  params: { surfaceId: string; bytes: string } }
@@ -276,24 +257,86 @@ When that PTY exits, the Host emits `terminal.closed` and then drops the
 attachment, so a later `terminal.write`/`terminal.resize` for the surface is
 rejected ("surface is not attached") instead of acting on the disposed terminal.
 
-### Size authority: last-attach-wins
+#### Size authority: last-attach-wins
 
 A terminal has one size, and the most recent size writer owns it: attaching
 with dimensions and `terminal.resize` both take authority, and the Host user
-interacting with the pane locally reclaims it. Every other display of that
-pane — the Host's wall pane, other attached viewers — greys out and shows only
-**"tethering to \<device\>"** (the ACL record's label, e.g. `iPhone Safari`)
-instead of fighting over `SIGWINCH`. Interacting with a tethered pane is how a
-display takes it back.
+interacting with the pane locally reclaims it. The Host-side **"tethering to
+\<device\>"** display that greys out other displays of a tethered pane is
+staged — see [Future](#future); today the authority semantics hold at the PTY
+level without the dedicated display.
+
+## Input authority
+
+Deliberately flat: selfhost is single-user, so every paired session is the
+owner and gets full input (`grants: { input: true, layout: false }`). No
+session gets layout operations. Graded grants, Host-side viewer visibility,
+and layout mutations are staged — see [Future](#future).
+
+## Multi-viewer semantics
+
+Concurrent sessions need no special machinery: attach state is per-session,
+streams fan out per attachment, and terminal size is last-attach-wins.
+Interleaved typing from two granted sessions is no worse than two keyboards on
+one machine; the window lease (future) is the only exclusive resource. Showing
+connected viewers on the Host UI (label from the ACL record, e.g. `iPhone
+Safari`) with per-viewer disconnect is staged with the tethering display — see
+[Future](#future).
+
+## Future
+
+Staged in likely order of arrival. Each item is additive — a new method,
+event, or optional field — so nothing in protocol-v1 changes shape when it
+lands.
+
+### 1. Browser surfaces (`agent-browser`)
+
+Browser remoting was specified alongside protocol-v1 but the shipped slice is
+terminal-only, so it is now the first staged item. The existing screencast
+path (`docs/specs/dor-browser.md`), made remote:
+
+* The client hello gains the reserved `capabilities` field
+  (what the client can render — screencast formats, window support):
+  `{ screencast: ['jpeg' | 'webp'], input: boolean, window: boolean }`.
+* `DirectoryEntry` gains browser entries — `type: 'browser'` (the canonical
+  component-level kind, `docs/specs/glossary.md` Naming conventions) plus a
+  browser-only `url` field.
+* Media frames share the WebSocket with control messages. A dropped frame must
+  be skipped, not queued behind: the Host keeps at most the newest frame per
+  attachment and sends it only when the socket drains, so a slow link degrades
+  to a lower frame rate instead of growing a buffer.
 
-### Future work: in-flight replay, then semantic scrollback
+```ts
+type BrowserEvent =
+  | { event: 'browser.frame'; data: { format: 'jpeg' | 'webp'; width: number; height: number; bytes: string } }
+  | { event: 'browser.tab';   data: AgentBrowserTab }   // title/url/active changes
+  | { event: 'browser.closed'; data: {} };
 
-**In-flight replay (first follow-up after v1).** The most common reason to
-open a pane on the phone is a command that is still running — "is my build
-done?" — and a resize repaint shows nothing for a command quietly writing a
-log. (Dormouse's primary workload, agent TUIs, do repaint on resize — which is
-what makes this deferrable at all.) The Host retains the output of the current
-command from its `commandStart` boundary (OSC 133/633, with the existing
+// client → host (requires the input grant); coordinates in frame space,
+// the host maps them through the screencast scale into CDP input.
+type BrowserInput =
+  | { method: 'browser.pointer'; params: { surfaceId: string; kind: 'tap' | 'down' | 'move' | 'up' | 'scroll'; x: number; y: number; dx?: number; dy?: number } }
+  | { method: 'browser.key';     params: { surfaceId: string; text?: string; key?: string; modifiers?: number } };
+```
+
+The Host picks fixed, phone-appropriate screencast parameters (JPEG, capped
+dimension and frame rate) at first; per-attachment quality negotiation
+(`browser.quality`) and remote navigation (`browser.navigate`) come after — a
+phone can drive the page's own UI in the meantime.
+
+Iframe surfaces stay unsupported even here: omitted from the directory,
+refusing attachment; Window snapshots still list them (the layout must be
+truthful) and VR renders an inert placeholder. Nothing else in the protocol
+assumes they exist, so support can be added cleanly later.
+
+### 2. In-flight command replay
+
+The first terminal follow-up. The most common reason to open a pane on the
+phone is a command that is still running — "is my build done?" — and a resize
+repaint shows nothing for a command quietly writing a log. (Dormouse's primary
+workload, agent TUIs, do repaint on resize — which is what makes this
+deferrable at all.) The Host retains the output of the current command from
+its `commandStart` boundary (OSC 133/633, with the existing
 keystroke-heuristic fallback), tail-capped to a fixed byte budget, dropped at
 the next prompt; attach replays it via the reserved `inflight` field:
 
@@ -306,11 +349,12 @@ inflight?: {
 }
 ```
 
-**Semantic command scrollback (v2).** History arrives as structure the Host
-already extracts, not as emulator state: OSC 133/633 segmentation gives
-per-command boundaries, alt-screen spans are already tracked and stripped, and
-the in-flight buffer is the same capture mechanism retained for K commands
-instead of one:
+### 3. Semantic command scrollback
+
+History arrives as structure the Host already extracts, not as emulator
+state: OSC 133/633 segmentation gives per-command boundaries, alt-screen spans
+are already tracked and stripped, and the in-flight buffer is the same capture
+mechanism retained for K commands instead of one:
 
 ```ts
 interface CommandBlock {
@@ -329,96 +373,79 @@ own width — collapsible cards on the phone, panels in VR — rather than
 replaying a fixed-width terminal. Additive by construction: a `blocks` field
 on `TerminalAttachResult` plus a `terminal.block` event.
 
-## Browser surfaces (`agent-browser`)
+### 4. Directory thumbnails
 
-The existing screencast path, made remote:
+### 5. Tethering display and viewer visibility
 
-```ts
-type BrowserEvent =
-  | { event: 'browser.frame'; data: { format: 'jpeg' | 'webp'; width: number; height: number; bytes: string } }
-  | { event: 'browser.tab';   data: AgentBrowserTab }   // title/url/active changes
-  | { event: 'browser.closed'; data: {} };
-
-// client → host (requires the input grant); coordinates in frame space,
-// the host maps them through the screencast scale into CDP input.
-type BrowserInput =
-  | { method: 'browser.pointer'; params: { surfaceId: string; kind: 'tap' | 'down' | 'move' | 'up' | 'scroll'; x: number; y: number; dx?: number; dy?: number } }
-  | { method: 'browser.key';     params: { surfaceId: string; text?: string; key?: string; modifiers?: number } };
-```
-
-In v1 the Host picks fixed, phone-appropriate screencast parameters (JPEG,
-capped dimension and frame rate). Per-attachment quality negotiation
-(`browser.quality`) and remote navigation (`browser.navigate`) are future
-work — a phone can drive the page's own UI in the meantime.
-
-## Iframe surfaces
+While a remote session holds size authority, every other display of that pane
+— the pane in the Host's own Wall, other attached viewers — greys out and shows only
+**"tethering to \<device\>"** (the ACL record's label, e.g. `iPhone Safari`)
+instead of fighting over `SIGWINCH`. Interacting with a tethered pane is how a
+display takes authority back. Alongside it: the Host UI shows connected
+viewers (label from the ACL record) with per-viewer disconnect, and in-flight
+input is dropped the moment a session is killed.
 
-Not supported. Iframe surfaces are omitted from the directory and refuse
-attachment; wall snapshots still list them (the layout must be truthful) and
-VR renders an inert placeholder. Nothing else in the protocol assumes they
-exist, so support can be added cleanly later — it is not on the critical path.
+The wire half, landing additively as new event names:
 
----
+```ts
+// host → client: another display took size authority over your attachment
+{ event: 'terminal.resize';   data: { cols: number; rows: number } }
+// host → client: live cwd/activity/title for the attached pane
+{ event: 'terminal.semantic'; data: TerminalSemanticEvent }
+```
 
-# Input authority
+`terminal.resize` is what lets an attached viewer show its own tether state
+instead of rendering garbled wrap until re-attach; `terminal.semantic` frees
+the attached pane's header from the coalesced `directory.snapshot` cadence.
 
-v1 is deliberately flat: selfhost is single-user, so every paired session is
-the owner and gets full input (`grants: { input: true, layout: false }`). No
-session gets layout operations. The Host UI still shows connected viewers and
-can kill any session live; in-flight input is dropped the moment it does.
+### 6. Graded grants and layout mutations
 
-Future work — graded grants, layered so "the Host is the final authority"
-holds at every step:
+Layered so "the Host is the final authority" holds at every step:
 
 1. **Pairing-time**: the ACL record's approval carries a standing grant
    (observe-only vs interactive) chosen in the Host's approval UI.
-2. **Session-time**: `HostHello.grants` reports what the session actually got.
+2. **Session-time**: the hello's `grants` reports what the session actually
+   got.
 3. **Layout**: destructive operations (`surface.kill`) require the `layout`
    grant and are confirmed on the Host the same way local kills are
    (KillConfirm), unless the Host user opts a session into unattended control.
 
----
-
-# The wall (VR) — future work
-
-Nothing in this section is v1. VR does not stream the desktop; it *is* the
-desktop: the headset runs the same web UI (`lib`) against remote data sources
-instead of local ones.
+### 7. The Window (VR)
 
-## Layout replication
+VR does not stream the desktop; it *is* the desktop: the headset runs the same
+web UI (`lib`) against remote data sources instead of local ones.
 
-`wall.watch` subscribes to the layout tree plus geometry:
+`window.watch` subscribes to the Host Window's layout tree plus geometry. A
+session connects to one Host, hence one Window, so the snapshot follows the
+glossary containment directly (`Window ⊃ Workspace ⊃ Pane ⊃ Surface`):
 
 ```ts
-interface WallSnapshot {
+interface WindowSnapshot {
   workspaces: Array<{
     ref: string; name: string;
-    windows: Array<{
-      ref: string;
-      panes: Array<{
-        paneRef: string;
-        /** Normalized rect within the window, for initial spatial placement. */
-        rect: { x: number; y: number; w: number; h: number };
-        surfaces: Surface[];      // the existing Surface shape
-      }>;
+    panes: Array<{
+      paneRef: string;
+      /** Normalized rect within the Workspace's Wall, for initial spatial placement. */
+      rect: { x: number; y: number; w: number; h: number };
+      surfaces: Surface[];      // the existing Surface shape
     }>;
   }>;
+  /** Which Workspace the Host has mounted locally. */
+  activeWorkspaceRef: string;
   focusedSurfaceId: string | null;
 }
 
-type WallEvent =
-  | { event: 'wall.snapshot'; data: WallSnapshot }
-  | { event: 'wall.changed';  data: WallSnapshot };  // coalesced; layouts are small
+type WindowEvent =
+  | { event: 'window.snapshot'; data: WindowSnapshot }
+  | { event: 'window.changed';  data: WindowSnapshot };  // coalesced; layouts are small
 ```
 
 The rects seed VR placement; after that the headset owns spatial arrangement
 locally (a VR user re-hanging panels in space is presentation, not layout, and
 does not round-trip to the Host).
 
-## Layout mutations
-
-The existing `surface.*` control vocabulary, carried over the session
-(requires the `layout` grant):
+**Layout mutations** reuse the existing `surface.*` control vocabulary,
+carried over the session (requires the `layout` grant):
 
 ```
 surface.split    surface.ensure    surface.send
@@ -428,46 +455,35 @@ surface.kill     surface.read      surface.focus
 These are the same methods the dor CLI speaks today; the remote API reuses
 their request/response shapes so the Host dispatches both through one handler.
 
-## Wall lease
-
-A VR session may request `wall.lease`, declaring itself the primary display.
-Sizing needs no lease — last-attach-wins already hands VR the panes it
-displays — so the lease is presentational: the Host UI tethers wholesale
-("tethering to \<device\>") instead of pane by pane, and panes created on the
-Host while the lease is held open tethered to the leaseholder. One lease at a
-time; the Host user can always reclaim it locally. Phones never need it.
+**Window lease.** A VR session may request `window.lease`, declaring itself
+the primary display. Sizing needs no lease — last-attach-wins already hands VR
+the panes it displays — so the lease is presentational: the Host UI tethers
+wholesale ("tethering to \<device\>") instead of pane by pane, and panes
+created on the Host while the lease is held open tethered to the leaseholder.
+One lease at a time; the Host user can always reclaim it locally. Phones never
+need it.
 
----
+### 8. WebRTC transport and app-layer encryption
 
-# Multi-viewer semantics
+Neither changes the API surface: WebRTC rendezvous for latency (the Server
+signals but, per the security model, is never trusted with authorization — pin
+the DTLS fingerprint inside the device-key-signed connect payload), and
+app-layer encryption so the relaying Server sees only ciphertext.
 
-Concurrent sessions need no special machinery in v1: attach state is
-per-session, streams fan out per attachment, and terminal size is
-last-attach-wins with the tether display resolving contention. Every viewer is
-visible on the Host (label from the ACL record, e.g. `iPhone Safari`), with
-per-viewer disconnect. Interleaved typing from two granted sessions is no
-worse than two keyboards on one machine; the wall lease (future) is the only
-exclusive resource.
+### 9. Audio
 
----
+Browser surfaces can produce audio; VR will want it (spatial, per-panel).
 
-# QoS notes (phone-first)
+### QoS hardening (phone-first, orthogonal to the stages above)
 
-* Terminal output is already coalesced host-side; the remote stream reuses
-  that batching and adds a per-session byte budget with tail-drop + resync
-  (an implicit re-attach: repaint via resize) rather than unbounded buffering
-  on a bad link.
-* Screencast frames are droppable by design; only the newest frame matters.
-* The directory is metadata-only.
+* Terminal output is already coalesced host-side; the remote stream should add
+  a per-session byte budget with tail-drop + resync (an implicit re-attach:
+  repaint via resize) rather than unbounded buffering on a bad link.
 * Detach on backgrounding: when the phone app/PWA loses visibility, the client
   detaches streams but keeps the control channel; reattach is one message.
 
----
-
-# Open questions
+### Open questions
 
-* **Browser media**: screencast frames over the WebSocket are v1; when WebRTC
+* **Browser media**: screencast frames over the WebSocket first; when WebRTC
   arrives, a video track would be smoother for VR. Possibly phone=frames,
   VR=track, negotiated in the hello.
-* **Audio**: browser surfaces can produce audio; VR will want it (spatial,
-  per-panel). Out of scope for v1.
diff --git a/docs/specs/remote-security-model.md b/docs/specs/remote-security-model.md
index 36d9aa15..bd230ba1 100644
--- a/docs/specs/remote-security-model.md
+++ b/docs/specs/remote-security-model.md
@@ -1,22 +1,33 @@
 # Remote Security Model
 
-Our security model is based on two independent security primitives between the Client (Dormouse Pocket), Host (Dormouse Terminal), and coordinating Server:
-
-* Passkeys verify fresh user presence.
-
-  * Fresh user presence is required by both the coordinating server and the host.
-  * Passkeys authenticate the user, but do not independently grant host access.
-
-* Each client device must complete an explicit one-to-one pairing ceremony with each host device.
-
-  * The host maintains its own local ACL of approved clients.
-  * Approved clients are identified by an asymmetric device keypair generated in the browser and stored locally as a non-extractable WebCrypto key.
-
-This separation ensures that account-level compromise is insufficient for host access. Adding a new passkey to an account, or compromising the coordinating server, does not authorize a new client: the host will reject any client that has not been locally paired.
-
-# Goals
-
-Dormouse enables a user to control a Host (Dormouse Terminal) from a Client (Dormouse Pocket) using only web technologies.
+The trust model for remote control, built on two independent security
+primitives between the Client (Dormouse Pocket), Host (Dormouse Terminal), and
+coordinating Server:
+
+* **Passkeys verify fresh user presence.** Fresh presence is required by both
+  the Server and the Host. A passkey authenticates the user; it never
+  independently grants host access.
+* **Each Client device completes an explicit one-to-one pairing ceremony with
+  each Host.** The Host maintains its own local ACL of approved Clients,
+  identified by an asymmetric device keypair generated in the browser and
+  stored locally as a non-extractable WebCrypto key.
+
+This separation ensures that account-level compromise is insufficient for host
+access. Adding a new passkey to an account, or compromising the coordinating
+Server, does not authorize a new client: the Host rejects any client that has
+not been locally paired.
+
+Everything in this spec is implemented in `server-lib-common/src/security/` —
+runtime-agnostic modules shared verbatim by the Server, the Host module in
+`lib`, and the Pocket client, so the three sides cannot disagree on what a
+valid credential is. The concrete pairing and connect message sequences live
+in `docs/specs/server.md` (Relay); this spec defines what those sequences must
+establish.
+
+## Goals
+
+Dormouse enables a user to control a Host (Dormouse Terminal) from a Client
+(Dormouse Pocket) using only web technologies.
 
 Primary goals:
 
@@ -35,51 +46,22 @@ Non-goals:
 * Preventing users from intentionally clearing browser data
 * Providing permanent device identity guarantees across browser resets
 
----
-
-# Terminology
-
-## Client (Dormouse Pocket)
-
-A browser or installed PWA used to initiate remote-control sessions.
-
-Responsibilities:
-
-* Authenticate using passkeys
-* Maintain a local device keypair
-* Establish connections to Hosts
-* Sign Host challenges
-
-## Host (Dormouse Terminal)
-
-The machine being remotely controlled.
-
-Responsibilities:
-
-* Maintain a local ACL of approved Clients
-* Verify Client authorization
-* Verify fresh user presence
-* Establish and terminate control sessions
-
-The Host is the final authority for access decisions.
+## Terminology
 
-## Server
+* **Client (Dormouse Pocket)** — a browser or installed PWA used to initiate
+  remote-control sessions. It authenticates with passkeys, maintains a local
+  device keypair, and signs Host challenges.
+* **Host (Dormouse Terminal)** — the machine being remotely controlled. It
+  maintains the local ACL, verifies Client authorization and fresh user
+  presence, and establishes/terminates control sessions. **The Host is the
+  final authority for access decisions.**
+* **Server** — the coordinating service: account management, passkey
+  registration, WebAuthn challenge generation, and signaling/rendezvous. The
+  Server is not the final authority for Host access. (Revocation today is
+  local state editing — see `docs/specs/server.md` Guardrails; Server-pushed
+  revocation propagation is staged in [Future](#future).)
 
-The coordinating service used for accounts, authentication, signaling, and session establishment.
-
-Responsibilities:
-
-* Account management
-* Passkey registration
-* WebAuthn challenge generation
-* Signaling and rendezvous
-* Revocation propagation
-
-The Server is not the final authority for Host access.
-
----
-
-# Trust Model
+## Trust Model
 
 Dormouse intentionally separates:
 
@@ -90,316 +72,167 @@ Dormouse intentionally separates:
 | Host ACL   | Authorization              |
 | Host       | Final access decision      |
 
-No single layer is sufficient to gain access.
-
-A successful connection requires all layers to agree.
-
----
-
-# Passkeys
-
-## Purpose
-
-Passkeys verify fresh user presence.
-
-Every connection requires a fresh WebAuthn assertion.
-
-Fresh user presence is validated by:
-
-* The Server
-* The Host
-
-A passkey authenticates a user account but does not grant access to any Host.
-
-## Important Property
+No single layer is sufficient to gain access. A successful connection requires
+all layers to agree.
 
-Passkeys are frequently synchronized credentials.
+## Passkeys
 
-Examples include:
+Passkeys verify fresh user presence: every connection requires a fresh
+WebAuthn assertion, validated by **both** the Server and the Host.
 
-* iCloud Keychain
-* Google Password Manager
-* Platform authenticators
-* Hardware security keys
-
-A single passkey may appear on multiple physical devices.
-
-Therefore:
+Passkeys are frequently *synchronized* credentials — iCloud Keychain, Google
+Password Manager, platform authenticators — so a single passkey may appear on
+multiple physical devices. Therefore:
 
 > Passkeys are treated as user credentials, not device identities.
 
----
-
-# Device Keys
-
-## Purpose
-
-Device keys establish long-lived Client identity.
-
-They provide the capability being authorized by the Host.
-
-This prevents:
-
-* Newly-added passkeys from inheriting Host access
-* Synced passkeys from automatically becoming trusted devices
-* Server-only compromise from granting Host access
-
-## Generation
-
-Each Client generates an asymmetric keypair:
-
-* Signing keypair
-* Non-extractable private key
-* Generated using WebCrypto
-
-The public key is used as the Client identifier.
-
-## Storage
-
-Recommended implementation:
-
-* WebCrypto
-* IndexedDB
-* `extractable: false`
-* `navigator.storage.persist()`
-
-The private key never leaves browser storage under normal operation.
-
-## Security Properties
-
-Strengths:
-
-* Durable across browser restarts
-* Durable across page reloads
-* Non-extractable through normal browser APIs
-* Fully web-native
-
-Limitations:
-
-* Active XSS can use the key
-* Browser compromise defeats the model
-* OS compromise defeats the model
-* Clearing browser data destroys the key
-
-Device-key loss is considered a recoverable event.
-
----
-
-# Host Authorization
-
-## Host ACL
-
-Each Host maintains a local authorization list.
-
-The ACL is authoritative.
-
-The Server cannot unilaterally grant access.
+A passkey authenticates a user account but does not grant access to any Host.
 
-Example:
+Source of truth: `verifyPasskeyAssertion` / `hashPasskeyPublicKey` in
+`server-lib-common/src/security/passkey.ts` — the same assertion verifier runs
+on the Server and the Host (`docs/specs/server.md`, "WebAuthn without a
+WebAuthn library").
 
-```text
-Dormouse Terminal
+## Device Keys
 
-Authorized Clients:
+Device keys establish long-lived Client identity — the capability the Host
+actually authorizes. This prevents newly-added passkeys from inheriting Host
+access, synced passkeys from automatically becoming trusted devices, and
+Server-only compromise from granting Host access.
 
-- iPhone Safari
-  Passkey A
-  Device Key 1
+Implementation: each Client generates a non-extractable ECDSA P-256 signing
+keypair with WebCrypto (`DEVICE_KEY_ALGORITHM` / `generateDeviceKeyPair` in
+`server-lib-common/src/security/deviceKey.ts`). The base64url raw public
+point is the Client identifier. Device signatures are domain-separated
+(`DEVICE_AUTH_DOMAIN`) so a signed challenge cannot be replayed in another
+protocol context. The `CryptoKey` objects are persisted directly in IndexedDB
+— never exported — by `getOrCreateDeviceKey` /
+`indexedDbDeviceKeyStore` in `lib/src/remote/client/device-key.ts` (the
+IndexedDB wrapper is DOM-dependent, so it lives in `lib`, not
+`server-lib-common`).
 
-- Android Chrome
-  Passkey A
-  Device Key 2
+Security properties — strengths: durable across browser restarts and page
+reloads, non-extractable through normal browser APIs, fully web-native.
+Limitations: active XSS can *use* the key, browser or OS compromise defeats
+the model, and clearing browser data destroys the key. Device-key loss is a
+recoverable event (see [Device Key Loss](#device-key-loss)).
 
-- MacBook Chrome
-  Passkey B
-  Device Key 3
-```
+## Host Authorization
 
-## ACL Record
+Each Host maintains a local authorization list. **The ACL is authoritative**;
+the Server cannot unilaterally grant access.
 
-Recommended fields:
+The record schema (source of truth: `HostAclRecord` / `HostAcl` in
+`server-lib-common/src/security/acl.ts`; persisted on the Host in webview
+`localStorage` via `lib/src/lib/local-json-store.ts`, `docs/specs/server.md`):
 
-```text
-host_id
-account_id
-passkey_credential_id
-passkey_public_key_hash
-device_public_key
-approved_at
-approved_by
-label
-revoked_at
+```ts
+interface HostAclRecord {
+  hostId: string;
+  accountId: string;
+  passkeyCredentialId: string;
+  /** SHA-256 of the passkey's SPKI public key, base64url. */
+  passkeyPublicKeyHash: string;
+  /** Base64url raw P-256 point — the Client's identity. */
+  devicePublicKey: string;
+  approvedAt: number;            // epoch ms
+  approvedBy: string;            // who approved locally, e.g. `host-user`
+  label: string;                 // client name shown in Host UI, e.g. `iPhone Safari`
+  revokedAt: number | null;      // null while active
+}
 ```
 
-The exact schema may evolve.
-
----
-
-# Pairing Ceremony
-
-## Purpose
-
-Establish trust between one Client and one Host.
-
-Pairing requires physical access to the Host.
-
-## Security Property
-
-A newly-added passkey is not automatically trusted.
-
-The Client must still complete Host pairing.
-
-## Flow
-
-1. Client authenticates using a passkey.
-2. Client presents its device public key.
-3. Host displays local approval UI.
-4. User approves locally on the Host.
-5. Host stores:
-
-   * passkey credential identity
-   * device public key
-   * authorization metadata
-6. Pairing completes.
-
-The Client is now trusted by that Host.
-
-No other Hosts are affected.
-
----
-
-# Connection Establishment
-
-## Requirements
-
-A connection succeeds only if:
-
-1. The passkey successfully proves fresh user presence.
+A record authorizes the *pair* of a passkey credential and a device key:
+`HostAcl` reports a miss (`passkey-not-paired`, `device-not-paired`,
+`pairing-mismatch`) unless both halves match one active record.
+
+## Pairing Ceremony
+
+Pairing establishes trust between one Client and one Host, and local approval
+on the Host is the only path into the ACL. A newly-added passkey is *not*
+automatically trusted — the Client must still complete Host pairing.
+
+What the ceremony establishes: the Client authenticates with a passkey and
+presents its device public key; the Host displays local approval UI (the
+pairing modal, same pattern as KillConfirm — `docs/specs/server.md`, Host
+side); the user approves locally on the Host; the Host writes the
+`HostAclRecord` binding the passkey credential identity to the device public
+key. The Client is now trusted by that Host and no other.
+
+**Presence for pairing is server-attested plus Host-approved.** The Server
+relays a pairing request only while the session's last server-verified
+passkey assertion is within `PAIRING_PRESENCE_WINDOW_MS` (30 seconds;
+sign-in, re-auth, and the connect handshake all refresh the stamp — `checkPair`
+in `server/src/handshake.ts`). A stale session is answered with
+`PAIRING_STALE_PRESENCE_ERROR`; the Client re-asserts with one WebAuthn prompt
+(`/api/reauth/begin` + `/api/reauth/finish`, refreshing the same session and
+relay socket) and retries. The Host does not re-verify an assertion at pairing
+time — its stronger control is the mandatory local approval, which connect
+lacks (there `authorizeConnection` verifies presence itself). Under Server
+compromise, a forged freshness stamp gets an attacker no further than the
+human staring at the approval modal.
+
+Source of truth: `PairingRequest` / `PairingTicket` / `PairingCeremony` /
+`PAIRING_PRESENCE_WINDOW_MS` in `server-lib-common/src/security/pairing.ts`
+(tickets are single-use with a `DEFAULT_PAIRING_TTL_MS` = 5-minute TTL;
+approval after expiry fails without touching the ACL — the presence window
+gates the *request*, not the approver's deliberation). The wire sequence —
+who relays what — is the pairing diagram in `docs/specs/server.md`.
+
+## Connection Establishment
+
+A connection succeeds only if **all** of the following hold:
+
+1. The passkey proves fresh user presence.
 2. The Server recognizes the account.
 3. The Host recognizes the passkey credential.
 4. The Host recognizes the device key.
-5. The Client signs a fresh Host challenge.
-
-All requirements are mandatory.
-
-## Flow
-
-1. Client requests connection.
-2. Server validates account state.
-3. Host issues a fresh challenge.
-4. Client performs WebAuthn authentication.
-5. Client signs the Host challenge using its device key.
-6. Server validates WebAuthn.
-7. Host validates:
-
-   * passkey authorization
-   * device authorization
-   * challenge signature
-8. Session is established.
-
-The Host makes the final decision.
-
----
-
-# Storage Durability
-
-## iOS
-
-### Browser Tab
-
-Durability is limited.
-
-Browser-managed storage may be removed after periods of inactivity.
-
-Do not treat browser-tab storage as permanent.
-
-### Installed PWA
-
-Preferred mode.
-
-Dormouse should encourage installation before pairing.
+5. The Client signs a fresh Host challenge with its device key.
 
-Recommended behavior:
+The Host makes the final decision — `authorizeConnection` in
+`server-lib-common/src/security/connection.ts` evaluates the assertion, the
+device signature, and the ACL against the Host's `ConnectionPolicy`
+(origin/rpId), and returns a `ConnectionDecision` regardless of what the
+Server claims to have already checked. Host challenges are 32-byte,
+single-use, TTL-bounded values from `HostChallengeIssuer`
+(`server-lib-common/src/security/challenge.ts`, default 2-minute TTL).
 
-* Generate device key only while running as an installed PWA.
-* Pair only after installation.
+One host challenge feeds both the passkey assertion and the device-key
+signature, so connecting costs the user a single biometric prompt per
+connection. The concrete sequence is the connect diagram in
+`docs/specs/server.md`.
 
-## Android
+## Storage Durability
 
-### Browser Tab
+Where the device key lives is browser-managed storage, and durability differs
+by platform:
 
-Generally durable.
+* **iOS browser tab** — durability is limited: browser-managed storage may be
+  evicted after periods of inactivity. Do not treat it as permanent.
+* **iOS installed PWA** — the preferred mode; meaningfully stronger retention.
+* **Android browser tab** — generally durable; suitable for casual use.
+* **Android installed PWA** — the preferred mode; the strongest web-only
+  durability guarantee.
 
-Suitable for casual use.
+Today Pocket generates the device key in whatever context it runs — the
+install-before-pairing guidance and storage-persistence hardening are staged
+(see [Future](#future)). Eviction is recoverable, not catastrophic: see
+[Device Key Loss](#device-key-loss).
 
-### Installed PWA
+## Device Key Loss
 
-Preferred mode.
-
-Provides the strongest web-only durability guarantees.
-
----
-
-# Installed PWA Detection
-
-Dormouse can detect whether it is currently running as an installed application:
-
-```ts
-const isInstalledRuntime =
-  window.matchMedia('(display-mode: standalone)').matches ||
-  window.matchMedia('(display-mode: fullscreen)').matches ||
-  window.matchMedia('(display-mode: minimal-ui)').matches ||
-  window.navigator.standalone === true;
-```
-
-This indicates that the application is currently running in standalone mode.
-
-It does not indicate whether the application was previously installed.
-
----
-
-# Device Key Loss
-
-Device-key loss is expected.
-
-Causes include:
-
-* Browser reset
-* Site-data clearing
-* Device replacement
-* Browser corruption
-* PWA removal
-
-Recovery process:
+Device-key loss is expected — browser reset, site-data clearing, device
+replacement, PWA removal. Recovery is a re-run of the normal flows:
 
 1. User authenticates with a passkey.
 2. Client generates a new device key.
 3. Host performs a new pairing ceremony.
-4. Previous device key may be revoked.
-
-No security compromise occurs.
+4. The previous device key's record may be revoked (`revokedAt`).
 
----
+No security compromise occurs: the lost key authorized nothing without its
+paired passkey, and the new key starts unauthorized everywhere.
 
-# Future: WebAuthn PRF
-
-WebAuthn PRF is a future enhancement.
-
-Potential uses include:
-
-* End-to-end session key derivation
-* Reduced trust in the Server
-* Stronger cryptographic channel binding
-* Offline operation
-* Noise-style authenticated key exchange
-
-PRF is not required for the core Dormouse security model.
-
-The MVP relies only on standard WebAuthn assertions and device-key authorization.
-
----
-
-# Security Guarantees
+## Security Guarantees
 
 Dormouse is designed so that:
 
@@ -411,3 +244,39 @@ Dormouse is designed so that:
 * Every access decision is ultimately made by the Host.
 
 The Host remains the final authority throughout the system.
+
+## Future
+
+### Revocation propagation
+
+The Server pushing revocations to Hosts. Today `HostAcl.revokeDevice` /
+`revokePasskey` exist but have no callers, and no relay frame carries a
+revocation — revoking is hand-editing state (`docs/specs/server.md`,
+Guardrails) and takes effect at the Host's next `authorizeConnection`.
+
+### Storage-durability hardening
+
+* Call `navigator.storage.persist()` when creating the device key, so the
+  browser treats the Client's IndexedDB as persistent rather than
+  best-effort.
+* On iOS, encourage PWA installation *before* pairing — generate the device
+  key only while running as an installed app. Detection recipe:
+
+  ```ts
+  const isInstalledRuntime =
+    window.matchMedia('(display-mode: standalone)').matches ||
+    window.matchMedia('(display-mode: fullscreen)').matches ||
+    window.matchMedia('(display-mode: minimal-ui)').matches ||
+    window.navigator.standalone === true;
+  ```
+
+  (This detects the *current* run mode only; it cannot tell whether the app
+  was previously installed.)
+
+### WebAuthn PRF
+
+A future enhancement; potential uses include end-to-end session key
+derivation, reduced trust in the Server, stronger cryptographic channel
+binding, offline operation, and a Noise-style authenticated key exchange. PRF
+is not required for the core model — the shipped system relies only on
+standard WebAuthn assertions and device-key authorization.
diff --git a/docs/specs/server.md b/docs/specs/server.md
index 4e441f56..09843ae2 100644
--- a/docs/specs/server.md
+++ b/docs/specs/server.md
@@ -1,31 +1,32 @@
-# Server (selfhost POC)
+# Server (selfhost)
+
+> See `docs/specs/glossary.md` for Session / Pane / Surface vocabulary; this spec uses it for what the relay exposes.
 
 The coordinating Server from the
 [remote security model](./remote-security-model.md), in its selfhost mode, cut
 down to the smallest thing that completes this loop:
 
 > Run the server with a setup password. Visit it, present the password, create
-> a passkey. Pair your phone with your laptop's Dormouse Terminal. Move a
-> running terminal session from the laptop to the phone.
+> a passkey. Pair your phone with your laptop's Dormouse Terminal. Pick up a
+> running terminal session from the laptop on the phone.
 
 One Node process (Hono, as the `server` package already is). No database. No
 browser-surface support — **terminal-only**. The heavy lifting is already
 done: every security primitive lives in `server-lib-common`, and the terminal
 UI lives in `lib`/`standalone`.
 
-## POC guardrails
+## Guardrails
 
 * One account (`accountId: "owner"`), created once with the setup password.
-* Terminal surfaces only; the remote-api v1 subset minus browser surfaces.
+* Terminal surfaces only — exactly remote-api.md's **protocol-v1** (browser
+  remoting is staged in that spec's `## Future`).
 * Revocation is editing a JSON file by hand; no management UI.
 * A dropped WebSocket is handled by reloading the page / reconnecting the
   host. No resume protocol.
 * Everything transient (challenges, sessions, relay state) is in memory; a
   server restart just means everyone reconnects.
 
----
-
-# Configuration
+## Configuration
 
 | Env var                   | Meaning                                                    |
 | ------------------------- | ---------------------------------------------------------- |
@@ -38,6 +39,7 @@ WebAuthn requires a secure context: `localhost` works for development; for a
 real phone, put the server behind TLS (`tailscale serve` is the intended
 selfhost path, any reverse proxy works). The server itself always speaks
 plain HTTP.
+
 `DORMOUSE_ORIGIN` is parsed once and normalized with `URL.origin`; WebAuthn
 clientData checks, passkey assertion verification, and the Host enrollment
 policy all use that normalized origin.
@@ -57,7 +59,7 @@ SaaS sources; localhost and the rest of the policy are untouched. The default
 is deliberately not internet-wide — widening it is an explicit, per-build
 opt-in.
 
-# State files
+## State files
 
 ```
 $DORMOUSE_STATE_DIR/
@@ -68,12 +70,10 @@ $DORMOUSE_STATE_DIR/
 ```
 
 That is the entire persistent state. The Host's ACL is not here — it lives on
-the Host (platform `saveState`), which is the whole point of the security
-model.
-
----
+the Host, in webview `localStorage` (`lib/src/lib/local-json-store.ts`),
+which is the whole point of the security model.
 
-# WebAuthn without a WebAuthn library
+## WebAuthn without a WebAuthn library
 
 Two facts keep the server dependency-free:
 
@@ -90,6 +90,7 @@ Two facts keep the server dependency-free:
 
 Server-issued challenges (registration, sign-in) reuse `HostChallengeIssuer`
 — it is a generic single-use/TTL challenge store despite the name.
+
 Before a challenge is consumed, the server canonicalizes the browser's
 `clientDataJSON.challenge` by decoded base64url bytes, so padded browser
 serializations redeem the issued challenge without weakening single-use replay
@@ -98,30 +99,28 @@ protection.
 This also makes the server fully testable without a browser: the
 `SimAuthenticator` harness in `server-lib-common` produces real assertions,
 so `node --test` can drive setup → pairing → connect end to end via
-`app.request()` and a pair of in-process WebSockets.
-
----
+`app.request()` and real WebSockets against an ephemeral-port server.
 
-# HTTP API
+## HTTP API
 
 | Route                            | Auth           | Does                                              |
 | -------------------------------- | -------------- | ------------------------------------------------- |
 | `GET /*`                         | —              | Serves the Pocket web app (static build of `lib`'s pocket entry) |
-| `POST /api/setup/begin`          | setup password | `{ challenge }` for registration; rejects if the account already has a passkey (add more by re-presenting the password) |
+| `POST /api/setup/begin`          | setup password | `{ challenge }` for registration. Only the password gates it — re-presenting the password adds another passkey to the account |
 | `POST /api/setup/finish`         | setup password | `{ credentialId, publicKey, clientDataJSON }` → creates/updates `account.json` |
 | `POST /api/signin/begin`         | —              | `{ challenge }` for sign-in                        |
 | `POST /api/signin/finish`        | —              | full assertion → verified → `{ sessionToken }` (random, in-memory, hours-scale TTL) |
+| `POST /api/reauth/begin`         | session token  | `{ challenge }` to re-assert presence on the current session |
+| `POST /api/reauth/finish`        | session token  | full assertion → verified (same checks as sign-in) → refreshes the session's presence stamp; the token and relay socket are kept |
 | `POST /api/host/enroll`          | setup password | `{ label }` → `{ hostId, hostToken, origin, rpId }`; appends to `hosts.json` |
 | `GET /api/hosts`                 | session token  | Enrolled hosts + whether each is currently connected |
 | `GET /ws/host`                   | host token     | The Host's relay socket                            |
 | `GET /ws/client`                 | session token  | A Client's relay socket                            |
 
 The setup password is compared in constant time with a small fixed delay on
-failure; that is the extent of POC hardening.
+failure; that is the extent of the hardening today.
 
----
-
-# Relay
+## Relay
 
 The server routes JSON envelopes between client sockets and host sockets
 (`@hono/node-ws`). Before a session is authorized it only forwards an
@@ -134,16 +133,18 @@ re-establish an old session.
 When a Client socket binds to a different Host, the relay sends `client-gone`
 to the previous live Host before replacing the binding, so Host-side pairing UI,
 remote-api sessions, and watchers are disposed immediately.
+
 Client-originated `pair` and `connect2` frames are also rechecked after their
 async validation work: if the Client disconnected, rebound, or the Host socket
 was replaced while validation was pending, the stale result is dropped.
+
 For `connect2`, the server remembers the last Host challenge it relayed to a
 Client with a relay-local expiry derived from the server's observation time
 (`DEFAULT_CHALLENGE_TTL_MS`). The Host's `expiresAt` is still forwarded to the
 Client, but the server never compares its own clock to that Host wall-clock
 timestamp.
 
-## Pairing (phone ↔ laptop, first time)
+### Pairing (phone ↔ laptop, first time)
 
 ```
 phone                        server                        host (laptop)
@@ -156,13 +157,21 @@ phone                        server                        host (laptop)
 
 The `pair-request` carries the `PairingRequest` shape from `server-lib-common`
 (`accountId`, `passkeyCredentialId`, `passkeyPublicKeyHash`,
-`devicePublicKey`, `requestedLabel`). The server checks the session's
-credential matches and rejects malformed requests before relaying; the Host runs
-`PairingCeremony` and only local approval writes the ACL. A malformed
-`PairingRequest` is answered locally with `pair-result approved:false` and is
-never shown in the Host approval UI.
-
-## Connect (every session)
+`devicePublicKey`, `requestedLabel`). The server checks the request's
+credential is a registered passkey of the account (and that its public-key
+hash matches the stored key) and rejects malformed requests before relaying —
+an account-level check; the `/ws/client` session is not bound to one
+credential. The server also requires **fresh presence**: the session's last
+verified assertion (sign-in, re-auth, or a connect handshake) must be within
+`PAIRING_PRESENCE_WINDOW_MS`, else the request is answered locally with
+`pair-result approved:false, error: 'stale-presence'` and the Pocket client
+re-asserts via `/api/reauth/*` (one biometric prompt) and retries
+(`docs/specs/remote-security-model.md`, Pairing Ceremony). The Host runs
+`PairingCeremony` and only local approval writes the ACL. A malformed or
+stale `PairingRequest` is answered locally and is never shown in the Host
+approval UI.
+
+### Connect (every session)
 
 ```
 phone                        server                        host
@@ -184,23 +193,23 @@ per connection. The server verifies the assertion against the stored passkey
 and drops the request on failure; the Host's `authorizeConnection` remains the
 final authority regardless of what the server claims to have checked.
 
-## After authorization: remote-api v1, terminal-only
+### After authorization: remote-api protocol-v1
 
-Exactly the v1 scope of [remote-api.md](./remote-api.md) minus browser
-surfaces: `hello`, `directory.watch` (snapshot-only), one `surface.attach`
-(attach-is-the-resize), `terminal.data`/`semantic`/`resize`/`closed` out,
-`terminal.write`/`terminal.resize` in.
+Exactly the protocol-v1 scope of [remote-api.md](./remote-api.md)
+(terminal-only): `hello`, `directory.watch` (snapshot-only), one
+`surface.attach` (attach-is-the-resize), `terminal.data`/`terminal.closed`
+out, `terminal.write`/`terminal.resize` in. (Host→client size-authority and
+semantic events are staged in remote-api.md `## Future`.)
 
----
-
-# Host side (`lib` + `standalone`)
+## Host side (`lib` + `standalone`)
 
 A `remote-host` module in `lib`, active in standalone:
 
 * **Enrollment** (settings UI, once): server URL + setup password →
   `POST /api/host/enroll` → persist `{ serverUrl, hostId, hostToken, origin,
-  rpId }` via the platform adapter; open and maintain `GET /ws/host`.
-* **Security**: `HostAcl` (persisted with `saveState`/`getState` as
+  rpId }` in webview `localStorage` (`local-json-store.ts` — deliberately no
+  platform-adapter dependency); open and maintain `GET /ws/host`.
+* **Security**: `HostAcl` (persisted to `localStorage` as
   `records()`/`fromRecords`), `HostChallengeIssuer`, `PairingCeremony`, and
   `authorizeConnection` — all straight from `server-lib-common`, running in
   the webview.
@@ -213,10 +222,11 @@ A `remote-host` module in `lib`, active in standalone:
   hasTODO — all already tracked); `surface.attach` resizes the PTY through
   the existing resize path and subscribes to its data stream;
   `terminal.write` feeds the existing input path.
-* **Tethering**: while a remote session holds size authority, the local pane
-  greys out to "tethering to \<label\>"; local interaction reclaims it.
+* **Size authority**: last-attach-wins holds at the PTY level through the
+  existing resize path. The "tethering to \<label\>" grey-out display on the
+  local pane is staged — see remote-api.md `## Future`.
 
-# Pocket side (phone)
+## Pocket side (phone)
 
 Served by the server, built from `lib`:
 
@@ -229,39 +239,24 @@ Served by the server, built from `lib`:
 * Picker renders `directory.snapshot`; tapping a pane attaches with the
   phone's cols/rows and reuses the existing mobile terminal UI (xterm).
 
----
-
-# Build order — five slices, each testable
+## Testing
 
-1. **Accounts & passkeys.** Setup/sign-in endpoints + `account.json` +
-   static-serving stub. Tests: `node --test` with `SimAuthenticator` against
-   `app.request()` — register, sign in, wrong password, replayed challenge,
-   wrong origin. Manual: create a real passkey at `localhost:3000`.
-2. **Relay & host enrollment.** `hosts.json`, host/client sockets, envelope
-   routing, presence in `GET /api/hosts`. Tests: two in-process WebSockets
-   echo through the relay; token/session rejection.
-3. **Security handshake over the relay.** A headless fake host (a Node script
-   wiring `server-lib-common` exactly as the harness's `SimHost` does) +
-   `SimAuthenticator` client: full pairing ceremony and connect through the
-   real server, plus the deny cases (unpaired device, revoked record, replayed
-   challenge). Still no browser anywhere.
-4. **Standalone host module.** Enrollment settings, approval modal, ACL
-   persistence, host socket. Dogfood: pair a second browser profile (or the
-   phone) against your real standalone app and watch the modal + ACL.
-5. **Terminal bridge + Pocket terminal view.** Directory, attach-is-the-resize,
-   write/resize, tether display, mobile terminal UI hookup. Dogfood — the
-   actual goal: pick up a running session from your laptop on your phone.
+The security and relay layers are covered without a browser: `node --test`
+drives setup → pairing → connect end to end through the real server —
+`app.request()` for HTTP routes, real WebSockets against an ephemeral-port
+server for the relay — using `SimAuthenticator` (from `server-lib-common`)
+plus the `FakeHost` harness in `server/test/harness/fake-host.mjs` (register,
+sign-in, wrong password, replayed challenge, wrong origin, plus relay routing
+and token/session rejection). Revoked-record denial is covered at the unit
+level in `server-lib-common`'s own tests, not through the relay.
+`server/scripts/fake-host.mjs` is a manual dev stand-in built on the same
+`FakeHost` class (see Running it below). Browser-dependent layers — the
+standalone host module and the Pocket terminal view — are dogfooded rather
+than automated.
 
-Slices 1–3 are pure Node with full automated coverage; browsers only enter at
-slice 4. After slice 5 the POC is in daily-use territory, and everything
-after that (browser surfaces, in-flight replay, thumbnails, WebRTC) is
-already staged in remote-api.md as additive follow-ups.
+## Running it
 
----
-
-# Running the POC
-
-All five slices are implemented. To test end to end:
+The loop at the top of this spec is implemented end to end. To test:
 
 **1. Server + Pocket** (one terminal):
 
@@ -285,15 +280,22 @@ Enrollment persists in localStorage; on later launches the host connects by
 itself. (`status()` / `clearEnrollment()` on the same object.) For a headless
 stand-in host instead:
 `DORMOUSE_SETUP_PASSWORD=hunter2 node server/scripts/fake-host.mjs http://localhost:3000`
-(auto-approves pairing; answers `hello` only — no real terminals).
+(auto-approves pairing and serves the same synthetic echo terminals as the
+test harness — it instantiates `FakeHost` from
+`server/test/harness/fake-host.mjs`; only the auto-approval and logging
+differ).
 
 **3. Phone** (or any other browser profile): open the server origin →
 First-time setup (password + label) creates the passkey and signs you in →
 Hosts → **Pair** → approve in the modal on the laptop → **Connect** (one
 biometric prompt) → pick a pane → type.
 
-POC limitations to know about: pair/connect only works from the browser that
+Limitations to know about: pair/connect only works from the browser that
 registered the passkey (the passkey public key is stored client-side at
 registration); clearing site data destroys the device key → re-pair, per the
 security model; a dropped WebSocket sends you back to the Hosts view —
 reconnect by tapping Connect again.
+
+Everything past this loop (browser surfaces, in-flight replay, thumbnails,
+the tethering display, WebRTC) is staged in remote-api.md `## Future` as
+additive follow-ups.
diff --git a/docs/specs/shortcuts.md b/docs/specs/shortcuts.md
index a85c0ba8..8689c1b8 100644
--- a/docs/specs/shortcuts.md
+++ b/docs/specs/shortcuts.md
@@ -1,11 +1,11 @@
 # Keyboard Shortcuts
 
-Complete reference for Dormouse's keyboard shortcuts. Shortcuts are grouped by the mode/context in which they apply.
+Quick-reference index of Dormouse's keyboard shortcuts, grouped by the mode/context in which they apply. This file is a derived convenience table: `docs/specs/layout.md` owns command-mode dispatch and mode switching, and `docs/specs/mouse-and-clipboard.md` owns selection/copy/paste. Change behavior there first, then keep this table in sync.
 
-Dormouse has two modes:
+Dormouse has two modes (`docs/specs/glossary.md` owns the names):
 
-- **Command mode** — keys drive pane and workspace layout. (Internally `command`; this reference previously called it "Workspace mode," renamed to free the word "Workspace" for the pane-group container — see `docs/specs/glossary.md`.)
-- **Terminal mode** (a.k.a. "passthrough" mode) — keys go to the running program, except copy/paste and the mode-switch gesture.
+- **Command mode** — keys drive pane and workspace layout.
+- **Passthrough mode** — keys go to the running program, except copy/paste and the mode-switch gesture.
 
 In the VS Code extension host, selected workbench chords are mirrored: the terminal receives the key, and Dormouse also runs the matching VS Code workbench command. See [the VS Code host spec](vscode.md) for the exact allowlist.
 
@@ -13,9 +13,9 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 
 | Key | Action | Description |
 |-----|--------|-------------|
-| Left ⌘ → Right ⌘ (within 500 ms) | Toggle mode | Tap left Command, then right Command within 500 ms to swap between command and terminal mode. |
-| Left Shift → Right Shift (within 500 ms) | Toggle mode | Same as above, but with the Shift keys. |
-| `Enter` (command) | Enter terminal mode | Switch the selected pane into passthrough (or reattach a minimized door). |
+| Left ⌘ → Right ⌘ (within 500 ms) | Enter command mode | Tap left Command, then right Command within 500 ms while in passthrough. The gesture only exits passthrough — it does nothing in command mode. |
+| Left Shift → Right Shift (within 500 ms) | Enter command mode | Same as above, but with the Shift keys. |
+| `Enter` (command) | Enter passthrough mode | Switch the selected pane into passthrough (or reattach a minimized door). Clicking a pane also enters passthrough. |
 
 ## Pane actions (command mode)
 
@@ -25,7 +25,7 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 | `-` or `"` | Split top/bottom | Split the selected pane into two stacked panes. |
 | `z` | Toggle zoom | Fullscreen the selected pane, or return to the normal layout. |
 | `m` or `d` | Minimize / reattach | Minimize the selected pane to the baseboard, or reattach a minimized door. |
-| `k` or `x` | Kill | Kill the selected pane or door. Prompts for a random character to confirm. |
+| `k` or `x` | Kill | Kill the selected pane or door. Prompts for a random character to confirm; untouched (never-typed-in) panes and doors are killed immediately without the prompt. |
 | `,` | Rename | Enter rename mode for the selected pane's title. |
 | `a` | Toggle alert | Dismiss or toggle the bell alert for the selected pane. Meaningful only for a terminal Surface — a browser surface has no bell to ring (`docs/specs/glossary.md`). |
 | `t` | Toggle todo | Toggle the TODO marker on or off for the selected pane's Surface. Works on any Surface — a terminal Session or a browser surface. |
@@ -35,11 +35,7 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 | Key | Action | Description |
 |-----|--------|-------------|
 | `↑` / `↓` / `←` / `→` | Move selection | Move selection to the adjacent pane or door. Press the opposite direction to return. |
-| `⌘↑` / `⌘↓` / `⌘←` / `⌘→` (macOS)<br>`Ctrl`+arrows (others) | Swap terminals | Swap terminal sessions between two panes — layout and titles swap; selection follows the terminal. |
-
-## Workspaces (command mode)
-
-> Workspace switch / create / close / rename shortcuts are being finalized in the Storybook UI pass, following the tmux *window* bindings the rest of the keymap mirrors. They are listed here once bound. See `docs/specs/layout.md` and `docs/specs/glossary.md` for the Workspace model.
+| `⌘`+arrows or `Ctrl`+arrows | Swap terminals | Swap terminal sessions between two panes — layout and titles swap; selection follows the terminal. Either modifier works on every platform. |
 
 ## Selection & drag
 
@@ -55,10 +51,9 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 |-----|--------|-------------|
 | `⌘C` (macOS) / `Ctrl+C` (others) | Copy raw | Copy selected text as-is, without rewrapping. Requires a finalized selection. |
 | `⌘⇧C` (macOS) / `Ctrl+Shift+C` (others) | Copy rewrapped | Copy selected text with rewrapping for single-line display. |
-| `⌘V` / `⌘⇧V` (macOS) | Paste | Paste clipboard contents into the terminal. |
-| `Ctrl+V` / `Ctrl+Shift+V` (others) | Paste | Paste clipboard contents into the terminal. |
+| `⌘V` / `⌘⇧V` / `Ctrl+V` / `Ctrl+Shift+V` | Paste | Paste clipboard contents into the terminal. The Ctrl variants are intercepted on every platform, macOS included. |
 
-On macOS, `Ctrl+C` / `Ctrl+V` pass through to the running program; only the ⌘-prefixed variants are intercepted.
+On macOS, `Ctrl+C` passes through to the running program (only `⌘C` copies); `Ctrl+V` is intercepted for paste everywhere — use the shell's `quoted-insert` (`Ctrl+Q`) to send a literal `0x16` (`docs/specs/mouse-and-clipboard.md` §8.3).
 
 ## Dialogs & prompts
 
@@ -76,3 +71,7 @@ On macOS, `Ctrl+C` / `Ctrl+V` pass through to the running program; only the ⌘-
 - Primary keyboard handler: `lib/src/components/wall/use-wall-keyboard.ts` (command-mode key dispatch, mode toggle, dialog key handlers)
 - Selection popup copy bindings: `lib/src/components/SelectionPopup.tsx`
 - Alt-to-toggle-block selection: `lib/src/lib/terminal-mouse-router.ts`
+
+## Future
+
+Workspace switch / create / close / rename shortcuts (command mode) are staged with the workspaces rollout — see `docs/specs/layout.md` `## Future` (workspaces-rollout). They follow the tmux *window* bindings the rest of the keymap mirrors and are listed here once bound.
diff --git a/docs/specs/standalone.md b/docs/specs/standalone.md
new file mode 100644
index 00000000..2c48b75b
--- /dev/null
+++ b/docs/specs/standalone.md
@@ -0,0 +1,203 @@
+# Dormouse Standalone (Tauri) Integration Spec
+
+> See `docs/specs/glossary.md` for Session / Surface / Pane / Door vocabulary. See `docs/specs/transport.md` for the PTY lifecycle, message protocol, persisted-session types, and adapter-agnostic invariants the standalone app shares with the VS Code and fake adapters. This spec covers the standalone-specific layer: the Tauri window, the Rust ↔ sidecar bridge, the AppBar, persistence at the adapter boundary, shutdown ordering, logging, and the build/dev workflow.
+
+## Architecture
+
+```
+Tauri app process (Rust — standalone/src-tauri/src/lib.rs)
+├── WebView (Vite frontend — standalone/src/)
+│   ├── main.tsx           — bootstrap: platform init, theme restore, resumeOrRestore, updater
+│   ├── AppBar.tsx         — draggable titlebar: shell dropdown, theme picker, window controls
+│   ├── tauri-adapter.ts   — TauriAdapter (PlatformAdapter over Tauri invoke/events)
+│   ├── updater.ts         — auto-update state machine (docs/specs/auto-update.md)
+│   └── browser-sidecar-{host,adapter}.ts — browser-dev harness (docs/specs/transport.md)
+└── Node sidecar (standalone/sidecar/main.js — spawned by Rust at setup)
+    ├── pty-core.js            — shared PTY manager (docs/specs/transport.md; also used by the VS Code pty-host)
+    ├── dor-control-server.js  — dor CLI control socket (docs/specs/dor-cli.md)
+    ├── iframe-proxy.cjs       — bundled from lib/src/host/iframe-proxy.ts (docs/specs/dor-browser.md)
+    ├── agent-browser-host.cjs — bundled from lib/src/host/agent-browser-host.ts (docs/specs/dor-browser.md)
+    ├── clipboard-ops.js       — OS clipboard: paste-read tiers for macOS/Linux (Windows reads go native in Rust); agent-browser clipboard writes on all platforms (docs/specs/mouse-and-clipboard.md §8.6, docs/specs/dor-browser.md)
+    └── shell-integration/     — injected shell hook scripts (docs/specs/terminal-escapes.md)
+```
+
+The Rust layer is deliberately thin: it spawns and supervises the sidecar,
+bridges the webview to it, and owns the OS-integration edges (window events,
+file drop, dock icon, logging). Everything with real logic — PTYs, the dor
+control server, the iframe proxy, the agent-browser host — runs in the Node
+sidecar, sharing the same modules the VS Code host runs
+(`build-sidecar-proxy.mjs` bundles the `lib/src/host/` sources into the
+sidecar's `.cjs` copies, so the two hosts cannot drift).
+
+## Boot sequence
+
+Source of truth: `standalone/src/main.tsx` (`bootstrap()`).
+
+1. Pick the platform: `BrowserSidecarAdapter` when `VITE_DORMOUSE_BROWSER_DEV_HOST`
+   is set (the browser-dev harness, `docs/specs/transport.md`), otherwise
+   `TauriAdapter`.
+2. `setPlatform(platform)` then `await platform.init()` **before**
+   `resumeOrRestore` — init registers the event listeners that resume replay
+   arrives on.
+3. `initAlertStateReceiver()`, `restoreActiveTheme()` (`docs/specs/theme.md`).
+4. `getAvailableShells()` seeds the AppBar dropdown and
+   `setDefaultShellOpts` (the default-shell slot used by split/spawn/restore
+   paths, `docs/specs/layout.md`).
+5. `resumeOrRestore(platform)` runs the priority-based recovery from
+   `docs/specs/transport.md`.
+6. `startUpdateCheck()` (`docs/specs/auto-update.md`), then render `AppBar` +
+   `App` with `enableRemoteHost` (activating the remote Host module —
+   enrollment, pairing modal, relay socket; `docs/specs/server.md` Host side),
+   threading `<ConnectedUpdateBanner />` through the `baseboardNotice` slot.
+
+## Rust ↔ sidecar bridge
+
+Source of truth: `standalone/src-tauri/src/lib.rs` (`SidecarState`, the
+`#[tauri::command]` set, `resolve_sidecar_path`) and
+`standalone/sidecar/main.js` (the dispatch table).
+
+The sidecar speaks JSON-lines over stdio: commands in on stdin, events out on
+stdout (stdout is reserved for the protocol — sidecar diagnostics go to
+stderr, which Rust appends to the log file). Webview → Rust is the Tauri
+`invoke` command set — `pty_spawn` / `pty_write` / `pty_resize` / `pty_kill` /
+`pty_request_init` / `pty_get_cwd` / `pty_get_open_ports` /
+`pty_get_scrollback` / `get_available_shells`, `dor_control_response`,
+`iframe_create_proxy_url`, the `agent_browser_*` family, the `clipboard`
+readers, `read_update_log`, and `kill_sidecar_now` — each a thin forwarder to
+the corresponding sidecar message, with two carve-outs: on Windows the
+clipboard readers skip the sidecar and read the Win32 clipboard natively
+(`clipboard_win.rs`; behavior in `docs/specs/mouse-and-clipboard.md` §8.6),
+and `agent_browser_screenshot` receives a temp-file *path* from the sidecar
+and reads the bytes in Rust so images never ride the JSON-lines pipe shared
+with PTY traffic (`docs/specs/dor-browser.md`). Request/response commands block on the
+sidecar's reply with a timeout; `OPEN_PORT_TIMEOUT_MS` in `lib.rs` mirrors the
+constant in `lib/src/lib/platform/types.ts` and the two must stay in sync.
+Sidecar events (`pty:*`, dor control requests, async results) are emitted to
+the webview, where `TauriAdapter` converts dor control requests into the
+`dormouse:control-request` CustomEvent that `Wall` handles
+(`docs/specs/dor-cli.md`, Host Plumbing — including the sidecar env:
+`DORMOUSE_NODE`, `DORMOUSE_CLI_*`, `DORMOUSE_CONTROL_*`).
+
+`resolve_sidecar_path` strips Windows `\\?\` verbatim prefixes from
+`resource_dir()` once at the boundary so every derived path is plain — the
+reasons live in `docs/specs/dor-cli.md` (Bundling And PATH).
+
+## Sidecar lifecycle
+
+Source of truth: `standalone/sidecar/main.js`.
+
+Shutdown (`sidecar:shutdown` message, stdin EOF, or SIGTERM) is idempotent and
+ordered:
+
+1. `agentBrowser.closePoppedOut()` bounded by a 1.5s race, so quitting never
+   orphans a headed Chrome window and a hung agent-browser cannot wedge the
+   exit (mirrors the VS Code host's `deactivate()`; `docs/specs/dor-browser.md`).
+2. Close the dor control socket.
+3. `mgr.killAll()` (all PTYs), then `process.exit(0)`.
+
+A parent-PID watchdog polls every 2s and self-triggers shutdown if the Tauri
+process disappears: stdin EOF is not always delivered when the host is
+force-killed (especially on Windows), and an orphaned sidecar would hold
+`conpty.node`/`conpty.dll` open and block the NSIS installer
+(`docs/specs/auto-update.md`, Sidecar teardown on Windows).
+
+Host-side ordering: the window-close path is owned by the updater's close
+handler (`docs/specs/auto-update.md` — post-install markers, and on Windows a
+synchronous `kill_sidecar_now` that waits for the process to actually exit
+before `install()`). Independently, Tauri's `RunEvent::Exit` runs
+`shutdown_sidecar_and_wait` so a plain quit also tears the sidecar down.
+
+## AppBar
+
+Source of truth: `standalone/src/AppBar.tsx`.
+
+The AppBar is the draggable titlebar region and carries, left to right: the
+shell controls, the theme picker (`docs/specs/theme.md`), and the window
+controls (minimize / maximize / close via `@tauri-apps/api/window`, with
+window-focus tracking dimming the bar). The shell controls are:
+
+- **`[+]`** — spawns a new terminal with the currently selected shell
+  (dispatches the `dormouse:new-terminal` CustomEvent that `Wall` listens
+  for; the VS Code equivalent is the `dormouse:newTerminal` postMessage in
+  `docs/specs/transport.md`).
+- **Shell dropdown** — lists `getAvailableShells()`; picking a different
+  shell updates `setDefaultShellOpts` and dispatches `dormouse:new-terminal`
+  with `replaceUntouched: true, announce: true`, so an untouched selected
+  terminal is replaced in place (`docs/specs/layout.md`, Shell selection
+  replacement).
+
+The workspace strip lands here when the workspaces rollout reaches stage 3 —
+`docs/specs/layout.md` `## Future` (workspaces-rollout).
+
+## Persistence
+
+`TauriAdapter.saveState` / `getState` store the session blob in webview
+`localStorage` under `TauriAdapter.STATE_KEY`, routed through
+`lib/src/lib/window-persistence.ts` (`loadSessionState` / `saveSessionState`)
+— the standalone adapter boundary where the `PersistedWindow` wrapping lives,
+identity-passthrough while the workspaces flag is off
+(`docs/specs/transport.md`, Workspace/Window containers). Theme selection
+persists separately through the theme store (`docs/specs/theme.md`).
+
+## File drop
+
+The `WindowEvent::DragDrop` handler in `lib.rs` routes dropped paths to the
+focused pane as escaped, space-joined paste input — but it is **inert
+today**: `tauri.conf.json` sets `dragDropEnabled: false` so HTML5
+drag-and-drop inside the webview (dockview pane dragging) keeps working
+(tauri-apps/tauri#14373, dormouse#38). Behavior and status are specified in
+`docs/specs/mouse-and-clipboard.md` (§8.7 Drag-to-Paste).
+
+## Logging
+
+Windows release builds use the GUI subsystem, so nothing streams to a
+launching terminal. The Rust backend appends sidecar stdout/stderr lines and
+its own diagnostics to a log file: `%LOCALAPPDATA%\Dormouse Terminal\dormouse.log`
+on Windows, `$TMPDIR/dormouse.log` elsewhere, overridable via
+`DORMOUSE_LOG_FILE` (`docs/specs/deploy.md`, Packaged app logging). The
+updater debug modal reads it back through `read_update_log`.
+
+## Build and development
+
+Source of truth: `standalone/package.json` (package scripts),
+`standalone/src-tauri/tauri.conf.json` (`build`, `bundle.resources`), and the
+root `package.json` for the `dev:standalone*` orchestration.
+
+- `stage` = `stage:dor-cli` (build + stage the dor CLI, `docs/specs/dor-cli.md`)
+  plus `stage:sidecar-proxy` (`build-sidecar-proxy.mjs` bundles the
+  `lib/src/host/` sources into the sidecar `.cjs` files).
+- The `tauri` script runs `standalone/scripts/tauri.mjs`, which rewrites the
+  webview CSP via `standalone/scripts/csp.mjs` when the
+  `DORMOUSE_REMOTE_CONNECT_SRC` build-time override for self-host relay
+  origins is set (`docs/specs/server.md`, Host webview CSP), then delegates
+  to the Tauri CLI.
+- The Tauri bundle ships the whole sidecar via the `../sidecar/**/*` resources
+  glob — including node-pty's prebuilds + bundled ConPTY and the
+  shell-integration scripts (`docs/specs/terminal-escapes.md`).
+- **Dev caveat:** `tauri.conf.json`'s `beforeDevCommand` is `pnpm dev` (Vite
+  only). Frontend edits hot-reload, but changes to the sidecar, the staged dor
+  CLI, or the bundled `lib/src/host/` sources need a manual re-stage and app
+  restart — the dev loop does not watch them.
+- `pnpm dev:standalone:ab` runs the sidecar + webview in a normal browser via
+  the browser-dev harness instead of the Tauri WebView
+  (`docs/specs/transport.md`, Standalone browser-dev harness).
+
+## Files
+
+| File | Role |
+|------|------|
+| `standalone/src-tauri/src/lib.rs` | Rust backend: sidecar spawn/supervision, invoke commands, event forwarding, file drop, logging, dock icon, exit teardown |
+| `standalone/src-tauri/src/clipboard_win.rs` | Native Win32 clipboard reads on Windows (owned by `docs/specs/mouse-and-clipboard.md`) |
+| `standalone/scripts/tauri.mjs`, `csp.mjs` | Tauri CLI wrapper assembling the webview CSP (`DORMOUSE_REMOTE_CONNECT_SRC`) |
+| `standalone/src-tauri/tauri.conf.json` | Window config, dev/build commands, sidecar resources glob, updater config |
+| `standalone/src/main.tsx` | Webview bootstrap (boot sequence above) |
+| `standalone/src/AppBar.tsx` | Titlebar: shell dropdown, theme picker, window controls |
+| `standalone/src/tauri-adapter.ts` | `TauriAdapter`: PlatformAdapter over Tauri invoke/events, localStorage persistence, control-request dispatch |
+| `standalone/src/updater.ts`, `UpdateBanner.tsx`, `UpdateDebugModal.tsx` | Auto-update (owned by `docs/specs/auto-update.md`) |
+| `standalone/src/browser-sidecar-host.ts`, `browser-sidecar-adapter.ts` | Browser-dev harness (owned by `docs/specs/transport.md`) |
+| `standalone/sidecar/main.js` | Sidecar entry: stdio JSON-lines dispatch, shutdown ordering, parent-PID watchdog |
+| `standalone/sidecar/pty-core.js` | Shared PTY manager (owned by `docs/specs/transport.md`) |
+| `standalone/sidecar/dor-control-server.js` | dor CLI control socket (owned by `docs/specs/dor-cli.md`) |
+| `standalone/sidecar/clipboard-ops.js` | OS clipboard tiers (owned by `docs/specs/mouse-and-clipboard.md`) |
+| `standalone/scripts/build-sidecar-proxy.mjs` | Bundles `lib/src/host/` into the sidecar `.cjs` copies |
+| `standalone/scripts/dev-agent-browser.mjs` | `dev:standalone:ab` entry (owned by `docs/specs/transport.md`) |
diff --git a/docs/specs/terminal-escapes.md b/docs/specs/terminal-escapes.md
index 846dc678..3cac48fe 100644
--- a/docs/specs/terminal-escapes.md
+++ b/docs/specs/terminal-escapes.md
@@ -61,6 +61,8 @@ Unknown non-iTerm2 OSC families pass through to xterm.js unchanged so xterm.js c
 | `OSC 777 ; notify ; <title> ; <body> ST` | rxvt/WezTerm notification | [alert.md](alert.md#osc-777) |
 | `OSC 1337 ; CurrentDir=<cwd> ST` | CWD (iTerm2 compatibility) | [terminal-state.md](terminal-state.md#supported-osc-inputs) |
 
+(`BEL` is not itself an OSC; it has a row here because a standalone `BEL` is parsed and stripped at the same PTY data boundary as the OSCs.)
+
 Some sequences are dual-purpose. The notification rows for `OSC 9 ; <message> ST`, `OSC 99` (`p=title`/`p=body`), and `OSC 777 ; notify` also feed the title-candidate channel in `terminal-state.md` — see its [Title candidate diagnostics](terminal-state.md#supported-osc-inputs) table. Only the OSC 9 *message* form can become a header/door label; OSC 99 and OSC 777 candidates are stored for the diagnostic popup only. The OSC 9 *progress* form (`OSC 9 ; 4`) carries no text and never contributes a title candidate.
 
 #### OSC color queries on Windows require the bundled ConPTY
@@ -120,7 +122,7 @@ Environment for spawned PTYs:
 |---|---|
 | `TERM_PROGRAM` | `iTerm.app` |
 | `TERM_PROGRAM_VERSION` | Dormouse's chosen iTerm2 compatibility version, not the package version |
-| `LC_TERMINAL` | `iTerm2` only if needed by real-world shell integrations |
+| `LC_TERMINAL` | `iTerm2` — set unconditionally on every spawned PTY (some real-world shell integrations key off it rather than `TERM_PROGRAM`) |
 | `LC_TERMINAL_VERSION` | same compatibility version as `TERM_PROGRAM_VERSION` |
 | `COLORTERM` | `truecolor` — advertise 24-bit color, which xterm.js renders. The PTY is spawned as `xterm-256color` with no other depth hint, so env-sniffing tools (e.g. `supports-color`) would otherwise assume 256/ANSI-16 and quantize RGB output to the nearest palette entry. Truecolor-aware TUIs (Codex's composer pill, syntax highlighters) then render smooth RGB. Windows Terminal is recognized as truecolor via `WT_SESSION`; Dormouse isn't, so it advertises `COLORTERM` explicitly. This is a color-*depth* signal, **independent** of the light/dark *background* detection (OSC color queries above) that drives those TUIs' theme choice. Not iTerm2-identity-specific. |
 
@@ -142,7 +144,6 @@ A binary on `PATH` only has to be **found**, so it injects via one env var (`DOR
 |---|---|---|---|
 | zsh | `ZDOTDIR` → our dotfiles chain to the user's, then install `precmd`/`preexec` hooks | env (as reliable as the `PATH` prepend) | User's real `ZDOTDIR` is passed through as `USER_ZDOTDIR`; our `.zshrc` hands `ZDOTDIR` back so `.zlogin` and child shells are unaffected. |
 | bash | `--init-file` → our script replicates login-profile sourcing, then installs a `DEBUG`-trap / `PROMPT_COMMAND` hook | shellArgs | `--init-file` and login mode are mutually exclusive, so Dormouse drops `-l` and the script sources `/etc/profile` + the user's profile itself. Injected whenever the launch args are *only* interactive/login flags (`-i`/`-l`/`--login`) — so Git Bash, launched with `--login -i`, is covered too; a specific invocation like `-c <cmd>` is left untouched. Written for bash 3.2 (macOS system bash): no `PS0`, no array `PROMPT_COMMAND`. The `E` command line is the first simple command of a pipeline (a `DEBUG`-trap limitation); boundaries and exit codes stay exact. |
-| fish | `XDG_DATA_DIRS` → fish auto-sources `*/fish/vendor_conf.d/*.fish` | env | (not yet implemented) |
 | PowerShell | `-Command ". '<script>'"` → the dot-sourced script wraps the user's `prompt` and PSReadLine's `PSConsoleHostReadLine` (covers `pwsh` and Windows `powershell.exe`) | shellArgs | `-NoProfile` is *not* passed, so the user's profile loads and defines their prompt before we wrap it. Injected for any **interactive** launch: a bare REPL gets `-NoExit -Command ". '<script>'"`, and a launch that already runs a startup command — e.g. the VS "Developer PowerShell" (`-NoExit -Command "& { Import-Module … }"`) — gets our dot-source *appended* to that command, so its environment is set up first and our wrapper installs after it. Non-interactive one-offs (a `-Command`/`-File`/`-EncodedCommand` without `-NoExit`) are left untouched. PowerShell has no `preexec`, so `E`/`C` (command line + start) are emitted by wrapping `PSConsoleHostReadLine`, which runs just before a submitted command executes — so the running command shows immediately, like bash/zsh. The matching `D` (finish, exit code from `$?`/`$LASTEXITCODE`) is emitted from the next `prompt` render. If PSReadLine is absent, the whole `E`/`C`/`D` triple is reported from the next prompt instead (command line from history): boundaries and exit codes stay exact, but the running command isn't shown until it finishes. |
 | WSL | `wsl.exe -d <distro> -- sh -c <detector>` → the detector execs the distro's bash with our `--init-file` (the Windows bash script, referenced via its `/mnt/...` path) | shellArgs | Windows-side injection can't reach the Linux shell, so we append a command. The detector reads the login shell from `/etc/passwd`: it steps aside for an explicit zsh/fish login shell, execs bash+integration when bash exists (covering bash and an empty detection — the safe default), and falls back to the login shell only when bash is absent (e.g. Alpine). bash is the only WSL shell integrated for now. Assumes the default `/mnt` automount root. |
 | cmd.exe | no per-command hook exists | — | Never gets real OSC 633; always uses the keystroke fallback below. |
@@ -151,9 +152,7 @@ Injection is wired in `resolveSpawnConfig` (`standalone/sidecar/pty-core.js`) an
 
 ### Keystroke fallback
 
-When injection isn't possible (cmd.exe, an unknown shell, or scripts not present) or simply doesn't take, Dormouse falls back to its keystroke heuristic: it watches what the user types and synthesizes `commandStart{source:'user_input'}` (see `recordTerminalUserInput` in `lib/src/lib/terminal-state-store.ts` and [terminal-state.md](terminal-state.md)). This fallback has no real exit codes and only a best-effort idle transition.
-
-The two are mutually exclusive **per pane**: the first genuine OSC 633/133 boundary a pane sees (a real prompt-start lands before the first command is typed) flips that pane to "OSC-driven" and retires the keystroke heuristic for it, so the two never both report the same command. Prompt boundaries that the heuristic *itself* synthesizes are flagged so they don't trip this detection. This is what makes the fallback fire "only if injection fails."
+When injection isn't possible (cmd.exe, an unknown shell, or scripts not present) or simply doesn't take, Dormouse falls back to its keystroke heuristic: it reads the submitted command off the rendered prompt line and synthesizes `commandStart{source:'user_input'}`. This fallback has no real exit codes and only a best-effort idle transition. The fallback rules — prompt-shape learning, submit parsing, and the per-pane promotion that retires the heuristic on the first authentic OSC boundary (which is what makes it fire "only if injection fails") — are owned by [terminal-state.md](terminal-state.md#keystroke-fallback).
 
 > Packaging caveat: the zsh scripts are dotfiles (`.zshrc`, `.zshenv`, `.zprofile`). Confirm the VS Code `.vsix` actually includes `dist/shell-integration/.z*` — if a packaging step strips dotfiles, VS Code silently degrades to the keystroke fallback.
 
@@ -186,3 +185,7 @@ This list is non-exhaustive. Any iTerm2-compatibility OSC family that Dormouse c
 - kitty desktop notifications (OSC 99): https://sw.kovidgoyal.net/kitty/desktop-notifications/
 - kitty keyboard protocol: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
 - WezTerm escape sequences (OSC 777): https://wezterm.org/escape-sequences.html
+
+## Future
+
+- **fish shell integration** — inject via `XDG_DATA_DIRS`: fish auto-sources `*/fish/vendor_conf.d/*.fish`, so the integration ships as a vendor conf file (env channel, as reliable as the `PATH` prepend). Until it lands, fish panes use the keystroke fallback above.
diff --git a/docs/specs/terminal-state.md b/docs/specs/terminal-state.md
index 2b950de0..e692435e 100644
--- a/docs/specs/terminal-state.md
+++ b/docs/specs/terminal-state.md
@@ -132,7 +132,7 @@ CWD:
 
 Non-OSC CWD sources:
 
-- `process` — adapter polled the PTY's process for its working directory. Used when no OSC source has reported recently.
+- `process` — adapter polled the PTY's process for its working directory. Applied only while no OSC source has ever reported for the pane (see CWD precedence below — the rule is source-based, not time-based).
 - `manual` — caller seeded the CWD directly (e.g., session restore from saved state, or a known spawn directory). Produced by `cwdFromManualPath()`.
 
 Command lifecycle:
@@ -175,21 +175,36 @@ The parser accepts both BEL and ST terminators and handles split chunks. Support
 
 `reduceTerminalState(state, event)` is the only state transition surface.
 
+### OSC-driven events
+
 - `cwd` replaces the latest session CWD.
 - `promptStart` sets `{ kind: "prompt" }`, clears `currentCommand`, and clears `pendingCommandLine`. Any pending input that was not yet consumed by a `commandStart` is dropped — a fresh prompt is the unambiguous signal that no command is in flight.
 - `promptEnd` sets `{ kind: "editing" }`, clears `currentCommand`, and clears `pendingCommandLine` for the same reason.
 - `commandLine` stores `pendingCommandLine`.
-- For shells without OSC 133/633 integration, the command is read from what is on screen rather than reconstructed from keystrokes. The store learns a cwd-invariant prompt **shape** — the prompt's trailing terminator character (`%`, `$`, `#`, `>`, `❯`, `➜`, `λ`) plus how many times that character already appears earlier in the prompt — from every detected idle prompt, including the shell's first prompt at spawn. On submit (an Enter that is not inside a bracketed paste) it reads the cursor's rendered logical line (`prompt + command`, soft-wrapped rows joined and bounded at the cursor column so zsh-autosuggestions ghost text is excluded) and splits the command off after the prompt's terminator, trimming leading whitespace. A non-empty result emits `commandLine` + `commandStart(source: "user_input")` immediately, so the active command shows even without command-start integration. Because it parses the rendered line, the title is correct regardless of how the command arrived — typed, history-recalled, or pasted — and independent of the race between shell output and idle detection. A prompt with no recognized terminator yields no shape, hence no title, rather than a wrong one.
-- The prompt shape survives across commands (it does not reset on `promptStart`/`promptEnd`/`commandStart`) and is pre-seeded from restored scrollback on session restore / VS Code panel reopen, so the first command after a reconnect — when the live shell will not re-emit its prompt — is still titled. Seeding is learn-only and fires no prompt transition.
-- The input fallback resolves the current Session id from the PTY id before recording submit input or prompt-looking output, so drag-to-swap moves the fallback state — including the learned prompt shape — with the visible pane.
 - `commandStart` creates `currentCommand`, snapshots `cwdAtStart`, uses `event.startedAt` when present, clears `pendingCommandLine`, and sets `{ kind: "running" }`.
 - `commandFinish` moves `currentCommand` to `lastCommand`, stores `finishedAt`/`exitCode`, snapshots the latest in-run OSC 0/2/9 title into `lastCommand.finalTerminalTitle` (titles older than `startedAt` or younger than `finishedAt` are excluded), clears `currentCommand`, and sets `{ kind: "finished", exitCode }`.
 - `title` updates `title` and the per-source entry in `titleCandidates`. Later OSC title events do not erase earlier user, shell, or notification channel candidates from other sources.
 - A later prompt signal moves the pane out of `finished`. If a command was started from `user_input` and no explicit `commandFinish` arrived, the prompt signal also clears `currentCommand` so the header returns to `<idle>`.
-- Visible output that looks like a returned shell prompt always refreshes the learned prompt shape, but only synthesizes the idle prompt transition when `currentCommand.source === "user_input"`. This keeps shape learning available for all shells while scoping the finish/start synthesis to shells that do not emit command finish/start OSCs (OSC-tracked shells drive their own boundaries).
-- **Per-pane keystroke retirement.** The keystroke fallback and real OSC 633/133 integration are mutually exclusive per pane. The first authentic OSC boundary a pane emits (`promptStart`/`promptEnd`/`commandFinish` always, or a `commandStart` whose source is an OSC boundary — not `user_input`) promotes the pane to **OSC-driven**, after which the keystroke path stops recording: `recordTerminalUserInput` early-returns and no further `user_input` `commandStart`/`commandLine` is synthesized, so injected shells never double-count. The synthesized prompt markers the fallback itself emits are passed with a `keystrokeHeuristic` flag so they do **not** trigger promotion — otherwise the fallback would retire the very path that emits them. The flag is per-pane runtime state, seeded fresh and cleared on pane reset/removal; it is not persisted.
 
-CWD precedence:
+### Keystroke fallback
+
+For shells without OSC 133/633 integration, the command is read from what is on screen rather than reconstructed from keystrokes. This subsection is the single home for the fallback rules; `docs/specs/terminal-escapes.md` (Shell-integration injection → Keystroke fallback) defers here.
+
+```
+idle prompt rendered ──learn──▶ prompt shape (terminator char + repeat count)
+Enter (not bracketed paste) + known shape ──parse rendered line──▶ commandLine + commandStart(user_input)
+prompt-looking output while a user_input command runs ──▶ synthesized finish → prompt
+first authentic OSC boundary ──▶ pane promoted to OSC-driven; fallback retired
+```
+
+- **Prompt-shape learning.** The store learns a cwd-invariant prompt **shape** — the prompt's trailing terminator character (`%`, `$`, `#`, `>`, `❯`, `➜`, `λ`) plus how many times that character already appears earlier in the prompt — from every detected idle prompt, including the shell's first prompt at spawn. A prompt with no recognized terminator yields no shape, hence no title, rather than a wrong one.
+- **Submit parsing.** On submit (an Enter that is not inside a bracketed paste) it reads the cursor's rendered logical line (`prompt + command`, soft-wrapped rows joined and bounded at the cursor column so zsh-autosuggestions ghost text is excluded) and splits the command off after the prompt's terminator, trimming leading whitespace. A non-empty result emits `commandLine` + `commandStart(source: "user_input")` immediately, so the active command shows even without command-start integration. Because it parses the rendered line, the title is correct regardless of how the command arrived — typed, history-recalled, or pasted — and independent of the race between shell output and idle detection.
+- **Shape survival and reconnect seeding.** The prompt shape survives across commands (it does not reset on `promptStart`/`promptEnd`/`commandStart`) and is pre-seeded from restored scrollback on session restore / VS Code panel reopen, so the first command after a reconnect — when the live shell will not re-emit its prompt — is still titled. Seeding is learn-only and fires no prompt transition.
+- **Swap safety.** The fallback resolves the current Session id from the PTY id before recording submit input or prompt-looking output, so drag-to-swap moves the fallback state — including the learned prompt shape — with the visible pane.
+- **Synthesized idle transitions.** Visible output that looks like a returned shell prompt always refreshes the learned prompt shape, but only synthesizes the idle prompt transition when `currentCommand.source === "user_input"`. This keeps shape learning available for all shells while scoping the finish/start synthesis to shells that do not emit command finish/start OSCs (OSC-tracked shells drive their own boundaries).
+- **Per-pane retirement.** The keystroke fallback and real OSC 633/133 integration are mutually exclusive per pane. The first authentic OSC boundary a pane emits (`promptStart`/`promptEnd`/`commandFinish` always, or a `commandStart` whose source is an OSC boundary — not `user_input`) promotes the pane to **OSC-driven**, after which the keystroke path stops recording: `recordTerminalUserInput` early-returns and no further `user_input` `commandStart`/`commandLine` is synthesized, so injected shells never double-count. The synthesized prompt markers the fallback itself emits are passed with a `keystrokeHeuristic` flag so they do **not** trigger promotion — otherwise the fallback would retire the very path that emits them. The flag is per-pane runtime state, seeded fresh and cleared on pane reset/removal; it is not persisted.
+
+### CWD precedence
 
 - OSC-sourced CWD (`osc7`, `osc9_9`, `osc633`, `osc1337`) wins over everything. Once an OSC has reported a directory, only a later OSC can replace it.
 - Process-polled CWD (`process`) updates only when the current source is `null`, `manual`, or another `process` reading. It fills the gap when the shell does not emit OSC 7 / 633;P / 1337 / 9;9.
@@ -243,3 +258,11 @@ Source of truth: `statusBucket()` in `lib/src/lib/terminal-state.ts` projects th
 
 Directory group keys use `cwdIdentity(cwd)` so remote hosts and Windows/POSIX path kinds remain distinct.
 Windows UNC display labels keep `\\server\share\` as the path root and do not repeat the server/share in the trailing path segments.
+
+## Files
+
+| File | Role |
+|------|------|
+| `lib/src/lib/terminal-state.ts` | Pure semantic model: types, reducer, CWD precedence, header derivation, grouping |
+| `lib/src/lib/terminal-state-store.ts` | React-facing store; PTY-id → pane-id resolution; keystroke fallback recording (`recordTerminalUserInput`) |
+| `lib/src/lib/terminal-protocol.ts` | Semantic OSC parsing that emits `TerminalSemanticEvent` (parsing location rules in `docs/specs/terminal-escapes.md`) |
diff --git a/docs/specs/theme.md b/docs/specs/theme.md
index d598c55a..dd740cdb 100644
--- a/docs/specs/theme.md
+++ b/docs/specs/theme.md
@@ -1,5 +1,7 @@
 # Theme Spec
 
+> See `docs/specs/glossary.md` for Pane / Door vocabulary used in the surface hierarchy below.
+
 Dormouse's theme contract is intentionally small: render the terminal chrome
 with VSCode-appropriate surfaces, and render terminal content with
 theme-appropriate xterm.js colors.
@@ -18,7 +20,9 @@ designed to read clearly inside the sidebar host area. Use bg-only chrome for
 panes and doors; do not add borders to make the hierarchy work.
 
 Source of truth: `lib/src/theme.css` defines token→VSCode-key bindings. The
-runtime-picked `--color-door-bg` and `--color-focus-ring` are computed by
+runtime-picked `--color-door-bg` / `--color-door-fg`, `--color-focus-ring`, and
+the per-surface alarm tints
+(`--color-alarm-vs-{header-active,header-inactive,door}`) are computed by
 `computeDynamicPalette()` in `lib/src/lib/themes/dynamic-palette.ts` using OKLab
 distance/chroma helpers from `lib/src/lib/color-contrast.ts`;
 `useDynamicPalette()` in `lib/src/lib/themes/use-dynamic-palette.ts` publishes
@@ -30,10 +34,18 @@ the chosen variables on `document.body`. Public theme helpers are exported from
   `--color-app-bg`.
 - Focus ring prefers a chromatic `focusBorder`, then a chromatic active-header
   background, then the highest contrast fallback.
+- Each alarm tint is plain white or black, picked by the OKLab lightness of
+  the background the ringing bell sits on (`pickAlarmColor`): the active
+  header, the inactive header, or the door. The `--vscode-terminal-ansiYellow`
+  binding in `theme.css` is only the pre-publish baseline. Because
+  `--color-alarm-vs-door` derives from `--color-door-bg`, which the same pass
+  computes, the first pass after a theme change reads the previous door bg —
+  the `MutationObserver` re-fires on the pass's own `body.style` write, so the
+  next pass corrects it.
 - Header-internal text and buttons inherit the header foreground. Do not add
   `text-muted` inside headers; use `hover:bg-current/10` for neutral hover
-  feedback. Semantic exceptions are `text-warning` for ringing alerts and
-  error styling for destructive actions.
+  feedback. Semantic exceptions are the `text-alarm-vs-*` tint for ringing
+  alerts and error styling for destructive actions.
 
 High-contrast VSCode themes may make bg-only chrome look flatter than normal.
 That is accepted; terminal content still uses the theme's terminal palette.
@@ -66,10 +78,12 @@ state saying a theme is active while xterm.js sees fallback colors.
 `--vscode-*` variables also live there. Keep the parallel `@theme`
 declarations so Tailwind can generate utility classes, but treat the body-level
 declarations as the runtime source of truth.
-Dynamic palette tokens (`--color-door-bg`, `--color-door-fg`, and
-`--color-focus-ring`) also have body-level baseline bindings matching the
-`@theme` declarations, so direct CSS-var consumers such as the mobile gesture
-SVG render visibly before `useDynamicPalette()` publishes refined values.
+Dynamic palette tokens (`--color-door-bg`, `--color-door-fg`,
+`--color-focus-ring`, and the three `--color-alarm-vs-*` tokens) also have
+body-level baseline bindings matching the `@theme` declarations, so direct
+CSS-var consumers such as the mobile gesture SVG — and a ringing bell before
+the first dynamic pass — render visibly before `useDynamicPalette()` publishes
+refined values.
 
 `theme.css` must not contain hardcoded color defaults or `var(..., fallback)`
 chains. Runtime hosts plus the shared resolver are responsible for providing
@@ -104,9 +118,10 @@ the VSCode terminal defaults before those values are read:
 - The 16 ANSI colors from `terminal.ansiBlack` through
   `terminal.ansiBrightWhite`.
 
-The `terminal-theme.ts` body/html `MutationObserver` re-reads these values
-when the body class or style changes, so applying a theme updates existing
-terminals. `terminal-registry.ts` remains the public facade for callers.
+The `terminal-theme.ts` `MutationObserver` re-reads these values on class or
+style mutations of `body` or `html`, so applying a theme updates existing
+terminals. Adapters use the `terminal-theme.ts` API directly — it is not
+re-exported through the `terminal-registry` facade.
 
 ## Theme data
 
@@ -132,10 +147,10 @@ defines Storybook's default simulated host theme, with fallback to the first
 bundled theme so a renamed or removed bundle cannot leave stories without theme
 vars.
 The Storybook preview decorator also computes and publishes the dynamic palette
-vars (`--color-door-bg`, `--color-door-fg`, `--color-focus-ring`) through the
+vars (door pair, focus ring, and the `--color-alarm-vs-*` tints) through the
 shared `computeDynamicPalette()` helper, matching the runtime
-`useDynamicPalette()` hook for stories that render doors, baseboards, or focus
-rings outside a full Wall instance.
+`useDynamicPalette()` hook for stories that render doors, baseboards, focus
+rings, or ringing bells outside a full Wall instance.
 
 ## Theme debugger
 
@@ -180,7 +195,9 @@ When changing theme behavior:
 - Keep xterm.js terminal colors sourced from `--vscode-terminal-*` variables,
   not from Dormouse chrome tokens.
 - Keep debugger dynamic-pick reporting and runtime dynamic-palette picks sharing
-  `pickDoorPair()` and `pickFocusRing()`; do not fork those rules in UI code.
+  `pickDoorPair()` and `pickFocusRing()`, and keep the alarm tint on
+  `pickAlarmColor()` — do not fork those rules in UI code. (The debugger does
+  not report alarm picks today.)
 - Do not add hardcoded color defaults or CSS variable fallback chains to
   `lib/src/theme.css`; fix the theme data or runtime host instead.
 - Avoid reintroducing a pass-through `--mt-*` layer or one-off tokens for tabs,
diff --git a/docs/specs/transport.md b/docs/specs/transport.md
index bc8988e1..0f40c883 100644
--- a/docs/specs/transport.md
+++ b/docs/specs/transport.md
@@ -93,7 +93,7 @@ Non-obvious message contracts:
 
 VS Code-only workbench chord mirroring uses `dormouse:runWorkbenchCommand` from webview to host. The host validates the requested command against the allowlist in `lib/src/lib/vscode-keybindings.ts` (see [the VS Code host spec](vscode.md)) before calling `vscode.commands.executeCommand`; generic command execution over the webview boundary is not allowed.
 
-Workspace union status (`docs/specs/alert.md`) adds no new message. Standalone computes it in-webview — the app bar's workspace strip and the Walls share one webview, so the strip reads the activity store and browser-surface state directly. VS Code computes only the host-visible native-chrome projection from the module-level `AlertManager` filtered to each router's `ownedPtyIds`, then writes it onto native chrome; the host already receives every PTY's alert state, but it does not receive browser-surface TODO without a future webview→host Surface-state message (`docs/specs/vscode.md`).
+Workspace union status (`docs/specs/alert.md`) adds no new message. Standalone computes it in-webview — the app bar's workspace strip and the Walls share one webview, so the strip reads the activity store and browser-surface state directly. VS Code computes only the host-visible native-chrome projection from the module-level `AlertManager` filtered to each router's `ownedPtyIds`, then writes it onto native chrome; the host already receives every PTY's alert state, but it does not receive browser-surface TODO (the webview→host Surface-state message is staged — see `docs/specs/vscode.md` `## Future`).
 
 | Direction | Message | Source type | Contract |
 | --- | --- | --- | --- |
@@ -108,15 +108,15 @@ The OSC parsing/stripping rules that produce `pty:data` and `terminal:semanticEv
 
 ## Persisted session types
 
-Source of truth: `lib/src/lib/session-types.ts` defines the persisted-session interfaces (`PersistedSession` v3, `PersistedPane` — now carrying `surfaceType` — `PersistedAlertState`, `PersistedDoor`, and the stage-2b `PersistedWorkspace` / `PersistedWindow`) and their migrations.
+Source of truth: `lib/src/lib/session-types.ts` defines the persisted-session interfaces (`PersistedSession` v3, `PersistedPane` — now carrying `surfaceType` — `PersistedAlertState`, `PersistedDoor`, and the container types `PersistedWorkspace` / `PersistedWindow`) and their migrations.
 
-**Surface kinds in the snapshot (stage 2a, implemented).** Each `PersistedPane` records a `surfaceType` (`docs/specs/glossary.md`): `'terminal'` (the default, omitted from the row to keep terminal snapshots byte-identical) or `'browser'`. This is the discriminator that routes restore/resume. `restoreSession` skips terminal restoration for a browser pane, so it no longer mints a stray PTY + xterm for each browser pane id (`session-restore.ts`); the resume plan keeps browser panes (and minimized browser doors) even though they have no live PTY, so the saved `layout`'s panel set still matches and is not discarded (`reconnect.ts`). A browser pane rebuilds from the dockview `layout` blob (visible) or `PersistedDoor.params` (minimized); its render params (`renderMode`, `url`, agent-browser `session`) live there, not in `PersistedPane` — `surfaceType` alone is enough to route restore. A pane lacking `surfaceType` reads as `'terminal'`, so older snapshots migrate transparently.
+**Surface kinds in the snapshot.** Each `PersistedPane` records a `surfaceType` (`docs/specs/glossary.md`): `'terminal'` (the default, omitted from the row to keep terminal snapshots byte-identical) or `'browser'`. This is the discriminator that routes restore/resume. `restoreSession` skips terminal restoration for a browser pane, so it no longer mints a stray PTY + xterm for each browser pane id (`session-restore.ts`); the resume plan keeps browser panes (and minimized browser doors) even though they have no live PTY, so the saved `layout`'s panel set still matches and is not discarded (`reconnect.ts`). A browser pane rebuilds from the dockview `layout` blob (visible) or `PersistedDoor.params` (minimized); its render params (`renderMode`, `url`, agent-browser `session`) live there, not in `PersistedPane` — `surfaceType` alone is enough to route restore. A pane lacking `surfaceType` reads as `'terminal'`, so older snapshots migrate transparently.
 
-**Workspace/Window containers (stage 2b — implemented, dormant behind the `dormouse.flags.workspaces` flag).** A **Workspace** persists as a `PersistedWorkspace`: a `WorkspaceId`, a user-facing `name`, and the Workspace's `PersistedSession` (its panes, doors, and dockview layout). The standalone Window persists as a `PersistedWindow`: the ordered list of `PersistedWorkspace` plus the active `WorkspaceId`. Source of truth: `PersistedWorkspace` / `PersistedWindow` / `readPersistedWindow` / `replaceActiveSession` in `session-types.ts`. VS Code does **not** use `PersistedWindow`; each webview persists exactly one `PersistedSession` — its single Workspace — through the same per-surface state API as today (`workspaceState` for the view, `vscode.setState()` per editor panel; see `docs/specs/vscode.md`).
+**Workspace/Window containers (implemented, dormant behind the `dormouse.flags.workspaces` flag; rollout ledger in `docs/specs/layout.md` `## Future`).** A **Workspace** persists as a `PersistedWorkspace`: a `WorkspaceId`, a user-facing `name`, and the Workspace's `PersistedSession` (its panes, doors, and dockview layout). The standalone Window persists as a `PersistedWindow`: the ordered list of `PersistedWorkspace` plus the active `WorkspaceId`. Source of truth: `PersistedWorkspace` / `PersistedWindow` / `readPersistedWindow` / `replaceActiveSession` in `session-types.ts`. VS Code does **not** use `PersistedWindow`; each webview persists exactly one `PersistedSession` — its single Workspace — through the same per-surface state API as today (`workspaceState` for the view, `vscode.setState()` per editor panel; see `docs/specs/vscode.md`).
 
-The wrapping lives at the **standalone adapter boundary**, not in the shared save/restore code: `lib/src/lib/window-persistence.ts` (`activeSessionFromStored` / `storedValueForSession`) translates between the host's stored top-level blob and the bare `PersistedSession` that `reconnect.ts` / `session-save.ts` operate on, and `tauri-adapter.ts` / `browser-sidecar-adapter.ts` route `getState` / `saveState` through it. With the flag **off** (the default) these are identity passthroughs — the stored blob stays a bare `PersistedSession` and behavior is byte-identical to stage 2a. With the flag **on**, load returns the active Workspace's session and save merges it back into the active slot, preserving the other Workspaces.
+The wrapping lives at the **standalone adapter boundary**, not in the shared save/restore code: `lib/src/lib/window-persistence.ts` (`activeSessionFromStored` / `storedValueForSession`) translates between the host's stored top-level blob and the bare `PersistedSession` that `reconnect.ts` / `session-save.ts` operate on, and `tauri-adapter.ts` / `browser-sidecar-adapter.ts` route `getState` / `saveState` through it. With the flag **off** (the default) these are identity passthroughs — the stored blob stays a bare `PersistedSession` and behavior is byte-identical to pre-workspace behavior. With the flag **on**, load returns the active Workspace's session and save merges it back into the active slot, preserving the other Workspaces.
 
-Versioning and migration (stage 2b): the standalone top-level snapshot is a `PersistedWindow` (its own `version: 1`) wrapping v3 sessions. A pre-workspace bare `PersistedSession` (any version) migrates on read to a single `PersistedWorkspace` named `Workspace 1`, marked active, inside a `PersistedWindow` (`readPersistedWindow`); unreadable inner sessions are dropped and a dangling `activeWorkspaceId` is repaired to the first Workspace. A host that hands back a bare `PersistedSession` (VS Code, or legacy/flag-off standalone storage) is read as one Workspace. Migrations stay additive — older shapes keep flowing v1→v2→v3→(window) without losing panes, doors, alert state, or surface kind.
+Versioning and migration: the standalone top-level snapshot is a `PersistedWindow` (its own `version: 1`) wrapping v3 sessions. A pre-workspace bare `PersistedSession` (any version) migrates on read to a single `PersistedWorkspace` named `Workspace 1`, marked active, inside a `PersistedWindow` (`readPersistedWindow`); unreadable inner sessions are dropped and a dangling `activeWorkspaceId` is repaired to the first Workspace. A host that hands back a bare `PersistedSession` (VS Code, or legacy/flag-off standalone storage) is read as one Workspace. Migrations stay additive — older shapes keep flowing v1→v2→v3→(window) without losing panes, doors, alert state, or surface kind.
 
 Every saved-session entry point must pass through `readPersistedSession()`. That reader accepts both the canonical parsed object and a JSON-stringified session blob before validating/migrating; this covers host state APIs that may hand back the inner serialized JSON string.
 
diff --git a/docs/specs/tutorial.md b/docs/specs/tutorial.md
index 31ecf6ab..3a72334b 100644
--- a/docs/specs/tutorial.md
+++ b/docs/specs/tutorial.md
@@ -1,5 +1,7 @@
 # Playground Tutorial
 
+> See `docs/specs/glossary.md` for Session / Pane vocabulary. This spec uses it for the playground's pane layout and detection wiring.
+
 The website playground has canonical device-specific routes:
 
 - `/playground` is a client-side dispatcher. It picks Pocket for coarse-pointer devices or narrow viewports and Desktop otherwise, then replaces the history entry with `/playground/desktop` or `/playground/pocket`. The exact media query lives in `website/src/lib/playground-routing.ts`.
@@ -42,7 +44,7 @@ Every pane gets a `TutorialShell` input handler via `PlaygroundShellRegistry`; t
 
 ## Menu and navigation behavior
 
-The desktop runner opens at a top-level menu; Pocket starts inside Gesture navigation and Esc returns to its menu. Selecting a section drills into its item list, showing `[N/M complete]` per section. Inside a section, items render `✓` (green, complete), `●` (yellow active marker — intentionally static so runner re-renders don't feed the activity monitor), or `·` (dim, later). Esc / `q` / Ctrl+C pops back one screen (section → menu → exit); re-running `tut` re-enters. `Reset progress` returns to the profile's initial screen.
+The desktop runner opens at a top-level menu; Pocket starts inside Gesture navigation and Esc returns to its menu. Selecting a section drills into its item list, showing `[N/M complete]` per section. Inside a section, items render `✓` (green, complete), `●` (yellow active marker — intentionally static so runner re-renders don't feed the activity monitor), or `·` (dim, later). Esc / `q` pop back one screen (section → menu → exit); Ctrl+C exits the runner immediately from any screen; re-running `tut` re-enters. `Reset progress` returns to the profile's initial screen.
 
 Below the sections the menu lists `Starred on GitHub` (persisted separately, calls `onOpenGithub`) and `🐭 FlappyTerm 🐭`. Flappy is `[LOCKED N/M]` until all section checklist items are complete (the star and Flappy rows don't count toward `N/M`), then shows `[High score: N]` and unlocks a runner-local mini-game. The game-over screen cross-links the other surface: desktop `p` → `onOpenPocket`, Pocket `n` → `onNotifyPocket`. The page wires these callbacks (and their URLs) in `PocketTerminalExperience.tsx` and the desktop playground page.
 
@@ -57,6 +59,24 @@ Two keys are intercepted by `TutRunner` while a specific section is open — the
 
 Pocket reuses `cp-select`/`cp-raw`/`cp-rewrap` but drops `cp-override`: in Select mode it auto-overrides mouse capture for every mounted pane whose TUI is capturing the mouse, so it never asks the user to click the cursor icon. It also renders a non-counted live prompt above the checklist that reflects the current touch mode (yellow while Select is inactive, green once active); it is not stored or checkmarked.
 
+## Fake shell behavior
+
+Every playground pane gets a `TutorialShell` (see Architecture); a fake shell
+is all the playground needs. Minimum useful behavior:
+
+* Echo typed characters and maintain a command-line buffer; Enter submits,
+  Backspace edits.
+* Up/Down arrows recall command history at the shell prompt; Escape, Tab, and Left/Right are no-ops at the base prompt (full-screen runners like `ascii-splash` give them behavior).
+* When a fake full-screen app such as `ascii-splash`, `splash`, `changelog`, or
+  `tut` is running, `Ctrl+C` sends `\x03` to that app; if the app exits, the
+  terminal returns to the fake shell prompt instead of restarting the app.
+* New panes created from the wall get the same fake shell behavior and prompt
+  as regular `/playground/desktop` panes.
+
+Example commands: `help`, `clear`, `echo hello`, `ascii-splash`, `changelog`,
+`tut`. The shell only needs enough behavior to exercise the tutorial and the
+mobile controls.
+
 ## Storage
 
 `TutorialState` persists to `localStorage`. Unknown ids in a stored payload are filtered on load, so renaming an id is a one-way reset for that item. Both profiles share the completion key; profile totals count only that profile's items.
@@ -80,7 +100,7 @@ These exist in `dormouse-lib` (or `MobileTerminalUi`) specifically so the browse
 
 ## Theme Picker
 
-Implemented in `dormouse-lib/lib/themes` and `dormouse-lib/components/ThemePicker`. Bundled themes are GitHub variants only; users can install more from OpenVSX via the dropdown footer (`Install theme from OpenVSX`). Installed rows have an `X` delete control (requires browser confirmation); deleting the active installed theme falls back to the first bundled theme.
+Implemented in `dormouse-lib/lib/themes` and `dormouse-lib/components/ThemePicker`. Bundled themes are a small built-in VS Code set (`bundled.json`: Dark/Light Visual Studio, Monokai, Quiet Light, Red, Kimbie Dark, Abyss, and Selenized variants); users can install more from OpenVSX via the dropdown footer (`Install theme from OpenVSX`). Installed rows have an `X` delete control (requires browser confirmation); deleting the active installed theme falls back to the page's `defaultThemeId` (Kimbie Dark on the playground/Pocket pages), with the first bundled theme as last resort.
 
 The picker is labeled `Theme:` and appears on `/playground/desktop` (inside the theme-aware `SiteHeader`), `/playground/pocket` mobile (floating over the terminal), and the desktop Pocket page (standalone appbar variant). `/pocket` redirects before rendering one.
 
@@ -92,26 +112,28 @@ The Playground is the primary dogfood surface for `docs/specs/mouse-and-clipboar
 
 | Spec § | Feature | Status | Why |
 |---|---|---|---|
-| §1 | Mouse icon visible when program requests reporting | ✅ | `ascii-splash` emits `\x1b[?1000h` / `?1002h` / `?1003h` / `?1006h`. |
-| §2 | Temporary/permanent override, banner, Make-permanent / Cancel | ✅ | Use the header mouse icon while `ascii-splash` is active. |
-| §3.1–§3.3 | Drag, Alt-block shape, "Hold Alt" hint | ✅ | Works on any visible text. |
-| §3.3 | "Press e to select the full URL/path" hint | ❌ | No qualifying tokens in the live scenarios. |
-| §3.4 | Pure-scroll follows, cancel-on-change, cancel-on-resize | ⚠️ | `ascii-splash` makes cancel-on-change and resize observable; scenarios too short for pure-scroll. |
-| §3.5 | Scrollback-origin / cross-boundary drags | ⚠️ | Scrollback too short to exercise. |
-| §3.6 | Keyboard routing during drag | ✅ | With override active on `ascii-splash`, drag-time keyboard consumption is observable. |
-| §3.7 | Popup on mouse-up, new-drag-replaces | ✅ | Any selection. |
-| §4.1.1 | Copy Raw | ✅ | Any selection. |
-| §4.1.2 | Copy Rewrapped (paragraph unwrap) | ✅ | `ChangelogRunner` renders wrapped item lines that exercise the rewrap path. |
-| §4.2 | Cmd+C / Cmd+Shift+C | ✅ | Any selection. |
-| §4.3 | Esc / click-outside dismiss | ✅ | Any selection popup. |
-| §5 | Smart-extension (URL / abs path / rel path / Windows path / error location) | ❌ | No matching tokens in the scenarios. |
-| §5.3 | Press `e` to extend | ❌ | Blocked on §5 coverage. |
-| §8.2 | Cmd+V / Cmd+Shift+V / Ctrl+V / Ctrl+Shift+V paste | ⚠️ | Fires and writes to the fake PTY, but `TutorialShell.handleInput` echoes char-by-char and ignores bracketed-paste markers. |
-| §8.5 | Bracketed paste wraps `\e[200~ … \e[201~` | ❌ | No scenario emits `\x1b[?2004h`, so `bracketedPaste` stays `false`. |
-
-`§3.6` auto-scroll and `§8.7` right-click paste are deferred in the implementation itself — not Playground gaps.
+| [§1](mouse-and-clipboard.md#1-the-mouse-icon-header-indicator) | Mouse icon visible when program requests reporting | ✅ | `ascii-splash` emits `\x1b[?1000h` / `?1002h` / `?1003h` / `?1006h`. |
+| [§2](mouse-and-clipboard.md#2-override-state) | Temporary/permanent override, banner, Make-permanent / Cancel | ✅ | Use the header mouse icon while `ascii-splash` is active. |
+| [§3.1–§3.3](mouse-and-clipboard.md#31-initiating-a-selection) | Drag, Alt-block shape, "Hold Alt" hint | ✅ | Works on any visible text. |
+| [§3.3](mouse-and-clipboard.md#33-selection-hint-text) | "Press e to select the full URL/path" hint | ❌ | No qualifying tokens in the live scenarios. |
+| [§3.4](mouse-and-clipboard.md#34-selection-follows-content) | Pure-scroll follows, cancel-on-change, cancel-on-resize | ⚠️ | `ascii-splash` makes cancel-on-change and resize observable; scenarios too short for pure-scroll. |
+| [§3.5](mouse-and-clipboard.md#35-selection-in-the-live-region-vs-scrollback) | Scrollback-origin / cross-boundary drags | ⚠️ | Scrollback too short to exercise. |
+| [§3.6](mouse-and-clipboard.md#36-during-a-drag) | Keyboard routing during drag | ✅ | With override active on `ascii-splash`, drag-time keyboard consumption is observable. |
+| [§3.7](mouse-and-clipboard.md#37-ending-a-selection) | Popup on mouse-up, new-drag-replaces | ✅ | Any selection. |
+| [§4.1.1](mouse-and-clipboard.md#411-copy-raw) | Copy Raw | ✅ | Any selection. |
+| [§4.1.2](mouse-and-clipboard.md#412-copy-rewrapped) | Copy Rewrapped (paragraph unwrap) | ✅ | `ChangelogRunner` renders wrapped item lines that exercise the rewrap path. |
+| [§4.2](mouse-and-clipboard.md#42-keyboard-shortcuts) | Cmd+C / Cmd+Shift+C | ✅ | Any selection. |
+| [§4.3](mouse-and-clipboard.md#43-dismissing-the-popup) | Esc / click-outside dismiss | ✅ | Any selection popup. |
+| [§5](mouse-and-clipboard.md#5-smart-extension-url--path-detection) | Smart-extension (URL / abs path / rel path / Windows path / error location) | ❌ | No matching tokens in the scenarios. |
+| [§5.3](mouse-and-clipboard.md#53-extension-action) | Press `e` to extend | ❌ | Blocked on §5 coverage. |
+| [§8.2](mouse-and-clipboard.md#82-paste-keybindings) | Cmd+V / Cmd+Shift+V / Ctrl+V / Ctrl+Shift+V paste | ⚠️ | Fires and writes to the fake PTY, but `TutorialShell.handleInput` echoes char-by-char and ignores bracketed-paste markers. |
+| [§8.5](mouse-and-clipboard.md#85-bracketed-paste) | Bracketed paste wraps `\e[200~ … \e[201~` | ❌ | No scenario emits `\x1b[?2004h`, so `bracketedPaste` stays `false`. |
+
+Auto-scroll during a drag and right-click paste are deferred in the implementation itself ([§9. Future](mouse-and-clipboard.md#9-future)) — not Playground gaps.
+
+## Future
 
 Two follow-up scenarios from the previous remediation plan remain useful and can be added without changing the three sections (expanding or replacing the `tut-boxed` neighbor):
 
-1. **`SCENARIO_BRACKETED_PASTE_TUI`** — closes §8.5. Emits `\x1b[?2004h` and an idle ANSI-framed view.
-2. **`SCENARIO_SMART_TOKENS`** — closes the §3.3 hint and §5.1–§5.3. Prints one of each shape from `lib/src/lib/smart-token.ts`'s `PATTERNS`.
+1. **`SCENARIO_BRACKETED_PASTE_TUI`** — closes [§8.5](mouse-and-clipboard.md#85-bracketed-paste). Emits `\x1b[?2004h` and an idle ANSI-framed view.
+2. **`SCENARIO_SMART_TOKENS`** — closes the [§3.3](mouse-and-clipboard.md#33-selection-hint-text) hint and [§5.1–§5.3](mouse-and-clipboard.md#51-detection). Prints one of each shape from `lib/src/lib/smart-token.ts`'s `PATTERNS`.
diff --git a/docs/specs/vscode.md b/docs/specs/vscode.md
index 9022078d..9ec89cf0 100644
--- a/docs/specs/vscode.md
+++ b/docs/specs/vscode.md
@@ -107,13 +107,13 @@ PTY lifecycle, buffering, the reconnection sequence, and the full message protoc
 
 > See `docs/specs/glossary.md` for the Workspace / Window containers and `docs/specs/alert.md` for the union status.
 >
-> Each webview's union is computed host-side and reflected onto native chrome (see "Surfacing union status" below) — implemented. It is currently always-on: the extension host has no `localStorage` to read the standalone workspaces flag, so whether to add a host-side gate is a merge-time decision. The stage-2b Window persistence container is standalone-only and does not touch VS Code, which keeps one bare `PersistedSession` per webview.
+> Each webview's union is computed host-side and reflected onto native chrome (see "Surfacing union status" below) — implemented. It is currently always-on: the extension host has no `localStorage` to read the standalone workspaces flag (a host-side gate is an open question — see [Future](#future)). The Window persistence container is standalone-only and does not touch VS Code, which keeps one bare `PersistedSession` per webview.
 
 In VS Code, **one webview is one Workspace**. The bottom-panel `WebviewView` ("Dormouse") is the default Workspace; each `dormouse.open` editor-tab `WebviewPanel` is an independent Workspace. Unlike standalone, several Workspaces are visible at once, and VS Code — not Dormouse — owns their tabs, creation, and closing: opening a Dormouse editor tab creates a Workspace and closing the tab closes it, so Dormouse adds no create/rename/close affordances here. A webview owns the terminal Sessions whose PTYs its router tracks (`ownedPtyIds`, `docs/specs/transport.md`) plus any browser surfaces rendered in it; together those are the Workspace's Surfaces.
 
 #### Surfacing union status on native chrome
 
-The host computes each webview's union (`ringing` / `todo`) from the module-level `AlertManager` scoped to that router's `ownedPtyIds` (`computeWorkspaceUnion`), delivered via the `attachRouter` `onUnion` callback. Because `ownedPtyIds` are PTY-backed terminals, **VS Code chrome reflects terminal Session ring + TODO only**; a browser surface's TODO stays webview-local until a future webview→host Surface-state channel exists (the `alert:state` channel is keyed by PTY-backed Session ids).
+The host computes each webview's union (`ringing` / `todo`) from the module-level `AlertManager` scoped to that router's `ownedPtyIds` (`computeWorkspaceUnion`), delivered via the `attachRouter` `onUnion` callback. Because `ownedPtyIds` are PTY-backed terminals, **VS Code chrome reflects terminal Session ring + TODO only**; a browser surface's TODO stays webview-local (the `alert:state` channel is keyed by PTY-backed Session ids; the webview→host Surface-state channel that would lift this is staged — see [Future](#future)).
 
 The two hosting primitives expose different chrome, so each uses what it supports, following the in-app `<title> <bell> [TODO]` pattern where possible:
 
@@ -159,9 +159,9 @@ Example of the pattern:
 --color-header-inactive-fg: var(--vscode-list-inactiveSelectionForeground);
 ```
 
-`theme.css` intentionally has no hardcoded color defaults or CSS variable fallback chains. The resolver duplicates VSCode registry defaults for the Dormouse-consumed color IDs, including `null` default behavior where Dormouse needs a concrete CSS variable. In particular, `list.inactiveSelectionForeground` resolves to normal foreground inheritance, not `list.activeSelectionForeground`; this matches VSCode's list/tree selected-row behavior for built-in Light.
+`theme.css` intentionally has no hardcoded color defaults or CSS variable fallback chains. The resolver duplicates VSCode registry defaults for the Dormouse-consumed color IDs, including `null` default behavior where Dormouse needs a concrete CSS variable; the null-default materialization rules (including the `list.inactiveSelectionForeground` case) are owned by `docs/specs/theme.md` (Runtime model).
 
-A `MutationObserver` in `lib/src/lib/terminal-theme.ts` watches for VS Code theme changes on `body`/`html` (class and style attribute mutations) and live-updates all xterm.js instances. The `terminal-registry.ts` facade still exposes the public lifecycle APIs. The theme resolver has its own observer on the same attributes so derived `--vscode-*` variables stay in sync before xterm rereads the terminal palette.
+A `MutationObserver` in `lib/src/lib/terminal-theme.ts` watches for VS Code theme changes — class + style mutations on both `body` and `html` — and live-updates all xterm.js instances. The `terminal-registry.ts` facade still exposes the public lifecycle APIs. The theme resolver has its own observer on the same roots and attributes (`vscode-color-observer.ts`) so derived `--vscode-*` variables stay in sync before xterm rereads the terminal palette.
 
 `dormouse.debugTheme` focuses the Dormouse WebviewView and posts
 `dormouse:openThemeDebugger` to the webview. `VSCodeAdapter` converts that
@@ -198,7 +198,15 @@ window must be reloaded to pick up changes.
 
 The Vite config for the extension (`vscode-ext/vite.config.ts`) sets `root: ../lib` and `outDir: ./media`, building the shared React frontend directly into the extension's media folder.
 
-## Dream architecture
+## Future
+
+### Webview→host Surface-state channel
+
+Today the host receives only PTY-keyed alert state (`alert:state`), so a browser surface's TODO stays webview-local and native chrome reflects terminal ring/TODO only. A webview→host Surface-state message would let the native-chrome union count browser-surface TODOs too (`docs/specs/alert.md`, `docs/specs/transport.md`).
+
+### Host-side workspaces flag gate
+
+The native-chrome union reflection is always-on because the extension host cannot read the standalone `dormouse.flags.workspaces` localStorage flag. Whether to add a host-side gate gets decided when the workspaces rollout reaches VS Code (`docs/specs/layout.md` `## Future`, workspaces-rollout).
 
 ### Context keys
 
@@ -208,11 +216,11 @@ Set context keys so menus and extensions can target Dormouse state:
 // Set when any Dormouse webview has focus
 vscode.commands.executeCommand('setContext', 'dormouse.active', true);
 
-// Set when Dormouse is in passthrough/terminal mode (keys go to PTY)
-vscode.commands.executeCommand('setContext', 'dormouse.mode', 'terminal');
+// Set when Dormouse is in passthrough mode (keys go to PTY)
+vscode.commands.executeCommand('setContext', 'dormouse.mode', 'passthrough');
 
-// Set when Dormouse is in normal/navigation mode (keys go to Dormouse UI)
-vscode.commands.executeCommand('setContext', 'dormouse.mode', 'normal');
+// Set when Dormouse is in command mode (keys drive Dormouse UI)
+vscode.commands.executeCommand('setContext', 'dormouse.mode', 'command');
 ```
 
 ### Commands
@@ -224,15 +232,13 @@ vscode.commands.executeCommand('setContext', 'dormouse.mode', 'normal');
 | `dormouse.closePane` | Close the focused pane |
 | `dormouse.nextPane` | Focus next pane |
 | `dormouse.prevPane` | Focus previous pane |
-| `dormouse.enterTerminalMode` | Switch to passthrough mode |
-| `dormouse.enterNormalMode` | Switch to navigation mode |
+| `dormouse.enterPassthroughMode` | Switch to passthrough mode |
+| `dormouse.enterCommandMode` | Switch to command mode |
 | `dormouse.listSessions` | Show QuickPick of all live PTY sessions |
 | `dormouse.reattach` | Reattach a minimized PTY to a pane |
 
-### Not yet implemented
+### Other host integrations
 
-- `TerminalProfileProvider` not registered — Dormouse doesn't appear in the terminal `+` dropdown
-- Context keys not set (`dormouse.active`, `dormouse.mode`) — needed for conditional keybindings
-- Commands not registered: `dormouse.newPane`, `closePane`, `nextPane`, `prevPane`, `enterTerminalMode`, `enterNormalMode`, `listSessions`, `reattach`
-- No status bar item showing active session count
-- No QuickPick for listing/reattaching PTY sessions
+- `TerminalProfileProvider` registration, so Dormouse appears in the terminal `+` dropdown
+- A status bar item showing active session count
+- A QuickPick for listing/reattaching PTY sessions
diff --git a/lib/src/components/MobileTerminalUi.tsx b/lib/src/components/MobileTerminalUi.tsx
index 61c9e961..1bcd2db4 100644
--- a/lib/src/components/MobileTerminalUi.tsx
+++ b/lib/src/components/MobileTerminalUi.tsx
@@ -512,7 +512,8 @@ export function MobileTerminalUi({
       if (isEditableTarget(active)) active.blur();
     };
     // Wall defers xterm focus via rAF, so a single blur can be reverted after we
-    // return; repeat across rAF and a few staggered ticks. See mobile-ui.md §10.
+    // return; repeat across rAF and a few staggered ticks. See
+    // mobile-terminal-ui.md (Touch interactions).
     blurActivePaneInput();
     window.setTimeout(blurActivePaneInput, 0);
     window.setTimeout(blurActivePaneInput, 50);
diff --git a/lib/src/host/iframe-proxy-rewrite.ts b/lib/src/host/iframe-proxy-rewrite.ts
index 367c34e9..c669821f 100644
--- a/lib/src/host/iframe-proxy-rewrite.ts
+++ b/lib/src/host/iframe-proxy-rewrite.ts
@@ -26,8 +26,8 @@ export const STRIP_RESPONSE_HEADERS = new Set([
 
 // The fixed, Dormouse-owned shim — like agent-browser's EDIT_SCRIPTS, never
 // user-supplied, so it is not an eval vector. Injected inline into served HTML
-// (loopback CSP is dropped, so an inline script runs). It posts two things to
-// the Wall and nothing else (every other keystroke flows to the tool):
+// (loopback CSP is dropped, so an inline script runs). It posts four message
+// kinds to the Wall and nothing else (every other keystroke flows to the tool):
 //   - `leader`: the reserved dual-tap ⌘/⇧ chord (matching handle-dual-tap.ts),
 //     so the global chord keeps working with the frame focused (#1).
 //   - `pointerdown`: a click landed in the frame. A cross-origin click reaches
diff --git a/lib/src/lib/alert-manager.test.ts b/lib/src/lib/alert-manager.test.ts
index 322f440e..259ca7f4 100644
--- a/lib/src/lib/alert-manager.test.ts
+++ b/lib/src/lib/alert-manager.test.ts
@@ -273,6 +273,28 @@ describe('AlertManager in isolation', () => {
     });
   });
 
+  it('opens the dialog after an attention-dismissed ring even when WATCHING is disabled', () => {
+    const id = 'attention-dismissed-watching-disabled';
+
+    // A protocol ring needs no WATCHING; attending it dismisses the ring and
+    // sets attentionDismissedRing while status falls back to WATCHING_DISABLED.
+    manager.notifyFromProtocol(id, { source: 'OSC 9', title: null, body: 'Build finished' });
+    expect(manager.getState(id).status).toBe('ALERT_RINGING');
+    manager.attend(id);
+    expect(manager.getState(id)).toMatchObject({
+      status: 'WATCHING_DISABLED',
+      todo: true,
+    });
+
+    // The next bell click must open the dialog, not silently enable WATCHING.
+    expect(manager.dismissOrToggleAlert(id, 'WATCHING_DISABLED')).toBe('dismissed');
+    expect(manager.getState(id).watchingEnabled).toBe(false);
+
+    // Flag consumed: the click after that enables WATCHING as usual.
+    expect(manager.dismissOrToggleAlert(id, 'WATCHING_DISABLED')).toBe('enabled');
+    expect(manager.getState(id).watchingEnabled).toBe(true);
+  });
+
   it('protocol completion is suppressed while the user has attention', () => {
     const id = 'osc-progress-attention';
 
diff --git a/lib/src/lib/alert-manager.ts b/lib/src/lib/alert-manager.ts
index 0b6b8e3a..11f5d929 100644
--- a/lib/src/lib/alert-manager.ts
+++ b/lib/src/lib/alert-manager.ts
@@ -504,6 +504,14 @@ export class AlertManager {
 
     switch (displayedStatus) {
       case 'WATCHING_DISABLED':
+        // A protocol/command-exit ring needs no WATCHING, so an attention-based
+        // dismissal can land here too; the next click must open the dialog
+        // instead of silently enabling WATCHING (alert.md, attentionDismissedRing).
+        if (entry.attentionDismissedRing) {
+          entry.attentionDismissedRing = false;
+          this.notify(id);
+          return 'dismissed';
+        }
         this.toggleAlert(id);
         return 'enabled';
       case 'ALERT_RINGING':
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index 8abd7e5b..de4b1825 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -164,8 +164,9 @@ export interface PlatformAdapter {
   // stream's screencast is CSS-resolution only (a Chromium limitation —
   // Page.startScreencast ignores deviceScaleFactor), so the panel displays
   // these crisp screenshots instead, using stream frames only as change
-  // signals. Absent on hosts that can't run the binary (degrades to rendering
-  // the screencast frames directly).
+  // signals. Absent on hosts that can't run the binary — the panel then shows
+  // only the placeholder (frame bytes are discarded; there is no frame-drawing
+  // fallback).
   agentBrowserScreenshot?(session: string, opts: { format?: 'jpeg' | 'png'; quality?: number }, binaryPath?: string): Promise<AgentBrowserScreenshotResult>;
   // Reads the current stream port for an already-running session. This is a
   // purpose-built status channel, not part of agentBrowserCommand's allowlist,
diff --git a/lib/src/lib/session-activity-store.ts b/lib/src/lib/session-activity-store.ts
index 17785878..8c588665 100644
--- a/lib/src/lib/session-activity-store.ts
+++ b/lib/src/lib/session-activity-store.ts
@@ -192,7 +192,9 @@ export function dismissOrToggleAlert(id: string, displayedStatus: SessionStatus)
   let result: AlertButtonActionResult;
   switch (displayedStatus) {
     case 'WATCHING_DISABLED':
-      result = 'enabled';
+      // Mirrors AlertManager.dismissOrToggleAlert: after an attention-based
+      // dismissal the next click opens the dialog, even from WATCHING_DISABLED.
+      result = entry?.attentionDismissedRing ? 'dismissed' : 'enabled';
       break;
     case 'ALERT_RINGING':
       result = 'dismissed';
diff --git a/lib/src/lib/terminal-protocol.ts b/lib/src/lib/terminal-protocol.ts
index 801c443e..90530431 100644
--- a/lib/src/lib/terminal-protocol.ts
+++ b/lib/src/lib/terminal-protocol.ts
@@ -59,6 +59,9 @@ const OSC99_PENDING_BODY_LIMIT = 16_384;
 const OSC99_SUPPORT_PAYLOAD = 'o=always:p=title,body';
 const OSC99_RESPONSE_ID_RE = /^[^\s:;\x00-\x1f\x7f-\x9f]+$/;
 const TERMINAL_BELL_NOTIFICATION: ActivityNotification = { source: 'BEL', title: 'Terminal bell', body: null };
+// Mirrors ITERM2_COMPAT_VERSION in standalone/sidecar/pty-core.js — keep in
+// sync (terminal-escapes.md: one compatibility version across env and device
+// responses).
 export const ITERM2_COMPAT_VERSION = '3.5.0';
 export const ITERM2_DEVICE_ATTRIBUTES_RESPONSE = `\x1bP>|iTerm2 ${ITERM2_COMPAT_VERSION}\x1b\\`;
 
@@ -70,8 +73,10 @@ export class TerminalProtocolParser {
    * @param colorProvider Resolves the active terminal theme color for OSC
    *   10/11/12 background/foreground/cursor *queries*. Frontend adapters pass a
    *   provider backed by the live xterm theme, so TUIs (e.g. Codex) can detect
-   *   the real terminal background. Host-side parsers (VS Code extension host)
-   *   omit it, leaving such queries to xterm.js as before.
+   *   the real terminal background. The VS Code extension-host parser passes a
+   *   provider fed by webview-pushed colors (`dormouse:themeColors`); until the
+   *   first push the provider returns null and the query falls through to
+   *   xterm.js.
    */
   constructor(private readonly colorProvider?: TerminalColorProvider) {}
 
diff --git a/lib/src/lib/terminal-theme.ts b/lib/src/lib/terminal-theme.ts
index 4460bb96..de548ab3 100644
--- a/lib/src/lib/terminal-theme.ts
+++ b/lib/src/lib/terminal-theme.ts
@@ -92,6 +92,9 @@ export function startThemeObserver(): void {
     for (const listener of themeChangeListeners) listener();
   });
 
+  // class + style on both roots, matching the resolver's observer
+  // (vscode-color-observer.ts) so a theme signaled via an <html> class
+  // mutation also refreshes the terminal palette.
   observer.observe(document.body, { attributes: true, attributeFilter: ['class', 'style'] });
-  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['style'] });
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'style'] });
 }
diff --git a/lib/src/remote/client/pocket-client.test.ts b/lib/src/remote/client/pocket-client.test.ts
index 6b929556..3c6bb1df 100644
--- a/lib/src/remote/client/pocket-client.test.ts
+++ b/lib/src/remote/client/pocket-client.test.ts
@@ -10,6 +10,7 @@
 
 import { describe, expect, it } from 'vitest';
 import {
+  PAIRING_STALE_PRESENCE_ERROR,
   SELFHOST_ACCOUNT_ID,
   generateDeviceKeyPair,
   hashPasskeyPublicKey,
@@ -293,6 +294,46 @@ describe('pair', () => {
     expect(result.error).toBe('denied by host');
     expect(client.isPaired('h1')).toBe(false);
   });
+
+  it('re-asserts presence and retries once on a stale-presence denial', async () => {
+    const harness = makeClient({
+      ...AUTH_ROUTES,
+      '/api/reauth/begin': () => ({ json: { challenge: b64uChallenge(7), rpId: RP_ID } }),
+      '/api/reauth/finish': () => ({ json: { presenceVerifiedAt: 123 } }),
+    });
+    const { client, socket, calls } = harness;
+    await client.setup('pw', 'My Phone');
+    await client.signin();
+    const open = client.openSocket();
+    socket.fireOpen();
+    await open;
+
+    const pairing = client.pair('h1', 'iPhone');
+    await nextSent(socket, (f) => f.t === 'pair');
+    socket.server({ t: 'pair-result', approved: false, error: PAIRING_STALE_PRESENCE_ERROR });
+
+    // The client re-auths (bearer-authorized begin + finish) and re-sends the
+    // SAME pairing request; approve the retry.
+    const retry = await (async () => {
+      for (let i = 0; i < 200; i++) {
+        const pairs = socket.sent.filter((f) => f.t === 'pair');
+        if (pairs.length >= 2) return pairs[1]!;
+        await new Promise((r) => setTimeout(r, 2));
+      }
+      throw new Error('no retry pair frame was sent');
+    })();
+    const first = socket.sent.find((f) => f.t === 'pair')!;
+    expect(retry.request).toEqual(first.request);
+    socket.server({ t: 'pair-result', approved: true, record: { hostId: 'h1' } });
+
+    const result = await pairing;
+    expect(result.approved).toBe(true);
+    expect(client.isPaired('h1')).toBe(true);
+    for (const route of ['/api/reauth/begin', '/api/reauth/finish']) {
+      const call = calls.find((c) => c.url.endsWith(route))!;
+      expect(call.headers.authorization).toBe('Bearer tok-abc');
+    }
+  });
 });
 
 describe('connect', () => {
diff --git a/lib/src/remote/client/pocket-client.ts b/lib/src/remote/client/pocket-client.ts
index bbfc6b48..3fc400b3 100644
--- a/lib/src/remote/client/pocket-client.ts
+++ b/lib/src/remote/client/pocket-client.ts
@@ -17,6 +17,7 @@
 
 import {
   API_ROUTES,
+  PAIRING_STALE_PRESENCE_ERROR,
   REMOTE_EVENTS,
   REMOTE_METHODS,
   SELFHOST_ACCOUNT_ID,
@@ -34,6 +35,7 @@ import {
   type HostAclRecord,
   type HostsResponse,
   type PairingRequest,
+  type ReauthFinishResponse,
   type RemoteEventMsg,
   type RemoteResponse,
   type ServerToClientFrame,
@@ -44,7 +46,6 @@ import {
   type TerminalAttachResult,
   type TerminalClosedEvent,
   type TerminalDataEvent,
-  type TerminalResizeEvent,
 } from 'server-lib-common';
 import type { WebAuthnClient } from './webauthn';
 import type { RemoteWebSocket } from '../ws';
@@ -85,7 +86,6 @@ export interface PocketClientDeps {
 export interface TerminalHandlers {
   /** Base64url PTY output bytes. */
   onData(bytes: string): void;
-  onResize?(cols: number, rows: number): void;
   onClosed?(exitCode?: number): void;
 }
 
@@ -250,13 +250,33 @@ export class PocketClient {
       devicePublicKey: device.devicePublicKey,
       requestedLabel: label,
     };
+    let result = await this.#sendPair(hostId, request);
+    if (!result.approved && result.error === PAIRING_STALE_PRESENCE_ERROR) {
+      // Pairing presence went stale (> PAIRING_PRESENCE_WINDOW_MS since the
+      // last server-verified assertion). One WebAuthn prompt refreshes the
+      // session's stamp; then retry once. (remote-security-model.md, Pairing.)
+      await this.#reauth();
+      result = await this.#sendPair(hostId, request);
+    }
+    if (result.approved) this.#storage.markPaired(hostId);
+    return result;
+  }
+
+  async #sendPair(hostId: string, request: PairingRequest): Promise<PairResult> {
     const awaited = this.#expect('pair-result');
     this.#send({ t: 'pair', hostId, request });
     const frame = (await awaited) as Extract<ServerToClientFrame, { t: 'pair-result' }>;
-    if (frame.approved) this.#storage.markPaired(hostId);
     return { approved: frame.approved, record: frame.record, error: frame.error };
   }
 
+  /** Refresh the session's server-verified presence with one WebAuthn prompt. */
+  async #reauth(): Promise<void> {
+    const auth = { authorization: `Bearer ${this.#requireToken()}` };
+    const begin = await this.#api<SigninBeginResponse>(API_ROUTES.reauthBegin, {}, { headers: auth });
+    const assertion = await this.#webauthn.getAssertion(begin.challenge, begin.rpId);
+    await this.#api<ReauthFinishResponse>(API_ROUTES.reauthFinish, { assertion }, { headers: auth });
+  }
+
   /**
    * Connect to a paired Host: request a challenge, then produce ONE passkey
    * assertion + one device-key signature over it (one biometric prompt), send
@@ -347,11 +367,6 @@ export class PocketClient {
           case REMOTE_EVENTS.terminalData:
             handlers.onData((event.data as TerminalDataEvent).bytes);
             return;
-          case REMOTE_EVENTS.terminalResize: {
-            const data = event.data as TerminalResizeEvent;
-            handlers.onResize?.(data.cols, data.rows);
-            return;
-          }
           case REMOTE_EVENTS.terminalClosed:
             handlers.onClosed?.((event.data as TerminalClosedEvent).exitCode);
             return;
diff --git a/lib/src/remote/client/remote-adapter.ts b/lib/src/remote/client/remote-adapter.ts
index 430b59c9..20f387f5 100644
--- a/lib/src/remote/client/remote-adapter.ts
+++ b/lib/src/remote/client/remote-adapter.ts
@@ -41,8 +41,9 @@
  * non-attached pane are dropped (the Host would reject them anyway), and the
  * attach repaint — not a snapshot transfer — is what fills the client screen.
  * The registry's own `onResize → resizePty` path keeps the attached pane sized;
- * `setActivePane` seeds the first size. Host-initiated `terminal.resize` events
- * are ignored (the PlatformAdapter interface has no inbound-resize channel).
+ * `setActivePane` seeds the first size. Protocol-v1 has no host-initiated
+ * resize event — size-authority notification is staged in remote-api.md
+ * ## Future (the PlatformAdapter interface has no inbound-resize channel).
  */
 
 import {
diff --git a/package.json b/package.json
index c8c601fe..4be71f35 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,8 @@
   },
   "scripts": {
     "build": "pnpm run build:vscode && pnpm --filter dormouse-website build",
-    "test": "pnpm -r run test",
+    "test": "node scripts/spec-lint.mjs && pnpm -r run test",
+    "lint:specs": "node scripts/spec-lint.mjs",
     "dev:lib": "pnpm --filter dormouse-lib dev",
     "dev:standalone": "node scripts/free-dev-port.mjs && pnpm --filter dormouse-standalone tauri dev",
     "dev:standalone:ab": "pnpm --filter dormouse-standalone dev:agent-browser",
diff --git a/scripts/spec-lint.mjs b/scripts/spec-lint.mjs
new file mode 100644
index 00000000..626285b8
--- /dev/null
+++ b/scripts/spec-lint.mjs
@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Mechanical checks for the spec-suite conventions in AGENTS.md ("Specs" and
+ * "Spec lifecycle"). Runs from the repo root via `pnpm test` (see the root
+ * package.json). Exits non-zero with a per-violation report.
+ *
+ * Checks:
+ *   1. Every docs/specs/*.md file is indexed in AGENTS.md.
+ *   2. `## Future` (or `## N. Future`), when present, is the LAST section of
+ *      its spec — the fold convention.
+ *   3. Every relative markdown link in AGENTS.md + docs/specs resolves: the
+ *      target file exists, and a `#fragment` matches a real heading anchor.
+ *   4. Every backticked repo path mentioned in AGENTS.md + docs/specs exists
+ *      on disk — catches `Source of truth:` pointers rotting on renames.
+ *      Conservative: only tokens that start with a known top-level directory
+ *      and contain no globs/placeholders are checked. Build outputs that only
+ *      exist after a build are skipped via SKIP_PATH_PREFIXES.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, normalize } from 'node:path';
+
+const ROOT = new URL('..', import.meta.url).pathname;
+const SPECS_DIR = 'docs/specs';
+
+const TOP_LEVEL_DIRS = [
+  'lib/', 'standalone/', 'vscode-ext/', 'website/', 'server/',
+  'server-lib-common/', 'dor/', 'dor-lib-common/', 'docs/', 'scripts/',
+  '.github/', '.claude/', '.vscode/',
+];
+// Path prefixes that are legitimate references to build/staged/generated
+// output which does not exist in a clean checkout.
+const SKIP_PATH_PREFIXES = [
+  'lib/dist', 'dor/dist', 'vscode-ext/dist', 'vscode-ext/media',
+  'standalone/dist',
+  'website/src/data/changelog.json', // gitignored, generated by website prebuild (deploy.md)
+];
+
+const specFiles = readdirSync(join(ROOT, SPECS_DIR))
+  .filter((f) => f.endsWith('.md'))
+  .map((f) => join(SPECS_DIR, f));
+const allFiles = ['AGENTS.md', ...specFiles];
+const problems = [];
+
+const read = (rel) => readFileSync(join(ROOT, rel), 'utf-8');
+
+/** GitHub-style anchor slug for a heading title. */
+function slug(title) {
+  let t = title.trim().replace(/`/g, '');
+  t = t.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1'); // unwrap md links
+  return t
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s/g, '-');
+}
+
+function headings(rel) {
+  const out = [];
+  let inFence = false;
+  for (const line of read(rel).split('\n')) {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    if (inFence) continue;
+    const m = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (m) out.push({ level: m[1].length, title: m[2].trim() });
+  }
+  return out;
+}
+
+const anchorCache = new Map();
+function anchorsOf(rel) {
+  if (!anchorCache.has(rel)) {
+    anchorCache.set(rel, new Set(headings(rel).map((h) => slug(h.title))));
+  }
+  return anchorCache.get(rel);
+}
+
+// --- Check 1: index completeness -------------------------------------------
+const agents = read('AGENTS.md');
+for (const spec of specFiles) {
+  const base = spec.split('/').pop();
+  if (!agents.includes(base)) {
+    problems.push(`AGENTS.md: spec not indexed -> ${spec}`);
+  }
+}
+
+// --- Check 2: Future is the last section ------------------------------------
+for (const spec of specFiles) {
+  const h2s = headings(spec).filter((h) => h.level === 2);
+  const futureIdx = h2s.findIndex((h) => /^(\d+\.\s*)?Future$/i.test(h.title));
+  if (futureIdx !== -1 && futureIdx !== h2s.length - 1) {
+    problems.push(
+      `${spec}: "## ${h2s[futureIdx].title}" must be the last section ` +
+      `(followed by "## ${h2s[futureIdx + 1].title}")`,
+    );
+  }
+}
+
+// --- Check 3: relative links + anchors resolve -------------------------------
+const LINK_RE = /\]\(([^)\s]+)\)/g;
+for (const rel of allFiles) {
+  const base = dirname(rel);
+  const lines = read(rel).split('\n');
+  let inFence = false;
+  lines.forEach((line, i) => {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    if (inFence) return;
+    for (const m of line.matchAll(LINK_RE)) {
+      const target = m[1];
+      if (/^(https?:|mailto:)/.test(target)) continue;
+      const [path, fragment] = target.split('#');
+      const full = path ? normalize(join(base, path)) : rel;
+      if (path && !existsSync(join(ROOT, full))) {
+        problems.push(`${rel}:${i + 1}: broken link -> ${target}`);
+        continue;
+      }
+      if (fragment && full.endsWith('.md') && !anchorsOf(full).has(fragment)) {
+        problems.push(`${rel}:${i + 1}: missing anchor -> ${target}`);
+      }
+    }
+  });
+}
+
+// --- Check 4: backticked repo paths exist ------------------------------------
+const TICK_RE = /`([^`\n]+)`/g;
+for (const rel of allFiles) {
+  const lines = read(rel).split('\n');
+  let inFence = false;
+  lines.forEach((line, i) => {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    if (inFence) return;
+    for (const m of line.matchAll(TICK_RE)) {
+      const token = m[1];
+      if (!token.includes('/')) continue;
+      if (/[\s*{<>$%(?\\]|\.\.\.|…/.test(token)) continue;
+      if (!TOP_LEVEL_DIRS.some((d) => token === d.slice(0, -1) || token.startsWith(d))) continue;
+      if (SKIP_PATH_PREFIXES.some((p) => token.startsWith(p))) continue;
+      if (!existsSync(join(ROOT, token))) {
+        problems.push(`${rel}:${i + 1}: path does not exist -> ${token}`);
+      }
+    }
+  });
+}
+
+// -----------------------------------------------------------------------------
+if (problems.length > 0) {
+  console.error(`spec-lint: ${problems.length} problem(s)\n`);
+  for (const p of problems) console.error(`  ${p}`);
+  console.error(
+    '\nConventions are defined in AGENTS.md ("Specs" and "Spec lifecycle").',
+  );
+  process.exit(1);
+}
+console.log(`spec-lint: OK (${specFiles.length} specs, ${allFiles.length} files checked)`);
diff --git a/server-lib-common/src/remote/wire.ts b/server-lib-common/src/remote/wire.ts
index cca77804..b257ba34 100644
--- a/server-lib-common/src/remote/wire.ts
+++ b/server-lib-common/src/remote/wire.ts
@@ -18,6 +18,8 @@ export const API_ROUTES = {
   setupFinish: '/api/setup/finish',
   signinBegin: '/api/signin/begin',
   signinFinish: '/api/signin/finish',
+  reauthBegin: '/api/reauth/begin',
+  reauthFinish: '/api/reauth/finish',
   hostEnroll: '/api/host/enroll',
   hosts: '/api/hosts',
 } as const;
@@ -74,6 +76,21 @@ export interface SigninFinishResponse {
   expiresAt: number;
 }
 
+/**
+ * Re-assert presence on an existing session (session-token auth; begin reuses
+ * the {@link SigninBeginResponse} shape). Used when pairing reports
+ * `PAIRING_STALE_PRESENCE_ERROR` (pairing.ts): one WebAuthn prompt refreshes
+ * the session's presence stamp without re-minting the token or the relay
+ * socket.
+ */
+export interface ReauthFinishRequest {
+  assertion: PasskeyAssertion;
+}
+export interface ReauthFinishResponse {
+  /** Epoch ms the session's presence stamp was refreshed to. */
+  presenceVerifiedAt: number;
+}
+
 export interface HostEnrollRequest {
   password: string;
   label: string;
@@ -157,11 +174,12 @@ export const REMOTE_METHODS = {
   terminalResize: 'terminal.resize',
 } as const;
 
+// Events are dispatched by name, so future events (size-authority notify,
+// per-attachment semantics — staged in remote-api.md ## Future) land here
+// additively; old clients ignore names they don't know.
 export const REMOTE_EVENTS = {
   directorySnapshot: 'directory.snapshot',
   terminalData: 'terminal.data',
-  terminalResize: 'terminal.resize',
-  terminalSemantic: 'terminal.semantic',
   terminalClosed: 'terminal.closed',
 } as const;
 
@@ -213,10 +231,6 @@ export interface TerminalDataEvent {
   /** Base64url PTY output bytes. */
   bytes: string;
 }
-export interface TerminalResizeEvent {
-  cols: number;
-  rows: number;
-}
 export interface TerminalClosedEvent {
   exitCode?: number;
 }
diff --git a/server-lib-common/src/security/pairing.ts b/server-lib-common/src/security/pairing.ts
index b705b15c..63e8fee3 100644
--- a/server-lib-common/src/security/pairing.ts
+++ b/server-lib-common/src/security/pairing.ts
@@ -5,9 +5,16 @@
  * models the local approval UI on the Host. The Server can relay a pairing
  * *request*, but only someone at the Host can turn it into authorization.
  *
- * Integration contract: the Host must verify a fresh passkey assertion for
- * the requesting account (see passkey.ts) before calling {@link begin} — a
- * pairing request is meaningless unless the user just proved presence.
+ * Integration contract: presence for pairing is server-attested plus
+ * Host-approved. The Server relays a pairing request only while the session's
+ * last server-verified passkey assertion is within
+ * {@link PAIRING_PRESENCE_WINDOW_MS} (sign-in, re-auth, and the connect2
+ * handshake all refresh the stamp); a stale session is answered with
+ * {@link PAIRING_STALE_PRESENCE_ERROR} and the Client re-asserts with one
+ * WebAuthn prompt, then retries. The Host does not re-verify an assertion at
+ * pairing time — its stronger control is the mandatory local approval below,
+ * unlike connect, where `authorizeConnection` verifies presence itself
+ * (docs/specs/remote-security-model.md, Pairing Ceremony).
  */
 
 import { toBase64Url } from './bytes.js';
@@ -15,6 +22,17 @@ import { getWebCrypto, type WebCryptoLike } from './webcrypto.js';
 import { HostAcl, type HostAclRecord } from './acl.js';
 
 export const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * How recent the session's last server-verified passkey assertion must be for
+ * the Server to relay a pairing request. Tight on purpose: it covers
+ * "sign in, then tap Pair", and anything slower costs exactly one extra
+ * biometric prompt via re-auth.
+ */
+export const PAIRING_PRESENCE_WINDOW_MS = 30_000;
+
+/** `pair-result.error` code telling the Client to re-assert presence and retry. */
+export const PAIRING_STALE_PRESENCE_ERROR = 'stale-presence';
 const PAIRING_ID_BYTE_LENGTH = 16;
 
 /** What a Client submits to request pairing (after passkey authentication). */
diff --git a/server/src/app.ts b/server/src/app.ts
index 89b418c9..792f85b2 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -46,6 +46,8 @@ import type {
   HostEnrollResponse,
   HostsResponse,
   PasskeyAssertion,
+  ReauthFinishRequest,
+  ReauthFinishResponse,
   SetupBeginRequest,
   SetupBeginResponse,
   SetupFinishRequest,
@@ -91,6 +93,13 @@ export interface AppConfig {
 export interface Session {
   readonly accountId: string;
   readonly expiresAt: number;
+  /**
+   * Epoch ms of the last passkey assertion the Server verified for this
+   * session — set at sign-in, refreshed by `/api/reauth/finish` and by a
+   * verified `connect2` handshake. Pairing requires it to be within
+   * `PAIRING_PRESENCE_WINDOW_MS` (handshake.ts `checkPair`).
+   */
+  lastVerifiedPresence: number;
 }
 
 type AppEnv = { Variables: { session: Session; host: StoredHost } };
@@ -116,7 +125,11 @@ export class SessionStore {
   /** Mint a fresh session token (32 random bytes, base64url) for an account. */
   mint(accountId: string): { token: string; session: Session } {
     const token = toBase64Url(randomBytes(32));
-    const session: Session = { accountId, expiresAt: this.#now() + SESSION_TTL_MS };
+    const session: Session = {
+      accountId,
+      expiresAt: this.#now() + SESSION_TTL_MS,
+      lastVerifiedPresence: this.#now(),
+    };
     this.#sessions.set(token, session);
     return { token, session };
   }
@@ -266,29 +279,31 @@ export function createApp(config: AppConfig): CreatedApp {
     return c.json(res);
   });
 
-  app.post(API_ROUTES.signinFinish, async (c) => {
-    const body = await readJson<SigninFinishRequest>(c);
-    const assertion = body?.assertion;
+  /**
+   * Shared by sign-in and re-auth: pull the challenge out of the assertion's
+   * own clientDataJSON and consume it (single-use, BEFORE verifying — a
+   * captured assertion can never be replayed even if verification succeeds),
+   * then verify against the STORED passkey for the asserted credential.
+   */
+  const verifyFreshAssertion = async (
+    assertion: SigninFinishRequest['assertion'] | undefined,
+  ): Promise<{ ok: true } | { ok: false; status: 400 | 401 | 404; error: string }> => {
     if (!assertion || typeof assertion.credentialId !== 'string') {
-      return c.json({ error: 'malformed assertion' }, 400);
+      return { ok: false, status: 400, error: 'malformed assertion' };
     }
-
     const stored = await accounts.findPasskey(assertion.credentialId);
-    if (!stored) return c.json({ error: 'unknown credential' }, 404);
+    if (!stored) return { ok: false, status: 404, error: 'unknown credential' };
 
-    // Pull the challenge out of the assertion's own clientDataJSON so we can
-    // consume it (single-use) before verifying. Consuming first guarantees a
-    // captured assertion can never be replayed even if verification succeeds.
     const clientData = decodeClientData(assertion.clientDataJSON);
     if (!clientData || typeof clientData.challenge !== 'string') {
-      return c.json({ error: 'malformed clientDataJSON' }, 400);
+      return { ok: false, status: 400, error: 'malformed clientDataJSON' };
     }
     const challenge = normalizeChallenge(clientData.challenge);
     if (!challenge) {
-      return c.json({ error: 'malformed clientDataJSON' }, 400);
+      return { ok: false, status: 400, error: 'malformed clientDataJSON' };
     }
     if (!signinChallenges.consume(challenge)) {
-      return c.json({ error: 'unrecognized or expired challenge' }, 400);
+      return { ok: false, status: 400, error: 'unrecognized or expired challenge' };
     }
 
     const result = await verifyPasskeyAssertion(assertion as PasskeyAssertion, stored.publicKey, {
@@ -300,8 +315,15 @@ export function createApp(config: AppConfig): CreatedApp {
       requireUserVerification: config.requireUserVerification,
     });
     if (!result.ok) {
-      return c.json({ error: `assertion rejected: ${result.reason}` }, 401);
+      return { ok: false, status: 401, error: `assertion rejected: ${result.reason}` };
     }
+    return { ok: true };
+  };
+
+  app.post(API_ROUTES.signinFinish, async (c) => {
+    const body = await readJson<SigninFinishRequest>(c);
+    const verdict = await verifyFreshAssertion(body?.assertion);
+    if (!verdict.ok) return c.json({ error: verdict.error }, verdict.status);
 
     const { token, session } = sessions.mint(SELFHOST_ACCOUNT_ID);
     const res: SigninFinishResponse = {
@@ -339,6 +361,30 @@ export function createApp(config: AppConfig): CreatedApp {
     await next();
   };
 
+  // --- Re-auth: refresh an existing session's verified-presence stamp ------
+  // Pairing requires a recent server-verified assertion (PAIRING_PRESENCE_WINDOW_MS;
+  // remote-security-model.md, Pairing Ceremony). When the stamp is stale the
+  // Pocket client calls these to re-assert with one WebAuthn prompt — the same
+  // verification as sign-in, but the session (and the relay socket opened with
+  // its token) is kept rather than re-minted.
+
+  app.post(API_ROUTES.reauthBegin, requireSession, (c) => {
+    const { challenge } = signinChallenges.issue();
+    const res: SigninBeginResponse = { challenge, rpId };
+    return c.json(res);
+  });
+
+  app.post(API_ROUTES.reauthFinish, requireSession, async (c) => {
+    const body = await readJson<ReauthFinishRequest>(c);
+    const verdict = await verifyFreshAssertion(body?.assertion);
+    if (!verdict.ok) return c.json({ error: verdict.error }, verdict.status);
+
+    const session = c.get('session');
+    session.lastVerifiedPresence = now();
+    const res: ReauthFinishResponse = { presenceVerifiedAt: session.lastVerifiedPresence };
+    return c.json(res);
+  });
+
   // --- Host presence: enrolled hosts + whether each is connected -----------
 
   app.get(API_ROUTES.hosts, requireSession, async (c) => {
@@ -392,7 +438,12 @@ export function createApp(config: AppConfig): CreatedApp {
       if (!session) return c.json({ error: 'unauthorized' }, 401);
       return next();
     },
-    upgradeWebSocket(() => {
+    upgradeWebSocket((c) => {
+      // Re-resolve the Session OBJECT (not just validity — the middleware
+      // already gated that) so the relay can hand the gate a live reference
+      // whose presence stamp reauth/connect2 can refresh.
+      const token = c.req.query(WS_TOKEN_PARAM);
+      const session = token ? sessions.validate(token) : null;
       let conn: ClientConn | undefined;
       // `onClientFrame` is async (pair/connect2 verification), so serialize
       // frames from this socket through a promise chain — a client's frames
@@ -400,7 +451,12 @@ export function createApp(config: AppConfig): CreatedApp {
       let chain: Promise<void> = Promise.resolve();
       return {
         onOpen: (_evt, ws) => {
-          conn = hub.registerClient(ws);
+          if (!session) {
+            // Expired between the middleware check and the upgrade.
+            ws.close(1008, 'unauthorized');
+            return;
+          }
+          conn = hub.registerClient(ws, session);
         },
         onMessage: (evt) => {
           if (conn && typeof evt.data === 'string') {
diff --git a/server/src/handshake.ts b/server/src/handshake.ts
index e31624c7..8627038f 100644
--- a/server/src/handshake.ts
+++ b/server/src/handshake.ts
@@ -6,8 +6,10 @@
  *
  *   - `pair`:     the pairing request must be consistent with the authenticated
  *                 session — the owner account, a registered passkey credential,
- *                 and the matching stored public-key hash. Otherwise the server
- *                 refuses to relay it to the Host at all.
+ *                 and the matching stored public-key hash — and the session's
+ *                 presence must be fresh: its last server-verified assertion
+ *                 within PAIRING_PRESENCE_WINDOW_MS (pairing.ts). Otherwise the
+ *                 server refuses to relay it to the Host at all.
  *   - `connect2`: the WebAuthn assertion must verify against the STORED passkey
  *                 public key (not the one the request carries), over the exact
  *                 Host challenge the server just relayed to this client. This is
@@ -23,6 +25,8 @@
 
 import {
   DEFAULT_CHALLENGE_TTL_MS,
+  PAIRING_PRESENCE_WINDOW_MS,
+  PAIRING_STALE_PRESENCE_ERROR,
   SELFHOST_ACCOUNT_ID,
   hashPasskeyPublicKey,
   verifyPasskeyAssertion,
@@ -34,6 +38,16 @@ import type { AccountStore } from './state.js';
 /** Result of {@link HandshakeGate.checkPair}. */
 export type PairCheck = { readonly ok: true } | { readonly ok: false; readonly error: string };
 
+/**
+ * The slice of the app's `Session` the gate reads and refreshes: the epoch-ms
+ * timestamp of the last assertion the Server verified for it. Mutable — a
+ * verified `connect2` refreshes it, and `/api/reauth/finish` refreshes it out
+ * of band.
+ */
+export interface PresenceSession {
+  lastVerifiedPresence: number;
+}
+
 /** Result of {@link HandshakeGate.checkConnect2}. Failures reuse the Host's vocabulary. */
 export type Connect2Check =
   | { readonly ok: true }
@@ -45,8 +59,8 @@ export type Connect2Check =
  * transport-dumb.
  */
 export interface HandshakeGate {
-  /** Verify a `pair` request before relaying it to the Host. */
-  checkPair(request: unknown): Promise<PairCheck>;
+  /** Verify a `pair` request (contents + session presence) before relaying it to the Host. */
+  checkPair(request: unknown, session: PresenceSession): Promise<PairCheck>;
   /** Remember the Host challenge the server just relayed to a client (freshness half). */
   observeChallenge(clientId: string, hostId: string, challenge: string, expiresAt: number): void;
   /** Verify a `connect2` request before relaying it to the target Host. */
@@ -54,6 +68,7 @@ export interface HandshakeGate {
     clientId: string,
     targetHostId: string,
     request: ConnectionRequest,
+    session: PresenceSession,
   ): Promise<Connect2Check>;
   /** Drop any remembered challenge for a client that disconnected. */
   forgetClient(clientId: string): void;
@@ -76,6 +91,8 @@ export interface HandshakeConfig {
   readonly now?: () => number;
   /** Relay-side TTL for Host challenges observed by the server. */
   readonly relayedChallengeTtlMs?: number;
+  /** Presence window for pairing; defaults to `PAIRING_PRESENCE_WINDOW_MS`. */
+  readonly pairingPresenceWindowMs?: number;
 }
 
 /** The last Host challenge the server relayed to a client. */
@@ -93,6 +110,7 @@ export class Handshake implements HandshakeGate {
   readonly #requireUserVerification: boolean;
   readonly #now: () => number;
   readonly #relayedChallengeTtlMs: number;
+  readonly #pairingPresenceWindowMs: number;
   /** clientId → the last Host challenge relayed to it; consumed single-use. */
   readonly #relayed = new Map<string, RelayedChallenge>();
 
@@ -103,9 +121,10 @@ export class Handshake implements HandshakeGate {
     this.#requireUserVerification = config.requireUserVerification ?? false;
     this.#now = config.now ?? (() => Date.now());
     this.#relayedChallengeTtlMs = config.relayedChallengeTtlMs ?? DEFAULT_CHALLENGE_TTL_MS;
+    this.#pairingPresenceWindowMs = config.pairingPresenceWindowMs ?? PAIRING_PRESENCE_WINDOW_MS;
   }
 
-  async checkPair(request: unknown): Promise<PairCheck> {
+  async checkPair(request: unknown, session: PresenceSession): Promise<PairCheck> {
     if (!isPairingRequest(request)) {
       return { ok: false, error: 'malformed pairing request' };
     }
@@ -123,6 +142,12 @@ export class Handshake implements HandshakeGate {
     if (request.passkeyPublicKeyHash !== expectedHash) {
       return { ok: false, error: 'passkey public key hash does not match the registered key' };
     }
+    // Presence half for pairing (server-attested; remote-security-model.md,
+    // Pairing Ceremony): the session's last verified assertion must be recent.
+    // The Pocket client maps this error to one re-assert prompt and a retry.
+    if (this.#now() - session.lastVerifiedPresence > this.#pairingPresenceWindowMs) {
+      return { ok: false, error: PAIRING_STALE_PRESENCE_ERROR };
+    }
     return { ok: true };
   }
 
@@ -142,6 +167,7 @@ export class Handshake implements HandshakeGate {
     clientId: string,
     targetHostId: string,
     request: ConnectionRequest,
+    session: PresenceSession,
   ): Promise<Connect2Check> {
     const failures: ConnectionFailure[] = [];
 
@@ -190,7 +216,11 @@ export class Handshake implements HandshakeGate {
       failures.push('passkey-assertion-invalid');
     }
 
-    return failures.length === 0 ? { ok: true } : { ok: false, failures };
+    if (failures.length > 0) return { ok: false, failures };
+    // Any server-verified assertion refreshes the session's presence stamp, so
+    // "connect to host A, then pair host B moments later" needs no re-prompt.
+    session.lastVerifiedPresence = this.#now();
+    return { ok: true };
   }
 }
 
diff --git a/server/src/relay.ts b/server/src/relay.ts
index 08639a16..a6c677dd 100644
--- a/server/src/relay.ts
+++ b/server/src/relay.ts
@@ -34,7 +34,7 @@ import type {
   ServerToHostFrame,
 } from 'server-lib-common';
 
-import type { HandshakeGate } from './handshake.js';
+import type { HandshakeGate, PresenceSession } from './handshake.js';
 
 /**
  * The slice of a WebSocket the hub actually uses. `WSContext` from
@@ -56,6 +56,8 @@ export interface HostConn {
 export interface ClientConn {
   readonly clientId: string;
   readonly socket: RelaySocket;
+  /** The authenticated session behind this socket; the gate reads/refreshes its presence stamp. */
+  readonly session: PresenceSession;
   /** The Host this client is currently talking to, or `null` if unbound. */
   hostId: string | null;
   /** Whether `msg` frames may flow — set true only by an allowed Host decision. */
@@ -194,9 +196,9 @@ export class RelayHub {
   // --- Client lifecycle -----------------------------------------------------
 
   /** Register a freshly-opened Client socket with a fresh secret `clientId`. */
-  registerClient(socket: RelaySocket): ClientConn {
+  registerClient(socket: RelaySocket, session: PresenceSession): ClientConn {
     const clientId = toBase64Url(randomBytes(16));
-    const conn: ClientConn = { clientId, socket, hostId: null, established: false };
+    const conn: ClientConn = { clientId, socket, session, hostId: null, established: false };
     this.#clients.set(clientId, conn);
     return conn;
   }
@@ -246,8 +248,9 @@ export class RelayHub {
         if (frame.t === 'pair') {
           // Only relay a pairing request the authenticated session could have
           // made: the owner account, a registered credential, a matching key
-          // hash. A forged request is answered locally and never reaches the Host.
-          const check = await this.#gate.checkPair(frame.request);
+          // hash, and fresh session presence. A forged or stale request is
+          // answered locally and never reaches the Host.
+          const check = await this.#gate.checkPair(frame.request, client.session);
           if (!this.#isCurrentClientHost(client, frame.hostId, host)) return;
           if (!check.ok) {
             this.#toClient(client, { t: 'pair-result', approved: false, error: check.error });
@@ -259,7 +262,12 @@ export class RelayHub {
         // connect2: the server verifies the assertion (against the STORED key)
         // and challenge freshness before forwarding. On failure the client gets
         // a denial and the Host's challenge stays unburned.
-        const check = await this.#gate.checkConnect2(client.clientId, frame.hostId, frame.request);
+        const check = await this.#gate.checkConnect2(
+          client.clientId,
+          frame.hostId,
+          frame.request,
+          client.session,
+        );
         if (!this.#isCurrentClientHost(client, frame.hostId, host)) return;
         if (!check.ok) {
           this.#toClient(client, { t: 'decision', allowed: false, failures: check.failures });
diff --git a/server/test/handshake.test.mjs b/server/test/handshake.test.mjs
index 0e0b84a2..24605d3d 100644
--- a/server/test/handshake.test.mjs
+++ b/server/test/handshake.test.mjs
@@ -17,7 +17,10 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
 import {
+  API_ROUTES,
   DEFAULT_CHALLENGE_TTL_MS,
+  PAIRING_PRESENCE_WINDOW_MS,
+  PAIRING_STALE_PRESENCE_ERROR,
   REMOTE_EVENTS,
   REMOTE_METHODS,
   SELFHOST_ACCOUNT_ID,
@@ -411,18 +414,26 @@ test('server derives relayed challenge expiry from its own observation clock', a
   clock.advance(DEFAULT_CHALLENGE_TTL_MS - 1);
 
   const assertion = await authenticator.assert({ challenge, origin: ORIGIN, rpId: RP_ID });
-  const result = await gate.checkConnect2('client-1', 'host-1', {
-    accountId: SELFHOST_ACCOUNT_ID,
-    devicePublicKey: 'device-public-key',
-    challenge,
-    deviceSignature: 'device-signature',
-    passkey: {
-      publicKey: authenticator.publicKey,
-      assertion,
+  const session = { lastVerifiedPresence: 0 };
+  const result = await gate.checkConnect2(
+    'client-1',
+    'host-1',
+    {
+      accountId: SELFHOST_ACCOUNT_ID,
+      devicePublicKey: 'device-public-key',
+      challenge,
+      deviceSignature: 'device-signature',
+      passkey: {
+        publicKey: authenticator.publicKey,
+        assertion,
+      },
     },
-  });
+    session,
+  );
 
   assert.deepEqual(result, { ok: true });
+  // A verified connect2 refreshes the session's pairing-presence stamp.
+  assert.equal(session.lastVerifiedPresence, clock.now());
 });
 
 test('server rejects a connect2 that answers a different Host challenge', async () => {
@@ -683,6 +694,53 @@ test('remote terminal: a stale detach for the previous surface does not kill the
   }
 });
 
+test('pairing requires fresh presence: stale session → stale-presence; re-auth → approved', async () => {
+  const clock = makeClock();
+  const created = await freshApp({ now: clock.now });
+  const server = await startServer(created);
+  try {
+    const { body: host } = await enrollHost(created.app, { label: 'Laptop' });
+    const fakeHost = await startFakeHost(server, host, { autoApprove: true });
+    const p = await phone(created.app, server);
+
+    // Let the sign-in's verified presence lapse past the pairing window.
+    clock.advance(PAIRING_PRESENCE_WINDOW_MS + 1);
+
+    const stale = await pair(p, host.hostId);
+    assert.equal(stale.t, 'pair-result');
+    assert.equal(stale.approved, false);
+    assert.equal(stale.error, PAIRING_STALE_PRESENCE_ERROR);
+
+    // Re-assert presence on the SAME session (and the same relay socket):
+    // reauth/begin → WebAuthn assert → reauth/finish.
+    const auth = { 'content-type': 'application/json', authorization: `Bearer ${p.sessionToken}` };
+    const begin = await created.app.request(API_ROUTES.reauthBegin, {
+      method: 'POST',
+      headers: auth,
+      body: '{}',
+    });
+    assert.equal(begin.status, 200);
+    const { challenge } = await begin.json();
+    const assertion = await p.authenticator.assert({ challenge, origin: ORIGIN, rpId: RP_ID });
+    const finish = await created.app.request(API_ROUTES.reauthFinish, {
+      method: 'POST',
+      headers: auth,
+      body: JSON.stringify({ assertion }),
+    });
+    assert.equal(finish.status, 200);
+    assert.equal((await finish.json()).presenceVerifiedAt, clock.now());
+
+    // The retry over the same socket is now relayed and auto-approved.
+    const retried = await pair(p, host.hostId);
+    assert.equal(retried.approved, true);
+
+    p.socket.close();
+    fakeHost.close();
+  } finally {
+    await server.close();
+  }
+});
+
 // A short settle so no test leaves an in-flight frame racing teardown.
 test.after?.(async () => {
   await sleep(10);
diff --git a/server/test/harness/fake-host.mjs b/server/test/harness/fake-host.mjs
index 310ee979..c4e0b594 100644
--- a/server/test/harness/fake-host.mjs
+++ b/server/test/harness/fake-host.mjs
@@ -168,7 +168,8 @@ export class FakeHost extends EventEmitter {
 
     switch (method) {
       case REMOTE_METHODS.hello:
-        ok({ protocolVersion: 1, hostId: this.hostId, grants: { input: true, layout: true } });
+        // Mirror the shipped Host: protocol-v1 grants no layout authority.
+        ok({ protocolVersion: 1, hostId: this.hostId, grants: { input: true, layout: false } });
         return;
 
       case REMOTE_METHODS.directoryWatch: {
diff --git a/standalone/sidecar/pty-core.js b/standalone/sidecar/pty-core.js
index f2b33657..ce67efa7 100644
--- a/standalone/sidecar/pty-core.js
+++ b/standalone/sidecar/pty-core.js
@@ -24,6 +24,9 @@ function resolveDefaultShell(platform = process.platform, env = process.env) {
 }
 
 const LOGIN_ARG_UNSUPPORTED_SHELLS = new Set(['csh', 'tcsh']);
+// Mirrors ITERM2_COMPAT_VERSION in lib/src/lib/terminal-protocol.ts — keep in
+// sync (terminal-escapes.md: one compatibility version across env and device
+// responses).
 const ITERM2_COMPAT_VERSION = '3.5.0';
 
 // bash flags that merely select an interactive and/or login shell. When the args
diff --git a/standalone/src/browser-sidecar-host.ts b/standalone/src/browser-sidecar-host.ts
index 70694398..9dad0c41 100644
--- a/standalone/src/browser-sidecar-host.ts
+++ b/standalone/src/browser-sidecar-host.ts
@@ -1,14 +1,8 @@
 export type BrowserSidecarEvent = { event: string; data: unknown };
 
-type Pending = {
-  resolve: (value: unknown) => void;
-  reject: (error: Error) => void;
-};
-
 export class BrowserSidecarHost {
   private events: EventSource | null = null;
   private readonly eventHandlers = new Set<(event: BrowserSidecarEvent) => void>();
-  private readonly pending = new Map<string, Pending>();
   private nextId = 1;
 
   constructor(private readonly baseUrl: string) {}
@@ -33,8 +27,6 @@ export class BrowserSidecarHost {
   close(): void {
     this.events?.close();
     this.events = null;
-    for (const { reject } of this.pending.values()) reject(new Error('browser sidecar host closed'));
-    this.pending.clear();
   }
 
   onEvent(handler: (event: BrowserSidecarEvent) => void): () => void {
@@ -63,18 +55,9 @@ export class BrowserSidecarHost {
     return body.result as T;
   }
 
+  // Request/response correlation happens over the /invoke HTTP round-trip,
+  // not the SSE stream — every streamed event just fans out to handlers.
   private deliver(event: BrowserSidecarEvent): void {
-    const data = event.data as { requestId?: unknown; error?: unknown };
-    const requestId = typeof data?.requestId === 'string' ? data.requestId : null;
-    if (requestId) {
-      const pending = this.pending.get(requestId);
-      if (pending) {
-        this.pending.delete(requestId);
-        if (typeof data.error === 'string') pending.reject(new Error(data.error));
-        else pending.resolve(event.data);
-        return;
-      }
-    }
     for (const handler of this.eventHandlers) handler(event);
   }
 }