publishing a plugin is pushing a tag

Three mechanisms where there should be one. The catalogue was filled by hand, and each host separately polled twenty-one repositories with git to work out whether a release existed — a second source of truth for a fact one place already knew. Shipping photos 2026.09.03.02 correctly and watching alpha not notice for ten minutes is what started this. The timer. scripts/marketplace-cron.sh, every minute, on the machine that publishes. Safe now only because the previous commit made the sync read tags instead of working trees; over the old one this would have published somebody's afternoon on a schedule. Nothing is written unless the release commit differs from the one already published, so a tick with nothing to do is one query, one fetch per repo and no writes — about 2.7s. One timestamped summary line per tick regardless, because a fresh timestamp is the only thing that separates "nothing to publish" from "the timer died"; a named line only for a plugin that moved. The badge. `updateable` now compares the tag at HEAD with the tag the catalogue says is newest — difference, not ordering, since parsing 2026.08.27.01 works right up until somebody tags v2 and then fails silently. refreshRemote() and its two-minute window are gone with the polling they existed to paper over. The git rule stays as the fallback for a plugin the store cannot speak for: an unregistered checkout, or an unreachable store. That case now reads whatever refs the last pull left, which is the accepted cost of not making every machine poll every repository forever. fetchCatalogue()'s cache went from five minutes to one. It only drew tiles before; now the wait for a release to appear would have been the sync's minute plus its five. Also: the Update button names its destination whenever a release is known, not only on `new-release`. An untagged checkout reports `untagged` and used to lose the tag with it, so the button said "Update" and the owner had to guess where it landed — the marketplace knows, even for a checkout that has never fetched it. Verified: forced a stale row, the timer republished it inside 60s and logged one line. Badge decisions checked against the live catalogue for seven plugins, including the two shapes that matter — at a tag the store agrees with, and untagged with a release known only to the store. 9 release tests pass, 100% of release.ts covered, four of them new and all against real repositories. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
the marketplace publishes releases, not working trees
2026-09-03 13:13:43 +01:00 · 2026-09-03 13:05:50 +01:00 · 2026-09-03 12:47:09 +01:00 · 2026-09-03 12:37:14 +01:00 · 2026-09-03 12:31:30 +01:00 · 2026-09-01 07:17:33 +01:00
49 changed files with 2201 additions and 263 deletions
@@ -0,0 +1,76 @@
+# 2026.08.29.04 — deploy report
+
+**7 of 7 targets succeeded. `officer-dev` skipped by design — it is the host the rollout ran on.**
+
+Every host went `03fbb118` → `e9b71522` except `fofos`, which started further back at `2738f799` and
+travelled further. All eight rows below end on `e9b71522`, the commit `deploy/2026.08.29.04` points at.
+
+Nothing failed. Nothing was left half-applied. No host was unreachable — `macbookpro` was awake.
+
+## What ran, per host
+
+The same four steps everywhere: tracked-only dirty check, `git fetch origin --tags`,
+`git merge --ff-only deploy/2026.08.29.04`, `bun run plugins:update`, then `pm2 restart officer` and
+nothing else. The plan asked for no `bun install` and no `bun db:push`, and neither was run.
+
+| Host | HEAD before | HEAD after | plugins | `officer` restarts | health | `ls` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `officer-dev` | — | — | **SKIPPED — the rollout ran here** | — | — | — |
+| `alpha` | `03fbb118` | `e9b71522` | 15/15 | 5 → 6 | 401 | 200, 77 entries |
+| `fofos` | `2738f799` | `e9b71522` | 5/5 | 93 → 94 | 401 | 200, 39 entries |
+| `macbookpro` | `03fbb118` | `e9b71522` | none installed | 5 → 6 | 401 (9010) | 200, 62 entries |
+| `macbruno` | `03fbb118` | `e9b71522` | 1/1 | 8 → 9 | 401 | 200, 41 entries |
+| `production-pertento-bridge` | `03fbb118` | `e9b71522` | 1/1 | 6 → 7 | 401 (9010) | 200, 53 entries |
+| `edge-pertento-bridge` | `03fbb118` | `e9b71522` | 2/2 | 7 → 8 | 401 | 200, 29 entries |
+| `deadpool-rezio-bridge` | `03fbb118` | `e9b71522` | 2/2 | 24 → 25 | 401 | 200, 49 entries |
+
+`plugins:update` exited 0 on every host that has plugins. `401` on `/api/health` is healthy — the plan
+says so and every host gave the same answer.
+
+## The file browser check
+
+This release rewrote the file browser and the viewer, so the plan asked for one signed
+`/api/file-browser/ls` call per host. **Seven hosts, seven `200`s**, each with a plausible entry count
+for that machine. The counts differ because the homes differ; none was zero and none was a 500.
+
+Signed as user id 1 with that host's own owner, which is not the same address everywhere —
+`conceiba@gmail.com` on `macbruno` and `brunorezio@gmail.com` on `deadpool-rezio-bridge`. Read from each
+host's own `users` table rather than assumed.
+
+## Schema
+
+**No schema verification was performed, because this release changes no schema.** The plan states that
+and shows the two `git diff --name-only` commands behind the claim. No `bun db:push` step exists in it
+and none was improvised.
+
+The plugin sidecars did apply their own schemas during `plugins:update` — `music` on `alpha`,
+`fofos-admin` and `proxy-manager` on `fofos`, `proxy-manager` on `macbruno`, `offscale` on
+`edge-pertento-bridge`, `email` on `deadpool-rezio-bridge`. Each printed its own
+`schema: applied … (N table(s) verified)`. That belongs to the plugin updater, not to this release.
+
+## More restarted than `officer`
+
+`plugins:update` restarts a sidecar whenever it moves a plugin, before the plan's own restart. Naming
+only `officer` would understate what moved, so: `officer-music` on `alpha`, `officer-av-club` on
+`fofos`, `officer-gitea` on `production-pertento-bridge`, `officer-gitea` and `officer-offscale` on
+`edge-pertento-bridge`, `officer-email` on `deadpool-rezio-bridge`. Every one came back `online`.
+
+`ecosystem.config.cjs` was never restarted anywhere. No vault was touched.
+
+## What I did not do
+
+- **`officer-dev` — skipped entirely.** Not pulled, nothing restarted. It already sits on this code, and
+  restarting it would have ended the session writing this report. The owner restarts it deliberately,
+  last, once happy with the rest.
+- **`fofos` has an untracked `scripts/chk.ts`.** Untracked is not dirty; the fast-forward could not touch
+  it and it was left exactly where it was. A note, not a skip.
+- **`production-pertento-bridge` prints an nvm warning** on every interactive shell — its `~/.npmrc` has a
+  `globalconfig`/`prefix` setting nvm objects to. It is noise, it broke nothing, and it is not this
+  release's doing. Worth clearing at some point so it stops appearing in deploy output.
+- **No `--force` anywhere**, no dependency install, no database write.
+
+## One thing worth knowing
+
+The plan flags a **platform event bus** — `files:uploaded`, `files:placed`, `archive:extracted` — that no
+plugin subscribes to yet. The dispatch path therefore ships unexercised. If something odd shows up near an
+upload on any of these hosts, that is the first place to look.
@@ -0,0 +1,99 @@
+# 2026.08.30.01 — the file browser's clipboard moves to the server, and plugins reach further in
+
+**No schema change and no dependency change.** Verified rather than assumed:
+
+```bash
+git diff --name-only deploy/2026.08.29.04..deploy/2026.08.30.01 | grep -iE 'schema|/db/|databases'   # nothing
+git diff --name-only deploy/2026.08.29.04..deploy/2026.08.30.01 -- package.json bun.lock             # nothing
+```
+
+So **no `bun db:push` and no `bun install` step exists in this plan, and neither should be improvised.**
+Eleven commits; one of them is the previous release's report.
+
+The clipboard is per-user state and it needs no migration — it is a key in `user_state`, a JSONB column
+that already exists, written by the same `PATCH /user/state` the dock and the view mode already use.
+
+## What is in it
+
+- **The file browser's clipboard lives on the server.** It was `useState`, so it existed in one tab and
+  died with it: copying in one window and pasting in another did nothing, and a reload lost a pending cut
+  with no sign that it had. It is now a key in `user_state`, per user rather than per browser — cutting on
+  a desktop and pasting on a phone is one gesture across two screens.
+- **Files can be dragged between windows.** A custom MIME type on the DataTransfer survives between tabs
+  and windows of the same browser, so a row can be dragged from one Officer window into a folder in
+  another. It cannot cross different browsers or exchange with Finder; that is a property of the platform,
+  not a gap to report.
+- **A window re-reads its folder and the clipboard when it comes forward**, so the window a file was cut
+  from stops listing it. And **re-reading no longer blanks the list** — the spinner is now for a folder
+  that cannot yet be shown, so a refresh after a paste or a delete leaves the rows and the scroll position
+  where they were.
+- **A plugin can put an action in the file browser's context menu**, and gets an authenticated client to
+  use in it. Three commits, because the first two shipped the registration without forwarding it into the
+  menu, and then without a way to call the API.
+- **The file browser can be a file picker** — `onPickFile` turns opening a file into handing it back,
+  rather than a second component that reimplements a listing, a breadcrumb and a sort.
+- **A plugin can hand the agent its own MCP server**, declared in its manifest.
+- **A plugin may not bring its own React.** `npmDependencies` strips and then deletes `react` and
+  `react-dom` after install: a plugin's peer copy landing in `plugins/node_modules` gives the app two
+  Reacts and every hook throws.
+
+## Nothing here changes behaviour anyone has to be warned about
+
+No route is removed, no permission changes, nothing 404s that did not before. The clipboard is additive:
+a browser that has never set one reads `null` and behaves exactly as before.
+
+## Every host — the commands
+
+The standard steps in `prompts/deploy-commander.md` are the whole rollout (dirty check,
+`git fetch origin --tags`, `git merge --ff-only deploy/2026.08.30.01`, `bun run plugins:update`), plus:
+
+```bash
+pm2 restart officer
+```
+
+`officer` only — `plugins:update` has already restarted the plugin sidecars.
+
+### Verify it came back
+
+`pm2 jlist`: `officer` online and `restart_time` moved, then `/api/health` on the host's own port
+(9010 on `macbookpro` and `production-pertento-bridge`, 9000 elsewhere). `200` or `401` are healthy.
+
+### And check the file browser still lists
+
+This release touched the file browser heavily — the listing loader, the clipboard and the row markup —
+so one call per host:
+
+```bash
+bun -e "
+const { sign } = await import('./src/servers/jwt');
+const t = await sign({ id: 1, email: '<the owner on this host>' }, '2m');
+const r = await fetch('http://127.0.0.1:<PORT>/api/file-browser/ls?root=home&path=/', { headers: { Authorization: 'Bearer ' + t } });
+const b = await r.json(); console.log(r.status, (b.entries ?? []).length + ' entries');
+process.exit(0)"
+```
+
+A `200` with a plausible count. **A 500 here is a failed host** — report it and move on.
+
+## Per host
+
+Surveyed 2026-08-30 while writing this. Every host answered, and every one is clean
+(`--untracked-files=no`).
+
+| Host | HEAD at survey | Note |
+| --- | --- | --- |
+| `officer-dev` | — | **SKIP ENTIRELY.** The rollout runs here and it is already at this code. Name it as skipped. |
+| `alpha` | `e9b71522` | Exactly on the previous tag. Ordinary target. |
+| `fofos` | `601849be` | **Ahead of the previous tag, behind this one.** It has been hand-pulled all day while the fofos plugin work was written against it. That commit is an ancestor of this tag, so the fast-forward is ordinary — it simply travels fewer commits. It is also the only host with `av-club` and `fofos-admin` installed, so `plugins:update` moves more here than anywhere else. |
+| `macbookpro` | `e9b71522` | macOS, port **9010**, a laptop. Answered the survey; if it has slept since, unreachable is a SKIP with a note, not a failure. |
+| `macbruno` | `e9b71522` | macOS, login **`brunoalcadapadezmonteirodaconceicao`**. |
+| `production-pertento-bridge` | `e9b71522` | Port **9010**. |
+| `edge-pertento-bridge` | `e9b71522` | Ordinary target. |
+| `deadpool-rezio-bridge` | `e9b71522` | Login **`br`**, checkout `/home/br/officerdev/platform`. |
+
+## What "done" looks like
+
+Per host: HEAD before and after, `plugins:update` result, `officer` back online with a moved
+`restart_time`, and the `ls` check's output.
+
+Nothing in this release needs a database query, a backup or an install. If you find yourself running one,
+stop — the plan is wrong, and that is worth reporting rather than working around.
@@ -0,0 +1,114 @@
+# 2026.08.30.01 — rollout report
+
+**7 of 7 targets succeeded. `officer-dev` skipped by design — it is the host the rollout ran on.**
+
+One plugin failed on one host (`fofos-admin` on `fofos`) and it is a false alarm in the checker, not a
+broken install. The owner fixed it mid-rollout in `537cc29c`, which is NOT in this tag. Detail below.
+
+No schema change, no `bun install`, no `bun db:push` — the plan says so and shows the two
+`git diff --name-only` commands behind the claim. Nothing was improvised.
+
+## Per host
+
+| Host | HEAD before | HEAD after | plugins:update | `officer` restart_time | /api/health | file-browser `ls` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `officer-dev` | — | — | — | — | — | **SKIPPED — ran here** |
+| `alpha` | `e9b71522` | `816f8695` | 15/15, exit 0 | 6 → 7 | 401 | 200, 77 entries |
+| `fofos` | `601849be` | `816f8695` | **4/5, exit 1** | 3 → 4 | 401 | 200, 39 entries |
+| `macbookpro` | `e9b71522` | `816f8695` | no plugins installed | 6 → 7 | 401 | 200, 62 entries |
+| `macbruno` | `e9b71522` | `816f8695` | 1/1, exit 0 | 9 → 10 | 401 | 200, 41 entries |
+| `production-pertento-bridge` | `e9b71522` | `816f8695` | 1/1, exit 0 | 7 → 8 | 401 | 200, 53 entries |
+| `edge-pertento-bridge` | `e9b71522` | `816f8695` | 2/2, exit 0 | 8 → 9 | 401 | 200, 29 entries |
+| `deadpool-rezio-bridge` | `e9b71522` | `816f8695` | 2/2, exit 0 | 25 → 26 | 401 | 200, 49 entries |
+
+Every host landed on `816f8695`, exactly the tag. `fofos` started ahead of the previous tag and behind
+this one, as the plan predicted, so its fast-forward moved 12 files rather than 23.
+
+`401` on `/api/health` is healthy — the plan says so and all seven agreed. Ports were read from each
+host's own `.env`, never assumed: 9010 on `macbookpro` and `production-pertento-bridge`, 9000 elsewhere.
+
+## The file browser check
+
+This release touched the listing loader, the clipboard and the row markup, so the plan asked for one
+signed `/api/file-browser/ls` per host. **Seven hosts, seven `200`s**, every one with a plausible count
+and none of them zero. The counts differ because the homes differ.
+
+Signed as that host's own owner, read from its own `users` table rather than assumed —
+`conceiba@gmail.com` on `macbruno`, `brunorezio@gmail.com` on `deadpool-rezio-bridge`,
+`pastilhas@officer.dev` on the rest.
+
+## Schema
+
+**No schema verification was performed, because this release changes no schema.** No `db:push` step
+exists in the plan and none was run, so there is nothing to verify by query. The clipboard is a key in
+`user_state`, a JSONB column that already existed.
+
+The plugin sidecars applied their OWN schemas during `plugins:update`, which belongs to the plugin
+updater and not to this release: `music` on `alpha` (4 tables), `proxy-manager` on `fofos` (3) and on
+`macbruno` (3), `offscale` on `edge-pertento-bridge` (1), `email` on `deadpool-rezio-bridge` (1).
+
+## The one failure: `fofos-admin` on `fofos`
+
+`bun run plugins:update` exited 1 with:
+
+```
+FAILED: packages installed, but @tiptap/pm cannot be resolved from …/plugins/fofos-admin
+```
+
+**The install is fine and the plugin is not broken.** Verified on the host rather than assumed:
+
+- `plugins/node_modules/@tiptap/pm` is present, with its `dist` and the prosemirror packages.
+- `@tiptap/pm` declares no `main`, no `module`, and an `exports` map with no `"."` — it exists only as
+  subpaths. Code imports `@tiptap/pm/state`, never the bare name.
+- `Bun.resolveSync('@tiptap/pm', pluginDir)` therefore fails, while `@tiptap/react` and
+  `@tiptap/starter-kit` both resolve. `unresolvableDependencies` reads that as a failed install.
+- `fofos-admin`'s own checkout is clean, so this is not the usual uncommitted-change cause.
+
+Also verified there, and it is this release working as intended: `react` resolves out of the PLATFORM's
+`node_modules`, not the plugins tree. The eviction added in `9719e367` did its job.
+
+**The owner shipped the fix at 11:20 while the rollout was in flight — `537cc29c`, "a package with no
+root entry point is not a broken install".** It is one commit PAST this tag and is therefore deployed
+nowhere. `fofos` will keep failing that step on every `plugins:update` until a release carries it.
+
+What this cost on `fofos`: `fofos-admin` did not finish its update — no assets publish, no access grant,
+no `recorded at`. Its code was already at the latest commit, and the platform mounted `/fofos-admin`
+normally. The other four plugins updated.
+
+## A commit landed on master mid-rollout, and the tag absorbed it
+
+`alpha`, `fofos`, `macbookpro`, `macbruno` and `production-pertento-bridge` fetched `origin/master` at
+`816f8695`. `edge-pertento-bridge` and `deadpool-rezio-bridge` fetched it at `537cc29c`.
+
+Because every host merged `--ff-only deploy/2026.08.30.01` and not the branch, **all seven are on the
+tag and none carries the extra commit.** This is the exact failure of 2026-08-23, and merging the tag is
+what prevented it.
+
+## More restarted than `officer`
+
+`plugins:update` restarts a sidecar whenever it moves a plugin, before the plan's own restart. Naming
+only `officer` would understate what moved, so: `officer-music` on `alpha`, `officer-av-club` on
+`fofos`, `officer-gitea` on `production-pertento-bridge`, `officer-gitea` and `officer-offscale` on
+`edge-pertento-bridge`, `officer-email` on `deadpool-rezio-bridge`. `macbruno` moved `proxy-manager`,
+which declares no sidecar, so nothing extra bounced there.
+
+After every restart, `pm2 jlist` showed **every `officer*` process `online` on all seven hosts**. None
+was `errored` and none failed to come back.
+
+`ecosystem.config.cjs` was never restarted anywhere. No vault was touched. On
+`production-pertento-bridge` the eight Pertento-owned processes — `Dashboard`, `Tracking`, `Uptime` and
+the five `Crons *` — were filtered out of every read and never named in a restart.
+
+## What I did not do
+
+- **`officer-dev` — skipped entirely.** Not pulled, not restarted. The rollout ran inside its
+  `officer-claude-code` sidecar, and restarting it would have ended the session writing this report. Its
+  working tree already held this code. The owner restarts it deliberately, as the last step.
+- **Did not fix the `fofos-admin` checker.** The fix exists in `537cc29c` and belongs to a release, not
+  to a rollout editing five hosts.
+- **Did not re-run `plugins:update` on `fofos`** after diagnosing it. It would fail identically — the
+  code that decides is in the tag.
+- **Did not run `bun run docs:check`.** Not the commander's job.
+- **One untracked file noted, not touched:** `scripts/chk.ts` on `fofos`. Untracked is a note, not a
+  skip, and a fast-forward could never have touched it. Every host was clean on
+  `--untracked-files=no`.
@@ -0,0 +1,99 @@
+# 2026.08.30.03 — a package with no root entry point is not a broken install
+
+**One commit.** `537cc29c`, fixing what the 2026.08.30.01 rollout found on `fofos`.
+
+**Why .03 and not .02.** `2026.08.30.02` was tagged against a commit that was not on `master` — the
+rollout's own report had just been pushed and the release was cut without pulling first. The branch push
+was rejected, the tag was not, and a tag pointing off-branch was published for about ten seconds before
+being withdrawn. The watcher claimed the version inside that window.
+
+A claim is permanent by design and that is correct: `.02` was attempted, so `.02` is spent and cannot be
+deployed. It has a claim and no `.done`, which is exactly what "attempted and did not succeed" should
+look like in the record. Nothing reached any host — every one stayed on `816f8695` throughout.
+
+**No schema change and no dependency change.** Verified rather than assumed:
+
+```bash
+git diff --name-only deploy/2026.08.30.01..deploy/2026.08.30.03 | grep -iE 'schema|/db/|databases'   # nothing
+git diff --name-only deploy/2026.08.30.01..deploy/2026.08.30.03 -- package.json bun.lock             # nothing
+```
+
+So **no `bun db:push` and no `bun install` step exists in this plan, and neither should be improvised.**
+
+## What it fixes, and what it does not
+
+`unresolvableDependencies` asked `Bun.resolveSync(name, pluginDir)` of every package a plugin declares.
+That is the right question for almost all of them and unanswerable for a few.
+
+`@tiptap/pm` declares no `main`, no `module`, and an `exports` map with no `"."` — it exists only as
+subpaths, because it is tiptap's single pinned copy of the ProseMirror packages and you import
+`@tiptap/pm/state`, never `@tiptap/pm`. Asked to resolve the bare name, Bun correctly says it cannot,
+and the checker read that as a failed install.
+
+**Nothing was ever broken on disk.** The install on `fofos` is complete — the directory, its `dist` and
+thirteen prosemirror packages. The editor works. What failed was the verification, which then failed
+`plugins:update`, which exits non-zero if any plugin failed.
+
+The consequence worth shipping for: **`bun run plugins:update` exits 1 on `fofos` every time** until
+this lands, so the plugin step of every future deploy fails there and looks like a new problem.
+
+The strong check stays first, so a package that installed but cannot be loaded on this machine still
+fails — `sharp` resolving to a platform-specific binary is the shape it was written for. Only a package
+that fails it is asked the weaker question: is it there.
+
+## Every host — the commands
+
+The standard steps in `prompts/deploy-commander.md` are the whole rollout (dirty check,
+`git fetch origin --tags`, `git merge --ff-only deploy/2026.08.30.03`, `bun run plugins:update`), plus:
+
+```bash
+pm2 restart officer
+```
+
+`officer` only — `plugins:update` has already restarted the plugin sidecars.
+
+**`fofos` is the host this release is for.** Its `plugins:update` failed 4/5 on the last rollout and
+should now be 5/5, exit 0. That is the check that matters:
+
+```
+→ fofos-admin
+    packages: installed and resolvable
+```
+
+If `fofos` still reports 4/5 with `@tiptap/pm cannot be resolved`, this release did not work and that
+is the finding — report it rather than working around it.
+
+Everywhere else this is a no-op in behaviour: no other host has `fofos-admin` installed, so no other
+host was failing and none should start.
+
+### Verify it came back
+
+`pm2 jlist`: `officer` online and `restart_time` moved, then `/api/health` on the host's own port
+(9010 on `macbookpro` and `production-pertento-bridge`, 9000 elsewhere). `200` or `401` are healthy.
+
+No file-browser check this time — this release touches one function in the plugin installer and
+nothing a browser reaches.
+
+## Per host
+
+Every host went to `816f8695` an hour ago and all seven came back online, so they start from there.
+
+| Host | Note |
+| --- | --- |
+| `officer-dev` | **SKIP ENTIRELY.** The rollout runs here. It already holds this commit and its `officer` was restarted by hand at 11:23. |
+| `alpha` | Ordinary target. No `fofos-admin`, so nothing changes in behaviour. |
+| `fofos` | **The reason for this release.** Expect `plugins:update` to go 4/5 → 5/5. |
+| `macbookpro` | macOS, port **9010**, a laptop. Unreachable is a SKIP with a note, not a failure. |
+| `macbruno` | macOS, login **`brunoalcadapadezmonteirodaconceicao`**. |
+| `production-pertento-bridge` | Port **9010**. |
+| `edge-pertento-bridge` | Ordinary target. |
+| `deadpool-rezio-bridge` | Login **`br`**, checkout `/home/br/officerdev/platform`. |
+
+Note for whoever reads the report: `scripts/chk.ts` is untracked on `fofos` and was noted last time. It
+is still a note, not a skip.
+
+## What "done" looks like
+
+Per host: HEAD before and after, `plugins:update` result, `officer` back online with a moved
+`restart_time`. And for `fofos` specifically, the `fofos-admin` line reading
+`packages: installed and resolvable`.
@@ -0,0 +1,55 @@
+# 2026.08.30.03 — report
+
+**7 of 7 target hosts succeeded.** `officer-dev` skipped entirely, as the host the rollout ran on.
+
+Every target went `816f8695` → `c97da029` by `git merge --ff-only deploy/2026.08.30.03`. No host was
+dirty in tracked files, none had to be skipped, and no merge was anything other than a fast-forward.
+
+**The release did what it was cut for.** `fofos` went 4/5 → **5/5, exit 0**, with `fofos-admin` reading
+`packages: installed and resolvable`. That was the one check that mattered and it passed.
+
+**No schema step and no `bun install` step** — the plan has neither, and neither was improvised. So there
+is no per-host schema query in this report, because this release introduced nothing to query for.
+
+## Per host
+
+| Host | HEAD before → after | `plugins:update` | `officer` restart_time | health |
+| --- | --- | --- | --- | --- |
+| `officer-dev` | — | — | — | **SKIPPED** — the host this ran on |
+| `alpha` | `816f8695` → `c97da029` | 15/15 | 7 → 8, online | `401` (9000) |
+| `fofos` | `816f8695` → `c97da029` | **5/5, exit 0** | 4 → 5, online | `401` (9000) |
+| `macbookpro` | `816f8695` → `c97da029` | no plugins installed | 7 → 8, online | `401` (9010) |
+| `macbruno` | `816f8695` → `c97da029` | 1/1 | 10 → 11, online | `401` (9000) |
+| `production-pertento-bridge` | `816f8695` → `c97da029` | 1/1 | 8 → 9, online | `401` (9010) |
+| `edge-pertento-bridge` | `816f8695` → `c97da029` | 2/2 | 9 → 10, online | `401` (9000) |
+| `deadpool-rezio-bridge` | `816f8695` → `c97da029` | 2/2 | 26 → 27, online | `401` (9000) |
+
+`401` on `/api/health` is healthy — the endpoint is behind auth.
+
+## What is worth reading
+
+- **`fofos` is fixed.** `plugins:update` there had failed 4/5 on every rollout since `@tiptap/pm` was
+  installed, and it now exits 0. The plugin step of the next deploy should be unremarkable on that host.
+- **`macbookpro` needed a fetch retry.** The first `git fetch` failed with
+  `Connection closed by 77.42.39.155 port 22` — gitea's public SSH, rate-limited at the proxy. That host
+  resolves `gitea.officer.dev` to the public address where `alpha` reaches it over the tailnet. The first
+  retry succeeded and the rollout continued normally. A later probe was refused again, so the window is
+  intermittent rather than closed. **Nothing to fix in the deploy; the remote on that host is the thing
+  that is wrong**, and pointing it at the tailnet address would remove a class of failure that costs a
+  retry on every release.
+- **`scripts/chk.ts` is still untracked on `fofos`.** Noted, not a skip, exactly as the plan said. It has
+  survived two rollouts now; somebody may want to commit it or delete it.
+- **`plugins:update` restarted sidecars on several hosts** before the `pm2 restart officer` the plan
+  asked for — `officer-music` on `alpha`, `officer-gitea` on `production-pertento-bridge`,
+  `officer-offscale` on `edge-pertento-bridge`, `officer-email` on `deadpool-rezio-bridge`. That is the
+  documented behaviour of the plugins step, not something this rollout chose.
+- **On `production-pertento-bridge` only `officer` was restarted.** Pertento's eight production processes
+  were not touched.
+
+## What was not done
+
+- `officer-dev` was not pulled, not updated and not restarted. It already holds `c97da029` and its
+  `officer` was restarted by hand at 11:23. **The owner restarts this host deliberately, as the last
+  step**, once happy with the rest.
+- No `bun db:push`, no `bun install`, no direct SQL. The plan called for none.
+- No file-browser check, per the plan.
@@ -29,17 +29,21 @@ Ranked by what actually blocks something.

 ## Staleness

