# 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.