step 4/4: the docs say permissions too, and capability means one thing again

44 files of prose — CLAUDE.md, AGENTS.md, TODO.md, 20 docs, both plugin design
documents, and the comment surface the earlier steps could not reach.

Applied against an explicit keep-list, not swept, because the word turned out to
have SIX meanings in this repository rather than the three the offscale doc
recorded:

  permissions          renamed (steps 1–2)
  $OFFICER_ROOT/capabilities/  KEPT — the item store, and now the only thing
                               the word means that is ours
  sidecar routing keys renamed to `handles` (step 3)
  Lightning wallet     KEPT — a domain term, and on the wire to the mobile apps
  terminfo queries     KEPT — XTGETTCAP, in the pty sidecar
  InvoiceShelf         KEPT — per-resource { write, bulkDelete } flags

The sweep still falsified two things, both caught by checking rather than by
review, and both in prose that discusses more than one meaning at once:

CLAUDE.md began claiming the item store lives at `$OFFICER_ROOT/permissions`.
It does not; that directory is on disk and full of skills and tools.

And the offscale doc's own note about the collision became
"Named `permissions`, NOT `permissions`" — a sentence that had eaten the thing
it existed to warn about.

Both restored, and the note rewritten to say what is now true: capability means
one thing of ours, and three that belong to somebody else's vocabulary.

Verified live after restart: self and admin permission endpoints 200, gated
route 200, agent-status 200, 9 grants intact with 6 permissions offered.
tsgo clean, 797 tests, 787 pass, same 7.

The rename is done. Four steps, no data lost, no client break that survived
the step it was introduced in.

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

@@ -23,7 +23,7 @@ const LOG_POLL_MS = 1500;
 const isTerminal = (s: string) => s === 'completed' || s === 'failed' || s === 'stopped' || s === 'interrupted';
 
 // A script may publish counter-style progress via the `@@officer:progress@@` sentinel (e.g. the
-// download-media capability). When shaped like that, render the two phase bars above the log.
+// download-media permission). When shaped like that, render the two phase bars above the log.
 const isDownloadProgress = (p: unknown): p is DownloadProgress =>
   !!p && typeof p === 'object' && 'meta' in p && 'dl' in p;
 

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

