Wayfinder: chart the Shopify headless commerce map

The route from "mozimo.in displays Shopify products" to "mozimo.in sells them",
as a plan with a phase spine and gates, plus the open decision tickets that
still shape it and the evidence they rest on.

- .scratch/shopify-headless-commerce/: plan.md (phases and gates), map.md (the
  wayfinder map), 10 open decision tickets
- CONTEXT.md: Storefront / Theme store / Cart / Parity vocabulary
- docs/adr/0001-0003: Checkout stays Shopify-hosted, one Variant per product,
  the checkout domain stays shop.mozimo.in
- docs/research/ and docs/shopify-catalog-inventory.md: verified store facts,
  the Cart API probe, and the catalogue inventory

Raw Shopify doc scrapes under .scratch/shopify-research/ are ignored: they are
working material, not record.

.scratch/shopify-headless-commerce/issues/01-seed-dev-store.md

@@ -0,0 +1,44 @@
+# Seed the dev store from the live catalogue
+
+`Type:` task (HITL)
+`Status:` open
+
+Part of [the map](../map.md). Empty the frontier from the top.
+
+## Question
+
+The dev store `staging-iw0gviik.myshopify.com` is empty. How does it come to hold the live catalogue faithfully, so that Phase 1 Cart work is built against realistic data?
+
+The manual CSV route was chosen for this. Verification has now shown exactly where it holds and where it **cannot**:
+
+### ✅ Products, and product metafields with preparation
+
+- Export: **Products → Export** → scope → *Plain CSV* or *CSV for Excel/Numbers* → **Export products**. One file. Note that an **All products export is emailed**, not downloaded.
+- Import: **Products → Import** → add file → *Overwrite products with matching handles* → **Import products**.
+- Product metafields **do** ride in the CSV as their own columns, named `<Name> (product.metafields.<namespace>.<key>)`. `custom.ingredients` as multi-line text and `custom.energy_kcal` as a number are both documented-supported types.
+- **Precondition:** the metafield **definitions must already exist in the destination store** (Settings → Custom data → Products). Shopify's docs only promise columns for *defined* metafields. What happens to an undefined metafield's value is undocumented — so create the definitions before importing, not after.
+- Hazards: with *Overwrite* on, a **blank metafield cell overwrites the destination value as blank**. Images are URLs only and Shopify re-hosts them at import, so production's products and images must stay publicly reachable until the import finishes. There is **no dry run**, imports cannot be cancelled, there is no import history, and the file cap is 15 MB.
+
+### ❌ Collection membership — impossible by CSV
+
+The `Collection` column is **never exported**, and on import it is the only column you may add — and it admits **one collection per product**. Most of this catalogue belongs to three or four collections each: `mozimo-carnival-celebration-m` is in `best-sellers`, `gift-collection`, `diwali` and `hampers-boxes` at once. Sixteen collections and their multi-membership therefore need a **second mechanism**.
+
+This part re-opens the seeding decision, because the chosen route cannot finish the job alone.
+
+### ⚠️ Variant option shape — read the real export
+
+Shopify's docs say a one-option product should carry `Default Title` in `Option1 value`, while the **official sample CSV represents its single-option product as `Option1 name = Title`, `Option1 value = Premium`** — which is exactly this catalogue's stored shape. The docs and their own sample disagree, and the documented hazards around *changing* option values (variants are deleted and recreated, so IDs change) make this worth confirming rather than assuming. Exporting from production settles it, and that export is needed anyway.
+
+## To resolve
+
+1. Export the full catalogue from production and record what `Option1 name` / `Option1 value` actually contain.
+2. Create the metafield definitions in the dev store before importing.
+3. Run a **small-batch import with *Overwrite* off** to surface per-line errors cheaply, then the full set.
+4. Decide the second mechanism for collection membership — admin bulk-editor passes, or a small Admin API script using the credentials the repo already mints. Record which was chosen and why.
+5. Record what actually landed: product count, collection count and membership, metafield coverage, anything rebuilt by hand.
+
+Facts later tickets depend on: which products exist in the dev store, whether their Variant GIDs differ from production's (they will), and whether the metafield values survived.
+
+## Answer
+
+<!-- filled on resolution -->