docs/database.md

# Database workflow

The project uses Supabase SQL migrations as source of truth and Prisma for Python client generation.

## Mandatory flow

1. Create schema change in local Supabase.
2. Generate migration:
   - `supabase db diff -f <migration_name>`
3. Review migration SQL in `supabase/migrations/`.
4. Rebuild local DB:
   - `supabase db reset`
5. Sync Prisma schema:
   - `prisma db pull`
   - `prisma generate`
6. Run tests, then commit SQL + Prisma schema + code/tests.

## Rules

- Never edit an already applied migration.
- Never edit `prisma/schema.prisma` manually.
- Avoid direct schema-only changes in remote dashboard.