feat(plugin): add storefront standards for coding agents (#387)

* feat(plugin): add storefront standards for coding agents

* feat(plugin): define cart provider contract

* chore: ignore generated zip archives

* docs: strengthen storefront skill guidance

* feat(plugin): build-shop with docs/src reference

Author: blurrah

.gitignore

@@ -20,6 +20,9 @@ out/
 # production
 build
 
+# generated archives
+/*.zip
+
 # misc
 .DS_Store
 *.pem

apps/docs/AGENTS.md

@@ -16,7 +16,7 @@ npx plugins add Shopify/shopify-ai-toolkit --scope project --yes
 
 - `vercel-shop` provides the canonical storefront skills that the docs site renders and references.
 - `vercel-plugin` provides generic Vercel and Next.js skills.
-- `shopify-ai-toolkit` provides Shopify-aware tooling and schema access.
+- `shopify-ai-toolkit` is authoritative for current Shopify documentation, API schemas, operation validation, and store execution.
 
 ## Geistdocs architecture rules
 

apps/docs/content/docs/getting-started/extending-with-agents.mdx

@@ -11,7 +11,7 @@ Vercel Shop is built for agentic development. Instead of copy-pasting snippets f
 This works because the template ships with structured context that agents read automatically:
 
 - **`AGENTS.md`** - architecture rules and conventions. Tells the agent things like "every cart mutation must call `invalidateCartCache()`" or "components in `ui/` must not import domain types."
-- **Project-scoped plugins** - `vercel-shop`, `vercel-plugin`, and `shopify-ai-toolkit` provide skills, platform guidance, and live Shopify schema tooling.
+- **Project-scoped plugins** - `vercel-shop`, `vercel-plugin`, and `shopify-ai-toolkit` provide template conventions, platform guidance, and authoritative Shopify documentation and validation.
 
 For best results, use an agent that reads `AGENTS.md` and supports skills and project-scoped plugins - for example [Claude Code](https://claude.ai/code), [Cursor](https://cursor.sh), or [Codex](https://openai.com/index/introducing-codex/). Claude Code has the deepest integration via the plugin install flow; Cursor and Codex lean more on the repo context and docs.
 
@@ -21,7 +21,7 @@ After [creating your project](/docs/getting-started), `create-vercel-shop` insta
 
 - `vercel-shop` for initialization and storefront skills plus drift and upgrade-planning commands
 - `vercel-plugin` for generic Vercel and Next.js guidance
-- `shopify-ai-toolkit` for Shopify-aware tooling and schema access
+- `shopify-ai-toolkit` for current Shopify documentation, schemas, operation validation, and store execution
 
 If you already have a project and only want the agent setup:
 
@@ -93,6 +93,9 @@ You can also follow any skill manually from the docs, or inspect the source in t
 ### Available skills
 
 <Cards>
+  <Card title="Build with Vercel Shop" href="/docs/skills/build-shop">
+    Source-backed storefront architecture and commerce behavior.
+  </Card>
   <Card title="Enable Shopify Markets" href="/docs/skills/enable-shopify-markets">
     Multi-locale and multi-currency support.
   </Card>
@@ -146,6 +149,24 @@ Make the accordion closed by default on mobile
 
 The agent retains context from the previous exchange.
 
+### Use a browser feedback loop
+
+Storefront changes should be checked in a real browser, not only by reading diffs. v0 has this feedback loop built in. For agents without built-in browser control, install the standalone [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI:
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+Then ask the agent to start the dev server, open the affected route, capture a snapshot and screenshot, interact through the changed commerce flow, and repeat until the browser result matches the intended behavior.
+
+```bash
+agent-browser open http://localhost:3000/products/example
+agent-browser wait --load networkidle
+agent-browser snapshot
+agent-browser screenshot --full
+```
+
 ### When something breaks, name the failure
 
 Specific error messages and likely files beat "fix it":

apps/docs/content/docs/reference/storefront-api.mdx

@@ -72,7 +72,7 @@ Output lands in `lib/shopify/types/generated/`, which is **gitignored**. Nothing
 
 Because codegen resolves interpolations of other `#graphql` consts by name, every fragment in `lib/shopify/fragments.ts` is also tagged `#graphql ... as const`. A raw selection snippet that isn't a valid standalone document (it can't be `#graphql`-tagged) must be inlined into each operation rather than interpolated.
 
-Always verify fields against the live Storefront API schema with `shopify-ai-toolkit` or [`/vercel-shop:shopify-graphql-reference`](/docs/skills/shopify-graphql-reference) when adding or modifying queries - don't guess field names.
+Always use Shopify AI Toolkit to search current Shopify documentation and validate the final operation. Then use [`/vercel-shop:shopify-graphql-reference`](/docs/skills/shopify-graphql-reference) for Vercel Shop integration conventions. The Vercel Shop skill is not a schema source.
 
 ## Fragments
 
@@ -131,14 +131,23 @@ export async function getProduct({
 
 Key elements:
 
-1. **`"use cache"`** - uses the local Next.js cache for stable, low-cardinality reads
+1. **`"use cache"`** - includes the stable product body coherently in the PDP's prerendered shell
 2. **`cacheLife("max")`** - caches indefinitely until manually revalidated
 3. **`cacheTag(...)`** - assigns tags for granular invalidation via `revalidateTag()`
 4. **Transform** - convert the Shopify response to a domain type before returning. Components never import Shopify types directly.
 
 ## Caching
 
-Read operations use `"use cache"` or `"use cache: remote"` with `cacheLife("max")` and one or more cache tags. Stable, low-cardinality reads (product detail, single collection) can use plain `"use cache"` so they inline into the static shell; high-cardinality operations that depend on search, filters, sort, or cursors use `"use cache: remote"`, which stores entries in Vercel's shared Runtime Cache so they persist across serverless instances and between requests. Tags follow a hierarchy:
+Read operations choose cache behavior from their render role:
+
+| Render role                                                                     | Treatment                                                        |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Public identity/body that belongs coherently in the prerendered shell           | Plain `"use cache"`                                              |
+| Public results resolved after request inputs such as filters, search, or cursor | `"use cache: remote"` when shared Runtime Cache is justified     |
+| Cart, session, authorization, or Customer Account data                          | Request-scoped or private; never public remote cache             |
+| Mutation                                                                        | No read-cache directive; invalidate affected state after success |
+
+Cached public operations use the established `cacheLife` and tags. Combined with webhook-driven invalidation, those tags refresh the intended shell or runtime entry when Shopify changes. Tags follow a hierarchy:
 
 | Tag pattern                | Scope                                |
 | -------------------------- | ------------------------------------ |
@@ -206,20 +215,19 @@ Domain types are defined in `lib/types.ts` and are provider-agnostic. Components
 
 ## Key files and tools
 
-| Resource                                | Purpose                                                                              |
-| --------------------------------------- | ------------------------------------------------------------------------------------ |
-| `lib/shopify/storefront.ts`             | Shared `@shopify/storefront-api-client` instance + `customFetchApi`                  |
-| `lib/shopify/errors.ts`                 | `assertStorefrontOk` response contract + cart error helpers                          |
-| `lib/shopify/customer-account.ts`       | `customerAccountFetch` for the separate Customer Account API                         |
-| `.graphqlrc.ts`                         | Codegen config (schema source, documents, output dir)                                |
-| `lib/shopify/types/generated/`          | Generated (gitignored) Storefront types + schema snapshot; codegen validation output |
-| `lib/shopify/fragments.ts`              | Reusable `#graphql` fragment definitions                                             |
-| `lib/shopify/operations/products.ts`    | Product queries: single, batch, search, recommendations                              |
-| `lib/shopify/operations/cart.ts`        | Cart queries and mutations                                                           |
-| `lib/shopify/operations/collections.ts` | Collection queries                                                                   |
-| `lib/shopify/operations/search.ts`      | Predictive search                                                                    |
-| `lib/shopify/operations/menu.ts`        | Navigation menu queries                                                              |
-| `lib/shopify/transforms/product.ts`     | Shopify product → domain type                                                        |
-| `lib/shopify/transforms/cart.ts`        | Shopify cart → domain type                                                           |
-| `lib/cart/server.ts`                    | `invalidateCartCache()` for mutation cache busting                                   |
-| `shopify-ai-toolkit`                    | Live Storefront and Customer Account schema inspection                               |
+| Resource                                | Purpose                                                               |
+| --------------------------------------- | --------------------------------------------------------------------- |
+| `lib/shopify/storefront.ts`             | Shared `@shopify/storefront-api-client` instance + `customFetchApi`   |
+| `lib/shopify/errors.ts`                 | `assertStorefrontOk` response contract + cart error helpers           |
+| `lib/shopify/customer-account.ts`       | `customerAccountFetch` for the separate Customer Account API          |
+| `.graphqlrc.ts`                         | Codegen config (schema source, documents, output dir)                 |
+| `lib/shopify/fragments.ts`              | Reusable `#graphql` fragment definitions                              |
+| `lib/shopify/operations/products.ts`    | Product queries: single, batch, search, recommendations               |
+| `lib/shopify/operations/cart.ts`        | Cart queries and mutations                                            |
+| `lib/shopify/operations/collections.ts` | Collection queries                                                    |
+| `lib/shopify/operations/search.ts`      | Predictive search                                                     |
+| `lib/shopify/operations/menu.ts`        | Navigation menu queries                                               |
+| `lib/shopify/transforms/product.ts`     | Shopify product → domain type                                         |
+| `lib/shopify/transforms/cart.ts`        | Shopify cart → domain type                                            |
+| `lib/cart/server.ts`                    | `invalidateCartCache()` for mutation cache busting                    |
+| `shopify-ai-toolkit`                    | Authoritative Shopify docs, schemas, operation design, and validation |

apps/docs/content/docs/reference/troubleshooting.mdx

@@ -45,7 +45,7 @@ images: {
 
 This usually means the query references a field, argument, or enum value that doesn't exist on the live Shopify API version your store is using.
 
-Re-check the operation with `shopify-ai-toolkit` or the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) and confirm each field against the live schema before changing the query.
+Re-check and validate the operation with Shopify AI Toolkit first. Then use the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) for the template integration and cache role.
 
 If the Shopify plugin is missing, reinstall it:
 

apps/docs/content/docs/shopify/index.mdx

@@ -38,7 +38,7 @@ Menu items can link to collections, products, pages, or custom URLs.
 
 ## Webhooks and cache invalidation
 
-All read operations are cached with `"use cache: remote"` and `cacheLife("max")`. Without webhooks, changes in Shopify won't appear until the cache expires. To get near-instant updates, configure Shopify webhooks to hit the template's invalidation endpoint.
+Public reads use either plain `"use cache"` for content that belongs coherently in a prerendered shell or `"use cache: remote"` for reusable request-time results. Both use established cache tags. Without webhooks, Shopify changes may remain cached until the configured lifetime expires, so configure Shopify webhooks to hit the template's invalidation endpoint.
 
 ### Webhook endpoint
 

apps/docs/content/docs/shopify/writing-shopify-queries.mdx

@@ -8,11 +8,11 @@ prerequisites:
 
 This guide walks through adding a new Shopify Storefront API operation from scratch. We'll fetch a shop's privacy policy as a concrete example.
 
-If you're using a coding agent, run `/vercel-shop:shopify-graphql-reference` in Claude Code or ask the agent to use the `shopify-graphql-reference` skill first. The skill is the reference source for Shopify GraphQL work and uses `shopify-ai-toolkit` for live schema checks while keeping the agent anchored to the template guardrails.
+If you're using a coding agent, use Shopify AI Toolkit's Storefront GraphQL skill first so it searches current Shopify documentation and validates the operation. Then run `/vercel-shop:shopify-graphql-reference` to integrate that validated operation with the template's files, domain types, cache role, and invalidation.
 
 ## 1. Check the schema
 
-Use `shopify-ai-toolkit`, Shopify's GraphQL docs, or your preferred GraphQL explorer to confirm the field exists before writing the query. For our example, the `QueryRoot` type has a `shop` field with a `privacyPolicy` property that returns a `ShopPolicy`:
+Use Shopify AI Toolkit to confirm the operation against the intended Storefront API version before writing template code. For this example, validate the `shop.privacyPolicy` selection and its return fields rather than relying on this guide as API reference:
 
 ```graphql
 type ShopPolicy {
@@ -86,15 +86,14 @@ Codegen parses every `#graphql`-tagged query and **fails the command if a field,
 Create a new file in `lib/shopify/operations/` or add to an existing one. The function calls `storefront.request`, asserts the response is OK, applies caching, and returns the result:
 
 ```ts
-import { cacheLife, cacheTag } from "next/cache";
+import { cacheLife } from "next/cache";
 import { defaultLocale, getCountryCode, getLanguageCode } from "@/lib/i18n";
 import { assertStorefrontOk } from "../errors";
 import { storefront } from "../storefront";
 
 export async function getPrivacyPolicy(locale: string = defaultLocale) {
   "use cache";
-  cacheLife("max");
-  cacheTag("policies");
+  cacheLife("days");
 
   const response = await storefront.request<ShopifyPrivacyPolicyResponse>(PRIVACY_POLICY_QUERY, {
     variables: {
@@ -113,12 +112,12 @@ Key points:
 
 - **`storefront`** is the shared `@shopify/storefront-api-client` instance from `lib/shopify/storefront.ts`. Pass your response type as the generic; the query is the first argument and variables go in the options object.
 - **`assertStorefrontOk(response, name)`** throws on a transport/GraphQL failure (no `data`), warns on partial errors, and narrows `response.data` to non-null.
-- **`"use cache"`** uses the local Next.js cache for stable, low-cardinality reads
-- **`cacheLife("max")`** caches until you manually invalidate
-- **`cacheTag("policies")`** lets you invalidate with `revalidateTag("policies")` later
-- Use `"use cache: remote"` instead for high-cardinality reads that depend on search, filters, sort, or cursors
+- **`"use cache"`** allows this stable policy body to become part of the page's prerendered shell.
+- **`cacheLife("days")`** refreshes content that has no matching webhook invalidation path.
 - Always pass `locale` and extract `country`/`language` from it
 
+Cache behavior follows the consuming route, not a universal default. Use plain `"use cache"` for public identity/body content that must be coherent in the static shell. Use `"use cache: remote"` for reusable public results resolved after request inputs such as filters, search, or cursors. Keep cart, session, and Customer Account data request-scoped or private. Use `cacheLife("max")` only when a webhook, mutation, or deliberate manual path invalidates every associated tag.
+
 ## 6. Add a transform (if needed)
 
 If the Shopify response shape differs from how your components want to consume the data, add a transform in `lib/shopify/transforms/`. This keeps Shopify-specific types out of your UI:
@@ -195,10 +194,11 @@ Expose mutations to the client through server actions in `components/cart/action
 - [ ] Query string starts with `#graphql` and the declaration ends with `as const`
 - [ ] Query/mutation is **named** so codegen can parse it
 - [ ] Document is static — dynamic parts passed as variables, not interpolated into the query string
+- [ ] Validated the final operation with Shopify AI Toolkit
 - [ ] `pnpm --filter template codegen` passes (validates fields against the live schema); generated types are gitignored and regenerate at dev/build
 - [ ] `@inContext` directive included if data is locale-sensitive
 - [ ] `storefront.request<ResponseType>(QUERY, { variables })` followed by `assertStorefrontOk(response, name)`
-- [ ] `"use cache"` or `"use cache: remote"`, `cacheLife`, and `cacheTag` set for read operations
+- [ ] Cache directive chosen from the route's render role, with `cacheLife` and `cacheTag` where applicable
 - [ ] Transform added if the Shopify response shape needs mapping
 - [ ] Components import domain types from `lib/types`, not Shopify response types
 - [ ] Cart mutations call `invalidateCartCache()`