pastilhas
027b10bd6e
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.
42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# 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 permission grants, resolved on every request.
|
|
|
|
If a design question turns on "which user", the answer depends on the surface: real for the **app**
|
|
permissions (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/permissions/registry.ts` is the authority.
|
|
|
|
**Mounting a router without a registry entry makes the server refuse to boot.** Read the "Permissions"
|
|
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 permission registry as the source of truth over either.
|
|
|
|
This repo is one of two. The other, `permissions/`, 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.
|