costco-grocery-list/AGENTS.md

AGENTS.md - Fiddy (External DB)

Authority

• Source of truth: PROJECT_INSTRUCTIONS.md (repo root). If conflict, follow it.
• Bugfix protocol: DEBUGGING_INSTRUCTIONS.md (repo root).
• Do not implement features unless required to fix the bug.

Non-negotiables

• External DB: DATABASE_URL points to on-prem Postgres (NOT a container).
• Dev/Prod share schema via migrations in packages/db/migrations.
• No cron/worker jobs. Fixes must work without background tasks.
• Server-side RBAC only. Client checks are UX only.

Security / logging (hard rules)

• Never log secrets (passwords/tokens/cookies).
• Never log receipt bytes.
• Never log full invite codes; logs/audit store last4 only.

Non-regression contracts

• Sessions are DB-backed (sessions table) and cookies are HttpOnly.
• Receipt images stored in receipts (bytea).
• Entries list endpoints must NEVER return receipt bytes.
• API responses must include request_id; audit logs must include request_id.
• Frontend actions that manipulate database state must show a toast/bubble notification with basic outcome info (action + target + success/failure).
• Progress-type notifications must reuse the existing upload toaster pattern (UploadQueueContext + UploadToaster).

Architecture boundaries (follow existing patterns; do not invent)

1. API routes: app/api/**/route.ts
   • Thin: parse/validate + call service, return JSON.
2. Server services: lib/server/*
   • Own DB + authz. Must include import "server-only";.
3. Client wrappers: lib/client/*
   • Typed fetch + error normalization; always send credentials.
4. Hooks: hooks/use-*.ts
   • Primary UI-facing API layer; components avoid raw fetch().

Next.js dynamic route params (required)

• In app/api/**/[param]/route.ts, treat context.params as async:
  • const { id } = await context.params;

Working style

• Scan repo first; do not guess file names or patterns.
• Make the smallest change that resolves the issue.
• Keep touched files free of TS warnings and lint errors.
• Add/update tests when API behavior changes (include negative cases).
• Keep text encoding clean (no mojibake).

Response icon legend

Use the same status icons defined in PROJECT_INSTRUCTIONS.md section "Agent Response Legend (required)":

• 🔄 in progress
• ✅ completed
• 🧪 verification/test result
• ⚠️ risk/blocker/manual action
• ❌ failure
• 🧭 recommendation/next step