docs: add project-context.md and AGENTS.md for AI agents

AGENTS.md

@@ -0,0 +1,37 @@
+# Agents
+
+Always read `project-context.md` first — it is the canonical source of truth for this project's architecture, data model, API contract, file roles, and conventions.
+
+## Reading project-context
+
+- Before making any change, read `project-context.md` in full. Do not rely on memory of the codebase or on assumptions from other projects.
+- If `project-context.md` is missing or clearly stale (e.g. a file/endpoint it describes does not exist), treat that as a bug and update it as part of your work.
+
+## Keeping project-context updated
+
+- Keep `project-context.md` current with the actual state of the project. It is a living spec, not a changelog — do not turn it into a history of edits.
+- Whenever you change any of the following, update `project-context.md` in the same delivery (same commit/PR):
+  - architecture or layering
+  - file roles / new or removed source files
+  - API endpoints, request/response contracts, or error shapes
+  - data model (tables, columns, seeds, constraints)
+  - environment variables, ports, or runtime behavior
+  - build, image, or deployment flow (Dockerfile, deploy manifests, CI)
+  - dependencies or technology-stack changes
+  - notable UI/UX or product decisions
+- Prefer precise, file-level descriptions over vague summaries so future agents can navigate the code without re-discovering it.
+
+## Build & verify before claiming done
+
+- Backend: `go test ./...` must pass. `go build ./...` must succeed with `CGO_ENABLED=0`.
+- Frontend: `cd web && npm ci && npm run build` must succeed (this type-checks and bundles to `web/dist`, which is embedded by the Go binary and git-ignored).
+- Do not commit `web/node_modules` or `web/dist` — both are git-ignored; the Docker `frontend` stage rebuilds `dist`.
+- The `verify` job of `.gitea/workflows/main.yaml` installs Go + Node via `apk add` on the Alpine slim runner and performs an offline YAML doc check (no cluster access) — keep that step cluster-free.
+
+## Conventions
+
+- Single fixed board (no `boards` resource). Lists + cards only.
+- SQLite on a single-writer PVC; one replica, `Recreate` strategy, container runs as root (`USER 0`) on NFS.
+- Plain nginx ingress `havenllo.haven` (default namespace), no TLS/cert-manager.
+- Same-origin API under `/api`; the Go binary also serves the embedded SPA. No CORS, no auth.
+- Minimal dependencies: `modernc.org/sqlite` (backend), `preact` only (frontend runtime); no ORM, no DnD/state/icon libraries.