AGENTS.md - Fiddy

Authority

Full-stack grocery list app with household/group behavior, RBAC, image support, and Postgres persistence.
Backend: Express 5 CommonJS API in backend/.
Frontend: React 19 + Vite SPA in frontend/, with partial TypeScript.
Database: external on-prem Postgres. Do not add or assume a DB container.
Canonical migrations live in packages/db/migrations.

backend/routes, backend/controllers: route registration and request/response handling.
backend/models, backend/services, backend/middleware, backend/db: DB access, domain logic, auth, RBAC, request IDs, image handling.
frontend/src/api: client API wrappers using the shared Axios instance.
frontend/src/context, frontend/src/hooks, frontend/src/components, frontend/src/pages: UI state and screens.
frontend/tests: Playwright e2e tests.
backend/tests: Jest/Supertest backend tests.
scripts: DB migration helpers.
docs: practical maps, runbooks, architecture notes, and archived implementation history.

Install root tools: npm ci
Install backend tools: npm --prefix backend ci
Install frontend tools: npm --prefix frontend ci
Use Node.js 20.19+ or 22.12+ for frontend/Vite commands.
Configure backend env from backend/.env.example; never commit real .env values.
For migration scripts, set DATABASE_URL in the shell before running root DB commands.

Dev with Docker: docker compose -f docker-compose.dev.yml up
Backend only: npm run dev:backend
Frontend only: npm run dev:frontend
Backend default port: 5000
Frontend Docker-mapped port: 3010; Vite direct default is 5173 unless overridden.

backend/.env is used by the backend and Docker dev service.
frontend/.env may define VITE_API_URL and VITE_ALLOWED_HOSTS.
Do not print, log, or commit secrets, tokens, cookies, DB URLs, receipt bytes, or full invite codes.
Logs/audit entries for invite codes may include last4 only.

Preserve the current stack; do not migrate to Next.js or another framework.
Keep Express routes/controllers thin; put DB-heavy work in models/services and authz in backend layers.
Keep frontend network calls in frontend/src/api wrappers and UI state in context/hooks.
Always send credentials through the shared Axios client when touching authenticated frontend API calls.
Enforce RBAC server-side; client guards are UX only.
Frontend DB-mutating actions must show toast/bubble outcome notifications.
Progress notifications must reuse UploadQueueContext and UploadToaster.
Keep encoding clean; do not introduce mojibake.

npm is the package manager; do not introduce pnpm, yarn, bun, or another build tool.
Do not add production dependencies unless the task clearly requires it and the repo has no practical existing option.
Do not add cron, workers, polling daemons, or background job frameworks.

Add or update tests when API behavior changes.
Include negative cases for authz, membership, and invalid input where applicable.
For UI behavior changes, prefer focused Playwright tests.
Run the narrowest relevant checks first, then broader checks when risk warrants it.

Behavior is preserved unless the task explicitly requires a change.
Relevant tests/lint/typecheck/build commands were run or the reason they could not run is documented.
Touched files have no known TS/lint errors.
Migrations are in packages/db/migrations when schema changes are required.
Documentation is updated for changed commands, contracts, or workflows.

Do not read or expose real .env values; inspect variable names only when needed.
Do not touch production data or run DB migrations without explicit operator intent.
Do not log secrets, receipt bytes, or full invite codes.
Do not delete user work or generated artifacts unless explicitly asked.
Do not make broad refactors, file moves, or framework changes for cleanup alone.

docs/PROJECT_MAP.md: quick repo orientation.
docs/DEVELOPMENT.md: setup, run, verify, and troubleshooting.
docs/DB_MIGRATION_WORKFLOW.md: migration runbook.
docs/PLANS.md: template for multi-step work.
.agents/skills/fiddy-verify/SKILL.md: repo-specific verification workflow for Codex.