@@ -160,7 +160,7 @@ import {
  * The dock items that belong to the SHELL — present on every install, with no sidecar behind them.
  *
  * Everything else is contributed by an installed sidecar's UI manifest and arrives from
- * `/capabilities` at runtime (see `dockItemsFromPlugins`). The split is the point: a feature that can be
+ * `/permissions` at runtime (see `dockItemsFromPlugins`). The split is the point: a feature that can be
  * installed and uninstalled must not be hardcoded here, or the dock would list things this server does
  * not have and the shell would need editing every time a sidecar is added.
  *

src/databases/officer_db/src/app-store/schema.ts

@@ -13,7 +13,7 @@ import { pgTable, serial, text, boolean, timestamp, jsonb, uniqueIndex } from 'd
 // Gitea is the worked example. The owner installs it once, and the row here says the process runs; each
 // member then holds their own credential in `service_connections`, inheriting the instance URL from the
 // owner's row. A member can therefore use a service without being able to install, uninstall or point it
-// somewhere else — which is the same split `capabilities/registry.ts` already draws between `app` and
+// somewhere else — which is the same split `permissions/registry.ts` already draws between `app` and
 // `admin` kinds.
 //
 // ── Why `installed` and `enabled` are separate ──

src/servers/api/users/permissions-routes.ts

@@ -109,7 +109,7 @@ permissionAdminRouter.get('/permissions', ownerGate, async (ctx) => {
     // database refuses a row for that role.
     roles: USER_ROLES.filter((r) => r !== 'Super Admin'),
     // The column is `permission` now too, so this is a straight pass-through again. It was briefly a
-    // mapping — the wire said `permission` while the column still said `capability` — which is what let
+    // mapping — the wire said `permission` while the column still said `permission` — which is what let
     // the table be renamed without any client noticing.
     grants: await getAllRoleGrants(),
   });

src/servers/plugins/manifest.ts

@@ -16,10 +16,14 @@
 /**
  * A permission the plugin adds to the platform's permission system.
  *
- * Called `permissions`, and that word is used throughout the plugin system deliberately. The other one
- * already means three different things here — the permission registry, the file-based item store under
- * `$OFFICER_ROOT/permissions`, and the routing keys a sidecar registers with — and a fourth meaning
- * would be one too many. Nothing in this system uses it.
+ * Called `permissions`, and the plugin system used that word first — before the platform did. On
+ * 2026-08-15 the rest of the codebase followed: the registry moved to `permissions/`, its table to
+ * `role_permissions`, and the sidecar's routing keys became `handles`.
+ *
+ * `capability` now means exactly one thing, the file-based item store under `$OFFICER_ROOT/capabilities`
+ * — skills, tools, tasks. Three other uses survive because they are somebody else's vocabulary rather
+ * than ours: the wallet's Lightning backend features, the pty sidecar's terminfo queries, and
+ * InvoiceShelf's per-resource flags.
  */
 export type PluginPermission = {
   /** Stable identifier, stored as the grant's subject. Renaming one is a data change. */

src/servers/sidecar-registry.test.ts

@@ -28,7 +28,7 @@ afterEach(() => {
   while (registered.length) unregisterSidecar(registered.pop()!);
 });
 
-/** Wait until a request has actually reached the socket — spawnClaude awaits waitForCapability first. */
+/** Wait until a request has actually reached the socket — spawnClaude awaits waitForPermission first. */
 async function awaitSend(socket: { sent: string[] }): Promise<void> {
   for (let i = 0; i < 50 && socket.sent.length === 0; i++) await Bun.sleep(1);
   expect(socket.sent).not.toHaveLength(0);

src/servers/sidecar/claude/user-instance.ts

@@ -25,7 +25,7 @@ import { API_URL, OFFICER_API_URL, ANTHROPIC_PROXY_URL } from '../../officer-url
 // this process can work. CLAUDE_USER_EMAIL still wins when set, for manual runs.
 //
 // "The owner" is not a simplification that multi-user will later invalidate. `chat` is an `execution`
-// capability (capabilities/registry.ts) and is never grantable at any level, so no account other than
+// permission (permissions/registry.ts) and is never grantable at any level, so no account other than
 // the owner can ever reach this sidecar, however many accounts exist.
 //
 // ── Why this retries rather than throws ──
@@ -79,7 +79,7 @@ const OFFICER_AUTH_TOKEN = await sign({ id: dbUser.id, email, username: dbUser.u
 // The owner runs Claude with no isolation — real HOME, real ~/.claude — so platform sessions have
 // perfect parity with terminal sessions (same config, credentials and transcript store,
 // interchangeable via `claude --resume`). That absence of isolation is precisely why `chat` is an
-// `execution` capability and can never be granted: this is a shell, not a feature flag.
+// `execution` permission and can never be granted: this is a shell, not a feature flag.
 // Evaluated here, ABOVE the `process.env.HOME = homeDir` below: homedir() reads $HOME, so a
 // read placed after that assignment would return whatever was last spawned into.
 const homeDir = homedir();

src/servers/sidecar/notify/resolve-user.test.ts

@@ -11,7 +11,7 @@ describe('resolveNotifyUser', () => {
   });
 
   // The regression this module exists for: `body.userId ?? header` let any account holding the
-  // `notify` capability push to any other account's devices by naming them in a JSON body.
+  // `notify` permission push to any other account's devices by naming them in a JSON body.
   test('the header beats a conflicting body userId', () => {
     expect(resolveNotifyUser({ header: '13', bodyUserId: 1 })).toBe(13);
     expect(resolveNotifyUser({ header: '1', bodyUserId: 13 })).toBe(1);

src/servers/sidecar/notify/resolve-user.ts

@@ -10,7 +10,7 @@
 //
 // So the header wins wherever it is present. This lives in its own module, away from the Bun.serve
 // entrypoint, purely so it can be tested — it is an access-control decision, and the version that read
-// `body.userId ?? header` let any account holding the `notify` capability push to any other account's
+// `body.userId ?? header` let any account holding the `notify` permission push to any other account's
 // devices by naming them in a JSON body.
 
 type ResolveUserParams = {

src/workspaces/hooks/src/usePermissions.ts

@@ -6,7 +6,7 @@ import { useClient } from './useClient';
 //
 // THIS IS NOT ACCESS CONTROL. Every answer here is a courtesy: it stops the app offering a member a
 // Terminal icon that would 403, and stops a screen mounting a panel whose every request will fail. The
-// lock is server-side, in the capability gate and the websocket gate — both of which
+// lock is server-side, in the permission gate and the websocket gate — both of which
 // hold regardless of what this hook returns, including when it returns nothing because the request failed.
 //
 // Which is why the failure mode below is deliberately generous rather than restrictive: if this request
@@ -42,7 +42,7 @@ export type SelfPermissions = {
 /** What an installed sidecar says about how it should appear. Mirrors UiManifest on the server. */
 export type PluginManifest = {
   sidecarId: string;
-  capability: string | null;
+  permission: string | null;
   name: string;
   icon?: string;
   image?: string;
@@ -88,7 +88,7 @@ export function usePermissions() {
   );
 
   /**
-   * Whether a frontend route is reachable. Only routes a capability actually claims are ever denied —
+   * Whether a frontend route is reachable. Only routes a permission actually claims are ever denied —
    * `/`, the settings shell and anything else unclaimed stays open, because denying by default here would
    * blank the app for everyone rather than restrict it for anyone.
    */
@@ -115,8 +115,8 @@ export function usePermissions() {
       if (!data) return null;
       if (!data.deniedRoutes.some((route) => path === route || path.startsWith(`${route}/`))) return null;
 
-      // Held but unavailable → the sidecar is missing. Checked against the capability that claims the route,
-      // which is why `unavailable` is returned as capability keys rather than routes.
+      // Held but unavailable → the sidecar is missing. Checked against the permission that claims the route,
+      // which is why `unavailable` is returned as permission keys rather than routes.
       const unavailable = new Set(data.unavailable ?? []);
       const heldAndUnavailable = data.permissions.some(({ key }) => unavailable.has(key));
       if (data.isOwner || heldAndUnavailable) return 'not-installed';

src/workspaces/officerdev/src/apps/AppStore/useAppStore.ts

@@ -49,7 +49,7 @@ export function useAppStore() {
     queryFn: () => client.get<{ items: StoreItem[] }>('/app-store'),
   });
 
-  // Every verb invalidates the same key, and also the capability answer: installing changes which dock
+  // Every verb invalidates the same key, and also the permission answer: installing changes which dock
   // tiles exist, and a store that updated while the dock kept the old list would be visibly wrong on
   // the same screen.
   const invalidate = () => {

src/workspaces/officerdev/src/apps/FileBrowser/useAgents.ts

@@ -18,7 +18,7 @@ export type AgentGroup = { category: string; agents: AgentSummary[] };
 // wrong thing about what happens when you click.
 export const useAgents = () => {
   const client = useClient();
-  // Agents are the `items` capability — skills, tools and agents on the owner's disk — and running one
+  // Agents are the `items` permission — skills, tools and agents on the owner's disk — and running one
   // starts a chat session, which is `chat`. Both are execution-only, so a member gets no agent submenu.
   const { can } = usePermissions();
   const allowed = can('items');

src/workspaces/state/src/useServerSettings.ts

@@ -19,7 +19,7 @@ export const useServerSettings = () => {
   const client = useClient();
   const queryClient = useQueryClient();
 
-  // `/server-settings` is the `server-admin` capability: owner only, and not grantable at any level. This
+  // `/server-settings` is the `server-admin` permission: owner only, and not grantable at any level. This
   // hook is mounted by shell components that every account loads, so without the guard a member's first
   // paint fired a 403 at it.
   const { isOwner } = usePermissions();