Merge main into demo/enterprise

apps/docs/AGENTS.md

@@ -60,8 +60,17 @@ npx plugins add Shopify/shopify-ai-toolkit --scope project --yes
 - Use MDX frontmatter with at least `title` and `description`; the schema (from `@vercel/geistdocs/source-config`) also supports `type`, `prerequisites`, `related`, `summary`, `tags`, and `excludeFrom`.
 - Add each new page to the relevant `meta.json` so it appears in the sidebar.
 - Plain markdown copied into MDX must have `{`, `}`, and bare `<` escaped outside code blocks.
-- Do not add `Key files`, file inventory, or file-to-purpose table sections. Mention a path inline only when it directly supports the surrounding instruction or explanation.
-- Keep customization suggestions concise and user-facing: say what can be changed and why someone might change it. Avoid implementation steps, code symbols, and file paths unless they are necessary to complete the customization or the reader asks for them.
+- Give each page one audience and one purpose. Lead with the outcome, then state the default, required action, and important limits.
+- Apply an essentiality test to implementation detail. Keep a technical detail only when the reader needs it to complete a task, make a decision, avoid a security or data problem, understand a real limitation, or verify the result.
+- Prefer observable behavior and merchant or shopper language. Treat function names, component names, internal fields, file paths, request choreography, and cache mechanics as warning signs in reader-facing guides.
+- Use short sentences, active voice, consistent terms, one instruction per step, and one main idea per paragraph. Define uncommon abbreviations before using them.
+- Exact commands, settings, environment variables, Admin paths, callback URLs, permissions, and security requirements are appropriate when the reader must act on them.
+- Generated skill pages are procedural instructions for coding agents and may remain technical. Never hand-edit their embedded skill content.
+- Do not put material in a reader-facing guide solely for a coding agent. Put repository instructions in `AGENTS.md` and reusable agent procedures in a skill.
+- Do not add `Key files`, file inventory, or file-to-purpose table sections. Mention a path inline only when it directly supports a required action.
+- Do not add a routine closing `Verify`, `Test`, or `Validation` section to reader-facing docs. In a procedural guide, place an essential confirmation immediately after the action it validates and describe the observable result. Agent-facing skills may keep explicit verification checklists.
+- End feature guides with a concise `What’s next` section. Suggest common ways teams extend or adapt the feature, explain what each change enables, and mention important tradeoffs. Keep the suggestions user-facing rather than turning them into implementation inventories.
+- Do not force `What’s next` onto reference pages, index pages, or setup flows that already end with a natural next action or navigation cards. Avoid repeating ideas already covered in the body.
 - Keep slugs stable unless the task explicitly includes redirects or link updates.
 
 ## Commands

apps/docs/content/docs/anatomy/aeo-geo.mdx

@@ -4,68 +4,33 @@ description: How the storefront makes itself legible to AI answer engines and ge
 type: guide
 ---
 
-**Answer Engine Optimization (AEO)** and **Generative Engine Optimization (GEO)** are the practices of making a site legible to the AI surfaces that increasingly mediate commerce — ChatGPT, Claude, Perplexity, Google AI Overviews, and the long tail of agent-driven shopping. Where classical SEO optimizes for crawlers that build a search index, AEO/GEO optimizes for models that read a page once and synthesize an answer. The legibility bar is higher: noisy markup, hydration-only data, and content trapped behind interaction all degrade an LLM's ability to recover the underlying facts.
+**Answer Engine Optimization (AEO)** and **Generative Engine Optimization (GEO)** help AI services understand and cite your storefront. The template provides machine-readable product and collection content without changing the pages shoppers visit.
 
-The template ships with several built-in surfaces that contribute to AEO/GEO. The largest of them is **content negotiation** — serving structured markdown to clients that ask for it — but the supporting cast (JSON-LD schema, sitemaps, OpenGraph metadata) is what makes a page consistently parseable across surfaces.
+## Make storefront content readable to AI
 
-## How it works
+Product, collection, and search URLs return structured Markdown when a client requests `text/markdown`. Normal browser requests continue to receive HTML from the same URLs. No setup is required.
 
-**Content negotiation swaps response format, not routes.** Product, collection, and search pages serve structured markdown when a client sends `Accept: text/markdown`; browsers that don't send it are unaffected and keep getting HTML from the same URL. A `next.config.ts` rewrite intercepts the matching request and routes it to a markdown handler under `app/md/` instead of the page route:
+The storefront also publishes `/llms.txt`, a concise index for AI agents. It links to search, collections, the sitemap, and crawl guidance rather than duplicating the full catalog. The [sitemap](/docs/anatomy/sitemap) remains the complete URL inventory.
 
