@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/inputs/guidelines-frame.md

@@ -0,0 +1,178 @@
+# Guidelines frame — canonical token source
+
+ZCommerce theme Figma files follow a convention: every theme has a **guidelines frame** containing typography scale, color palette, button variants, and component micro-specs. This is the source of truth for design tokens — preferred over `get_variable_defs` because it survives URL-only access (no active Figma desktop selection needed) and captures component-level specs that flat variables can't.
+
+## What the frame contains
+
+A standard guidelines frame has six regions, all visible in one screenshot:
+
+| Region | What it gives the skill |
+|---|---|
+| **Typography table** | Heading font family + weights, body font family, full size scale (H1–H6 + body) with line heights. |
+| **Color palette grid** | Named tokens (PRIMARY, SECONDARY, NEUTRAL, ERROR, SUCCESS, WARNING, LINK, BACKGROUND 1, BACKGROUND 2, BORDER) with weight numbers and hex codes. |
+| **Button variants** | Each variant (outlined, filled-large, filled-small, icon) shown in four states: Default / Hover / Pressed / Disabled. Annotated with font, padding, corner radius. |
+| **Form / input components** | Text input, dropdown, checkbox, radio — each with default + focus + error states. |
+| **Misc components** | Tooltip, badge, breadcrumb, pagination, currency selector, menu header, dropdown — each annotated with padding, font, gap. |
+| **Spacing / radius scale** (sometimes) | Spacing multiples (4, 8, 12, 16, …) and radius scale (sm/md/lg/full) if not implied by component examples. |
+
+If a frame is missing some regions, fall back to `get_variable_defs` for the gaps.
+
+## How to extract — protocol
+
+### Step 1: Get the URL from the developer
+
+In Stage 0 of `bootstrap.md`, ask for the guidelines frame URL. Typical form:
+```
+https://www.figma.com/design/{fileKey}/{name}?node-id={nodeId}&m=dev
+```
+
+### Step 2: Render the frame
+
+```
+mcp__32a68a89-...__get_screenshot
+  fileKey: extracted from URL
+  nodeId:  extracted from URL (replace - with :)
+  maxDimension: 2400          # high res — typography px values must be readable
+  enableBase64Response: true  # inline image so the agent's vision can read it
+```
+
+Use `maxDimension: 2400` minimum. Lower than that and the px annotations under each typography sample become unreadable.
+
+### Step 3: Read the rendered image with vision
+
+The agent reads the PNG directly. Walk it region by region.
+
+### Step 4: Extract tokens
+
+For each region, populate the corresponding theme tokens.
+
+#### Typography → `theme.json`
+
+```
+font_heading       = "Oswald"     (from "Heading" label in typography table)
+font_body          = "Lato"       (from "Body" label)
+font_h1_size       = "112px"      (read from H1 sample annotation)
+font_h1_line       = "120px"
+font_h1_weight     = "600"
+font_h2_size       = "56px"       (… same for H2–H6)
+font_body_size     = "14px"
+font_body_line     = "12px"
+font_body_weight   = "400"
+```
+
+If H4 and H5 have identical specs (common — designers sometimes duplicate), record both as the same value — don't collapse.
+
+#### Color palette → `theme.json`
+
+Walk the swatch grid. Each cell has: NAME, weight number (100/200/…), hex. Map names to schema keys:
+
+| Frame label | theme.json key | tailwind.config.js variable |
+|---|---|---|
+| PRIMARY | `color_primary` | `--color-primary` |
+| SECONDARY | `color_accent` | `--color-accent` (semantic remap — "secondary" in the frame = "accent" in the schema) |
+| NEUTRAL | `color_neutral` | `--color-neutral` |
+| ERROR | `color_error` | `--color-error` |
+| SUCCESS | `color_success` | `--color-success` |
+| WARNING | `color_warning` | `--color-warning` |
+| LINK | `color_link` | `--color-link` |
+| BACKGROUND 1 | `color_background` | `--color-background` |
+| BACKGROUND 2 | `color_surface` | `--color-surface` (secondary surface) |
+| BORDER / BOARDER | `color_border` | `--color-border` |
+
+Watch for the "BOARDER" typo — common in real Figma files; treat as `BORDER`.
+
+For each color, derive **on-color** automatically (`color_on_primary`, `color_on_background`, etc.) using contrast math: pick `#FFFFFF` or `#000000` whichever yields better WCAG contrast. Verify result is ≥ 4.5:1; if not, log to `NEEDS_REVIEW`.
+
+#### Button variants → `theme.json` + per-button CSS
+
+Three to four button styles, each with four states. Translate to:
+
+```
+radius_button     = "999px"   (corner radius — visible on annotation, almost always pill or fixed px)
+button_outlined_padding   = "16px 100px"
+button_outlined_font      = "Lato 600"
+button_outlined_default_border  = "#FF24AA"   (color sampled from the default state's border)
+button_outlined_default_bg      = "transparent"
+button_outlined_hover_bg        = "#FF24AA"   (sampled from hover state)
+button_outlined_pressed_bg      = "#FFFFFF"
+button_outlined_disabled_bg     = "#FFE5D9"   (light variant)
+button_outlined_disabled_text   = "#FFB394"
+```
+
+Same shape for filled and icon buttons. Persist to `theme.json` under `buttons.{variant}.{state}.{property}`.
+
+These per-state colors feed the `<style>` blocks in `header.liquid`, `footer.liquid`, and any section's CTA buttons. They're more granular than the flat color palette and they're what make hover/focus states look correct on the first build.
+
+#### Component micro-specs → snippet defaults
+
+Tooltip, badge, breadcrumb, pagination, dropdown, currency selector — each carries:
+- padding (vertical × horizontal)
+- font (family + weight)
+- gap (for pagination)
+
+Record as `component_<name>_padding`, `component_<name>_font`, `component_<name>_gap`. These get baked into the corresponding snippet's default styles.
+
+#### Spacing scale
+
+If the frame has a separate spacing scale, read it. Otherwise infer from button paddings — Lato 16/12/8/4 is the typical scale increment. Persist to `theme.json` under `space_1` through `space_24` (4-multiples).
+
+#### Radius scale
+
+If a separate scale is shown, read it. Otherwise infer:
+- Button corner radius → `radius_button`
+- Card / surface radius from the swatch tiles themselves → `radius_card`
+- Input radius from form components → `radius_input`
+
+Common defaults if the frame doesn't specify:
+- `radius_sm` = 4px, `radius_md` = 8px, `radius_lg` = 16px, `radius_full` = 9999px
+
+### Step 5: Persist
+
+Write the extracted tokens to:
+
+1. `settings/theme.json` — the full token set.
+2. `figma-variables.json` — W3C-shaped tokens (`$type`, `$value`) for use by sections at build time.
+3. `.claude/scratchpad/<theme_name>/bootstrap/guidelines-extraction.md` — a human-readable extraction log so the developer can review what was read.
+
+### Step 6: Hand off
+
+Bootstrap continues to retokenize header.liquid + footer.liquid, lock them, and pass control to the parallel page agents.
+
+## Failure modes
+
+| Problem | Fallback |
+|---|---|
+| No guidelines frame in the file | Ask the developer to point at the page that has the most styled elements. The skill samples colors / fonts from there but the result is lower fidelity — log this as `NEEDS_REVIEW` so the developer knows tokens may need manual review. |
+| Frame is partial (e.g. typography but no buttons) | Extract what's there. For missing regions, call `get_variable_defs` to fill gaps. Anything still missing → ask the developer once. |
+| Hex codes unreadable in the screenshot | Re-render with `maxDimension: 3600`. If still unreadable, fall back to the live Figma variable values for that node via `get_variable_defs`. |
+| Two button variants with the same padding spec (designer error) | Use both — they may be intentional duplicates. Don't auto-deduplicate without asking. |
+| Typo in palette names (e.g. "BOARDER" for BORDER) | Map by closest schema name. Log the typo in extraction notes so the designer can fix it in the source file. |
+
+## What this replaces
+
+- The old `Preset:` block in the developer's input (primary / accent / fonts / radius) is gone. The guidelines frame supplies all of it.
+- `get_variable_defs` becomes a fallback, not the primary path. Useful for files that pre-date the guidelines-frame convention.
+- The "extract-tokens" command from the old skill is fully absorbed into Stage 0 — no separate step.
+
+## Example
+
+For the file at `<your-figma-file-url>` the guidelines frame yields:
+
+```
+font_heading      = Oswald
+font_body         = Lato
+H1: 112/120 · H2: 56/56 · H3: 40/44 · H4: 28/28 · H5: 28/28 · H6: 16/20 · Body: 14/12
+color_primary     = #FF24AA (verify hex via re-render at 3600px)
+color_accent      = (sampled from SECONDARY swatch)
+color_neutral, error, success, warning, link, background_1, background_2, border = (sampled)
+radius_button     = 999px (pill)
+button_outlined   = padding 16×100, Lato 600
+button_filled_lg  = padding 12×40, Lato 600
+button_filled_sm  = padding 16×60, Lato 600
+tooltip_padding   = 8px, Lato 500
+badge_padding     = 12×8, Lato 500
+breadcrumb_padding= 12×8, Lato 500
+pagination_gap    = 24px
+```
+
+All extracted in one screenshot read — zero developer input beyond the URL.

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

