# AGENTS.md - Fiddy

## Authority
- Source of truth: `PROJECT_INSTRUCTIONS.md` in the repo root.
- Bugfix protocol: `DEBUGGING_INSTRUCTIONS.md`.
- Current-stack mapping: `docs/AGENTIC_CONTRACT_MAP.md`.
- If files conflict, follow `PROJECT_INSTRUCTIONS.md`.

## Project Overview
- 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`.

## Important Directories
- `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.

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

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

## Verification Commands
- Backend unit/API tests: `npm test`
- Frontend lint: `npm run lint`
- Frontend typecheck: `npm run typecheck`
- Vulnerability audit: `npm run audit`
- Backend build: `npm run build:backend`
- Frontend build: `npm run build:frontend`
- Full build: `npm run build`
- E2E tests: `npm run test:e2e`
- Migration status: `npm run db:migrate:status`
- Migration verification: `npm run db:migrate:verify`

## Environment Notes
- `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.

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

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

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

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

## Codex Must Not
- 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.

## Deeper Docs
- `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.

## Response Icon Legend
- `🔄` in progress
- `✅` completed
- `🧪` verification/test result
- `📄` documentation update
- `🗄️` database or migration change
- `🚀` deploy/release step
- `⚠️` risk, blocker, or manual operator action needed
- `❌` failed command or unsuccessful attempt
- `ℹ️` informational context
- `🧭` recommendation or next-step option