- [ ] **Nothing refreshes the catalogue automatically.** Publishing a plugin update changes nothing until
-      somebody runs `bun --env-file=.env scripts/marketplace-sync.ts`. A Gitea webhook or a cron is the
-      obvious next step.
+- [x] **Nothing refreshes the catalogue automatically.** Done 2026-09-03: `scripts/marketplace-cron.sh`
+      every minute. A Gitea webhook would make it a second instead, at the price of a public write route
+      on the one process here with no login — not worth it for a minute.

- [ ] **The sync reads local clones, not the remotes.** The machine running it must have every plugin
-      checked out, so the catalogue describes that machine's copies. The version that clones each repo
-      into a temp directory is a small change.
+- [x] **The sync reads local clones, not the remotes.** Done 2026-09-03. Bare mirrors, read at the newest
+      tag, driven by the registry rather than by a directory listing. The catalogue no longer describes
+      any machine's working copies.

- [ ] **`rawUrl()` assumes Gitea and a `main` branch.** A GitHub-hosted plugin, or one whose default branch
-      is `master`, gets a 404 for its icon. The forge belongs in the registry rather than inferred from a
-      URL shape.
+- [ ] **`rawUrl()` assumes Gitea.** A GitHub-hosted plugin gets a 404 for its icon. The forge belongs in
+      the registry rather than inferred from a URL shape. (The `main`-vs-`master` half of this is gone —
+      URLs pin to the release tag now.)
+
+- [ ] **Four plugins have never been tagged**, so the store still shows rows the old sync took from a
+      working tree: av-club, kanban, openseo, fofos-admin. They are frozen until somebody tags them, and
+      the sync names them on every run somebody asks for.

 ## Scale

@@ -10,8 +10,9 @@ from. **The website installs nothing** — installing means cloning a repository
 starting a process on someone else's machine, so it happens entirely inside the owner's own Officer.

 ```
-gitea.officer.dev/plugins/*   the repositories (source of truth)
-        │  scripts/marketplace-sync.ts  (manual, reads manifest.ts + README.md)
+gitea.officer.dev/**          the repositories (source of truth)
+        │  bare mirrors, read AT THE NEWEST TAG — src/servers/marketplace/sync.ts
+        │  every minute, scripts/marketplace-cron.sh
        ▼
 officer_marketplace (postgres)          plugins + plugin_metadata
        │  src/servers/marketplace/server.tsx  :9100
@@ -20,6 +21,7 @@ marketplace.officer.dev                 GET /api/plugins, /api/plugins/:appName
        │  fetchCatalogue()  live → cached → bundled
        ▼
 an Officer install                      /marketplace → clone → push schema → mount
+                                        and the update badge — see "Publishing" below
 ```

 ## The parts
@@ -78,19 +80,87 @@ disappearing from the store.
 the clone, the plugin's own manifest is what the platform reads. A metadata row that disagrees with the
 repository is a marketplace bug, never a second source of truth.

-## Sync
+## Publishing
+
+**Push a tag. That is the whole procedure.** A timer on officer-dev picks it up within a minute and every
+Officer install sees it on the next page load.

 ```bash
-bun --env-file=.env scripts/marketplace-sync.ts
+bun --env-file=.env scripts/marketplace-sync.ts            # all of them, now
+bun --env-file=.env scripts/marketplace-sync.ts photos     # one
+bun --env-file=.env scripts/marketplace-sync.ts --add https://gitea.officer.dev/plugins/finances.git
+bun --env-file=.env scripts/marketplace-sync.ts --force    # re-publish rows this file's own logic changed
 ```

-Reads every directory under `plugins/`, imports its `manifest.ts`, derives `has` from the directory
-rather than from a declaration, reads `README.md`, and upserts. Re-running is always safe: it overwrites,
-never merges.
+### It reads releases, never a working tree

-It rewrites SSH remotes to HTTPS. `example` and `offscale` had `git@gitea…` origins, which would have
-handed every installer a URL that only works on the machine that published it — the install fails at
-authentication, which reads as "the plugin is broken" rather than "the catalogue is wrong".
+Every registered plugin is mirrored bare into `~/.cache/officer-marketplace/mirrors` and read at its
+newest tag — manifest, README and file list all out of `git cat-file`. There is no working tree in the
+path, so publishing something uncommitted is not a mistake that can be made.
+
+That is a change, and it was load-bearing. Until 2026-09-03 the sync imported `manifest.ts` off
+`platform/plugins/` — the directories THIS machine has installed — so publishing meant "get officer-dev's
+checkout to the release, then run the script", and nothing showed when that had not happened. On the day
+it was rewritten the live store was advertising four plugins from untagged working copies: av-club
+2026.08.29.01, kanban 2026.08.29.02, openseo 0.1.0 and fofos-admin 2026.08.29.26, none of which had ever
+been tagged. It is also why the job could not go on a timer before: a cron over it published whatever was
+in a working tree, on a schedule.
+
+### The registry decides which plugins, and where from
+
+The list comes from the `plugins` table — the half this document has always called authoritative, and
+which was in fact a by-product of what happened to be checked out. Now it decides. A plugin nobody has
+installed here can still be published, and a plugin lives wherever its row says: `fofos-admin` is under
+`fofos/`, not `plugins/`, which an org listing would have missed. Registering one is `--add`.
+
+### A plugin with no tag is left alone
+
+It has never made a release, so the sync has nothing true to say about it: the existing row stays and the
+run names it. Deleting it would drop somebody's plugin out of the store on the day the rule changed.
+Tagging it is the fix, and the report is the reminder.
+
+### `release_tag`, and why it is not `version`
+
+`version` is the manifest's own claim; `release_tag` is what was pushed. They match every time somebody
+tags correctly, and when they do not, the tag is the fact — a manifest whose version nobody bumped would
+otherwise make a real release invisible to anything comparing versions. The sync warns on a mismatch.
+
+Icon URLs pin to the tag too. `/raw/HEAD/…` served whatever was on the default branch, via a 303, so a
+plugin could show one icon in the store and ship another.
+
+### The timer
+
+`scripts/marketplace-cron.sh`, `* * * * *`, logging to `officer-dev/marketplace-sync.log`. One
+timestamped summary line per tick — always, including the ticks that do nothing, because a fresh
+timestamp is the only thing that distinguishes "nothing to publish" from "the timer died". A plugin-level
+line appears only when one actually moved.
+
+A tick costs about 2.7s with nothing to do: one query, one fetch per repository, no writes. Nothing is
+written unless the release commit differs from the one already published.
+
+A Gitea webhook would cut the delay from a minute to a second, at the price of a public write route and a
+shared secret. A minute was never the problem anybody had — the complaint that started this was a release
+that never appeared at all.
+
+### Remotes
+
+`--add` rewrites SSH to HTTPS. A `git@gitea…` origin in the catalogue hands every installer a URL that
+only works on the machine that published it, and the install fails at authentication — which reads as
+"the plugin is broken" rather than "the catalogue is wrong".
+
+## The update badge reads the catalogue
+
+`updateable` on `/api/plugins` compares the tag at the checkout's HEAD with the tag the catalogue says is
+newest. Difference, not ordering: parsing `2026.08.27.01` works right up until somebody tags `v2`, and
+then it fails silently.
+
+Before this, each host ran a rate-limited background `git fetch` against all twenty-one repositories to
+re-derive a fact one place already knew. That is gone. `releaseState()` still holds the git rule as a
+fallback for a plugin the store cannot speak for — an unregistered checkout, or a store that could not be
+reached — and in that case its refs are whatever the last `pullPlugin` left, which is the accepted cost.
+
+`fetchCatalogue()`'s cache dropped from five minutes to one when the badge started depending on it:
+otherwise the wait for a release to appear was the sync's minute plus the cache's five.

 ## The platform degrades, it does not break

@@ -111,13 +181,8 @@ The full list, ranked, is `docs/marketplace-todo.md`. The ones that shape the de
 - **`[blocker]` Third-party submissions cannot use this sync.** It reads a manifest by importing it, which
  is code execution. Fine for our own repositories; not a mechanism a stranger's plugin can go through.
  Submissions need either a sandbox or a published `manifest.json` alongside the TypeScript one.
- **`[open]` Sync reads local clones, not the remotes.** The machine running it must have the plugins
-  checked out. The version that clones each repo into a temp directory is a small change and was left out
-  of the first pass.
- **`[open]` `rawUrl()` assumes Gitea and a `main` branch.** A GitHub-hosted plugin or one defaulting to
-  `master` gets a 404 for its icon. The forge should become part of the registry rather than inferred.
+- **`[open]` `rawUrl()` assumes Gitea.** A GitHub-hosted plugin needs the other URL form. The forge should
+  become part of the registry rather than inferred from the URL.
 - **`[open]` No versions table.** `plugin_metadata` is one row per plugin — a snapshot, not a history. A
  store that can offer "install 1.2 instead of 1.3" needs a different shape.
- **`[open]` Nothing refreshes automatically.** Publishing a plugin update does not change the catalogue
-  until somebody runs the sync. A cron or a Gitea webhook is the obvious next step.
 - **`[open]` No search, no categories, no counts.** Three plugins do not need them.