@@ -0,0 +1,322 @@
+# DEPRECATED — use page-orchestrator.md (Level A)
+
+This file described the old flat model where one agent built an entire page. **Do not use.**
+
+Use instead:
+- `agent-hierarchy.md` — Level 0 / A / B roles
+- `page-orchestrator.md` — **Level A** (identify sections, spawn Level B, assemble page)
+- `section-builder.md` — **Level B** (build one section from section Figma node only)
+- `parallel-fanout.md` — spawn templates
+
+---
+
+# Page builder (archived reference)
+
+Each of the 5 parallel agents in Stage 1 executed this workflow. Kept for asset-extraction notes only.
+
+**Read alongside this doc** (the official ZCommerce reference, bundled at `zcommerce-docs/`):
+- `zcommerce-docs/sections.md` — section structure, schema rules, block patterns. Read before writing any `.liquid` section.
+- `zcommerce-docs/snippets.md` — snippet variable scoping (the bug-prone area).
+- `zcommerce-docs/reference/schema-types.md` — all valid `{% schema %}` field types and their default JSON shapes (text, url, image_picker, color, range, select, etc.). Read this when defining schema fields, not guessed from memory.
+- `zcommerce-docs/reference/filters.md` — every supported Liquid filter. Lint enforces this list; reading the docs first avoids the trip.
+- `zcommerce-docs/reference/global-objects.md` — `organization`, `pageinfo`, `cart`, `product`, `section`, etc. Read before accessing any top-level Liquid variable.
+- `zcommerce-docs/reference/tags.md` — the 13 supported Liquid tags. **Do NOT use `{% paginate %}`, `{% form %}`, `{% javascript %}`, `{% stylesheet %}` — they don't exist in this engine.**
+- `zcommerce-docs/i18n.md` — translation key conventions; the runtime/schema split that crashed a prior build.
+- `zcommerce-docs/assets.md` — `asset_url` filter usage; fingerprint.json contract.
+- `zcommerce-docs/best-practices.md` — performance, security, accessibility rules (defer scripts, escape user output, semantic HTML).
+
+## Inputs you receive
+
+From the orchestrator (see `parallel-fanout.md`):
+- Your assigned page name and Figma URL.
+- The theme folder path.
+- Your scratchpad path.
+- The list of locked files you must not modify.
+
+## Asset extraction protocol — applies to ALL agents
+
+Every image, logo, icon, font, or graphic used by any section MUST come from the input Figma — never from another theme's `assets/`. After bootstrap, the theme's `assets/` folder is empty (only `fingerprint.json`). Each agent populates it for the assets its sections need.
+
+### Where assets come from
+
+1. **Figma exportable assets.** Most Figma frames have image/icon layers marked as exportable. Use the Dev-Mode MCP:
+   - `mcp__32a68a89-...__get_design_context` on the parent frame returns asset download URLs as part of the response (alongside the structured tree).
+   - Each exportable asset has a node ID and an export format (svg, png@2x, etc.).
+2. **Region crops via screenshot.** For logos, icons, or graphic regions that aren't explicit export targets, use `get_screenshot` with `maxDimension` high enough for the use case (4× for logos/icons, 2× for hero images).
+3. **Fonts.** Read the font family + weights from the guidelines frame (already in `theme.json`). Two options:
+   - Reference Google Fonts via `layouts/theme.liquid` `<link>` tag — preferred for fonts available there (Inter, Lato, Oswald, Playfair, Roboto, etc.).
+   - Download `.woff2` files manually if the font is proprietary and the developer provides them.
+
+### How to fetch and save
+
+The skill's sandbox can't directly download from `figma.com` URLs (the proxy blocks them). Two working paths:
+
+**Path A: base64 inline (works for screenshots).**
+Call `get_screenshot` with `enableBase64Response: true`. The image comes back inline. Save the base64 to a file using bash + `base64 -d`. Use this for logo/icon crops.
+
+**Path B: developer-staged assets folder (for arbitrary image exports).**
+For images the developer pre-exported from Figma into `.claude/scratchpad/<theme>/figma-assets/`, the agent just `cp` them into `assets/` and renames per the naming convention below.
+
+If neither path works (e.g. an asset is only in Figma and can't be screenshotted clean), **ask the developer to export it manually** and surface a `NEEDS_REVIEW` item — never use a placeholder asset from another source.
+
+### Naming convention
+
+Each section namespaces its assets with the section name:
+
+```
+assets/
+  hero-banner-bg-desktop.webp
+  hero-banner-bg-mobile.webp
+  hero-banner-logo-overlay.svg
+  product-card-placeholder.webp
+  footer-logo.svg
+  footer-icon-instagram.svg
+  footer-icon-twitter.svg
+```
+
+Prefix with the section name → no collisions when multiple sections need a similarly-named asset. Use kebab-case throughout.
+
+### Wire into Liquid
+
+Reference assets via `asset_url` filter, NOT hardcoded paths:
+
+```liquid
+<img src="{{ 'hero-banner-bg-desktop.webp' | asset_url }}" alt="{{ section.settings.alt }}">
+```
+
+For section settings that accept an image (via `image_picker`), the developer can override at customization time:
+
+```liquid
+{% liquid
+  assign hero_bg = section.settings.hero_image | default: 'hero-banner-bg-desktop.webp'
+%}
+<img src="{{ hero_bg | asset_url }}" alt="...">
+```
+
+### Update fingerprint.json
+
+After adding new assets, regenerate `fingerprint.json` (the build pipeline does this on `npx @zohofinance/commerce theme build`, but for dev preview you may need a manual entry). Each agent appends its new asset names to the map.
+
+### Forbidden patterns
+
+- Copying assets from any other source — all assets must be extracted from the input Figma.
+- `<img src="https://cdn.{external}.com/...">` — hot-linking external CDNs.
+- Hardcoded image URLs that don't go through `asset_url` filter.
+- Reusing icon SVGs from any external source — they will have the wrong stroke style.
+
+The `verify-theme.mjs` `assets_diverge` check catches these violations.
+
+## Special case: the index agent
+
+The index agent runs **first**, alone, before the four other page agents fan out. It has two extra responsibilities:
+
+### 1. Extract and build the header
+
+From the index Figma frame, identify the top region — typically the first 80–120 px on desktop, the first ~60 px on mobile. This is the site header.
+
+- Call `get_screenshot` with a region selector or crop the full screenshot to the header region.
+- Build `sections/header.liquid` and `sections/header-group.json` from this design.
+- Update `i18n/en.json` (runtime strings) AND `i18n/en.schema.json` (settings labels) with the new keys.
+- Use the design system primitives from `theme.json` (colors, fonts, button styles, etc.) — never hardcode hex or px font sizes.
+- Required elements that the schema MUST support (even if hidden by default): logo, primary nav, search trigger, account icon, cart icon with item count badge, mobile nav drawer toggle.
+
+### 2. Extract and build the footer
+
+From the index Figma frame, identify the bottom region — the last 200–400 px depending on the design. This is the site footer.
+
+- Crop the screenshot to the footer region.
+- Build `sections/footer.liquid` and `sections/footer-group.json`.
+- Append i18n keys.
+- Required elements: logo or brand name, primary footer nav (columns), social-media row, newsletter signup form, copyright line. Skip whichever the design doesn't show but keep the schema fields so the admin can enable them later.
+
+### 3. Publish the ready-marker
+
+After header.liquid and footer.liquid pass the lint AND the verification gates against their respective Figma crops, write a marker file:
+
+```
+touch .claude/scratchpad/<theme>/header-footer-ready
+```
+
+This unblocks the four other page agents. **Do not write this marker if either file failed gates** — the marker is the contract that the locked files are correct.
+
+### 4. Build the rest of the index page
+
+After the marker, continue with the index-page sections (hero, features, products, CTA, newsletter, etc.) using the standard workflow below.
+
+## What the other four agents do at startup
+
+Before doing anything, wait for the marker file:
+
+```bash
+while [ ! -f .claude/scratchpad/<theme>/header-footer-ready ]; do sleep 5; done
+```
+
+Once the marker exists, header.liquid and footer.liquid are locked — read them as you would any locked file, but never modify.
+
+## Outputs you produce
+
+- New `.liquid` files in `sections/`.
+- Updated `pages/<page>.json` wiring those sections.
+- New translation keys appended to `i18n/en.json` and `en.schema.json`.
+- A `report.md` in your scratchpad subdirectory.
+
+---
+
+## Workflow (5 phases — keep moving, don't ask questions mid-build)
+
+### Phase 1 — Intake (~30s)
+
+Pull from Figma in **parallel** (single message, multiple tool calls):
+1. `get_metadata` on the desktop frame.
+2. `get_screenshot` on the desktop frame → save to scratchpad.
+3. `get_metadata` on the mobile frame.
+4. `get_screenshot` on the mobile frame → save to scratchpad.
+5. `get_design_context` on both → save to scratchpad as `figma-context.json`.
+
+If the URL points to a single combined frame, ask `get_design_context` to identify desktop and mobile sub-frames within it.
+
+### Phase 2 — Section plan (~15s)
+
+From the design context, identify the distinct sections on the page top-to-bottom. Typical breakdown:
+
+- **Index:** hero, value props / feature row, featured products, image+text alternating blocks, testimonials, newsletter, CTA banner.
+- **Listing:** category header, filter rail (desktop) / filter drawer (mobile), sort dropdown, product grid, pagination.
+- **Product:** image gallery, product info (title/price/options/CTA), description tabs, related products, reviews.
+- **Blog list:** page header, post grid, pagination.
+- **Blog detail:** article body, author + meta, related posts, comment section.
+
+Write this list to `scratchpad/.../sections.plan.md`:
+```
+SECTION 1: hero-banner               (anchored exemplar: <theme>/sections/hero-banner.liquid, 82 lines)
+SECTION 2: value-props               (exemplar: <theme>/sections/value-props-row.liquid)
+SECTION 3: featured-products-grid    (exemplar: <theme>/sections/product-collection.liquid, 89 lines)
+...
+```
+
+For each section, pick an **anchor exemplar** from `exemplars.md`. The exemplar is a **logic and code-structure reference only** — it sets the structural budget (DOM depth, class count, line count) and shows the right Liquid patterns / schema patterns / web-component wiring for this archetype.
+
+**Critical: do NOT copy visual decisions from the exemplar.** Colors, fonts, spacing, radius, shadows, layout density — every design choice comes from your assigned Figma frame and the theme tokens in `theme.json` / `figma-variables.json`. Two sections of the same archetype (say two hero banners from two different themes) should share their Liquid skeleton and visual approach to nesting, but look completely different in every other respect. If you find yourself thinking "I'll use the same gap and radius as the exemplar," stop — those values come from your Figma, not from the exemplar.
+
+### Phase 3 — Spec table (~1 min for the whole page)
+
+For each section in the plan, fill out a row-per-property spec table. Format defined in the previous skill's `spec-table.md` — same rules:
+- One CSS property per row.
+- Numeric values resolved against `figma-variables.json`.
+- Tailwind / CSS variable column filled in (must reference classes that actually exist in `tailwind.config.js`).
+
+Persist to `scratchpad/.../spec-table.md`. This is the contract.
+
+**Hard rule:** No row may be left unresolved (`?`) before phase 4 starts. If the design is genuinely ambiguous, mark it in the report as `NEEDS_REVIEW` and continue with your best resolution.
+
+### Phase 4 — Build (parallel section writes, with write-time lint)
+
+For each section in the plan, **in parallel where dependencies allow**, build the section file:
+
+1. **Plan the DOM** before writing. Identify the elements, hierarchy, and class lists.
+2. **Run the write-time lint** mentally (see `code-quality.md`):
+   - Tailwind classes per element ≤ 12.
+   - DOM depth ≤ 6.
+   - No empty wrapper divs.
+   - Every schema field will be wired into markup.
+   - Section file projected ≤ 250 lines.
+   - Heading hierarchy correct (section starts at `<h2>`, not `<h1>`).
+3. **Compare to anchor exemplar.** If your planned section has materially more elements, deeper nesting, or more classes than the exemplar, simplify before writing.
+4. **Write the file.** Follow the anatomy from the old `zcommerce-theme-builder` SKILL (script/style/liquid/conditional/wrapper/schema in that order — yes, the anatomy rule survives, the *anatomy* docs were correct).
+5. **Run `scripts/lint-section.mjs <file>`** — automated check of the same budgets. If it fails, the file is rejected; fix and re-write before continuing.
+
+You may build multiple sections concurrently using the file tools — the lint is per-file, the budgets are per-file, no cross-section coupling at this phase.
+
+### Phase 5 — Verify (~1 min) — MANDATORY, BLOCKING
+
+Once all sections are written:
+
+1. **Update `pages/<page>.json`** to wire the sections in order with their default settings.
+2. **Append translation keys** to `i18n/en.json` AND `i18n/en.schema.json`. Use append-only writes (read, splice, write) — never overwrite.
+   - **CRITICAL distinction:** runtime keys (used in markup via `'key' | t`) MUST live in `en.json`. Schema-label keys (used in `{% schema %}` via `"t:key"`) MUST live in `en.schema.json`. Putting runtime keys in en.schema.json causes the page to crash at render time — this exact bug shipped in a prior build and is now caught by `lint-section.mjs` → `i18n_keys_resolve`. **Re-run the lint** on every section after appending i18n to confirm 0 misplaced keys before continuing.
+3. **Start the dev server** if it's not already running (the orchestrator may have started it). Capture the port.
+4. **Run the four verification scripts via bash. These are MANDATORY — not optional.** A page agent that does not produce all four output JSON files is treated as a failure regardless of any other claim of success.
+   ```bash
+   node .claude/skills/theme-from-figma/scripts/pixel-diff.mjs \
+     --rendered-url http://localhost:<port>/<page_route> \
+     --figma-image .claude/scratchpad/<theme>/pages/<page>/figma-desktop.png \
+     --viewport 1440x900 \
+     --out .claude/scratchpad/<theme>/pages/<page>/verify/pixel-diff-desktop.json
+   
+   node .claude/skills/theme-from-figma/scripts/a11y.mjs \
+     --url http://localhost:<port>/<page_route> \
+     --out .claude/scratchpad/<theme>/pages/<page>/verify/axe.json
+   
+   node .claude/skills/theme-from-figma/scripts/perf.mjs \
+     --url http://localhost:<port>/<page_route> \
+     --out .claude/scratchpad/<theme>/pages/<page>/verify/lighthouse.json
+   ```
+5. Repeat pixel-diff for mobile viewport (`--viewport 375x812`, `--figma-image figma-mobile.png`).
+6. **Read all four JSON outputs** and classify pass/fail per the gates in `verification.md`.
+
+**Mandatory output contract.** After verify, the following files MUST exist:
+```
+.claude/scratchpad/<theme>/pages/<page>/verify/
+  pixel-diff-desktop.json
+  pixel-diff-mobile.json
+  axe.json
+  lighthouse.json
+```
+If any are missing or empty, the agent records `gates_unrun: true` in its report and exits with `FAILED` — the stage-2 coordinator will not let the theme ship. There is no "passed without running" path.
+
+**Threshold contract.** A page does not pass if:
+- `pixel-diff` mean ΔE ≥ 5 (vs the previous 2.0 — relaxed slightly for real-world font rendering)
+- `pixel-diff` max ΔE ≥ 15 in any region (vs 5 — tightened on max because that's where structural mismatches show up)
+- `pixel-diff` mismatch ratio ≥ 0.20 (twenty percent — if more than 1/5 of pixels differ from the Figma, the section is structurally wrong, not just a minor visual tweak)
+- `axe.json` has any critical or serious violation
+- `lighthouse.json` performance score < 85 on mobile (relaxed from 90 due to real-world LCP variance on dev server) OR LCP > 4s OR CLS > 0.25
+
+The threshold for `pixel-diff mismatch ratio` is the critical one for catching "your header is identical to a sibling theme" failures — that's the kind of mismatch that's huge (well over 20% of pixels differ) and unambiguous.
+
+### Phase 6 — Iterate (max 3 passes)
+
+If any gate fails, locate the failing element(s) from the script output, edit the section file(s), and re-run verification. Cap at **3 iterations**. After the 3rd failed iteration, write the remaining issues to your `report.md` under `NEEDS_REVIEW` and exit — Stage 2 consolidation will decide whether to surface them to the user.
+
+Inside the iteration loop:
+- Token mismatch / class wrong → edit and re-run pixel-diff only.
+- A11y violation → edit and re-run a11y only.
+- Perf regression → edit (usually image size, font preload, lazy-load attrs) and re-run perf only.
+
+Don't re-run all three on every iteration — only the failing gate. This keeps iterations short.
+
+### Phase 7 — Write report.md
+
+Final action before exit:
+
+```
+PAGE: index
+SECTIONS BUILT: 5
+  - hero-banner               (98 lines, 5 depth, 11 max classes)
+  - feature-props-row         (62 lines, 4 depth, 8 max classes)
+  - featured-products-grid    (74 lines, 4 depth, 9 max classes)
+  - cta-banner                (45 lines, 3 depth, 7 max classes)
+  - newsletter-signup         (58 lines, 4 depth, 10 max classes)
+
+GATES:
+  pixel-diff desktop:  pass (avg ΔE 1.2, max ΔE 2.8)
+  pixel-diff mobile:   pass (avg ΔE 1.4, max ΔE 3.1)
+  a11y:                pass (0 critical, 0 serious, 1 moderate)
+  perf desktop:        pass (perf 96, LCP 1.4s, CLS 0.01)
+  perf mobile:         pass (perf 91, LCP 2.2s, CLS 0.03)
+
+ITERATIONS: 1
+
+NEEDS_REVIEW:
+  - hero-banner: figma uses font weight 850, nearest available is 800.
+```
+
+Stage 2 collects these reports.
+
+---
+
+## Things to NOT do
+
+- Don't ask the user a question mid-build. Phase 1 may surface a missing input (mobile frame), but that should have been caught at preconditions in SKILL.md. If you get here without inputs, fail fast with a clear message; don't try to recover by asking the user — your concurrent siblings won't know to wait.
+- Don't modify the locked files (header, footer, theme.json, tailwind.config.js).
+- Don't touch other pages' sections or JSONs.
+- Don't re-extract Figma tokens. Bootstrap did that. Trust `figma-variables.json`.
+- Don't reformat sections you didn't write. Even if `header.liquid` looks like it could use cleanup, leave it alone — Stage 2 handles cross-page concerns.