---
description: Schema map — when an agent needs to know what columns exist on which table
globs: pages/api/**/*.js,scripts/**/*.js,lib/database.js,lib/permission-middleware.js
---

# Use the schema map

Before writing any SQL that touches a column you haven't verified:

1. **Read [`docs/SCHEMA_MAP.md`](../../docs/SCHEMA_MAP.md)** — it's the curated reference.
2. If the column isn't documented there, search the migration scripts:

   ```
   rg "<column_name>" scripts/
   ```

3. If still no match, **stop and ask** — don't guess column names; Postgres won't be polite.

## When to update the schema map

After running any `scripts/add-*.js` / `scripts/fix-*.js` or any direct `ALTER TABLE`, update the matching table section in `docs/SCHEMA_MAP.md` in the same PR. The CI gate `schema-map-fresh` will fail if a `scripts/add-*.js` is added without a corresponding update.

## Common reference

- **Auth check inside an API route** → `users` (id, email, role)
- **Card lookup** → `cards` (id, name, scryfall_id UNIQUE, game)
- **What a user owns** → `user_cards` (user_id, card_id, quantity, is_foil)
- **Collection card list** → `collection_cards` JOIN `cards`
- **Permission check** → `collection_permissions` (collection_id, user_id, role, status='active')
- **Activity feed** → `collection_activity` (action, details JSONB)