release 2026.08.23.01

The commander creation flow rebuilt end to end, the delete path that actually
removes one, /minesweeper, and docs:check.

Schema change — command_hq_spawned is new and command_hq_sessions gains name, so
bun db:push is a step. No dependency change; bun.lock is untouched.

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

.gitignore

@@ -105,6 +105,13 @@ src/databases/officer_db/migrations/
 # to the platform; the plugins do not.
 /plugins/*/
 
+# Generated by src/servers/plugins/npm-deps.ts from every plugin's `npmDependencies`, and installed into
+# plugins/node_modules/. It describes whichever plugins are on THIS machine, so committing one would
+# claim a dependency set nobody chose. The rule above only ignores directories, so these need naming.
+/plugins/package.json
+/plugins/bun.lock
+/plugins/bun.lockb
+
 # Visual baselines for the theme extraction — large, machine-specific, regenerate with scripts/theme-snapshot.ts
 .snapshots/
 

BLOCKERS.md

@@ -0,0 +1,190 @@
+# Atelier extraction — blockers and decisions made without asking
+
+Unattended run, started 2026-08-20. Per the kickoff prompt: decisions made here without being able to
+ask, in the order found. Nobody is awake; each entry says what I did and why, then the run continues.
+
+## Map, before anything moved
+
+Grepped the whole platform for `atelier` (case-insensitive, every `.ts`/`.tsx`/`.md`/`.json`/`.cjs`
+file). Two hits, both incidental:
+
+- `src/workspaces/officerdev/src/apps/Chat/components/chat-images.test.ts:10` — a test fixture using
+  `https://atelier.officer.dev/images/....png` as an example markdown image URL. Not a dependency.
+- `src/servers/api/chat/task-restart.ts:181` — a comment mentioning a stray `bun dev` process that once
+  ran from `~/dockers/officer-atelier` and got respawned by accident. Historical, not a dependency.
+
+**No platform code imports anything from Atelier, and Atelier imports nothing from the platform.**
+Unlike music/offscale, there is no reverse dependency to find and no "this stays behind" piece. It comes
+out whole, the way offscale did before the imports were found — except here there really are none.
+
+Also checked: `ecosystem.config.cjs` (platform's own) has no `atelier` entry — the standalone service is
+managed by its OWN `ecosystem.config.cjs` inside `~/officer-dev/dockers/officer-atelier/`, entirely
+outside this repository.
+
+## The standalone service stays running, untouched
+
+`officer-atelier` (PM2, port 3002) is a **live production service** — its own `ecosystem.config.cjs` says
+plainly "this is the instance the mobile app talks to, so it holds still." It serves
+`https://atelier.officer.dev` via nginx and holds real data (87 generations, 2 collections, 5 providers,
+1 provider_settings row, checked directly against Postgres).
+
+I am not stopping it, not touching its nginx config, not touching its PM2 entry, and not touching the
+mobile app. This extraction adds a new, additive plugin inside the platform; cutting the mobile app over
+to it (or deciding whether to) is the owner's call, not mine to make unattended. Recorded here so nobody
+reads the plugin's existence as "the old service is now redundant, kill it" — it is not redundant until
+someone repoints the mobile app.
+
+## Decision 3 — database rows checked, both non-empty → database stays separate
+
+Queried the live `atelier` Postgres database directly (via a throwaway `postgres` client, same
+credentials as `.env.production.local`):
+
+```
+collections         2
+collection_items    73
+provider_settings    1
+providers            5
+generations          87
+```
+
+`collections` (2) and `provider_settings` (1) are the two tables the brief named — both non-empty. Per
+decision 3: **the `atelier` database stays separate**, not folded into `officer_db`. No
+`plugins/atelier/db/schema.ts` (that convention is for `officer_db`-prefixed tables); the sidecar keeps
+its own Postgres connection to the `atelier` database, exactly as today, just running from inside the
+plugin's `sidecar/` directory instead of a standalone repo.
+
+**The brief undersold the schema.** It says "tables: collections, provider_settings" — the real schema
+has five: `generations` (the actual data — 87 rows, prompts/images/costs), `collection_items` (the join
+table), `providers` (configured adapter+model+key rows — 5 of them; a newer, richer replacement for
+`provider_settings` that the brief doesn't mention at all), plus the two named. `generations` alone
+being non-empty would have settled decision 3 on its own. Following the letter of decision 3 (check the
+two named tables) rather than re-deriving it from the fuller schema, since both answers point the same
+way here.
+
+**Migration to `officer_db` is a real follow-up**, not done here: fold `collections`, `collection_items`,
+`providers`, `provider_settings`, `generations` into `officer_db` as `atelier_*`-prefixed tables once
+someone is awake to watch a real data migration. Until then the plugin's sidecar owns a second Postgres
+connection, to a second database, which is new territory for this plugin system (every other plugin's
+`db/` is officer_db-prefixed tables) — documented in PLUGIN.md.
+
+## Postgres connection for the separate database
+
+The sidecar needs its own connection string. Added `ATELIER_POSTGRES_URL` as a new platform `.env`
+variable (same pattern as `OFFICERDEV_POSTGRES_URL` for officer's own database) rather than routing it
+through the secret store — a database URL carrying a password is handled as a plain `.env` value
+everywhere else in this codebase (`OFFICERDEV_POSTGRES_URL` itself), and the secret store's own docs
+scope it to "every encryption and signing key the platform uses" plus foreign bearer credentials
+(APNs, FCM, webhooks) — not connection strings. Kept consistent with the existing convention rather than
+inventing a new one.
+
+**Not set automatically.** I don't have a safe way to guess whether the owner wants the plugin sidecar
+to point at the _existing_ `atelier` database (sharing state with the still-running standalone service —
+two writers to one queue table, which `generations.status` and the `claimableGenerations`/`markRunning`
+claim logic were written assuming is single-process) or a fresh one. Left unset, with a clear startup
+error, and documented in PLUGIN.md. **Do not just paste the standalone service's `POSTGRES_URL` in and
+restart both** — two processes racing the same `generations` queue is exactly the hazard `markRunning`'s
+atomic claim exists to prevent for restarts of _one_ process, not for two live ones.
+
+## Decision 2 — Providers as an Officer settings screen, against a direct precedent
+
+Found `IntegrationsSettings/index.tsx`'s own comment, written when email was extracted on 2026-08-18:
+
+> "Email account management left with the feature (`plugins/email/`). A plugin contributes panels, not
+> settings sections, so it now lives inside the email workspace itself."
+
+That is the opposite of decision 2, written five days before this run, in the exact settings screen
+decision 2 points Atelier's Providers into. Per the brief's own instructions ("if you find evidence one
+is wrong, write it down, follow the decision anyway"): implemented Providers as a genuine platform
+settings section — `IntegrationsSettings` gained an "Atelier" entry under the Enterprise tab — as new
+**platform** code (`src/apps/officer-web/...`) that talks to `/api/atelier/providers` over HTTP via
+`useClient`, same as any other authenticated screen. It does not import anything from
+`plugins/atelier/`, so it does not violate "a plugin importing platform code is fine; the reverse is
+not" — there is no import in either direction, only an HTTP call, which is what every frontend/backend
+pair in this codebase already is.
+
+Recording the contradiction here rather than silently picking the email precedent, since decision 2 was
+explicit and pre-made.
+
+## Images served through an authenticated route, not the old `PUBLIC_URL` scheme
+
+The standalone service served `/images/*` unauthenticated, off Bun's top-level route table, with
+`PUBLIC_URL` baked into every response so the URL was durable outside the process. Per "What you may NOT
+do", that is gone: images are served from `GET /api/atelier/files/:filename`, mounted like every other
+route, behind the permission gate. Named `files` rather than `images` so it cannot sit one path segment
+away from `/api/atelier/images/generations/:id` — the JSON job API already owns `/images`.
+
+The frontend needs `<img src>` to carry a credential a browser cannot put in an `Authorization` header.
+Used the platform's existing `?token=` escape hatch — already read by both
+`permission-gate.ts:37` and `user-middleware.ts:22`, already used by `FileViewer/file-types.ts` for
+exactly this (`getRawUrl`, `getAudioTracksUrl`, ...) for the file browser's raw/audio/subtitle routes.
+Not a new mechanism, not an unauthenticated route: the same query-token path every other authenticated
+media URL in this app already takes.
+
+## `sharp` added as a direct dependency
+
+Atelier's `inspect.ts` uses `sharp` to measure width/height/alpha-channel/opacity of a written image —
+load-bearing (it is how a `background: transparent` request that silently produced an opaque image gets
+caught). `sharp@0.33.5` was already resolved in `bun.lock` as an optional transitive dependency of
+`next`, so promoting it to a direct dependency of the platform added no new resolution — verified the
+lockfile diff is exactly that promotion, nothing else moved. Done via the documented dance:
+`frozenLockfile` commented out in `bunfig.toml` for one `bun install`, restored immediately after,
+diff reviewed before committing both files.
+
+## Publishing to the Marketplace — not done, left as the one open step
+
+`plugins/atelier/` is its own local git repository (`git init`, per "Done means"), but I did not create
+`gitea.officer.dev/plugins/atelier` or push to it. I found no Gitea API token or credential available to
+this session, and creating a new repository on a shared Gitea instance and registering it in the
+marketplace catalogue (`scripts/marketplace-sync.ts`, `BUNDLED` in `src/servers/plugins/marketplace.ts`)
+is exactly the kind of action with effects beyond this local checkout that the run's own ground rules
+say to flag rather than take unilaterally, especially with no verified way to confirm it succeeded.
+
+Left for the owner:
+
+```
+cd plugins/atelier
+git remote add origin git@gitea.officer.dev:plugins/atelier.git   # after creating the repo on Gitea
+git push -u origin main
+cd ../..
+bun --env-file=.env scripts/marketplace-sync.ts
+```
+
+Then add a `BUNDLED` entry in `src/servers/plugins/marketplace.ts` (offline fallback), matching the
+other three plugins' entries.
+
+Until that happens, the plugin still installs fine from a checkout that already has the directory
+(`plugins/atelier/` committed to its own local repo, present on disk) — it just cannot be discovered by
+the Marketplace screen on a machine that has never had it, per "Done means" #2. This is the one piece of
+"done" I could not complete unattended.
+
+## No `plugins/atelier/db/`, on purpose
+
+"Done means" lists `db/` among the plugin's expected pieces, matching offscale's and music's shape. This
+plugin has no `db/schema.ts` at all — `discoverPlugins()` correctly reports `schema: null` for it. That
+convention is specifically for `officer_db`-prefixed tables pushed by `pushPluginSchema`; decision 3
+keeps Atelier's tables in their own separate Postgres database instead, so there is nothing for that
+convention to describe. The database code lives inside `sidecar/db/` as an internal implementation
+detail of the sidecar process, not as a platform-recognised `db/` directory. Documented in full in
+`plugins/atelier/PLUGIN.md`, under "The database".
+
+## What I verified, and what I deliberately did not
+
+- `bunx tsgo`: clean throughout.
+- `bun test`: baseline 1041 pass / 0 fail / 90 files → after this run, 1069 pass / 0 fail / 92 files.
+  The two new files are the ported `serialize.test.ts` and `generations/response.test.ts`. No
+  regressions, file count only grew.
+- `discoverPlugins()` finds the plugin and the manifest validates with no problems.
+- The platform-side proxy router mounts and correctly 503s with no sidecar running.
+- The sidecar's own Hono app was exercised directly against the real `atelier_dev` Postgres database
+  (not `officer_db`, not the production `atelier` database) with real HTTP requests and no port bound:
+  providers, providers/adapters, collections and images all answered correctly; a missing file 404s; an
+  unknown route gets the OpenAI-shaped error envelope; provider rows whose keys were encrypted under the
+  standalone service's own key correctly fail to decrypt rather than crashing (a fresh `secret.key` was
+  generated for this checkout at `$OFFICER_ROOT/data/atelier/secret.key`, which is expected and correct
+  — see PLUGIN.md).
+- **Deliberately not done**: installing the plugin through the live, running `officer` PM2 process. That
+  process serves the owner's real session, its `plugins/` directory is the main checkout (not this
+  worktree, so it would not even find this code), and going through its install flow would write a real
+  `plugin_installs` row into the shared production `officer` Postgres database from a session with no way
+  to confirm the result against a live browser. Full PM2 install/enable/disable/uninstall/purge cycle,
+  per the runbook's verification table, is left for the owner — noted as open item 5 in PLUGIN.md.

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). **19 entries as of 2026-08-22** — verified by `bun run docs:check`, which fails if this number drifts again: 5 core, 3 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,
@@ -421,6 +445,9 @@ explaining why it was safe.
 
 - `docs/navigation-audit.md` — **authoritative** on routing/navigation: the opaque-click anti-pattern,
   a severity-ranked findings table, the channel-selection map and the four-phase plan
+- `docs/email-recall.md` — **design, not built**: recall over your own correspondence. The split that
+  matters is counting (needs every message judged) versus retrieval (needs the best few, fast) — and why
+  a number produced by searching is confidently wrong with no signal that it is
 - `docs/find-my-device.md` — **design, not built**: locating your own devices from Officer. What is
   assembly (most of it), what is impossible (offline finding — there is no crowd to relay it), and the
   question to settle first, which is retention rather than anything technical
@@ -435,6 +462,21 @@ explaining why it was safe.
   mounted and what it knows, the URL-vs-channel split for panel-to-panel communication, and the
   persistence key families. Read before building a panel app. Its defect list is
   `docs/workspace-panel-todo.md`.
+- `docs/multi-server-push.md` — **design, not built**: one Officer app receiving notifications from every
+  server it is signed into. Works already, bar one missing field — and why the `mv` catalogue-version
+  check turns into an endless resync between servers without it. The server identifier is an SSO decision
+- `docs/visual-regression-plan.md` — **plan, not built**: nightly screenshot regression against a JWT
+  dashboard on a second server. The blocker is that a JWT lives in `localStorage` and iris copies only
+  cookies, so an authenticated capture silently renders the login page — plus why diffing must happen
+  before any agent is asked to look
+- `docs/plugin-dependency-scope.md` — a plugin declares WHO must be able to run each host binary. Why the
+  owner's login shell is the wrong question for a `confined` plugin, the two-part reachability check
+  (world-executable AND every parent traversable), and why members' binaries on alpha worked only because
+  one home directory happened to be mode 751
+- `docs/plugin-route-authorization.md` — **design, not built**: making a plugin's settings routes
+  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/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

TODO.md

@@ -1,713 +1,75 @@
-# TODO
+# TODO — the index
 
-Deferred work.
+Deferred work. **The items live in `todo/`, one file each**, grouped by theme; this file is the map
+over them and is GENERATED — run `bun run todo:index` after any change rather than editing it here.
+Format and the two-way-sync contract: `todo/README.md`.
 
-**Context, corrected 2026-08-07.** This file used to open by saying Officer was "collapsing from
+**Context, corrected 2026-08-07.** This list used to open by saying Officer was "collapsing from
 multi-tenant / open-source-ready to a **single-user platform**", and told you to treat multi-tenant
-indirection as accidental complexity. **That direction was reversed.** The permission permission model
+indirection as accidental complexity. **That direction was reversed.** The permission model shipped on
-shipped on 2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each
+2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each one their own
-one their own Gitea account through the platform. Per-user scoping is now a requirement, and the items
+Gitea account through the platform. Per-user scoping is now a requirement, and the items that proposed
-below that proposed deleting it have been removed rather than left to mislead the next reader.
+deleting it have been removed rather than left to mislead the next reader.
 
 What did NOT reverse: `execution` permissions (terminal, chat, tasks, files, desktop, browser) run as
 the owner's OS user and can never be granted. Indirection there really is accidental complexity.
 
-## Multi-user
+## Urgent
-
+
-- [ ] **`deprovisionOsAccount` is written but has never run against a real account.** Landed 2026-08-12 in
+- **due 2026-08-22** — **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)
-      `os-user-deprovision.ts` and wired into `deleteUserHandler`, which now refuses to delete the row when
+
-      the Linux teardown fails — so a failure is retryable instead of forgotten. Only the pure guards
+## Themes
-      (`guardDeletable`, `guardMemberTree`, `parseSubUidEntry`) have tests; the reap loop, the `chown -R`
+
-      sever and `userdel` have been exercised by nobody. `docs/deprovision-os-account.md` → "What is still
+**90 open, 25 closed**, across 29 themes.
-      unproven" has the five-step validation, and it has to happen on the production host with a throwaway
+
-      account that has **a shell left open** and **a container writing as a non-root user** — those are the
+| Theme | Open | Closed |
-      two cases the quiet path passes vacuously.
+| --- | --- | --- |
-
+| [Affordances](todo/affordances/) | 1 | 0 |
-- [ ] **The terminal replays terminal QUERIES, which get typed into the shell.** `sidecar/pty/sessions.mjs`
+| [Speaking into a session from the backend](todo/agent-delivery/) | 2 | 0 |
-      replays the whole scrollback on attach; query sequences in the buffer get re-asked, xterm.js answers,
+| [Backburner](todo/backburner/) | 2 | 0 |
-      and the answers arrive as keystrokes. Visible to a member daily. Fix is to strip query sequences in
+| [Background jobs](todo/background-jobs/) | 3 | 0 |
-      `appendBuffer`, so a replay reproduces output and never re-issues requests.
+| [Chat interface](todo/chat/) | 1 | 0 |
-
+| [Code editor](todo/code-editor/) | 1 | 0 |
-- [ ] **The web terminal renders a long URL as unreadable fragments.** Claude Code's first-run login prints
+| [Components — the shared UI layer](todo/components/) | 1 | 0 |
-      a ~400-character OAuth URL; the web terminal shows scattered characters with large gaps, nothing
+| [File watchers](todo/file-watchers/) | 1 | 0 |
-      selectable. Half worked around by `2a8f004` (OSC 52, so "press c to copy" reaches the clipboard) — the
+| [Fleet — one command across every server](todo/fleet/) | 5 | 2 |
-      rendering itself is undiagnosed. This is every new member's first five minutes.
+| [Headscale](todo/headscale/) | 0 | 5 |
-      `docs/open-threads-after-per-user-claude.md` §1 has what is known and where to start.
+| [Infra (alpha)](todo/infra/) | 7 | 0 |
-
+| [Known bugs](todo/known-bugs/) | 3 | 2 |
-- [ ] **Agent sessions are not durable, and it is one property behind three symptoms.** A sidecar restart
+| [Mobile apps](todo/mobile-apps/) | 3 | 0 |
-      loses session identity, which is why `endTurnIfAgentIsGone` must skip sessions with no recorded
+| [Multi-user](todo/multi-user/) | 16 | 5 |
-      `userId`, why a stuck "generating" spinner survives until a reconnect, and why any crash in that process
+| [Notifications](todo/notifications/) | 1 | 0 |
-      is destructive rather than merely inconvenient. Fixing the three separately would miss that they are one
+| [Plugin ecosystem — before it opens to third parties (2026-08-18)](todo/plugin-ecosystem/) | 3 | 0 |
-      missing property. `docs/open-threads-after-per-user-claude.md` §2.
+| [Plugin infrastructure](todo/plugin-infrastructure/) | 2 | 0 |
-
+| [Plugin repos — what writing their READMEs turned up](todo/plugin-repos/) | 10 | 9 |
-- [ ] **`ProcessTransport is not ready for writing` — survivable since `8c4f150`, still unexplained.** A
+| [Plugin system — gaps the email extraction found (2026-08-18)](todo/plugin-system/) | 3 | 0 |
-      floating rejection inside the SDK's own input pump, with no frames from our code, so no `await` of ours
+| [Prompt library](todo/prompt-library/) | 1 | 0 |
-      can catch it. It crashed `officer-agent` four times on 2026-08-11, once truncating a turn mid-sentence;
+| [Settings — portable, and readable by an agent](todo/settings/) | 2 | 0 |
-      the `unhandledRejection` backstop has caught it once since. Best hypothesis is the `claude` CLI exiting
+| [Shell — spotlight and the dock](todo/shell/) | 4 | 1 |
-      while `streamInput` is still pumping. It needs looking at after the next occurrence, not catching in the
+| [Sub-agents — agents spawning agents](todo/sub-agents/) | 1 | 1 |
-      act — markers to grep in `docs/open-threads-after-per-user-claude.md` §3.
+| [Sudo terminal modal](todo/sudo-terminal-modal/) | 1 | 0 |
-
+| [Tooling — the list about the list](todo/tooling/) | 1 | 0 |
-- [x] **No way to create a second account.** Fixed 2026-08-11 on `sidecar-app-store`: `POST /api/users`
+| [Transmission](todo/transmission/) | 6 | 0 |
-      (`api/users/create-user.ts`, owner-gated) plus an Add-account form in
+| [URL state — routing, query strings and selection](todo/url-state/) | 4 | 0 |
-      Settings → User management. Created accounts are `status: 'Active'` — the column defaults to
+| [Waiting on the owner to run it](todo/waiting-on-owner/) | 3 | 0 |
-      `'Unverified'` and `signin.ts` refuses anything else with a bare UNAUTHORIZED, which is the trap
+| [Workspaces & Panels](todo/workspaces-panels/) | 2 | 0 |
-      the hand-INSERT route fell into. The owner sets the password and reads it out; `passwordChangedAt`
+
-      stays null. Directories come from the shared `provisionUserDirs`/`USER_DIRS` in `data-path.ts`,
+## Records — no items, kept for the reasoning
-      which `scripts/provision-user-dirs.ts` now imports rather than restating.
+
-
+- [Affordances (2026-08-19)](todo/affordances-runtime/_index.md)
-- [ ] **Still no invite flow, and no password reset for a member.** The owner types the password and
+- [Email](todo/email/_index.md)
-      tells the person, which means the owner knows it and the member cannot change it back if they
+- [Inputs outside forms (2026-08-19) — swept, fixed, closed](todo/inputs-outside-forms/_index.md)
-      forget theirs — recovery today is delete-and-recreate. An invite (token, expiry, member sets
+- [Release-binary dependencies (2026-08-19)](todo/release-binaries/_index.md)
-      their own) needs a mail path. This is the next piece, not a nice-to-have.
+
-
+## Newest ten
-- [x] **A second Super Admin was storable, and made the owner nondeterministic.** Fixed 2026-08-11.
+
-      `ck_users_owner_is_super_admin` pins user 1's role but a row-level CHECK cannot see other rows, and
+- `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)
-      `updateUserRoleHandler` happily promoted anyone — while `getOwnerUser()` was
+- `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)
-      `WHERE role='Super Admin' LIMIT 1` with no ORDER BY. Two holders would have made "who owns this
+- `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)
-      server" a question the query plan answered, and that answer feeds the agent sidecar's identity,
+- `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)
-      vault access and origin scoping. Both write paths now refuse the role, the list endpoint offers
+- `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)
-      `assignableRoles` without it, and `getOwnerUser()` orders by id.
+- `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)
-- [ ] **`dashboards.id` is a global primary key, and ids are `slugify(name)`.** Two accounts cannot
+- `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)
-      both have a dashboard named "Home". Reachable today: six accounts exist. The recommendation on
+- `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)
-      the table is a composite PK `(user_id, id)` — it matches the `uq_dashboards_user_id` index
+- `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)
-      already there and keeps every stored `ws-layout-<id>` address valid, which uuid ids would not.
-      Note the drizzle composite-PK re-diff quirk in `databases/CLAUDE.md`. Full analysis in
-      `docs/workspace-panel-todo.md` §3.
-
-- [ ] **`permissions/authorize.ts` has no automated tests.** `registry.test.ts` covers the pure
-      registry functions and the totality check; the resolver that does the owner bypass, the grant
-      lookup, the role cache and the fail-closed catches is exercised only by hand. It is the file
-      standing between a Member and a shell.
-
-- [ ] **`assertPermissionTotality` checks the wrong list, and `registry.test.ts` has been red since
-      2026-08-13.** It is fed `Object.keys(handlers)` from `server.tsx`, but Bun serves the _route table_.
-      Those diverged when the cliamp/desktop/vault plugins were switched off: `/api/cliamp/ws` and
-      `/api/cliamp/audio/ws` are still live routes with their handlers and registry claims commented out.
-      Not exploitable — `isWsProviderAllowed` finds no permission and 403s a member; the owner upgrades onto
-      a dead socket. But the boot check that exists to stop exactly this cannot see it. Two fixes: point
-      totality at the route table, and either delete the dead routes or restore their claims. The 8 failing
-      tests in `registry.test.ts` are the same drift — `REAL_WS` still lists all nine providers as served,
-      which is why nobody noticed. Found 2026-08-14.
-
-- [ ] **No empty state for a denied screen.** A member who reaches a route their role lacks gets a
-      broken panel or an endless spinner rather than a clean refusal.
-
-- [ ] **`getOwnerHomeDir(email)` ignores its argument** whenever `HOME_DIR` is set, which it is here —
-      every caller resolves to the owner's real login home. Safe only because all seven callers sit
-      behind `execution` permissions. If per-user home confinement is ever attempted, this is the
-      function to start from.
-
-- [ ] **`pty`, `vault` and `opencode` receive no identity at all.** Every other sidecar validates
-      `X-Officer-User`. The pty sidecar keys purely on a `sessionId` from the query string and its
-      `/_officer/sessions` endpoints list and kill _every_ session on the box; vault and opencode take
-      no user argument. All three are covered today only because `terminal`, `vault` and the agent are
-      owner-only permissions — that is a correct outcome resting on the wrong layer, and it is the
-      thing to fix first if any of them is ever granted.
-
-- [ ] **Radicale is configured `type = owner_only`** (`sidecar/caldav/radicale.ts:54`) while the caldav
-      sidecar itself is fully per-user and confines every JSON read to `/dav/<userId>/`. The platform
-      side is ready for members; the CalDAV server underneath is not.
-
-- [ ] **The music library is one global index.** `sidecar/music/indexer.ts` reads `HOME_DIR` and serves
-      every account from it. Favourites, playlists and now-playing _are_ per-user. Deliberate for now
-      (one household, one library) but worth stating rather than discovering.
-
-- [ ] **`markInterruptedJobs()` and `getOldestPendingJob()` are platform-wide.** The pipeline queue is a
-      single global lane; ownership is enforced one layer up, in `pipeline-jobs-routes.ts`, by an
-      explicit `job.userId !== user.id → 404` on every by-id route. Correct today, but the queue itself
-      has no notion of whose work it is running.
-
-- [x] **Cross-user writes in the notify sidecar** (fixed 2026-08-07, this session).
-      `DELETE /_officer/devices/:token` deleted by token with no user predicate, so any account with the
-      `notify` permission could deregister another's device; and `POST /_officer/notify` let a request
-      body's `userId` override the proxy-injected `X-Officer-User`, so the same account could push to
-      another's devices. `deletePushDevice` now takes an optional `userId` (the route passes it, the
-      APNs/FCM dead-token paths deliberately do not) and the header now wins over the body.
-
-- [ ] **Remove dead `username` plumbing.** `send-claude-code.ts` declares `username` in two types
-      without using it. (`toShellUsername` is NOT dead — `server.tsx:190` and
-      `pipeline-job-manager.ts:267` both call it. The `provision.ts` caller this item used to name no
-      longer exists.)
-
-## Email
-
-Email became a plugin on 2026-08-18 (`plugins/email/`, `gitea.officer.dev/plugins/email`). Its work queue
-went with it — the open items pointed at `sidecar/email/store.ts`, a path in another repository, which is
-exactly the way a leftover list sends someone to edit files that are not there.
-
-Anything still owed to the mail client belongs in that repository's own TODO.
-
-## Transmission
-
-Phase 1 (parity with `_references/transmission-web`) shipped 2026-07-30: the `officer-transmission`
-sidecar plus `/transmission` (torrents / stats / settings). Everything below is **phase 2** — none of
-it exists in the reference app, so none of it was in scope for parity.
-
-### Probably needed regardless
-
-- [ ] **Resizable detail pane.** `TorrentsView` pins it at `DETAIL_HEIGHT = '45%'`, which is a guess.
-      Either a drag handle or a persisted height in `useLocalStorageState`, alongside the column set.
-- [ ] **Revisit `DEFAULT_VISIBLE_COLUMNS`.** Eleven of thirty, chosen before ever seeing the table
-      rendered against the real 43-torrent library. Likely wrong in both directions.
-- [ ] **Files tab on huge torrents.** `detail/FilesTab.tsx` builds the whole tree and renders every
-      node — no virtualisation. Fine at 14 files; unknown at a few thousand. If it stalls, the fix is
-      `useVirtualizer` over a flattened visible-node list, the same shape as `TorrentTable`.
-
-### Ideas, unprioritised
-
-- [ ] **Container→host path mapping.** The daemon reports its own namespace (`/downloads/complete`),
-      which is not a path on this host. A mapping table (`/downloads` → `~/hdds/08_TB_01/Torrents`,
-      `/downloadsTV` → `14_TB_02/Torrents`) would make locations clickable through to `/files` and
-      make "Set location" offer real destinations. Deliberately dropped from phase 1: the reference
-      app has no such feature, so it would have been config nothing read.
-- [ ] **Push instead of poll.** Transmission RPC has no push channel, so `useTransmissionData` polls
-      every 5s. The sidecar could poll once and fan out over a WebSocket, which is both cheaper and
-      what every other live surface in the platform already does.
-- [ ] **Cross-surface links.** Soulseek and `download-media` both land files in the same library;
-      Transmission is the third door to it. Worth a think about whether they should know about each
-      other at all.
-
-## Headscale
-
-Gaps against headscale's own API, found while reading the app on 2026-08-05 — all closed the same
-day. Kept here for what the policy work turned up, which is not obvious from the code.
-
-- [x] **ACL policy.** `/api/v1/policy` GET/PUT behind `/_officer/policy`, with a plain HuJSON textarea
-      that sends the text byte for byte and shows headscale's verdict verbatim (line and column
-      included). Officer does not pre-validate: headscale owns the only parser that resolves groups,
-      tags and hosts, and a second weaker one would disagree with the thing that actually enforces.
-      **The mode cannot be read.** A file-backed policy is still served over GET; only a PUT refuses,
-      with "update is disabled for modes other than 'database'". So the first save is what discovers
-      writability, and a refusal becomes a persistent read-only banner. Verified live, not inferred.
-
-- [x] **A node can be moved between users.** `/api/v1/node/{id}/user`, in the expanded node card next
-      to the tag editor — both being the things that decide which policy rules apply to a node.
-
-- [x] **User rename** — was already shipped end to end (`/users/:id/rename`, `UsersView`); this entry
-      was stale when it was written.
-
-- [x] **Polling** — `useHeadscaleNodes` has had `refetchInterval: 20_000` all along; also stale.
-
-- [x] **Device invites, platform side** (`COMMS/OFFSCALE_INVITE_ENROLLMENT.md` §5, built 2026-08-05).
-      Authorize-new-device form, the one-time link with copy/share/QR, and the invite list with revoke —
-      `/_officer/enroll/invites` in `invites.ts`, `InvitesView`. **The records are not Officer's.** They
-      proxy to the server's Officer Companion, because the joining phone has to claim without an Officer
-      account and this sidecar is loopback-only behind our auth; the spec's own "an invite must work when
-      the platform is down" argument says the same. Officer stores no invite and no claim token.
-      **Live on all four servers since 2026-08-05.** The 401 that blocked it was a companion-side prefix
-      parse (a Headscale key prefix is a fixed 12 chars and may contain `-`; they split on the first one);
-      fixed upstream. Verified end to end against pastilhas-eu: create returns the
-      `officer-offscale://join#…` link, list shows the record, revoke flips it to `revoked`. The list
-      envelope is not in the spec, so `pickInvites` takes the body's array whatever it is keyed under.
-      Four gaps were sent back to the spec author: `keys.ts` has no
-      sub-day key TTL for the 5-minute claim key, "the sidecar must refuse plaintext" is unenforceable
-      behind nginx, `tailnet` is not a headscale concept and has to be recorded on the invite, and
-      `/api/v1/enroll/*` collides with headscale's own namespace.
-
-## Workspaces & Panels
-
-Its own list — **`docs/workspace-panel-todo.md`** — because it is long and actively worked. Full
-analysis behind it: `COMMS/workspace-panel-framework-analysis-2026-08-07.md`.
-
-Headlines: the framework has **no panel lifecycle** (a panel can be destroyed but never told, which is
-the real cause of the terminal orphan leak); three state-key families are **silently dropped on every
-write**, orphaning a pty per reload; Running Shells has **404'd since 2026-07-31**; there are **zero
-error boundaries** anywhere in the repo; and `dashboards.id` is a **global** primary key fed by
-`slugify(name)`, so two members naming a dashboard the same thing collide.
-
-- [ ] **Renaming a panel key is a silent data migration, and the repair is destructive.** A saved layout
-      holds `appType` strings. `normalizeLayout` replaces any appType not in the allow-list with the
-      caller's `fallback`, and `WorkspaceView.tsx:97` writes that back — so a renamed key turns every
-      saved layout into N copies of whichever panel is `allowed[0]`, permanently, on one page load.
-      Renaming `headscale-*` → `offscale-*` did exactly this: `/offscale` rendered three server pickers,
-      `ServersView` never mounted, and it survived every restart because the code was correct and the
-      data was not (2026-08-17, `ed3806f9`).
-
-      Plugin screens are now cleared at install, which covers plugins and nothing else. The general fix
-      is a rule about wholesale mismatch: **a layout in which NO panel has a recognised appType is
-      residue from older code — discard it and use the screen's default**, rather than collapsing it.
-      `fallback: allowed[0]` is arbitrary (it is whatever `panels.ts` happens to list first) and should
-      probably not be a per-panel substitution at all.
-
-## Code editor
-
-- [ ] **The owner wants to go deeper here — ideas pending (noted 2026-08-15).** Raised right after the file
-      browser gained its first links into `/code-editor`. Do this after the file-browser test pass.
-
-      What is worth knowing before starting, all established on 2026-08-15:
-
-      **It has been effectively invisible for six months.** The app landed 2026-02-21 (`9e9acd96`), the
-      screen 2026-02-17, and `1fa3a659` on 2026-07-25 is titled "**restore** the code editor screen" — so
-      it was dropped and brought back at least once. It IS in `CORE_DOCK_ITEMS` as "Editor", but
-      `DEFAULT_DOCK_PATHS` is `['/', '/files', '/terminal', '/dashboards', '/chat']` and the owner's own
-      `dock_configs` row does not list it either. Until today the only way in was typing the URL.
-
-      **So it has no users, and that is the risk.** A surface nobody reached for six months is where things
-      rot quietly. Nothing about the editor itself has been verified — whether saving works, how the file
-      tree behaves, what closing the last tab does, what an unsaved-changes navigation does. Only the
-      plumbing was checked: `?file=` is read (`EDITOR_FILE_PARAM`), `/code-editor` renders with `urlState`,
-      and `CodeEditor.tsx:60-76` fetches a path that arrives in the URL rather than only matching already
-      open tabs.
-
-      **One bug of exactly this kind was already found and fixed** in the FileViewer's editor on the same
-      day: the Edit toggle was gated on `content` rather than `content !== null`, so an empty file — the
-      one "New file" produces — could not be edited at all. Assume siblings.
-
-      **Open question, deliberately not decided:** `Open in editor` in the file browser's row menu still
-      navigates to `/code-editor`, which is the last action that leaves the browser. Editing now happens
-      in place via double-click → the viewer's pane. Either `/code-editor` earns its keep as a genuinely
-      different tool (tree, tabs, multi-file) or that menu item should go.
-
-## Files app — routing
-
-**The URL model is done (2026-08-15).** The folder is the pathname —
-`/files/archive/Tests/platform/docs` — and `?view=` is a NAME within it, not a second copy of the path.
-Deep links and refresh work, which they never had. Landed across `559560de`, `98ba604a`, `7e31564c`,
-`0dc88b51`, `7359af2f`, with `files-route.ts` + 23 tests as the one owner of encoding and of which params
-belong to the overlay.
-
-Four bugs came out of that work and are fixed: closing a pane sent you home; `?view=` was stripped on
-every page load by a mount effect that had made deep links impossible since 2026-02-23; navigating kept a
-pane belonging to the folder you left; and the breadcrumb opted out of that last rule because it is a
-`<Link>` and never called the function enforcing it.
-
-- [ ] **Rows are still not links.** This is the half that did not get done, and it is the original
-      finding. Both list and grid render `<div onDoubleClick>` (`FileItem.tsx:701,748`), and search
-      results render `<div onClick>` (`FileViewContainer.tsx:187`) — the "opaque click" that
-      `docs/navigation-audit.md` names. No cmd-click into a new tab, no middle-click, not
-      link-focusable, and the target lives in a closure rather than the DOM.
-
-      It is now much easier than it was: `folderHref(path)` gives a folder's URL and `hrefForPath` gives
-      a full `To` with the overlay already stripped, so a row becomes
-      `<Link to={hrefForPath(childPath)}>` and a file row becomes a link that sets `?view=<name>`. The
-      breadcrumb has done exactly this since before today and is the model.
-
-      Watch for: a row is also a click target for SELECTION (single click selects, double opens,
-      shift/cmd extend). An anchor changes what those gestures mean by default, so the selection
-      handlers have to keep working and `preventDefault` where they win.
-
-- [ ] **The acts that clear the overlay have no owner, only the list does.** `VIEWER_PARAMS` and
-      `withoutViewerParams` live in `files-route.ts` and are shared. But every site still decides FOR
-      ITSELF whether to call them, which is precisely how the breadcrumb shipped wrong an hour after the
-      rule was written. Three bugs in a row came from this. A single `navigateToFolder()` that every
-      caller must go through — rather than a helper they may remember — is the fix if a fourth appears.
-
-- [ ] **A panel's folder is still not addressable.** `urlPath` is true only on the `/files` screen;
-      panels keep the path in local state, so they always open at their base and cannot be linked or
-      restored. Deliberate as written — a dashboard can hold two browsers and one URL cannot serve both —
-      but worth re-deciding rather than inheriting.
-
-## Release-binary dependencies (2026-08-19)
-
-Built: a plugin can declare `release: { url, identify }` for a dependency no package manager carries.
-Gitea's `tea` is the motivating case and the first user.
-
-Two things it does NOT do, both deliberate and both worth knowing:
-
-- **No checksum.** The download is verified by RUNNING it through the same `identify` rule the probe
-  uses, which catches an HTML error page, a truncated file and a wrong-architecture build — none of them
-  print what the plugin said to look for. It does not catch a compromised upstream. A checksum per
-  os/arch is a table that goes stale every release and would stop installs the day upstream re-cuts a
-  tag; HTTPS and a URL the owner reads in the install dialog is what stands behind it today.
-- **The version is pinned in the manifest.** `tea` is fixed at 0.15.1, so a new release needs a plugin
-  update. That is the right default — an install that silently fetches whatever is latest is not
-  reproducible — but there is no "check for a newer one" anywhere.
-
-## Inputs outside forms (2026-08-19) — swept, fixed, closed
-
-The "19 files" count in the previous version of this entry came from one grep
-(`components/ui/input`) and was a starting point, not the answer. A wider sweep — bare `<input>` and
-`<textarea>` too, across the platform and every installed plugin — found **87 files with a matching
-element and no enclosing `<form>`**. Three were false positives (the `Input`/`Textarea` primitives
-themselves, and a `DataTable` test file). Of the remaining 84, **41 were fixed** (real forms, single
-fields with an obvious action, or multi-field editors) and **43 were left alone**, almost all because
-they're a search/filter box with nothing to submit.
-
-**Fixed — platform (24 files, one commit):** `CapabilityPage`, `ApifyConfig`, `ApiKeys`,
-`DavAppPasswords`, `GoogleOAuthConfig`, `AIHarnessesSection` (local-provider connect, its auth step,
-and both API-key edit rows), `OCRSection`, `SMTPSection` (split into two independent forms — save vs.
-send-test-email, since one form would have made Enter in the test-email field trigger Save),
-`STTSection`, `TTSSection`, `AppStoreDetail`, `ChatHeader`, `BackgroundJobDialog`, `QuestionActivity`,
-`WebpageDialog`, `DirPickerModal`, `SessionRow`, `CommandHqCategories`, `FileItem`, `NewEntryDialog`,
-`TaskRunnerModal` (the Agentic and Pipeline ready phases), `PreviewHeader`, `widgets/DailyGoals`,
-`widgets/Pomodoro`.
-
-**Fixed — plugins (17 files, one commit per plugin, each pushed to its own remote):**
-`bitcoin-wallet` (`ChainSourceCard`, `RescanCard`, `WalletSettingsView`), `email` (`Compose`,
-`EmailAccounts`), `invoices` (`DocumentEditor`, `RecordEditors`, `SendDocumentDialog`), `offscale`
-(`NodesView` — rename and tags fields), `soulseek` (`SoulseekConnection`), `transmission`
-(`ConnectionView`, `SettingsView`, `AddTorrentDialog`, `MoveTorrentDialog`, `RenameDialog`,
-`TorrentOptionsDialog`), `vault` (`VaultPanel`). `jellyfin` and `music` needed no changes.
-
-**Left alone — search/filter boxes with no submit action** (the large majority of the 43): `JobsPage`,
-`SettingsPanel`, `SearchInput`, `sounds/Catalog`, `widgets/QuickNotes`, `Dashboards/DashboardListApp`,
-`SystemMonitor/DockerView`, `FileBrowser*` toolbar/header/view-container files, `ChatHistory` list
-filters, `invoices`' six list views (`CustomersListView`, `EstimatesListView`, `ExpensesListView`,
-`InvoicesListView`, `ItemsListView`, `ReportsView`, `components.tsx`), `jellyfin` (`PlayerControls` —
-range sliders, not text fields — and `SearchSection`), `music` (`MusicBrowser`, `MusicPlayerHost`),
-`offscale` (`Cards`, `PolicyAssistant` — already handles Enter/Shift+Enter correctly, `PolicyView` — a
-textarea, never auto-submits), `soulseek` (`SearchResults`, `SharesBrowser`), `transmission`
-(`TorrentToolbar`), `FileViewer` renderers (`AudioRenderer`/`VideoRenderer` — volume/seek sliders), and
-the main chat composers (`InputArea`, `ChatLauncher`, `SoulseekChat`) — all textareas with their own
-Enter-sends/Shift+Enter-newlines handling, where a `<form>` would add nothing and risks regressing that
-handling.
-
-**Left alone — genuinely ambiguous, flagged rather than guessed:**
-
-- `TaskRunnerModal`'s `ScriptRunner` ready phase offers three simultaneously-visible, non-equivalent
-  primary actions ("Run here" / "Queue" / "Run as job"); there's no single canonical action for Enter to
-  trigger.
-- `Dashboards/DashboardPreview`'s `NamePanel` (name + description) has its submit button in a
-  _different_, independently-mounted panel (`CreatePanel`) elsewhere in the workspace layout tree — a
-  `<form>` can't span two panels without restructuring the wizard.
-- `ColorPicker` and `MarkdownEditor` have zero call sites anywhere in the repo right now; both are
-  shaped to be embedded in a future caller's own form (uncontrolled inputs with `name` attributes, or a
-  plain controlled textarea with no submit of its own), so there's nothing to wrap yet.
-- `widgets/Weather`'s `LocationSetup` is a live autocomplete with several result rows and no single
-  obvious Enter target (which of N matches?).
-
-**Noticed, out of scope, not fixed:**
-
-- `ModelSelector`'s provider-picker button has no `type` attribute — harmless today only because it
-  currently sits outside every `<form>`; a landmine if that layout changes.
-- `MusicBrowser`'s filter input uses `(e) =>` instead of the house `ev` convention — pre-existing, not
-  touched since the file needed no fix.
-- `EmailList.tsx`, and a few plugin files touched by this sweep (`VaultPanel`, `ConnectionView`,
-  `SoulseekConnection`, `ChainSourceCard`), have pre-existing `prettier --check` drift outside the lines
-  this pass touched — left as found, not reformatted, per "don't reformat what you're not fixing."
-  Relatedly: **`prettier --write` on a `plugins/<name>/…` path silently no-ops when run from the
-  platform root**, because Prettier v3 respects the root `.gitignore` and `/plugins/*/` is in it — it
-  exits 0 with no diff and no error. Formatting a plugin file requires running prettier from inside
-  that plugin's own directory (still resolves the platform's `.prettierrc` by walking up).
-- A few "Save"/"I've saved it"-style buttons (`ApiKeys`, `DavAppPasswords`, `DirPickerModal`) have no
-  `type` attribute but currently sit outside any `<form>`, so it's harmless today — worth remembering if
-  a future edit wraps that region.
-
-## Affordances (2026-08-19)
-
-Agreed and written down in `plugins/CLAUDE.md`; **nothing is built**. An affordance is what the surface
-on the other end offers the agent — declared by the code that implements it, read at runtime. The first
-two are image rendering (core) and gitea (`git` for git, `tea` for everything else).
-
-Built 2026-08-19: `servers/affordances/load.ts` reads the tree and compiles one block, and
-`claude-manager.ts` appends it to every Claude session via
-`systemPrompt: { type: 'preset', preset: 'claude_code', append }`. Read per session, so a plugin
-installed an hour ago is live on the next message.
-
-Still to build:
-
-- `capabilities/affordances/` created by the setup script, with `officer/core/` populated from an
-  officer-capabilities repository. The directory exists on this machine by hand; a fresh install gets
-  nothing, so the first affordance is currently a local artefact rather than a shipped one.
-- **Opencode delivery.** It has its own driver and gets nothing, so image rendering is currently a claim
-  that holds on one harness — exactly the drift affordances exist to remove. Deliberate: opencode work is
-  paused pending its v2 migration and this would be thrown away. Revisit when v2 lands.
-- A bare `claude` run in a terminal on the host gets nothing either, since it never passes through
-  `claude-manager`. Would need a generated file, which is the thing `user-instance.ts` refuses to write
-  for the owner.
-- ~~Plugin contribution~~ — built 2026-08-19 (`affordances/publish.ts`). An `affordances/` directory in
-  the plugin repository is copied to `capabilities/affordances/<publisher>/<plugin>/` on install and
-  removed on uninstall. Gitea is the first to ship one.
-- **The other categories.** A plugin can contribute affordances and nothing else. Skills, tools, tasks
-  and processes are the obvious next ones and were deliberately left out — one mechanism, proven, before
-  five. When they land, `publishAffordances` generalises rather than gaining siblings.
-- **`officer/core` and `officerdev/<plugin>` are both correct — do not normalise them.** The path uses
-  `publisher` verbatim, so a plugin published by officerdev lands under `officerdev/`. `officer/core` is
-  not a plugin at all: it is the PLATFORM's own, shipped by the setup script from the capabilities
-  repository. Two spellings marking two different things, arrived at by accident and kept on purpose.
-  Anyone tidying this into one name is removing the distinction, not the inconsistency.
-
-Open, and deliberately deferred:
-
-- **Scoping.** Everything is loaded into every conversation. Fine at two files, not at twenty. A
-  `surface` field was drafted and dropped because it was doing two jobs at once: for image rendering it
-  means _what the client renders_ (a phone, a web bubble, a cron run with nobody watching), for gitea
-  _what tooling exists on this machine_. Those are different axes and one field cannot be both. Decide
-  the axis before adding the field — and note this codebase has already been bitten by a field that
-  validated itself and was never consumed (`unauthenticatedPaths`, see `plugins/public-paths.ts`).
-- **Drift.** The rule is "declared where implemented", but a hand-authored markdown file in a repository
-  is not that — `ChatImage` could stop rendering images and no file would notice. Accepted for now
-  because prose that reaches every harness beats a registry that reaches one; revisit if it bites.
-
-## Plugin ecosystem — before it opens to third parties (2026-08-18)
-
-Not now. Months away. Recorded so it is not re-derived.
-
-- [ ] **A plugin install is not pinned, so a review would bind a repository rather than code.**
-      `fetch.ts:70` is `git clone --depth 1 <source>` — no ref — so it takes whatever the default branch
-      points at when the install runs. A plugin reviewed at commit X installs at whatever was pushed
-      since, and `--depth 1` leaves no history to compare against.
-
-      This is the shape of the npm attack already documented in `CLAUDE.md` (2026-08-04), and the same
-      shape as the Chrome Web Store's real failures — not bad extensions passing review, but good ones
-      sold or compromised and then pushing an update to users who had already accepted them.
-
-      Fix: a `reviewedCommit` on the catalogue entry, checkout detached at that SHA, and **verify
-      `rev-parse HEAD` matches or refuse**. The verification is the part that matters. An update then
-      becomes "a new reviewed SHA exists" — a catalogue change rather than something the author triggers.
-
-- [ ] **Third-party plugin sidecars are unconfined.** A plugin sidecar runs `bun run <script>` with
-      `cwd: PLATFORM_DIR`, so Bun auto-loads `.env` and it gets `POSTGRES_URL`; it runs as the service
-      user, which owns `secrets/officer-keys.db` and can therefore mint an owner JWT. Fine for
-      first-party plugins, total compromise for anyone else's.
-
-      The mechanism to fix it already exists and is pointed elsewhere: `spawn-as-member.ts` drops
-      privileges with `setpriv --reset-env` and a six-name allowlist for exactly this reason.
-
-- [ ] **No install-from-git-URL.** The catalogue is the only route for a remote plugin, so the
-      "build your own, give it to a friend" path has no affordance. Small, and needed before the
-      unofficial channel is real.
-
-## Plugin system — gaps the email extraction found (2026-08-18)
-
-- [ ] **A plugin cannot declare its own npm dependencies, so the PLATFORM is carrying them.** `imapflow`,
-      `mailparser` and `@types/mailparser` are in the platform's `package.json` and are imported by nothing
-      in `src/` — they exist solely for `plugins/email/sidecar/`. Plugins have no `package.json`, run with
-      `cwd: PLATFORM_DIR`, and resolve from the platform's `node_modules`, so deleting those three lines
-      breaks the installed plugin on its first sync.
-
-      This does not scale and it is the wrong party holding the risk: the platform cannot be answerable for
-      what an arbitrary plugin decides to install, and `bunfig.toml` sets `frozenLockfile = true` precisely
-      so a dependency change is a deliberate, reviewed act. Publishing will be reviewed rather than a
-      free-for-all, which narrows the threat but does not move the responsibility.
-
-      What it probably needs: a `dependencies` field in the manifest (the manifest already holds
-      `osDependencies` for host binaries, which is the same shape of problem solved once), installed into
-      the plugin's own directory at install time rather than merged into the platform's tree. Note the
-      install path already learned not to trust `$PATH` — `pushPluginSchema` resolves a binary rather than
-      spawning `bunx` — so whatever runs the install has to do the same.
-
-      Until then: `imapflow` and `mailparser` STAY. Removing them is not tidying, it is breaking email.
-
-- [ ] **`email_accounts/` is created by the PLATFORM for every account, and should be the plugin's job.**
-      `USER_DIRS` in `data-path.ts` pre-creates it at 0700 for every user, whether or not the email plugin
-      is installed — so a core install provisions a directory named for a plugin it does not have.
-
-      Ownership should invert: the plugin provisions its own storage, in all three moments —
-
-      1. **on plugin install**, for accounts that already exist;
-      2. **on user provisioning**, for accounts created afterwards;
-      3. **lazily**, the first time a provisioned user opens the plugin, so a machine that missed either of
-         the above still heals itself.
-
-      The third is the one that makes the other two non-critical, and it belongs in the email sidecar
-      rather than in the platform's account handler.
-
-      This is entangled with the `email_db` leak below — core reads that directory today, so the plugin
-      cannot become its sole owner until that is resolved too. Do them together.
-
-- [ ] **The platform still knows email's on-disk vocabulary, deliberately, and it is untested by anything.**
-      `findEmailAccountName` in `data-path.ts` reads `DATA_PATH/<user>/email_accounts/*/emails.db` and picks
-      the newest by mtime. Two core callers use it: `user-instance.ts` (`OFFICER_EMAIL_DB`, for the agent's
-      `email_db` MCP tool) and `chat/websocket.ts` (`resolveEmailCwd`, for a chat opened against a mailbox).
-      `ChatPanelWrapper.tsx` hardcodes `workspace.id === 'email'` to trigger the second.
-
-      This traded a CODE dependency for a CONVENTION, which was the right trade at the time — the code
-      dependency is what put `officer-agent` into a restart loop on 2026-08-13 (`fbb6d6c7`). But the
-      convention has no enforcement on either side: if the plugin ever renames `emails.db`, moves to one
-      database per folder, or nests differently, core silently points the agent at a path that does not
-      exist. No import breaks, no type fails, no test covers it. The tool just goes quiet.
-
-      The clean version needs two things the platform does not have: a way for a plugin to ship an MCP tool,
-      and a way for a plugin to declare a chat context. Until both exist this stays — but it should be a
-      decision someone re-takes, not one that is inherited.
-
-## Plugin repos — what writing their READMEs turned up
-
-Three READMEs were written on 2026-08-16 (`music`, `offscale`, `example`) and pushed to their own repos.
-Writing them meant reading each plugin against its own documentation, which is the cheapest audit there
-is. Everything below was found that way and none of it is fixed.
-
-**Offscale is still branded headscale in shipped, user-visible places.**
-
-- [ ] `web/panels.ts` registers three panels named "Headscale servers", "Headscale", "Headscale" — these
-      are what a user reads in the panel picker.
-- [ ] `web/OffscaleServerPicker.tsx:26` renders the literal heading `Headscale`.
-- [ ] `web/ConsoleView.tsx:22` mints terminal session ids as `headscale-console-<id>`. That is persisted
-      state rather than a comment, so renaming it orphans live console sessions — cheap now, less so later.
-- [ ] ~12 stale `/headscale` route paths in comments across `web/`, plus `App.tsx:78` in the platform.
-- [ ] `PLUGIN.md` has ~11 stale self-references (`headscale_servers`, `listHeadscaleServers`, permission
-      key `headscale`, `/api/headscale`, panel keys, `useHeadscaleSection()`).
-
-**Documentation that actively lies.**
-
-- [ ] `plugins/offscale/PLUGIN.md:445-449` says the ACL assistant is deliberately unwired and must not be
-      wired up. It IS wired — `sidecar/assist.ts`, `claude-proxy.ts`, `web/PolicyAssistant.tsx` and the
-      manifest's `readOnlyWrites` all ship.
-- [ ] `plugins/offscale/OFFSCALE_API.md` claims to publish the contract "in full" and omits six live
-      surfaces, including all of `/_officer/companion/*` and `/_officer/enroll/invites`.
-- [ ] `plugins/music/MUSIC_API.md` says favourites and now-playing are served by the platform from
-      Postgres; the sidecar serves them itself, scoped by `X-Officer-User`. It also documents the playlist
-      item key as `<albumRel>/<file>` while the schema and favourites use the home path — the same file
-      contradicts itself.
-- [ ] `plugins/music/MUSIC_API.md` documents now-playing as one snapshot per user with no mention of
-      `?device=`, which the schema makes part of the primary key. A mobile client written to that doc is
-      correct only by accident.
-- [ ] `plugins/example/manifest.ts:12` lists `web/Router.tsx` as the frontend convention; discovery
-      requires `web/panels.ts` AND `web/layout.ts`. The same file documents an `ownerOnly` field that does
-      not exist and never did.
-- [ ] The Companion contract docs the offscale code cites (`COMMS/OFFSCALE_COMPANION_API.md`,
-      `COMMS/OFFSCALE_INVITE_ENROLLMENT.md`) exist nowhere — `COMMS/` was deleted. Two of the plugin's
-      eight sections depend on a service with no published spec.
-
-**Conventions a plugin author has to guess.** All verified in `discover.ts`/`mount.ts`, none documented
-outside the example's new README:
-
-- [ ] Panel `key`s and layout `appType`s must agree, and a mismatch fails SILENTLY — `PluginScreen.tsx`
-      pins `appTypes.allowed` with `fallback: allowed[0]`, so a typo renders the first panel.
-- [ ] The `<appName>_` table prefix is unenforced. The barrel is `export *` across every plugin into one
-      `public` schema, so two plugins choosing the same unprefixed name collide with no error until push.
-- [ ] A manifest is module-cached for the process lifetime: editing it does nothing until
-      `pm2 restart officer`, and `outdated` cannot see a version bump either.
-- [ ] Permission-key prefixing is convention, not validation. Only a collision with a CORE key is refused,
-      silently, at mount, with a console error.
-
-**Genuinely missing.**
-
-- [ ] `plugins/offscale` spawns the `ssh` binary (`sidecar/ssh.ts`) but declares no `osDependencies`, so
-      install never checks for it and the Console fails at runtime instead of refusing at install.
-      `PLUGIN.md:421` already lists it as a host dependency — the manifest is the file that is wrong.
-- [ ] `scripts/reindex-music.ts` resolves its port file from `process.env.DATA_PATH ?? cwd/data`, and
-      `DATA_PATH` stopped being an env var on 2026-08-13. Run from the repo it looks in
-      `platform/data/music/.server` and never finds it. One line.
-- [ ] `plugins/music/web/MusicPlayerHost.tsx` header says it is mounted once in the persistent
-      DashboardLayout; it moved into `MusicDetail`. That is exactly the comment that would mislead
-      someone about why playback stops off-route.
-- [ ] A plugin's `assets/icon.png` is only published while installed, so its real icon is invisible in the
-      store before install. The catalogue's `iconUrl` works around it, and an author has to know to add one.
-
-## Waiting on the owner to run it
-
-- [ ] **The AI usage panel works for one account; the multi-account half is unproven.** Landed and verified
-      live 2026-08-18 — click the harness pill in the chat composer and it shows Claude Code's own usage
-      display, limits with countdowns, tokens by day and by model.
-
-      What is NOT proven is the reason it was built: a second Anthropic login, the account tabs, and a
-      stored row surviving a switch. **Group C of `docs/ai-usage-panel.md`** is that, and test 10 is the one
-      most likely to be wrong — a refresh must not overwrite an account it could not measure, and that
-      failure is silent.
-
-      Deliberately deferred rather than forgotten: the owner switches accounts when the work needs it, and
-      the worst case is one wrong tab. Run Group C the first time a second login lands on this machine.
-
-      Also unexercised: the model dropdown no longer renders the literal string `claude-code` for a chat
-      that named no tier. Needs `officer-claude-code` restarted, not just `officer` — the parser in the
-      sidecar is what emits it.
-
-- [ ] **Plan mode is live and has never been exercised.** Landed `1b811dfa` on 2026-08-17; all three
-      processes were restarted the same evening, so the code IS running. Not one part of it has been used:
-      not the toggle, not the plan card, not the round trip from the sidecar's pending promise to a browser
-      and back, not the stored column, not `settleAllPlans`.
-
-      **`docs/chat-plan-mode-test-plan.md` is the checklist** — eleven ordered tests, what each should show,
-      and what its failure looks like. Test 4 (approve) is the one most likely to be wrong: it is the case
-      that changed the design, because approving `ExitPlanMode` drops the harness into `default` rather than
-      back into `bypassPermissions`.
-
-      Safe to leave untested. Plan mode is opt-in and off by default, so a conversation that never touches
-      the toggle behaves exactly as it did before. The one failure worth knowing in advance is a turn that
-      never ends after a plan is answered — that would be a leaked `canUseTool` promise, and
-      `pm2 restart officer-claude-code` clears it.
-
-      Design and the probe results behind it: `docs/chat-plan-mode.md`.
-
-## Known bugs
-
-- [ ] **Background job logs appeared INSIDE an open file in the code editor.** Reported 2026-08-16 by the
-      owner, on the production host, running as a member with a `bun dev` background job streaming. The
-      editor had a file open; the runner's log output was rendered into that file's buffer. **It was never
-      saved** — the file on disk was intact, and the editor was not marked dirty as far as the report goes.
-      So this is a DISPLAY-layer mixing, not a write path: the bytes reached a buffer that only exists in
-      the browser.
-
-      Not reproduced, not diagnosed, and deliberately not guessed at further than this. What is worth
-      recording is where the two streams could meet, because both were added in the same week and they are
-      the only two things writing text into a panel:
-
-      - `useTaskDetail` polls `GET /chat/tasks/:id` every 2s while a job runs and returns `{kind:'log', text}`.
-        `CodeSurface` renders it — and `CodeSurface` is shared with the editor's own surfaces.
-      - The editor keys open files by PATH (`useEditorState`), while the task panel keys by TASK ID, and
-        several panel-scoped stores in between are keyed by `panelId` through `useGlobal` /
-        `usePanelMemory`. A key collision between those namespaces would produce exactly this: one panel's
-        text arriving in another's buffer, with no server involvement and nothing persisted.
-
-      **Screenshot 2026-08-16 answers the first question and kills two theories.** The tab carries a DIRTY
-      dot, and the log lines have Monaco line numbers continuing the file's own sequence (…180, then eight
-      lines of dotenv/POSTGRES_URL output, then 189 `</Link>`). So the MODEL was mutated — this is the
-      editor's content state, not its render, and the earlier "the file was okay" means it was simply never
-      saved. Note the splice is mid-file, not a replacement: JSX text and log text share line 180
-      (`Forgot?--env-file=.env --watch src/server.tsx`).
-
-      Ruled out by that: `CodeSurface` renders with shiki, not Monaco, so the two cannot share an editor
-      instance. And the app's only other Monaco mount (`FileViewer/renderers/EditorRenderer.tsx`) passes no
-      `path`, so its model URI is `inmemory://model/N` and cannot collide with the editor's `file:///…`.
-
-      So the pollution arrives as TEXT through the editor's own content path — `openFile`, `setContent`, or
-      the end-of-turn refresh that re-reads every clean file. That last one is the prime suspect: it is the
-      only thing that writes a buffer without a keystroke, it runs exactly when a background job is
-      producing output, and it lands its result by path.
-
-      **Narrowed 2026-08-16, and a trap is now set.** `reloadFile` sets `originalContent` and clears
-      `isDirty`, so the end-of-turn refresh CANNOT produce the dirty dot in the screenshot — the refresh
-      path is out. Nothing in the app injects text into the page either: no `execCommand('insertText')`,
-      no synthetic keyboard events, no clipboard writes near the editor. That leaves Monaco's own change
-      event, which means it looks like a paste or a programmatic `executeEdits`.
-
-      **`docs/editor-buffer-corruption.md` is the procedure — read that when someone reports this.** A
-      trap is set: `reportSuspiciousEdit` in CodeEditor.tsx records any insertion over 200 characters
-      arriving while the editor is NOT focused, with the stack at that moment, into
-      `localStorage['officer:editor-buffer-trap']` (last five). It persists rather than only logging
-      because this arrives as a report hours later, when the console is long gone — the question becomes
-      "paste this key" instead of "what did you see?". Delete all of it once the cause is known.
-
-      One thing to rule out first, because it is mine and it is recent: `2b70a570` gave `<Editor>` a real
-      `path`, so models are now keyed by file URI globally rather than being per-mount `inmemory://`. Two
-      panels open on the same file now share one model. That should be an improvement, but it is a change
-      in exactly the layer that turned out to be involved.
-
-      Worth noting because it is the reason to look at all: an editor that can show content the file does
-      not contain is a correctness problem even when it never writes — the next person's instinct will be to
-      save the file to "fix" it.
-
-- [ ] **`bootstrap.ts` runs `npm install -g` for Pi on every boot.** `findPiPackageDir` checks stale
-      paths and an outdated package name, so `installPi` always fires and floods the logs with
-      `EEXIST` noise. Should detect `@earendil-works/pi-coding-agent` at the real npm prefix.
-
-- [x] **VNC mirror can orphan/duplicate x11vnc across sidecar restarts.** FIXED 2026-08-01 in the
-      Xvnc rewrite. The diagnosis was right and survived the move off mirroring: the running desktop is
-      tracked in module-level state, so a sidecar restart forgot it while the server kept running
-      orphaned, and `waitForPort` treated ANY listener on 5900 as success — so the next start reported
-      success while the browser talked to the stale process. Now `reclaimPort` frees 5900 (TERM, then
-      KILL after 2s) before spawning, and `waitForPort` also fails if the process we spawned has
-      exited, so a listener that is not ours can no longer be mistaken for a healthy start.
-
-## Infra (alpha)
-
-- [ ] **Delete `/etc/systemd/system/officer-vnc.service`.** Hand-installed unit (not in this repo)
-      that ran `vncserver :1 -geometry 1920x1080 -localhost yes -fg` with `Restart=on-failure`,
-      enabled at boot — it kept a whole parallel XFCE session alive on `:1` (283 MB, 166 tasks)
-      independently of the platform, and silently respawned it whenever the display was killed.
-      Obsolete now that the Desktop panel mirrors `:0` via x11vnc. Disabled 2026-07-15
-      (`systemctl disable --now`), but the unit file is still on disk. Nothing in the codebase
-      recreates it and nothing documents it, so delete the file rather than leave a mystery service
-      one `systemctl enable` away from returning.
-
-- [ ] **`ufw` blocks port 9010 on the LAN.** Default deny incoming; only `22/tcp`, `80/tcp`,
-      `443/tcp`, and everything on `tailscale0` are allowed — so `http://192.168.47.196:9010` is
-      unreachable from the LAN while localhost and Tailscale work.
-      Fix: `sudo ufw allow from 192.168.47.0/24 to any port 9010 proto tcp`
-
-- [ ] **Move the remaining env credentials into the secret store.** `putSecret`/`getSecret` and
-      `bun run secret:set` landed 2026-08-19, and notify now reads `apns-p8`, `apns-key-id`,
-      `apns-team-id`, `fcm-service-account` and `discord-webhook` from the store with env as a
-      fallback. Every other plugin credential is still env-only — same argument applies: bun
-      auto-loads `.env` into every PM2 process, so each one is readable from `/proc/<pid>/environ`
-      of twenty processes that have no business with it.
-
-## Backburner
-
-- [ ] **Music tagging feature** (`/music`, Mp3tag-inspired). v1 was scoped as a two-panel workspace —
-      file browser left, table right, single "Load" context-menu item flattening audio files into the
-      table. Discarded before completion; would need `GET /file-browser/flatten-audio`, a
-      `useFilesAPI.flattenAudio` method, and the Music app panel rebuilt from scratch.

deploy/2026.08.21.01.md

@@ -0,0 +1,43 @@
+# 2026.08.21.01
+
+The first release under this scheme, and the first deploy of the night's work. Everything since
+`0.1.0`, which is to say everything.
+
+## What is in it
+
+- **Two plugins extracted**: `desktop` (VNC) and `browser` (the relay, its extension and its panels),
+  with the platform losing the VNC vocabulary it should never have had.
+- **Themes regenerated** — all 22 from Omarchy, 84 tokens each, contrast-checked. The eleven that
+  shipped with 34 of an 84-token contract are replaced.
+- **Spotlight**, on `shift-space`.
+- **Chat fixes**: a turn waiting on a person is no longer killed as stalled, and an answer that goes
+  nowhere now says so.
+- **Plugin infrastructure**: `importFresh` (a reinstalled plugin was being read from the deleted one),
+  `ownerOnly` paths, dependency `scope`, extensions published unauthenticated, `plugins:update`.
+- An **Update button** in maintenance, and the **sub-agent budget guard**.
+
+## Steps, in order, on every host
+
+Same on all six — nothing here is host-specific.
+
+1. `git pull --ff-only`
+2. `bun install` — **required.** `bun.lock` changed and `sharp` was removed from the platform's
+   dependencies (it moved into atelier's `npmDependencies`). Without this the lockfile and the tree
+   disagree, and the frozen-lockfile rule turns that into a failed install later rather than now.
+3. `bun run plugins:update`
+4. `bun db:push` — **required.** `users.username` becomes `NOT NULL` and gains a case-insensitive
+   unique index.
+5. `pm2 restart officer`
+6. Then, and only for hosts that have them: `pm2 restart officer-claude-code officer-pty` — both load
+   changed sidecar code. **Not** the whole ecosystem, ever.
+
+## The one thing that could have gone wrong, and did not
+
+`db:push` refuses if any account has a null username, or if two differ only by case. **Checked on all
+six before writing this**: 12 users across the fleet, zero nulls, zero case-collisions. If a future
+host fails here, that is why, and the fix is data rather than schema.
+
+## Post-deploy check
+
+`pm2 jlist` — every restarted process `online` with a moved `restart_time`, and the platform's own
+domain answering 200. `docs/servers.md` has the domain per host.

deploy/2026.08.21.01.report.md

@@ -0,0 +1,42 @@
+# 2026.08.21.01 — deployed
+
+**6/6 hosts.** Every platform is on `eee73e77`, schema pushed, processes online and every domain
+answering 200.
+
+Rolled out by hand from `officer-dev`, one host at a time, because nothing wakes the commander yet.
+
+| Host                         | Before     | After      | install | db:push | plugins        | restarted                 | domain |
+| ---------------------------- | ---------- | ---------- | ------- | ------- | -------------- | ------------------------- | ------ |
+| `alpha`                      | `44f6c6d6` | `eee73e77` | ok      | applied | 12/12          | officer, claude-code, pty | 200    |
+| `fofos`                      | `6db26ae4` | `eee73e77` | ok      | applied | 1/1            | officer, claude-code, pty | 200    |
+| `edge-pertento-bridge`       | —          | `eee73e77` | ok      | applied | 2/2            | officer, claude-code, pty | —      |
+| `production-pertento-bridge` | —          | `eee73e77` | ok      | applied | 1/1            | officer, claude-code, pty | —      |
+| `macbookpro`                 | `2e76cabf` | `eee73e77` | ok      | applied | none installed | officer, claude-code, pty | —      |
+| `officer-dev`                | `eee73e77` | `eee73e77` | ok      | applied | 3/3            | officer, pty              | 200    |
+
+`bun install` reported no changes everywhere — the lockfile diff was `sharp` leaving, and nothing had
+it as a transitive need.
+
+## What was NOT done, and why
+
+- **`officer-claude-code` was not restarted on `officer-dev`.** That sidecar holds the session doing
+  the deploy; restarting it would have ended the conversation mid-rollout. Every other host got it.
+  **Outstanding — run it when convenient.**
+- **`fofos` did not sync its capabilities.** `git` refused the checkout as "dubious ownership" and
+  printed the usual `safe.directory` remedy. Ownership is actually correct (`pastilhas:pastilhas`,
+  running as `pastilhas`), so the cause is not what the message suggests and papering over it with a
+  config entry would hide a real question. Its one plugin updated fine. **Unexplained.**
+- **`macbookpro` has no plugins installed**, so `plugins:update` was a no-op there. Not a failure —
+  worth knowing before someone expects the browser relay on it.
+
+## Notes for the next one
+
+- **The dirty-tree check was too strict.** `git status --porcelain` counts UNTRACKED files, and
+  `fofos` was skipped on the first pass for one stray `scripts/chk.ts` that a fast-forward could never
+  touch. The rule is `--untracked-files=no`; untracked files get a note, not a skip.
+  `prompts/deploy-commander.md` says "refuse a dirty tree" and should say which kind.
+- **`macbookpro` needs `$SHELL -ic` and nothing else.** Exporting a PATH to reach `bun` broke `pm2`,
+  which is only on the interactive shell's path. Do not help it.
+- **The pre-flight was worth it.** `users.username` became `NOT NULL` with a case-insensitive unique
+  index; checked across all six first — 12 users, zero nulls, zero collisions — so `db:push` applied
+  everywhere without a data fix.

deploy/2026.08.21.02.md

@@ -0,0 +1,33 @@
+# 2026.08.21.02
+
+Command HQ made usable: a commander's transcript renders, and Live separates commanders from the
+conversations somebody is having.
+
+Frontend and one chat API route. **No schema change, no dependency change** — verified against
+`deploy/2026.08.21.01..HEAD`: nothing touched `src/schema.ts`, `package.json` dependencies or `bun.lock`.
+So there is no `db:push` and no `bun install` in this plan, and a host that runs one has run something
+this release did not ask for.
+
+## What is in it
+
+- Three separate defects that each made a commander's conversation invisible: the pane navigated to
+  officer's session key instead of Claude's transcript id, then remounted and discarded the live chat at
+  the end of the first turn, then seeded `useChat` with messages that had not arrived yet.
+- Live splits into `Agents (n)` / `Commanders (n)`, and `/chat/live` now carries `isCommander` so a client
+  with no room for tabs — the iPhone app's swipe order — can filter on it.
+- The handoff watcher's controls, which were built and never rendered.
+
+## Every host
+
+In the order the procedure gives. Nothing here is host-specific.
+
+1. `git pull --ff-only`
+2. `bun run plugins:update`
+3. `pm2 restart officer`
+
+**`officer` only.** No sidecar changed. Restarting `officer` rebuilds the SPA on boot, which is what
+ships the frontend — there is no separate build step to run.
+
+## Then check
+
+`pm2 jlist`: `officer` is `online` and its `restart_time` moved. Nothing else should have restarted.

deploy/2026.08.21.02.report.md

@@ -0,0 +1,76 @@
+# 2026.08.21.02 — deployed
+
+**6/6 hosts.** Every platform the plan reaches is on `55ecbf4f`, `officer` restarted and back `online`,
+and no other process on any host was touched by the restart step.
+
+`officer-dev` is the seventh platform and was **skipped entirely** — it is the host this commander runs
+on. See below.
+
+Rolled out one host at a time from `officer-dev`, by the procedure in `prompts/deploy-commander.md`.
+
+## The release
+
+Tag `deploy/2026.08.21.02` → `55ecbf4f`; `package.json` says `2026.08.21.02`. They agree.
+Plan: `deploy/2026.08.21.02.md` — pull, `plugins:update`, restart `officer` only. No `bun install`,
+no `db:push`, and neither was run anywhere.
+
+| Host                         | Before     | After      | plugins        | restarted | restart_time | back    |
+| ---------------------------- | ---------- | ---------- | -------------- | --------- | ------------ | ------- |
+| `alpha`                      | `eee73e77` | `55ecbf4f` | 12/12          | officer   | 60 → 61      | online  |
+| `fofos`                      | `eee73e77` | `55ecbf4f` | 1/1            | officer   | 15 → 16      | online  |
+| `macbookpro`                 | `eee73e77` | `55ecbf4f` | none installed | officer   | 2 → 3        | online  |
+| `edge-pertento-bridge`       | `eee73e77` | `55ecbf4f` | 2/2            | officer   | 4 → 5        | online  |
+| `production-pertento-bridge` | `eee73e77` | `55ecbf4f` | 1/1            | officer   | 6 → 7        | online  |
+| `deadpool-rezio-bridge`      | `bd41dff5` | `55ecbf4f` | none installed | officer   | 0 → 1        | online  |
+| `officer-dev`                | `55ecbf4f` | `55ecbf4f` | not run        | **none**  | 155          | skipped |
+
+Every host was clean of TRACKED changes and every pull was a real fast-forward. `pm2 jlist` after each
+restart showed zero processes in any state other than `online`, so nothing was collaterally bounced.
+
+Checkout paths were taken from each `officer` process's `pm_cwd`, not assumed — so `alpha`'s stale
+second checkout at `~/dockers/officer.dev/platform` was never touched.
+
+## What was NOT done, and why
+
+- **`officer-dev` was skipped completely** — no pull, no `plugins:update`, no restart. This session runs
+  inside `officer-claude-code` on it, and its `officer` process would have been restarted out from under
+  the rollout. Its checkout is already at `55ecbf4f` (the tag was cut here), so **the code is present and
+  the running process is a build behind**. `pm2 restart officer` on `officer-dev`, when the owner is happy
+  with the rest, finishes this release. **Outstanding.**
+
+- **`deadpool-rezio-bridge` was two releases behind, not one.** It came in at `bd41dff5` — the
+  `deploy/2026.08.21.01` commit — while every other host was at `eee73e77`. The fast-forward carried both,
+  14 files, and it is now level. Nothing was wrong with it; it simply had not had the interim commits.
+
+- **`fofos` still cannot sync its capabilities.** Same `dubious ownership` refusal as `2026.08.21.01`,
+  same unexplained cause, still not papered over with a `safe.directory` entry. New this time and probably
+  the same root: its gitea plugin could not publish affordances —
+  `EACCES: permission denied, mkdir '/home/pastilhas/officerdev/capabilities/affordances/officerdev'`.
+  Both point at that capabilities checkout being owned by somebody other than `pastilhas`, which is worth
+  one `stat` before the next deploy. `plugins:update` exited 0 and the plugin itself updated. **Unexplained,
+  and now costing two things instead of one.**
+
+- **`fofos` carries one untracked file**, `scripts/chk.ts`. A note, not a skip — that is the rule the last
+  report asked for and it worked.
+
+- **No `bun install` and no `db:push` ran anywhere.** The plan says this release needs neither.
+
+## Notes for the next one
+
+- **`macbookpro` needs the PATH helped after all — carefully.** The last report said "`$SHELL -ic` and
+  nothing else"; that is right for `pm2` and wrong for `bun`. `bun` is at `/opt/homebrew/bin/bun`, and
+  `.zshrc` does not put `/opt/homebrew/bin` on the interactive PATH, so `bun run plugins:update` failed
+  `command not found` before it ran a line. What works is **appending** that one directory for that one
+  command (`export PATH=$PATH:/opt/homebrew/bin`) and running `pm2` as a separate command. Appending
+  shadows nothing — `pm2` stays at `~/.local/bin/pm2` and `node` at `node@22`. **Replacing** the PATH is
+  what broke `pm2` last time. `docs/servers.md` says "do not help the PATH" and should say "append, never
+  replace, and only for `bun`".
+
+- **`$SHELL -ic` on `macbookpro` also aliases `ls` to `eza`**, which is not installed, so a probe using
+  `ls` reports a missing file that is plainly there. Use `command ls` or a plain non-interactive shell for
+  file tests.
+
+- **`plugins:update` restarts sidecars itself.** It prints `sidecar: started` per plugin, so on `alpha`
+  twelve sidecars bounced during step 3 — before the plan's restart step, and not something the plan asked
+  for. That is the script's own behaviour and it is not new, but a report that only lists `officer` under
+  "restarted" is understating it. Worth a line in the plan format.

deploy/2026.08.21.03.md

@@ -0,0 +1,30 @@
+# 2026.08.21.03 — a drill
+
+**No code change.** This release exists to watch the watcher fire, and to exercise the claim rule that
+landed after the last one.
+
+There is nothing to bump but the version and this file, and that is deliberate rather than lazy: a tag
+whose `package.json` disagrees with it makes the commander stop, and a tag with no plan beside it makes it
+stop too, so the smallest honest release is still a version and a plan.
+
+## What is being tested
+
+- The watcher noticing a tag and spawning an agent on its own, with nobody watching the composer.
+- `scripts/deploy-claim.sh` taking the claim before anything is deployed, and the deploy recording success
+  through the same script.
+- A second pass over the same version being refused rather than repeated.
+
+## Every host
+
+1. `git pull --ff-only`
+2. `bun run plugins:update`
+3. `pm2 restart officer`
+
+`officer` only. No `bun install`, no `db:push` — nothing in this range touches a schema, a dependency or
+the lockfile, and `git diff deploy/2026.08.21.02..HEAD` is two files.
+
+## Then check
+
+`pm2 jlist`: `officer` is `online` and its `restart_time` moved. Nothing else restarted.
+
+`scripts/deploy-claim.sh state 2026.08.21.03` says `done`.

deploy/2026.08.21.03.report.md

@@ -0,0 +1,83 @@
+# 2026.08.21.03 — deployed
+
+**6/6 hosts.** Every platform the plan reaches is on `3343b21a`, `officer` restarted and back `online`,
+and no other process on any host was left in a state other than `online`.
+
+`officer-dev` is the seventh platform and was **skipped entirely** — it is the host this deploy ran on.
+See below; its skip is now two releases deep.
+
+This was a drill. The release changes `package.json` and adds its own plan file, nothing else, and it
+exists to watch the claim rule work. It did: `scripts/deploy-claim.sh claim 2026.08.21.03` was taken
+before any host was touched, and `state` reads `done`.
+
+## The release
+
+Tag `deploy/2026.08.21.03` → `3343b21a`; `package.json` at that commit says `2026.08.21.03`. They agree.
+Plan: `deploy/2026.08.21.03.md` — pull, `plugins:update`, restart `officer` only. No `bun install`, no
+`db:push`, and neither ran anywhere.
+
+| Host                         | Before     | After      | plugins        | restarted | restart_time | back    |
+| ---------------------------- | ---------- | ---------- | -------------- | --------- | ------------ | ------- |
+| `alpha`                      | `55ecbf4f` | `3343b21a` | 12/12          | officer   | 61 → 62      | online  |
+| `fofos`                      | `55ecbf4f` | `3343b21a` | 1/1            | officer   | 16 → 17      | online  |
+| `macbookpro`                 | `55ecbf4f` | `3343b21a` | none installed | officer   | 3 → 4        | online  |
+| `edge-pertento-bridge`       | `55ecbf4f` | `3343b21a` | 2/2            | officer   | 5 → 6        | online  |
+| `production-pertento-bridge` | `55ecbf4f` | `3343b21a` | 1/1            | officer   | 7 → 8        | online  |
+| `deadpool-rezio-bridge`      | `55ecbf4f` | `3343b21a` | none installed | officer   | 1 → 2        | online  |
+| `officer-dev`                | `3343b21a` | `3343b21a` | not run        | **none**  | 155          | skipped |
+
+Every host came in at `55ecbf4f` — the previous release, level for the first time in three deploys — and
+every pull was a real fast-forward. Checkout paths were taken from each `officer` process's `pm_cwd`, so
+`alpha`'s stale second checkout at `~/dockers/officer.dev/platform` was never touched. `macbookpro` was
+awake.
+
+**More than `officer` restarted, and the plan did not ask for it.** `bun run plugins:update` bounces each
+plugin's sidecar as it goes: twelve on `alpha`, two on `edge`, one each on `fofos` and
+`production-pertento-bridge`. Every one came back `online`. Nothing was left down.
+
+## What was NOT done, and why
+
+- **`officer-dev` was skipped completely** — no pull (it is already at the tag, which was cut here), no
+  `plugins:update`, no restart. This session runs inside `officer-claude-code` on it, and restarting
+  `officer` there ends the rollout mid-flight.
+
+  **Its running process is now two releases old.** `restart_time` is 155, unchanged since before
+  `2026.08.21.02` — so the same restart the last report left outstanding is still outstanding, and it now
+  carries both releases. The code for both is on disk. `pm2 restart officer` on `officer-dev` finishes
+  them, whenever the owner wants it. **Outstanding, and no longer new.**
+
+- **`fofos` still cannot sync its capabilities.** Third deploy running, same two failures, same
+  unexplained cause:
+
+  - `capabilities: failed — fatal: detected dubious ownership in repository at
+    '/home/pastilhas/officerdev/capabilities'`
+  - `affordances: NOT published — EACCES: permission denied, mkdir
+    '/home/pastilhas/officerdev/capabilities/affordances/officerdev'`
+
+  Both say that checkout is not owned by `pastilhas`. Still not papered over with a `safe.directory`
+  entry, because a `safe.directory` line would silence the first message and leave the `EACCES` — they are
+  one cause, and one `stat` settles it. `plugins:update` exited 0 and the gitea plugin itself updated, so
+  this costs capability sync on that host and nothing else. **Unexplained.**
+
+- **`fofos` still carries one untracked file**, `scripts/chk.ts`. A note, not a skip — the rule works.
+
+- **No `bun install` and no `db:push` ran anywhere.** The plan says this release needs neither, and
+  `deploy/2026.08.21.02..deploy/2026.08.21.03` is two files.
+
+- **Nothing was verified beyond `pm2`.** `officer` is `online` with a moved `restart_time` on all six
+  hosts; no HTTP request was made to any domain. That is what the plan asked to check.
+
+## Notes for the next one
+
+- **The `macbookpro` PATH rule in `docs/servers.md` is now correct and was followed as written.**
+  `export PATH=$PATH:/opt/homebrew/bin` for the `bun` command, `pm2` as a separate command, and both
+  worked first time. Nothing to change.
+
+- **`$SHELL -ic "pm2 jlist"` with stderr discarded came back empty once**, on `edge-pertento-bridge`, and
+  the same command with `2>&1` a second later returned the full list. Transient, and it looked exactly
+  like a dead pm2. Capture stderr and parse the JSON out of the stream rather than trusting the whole of
+  stdout to be JSON — an interactive shell puts its own noise (`starship`, aliases) in there.
+
+- **`officer-dev`'s skip needs a home other than a report.** It has been carried forward twice now, and a
+  report is not a place work waits — the next deploy will write the same paragraph. Either the owner
+  restarts it, or it belongs in `TODO.md`.

deploy/2026.08.21.04.md

@@ -0,0 +1,51 @@
+# 2026.08.21.04
+
+`/login` in the chat window, switching between Anthropic accounts from the usage pills, and a Spotlight
+that can actually reach the plugins.
+
+**This release has a SCHEMA CHANGE.** The previous two did not, and said so; this one adds
+`anthropic_accounts`. Without the push, `GET /api/claude-auth/accounts` fails on a missing relation the
+first time the usage panel is opened — so `bun db:push` is a step here, not an optional tidy.
+
+No dependency change: nothing in `deploy/2026.08.21.03..HEAD` touches `package.json` dependencies or
+`bun.lock`. Do not run `bun install`.
+
+## What is in it
+
+- **`/login` works in the chat composer.** `claude auth login` behaves the same through plain pipes as
+  through a terminal, so it is a subprocess with two reads and one write — no pty. Copy-link beside the
+  open-link button, because opening it here opens it in the browser already signed into the account you are
+  leaving.
+- **Account switching from the usage pills.** `anthropic_accounts` keeps each login's OAuth credential
+  encrypted under a per-account key from the secret store, so a switch needs no browser round trip. An
+  account with no saved credential still gets a chip you can read — cached percentages and a correct reset
+  time — marked as needing `/login`.
+- **Spotlight reached eight items.** Core filled all eight slots, so on a populated server every plugin was
+  unreachable. The cap is gone, rows draw the dock's own tiles, and the settings list went from nine
+  hand-written rows to twenty read off the screens that declare them.
+- The ephemeral pane opens from the markup rather than an effect.
+
+## Every host
+
+1. `git pull --ff-only`
+2. **`bun db:push`** — new this release, see above
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only; no sidecar changed. Restarting it rebuilds the SPA, which is what ships the frontend.
+
+**`alpha` is already at this code**, deployed by hand as a preview before the tag. Its pull will be a
+no-op and that is expected — run the remaining steps anyway rather than skipping the host, so its
+`restart_time` moves with everyone else's.
+
+**On `macbookpro`, append to the PATH for `bun`** — `export PATH=$PATH:/opt/homebrew/bin` — and run `pm2`
+as a separate command. `docs/servers.md` has the detail; replacing the PATH is what broke `pm2` on an
+earlier deploy.
+
+## Then check
+
+`pm2 jlist`: `officer` is `online` and `restart_time` moved. Nothing else restarted by step 4 — note that
+step 3 restarts every plugin's sidecar on its own, which is the script's behaviour and worth recording
+rather than omitting.
+
+`scripts/deploy-claim.sh state 2026.08.21.04` says `done`.

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/README.md

@@ -0,0 +1,23 @@
+# `deploy/`
+
+One file per release, and one report per release.
+
+```
+deploy/
+├── 2026.08.21.01.md         the plan — what to run, in order, on which hosts
+└── 2026.08.21.01.report.md  what actually happened, written by the commander
+```
+
+The plan is written by hand before the release commit. The report is written by the deploy commander
+afterwards and pushed back here.
+
+**A release is a tag**, `deploy/<version>`, and nothing else triggers a deploy — not a commit message,
+not a branch. A tag cannot be written into prose by accident, which a code word can and which every
+document about deploying does.
+
+**What marks a release deployed is LOCAL**: `$OFFICER_ROOT/data/deploys/<version>.done`. Not the report.
+If the lock were the pushed report, a failed push would mean the release looked undeployed and the next
+tick would roll it out again — and pushes here fail for unrelated reasons. So the report is an artefact,
+valuable and not load-bearing.
+
+See `prompts/deploy-commander.md`.

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/email-recall.md

@@ -0,0 +1,159 @@
+# Recall over your own correspondence
+
+**Status: DESIGN, NOT BUILT.** Sketched 2026-08-20, for the email plugin.
+
+## The goal, which is not the technology
+
+Someone is on a phone call with their ex-wife. She says something about the weekend arrangement. He has
+eight years of email with her, and he needs the fact **now** — not after a search, not after reading
+twenty messages.
+
+That is the whole requirement. Everything below is in service of it, and any part of this that does not
+make that moment faster or more accurate is decoration.
+
+The user will never write a query. They ask the agent a question in their own words, and the agent picks
+its tools. So the design question is not "what can the user search" — it is **"what does the agent have
+to work with, and which of its answers can be trusted"**.
+
+## Two mechanisms, because there are two kinds of question
+
+The examples that prompted this split cleanly, and they need different machinery:
+
+| the question                                                     | what it needs                         |
+| ---------------------------------------------------------------- | ------------------------------------- |
+| _"how many times did she ask me to break the weekend agreement"_ | **exhaustion** — every message judged |
+| _"what did she say about the school run"_                        | **retrieval** — the best few, fast    |
+
+```
+COMPILE    exhaustive, once, expensive   → counting, timelines, "show me all of them"
+RETRIEVE   cheap, approximate, always    → exploring, mid-call, "what did she say about…"
+```
+
+They are not competing designs. The agent should have both and choose.
+
+### Counting cannot be done by searching
+
+This is the load-bearing point, and it is the one most likely to be skipped.
+
+An agent asked "how many times" will search, find some, and answer with a number. That number is bounded
+by the phrasings it happened to think of. **"I found four" is indistinguishable from "there were nine"**,
+and nothing in the output signals which it was.
+
+Vector search does not fix this. Top-k also misses — it just misses differently. Ask for the top 20 and
+the 21st is silently gone.
+
+The only honest way to count is to judge every message once and store the verdict. Then counting is
+`SELECT count(*)`: exact, instant, and re-askable a hundred ways without re-reading anything.
+
+**A stored verdict is a judgement a model made about someone's divorce.** It records what it was asked,
+which message it read, and when — so the answer can be inspected, disbelieved and redone. A number with
+no provenance is worse than no number, because it will be quoted.
+
+### Retrieval is where embeddings earn their place
+
+Keyword search finds `school run`. It will never find it from _"the pickup arrangement"_ or _"when I
+collect her on Fridays"_. Over eight years, the same thing is described twenty ways and never once in the
+words you would search for.
+
+An agent closes some of that gap by itself — it knows those are synonyms and can fire several searches.
+But that is **guess-bounded**: it finds the phrasings it thought of, and cannot know the ones it did not.
+
+Two things decide it in favour of embeddings anyway:
+
+- **Latency.** Five keyword searches and twenty candidate reads is thirty seconds. On a live call that is
+  a lost moment. A vector query is milliseconds plus one read.
+- **What comes later.** WhatsApp and audio transcripts share no vocabulary, schema or structure with
+  email. Embeddings collapse all of it into one space. ASR output is noisy in a way keyword search is
+  brittle against and embeddings are not.
+
+**But we do not have WhatsApp or transcripts.** They shape exactly one decision — see the schema — and
+nothing else. Build against email.
+
+## It has to run locally
+
+Every message passes through an embedding model. Doing that through an API means uploading eight years of
+private correspondence to a third party.
+
+For this content that is not a trade-off, it is a disqualification. **Local embedding is a requirement,
+not a preference.**
+
+Today there is no ollama and no embedding code on any of these machines. **That is the real new
+dependency — not the database.**
+
+## Not a vector database
+
+`sqlite-vec` is an extension to the SQLite already in use. Same file as `emails.db`, no service, no
+sidecar, no Docker, no port, nothing to supervise or back up separately.
+
+For a plugin that already owns that file, this is **a table, not an architecture**. A separate vector
+database would add an operational surface for a corpus of 19,000 rows, which is small — vector stores
+begin earning their keep in the millions. What is being bought here is recall on paraphrase and speed on
+a phone call, not scale.
+
+## The genuinely hard part is chunking
+
+Not the vectors. **Quoted reply chains.**
+
+The same paragraph exists in forty messages of one thread. Embed naively and every query returns that
+thread forty times, and it will feel worse than what exists today.
+
+So: strip quoted history, thread properly, embed the new text of each message. `emails` already has
+`thread_id`. This is the work.
+
+Two other email-specific traps measured on the real 19,097-message store:
+
+- **Bodies are ~0.5 GB of HTML.** Embed the text, not the markup.
+- **`labels` is a comma-separated string**, and `read` is populated on 93 rows. Neither is a filter to
+  build on. See the `email-db` skill.
+
+## Schema sketch
+
+Deliberately **not** email-shaped. That is the one concession to a future that does not exist yet, and it
+costs nothing now:
+
+```
+recall_chunks
+  id            integer pk
+  source        text      -- 'email' today. 'whatsapp', 'transcript' later.
+  source_id     text      -- the message id in ITS store — no foreign key across sources
+  account       text      -- which mailbox/number this came from
+  thread_id     text      -- for dedupe and for showing context
+  author        text      -- who said it
+  said_at       timestamp
+  text          text      -- quoted history stripped
+  embedding     float[]   -- sqlite-vec
+
+recall_verdicts             -- the COMPILE half
+  id            integer pk
+  question      text      -- what the model was asked, verbatim
+  source        text
+  source_id     text
+  verdict       boolean
+  reasoning     text
+  model         text      -- which model, so a re-run is comparable
+  judged_at     timestamp
+```
+
+Everything else assumes email until something else exists.
+
+## Build order
+
+1. **Chunking and dedupe**, with no embeddings at all. Strip quotes, thread, count what is left. If this
+   is wrong nothing after it can be right, and it is testable on its own.
+2. **A local embedding model**, and a decision about which. The new dependency.
+3. **`sqlite-vec` + backfill** of the existing corpus. One-off, slow, resumable.
+4. **A retrieval tool** the agent can call, returning chunks with their message ids so it can go read the
+   original.
+5. **The compile half** — a verdict table and a way to ask "judge every message against this question".
+6. Multi-source, if and when WhatsApp or transcripts exist.
+
+Steps 1 and 5 are useful without any of the others. Step 5 in particular answers the questions that
+prompted this, and needs no vectors at all.
+
+## Open questions
+
+- **Which local model**, and how big. Quality against a laptop-or-server-sized footprint.
+- **Re-embedding.** Changing model means re-embedding everything. Store which model produced each vector.
+- **Retention and deletion.** A deleted email should lose its chunks and its verdicts. Nothing here
+  currently cascades.
+- **Who can query it.** This is the most sensitive data in the platform, and it is per-account.

docs/multi-server-push.md

@@ -0,0 +1,112 @@
+# Notifications from more than one server
+
+**Design, not built.** Written 2026-08-21, for the single-sign-on work.
+
+The good news first, because it is the part that needed checking and it holds: **one Officer app can
+receive notifications from every server you are signed into, and almost nothing has to change to allow
+it.** One field is missing. This is what it is and why it matters more than it looks.
+
+## Why it works at all
+
+An APNs auth key (`.p8`) belongs to the **developer account**, not to a machine. There is no server
+binding in it. So every Officer install can hold the same key, mint its own provider token from it, and
+push to the same app.
+
+The device token belongs to the **app**, not to a server either. One Officer app has one token, whichever
+servers it talks to.
+
+So N servers pushing to one phone needs no coordination between them. Each just needs the token, which the
+app posts when it signs in — which the multi-server manager is doing anyway.
+
+Two facts about the shared key, neither blocking:
+
+- **Apple allows 2 active auth keys per account.** Sharing one across servers is the intended pattern;
+  one key per server is not an option past two.
+- **Revoking it kills push everywhere**, with no way to tell which machine leaked it. That is the real
+  cost of copying it to ten boxes, and the reason it belongs in each one's secret store rather than
+  in `.env`.
+
+## The missing field
+
+A payload today:
+
+```json
+{
+  "aps": { "alert": { "title": "Officer" }, "thread-id": "chat:abc", "mutable-content": 1 },
+  "officer": { "c": "officer/core:chat.turn-ended", "id": 42, "mv": 1873 }
+}
+```
+
+There is no origin. With one server that is correct and minimal. With five it breaks three things, and
+only the first is obvious.
+
+**1. The deep link opens the wrong thing.** `officer-chat://session/{id}` — that id is meaningful only on
+the server that issued it. The app has no way to know which, so it picks one. Sometimes it opens nothing;
+sometimes it opens somebody else's conversation with a matching id, which is worse.
+
+**2. `mv` starts a resync fight.** `mv` is a content hash of **that server's** catalogue, and servers with
+different plugins have genuinely different catalogues. The client's rule is `mv !== version → resync`.
+With one stored catalogue and five servers, every push from server B invalidates the copy synced from
+server A, and the app resyncs forever, always against whichever pushed last.
+
+This is the one that would look like a mysterious battery and data problem rather than a bug.
+
+**3. Threading collapses across servers.** `chat:{id}` groups per conversation. Two servers' ids
+coinciding is unlikely with UUIDs and not impossible, and "these two unrelated chats are one banner" is a
+confusing failure to diagnose.
+
+## The change
+
+**A server identifier in the `officer` block**, and the app keeping **one catalogue per server** keyed on
+it:
+
+```json
+"officer": { "s": "<server-id>", "c": "officer/core:chat.turn-ended", "id": 42, "mv": 1873 }
+```
+
+`mv` then means "version of that server's catalogue", threading becomes `<server>:chat:{id}`, and the deep
+link resolves against a known server.
+
+### Where the identifier comes from is an SSO decision, not a notifications one
+
+This is the part to settle tomorrow, and it belongs to the sign-on design rather than to this file.
+
+The multi-server manager already needs a key for each server — to store its API key against, to label it
+in a switcher, to route a deep link. **Whatever that key is, notifications should adopt it.** Inventing a
+second identity here means two ids for one server, drifting the first time somebody renames a host.
+
+It has to survive a hostname change, be stable across reinstalls of the app, and not be a secret — it
+travels in a push payload, which is the one place content is deliberately withheld. A server-generated
+opaque id created at bootstrap fits; a URL does not, because URLs change.
+
+## What stays per server, correctly
+
+Worth stating so nobody tries to unify it:
+
+- **`push_devices`** — each server holds its own registrations. The same phone appears once per server.
+- **`chat_notification_prefs`** — muting a conversation is per server, because the conversation is.
+- **The catalogue** — a server's codes come from its own plugins. Two installs with different plugins
+  legitimately have different vocabularies.
+
+None of that wants a shared store. The app is what joins them, which is the same shape as the sign-on
+work: the app holds the list, each server holds its own truth.
+
+## Current state, verified 2026-08-21
+
+|                        | alpha          | officer-dev |
+| ---------------------- | -------------- | ----------- |
+| iOS devices registered | 2              | 0           |
+| APNs credentials       | partly present | absent      |
+
+So only alpha can push today, and notifications seen elsewhere are the in-app bell rather than push. That
+is not a limitation of the design — it is two things absent on the other machines.
+
+## Order of work
+
+1. **Settle the server identifier** with the SSO design. Everything else waits on it, and it is a
+   half-hour conversation rather than a build.
+2. Add `s` to the payload; keep it optional so an older app ignores it.
+3. Per-server catalogue storage in the app, keyed on `s`. **This is the one that must land before a
+   second server starts pushing**, or the resync fight above begins.
+4. Thread ids become `<server>:chat:{id}`.
+5. Copy the `.p8` into the other servers' secret stores, and have the app register its token per server.

docs/plugin-dependency-scope.md

@@ -0,0 +1,91 @@
+# Plugin dependency scope
+
+**Built 2026-08-21.** A plugin declares WHO has to be able to run each host binary, and the platform
+installs and checks accordingly.
+
+## The bug
+
+`os-deps.ts` probes a dependency by asking the owner's login shell where the binary is. That is the right
+question for most plugins and the wrong one for some, and nothing distinguished them — a per-user answer
+was reported as a fact about the machine.
+
+It matters because `confined` plugins do their work as **the member's own Linux user**, in their own home.
+A binary in the owner's `~/.local/bin` is not on that user's PATH, and reaching it means traversing the
+owner's home directory.
+
+On alpha it happened to work. `/home/pastilhas` is mode **751** — world-traversable, not readable — so an
+absolute path resolved for members. Mode 750, which is the more usual default, would have broken every
+member's binary with nothing reporting anything: the install would still say satisfied, because the
+install only ever asked the owner.
+
+Working by accident is the part worth fixing. Nobody chose 751.
+
+## The field
+
+```ts
+osDependencies: [{ binary: 'iris', reason: '…', packages: {…}, scope: 'shared' }]
+```
+
+`owner` is the default and stays right for most things — anything an `execution` plugin uses runs as the
+owner in the owner's home by definition. `shared` says every account with a Linux user must be able to run
+it, which changes both the install target and the check.
+
+An unrecognised value is a manifest error rather than a silent fallback to `owner`, because the fallback
+is the permissive one.
+
+## What changes when it is `shared`
+
+**Where it is looked for.** System directories only — `/usr/local/bin`, `/usr/bin`, `/bin`, and the sbin
+trio. Deliberately not the owner's login shell: that shell finds the copy in the owner's home and reports
+the dependency satisfied, which is the exact false answer this exists to stop.
+
+**What counts as reachable.** Two things, and checking only the first is how this hid:
+
+- the file is world-executable (`0o001` — group is not enough, members are not in the owner's group)
+- **every directory above it is traversable**, walked to the root
+
+A binary at 755 inside a home at 700 is unreachable, and `stat` on the file alone says it is fine.
+
+**Where a release binary is installed.** `/usr/local/bin`, via `sudo -n install -m 0755`. The download is
+still staged in the owner's own space — fetching straight into a root-owned directory would mean running
+the download as root, which is a bigger ask than moving the result. `-n` so a plugin install never blocks
+on an invisible password prompt.
+
+**What blocks an install.** A shared dependency that is present and working but unreachable gets its own
+state, `unreachable`, and its own refusal — checked before everything else, because no package manager
+fixes it. The binary is installed; what is wrong is where it lives. Reinstalling the package would report
+success and change nothing.
+
+## What this deliberately does not do
+
+**It does not gate execution on a grant.** A binary in `/usr/local/bin` is runnable by any account with a
+shell, whether or not they hold the plugin's permission. The kernel does not know about `role_permissions`
+and never will.
+
+That is the same boundary `ffmpeg` and everything else in `/usr/bin` already has, and it is the right one:
+the plugin's **data** is gated by the permission system, its **executable** is not. For iris it is benign —
+a member who runs it captures their own `$HOME` profile and their own sessions, which is the isolation the
+wrapper already depends on.
+
+If a binary must not merely be _reachable_ but _unusable_ without a grant, `scope` is not the mechanism.
+That needs the plugin's own surface behind the permission gate, and the binary not on anyone's PATH.
+
+## Iris
+
+The motivating case, and still the only `shared` one. `PLUGIN.md` had already recorded it as open item 3 —
+"the binary lands in the owner's `~/.local/bin`, and a confined member's agent cannot read it there" — but
+that had not been connected to the probe being owner-scoped, so the install reported success either way.
+
+`iris` and `iris-browser` are built by the sidecar rather than fetched, so declaring `scope: 'shared'`
+makes the probe honest about who can run them; moving the sidecar's build output into `/usr/local/bin` is
+the remaining half, and it is a change to the sidecar rather than to this.
+
+## Status
+
+|       |                                                                            |
+| ----- | -------------------------------------------------------------------------- |
+| Built | `scope` on a dependency, validated, defaulting to `owner`                  |
+| Built | shared probing on system paths, with a traversal walk to the root          |
+| Built | shared release binaries installed to `/usr/local/bin` via `sudo -n`        |
+| Built | an unreachable shared dependency refuses the install, naming the directory |
+| Open  | iris's sidecar still builds into `~/.local/bin` — see above                |

docs/plugin-route-authorization.md

@@ -0,0 +1,140 @@
+# Plugin route authorization
+
+**Platform half built 2026-08-21.** The gate enforces `ownerOnly`, the manifest accepts it, and the proxy
+forwards `X-Officer-Owner` / `X-Officer-Level`. **No plugin declares it yet** — jellyfin's `/_config` is
+still reachable by anyone granted the plugin, and cannot be locked until the credential question at the
+bottom of this file is answered.
+
+The question: a plugin's **settings** routes should be reachable only by the owner, even when the plugin
+itself is granted to other accounts. Jellyfin is the case that raised it — connecting a server, storing
+its admin token and provisioning accounts is not something a Member should reach, but Jellyfin as a whole
+is exactly the sort of plugin a Member should have.
+
+## The shape we agreed
+
+Authorization stays where the platform already puts it — the gate answers "may this account reach this
+plugin, and at what level" — and the plugin decides what that means **inside** its own surface. That is
+not a new principle. `src/servers/plugins/manifest.ts` already says it, in the comment refusing an
+`ownerOnly` field on a permission:
+
+> Every plugin permission is grantable, per role, at read or write … Finer visibility — whose rows a
+> member sees, what a read means for this plugin's data — is the PLUGIN's business and lives in its own
+> queries.
+
+"Which of my routes are administrative" is the same kind of question as "whose rows does a read return".
+It belongs to the plugin, because only the plugin knows that `/_config` is settings and `/_jf` is bytes.
+
+So: **the platform tells the plugin who is asking; the plugin decides what they may do.**
+
+### What gets passed, and what does not
+
+Today the proxy sends exactly one fact (`src/servers/sidecar/create-proxy.ts`):
+
+```
+X-Officer-User: <id>
+```
+
+The extension is one or two more headers alongside it. Two points about how, both load-bearing:
+
+**Pass derived facts, not the role name.** The instinct is to send `X-Officer-Role: Super Admin`. Don't.
+Roles are the platform's vocabulary and they are not frozen — `Admin`, `Member`, `Developer` today, with
+grants keyed on the role string in `role_permissions`. A plugin that branches on a role name gives every
+plugin repository an opinion about that vocabulary, and renaming a role silently changes authorization
+in code the platform does not own and cannot see.
+
+Send instead what a plugin can act on without knowing anything:
+
+```
+X-Officer-User:  <id>
+X-Officer-Owner: 1 | 0            — is this the server owner
+X-Officer-Level: none|read|write  — this account's effective level for THIS plugin's permission
+```
+
+`isOwner` is the fact that is structurally stable: user id 1, pinned by a CHECK constraint, bypassing
+every permission check. It will mean the same thing in a year. `Super Admin` might not.
+
+A plugin that genuinely needs a third tier — "Admins may also do this" — should not get it by reading a
+role. It should declare a second permission key and let the owner grant it. That keeps the answer to
+"who may do this" on the permissions page, where the owner can see and change it, rather than compiled
+into a plugin's `if`.
+
+**Nothing may be trusted from the caller.** The proxy builds a fresh header object and copies a
+three-item allowlist; it does not forward arbitrary inbound headers. That is why `X-Officer-User` is
+safe to trust, and any new header inherits the same safety **only for as long as the allowlist stays an
+allowlist**. If that loop is ever changed to a copy-everything-except, a client-supplied
+`X-Officer-Owner: 1` becomes a privilege escalation against every plugin at once.
+
+**Absent means denied.** A sidecar that does not see the headers — reached directly, an older platform,
+a bug — must resolve to no privileges rather than to the owner. Same rule as `authorize.ts`, where every
+catch returns deny.
+
+## Where I disagree, and it is one point
+
+Plugin-side enforcement has a failure mode the platform has already been bitten by, and it is worth
+naming before it happens again rather than after.
+
+`assertPermissionTotality` exists because a Member could 403 on `GET /api/tasks` and open
+`/api/tasks/pipeline/ws` with a 101 in the same minute. The lesson written down at the time was
+"**a patch does not survive the next door; refusing to boot does.**" Pure plugin-side authorization is
+that same shape: jellyfin will check, because we are about to write the check. The next plugin's author
+forgets one route, and nothing anywhere notices — no boot failure, no warning, no test.
+
+So the recommendation is not "platform enforces instead". It is **declare in the manifest, enforce in the
+proxy, and pass the facts to the sidecar as well**:
+
+Built as a field on the permission rather than at the manifest root, following `readOnlyWrites` — both
+are sub-paths written relative to the plugin's prefix with a rule attached, and one precedent is better
+than two shapes:
+
+```ts
+// manifest.ts
+permissions: [{ key: 'jellyfin', label: 'Jellyfin', description: '…', ownerOnly: ['/_config'] }],
+```
+
+- **Declared by the plugin**, because the plugin knows which of its paths are administrative.
+- **Enforced by the platform**, in the proxy, before the request reaches the sidecar — so forgetting the
+  check inside the plugin is not a hole, and the rule holds for a route added later by someone who never
+  read this file.
+- **Visible at install**, next to the permissions the owner already reviews, and greppable across every
+  plugin from one place.
+- **Still passed to the sidecar**, because the plugin's own finer rules — whose rows, which fields — are
+  genuinely its business and cannot be expressed as a path prefix.
+
+This does not contradict the `manifest.ts` comment above. That comment refuses to make a **permission**
+owner-only, because a permission is a thing the owner delegates and one nobody can delegate is a
+contradiction. A path prefix is not a grant; it is a statement that a route administers the plugin
+rather than uses it.
+
+## The frontend is a courtesy, not the lock
+
+Hiding the Settings entry in the plugin's nav for a non-owner is worth doing, and it is not security.
+Same rule as `usePermissions`, which fails open on purpose: hiding an entry is politeness, the 403 is the
+lock. Write the guard on the route first and the nav second, never only the second.
+
+## What must be settled before any of this lands
+
+**A member with no server has no Jellyfin.** Connections are stored strictly per user — every query in
+`plugins/jellyfin/db/queries.ts` filters on `eq(jellyfinServers.userId, userId)`. Lock `/_config` to the
+owner today and a Member gets a plugin that can only ever show them the connect form they are forbidden
+to submit.
+
+The resolution that fits what already exists: a non-owner resolves to the **owner's active server URL**
+authenticated with **their own token**, which provisioning already mints and stores in
+`jellyfin_accounts`. That is arguably why those tokens are minted at all — per-user identity upstream, so
+resume points, watched marks and next-up stay each person's own rather than everyone sharing the owner's.
+
+That is a change to credential resolution, not to authorization, and it is the actual prerequisite. The
+guard is a few lines; this is the work.
+
+## Status
+
+|             |                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------- |
+| Agreed      | plugin decides what a level means inside its own surface                              |
+| Agreed      | pass `isOwner` and the effective level; never the role name                           |
+| Agreed      | fail closed when the headers are absent                                               |
+| Built       | `ownerOnly` on a plugin permission, enforced by the gate before self-service and kind |
+| Built       | `X-Officer-Owner` and `X-Officer-Level`, sent when a proxy names its permission key   |
+| Built       | manifest validation — a sub-path without a leading slash is a manifest error          |
+| Blocked on  | credential resolution for non-owners, above                                           |
+| Not started | any plugin actually declaring one                                                     |

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

@@ -0,0 +1,134 @@
+# Servers — the running list
+
+Every machine the owner runs, how to reach it, and what of Officer is on it. Kept here so an
+orchestrator ("pull and update every platform", "restart officer everywhere", "which host is behind")
+has one place to read rather than a fact re-derived per session.
+
+**Verified 2026-08-21** from `officer-dev` by SSH and `pm2 jlist`, except where marked assumed.
+
+## How access works
+
+All of it is over the tailnet, key-based, no `~/.ssh/config`, no passwords, no jump hosts, no ports.
+
+**The login user is NOT always `pastilhas`.** It is per host and it is in the table below. `deadpool` runs
+as `br` and always will — the owner's key is authorised for that account. An orchestrator that hard-codes
+a username fails on that host and will fail on the next one like it.
+
+```bash
+ssh alpha                       # pastilhas, implied
+ssh br@deadpool-rezio-bridge    # not implied
+```
+
+## Officer platforms
+
+Seven, all running.
+
+| Host                         | Tailnet IP  | Login       | Checkout                            | Domain                            |
+| ---------------------------- | ----------- | ----------- | ----------------------------------- | --------------------------------- |
+| `officer-dev`                | 100.64.0.13 | `pastilhas` | `~/officer-dev/platform`            | `platform.officer.dev`            |
+| `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.
+
+### Names that disagree with themselves
+
+Three hosts answer to more than one name, and `tailscale status` is not always the one in use:
+
+| In `tailscale status`   | Also                         | The machine's own hostname |
+| ----------------------- | ---------------------------- | -------------------------- |
+| `edge-bridge`           | `edge-pertento-bridge`       | `edge-pertento`            |
+| `gitea-bridge`          | `production-pertento-bridge` | `PPROD`                    |
+| `deadpool-rezio-bridge` | —                            | `deadpool`                 |
+
+The middle column is what to use. `edge-bridge` and `gitea-bridge` are the old names and are being
+retired; anything reading `tailscale status` will still see them.
+
+### Things that will catch out an orchestrator
+
+All verified, none cosmetic.
+
+- **The checkout path differs per host** — four distinct shapes across seven machines. Take it from PM2:
+  the `officer` process's `pm_cwd`. `alpha` carries a SECOND, stale checkout at
+  `~/dockers/officer.dev/platform`, and pulling that one succeeds while changing nothing.
+- **`pm2` is not on a non-interactive PATH.** It lives under nvm, and nvm's setup is in `.zshrc`, which a
+  _login_ shell does not read. Use `ssh <host> '$SHELL -ic "pm2 jlist"'`. `-lc` is **not** enough — it
+  reports "command not found" on machines where pm2 is plainly running, which cost two wrong conclusions
+  on 2026-08-21.
+- **On `macbookpro`, APPEND to the PATH for `bun`. Never replace it.** This said "do not help the PATH"
+  until 2026-08-21, and that was half right in a way that cost a deploy step: `pm2` is only on the
+  interactive shell's PATH, so replacing it breaks `pm2` — but `bun` is at `/opt/homebrew/bin/bun` and
+  `.zshrc` does not put that directory on the interactive PATH either, so `bun run plugins:update` fails
+  `command not found` before it runs a line. `export PATH=$PATH:/opt/homebrew/bin` for that one command
+  shadows nothing: `pm2` stays at `~/.local/bin/pm2` and `node` at `node@22`. Run `pm2` as a separate
+  command.
+- **`$SHELL -ic` on `macbookpro` aliases `ls` to `eza`, which is not installed.** A probe using `ls`
+  reports a missing file that is plainly there. Use `command ls`, or a non-interactive shell for file tests.
+- **The git remotes differ.** `fofos` pulls over HTTPS; the others over SSH. Never assume a URL — pull in
+  place.
+- **A "dirty tree" means TRACKED changes.** `git status --porcelain` counts untracked files, and a stray
+  script a fast-forward could never touch is not a reason to skip a host. Use `--untracked-files=no`.
+- **`macbookpro` is a laptop.** It may be asleep. Unreachable is a skip with a note, not a failed deploy.
+- **`bun run plugins:update` restarts sidecars itself**, printing `sidecar: started` per plugin — on
+  `alpha` that is twelve processes bouncing during the plugins step, before any restart the plan asked for.
+  Not a fault, but a deploy report that lists only `officer` under "restarted" is understating what moved.
+- **`fofos` failed its capabilities sync for three deploys, and it was ownership.** Fixed 2026-08-21.
+  Two errors that read as unrelated problems — `dubious ownership` from git, and
+  `EACCES … mkdir '…/capabilities/affordances/officerdev'` from the gitea plugin — were one cause in two
+  dialects: fifty paths under that checkout were owned by `root`, including `.git` and `affordances`, all
+  stamped `19 Aug 21:43`. Something was run with `sudo` and left them behind. Mode `755` is why the split
+  looked odd: everything could be READ, so git saw the repo and refused it on ownership while the plugin
+  saw `affordances` and could not write into it.
+
+  One `stat` settled it, and that is the general lesson — `stat` prints the owner rather than inferring
+  anything, so it either proves ownership is the cause or eliminates it, in one command. Fixed with
+  `sudo chown -R pastilhas:pastilhas ~/officerdev/capabilities`; verified after by a `mkdir` into the
+  directory that used to refuse one.
+
+  **A `safe.directory` entry was deliberately NOT used**, and that call is worth keeping. It would have
+  silenced the git message and left the `EACCES` untouched — one symptom of a two-symptom cause hidden,
+  with the obvious explanation spent.
+
+## Not platforms — ignore for now
+
+A checkout may be present; no `officer` process runs on any of these. Whether they are retired, staging
+or half-installed is **not established** — ask before treating them as targets.
+
+| Host        | Tailnet IP |
+| ----------- | ---------- |
+| `headscale` | 100.64.0.2 |
+| `omega`     | 100.64.0.3 |
+| `gateway`   | 100.64.0.4 |
+
+## Other machines on the tailnet
+
+- **Not SSH-reachable** (port 22 refused): `edge-dns` (100.64.0.8), `officer-bridge` (100.64.0.5).
+  Assumed service-only containers — not confirmed. `edge-bridge` was listed here until 2026-08-21 and was
+  wrong: its SSH was simply down at the time of checking.
+- **Client devices, not servers:** `iphone16`, `andres-ipad`, `pixel9a`, plus other people's devices in
+  the tailnet (`diogos-ipad`, `iphone-diogo`, `iphone-bruno`, `fedras-iphone`,
+  `guilhermes-macbook-pro`, `macbook-pro-de-joo`).
+
+## Known wrong, waiting on someone else
+
+- **`officer.rezio.dev` resolves to 100.64.0.4** — that is `gateway`, not `deadpool` (100.64.0.21). Not
+  merely unavailable: pointed at a different machine, so it will serve the wrong box the moment gateway
+  answers on 443. Ports 80 and 443 are closed on `deadpool`, so nothing fronts it yet. Waiting on the
+  domain owner.
+
+## Keeping this list true
+
+It rots when a server is added, a checkout moves, a platform is retired, a remote changes or a login
+differs. Re-verify with the four commands it was built from:
+
+```bash
+tailscale status
+ssh <login>@<host> '$SHELL -ic "pm2 jlist"'   # the officer entry's pm_cwd
+ssh <login>@<host> 'git -C <cwd> remote get-url origin'
+getent hosts <domain>
+```

docs/visual-regression-plan.md

@@ -0,0 +1,149 @@
+# Nightly visual regression, on a second server
+
+**Plan, not built.** Written 2026-08-21.
+
+Capture every route of a dashboard behind a JWT login, every night, on a machine nobody is sitting at —
+and have an agent look only at what changed.
+
+The target is **not** Officer and **not** this machine: a separate box running Officer with the `iris` and
+`browser` plugins, pointed at a dashboard the owner runs elsewhere. Its login is a JWT, like Officer's.
+
+## The shape
+
+```
+target server (Officer + iris + browser)
+  │
+  ├─ cron, 03:00 ──▶ capture N routes with iris        → runs/<date>/<route>.png
+  │                  compare against runs/baseline/    → changed[]
+  │                  if changed is empty → record and stop, wake nobody
+  │                  else → open a chat turn with the changed pairs attached
+  │
+  └─ agent reads only the changed images, judges each: intended, or regression
+                     → notification with the verdict, and a link to the run
+```
+
+The expensive, fuzzy step happens only where pixels actually moved. On a quiet night the run costs a few
+seconds of Chrome and nothing else.
+
+## The hard part: a JWT lives in localStorage, and iris cannot put it there
+
+This is the thing to solve first, because everything else is plumbing.
+
+Cookie-authenticated sites work today: `iris-browser` copies `Cookies`, `Cookies-wal`, `Login Data` and
+`Local State` out of a signed-in profile, so a capture rides the same session.
+
+**A JWT dashboard is not cookie-authenticated.** The token sits in `localStorage`, which Chrome keeps in
+`Default/Local Storage/leveldb/` — a directory `iris-browser` does not copy. So a capture of a
+token-authenticated app renders the login screen, and does it silently: the screenshot is real, the page
+is real, and it is the wrong page.
+
+Three ways out, worth choosing between deliberately.
+
+### A. Copy `Local Storage/leveldb` too — smallest change, biggest blast radius
+
+One more entry in `seed_sessions`. It works, and it copies **every** site's localStorage into the
+capture profile, not just the target's. That is someone's whole browser state in a temp directory, and
+the directory is a LevelDB — copying it under a live browser can catch a compaction mid-write, which
+Cookies-the-file mostly cannot.
+
+Viable, and the least attractive of the three.
+
+### B. Log in during the capture — no profile at all
+
+Most JWT dashboards accept a token in the URL, or can be given one by a first-run page. If the target
+does, then:
+
+```
+iris 'https://dash.example.com/?token=<jwt>' -o run/home.png
+```
+
+and there is no profile, no desktop, no signed-in browser anywhere. The token comes from a service
+account minted for this, stored in Officer's secret store, and never appears in a screenshot.
+
+**This is the recommended path** when the target supports it. It removes desktop from the picture
+entirely, which removes the only reason that plugin was in this plan.
+
+### C. Seed via the relay, capture via iris
+
+Pair a browser once, use the relay to `evaluate` the token into `localStorage`, and let iris capture from
+that profile. Works without changing either plugin, and needs a browser paired at 3am — which is exactly
+the constraint iris exists to avoid.
+
+Keep as the fallback for a target that supports neither a token URL nor a clean profile copy.
+
+## What to capture
+
+**Routes come from a list the repo owns**, not from crawling. A crawler finds what exists; a list says
+what is supposed to exist, and a route disappearing is the regression you most want caught.
+
+```jsonc
+// routes.json, in the dashboard's own repository
+[
+  { "path": "/", "name": "home" },
+  { "path": "/reports", "name": "reports", "waitFor": "[data-ready]" },
+  { "path": "/reports/42", "name": "report-detail" },
+]
+```
+
+`waitFor` maps to iris's `--wait-for`, which is what stops a spinner being the thing under test.
+
+Two viewports — one desktop, one phone — doubles the run and catches the majority of layout breakage.
+`--jobs` renders them in parallel.
+
+## Diffing, before any agent is involved
+
+Compare each capture with the same route's baseline. A pixel count, a threshold, nothing clever:
+
+- **identical** → nothing happens
+- **differs under threshold** (antialiasing, a clock, a random avatar) → nothing happens, but log it
+- **differs over threshold** → into `changed[]`
+
+The threshold exists because something on the page always moves. **Mask what is known to move** rather
+than raising the threshold until it passes — a timestamp region is a rectangle to blank before comparing,
+not a reason to accept 3% drift everywhere.
+
+Officer has no image diff today. `sharp` is already a plugin dependency (atelier) and can do it; a raw
+pixel loop over two decoded buffers is about thirty lines and needs nothing.
+
+**Baselines are promoted, never automatic.** A run does not overwrite the baseline because it succeeded —
+it does so when someone says "yes, that is the new correct". Otherwise a regression becomes the baseline
+on night two and disappears.
+
+## What reaches the agent
+
+Only changed pairs, and each one as **two images plus the route name**: baseline and current. The
+question asked is narrow, because a broad one gets a broad answer:
+
+> This is `/reports` before and after. Describe what changed, then say whether it is a layout break, a
+> content change, or noise. If you cannot tell, say so.
+
+"If you cannot tell, say so" earns its place — a model asked to judge will judge, and a confident wrong
+verdict on night four is how the whole thing stops being trusted.
+
+The verdicts land in a notification (`officer-notify` is already core) with a count and a link, not the
+images. Nobody wants twenty pictures on a phone at 3am.
+
+## What does not exist yet
+
+In rough order of how much they block:
+
+1. **`--wait-for` against a JWT app** — solve auth first (§B), everything else is downstream.
+2. **An image diff.** Thirty lines, or `sharp`.
+3. **A scheduler.** Officer's queue has retries, not schedules — `scheduleRetry` is the only timed thing
+   in it. So this is system cron calling a script, or a `setInterval` in a plugin sidecar the way the
+   nudger does it. Cron is the honest answer for something that runs once a night.
+4. **A place for runs and baselines.** `$OFFICER_ROOT/data/visual-regression/{baseline,runs}/` — outside
+   any plugin directory, because a plugin update replaces that.
+5. **Whatever holds this.** A plugin of its own on that server, with `routes.json` as its config and a
+   panel showing the last run. It is not iris and it is not the relay; it is the thing that uses them.
+
+## What this deliberately is not
+
+**Not a test runner.** It proves a page renders and looks like it did yesterday. It cannot tell you a
+button is wired to the wrong handler, and it should not be stretched to try — that is a real test suite,
+and the two answer different questions.
+
+**Not a crawler.** See routes, above.
+
+**Not the browser relay.** The relay drives a live browser someone is signed into; this runs when nobody
+is. They overlap only in that both produce screenshots. If §B holds, the relay has no role in this at all.

package.json

@@ -1,16 +1,23 @@
 {
   "name": "officer",
-  "version": "0.1.0",
+  "version": "2026.08.23.01",
   "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",
     "fix:env": "bun run ./scripts/fix-env.ts",
+    "todo:index": "bun run ./scripts/todo-index.ts",
+    "plugins:update": "bun run ./scripts/update-plugins.ts",
+    "nudge": "bun run --env-file=.env ./scripts/nudge-agent.ts",
+    "doctor": "bun run --env-file=.env ./scripts/doctor.ts",
     "secret:set": "bun run --env-file=.env ./scripts/secret-set.ts",
     "notify:test": "bun run --env-file=.env ./scripts/notify-test.ts",
     "gen:ecosystem": "bun run --env-file=.env ./scripts/gen-ecosystem.ts",
@@ -30,7 +37,9 @@
     "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",

plugins/EXTRACT-ATELIER-PROMPT.md

@@ -0,0 +1,181 @@
+# Kickoff prompt: extract Atelier into a plugin
+
+Written 2026-08-20 for an **unattended overnight run**. That changes two things from
+`EXTRACT-A-PLUGIN-PROMPT.md`, which assumes the owner is awake:
+
+- **It does not say "ask and wait".** Nobody is there. Decisions that would normally be questions are
+  pre-made below, with reasoning, so the run does not stall on them.
+- **It assumes you may be restarted.** Commit after every task, so whoever picks this up — including you,
+  an hour later, with no memory of it — finds a clean tree and a readable history.
+
+Paste everything below the line into a fresh agent.
+
+---
+
+You are extracting **Atelier** out of `~/officer-dev/dockers/officer-atelier` and into an Officer plugin,
+the way `music`, `offscale` and `gitea` were extracted before it.
+
+**Work in a git worktree, not the main checkout.** Another agent is watching
+`/home/pastilhas/officer-dev/platform` and pulling into it as you push. Two processes in one working tree
+is how work gets lost — on 2026-08-20 it nearly did.
+
+```
+git -C /home/pastilhas/officer-dev/platform worktree add /home/pastilhas/officer-dev/atelier-work -b atelier-plugin
+```
+
+Everything below happens in `~/officer-dev/atelier-work`.
+
+**Push every commit straight to master**, from the worktree:
+
+```
+git push origin HEAD:master
+```
+
+The branch is only there to keep your files out of the other checkout. Master is what is being reviewed.
+Push after every task — a reviewer reading five small commits can tell you what went wrong on the second
+one; nobody can do that with one commit at the end.
+
+**Your final commit message must contain `ATELIER-COMPLETE` on its own line**, and no earlier commit may
+contain that string. It is the signal that the run is finished and the review can start. Do not use it to
+mean "this part is done".
+
+## Read first, in this order
+
+1. **`plugins/EXTRACTING-A-PLUGIN.md`** — the runbook and the authority. Read "What changed on
+   2026-08-16" carefully; it contradicts an earlier instruction in the same file, deliberately.
+2. **`plugins/example/README.md`** — what a plugin is, as conventions.
+3. **`src/servers/plugins/`** — `discover.ts`, `manifest.ts`, `mount.ts`, `install.ts`, `ecosystem.ts`.
+   Where this prompt and that code disagree, **the code is right**.
+4. **`CLAUDE.md`** — house rules, the permission model, and why `assertPermissionTotality` refuses to boot.
+5. **`docs/secret-store.md`** — Atelier holds an OpenAI key.
+6. **`src/workspaces/officerdev/APP_CONVENTIONS.md`** and `HOOK_CONVENTIONS.md` — you are writing panels.
+
+## What Atelier is
+
+Image generation as a service: a provider-shaped API over OpenAI's image endpoints, storing what it makes
+so every image has a permanent URL. Bun · Hono · Postgres/Drizzle · htmx with Hono JSX · a React SPA.
+
+```
+84 ts/tsx files, ~6,400 lines
+tables      collections, provider_settings        (its own `atelier` database)
+routes      /generations, /generations/:id, /edits, /adapters,
+            /:id/items, /:id/items/:generationId, mask
+env         BUN_PORT, PUBLIC_URL, POSTGRES_URL, ATELIER_DATA_DIR,
+            OPENAI_API_KEY, ATELIER_MAX_CONCURRENCY
+runs as     pm2 `officer-atelier`, cwd ~/officer-dev/dockers/officer-atelier
+```
+
+It is a **sidecar** plugin for one reason that survives the UI moving into Officer: generation is
+long-running, capped by `ATELIER_MAX_CONCURRENCY`, and holds a credential the platform must not. The UI
+is Officer's; the work is the sidecar's.
+
+## Decisions already made — do not re-open these
+
+Each of these would normally be a question. They are answered so you can keep moving. If you find
+evidence that one is wrong, **write it in `BLOCKERS.md`, follow the decision anyway, and carry on** — a
+half-applied decision is worse than a wrong one consistently applied.
+
+**1. The UI is PORTED into Officer. No proxy, no iframe, no sidecar-served UI.** Atelier was a separate
+server because that was the quick answer at the time; this extraction is what undoes that. It becomes part
+of Officer, not something Officer frames.
+
+It is smaller than the repository suggests:
+
+```
+src/apps/frontend      1,736 lines / 25 files
+  6 of those           components/ui/*  — shadcn Officer ALREADY HAS. Delete, import from @/components/ui.
+  real work            Generate · Gallery (+ Lightbox) · Collections · Providers   ≈1,200 lines
+src/apps/web           the htmx half — 8 files, DELETED, not ported
+```
+
+So: three panel apps — **Generate**, **Gallery**, **Collections** — under
+`plugins/atelier/web/`, each exporting `appRegistryMetas`, with a `layout.ts` composing them. Follow the
+frontend route conventions in `CLAUDE.md`: selection lives in the URL, rows are real links, no
+`usePanelChannel` for "which thing is open".
+
+The fourth feature, **Providers**, is not a panel — see the next decision.
+
+**2. Providers become Officer settings, with more than one.** `features/Providers/` is a settings screen,
+and Officer has a settings surface already. It moves there rather than becoming a panel.
+
+`src/servers/providers/` is already adapter-shaped — `types.ts`, `openai.ts`, `credentials.ts`, an
+`index.ts` that dispatches. Keep that shape and keep the seam: today OpenAI is the only adapter, and the
+point of moving the settings is that a second one is a new file rather than a new screen. **Do not add a
+second provider in this run** — leave the shape able to take one and say so in `PLUGIN.md`.
+
+**3. The database: check the rows, then decide.** Atelier uses a separate `atelier` Postgres database,
+deliberately — `src/databases/atelier_db/drizzle.config.ts` says why. Plugin tables normally live in
+`officer_db` with a prefix.
+
+- Count the rows in `collections` and `provider_settings` first.
+- **If both are empty**, fold them into `officer_db` as `atelier_collections` and
+  `atelier_provider_settings`, following `plugins/*/db/schema.ts`. Two tables do not earn a second
+  database.
+- **If either has rows**, keep the separate database for now and record the migration as a follow-up in
+  `BLOCKERS.md`. Losing someone's generated images to a schema decision at 4am is not a trade worth making.
+
+**4. Artefacts: `$OFFICER_ROOT/data/atelier/`.** Generated images are files, and `ATELIER_DATA_DIR`
+currently points wherever its `.env` says. A plugin directory is a git clone that an update replaces, so
+artefacts kept there vanish on upgrade with nothing logging it. `plugins/kiosk/artefacts.ts` has the same
+problem solved and the comment explaining it.
+
+**5. `OPENAI_API_KEY` goes in the secret store**, not `.env`. `putSecret`/`getSecret` landed 2026-08-19;
+`bun run secret:set atelier-openai-key` puts it there. Read with `getSecret`, **never `getKey`** — `getKey`
+mints a random value for an absent purpose, which for a foreign credential means silently authenticating
+with a fake. Fall back to env when the store has nothing, so an install that predates this keeps working.
+
+**6. One permission, `atelier`, `kind: 'app'`.** Image generation is not `execution` — it does not run as
+the owner's OS user in the owner's home.
+
+## How to work
+
+**Map before you move.** The first task is not a file move. Find every line in the platform that names
+atelier, and every import pointing INTO it. A plugin may import platform code (`@@/…`); the reverse cannot
+happen. Report what you find before moving anything.
+
+**Commit after every task, and push.** You may be restarted at any point by a scheduler that has no idea
+what you were doing. A clean tree and a commit message are how the next attempt — possibly you — knows
+where it is. Commit messages: simple lowercase, no prefixes.
+
+**Do not restart the platform.** `pm2 restart officer` breaks the owner's chat session. Write the command
+down instead; they will run it.
+
+**Do not `git add -A`.** Add the paths you touched. This has caused two commits to swallow another
+agent's work in one day.
+
+**Format only what you touched** — `bunx prettier --write <paths>`, never `bun format`.
+
+**`bunx tsgo` must be clean** before every commit. Not `tsc`.
+
+## When you get stuck
+
+Write it in `BLOCKERS.md` at the worktree root — what you were doing, what stopped you, what you did
+instead, and whether it is reversible. Then **move to the next task**. Do not wait, do not invent a
+workaround that changes behaviour without saying so, and do not stop the run.
+
+If invented content ends up anywhere durable — copy, defaults, seed data — mark it `[placeholder]` so it
+can be found later with a grep.
+
+## Done means
+
+- `plugins/atelier/` with `manifest.ts`, `api/router.ts`, `sidecar/index.ts`, `web/panels.ts`,
+  `web/layout.ts`, `db/`, `assets/icon.png`, `assets/splash.png`, and its own git repository.
+- It installs from the Marketplace onto a machine that has never had it, and the panel renders.
+- `bunx tsgo` clean, `bun test` passing.
+- A `PLUGIN.md` in the plugin recording what moved, what did not, and why — the way `music` and `offscale`
+  did. This is the part that is worth most in three months.
+- `BLOCKERS.md` listing every decision you made without being able to ask.
+
+## What you may NOT do
+
+- No unauthenticated routes. A plugin cannot serve one; `UNPROTECTED_API_PREFIXES` is hardcoded in the
+  platform. If Atelier needs one, that is a blocker, not something to work around. (`plugins/kiosk`
+  is stuck on exactly this — read its README before concluding you have found a way.)
+- **Generated images are served through an authenticated route**, like every other plugin artefact. Every
+  image having "a permanent URL" was true of a standalone server with its own `PUBLIC_URL`; inside Officer
+  the URL is behind the session. If something needs an image without one — an `<img>` in an email, a
+  share link — that is a blocker to write down, not a route to open. See the image-rendering affordance
+  in `capabilities/affordances/officer/core/` for why an `<img>` cannot carry a token.
+- No changes to `src/servers/plugins/` to make Atelier fit. If the contract does not accommodate it, that
+  is a finding worth more than the workaround.
+- No second agent, no second worktree, no background job that writes to this tree.

plugins/EXTRACTING-A-PLUGIN.md

@@ -78,9 +78,11 @@ Music added the field; see its PLUGIN.md for what it is guarding against.
 **Nothing may branch on provenance** except `mountPrefix()`. First-party and third-party differing
 anywhere else means two systems, and only one gets tested.
 
-**Uninstall never destroys data.** The generated schema barrel follows plugin **directories**, not the
+**Only an explicit tick destroys data.** The generated schema barrel follows plugin **directories**, not
-install table — `db:push` drops what it cannot see, so following installs would delete a plugin's tables
+the install table — `db:push` drops what it cannot see, so following installs would delete a plugin's
-on uninstall. Only deleting a plugin's source can lose its data.
+tables the moment it was stopped. Deleting a plugin removes its directory, and the confirmation's
+"also delete all its data" checkbox is the one thing that drops its tables. Unticked, the rows outlive
+the plugin and show up in the orphan list on the same screen.
 
 ---
 
@@ -125,9 +127,9 @@ Then through `/plugins`, watching PM2 and the browser at each step:
 | permissions page                | its permission is listed, read/write/none                   |
 | disable                         | route 404s, sidecar stops, **tables and rows survive**      |
 | enable                          | comes back                                                  |
-| uninstall                       | route gone, `pm2 list` loses it, **data still there**       |
+| delete, checkbox unticked       | route gone, `pm2 list` loses it, directory gone, **data still there** |
-| `bun db:push` while uninstalled | **do not run this — see "What changed on 2026-08-16"**      |
+| install again                   | fresh clone, and it finds those rows                        |
-| install again                   | identical to the first install                              |
+| delete, checkbox ticked         | tables dropped too — a machine that never had it            |
 
 A normal refresh is enough; the shell is `no-store`. When the log's last line appears, the bundle exists.
 
@@ -220,15 +222,21 @@ no terminal it applies NOTHING and exits 0, so an install reports success and th
 query with 42P01. `--force` would be worse if it worked: the destructive statements are `drop table` for
 every plugin whose directory is absent.
 
-So: the row in the verification table that says to run `bun db:push` while uninstalled is struck out. The
+So: the row in the verification table that said to run `bun db:push` while stopped is gone. The property
-property it was checking — uninstall does not destroy data — is now checked by reinstalling and finding
+it was checking — stopping a plugin does not destroy data — is now checked by deleting it with the
-your rows still there.
+checkbox unticked, installing again, and finding your rows still there.
 
-**Use `purge` to test the install twice.** Uninstall deliberately keeps the directory and the tables, so a
+**Delete WITH the checkbox to test the install twice.** Anything less is not a fresh install: the
-second install is not a fresh one: the marketplace hides a plugin whose directory exists, and the tables
+marketplace hides a plugin whose directory exists, and tables that are already there make `db:push` a
-are already there. The Marketplace screen has "Delete <plugin> and all its data" — it drops the tables,
+no-op, so a broken schema stays broken and passes. Ticked, it drops the tables, deletes the directory and
-deletes the directory and regenerates the barrel, and afterwards the plugin installs from the catalogue
+regenerates the barrel — and afterwards the plugin installs from the catalogue exactly as a stranger's
-exactly as a stranger's machine would. **That is the only honest test of an install.**
+machine would. **That is the only honest test of an install.**
+
+**Uninstall was removed on 2026-08-21.** It sat between disable and delete, keeping the directory and the
+data, and the screen could not show the difference: an uninstalled plugin stayed in the list under a
+heading that said "Installed" while its directory silently decided what the next install would run. That
+is not hypothetical — it is how a jellyfin install on alpha re-applied a checkout from two days earlier,
+reporting success at every step. The verbs are now enable, disable and delete.
 
 **The install now verifies its own tables.** After the push it asks Postgres whether each declared table
 exists and fails the install naming what is missing. If your extraction reports "schema push reported

plugins/USER_PROVISIONING.md

@@ -0,0 +1,240 @@
+# Provisioning a user in a plugin's upstream service
+
+> **Handing this to a fresh agent?** Everything below was verified against a live instance on
+> 2026-08-19 — every status code, every error body. Trust it over the upstream's own docs, which
+> lag. Re-verify with the probe sequence at the end if the upstream has been upgraded since.
+
+Officer creates the account; the upstream service owns it. This is the contract for doing that
+safely, written from the **`photos` plugin** (Immich) as the first worked example. The shape
+generalises: authenticate as an admin, check-then-create, verify the result, hand over a one-time
+password.
+
+**This directory holds documentation, not plugins.** The plugin itself lives in
+[`plugins/photos`](https://gitea.officer.dev/plugins/photos).
+
+---
+
+## The four rules
+
+1. **Never hardcode the admin credential.** Read it from the environment or the platform's
+   credential store, and never log it. Docs and repos get shared; credentials must not travel
+   with them.
+2. **Check before you create.** None of these APIs upsert. A second call with the same email is
+   an error, not a no-op — so provisioning must be re-runnable by listing first.
+3. **Force a password change.** Generate a strong random password, mark it as
+   must-change, and treat it as a one-time handover value. It stops being a secret the moment
+   the user logs in.
+4. **Verify by logging in.** A `201` means the row was written, not that the account works. Do a
+   real login before reporting success, so failures surface at provisioning time rather than when
+   the person first tries to use it.
+
+---
+
+## Worked example — Immich (`photos` plugin)
+
+Verified against **Immich 3.1.0**.
+
+| | |
+|---|---|
+| API root | `<base>/api` — e.g. `http://127.0.0.1:2283/api` |
+| Auth | header `x-api-key: <ADMIN_API_KEY>` |
+| Admin routes | `/api/admin/*` — reject non-admin keys with `401` |
+
+Immich stores API keys **SHA-256 hashed**, so a lost key can only be replaced, never recovered.
+Mint one in the UI → Account Settings → API Keys.
+
+### 1. Check (idempotency guard)
+
+```http
+GET /api/admin/users
+x-api-key: <ADMIN_API_KEY>
+```
+→ `200`, JSON array. If the target email is present, stop — already provisioned.
+
+### 2. Create
+
+```http
+POST /api/admin/users
+x-api-key: <ADMIN_API_KEY>
+Content-Type: application/json
+
+{
+  "email": "person@example.com",
+  "password": "<generated>",
+  "name": "Full Name",
+  "shouldChangePassword": true
+}
+```
+
+**Required:** `email`, `password`, `name`.
+
+| Optional field | Type | Notes |
+|---|---|---|
+| `shouldChangePassword` | bool | `true` ⇒ forced reset at first login. Always send it. |
+| `quotaSizeInBytes` | int | e.g. `1073741824` = 1 GiB. Omit for unlimited. |
+| `storageLabel` | string | Folder name used by the storage template. |
+| `notify` | bool | Emails the new user. Requires SMTP configured upstream. |
+
+→ **`201 Created`**, body carries the new `id`:
+
+```json
+{ "id": "70ee4cd2-…", "email": "person@example.com", "name": "Full Name",
+  "isAdmin": false, "shouldChangePassword": true, "quotaSizeInBytes": null }
+```
+
+`isAdmin` cannot be set at creation — promote afterwards via the admin update endpoint.
+Names are full Unicode (`Bruno Conceição`); send UTF-8, no escaping.
+
+### 3. Verify
+
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{ "email": "person@example.com", "password": "<generated>" }
+```
+→ `200` with `{"name":…,"userEmail":…,"isAdmin":false,"shouldChangePassword":true}`.
+No API key — this is the ordinary user login path, which is exactly why it proves the account works.
+
+### Errors (observed, not guessed)
+
+| Condition | Status | Body |
+|---|---|---|
+| Email already exists | `400` | `{"message":"Email is not available"}` |
+| Missing `password` / `name` | `400` | `{"message":"Validation failed","errors":[{"path":["password"],…}]}` |
+| Bad or missing API key | `401` | — |
+
+### Deprovisioning
+
+```http
+DELETE /api/admin/users/{id}
+Content-Type: application/json
+
+{ "force": true }
+```
+→ `200` with `{"status":"removing","deletedAt":"…"}`. Soft-delete; `force` skips the grace period.
+
+---
+
+## Worked example — Jellyfin (`jellyfin` plugin)
+
+Same four rules, **different shape**. Read this section as: the route surface and auth model are
+**verified** against Jellyfin **10.11.11**; the request bodies are from working knowledge and
+marked as such — confirm them with the probe recipe below before relying on them in code.
+
+### How it differs from Immich — read this first
+
+| | Immich | Jellyfin |
+|---|---|---|
+| Auth header | `x-api-key: <key>` | `Authorization: MediaBrowser Token="<key>"` |
+| Create + configure | one call | **two or three** — create, then policy, sometimes password |
+| Force password change | `shouldChangePassword: true` | **no equivalent** — see below |
+| Scope of an account | one server | **per instance** — see below |
+
+Two consequences that bite:
+
+1. **There is no "must change password" flag.** Rule 3 cannot be enforced by the server.
+   **Decision for this deployment (2026-08-20): set a generated password at creation and tell the
+   user to change it.** Do *not* use the blank-password alternative — Jellyfin permits it, but the
+   account is then open to anyone who can reach the port until the user sets one.
+   So for Jellyfin, rule 3 becomes: still generate a strong unique password, still treat it as a
+   handover value, but the change is advisory rather than forced — which means **never reuse a
+   generated password across users or instances**, since it may stay valid indefinitely.
+2. **Users are per-instance, not global.** This deployment runs **four** independent Jellyfin
+   servers, each with its own user database and its own API keys:
+
+   | Instance | Port | Server name |
+   |---|---|---|
+   | `jellyfin` | 9301 | Jelly |
+   | `jellyfin_music` | 9302 | Albums |
+   | `jellyfin_dj_sets` | 9303 | DJ_Sets |
+   | `jellyfin_diogo` | 9399 | JellyDiogo |
+
+   Provisioning "a Jellyfin user" therefore means looping over whichever instances that person
+   should reach, with a **separate API key per instance**. There is no cross-server account.
+
+### Getting an API key
+
+Unlike Immich, Jellyfin has **no admin-token bootstrap from nothing** — creating a key requires
+an already-authenticated session. Two routes:
+
+- **UI:** Dashboard → API Keys → `+`. Simplest, and the one to use for first setup.
+- **API:** `POST /Auth/Keys?App=<name>` (verified: route exists, `401` unauthenticated), using a
+  token obtained from `POST /Users/AuthenticateByName` with an admin username/password
+  (verified: route exists; returns `415` if you omit the JSON content type).
+
+`GET /Auth/Keys` lists them (verified: exists, `401` unauthenticated). Keys are stored in
+`config/data/jellyfin.db`, table `ApiKeys`. **This deployment currently has zero API keys** — one
+must be created before any of the flow below will work.
+
+### The flow
+
+```http
+GET /Users
+Authorization: MediaBrowser Token="<API_KEY>"
+```
+→ verified: exists, `401` without auth. Use it as the **check** step (rule 2) — match on `Name`.
+
+```http
+POST /Users/New
+Authorization: MediaBrowser Token="<API_KEY>"
+Content-Type: application/json
+
+{ "Name": "Full Name", "Password": "<generated>" }
+```
+→ verified: route exists (`401` unauthenticated). Body shape from working knowledge. Returns the
+created user object including its `Id` (a GUID), which the next calls need.
+
+Then, as needed:
+
+| Purpose | Endpoint | Notes |
+|---|---|---|
+| Library access, admin rights, parental rating | `POST /Users/{id}/Policy` | Full policy object; **send the whole thing**, it replaces rather than merges. This is where `IsAdministrator` and `EnabledFolders` live. |
+| Set/replace password | `POST /Users/{id}/Password` | Needed if you created the user without one. |
+| Delete | `DELETE /Users/{id}` | Hard delete — no soft-delete/grace period, unlike Immich. |
+
+**Verify (rule 4)** with a real login rather than trusting the create:
+
+```http
+POST /Users/AuthenticateByName
+Content-Type: application/json
+
+{ "Username": "Full Name", "Pw": "<generated>" }
+```
+→ returns an `AccessToken` and the `User` object on success. Note the field is `Pw`, not
+`Password`, and Jellyfin authenticates by **username**, not email — Jellyfin has no concept of an
+email login.
+
+### A public endpoint worth knowing
+
+`GET /Users/Public` needs **no authentication at all** (verified: `200`). It lists users flagged
+as visible on the login screen. On this deployment it returns `[]` on all four instances, so
+nothing is currently exposed — but if you provision users, be aware that leaving them
+login-screen-visible publishes their names to anyone who can reach the port.
+
+### Probe recipe (Jellyfin)
+
+Same spirit as the Immich one, but you need a key first, and there is no soft-delete — so probe on
+a **non-production instance** or be prepared to hard-delete:
+
+1. `GET /Users` with the key → `200` and an array. Wrong key → `401`.
+2. `POST /Users/New` with a throwaway name → expect the created object; keep the `Id`.
+3. Repeat the identical call → observe the duplicate-name behaviour and **record the exact status
+   and body here**, since it is the guard rule 2 depends on.
+4. `POST /Users/AuthenticateByName` with the throwaway credentials → expect an `AccessToken`.
+5. `DELETE /Users/{id}` → then `GET /Users` to confirm it is gone.
+
+---
+
+## Re-verifying after an upstream upgrade
+
+Cheap and non-destructive — create a probe user on an unroutable domain, exercise it, delete it:
+
+1. `POST /api/admin/users` with `probe-delete-me@example.invalid` → expect `201`, keep the `id`.
+2. Repeat the identical call → expect the duplicate-email `400`.
+3. `POST` with `password`/`name` omitted → expect the validation `400`.
+4. `POST` with a bogus key → expect `401`.
+5. `DELETE /api/admin/users/{id}` with `{"force":true}` → expect `200`, then `GET` to confirm it's gone.
+
+Use `.invalid` (RFC 2606 — guaranteed never to resolve) so a stray notification email can never
+reach a real person.

prompts/deploy-commander.md

@@ -0,0 +1,239 @@
+# Deploy commander
+
+Start a commander with this. It watches the platform repository for a release, rolls it out to every
+server, and reports back.
+
+**It never decides what a deploy needs.** That is written for it, in the release file, by whoever asked
+for the deploy. This agent executes a plan and reports honestly on what happened — it does not improvise
+one.
+
+---
+
+## What wakes you
+
+You are not a loop. Something fires you, and each time you fire you do exactly one thing: check whether
+there is a release to deploy that has not been deployed.
+
+```bash
+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.
+
+**Why a tag and not a code word in a commit.** A code word can be written by accident. Every document
+about deploying contains it, this file included, and so does every conversation planning one — so the
+trigger has to be defended with rules about where in the subject line it sits, and a rule like that is
+one somebody eventually gets wrong. A tag cannot be typed into prose. It is created deliberately, it
+names its own version, and `git ls-remote` answers "is there one" in a single call without fetching.
+
+- **No untagged release** → say "no release pending" and stop. Do not pull, do not touch a server.
+- **A `deploy/*` tag with no local record** → that is the release. Continue.
+
+### One attempt per release, and you do not enforce that yourself
+
+**Before you spawn or run anything for a version, claim it:**
+
+```bash
+scripts/deploy-claim.sh claim <version>   # exit 0 = it is yours, exit 1 = do not proceed
+```
+
+Exit 1 means somebody already attempted this release. **Stop. Do not retry it, do not deploy it, and do
+not decide the previous attempt does not count.** Say what the script said and move on.
+
+On success, record it through the same script:
+
+```bash
+scripts/deploy-claim.sh done <version>
+```
+
+**Why this is a script and not a rule you follow.** A watcher loop is written fresh each time one arms, so
+a rule that lives only in this file gets re-implemented from scratch every time — and the wrong version of
+it looks right: test for the `.done` file, which exists only on SUCCESS. Write that and a failing release
+spawns a new agent every poll, all night, each one costing money. That is not hypothetical. It is what the
+first watcher did on 2026-08-21: a careful loop, honest logging, and an unbounded retry inside it.
+
+So the rule is code. `mkdir` is the claim — atomic, one syscall that both tests and takes, no window
+between checking and acting. The script refuses a second claim and keeps refusing, whatever happened to the
+first attempt.
+
+**A failed release is therefore not retried. It is looked at.** Clearing a claim is a deliberate human act
+(`rm -rf …/<version>.claim`) or a new tag. A loop cannot undo its own claim, which is the property that
+makes the storm impossible rather than unlikely.
+
+### The record is LOCAL, not in git
+
+```
+$OFFICER_ROOT/data/deploys/<version>.done
+```
+
+That file's existence means deployed. Written after the rollout, before the report is pushed.
+
+**This is deliberate and it is the important part.** The obvious design makes the pushed report the
+marker — and then a failed `git push` means the release looks undeployed and the next tick **does it all
+again**. Pushes here are genuinely unreliable: gitea's public SSH is rate-limited because every
+connection arrives from one proxy container IP and internet bots get it penalised, which cost several
+retries on 2026-08-21.
+
+So the lock is local and cannot fail for a network reason. The report is an ARTEFACT — valuable, and not
+load-bearing. A missing report is a missing record; a missing lock is a second deploy.
+
+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:
+
+- `package.json` — `version` matching the tag, `yyyy.mm.dd.NN` (`2026.08.21.01`), the mobile apps'
+  scheme. `NN` increments for a second deploy on the same day.
+- `deploy/<version>.md` — **the plan**. What to run, in order, and on which hosts. Written by hand.
+
+If the tag and `package.json` disagree, **stop and say so**. One of them is a mistake and guessing which
+is how the wrong tree gets deployed.
+
+If the plan file is missing, **stop and say so**. A release with no plan is not a release you can guess
+at, and guessing is how a database gets a schema it was not ready for.
+
+---
+
+## The servers
+
+**Read `docs/servers.md`.** Do not take a list of hosts from this file — there is deliberately none here,
+because a copy rots the day a server moves and the copy is always the one somebody trusts.
+
+That document holds every machine, its tailnet name, **its login user**, its checkout and whether a
+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.
+
+**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.
+
+Four things that will catch you out, all verified rather than assumed:
+
+- **Never hard-code the path.** Take it from PM2: the `officer` process's `pm_cwd`. `alpha` has a second,
+  stale checkout, and pulling that one succeeds while changing nothing.
+- **`pm2` is not on a non-interactive PATH.** It is installed under nvm, and nvm lives in `.zshrc`, which
+  a _login_ shell does not read. Use `ssh <host> '$SHELL -ic "pm2 jlist"'`. `-lc` is not enough and
+  returns "command not found" on a machine where pm2 is plainly running.
+- **The git remotes differ.** `fofos` pulls over HTTPS; others over SSH. Never assume a URL — just
+  `git pull --ff-only` in place.
+- **`macbookpro` is macOS and is a laptop.** It may be asleep. Unreachable is a SKIP with a note, not a
+  failure of the deploy.
+
+---
+
+## Rolling it out
+
+Per host, in this order. Do them **one host at a time** and keep a record as you go — a report you
+assemble at the end from memory is a report that will be wrong about the host that failed.
+
+1. **Refuse a dirty tree — TRACKED changes only.** `git status --porcelain --untracked-files=no`. Plain
+   `--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.
+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
+   checkout.
+4. **Run the plan's commands** for that host, in the order given. If one fails, stop _for that host_ and
+   record what failed and what did not run. Do not continue past a failed `bun install` or `db:push`.
+5. **Restart what the plan names**, and nothing else. Never `pm2 restart ecosystem.config.cjs` — it
+   bounces every sidecar including the vault.
+6. **Check it came back.** `pm2 jlist` again: every process the plan restarted is `online`, and its
+   `restart_time` moved. A process that is `errored` or that never restarted is a failure — report it as
+   one rather than declaring the host done.
+
+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.
+
+### 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**.
+
+You are a session inside `officer-claude-code` on that machine. Restarting it ends you mid-rollout —
+which is not a hypothetical: on 2026-08-21 a manual deploy reached its own host last and had to leave
+that one sidecar alone to survive writing its own report.
+
+Restarting only `officer` and leaving your own sidecar behind would work, and it is worse: it puts one
+host in a state nobody chose, a step behind the others, discovered later. So skip the whole host and say
+which one. The owner restarts it deliberately, as the last step, once they are happy with the rest.
+
+Find it with `hostname` and match it against the list — do not assume you are on any particular one.
+
+---
+
+## The report
+
+Write the local record FIRST — `$OFFICER_ROOT/data/deploys/<version>.done` — then commit
+`deploy/<version>.report.md` and push it.
+
+That order matters. The record is what stops a second deploy, and the push is the part that can fail for
+reasons having nothing to do with the rollout. **If the push fails, say so and stop — do not retry into a
+loop and do not treat it as a failed deploy.** The deploy succeeded; its paperwork is pending.
+
+Never tag the report. A tag is the trigger, and a report that tags itself deploys itself forever.
+
+Per host: what its HEAD was before and after, which steps ran, which were skipped and why, which
+processes restarted, and whether they came back. Then one line at the top saying how many hosts
+succeeded out of how many.
+
+Say what you did not do. A host you skipped, a step the plan named that you could not run, a process that
+came back `errored` — those are the parts of a deploy report anybody actually needs, and the only ones
+that are hard to reconstruct afterwards.
+
+---
+
+## Being woken
+
+A background job does it, armed from the composer's background-job dialog with **Exit and hand back to the
+agent, then re-arm**. The wait happens in the shell, not in a model tick — a loop polling
+`git ls-remote`, which is one network call and no tokens.
+
+The loop cannot do a deploy: it cannot read a plan, judge a host or write a report. So on firing it spawns
+a headless agent — `claude -p "<read this file and follow it>" --dangerously-skip-permissions
+--output-format=stream-json --verbose` — and pipes the events through `jq` so the job panel shows progress
+instead of a blank box for twenty minutes.
+
+Two things that loop must get right, both learned by getting them wrong on 2026-08-21:
+
+- **Claim the version first**, per the section above. This is the one that costs money when missed.
+- **Set `OFFICER_ROOT` explicitly.** It is empty in the sidecar's environment, so the lock path resolves to
+  `/data/deploys` and the release looks permanently undeployed.
+
+The deploy therefore runs in a **separate** agent, not in the commander's own conversation: no Command HQ
+row, no cost on the commander's line, and its reasoning lives in that child's transcript. That is the price
+of putting the wait in the shell, and it is worth it — a model-side tick that re-reads a whole conversation
+to learn nothing is the thing being avoided.

public/officer-logo.svg

@@ -1,4 +1,4 @@
-<svg width="1200" height="240" viewBox="-20 40 1200 260" xmlns="http://www.w3.org/2000/svg">
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="300" viewBox="60 40 900 300">
   <defs>
     <filter id="shadow3d-main-officer">
       <feOffset dx="6" dy="6" in="SourceGraphic" result="offset1"/>
@@ -25,25 +25,26 @@
     </pattern>
 
     <mask id="textMaskOfficer">
-      <text x="580" y="220" text-anchor="middle" class="officer-text-main" fill="white">o<tspan dx="6" dy="30" letter-spacing="14">ff</tspan><tspan dx="-2" dy="-30">icer.dev</tspan></text>
+      <text x="510" y="220" text-anchor="middle" class="officer-text-main" fill="white">Of<tspan dx="16">f</tspan><tspan dx="10">i</tspan><tspan dx="10">c</tspan><tspan dx="10">e</tspan><tspan dx="10">r</tspan></text>
     </mask>
 
     <style>
       .officer-text-main {
-        font-family: system-ui, -apple-system, sans-serif;
+        font-family: system-ui, -apple-system, "System Font", ".SF NS", "Helvetica Neue", sans-serif;
         font-size: 140px;
-        font-weight: 900;
+        font-weight: 700;
         fill: #F4C430;
         stroke: #14532D;
         stroke-width: 3;
         paint-order: stroke fill;
-        letter-spacing: -2px;
+        letter-spacing: 8px;
-        text-transform: lowercase;
+        font-variant-ligatures: none;
+        font-feature-settings: "liga" 0, "clig" 0, "dlig" 0;
       }
     </style>
   </defs>
 
-  <text x="580" y="220" text-anchor="middle" class="officer-text-main" filter="url(#shadow3d-main-officer)">o<tspan dx="6" dy="30" letter-spacing="14">ff</tspan><tspan dx="-2" dy="-30">icer.dev</tspan></text>
+  <text x="510" y="220" text-anchor="middle" class="officer-text-main" filter="url(#shadow3d-main-officer)">Of<tspan dx="16">f</tspan><tspan dx="10">i</tspan><tspan dx="10">c</tspan><tspan dx="10">e</tspan><tspan dx="10">r</tspan></text>
 
   <rect x="0" y="0" width="1160" height="300" fill="url(#gridPatternOfficer)" mask="url(#textMaskOfficer)"/>
 </svg>

scripts/deploy-claim.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+#
+# One attempt per release, enforced by the filesystem.
+#
+# A watcher loop asks this before it spawns anything. Exit 0 means "you have the claim, go". Exit 1 means
+# "somebody already had it" — and that answer never changes back, whatever happened to the attempt that
+# held it. A release that fails is not retried; it is looked at.
+#
+# WHY THIS IS A SCRIPT AND NOT A PARAGRAPH IN prompts/deploy-commander.md
+#
+# The watcher loop is written fresh by an agent each time it arms, so a rule that lives only in prose is
+# re-implemented from scratch on every arming, and "skip a version already attempted" has a wrong version
+# that looks right: test the .done file, which only exists on SUCCESS. Write that and a failing deploy
+# spawns a fresh agent every poll, all night, each one costing money. That is exactly what happened on
+# 2026-08-21 — the loop was careful, logged honestly, and still had an unbounded retry in it.
+#
+# WHY BASH AND NOT bun
+#
+# The thing that stops a retry storm must not depend on the checkout being healthy. A deploy that dies on
+# `bun install` is precisely when this has to work.
+#
+# WHY mkdir
+#
+# It is atomic on every POSIX filesystem and it fails if the target exists — one syscall that both tests
+# and claims. `[ -f x ] && ...` is two steps with a race between them, and two pollers a second apart is
+# not a hypothetical when a watcher is restarted.
+set -u
+
+DEPLOYS_DIR="${DEPLOYS_DIR:-$HOME/officer-dev/data/deploys}"
+
+usage() {
+  cat >&2 <<'USAGE'
+usage: deploy-claim.sh claim <version>    take the one attempt for this release (exit 0 = yours, 1 = taken)
+       deploy-claim.sh done  <version>    record that the attempt succeeded
+       deploy-claim.sh state <version>    print unclaimed | claimed | done
+       deploy-claim.sh list               every release this host knows about
+
+To retry a release deliberately: rm -rf <deploys-dir>/<version>.claim
+That is a human act on purpose. A loop cannot undo its own claim.
+USAGE
+  exit 2
+}
+
+version_ok() {
+  # The version reaches here from a git tag, so it is attacker-adjacent input used to build a path.
+  case "$1" in
+    *[!0-9.]* | '' | *..*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+CMD="${1:-}"
+[ -n "$CMD" ] || usage
+
+case "$CMD" in
+  list)
+    mkdir -p "$DEPLOYS_DIR"
+    found=0
+    for d in "$DEPLOYS_DIR"/*.claim; do
+      [ -e "$d" ] || continue
+      found=1
+      v=$(basename "$d" .claim)
+      if [ -f "$DEPLOYS_DIR/$v.done" ]; then s="done"; else s="claimed, no success recorded"; fi
+      printf '%-16s %s\n' "$v" "$s"
+    done
+    [ "$found" = 1 ] || echo "no releases attempted on this host"
+    ;;
+
+  claim | done | state)
+    V="${2:-}"
+    [ -n "$V" ] || usage
+    version_ok "$V" || { echo "deploy-claim: refusing a version that is not digits and dots: $V" >&2; exit 2; }
+    mkdir -p "$DEPLOYS_DIR" || exit 2
+    CLAIM="$DEPLOYS_DIR/$V.claim"
+    DONE="$DEPLOYS_DIR/$V.done"
+
+    case "$CMD" in
+      state)
+        if [ -f "$DONE" ]; then echo done
+        elif [ -d "$CLAIM" ]; then echo claimed
+        else echo unclaimed; fi
+        ;;
+      claim)
+        # A pre-existing .done with no .claim is a release deployed before this script existed. Honour it.
+        if [ -f "$DONE" ]; then
+          echo "deploy-claim: $V is already deployed" >&2
+          exit 1
+        fi
+        if mkdir "$CLAIM" 2>/dev/null; then
+          printf '%s claimed on %s by pid %s\n' "$(date -Iseconds)" "$(hostname)" "$$" > "$CLAIM/by"
+          echo "deploy-claim: $V is yours"
+          exit 0
+        fi
+        printf 'deploy-claim: %s was already attempted — %s\n' "$V" "$(cat "$CLAIM/by" 2>/dev/null || echo 'claim exists')" >&2
+        echo "deploy-claim: NOT retrying. Look at what failed, then rm -rf $CLAIM to allow another attempt." >&2
+        exit 1
+        ;;
+      done)
+        [ -d "$CLAIM" ] || echo "deploy-claim: warning — recording success for $V that was never claimed" >&2
+        printf '%s succeeded on %s\n' "$(date -Iseconds)" "$(hostname)" >> "$DONE"
+        echo "deploy-claim: $V recorded as deployed"
+        ;;
+    esac
+    ;;
+
+  *) usage ;;
+esac

scripts/deploy-claim.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const SCRIPT = join(import.meta.dir, 'deploy-claim.sh');
+let dir: string;
+
+const run = (...args: string[]) => {
+  const p = Bun.spawnSync([SCRIPT, ...args], { env: { ...process.env, DEPLOYS_DIR: dir } });
+  return { code: p.exitCode, out: p.stdout.toString(), err: p.stderr.toString() };
+};
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'deploy-claim-'));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+// The whole point of this script is that the SECOND caller is refused. Everything else is scaffolding.
+describe('deploy-claim', () => {
+  it('grants once and refuses after, whatever the outcome was', () => {
+    expect(run('claim', '2026.09.01.01').code).toBe(0);
+    expect(run('claim', '2026.09.01.01').code).toBe(1);
+    // Still refused after a failure — no .done was ever written. This is the retry storm not happening.
+    expect(run('claim', '2026.09.01.01').code).toBe(1);
+    expect(run('state', '2026.09.01.01').out.trim()).toBe('claimed');
+  });
+
+  it('refuses a release already deployed, even with no claim beside it', () => {
+    // A release deployed by hand before this script existed. `deploy/2026.08.21.01` is exactly this case.
+    writeFileSync(join(dir, '2026.08.21.01.done'), 'deployed by hand\n');
+    expect(run('claim', '2026.08.21.01').code).toBe(1);
+    expect(run('claim', '2026.08.21.01').err).toContain('already deployed');
+  });
+
+  it('lets a human hand the claim back, and only a human', () => {
+    expect(run('claim', '2026.09.01.02').code).toBe(0);
+    rmSync(join(dir, '2026.09.01.02.claim'), { recursive: true });
+    expect(run('claim', '2026.09.01.02').code).toBe(0);
+  });
+
+  it('records success separately from the claim', () => {
+    run('claim', '2026.09.01.03');
+    run('done', '2026.09.01.03');
+    expect(run('state', '2026.09.01.03').out.trim()).toBe('done');
+    expect(existsSync(join(dir, '2026.09.01.03.done'))).toBe(true);
+  });
+
+  // The version comes off a git tag, and it is concatenated into a path.
+  it('refuses anything that is not digits and dots', () => {
+    for (const bad of ['../../etc/passwd', 'x; rm -rf /', '2026.08.21.01/..', '', 'v1']) {
+      expect(run('claim', bad).code).toBe(2);
+    }
+    expect(existsSync(join(dir, '..', 'etc'))).toBe(false);
+  });
+
+  it('says so plainly when nothing has been attempted', () => {
+    expect(run('list').out).toContain('no releases attempted');
+  });
+});

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+/**
+ * `bun run doctor` — check the invariants that provisioning cannot check for itself.
+ *
+ * ── Why ──
+ *
+ * Every step in `provisionOsAccount` is deliberately non-fatal, so "nothing reported an error" is much
+ * weaker than it sounds. The 2026-08-19 case: a fresh server, an Admin granted files, chat and terminal,
+ * every named ACL entry correct, provisioning clean — and the account reached nothing, because a later
+ * `chmod 700` had recomputed the ACL mask to `---`. It was found by a person, three days and one
+ * confusing UI message later.
+ *
+ * This is the same posture as `assertPermissionTotality`: state the invariant, verify it, name the fix.
+ * The difference is that this reports rather than refusing to boot — a broken member must not stop the
+ * platform serving everyone else.
+ *
+ * Read-only. It changes nothing, so it is safe on a production box.
+ *
+ * Exit 1 if anything is wrong, so it can gate the end of a setup run.
+ */
+import { getUsers, getAllRoleGrants, OWNER_USER_ID } from 'officerdb';
+import { checkOsAccount } from '../src/servers/os-user-verify';
+import { PERMISSIONS } from '../src/servers/permissions/registry';
+
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+let problems = 0;
+const fail = (what: string, fix: string) => {
+  problems++;
+  console.log(`${red('✗')} ${what}`);
+  console.log(`  ${dim(fix)}`);
+};
+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();
+
+for (const user of users) {
+  if (user.id === OWNER_USER_ID) {
+    // The owner runs AS the service user, in the service user's own home. There is no Linux account to
+    // check and no ACL to get wrong — `osUser: null` is correct here, not a finding.
+    pass(`${user.email} ${dim('(owner — runs as the service account)')}`);
+    continue;
+  }
+
+  const check = await checkOsAccount(user.email, user.osUser ?? null);
+  if (check.ok) {
+    pass(`${user.email} ${dim(`(${user.role}, os_user=${check.osUser}, home readable)`)}`);
+  } else {
+    fail(`${user.email} (${user.role}) — ${check.problem}`, `home: ${check.home}`);
+  }
+}
+
+console.log('\n── Grants that cannot take effect ──\n');
+
+// A `confined` grant is silently dropped for an account with no Linux user. That is correct behaviour and
+// completely invisible: the grant is in the table, the UI shows it ticked, and it resolves to nothing.
+const confinedKeys = new Set(PERMISSIONS.filter((p) => p.kind === 'confined').map((p) => p.key));
+const grants = await getAllRoleGrants();
+const unconfined = users.filter((u) => u.id !== OWNER_USER_ID && !u.osUser);
+
+if (!unconfined.length) {
+  pass('every non-owner account has a Linux user');
+} else {
+  for (const user of unconfined) {
+    const dropped = grants
+      .filter((g) => g.role === user.role && confinedKeys.has(g.permission))
+      .map((g) => g.permission);
+    if (!dropped.length) continue;
+    fail(
+      `${user.email} (${user.role}) holds ${dropped.join(', ')} — all dropped, because the account has no Linux user`,
+      'Fix: Settings → User management → provision, or POST /api/users/<id>/provision-linux',
+    );
+  }
+}
+
+console.log('');
+if (problems === 0) {
+  console.log(green('No problems found.\n'));
+  process.exit(0);
+}
+console.log(red(`${problems} problem${problems === 1 ? '' : 's'} found.\n`));
+process.exit(1);

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/generate-themes.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env bun
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadPalette } from './themes/palette';
+import { mapPalette } from './themes/map';
+import { TEXT, UI, contrast } from './themes/contrast';
+
+// Generate Officer themes from Omarchy's, and refuse to write an unreadable one.
+//
+//   bun scripts/generate-themes.ts <path-to-omarchy-checkout> [--check]
+//
+// `--check` writes nothing and reports what would change, which is what a test runs.
+//
+// ── Why generated rather than authored ──
+//
+// Twenty-two themes hand-written against an 84-token contract will disagree, and the previous attempt
+// proved it: eleven themes, 34 tokens each, every surface missing. One mapping means one place to be
+// wrong and one place to fix — and a palette that Omarchy updates is a re-run rather than a rewrite.
+//
+// The Duck and Plain themes are NOT generated. They are Officer's own, authored, and this must never
+// overwrite them.
+
+const OMARCHY = process.argv[2];
+const CHECK = process.argv.includes('--check');
+const THEME_DIR = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'css', 'themes');
+
+if (!OMARCHY || !existsSync(join(OMARCHY, 'themes'))) {
+  console.error('usage: bun scripts/generate-themes.ts <path-to-omarchy-checkout> [--check]');
+  process.exit(1);
+}
+
+/** Officer's own. Generated themes may never take these names. */
+const AUTHORED = new Set(['duck-light', 'duck-dark', 'plain']);
+
+const title = (id: string): string =>
+  id
+    .split('-')
+    .map((w) => (w.length <= 2 ? w.toUpperCase() : w[0]!.toUpperCase() + w.slice(1)))
+    .join(' ');
+
+/**
+ * The pairs that must be readable, checked after mapping rather than trusted.
+ *
+ * `ensureContrast` already guarantees most of these — this is the belt to that braces. A mapping change
+ * that quietly breaks one shows up here as a failure instead of as somebody squinting at a screenshot.
+ */
+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],
+  // Not `--border` at UI: a panel edge is decoration and 3:1 would ring everything in a hard line. What
+  // must be visible is a form field's boundary and the focus ring — the two that carry information.
+  ['--input', '--background', 1.35],
+  ['--ring', '--background', UI],
+];
+
+let failures = 0;
+let written = 0;
+const generated: { id: string; name: string; dark: boolean }[] = [];
+
+for (const id of readdirSync(join(OMARCHY, 'themes')).sort()) {
+  const toml = join(OMARCHY, 'themes', id, 'colors.toml');
+  if (!existsSync(toml)) continue;
+  if (AUTHORED.has(id)) {
+    console.log(`  ${id}: SKIPPED — Officer's own theme, never generated`);
+    continue;
+  }
+
+  const palette = loadPalette(toml);
+  const tokens = mapPalette(palette);
+
+  for (const [fgKey, bgKey, min] of PAIRS) {
+    const fg = tokens[fgKey]!;
+    const bg = tokens[bgKey]!;
+    // Only flat hex pairs are checkable — a translucent surface depends on what is behind it.
+    if (!fg.startsWith('#') || !bg.startsWith('#')) continue;
+    const ratio = contrast(fg, bg);
+    if (ratio < min) {
+      console.error(`  ${id}: ${fgKey} on ${bgKey} is ${ratio.toFixed(2)}:1, needs ${min}:1`);
+      failures++;
+    }
+  }
+
+  const body = Object.entries(tokens)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n');
+  const css = `/*
+  ${title(id)} — generated from Omarchy's palette by scripts/generate-themes.ts.
+
+  DO NOT EDIT BY HAND. Change the mapping in scripts/themes/map.ts and re-run, so every theme moves
+  together — the previous port drifted precisely because each file was edited on its own.
+
+  Source: basecamp/omarchy themes/${id}/colors.toml (mode: ${palette.mode})
+*/
+[data-theme='${id}'] {
+${body}
+}
+`;
+
+  const path = join(THEME_DIR, `${id}.css`);
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (before !== css) {
+    if (!CHECK) writeFileSync(path, css);
+    written++;
+  }
+  generated.push({ id, name: title(id), dark: palette.mode === 'dark' });
+}
+
+console.log(`\n  ${generated.length} themes, ${written} ${CHECK ? 'would change' : 'written'}, ${failures} contrast failures`);
+
+if (!CHECK) {
+  // The registry and the stylesheet index, rewritten from what was generated so a theme cannot exist as
+  // a file nobody imports — which is a theme that silently does not work.
+  const imports = generated.map((t) => `@import './themes/${t.id}.css';`).join('\n');
+  const indexPath = join(THEME_DIR, '..', 'index.css');
+  const index = readFileSync(indexPath, 'utf8');
+  const marker = '/* Palette themes';
+  const head = index.slice(0, index.indexOf(marker));
+  writeFileSync(
+    indexPath,
+    `${head}/* Palette themes — generated from Omarchy by scripts/generate-themes.ts. Do not edit this block. */\n${imports}\n\n@import './chrome.css';\n`,
+  );
+  console.log(`  index.css: ${generated.length} imports`);
+
+  // The REGISTRY, from the same list. A theme file nothing imports does not work; a theme imported but
+  // absent from here does not appear in the picker. Both were true of the previous port — catppuccin-mocha
+  // outlived its stylesheet — so both halves are written from one source rather than maintained by hand.
+  //
+  // Display names get a pass for the ones a slug cannot spell.
+  const NICER: Record<string, string> = {
+    'rose-pine': 'Rosé Pine',
+    'retro-82': 'Retro 82',
+    'tokyo-night': 'Tokyo Night',
+    'catppuccin': 'Catppuccin Mocha',
+    'catppuccin-latte': 'Catppuccin Latte',
+  };
+  const FAMILY: Record<string, string> = { catppuccin: 'Catppuccin', 'catppuccin-latte': 'Catppuccin' };
+
+  const rows = generated
+    .map((t) => {
+      const name = NICER[t.id] ?? t.name;
+      const family = FAMILY[t.id] ?? name;
+      return `  { id: '${t.id}', name: '${name}', family: '${family}', applyDarkClass: ${t.dark} },`;
+    })
+    .join('\n');
+
+  const registryPath = join(import.meta.dir, '..', 'src', 'workspaces', 'theme', 'src', 'themes.ts');
+  const registry = readFileSync(registryPath, 'utf8');
+  const START = '  /* GENERATED THEMES — start */';
+  const END = '  /* GENERATED THEMES — end */';
+  if (!registry.includes(START)) {
+    console.error('  themes.ts: missing the GENERATED THEMES markers — not touching it');
+    process.exit(1);
+  }
+  const registryHead = registry.slice(0, registry.indexOf(START) + START.length);
+  const registryTail = registry.slice(registry.indexOf(END));
+  writeFileSync(registryPath, `${registryHead}\n${rows}\n${registryTail}`);
+  console.log(`  themes.ts: ${generated.length} entries`);
+}
+
+process.exit(failures > 0 ? 1 : 0);

