# AGENTS.md: Sanity (Studio + frontend)

## Commands
- Studio dev: `npx sanity dev` · deploy (only when asked): `npx sanity deploy`
- Types: `npx sanity schema extract && npx sanity typegen generate` after any schema or query change
- Migrations: `npx sanity migration create` then `npx sanity migration run <id>` (dry run by default; add `--no-dry-run` only when asked)

## Code map
- `schemaTypes/` (or `sanity/schemaTypes/`): one file per document/object type, exported from `index.ts`.
- `sanity.config.ts`, `sanity.cli.ts` at the Studio root. Frontend queries in `lib/queries.ts` (or `sanity/lib/queries.ts`).

## Schema rules
- Use `defineType`, `defineField`, `defineArrayMember` for every type so TypeScript and TypeGen work.
- Every document has `title`, a `slug` with `options.source`, `validation` rules for required fields, and a `preview` config.
- Use references for shared entities (authors, categories) instead of duplicating objects.
- Images use `type: 'image'` with `options.hotspot: true` and a required `alt` field.
- Renaming or removing fields breaks existing content: write a migration instead of deleting the field.

## Query rules
- Write GROQ with the `defineQuery` helper so TypeGen produces result types; project only the fields you need (`{_id, title, "slug": slug.current}`).
- Pass parameters (`$slug`), never string-interpolate user input into GROQ.
- Use the CDN (`useCdn: true`) for public reads; use a token-authenticated client only on the server, and never ship tokens to the browser.
- Render Portable Text with `@portabletext/react` (or the framework's equivalent) and explicit components for custom blocks.
- Use `next-sanity`'s `sanityFetch` with tags / Live Content API for revalidation when the frontend is Next.js.

## Done
Studio builds (`npx sanity build`), typegen is up to date with no type errors, and the frontend build passes.