havenllo/AGENTS.md

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.