diff --git a/manifest.json b/manifest.json
index 0da8ef6..db8f04d 100644
--- a/manifest.json
+++ b/manifest.json
@@ -112,7 +112,7 @@
     {
       "slug": "themes/theme-clone",
       "name": "Theme Clone",
-      "description": "Clone any website into a pixel-perfect Fluid theme — scrape the source, build sections, push, and visually verify against the original.",
+      "description": "Clone any website into a pixel-perfect Fluid theme \u2014 scrape the source, build sections, push, and visually verify against the original.",
       "category": "themes",
       "icon": "copy",
       "path": "themes/theme-clone/SKILL.md",
@@ -297,7 +297,7 @@
     {
       "slug": "marketing/brand-social-import",
       "name": "Brand Social Content Import",
-      "description": "Import a company's OWN YouTube + TikTok videos into Fluid: find the official accounts, register them in social-media settings, and pull their videos into the DAM + Media. Not UGC — this is the brand's own content.",
+      "description": "Import a company's OWN YouTube + TikTok videos into Fluid: find the official accounts, register them in social-media settings, and pull their videos into the DAM + Media. Not UGC \u2014 this is the brand's own content.",
       "category": "marketing",
       "icon": "video",
       "path": "marketing/brand-social-import.md",
@@ -306,7 +306,7 @@
     {
       "slug": "marketing/brand-setup",
       "name": "Brand Setup",
-      "description": "Interview the company to build a living brand.md — a brand-voice document that Mist, themes, portals, and widgets read to match the company's tone and style. Prefills colors/name from brand guidelines and saves via the update_brand_voice tool. Also use to append a single brand decision later.",
+      "description": "Interview the company to build a living brand.md \u2014 a brand-voice document that Mist, themes, portals, and widgets read to match the company's tone and style. Prefills colors/name from brand guidelines and saves via the update_brand_voice tool. Also use to append a single brand decision later.",
       "category": "marketing",
       "icon": "palette",
       "path": "marketing/brand-setup.md",
@@ -315,7 +315,7 @@
     {
       "slug": "themes/suggested-changes",
       "name": "Suggested Changes",
-      "description": "Review Lighthouse performance and compliance findings for this store, then approve or dismiss each recommended fix — approvals are applied and their impact is tracked.",
+      "description": "Review Lighthouse performance and compliance findings for this store, then approve or dismiss each recommended fix \u2014 approvals are applied and their impact is tracked.",
       "category": "themes",
       "icon": "sparkles",
       "path": "themes/suggested-changes.md",
@@ -333,7 +333,7 @@
     {
       "slug": "compliance/compliance-manager",
       "name": "Country Compliance Manager",
-      "description": "Audit a storefront against a country's legal requirements — disclosure pages, price display, cookie/privacy law, agreements, product labeling, storefront language — using the Country Atlas as the rulebook. Runs standalone and as the final step of the mode finalizers.",
+      "description": "Audit a storefront against a country's legal requirements \u2014 disclosure pages, price display, cookie/privacy law, agreements, product labeling, storefront language \u2014 using the Country Atlas as the rulebook. Runs standalone and as the final step of the mode finalizers.",
       "category": "compliance",
       "icon": "scale",
       "path": "compliance/compliance-manager/SKILL.md",
@@ -351,7 +351,7 @@
     {
       "slug": "mist/smart-dashboard",
       "name": "Smart Dashboard",
-      "description": "Self-fabricate a live business dashboard from real data — gather what every department cares about, render it with show_dashboard, then learn what the user wants front-and-center and remember it.",
+      "description": "Self-fabricate a live business dashboard from real data \u2014 gather what every department cares about, render it with show_dashboard, then learn what the user wants front-and-center and remember it.",
       "category": "mist",
       "icon": "layout-dashboard",
       "path": "mist/smart-dashboard/SKILL.md",
@@ -378,7 +378,7 @@
     {
       "slug": "sales/aov-lever-audit",
       "name": "AOV lever audit",
-      "description": "Find which levers actually move average order value — item count, bundles, discount depth — with a dollar figure per lever.",
+      "description": "Find which levers actually move average order value \u2014 item count, bundles, discount depth \u2014 with a dollar figure per lever.",
       "category": "sales",
       "icon": "trending-up",
       "path": "sales/aov-lever-audit.md",
@@ -441,7 +441,7 @@
     {
       "slug": "themes/clone-system-pages",
       "name": "Clone System Pages",
-      "description": "Build the Fluid system routes a source rarely exposes — themed 404 and 503 error pages with full shell, plus the reusable generic content-page template.",
+      "description": "Build the Fluid system routes a source rarely exposes \u2014 themed 404 and 503 error pages with full shell, plus the reusable generic content-page template.",
       "category": "themes",
       "icon": "triangle-alert",
       "path": "themes/clone-system-pages/SKILL.md",
@@ -473,6 +473,35 @@
       "icon": "rocket",
       "path": "onboarding/launch-setup/SKILL.md",
       "updated_at": "2026-07-30T23:10:00Z"
+    },
+    {
+      "slug": "themes/dynamic-bundles",
+      "name": "Dynamic Bundles",
+      "description": "Understand a company's existing bundle implementation (or a source configurator page) and recreate it as Fluid Dynamic Bundles, with one reusable theme implementation that renders every current and future bundle.",
+      "category": "themes",
+      "icon": "boxes",
+      "path": "themes/dynamic-bundles/SKILL.md",
+      "updated_at": "2026-08-07T00:00:00Z",
+      "references": [
+        "themes/dynamic-bundles/PLAN.md",
+        "themes/dynamic-bundles/playbooks/01-discovery.md",
+        "themes/dynamic-bundles/playbooks/02-translation.md",
+        "themes/dynamic-bundles/playbooks/03-theme-generation.md",
+        "themes/dynamic-bundles/playbooks/04-routing.md",
+        "themes/dynamic-bundles/playbooks/05-validation.md",
+        "themes/dynamic-bundles/playbooks/06-greenfield.md",
+        "themes/dynamic-bundles/playbooks/07-troubleshooting.md",
+        "themes/dynamic-bundles/playbooks/08-api-write-recipe.md",
+        "themes/dynamic-bundles/playbooks/09-pricing-patterns.md",
+        "themes/dynamic-bundles/playbooks/10-ui-and-price-surfaces.md"
+      ],
+      "assets": [
+        "themes/dynamic-bundles/templates/sections/bundle_builder/index.liquid",
+        "themes/dynamic-bundles/templates/assets/bundle-builder.js",
+        "themes/dynamic-bundles/templates/assets/bundle-builder.css",
+        "themes/dynamic-bundles/templates/product/bundle/index.liquid",
+        "themes/dynamic-bundles/schemas/bundle-manifest.schema.json"
+      ]
     }
   ],
   "workflows": [
@@ -505,6 +534,11 @@
       "slug": "speed-import",
       "path": "workflows/speed-import.workflow.json",
       "updated_at": "2026-07-30T18:00:00Z"
+    },
+    {
+      "slug": "dynamic-bundles",
+      "path": "workflows/dynamic-bundles.workflow.json",
+      "updated_at": "2026-08-07T00:00:00Z"
     }
   ]
 }
diff --git a/themes/dynamic-bundles/PLAN.md b/themes/dynamic-bundles/PLAN.md
new file mode 100644
index 0000000..32a3922
--- /dev/null
+++ b/themes/dynamic-bundles/PLAN.md
@@ -0,0 +1,522 @@
+# Universal Dynamic Bundles Skill — Research & Implementation Plan
+
+Status: **IMPLEMENTED AND FIELD-VERIFIED.** Planned 2026-08-05; built and exercised against a live company 2026-08-06.
+Author: Mist. Date: 2026-08-05, revised 2026-08-06. Reference corpus: the 18 docs now shipped alongside this skill at `reference/*.md` (originally read from `fluid-dynamic-bundles copy/`).
+
+> **Read PART 7 before trusting PART 1.** Parts 1–6 are the pre-build research record and are
+> preserved deliberately, including the questions that were open at planning time. PART 7 records
+> what changed once the writes actually ran — including **two claims in PART 1 that live testing
+> disproved**. Where the two disagree, PART 7 wins. The operational form of PART 7 is
+> `playbooks/08-api-write-recipe.md`; this part exists to show the evidence behind it.
+Primary test company: **Chipotle** (`980243433`) — confirmed live: `GET /api/v2025-06/bundles` → `[]`, active theme `57123` "Chipotle Onboarding Theme", sibling theme `57124`. Clean slate, exactly as the readiness doc predicts.
+
+---
+
+# PART 1 — What I actually learned
+
+## 1.1 The model, in one page
+
+A bundle is **a Product** with `products.bundle = true`, a shadow `Bundle` row (1 live row per product, unique index), and N `ProductBundleGroup` rows each holding N `BundleGroupItem` rows. Three layers, and which layer owns a setting determines what it can influence:
+
+```
+BUNDLE  (products.* + products.bundle_config + bundles.settings)
+  └ GROUP (product_bundle_groups.* + .pricing_config)   group_type = included | customizable
+      └ ITEM (bundle_group_items.* + .config)           one variant, in one group
+```
+
+Load-bearing consequences:
+
+- **`group_type` is a stored NOT-NULL column**, not emergent. The *bundle's* static/dynamic nature is emergent (`static?` = all groups included).
+- **Static/`included` groups are reconstituted server-side** and must **not** be sent in `bundled_items` — with exactly one exception: an included group that is a member of an exclusive pair *must* be sent, because the server cannot know which branch was chosen.
+- **Bundle-level flat pricing collapses the layers.** When on, group and item prices become display-only; nothing beneath can move the charge. It is *illegal* to combine with a `dynamic_price` group (model validation), so a theme never has to reconcile those two.
+- Almost everything a theme cares about lives in four schemaless JSONB bags: `bundles.settings`, `products.bundle_config`, `product_bundle_groups.pricing_config`, `bundle_group_items.config`. Unknown keys round-trip verbatim and are never rejected — a typo returns 200 with the key missing.
+
+## 1.2 Detection — the only gate worth writing
+
+```liquid
+{% if product and product.product_bundle_groups.size > 0 %}
+```
+
+Valid in every scope. `is_bundle` is API-only and nil everywhere in Liquid. `slug`/`handle` are nil in page and section scope. `product.bundle` *does* work (contrary to the old skill) but is absent from the enrollment product hashes and can be `true` with zero visible groups. `bundle_in_stock` is `true` on non-bundles — never a detector.
+
+## 1.3 Three "product" shapes, and the one that matters
+
+| Scope | Producer | Keys | Has `mutually_exclusive_groups`? |
+|---|---|---|---|
+| **A** page `product` (a PDP, and any `{% section %}` on it) | `Variables::Product#product_hash` | 50 | ❌ **no** |
+| **B** `section.settings.<product-typed setting>` | `ProductDrop#as_json` | 40 | ✅ yes |
+| **C** live `ProductDrop` (`products[i]`) | Drop object, every public method | — | ✅ yes |
+
+A section **inherits the page scope verbatim** — inside `sections/*.liquid` on a product template, `product` is always scope A. So on the deployment shape we want (one shared bundle template, no pinning), **exclusivity data is only reachable at `product.bundle_config.mutually_exclusive_groups`**. And that value holds **`sort_order`s, not group ids**, in two possible shapes (`[{ids:[…],default:…}]` or a bare `Array<Integer>`), and is `null` — not `[]` — on older bundles.
+
+## 1.4 The three moving parts (and the two that are missing by default)
+
+| Part | Default on a new company |
+|---|---|
+| The `product_bundle` section | ✅ free everywhere — one global row unioned into every theme, byte-identical across 33 themes / 6 companies, renders on companies with zero bundle infrastructure |
+| A host `product` template containing it | ❌ **no seed ships one** |
+| Routing (product → that template) | ❌ **no auto-assignment exists** |
+
+Routing is not a column — it is a `template_resources` join **scoped to the currently-active theme**. So: switching or cloning a theme silently un-routes every bundle; and a bundle created via API with no explicit `application_theme_template_id` comes back `null` and renders as an ordinary product.
+
+**A bundle on a bundle-unaware theme is a silent revenue hole**: normal-looking product page, working native add-to-cart, hard failure at checkout (`orchestrator.rb` `validate_bundle_configuration`). Nothing surfaces to the merchant.
+
+## 1.5 The trilemma that decides the architecture
+
+Global sections **never resolve typed `{% schema %}` settings** (`section_templates_for_template` omits the global union — defect **P3**). Measured, all four combinations:
+
+| Setup | Data blob | exclusivity | schema settings | scales? |
+|---|---|---|---|---|
+| Global section, no pin | 50-key page hash | ❌ | ❌ inert | ✅ one template |
+| Global section + `bundle_product` pinned | ❌ **dead shell** | — | — | ❌ |
+| Local clone, no pin | 50-key page hash | ❌ | ✅ | ✅ one template |
+| Local clone + pin | 40-key drop | ✅ | ✅ | ❌ **one template per bundle** |
+
+**No stock configuration gives both exclusivity and scale.** Pinning is also actively *destructive* on a global-only install (a raw integer is non-blank, suppresses the page-product fallback, emits no blob). And a theme-local clone **shadows the global permanently and never receives updates** (`auto_upgradeable?` is hardcoded `false`; two Chick-fil-A clones are already 15.7 KB stale).
+
+⇒ The scalable shape is: **theme owns the section source, never pin `bundle_product` on `product/*`, read exclusivity from `bundle_config`.**
+
+## 1.6 Write surfaces — one is safe, one is not
+
+**Surface A — `POST /api/company/v1/products/create_bundle_product` / `PATCH …/{id}/update_bundle_product`** (what the admin Bundle Builder uses). Only this surface can:
+- write `products.bundle_config` — *the place the cart validator and cart pricer actually read* `mutually_exclusive_groups`
+- set `products.bundle`, `track_inventory_on_bundle_items`, variants, `variant_countries`, images, SEO
+- run `BundleConfigValidation` (exclusive-pair arity/uniqueness + the `hidden`-flag rules)
+- do surgical nested deletes via `_destroy`
+
+**Surface B — `/api/v2025-06/bundles`** is a trap: no pagination, `per_page`/`page` silently ignored, **omits `product_id`** (you cannot get from bundle to product), skips `BundleConfigValidation` entirely, writes `bundles.settings` *without* mirroring to `products.bundle_config` (so exclusivity written here is honoured by the portal and **silently ignored by the cart**), returns **500 not 422** on any schema violation, `items[].is_default` 500s on update and is dropped on create, `sort_order` is overwritten by array position, `groups: []` destroys all groups, and it is entirely undocumented and untested upstream.
+
+⇒ **The skill writes bundles exclusively through Surface A**, reads through `GET /api/company/v1/products/{id}`, and uses Surface B only as a *read* cross-check (never as the source of truth, never for bundle→product resolution).
+
+Two more write rules learned the hard way:
+- `is_default` must be sent **inside `config`** on both surfaces.
+- **Match bundle → product by `product.product_bundle_groups[].id`, never by slug.** Duplicate/orphan Bundle rows share a title and the later row often owns the uniquified slug — slug matching resolved the *wrong* bundle on ≥3 fixtures, one of which reports empty `country_pricing` while the product actually charges $25.
+- **Delete the Bundle before the Product.** Reverse order leaves an orphan whose `DELETE` then 500s forever (nine such orphans exist on CrashTest).
+
+## 1.7 The cart contract
+
+```js
+window.FairShareSDK.addCartItems(PARENT_VARIANT_ID, {
+  quantity: 1,
+  bundled_items: [{ variant_id, quantity, product_bundle_group_id, subscription?, subscription_plan_id? }]
+});
+```
+
+- **Always send `product_bundle_group_id`.** Schema-optional, load-bearing: omitting it changes `bundle_selection_key` (`1527:56794x1|…` vs `56794x1|…`), so the same bundle added tagged once and untagged once produces **two lines and a double charge**. Mixing tagged/untagged for one variant is a hard 422.
+- **Never send included/static items** — except exclusive-set members (§1.1).
+- `quantity: 0` entries are **dropped before rule counting**, not rejected.
+- **Duplicates are not de-duplicated** — counting is over *entries*, not distinct variants. One entry per click ⇒ silent over-charge. Collapse into `quantity` yourself.
+- A cold cart is **two** HTTP calls for a bundle (create empty, then `…/items`); non-bundles are one.
+- Re-adding **sets** quantity, it does not increment. In-place edits via `POST` + `cart_item_id` are silently ignored; `PATCH …/bundled_items` works but leaves a stale selection key. **Use delete-then-re-add.**
+- **The promise never rejects.** `swallowErrors: true` ⇒ resolves `undefined` on 4xx/5xx/network, and `performAddCartItems` replaces the server body with a generic `"Failed to add items to cart"`. A theme `.catch()` never runs. The stock section's `.then()` therefore opens an unchanged cart drawer *after a failed add*.
+- **HTTP 200 is not success.** A country-unavailable child returns 200, prices the bundle at **$0.00**, and (finding D) leaves `items[].errors` **empty** — no programmatic signal at all. `valid_for_checkout` is `false` on every bare cart, so it is not a guard. Out-of-stock is *skippable*: the line is dropped and reported in a top-level `skipped_items` array that is **not** on the resolved Cart object (only on the event detail).
+
+## 1.8 Pricing — the chains a theme must implement
+
+- **Item:** `country_prices[ISO]` → `item.price` → `variant.variant_countries[ISO].price`. `item.price` is `"0.0"` on **100%** of fixtures, and a zero here means *unset*, not free.
+- **Group:** `pricing_config.country_pricing[ISO]` → `pricing_config.fixed_price`. `group.fixed_price` reads `"0.0"` when unset — indistinguishable from a real zero unless you check `pricing_config.fixed_price` for key presence. `min_price`/`max_price`/`compare_at_price` are effectively dead (`"0.0"` on every live group).
+- **Bundle:** `bundle_config.bundle_pricing_config.country_pricing[]` (values are **strings**). `product.bundle_price` is empty even with bundle pricing on. `primary_price`/`primary_currency` are admin echo — **never read by Rails**.
+- `product.price` in the Liquid drop **is** correct and country-resolved (`"$50.00"`, or a `"$30.00 - $70.00"` range when any group is dynamic). Top-level `price`/`display_price` from *both* JSON APIs are computed with `country_code: nil` and read `$0.00` — unusable. But **`price_range`/`bundle_price_range` are correct and country-resolved**, and are the primary write-verification signal (verified 2026-08-06 on nine bundles, including one *wrong* `$55.75–$66.75` that exposed a real pricing defect — see `playbooks/08-api-write-recipe.md` §4).
+- **Mode behaviour, verified three-way (display == cart == checkout):** `dynamic_price` sums selections and scales with quantity ✅; `fixed_price` group ignores picks *and* quantities ✅; bundle-level flat ignores everything below ✅; mixed = dynamic sum + fixed group price ✅. Two exceptions, both real money: an `included` group with **no** `fixed_price` displays as its item sum and **charges $0.00** (P11/finding C); a child with no priced country row **zeroes the whole bundle** (P6/finding D).
+- **CV/QV only flow from `dynamic_price` groups.** Fixed-price / flat bundles credit 0/0 unless CV/QV is re-entered on the group or bundle `country_pricing` row. A theme that sums `variant_countries[].cv` to promise "you'll earn N CV" **overstates every non-dynamic group**.
+- **Compare-at**: only render when `compare_price > price`, else you advertise an increase.
+- Type traps in one object: `variant_countries[].price`/`wholesale`/`compare_price` are **floats**, `subscription_price` is a **string**; `cv`/`qv` are Integers in Liquid and **strings** in both APIs; `display_*` carries a `" (USD)"` suffix; drop prices can be BigDecimal engineering notation (`"0.4999e2"`) — `parseFloat` survives it, `{{ item.price }}` in Liquid does not.
+
+## 1.9 Subscriptions
+
+Precedence: bundle-wide `subscription: true` **suppresses** per-item forced-subscription checks. Item `force_subscription` ⇒ must send `subscription: true` (422 otherwise); `allow_subscription: false` ⇒ must not (422). Group `force_subscriptions` / `allow_subscriptions` apply the same way — but note group `allow_subscriptions` is **never read server-side**, and on real fixtures the forcing lives on the *item* while the group flag is false, so **check both levels**. A missing plan id with `subscription: true` gets the company default. `force_subscription` requires the item's product to have ≥1 active plan (model validation).
+
+**P7 (by design, not filable): renewal price comes from the BGI variant's own `variant_country`, deliberately not the parent** — so a $35 bundle can renew at $100/mo or $0/mo depending only on which child was ticked, and **the PDP shows nothing**. The only theme-side remedy is disclosure.
+
+## 1.10 What the platform section actually is
+
+3063 lines. Lines 1–839 are inlined static CSS (there is no separate stylesheet to port). Lines 863–1148 are markup: 5 `<template>` blocks + 2 JSON `<script>` payloads + an empty `<div data-bundle-groups>`. Lines 1150–2966 are two IIFEs. **The visible DOM is built entirely by JS cloning templates.** The whole client contract crosses one tag:
+
+```liquid
+<script type="application/json" data-bundle-product>{{ bundle_product | json }}</script>
+```
+
+So *what the JS can act on is exactly what the drop serializes* — nothing the drop omits can be rendered, whatever the REST API returns.
+
+Surface area: 5 templates, ~50 `data-*` hooks, 79 `bundle-*` classes, **plus 31 generic utility classes** (`.btn`, `.container`, `.text-sm`, `.flex`, `.font-bold`, `.mt-lg` …) that collide with any theme defining the same names, **46 inline `style=` attributes**, and **18 hardcoded hex colours**. It also emits a nested double `<section>`, a dead step-indicator subsystem, and a hardcoded green `#059669` progress fill that overrides the `progress_bar_color` setting. It reads three CSS tokens (`--clr-black`, `--clr-white`, `--text-sm`) that happen to exist on all 8 surveyed themes but are an alias shim on one, and `--text-sm` is `0.875rem` in one lineage and `14px` in the other.
+
+The deployed global row is **not** the repo file (3058 vs 3063 lines; missing one merged commit) — so never assume a company's hosted section equals master; fetch and diff.
+
+## 1.11 The defect surface a generated theme has to survive
+
+Filable platform bugs relevant to us: **P2** exclusivity no-ops on the page path (shopper charged for a branch they never receive, $60 confirmed) · **P1** stored XSS via product title into an inline `<script>` (bundle-section-only; root cause `JsonFilter#json` using bare `JSON.generate`) · **P3** global schema settings · **P5** swallowed cart errors · **P6** silent $0.00 · **P10** bundle-wide subscribe shows $77 charges $70 · **P14** `max_only` cannot submit zero · **P16** **HTTP 500** when a selection bound is nil (nils are created by the platform's own `normalize_selection_bounds`, and the CTA *enables*) · **P17** no SDK ⇒ perfect-looking page, dead button, no console error · **P19** defaults pre-select past `max_selections` ⇒ `3 / 1`, CTA permanently dead, message says add *more* · **P20** phantom Add on a card disabled by an exclusive switch · **P21** contradictory out-of-stock wording.
+
+Explicitly *not* bugs (don't design around them as if they were): **P4** the section doesn't self-guard (by design — a section renders where you put it; the trap is real, the fix is hosting) · **P7**/**P12** by design, named verbatim in their originating commits · **P11/P13/P16-fixture/P18** are API-only states the Bundle Builder cannot produce · **P8** is theme responsibility (send the group id) · the `e.target`-vs-`closest()` dead-click bug is **fixed** and the `pointer-events:none` / MutationObserver workarounds are unnecessary.
+
+## 1.12 Assumptions that do NOT hold across companies
+
+This list is the actual reason a "universal" skill is hard. Every item was observed varying:
+
+1. **Two CSS token lineages** — `--clr-*` (7 themes) vs `--color-*` (chewy, where `--clr-*` exists only as an alias shim). Namespace must be *detected*.
+2. **Three `.container` widths and two mechanisms** (1360 `width:` / 1280 `max-width:` / 1328), and the **newest PDPs bypass `.container` entirely** in favour of a per-section container keyed to `section.id`. A section that wraps itself in `.container` misaligns with the rest of the PDP on those themes — guaranteed, visible.
+3. **`button, .btn {}` is hijacked on 6 of 8 themes** into a black flex box; `input, button, textarea, select { -webkit-appearance: none }` makes **native radios and checkboxes invisible on every theme**; `ul, li { list-style: none }` kills bullets on 7 of 8.
+4. `!important` density ranges 0 → 16 plus 7 more inline.
+5. **One currency / 2 decimals is not safe** — read `localization.country.currency.symbol` and `.decimal_places`.
+6. **One subscription plan is not safe** — CrashTest has exactly one (618 Monthly), so the multi-plan picker has *never been exercised*. Plans attach company-wide.
+7. **Hidden-group filtering differs by scope** — the drop rejects `pricing_config.hidden`, the page path does **not**. Filter yourself.
+8. `mutually_exclusive_groups` shape varies and may be `null`; it references `sort_order`.
+9. `description` on a group can be `""` *or* `null` (both occur live).
+10. Some fixtures have **no image anywhere** — the placeholder path must work.
+11. API traps that fake theme bugs: `per_page=100` on `/api/company/v1/products` returns **zero** products with no error (50 works); ignored filters return an unfiltered page; `?country=CA` is ignored, `?country_id=35` works.
+12. Enrollment bundles expose the same data and have **zero** rendering support anywhere. Genuinely unsupported.
+
+---
+
+# PART 2 — Design decisions
+
+## D1. Generate a theme-owned section, not a clone of `product_bundle`
+
+**Decision:** the skill generates a theme-native section (working name `bundle_builder`) that implements the platform's *data contract and cart contract exactly*, and owns its own presentation layer. A patched clone of `product_bundle` is offered as a documented, non-default "parity mode".
+
+Why, in order of weight:
+
+1. **The brand requirement is unachievable with the platform section.** 46 inline `style=` attributes and 18 hardcoded hex colours outrank any stylesheet on specificity. "Match the company's branding" would mean `!important` warfare or editing the template anyway — at which point you own the source and the clone bought you nothing.
+2. **A clone inherits ~11 client-side defects** (P2, P5, P10, P14, P15, P16-client, P17, P19, P20, P21, and P1's escaping) that we can simply not write.
+3. **A clone never receives updates regardless.** `auto_upgradeable?` is hardcoded `false` and `prefer_theme_specific` makes a local copy shadow the global permanently. The "stay in sync with upstream" argument for cloning is *false* — cloning guarantees the drift it's supposed to avoid, and two CFA clones already prove it.
+4. **The stable part of the platform is the contract, not the UI.** The drop shape and the cart schema are what upstream changes cost you; both are documented, both are what we build against. The 3000 lines of inlined CSS+JS are the volatile, unmaintainable part.
+5. **Collision safety.** The platform section emits 31 generic utility class names into whatever theme hosts it. Ours emits only `data-*` hooks plus a single scoped namespace.
+
+Cost, and how it's paid: we re-implement ~2000 lines of interaction logic. That is bounded because the behaviour is fully specified in `00-BEHAVIOUR-MAP.md` (98 scenarios) + `05a-behavior-verified.md` (31 verified) + `11-edge-cases.md` (25 adverse), and we validate against the platform section side-by-side using the bench (same product, two `theme_template_id`s) as the differential oracle.
+
+## D2. Layered architecture for the generated implementation
+
+Five artefacts, each with one job. This is the maintainability answer.
+
+```
+sections/bundle_builder/index.liquid   presentation only: <template>s + {% schema %} + the data blob.
+                                       No pricing logic. No rule logic. Escaped blob (fixes P1).
+                                       Server-renders included rows + group scaffold (no blank-until-JS, no CLS).
+assets/bundle-builder.js               one pure normalizer + one state machine + one cart adapter.
+                                       No markup strings, no company constants, no bundle ids.
+assets/bundle-builder.css              tokens only, zero hex, scoped under [data-bundle-root],
+                                       + a compat layer that neutralises the host theme's button/input/list resets
+                                         *inside the section only*.
+product/<name>/index.liquid            host template. Gates on product_bundle_groups.size > 0 and
+                                       falls through to the theme's normal product body when false.
+theme/bundle-manifest.json             provenance + routing map + applied-defect list + contract revision.
+```
+
+The JS splits into four named layers so a future change lands in exactly one:
+
+| Layer | Responsibility | Why separate |
+|---|---|---|
+| `normalize(rawProduct, ctx)` | drop JSON → a flat, typed, country-resolved `BundleModel`. Every price chain, every string→number coercion, every `null` vs `""` guard, hidden-group filtering, `sort_order` sorting, exclusivity read from `bundle_config` **and** the top-level key, both mutex shapes, nil-bound repair. | This is where 100% of the platform's data traps live. One function, unit-testable, and the *only* thing that changes when the drop changes. |
+| `rules(model, selection)` | pure function → `{ perGroup: {count, min, max, satisfied, blocked, reason}, complete, violations[] }`. Mirrors `CartBundleValidator` exactly, including nil-bound guards and `max_only`-zero. | Turns swallowed 422s into inline messages *before* the request. |
+| `render(model, state, refs)` | clones `<template>`s, sets text/attrs. Knows nothing about pricing or rules. | Restyling and re-layout never touch logic. |
+| `cart(model, selection)` | builds `bundled_items` (tag every entry, drop included groups except exclusive members, collapse duplicates into quantity, omit zero-qty), calls the SDK, treats resolved-`undefined` as failure, reads the cart back, inspects `items[].errors` and `skipped_items`. | The money path, isolated and assertable. |
+
+## D3. Zero bundle-specific hardcoding — mechanically enforced
+
+The generator emits no bundle id, product id, group id, group title, item count, or price anywhere in the theme. A validation gate greps every generated file for every live id in the company's bundle set and **fails the run** on a hit. `bundle_product` is never set on a `product/*` template (it hard-wires one bundle, drops hidden groups 3→2, and is destructive on a global install). Group *labels* come from `group.title`; rule *copy* comes from schema settings with `{count}`-style placeholders, so it localises without code.
+
+## D4. Routing, done deliberately
+
+Per bundle product: `PATCH /api/company/v1/products/{id} { product: { application_theme_template_id } }` → then **fetch the plain storefront URL** (no `preview` param) and assert our marker is present and the old implementation's markers are gone. Verified end-to-end in the reference campaign; a plain PATCH is sufficient and takes effect immediately.
+
+Because routing is a per-active-theme join, `bundle-manifest.json` records `{theme_id, template_id, product_ids[]}` so re-routing after a theme switch or clone is a single idempotent replay — and the skill *warns* about this explicitly, since it's the #1 real-world fault (`byob-undle` was rendering bundle-less purely because the join was null).
+
+## D5. Discovery: classify, don't assume
+
+The skill never assumes an architecture. It gathers evidence and classifies the company into one of five archetypes, with confidence, and writes `bundle-discovery.json`.
+
+| Archetype | Signals | Action |
+|---|---|---|
+| **A. Already dynamic bundles** | products with `product_bundle_groups.size > 0` | audit + re-theme + fix routing/pricing gaps. No data migration. |
+| **B. Hand-authored picker** | theme source contains `dynamic_bundle_picker`, `data-dbp-*`, `data-fluid-dbp`; often injected into `product/default` | read the picker's own rule/pricing/submit logic as the behavioural spec; port to the generated section; un-inject from default. |
+| **C. Legacy flat `ProductBundle`** | `product_bundles[]` non-empty and `product_bundle_groups` empty | convert to one `included` group (split by `display_externally` into included + hidden if needed). Preserve `quantity`. Note: these price from the master variant like a normal product — pricing intent must be captured *before* conversion. |
+| **D. Convention-based "fake" bundles** | multi-variant kit/combo/bundle titles; option-driven builders; products whose description enumerates components; a catalog of component products with a parent SKU pattern | **propose, never auto-convert.** Present candidates with evidence and let the user confirm each. |
+| **E. Greenfield (Chipotle)** | zero bundles, zero infrastructure | generate the implementation; optionally build one *real* bundle from the live catalog as the proving fixture. |
+
+Evidence sources: `/api/company/v1/products` (paged at **50**, never 100), the active theme's template list + section sources, `/api/v2025-06/bundles` as a read cross-check only, `variant_countries` for pricing intent, subscription plans, `company_countries` for the country/currency matrix.
+
+## D6. Translation rules (existing → dynamic), table-driven
+
+Every conversion is a declarative row, so it's reviewable and extensible rather than buried in code. The contract is *preserve*, in this order of priority: **charged price** → **selection semantics** → **subscription semantics** → **exclusivity** → **defaults/quantity caps** → **copy/imagery**.
+
+| Source concept | Target | Notes / trap |
+|---|---|---|
+| "always included" component | `included` group, item `quantity` = component qty | **must set an explicit `fixed_price`** or it displays as the item sum and charges $0.00 (P11) |
+| "pick exactly N" | `customizable` + `selection_type: exact`, `min_selections: N` | `exact` collapses `max` to `min`; a stale persisted `max` is normalized by the drop but not the raw API |
+| "pick up to N" | `max_only`, `max_selections: N` | `min_selections` is forced `nil` → **guard the client comparison** (P16) and allow zero-submit (P14) |
+| "pick at least N" | `min_only` | `max_selections` forced `nil` — same guard |
+| "pick N–M" | `min_and_max` | progress denominator is max, completion is judged at min |
+| either-A-or-B branch | two groups + `bundle_config.mutually_exclusive_groups` (pairs of **sort_order**, max 2 per set, a group in at most one set) | write via **Surface A only**, else the cart ignores it |
+| per-component price | group `dynamic_price` (sums, scales with qty, **credits CV/QV**) | the only mode where volume flows from items |
+| one flat kit price | group `fixed_price`, or bundle-level flat for the whole bundle | fixed/flat credit **0/0 CV/QV** unless re-entered on the group/bundle country row — surface this to the user, it's a commissions decision |
+| per-country price | `country_pricing[]` at the right layer | strings, UPPERCASE ISO, `enabled` strict `== true` |
+| pre-selected option | item `config.is_default: true` | **clamp to `max_selections`** and skip out-of-stock (P19) |
+| "max 2 of this" | item `config.max_quantity` | counters count *units*, not lines |
+| subscribe option / required | item `config.allow_subscription` / `force_subscription` (+ plan id) | forced items need an active plan on their own product; check group level too |
+| hidden internal component | `included` group + `pricing_config.hidden: true` | legal only on static groups outside an exclusive pair |
+
+## D7. Self-validation gates
+
+Every gate reads state back. None trusts the screen. A failed gate either auto-repairs (idempotent, bounded) or stops with an actionable message naming the exact resource and field.
+
+| Gate | Proves |
+|---|---|
+| **G0 preflight** | token scope; exactly one `status:"active"` theme identified; `product_bundle` global resolves; countries + currency + decimals; subscription plan inventory; SDK boot tag present on the storefront |
+| **G1 discovery** | every candidate classified with evidence; no product both "bundle" and unclassified; enrollment bundles flagged as unsupported and excluded |
+| **G2 config write-back** | re-`GET` each product and diff field-by-field against intent; `products.bundle_config` non-empty; every mutex tuple references an existing `sort_order`; `is_default` present *inside* `config`; no group left with a nil surviving selection bound; every `included` group has an explicit price or an explicit $0 decision |
+| **G3 render** | blob present + key count as expected; post-JS `[data-group-id]` count == expected (excluding `<template>`s); zero console errors; **a non-bundle product on the default template is byte-untouched**; 390 px with no horizontal overflow |
+| **G4 interaction** | each `selection_type` gates correctly; defaults ≤ max; at-max gives a real disabled affordance or swaps; `max_only` can submit zero; nil bounds don't enable a doomed CTA; subscribe controls appear only where allowed and are locked where forced; a **real scrolled mouse click** on the CTA *and on a child of it* |
+| **G5 cart** | captured request body: every entry tagged with `product_bundle_group_id`, included items **absent** (exclusive members **present**), duplicates collapsed; cart read back with one line, `metadata.is_bundle`, every expected child incl. server-reconstituted ones; `items[].errors` and `skipped_items` inspected **even on 200**; resolved-`undefined` surfaces our error UI; add-twice produces the expected lines |
+| **G6 money** | displayed total == cart total == checkout total in **every pricing mode the company uses**; recurring subtotal read from `cart.recurring[0]` and disclosed on the PDP; no $0.00 accepted silently; CV/QV expectation matches the mode |
+| **G7 reusability** | **the platform proof**: synthesise a second bundle with a *different* shape (extra group, nested exclusivity, per-item max, a subscription-forced item) and confirm it renders and adds to cart with **zero code changes** and no new template |
+
+## D8. Improvements beyond the brief (and why each earns its place)
+
+1. **Client rule engine mirroring the server validator** — the server's message is destroyed by the SDK, so pre-validation is the *only* way a shopper ever learns why. Also kills P14/P16 client-side.
+2. **Real server-error capture** — a narrow `fetch`/XHR interceptor records the last cart error body before the SDK generalises it, surfaced on `CART_OPERATION_ERROR`. Diagnostics stop being guesswork.
+3. **$0.00 / country-availability guard** — refuse or warn when a selected child has no positive priced row for the cart country. This is real money and the platform gives *no* signal.
+4. **Recurring-total disclosure** — computed from item subscription prices and shown on the PDP. Can't fix P7/P10; can stop hiding a $100/mo surprise until checkout.
+5. **Swap-on-click at max + genuine disabled affordance** — P15 is called "the single most likely thing to generate support tickets".
+6. **Defaults clamped to max, out-of-stock defaults skipped** — P19 is reachable by a real merchant in one click.
+7. **XSS-safe blob** — escape `<`/`>`/`&` in the emitted JSON. We can do in our section what the theme cannot do with the platform's.
+8. **Accessibility** — the platform section has none. Real `radiogroup`/checkbox-group semantics, keyboard operability, `aria-live` on tracker and total, focus management on exclusive switches. Also fixes the "native inputs are invisible on every theme" reset problem by not depending on native input chrome.
+9. **Capability registry + unknown-field notice** — the model records which group/item flags it understood; an unrecognised flag logs one dev-mode notice instead of silently doing nothing. This is how future platform features surface instead of rotting.
+10. **`bundle-manifest.json`** — records routing map, source archetype + evidence, contract revision, applied-defect list, and the global section's fetched digest, so the next agent can re-sync deliberately instead of archaeologically.
+11. **Idempotent, resumable writes** — deterministic external keys, read-before-write, converge-not-duplicate on re-run. Bundle-before-product delete order baked in.
+12. **Dry-run by default** — a full plan + diff, then `human_in_the_loop` approval before any write. Bundles touch pricing.
+13. **Explicit refusal for enrollment bundles** — honest "not supported, here's why" beats a half-working picker.
+14. **Locale/currency correctness** — symbol and decimal places from `localization`, thousands separators, never a hardcoded `$`/2 (the *deployed* global section hardcodes 2).
+15. **Progressive enhancement** — static rows and group scaffold server-rendered so the page has content and stable layout before JS, unlike the platform section which paints nothing until its IIFE runs.
+
+---
+
+# PART 3 — The workflow the skill will run
+
+Phase 0 and 1 are read-only. Nothing writes before the approval gate in Phase 4.
+
+**Step 1 — Resolve the reference company.** Use the workflow/chat context if a company is already in scope (same pattern as the onboarding workflow's company resolution); otherwise ask once. Resolve: company id, active theme, storefront host, countries + currencies, subscription plans. → **G0**
+
+**Step 2 — Study the reference company.** Catalog scan (paged at 50), theme source scan, existing bundle inventory (matched by group id, never slug), pricing/subscription/CV intent, live storefront probe of one representative product on all three render paths (plain / canonical / any existing picker). Produce `bundle-discovery.json` + a written "how this company's bundles work, and *why*" summary. → **G1**
+
+**Step 3 — Plan the translation.** Emit `bundle-plan.json`: per source bundle, the exact target group/item/pricing/exclusivity/subscription configuration, plus the preserved-behaviour assertions each one must satisfy. Flag every judgement call (fixed vs dynamic pricing → CV/QV consequence; included-group price; defaults) for the user.
+
+**Step 4 — Approve.** `human_in_the_loop` with the plan, the money implications, and the exact write list. Stop.
+
+**Step 5 — Write the Dynamic Bundle records.** Surface A only, idempotent, one product at a time, read-back-and-diff after each. → **G2**
+
+**Step 6 — Generate the theme implementation.** Detect the theme's token lineage, container mechanism, button/input/list resets, typography scale and radius; emit the five artefacts against *those* tokens; `fluid theme push` (never `--force`); publish (updates require an explicit publish — a `PUT` alone changes nothing on the storefront). → **G3**
+
+**Step 7 — Route + verify.** Assign each bundle product; verify on the plain storefront URL. → **G3/G4**
+
+**Step 8 — Prove it.** G4 → G5 → G6 → G7, then write `bundle-manifest.json` and a report: what was built, what was preserved, what differs from the source and why, what needs a human, and which platform defects are worked around versus still live.
+
+**Greenfield branch (Chipotle):** Steps 2–3 collapse to "no existing implementation"; the skill generates the implementation, and builds **one real bundle from the live catalog** as the proving fixture (not a toy), then runs the same G3–G7.
+
+---
+
+# PART 4 — Skill deliverable layout
+
+```
+fluid-dynamic-bundles/
+  SKILL.md                       trigger + orientation + the 5 rules + the workflow
+  reference/                     the existing corpus, kept as the spec (00-BEHAVIOUR-MAP.md remains primary)
+  playbooks/
+    01-discovery.md              archetype signals, evidence queries, API traps
+    02-translation.md            the D6 mapping table + preserved-behaviour assertions
+    03-theme-generation.md       token detection, the 5 artefacts, compat layer, push/publish
+    04-routing.md                assignment + verification + theme-switch replay
+    05-validation.md             G0–G7 as runnable checks
+    06-greenfield.md             no-existing-bundles path
+    07-troubleshooting.md        health-check → defect-triage decision tree
+  templates/                     the generated artefacts as parameterised sources
+    sections/bundle_builder/index.liquid
+    assets/bundle-builder.js
+    assets/bundle-builder.css
+    product/bundle/index.liquid
+  schemas/
+    bundle-discovery.schema.json
+    bundle-plan.schema.json
+    bundle-manifest.schema.json
+```
+
+---
+
+# PART 5 — Edge cases the design explicitly handles
+
+Bundle with zero visible groups (all hidden) · group with zero items · `included` group with no price · nil surviving selection bound · defaults exceeding max · out-of-stock default · variant in two groups (must tag) · duplicate variant across groups · cross-group duplicate submitted naively (the 422 the included-skip prevents) · `max_only` with nothing selected · exclusive pair where one branch is static · exclusive pair with an unavailable item (P20) · older bundle with `mutually_exclusive_groups: null` · legacy bare-array mutex shape · child with no country row · child not sellable in the cart country · parent not sellable (422 at create) · bundle with no image anywhere · engineering-notation prices · `cv`/`qv` type flip between Liquid and API · `description` `""` vs `null` · multi-plan subscription selector (**untested upstream — treat as unproven**) · bundle-wide + per-item subscription coexisting · re-add sets not increments · theme switch un-routing everything · a company whose theme already defines `.btn`/`.container`/`.text-sm` · a company with a non-USD, non-2-decimal currency · orphan Bundle rows · enrollment bundles (refused).
+
+---
+
+# PART 6 — Decisions I need from you before I build
+
+1. **Architecture (the big one).** Generate a theme-native `bundle_builder` section (D1, recommended) — or patch-and-clone the platform `product_bundle` for byte-parity? My recommendation is D1 for the five reasons above; the parity path stays documented as an option.
+2. **Chipotle's proving bundle.** Chipotle has 0 bundles but ~47 build-component products already in the catalog (7 proteins, 2 rices, 2 beans, 11 toppings, chips & dips, sides, high-protein cups). A real "Build Your Own Burrito/Bowl" is an unusually good test fixture: an exact-1 protein group, max-1 rice and beans, a many-select toppings group at $0, an included tortilla/base, per-item `max_quantity` for double protein, and a natural exclusive pair (bowl vs burrito). **Confirm this is the fixture you want** (and whether it should be `draft` or published).
+3. **Packaging.** One skill that runs end-to-end, or skill + a `dynamic-bundles` workflow (per-step QA + rework, like the onboarding chain)? The validation gates map cleanly onto workflow steps, which would give automatic rework on failure.
+4. **Aggressiveness on archetype D.** For convention-based "fake" bundles, my default is *propose, never auto-convert*. Say the word if you'd rather it convert above a confidence threshold.
+```
+
+---
+
+# PART 7 — What the live run changed (2026-08-06)
+
+Everything below was observed against **Chipotle (`980243433`)** while converting six menu items,
+building four fixed catering kits, and reproducing a real add-to-cart failure. Nine bundles exist
+as a result (`1088`–`1095`, plus `1092` rebuilt). Where this part contradicts PARTS 1–6, this part
+wins; the earlier text is kept so the correction is visible rather than silently overwritten.
+
+## 7.0 The PART 6 decisions, as resolved
+
+| # | Question | Resolution |
+|---|---|---|
+| 1 | Architecture | **D1** — theme-native generated `bundle_builder`. Built; the parity-clone path stays documented but non-default. |
+| 2 | Chipotle fixture | Went further than a fixture: **six real menu items converted in place** (Burrito 89585, Bowl 89586, Tacos 89590, Salad 89589, Quesadilla 89588, Kid's BYO 89591) plus **four catering products** (89900–89903) and one rebuilt builder (89584). Published, not draft. |
+| 3 | Packaging | **Both** — skill *and* `dynamic-bundles` workflow. The gates did map onto steps; the workflow is where the new evidence requirements are enforced. |
+| 4 | Archetype D aggressiveness | *Propose, never auto-convert* — **retained, and vindicated.** §7.1 is the reason. |
+
+## 7.1 Shape classification — the failure that recurred three times
+
+The most expensive mistake available is applying one pattern to products that merely *look*
+uniform. Seven Chipotle "menu item" products split three ways:
+
+| Products | Option | Values are | Correct shape |
+|---|---|---|---|
+| Burrito, Bowl, Tacos, Salad, Quesadilla, Kid's | **1144** | components of one item (Chicken, Steak…) | bundle |
+| Chips & Sides 89593 | **1145** | 24 values that each already exist as their own product | **category** |
+| Build-Your-Own 89584 / High Protein 89587 | **1143** | distinct menu items, $3.50–$16.10 | category (89587) / bundle (89584) |
+
+The test is **not** "do these share an option?" It is: *are the option values components of a
+single sellable thing, or separate sellable things?* Components → bundle. Separate things →
+category/collection. Converting a category into one bundle destroys a browsable listing and
+advertises one wrong price.
+
+Two further shape lessons:
+
+- **Fixed kit vs configurable vs BOTH.** Family Meals is a category page of four fixed-kit cards
+  where *each card also has a CUSTOMIZE link* into a builder. The correct model is **N fixed kits
+  PLUS one configurable bundle** in one collection — not one or the other. I modelled it as one
+  configurable product first, which was wrong, then briefly called 89584 redundant, which was also
+  wrong. The kit and builder prices legitimately differ ($52/$52/$63 kits vs $53/$53/$64 builder,
+  a flat +$1 to customize) and must **not** be reconciled.
+- **Never treat imported catalog prices as source of truth.** The importer had the catering
+  proteins at $50/$50/$61; the source page said **$52/$52/$63**. The catalog was wrong before
+  anything was touched. Deriving deltas from existing variants is right when *preserving* prices
+  and wrong when *matching a source*.
+
+## 7.2 Create is one call; convert is two
+
+| Endpoint | `bundle: true` + groups in one request |
+|---|---|
+| `POST …/create_bundle_product` | ✅ persists — `is_bundle: true`, `bundle_price` correct, Bundle row synced (3/3 creates) |
+| `PATCH …/{id}/update_bundle_product` | ❌ groups created, `is_bundle` stays **false**, `bundle_config: {}`, **no Bundle row** (6/6 conversions) |
+
+A conversion therefore needs a second, groups-free `{id, title, bundle: true, status}` call. Also
+confirmed: **`title` is required even on an update** (omitting it → 422 `title is missing`), and
+plain `PATCH /api/company/v1/products/{id}` silently ignores
+`product_bundle_groups_attributes` while returning 200.
+
+Between the two calls the product has groups but no bundle record; unrouted, its PDP renders
+$0.00 with no picker. Hence: route **per product, immediately**, never batched to the end.
+
+## 7.3 Pricing — corrections to PART 1
+
+### 7.3a `price_range` is usable, and is the primary verification signal
+**PART 1 (§1.6 bullet) claimed `price_range`/`bundle_price_range` are computed with
+`country_code: nil` and read `$0.00`. That is wrong.** Across nine bundles they returned correct,
+country-resolved values: `$9.35–$11.35` (×4), `$9.90–$11.90`, `$5.60`, `$52.00`, `$63.00`,
+`$53.00–$64.00` — and one *wrong* value, `$55.75–$66.75`, which is how a real pricing defect was
+caught (§7.3b). Only top-level `price` / `display_price` are unusable (`$0.00 (USD)` on every
+bundle). Compare `price_range` before → after on every write.
+
+### 7.3b `fixed_price: "0.00"` is ignored
+A group priced at zero does **not** zero its contents. Each item's `resolved_price` falls back to
+the component variant's own price even when `config.price` is explicitly `"0.0"`. Large Chips
+(variant 344052, $2.75) inside a `fixed_price: "0.00"` **included** group pushed 89584 from
+`$53–$64` to `$55.75–$66.75`; removing that one item restored it. So: **a nonzero `fixed_price`
+pins a group total; `0.00` behaves as unset.** Only genuinely $0 variants belong in a free group.
+Consequence: Large Chips is named in 89584's copy but is *not* a component of it.
+
+### 7.3c Floor contribution is three-way
+| Group | Adds to `price_range.min` |
+|---|---|
+| `included` | **sum of ALL** its components' resolved prices |
+| optional `fixed_price` (`max_only`) | **nothing** |
+| optional `dynamic_price` | **its cheapest item** — even at `min_selections: nil` |
+
+The last row supersedes an earlier blanket phrasing of "any dynamic group". An optional paid
+"Add Guac or Queso" `dynamic_price` group moved the burrito's floor from **$9.35 → $12.30**, so
+every collection tile advertised "from $12.30" for a burrito buyable at $9.35. Computed
+server-side; no theme-side fix. Never add one to a product whose "from" price is customer-facing
+without explicit client acceptance.
+
+### 7.3d A fixed-price `included` group prices the bundle exactly
+`bundle_price` / `price_range` equal the group's `fixed_price`, ignoring components' own prices
+(items still echo their real `pc_price`). This is the correct primitive for a fixed kit and means
+the kit price cannot drift when a component's à-la-carte price changes.
+
+## 7.4 The add-to-cart root cause
+
+**Valid bundle config is not evidence the storefront can sell it.** 89584 read back perfectly from
+`GET /api/v2025-06/bundles` — six groups, correct prices — and failed for every shopper:
+
+```
+POST /api/checkout/v2026-04/carts → 400
+"product_bundle_group_id 1771 must reference a customizable group
+ or an exclusive included group"
+```
+
+Group 1771 is `Included Sides`, `group_type: "included"`. This is **SKILL.md rule 3 violated by
+the client**, not a platform defect and not a gap in the skill — `bundle-builder.js` `cart()`
+already drops included groups. The live theme didn't.
+
+Two payloads verified 200 with correct totals:
+
+```jsonc
+// configurable — customizable groups ONLY; included group omitted
+{ "variant_id": 343601, "quantity": 1, "bundled_items": [
+  {"variant_id":344039,"quantity":1,"product_bundle_group_id":1765},
+  {"variant_id":344022,"quantity":1,"product_bundle_group_id":1769},
+  {"variant_id":344023,"quantity":1,"product_bundle_group_id":1770} ] }   // → $53.00
+
+// pure fixed kit (89901) — NO bundled_items at all
+{ "variant_id": 344077, "quantity": 1 }                                   // → $52.00
+```
+
+The cart attaches included components itself: the successful response listed Cheese, Romaine and
+Soft Flour Tortillas under group 1771 although they were never sent. Cart metadata carries
+`is_bundle: true`, `bundle_group_base_price`, and a `bundle_selection_key` listing **only** the
+customizable picks (`1765:344039x1|1769:344022x1|1770:344023x1`; empty string for a pure fixed kit).
+
+**Corollary that matters as much as the fix:** an all-`included` product has nothing to select, so
+any UI gating add-to-cart on "all required groups chosen" leaves every fixed kit permanently
+unclickable — while the API side looks perfectly healthy. Workflow step 8 therefore demands a cart
+call for one configurable bundle **and** one pure fixed kit; testing one shape is an explicit fail.
+
+## 7.5 Mutation gotchas found while writing
+
+- **`images_attributes` APPENDS on PATCH.** No replace. 89900 ended with two gallery rows both at
+  position 1. Send `_destroy` for the old image id when swapping.
+- **Collection membership REPLACES.** `PATCH /api/v202604/company/collections/{id}`
+  `{collection:{product_ids:[…]}}` overwrites the whole set and the response does **not** echo
+  products. Read current members first (v1 GET returns `product_collections[]`), then re-GET.
+- **A `draft` / `public: false` collection still renders publicly.** Verified by fetching a live
+  draft collection page — full `collection_showcase` with pagination. Do not "fix" draft status to
+  make a collection reachable.
+- **Cross-group duplicate variants are legal.** Cheese (344035) sits in Quesadilla's protein group
+  as "Cheese Only" ($9.90) *and* in its toppings group ($0). Different `product_bundle_group_id`
+  ⇒ distinct cart keys. This is why tagging every entry (rule 4) is load-bearing.
+- **Sequencing.** Never archive or delete a product the storefront still links to; retire only
+  after the referring tile/nav is repointed *and* that change is confirmed. Corollary of the
+  existing rule that the Bundle row must be deleted before the Product.
+
+## 7.6 Summary of corrections to PARTS 1–6
+
+| Claim in PARTS 1–6 | Status after the live run |
+|---|---|
+| `price_range`/`bundle_price_range` read `$0.00`, unusable | **Wrong.** Correct and country-resolved; the primary write-verification signal. Only top-level `price`/`display_price` are unusable. |
+| (Implied) one write call sets `bundle: true` with groups | **Split.** True for `create_bundle_product`; false for `update_bundle_product`, which needs a second flag call. |
+| Products sharing an option share a shape | **Never assume.** Classify per product by option id; components vs separate sellable items. |
+| An optional group can't affect the advertised price | **Wrong** for `dynamic_price` — it contributes its cheapest item. |
+| A `fixed_price: "0.00"` group is free | **Wrong.** `0.00` behaves as unset. |
+
+Unchanged and re-confirmed: `group_type` is a stored column; Surface A is the only safe write
+surface; never send included items (rule 3) and always tag the group (rule 4); routing is a
+theme-scoped join that must be re-run after a theme switch or clone; HTTP 200 is not success.
diff --git a/themes/dynamic-bundles/SKILL.md b/themes/dynamic-bundles/SKILL.md
new file mode 100644
index 0000000..1e7e1f2
--- /dev/null
+++ b/themes/dynamic-bundles/SKILL.md
@@ -0,0 +1,481 @@
+---
+name: dynamic-bundles
+description: Use when configuring, migrating, or theming Fluid Dynamic Bundles for ANY company — recreating an existing bundle implementation as Dynamic Bundles, building a reusable bundle theme from scratch, translating a source site's configurator/meal-builder page into a bundle, or diagnosing a bundle that renders wrong, won't add to cart, or charges the wrong price. Triggers - "dynamic bundles", "build your own", "bundle builder", "make <company> bundle-ready", "turn this page into a bundle", "migrate bundles", "bundle picker", "bundle won't add to cart", "bundle price wrong", "configurator page".
+---
+
+# Fluid Dynamic Bundles — universal build & migration skill
+
+> **This skill is a platform, not a migration.** Its output is one theme implementation
+> that renders *every* current and future bundle for a company with zero per-bundle code,
+> plus correctly-configured Dynamic Bundle records. Nothing it generates may contain a
+> bundle id, product id, group id, or group title.
+
+**The spec is `reference/00-BEHAVIOUR-MAP.md`** (every admin setting → renders → responds →
+cart → checkout). This file is the operating procedure; the reference corpus is the truth.
+Claims here are already reconciled against it — where this file and a reference doc disagree,
+the reference doc wins and this file is a bug.
+
+---
+
+## Where this sits — it runs AFTER onboarding, and replaces nothing
+
+This is a **follow-on capability**, not an alternative to the onboarding workflow. It assumes
+a company that already exists and already has a store.
+
+| This skill DOES | This skill does NOT |
+|---|---|
+| Read an existing catalog and classify how bundles work today | Import or create a catalog |
+| Configure Dynamic Bundle records on existing products | Scrape or clone a storefront |
+| Add a bundle section + host template to an **existing** theme | Create or seed a theme, or build a homepage / PDP / shop page |
+| Route bundle products to that template | Set up brand, domains, payments, countries |
+
+**Prerequisites, checked in G0 and stopped on:** the company has an active theme, and the
+catalog contains the products the bundle will be built from. If either is missing, say so and
+point at the onboarding workflow — do not start doing onboarding's job inside this one.
+
+Typical order: **onboarding (store + catalog + theme) → this (bundles on top)**. It is also
+correct to run this standalone, months later, on a mature store — that is the common case.
+
+---
+
+## Applies to every vertical, not just configurators
+
+Most companies sell ordinary products. A build-your-own configurator is the **hardest** case,
+not the typical one — do not treat it as the default shape and do not over-engineer toward it.
+
+The three shapes that cover the large majority of real bundles:
+
+1. **Fixed kit** — "Bundle & save", a gift set, a starter pack. Every component is
+   `included`; one flat price. No shopper choice at all. *This is the most common bundle on
+   the platform.*
+2. **One pick-N group** — "Choose any 3 flavours", "pick 2 shades". A single `customizable`
+   group over a set of variants.
+3. **Base + options** — an `included` core plus one or more choice groups. Configurators are
+   just this shape with more groups.
+
+Per-vertical patterns are in `playbooks/01-discovery.md` §5a, and the recipes for building
+each from scratch are in `playbooks/06-greenfield.md`. Food/QSR meal builders appear there as
+**one worked example among several**, because that is the test company — not because the skill
+is food-shaped.
+
+### Variants vs bundles — the distinction that decides everything
+
+Both are "a product with choices", and getting this backwards is the most expensive
+classification error in the skill. **Options do not settle it. What the option MEANS does.**
+
+| The option varies… | It is | Example |
+|---|---|---|
+| one indivisible item's own attributes | **variants** — leave alone | size, colour, length, scent of a single item |
+| **which components the item is composed of** | **a bundle** | protein, base, add-ons, configuration |
+
+The decisive, mechanical test: **do the option's values correspond to things that exist (or
+could exist) as their own catalog products?** A Large is not a product. Steak is. If the values
+map onto standalone products, the option is encoding *component selection* and the product is
+a bundle that was modelled as variants.
+
+Three corroborating signals, all checkable:
+
+1. The option's values match existing product titles in the catalog.
+2. The same option object is **shared across several parent products** — a real variant axis is
+   usually product-specific, whereas one "protein" option reused across burrito / bowl / tacos
+   is a menu-wide component axis.
+3. Variant price differences equal the price differences between those standalone components —
+   the variant price is carrying a component upcharge.
+
+Genuinely **not** bundles: a quantity break ("buy 3, save 10%"), a multipack with its own SKU,
+a "frequently bought together" upsell, a subscription of one product. Those are pricing and
+merchandising features.
+
+**A mis-modelled product is adjusted, not duplicated.** Creating a second "Build Your Own X"
+next to the existing X leaves the company with two products for one thing, one of them wrong.
+See `playbooks/02-translation.md` §5.
+
+---
+
+## 0. The 60-second model
+
+A bundle is a **Product** (`products.bundle = true`) + a shadow `Bundle` row + N
+`ProductBundleGroup`s each holding N `BundleGroupItem`s (one variant each).
+
+```
+BUNDLE   products.* · products.bundle_config · bundles.settings
+  └ GROUP   group_type = included | customizable   (a stored NOT-NULL column)
+      └ ITEM   one variant + config jsonb
+```
+
+- The **group's** type is stored. The **bundle's** static/dynamic nature is emergent
+  (`static?` = every group `included`).
+- Everything the client can act on crosses **one tag**:
+  `<script type="application/json" data-bundle-product>{{ bp | json }}</script>`.
+  What the drop serializes is the entire client contract, whatever the REST API returns.
+- Bundle-level flat pricing **collapses the layers** — group and item prices become
+  display-only. It is illegal to combine with a `dynamic_price` group (model validation),
+  so a theme never has to reconcile those two.
+
+---
+
+## 1. The nine rules that prevent essentially every bug
+
+1. **Detect with `product.product_bundle_groups.size > 0`.** Nothing else. `is_bundle` is
+   API-only; `slug`/`handle` are nil in page and section scope; `bundle_in_stock` is `true`
+   on non-bundles.
+2. **Write bundles only through Surface A** —
+   `POST /api/company/v1/products/create_bundle_product` /
+   `PATCH /api/company/v1/products/{id}/update_bundle_product`. It is the only surface that
+   writes `products.bundle_config` (*where the cart reads exclusivity*) and the only one that
+   validates. `/api/v2025-06/bundles` is READ-CROSS-CHECK ONLY (§5).
+3. **Never send included/static items** in `bundled_items` — the server reconstitutes them.
+   *Exception:* an included group inside an exclusive set **must** be sent, because the
+   server cannot know which branch was chosen.
+4. **Always send `product_bundle_group_id`** on every entry. Omitting it changes
+   `bundle_selection_key` (`1527:56794x1|…` vs `56794x1|…`) → duplicate lines → double charge.
+   Mixing tagged and untagged for one variant is a hard 422.
+5. **Read exclusivity from `bundle_config.mutually_exclusive_groups`.** It holds
+   **`sort_order`s, not group ids**, in two shapes (`[{ids:[…],default:…}]` or a bare
+   `Array<Integer>`), and is `null` — not `[]` — on older bundles.
+6. **Collapse duplicate variants into `quantity`.** The server counts **units**, and does
+   **not** de-duplicate entries. One entry per click = silent over-charge.
+7. **HTTP 200 is not success.** The SDK promise resolves `undefined` on failure and destroys
+   the server's message. A country-unavailable child returns 200, prices the bundle at
+   **$0.00**, and leaves `items[].errors` **empty**. Verify by reading the cart back.
+8. **Every price is a chain.** `item.price` is `"0.0"` on 100% of fixtures and a zero there
+   means *unset*, not free. See §4.
+9. **Match bundle → product by `product_bundle_groups[].id`, never by slug.** Duplicate and
+   orphan `Bundle` rows share a title and the later row often owns the uniquified slug.
+   And **delete the Bundle before the Product** — reverse order leaves an orphan whose
+   `DELETE` then 500s forever.
+
+---
+
+## 2. The three moving parts — two are missing by default
+
+| Part | Default on a new company |
+|---|---|
+| A bundle-rendering section | ✅ the platform's `product_bundle` is free everywhere (one global row unioned into every theme) |
+| A `product` template hosting it | ❌ **no seed ships one** |
+| Routing (product → that template) | ❌ **no auto-assignment exists** |
+
+Routing is not a column — it is a `template_resources` join **scoped to the currently-active
+theme**. Consequences:
+
+- **Switching or cloning a theme silently un-routes every bundle.**
+- A bundle created via API with no explicit `application_theme_template_id` comes back `null`.
+- **A bundle on a bundle-unaware theme is a silent revenue hole**: normal-looking product
+  page, working native add-to-cart, hard failure at checkout. Nothing surfaces to the merchant.
+
+---
+
+## 3. Architecture decision — generate, don't clone
+
+This skill generates a **theme-owned** section (`bundle_builder`) implementing the platform's
+data + cart contract exactly, and owning its own presentation. It does **not** clone the
+platform's `product_bundle`. Five reasons, in order of weight:
+
+1. **"Match the brand" is unachievable with the platform section.** 46 inline `style=`
+   attributes and 18 hardcoded hex colours outrank any stylesheet.
+2. **A clone inherits ~11 client-side defects** (P2, P5, P10, P14, P15, P16-client, P17, P19,
+   P20, P21, P1's escaping) that we can simply not write.
+3. **A clone never receives updates anyway.** `auto_upgradeable?` is hardcoded `false` and a
+   theme-local copy shadows the global permanently. Cloning *guarantees* the drift it is
+   supposed to avoid — two Chick-fil-A clones are already 15.7 KB stale.
+4. **The stable part of the platform is the contract, not the UI.** The drop shape and cart
+   schema are documented and are what we build against.
+5. **Collision safety.** The platform section emits 31 generic utility class names
+   (`.btn`, `.container`, `.text-sm`, `.flex` …) into whatever theme hosts it.
+
+A patched clone remains available as documented, non-default **parity mode**
+(`playbooks/03-theme-generation.md` §9).
+
+### 3a. The trilemma this avoids
+
+Global sections never resolve typed `{% schema %}` settings (defect **P3**), so pinning
+`bundle_product` on a global install yields a **dead shell**; and exclusivity is top-level
+only in the 40-key drop shape, not the 50-key page shape a PDP gives you. No stock
+configuration gives both exclusivity and scale. Owning the source + reading exclusivity from
+`bundle_config` gives both.
+
+**Never pin `bundle_product` on a `product/*` template.** It hard-wires one bundle and drops
+hidden groups. Pin only on `home_page`/`page` templates, where there is no page product.
+
+---
+
+## 4. Price and type traps
+
+- **Item:** `country_prices[ISO]` → `item.price` (>0) → `variant.variant_countries[ISO].price`.
+- **Group:** `pricing_config.country_pricing[ISO]` → `pricing_config.fixed_price`.
+  `group.fixed_price` reads `"0.0"` when unset — check `pricing_config.fixed_price` for **key
+  presence** to distinguish unset from a real zero. `min_price`/`max_price`/`compare_at_price`
+  are dead (`"0.0"` on every live group).
+- **Bundle:** `bundle_config.bundle_pricing_config.country_pricing[]` (values are **strings**,
+  `country_code` UPPERCASE, `enabled` strict `== true`). `product.bundle_price` is empty even
+  with bundle pricing on. `primary_price`/`primary_currency` are admin echo, never read by Rails.
+- `product.price` in the Liquid drop **is** correct and country-resolved (`"$50.00"`, or a
+  `"$30.00 - $70.00"` range when any group is dynamic). Top-level `price` and `display_price`
+  from the JSON APIs are computed with `country_code: nil` and read `0.0` / `$0.00` — unusable
+  (every live bundle reports `display_price: "$0.00 (USD)"`).
+- **`price_range` / `bundle_price_range` sum each item's `config.price`. They do NOT read the
+  group's `fixed_price`.** So:
+  - **dynamic** choice groups → the range is correct and arithmetically checkable. Use it.
+  - **all-fixed** bundle (anchor holds the price, items all `0.0`) → the range reads **`$0.00`**
+    on a fresh GET while the cart charges correctly. Not a reader defect — an accurate sum of
+    zeros. Useless for verification, and dangerous on any storefront surface that renders it.
+- **A PATCH echo is not proof.** On 2026-08-06 an all-fixed kit was recorded at `$52.00` from
+  the `update_bundle_product` echo; a fresh `GET` on 2026-08-08, stored config byte-identical
+  and `updated_at` unchanged, returns `0.0`. The cart was correct at `$52.00` throughout
+  (verified with a real cart POST). **Never verify a write from the response to that write —
+  always re-`GET`, or prove it with a cart.** See `playbooks/09-pricing-patterns.md` §5.
+- In one object: `price`/`wholesale`/`compare_price` are **floats**, `subscription_price` is a
+  **string**. `cv`/`qv` are Integers in Liquid, **strings** in both APIs. `display_*` carries a
+  `" (USD)"` suffix. Drop prices can be BigDecimal engineering notation (`"0.4999e2"`) —
+  `parseFloat` survives it, `{{ item.price }}` in Liquid does not.
+- **Compare-at**: render only when `compare_price > price`, else you advertise an increase.
+- **CV/QV only flow from `dynamic_price` groups.** Fixed-price and flat bundles credit 0/0
+  unless CV/QV is re-entered on the group or bundle `country_pricing` row. Never sum
+  `variant_countries[].cv` into a "you'll earn N CV" promise.
+
+---
+
+## 4a. Planning rules learned in the field
+
+1. **Variants must exist before groups are built.** A group built while its component
+   products were single-variant points at the only variant available; once real variants are
+   added that pointer is *wrong* and the group must be repointed. A second group built too
+   early had 43 items where the source offered 117 (43 products × sizes) and needed a full
+   rebuild. **Assert in preflight: every product that will become a component already carries
+   its full variant set.** If not, fix the catalog first — this is a G0 check, alongside
+   active-theme and non-empty-catalog.
+
+2. **Group membership comes from the source, per bundle — never derived from the component
+   product.** Different bundles offer different subsets of the same product's variants; one
+   bundle offered three sizes of a component, another offered a smaller size the first did
+   not. Deriving from the parent product's full variant list silently adds options the
+   merchant does not sell. Where the source declares a default member, honour it; where it
+   declares none, use the cheapest.
+
+3. **Upgrade pricing needs a rebalanced base**, not just `dynamic_price` — see
+   `playbooks/09-pricing-patterns.md`. Compute `base = headline − Σ(defaults)` per bundle and
+   assert `base >= 0` before writing. A negative base is normal for value bundles and is
+   resolved by honouring the source's default; if it is still negative, **escalate**.
+
+4. **Bundles are not interchangeable — census before any batch.** Flag any candidate whose
+   computed base is negative or zero, that carries an explicit price-increment mechanism,
+   whose group count or min/max differs from the proven shape, or that has more than one
+   anchor candidate (or none). Anything unresolved is **skipped and named**, never guessed.
+   Convert in batches behind a human gate, then cart-verify a sample spanning the *kinds* of
+   bundle — premium, value, and any odd shape — not just the easy ones.
+
+---
+
+## 5. Write surfaces
+
+**Surface A — `create_bundle_product` / `update_bundle_product`** (what the admin Bundle
+Builder uses). The only surface that can set `products.bundle`, `bundle_config`,
+`track_inventory_on_bundle_items`, variants, `variant_countries`, images, SEO, group
+`images_attributes`, `_destroy` nested deletes — and the only one that runs
+`BundleConfigValidation`. **Use this exclusively for writes.**
+
+**Surface B — `/api/v2025-06/bundles`** — a trap. No pagination (`per_page`/`page` silently
+ignored), **omits `product_id`** (you cannot get from bundle to product), skips validation,
+writes `bundles.settings` without mirroring to `products.bundle_config` (so exclusivity
+written here is honoured by the portal and **silently ignored by the cart**), returns **500
+not 422** on schema errors, `items[].is_default` 500s on update and is dropped on create,
+`sort_order` is overwritten by array position, and `groups: []` destroys all groups.
+
+### 5a. The write contract — inline, as the safety net
+
+A workflow step chat does not inherit the launching skill's materialized files, so
+`playbooks/`, `templates/` and `reference/` have repeatedly come back ENOENT. Every step of
+the `dynamic-bundles` workflow now calls `run_skill("themes/dynamic-bundles")` first, which
+materializes them — but if that call fails, this table is all you have. Do not go looking for
+the write recipe elsewhere and do not improvise it.
+
+| Rule | Detail |
+|---|---|
+| Surface A only | `POST create_bundle_product` / `PATCH /api/company/v1/products/{id}/update_bundle_product`. Never `/api/v2025-06/bundles` for writes. |
+| `product.title` required on **every** call | Omitting it → `422 product.title is missing`, even when updating only pricing. |
+| Nested keys | `product_bundle_groups_attributes` / `bundle_group_items_attributes`. |
+| `is_default` goes **inside `config`** | At top level it is silently dropped. |
+| **Create = 1 call, convert = 2** | `bundle: true` persists on `create_bundle_product`; on `update_bundle_product` it does not — a second groups-free `{id, title, bundle: true, status}` call is required. |
+| Items are **append-only** | Omitted existing items are kept, not removed. |
+| Uniqueness on (group, variant) | Re-sending an existing variant `422`s the **whole request**, atomically. Useful as a cheap non-mutating membership oracle. |
+| Group-level `_destroy` **does not work** | Returns 404 even for a group that exists. Do not plan delete-and-recreate around it. Item-level and variant-level `_destroy` DO work. |
+| Item updates by `id` work | Including repointing `variant_id` in place — this is how you fix a group pointing at the wrong variant. |
+| `images_attributes` **appends** | It does not replace. Send `_destroy` with the old image id when swapping. |
+| Reads cap at 51,200 bytes | A large bundle cannot be read whole. Page it by PATCHing visible items' `sort_order` into a high block and re-reading. |
+| Unknown keys silently dropped, 200 | Always read back and diff. |
+| **A PATCH echo is not proof** | The echo can show values a fresh GET does not. Always re-`GET`. |
+
+Cart writes need **both** `fluid_shop` and a top-level **`country_code`** — omitting the
+latter is `422 country_code is missing`.
+
+---
+
+## 6. The workflow
+
+Run the **`dynamic-bundles` workflow** — it is this skill's execution engine, with per-step QA
+and bounded rework. Everything before `write-bundles` is read-only.
+
+**You are the launcher. Collect these before calling `run_workflow`** — the workflow cannot
+recover from any of them being wrong, because a step chat only ever sees the start context:
+
+| Context key | Why it must come from you |
+|---|---|
+| `theme_id` | **Required.** Mist picks the project for a theme-targeted step from `context.theme_id`. Absent, it takes the first local theme checkout or scaffolds one — so the run can silently build into a theme nobody asked for. `preflight` stops the run if this is missing or disagrees with the active theme. |
+| `approved` | Gates the entire mutating tail via `runIf`. Absent or falsy, steps 5–9 are condition-skipped and the run still completes, reporting a plan and no writes. |
+| `source_url` | Optional. Present → `source-analysis` runs; absent → it is condition-skipped, which satisfies its dependents, so the run proceeds without it. |
+
+`approved: true` says *this run may write*. It is **not** consent to a plan that does not exist
+yet when `run_workflow` is called. `write-bundles` therefore calls `human_in_the_loop` with the
+plan's real numbers and gets approval for **that** before its first write.
+
+| # | Step | QA on fail |
+|---|---|---|
+| 1 | `preflight` — company, `fluid_shop`, active theme vs `context.theme_id`, variant completeness (**G0, blocking**) | **stop** |
+| 2 | `study-company` — catalog, shapes, anchors, theme token lineage | continue |
+| 3 | `source-analysis` — the source configurator (`runIf: source_url`) | continue |
+| 4 | `plan-translation` — `bundle-plan.json` + the base arithmetic, `base >= 0` | **stop** |
+| 5 | `write-bundles` — Surface A; `human_in_the_loop` on the plan, then write; fresh-GET verify | **stop** |
+| 6 | `picker-section` — the one reusable section | continue |
+| 7 | `price-surfaces` — inventory and wire every surface that shows a price | continue |
+| 8 | `route-and-render` — per product, on the ACTIVE theme | continue |
+| 9 | `cart-and-money` — default / upgrade / downgrade / **negative case** through the cart API | continue |
+| 10 | `reusability-and-report` — proof, manifest, four-part report | continue |
+
+Steps 5–9 carry `runIf: {flag: "approved"}`. Step 10 deliberately does not, so an unapproved
+run still ends with a report saying what it would have written.
+
+Greenfield collapses 2–4 to "no existing implementation" and builds **one real bundle from
+the live catalog** as the proving fixture.
+
+Playbooks: `01-discovery` · `02-translation` · `03-theme-generation` · `04-routing` ·
+`05-validation` · `06-greenfield` · `07-troubleshooting` · `08-api-write-recipe` ·
+`09-pricing-patterns` · `10-ui-and-price-surfaces`.
+(`09` and `10` supersede `02`/`03` where they overlap — they are field corrections.)
+
+**The workflow may not exist in this company.** The skill catalog and the workflow library
+sync separately and per-company; a skill can be present with no matching workflow. Check
+first. If `dynamic-bundles` is absent, either author it from the table above with
+`create_workflow` — carrying the acceptance criteria, not just the step names — or run the
+steps directly in order. Do not assume it arrived with the skill.
+
+**If you run the steps directly instead**, you are running them in one chat, so `run_skill` and
+the `runIf` gating do not apply — but the two gates they encode still do. Do not write until a
+human has seen the actual plan, and confirm which theme you are editing before the first file
+write.
+
+---
+
+## 7. Beliefs to discard
+
+| Belief | Reality |
+|---|---|
+| Group type is emergent from config | `group_type` is a stored NOT-NULL column |
+| Products sharing an option share a pattern | Check the **option id per product**. Option values that are *components of one item* → bundle; values that are *separate sellable items* → category/collection. Converting a category into one bundle destroys a listing and advertises one wrong price (hit 3× in one session) |
+| A group priced `fixed_price: "0.00"` is free | `0.00` behaves as **unset** — components fall back to their own variant price and inflate the bundle floor |
+| Flipping choice groups to `dynamic_price` gives upgrade pricing | It double-charges unless the anchor base is rebalanced. `base = headline − Σ(defaults)`. See `09-pricing-patterns.md` |
+| A `$0.00` read means the platform is broken | It usually means every item genuinely resolves to zero. Check the configuration before filing a defect |
+| A PATCH echo confirms the write | It does not. Re-`GET`, or prove it with a real cart |
+| Group-level `_destroy` removes a group | Returns 404. Only item- and variant-level `_destroy` work |
+| Sending the full item list replaces the group's items | Items are **append-only**; omitted items are kept |
+| An optional group can't affect the advertised price | An optional `dynamic_price` group adds its **cheapest** item to `price_range.min` regardless of `min_selections: nil` |
+| `product.bundle` is nil in section scope | It works. Only `is_bundle` / `slug` / `handle` are nil |
+| Legacy `ProductBundle` is retired | Still writable, still read, still rendered |
+| Send every selected item to the cart | Included/static items must NOT be sent — except exclusive members |
+| Use `data-fluid-bundled-items` (declarative) | Call the SDK imperatively; the declarative path has 4 silent-failure modes |
+| Child clicks on the CTA are ignored (`e.target`) | **Fixed** — the SDK uses `closest()` |
+| The section self-gates on non-bundles | It doesn't. Only the data blob is gated |
+| Bundles auto-route to a bundle template | No auto-assignment exists. Manual, per product, per active theme |
+| `product.bundle_price` gives the price | Empty even when bundle pricing is on |
+| Exclusivity via `product.mutually_exclusive_groups` | Absent from page scope, silently no-ops |
+| `include_parent_in_orders` changes order lines | No effect in Rails; advisory only |
+| Group `allow_subscriptions` gates subscriptions | Never read server-side — check the item too |
+| Add-to-cart errors surface to the theme | Promise resolves `undefined`; errors swallowed |
+| MutationObserver freeze / hiding the native CTA | Only ever needed for the hand-authored picker |
+
+---
+
+## 8. Assumptions that do NOT hold across companies
+
+Every one was observed varying. This list is why "universal" is hard.
+
+1. **Two CSS token lineages** — `--clr-*` (7 themes) vs `--color-*` (chewy, where `--clr-*` is
+   an alias shim). Resolve with layered `var()` fallbacks, never a hardcoded token name.
+2. **Three `.container` widths, two mechanisms**, and the **newest PDPs bypass `.container`
+   entirely** for a per-section container keyed to `section.id`. A section that wraps itself
+   in `.container` misaligns with the rest of the PDP on those themes — guaranteed, visible.
+3. `button, .btn {}` is **hijacked on 6 of 8 themes** into a black flex box;
+   `-webkit-appearance: none` makes **native radios and checkboxes invisible on every theme**;
+   `ul, li { list-style: none }` kills bullets on 7 of 8. Ship a scoped compat layer.
+4. `!important` density ranges 0 → 16, plus 7 more inline.
+5. **One currency / 2 decimals is not safe** — read `localization.country.currency.symbol`
+   and `.decimal_places`.
+6. **One subscription plan is not safe** — the multi-plan picker has never been exercised
+   upstream. Treat it as unproven and degrade cleanly.
+7. **Hidden-group filtering differs by scope** — the drop rejects `pricing_config.hidden`, the
+   page path does **not**. Filter yourself.
+8. `description` on a group can be `""` *or* `null`. Some fixtures have **no image anywhere**.
+9. **API traps that fake theme bugs:** `per_page=100` on `/api/company/v1/products` returns
+   **zero** products with no error (50 works); ignored filters return an unfiltered page;
+   `?country=CA` is ignored, `?country_id=<numeric>` works.
+10. **Enrollment bundles are not supported.** The drop exposes the same data; there is zero
+    rendering support anywhere. Refuse honestly.
+
+---
+
+## 9. Before you file a bug
+
+A bundle rendering wrong is **more often theme, routing, or data than a platform defect** — in
+the source campaign three bundles showed "no bundle UI" and only **one** was a real fault (the
+others were a draft product and a product with zero groups). Work
+`reference/12-theme-health-check.md` first, then `reference/13-defect-triage.md`.
+**8 of 21 reported defects were downgraded.** Do not file P7, P12, P4 (by design) or
+P11, P13, P16, P18 (fixture artifacts the Bundle Builder cannot produce).
+
+The two worth acting on: **P2** (exclusivity — shopper charged for a branch they never
+receive, $60 confirmed) and **P19** (defaults over max → unrecoverable `3 / 1` in one click).
+
+---
+
+## 10. Where things are
+
+**Everything this skill needs ships inside the skill's own directory.** Paths below are
+relative to the directory holding this `SKILL.md`, so they resolve the same way for every
+company — there is no dependency on any particular workspace.
+
+| What | Path |
+|---|---|
+| These playbooks | `playbooks/*.md` |
+| The `bundle_builder` section | `templates/sections/bundle_builder/index.liquid` |
+| The four-layer JS engine | `templates/assets/bundle-builder.js` |
+| Token-only CSS | `templates/assets/bundle-builder.css` |
+| Host template | `templates/product/bundle/index.liquid` |
+| Manifest schema | `schemas/bundle-manifest.schema.json` |
+| The reference corpus (the spec) | `reference/*.md` |
+
+**Assume you may not be able to read any of them.** Workflow step sandboxes have repeatedly
+failed with ENOENT on `playbooks/`, `templates/` and `reference/`. `SKILL.md` is written to be
+sufficient on its own — §5a carries the full write contract for exactly this reason. If a
+playbook is unreachable, say so in the report and proceed from this file; do not stall, and
+do not silently reverse-engineer a contract that is already written down here.
+
+If `reference/` is missing the skill still runs — it is the evidence behind the rules, needed
+only when triaging a suspected platform defect (§9) or checking a claim.
+
+Copy the artefacts into the theme and **adapt only what `01-discovery.md` §3 recorded about the
+host theme** — they are already lineage-agnostic. A step running inside a theme project that
+cannot see the skill directory can be handed the four artefact files by the operator; nothing
+else needs to travel.
+
+| Need | Read |
+|---|---|
+| The spec | `reference/00-BEHAVIOUR-MAP.md` |
+| Model, APIs, validators | `reference/01-model-and-backend.md` |
+| Hosting & routing procedure | `reference/02-hosting-and-routing.md` |
+| The Liquid drop contract | `reference/03-data-contract.md` |
+| Cart / checkout contract | `reference/07-cart-contract.md` |
+| Pricing & subscriptions (empirical) | `reference/06-pricing.md` |
+| Admin control → data field | `reference/08-admin-reference.md` |
+| Per-company readiness & theme variance | `reference/09-company-readiness.md` |
+| Defects + triage | `reference/10-known-defects.md`, `reference/13-defect-triage.md` |
+| Health check first | `reference/12-theme-health-check.md` |
+| Proof | `reference/14-verification.md` |
diff --git a/themes/dynamic-bundles/playbooks/01-discovery.md b/themes/dynamic-bundles/playbooks/01-discovery.md
new file mode 100644
index 0000000..99c6100
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/01-discovery.md
@@ -0,0 +1,256 @@
+# 01 — Discovery: classify, never assume
+
+Read-only. Output is `bundle-discovery.json` plus a written answer to
+**"how do this company's bundles work, and *why*?"** — not a config dump.
+
+---
+
+## 1. Preflight (gate G0)
+
+| Check | How | Fail action |
+|---|---|---|
+| Active theme | `GET /api/application_themes` → the single `status:"active"` row | Stop. Only the active theme renders. |
+| Templates | `GET /api/application_theme_templates?application_theme_id=<id>` (root key `templates`, includes globals — `application_theme_id: null` means global, not the company's) | — |
+| Countries / currency / decimals | company countries + `localization` | Never assume USD/2 |
+| Subscription plans | plan inventory per product | Multi-plan is unproven upstream |
+| SDK boots | fetch a storefront product page, assert the `fluid-cdn-script` tag | P17: no SDK = perfect page, dead button, no console error |
+| Storefront host | `<slug>.fluid.app` or custom domain | Needed for every later verification |
+
+---
+
+## 2. Catalog scan
+
+`GET /api/company/v1/products?per_page=50` — **never 100**, which returns zero products with
+no error. Page to exhaustion. For each product keep: `id`, `title`, `slug`, `status`, `bundle`,
+`product_bundle_groups[]` (ids, types, selection rules, pricing), `product_bundles[]`,
+`variants[].variant_countries[]`, `application_theme_template_id`, images.
+
+Cross-check with `GET /api/v2025-06/bundles` — **read only**. It has no pagination and omits
+`product_id`, so **match bundle → product by `product_bundle_groups[].id`**, never by slug
+(slug matching resolved the wrong bundle on ≥3 known fixtures, one of which reports empty
+`country_pricing` while the product actually charges $25).
+
+Flag, do not fix: orphan `Bundle` rows (storefront 302s to /404), products with
+`bundle: true` and zero groups, bundles with `status: draft`, bundles with
+`application_theme_template_id: null`.
+
+---
+
+## 3. Theme scan
+
+Pull every template and section of the **active** theme and grep for:
+
+| Signal | Means |
+|---|---|
+| `{% section 'product_bundle' %}` | a canonical host exists |
+| a theme-local `sections/product_bundle` | a clone — diff it against the global; it will never auto-update |
+| `dynamic_bundle_picker`, `data-dbp-`, `data-fluid-dbp` | hand-authored picker (Archetype B) |
+| the picker injected into `product/default` | must be un-injected |
+| `data-fluid-bundled-items` | declarative cart path — 4 silent-failure modes |
+
+Also record, because they decide how the generated CSS is written: the token lineage
+(`--clr-*` vs `--color-*`), the `.container` mechanism (or a per-section container keyed to
+`section.id`), the `button, .btn {}` reset, the input `-webkit-appearance` reset, the
+`ul, li { list-style: none }` reset, radius and type scale.
+
+---
+
+## 4. Live storefront probe
+
+For one representative product, compare all three render paths — this is how you tell a
+platform bug from a theme bug:
+
+```
+plain:     https://<co>.fluid.app/home/products/<slug>
+canonical: …?preview=true&theme_template_id=<canonical host>
+picker:    …?preview=true&theme_template_id=<hand-authored host>
+```
+
+Markers: canonical → `data-bundle-section`; hand-authored → `data-dbp-*`; ours → `data-bb-root`.
+
+Parse the data blob directly — key count is diagnostic: **50 = page scope** (exclusivity is
+only in `bundle_config`), **40 = `ProductDrop#as_json`** (top-level exclusivity present,
+hidden groups dropped).
+
+---
+
+## 5. Archetypes
+
+Classify with a confidence score and the evidence that produced it.
+
+| # | Archetype | Signals | Action |
+|---|---|---|---|
+| **A** | Already dynamic bundles | products with `product_bundle_groups.size > 0` | Audit + re-theme + fix routing/pricing gaps. No data migration. |
+| **B** | Hand-authored picker | picker section in the theme; `data-dbp-*` on live pages | The picker's own rule/pricing/submit logic **is** the behavioural spec — read it, port it, then un-inject from `product/default`. |
+| **C** | Legacy flat `ProductBundle` | `product_bundles[]` non-empty, `product_bundle_groups` empty | Convert to one `included` group (split by `display_externally` into visible + hidden). Preserve `quantity`. **Capture pricing intent first** — these price from the master variant like a normal product. |
+| **D** | Convention-based "fake" bundles | kit/combo/bundle titles with multi-variant options; descriptions enumerating components; a component catalog with a parent SKU pattern | **Propose, never auto-convert.** Present candidates with evidence; the user confirms each. |
+| **E** | Greenfield | zero bundles, zero infrastructure | `playbooks/06-greenfield.md` |
+| **F** | External source page | a reference URL that is a configurator or a fixed bundle page (§6) | Translate the page's own option model into groups. |
+| **G** | **Mis-modelled variant product** | a multi-variant product whose option encodes COMPONENT choice, not item attributes — see the test below | **Adjust the existing product in place.** Never create a parallel "Build Your Own X" beside it. Propose, with the price consequence stated. |
+
+A company can be several at once. Classify per product, not per company.
+
+Archetype G is common on any store whose catalog was imported or built by an earlier automated
+pass: a menu, a configurator or a kit gets flattened into one product with one option axis,
+because that is what a plain product importer can express. It is the single most likely thing
+this skill will find on a company that has already been through onboarding — and it is the case
+a naive read dismisses as "just variants".
+
+---
+
+## 5a. What a bundle looks like, by vertical
+
+Most companies sell ordinary products. **A configurator is the hardest case, not the common
+one.** Rank your expectations accordingly: the single most frequent real bundle on the platform
+is a fixed kit with one flat price and no shopper choice whatsoever.
+
+| Vertical | How the bundle usually presents | Group shape |
+|---|---|---|
+| **Any** — the baseline | "Bundle & save", gift set, starter pack | all `included`, bundle-level flat price |
+| Supplements / wellness | "Starter stack", "3-month supply", "build your stack" | `included` base + `max_only` add-ons; subscription often forced |
+| Beauty / skincare | "Build your routine", custom kit, "pick 3 shades" | `exact N` over shade/size variants, `dynamic_price` |
+| Apparel | "Build a set", "3 for $99", "complete the look" | `exact N` or `min_and_max`, group `fixed_price` |
+| Food / QSR | meal builder, "make it a combo" | `included` base + `exact 1` protein + `max_only` toppings |
+| Electronics / hardware | "Configure", "kit with accessories" | `included` core + `exact 1` config + `max_only` accessories; **exclusive pairs common** |
+| Pet | variety pack, "pick your flavours" | one `exact N` group |
+| Coffee / beverage | "choose 3 bags", subscription bundle | `exact N` + subscription |
+| Home goods / furniture | room bundle, matching set | all `included`, flat price |
+| Direct sales / MLM | business builder kit, **enrollment pack** | catalog bundles fine; **enrollment bundles are UNSUPPORTED — refuse** |
+
+**Variant-dimension trap, most visible in apparel and beauty.** A bundle item is a *variant*,
+not a product. So "pick a shirt, then pick its size" is two-dimensional, and the platform has
+only one dimension: you enumerate the variants you want selectable. Either the group lists one
+representative variant per style (and size is handled elsewhere), or it lists every
+style×size variant and gets large fast. Surface this to the user rather than silently choosing —
+it changes the shopper experience materially.
+
+### Variants vs bundles — run this test on every multi-variant product
+
+Do **not** dismiss a product just because it has options. Options are how a mis-modelled
+bundle looks. Ask what the option *means*:
+
+| The option varies… | Verdict |
+|---|---|
+| attributes of one indivisible item (size, colour, length, scent) | **variants** — leave alone |
+| **which components the item is made of** (protein, base, configuration, add-on) | **archetype G** — a bundle modelled as variants |
+
+**The mechanical test: do the option's values correspond to things that exist, or could exist,
+as their own catalog products?** A Large is not a product. Steak is.
+
+Run these three checks and record the result per product:
+
+1. **Value↔product match** — normalise each option value and look for a catalog product with
+   that title. A high match rate means the option is component selection.
+2. **Shared option object** — is the same option `id` attached to several parent products? A
+   real variant axis is usually product-specific; a shared axis is a menu/category-wide
+   component choice.
+3. **Price-delta correspondence** — do the variant price gaps equal the price gaps between
+   those standalone components? Then the variant price is carrying a component upcharge.
+
+Genuinely **not** bundles, decline with a reason: a quantity break, a multipack with its own
+SKU, a "frequently bought together" upsell, a subscription of one product.
+
+> **Observed live (Chipotle, 2026-08).** `Burrito` (89585) and `Burrito Bowl` (89586) each had
+> one option — `"protein or veggie"`, **option id 1144, shared between them** — with 7 variants
+> priced $9.35–$11.35, and every value (Chicken, Steak, Sofritas, Veggie…) also existing as a
+> standalone product. No rice, beans or topping modelling anywhere, so a shopper could choose a
+> protein and nothing else. All three signals fired. These are archetype G, and the first run
+> of this workflow missed them because the rule then in force excused "flavour" options.
+
+---
+
+## 6. Archetype F — recognising a bundle from a source page
+
+**The agent should not need to be told a page is a bundle.** Crawl the URL with
+`formats:['markdown','html']` and `only_main_content:false`, then score the signals below.
+
+There are **two** shapes to recognise, and the simpler one is more common:
+
+**Shape 1 — fixed bundle page.** "What's included" / "In this kit" / "This set contains" plus
+an itemised component list, ONE price (often struck through against a higher "value" figure),
+and a plain add-to-cart. No selection UI at all. ⇒ all `included` groups, flat price. Do not
+invent choice groups for a page that offers none.
+
+**Shape 2 — configurator.** Signals below. This is the harder case and the rarer one.
+
+**Strong (any two ⇒ configurator):**
+- Repeated option cards in labelled sections, where the section heading is an instruction —
+  "Choose your…", "Pick 2", "Add…", "Select up to…".
+- A running total or price that updates as options change, and a single terminal CTA
+  ("Add to bag", "Add to order") rather than one CTA per card.
+- Cards carrying a per-item price delta (`+ $2.00`, "Free", "Included").
+- A quantity stepper or an "extra / double" affordance on individual cards.
+- Radio-like exclusivity within a section (one selection replaces another) versus
+  checkbox-like multi-select in another.
+
+**Supporting:**
+- URL shape: `/build`, `/builder`, `/customize`, `/configure`, `/create-your-own`, `/bundle`.
+- A step/progress indicator, or a persistent summary panel.
+- Structured data (`ProductGroup`, `hasVariant`, `AggregateOffer`) with more members than a
+  normal PDP.
+
+**Extraction → group model.** For each section of the page:
+
+| Read from the page | Becomes |
+|---|---|
+| Section heading text | `group.title` |
+| "Choose 1" / a radio group | `customizable`, `selection_type: exact`, `min_selections: 1` |
+| "Pick 2" / "Choose 3" | `exact`, `min_selections: N` |
+| "Add up to N" / optional checkboxes | `max_only`, `max_selections: N` |
+| "Choose at least N" | `min_only` |
+| No limit stated, multi-select | `max_only` with `max_selections` = the item count, flagged for confirmation |
+| Cards with a `+$` delta | `pricing_type: dynamic_price` |
+| Cards all free / no deltas shown | `fixed_price` with `fixed_price: "0.0"` **explicitly set** |
+| An always-present component, no picker | `included` group — **and it must get an explicit price** |
+| Two sections where choosing one hides the other (bowl vs burrito) | an exclusive pair |
+| "Extra"/"Double" on a card | item `max_quantity: 2` |
+| A card pre-highlighted on load | item `config.is_default: true` |
+
+**Then map each extracted option to a real catalog product** by normalised title, then SKU,
+then fuzzy match. Report three buckets: matched, ambiguous (≥2 candidates — ask), missing
+(no catalog product — offer to create, or exclude). **Never invent a variant id.**
+
+### JS-gated pages — the general rule
+
+Configurators are frequently client-rendered and bot-protected (Kasada, Cloudflare, Akamai, or
+simply a hydrated SPA). When the crawl returns a shell with no option cards:
+
+1. Say so explicitly and name the reason. **Report it as a capture limitation, never as an
+   empty result** — "no options found" and "could not read the page" are different findings and
+   conflating them is the failure mode here.
+2. Ask the user to paste the rendered HTML (DevTools → Elements → copy outer HTML). Option
+   cards in a modern configurator almost always carry stable hooks — a `data-*` item name/id,
+   an `aria-label` with price, a background-image URL — so a paste is deterministic to parse.
+3. Fall back to a plain-language description from the user only if the paste is unavailable,
+   and mark every derived group as **needs confirmation**.
+
+> **Worked example (food/QSR, the test company).** `chipotle.com/order/build/burrito` is a
+> Kasada-protected Vue app fed by `services.chipotle.com`. On the pasted HTML every
+> `.meal-builder-item-selector-card-container` carries `data-qa-item-name`, `data-qa-item-id`,
+> an `aria-label` with price + calories, an optional `.item-tagline`, and a `background-image`
+> pointing at the official DAM PNG — and 47 of those components already exist as individual
+> products, so the matching stage resolves against the live catalog rather than creating
+> anything. The *shape* of that recovery generalises; the selectors are that site's.
+
+---
+
+## 7. Output — `bundle-discovery.json`
+
+```jsonc
+{
+  "company": { "id": 0, "slug": "", "storefront": "", "countries": ["US"], "currency": {} },
+  "theme":   { "activeId": 0, "tokenLineage": "clr|color", "containerMechanism": "",
+               "resets": { "button": true, "inputAppearance": true, "listStyle": true },
+               "hasCanonicalHost": false, "hasLocalSectionClone": false, "pickerSections": [] },
+  "archetypes": [ { "kind": "A|B|C|D|E|F", "confidence": 0.0, "evidence": [], "productIds": [] } ],
+  "bundles":  [ { "productId": 0, "bundleId": 0, "matchedBy": "group_id", "groups": [],
+                  "routedTemplateId": null, "issues": [] } ],
+  "candidates": [ { "productId": 0, "why": [], "proposedGroups": [] } ],
+  "sourcePages": [ { "url": "", "captured": "html|blocked", "sections": [], "matching": {} } ],
+  "blockers": []
+}
+```
+
+**G1 passes when:** every candidate is classified with evidence; no product is both "bundle"
+and unclassified; enrollment bundles are flagged unsupported and excluded; every source-page
+option is matched, ambiguous, or missing — never silently dropped.
diff --git a/themes/dynamic-bundles/playbooks/02-translation.md b/themes/dynamic-bundles/playbooks/02-translation.md
new file mode 100644
index 0000000..0f1766f
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/02-translation.md
@@ -0,0 +1,154 @@
+# 02 — Translation: existing behaviour → Dynamic Bundle records
+
+Output is `bundle-plan.json`. Nothing writes until the plan is approved.
+
+**Preservation priority, in order.** When two cannot both be preserved, the higher one wins
+and the conflict is surfaced, never silently resolved:
+
+1. charged price → 2. selection semantics → 3. subscription semantics → 4. exclusivity →
+5. defaults & quantity caps → 6. copy & imagery.
+
+---
+
+## 1. The mapping table
+
+| Source concept | Target | Trap |
+|---|---|---|
+| "always included" component | `included` group, item `quantity` = component qty | **Must set an explicit `fixed_price`** — an included group with no price displays as its item sum and charges **$0.00** (finding C). If it really is free, set `"0.0"` deliberately and record that. |
+| "pick exactly N" | `customizable`, `selection_type: exact`, `min_selections: N` | `exact` collapses `max` to `min`; a stale persisted `max_selections` is normalized by the drop but **not** by the raw API |
+| "pick up to N" | `max_only`, `max_selections: N` | `min_selections` is forced `nil` → guard the client comparison (P16) and allow a zero submit (P14) |
+| "pick at least N" | `min_only`, `min_selections: N` | `max_selections` forced `nil` — same nil guard |
+| "pick N–M" | `min_and_max` | progress denominator is max, completion is judged at min |
+| either-A-or-B branch | two groups + `bundle_config.mutually_exclusive_groups` | pairs of **sort_order**, max 2 per set, a group in at most one set — **Surface A only**, or the cart ignores it |
+| per-component price | group `dynamic_price` | the **only** mode where CV/QV flows from items |
+| one flat kit price | group `fixed_price`, or bundle-level flat for the whole bundle | credits **0/0 CV/QV** unless re-entered on the group/bundle country row — surface this, it is a commissions decision |
+| per-country price | `country_pricing[]` at the right layer | values are **strings**, ISO **UPPERCASE**, `enabled` strict `== true` |
+| pre-selected option | item `config.is_default: true` | **clamp to `max_selections`** and skip out-of-stock (P19) |
+| "max 2 of this" | item `config.max_quantity` | counters count **units**, not lines |
+| subscribe option / required | item `config.allow_subscription` / `force_subscription` (+ plan id) | a forced item needs ≥1 active plan on **its own** product; check the group level too — real fixtures force at item level with the group flag false |
+| hidden internal component | `included` group + `pricing_config.hidden: true` | legal only on static groups outside an exclusive pair |
+| legacy `ProductBundle` row | one `included` group; `display_externally: false` → a second `hidden` group | preserve `quantity`; these previously priced from the master variant |
+
+---
+
+## 2. Write shape (Surface A only)
+
+```jsonc
+PATCH /api/company/v1/products/{id}/update_bundle_product
+{ "product": {
+    "bundle": true,
+    "status": "published",
+    "bundle_config": {
+      "mutually_exclusive_groups": [ { "ids": [1, 2], "default": null } ],   // SORT ORDERS
+      "bundle_pricing_enabled": false
+    },
+    "product_bundle_groups_attributes": [
+      { "id": 0, "title": "", "group_type": "customizable", "sort_order": 0,
+        "selection_type": "exact", "min_selections": 1,
+        "pricing_config": { "pricing_type": "dynamic_price" },
+        "bundle_group_items_attributes": [
+          { "variant_id": 0, "quantity": 1, "sort_order": 0,
+            "config": { "is_default": true, "max_quantity": 2, "allow_subscription": false } }
+        ] } ] } }
+```
+
+Rules the shape encodes:
+
+- `is_default` goes **inside `config`** — there is no column, and on Surface B it 500s.
+- `sort_order` is meaningful because exclusivity references it. Set it explicitly.
+- Omit `id` to create, include it to update, add `"_destroy": true` to remove.
+- Unknown keys are silently dropped with a **200**. Read back and diff, always.
+- Create returns **200**, not 201.
+- On the **create** path, `bundle_pricing_enabled: true` + a `dynamic_price` group passes
+  validation (the bundle saves before its groups) and then fails on the next update. Never
+  emit that combination.
+
+---
+
+## 2b. Archetype G — converting a variant-encoded product into a bundle
+
+The product already exists, already ranks, already has a URL, and its variants already carry
+the full price. Three rules, in order of importance:
+
+**1. Adjust in place. Do not create a parallel product.** Shipping "Build Your Own Burrito"
+next to "Burrito" leaves two products for one menu item, splits the URL and any SEO, and
+guarantees the wrong one gets ordered. Convert `89585`, do not create `89898`.
+
+**2. The double-charge trap.** A variant priced $9.95 already includes its component. Bolt a
+priced component group onto that product and the shopper pays for the protein twice. So
+conversion is not additive — the variant layer must be dismantled as the group layer goes in:
+
+```
+BEFORE  product 89585  option "protein or veggie" → 7 variants @ $9.35–$11.35
+AFTER   product 89585  one master variant, options cleared
+                       + group "Protein or Veggie", customizable, exact 1
+```
+
+**3. Where the money goes is a decision, not a default.** Two legal shapes, and they price
+differently:
+
+| Shape | How | Consequence |
+|---|---|---|
+| **Component-priced** | one `customizable` group, `dynamic_price`, each item priced at the component's own price | total = sum of picks; CV/QV flows; the menu price is only reproduced if component prices happen to add up to it |
+| **Base + upcharge** | an `included` group at an explicit base price + a `customizable` group whose items carry only the *delta* ($0 chicken, +$1.40 steak) | reproduces the original variant prices exactly; the fixed base credits 0/0 CV/QV unless re-entered |
+
+Derive the deltas from the variants you are replacing — that is the only source that preserves
+the prices the merchant actually set. **Never infer the menu price from ingredient add-on
+prices**; a burrito is not the sum of its toppings' à-la-carte prices.
+
+Mechanics that bite:
+
+- Clearing `option_attrs` to `[]` at product and variant level drops the option display, but a
+  variant retains its stale `option_ids` — verify by re-reading, not by the 200.
+- Removing a variant is `variants_attributes: [{ id, _destroy: true }]`. Removing every
+  non-master variant is the goal; the master survives as the bundle parent.
+- A bundle parent's master variant is normally priced 0 and does **not** contribute to the
+  bundle total — the base must live in a group, not on the parent.
+- Deleting a variant that has order history may be refused. If so, deactivate it
+  (`variant_countries.active: false`) and say so rather than forcing it.
+- **A shared option object** (the same option `id` on several products) means converting one
+  product does not free the others. Convert the set together, or state which remain.
+
+Always report the before/after price for at least the cheapest and dearest original variant, so
+the merchant can see whether the conversion moved any price.
+
+---
+
+## 3. Judgement calls that must be surfaced, not decided silently
+
+Each of these changes money or commissions. Put them in the plan with the consequence spelled
+out, and let the human choose:
+
+1. **dynamic vs fixed group pricing** → CV/QV flows or doesn't.
+2. **an included group's price** → an unset price ships the contents free.
+3. **defaults** → which options are pre-selected, and the resulting starting price.
+4. **bundle-level flat pricing** → collapses every layer beneath it and forbids dynamic groups.
+5. **subscription forcing** → a forced item that loses its plan makes the bundle unbuyable.
+6. **a component with no catalog match** → create the product, or drop the option.
+
+---
+
+## 4. `bundle-plan.json`
+
+```jsonc
+{
+  "sourceArchetype": "B",
+  "bundles": [{
+    "productId": 0, "action": "create|update|adopt",
+    "groups": [{ "title": "", "type": "", "selectionType": "", "min": 1, "max": 1,
+                 "pricingType": "", "price": null, "sortOrder": 0,
+                 "items": [{ "variantId": 0, "quantity": 1, "maxQuantity": null,
+                             "isDefault": false, "allowSubscription": false }] }],
+    "exclusiveSets": [[0, 1]],
+    "assertions": [
+      { "kind": "price", "selection": [], "expected": "50.00" },
+      { "kind": "selection", "group": 0, "rule": "exact 1" },
+      { "kind": "cart", "expects": "included group absent from bundled_items" }
+    ],
+    "judgementCalls": [{ "id": "", "question": "", "chosen": "", "consequence": "" }]
+  }]
+}
+```
+
+`assertions[]` is the point of the file — gates G5 and G6 replay them against the real cart,
+so "preserved the original behaviour" becomes a machine check rather than a claim.
diff --git a/themes/dynamic-bundles/playbooks/03-theme-generation.md b/themes/dynamic-bundles/playbooks/03-theme-generation.md
new file mode 100644
index 0000000..e8fca0f
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/03-theme-generation.md
@@ -0,0 +1,95 @@
+# 03 — Theme generation
+
+Five artefacts. One job each. No bundle-specific anything in any of them.
+
+```
+sections/bundle_builder/index.liquid   presentation + the data blob + {% schema %}
+assets/bundle-builder.js               normalize | rules | render | cart
+assets/bundle-builder.css              tokens only, scoped, + the compat layer
+product/bundle/index.liquid            host template, self-gating, with a fallback
+theme/bundle-manifest.json             provenance, routing map, contract revision
+```
+
+Source lives in `templates/` in this skill. Generation = copy + adapt to the host theme.
+
+---
+
+## 1. Adapt to the host theme (from discovery §3)
+
+The shipped CSS is already lineage-agnostic — every colour is a layered `var()` fallback that
+resolves on `--clr-*`, on `--color-*`, or on neither. So adaptation is small and specific:
+
+| Observed | Do |
+|---|---|
+| Per-section container keyed to `section.id` (newest PDPs) | leave the section container-less; it inherits the host template's width. **Never add `.container`** — that is the guaranteed-visible misalignment. |
+| `.container`-based PDP | wrap `{% section %}` in the host template, not inside the section |
+| `button, .btn {}` hijack | already handled by `.bb button { all: unset }` |
+| `-webkit-appearance: none` on inputs | already handled — custom check markers, no native chrome |
+| `ul, li { list-style: none }` | already handled — the section styles its own lists |
+| Theme radius / type scale | set `card_radius` and, if the theme has a distinctive scale, adjust `.bb-card__title` / `.bb__heading` sizes only |
+| Brand accent | leave `accent_color` unset so it inherits `--clr-primary`; set it only if the brand guide names a specific bundle accent |
+
+Nothing else. Resist restyling into a bespoke design — the whole point is that it inherits.
+
+---
+
+## 2. Push and publish
+
+```
+fluid theme push          # NEVER --force (it pushes to the LIVE theme with delete=true)
+```
+
+If writing via the API instead: **updates need an explicit publish.** The renderer serves
+`theme_template.published`, so a `PUT` alone changes nothing on the storefront —
+`POST /api/application_theme_templates/<id>/publish`.
+
+Creating a new template is additive: `CreateAction` sets `status: :active` and publishes, and
+does **not** set `default: true`, so it cannot hijack the default product page.
+
+---
+
+## 3. Zero-hardcoding check (mechanical, and it fails the run)
+
+Grep every generated file for every live bundle id, product id, group id, variant id, and
+group title in the company's bundle set. **Any hit fails G3.** The one legitimate exception is
+`bundle-manifest.json`, which is provenance, not code.
+
+Also assert: `bundle_product` is **not** set on any `product/*` template.
+
+---
+
+## 4. What must be true after generation
+
+- The section renders **nothing** on a non-bundle product (`data-bb-root` absent).
+- The data blob is present and escaped — zero raw `<` inside the `<script>`.
+- Group shells and included rows exist in the **server-rendered** HTML (progressive
+  enhancement — no blank-until-JS, no layout shift).
+- `[data-bb-ready="true"]` appears after JS runs.
+- Zero console errors; no horizontal overflow at 390 px.
+
+---
+
+## 5. Extending it later
+
+| Want | Change | Don't touch |
+|---|---|---|
+| Different card layout | `<template data-bb-tpl="card">` + CSS | JS |
+| New rule type the platform adds | `selectionBounds()` + `rules()` | render, cart |
+| New drop field | `normalize()` only | everything else |
+| New cart field | `buildCartPayload()` only | everything else |
+| Different copy / language | `{% schema %}` settings | all code |
+
+`model.unknownFields` logs any group/item key the normalizer did not understand (dev mode
+only). That is how a future platform feature surfaces instead of silently doing nothing.
+
+---
+
+## 6. Parity mode (non-default)
+
+If byte-parity with the platform section is genuinely required, clone the global
+`product_bundle` into the theme instead and apply the 5-site exclusivity patch from
+`reference/02-hosting-and-routing.md` §3a (read `bundle_config.mutually_exclusive_groups` as a
+fallback). Accept the consequences: ~11 inherited client defects, 46 inline styles that
+outrank your CSS, 31 leaked utility class names, and a copy that will never receive upstream
+updates (`auto_upgradeable?` is hardcoded `false`). Record the source revision — the deployed
+global row is **not** the repo file, so fetch and diff before debugging.
diff --git a/themes/dynamic-bundles/playbooks/04-routing.md b/themes/dynamic-bundles/playbooks/04-routing.md
new file mode 100644
index 0000000..9733d18
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/04-routing.md
@@ -0,0 +1,46 @@
+# 04 — Routing
+
+There is **no auto-assignment**. This step is required, per product, and it is the single most
+common real-world fault.
+
+## Assign
+
+```
+PATCH /api/company/v1/products/{productId}
+{ "product": { "application_theme_template_id": <bundle template id> } }
+```
+
+A plain PATCH is sufficient and takes effect immediately (verified end to end). In the admin
+Bundle Builder this is the required **"Select template"** field.
+
+## Verify — on the PLAIN storefront URL
+
+```
+https://<company>.fluid.app/home/products/<slug>          # no ?preview=
+```
+
+Assert: our marker `data-bb-root` present; the previous implementation's markers
+(`data-bundle-section`, `data-dbp-*`) absent; HTTP 200, not a 302 to /404.
+
+Use `canonical_url` from the API response — never a URL composed from a slug you chose. The
+create/update endpoints ignore a `slug` you send and generate one from the title.
+
+## The trap that will bite later
+
+`application_theme_template_id` is **not a column**. It is a `template_resources` join scoped
+to the company's currently-active theme. So:
+
+- **Switching or cloning a theme silently un-routes every bundle.** Cloning copies templates,
+  not the join rows.
+- `?preview=true&theme_template_id=<id>` works because it overrides the active-theme lookup —
+  which is why preview is safe and proves nothing about live routing.
+
+`bundle-manifest.json` records `{ themeId, templateId, productIds[] }` precisely so
+re-routing after a theme change is one idempotent replay instead of an archaeology exercise.
+Say this to the user out loud when handing over.
+
+## Un-routing an old implementation
+
+Archetype B companies often have the hand-authored picker injected directly into
+`product/default`. Removing that injection is part of the job — otherwise every ordinary
+product keeps paying for picker markup. Do it as a separate, reviewable change.
diff --git a/themes/dynamic-bundles/playbooks/05-validation.md b/themes/dynamic-bundles/playbooks/05-validation.md
new file mode 100644
index 0000000..21d2635
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/05-validation.md
@@ -0,0 +1,77 @@
+# 05 — Validation gates G0–G7
+
+Every gate **reads state back**. None trusts the screen. A gate either auto-repairs
+(idempotent, bounded) or stops with a message naming the exact resource and field.
+
+> A bundle page that merely *looks* right is not evidence. A bundle on a bundle-unaware theme
+> renders as a normal product with a working add-to-cart and only dies at checkout; add-to-cart
+> failures resolve silently.
+
+---
+
+## G0 — Preflight
+Token scope · exactly one `status:"active"` theme · countries, currency symbol and decimal
+places · subscription plan inventory · SDK boot tag present on a live storefront page.
+
+## G1 — Discovery
+Every candidate classified with evidence · no product both "bundle" and unclassified ·
+enrollment bundles flagged unsupported and excluded · every source-page option matched,
+ambiguous, or missing — never silently dropped.
+
+## G2 — Config write-back
+Re-`GET` each product and diff field-by-field against the plan. Assert:
+- `products.bundle_config` is non-empty
+- every mutex tuple references an **existing `sort_order`**, ≤2 per set, each group in ≤1 set
+- `is_default` is present **inside `config`**
+- no customizable group has a nil surviving selection bound
+- every `included` group has an explicit price or an explicitly recorded $0 decision
+- no group carries `hidden: true` while customizable or inside an exclusive pair
+
+## G3 — Render
+Blob present, key count as expected (50 = page scope, 40 = drop) · zero raw `<` inside the
+blob script · post-JS `[data-group-id]`/`[data-bb-group]` count matches expectation
+**excluding `<template>`s** (the DOM is client-built; a server-side grep matches the templates
+and misleads you) · `[data-bb-ready="true"]` · **a non-bundle product on the default template
+is byte-untouched** · zero console errors · 390 px with no horizontal overflow.
+
+## G4 — Interaction
+Each `selection_type` gates correctly · defaults ≤ max and skip out-of-stock · at-max gives a
+real disabled affordance with a reason, or swaps · `max_only` can submit zero · a nil bound
+never enables a doomed CTA · subscribe controls appear only where allowed and are locked where
+forced · **a real scrolled mouse click** on the CTA *and on a child element of it* (synthetic
+`element.click()` can pass where a user click fails).
+
+## G5 — Cart
+Capture the request body:
+- every entry tagged with `product_bundle_group_id`
+- included items **absent** — exclusive-set members **present**
+- duplicates collapsed into `quantity`, zero-quantity entries omitted
+
+Then read the cart back:
+- exactly one line, `metadata.is_bundle === true`
+- every expected child present, **including the ones the server reconstitutes**
+- `items[].errors` and `skipped_items` inspected **even on HTTP 200**
+- a resolved-`undefined` promise surfaces our error UI
+- add the same bundle twice → the lines you expect (re-adding **sets** quantity)
+
+## G6 — Money
+Displayed total == cart total == checkout total, in **every pricing mode the company uses**.
+Read the recurring subtotal from `cart.recurring[0]` and confirm the PDP disclosed it. Never
+accept a silent `$0.00`. Confirm the CV/QV expectation matches the mode (fixed and flat credit
+0/0 unless re-entered). Reach the checkout page and read the totals — **do not place an order**.
+
+## G7 — Reusability (the platform proof)
+Synthesise a **second bundle with a different shape** — an extra group, nested exclusivity, a
+per-item max, a subscription-forced item — and confirm it renders and adds to cart with **zero
+code changes and no new template**. Then delete it (**Bundle first, then Product** — reverse
+order leaves an orphan whose DELETE 500s forever).
+
+Grep the generated theme for every live id and group title. Any hit fails the gate.
+
+---
+
+## Test-safety rules on a shared company
+Creating new templates and products is additive and safe — prefix `[QA]`. **Never** modify the
+default product template, an existing bundle template, or the global section row. Never
+`fluid theme push --force`. Carts are fine; do not place orders. **Never put markup in a
+product title** — titles are emitted into an inline `<script>` and that is live stored XSS.
diff --git a/themes/dynamic-bundles/playbooks/06-greenfield.md b/themes/dynamic-bundles/playbooks/06-greenfield.md
new file mode 100644
index 0000000..a8978fd
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/06-greenfield.md
@@ -0,0 +1,99 @@
+# 06 — Greenfield: a company with no bundles
+
+Zero bundles, zero infrastructure. The deliverable is **not** one bundle — it is the platform,
+proven by one real bundle.
+
+**Prerequisite.** Greenfield here means *no bundles*. It does **not** mean no store. This
+playbook assumes an existing active theme and a populated catalog — that is onboarding's
+output. If the catalog is empty or there is no theme, stop and say the onboarding workflow
+should run first.
+
+## Order of work
+
+1. **Generate the theme implementation first** (`03-theme-generation.md`). It is independent
+   of any bundle and is the reusable asset.
+2. **Create the host template** and record its id.
+3. **Build one proving fixture from the live catalog** — never a toy. Choose or construct a
+   bundle that exercises as many dimensions as the catalog honestly supports:
+
+   | Dimension | Why it must be in the fixture |
+   |---|---|
+   | an `included` group | proves server-side reconstitution and the explicit-price rule |
+   | an `exact` group | the most common rule |
+   | a `max_only` group | proves zero-submit (P14) and the nil-bound guard (P16) |
+   | a `dynamic_price` group | the only mode where CV/QV flows |
+   | a per-item `max_quantity` | proves unit counting, not line counting |
+   | a default selection | proves the clamp-to-max fix (P19) |
+   | an exclusive pair | proves the `bundle_config` read (P2) — the highest-value defect |
+
+4. **Route it, then run G3–G7.**
+5. **Prove reusability (G7)** with a second, differently-shaped bundle, then remove it.
+
+## Choosing the fixture for THIS company
+
+Pick the shape the company would plausibly sell, from its own catalog. In descending order of
+how often it is the right answer:
+
+**A. Fixed kit** — the default choice for most companies. Three to five existing products that
+belong together, one `included` group each (or one group holding all of them), bundle-level
+flat price below the sum. Exercises: reconstitution, the explicit-price rule, flat pricing.
+*Good for: home goods, gift sets, apparel sets, anything with a natural "buy these together".*
+
+**B. Pick-N** — "choose any 3". One `customizable` group, `exact 3`, `dynamic_price` so CV/QV
+flows. Exercises: selection gating, unit counting, per-item pricing.
+*Good for: coffee, pet food, supplements, beauty shades, beverages.*
+
+**C. Base + options** — an `included` core plus `exact 1` and `max_only` groups. Exercises
+nearly everything, and is the honest test if the company's real product needs configuration.
+*Good for: electronics kits, meal builders, supplement stacks, "build your routine".*
+
+Whichever you choose, stretch it to cover the dimension table above — add one per-item
+`max_quantity`, one default, and one exclusive pair even if the minimal version wouldn't need
+them. The point is the platform, not the bundle.
+
+If the catalog genuinely has no products that belong together, say so and ask rather than
+inventing a nonsense bundle.
+
+---
+
+## Worked example — food/QSR (the test company)
+
+Chipotle is greenfield (`GET /api/v2025-06/bundles` → `[]`) with an unusually good catalog for
+this: 47 build components already exist as individual products — 7 proteins, 2 rices, 2 beans,
+11 toppings, chips & dips, sides, high-protein cups. That makes it a shape-C fixture. **Read
+this as one instance of the recipe above, not as the recipe.**
+
+Map `chipotle.com/order/build/burrito` (Archetype F, `01-discovery.md` §6) onto:
+
+| Group | Type | Rule | Pricing | Notes |
+|---|---|---|---|---|
+| Tortilla / base | `included` | — | explicit `fixed_price` | the $0 decision must be deliberate |
+| Protein | customizable | `exact 1` | `dynamic_price` | prices differ per protein; `max_quantity: 2` for double |
+| Rice | customizable | `max_only 1` | `fixed_price "0.0"` | the "No Rice" card is a negative selection, **not** an item |
+| Beans | customizable | `max_only 1` | `fixed_price "0.0"` | same |
+| Toppings | customizable | `max_only N` | `fixed_price "0.0"` | many-select, included at no charge |
+| Extras (guac, queso) | customizable | `max_only N` | `dynamic_price` | real per-item deltas |
+
+Bowl vs burrito is the natural **exclusive pair** if both are modelled in one product;
+otherwise they are two bundles sharing the same groups' worth of items.
+
+Two catalog rules already established for this company and still binding: prices for build
+components come from the meal-builder HTML, not the in-store photo; and creating a product
+whose slug already exists silently yields a UUID-suffixed slug, so always read `slug` /
+`canonical_url` back from the response.
+
+The equivalents in other verticals, for orientation: an electronics "configure your laptop"
+page is the same shape (included chassis + `exact 1` RAM + `exact 1` storage + `max_only`
+accessories, with RAM tiers as an exclusive set); a supplement "build your stack" is the same
+shape with subscription forcing on the base; a beauty "build your routine" is the same shape
+with `dynamic_price` throughout. None of them need a code change.
+
+Create the fixture as **draft** while iterating; publish only after G6 passes.
+
+## Handing over
+
+Say plainly:
+- what was built, and that it renders every future bundle with no code change
+- how to add the next bundle (admin Bundle Builder → set the Theme Template field)
+- that a theme switch or clone **un-routes every bundle**, and the manifest is the replay list
+- which judgement calls were made on their behalf and what each one costs
diff --git a/themes/dynamic-bundles/playbooks/07-troubleshooting.md b/themes/dynamic-bundles/playbooks/07-troubleshooting.md
new file mode 100644
index 0000000..60641fd
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/07-troubleshooting.md
@@ -0,0 +1,71 @@
+# 07 — Troubleshooting
+
+Work top to bottom. Stop at the first failure. **Most "platform bugs" are not.**
+
+## 1. Is the product actually a published, routed bundle?
+
+`GET /api/company/v1/products/{id}` and check, in order:
+
+| Field | Must be | If not |
+|---|---|---|
+| `status` | `active` | drafts aren't published. Not a bug. |
+| `product_bundle_groups.length` | `> 0` | **not a bundle product**, whatever `/bundles` says. Not a bug. |
+| `application_theme_template_id` | not `null` | **unrouted** — the most common real fault |
+
+Worked example from the source campaign: three bundles showed "no bundle UI" and only **one**
+was a fault (unrouted). The others were a draft and a product with zero groups. Two of three
+would have been false bug reports.
+
+## 2. Are you reading the right bundle row?
+
+Match by `product_bundle_groups[].id`, **never slug**. Duplicate/orphan rows share a title and
+the later row often owns the uniquified slug.
+
+## 3. Is it an orphan?
+
+Storefront 302s to /404 ⇒ the Product was deleted and the Bundle row survived. `DELETE` on it
+then 500s forever. Always delete **Bundle first, then Product**.
+
+## 4. Which implementation is rendering?
+
+Compare all three paths (plain / canonical / picker). If it only misbehaves on one, that
+implementation owns the bug. To decide platform-vs-theme with certainty, render the section
+with no theme code around it in a throwaway host template.
+
+## 5. Is it a data precondition?
+
+| Symptom | Cause |
+|---|---|
+| "Out of stock" on a new bundle | the master variant has no active `variant_countries` row for the shopper's country |
+| Everything prices at $0.00 | a child has no priced country row. HTTP 200, `items[].errors: []` — **no signal at all** |
+| Subscribe toggle missing | the item's `allow_subscription` is false |
+| Renewal price is wild | P7, by design — the BGI variant's own country row, not the parent |
+
+## 6. API traps that fake a theme bug
+
+| Trap | Effect |
+|---|---|
+| `per_page=100` on `/api/company/v1/products` | returns **zero** products, no error. 50 works. |
+| `/api/v2025-06/bundles` | no pagination, omits `product_id` |
+| Ignored filters | return an unfiltered page |
+| `?country=CA` | ignored — use `?country_id=<numeric>` |
+| Unknown keys on a write | silently dropped, HTTP 200 |
+
+## 7. Symptom → cause, ours
+
+| Symptom | Look at |
+|---|---|
+| Section renders nothing | `product_bundle_groups.size > 0` gate — correct behaviour on a non-bundle |
+| Renders but no cards | `normalize()` dropped them — hidden groups, or every item filtered as unavailable. Turn on `debug` and read the warnings. |
+| CTA never enables | `rules().violations` — most often a `configError` (nil bound) or an unchosen exclusive branch |
+| CTA does nothing, no error | SDK never loaded. Our code shows a message; the platform's shows nothing (P17) |
+| Add succeeds, cart empty/wrong | read the captured `bundled_items` — included group sent by mistake, or a missing group id |
+| Total right on page, wrong in cart | a fixed-price group being summed, or bundle-level flat being ignored. `total()` mode must match the config. |
+| Duplicate cart lines | an untagged entry crept in — every entry needs `product_bundle_group_id` |
+
+## 8. Before filing anything
+
+`reference/13-defect-triage.md`. **8 of 21 reported defects were downgraded.** Do not file
+P7, P12, P4 (by design, named verbatim in their originating commits) or P11, P13, P16, P18
+(fixture artifacts the Bundle Builder cannot produce). Do file P2 (exclusivity) and P19
+(defaults over max) — those are reachable by a real merchant and cost real money.
diff --git a/themes/dynamic-bundles/playbooks/08-api-write-recipe.md b/themes/dynamic-bundles/playbooks/08-api-write-recipe.md
new file mode 100644
index 0000000..7e1e6d0
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/08-api-write-recipe.md
@@ -0,0 +1,270 @@
+# 08 — The verified write recipe
+
+Every rule here was confirmed live against Chipotle (company 980243433) on 2026-08-06 while
+converting six menu items to bundles, building four fixed catering kits, and reproducing a real
+add-to-cart failure. Each one exists because a request failed or a read-back was wrong. Nothing
+here is inferred.
+
+Read this **after** `02-translation.md` (shape decisions) and alongside `05-validation.md`.
+
+---
+
+## 1. Classify the shape before you write anything
+
+The most expensive mistake available is applying one pattern to products that merely *look*
+uniform. It happened three times in one session.
+
+Chipotle had 7 "menu item" products. They split three ways:
+
+| Products | Option | What the values are | Correct shape |
+|---|---|---|---|
+| Burrito, Bowl, Tacos, Salad, Quesadilla, Kid's | **1144** | components of *one* item (Chicken, Steak…) | **bundle** — component axis |
+| Chips & Sides 89593 | **1145** | 24 values that each already exist as their own product | **category** — a flattened collection |
+| Build-Your-Own 89584, High Protein 89587 | **1143** | distinct menu items at $3.50–$16.10 | **category** (89587) / **bundle** (89584) |
+
+So the test is never "do these share an option?" It is:
+
+> **Are the option values components of a single sellable thing, or are they separate sellable
+> things?** Components → bundle. Separate things → category/collection. Converting a category
+> into one bundle destroys a browsable listing and advertises one wrong price.
+
+Check the **option id** per product. Do not generalise from a sibling.
+
+### Fixed kit vs configurable — and the case where it is BOTH
+
+- **Fixed kit** (shape 1, the most common): the card names its full contents and has one price.
+  Model as a bundle with a single `included` group at `fixed_price`.
+- **Configurable**: the shopper chooses. `customizable` groups.
+- **Both**: a category page of fixed kits where each card *also* has a **CUSTOMIZE** link into a
+  builder. Chipotle's Family Meals is this. The correct model is **N fixed-kit products *plus* one
+  configurable bundle**, all in one collection — not one or the other. The kit and builder prices
+  legitimately differ (Chipotle: $52/$52/$63 kits vs $53/$53/$64 builder, a flat +$1 to
+  customize). **Do not "reconcile" them.**
+
+### Never trust imported prices as source of truth
+The importer had the catering proteins at $50/$50/$61; the live page said **$52/$52/$63**. The
+catalog was wrong before anyone touched it. Deriving deltas from existing variants is correct when
+*preserving* prices and wrong when *matching a source*. Read the source.
+
+---
+
+## 2. The endpoint, and the two calls
+
+```
+POST  /api/company/v1/products/create_bundle_product
+PATCH /api/company/v1/products/{id}/update_bundle_product
+```
+
+Body wrapped in `product`. Plain `PATCH /api/company/v1/products/{id}` **silently ignores**
+`product_bundle_groups_attributes` and still returns 200 — the classic false success.
+
+**`title` is required even on an update.** Omitting it → 422 `{"product":{"title":["is missing"]}}`.
+
+### Create = ONE call. Convert = TWO.
+
+Verified on three creates and six conversions:
+
+| | `bundle: true` + groups in one request |
+|---|---|
+| `POST create_bundle_product` | ✅ persists — `is_bundle: true`, `bundle_price` correct, Bundle row synced |
+| `PATCH update_bundle_product` | ❌ groups are created but `is_bundle` stays **false**, `bundle_config: {}`, **no Bundle row** |
+
+So a conversion needs a second, **groups-free** flag call:
+
+```jsonc
+// CALL 1 — structure (teardown + groups, see §3)
+// CALL 2 — flag only
+{ "product": { "id": 89585, "title": "Burrito", "bundle": true, "status": "active" } }
+```
+
+Between the two calls the product has groups but no bundle record, and if unrouted its PDP renders
+$0.00 with no picker. **Route immediately after (§5), per product — never batch routing to the end.**
+
+---
+
+## 3. Teardown and groups go in the SAME call
+
+A variant priced $9.95 already contains its component. Adding a priced component group while the
+priced variant axis still exists charges the shopper twice. Never leave that state, not even
+between two requests.
+
+```jsonc
+"option_attrs": [],
+"variants_attributes": [
+  { "id": <master>, "option_attrs": [],
+    "variant_countries_attributes": [ { "id": <country_row_id>, "price": "0.0" } ] },
+  { "id": <variant_2>, "_destroy": true }
+]
+```
+
+The surviving master **must** be repriced to 0 on every country row, addressed by
+`variant_countries_attributes[].id` — not by writing `price` on the variant. If a `_destroy` is
+refused for order history, deactivate instead and say so in the report.
+
+---
+
+## 4. Pricing — the part that silently costs money
+
+### 4a. `fixed_price: "0.00"` is IGNORED
+A group priced at zero does **not** zero its contents. Each item's `resolved_price` falls back to
+the component variant's own price, even when `config.price` is explicitly `"0.0"`.
+
+Live proof: Large Chips ($2.75) inside a `fixed_price: "0.00"` **included** group pushed
+`price_range` from **$53–$64 to $55.75–$66.75**. Removing that one item restored it.
+
+⇒ **A nonzero `fixed_price` pins a group total. `0.00` behaves as unset.** Only components whose
+underlying variant is genuinely $0 belong in a free group.
+
+### 4b. What each group type adds to the advertised floor
+
+| Group | Contribution to `price_range.min` |
+|---|---|
+| `included` | **sum of ALL its components'** resolved prices |
+| optional `fixed_price` (`max_only`) | **nothing** |
+| optional `dynamic_price` | **its cheapest item** — even when `min_selections: nil` |
+
+That last row is the trap. An optional paid "Add Guac or Queso" `dynamic_price` group moved the
+burrito's floor from **$9.35 → $12.30**, so every collection tile advertised "from $12.30" for a
+burrito buyable at $9.35. There is no theme-side fix; the value is computed server-side.
+
+⇒ **Never add an optional priced `dynamic_price` group to a product whose "from" price is
+customer-facing** unless the client accepts the inflated floor.
+
+### 4c. A fixed-price `included` group prices the bundle exactly
+`bundle_price` / `price_range` equal the group's `fixed_price`, ignoring components' own prices
+(items still echo their real `pc_price`). This is the correct primitive for a fixed kit, and it
+means the kit price cannot drift when a component's à-la-carte price changes.
+
+### 4d. Compare `price_range` before → after — but know what it measures
+It sums each item's `config.price`; it does **not** read the group's `fixed_price`. So it is a
+strong signal for **dynamic** groups (a moved minimum means you changed the shelf price — that
+check caught both 4a and 4b), and reads **`$0.00`** for an **all-fixed** bundle even though the
+cart charges correctly. Do not read a zero as a defect, and do not read it as verification.
+Full semantics: `09-pricing-patterns.md` §5.
+
+### 4e. Upgrade pricing needs a rebalanced base
+Flipping choice groups to `dynamic_price` alone **double-charges**: each item contributes its
+full variant price on top of an anchor group that already holds the headline. Use
+`base = headline − Σ(default component prices)` on the anchor, `dynamic_price` on every choice
+group, `is_default: true` inside `config` on each intended default. Assert `base >= 0`.
+See `09-pricing-patterns.md` — this is the single biggest gap the first version of this
+playbook had.
+
+---
+
+## 5. Route immediately, per product
+
+```
+PATCH /api/company/v1/products/{id}   { "product": { "application_theme_template_id": <id> } }
+```
+
+Confirm with `GET /api/application_theme_templates/{id}/available_themeables?per_page=200`. This is
+a `template_resources` join **scoped to the active theme** and is silently dropped on a theme
+switch or clone — re-run after either.
+
+Loop shape: `call 1 → call 2 → read back → route → verify`. Per product, not per phase.
+
+---
+
+## 6. Other mutation gotchas
+
+- **`images_attributes` APPENDS on PATCH.** It does not replace. Swapping an image without
+  `_destroy` for the old id leaves two rows both at position 1. Send `_destroy`.
+- **Collection membership REPLACES.** `PATCH /api/v202604/company/collections/{id}`
+  `{collection:{product_ids:[…]}}` overwrites the whole set, and the response does **not** echo
+  products. Read current members first (v1 GET returns `product_collections[]`), then re-GET to verify.
+- **A `draft` / `public: false` collection still renders publicly.** Verified by fetching a live
+  draft collection page. Do not "fix" draft status to make a collection reachable.
+- **Cross-group duplicate variants are legal.** Cheese sits in both the protein group ("Cheese
+  Only", $9.90) and the toppings group ($0) on Quesadilla. Different `product_bundle_group_id` ⇒
+  distinct cart keys. This is why rule 4 (always tag the group) is load-bearing.
+- **Sequencing: never archive or delete a product the storefront still links to.** Retire only
+  after the referring tile/nav has been repointed and that change is confirmed.
+- **Bundle items are append-only.** Omitting an existing item from
+  `bundle_group_items_attributes` keeps it; it does not remove it.
+- **(group, variant) is unique.** Re-sending a variant already in that group `422`s the
+  **whole request**, atomically — nothing is written. This makes it a cheap, non-mutating
+  membership oracle: send a candidate and read the error.
+- **Group-level `_destroy` does not work** — returns 404 even for a group that exists. Do not
+  plan a delete-and-recreate around it. Item-level and variant-level `_destroy` DO work.
+- **Item updates by `id` work**, including repointing `variant_id` in place. That is how you
+  fix a group pointing at the wrong variant — no rebuild needed.
+- **Reads cap at 51,200 bytes.** A large bundle cannot be read whole. Page it by PATCHing the
+  visible items' `sort_order` into a high block and re-reading.
+- **Cart creation needs a top-level `country_code`** as well as `fluid_shop`. Omitting it is
+  `422 country_code is missing`.
+
+---
+
+## 7. Read-back checklist, per product
+
+Do all of this from a **fresh `GET`**. A PATCH echo can show values the persisted read does
+not — an all-fixed kit echoed `$52.00` and reads `0.0` two days later with its stored config
+byte-identical (`09-pricing-patterns.md` §5a). The echo is not evidence.
+
+| Assert | Where |
+|---|---|
+| `is_bundle: true` | fresh GET after the flag call |
+| `price_range` matches intent (dynamic groups) — or is a knowing `$0.00` (all-fixed) | fresh GET |
+| `option_attrs: []`, no priced variants remain | product response |
+| Bundle row exists with the expected group count | `GET /api/v2025-06/bundles` (read-only) |
+| `application_theme_template_id` set | `available_themeables` |
+| **Add-to-cart actually succeeds** | §8 — the only test that matters |
+
+Report actual values, never the word "verified".
+
+---
+
+## 8. Prove add-to-cart through the checkout API
+
+**Config being valid says nothing about whether the storefront can sell it.** A six-group bundle
+read back perfectly from `/api/v2025-06/bundles` and still failed for shoppers.
+
+Reproduce with the real endpoint:
+
+```
+POST /api/checkout/v2026-04/carts
+{ "fluid_shop": "<sub>", "country_code": "US", "items": [ { "variant_id": <master>, "quantity": 1,
+  "bundled_items": [ { "variant_id": …, "quantity": 1, "product_bundle_group_id": … } ] } ] }
+```
+
+**The failure this catches** — sending a selection for an `included` group:
+
+```
+400  "product_bundle_group_id 1771 must reference a customizable group
+      or an exclusive included group"
+```
+
+This is SKILL.md rule 3 violated by the client. The cart attaches included components itself: the
+successful response listed Cheese / Romaine / Tortillas under group 1771 although they were **not**
+in the request.
+
+Two shapes verified 200 with correct totals:
+
+```jsonc
+// configurable — customizable groups ONLY (protein, rice, beans). Included group omitted.
+{ "variant_id": 343601, "quantity": 1, "bundled_items": [
+  {"variant_id":344039,"quantity":1,"product_bundle_group_id":1765},
+  {"variant_id":344022,"quantity":1,"product_bundle_group_id":1769},
+  {"variant_id":344023,"quantity":1,"product_bundle_group_id":1770} ] }   // → $53.00
+
+// pure fixed kit — NO bundled_items at all
+{ "variant_id": 344077, "quantity": 1 }                                   // → $52.00
+```
+
+Expect on the cart line: `is_bundle: true`, `bundle_group_base_price`, and a
+`bundle_selection_key` listing **only** the customizable picks
+(`1765:344039x1|1769:344022x1|1770:344023x1`; empty string for a pure fixed kit).
+
+**Corollary for the theme:** an all-`included` product has nothing to select, so any UI that gates
+add-to-cart on "all required groups chosen" leaves every fixed kit permanently unclickable — and
+the API side looks perfectly healthy. Test a fixed kit in the browser, not just in the API.
+
+---
+
+## 9. Cost of the write phase
+
+Each `update_bundle_product` response is a full ~50 KB product payload. Six conversions ≈ 600 KB
+across 12 calls plus read-backs. Budget for it: convert in small batches or run it as a workflow
+step with its own context, or the agent runs out of room mid-conversion and leaves products
+converted-but-unrouted — the exact broken state §5 warns about.
diff --git a/themes/dynamic-bundles/playbooks/09-pricing-patterns.md b/themes/dynamic-bundles/playbooks/09-pricing-patterns.md
new file mode 100644
index 0000000..2d51879
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/09-pricing-patterns.md
@@ -0,0 +1,150 @@
+# 09 — Pricing patterns: how to get upgrade pricing
+
+The skill documents fixed vs dynamic group pricing as a *data field*. That is not the same as
+knowing **how to price a bundle so that picking a dearer option costs more** — which is what
+most operators actually want. This playbook is that missing piece.
+
+Confirmed on two companies: Chipotle (2026-08-06) and a second conversion (2026-08-07,
+~13 live carts). Written for the general case — an **anchor** item plus one or more **choice
+groups**, whether that is a gift set, a starter kit, a build-your-own PC, a treatment
+regimen, or a meal.
+
+---
+
+## 1. Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **anchor group** | The `included` group holding the thing the bundle is named after. Usually carries the headline price. |
+| **choice group** | A `customizable` group the shopper selects from. |
+| **headline price** | What the bundle is advertised at in its default configuration. |
+| **base** | The `fixed_price` you put on the anchor group. |
+
+---
+
+## 2. The trap: flipping choice groups to `dynamic_price` double-charges
+
+Under `dynamic_price`, **each selected item contributes its own full variant price**. If the
+anchor group still holds the whole headline price, the total becomes
+
+```
+headline + Σ(full component prices)
+```
+
+and the customer pays twice for what the headline already covered. Observed: an $11.19
+bundle would have charged **$16.27**.
+
+This is the same failure mode as the earlier variant→bundle double-charge (playbook 08 §3),
+arriving from a different direction.
+
+---
+
+## 3. The pattern that works — **rebalanced base**
+
+```
+anchor_group.fixed_price = headline_price − Σ(default component price, one per choice group)
+every choice group       = dynamic_price
+is_default: true         = the intended default member of each choice group
+```
+
+The default configuration lands exactly on the headline price, and **every upgrade is a true
+delta**. Verified on live carts:
+
+| Selection | Total |
+|---|---|
+| default | $11.19 |
+| one tier up (+$0.60 component) | $11.79 |
+| cheaper option (−$1.80 component) | $9.39 |
+
+This is the only supported route to upgrade pricing. Document it as *the* pattern; treat
+anything else as a smell.
+
+### 3a. Guard — the base can go negative, and that is normal
+
+Value and discounted bundles are frequently priced **below** the sum of their standard
+components. That is the entire point of a bundle. A $5.00 value bundle minus a $2.79 side
+minus a $2.29 drink yields a base of **−$0.08**.
+
+Resolution order — do not improvise past step 2:
+
+1. **Honour the source's own declared default** for each group. Value bundles usually default
+   to a smaller or cheaper component, which fixes it: `5.00 − 1.19 − 2.29 = +1.52`.
+2. Still negative → **stop and escalate.** Do not clamp to zero. Do not pick a different
+   default to make the arithmetic work. A negative base means the intended pricing cannot be
+   expressed this way, and a human has to decide.
+
+**Compute the base per bundle and assert `base >= 0` before writing anything.**
+
+---
+
+## 4. Approaches that do NOT work
+
+| Attempt | What happens |
+|---|---|
+| **Per-item deltas** — base component `0.00`, upgrades `+delta` | A `0.00` item price is treated as **unset** and falls back to the variant's own price. Same double-charge. |
+| **`config.country_prices`** to force a genuine zero | HTTP **500** when sent as an object; **silently dropped** when sent as an array. Broken. Do not spend time here. |
+| **`fixed_price: "0.00"` on a group** to make it free | Ignored — behaves as unset, components fall back to their own variant prices (playbook 08 §4a). |
+
+The common root: **the platform cannot represent "this component is free *here*" via a zero.**
+Zero means unset everywhere it appears. Only a genuinely $0 variant is genuinely free.
+
+---
+
+## 5. What `price_range` actually reports — and how it lies
+
+`price_range` / `bundle_price_range` sums each item's **`config.price`**. It does *not* read
+the group's `fixed_price`.
+
+Consequences, both confirmed:
+
+- **All-fixed bundle** (anchor holds the price, every item priced `0.0`) → `price_range`
+  reads **`$0.00`** on a fresh GET, while the cart charges the headline price correctly.
+  This is *not* a reader defect: it is an accurate sum of items that are all zero. It is
+  also useless as a verification signal, and actively dangerous on any storefront surface
+  that renders it (see playbook 03 §price-surfaces).
+- **Dynamic choice groups** → the range is correct and arithmetically checkable
+  (e.g. `$8.09 – $14.69`), and *is* a good verification signal.
+
+> A suspicious constant in a read is more often a true report of a degenerate configuration
+> than a broken reader. Check the configuration before filing a defect.
+
+### 5a. A PATCH echo is not proof — this bit us
+
+On 2026-08-06 an all-fixed kit (Chipotle 89901, anchor group `fixed_price: "52.00"`) was
+recorded as `price_range: $52.00` **from the `update_bundle_product` response echo**. A fresh
+`GET` on 2026-08-08, with the stored group config byte-identical and `updated_at` unchanged,
+returns:
+
+```
+bundle_price: "0.0"    price_range: { min: "0.0", max: "0.0" }
+```
+
+The echo reflected the values just submitted; the persisted read computes them differently.
+The cart was and remains correct at **$52.00** — that was verified with a real
+`POST /api/checkout/v2026-04/carts`, not an echo.
+
+**Rule: never verify a write from the response to that write. Always re-`GET`.** Every
+"verified" price in a report must trace to a fresh read or a real cart.
+
+---
+
+## 6. Choosing the shape
+
+| Situation | Shape |
+|---|---|
+| One price, fixed contents, nothing to choose | Single `included` group, `fixed_price` = headline. Accept that `price_range` reads `$0.00`; render the headline from the anchor group, never from `price_range`. |
+| Shopper chooses, all options same price | Choice groups `fixed_price: "0.00"`… **no** — see §4. Use `dynamic_price` with every item priced equal, and rebalance the base. |
+| Shopper chooses, options differ in price (the common case) | **Rebalanced base**, §3. |
+| Optional paid add-ons on top | Allowed, but an optional `dynamic_price` group raises the advertised floor by its cheapest item (playbook 08 §4b). Get explicit sign-off. |
+
+---
+
+## 7. Pre-write checklist
+
+- [ ] Source's declared default identified for **every** choice group
+- [ ] `base = headline − Σ(defaults)` computed **per bundle**
+- [ ] `base >= 0` asserted; negatives escalated, never clamped
+- [ ] `is_default: true` set **inside `config`** on the intended default of each choice group
+- [ ] Every choice group is `dynamic_price`; the anchor group is `included` + `fixed_price: base`
+- [ ] Planned default total == headline, arithmetic shown
+- [ ] Post-write: fresh `GET` (not the echo) + at least one real cart at the default
diff --git a/themes/dynamic-bundles/playbooks/10-ui-and-price-surfaces.md b/themes/dynamic-bundles/playbooks/10-ui-and-price-surfaces.md
new file mode 100644
index 0000000..43af79a
--- /dev/null
+++ b/themes/dynamic-bundles/playbooks/10-ui-and-price-surfaces.md
@@ -0,0 +1,87 @@
+# 10 — Rendering the picker, and every price on the page
+
+Supersedes `03-theme-generation.md` on card rendering and price display. Everything here is
+a defect found in the generated section on a live storefront (2026-08-07) and fixed.
+
+---
+
+## 1. One card per **product**, not per item
+
+The generated section looped `group.bundle_group_items` and emitted one card per **item**.
+When a group holds several variants of the same product, the shopper sees the same title and
+the same parent image repeated — three "Fries" cards, two "Chili" cards.
+
+**Required shape:**
+
+1. Group items by **parent product id** (`item.product_id` — confirmed present on the drop).
+2. Render **one card per product**.
+3. Render a **variant sub-picker** only for products contributing more than one variant.
+4. Labels come from the variant's own option values. **Never a hardcoded list** ("Small /
+   Medium / Large") — that breaks the moment a vertical has capacities, colours or tiers.
+5. Selecting product + option must resolve to exactly **one** `variant_id`, and that is what
+   goes into `bundled_items`.
+
+This is the generic shape for every vertical: colour swatches, capacity pills, tier buttons,
+sizes. Same mechanic.
+
+## 2. Use the variant's image
+
+Cards used `item.product_image_url` (the parent) even where each variant carried its own.
+Use the **variant** image, fall back to the parent only when absent, and **swap it when the
+sub-picker changes**.
+
+## 3. The anchor is never visually subordinate to the options
+
+The anchor item — the thing the bundle is *named after* — rendered at **36×36** beside
+~144px option thumbnails. It read as a footnote to its own bundle.
+
+Fix: derive the anchor's size from **the same sizing token as the option grid** so the two
+cannot drift apart. Observed good ratio: anchor ≈ 1.25× an option thumbnail (180px against
+144px). Make this an explicit requirement, not a judgement call.
+
+---
+
+## 4. A bundle page is not one price
+
+On the live page the host template composed **four** sections, only one of which was wired to
+the selection engine; the PDP header rendered **no price at all**; and listing cards rendered
+a scalar where a bundle needs a range.
+
+### 4a. Inventory before wiring
+
+Before touching any of them, enumerate **every** surface that shows a price:
+
+- PDP header / hero
+- each composed section on the product template
+- sticky CTA / add-to-cart bars
+- listing, collection and search cards
+- cart page, cart drawer, mini-cart
+
+Classify each one:
+
+| Class | Treatment |
+|---|---|
+| must update live | subscribes to the engine's computed total |
+| should show a range / "from" | server-rendered, cannot update — render a range |
+| correct as-is | leave it |
+| should not render a price | remove it |
+
+### 4b. One computed source of truth
+
+Live surfaces **subscribe to the engine's total**. Never a second parallel calculation — that
+is exactly how two numbers on one page drift apart.
+
+- Surfaces outside the section need an explicit **data-attribute hook**, not a cross-section
+  CSS selector.
+- Server-rendered surfaces that cannot update show a **range or "from"** price.
+- **First paint must equal the default configuration**, or the page visibly flickers from a
+  wrong number to the right one.
+- Remember `price_range` reads **`$0.00`** for an all-fixed bundle (playbook 09 §5). Do not
+  wire a surface to it without checking the bundle's pricing shape first.
+
+### 4c. Acceptance
+
+> No price anywhere on the page may contradict another price on the same page at the same
+> moment — and page == cart == checkout.
+
+Check it at the default configuration, after one upgrade, and after one downgrade.
diff --git a/themes/dynamic-bundles/schemas/bundle-manifest.schema.json b/themes/dynamic-bundles/schemas/bundle-manifest.schema.json
new file mode 100644
index 0000000..41f4536
--- /dev/null
+++ b/themes/dynamic-bundles/schemas/bundle-manifest.schema.json
@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "bundle-manifest.json",
+  "description": "Provenance and routing state for a generated Dynamic Bundles implementation. Written at the end of a run; read by the next agent so re-syncing is deliberate rather than archaeological.",
+  "type": "object",
+  "required": ["generatedAt", "company", "theme", "artefacts", "routing", "contract"],
+  "properties": {
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "skillVersion": { "type": "string" },
+    "company": {
+      "type": "object",
+      "required": ["id", "slug"],
+      "properties": {
+        "id": { "type": "integer" },
+        "slug": { "type": "string" },
+        "storefront": { "type": "string" },
+        "countries": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "integer" },
+        "name": { "type": "string" },
+        "tokenLineage": { "enum": ["clr", "color", "none"] },
+        "containerMechanism": { "type": "string" },
+        "globalSectionDigest": {
+          "type": "string",
+          "description": "SHA of the platform product_bundle row at generation time. The deployed row is NOT the repo file; record it so a future diff is meaningful."
+        }
+      }
+    },
+    "artefacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "kind"],
+        "properties": {
+          "path": { "type": "string" },
+          "kind": { "enum": ["section", "asset", "template", "manifest"] },
+          "templateId": { "type": ["integer", "null"] },
+          "published": { "type": "boolean" }
+        }
+      }
+    },
+    "routing": {
+      "type": "object",
+      "description": "Replay list. application_theme_template_id is a template_resources join scoped to the ACTIVE theme, so a theme switch or clone silently un-routes every product here.",
+      "required": ["themeId", "templateId", "productIds"],
+      "properties": {
+        "themeId": { "type": "integer" },
+        "templateId": { "type": "integer" },
+        "productIds": { "type": "array", "items": { "type": "integer" } },
+        "verifiedAt": { "type": "string", "format": "date-time" },
+        "verifiedOn": { "type": "string", "description": "The plain storefront URL used for verification — never a preview URL." }
+      }
+    },
+    "contract": {
+      "type": "object",
+      "properties": {
+        "dropRevision": { "type": "string" },
+        "cartRevision": { "type": "string" },
+        "detector": { "type": "string", "default": "product.product_bundle_groups.size > 0" },
+        "exclusivitySource": { "type": "string", "default": "bundle_config.mutually_exclusive_groups" }
+      }
+    },
+    "defectsHandled": {
+      "type": "array",
+      "description": "Platform defects this implementation works around, so a future agent does not 'simplify' the guard away.",
+      "items": {
+        "type": "object",
+        "required": ["id", "how"],
+        "properties": {
+          "id": { "type": "string" },
+          "how": { "type": "string" }
+        }
+      }
+    },
+    "openIssues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": { "type": "string" },
+          "detail": { "type": "string" },
+          "needsHuman": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}
diff --git a/themes/dynamic-bundles/templates/assets/bundle-builder.css b/themes/dynamic-bundles/templates/assets/bundle-builder.css
new file mode 100644
index 0000000..1853ba4
--- /dev/null
+++ b/themes/dynamic-bundles/templates/assets/bundle-builder.css
@@ -0,0 +1,188 @@
+/* =============================================================================
+ * Fluid Dynamic Bundles — presentation layer
+ * -----------------------------------------------------------------------------
+ * Rules this file obeys, because the host theme is unknown:
+ *
+ *  1. ZERO hardcoded brand colour. Every colour is a layered var() fallback that
+ *     resolves on BOTH token lineages (--clr-* and --color-*) and degrades to a
+ *     neutral if neither exists.
+ *  2. Everything is scoped under .bb / [data-bb-root]. No generic utility class
+ *     names (.btn, .container, .text-sm, .flex …) are emitted or relied upon —
+ *     the platform section leaks 31 of them into whatever theme hosts it.
+ *  3. NO self-imposed .container. The newest Fluid PDPs bypass .container for a
+ *     per-section container, so a section that adds its own misaligns with the
+ *     rest of the page. Inherit the host template's width.
+ *  4. A scoped compat layer neutralises the three host resets that break bundle
+ *     UI on nearly every theme: `button,.btn{}` (black flex box, 6 of 8 themes),
+ *     `-webkit-appearance:none` on inputs (invisible native checkboxes, ALL
+ *     themes), and `ul,li{list-style:none}` (7 of 8).
+ *  5. Custom check markers, so nothing depends on native input chrome.
+ * ========================================================================== */
+
+.bb {
+  /* ---- token bridge: works on --clr-*, --color-*, or neither ---- */
+  --bb-fg:        var(--clr-black,  var(--color-black,  #111111));
+  --bb-bg:        var(--clr-white,  var(--color-white,  #ffffff));
+  --bb-muted:     var(--clr-muted,  var(--color-muted,  #6b7280));
+  --bb-line:      var(--clr-gray,   var(--color-gray,   #e5e7eb));
+  --bb-accent:    var(--clr-primary, var(--color-primary, #111111));
+  --bb-accent-fg: var(--clr-white,  var(--color-white,  #ffffff));
+  --bb-danger:    #b42318;
+  --bb-ok:        #067647;
+  --bb-radius:    12px;
+  --bb-gap:       16px;
+  --bb-pad-top:   48px;
+  --bb-pad-bottom:48px;
+
+  padding-top: var(--bb-pad-top);
+  padding-bottom: var(--bb-pad-bottom);
+  color: var(--bb-fg);
+  font-family: inherit;
+}
+
+/* ---------------------------------------------------------------- compat -- */
+.bb button {
+  /* undo the host theme's global black flex-box button, inside this section only */
+  all: unset;
+  box-sizing: border-box;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+}
+.bb button:disabled { cursor: not-allowed; }
+.bb ul, .bb ol { list-style: none; margin: 0; padding: 0; }
+.bb *, .bb *::before, .bb *::after { box-sizing: border-box; }
+.bb [hidden] { display: none !important; }
+.bb img { max-width: 100%; height: auto; display: block; }
+
+/* ---------------------------------------------------------------- layout -- */
+.bb__layout { display: grid; gap: 32px; align-items: start; }
+.bb__layout--sidebar { grid-template-columns: 1fr; }
+@media (min-width: 900px) {
+  .bb__layout--sidebar { grid-template-columns: minmax(0, 1fr) 340px; }
+  .bb__layout--sidebar .bb__aside { position: sticky; top: 24px; }
+}
+.bb__heading { margin: 0 0 8px; font-size: clamp(1.5rem, 1.2rem + 1.4vw, 2.25rem); line-height: 1.15; }
+.bb__intro   { margin: 0 0 28px; color: var(--bb-muted); max-width: 60ch; }
+
+/* ----------------------------------------------------------------- group -- */
+.bb-group { padding: 0 0 28px; margin: 0 0 28px; border-bottom: 1px solid var(--bb-line); }
+.bb-group:last-child { border-bottom: 0; margin-bottom: 0; }
+.bb-group.is-inactive { opacity: .45; }
+.bb-group.is-inactive .bb-grid,
+.bb-group.is-inactive .bb-included { pointer-events: none; }
+.bb-group.is-inactive .bb-group__choose { pointer-events: auto; }
+
+.bb-group__head { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
+.bb-group__title { margin: 0; font-size: 1.125rem; line-height: 1.25; flex: 1 1 auto; }
+.bb-group__desc { margin: 6px 0 0; color: var(--bb-muted); font-size: .9375rem; }
+.bb-group__rule { margin: 6px 0 0; color: var(--bb-muted); font-size: .875rem; }
+
+.bb-group__choose {
+  padding: 6px 14px; border: 1px solid var(--bb-line); border-radius: 999px;
+  font-size: .875rem; background: var(--bb-bg);
+}
+.bb-group__choose[aria-pressed="true"] {
+  background: var(--bb-accent); color: var(--bb-accent-fg); border-color: var(--bb-accent);
+}
+
+/* --------------------------------------------------------------- tracker -- */
+.bb-tracker { display: flex; align-items: center; gap: 10px; margin-top: 12px; }
+.bb-tracker__label { font-size: .8125rem; color: var(--bb-muted); font-variant-numeric: tabular-nums; }
+.bb-tracker__track { flex: 1 1 auto; height: 4px; border-radius: 999px; background: var(--bb-line); overflow: hidden; }
+.bb-tracker__fill  { display: block; height: 100%; width: 0; background: var(--bb-accent); transition: width .18s ease; }
+.bb-group.is-complete .bb-tracker__label { color: var(--bb-ok); font-weight: 600; }
+
+/* ------------------------------------------------------------------ grid -- */
+.bb-grid {
+  margin-top: 16px; display: grid; gap: var(--bb-gap);
+  grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+}
+
+/* ------------------------------------------------------------------ card -- */
+.bb-card {
+  display: flex; flex-direction: column; gap: 10px; padding: 12px;
+  border: 1px solid var(--bb-line); border-radius: var(--bb-radius);
+  background: var(--bb-bg); transition: border-color .15s ease, box-shadow .15s ease;
+}
+.bb-card.is-selected { border-color: var(--bb-accent); box-shadow: 0 0 0 1px var(--bb-accent) inset; }
+.bb-card.is-unavailable, .bb-card.is-blocked { opacity: .5; }
+.bb-card:focus-within { outline: 2px solid var(--bb-accent); outline-offset: 2px; }
+
+.bb-card__media { position: relative; aspect-ratio: 1 / 1; border-radius: calc(var(--bb-radius) - 4px); overflow: hidden; background: var(--bb-line); }
+.bb-card__img { width: 100%; height: 100%; object-fit: cover; }
+.bb-card__ph { position: absolute; inset: 0; background:
+  repeating-linear-gradient(45deg, transparent 0 8px, rgba(0,0,0,.03) 8px 16px); }
+
+.bb-card__body { display: flex; flex-direction: column; gap: 2px; flex: 1 1 auto; }
+.bb-card__title { font-weight: 600; font-size: .9375rem; line-height: 1.3; }
+.bb-card__variant { font-size: .8125rem; color: var(--bb-muted); }
+.bb-card__prices { display: flex; align-items: baseline; gap: 6px; margin-top: 2px; }
+.bb-card__price { font-size: .875rem; font-variant-numeric: tabular-nums; }
+.bb-card__compare { font-size: .8125rem; color: var(--bb-muted); }
+
+.bb-card__actions { display: flex; align-items: center; gap: 8px; }
+.bb-card__toggle { width: 100%; justify-content: center; }
+
+/* --------------------------------------------------------------- stepper -- */
+.bb-stepper { display: inline-flex; align-items: center; gap: 4px; border: 1px solid var(--bb-line); border-radius: 999px; padding: 2px; }
+.bb-stepper__btn { width: 28px; height: 28px; display: grid; place-items: center; border-radius: 999px; font-size: 1rem; line-height: 1; }
+.bb-stepper__btn:hover:not(:disabled) { background: var(--bb-line); }
+.bb-stepper__val { min-width: 20px; text-align: center; font-size: .875rem; font-variant-numeric: tabular-nums; }
+
+/* -------------------------------------------------------------- included -- */
+.bb-included { margin-top: 14px; display: flex; flex-direction: column; gap: 10px; }
+.bb-included__row { display: flex; align-items: center; gap: 12px; }
+.bb-included__img, .bb-included__ph { width: 48px; height: 48px; border-radius: 8px; object-fit: cover; flex: 0 0 48px; background: var(--bb-line); }
+.bb-included__title { font-size: .9375rem; }
+.bb-included__qty { margin-left: auto; color: var(--bb-muted); font-size: .875rem; }
+
+/* ------------------------------------------------------------ checkboxes -- */
+.bb-check { display: inline-flex; align-items: center; gap: 8px; font-size: .875rem; cursor: pointer; }
+.bb-check input { position: absolute; opacity: 0; width: 1px; height: 1px; }
+.bb-check__box {
+  width: 18px; height: 18px; flex: 0 0 18px; border: 1px solid var(--bb-line);
+  border-radius: 4px; background: var(--bb-bg); position: relative;
+}
+.bb-check input:checked + .bb-check__box { background: var(--bb-accent); border-color: var(--bb-accent); }
+.bb-check input:checked + .bb-check__box::after {
+  content: ""; position: absolute; left: 5px; top: 1px; width: 5px; height: 10px;
+  border: solid var(--bb-accent-fg); border-width: 0 2px 2px 0; transform: rotate(45deg);
+}
+.bb-check input:focus-visible + .bb-check__box { outline: 2px solid var(--bb-accent); outline-offset: 2px; }
+.bb-check input:disabled + .bb-check__box { opacity: .5; }
+
+/* --------------------------------------------------------------- summary -- */
+.bb-sum { border: 1px solid var(--bb-line); border-radius: var(--bb-radius); padding: 20px; background: var(--bb-bg); }
+.bb-sum__heading { margin: 0 0 14px; font-size: 1rem; }
+.bb-sum__items { display: flex; flex-direction: column; gap: 8px; margin-bottom: 14px; }
+.bb-sum__row { display: flex; align-items: baseline; gap: 8px; font-size: .875rem; }
+.bb-sum__title { flex: 1 1 auto; }
+.bb-sum__qty, .bb-sum__price { color: var(--bb-muted); font-variant-numeric: tabular-nums; }
+.bb-sum__badge { font-size: .6875rem; text-transform: uppercase; letter-spacing: .04em; color: var(--bb-accent); }
+.bb-sum__suball { margin: 10px 0; }
+.bb-sum__plan { width: 100%; margin-bottom: 12px; padding: 8px; border: 1px solid var(--bb-line); border-radius: 8px; background: var(--bb-bg); font: inherit; }
+.bb-sum__total { display: flex; justify-content: space-between; align-items: baseline; padding-top: 14px; border-top: 1px solid var(--bb-line); font-size: 1.0625rem; }
+.bb-sum__total strong { font-size: 1.25rem; font-variant-numeric: tabular-nums; }
+.bb-sum__recurring { margin: 6px 0 0; font-size: .8125rem; color: var(--bb-muted); }
+.bb-sum__cta { width: 100%; margin-top: 16px; justify-content: center; }
+.bb-sum__msg { margin: 10px 0 0; font-size: .8125rem; color: var(--bb-muted); text-align: center; }
+.bb-sum__err { margin: 10px 0 0; font-size: .8125rem; color: var(--bb-danger); text-align: center; }
+
+/* --------------------------------------------------------------- buttons -- */
+.bb-btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  padding: 12px 18px; border-radius: 999px; font-weight: 600; font-size: .9375rem;
+  border: 1px solid transparent; transition: opacity .15s ease, background-color .15s ease;
+}
+.bb-btn--primary { background: var(--bb-accent); color: var(--bb-accent-fg); }
+.bb-btn--ghost   { background: var(--bb-bg); color: var(--bb-fg); border-color: var(--bb-line); }
+.bb-card.is-selected .bb-btn--ghost { background: var(--bb-accent); color: var(--bb-accent-fg); border-color: var(--bb-accent); }
+.bb-btn:hover:not(:disabled) { opacity: .88; }
+.bb-btn:disabled { opacity: .45; }
+.bb-btn:focus-visible { outline: 2px solid var(--bb-accent); outline-offset: 2px; }
+.bb-btn.is-loading { opacity: .6; pointer-events: none; }
+
+@media (prefers-reduced-motion: reduce) {
+  .bb *, .bb *::before, .bb *::after { transition: none !important; animation: none !important; }
+}
diff --git a/themes/dynamic-bundles/templates/assets/bundle-builder.js b/themes/dynamic-bundles/templates/assets/bundle-builder.js
new file mode 100644
index 0000000..2a201ed
--- /dev/null
+++ b/themes/dynamic-bundles/templates/assets/bundle-builder.js
@@ -0,0 +1,1095 @@
+/* =============================================================================
+ * Fluid Dynamic Bundles — universal client engine
+ * -----------------------------------------------------------------------------
+ * Four isolated layers. Every platform data trap lives in exactly one of them.
+ *
+ *   normalize(raw, ctx)          drop JSON  -> typed, country-resolved BundleModel
+ *   rules(model, selection)      pure       -> per-group state + violations
+ *   render(model, state, refs)   DOM only   -> clones <template>s, sets text/attrs
+ *   cart(model, selection)       money      -> bundled_items, SDK call, read-back
+ *
+ * No company constants. No bundle/product/group ids. No markup strings outside
+ * render(). Restyling never touches logic; a drop-shape change lands only in
+ * normalize().
+ *
+ * Contract: reference/03-data-contract.md + reference/07-cart-contract.md
+ * ========================================================================== */
+(function (root) {
+  'use strict';
+
+  /* ---------------------------------------------------------------------- *
+   * 0. Primitives
+   * ---------------------------------------------------------------------- */
+
+  /** Coerce anything the platform emits into a finite number.
+   *  Handles: floats, decimal strings, BigDecimal engineering notation
+   *  ("0.4999e2"), null, "", and the literal integer 0. */
+  function num(v) {
+    if (v === null || v === undefined || v === '') return null;
+    if (typeof v === 'number') return isFinite(v) ? v : null;
+    var n = parseFloat(String(v));
+    return isFinite(n) ? n : null;
+  }
+
+  /** First strictly-positive number in the chain, else null. A zero price on
+   *  the platform means "unset", never "free" — that distinction is made by the
+   *  caller via *Configured flags, not here. */
+  function firstPositive() {
+    for (var i = 0; i < arguments.length; i++) {
+      var n = num(arguments[i]);
+      if (n !== null && n > 0) return n;
+    }
+    return null;
+  }
+
+  /** Strict boolean — the backend compares with `== true`, so "true" and 1 are
+   *  false everywhere. Mirror that exactly. */
+  function strictBool(v) {
+    return v === true;
+  }
+
+  function asArray(v) {
+    return Array.isArray(v) ? v : [];
+  }
+
+  function str(v) {
+    return v === null || v === undefined ? '' : String(v);
+  }
+
+  function upper(v) {
+    return str(v).toUpperCase();
+  }
+
+  /* ---------------------------------------------------------------------- *
+   * 1. normalize — every data trap in the platform lives here
+   * ---------------------------------------------------------------------- */
+
+  var KNOWN_GROUP_KEYS = [
+    'id', 'title', 'description', 'group_type', 'sort_order', 'selection_type',
+    'min_selections', 'max_selections', 'pricing_type', 'fixed_price', 'min_price',
+    'max_price', 'compare_at_price', 'group_cv', 'group_qv', 'track_quantity',
+    'country_pricing', 'pricing_config', 'allow_subscriptions', 'force_subscriptions',
+    'image_urls', 'images', 'bundle_group_items', 'created_at', 'updated_at'
+  ];
+
+  var KNOWN_ITEM_KEYS = [
+    'id', 'quantity', 'sort_order', 'price', 'cv', 'qv', 'is_default',
+    'display_quantity', 'max_quantity', 'allow_subscription', 'force_subscription',
+    'product_id', 'product_title', 'product_image_url', 'product_bundles',
+    'image_url', 'available_country_codes', 'country_prices',
+    'country_subscription_prices', 'subscription_plan_id', 'subscription_plans',
+    'in_stock', 'available_quantity', 'config', 'variant'
+  ];
+
+  function unknownKeys(obj, known) {
+    var out = [];
+    for (var k in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, k) && known.indexOf(k) === -1) out.push(k);
+    }
+    return out;
+  }
+
+  /** variant_countries row for this ISO, or null. */
+  function variantCountry(variant, iso) {
+    var rows = asArray(variant && variant.variant_countries);
+    for (var i = 0; i < rows.length; i++) {
+      if (upper(rows[i].country_iso) === iso) return rows[i];
+    }
+    return null;
+  }
+
+  /** country_pricing[] row for this ISO where enabled === true, or null. */
+  function countryPricingRow(list, iso) {
+    var rows = asArray(list);
+    for (var i = 0; i < rows.length; i++) {
+      if (upper(rows[i].country_code) === iso && strictBool(rows[i].enabled)) return rows[i];
+    }
+    return null;
+  }
+
+  /** item.country_prices is keyed by ISO; the value is either a decimal string
+   *  or an object { price, wholesale }. Both shapes occur. */
+  function itemCountryPrice(item, iso) {
+    var map = item && item.country_prices;
+    if (!map || typeof map !== 'object') return null;
+    var v = map[iso] !== undefined ? map[iso] : map[iso.toLowerCase()];
+    if (v === undefined || v === null) return null;
+    if (typeof v === 'object') return num(v.price);
+    return num(v);
+  }
+
+  /** Image chain. item.image_url and variant.image_url are blank essentially
+   *  always; some bundles have no image anywhere, so '' is a legal answer and
+   *  the placeholder path must work. */
+  function itemImage(item, fallback) {
+    var v = item.variant || {};
+    var imgs = asArray(v.images);
+    var first = imgs[0] || {};
+    return (
+      str(v.image_url) ||
+      str(first.preview_image && first.preview_image.src) ||
+      str(first.src) ||
+      str(item.image_url) ||
+      str(item.product_image_url) ||
+      str(fallback) ||
+      ''
+    );
+  }
+
+  /** Repair the selection bounds the platform's own normalize_selection_bounds
+   *  leaves nil, and flag the configurations that would 500 the cart (P16). */
+  function selectionBounds(group, warnings) {
+    var type = group.selection_type;
+    var rawMin = num(group.min_selections);
+    var rawMax = num(group.max_selections);
+    var min = null, max = null, configError = null;
+
+    if (group.group_type !== 'customizable') return { min: null, max: null, configError: null };
+
+    switch (type) {
+      case 'exact':
+        min = rawMin;
+        max = rawMin;
+        if (min === null) configError = 'exact group has no min_selections';
+        break;
+      case 'min_only':
+        min = rawMin;
+        max = null;
+        if (min === null) configError = 'min_only group has no min_selections';
+        break;
+      case 'max_only':
+        min = 0;
+        max = rawMax;
+        if (max === null) configError = 'max_only group has no max_selections';
+        break;
+      case 'min_and_max':
+        min = rawMin === null ? 0 : rawMin;
+        max = rawMax;
+        if (max === null) configError = 'min_and_max group has no max_selections';
+        break;
+      default:
+        configError = 'customizable group has no selection_type';
+    }
+    if (configError) warnings.push('Group "' + str(group.title) + '": ' + configError);
+    return { min: min, max: max, configError: configError };
+  }
+
+  /** mutually_exclusive_groups holds SORT ORDERS, not group ids, in two shapes,
+   *  and is null (not []) on older bundles. Read bundle_config first — the
+   *  top-level key exists only in the 40-key ProductDrop shape. */
+  function exclusiveSets(raw) {
+    var cfg = raw.bundle_config || {};
+    var src = cfg.mutually_exclusive_groups;
+    if (!src) src = raw.mutually_exclusive_groups;
+    var list = asArray(src);
+    var sets = [];
+    for (var i = 0; i < list.length; i++) {
+      var e = list[i];
+      if (typeof e === 'number') {
+        // legacy bare Array<Integer> — one flat set of sort_orders
+        if (!sets.length) sets.push({ sortOrders: [], defaultSortOrder: null });
+        sets[0].sortOrders.push(e);
+      } else if (e && Array.isArray(e.ids)) {
+        sets.push({
+          sortOrders: e.ids.map(function (n) { return num(n); }).filter(function (n) { return n !== null; }),
+          defaultSortOrder: e['default'] === null || e['default'] === undefined ? null : num(e['default'])
+        });
+      }
+    }
+    return sets.filter(function (s) { return s.sortOrders.length > 1; });
+  }
+
+  function normalize(raw, ctx) {
+    ctx = ctx || {};
+    var iso = upper(ctx.countryIso || 'US');
+    var warnings = [];
+    var unknown = [];
+    raw = raw || {};
+
+    var bundleCfg = raw.bundle_config || {};
+    var pricingCfg = bundleCfg.bundle_pricing_config || {};
+    var bundlePricingEnabled = strictBool(bundleCfg.bundle_pricing_enabled);
+    var bundleRow = countryPricingRow(pricingCfg.country_pricing, iso);
+
+    var groups = asArray(raw.product_bundle_groups)
+      // Hidden groups are filtered in the drop shape but NOT in page scope.
+      .filter(function (g) {
+        return !strictBool(g.pricing_config && g.pricing_config.hidden);
+      })
+      .map(function (g) {
+        unknown = unknown.concat(unknownKeys(g, KNOWN_GROUP_KEYS));
+        var gpc = g.pricing_config || {};
+        var gRow = countryPricingRow(g.country_pricing || gpc.country_pricing, iso);
+        var bounds = selectionBounds(g, warnings);
+
+        // fixed_price reads "0.0" when unset — key presence is the only way to
+        // tell an unset price from a real zero.
+        var fixedConfigured = Object.prototype.hasOwnProperty.call(gpc, 'fixed_price') &&
+          gpc.fixed_price !== null && gpc.fixed_price !== '';
+        var fixedPrice = gRow ? num(gRow.price) : (fixedConfigured ? num(gpc.fixed_price) : null);
+
+        var items = asArray(g.bundle_group_items).map(function (it) {
+          unknown = unknown.concat(unknownKeys(it, KNOWN_ITEM_KEYS));
+          var v = it.variant || {};
+          var vc = variantCountry(v, iso);
+          var codes = asArray(it.available_country_codes).map(upper);
+
+          var price = firstPositive(
+            itemCountryPrice(it, iso),
+            it.price,
+            vc && vc.price
+          );
+          var subPrice = firstPositive(
+            it.country_subscription_prices && it.country_subscription_prices[iso],
+            vc && vc.subscription_price
+          );
+          var comparePrice = num(vc && vc.compare_price);
+
+          return {
+            id: num(it.id),
+            variantId: num(v.id),
+            sourceProductId: num(it.product_id),
+            title: str(it.product_title) || str(v.display_name) || str(v.title),
+            variantTitle: v.is_master ? '' : str(v.title),
+            image: itemImage(it, ctx.fallbackImage),
+            quantity: num(it.quantity) || 1,
+            displayQuantity: num(it.display_quantity) || num(it.quantity) || 1,
+            maxQuantity: num(it.max_quantity),
+            isDefault: strictBool(it.is_default),
+            allowSubscription: strictBool(it.allow_subscription),
+            forceSubscription: strictBool(it.force_subscription),
+            subscriptionPlanId: num(it.subscription_plan_id),
+            subscriptionPlans: asArray(it.subscription_plans),
+            price: price,
+            priced: price !== null,
+            comparePrice: comparePrice !== null && price !== null && comparePrice > price ? comparePrice : null,
+            subscriptionPrice: subPrice,
+            // CV/QV are Integers here and strings in both APIs. Only display
+            // them for dynamic_price groups (see model.cvFlows).
+            cv: num(vc && vc.cv) || 0,
+            qv: num(vc && vc.qv) || 0,
+            inStock: it.in_stock !== false,
+            availableQuantity: num(it.available_quantity),
+            // Two independent gates: the BGI country list, and whether the
+            // variant actually has a priced row for this country (P6).
+            availableInCountry: (codes.length === 0 || codes.indexOf(iso) !== -1) && !!vc
+          };
+        });
+
+        var pricingType = str(g.pricing_type) || 'fixed_price';
+        return {
+          id: num(g.id),
+          sortOrder: num(g.sort_order) || 0,
+          type: g.group_type === 'included' ? 'included' : 'customizable',
+          title: str(g.title),
+          description: str(g.description),
+          selectionType: str(g.selection_type) || null,
+          min: bounds.min,
+          max: bounds.max,
+          configError: bounds.configError,
+          pricingType: pricingType,
+          fixedPrice: fixedPrice,
+          fixedPriceConfigured: fixedConfigured || !!gRow,
+          allowSubscriptions: strictBool(g.allow_subscriptions),
+          forceSubscriptions: strictBool(g.force_subscriptions),
+          items: items
+        };
+      })
+      .sort(function (a, b) { return a.sortOrder - b.sortOrder; });
+
+    // An included group with no explicit price displays as its item sum and
+    // charges $0.00 (finding C). Warn loudly — it is real money.
+    groups.forEach(function (g) {
+      if (g.type === 'included' && !g.fixedPriceConfigured && !bundlePricingEnabled) {
+        warnings.push('Group "' + g.title + '" is included with no configured price — it will charge $0.00.');
+      }
+      g.items.forEach(function (it) {
+        if (!it.availableInCountry) {
+          warnings.push('"' + it.title + '" has no priced row for ' + iso + ' — it would zero the bundle total.');
+        }
+      });
+    });
+
+    var sets = exclusiveSets(raw).map(function (s) {
+      return {
+        sortOrders: s.sortOrders,
+        defaultSortOrder: s.defaultSortOrder,
+        groupIds: s.sortOrders.map(function (so) {
+          var g = groups.filter(function (gg) { return gg.sortOrder === so; })[0];
+          return g ? g.id : null;
+        }).filter(function (x) { return x !== null; })
+      };
+    }).filter(function (s) { return s.groupIds.length > 1; });
+
+    return {
+      productId: num(raw.id),
+      title: str(raw.title),
+      parentVariantId: num(
+        (raw.selected_or_first_available_variant && raw.selected_or_first_available_variant.id) ||
+        (asArray(raw.variants)[0] || {}).id
+      ),
+      countryIso: iso,
+      bundlePricingEnabled: bundlePricingEnabled,
+      bundleFlatPrice: bundleRow ? num(bundleRow.price) : null,
+      bundleSubscriptionPrice: bundleRow ? num(bundleRow.subscription_price) : null,
+      subscriptionPlans: asArray(raw.subscription_plans),
+      // CV/QV only flow from dynamic_price groups. Anything else credits 0/0
+      // unless re-entered on the group/bundle country row.
+      cvFlows: groups.some(function (g) { return g.pricingType === 'dynamic_price'; }),
+      groups: groups,
+      exclusiveSets: sets,
+      warnings: warnings,
+      unknownFields: unknown.filter(function (v, i, a) { return a.indexOf(v) === i; })
+    };
+  }
+
+  /* ---------------------------------------------------------------------- *
+   * 2. rules — mirrors CartBundleValidator, client-side, before the request
+   * ---------------------------------------------------------------------- */
+
+  function key(groupId, variantId) { return groupId + ':' + variantId; }
+
+  /** selection: { "<groupId>:<variantId>": { qty, subscribe, planId } }
+   *  branches:  { "<setIndex>": <groupId> }  — chosen exclusive branch */
+  function rules(model, selection, branches) {
+    selection = selection || {};
+    branches = branches || {};
+    var perGroup = {};
+    var violations = [];
+
+    var inactive = {};
+    model.exclusiveSets.forEach(function (set, i) {
+      var chosen = branches[i];
+      if (chosen === undefined || chosen === null) {
+        violations.push({ type: 'exclusive_unchosen', setIndex: i, message: 'Choose one option to continue' });
+        set.groupIds.forEach(function (gid) { inactive[gid] = true; });
+      } else {
+        set.groupIds.forEach(function (gid) { if (gid !== chosen) inactive[gid] = true; });
+      }
+    });
+
+    model.groups.forEach(function (g) {
+      // The server counts UNITS (sum of quantity), not entries, and drops
+      // quantity-0 entries before counting.
+      var count = 0, lines = 0;
+      g.items.forEach(function (it) {
+        var e = selection[key(g.id, it.variantId)];
+        if (e && e.qty > 0) { count += e.qty; lines += 1; }
+      });
+
+      var isInactive = !!inactive[g.id];
+      var state = {
+        groupId: g.id,
+        type: g.type,
+        inactive: isInactive,
+        count: count,
+        lines: lines,
+        min: g.min,
+        max: g.max,
+        atMax: g.max !== null && count >= g.max,
+        remaining: g.max === null ? null : Math.max(0, g.max - count),
+        satisfied: true,
+        blocked: false,
+        reason: ''
+      };
+
+      if (g.type === 'included' || isInactive) {
+        perGroup[g.id] = state;
+        return;
+      }
+
+      if (g.configError) {
+        state.satisfied = false;
+        state.blocked = true;
+        state.reason = 'This option group is misconfigured and cannot be ordered.';
+        violations.push({ type: 'config_error', groupId: g.id, message: state.reason });
+        perGroup[g.id] = state;
+        return;
+      }
+
+      if (g.min !== null && count < g.min) {
+        state.satisfied = false;
+        state.reason = g.selectionType === 'exact'
+          ? 'Choose ' + g.min
+          : 'Choose at least ' + g.min;
+        violations.push({ type: 'under_min', groupId: g.id, message: '"' + g.title + '" ' + state.reason.toLowerCase() });
+      } else if (g.max !== null && count > g.max) {
+        state.satisfied = false;
+        state.reason = 'Remove ' + (count - g.max) + ' to continue';
+        violations.push({ type: 'over_max', groupId: g.id, message: '"' + g.title + '" allows at most ' + g.max });
+      }
+
+      // Per-item cap and subscription legality — both are hard 422s server-side.
+      g.items.forEach(function (it) {
+        var e = selection[key(g.id, it.variantId)];
+        if (!e || e.qty <= 0) return;
+        if (it.maxQuantity !== null && e.qty > it.maxQuantity) {
+          violations.push({ type: 'over_item_max', groupId: g.id, variantId: it.variantId,
+            message: '"' + it.title + '" is limited to ' + it.maxQuantity });
+        }
+        if (e.subscribe && !it.allowSubscription && !it.forceSubscription) {
+          violations.push({ type: 'sub_not_allowed', groupId: g.id, variantId: it.variantId,
+            message: '"' + it.title + '" cannot be subscribed' });
+        }
+        if (it.forceSubscription && !e.subscribe) {
+          violations.push({ type: 'sub_required', groupId: g.id, variantId: it.variantId,
+            message: '"' + it.title + '" requires a subscription' });
+        }
+        if (!it.availableInCountry) {
+          violations.push({ type: 'country_unavailable', groupId: g.id, variantId: it.variantId,
+            message: '"' + it.title + '" is not available in your region' });
+        }
+      });
+
+      perGroup[g.id] = state;
+    });
+
+    return {
+      perGroup: perGroup,
+      violations: violations,
+      complete: violations.length === 0
+    };
+  }
+
+  /* ---------------------------------------------------------------------- *
+   * 3. pricing — display total, mirroring the server's charge path
+   * ---------------------------------------------------------------------- */
+
+  function total(model, selection, branches, subscribeAll) {
+    var inactive = {};
+    model.exclusiveSets.forEach(function (set, i) {
+      var chosen = (branches || {})[i];
+      set.groupIds.forEach(function (gid) { if (gid !== chosen) inactive[gid] = true; });
+    });
+
+    // Bundle-level flat pricing collapses every layer beneath it.
+    if (model.bundlePricingEnabled && model.bundleFlatPrice !== null) {
+      var flat = subscribeAll && model.bundleSubscriptionPrice !== null
+        ? model.bundleSubscriptionPrice
+        : model.bundleFlatPrice;
+      return { amount: flat, recurring: model.bundleSubscriptionPrice, mode: 'bundle_flat', cv: 0, qv: 0 };
+    }
+
+    var amount = 0, recurring = 0, cv = 0, qv = 0, anyRecurring = false;
+
+    model.groups.forEach(function (g) {
+      if (inactive[g.id]) return;
+
+      if (g.pricingType === 'dynamic_price') {
+        g.items.forEach(function (it) {
+          var e = (selection || {})[key(g.id, it.variantId)];
+          var qty = g.type === 'included' ? it.quantity : (e && e.qty > 0 ? e.qty : 0);
+          if (!qty) return;
+          amount += (it.price || 0) * qty;
+          cv += it.cv * qty;
+          qv += it.qv * qty;
+          if ((e && e.subscribe) || it.forceSubscription || subscribeAll) {
+            anyRecurring = true;
+            recurring += (it.subscriptionPrice !== null ? it.subscriptionPrice : (it.price || 0)) * qty;
+          }
+        });
+      } else {
+        // fixed_price: picks and quantities never move the charge.
+        if (g.fixedPrice !== null) amount += g.fixedPrice;
+        g.items.forEach(function (it) {
+          var e = (selection || {})[key(g.id, it.variantId)];
+          var subscribed = (e && e.subscribe) || it.forceSubscription || subscribeAll;
+          if (subscribed && (g.type === 'included' || (e && e.qty > 0))) {
+            anyRecurring = true;
+            // P7: renewal comes from the child variant's own country row, not
+            // the group/bundle price. We cannot fix it — we disclose it.
+            recurring += (it.subscriptionPrice || 0) * (g.type === 'included' ? it.quantity : e.qty);
+          }
+        });
+      }
+    });
+
+    return {
+      amount: amount,
+      recurring: anyRecurring ? recurring : null,
+      mode: 'sum',
+      // CV/QV only flow from dynamic groups; never promise volume otherwise.
+      cv: model.cvFlows ? cv : 0,
+      qv: model.cvFlows ? qv : 0
+    };
+  }
+
+  /* ---------------------------------------------------------------------- *
+   * 4. cart — the money path
+   * ---------------------------------------------------------------------- */
+
+  /** Build bundled_items exactly as the server expects. */
+  function buildCartPayload(model, selection, branches, subscribeAll, bundlePlanId) {
+    var inExclusive = {};
+    model.exclusiveSets.forEach(function (set) {
+      set.groupIds.forEach(function (gid) { inExclusive[gid] = true; });
+    });
+    var inactive = {};
+    model.exclusiveSets.forEach(function (set, i) {
+      var chosen = (branches || {})[i];
+      set.groupIds.forEach(function (gid) { if (gid !== chosen) inactive[gid] = true; });
+    });
+
+    var byKey = {};
+    var order = [];
+
+    function push(groupId, item, qty, subscribe, planId) {
+      if (!qty || qty <= 0) return;                 // qty 0 is a delete instruction
+      var k = key(groupId, item.variantId);
+      if (byKey[k]) {                                // collapse duplicates into quantity
+        byKey[k].quantity += qty;
+        return;
+      }
+      var entry = {
+        variant_id: item.variantId,
+        quantity: qty,
+        product_bundle_group_id: groupId            // ALWAYS. Never optional in practice.
+      };
+      if (subscribe) {
+        entry.subscription = true;
+        var pid = planId || item.subscriptionPlanId;
+        if (pid) entry.subscription_plan_id = pid;
+      }
+      byKey[k] = entry;
+      order.push(k);
+    }
+
+    model.groups.forEach(function (g) {
+      if (inactive[g.id]) return;
+
+      if (g.type === 'included') {
+        // Included items are reconstituted server-side and must NOT be sent —
+        // EXCEPT inside an exclusive set, where the server cannot know the branch.
+        if (!inExclusive[g.id]) return;
+        g.items.forEach(function (it) {
+          push(g.id, it, it.quantity, it.forceSubscription || (subscribeAll && it.allowSubscription), null);
+        });
+        return;
+      }
+
+      g.items.forEach(function (it) {
+        var e = (selection || {})[key(g.id, it.variantId)];
+        if (!e || e.qty <= 0) return;
+        var subscribe = it.forceSubscription || (!!e.subscribe && it.allowSubscription) ||
+          (subscribeAll && it.allowSubscription);
+        push(g.id, it, e.qty, subscribe, e.planId);
+      });
+    });
+
+    var payload = {
+      quantity: 1,
+      bundled_items: order.map(function (k) { return byKey[k]; })
+    };
+    // A bundle-wide subscription is distinct from per-item and suppresses the
+    // per-item forced-subscription check server-side.
+    if (subscribeAll) {
+      payload.subscribe = true;
+      if (bundlePlanId) payload.subscription_plan_id = bundlePlanId;
+    }
+    return payload;
+  }
+
+  /** The SDK's methods attach asynchronously, so `typeof SDK === "object"` is
+   *  not sufficient. Gate on the function itself (P17: no SDK = dead button,
+   *  perfect-looking page, no console error). */
+  function sdk() {
+    var s = root.FairShareSDK || root.FluidCommerceSDK;
+    return s && typeof s.addCartItems === 'function' ? s : null;
+  }
+
+  /** The SDK replaces the server's message with a generic string before we can
+   *  see it. Capture the real body ourselves. Narrow: cart endpoints only. */
+  var lastServerError = null;
+  function installErrorCapture() {
+    if (!root.fetch || root.__fluidBundleErrorCapture) return;
+    root.__fluidBundleErrorCapture = true;
+    var orig = root.fetch;
+    root.fetch = function (input, init) {
+      var url = typeof input === 'string' ? input : (input && input.url) || '';
+      return orig.apply(this, arguments).then(function (res) {
+        if (!res.ok && url.indexOf('/commerce/carts') !== -1) {
+          res.clone().json().then(function (b) {
+            lastServerError = (b && (b.error_message || (b.error && b.error.message))) || null;
+          }).catch(function () {});
+        }
+        return res;
+      });
+    };
+  }
+
+  /** Add to cart and PROVE it. Resolves { ok, cart, line, error, skipped }. */
+  function addToCart(model, payload) {
+    var s = sdk();
+    if (!s) {
+      return Promise.resolve({ ok: false, error: 'Cart is still loading. Please try again in a moment.' });
+    }
+    lastServerError = null;
+    var skipped = [];
+    function onSkip(e) {
+      var d = (e && e.detail) || {};
+      if (Array.isArray(d.skipped_items)) skipped = skipped.concat(d.skipped_items);
+    }
+    root.addEventListener('ADD_TO_CART', onSkip);
+    root.addEventListener('CREATE_CART', onSkip);
+
+    return s.addCartItems(model.parentVariantId, payload)
+      .then(function (cart) {
+        root.removeEventListener('ADD_TO_CART', onSkip);
+        root.removeEventListener('CREATE_CART', onSkip);
+
+        // The promise NEVER rejects. undefined IS the failure signal.
+        if (!cart) {
+          return { ok: false, error: lastServerError || 'We could not add that bundle. Please review your selections.' };
+        }
+
+        var line = null;
+        asArray(cart.items).forEach(function (i) {
+          if (i && i.metadata && i.metadata.is_bundle && num(i.variant_id) === model.parentVariantId) line = i;
+        });
+
+        // HTTP 200 is not success: inspect per-line errors even on a resolved cart.
+        if (line && asArray(line.errors).length) {
+          return { ok: false, cart: cart, line: line, skipped: skipped,
+            error: 'That bundle cannot be shipped to your region.' };
+        }
+        // A $0.00 bundle that should not be free means a child has no priced
+        // country row (P6). The platform gives no other signal.
+        if (line && num(line.total) === 0 && !model.expectedFree) {
+          return { ok: false, cart: cart, line: line, skipped: skipped,
+            error: 'Something went wrong pricing that bundle. Please try again.' };
+        }
+        if (skipped.length) {
+          return { ok: false, cart: cart, line: line, skipped: skipped,
+            error: 'Some items in that bundle are out of stock.' };
+        }
+        return { ok: true, cart: cart, line: line, skipped: skipped };
+      });
+  }
+
+  /* ---------------------------------------------------------------------- *
+   * 5. render — DOM only. Knows nothing about pricing or rules.
+   * ---------------------------------------------------------------------- */
+
+  function money(ctx, n) {
+    if (n === null || n === undefined) return '';
+    if (ctx.currencyCode && root.Intl && Intl.NumberFormat) {
+      try {
+        return new Intl.NumberFormat(ctx.locale || undefined, {
+          style: 'currency', currency: ctx.currencyCode,
+          minimumFractionDigits: ctx.decimalPlaces, maximumFractionDigits: ctx.decimalPlaces
+        }).format(n);
+      } catch (e) { /* fall through */ }
+    }
+    return ctx.currencySymbol + n.toFixed(ctx.decimalPlaces);
+  }
+
+  function tpl(rootEl, name) {
+    var t = rootEl.querySelector('[data-bb-tpl="' + name + '"]');
+    return t ? t.content.firstElementChild.cloneNode(true) : null;
+  }
+
+  function q(el, sel) { return el.querySelector(sel); }
+  function qa(el, sel) { return Array.prototype.slice.call(el.querySelectorAll(sel)); }
+  function setText(el, sel, text) { var n = q(el, sel); if (n) n.textContent = text; }
+  function show(el, on) { if (el) el.hidden = !on; }
+
+  /* ---------------------------------------------------------------------- *
+   * 6. mount — wiring
+   * ---------------------------------------------------------------------- */
+
+  function mount(rootEl) {
+    var cfgEl = q(rootEl, '[data-bb-config]');
+    var prodEl = q(rootEl, '[data-bb-product]');
+    if (!cfgEl || !prodEl) return;                 // not a bundle — leave the page alone
+
+    var cfg, raw;
+    try {
+      cfg = JSON.parse(cfgEl.textContent);
+      raw = JSON.parse(prodEl.textContent);
+    } catch (e) {
+      if (root.console) console.error('[bundle-builder] bad payload', e);
+      return;
+    }
+
+    var ctx = {
+      countryIso: upper(cfg.countryIso || 'US'),
+      currencySymbol: cfg.currencySymbol || '$',
+      currencyCode: cfg.currencyCode || null,
+      decimalPlaces: cfg.decimalPlaces === undefined ? 2 : cfg.decimalPlaces,
+      locale: cfg.locale || undefined,
+      fallbackImage: cfg.fallbackImage || ''
+    };
+
+    var model = normalize(raw, ctx);
+    if (!model.groups.length) return;
+
+    if (cfg.debug && model.warnings.length && root.console) {
+      model.warnings.forEach(function (w) { console.warn('[bundle-builder] ' + w); });
+    }
+    if (cfg.debug && model.unknownFields.length && root.console) {
+      // Future platform features surface here instead of silently doing nothing.
+      console.info('[bundle-builder] unrecognised fields (not rendered): ' + model.unknownFields.join(', '));
+    }
+
+    installErrorCapture();
+
+    var selection = {};
+    var branches = {};
+    var subscribeAll = false;
+    var bundlePlanId = null;
+
+    // ---- defaults: clamp to max, skip out-of-stock / unavailable (P19) ----
+    model.groups.forEach(function (g) {
+      if (g.type !== 'customizable' || g.max === null) {
+        if (g.type !== 'customizable') return;
+      }
+      var used = 0;
+      g.items.forEach(function (it) {
+        if (!it.isDefault || !it.inStock || !it.availableInCountry) return;
+        var qty = Math.min(it.quantity || 1, it.maxQuantity === null ? Infinity : it.maxQuantity);
+        if (g.max !== null && used + qty > g.max) return;   // never pre-select past max
+        used += qty;
+        selection[key(g.id, it.variantId)] = { qty: qty, subscribe: it.forceSubscription, planId: it.subscriptionPlanId };
+      });
+    });
+    model.exclusiveSets.forEach(function (set, i) {
+      if (set.defaultSortOrder !== null) {
+        var g = model.groups.filter(function (gg) { return gg.sortOrder === set.defaultSortOrder; })[0];
+        if (g) branches[i] = g.id;
+      }
+    });
+
+    var groupsHost = q(rootEl, '[data-bb-groups]');
+    var groupEls = {};
+
+    // ---- build the grids (group shells are server-rendered) ----
+    model.groups.forEach(function (g) {
+      var gEl = q(rootEl, '[data-bb-group="' + g.id + '"]');
+      if (!gEl && groupsHost) {
+        gEl = tpl(rootEl, 'group');
+        if (!gEl) return;
+        gEl.setAttribute('data-bb-group', g.id);
+        groupsHost.appendChild(gEl);
+      }
+      if (!gEl) return;
+      groupEls[g.id] = gEl;
+      gEl.setAttribute('data-bb-group-type', g.type);
+
+      setText(gEl, '[data-bb-group-title]', g.title);
+      var desc = q(gEl, '[data-bb-group-desc]');
+      if (desc) { desc.textContent = g.description; show(desc, !!g.description); }
+
+      var grid = q(gEl, '[data-bb-grid]');
+      if (grid && g.type === 'customizable') {
+        grid.innerHTML = '';
+        g.items.forEach(function (it) { grid.appendChild(buildCard(g, it)); });
+      }
+
+      var choose = q(gEl, '[data-bb-choose]');
+      var setIndex = -1;
+      model.exclusiveSets.forEach(function (s, i) { if (s.groupIds.indexOf(g.id) !== -1) setIndex = i; });
+      show(choose, setIndex !== -1);
+      if (choose && setIndex !== -1) {
+        choose.addEventListener('click', function () {
+          branches[setIndex] = g.id;
+          // Switching a branch clears the sibling's selections atomically.
+          model.exclusiveSets[setIndex].groupIds.forEach(function (gid) {
+            if (gid === g.id) return;
+            Object.keys(selection).forEach(function (k) {
+              if (k.indexOf(gid + ':') === 0) delete selection[k];
+            });
+          });
+          update();
+        });
+      }
+    });
+
+    function buildCard(g, it) {
+      var card = tpl(rootEl, 'card');
+      card.setAttribute('data-bb-variant', it.variantId);
+      card.setAttribute('data-bb-card-group', g.id);
+
+      var img = q(card, '[data-bb-card-image]');
+      var ph = q(card, '[data-bb-card-placeholder]');
+      if (it.image && img) { img.src = it.image; img.alt = it.title; show(img, true); show(ph, false); }
+      else { show(img, false); show(ph, true); }
+
+      setText(card, '[data-bb-card-title]', it.title);
+      var vt = q(card, '[data-bb-card-variant]');
+      if (vt) { vt.textContent = it.variantTitle; show(vt, !!it.variantTitle); }
+
+      var priceEl = q(card, '[data-bb-card-price]');
+      if (priceEl) {
+        // A fixed_price group's item prices are display noise — the pick never
+        // moves the charge, so showing them is a lie.
+        var showPrice = g.pricingType === 'dynamic_price' && !model.bundlePricingEnabled && it.price;
+        priceEl.textContent = showPrice ? '+' + money(ctx, it.price) : '';
+        show(priceEl, !!showPrice);
+      }
+      var cmpEl = q(card, '[data-bb-card-compare]');
+      if (cmpEl) {
+        var showCmp = g.pricingType === 'dynamic_price' && !model.bundlePricingEnabled && it.comparePrice;
+        cmpEl.textContent = showCmp ? money(ctx, it.comparePrice) : '';
+        show(cmpEl, !!showCmp);
+      }
+
+      var sub = q(card, '[data-bb-card-subscribe]');
+      show(sub, it.allowSubscription || it.forceSubscription);
+      if (sub) {
+        var box = q(sub, 'input');
+        if (box) {
+          box.checked = it.forceSubscription;
+          box.disabled = it.forceSubscription;
+          box.addEventListener('change', function () {
+            var e = selection[key(g.id, it.variantId)];
+            if (e) { e.subscribe = box.checked; update(); }
+          });
+        }
+        var lbl = q(sub, '[data-bb-card-subscribe-label]');
+        if (lbl) lbl.textContent = it.forceSubscription ? 'Subscription required' : 'Subscribe & save';
+      }
+
+      var toggle = q(card, '[data-bb-toggle]');
+      var stepper = q(card, '[data-bb-stepper]');
+      var maxQty = it.maxQuantity === null ? Infinity : it.maxQuantity;
+
+      if (toggle) {
+        toggle.addEventListener('click', function () {
+          var k = key(g.id, it.variantId);
+          var st = rules(model, selection, branches).perGroup[g.id];
+          if (selection[k]) { delete selection[k]; update(); return; }
+          if (!it.inStock || !it.availableInCountry) return;
+          // At max: swap out the oldest pick rather than silently ignoring the
+          // click (P15 — the single biggest source of support tickets).
+          if (st && st.atMax) {
+            if (g.max === 1) {
+              Object.keys(selection).forEach(function (kk) {
+                if (kk.indexOf(g.id + ':') === 0) delete selection[kk];
+              });
+            } else { return; }
+          }
+          selection[k] = { qty: Math.min(it.quantity || 1, maxQty), subscribe: it.forceSubscription, planId: it.subscriptionPlanId };
+          update();
+        });
+      }
+      if (stepper) {
+        var minus = q(stepper, '[data-bb-minus]');
+        var plus = q(stepper, '[data-bb-plus]');
+        if (minus) minus.addEventListener('click', function () {
+          var e = selection[key(g.id, it.variantId)];
+          if (!e) return;
+          e.qty -= 1;
+          if (e.qty <= 0) delete selection[key(g.id, it.variantId)];
+          update();
+        });
+        if (plus) plus.addEventListener('click', function () {
+          var e = selection[key(g.id, it.variantId)];
+          var st = rules(model, selection, branches).perGroup[g.id];
+          if (!e) return;
+          if (e.qty + 1 > maxQty) return;
+          if (st && g.max !== null && st.count + 1 > g.max) return;
+          e.qty += 1;
+          update();
+        });
+      }
+      return card;
+    }
+
+    // ---- summary / CTA refs ----
+    var summaryHost = q(rootEl, '[data-bb-summary-items]');
+    var totalEl = q(rootEl, '[data-bb-total]');
+    var recurringEl = q(rootEl, '[data-bb-recurring]');
+    var cta = q(rootEl, '[data-bb-cta]');
+    var msgEl = q(rootEl, '[data-bb-message]');
+    var errEl = q(rootEl, '[data-bb-error]');
+    var subAllEl = q(rootEl, '[data-bb-subscribe-all]');
+    var planSel = q(rootEl, '[data-bb-plan-select]');
+
+    if (subAllEl) {
+      var subAllBox = q(subAllEl, 'input');
+      show(subAllEl, model.subscriptionPlans.length > 0);
+      if (subAllBox) subAllBox.addEventListener('change', function () {
+        subscribeAll = subAllBox.checked; update();
+      });
+    }
+    if (planSel) {
+      planSel.innerHTML = '';
+      model.subscriptionPlans.forEach(function (p) {
+        var o = document.createElement('option');
+        o.value = p.id; o.textContent = p.name;
+        if (p['default'] || p.selected) { o.selected = true; bundlePlanId = num(p.id); }
+        planSel.appendChild(o);
+      });
+      // Multi-plan selection is unproven upstream — hide it rather than fake it.
+      show(planSel, model.subscriptionPlans.length > 1);
+      planSel.addEventListener('change', function () { bundlePlanId = num(planSel.value); update(); });
+    }
+
+    function update() {
+      var r = rules(model, selection, branches);
+      var t = total(model, selection, branches, subscribeAll);
+
+      model.groups.forEach(function (g) {
+        var gEl = groupEls[g.id];
+        if (!gEl) return;
+        var st = r.perGroup[g.id] || {};
+        gEl.classList.toggle('is-inactive', !!st.inactive);
+        gEl.classList.toggle('is-complete', !!st.satisfied && g.type === 'customizable' && st.count > 0);
+
+        var tracker = q(gEl, '[data-bb-tracker]');
+        if (tracker) {
+          var showTracker = g.type === 'customizable' && g.max !== null && cfg.showProgress !== false;
+          show(tracker, showTracker);
+          if (showTracker) {
+            setText(tracker, '[data-bb-tracker-label]', st.count + ' / ' + g.max);
+            var fill = q(tracker, '[data-bb-tracker-fill]');
+            if (fill) fill.style.width = Math.min(100, (st.count / g.max) * 100) + '%';
+            tracker.setAttribute('aria-valuenow', st.count);
+            tracker.setAttribute('aria-valuemax', g.max);
+          }
+        }
+
+        var rule = q(gEl, '[data-bb-rule]');
+        if (rule) {
+          var text = '';
+          if (g.type === 'customizable' && !g.configError) {
+            if (g.selectionType === 'exact') text = 'Choose ' + g.min;
+            else if (g.selectionType === 'min_only') text = 'Choose at least ' + g.min;
+            else if (g.selectionType === 'max_only') text = 'Choose up to ' + g.max + ' (optional)';
+            else if (g.min > 0) text = 'Choose ' + g.min + '–' + g.max;
+            else text = 'Choose up to ' + g.max;
+          }
+          rule.textContent = text;
+          show(rule, !!text);
+        }
+
+        var choose = q(gEl, '[data-bb-choose]');
+        if (choose && !choose.hidden) {
+          var active = !st.inactive;
+          choose.setAttribute('aria-pressed', active ? 'true' : 'false');
+          setText(choose, '[data-bb-choose-label]', active ? 'Selected' : 'Choose this');
+        }
+
+        qa(gEl, '[data-bb-variant]').forEach(function (card) {
+          var vid = num(card.getAttribute('data-bb-variant'));
+          var it = g.items.filter(function (x) { return x.variantId === vid; })[0];
+          if (!it) return;
+          var e = selection[key(g.id, vid)];
+          var selected = !!e;
+          card.classList.toggle('is-selected', selected);
+          card.setAttribute('aria-checked', selected ? 'true' : 'false');
+
+          var unavailable = !it.inStock || !it.availableInCountry;
+          // At max with nothing selected here: a real disabled affordance with a
+          // reason, never a live-looking button that silently ignores clicks.
+          var blocked = !selected && st.atMax && g.max !== 1;
+          card.classList.toggle('is-unavailable', unavailable);
+          card.classList.toggle('is-blocked', !!blocked);
+          card.setAttribute('aria-disabled', (unavailable || blocked) ? 'true' : 'false');
+
+          var t2 = q(card, '[data-bb-toggle]');
+          if (t2) {
+            t2.disabled = unavailable || blocked;
+            setText(card, '[data-bb-toggle-label]',
+              unavailable ? (it.inStock ? 'Unavailable in your region' : 'Out of stock')
+                : blocked ? 'Remove one to choose another'
+                  : selected ? 'Selected' : 'Add');
+          }
+          var stepEl = q(card, '[data-bb-stepper]');
+          show(stepEl, selected && (it.maxQuantity === null || it.maxQuantity > 1));
+          if (selected && stepEl) setText(stepEl, '[data-bb-qty]', String(e.qty));
+        });
+      });
+
+      // ---- summary ----
+      if (summaryHost) {
+        summaryHost.innerHTML = '';
+        model.groups.forEach(function (g) {
+          var st = r.perGroup[g.id] || {};
+          if (st.inactive) return;
+          g.items.forEach(function (it) {
+            var e = selection[key(g.id, it.variantId)];
+            var qty = g.type === 'included' ? it.quantity : (e ? e.qty : 0);
+            if (!qty) return;
+            var row = tpl(rootEl, 'summary-row');
+            if (!row) return;
+            setText(row, '[data-bb-sum-title]', it.title);
+            setText(row, '[data-bb-sum-qty]', qty > 1 ? '×' + qty : '');
+            var p = q(row, '[data-bb-sum-price]');
+            if (p) {
+              var showP = g.pricingType === 'dynamic_price' && !model.bundlePricingEnabled && it.price;
+              p.textContent = showP ? money(ctx, it.price * qty) : '';
+            }
+            var b = q(row, '[data-bb-sum-badge]');
+            if (b) {
+              var subbed = (e && e.subscribe) || it.forceSubscription || subscribeAll;
+              b.textContent = subbed ? 'Subscription' : '';
+              show(b, !!subbed);
+            }
+            summaryHost.appendChild(row);
+          });
+        });
+      }
+
+      if (totalEl) totalEl.textContent = money(ctx, t.amount);
+      if (recurringEl) {
+        // P7/P10: renewal can differ wildly from the first charge and the
+        // platform first reveals it at checkout. Disclose it here.
+        var showRec = cfg.showRecurring !== false && t.recurring !== null && t.recurring > 0;
+        recurringEl.textContent = showRec ? 'Then ' + money(ctx, t.recurring) + ' per renewal' : '';
+        show(recurringEl, showRec);
+      }
+
+      if (cta) cta.disabled = !r.complete;
+      if (msgEl) {
+        var first = r.violations[0];
+        msgEl.textContent = first ? first.message : '';
+        show(msgEl, !!first);
+      }
+      if (errEl && errEl.dataset.sticky !== 'true') show(errEl, false);
+    }
+
+    if (cta) {
+      cta.addEventListener('click', function () {
+        var r = rules(model, selection, branches);
+        if (!r.complete) { update(); return; }
+        var payload = buildCartPayload(model, selection, branches, subscribeAll, bundlePlanId);
+        model.expectedFree = total(model, selection, branches, subscribeAll).amount === 0;
+
+        cta.disabled = true;
+        cta.classList.add('is-loading');
+        addToCart(model, payload).then(function (res) {
+          cta.classList.remove('is-loading');
+          cta.disabled = false;
+          if (!res.ok) {
+            if (errEl) { errEl.textContent = res.error; errEl.dataset.sticky = 'true'; show(errEl, true); }
+            if (root.console) console.error('[bundle-builder] add failed', res);
+            return;
+          }
+          if (errEl) { errEl.dataset.sticky = 'false'; show(errEl, false); }
+          var s = sdk();
+          if (s && s.cart && s.cart.control && s.cart.control.open) s.cart.control.open();
+        });
+      });
+    }
+
+    update();
+    rootEl.setAttribute('data-bb-ready', 'true');
+  }
+
+  function boot() {
+    Array.prototype.slice.call(document.querySelectorAll('[data-bb-root]')).forEach(mount);
+  }
+
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);
+  else boot();
+
+  root.FluidBundleBuilder = {
+    normalize: normalize,
+    rules: rules,
+    total: total,
+    buildCartPayload: buildCartPayload,
+    addToCart: addToCart,
+    mount: mount
+  };
+})(window);
diff --git a/themes/dynamic-bundles/templates/product/bundle/index.liquid b/themes/dynamic-bundles/templates/product/bundle/index.liquid
new file mode 100644
index 0000000..2827897
--- /dev/null
+++ b/themes/dynamic-bundles/templates/product/bundle/index.liquid
@@ -0,0 +1,45 @@
+{%- comment -%}
+  Host template for Dynamic Bundles.
+  ----------------------------------------------------------------------------
+  NEVER host a bundle section in product/default — the platform's section does
+  not self-guard and paints ~98 KB of empty "Build Your Bundle" UI onto every
+  ordinary product (defect P4). Ours does self-guard, but a dedicated template
+  is still correct: it keeps routing explicit and reversible.
+
+  This template is ADDITIVE. CreateAction sets status:active and publishes but
+  does NOT set default:true, so it cannot hijack the default product page.
+
+  Routing is manual and per-active-theme:
+    PATCH /api/company/v1/products/{id} { "product": { "application_theme_template_id": <this id> } }
+  Re-run that after ANY theme switch or clone — the assignment is a
+  template_resources join scoped to the active theme and is silently dropped.
+
+  The fallback below matters: if a product is routed here but has no bundle
+  groups (draft data, a mis-route, a bundle whose groups were removed), the
+  shopper still gets a working product page instead of a blank one.
+{%- endcomment -%}
+
+{% section 'header' %}
+
+<main class="bundle-page">
+  {%- if product.product_bundle_groups.size > 0 -%}
+    {% section 'bundle_builder' %}
+  {%- else -%}
+    {% section 'main_product' %}
+  {%- endif -%}
+</main>
+
+{% section 'footer' %}
+
+{% schema %}
+{
+  "name": "Dynamic bundle",
+  "sections": {
+    "header": { "type": "header" },
+    "bundle_builder": { "type": "bundle_builder" },
+    "main_product": { "type": "main_product" },
+    "footer": { "type": "footer" }
+  },
+  "order": ["header", "bundle_builder", "main_product", "footer"]
+}
+{% endschema %}
diff --git a/themes/dynamic-bundles/templates/sections/bundle_builder/index.liquid b/themes/dynamic-bundles/templates/sections/bundle_builder/index.liquid
new file mode 100644
index 0000000..6d78175
--- /dev/null
+++ b/themes/dynamic-bundles/templates/sections/bundle_builder/index.liquid
@@ -0,0 +1,277 @@
+{%- comment -%}
+  ============================================================================
+  bundle_builder — universal Fluid Dynamic Bundle section
+  ----------------------------------------------------------------------------
+  Presentation only. No pricing logic, no rule logic, no bundle-specific ids.
+  All behaviour lives in assets/bundle-builder.js (normalize / rules / render /
+  cart). All styling lives in assets/bundle-builder.css.
+
+  Renders NOTHING unless the resolved product has bundle groups, so this section
+  is safe to place on a shared product template (the platform's own section is
+  not — it paints ~98 KB of empty UI onto every ordinary product, defect P4).
+
+  Progressive enhancement: group shells and static/included rows are rendered
+  server-side, so the page has real content and stable layout before JS runs.
+  JS fills the selectable grids and the summary.
+  ============================================================================
+{%- endcomment -%}
+
+{%- liquid
+  assign bp = section.settings.bundle_product
+  if bp == blank
+    assign bp = product
+  endif
+
+  assign is_bundle = false
+  if bp != blank and bp.product_bundle_groups.size > 0
+    assign is_bundle = true
+  endif
+-%}
+
+{%- if is_bundle -%}
+  {%- liquid
+    assign iso = localization.country.iso_code | default: 'US' | upcase
+    assign sym = localization.country.currency.symbol | default: '$'
+    assign ccode = localization.country.currency.iso_code
+    assign dp = localization.country.currency.decimal_places
+    if dp == blank
+      assign dp = 2
+    endif
+    assign fallback_image = ''
+    if bp.images.size > 0
+      assign fallback_image = bp.images[0].src
+    endif
+  -%}
+
+  <div
+    class="bb"
+    data-bb-root
+    data-bb-section="{{ section.id }}"
+    style="
+      --bb-accent: {{ section.settings.accent_color | default: 'var(--clr-primary, var(--color-primary, #111111))' }};
+      --bb-radius: {{ section.settings.card_radius | default: 12 }}px;
+      --bb-pad-top: {{ section.settings.padding.top | default: 48 }}px;
+      --bb-pad-bottom: {{ section.settings.padding.bottom | default: 48 }}px;
+    "
+  >
+    {%- comment -%} ---------- data contract: ONE tag ---------- {%- endcomment -%}
+    <script type="application/json" data-bb-config>
+      {
+        "countryIso": {{ iso | json }},
+        "currencySymbol": {{ sym | json }},
+        "currencyCode": {{ ccode | json }},
+        "decimalPlaces": {{ dp | json }},
+        "locale": {{ request.locale.iso_code | default: '' | json }},
+        "fallbackImage": {{ fallback_image | json }},
+        "showProgress": {{ section.settings.show_progress | json }},
+        "showRecurring": {{ section.settings.show_recurring | json }},
+        "debug": {{ section.settings.debug | default: false | json }}
+      }
+    </script>
+
+    {%- comment -%}
+      The platform emits this blob with a bare JSON.generate, so a product title
+      containing `</script>` executes (defect P1, live stored XSS). We escape the
+      three dangerous characters as JSON \u escapes — JSON.parse restores them
+      exactly, and the raw characters never reach the HTML parser.
+    {%- endcomment -%}
+    <script type="application/json" data-bb-product>
+      {{- bp | json | replace: '<', '\u003c' | replace: '>', '\u003e' | replace: '&', '\u0026' -}}
+    </script>
+
+    {%- comment -%} ---------- templates cloned by JS ---------- {%- endcomment -%}
+    <template data-bb-tpl="group">
+      <section class="bb-group" data-bb-group>
+        <header class="bb-group__head">
+          <h3 class="bb-group__title" data-bb-group-title></h3>
+          <button type="button" class="bb-group__choose" data-bb-choose hidden aria-pressed="false">
+            <span data-bb-choose-label>Choose this</span>
+          </button>
+        </header>
+        <p class="bb-group__desc" data-bb-group-desc hidden></p>
+        <p class="bb-group__rule" data-bb-rule hidden></p>
+        <div class="bb-tracker" data-bb-tracker hidden role="progressbar" aria-valuemin="0">
+          <span class="bb-tracker__label" data-bb-tracker-label></span>
+          <span class="bb-tracker__track"><span class="bb-tracker__fill" data-bb-tracker-fill></span></span>
+        </div>
+        <div class="bb-grid" data-bb-grid role="group"></div>
+      </section>
+    </template>
+
+    <template data-bb-tpl="card">
+      <div class="bb-card" role="checkbox" aria-checked="false" data-bb-variant>
+        <div class="bb-card__media">
+          <img class="bb-card__img" data-bb-card-image loading="lazy" decoding="async" alt="" hidden>
+          <span class="bb-card__ph" data-bb-card-placeholder aria-hidden="true"></span>
+        </div>
+        <div class="bb-card__body">
+          <span class="bb-card__title" data-bb-card-title></span>
+          <span class="bb-card__variant" data-bb-card-variant hidden></span>
+          <span class="bb-card__prices">
+            <s class="bb-card__compare" data-bb-card-compare hidden></s>
+            <span class="bb-card__price" data-bb-card-price hidden></span>
+          </span>
+          <label class="bb-check bb-card__sub" data-bb-card-subscribe hidden>
+            <input type="checkbox"><span class="bb-check__box" aria-hidden="true"></span>
+            <span data-bb-card-subscribe-label></span>
+          </label>
+        </div>
+        <div class="bb-card__actions">
+          <button type="button" class="bb-btn bb-btn--ghost bb-card__toggle" data-bb-toggle>
+            <span data-bb-toggle-label>Add</span>
+          </button>
+          <div class="bb-stepper" data-bb-stepper hidden>
+            <button type="button" class="bb-stepper__btn" data-bb-minus aria-label="Decrease quantity">&minus;</button>
+            <span class="bb-stepper__val" data-bb-qty aria-live="polite">1</span>
+            <button type="button" class="bb-stepper__btn" data-bb-plus aria-label="Increase quantity">+</button>
+          </div>
+        </div>
+      </div>
+    </template>
+
+    <template data-bb-tpl="summary-row">
+      <li class="bb-sum__row">
+        <span class="bb-sum__title" data-bb-sum-title></span>
+        <span class="bb-sum__qty" data-bb-sum-qty></span>
+        <span class="bb-sum__badge" data-bb-sum-badge hidden></span>
+        <span class="bb-sum__price" data-bb-sum-price></span>
+      </li>
+    </template>
+
+    {%- comment -%} ---------- server-rendered shell ---------- {%- endcomment -%}
+    <div class="bb__layout bb__layout--{{ section.settings.layout | default: 'sidebar' }}">
+      <div class="bb__main">
+        {%- if section.settings.heading != blank -%}
+          <h2 class="bb__heading">{{ section.settings.heading }}</h2>
+        {%- endif -%}
+        {%- if section.settings.description != blank -%}
+          <p class="bb__intro">{{ section.settings.description }}</p>
+        {%- endif -%}
+
+        <div data-bb-groups>
+          {%- for group in bp.product_bundle_groups -%}
+            {%- unless group.pricing_config.hidden -%}
+              <section
+                class="bb-group"
+                data-bb-group="{{ group.id }}"
+                data-bb-group-type="{{ group.group_type }}"
+              >
+                <header class="bb-group__head">
+                  <h3 class="bb-group__title" data-bb-group-title>{{ group.title }}</h3>
+                  <button type="button" class="bb-group__choose" data-bb-choose hidden aria-pressed="false">
+                    <span data-bb-choose-label>Choose this</span>
+                  </button>
+                </header>
+                <p class="bb-group__desc" data-bb-group-desc {% if group.description == blank %}hidden{% endif %}>{{ group.description }}</p>
+                <p class="bb-group__rule" data-bb-rule hidden></p>
+
+                {%- if group.group_type == 'customizable' -%}
+                  <div class="bb-tracker" data-bb-tracker hidden role="progressbar" aria-valuemin="0">
+                    <span class="bb-tracker__label" data-bb-tracker-label></span>
+                    <span class="bb-tracker__track"><span class="bb-tracker__fill" data-bb-tracker-fill></span></span>
+                  </div>
+                  <div class="bb-grid" data-bb-grid role="group" aria-label="{{ group.title | escape }}">
+                    {%- comment -%} JS fills this; a no-JS shopper sees the included list + copy. {%- endcomment -%}
+                  </div>
+                {%- else -%}
+                  <ul class="bb-included">
+                    {%- for item in group.bundle_group_items -%}
+                      <li class="bb-included__row">
+                        {%- assign img = item.variant.images[0].src | default: item.product_image_url -%}
+                        {%- if img != blank -%}
+                          <img class="bb-included__img" src="{{ img }}" alt="" loading="lazy" decoding="async" width="48" height="48">
+                        {%- else -%}
+                          <span class="bb-included__ph" aria-hidden="true"></span>
+                        {%- endif -%}
+                        <span class="bb-included__title">{{ item.product_title }}</span>
+                        {%- if item.display_quantity > 1 -%}
+                          <span class="bb-included__qty">&times;{{ item.display_quantity }}</span>
+                        {%- endif -%}
+                      </li>
+                    {%- endfor -%}
+                  </ul>
+                {%- endif -%}
+              </section>
+            {%- endunless -%}
+          {%- endfor -%}
+        </div>
+      </div>
+
+      <aside class="bb__aside">
+        <div class="bb-sum">
+          <h3 class="bb-sum__heading">{{ section.settings.summary_heading | default: 'Your bundle' }}</h3>
+          <ul class="bb-sum__items" data-bb-summary-items></ul>
+
+          <label class="bb-check bb-sum__suball" data-bb-subscribe-all hidden>
+            <input type="checkbox"><span class="bb-check__box" aria-hidden="true"></span>
+            <span>{{ section.settings.subscribe_label | default: 'Subscribe & save' }}</span>
+          </label>
+          <select class="bb-sum__plan" data-bb-plan-select aria-label="Subscription plan" hidden></select>
+
+          <div class="bb-sum__total">
+            <span>{{ section.settings.total_label | default: 'Total' }}</span>
+            <strong data-bb-total aria-live="polite">{{ bp.price }}</strong>
+          </div>
+          <p class="bb-sum__recurring" data-bb-recurring hidden aria-live="polite"></p>
+
+          <button type="button" class="bb-btn bb-btn--primary bb-sum__cta" data-bb-cta disabled>
+            {{ section.settings.cta_text | default: 'Add bundle to cart' }}
+          </button>
+          <p class="bb-sum__msg" data-bb-message aria-live="polite" hidden></p>
+          <p class="bb-sum__err" data-bb-error role="alert" hidden></p>
+          <noscript>
+            <p class="bb-sum__msg">Building a bundle requires JavaScript.</p>
+          </noscript>
+        </div>
+      </aside>
+    </div>
+  </div>
+{%- endif -%}
+
+{% schema %}
+{
+  "name": "Bundle Builder",
+  "tag": "section",
+  "class": "bundle-builder",
+  "settings": [
+    { "type": "header", "content": "Bundle source" },
+    {
+      "type": "product",
+      "id": "bundle_product",
+      "label": "Bundle product",
+      "info": "Leave EMPTY on product templates — the page product is used automatically, and pinning hard-wires one bundle. Set this only on home/landing page templates."
+    },
+    { "type": "header", "content": "Content" },
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Build your bundle" },
+    { "type": "textarea", "id": "description", "label": "Description" },
+    { "type": "text", "id": "summary_heading", "label": "Summary heading", "default": "Your bundle" },
+    { "type": "text", "id": "total_label", "label": "Total label", "default": "Total" },
+    { "type": "text", "id": "cta_text", "label": "Add to cart button", "default": "Add bundle to cart" },
+    { "type": "text", "id": "subscribe_label", "label": "Subscribe label", "default": "Subscribe & save" },
+    { "type": "header", "content": "Behaviour" },
+    { "type": "checkbox", "id": "show_progress", "label": "Show per-group progress", "default": true },
+    {
+      "type": "checkbox",
+      "id": "show_recurring",
+      "label": "Disclose renewal price",
+      "default": true,
+      "info": "Renewal can differ from the first charge. Off means the shopper first sees it at checkout."
+    },
+    { "type": "checkbox", "id": "debug", "label": "Log configuration warnings to the console", "default": false },
+    { "type": "header", "content": "Layout & style" },
+    {
+      "type": "select",
+      "id": "layout",
+      "label": "Layout",
+      "default": "sidebar",
+      "options": [
+        { "value": "sidebar", "label": "Summary sidebar" },
+        { "value": "stacked", "label": "Summary below" }
+      ]
+    },
+    { "type": "color", "id": "accent_color", "label": "Accent colour" },
+    { "type": "range", "id": "card_radius", "label": "Card corner radius", "min": 0, "max": 32, "step": 2, "unit": "px", "default": 12 },
+    { "type": "padding", "id": "padding", "label": "Section padding" }
+  ]
+}
+{% endschema %}
diff --git a/workflows/dynamic-bundles.workflow.json b/workflows/dynamic-bundles.workflow.json
new file mode 100644
index 0000000..8ff372a
--- /dev/null
+++ b/workflows/dynamic-bundles.workflow.json
@@ -0,0 +1,297 @@
+{
+  "revision": "2026-08-07-rev3-run-skill-materialization+human-in-the-loop-approval+theme-pinning+runif-source-and-approval",
+  "slug": "dynamic-bundles",
+  "name": "Dynamic Bundles",
+  "description": "Execution engine for the themes/dynamic-bundles skill. Understands a company's existing bundle implementation (or a source configurator page) and recreates it as Fluid Dynamic Bundles, with one reusable theme implementation that renders every current and future bundle. Every step materializes the skill with run_skill first. Everything before `write-bundles` is READ-ONLY; the mutating tail is gated on `context.approved` via runIf AND on a human_in_the_loop confirmation of the actual plan. Requires `context.theme_id` pinned to the active theme — preflight stops the run if it is missing or disagrees.",
+  "maxParallel": 3,
+  "runTitleTemplate": "Dynamic Bundles — {{company}}",
+  "steps": [
+    {
+      "id": "preflight",
+      "name": "Preflight: company, theme, and variant completeness",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nEstablish what you are working on before touching anything.\n\n1. GET `/api/company/v1/companies/me` — record company id AND the `fluid_shop` subdomain. The cart step needs the subdomain; do not skip it.\n2. GET `/api/application_themes/active` — record active theme id and name. **Then reconcile it with `context.theme_id`.** Mist resolves a theme-targeted step from the run's initial `context.theme_id`, NOT from anything discovered here — so if `context.theme_id` is absent or names a different theme, every later theme step may edit an unrelated checkout. If they disagree, or `context.theme_id` is missing, STOP and tell the operator to restart the run with `context.theme_id` set to the active theme. Routing is a `template_resources` join **scoped to the active theme**, so every later routing claim is relative to this id.\n3. GET `/api/v2025-06/bundles` — READ ONLY. Record existing bundle count and slugs. This endpoint omits `product_id`; never use it to get from bundle to product.\n4. **Variant completeness (G0, blocking).** Identify the products that will become bundle components and confirm each already carries its **full variant set**. A group built while its components are single-variant points at the only variant available; once real variants land that pointer is wrong and the group needs repointing or a full rebuild. If any component product is missing variants, STOP and report that the catalog must be fixed first.\n5. Read `context` for `source_url` and `approved`; state which are present.\n\nSTEP_OUTPUT: company id, fluid_shop, active theme id + name, existing bundle count, variant-completeness verdict, and whether source_url / approved were supplied.",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "The report names company id, the fluid_shop subdomain, and the active theme id and name, each quoted from a successful GET this turn.",
+        "Existing bundles were listed via GET /api/v2025-06/bundles and the count is stated (zero is valid).",
+        "Variant completeness is explicitly asserted for the intended component products — either 'all carry full variant sets' with evidence, or a STOP naming which products are incomplete.",
+        "The report states whether context.source_url and context.approved were present, with no assumption either way.",
+        "context.theme_id is reconciled against the active theme from GET /api/application_themes/active: either they match and both ids are quoted, or the step STOPPED and said so. Reporting the active theme without checking context.theme_id is a FAIL — the theme steps do not read this step's output to choose a project."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "stop"
+      },
+      "dependsOn": [],
+      "maxReworkRounds": 2
+    },
+    {
+      "id": "study-company",
+      "name": "Study the catalog and classify candidate shapes",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nFind the products that should become bundles — and, critically, the ones that should NOT. Follow `playbooks/01-discovery.md`; SKILL.md §4a carries the same rules in short form.\n\n1. Page `/api/company/v1/products` at `per_page=50`. **`per_page=100` returns zero products with no error.** Record every product with multi-value `options`, plus every product already carrying `product_bundle_groups`.\n2. For each candidate record **the option id** and its values.\n3. Classify with the shape test:\n   - values are **components of one sellable item** → **bundle**\n   - values are **separate sellable items that already exist as their own products** → **category/collection, NOT a bundle**\n   Products that merely look alike do not share a shape. In the reference campaign seven near-identical products split three ways across three option ids; converting a flattened category into one bundle destroys a browsable listing and advertises one wrong price.\n4. Label each bundle candidate: fixed kit, configurable, or **both** (a category page of fixed kits where each card ALSO has a CUSTOMIZE link — that is N fixed kits PLUS one configurable bundle).\n5. **Identify the anchor** of each bundle — the item the bundle is named after, which will hold the base price. Flag any candidate with more than one anchor candidate, or none.\n6. Record the theme's CSS token lineage (`--clr-*` vs `--color-*`) and container mechanism.\n\nSTEP_OUTPUT: table of candidate → option id → components|separate-items → bundle|category → fixed|configurable|both → anchor.",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "Products were listed via GET /api/company/v1/products at per_page<=50 and each candidate is named by id and title.",
+        "EVERY candidate carries its own option id and an explicit components-of-one-item vs separate-sellable-items classification. A blanket claim that a group of products 'share a pattern' is a FAIL — the option id must be cited per product.",
+        "Any candidate classified as category/collection rather than bundle is named with its reason, so it is excluded from the write phase.",
+        "Each bundle candidate is labelled fixed kit, configurable, or both, and names its anchor item (or flags that the anchor is ambiguous).",
+        "The theme's CSS token lineage and container mechanism are named."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "strict",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "preflight"
+      ],
+      "maxReworkRounds": 2
+    },
+    {
+      "id": "source-analysis",
+      "name": "Source configurator analysis",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nRun ONLY when `context.source_url` is present; otherwise emit `STEP_OUTPUT: no source_url supplied; skipped` and stop.\n\nCrawl the source with `crawl(url, formats: ['markdown','html'], only_main_content: false)` and extract verbatim:\n- every group heading and its selection rule (Choose One, Up to Three, included-with-no-choice)\n- every option with its **exact price** and any qualifier text\n- **which option is preselected in each group** — this is load-bearing, it becomes `is_default` and it determines the base arithmetic\n\nTwo hard rules:\n1. **Never trust imported catalog prices as source of truth.** Read prices off the source. In the reference campaign the importer had proteins at $50/$50/$61 while the live page said $52/$52/$63 — the catalog was wrong before anything was touched.\n2. If the source is bot-gated (Kasada/Cloudflare) and the crawl fails, say so plainly and ask the operator to paste the rendered HTML. Do not infer a menu you could not read.\n\n**Membership is per bundle.** Different bundles offer different subsets of the same product's variants. Record each group's membership from the source's own definition — never derive it from the component product's full variant list, which silently adds options the merchant does not sell.\n\nSTEP_OUTPUT: group-by-group structure with verbatim prices and the declared default per group, the page's shape verdict, and how evidence was obtained (crawled | operator-pasted | unavailable).",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "Either the source was crawled this turn with verbatim group headings, selection rules and per-option prices, OR no source_url was supplied and the step reported that and stopped, OR the source was unreadable and the report names what it asked the operator for. All three are passes; a crawl that half-happened and was written up as though it succeeded is not.",
+        "The declared default member of each choice group is recorded, or its absence is stated explicitly.",
+        "Group membership is presented as read from the source per bundle, not derived from any component product's variant list."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "preflight"
+      ],
+      "maxReworkRounds": 2,
+      "runIf": {
+        "flag": "source_url"
+      }
+    },
+    {
+      "id": "plan-translation",
+      "name": "Plan the translation and the pricing arithmetic",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nProduce `bundle-plan.json`. Still READ-ONLY — make no writes.\n\nFor each product to convert or create, plan the group list with `group_type`, `selection_type`, min/max and `pricing_config`; every item with its variant id; the **before** price span; and the **intended after** state.\n\n**The pricing decision (playbooks/09-pricing-patterns.md — read it if reachable):**\n\n- If the shopper's choices should change the price (the usual case), use the **rebalanced base**:\n  `anchor_group.fixed_price = headline − Σ(default component price, one per choice group)`, every choice group `dynamic_price`, `is_default: true` inside `config` on each intended default.\n- **Show the arithmetic per bundle.** Default configuration must land exactly on the headline.\n- **Assert `base >= 0`.** A negative base is normal for value bundles priced below the sum of their parts. Resolve it by honouring the source's declared default (usually a smaller/cheaper component). If it is STILL negative, **stop and escalate** — do not clamp to zero, do not substitute a different default to make the sum work.\n- Do NOT plan per-item deltas with a `0.00` base item: `0.00` is treated as unset and falls back to the variant's own price, which double-charges. Do not plan `config.country_prices` — 500 as an object, silently dropped as an array.\n- Optional `dynamic_price` groups raise the advertised floor by their cheapest item; flag any for explicit operator acceptance.\n\n**Census before any batch.** Flag every candidate whose base is negative or zero, that carries an explicit price-increment mechanism, whose group count or min/max differs from the proven shape, or whose anchor is ambiguous. Anything unresolved is **skipped and named**, never guessed.\n\nSTEP_OUTPUT: the plan; per bundle the base arithmetic (headline, each default, resulting base) and the assertion that base >= 0; the census with any skipped candidates named.",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "Every planned bundle shows its base arithmetic explicitly: headline price, each choice group's default component price, and the resulting anchor base.",
+        "Every planned bundle asserts base >= 0. Any negative base is either resolved by honouring the source's declared default (shown) or escalated — clamping to zero or silently swapping the default is a FAIL.",
+        "No plan uses a 0.00 item price as an intended-free component, and none uses config.country_prices.",
+        "Any group that would raise the advertised floor is called out for operator acceptance rather than buried.",
+        "A census is present naming every candidate that is being skipped and why.",
+        "No write calls were made in this step."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "strict",
+        "onFail": "stop"
+      },
+      "dependsOn": [
+        "study-company",
+        "source-analysis"
+      ],
+      "maxReworkRounds": 2
+    },
+    {
+      "id": "write-bundles",
+      "name": "Write the bundle records",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\n**APPROVAL GATE — two locks, and `context.approved` is only the first.**\n\n`context.approved` is fixed when `run_workflow` is called, which is BEFORE this run produced a plan. It authorises the run to be capable of writing; it is not consent to the specific plan `plan-translation` just produced. So:\n\n1. If `context.approved` is not exactly `true`, emit `STEP_OUTPUT: not approved; no writes performed` and STOP.\n2. Then call **`human_in_the_loop`** with the plan's actual numbers — per bundle: headline, the base arithmetic, and the before → intended-after price span — and get explicit approval of THAT before the first write. This is the lock that matters, because it is the only one a human sees the plan behind.\n3. If `human_in_the_loop` is unavailable in this build, do NOT treat that as approval. Write nothing, emit the plan and `STEP_OUTPUT: approval mechanism unavailable; no writes performed`, and stop.\n\nMoney is involved and these writes change advertised shelf prices.\n\nWrite through **Surface A only** — `POST /api/company/v1/products/create_bundle_product` and `PATCH /api/company/v1/products/{id}/update_bundle_product`. Never `/api/v2025-06/bundles` for writes.\n\nThe write contract (SKILL.md §5a carries the full table if the playbook is unreachable):\n- `product.title` is required on **every** call, even a pricing-only update.\n- **Create = ONE call. Convert = TWO** — on `update_bundle_product`, `bundle: true` does not persist alongside groups; a second groups-free `{id, title, bundle: true, status}` call is required.\n- Teardown (`option_attrs: []`, master repriced to `0.0` via `variant_countries_attributes[].id`, `_destroy` per non-master variant) goes in the SAME call as the groups.\n- `is_default` goes **inside `config`**; at top level it is silently dropped.\n- Items are **append-only**; omitted items are kept.\n- (group, variant) is unique — re-sending an existing variant 422s the whole request atomically.\n- **Group-level `_destroy` returns 404.** Item-level works; repointing `variant_id` on an item by `id` works and is how you fix a wrong pointer.\n- `images_attributes` appends; send `_destroy` with the old id when swapping.\n- Route each product immediately after its flag call, before starting the next.\n\n**Verify from a fresh `GET`, never from the PATCH echo.** An echo showed `$52.00` on an all-fixed kit that a fresh GET returns as `0.0` two days later with the stored config byte-identical. The echo is not evidence.\n\nSTEP_OUTPUT: per product — id, is_bundle, group count, the fresh-GET price_range, template id, and whether it was create (1 call) or convert (2 calls).",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "If context.approved was not true, NOTHING was written and the report says so. Otherwise every criterion below applies.",
+        "Every reported value comes from a fresh GET issued AFTER the write, not from the PATCH response echo. A report that quotes only echo values is a FAIL.",
+        "For every written product the report quotes is_bundle: true and an actual price_range from that fresh GET, and interprets it correctly — a $0.00 range on an all-fixed bundle is expected and must be named as such, not reported as a defect or as verification.",
+        "Each converted product shows the two-call sequence; each created product shows the single create call.",
+        "Every written product has a non-null application_theme_template_id confirmed via GET /api/application_theme_templates/{id}/available_themeables.",
+        "No writes were made through /api/v2025-06/bundles.",
+        "Approval was obtained through human_in_the_loop AFTER the plan existed and BEFORE the first write, and the report shows the figures that were put in front of the human. Treating context.approved alone as consent to the plan is a FAIL — it is fixed before the plan exists."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "strict",
+        "onFail": "stop"
+      },
+      "dependsOn": [
+        "plan-translation"
+      ],
+      "maxReworkRounds": 2,
+      "runIf": {
+        "flag": "approved"
+      }
+    },
+    {
+      "id": "picker-section",
+      "name": "Build the picker section",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nInstall the reusable bundle section. ONE implementation must render every current and future bundle — no per-bundle templates. Follow `playbooks/10-ui-and-price-surfaces.md`, which supersedes `03-theme-generation.md` on card rendering.\n\nCopy the skill's `templates/` artefacts into the theme and adapt ONLY what the study step recorded about the host theme (token lineage, container mechanism, button/list resets). If `templates/` is still absent after `run_skill`, say so in STEP_OUTPUT and build to the contract in SKILL.md rather than inventing one.\n\nNon-negotiables:\n- Detect a bundle with `product.product_bundle_groups.size > 0`. Not `is_bundle`, not `slug`/`handle`, not `bundle_in_stock`.\n- **Never pin `bundle_product` on a `product/*` template.**\n- Read exclusivity from `product.bundle_config.mutually_exclusive_groups` (holds `sort_order`s, not ids; `null` not `[]` on older bundles).\n- **One card per parent product, not per item.** Group items by `item.product_id`. A group holding three variants of one product must render ONE card with a variant sub-picker — not three identical cards. Sub-picker labels come from the variant's own option values, never a hardcoded size list. Product + option must resolve to exactly one variant_id.\n- **Use the variant's image**, falling back to the parent only when absent, and swap it when the sub-picker changes.\n- **The anchor item is never visually subordinate to the options.** Derive its size from the same sizing token as the option grid so they cannot drift; roughly 1.25x an option thumbnail.\n- Build `bundled_items` tagging EVERY entry with `product_bundle_group_id`, collapsing duplicate variants into `quantity`, and **omitting every `included` group** except an exclusive-pair member. A product whose only group is `included` sends NO `bundled_items`.\n- Add-to-cart must be ENABLED when every group is `included` or optional — a fixed kit has nothing to select, and gating on 'all required groups chosen' leaves every kit unclickable while the API looks healthy.\n\nSTEP_OUTPUT: files written, the detection expression, the grouping/sub-picker approach, anchor sizing token, and the CTA-enablement rule.\n\n**Before touching a single file, confirm you are in the right theme.** Read the theme id of the checkout you are in and compare it to the active theme id from `preflight`. Mist picked this project from the run's initial `context.theme_id`, or — if that was absent — by taking the first local theme checkout or scaffolding a new one, so being in the wrong theme is a live failure mode, not a hypothetical. If they do not match, STOP and report both ids. Do not 'fix' it by switching the active theme; routing is theme-scoped and that silently un-routes every bundle.",
+      "target": {
+        "type": "kind",
+        "kind": "theme",
+        "fallbackToManager": true
+      },
+      "acceptance": [
+        "The theme checkout's own id is quoted and matches the active theme id from preflight. An unverified assumption that this is the right theme is a FAIL.",
+        "The section, JS, CSS and host template exist in the theme and the report names each path.",
+        "Bundle detection uses product.product_bundle_groups.size > 0 — the report quotes the expression.",
+        "Cards are grouped by parent product id with a variant sub-picker for multi-variant products — the report shows the grouping code or expression, and confirms one product contributing N variants yields ONE card.",
+        "Sub-picker labels derive from variant option values, with no hardcoded size/tier list anywhere in the section.",
+        "The anchor item's size derives from the same token as the option grid, and the report states both resulting sizes.",
+        "The cart payload builder tags every entry with product_bundle_group_id, collapses duplicates into quantity, and skips included groups except exclusive members.",
+        "The report confirms a product whose only group is included yields an ENABLED CTA and an empty bundled_items array."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "write-bundles"
+      ],
+      "maxReworkRounds": 2,
+      "runIf": {
+        "flag": "approved"
+      }
+    },
+    {
+      "id": "price-surfaces",
+      "name": "Inventory and wire every price surface",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nA bundle page is not one price. On the reference storefront the host template composed FOUR sections, only one was wired to the selection engine, the PDP header rendered no price at all, and listing cards rendered a scalar where a bundle needs a range.\n\n1. **Inventory first.** Enumerate every surface that shows a price for a bundle: PDP header/hero, each composed section on the product template, sticky CTA bars, listing/collection/search cards, cart page, cart drawer, mini-cart.\n2. **Classify each**: must update live | should show a range or 'from' | correct as-is | should not render a price.\n3. **Wire from one computed source of truth.** Live surfaces subscribe to the engine's total. Never a second parallel calculation — that is how two numbers on one page drift apart. Surfaces outside the section need an explicit data-attribute hook, not a cross-section CSS selector.\n4. Server-rendered surfaces that cannot update show a **range or 'from'** price.\n5. **First paint must equal the default configuration** or the page visibly flickers from a wrong number to the right one.\n6. Remember `price_range` reads **$0.00** for an all-fixed bundle. Do not wire a surface to it without checking that bundle's pricing shape.\n\nSTEP_OUTPUT: the inventory table (surface → classification → treatment applied), and the source of truth every live surface reads from.\n\n**Before touching a single file, confirm you are in the right theme.** Read the theme id of the checkout you are in and compare it to the active theme id from `preflight`. Mist picked this project from the run's initial `context.theme_id`, or — if that was absent — by taking the first local theme checkout or scaffolding a new one, so being in the wrong theme is a live failure mode, not a hypothetical. If they do not match, STOP and report both ids. Do not 'fix' it by switching the active theme; routing is theme-scoped and that silently un-routes every bundle.",
+      "target": {
+        "type": "kind",
+        "kind": "theme",
+        "fallbackToManager": true
+      },
+      "acceptance": [
+        "The theme checkout's own id is quoted and matches the active theme id from preflight. An unverified assumption that this is the right theme is a FAIL.",
+        "An inventory table is present naming every price surface found, each with a classification and the treatment applied — not a general statement that prices were wired.",
+        "All live surfaces read from a single computed total; the report names it and confirms no second parallel calculation exists.",
+        "Surfaces outside the section are hooked by explicit data attributes, not cross-section CSS selectors.",
+        "The report confirms first paint equals the default configuration.",
+        "Any surface wired to price_range is confirmed to belong to a bundle whose pricing shape makes that value meaningful."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "picker-section"
+      ],
+      "maxReworkRounds": 2,
+      "runIf": {
+        "flag": "approved"
+      }
+    },
+    {
+      "id": "route-and-render",
+      "name": "Route and render every bundle",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nFor every bundle product confirm it is routed to the bundle template on the ACTIVE theme and that the picker actually renders at the product's own canonical URL.\n\n1. `GET /api/application_theme_templates/{template_id}/available_themeables?per_page=200` — every bundle product must appear with a non-null `application_theme_template_id`.\n2. Load each bundle's `canonical_url`, copied verbatim from the product response and never composed from a slug, and confirm the group UI renders.\n3. **Warn in the report** that routing is per-product and per-ACTIVE-theme: switching or cloning the active theme silently un-routes every bundle and this step must be re-run.\n\nA bundle on a bundle-unaware theme is a silent revenue hole: normal-looking page, working native add-to-cart, hard failure at checkout.\n\nSTEP_OUTPUT: per bundle — canonical_url, routed yes/no, picker renders yes/no, plus the theme-switch warning.\n\n**Before touching a single file, confirm you are in the right theme.** Read the theme id of the checkout you are in and compare it to the active theme id from `preflight`. Mist picked this project from the run's initial `context.theme_id`, or — if that was absent — by taking the first local theme checkout or scaffolding a new one, so being in the wrong theme is a live failure mode, not a hypothetical. If they do not match, STOP and report both ids. Do not 'fix' it by switching the active theme; routing is theme-scoped and that silently un-routes every bundle.",
+      "target": {
+        "type": "kind",
+        "kind": "theme",
+        "fallbackToManager": true
+      },
+      "acceptance": [
+        "The theme checkout's own id is quoted and matches the active theme id from preflight. An unverified assumption that this is the right theme is a FAIL.",
+        "Every bundle product is confirmed routed via available_themeables, quoted per product.",
+        "Every bundle's canonical_url was loaded this turn and the report states per product whether the picker rendered — not in aggregate.",
+        "Every URL in the report was copied from an API response, not composed from a slug.",
+        "The report carries the explicit warning that a theme switch or clone un-routes every bundle."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "price-surfaces"
+      ],
+      "maxReworkRounds": 2,
+      "runIf": {
+        "flag": "approved"
+      }
+    },
+    {
+      "id": "cart-and-money",
+      "name": "Prove add-to-cart and the money path",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\n**Valid bundle config is NOT evidence the storefront can sell it.** In the reference campaign a six-group bundle read back perfectly and still failed for every shopper.\n\nCart creation needs BOTH `fluid_shop` and a top-level **`country_code`** — omitting the latter is `422 country_code is missing`.\n\nPOST /api/checkout/v2026-04/carts\n{ \"fluid_shop\": \"<subdomain>\", \"country_code\": \"<ISO>\", \"items\": [ { \"variant_id\": <master>, \"quantity\": 1, \"bundled_items\": [ ... ] } ] }\n\nTest matrix, per bundle:\n1. **Default** configuration — total must equal the headline price exactly.\n2. **One upgrade** — total must move by exactly the component delta.\n3. **One downgrade** — same, downward.\n4. **Negative case** — send a variant that is NOT in the group; it must be rejected. This is what proves membership is enforced rather than merely looking right.\n\nFor a **pure fixed kit** send **NO `bundled_items` at all**. For configurable bundles send `customizable` groups ONLY — an `included` group returns `400 product_bundle_group_id <id> must reference a customizable group or an exclusive included group`. The cart attaches included components itself.\n\n**Read every cart back.** `200` + `$0.00` total + empty `items[].errors` is a documented silent failure and it is real. Inspect `items[].errors` and any top-level `skipped_items`.\n\nFinally exercise the UI: click through one configurable bundle and one fixed kit in the browser, confirm the CTA is enabled and the cart line matches the page. Read console and server logs.\n\nSTEP_OUTPUT: per tested configuration — payload shape, HTTP status, amount_total, bundle_selection_key, and pass/fail against the expected total.\n\n**Before touching a single file, confirm you are in the right theme.** Read the theme id of the checkout you are in and compare it to the active theme id from `preflight`. Mist picked this project from the run's initial `context.theme_id`, or — if that was absent — by taking the first local theme checkout or scaffolding a new one, so being in the wrong theme is a live failure mode, not a hypothetical. If they do not match, STOP and report both ids. Do not 'fix' it by switching the active theme; routing is theme-scoped and that silently un-routes every bundle.",
+      "target": {
+        "type": "kind",
+        "kind": "theme",
+        "fallbackToManager": true
+      },
+      "acceptance": [
+        "The theme checkout's own id is quoted and matches the active theme id from preflight. An unverified assumption that this is the right theme is a FAIL.",
+        "Successful POST /api/checkout/v2026-04/carts calls are reported for at least ONE configurable bundle AND at least ONE pure fixed kit, with the actual amount_total quoted for each. Testing only one shape is a FAIL.",
+        "The default configuration's amount_total equals the headline price exactly, and the arithmetic is shown.",
+        "At least one upgrade and one downgrade were carted, and each total moved by exactly the expected component delta.",
+        "A negative case was attempted — a variant not in the group — and was rejected. Omitting this is a FAIL, because nothing else proves membership is enforced.",
+        "The fixed-kit request demonstrably sent NO bundled_items, and no successful request included a bundled_items entry for an included group except a documented exclusive-pair member.",
+        "items[].errors and skipped_items were inspected and reported — an empty errors array is stated explicitly rather than assumed to mean success.",
+        "A browser add-to-cart was exercised for one configurable bundle and one fixed kit, with console and server logs read, and page total == cart total confirmed."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "strict",
+        "onFail": "continue",
+        "requiredTools": [
+          {
+            "tool": "fluid_api",
+            "minSuccessfulCalls": 3,
+            "input": {
+              "path": "/api/checkout/v2026-04/carts"
+            },
+            "distinctBy": [
+              "body"
+            ]
+          }
+        ]
+      },
+      "dependsOn": [
+        "route-and-render"
+      ],
+      "maxReworkRounds": 3,
+      "runIf": {
+        "flag": "approved"
+      }
+    },
+    {
+      "id": "reusability-and-report",
+      "name": "Reusability proof and final report",
+      "prompt": "**First, call `run_skill(\"themes/dynamic-bundles\")` and follow it.** A workflow step runs in its own chat and does NOT inherit the launching skill's materialized files — without this call `SKILL.md`, `playbooks/`, `templates/` and `schemas/` are not on disk and every path below is a dead reference. If the call fails, say so explicitly in STEP_OUTPUT and work from this prompt alone; do not silently proceed as though you had read them.\n\nProve the implementation is general, not fitted to one product, then report honestly.\n\n1. **Reusability proof:** confirm the same section renders a bundle it was not built against — a second existing bundle with a different group shape, or a scratch bundle created and then removed. **Delete the Bundle row BEFORE the Product**; the reverse order leaves an orphan whose DELETE then 500s forever.\n2. Write the manifest.\n3. Final report in four parts: what was built · what was verified and how · what was NOT verified · what a human must decide.\n\nSeparate observed facts from inference. If products were never driven through the cart, say so rather than implying they were. If an advertised price moved, name the product and both numbers. If a playbook or template was unreachable, name it — that is a portability finding worth recording, not an embarrassment.\n\nSTEP_OUTPUT: manifest path, reusability evidence, and the four-part report.",
+      "target": {
+        "type": "manager"
+      },
+      "acceptance": [
+        "The same theme implementation is shown rendering at least two bundles with different group shapes, named by id.",
+        "A manifest was written that validates against schemas/bundle-manifest.schema.json.",
+        "The final report has a distinct 'not verified' section naming every claim that rests on inference rather than a call made this run.",
+        "Any advertised price change is reported with the product and both before and after values.",
+        "If a scratch bundle was created for the reusability proof, the report confirms the Bundle row was deleted before the Product.",
+        "Any unreachable playbook, template or reference file is named explicitly.",
+        "If the run was not approved and the mutating steps were condition-skipped, the report says exactly that and names what WOULD have been written — and the reusability criteria above do not apply. A skipped write reported as a completed one is a FAIL."
+      ],
+      "qa": {
+        "enabled": true,
+        "strictness": "standard",
+        "onFail": "continue"
+      },
+      "dependsOn": [
+        "cart-and-money"
+      ],
+      "maxReworkRounds": 2
+    }
+  ]
+}