Connecting to the local trimwire cockpit…
+
+ If this persists, start the daemon's cockpit with
+ trimwire cockpit, then reopen this window.
+ The app loads the same control UI the binary serves on
+ 127.0.0.1:8766.
+
&v=1`.
+2. **App scans / types**, connects, **pins the fingerprint** (TOFU — rejects on mismatch
+ thereafter), and presents the pairing code over the cert-pinned channel.
+3. **Token exchange:** daemon validates the code (single-use, unexpired), issues a **per-device
+ bearer token** (256-bit, stored hashed server-side), app stores it in the platform secure
+ store (Keychain/Keystore/DPAPI/libsecret). Pairing code is burned.
+4. **Subsequent calls** present `Authorization: Bearer ` over the pinned channel.
+
+This is the **OAuth 2.0 Device Authorization Grant shape** but fully self-contained — the local
+daemon *is* the authorization server; no external IdP, no trimwire-hosted auth. TOFU cert
+pinning + a pairing code is the documented best practice for local daemons that can't run PKI;
+the code defeats a same-LAN attacker who reaches the port but can't see the host's screen.
+
+**Per-device tokens** live in a `devices` table (separate from the content-free ledger):
+`device_id, label, token_hash, created_at, last_seen, expires_at, capabilities, revoked_at`.
+Revocation is immediate (`trimwire devices revoke `) — the server-side token store *is* the
+revocation list (no CRL). Tokens carry `expires_at` (30–90 days, configurable); optionally
+issue short-lived (5–60 min) access tokens derived from the device token to bound replay.
+
+## 3. Threat model
+
+| # | Threat | Mitigation |
+|---|---|---|
+| T1 | OAuth token theft | token never readable via control API (structural); `upstream` not remotely settable; control responses schema-tested to exclude it |
+| T2 | Daemon hijack to redirect upstream | `upstream` immutable from any remote/control path; `config:write` hard deny-lists `server.upstream`; re-pointing stays a local-file + restart op |
+| T3 | MITM on control channel | TLS required for any non-loopback bind; cert-fingerprint pinning (TOFU); mismatch = hard reject |
+| T4 | Replay | short-lived derived access tokens; TLS; optional per-request nonce/timestamp on writes |
+| T5 | Malicious LAN peer | bind opt-in (off by default); pairing code required to mint a token; rate-limit + lockout |
+| T6 | Exposed-port scanning | default loopback (unreachable); when exposed, TLS + valid token (scanner gets 401); `doctor` warns on non-loopback bind |
+| T7 | DNS rebinding / cross-origin (browser cockpit) | strict `Host`/`Origin` allowlist; same-origin token, no ambient auth |
+| T8 | Relay compromise (v3) | zero-knowledge relay — never sees plaintext/token/stats; can DoS but not read |
+| T9 | Pairing-code brute force | ≥40-bit code, ~120s TTL, single-use, attempt lockout, valid only on the pinned channel |
+| T10 | Stolen/lost device | per-device revocation; expiry; secure-store at rest; remote revoke from host |
+| T11 | Scope confusion (read token used for control) | capability scope checked per-endpoint, deny-by-default |
+| T12 | Detection-evasion creep | **forbidden** — remote control is faithful proxy control only; no obfuscation, no upstream spoofing |
+
+## 4. What v1 MUST NOT preclude — requirements for the v1 control API (doc 03)
+
+Each is cheap now, expensive to retrofit. The control-API design (doc 03) already commits to
+these:
+
+- **R1 — Auth-token abstraction.** Every request flows through an `Authenticator` trait;
+ handlers receive an authenticated `Principal`, never raw trust. v1 impl = `LoopbackToken`.
+- **R2 — Bind-address config + explicit opt-in.** Bind is a config field; v1 ships loopback-only
+ and **refuses** any non-loopback bind (error points at the future opt-in).
+- **R3 — TLS-readiness.** The listener is constructed through an abstraction that can wrap a
+ rustls acceptor (config-driven branch). Cert/key paths reserved in config (unused in v1).
+- **R4 — Per-request device identity.** Handlers operate on `Principal { device_id, scopes,
+ channel }`, even when v1 fills a synthetic "local" principal.
+- **R5 — Capability scoping.** Define caps now (`stats:read`, `ledger:read`, `service:toggle`,
+ `profile:switch`, `config:read`, `config:write` [upstream-excluded], `sweep:run`,
+ `summarizer:manage`); each endpoint declares its required cap; deny-by-default.
+- **R6 — Upstream-credential firewall.** Control handlers live in a module that *cannot* import
+ the proxy credential; `config:write` hard deny-lists `server.upstream`; **a CI test asserts no
+ control response field derives from the upstream credential.**
+- **R7 — Host/Origin validation hook** (defeats DNS-rebinding) — built now, even loopback.
+- **R8 — Versioned, content-free, token-free API contract** (`/api/v1`); pairing/`devices`
+ endpoints stubbed/absent in v1 but the version prefix + content-free discipline hold.
+- **R9 — Rate-limit/lockout seam** on the auth layer (no-op/generous in v1).
+- **R10 — Secure local-credential storage** (`0600` token in `~/.trimwire/`) — the convention the
+ `devices` table extends.
+
+## 5. Phasing & the gate at each step
+
+| Phase | Transport / bind | Auth | Gate to ship |
+|---|---|---|---|
+| **v1 — local loopback** | `127.0.0.1` only; refuses non-loopback | local principal (R1) + `0600` token (R10) | seams R1–R10 present & tested; **token-leak CI test is the merge gate** (R6) |
+| **v2a — Direct LAN (opt-in)** | LAN bind + mDNS + self-signed TLS | per-device tokens via QR/pairing TOFU; scopes (R5); revocation/expiry | off by default; refuses to expose without TLS+pairing; Host/Origin active; pairing rate-limit; `doctor` warns |
+| **v2b — BYO overlay (recommended)** | **daemon stays loopback**; user's overlay forwards | same per-device-token layer (defense in depth atop overlay keys) | bind unchanged from v1 (best posture); docs only; pairing still required |
+| **v3 — relay / reverse tunnel** | zero-knowledge rendezvous OR user-owned tunnel; off by default | E2E; per-device tokens unchanged; relay token/content-blind | build only if BYO friction demands it; provably content/token-blind; abuse/DoS plan |
+
+**Gate principle:** every phase is off by default, requires explicit opt-in, and cannot regress
+the token invariant. Each step up the ladder widens *reachability*, never *trust* — the
+auth/scope/credential model is identical from v2 onward; only the transport changes.
+
+## Sources
+
+Tailscale `tsnet` docs + `tailscale-rs` preview; mDNS/DNS-SD references; OAuth 2.0 Device
+Authorization Flow (Descope) + IETF cross-device security BCP; self-signed TLS client-auth /
+fingerprint-pinning patterns; bearer-token best-practice guides. Full URLs in the session
+transcript.
diff --git a/docs/cockpit/07-security-tos-redlines.md b/docs/cockpit/07-security-tos-redlines.md
new file mode 100644
index 0000000..6140964
--- /dev/null
+++ b/docs/cockpit/07-security-tos-redlines.md
@@ -0,0 +1,116 @@
+# 07 — Security, ToS & Red Lines (the disagree-seeking review)
+
+> This doc is deliberately adversarial. While the other docs design an exciting cockpit, this
+> one steelmans the case **against** building it — or against building parts of it — and where
+> it drifts from trimwire's identity. It is anchored in trimwire's *own* code, not speculation.
+> **The red lines here are non-negotiable constraints on everything else in this folder.**
+
+## The dissent in five sentences
+
+1. trimwire's whole value is "one small static binary, no heavy runtime deps, transparent and
+ ToS-compliant." A full-control local API + remote stack + native multi-platform app is the
+ single biggest scope expansion the project could make — driven by a *metaphor* ("cockpit"),
+ not measured user demand.
+2. The codebase already encodes, in `config.rs`, that **the most dangerous thing in the system is
+ "where does the Bearer token get sent"** — a mutating control API is a new write path into
+ exactly that surface, and a remote port is a network-reachable handle on a process holding a
+ Claude OAuth token.
+3. "Remote control of your Claude proxy" reads, to an enforcement team, like the redistributed-
+ token pattern that **already got OpenClaw/OpenCode/Cline killed in 2026** — even if
+ implemented innocently, it moves trimwire from *passive-gray* toward something that *looks*
+ active.
+4. The content-free guarantee holds today because the ledger *literally cannot* hold content;
+ several proposed panes ("preview what's pruned," "inspect sessions") create pressure to read
+ **raw transcripts** into a UI — the one move that breaks it.
+5. The existing `trimwire dashboard` HTML + statusline + CLI already deliver ~90% of the
+ cockpit's read value at ~0% of its risk.
+
+## Risk register
+
+| Risk | Likelihood | Severity | Mitigation |
+|---|---|---|---|
+| Control API exposes a config-write path that can redirect the OAuth token (`upstream`/summarizer URL) | Med | **Critical** | R1: forbid those keys from the API; reuse the existing global-only guard + its regression test |
+| Localhost control port hit by a malicious web page (CSRF → config write / info disclosure) | **High** if unguarded | Critical | R4: per-install bearer secret + Host/Origin checks; loopback bind |
+| "Remote control of your Claude proxy" pattern-matches enforcement → ToS/account action | Med | **Critical** | R6: defer + gate on ToS re-review; v1 loopback-only; keep the "compliant" brand |
+| Preview/inspect pane renders transcript content → breaks content-free guarantee | **High** (UX pull) | High | R7+R8: counts/structure only; ledger-and-`--json`-only data sources; never read live transcripts |
+| Native multi-platform + mobile build/signing burden sinks solo velocity | High | High | ship a PWA; no native app / mobile in the minimal v1 |
+| JS SPA + node_modules reverses the lightweight ethos / adds supply-chain surface | Med | Med | reuse the existing dashboard front-end machinery; no heavy SPA framework; JS is build-time only |
+| Remote relay creates recurring infra cost + uptime/abuse obligation | Med (if built) | High | don't build it in v1; BYO overlay (doc 06) needs no infra |
+| Mutation logic creeps into `gateway.rs`, eroding layer discipline | Med | Med | R9: separate `admin/` module/router; gateway stays non-mutating |
+| Scope absorbs bandwidth AGENTS.md reserves for CODE > DX | High | Med | decouple the cheap read view from the expensive control/remote/app; ship the cheap half first |
+
+## RED LINES (must not be crossed — bind every other doc)
+
+- **R1** — The control API can **never** write `server.upstream` or any summarizer
+ `base_url`/`full_url`. Route any config write through the same global-only guard, or forbid
+ those keys outright.
+- **R2** — The control API **stays bound to `127.0.0.1`** in v1; **no** `0.0.0.0`/LAN bind option
+ ships in v1.
+- **R3** — The API **never** returns the OAuth token, `Authorization` header, or any derived
+ value, and **never** exposes a "test/ping upstream" endpoint that originates a call on the
+ subscription token.
+- **R4** — The API **defends against drive-by browser requests**: a per-install bearer secret +
+ Host/Origin checks on every call. A localhost port is **not** a security boundary against local
+ web pages.
+- **R5** — **No detection-evasion, ever** — no client-fingerprint spoofing, header-order mimicry,
+ or proxy-hiding.
+- **R6** — **Remote control is deferred AND gated on an explicit, written ToS re-review** before
+ any relay/exposure code. "Do not design the relay until we've re-checked enforcement posture."
+ (Designing the *API shape* for remote-additivity, per doc 06 R1–R10, is fine; standing up
+ network infrastructure is not.)
+- **R7** — **No UI pane renders message content, prompts, tool-result bodies, or file paths.**
+ Preview shows counts, byte deltas, strategy names, block *types* — never the bytes.
+- **R8** — The API's data sources are **the ledger + content-free `--json` outputs only.** No
+ reading of `~/.claude/**` transcript bodies into any UI surface.
+- **R9** — The control API lives in its **own module/router**, not inside `gateway.rs` (which the
+ layer rules say must not contain mutation). Don't erode the layer discipline that keeps the
+ core testable.
+
+## Fresh-sources update (doc 10)
+
+A second adversarial pass against 2026 sources added these constraints (full detail +
+citations in [doc 10](10-security-fresh-sources.md)):
+
+- **R4 strengthened:** Host-pin is necessary-but-not-sufficient. Require a **`Sec-Fetch-Site`**
+ gate **and** a **custom preflight-forcing header** on writes, ordered before the token check.
+- **Token-in-HTML is a tradeoff, not solved:** any XSS exfiltrates the control token → require
+ a **strict CSP** (nonces, not `'unsafe-inline'`) or move to an **`HttpOnly` cookie handshake**;
+ native client reads the token from the **OS keychain**.
+- **New ToS note (R6 reinforced):** the 2026-02-20 clarification has **no carve-out for local
+ proxies/middleware**, and the **base passthrough proxy itself** (which modifies request bodies)
+ is grayer now — pre-write the affirmative compliance argument; keep remote hard-gated.
+- **Browser LNA (Chrome 142) does NOT cover localhost→localhost** — don't lean on it.
+
+## The safest minimal viable cockpit (the dissent's counter-proposal)
+
+If trimwire wanted the *smallest* responsible step:
+
+1. A **local-only, read-mostly page served by the binary**, reusing `dashboard.rs` +
+ `dashboard_template.html`. Data: ledger + content-free `--json`. ~90% of the value, ~0% new
+ risk.
+2. **Control limited to three verbs:** on/off; switch profile (`default`⇄`gentle`); a
+ **whitelisted** subset of strategy knobs applied via restart — **never** `upstream`/summarizer
+ endpoints. No general config-write; no sweep-from-UI in the minimal cut (sweep mutates on-disk
+ transcripts — keep it auditable in the CLI initially).
+3. **Ship as a PWA, not a native app.** Zero native build matrix, zero signing, zero app-store
+ tax. No mobile in the minimal v1.
+4. **No remote, at all, in the minimal v1.** Loopback only; design the data model for a future
+ remote phase but don't build (or design the relay for) it until the ToS re-review (R6).
+
+## How the rest of this folder reconciles with the dissent
+
+The plan does **not** ship the maximal version all at once. The reconciliation (see
+[README](README.md) and [roadmap](08-roadmap.md)):
+
+- The **roadmap's v0/v1 ≈ this minimal proposal** — local, content-free, binary-served, bounded
+ control. That's what gets built and proven first.
+- **Full config control, the native app, LAN/overlay remote, and mobile are later phases**, each
+ behind the red lines above and an explicit security/ToS gate.
+- The control-API design (doc 03) and the remote design (doc 06) already adopt R1–R9 as
+ load-bearing requirements — the separate loopback admin listener, the upstream-credential
+ firewall with a CI leak test, Host/Origin validation, content-free events, and the
+ "designed-for-but-deferred" remote seams are direct responses to this review.
+
+So this doc isn't an objection the plan ignores — it's the **constraint system the plan is built
+inside.** If a future change conflicts with a red line here, the red line wins, or the change
+needs explicit maintainer + ToS sign-off.
diff --git a/docs/cockpit/08-roadmap.md b/docs/cockpit/08-roadmap.md
new file mode 100644
index 0000000..d057882
--- /dev/null
+++ b/docs/cockpit/08-roadmap.md
@@ -0,0 +1,116 @@
+# 08 — Roadmap
+
+> The phased plan that ties docs 03–07 together. Each phase is **off by default until the prior
+> one is proven**, ships through the existing PR/CI flow, and is bounded by the red lines in
+> [doc 07](07-security-tos-redlines.md). The destination is the cockpit the maintainer asked for
+> (full control, multi-platform app, phased remote); the sequencing is what makes getting there
+> safe.
+
+## Phase map at a glance
+
+| Phase | Deliverable | Reach | Risk | Gate to start |
+|---|---|---|---|---|
+| **v0** | Read-only cockpit (live, served by the binary) | local loopback | very low | none — it's a reskin of `dashboard` |
+| **v1** | Full **local** control (the control API + Flightdeck UI), **installable as a PWA** | local loopback | low–med | v0 shipped; red lines R1–R9 enforced; token-leak CI test green |
+| **v2** | **Tauri desktop wrapper** of the same PWA (tray, autostart, sidecar) | local | med | v1 shipped; shell is a thin client of the v1 API |
+| **v3** | **Remote** control (BYO overlay + opt-in LAN) — the **PWA over TLS/overlay** | cross-network, opt-in | high | **written ToS re-review (R6)**; remote seams from v1 in place; pairing/devices built |
+| **v4** | **Mobile = the PWA** (Add-to-Home-Screen, no store/fee); native APK only if ever needed | remote | low–med | v3 shipped (for cross-device); **no Apple/Play pipeline required** |
+
+## v0 — Read-only cockpit (the cheap, near-free win)
+
+**What:** upgrade `trimwire dashboard` into a live, locally-served page. Reuse `dashboard.rs` +
+`dashboard_template.html` + the site's dashboard components + design tokens. Data: ledger +
+`stats`/`recall`/`preview --json`. **No control actions**, **no remote**, content-free.
+
+**Why first:** it's ~90% of the perceived value at ~0% new risk, validates the UI/design, and
+ships before any of the contentious surface exists. Maps to the disagree-seeking review's
+"safest minimal" read view (doc 07).
+
+**Backend need:** minimal — could even be the static HTML report plus a tiny read-only loopback
+serve. If building toward v1, start the `admin/` read endpoints here (control-API PR 1, read-only
+subset).
+
+## v1 — Full local control
+
+**What:** the control API (doc 03, PRs 1–5) + the Flightdeck UI (doc 04) with full control:
+on/off, profile switch, validated config + per-strategy knobs (restart-or-hot-reload), preview,
+sweep (dry-run-first), summarizer, share opt-in, live SSE monitor. **Loopback only.**
+
+**Non-negotiables (doc 07):** separate `127.0.0.1:8766` admin listener (R2, R9); bearer token +
+Host/Origin guard (R4); `config:write` deny-lists `server.upstream`/summarizer URLs (R1, R3);
+content-free panes & data sources only (R7, R8); no detection-evasion (R5). **The token-leak CI
+test (doc 06 R6) is the merge gate.**
+
+**Frontend stack decision:** vanilla DOM vs **Svelte** (doc 04 §2). Given the site is being
+rebranded to Svelte+Astro, the recommendation is to build the cockpit in **Svelte** so it shares
+one idiom + component library with the new site — *unless* the cockpit ships before the rebrand,
+in which case start vanilla (a direct lift) and port later (mechanical; data contracts + tokens
+don't change). **Open for maintainer confirmation.**
+
+**PWA in v1:** the binary serves a Web App Manifest + icon (already in the POC), so v1 is
+**installable** — desktop browsers get "Install app", and phones on the same machine/overlay get
+Add-to-Home-Screen. This is the *multi-platform app* for most users; v2 is just a nicer desktop
+shell on top.
+
+**Exit:** people actually use it locally. That usage is the evidence (AGENTS.md: "measure, don't
+guess") that justifies climbing to v2+.
+
+## v2 — Tauri desktop wrapper (optional convenience)
+
+**What:** a Tauri 2 desktop shell wrapping the **same** PWA bundle (doc 05). Shape **A**
+(talk-to-running-daemon) first; optional sidecar mode (B) later. Adds desktop packaging to the
+existing 3-platform CI via `tauri-action`. **Still local** — the shell talks to `127.0.0.1:8766`.
+It adds tray/autostart/sidecar + OS-keychain token storage; it does **not** add a new UI.
+
+**Why after v1, and why optional:** the shell is a thin client of the v1 API, and the PWA already
+covers "an installable app on every platform." Tauri is a desktop *enhancement*, not the thing
+that makes the cockpit multi-platform. The HTTP-first design means v2 is low-regret (if Tauri
+disappoints, the PWA still works).
+
+## v3 — Remote control (the gated leap)
+
+**What:** reach a daemon on another machine. **Primary: BYO overlay (Tailscale/WireGuard)** — the
+daemon stays loopback, the user's overlay forwards (trimwire ships no infra). **Plus opt-in
+Direct LAN** (mDNS + self-signed TLS + QR/pairing-code TOFU). Per-device tokens, capability
+scopes, revocation/expiry (doc 06).
+
+**Hard gate (doc 07 R6):** a **written ToS re-review before any exposure/relay code.** "Remote
+control of the process holding your Claude OAuth token" is the feature most likely to spend
+trimwire's compliance moat — it must be deliberate, off by default, and never expose the token or
+make `upstream` remotely settable. The v1 control API already ships the additive seams (doc 06
+R1–R10) so this is new endpoints (`/pair`, `/devices`) + a transport, not a v2 API.
+
+**Relay (c)/reverse-tunnel (d) are v3.x last resorts** — zero-knowledge, off by default, built
+only if BYO-overlay friction demands it.
+
+## v4 — Mobile (no paid app store)
+
+**What:** a phone client (remote controller) = the **same web frontend as an installable PWA**
+(add-to-home-screen on iOS + Android, $0, no store) — the recommended default. Optionally a
+**Tauri-Android / Capacitor APK** distributed via **GitHub Releases + F-Droid** (also $0, no Play
+account) if a native Android shell is wanted. **No Apple Developer / Google Play fee is required**
+(maintainer constraint), and **Flutter is not the fallback** — it's always the same web frontend
+(doc 05 §4). Depends on v3 (remote) being in place for cross-device control.
+
+## Cross-cutting workstreams
+
+- **Docs:** update `ARCHITECTURE.md` (new `admin/` module + layer rows + decision log),
+ `CONFIGURATION.md` (`[admin]`), `SECURITY.md` (loopback+token+Host-pin model, content-free
+ events) as the relevant phase lands.
+- **Tests:** content-free event test (mirrors `audit.rs`); token-leak CI test; **API contract
+ tests** so the cockpit can't break when CLI commands change (`/api/v1` shape pinned; byte-equal
+ to `--json` from the shared builder — doc 11); atomic-write crash-safety; hot-reload visibility.
+- **Parity oracle:** untouched throughout — the control plane never touches `strategies/` or
+ `pairing/`.
+
+## Decision log (open questions for the maintainer)
+
+1. **Frontend stack:** Svelte (recommended given the site rebrand) vs vanilla-now-port-later?
+2. **How far is v1's config control?** Full validated editor (doc 03) vs the disagree-seeking
+ review's bounded "on/off + profile + whitelisted knobs" (doc 07)? Recommendation: ship the
+ bounded version in v1, expand to the full editor once the write path + restart UX are proven.
+3. **App home:** workspace member vs sibling repo (doc 05 §7)?
+4. **Is mobile (v4) actually wanted,** or is multi-platform satisfied by desktop + PWA?
+5. **Visible name:** Flightdeck / Console / Panel (doc 04 §6)?
+
+These don't block v0/v1 — they shape v2+. None requires answering tonight.
diff --git a/docs/cockpit/09-poc.md b/docs/cockpit/09-poc.md
new file mode 100644
index 0000000..fef1b99
--- /dev/null
+++ b/docs/cockpit/09-poc.md
@@ -0,0 +1,91 @@
+# 09 — Proof of Concept (small, but touches every layer)
+
+> A deliberately small but **end-to-end vertical slice** of the cockpit, built on
+> this branch. It compiles clean (`fmt` / `clippy -D warnings` / full test suite)
+> and runs. It is **off by default** — the daemon is byte-for-byte unchanged unless
+> you opt in via `[admin] enabled = true` or run `trimwire cockpit`.
+
+
+
+*The running cockpit: teal Flightdeck brand, a live "gateway serving" indicator,
+content-free KPI cards from the local ledger, and a working SSE feed — served by
+the trimwire binary on a loopback-only control API.*
+
+## What the POC includes (every layer, minimally)
+
+| Layer (plan doc) | POC artifact | State |
+|---|---|---|
+| **Control API** (doc 03) | `src/admin/mod.rs` — separate **loopback admin listener** (`127.0.0.1:8766`), kept off the token-bearing gateway port | real |
+| ↳ Auth seam (doc 06 R1) | `Authenticator` trait + `LoopbackToken` impl; 256-bit bearer token at `~/.trimwire/control.token` (`0600`), constant-time compare | real |
+| ↳ DNS-rebind / CSRF guard (doc 03 §5, doc 06 R7) | authority (`Host`/h2 `:authority`) allowlist + same-origin `Origin` + `Sec-Fetch-Site` — three gates, ordered before auth | real |
+| ↳ Token-page XSS hardening (doc 10 G3) | per-render **nonce CSP** (no `'unsafe-inline'`, `worker-src 'none'`) + `X-Frame-Options: DENY` on the token-bearing HTML | real |
+| ↳ Read endpoints | `GET /api/v1/{health,version,service,stats}` — `stats` reuses the content-free ledger `Report`; `version` omits `upstream` | real |
+| ↳ Live events (doc 03 §4) | `GET /api/v1/events` — SSE, content-free aggregate snapshot | real (one-shot; prod uses a broadcast channel) |
+| **Web cockpit** (doc 04) | `src/admin/cockpit.html` — embedded single-file UI, teal design tokens, same-origin token bootstrap, KPIs + SSE log | real (vanilla; prod may use Svelte) |
+| ↳ **PWA install** (doc 05 — PWA-first) | served `GET /manifest.webmanifest` + `GET /icon.svg`, linked from the HTML → **installable** ("Install app" / Add-to-Home-Screen, no store) | real (manifest+icon; service worker is a follow-up) |
+| ↳ CLI surface | `trimwire cockpit` subcommand + `[admin]` config section | real |
+| **Multi-platform app** (doc 05) | **PWA-primary** (the page above is the app on every platform) + `app/` Tauri 2 desktop-shell scaffold | PWA real; Tauri scaffold (not in CI) |
+| **Remote** (doc 06) | non-loopback bind **refused** at startup; auth/identity seam present | seam only (deferred, by design) |
+| **Security red lines** (doc 07) | loopback-only, token never exposed, `upstream` never written **nor returned**, content-free responses, separate module (not in `gateway.rs`) | enforced |
+
+## Run it
+
+```bash
+# Easiest: one command starts the gateway + the control API + the web UI.
+trimwire cockpit
+# [cockpit] open http://127.0.0.1:8766 in your browser
+
+# Or enable it permanently for the always-on daemon:
+# ~/.config/trimwire.toml
+# [admin]
+# enabled = true
+# listen = "127.0.0.1:8766"
+```
+
+The control token is printed/located at `~/.trimwire/control.token`. The browser UI
+is handed it same-origin at page load; CLI/curl callers pass
+`Authorization: Bearer `.
+
+## Verified behaviour (smoke test)
+
+```
+GET /api/v1/health → 200 {"ok":true,"version":"0.3.16"} (unauth)
+GET /api/v1/stats (no token) → 401 unauthorized
+GET /api/v1/stats (Bearer token) → 200 full content-free ledger Report
+GET /api/v1/version (Bearer token) → 200 {version, control_api, profile, listen addrs}
+ (NO `upstream` — credential routing never crosses the wire)
+GET /api/v1/service (Bearer token) → 200 {serving:true, ...} (live gateway probe)
+GET /api/v1/health (Host: evil.com) → 403 forbidden: bad Host (DNS-rebind guard)
+GET /api/v1/health (Origin: evil) → 403 forbidden: bad Origin (cross-origin guard)
+GET / → HTML, token injected, nonce-CSP (no `'unsafe-inline'`)
+```
+
+Plus 13 unit tests in `src/admin/mod.rs` (constant-time compare, authority/Origin/
+`Sec-Fetch-Site` guards, bearer extraction, token generation = 256-bit hex + stable +
+concurrency-safe, authenticator accept/reject, `/version` contract incl. **`upstream`
+absent**, `/stats` content-free, PWA manifest, nonce-CSP, HTML-placeholder guard) and a
+`[admin]`-global-only regression test in `src/config.rs`. Full suite stays green:
+`cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test --all-features`.
+
+## What is deliberately NOT in the POC
+
+- No config **write** / hot-reload (read + control-shape only); no `ArcSwap` refactor.
+- No socket-activation for the admin port (plain loopback bind).
+- No real streaming SSE (one-shot snapshot; `EventSource` reconnects make it live-ish — and
+ each reconnect re-runs a ledger `report()` query, so an open tab polls ~every 2s. Production
+ replaces this with a broadcast channel fed at ledger-write time, doc 03 §4).
+- No custom **`X-Trimwire-Control`** preflight-forcing header — not needed yet (the POC is
+ read-only + token-gated), but **required before any mutating endpoint** (`POST /service/*`,
+ `PUT /config`) lands, per doc 10 G1.
+- No remote transport, pairing, or `devices` table (deferred phase — only the seams).
+- The Tauri `app/` is a scaffold: it shows the shape but is not built by CI and needs
+ the Tauri toolchain to run.
+
+These are the exact follow-ups itemized in docs 03/06/08 — the POC is the first
+slice of that plan, not a shortcut around it.
+
+## New dependencies
+
+**None.** The control API reuses `hyper` / `http-body-util` / `tokio` / `serde_json`
+/ `getrandom` / `hex` already in the dependency tree — honoring the single-static-
+binary, no-heavy-runtime-deps ethos.
diff --git a/docs/cockpit/10-security-fresh-sources.md b/docs/cockpit/10-security-fresh-sources.md
new file mode 100644
index 0000000..7fadf10
--- /dev/null
+++ b/docs/cockpit/10-security-fresh-sources.md
@@ -0,0 +1,133 @@
+# 10 — Security: Fresh-Sources Addendum (2026 review)
+
+> A second, adversarial research pass against the plan using sources the other docs
+> do **not** cite (independent / 2025–2026-dated). It found four things the plan got
+> right, and several real gaps. The corrections below are folded back into docs 03,
+> 04, 07, 02 by reference, and the cheap ones are already implemented in the POC
+> (doc 09). Citations are inline.
+
+## What the plan got right (confirmed)
+
+1. **Treating localhost as hostile is correct.** The Ollama DNS-rebinding CVE
+ (CVE-2024-28224) is a localhost daemon with *no* Host pinning getting full remote
+ API access from a malicious web page — exactly the attack the Host-pin guards.
+ ([NCC Group](https://www.nccgroup.com/research/technical-advisory-ollama-dns-rebinding-attack-cve-2024-28224/))
+2. **"Bearer token, not a cookie → CSRF structurally prevented" is the strongest part
+ of the design** — a token in an `Authorization` header is not ambient/auto-attached.
+ ([OWASP CSRF](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html))
+3. **Serving the UI same-origin on the admin port** (CORS stays default-deny) is right,
+ and `http://localhost` / `127.0.0.0/8` are "potentially trustworthy" secure contexts,
+ so the page can use SubtleCrypto and isn't mixed-content-blocked.
+ ([W3C Secure Contexts](https://www.w3.org/TR/secure-contexts/))
+4. **"Defer remote, stay loopback, no detection-evasion" (R5/R6) is vindicated by 2026
+ events** — Anthropic's Jan–Apr 2026 crackdown killed exactly the named tools.
+ ([The Register, 2026-02-20](https://www.theregister.com/2026/02/20/anthropic_clarifies_ban_third_party_claude_access/))
+
+## Gaps and corrections
+
+### G1 — Host-pin alone is too thin; add two more independent gates *(highest priority)*
+
+DNS rebinding **defeats Origin checks** (the attacker's page origin is unchanged; only
+the resolved IP flips), so Host-pin is the *only* barrier in the original design — and a
+single allowlist bug collapses it. A cross-site **simple request** (`GET`/form `POST`)
+reaches localhost with **no preflight**, so a *blind write* needs no response-read.
+
+**Mitigations (defense-in-depth, independent of Host-pin correctness):**
+- **`Sec-Fetch-Site` enforcement** — browser-set, page-unforgeable; reject anything not
+ `same-origin`/`none`. **Implemented in the POC** (`src/admin/mod.rs` `sec_fetch_site_ok`).
+- **A custom non-simple header on mutating endpoints** (e.g. `X-Trimwire-Control: 1`) to
+ force a CORS preflight that default-deny CORS fails. The POC is read-only + token-gated,
+ so this is a **production requirement** for when `POST /service/*` / `PUT /config` land.
+- **Order all gates before the token compare and before any side effect** — a rebinding
+ caller never reaches auth even if the token check had a bug. **Done in the POC.**
+
+([OWASP CSRF](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html),
+[Mixmax: CORS-as-CSRF](https://www.mixmax.com/engineering/modern-csrf))
+
+### G2 — Browser Local Network Access does NOT cover localhost→localhost
+
+Chrome shipped **Local Network Access** (LNA, ex-PNA) in **Chrome 142 (2025-10-28)**,
+gating *public-site → loopback* behind a permission prompt — good for the public drive-by
+case. **But the same announcement says localhost→localhost is NOT yet gated**, and the old
+PNA CORS preflight was **withdrawn**. So: a malicious *other localhost app* is unchanged by
+LNA, and the plan must **not** lean on browser network-access prompts — the G1 gates carry
+the sibling-localhost threat. ([Chrome for Developers](https://developer.chrome.com/blog/local-network-access),
+[chromestatus](https://chromestatus.com/feature/5152728072060928))
+
+### G3 — "Token injected into served HTML" is a tradeoff, not "solved"
+
+Any **XSS in the cockpit UI exfiltrates the control token** (then full control). Precedent
+is mixed (VS Code's connection-token is widely seen as the weak link). Corrections:
+- **Mandatory strict CSP** (nonces, not `'unsafe-inline'`) on the token-bearing page.
+ **Done in the POC:** the cockpit HTML is served with a **per-render nonce CSP**
+ (`script-src 'nonce-…'; style-src 'nonce-…'; worker-src 'none'`, no `'unsafe-inline'`) via
+ `html_response` in `src/admin/mod.rs`; an injected `
+