rsc-universal 0.1.1

package/skills/shopify/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: shopify
+description: "Use when building or customizing a Shopify store across its three code surfaces — themes (Liquid + Online Store 2.0 sections/blocks/JSON templates), apps (Remix + versioned GraphQL Admin API), and checkout (UI extensions, Functions, Web Pixels). Triggers: writing/reviewing any .liquid section/snippet/template or {% schema %}, scaffolding a Shopify app with @shopify/shopify-app-remix + Polaris, Admin GraphQL queries and the query-cost/throttle model, shopify CLI flow (theme dev/push, app dev/deploy), 'merchant must edit content in the theme editor without a deploy', 'our checkout customizations broke after the August upgrade', 'add an @app block to the product section', 'migrar el checkout.liquid a checkout extensibility', 'afegir un bloc d'app a la secció de producte'. NOT WooCommerce/PHP stores (that is wordpress), NOT the React/RSC layer of a headless storefront (that is nextjs), NOT non-Shopify payment integrations (that is stripe)."
+tags: [shopify, liquid, ecommerce, themes, checkout, graphql, storefront]
+recommends: [nextjs, stripe, wordpress, api-design, seo-geo]
+origin: risco
+---
+
+# Shopify themes, apps & checkout
+
+The single authoritative skill for building and customizing a Shopify store. The mental model:
+**a Shopify store is a hosted platform you extend at well-defined seams — never a server you
+control.** You render on the storefront with Liquid, you mutate data through the versioned
+GraphQL Admin API, and you customize checkout through sandboxed extensions. The platform owns
+hosting, the database, PCI scope, and the checkout DOM; you own only the seams. Three surfaces,
+three toolchains — name the surface before you write a line of code.
+
+Pinned stack (verify against shopify.dev before pinning in a repo):
+
+- **Shopify CLI 4.x** — auto-upgrades via the package manager it was installed with; skips CI,
+  project-local installs, and major bumps. `shopify app config push` is removed; use `shopify app deploy`.
+- **GraphQL Admin API `2026-04`** — latest stable; supported window 2026-04 / 2026-01 / 2025-10 /
+  2025-07†. Each version is supported ~12 months. Pin `apiVersion` and bump quarterly.
+  † `2025-07` is at the edge of its window — accessible only until 2026-07-16; treat it as
+  sunsetting and do not pin it in new work. Re-check the live list at shopify.dev/docs/api/usage/versioning.
+- **Remix app template** (`@shopify/shopify-app-remix`, App Bridge, Polaris React). GraphQL > REST —
+  REST Admin API is legacy; Shopify steers all new app work to GraphQL.
+- **Dawn** — Shopify's source-available reference theme; OS 2.0 architecture is the baseline.
+
+## Pick your surface first
+
+Most Shopify mistakes are surface confusion — answering with a headless React build when the ask
+was a Liquid section, or editing `checkout.liquid` when the seam is now an extension. Branch here:
+
+| Surface | You're working on… | Tool & entry | Reference |
+|---|---|---|---|
+| **Theme** | `.liquid` files, `{% schema %}`, JSON templates, storefront rendering, merchant-editable content | `shopify theme dev` on a Dawn-based theme | `references/liquid-themes.md` |
+| **App** | embedded admin UI, reading/writing store data, webhooks, automation | `shopify app dev` on the Remix template + Admin GraphQL | `references/apps-graphql.md` |
+| **Checkout** | checkout/thank-you/order-status UI or logic, discounts, shipping, tracking | Checkout UI extensions / Functions / Web Pixels | `references/checkout-extensibility.md` |
+
+If the answer is "the React rendering layer of a headless storefront", that is `../nextjs/SKILL.md`,
+not this skill — Shopify is only the data seam (Storefront API) there.
+
+## Theme surface — Online Store 2.0 architecture
+
+OS 2.0 (GA 2021, sometimes marketed "3.0") is the architecture: JSON templates + sections-
+everywhere + theme blocks + `@app` blocks + dynamic sources. The file map:
+
+```text
+layout/theme.liquid            # the HTML shell (one per theme)
+templates/product.json         # JSON template: which sections render, in what order
+sections/main-product.liquid   # a section: markup + {% schema %} of merchant settings
+sections/*.liquid              # section groups (header/footer) live here too
+blocks/*.liquid                # theme blocks (reusable, nestable) — OS 2.0
+snippets/*.liquid              # partials rendered via {% render %}
+config/settings_schema.json    # global theme settings
+```
+
+**Rule: every section carries a `{% schema %}` with `presets` so merchants edit content in the
+theme editor without a deploy.** The why: content belongs in `section.settings` and metafields, not
+in code — if a merchant has to ask you to change a headline, the section is built wrong.
+
+```liquid
+<!-- Bad: copy hardcoded in Liquid; merchant can't touch it -->
+<h2>Summer Sale — 20% off everything</h2>
+
+<!-- Good: editable in the theme editor, with a preset so it appears in "Add section" -->
+<h2>{{ section.settings.heading | escape }}</h2>
+{% schema %}
+{
+  "name": "Promo banner",
+  "settings": [
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer Sale" }
+  ],
+  "blocks": [{ "type": "@app" }],
+  "presets": [{ "name": "Promo banner" }]
+}
+{% endschema %}
+```
+
+The `{ "type": "@app" }` block lets merchant-installed apps drop content into your section. The
+Shopify Theme Store **requires** the main product and featured-product sections to support `@app`
+blocks. See `references/liquid-themes.md` for setting types, section groups, and dynamic sources.
+
+## Liquid rules
+
+- **`{% render %}`, never `{% include %}`.** `render` is scoped (the snippet only sees what you
+  pass) and cacheable; `include` leaks the parent scope and is deprecated.
+
+  ```liquid
+  {% comment %} Bad {% endcomment %}
+  {% include 'price' %}
+  {% comment %} Good — explicit, scoped, cacheable {% endcomment %}
+  {% render 'price', product: product, variant: variant %}
+  ```
+
+- **Bound every collection loop with `limit:`** and never nest unbounded loops — storefront render
+  cost is real and slow pages cost conversions. `{% for p in collection.products limit: 8 %}`.
+- **Pipe all dynamic output.** `| money` for prices (raw values render cents/locale wrong),
+  `| escape` for any user/merchant string (XSS), `| json` when emitting data into a `<script>`.
+- **Push branchy logic into metafields/metaobjects, not conditional chains.** A `case`/`if` ladder
+  over product types is data pretending to be code — bind a metafield and let Liquid do a lookup.
+
+## CLI workflow
+
+Theme work (hot-reloads against a dev theme; never edits live unprompted):
+
+```bash
+shopify theme dev                      # local preview + hot reload
+shopify theme pull                     # sync live/named theme down
+shopify theme push --only templates/*  # push a subset; --ignore excludes paths
+shopify theme check                    # Theme Check linter — wire into CI
+```
+
+Multi-environment lives in `shopify.theme.toml`; `--environment` is repeatable
+(`shopify theme push --environment staging --environment prod`).
+
+App work:
+
+```bash
+shopify app dev      # tunnel + env + reload; provisions admin.graphql()
+shopify app deploy   # release app + extensions  (NOT `app config push` — removed in 4.x)
+```
+
+CLI 4.x auto-upgrades via your package manager but skips CI and project-local installs — pin the
+version in CI so a silent bump never changes a release.
+
+## App surface — Remix + GraphQL Admin API
+
+Apps are the Remix template. The shape:
+
+```text
+app/shopify.server.js     # shopifyApp({ apiVersion, sessionStorage, webhooks, ... })
+app/routes/app.*.jsx      # embedded admin pages (App Bridge + Polaris)
+shopify.app.toml          # app config, scopes, webhook subscriptions
+extensions/*              # app extensions (theme app ext, UI ext, Functions, Flow)
+```
+
+- **Pin `apiVersion` in `shopify.server` and bump it quarterly** — an unpinned client silently
+  follows Shopify's default and can break on a version rollover.
+- **Use the GraphQL Admin API, not REST.** REST is legacy; new fields ship to GraphQL only.
+
+  ```js
+  // Bad — legacy REST Admin endpoint
+  await fetch(`https://${shop}/admin/api/2026-04/orders.json`);
+
+  // Good — authenticated GraphQL through the template
+  const { admin } = await authenticate.admin(request);
+  const res = await admin.graphql(
+    `#graphql
+     query Orders { orders(first: 10) { nodes { id name } } }`
+  );
+  ```
+
+- **Verify webhook HMAC** before trusting any payload — `authenticate.webhook(request)` in the
+  template does this; never parse a raw webhook body without it.
+
+See `references/apps-graphql.md` for OAuth/session storage, mutations, App Bridge, and extensions.
+
+## GraphQL query-cost model
+
+Admin GraphQL meters by **calculated query cost (points), not request count.** Every response
+carries `extensions.cost`:
+
+```json
+{ "extensions": { "cost": {
+  "requestedQueryCost": 92, "actualQueryCost": 30,
+  "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1970, "restoreRate": 100 }
+}}}
+```
+
+- **Over-budget returns HTTP 200 with a `MAX_COST_EXCEEDED` error** — you must handle it in code; it
+  is not an HTTP-level failure your client will throw on.
+- **Read `throttleStatus` and back off on `restoreRate`** (points restored per second) rather than
+  blindly retrying.
+- **Large reads use bulk operations, not paginated loops.** A 10k-product export through `first:`
+  pagination will throttle; `bulkOperationRunQuery` runs async and returns a JSONL file.
+
+## Checkout surface — the post-`checkout.liquid` model
+
+`checkout.liquid` and additional scripts are **deprecated and being removed**. Dated facts:
+
+- **2024-08-13** — Information/Shipping/Payment steps lost `checkout.liquid` support.
+- **2025-08-28** — Plus self-migrate deadline for Thank-you & Order-status customizations (additional
+  scripts, script tags, `checkout.liquid`). This was the *deadline to act*, not the auto-upgrade date.
+- **2026-01** — **automatic upgrades** of Thank-you & Order-status pages begin (30-day email notice);
+  any remaining additional-scripts / script-tag / `checkout.liquid` customizations stop running.
+- **2026-04-15** — legacy Shopify Scripts can no longer be edited or published (existing scripts still run).
+- **2026-06-30** — legacy Shopify Scripts (Script Editor discount/shipping/payment scripts) stop executing entirely.
+
+Migrate by surface — match the old mechanism to its new seam:
+
+| Old (deprecated) | New seam | Notes |
+|---|---|---|
+| `checkout.liquid` UI tweaks | **Checkout UI extensions** | sandboxed React/JS targets, not DOM access |
+| Script Editor / additional-script discounts, shipping, payment logic | **Functions** (Rust or JS → Wasm) | deterministic, run server-side |
+| `<script>` tracking / analytics in checkout | **Web Pixels** + server-side events | sandboxed; no arbitrary DOM scripts |
+| custom checkout colors/fonts/CSS | **Checkout Branding API** | GraphQL, not CSS injection |
+
+Several checkout surfaces (full checkout UI customization, some Functions) are **Shopify Plus-only**.
+The full migration map, extension targets, and Functions structure are in
+`references/checkout-extensibility.md`.
+
+## App extensions catalog
+
+- **Theme app extension** — your app injects an `@app` block / blocks into themes (no theme edit).
+- **Admin UI extension** — surfaces inside admin pages (product, order) without leaving Shopify.
+- **Customer-account UI extension** — extends the new customer accounts.
+- **Functions** — discount / shipping / payment / cart logic as Wasm; the `checkout.liquid` logic seam.
+- **Flow** — triggers/actions for Shopify Flow automation, exposed by your app.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| `{% include %}` in new code | deprecated, leaks parent scope, not cacheable | `{% render %}` with explicit args |
+| Raw `{{ price }}` / `{{ user_input }}` | wrong locale/cents; XSS | `\| money`, `\| escape`, `\| json` |
+| Editing `checkout.liquid` / additional scripts | deprecated; auto-upgraded away starting 2026-01 | UI extensions / Functions / Web Pixels |
+| REST Admin calls in a new app | legacy; new fields are GraphQL-only | `admin.graphql()` |
+| Unpinned or stale `apiVersion` | breaks on Shopify's version rollover | pin a supported version, bump quarterly |
+| Paginated `first:` loop for big reads | throttles on query cost | `bulkOperationRunQuery` |
+| Ignoring `extensions.cost.throttleStatus` | silent `MAX_COST_EXCEEDED` at HTTP 200 | read cost, back off on `restoreRate` |
+| Hardcoded copy in Liquid | merchant can't edit without a deploy | `section.settings` / metafields |
+| Section with no `presets` | won't appear in "Add section" in the editor | add a `presets` entry to `{% schema %}` |
+| Secrets committed in `shopify.app.toml` | leaks API credentials | env vars; keep secrets out of TOML |
+| No Theme Check in CI | regressions ship to the storefront | `shopify theme check` in the pipeline |
+| Answering with a headless React build | wrong surface for a Liquid/theme ask | confirm the surface; route React to `../nextjs/SKILL.md` |
+
+Run `scripts/verify.sh <theme-or-app-dir>` for an advisory scan of these foot-guns.

package/skills/shopify/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — shopify
+
+Run these against the repo's eval harness pointed at the `shopify` skill id. The
+`should_trigger` cases mirror the `description` triggers across all three surfaces (theme, app,
+checkout) and include the non-obvious ones — the "broke after the August upgrade" checkout-
+migration framing, the `MAX_COST_EXCEEDED` query-cost framing, and the Catalan phrasing — to
+confirm the skill fires when the surface is implicit. The `should_not_trigger` cases each route to
+a real sibling (`wordpress`, `stripe`, `nextjs`, `no-code-app`, `api-design`) and exist to catch
+surface confusion: WooCommerce/PHP, non-Shopify payments, the headless React layer, no-code
+builders, and generic API-contract design must *not* pull in Shopify. The single `capability` case
+is graded against its `must_include` rubric — a correct answer scaffolds an OS 2.0 section
+(`render` not `include`, a `presets` + `@app` block schema) plus a Remix loader on a pinned
+`apiVersion` with `admin.graphql()` and cost/throttle awareness, and never reaches for
+`checkout.liquid`.

package/skills/shopify/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: shopify
+
+should_trigger:
+  - prompt: "Add a customizable section to my Shopify theme that merchants can edit in the theme editor without asking me to deploy."
+    why: "OS 2.0 section + {% schema %} with presets — the editable-content theme surface."
+  - prompt: "Build a Shopify app with Remix that reads orders from the Admin API and shows them in an embedded admin page."
+    why: "App surface: Remix template, admin.graphql(), App Bridge/Polaris."
+  - prompt: "Our checkout customizations stopped working after the August upgrade — how do I get them back?"
+    why: "Non-obvious: 2025-08-28 was the Plus self-migrate deadline; automatic upgrades begin 2026-01 → rebuild on checkout extensibility."
+  - prompt: "Replace the include tags in our Liquid snippets and stop the price from showing raw cents."
+    why: "Theme/Liquid rules: {% render %} over {% include %}, pipe through | money."
+  - prompt: "migrar el checkout.liquid a checkout extensibility i afegir un bloc d'app a la secció de producte"
+    why: "Catalan; checkout migration + @app block — both core surfaces of this skill."
+  - prompt: "We're getting MAX_COST_EXCEEDED from the Shopify Admin API on a big product export."
+    why: "Non-obvious: GraphQL query-cost/throttle model → bulk operations."
+
+should_not_trigger:
+  - prompt: "Build a WooCommerce store with a custom PHP theme and a few hooks in functions.php."
+    route_to: wordpress
+    why: "WooCommerce/PHP/WP plugin model, not Liquid + shopify.*.toml + GraphQL Admin API."
+  - prompt: "Integrate Stripe Checkout and subscription billing into our SaaS app."
+    route_to: stripe
+    why: "Non-Shopify payment system; Shopify Payments/checkout is in-platform only."
+  - prompt: "Build the React/RSC frontend and routing for our headless storefront."
+    route_to: nextjs
+    why: "The rendering/routing layer is Next.js; Shopify is only the data seam there."
+  - prompt: "Set up a no-code drag-and-drop online store, no developers involved."
+    route_to: no-code-app
+    why: "Non-developer store builder; this skill is the code surfaces (Liquid, CLI, GraphQL)."
+  - prompt: "Design our public REST API's versioning, pagination, and status-code conventions."
+    route_to: api-design
+    why: "Generic API contract design, not Shopify's specific versioned GraphQL + cost model."
+
+capability:
+  - scenario: "Scaffold an OS 2.0 section with {% schema %} + @app block support, and a Remix loader that queries products via the Admin GraphQL API."
+    must_include:
+      - "uses {% render %} (not {% include %})"
+      - "{% schema %} with a presets entry and a { type: '@app' } block"
+      - "pins a current apiVersion (2026-04 or another supported quarterly version) and uses admin.graphql()"
+      - "mentions query-cost / throttleStatus or bulk-operations awareness"
+      - "escapes/pipes dynamic output (| escape / | money) and does NOT touch checkout.liquid"

package/skills/shopify/references/apps-graphql.md

@@ -0,0 +1,103 @@
+# Shopify apps & the GraphQL Admin API — deep dive
+
+Companion to the App surface section of `../SKILL.md`. The template is `@shopify/shopify-app-remix`.
+
+## Template wiring
+
+```js
+// app/shopify.server.js
+import { shopifyApp, ApiVersion } from "@shopify/shopify-app-remix/server";
+import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
+
+const shopify = shopifyApp({
+  apiKey: process.env.SHOPIFY_API_KEY,
+  apiSecretKey: process.env.SHOPIFY_API_SECRET,   // env, never in shopify.app.toml
+  apiVersion: ApiVersion.April26,                  // pin; bump quarterly
+  scopes: process.env.SCOPES?.split(","),
+  sessionStorage: new PrismaSessionStorage(prisma),
+  webhooks: { ORDERS_CREATE: { deliveryMethod: "http", callbackUrl: "/webhooks" } },
+  future: { unstable_newEmbeddedAuthStrategy: true },
+});
+export const authenticate = shopify.authenticate;
+```
+
+OAuth, token exchange, and session storage are handled by the template — store sessions in a real
+DB (Prisma/SQL) in production, never in memory.
+
+## Queries & mutations
+
+```js
+export async function loader({ request }) {
+  const { admin } = await authenticate.admin(request);
+  const res = await admin.graphql(
+    `#graphql
+     query Products($n: Int!) {
+       products(first: $n) { nodes { id title totalInventory } }
+     }`,
+    { variables: { n: 20 } },
+  );
+  const { data, extensions } = await res.json();
+  return { products: data.products.nodes, cost: extensions.cost };
+}
+```
+
+Mutations follow the same shape and always select `userErrors { field message }` — Shopify returns
+validation failures there, not as thrown errors:
+
+```graphql
+mutation UpdatePrice($input: ProductVariantsBulkInput!, $productId: ID!) {
+  productVariantsBulkUpdate(productId: $productId, variants: [$input]) {
+    productVariants { id price }
+    userErrors { field message }
+  }
+}
+```
+
+## Query-cost, throttling & bulk operations
+
+Read `extensions.cost.throttleStatus` after every call. Over-budget = HTTP 200 + a
+`MAX_COST_EXCEEDED` entry in `errors`. Back off using `restoreRate` (points/sec). For large
+exports use bulk operations instead of `first:`/`after:` loops:
+
+```graphql
+mutation {
+  bulkOperationRunQuery(query: "{ products { edges { node { id title } } } }") {
+    bulkOperation { id status }
+    userErrors { field message }
+  }
+}
+```
+
+Poll `currentBulkOperation` until `status: COMPLETED`, then stream the JSONL from its `url`.
+
+## Webhooks (HMAC)
+
+```js
+// app/routes/webhooks.jsx
+export async function action({ request }) {
+  const { topic, shop, payload } = await authenticate.webhook(request); // verifies HMAC
+  // ... handle topic; return 200 fast, offload heavy work
+  return new Response();
+}
+```
+
+Never parse `request.body` directly — an unverified payload is untrusted input. Reconcile periodically;
+webhooks can be missed.
+
+## App Bridge & Polaris
+
+Embedded UI runs inside the Shopify admin iframe. App Bridge handles session-token auth, navigation,
+and toasts; Polaris React gives admin-consistent components. Keep app UI in Polaris so it matches the
+admin chrome — do not hand-roll admin-looking CSS.
+
+## App extensions & deploy
+
+Extensions live under `extensions/` (theme app extension, admin/customer-account UI extensions,
+Functions, Flow). Ship them with versioned releases:
+
+```bash
+shopify app deploy   # creates an app version bundling code + extensions; `app config push` is removed
+```
+
+Each `shopify app deploy` is an immutable, rollback-able version. Pin and bump `apiVersion`
+quarterly across both the app client and extension configs.

package/skills/shopify/references/checkout-extensibility.md

@@ -0,0 +1,71 @@
+# Checkout extensibility — migration off `checkout.liquid`
+
+Companion to the Checkout surface section of `../SKILL.md`. The old model (`checkout.liquid`,
+additional scripts, script tags, Script Editor) is deprecated and being removed.
+
+## The dated deadlines
+
+- **2024-08-13** — Information / Shipping / Payment steps stopped supporting `checkout.liquid`.
+- **2025-08-28** — Plus self-migrate deadline for Thank-you and Order-status page customizations
+  (additional scripts, script tags, `checkout.liquid`). This is the date to *act by*, not the
+  auto-upgrade date.
+- **2026-01** — **automatic upgrades** of Thank-you and Order-status pages begin. Shopify gives a
+  30-day email notice, then upgrades the store; any remaining additional-scripts, script-tag, or
+  `checkout.liquid` customizations stop running. (Non-Plus stores have a later self-migrate deadline
+  of 2026-08-26.)
+- **2026-04-15** — legacy Shopify Scripts can no longer be **edited or published** (existing
+  published scripts keep running until the shutdown below — so a bug after this date has no in-Script fix).
+- **2026-06-30** — legacy Shopify Scripts (Script Editor) **stop executing**. Replace with Functions.
+
+If a store says "checkout customizations broke after the August upgrade," they usually mean the
+2025-08-28 deadline passed and they were caught by the automatic upgrade (rolling out from 2026-01) —
+the old script no longer runs. Rebuild it on the seam below.
+
+## Migration map
+
+| Old mechanism | New seam | What you build |
+|---|---|---|
+| `checkout.liquid` markup / additional scripts (UI) | **Checkout UI extensions** | a sandboxed extension targeting a checkout location |
+| Script Editor discount logic | **Discount Function** | Wasm function returning discount operations |
+| Script Editor shipping/delivery logic | **Delivery customization Function** | reorder/rename/hide shipping options |
+| Script Editor payment logic | **Payment customization Function** | reorder/rename/hide payment methods |
+| `<script>` analytics/tracking in checkout | **Web Pixels** (+ server-side events) | sandboxed pixel; subscribe to standard events |
+| custom checkout CSS / branding | **Checkout Branding API** | GraphQL mutations on the checkout profile |
+
+## Checkout UI extensions
+
+React/JS extensions that render at defined **targets** (e.g. `purchase.checkout.block.render`,
+`purchase.checkout.delivery-address.render-before`). You get a typed API and components — **no DOM
+access**, by design (PCI + stability). Configure target + capabilities in the extension's TOML.
+
+```jsx
+import { reactExtension, Banner } from "@shopify/ui-extensions-react/checkout";
+export default reactExtension("purchase.checkout.block.render", () => <Banner>Free gift over 50</Banner>);
+```
+
+## Functions
+
+Deterministic server-side logic compiled to Wasm — author in Rust or JavaScript. A Function takes a
+typed input (a GraphQL query you define against the function's input schema) and returns operations.
+Categories: product discount, order discount, shipping discount, delivery customization, payment
+customization, cart/checkout validation. Generate with `shopify app generate extension`, build, and
+ship with `shopify app deploy`.
+
+```rust
+#[shopify_function]
+fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> {
+    // return discount operations from typed input
+}
+```
+
+## Web Pixels
+
+For tracking/analytics that previously lived in checkout `<script>` tags. A pixel runs in a sandbox
+and subscribes to standard customer events (`checkout_completed`, `product_viewed`, …). It cannot
+reach the page DOM; send events to your endpoint or a destination.
+
+## Plus-only surfaces
+
+Full checkout UI customization and some Function/branding capabilities are **Shopify Plus-only**.
+Non-Plus stores get a constrained set of UI extension targets. Confirm the merchant's plan before
+promising a checkout customization.

package/skills/shopify/references/liquid-themes.md

@@ -0,0 +1,89 @@
+# Liquid & Online Store 2.0 themes — deep dive
+
+Companion to the Theme surface section of `../SKILL.md`. Everything here is OS 2.0 (GA 2021).
+
+## The architecture, end to end
+
+A storefront page is assembled top-down:
+
+1. `layout/theme.liquid` — the HTML shell. Renders `{{ content_for_header }}` and
+   `{{ content_for_layout }}`. One per theme (plus optional `checkout` layout on Plus).
+2. A **JSON template** (`templates/product.json`, `templates/index.json`, …) declares which
+   sections render and their order — not Liquid, pure JSON the theme editor mutates.
+3. Each **section** (`sections/*.liquid`) is markup + a `{% schema %}` of settings and blocks.
+4. **Section groups** (`sections/header.json`, `sections/footer.json`) make header/footer
+   editable as section lists.
+5. **Snippets** (`snippets/*.liquid`) are partials, always via `{% render %}`.
+
+```json
+// templates/product.json
+{
+  "sections": {
+    "main": { "type": "main-product" },
+    "related": { "type": "related-products", "settings": { "heading": "You may also like" } }
+  },
+  "order": ["main", "related"]
+}
+```
+
+## `{% schema %}` setting types & presets
+
+The schema is JSON inside the `.liquid` file. Common setting types: `text`, `textarea`,
+`richtext`, `image_picker`, `url`, `product`, `collection`, `product_list`, `color`, `range`,
+`select`, `checkbox`, `font_picker`, `metaobject`/`metaobject_list`.
+
+```liquid
+{% schema %}
+{
+  "name": "Featured collection",
+  "tag": "section",
+  "settings": [
+    { "type": "collection", "id": "collection", "label": "Collection" },
+    { "type": "range", "id": "limit", "min": 2, "max": 12, "step": 1, "default": 8, "label": "Products" }
+  ],
+  "blocks": [
+    { "type": "text", "name": "Text", "settings": [{ "type": "richtext", "id": "body", "label": "Body" }] },
+    { "type": "@app" }
+  ],
+  "presets": [{ "name": "Featured collection", "blocks": [{ "type": "text" }] }]
+}
+{% endschema %}
+```
+
+- `presets` is what makes the section show up in "Add section" in the editor. No preset → the
+  section exists but a merchant can't add it.
+- `blocks` with `{ "type": "@app" }` accepts app-provided blocks (theme app extensions).
+- Iterate blocks in render order: `{% for block in section.blocks %}{% render block.type, block: block %}{% endfor %}`
+  and emit `{{ block.shopify_attributes }}` on the block's root element so the editor can target it.
+
+## Theme blocks (OS 2.0 reusable blocks)
+
+`blocks/*.liquid` define reusable, nestable blocks usable across sections — distinct from a
+section's inline `blocks`. They have their own `{% schema %}` and can accept child blocks via
+`"blocks": [{ "type": "@theme" }]`. Use them to avoid copy-pasting block markup between sections.
+
+## Dynamic sources, metafields & metaobjects
+
+Bind structured content instead of hardcoding. A setting can carry a **dynamic source** so a
+merchant connects it to a metafield in the editor. Read metafields in Liquid:
+
+```liquid
+{{ product.metafields.custom.care_instructions | metafield_tag }}
+{% assign spec = product.metafields.custom.spec.value %}  {# metaobject reference #}
+```
+
+Prefer this over an `if product.type == ...` ladder: the branch becomes a metafield lookup, so
+new product types need data, not a theme deploy.
+
+## Storefront performance
+
+- Responsive images: `{{ image | image_url: width: 800 | image_tag: loading: 'lazy', sizes: '...', widths: '300,600,800,1200' }}`.
+- `loading="eager"` + a `<link rel="preload">` only for the LCP hero image; lazy-load the rest.
+- Defer non-critical media and scripts; avoid render-blocking app embeds.
+- Always `limit:` collection/loop output; unbounded loops dominate render time.
+
+## Theme Check
+
+`shopify theme check` (config: `.theme-check.yml`) flags deprecated `include`, unused
+assigns, missing `{{ block.shopify_attributes }}`, untranslated strings, and parser errors. Run
+it locally and in CI. `theme dev` gives hot reload as the inner loop.