capabilities/skills/platform/SKILL.md

---
name: Officer platform
description: >-
  Use when the user asks what Officer can do, how to use a feature, what an endpoint is, why something is
  refused, or how permissions and accounts work — "how do I start a commander", "can a member see my files",
  "what is the API for tasks". Carries the permission registry, every API prefix and socket, the frontend
  routes and the keyboard shortcuts, derived from the code rather than written by hand.
version: 1
---

<!--
  GENERATED by `bun run skills:platform`. Do not edit by hand — `bun run docs:check` fails if this file
  differs from what the generator produces, and an edit here is lost on the next run.

  The prose lives in scripts/gen-platform-skill.ts, beside the generation, so the two cannot separate.
-->

# What Officer is

One self-hosted app for one person — the **owner** — that also admits additional accounts holding a
strict subset of it. The owner is user id 1, role `Super Admin`, and bypasses every permission check.
Everyone else gets what their ROLE is granted, and nothing else: grants are keyed on role, never on a
user, and **absence denies** — there is no row meaning "no".

So "can this account do X" has three possible answers, and the third is the one people miss: yes,
no, and *not shareable at all*.

# Permissions

The authority for this is `src/servers/permissions/registry.ts`. Mounting an API router without an
entry there makes the server **refuse to boot** — so this list is complete by construction, not by
diligence.

## `core` — every account has it and it cannot be denied — the caller acting on themselves

- **Account** (`account`) — Sign in, your own profile, password, preferences and API keys
  - API `/user`, `/dock`, `/api-keys`, `/theme-favorites` · screen `/settings/profile`
- **Themes** (`themes`) — Read the themes installed on this machine
  - API `/themes`
- **Report a problem** (`bug-report`) — Send the server owner a bug report
  - API `/bug-report`
- **Notifications** (`notify`) — Push notifications to your devices
  - API `/notify`
  - owner only, even when granted: `/broadcast`
- **Screen layouts and dashboards** (`dashboards`) — Where your own screen layouts and dashboards are saved
  - API `/dashboards` · screen `/dashboards`
- **Command HQ** (`command-hq`) — Long-running commanders you started, organised into categories
  - API `/command-hq` · screen `/command-hq`

## `app` — grantable per role, at read or write

- **Memos** (`memos`) — Notes
  - screen `/memos`
- **Calendar and contacts** (`calendar`) — Calendars, contacts, and the app passwords that sync them to a phone
  - API `/caldav`, `/dav` · screen `/calendar`, `/contacts`
- **SendOff** (`sendoff`) — Send files to your own machines, and to accounts that have allowed you
  - API `/sendoff` · screen `/sendoff`

## `confined` — grantable, but only to an account that has its own Linux user; without one the grant resolves to nothing

- **Terminal** (`terminal`) — A shell on this machine, as your own user
  - API `/terminal` · socket `terminal` · screen `/terminal`
- **Chat** (`chat`) — The agent
  - API `/chat`, `/agent-status`, `/claude-auth` · socket `chat`, `chat-notify` · screen `/chat`, `/bots`
- **Files** (`files`) — Your own home directory on this machine, and the code editor over it
  - API `/file-browser`, `/upload` · screen `/files`, `/code-editor`
  - a POST that is really a read, allowed at read level: `/download`
- **Sub-agents** (`sub-agents`) — Start another agent from a prompt, subject to the account budget
  - API `/sub-agents`

## `execution` — runs as the server owner in the owner’s home. NEVER grantable, at any level, structurally

- **Tasks and jobs** (`tasks`) — Running permissions, pipelines and background jobs
  - API `/tasks`, `/jobs`, `/pipeline-jobs`, `/queue` · socket `task-runner`, `pipeline` · screen `/jobs`
- **Permission authoring** (`items`) — Skills, tools, agents and processes on disk
  - API `/skills`, `/tools`, `/agents`, `/processes`, `/rescan`
- **Scraping** (`browser`) — Fetches and renders a page in a headless browser, as the server owner
  - API `/scrape`

## `admin` — the server owner only

- **App store** (`app-store`) — Install, enable and remove the sidecars this server runs
  - API `/app-store` · screen `/app-store`
- **Plugins** (`plugins`) — Install, enable and remove the plugins this server runs
  - API `/plugins` · screen `/marketplace`, `/plugins`
- **Todo board** (`todos`) — The platform's own backlog — todo/ in the repo, browsed and edited at /todos
  - API `/todos` · screen `/todos`
- **Server settings** (`server-admin`) — Server configuration, integrations and the activity log
  - API `/server-settings`, `/integrations`, `/activity`, `/system-monitor` · screen `/settings/server`, `/settings/system`, `/activity`, `/system-monitor`
- **User management** (`user-admin`) — Accounts, roles and what each role may reach
  - API `/users` · screen `/settings/user-management`
  - acts on the caller themselves, allowed with no grant: `PUT /`
- **Roles** (`roles`) — Create, rename and delete the roles this server grants
  - API `/roles`

# Keyboard shortcuts

Derived from `src/apps/officer-web/state/shortcuts.ts`. These have moved several times; quote this
list rather than remembering one.

## Navigation

- `Ctrl+Space` — Spotlight — go to any screen, plugin or setting by name
- `Ctrl+?` — This list

## Themes

The browser applies as you move, so you watch the app change rather than reading names.

- `Ctrl+Shift+↑ / ↓` — Open the theme browser
- `Ctrl+Shift+← / →` — Previous / next theme, without opening anything
- `Ctrl+Shift+F` — Star or unstar the current theme, from anywhere

## In the theme browser

- `j / k  ↑ / ↓` — Move through the list
- `l  →` — Apply the focused theme and keep browsing
- `h  ←` — Put back the theme you started on
- `f` — Star or unstar the focused theme
- `Enter` — Keep what you are looking at
- `Esc` — Cancel and restore

## In Spotlight

- `↑ / ↓` — Move through the results
- `Enter` — Go there
- `Esc` — Close

## Chat

Recall only takes the arrow key from an EMPTY composer, and any other key ends a recall — so a draft is never overwritten.

- `↑ / ↓` — Previous / next prompt you sent, shell-style
- `Enter` — Send · on an empty composer with something queued, send that now
- `Shift+Enter` — Newline
- `Esc` — Stop the turn that is generating

# What is NOT in here

- **Installed plugins.** They vary per machine and per install, so a generated list would be wrong on
  every other server. Ask the platform: `GET /api/plugins` for what is installed here.
- **Request and response shapes.** This says which prefix a permission covers, not what a route
  accepts. Read the router under `src/servers/api/<feature>/` when the shape matters.
- **Anything about a commander beyond its permission.** That has its own skill — open it for what a
  commander is, how one is started, and how to help somebody shape one.

# When you are about to guess

Do not. This file is generated from the registry, so a question it does not answer is a question the
registry does not answer either — say so, and read the code. Every documented count in this repository
that was maintained by hand has been wrong, and an agent quoting a stale number sounds exactly as
certain as one quoting a true one.