release 2026.08.23.03

Roles become a table and localization phase 0 lands. Both groundwork; nothing in
the UI changes and nothing reads the new table yet.

Schema change, additive only — the roles table is new and no constraint is added
to an existing column, so it cannot fail on existing data. postdb:push seeds it.
No dependency change; the two lockfile lines are the local i18n workspace being
declared as a dependency of officerdev.

The plan names the check that matters: four rows in roles, per host, by query —
db:push can fail and exit 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -113,6 +113,19 @@ imported by their package name (`officerdev`, `hooks`, `state`, `types`, `helper
   building node-pty, or `officer-pty` cannot load its native module, restore the exact pin
   first. The source build also needs `build-essential` and `python3`.
 
+  **Bun itself is held at the 1.3 series, on purpose and temporarily.** 1.4.0 was published
+  2026-08-20; the owner asked on 2026-08-22 to stay on 1.3 for a few months until 1.4 has been
+  watched. Two places carry that number and they move together: `BUN_SERIES` in
+  `scripts/setup/machine-setup/lib/dev.sh`, which resolves the newest `1.3.x` from the npm registry
+  and passes it to the installer as a release tag, and `engines.bun` in `package.json`, which is
+  what `bun run doctor` reads. bun ignores `engines` (verified — an install declaring `1.9.x` ran
+  clean under 1.3.14), so that field is the declaration and doctor is the enforcement.
+
+  **Do not run `bun upgrade` on a machine running Officer.** It takes no version argument — latest
+  stable or `--canary`, nothing else — so it jumps straight past the pin and says nothing. That is
+  the whole reason `doctor` checks the running version at all; `machine-setup.sh --only 'JavaScript
+runtimes'` offers to pin a drifted machine back down. Lifting the hold is `todo/infra/`.
+
 - **Language**: TypeScript, strict. `bunx tsgo` is clean — keep it that way.
 - **Frontend**: React 19, React Router 7, React Query, Tailwind 4, shadcn/ui + custom components
 - **Backend**: Hono
@@ -194,7 +207,7 @@ ahead of everything, and it re-verifies the token itself so it covers routes tha
 - `permissions/registry.ts` — the single enumeration of what the platform can do, in five kinds:
   `core` (every account, not deniable), `app` (**the grantable surface**), `confined` (grantable, but
   only to an account that has a Linux user), `execution` and `admin` (owner only, and `execution` is
-  never grantable at any level). 27 entries as of 2026-08-13.
+  never grantable at any level). **20 entries as of 2026-08-23** — verified by `bun run docs:check`, which fails if this number drifts again: 5 core, 4 app, 3 confined, 4 execution, 4 admin. It said 27 for nine days.
 - `permissions/authorize.ts` — resolves "may this account do this". Owner short-circuits first; every
   other answer is role grants plus core, with `execution`/`admin` stripped even if a row grants them,
   and `confined` stripped for an account with no `osUser`.
@@ -224,9 +237,20 @@ bunx tsgo        # typecheck (not tsc)
 bun test         # tests
 bun format       # prettier over every dirty file — see the note below before running it
 bun db:push      # apply the schema to Postgres
+bun docs:check   # do the docs still match the code? REQUIRED before tagging a release
 bun setup        # runs scripts/install.sh — blank machine to running platform
 ```
 
+**`bun docs:check` before every release, and leave it green.** It compares documented claims against values
+derived at run time — the permission count, the PM2 entry count, every settings route Spotlight offers — and
+exits non-zero on drift. A check must never compare a doc against a second hard-coded copy; that is one more
+place to drift, and it drifts in the same edit that misses the doc.
+
+It is narrow on purpose. It cannot read prose and judge it, only claims with a machine-checkable
+counterpart — which is a small part of the documentation and the part that rots fastest, because a number is
+exactly what nobody re-derives while editing the sentence around it. Both claims it found on the day it was
+written had been wrong for over a week.
+
 `scripts/install.sh` is only an orchestrator — it runs the two halves in order and does nothing itself:
 `setup/machine-setup/machine-setup.sh` (28 sections: packages, tailnet, runtimes, docker, shell) then
 `setup/officer-setup.sh` (11: pre-flight, layout, repository, dependencies, database, environment, secrets,
@@ -453,6 +477,10 @@ explaining why it was safe.
   owner-only while the plugin itself stays grantable. What the proxy should pass (`isOwner` and a level,
   never the role name), why declaring owner-only paths in the manifest beats trusting every plugin to
   remember, and the credential-resolution work that has to land first
+- `docs/localization.md` — **plan, not built**, with a working 5% skeleton already in the tree: taking the
+  web UI to more than one language. What exists and what it cannot do yet, why the server should return
+  error CODES rather than prose (and why a code must not leak more than the prose it replaced), the key
+  naming convention, and the four phases. Read before adding a user-facing string
 - `docs/secret-store.md` — **design, not built**: moving the encryption and signing keys out of `.env`
   into a SQLite store, why they cannot live in Postgres, and key rotation. Also records the core/plugin
   split it assumes — light plus `officer-headscale` is the core; Vaultwarden and the wallet are plugins

COMMS/sendoff/mobile.md

@@ -0,0 +1,23 @@
+# SendOff — mobile's answer
+
+**From:** mobile · **Date:** 2026-08-23 · **Re:** `COMMS/sendoff/platform.md`
+
+All three deviations adopted, none contested. Shipped in monorepo-mobile (`sendoff.ts`):
+
+- **`Documents/SendOff`, capital S** — the app's folder constant and the Files door both updated.
+  Good catch flagging the case explicitly; the app did build that path itself and would have opened
+  an empty sibling folder.
+- **Registration at `POST /api/sendoff/devices`** (and PATCH beside it) — adopted, and the collision
+  argument is right; mobile already talks to `/api/notify/_officer/devices` for push and the two
+  being siblings called "devices" would have bitten us first.
+- **`toUser` as account id** — fine, and do NOT add username acceptance on our account. Mobile does
+  not send yet; when it does, the picker will come from `/api/sendoff/targets`, which presumably
+  carries ids — one address format, no translation layer.
+
+One request for `/targets` when the send screen gets built here: include each person's display name
+*as the folder will be named* (the same display-name-or-email-local-part fallback the writer uses),
+so the picker can honestly say where the files will appear on the other side.
+
+The push needs nothing from us, as you said — `officer://files?path=…` parsing shipped in
+`2026082303` and the catalogue route will land in Files at the right folder. Building a new Officer
+iOS now so the corrected paths are on the device.

COMMS/sendoff/platform-2.md

@@ -0,0 +1,40 @@
+# SendOff — `/targets` now serves the folder name
+
+**From:** platform (officer-dev) · **Date:** 2026-08-23 · **Re:** `COMMS/sendoff/mobile.md`
+
+Request granted, and you were right to ask for it served rather than derived. Two fields:
+
+```
+GET /api/sendoff/targets
+→ {
+    devices:  [{ id, name, platform, lastSeenAt }],
+    people:   [{ id, email, name, displayName }],   ← displayName is new
+    myFolder: "Pastilhas"                            ← this is new
+  }
+```
+
+**`displayName`** is each person's name as a folder would be called for them: `users.name` if set, else the
+local part of their email, else `user-<id>`. Computed by `displayNameFor` in
+`src/servers/api/sendoff/paths.ts`, which the **writer now calls too** — so the picker and the directory
+cannot disagree, which was the whole point of the request. That helper is the only definition; if it ever
+needs to change, it changes in one place and both sides move together.
+
+**`myFolder`** is the answer to the question a send picker actually asks. Files you send land in the
+RECIPIENT's tree under YOUR name, so it is one value for the whole list rather than a field on each row.
+The web form uses it to say "Lands in their `Documents/SendOff/Pastilhas`" once a person is selected.
+
+Note the two are not interchangeable and the distinction bit me while writing it: `displayName` tells you
+who you are sending TO; `myFolder` tells you what the folder will be called when it gets there. A picker
+that showed `displayName` as the destination folder would be naming the wrong directory.
+
+Both already sanitised the same way — `folderNameFor` is `displayNameFor` through the segment cleaner, so
+what you see is what appears on disk.
+
+## Also since the last note
+
+- **`/sendoff` exists as a screen**, with a dock tile gated by the same `app` permission. Pick files, pick a
+  machine or a person, send. No received view, deliberately: the file browser already is the inbox.
+- Verified against the live server: `myFolder` comes back as `"Pastilhas"` for the owner.
+
+Nothing here needs anything from mobile. Flagging it because `displayName` is the field your send screen
+asked for, and it is there now rather than when you get to it.

COMMS/sendoff/platform.md

@@ -0,0 +1,141 @@
+# SendOff — the backend is in. What mobile needs to change.
+
+**From:** platform (officer-dev) · **Date:** 2026-08-23 · **Reading:** `docs/sendoff.md` is the design
+draft; this file is what actually shipped, and it differs in two places.
+
+The backend landed in `b94a5e90` and is verified end to end on `officer-dev`. Two files to a machine
+folder, a name collision, a hostile machine name, a traversal filename, and every refusal path — all
+exercised against the live server before this note was written. The web send form is **not** built yet;
+that is on this side and does not block anything below.
+
+## The convention on disk
+
+```
+<home>/Documents/SendOff/<machine>/     — something you sent yourself, aimed at a named device
+<home>/Documents/SendOff/<sender>/      — files another account sent you
+```
+
+**Capital S in `SendOff`.** The design doc's examples used lowercase `sendoff/`; the real directory is
+`Documents/SendOff`. If the app builds that path anywhere itself, it needs the capital.
+
+`<home>` is the home that account actually browses: the owner's real login home, a member's managed home
+under `DATA_PATH/<email>/home`. The app never needs to know which — every path it receives is already
+relative to the right one.
+
+There is no `from-` prefix. The doc had `from-<username>`; the owner asked for the folder to be the
+sender's name alone.
+
+## Two changes from the draft spec
+
+**1. Device registration moved under the feature.**
+
+```
+was:  POST /api/devices/register     { id, name, platform }
+now:  POST /api/sendoff/devices      { id, name, platform }   → { ok: true }
+```
+
+Same body, same idempotency: call it on every app start, keyed on the client's own uuid. Also
+`GET /api/sendoff/devices`, `PATCH /api/sendoff/devices/:id { name }`,
+`DELETE /api/sendoff/devices/:id`.
+
+Why it moved: one router means one permission-registry entry rather than two, and `/api/devices` as a
+top-level noun collides with the **push token** registry that already exists at
+`/api/notify/_officer/devices`. Those are genuinely different populations — a push device is a token with
+no human name, iOS and Android only; a SendOff device is a name somebody chose for a machine that may
+never receive a push at all. Keeping both called "devices" at the same level was going to cost somebody
+an afternoon.
+
+**2. `toUser` is an account id, not a username.**
+
+```
+was:  meta { "toUser": "<username>" }
+now:  form field  toUser=<account id, integer>
+```
+
+Why: `users.name` is nullable in this schema, so a username is not a reliable address. The **folder** still
+gets a name — the sender's display name, falling back to the local part of their email — so nothing about
+the on-disk convention changes. If the app would rather send a username, say so and this side will accept
+either; it is a small change here and a smaller one than guessing.
+
+## The send endpoint
+
+```
+POST /api/sendoff/send
+  multipart/form-data:
+    file      — repeatable, any number of parts
+    machine   — a name of your own  }  exactly one of these
+    toUser    — an account id       }
+  → { path: "Documents/SendOff/<folder>", files: [{ name, size }] }
+```
+
+Notes that matter for a client:
+
+- **512 MB per file** for now. Owner-configurable per account is `todo/sendoff/per-user-size-limit.md`.
+  A file over the limit is a `400` naming the file.
+- **`name` in the response may differ from what you sent.** Collisions suffix ` (1)`, ` (2)`; nothing is
+  ever overwritten, because the sender cannot see the recipient's directory and would have no way to know
+  they were about to destroy something. Show the returned name, not the local one.
+- **Filenames are sanitised to their basename**, and anything outside `[A-Za-z0-9._-]` becomes a dash.
+  Verified: a filename of `../../../../tmp/pwned.txt` writes `pwned.txt` inside the target.
+- **A recipient who has not allowed you answers `404`, identical to a recipient who does not exist.**
+  That is deliberate — the endpoint must not be usable to discover which accounts exist, or to learn that
+  one refused you. Do not present the two differently, because they are not distinguishable.
+
+## Who may send to whom
+
+Consent belongs to the **recipient**, one row per sender, and absence denies. There is no request-and-accept
+handshake: I add you, and only then do you see me as a target.
+
+```
+GET    /api/sendoff/targets            → { devices: [...], people: [...] }   ← what the picker shows
+GET    /api/sendoff/senders            → { allowed: [...], candidates: [{ ...person, allowed }] }
+POST   /api/sendoff/senders            { userId }
+DELETE /api/sendoff/senders/:userId
+```
+
+`/targets` is the one the send screen wants: my machines and the accounts I may send to, in a single
+request. For everyone except the owner, `people` contains only accounts that have named them. **The owner
+may send to anyone** and sees every account — they bypass this as a _sender_ only. Receiving still needs
+their say-so, so nobody lands files in the owner's tree uninvited.
+
+Revoking stops future sends and touches nothing already delivered. Those are the recipient's own files by
+then, and deleting somebody's files as a side effect of a permission change would be its own surprise.
+
+## The push
+
+```
+code:  officer/core:sendoff.landed
+id:    the folder name — a username, or one of your own machine names
+n:     how many files landed
+```
+
+The catalogue entry renders `{n} file(s) from {id}` and its route is:
+
+```
+officer://files?path=Documents/SendOff/{id}
+```
+
+**Nothing here needs an app build.** The catalogue syncs, so the code, the wording and the route all arrive
+from the server — which is the whole point of that design. What the app does need is to keep parsing
+`officer://files?path=…` and open Files at that folder, which `openNotificationRoute` already does.
+
+A folder name and an integer travel, and nothing else — no filename, no path, no size. That is a deliberate
+relaxation of `types.ts`'s "content does not travel", decided by the owner on the grounds that the file
+itself never leaves the tailnet and a notification nobody can act on is not worth sending. A filename would
+be content; whose folder it is, is addressing. If a future notification wants more than that, it is a
+conversation rather than a patch.
+
+## What is NOT built
+
+- **The web send form.** This side, in progress. It changes no API.
+- **Sending from the phone.** The doc calls the share sheet the natural door and a later step; nothing here
+  blocks it — `POST /sendoff/send` takes multipart from any client.
+- **Per-account size limits** — `todo/sendoff/per-user-size-limit.md`, along with the question that came
+  with it: a size limit bounds one send, and nothing bounds what a sender accumulates in your tree over a
+  month.
+
+## If something here is wrong for mobile
+
+Say which, in `COMMS/sendoff/mobile.md`. Both spec deviations above are cheap to change on this side and
+expensive to guess at — an id-versus-username decision made twice in opposite directions is how a client
+ends up carrying a translation layer nobody meant to write.

TODO.md

@@ -20,37 +20,38 @@ the owner's OS user and can never be granted. Indirection there really is accide
 
 ## Themes
 
-**84 open, 22 closed**, across 28 themes.
+**90 open, 25 closed**, across 29 themes.
 
 | Theme | Open | Closed |
 | --- | --- | --- |
 | [Affordances](todo/affordances/) | 1 | 0 |
 | [Speaking into a session from the backend](todo/agent-delivery/) | 2 | 0 |
 | [Backburner](todo/backburner/) | 2 | 0 |
-| [Background jobs](todo/background-jobs/) | 2 | 0 |
+| [Background jobs](todo/background-jobs/) | 3 | 0 |
 | [Chat interface](todo/chat/) | 1 | 0 |
 | [Code editor](todo/code-editor/) | 1 | 0 |
 | [Components — the shared UI layer](todo/components/) | 1 | 0 |
 | [File watchers](todo/file-watchers/) | 1 | 0 |
 | [Fleet — one command across every server](todo/fleet/) | 5 | 2 |
 | [Headscale](todo/headscale/) | 0 | 5 |
-| [Infra (alpha)](todo/infra/) | 6 | 0 |
-| [Known bugs](todo/known-bugs/) | 4 | 1 |
+| [Infra (alpha)](todo/infra/) | 7 | 0 |
+| [Known bugs](todo/known-bugs/) | 3 | 2 |
 | [Mobile apps](todo/mobile-apps/) | 3 | 0 |
-| [Multi-user](todo/multi-user/) | 17 | 3 |
+| [Multi-user](todo/multi-user/) | 16 | 5 |
 | [Notifications](todo/notifications/) | 1 | 0 |
 | [Plugin ecosystem — before it opens to third parties (2026-08-18)](todo/plugin-ecosystem/) | 3 | 0 |
 | [Plugin infrastructure](todo/plugin-infrastructure/) | 2 | 0 |
 | [Plugin repos — what writing their READMEs turned up](todo/plugin-repos/) | 10 | 9 |
 | [Plugin system — gaps the email extraction found (2026-08-18)](todo/plugin-system/) | 3 | 0 |
 | [Prompt library](todo/prompt-library/) | 1 | 0 |
-| [Shell — spotlight and the dock](todo/shell/) | 1 | 1 |
+| [Settings — portable, and readable by an agent](todo/settings/) | 2 | 0 |
+| [Shell — spotlight and the dock](todo/shell/) | 4 | 1 |
 | [Sub-agents — agents spawning agents](todo/sub-agents/) | 1 | 1 |
 | [Sudo terminal modal](todo/sudo-terminal-modal/) | 1 | 0 |
 | [Tooling — the list about the list](todo/tooling/) | 1 | 0 |
 | [Transmission](todo/transmission/) | 6 | 0 |
 | [URL state — routing, query strings and selection](todo/url-state/) | 4 | 0 |
-| [Waiting on the owner to run it](todo/waiting-on-owner/) | 2 | 0 |
+| [Waiting on the owner to run it](todo/waiting-on-owner/) | 3 | 0 |
 | [Workspaces & Panels](todo/workspaces-panels/) | 2 | 0 |
 
 ## Records — no items, kept for the reasoning
@@ -62,13 +63,13 @@ the owner's OS user and can never be granted. Indirection there really is accide
 
 ## Newest ten
 
+- `2026-08-22` **'A commander picks the cheapest model that will do the job — for itself and for what it spawns'** — [background-jobs/a-commander-picks-the-cheapest-model-that-will](todo/background-jobs/a-commander-picks-the-cheapest-model-that-will.md)
+- `2026-08-22` **'Revisit the bun 1.3 pin once 1.4 has been watched for a while'** — [infra/revisit-the-bun-1-3-pin-once-1-4-has-been](todo/infra/revisit-the-bun-1-3-pin-once-1-4-has-been.md)
+- `2026-08-22` **A plugin's permission should be on for every role by default, off only on request** — [multi-user/a-plugin-s-permission-should-be-on-for-every](todo/multi-user/a-plugin-s-permission-should-be-on-for-every.md)
+- `2026-08-22` **A user's settings should export and import as a plain file** — [settings/a-user-s-settings-should-export-and-import-as](todo/settings/a-user-s-settings-should-export-and-import-as.md)
+- `2026-08-22` **The same for system settings, owned by the Super Admin** — [settings/the-same-for-system-settings-owned-by-the](todo/settings/the-same-for-system-settings-owned-by-the.md)
+- `2026-08-22` **All keyboard shortcuts configurable** — [shell/all-keyboard-shortcuts-configurable](todo/shell/all-keyboard-shortcuts-configurable.md)
+- `2026-08-22` **Ctrl+? shows every keyboard shortcut in a modal** — [shell/ctrl-shows-every-keyboard-shortcut-in-a-modal](todo/shell/ctrl-shows-every-keyboard-shortcut-in-a-modal.md)
+- `2026-08-22` **Revamp the menus — spotlight, themes — toward an Omarchy-like shape** — [shell/revamp-the-menus-toward-an-omarchy-like-shape](todo/shell/revamp-the-menus-toward-an-omarchy-like-shape.md)
+- `2026-08-22` **Review officer-secret-store, built overnight and untested by the owner** — [waiting-on-owner/review-the-officer-secret-store-built-last](todo/waiting-on-owner/review-the-officer-secret-store-built-last.md)
 - `2026-08-21` **No way to see which affordances are reaching your agents, or to turn one off** — [affordances/no-way-to-see-which-affordances-are-reaching](todo/affordances/no-way-to-see-which-affordances-are-reaching.md)
-- `2026-08-21` **Generalise it: deliver a turn to a named session, from anywhere in the backend** — [agent-delivery/generalise-it-deliver-a-turn-to-a-named](todo/agent-delivery/generalise-it-deliver-a-turn-to-a-named.md)
-- `2026-08-21` **The cost of resuming grows with the transcript** — [agent-delivery/the-cost-of-resuming-grows-with-the-transcript](todo/agent-delivery/the-cost-of-resuming-grows-with-the-transcript.md)
-- `2026-08-21` **'An agent spawned by a background job is invisible in the interface'** — [background-jobs/a-spawned-agent-is-invisible-in-the-interface](todo/background-jobs/a-spawned-agent-is-invisible-in-the-interface.md)
-- `2026-08-21` **Show how long a turn took, beside its cost and tokens** — [chat/show-how-long-a-turn-took-beside-its-cost](todo/chat/show-how-long-a-turn-took-beside-its-cost.md)
-- `2026-08-21` **Map every custom component, centralise it, and let a theme override it** — [components/map-every-custom-component-and-centralise-it](todo/components/map-every-custom-component-and-centralise-it.md)
-- `2026-08-21` **Watch a directory, and attach actions to what lands in it** — [file-watchers/watch-a-directory-and-attach-actions-to-what](todo/file-watchers/watch-a-directory-and-attach-actions-to-what.md)
-- `2026-08-21` **Settings to choose which server each feature uses** — [fleet/settings-to-choose-which-server-each-feature](todo/fleet/settings-to-choose-which-server-each-feature.md)
-- `2026-08-21` **'A deploy verifies PM2, not that the app still works'** — [fleet/a-deploy-report-verifies-pm2-not-that-the-app](todo/fleet/a-deploy-report-verifies-pm2-not-that-the-app.md)
-- `2026-08-21` **'The deploy commander cannot finish its own host'** — [fleet/the-deploy-commander-cannot-finish-its-own-host](todo/fleet/the-deploy-commander-cannot-finish-its-own-host.md)

bun.lock

@@ -210,6 +210,7 @@
         "dotenv": "^16.4.7",
         "embla-carousel-react": "^8.5.1",
         "hooks": "*",
+        "i18n": "*",
         "input-otp": "^1.4.1",
         "lucide-react": "^0.468.0",
         "next-themes": "^0.4.4",
@@ -271,6 +272,7 @@
       "version": "0.0.1",
       "dependencies": {
         "hooks": "workspace:*",
+        "i18n": "workspace:*",
         "state": "workspace:*",
         "widgets": "workspace:*",
       },

deploy/2026.08.21.04.report.md

@@ -0,0 +1,102 @@
+# 2026.08.21.04 — deploy report
+
+**6 of 6 hosts in scope succeeded.** `officer-dev` was skipped entirely — it is the host this agent runs
+on. Seven platforms exist; six were deployable.
+
+Target commit `98177c3b`, tag `deploy/2026.08.21.04`, `package.json` version `2026.08.21.04` — tag and
+version agree.
+
+Every host ran the same four steps from `deploy/2026.08.21.04.md`: `git pull --ff-only`, `bun db:push`
+(the schema change), `bun run plugins:update`, `pm2 restart officer`. No host ran `bun install` — the plan
+said not to.
+
+---
+
+## Per host
+
+### `alpha` — succeeded
+
+- HEAD `3cab16ca` → `98177c3b`. Tree clean, no untracked files.
+- The pull moved only `deploy/2026.08.21.04.md` and `package.json`: the code was already there from the
+  hand deploy the plan describes. Expected, and the remaining steps ran anyway.
+- `db:push` — changes applied. `anthropic_accounts` verified present by direct query.
+- `plugins:update` — 12/12 updated in 44s, exit 0. **Twelve sidecars restarted by that step**: atelier,
+  bitcoin-wallet, email, gitea, invoices, jellyfin, music, offscale, photos, soulseek, transmission,
+  vault. That is the script's own behaviour, not something the plan asked for.
+- `pm2 restart officer` — `restart_time` 63 → 64, `online`.
+
+### `fofos` — succeeded
+
+- HEAD `3343b21a` → `98177c3b`. No tracked changes.
+- **Untracked file present: `scripts/chk.ts`.** Left alone — a fast-forward cannot touch it, and it is
+  not a reason to skip a host.
+- `db:push` — changes applied. `anthropic_accounts` verified by direct query.
+- `plugins:update` — 1/1 (gitea), exit 0. One sidecar restarted: `officer-gitea`.
+- `pm2 restart officer` — 17 → 18, `online`.
+- The capabilities ownership fault recorded in `docs/servers.md` did not recur: `capabilities: pulled`.
+
+### `macbookpro` — succeeded
+
+- HEAD `b10a49c0` → `98177c3b`. Tree clean.
+- Awake and reachable; no skip needed.
+- `bun` reached with `export PATH=$PATH:/opt/homebrew/bin` appended for the `bun` commands only, `pm2`
+  run as a separate command, per the plan and `docs/servers.md`.
+- `db:push` — changes applied.
+- `plugins:update` — "no plugins installed — nothing to update", exit 0. No sidecar restarted.
+- `pm2 restart officer` — 4 → 5, `online`.
+- **The one thing not verified here:** `psql` is not on this machine's PATH under any prefix tried, so
+  `anthropic_accounts` was confirmed only by `db:push` reporting "Changes applied", not by querying the
+  table. Every other host was checked directly.
+- Cosmetic noise from the interactive shell: `.zshrc:123: command not found: starship`. Harmless, and
+  unrelated to the deploy.
+
+### `edge-pertento-bridge` — succeeded
+
+- HEAD `3343b21a` → `98177c3b`. Tree clean.
+- `db:push` — changes applied. `anthropic_accounts` verified by direct query.
+- `plugins:update` — 2/2 (gitea, offscale), exit 0. Two sidecars restarted.
+- `pm2 restart officer` — 6 → 7, `online`.
+
+### `production-pertento-bridge` — succeeded
+
+- HEAD `3343b21a` → `98177c3b`. Tree clean.
+- `db:push` — changes applied. `anthropic_accounts` verified by direct query.
+- `plugins:update` — 1/1 (gitea), exit 0. One sidecar restarted.
+- `pm2 restart officer` — 8 → 9, `online`.
+
+### `deadpool-rezio-bridge` — succeeded
+
+- Logged in as `br`, checkout `/home/br/officerdev/platform`.
+- HEAD `3343b21a` → `98177c3b`. Tree clean.
+- `db:push` — changes applied. `anthropic_accounts` verified by direct query.
+- `plugins:update` — "no plugins installed — nothing to update", exit 0. No sidecar restarted.
+- `pm2 restart officer` — 2 → 3, `online`.
+
+### `officer-dev` — SKIPPED, deliberately
+
+Not pulled, no schema push, no plugin update, nothing restarted. This agent is a session inside
+`officer-claude-code` on this machine, and restarting `officer` here ends the rollout mid-report. The
+host is therefore one release behind the other six until the owner deploys it by hand — checkout
+`~/officer-dev/platform`, and its working tree is already at `98177c3b` plus this report.
+
+---
+
+## What was checked, and how
+
+- Every checkout path came from PM2 (`officer`'s `pm_cwd`), not from the table — so `alpha`'s second,
+  stale checkout was never a candidate.
+- `pm2 jlist` after each restart: `officer` `online` with `restart_time` moved, on all six.
+- A full sweep for anything not `online` on all six hosts afterwards: **none**. No process came back
+  `errored`, including the sixteen sidecars that `plugins:update` bounced across four hosts.
+- `anthropic_accounts` queried directly with `to_regclass` on five hosts; on `macbookpro` only the
+  `db:push` output stands behind it.
+
+## What was not done
+
+- `officer-dev` — the whole host, as above.
+- No host was skipped for a dirty tree; none had tracked changes.
+- No process other than `officer` was restarted by this agent. The sidecars that moved were restarted by
+  `plugins:update` itself.
+- `bun install` was not run anywhere, per the plan.
+
+Local record: `data/deploys/2026.08.21.04.done`, written before this report.

deploy/2026.08.22.01.md

@@ -0,0 +1,53 @@
+# 2026.08.22.01
+
+349 community themes, Spotlight made usable, prompt history that stops eating drafts, and the email
+plugin's multi-account backend.
+
+**No schema change and no dependency change.** Verified against `deploy/2026.08.21.04..HEAD`: nothing
+touches a `databases/*/schema.ts`, `package.json` dependencies or `bun.lock`. So **no `bun db:push` and no
+`bun install`** — a host that runs either has run something this release did not ask for. Note that the
+previous release DID need a push; that was `anthropic_accounts` and it is already applied everywhere.
+
+## What is in it
+
+- **The theme collection.** 147 ports from omarchythemes.com, then 44 more rescued by supporting
+  `colors.toml` and `0x`-prefixed hex, then a fix to accent/secondary foreground derivation across 202 of
+  them. This is the bulk of the diff: 229 files, ~22.5k lines, almost all data.
+- **Spotlight.** Opens on **alt-space** and nothing else, from anywhere including a focused text field.
+  The eight-item cap is gone — core items filled it, so every plugin tile was unreachable on a populated
+  server. Rows draw the dock's own tiles, and the settings list went from nine hand-written entries to
+  twenty read off the screens that declare them.
+- **Prompt history.** Up/Down only recall from an empty composer, and any other keystroke ends a recall —
+  so a half-written thought is never swapped for one from last week.
+- **The email plugin's multi-account backend**, which arrives via `plugins:update` rather than through this
+  repository. `?account=<id>` names a mailbox, `?account=all` spans them. **Absent is unchanged**, so
+  nothing that calls those routes today behaves differently — including the mobile app and the agent's
+  `email_db` tool. Only hosts with the email plugin installed are affected at all.
+
+## Every host
+
+1. `git pull --ff-only` — larger than usual, ~22.5k lines of theme data
+2. `bun run plugins:update`
+3. `pm2 restart officer`
+
+`officer` only. Step 2 restarts each plugin's own sidecar, which is that script's behaviour and worth
+recording in the report rather than omitting.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands and run `pm2` separately. See
+`docs/servers.md` — replacing the PATH is what broke `pm2` on an earlier deploy.
+
+## `officer-dev` — skip it, and do NOT report it as behind
+
+The commander runs there and skips its own host, as always. But this time the host is **already on this
+code**: `officer` was restarted there many times during the night as the work landed, so it is running the
+tree this tag names rather than lagging. Report it as skipped and current, not skipped and stale.
+
+## Then check
+
+`pm2 jlist`: `officer` is `online` and `restart_time` moved. Nothing `errored`, including the sidecars step
+2 bounced.
+
+A theme picker still lists themes and one loads — the diff is data, so a bad parse would show as a missing
+or unreadable theme rather than as a failed boot.
+
+`scripts/deploy-claim.sh state 2026.08.22.01` says `done`.

deploy/2026.08.22.01.report.md

@@ -0,0 +1,104 @@
+# 2026.08.22.01 — deploy report
+
+**6 of 6 hosts succeeded.** `officer-dev` skipped (the commander's own host) and already on this code.
+No host failed, no process came back `errored`.
+
+Tag `deploy/2026.08.22.01` → `78db9c8c`. `package.json` reads `2026.08.22.01` at that commit — they agree.
+Every host went `98177c3b` → `78db9c8c`, a clean fast-forward.
+
+Per the plan: **no `bun install` and no `bun db:push` ran anywhere.**
+
+## Per host
+
+### `alpha` — succeeded
+
+- Checkout `/home/pastilhas/officerdev/platform`, from PM2's `pm_cwd` (the stale second checkout at
+  `~/dockers/officer.dev/platform` was not touched).
+- Tree clean, tracked and untracked both. HEAD `98177c3b` → `78db9c8c`.
+- `bun run plugins:update`: `12/12 updated in 48s`, no plugin reported a failure. It bounced twelve plugin
+  sidecars of its own accord — atelier, bitcoin-wallet, email, gitea, invoices, jellyfin, music, offscale,
+  photos, soulseek, transmission, vault.
+- `pm2 restart officer`: `restart_time` 64 → 65, `online`.
+- All 19 processes `online` afterwards.
+
+One gap, stated because it is the kind of thing a report should not quietly round up: **the exit code of
+`plugins:update` was lost on this host** — the shell wrapper swallowed it. Success is asserted from the
+`12/12 updated` line and the absence of any per-plugin failure, not from an exit status. Every other host
+captured an explicit `0`.
+
+### `fofos` — succeeded
+
+- Checkout `/home/pastilhas/officerdev/platform`. HEAD `98177c3b` → `78db9c8c`.
+- **One untracked file present: `scripts/chk.ts`.** Noted, not a reason to skip — a fast-forward cannot
+  touch it, and it was left alone. No tracked change.
+- `plugins:update` exit 0: `1/1 updated in 7s` (gitea), its sidecar restarted.
+- `pm2 restart officer`: 18 → 19, `online`. All 8 processes `online`.
+- The capabilities sync that failed here for three deploys ran clean: `capabilities: pulled`. The ownership
+  fix of 2026-08-21 is holding.
+
+### `macbookpro` — succeeded
+
+- Awake and reachable. Checkout `/Users/pastilhas/projects/officer-suite/platform`.
+- HEAD `98177c3b` → `78db9c8c`, tree clean.
+- `bun` run with `PATH=$PATH:/opt/homebrew/bin` **appended**, `pm2` run as a separate command through the
+  interactive shell, exactly as the plan and `docs/servers.md` require.
+- `plugins:update` exit 0: `no plugins installed — nothing to update`. No sidecar bounced.
+- `pm2 restart officer`: 5 → 6, `online`. All 6 processes `online`.
+
+### `edge-pertento-bridge` — succeeded
+
+- Checkout `/home/pastilhas/officerdev/platform`. HEAD `98177c3b` → `78db9c8c`, tree clean.
+- `plugins:update` exit 0: `2/2 updated in 9s` (gitea, offscale), both sidecars restarted.
+- `pm2 restart officer`: 7 → 8, `online`. All 8 processes `online`.
+
+### `production-pertento-bridge` — succeeded
+
+- Checkout `/home/pastilhas/officerdev/platform`. HEAD `98177c3b` → `78db9c8c`, tree clean.
+- `plugins:update` exit 0: `1/1 updated in 4s` (gitea), its sidecar restarted.
+  nvm printed its `.npmrc` `globalconfig`/`prefix` warning first. Pre-existing, unrelated to this release,
+  and the command still exited 0 — recorded so the next reader does not chase it.
+- `pm2 restart officer`: 9 → 10, `online`.
+- This host also runs a **non-Officer** PM2 set (`Dashboard`, `Tracking`, `Uptime`, five `Crons *` entries).
+  All `online`, none touched.
+
+### `deadpool-rezio-bridge` — succeeded
+
+- Login `br`, not `pastilhas`. Checkout `/home/br/officerdev/platform`.
+- HEAD `98177c3b` → `78db9c8c`, tree clean.
+- `plugins:update` exit 0: `2/2 updated in 8s` (email, offscale), both sidecars restarted.
+  Printed `capabilities: adopted` rather than `pulled` — this host's capabilities checkout is newer than
+  the others'. Not an error.
+- `pm2 restart officer`: 3 → 4, `online`. All 9 processes `online`.
+
+### `officer-dev` — SKIPPED, and current
+
+The commander runs here, inside `officer-claude-code`. Nothing was pulled and nothing restarted.
+
+It is **not behind**: `deploy/2026.08.22.01` is an ancestor of the local HEAD. The checkout is in fact
+**two commits past** the tag — `c9823533` and `0c2ff88c`, neither on `origin` when this ran — written by
+another agent working in this same tree during the rollout. Its work was left alone; only this report was
+staged, by path.
+
+Worth knowing rather than discovering: **pushing this report carries those two commits to `origin/master`
+with it**, because they are its ancestors. Nothing was deployed from them — every host in this rollout is
+at `78db9c8c`, the tag — but the next release will include them.
+
+`officer` here is `online` at `restart_time` 180, running the tree this tag names.
+
+## Verification
+
+- **Every restarted process came back.** `pm2 jlist` re-read on each host after the restart: `officer`
+  `online` with `restart_time` incremented, and no process anywhere in state `errored` or `stopped`.
+- **The theme data landed.** The release is mostly data, so a bad file shows up as a missing or unreadable
+  theme rather than a failed boot. All six hosts carry **227** theme CSS files under
+  `src/workspaces/theme/css/themes/`, matching the release tree exactly.
+- `scripts/deploy-claim.sh state 2026.08.22.01` → `done`.
+
+## What was not done
+
+- **`officer-dev` was skipped entirely** — its own host, by design. The owner restarts it deliberately when
+  happy with the rest. It needs no pull.
+- **No theme was loaded through a UI.** The plan asks that a theme picker still lists themes and one loads.
+  A commander cannot click. The file-count check above is the substitute, and it is weaker: it proves the
+  files arrived, not that each parses.
+- **`alpha`'s `plugins:update` exit code was not captured** (see above). Judged from output, not status.

deploy/2026.08.22.02.md

@@ -0,0 +1,57 @@
+# 2026.08.22.02
+
+Theme favourites, a shortcuts modal on `Ctrl+?`, Command HQ rebuilt into two columns, 27 tests on the
+authorization resolver, and the email plugin's multi-account backend.
+
+**SCHEMA CHANGE.** `theme_favorites` is new, so `bun db:push` is a step. Without it, opening the theme
+dropdown fails on a missing relation the first time it reads a starred list.
+
+**No dependency change** — nothing in `deploy/2026.08.22.01..HEAD` touches `package.json` dependencies or
+`bun.lock`. Do not run `bun install`.
+
+## What is in it
+
+- **Theme favourites**, per account, in `theme_favorites`. Star from the dropdown, from the browser
+  (`f`), or from anywhere (`Ctrl+Shift+F`). The lists rotate to the theme you are wearing rather than
+  sorting it to the top, so neighbours survive.
+- **`Ctrl+?`** renders every shell shortcut from a registry — `state/shortcuts.ts` — ported in shape from
+  the owner's `vimazing`.
+- **Spotlight is on `Shift+Space`.** It was `alt-space` in the last release. `Ctrl+Space` cannot work:
+  Brave claims it at the browser level and the key never reaches the page.
+- **Command HQ is two columns** — navigation stacked into one 24% rail, transcript at 76%. **It migrates a
+  saved layout on load**, so anyone who has opened that screen will see their arrangement replaced once.
+  That is deliberate; the screen is `locked` and the only user contribution was column sizes.
+- **27 tests on `permissions/authorize.ts`**, which had none. Its decisions are now pure functions, split
+  from the database calls. No behaviour change.
+- **`assertPermissionTotality` reads the sockets that are served**, generated from one `WS_ROUTES`
+  declaration, instead of a parallel list of handlers.
+- **The email plugin's multi-account backend**, via `plugins:update` — `?account=<id>` names a mailbox,
+  `?account=all` spans them, absent is unchanged. Only hosts with that plugin installed are affected.
+
+## Every host
+
+1. `git pull --ff-only`
+2. **`bun db:push`** — new this release
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only. Step 3 restarts each plugin's own sidecar; that is the script's behaviour and belongs in the
+report rather than being omitted.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands, run `pm2` separately. See
+`docs/servers.md`.
+
+## `officer-dev` — skip it, and it is already current
+
+The commander runs there and skips its own host. That host was restarted repeatedly through the day as this
+work landed, so it is running this tree rather than lagging. Report it as skipped and current.
+
+## Then check
+
+`pm2 jlist`: `officer` is `online` and `restart_time` moved; nothing `errored`.
+
+`theme_favorites` exists — `to_regclass('theme_favorites')` is not null. This is the one step whose absence
+shows up as a broken dropdown rather than a failed boot, so verify it directly where `psql` is available and
+say where it is not.
+
+`scripts/deploy-claim.sh state 2026.08.22.02` says `done`.

deploy/2026.08.22.02.report.md

@@ -0,0 +1,105 @@
+# 2026.08.22.02 — deploy report
+
+**6 of 6 target hosts succeeded.** `officer-dev` skipped (the commander runs there) and verified already
+current. No host failed, no step was skipped for a fault, nothing came back `errored`.
+
+Deployed 2026-08-22 from `officer-dev`. Tag `deploy/2026.08.22.02` → `68d60e40`, matching
+`package.json` `2026.08.22.02`.
+
+## Summary
+
+| Host                         | HEAD before | HEAD after | Steps      | `officer` restart | `theme_favorites` |
+| ---------------------------- | ----------- | ---------- | ---------- | ----------------- | ----------------- |
+| `officer-dev`                | `68d60e40`  | —          | skipped    | not touched (192) | present           |
+| `alpha`                      | `78db9c8c`  | `68d60e40` | all 4      | 65 → 66, online   | present           |
+| `fofos`                      | `78db9c8c`  | `68d60e40` | all 4      | 19 → 20, online   | present           |
+| `macbookpro`                 | `9b459b79`  | `68d60e40` | all 4      | 6 → 7, online     | present           |
+| `edge-pertento-bridge`       | `78db9c8c`  | `68d60e40` | all 4      | 8 → 9, online     | present           |
+| `production-pertento-bridge` | `78db9c8c`  | `68d60e40` | all 4      | 10 → 11, online   | present           |
+| `deadpool-rezio-bridge`      | `78db9c8c`  | `68d60e40` | all 4      | 4 → 5, online     | present           |
+
+Checkout paths were taken from each `officer` process's `pm_cwd`, not from a hard-coded list.
+
+## Per host
+
+### `officer-dev` — SKIPPED, and current
+
+The commander session runs inside `officer-claude-code` on this machine, so the whole host was skipped as
+the plan and `prompts/deploy-commander.md` both require: no pull, no `db:push`, no `plugins:update`, no
+restart. It was already at `68d60e40` before the rollout started and `theme_favorites` is present, so it is
+running this release rather than lagging. `officer` shows 192 restarts, untouched by this deploy.
+
+**The owner restarts this host deliberately, once happy with the rest.** Strictly nothing is pending on it —
+the tree, the schema and the running process are all already on this release.
+
+### `alpha` — done
+
+Tree clean (tracked and untracked). Pulled `78db9c8c` → `68d60e40`. `bun db:push` applied changes;
+`backfill-session-models` reported 0 seeded, 32 already recorded. `bun run plugins:update` returned
+**12/12 updated in 46s**, exit 0 — and it restarted all twelve plugin sidecars itself (atelier,
+bitcoin-wallet, email, gitea, invoices, jellyfin, music, offscale, photos, soulseek, transmission, vault),
+which is the script's normal behaviour and not something the plan asked for. `pm2 restart officer`: 65 → 66,
+`online`. All 19 processes `online`. `to_regclass('theme_favorites')` returned the table.
+
+### `fofos` — done
+
+Tracked tree clean. **One untracked file, `scripts/chk.ts`** — noted, not a reason to skip, and untouched by
+the fast-forward. Pulled `78db9c8c` → `68d60e40`. `db:push` applied changes (3 transcripts already recorded).
+`plugins:update`: **1/1 (gitea)**, exit 0, its sidecar restarted by the script. `officer` 19 → 20, `online`;
+all 8 processes `online`. `theme_favorites` present.
+
+Note for anyone scripting against this host: its `.env` names the connection `OFFICERDEV_POSTGRES_URL`, not
+`POSTGRES_URL`, and a naive `grep POSTGRES_URL` matches a comment line first. Same on `macbookpro`,
+`edge-pertento-bridge`, `production-pertento-bridge` and `deadpool-rezio-bridge`; `alpha` and `officer-dev`
+use `POSTGRES_URL`.
+
+### `macbookpro` — done, awake
+
+Reachable — not asleep this time. Tree clean. **It was two releases behind**: `9b459b79`, not `78db9c8c`
+like the rest. Pulled straight to `68d60e40`.
+
+`PATH` was appended with `/opt/homebrew/bin` for the `bun` commands and `pm2` run separately, per
+`docs/servers.md`. `db:push` applied changes, exit 0. `plugins:update` exit 0 with **no plugins installed —
+nothing to update**, so no plugin sidecars moved here. `officer` 6 → 7, `online`; all 6 processes `online`.
+
+**`psql` is not installed on this host** — the plan's direct schema check could not be run the way it is
+written. Verified instead through the platform's own `postgres` client (`bun --env-file=.env` against
+`OFFICERDEV_POSTGRES_URL`), which returned `theme_favorites`. Same fact, different tool.
+
+`$SHELL -ic` also prints `command not found: starship` from `.zshrc:123` on every invocation. Cosmetic, and
+unrelated to this release, but it appears in the raw output above every command.
+
+### `edge-pertento-bridge` — done
+
+Tree clean. Pulled `78db9c8c` → `68d60e40`. `db:push` applied changes, exit 0. `plugins:update`: **2/2
+(gitea, offscale)**, exit 0, both sidecars restarted by the script. `officer` 8 → 9, `online`; all 8
+processes `online`. `theme_favorites` present.
+
+### `production-pertento-bridge` — done
+
+Tree clean. Pulled `78db9c8c` → `68d60e40`. `db:push` applied changes, exit 0. `plugins:update`: **1/1
+(gitea)**, exit 0, sidecar restarted by the script. `officer` 10 → 11, `online`; all 15 processes `online`.
+`theme_favorites` present.
+
+### `deadpool-rezio-bridge` — done
+
+Logged in as **`br`**, not `pastilhas`. Tree clean. Pulled `78db9c8c` → `68d60e40`. `db:push` applied
+changes, exit 0. `plugins:update`: **2/2 (email, offscale)**, exit 0, both sidecars restarted by the script.
+`officer` 4 → 5, `online`; all 9 processes `online`. `theme_favorites` present.
+
+## What did not happen
+
+- **No host was skipped for a fault.** The only skip is `officer-dev`, by design.
+- **`bun install` was not run anywhere.** The plan says this release changes no dependency, and the plan is
+  what this agent executes.
+- **Nothing but `officer` was restarted deliberately.** The plugin sidecars that bounced were restarted by
+  `plugins:update` itself — eighteen processes across five hosts, listed per host above. Recording them
+  here rather than reporting only `officer` is the plan's explicit instruction.
+- **The one verification that had to change shape** is `macbookpro`'s schema check, for want of `psql`.
+  Everything else was verified exactly as written.
+
+## Claim record
+
+`scripts/deploy-claim.sh state 2026.08.22.02` → `done`. The local record
+`data/deploys/2026.08.22.02.done` was written before this report was committed, so a push failure here
+cannot cause a second rollout.

deploy/2026.08.23.01.md

@@ -0,0 +1,64 @@
+# 2026.08.23.01
+
+The commander creation flow, rebuilt end to end — named, given a directory, and started by a button that
+makes it interview you rather than waiting for a prompt somebody else wrote. Plus the delete path that
+actually removes one, `/minesweeper`, and `docs:check` guarding the documentation's checkable claims.
+
+**SCHEMA CHANGE.** `bun db:push` is a step. `command_hq_spawned` is new and `command_hq_sessions` gains
+`name`. Without the push, Command HQ fails on a missing column the first time it lists a commander.
+
+**No dependency change** — `bun.lock` is untouched across `deploy/2026.08.22.02..HEAD`. `package.json`
+moved only to add `engines.bun` and two scripts. **Do not run `bun install`.**
+
+## What is in it
+
+- **A commander is created, not configured.** Name it, choose its working directory, press Start. It reads
+  the directory, works out whether the job is already written down there, and either reads its
+  understanding back for confirmation or asks what it should be watching. The name is the brief — it is the
+  only thing the owner says before anything else, and it now reaches the model instead of only titling the
+  transcript.
+- **`command_hq_sessions.name`** — the platform owns the name. It was only ever in the transcript's summary
+  record, which the harness cannot write until the first turn ends, so the list showed the opening brief
+  while the header showed the real name.
+- **Deleting a commander removes it.** Four defects, each of which left something behind: the session kill
+  ran in the wrong process and always failed; the transcript was deleted while the harness was still
+  writing it, so it came straight back as an untitled chat; `chat_session_events` is keyed on officer's
+  session key while everything else uses the transcript id, so its rows were never matched; and the key was
+  resolved from an in-memory map that is empty for anything older than the process. The event rows carry
+  both ids, so they are asked when the maps cannot answer.
+- **`GET /chat/live?kind=`** — `agent` (the default), `commander`, or `all`, with `counts` always
+  describing the whole set. Defaulting to agents means a client that forgets cannot be handed a commander;
+  the web list asks for `all` explicitly.
+- **A dropped sidecar command says so.** `sendFire` did nothing when no sidecar was registered — no log, no
+  error — so answering a question during the reconnect window after a restart vanished and the card span
+  forever. Question answers and plan decisions now report it.
+- **`/minesweeper`** — a wine session streamed to the browser over RFB. The session is not running on
+  `officer-dev`, so the route renders its "not running" state with a Start button. That is expected.
+- **Usage limits are read live.** `limitsCache` was keyed on nothing, so switching Anthropic account showed
+  the previous account's percentages under the new name. The cache remains for the failure path only, keyed
+  per account.
+- **`bun docs:check`** compares documented claims against values derived at run time — the permission
+  count, the PM2 entry count, the generated platform skill. It found both claims it was written to check
+  already wrong. **Required before tagging a release.**
+- **Empty transcripts no longer list.** A file holding only harness metadata and no turns is not a
+  conversation; four had accumulated as "(untitled) · 0 msgs".
+- **Bun is held at the 1.3 series** — `engines.bun` and `BUN_SERIES` move together. Do not run
+  `bun upgrade` on a host.
+
+## Every host
+
+1. `git pull --ff-only`
+2. **`bun db:push`** — new this release
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only. Step 3 restarts each plugin's own sidecar; that is the script's behaviour and belongs in
+the report rather than being omitted.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands, run `pm2` separately. See
+`docs/servers.md`.
+
+## `officer-dev` — skip it
+
+This is the machine the rollout runs from, and restarting `officer` here ends the agent performing it.
+Name it as skipped in the report. It is already current.

deploy/2026.08.23.01.report.md

@@ -0,0 +1,134 @@
+# 2026.08.23.01 — deploy report
+
+**4 of 6 target hosts succeeded.** `officer-dev` skipped by the plan (the commander runs there) and
+verified already current. Two hosts were **not reached at all**, both for access reasons that have nothing
+to do with this release: `edge-pertento-bridge` will not complete an SSH handshake, and
+`production-pertento-bridge` presented a **changed host key**, which is not something a deploy agent
+clears. Neither was pulled, pushed to, or restarted. No host failed a step; nothing came back `errored`.
+
+Deployed 2026-08-23 from `officer-dev`. Tag `deploy/2026.08.23.01` → `dee0b89b`, matching `package.json`
+`2026.08.23.01`.
+
+**Hosts landed on `e6f1388a`, one commit past the tag.** The plan says `git pull --ff-only`, which follows
+`master`, and `master` had moved on by one commit — `plan: localizing the web UI, and the scanner that
+sizes it`, three files: `CLAUDE.md`, `docs/localization.md`, `scripts/i18n/scan-hardcoded.ts`. Documentation
+and a standalone script, no runtime code, no schema and no dependency. Recorded here because "deployed the
+tag" would not be true of any host.
+
+## Summary
+
+| Host                         | HEAD before | HEAD after | Steps    | `officer` restart | Schema  |
+| ---------------------------- | ----------- | ---------- | -------- | ----------------- | ------- |
+| `officer-dev`                | `e6f1388a`  | —          | skipped  | not touched (237) | ✓       |
+| `alpha`                      | `68d60e40`  | `e6f1388a` | all 4    | 66 → 67, online   | ✓       |
+| `fofos`                      | `68d60e40`  | `e6f1388a` | all 4    | 20 → 21, online   | ✓       |
+| `macbookpro`                 | `8b4a5b3b`  | `e6f1388a` | all 4    | 7 → 8, online     | ✓       |
+| `edge-pertento-bridge`       | unknown     | —          | **none** | not touched       | unknown |
+| `production-pertento-bridge` | unknown     | —          | **none** | not touched       | unknown |
+| `deadpool-rezio-bridge`      | `68d60e40`  | `e6f1388a` | all 4    | 5 → 6, online     | ✓       |
+
+Checkout paths came from each `officer` process's `pm_cwd`, not from a hard-coded list. "Schema ✓" is a
+live check, not an inference from `db:push` exiting zero: `command_hq_spawned` exists and
+`command_hq_sessions.name` exists, queried per host against that host's own database.
+
+## Per host
+
+### `officer-dev` — SKIPPED, and current
+
+The commander session runs inside `officer-claude-code` here, so the whole host was skipped as the plan
+requires: no pull, no `db:push`, no `plugins:update`, no restart. It was already at `e6f1388a` and both
+schema objects are present, so it is running this release rather than lagging. `officer` shows 237 restarts,
+untouched by this deploy. Nothing is pending on it — the owner restarts it deliberately if they want to.
+
+### `alpha` — done
+
+Tree clean, tracked and untracked. Pulled `68d60e40` → `e6f1388a`. `bun db:push` applied changes;
+`backfill-session-models` reported 0 seeded. `bun run plugins:update` returned **12/12 updated in 48s**,
+exit 0, and restarted all twelve plugin sidecars itself — atelier, bitcoin-wallet, email, gitea, invoices,
+jellyfin, music, offscale, photos, soulseek, transmission, vault. Then `pm2 restart officer`: 66 → 67,
+`online`. Every other PM2 entry `online`.
+
+### `fofos` — done
+
+Tree clean. Pulled `68d60e40` → `e6f1388a`. `db:push` applied changes. `plugins:update`: **1/1 in 8s**
+(gitea), which restarted `officer-gitea`. `pm2 restart officer`: 20 → 21, `online`. No trace of the
+`dubious ownership` / `EACCES` pair that broke its capabilities sync for three deploys — `capabilities:
+pulled` came back clean, as it has since the 2026-08-21 `chown`.
+
+### `macbookpro` — done
+
+Awake and reachable. Tree clean. Pulled `8b4a5b3b` → `e6f1388a` — two releases behind, so it picked up
+2026.08.22.01 and .02 as well. `db:push` applied changes (3 plugin schemas generated: atelier, kiosk,
+music). `plugins:update`: `no plugins installed — nothing to update`, exit 0. `pm2 restart officer` was run
+as a **separate** command per `docs/servers.md`: 7 → 8, `online`.
+
+`PATH` was appended, never replaced — `export PATH="$PATH:/opt/homebrew/bin"` inside the interactive shell,
+so `bun` resolves and `pm2` stays where nvm put it. `.zshrc` still fails on a missing `starship` on every
+non-interactive login; noise, not a fault, and it has been there for at least three deploys.
+
+### `deadpool-rezio-bridge` — done
+
+Logged in as **`br`**, not `pastilhas`. Tree clean. Pulled `68d60e40` → `e6f1388a`. `db:push` applied
+changes. `plugins:update`: **2/2 in 8s** (email, offscale), restarting both sidecars. `pm2 restart officer`:
+5 → 6, `online`.
+
+### `edge-pertento-bridge` — NOT REACHED
+
+**Four attempts, ConnectTimeout up to 60s: `Connection timed out during banner exchange`.** The TCP
+connection succeeds — `nc -z 100.64.0.15 22` reports the port open and `ssh -v` logs `Connection
+established` — and then sshd never sends its version string. Tailscale shows the node `active; direct`, so
+the tunnel is up and this is not a tailnet problem.
+
+That is a host-side sshd or load problem, not a credential one and not a rate-limit one. Nothing was run
+against it: it is still on whatever it was before this release, which I could not read, because reading it
+needs the same handshake. It also did not answer HTTPS on its tailnet address during the probe.
+
+**This host needs a look before the next release**, and the check is one command from anywhere on the
+tailnet — `ssh edge-pertento-bridge hostname`. If it still hangs, the box wants a console.
+
+### `production-pertento-bridge` — NOT REACHED, host key changed
+
+```
+WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
+The fingerprint for the ED25519 key sent by the remote host is
+SHA256:63S0GKa7eqv2a4cGbT7UqsDqupFrdd+RQsUYJ8Mg1ww
+Offending ECDSA key in /home/pastilhas/.ssh/known_hosts:37
+```
+
+**I did not clear the entry and did not connect.** Accepting a new host key is a trust decision, and a
+deploy agent that removes a `known_hosts` line to get its release out has removed the only warning the
+owner would ever get. `StrictHostKeyChecking` did exactly what it is for.
+
+What is known, all read locally without touching the host:
+
+- `known_hosts` holds three keys for this name: ED25519 `SHA256:dw7kG2MDftuLDT1CduEO+OVYuMVHsx02Cnwikj7GS/4`
+  (line 33), RSA (line 36), ECDSA (line 37, the one ssh names as offending).
+- The host now offers ED25519 `SHA256:63S0GKa7eqv2a4cGbT7UqsDqupFrdd+RQsUYJ8Mg1ww` — a different key from
+  the ED25519 already trusted.
+- Tailscale shows it `active; direct`, port 22 accepts TCP, and it did not answer HTTPS on 100.64.0.12
+  during the probe.
+
+The benign explanation is a rebuild or a regenerated host key — this is `PPROD`, a bridge that has been
+reinstalled before. The other explanation is the one the warning is about. **Settle it out of band**: read
+`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the machine's own console, compare it to
+`63S0GK…`, and only then drop the stale lines with
+`ssh-keygen -f ~/.ssh/known_hosts -R production-pertento-bridge`. Do not compare it over SSH; that is the
+channel in question.
+
+Until then this host is a release behind — it was at `68d60e40` as of the 2026.08.22.02 report.
+
+## What I did not do
+
+- **Did not deploy `edge-pertento-bridge` or `production-pertento-bridge`**, and did not force either.
+  Neither was pulled, neither had a process restarted, and neither has this release's schema.
+- **Did not touch `~/.ssh/known_hosts`.**
+- **Did not run `bun install`** — the plan forbids it and `bun.lock` is unchanged across
+  `deploy/2026.08.22.02..HEAD`.
+- **Did not run `bun run docs:check`** — not the commander's job; it is run before the tag.
+- **Did not restart anything the plan did not name.** `officer` only, per host. The plugin sidecars that
+  bounced were restarted by `plugins:update` itself, which is that script's own behaviour: 12 on `alpha`,
+  1 on `fofos`, 2 on `deadpool-rezio-bridge`.
+- **Did not touch `officer-dev`** at all.
+
+The local record `data/deploys/2026.08.23.01.done` was written before this report, as the protocol requires:
+the record is what prevents a second attempt, and pushing this file is paperwork that is allowed to fail.

deploy/2026.08.23.02.md

@@ -0,0 +1,53 @@
+# 2026.08.23.02
+
+SendOff — send a file to one of your own machines, or to somebody who has allowed you, and it lands in a
+real directory in their tree. Plus the deploy procedure's own corrections from the last rollout.
+
+**SCHEMA CHANGE.** `bun db:push` is a step. `sendoff_devices` and `sendoff_senders` are new. Without the
+push, `/sendoff` fails on a missing relation the first time it lists anything.
+
+**No dependency change** — `bun.lock` is untouched across `deploy/2026.08.23.01..HEAD` and `package.json`
+moved only its version. **Do not run `bun install`.**
+
+## What is in it
+
+- **SendOff.** `Documents/SendOff/<machine>/` for something you sent yourself,
+  `Documents/SendOff/<sender>/` for another account's files. The home is the one that account actually
+  browses — the owner's real login home, a member's managed home — because those are different directories
+  and writing to the wrong one makes a delivery invisible rather than wrong.
+- **Consent belongs to the recipient**, one row per sender, absence denies. Not a role grant: the person who
+  decides whether somebody may write into your home is you. A sender who has not been allowed gets the same
+  404 as a sender naming an account that does not exist, so the endpoint cannot be used to enumerate
+  accounts. The owner bypasses this as a SENDER only.
+- **`/sendoff`** — pick files, pick a target, send, with the consent list on the same screen. No received
+  view: the file browser already is the inbox. A dock tile, gated by the new `sendoff` permission.
+- **Push on arrival** — `officer/core:sendoff.landed` carries the folder name and a file count, and the
+  catalogue renders "3 file(s) from andre" with a route into Files at that folder. No app build needed;
+  the catalogue syncs.
+- **The deploy procedure deploys the TAG**, not `master`. `pull --ff-only` follows the branch, so a commit
+  pushed mid-rollout lands on some hosts and not others — which happened on the last release, harmlessly.
+- **`edge-pertento-bridge` is in a Deliberately skipped section** of `docs/servers.md`. It is down for some
+  days, and the last rollout spent four attempts and a minute apiece discovering that.
+
+## Every host
+
+1. `git fetch origin --tags` then `git merge --ff-only deploy/2026.08.23.02`
+2. **`bun db:push`** — new this release
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only. Step 3 restarts each plugin's own sidecar; that is the script's behaviour and belongs in
+the report rather than being omitted.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands, run `pm2` separately.
+
+## Hosts to expect trouble from
+
+- **`edge-pertento-bridge`** — skipped, see `docs/servers.md`. Name it and move on.
+- **`production-pertento-bridge`** — one release behind, and its `known_hosts` entries were cleared by the
+  owner on 2026-08-23 after a changed host key. The first connection will pin whatever key it offers. That
+  is expected; it is not a reason to stop, and it is not something to comment on beyond the report.
+
+## `officer-dev` — skip it
+
+The rollout runs from here and restarting `officer` ends the agent performing it. Name it as skipped.

deploy/2026.08.23.02.report.md

@@ -0,0 +1,69 @@
+# 2026.08.23.02 — deploy report
+
+**5 of 5 target hosts succeeded.** Two hosts were not targets: `officer-dev` (the rollout ran from it)
+and `edge-pertento-bridge` (deliberately skipped in `docs/servers.md`).
+
+Every target went the same way, in the plan's order: `git fetch origin --tags`, `git merge --ff-only
+deploy/2026.08.23.02`, `bun db:push`, `bun run plugins:update`, `pm2 restart officer`. No tree was dirty
+in tracked files, so no host was skipped for that. Every host fast-forwarded cleanly to
+`0a8fe1c2` — the tag commit, and exactly that commit on all five.
+
+The tag and `package.json` agree (`2026.08.23.02`), and the plan file was present at the tag.
+
+## Per host
+
+| Host                         | HEAD before | HEAD after | db:push | plugins:update | `officer` restart_time | Result  |
+| ---------------------------- | ----------- | ---------- | ------- | -------------- | ---------------------- | ------- |
+| `alpha`                      | `e6f1388a`  | `0a8fe1c2` | applied | 12/12 in 47s   | 67 → 68, online        | ok      |
+| `fofos`                      | `e6f1388a`  | `0a8fe1c2` | applied | 1/1 in 7s      | 21 → 22, online        | ok      |
+| `macbookpro`                 | `b22e9d86`  | `0a8fe1c2` | applied | no plugins     | 8 → 9, online          | ok      |
+| `production-pertento-bridge` | `68d60e40`  | `0a8fe1c2` | applied | 1/1 in 5s      | 0 → 1, online          | ok      |
+| `deadpool-rezio-bridge`      | `e6f1388a`  | `0a8fe1c2` | applied | 2/2 in 7s      | 6 → 7, online          | ok      |
+| `officer-dev`                | —           | —          | —       | —              | —                      | SKIPPED |
+| `edge-pertento-bridge`       | —           | —          | —       | —              | —                      | SKIPPED |
+
+`bun db:push` reported `Changes applied` on all five. It prompted for nothing — `sendoff_devices` and
+`sendoff_senders` are new tables, so the diff was additive.
+
+## What restarted, beyond what the plan asked for
+
+The plan named `officer` only, and `officer` is the only process this deploy restarted deliberately.
+`bun run plugins:update` restarts each plugin's own sidecar as it goes — that is the script's behaviour,
+not a fault, and it is the larger part of what moved:
+
+- `alpha` — twelve plugin sidecars bounced during the plugins step (atelier, bitcoin-wallet, email,
+  gitea, invoices, jellyfin, music, offscale, photos, soulseek, transmission, vault).
+- `fofos` — one (`officer-gitea`).
+- `production-pertento-bridge` — one (`officer-gitea`).
+- `deadpool-rezio-bridge` — two (`officer-email`, `officer-offscale`).
+- `macbookpro` — none; no plugins are installed there.
+
+After each restart, `pm2 jlist` showed `officer` `online` with `restart_time` incremented, and no process
+on any host was `errored`.
+
+## Hosts the plan flagged
+
+- **`production-pertento-bridge`** was one release behind (`68d60e40`, which is `deploy/2026.08.22.02`)
+  and fast-forwarded past `deploy/2026.08.23.01` to this tag in one step. Its `known_hosts` entry was
+  absent as expected; the first connection pinned the ED25519 key it offered. Expected, per the plan.
+- **`edge-pertento-bridge`** was not contacted at all. Nothing was spent on it.
+- **`macbookpro`** was awake and needed the documented PATH append (`/opt/homebrew/bin`) for the `bun`
+  steps, with `pm2` run separately through `$SHELL -ic`.
+
+## Things worth knowing, none of them failures
+
+- `fofos` carries one untracked file, `scripts/chk.ts`. A note, not a skip — a fast-forward cannot touch
+  it, and it was left alone.
+- `production-pertento-bridge` prints an nvm/`.npmrc` `globalconfig` warning before every command run
+  through `$SHELL -ic`. It is noise; every command it prefixed succeeded.
+- `macbookpro` prints `command not found: starship` on stderr from `.zshrc`. Harmless, but it corrupts
+  `pm2 jlist` output if stderr is merged into stdout — read that host's JSON with `2>/dev/null`.
+
+## What was not done
+
+- **`officer-dev` was not deployed.** Its checkout is already at `0a8fe1c2` (the release was cut here),
+  but nothing was pulled, no schema was pushed, no plugin was updated and no process was restarted. The
+  rollout ran from this machine, and restarting `officer` here ends the agent doing it. That host needs
+  a deliberate `bun db:push`, `bun run plugins:update` and `pm2 restart officer` from the owner before
+  `/sendoff` will work on it — the schema change means the missing `bun db:push` is not cosmetic.
+- No host got `bun install`. The plan forbade it: `bun.lock` is unchanged across this release.

deploy/2026.08.23.03.md

@@ -0,0 +1,64 @@
+# 2026.08.23.03
+
+Roles become a table, and the localization infrastructure lands. Both are groundwork — nothing in the UI
+changes and nothing reads the new table yet.
+
+**SCHEMA CHANGE.** `bun db:push` is a step, and `postdb:push` now seeds the new table automatically. The
+`roles` table is new. Additive only: no constraint is added to an existing column, so this cannot fail on
+existing data.
+
+**No dependency change.** `bun.lock` gained two lines and they are the local `i18n` workspace package being
+declared as a dependency of `officerdev` — a workspace path, not a registry fetch. **Do not run
+`bun install`.**
+
+## What is in it
+
+- **`roles` is a table**, seeded with the four the platform already had, each marked `isSystem` because the
+  code names it: `rolePermitsDevTools()` tests for `Developer`, bootstrap writes `Super Admin`, `users.role`
+  defaults to `Member`. Nothing reads the table yet — `USER_ROLES` is still the type and `authorize.ts` is
+  untouched. **There is deliberately no foreign key on `users.role`**; that change cannot go through
+  `db:push` and is a later release.
+- **The seed runs from `postdb:push`**, so a host gets the four rows on its next schema push with no extra
+  step here. It never overwrites an existing row.
+- **Localization phase 0** — plural selection through `Intl.PluralRules`, a `useFormat()` hook for dates and
+  numbers, three namespaced catalogs deep-merged at the bridge, `dir` on `<html>`, and key-parity tests that
+  fail the build on a missing key. The language picker now offers only the two catalogs that exist rather
+  than twenty codes, eighteen of which silently rendered English. Stored bare codes widen on read
+  (`en` → `en-GB`), with no database migration.
+- **SendOff's folder name is served rather than derived** — `/sendoff/targets` carries `displayName` and
+  `myFolder` from the same helper the writer uses, so a picker cannot name a folder the writer will not
+  create.
+
+## Every host
+
+1. `git fetch origin --tags` then `git merge --ff-only deploy/2026.08.23.03`
+2. **`bun db:push`** — and per the procedure, **verify by query, not by exit code.** Check that `roles`
+   exists and holds four rows on that host. `db:push` can fail and still exit 0.
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only. Step 3 restarts each plugin's own sidecar; that is the script's behaviour and belongs in
+the report.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands, run `pm2` separately.
+
+## The check that matters this release
+
+```sql
+select count(*) from roles;   -- expect 4
+```
+
+Four rows named `Super Admin`, `Admin`, `Developer`, `Member`. If a host shows the table but zero rows, the
+`postdb:push` hook did not run — report it as a failure for that host rather than as a success, and say so
+per host in the report.
+
+No direct SQL is needed and none is authorised for this release.
+
+## Hosts to expect trouble from
+
+- **`edge-pertento-bridge`** — skipped, per `docs/servers.md`. Name it and spend nothing on it.
+- **`production-pertento-bridge`** — came back last release after two behind. Nothing special expected.
+
+## `officer-dev` — skip it
+
+The rollout runs from here. It already holds the release and the four rows, verified locally.

docs/chat-sessions-list.md

@@ -57,6 +57,25 @@ so the walk exists — this is a second consumer of it, not a new class of work.
 live count needs no new endpoint. Correlate `live.claudeSessionId === session.id`; a live row whose id is
 still null contributes to no directory (see above).
 
+**`/chat/live` returns only agents unless asked otherwise.** `?kind=` takes `agent` (the default),
+`commander`, or `all`; anything else is a 400 rather than a silent fallback, and the plural forms are
+accepted because the web client's own type is already `'agents' | 'commanders'`.
+
+The default is the point. Commanders run background work and the phone swipes between live chats one at a
+time, with no room for tabs and no way to skip a row — so a client that forgets the parameter must not be
+handed a deploy commander. Defaulting to `agent` means forgetting can only ever under-report. The two
+callers that genuinely want both say `kind=all`, which is a fair price: they are few, they are on screens
+built to show both, and they are the ones positioned to notice if the answer is wrong.
+
+`counts` describes **every** live session regardless of the filter, so a filtered caller still renders
+`Agents (n) / Commanders (n)` without a second request. That is what stops a server-side filter from
+costing more round trips than the client-side one it replaced.
+
+Which rows are commanders comes from `command_hq_sessions`, **not** from the working directory — a
+commander chooses its own cwd, so the directory answers nothing. `GET /chat/sessions` reports no
+`isCommander` at all, because it removes commanders entirely; a list that excludes them has nothing to say
+about which of its rows is one.
+
 ---
 
 ## Landmines

docs/localization.md

@@ -0,0 +1,366 @@
+# Localization
+
+**Status: DESIGN, NOT BUILT — with a working 5% skeleton already in the tree.**
+
+This is an execution plan. It is written to be handed to an agent who has not had the conversation
+that produced it, so it states the decisions and the reasons for them, not just the steps.
+
+Every count here is a **measurement taken on 2026-08-23**, not a claim that stays true — the whole
+point is for it to fall. Re-derive with `bun scripts/i18n/scan-hardcoded.ts` rather than trusting the
+number beside it, and do not wire these into `docs:check`: a guard that fails when the count drops
+would be a guard against progress.
+
+---
+
+## What this is
+
+Every word the UI shows a person should come from a catalog keyed by locale, so the platform can be
+read in a language other than English. Routes stay English (`/minesweeper`, `/chat`) — that is a URL
+decision, deferred, and nothing here depends on it.
+
+The scope is **the web UI only**. Not the server, not the plugins, not email or push. See D1 for what
+the server does instead, which is the one decision that reaches outside this boundary.
+
+---
+
+## What exists today, and what it cannot do
+
+There is already an i18n system. It is small, hand-rolled, has no npm dependency, and it works. It is
+also about **5% deployed**, and that gap is the whole job.
+
+|                                           |                                                                            |
+| ----------------------------------------- | -------------------------------------------------------------------------- |
+| `src/workspaces/i18n/`                    | the package: `I18nProvider`, `useTranslation`, `resolveKey`, `interpolate` |
+| `src/apps/officer-web/lib/i18n.ts`        | a typed wrapper binding keys to `en.json`                                  |
+| `src/apps/officer-web/lib/I18nBridge.tsx` | reads `settings.languages.default`, feeds the provider                     |
+| `src/apps/officer-web/locales/`           | `en.json` and `pt.json` — **46 keys each, in sync**                        |
+| components actually using it              | **3** — `UserMenu`, `Languages`, `ChangePassword`                          |
+
+What it already does well, and which this plan keeps: dot-path lookup, `{{param}}` interpolation,
+fallback to `en`, and **type-safe keys** via `TranslationKeys<typeof en>` — a wrong key is a
+typecheck failure, which is worth more than it sounds when one agent is editing 400 files.
+
+**What it cannot do yet**, each of which is a task below:
+
+1. **No plural rules.** `1 file` / `2 files` has no expression. `Intl.PluralRules` is built into the
+   runtime and unused.
+2. **No locale-aware dates or numbers.** ~23 `toLocaleDateString/TimeString/String()` call sites use
+   the _browser's_ locale, not the user's chosen one, so a Portuguese UI shows American dates.
+3. **No fallback chain.** `resolveKey` falls back to `en` and nothing else, so `pt-BR` cannot inherit
+   from `pt`.
+4. **One catalog, one workspace.** `locales/` lives inside `officer-web`. The 213 panel files in
+   `officerdev` and the 91 in `components` have no catalog of their own.
+5. **Silent, ugly misses.** A missing key renders its own dot-path (`settings.profile.foo`) to the
+   user. No warning, no test.
+6. **Twenty languages offered, two that exist.** The picker in `Languages.tsx` lists ~20 codes
+   including Hebrew and Greek. Choosing any of the eighteen silently yields English.
+
+### The size of the remaining work
+
+Measured, not guessed — `bun scripts/i18n/scan-hardcoded.ts`:
+
+| area                  | files   | occurrences |
+| --------------------- | ------- | ----------- |
+| `officer-web` (shell) | 132     | 556         |
+| `officerdev` (panels) | 213     | 567         |
+| shared `components`   | 91      | 47          |
+| **total**             | **436** | **1170**    |
+
+**884 distinct strings**, of which **88 need interpolation**. Against 46 keys today.
+
+That is a floor, not a ceiling. The scanner cannot see multi-line JSX, ternaries inside JSX, strings
+passed down as props, or anything a plugin renders. Budget for **1200–1500 keys**.
+
+---
+
+## Decisions
+
+### D1. The web UI only — and the server returns codes, not prose
+
+The server should **never emit user-facing prose**. It returns a stable machine-readable code; the UI
+owns every word a person reads and localizes it like any other string.
+
+```jsonc
+// not this
+{ "error": "The Minesweeper session is not running" }
+// this
+{ "code": "MINESWEEPER_NOT_RUNNING" }
+```
+
+This is better than translating the server, for reasons that have nothing to do with translation. A
+code maps to exactly one failure site, so it is greppable and a support conversation has something
+precise to quote. Prose drifts; a code does not. And the server stops needing to know who is reading.
+
+- **Phase 1 establishes the convention** so new code stops adding debt: new error paths emit codes,
+  and the catalog gets an `errors.*` namespace.
+- **Phase 2 migrates the existing ~53** prose strings in `src/servers`. Not in this plan's scope.
+- **Unmapped code** renders a generic localized line **with the code visible**. Never a blank, never
+  a raw key.
+
+**The trap, and it is a real one: a code must not leak more than the prose it replaces.** Where a
+refusal is deliberately vague, the code has to stay equally vague. `officer-secret-store` returns a
+byte-identical `403` for "no such app" and "no grant" precisely so a caller cannot enumerate what
+exists; splitting that into `APP_UNKNOWN` and `GRANT_MISSING` would hand back the enumeration oracle
+the prose was careful not to be. When in doubt, one code for one _response_, not one per branch.
+
+### D2. Regional locales, BCP 47, and every catalog is complete
+
+`pt-PT`, `pt-BR`, `en-GB`, `en-US` — not bare `pt` and `en`. Portuguese is the case that forces it, and
+it is the owner's own language, so getting it wrong is felt immediately.
+
+**Every locale ships a COMPLETE catalog. There is no regional inheritance and no overlay.** A file holds
+every key the UI has, translated for that locale, or it does not ship.
+
+This reverses an earlier version of this decision, which had `pt-BR` inherit from `pt` so a base catalog
+carried the shared bulk and a regional file carried only the differences. That is the conventional design
+and it was rejected for a product reason that outranks the engineering one:
+
+**A missing European Portuguese key would have fallen through to Brazilian.** European and Brazilian
+Portuguese differ most in exactly the vocabulary this UI is full of — technical terms — and the platform is
+being sold into the European Portuguese market first. So the failure mode of an overlay is a Portuguese
+reader getting Brazilian phrasing on whichever strings nobody remembered to override, silently, and with no
+signal that it happened. Owner's call, and it is the right one: a reader must never be served a neighbouring
+variant's words.
+
+The engineering objection to full catalogs was drift — two near-identical files diverging within a month.
+That is answered by making the **key-parity test load-bearing** rather than advisory (see Tooling): a locale
+missing a key that `en` has fails the build, so an incomplete catalog cannot ship. Completeness is enforced
+by the test rather than by a fallback quietly papering over a gap.
+
+It is also less code. `resolveKey` looks in the active locale and then, only if the key is genuinely absent,
+in `en` — which per D8 is a bug the parity test should already have caught. There is no chain to walk, no
+base-versus-overlay merge order, and no question about which file a given string lives in.
+
+`Intl` takes BCP 47 tags natively, so dates, numbers and plurals come out right with no extra work.
+
+**Migration:** `settings.languages.default` stores bare codes today (`pt`). The picker must move to regional
+tags, and stored values need a one-time widening (`pt` → `pt-PT`, `en` → `en-GB`). Prefer widening on read
+over a database migration — a stale bare code should resolve, not fail.
+
+**Consequence for translation work:** a new locale is a whole catalog, not a diff. Machine-translate the
+full file and have it reviewed, rather than hand-writing overrides against a base. For `pt-PT` and `pt-BR`
+that means two complete passes, reviewed separately, because the whole point is that neither borrows from
+the other.
+
+### D3. RTL — prepare, do not ship
+
+No right-to-left locale ships in this phase. But since 436 files are being opened anyway, they get
+opened once:
+
+- **CSS logical properties** as components are touched — `margin-inline-start`, `padding-inline`,
+  `text-align: start` — instead of `left`/`right`. Tailwind has `ms-`/`me-`/`ps-`/`pe-` for this.
+- **`dir` on `<html>`**, driven by the locale, wired now and set to `ltr` for every shipped locale.
+
+The cost during a pass we are already making is close to nothing. The cost of a second pass over 436
+files later is not. Hebrew stays in the picker but is not selectable until a catalog exists (see the
+"twenty offered, two that exist" defect above — fix it by filtering the picker to shipped locales).
+
+### D4. Extend the existing package. Do not adopt a library
+
+`react-i18next`, `lingui` and `formatjs` are all better than what is here, and all of them are
+dependencies. This repository froze its lockfile and hand-rolled a secret store rather than take
+one, for reasons written down in `CLAUDE.md` → "Installs are frozen".
+
+The gap is smaller than it looks, because the hard parts are in the runtime already: `Intl.PluralRules`,
+`Intl.DateTimeFormat`, `Intl.NumberFormat`, `Intl.RelativeTimeFormat`. What is missing is roughly 150
+lines of glue, listed in "What it cannot do yet".
+
+Revisit this only if message _formatting_ gets genuinely complex — nested selects, gendered forms.
+ICU MessageFormat is a real specification and reimplementing it would be the wrong kind of ambition.
+
+### D5. Keys, not English source text
+
+`t('settings.profile.changePassword.title')`, never `t('Change Password')`.
+
+Source-text keys (the gettext and lingui style) read nicely and mean an untranslated string still
+renders. They also mean **editing an English word invalidates every translation of it**, and this
+codebase already has typed keys — a wrong key is a compile error today, and that is not worth
+trading away.
+
+### D6. Catalogs live per workspace, merged at the bridge
+
+Not one god file. Three:
+
+```
+src/apps/officer-web/locales/          →  namespace  app.*
+src/workspaces/officerdev/src/locales/ →  namespace  panel.*
+src/workspaces/components/locales/     →  namespace  ui.*
+```
+
+`I18nBridge` deep-merges them before handing the map to the provider. Each workspace exports its own
+typed `useTranslation` the way `officer-web/lib/i18n.ts` does today.
+
+Two reasons, and the second is the one that matters for execution. Strings belong next to the code
+that renders them, so a panel stays self-contained. And **one 900-key `en.json` is a merge conflict
+on every parallel edit** — with several agents or several days of work, a single file is a queue.
+
+Namespaces also make an unqualified key impossible to place wrongly: `ui.*` is shared, so anything
+under it must not mention a feature.
+
+### D7. Plurals and formatting go through `Intl`
+
+A plural value becomes an object; a string stays a string:
+
+```jsonc
+"panel.files.selected": { "one": "{{count}} file selected", "other": "{{count}} files selected" }
+```
+
+`t()` picks the branch with `new Intl.PluralRules(locale).select(count)` when `count` is passed.
+Categories are per-locale — English and Portuguese use `one`/`other`, Arabic uses six — so the shape
+must be an open record, never a two-field type.
+
+A `useFormat()` hook returns `date`, `time`, `dateTime`, `number` and `relative`, each bound to the
+active locale. **The ~23 `toLocale*` call sites move to it.** Left alone they follow the browser's
+locale and quietly contradict the rest of the UI.
+
+### D8. A missing key falls back to English and is loud in dev
+
+Never render a dot-path to a person. Resolution walks the chain, ends at `en`, and only if English is
+missing too does it render the key — which at that point is a bug the parity test below should have
+caught.
+
+In dev, a miss logs once per key with the key and the locale. In production it is silent.
+
+---
+
+## The key naming convention
+
+Three segments, sometimes four. **Name the role, never the text.**
+
+```
+<namespace>.<area>.<component>.<element>
+
+app.settings.profile.changePassword.title
+panel.files.contextMenu.rename
+panel.chat.composer.placeholder
+ui.button.cancel
+app.errors.MINESWEEPER_NOT_RUNNING
+```
+
+- `namespace` — `app` / `panel` / `ui`, per D6.
+- `area` — the route or panel it belongs to; matches the directory.
+- `component` — the file, lowercased.
+- `element` — what it _is_: `title`, `description`, `placeholder`, `confirmLabel`, `emptyState`.
+
+Rules that keep 1200 keys navigable:
+
+- **Never key by the English words.** `ui.button.save`, not `ui.button.saveText` and never
+  `ui.button.Save`.
+- **Never build a key at runtime.** `t(\`panel.${kind}.title\`)` defeats both the type checker and
+  the extractor. Use an explicit map from the dynamic value to literal keys.
+- **`ui.*` may not name a feature.** If a shared component needs feature words, the caller passes
+  them as a prop.
+- **One key per meaning, not per occurrence.** "Cancel" in twelve dialogs is `ui.button.cancel` once.
+  But a word that is the same in English and different elsewhere — "Post" the noun and the verb —
+  gets two keys. When unsure, split: merging later is safe, splitting later is not.
+
+---
+
+## What must never be translated
+
+Getting this wrong is worse than missing a string, because it corrupts data or breaks a contract.
+
+- **Agent and chat output.** Whatever Claude or opencode wrote. It is content.
+- **User content** — file names, paths, terminal output, code, commit messages, note bodies.
+- **Identifiers that cross a boundary** — route paths, permission keys (`registry.ts`), error _codes_
+  (the code is the key; its message is what gets translated), app ids, sidecar names, PM2 process
+  names, database values.
+- **Log lines and thrown `Error` messages** that are not rendered to a user. They are for whoever is
+  reading a terminal at 4am, and they should stay greppable in one language.
+- **"Officer"**, and product names generally.
+
+---
+
+## Execution
+
+Four phases. Each is a commit that leaves the tree green — the app must run in English at every point,
+because a half-converted UI is unreviewable.
+
+### Phase 0 — infrastructure, no visible change
+
+Everything in "What it cannot do yet". Nothing in this phase touches a component.
+
+1. `resolve.ts`: fallback chain (D2), plural selection (D7), dev-mode miss warning (D8).
+2. `I18nProvider`: accept a merged map; expose `useFormat()`.
+3. `I18nBridge`: deep-merge the three catalogs (D6); set `dir` on `<html>` (D3).
+4. `Languages.tsx`: regional tags, and **filter the picker to locales that actually exist**.
+5. Settings migration: widen stored bare codes on read.
+6. Scaffold `locales/` in `officerdev` and `components`, each with its typed hook.
+7. Land the tooling below.
+
+Phase 0 is the whole plan's risk. It is also small, and it is the only part where a wrong decision is
+expensive to reverse — review it before phase 1 starts.
+
+### Phase 1 — shared components (91 files, ~47 strings)
+
+Smallest, highest reuse, and it establishes `ui.*` before anything depends on it. Do this first so
+phases 2 and 3 can reach for `ui.button.cancel` instead of inventing it twice.
+
+### Phase 2 — the shell (132 files, ~556 strings)
+
+`officer-web`: settings, dock, header, screens. Highest-traffic text and the part a reviewer will
+look at first. Convert per directory, one commit per area.
+
+### Phase 3 — the panels (213 files, ~567 strings)
+
+`officerdev` apps. The largest surface and the most parallelizable, because panels barely share
+strings. **One panel per commit** — this is where per-workspace catalogs earn their keep, but two
+agents in the same panel will still conflict.
+
+### Then: `pt-PT`
+
+Only after English is fully keyed. Translating against a moving catalog is wasted work.
+
+---
+
+## Tooling and guardrails
+
+Without these, 1200 keys rot. All three are small and belong in phase 0.
+
+**`scripts/i18n/scan-hardcoded.ts`** — already written and committed. Reports every candidate
+hardcoded string by area and file. It is how the numbers above were produced, and it is the progress
+meter: the count goes down as work lands.
+
+**A key-parity test — and per D2 this is now load-bearing, not a nicety.** For each shipped locale, every
+key that `en` has must be present IN THAT LOCALE'S OWN FILE. Fails the build on a gap, the same way
+`bun docs:check` fails on a stale number.
+
+With full catalogs and no overlays, this test is the only thing standing between "complete translation" and
+"silently English in patches". It replaces the fallback that used to hide a gap, so it has to be as
+unavoidable as the typecheck: a missing key is not a warning, it is a red build.
+
+**A no-new-hardcoded-strings check.** Once an area reaches zero, add it to an allow-list the scanner
+enforces, so the next feature cannot reintroduce debt. Add this per area as it completes — enabling
+it globally on day one would just be red forever.
+
+**Also worth having:** an unused-key report. Keys outlive the components that used them, and nothing
+else will ever notice.
+
+---
+
+## Verification
+
+- `bunx tsgo` clean. A wrong key is a type error, so this is the primary check.
+  **Note for this machine:** `earlyoom` (`-r 3600`) SIGTERMs `tsgo` under memory pressure — it dies
+  around 15s with `Command failed`. That is not a type error. Free memory or scope the check.
+- `bun test` — parity test green for every shipped locale.
+- `bun scripts/i18n/scan-hardcoded.ts` — count strictly decreasing per phase.
+- By hand: switch the locale to `pt-PT` and walk the converted area. Untranslated strings should read
+  as **English, never as dot-paths**.
+- Check a plural at 0, 1 and 2, and a date, in both locales. These are the two things that look fine
+  in English and wrong everywhere else.
+
+---
+
+## Open questions
+
+1. **Routes.** Deferred deliberately. Nothing here depends on it, and localized URLs bring
+   canonicalization and redirect questions that are not worth answering yet.
+2. **Who translates?** Machine translation for `pt-PT` and `pt-BR` reviewed by the owner is the
+   obvious first pass. Any locale beyond Portuguese needs an answer to this before it is offered.
+3. **Plugin frontends** are out of scope and will need a catalog-merging contract in the plugin
+   manifest. Their strings are not counted above.
+4. **The `translateTo` setting already in `settings.languages`** is about translating _content_, not
+   the UI. It is a different feature that happens to sit in the same object — do not conflate them.
+5. **Does a member see the owner's locale anywhere?** Any server-rendered or cached string shared
+   between accounts needs a locale decision. D1 mostly removes this by removing server prose.

docs/sendoff.md

@@ -0,0 +1,93 @@
+# SendOff — files land in the user's own tree, and a push says where
+
+**From:** mobile · **Date:** 2026-08-23 · **v2, replacing this morning's spec entirely.** The v1
+design (staging area, transfer/target/file tables, ack lifecycle, TTL cleanup) is withdrawn — Andre's
+observation kills it: every user already has a filesystem on the server, a file browser on the web,
+and a Files app on the phone. SendOff is not a new storage system; it is a folder convention, one
+endpoint, and a push.
+
+## The convention
+
+```
+~/Downloads/sendoff/from-<username>/   ← a file another USER sent you
+~/Downloads/sendoff/<machine>/         ← a file you sent yourself, aimed at a named device
+```
+
+That is the whole data model. Nothing to ack, nothing to expire, nothing to clean up — the files are
+ordinary files in the recipient's tree, visible in every file UI that already exists, managed like
+anything else they own.
+
+## The endpoint
+
+```
+POST /api/sendoff/send
+  multipart: any number of `file` parts + a `meta` part:
+    { "toUser": "<username>" }        — cross-user: writes into THEIR tree, from-<sender>/
+    { "machine": "<device name>" }    — self: writes into own tree, <machine>/
+  → { path: "Downloads/sendoff/…", files: [{ name, size }] }
+```
+
+Server-side because of the cross-user case: `/api/file-browser/upload` correctly writes only the
+caller's own tree, and that must not change. This endpoint is the one sanctioned door into another
+user's filesystem, and it writes ONLY under `Downloads/sendoff/from-<sender>/` — the sender's
+identity comes from their token, never from the payload, so the folder name cannot lie about who
+sent it. Filenames sanitised, collisions suffixed `(1)` — never overwritten; a second send of the
+same name is a second file.
+
+Whether user A may send to user B at all is a platform policy decision (everyone on the server? a
+grant?) — flagging it rather than deciding it here.
+
+## The push
+
+On write, push to the recipient's devices through the existing pipeline:
+
+```
+{ "officer": { "c": "officer/core:sendoff.landed", "path": "Downloads/sendoff/from-andre" } }
+alert: "photo.jpg from andre" / "3 files from omega"
+```
+
+The push catalogue's route for the category:
+
+```
+officer://files?path={path}
+```
+
+Mobile opens routes from the catalogue verbatim (`openNotificationRoute`), and Officer now parses
+`officer://files?path=…` into the Files app at that folder. The web can deep-link its file browser
+the same way.
+
+For a `machine`-targeted send, push only to that machine's device if it can be identified; to all
+the user's devices otherwise — the path in the folder name already says who it was for.
+
+## Devices
+
+The `machine` name needs a picker on the sending side, so a minimal registry survives from v1:
+
+```
+devices: id (client uuid), user_id, name, platform, last_seen_at
+POST /api/devices/register { id, name, platform }   (upsert; called on every app start)
+GET  /api/devices → { devices }                     (the "send to my…" picker)
+PATCH /api/devices/:id { name } · DELETE /api/devices/:id
+```
+
+No link to transfers — nothing references a device row except the picker and, best-effort, push
+targeting.
+
+## Web UI
+
+One send form: files + target (one of my machines / another user), POST, done. Received files need
+no UI at all — they are in the file browser already.
+
+## What mobile already does (shipped against this)
+
+- Registers the device on start (silent failure until the endpoint exists).
+- Parses `officer://files?path=…` and opens the Files app at that path — this is the piece that
+  makes the push tap land somewhere.
+- SendOff screen: the device's name (the folder senders will aim at), and an explanation of where
+  arrivals land. Sending FROM the phone comes later, likely through the existing share sheet.
+
+## Out of scope
+
+Receiving in the browser (already exists — it is the file browser); cross-user permission model
+(platform decision); phone-side arbitrary-file sending (needs a document picker; the share sheet is
+the natural door and is a later step).

docs/servers.md

@@ -29,13 +29,32 @@ Seven, all running.
 | `alpha`                      | 100.64.0.1  | `pastilhas` | `~/officerdev/platform`             | `officer.pastilhas.dev`           |
 | `fofos`                      | 100.64.0.17 | `pastilhas` | `~/officerdev/platform`             | `officer.fofosfluffybastards.com` |
 | `macbookpro`                 | 100.64.0.9  | `pastilhas` | `~/projects/officer-suite/platform` | `macbookpro.pastilhas.dev`        |
-| `edge-pertento-bridge`       | 100.64.0.15 | `pastilhas` | `~/officerdev/platform`             | `edge.pertento.ai`                |
 | `production-pertento-bridge` | 100.64.0.12 | `pastilhas` | `~/officerdev/platform`             | `officer.pertento.ai`             |
 | `deadpool-rezio-bridge`      | 100.64.0.21 | **`br`**    | `/home/br/officerdev/platform`      | `officer.rezio.dev` `[pending]`   |
 
 Only `platform.officer.dev` is public (77.42.39.155). The rest resolve to tailnet addresses and are
 reachable from inside only.
 
+## Deliberately skipped
+
+A host here is NOT a deploy target. A rollout names it as skipped and moves on — it is not a failure,
+and it must not be reported as one.
+
+| Host                   | Since      | Why                                                              |
+| ---------------------- | ---------- | ---------------------------------------------------------------- |
+| `edge-pertento-bridge` | 2026-08-23 | Down, and staying down for some days. Owner's call, not a fault. |
+
+Its row, kept so restoring it is one move:
+
+```
+| `edge-pertento-bridge`       | 100.64.0.15 | `pastilhas` | `~/officerdev/platform`             | `edge.pertento.ai`                |
+```
+
+On 2026-08-23 the deploy agent spent four attempts and up to 60s per try on this host before reporting
+it unreachable — TCP on 22 accepted, then no SSH banner. That work was correct and entirely wasted, which
+is what this section exists to prevent: a host that is known to be down should cost a line in a report,
+not a retry budget.
+
 ### Names that disagree with themselves
 
 Three hosts answer to more than one name, and `tailscale status` is not always the one in use:

package.json

@@ -1,12 +1,15 @@
 {
   "name": "officer",
-  "version": "2026.08.21.04",
+  "version": "2026.08.23.03",
   "private": true,
   "type": "module",
   "workspaces": [
     "src/databases/*",
     "src/workspaces/*"
   ],
+  "engines": {
+    "bun": "1.3.x"
+  },
   "scripts": {
     "preinstall": "node -e \"var v = +process.versions.node.split('.')[0]; if (v < 22) { console.error('Node 22 or newer required (got ' + process.versions.node + '). Run: nvm use 22'); process.exit(1); }\"",
     "gen:index": "bun run ./scripts/gen-index.ts",
@@ -27,14 +30,16 @@
     "build:dashboard": "bun run ./scripts/build/dashboard.ts",
     "db:gen": "cd src/databases/officer_db && bun run generate",
     "db:push": "bun run scripts/gen-plugin-schemas.ts && cd src/databases/officer_db && bun run push",
-    "postdb:push": "bun run --env-file=.env scripts/backfill-session-models.ts",
+    "postdb:push": "bun run --env-file=.env scripts/backfill-session-models.ts && bun run --env-file=.env scripts/seed-roles.ts",
     "db:migrate": "cd src/databases/officer_db && bun run migrate",
     "dev:emailer": "cd src/workspaces/emailer && bun run dev",
     "format": "{ git diff --name-only HEAD -- 'src/**/*.ts' 'src/**/*.tsx'; git ls-files --others --exclude-standard -- 'src/**/*.ts' 'src/**/*.tsx'; } | xargs -r prettier --write",
     "format:all": "prettier --write \"src/**/*.{ts,tsx}\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
     "setup": "bash scripts/install.sh",
-    "check:theme": "bun scripts/check-theme-tokens.ts"
+    "check:theme": "bun scripts/check-theme-tokens.ts",
+    "docs:check": "bun run scripts/docs-check.ts",
+    "skills:platform": "bun run scripts/gen-platform-skill.ts"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",

prompts/deploy-commander.md

@@ -18,6 +18,21 @@ there is a release to deploy that has not been deployed.
 git ls-remote --tags origin 'refs/tags/deploy/*'
 ```
 
+**Poll a LOCAL remote, never the public hostname.** On `officer-dev`, gitea is a plugin on the same machine
+— it listens on `100.64.0.13:10023` and on loopback — so `origin` points there. `gitea.officer.dev` resolves
+to the public address and arrives through Nginx Proxy Manager, where every connection appears to come from
+one container IP: internet bots get that IP penalised by `srclimit_penalise`, and SSH is then refused for
+long stretches.
+
+That is not hypothetical and it is not subtle when it happens. On 2026-08-21 a tag pushed at 21:47 was not
+noticed until 23:07 — eighty minutes of `ls-remote` being closed on, forty-odd ticks, all correctly logged
+and retried. On 2026-08-22 it refused at 08:35 and again at 12:58. The loop is not at fault in any of those:
+it logs the exit code, sleeps, and carries on. It is simply asking through a door that is sometimes shut.
+
+If `ls-remote` fails with `Connection closed by <public ip> port 22`, that is this, and the remote is wrong
+rather than the credentials. Loopback needs a `known_hosts` entry that may not exist; the tailnet address is
+already trusted.
+
 A release is **a tag**, named `deploy/<version>` — `deploy/2026.08.21.01`. Nothing else triggers you: not
 a commit message, not a branch, not a push.
 
@@ -81,6 +96,21 @@ load-bearing. A missing report is a missing record; a missing lock is a second d
 It sits under `data/` rather than in the repository so a `git pull` can never clobber it, and so a fresh
 clone does not arrive believing it has deployed nothing.
 
+## Before a release is tagged — not your job, but know it happened
+
+Whoever cuts a release runs `bun run docs:check` first and leaves it green. It compares documented claims
+against values derived at run time — how many permissions the registry holds, how many PM2 entries Officer
+is, whether every settings route Spotlight offers actually exists — and exits non-zero on drift.
+
+It exists because "update the docs before a deploy" is a step that gets skipped at two in the morning and
+whose absence is invisible. On 2026-08-22 it found, immediately: `platform/CLAUDE.md` claiming 27 permission
+entries against a registry holding 18, and the workspace `CLAUDE.md` claiming twenty PM2 entries against
+thirteen, listing eleven processes that do not run here while omitting six that do.
+
+**You do not run it and you do not fix documentation.** You execute a plan and report. It is here so that a
+report saying "the docs are stale" has somewhere to point, and so nobody adds doc-fixing to a rollout, where
+it would put a prose edit between two hosts.
+
 ## The release
 
 The tag names the version. The commit it points at carries the rest:
@@ -106,6 +136,11 @@ That document holds every machine, its tailnet name, **its login user**, its che
 platform runs on it. Read it at the start of every deploy, and treat the hosts marked as having no
 platform as out of scope.
 
+It also has a **Deliberately skipped** section. A host listed there is not a target: name it as skipped
+in the report and spend nothing on it. On 2026-08-23 a host that was known to be down cost four attempts
+and a minute apiece before being reported unreachable — correct behaviour against a list that had not been
+told. Read that section before you try to reach anything.
+
 **The login is not always `pastilhas`.** `deadpool-rezio-bridge` runs as `br`, permanently, and more will.
 Take the user from the table — an orchestrator that hard-codes one fails on that host silently, because
 `Permission denied (publickey)` looks like a broken key rather than a wrong username.
@@ -133,7 +168,15 @@ assemble at the end from memory is a report that will be wrong about the host th
    `--porcelain` counts untracked files, and on 2026-08-21 that skipped a host over one stray script a
    fast-forward could never have touched. Untracked files get a note in the report, not a skip. Never
    discard someone's work to ship a release.
-2. `git pull --ff-only`. A non-fast-forward means that checkout has diverged: skip and report.
+2. **`git fetch origin --tags` then `git merge --ff-only <tag>`** — the TAG you are deploying, not
+   `master`. `git pull --ff-only` follows the branch, so a commit pushed while you are rolling out lands
+   on some hosts and not others, and "deployed the tag" stops being true of any of them. That happened on
+   2026-08-23: every host came up one commit past the tag because a docs commit landed mid-rollout. It was
+   harmless and it need not have been.
+
+   A non-fast-forward means that checkout has diverged: skip and report. A tag that will not fast-forward
+   because the host is AHEAD is the same answer — report it, do not reset.
+
 3. **Update the plugins.** `bun run plugins:update`. Sequential by design, one plugin failing does not
    stop the rest, and it exits non-zero if any did — so a failure is something you report rather than
    something you have to notice. A failure here is usually an uncommitted change in that plugin's own
@@ -149,6 +192,51 @@ assemble at the end from memory is a report that will be wrong about the host th
 If a host fails, **continue to the next one**. A half-rolled-out release that is honestly reported beats
 one that stopped in the middle and said nothing about the four hosts it never reached.
 
+### Schema changes, and why `db:push` cannot be trusted
+
+**`drizzle-kit push` can fail and still exit 0.** Verified on 2026-08-23 against a scratch database: a
+change that violated a foreign key printed the Postgres error, created part of the change, left the rest
+undone, and returned zero. `bun db:push` wraps it, so a plan step that reads `bun db:push` can report
+success while the schema is half-applied.
+
+So on any release whose plan says the schema changed:
+
+**Never take the exit code as the answer. Check the database.** Query for the specific thing the plan
+introduced — the table, the column — on that host, against that host's own database. `Changes applied` on
+stdout is not evidence, and neither is exit 0. A report that says "schema ✓" without a query behind it is
+a guess.
+
+**Some changes cannot go through `db:push` at all, and the plan should say so.** The shape that fails is
+create-then-constrain: a new table plus a foreign key onto it from an existing column. `push` creates the
+table empty and adds the constraint in the same run, so every existing row violates it. There is no
+ordering of `push` invocations that fixes this, because the seed has to happen between the two halves.
+
+**When the plan says the schema needs direct SQL — last resort, and only when the plan says it.**
+
+This is allowed and it is not a licence to improvise. The rules, in order:
+
+1. **The Drizzle schema is the source of truth, always.** The SQL you run exists to make the database match
+   what the schema code already says. If you find yourself writing SQL the schema does not describe, stop —
+   that is a code change and it is not yours to make on five production hosts at 3am.
+2. **The plan must contain the exact SQL.** Written by whoever cut the release, reviewed before the tag.
+   Do not compose it yourself from the diff, and do not adapt it per host: same statements, every host, or
+   the fleet has diverged in a way nothing will detect.
+3. **Idempotent, or guarded.** `create table if not exists`, `insert … on conflict do nothing`,
+   `alter table … add constraint` only after checking `pg_constraint`. A deploy that is safe to run twice
+   is a deploy that can be retried, and being retryable is what stops a partial rollout becoming a
+   forensic exercise.
+4. **Then run `bun db:push` anyway**, and expect it to be a no-op. That is the proof the two agree: if
+   `push` still wants to change something after your SQL, the SQL was wrong or incomplete, and that is a
+   finding for the report rather than something to push past.
+5. **Verify per host, by query**, and put the result in the report per host. Not "applied on all five" —
+   the specific check, and its answer, for each.
+6. **A host where the SQL fails is a failed host.** Report it, move to the next, and do not attempt a
+   repair you invented.
+
+**One thing to refuse outright:** `--force`. It exists to answer prompts unattended, and the prompts it
+answers are the destructive ones. On five hosts holding real data, a flag whose whole job is to say yes to
+"this will truncate a table" is not a convenience. If a change needs `--force` to apply, it needs a human.
+
 ### Skip the host you are running on
 
 Entirely. Do not pull it, do not restart anything on it, and **name it in the report as skipped**.

scripts/deploy-watch.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+#
+# The wait half of the deploy commander: poll for a release tag, and when one appears that has not been
+# attempted, spawn a headless agent to deploy it.
+#
+# WHY THIS IS IN THE REPOSITORY AND NOT WRITTEN FRESH EACH ARMING
+#
+# prompts/deploy-commander.md says the watcher loop is rewritten from scratch every time one arms, and
+# treats that as a given. It is also how the same defect keeps arriving. The loop that was on disk at
+# data/deploy-watch.sh from 2026-08-21 gated on "$v.done" — a file that exists only on SUCCESS — and never
+# called deploy-claim.sh at all. That is precisely the retry storm the claim script was written to make
+# impossible, reintroduced in the one place the claim script cannot reach: the caller that decides whether
+# to invoke it. A rule enforced by a script nobody calls is not enforced.
+#
+# So the loop lives next to the claim it depends on, and changes with it.
+#
+# THE BASELINE IS THE CLAIM, NOT THE SUCCESS
+#
+# A watcher needs to know what counts as new. Here that is "no claim directory for this version" — a record
+# of what has been HANDLED, not of what has SUCCEEDED. The distinction is the whole point: a release that
+# failed is handled. It is looked at by a human, not retried by a loop.
+#
+# deploy-claim.sh honours a pre-existing .done with no .claim, so releases deployed before it existed are
+# already skipped and arming this today fires on none of them.
+#
+# THE CLAIM IS TAKEN HERE, BEFORE THE SPAWN
+#
+# An action that claims its own work has claimed nothing if it dies before getting that far. So the loop
+# claims, then spawns — which means the child must be TOLD the claim is already held. It is about to read
+# prompts/deploy-commander.md, whose claim instruction is addressed to whoever reads it, and an obedient
+# child that claims for itself gets exit 1 and correctly refuses to deploy. See PROMPT below.
+set -u
+
+PLATFORM_DIR="${PLATFORM_DIR:-$HOME/officer-dev/platform}"
+# Empty in the sidecar's environment, where anything built from it resolves to /data/... and the record
+# lands where nothing reads it. A watcher whose baseline is invisible to itself has none.
+OFFICER_ROOT="${OFFICER_ROOT:-$HOME/officer-dev}"
+DEPLOYS_DIR="${DEPLOYS_DIR:-$OFFICER_ROOT/data/deploys}"
+POLL_SECONDS="${POLL_SECONDS:-120}"
+export OFFICER_ROOT DEPLOYS_DIR
+
+CLAIM_SH="$PLATFORM_DIR/scripts/deploy-claim.sh"
+
+stamp() { date -Iseconds; }
+
+if [ ! -x "$CLAIM_SH" ]; then
+  echo "$(stamp) deploy-watch: no claim script at $CLAIM_SH — refusing to arm without one" >&2
+  exit 2
+fi
+
+mkdir -p "$DEPLOYS_DIR" || exit 2
+
+echo "$(stamp) deploy-watch: armed. polling $(cd "$PLATFORM_DIR" && git remote get-url origin) every ${POLL_SECONDS}s"
+echo "$(stamp) deploy-watch: baseline is $DEPLOYS_DIR — a version with a claim is never fired again"
+
+while true; do
+  # origin is the LOCAL gitea over the tailnet. The public hostname arrives through a proxy where every
+  # connection shares one source IP and SSH is refused for long stretches — which presents as an
+  # access-rights error and is not one. Eighty minutes of detection latency on 2026-08-21.
+  raw=$(cd "$PLATFORM_DIR" && timeout 30 git ls-remote --tags origin 'refs/tags/deploy/*' 2>&1)
+  rc=$?
+
+  if [ $rc -ne 0 ]; then
+    echo "$(stamp) tick: ls-remote failed (exit $rc) — ${raw%%$'\n'*}"
+    sleep "$POLL_SECONDS"
+    continue
+  fi
+
+  versions=$(printf '%s\n' "$raw" | grep -v '\^{}' | awk '{print $2}' | sed -E 's#.*refs/tags/deploy/##' | sort -u)
+
+  pending=""
+  for v in $versions; do
+    [ -n "$v" ] || continue
+    [ "$("$CLAIM_SH" state "$v" 2>/dev/null)" = unclaimed ] && pending="$pending $v"
+  done
+
+  # Every tick leaves a line, including the quiet ones: a fresh timestamp is the only thing that tells
+  # "nothing to deploy" apart from "the loop died".
+  echo "$(stamp) tick: $(printf '%s\n' "$versions" | grep -c .) tags,${pending:- none} pending"
+
+  for v in $pending; do
+    if ! "$CLAIM_SH" claim "$v"; then
+      # Lost a race with another watcher, or it was claimed between the state check and here. Either way
+      # it is not ours and never becomes ours.
+      continue
+    fi
+
+    echo "$(stamp) deploy/$v claimed — spawning deploy agent"
+
+    # The child reads the procedure, which tells ITS reader to claim first. It must not: we hold the claim
+    # on its behalf, and its own claim would return exit 1 and stop the deploy it was spawned to do.
+    PROMPT="Read prompts/deploy-commander.md in $PLATFORM_DIR and follow it exactly, for the release deploy/$v.
+
+The claim for $v is ALREADY HELD on your behalf by the watcher that spawned you. Do NOT run
+'scripts/deploy-claim.sh claim $v' — it will refuse, correctly, because the claim is taken, and stopping
+there would abandon a deploy you were started to perform. Everything else in that file applies unchanged,
+including running 'scripts/deploy-claim.sh done $v' once the rollout has succeeded.
+
+Roll it out across every host the plan names, skip the host you are running on, and write the report
+exactly as the procedure specifies."
+
+    raw_log="$DEPLOYS_DIR/$v.child.jsonl"
+
+    # Nothing links a spawned agent to its parent and a child transcript does not last, so the stream is
+    # kept here as it arrives. stderr never enters the pipe: the CLI writes warnings there and one landing
+    # in the stream corrupts the first jq parse.
+    {
+      cd "$PLATFORM_DIR" && claude -p "$PROMPT" \
+        --dangerously-skip-permissions \
+        --output-format=stream-json \
+        --verbose
+    } 2> >(while IFS= read -r l; do echo "  ! $l"; done) \
+      | tee -a "$raw_log" \
+      | jq -r --unbuffered '
+          if .type=="system" and .subtype=="init" then
+            "  · child session " + .session_id
+          elif .type=="assistant" then
+            (.message.content[]? |
+              if .type=="tool_use" then
+                "  ⚙ " + .name + ": " + ((.input.description // .input.command // .input.pattern // (.input | tostring)))
+              elif .type=="text" then
+                "  » " + .text
+              else empty end)
+          elif .type=="user" then
+            (.message.content[]? | select(.type=="tool_result") |
+              "    " + (if (.content|type)=="string" then .content else (.content // [] | map(.text? // "") | join(" ")) end))
+          elif .type=="result" then
+            "  = deploy agent " + .subtype + ", " + (.num_turns|tostring) + " turns, " + (.total_cost_usd|tostring) + " usd"
+          else empty end
+        ' 2>/dev/null
+
+    if [ -f "$DEPLOYS_DIR/$v.done" ]; then
+      echo "$(stamp) deploy/$v SUCCEEDED — recorded, transcript at $raw_log"
+    else
+      # The claim stays held. This is the loop's most important line and the one that used to say
+      # "will retry next poll".
+      echo "$(stamp) deploy/$v FAILED — no .done written. NOT retrying; the claim is held."
+      echo "$(stamp)   transcript: $raw_log"
+      echo "$(stamp)   to allow another attempt, deliberately: rm -rf $DEPLOYS_DIR/$v.claim"
+    fi
+  done
+
+  sleep "$POLL_SECONDS"
+done

scripts/docs-check-settings.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { Glob } from 'bun';
+
+/*
+  Which settings sections actually exist, read from the screens that declare them.
+
+  Separated from `docs-check.ts` because it is the only check that parses source rather than importing it —
+  the sections are JSX-adjacent object literals inside components, so importing them would drag React and a
+  browser environment into a CLI. A regex over `BASE_PATH` and `key:` is the honest tool for that, and it is
+  narrow enough to be obvious when it breaks.
+*/
+
+const ROOT = resolve(import.meta.dir, '..');
+const SETTINGS_DIR = join(ROOT, 'src/apps/officer-web/Screens/Dashboard/Settings');
+
+/** `/settings/profile` + `change-password` → `/settings/profile/change-password`. */
+export async function declaredSettingsPaths(): Promise<Set<string>> {
+  const paths = new Set<string>();
+  const glob = new Glob('**/*.tsx');
+  for await (const file of glob.scan({ cwd: SETTINGS_DIR, absolute: true })) {
+    const body = readFileSync(file, 'utf-8');
+    const base = /BASE_PATH\s*=\s*'([^']+)'/.exec(body)?.[1];
+    if (!base) continue;
+    paths.add(base);
+    for (const m of body.matchAll(/key:\s*'([^']+)'/g)) paths.add(`${base}/${m[1]}`);
+  }
+  return paths;
+}
+
+/**
+ * Settings routes Spotlight offers, and which of them nothing declares.
+ *
+ * Parsed rather than imported for the same reason: `useSpotlightItems` is a hook and pulls in the dock,
+ * lucide and React.
+ */
+export async function SPOTLIGHT_SETTINGS_PATHS(): Promise<{ offered: string[]; missing: string[] }> {
+  const file = join(ROOT, 'src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/useSpotlightItems.ts');
+  const body = readFileSync(file, 'utf-8');
+  const offered = [...body.matchAll(/to:\s*'(\/settings\/[^']+)'/g)].map((m) => m[1]!);
+  const declared = await declaredSettingsPaths();
+  return { offered, missing: offered.filter((p) => !declared.has(p)) };
+}

scripts/docs-check.ts

@@ -0,0 +1,169 @@
+/*
+  Does the documentation still match the code?
+
+  ── Why a script and not a habit ──
+
+  "Update the docs before a deploy" is a step that gets skipped at two in the morning, and its absence is
+  invisible. Every piece of drift found on 2026-08-22 was MECHANICAL — a count, a route name, a process
+  list — so it is checkable, and a check that exits non-zero cannot be quietly not done.
+
+  What it will not do is read prose and judge it. It looks only at claims with a machine-checkable
+  counterpart, which is a small fraction of the documentation and the fraction that rots fastest, because a
+  number is exactly the thing nobody re-derives while editing a sentence around it.
+
+  Real examples this was written from, both live at the time:
+
+    platform/CLAUDE.md   "27 entries as of 2026-08-13"   → the registry held 18
+    officer-dev/CLAUDE.md "Officer is twenty PM2 entries" → there were 13
+    Spotlight's settings list  9 rows against 21 sections, and one route that does not exist
+
+  ── The rule for adding a check ──
+
+  A check must compare a documented claim against a value DERIVED AT RUN TIME, never against a second
+  hard-coded copy. A check with the answer written into it is one more place to drift, and it will drift in
+  the same edit that misses the doc.
+*/
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+type Finding = { file: string; claim: string; documented: string; actual: string };
+type CheckResult = { findings: Finding[]; skipped?: string };
+
+const ROOT = resolve(import.meta.dir, '..');
+const WORKSPACE = resolve(ROOT, '..');
+
+const read = (path: string): string | null => (existsSync(path) ? readFileSync(path, 'utf-8') : null);
+
+/** Spelled-out numbers appear in prose more often than digits, and both need catching. */
+const WORDS: Record<string, number> = {
+  ten: 10,
+  eleven: 11,
+  twelve: 12,
+  thirteen: 13,
+  fourteen: 14,
+  fifteen: 15,
+  sixteen: 16,
+  seventeen: 17,
+  eighteen: 18,
+  nineteen: 19,
+  twenty: 20,
+  'twenty-one': 21,
+  'twenty-two': 22,
+  'twenty-three': 23,
+  'twenty-four': 24,
+  'twenty-five': 25,
+};
+const asNumber = (raw: string): number | null => {
+  const digits = Number(raw);
+  if (Number.isFinite(digits)) return digits;
+  return WORDS[raw.toLowerCase()] ?? null;
+};
+
+/**
+ * A documented count, found by a pattern with one capture group, compared to the live value.
+ *
+ * Returns a finding per MISMATCH, not per occurrence: a doc stating the right number twice is fine.
+ */
+function checkCount(file: string, pattern: RegExp, actual: number, claim: string): CheckResult {
+  const body = read(file);
+  if (!body) return { findings: [], skipped: `${file} not found` };
+  const findings: Finding[] = [];
+  for (const match of body.matchAll(pattern)) {
+    const stated = asNumber(match[1] ?? '');
+    if (stated === null || stated === actual) continue;
+    findings.push({ file, claim, documented: String(stated), actual: String(actual) });
+  }
+  return { findings };
+}
+
+async function main(): Promise<void> {
+  const all: Finding[] = [];
+  const skipped: string[] = [];
+  const record = (r: CheckResult) => {
+    all.push(...r.findings);
+    if (r.skipped) skipped.push(r.skipped);
+  };
+
+  // 1. How many permissions the registry holds. The number appears in prose and is never recomputed.
+  const { PERMISSIONS } = await import('../src/servers/permissions/registry');
+  record(
+    checkCount(
+      join(ROOT, 'CLAUDE.md'),
+      /([0-9]+|[a-z-]+) entries as of/gi,
+      PERMISSIONS.length,
+      'permission registry entries',
+    ),
+  );
+
+  // 2. How many PM2 entries Officer is. Documented as going stale "every time a sidecar lands", which is an
+  //    admission that it needs a check rather than a caveat.
+  const pm2 = Bun.spawnSync([process.env.SHELL || '/bin/sh', '-ic', 'pm2 jlist'], { stdout: 'pipe', stderr: 'pipe' });
+  if (pm2.exitCode === 0) {
+    try {
+      const list = JSON.parse(pm2.stdout.toString()) as Array<{ name: string }>;
+      const officer = list.filter((p) => p.name === 'officer' || p.name.startsWith('officer-')).length;
+      record(
+        checkCount(
+          join(WORKSPACE, 'CLAUDE.md'),
+          /Officer is ([a-z-]+|[0-9]+) PM2 entries/gi,
+          officer,
+          'officer PM2 entries',
+        ),
+      );
+    } catch {
+      skipped.push('pm2 jlist did not parse');
+    }
+  } else {
+    // Honest rather than silent: a machine with no pm2 cannot check this, and saying so is the point.
+    skipped.push('pm2 unavailable — PM2 entry count unchecked');
+  }
+
+  // 3. Every settings path Spotlight offers must exist as a declared section. This is the drift that shipped
+  //    a dead link to /settings/users, and it is the class the other two cannot catch: a name, not a count.
+  const { SPOTLIGHT_SETTINGS_PATHS } = await import('./docs-check-settings');
+  const declared = await SPOTLIGHT_SETTINGS_PATHS();
+  for (const bad of declared.missing) {
+    all.push({
+      file: 'Spotlight/useSpotlightItems.ts',
+      claim: 'settings route offered by Spotlight',
+      documented: bad,
+      actual: 'no screen declares that section',
+    });
+  }
+
+  // 4. The generated platform skill must match its generator. A stale SKILL.md is worse than a stale doc:
+  //    an agent quotes it to a user with no way to tell it is out of date.
+  const { renderPlatformSkill, SKILL_PATH } = await import('./gen-platform-skill');
+  const expected = await renderPlatformSkill();
+  const onDisk = read(SKILL_PATH);
+  if (onDisk === null) {
+    all.push({
+      file: 'capabilities/skills/platform/SKILL.md',
+      claim: 'generated platform skill',
+      documented: 'missing',
+      actual: 'run `bun run skills:platform`',
+    });
+  } else if (onDisk !== expected) {
+    all.push({
+      file: 'capabilities/skills/platform/SKILL.md',
+      claim: 'generated platform skill is stale',
+      documented: `${onDisk.split('\n').length} lines on disk`,
+      actual: `${expected.split('\n').length} lines from the generator — run \`bun run skills:platform\``,
+    });
+  }
+
+  for (const note of skipped) console.log(`  skipped: ${note}`);
+  if (all.length === 0) {
+    console.log('docs:check — every checkable claim matches the code');
+    return;
+  }
+  console.log(`\ndocs:check — ${all.length} claim(s) no longer match the code:\n`);
+  for (const f of all) {
+    console.log(`  ${f.file}`);
+    console.log(`    ${f.claim}: says ${f.documented}, actually ${f.actual}\n`);
+  }
+  process.exit(1);
+}
+
+await main();

scripts/doctor.ts

@@ -34,6 +34,44 @@ const fail = (what: string, fix: string) => {
 };
 const pass = (what: string) => console.log(`${green('✓')} ${what}`);
 
+console.log('\n── Runtime ──\n');
+
+/**
+ * bun is deliberately held at a series — `BUN_SERIES` in
+ * scripts/setup/machine-setup/lib/dev.sh — while 1.4 is watched for a while.
+ *
+ * The setup script can pin the INSTALL and nothing more. `bun upgrade` takes no version
+ * argument (it offers latest-stable or --canary and nothing else), so it always jumps to the
+ * newest release and walks a pinned machine off the pin without saying so. This is the only
+ * thing that notices, which is why a version check sits in a script otherwise about accounts.
+ *
+ * The wanted series is READ from `engines.bun` rather than repeated here, because a second
+ * hardcoded copy is a second thing to drift. bun does not enforce that field — verified: an
+ * install declaring `engines.bun: "1.9.x"` ran clean under 1.3.14, no warning — so the field is
+ * the declaration and this is the enforcement.
+ */
+const pkg = (await Bun.file(new URL('../package.json', import.meta.url)).json()) as {
+  engines?: { bun?: string };
+};
+const wantSeries = (pkg.engines?.bun ?? '').replace(/\.x$/, '');
+const nowSeries = Bun.version.split('.').slice(0, 2).join('.');
+
+if (!wantSeries) {
+  fail(
+    'package.json declares no engines.bun',
+    'The setup scripts pin a bun series and nothing else records which one. Add it.',
+  );
+} else if (nowSeries === wantSeries) {
+  pass(`bun ${Bun.version} ${dim(`(inside the pinned ${wantSeries} series)`)}`);
+} else {
+  fail(
+    `bun ${Bun.version} is outside the pinned ${wantSeries} series`,
+    `Usually a 'bun upgrade', which always takes the newest release. Pin it back with ` +
+      `'curl -fsSL https://bun.sh/install | bash -s bun-v<newest ${wantSeries}.x>', or raise ` +
+      `engines.bun and BUN_SERIES together if ${nowSeries} is now wanted.`,
+  );
+}
+
 console.log('\n── Accounts ──\n');
 
 const users = await getUsers();

scripts/gen-platform-skill.ts

@@ -0,0 +1,155 @@
+/*
+  Generates the PLATFORM skill — the reference an agent opens when a user asks what the platform can do.
+
+  ── Why generated ──
+
+  Because a hand-written one rots, and we measured it. Spotlight's settings list was hand-written and drifted
+  within two days: nine rows against twenty-one sections, and a route that does not exist. `CLAUDE.md` claimed
+  27 permission entries against 18, and twenty PM2 processes against thirteen, both for over a week.
+
+  A skill is worse than a doc when it is wrong, because an agent quotes it with confidence and the user has no
+  way to tell. So the parts a registry can answer are derived here, at generation time, from the registry —
+  and the prose is limited to what no registry can express.
+
+  ── The split, and where the line is ──
+
+    GENERATED   permissions: key, label, kind, api prefixes, sockets, frontend routes
+                keyboard shortcuts
+    PROSE       what the platform IS, what a permission KIND means for a user, where to look next
+
+  Run `bun run skills:platform`. `bun run docs:check` regenerates into memory and fails if the committed file
+  differs, so a stale skill is a failed check rather than a confident wrong answer.
+*/
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const ROOT = resolve(import.meta.dir, '..');
+export const SKILL_PATH = join(ROOT, '..', 'capabilities', 'skills', 'platform', 'SKILL.md');
+
+const KIND_MEANING: Record<string, string> = {
+  core: 'every account has it and it cannot be denied — the caller acting on themselves',
+  app: 'grantable per role, at read or write',
+  confined: 'grantable, but only to an account that has its own Linux user; without one the grant resolves to nothing',
+  execution: 'runs as the server owner in the owner’s home. NEVER grantable, at any level, structurally',
+  admin: 'the server owner only',
+};
+
+export async function renderPlatformSkill(): Promise<string> {
+  const { PERMISSIONS } = await import('../src/servers/permissions/registry');
+  const { SHORTCUT_SECTIONS } = await import('../src/apps/officer-web/state/shortcuts');
+
+  const byKind = new Map<string, typeof PERMISSIONS>();
+  for (const p of PERMISSIONS) {
+    const list = byKind.get(p.kind) ?? [];
+    list.push(p);
+    byKind.set(p.kind, list as typeof PERMISSIONS);
+  }
+
+  const lines: string[] = [];
+  const out = (s = '') => lines.push(s);
+
+  out('---');
+  out('name: Officer platform');
+  // The description is the ENTIRE interface: the agent sees only this before deciding to open the body.
+  // Vague makes a skill useless rather than merely verbose — see skills/load.ts.
+  out('description: >-');
+  out('  Use when the user asks what Officer can do, how to use a feature, what an endpoint is, why something is');
+  out('  refused, or how permissions and accounts work — "how do I start a commander", "can a member see my files",');
+  out('  "what is the API for tasks". Carries the permission registry, every API prefix and socket, the frontend');
+  out('  routes and the keyboard shortcuts, derived from the code rather than written by hand.');
+  out('version: 1');
+  out('---');
+  out();
+  out('<!--');
+  out('  GENERATED by `bun run skills:platform`. Do not edit by hand — `bun run docs:check` fails if this file');
+  out('  differs from what the generator produces, and an edit here is lost on the next run.');
+  out();
+  out('  The prose lives in scripts/gen-platform-skill.ts, beside the generation, so the two cannot separate.');
+  out('-->');
+  out();
+  out('# What Officer is');
+  out();
+  out('One self-hosted app for one person — the **owner** — that also admits additional accounts holding a');
+  out('strict subset of it. The owner is user id 1, role `Super Admin`, and bypasses every permission check.');
+  out('Everyone else gets what their ROLE is granted, and nothing else: grants are keyed on role, never on a');
+  out('user, and **absence denies** — there is no row meaning "no".');
+  out();
+  out('So "can this account do X" has three possible answers, and the third is the one people miss: yes,');
+  out('no, and *not shareable at all*.');
+  out();
+  out('# Permissions');
+  out();
+  out('The authority for this is `src/servers/permissions/registry.ts`. Mounting an API router without an');
+  out('entry there makes the server **refuse to boot** — so this list is complete by construction, not by');
+  out('diligence.');
+  out();
+  for (const [kind, meaning] of Object.entries(KIND_MEANING)) {
+    const entries = byKind.get(kind) ?? [];
+    if (!entries.length) continue;
+    out(`## \`${kind}\` — ${meaning}`);
+    out();
+    for (const p of entries) {
+      const bits: string[] = [];
+      if (p.api?.length) bits.push(`API \`${p.api.join('`, `')}\``);
+      if (p.ws?.length) bits.push(`socket \`${p.ws.join('`, `')}\``);
+      if (p.routes?.length) bits.push(`screen \`${p.routes.join('`, `')}\``);
+      out(`- **${p.label}** (\`${p.key}\`) — ${p.description}`);
+      if (bits.length) out(`  - ${bits.join(' · ')}`);
+      if (p.selfService?.length) {
+        out(`  - acts on the caller themselves, allowed with no grant: \`${p.selfService.join('`, `')}\``);
+      }
+      if (p.ownerOnly?.length) out(`  - owner only, even when granted: \`${p.ownerOnly.join('`, `')}\``);
+      if (p.readOnlyWrites?.length) {
+        out(`  - a POST that is really a read, allowed at read level: \`${p.readOnlyWrites.join('`, `')}\``);
+      }
+    }
+    out();
+  }
+
+  out('# Keyboard shortcuts');
+  out();
+  out('Derived from `src/apps/officer-web/state/shortcuts.ts`. These have moved several times; quote this');
+  out('list rather than remembering one.');
+  out();
+  for (const section of SHORTCUT_SECTIONS) {
+    out(`## ${section.title}`);
+    if (section.note) {
+      out();
+      out(section.note);
+    }
+    out();
+    for (const s of section.shortcuts) out(`- \`${s.keys}\` — ${s.description}`);
+    out();
+  }
+
+  out('# What is NOT in here');
+  out();
+  out('- **Installed plugins.** They vary per machine and per install, so a generated list would be wrong on');
+  out('  every other server. Ask the platform: `GET /api/plugins` for what is installed here.');
+  out('- **Request and response shapes.** This says which prefix a permission covers, not what a route');
+  out('  accepts. Read the router under `src/servers/api/<feature>/` when the shape matters.');
+  out('- **Anything about a commander beyond its permission.** That has its own skill — open it for what a');
+  out('  commander is, how one is started, and how to help somebody shape one.');
+  out();
+  out('# When you are about to guess');
+  out();
+  out('Do not. This file is generated from the registry, so a question it does not answer is a question the');
+  out('registry does not answer either — say so, and read the code. Every documented count in this repository');
+  out('that was maintained by hand has been wrong, and an agent quoting a stale number sounds exactly as');
+  out('certain as one quoting a true one.');
+
+  return `${lines.join('\n')}\n`;
+}
+
+if (import.meta.main) {
+  const body = await renderPlatformSkill();
+  mkdirSync(join(SKILL_PATH, '..'), { recursive: true });
+  const existing = existsSync(SKILL_PATH) ? readFileSync(SKILL_PATH, 'utf-8') : null;
+  if (existing === body) {
+    console.log('skills:platform — already current');
+  } else {
+    writeFileSync(SKILL_PATH, body);
+    console.log(`skills:platform — wrote ${SKILL_PATH} (${body.split('\n').length} lines)`);
+  }
+}

scripts/i18n/scan-hardcoded.ts

@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+/**
+ * Counts candidate hardcoded user-facing strings in the web UI.
+ *
+ * Two jobs. It sizes the localization work (docs/localization.md quotes its output), and once an area
+ * reaches zero it becomes the guard that stops the debt coming back — see ZEROED below.
+ *
+ * It is a heuristic and it is deliberately a FLOOR. It cannot see multi-line JSX text, ternaries
+ * inside JSX, strings passed down as props, or anything a plugin renders. A falling number means
+ * progress; a zero means "nothing this scanner can see", not "nothing left".
+ *
+ *   bun scripts/i18n/scan-hardcoded.ts            # summary by area
+ *   bun scripts/i18n/scan-hardcoded.ts --files    # worst files first
+ *   bun scripts/i18n/scan-hardcoded.ts --list ui.button   # print the strings themselves
+ *   bun scripts/i18n/scan-hardcoded.ts --check    # non-zero exit if a zeroed area regressed
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const AREAS = [
+  { label: 'officer-web (shell)', root: 'src/apps/officer-web' },
+  { label: 'officerdev (panels)', root: 'src/workspaces/officerdev/src' },
+  { label: 'shared components', root: 'src/workspaces/components' },
+] as const;
+
+/**
+ * Areas that have been converted and must stay converted. Add an area here the moment it reaches
+ * zero — enabling every area on day one would just be red for weeks and get ignored.
+ */
+const ZEROED: string[] = [];
+
+const SKIP = /node_modules|\.gen\.|[/\\]locales[/\\]|[/\\]vendor[/\\]|\.test\.|\.d\.ts$/;
+
+// A quoted literal, single or double. Kept as two groups because JS has no branch reset.
+const Q = String.raw`(?:"([^"\n]{2,120})"|'([^'\n]{2,120})')`;
+
+const PATTERNS: { kind: string; rx: RegExp }[] = [
+  // >Some visible words<
+  { kind: 'jsx text', rx: />\s*([A-Z][A-Za-z0-9][^<>{}\n]{2,100}?)\s*</g },
+  // placeholder="..." and friends
+  {
+    kind: 'attributes',
+    rx: new RegExp(String.raw`\b(?:placeholder|title|aria-label|alt|label|description|tooltip|emptyMessage)\s*=\s*` + Q, 'g'),
+  },
+  { kind: 'toast/alert', rx: new RegExp(String.raw`\b(?:toast(?:\.\w+)?|alert|confirm)\s*\(\s*` + Q, 'g') },
+  // label: 'Status' — nav items, menus, table columns. The largest hidden category.
+  {
+    kind: 'object labels',
+    rx: new RegExp(String.raw`\b(?:label|name|title|heading|placeholder|description|tooltip|emptyText)\s*:\s*` + Q, 'g'),
+  },
+  { kind: 'thrown errors', rx: new RegExp(String.raw`new Error\(\s*` + Q, 'g') },
+  // `Failed to create ${kind}` — needs interpolation, so it costs more to convert.
+  { kind: 'template str', rx: /`([A-Z][^`\n]{4,100}\$\{[^`]*)`/g },
+];
+
+/** Filters out ids, class names, paths, mime types and SCREAMING_CONSTANTS. */
+function isHuman(value: string | undefined): value is string {
+  if (!value) return false;
+  const s = value.trim();
+  if (s.length < 3) return false;
+  if (!/[A-Za-z]{3}/.test(s)) return false;
+  if (/^[a-z0-9\-_./:]+$/.test(s)) return false;
+  if (/^(https?:|\/|#|data:|application\/|image\/)/.test(s)) return false;
+  if (/^[A-Z0-9_]+$/.test(s)) return false;
+  return true;
+}
+
+function* walk(dir: string): Generator<string> {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    if (SKIP.test(path)) continue;
+    let isDir = false;
+    try {
+      isDir = statSync(path).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) yield* walk(path);
+    else if (path.endsWith('.tsx') || path.endsWith('.ts')) yield path;
+  }
+}
+
+type Hit = { kind: string; value: string; file: string };
+
+function scan(root: string): { files: number; hits: Hit[] } {
+  const hits: Hit[] = [];
+  let files = 0;
+
+  for (const file of walk(root)) {
+    files++;
+    let source: string;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const { kind, rx } of PATTERNS) {
+      rx.lastIndex = 0;
+      for (const match of source.matchAll(rx)) {
+        const value = match.slice(1).find((group) => group !== undefined);
+        if (isHuman(value)) hits.push({ kind, value: value.trim(), file });
+      }
+    }
+  }
+  return { files, hits };
+}
+
+const args = new Set(process.argv.slice(2));
+const listPrefix = process.argv.includes('--list') ? process.argv[process.argv.indexOf('--list') + 1] : undefined;
+
+const results = AREAS.map((area) => ({ ...area, ...scan(area.root) }));
+const kinds = PATTERNS.map((p) => p.kind);
+const pad = (s: string | number, n: number) => String(s).padStart(n);
+
+console.log(`${'area'.padEnd(22)} ${pad('files', 5)} ${kinds.map((k) => pad(k.slice(0, 13), 14)).join('')} ${pad('total', 7)}`);
+for (const r of results) {
+  const byKind = kinds.map((k) => pad(r.hits.filter((h) => h.kind === k).length, 14)).join('');
+  console.log(`${r.label.padEnd(22)} ${pad(r.files, 5)} ${byKind} ${pad(r.hits.length, 7)}`);
+}
+
+const all = results.flatMap((r) => r.hits);
+const distinct = new Set(all.map((h) => h.value));
+const interpolated = new Set(all.filter((h) => h.kind === 'template str').map((h) => h.value));
+
+console.log(`${'TOTAL'.padEnd(22)} ${pad(results.reduce((n, r) => n + r.files, 0), 5)} ${kinds.map((k) => pad(all.filter((h) => h.kind === k).length, 14)).join('')} ${pad(all.length, 7)}`);
+console.log();
+console.log(`occurrences        ${all.length}`);
+console.log(`distinct strings   ${distinct.size}`);
+console.log(`  needing params   ${interpolated.size}`);
+
+if (args.has('--files')) {
+  console.log('\nworst files:');
+  const perFile = new Map<string, number>();
+  for (const h of all) perFile.set(h.file, (perFile.get(h.file) ?? 0) + 1);
+  for (const [file, n] of [...perFile].sort((a, b) => b[1] - a[1]).slice(0, 25)) {
+    console.log(`  ${pad(n, 4)}  ${file}`);
+  }
+}
+
+if (listPrefix) {
+  console.log(`\nstrings in files matching "${listPrefix}":`);
+  for (const h of all.filter((x) => x.file.includes(listPrefix))) console.log(`  [${h.kind}] ${h.value}`);
+}
+
+if (args.has('--check')) {
+  const regressed = results.filter((r) => ZEROED.includes(r.label) && r.hits.length > 0);
+  if (regressed.length > 0) {
+    console.error('\nThese areas were converted and have regressed:');
+    for (const r of regressed) console.error(`  ${r.label}: ${r.hits.length} hardcoded strings`);
+    console.error('\nUse a catalog key. See docs/localization.md.');
+    process.exit(1);
+  }
+  console.log(`\ncheck: ok (${ZEROED.length} area(s) held at zero)`);
+}

scripts/port-community-themes.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { mapPalette } from './themes/map';
+import type { Palette } from './themes/palette';
+import { paletteFromRecord, parseTomlText } from './themes/palette';
+import { deriveOmarchyPalette } from './themes/from-ansi';
+import { parseAlacrittyToml, parseColor16Toml, parseGhosttyConf } from './themes/ansi-source';
+import { contrast, ensureContrast, TEXT, UI } from './themes/contrast';
+
+// Port community Omarchy themes from omarchythemes.com into the same 84-token shape the official
+// pipeline produces — see `generate-themes.ts` for that one. This is its sibling for themes that have no
+// `colors.toml`: a single-theme repo instead ships per-app configs, so `from-ansi.ts` reconstructs the
+// same `Palette` from `alacritty.toml` or `ghostty.conf`, and everything downstream (mapping, contrast
+// checking) is identical. What's NOT identical: these are unofficial, one author's repo can vanish or
+// change, and the reconstruction is a heuristic, not Omarchy's own curated palette — every generated file
+// says so in its header.
+//
+//   bun scripts/port-community-themes.ts [--limit=N] [--slug=<one-slug>] [--redo]
+//
+// State lives in `scripts/themes/community-manifest.json` — one entry per theme successfully ported, so a
+// re-run only fetches what's missing (or everything, with --redo) and the registry/index blocks are
+// always rewritten fresh from the whole manifest, never hand-edited.
+
+const CSS_THEME_DIR = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'css', 'themes');
+const INDEX_CSS = join(CSS_THEME_DIR, '..', 'index.css');
+const REGISTRY = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'src', 'themes.ts');
+const MANIFEST_PATH = join(import.meta.dir, 'themes', 'community-manifest.json');
+const SITE = 'https://omarchythemes.com';
+const CONCURRENCY = 8;
+
+const REDO = process.argv.includes('--redo');
+const ONLY_SLUG = process.argv.find((a) => a.startsWith('--slug='))?.split('=')[1];
+const LIMIT = Number(process.argv.find((a) => a.startsWith('--limit='))?.split('=')[1] ?? Infinity);
+
+type ManifestEntry = {
+  id: string;
+  name: string;
+  repo: string;
+  /** Omitted means GitHub, which is where all but a couple of these live. */
+  host?: 'gitlab';
+  kind: string;
+  dark: boolean;
+};
+
+type Repo = { host: 'github' | 'gitlab'; path: string };
+
+const repoUrl = (r: Repo): string => `https://${r.host === 'gitlab' ? 'gitlab.com' : 'github.com'}/${r.path}`;
+
+// Same pairs `generate-themes.ts` checks, kept in sync by hand since this is the only other place that
+// needs them and duplicating a 20-line array beats a shared module for one caller each.
+const PAIRS: [string, string, number][] = [
+  ['--foreground', '--background', TEXT],
+  ['--card-foreground', '--card', TEXT],
+  ['--popover-foreground', '--popover', TEXT],
+  ['--muted-foreground', '--muted', TEXT],
+  ['--accent-foreground', '--accent', TEXT],
+  ['--primary-foreground', '--primary', TEXT],
+  ['--secondary-foreground', '--secondary', TEXT],
+  ['--cta-foreground', '--cta', TEXT],
+  ['--success-foreground', '--success', TEXT],
+  ['--warning-foreground', '--warning', TEXT],
+  ['--destructive-foreground', '--destructive', TEXT],
+  ['--info-foreground', '--info', TEXT],
+  ['--busy-foreground', '--busy', TEXT],
+  ['--busy-ink', '--background', TEXT],
+  ['--input', '--background', 1.35],
+  ['--ring', '--background', UI],
+];
+
+const title = (id: string): string =>
+  id
+    .split('-')
+    .map((w) => (w.length <= 2 ? w.toUpperCase() : w[0]!.toUpperCase() + w.slice(1)))
+    .join(' ');
+
+function loadManifest(): ManifestEntry[] {
+  if (!existsSync(MANIFEST_PATH)) return [];
+  return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
+}
+
+function saveManifest(entries: ManifestEntry[]): void {
+  writeFileSync(MANIFEST_PATH, `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+function ghApiDefaultBranch(repo: string): string {
+  try {
+    const out = execSync(`gh api repos/${repo} --jq .default_branch`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() || 'main';
+  } catch {
+    return 'main';
+  }
+}
+
+async function gitlabDefaultBranch(path: string): Promise<string> {
+  const json = await fetchText(`https://gitlab.com/api/v4/projects/${encodeURIComponent(path)}`);
+  if (!json) return 'main';
+  try {
+    return (JSON.parse(json).default_branch as string) || 'main';
+  } catch {
+    return 'main';
+  }
+}
+
+async function fetchText(url: string): Promise<string | undefined> {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return undefined;
+    return await res.text();
+  } catch {
+    return undefined;
+  }
+}
+
+async function discoverRepo(slug: string): Promise<Repo | undefined> {
+  const html = await fetchText(`${SITE}/themes/${slug}`);
+  if (!html) return undefined;
+  const gh = html.match(/https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)/);
+  if (gh) return { host: 'github', path: `${gh[1]}/${gh[2]}` };
+  // A couple of authors host on GitLab instead. Its group paths can nest, hence the greedier match.
+  const gl = html.match(/https:\/\/gitlab\.com\/([\w.-]+(?:\/[\w.-]+)+?)(?=["'\s<]|$)/);
+  if (gl) return { host: 'gitlab', path: gl[1]!.replace(/\.git$/, '') };
+  return undefined;
+}
+
+async function sourceFor(
+  repo: Repo,
+  slug: string,
+): Promise<{ palette: Palette; kind: string; derived: boolean } | undefined> {
+  const branch = repo.host === 'gitlab' ? await gitlabDefaultBranch(repo.path) : ghApiDefaultBranch(repo.path);
+  const raw = (p: string) =>
+    repo.host === 'gitlab'
+      ? `https://gitlab.com/${repo.path}/-/raw/${branch}/${p}`
+      : `https://raw.githubusercontent.com/${repo.path}/${branch}/${p}`;
+
+  // Most repos hold one theme at the root. A few are packs that nest one directory per theme, so also
+  // look under the directory named after THIS slug — an exact match is the only safe pick, since a pack
+  // with variant names of its own (`abyss-dark`, `lagoon-light`, …) has no one theme that is "the" one.
+  const prefixes = ['', `themes/${slug}/`, `omarchy/themes/${slug}/`, `${slug}/`];
+
+  for (const prefix of prefixes) {
+    // `colors.toml` is ambiguous across community repos: it might genuinely be Omarchy 4's own semantic
+    // schema (in which case no derivation is needed at all — same quality as the official 22), or it might
+    // reuse the filename for an unrelated flat `color0..color15` ANSI scheme. Try the real schema first;
+    // only fall through to the ANSI reading if the required keys aren't there.
+    const tomlText = await fetchText(raw(`${prefix}colors.toml`));
+    if (tomlText) {
+      const kv = parseTomlText(tomlText);
+      try {
+        return {
+          palette: paletteFromRecord(kv, `${repo.path}/${prefix}colors.toml`),
+          kind: 'colors.toml (Omarchy schema)',
+          derived: false,
+        };
+      } catch {
+        const ansi = parseColor16Toml(kv);
+        if (ansi) return { palette: deriveOmarchyPalette(ansi), kind: 'colors.toml (16-colour ANSI)', derived: true };
+      }
+    }
+
+    for (const path of [
+      'alacritty.toml',
+      '.config/alacritty.toml',
+      'alacritty/alacritty.toml',
+      'config/alacritty.toml',
+    ]) {
+      const text = await fetchText(raw(`${prefix}${path}`));
+      if (!text) continue;
+      const ansi = parseAlacrittyToml(text);
+      if (ansi) return { palette: deriveOmarchyPalette(ansi), kind: 'alacritty.toml', derived: true };
+    }
+    for (const path of ['ghostty.conf', 'ghostty-theme', '.config/ghostty/config']) {
+      const text = await fetchText(raw(`${prefix}${path}`));
+      if (!text) continue;
+      const ansi = parseGhosttyConf(text);
+      if (ansi) return { palette: deriveOmarchyPalette(ansi), kind: 'ghostty.conf', derived: true };
+    }
+  }
+  return undefined;
+}
+
+async function portOne(slug: string): Promise<{ entry: ManifestEntry; css: string } | { skip: string }> {
+  const repo = await discoverRepo(slug);
+  if (!repo) return { skip: 'no github/gitlab repo link found on its omarchythemes.com page' };
+
+  const source = await sourceFor(repo, slug);
+  if (!source) return { skip: `no parseable colors.toml/alacritty.toml/ghostty.conf in ${repo.path}` };
+
+  const palette = source.palette;
+  const tokens = mapPalette(palette);
+
+  // `--input` carries a real accessibility requirement (a field boundary you can't see) where `--border`
+  // is decoration and isn't held to one — see the README. `map.ts` derives both from the same mix for
+  // every theme, official ones included, and it normally clears 1.35:1 on its own; a few derived palettes
+  // land just under it, so nudge only this one rather than loosening the check.
+  tokens['--input'] = ensureContrast(tokens['--input']!, tokens['--background']!, 1.35);
+
+  const failures: string[] = [];
+  for (const [fgKey, bgKey, min] of PAIRS) {
+    const fg = tokens[fgKey]!;
+    const bg = tokens[bgKey]!;
+    if (!fg.startsWith('#') || !bg.startsWith('#')) continue;
+    const ratio = contrast(fg, bg);
+    if (ratio < min) failures.push(`${fgKey} on ${bgKey} is ${ratio.toFixed(2)}:1, needs ${min}:1`);
+  }
+  if (failures.length > 0) return { skip: `contrast failed after derivation: ${failures.join('; ')}` };
+
+  const name = title(slug);
+  const body = Object.entries(tokens)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n');
+  const modeLine = source.kind.startsWith('colors.toml (Omarchy')
+    ? `${palette.mode === 'dark' ? 'Dark theme' : 'Light theme'} (${palette.mode}) — the source repo's own colors.toml says so directly.`
+    : `${palette.mode === 'dark' ? 'Dark theme' : 'Light theme'} (${palette.mode}), by luminance of its own background — the source repo carries no mode flag of its own to read.`;
+  const provenanceLine = source.derived
+    ? `went through deriveOmarchyPalette (scripts/themes/from-ansi.ts) because the source has no Omarchy 4\n  colors.toml — some tokens here are reconstructed, not authored.`
+    : `came straight from the repo's own colors.toml — the same schema and reader the official 22 themes\n  use, so nothing here is reconstructed.`;
+  const css = `/*
+  ${name} — ported from a community Omarchy theme, not from basecamp/omarchy's own set.
+
+  ${modeLine}
+
+  Source: ${repoUrl(repo)} (${source.kind}), read by scripts/port-community-themes.ts. Values
+  ${provenanceLine} Every text/surface pair is contrast-checked the same way the official themes are.
+
+  DO NOT EDIT BY HAND. Re-run the script to refresh from the source repo.
+*/
+[data-theme='${slug}'] {
+${body}
+}
+`;
+
+  return {
+    entry: {
+      id: slug,
+      name,
+      repo: repo.path,
+      ...(repo.host === 'gitlab' ? { host: 'gitlab' as const } : {}),
+      kind: source.kind,
+      dark: palette.mode === 'dark',
+    },
+    css,
+  };
+}
+
+function rewriteIndexCss(entries: ManifestEntry[]): void {
+  const index = readFileSync(INDEX_CSS, 'utf8');
+  const marker = '/* Community themes';
+  const startIdx = index.indexOf(marker);
+  const head = startIdx >= 0 ? index.slice(0, startIdx) : index.replace(/\n@import '\.\/chrome\.css';\n$/, '\n');
+  const imports = entries.map((e) => `@import './themes/${e.id}.css';`).join('\n');
+  writeFileSync(
+    INDEX_CSS,
+    `${head}/* Community themes — ported from omarchythemes.com by scripts/port-community-themes.ts. Do not edit this block. */\n${imports}\n\n@import './chrome.css';\n`,
+  );
+}
+
+function rewriteRegistry(entries: ManifestEntry[]): void {
+  const registry = readFileSync(REGISTRY, 'utf8');
+  const START = '  /* COMMUNITY THEMES — start */';
+  const END = '  /* COMMUNITY THEMES — end */';
+  const rows = entries
+    .map((e) => `  { id: '${e.id}', name: '${e.name}', family: '${e.name}', applyDarkClass: ${e.dark} },`)
+    .join('\n');
+  const block = `${START}\n${rows}\n${END}`;
+
+  if (registry.includes(START) && registry.includes(END)) {
+    // Snap to the start of the marker's own line — `indexOf` on a string with leading spaces can match
+    // partway into stray indentation left by an earlier write, which would otherwise accumulate.
+    const startLineBegin = registry.lastIndexOf('\n', registry.indexOf(START)) + 1;
+    const before = registry.slice(0, startLineBegin);
+    const after = registry.slice(registry.indexOf(END) + END.length);
+    writeFileSync(REGISTRY, `${before}${block}${after}`);
+  } else {
+    const anchor = '] as const;';
+    const idx = registry.indexOf(anchor);
+    writeFileSync(REGISTRY, `${registry.slice(0, idx)}${block}\n${registry.slice(idx)}`);
+  }
+}
+
+async function main() {
+  const slugsFile = process.argv.find((a) => a.startsWith('--slugs='))?.split('=')[1];
+  const allSlugs: string[] = slugsFile ? readFileSync(slugsFile, 'utf8').trim().split('\n').filter(Boolean) : [];
+
+  const manifest = loadManifest();
+  const known = new Set(manifest.map((e) => e.id));
+  // Never take a slug the OFFICIAL/hand-authored part of the registry already owns — that's everything
+  // before this script's own block, which it is free to redo.
+  const registryHead = readFileSync(REGISTRY, 'utf8').split('/* COMMUNITY THEMES — start */')[0]!;
+  const registryIds = new Set(Array.from(registryHead.matchAll(/id: '([\w-]+)'/g)).map((m) => m[1]!));
+
+  let todo = ONLY_SLUG ? [ONLY_SLUG] : allSlugs.filter((s) => !registryIds.has(s) && (REDO || !known.has(s)));
+  todo = todo.slice(0, LIMIT);
+
+  console.log(`community theme port: ${todo.length} to try, ${manifest.length} already in the manifest`);
+
+  const results: ManifestEntry[] = [...manifest.filter((e) => !todo.includes(e.id))];
+  let done = 0;
+  let ok = 0;
+  let skipped = 0;
+
+  async function worker() {
+    while (todo.length > 0) {
+      const slug = todo.shift();
+      if (!slug) break;
+      try {
+        const result = await portOne(slug);
+        done++;
+        if ('skip' in result) {
+          skipped++;
+          console.log(`[${done}] SKIP  ${slug} — ${result.skip}`);
+        } else {
+          writeFileSync(join(CSS_THEME_DIR, `${slug}.css`), result.css);
+          results.push(result.entry);
+          ok++;
+          console.log(`[${done}] OK    ${slug} — from ${result.entry.repo} (${result.entry.kind})`);
+        }
+      } catch (err) {
+        done++;
+        skipped++;
+        console.log(`[${done}] ERROR ${slug} — ${(err as Error).message}`);
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+
+  results.sort((a, b) => a.id.localeCompare(b.id));
+  saveManifest(results);
+  rewriteIndexCss(results);
+  rewriteRegistry(results);
+
+  console.log(`\ndone: ${ok} ported, ${skipped} skipped, ${results.length} total in manifest`);
+}
+
+main();

scripts/seed-roles.ts

@@ -0,0 +1,53 @@
+/**
+ * Seed the `roles` table with the roles the platform's own code names.
+ *
+ * Runs from `postdb:push`, so every machine gets the rows on its next schema push rather than needing a
+ * per-server step in a deploy plan. Bun fires `pre`/`post` hooks for colon-named scripts — the same
+ * mechanism `backfill-session-models.ts` relies on.
+ *
+ * ── Why these four are `isSystem` ──
+ *
+ * Each is named by name somewhere in the code: `rolePermitsDevTools()` tests for `'Developer'`,
+ * `bootstrap.ts` writes `'Super Admin'`, `users.role` defaults to `'Member'`, and `'Admin'` is the one
+ * `rolePermitsDevTools` deliberately excludes. Renaming or deleting one of those is not a data change, it
+ * is a code change that has not happened — so the flag exists for the delete and rename paths to refuse on,
+ * rather than for the failure to turn up later as a missing database role or an account that cannot log in.
+ *
+ * ── What this deliberately does NOT do ──
+ *
+ * No foreign key from `users.role`. That change cannot go through `db:push`: push creates the table empty
+ * and adds the constraint in the same run, so every existing account violates it — verified against a
+ * scratch database on 2026-08-23, where push reported the violation, created the table, skipped the
+ * constraint, and exited 0. The FK is a separate release, once every host holds these rows.
+ *
+ * So today `users.role` is still a plain text column and nothing enforces that its value is a real role.
+ * That is the intended state of this phase: additive, unable to fail, and safe to run on five hosts
+ * unattended.
+ *
+ * Never overwrites. A description edited on one server must not be reverted by the next deploy.
+ */
+import { seedRole, waitForDatabase } from '../src/databases/officer_db/src/index';
+
+const SEED: { name: string; description: string }[] = [
+  { name: 'Super Admin', description: 'Full authority over the platform, and an OS account with sudo' },
+  { name: 'Admin', description: 'Administers the platform. No operating-system privilege' },
+  { name: 'Developer', description: 'A member who is also trusted with developer tooling on the machine' },
+  { name: 'Member', description: 'The default. Reaches only what their role has been granted' },
+];
+
+async function main(): Promise<void> {
+  await waitForDatabase();
+  let created = 0;
+  for (const role of SEED) {
+    if (await seedRole({ ...role, isSystem: true })) created += 1;
+  }
+  console.log(`[seed:roles] ${created} seeded, ${SEED.length - created} already present (of ${SEED.length})`);
+}
+
+// Never fatal. This runs from a `post` hook after a schema push, and a seed that cannot write must not make
+// a successful push look like a failed one — the rows are additive and the next push tries again.
+main()
+  .catch((err: unknown) => {
+    console.error('[seed:roles] could not seed:', err instanceof Error ? err.message : err);
+  })
+  .finally(() => process.exit(0));

scripts/setup/machine-setup/lib/dev.sh

@@ -206,7 +206,7 @@ nvim_clone_config() {
 #          every process here. officer-pty imports node-pty, a native addon with
 #          no Linux prebuild — it compiles against the installed Node on every
 #          machine. Either one alone makes Node load-bearing.
-#   bun    the platform itself and nineteen of the twenty pm2 apps.
+#   bun    the platform itself, and every pm2 app except officer-pty.
 #   pm2    the process manager the ecosystem files are written for.
 #
 # Deno is not. Nothing in the platform imports it — checked across the whole
@@ -243,6 +243,69 @@ install_node() {
   npm config set prefix /usr/local >/dev/null 2>&1 || true
 }
 
+# ── Held at the 1.3 series, deliberately and temporarily ──
+#
+# bun 1.4.0 landed on 2026-08-20 and https://bun.sh/install takes whatever is
+# newest, so a machine provisioned two days later puts a brand-new release under
+# the platform and every pm2 app it runs. Held at 1.3 until 1.4 has been watched
+# for a while. That is the owner's call and it is meant to be revisited in a few
+# months, not a permanent ceiling — raise BUN_SERIES when 1.4 has earned it.
+#
+# The SERIES is pinned, not a patch. 1.3.x fixes still land and should still be
+# taken; a hardcoded 1.3.14 would rot into "the version we happened to pick"
+# exactly the way setup_22.x did for Node.
+#
+# This covers the INSTALL path only, and cannot cover the other one: `bun upgrade`
+# takes no version argument — checked against `bun upgrade --help` on 1.3.14, which
+# offers latest-stable or --canary and nothing else — so it always jumps to the
+# newest release and will walk a pinned machine onto 1.4 on its own. Nothing in a
+# setup script can prevent that. `bun run doctor` is where that drift is caught.
+BUN_SERIES="${BUN_SERIES:-1.3}"
+
+# The newest stable release inside the series.
+#
+# Asked of the npm registry rather than GitHub's releases API, which is the obvious
+# source and the wrong one: it rate-limits unauthenticated callers to 60 an hour per
+# IP, and it returned 504 twice while this was being written. An empty answer here
+# means no bun gets installed at all (see install_bun), so where it comes from is
+# load-bearing rather than a matter of taste. bun publishes every release to npm.
+#
+# `sort -V` rather than trusting the order the registry returns them in, and the
+# pattern is anchored so 1.3.1 cannot be mistaken for the newest when 1.3.14 exists.
+bun_series_latest() {
+  curl -fsSL https://registry.npmjs.org/bun 2>/dev/null |
+    jq -r '.versions | keys[]' 2>/dev/null |
+    grep -E "^${BUN_SERIES//./\\.}\.[0-9]+$" |
+    sort -V | tail -1
+}
+
+# The major.minor of a full version — "1.3.14" is in series "1.3".
+bun_series_of() { sed -E 's/^([0-9]+\.[0-9]+).*/\1/' <<<"${1:-}"; }
+
+# Where an installed bun sits relative to the pin: in, above, below, or unknown.
+#
+# Above and below are different problems and get different answers — above is a
+# machine that has upgraded itself past the pin, below is one that is simply old —
+# so this reports which rather than a yes/no. `sort -V` does the comparing, so
+# nothing here has to parse a version.
+bun_series_position() {
+  local now
+  now="$(bun_series_of "${1:-}")"
+  [[ -n "$now" ]] || {
+    echo unknown
+    return
+  }
+  [[ "$now" == "$BUN_SERIES" ]] && {
+    echo in
+    return
+  }
+  if [[ "$(printf '%s\n%s\n' "$now" "$BUN_SERIES" | sort -V | tail -1)" == "$now" ]]; then
+    echo above
+  else
+    echo below
+  fi
+}
+
 # Present anywhere: on PATH for this root shell, or in the account's own
 # ~/.bun/bin, which is where the installer puts it and where root cannot see it.
 bun_installed() { command -v bun &>/dev/null || [[ -x "${USER_HOME}/.bun/bin/bun" ]]; }
@@ -260,8 +323,8 @@ bun_version() {
 # The system-wide link, ensured on every run rather than only after an install.
 #
 # pm2 started at boot by systemd has no login shell, so ~/.bun/bin is not on its
-# PATH — and every one of the twenty ecosystem apps that says `script: 'bun'`
-# then fails to start on reboot while working perfectly when started by hand. A
+# PATH — and every ecosystem app that says `script: 'bun'` then fails to start on
+# reboot while working perfectly when started by hand. A
 # machine that already had bun before this script ran would never get the link if
 # it were only made as part of installing.
 #
@@ -280,8 +343,22 @@ ensure_bun_symlink() {
 # systemd has no login shell and therefore no ~/.bun/bin on PATH — without the
 # symlink every bun-based sidecar fails to start on reboot and works fine when
 # started by hand, which is a miserable thing to debug.
+#
+# The version goes in as the installer's first positional argument, which it
+# documents as "a specific tag of bun to install (e.g. bun-v0.1.4)" and turns into a
+# releases/download/<tag>/ URL. `bash -s` is what carries an argument through a pipe.
+# The installer handles being pointed at an older tag on purpose — it re-probes AVX2
+# rather than assuming the baseline the newest release was built for — so this both
+# installs and pins back down.
+#
+# It REFUSES to run unpinned. An empty tag means bun_series_latest could not reach
+# the registry, and installing whatever is newest is the single outcome the pin
+# exists to prevent, so a machine with no bun is the better failure: it is loud, and
+# officer-setup's pre-flight stops on a missing bun rather than building on 1.4.
 install_bun() {
-  (cd / && sudo -H -u "$USERNAME" bash -c 'curl -fsSL https://bun.sh/install | bash') >/dev/null 2>&1
+  local tag="${1:-}"
+  [[ -n "$tag" ]] || return 1
+  (cd / && sudo -H -u "$USERNAME" bash -c "curl -fsSL https://bun.sh/install | bash -s '${tag}'") >/dev/null 2>&1
   [[ -x "${USER_HOME}/.bun/bin/bun" ]]
 }
 

scripts/setup/machine-setup/machine-setup.sh

@@ -1981,14 +1981,18 @@ step "JavaScript runtimes"
 if ! skip; then
   NODE_LTS="$(node_lts_major)"
   NODE_NOW="$(node_installed_major)"
+  # Resolved before the banner so it can state the pin rather than only the version
+  # that happens to be here. One network call, same as node_lts_label above it.
+  BUN_WANT="$(bun_series_latest)"
+  BUN_NOW="$(bun_version)"
 
   echo ""
   info "JavaScript runtimes — required, so these are installed rather than offered"
   echo "     node   ${NODE_NOW:+v$NODE_NOW }${NODE_NOW:+-> }LTS $(node_lts_label)"
   echo "            pm2 is a Node application, and officer-pty compiles node-pty"
   echo "            against whatever Node is installed — there is no Linux prebuild."
-  echo "     bun    $(bun_installed && bun_version || echo 'not installed')"
-  echo "            the platform itself, and nineteen of the twenty pm2 apps."
+  echo "     bun    ${BUN_NOW:-not installed} — pinned to the ${BUN_SERIES} series${BUN_WANT:+, newest is ${BUN_WANT}}"
+  echo "            the platform itself, and every pm2 app except officer-pty."
   echo "     pm2    $(pm2_installed && echo installed || echo 'not installed')"
   echo "            supervises all of them, and the ecosystem files are written for it."
   echo ""
@@ -2014,18 +2018,93 @@ if ! skip; then
     fi
   fi
 
-  # ── bun ──
-  if bun_installed; then
-    ok "bun $(bun_version) already installed"
-  else
-    info "     installing bun..."
-    if install_bun && bun_installed; then
+  # ── bun, held at the pinned series ──
+  #
+  # Four states, because "installed" is not one answer. A machine can be inside the
+  # pin, behind it, or past it — and past it is the case worth catching, since that
+  # is what a `bun upgrade` leaves behind and nothing else reports it.
+  if [[ -z "$BUN_WANT" ]]; then
+    # No pin resolved means no install: taking whatever bun.sh serves is the one
+    # thing the pin exists to stop.
+    warn "could not reach the npm registry to find the newest bun ${BUN_SERIES}.x"
+    if bun_installed; then
+      echo "     leaving bun ${BUN_NOW} where it is"
+      ERRORS+=("Bun: could not resolve ${BUN_SERIES}.x; left ${BUN_NOW} alone")
+    else
+      echo "     nothing installed — this will not install an unpinned bun, and"
+      echo "     officer-setup stops on a missing bun rather than building on 1.4."
+      ERRORS+=("Bun: could not resolve ${BUN_SERIES}.x; nothing installed")
+    fi
+
+  elif ! bun_installed; then
+    info "     installing bun ${BUN_WANT}, pinned to the ${BUN_SERIES} series..."
+    if install_bun "bun-v${BUN_WANT}" && bun_installed; then
       ok "bun $(bun_version)"
-      SUMMARY+=("Bun: $(bun_version)")
+      SUMMARY+=("Bun: $(bun_version) (pinned to ${BUN_SERIES}.x)")
     else
       warn "the bun install did not complete"
       ERRORS+=("Bun: install failed")
     fi
+
+  else
+    case "$(bun_series_position "$BUN_NOW")" in
+      in)
+        if [[ "$BUN_NOW" == "$BUN_WANT" ]]; then
+          ok "bun ${BUN_NOW} — the newest in the pinned ${BUN_SERIES} series"
+        else
+          info "bun ${BUN_NOW} is inside the pin, and ${BUN_WANT} is out"
+          echo "     A patch inside the series is what the pin is meant to let"
+          echo "     through. Note that 'bun upgrade' would not stop there — it"
+          echo "     takes the newest release, which is past the pin."
+          if confirm "Move to ${BUN_WANT}?"; then
+            if install_bun "bun-v${BUN_WANT}"; then
+              ok "bun $(bun_version)"
+              SUMMARY+=("Bun: ${BUN_NOW} -> $(bun_version)")
+            else
+              warn "the install did not complete — bun ${BUN_NOW} is untouched"
+              ERRORS+=("Bun: could not move to ${BUN_WANT}")
+            fi
+          else
+            echo "     left at ${BUN_NOW}"
+          fi
+        fi
+        ;;
+      above)
+        # The `bun upgrade` case. Reported rather than corrected silently: moving
+        # somebody's runtime backwards is a decision, and this is the only place
+        # that knows it happened.
+        warn "bun ${BUN_NOW} is PAST the pinned ${BUN_SERIES} series"
+        echo "     Most likely a 'bun upgrade', which takes no version argument and"
+        echo "     always jumps to the newest release. The platform and every pm2"
+        echo "     app except officer-pty run on this."
+        if confirm "Pin it back to ${BUN_WANT}?"; then
+          if install_bun "bun-v${BUN_WANT}"; then
+            ok "bun $(bun_version) — back inside the pin"
+            SUMMARY+=("Bun: pinned back, ${BUN_NOW} -> $(bun_version)")
+          else
+            warn "the install did not complete — bun ${BUN_NOW} is untouched"
+            ERRORS+=("Bun: could not pin ${BUN_NOW} back to ${BUN_WANT}")
+          fi
+        else
+          warn "left at ${BUN_NOW}, outside the pin"
+          SUMMARY+=("Bun: ${BUN_NOW}, PAST the ${BUN_SERIES} pin by choice")
+        fi
+        ;;
+      *)
+        info "bun ${BUN_NOW} is older than the pinned ${BUN_SERIES} series"
+        if confirm "Move to ${BUN_WANT}?"; then
+          if install_bun "bun-v${BUN_WANT}"; then
+            ok "bun $(bun_version)"
+            SUMMARY+=("Bun: ${BUN_NOW} -> $(bun_version)")
+          else
+            warn "the install did not complete — bun ${BUN_NOW} is untouched"
+            ERRORS+=("Bun: could not move to ${BUN_WANT}")
+          fi
+        else
+          echo "     left at ${BUN_NOW}"
+        fi
+        ;;
+    esac
   fi
 
   # Ensured every run, not only after an install. A machine that already had bun

scripts/setup/officer-setup.sh

@@ -760,7 +760,7 @@ if ! skip; then
   echo "     The ecosystem file is GENERATED, not checked in. It describes this"
   echo "     install and nothing else, so nothing in git can drift from it."
   echo ""
-  echo "     six processes:"
+  echo "     ${#CORE_PROCESSES[@]} processes:"
   for entry in "${CORE_PROCESSES[@]}"; do
     IFS='|' read -r _name _script _args <<<"$entry"
     printf "       %-24s %s %s\n" "$_name" "$_script" "$_args"
@@ -772,7 +772,7 @@ if ! skip; then
   if confirm "Write it and start them?"; then
     write_ecosystem
     ok "written — $(ecosystem_file)"
-    report_changed "wrote $(ecosystem_file) — six pm2 apps: $(printf '%s ' "${CORE_PROCESSES[@]%%|*}")"
+    report_changed "wrote $(ecosystem_file) — ${#CORE_PROCESSES[@]} pm2 apps: $(printf '%s ' "${CORE_PROCESSES[@]%%|*}")"
 
     # Starting against a database that is not answering is not fatal — the server
     # waits and the agent retries forever — but it makes the Verify section below
@@ -792,13 +792,13 @@ if ! skip; then
         if pm2_enable_startup; then
           ok "pm2 will resurrect them at boot"
           report_ran "pm2 startup systemd — installed a systemd unit so pm2 resurrects these at boot"
-          SUMMARY+=("Services: 6 processes started, enabled at boot")
+          SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started, enabled at boot")
         else
           warn "could not enable the boot hook — run 'pm2 startup' yourself and follow it"
-          SUMMARY+=("Services: 6 processes started; boot hook NOT enabled")
+          SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started; boot hook NOT enabled")
         fi
       else
-        SUMMARY+=("Services: 6 processes started; not enabled at boot")
+        SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started; not enabled at boot")
       fi
     else
       warn "pm2 did not start cleanly"
@@ -945,7 +945,7 @@ fi
 #
 # Root, and that surprises people — reasonably, because everything this script just
 # installed belongs to somebody else. The platform runs as ${USERNAME}: the checkout,
-# node_modules, .env, the secret store and all six pm2 processes are theirs. Root was
+# node_modules, .env, the secret store and every pm2 process are theirs. Root was
 # the installer's privilege, never the platform's.
 #
 # Saying so matters for two things that are invisible until they bite:

scripts/setup/officer-setup/lib/preflight.sh

@@ -59,7 +59,7 @@ tool_why() {
   case "$1" in
     git) echo "to clone and update the platform" ;;
     node) echo "pm2 runs on it, and the terminal sidecar builds node-pty against it" ;;
-    bun) echo "the platform itself and nineteen of the twenty processes" ;;
+    bun) echo "the platform itself and every process except the pty sidecar" ;;
     pm2) echo "supervises every process; the ecosystem files are written for it" ;;
     docker) echo "Postgres, and anything the app store provisions" ;;
     *) echo "" ;;

scripts/themes/ansi-source.ts

@@ -0,0 +1,205 @@
+// Reading a community theme's actual shipped format.
+//
+// Omarchy's own 22 themes carry a `colors.toml` in the semantic shape `palette.ts` expects — three
+// background depths, four foreground weights, an accent, a selection, a muted. A community theme on
+// omarchythemes.com ships none of that: it's per-app config files in the classic 16-ANSI-slot style,
+// because that's what predates Omarchy 4's own format and what most single-theme repos still use.
+//
+// This file reads the two shapes that cover almost every repo: `alacritty.toml` (structured, typed,
+// preferred) and `ghostty.conf`/`ghostty-theme` (flat `key = value` lines, fallback). Either becomes an
+// `AnsiSource` — the 16 ANSI slots plus primary background/foreground — which `from-ansi.ts` turns into
+// the same `Palette` shape the official pipeline consumes, so every downstream guarantee (contrast
+// checking, the 84-token mapping) applies unchanged.
+
+export type AnsiSource = {
+  background: string;
+  foreground: string;
+  black: string;
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  brightBlack: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+};
+
+// `#rrggbb` is standard; `0xrrggbb` shows up in a handful of community alacritty.toml files (their
+// authors apparently ported from a scheme that used C-style hex literals).
+const HEX = /#[0-9a-fA-F]{3,8}|0x[0-9a-fA-F]{3,8}/;
+
+function normalizeHex(v: string): string | undefined {
+  const m = v.match(HEX);
+  if (!m) return undefined;
+  let h = m[0].replace(/^(#|0x)/, '').toLowerCase();
+  if (h.length === 3)
+    h = h
+      .split('')
+      .map((c) => c + c)
+      .join('');
+  if (h.length >= 6) h = h.slice(0, 6);
+  return `#${h}`;
+}
+
+/** A deliberately small TOML reader: flat `key = "value"` lines plus `[section]` headers. */
+export function parseAlacrittyToml(text: string): AnsiSource | undefined {
+  let section = '';
+  const rows: Record<string, Record<string, string>> = {};
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    const sectionMatch = line.match(/^\[([\w.]+)]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1]!;
+      rows[section] ??= {};
+      continue;
+    }
+    // Quoted specifically, not "anything but a comment" — a hex value starts with `#`, the same
+    // character that opens a trailing comment, so the two can only be told apart by the quotes.
+    const kv = line.match(/^([\w-]+)\s*=\s*(['"])(.*?)\2/);
+    if (kv && section) {
+      const hex = normalizeHex(kv[3]!);
+      if (hex) rows[section]![kv[1]!] = hex;
+    }
+  }
+
+  const primary = rows['colors.primary'];
+  const normal = rows['colors.normal'];
+  const bright = rows['colors.bright'];
+  if (!primary?.background || !primary?.foreground || !normal || !bright) return undefined;
+
+  const need = (r: Record<string, string>, k: string): string | undefined => r[k];
+  const n = (k: string) => need(normal, k);
+  const b = (k: string) => need(bright, k);
+  if (
+    !n('black') ||
+    !n('red') ||
+    !n('green') ||
+    !n('yellow') ||
+    !n('blue') ||
+    !n('magenta') ||
+    !n('cyan') ||
+    !n('white')
+  )
+    return undefined;
+  if (
+    !b('black') ||
+    !b('red') ||
+    !b('green') ||
+    !b('yellow') ||
+    !b('blue') ||
+    !b('magenta') ||
+    !b('cyan') ||
+    !b('white')
+  )
+    return undefined;
+
+  return {
+    background: primary.background,
+    foreground: primary.foreground,
+    black: n('black')!,
+    red: n('red')!,
+    green: n('green')!,
+    yellow: n('yellow')!,
+    blue: n('blue')!,
+    magenta: n('magenta')!,
+    cyan: n('cyan')!,
+    white: n('white')!,
+    brightBlack: b('black')!,
+    brightRed: b('red')!,
+    brightGreen: b('green')!,
+    brightYellow: b('yellow')!,
+    brightBlue: b('blue')!,
+    brightMagenta: b('magenta')!,
+    brightCyan: b('cyan')!,
+    brightWhite: b('white')!,
+  };
+}
+
+/** Ghostty's config: flat `key = value`, ANSI palette as sixteen `palette = N=#hex` lines. */
+export function parseGhosttyConf(text: string): AnsiSource | undefined {
+  let background: string | undefined;
+  let foreground: string | undefined;
+  const palette: Record<number, string> = {};
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (line.startsWith('#')) continue;
+    const bg = line.match(/^background\s*=\s*(#[0-9a-fA-F]{3,8})/);
+    if (bg) background = normalizeHex(bg[1]!);
+    const fg = line.match(/^foreground\s*=\s*(#[0-9a-fA-F]{3,8})/);
+    if (fg) foreground = normalizeHex(fg[1]!);
+    const pal = line.match(/^palette\s*=\s*(\d+)\s*=\s*(#[0-9a-fA-F]{3,8})/);
+    if (pal) {
+      const hex = normalizeHex(pal[2]!);
+      if (hex) palette[Number(pal[1])] = hex;
+    }
+  }
+
+  if (!background || !foreground) return undefined;
+  for (let i = 0; i <= 15; i++) if (!palette[i]) return undefined;
+
+  return {
+    background,
+    foreground,
+    black: palette[0]!,
+    red: palette[1]!,
+    green: palette[2]!,
+    yellow: palette[3]!,
+    blue: palette[4]!,
+    magenta: palette[5]!,
+    cyan: palette[6]!,
+    white: palette[7]!,
+    brightBlack: palette[8]!,
+    brightRed: palette[9]!,
+    brightGreen: palette[10]!,
+    brightYellow: palette[11]!,
+    brightBlue: palette[12]!,
+    brightMagenta: palette[13]!,
+    brightCyan: palette[14]!,
+    brightWhite: palette[15]!,
+  };
+}
+
+/**
+ * A third shape some community repos name `colors.toml` too, unrelated to Omarchy 4's own — flat
+ * `color0`..`color15` in standard ANSI order, plus `background`/`foreground`. Try this only after
+ * `paletteFromRecord` (the real Omarchy schema) has already failed on the same file: the two are
+ * distinguished only by which keys are present, and a file can't be both.
+ */
+export function parseColor16Toml(t: Record<string, string>): AnsiSource | undefined {
+  const at = (i: number): string | undefined => (t[`color${i}`] ? normalizeHex(t[`color${i}`]!) : undefined);
+  const background = t.background ? normalizeHex(t.background) : undefined;
+  const foreground = t.foreground ? normalizeHex(t.foreground) : undefined;
+  if (!background || !foreground) return undefined;
+  const slots = Array.from({ length: 16 }, (_, i) => at(i));
+  if (slots.some((s) => !s)) return undefined;
+
+  return {
+    background,
+    foreground,
+    black: slots[0]!,
+    red: slots[1]!,
+    green: slots[2]!,
+    yellow: slots[3]!,
+    blue: slots[4]!,
+    magenta: slots[5]!,
+    cyan: slots[6]!,
+    white: slots[7]!,
+    brightBlack: slots[8]!,
+    brightRed: slots[9]!,
+    brightGreen: slots[10]!,
+    brightYellow: slots[11]!,
+    brightBlue: slots[12]!,
+    brightMagenta: slots[13]!,
+    brightCyan: slots[14]!,
+    brightWhite: slots[15]!,
+  };
+}

scripts/themes/from-ansi.ts

@@ -0,0 +1,76 @@
+import type { Palette } from './palette';
+import type { AnsiSource } from './ansi-source';
+import { UI, contrast, ensureContrast, luminance, mix, parseHex } from './contrast';
+
+// An `AnsiSource` (16 ANSI slots + primary bg/fg) has no notion of "three background depths" or "an
+// accent" — Omarchy 4's `colors.toml` is a richer, hand-curated shape that a sixteen-slot terminal scheme
+// was never designed to fill. This derives one anyway, by role rather than by guessing a fixed value:
+//
+//   - accent is whichever blue-ish slot actually stands out from the background (every official palette
+//     picks blue too — this just guards against a scheme that reused the background for it).
+//   - the three depths are the background pushed a fixed distance toward black or white, in the direction
+//     each mode's surfaces already move (dark themes rise lighter, light themes recede darker — see the
+//     ratios comment below, calibrated against Nord and Rosé Pine's real colors.toml).
+//   - the three foreground weights are the foreground pulled toward the background by a fixed fraction,
+//     standing in for "faint", "muted" and "strong" text.
+//
+// None of this has to be exact. `mapPalette`'s `ensureContrast` re-checks every text/surface pair
+// afterward and nudges anything that fails — the approximation only has to be plausible, not correct.
+
+function pickAccent(a: AnsiSource): string {
+  const candidates = [a.blue, a.brightBlue, a.cyan, a.brightCyan];
+  const best = candidates.reduce((hi, c) => (contrast(c, a.background) > contrast(hi, a.background) ? c : hi));
+  // `--ring` is this colour laid directly on `--background` (see `map.ts`), and it's in the contract's
+  // PAIRS check same as the official themes — so guarantee it the way `ensureContrast` guarantees text,
+  // rather than only guarding against a background-coloured accent.
+  return ensureContrast(best, a.background, UI);
+}
+
+export function deriveOmarchyPalette(a: AnsiSource): Palette {
+  const dark = luminance(parseHex(a.background)) < 0.5;
+  const mode: Palette['mode'] = dark ? 'dark' : 'light';
+
+  const darkerBackground = dark ? mix(a.background, '#000000', 0.45) : mix(a.background, '#000000', 0.1);
+  const darkBackground = dark ? mix(a.background, '#000000', 0.22) : mix(a.background, '#000000', 0.06);
+  const lighterBackground = dark ? mix(a.background, '#ffffff', 0.07) : mix(a.background, '#000000', 0.035);
+
+  // Faintest → strongest, all pulled toward the background rather than toward a fixed grey, so a warm
+  // palette's dim text stays warm instead of turning neutral.
+  const darkForeground = mix(a.foreground, a.background, 0.55);
+  const lightForeground = mix(a.foreground, a.background, 0.3);
+
+  const accent = pickAccent(a);
+  const muted = contrast(a.brightBlack, a.background) >= 1.15 ? a.brightBlack : mix(a.foreground, a.background, 0.6);
+
+  return {
+    mode,
+    accent,
+    // Unused by `mapPalette` today (grep confirms `p.selection` has no reader) — kept only because the
+    // `Palette` type requires it.
+    selection: mix(a.background, a.foreground, 0.2),
+    muted,
+    background: a.background,
+    darkBackground,
+    darkerBackground,
+    lighterBackground,
+    foreground: a.foreground,
+    darkForeground,
+    lightForeground,
+    brightForeground: a.foreground,
+    red: a.red,
+    yellow: a.yellow,
+    green: a.green,
+    cyan: a.cyan,
+    blue: a.blue,
+    magenta: a.magenta,
+    // Standard ANSI has no orange slot. Mixing red and yellow reads better as "busy" than falling back to
+    // plain yellow the way `loadPalette` does for the 3 official themes that omit it.
+    orange: mix(a.red, a.yellow, 0.5),
+    brightRed: a.brightRed,
+    brightYellow: a.brightYellow,
+    brightGreen: a.brightGreen,
+    brightCyan: a.brightCyan,
+    brightBlue: a.brightBlue,
+    brightMagenta: a.brightMagenta,
+  };
+}

scripts/themes/map.ts

@@ -49,6 +49,13 @@ export function mapPalette(p: Palette): Tokens {
   // miasma at 4.00 — close enough to look fine and still fail, which is the kind of near-miss that a
   // person eyeballing a screenshot would have shipped.
   const fgMuted = ensureContrast(p.lightForeground, s.high);
+  // Same reasoning as `fgMuted`, for the same surface: `--accent` and `--secondary` are BOTH `s.high`,
+  // so their text has to be checked against `s.high` too. It was deriving from `fgRaised` — the weight
+  // for `s.raised` — which is the identical near-miss the comment above describes, just one token over.
+  // A no-op for all 22 official palettes (each already clears 4.5:1 on `s.high` by 1.4x or more, and
+  // `ensureContrast` returns its input untouched when it passes); what it fixes is the ported palettes
+  // whose foreground sits between the two surfaces' thresholds.
+  const fgHigh = ensureContrast(p.foreground, s.high);
   const fgFaint = ensureContrast(p.darkForeground, s.raised, UI);
 
   /**
@@ -88,13 +95,13 @@ export function mapPalette(p: Palette): Tokens {
     '--muted': s.high,
     '--muted-foreground': fgMuted,
     '--accent': s.high,
-    '--accent-foreground': fgRaised,
+    '--accent-foreground': fgHigh,
 
     // ── Actions ──
     '--primary': accent,
     '--primary-foreground': on(accent),
     '--secondary': s.high,
-    '--secondary-foreground': fgRaised,
+    '--secondary-foreground': fgHigh,
     '--cta': accent,
     '--cta-foreground': on(accent),
     '--ctahover': mix(accent, s.dark ? '#ffffff' : '#000000', 0.12),

scripts/themes/palette.ts

@@ -38,21 +38,28 @@ export type Palette = {
   brightMagenta: string;
 };
 
-/** A deliberately small TOML reader: this file is flat `key = "value"` and nothing else. */
-function readToml(path: string): Record<string, string> {
+/**
+ * A deliberately small TOML reader: this file is flat `key = "value"` and nothing else.
+ *
+ * Exported (not just used by `loadPalette` below) because a community theme can ship this exact shape
+ * too — see `port-community-themes.ts`, which reads it from a fetched string rather than a file path.
+ */
+export function parseTomlText(text: string): Record<string, string> {
   const out: Record<string, string> = {};
-  for (const line of readFileSync(path, 'utf8').split('\n')) {
+  for (const line of text.split('\n')) {
     const m = line.match(/^\s*([a-z_0-9]+)\s*=\s*"([^"]*)"/i);
-    if (m) out[m[1]!] = m[2]!;
+    // basecamp/omarchy's own files are already lowercase hex; a community `colors.toml` isn't guaranteed
+    // to be, so normalize here rather than leaving the two sources visibly inconsistent.
+    if (m) out[m[1]!] = m[2]!.toLowerCase();
   }
   return out;
 }
 
-export function loadPalette(tomlPath: string): Palette {
-  const t = readToml(tomlPath);
+/** The 24-key contract, given an already-parsed record rather than a path — see `parseTomlText`. */
+export function paletteFromRecord(t: Record<string, string>, label: string): Palette {
   const need = (key: string): string => {
     const v = t[key];
-    if (!v) throw new Error(`${tomlPath}: missing "${key}"`);
+    if (!v) throw new Error(`${label}: missing "${key}"`);
     return v;
   };
 
@@ -84,3 +91,7 @@ export function loadPalette(tomlPath: string): Palette {
     brightMagenta: need('bright_magenta'),
   };
 }
+
+export function loadPalette(tomlPath: string): Palette {
+  return paletteFromRecord(parseTomlText(readFileSync(tomlPath, 'utf8')), tomlPath);
+}

src/apps/officer-web/App.tsx

@@ -106,6 +106,8 @@ export function App() {
             <Route path="/system-monitor/:scope" element={<Dashboard.SystemMonitorScreen />} />
             {/* TEMPORARY / EXPERIMENTAL — offline file transfer over animated QR codes */}
             <Route path="/qr-transfer" element={<Dashboard.QrTransferScreen />} />
+            <Route path="/minesweeper" element={<Dashboard.MinesweeperScreen />} />
+            <Route path="/sendoff" element={<Dashboard.SendOffScreen />} />
             <Route path="/activity" element={<Dashboard.ActivityScreen />} />
             <Route path="/activity/:id" element={<Dashboard.ActivityScreen />} />
 

src/apps/officer-web/Screens/Dashboard/CommandHQ/CommandHqScreen.tsx

@@ -1,15 +1,29 @@
+import { useEffect } from 'react';
 import type { LayoutNode } from 'officerdev';
 import { WorkspaceView } from 'officerdev';
 import { useDashboardState } from 'state/useDashboardState';
-import { defaultLayout } from './defaultLayout';
+import { defaultLayout, isLegacyThreeColumn } from './defaultLayout';
 
-// /command-hq: nav + grid + detail, all three always mounted (like /chat), selection carried by the URL
+// /command-hq: navigation and detail, all panels always mounted (like /chat), selection carried by the URL
 // — `?category=` for the nav filter, `:sessionId` for the open commander. See `docs/command-hq.md` →
-// "Route, surface, placement" and "Layout, v1".
+// "Route, surface, placement".
 
 export const CommandHqScreen = () => {
   const workspace = useDashboardState<LayoutNode>('screens/command-hq', defaultLayout);
 
+  /*
+    Move a saved three-column layout onto the two-column one.
+
+    The default alone cannot do it: this key is persisted per account, so anybody who has opened the screen
+    keeps the arrangement they had. See `isLegacyThreeColumn` for why the test is structural rather than an
+    appType check, and why replacing outright is the safe direction on a `locked` screen.
+  */
+  useEffect(() => {
+    if (!workspace.isLoaded) return;
+    if (!isLegacyThreeColumn(workspace.value)) return;
+    workspace.setValue(defaultLayout);
+  }, [workspace.isLoaded, workspace.value, workspace.setValue]);
+
   return (
     <div className="h-full w-full pt-2">
       <WorkspaceView

src/apps/officer-web/Screens/Dashboard/CommandHQ/defaultLayout.ts

@@ -1,14 +1,60 @@
 import type { LayoutNode } from 'officerdev';
 
-// Three columns, per `docs/command-hq.md` → "Layout, v1": category nav, commander grid, detail pane. The
-// detail pane gets the most room because it is a live chat transcript once something is selected.
+/*
+  Two columns, with the navigation stacked into the left one.
+
+  ── Why it changed from three ──
+
+  It was `16 / 34 / 50`: a category column, a commander column, and the transcript. So half the screen was
+  navigation for a list that holds a handful of commanders — one, on the machine this was written on — while
+  the only thing anybody reads got the other half. A category pane of its own is a filter for a list short
+  enough to see whole.
+
+  Now: commanders on top, categories beneath them, transcript taking three quarters.
+
+  ── Why the categories are BELOW the commanders ──
+
+  Because the commanders are the thing you came for and the categories are how you narrow them when there
+  are too many to scan. Above, the filter would push the list down the screen and be the first thing read;
+  below, the list is at the top where a list belongs and the filter is where you reach for it. It also means
+  the categories can grow their own scrollbar without ever taking room from the commanders.
+*/
 export const defaultLayout: LayoutNode = {
   type: 'group',
   id: 'command-hq-root',
   direction: 'horizontal',
   children: [
-    { node: { type: 'panel', id: 'command-hq-categories', appType: 'command-hq-categories' }, size: 16 },
-    { node: { type: 'panel', id: 'command-hq-grid', appType: 'command-hq-grid' }, size: 34 },
-    { node: { type: 'panel', id: 'command-hq-detail', appType: 'command-hq-detail' }, size: 50 },
+    {
+      node: {
+        type: 'group',
+        id: 'command-hq-nav',
+        direction: 'vertical',
+        children: [
+          { node: { type: 'panel', id: 'command-hq-grid', appType: 'command-hq-grid' }, size: 62 },
+          { node: { type: 'panel', id: 'command-hq-categories', appType: 'command-hq-categories' }, size: 38 },
+        ],
+      },
+      size: 24,
+    },
+    { node: { type: 'panel', id: 'command-hq-detail', appType: 'command-hq-detail' }, size: 76 },
   ],
 };
+
+/**
+ * Is this a saved copy of the three-column layout this replaced?
+ *
+ * No appType was retired — all three panels survive and only their arrangement changed — so `hasAppType`
+ * cannot see this the way the /chat migration could. The test is structural instead: the old shape is a
+ * horizontal root with THREE children, and the new one has two.
+ *
+ * It terminates for that reason: the replacement does not satisfy the test.
+ *
+ * Replacing outright is safe because the screen is `locked` — its structure is dictated by code, and the
+ * only thing a person can have contributed is the column sizes, which is a cheap thing to lose once. The
+ * same reasoning, and the same warning, as `ChatHistory/index.tsx`: get the test backwards and a stranded
+ * panel collapses onto `appTypes.fallback` and is written back, which is how /offscale once rendered three
+ * copies of one picker.
+ */
+export function isLegacyThreeColumn(node: LayoutNode): boolean {
+  return node.type === 'group' && node.direction === 'horizontal' && node.children.length === 3;
+}

src/apps/officer-web/Screens/Dashboard/Layout/DashboardLayout.tsx

@@ -8,6 +8,7 @@ import { Background } from './Background';
 import { Header } from './Header';
 import { Dock, CORE_DOCK_ITEMS, dockItemsFromPlugins, defaultDockPaths } from './Dock';
 import { Spotlight } from './Spotlight/Spotlight';
+import { ShortcutsModal } from './ShortcutsModal';
 import { useIsTouch } from './useIsTouch';
 import { usePageTitleSync } from '@/state/usePageTitle';
 import { RouteGate } from './RouteGate';
@@ -51,6 +52,9 @@ export function DashboardLayout({ children }: DashboardLayoutProps) {
       {/* Outside the content region on purpose, like the header and the dock: whatever a screen is doing
           — maximised panel, error boundary, mid-navigation — ctrl-space still gets you off it. */}
       <Spotlight />
+      {/* Outside the content region for the same reason Spotlight is: ctrl+? has to work from a maximised
+          panel, an error boundary, or mid-navigation. */}
+      <ShortcutsModal />
       {/* overflow-CLIP, not hidden: `hidden` still makes this a scroll container, and the nav Dock —
           absolute, parked below the bottom edge by translateY while hidden — adds its transformed box to
           the scrollable overflow. So clicking a link let the browser scroll this section ~70px to reveal

src/apps/officer-web/Screens/Dashboard/Layout/Dock.tsx

@@ -155,6 +155,7 @@ import {
   Store,
   Puzzle,
   Radar,
+  Send,
 } from 'lucide-react';
 
 /**
@@ -180,6 +181,10 @@ export const CORE_DOCK_ITEMS: DockItem[] = [
   { label: 'Monitor', to: '/system-monitor', icon: Activity, color: '#0ea5e9' },
   { label: 'Activity', to: '/activity', icon: Radio, color: '#f59e0b' },
   { label: 'Dashboards', to: '/dashboards', icon: LayoutGrid, color: '#8b5cf6' },
+  // Core because it is the door into another account's filesystem, and the permission that gates it is
+  // `kind: 'app'` — so `canVisit()` hides the tile from anyone not granted it, which is the same treatment
+  // every other grantable tile here gets.
+  { label: 'SendOff', to: '/sendoff', icon: Send, color: '#22d3ee' },
   // Core since 2026-08-19. These were contributed by the app-store `caldav` entry until calendar and
   // contacts became core, and deleting that entry took their tiles with it — the routes kept working
   // while the dock and the settings list went silent about them, which is exactly the shape of failure

src/apps/officer-web/Screens/Dashboard/Layout/Header/Header.tsx

@@ -11,6 +11,7 @@ import { JobsIndicator } from './JobsIndicator';
 import { ThemeSwitcher } from './ThemeSwitcher';
 import { RescanButton } from '../Rescan/RescanButton';
 import { usePageTitle } from '@/state/usePageTitle';
+import { useAuth } from 'hooks/useAuth';
 import { useThemeAsset } from '@/components/ui/ThemeProvider';
 // import { BugReportButton } from '../BugReport/BugReportButton';
 
@@ -46,6 +47,7 @@ type HeaderProps = {
 export function Header({ dockItems, hidden }: HeaderProps) {
   const [open, setOpen] = useState(false);
   const isTouch = useIsTouch();
+  const { user } = useAuth();
   // The mark comes from the theme — a white-labelled build replaces it without touching this file.
   const logo = useThemeAsset('--logo-src');
 
@@ -100,9 +102,15 @@ export function Header({ dockItems, hidden }: HeaderProps) {
           */}
           {/* Bug Report — hidden */}
           {/* <BugReportButton /> */}
-          <JobsIndicator />
-          <RescanButton />
           <ThemeSwitcher />
+          {/* Owner only, and tidiness rather than access control — /jobs stays reachable and the rescan
+              endpoint is gated server-side, because a hidden button is not a permission. */}
+          {user?.role === 'Super Admin' && (
+            <>
+              <JobsIndicator />
+              <RescanButton />
+            </>
+          )}
           <UserMenu />
         </div>
       </div>

src/apps/officer-web/Screens/Dashboard/Layout/Header/ThemeSwitcher.tsx

@@ -1,8 +1,10 @@
+import { useMemo, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { Palette, Check } from 'lucide-react';
+import { Check, Star } from 'lucide-react';
+import { favouritesFirst, groupByFamily, rotateToSelected } from 'theme';
 import * as Dropdown from '@/components/ui/dropdown-menu';
-import type { Theme } from '@/components/ui/ThemeProvider';
 import { useTheme, useThemeKeys } from '@/components/ui/ThemeProvider';
+import { useThemeFavorites } from '@/state/useThemeFavorites';
 
 const {
   DropdownMenu,
@@ -21,7 +23,7 @@ const {
  *
  * ── The overlay ──
  *
- * `ctrl+alt+space` opens a list in the middle of the screen; `j`/`k` move through it and `l` applies the
+ * `ctrl+shift+space` opens a list in the middle of the screen; `j`/`k` move through it and `l` applies the
  * focused theme to the app BEHIND it. That is the whole idea, and it is why this is a portal over a
  * translucent backdrop rather than a modal dialog: you are meant to watch the application change while
  * you browse, so as little of it as possible should be covered.
@@ -30,43 +32,115 @@ const {
  */
 export const ThemeSwitcher = () => {
   const { theme, themeId, setTheme, themes } = useTheme();
-  const { open, setOpen, focused, setFocused } = useThemeKeys();
+  const { favorites, isFavorite, toggle } = useThemeFavorites();
+  // Declared before the key hook, which needs the toggle: `f` in the list and `ctrl+shift+f` from anywhere.
+  const { open, setOpen, focused, setFocused } = useThemeKeys({ onToggleFavorite: toggle });
+  const [onlyFavorites, setOnlyFavorites] = useState(false);
 
-  // Grouped by family, so `Duck Light`/`Duck Dark` and the two Catppuccins sit together. The registry is
-  // readonly, so this builds mutable arrays rather than pushing into its own type.
-  const families = themes.reduce<Record<string, Theme[]>>((acc, t) => {
-    (acc[t.family] ??= []).push(t);
-    return acc;
-  }, {});
+  /*
+    One ordering, used by both lists.
+
+    ROTATED to the theme you are wearing rather than sorted: with 200+ installed, the list's only structure
+    is the registry order — families sit together in it — and lifting the selected theme out of its family
+    would answer "which am I on" by destroying "what is next to it". A rotation answers both. See
+    `theme/rotate.ts`.
+
+    Then favourites first, which is a second rotation-preserving pass rather than a filter: each half keeps
+    the order it was given, so the theme you are wearing still leads.
+  */
+  const ordered = useMemo(() => {
+    const rotated = rotateToSelected(themes, themeId);
+    const listed = onlyFavorites ? rotated.filter((t) => favorites.has(t.id)) : rotated;
+    return favouritesFirst(listed, favorites);
+    // `favorites` is a fresh Set each render; its CONTENTS are what matter, so key on those.
+  }, [themes, themeId, onlyFavorites, [...favorites].sort().join(',')]);
+
+  const families = useMemo(() => groupByFamily(ordered), [ordered]);
 
   return (
     <>
       <DropdownMenu>
         <DropdownMenuTrigger asChild>
           <button
-            title={`Theme: ${theme.name}  ·  ctrl+shift+←/→ to cycle · ctrl+shift+space for the list`}
-            aria-label="Theme"
-            className="flex h-8 w-8 items-center justify-center rounded-full transition-transform hover:scale-110 cursor-pointer"
+            title={`Theme: ${theme.name}  ·  ctrl+shift+←/→ cycle · ctrl+shift+space browse · ctrl+shift+f ${
+              isFavorite(themeId) ? 'unstar' : 'star'
+            }`}
+            aria-label={`Theme: ${theme.name}`}
+            // Named rather than a palette glyph: with 227 themes the one you are wearing is worth
+            // reading at a glance, and an icon cannot say which that is. Same pill as JobsIndicator so
+            // the cluster stays one shape.
+            className="flex h-8 cursor-pointer items-center rounded-full bg-black/25 px-2.5 text-xs font-semibold transition-colors hover:bg-black/35"
             style={{ color: 'var(--header-fg)' }}
           >
-            <Palette className="h-4 w-4" />
+            {theme.name}
+            {/* A star on the pill, so "is this one of mine" is answerable without opening anything. Only
+                when true — a hollow star on every theme would be chrome that says nothing 200 times. */}
+            {isFavorite(themeId) && <Star className="ml-1.5 h-3 w-3 fill-current opacity-80" />}
           </button>
         </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" className="z-50 max-h-[70vh] w-56 overflow-y-auto">
-          <DropdownMenuLabel className="text-xs font-normal text-muted-foreground">
-            ctrl+shift+←/→ · ctrl+shift+space
-          </DropdownMenuLabel>
-          <DropdownMenuSeparator />
-          {Object.entries(families).map(([family, entries]) => (
-            <div key={family}>
-              {entries.map((t) => (
-                <DropdownMenuItem key={t.id} onClick={() => setTheme(t.id)} className="cursor-pointer">
-                  <Check className={`mr-2 h-4 w-4 ${t.id === themeId ? 'opacity-100' : 'opacity-0'}`} />
-                  {t.name}
-                </DropdownMenuItem>
-              ))}
-            </div>
-          ))}
+        {/*
+          The CONTENT does not scroll — the list inside it does.
+
+          It used to carry `overflow-y-auto` itself, which scrolled the instruction line away with the
+          themes. Two hundred entries meant the one line telling you the keyboard shortcuts existed was
+          visible for the first half-second and then gone for good, which is the same as not having written
+          it. Header and footer are now siblings of a scroll box rather than passengers in one.
+        */}
+        <DropdownMenuContent align="end" className="z-50 flex max-h-[70vh] w-64 flex-col overflow-hidden p-0">
+          <div className="shrink-0 border-b border-border px-2 py-1.5">
+            <DropdownMenuLabel className="px-0 py-0 text-xs font-normal leading-relaxed text-muted-foreground">
+              <span className="block">ctrl+shift+←/→ cycle · ctrl+shift+space browse</span>
+              <span className="block">ctrl+? for every shortcut</span>
+            </DropdownMenuLabel>
+            <button
+              type="button"
+              onClick={(ev) => {
+                // The dropdown closes on any item activation, and this is a filter rather than a choice.
+                ev.preventDefault();
+                ev.stopPropagation();
+                setOnlyFavorites((was) => !was);
+              }}
+              className={`mt-1 inline-flex cursor-pointer items-center gap-1.5 rounded px-1.5 py-0.5 text-xs font-medium transition-colors ${
+                onlyFavorites ? 'bg-primary/15 text-primary' : 'text-muted-foreground hover:text-foreground'
+              }`}
+            >
+              <Star className={`h-3.5 w-3.5 ${onlyFavorites ? 'fill-current' : ''}`} />
+              {onlyFavorites ? `Favourites only (${favorites.size})` : `Favourites (${favorites.size})`}
+            </button>
+          </div>
+
+          <div className="min-h-0 flex-1 overflow-y-auto p-1">
+            {ordered.length === 0 ? (
+              <p className="px-2 py-6 text-center text-xs text-muted-foreground">
+                No favourites yet — star one with the button on its row.
+              </p>
+            ) : (
+              families.map(([family, entries]) => (
+                <div key={family}>
+                  {entries.map((t) => (
+                    <DropdownMenuItem key={t.id} onClick={() => setTheme(t.id)} className="cursor-pointer pr-1">
+                      <Check className={`mr-2 h-4 w-4 shrink-0 ${t.id === themeId ? 'opacity-100' : 'opacity-0'}`} />
+                      <span className="min-w-0 flex-1 truncate">{t.name}</span>
+                      {/* A sibling of the row's action, never nested inside it — starring is not choosing. */}
+                      <button
+                        type="button"
+                        aria-label={isFavorite(t.id) ? `Unstar ${t.name}` : `Star ${t.name}`}
+                        title={isFavorite(t.id) ? 'Remove from favourites' : 'Add to favourites'}
+                        onClick={(ev) => {
+                          ev.preventDefault();
+                          ev.stopPropagation();
+                          toggle(t.id);
+                        }}
+                        className="ml-1 shrink-0 rounded p-1 text-muted-foreground hover:text-primary"
+                      >
+                        <Star className={`h-3.5 w-3.5 ${isFavorite(t.id) ? 'fill-current text-primary' : ''}`} />
+                      </button>
+                    </DropdownMenuItem>
+                  ))}
+                </div>
+              ))
+            )}
+          </div>
         </DropdownMenuContent>
       </DropdownMenu>
 
@@ -87,8 +161,11 @@ export const ThemeSwitcher = () => {
               }}
               onClick={(ev) => ev.stopPropagation()}
             >
-              <ul className="flex flex-col gap-1">
-                {themes.map((t) => {
+              {/* The SAME `ordered` list as the dropdown — rotated to what you are wearing, favourites
+                  first. Both lists agreeing is the point: "the one below the one I have on" has to mean the
+                  same thing in both, or the browse teaches you an order the menu then contradicts. */}
+              <ul className="flex max-h-[70vh] flex-col gap-1 overflow-y-auto">
+                {ordered.map((t) => {
                   const isFocused = t.id === focused;
                   return (
                     <li key={t.id}>
@@ -98,19 +175,43 @@ export const ThemeSwitcher = () => {
                           setTheme(t.id);
                           setOpen(false);
                         }}
-                        className={`w-full rounded-md px-4 py-1 text-left transition-all cursor-pointer ${
+                        className={`flex w-full items-center gap-2 rounded-md px-4 py-1 text-left transition-all cursor-pointer ${
                           isFocused ? 'text-2xl font-extrabold' : 'text-lg opacity-60 hover:opacity-100'
                         }`}
                       >
-                        {t.name}
-                        {t.id === themeId && <span className="ml-2 align-middle text-xs opacity-70">active</span>}
+                        <span className="min-w-0 flex-1 truncate">{t.name}</span>
+                        {t.id === themeId && <span className="shrink-0 text-xs opacity-70">active</span>}
+                        {/*
+                          A span, not a button: this sits inside the row's own <button>, and a button inside
+                          a button is invalid HTML that browsers resolve by dropping one of them. The click
+                          handler and the role are set explicitly instead, and `f` does the same thing from
+                          the keyboard.
+                        */}
+                        <span
+                          role="button"
+                          tabIndex={-1}
+                          aria-label={isFavorite(t.id) ? `Unstar ${t.name}` : `Star ${t.name}`}
+                          title={isFavorite(t.id) ? 'Remove from favourites (f)' : 'Add to favourites (f)'}
+                          onClick={(ev) => {
+                            // Or the row's own onClick applies the theme and closes the overlay, which is
+                            // the opposite of what starring is for.
+                            ev.preventDefault();
+                            ev.stopPropagation();
+                            toggle(t.id);
+                          }}
+                          className="shrink-0 rounded p-1 opacity-70 hover:opacity-100"
+                        >
+                          <Star className={`h-4 w-4 ${isFavorite(t.id) ? 'fill-current' : ''}`} />
+                        </span>
                       </button>
                     </li>
                   );
                 })}
               </ul>
+              {/* Always visible: it sits outside the scroll box above, for the same reason the dropdown's
+                  header does. */}
               <p className="mt-6 text-center text-xs opacity-60">
-                j/k or ↑/↓ move · l or → preview · h or ← reset · enter keep · esc cancel
+                j/k or ↑/↓ move · l or → preview · f star · h or ← reset · enter keep · esc cancel
               </p>
             </div>
           </div>,

src/apps/officer-web/Screens/Dashboard/Layout/ShortcutsModal.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react';
+import { Keyboard } from 'lucide-react';
+import { isShortcutsChord, SHORTCUT_SECTIONS } from '@/state/shortcuts';
+
+/*
+  `Ctrl+?` — every shortcut the shell owns, on one screen.
+
+  Ported in shape from `vimazing`, where the controls are declared as data and the help screen renders them.
+  Its renderer was a recursive `any` walk over arbitrary content, which is right for a game whose help also
+  carries rules and scoring; here the content is one shape, so the renderer is typed and boring and the
+  interesting part is `state/shortcuts.ts`.
+
+  Card per section, two columns on anything wider than a phone — the same arrangement vimazing used for its
+  controls grid, and for the same reason: these are short lists that read badly as one long column.
+*/
+
+const Row = ({ keys, description }: { keys: string; description: string }) => (
+  <div className="flex items-baseline gap-3 py-1">
+    {/* Fixed width, tabular: the chords line up into a column you can scan, which is the whole point of
+        putting them on the left. */}
+    <kbd className="w-32 shrink-0 rounded border border-border bg-muted/60 px-1.5 py-0.5 text-center font-mono text-[11px] text-foreground/90">
+      {keys}
+    </kbd>
+    <span className="text-sm text-muted-foreground">{description}</span>
+  </div>
+);
+
+export const ShortcutsModal = () => {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const onKey = (ev: KeyboardEvent) => {
+      if (isShortcutsChord(ev)) {
+        // No focus check: `Ctrl+?` types nothing in a text field, and a help list you cannot open from the
+        // composer is a help list you cannot open — the lesson from the Spotlight guard.
+        ev.preventDefault();
+        setOpen((was) => !was);
+        return;
+      }
+      if (ev.key === 'Escape' && open) setOpen(false);
+    };
+    // Capture, so a panel with its own key handling cannot swallow it first.
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  }, [open]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-[901] flex items-start justify-center bg-black/50 pt-[8vh] backdrop-blur-sm"
+      onMouseDown={() => setOpen(false)}
+    >
+      <div
+        className="flex max-h-[80vh] w-[min(94vw,860px)] flex-col overflow-hidden rounded-2xl border border-border bg-background/95 shadow-2xl"
+        onMouseDown={(ev) => ev.stopPropagation()}
+      >
+        <div className="flex shrink-0 items-center gap-2 border-b border-border px-5 py-3">
+          <Keyboard className="h-4 w-4 text-muted-foreground" />
+          <h2 className="text-sm font-semibold">Keyboard shortcuts</h2>
+          <span className="ml-auto text-xs text-muted-foreground">Ctrl+? · Esc to close</span>
+        </div>
+
+        {/* Only this scrolls — the header stays, for the same reason the theme dropdown's does. */}
+        <div className="grid min-h-0 flex-1 gap-5 overflow-y-auto p-5 sm:grid-cols-2">
+          {SHORTCUT_SECTIONS.map((section) => (
+            <section key={section.title} className="rounded-xl border border-border bg-muted/20 p-4">
+              <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground/80">{section.title}</h3>
+              {section.note && <p className="mt-1 text-[11px] leading-snug text-muted-foreground">{section.note}</p>}
+              <div className="mt-2">
+                {section.shortcuts.map((shortcut) => (
+                  <Row key={shortcut.keys} keys={shortcut.keys} description={shortcut.description} />
+                ))}
+              </div>
+            </section>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/Spotlight.tsx

@@ -11,19 +11,58 @@ import { useSpotlightItems, type SpotlightItem } from './useSpotlightItems';
 //
 // ── Keyboard first, and the trigger ──
 //
-// `shift-space`. The two obvious chords were both taken: `ctrl-space` focuses the address bar in Brave,
-// and `alt-space` is load-bearing for the owner elsewhere. `cmd-k` belongs to the browser on some
-// platforms and to text fields on others.
+// `shift-space`, and ONLY that. Fifth setting: ctrl-space → shift-space → alt-space → ctrl-space →
+// shift-space. Every move was the owner naming a collision, and by now the list is the useful part:
 //
-// **Shift-space is a real key combination inside a text field** — it types a space, and people hold shift
-// through one more often than they think while typing capitals. So the trigger is IGNORED when focus is
-// in an input, a textarea or anything contenteditable, and the space is typed as normal.
+//   ctrl-space   Brave takes it for the address bar, at the browser level. Tried twice, on the theory that
+//                preventDefault would win. It does not — the key never reaches this handler.
+//   alt-space    the GNOME window menu. He rebound the desktop to keep it, disliked the replacement, and
+//                would rather move the app than the window manager.
+//   shift-space  where it lands, with BOTH of its stock behaviours deliberately overridden.
 //
-// The cost of that is worth stating: focus usually IS in the chat composer, so opening Spotlight from
-// there means clicking out first. If that turns out to be the common case, a double-tap of shift is the
-// escape hatch — it conflicts with nothing anywhere.
+// ── Shift-space overrides two things, on purpose ──
+//
+// It types a space in a text field, and it scrolls a page UP when nothing has focus. The owner's judgement,
+// and it is his to make: neither is worth a launcher. Page-up-by-shift-space is a fossil nobody reaches for,
+// and typing a space is what the unmodified spacebar is for.
+//
+// The cost, stated once because it is the one that will bite: typing in CAPS by holding shift rather than
+// using caps lock puts a shift-space between every word. That opens the launcher mid-sentence. If it turns
+// out to be a nuisance, the fix is a guard for text fields only — which this had for a day, and which is
+// what made the launcher unopenable from the composer, where it is most wanted.
+//
+// This is also why the ctrl+? registry names the file that implements each chord: five moves in three days
+// is the argument for making them configurable, not for choosing better.
+//
+// **Shift-space was never a good choice**, and that is why it did not last a day. It is a real key
+// combination inside a text field: it types a space, and people hold shift through one more often than
+// they think while typing capitals. Guarding it meant IGNORING the trigger whenever focus was in an input
+// — which is where focus usually is, the chat composer — so opening Spotlight meant clicking out first.
+// A launcher you have to prepare for is not a launcher.
+//
+// There is NO focus check, and here that is a choice with a cost rather than a free one — see above. The guard shift-space
+// needed was kept for one commit as "belt-and-braces" and was simply the old bug wearing a new hat: focus
+// is usually in the chat composer, so a launcher that stands down there is a launcher that does not open
+// when you want it. `preventDefault` on the handler covers the only real risk the guard addressed.
+//
+// Nothing else opens it. There is deliberately no second chord — two triggers for one thing means two
+// things to collide with, and this one moved twice already.
 //
 // Escape closes, arrows move, enter goes. The mouse works, but nothing here is designed around it.
+//
+// ── Sizing ──
+//
+// Loosened 2026-08-22: the first pass reused the app's list metrics (7px tile, text-sm, py-2) and read as
+// cramped, because this is not a list inside a panel — it is a modal you look at for two seconds with
+// nothing else competing for the eye. So the search input leads at `text-base`, rows are `py-2.5` with a
+// 9px tile, and the label is `text-[15px]` with the hint and path kept deliberately subordinate.
+//
+// The panel widened with them (560 → 640). Rows now carry a label, a hint and a route on one line, and the
+// route is the first thing to be squeezed out — it is also the thing that disambiguates two rows with the
+// same name.
+//
+// The results box grew 52vh → 60vh for the arithmetic reason: taller rows in the same box show fewer
+// results, and the cap on how many are listed was removed for a reason.
 
 /*
   No cap, deliberately, and it used to be 8.
@@ -38,19 +77,6 @@ import { useSpotlightItems, type SpotlightItem } from './useSpotlightItems';
   cap becomes indistinguishable from a missing feature.
 */
 
-/**
- * Is the user typing into something?
- *
- * `shift-space` types a space in any text field, so the trigger has to stand down there or it eats a
- * keystroke people make by accident all day. `isContentEditable` covers the editor and any rich input a
- * panel brings with it.
- */
-function isTyping(target: EventTarget | null): boolean {
-  const el = target as HTMLElement | null;
-  if (!el || !el.tagName) return false;
-  return el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable === true;
-}
-
 /** Label with the matched characters picked out, so it is obvious WHY a result is here. */
 const Highlighted = ({ label, hits }: { label: string; hits: number[] }) => {
   if (!hits.length) return <>{label}</>;
@@ -98,7 +124,7 @@ const Row = ({
         ev.preventDefault();
         onPick();
       }}
-      className={`flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors ${
+      className={`flex w-full items-center gap-3.5 rounded-lg px-3.5 py-2.5 text-left transition-colors ${
         active ? 'bg-accent' : 'hover:bg-accent/50'
       }`}
     >
@@ -116,7 +142,7 @@ const Row = ({
         it put a coloured pane behind Calendar, Contacts and every plugin logo.
       */}
       <span
-        className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md"
+        className="flex h-9 w-9 shrink-0 items-center justify-center rounded-md"
         style={{
           background: item.tile === 'bare' ? 'transparent' : (item.color ?? 'transparent'),
           // No colour at all is a settings row: keep the muted glyph rather than inventing a swatch.
@@ -130,18 +156,20 @@ const Row = ({
             className={item.tile === 'bare' ? 'h-full w-full object-contain' : 'h-5 w-5 object-contain'}
           />
         ) : Icon ? (
-          <Icon className={`h-4 w-4 ${item.color ? '' : 'text-muted-foreground'}`} />
+          <Icon className={`h-[18px] w-[18px] ${item.color ? '' : 'text-muted-foreground'}`} />
         ) : (
-          <Search className="h-4 w-4 text-muted-foreground" />
+          <Search className="h-[18px] w-[18px] text-muted-foreground" />
         )}
       </span>
       <span className="min-w-0 flex-1">
-        <span className="block truncate text-sm text-foreground">
+        <span className="block truncate text-[15px] leading-snug text-foreground">
           <Highlighted label={item.label} hits={hits} />
         </span>
-        {item.hint ? <span className="block truncate text-xs text-muted-foreground">{item.hint}</span> : null}
+        {item.hint ? (
+          <span className="block truncate text-[13px] leading-snug text-muted-foreground">{item.hint}</span>
+        ) : null}
       </span>
-      <span className="shrink-0 font-mono text-[10px] text-muted-foreground/60">{item.to}</span>
+      <span className="shrink-0 font-mono text-[11px] text-muted-foreground/60">{item.to}</span>
     </button>
   );
 };
@@ -156,6 +184,19 @@ export const Spotlight = () => {
 
   const results = useMemo(() => rank(items, query), [items, query]);
 
+  /*
+    The window handler reads these through refs.
+
+    It has to: the listener is registered once per open, and closing over `results` and `active` would pin
+    it to their values at registration — so arrowing down would read a stale list and Enter would open
+    whatever was first when the panel appeared. Adding them to the effect's deps instead would tear down and
+    re-register the listener on every keystroke, which is the same bug wearing a costume.
+  */
+  const resultsRef = useRef(results);
+  resultsRef.current = results;
+  const activeRef = useRef(active);
+  activeRef.current = active;
+
   const close = useCallback(() => {
     setOpen(false);
     setQuery('');
@@ -175,16 +216,51 @@ export const Spotlight = () => {
   // anywhere — including inside a panel that has its own key handling.
   useEffect(() => {
     const onKey = (ev: KeyboardEvent) => {
-      if (ev.shiftKey && ev.code === 'Space' && !isTyping(ev.target)) {
+      // `code`, not `key`: shift+space reports `key: ' '` on most layouts and something else on a few, while
+      // the physical key is `Space` everywhere.
+      //
+      // Every other modifier must be ABSENT. `ctrl+shift+space` is the theme browser, and one chord opening
+      // both is the bug that took a capture-phase listener to fix on the theme side.
+      //
+      // No focus check. There was one, inherited from shift-space where it was mandatory, and keeping it
+      // "as belt-and-braces" was wrong in the plainest way: focus is usually IN the chat composer, so the
+      // guard meant the launcher did not open from the place it is most often wanted. `preventDefault`
+      // below covers the only thing the guard was protecting against — a layout that would otherwise type
+      // a character.
+      if (ev.shiftKey && !ev.ctrlKey && !ev.altKey && !ev.metaKey && ev.code === 'Space') {
         ev.preventDefault();
+        // Take focus off whatever had it, explicitly, before the overlay mounts. The effect below focuses
+        // this panel's own input, and on paper that is enough — but "on paper" is what produced arrow keys
+        // that sometimes did nothing: focus stayed in the composer, so ArrowDown went to the textarea and
+        // the launcher never saw it. Blurring the outgoing element is one line and removes the race rather
+        // than narrowing it.
+        (document.activeElement as HTMLElement | null)?.blur?.();
         setOpen((wasOpen) => !wasOpen);
         return;
       }
-      if (ev.key === 'Escape' && open) close();
+      if (!open) return;
+      if (ev.key === 'Escape') {
+        close();
+        return;
+      }
+      // Navigation is handled HERE rather than on the input, so it works no matter what has focus — a
+      // panel that grabbed it back, a blur that lost the race, an element with its own key handling. The
+      // input's own onKeyDown used to own this, which made every keystroke conditional on focus having
+      // landed where we expected.
+      if (ev.key === 'ArrowDown') {
+        ev.preventDefault();
+        setActive((i) => Math.min(i + 1, resultsRef.current.length - 1));
+      } else if (ev.key === 'ArrowUp') {
+        ev.preventDefault();
+        setActive((i) => Math.max(i - 1, 0));
+      } else if (ev.key === 'Enter') {
+        ev.preventDefault();
+        pick(resultsRef.current[activeRef.current]?.item);
+      }
     };
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
-  }, [open, close]);
+  }, [open, close, pick]);
 
   useEffect(() => {
     if (open) inputRef.current?.focus();
@@ -201,34 +277,22 @@ export const Spotlight = () => {
       onMouseDown={close}
     >
       <div
-        className="w-[min(92vw,560px)] overflow-hidden rounded-2xl border border-border bg-background/95 shadow-2xl"
+        className="w-[min(92vw,640px)] overflow-hidden rounded-2xl border border-border bg-background/95 shadow-2xl"
         // The backdrop closes on mousedown; this stops a click INSIDE the panel counting as one.
         onMouseDown={(ev) => ev.stopPropagation()}
       >
         <div className="flex items-center gap-2 border-b border-border px-4">
-          <Search className="h-4 w-4 shrink-0 text-muted-foreground" />
+          <Search className="h-5 w-5 shrink-0 text-muted-foreground" />
           <input
             ref={inputRef}
             value={query}
             onChange={(ev) => setQuery(ev.target.value)}
-            onKeyDown={(ev) => {
-              if (ev.key === 'ArrowDown') {
-                ev.preventDefault();
-                setActive((i) => Math.min(i + 1, results.length - 1));
-              } else if (ev.key === 'ArrowUp') {
-                ev.preventDefault();
-                setActive((i) => Math.max(i - 1, 0));
-              } else if (ev.key === 'Enter') {
-                ev.preventDefault();
-                pick(results[active]?.item);
-              }
-            }}
             placeholder="Go to…"
-            className="w-full bg-transparent py-3.5 text-sm text-foreground outline-none placeholder:text-muted-foreground"
+            className="w-full bg-transparent py-4 text-base text-foreground outline-none placeholder:text-muted-foreground"
           />
         </div>
 
-        <div className="max-h-[52vh] overflow-y-auto p-2">
+        <div className="max-h-[60vh] overflow-y-auto p-2">
           {results.length === 0 ? (
             <p className="px-3 py-6 text-center text-sm text-muted-foreground">Nothing matches “{query}”.</p>
           ) : (

src/apps/officer-web/Screens/Dashboard/Minesweeper/MinesweeperScreen.tsx

@@ -0,0 +1,20 @@
+import type { LayoutNode } from 'officerdev';
+import { WorkspaceView } from 'officerdev';
+import { useDashboardState } from 'state/useDashboardState';
+import { defaultLayout } from './defaultLayout';
+
+// /minesweeper — Minesweeper X running under wine on a virtual display, streamed over RFB.
+//
+// The pixels arrive through /api/minesweeper/ws, which is a byte relay onto x11vnc's own TCP socket on
+// loopback — the same shape as the terminal's relay onto the pty sidecar, and the reason this works at
+// all where `plugins/desktop` could not: a websocket provider is a platform concern, and a plugin
+// cannot claim one.
+//
+// Owner-only, and not because a game is dangerous: wine runs as the server owner, so the game's menus
+// are file dialogs with the owner's home behind them.
+
+export const MinesweeperScreen = () => {
+  const workspace = useDashboardState<LayoutNode>('screens/minesweeper', defaultLayout);
+
+  return <WorkspaceView workspace={workspace} locked appTypes={{ allowed: ['minesweeper'], fallback: 'minesweeper' }} />;
+};

src/apps/officer-web/Screens/Dashboard/Minesweeper/defaultLayout.ts

@@ -0,0 +1,9 @@
+import type { LayoutNode } from 'officerdev';
+
+// One panel. The board is 152x214 and there is nothing to put beside it — a split here would be a
+// second panel of empty space.
+export const defaultLayout: LayoutNode = {
+  type: 'panel',
+  id: 'minesweeper',
+  appType: 'minesweeper',
+};

src/apps/officer-web/Screens/Dashboard/Minesweeper/index.tsx

@@ -0,0 +1 @@
+export * from './MinesweeperScreen';

src/apps/officer-web/Screens/Dashboard/SendOff/SendOffScreen.tsx

@@ -0,0 +1,16 @@
+import type { LayoutNode } from 'officerdev';
+import { WorkspaceView } from 'officerdev';
+import { useDashboardState } from 'state/useDashboardState';
+import { defaultLayout } from './defaultLayout';
+
+// /sendoff — pick files, pick a machine of your own or a person who has allowed you, send.
+//
+// There is no receiving half. Files land in `Documents/SendOff/` inside the recipient's own tree, so the
+// file browser already IS the inbox — and a second view of the same directory would be a worse copy of
+// one that already works, kept in sync by hand.
+
+export const SendOffScreen = () => {
+  const workspace = useDashboardState<LayoutNode>('screens/sendoff', defaultLayout);
+
+  return <WorkspaceView workspace={workspace} locked appTypes={{ allowed: ['sendoff'], fallback: 'sendoff' }} />;
+};

src/apps/officer-web/Screens/Dashboard/SendOff/defaultLayout.ts

@@ -0,0 +1,9 @@
+import type { LayoutNode } from 'officerdev';
+
+// One panel. The form is a column and there is nothing to put beside it — receiving already has a UI,
+// which is the file browser.
+export const defaultLayout: LayoutNode = {
+  type: 'panel',
+  id: 'sendoff',
+  appType: 'sendoff',
+};

src/apps/officer-web/Screens/Dashboard/SendOff/index.tsx

@@ -0,0 +1 @@
+export * from './SendOffScreen';

src/apps/officer-web/Screens/Dashboard/Settings/ProfileSettings/Languages.tsx

@@ -3,6 +3,7 @@ import { X } from 'lucide-react';
 import { Label } from '@/components/ui/label';
 import { useSettings } from 'state/useSettings';
 import { useTranslation } from '@/lib/i18n';
+import { SHIPPED_LOCALES } from '@/lib/locales';
 
 const LANGUAGES = [
   { code: 'en', label: 'English' },
@@ -56,7 +57,8 @@ export const Languages = () => {
   const removeSpoken = (code: string) => {
     const next = spoken.filter((s) => s !== code);
     const updates = { ...settings.languages, spoken: next };
-    if (defaultLang === code) updates.default = next[0] ?? 'en';
+    // `default` (UI localization) draws from SHIPPED_LOCALES, not `spoken` — removing a spoken
+    // language never leaves it without a valid value.
     if (translateTo === code) updates.translateTo = next[0] ?? 'en';
     save(updates);
   };
@@ -104,7 +106,7 @@ export const Languages = () => {
         )}
       </div>
 
-      {/* Default language */}
+      {/* Default language — UI localization, so it only offers locales that actually ship (D2) */}
       <Label className="grid gap-2">
         <span className="text-duck-dark/70">{t('settings.profile.languages.defaultLabel')}</span>
         <select
@@ -112,9 +114,9 @@ export const Languages = () => {
           onChange={(ev) => save({ ...settings.languages, default: ev.target.value })}
           className="text-sm border border-duck-dark/20 rounded-md px-3 py-2 bg-background/60 text-duck-dark cursor-pointer"
         >
-          {spoken.map((code) => (
+          {SHIPPED_LOCALES.map(({ code, label }) => (
             <option key={code} value={code}>
-              {getLabel(code)}
+              {label}
             </option>
           ))}
         </select>

src/apps/officer-web/Screens/Dashboard/index.tsx

@@ -22,3 +22,5 @@ export * from './Dashboards';
 export * from './Terminal';
 export * from './Jobs';
 export * from './QrTransfer';
+export * from './Minesweeper';
+export * from './SendOff';

src/apps/officer-web/lib/I18nBridge.tsx

@@ -1,11 +1,30 @@
+import { useEffect } from 'react';
 import type { ReactNode } from 'react';
 import type { TranslationMap } from 'i18n';
-import { I18nProvider } from 'i18n';
+import { I18nProvider, localeDirection } from 'i18n';
+import { panelCatalogs } from 'officerdev';
+import { uiCatalogs } from '@/components/locales';
 import { useSettings } from 'state/useSettings';
-import en from '../locales/en.json';
-import pt from '../locales/pt.json';
+import { FALLBACK_LOCALE, SHIPPED_LOCALES } from './locales';
+import appEnGB from '../locales/en-GB.json';
+import appPtPT from '../locales/pt-PT.json';
 
-const translations: TranslationMap = { en, pt };
+const appCatalogs: TranslationMap = { 'en-GB': appEnGB, 'pt-PT': appPtPT };
+
+/**
+ * Deep-merges the three per-workspace catalogs (D6) into one map per shipped locale — `app.*` from
+ * officer-web, `panel.*` from officerdev's panel apps, `ui.*` from shared components.
+ */
+const translations: TranslationMap = Object.fromEntries(
+  SHIPPED_LOCALES.map(({ code }) => [
+    code,
+    {
+      app: appCatalogs[code] ?? {},
+      panel: panelCatalogs[code] ?? {},
+      ui: uiCatalogs[code] ?? {},
+    },
+  ]),
+);
 
 type I18nBridgeProps = {
   children: ReactNode;
@@ -15,8 +34,14 @@ export const I18nBridge = ({ children }: I18nBridgeProps) => {
   const { settings } = useSettings();
   const locale = settings.languages.default;
 
+  // Prepared for RTL (D3) — every shipped locale is `ltr` today, but the wiring exists so a future
+  // RTL catalog needs no second pass over the tree.
+  useEffect(() => {
+    document.documentElement.dir = localeDirection(locale);
+  }, [locale]);
+
   return (
-    <I18nProvider translations={translations} locale={locale}>
+    <I18nProvider translations={translations} locale={locale} fallbackLocale={FALLBACK_LOCALE}>
       {children}
     </I18nProvider>
   );

src/apps/officer-web/lib/i18n.ts

@@ -1,12 +1,14 @@
 import type { TranslationKeys } from 'i18n';
 import type { InterpolationParams } from 'i18n';
 import { useTranslation as useTranslationBase } from 'i18n';
-import type en from '../locales/en.json';
+import type en from '../locales/en-GB.json';
 
 type AppTranslationKey = TranslationKeys<typeof en>;
 
+// The `app.` prefix is namespace wiring for the merged catalog (D6) — callers never spell it, they
+// pass the same bare key the JSON file uses.
 export const useTranslation = () => {
   const { t: baseT, locale } = useTranslationBase();
-  const t = (key: AppTranslationKey, params?: InterpolationParams) => baseT(key, params);
+  const t = (key: AppTranslationKey, params?: InterpolationParams) => baseT(`app.${key}`, params);
   return { t, locale };
 };

src/apps/officer-web/lib/locales.ts

@@ -0,0 +1,14 @@
+/**
+ * The UI locales that actually ship — regional BCP 47 tags, per docs/localization.md D2. This is the
+ * one list `I18nBridge` merges catalogs for and `Languages.tsx` offers for UI localization; it is
+ * deliberately separate from the broader "languages you speak" / "translate to" lists, which are a
+ * different feature (see the doc's open question 4) and are not limited to locales with a catalog.
+ */
+export type ShippedLocale = { code: string; label: string };
+
+export const SHIPPED_LOCALES: ShippedLocale[] = [
+  { code: 'en-GB', label: 'English (UK)' },
+  { code: 'pt-PT', label: 'Português (Portugal)' },
+];
+
+export const FALLBACK_LOCALE = 'en-GB';

src/apps/officer-web/locales/parity.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test';
+import { findMissingKeys } from 'i18n';
+import en from './en-GB.json';
+import ptPT from './pt-PT.json';
+
+// D2: every shipped locale ships a COMPLETE catalog. A key en-GB has and pt-PT lacks is a red build,
+// not a warning — there is no regional fallback to paper over the gap.
+describe('officer-web (app.*) locale catalogs', () => {
+  test('pt-PT has every key en-GB has', () => {
+    expect(findMissingKeys(en, { 'pt-PT': ptPT })).toEqual([]);
+  });
+});

src/apps/officer-web/state/shortcuts.ts

@@ -0,0 +1,127 @@
+/*
+  Every keyboard shortcut the shell owns, as data.
+
+  ── Why a registry ──
+
+  Ported in shape from the owner's `vimazing` (`vim-maze/src/gameInfo.ts`), where the controls are declared
+  once and the help screen renders them. The alternative is what this replaced: chords spelled out inside
+  three separate key handlers, and a help text nobody updates because it lives somewhere else.
+
+  Two things follow from having it. `Ctrl+?` can render an accurate list without anybody maintaining prose.
+  And when shortcuts become configurable — the next big piece — this is the table a binding UI edits, rather
+  than a grep across handlers.
+
+  ── What it is NOT, yet ──
+
+  Declarative but not authoritative: the handlers still contain their own conditions, so a chord changed here
+  does not move. Making this the single source is part of the configurable-shortcuts work, and doing it now
+  would mean a rewrite of three handlers for no visible gain. Where a chord appears in both places the file
+  that owns it is named in `implementedIn`, so the pair can be found in one search.
+*/
+
+export type Shortcut = {
+  /** As a person reads it — `Ctrl+Shift+Space`, not a KeyboardEvent spelling. */
+  keys: string;
+  description: string;
+  /** The file whose handler actually implements it, until this registry is authoritative. */
+  implementedIn: string;
+};
+
+export type ShortcutSection = {
+  title: string;
+  /** Shown under the title when the section needs a caveat that a per-row description cannot carry. */
+  note?: string;
+  shortcuts: Shortcut[];
+};
+
+export const SHORTCUT_SECTIONS: ShortcutSection[] = [
+  {
+    title: 'Navigation',
+    shortcuts: [
+      {
+        keys: 'Shift+Space',
+        description: 'Spotlight — go to any screen, plugin or setting by name',
+        implementedIn: 'Layout/Spotlight/Spotlight.tsx',
+      },
+      { keys: 'Ctrl+?', description: 'This list', implementedIn: 'Layout/ShortcutsModal.tsx' },
+    ],
+  },
+  {
+    title: 'Themes',
+    note: 'The browser applies as you move, so you watch the app change rather than reading names.',
+    shortcuts: [
+      {
+        keys: 'Ctrl+Shift+Space',
+        description: 'Open the theme browser',
+        implementedIn: 'theme/useThemeKeys.ts',
+      },
+      {
+        keys: 'Ctrl+Shift+← / →',
+        description: 'Previous / next theme, without opening anything',
+        implementedIn: 'theme/useThemeKeys.ts',
+      },
+      {
+        keys: 'Ctrl+Shift+F',
+        description: 'Star or unstar the current theme, from anywhere',
+        implementedIn: 'theme/useThemeKeys.ts',
+      },
+    ],
+  },
+  {
+    title: 'In the theme browser',
+    shortcuts: [
+      { keys: 'j / k  ↑ / ↓', description: 'Move through the list', implementedIn: 'theme/useThemeKeys.ts' },
+      {
+        keys: 'l  →',
+        description: 'Apply the focused theme and keep browsing',
+        implementedIn: 'theme/useThemeKeys.ts',
+      },
+      { keys: 'h  ←', description: 'Put back the theme you started on', implementedIn: 'theme/useThemeKeys.ts' },
+      { keys: 'f', description: 'Star or unstar the focused theme', implementedIn: 'theme/useThemeKeys.ts' },
+      { keys: 'Enter', description: 'Keep what you are looking at', implementedIn: 'theme/useThemeKeys.ts' },
+      { keys: 'Esc', description: 'Cancel and restore', implementedIn: 'theme/useThemeKeys.ts' },
+    ],
+  },
+  {
+    title: 'In Spotlight',
+    shortcuts: [
+      { keys: '↑ / ↓', description: 'Move through the results', implementedIn: 'Layout/Spotlight/Spotlight.tsx' },
+      { keys: 'Enter', description: 'Go there', implementedIn: 'Layout/Spotlight/Spotlight.tsx' },
+      { keys: 'Esc', description: 'Close', implementedIn: 'Layout/Spotlight/Spotlight.tsx' },
+    ],
+  },
+  {
+    title: 'Chat',
+    note: 'Recall only takes the arrow key from an EMPTY composer, and any other key ends a recall — so a draft is never overwritten.',
+    shortcuts: [
+      {
+        keys: '↑ / ↓',
+        description: 'Previous / next prompt you sent, shell-style',
+        implementedIn: 'Chat/EmbeddableChat/useEmbeddableChat.ts',
+      },
+      {
+        keys: 'Enter',
+        description: 'Send · on an empty composer with something queued, send that now',
+        implementedIn: 'Chat/EmbeddableChat/useEmbeddableChat.ts',
+      },
+      { keys: 'Shift+Enter', description: 'Newline', implementedIn: 'Chat/EmbeddableChat/useEmbeddableChat.ts' },
+      {
+        keys: 'Esc',
+        description: 'Stop the turn that is generating',
+        implementedIn: 'Chat/EmbeddableChat/useEmbeddableChat.ts',
+      },
+    ],
+  },
+];
+
+/**
+ * Is this the `Ctrl+?` chord?
+ *
+ * `?` is `Shift+/` on most layouts and its own key on some, so both spellings are accepted rather than
+ * guessing which keyboard is attached. `code === 'Slash'` is the physical key, which is stable where `key`
+ * is not.
+ */
+export function isShortcutsChord(ev: KeyboardEvent): boolean {
+  if (!ev.ctrlKey) return false;
+  return ev.key === '?' || (ev.shiftKey && ev.code === 'Slash');
+}

src/apps/officer-web/state/useThemeFavorites.ts

@@ -0,0 +1,55 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useClient } from 'hooks/useClient';
+
+/*
+  Starred themes, per account.
+
+  With 200+ installed, "which of these did I like" is a question the list cannot answer by itself, and the
+  answer belongs to the account rather than to the browser — the same taste follows you to the phone.
+
+  Optimistic, and that is not a nicety here: the star sits in a dropdown you are about to close, so a
+  round trip before the icon fills means the confirmation arrives after the thing it confirms has gone.
+*/
+
+const KEY = ['themes', 'favorites'];
+
+export function useThemeFavorites() {
+  const client = useClient();
+  const queryClient = useQueryClient();
+
+  const query = useQuery<{ favorites: string[] }>({
+    queryKey: KEY,
+    queryFn: () => client.get<{ favorites: string[] }>('/theme-favorites'),
+    // Taste does not change while you look at it, and the mutation below keeps the cache honest.
+    staleTime: 5 * 60_000,
+    refetchOnWindowFocus: false,
+    retry: false,
+  });
+
+  const toggle = useMutation({
+    mutationFn: ({ themeId, favorite }: { themeId: string; favorite: boolean }) =>
+      client.put<{ themeId: string; favorite: boolean }>(`/theme-favorites/${themeId}`, { favorite }),
+    onMutate: async ({ themeId, favorite }) => {
+      await queryClient.cancelQueries({ queryKey: KEY });
+      const previous = queryClient.getQueryData<{ favorites: string[] }>(KEY);
+      const current = previous?.favorites ?? [];
+      queryClient.setQueryData(KEY, {
+        favorites: favorite ? [...new Set([...current, themeId])] : current.filter((id) => id !== themeId),
+      });
+      return { previous };
+    },
+    // Put it back on failure. A star that stayed filled after the write was refused is worse than one that
+    // never filled: it reports a preference the server does not hold.
+    onError: (_err, _vars, context) => {
+      if (context?.previous) queryClient.setQueryData(KEY, context.previous);
+    },
+  });
+
+  const favorites = new Set(query.data?.favorites ?? []);
+
+  return {
+    favorites,
+    isFavorite: (themeId: string) => favorites.has(themeId),
+    toggle: (themeId: string) => toggle.mutate({ themeId, favorite: !favorites.has(themeId) }),
+  };
+}

src/databases/officer_db/src/chat-session-cleanup.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { inArray } from 'drizzle-orm';
+import { db } from './db';
+import { chatSessionEvents } from './chat-events/schema';
+import { chatSessionModels } from './chat-session-models/schema';
+import { forgetChatSessions } from './chat-session-cleanup';
+
+/*
+  Deleting a conversation, across the two id spaces it actually spans.
+
+  This file touches the real database, which the rest of the suite avoids on purpose. It has to: the defect
+  it exists to catch was never in a decision, it was in which column a `delete` matched. A test built on a
+  fake store would have passed against both the broken version and the fixed one.
+
+  Safe because every id here is a synthetic uuid in a reserved block that no harness produces, and because
+  each test removes exactly what it wrote. Nothing reads live rows and nothing deletes by anything but these
+  ids.
+
+  Two regressions are pinned here, and they are the same bug seen twice:
+
+  1. `chat_session_events` is keyed on officer's SESSION KEY while everything else is keyed on the TRANSCRIPT
+     id. One list passed to all four tables matched nothing in this one, ever, by construction — and counting
+     events by transcript id to check also returns zero by construction, so it read as clean.
+  2. Resolving that key from a live in-memory map only works for a session younger than the process. After a
+     restart it comes back null, the key list arrives empty, and the events survive a delete that reports
+     success. The key has to come from the rows, which carry `claudeSessionId` in their payload.
+*/
+
+const TRANSCRIPT = '00000000-dead-4000-8000-000000000001';
+const SESSION_KEY = '00000000-dead-4000-8000-0000000000ff';
+
+afterEach(async () => {
+  await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, [SESSION_KEY]));
+  await db.delete(chatSessionModels).where(inArray(chatSessionModels.sessionId, [TRANSCRIPT]));
+});
+
+const countEvents = async () =>
+  (
+    await db
+      .select()
+      .from(chatSessionEvents)
+      .where(inArray(chatSessionEvents.sessionId, [SESSION_KEY]))
+  ).length;
+
+describe('forgetChatSessions', () => {
+  test('removes events keyed on the session key, found via the transcript id in their payload', async () => {
+    // Exactly the real shape: one `result` carries both ids, the rest carry neither.
+    await db.insert(chatSessionEvents).values([
+      { sessionId: SESSION_KEY, event: { type: 'result', sessionId: SESSION_KEY, claudeSessionId: TRANSCRIPT } },
+      { sessionId: SESSION_KEY, event: { type: 'assistant:text', text: 'no ids on this one' } },
+      { sessionId: SESSION_KEY, event: { type: 'tool:start', toolName: 'Bash' } },
+    ]);
+    expect(await countEvents()).toBe(3);
+
+    // No `sessionKeys` — this is the post-restart case, where the caller cannot resolve one.
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT] });
+
+    // All three, not just the one carrying the id: resolving the key covers the whole session.
+    expect(await countEvents()).toBe(0);
+  });
+
+  test('an explicit session key still works when no event names the transcript', async () => {
+    await db
+      .insert(chatSessionEvents)
+      .values([{ sessionId: SESSION_KEY, event: { type: 'assistant:text', text: 'nothing identifying here' } }]);
+
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT], sessionKeys: [SESSION_KEY] });
+    expect(await countEvents()).toBe(0);
+  });
+
+  test('leaves another session alone', async () => {
+    const OTHER = '00000000-dead-4000-8000-0000000000ee';
+    await db
+      .insert(chatSessionEvents)
+      .values([{ sessionId: OTHER, event: { type: 'assistant:text', text: 'theirs' } }]);
+    try {
+      await forgetChatSessions({ transcriptIds: [TRANSCRIPT], sessionKeys: [SESSION_KEY] });
+      const left = await db
+        .select()
+        .from(chatSessionEvents)
+        .where(inArray(chatSessionEvents.sessionId, [OTHER]));
+      expect(left.length).toBe(1);
+    } finally {
+      await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, [OTHER]));
+    }
+  });
+
+  test('forgets the transcript-keyed tables too', async () => {
+    await db.insert(chatSessionModels).values({ sessionId: TRANSCRIPT, model: 'claude-code/opus', planMode: false });
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT] });
+    const left = await db
+      .select()
+      .from(chatSessionModels)
+      .where(inArray(chatSessionModels.sessionId, [TRANSCRIPT]));
+    expect(left.length).toBe(0);
+  });
+});

src/databases/officer_db/src/chat-session-cleanup.ts

@@ -0,0 +1,113 @@
+import { eq, inArray, sql } from 'drizzle-orm';
+import { db } from './db';
+import { chatSessionEvents } from './chat-events/schema';
+import { chatNotificationPrefs } from './chat-notification-prefs/schema';
+import { chatSessionModels } from './chat-session-models/schema';
+import { nudges } from './nudges/schema';
+
+/*
+  Everything the platform stores ABOUT a conversation, forgotten together.
+
+  ── Why this exists as one function ──
+
+  Four tables describe a conversation, and none has a foreign key to anything, because the thing they
+  describe is a FILE — a transcript on disk, written by the harness. There is no row for a chat session to
+  reference, so the database cannot cascade and the delete path has to be explicit.
+
+  It was not. Deleting a conversation removed the transcript and left all four behind, for ever. Found on
+  2026-08-22 by counting rows after two commanders were deleted through the UI: `chat_session_models` held 36
+  rows against far fewer live conversations.
+
+  ── Why it is more than untidy ──
+
+  Three of the four are inert — a model, a bell preference, a durable copy of turn output that nothing will
+  ask for again. `nudges` is not: it is a SCHEDULE, and the tick in `nudger.ts` reads it. A nudge left behind
+  by a deleted conversation is a timer that keeps firing at something that does not exist.
+
+  ── TWO id spaces, and this is where they were confused ──
+
+  Three of these tables are keyed on the TRANSCRIPT id — the harness's uuid, which is also the filename.
+  `chat_session_events` is keyed on officer's own SESSION KEY, which is a different uuid for the same
+  conversation. Its rows carry both (`{sessionId, claudeSessionId}`), which is how the mismatch was finally
+  proved rather than argued.
+
+  This function used to take one list and pass it to all four. So the events delete matched nothing, ever —
+  not sometimes, by construction — and a deleted conversation left its entire durable output behind. The
+  verification missed it twice, because counting events BY TRANSCRIPT ID also returns zero by construction,
+  and zero read as "cleaned". Found 2026-08-22 by reading an orphaned event payload instead of counting it.
+
+  The parameter is named for its id space so a caller cannot pass the wrong one without writing the wrong
+  word. That is the entire defence: nothing else about the two distinguishes them, since both are uuids.
+
+  ── Why each takes a list ──
+
+  A `/clear` chain is several transcripts presenting as one conversation, and deleting it deletes every part.
+  Forgetting one id and leaving its siblings is the same bug at a smaller scale, so the caller passes the ids
+  it actually removed.
+*/
+type ForgetChatSessionsParams = {
+  /** Harness transcript uuids — the filenames that were removed, including every part of a `/clear` chain. */
+  transcriptIds: string[];
+  /**
+   * Officer's session keys for the same conversations, for `chat_session_events` alone.
+   *
+   * Empty is legitimate and common: a session spawned by `claude -p` outside officer's websocket never had a
+   * key and never wrote an event, which is exactly the case for a commander's children.
+   */
+  sessionKeys?: string[];
+};
+
+export async function forgetChatSessions({ transcriptIds, sessionKeys = [] }: ForgetChatSessionsParams): Promise<void> {
+  // Sequential rather than a transaction: these are independent tables with no invariant between them, and
+  // a partial forget is strictly better than a failed delete that leaves the transcript gone and every row
+  // in place. Each is idempotent — running it twice removes nothing the second time.
+  if (transcriptIds.length) {
+    await db.delete(nudges).where(inArray(nudges.sessionId, transcriptIds));
+    await db.delete(chatSessionModels).where(inArray(chatSessionModels.sessionId, transcriptIds));
+    await db.delete(chatNotificationPrefs).where(inArray(chatNotificationPrefs.sessionId, transcriptIds));
+  }
+  /*
+    Events, resolved from the table's OWN data rather than from the caller's key.
+
+    `sessionKeys` is a fast path and not a reliable one: the caller gets it from an in-memory map that is
+    empty for any session created before the last restart, so the first real test of this deleted everything
+    except the events — the key came back null and the list was empty. A cleanup that only works for
+    conversations younger than the process is not a cleanup.
+
+    So ask the rows. Every event carries `claudeSessionId` in its payload, which is durable, survives any
+    restart, and is the one place the two id spaces are written down together. One id inside the JSON is
+    enough to resolve the key for all of that session's rows, including the events that carry no id of their
+    own — which is most of them.
+  */
+  if (transcriptIds.length) {
+    const keysFromEvents = await db
+      .selectDistinct({ sessionId: chatSessionEvents.sessionId })
+      .from(chatSessionEvents)
+      .where(inArray(sql`${chatSessionEvents.event}->>'claudeSessionId'`, transcriptIds));
+    const keys = [...new Set([...sessionKeys, ...keysFromEvents.map((r) => r.sessionId)])];
+    if (keys.length) await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, keys));
+  } else if (sessionKeys.length) {
+    await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, sessionKeys));
+  }
+}
+
+/**
+ * Officer's session key for a transcript, read from the durable event log.
+ *
+ * The in-memory maps (`sessionKeyForTranscript`, `findSessionKeyByClaudeSession`) only answer for a session
+ * younger than the process that is asking. After a restart both return undefined, and the delete path then
+ * skips the kill entirely — so the transcript is removed while the harness is still writing it, and the
+ * harness writes it straight back. A deleted commander reappears as an untitled stub.
+ *
+ * Every `result` event carries both ids in its payload, which survives any restart. Same trick as
+ * `forgetChatSessions`, and for the same reason: the rows are the only place the two id spaces are written
+ * down together.
+ */
+export async function sessionKeyForTranscriptId(transcriptId: string): Promise<string | undefined> {
+  const [row] = await db
+    .select({ sessionId: chatSessionEvents.sessionId })
+    .from(chatSessionEvents)
+    .where(eq(sql`${chatSessionEvents.event}->>'claudeSessionId'`, transcriptId))
+    .limit(1);
+  return row?.sessionId;
+}

src/databases/officer_db/src/command-hq/index.ts

@@ -14,6 +14,8 @@ export {
   recordCommandHqWatcherFired,
   disarmCommandHqWatcher,
   recordCommandHqTurn,
+  ingestSpawnedChildren,
+  recordSpawnedOutcome,
   getCommandHqCostSummary,
   listCommandHqTurns,
   listCommandHqWatcherFires,

src/databases/officer_db/src/command-hq/queries.ts

@@ -7,6 +7,7 @@ import {
   commandHqTags,
   commandHqTurns,
   commandHqWatcherFires,
+  commandHqSpawned,
 } from './schema';
 
 // ── Categories ──
@@ -54,6 +55,8 @@ export async function deleteCommandHqCategory(userId: number, id: number): Promi
 export type CommandHqSessionRow = {
   id: number;
   sessionId: string;
+  /** What the owner called it. Null for rows filed before the column existed — fall back to the transcript. */
+  name: string | null;
   categoryId: number | null;
   watcherArmed: boolean;
   watcherTaskId: string | null;
@@ -66,6 +69,7 @@ export type CommandHqSessionRow = {
 const SESSION_ROW_COLUMNS = {
   id: commandHqSessions.id,
   sessionId: commandHqSessions.sessionId,
+  name: commandHqSessions.name,
   categoryId: commandHqSessions.categoryId,
   watcherArmed: commandHqSessions.watcherArmed,
   watcherTaskId: commandHqSessions.watcherTaskId,
@@ -83,10 +87,11 @@ export async function createCommandHqSession(
   userId: number,
   sessionId: string,
   categoryId: number | null = null,
+  name: string | null = null,
 ): Promise<CommandHqSessionRow> {
   const [row] = await db
     .insert(commandHqSessions)
-    .values({ userId, sessionId, categoryId })
+    .values({ userId, sessionId, categoryId, name })
     .onConflictDoNothing({ target: [commandHqSessions.userId, commandHqSessions.sessionId] })
     .returning(SESSION_ROW_COLUMNS);
   // `onConflictDoNothing` returns nothing on the conflict path, so the existing row is fetched explicitly —
@@ -405,3 +410,68 @@ export async function removeCommandHqSessionTag(sessionRowId: number, tagId: num
     .delete(commandHqSessionTags)
     .where(and(eq(commandHqSessionTags.sessionRowId, sessionRowId), eq(commandHqSessionTags.tagId, tagId)));
 }
+
+/*
+  Spawned children. The file is the inbox; these rows are the record — see the schema note.
+*/
+
+export type SpawnedChild = {
+  spawnedSessionId: string;
+  firstSeenAt: string;
+  finishedAt: string | null;
+  totalUsd: number | null;
+  outcome: string | null;
+};
+
+/**
+ * Ingest ids the loop appended, idempotently, and return the commander's children.
+ *
+ * One statement for the insert because the loop can repeat itself after a restart, so a duplicate append is
+ * expected rather than exceptional. `onConflictDoNothing` on the unique index makes re-ingesting the whole
+ * file cost nothing and change nothing, which is what lets the caller ingest on every read instead of
+ * running a cron that can silently stop.
+ */
+export async function ingestSpawnedChildren(sessionRowId: number, ids: string[]): Promise<SpawnedChild[]> {
+  if (ids.length) {
+    await db
+      .insert(commandHqSpawned)
+      .values(ids.map((spawnedSessionId) => ({ sessionRowId, spawnedSessionId })))
+      .onConflictDoNothing();
+  }
+  const rows = await db
+    .select()
+    .from(commandHqSpawned)
+    .where(eq(commandHqSpawned.sessionRowId, sessionRowId))
+    .orderBy(commandHqSpawned.firstSeenAt);
+  return rows.map((r) => ({
+    spawnedSessionId: r.spawnedSessionId,
+    firstSeenAt: r.firstSeenAt.toISOString(),
+    finishedAt: r.finishedAt?.toISOString() ?? null,
+    totalUsd: r.totalUsd,
+    outcome: r.outcome,
+  }));
+}
+
+/**
+ * What a child cost, once something knows.
+ *
+ * Separate from the ingest because the two facts arrive at different times from different parties: the loop
+ * knows the id at spawn, and only the child knows what it cost when it exits. Null cost stays null — an
+ * unknown total must not be reported as zero.
+ */
+export async function recordSpawnedOutcome(
+  sessionRowId: number,
+  spawnedSessionId: string,
+  outcome: { totalUsd?: number | null; outcome?: string | null },
+): Promise<void> {
+  await db
+    .update(commandHqSpawned)
+    .set({
+      finishedAt: new Date(),
+      ...(outcome.totalUsd === undefined ? {} : { totalUsd: outcome.totalUsd }),
+      ...(outcome.outcome === undefined ? {} : { outcome: outcome.outcome }),
+    })
+    .where(
+      and(eq(commandHqSpawned.sessionRowId, sessionRowId), eq(commandHqSpawned.spawnedSessionId, spawnedSessionId)),
+    );
+}

src/databases/officer_db/src/command-hq/schema.ts

@@ -86,6 +86,18 @@ export const commandHqSessions = pgTable(
      * id spaces both agree on only sometimes.
      */
     sessionId: text('session_id').notNull(),
+    /**
+     * What the owner called it, held here rather than only in the transcript's summary record.
+     *
+     * The summary is the harness's, and it can only be written once the transcript file exists — which is
+     * after the first turn. So a list reading the transcript showed the opening brief until that turn ended,
+     * while the header beside it showed the name from local state. Two names for one commander, and every
+     * fix for it was a cache-invalidation trick timed against somebody else's write.
+     *
+     * The row is written when the commander is filed, before any of that. Nullable for the rows that predate
+     * this, which fall back to the transcript.
+     */
+    name: text('name'),
     /** Nullable — a commander may be uncategorised. `onDelete: 'set null'`: deleting a category uncategorises its commanders rather than deleting them. */
     categoryId: integer('category_id').references(() => commandHqCategories.id, { onDelete: 'set null' }),
     /** Should the platform keep re-arming this commander's watcher on every fire? See the file docstring. */
@@ -195,3 +207,53 @@ export const commandHqSessionTags = pgTable(
   },
   (table) => [uniqueIndex('uq_command_hq_session_tags').on(table.sessionRowId, table.tagId)],
 );
+
+/**
+ * One row per agent a commander spawned.
+ *
+ * ── Why the database, when the loop writes a file ──
+ *
+ * The file is an INBOX, not the record. A commander's loop is bash: it can append a session id with a shell
+ * redirect and it cannot reach Postgres, and giving it a credential so it could would put an authenticated
+ * writer inside a background job — worse than the problem. So the loop appends, and the platform ingests
+ * into this table whenever anything asks. The file is allowed to be lossy; this is not.
+ *
+ * What the table buys that the file cannot:
+ *
+ *   - the LINK, enforced. `onDelete: 'cascade'` means deleting a commander cannot leave orphaned children
+ *     behind, which is the whole reason this became important.
+ *   - queries. Cost per commander, how many agents a trigger spawned, which ones are still running — none of
+ *     which a newline-delimited file can answer without reading every one.
+ *   - a place for what the loop cannot know at append time: when the child finished, what it cost, whether
+ *     it succeeded. Those arrive later, from the child itself, and a file appended by a shell cannot be
+ *     updated in place.
+ *
+ * ── Why the child's own id is the key and not a serial ──
+ *
+ * Because the same child must not be ingested twice — the file is appended to by a loop that may repeat
+ * itself after a restart, and the ingest is idempotent on `(session_row_id, spawned_session_id)`.
+ */
+export const commandHqSpawned = pgTable(
+  'command_hq_spawned',
+  {
+    id: serial('id').primaryKey(),
+    /** The commander. Cascades: its children go with it, which is the point. */
+    sessionRowId: integer('session_row_id')
+      .notNull()
+      .references(() => commandHqSessions.id, { onDelete: 'cascade' }),
+    /** The child's own transcript id, as the harness wrote it. */
+    spawnedSessionId: text('spawned_session_id').notNull(),
+    /** When the platform first saw it in the inbox — not when the child started, which nothing records. */
+    firstSeenAt: timestamp('first_seen_at', { withTimezone: true }).notNull().defaultNow(),
+    /**
+     * Filled in later, by whoever finds out. Null means unknown rather than zero — a commander whose
+     * children's costs are unknown must not display a confident total that happens to be too low, which is
+     * the failure this table exists to end.
+     */
+    finishedAt: timestamp('finished_at', { withTimezone: true }),
+    totalUsd: doublePrecision('total_usd'),
+    outcome: text('outcome'),
+  },
+  // uniqueIndex, never unique().on() — drizzle-kit re-creates named composite constraints on every push.
+  (table) => [uniqueIndex('uq_command_hq_spawned').on(table.sessionRowId, table.spawnedSessionId)],
+);

src/databases/officer_db/src/index.ts

@@ -38,6 +38,10 @@ export * from './chat-notification-prefs';
 export * from './nudges';
 export * from './ai-provider-usage';
 export * from './anthropic-accounts';
+export * from './theme-favorites';
+export { forgetChatSessions, sessionKeyForTranscriptId } from './chat-session-cleanup';
+export * from './sendoff';
+export * from './roles';
 export * from './command-hq';
 export * from './dashboards';
 export * from './integrations';

src/databases/officer_db/src/roles/index.ts

@@ -0,0 +1,2 @@
+export { roles } from './schema';
+export { listRoles, getRole, seedRole, type RoleRow } from './queries';

src/databases/officer_db/src/roles/queries.ts

@@ -0,0 +1,61 @@
+import { asc, eq, sql } from 'drizzle-orm';
+import { db } from '../db';
+import { users } from '../auth/schema';
+import { roles } from './schema';
+
+export type RoleRow = {
+  name: string;
+  description: string | null;
+  isSystem: boolean;
+  provisioningScript: string | null;
+  createdAt: Date;
+};
+
+/**
+ * Every role, with how many accounts hold each.
+ *
+ * The count is here rather than in a second query because every caller needs it: a picker wants to show
+ * it, and the delete guard is defined in terms of it. One left join beats two round trips and a race
+ * between them.
+ */
+export async function listRoles(): Promise<(RoleRow & { userCount: number })[]> {
+  const rows = await db
+    .select({
+      name: roles.name,
+      description: roles.description,
+      isSystem: roles.isSystem,
+      provisioningScript: roles.provisioningScript,
+      createdAt: roles.createdAt,
+      userCount: sql<number>`count(${users.id})::int`,
+    })
+    .from(roles)
+    .leftJoin(users, eq(users.role, roles.name))
+    .groupBy(roles.name, roles.description, roles.isSystem, roles.provisioningScript, roles.createdAt)
+    .orderBy(asc(roles.name));
+  return rows;
+}
+
+export async function getRole(name: string): Promise<RoleRow | undefined> {
+  const [row] = await db.select().from(roles).where(eq(roles.name, name)).limit(1);
+  return row;
+}
+
+/**
+ * Seed a role if it is not there. Idempotent, and it does NOT overwrite an existing row.
+ *
+ * Called from `postdb:push` on every machine, so it runs again on every schema push for the rest of this
+ * platform's life. An upsert would mean a description edited on one server is silently reverted by the next
+ * deploy — so the seed establishes a row and never touches it again.
+ */
+export async function seedRole(row: {
+  name: string;
+  description?: string | null;
+  isSystem?: boolean;
+}): Promise<boolean> {
+  const inserted = await db
+    .insert(roles)
+    .values({ name: row.name, description: row.description ?? null, isSystem: row.isSystem ?? false })
+    .onConflictDoNothing({ target: roles.name })
+    .returning({ name: roles.name });
+  return inserted.length > 0;
+}

src/databases/officer_db/src/roles/schema.ts

@@ -0,0 +1,52 @@
+import { pgTable, text, boolean, timestamp } from 'drizzle-orm/pg-core';
+
+/**
+ * The roles this server has, as data rather than a TypeScript union.
+ *
+ * ── Why the NAME is the primary key ──
+ *
+ * `users.role` and `role_permissions.role` both hold a role name today, and `authorize.ts` reads a name off
+ * the user to look up grants. Re-keying those onto a serial id would touch the authorization path — the one
+ * file standing between a Member and a shell — to buy nothing the name does not already give, because
+ * Postgres will cascade a rename for us. So both columns become foreign keys onto this one with
+ * `ON UPDATE CASCADE`: renaming a role moves every user and every grant with it, atomically, and no code
+ * changes.
+ *
+ * The cost is that a rename is a data migration rather than a label edit. That is honest — a role name
+ * appears in `rolePermitsDevTools`, in report text and in whatever a plugin has written down.
+ *
+ * ── What is NOT here ──
+ *
+ * **Ownership.** The owner is `OWNER_USER_ID`, an identity, not a role — see `super-admin.ts`. Before this
+ * table existed, "who owns this server" was answered by `users.role === 'Super Admin'`, which meant that
+ * making roles editable would have made "add a role" and "become the owner" the same feature. Several
+ * accounts may now hold `Super Admin`; exactly one account is the owner, and no role grants it.
+ *
+ * **Permissions.** They stay in `role_permissions`, keyed on the name. A role row is the role's identity and
+ * its provisioning, not its grants.
+ */
+export const roles = pgTable('roles', {
+  /** The name, and the key. Referenced by `users.role` and `role_permissions.role` with ON UPDATE CASCADE. */
+  name: text('name').primaryKey(),
+  /** One line, for a picker. Never load-bearing — nothing branches on it. */
+  description: text('description'),
+  /**
+   * A role the platform's own code names, so it cannot be deleted or renamed.
+   *
+   * `rolePermitsDevTools()` tests for `'Developer'` by name, `bootstrap.ts` sets `'Super Admin'`, and the
+   * users table defaults to `'Member'`. Deleting or renaming one of those is not a data change, it is a
+   * code change that has not happened yet — so the delete and rename paths refuse on this flag rather than
+   * discovering it as a runtime failure somewhere else.
+   */
+  isSystem: boolean('is_system').notNull().default(false),
+  /**
+   * Reserved for the per-role provisioning that comes next: a script run when an account is given this
+   * role, so "Developer gets rootless Docker" stops being a special case in `os-user-postgres.ts` and
+   * becomes a row. Null today, and nothing reads it.
+   *
+   * Declared now rather than later on purpose — it is the reason the owner wanted a table at all, and a
+   * column that arrives with the feature that uses it is a second migration for no gain.
+   */
+  provisioningScript: text('provisioning_script'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});

src/databases/officer_db/src/schema.ts

@@ -35,7 +35,10 @@ export * from './chat-session-models/schema'; // chat_session_models
 export * from './chat-notification-prefs/schema'; // chat_notification_prefs
 export * from './ai-provider-usage/schema'; // ai_provider_usage — last usage reading per AI account
 export * from './anthropic-accounts/schema'; // anthropic_accounts — switchable OAuth credentials
+export * from './theme-favorites/schema'; // theme_favorites — starred themes, per account
 export * from './command-hq/schema'; // command_hq_categories, command_hq_sessions, command_hq_tags, command_hq_session_tags
+export * from './sendoff/schema'; // sendoff_devices, sendoff_senders
+export * from './roles/schema'; // roles
 export * from './agent-panels/schema'; // agent_panels
 
 // Core because the tailnet is the perimeter — a security model resting on it cannot treat administering

src/databases/officer_db/src/sendoff/index.ts

@@ -0,0 +1,16 @@
+export { sendoffDevices, sendoffSenders } from './schema';
+export {
+  upsertSendoffDevice,
+  listSendoffDevices,
+  renameSendoffDevice,
+  deleteSendoffDevice,
+  listAllowedSenders,
+  listMyRecipients,
+  listOtherAccounts,
+  allowSender,
+  revokeSender,
+  maySendTo,
+  accountsByIds,
+  type SendoffDevice,
+  type SendoffPerson,
+} from './queries';

src/databases/officer_db/src/sendoff/queries.ts

@@ -0,0 +1,122 @@
+import { and, eq, inArray } from 'drizzle-orm';
+import { db } from '../db';
+import { users } from '../auth/schema';
+import { sendoffDevices, sendoffSenders } from './schema';
+
+export type SendoffDevice = { id: string; name: string; platform: string | null; lastSeenAt: Date };
+
+/**
+ * Register or refresh a device. Called on every app start, so it must be idempotent on the client's own id.
+ *
+ * `lastSeenAt` is refreshed on conflict and the name is overwritten, because the client is the authority on
+ * what it calls itself — renaming on the device should show up in the picker without a second endpoint.
+ */
+export async function upsertSendoffDevice(params: {
+  id: string;
+  userId: number;
+  name: string;
+  platform?: string | null;
+}): Promise<void> {
+  await db
+    .insert(sendoffDevices)
+    .values({
+      id: params.id,
+      userId: params.userId,
+      name: params.name,
+      platform: params.platform ?? null,
+    })
+    .onConflictDoUpdate({
+      target: sendoffDevices.id,
+      set: { name: params.name, platform: params.platform ?? null, lastSeenAt: new Date() },
+    });
+}
+
+export async function listSendoffDevices(userId: number): Promise<SendoffDevice[]> {
+  const rows = await db
+    .select({
+      id: sendoffDevices.id,
+      name: sendoffDevices.name,
+      platform: sendoffDevices.platform,
+      lastSeenAt: sendoffDevices.lastSeenAt,
+    })
+    .from(sendoffDevices)
+    .where(eq(sendoffDevices.userId, userId));
+  return rows;
+}
+
+/** Scoped to the owner of the row: a device id is a client-chosen uuid and must not be a way to reach another account's. */
+export async function renameSendoffDevice(userId: number, id: string, name: string): Promise<boolean> {
+  const rows = await db
+    .update(sendoffDevices)
+    .set({ name })
+    .where(and(eq(sendoffDevices.id, id), eq(sendoffDevices.userId, userId)))
+    .returning({ id: sendoffDevices.id });
+  return rows.length > 0;
+}
+
+export async function deleteSendoffDevice(userId: number, id: string): Promise<boolean> {
+  const rows = await db
+    .delete(sendoffDevices)
+    .where(and(eq(sendoffDevices.id, id), eq(sendoffDevices.userId, userId)))
+    .returning({ id: sendoffDevices.id });
+  return rows.length > 0;
+}
+
+export type SendoffPerson = { id: number; email: string; name: string | null };
+
+/** The accounts I have allowed to send to me. */
+export async function listAllowedSenders(recipientUserId: number): Promise<SendoffPerson[]> {
+  const rows = await db
+    .select({ id: users.id, email: users.email, name: users.name })
+    .from(sendoffSenders)
+    .innerJoin(users, eq(users.id, sendoffSenders.senderUserId))
+    .where(eq(sendoffSenders.recipientUserId, recipientUserId));
+  return rows;
+}
+
+/**
+ * The accounts I may send to — the inverse question, and the one the picker asks.
+ *
+ * Absence denies, so this returns only recipients who have named me. A sender never learns that an account
+ * exists and refused them; it simply is not in the list.
+ */
+export async function listMyRecipients(senderUserId: number): Promise<SendoffPerson[]> {
+  const rows = await db
+    .select({ id: users.id, email: users.email, name: users.name })
+    .from(sendoffSenders)
+    .innerJoin(users, eq(users.id, sendoffSenders.recipientUserId))
+    .where(eq(sendoffSenders.senderUserId, senderUserId));
+  return rows;
+}
+
+/** Every account except me — what the owner's picker shows, since the owner may send to anyone. */
+export async function listOtherAccounts(exceptUserId: number): Promise<SendoffPerson[]> {
+  const rows = await db.select({ id: users.id, email: users.email, name: users.name }).from(users);
+  return rows.filter((r) => r.id !== exceptUserId);
+}
+
+export async function allowSender(recipientUserId: number, senderUserId: number): Promise<void> {
+  await db.insert(sendoffSenders).values({ recipientUserId, senderUserId }).onConflictDoNothing();
+}
+
+export async function revokeSender(recipientUserId: number, senderUserId: number): Promise<void> {
+  await db
+    .delete(sendoffSenders)
+    .where(and(eq(sendoffSenders.recipientUserId, recipientUserId), eq(sendoffSenders.senderUserId, senderUserId)));
+}
+
+/** May this sender write into this recipient's tree? The owner check is the CALLER's job — see the schema. */
+export async function maySendTo(senderUserId: number, recipientUserId: number): Promise<boolean> {
+  const rows = await db
+    .select({ id: sendoffSenders.id })
+    .from(sendoffSenders)
+    .where(and(eq(sendoffSenders.recipientUserId, recipientUserId), eq(sendoffSenders.senderUserId, senderUserId)))
+    .limit(1);
+  return rows.length > 0;
+}
+
+/** Resolve accounts by id, for naming a recipient in a response without a second round trip. */
+export async function accountsByIds(ids: number[]): Promise<SendoffPerson[]> {
+  if (!ids.length) return [];
+  return db.select({ id: users.id, email: users.email, name: users.name }).from(users).where(inArray(users.id, ids));
+}

src/databases/officer_db/src/sendoff/schema.ts

@@ -0,0 +1,55 @@
+import { pgTable, serial, integer, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
+import { users } from '../auth/schema';
+
+/**
+ * A named machine, so "send it to my laptop" has something to pick from.
+ *
+ * Separate from `push_devices` deliberately, and the two are not the same population. A push device is a
+ * token: iOS or Android only, no human name, and it exists to be pushed AT. This is a name a person chose,
+ * for a machine that may never receive a push at all — a desktop, a browser, a box with no app on it. The
+ * name's only job is to become a folder.
+ *
+ * The id is the client's own uuid rather than a serial, because registration happens on every app start and
+ * has to be idempotent without the client remembering a number we gave it.
+ */
+export const sendoffDevices = pgTable('sendoff_devices', {
+  id: text('id').primaryKey(),
+  userId: integer('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  /** What the owner calls it. Becomes a directory name, so it is sanitised before it touches the disk. */
+  name: text('name').notNull(),
+  platform: text('platform'),
+  lastSeenAt: timestamp('last_seen_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+/**
+ * Who may send files to whom — held by the RECIPIENT, one row per sender they have allowed.
+ *
+ * This is the whole cross-user permission model and it is deliberately not a role grant. A grant answers
+ * "may this role send files", which is the wrong question: the person who should decide whether Fedra can
+ * put a file in your home directory is you, not whoever administers roles. So consent is data, it is
+ * per-pair, and absence denies — a sender who has not been allowed does not see the recipient as a target
+ * at all, rather than seeing one and being refused.
+ *
+ * The owner is exempt as a SENDER and only as a sender: they bypass every other check on this platform and
+ * there is no version of this where they cannot reach a home directory they already own. Receiving still
+ * needs their say-so, so nobody lands files in the owner's tree uninvited.
+ */
+export const sendoffSenders = pgTable(
+  'sendoff_senders',
+  {
+    id: serial('id').primaryKey(),
+    /** The account granting permission — the one whose tree gets written to. */
+    recipientUserId: integer('recipient_user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    /** The account allowed to send to them. */
+    senderUserId: integer('sender_user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  // uniqueIndex, never unique().on() — drizzle-kit re-creates named composite constraints on every push.
+  (table) => [uniqueIndex('uq_sendoff_senders').on(table.recipientUserId, table.senderUserId)],
+);

src/databases/officer_db/src/theme-favorites/index.ts

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './queries';

src/databases/officer_db/src/theme-favorites/queries.ts

@@ -0,0 +1,28 @@
+import { and, eq } from 'drizzle-orm';
+import { db } from '../db';
+import { themeFavorites } from './schema';
+
+/** The theme ids this account has starred. Order is not meaningful — the caller owns the ordering. */
+export async function listThemeFavorites(userId: number): Promise<string[]> {
+  const rows = await db
+    .select({ themeId: themeFavorites.themeId })
+    .from(themeFavorites)
+    .where(eq(themeFavorites.userId, userId));
+  return rows.map((r) => r.themeId);
+}
+
+/**
+ * Star or unstar, returning the state it ended in.
+ *
+ * Idempotent in both directions on purpose: a double-tap, or two tabs racing, must not end with the star
+ * in a state neither of them asked for. `onConflictDoNothing` makes the insert safe to repeat, and the
+ * delete is naturally so.
+ */
+export async function setThemeFavorite(userId: number, themeId: string, favorite: boolean): Promise<boolean> {
+  if (favorite) {
+    await db.insert(themeFavorites).values({ userId, themeId }).onConflictDoNothing();
+    return true;
+  }
+  await db.delete(themeFavorites).where(and(eq(themeFavorites.userId, userId), eq(themeFavorites.themeId, themeId)));
+  return false;
+}

src/databases/officer_db/src/theme-favorites/schema.ts

@@ -0,0 +1,37 @@
+import { integer, pgTable, serial, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
+import { users } from '../auth/schema';
+
+/**
+ * Which themes an account has starred.
+ *
+ * ── Why a table, when a preference could be one JSON column ──
+ *
+ * Because it is per account and unbounded. `user_settings` would hold an array that grows with taste and
+ * has to be read-modify-written by whoever toggles a star, and two tabs doing that at once lose one of the
+ * stars. A row per favourite makes a toggle an INSERT or a DELETE, which cannot race with itself.
+ *
+ * ── Why the theme id is text with no foreign key ──
+ *
+ * Themes are not database rows. Most are compiled into the bundle; the rest are directories under
+ * `platform/themes/` discovered at request time, so a theme can appear or vanish without anything writing
+ * SQL. A foreign key would either be unenforceable or would make installing a theme a migration.
+ *
+ * The consequence is deliberate: a star can outlive its theme. That is why the reader intersects with the
+ * live registry rather than trusting the table — a favourite naming a theme nobody has installed is
+ * ignored, not shown as a broken entry, and it costs one row until the account unstars something.
+ */
+export const themeFavorites = pgTable(
+  'theme_favorites',
+  {
+    id: serial('id').primaryKey(),
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    /** The theme's registry id — `duck-dark`, `catppuccin`. Not a foreign key; see above. */
+    themeId: text('theme_id').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  // uniqueIndex, never unique().on() — drizzle-kit re-creates named composite constraints on every push.
+  // See src/databases/CLAUDE.md → "Composite keys".
+  (table) => [uniqueIndex('uq_theme_favorites_user_theme').on(table.userId, table.themeId)],
+);

src/server.tsx

@@ -16,6 +16,7 @@ import { resolveAuthToken } from './servers/auth-token';
 import { isWsProviderAllowed } from './servers/permissions/authorize';
 import { isTokenBlacklisted, getUserById } from 'officerdb';
 import { terminalWebsocket } from './servers/api/terminal/websocket';
+import { minesweeperWebsocket } from './servers/api/minesweeper/websocket';
 import { chatWebsocket } from './servers/api/chat/websocket';
 import { chatNotifyWebsocket } from './servers/api/chat/notify-delivery';
 import { registerChatPushNotifications } from './servers/api/chat/notify-push';
@@ -159,19 +160,65 @@ const handlers: Record<string, any> = {
   'chat-notify': chatNotifyWebsocket,
   'task-runner': taskRunnerWebsocket,
   pipeline: pipelineWebsocket,
+  minesweeper: minesweeperWebsocket,
   sidecar: sidecarWebsocket,
 };
 
-// Both doors into the platform, checked against the permission registry before either opens.
-//
-// This throws rather than warns, and it throws HERE — before serve() — so a surface nobody has gated
-// cannot be reached even once. The HTTP half comes from hono.ts's own mount table and the socket half
-// from the map directly above, so neither list can be a stale copy of the thing it describes.
+/**
+ * Every websocket path Bun serves, and the provider each one upgrades to.
+ *
+ * ── Why this exists rather than a hand-written route table ──
+ *
+ * The boot check below used to be fed `Object.keys(handlers)` — the map of provider implementations — while
+ * Bun served a SEPARATE, hand-listed set of routes. Two lists describing one thing, and the comment beside
+ * the check said neither could be a stale copy of the other, which was simply not true: a socket route with
+ * no handler, or with no registry claim, was invisible to the very check that exists to refuse it.
+ *
+ * It had a live instance. `/api/cliamp/ws` and `/api/cliamp/audio/ws` stayed in the route table for two
+ * days after their handlers and registry entries were commented out — not exploitable, since
+ * `isWsProviderAllowed` finds no permission and 403s a member while the owner upgrades onto a dead socket,
+ * but exactly the drift the guard is for. Deleting cliamp on 2026-08-15 removed the symptom and left the
+ * shape.
+ *
+ * Now the routes are GENERATED from this, and this is what totality reads. A path added here without a
+ * handler or without a registry claim fails the boot rather than serving quietly.
+ */
+const WS_ROUTES: Record<string, UpgradableProvider> = {
+  '/api/tasks/run/ws': 'task-runner',
+  '/api/tasks/pipeline/ws': 'pipeline',
+  '/api/terminal/ws': 'terminal',
+  '/api/minesweeper/ws': 'minesweeper',
+  '/api/chat/ws': 'chat',
+  '/api/chat/notify/ws': 'chat-notify',
+};
+
+// Every provider named by a served route, plus the two that upgrade through their own handlers rather than
+// `upgradeWs`: `sidecar` (loopback process-to-process, its own route below) and `dev-proxy` (upgraded from
+// inside the proxy router). Named explicitly so their absence from WS_ROUTES cannot read as an oversight.
+const SERVED_WS_PROVIDERS = [...new Set([...Object.values(WS_ROUTES), 'sidecar', 'dev-proxy'])];
+
+/*
+  Both doors into the platform, checked against the permission registry before either opens.
+
+  This throws rather than warns, and it throws HERE — before serve() — so a surface nobody has gated cannot
+  be reached even once. The HTTP half comes from hono.ts's own mount table. The socket half now comes from
+  WS_ROUTES, which the route table is BUILT from, so the check reads what is actually served rather than a
+  parallel list that agrees with it by hand.
+
+  A provider with a handler and no route is fine and is not checked: unreachable is the safe direction. The
+  failure this catches is the other one — a route reachable with nothing claiming it.
+*/
 assertPermissionTotality({
   apiPrefixes: [...PROTECTED_API_PREFIXES, ...UNPROTECTED_API_PREFIXES],
-  wsProviders: Object.keys(handlers),
+  wsProviders: SERVED_WS_PROVIDERS,
 });
 
+// A route cannot name a provider that has no implementation. Cheap, and it turns a 500 on first connect
+// into a refusal to boot with the name in it.
+for (const [path, provider] of Object.entries(WS_ROUTES)) {
+  if (!handlers[provider]) throw new Error(`${path} upgrades to '${provider}', which has no handler`);
+}
+
 // Chat's phone channel. Subscribes to the same signal the browser bell uses and asks the same question;
 // it just answers it into APNs/FCM instead of a websocket. Registered here, and explicitly, because a
 // module whose only job is a side effect is one an import sweep quietly deletes.
@@ -312,11 +359,16 @@ console.log(
     : '[web] serving via the HTML import (dev) — HMR is live, and `build/` is not used',
 );
 
-async function upgradeWs(
-  req: Request,
-  server: any,
-  provider: 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline',
-) {
+/**
+ * A provider reachable by upgrading a URL.
+ *
+ * Named rather than inline so `WS_ROUTES` is checked against it: a route naming a provider this function
+ * cannot serve is now a typecheck failure instead of a runtime one. `sidecar` and `dev-proxy` are
+ * deliberately absent — they upgrade through their own handlers, not through here.
+ */
+type UpgradableProvider = 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline' | 'minesweeper';
+
+async function upgradeWs(req: Request, server: any, provider: UpgradableProvider) {
   const token = new URL(req.url).searchParams.get('token');
   if (!token) return new Response('Unauthorized', { status: 401 });
 
@@ -441,11 +493,13 @@ const server = serve({
       });
       if (!ok) return new Response('Upgrade failed', { status: 500 });
     },
-    '/api/tasks/run/ws': (req, server) => upgradeWs(req, server, 'task-runner'),
-    '/api/tasks/pipeline/ws': (req, server) => upgradeWs(req, server, 'pipeline'),
-    '/api/terminal/ws': (req, server) => upgradeWs(req, server, 'terminal'),
-    '/api/chat/ws': (req, server) => upgradeWs(req, server, 'chat'),
-    '/api/chat/notify/ws': (req, server) => upgradeWs(req, server, 'chat-notify'),
+    // Generated from WS_ROUTES, so this table and the boot check cannot describe different sets.
+    ...Object.fromEntries(
+      Object.entries(WS_ROUTES).map(([path, provider]) => [
+        path,
+        (req: Request, server: any) => upgradeWs(req, server, provider),
+      ]),
+    ),
     // CalDAV/CardDAV. These live OUTSIDE /api because DAV clients are given a bare domain and probe
     // fixed, spec-defined paths — `/.well-known/caldav` unauthenticated, before they hold any
     // credential at all. They need naming explicitly here or the `/*` SPA fallback below swallows them

src/servers/api/chat/chat.ts

@@ -1,5 +1,5 @@
 import type { Context } from 'hono';
-import { emitToSession } from './websocket';
+import { emitToSession, sessionKeyForTranscript } from './websocket';
 import { pauseBackgroundTask, restartBackgroundTask } from './task-restart';
 import { createRouter } from '../../create-router';
 import * as errors from '@@/custom-errors';
@@ -12,6 +12,7 @@ import {
   getChatNotifyPreference,
   getChatNotifyPreferences,
   setChatNotifyPreference,
+  forgetChatSessions,
 } from 'officerdb';
 import type { NotifyPreference } from 'officerdb/types';
 import { setNudge, getNudge, cancelNudge } from 'officerdb';
@@ -27,7 +28,6 @@ import {
   stopBackgroundTask,
   claudeSessionContext,
   liveSessionTitle,
-  isCommandersDir,
 } from './claude-sessions';
 import {
   listOpenCodeSessions,
@@ -58,7 +58,7 @@ import { readSttConfig } from '../server-settings/stt';
  * Reachable by a member since 2026-08-12 — see the note below on what replaced the wholesale refusal that
  * used to stand at the top of this router.
  */
-async function chatIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
+export async function chatIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
   const resolved = await resolveHomeDir(user.id);
   if (!resolved.ok) throw errors.FORBIDDEN(resolved.reason);
   return { email: user.email, home: resolved.home, osUser: resolved.osUser, isOwner: resolved.isOwner };
@@ -151,6 +151,12 @@ chatRouter.get('/sessions', async (ctx) => {
 
     Never fatal — a database hiccup on a feature /chat does not otherwise depend on must not take the whole
     conversation list down with it, the same posture `getChatSessionModels` below already takes.
+
+    This route does NOT report `isCommander` on its rows, and that is not an omission. It used to: rows were
+    tagged from this same set a few lines above and then removed by it here, so the flag was false on every
+    row that survived — a field that could only ever lie, plus a second identical query to produce it. A list
+    that excludes commanders has nothing to say about which of its rows is one. `/chat/live` is where the
+    flag is real, because that route keeps both kinds.
   */
   const filed = await listCommandHqSessionIds(user.id).catch(() => new Set<string>());
   const sessions = merged.filter((s) => !filed.has(s.id));
@@ -257,6 +263,16 @@ chatRouter.get('/sessions/:id', async (ctx) => {
     offset: windowed ? start : 0,
     title: context?.title ?? null,
     partCount: context?.partCount ?? 1,
+    /*
+      Whether this conversation is a commander, derived from ITS OWN cwd rather than from the screen asking.
+
+      The composer offers "exit and hand back, then re-arm" — the only fire behaviour a watcher wants — and
+      decided whether to by looking at the route it was rendered on. So the same commander, opened from
+      /chat instead of Command HQ, silently lost the control that is the whole point of it. A commander is a
+      commander wherever it is rendered, and `detail.cwd` is the transcript's own directory, so this answer
+      travels with the conversation.
+    */
+    isCommander: (await listCommandHqSessionIds(user.id)).has(id),
   });
 });
 
@@ -282,6 +298,7 @@ chatRouter.get('/live', async (ctx) => {
     sidecar.listLiveClaudeSessions(user.id),
     who.isOwner ? sidecar.listLiveOpenCodeSessions() : Promise.resolve([]),
   ]);
+  const commanderIds = await listCommandHqSessionIds(user.id);
   const sessions = live.map((session) => {
     // Resolve by Claude's id, never by the session key — the key is officer's handle and the transcript
     // is named after Claude's. Null until the first turn reports one, which is a conversation that has
@@ -294,14 +311,16 @@ chatRouter.get('/live', async (ctx) => {
       harness: 'claude' as const,
       title: resolved?.title ?? null,
       cwd,
-      // Derived from the cwd rather than looked up in `command_hq_sessions`, for the same reason the
-      // history listing does it: every commander shares one directory, so the directory IS the answer and
-      // it needs no query. It also stays right for a commander mid-first-turn, before any row exists.
+      // From the `command_hq_sessions` rows, because a commander chooses its own working directory and the
+      // directory therefore answers nothing. One query for the whole set, before the map below.
+      //
+      // A commander mid-first-turn has no row yet and so reports false here for one turn. That is the same
+      // turn on which it must not arm anything, and it corrects itself the moment it is filed.
       //
       // This field is why the route changed at all. The iPhone app swipes between LIVE chats and has no
       // room for tabs, so it can only exclude commanders if the payload says which ones they are — and a
       // deploy commander turning up in that swipe order is exactly what it must not do.
-      isCommander: cwd ? isCommandersDir(who.email, cwd) : false,
+      isCommander: transcriptId ? commanderIds.has(transcriptId) : false,
     };
   });
 
@@ -347,7 +366,42 @@ chatRouter.get('/live', async (ctx) => {
     };
   });
 
-  return ctx.json({ sessions: [...sessions, ...openCodeSessions] });
+  const rows = [...sessions, ...openCodeSessions];
+
+  /*
+    `?kind=` — the split, done here rather than by each client.
+
+    The classification was already server-side; what was not was the FILTER, so every client repeated it.
+    That is fine for the web list, which has both tabs on screen, and wrong for a phone that swipes between
+    live chats one at a time and must simply never be handed a commander.
+
+    **The default is `agent`, not "everything".** A caller that says nothing gets ordinary chats, so the way
+    to receive a commander is to ask for one by name. That is the whole point: forgetting the parameter can
+    only ever under-report, never put a deploy commander into a swipe order that has no way to skip it. It
+    costs the two callers that DO want both an explicit `kind=all`, which is the right trade — they are few,
+    they are on screens built for it, and they are the ones in a position to notice if it is wrong.
+
+    Counts always describe the WHOLE set, whatever the filter. The web tabs show `Agents (n) /
+    Commanders (n)` side by side and both numbers have to be right whichever tab is open — a filter that
+    also hid the other count would force a second request to render one screen, which is how a server-side
+    filter ends up costing more than the client-side one it replaced.
+
+    An unrecognised `kind` is a 400, never a silent fallback. Plural forms are accepted because the client's
+    own type is already `'agents' | 'commanders'`, and the failure silence would buy is precise: a mistyped
+    `?kind=agents` resolving to something other than agents is the exact bug this exists to prevent.
+  */
+  const kind = ctx.req.query('kind') ?? 'agent';
+  const counts = {
+    agents: rows.filter((s) => !s.isCommander).length,
+    commanders: rows.filter((s) => s.isCommander).length,
+  };
+  if (!['agent', 'agents', 'commander', 'commanders', 'all'].includes(kind)) {
+    return ctx.json({ error: `Unknown kind '${kind}' — expected 'agent', 'commander' or 'all'` }, 400);
+  }
+  const wantCommanders = kind === 'commander' || kind === 'commanders';
+  const shown = kind === 'all' ? rows : rows.filter((s) => s.isCommander === wantCommanders);
+
+  return ctx.json({ sessions: shown, counts });
 });
 
 // DELETE /chat/sessions/:id[?cwd=] — remove a conversation from the owning harness's store. For a
@@ -358,8 +412,36 @@ chatRouter.delete('/sessions/:id', async (ctx) => {
   const id = ctx.req.param('id');
   const cwd = cwdOf(ctx, who.home);
   if (isOpenCodeSessionId(id) && !who.isOwner) return ctx.text('Not found', 404);
-  const ok = isOpenCodeSessionId(id) ? await deleteOpenCodeSession(id) : deleteClaudeSession(who, cwd, id);
-  if (!ok) return ctx.text('Not found', 404);
+  if (isOpenCodeSessionId(id)) {
+    if (!(await deleteOpenCodeSession(id))) return ctx.text('Not found', 404);
+    return ctx.json({ ok: true });
+  }
+
+  /*
+    Stop the harness BEFORE removing its file, and wait for it.
+
+    The `claude` CLI owns the transcript. Deleting it while a live session is still writing removes a file
+    that is written straight back, so the conversation reappears untitled on the next refresh — see
+    `killClaudeAndWait`. No live session means nothing to wait for, which is the ordinary case here.
+  */
+  const liveKey = sessionKeyForTranscript(id);
+  if (liveKey) await sidecar.killClaudeAndWait(liveKey, ctx.get('user').id);
+
+  // `.length`, not truthiness: this returns the IDS it removed and an empty array is truthy in JavaScript,
+  // so `if (removed)` would report a delete that found nothing as a success.
+  const removed = deleteClaudeSession(who, cwd, id);
+  if (!removed.length) return ctx.text('Not found', 404);
+
+  /*
+    The transcript is gone; forget what the platform stored ABOUT it. Four tables describe a conversation with
+    no foreign key — there is no row for one to reference — so nothing cascades and this has to be explicit.
+    One of them, `nudges`, is a live schedule: left behind it keeps firing at a conversation that is gone.
+
+    Two id spaces, and they are not interchangeable: three tables are keyed on the transcript id, while
+    `chat_session_events` is keyed on officer's session key. Undefined here is the normal case for an old
+    conversation — no live session holds it, so nothing is keyed on a key to remove.
+  */
+  await forgetChatSessions({ transcriptIds: removed, sessionKeys: liveKey ? [liveKey] : [] });
   return ctx.json({ ok: true });
 });
 

src/servers/api/chat/claude-sessions.ts

@@ -1,4 +1,4 @@
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { DATA_PATH, getCommandersDir } from '../../data-path';
 import {
   appendTextAs,
@@ -642,9 +642,12 @@ const findTranscript = (who: ChatIdentity, cwd: string, sessionId: string): stri
  * routinely (see `findTranscript`), and the wrong group would find no chain and silently delete one
  * part of several.
  */
-export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: string): boolean {
+export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: string): string[] {
   const filePath = findTranscript(who, cwd, sessionId);
-  if (!filePath) return false;
+  // The IDS it removed, not a boolean — empty means nothing was there. The caller needs them to forget the
+  // rows keyed on each one (`forgetChatSessions`), and a `/clear` chain is several transcripts presenting as
+  // one conversation: returning true would have told a caller to forget the head and orphan its parts.
+  if (!filePath) return [];
 
   const ownCwd = firstCwd(who.osUser, filePath);
   const ids = ownCwd ? chainFileIds(who, ownCwd, sessionId) : [sessionId];
@@ -653,7 +656,7 @@ export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: s
   // success — the conversation reappeared on the next refresh.
   const dir = dirname(filePath);
   for (const id of ids) removeAs(who.osUser, join(dir, `${id}.jsonl`));
-  return true;
+  return ids;
 }
 
 /**
@@ -984,20 +987,45 @@ function scanGroup(who: ChatIdentity, cwd: string): TranscriptSummary[] {
   return applyLineage(sessions);
 }
 
-/** Conversations Claude has stored for a working directory, newest first, one row per `/clear` chain. */
+/**
+ * Conversations Claude has stored for a working directory, newest first, one row per `/clear` chain.
+ *
+ * **Says nothing about commanders**, deliberately. It used to: every commander shared one directory, so the
+ * directory was the answer and this computed it once per group. That stopped being true the moment a
+ * commander could choose its own working directory — a commander in the platform checkout would have been
+ * reported as an ordinary chat, and an ordinary chat in the old commanders directory as a commander.
+ *
+ * Identity is now the `command_hq_sessions` row, which is the only thing that survives the cwd being free.
+ * It is applied by the CALLER, because that requires a database read and this function is synchronous over a
+ * directory scan.
+ */
+/**
+ * A transcript with no human or assistant turn in it is not a conversation.
+ *
+ * The harness writes metadata records — `last-prompt`, `ai-title`, `atis-latch` — into a transcript file
+ * independently of the conversation, and it will happily create the file to hold them. So a session that was
+ * deleted, or one that never sent anything, leaves a file containing only those three lines, which listed as
+ * "(untitled) · 0 msgs" and accumulated: four of them from one evening of testing.
+ *
+ * Filtered at the list rather than deleted on disk. The files are the harness's, it is entitled to write
+ * them, and a cleanup that raced it would be the same class of bug as the one that produced them.
+ */
+const hasConversation = (s: ClaudeSessionSummary): boolean => s.messageCount > 0;
+
 export function listClaudeSessions(who: ChatIdentity, cwd: string): ClaudeSessionSummary[] {
-  // Every commander a user has lives in ONE directory, so this is a property of the group rather than of
-  // each transcript — computed once here instead of per row. See `isCommander` on the summary type for
-  // why the flag has to reach the payload at all.
-  const commander = isCommandersDir(who.email, cwd);
   return mergeChains(scanGroup(who, cwd))
     .map(publish)
-    .map((entry) => (commander ? { ...entry, isCommander: true } : entry))
+    .filter(hasConversation)
     .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
 /**
- * Is this directory the one every commander shares?
+ * Is this the default commanders directory?
+ *
+ * **No longer the test for whether something is a commander** — that is the `command_hq_sessions` row, since
+ * a commander now chooses its own working directory. This remains only for the places that legitimately care
+ * about that specific path: creating it for a new OS account, and as the historical location of commanders
+ * created before the cwd was choosable.
  *
  * Compared after `resolve`, so a trailing slash or a `..` cannot make the same directory look like a
  * different one — the cwd here comes from a transcript rather than from code, and transcripts record
@@ -1011,6 +1039,36 @@ export function isCommandersDir(email: string, cwd: string): boolean {
   }
 }
 
+/**
+ * One session's list-shaped summary, found by id wherever it lives.
+ *
+ * For callers that hold a set of ids rather than a directory — Command HQ, which reads its commanders from
+ * `command_hq_sessions` and cannot scan for them any more now that each chooses its own working directory.
+ *
+ * Returns null when no transcript can be found, which is the same signal a directory scan gave by omission:
+ * a filed row whose conversation has been deleted. `purgeCommandHqSessions` is what tidies those.
+ *
+ * Deliberately NOT chain-aware in the way `listClaudeSessions` is. It reports the transcript addressed by
+ * this id; a `/clear` chain's head is what gets filed and what every surface addresses, so the tail is not
+ * something a caller here holds an id for.
+ */
+export function loadClaudeSessionSummaryById(who: ChatIdentity, sessionId: string): ClaudeSessionSummary | null {
+  const filePath = locateTranscript(who, sessionId);
+  if (!filePath) return null;
+
+  // `mtimeMs` becomes `updatedAt`, which is what every caller sorts on — so it has to be real, not zero.
+  // Taken from `listTranscriptsAs` over the transcript's OWN directory rather than a bare `statSync`: the
+  // file may belong to a member, and reading a member's tree needs the as-user path. One directory listing
+  // per commander, scoped to one group — the same call the old whole-directory scan made, once per row
+  // instead of once for all of them, which is the cost of letting each choose where it lives.
+  const group = basename(dirname(filePath));
+  const entry = listTranscriptsAs(who.osUser, claudeProjectsDir(who.home), group).find((f) => f.id === sessionId);
+  if (!entry) return null;
+
+  const summary = summarizeTranscript(who.osUser, filePath, sessionId, entry.mtimeMs);
+  return summary ? publish(summary) : null;
+}
+
 /**
  * Every conversation in every directory, newest first.
  *

src/servers/api/chat/claude-usage.ts

@@ -78,11 +78,15 @@ const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
 /**
  * How long a reading is reused.
  *
- * Both halves are expensive in different ways — the endpoint rate-limits, and the scan reads ~90MB of JSONL —
- * and neither changes meaningfully inside a minute. Cached SEPARATELY so a network failure does not throw
- * away a good scan, and so opening and shutting the popover is not a request per flick.
+ * The transcript scan reads ~90MB of JSONL and its answer does not change meaningfully inside a minute, so
+ * it is still served from cache. It is also the same answer whichever account is signed in — it counts what
+ * this machine wrote, not what an account is allowed — which is why switching account does not need to
+ * invalidate it.
+ *
+ * **The limits have no TTL and are never served from cache.** They are per-account and they are the number
+ * somebody opens this panel to read, so a stale one is worse than a slow one. The store is kept for the
+ * failure path only — see `lastGoodLimits`.
  */
-const LIMITS_TTL_MS = 60_000;
 const SCAN_TTL_MS = 60_000;
 
 const claudeDir = (): string => process.env.CLAUDE_CONFIG_DIR?.trim() || join(getOwnerHomeDir(''), '.claude');
@@ -142,7 +146,21 @@ export async function readAccountEmail(): Promise<string | null> {
 
 type LimitsResult = { limits: UsageLimit[]; problem?: string };
 
-let limitsCache: { at: number; result: LimitsResult } | null = null;
+/*
+  Last good reading PER ACCOUNT, and used only when a probe fails.
+
+  This was a TTL cache keyed on nothing, and the consequence was the whole feature lying. Switching account
+  changes which credential `readOauthLogin` returns, but a cached entry was served regardless — so the panel
+  showed the previous account's percentages under the new account's name for the length of the TTL, and the
+  failure fallback served them for as long as the probe kept failing. Reported by the owner: maxed out on one
+  account, switched, and the numbers did not move.
+
+  So there is no TTL any more. Every request probes, because these percentages are the entire point of the
+  panel and a stale one is worse than a slow one. What survives is the fallback, now keyed on the account it
+  was measured for, so a flaky request degrades to that account's own last reading rather than to a blank
+  panel or — far worse — to somebody else's numbers.
+*/
+const lastGoodLimits = new Map<string, { at: number; result: LimitsResult }>();
 
 const asPercent = (value: unknown): number => {
   const n = Number(
@@ -303,20 +321,22 @@ async function collectLimits(): Promise<LimitsResult & { plan: string | null; me
     return { limits: [], plan: null, measuredAt: now, problem: 'Claude Code is not signed in on this machine.' };
   }
 
-  if (limitsCache && now - limitsCache.at < LIMITS_TTL_MS) {
-    return { ...limitsCache.result, plan: login.plan, measuredAt: limitsCache.at };
-  }
+  // Which account this reading belongs to. Null would make every account share one entry, which is the bug
+  // this key exists to prevent, so an unattributable reading gets no fallback rather than a shared one.
+  const account = await readAccountEmail();
 
   const fresh = await probeLimits(login.accessToken);
   if (fresh.limits.length) {
-    limitsCache = { at: now, result: fresh };
+    if (account) lastGoodLimits.set(account, { at: now, result: fresh });
     return { ...fresh, plan: login.plan, measuredAt: now };
   }
 
-  // A failed probe falls back to the last good reading rather than to nothing — the numbers are minutes old
-  // at worst, and a panel that goes blank on one flaky request is worse than one that is slightly behind.
-  const stale = limitsCache?.result.limits.filter((l) => windowStillOpen(l, now)) ?? [];
-  return { limits: stale, plan: login.plan, measuredAt: limitsCache?.at ?? now, problem: fresh.problem };
+  // A failed probe falls back to THIS account's last good reading rather than to nothing — minutes old at
+  // worst, and a panel that blanks on one flaky request is worse than one slightly behind. Windows that have
+  // since reset are dropped: a stale 78% would misreport an allowance that is now untouched.
+  const previous = account ? lastGoodLimits.get(account) : undefined;
+  const stale = previous?.result.limits.filter((l) => windowStillOpen(l, now)) ?? [];
+  return { limits: stale, plan: login.plan, measuredAt: previous?.at ?? now, problem: fresh.problem };
 }
 
 // ── Local transcript scan ──

src/servers/api/chat/types.ts

@@ -76,6 +76,20 @@ export type ClientMessage =
        * first turn is the first moment the preference can be acted on OR written down.
        */
       planMode?: boolean;
+      /**
+       * The name the owner chose for a COMMANDER before its first message.
+       *
+       * Claude Code will not accept a name for a new session — the harness names its own from the first
+       * prompt — so the platform renames the transcript the moment it exists. Carried on the turn rather
+       * than sent afterwards because it must not depend on a browser still being open: the name was chosen
+       * before anything was said, and losing it to a closed tab would leave a commander called after
+       * whatever it happened to say first.
+       *
+       * Applied once, by `fileAsCommander`, via `renameClaudeSession` — which writes a `summary` record and
+       * therefore an EXPLICIT title, and an explicit title is never overwritten by `ai-title` or by the
+       * first-message fallback.
+       */
+      commanderName?: string;
       /**
        * This turn is arming a Command HQ watcher — see `docs/command-hq.md` → "The watcher loop". Set only
        * by `BackgroundJobDialog` submitting a `handoff` job inside a commander (`isCommander` true); every

src/servers/api/chat/websocket.ts

@@ -15,12 +15,7 @@ import { sendClaudeCodeStreaming } from '@@/channels/send-claude-code';
 import { sendOpenCodeStreaming } from '@@/channels/send-opencode';
 import * as sidecar from '@@/sidecar-registry';
 import { join } from 'path';
-import {
-  getOwnerHomeDir,
-  getEmailAccountsDir,
-  findEmailAccountName,
-  getCommandersDir,
-} from '../../../servers/data-path';
+import { getOwnerHomeDir, getEmailAccountsDir, findEmailAccountName } from '../../../servers/data-path';
 import { attachedFilePaths } from './attached-files';
 import {
   getUserSettings,
@@ -37,6 +32,8 @@ import {
 } from 'officerdb';
 import { resolveHomeDir } from '@@/user-home';
 import { renameClaudeSession, type ChatIdentity } from './claude-sessions';
+import { chatIdentity } from './chat';
+import { commanderBlock } from '../command-hq/commander-block';
 import { claudeLoginState } from '@@/os-user-claude';
 import { mkdirSync } from 'node:fs';
 import { logger } from './logger';
@@ -154,16 +151,25 @@ async function resolveChatCwd(
   userId: number,
   home: string,
 ): Promise<string> {
-  // Every commander a user has shares ONE directory — never a client-chosen one, and never per-commander
-  // (see `getCommandersDir`). `msg.cwd` is ignored on this branch entirely, the same posture the identity
-  // half of a turn already takes: resolved by the platform, never trusted from the caller.
-  //
-  // `mkdirSync` — synchronous, so this returns only once the directory genuinely exists, the same pattern
-  // `resolveEmailCwd` below already uses. No race: unlike the rejected per-commander design, this directory
-  // is shared and only the very first commander ever needs the mkdir to do anything; `recursive: true`
-  // makes every call after that a no-op stat.
+  /*
+    A commander runs where the owner chose, and the choice is required.
+
+    This used to force `getCommandersDir(email)` and ignore `msg.cwd` entirely — every commander shared one
+    empty directory whose only job was to BE a cwd, because the cwd was how a commander was recognised.
+    Identity is the `command_hq_sessions` row now, so the directory is free to be useful: a commander that
+    works on the platform can live in the platform checkout, where its relative paths mean something and its
+    transcripts sit beside the work they are about.
+
+    The chosen path is resolved through `resolveCwd(home, …)`, the same containment the ordinary chat branch
+    below uses — so "client-chosen" still does not mean "anywhere". A commander cannot be pointed outside
+    the account's own tree by a crafted message.
+
+    No fallback to the old shared directory when nothing is chosen: the UI requires a directory before the
+    first message can be sent, and a silent default would be a commander running somewhere nobody picked.
+    Falling back to the account's home is the honest last resort for a caller that predates the requirement.
+  */
   if (msg.context === 'command-hq') {
-    const dir = getCommandersDir(email);
+    const dir = msg.cwd?.trim() ? resolveCwd(home, msg.cwd) : home;
     mkdirSync(dir, { recursive: true });
     return dir;
   }
@@ -351,6 +357,15 @@ function createMessageHandler(
   resumeSessionId?: string,
   planMode?: boolean,
   commandHq?: boolean,
+  /**
+   * The name the owner chose before the conversation started, for a commander.
+   *
+   * Claude Code will not accept a name for a NEW session — the harness names its own — so the platform
+   * renames it the moment the transcript exists. Done here rather than by the client because it must not
+   * depend on a browser still being open: the name was chosen before the first message, and losing it to a
+   * closed tab would leave a commander called after whatever it happened to say first.
+   */
+  commanderName?: string,
 ) {
   /*
     The model messages are ATTRIBUTED to, which is not always the model the turn asked for.
@@ -450,17 +465,54 @@ function createMessageHandler(
     Fire-and-forget, swallowed failure, same posture as `record`: a database hiccup here must not be a
     reason a chat turn fails.
   */
+  // Whether the chosen name has actually reached the transcript. False until a rename RETURNS true — see
+  // the retry note inside `fileAsCommander`.
+  let commanderNamed = false;
+
   const fileAsCommander = (): void => {
     if (!commandHq || !transcriptId) return;
     const userId = sessionManager.getSession(sessionId)?.userId;
     if (!userId) return;
-    void createCommandHqSession(userId, transcriptId).catch((err: unknown) => {
-      logger.warn('Could not file this session as a commander', {
-        sessionId,
-        transcriptId,
-        error: err instanceof Error ? err.message : String(err),
+    const filedId = transcriptId;
+    // The name goes in with the row, not only to the transcript: the list reads it from here and is
+    // right immediately, rather than waiting on a summary record the harness cannot write until the
+    // first turn has finished.
+    void createCommandHqSession(userId, filedId, null, commanderName?.trim() || null)
+      .then(async () => {
+        /*
+          The chosen name, applied once — and RETRIED, because the first attempt usually fails.
+
+          `fileAsCommander` runs on `session:claude`, which arrives at the START of a turn: the transcript
+          file may not be on disk yet, and `renameClaudeSession` returns false when it cannot find one. It
+          returns a boolean that nothing was checking, so the name was silently dropped and the conversation
+          kept the harness's own `ai-title` — which is exactly what the first live test showed.
+
+          So the attempt is recorded and retried at the end of the turn, by which point the file certainly
+          exists. Idempotent: once it succeeds, `commanderNamed` stops it repeating.
+
+          It still writes a `summary` record, which sets `hasExplicitTitle` — and an explicit title is never
+          overwritten by `ai-title` or by the first-message fallback. So it wins whenever it lands.
+        */
+        if (!commanderName?.trim() || commanderNamed) return;
+        // The same identity resolution every chat route uses, rather than a second copy of it: it is what
+        // decides the home and the OS user, and a rename writes a file as that user.
+        const user = await getUserById(userId).catch(() => null);
+        if (!user?.email) return;
+        const who = await chatIdentity({ id: userId, email: user.email }).catch(() => null);
+        if (!who) return;
+        // `who.home` as the hint, not the old shared commanders directory: a commander chooses its own
+        // working directory now, so that path is usually wrong. `findTranscript` treats the cwd as a HINT
+        // and locates the transcript wherever it actually is — so this works either way, and passing a
+        // path we know is probably wrong would be the kind of thing that reads as intent later.
+        commanderNamed = renameClaudeSession(who, who.home, filedId, commanderName.trim());
+      })
+      .catch((err: unknown) => {
+        logger.warn('Could not file this session as a commander', {
+          sessionId,
+          transcriptId: filedId,
+          error: err instanceof Error ? err.message : String(err),
+        });
       });
-    });
   };
 
   return (msg: TurnMessage, seq?: number): void => {
@@ -511,6 +563,8 @@ function createMessageHandler(
     // written on its very first turn rather than on its second.
     if (msg.type === 'session:claude' && msg.claudeSessionId) {
       transcriptId = msg.claudeSessionId;
+      // The platform's own copy of the mapping — see `transcriptIdBySessionKey`.
+      transcriptIdBySessionKey.set(sessionId, msg.claudeSessionId);
       record();
       fileAsCommander();
     }
@@ -519,6 +573,9 @@ function createMessageHandler(
       record();
       fileAsCommander();
     }
+    // And retried on every result until the name lands. The first attempt runs before the transcript file
+    // exists, so the end of the first turn is the earliest a rename can succeed.
+    if (msg.type === 'result' && commandHq && !commanderNamed) fileAsCommander();
 
     /*
       The watcher loop — see `docs/command-hq.md` → "The watcher loop" and `handoffContract` in
@@ -734,6 +791,11 @@ async function handleChat(
   msg: {
     prompt: string;
     displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
     sessionId?: string;
     model?: string;
     cwd?: string;
@@ -851,6 +913,32 @@ export type ClaudeTurnOutcome = { ok: true; transcriptId: string } | { ok: false
  * generic timeout: the reasons below (member not signed in, Claude not installed, spawn failure) are the
  * same reasons a websocket caller already sees via `sendToClient`, just mirrored to a second listener.
  */
+/**
+ * Officer's session key → Claude's transcript id, for the platform's own use.
+ *
+ * The sidecar keeps this mapping and the platform cannot read it: `state.ts` holds it in the sidecar's
+ * memory, and re-loading its file from here does not find a live session. So the platform keeps its own,
+ * filled from the `session:claude` message it already handles.
+ *
+ * This is the third distinct place the two ids have caused a bug today. The mapping is not derivable — it is
+ * announced, once, mid-turn — so anything needing it either records it when it passes or does without.
+ */
+const transcriptIdBySessionKey = new Map<string, string>();
+
+/** The mapping read backwards, for callers holding a transcript id — the delete route, mainly. */
+export function sessionKeyForTranscript(transcriptId: string): string | undefined {
+  for (const [key, id] of transcriptIdBySessionKey) if (id === transcriptId) return key;
+  return undefined;
+}
+
+/**
+ * Sessions already told what they are and where to record it.
+ *
+ * In memory, keyed on officer's session id: a restart re-briefs, which costs a few hundred tokens on one
+ * turn and is the safe direction — a commander that was never told is one that cannot be stopped.
+ */
+const briefedSessions = new Set<string>();
+
 export async function startClaudeTurn(params: {
   email: string;
   username: string;
@@ -861,6 +949,11 @@ export async function startClaudeTurn(params: {
   msg: {
     prompt: string;
     displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
     groupSlug?: string;
     context?: string;
     contextId?: string;
@@ -869,12 +962,44 @@ export async function startClaudeTurn(params: {
     images?: PromptImage[];
     resumeSessionId?: string;
     planMode?: boolean;
+    /** See `commanderName` on the wire type — the name chosen before a commander's first message. */
+    commanderName?: string;
     armWatcher?: boolean;
   };
   effectivePrompt: string;
   onOutcome?: (outcome: ClaudeTurnOutcome) => void;
 }): Promise<void> {
-  const { email, username, userId, ws, sessionId, model, msg, effectivePrompt, onOutcome } = params;
+  const { email, username, userId, ws, sessionId, model, msg, onOutcome } = params;
+
+  /*
+    A commander is told its record paths ON A TURN, not in the system preamble.
+
+    The preamble is built inside `createSession`, which runs ONCE — on a conversation's first turn. For a
+    commander that is precisely the turn where the block cannot exist: it has no `command_hq_sessions` row
+    and no transcript id yet, so `commanderBlock` returns null, and every later turn reuses the same session
+    and never rebuilds the preamble. So a commander never received the block at all, and its loop had no
+    paths to record itself at. Its own test caught it: it armed a perfectly good watcher and wrote no
+    `loop-pid`.
+
+    Riding `effectivePrompt` instead. That is the string the model sees; `displayText` is what the transcript
+    shows — the same seam the background-job dialog already uses to send a hidden preamble — so this reaches
+    the agent without appearing in the conversation.
+
+    Once per session, on the first turn where the block resolves, which is the first turn after the commander
+    is filed. It stays available afterwards because it is in the conversation's own history from then on.
+  */
+  let effectivePrompt = params.effectivePrompt;
+  if (!briefedSessions.has(sessionId)) {
+    const block = await commanderBlock({
+      userId,
+      sessionId: transcriptIdBySessionKey.get(sessionId) ?? msg.resumeSessionId ?? null,
+      selfStarted: msg.selfStarted === true,
+    });
+    if (block) {
+      briefedSessions.add(sessionId);
+      effectivePrompt = `${block}\n\n---\n\n${effectivePrompt}`;
+    }
+  }
   const fail = (error: string) => {
     sendToClient(ws, { type: 'error', message: error });
     onOutcome?.({ ok: false, error });
@@ -958,6 +1083,7 @@ export async function startClaudeTurn(params: {
     msg.resumeSessionId,
     msg.planMode,
     msg.context === 'command-hq',
+    msg.commanderName,
   );
   // Wrapped rather than passed straight to the spawn call, so `onOutcome` sees the transcript id at the
   // exact moment `fileAsCommander` (inside `createMessageHandler`) does — both react to the same
@@ -1035,6 +1161,11 @@ async function handleClaudeCodeChat(
   msg: {
     prompt: string;
     displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
     groupSlug?: string;
     context?: string;
     contextId?: string;
@@ -1058,6 +1189,11 @@ async function handleOpenCodeChat(
   msg: {
     prompt: string;
     displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
     groupSlug?: string;
     context?: string;
     contextId?: string;
@@ -1263,13 +1399,20 @@ function handlePlanDecision(
 ): void {
   const sessionId = wsToSessionMap.get(ws);
   if (!sessionId) return;
-  sidecar.decideClaudePlan({
+  const delivered = sidecar.decideClaudePlan({
     sessionKey: sessionId,
     userId: ws.data.userId,
     requestId: msg.requestId,
     approve: msg.approve,
     feedback: msg.feedback,
   });
+  // Same drop as `handleQuestionAnswer`, same spinning card — see `sendFire`.
+  if (!delivered) {
+    sendToClient(ws, {
+      type: 'error',
+      message: 'The agent is not connected right now, so that decision did not reach it. Try again in a moment.',
+    });
+  }
 }
 
 /**
@@ -1283,12 +1426,29 @@ function handlePlanDecision(
 function handleQuestionAnswer(ws: ServerWebSocket<WSData>, msg: { toolCallId: string; answer: string }): void {
   const sessionId = wsToSessionMap.get(ws);
   if (!sessionId) return;
-  sidecar.answerClaudeQuestion({
+  /*
+    A dropped answer has to reach the person who sent it.
+
+    `sendFire` does nothing when no sidecar is registered, and that window is real — every restart of this
+    process has one while the agent reconnects. The answer vanished with no log and no error, so the
+    question card spun on, which is indistinguishable from a slow agent. The only move left was to send
+    another message, which is the worst possible thing to do to a waiting tool call.
+
+    The agent's own handler already reports the failures it CAN see (no such session, question no longer
+    waiting). This is the one it cannot, because the command never arrives.
+  */
+  const delivered = sidecar.answerClaudeQuestion({
     sessionKey: sessionId,
     userId: ws.data.userId,
     toolCallId: msg.toolCallId,
     answer: msg.answer,
   });
+  if (!delivered) {
+    sendToClient(ws, {
+      type: 'error',
+      message: 'The agent is not connected right now, so that answer did not reach it. Try again in a moment.',
+    });
+  }
 }
 
 async function handleStop(ws: ServerWebSocket<WSData>): Promise<void> {

src/servers/api/command-hq/commander-block.ts

@@ -0,0 +1,93 @@
+import { getCommandHqSession, getUserById } from 'officerdb';
+import { loopPidPath, spawnedRecordPath } from './spawned';
+
+/*
+  What a commander is told about ITSELF, once per session.
+
+  ── Why this exists ──
+
+  A commander must record its own loop's pid and every agent that loop spawns, or it cannot be stopped and
+  cannot be fully deleted. The instruction for that used to live in ONE place: the preamble the
+  background-job dialog composes. Which was fine while the only way to arm a commander was through that
+  dialog, and wrong the moment a commander arms itself from the conversation — the intended flow. An agent
+  starting its own background job never sees that preamble, so it would record nothing, and delete would go
+  back to leaving orphaned loops without anybody noticing it had.
+
+  ── Why the paths come from here and the method comes from the skill ──
+
+  The split is not arbitrary. The METHOD — how to write the record, when, what to append — is reference
+  material that belongs with everything else about commanders, in the skill, where it can be as long as it
+  needs to be and is read only when relevant. The PATHS are a fact about THIS session that nothing else can
+  supply: they are rooted in DATA_PATH and keyed on the commander's own transcript id, and an agent knows
+  neither. So they are compiled in, always, like an affordance — because a fact the agent cannot derive is
+  exactly what an always-loaded block is for.
+
+  Short for the same reason every affordance is short: it is charged to every turn of every commander.
+*/
+
+type CommanderBlockParams = {
+  /** The Officer account, for the row lookup and for the paths. */
+  userId: number;
+  /** Claude's transcript id — what a commander is keyed on everywhere. */
+  sessionId: string | null;
+  /**
+   * The owner pressed Start rather than typing an opening message.
+   *
+   * They supplied a name and a working directory and nothing else, so there is no request to act on and
+   * the commander has to run the interview itself. Only ever true on the turn the button sends — a
+   * commander asked something later is an ordinary conversation and must not restart its intake.
+   */
+  selfStarted?: boolean;
+};
+
+export async function commanderBlock(params: CommanderBlockParams): Promise<string | null> {
+  if (!params.sessionId) return null;
+
+  // The ROW decides, not the working directory. A commander chooses its own cwd, so the directory answers
+  // nothing — and a session in the old shared directory is not a commander unless it was filed as one.
+  const row = await getCommandHqSession(params.userId, params.sessionId).catch(() => null);
+  if (!row) return null;
+
+  // The paths need the account's email and the row carries a user id, so this is a second read. Once per
+  // session spawn, alongside the affordances and the skills index, which are also read here rather than
+  // cached — the same trade for the same reason.
+  const user = await getUserById(params.userId).catch(() => null);
+  if (!user?.email) return null;
+  const email = user.email;
+
+  return [
+    '# You are a commander',
+    '',
+    'This conversation is a commander: an agent that keeps working when nobody is watching. Open the',
+    '**Commanders** skill before starting or changing a watcher — it carries how the pieces fit, what to',
+    'establish with the owner first, and the mistakes that are expensive.',
+    '',
+    'Two paths only this session can be told. **Write to them or you cannot be stopped:**',
+    '',
+    `- your loop's own pid: \`${loopPidPath(email, params.sessionId)}\``,
+    `- one session id per line, for every agent your loop spawns: \`${spawnedRecordPath(email, params.sessionId)}\``,
+    '',
+    'The platform cannot find your process and cannot recover a spawned agent id after it exits, so this',
+    'record is the only one. Without it, deleting this commander leaves your loop running.',
+    '',
+    '**Never arm a watcher on your first turn.** The first turn is for settling what to watch and what to do',
+    'about it — arming before that is arming a guess, and a wrong condition either never fires or fires',
+    'constantly and is found out days later. If you were given no paths above, you ARE on your first turn:',
+    'that is what their absence means. Ask, and arm once it is agreed.',
+    /*
+      The button case. A pointer, not the interview itself: the questions live in the skill, which is
+      re-read from disk on every run, so rewording one costs nothing. The same words here would cost a
+      `pm2 restart officer` every time — and this file is the wrong home for doctrine that will be
+      edited far more often than the mechanism around it.
+    */
+    ...(params.selfStarted
+      ? [
+          '',
+          '**Nobody has told you what they want yet.** They gave a name and a working directory and',
+          'pressed Start, which is a request to run the interview — not a request to do anything else.',
+          'Read the **Commanders** skill now and follow "When you started yourself": orient in this',
+          'directory first, then open with what you found and ONE question.',
+        ]
+      : []),
+  ].join('\n');
+}

src/servers/api/command-hq/router.ts

@@ -5,11 +5,23 @@ import { checkBudget } from '../sub-agents/budget';
 import * as errors from '@@/custom-errors';
 import { resolveHomeDir } from '@@/user-home';
 import { getCommandersDir, toShellUsername } from '@@/data-path';
-import { getChatEventsSince } from 'officerdb';
+import { forgetChatSessions, getChatEventsSince, ingestSpawnedChildren, sessionKeyForTranscriptId } from 'officerdb';
+import * as sidecar from '@@/sidecar-registry';
+import { findSessionKeyByClaudeSession } from '@@/sidecar/claude/state';
+import { sessionKeyForTranscript } from '../chat/websocket';
+import {
+  clearSpawnedRecord,
+  listSpawnedSessions,
+  loopPidPath,
+  spawnedRecordPath,
+  stopCommanderProcesses,
+  liveLoopPid,
+} from './spawned';
 import type { ServerMessage } from '../chat/types';
 import {
   listClaudeSessions,
   loadClaudeSessionById,
+  loadClaudeSessionSummaryById,
   renameClaudeSession,
   deleteClaudeSession,
   type ChatIdentity,
@@ -55,11 +67,17 @@ import {
  *
  * ── Where commanders live ──
  *
- * Every commander shares ONE working directory per user — `getCommandersDir(email)` — never one per
- * commander. That means listing a user's commanders is exactly `listClaudeSessions` (the same function
- * `/chat` uses for its own per-directory list) pointed at that one directory, filtered to sessions with a
- * `command_hq_sessions` row. No new session-scanning code exists here; this router is a client of the same
- * transcript reader `/chat` already is.
+ * **Wherever the owner chose.** Each commander names its own working directory when it is created, and that
+ * directory is where its relative paths resolve and where its transcripts are grouped.
+ *
+ * It was one shared directory per user until 2026-08-22, because the directory WAS the identity — the only
+ * way to tell a commander from an ordinary chat. Identity is the `command_hq_sessions` row now, so the
+ * directory became free to be useful, and a commander that works on the platform can live in the platform.
+ *
+ * The consequence for this router is that listing is no longer a directory scan. It reads its rows and loads
+ * each transcript BY ID (`loadClaudeSessionSummaryById`) — a handful of lookups rather than one walk. A row
+ * whose transcript cannot be found anywhere is treated as absent, exactly as a missing file in the old scan
+ * was, and `POST /purge` is what tidies those.
  */
 
 async function commandHqIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
@@ -194,12 +212,24 @@ commandHqRouter.get('/commanders', async (ctx) => {
   const categoryParam = ctx.req.query('category');
   const categoryId = categoryParam === undefined ? undefined : categoryParam === 'none' ? null : Number(categoryParam);
 
-  const [rows, live] = await Promise.all([
-    listCommandHqSessions(user.id, categoryId),
-    listClaudeSessions(who, getCommandersDir(who.email)),
-  ]);
+  /*
+    Each commander's transcript is loaded BY ID, not found by scanning one directory.
 
-  const liveById = new Map(live.map((s) => [s.id, s]));
+    It used to be `listClaudeSessions(who, getCommandersDir(...))` — every commander lived in one place, so
+    one scan found them all and a row without a match there was a row whose transcript had been deleted. A
+    commander chooses its own working directory now, so that scan finds only the ones that happen to still
+    live in the old shared folder and would silently hide every other.
+
+    One `locateTranscript` per row instead of one scan for all of them. Commanders are few — this is a
+    handful of stats, not a directory walk per row — and a row whose transcript cannot be found anywhere is
+    still treated exactly as before: absent, which is what `purgeCommandHqSessions` exists to tidy.
+  */
+  const rows = await listCommandHqSessions(user.id, categoryId);
+  const summaries = rows
+    .map((row) => loadClaudeSessionSummaryById(who, row.sessionId))
+    .filter((s): s is NonNullable<typeof s> => !!s);
+
+  const liveById = new Map(summaries.map((s) => [s.id, s]));
   const filed = rows.filter((row) => liveById.has(row.sessionId));
 
   const [tagsByRow, lastFiredByRow, runningById, costByRow] = await Promise.all([
@@ -219,10 +249,17 @@ commandHqRouter.get('/commanders', async (ctx) => {
   const commanders: CommanderSummary[] = filed
     .map((row) => ({
       ...liveById.get(row.sessionId)!,
+      // The row's name wins over the transcript's. It is written when the commander is filed, while the
+      // summary record cannot exist until the first turn ends — so until then the transcript still reports
+      // the opening brief, and the row is the only source that is right from the start.
+      ...(row.name ? { title: row.name } : {}),
       categoryId: row.categoryId,
       tagIds: tagsByRow.get(row.id) ?? [],
       running: runningById.get(row.sessionId) ?? false,
-      watcherArmed: row.watcherArmed,
+      // The pid file is the FACT; `watcher_armed` is a claim only one path sets. A commander that started
+      // its loop as a plain background job recorded its pid correctly and still reported unarmed, so the
+      // grid offered nothing to stop — which is the one thing this column exists to make possible.
+      watcherArmed: row.watcherArmed || liveLoopPid(who.email, row.sessionId) !== null,
       watcherArmedAt: row.watcherArmedAt,
       watcherStoppedAt: row.watcherStoppedAt,
       watcherLastFiredAt: lastFiredByRow.get(row.id) ?? null,
@@ -265,8 +302,10 @@ commandHqRouter.get('/commanders', async (ctx) => {
 commandHqRouter.post('/commanders/new', async (ctx) => {
   const user = ctx.get('user');
   const body = await ctx.req
-    .json<{ prompt?: string; displayText?: string; categoryId?: number | null }>()
-    .catch(() => ({}) as { prompt?: string; displayText?: string; categoryId?: number | null });
+    .json<{ prompt?: string; displayText?: string; categoryId?: number | null; cwd?: string; name?: string }>()
+    .catch(
+      () => ({}) as { prompt?: string; displayText?: string; categoryId?: number | null; cwd?: string; name?: string },
+    );
   const prompt = body.prompt?.trim();
   if (!prompt) throw errors.BAD_REQUEST('prompt is required');
 
@@ -302,7 +341,17 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
       ws: null,
       sessionId,
       model,
-      msg: { prompt, displayText: body.displayText?.trim() || undefined, context: 'command-hq' },
+      msg: {
+        prompt,
+        displayText: body.displayText?.trim() || undefined,
+        context: 'command-hq',
+        // Where this commander runs, and its name. Both are chosen before the first message — the UI makes
+        // them mandatory — so this programmatic path takes them too rather than inventing a default. An
+        // absent cwd falls back to the account's home in `resolveChatCwd`, which is the honest last resort
+        // for a caller that predates the requirement.
+        ...(body.cwd?.trim() ? { cwd: body.cwd.trim() } : {}),
+        ...(body.name?.trim() ? { commanderName: body.name.trim() } : {}),
+      },
       effectivePrompt: prompt,
       onOutcome: settle,
     });
@@ -322,7 +371,9 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
   await createCommandHqSession(user.id, outcome.transcriptId, body.categoryId ?? null);
   await setCommandHqSessionCategory(user.id, outcome.transcriptId, body.categoryId ?? null);
 
-  return ctx.json({ sessionId: outcome.transcriptId, cwd: getCommandersDir(user.email) });
+  // The cwd it ACTUALLY ran in, from the spawn outcome — not a guess at the old shared directory, which is
+  // no longer where a commander necessarily lives.
+  return ctx.json({ sessionId: outcome.transcriptId, cwd: body.cwd?.trim() ?? null });
 });
 
 /**
@@ -350,10 +401,11 @@ commandHqRouter.get('/commanders/:sessionId', async (ctx) => {
   ]);
   return ctx.json({
     sessionId: row.sessionId,
+    name: row.name,
     categoryId: row.categoryId,
     tagIds: tagsByRow.get(row.id) ?? [],
     running,
-    watcherArmed: row.watcherArmed,
+    watcherArmed: row.watcherArmed || liveLoopPid(who.email, row.sessionId) !== null,
     watcherArmedAt: row.watcherArmedAt,
     watcherStoppedAt: row.watcherStoppedAt,
     watcherLastFiredAt: lastFiredByRow.get(row.id) ?? null,
@@ -417,8 +469,10 @@ commandHqRouter.post('/commanders', async (ctx) => {
   const sessionId = body.sessionId?.trim();
   if (!sessionId) throw errors.BAD_REQUEST('sessionId is required');
 
-  const live = listClaudeSessions(who, getCommandersDir(who.email));
-  if (!live.some((s) => s.id === sessionId)) throw errors.NOT_FOUND('no such session in the commanders directory');
+  // Located by id wherever it lives, not required to be in the old shared directory. A commander chooses
+  // its own working directory, so "is it in the commanders folder" stopped being a meaningful check — and
+  // as a GUARD it only ever established that the transcript exists, which this still does.
+  if (!loadClaudeSessionSummaryById(who, sessionId)) throw errors.NOT_FOUND('no such conversation');
 
   const row = await createCommandHqSession(user.id, sessionId, body.categoryId ?? null);
   return ctx.json(row);
@@ -451,7 +505,9 @@ commandHqRouter.patch('/commanders/:sessionId', async (ctx) => {
     await setCommandHqSessionCategory(user.id, sessionId, body.categoryId);
   }
   if (body.name !== undefined) {
-    const ok = renameClaudeSession(who, getCommandersDir(who.email), sessionId, body.name.trim());
+    // `who.home` as the HINT only — `findTranscript` locates the transcript wherever it actually is, and a
+    // commander's directory is its own choice now.
+    const ok = renameClaudeSession(who, who.home, sessionId, body.name.trim());
     if (!ok) throw errors.NOT_FOUND('transcript not found');
   }
   if (body.watcherArmed === false) {
@@ -469,11 +525,25 @@ commandHqRouter.patch('/commanders/:sessionId', async (ctx) => {
  * disk, so hide it" pattern `purgeCommandHqSessions` exists for — it is the one place that makes the two
  * agree by deleting the thing itself, on purpose, because the owner asked to.
  *
- * A watcher still armed at the time of deletion is left as-is rather than disarmed first: the transcript
- * is gone either way, `armCommandHqWatcher`/`recordCommandHqWatcherFired` can no longer find a row to
- * update once this returns, and the running background process (if any) dies on its own the same way it
- * would if the harness process were killed out from under any other conversation — not a new failure
- * mode this route has to account for.
+ * ── It cascades, and it has to ──
+ *
+ * Deleting a commander means being finished with it and with everything it produced. So, in this order:
+ *
+ *   1. STOP the processes. The loop the commander started is a descendant of the commander's own `claude`,
+ *      and any agent the loop spawned is a descendant of the loop, so one `killTree` from the session's
+ *      process takes all of it. The comment here used to claim the background process "dies on its own" —
+ *      it does not. Nothing in this route touched a process, so a deleted commander left its loop running:
+ *      still polling, still able to fire, still able to spawn an agent, with no chip to stop it from and no
+ *      row left to disarm.
+ *   2. DELETE the children's transcripts, read from the spawned record. They cannot be found any other way
+ *      — see `spawned.ts` for the three approaches that do not work.
+ *   3. DELETE the commander's own transcript and row, as before.
+ *
+ * Stopping first is deliberate: a live agent writing to a transcript being deleted is a race, and the loop
+ * could spawn a new one between steps 2 and 3.
+ *
+ * A watcher still armed is not disarmed first, and does not need to be — the row goes away entirely, and
+ * `armCommandHqWatcher`/`recordCommandHqWatcherFired` can no longer find one to update.
  */
 commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
   const user = ctx.get('user');
@@ -483,9 +553,111 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
   const row = await getCommandHqSession(user.id, sessionId);
   if (!row) throw errors.NOT_FOUND('not a commander');
 
-  deleteClaudeSession(who, getCommandersDir(who.email), sessionId);
+  /*
+    1. Everything this commander is still running — the SESSION first, then the loop.
+
+    Killing the loop alone is not enough, and its own test proved it: the loop is a grandchild of the
+    commander's `claude` process, so ending the loop leaves the session alive — and a live session REWRITES
+    its transcript after the file is deleted. Twice tonight a deleted commander's transcript reappeared, and
+    twice it read as the delete having failed.
+
+    `killClaudeSession` takes officer's session key while this route holds a transcript id, so the map is
+    read backwards — `findSessionKeyByClaudeSession`, which exists for the same reason a refreshed browser
+    holds only the uuid. Ending the session takes its children with it, and the pid-based stop below then
+    catches anything that outlived its parent.
+  */
+  // Same mapping problem as the briefing: the sidecar's map is not visible from here, so the platform's own
+  // is asked first and the sidecar's is kept as a fallback for a session that predates this process.
+  /*
+    Third fallback, and the only one that survives a restart.
+  
+    Both maps above are in-memory and answer only for a session younger than this process. After a
+    restart they both return undefined, no kill is sent, and the transcript is deleted while the harness
+    is still writing — so it writes it back and the deleted commander returns as an untitled stub. Seen
+    twice tonight, after the fix that was meant to prevent exactly this.
+  */
+  const sessionKey =
+    sessionKeyForTranscript(sessionId) ??
+    findSessionKeyByClaudeSession(sessionId, user.id) ??
+    (await sessionKeyForTranscriptId(sessionId).catch(() => undefined));
+  /*
+    Across the socket, and AWAITED — both halves matter.
+
+    `killClaudeSession` from `claude-manager` was called directly here, and it could only ever return false:
+    the session map lives in the `officer-claude-code` process and this route runs in `officer`, so it was
+    reading an empty map in the wrong process. The kill silently never happened.
+
+    Awaited because the next thing this route does is delete the transcript, and the `claude` CLI owns that
+    file. Deleting it while the CLI is still unwinding removes a file that is written straight back — which
+    is exactly how a deleted commander came back as an untitled ordinary chat.
+  */
+  const sessionKilled = sessionKey ? await sidecar.killClaudeAndWait(sessionKey, user.id) : false;
+  const stopped = stopCommanderProcesses(who.email, sessionId);
+
+  // 2. Everything it spawned. Best-effort per child: one transcript that has already been cleaned up must
+  //    not stop the rest from going, and a child is often gone before its parent.
+  // Ingest the inbox before reading it, so a child appended since the last read is still deleted. The file
+  // is lossy by design and the rows are not — but a row that has never been ingested does not exist yet.
+  const children = (await ingestSpawnedChildren(row.id, listSpawnedSessions(who.email, sessionId))).map(
+    (c) => c.spawnedSessionId,
+  );
+  let childrenDeleted = 0;
+  // Every transcript id actually removed — the commander's and its children's, chains included. Collected
+  // rather than assumed, because a `/clear` chain is several ids behind one conversation.
+  const forgotten: string[] = [];
+  for (const child of children) {
+    try {
+      // A spawned agent runs in the platform checkout, not the commanders directory, so its transcript
+      // lives in that project's group — the same lookup `/chat/sessions/:id` falls back to.
+      // The cwd is a HINT here, not an authority — `deleteClaudeSession` falls back to locating the
+      // transcript wherever it actually is, which is what makes this work for a child that ran in a
+      // different directory from its parent.
+      //
+      // `.length`, not truthiness: this returns the ids it removed, and an empty array is truthy.
+      const removedChild = deleteClaudeSession(who, who.home, child);
+      if (removedChild.length) {
+        childrenDeleted += 1;
+        forgotten.push(...removedChild);
+      }
+    } catch {
+      // Already gone, or never written. Counted as not-deleted rather than failing the request.
+    }
+  }
+  clearSpawnedRecord(who.email, sessionId);
+
+  // 3. The commander itself.
+  forgotten.push(...deleteClaudeSession(who, who.home, sessionId));
   await deleteCommandHqSession(user.id, sessionId);
-  return ctx.json({ ok: true });
+
+  /*
+    Forget what the platform stored ABOUT every transcript that just went — the commander's and its
+    children's, in one call.
+
+    The `command_hq_*` tables cascade from the row, because they reference it. These four do not: they are
+    keyed on a transcript id, which is a FILE, so there is no row for them to reference and nothing to
+    cascade from. Left behind they are mostly inert — a model, a bell preference, a durable copy of turn
+    output — except `nudges`, which is a live schedule that would keep firing at a conversation that no
+    longer exists.
+  */
+  /*
+    `sessionKeys` carries the commander's own key and nothing else, on purpose. Children are spawned by
+    `claude -p` outside officer's websocket, so they never had a key and never wrote a durable event — an
+    empty entry for them would be noise, not caution.
+
+    `sessionKey` is resolved above for the kill and reused here rather than looked up twice; when it is null
+    the session was already gone, and so were its events.
+  */
+  await forgetChatSessions({ transcriptIds: forgotten, sessionKeys: sessionKey ? [sessionKey] : [] });
+
+  // Said back rather than a bare ok: this is the one irreversible action here, and the counts are what
+  // make it auditable after the fact.
+  return ctx.json({
+    ok: true,
+    sessionKilled,
+    processesStopped: stopped,
+    childrenFound: children.length,
+    childrenDeleted,
+  });
 });
 
 /**
@@ -498,8 +670,16 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
 commandHqRouter.post('/purge', async (ctx) => {
   const user = ctx.get('user');
   const who = await commandHqIdentity(user);
-  const live = listClaudeSessions(who, getCommandersDir(who.email));
-  const removed = await purgeCommandHqSessions(user.id, new Set(live.map((s) => s.id)));
+  /*
+    "Still exists" is now per row, wherever that row's transcript lives.
+
+    Scanning one directory would have deleted every commander that chose a different one — a housekeeping
+    route quietly unfiling live commanders is the worst possible version of this bug, because the rows are
+    what identity depends on now.
+  */
+  const rows = await listCommandHqSessions(user.id);
+  const stillThere = new Set(rows.map((row) => row.sessionId).filter((id) => !!loadClaudeSessionSummaryById(who, id)));
+  const removed = await purgeCommandHqSessions(user.id, stillThere);
   return ctx.json({ removed });
 });
 
@@ -518,6 +698,59 @@ commandHqRouter.post('/commanders/:sessionId/tags', async (ctx) => {
   return ctx.json({ ok: true });
 });
 
+/**
+ * GET /command-hq/commanders/:sessionId/children
+ *
+ * The agents this commander spawned, ingested from the loop's inbox on the way through.
+ *
+ * Ingesting on READ rather than on a timer is deliberate: a cron for this is a moving part that can stop
+ * without anybody noticing, and the read is the only moment the answer is wanted. `onConflictDoNothing` on
+ * the unique index makes re-ingesting the whole file cost nothing, so this is safe to call as often as the
+ * UI likes.
+ */
+commandHqRouter.get('/commanders/:sessionId/children', async (ctx) => {
+  const user = ctx.get('user');
+  const who = await commandHqIdentity(user);
+  const sessionId = ctx.req.param('sessionId');
+
+  const row = await getCommandHqSession(user.id, sessionId);
+  if (!row) throw errors.NOT_FOUND('not a commander');
+
+  const children = await ingestSpawnedChildren(row.id, listSpawnedSessions(who.email, sessionId));
+  // `unknownCost` said out loud rather than summed as zero: a commander whose children's costs are unknown
+  // must not display a confident total that happens to be too low. That understatement is the whole reason
+  // this exists.
+  const known = children.filter((c) => c.totalUsd !== null);
+  return ctx.json({
+    children,
+    totalUsd: known.reduce((sum, c) => sum + (c.totalUsd ?? 0), 0),
+    unknownCost: children.length - known.length,
+  });
+});
+
+/**
+ * GET /command-hq/commanders/:sessionId/record-paths
+ *
+ * Where this commander's loop must write its pid and the session ids it spawns.
+ *
+ * The composer needs these to build the background-job prompt, and cannot derive them: they are rooted in
+ * `DATA_PATH`, which is a server fact. Returning paths rather than accepting an upload is deliberate — the
+ * loop writes them itself with a shell redirect, which needs no token and works from inside a background
+ * job, where an authenticated POST would need a credential the loop has no business holding.
+ *
+ * Not gated on the commander existing as a ROW: a brand-new commander asks for these before its first turn
+ * has filed it, and refusing then would mean the very first loop is the one that cannot record itself.
+ */
+commandHqRouter.get('/commanders/:sessionId/record-paths', async (ctx) => {
+  const user = ctx.get('user');
+  const who = await commandHqIdentity(user);
+  const sessionId = ctx.req.param('sessionId');
+  return ctx.json({
+    loopPidPath: loopPidPath(who.email, sessionId),
+    spawnedPath: spawnedRecordPath(who.email, sessionId),
+  });
+});
+
 // DELETE /command-hq/commanders/:sessionId/tags/:tagId
 commandHqRouter.delete('/commanders/:sessionId/tags/:tagId', async (ctx: Context) => {
   const user = ctx.get('user');

src/servers/api/command-hq/spawned.ts

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCommanderStateDir } from '../../data-path';
+import { descendantPids } from '../tasks/process-tree';
+
+/*
+  What a commander spawned, and why the platform cannot work it out for itself.
+
+  A commander's action is a headless agent — `claude -p`, started by the shell loop the commander itself
+  started. The platform never sees that spawn: it happens inside a background job, two processes below a
+  conversation, and the agent talks to Anthropic rather than to us.
+
+  Three ways to recover the link were tried and none works:
+
+    - the PROCESS holds nothing. No open transcript descriptor (it appends and closes), and nothing
+      identifying in its environment. Verified 2026-08-22.
+    - the TRANSCRIPT is indistinguishable. `queue-operation`, `ai-title`, `last-prompt`, `atis-latch` look
+      like markers the platform injects and are the harness's own, appearing in every session equally. A
+      discriminator built on them rejected a real child and reported zero when one was running.
+    - CONTENT matching finds the wrong sessions. An ordinary chat that happens to quote a procedure matches
+      as well as the agent following it.
+
+  So the loop records it, and the platform reads it. One newline-delimited file per commander:
+
+      <DATA_PATH>/<email>/commander-state/<commander session id>/spawned
+
+  The loop can only do that if it knows which commander it belongs to, which it does not by default — the
+  id is injected into the background-job prompt by `background-job-prompt.ts`. That is the whole chain, and
+  every link is required.
+*/
+
+const FILE = 'spawned';
+const PID_FILE = 'loop-pid';
+
+/** A session id as the harness writes them. Anything else is a corrupt line and is dropped, not trusted. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Where the loop should append. Handed to the agent in its prompt; nothing guesses it. */
+export function spawnedRecordPath(email: string, commanderSessionId: string): string {
+  return join(getCommanderStateDir(email, commanderSessionId), FILE);
+}
+
+/**
+ * Every agent this commander recorded, oldest first, de-duplicated.
+ *
+ * Tolerant on purpose. The writer is a shell loop appending under whatever conditions it is in, so a
+ * truncated write, a blank line or a stray log line must not break a delete — they are dropped and the rest
+ * is used. A record that fails closed here would make a commander undeletable because of a bad line.
+ */
+export function listSpawnedSessions(email: string, commanderSessionId: string): string[] {
+  const path = spawnedRecordPath(email, commanderSessionId);
+  if (!existsSync(path)) return [];
+  try {
+    const seen = new Set<string>();
+    for (const raw of readFileSync(path, 'utf-8').split('\n')) {
+      const id = raw.trim();
+      if (SESSION_ID.test(id)) seen.add(id.toLowerCase());
+    }
+    return [...seen];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Record one, idempotently. For the platform's own use — the loop appends directly, by design.
+ *
+ * Kept because the platform spawning an agent on a commander's behalf is the obvious next shape, and when
+ * that arrives it must write the same file rather than a second record.
+ */
+export function recordSpawnedSession(email: string, commanderSessionId: string, spawnedId: string): void {
+  if (!SESSION_ID.test(spawnedId)) return;
+  if (listSpawnedSessions(email, commanderSessionId).includes(spawnedId.toLowerCase())) return;
+  const dir = getCommanderStateDir(email, commanderSessionId);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, FILE), `${spawnedId.toLowerCase()}\n`, { mode: 0o600 });
+}
+
+/** Drop the whole record. Called when the commander is deleted, after its children have been dealt with. */
+export function clearSpawnedRecord(email: string, commanderSessionId: string): void {
+  try {
+    rmSync(getCommanderStateDir(email, commanderSessionId), { recursive: true, force: true });
+  } catch {
+    // A record we cannot remove is untidy, not incorrect: the commander is gone and nothing reads this
+    // without a commander to read it for.
+  }
+}
+
+/*
+  ── Stopping what a commander is running ──
+
+  The platform has no session-to-process map: `claude-manager` spawns through the SDK and keeps no pid, and
+  a `claude` process cannot be attributed to a particular commander from outside — every commander's session
+  runs with the same cwd, so the process table cannot tell them apart.
+
+  So the loop records its own pid, the same way it records what it spawns, and for the same reason: it is the
+  only party that knows. From that one number the whole tree follows — the loop's children include any agent
+  it spawned, and `descendantPids` was written for exactly this ("Bun's proc.kill() signals only the direct
+  child, so a running grandchild is left orphaned and keeps going").
+
+  A commander with no recorded pid stops nothing and SAYS so. That is the honest answer for a commander armed
+  before this existed, and pretending otherwise would report a clean delete over a loop still polling.
+*/
+
+/** Where the loop should write its own pid. Handed to it in its prompt, like the spawned record. */
+export function loopPidPath(email: string, commanderSessionId: string): string {
+  return join(getCommanderStateDir(email, commanderSessionId), PID_FILE);
+}
+
+/** The loop's pid, if it recorded one and the process is still alive. */
+export function liveLoopPid(email: string, commanderSessionId: string): number | null {
+  const path = loopPidPath(email, commanderSessionId);
+  if (!existsSync(path)) return null;
+  const pid = Number(readFileSync(path, 'utf-8').trim());
+  if (!Number.isInteger(pid) || pid <= 1) return null;
+  try {
+    // Signal 0 tests for existence without touching it. A recorded pid whose process has gone is not an
+    // error — loops end — and reusing a dead pid's number would kill something unrelated.
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stop the loop and everything under it. Returns how many processes were signalled.
+ *
+ * Children first, then the loop, so the loop cannot spawn a replacement between the two.
+ */
+export function stopCommanderProcesses(email: string, commanderSessionId: string): number {
+  const pid = liveLoopPid(email, commanderSessionId);
+  if (!pid) return 0;
+  const tree = [...descendantPids(pid), pid];
+  let signalled = 0;
+  for (const target of tree) {
+    try {
+      process.kill(target, 'SIGTERM');
+      signalled += 1;
+    } catch {
+      // Gone between the walk and the signal. Not a failure — that is the outcome we wanted.
+    }
+  }
+  return signalled;
+}

src/servers/api/minesweeper/router.ts

@@ -0,0 +1,28 @@
+import { createRouter } from '../../create-router';
+import { sessionStatus, startSession, stopSession } from './session';
+
+/**
+ * Session control. The pixels do not come through here — they come through the websocket relay; this
+ * is only "is it up, bring it up, take it down", plus the window size the panel needs to size its
+ * canvas.
+ */
+export const minesweeperRouter = createRouter();
+
+minesweeperRouter.get('/status', async (c) => c.json(await sessionStatus()));
+
+minesweeperRouter.post('/start', async (c) => {
+  const status = await sessionStatus();
+  if (!status.installed) {
+    return c.json({ error: 'Minesweeper is not installed on this server (wine-minesweeper is missing)' }, 501);
+  }
+  if (status.running) return c.json(status);
+
+  const result = await startSession();
+  if (!result.ok) return c.json({ error: `Could not start the session: ${result.out.trim()}` }, 500);
+  return c.json(await sessionStatus());
+});
+
+minesweeperRouter.post('/stop', async (c) => {
+  await stopSession();
+  return c.json(await sessionStatus());
+});

src/servers/api/minesweeper/session.ts

@@ -0,0 +1,111 @@
+import { join } from 'node:path';
+import { OFFICER_ROOT } from '../../data-path';
+
+/**
+ * The Minesweeper X session: a virtual display with one Windows game on it, and x11vnc serving that
+ * display on loopback.
+ *
+ * The platform does not implement any of that — it drives `bin/session.sh`, which is the same script
+ * used by hand. One implementation, so a session started from the browser and one started from a
+ * terminal are the same session with the same lifecycle.
+ */
+
+export const MINESWEEPER_DIR = join(OFFICER_ROOT, 'wine-minesweeper');
+const SESSION_SCRIPT = join(MINESWEEPER_DIR, 'bin', 'session.sh');
+
+export const VNC_HOST = '127.0.0.1';
+export const VNC_PORT = Number(process.env.MINESWEEPER_VNC_PORT ?? 5907);
+const DISPLAY = process.env.MINESWEEPER_DISPLAY ?? ':7';
+
+export type WindowGeometry = { width: number; height: number; x: number; y: number };
+export type SessionStatus = {
+  installed: boolean;
+  running: boolean;
+  /** Absent until the game has drawn its window. */
+  window: WindowGeometry | null;
+};
+
+const run = async (cmd: string[], env: Record<string, string> = {}): Promise<{ ok: boolean; out: string }> => {
+  const proc = Bun.spawn(cmd, {
+    cwd: MINESWEEPER_DIR,
+    env: { ...process.env, ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  const code = await proc.exited;
+  return { ok: code === 0, out: `${out}${err}` };
+};
+
+export const isInstalled = (): boolean => Bun.file(SESSION_SCRIPT).size > 0;
+
+/**
+ * Whether x11vnc is listening, decided by reading the kernel's socket table rather than by connecting.
+ *
+ * This used to open a TCP connection and drop it. That wedged the VNC server: libvncserver peeks at a
+ * new connection to decide whether it is a WebSocket handshake, and that peek blocks its main loop
+ * until the client speaks or the peek times out. A health check that connects and says nothing is
+ * therefore a small stall, and the panel polls status on a timer — so the stalls overlapped, the accept
+ * backlog filled (Recv-Q 32/32), and the server stopped accepting the real viewer too.
+ *
+ * The rule it cost to learn: a liveness check must not be indistinguishable from a client. Reading
+ * /proc/net/tcp is free, cannot block, and cannot be mistaken for a viewer.
+ */
+async function isServing(): Promise<boolean> {
+  const wanted = VNC_PORT.toString(16).toUpperCase().padStart(4, '0');
+  const LISTEN = '0A';
+
+  for (const table of ['/proc/net/tcp', '/proc/net/tcp6']) {
+    const text = await Bun.file(table)
+      .text()
+      .catch(() => '');
+
+    for (const line of text.split('\n').slice(1)) {
+      const columns = line.trim().split(/\s+/);
+      const local = columns[1];
+      const state = columns[3];
+      if (!local || state !== LISTEN) continue;
+      if (local.split(':')[1] === wanted) return true;
+    }
+  }
+  return false;
+}
+
+
+/**
+ * The game window's size, so the browser can size its canvas to the board rather than to the whole
+ * framebuffer. `session.sh` parks the window at 0,0, so the offset is expected to be zero and is
+ * reported anyway — a non-zero one means something moved it and the canvas would be misaligned.
+ *
+ * The board changes size when the difficulty changes, which is why this is polled rather than read
+ * once at connect.
+ */
+export async function windowGeometry(): Promise<WindowGeometry | null> {
+  const search = await run(['xdotool', 'search', '--name', 'Minesweeper X'], { DISPLAY });
+  if (!search.ok) return null;
+
+  let best: WindowGeometry | null = null;
+  for (const id of search.out.trim().split('\n').filter(Boolean)) {
+    const geom = await run(['xdotool', 'getwindowgeometry', '--shell', id], { DISPLAY });
+    if (!geom.ok) continue;
+
+    const read = (key: string): number => Number(new RegExp(`^${key}=(\\d+)$`, 'm').exec(geom.out)?.[1] ?? NaN);
+    const candidate = { width: read('WIDTH'), height: read('HEIGHT'), x: read('X'), y: read('Y') };
+    if (Object.values(candidate).some(Number.isNaN)) continue;
+
+    // wine creates a 1x1 owner stub alongside the real window; the larger one is the game.
+    if (!best || candidate.width * candidate.height > best.width * best.height) best = candidate;
+  }
+  return best && best.width > 1 ? best : null;
+}
+
+export async function sessionStatus(): Promise<SessionStatus> {
+  const installed = isInstalled();
+  if (!installed) return { installed, running: false, window: null };
+
+  const running = await isServing();
+  return { installed, running, window: running ? await windowGeometry() : null };
+}
+
+export const startSession = (): Promise<{ ok: boolean; out: string }> => run([SESSION_SCRIPT, 'start']);
+export const stopSession = (): Promise<{ ok: boolean; out: string }> => run([SESSION_SCRIPT, 'stop']);

src/servers/api/minesweeper/websocket.ts

@@ -0,0 +1,95 @@
+import type { ServerWebSocket, Socket } from 'bun';
+import { VNC_HOST, VNC_PORT } from './session';
+
+/**
+ * A byte relay between the browser and x11vnc, in the same spirit as the terminal's relay onto the pty
+ * sidecar — this file authenticates the upgrade (upgradeWs, in server.tsx) and moves bytes without
+ * reading them.
+ *
+ * One difference decides the shape: x11vnc serves raw TCP, not a WebSocket. So this is the job
+ * websockify would otherwise do, done in-process with `Bun.connect` rather than by adding a second
+ * daemon and a second port to protect. RFB is a stream protocol, so frame boundaries carry no meaning
+ * and chunks are forwarded exactly as they arrive.
+ */
+
+export type MinesweeperWSData = { provider: 'minesweeper'; search: string };
+
+type Relay = { socket: Socket | null; queue: Uint8Array[]; done: boolean };
+
+const relays = new Map<ServerWebSocket<MinesweeperWSData>, Relay>();
+
+const closeClient = (ws: ServerWebSocket<MinesweeperWSData>, code: number, reason: string) => {
+  const relay = relays.get(ws);
+  relays.delete(ws);
+  if (relay) relay.done = true;
+  try {
+    relay?.socket?.end();
+  } catch {
+    /* already gone */
+  }
+  try {
+    ws.close(code, reason);
+  } catch {
+    /* already closed */
+  }
+};
+
+export const minesweeperWebsocket = {
+  open(ws: ServerWebSocket<MinesweeperWSData>) {
+    // Registered synchronously, so bytes arriving before the TCP connection is up are queued rather
+    // than dropped. The RFB handshake starts with the SERVER talking, but a client that pipelines its
+    // version string would otherwise lose it.
+    const relay: Relay = { socket: null, queue: [], done: false };
+    relays.set(ws, relay);
+
+    void Bun.connect({
+      hostname: VNC_HOST,
+      port: VNC_PORT,
+      socket: {
+        open(socket) {
+          if (relay.done) {
+            socket.end();
+            return;
+          }
+          relay.socket = socket;
+          for (const chunk of relay.queue) socket.write(chunk);
+          relay.queue.length = 0;
+        },
+        data(_socket, chunk) {
+          try {
+            ws.send(chunk);
+          } catch {
+            /* client gone; the close handler tears down the socket */
+          }
+        },
+        close: () => closeClient(ws, 1000, 'vnc closed'),
+        error: () => closeClient(ws, 1011, 'vnc error'),
+      },
+    }).catch(() => {
+      // No x11vnc listening — the session is not running. 1011 rather than a silent close, so the
+      // panel can say so instead of showing an empty canvas.
+      closeClient(ws, 1011, 'minesweeper session is not running');
+    });
+  },
+
+  message(ws: ServerWebSocket<MinesweeperWSData>, raw: string | Buffer) {
+    const relay = relays.get(ws);
+    if (!relay) return;
+
+    // RFB is binary in both directions; a text frame is a client that is not speaking it.
+    const bytes = typeof raw === 'string' ? new TextEncoder().encode(raw) : new Uint8Array(raw);
+    if (relay.socket) relay.socket.write(bytes);
+    else relay.queue.push(bytes);
+  },
+
+  close(ws: ServerWebSocket<MinesweeperWSData>) {
+    const relay = relays.get(ws);
+    relays.delete(ws);
+    if (relay) relay.done = true;
+    try {
+      relay?.socket?.end();
+    } catch {
+      /* ignore */
+    }
+  },
+};

src/servers/api/sendoff/paths.ts

@@ -0,0 +1,72 @@
+import { join } from 'node:path';
+import { getHomeDir, getOwnerHomeDir } from '@@/data-path';
+
+/** `Documents/SendOff` under whichever home this account actually browses. */
+export const SENDOFF_SUBPATH = join('Documents', 'SendOff');
+
+/**
+ * The SendOff directory for an account, in the home its own file browser shows.
+ *
+ * The two homes are not interchangeable and picking the wrong one makes a delivery invisible: the owner
+ * browses their real login home (`/home/pastilhas`), while another account browses the managed home under
+ * `DATA_PATH/<email>/home`. `getOwnerHomeDir` ignores the email it is passed and always answers the owner,
+ * so it can only be used once the role has been checked — which is why this takes the role rather than
+ * working it out from the email.
+ */
+export function sendoffDirFor(account: { email: string; isOwner: boolean }): string {
+  const home = account.isOwner ? getOwnerHomeDir(account.email) : getHomeDir(account.email);
+  return join(home, SENDOFF_SUBPATH);
+}
+
+/**
+ * A folder name safe to create, from a name a person or a device chose.
+ *
+ * Anything that is not a letter, digit, dash, underscore or dot becomes a dash, and leading dots go — so a
+ * name cannot produce `..`, a hidden directory, or a path with a separator in it. Empty after that is
+ * refused by the caller rather than silently becoming a directory called `-`.
+ */
+export function safeSegment(name: string): string {
+  return name
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^\.+/, '')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+}
+
+/**
+ * A filename safe to write, preserving the extension.
+ *
+ * Same rules as a segment, with the basename taken first: a browser will happily send `../../etc/passwd`
+ * as a filename and the multipart spec does not forbid it.
+ */
+export function safeFilename(name: string): string {
+  const base = name.split(/[/\\]/).pop() ?? '';
+  const cleaned = base
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^\.+/, '')
+    .slice(0, 200);
+  return cleaned || 'file';
+}
+
+/**
+ * The name an account appears as, and therefore the name of the folder its files land in.
+ *
+ * One definition, used by the writer AND by `/targets`, because the two must agree: a picker that says
+ * "Fedra" while the writer creates `fedra.almeida` has told somebody the wrong place to look. Mobile asked
+ * for this to be served rather than derived, which is right — three clients reimplementing a fallback is
+ * how three clients disagree.
+ *
+ * `users.name` is nullable, so the fallback chain ends at the account id, which is always there.
+ */
+export function displayNameFor(account: { id: number; name: string | null; email: string }): string {
+  const chosen = account.name?.trim();
+  if (chosen) return chosen;
+  const local = account.email.split('@')[0]?.trim();
+  return local || `user-${account.id}`;
+}
+
+/** What that name becomes on disk — the same value, through the segment sanitiser. */
+export const folderNameFor = (account: { id: number; name: string | null; email: string }): string =>
+  safeSegment(displayNameFor(account)) || `user-${account.id}`;

src/servers/api/sendoff/router.ts

@@ -0,0 +1,248 @@
+import { mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { createRouter } from '../../create-router';
+import * as errors from '@@/custom-errors';
+import {
+  accountsByIds,
+  allowSender,
+  deleteSendoffDevice,
+  listAllowedSenders,
+  listMyRecipients,
+  listOtherAccounts,
+  listSendoffDevices,
+  maySendTo,
+  renameSendoffDevice,
+  revokeSender,
+  upsertSendoffDevice,
+} from 'officerdb';
+import { getNotifyServerUrl } from '../notify/router';
+import { displayNameFor, folderNameFor, safeFilename, safeSegment, sendoffDirFor } from './paths';
+
+/*
+  SendOff — files land in a real directory in the recipient's own tree.
+
+  There is no staging area, no transfer record and nothing to expire. Every account already has a home, a
+  file browser over it and a Files app on the phone, so a delivered file is an ordinary file: visible in
+  every UI that exists, and managed like anything else its owner owns.
+
+  Two things are worth knowing before changing anything here.
+
+  **This is the only sanctioned door into another account's filesystem.** `/file-browser` and `/upload`
+  write exclusively into the caller's own tree and that must stay true. So this route writes ONLY under
+  `Documents/SendOff/<sender>/`, and `<sender>` comes from the token — never from the payload — so a folder
+  name cannot lie about who put a file there.
+
+  **Consent belongs to the recipient.** A role grant would answer "may this role send files", which is the
+  wrong question; the person who decides whether somebody may write into your home is you. So it is a row,
+  per pair, held by the recipient, and absence denies. A sender who has not been allowed does not see the
+  recipient in their picker at all rather than seeing one and being refused — which also means this endpoint
+  never confirms that an account exists.
+*/
+
+export const sendoffRouter = createRouter();
+
+const MAX_FILE_SIZE = 512 * 1024 * 1024; // 512 MB — this is a file transfer, not an avatar upload
+const isOwnerRole = (role: string | null | undefined): boolean => role === 'Super Admin';
+
+/**
+ * A path that does not exist yet, suffixing ` (1)`, ` (2)`, … before the extension.
+ *
+ * Never overwrite. A second send of the same name is a second file: the sender cannot see the recipient's
+ * directory, so they have no way to know they are about to destroy something, and silently replacing a file
+ * somebody was sent is the one outcome with no recovery.
+ */
+function freePath(dir: string, filename: string): string {
+  const first = join(dir, filename);
+  if (!existsSync(first)) return first;
+  const ext = extname(filename);
+  const stem = filename.slice(0, filename.length - ext.length);
+  for (let n = 1; n < 1000; n++) {
+    const candidate = join(dir, `${stem} (${n})${ext}`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  return join(dir, `${stem} (${Date.now()})${ext}`);
+}
+
+/*
+  The push, and why it carries what it does.
+
+  `id` is the FOLDER NAME — a username or a machine name — and `n` is a file count. Both are interpolated by
+  the catalogue on the device ("3 file(s) from andre") and both are what the route needs to open the right
+  directory. No filename and no path travels: the folder name plus the count is what the owner accepted as
+  the line, and it is enough for the tap to land somewhere useful.
+
+  Never fatal. A delivery that succeeded must not be reported as a failure because a notification did not
+  go out — the file is already in their tree, and the file browser shows it either way.
+*/
+async function pushLanded(recipientUserId: number, folder: string, count: number): Promise<void> {
+  try {
+    const base = getNotifyServerUrl();
+    if (!base) return;
+    await fetch(`${base}/_officer/notify`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'X-Officer-User': String(recipientUserId) },
+      body: JSON.stringify({ code: 'officer/core:sendoff.landed', userId: recipientUserId, id: folder, n: count }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    console.error('[sendoff] could not push:', err instanceof Error ? err.message : err);
+  }
+}
+
+/**
+ * POST /sendoff/send — multipart: any number of `file` parts, plus `toUser` or `machine`.
+ *
+ * `toUser` is an account id and writes into THEIR tree under `SendOff/<my-username>/`. `machine` is a name
+ * of my own and writes into MY tree under `SendOff/<machine>/`. Exactly one of the two.
+ */
+sendoffRouter.post('/send', async (ctx) => {
+  const me = ctx.get('user');
+  const body = ctx.get('body') as Record<string, unknown>;
+
+  // `parseBody({ all: true })` gives an array when a part repeats and a single value when it does not, so
+  // both shapes have to be accepted — a one-file send is the common case and must not need a special part.
+  const raw = body.file;
+  const files = (Array.isArray(raw) ? raw : [raw]).filter((f): f is File => f instanceof File);
+  if (!files.length) throw errors.BAD_REQUEST('at least one file is required');
+  const tooBig = files.find((f) => f.size > MAX_FILE_SIZE);
+  if (tooBig) throw errors.BAD_REQUEST(`${tooBig.name} exceeds the ${MAX_FILE_SIZE / 1024 / 1024} MB limit`);
+
+  const toUser = body.toUser === undefined || body.toUser === '' ? null : Number(body.toUser);
+  const machine = typeof body.machine === 'string' && body.machine.trim() ? body.machine.trim() : null;
+  if ((toUser === null) === (machine === null)) {
+    throw errors.BAD_REQUEST('send to exactly one of toUser or machine');
+  }
+
+  let targetUserId: number;
+  let targetAccount: { email: string; isOwner: boolean };
+  let folder: string;
+
+  if (machine) {
+    // My own machine, my own tree. The name is mine to choose and is not checked against the device
+    // registry: the registry exists to POPULATE a picker, not to be the authority on what I may call a
+    // folder in my own home.
+    targetUserId = me.id;
+    targetAccount = { email: me.email, isOwner: isOwnerRole(me.role) };
+    folder = safeSegment(machine);
+  } else {
+    if (toUser === me.id) throw errors.BAD_REQUEST('use machine to send to yourself');
+    if (!Number.isInteger(toUser) || toUser === null || toUser <= 0)
+      throw errors.BAD_REQUEST('toUser must be an account id');
+    const [recipient] = await accountsByIds([toUser]);
+    // 404, never 403, and the same answer for "no such account" as for "did not allow you". A sender must
+    // not be able to enumerate accounts, nor learn that one refused them.
+    if (!recipient) throw errors.NOT_FOUND('no such recipient');
+    const allowed = isOwnerRole(me.role) || (await maySendTo(me.id, toUser));
+    if (!allowed) throw errors.NOT_FOUND('no such recipient');
+
+    const [full] = await accountsByIds([toUser]);
+    targetUserId = toUser;
+    targetAccount = { email: recipient.email, isOwner: full?.id === 1 };
+    // From the TOKEN. This is the whole reason the folder name can be trusted.
+    folder = folderNameFor({ id: me.id, name: me.name ?? null, email: me.email });
+  }
+
+  if (!folder) throw errors.BAD_REQUEST('that name has no usable characters');
+
+  const dir = join(sendoffDirFor(targetAccount), folder);
+  await mkdir(dir, { recursive: true });
+
+  const written: { name: string; size: number }[] = [];
+  for (const file of files) {
+    const path = freePath(dir, safeFilename(file.name));
+    await Bun.write(path, await file.arrayBuffer());
+    written.push({ name: path.split('/').pop() ?? file.name, size: file.size });
+  }
+
+  void pushLanded(targetUserId, folder, written.length);
+
+  return ctx.json({ path: join('Documents', 'SendOff', folder), files: written });
+});
+
+/**
+ * GET /sendoff/targets — everything the send form needs: my machines, and who I may send to.
+ *
+ * The owner sees every account because they may send to anyone; everybody else sees only the accounts that
+ * have named them. One request rather than two, because a picker with half its options is not a picker.
+ */
+sendoffRouter.get('/targets', async (ctx) => {
+  const me = ctx.get('user');
+  const [devices, people] = await Promise.all([
+    listSendoffDevices(me.id),
+    isOwnerRole(me.role) ? listOtherAccounts(me.id) : listMyRecipients(me.id),
+  ]);
+  /*
+    `displayName` is served rather than derived, at mobile's request and for the right reason: the writer
+    already computes this exact string to name a folder, and a picker that computes its own would sooner or
+    later disagree with it — which means telling somebody the wrong place to look.
+
+    `myFolder` answers the question a picker actually wants: files I send land in the RECIPIENT's tree under
+    MY name, so it is one value for the whole list, not a field on each row.
+  */
+  return ctx.json({
+    devices,
+    people: people.map((p) => ({ ...p, displayName: displayNameFor(p) })),
+    myFolder: folderNameFor({ id: me.id, name: me.name ?? null, email: me.email }),
+  });
+});
+
+/** GET /sendoff/senders — who I have allowed to send to me. */
+sendoffRouter.get('/senders', async (ctx) => {
+  const me = ctx.get('user');
+  const [allowed, everyone] = await Promise.all([listAllowedSenders(me.id), listOtherAccounts(me.id)]);
+  const allowedIds = new Set(allowed.map((a) => a.id));
+  // Both lists, so the UI can render a set of toggles rather than an "add" flow over an account picker.
+  return ctx.json({ allowed, candidates: everyone.map((p) => ({ ...p, allowed: allowedIds.has(p.id) })) });
+});
+
+sendoffRouter.post('/senders', async (ctx) => {
+  const me = ctx.get('user');
+  const body = ctx.get('body') as { userId?: number };
+  const id = Number(body?.userId);
+  if (!Number.isInteger(id) || id <= 0) throw errors.BAD_REQUEST('userId is required');
+  if (id === me.id) throw errors.BAD_REQUEST('you can always send to yourself');
+  const [account] = await accountsByIds([id]);
+  if (!account) throw errors.NOT_FOUND('no such account');
+  await allowSender(me.id, id);
+  return ctx.json({ ok: true });
+});
+
+sendoffRouter.delete('/senders/:userId', async (ctx) => {
+  const me = ctx.get('user');
+  const id = Number(ctx.req.param('userId'));
+  if (!Number.isInteger(id) || id <= 0) throw errors.BAD_REQUEST('userId is required');
+  // Revoking stops future sends. Files already delivered are the recipient's own files now, and deleting
+  // somebody's files as a side effect of a permission change would be its own kind of surprise.
+  await revokeSender(me.id, id);
+  return ctx.json({ ok: true });
+});
+
+/** POST /sendoff/devices — register or refresh. Idempotent on the client's own uuid; called every launch. */
+sendoffRouter.post('/devices', async (ctx) => {
+  const me = ctx.get('user');
+  const body = ctx.get('body') as { id?: string; name?: string; platform?: string };
+  const id = typeof body?.id === 'string' ? body.id.trim() : '';
+  const name = typeof body?.name === 'string' ? body.name.trim() : '';
+  if (!id || !name) throw errors.BAD_REQUEST('id and name are required');
+  if (!safeSegment(name)) throw errors.BAD_REQUEST('that name has no usable characters');
+  await upsertSendoffDevice({ id, userId: me.id, name, platform: body?.platform ?? null });
+  return ctx.json({ ok: true });
+});
+
+sendoffRouter.get('/devices', async (ctx) => ctx.json({ devices: await listSendoffDevices(ctx.get('user').id) }));
+
+sendoffRouter.patch('/devices/:id', async (ctx) => {
+  const me = ctx.get('user');
+  const body = ctx.get('body') as { name?: string };
+  const name = typeof body?.name === 'string' ? body.name.trim() : '';
+  if (!name || !safeSegment(name)) throw errors.BAD_REQUEST('name is required');
+  if (!(await renameSendoffDevice(me.id, ctx.req.param('id'), name))) throw errors.NOT_FOUND('no such device');
+  return ctx.json({ ok: true });
+});
+
+sendoffRouter.delete('/devices/:id', async (ctx) => {
+  const me = ctx.get('user');
+  if (!(await deleteSendoffDevice(me.id, ctx.req.param('id')))) throw errors.NOT_FOUND('no such device');
+  return ctx.json({ ok: true });
+});

src/servers/api/themes/favorites.ts

@@ -0,0 +1,44 @@
+import type { Context } from 'hono';
+import { listThemeFavorites, setThemeFavorite } from 'officerdb';
+import { createRouter } from '../../create-router';
+
+/*
+  Starred themes, per account.
+
+  ── Why this is not on `/themes` ──
+
+  Because that prefix is deliberately UNAUTHENTICATED: the sign-in screen renders in the chosen theme, so
+  the list and the stylesheets have to be readable before anyone has an account. A per-account preference on
+  an anonymous prefix has no caller to attribute it to — the first version of this lived there and answered
+  500 to an anonymous GET, which was the honest consequence arriving early.
+
+  ── Why the `account` permission ──
+
+  It is `core`, so every account holds it and it cannot be denied, and it already owns `/user`, `/dock` and
+  `/api-keys` — preferences and credentials belonging to the caller themselves. A theme favourite is the
+  same shape as a dock preference: it grants nothing, it is about this account's own eyes, and denying it
+  would only mean an account that can choose a theme cannot remember which ones it liked.
+
+  Every route here reads `user.id` from the token. None of them names an account, so there is nothing to get
+  wrong about whose stars these are.
+*/
+export const themeFavoritesRouter = createRouter();
+
+// GET /theme-favorites — this account's starred theme ids.
+themeFavoritesRouter.get('/', async (ctx: Context) => {
+  const user = ctx.get('user');
+  return ctx.json({ favorites: await listThemeFavorites(user.id) });
+});
+
+// PUT /theme-favorites/:id — star or unstar one.
+//
+// PUT rather than POST because it SETS a state rather than appending: sending `{favorite:true}` twice ends
+// where sending it once does, which is what a double-tap and two racing tabs both need. The store is
+// idempotent in both directions for the same reason.
+themeFavoritesRouter.put('/:id', async (ctx: Context) => {
+  const user = ctx.get('user');
+  const themeId = ctx.req.param('id');
+  const body = await ctx.req.json().catch(() => ({}) as Record<string, unknown>);
+  const favorite = body.favorite !== false;
+  return ctx.json({ themeId, favorite: await setThemeFavorite(user.id, themeId, favorite) });
+});

src/servers/api/themes/themes.ts

@@ -5,6 +5,12 @@ import { discoverThemes, readThemeCss } from '../../themes/discover';
 /**
  * Installed themes — the ones in `platform/themes/`, not the ones the platform ships.
  *
+ * **This prefix is UNAUTHENTICATED** (`UNPROTECTED_API_PREFIXES` in hono.ts) and must stay that way: the
+ * sign-in screen paints in the chosen theme, before any account exists to ask. So nothing per-account can
+ * live here — theme FAVOURITES are on `/theme-favorites`, behind the `account` permission, for exactly that
+ * reason. Adding them here returned 500 on an anonymous request, which was the polite version of the
+ * problem.
+ *
  * The shipped themes are compiled into the bundle and need no server. These are read off disk at request
  * time, so dropping a directory in makes a theme appear on the next page load. No install step, no
  * rebuild, no restart — a theme is CSS custom properties, and none of that needs compiling.

src/servers/data-path.ts

@@ -219,6 +219,21 @@ export const getEmailAttachmentCacheDir = (ownerEmail: string) =>
  */
 export const getCommandersDir = (email: string) => join(DATA_PATH, email, 'commanders');
 
+/**
+ * Where a commander records what it spawned — one directory per commander, named by its session id.
+ *
+ * Beside the transcripts rather than inside them: a transcript is the harness's file and the platform does
+ * not write into it. `spawned` is a plain newline-delimited list of session ids, appended by the loop the
+ * commander started, because nothing else CAN know them — a spawned agent's id is not recoverable from its
+ * process (no open descriptor, nothing in its environment) and its transcript is indistinguishable from any
+ * other session's.
+ *
+ * That makes this record load-bearing rather than convenient. Without it a commander cannot be deleted
+ * completely, its children cannot be followed, and its cost cannot be totalled.
+ */
+export const getCommanderStateDir = (email: string, sessionId: string) =>
+  join(DATA_PATH, email, 'commander-state', sessionId);
+
 /**
  * Which mail account's store to use, found on DISK rather than by asking the database.
  *

src/servers/hono.ts

@@ -6,6 +6,7 @@ import { authRouter } from './api/auth';
 import { serverSettingsRouter } from './api/server-settings/server-settings';
 import { landingPageDataRouter } from './api/landing-page-data/landing-page-data';
 import { themesRouter } from './api/themes/themes';
+import { themeFavoritesRouter } from './api/themes/favorites';
 import { waitlistRouter } from './api/waitlist/waitlist';
 import { usersRouter } from './api/users/users-router';
 import { apiKeysRouter } from './api/api-keys/router';
@@ -25,6 +26,8 @@ import { pluginsRouter } from './api/plugins/router';
 import { isPluginPublicPath, pluginForProtocolHeaders } from './plugins/public-paths';
 import { agentHandoffRouter } from './api/agent-handoff/router';
 import { terminalRouter } from './api/terminal/sidecar-server';
+import { minesweeperRouter } from './api/minesweeper/router';
+import { sendoffRouter } from './api/sendoff/router';
 import { caldavRouter } from './api/dav/sidecar-server';
 // import { memosRouter } from './api/memos/router';
 import { appStoreRouter } from './api/app-store/router';
@@ -122,6 +125,8 @@ const isDavPath = (path: string) =>
 // disambiguate. `/pipeline-jobs` and `/jobs` deliberately share one router.
 const PROTECTED_MOUNTS: [prefix: string, router: ReturnType<typeof createRouter>][] = [
   ['/server-settings', serverSettingsRouter],
+  // Protected, unlike `/themes` beside it — see api/themes/favorites.ts for why they are separate mounts.
+  ['/theme-favorites', themeFavoritesRouter],
   ['/users', usersRouter],
   ['/skills', skillsRouter],
   ['/tasks', tasksRouter],
@@ -136,6 +141,8 @@ const PROTECTED_MOUNTS: [prefix: string, router: ReturnType<typeof createRouter>
   ['/dashboards', dashboardsRouter],
   ['/file-browser', fileBrowserRouter],
   ['/terminal', terminalRouter],
+  ['/minesweeper', minesweeperRouter],
+  ['/sendoff', sendoffRouter],
   // ['/memos', memosRouter],  // plugin — switched off 2026-08-13
   ['/app-store', appStoreRouter],
   ['/plugins', pluginsRouter],

src/servers/notifications/catalogue.ts

@@ -99,6 +99,22 @@ const CORE_ENTRIES: Record<string, NotificationEntry> = {
     route: 'officer://jobs/{id}',
     thread: 'officer/core:job',
   },
+  /*
+    SendOff. `id` is the FOLDER — a username, or one of your own machine names — and `n` is how many
+    files landed, so the device renders "3 file(s) from andre" and the route opens that directory.
+  
+    A folder name and a count travel, and nothing else: no filename, no path, no size. That is a
+    deliberate relaxation of "content does not travel" rather than an oversight — the owner's call, on
+    the grounds that the file itself never leaves the tailnet, and a notification nobody can act on is
+    not worth sending. A filename would be content; whose folder it is, is addressing.
+  */
+  'officer/core:sendoff.landed': {
+    title: 'SendOff',
+    body: '{n} file(s) from {id}',
+    target: 'mobile',
+    route: 'officer://files?path=Documents/SendOff/{id}',
+    thread: 'sendoff:{id}',
+  },
   'officer/core:job-failed': {
     title: 'Job failed',
     target: 'mobile',

src/servers/permissions/authorize.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, test } from 'bun:test';
+import type { UserRole } from 'officerdb';
+import type { EffectivePermissions } from './authorize';
+import { decideApiRequest, decideWsProvider, resolveEffectivePermissions } from './authorize';
+import type { PermissionLevel } from './registry';
+import { CORE_PERMISSIONS } from './registry';
+
+/*
+  The resolver, which its own header calls the file standing between a Member and a shell — and which had no
+  automated tests at all until 2026-08-22.
+
+  It had none because every path needed two database calls. The decisions are now split from the fetching
+  (`resolveEffectivePermissions`, `decideApiRequest`, `decideWsProvider` are pure), so this file needs no
+  mock, no database and no `officerdb` stub — which matters beyond convenience: the one file in this
+  repository that mocks `officerdb` leaks its stub into whatever runs after it.
+
+  REAL registry keys throughout, deliberately. A suite built on invented permissions would keep passing
+  after a rename, which is the failure mode a test of an authorization table can least afford. If a key here
+  disappears, this file should go red.
+*/
+
+const member = (osUser: string | null = 'm1'): { role: UserRole; osUser: string | null } => ({
+  role: 'Member',
+  osUser,
+});
+const grants = (...pairs: Array<[string, PermissionLevel]>) => new Map<string, PermissionLevel>(pairs);
+const resolve = (user: { role: UserRole; osUser: string | null }, g = grants()) => resolveEffectivePermissions(user, g);
+
+/** No account at all — an unauthenticated or deleted caller, as the async wrapper reports it. */
+const NOBODY: EffectivePermissions = { isOwner: false, grants: new Map() };
+
+describe('resolving what an account holds', () => {
+  test('the owner bypasses, and carries no grants to consult', () => {
+    const owner = resolve({ role: 'Super Admin', osUser: null });
+    expect(owner.isOwner).toBe(true);
+    // Empty on purpose: an owner's grants are never read, and filling them would invite somebody to.
+    expect(owner.grants.size).toBe(0);
+  });
+
+  test('a member gets every core permission at write, granted nothing', () => {
+    const held = resolve(member()).grants;
+    for (const permission of CORE_PERMISSIONS) expect(held.get(permission.key)).toBe('write');
+  });
+
+  test('core is write even though nothing granted it', () => {
+    // A read-only "change your own password" is not a coherent thing to offer, which is why core is not
+    // levelled. Pinned because a future levels-everywhere refactor would silently break it.
+    expect(resolve(member()).grants.get('account')).toBe('write');
+  });
+
+  test('an app grant is honoured at the level given', () => {
+    expect(resolve(member(), grants(['calendar', 'read'])).grants.get('calendar')).toBe('read');
+    expect(resolve(member(), grants(['calendar', 'write'])).grants.get('calendar')).toBe('write');
+  });
+
+  // The rule that only exists because getOwnerHomeDir ignores its argument: a confined grant with no Linux
+  // user to confine to would resolve to the OWNER's home.
+  test('a confined grant needs a Linux account', () => {
+    expect(resolve(member('m1'), grants(['files', 'write'])).grants.get('files')).toBe('write');
+    expect(resolve(member(null), grants(['files', 'write'])).grants.has('files')).toBe(false);
+  });
+
+  test('every confined permission is dropped together, not one by one', () => {
+    const held = resolve(member(null), grants(['files', 'write'], ['terminal', 'write'], ['chat', 'write']));
+    for (const key of ['files', 'terminal', 'chat']) expect(held.grants.has(key)).toBe(false);
+  });
+
+  // The database has no CHECK stopping these rows; the API refuses to write one. This is the layer that
+  // has to hold if one ever exists.
+  test('an execution grant in the table is ignored', () => {
+    expect(resolve(member(), grants(['tasks', 'write'])).grants.has('tasks')).toBe(false);
+  });
+
+  test('an admin grant in the table is ignored', () => {
+    expect(resolve(member(), grants(['user-admin', 'write'])).grants.has('user-admin')).toBe(false);
+    expect(resolve(member(), grants(['server-admin', 'write'])).grants.has('server-admin')).toBe(false);
+  });
+
+  test('a grant naming a permission that no longer exists is ignored', () => {
+    const held = resolve(member(), grants(['cliamp', 'write'], ['a-plugin-uninstalled-last-year', 'read']));
+    expect(held.grants.has('cliamp')).toBe(false);
+    expect(held.grants.has('a-plugin-uninstalled-last-year')).toBe(false);
+    // …and does not disturb what is legitimately held.
+    expect(held.grants.get('account')).toBe('write');
+  });
+});
+
+describe('deciding an HTTP request', () => {
+  const owner: EffectivePermissions = { isOwner: true, grants: new Map() };
+
+  test('the owner is allowed anything, including paths nothing serves', () => {
+    expect(decideApiRequest(owner, 'DELETE', '/api/users/9').allowed).toBe(true);
+    expect(decideApiRequest(owner, 'GET', '/api/nothing-serves-this').allowed).toBe(true);
+  });
+
+  test('a path no permission covers is refused, not allowed by default', () => {
+    const d = decideApiRequest(NOBODY, 'GET', '/api/nothing-serves-this');
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain('no permission covers this path');
+  });
+
+  test('an execution permission is refused however it is granted', () => {
+    // Refused by KIND, before any grant lookup — so a row granting it changes nothing.
+    const forged = resolve(member(), grants(['tasks', 'write']));
+    const d = decideApiRequest(forged, 'GET', '/api/tasks');
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain('runs as the server owner');
+  });
+
+  test('an admin permission is refused', () => {
+    const d = decideApiRequest(resolve(member()), 'GET', '/api/users');
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain('restricted to the server owner');
+  });
+
+  // The one self-service route in the registry: updating your own profile lives on the router that also
+  // holds account administration.
+  test('a self-service route is allowed with no grant at all', () => {
+    expect(decideApiRequest(resolve(member()), 'PUT', '/api/users').allowed).toBe(true);
+  });
+
+  test('self-service is exact — neither the method nor the path may drift', () => {
+    expect(decideApiRequest(resolve(member()), 'POST', '/api/users').allowed).toBe(false);
+    expect(decideApiRequest(resolve(member()), 'PUT', '/api/users/7').allowed).toBe(false);
+  });
+
+  test('no grant means no access, with the permission named', () => {
+    const d = decideApiRequest(resolve(member()), 'GET', '/api/file-browser');
+    expect(d.allowed).toBe(false);
+    expect(d.reason).toContain('your role does not have access to');
+  });
+
+  test('read grants reads and refuses writes', () => {
+    const held = resolve(member('m1'), grants(['files', 'read']));
+    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(true);
+    const write = decideApiRequest(held, 'POST', '/api/file-browser');
+    expect(write.allowed).toBe(false);
+    expect(write.reason).toContain('read-only');
+  });
+
+  test('write grants both', () => {
+    const held = resolve(member('m1'), grants(['files', 'write']));
+    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(true);
+    expect(decideApiRequest(held, 'POST', '/api/file-browser').allowed).toBe(true);
+  });
+
+  // A read that has to be a POST — the body is too big for a query string — must not need write.
+  //
+  // The path is `/api/file-browser/download`, not `/api/download`: readOnlyWrites entries are RELATIVE to
+  // the permission's own api prefix. Worth a comment because the absolute form looks right, is what I wrote
+  // first, and fails as "no permission covers this path" rather than as a level problem — a misleading
+  // error for a misleading path.
+  test('a readOnlyWrites path is allowed at read level', () => {
+    const held = resolve(member('m1'), grants(['files', 'read']));
+    expect(decideApiRequest(held, 'POST', '/api/file-browser/download').allowed).toBe(true);
+    // And the same POST elsewhere under the prefix still needs write.
+    expect(decideApiRequest(held, 'POST', '/api/file-browser/move').allowed).toBe(false);
+  });
+
+  // The two rules composing: granted, but with no kernel boundary to be granted inside.
+  test('a granted confined permission is still refused without a Linux account', () => {
+    const held = resolve(member(null), grants(['files', 'write']));
+    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(false);
+  });
+
+  test('an unauthenticated caller is refused everything', () => {
+    for (const path of ['/api/file-browser', '/api/chat', '/api/users', '/api/tasks']) {
+      expect(decideApiRequest(NOBODY, 'GET', path).allowed).toBe(false);
+    }
+  });
+});
+
+describe('deciding a websocket', () => {
+  test('the owner opens anything', () => {
+    expect(decideWsProvider({ isOwner: true, grants: new Map() }, 'terminal')).toBe(true);
+  });
+
+  test('a provider no permission claims is refused', () => {
+    expect(decideWsProvider(resolve(member()), 'not-a-provider')).toBe(false);
+  });
+
+  test('a confined socket needs the grant AND the Linux account', () => {
+    expect(decideWsProvider(resolve(member('m1'), grants(['terminal', 'read'])), 'terminal')).toBe(true);
+    expect(decideWsProvider(resolve(member(null), grants(['terminal', 'read'])), 'terminal')).toBe(false);
+  });
+
+  // No method to reason about, so any level opens it. Pinned because "read-only socket" is a tempting idea
+  // that would silently close terminals granted at read.
+  test('read is enough — a socket has no method', () => {
+    expect(decideWsProvider(resolve(member('m1'), grants(['chat', 'read'])), 'chat')).toBe(true);
+    expect(decideWsProvider(resolve(member('m1'), grants(['chat', 'read'])), 'chat-notify')).toBe(true);
+  });
+
+  test("an execution permission's socket is refused however it is granted", () => {
+    const forged = resolve(member('m1'), grants(['tasks', 'write']));
+    expect(decideWsProvider(forged, 'task-runner')).toBe(false);
+    expect(decideWsProvider(forged, 'pipeline')).toBe(false);
+  });
+
+  test('an unauthenticated caller opens nothing', () => {
+    for (const p of ['terminal', 'chat', 'task-runner', 'sidecar']) expect(decideWsProvider(NOBODY, p)).toBe(false);
+  });
+});
+
+/*
+  NOT covered here, and stated rather than left as a gap somebody has to notice:
+
+  - `isOwnerOnlyRoute`. No permission in the registry declares `ownerOnly` yet — the field was added on
+    2026-08-21 for plugin settings routes and has no user. It is checked before self-service and before
+    kind, which is the part worth a test, and it cannot get one until a real permission uses it. Covering it
+    with an invented permission would test this file's fixtures rather than the registry.
+  - The grant cache and `invalidateRoleGrants`. They live on the async side, around a database call, which
+    is exactly the half this split moved away from. Their contract — the one writer in
+    `api/users/permissions-routes.ts` calls the invalidator — is a claim about call sites, not about logic,
+    and a test here could only re-state it.
+*/