@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/bootstrap.md

@@ -0,0 +1,260 @@
+# Stage 0 — Bootstrap
+
+Serial, single agent, runs once at the start. ~30s budget.
+
+**Read first:** `zcommerce-docs/theme-structure.md` (required folder layout, naming conventions) and `zcommerce-docs/setup-guide.md` (CLI commands, `?format=json` data inspection tip). The folder structure bootstrap creates must match exactly what these docs prescribe.
+
+**Start the build clock** — write `.claude/scratchpad/<theme>/build-started.json`:
+
+```json
+{ "theme": "<theme_name>", "started_at": "<ISO8601>", "figma_file_key": "<key>" }
+```
+
+**Ask developer for dev config** — before any browser work, collect `storeUrl` and confirm page URLs. Write `.claude/scratchpad/<theme>/dev-config.json`:
+
+```json
+{
+  "store_url": "",
+  "page_urls": {},
+  "confirmed_by_developer": false
+}
+```
+
+See `dev-server-and-urls.md`. Do not navigate until `confirmed_by_developer` is true.
+
+Stage 2 runs `record-build-metrics.mjs` against build-started.json. See `build-metrics.md`.
+
+## Core principle
+
+Bootstrap creates an **empty theme**. It does NOT copy any `.liquid` file, snippet, asset, image, or font from any existing theme. Every visual artefact in the finished theme is either:
+
+1. Generated from the developer's guidelines frame (tokens), or
+2. Extracted from the developer's per-page Figma frames (sections, assets), or
+3. Written fresh by the page agents and the common-pages agent (Liquid markup, snippets) from the official docs — never copied from another theme.
+
+There is no base theme to copy from. Agents build fresh code for this theme from the official ZCommerce docs (`zcommerce-docs/`).
+
+## What bootstrap produces
+
+```
+<theme_name>/
+  assets/
+    fingerprint.json       (empty {} — populated by agents from Figma assets)
+    main.css               (Tailwind entry — @import theme-settings.css + @tailwind directives)
+    theme-settings.css     (utility classes for tokens — sr-only, font-heading, etc.)
+  i18n/
+    en.json                ({} — keys appended by agents during build)
+    en.schema.json         ({} — keys appended by agents during build)
+  layouts/
+    theme.liquid           (written fresh — see step 3)
+    accounts.liquid        (written fresh — see step 3)
+    sitemap.liquid         (written fresh — see step 3)
+  pages/                   (empty — page JSONs written by page agents + common-pages agent)
+  sections/                (empty — section .liquid files written by agents)
+  snippets/                (empty — snippets written by agents when needed)
+  settings/
+    schema.json            (generated from guidelines frame)
+    theme.json             (generated from guidelines frame)
+  figma-variables.json     (generated from guidelines frame)
+  tailwind.config.js       (generated from guidelines frame)
+  postcss.config.js        (generated from a standard template)
+  package.json             (generated with new theme name)
+  project.json             (generated with new theme name)
+```
+
+## Steps
+
+### 1. Validate inputs
+
+- Theme name (snake-case, no existing folder with this name).
+- `figma_file_key` from command (required for full theme build).
+- Page map from **auto-discovery** (`figma-discovery.md`) — NOT from developer-pasted URLs unless discovery failed.
+- Guidelines tokens from Guidelines frame inside the discovered file (see `inputs/guidelines-frame.md`).
+
+If `figma_file_key` was provided, run discovery first. Only ask for page URLs when discovery fails. Never ask which theme to use as a template.
+
+### 2. Create folder structure
+
+```bash
+THEME=<theme_name>          # snake-case, e.g. orange_market
+THEME_KEBAB="${THEME//_/-}"
+
+mkdir -p $THEME/{assets,i18n,layouts,sections,snippets,settings,pages,thumbnail_images}
+
+# Empty files that need to exist for the build pipeline
+echo '{}' > $THEME/assets/fingerprint.json
+echo '{}' > $THEME/i18n/en.json
+echo '{}' > $THEME/i18n/en.schema.json
+```
+
+Notice: **no `cp` commands.** Bootstrap copies nothing from any theme.
+
+### 3. Synthesize layout files
+
+Layout files (`theme.liquid`, `accounts.liquid`, `sitemap.liquid`) are mostly identical across themes by convention — they're HTML wrappers that handle `<head>`, asset/font loading, the `content_for_*` hooks, and footer scripts.
+
+Bootstrap synthesizes these by:
+1. Reading `zcommerce-docs/layouts.md` for the required structure (what `content_for_header` / `content_for_layout` / `content_for_footer` do, where they must go).
+2. Writing a fresh `layouts/theme.liquid` using the new theme's tokens (font preloads from `theme.json`, asset URLs via `asset_url` filter, semantic HTML).
+
+The result must follow the documented layout conventions. The agent reads for *what content goes where* from the docs, not from any other theme file.
+
+Same for `accounts.liquid` and `sitemap.liquid`.
+
+### 4. Extract tokens from the guidelines frame
+
+Follow `inputs/guidelines-frame.md` end to end:
+1. Call `get_screenshot` on the guidelines node at `maxDimension: 2400` with `enableBase64Response: true`.
+2. Read the rendered image with vision — extract fonts, colors, button states, component specs.
+3. Map names to schema keys (PRIMARY → `color_primary`, BOARDER typo → `color_border`, etc.).
+4. Derive on-colors via WCAG contrast math.
+5. Write to `settings/theme.json`, `settings/schema.json`, `figma-variables.json`.
+
+### 5. Generate tailwind.config.js
+
+Write a fresh `tailwind.config.js` extending Tailwind with CSS variables for every token in `theme.json`:
+- `theme.extend.colors.primary` → `var(--color-primary)` (and so on for each color)
+- `theme.extend.spacing` for each space token
+- `theme.extend.borderRadius` for each radius
+- `theme.extend.fontFamily.heading` and `.body` from the guidelines frame
+
+The content paths array must point at the new theme's directories (paths are relative to the theme root):
+```js
+content: [
+  './pages/*.liquid',
+  './sections/*.liquid',
+  './snippets/*.liquid',
+  './layouts/*.liquid',
+  './assets/*.js',
+],
+```
+
+Use Tailwind v3 conventions (the project's standard).
+
+### 6. Generate postcss.config.js, assets/main.css, package.json, project.json
+
+Match the standard multi-theme pattern — do not use bare `npx @zohofinance/commerce` stubs.
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: { tailwindcss: {}, autoprefixer: {} },
+};
+```
+
+```css
+/* assets/main.css */
+@import 'theme-settings.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+html, body { height: 100%; display: flex; flex-direction: column; }
+footer { margin-top: auto; }
+```
+
+```css
+/* assets/theme-settings.css — minimal utilities; agents may extend */
+.font-heading { font-family: var(--font-heading); }
+.font-body { font-family: var(--font-body); }
+.max-w-container-theme { max-width: var(--page-width); }
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border-width: 0; }
+```
+
+**Naming convention:**
+- `package.json` → `"name": "<theme_name>"` (snake_case folder name, e.g. `my_theme`)
+- `project.json` → `"name": "<theme-kebab>"` (underscores → hyphens, e.g. `my-theme`)
+
+```json
+// package.json — replace <theme_name> with the folder name
+{
+  "name": "<theme_name>",
+  "version": "1.0.0",
+  "type": "module",
+  "zcommerce": {
+    "thumbnail_images": {
+      "desktop_image": "thumbnail_images/desktop.png",
+      "mobile_image": "thumbnail_images/mobile.png"
+    }
+  },
+  "scripts": {
+    "prebuild:dev": "tailwindcss -i ./assets/main.css -o ./assets/style.css",
+    "dev": "yarn prebuild:dev && npx @zohofinance/commerce theme dev",
+    "build": "npx @zohofinance/commerce theme build"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "@zohofinance/commerce": "latest",
+    "postcss": "^8.4.38"
+  },
+  "devDependencies": {
+    "autoprefixer": "^10.4.19",
+    "tailwindcss": "^3.4.3"
+  },
+  "volta": {
+    "node": "18.20.4",
+    "yarn": "1.22.10"
+  }
+}
+```
+
+Also create `thumbnail_images/` (empty — designer adds desktop.png / mobile.png before deploy).
+
+### 7. Hard assertions before handing off
+
+Bootstrap MUST exit with `FATAL` if any of these are violated:
+
+```bash
+# No .liquid files copied from anywhere
+test "$(find $THEME -name '*.liquid' -not -path '*/layouts/*' | wc -l)" -eq 0 || \
+  { echo "FATAL: .liquid files exist outside layouts/ — bootstrap should not create sections/snippets" >&2; exit 1; }
+
+# layouts/ has exactly the three expected files
+test "$(ls $THEME/layouts/ | wc -l)" -eq 3 || \
+  { echo "FATAL: layouts/ should contain exactly theme.liquid, accounts.liquid, sitemap.liquid" >&2; exit 1; }
+
+# assets/ has only bootstrap stubs (no images/fonts copied from sibling themes)
+ALLOWED_ASSETS='^(fingerprint\.json|main\.css|theme-settings\.css)$'
+test "$(ls $THEME/assets/ | grep -Ev "$ALLOWED_ASSETS" | wc -l)" -eq 0 || \
+  { echo "FATAL: assets/ should only contain fingerprint.json, main.css, theme-settings.css at bootstrap" >&2; ls $THEME/assets/; exit 1; }
+
+# pages/ is empty (page agents create them)
+test "$(ls $THEME/pages/ 2>/dev/null | wc -l)" -eq 0 || \
+  { echo "FATAL: pages/ should be empty after bootstrap" >&2; exit 1; }
+
+# project.json + package.json have the new name (package = folder, project = kebab)
+grep -q "\"name\": \"$THEME\"" $THEME/package.json || \
+  { echo "FATAL: package.json name must be $THEME" >&2; exit 1; }
+grep -q "\"name\": \"$THEME_KEBAB\"" $THEME/project.json || \
+  { echo "FATAL: project.json name must be $THEME_KEBAB" >&2; exit 1; }
+
+# Tailwind entry exists
+test -f $THEME/assets/main.css || \
+  { echo "FATAL: assets/main.css missing" >&2; exit 1; }
+
+# theme.json reflects guidelines frame tokens (sanity-check primary is set)
+python3 -c "import json; d=json.load(open('$THEME/settings/theme.json')); assert d['presets']['default']['color_primary'].startswith('#'), 'primary color not set'" \
+  || { echo "FATAL: theme.json tokens not populated from guidelines frame" >&2; exit 1; }
+```
+
+### 8. Emit a stage-0 report
+
+```
+Stage 0 — Bootstrap complete (32s)
+  ├─ theme: orange_market
+  ├─ folders created: 8 (all empty except config + tokens)
+  ├─ tokens: 47 extracted from guidelines frame
+  ├─ layouts: 3 written fresh (synthesized from docs)
+  ├─ tailwind.config.js + theme.json + figma-variables.json generated
+  └─ pages/, sections/, snippets/, assets/ all empty — agents build them
+
+Next: stage 1 — index agent (builds header + footer + index sections)
+```
+
+## Failure modes
+
+- **Guidelines frame URL missing or unreadable** → ask developer once. Without the guidelines frame, the skill cannot produce a theme.
+- **Theme name already exists** → ask whether to overwrite. Never silently overwrite — the developer might lose work.
+- **Sandbox can't reach Figma** → fall back to base64 mode for screenshots, surface specific assets the developer needs to export manually.
+- **Hex codes unreadable in the guidelines screenshot** → re-render at `maxDimension: 3600`. If still unreadable, ask developer for the hex values once.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/build-metrics.md

@@ -0,0 +1,89 @@
+# Build metrics — mandatory end-of-run report
+
+Every `/build-theme` run MUST end with a metrics block in `.claude/scratchpad/<theme>/report.md`.
+
+## Record start time (Stage 0)
+
+At bootstrap, write:
+
+```json
+// .claude/scratchpad/<theme>/build-started.json
+{
+  "theme": "<theme_name>",
+  "started_at": "2026-06-10T14:32:00.000Z",
+  "figma_file_key": "<figma_file_key>"
+}
+```
+
+## Collect metrics (Stage 2)
+
+```bash
+node .claude/skills/theme-from-figma/scripts/record-build-metrics.mjs <theme_name>
+```
+
+Paste the script output into `report.md` under `## Build metrics`.
+
+## Report template (append to report.md)
+
+```markdown
+## Build metrics
+
+| Metric | Value |
+|---|---|
+| Wall-clock duration | 42m 18s |
+| Bootstrap | 28s |
+| Page builds (parallel) | 38m 52s (slowest: product) |
+| Consolidation | 2m 58s |
+| Sections built | 23 |
+| Snippets built | 14 |
+| Visual verify loops | 31 (avg 1.4 iterations/section) |
+| Sections with 0 CRITICAL after verify | 21/23 |
+| Pages visually verified (desktop+mobile) | 5/5 |
+| Lighthouse a11y (pages) | 5 pass / 0 fail |
+| Lighthouse perf mobile (pages) | avg 91 |
+| Lint failures fixed during build | 6 |
+| verify-theme.mjs | PASS / FAIL |
+
+### Token estimate (approximate)
+
+Cursor does not expose per-run token counts to agents. Provide a **range estimate** based on run complexity:
+
+| Build profile | Typical agent turns | Approx. tokens |
+|---|---|---|
+| Small theme (≤15 sections, 1 iteration each) | 80–120 | 800K–1.5M |
+| Medium theme (20–30 sections, 1–2 iterations) | 150–250 | 1.5M–3M |
+| Large theme (30+ sections, visual re-loops) | 250–400+ | 3M–6M+ |
+
+Record what you observe:
+- **Estimated input tokens:** ~2.8M (based on 5 page orchestrators + 23 section subagents + consolidation)
+- **Estimated output tokens:** ~420K
+- **Confidence:** low / medium / high
+
+Factors that increase cost: visual re-loops (>2 per section), stalled subagents, whole-page fixes, large Figma frames.
+
+### Cost / time insights for developers
+
+- **Parallel page agents** save wall-clock (~5× vs serial) but do not reduce total tokens.
+- **Per-section Chrome DevTools verify** is the highest-ROI step for Figma fidelity — skipping it is why output drifted.
+- **First-time builds** average 35–60 min wall-clock for a 5-page theme.
+- **Re-runs** on a single page after feedback: 5–15 min.
+
+### Per-page breakdown
+
+| Page | Sections | Wall time | Visual iters | CRITICAL remaining |
+|---|---|---|---|---|
+| index | 8 | 12m 04s | 9 | 0 |
+| product | 2 | 8m 22s | 4 | 0 |
+| collection | 2 | 6m 15s | 3 | 0 |
+| blog_list | 2 | 4m 48s | 2 | 0 |
+| blog_detail | 2 | 5m 10s | 2 | 0 |
+```
+
+## Who writes what
+
+| Agent | Writes |
+|---|---|
+| Bootstrap (Stage 0) | `build-started.json` |
+| Section subagent | `pages/<page>/sections/<section>/visual-diff.md` with iteration count |
+| Page orchestrator | `pages/<page>/report.md` with page wall time |
+| Consolidator (Stage 2) | Runs `record-build-metrics.mjs`, final `report.md` |

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/code-quality.md