scripts/marketplace-sync.ts

@@ -147,7 +147,11 @@ function rawUrl(repoUrl: string, path: string): string {
 }
 
 const dirs = existsSync(PLUGINS_DIR)
-  ? [...new Bun.Glob('*/').scanSync({ cwd: PLUGINS_DIR, onlyFiles: false })].map((d) => join(PLUGINS_DIR, d))
+  ? [...new Bun.Glob('*/').scanSync({ cwd: PLUGINS_DIR, onlyFiles: false })]
+      // Not a plugin: the shared install target for plugin npm packages, which lives here because bun
+      // resolves node_modules up the tree. `discoverPlugins` skips it for the same reason.
+      .filter((d) => d.replace(/\/$/, '') !== 'node_modules')
+      .map((d) => join(PLUGINS_DIR, d))
   : [];
 
 if (dirs.length === 0) {

scripts/nudge-agent.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env bun
+/**
+ * Poke a chat session on a timer, but ONLY when it is idle.
+ *
+ *   bun run nudge -- --session <id> --every 3600 --message "Continue. If blocked, write it down and move on."
+ *   bun run nudge -- --list                       # which sessions exist, and which are working
+ *
+ * ── What this is for ──
+ *
+ * An agent left running overnight. It is told to record blockers and continue rather than wait for a human,
+ * and mostly it does — but a turn that ends leaves it idle until someone types, and at 3am nobody does.
+ * This is the someone.
+ *
+ * ── Why it is a script and not a queue job ──
+ *
+ * The platform has no recurring scheduler and no way to put a prompt into a live session: `pushTurn` has
+ * exactly one caller, the chat websocket. Adding both is real work in the queue engine and the chat API,
+ * and doing it tonight would mean editing a repository an agent is currently working in.
+ *
+ * So this talks to the same doors a browser does — `GET /api/chat/sessions` to see the state, then the chat
+ * websocket to speak. Nothing new is exposed and nothing in the platform changes. If the loop is ever worth
+ * making permanent, it belongs in the queue with a real trigger, and this script is what that would replace.
+ *
+ * ── The one rule ──
+ *
+ * NEVER interrupt work. A nudge sent mid-turn is at best noise and at worst a derail, so `isGenerating` is
+ * checked immediately before speaking and a working session is skipped silently. The point is to restart a
+ * stopped agent, not to hurry a busy one.
+ */
+import { sign } from '@@/jwt';
+import { getOwnerUser } from 'officerdb';
+
+const arg = (name: string): string | undefined => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const has = (name: string) => process.argv.includes(`--${name}`);
+
+const PORT = process.env.OFFICERDEV_PORT ?? process.env.PORT ?? '9000';
+const BASE = `http://127.0.0.1:${PORT}`;
+
+const owner = await getOwnerUser();
+if (!owner) {
+  console.error('[nudge] no owner account — nothing to sign as');
+  process.exit(1);
+}
+// Minted here rather than asked for: this runs on the box, as the owner, and a token pasted into a shell
+// is a token in the shell history.
+const token = await sign({ id: owner.id, email: owner.email, username: owner.username }, '2d');
+
+type Session = { id: string; title?: string; isGenerating?: boolean; updatedAt?: string };
+
+async function sessions(): Promise<Session[]> {
+  // `?all=1` — every working directory, not just the default one. Without it the list is scoped to the
+  // owner's home and an agent started in a project directory is simply absent, which reads as "the session
+  // is gone" and stops the loop. This is the list's own Latest tab, so the shape is identical.
+  const res = await fetch(`${BASE}/api/chat/sessions?all=1`, {
+    headers: { authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!res.ok) throw new Error(`GET /api/chat/sessions → ${res.status}`);
+  const body = (await res.json()) as { sessions?: Session[] } | Session[];
+  return Array.isArray(body) ? body : (body.sessions ?? []);
+}
+
+if (has('list')) {
+  for (const s of await sessions()) {
+    console.log(`${s.isGenerating ? 'WORKING ' : 'idle    '} ${s.id}  ${s.title ?? ''}`);
+  }
+  process.exit(0);
+}
+
+const sessionId = arg('session');
+const message =
+  arg('message') ?? 'Continue with the next task. If you are blocked, write the blocker down and move on.';
+const every = Number(arg('every') ?? 3600);
+/** A ceiling, because a loop nobody is watching should end on its own. Twelve hours by default. */
+const max = Number(arg('max') ?? 12);
+
+if (!sessionId) {
+  console.error('[nudge] --session <id> is required. Use --list to find one.');
+  process.exit(2);
+}
+
+/** Send one prompt, the way the browser does. Resolves once the server acknowledges the turn. */
+function nudge(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proto = 'ws';
+    const ws = new WebSocket(`${proto}://127.0.0.1:${PORT}/api/chat/ws?token=${token}&sessionId=${sessionId}`);
+    const done = (err?: Error) => {
+      try {
+        ws.close();
+      } catch {
+        /* already closing */
+      }
+      err ? reject(err) : resolve();
+    };
+
+    const timer = setTimeout(() => done(new Error('no acknowledgement within 30s')), 30_000);
+
+    ws.onopen = () => ws.send(JSON.stringify({ type: 'chat', prompt: message, sessionId }));
+    ws.onmessage = (ev) => {
+      // Anything that is not an error means the turn was taken. We do not wait for it to FINISH — that is
+      // the agent's night, not ours.
+      try {
+        const msg = JSON.parse(String(ev.data)) as { type?: string; message?: string };
+        if (msg.type === 'error') {
+          clearTimeout(timer);
+          return done(new Error(msg.message ?? 'server refused the prompt'));
+        }
+        if (msg.type === 'assistant:delta' || msg.type === 'assistant:text' || msg.type === 'tool:start') {
+          clearTimeout(timer);
+          return done();
+        }
+      } catch {
+        /* not json — ignore */
+      }
+    };
+    ws.onerror = () => {
+      clearTimeout(timer);
+      done(new Error('websocket error'));
+    };
+  });
+}
+
+const stamp = () => new Date().toISOString().slice(11, 19);
+
+console.log(`[nudge] session ${sessionId} — every ${every}s, at most ${max} times`);
+console.log(`[nudge] message: ${message}`);
+
+for (let sent = 0, tick = 0; sent < max; tick++) {
+  if (tick > 0) await Bun.sleep(every * 1000);
+
+  let state: Session | undefined;
+  try {
+    state = (await sessions()).find((s) => s.id === sessionId);
+  } catch (err) {
+    console.error(`[nudge ${stamp()}] could not read sessions: ${err instanceof Error ? err.message : err}`);
+    continue; // a server restart is not a reason to give up on the night
+  }
+
+  if (!state) {
+    console.error(`[nudge ${stamp()}] session ${sessionId} is gone — stopping`);
+    break;
+  }
+
+  if (state.isGenerating) {
+    console.log(`[nudge ${stamp()}] working — skipped`);
+    continue;
+  }
+
+  try {
+    await nudge();
+    sent++;
+    console.log(`[nudge ${stamp()}] idle — nudged (${sent}/${max})`);
+  } catch (err) {
+    console.error(`[nudge ${stamp()}] failed: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+console.log(`[nudge ${stamp()}] finished`);
+process.exit(0);

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/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'`
+# PATH — and every ecosystem app that says `script: 'bun'` then fails to start on
-# then fails to start on reboot while working perfectly when started by hand. A
+# 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 "     bun    ${BUN_NOW:-not installed} — pinned to the ${BUN_SERIES} series${BUN_WANT:+, newest is ${BUN_WANT}}"
-  echo "            the platform itself, and nineteen of the twenty pm2 apps."
+  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 ──
+  # ── 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
-    ok "bun $(bun_version) already installed"
+      echo "     leaving bun ${BUN_NOW} where it is"
+      ERRORS+=("Bun: could not resolve ${BUN_SERIES}.x; left ${BUN_NOW} alone")
     else
-    info "     installing bun..."
+      echo "     nothing installed — this will not install an unpinned bun, and"
-    if install_bun && bun_installed; then
+      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/contrast.ts

@@ -0,0 +1,96 @@
+// WCAG contrast, so "is this readable" stops being a matter of taste.
+//
+// Every complaint about the current themes reduces to one of two failures: a highlight so strong it
+// masks the content on it, or text so close to its background it disappears. Both are a contrast ratio,
+// and a ratio is checkable. This file is what turns the whole exercise from opinion into a test.
+
+export type Rgb = { r: number; g: number; b: number };
+
+export function parseHex(hex: string): Rgb {
+  const h = hex.trim().replace('#', '');
+  const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+  return {
+    r: Number.parseInt(full.slice(0, 2), 16),
+    g: Number.parseInt(full.slice(2, 4), 16),
+    b: Number.parseInt(full.slice(4, 6), 16),
+  };
+}
+
+export const toHex = ({ r, g, b }: Rgb): string =>
+  `#${[r, g, b].map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('')}`;
+
+/** Relative luminance, per WCAG 2.1. */
+export function luminance(c: Rgb): number {
+  const channel = (v: number) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(c.r) + 0.7152 * channel(c.g) + 0.0722 * channel(c.b);
+}
+
+/** 1 (identical) to 21 (black on white). */
+export function contrast(a: string, b: string): number {
+  const [x, y] = [luminance(parseHex(a)), luminance(parseHex(b))];
+  const [hi, lo] = x > y ? [x, y] : [y, x];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * The thresholds, and why these ones.
+ *
+ * `TEXT` is WCAG AA for body text. `UI` is AA for large text and non-text contrast — borders, icons, the
+ * edge of a control. A border at 4.5 would be a hard line around everything, which is a different design
+ * rather than a more accessible one.
+ */
+export const TEXT = 4.5;
+export const UI = 3;
+
+/**
+ * Push a foreground away from its background until it is readable.
+ *
+ * Moves toward black or white — whichever the background is further from — in small steps, so a colour
+ * that is nearly readable keeps almost all of its hue and only a hopeless one ends up monochrome. That
+ * matters: the point is a theme that still looks like Nord, not one that passes and looks like nothing.
+ *
+ * Returns the original when it already passes, so a well-chosen palette is untouched.
+ */
+export function ensureContrast(fg: string, bg: string, min = TEXT): string {
+  if (contrast(fg, bg) >= min) return fg;
+
+  // Whichever extreme is FURTHER from the background, not whichever side of mid-grey it falls on.
+  // Those differ for a mid-tone fill and the difference is the whole answer: rose-pine's rose is at
+  // luminance 0.25, so a `> 0.5` test sends this toward white and caps at 3.5:1, while black reaches
+  // 6:1 easily. Six of its tones were unfixable until this stopped guessing and measured.
+  const black = '#000000';
+  const white = '#ffffff';
+  const target = parseHex(contrast(black, bg) >= contrast(white, bg) ? black : white);
+  const start = parseHex(fg);
+
+  // 40 steps of 2.5% each. Fine enough that the first passing value is close to the original.
+  for (let i = 1; i <= 40; i++) {
+    const t = i / 40;
+    const moved = toHex({
+      r: start.r + (target.r - start.r) * t,
+      g: start.g + (target.g - start.g) * t,
+      b: start.b + (target.b - start.b) * t,
+    });
+    if (contrast(moved, bg) >= min) return moved;
+  }
+  return toHex(target);
+}
+
+/** Blend two colours. `amount` is how much of `b`. */
+export function mix(a: string, b: string, amount: number): string {
+  const [x, y] = [parseHex(a), parseHex(b)];
+  return toHex({
+    r: x.r + (y.r - x.r) * amount,
+    g: x.g + (y.g - x.g) * amount,
+    b: x.b + (y.b - x.b) * amount,
+  });
+}
+
+/** `#rrggbb` → `r g b` for `rgb(var(--x) / 0.5)`, which is how the surfaces get their opacity. */
+export const rgbTriplet = (hex: string): string => {
+  const { r, g, b } = parseHex(hex);
+  return `${r} ${g} ${b}`;
+};

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

@@ -0,0 +1,200 @@
+import type { Palette } from './palette';
+import { UI, contrast, ensureContrast, mix, rgbTriplet } from './contrast';
+
+// Omarchy palette → Officer's 84 declarations.
+//
+// This file is the whole port. It exists once so that twenty-two themes cannot disagree about what
+// "muted" means, and so that improving the mapping improves all of them at once.
+//
+// ── What went wrong before, and what this fixes ──
+//
+// The previous port produced 34 declarations per theme against a contract of 84. The missing fifty were
+// every surface (`--panel-bg`, `--card-bg`, `--glass-bg`), every state colour (`--success`, `--warning`,
+// `--busy`, `--info`), the header, the scrollbars and the grid — so they fell back to whatever the base
+// stylesheet or the previous theme left behind. That is why highlights masked content and text faded
+// out: not taste, absence. It also shipped thirteen tokens nothing reads (`--chart-1..5`, `--sidebar-*`),
+// which is the tell that it came from a shadcn template rather than from this codebase's contract.
+//
+// ── The rule that makes them readable ──
+//
+// Every foreground is run through `ensureContrast` against the surface it actually sits on. A palette
+// whose colours are already readable is untouched; one that is not gets nudged toward black or white
+// until it passes, keeping as much hue as it can. So a theme cannot ship with invisible text, no matter
+// what its author chose.
+
+export type Tokens = Record<string, string>;
+
+/** Depth ordering differs by mode: a light theme's "darker" is its raised surface, not its page. */
+function surfaces(p: Palette) {
+  const dark = p.mode === 'dark';
+  return {
+    /** The page. The deepest surface in dark, the plainest in light. */
+    page: dark ? p.darkerBackground : p.background,
+    /** Panels and cards sit one step up from the page, so a tile reads as a tile. */
+    raised: dark ? p.background : p.lighterBackground,
+    /** Hovers, secondary fills, the header. One step up again. */
+    high: dark ? p.lighterBackground : p.darkBackground,
+    dark,
+  };
+}
+
+export function mapPalette(p: Palette): Tokens {
+  const s = surfaces(p);
+
+  // Text, checked against the surface each weight actually appears on.
+  const fg = ensureContrast(p.foreground, s.page);
+  const fgRaised = ensureContrast(p.foreground, s.raised);
+  // Checked against `s.high`, not `s.raised`: `--muted-foreground` is the text ON `--muted`, and
+  // `--muted` is the high surface. Deriving it against the wrong one left everforest at 4.44:1 and
+  // 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);
+
+  /**
+   * Text for a solid fill of `bg`.
+   *
+   * Tries the palette's own extremes first, so a button's label still belongs to the theme, and only
+   * falls through to `ensureContrast` when neither is readable. Both steps are needed: picking the
+   * better of two candidates does NOT guarantee either passes — rose-pine's fills are all mid-tone and
+   * every one came out between 2.2:1 and 4.2:1 until this drove it the rest of the way.
+   */
+  const on = (bg: string): string => {
+    const light = p.brightForeground;
+    const dark = p.darkerBackground;
+    const better = contrast(light, bg) >= contrast(dark, bg) ? light : dark;
+    return ensureContrast(better, bg);
+  };
+
+  const accent = p.accent;
+  // Borders are DECORATION, not information, so they are not held to a text ratio — a 3:1 line drawn
+  // around every panel is a different design, not a more accessible one. What they must be is
+  // discernible, which `--input` below is checked for: a form field whose boundary you cannot see is a
+  // real accessibility failure, unlike a subtle panel edge.
+  const border = mix(s.raised, s.dark ? p.lightForeground : p.darkForeground, 0.28);
+
+  return {
+    // ── Ground ──
+    '--background': s.page,
+    '--foreground': fg,
+
+    // ── Surfaces ──
+    '--card': s.raised,
+    '--card-foreground': fgRaised,
+    '--popover': s.raised,
+    '--popover-foreground': fgRaised,
+    // `muted` is a SURFACE here, not the palette's `muted` colour — that one is a mid-grey meant for
+    // dimmed text, and using it as a fill is precisely how a highlight ends up masking its content.
+    '--muted': s.high,
+    '--muted-foreground': fgMuted,
+    '--accent': s.high,
+    '--accent-foreground': fgHigh,
+
+    // ── Actions ──
+    '--primary': accent,
+    '--primary-foreground': on(accent),
+    '--secondary': s.high,
+    '--secondary-foreground': fgHigh,
+    '--cta': accent,
+    '--cta-foreground': on(accent),
+    '--ctahover': mix(accent, s.dark ? '#ffffff' : '#000000', 0.12),
+
+    // ── State — five tones, each readable on its own fill ──
+    '--success': p.green,
+    '--success-foreground': on(p.green),
+    '--warning': p.yellow,
+    '--warning-foreground': on(p.yellow),
+    '--destructive': p.red,
+    '--destructive-foreground': on(p.red),
+    '--info': p.blue,
+    '--info-foreground': on(p.blue),
+    '--busy': p.orange,
+    '--busy-foreground': on(p.orange),
+    // The odd one, per the contract: a fill bright enough for black text is too light to BE text. So ink
+    // is the same hue pushed until it reads on the page.
+    '--busy-ink': ensureContrast(p.orange, s.page),
+
+    // ── Lines ──
+    '--border': border,
+    '--input': border,
+    '--ring': accent,
+    '--radius': '0.625rem',
+
+    // ── Data ──
+    '--chart-primary': accent,
+    '--chart-secondary': p.magenta,
+    '--status-success': p.green,
+    '--status-warning': p.yellow,
+    '--status-in-progress': p.blue,
+
+    // ── Surfaces, as complete CSS values ──
+    '--page-bg': s.page,
+    '--page-bg-src': "''",
+    '--panel-bg': `rgb(${rgbTriplet(s.raised)} / 0.72)`,
+    '--panel-border': `rgb(${rgbTriplet(border)} / 0.9)`,
+    '--panel-border-bare': `rgb(${rgbTriplet(border)} / 0.55)`,
+    // DENSER, not darker — panel chrome is dark text and a heavy fill hides every icon. The contract
+    // says so; this is the one place a value is chosen to obey a sentence rather than a ratio.
+    '--panel-raised-bg': `rgb(${rgbTriplet(s.raised)} / 0.95)`,
+    '--panel-raised-border': `rgb(${rgbTriplet(border)} / 1)`,
+    '--panel-accent': accent,
+    '--panel-header-bg': `rgb(${rgbTriplet(s.high)} / 0.6)`,
+    '--panel-header-fg': fgRaised,
+    '--panel-radius': '0.75rem',
+    '--panel-blur': '12px',
+    '--card-bg': s.raised,
+    '--glass-bg': `rgb(${rgbTriplet(s.raised)} / 0.55)`,
+    '--glass-border': `rgb(${rgbTriplet(border)} / 0.7)`,
+    '--dock-bg': `rgb(${rgbTriplet(s.raised)} / 0.7)`,
+    '--dock-border': `rgb(${rgbTriplet(border)} / 0.8)`,
+    '--dock-tooltip-bg': s.high,
+    '--header-bg': `rgb(${rgbTriplet(s.raised)} / 0.8)`,
+    '--header-border': `rgb(${rgbTriplet(border)} / 0.9)`,
+    '--header-fg': fgRaised,
+    '--header-blur': '12px',
+
+    // Grid lines are a texture, not a colour anyone should notice — kept just above the surface.
+    '--pixel-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.07)`,
+    '--card-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.05)`,
+    '--panel-grid-color': `rgb(${rgbTriplet(fgFaint)} / 0.06)`,
+
+    '--scrollbar-thumb': `rgb(${rgbTriplet(p.muted)} / 0.6)`,
+    '--scrollbar-thumb-hover': `rgb(${rgbTriplet(p.muted)} / 0.85)`,
+    '--scrollbar-thin-thumb': `rgb(${rgbTriplet(p.muted)} / 0.45)`,
+    '--scrollbar-thin-thumb-hover': `rgb(${rgbTriplet(p.muted)} / 0.7)`,
+
+    // ── Brand slots ──
+    //
+    // A ported theme has no brand of its own, so these follow its accent rather than importing Duck's
+    // green into somebody else's palette. `--ink` is the app's text colour and is used ~950 times.
+    '--brand': accent,
+    '--brand-foreground': on(accent),
+    '--brand-primary': accent,
+    '--brand-accent': p.cyan,
+    '--brand-warm': p.orange,
+    '--brand-deep': s.dark ? p.darkerBackground : p.darkBackground,
+    '--brand-muted': p.muted,
+    '--ink': fg,
+    '--surface-warm': s.raised,
+    '--naturegreen': p.green,
+    '--naturegreen-foreground': on(p.green),
+
+    // Legacy aliases the contract keeps until the utility rename lands — `prose.css` and some plugins
+    // read them directly, so a theme without them has unstyled prose.
+    '--duck-dark': fg,
+    '--duck-teal': p.cyan,
+    '--duck-yellow': p.yellow,
+    '--duck-orange': p.orange,
+    '--duck-forest': p.green,
+    '--duck-beige': mix(s.raised, fg, 0.1),
+
+    '--logo-src': "'/officer-logo.svg'",
+  };
+}

scripts/themes/palette.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+
+// Reading an Omarchy theme's `colors.toml`.
+//
+// Omarchy 4 ships a genuinely semantic palette rather than sixteen ANSI slots: three background depths,
+// four foreground weights, an accent, a selection and a muted, plus the named hues. That is why this port
+// can be a mapping at all — the previous one had to guess, and the guessing is what produced themes with
+// no surfaces and unreadable highlights.
+//
+// Verified across all 22 themes in basecamp/omarchy@master: every one declares the 24 keys below.
+
+export type Palette = {
+  mode: 'dark' | 'light';
+  accent: string;
+  selection: string;
+  muted: string;
+  background: string;
+  darkBackground: string;
+  darkerBackground: string;
+  lighterBackground: string;
+  foreground: string;
+  darkForeground: string;
+  lightForeground: string;
+  brightForeground: string;
+  red: string;
+  yellow: string;
+  green: string;
+  cyan: string;
+  blue: string;
+  magenta: string;
+  /** Not in every theme — 19 of 22. Falls back to yellow-red mid, which is what orange is. */
+  orange: string;
+  brightRed: string;
+  brightYellow: string;
+  brightGreen: string;
+  brightCyan: string;
+  brightBlue: string;
+  brightMagenta: 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 text.split('\n')) {
+    const m = line.match(/^\s*([a-z_0-9]+)\s*=\s*"([^"]*)"/i);
+    // 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;
+}
+
+/** 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(`${label}: missing "${key}"`);
+    return v;
+  };
+
+  return {
+    mode: t.mode === 'light' ? 'light' : 'dark',
+    accent: need('accent'),
+    selection: need('selection'),
+    muted: need('muted'),
+    background: need('background'),
+    darkBackground: need('dark_background'),
+    darkerBackground: need('darker_background'),
+    lighterBackground: need('lighter_background'),
+    foreground: need('foreground'),
+    darkForeground: need('dark_foreground'),
+    lightForeground: need('light_foreground'),
+    brightForeground: need('bright_foreground'),
+    red: need('red'),
+    yellow: need('yellow'),
+    green: need('green'),
+    cyan: need('cyan'),
+    blue: need('blue'),
+    magenta: need('magenta'),
+    orange: t.orange ?? need('yellow'),
+    brightRed: need('bright_red'),
+    brightYellow: need('bright_yellow'),
+    brightGreen: need('bright_green'),
+    brightCyan: need('bright_cyan'),
+    brightBlue: need('bright_blue'),
+    brightMagenta: need('bright_magenta'),
+  };
+}
+
+export function loadPalette(tomlPath: string): Palette {
+  return paletteFromRecord(parseTomlText(readFileSync(tomlPath, 'utf8')), tomlPath);
+}

scripts/todo-index.ts

@@ -0,0 +1,140 @@
+/**
+ * Regenerate `TODO.md` — the index over `todo/`.
+ *
+ * The index is the one file everybody reads, so it is the one most able to lie. It is generated rather
+ * than maintained: `bun run todo:index` after any change to `todo/`, and it cannot drift from the tree
+ * it describes.
+ */
+import { readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = new URL('..', import.meta.url).pathname;
+const OUT = join(ROOT, 'todo');
+
+export type Item = {
+  id: string;
+  title: string;
+  theme: string;
+  status: string;
+  created: string;
+  /** `urgent` or empty — see todo/README.md for why there is no scale. */
+  priority: string;
+  due: string;
+  order: number;
+  file: string;
+};
+
+/** Minimal frontmatter reader — `key: value`, values optionally JSON-quoted. No YAML dependency. */
+export function frontmatter(text: string): Record<string, string> {
+  const end = text.indexOf('\n---', 4);
+  if (!text.startsWith('---') || end === -1) return {};
+  const out: Record<string, string> = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (!m || !m[1]) continue;
+    const raw = (m[2] ?? '').trim();
+    out[m[1]] = raw.startsWith('"') ? (JSON.parse(raw) as string) : raw;
+  }
+  return out;
+}
+
+export function readTree(): { themes: { theme: string; heading: string; items: Item[] }[] } {
+  const themes = readdirSync(OUT)
+    .filter((d) => statSync(join(OUT, d)).isDirectory())
+    .sort()
+    .map((theme) => {
+      const files = readdirSync(join(OUT, theme)).filter((f) => f.endsWith('.md'));
+      const meta = frontmatter(readFileSync(join(OUT, theme, '_index.md'), 'utf8'));
+      const items = files
+        .filter((f) => f !== '_index.md')
+        .map((f) => {
+          const fm = frontmatter(readFileSync(join(OUT, theme, f), 'utf8'));
+          return {
+            id: fm.id ?? `${theme}/${f.replace(/\.md$/, '')}`,
+            title: fm.title ?? f,
+            theme,
+            status: fm.status ?? 'open',
+            created: fm.created ?? '',
+            priority: fm.priority ?? '',
+            due: fm.due ?? '',
+            order: Number(fm.order ?? 0),
+            file: `todo/${theme}/${f}`,
+          };
+        })
+        .sort((a, b) => a.order - b.order);
+      return { theme, heading: meta.heading ?? theme, items };
+    });
+  return { themes };
+}
+
+const HEADER = `# TODO — the index
+
+Deferred work. **The items live in \`todo/\`, one file each**, grouped by theme; this file is the map
+over them and is GENERATED — run \`bun run todo:index\` after any change rather than editing it here.
+Format and the two-way-sync contract: \`todo/README.md\`.
+
+**Context, corrected 2026-08-07.** This list used to open by saying Officer was "collapsing from
+multi-tenant / open-source-ready to a **single-user platform**", and told you to treat multi-tenant
+indirection as accidental complexity. **That direction was reversed.** The permission model shipped on
+2026-08-07 to serve a real goal — deploy to the company server, onboard people, give each one their own
+Gitea account through the platform. Per-user scoping is now a requirement, and the items that proposed
+deleting it have been removed rather than left to mislead the next reader.
+
+What did NOT reverse: \`execution\` permissions (terminal, chat, tasks, files, desktop, browser) run as
+the owner's OS user and can never be granted. Indirection there really is accidental complexity.
+`;
+
+function render(): string {
+  const { themes } = readTree();
+  const open = themes.reduce((n, t) => n + t.items.filter((i) => i.status !== 'done').length, 0);
+  const done = themes.reduce((n, t) => n + t.items.filter((i) => i.status === 'done').length, 0);
+
+  const rows = themes
+    .filter((t) => t.items.length)
+    .map((t) => {
+      const o = t.items.filter((i) => i.status !== 'done').length;
+      const d = t.items.length - o;
+      return `| [${t.heading}](todo/${t.theme}/) | ${o} | ${d} |`;
+    });
+
+  const recent = themes
+    .flatMap((t) => t.items)
+    .filter((i) => i.status !== 'done')
+    .sort((a, b) => b.created.localeCompare(a.created))
+    .slice(0, 10)
+    .map((i) => `- \`${i.created}\` **${i.title}** — [${i.id}](${i.file})`);
+
+  // A theme holding only prose has no row above, and an entry nobody can see is the failure mode this
+  // whole split risks. List them explicitly rather than letting them age out of view.
+  const notes = themes.filter((t) => !t.items.length).map((t) => `- [${t.heading}](todo/${t.theme}/_index.md)`);
+
+  // Urgent goes above everything. An item the owner called urgent, sorted in among seventy-five others
+  // by theme, is an item nobody sees on the day it matters.
+  const urgent = themes
+    .flatMap((t) => t.items)
+    .filter((i) => i.status !== 'done' && i.priority === 'urgent')
+    .sort((a, b) => (a.due || '9999').localeCompare(b.due || '9999'))
+    .map((i) => `- ${i.due ? `**due ${i.due}** — ` : ''}**${i.title}** — [${i.id}](${i.file})`);
+
+  return [
+    HEADER,
+    ...(urgent.length ? [`## Urgent\n`, ...urgent, ``] : []),
+    `## Themes\n`,
+    `**${open} open, ${done} closed**, across ${rows.length} themes.\n`,
+    `| Theme | Open | Closed |`,
+    `| --- | --- | --- |`,
+    ...rows,
+    ``,
+    `## Records — no items, kept for the reasoning\n`,
+    ...notes,
+    ``,
+    `## Newest ten\n`,
+    ...recent,
+    ``,
+  ].join('\n');
+}
+
+if (import.meta.main) {
+  writeFileSync(join(ROOT, 'TODO.md'), render());
+  console.log('TODO.md regenerated');
+}

scripts/update-plugins.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+import { snapshotPlugins } from '../src/servers/plugins/mount';
+import { updatePlugin, syncCapabilities } from '../src/servers/plugins/update';
+
+// Update every installed plugin, from a terminal.
+//
+//   bun run plugins:update
+//
+// ── Why this exists ──
+//
+// The only way to do this was `POST /api/plugins/update-all`, which is authenticated — so a deploy had to
+// mint an API key to update the plugins on the machine it was already logged into. That is a credential
+// created, used and hopefully deleted, on every host, for a local operation.
+//
+// This is the same work through the same functions, with the HTTP layer removed rather than a second
+// implementation beside it. `prompts/deploy-commander.md` calls it.
+//
+// ── It runs OUTSIDE the server process ──
+//
+// Which matters, and is the one thing to know before reading the output. `updatePlugin` pulls, re-applies
+// and rebuilds the frontend — all of which touch disk and are picked up by the running server. But
+// remounting happens in the process that calls it, and this is not that process, so the routes the
+// server is serving do not change until it restarts.
+//
+// So: the files, the schema, the assets and the SPA bundle are all current when this finishes. The route
+// table is not. A deploy restarts `officer` afterwards, which is what makes the difference invisible —
+// and the reason this says so rather than leaving somebody to find out.
+
+const started = Date.now();
+const { states } = await snapshotPlugins();
+const installed = states.filter((st) => st.install).map((st) => st.plugin.appName);
+
+if (installed.length === 0) {
+  console.log('no plugins installed — nothing to update');
+  process.exit(0);
+}
+
+console.log(`updating ${installed.length} plugin(s): ${installed.join(', ')}\n`);
+
+let failed = 0;
+
+// SEQUENTIAL, like the route: each update pushes a schema, republishes assets, rewrites the ecosystem
+// file and rebuilds the frontend. Two at once is a race over one file each.
+for (const appName of installed) {
+  process.stdout.write(`→ ${appName}\n`);
+  // One plugin failing must not stop the rest. A dirty checkout is the EXPECTED failure — every plugin
+  // directory on a developer machine is a live one — and it should not hold back the other eleven.
+  const result = await updatePlugin(appName, async (step) => console.log(`    ${step}`));
+  if (!result.ok) {
+    failed++;
+    console.error(`    FAILED: ${result.error}`);
+  }
+}
+
+// The capabilities repository rides along, the same as it does through the button: it is one question —
+// "get me what has been published since I installed" — and a second gesture for it is one nobody remembers.
+const capabilities = await syncCapabilities();
+console.log(`\ncapabilities: ${capabilities.action}${capabilities.error ? ` — ${capabilities.error}` : ''}`);
+
+const ok = installed.length - failed;
+console.log(`${ok}/${installed.length} updated in ${Math.round((Date.now() - started) / 1000)}s`);
+if (failed) console.log("a failure above is usually an uncommitted change in that plugin's checkout");
+
+// Non-zero on failure, so a deploy script can stop rather than reporting a success it did not have.
+process.exit(failed > 0 ? 1 : 0);

src/apps/officer-web/App.tsx

@@ -106,6 +106,7 @@ 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="/activity" element={<Dashboard.ActivityScreen />} />
             <Route path="/activity/:id" element={<Dashboard.ActivityScreen />} />
 
@@ -120,10 +121,7 @@ export function App() {
             <Route path="/jobs/:id" element={<Dashboard.JobsPage />} />
             <Route path="/dashboards" element={<Dashboard.DashboardsScreen />} />
             <Route path="/dashboards/:id" element={<Dashboard.DashboardScreen />} />
-            <Route path="/browser" element={<Dashboard.BrowserScreen />} />
-            <Route path="/browser/:tabId" element={<Dashboard.BrowserScreen />} />
             <Route path="/terminal" element={<Dashboard.TerminalScreen />} />
-            <Route path="/desktop" element={<Dashboard.DesktopScreen />} />
             <Route path="/auth/signout" element={<Authentication.SignoutScreen />} />
             <Route path="*" element={<Navigate to="/" replace />} />
           </Routes>

src/apps/officer-web/Screens/Dashboard/Activity/ActivityScreen.tsx

@@ -102,7 +102,7 @@ export const ActivityScreen = () => {
             title={t.cwd}
           >
             <span
-              className={`inline-block h-2 w-2 shrink-0 rounded-full ${t.active ? 'bg-emerald-500 animate-pulse' : 'bg-muted-foreground/40'}`}
+              className={`inline-block h-2 w-2 shrink-0 rounded-full ${t.active ? 'bg-success animate-pulse' : 'bg-muted-foreground/40'}`}
             />
             <span className="truncate font-mono text-xs">{t.id}</span>
           </Link>

src/apps/officer-web/Screens/Dashboard/Browser/BrowserScreen.tsx

@@ -1,48 +0,0 @@
-import { useMemo, useCallback } from 'react';
-import { useNavigate } from 'react-router';
-import type { LayoutNode, PanelComponents } from 'officerdev';
-import { WorkspaceView, ChatPanelWrapper } from 'officerdev';
-import { useDashboardState } from 'state/useDashboardState';
-import { useIsMobile } from 'hooks/useIsMobile';
-import { defaultLayout } from './defaultLayout';
-import { TabList } from './TabList';
-import { TabPreview } from './TabPreview';
-import { useSelectedTabId } from './shared';
-
-const PROMPT_PREFIX = `You are a browser assistant. The user has connected Chrome tabs via the Officer Browser Relay. You have a 'browser' tool — use it to list tabs, take screenshots, navigate, evaluate JavaScript, and get page info. When asked about a page, take a screenshot first.`;
-
-// This screen's prompt, so this screen's chat panel. See the note in `EmailScreen`.
-const BrowserChatPanel = () => <ChatPanelWrapper panelId="browser-chat" promptPrefix={PROMPT_PREFIX} />;
-
-export const BrowserScreen = () => {
-  const isMobile = useIsMobile();
-  const navigate = useNavigate();
-  // No redirect guard: like /email, the bare /browser is the list with nothing open, and a tab id that
-  // no longer resolves gets the preview's "no longer attached" state rather than a rewritten address.
-  const selectedId = useSelectedTabId();
-  const workspace = useDashboardState<LayoutNode>('screens/browser', defaultLayout);
-
-  const components: PanelComponents = useMemo(
-    () => ({
-      'browser-tabs': TabList,
-      'browser-preview': TabPreview,
-      'browser-chat': BrowserChatPanel,
-    }),
-    [],
-  );
-
-  const mobilePanelId = isMobile && selectedId ? 'browser-preview' : undefined;
-  const onMobileBack = useCallback(() => navigate('/browser'), [navigate]);
-
-  return (
-    <div className="h-full w-full pt-2">
-      <WorkspaceView
-        workspace={workspace}
-        locked
-        components={components}
-        mobilePanelId={mobilePanelId}
-        onMobilePanelChange={mobilePanelId ? () => onMobileBack() : undefined}
-      />
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Browser/TabList.tsx

@@ -1,117 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-import { Link } from 'react-router';
-import { Globe, Loader2, X, Eye } from 'lucide-react';
-import { toast } from 'sonner';
-import { useClient } from 'hooks/useClient';
-import { browserTabPath, useBrowserTargets, useSelectedTabId, type BrowserTarget } from './shared';
-
-export const TabList = () => {
-  const client = useClient();
-  const selectedId = useSelectedTabId();
-
-  const { data: status } = useQuery({
-    queryKey: ['browser-status'],
-    queryFn: () => client.get<{ extensionConnected: boolean; targetCount: number }>('/browser/status'),
-    refetchInterval: 5000,
-  });
-
-  const { data: targets, isLoading } = useBrowserTargets(!!status?.extensionConnected);
-
-  const targetList: BrowserTarget[] = targets ?? [];
-
-  const handleClose = async (targetId: string) => {
-    try {
-      await client.post(`/browser/targets/${targetId}/close`);
-    } catch {
-      toast.error('Failed to close tab');
-    }
-  };
-
-  const handleActivate = async (targetId: string) => {
-    try {
-      await client.post(`/browser/targets/${targetId}/activate`);
-    } catch {
-      toast.error('Failed to activate tab');
-    }
-  };
-
-  const isConnected = status?.extensionConnected ?? false;
-
-  return (
-    <div className="flex h-full flex-col overflow-y-auto">
-      <div className="flex items-center gap-2 border-b px-3 py-2">
-        <Globe className="h-4 w-4 opacity-60" />
-        <span className="text-sm font-medium">Browser</span>
-        <div
-          className={`ml-auto h-2 w-2 rounded-full ${isConnected ? 'bg-green-500' : 'bg-red-500'}`}
-          title={isConnected ? 'Extension connected' : 'Extension not connected'}
-        />
-      </div>
-
-      {!isConnected && (
-        <div className="flex flex-col items-center justify-center gap-3 p-4 text-sm flex-1">
-          <Globe className="h-8 w-8 opacity-30" />
-          <p className="opacity-60 text-center">Extension not connected</p>
-          {/* A <Link>, not an <a href>: a raw href to an in-app route reloads the whole SPA. */}
-          <Link to="/settings/integrations" className="text-xs text-duck-teal underline">
-            Set up in Integrations
-          </Link>
-        </div>
-      )}
-
-      {isConnected && isLoading && (
-        <div className="flex h-32 items-center justify-center">
-          <Loader2 className="h-5 w-5 animate-spin opacity-50" />
-        </div>
-      )}
-
-      {isConnected && !isLoading && targetList.length === 0 && (
-        <div className="flex h-32 flex-col items-center justify-center gap-2 text-sm opacity-50">
-          <Globe className="h-6 w-6" />
-          <span>No tabs attached</span>
-          <span className="text-xs">Click the extension icon on a tab</span>
-        </div>
-      )}
-
-      {isConnected && targetList.length > 0 && (
-        <div className="flex flex-1 flex-col divide-y divide-white/10">
-          {/* Focus and Close are siblings of the anchor, not children of it: an <a> may not contain a
-              <button>, and the old row was a <button> containing two more — invalid either way, and it
-              was only the stopPropagation calls holding it together. */}
-          {targetList.map((target) => (
-            <div
-              key={target.id}
-              className={`group relative flex transition-colors ${
-                selectedId === target.id ? 'bg-accent' : 'hover:bg-accent/50'
-              }`}
-            >
-              <Link
-                to={browserTabPath(target.id)}
-                className="flex min-w-0 flex-1 flex-col gap-0.5 px-3 py-2.5 text-left"
-              >
-                <span className="truncate pr-14 text-sm font-medium">{target.title || 'Untitled'}</span>
-                <span className="truncate text-xs opacity-50">{target.url}</span>
-              </Link>
-              <div className="absolute right-3 top-2.5 flex shrink-0 items-center gap-1 opacity-0 transition-opacity group-hover:opacity-100">
-                <button
-                  onClick={() => handleActivate(target.id)}
-                  className="rounded p-0.5 hover:bg-black/10 cursor-pointer"
-                  title="Focus tab"
-                >
-                  <Eye className="h-3.5 w-3.5" />
-                </button>
-                <button
-                  onClick={() => handleClose(target.id)}
-                  className="rounded p-0.5 hover:bg-black/10 cursor-pointer"
-                  title="Close tab"
-                >
-                  <X className="h-3.5 w-3.5" />
-                </button>
-              </div>
-            </div>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-};

src/apps/officer-web/Screens/Dashboard/Browser/TabPreview.tsx

@@ -1,174 +0,0 @@
-import { useState, useCallback } from 'react';
-import { Link } from 'react-router';
-import { useQuery } from '@tanstack/react-query';
-import { Globe, RefreshCw, Send, Terminal, Loader2 } from 'lucide-react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import { useClient } from 'hooks/useClient';
-import { useBrowserTargets, useSelectedTabId } from './shared';
-
-export const TabPreview = () => {
-  const client = useClient();
-  // Reads the URL itself rather than being told by the list.
-  const selectedId = useSelectedTabId();
-  const { data: targets } = useBrowserTargets(!!selectedId);
-  // A target id dies with the browser session, so a link or a reload can name a tab that is no longer
-  // attached. Screenshotting it would 404 every ten seconds; better to say so once.
-  const isKnownTab = !!selectedId && !!targets?.some((t) => t.id === selectedId);
-  const [navUrl, setNavUrl] = useState('');
-  const [evalExpr, setEvalExpr] = useState('');
-  const [evalResult, setEvalResult] = useState<string | null>(null);
-  const [isNavigating, setIsNavigating] = useState(false);
-  const [isEvaluating, setIsEvaluating] = useState(false);
-
-  const {
-    data: screenshot,
-    isLoading,
-    refetch,
-    isFetching,
-  } = useQuery({
-    queryKey: ['browser-screenshot', selectedId],
-    queryFn: () => client.get<{ data: string; format: string }>(`/browser/targets/${selectedId}/screenshot`),
-    enabled: isKnownTab,
-    refetchInterval: 10000,
-  });
-
-  const handleNavigate = useCallback(async () => {
-    if (!selectedId || !navUrl.trim()) return;
-    setIsNavigating(true);
-    try {
-      await client.post(`/browser/targets/${selectedId}/navigate`, { url: navUrl.trim() });
-      setTimeout(() => void refetch(), 1000);
-    } catch {
-      toast.error('Navigation failed');
-    } finally {
-      setIsNavigating(false);
-    }
-  }, [client, selectedId, navUrl, refetch]);
-
-  const handleEvaluate = useCallback(async () => {
-    if (!selectedId || !evalExpr.trim()) return;
-    setIsEvaluating(true);
-    try {
-      const res = await client.post<{ result: unknown }>(`/browser/targets/${selectedId}/evaluate`, {
-        expression: evalExpr.trim(),
-      });
-      setEvalResult(JSON.stringify(res.result, null, 2));
-    } catch (err) {
-      setEvalResult(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    } finally {
-      setIsEvaluating(false);
-    }
-  }, [client, selectedId, evalExpr]);
-
-  if (!selectedId) {
-    return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 text-sm opacity-50">
-        <Globe className="h-8 w-8" />
-        <span>Select a tab to preview</span>
-      </div>
-    );
-  }
-
-  // Waiting on the list is not the same as knowing the tab is gone, so only say so once it has arrived.
-  if (targets && !isKnownTab) {
-    return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 text-sm opacity-50">
-        <Globe className="h-8 w-8" />
-        <span>That tab is no longer attached</span>
-        <Link to="/browser" className="text-xs underline">
-          Back to the tab list
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex h-full flex-col overflow-hidden">
-      {/* URL bar */}
-      <div className="flex items-center gap-2 border-b px-3 py-2">
-        <Button
-          variant="ghost"
-          size="sm"
-          className="h-7 w-7 p-0 shrink-0"
-          onClick={() => void refetch()}
-          disabled={isFetching}
-        >
-          {isFetching ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <RefreshCw className="h-3.5 w-3.5" />}
-        </Button>
-        <form
-          className="flex flex-1 items-center gap-2"
-          onSubmit={(ev) => {
-            ev.preventDefault();
-            void handleNavigate();
-          }}
-        >
-          <input
-            type="text"
-            value={navUrl}
-            onChange={(ev) => setNavUrl(ev.target.value)}
-            placeholder="Navigate to URL..."
-            className="flex-1 rounded-md border bg-transparent px-2 py-1 text-sm outline-none focus:border-cyan-500"
-          />
-          <Button
-            variant="ghost"
-            size="sm"
-            className="h-7 w-7 p-0 shrink-0"
-            type="submit"
-            disabled={isNavigating || !navUrl.trim()}
-          >
-            <Send className="h-3.5 w-3.5" />
-          </Button>
-        </form>
-      </div>
-
-      {/* Screenshot */}
-      <div className="flex-1 overflow-auto p-2">
-        {isLoading && !screenshot && (
-          <div className="flex h-full items-center justify-center">
-            <Loader2 className="h-6 w-6 animate-spin opacity-50" />
-          </div>
-        )}
-        {screenshot && (
-          <img
-            src={`data:image/${screenshot.format};base64,${screenshot.data}`}
-            alt="Tab screenshot"
-            className="w-full rounded-md border"
-          />
-        )}
-      </div>
-
-      {/* JS Console */}
-      <div className="border-t">
-        <form
-          className="flex items-center gap-2 px-3 py-2"
-          onSubmit={(ev) => {
-            ev.preventDefault();
-            void handleEvaluate();
-          }}
-        >
-          <Terminal className="h-3.5 w-3.5 shrink-0 opacity-50" />
-          <input
-            type="text"
-            value={evalExpr}
-            onChange={(ev) => setEvalExpr(ev.target.value)}
-            placeholder="Evaluate JavaScript..."
-            className="flex-1 bg-transparent text-sm outline-none font-mono"
-          />
-          <Button
-            variant="ghost"
-            size="sm"
-            className="h-6 px-2 shrink-0"
-            type="submit"
-            disabled={isEvaluating || !evalExpr.trim()}
-          >
-            {isEvaluating ? <Loader2 className="h-3 w-3 animate-spin" /> : 'Run'}
-          </Button>
-        </form>
-        {evalResult !== null && (
-          <pre className="max-h-32 overflow-auto border-t px-3 py-2 text-xs font-mono opacity-70">{evalResult}</pre>
-        )}
-      </div>
-    </div>
-  );
-};

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

@@ -1,22 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-
-export const defaultLayout: LayoutNode = {
-  type: 'group',
-  id: 'browser-root',
-  direction: 'horizontal',
-  children: [
-    { node: { type: 'panel', id: 'browser-tabs', appType: null }, size: 25 },
-    {
-      node: {
-        type: 'group',
-        id: 'browser-right',
-        direction: 'vertical',
-        children: [
-          { node: { type: 'panel', id: 'browser-preview', appType: null }, size: 60 },
-          { node: { type: 'panel', id: 'browser-chat', appType: 'officerdev/chat' }, size: 40 },
-        ],
-      },
-      size: 75,
-    },
-  ],
-};

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

@@ -1 +0,0 @@
-export { BrowserScreen } from './BrowserScreen';

src/apps/officer-web/Screens/Dashboard/Browser/shared.ts

@@ -1,34 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-import { useParams } from 'react-router';
-import { useClient } from 'hooks/useClient';
-
-// Which attached tab is being previewed is `/browser/:tabId`. It used to be a `BROWSER_SELECTED_TAB`
-// global read by three components, which meant the address bar said `/browser` no matter what you were
-// looking at, and a tab row was a `<button>` with the id in its onClick closure.
-
-export type BrowserTarget = {
-  id: string;
-  sessionId: string;
-  type: string;
-  title: string;
-  url: string;
-};
-
-export const browserTabPath = (id: string) => `/browser/${encodeURIComponent(id)}`;
-
-/** The previewed tab, or null on the bare `/browser` route — the list with nothing open. */
-export const useSelectedTabId = (): string | null => useParams<{ tabId?: string }>().tabId ?? null;
-
-// Both panels want this list and React Query serves both observers from one key, so the preview being
-// able to tell "no tab open" from "that tab is gone" costs no extra request. It needs to: a CDP target
-// id dies with the browser session, and now that the id is in the URL a reload can carry a stale one in
-// — which the old global, living in memory, could never do.
-export const useBrowserTargets = (enabled: boolean) => {
-  const client = useClient();
-  return useQuery({
-    queryKey: ['browser-targets'],
-    queryFn: () => client.get<BrowserTarget[]>('/browser/targets'),
-    refetchInterval: 3000,
-    enabled,
-  });
-};

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: {
-    { node: { type: 'panel', id: 'command-hq-detail', appType: 'command-hq-detail' }, size: 50 },
+        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/Desktop/DesktopScreen.tsx

@@ -1,18 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-import { WorkspaceView } from 'officerdev';
-import { useDashboardState } from 'state/useDashboardState';
-import { defaultLayout } from './defaultLayout';
-
-export const DesktopScreen = () => {
-  const workspace = useDashboardState<LayoutNode>('screens/desktop', defaultLayout);
-
-  return (
-    <div className="h-full w-full">
-      <WorkspaceView
-        workspace={workspace}
-        locked
-        appTypes={{ allowed: ['officerdev/desktop'], fallback: 'officerdev/desktop' }}
-      />
-    </div>
-  );
-};

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

@@ -1,7 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-
-export const defaultLayout: LayoutNode = {
-  type: 'panel',
-  id: 'desktop-screen',
-  appType: 'officerdev/desktop',
-};

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

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

src/apps/officer-web/Screens/Dashboard/Jobs/JobDetail.tsx

@@ -142,7 +142,7 @@ const StatusIcon = ({ status, className }: { status: string; className?: string
   switch (status) {
     case 'completed':
     case 'complete':
-      return <CheckCircle2 className={`${base} text-green-500`} />;
+      return <CheckCircle2 className={`${base} text-success`} />;
     case 'failed':
     case 'error':
       return <AlertCircle className={`${base} text-red-500`} />;

src/apps/officer-web/Screens/Dashboard/Jobs/JobsPage.tsx

@@ -44,7 +44,7 @@ const formatDate = (iso: string) =>
 const StatusIcon = ({ status }: { status: JobSummary['status'] }) => {
   switch (status) {
     case 'completed':
-      return <CheckCircle2 className="h-4 w-4 text-green-500 shrink-0" />;
+      return <CheckCircle2 className="h-4 w-4 text-success shrink-0" />;
     case 'failed':
       return <AlertCircle className="h-4 w-4 text-red-500 shrink-0" />;
     case 'running':

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

@@ -7,6 +7,8 @@ import { ScreenErrorFallback } from './ScreenErrorFallback';
 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';
@@ -47,6 +49,12 @@ export function DashboardLayout({ children }: DashboardLayoutProps) {
   return (
     <div className="relative flex h-dvh flex-col overflow-hidden outline-none inset-0">
       <Header dockItems={visibleItems} hidden={panelFullscreen} />
+      {/* 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/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');
 
@@ -81,7 +83,10 @@ export function Header({ dockItems, hidden }: HeaderProps) {
               role="img"
               aria-label="Officer"
               className="h-8 md:h-12 w-24 md:w-36 bg-contain bg-left bg-no-repeat"
-              style={{ backgroundImage: logo ? `url(${logo})` : 'none', transform: 'skew(-15deg, -2deg)' }}
+              /* No skew. The wordmark is drawn, kerned pair by pair, and shipped as the finished mark —
+                 shearing it in CSS was how the OLD logo got its slant, and doing it to this one distorts
+                 letterforms that were adjusted by hand. See landing/assets/brand/WORDMARK.md. */
+              style={{ backgroundImage: logo ? `url(${logo})` : 'none' }}
             />
           </Link>
         </div>
@@ -97,9 +102,15 @@ export function Header({ dockItems, hidden }: HeaderProps) {
           */}
           {/* Bug Report — hidden */}
           {/* <BugReportButton /> */}
+          <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 />
-          <ThemeSwitcher />
+            </>
+          )}
           <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.
+    One ordering, used by both lists.
-  const families = themes.reduce<Record<string, Theme[]>>((acc, t) => {
+
-    (acc[t.family] ??= []).push(t);
+    ROTATED to the theme you are wearing rather than sorted: with 200+ installed, the list's only structure
-    return acc;
+    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`}
+            title={`Theme: ${theme.name}  ·  ctrl+shift+←/→ cycle · ctrl+shift+space browse · ctrl+shift+f ${
-            aria-label="Theme"
+              isFavorite(themeId) ? 'unstar' : 'star'
-            className="flex h-8 w-8 items-center justify-center rounded-full transition-transform hover:scale-110 cursor-pointer"
+            }`}
+            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">
+          The CONTENT does not scroll — the list inside it does.
-            ctrl+shift+←/→ · ctrl+shift+space
+
+          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>
-          <DropdownMenuSeparator />
+            <button
-          {Object.entries(families).map(([family, entries]) => (
+              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">
+                    <DropdownMenuItem key={t.id} onClick={() => setTheme(t.id)} className="cursor-pointer pr-1">
-                  <Check className={`mr-2 h-4 w-4 ${t.id === themeId ? 'opacity-100' : 'opacity-0'}`} />
+                      <Check className={`mr-2 h-4 w-4 shrink-0 ${t.id === themeId ? 'opacity-100' : 'opacity-0'}`} />
-                  {t.name}
+                      <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">
+              {/* The SAME `ordered` list as the dropdown — rotated to what you are wearing, favourites
-                {themes.map((t) => {
+                  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}
+                        <span className="min-w-0 flex-1 truncate">{t.name}</span>
-                        {t.id === themeId && <span className="ml-2 align-middle text-xs opacity-70">active</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/Rescan/RescanButton.tsx

@@ -33,7 +33,28 @@ export function RescanButton() {
       await Promise.all(ITEM_QUERY_KEYS.map((key) => qc.invalidateQueries({ queryKey: [key], refetchType: 'all' })));
       const c = res.counts ?? {};
       toast.success(
-        `Rescanned items — ${c.tasks ?? 0} tasks, ${c.agents ?? 0} agents, ${c.tools ?? 0} tools, ${c.skills ?? 0} skills, ${c.processes ?? 0} processes`,
+        `Rescanned items — ${c.tasks ?? 0} tasks, ${c.agents ?? 0} agents, ${c.tools ?? 0} tools, ${c.skills ?? 0} skills, ${c.processes ?? 0} processes, ${c.affordances ?? 0} affordances`,
+        {
+          // Two things said here rather than left to be discovered.
+          //
+          // A rescan cannot reach a chat that is already open — its system prompt was assembled when it
+          // started. And a SKILL.md with no `description` is COUNTED as a skill but never offered to an
+          // agent, because the loader skips it: a line that does not say when to reach for something
+          // costs context in every conversation and earns nothing. So a skill can be present, listed and
+          // editable while being invisible to every agent, and the only symptom is two numbers
+          // disagreeing where nobody is comparing them.
+          description:
+            [
+              c.affordances || c.skillsOffered
+                ? 'Applies to new chats — an open one keeps what it started with.'
+                : null,
+              typeof c.skills === 'number' && typeof c.skillsOffered === 'number' && c.skillsOffered < c.skills
+                ? `${c.skills - c.skillsOffered} skill(s) have no description, so no agent is offered them.`
+                : null,
+            ]
+              .filter(Boolean)
+              .join(' ') || undefined,
+        },
       );
     } catch {
       toast.error('Failed to rescan items');

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

@@ -0,0 +1,313 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { Search } from 'lucide-react';
+import { rank } from './match';
+import { useSpotlightItems, type SpotlightItem } from './useSpotlightItems';
+
+// Spotlight: type a few letters, go somewhere.
+//
+// The dock is full and cannot grow, which is what this is for — once navigation lives here, the dock is
+// free to be a short list of what you actually use rather than a complete one.
+//
+// ── Keyboard first, and the trigger ──
+//
+// `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:
+//
+//   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.
+//
+// ── 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.
+
+  Eight was fine on the machine it was written on, which has few plugins. On a populated server the dock
+  carries fourteen plugin tiles and the core items alone fill all eight slots — so with an empty query the
+  list stopped at Browser and every plugin was unreachable unless you already knew its name well enough to
+  type it. A launcher you can only use for things you can already name is not doing the job.
+
+  The container has scrolled since it was written (`max-h-[52vh] overflow-y-auto`), so there was never a
+  layout reason for the limit, and the truncation was silent — nothing said "and 20 more", which is how a
+  cap becomes indistinguishable from a missing feature.
+*/
+
+/** 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}</>;
+  const set = new Set(hits);
+  return (
+    <>
+      {label.split('').map((char, i) =>
+        set.has(i) ? (
+          <span key={i} className="text-duck-teal">
+            {char}
+          </span>
+        ) : (
+          <span key={i}>{char}</span>
+        ),
+      )}
+    </>
+  );
+};
+
+const Row = ({
+  item,
+  hits,
+  active,
+  onPick,
+}: {
+  item: SpotlightItem;
+  hits: number[];
+  active: boolean;
+  onPick: () => void;
+}) => {
+  const Icon = item.icon;
+  // Keyboard navigation has to survive a list taller than the box. `block: 'nearest'` scrolls only when the
+  // row is actually out of sight, so arrowing through the visible middle of the list does not jump it.
+  const ref = useRef<HTMLButtonElement | null>(null);
+  useEffect(() => {
+    if (active) ref.current?.scrollIntoView({ block: 'nearest' });
+  }, [active]);
+  return (
+    <button
+      ref={ref}
+      type="button"
+      // `onMouseDown`, not `onClick`: the input holds focus and a click would blur it first, closing the
+      // overlay on the blur handler before the navigation ever ran.
+      onMouseDown={(ev) => {
+        ev.preventDefault();
+        onPick();
+      }}
+      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'
+      }`}
+    >
+      {/*
+        The dock's tile, at row size. Same two cases and the same rule for choosing between them, because
+        these are the SAME things and a second visual language for them is what made this list read as
+        somebody else's menu:
+
+          badge  a filled square of the item's colour with a white glyph — a white glyph on nothing is
+                 invisible, which is why the fill is not decoration
+          bare   no background, artwork fills the box — a logo framed in an arbitrary swatch reads as a
+                 mistake, and every plugin shipping its own art is this case
+
+        The tinted `${color}22` square this used for everything was a third style belonging to neither, and
+        it put a coloured pane behind Calendar, Contacts and every plugin logo.
+      */}
+      <span
+        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.
+          color: item.color ? '#fff' : undefined,
+        }}
+      >
+        {item.image ? (
+          <img
+            src={item.image}
+            alt=""
+            className={item.tile === 'bare' ? 'h-full w-full object-contain' : 'h-5 w-5 object-contain'}
+          />
+        ) : Icon ? (
+          <Icon className={`h-[18px] w-[18px] ${item.color ? '' : '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-[15px] leading-snug text-foreground">
+          <Highlighted label={item.label} hits={hits} />
+        </span>
+        {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-[11px] text-muted-foreground/60">{item.to}</span>
+    </button>
+  );
+};
+
+export const Spotlight = () => {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [active, setActive] = useState(0);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const navigate = useNavigate();
+  const items = useSpotlightItems();
+
+  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('');
+    setActive(0);
+  }, []);
+
+  const pick = useCallback(
+    (item: SpotlightItem | undefined) => {
+      if (!item) return;
+      close();
+      navigate(item.to);
+    },
+    [close, navigate],
+  );
+
+  // The trigger. Bound to the window rather than to a container, because it has to work while focus is
+  // anywhere — including inside a panel that has its own key handling.
+  useEffect(() => {
+    const onKey = (ev: KeyboardEvent) => {
+      // `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 (!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, pick]);
+
+  useEffect(() => {
+    if (open) inputRef.current?.focus();
+  }, [open]);
+
+  // Reset the cursor whenever the result set changes, so it never points past the end.
+  useEffect(() => setActive(0), [query]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center bg-black/40 pt-[12vh] backdrop-blur-sm"
+      onMouseDown={close}
+    >
+      <div
+        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-5 w-5 shrink-0 text-muted-foreground" />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(ev) => setQuery(ev.target.value)}
+            placeholder="Go to…"
+            className="w-full bg-transparent py-4 text-base text-foreground outline-none placeholder:text-muted-foreground"
+          />
+        </div>
+
+        <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>
+          ) : (
+            results.map((result, i) => (
+              <Row
+                key={result.item.id}
+                item={result.item}
+                hits={result.hits}
+                active={i === active}
+                onPick={() => pick(result.item)}
+              />
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/match.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test';
+import { rank } from './match';
+import type { SpotlightItem } from './useSpotlightItems';
+
+// The behaviours a launcher is judged on, which are all about ORDER rather than about matching. Anyone
+// can return the right set; returning it with the right thing first is the whole product.
+
+const item = (label: string, to: string, hint?: string): SpotlightItem => ({ id: to, label, to, hint });
+
+const ITEMS: SpotlightItem[] = [
+  item('Home', '/'),
+  item('Files', '/files'),
+  item('Chat', '/chat'),
+  item('Command HQ', '/command-hq'),
+  item('Editor', '/code-editor'),
+  item('Profile', '/settings/profile', 'avatar, name, email'),
+  item('API keys', '/settings/profile/api-keys', 'per-app keys'),
+  item('App store', '/app-store'),
+  item('Dashboards', '/dashboards'),
+];
+
+const top = (query: string, n = 1) =>
+  rank(ITEMS, query)
+    .slice(0, n)
+    .map((s) => s.item.label);
+
+describe('spotlight ranking', () => {
+  test('an exact label wins', () => {
+    expect(top('chat')).toEqual(['Chat']);
+  });
+
+  test('a prefix beats a scattered match — "fi" is Files, not Profile', () => {
+    expect(top('fi')).toEqual(['Files']);
+  });
+
+  test('initials find a two-word label — "chq" is Command HQ', () => {
+    expect(top('chq')).toEqual(['Command HQ']);
+  });
+
+  test('a subsequence works, so you can type the shape of a word', () => {
+    expect(top('apik')).toEqual(['API keys']);
+  });
+
+  test('a hint matches, but never outranks a label', () => {
+    // "keys" is API keys' own label AND its hint. It must not be beaten by anything mentioning keys.
+    expect(top('keys')).toEqual(['API keys']);
+  });
+
+  test('a path fragment finds the item without outranking labels', () => {
+    expect(rank(ITEMS, 'settings').map((s) => s.item.label)).toContain('Profile');
+    // "app" is a prefix of "App store" and appears in API keys' hint ("per-app keys"). Label wins.
+    expect(top('app')).toEqual(['App store']);
+  });
+
+  test('nothing matches means nothing returned, not everything', () => {
+    expect(rank(ITEMS, 'zzzzz')).toHaveLength(0);
+  });
+
+  test('an empty query keeps the given order rather than sorting it', () => {
+    expect(rank(ITEMS, '').map((s) => s.item.label)).toEqual(ITEMS.map((i) => i.label));
+  });
+
+  test('shorter labels break ties — "Chat" over "Chat history"', () => {
+    const withLonger = [...ITEMS, item('Chat history', '/chat-history')];
+    expect(rank(withLonger, 'chat')[0]!.item.label).toBe('Chat');
+  });
+});

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/match.ts

@@ -0,0 +1,93 @@
+import type { SpotlightItem } from './useSpotlightItems';
+
+// Ranking, kept apart from React so it can be tested with strings.
+//
+// Subsequence matching, not substring: "cmdhq" should find "Command HQ" and "apik" should find
+// "API keys". Anyone who has used a launcher expects to type the shape of a word rather than a prefix
+// of it, and a substring match makes them type more to get less.
+
+export type Scored = { item: SpotlightItem; score: number; hits: number[] };
+
+/**
+ * Where each character of `query` lands in `text`, or null if it does not fit.
+ *
+ * Greedy left-to-right, which is what makes it cheap and predictable. It can miss a better alignment —
+ * "ao" against "app store" takes the first `o` in the first word rather than the one in "store" — and
+ * that costs a slightly worse score, never a wrong answer, because the item still matches.
+ */
+function subsequence(text: string, query: string): number[] | null {
+  const hits: number[] = [];
+  let at = 0;
+  for (const char of query) {
+    const found = text.indexOf(char, at);
+    if (found === -1) return null;
+    hits.push(found);
+    at = found + 1;
+  }
+  return hits;
+}
+
+/** Start of the string, or the character after a space, dash or slash. */
+const isBoundary = (text: string, i: number): boolean => i === 0 || /[\s\-/]/.test(text[i - 1]!);
+
+/**
+ * Higher is better. The weights encode what a person means by "the right result":
+ *
+ * - **an exact label** is what they typed, so nothing beats it
+ * - **a prefix** beats a scattered match — typing "fi" should rank Files above Profile
+ * - **word boundaries** are why "chq" finds Command HQ at all, and should rank it above an item where
+ *   those letters happen to fall mid-word
+ * - **adjacency** rewards a run of letters, which is what a substring match would have found
+ * - **shortness** breaks ties toward the more specific label: "Chat" over "Chat history"
+ *
+ * The label is worth roughly three times the hint, so typing a word that IS a label beats an item that
+ * merely mentions it in passing.
+ */
+function scoreOne(text: string, query: string, weight: number): { score: number; hits: number[] } | null {
+  const hits = subsequence(text, query);
+  if (!hits) return null;
+
+  let score = 0;
+  if (text === query) score += 1000;
+  else if (text.startsWith(query)) score += 400;
+
+  for (let i = 0; i < hits.length; i++) {
+    const at = hits[i]!;
+    if (isBoundary(text, at)) score += 30;
+    if (i > 0 && at === hits[i - 1]! + 1) score += 15;
+  }
+
+  // Shorter labels win ties. Capped so a very long one is not driven negative.
+  score += Math.max(0, 40 - text.length);
+  return { score: score * weight, hits };
+}
+
+/**
+ * Rank items against a query.
+ *
+ * An empty query returns everything in its given order — the index is already in a sensible one (dock
+ * first, settings after), and imposing an alphabetical sort on an empty box would move Home away from
+ * the top for no reason.
+ */
+export function rank(items: SpotlightItem[], query: string): Scored[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return items.map((item) => ({ item, score: 0, hits: [] }));
+
+  const scored: Scored[] = [];
+  for (const item of items) {
+    const label = scoreOne(item.label.toLowerCase(), q, 1);
+    const hint = item.hint ? scoreOne(item.hint.toLowerCase(), q, 0.3) : null;
+    // The PATH is matched too, unweighted almost to nothing: it is how "/settings/profile" finds Profile
+    // when somebody types a URL fragment, without letting a path ever outrank a real label.
+    const path = scoreOne(item.to.toLowerCase(), q, 0.15);
+
+    const best = [label, hint, path]
+      .filter((s): s is { score: number; hits: number[] } => !!s)
+      .sort((a, b) => b.score - a.score)[0];
+    if (!best) continue;
+    // `hits` is only meaningful for the label, since that is the only string rendered with highlighting.
+    scored.push({ item, score: best.score, hits: label?.hits ?? [] });
+  }
+
+  return scored.sort((a, b) => b.score - a.score || a.item.label.length - b.item.label.length);
+}

src/apps/officer-web/Screens/Dashboard/Layout/Spotlight/useSpotlightItems.ts

@@ -0,0 +1,156 @@
+import { useMemo } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import {
+  Bot,
+  CalendarDays,
+  Cpu,
+  Globe,
+  KeyRound,
+  LayoutGrid,
+  Lock,
+  Mail,
+  Mic,
+  ScanText,
+  ShieldCheck,
+  Sparkles,
+  User,
+  Users,
+  Volume2,
+  Wrench,
+} from 'lucide-react';
+import { usePermissions } from 'hooks/usePermissions';
+import { CORE_DOCK_ITEMS, dockItemsFromPlugins } from '../Dock';
+
+// What Spotlight can take you to.
+//
+// ── It indexes the DOCK, rather than a list of its own ──
+//
+// The dock is already the composed, permission-filtered answer to "what can this account open here":
+// the shell's own screens, plus whatever installed plugins contribute, minus anything `canVisit` refuses.
+// Building a second list would mean two answers to one question, and the second would be wrong the day
+// somebody installs a plugin — which is the whole failure the dock's own comment warns about, arrived at
+// from a third direction.
+//
+// So a new plugin appears in Spotlight for the same reason it appears in the dock: because it is
+// installed. Nothing here is edited.
+//
+// Settings sections are added because they are the things people hunt for and the dock deliberately does
+// not carry. They are static: a settings screen is shell, not a plugin.
+
+export type SpotlightItem = {
+  /** Stable across renders — used as the React key and for the recency store. */
+  id: string;
+  label: string;
+  /** Where it goes. Matched against `canVisit` for anything not already filtered. */
+  to: string;
+  /** Shown small beside the label, so two "Profile"s are distinguishable. */
+  hint?: string;
+  icon?: LucideIcon;
+  /** Plugin artwork, when the tile has some. */
+  image?: string;
+  color?: string;
+  /**
+   * Copied from the dock tile, and it has to be.
+   *
+   * `bare` means the artwork brings its own frame — calendar, contacts, and every plugin shipping a logo.
+   * Dropping it here painted a coloured swatch behind those logos, which the dock's own comment calls out
+   * as reading like a mistake. It was dropped, so Spotlight looked like a different app's list of the same
+   * things.
+   */
+  tile?: 'badge' | 'bare';
+};
+
+/**
+ * The settings sections, which the dock does not carry.
+ *
+ * Hand-listed rather than derived, and that is a real cost: a section added to `IntegrationsSettings`
+ * will not appear here until someone adds it. The alternative is exporting every settings screen's
+ * section array up into the shell, which couples five screens to this one to save five lines.
+ *
+ * IT DRIFTED, and within two days. The first version listed nine rows against a settings area that has
+ * twenty-one, missed Languages and Voice entirely, pointed `/settings/users` at a route that does not
+ * exist (it is `/settings/user-management/users`), and gave four different rows the same User glyph —
+ * which is most of why the whole panel read as a generic list rather than as the app's own.
+ *
+ * So the cost is now measured rather than predicted, and deriving these from the screens is the fix if it
+ * happens a third time. Each group below names the file it is copied from, so checking is one grep.
+ *
+ * `hint` is what makes them findable — typing "keys" should reach the API keys screen, and the label alone
+ * does not say where it lives.
+ */
+const SETTINGS_ITEMS: SpotlightItem[] = [
+  // Profile — ProfileSettings/index.tsx
+  { id: 'set:profile', label: 'Profile', to: '/settings/profile', hint: 'avatar, name, email', icon: User },
+  { id: 'set:password', label: 'Change password', to: '/settings/profile/change-password', icon: Lock },
+  {
+    id: 'set:api-keys',
+    label: 'API keys',
+    to: '/settings/profile/api-keys',
+    hint: 'keys that sign in as you',
+    icon: KeyRound,
+  },
+  {
+    id: 'set:languages',
+    label: 'Languages',
+    to: '/settings/profile/languages',
+    hint: 'spoken and translation',
+    icon: Globe,
+  },
+  { id: 'set:voice', label: 'Voice', to: '/settings/profile/voice', hint: 'text-to-speech', icon: Volume2 },
+  { id: 'set:dock', label: 'Dock', to: '/settings/profile/dock', hint: 'choose and reorder', icon: LayoutGrid },
+  // AI — AISettings.tsx
+  { id: 'set:ai-my-models', label: 'My Models', to: '/settings/ai/my-models', icon: Sparkles },
+  { id: 'set:ai-channel-models', label: 'Channel Models', to: '/settings/ai/member-models', icon: Sparkles },
+  { id: 'set:ai-default-models', label: 'Default Models', to: '/settings/ai/default-models', icon: Sparkles },
+  { id: 'set:ai-harnesses', label: 'Providers', to: '/settings/ai/ai-harnesses', hint: 'harnesses', icon: Bot },
+  // System — SystemSettings.tsx
+  { id: 'set:tts', label: 'Text to Speech', to: '/settings/system/tts', icon: Volume2 },
+  { id: 'set:stt', label: 'Speech to Text', to: '/settings/system/stt', icon: Mic },
+  { id: 'set:ocr', label: 'OCR', to: '/settings/system/ocr', icon: ScanText },
+  {
+    id: 'set:maintenance',
+    label: 'Rebuild & restart',
+    to: '/settings/system/maintenance',
+    hint: 'maintenance',
+    icon: Cpu,
+  },
+  { id: 'set:smtp', label: 'SMTP', to: '/settings/system/smtp', hint: 'outgoing mail', icon: Mail },
+  // Integrations — IntegrationsSettings
+  { id: 'set:google-oauth', label: 'Google OAuth', to: '/settings/integrations/google-oauth', icon: KeyRound },
+  { id: 'set:apify', label: 'Apify', to: '/settings/integrations/apify', icon: Wrench },
+  {
+    id: 'set:dav',
+    label: 'Calendar & Contacts sync',
+    to: '/settings/integrations/dav-app-passwords',
+    hint: 'app passwords',
+    icon: CalendarDays,
+  },
+  // Users — UserManagement
+  { id: 'set:users', label: 'Accounts', to: '/settings/user-management/users', hint: 'users', icon: Users },
+  { id: 'set:permissions', label: 'Permissions', to: '/settings/user-management/permissions', icon: ShieldCheck },
+];
+
+/** Everything Spotlight can offer this account, in a stable order. */
+export function useSpotlightItems(): SpotlightItem[] {
+  const { canVisit, plugins } = usePermissions();
+
+  return useMemo(() => {
+    const fromDock: SpotlightItem[] = [...CORE_DOCK_ITEMS, ...dockItemsFromPlugins(plugins)]
+      .filter((item) => canVisit(item.to))
+      .map((item) => ({
+        id: `nav:${item.to}`,
+        label: item.label,
+        to: item.to,
+        icon: item.icon,
+        image: item.image,
+        color: item.color,
+        tile: item.tile,
+      }));
+
+    // Settings go through `canVisit` too. `usePermissions` fails OPEN by design — hiding a door is a
+    // courtesy and the 403 is the lock — so this cannot lock anyone out of their own settings.
+    const settings = SETTINGS_ITEMS.filter((item) => canVisit(item.to));
+
+    return [...fromDock, ...settings];
+  }, [canVisit, plugins]);
+}

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/Settings/IntegrationsSettings/ApifyConfig.tsx

@@ -54,7 +54,7 @@ export const ApifyConfig = () => {
       {status && (
         <div className="flex items-center gap-2 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-3">
           <div
-            className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.configured ? 'bg-green-500' : 'bg-duck-dark/20 dark:bg-foreground/20'}`}
+            className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.configured ? 'bg-success' : 'bg-duck-dark/20 dark:bg-foreground/20'}`}
           />
           <span className="text-sm text-duck-dark dark:text-foreground">
             {status.configured ? 'API token configured' : 'Not configured'}

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/BrowserRelay.tsx

@@ -1,199 +0,0 @@
-import { useState } from 'react';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { Copy, Check, Download, ExternalLink, RefreshCw, Trash2 } from 'lucide-react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import { useClient } from 'hooks/useClient';
-import { copyToClipboard } from 'helpers/clipboard';
-
-type RelayToken = {
-  token: string;
-  port: number;
-};
-
-export const BrowserRelay = () => {
-  const client = useClient();
-  const queryClient = useQueryClient();
-  const [copiedField, setCopiedField] = useState<string | null>(null);
-
-  const { data: status } = useQuery({
-    queryKey: ['browser-status'],
-    queryFn: () => client.get<{ extensionConnected: boolean; targetCount: number }>('/browser/status'),
-    refetchInterval: 5000,
-  });
-
-  const { data: tokenData } = useQuery({
-    queryKey: ['browser-relay-token'],
-    queryFn: () => client.get<RelayToken>('/browser/relay-token'),
-  });
-
-  const regenerate = useMutation({
-    mutationFn: () => client.post<RelayToken>('/browser/relay-token/regenerate'),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['browser-relay-token'] });
-      toast.success('Token regenerated — update the extension with the new token');
-    },
-    onError: () => toast.error('Failed to regenerate token'),
-  });
-
-  const revoke = useMutation({
-    mutationFn: () => client.delete('/browser/relay-token'),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['browser-relay-token'] });
-      toast.success('Token revoked');
-    },
-    onError: () => toast.error('Failed to revoke token'),
-  });
-
-  const handleCopy = async (value: string, field: string) => {
-    try {
-      await copyToClipboard(value);
-      setCopiedField(field);
-      toast.success('Copied to clipboard');
-      setTimeout(() => setCopiedField(null), 2000);
-    } catch {
-      toast.error('Failed to copy');
-    }
-  };
-
-  const isConnected = status?.extensionConnected ?? false;
-  const serverAddress = window.location.hostname;
-
-  return (
-    <div className="grid gap-4">
-      {isConnected ? (
-        <div className="flex items-center gap-3 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4">
-          <div className="h-2.5 w-2.5 rounded-full bg-green-500 shrink-0" />
-          <div className="min-w-0 flex-1">
-            <p className="text-sm font-medium text-duck-dark dark:text-foreground">Connected</p>
-            <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-              {status?.targetCount ?? 0} tab{(status?.targetCount ?? 0) !== 1 ? 's' : ''} attached
-              {' — '}
-              <a href="/browser" className="text-duck-teal underline">
-                view tabs
-              </a>
-            </p>
-          </div>
-        </div>
-      ) : (
-        <p className="text-sm text-duck-dark/60 dark:text-foreground/60">
-          Connect your Chrome browser to Officer so AI agents can view and interact with your tabs.
-        </p>
-      )}
-
-      {/* Step 1: Install */}
-      <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-        <p className="text-sm font-medium text-duck-dark dark:text-foreground">1. Install the extension</p>
-        <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-          Download and unzip the extension, then load it in Chrome:
-        </p>
-        <a
-          href="/browser-relay-extension.zip"
-          download
-          className="flex items-center justify-center gap-2 w-full h-11 rounded-md border border-duck-dark/15 dark:border-foreground/15 text-sm font-medium hover:bg-duck-dark/5 dark:hover:bg-foreground/5 transition-colors"
-        >
-          <Download className="h-4 w-4" />
-          Download Extension
-        </a>
-        <ol className="list-decimal list-inside space-y-1.5 text-xs text-duck-dark/50 dark:text-foreground/50">
-          <li>
-            Open{' '}
-            <code className="bg-duck-dark/5 dark:bg-foreground/5 px-1.5 py-0.5 rounded text-[11px]">
-              chrome://extensions
-            </code>{' '}
-            in Chrome
-          </li>
-          <li>
-            Enable <strong>Developer mode</strong> (top-right toggle)
-          </li>
-          <li>
-            Click <strong>Load unpacked</strong> and select the unzipped folder
-          </li>
-        </ol>
-      </div>
-
-      {/* Step 2: Configure */}
-      {tokenData && (
-        <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-          <p className="text-sm font-medium text-duck-dark dark:text-foreground">2. Configure the extension</p>
-          <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-            Open the extension options (right-click icon → Options) and enter these values:
-          </p>
-
-          <div className="grid gap-2">
-            <CredentialRow
-              label="Server address"
-              value={serverAddress}
-              copied={copiedField === 'host'}
-              onCopy={() => handleCopy(serverAddress, 'host')}
-            />
-            <CredentialRow
-              label="Port"
-              value={String(tokenData.port)}
-              copied={copiedField === 'port'}
-              onCopy={() => handleCopy(String(tokenData.port), 'port')}
-            />
-            <CredentialRow
-              label="Relay token"
-              value={tokenData.token}
-              masked
-              copied={copiedField === 'token'}
-              onCopy={() => handleCopy(tokenData.token, 'token')}
-            />
-          </div>
-
-          <div className="flex gap-2">
-            <Button variant="outline" size="sm" onClick={() => regenerate.mutate()} disabled={regenerate.isPending}>
-              <RefreshCw className="h-3.5 w-3.5 mr-1.5" />
-              Regenerate
-            </Button>
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => revoke.mutate()}
-              disabled={revoke.isPending}
-              className="text-red-500 hover:text-red-600"
-            >
-              <Trash2 className="h-3.5 w-3.5 mr-1.5" />
-              Revoke
-            </Button>
-          </div>
-        </div>
-      )}
-
-      {/* Step 3: Attach */}
-      <div className="rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4 grid gap-3">
-        <p className="text-sm font-medium text-duck-dark dark:text-foreground">3. Attach a tab</p>
-        <p className="text-xs text-duck-dark/50 dark:text-foreground/50">
-          Navigate to any webpage and click the Officer extension icon in the toolbar. A cyan <strong>ON</strong> badge
-          means the tab is connected. Then go to{' '}
-          <a href="/browser" className="text-duck-teal underline inline-flex items-center gap-0.5">
-            /browser <ExternalLink className="h-3 w-3" />
-          </a>{' '}
-          to view your tabs.
-        </p>
-      </div>
-    </div>
-  );
-};
-
-type CredentialRowProps = {
-  label: string;
-  value: string;
-  masked?: boolean;
-  copied: boolean;
-  onCopy: () => void;
-};
-
-const CredentialRow = ({ label, value, masked, copied, onCopy }: CredentialRowProps) => (
-  <div className="flex items-center gap-2 rounded-md bg-duck-dark/5 dark:bg-foreground/5 px-3 py-2">
-    <span className="text-xs text-duck-dark/50 dark:text-foreground/50 shrink-0 w-24">{label}</span>
-    <code className="flex-1 text-xs truncate">{masked ? `${value.slice(0, 8)}${'•'.repeat(16)}` : value}</code>
-    <button
-      onClick={onCopy}
-      className="shrink-0 p-1 rounded hover:bg-duck-dark/10 dark:hover:bg-foreground/10 cursor-pointer"
-    >
-      {copied ? <Check className="h-3.5 w-3.5 text-green-500" /> : <Copy className="h-3.5 w-3.5 opacity-50" />}
-    </button>
-  </div>
-);

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/GoogleAccount.tsx

@@ -71,7 +71,7 @@ export const GoogleAccount = () => {
       {status.connected ? (
         <>
           <div className="flex items-center gap-3 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-4">
-            <div className="h-2.5 w-2.5 rounded-full bg-green-500 shrink-0" />
+            <div className="h-2.5 w-2.5 rounded-full bg-success shrink-0" />
             <div className="min-w-0 flex-1">
               <p className="text-sm font-medium text-duck-dark dark:text-foreground">Connected</p>
               <p className="text-xs text-duck-dark/50 dark:text-foreground/50 truncate">{status.email}</p>

src/apps/officer-web/Screens/Dashboard/Settings/IntegrationsSettings/GoogleOAuthConfig.tsx

@@ -221,7 +221,7 @@ const CredentialStatus = ({ status, isVerifying }: { status: VerifyStatus; isVer
 
   return (
     <div className="flex items-center gap-2 rounded-lg border border-duck-dark/10 dark:border-foreground/10 p-3">
-      <div className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.valid ? 'bg-green-500' : 'bg-red-500'}`} />
+      <div className={`h-2.5 w-2.5 rounded-full shrink-0 ${status.valid ? 'bg-success' : 'bg-red-500'}`} />
       <span className={`text-sm ${status.valid ? 'text-duck-dark dark:text-foreground' : 'text-red-500'}`}>
         {status.valid ? 'Credentials valid' : (status.error ?? 'Invalid credentials')}
       </span>

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

@@ -8,10 +8,8 @@ import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { SettingsRoute, SettingsSidebar, SettingsContent, type SettingsSection } from '../SettingsPanel';
 import { GoogleOAuthConfig } from './GoogleOAuthConfig';
 // import { GoogleAccount } from './GoogleAccount'; // hidden — email uses IMAP app password now
-import { BrowserRelay } from './BrowserRelay';
 import { ApifyConfig } from './ApifyConfig';
 import { DavAppPasswords } from './DavAppPasswords';
-import { ApiKeys } from './ApiKeys';
 
 const BASE_PATH = '/settings/integrations';
 
@@ -51,20 +49,6 @@ const personalSections: SettingsSection[] = [
     description: 'Per-device passwords for CalDAV/CardDAV clients',
     content: <DavAppPasswords />,
   },
-  {
-    key: 'api-keys',
-    icon: KeyRound,
-    title: 'API keys',
-    description: 'Per-app keys that sign in as you, revocable one at a time',
-    content: <ApiKeys />,
-  },
-  {
-    key: 'browser-relay',
-    icon: Globe,
-    title: 'Browser Relay',
-    description: 'Connect your Chrome browser',
-    content: <BrowserRelay />,
-  },
 ];
 
 // The Enterprise/Personal tab is not a second thing to remember — it is a fact about which section is

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

@@ -2,7 +2,7 @@ import type { FormEvent } from 'react';
 import { useState } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { toast } from 'sonner';
-import { Copy, Ban, Plus, KeyRound, Loader2 } from 'lucide-react';
+import { Copy, Ban, Plus, KeyRound, Loader2, Trash2 } from 'lucide-react';
 import { useClient } from 'hooks/useClient';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -53,6 +53,7 @@ export const ApiKeys = () => {
   const queryClient = useQueryClient();
   const [name, setName] = useState('');
   const [isCreating, setIsCreating] = useState(false);
+  const [showRevoked, setShowRevoked] = useState(false);
   const [minted, setMinted] = useState<Minted | null>(null);
 
   const { data, isLoading } = useQuery<{ keys: ApiKey[] }>({
@@ -79,6 +80,15 @@ export const ApiKeys = () => {
     }
   };
 
+  const forget = async (id: number) => {
+    try {
+      await client.delete(`/api-keys/${id}/record`);
+      await refresh();
+    } catch {
+      toast.error('Could not remove it');
+    }
+  };
+
   const revoke = async (id: number) => {
     try {
       await client.delete(`/api-keys/${id}`);
@@ -89,7 +99,19 @@ export const ApiKeys = () => {
     }
   };
 
-  const keys = data?.keys ?? [];
+  const allKeys = data?.keys ?? [];
+
+  // Dead means revoked OR past its expiry — the same test the row rendering uses, lifted here so the
+  // count in the toggle and the rows it reveals can never disagree.
+  const isDead = (entry: ApiKey) =>
+    !!entry.revokedAt || (!!entry.expiresAt && new Date(entry.expiresAt).getTime() <= Date.now());
+
+  // Dead keys are HIDDEN by default rather than merely dimmed. Revoking is the normal end of a key's
+  // life, so on any account that has been used for a while the dead ones outnumber the live ones and the
+  // screen stops answering the question it exists for — which of my keys still work. The rows are kept
+  // and reachable; they are just not the first thing shown.
+  const deadKeys = allKeys.filter(isDead);
+  const keys = showRevoked ? allKeys : allKeys.filter((entry) => !isDead(entry));
 
   if (isLoading) {
     return (
@@ -102,8 +124,8 @@ export const ApiKeys = () => {
   return (
     <div className="grid gap-5">
       <p className="text-sm text-duck-dark/70 dark:text-foreground/70">
-        An API key signs in as you, without a password and without expiring. Give each app or device its own, so you can
+        An API key signs in as you, without a password and without expiring. One key works everywhere — a key is not
-        cut one off without touching the rest. Send it as{' '}
+        tied to an app. Giving each device its own is only so you can cut one off without touching the rest. Send it as{' '}
         <code className="font-mono text-xs">Authorization: Bearer …</code>.
       </p>
 
@@ -150,7 +172,9 @@ export const ApiKeys = () => {
 
       {keys.length === 0 ? (
         <div className="rounded-lg border border-dashed border-duck-dark/15 dark:border-foreground/15 p-6 text-center text-sm text-duck-dark/40 dark:text-foreground/40">
-          No keys yet.
+          {/* "No keys yet" would be false on an account whose keys are all revoked, and it is the sentence
+              that would send somebody looking for a bug in the list. */}
+          {allKeys.length === 0 ? 'No keys yet.' : 'No keys in use.'}
         </div>
       ) : (
         <div className="grid gap-2">
@@ -181,11 +205,23 @@ export const ApiKeys = () => {
                     {lastUsed ? `last used ${lastUsed}` : 'never used'}
                   </div>
                 </div>
-                {!dead && (
+                {dead ? (
+                  // Only offered once the key is already dead — the server refuses it otherwise, and the
+                  // button matching that rule is what keeps the two from drifting.
                   <Button
                     variant="ghost"
                     size="sm"
-                    onClick={() => revoke(entry.id)}
+                    onClick={() => void forget(entry.id)}
+                    title="Remove this record"
+                    className="hover:text-red-500"
+                  >
+                    <Trash2 className="h-3.5 w-3.5" />
+                  </Button>
+                ) : (
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => void revoke(entry.id)}
                     title="Revoke"
                     className="hover:text-red-500"
                   >
@@ -197,6 +233,18 @@ export const ApiKeys = () => {
           })}
         </div>
       )}
+
+      {deadKeys.length > 0 && (
+        <button
+          type="button"
+          onClick={() => setShowRevoked((v) => !v)}
+          className="mt-3 cursor-pointer text-xs text-duck-dark/40 underline underline-offset-2 transition-colors hover:text-duck-dark/70 dark:text-foreground/40 dark:hover:text-foreground/70"
+        >
+          {showRevoked
+            ? 'Hide revoked and expired'
+            : `Show ${deadKeys.length} revoked or expired key${deadKeys.length === 1 ? '' : 's'}`}
+        </button>
+      )}
     </div>
   );
 };

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

@@ -1,11 +1,12 @@
 import { useMemo } from 'react';
-import { User, Lock, Globe, LayoutGrid, Volume2 } from 'lucide-react';
+import { User, Lock, Globe, KeyRound, LayoutGrid, Volume2 } from 'lucide-react';
 import type { LayoutNode, PanelComponents } from 'officerdev';
 import { WorkspaceLayout } from 'officerdev';
 
 import { SettingsRoute, createSettingsPanelComponents, type SettingsSection } from '../SettingsPanel';
 import { UserData } from './UserData';
 import { ChangePassword } from './ChangePassword';
+import { ApiKeys } from './ApiKeys';
 import { Languages } from './Languages';
 import { DockSettings } from './DockSettings';
 import { VoicePreference } from './VoicePreference';
@@ -21,6 +22,17 @@ const sections: SettingsSection[] = [
     description: 'Update your password',
     content: <ChangePassword />,
   },
+  // Beside the password rather than under Integrations, where it was until 2026-08-21. A key is not an
+  // integration with anything — it is a second way to present the authority this account already has, and
+  // the permission registry says so: `/api-keys` is `core`, sitting with `/user` and `/dock`. Somebody
+  // looking for it went to user management and then to profile, which is where it should have been.
+  {
+    key: 'api-keys',
+    icon: KeyRound,
+    title: 'API keys',
+    description: 'Keys that sign in as you, revocable one at a time',
+    content: <ApiKeys />,
+  },
   {
     key: 'languages',
     icon: Globe,

src/apps/officer-web/Screens/Dashboard/Settings/ServerSettings/AIHarnessesSection.tsx

@@ -290,7 +290,7 @@ export const AIHarnessesSection = () => {
                 {localProviders.map((lp: LocalProviderEntry) => (
                   <div key={lp.id} className="flex items-center gap-2">
                     <span
-                      className={`inline-block h-2 w-2 shrink-0 rounded-full ${lp.id in localHealth ? (localHealth[lp.id] ? 'bg-green-500' : 'bg-red-500') : 'bg-duck-dark/20'}`}
+                      className={`inline-block h-2 w-2 shrink-0 rounded-full ${lp.id in localHealth ? (localHealth[lp.id] ? 'bg-success' : 'bg-red-500') : 'bg-duck-dark/20'}`}
                       title={lp.id in localHealth ? (localHealth[lp.id] ? 'Online' : 'Offline') : 'Checking...'}
                     />
                     <span className="text-duck-dark/70 dark:text-foreground/70 font-medium">{lp.name}</span>
@@ -439,7 +439,7 @@ export const AIHarnessesSection = () => {
                       <span
                         className={`inline-block h-2 w-2 shrink-0 rounded-full ${
                           remoteHealth[provider.providerId] === true
-                            ? 'bg-green-500'
+                            ? 'bg-success'
                             : remoteHealth[provider.providerId] === false
                               ? 'bg-red-500'
                               : 'bg-duck-dark/20'

src/apps/officer-web/Screens/Dashboard/Settings/ServerSettings/MaintenanceSection.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { Hammer, Loader2, RotateCw } from 'lucide-react';
+import { Download, Hammer, Loader2, RotateCw } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import { useClient } from 'hooks/useClient';
@@ -31,10 +31,45 @@ export function errorMessage(err: unknown, fallback: string): string {
 
 export const MaintenanceSection = () => {
   const client = useClient();
+  const [pulling, setPulling] = useState(false);
+  const [pulled, setPulled] = useState<{ from: string; to: string; commits: string[]; needs: string[] } | null>(null);
   const [rebuilding, setRebuilding] = useState(false);
   const [restarting, setRestarting] = useState(false);
   const [lastBuild, setLastBuild] = useState<string | null>(null);
 
+  /**
+   * Pull, and then say what the pull implies rather than acting on it.
+   *
+   * Deliberately does not chain into a rebuild or a restart. A pull that touched `bun.lock` means an
+   * install, which the frozen-lockfile rule exists to keep deliberate; one that touched a schema means
+   * `db:push` against a live database. Neither is a thing a button should decide, so `needs` is reported
+   * and the buttons below stay where they are.
+   */
+  const pull = async () => {
+    setPulling(true);
+    try {
+      const res = await client.post<{
+        ok: boolean;
+        updated: boolean;
+        from?: string;
+        to?: string;
+        commits: string[];
+        needs: string[];
+      }>('/server-settings/pull', {});
+      if (!res.updated) {
+        setPulled(null);
+        toast.success('Already up to date');
+        return;
+      }
+      setPulled({ from: res.from ?? '', to: res.to ?? '', commits: res.commits, needs: res.needs });
+      toast.success(`Pulled ${res.commits.length} commit${res.commits.length === 1 ? '' : 's'}`);
+    } catch (err) {
+      toast.error(errorMessage(err, 'Pull failed'));
+    } finally {
+      setPulling(false);
+    }
+  };
+
   const rebuild = async () => {
     setRebuilding(true);
     try {
@@ -90,6 +125,43 @@ export const MaintenanceSection = () => {
   return (
     <div className="flex flex-col gap-6">
       <div className="flex items-start justify-between gap-6">
+        <div className="min-w-0">
+          <div className="text-sm font-medium text-foreground">Update the platform</div>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Pulls this server&rsquo;s repository. Refuses if anything is uncommitted or the checkout has diverged — it
+            will never discard local work.
+          </p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            Changes nothing that is running. Whatever the update needs is listed here, and stays your call.
+          </p>
+          {pulled && (
+            <div className="mt-2 rounded-md border border-border bg-muted/40 p-2">
+              <p className="font-mono text-[11px] text-muted-foreground">
+                {pulled.from} → {pulled.to}
+              </p>
+              <ul className="mt-1 space-y-0.5">
+                {pulled.commits.slice(0, 5).map((line) => (
+                  <li key={line} className="truncate text-[11px] text-foreground/80">
+                    {line}
+                  </li>
+                ))}
+                {pulled.commits.length > 5 && (
+                  <li className="text-[11px] text-muted-foreground">+{pulled.commits.length - 5} more</li>
+                )}
+              </ul>
+              {pulled.needs.length > 0 && (
+                <p className="mt-1.5 text-[11px] text-warning">Needs: {pulled.needs.join(', ')}</p>
+              )}
+            </div>
+          )}
+        </div>
+        <Button disabled={pulling || rebuilding || restarting} onClick={() => void pull()} className="shrink-0">
+          {pulling ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Download className="mr-2 h-4 w-4" />}
+          {pulling ? 'Pulling…' : 'Update'}
+        </Button>
+      </div>
+
+      <div className="flex items-start justify-between gap-6 border-t border-border pt-6">
         <div className="min-w-0">
           <div className="text-sm font-medium text-foreground">Rebuild the frontend</div>
           <p className="mt-1 text-xs text-muted-foreground">
@@ -98,7 +170,7 @@ export const MaintenanceSection = () => {
           </p>
           {lastBuild && <p className="mt-1 text-xs text-muted-foreground/70">Last build: {lastBuild}</p>}
         </div>
-        <Button disabled={rebuilding || restarting} onClick={() => void rebuild()} className="shrink-0">
+        <Button disabled={pulling || rebuilding || restarting} onClick={() => void rebuild()} className="shrink-0">
           {rebuilding ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Hammer className="mr-2 h-4 w-4" />}
           {rebuilding ? 'Building…' : 'Rebuild'}
         </Button>
@@ -118,7 +190,7 @@ export const MaintenanceSection = () => {
         </div>
         <Button
           variant="destructive"
-          disabled={rebuilding || restarting}
+          disabled={pulling || rebuilding || restarting}
           onClick={() => void restart()}
           className="shrink-0"
         >

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

@@ -20,7 +20,6 @@ export * from './CodeEditor';
 export * from './ChatHistory';
 export * from './Dashboards';
 export * from './Terminal';
-export * from './Browser';
-export * from './Desktop';
 export * from './Jobs';
 export * from './QrTransfer';
+export * from './Minesweeper';

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/apps/officer-web/styles/prose.css

@@ -169,8 +169,11 @@
 .code-surface pre {
   margin: 0;
   padding: 0.75em 1em;
-  /* Room for the two copy buttons, so a long first line scrolls up to them rather than under them. */
+  /* Room for the copy controls, which sit absolutely at the bottom-right of the block. Horizontal so a
+     long line scrolls past them rather than under them; vertical so the LAST line — the one they now
+     overlap — keeps its own space. */
   padding-right: 5.5em;
+  padding-bottom: 2em;
   border-radius: 0.5rem;
   background: #0d1117;
   /* Scroll, never wrap: wrapping folds `ls -la`, `git log --oneline` and any other columnar output into
@@ -186,6 +189,12 @@
   padding-right: 10em;
 }
 
+/* The positioning context for those controls. Without it they escape to the nearest positioned ancestor,
+   which is how a copy button ends up floating below the block it belongs to. */
+.code-surface {
+  position: relative;
+}
+
 .code-surface pre code {
   padding: 0;
   border-radius: 0;