vibes

README.md

@@ -69,6 +69,33 @@ scripts/manual-pdf.sh                         # or: render to docs/generated/ fo
 
 Until it has been rendered once, `/manual.pdf` is a 404 that says so. The Markdown source is always at `/manual.md`.
 
+## Admin console
+
+`/admin` is a separate operator console: a list of accounts (ships, code slots, credits, last login and
+activity) and an audit log of what players did. It has its own login: one password, taken from the
+environment. With no password set the console is off.
+
+```sh
+echo 'HALCYON_ADMIN_PASSWORD=a-long-passphrase-of-12-or-more-characters' > .env   # git-ignored
+docker compose up -d
+```
+
+- **Sessions:** a signed, HttpOnly, SameSite=Strict cookie scoped to `/admin`, valid for 8 hours. Changing
+  the password ends every session. Wrong guesses are rate-limited per client address (5 failures, then a
+  15-minute lockout). Use it over HTTPS (Caddy does that) so the cookie is marked Secure.
+- **What is audited:** `register`, `login`, `code_save`, `code_clear`, `program_upload`, `launch` and
+  `uplink`, each with the account, time, client address and the specifics: the slot, name, size and
+  SHA-256 of saved code; the slot or program launched; the full data of every uplink (at most 1 KB). Actions
+  that fail are not recorded. A `login` is signing in with an access key through the site's login form (or
+  `POST /login`); other requests are authenticated by the key alone. The admin can read the code an
+  account has saved, but not change anything.
+- **Map:** the MAP tab is a top-down 2D chart of the belt: asteroids (coloured by dominant ore), the station,
+  drifting containers and every ship, each with its velocity vector drawn as an arrow (longer = faster).
+  Drag to pan, wheel or pinch to zoom, click an object for details, or pick a ship from the list to fly to it.
+  Positions are those at the start of the current day and are served by `GET /admin/api/map`. Clicking a ship
+  also draws the path it would coast along with its engine off from there, from `GET /admin/api/map/orbit`.
+- **Retention:** the log is never pruned. It is the `audit_log` table, so it can be queried or trimmed with SQL.
+
 ## Layout
 
 | path | what |