@@ -0,0 +1,186 @@
+# Code quality — strict budgets, enforced at write time
+
+The single biggest source of past iterations was AI-generated code being structurally heavier than necessary. This document defines hard budgets and the write-time lint that enforces them. **The lint script (`scripts/lint-section.mjs`) is the source of truth — these rules describe what it checks.**
+
+**Read also:** `zcommerce-docs/best-practices.md` — the official ZCommerce best-practices doc covering performance (minify, defer JS, async, preload), security (escape user output, avoid inline scripts from settings, use `json` filter for data), and accessibility (semantic HTML, alt text, form labels, heading hierarchy). The lint catches the syntactic violations of these rules; the doc explains the reasoning.
+
+## Budgets (calibrated to existing exemplars)
+
+| Metric | Budget | Why | Exemplar reference |
+|---|---:|---|---|
+| Tailwind utility classes per element | **≤ 12** | More than ~12 = unreadable class soup; extract to `{% style %}` block. | hero-banner.liquid (max 14 was top of range; we tighten to 12). |
+| DOM nesting depth per section | **≤ 6** | Anything deeper indicates redundant wrappers. | All exemplars are 3–6. |
+| Section file total lines | **≤ 250** | Section files over ~250 lines should be split into snippets. | Largest exemplar is 238 (blog-list); typical 80–170. |
+| Empty wrapper `<div>`s | **0** | A wrapper that contains a single element with no layout role is removable. | All exemplars have zero. |
+| `{% if %}` nesting depth | **≤ 2** | Three-deep `if` chains indicate a `case` is needed. | Exemplars use `case` for branching. |
+| Top-level `{% liquid %}` block | **1** | All `assign`s in one block at the top, not scattered. | Standard hero-banner pattern across themes. |
+| Inline `onclick=` / `onload=` etc. | **0** | All JS via `data-*` + external script. | CLAUDE.md rule. |
+| Hardcoded hex colors | **0** | Always a theme token. | CLAUDE.md rule. |
+| Hardcoded px font-size in inline `style=` | **0** | Use Tailwind class or `{% style %}` block. | CLAUDE.md rule. |
+| Schema fields not wired to markup | **0** | Every `id` in `{% schema %}` settings is referenced by the markup. | The most common build error. |
+| `rounded-*` without spec radius | **0** | Only if `figma-spec.json` has `border_radius > 0` for that element. | `transcription-rules.md` |
+| Product grid images without fixed media box | **flag** | Cards must use spec `w`×`h` + `object-fit` — not natural img height. | Uneven card heights bug |
+
+## Soft signals (warn, don't block)
+
+| Signal | Threshold | Comment |
+|---|---|---|
+| Sections that look like header/footer | should never go to `sections/header.liquid` etc — those are locked | If you find yourself wanting to write header content, you took the wrong work. |
+| Use of arbitrary Tailwind values `text-[19px]` | > 3 per section | Means the design isn't on the token grid. Consider adding a token. |
+| `<div>` to `<div class="...">` ratio | > 30% bare divs | Likely missing semantic elements (`<section>`, `<article>`, `<nav>`). |
+
+---
+
+## Pre-write checklist (run mentally before writing each section file)
+
+The agent must answer each before writing:
+
+1. **Anchor exemplar identified?** What's the closest match in `exemplars.md` and what are its metrics?
+2. **Element count?** Roughly how many DOM elements will this section have? If > 1.5× the exemplar's, why?
+3. **Max class count per element?** Mentally count classes on the most-styled element. If > 12, plan to move them to `{% style %}`.
+4. **DOM depth?** Sketch the hierarchy. If > 6 levels deep, identify the redundant wrappers.
+5. **Schema field count?** List the fields you'll define. For each, where will it appear in markup?
+6. **Liquid logic complexity?** Any `if` inside `if` inside `for`? Refactor before writing.
+
+If any answer is suspicious, **re-plan, don't write**. Bad code is harder to delete than to never write.
+
+---
+
+## Write-time lint (run by the agent after writing each section, automated)
+
+The agent runs:
+
+```bash
+node .claude/skills/theme-from-figma/scripts/lint-section.mjs \
+  sections/<section_name>.liquid
+```
+
+The script outputs a JSON report:
+
+```json
+{
+  "file": "lush_market/sections/hero-banner.liquid",
+  "lines": 98,
+  "checks": {
+    "lines_under_250":      { "pass": true,  "actual": 98 },
+    "max_classes_per_el":   { "pass": true,  "actual": 11, "budget": 12, "elementHint": "<a class=\"...\">" },
+    "max_dom_depth":        { "pass": true,  "actual": 5,  "budget": 6 },
+    "empty_wrappers":       { "pass": true,  "count": 0 },
+    "if_nesting_depth":     { "pass": true,  "actual": 1,  "budget": 2 },
+    "single_liquid_block":  { "pass": true,  "actual": 1 },
+    "inline_event_handlers":{ "pass": true,  "count": 0 },
+    "hardcoded_hex":        { "pass": true,  "count": 0 },
+    "hardcoded_inline_px":  { "pass": true,  "count": 0 },
+    "schema_fields_wired":  { "pass": false, "unused": ["unused_subtext"], "wired": 8, "total": 9 },
+    "render_not_include":   { "pass": true,  "count_include": 0 },
+    "escape_user_output":   { "pass": true,  "warnings": [] }
+  },
+  "verdict": "FAIL"
+}
+```
+
+If `verdict === "FAIL"`, the agent **must fix** before continuing. The agent is not allowed to silence a check.
+
+## Common rejections and how to fix
+
+### `max_classes_per_el` failure
+
+The lint shows the offending element. Move repeating utility classes into a `{% style %}` block:
+
+```liquid
+<!-- BEFORE: 18 classes -->
+<a class="inline-flex items-center justify-center px-theme-8 py-theme-3 bg-primary text-on-primary font-semibold rounded-theme-button hover:bg-primary-hover focus:ring-2 focus:ring-offset-2 transition-colors text-base md:text-lg">
+  {{ block.settings.button_label }}
+</a>
+
+<!-- AFTER: 1 class, 1 attribute -->
+<a class="cta-btn" href="{{ block.settings.button_link.handle }}">{{ block.settings.button_label }}</a>
+
+{% style %}
+  #section-{{ section.id }} .cta-btn {
+    display: inline-flex; align-items: center; justify-content: center;
+    padding: var(--space-3) var(--space-8);
+    background: var(--color-primary); color: var(--color-on-primary);
+    font-weight: 600; border-radius: var(--radius-button);
+    transition: background 0.15s ease;
+  }
+  #section-{{ section.id }} .cta-btn:hover { background: var(--color-accent); }
+{% endstyle %}
+```
+
+### `max_dom_depth` failure
+
+Walk the tree and find redundant wrappers:
+
+```liquid
+<!-- BEFORE: depth 8 -->
+<section>
+  <div>
+    <div class="container">
+      <div class="row">
+        <div class="col">
+          <div class="card">
+            <div class="card-body">
+              <h2>...</h2>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- AFTER: depth 4 -->
+<section id="section-{{ section.id }}" class="hero-section">
+  <div class="max-w-container-theme mx-auto px-theme-4">
+    <article class="hero-card">
+      <h2>...</h2>
+    </article>
+  </div>
+</section>
+```
+
+### `empty_wrappers` failure
+
+A `<div>` whose only child is another single element with no layout role:
+
+```liquid
+<!-- BEFORE -->
+<div>
+  <div class="text-center">
+    <h2>{{ heading }}</h2>
+  </div>
+</div>
+
+<!-- AFTER -->
+<h2 class="text-center">{{ heading }}</h2>
+```
+
+### `schema_fields_wired` failure
+
+The schema declares a setting but the markup never references it. Either wire it or remove it:
+
+```liquid
+{% schema %}
+{
+  "settings": [
+    { "type": "text", "id": "heading", "default": "..." },
+    { "type": "text", "id": "subheading", "default": "..." }   ← never referenced!
+  ]
+}
+{% endschema %}
+```
+
+Remove `subheading` from the schema, or add `{{ section.settings.subheading }}` somewhere.
+
+---
+
+## What the lint does NOT check
+
+- Visual fidelity → that's the pixel-diff gate (`verification.md`).
+- Accessibility violations → that's the a11y gate.
+- Performance → that's the perf gate.
+- Semantic correctness (does `<article>` make sense here?) → human judgment.
+- Typos in copy → not the lint's job.
+
+The lint exists for structural code quality. The four gates exist for behavioral correctness. Both layers run.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/common-pages-agent.md

