# AGENTS.md: Shopify app

## Commands
- `shopify app dev` (tunnels to a dev store) · `shopify app deploy` (only when asked) · `npm run typecheck` · `npm test`
- Config: `shopify.app.toml` (scopes, webhooks, app proxy). Run `shopify app config link` once per environment.

## Rules
- Every loader/action in admin routes starts with `const { admin, session } = await authenticate.admin(request);`. Webhook routes use `authenticate.webhook(request)`; app proxy routes use `authenticate.public.appProxy(request)`.
- Use the GraphQL Admin API (`admin.graphql(query, { variables })`) with a pinned API version. REST Admin API is legacy; don't add new REST calls.
- Request only the access scopes you need; changing scopes requires merchants to re-approve, so call it out.
- Handle GraphQL `userErrors` in mutation responses, not just HTTP errors. Respect rate limits (query cost) and paginate with cursors.
- Webhooks are declared in `shopify.app.toml`; handlers verify via the library, respond fast, and queue heavy work. Mandatory privacy webhooks (customer data request/redact, shop redact) must be implemented.
- Store shop data keyed by `session.shop`; never trust a shop domain from query params without authentication.
- Embedded admin UI uses Polaris (web components or React, matching the template) and App Bridge for navigation, toasts, and modals.
- Extensions (checkout UI, theme app extensions, functions) live in `extensions/` and are generated with `shopify app generate extension`.

## Don't
Don't deploy, change billing config, or hit a production store from the agent.