# AGENTS.md Guidance for AI agents and contributors working in this repo. Read `README.md` for commands and layout. ## Prose discipline Every word in this repo is read again on every future task, so prose is a recurring cost. On **any** change, sweep the prose you touched — this file, `README.md`, the example READMEs, and code comments — and cut it back to what a competent reader could not infer: - **Delete history.** Git holds it. No "this moved from X", "used to be Y", "was tried and rejected", "(declined twice)", dated changelog entries (a decision's date in `docs/decisions.md` is not one), or the symptom that prompted a fix. Record the decision and the reason it *currently* turns on, nothing else. - **Delete restatement.** A comment that says what the adjacent line says, a doc paragraph that re-explains a table above it, a file-map entry that expands the filename. The fix is deletion, not trimming. - **Delete the self-evident** and anything already stated once elsewhere. **One home per fact** — link to it instead of repeating it; the same sentence in five files is five chances to drift. - **Give every accepted risk an expiry** ("valid while X"), and delete the entry once X stops holding. - **Keep** the surprising why, the footgun, the invariant, the external constraint, and the one-time setup a reader cannot dig out of the code. Once a line has earned its place, make it short and information-dense. Trimming is not a separate task to schedule — do it in the same change, every time. ## How to work with tasks Use the file `todo.md`. For each todo item, interview the user extensively to deeply understand the scope and goal of each. When done, check the completed task in `todo.md`. Commit all changes and push to a new branch, create a PR and merge it when the CI/CD turns green. ## Project priorities (do not erode) 1. **Simplicity** — prefer the solution that is easiest to understand, smallest, and most readable. **A page is a document**: it scrolls, and the chrome scrolls with it. Nothing may bound the viewport to hold content still — no `height: 100dvh` frame, no `overflow: hidden` on `body`, no `position: sticky` header. Each such box buys an app-like look with CSS the next reader has to reverse-engineer, and is one more thing to undo before the content under it can be reached. Overlays are not this: the skip link, the mobile off-canvas nav and its scrim sit *above* the document rather than holding it still, and have no other spelling — the document keeps scrolling behind the open nav, accepted rather than overlooked. Only the document scroller gets keyboard paging unconditionally and back/forward scroll restoration, and a page a box clips fails silently: nothing in a test or a console says content is unreachable below the fold. 2. **Few dependencies** — runtime deps stay minimal (today `ejs`, `lucide-static`, `@larvit/log`, `postgres`). Prefer the Node standard library; justify any new dependency; do not add frameworks. The **host is stateless — it owns no schema and stores nothing of its own**; a plugin may own a Postgres database, which the host provisions but never reads or writes inside. Auth/identity/OAuth are **Ory sidecar services** reached over their REST APIs with built-in `fetch` — no SDK. New capabilities ship as **plugin folders** under `plugins/` that get their data from an upstream service or their own database, not as core code. 3. **Strict TypeScript** — `tsconfig.json` is strict (incl. `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `verbatimModuleSyntax`). Keep it that way. Prefer exact types; limit nullable and multi-option types. 4. **Environment-agnostic** — no `NODE_ENV` branching. Every behaviour is an **explicit config toggle** read once in `src/config.ts`; compose files set them per deployment. 5. **Semantic, accessible DOM** — the right element for the job (landmarks, one `

` per page + sane heading order, lists, `` with row/column headers, `
`/``, `