Files

T

pastilhasandClaude Opus 5 7c453d57ae two skills: the platform, and commanders

An agent answering "what is a commander, how do I start one" had nothing to answer from. skills/load.ts
already compiles an index of name + when-to-reach-for-it + path into every session, with the body read on
demand — so this needed skills written, not a mechanism built. There was one skill before these; now three.

skills/platform/SKILL.md is GENERATED by the platform repository's `bun run skills:platform`, and its
`docs:check` fails if it drifts. Do not edit it here — an edit is lost on the next run, and the generator
carries the prose for exactly that reason.

skills/commander/SKILL.md is written by hand, because none of it is derivable. What is in it is what three
days of running one taught, including the parts that surprised us:

- A commander is an ordinary chat session in a particular directory. Not a special agent — a conversation
plus a loop somebody started from inside it.
- Three pieces, and people get the third wrong: the conversation, the shell loop that waits, and the HEADLESS
AGENT the loop spawns when it fires. They expect the commander itself to wake up. It does not.
- Its cost line understates, structurally: only turns crossing the platform's chat socket are recorded, and a
spawned agent's never do. A commander that spent dollars through children can display cents.
- A spawned agent cannot be linked to its parent after the fact. The entry types that look like they mark one
are the harness's own and appear in both. If the link matters, the loop must record the id itself.
- Poll a local address, never a public hostname behind a reverse proxy — rate limiting there reads as an
access-rights error and is not one.
- The platform may not know a watcher exists: its bookkeeping engages only for the hand-back-and-re-arm fire
behaviour, so a working loop can sit beside a row that says unarmed.

The largest section is about helping somebody SHAPE one, since that is the part that is a conversation rather
than a form. Four questions, and the third is the one nobody volunteers: what must never happen twice. A
trigger that stays true after a failed action fires again, and again.

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

2026-08-22 16:48:48 +00:00

6.7 KiB

Raw Blame History

name, description, version

name	description	version
Officer platform	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.	1

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
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
Notifications (notify) — Push notifications to your devices
- API /notify

`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
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

`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
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 /

Keyboard shortcuts

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

Shift+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+Space — 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.

6.7 KiB Raw Blame History Unescape Escape