@damiangilgonzalez/harness 1.3.7

package/skills/seo-geo/scripts/verify.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# verify.sh — seo-geo on-page artifact gate (read-only).
+#
+# Usage:
+#   bash scripts/verify.sh [TARGET]
+#     TARGET = a file or directory containing the produced artifacts
+#              (HTML head, JSON-LD blocks, an optional robots.txt).
+#              Defaults to the current directory.
+#
+# What it checks across *.html *.htm *.json *.jsonld and robots.txt under TARGET:
+#   (a) NO DEAD schema @type appears (FAQPage, Course, ClaimReview,
+#       SpecialAnnouncement, VehicleListing, EstimatedSalary, LearningVideo) —
+#       the highest-value guard against shipping dead markup.
+#   (b) Each .json/.jsonld parses as valid JSON and carries @context + @type
+#       (when a JSON parser is available; skipped with a warning otherwise).
+#   (c) <title> text ≤ 60 chars; meta description ≤ 160 chars; exactly one <h1>.
+#   (d) If a robots.txt is present, it does not Disallow a search/citation bot
+#       (Googlebot, OAI-SearchBot, PerplexityBot, Claude-SearchBot) at the root.
+#
+# Read-only: reads files only, no writes, no network, no installs. Safe to re-run.
+# Exits 0 on an empty/clean target (no false failure); non-zero on any violation.
+#
+# Portability: stock macOS bash 3.2. No `mapfile`; no empty-array expansion under
+# set -u. `set -e` intentionally OFF (each check owns its exit code).
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; }
+
+TARGET="${1:-.}"
+if [ ! -e "$TARGET" ]; then
+  fail "target not found: $TARGET"
+  exit 1
+fi
+
+# --- collect candidate files (portable; no mapfile) ------------------------
+markup_files=""
+robots_files=""
+json_files=""
+if [ -d "$TARGET" ]; then
+  while IFS= read -r f; do markup_files="${markup_files}${f}
+"; done <<EOF
+$(find "$TARGET" -type f \( -name '*.html' -o -name '*.htm' \) 2>/dev/null)
+EOF
+  while IFS= read -r f; do json_files="${json_files}${f}
+"; done <<EOF
+$(find "$TARGET" -type f \( -name '*.json' -o -name '*.jsonld' \) 2>/dev/null)
+EOF
+  while IFS= read -r f; do robots_files="${robots_files}${f}
+"; done <<EOF
+$(find "$TARGET" -type f -name 'robots.txt' 2>/dev/null)
+EOF
+else
+  case "$TARGET" in
+    *.html|*.htm) markup_files="$TARGET" ;;
+    *.json|*.jsonld) json_files="$TARGET" ;;
+    *robots.txt) robots_files="$TARGET" ;;
+    *) markup_files="$TARGET" ;;  # treat unknown single file as markup-bearing
+  esac
+fi
+
+# Strip blank lines.
+markup_files="$(printf '%s\n' "$markup_files" | grep -v '^[[:space:]]*$' || true)"
+json_files="$(printf '%s\n' "$json_files" | grep -v '^[[:space:]]*$' || true)"
+robots_files="$(printf '%s\n' "$robots_files" | grep -v '^[[:space:]]*$' || true)"
+
+scanned=0
+
+DEAD_TYPES='FAQPage Course ClaimReview SpecialAnnouncement VehicleListing EstimatedSalary LearningVideo'
+
+# --- (a) dead schema types, across markup + json ---------------------------
+all_for_dead="$(printf '%s\n%s\n' "$markup_files" "$json_files" | grep -v '^[[:space:]]*$' || true)"
+if [ -n "$all_for_dead" ]; then
+  printf '%s\n' "$all_for_dead" | while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    for t in $DEAD_TYPES; do
+      # match "@type": "FAQPage" with flexible spacing/quoting
+      if grep -Eq "@type[\"']?[[:space:]]*:[[:space:]]*[\"']?$t([\"',}[:space:]]|$)" "$f"; then
+        printf 'DEAD %s %s\n' "$t" "$f"
+      fi
+    done
+  done > /tmp/seo_geo_dead.$$  2>/dev/null || true
+  if [ -s /tmp/seo_geo_dead.$$ ]; then
+    while IFS= read -r line; do
+      t="$(printf '%s' "$line" | awk '{print $2}')"
+      f="$(printf '%s' "$line" | cut -d' ' -f3-)"
+      fail "dead schema @type '$t' in $f — deprecated/retired, dead markup"
+    done < /tmp/seo_geo_dead.$$
+  fi
+  rm -f /tmp/seo_geo_dead.$$ 2>/dev/null || true
+fi
+
+# --- (b) JSON-LD validity + @context/@type --------------------------------
+json_parser=""
+if command -v python3 >/dev/null 2>&1; then json_parser="python3"; fi
+
+if [ -n "$json_files" ]; then
+  printf '%s\n' "$json_files" | while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    scanned=1
+    if [ -n "$json_parser" ]; then
+      python3 - "$f" <<'PY'
+import json, sys
+p = sys.argv[1]
+try:
+    with open(p) as fh:
+        data = json.load(fh)
+except Exception:
+    sys.exit(3)
+def has(d):
+    if isinstance(d, dict):
+        return ("@context" in d and "@type" in d) or any(has(v) for v in d.values())
+    if isinstance(d, list):
+        return any(has(x) for x in d)
+    return False
+sys.exit(0 if has(data) else 4)
+PY
+      rc=$?
+      if [ "$rc" -eq 3 ]; then echo "JSONERR-PARSE $f"; elif [ "$rc" -eq 4 ]; then echo "JSONERR-CTX $f"; fi
+    fi
+  done > /tmp/seo_geo_json.$$ 2>/dev/null || true
+  if [ -z "$json_parser" ]; then
+    warn "python3 not found — skipping JSON-LD validity/@context check"
+  fi
+  if [ -s /tmp/seo_geo_json.$$ ]; then
+    while IFS= read -r line; do
+      kind="$(printf '%s' "$line" | awk '{print $1}')"
+      f="$(printf '%s' "$line" | cut -d' ' -f2-)"
+      case "$kind" in
+        JSONERR-PARSE) fail "invalid JSON in $f" ;;
+        JSONERR-CTX)   fail "JSON-LD missing @context/@type in $f" ;;
+      esac
+    done < /tmp/seo_geo_json.$$
+  fi
+  rm -f /tmp/seo_geo_json.$$ 2>/dev/null || true
+fi
+
+# --- (c) head discipline: title<=60, meta desc<=160, exactly one h1 --------
+if [ -n "$markup_files" ]; then
+  printf '%s\n' "$markup_files" | while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    # title length
+    title="$(tr '\n' ' ' < "$f" | grep -oiE '<title>[^<]*</title>' | head -1 | sed -E 's/<\/?title>//gI')"
+    if [ -n "$title" ]; then
+      tlen=$(printf '%s' "$title" | wc -c | tr -d ' ')
+      if [ "$tlen" -gt 60 ]; then echo "TITLE $tlen $f"; fi
+    fi
+    # meta description length
+    desc="$(tr '\n' ' ' < "$f" | grep -oiE "<meta[^>]+name=[\"']description[\"'][^>]*>" | head -1 | grep -oiE "content=[\"'][^\"']*[\"']" | head -1 | sed -E "s/content=[\"']//I; s/[\"']$//")"
+    if [ -n "$desc" ]; then
+      dlen=$(printf '%s' "$desc" | wc -c | tr -d ' ')
+      if [ "$dlen" -gt 160 ]; then echo "DESC $dlen $f"; fi
+    fi
+    # h1 count
+    h1c="$(tr '\n' ' ' < "$f" | grep -oiE '<h1[ >]' | wc -l | tr -d ' ')"
+    if [ "$h1c" != "0" ] && [ "$h1c" != "1" ]; then echo "H1 $h1c $f"; fi
+  done > /tmp/seo_geo_head.$$ 2>/dev/null || true
+  if [ -s /tmp/seo_geo_head.$$ ]; then
+    while IFS= read -r line; do
+      kind="$(printf '%s' "$line" | awk '{print $1}')"
+      n="$(printf '%s' "$line" | awk '{print $2}')"
+      f="$(printf '%s' "$line" | cut -d' ' -f3-)"
+      case "$kind" in
+        TITLE) fail "<title> is $n chars (>60) in $f" ;;
+        DESC)  fail "meta description is $n chars (>160) in $f" ;;
+        H1)    fail "$n <h1> elements (expected exactly 1) in $f" ;;
+      esac
+    done < /tmp/seo_geo_head.$$
+  fi
+  rm -f /tmp/seo_geo_head.$$ 2>/dev/null || true
+fi
+
+# --- (d) robots.txt not self-blocking search/citation bots -----------------
+SEARCH_BOTS='Googlebot OAI-SearchBot PerplexityBot Claude-SearchBot'
+if [ -n "$robots_files" ]; then
+  printf '%s\n' "$robots_files" | while IFS= read -r rf; do
+    [ -f "$rf" ] || continue
+    # Walk groups: a User-agent line opens a group; collect bots until a Disallow: /.
+    awk -v bots="$SEARCH_BOTS" '
+      function lc(s){return tolower(s)}
+      BEGIN{ n=split(bots,B," "); for(i=1;i<=n;i++) want[lc(B[i])]=B[i]; ng=0 }
+      {
+        line=$0
+        sub(/#.*/,"",line)
+        gsub(/\r/,"",line)
+        if (line ~ /^[[:space:]]*[Uu]ser-agent[[:space:]]*:/) {
+          if (!inblock){ delete cur; cc=0; inblock=1 }
+          ua=line; sub(/^[^:]*:[[:space:]]*/,"",ua); gsub(/[[:space:]]+$/,"",ua)
+          cur[++cc]=ua
+          next
+        }
+        if (line ~ /^[[:space:]]*[Dd]isallow[[:space:]]*:/) {
+          val=line; sub(/^[^:]*:[[:space:]]*/,"",val); gsub(/[[:space:]]+$/,"",val)
+          if (val=="/"){ for(i=1;i<=cc;i++){ b=lc(cur[i]); if (b in want) print want[b] } }
+          next
+        }
+        if (line ~ /[^[:space:]]/ && line !~ /^[[:space:]]*[Aa]llow[[:space:]]*:/ && line !~ /^[[:space:]]*[Ss]itemap[[:space:]]*:/ && line !~ /^[[:space:]]*[Cc]rawl-delay/) {
+          inblock=0
+        }
+      }
+    ' "$rf" | sort -u | while IFS= read -r bot; do
+      [ -n "$bot" ] && echo "ROBOTS $bot $rf"
+    done
+  done > /tmp/seo_geo_robots.$$ 2>/dev/null || true
+  if [ -s /tmp/seo_geo_robots.$$ ]; then
+    while IFS= read -r line; do
+      bot="$(printf '%s' "$line" | awk '{print $2}')"
+      f="$(printf '%s' "$line" | cut -d' ' -f3-)"
+      fail "robots.txt blocks search/citation bot '$bot' (Disallow: /) in $f — removes you from that engine's results/citations"
+    done < /tmp/seo_geo_robots.$$
+  fi
+  rm -f /tmp/seo_geo_robots.$$ 2>/dev/null || true
+fi
+
+# --- verdict ---------------------------------------------------------------
+if [ -z "$markup_files" ] && [ -z "$json_files" ] && [ -z "$robots_files" ]; then
+  ok "no SEO artifacts under '$TARGET' — nothing to lint"
+  exit 0
+fi
+
+if [ "$failures" -eq 0 ]; then
+  ok "seo-geo artifacts pass: no dead schema, valid JSON-LD, head limits, robots not self-blocking"
+  exit 0
+fi
+
+printf '%s\n' "${RED}${failures} violation(s) — fix before shipping.${RESET}"
+exit 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 and JSON templates), apps (Remix with the versioned GraphQL Admin API and its query-cost model), and checkout (UI extensions, Functions, Web Pixels), plus the CLI flow and checkout-extensibility migration. NOT WooCommerce or PHP stores (that is `wordpress`), NOT the React 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.