@@ -0,0 +1,97 @@
+# Common-pages agent (Stage 1c)
+
+While the index agent and four parallel page agents build the Figma-driven pages, a sixth agent handles the **common pages** that have no Figma: cart, checkout, account flows, 404, signin, signup, forgotpassword, custom-page, payment, sitemap, orders.
+
+These pages exist in every theme but don't have per-theme designs in the input. The agent's job: read multiple themes' implementations to learn the LOGIC, then write fresh code that applies the new theme's tokens.
+
+## Why a separate agent
+
+Common pages have business logic (cart calculations, checkout steps, account form validation) that the index/page agents don't need to know. Isolating them in one agent:
+1. Keeps the page agents focused on Figma-driven sections.
+2. Lets the common-pages agent specialize in reading across many themes for any one archetype.
+3. Allows parallel work — common-pages agent runs alongside the page agents.
+
+## When it runs
+
+Stage 1c runs **in parallel with** Stage 1b (the four page agents that wait for the header-footer-ready marker). It does NOT wait for the marker because the common pages don't render the header/footer during the agent's own per-section verification (those layouts wrap them, but per-section gates use just the section's HTML).
+
+```
+Stage 1a:   index agent (header + footer + index sections)            ████████████ ~4min
+Stage 1b:                                              listing        ─────────────████ ~3min
+                                                       product        ─────────────█████ ~5min
+                                                       blog_list      ─────────────███ ~2min
+                                                       blog_detail    ─────────────███ ~2min
+Stage 1c:   common-pages agent (cart, checkout, etc.)                 ─────────████████ ~5min
+```
+
+## Inputs
+
+From the orchestrator:
+- Theme folder path.
+- Scratchpad path at `.claude/scratchpad/<theme>/common-pages/`.
+- Locked files: `theme.json`, `tailwind.config.js`, `figma-variables.json` (no header/footer lock — they don't exist yet when this agent starts; the agent waits for the header-footer-ready marker before its own per-page verification step, not before writing).
+
+## Pages it owns
+
+| Page route | Page JSON | Section files this agent writes |
+|---|---|---|
+| `/cart` | `pages/cart.json` | `cart-list.liquid`, `cart-popup.liquid`, `cart-empty.liquid` snippet |
+| `/checkout` | `pages/checkout.json` | `checkout.liquid` + `checkout-steps.liquid` snippet |
+| `/account/profile` | `pages/account-profile.json` | `account-profile.liquid` + `account-tab-navigation.liquid` |
+| `/account/address` | `pages/account-address.json` | `account-address.liquid` + `account-address-card.liquid` snippet |
+| `/account/orders` | `pages/account-order.json` | `account-order.liquid` |
+| `/account/order/<id>` | `pages/account-order-detail.json` | `accounts-order-details.liquid` |
+| `/account/order/<id>/status` | `pages/account-order-status.json` | `account-order-status.liquid` |
+| `/orders` | `pages/orders.json` | `orders.liquid` |
+| `/payment/<status>` | `pages/payment.json` | (status sections) |
+| `/signin` | `pages/signin.json` | `signin.liquid` |
+| `/signup` | `pages/signup.json` | `signup.liquid` |
+| `/forgotpassword` | `pages/forgotpassword.json` | `forgotpassword.liquid` |
+| `/404` | `pages/404.json` | `404.liquid` |
+| `/page/<slug>` | `pages/page.json` | `page.liquid` |
+| `/sitemap` | `pages/sitemap.json` | (uses `layouts/sitemap.liquid`) |
+
+## Workflow per archetype
+
+For each archetype above:
+
+1. **Explore.** Read every theme's implementation of this archetype (per `exemplars.md` § "Archetype → candidate themes"). Read minimum three; ideally all that have one.
+2. **Synthesize logic.** Identify common patterns:
+   - Cart: line-item rendering, quantity controls, totals, coupon, checkout CTA, empty state.
+   - Checkout: step navigation, address forms, shipping/payment selection, order summary.
+   - Account: tabbed nav, form fields per page, edit/save states.
+3. **Plan fresh markup.** Sketch DOM, schema fields, snippet decomposition. Apply the new theme's tokens (`var(--color-*)`, `var(--space-*)`, `var(--radius-*)`, `var(--font-*)`).
+4. **Write fresh.** Each section file goes through the same lint as page agents (`lint-section.mjs`). All lint rules apply — i18n keys, tag validity, filter validity, scope sanity, no hardcoded design.
+5. **Update page JSON.** Wire the new section into the corresponding `pages/<page>.json`.
+6. **Append translation keys.** Runtime keys to `en.json`, schema labels to `en.schema.json`.
+7. **Per-page verify.** Once header/footer-ready marker exists, run the gates against each common page:
+   - Pixel-diff: **no Figma to compare against**. Skip this gate for common pages, OR compare against a deterministic baseline (the same rendered page after a no-op rebuild — sanity check, not pixel-accuracy).
+   - a11y: MANDATORY. Axe must pass on every common page.
+   - Lighthouse: MANDATORY. Perf score ≥ 85 mobile.
+8. **Iterate** up to 3 passes per page on a11y or perf failures.
+9. **Report.**
+
+## Hard rules
+
+- **No `cp` from any theme.** Every line typed fresh.
+- **Read every available implementation** before writing. If you find yourself ready to write after reading only one, stop and read more.
+- **Common pages use the same design tokens as Figma-driven pages.** The cart on the orange theme has orange CTAs, Lato body font, Oswald headings — derived from `theme.json`, not from any sibling theme's cart styling.
+- **Snippets shared between common pages and page-agent pages** (like `pagination`, `product-card` if cart uses it) — coordinate via filename. If the common-pages agent needs `product-card`, it writes a fresh version OR waits for the listing/product agent (whichever finishes first) and uses theirs. The orchestrator coordinates this by giving the common-pages agent visibility into which snippets the other agents are writing.
+
+## Output
+
+```
+PAGE: cart                  ✓ 1m22s  (3 sections, lint pass, axe pass, perf 91)
+PAGE: checkout              ✓ 2m05s  (1 section + checkout-steps snippet, all gates pass)
+PAGE: account-profile       ✓ 0m48s  (1 section + account-tab-navigation, all gates pass)
+PAGE: account-address       ✓ 0m45s
+PAGE: account-order         ✓ 0m32s
+... (etc for all common pages)
+
+SECTIONS WRITTEN: 14
+SNIPPETS WRITTEN: 6
+ITERATIONS: 2 (one a11y fix on checkout, one perf fix on account-order)
+
+NEEDS_REVIEW:
+  - checkout/checkout-steps: stepper accent contrast 4.5:1 at WCAG AA minimum
+```