@@ -1,6 +1,6 @@
 {
  "name": "officer",
-  "version": "2026.08.29.04",
+  "version": "2026.08.30.03",
  "private": true,
  "type": "module",
  "workspaces": [
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Publish every plugin release to the marketplace catalogue. Meant for cron, on the ONE machine that
+# publishes.
+#
+# ── Why a timer at all, when a webhook would be instant ──
+#
+# The sync reads bare mirrors at their newest tag, so running it on a schedule cannot publish anything
+# that was not pushed — which is exactly what made a timer unsafe before, and is no longer true. A Gitea
+# webhook would cut the delay from a minute to a second, and it would also mean a public write route, a
+# shared secret, and a second path into the same code. A minute is not the problem anybody had: the
+# complaint that started this was a release that never appeared at all.
+#
+# ── What it costs ──
+#
+# About 2.7s per tick with nothing to do — one query, one fetch per repository, no writes. Gitea is on
+# this same machine, so none of that leaves the box.
+#
+# ── The log ──
+#
+# One timestamped summary line per tick, ALWAYS, including the ticks that do nothing. A fresh timestamp
+# is the only thing that distinguishes "nothing to publish" from "the timer died". Plugin-level lines
+# appear only for a plugin that actually moved, which is what `--quiet` buys.
+
+set -uo pipefail
+
+PLATFORM="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LOG="${MARKETPLACE_SYNC_LOG:-$(dirname "$PLATFORM")/marketplace-sync.log}"
+LOCK="/tmp/officer-marketplace-sync.lock"
+
+# Cron's PATH is three entries and bun is in none of them.
+export PATH="$HOME/.bun/bin:/usr/local/bin:/usr/bin:/bin"
+
+cd "$PLATFORM" || exit 1
+
+# Skip rather than queue. A tick that finds the previous one still running has nothing to add — the run
+# in progress will publish whatever this one would have.
+exec 9>"$LOCK"
+flock -n 9 || exit 0
+
+bun --env-file=.env scripts/marketplace-sync.ts --quiet >>"$LOG" 2>&1
+
+# Bounded without logrotate, because this is one file on one machine and a config file for it would be
+# more moving parts than the thing it manages.
+if [ "$(wc -l <"$LOG")" -gt 20000 ]; then
+  tail -n 5000 "$LOG" >"$LOG.tmp" && mv "$LOG.tmp" "$LOG"
+fi
@@ -1,43 +1,40 @@
 #!/usr/bin/env bun
-import { existsSync, readFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
-import { upsertMetadata, upsertPlugin } from '../src/databases/marketplace_db/src/plugins/queries';
-import { discoverPlugins } from '../src/servers/plugins/discover';
+import { upsertPlugin } from '../src/databases/marketplace_db/src/plugins/queries';
+import { syncAll, syncPlugin } from '../src/servers/marketplace/sync';

-// Fill the marketplace database from the plugin repositories.
-//
-// ── What this reads, and why it is not the marketplace's own opinion ──
-//
-// Every field except "where to clone from" comes out of the plugin's `manifest.ts` and its README. The
-// marketplace stores a COPY so the website can render without cloning three repositories per page load;
-// the manifest stays the source of truth, and the platform re-reads it after cloning. A row here that
-// disagrees with the repository is a stale cache, not a second opinion — which is why re-running this is
-// always safe and never merges: it overwrites.
-//
-// ── Reading the manifest by importing it ──
-//
-// A manifest is TypeScript, not JSON, so it is imported and evaluated rather than parsed. That is code
-// execution, and it is fine for OUR repositories and not fine as a general mechanism.
-//
-// `[blocker for third-party submissions]` A stranger's plugin cannot be imported by the machine that
-// serves the catalogue. Whoever builds submissions has to either evaluate manifests in a sandbox or make
-// authors publish a `manifest.json` alongside. Recorded rather than solved: nobody can submit yet.
-//
-// ── Local clones, for now ──
-//
-// It syncs from `plugins/` on this machine rather than by cloning each repo into a temp directory. That
-// keeps tonight's scope to "get real data into the database" — and it means the machine running the sync
-// must have the plugins checked out. See `docs/marketplace.md` → "Sync" for the version that clones.
+/**
+ * Fill the marketplace catalogue from the plugins' releases.
+ *
+ *   bun --env-file=.env scripts/marketplace-sync.ts                  every registered plugin
+ *   bun --env-file=.env scripts/marketplace-sync.ts photos           just one
+ *   bun --env-file=.env scripts/marketplace-sync.ts --add <url>      register a new one, then sync it
+ *   bun --env-file=.env scripts/marketplace-sync.ts --force          re-publish releases already published
+ *   bun --env-file=.env scripts/marketplace-sync.ts --quiet          print only what changed
+ *
+ * All the reasoning is in `src/servers/marketplace/sync.ts` — this file is the command line around it.
+ * It is a thin wrapper on purpose: the same functions are what the Gitea webhook calls, so a plugin
+ * published by hand and one published by pushing a tag go through exactly the same code.
+ *
+ * Re-running is always safe. It overwrites and never merges.
+ */

-type Sync = { appName: string; developer: string; repoUrl: string };
+const argv = process.argv.slice(2);
+/*
+  `--quiet` is what the timer runs: one line per plugin that actually moved, and a summary. Not silence —
+  the summary is always printed, because a log whose last line is old is the only way to tell "nothing to
+  publish" from "the timer died", and that question does come up.
+*/
+const quiet = argv.includes('--quiet');
+const force = argv.includes('--force');
+const args = argv.filter((a) => a !== '--quiet' && a !== '--force');

 /**
 * A clone URL the whole internet can use.
 *
- * `plugins/example` and `plugins/offscale` have `git@gitea.officer.dev:plugins/<name>.git` remotes,
- * because whoever set them up had a key on that host. Publishing that to a catalogue would hand every
- * installer a URL that only works on the machine it was published from — the install fails at
- * authentication, which reads as "the plugin is broken" rather than "the catalogue is wrong".
+ * Several plugin repos have `git@gitea.officer.dev:plugins/<name>.git` remotes, because whoever set them
+ * up had a key on that host. Registering one of those would hand every installer a URL that only works
+ * on the machine it was published from — the install fails at authentication, which reads as "the plugin
+ * is broken" rather than "the catalogue is wrong".
 */
 export function toHttpsRemote(remote: string): string | null {
  const trimmed = remote.trim();
@@ -60,142 +57,58 @@ export function toHttpsRemote(remote: string): string | null {
  return null;
 }

-const git = (dir: string, args: string[]): string | null => {
-  const result = Bun.spawnSync(['git', '-C', dir, ...args], { stdout: 'pipe', stderr: 'ignore' });
-  if (result.exitCode !== 0) return null;
-  return new TextDecoder().decode(result.stdout).trim() || null;
-};
-
-/*
-  Which plugins directory to publish FROM.
-
-  There is one: `platform/plugins/`, holding what this machine has INSTALLED — updated by
-  `plugins:update`, which is a git pull, so it sits at whatever version was last installed.
-
-  Publishing from it means the catalogue advertises the version this machine happens to be running
-  rather than the version that was released. That is exactly what happened on 2026-08-27: 21 plugins
-  were tagged and the store went on showing 1.0.0.
-
-  A second directory — `officer-dev/plugins/`, every repo in the org cloned side by side — was created
-  to fix that, and never did: its entries were SYMLINKS into this one, so both paths read the same
-  working copy and published the same version. It was removed on 2026-08-28.
-
-  **The problem is still open, and a second checkout was never the answer.** Each directory here is a
-  real git repo with its own tags, so the released manifest can be read out of the tag itself —
-  `git show <newest-tag>:manifest.ts` — without caring what is checked out. That is the fix; it is not
-  written yet, and until it is, this script advertises what is installed.
-*/
-const PLUGINS_DIR = process.env.PLUGINS_DIR ?? resolve(import.meta.dir, '..', 'plugins');
-
-async function syncOne(dir: string): Promise<Sync | null> {
-  const appName = basename(dir);
-  const manifestPath = join(dir, 'manifest.ts');
-  if (!existsSync(manifestPath)) {
-    console.warn(`[marketplace-sync] ${appName}: no manifest.ts — skipped`);
-    return null;
+if (args[0] === '--add') {
+  const raw = args[1];
+  if (!raw) {
+    console.error('usage: marketplace-sync.ts --add <clone url>');
+    process.exit(1);
  }
-
-  const remote = git(dir, ['remote', 'get-url', 'origin']);
-  const repoUrl = remote ? toHttpsRemote(remote) : null;
+  const repoUrl = toHttpsRemote(raw);
  if (!repoUrl) {
-    console.warn(`[marketplace-sync] ${appName}: no usable https remote (${remote ?? 'none'}) — skipped`);
-    return null;
+    console.error(`[marketplace-sync] ${raw} is not a clone URL this can turn into https`);
+    process.exit(1);
+  }
+  const appName = repoUrl.replace(/\.git$/, '').split('/').pop() ?? '';
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(appName)) {
+    console.error(`[marketplace-sync] "${appName}" is not a usable app name`);
+    process.exit(1);
  }

-  const { manifest } = (await import(manifestPath)) as { manifest: Record<string, unknown> };
-  if (!manifest) {
-    console.warn(`[marketplace-sync] ${appName}: manifest.ts exports no \`manifest\` — skipped`);
-    return null;
+  // Registered with a placeholder developer, then immediately synced — which reads the real publisher
+  // out of the released manifest and overwrites it. A repository with no tag stays registered and
+  // unpublished, which is the correct state for one that has not made a release yet.
+  await upsertPlugin({ appName, developer: 'unknown', repoUrl });
+  console.log(`[marketplace-sync] registered ${appName} → ${repoUrl}`);
+  const one = await syncPlugin(appName, force);
+  report([one]);
+  process.exit(one.status === 'failed' ? 1 : 0);
 }

-  // What the plugin SHIPS, read from the directory rather than declared — the same rule discovery
-  // follows, so a catalogue entry cannot claim a sidecar the repository does not have.
-  const has = {
-    api: existsSync(join(dir, 'api', 'router.ts')),
-    schema: existsSync(join(dir, 'db', 'schema.ts')),
-    sidecar: existsSync(join(dir, 'sidecar', 'index.ts')) || existsSync(join(dir, 'sidecar', 'index.mjs')),
-    web: existsSync(join(dir, 'web')),
-  };
+const results = args[0] ? [await syncPlugin(args[0], force)] : await syncAll(force);
+report(results);
+process.exit(results.some((r) => r.status === 'failed') ? 1 : 0);

-  const readmePath = ['README.md', 'readme.md'].map((n) => join(dir, n)).find((p) => existsSync(p));
-  const readme = readmePath ? readFileSync(readmePath, 'utf-8') : null;
-
-  const developer = String(manifest.publisher ?? 'unknown');
-  const pluginId = await upsertPlugin({ appName, developer, repoUrl });
-
-  await upsertMetadata(pluginId, {
-    version: String(manifest.version ?? '0.0.0'),
-    platform: String(manifest.platform ?? '>=1.0.0'),
-    label: String(manifest.label ?? appName),
-    summary: String(manifest.summary ?? ''),
-    // Taken verbatim, NOT validated here. `manifestProblems` already refuses a tag outside the
-    // vocabulary at discovery, so anything reaching this point is either valid or belongs to a plugin
-    // the platform would not load anyway — and a sync that silently dropped a tag would be a catalogue
-    // quietly disagreeing with the repository it claims to mirror.
-    tags: Array.isArray(manifest.tags) ? manifest.tags : [],
-    color: (manifest.color as string) ?? null,
-    tile: (manifest.tile as string) ?? null,
-    // Artwork lives in the repo, so the URL is built from the remote rather than stored by hand. Only
-    // claimed when the file is actually there — a broken image is worse than a glyph.
-    iconUrl: existsSync(join(dir, 'assets', 'icon.png')) ? rawUrl(repoUrl, 'assets/icon.png') : null,
-    icon: (manifest.icon as string) ?? null,
-    permissions: manifest.permissions ?? [],
-    osDependencies: manifest.osDependencies ?? null,
-    has,
-    readme,
-    sourceCommit: git(dir, ['rev-parse', 'HEAD']),
-  });
-
-  console.log(
-    `[marketplace-sync] ${appName} ← ${repoUrl}${readme ? '' : ' (no README)'}${has.web ? '' : ' (no web/)'}`,
-  );
-  return { appName, developer, repoUrl };
+function report(results: Awaited<ReturnType<typeof syncAll>>): void {
+  const stamp = new Date().toISOString();
+  for (const r of results) {
+    if (r.status === 'synced') console.log(`[marketplace-sync] ${r.appName} ← ${r.tag}`);
+    else if (r.status === 'failed') console.error(`[marketplace-sync] ${r.appName} failed: ${r.error}`);
+    else if (quiet) continue;
+    else if (r.status === 'unchanged') console.log(`[marketplace-sync] ${r.appName} = ${r.tag}`);
+    else console.warn(`[marketplace-sync] ${r.appName}: no tag — nothing published`);
  }

-/**
- * A raw-file URL for a Gitea repository.
- *
- * `HEAD`, not a branch name. This said `branch/main` and the comment here warned that "a repo whose
- * default branch is `master` gets a 404" — which then happened: four plugin repositories were created
- * on `master` and every one of them served a broken image in the marketplace on any server that reads
- * the remote catalogue. A warning in a comment is not a guard.
- *
- * Gitea resolves `HEAD` to whatever the default branch is, so the question stops being asked. Verified
- * against both spellings.
- *
- * `[open]` Still Gitea-shaped. A GitHub-hosted plugin needs the other form, and that wants the forge to
- * be part of the registry rather than inferred from the URL.
- */
-function rawUrl(repoUrl: string, path: string): string {
-  return `${repoUrl.replace(/\.git$/, '')}/raw/HEAD/${path}`;
+  const synced = results.filter((r) => r.status === 'synced').length;
+  const unchanged = results.filter((r) => r.status === 'unchanged').length;
+  const unreleased = results.filter((r) => r.status === 'unreleased').map((r) => r.appName);
+  const failed = results.filter((r) => r.status === 'failed').map((r) => r.appName);
+
+  console.log(`[marketplace-sync] ${stamp} — ${synced} published, ${unchanged} unchanged, ${unreleased.length} untagged`);
+  // Named rather than counted, and not under `--quiet`: "4 untagged" is a number nobody acts on, but a
+  // timer that reprints the same four names every minute is a log nobody reads. The names belong in a
+  // run somebody asked for.
+  if (unreleased.length && !quiet) {
+    console.warn(`[marketplace-sync] never tagged, so not updated: ${unreleased.join(', ')}`);
  }
-
-const dirs = existsSync(PLUGINS_DIR)
-  ? [...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) {
-  console.log(`[marketplace-sync] no plugin directories under ${PLUGINS_DIR} — nothing to sync`);
-  process.exit(0);
+  if (failed.length) console.error(`[marketplace-sync] failed: ${failed.join(', ')}`);
 }
-
-// Discovery is not used to FIND them — a plugin that fails discovery is exactly the kind of thing a
-// catalogue should still be able to describe — but its broken list is worth surfacing here.
-const { broken } = await discoverPlugins().catch(() => ({ broken: [] as { appName: string; error: string }[] }));
-for (const { appName, error } of broken) console.warn(`[marketplace-sync] ${appName} is broken on disk: ${error}`);
-
-const synced: Sync[] = [];
-for (const dir of dirs) {
-  const result = await syncOne(dir).catch((err) => {
-    console.error(`[marketplace-sync] ${basename(dir)} failed: ${err instanceof Error ? err.message : err}`);
-    return null;
-  });
-  if (result) synced.push(result);
-}
-
-console.log(`[marketplace-sync] ${synced.length}/${dirs.length} plugin(s) in the catalogue`);
-process.exit(0);
@@ -8,7 +8,17 @@ import { useInitialData } from '@/state/useInitialData';
 // `installedPlugins`, not `plugins`: App.tsx already destructures a `plugins` from useServerSettings(),
 // which is the DEAD plugin system — /server-settings/plugins scans src/workspaces/plugins/, a directory
 // that does not exist, so it is always []. Different thing entirely; see plugins/offscale/PLUGIN.md.
-import { plugins as installedPlugins } from './Plugins.gen';
+import { plugins as installedPlugins, pluginFileActions } from './Plugins.gen';
+import { registerFileActions } from 'officerdev';
+
+/*
+  Plugin actions for the file browser's context menu, handed over once at module load.
+
+  Injected rather than imported by the browser itself: `Plugins.gen.tsx` is generated INTO this app, and
+  the file browser lives in a workspace package this app depends on. Importing it there would point the
+  dependency backwards and make that package unusable outside Officer's own frontend.
+*/
+registerFileActions(pluginFileActions);

 /**
 * `/plugins` → `/marketplace`, KEEPING the query string.
@@ -87,20 +97,34 @@ export function App() {
                404 on a route that worked yesterday reads as the feature having been removed. */}
            <Route path="/plugins" element={<PluginsRedirect />} />
            {/* Installed plugins. Core routes above stay hand-written; everything below is generated from
-                what is installed, because a bundler cannot follow a runtime import specifier. The wildcard
-                hands the whole subtree to the plugin's own router, which react-router nests natively. */}
-            {/* One pair per SCREEN, not per plugin — `screenId` is the key, because a plugin with two
+                what is installed, because a bundler cannot follow a runtime import specifier. */}
+            {/* One route per SCREEN, not per plugin — `screenId` is the key, because a plugin with two
                screens (caldav: Calendar and Contacts) contributes two entries sharing one `appName`. */}
+            {/*
+              Three routes, and the third is the only new one.
+
+              `/<route>` and `/<route>/:section` are what every plugin has always had, and fifteen of
+              them read `useParams().section`. A splat ALONE replaced that for a day and took the
+              parameter away from all of them at once — the screens still mounted and every one of them
+              lost its selection, which is a worse failure than a 404 because nothing says so.
+
+              The splat is added for depth rather than instead of them: `/fofos-admin/layout/header` was
+              not expressible before, and a plugin that wants its own subtree reads the location.
+              React-router ranks a static or dynamic segment above a splat, so a plugin with one segment
+              still gets `section` and only deeper paths fall through.
+            */}
            {installedPlugins.flatMap((plugin) => [
              <Route key={plugin.screenId} path={plugin.route} element={<Dashboard.PluginScreen {...plugin} />} />,
-              // The section pair, exactly as the core screens do it (`/soulseek/:section`): the plugin's
-              // panels read `useParams` themselves, so which section is open is the URL rather than state
-              // passed between them.
              <Route
                key={`${plugin.screenId}-section`}
                path={`${plugin.route}/:section`}
                element={<Dashboard.PluginScreen {...plugin} />}
              />,
+              <Route
+                key={`${plugin.screenId}-deep`}
+                path={`${plugin.route}/*`}
+                element={<Dashboard.PluginScreen {...plugin} />}
+              />,
            ])}
            <Route path="/system-monitor" element={<Dashboard.SystemMonitorScreen />} />
            <Route path="/system-monitor/:scope" element={<Dashboard.SystemMonitorScreen />} />
@@ -14,6 +14,14 @@ export type CatalogueEntry = {
  appName: string;
  publisher: string;
  version: string;
+  /**
+   * The git tag this entry was published from.
+   *
+   * Optional on the wire, not in the database, and the two mean different things. Here it is absent for
+   * a row that predates release-based publishing OR for a catalogue too old to send the field at all —
+   * so a consumer must treat "no tag" as "cannot tell" and fall back to whatever it knew before.
+   */
+  releaseTag?: string;
  platform: string;
  label: string;
  summary: string;
@@ -52,6 +60,7 @@ function toCatalogueEntry(row: Row): CatalogueEntry | null {
    appName: row.appName,
    publisher: row.developer,
    version: m.version,
+    ...(m.releaseTag ? { releaseTag: m.releaseTag } : {}),
    platform: m.platform,
    label: m.label,
    summary: m.summary,
@@ -106,6 +115,36 @@ export async function catalogueEntry(appName: string): Promise<CatalogueEntry |
  return { ...entry, ...(row.metadata.readme ? { readme: row.metadata.readme } : {}) };
 }

+/**
+ * A registry row, plus the one piece of metadata the sync needs before deciding to do any work.
+ *
+ * `sourceCommit` is what the last sync published, and it is here rather than fetched per plugin so a
+ * run that has nothing to do costs one query instead of twenty-five. Null means never synced.
+ */
+export type RegistryRow = { id: number; appName: string; repoUrl: string; sourceCommit: string | null };
+
+/**
+ * Every registered plugin — identity and clone URL, no metadata.
+ *
+ * This is what the sync iterates, and it is the reason the registry is called authoritative: the
+ * catalogue lists what somebody deliberately registered, not what happens to be checked out on the
+ * machine that runs the job. Unlisted rows are included; hiding a plugin from the public API is not the
+ * same as no longer tracking it, and one taken down for a bad release has to be able to come back
+ * current.
+ */
+export async function listRegistry(): Promise<RegistryRow[]> {
+  return marketplaceDb
+    .select({
+      id: plugins.id,
+      appName: plugins.appName,
+      repoUrl: plugins.repoUrl,
+      sourceCommit: pluginMetadata.sourceCommit,
+    })
+    .from(plugins)
+    .leftJoin(pluginMetadata, eq(pluginMetadata.pluginId, plugins.id))
+    .orderBy(plugins.appName);
+}
+
 // ── Writes. Used by the sync script, never by the public API ──

 type RegisterParams = { appName: string; developer: string; repoUrl: string };
@@ -73,6 +73,19 @@ export const pluginMetadata = pgTable(
      .references(() => plugins.id, { onDelete: 'cascade' }),

    version: text('version').notNull(),
+    /**
+     * The git tag this row was read from — what "published" actually means.
+     *
+     * `version` above is the manifest's own claim, and the two are the same string every time somebody
+     * tags correctly. They are kept apart because when they DISAGREE the tag is the fact: it is what was
+     * pushed, and a manifest whose version nobody bumped would otherwise make a real release invisible
+     * to anything comparing versions.
+     *
+     * Nullable because rows existed before releases were the unit of publishing. A null one is a
+     * snapshot taken from a working tree by the old sync, and every consumer should read it as "unknown"
+     * rather than "no release".
+     */
+    releaseTag: text('release_tag'),
    /** The platform range it declares support for, e.g. `>=1.0.0`. */
    platform: text('platform').notNull(),
    label: text('label').notNull(),
@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { proxyOverrideScript, rewriteAssetPaths, rewriteHtml } from './html-rewrite';
+import { proxyOverrideScript, rewriteAssetPaths, rewriteCss, rewriteHtml } from './html-rewrite';

 const BASE = '/api/dev-proxy/3001';
 const attrs = (html: string) => [...html.matchAll(/(?:src|href)="([^"]+)"/g)].map((m) => m[1]!);
@@ -58,6 +58,43 @@ describe('rewriteHtml', () => {
    expect(out.indexOf('<script>')).toBeLessThan(out.indexOf('<title>'));
  });

+  test('every candidate in a srcset is prefixed, descriptors intact', () => {
+    expect(rewriteHtml('<img srcset="/a.webp 96w, /b.webp 320w">', BASE)).toContain(
+      `srcset="${BASE}/a.webp 96w, ${BASE}/b.webp 320w"`,
+    );
+  });
+
+  /*
+    The failure this was found by. An <img> with a srcset also has a src, and the src WAS prefixed — but
+    a browser given a valid srcset picks from it and never reads src. So the logo was missing while the
+    markup looked right.
+  */
+  test('a srcset is chosen over src by the browser, so prefixing src alone is not enough', () => {
+    const out = rewriteHtml('<img src="/logo.webp" srcset="/logo.webp 96w">', BASE);
+    expect(out).toContain(`src="${BASE}/logo.webp"`);
+    expect(out).toContain(`srcset="${BASE}/logo.webp 96w"`);
+  });
+
+  test('a candidate with no descriptor is prefixed too', () => {
+    expect(rewriteHtml('<img srcset="/only.webp">', BASE)).toContain(`srcset="${BASE}/only.webp"`);
+  });
+
+  test('imagesrcset on a preload link is prefixed — the one that is easy to miss', () => {
+    expect(rewriteHtml('<link rel="preload" as="image" imagesrcset="/hero.webp 1280w">', BASE)).toContain(
+      `imagesrcset="${BASE}/hero.webp 1280w"`,
+    );
+  });
+
+  test('a protocol-relative candidate is left alone, like everywhere else here', () => {
+    expect(rewriteHtml('<img srcset="//cdn.example.com/a.webp 96w, /b.webp 320w">', BASE)).toContain(
+      `srcset="//cdn.example.com/a.webp 96w, ${BASE}/b.webp 320w"`,
+    );
+  });
+
+  test('`..` is collapsed in a srcset candidate as well', () => {
+    expect(rewriteHtml('<img srcset="/../../x.webp 96w">', BASE)).toContain(`srcset="${BASE}/x.webp 96w"`);
+  });
+
  test('a query string and hash survive normalisation', () => {
    expect(attrs(rewriteHtml('<script src="/../x.js?v=2#frag">', BASE))).toEqual(['/api/dev-proxy/3001/x.js?v=2#frag']);
  });
@@ -175,3 +212,42 @@ describe('the injected location reporter', () => {
    expect(r.posted).toHaveLength(2);
  });
 });
+
+describe('stylesheets', () => {
+  test('a quoted url is prefixed — the form every generator emits', () => {
+    expect(rewriteCss('@font-face{src:url("/fonts/Averta.woff2") format("woff2")}', BASE)).toContain(
+      `url("${BASE}/fonts/Averta.woff2")`,
+    );
+  });
+
+  test('single quotes and bare urls too', () => {
+    expect(rewriteCss("a{background:url('/bg.png')}", BASE)).toContain(`url('${BASE}/bg.png')`);
+    expect(rewriteCss('a{background:url(/bg.png)}', BASE)).toContain(`url(${BASE}/bg.png)`);
+  });
+
+  test('the quote style is preserved, not normalised', () => {
+    expect(rewriteCss('a{background:url("/bg.png")}', BASE)).not.toContain("url('");
+  });
+
+  test('a url that is already absolute is left alone', () => {
+    const external = 'a{background:url("https://cdn.example.com/bg.png")}';
+    expect(rewriteCss(external, BASE)).toBe(external);
+    const protocolRelative = 'a{background:url("//cdn.example.com/bg.png")}';
+    expect(rewriteCss(protocolRelative, BASE)).toBe(protocolRelative);
+  });
+
+  test('a relative url is left alone — it already resolves against the stylesheet', () => {
+    const relative = 'a{background:url("./bg.png")}';
+    expect(rewriteCss(relative, BASE)).toBe(relative);
+  });
+
+  test('a stylesheet still gets the /_bun/ rule', () => {
+    expect(rewriteCss('@import "/_bun/x.css";', BASE)).toContain(`${BASE}/_bun/x.css`);
+  });
+
+  test('inline CSS in HTML gets the same treatment, quotes included', () => {
+    expect(rewriteHtml('<div style=\'background:url("/a.png")\'></div>', BASE)).toContain(
+      `url("${BASE}/a.png")`,
+    );
+  });
+});
@@ -89,7 +89,38 @@ const normalisePath = (path: string): string => {
 /** `/x` → `<base>/x`, with `..` already collapsed. Never touches `//host` or a full URL. */
 const prefix = (base: string, path: string): string => `${base}${normalisePath(path)}`;

-// HTML: rewrite src/href/action attributes with absolute paths + inject fetch/XHR override
+/**
+ * A `srcset`, which is a LIST and cannot be prefixed as one value.
+ *
+ * `srcset="/a.webp 96w, /b.webp 2x"` — comma-separated candidates, each a URL plus an optional
+ * descriptor. The attribute rule below matches a whole attribute value, so it can only ever have
+ * rewritten the first URL and left the descriptor mangled onto it; it does not match `srcset` at all,
+ * which is why responsive images 404'd silently.
+ *
+ * Silently is the operative word. A `<picture>` or an `<img srcset>` still has a `src`, and that one WAS
+ * prefixed — but a browser given a valid srcset chooses from it and never looks at src. So the markup
+ * appeared correct, one attribute pointed at the platform root, and the image was simply missing.
+ *
+ * Split on commas rather than parsed: a URL cannot contain an unescaped comma in this position, and the
+ * descriptor never does.
+ */
+const prefixSrcset = (base: string, list: string): string =>
+  list
+    .split(',')
+    .map((candidate) => {
+      const trimmed = candidate.trim();
+      if (!trimmed) return '';
+      // The URL is everything up to the first space; the rest is `96w`, `2x`, or nothing.
+      const space = trimmed.search(/\s/);
+      const url = space === -1 ? trimmed : trimmed.slice(0, space);
+      const descriptor = space === -1 ? '' : trimmed.slice(space);
+      // Same rule as everywhere else here: root-absolute only, never protocol-relative.
+      return url.startsWith('/') && !url.startsWith('//') ? `${prefix(base, url)}${descriptor}` : trimmed;
+    })
+    .filter(Boolean)
+    .join(', ');
+
+// HTML: rewrite src/href/action/srcset attributes with absolute paths + inject fetch/XHR override
 export const rewriteHtml = (html: string, base: string) =>
  html
    .replace(/<head([^>]*)>/i, `<head$1>${proxyOverrideScript(base)}`)
@@ -97,12 +128,52 @@ export const rewriteHtml = (html: string, base: string) =>
      /(href|src|action)=("|')(\/(?!\/)[^"']*)\2/gi,
      (_match, attr: string, quote: string, path: string) => `${attr}=${quote}${prefix(base, path)}${quote}`,
    )
-    .replace(/url\((\/(?!\/)[^)"']*)\)/g, (_match, path: string) => `url(${prefix(base, path)})`);
+    /*
+      `srcset` and `imagesrcset`, which the attribute rule above cannot do — see prefixSrcset.

-// JS/CSS: only `/_bun/` paths.
+      `imagesrcset` is the one on `<link rel="preload" as="image">`. It is easy to miss and expensive
+      to miss: a preload that 404s costs a request AND leaves the real image undiscovered until the
+      body is parsed, which is the opposite of what the preload was added for.
+    */
+    .replace(
+      /(imagesrcset|srcset)=("|')([^"']*)\2/gi,
+      (_match, attr: string, quote: string, list: string) => `${attr}=${quote}${prefixSrcset(base, list)}${quote}`,
+    )
+    .replace(CSS_URL, cssUrlPrefixer(base));
+
+/*
+  `url(/…)` — a font, a background image, an `@import`. CSS allows the target bare, single-quoted or
+  double-quoted, and all three mean the same thing, so all three have to match. The quote used is
+  captured and put back rather than normalised: rewriting is not the place to have an opinion about
+  someone else's stylesheet.
+
+  This rule missed every QUOTED url until 2026-08-31, which is a bad way to fail. `url(/x.png)` was
+  rewritten and `url("/x.png")` was not, so whether a stylesheet worked through the proxy came down to
+  the formatting preference of whatever generated it.
+*/
+const CSS_URL = /url\(\s*(["']?)(\/(?!\/)[^)"']*)\1\s*\)/g;
+
+const cssUrlPrefixer =
+  (base: string) =>
+  (_match: string, quote: string, path: string): string =>
+    `url(${quote}${prefix(base, path)}${quote})`;
+
+// JS: only `/_bun/` paths.
 //
 // Deliberately narrow. A blanket rewrite of every absolute path inside JavaScript hits strings that are
 // not URLs — a regex in the source, a route table, anything containing a slash — and corrupts the file it
 // is trying to fix. Bun's dev server emits its chunk imports under `/_bun/`, which is specific enough to
 // match safely. A Vite app instead wants `base` set in its own config; nothing here can guess that.
 export const rewriteAssetPaths = (text: string, base: string) => text.replace(/\/_bun\//g, `${base}/_bun/`);
+
+/*
+  A STYLESHEET gets more than that, because a stylesheet's absolute paths are unambiguous: `url(/…)` is
+  a URL and nothing else, so the argument for being narrow in JavaScript does not apply here.
+
+  This was the whole of it for a long time, and the symptom was specific: a site's own `@font-face` rules
+  kept pointing at `/fonts/…`, which inside the frame is the PLATFORM's root, so every face 404'd and the
+  preview quietly rendered in a system fallback. Nothing looked broken — it just looked like a different
+  site than the one being previewed, which is the one thing a preview must never do.
+*/
+export const rewriteCss = (text: string, base: string) =>
+  rewriteAssetPaths(text, base).replace(CSS_URL, cssUrlPrefixer(base));
@@ -1,7 +1,7 @@
 import { createRouter } from '../../create-router';
 import { resolveAuthToken } from '../../auth-token';
 import { isSuperAdmin } from '../../super-admin';
-import { rewriteAssetPaths, rewriteHtml } from './html-rewrite';
+import { rewriteAssetPaths, rewriteCss, rewriteHtml } from './html-rewrite';

 /**
 * See a dev server running on THIS machine's loopback, from a browser that is somewhere else.
@@ -145,7 +145,8 @@ devProxyRouter.all('/:port/*', async (ctx) => {

  const type = res.headers.get('content-type') ?? '';
  const isHtml = type.includes('text/html');
-  const rewritable = isHtml || type.includes('javascript') || type.includes('text/css');
+  const isCss = type.includes('text/css');
+  const rewritable = isHtml || isCss || type.includes('javascript');

  const headers = new Headers(res.headers);
  // Anything framed here is the owner's own dev server; the platform frames it deliberately.
@@ -169,7 +170,11 @@ devProxyRouter.all('/:port/*', async (ctx) => {
  }

  const text = await res.text();
-  const body = isHtml ? rewriteHtml(text, prefix) : rewriteAssetPaths(text, prefix);
+  const body = isHtml
+    ? rewriteHtml(text, prefix)
+    : isCss
+      ? rewriteCss(text, prefix)
+      : rewriteAssetPaths(text, prefix);
  // Both are wrong after a rewrite: the length changed, and the body was decoded on the way through.
  headers.delete('content-length');
  headers.delete('content-encoding');
@@ -1,6 +1,7 @@
 import { createRouter } from '@@/create-router';
 import { resolve, dirname, join, sep, parse as parsePath } from 'node:path';
-import { readdir, stat, mkdir, rm, rename, readFile, cp } from 'node:fs/promises';
+import { readdir, lstat, readlink, stat, mkdir, rm, rename, readFile, cp } from 'node:fs/promises';
+import type { Dirent } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { getOwnerHomeDir, DATA_PATH } from '@@/data-path';
 import { resolveHomeDir } from '@@/user-home';
@@ -188,9 +189,17 @@ router.get('/ls', async (ctx) => {
    await cleanOldCacheDirs(rootDir);
  }

-  let names: string[];
+  /*
+    `withFileTypes`, so a symlink can be spotted without a second syscall per entry.
+
+    The kind comes off the directory entry itself on every filesystem that reports it, and where it
+    does not Node falls back to an lstat it would otherwise have had to make anyway. `stat` below
+    FOLLOWS the link — which is right, and is why it cannot answer this question: a symlink to a folder
+    must still say `directory` so that opening it works.
+  */
+  let names: Dirent[];
  try {
-    names = await readdir(absPath);
+    names = await readdir(absPath, { withFileTypes: true });
  } catch (ex) {
    // A missing directory resets the browser to the root, which is the right answer for a stale path.
    //
@@ -213,18 +222,44 @@ router.get('/ls', async (ctx) => {
  const claimed = await pluginFileTypes();

  const entries = await Promise.all(
-    names.map(async (name) => {
+    names.map(async (entry) => {
+      const name = entry.name;
      const fullPath = resolve(absPath, name);
      // Skip entries that escape the home dir (shouldn't happen but be safe)
      if (!isInside(rootDir, fullPath)) return null;
+
+      /*
+        Where a link POINTS, exactly as it was written.
+
+        Not resolved to an absolute path: a relative target is a fact about the link, and rewriting it
+        would hide that `../originals` moves with the folder while `/home/…/originals` does not. Only
+        asked for the entries that are links, which in an ordinary folder is none of them.
+      */
+      const target = entry.isSymbolicLink() ? await readlink(fullPath).catch(() => null) : null;
+
      const s = await stat(fullPath).catch(() => null);
-      if (!s) return null;
-      const isDirectory = s.isDirectory();
+
+      /*
+        A BROKEN link still gets a row, and did not before.
+
+        `stat` follows, so a link whose target is gone fails here and the entry returned null — the file
+        vanished from the listing entirely. Nothing said it was there, nothing could delete it, and the
+        folder simply had fewer things in it than `ls` showed. `lstat` describes the link itself, which
+        exists whatever it points at.
+      */
+      const own = s ?? (target !== null ? await lstat(fullPath).catch(() => null) : null);
+      if (!own) return null;
+
+      const isDirectory = s?.isDirectory() ?? false;
      return {
        name,
        type: isDirectory ? 'directory' : 'file',
-        size: s.size,
-        modifiedAt: s.mtimeMs,
+        size: own.size,
+        modifiedAt: own.mtimeMs,
+        /** Where it points, or absent when it is an ordinary file. See the note above. */
+        symlink: target,
+        /** A link whose target is gone. `type` is `file` for want of anything truer to say. */
+        broken: target !== null && s === null ? true : undefined,
        /*
          Whether `/thumb` will produce something, decided HERE so there is one list of extensions
          rather than one on each side of the wire.
@@ -4,7 +4,7 @@ import { isSuperAdmin } from '../../super-admin';
 import { mountPrefix } from '../../plugins/manifest';
 import { snapshotPlugins } from '../../plugins/mount';
 import { manualInstallHint, reportDependencies } from '../../plugins/os-deps';
-import { fetchCatalogue, fetchReadme } from '../../plugins/marketplace';
+import { fetchCatalogue, fetchReadme, publishedTags } from '../../plugins/marketplace';
 import { findOrphanTables } from '../../plugins/orphans';
 import { fetchPlugin } from '../../plugins/fetch';
 import { discoverPlugins } from '../../plugins/discover';
@@ -57,7 +57,9 @@ pluginsRouter.get('/catalogue/:appName/readme', async (ctx) => {
 });

 pluginsRouter.get('/', async (ctx) => {
-  const { states, broken } = await snapshotPlugins();
+  // The catalogue, for the update badge — cached, never throws, and falls back to the git rule per
+  // plugin when the store has nothing to say. See `plugins/release.ts`.
+  const { states, broken } = await snapshotPlugins(await publishedTags());
  // Asked per plugin rather than once, because `pm2 jlist` is a fork and most plugins have no sidecar to
  // ask about. A plugin that is installed and enabled but whose process is not online is the state worth
  // rendering differently — it is the difference between "off" and "broken".
@@ -18,9 +18,14 @@ import { catalogueEntry, listCatalogue } from '../../databases/marketplace_db/sr
 *
 * ── Read-only, and structurally so ──
 *
- * There are two GET routes and no others. Registering a plugin is `scripts/marketplace-sync.ts`, run by
- * hand against the database. That is not a temporary shortcut standing in for a write API: while
- * submissions do not exist, a public write surface is all risk and no feature.
+ * There are two GET routes and no others. Everything that WRITES the catalogue — registering a plugin,
+ * publishing a release — is `scripts/marketplace-sync.ts` against the database, on the one machine that
+ * publishes. That is not a temporary shortcut standing in for a write API: while submissions do not
+ * exist, a public write surface is all risk and no feature.
+ *
+ * It stayed that way when publishing went onto a timer, which is the moment it would have been easy to
+ * add a `POST /api/sync` for a Gitea webhook. A minute of delay is cheaper than a write route on the one
+ * process here that has no login.
 *
 * ── CORS is wide open, deliberately ──
 *
@@ -0,0 +1,301 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  listRegistry,
+  type RegistryRow,
+  upsertMetadata,
+  upsertPlugin,
+} from '../../databases/marketplace_db/src/plugins/queries';
+
+/**
+ * Fill the catalogue from what each plugin has RELEASED.
+ *
+ * ── The bug this file exists to remove ──
+ *
+ * Until 2026-09-03 the sync read `platform/plugins/` — the directories this machine has INSTALLED — and
+ * imported each `manifest.ts` off the working tree. So "publish" meant "make sure officer-dev's checkout
+ * happens to be at the release, then run the script", and nobody could see when it was not. On the day
+ * this was rewritten the live catalogue was advertising four plugins from untagged working copies:
+ * av-club 2026.08.29.01, kanban 2026.08.29.02, openseo 0.1.0 and fofos-admin 2026.08.29.26, none of
+ * which had ever been tagged. The store was describing somebody's afternoon.
+ *
+ * That is also why the old script could not be put on a timer: a cron over it would have published
+ * whatever was sitting in a working tree, on a schedule.
+ *
+ * ── What replaces it: a bare mirror, read at a tag ──
+ *
+ * Every plugin in the registry is mirrored (`git clone --mirror`) into a cache directory, refreshed, and
+ * read AT ITS NEWEST TAG — the manifest, the README, the file list, all out of `git cat-file`. There is
+ * no working tree anywhere in this path, so publishing something uncommitted is not a mistake that can
+ * be made. A mirror is cheap: the whole set clones in a couple of seconds and refreshes in well under
+ * one.
+ *
+ * `docs/marketplace.md` proposed instead reading manifests over Gitea's API, which needed either a
+ * sandbox to evaluate a fetched string or a committed `manifest.json` for every plugin. Git gives the
+ * same guarantee — content at a named release, independent of any checkout — with neither, and the trust
+ * model is unchanged from today: we import our own repositories' code.
+ *
+ * `[still a blocker for third-party submissions]` It is unchanged BECAUSE it is unchanged. Importing a
+ * stranger's manifest is code execution no matter which ref it came from. Submissions still need a
+ * sandbox or a published `manifest.json`.
+ *
+ * ── Which plugins, and where from: the registry, and only the registry ──
+ *
+ * The list comes from the `plugins` table, which `docs/marketplace.md` has always called the
+ * authoritative, hand-curated half. It was not actually being used that way — the old sync discovered
+ * plugins by listing a directory, so the registry was a by-product of whatever officer-dev had
+ * installed. Now it decides, which means:
+ *
+ *   · a plugin nobody has installed here can still be published (`finances` is in exactly that state),
+ *   · a plugin lives wherever its registry row says, across orgs — `fofos-admin` is under `fofos/`,
+ *     not `plugins/`, so an org listing would have missed it,
+ *   · and adding one is a deliberate act: `marketplace-sync.ts --add <https clone url>`.
+ *
+ * ── A plugin with no tag is left ALONE, not removed ──
+ *
+ * It has never made a release, so this file has nothing true to say about it and says nothing: the
+ * existing metadata row stays, and the run reports it. Deleting the row would drop it out of the store
+ * on the day the rule changed, which is a decision about somebody's plugin dressed up as a refresh.
+ * Tagging it is the fix, and the report is there to ask for one.
+ */
+
+export type SyncOutcome =
+  | { appName: string; status: 'synced'; tag: string; version: string }
+  /** The release on the remote is the one already published. Nothing was written. */
+  | { appName: string; status: 'unchanged'; tag: string }
+  | { appName: string; status: 'unreleased' }
+  | { appName: string; status: 'failed'; error: string };
+
+/*
+  Where the mirrors live.
+
+  A fixed path under the user's cache directory, NOT one derived from the environment. This runs three
+  ways — by hand with `--env-file=.env`, from the webhook inside `officer-marketplace`, and from cron —
+  and those three do not have the same environment. A path that moved with `DATA_PATH` would have each
+  of them re-cloning twenty-five repositories into its own copy, and the "is it already mirrored" check
+  would answer differently depending on who asked.
+
+  Not in the source tree, because it is a cache of remote repositories and a `.gitignore` entry is a
+  worse way to keep several hundred megabytes out of a repo than not putting them there.
+*/
+const MIRROR_DIR =
+  process.env.MARKETPLACE_MIRROR_DIR ?? join(homedir(), '.cache', 'officer-marketplace', 'mirrors');
+
+const GIT_TIMEOUT_MS = 60_000;
+
+type Git = { ok: true; out: string } | { ok: false; err: string };
+
+async function git(args: string[], cwd?: string): Promise<Git> {
+  // A missing `cwd` makes posix_spawn fail with ENOENT, which reads as "git is not installed" and sent
+  // a first run of this looking for git for ten minutes. It means the mirror is not there yet.
+  if (cwd && !existsSync(cwd)) return { ok: false, err: `${cwd} does not exist` };
+
+  const proc = Bun.spawn(['git', ...args], {
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    // Never inherited: a mirror fetch that hits a host asking for a password would otherwise sit on a
+    // terminal prompt forever, and in the webhook server there is no terminal to sit on.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '/bin/true' },
+    signal: AbortSignal.timeout(GIT_TIMEOUT_MS),
+  });
+  const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  return (await proc.exited) === 0 ? { ok: true, out: out.trim() } : { ok: false, err: err.trim() || 'git failed' };
+}
+
+/** The mirror for a plugin, cloned if this is the first time and refreshed if it is not. */
+async function mirror(appName: string, repoUrl: string): Promise<string> {
+  mkdirSync(MIRROR_DIR, { recursive: true });
+  const dir = join(MIRROR_DIR, `${appName}.git`);
+
+  // Re-cloned rather than repaired when it is not a healthy bare repo: an interrupted clone leaves a
+  // directory that every later command fails against, and there is nothing in it worth keeping.
+  const existing = await git(['rev-parse', '--is-bare-repository'], dir);
+  if (!existing.ok || existing.out !== 'true') {
+    if (existsSync(dir)) await Bun.$`rm -rf ${dir}`.quiet().nothrow();
+    const cloned = await git(['clone', '--mirror', '--quiet', repoUrl, dir]);
+    if (!cloned.ok) throw new Error(`clone failed: ${cloned.err}`);
+    return dir;
+  }
+
+  // The registry is allowed to move a plugin. Setting the URL every time is one command and removes the
+  // failure where a repo is relocated and the mirror keeps refreshing from where it used to be.
+  await git(['remote', 'set-url', 'origin', repoUrl], dir);
+
+  // `--prune --prune-tags`: a deleted or MOVED tag has to disappear here too. Without it, a tag that was
+  // pushed by mistake and deleted would stay in the mirror forever and could go on being published as
+  // the newest release — a store advertising a version its repository no longer has.
+  const fetched = await git(['fetch', '--quiet', '--prune', '--prune-tags', '--tags', 'origin'], dir);
+  if (!fetched.ok) throw new Error(`fetch failed: ${fetched.err}`);
+  return dir;
+}
+
+/**
+ * The newest release, or null for a plugin that has never made one.
+ *
+ * Asked of git rather than by sorting version strings, which is the same rule `servers/plugins/release.ts`
+ * follows and for the same reason: parsing `2026.08.27.01` works right up until somebody tags `v2`, and
+ * then fails silently. `--abbrev=0` gives the closest tag reachable from HEAD, and a mirror's HEAD is the
+ * remote's default branch, so this is "the newest release on the branch the repository points at".
+ */
+async function newestTag(dir: string): Promise<string | null> {
+  const described = await git(['describe', '--tags', '--abbrev=0', 'HEAD'], dir);
+  return described.ok ? described.out : null;
+}
+
+/** A file at a ref, or null when it is not in that tree. */
+async function fileAt(dir: string, ref: string, path: string): Promise<string | null> {
+  const shown = await git(['cat-file', '-p', `${ref}:${path}`], dir);
+  return shown.ok ? shown.out : null;
+}
+
+/**
+ * The manifest at a release, as an object.
+ *
+ * Written to a temp file and imported, because a manifest is TypeScript. Keyed by the COMMIT, so the
+ * module cache is correct rather than merely convenient: the same commit is the same file, and a tag
+ * moved to a different commit gets a different path and a fresh import. That matters in the webhook
+ * server, which is long-lived and would otherwise serve the first version of a manifest it ever read.
+ *
+ * The `import type { PluginManifest }` at the top of every manifest is erased by the transpiler, so the
+ * file has no runtime dependency on the platform's path aliases and imports fine from anywhere.
+ */
+async function manifestAt(dir: string, ref: string, appName: string, commit: string): Promise<Record<string, unknown>> {
+  const source = await fileAt(dir, ref, 'manifest.ts');
+  if (source === null) throw new Error(`no manifest.ts at ${ref}`);
+
+  const scratch = join(tmpdir(), 'officer-marketplace-manifests');
+  mkdirSync(scratch, { recursive: true });
+  const path = join(scratch, `${appName}-${commit}.ts`);
+  await Bun.write(path, source);
+
+  const mod = (await import(path)) as { manifest?: Record<string, unknown> };
+  if (!mod.manifest) throw new Error(`manifest.ts at ${ref} exports no \`manifest\``);
+  return mod.manifest;
+}
+
+/**
+ * A raw-file URL for a Gitea repository, PINNED TO THE RELEASE.
+ *
+ * It used to be `/raw/HEAD/…`, which works only because Gitea 303s it to `/raw/branch/HEAD/…`; the
+ * artwork it served was whatever was on the default branch, so a plugin could show one icon in the store
+ * and ship another. `/raw/tag/<tag>/…` answers 200 directly and shows the icon that belongs to the
+ * version being advertised.
+ *
+ * `[open]` Still Gitea-shaped. A GitHub-hosted plugin needs the other form, and that wants the forge to
+ * be part of the registry rather than inferred from the URL.
+ */
+function rawUrl(repoUrl: string, tag: string, path: string): string {
+  return `${repoUrl.replace(/\.git$/, '')}/raw/tag/${encodeURIComponent(tag)}/${path}`;
+}
+
+/*
+  `force` re-publishes a release that is already published.
+
+  Needed because "unchanged" is judged on the plugin's commit, and that is only half the input: the other
+  half is THIS file. Change how a field is derived — as the switch to tag-pinned icon URLs did — and every
+  row is stale while every commit still matches. Then the run to fix them all is `--force`.
+*/
+async function syncRegistered(row: RegistryRow, force: boolean): Promise<SyncOutcome> {
+  const { appName, repoUrl } = row;
+  const dir = await mirror(appName, repoUrl);
+
+  const tag = await newestTag(dir);
+  if (!tag) return { appName, status: 'unreleased' };
+
+  const commitAt = await git(['rev-list', '-n', '1', tag], dir);
+  if (!commitAt.ok) throw new Error(`cannot resolve ${tag}`);
+  const commit = commitAt.out;
+
+  // Before the manifest is read, not after: this is what makes a per-minute run affordable. Twenty-five
+  // repositories with nothing new cost one query, twenty-five fetches of nothing, and no writes at all.
+  if (!force && row.sourceCommit === commit) return { appName, status: 'unchanged', tag };
+
+  const manifest = await manifestAt(dir, tag, appName, commit);
+
+  // What the plugin SHIPS, read from the tree at the release rather than from a declaration — the same
+  // rule discovery follows on disk, so a catalogue entry cannot claim a sidecar the release does not
+  // have.
+  const listed = await git(['ls-tree', '-r', '--name-only', tag], dir);
+  const files = new Set(listed.ok ? listed.out.split('\n') : []);
+  const has = {
+    api: files.has('api/router.ts'),
+    schema: files.has('db/schema.ts'),
+    sidecar: files.has('sidecar/index.ts') || files.has('sidecar/index.mjs'),
+    web: [...files].some((f) => f.startsWith('web/')),
+  };
+
+  const readme = (await fileAt(dir, tag, 'README.md')) ?? (await fileAt(dir, tag, 'readme.md'));
+
+  const version = String(manifest.version ?? tag);
+  if (version !== tag) {
+    // Not an error and not corrected here. The tag is what was released and the manifest is what the
+    // plugin will report about itself once installed; when they disagree, an update badge that compares
+    // versions goes quiet. Saying so is the only way anyone finds out.
+    console.warn(`[marketplace-sync] ${appName}: tag ${tag} but manifest says ${version} — they should match`);
+  }
+
+  const developer = String(manifest.publisher ?? 'unknown');
+  const pluginId = await upsertPlugin({ appName, developer, repoUrl });
+
+  await upsertMetadata(pluginId, {
+    version,
+    releaseTag: tag,
+    platform: String(manifest.platform ?? '>=1.0.0'),
+    label: String(manifest.label ?? appName),
+    summary: String(manifest.summary ?? ''),
+    // Taken verbatim, NOT validated here. `manifestProblems` already refuses a tag outside the
+    // vocabulary at discovery, so anything reaching this point is either valid or belongs to a plugin
+    // the platform would not load anyway — and a sync that silently dropped a tag would be a catalogue
+    // quietly disagreeing with the repository it claims to mirror.
+    tags: Array.isArray(manifest.tags) ? manifest.tags : [],
+    color: (manifest.color as string) ?? null,
+    tile: (manifest.tile as string) ?? null,
+    iconUrl: files.has('assets/icon.png') ? rawUrl(repoUrl, tag, 'assets/icon.png') : null,
+    icon: (manifest.icon as string) ?? null,
+    permissions: manifest.permissions ?? [],
+    osDependencies: manifest.osDependencies ?? null,
+    has,
+    readme,
+    sourceCommit: commit,
+  });
+
+  return { appName, status: 'synced', tag, version };
+}
+
+/** One plugin by app name. Unknown to the registry is a failure, not a silent no-op. */
+export async function syncPlugin(appName: string, force = false): Promise<SyncOutcome> {
+  const row = (await listRegistry()).find((r) => r.appName === appName);
+  if (!row) return { appName, status: 'failed', error: 'not in the registry' };
+  return syncRegistered(row, force).catch((err) => ({
+    appName,
+    status: 'failed' as const,
+    error: err instanceof Error ? err.message : String(err),
+  }));
+}
+
+/**
+ * Every registered plugin, one at a time.
+ *
+ * Sequential on purpose. Twenty-four concurrent fetches against one Gitea is a thundering herd for a job
+ * nothing is waiting on, and the whole set finishes in about a second anyway.
+ *
+ * Unlisted rows are included: `listed` hides a plugin from the public API, usually after a bad release,
+ * and it has to be able to come back with current metadata rather than with whatever was true when it
+ * was pulled.
+ */
+export async function syncAll(force = false): Promise<SyncOutcome[]> {
+  const rows = await listRegistry();
+  const out: SyncOutcome[] = [];
+  for (const row of rows) {
+    out.push(
+      await syncRegistered(row, force).catch((err) => ({
+        appName: row.appName,
+        status: 'failed' as const,
+        error: err instanceof Error ? err.message : String(err),
+      })),
+    );
+  }
+  return out;
+}
@@ -98,6 +98,8 @@ function findWeb(
        screens: [
          { segment: null, label: manifest?.label ?? appName, icon: manifest?.icon, art: null, panels, layout },
        ],
+        // Optional and unannounced — presence is the declaration, as it is for panels and layout.
+        fileActions: fileOrNull(join(webDir, 'file-actions.ts')),
      },
    };
  }
@@ -157,7 +159,7 @@ function findWeb(
  }

  if (problems.length) return { web: null, error: `${appName}: ${problems.join('; ')}.` };
-  return { web: { screens } };
+  return { web: { screens, fileActions: fileOrNull(join(webDir, 'file-actions.ts')) } };
 }

 const fileOrNull = (path: string): string | null => (existsSync(path) ? path : null);
@@ -66,6 +66,24 @@ export function generatePluginsModule(states: PluginState[]): string {
  // it always did; caldav has two, so it emits two routes, two layout keys and two dock tiles from one
  // install. The alias counter runs over screens for that reason — two screens of one plugin must not
  // share an import name.
+  /*
+    File-browser actions, one block per PLUGIN rather than per screen.
+
+    The context menu is global — it is the same menu wherever the browser is mounted — so an action
+    belongs to the plugin, not to one of its screens. A plugin with two screens contributes its actions
+    once.
+  */
+  const actionImports: string[] = [];
+  const actionEntries: string[] = [];
+  let a = 0;
+  for (const { plugin } of withWeb) {
+    if (!plugin.web?.fileActions) continue;
+    const alias = `Actions${a}`;
+    a += 1;
+    actionImports.push(`import { fileActions as ${alias} } from '${specifier(plugin.web.fileActions)}';`);
+    actionEntries.push(`  ...${alias},`);
+  }
+
  let i = 0;
  for (const { plugin } of withWeb) {
    for (const screen of plugin.web!.screens) {
@@ -85,8 +103,19 @@ export function generatePluginsModule(states: PluginState[]): string {
  }

  const body = `${HEADER}
-import type { AppRegistryMeta, LayoutNode } from 'officerdev';
+import type { AppRegistryMeta, FileAction, LayoutNode } from 'officerdev';
 ${imports.join('\n')}
+${actionImports.join('\n')}
+
+/**
+ * Context-menu actions plugins contribute to the file browser.
+ *
+ * Flat and global: the menu is the same wherever the browser is mounted, so these are not scoped to a
+ * screen. Each decides for itself whether it applies to what was selected.
+ */
+export const pluginFileActions: FileAction[] = [
+${actionEntries.join('\n')}
+];

 export type GeneratedPlugin = {
  /** The plugin this screen belongs to. Two screens of one plugin share it. */
@@ -523,6 +523,31 @@ export type PluginManifest = {
   */
  hooks?: Partial<Record<string, string>>;

+  /**
+   * An MCP server this plugin serves, offered to the agent as its own.
+   *
+   * ── Why a path and not a URL ──
+   *
+   * The path is under this plugin's own mount, so `/mcp` becomes `/api/<plugin>/mcp` on THIS Officer.
+   * A URL would let a plugin point the agent at any host, and the agent's config carries a token that
+   * signs as the owner — so the one field that must not be free-form is the destination.
+   *
+   * ── Why this exists rather than wrapping the tools ──
+   *
+   * A plugin that fronts something with its own MCP server — openseo is the first — can either
+   * reimplement that vocabulary as Officer tools or hand the real one over. Reimplementing means a
+   * second copy that goes stale, and it fails silently: a tool exists upstream that Officer cannot see.
+   * Handing it over costs this field.
+   *
+   * What a wrapper would have bought — authentication, logging, refusal — is already true of the path,
+   * because the agent reaches it through Officer's own API with Officer's own gate in front. Wrapping
+   * would buy it a second time.
+   */
+  mcp?: {
+    /** Under the plugin's mount. `/mcp` on a plugin mounted at `/api/openseo` is `/api/openseo/mcp`. */
+    path: string;
+  };
+
  osDependencies?: OsDependency[];

  /**
@@ -611,7 +636,20 @@ export type DiscoveredPlugin = {
   * Both files are required when `web/` exists at all. Missing either is a broken plugin, not a plugin
   * with a partial frontend.
   */
-  web: { screens: DiscoveredScreen[] } | null;
+  web: {
+    screens: DiscoveredScreen[];
+    /**
+     * `web/file-actions.ts`, when the plugin has one.
+     *
+     * Presence is the declaration, as with `panels.ts` — the manifest says nothing about it because
+     * there is nothing a human choice adds: an action carries its own label and decides for itself
+     * whether it applies.
+     *
+     * Not per screen. The file browser's context menu is the same menu wherever it is mounted, so an
+     * action belongs to the plugin.
+     */
+    fileActions: string | null;
+  } | null;
 };

 /**
@@ -39,6 +39,15 @@ export type CatalogueEntry = {
  appName: string;
  publisher: string;
  version: string;
+  /**
+   * The git tag this entry was published from — the newest RELEASE, as opposed to whatever a manifest
+   * claims about itself.
+   *
+   * Optional, and absent means "cannot tell" rather than "no release": an older catalogue does not send
+   * the field at all, and a plugin that has never been tagged has nothing to put in it. Both send the
+   * badge back to the git rule.
+   */
+  releaseTag?: string;
  platform: string;
  label: string;
  summary: string;
@@ -556,7 +565,15 @@ const MARKETPLACE_URL = process.env.MARKETPLACE_URL ?? 'https://marketplace.offi
 * plugin published this morning shows up this morning. The cache is per PROCESS and dies with it — a
 * restart is always a fresh look.
 */
-const CACHE_TTL_MS = 5 * 60 * 1000;
+/*
+  One minute, and the number changed when the badge started depending on it.
+
+  Five was fine while this only drew the store's tiles; it is not fine now that "is there an update" is
+  answered from the catalogue, because the wait for a release to appear became the sync's minute PLUS
+  this one. The cost is one small request per process per minute, and only while somebody is looking at
+  a page that lists plugins.
+*/
+const CACHE_TTL_MS = 60 * 1000;

 /**
 * How long to wait for the store before giving up on it.
@@ -639,6 +656,22 @@ export async function fetchCatalogue(): Promise<CatalogueEntry[]> {
  }
 }

+/**
+ * What the store says the newest release of each plugin is, keyed by app name.
+ *
+ * This is the fact the update badge is built on. It replaces every host in the fleet running `git fetch`
+ * against twenty-one repositories to re-derive something the catalogue already knows — see
+ * `plugins/release.ts` for the rule and for what happens to a plugin that has no entry here.
+ *
+ * A missing key and a null value mean the same thing to a caller and are kept apart for the reader: no
+ * entry at all (unregistered, or a store that could not be reached) versus an entry with no release yet.
+ * Both fall through to the git rule, which is the only honest answer when the store cannot speak.
+ */
+export async function publishedTags(): Promise<Map<string, string | null>> {
+  const entries = await fetchCatalogue().catch(() => []);
+  return new Map(entries.map((e) => [e.appName, e.releaseTag ?? null]));
+}
+
 /** One entry by app name, or null. Used by install to find where to clone from. */
 export async function catalogueEntry(appName: string): Promise<CatalogueEntry | null> {
  const all = await fetchCatalogue().catch(() => BUNDLED);
@@ -59,7 +59,13 @@ export type PluginsSnapshot = {
 * the tree while the row stayed, and there is nothing to mount, describe or offer. The row is left in the
 * database on purpose — deleting it here would turn "somebody moved the checkout" into silent data loss.
 */
-export async function snapshotPlugins(): Promise<PluginsSnapshot> {
+/**
+ * @param published Newest released tag per plugin, from the marketplace — `publishedTags()`. Passed by
+ *   the one caller that renders update badges, and by nothing else on purpose: every other caller wants
+ *   "what is on disk", and boot is among them. Making this function fetch the catalogue itself would put
+ *   a network request with a timeout in front of mounting plugins on a machine with no internet.
+ */
+export async function snapshotPlugins(published?: Map<string, string | null>): Promise<PluginsSnapshot> {
  const [{ plugins, broken }, installs] = await Promise.all([discoverPlugins(), listPluginInstalls()]);
  const byName = new Map(installs.map((row) => [row.appName, row]));

@@ -72,7 +78,7 @@ export async function snapshotPlugins(): Promise<PluginsSnapshot> {
        plugin,
        install,
        outdated: !!install && install.version !== plugin.manifest.version,
-        release: await releaseState(plugin.dir),
+        release: await releaseState(plugin.dir, published?.get(plugin.appName) ?? null),
      };
    }),
  );
@@ -1,3 +1,4 @@
+import { existsSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { PLATFORM_DIR } from '../data-path';
 import type { DiscoveredPlugin } from './manifest';
@@ -104,6 +105,32 @@ export async function installNpmDependencies(plugins: DiscoveredPlugin[]): Promi
    return { ok: true, ran: false, output: '', conflicts };
  }

+  /*
+  Packages the PLATFORM owns, which a plugin may never bring its own copy of.
+
+  React holds module-level state — the hook dispatcher — so two copies in one page is not a duplicated
+  dependency, it is a broken one. The second instance's `useRef` reads a null dispatcher and every panel
+  fails to render with "Cannot read properties of null (reading 'useRef')", which names nothing that
+  would lead somebody here.
+
+  It is easy to arrive at by accident and hard to diagnose: nobody asks for React. `@tiptap/react`
+  declares it as a PEER, bun installs peers, and the copy lands in plugins/node_modules where it wins
+  resolution for everything under it. That took the fofos-admin screen down the moment tiptap arrived.
+
+  Stripped rather than pinned. Matching the platform's version would still be two copies, and two copies
+  is the whole problem — bun resolves up the tree, so removing them entirely is what makes a plugin use
+  the one the platform already loaded.
+
+  Removed AFTER the install as well as before it, and the second is the one that does the work: no
+  plugin declares React, so there is nothing to strip from the merged list. It arrives as a PEER of
+  something that does, which bun installs and the generated file never mentions.
+*/
+const PLATFORM_OWNED = ['react', 'react-dom'];
+
+  for (const owned of PLATFORM_OWNED) {
+    if (owned in merged) delete merged[owned];
+  }
+
 const body = {
    name: '@officer/plugin-dependencies',
    private: true,
@@ -117,7 +144,26 @@ export async function installNpmDependencies(plugins: DiscoveredPlugin[]): Promi
    const proc = Bun.spawn(['bun', 'install'], { cwd: PLUGINS_DIR, stdout: 'pipe', stderr: 'pipe' });
    const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
    const code = await proc.exited;
-    return { ok: code === 0, ran: true, output: `${out}${err}`.trim(), conflicts };
+
+    /*
+      Evict the platform's singletons, however they got here.
+
+      This is the step that matters. Stripping the merged list above only covers a plugin ASKING for
+      React, and none do — it arrives as a peer of something that does, so bun installs it without the
+      generated file ever naming it. Deleting it afterwards is crude and it is deterministic, which is
+      the right trade for a failure whose symptom is every panel on a screen refusing to render.
+    */
+    const evicted: string[] = [];
+    for (const owned of PLATFORM_OWNED) {
+      const path = join(PLUGINS_DIR, 'node_modules', owned);
+      if (existsSync(path)) {
+        rmSync(path, { recursive: true, force: true });
+        evicted.push(owned);
+      }
+    }
+
+    const note = evicted.length ? `\nremoved ${evicted.join(', ')} — the platform owns those` : '';
+    return { ok: code === 0, ran: true, output: `${out}${err}${note}`.trim(), conflicts };
  } catch (error) {
    return { ok: false, ran: true, output: error instanceof Error ? error.message : String(error), conflicts };
  }
@@ -135,12 +181,31 @@ export async function installNpmDependencies(plugins: DiscoveredPlugin[]): Promi
 export function unresolvableDependencies(plugin: DiscoveredPlugin): string[] {
  const names = Object.keys(plugin.manifest.npmDependencies ?? {});
  return names.filter((name) => {
+    // The strong check: it imports. This is what catches a package that installed but cannot be loaded
+    // on this machine — `sharp` resolving to a platform-specific binary is the shape it was written for.
    try {
      Bun.resolveSync(name, plugin.dir);
      return false;
    } catch {
-      return true;
+      // fall through
    }
+
+    /*
+      Some packages have NO root entry point, and that is not a fault.
+
+      `@tiptap/pm` declares no `main`, no `module`, and an `exports` map with no `"."` — it exists only as
+      subpaths, and you import `@tiptap/pm/state`, never `@tiptap/pm`. Asked to resolve the bare name,
+      Bun correctly says it cannot, and the check above read that as a broken install.
+
+      It cost a deploy: fofos-admin declares `@tiptap/pm` because tiptap needs it present, the install
+      was perfect — the directory, its dist and thirteen prosemirror packages all there — and the plugin
+      was reported as failed on every host that had it.
+
+      So a package that does not resolve is asked the weaker question instead: is it THERE. Present but
+      unimportable still fails, because the strong check ran first and only a package with no root entry
+      reaches this line.
+    */
+    return !existsSync(join(PLUGINS_DIR, 'node_modules', name, 'package.json'));
  });
 }

@@ -94,6 +94,61 @@ describe('releaseState', () => {
    expect(s.updateable).toBe(true);
  });

+  /*
+    The catalogue path. These are the ones that matter now: a host no longer fetches to find out what the
+    newest release is, so every assertion below is about the store's tag winning over local refs — and
+    about the fallback still being there when it has nothing to say.
+  */
+  test('the published tag decides, without the checkout having ever fetched it', async () => {
+    const { work, origin, clone } = pair('published-newer');
+
+    // The clone is at v1 and has NEVER seen v2 — no fetch, no remote ref for it. Exactly the state a
+    // host is in a minute after somebody else tagged a release.
+    publish(work, origin, 'two', 'v1');
+    git(clone, 'fetch', '-q', '--tags', 'origin');
+    git(clone, 'checkout', '-q', 'v1');
+
+    const s = await releaseState(clone, 'v2');
+    expect(s.tagAtHead).toBe('v1');
+    expect(s.newestTag).toBe('v2');
+    expect(s.updateable).toBe(true);
+    expect(s.reason).toBe('new-release');
+  });
+
+  test('the published tag matching HEAD is up to date', async () => {
+    const { work, origin, clone } = pair('published-same');
+    publish(work, origin, 'two', 'v1');
+    git(clone, 'fetch', '-q', '--tags', 'origin');
+    git(clone, 'checkout', '-q', 'v1');
+
+    const s = await releaseState(clone, 'v1');
+    expect(s.updateable).toBe(false);
+    expect(s.reason).toBe('at-latest');
+  });
+
+  test('an untagged checkout is updateable AND says what it would land on', async () => {
+    const { clone } = pair('published-untagged');
+    const s = await releaseState(clone, 'v9');
+    expect(s.tagAtHead).toBeNull();
+    // The old code returned null here, so the button read "Update" with nothing after it.
+    expect(s.newestTag).toBe('v9');
+    expect(s.updateable).toBe(true);
+    expect(s.reason).toBe('untagged');
+  });
+
+  test('no published tag falls back to the git rule rather than to a guess', async () => {
+    const { work, origin, clone } = pair('no-entry');
+    publish(work, origin, 'two', 'v1');
+    git(clone, 'fetch', '-q', '--tags', 'origin');
+    git(clone, 'checkout', '-q', 'v1');
+
+    // Null, as it is for a plugin nobody registered or a store that could not be reached.
+    const s = await releaseState(clone, null);
+    expect(s.tagAtHead).toBe('v1');
+    expect(s.newestTag).toBe('v1');
+    expect(s.updateable).toBe(false);
+  });
+
  test('a directory that is not a checkout is not updateable', async () => {
    const d = join(root, 'plain');
    mkdirSync(d, { recursive: true });
@@ -29,12 +29,32 @@ import { join } from 'node:path';
 * is that tag, this checkout is at the latest release. If it is a different one, the remote has moved on.
 * That holds for any tag names anyone ever chooses, including ones that do not sort.
 *
- * ── What this does NOT do ──
+ * ── Where "the newest tag" comes from: the catalogue, not this machine's refs ──
 *
- * It never fetches. Every answer comes from refs already on disk, because this is called once per plugin
- * on a request that renders a list — twenty-one network round trips would make the plugins screen feel
- * broken. Tags arrive at clone and at the fetch `pullPlugin` already does, so "check for updates" is a
- * consequence of updating rather than a separate poll.
+ * Every answer here is local, and this is called once per plugin on a request that renders a list —
+ * twenty-one network round trips would make the plugins screen feel broken. That left one hard problem:
+ * refs on disk go stale. Tags arrived at clone and at the fetch `pullPlugin` does, so you learned an
+ * update existed BY UPDATING. A machine that had not touched a plugin since August compared this
+ * morning's release against a snapshot from before it existed and said, truthfully and uselessly, that
+ * it was at the latest.
+ *
+ * That was patched with a rate-limited background `git fetch` per checkout, which worked and was the
+ * wrong shape: every host in the fleet polling twenty-one repositories to re-derive a fact one place
+ * already knows. The marketplace publishes releases now — see `servers/marketplace/sync.ts` — so the
+ * newest release is simply asked of the catalogue, which every host already fetches for the store.
+ *
+ *   published tag (catalogue)  vs  tag at HEAD (this checkout)   →  differ, so there is an update
+ *
+ * DIFFERENCE, not ordering. `2026.08.27.01` parses fine until somebody tags `v2`, and then it fails
+ * silently. Two strings that are not equal is a comparison that cannot rot.
+ *
+ * ── The git rule stays, for a plugin the store cannot speak for ──
+ *
+ * A checkout of something unpublished — a plugin being written, one never registered — has no catalogue
+ * entry, and the fallback below is the old rule against local remote-tracking refs. Those refs are no
+ * longer refreshed here, so for that case this can miss a tag until something else fetches. That is the
+ * accepted cost: the alternative was every machine polling every repository forever to cover a case that
+ * only arises on a developer's own box, where `git fetch` is a thing they were about to run anyway.
 */

 export type ReleaseState = {
@@ -53,7 +73,12 @@ const run = async (dir: string, args: string[]): Promise<string | null> => {
  return (await proc.exited) === 0 ? out.trim() || null : null;
 };

-export async function releaseState(dir: string): Promise<ReleaseState> {
+/**
+ * @param publishedTag The tag the marketplace says is this plugin's newest release, or null when the
+ *   catalogue has nothing to say — an unregistered plugin, one never tagged, or a store that could not
+ *   be reached. Null falls through to the git rule rather than to a guess.
+ */
+export async function releaseState(dir: string, publishedTag: string | null = null): Promise<ReleaseState> {
  const none = { tagAtHead: null, newestTag: null };
  if (!existsSync(join(dir, '.git'))) {
    // Copied in by hand or bundled. Nothing to compare, and nothing to pull either — `pullPlugin` says
@@ -64,6 +89,16 @@ export async function releaseState(dir: string): Promise<ReleaseState> {
  // `--exact-match`, so this is "the tag AT this commit", not "the last tag before it". Fails, and
  // therefore returns null, when HEAD is between releases — which is the first half of the rule.
  const tagAtHead = await run(dir, ['describe', '--exact-match', '--tags', 'HEAD']);
+
+  if (publishedTag) {
+    // Reported even when HEAD is untagged, so the UI can say what pressing Update lands on. The old
+    // code returned a bare null here and the button read "Update" with nothing after it.
+    if (!tagAtHead) return { tagAtHead: null, newestTag: publishedTag, updateable: true, reason: 'untagged' };
+    return publishedTag === tagAtHead
+      ? { tagAtHead, newestTag: publishedTag, updateable: false, reason: 'at-latest' }
+      : { tagAtHead, newestTag: publishedTag, updateable: true, reason: 'new-release' };
+  }
+
  if (!tagAtHead) return { ...none, updateable: true, reason: 'untagged' };

  // Asked of the REMOTE branch, not of HEAD: a tag pushed after this checkout was made is not reachable
@@ -1,4 +1,5 @@
 import { existsSync, readdirSync } from 'node:fs';
+import { publishedTags } from './marketplace';
 import { releaseState } from './release';
 import { join } from 'node:path';
 import { PLUGINS_DIR } from './discover';
@@ -144,7 +145,10 @@ export async function updatePlugin(

    Checked BEFORE the pull, because a pull is what would make the answer stale.
  */
-  const state = await releaseState(join(PLUGINS_DIR, appName));
+  // Against the CATALOGUE, like the badge. Without it this asked local remote-tracking refs, which are
+  // no longer refreshed in the background — so a plugin at the latest tag it knows about would have
+  // short-circuited here and told the owner it was up to date without checking anything.
+  const state = await releaseState(join(PLUGINS_DIR, appName), (await publishedTags()).get(appName) ?? null);
  if (!state.updateable && state.reason === 'at-latest') {
    steps.push(`already at ${state.tagAtHead}, the newest release`);
    onStep?.(steps[steps.length - 1]!);
@@ -18,6 +18,8 @@ import { createSidecarConnector } from '../connect';
 import { sign } from '../../jwt';
 import { getUserByEmail, getOwnerUser } from 'officerdb';
 import { DATA_PATH, findEmailAccountName } from '../../data-path';
+import { listPluginInstalls } from 'officerdb';
+import { discoverPlugins } from '../../plugins/discover';
 import { API_URL, OFFICER_API_URL, ANTHROPIC_PROXY_URL } from '../../officer-url.mjs';

 // PM2 starts this sidecar with no user in its env, so resolve the owner from the database rather than
@@ -140,7 +142,7 @@ loadState(dbUser.id);

 // ── MCP config ──

-function generateMcpConfig(): string {
+async function generateMcpConfig(): Promise<string> {
  // Was `.container-context`, from the architecture where each user ran inside their own Docker
  // container and this directory described that container to the agent. Nothing about it is
  // container-related now — it holds exactly one file, the MCP server config handed to the CLI. The
@@ -152,8 +154,45 @@ function generateMcpConfig(): string {
  const userRoot = join(DATA_PATH, email!);

  const hostToolsDirs = [globalToolsDir, ...(existsSync(userToolsDir) ? [userToolsDir] : [])].join(':');
+
+  /*
+    MCP servers contributed by plugins.
+
+    A plugin that fronts something with its own MCP server can either reimplement that vocabulary as
+    Officer tools or hand the real one over. Reimplementing means a second copy that goes stale, and it
+    fails silently — a tool exists upstream that Officer cannot see. Handing it over costs this block.
+
+    The plugin declares a PATH, never a URL, and it is resolved against this Officer's own API. That is
+    the whole safety property: the config below carries `OFFICER_AUTH_TOKEN`, a token that signs as the
+    owner, so a manifest able to name an arbitrary host would be a manifest able to post the owner's
+    credential anywhere. A path can only ever reach this machine, through this machine's own gate.
+
+    Installed AND enabled, because a disabled plugin's routes are not mounted — offering the agent a
+    tool list that 404s is worse than not offering it.
+  */
+  const pluginMcpServers: Record<string, { type: 'http'; url: string; headers: Record<string, string> }> = {};
+  try {
+    const [installs, discovered] = await Promise.all([listPluginInstalls(), discoverPlugins()]);
+    const live = new Set(installs.filter((entry) => entry.enabled).map((entry) => entry.appName));
+
+    for (const plugin of discovered.plugins) {
+      const declared = plugin.manifest?.mcp?.path;
+      if (!declared || !live.has(plugin.appName)) continue;
+      const path = declared.startsWith('/') ? declared : `/${declared}`;
+      pluginMcpServers[plugin.appName] = {
+        type: 'http',
+        url: `${OFFICER_API_URL}/api/${plugin.appName}${path}`,
+        headers: { Authorization: `Bearer ${OFFICER_AUTH_TOKEN}` },
+      };
+    }
+  } catch {
+    // A plugin that cannot be read must not stop an agent from starting. It loses its MCP tools for this
+    // session and everything else works, which is the right side to fail on.
+  }
+
  const hostConfig = {
    mcpServers: {
+      ...pluginMcpServers,
      'officer-tools': {
        type: 'stdio',
        command: 'bun',
@@ -236,7 +275,13 @@ function ensureAnthropicEnv(): void {
 // deliberately not written — it would pollute the personal global ~/.claude/CLAUDE.md that the
 // terminal `claude` loads too.

-setMcpConfigPath(generateMcpConfig());
+/*
+  Awaited, because the config now asks the database which plugins are installed.
+
+  Not fire-and-forget: `setMcpConfigPath` is what the agent manager reads when it spawns, so a config
+  that arrives after the first spawn is an agent running without its plugin tools and no sign of why.
+*/
+setMcpConfigPath(await generateMcpConfig());
 ensureAnthropicEnv();

 console.log(`[agent] started for ${email} (HOME=${homeDir})`);
@@ -6,7 +6,7 @@ import { TaskRunnerDialog } from './components/TaskRunnerDialog';
 import { AgentRunnerDialog } from './components/AgentRunnerDialog';
 import { VideoDownloadDialog } from './components/VideoDownloadDialog';
 import { DictateDialog } from './components/DictateDialog';
-import { useFileBrowserApp } from './useFileBrowserApp';
+import { useFileBrowserApp, type PickedFile } from './useFileBrowserApp';

 type FileBrowserAppProps = {
  basePath?: string;
@@ -27,6 +27,14 @@ type FileBrowserAppProps = {
   * where the folder is the URL and already does.
   */
  panelId?: string;
+  /**
+   * Turn this into a CHOOSER: opening a file hands it back instead of opening a viewer.
+   *
+   * Folders still navigate, because choosing a file means getting to it. A prop rather than a second
+   * component — a picker built separately is a listing, a breadcrumb, a sort, thumbnails and keyboard
+   * handling reimplemented, all of it free to drift from the real browser.
+   */
+  onPickFile?: (file: PickedFile) => void;
 };

 export const FileBrowserApp = ({
@@ -36,8 +44,9 @@ export const FileBrowserApp = ({
  urlPath,
  panelId,
  pathParam,
+  onPickFile,
 }: FileBrowserAppProps) => {
-  const fileBrowserManager = useFileBrowserApp(basePath, rootOverride, urlPath, panelId, pathParam);
+  const fileBrowserManager = useFileBrowserApp(basePath, rootOverride, urlPath, panelId, pathParam, onPickFile);
  const { handleNavigate } = fileBrowserManager;

  return (
@@ -4,6 +4,8 @@ import { ChevronUp, ChevronDown } from 'lucide-react';
 import type { DirEntry } from '../../../../hooks/useFilesAPI';
 import { getFileType } from '../../../FileViewer';
 import type { UseFileBrowserAppType } from '../useFileBrowserApp';
+import { useClient } from 'hooks/useClient';
+import { fileActionsFor } from '../../file-actions';
 import { FileItem } from './FileItem';
 import { useTranslation } from '../../../../locales';

@@ -61,6 +63,8 @@ const useColumnCount = (scrollRef: React.RefObject<HTMLDivElement | null>) => {

 export const FileGrid = ({ fileBrowserManager }: FileGridProps) => {
  const { t } = useTranslation();
+  // For plugin actions: `run` is outside React and cannot call the hook itself.
+  const client = useClient();
  const {
    visibleEntries: entries,
    viewMode,
@@ -68,6 +72,7 @@ export const FileGrid = ({ fileBrowserManager }: FileGridProps) => {
    rootOverride,
    selected,
    clipboard,
+    refresh,
    handleOpen,
    handleDelete,
    handleRename,
@@ -167,8 +172,23 @@ export const FileGrid = ({ fileBrowserManager }: FileGridProps) => {
  const cols = useColumnCount(scrollRef);
  const cutPaths = clipboard?.mode === 'cut' ? new Set(clipboard.paths) : new Set<string>();
  const anySelected = selected.size > 0;
+
  const entryPath = (name: string) => (currentPath === '/' ? `/${name}` : `${currentPath}/${name}`);

+  const pluginActionsFor = (entry: DirEntry) => {
+    const names = selected.has(entry.name) && selected.size > 1 ? [...selected] : [entry.name];
+    const payload = entries
+      .filter((candidate) => names.includes(candidate.name))
+      .map((candidate) => ({ name: candidate.name, path: entryPath(candidate.name), type: candidate.type }));
+
+    return fileActionsFor(payload).map((action) => ({
+      key: action.key,
+      label: action.label,
+      Icon: action.icon,
+      onClick: () => action.run(payload, { currentPath, refresh, client }),
+    }));
+  };
+
  const rowCount = viewMode === 'list' ? sorted.length : Math.ceil(sorted.length / cols);

  const virtualizer = useVirtualizer({
@@ -269,6 +289,14 @@ export const FileGrid = ({ fileBrowserManager }: FileGridProps) => {
      onReadAloud={handleReadAloud}
      onExtract={handleExtract}
      taskGroups={getMatchingTaskGroups(entry.name, entry.type)}
+      /*
+        Plugin actions, resolved here because this is where the SELECTION lives.
+
+        An action receives the whole selection when the right-clicked item is part of one, and just
+        that item otherwise — what every file manager does. Acting on a selection the click was not
+        part of is the surprising alternative.
+      */
+      pluginActions={pluginActionsFor(entry)}
      onRunTask={handleRunTask}
      agentGroups={getMatchingAgentGroups(entry.name, entry.type)}
      onRunAgent={handleRunAgent}
@@ -277,6 +305,8 @@ export const FileGrid = ({ fileBrowserManager }: FileGridProps) => {
      onCompress={handleCompress}
      onDuplicate={handleDuplicate}
      onPasteInto={handlePasteInto}
+      onDragStart={fileBrowserManager.handleEntryDragStart}
+      onDropInto={fileBrowserManager.handleEntryDrop}
      onTogglePin={handleTogglePin}
      isPinned={isPinned(entryPath(entry.name))}
      canPaste={clipboard !== null}
@@ -1,6 +1,7 @@
 import { useState, useEffect, useRef } from 'react';
 import {
  Folder,
+  Link2,
  Trash2,
  Pencil,
  MoreVertical,
@@ -23,6 +24,7 @@ import {
  FileArchive,
  Pin,
  PinOff,
+  Sparkles,
 } from 'lucide-react';
 import { getIcon } from 'material-file-icons';
 import { Thumbnail } from './Thumbnail';
@@ -84,9 +86,25 @@ export type FileItemProps = {
  onRunAgent: (agent: AgentSummary, entry: DirEntry) => void;
  onCreateDashboard: (entry: DirEntry) => void;
  onOpenInEditor: (entry: DirEntry) => void;
+  /**
+   * Context-menu actions contributed by plugins, already resolved against the selection.
+   *
+   * Resolved by the caller, not here: whether an action receives one entry or the whole selection is a
+   * question about the SELECTION, which this component does not have and should not need.
+   */
+  pluginActions?: { key: string; label: string; Icon?: React.ComponentType<{ className?: string }>; onClick: () => void }[];
  onCompress: (entry: DirEntry) => void;
  onDuplicate: (entry: DirEntry) => void;
  onPasteInto: (entry: DirEntry) => void;
+  /**
+   * Dragging this row, and dropping onto it.
+   *
+   * A custom MIME type on the DataTransfer survives between windows of the same browser, which is what
+   * makes "drag from one Officer window into another" work at all. See useFileBrowserApp for the type
+   * and why `Files` is left alone.
+   */
+  onDragStart: (ev: React.DragEvent, entry: DirEntry) => void;
+  onDropInto: (ev: React.DragEvent, entry: DirEntry) => Promise<void>;
  onTogglePin: (entry: DirEntry) => void;
  isPinned: boolean;
  canPaste: boolean;
@@ -177,6 +195,7 @@ type MenuItemsProps = {
  canPaste: boolean;
  onOpen: (e: DirEntry) => void;
  onOpenInEditor: (e: DirEntry) => void;
+  pluginActions?: { key: string; label: string; Icon?: React.ComponentType<{ className?: string }>; onClick: () => void }[];
  onDelete: (e: DirEntry) => void;
  onStartRename: () => void;
  onChat: (e: DirEntry) => void;
@@ -212,6 +231,7 @@ const MenuItems = ({
  canPaste,
  onOpen,
  onOpenInEditor,
+  pluginActions,
  onDelete,
  onStartRename,
  onChat,
@@ -254,7 +274,7 @@ const MenuItems = ({

  const hasTasks = taskGroups.length > 0;
  const hasAgents = agentGroups.length > 0;
-  const hasActions = showReadAloud || showExtract || hasTasks || hasAgents;
+  const hasActions = showReadAloud || showExtract || hasTasks || hasAgents || Boolean(pluginActions?.length);
  // Only nest when more than one category matched — a file usually matches a single category, and
  // Run Task > Video > Convert would just add a hop.
  const nestTasks = taskGroups.length > 1;
@@ -305,6 +325,14 @@ const MenuItems = ({
          {t('files.menu.extract')}
        </Item>
      )}
+      {/* Plugin actions, flat rather than nested. There are few of them and each is one click; a
+          submenu for two items is a hop that buys nothing. */}
+      {pluginActions?.map((action) => (
+        <Item key={action.key} onClick={action.onClick} className="cursor-pointer">
+          {action.Icon ? <action.Icon className="mr-2 h-4 w-4" /> : <Sparkles className="mr-2 h-4 w-4" />}
+          {action.label}
+        </Item>
+      ))}
      {hasTasks && (
        <Sub>
          <SubTrigger className="cursor-pointer">
@@ -565,6 +593,7 @@ export const FileItem = ({
  viewMode,
  selected,
  anySelected,
+  pluginActions,
  selectedCount,
  isCut,
  onOpen,
@@ -589,6 +618,8 @@ export const FileItem = ({
  onCompress,
  onDuplicate,
  onPasteInto,
+  onDragStart,
+  onDropInto,
  onTogglePin,
  isPinned,
  canPaste,
@@ -601,6 +632,21 @@ export const FileItem = ({
  const clickTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const isDir = entry.type === 'directory';

+  /*
+    A link, and where it goes.
+
+    Drawn as an arrow beside the name rather than as a badge or a different icon: the icon already says
+    what the thing IS — a folder, a photograph — and a symlink to a folder is still a folder to anyone
+    using it. What the arrow adds is that there is an indirection in the way, which is the thing that
+    explains why deleting it did not free any space, or why two places show the same file.
+
+    The target goes in `title`. It is often long and absolute, so it belongs in a tooltip rather than in
+    a row that has to fit a name, a type, a size and a date.
+  */
+  const linkLabel = entry.symlink
+    ? `${entry.broken ? 'Broken symlink' : 'Symlink'} → ${entry.symlink}`
+    : undefined;
+
  const icon = isDir ? (
    <Folder className="h-5 w-5 text-duck-yellow fill-duck-yellow/30" />
  ) : (
@@ -735,6 +781,10 @@ export const FileItem = ({
    onCreateDashboard,
    onOpen,
    onOpenInEditor,
+    // Typed on both ends and forwarded by neither, which is why "Create Gallery" was in the bundle and
+    // not in the menu. `menuProps` is assembled field by field, so a new prop is not carried by being
+    // declared.
+    pluginActions,
    onCompress,
    onDuplicate,
    onPasteInto,
@@ -757,6 +807,24 @@ export const FileItem = ({
            onClick={handleClick}
            onDoubleClick={handleDoubleClick}
            onPointerDown={(ev) => ev.stopPropagation()}
+            draggable
+            onDragStart={(ev) => onDragStart(ev, entry)}
+            /*
+              A folder is a drop target; a file is not. `onDragOver` must preventDefault or the browser
+              refuses the drop entirely — that is the single line whose absence makes a target look
+              dead, with no error anywhere.
+
+              `dropEffect` is set here rather than at dragstart because only the target knows whether
+              it can accept: the cursor says "move" over a folder and "no" over a file, which is the
+              only feedback a drag has.
+            */
+            onDragOver={(ev) => {
+              if (entry.type !== 'directory' || !ev.dataTransfer.types.includes('application/x-officer-files')) return;
+              ev.preventDefault();
+              ev.stopPropagation();
+              ev.dataTransfer.dropEffect = 'move';
+            }}
+            onDrop={(ev) => void onDropInto(ev, entry)}
          >
            <Checkbox checked={selected} anySelected={anySelected} onClick={(ev) => onSelect(entry, ev)} />
            <span className="shrink-0">{listVisual}</span>
@@ -768,7 +836,18 @@ export const FileItem = ({
                  onCancel={() => setRenaming(false)}
                />
              ) : (
-                <span className="text-sm font-medium text-duck-dark truncate block">{entry.name}</span>
+                <span className="flex min-w-0 items-center gap-1">
+                  <span className="truncate text-sm font-medium text-duck-dark">{entry.name}</span>
+                  {linkLabel && (
+                    <span
+                      title={linkLabel}
+                      aria-label={linkLabel}
+                      className={`shrink-0 leading-none ${entry.broken ? 'text-destructive' : 'text-duck-dark/45'}`}
+                    >
+                      <Link2 className="h-3.5 w-3.5" />
+                    </span>
+                  )}
+                </span>
              )}
            </div>
            <span className="hidden md:inline text-xs text-duck-dark/50 shrink-0 w-20 text-right">
@@ -804,6 +883,15 @@ export const FileItem = ({
          onClick={handleClick}
          onDoubleClick={handleDoubleClick}
          onPointerDown={(ev) => ev.stopPropagation()}
+          draggable
+          onDragStart={(ev) => onDragStart(ev, entry)}
+          onDragOver={(ev) => {
+            if (entry.type !== 'directory' || !ev.dataTransfer.types.includes('application/x-officer-files')) return;
+            ev.preventDefault();
+            ev.stopPropagation();
+            ev.dataTransfer.dropEffect = 'move';
+          }}
+          onDrop={(ev) => void onDropInto(ev, entry)}
        >
          <div className="absolute top-1 left-1">
            <Checkbox checked={selected} anySelected={anySelected} onClick={(ev) => onSelect(entry, ev)} />
@@ -825,7 +913,18 @@ export const FileItem = ({
                onCancel={() => setRenaming(false)}
              />
            ) : (
-              <span className="w-full truncate text-center text-sm font-medium text-duck-dark">{entry.name}</span>
+              <span className="flex w-full min-w-0 items-center justify-center gap-1">
+                <span className="truncate text-center text-sm font-medium text-duck-dark">{entry.name}</span>
+                {linkLabel && (
+                  <span
+                    title={linkLabel}
+                    aria-label={linkLabel}
+                    className={`shrink-0 leading-none ${entry.broken ? 'text-destructive' : 'text-duck-dark/45'}`}
+                  >
+                    <Link2 className="h-3.5 w-3.5" />
+                  </span>
+                )}
+              </span>
            )}

            <span className="text-xs text-duck-dark/50">
@@ -1,5 +1,5 @@
 import { useRef } from 'react';
-import { FolderPlus, Upload, FolderUp, ClipboardPaste } from 'lucide-react';
+import { FolderPlus, Upload, FolderUp, ClipboardPaste, X } from 'lucide-react';
 import type { UseFileBrowserAppType } from '../../useFileBrowserApp';
 import { useTranslation } from '../../../../../locales';

@@ -9,7 +9,7 @@ type DefaultActionsProps = {

 export const DefaultActions = ({ fileBrowserManager }: DefaultActionsProps) => {
  const { t } = useTranslation();
-  const { setNewEntry, handleUpload, clipboard, handlePaste } = fileBrowserManager;
+  const { setNewEntry, handleUpload, clipboard, handlePaste, setClipboard } = fileBrowserManager;
  const fileInputRef = useRef<HTMLInputElement | null>(null);
  const folderInputRef = useRef<HTMLInputElement | null>(null);

@@ -56,14 +56,39 @@ export const DefaultActions = ({ fileBrowserManager }: DefaultActionsProps) => {
        />
      </button>

+      {/*
+        What is on the clipboard, said out loud.
+
+        It used to be an icon and a toast. That was enough while the clipboard died with the tab — you
+        had just pressed the key, so you knew what was on it. Now it is per-user and survives reloads,
+        tabs and days, which means somebody can arrive at a folder with three files pending from
+        yesterday and paste them without ever having been told. Invisible persistent state is how a
+        file gets moved by accident.
+
+        So it says how many and whether they will be copied or moved, and offers a way to let go of
+        them. `cut` is worth distinguishing in the label rather than only in the icon: it is the one
+        that takes the originals with it.
+      */}
      {clipboard !== null && (
+        <div className="flex items-center gap-0.5 rounded-md bg-duck-dark/5 pl-2">
+          <span className="text-xs text-duck-teal whitespace-nowrap">
+            {clipboard.paths.length} {clipboard.mode === 'cut' ? t('files.toMove') : t('files.toCopy')}
+          </span>
          <button
            onClick={handlePaste}
            title={t('files.menu.paste')}
-          className="p-1.5 rounded-md text-duck-teal hover:bg-duck-dark/5 cursor-pointer transition-colors"
+            className="p-1.5 rounded-md text-duck-teal hover:bg-duck-dark/10 cursor-pointer transition-colors"
          >
            <ClipboardPaste className="h-4 w-4" />
          </button>
+          <button
+            onClick={() => setClipboard(null)}
+            title={t('files.clearClipboard')}
+            className="p-1.5 rounded-md text-duck-teal/60 hover:bg-duck-dark/10 hover:text-duck-teal cursor-pointer transition-colors"
+          >
+            <X className="h-3.5 w-3.5" />
+          </button>
+        </div>
      )}
    </>
  );
@@ -213,7 +213,11 @@ export const VideoDownloadDialog = ({ fileBrowserManager }: VideoDownloadDialogP
            </div>
          </form>
        ) : (
-          <div className="flex flex-col gap-3">
+          // `min-w-0` on the DIRECT grid child. DialogContent is a grid, and a grid item defaults to
+          // `min-width: auto` — so this is the element that grows to fit a long title and takes the
+          // card out of the dialog with it. The constraint has to be here; on the scroll container
+          // inside it was one level too low to stop anything.
+          <div className="flex min-w-0 flex-col gap-3">
            <div className="flex items-center justify-between gap-2">
              <button
                type="button"
@@ -248,7 +252,19 @@ export const VideoDownloadDialog = ({ fileBrowserManager }: VideoDownloadDialogP
              </div>
            )}

-            <div className="flex max-h-[52vh] flex-col gap-2 overflow-y-auto pr-1">
+            {/*
+              `min-w-0` is the one that makes `truncate` work, three levels down.
+
+              DialogContent is a GRID, and a grid item defaults to `min-width: auto` — it refuses to
+              shrink below its content. So a long title pushed this container wider than the dialog's
+              own `max-w-lg`, the card grew with it, and the `truncate` on the title never had a width
+              to truncate against. The text simply ran out of the modal.
+
+              Making the card a column fixed a different half of this and was not enough: a column still
+              cannot be narrower than the widest thing a grid will let it be. The constraint has to come
+              from above, and this is the highest point where it was missing.
+            */}
+            <div className="flex max-h-[52vh] min-w-0 flex-col gap-2 overflow-y-auto pr-1">
              {entries.map((e, i) => (
                <div
                  key={`${e.url}-${i}`}
@@ -10,6 +10,7 @@ import { folderFromPathname, folderHref, relativeToFolder, withoutViewerParams }
 import { useTasks, runsWithoutPrompting, type TaskSummary } from '../useTasks';
 import { useAgents, type AgentSummary } from '../useAgents';
 import { useUserState } from 'state/useUserState';
+import { useQueryClient } from '@tanstack/react-query';
 import { useAuth } from 'hooks/useAuth';
 import { useClient } from 'hooks/useClient';
 import { runTaskNow } from './components/runTaskNow';
@@ -36,12 +37,17 @@ export const FILES_PATH_PARAM = 'path';
 * not fill the back stack, and no pathname involved at all. A reload lands where you were and the link
 * can be sent to somebody, which is what was actually wanted.
 */
+/** What a picker is handed when somebody opens a file in pick mode. */
+export type PickedFile = { name: string; path: string; type: string };
+
 export const useFileBrowserApp = (
  basePath: string,
  rootOverride?: string,
  urlPath = false,
  panelId?: string,
  pathParam?: string,
+  /** Set to turn this into a chooser: opening a file calls this instead of a viewer. */
+  onPickFile?: (file: PickedFile) => void,
 ) => {
  const { t } = useTranslation();
  const { user } = useAuth();
@@ -192,7 +198,25 @@ export const useFileBrowserApp = (
  const { togglePin, isPinned } = usePinnedFiles();
  const [uploadProgress, setUploadProgress] = useState<number | null>(null);
  const [selected, setSelected] = useState<Set<string>>(new Set());
-  const [clipboard, setClipboard] = useState<ClipboardState>(null);
+  /*
+    The clipboard lives on the SERVER, not in this component.
+
+    ── Why ──
+
+    It was `useState`, which meant it existed in one tab and died with it. Copying in one window and
+    pasting in another — the obvious way to move a file between two folders you can both see — did
+    nothing, and a reload lost a pending cut with no sign that it had.
+
+    `user_state` is a per-user JSONB row that already exists for exactly this kind of thing, and
+    `useUserState` already reads and writes it through React Query with an optimistic local update. So
+    a clipboard is one key in it and there is no new table, route or socket.
+
+    Per user rather than per browser, deliberately: cutting on the desktop and pasting on the phone is
+    the same gesture across two screens, and there is no reading of "my clipboard" where the two should
+    disagree.
+  */
+  const queryClient = useQueryClient();
+  const [clipboard, setClipboard] = useUserState<ClipboardState>('fileClipboard', null);
  const [renamingName, setRenamingName] = useState<string | null>(null);
  const [searchQuery, setSearchQuery] = useState('');
  const [searchResults, setSearchResults] = useState<DirEntry[] | null>(null);
@@ -223,6 +247,10 @@ export const useFileBrowserApp = (
  filesRef.current = files;
  const currentPathRef = useRef(currentPath);
  currentPathRef.current = currentPath;
+  // Read inside `refresh`, which is not re-created per render and would otherwise close over a
+  // stale list the first time it ran.
+  const entriesRef = useRef(entries);
+  entriesRef.current = entries;
  const visibleEntries = showHidden ? entries : entries.filter((e) => !e.name.startsWith('.'));

  const entryPath = (name: string) => (currentPath === '/' ? `/${name}` : `${currentPath}/${name}`);
@@ -230,8 +258,29 @@ export const useFileBrowserApp = (

  const firstListing = useRef(true);

+  /**
+   * The folder the entries currently on screen belong to.
+   *
+   * What separates "re-read this folder" from "go to a different one", which look identical from
+   * inside `refresh` and need opposite treatment — see below.
+   */
+  const shownPath = useRef<string | null>(null);
+
  const refresh = async () => {
-    setLoading(true);
+    /*
+      Blank the list only when there is nothing true to show.
+
+      `loading` swaps the whole grid for a spinner, which is right when arriving somewhere new and
+      wrong when re-reading a folder already on screen: every refresh — after a paste, after a delete,
+      and now every time the window comes forward — made the contents vanish and come back. On a
+      folder of a hundred files that is a flash and a lost scroll position, for information that was
+      already correct.
+
+      So the spinner is for a folder we cannot yet show: nothing listed, or a different folder than the
+      one listed. Re-reading the same folder leaves what is there until better information arrives, and
+      the only visible change is whatever actually changed.
+    */
+    if (entriesRef.current.length === 0 || shownPath.current !== currentPathRef.current) setLoading(true);
    try {
      const data = await filesRef.current.listDir(currentPathRef.current);
      if (data.reset) {
@@ -239,6 +288,7 @@ export const useFileBrowserApp = (
        return;
      }
      setEntries(data.entries);
+      shownPath.current = currentPathRef.current;
      if (data.rootDir) setRootDir(data.rootDir);
    } catch (err: any) {
      console.error('[FileBrowser] refresh error:', err);
@@ -302,6 +352,50 @@ export const useFileBrowserApp = (
    };
  }, [searchQuery]);

+  /*
+    Pull the clipboard again whenever this window comes forward.
+
+    `useUserState` holds USER_STATE with `staleTime: Infinity` — right for a dock layout, wrong for
+    something another window can change while this one is idle. Without this, window A cuts, window B
+    still shows nothing to paste, and the feature reads as broken in exactly the case it was built for.
+
+    Focus rather than a poll or a socket, and that is a judgement rather than a shortcut: pasting into
+    the other window means focusing the other window first, so the refresh happens at precisely the
+    moment it is needed and never while nobody is looking. A socket would be live for a case that does
+    not arise — two visible windows dragging between each other already carry the paths in the drag
+    itself.
+
+    `visibilitychange` as well as `focus`, because a background tab brought forward by switching tabs
+    fires only the second one in some browsers.
+  */
+  /*
+    ...and the FOLDER as well as the clipboard.
+
+    Cutting in one window and pasting in another moves the file on disk, and the window it left went on
+    listing it until somebody pressed refresh. The clipboard was the obvious half of "these two windows
+    disagree"; the listing is the half that matters more, because a file that is not there any more is
+    a lie rather than a stale label.
+
+    Held in a ref because `refreshRef.current` is rebuilt on every render — putting it in the
+    dependency array would tear down and re-add both listeners several times a second.
+  */
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+
+  useEffect(() => {
+    const onForeground = () => {
+      if (document.visibilityState !== 'visible') return;
+      void queryClient.invalidateQueries({ queryKey: ['USER_STATE'] });
+      void refreshRef.current();
+    };
+    window.addEventListener('focus', onForeground);
+    document.addEventListener('visibilitychange', onForeground);
+    return () => {
+      window.removeEventListener('focus', onForeground);
+      document.removeEventListener('visibilitychange', onForeground);
+    };
+  }, [queryClient]);
+
  // Clipboard image paste
  useEffect(() => {
    const handler = (ev: ClipboardEvent) => {
@@ -475,6 +569,21 @@ export const useFileBrowserApp = (
      setCurrentPath(next);
      return;
    }
+    /*
+      PICK MODE.
+
+      When a caller is using this browser to CHOOSE a file rather than to work in a folder, opening a
+      file means handing it back — not opening a viewer the caller would then have to close. Folders
+      still navigate above, because choosing a file requires getting to it.
+
+      A prop rather than a second browser: a picker built separately would be a listing, a breadcrumb,
+      a sort, thumbnails and keyboard handling reimplemented, all of it drifting from the real one.
+      This is the same component with one branch.
+    */
+    if (onPickFile) {
+      onPickFile({ name: entry.name, path: entryPath(entry.name), type: entry.type });
+      return;
+    }
    // An archive extracts rather than opening a pane. The viewer has nothing to show for one — it renders
    // a placeholder reading "Archive file" and the name you can already see in the listing — so a pane
    // was a step on the way to the only thing anyone opens a zip for. Extract resolves collisions, so a
@@ -970,6 +1079,78 @@ export const useFileBrowserApp = (
    }
  };

+  /*
+    Dragging rows between windows.
+
+    ── The MIME type is the whole trick ──
+
+    A custom type on the DataTransfer survives between tabs and windows of the SAME browser, which is
+    the case somebody actually has: two Officer windows side by side, one folder in each. It does not
+    survive between different browsers, and it cannot exchange with Finder — dragging out to the
+    desktop needs a Chrome-only API and only works outward.
+
+    `Files` is deliberately untouched. That is the type the OS puts on a real file drag, and the
+    existing upload path keys off it; a drag from inside carries only ours, so the two never meet.
+
+    ── It also writes the clipboard ──
+
+    Belt and braces, and cheap now that the clipboard is per-user server state: if a drop lands
+    somewhere that cannot read the payload, the paths are still held and a paste finishes the job. The
+    drag becomes a gesture over the same mechanism rather than a second one beside it.
+  */
+  const DRAG_TYPE = 'application/x-officer-files';
+
+  const handleEntryDragStart = (ev: React.DragEvent, entry: DirEntry) => {
+    // Dragging one of several selected rows takes the whole selection; dragging an unselected row
+    // takes just that one, which is what every file manager does and what a hand expects.
+    const paths = selected.has(entry.name)
+      ? [...selected].map((name) => entryPath(name))
+      : [entryPath(entry.name)];
+
+    ev.dataTransfer.setData(DRAG_TYPE, JSON.stringify(paths));
+    // `move` so the cursor shows what will happen. The drop decides for real; this is the hint.
+    ev.dataTransfer.effectAllowed = 'move';
+    setClipboard({ paths, mode: 'cut' });
+  };
+
+  /** Paths from a drag that started in an Officer window, or null if this is something else. */
+  const draggedPaths = (ev: React.DragEvent): string[] | null => {
+    if (!ev.dataTransfer.types.includes(DRAG_TYPE)) return null;
+    try {
+      const parsed = JSON.parse(ev.dataTransfer.getData(DRAG_TYPE));
+      return Array.isArray(parsed) && parsed.every((p) => typeof p === 'string') ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+
+  /**
+   * Drop onto a folder row — move into it.
+   *
+   * Refuses a folder being dropped into itself or into its own child, which the server would reject
+   * anyway but with an error rather than a shrug. Comparing with a trailing separator so `/a/bc` is
+   * not read as living inside `/a/b`.
+   */
+  const handleEntryDrop = async (ev: React.DragEvent, entry: DirEntry) => {
+    const paths = draggedPaths(ev);
+    if (!paths || entry.type !== 'directory') return;
+    ev.preventDefault();
+    ev.stopPropagation();
+
+    const destination = entryPath(entry.name);
+    const into = paths.filter((path) => destination !== path && !destination.startsWith(`${path}/`));
+    if (into.length === 0) return;
+
+    try {
+      await files.move(into, destination);
+      setClipboard(null);
+      await refresh();
+      toast.success(t('files.pastedItems', { count: into.length }));
+    } catch {
+      toast.error(t('files.pasteFailed'));
+    }
+  };
+
  const handleDragEnter = (ev: React.DragEvent) => {
    ev.preventDefault();
    dragCounter.current++;
@@ -995,6 +1176,28 @@ export const useFileBrowserApp = (
    dragCounter.current = 0;
    setDragging(false);

+    /*
+      A drag that began in an Officer window, dropped on this folder's background.
+
+      Checked before the upload path, because a drag from inside carries no `Files` and would
+      otherwise fall through to "read the dropped files", find none, and do nothing at all.
+    */
+    const dragged = draggedPaths(ev);
+    if (dragged) {
+      const into = dragged.filter((path) => currentPath !== path && !currentPath.startsWith(`${path}/`));
+      // Dropping a folder into the folder it already lives in. Nothing to do, and nothing to say.
+      if (into.length === 0) return;
+      try {
+        await files.move(into, currentPath);
+        setClipboard(null);
+        await refresh();
+        toast.success(t('files.pastedItems', { count: into.length }));
+      } catch {
+        toast.error(t('files.pasteFailed'));
+      }
+      return;
+    }
+
    const items = ev.dataTransfer.items;
    if (!items || items.length === 0) return;

@@ -1088,7 +1291,12 @@ export const useFileBrowserApp = (
    // Selection
    selected,
    setSelected,
+    handleEntryDragStart,
+    handleEntryDrop,
    clipboard,
+    // Exposed so the toolbar can let go of what is held. It is per-user state now, so a stale
+    // clipboard is something a person has to be able to clear rather than wait out.
+    setClipboard,
    renamingName,
    setRenamingName,
    // Search
@@ -0,0 +1,103 @@
+/**
+ * Actions a PLUGIN contributes to the file browser's context menu.
+ *
+ * ── Why this exists beside tasks ──
+ *
+ * A task already reaches that menu, and for "do this to these files" it is the right thing: it runs a
+ * script as the owner, reports through the job system, and needs no frontend at all.
+ *
+ * It is the wrong shape for anything that continues in the interface. "Create Gallery" from a folder is
+ * not a job to watch — it is a name to type and a screen to land on, and expressing that as a script
+ * would mean a job whose only output is somewhere to go next.
+ *
+ * So: a plugin exports `fileActions` from `web/file-actions.ts`, the generated plugin module collects
+ * them, and the menu renders the ones that apply. Presence on disk is the declaration, exactly as
+ * `panels.ts` and `layout.ts` already are.
+ *
+ * ── They run in the BROWSER ──
+ *
+ * Which is the whole difference. An action gets the selection and does what a panel would do — open a
+ * dialog, call its own plugin's API, navigate. It has no privileges of its own: everything it calls
+ * goes through the same permission gate as every other request that page makes.
+ */
+
+/** One entry the action was invoked on. */
+export type FileActionEntry = {
+  name: string;
+  /** Absolute within the browser's root, as the browser addresses it. */
+  path: string;
+  type: 'file' | 'directory';
+};
+
+export type FileActionContext = {
+  /** The folder currently open, so an action can act on "here" rather than on a selection. */
+  currentPath: string;
+  /** Re-read the listing. For an action that creates or removes something on disk. */
+  refresh: () => void;
+  /**
+   * An authenticated client for Officer's API, rooted at `/api`.
+   *
+   * Handed over rather than left to the action, because there is no way for it to build one: `run` is
+   * called from an event handler outside React, so it cannot use `useClient`, and a bare `fetch` gets a
+   * 401 — this API authenticates with a bearer token, not a cookie, and only the hook holds it.
+   */
+  client: {
+    get: <T>(url: string) => Promise<T>;
+    post: <T>(url: string, payload?: unknown) => Promise<T>;
+    put: <T>(url: string, payload?: unknown) => Promise<T>;
+    delete: <T>(url: string, payload?: unknown) => Promise<T>;
+  };
+};
+
+export type FileAction = {
+  /** Unique across every plugin. Prefixed with the plugin name by convention, like panel keys. */
+  key: string;
+  label: string;
+  /** A lucide icon component, as the rest of the menu uses. */
+  icon?: React.ComponentType<{ className?: string }>;
+  /**
+   * Whether this action makes sense for what was selected.
+   *
+   * Given EVERY entry the action would receive, so an action that only handles images can refuse a
+   * mixed selection rather than half-working. Returning false hides it — a menu of greyed-out items
+   * nobody can explain is worse than a shorter menu.
+   */
+  appliesTo: (entries: FileActionEntry[]) => boolean;
+  run: (entries: FileActionEntry[], context: FileActionContext) => void;
+};
+
+/**
+ * The registry, filled by the app at startup.
+ *
+ * ── Why injection rather than an import ──
+ *
+ * The generated plugin module lives in the APP (`src/apps/officer-web/Plugins.gen.tsx`) and this is a
+ * workspace package the app depends on. Importing it from here would point the dependency backwards and
+ * make this package unusable by anything that is not Officer's own frontend.
+ *
+ * So the package owns the list and the app hands it over — one call, at startup, before anything
+ * renders a file browser.
+ */
+let registered: FileAction[] = [];
+
+export const registerFileActions = (actions: FileAction[]): void => {
+  registered = actions;
+};
+
+/**
+ * The actions that apply to this selection, in registration order.
+ *
+ * `entries` is what the action would receive: the whole selection when the right-clicked item is part
+ * of a multiple selection, and just that item otherwise. That is what every file manager does, and the
+ * alternative — acting on a selection the click was not part of — is the surprising one.
+ */
+export const fileActionsFor = (entries: FileActionEntry[]): FileAction[] =>
+  registered.filter((action) => {
+    try {
+      return action.appliesTo(entries);
+    } catch {
+      // A plugin's predicate that throws hides its own action rather than breaking the menu for
+      // everything else on it.
+      return false;
+    }
+  });
@@ -9,6 +9,7 @@ export { useTasks, type TaskSummary } from './useTasks';
 export { useRecentFiles } from './useRecentFiles';
 export { usePinnedFiles } from './usePinnedFiles';
 export { FileBrowserApp, FileBrowserPanelWrapper } from './FileBrowserApp';
+export type { PickedFile } from './FileBrowserApp/useFileBrowserApp';
 export { FileBrowserWidget } from './FileBrowserWidget';
 export { TaskRunnerModal } from './FileBrowserApp/components/TaskRunnerModal';

@@ -27,3 +28,5 @@ export const appRegistryMetas: AppRegistryMeta[] = [
    availableOnPanel: false,
  },
 ];
+export type { FileAction, FileActionEntry, FileActionContext } from './file-actions';
+export { registerFileActions, fileActionsFor } from './file-actions';
@@ -534,9 +534,11 @@ export const PluginDetail = () => {
                how you teach someone to stop pressing it. */}
            {plugin.updateable && (
              <Button disabled={busy} onClick={() => run('update', plugin.appName)}>
-                {plugin.releaseReason === 'new-release' && plugin.newestTag
-                  ? `Update to ${plugin.newestTag}`
-                  : 'Update'}
+                {/* Named whenever a release is known, not only on `new-release`. An untagged checkout
+                    reports `untagged`, and it used to lose the destination with it — the button said
+                    "Update" and the owner had to guess where it landed. The marketplace knows the newest
+                    release even for a checkout that has never fetched it. */}
+                {plugin.newestTag ? `Update to ${plugin.newestTag}` : 'Update'}
              </Button>
            )}
            {/* Said out loud rather than shown as an absent button. "No Update button" and "up to date"
@@ -205,6 +205,20 @@ export type DirEntry = {
   * response, which simply means no thumbnail — the file icon, exactly as before.
   */
  thumb?: 'image' | 'video' | null;
+  /**
+   * Where this points, when it is a symlink — exactly as the link was written.
+   *
+   * Relative targets stay relative. `../originals` and `/home/…/originals` behave differently when the
+   * folder moves, and resolving one into the other would hide the difference at the moment somebody is
+   * looking to understand it.
+   *
+   * `type` still describes the TARGET, so a link to a folder opens like a folder. This says only that
+   * there is a link in the way. Absent on an older response, which reads as "not a link" — the same
+   * thing every entry said before.
+   */
+  symlink?: string | null;
+  /** The target is gone. The row is drawn anyway, because the link itself is really there. */
+  broken?: boolean;
 };

 type ListDirResponse = {
@@ -59,6 +59,9 @@ export {
  useRecentFiles,
  usePinnedFiles,
  FileBrowserApp,
+  registerFileActions,
+  type FileAction,
+  type PickedFile,
  FileBrowserPanelWrapper,
  FileBrowserWidget,
  TaskRunnerModal,
@@ -542,7 +542,10 @@
      "type": "Typ",
      "size": "Größe",
      "date": "Datum"
-    }
+    },
+    "toCopy": "zu kopieren",
+    "toMove": "zu verschieben",
+    "clearClipboard": "Zwischenablage leeren"
  },
  "taskRunner": {
    "stop": "Stopp",
@@ -542,7 +542,10 @@
      "type": "Type",
      "size": "Size",
      "date": "Date"
-    }
+    },
+    "toCopy": "to copy",
+    "toMove": "to move",
+    "clearClipboard": "Clear clipboard"
  },
  "taskRunner": {
    "stop": "Stop",
@@ -542,7 +542,10 @@
      "type": "Tipo",
      "size": "Tamaño",
      "date": "Fecha"
-    }
+    },
+    "toCopy": "para copiar",
+    "toMove": "para mover",
+    "clearClipboard": "Vaciar portapapeles"
  },
  "taskRunner": {
    "stop": "Detener",
@@ -542,7 +542,10 @@
      "type": "Type",
      "size": "Taille",
      "date": "Date"
-    }
+    },
+    "toCopy": "à copier",
+    "toMove": "à déplacer",
+    "clearClipboard": "Vider le presse-papiers"
  },
  "taskRunner": {
    "stop": "Arrêter",
@@ -542,7 +542,10 @@
      "type": "Tipo",
      "size": "Tamanho",
      "date": "Data"
-    }
+    },
+    "toCopy": "a copiar",
+    "toMove": "a mover",
+    "clearClipboard": "Limpar área de transferência"
  },
  "taskRunner": {
    "stop": "Parar",
@@ -542,7 +542,10 @@
      "type": "Typ",
      "size": "Storlek",
      "date": "Datum"
-    }
+    },
+    "toCopy": "att kopiera",
+    "toMove": "att flytta",
+    "clearClipboard": "Töm urklipp"
  },
  "taskRunner": {
    "stop": "Stoppa",
@@ -2,6 +2,15 @@ export { useSettings, DEFAULT_SETTINGS } from './useSettings';
 export type { UseSettingsType, UserSettings, UserState } from './useSettings';
 export { useUserState } from './useUserState';
 export { useDashboardState } from './useDashboardState';
+/*
+  Exported for a workspace nested INSIDE a panel — see plugins/fofos-admin/web/WorkPanel.tsx.
+
+  `useDashboardState` persists the whole tree, which is right for a dashboard somebody arranged and
+  wrong for a layout its author ships: the structure would be frozen at whatever it was the first time
+  a screen was opened. `useAuthoredLayout` keeps the structure in source and persists only sizes and
+  zoom, which is what a nested authored layout wants for the same reason `PluginScreen` does.
+*/
+export { useAuthoredLayout } from './useAuthoredLayout';
 export { useModels, useVisibleModels, useUserVisibleModels, useEnabledModels, modelKey } from './useModels';
 export type { ModelOption } from './useModels';
 export { useAccessPolicy } from './useAccessPolicy';
@@ -204,6 +204,51 @@
    background-attachment: fixed;
    background-size: cover;
  }
+
+  /*
+    NATIVE CONTROLS FOLLOW THE THEME.
+    ------------------------------------------------------------------------------------------
+
+    Nothing here set `color-scheme`, so the browser drew every control it renders itself as if the page
+    were light — on a dark theme, a `<select>`'s dropdown opened as a white sheet with the page's own
+    pale text on it. Unreadable, and unreachable by any utility class, because that list is painted by
+    the browser and is not in the document.
+
+    `color-scheme` is the only thing that reaches it. It also fixes, for free, the other controls with
+    no styleable interior: date and colour pickers, the spinner on a number input, and default
+    scrollbars where a theme has not replaced them.
+
+    ── Why the `dark` class decides it ──
+
+    It is the signal that exists. 203 of the 231 themes set `applyDarkClass`, and the provider puts the
+    class on <html> beside `data-theme`, so the two are always in agreement about the same element.
+    Both are specificity 0-1-0 and themes are imported after this file, so a theme that disagrees can
+    simply say so — this is a default, not a decision taken away.
+
+    ── And the explicit colours underneath ──
+
+    `color-scheme` gives the browser's generic dark, not the theme's. Where a browser honours colours on
+    `<option>` — Firefox, and Chrome on Linux and Windows — these make the list the theme's own popover
+    surface instead. Where it does not (Safari, Chrome on macOS, which use a genuinely native menu), the
+    scheme above is what carries it, and generic dark is a great deal better than white-on-white.
+
+    A utility still wins: these are base-layer rules, so `bg-transparent` on a select behaves exactly as
+    it did.
+  */
+  :root {
+    color-scheme: light;
+  }
+
+  .dark {
+    color-scheme: dark;
+  }
+
+  select,
+  option,
+  optgroup {
+    background-color: var(--popover);
+    color: var(--popover-foreground);
+  }
 }

 /*