# AGENTS.md

Guidance for any coding agent working in the Officer platform repo.

**The instructions live in [`CLAUDE.md`](CLAUDE.md). Read it first — this file only points there.**

Kept separate so agents that look for `AGENTS.md` by convention find the same guidance as those that
look for `CLAUDE.md`, without the two drifting apart.

## Orientation

Officer is a self-hosted platform built around **one owner** (user id 1, role `Super Admin`, who
bypasses every permission check), which since 2026-08-07 also admits **additional accounts holding a
strict subset of it**. Roles are `Admin` / `Member` / `Developer`; what each may reach is decided by
per-role capability grants, resolved on every request.

If a design question turns on "which user", the answer depends on the surface: real for the **app**
capabilities (gitea, music, photos, email, calendar…), and still always **the owner** for anything
that executes code or touches the disk — terminal, chat, tasks, files, desktop, browser are
`kind: 'execution'` and can never be granted. `src/servers/capabilities/registry.ts` is the authority.

**Mounting a router without a registry entry makes the server refuse to boot.** Read the "Capabilities"
section of `CLAUDE.md` before adding one.

This file previously described Officer as strictly single-user with "no tenancy, no roles, no user
management". That was written to correct an *older* drift in the opposite direction — a fictional
multi-user intranet with a user-invitation API — and it overshot. Both are now superseded by the
paragraph above; treat the capability registry as the source of truth over either.

This repo is one of two. The other, `capabilities/`, holds the agent's tasks, tools and skills as
plain files, and is where most changes belong — adding or changing a task needs no code change here
and no restart.

- [`CLAUDE.md`](CLAUDE.md) — this repo's architecture, conventions and code style
- [`docs/working-on-officer.md`](docs/working-on-officer.md) — the deployment-wide guide: which
  directory a change belongs in, how to run and verify it, the task system, and the failure modes
  worth knowing about
- `CONVENTIONS.md` — component organisation and React patterns, with rationale
- `TODO.md` — current direction; takes precedence where it disagrees with anything else

Treat the code as the source of truth where anything disagrees with it.