-```
-GET /products/speaker        (Accept: text/markdown)
-GET /collections/speakers    (Accept: text/markdown)
-GET /search?q=speaker        (Accept: text/markdown)
-    ↓
-next.config.ts rewrite
-    ↓
-/md/products/[handle]
-/md/collections/[handle]
-/md/search
-    ↓
-Route handler response: text/markdown
-```
+If you enable Shopify Markets, add a `locale` query parameter to request locale-specific prices and catalog context.
 
-Every markdown route lives under this single top-level `app/md/` directory so all content-negotiation handlers are co-located and easy to find, and the `Vary: Accept` header ensures CDNs cache the markdown and HTML responses separately. This is built in and requires no configuration.
+## Included discovery surfaces
 
-**`llms.txt` is a curated index, not a full dump.** `/llms.txt` is a machine-readable index of the storefront — an [emerging convention](https://llmstxt.org) that is to AI agents what `robots.txt` is to crawlers. It links to the search entry point, the collection catalog, and the sitemap/robots discovery surfaces, and tells agents that those pages also serve clean Markdown via the content negotiation above. The route is dynamic: collections are pulled live from Shopify and capped so the file stays a concise index rather than an exhaustive dump — the full URL set lives in the [sitemap](/docs/anatomy/sitemap) instead. Because the links honor content negotiation, the virtual `/collections/all` catalog page is served as Markdown too, not just HTML.
+| Surface                          | Outcome                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------ |
+| Markdown responses               | Gives AI clients clean product, collection, and search content                 |
+| Schema.org data                  | Describes products, breadcrumbs, and the organization                          |
+| [Sitemap](/docs/anatomy/sitemap) | Lists storefront content for crawlers                                          |
+| Crawl guidance                   | Points crawlers to the sitemap and blocks faceted collection URLs              |
+| `/llms.txt`                      | Gives AI agents a concise storefront index                                     |
+| Social metadata                  | Supplies route-specific titles, descriptions, images, prices, and availability |
 
-**If you've enabled Shopify Markets, locale routing composes with content negotiation for free.** The content-negotiation rewrite fires before locale routing, so no additional configuration is needed — pass a `?locale=` query parameter to the markdown endpoint for locale-specific pricing and collection/search context.
+Markdown responses include the facts needed to interpret each page:
 
-## Out of the box
+- **Products** — brand, category, prices, options, variants, specifications, images, tags, and SEO metadata.
+- **Collections** — description, active and available filters, products, pagination, image, and SEO metadata.
+- **Search** — query, collection scope, filters, products, and pagination.
 
-| Surface                          | What it does                                                                                           |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| **Content negotiation**          | Serves clean markdown to AI clients via `Accept: text/markdown`                                        |
-| **Schema.org JSON-LD**           | Embeds structured `Product`, `BreadcrumbList`, and `Organization` data                                 |
-| **Sitemap**                      | [Sitemap index + paged children](/docs/anatomy/sitemap) for products and collections                   |
-| **Robots**                       | Declares crawl policy and blocks faceted (sort/filter) collection URLs                                 |
-| **`llms.txt`**                   | Curated `/llms.txt` index of collections and discovery links for AI agents                             |
-| **OpenGraph & Twitter metadata** | Per-route title/description/image previews, plus `product` OG tags (type, price, availability) on PDPs |
+## What’s next
 
-Markdown coverage by page type:
-
-- **Product pages** — handle, brand, category, pricing, options, variants, specs, images, tags, and SEO metadata
-- **Collection pages** — collection metadata, description, applied filters, available filters, products, pagination, image, and SEO metadata
-- **Search pages** — query metadata, active collection filter, applied filters, available filters, products, and pagination state
-
-Verify it directly:
-
-```bash
-# Returns structured markdown
-curl -H "Accept: text/markdown" http://localhost:3000/products/speaker
-
-# Returns collection markdown with products, filters, and pagination
-curl -H "Accept: text/markdown" http://localhost:3000/collections/speakers
-
-# Returns search markdown with query, filters, and result summaries
-curl -H "Accept: text/markdown" "http://localhost:3000/search?q=speaker&sort=price-low-to-high"
-
-# Returns the normal HTML page
-curl http://localhost:3000/products/speaker
-```
-
-## Common customizations
-
-- **Extending markdown coverage to a new route** — add a handler under `app/md/`, wire the matching `next.config.ts` rewrite for its `Accept: text/markdown` variant, and decide what fields belong in the markdown output for that content type.
-- **Tuning the `llms.txt` index** — adjust the collection cap or linked discovery surfaces if your catalog size or navigation structure calls for a different balance between a concise index and a fuller listing.
+Keep `/llms.txt` concise and use the sitemap for exhaustive discovery. Common extensions include Markdown responses for additional page types, localized discovery content, and public metaobject content. Include only facts an agent needs to identify, compare, or link to that content.