claude-code-arcane 1.2.0 → 1.4.0

package/skills/cart-checkout/references/checkout-flow-spec.md

@@ -0,0 +1,50 @@
+# Checkout Flow — Step-by-Step Spec
+
+A platform-agnostic reference for a correct, conversion-optimized checkout. Adapt step granularity to your catalog (digital/low-SKU can collapse steps).
+
+## Steps, Fields & Validation
+
+| Step | Fields | Validation / behavior |
+|------|--------|-----------------------|
+| **Cart** | line items, qty, totals | Editable qty; re-price + re-check stock server-side on load |
+| **Identity** | email (required), login/guest | Collect email first; offer guest checkout prominently |
+| **Shipping address** | name, address, country, postal | Inline validation; address autocomplete if available |
+| **Shipping method** | method options + rates | Recompute on address change; show ETA + cost |
+| **Payment** | payment method | Tokenized/hosted fields; idempotency key generated here |
+| **Review** | full summary | Final total incl. tax/shipping/discounts before pay button |
+| **Confirmation** | order number | Show + email receipt; clear cart; fire `purchase` event |
+
+## Server-Side Re-Validation (before charge)
+Always recompute, never trust the client:
+1. Item availability (reserve with TTL)
+2. Prices (current catalog prices, not cart-stored)
+3. Promotions (re-evaluate eligibility + caps)
+4. Shipping + tax (against final address)
+5. Final total → only then create the payment intent
+
+## Error Handling
+- Never clear entered fields on a validation error.
+- Show errors inline next to the field, plus a summary.
+- Payment decline → keep the order in a recoverable state; let the shopper retry without re-entering everything.
+- Stock lost during checkout → tell the shopper exactly which line and offer alternatives.
+
+## Address Validation
+- Normalize country to ISO code; postal format per country.
+- Soft-validate (suggest correction) rather than hard-block where possible.
+
+## Abandoned-Cart Triggers
+| Touch | Timing | Content |
+|-------|--------|---------|
+| 1 | ~1h | "You left these" + cart contents |
+| 2 | ~24h | Objection handling, reviews, support offer |
+| 3 | ~72h | Incentive (only if margin allows) |
+
+Suppress all touches once `purchase` fires. Respect consent + frequency caps.
+
+## Verdict: READY when
+- [ ] Guest checkout works end-to-end
+- [ ] Email captured before payment
+- [ ] All totals recomputed server-side pre-charge
+- [ ] Payment is idempotent (no double-charge on retry/double-click)
+- [ ] Entered data survives validation errors
+- [ ] `purchase` event fires once with transaction id

package/skills/cold-outreach/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: cold-outreach
+description: "Write cold LinkedIn/email messages from a job-seeker to recruiters, hiring managers and referrals — plus post-application follow-up sequences that get replies. For B2B sales outreach use cold-email instead. Triggers: mensaje en frio recruiter, escribirle a un reclutador, follow up postulacion, networking message, pedir referido, contactar hiring manager."
+argument-hint: "[contact-note | recruiter + company]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch
+---
+
+# Cold Outreach — Job-seeker → Recruiter / Hiring Manager
+
+Escribís mensajes en frío de un **candidato** a recruiters, hiring managers y referidos, y secuencias de **follow-up** post-aplicación que reciben respuesta. Esto NO es venta B2B (para eso está `/cold-email`) — el ángulo es conseguir una conversación o un referido, sin sonar a spam ni a desesperación.
+
+## Cuándo usar cada variante
+
+| Situación | Mensaje |
+|-----------|---------|
+| Recruiter posteó un rol | Mensaje corto con fit + interés explícito |
+| Hiring manager / futuro lead | Mensaje de valor: qué resolvés que a su equipo le importa |
+| Pedir un referido a alguien de la empresa | Cálido, bajo compromiso, fácil de decir que sí |
+| Networking sin rol abierto | Curiosidad genuina + algo en común, sin pedir nada todavía |
+| Follow-up post-aplicación | Recordatorio con valor, no "¿alguna novedad?" |
+
+## Principios
+
+- **Personalizá la primera línea.** Algo real de esa persona/empresa/rol. Si sirve para 100 personas, no sirve para ninguna.
+- **Corto.** LinkedIn: 50–125 palabras. La connection note: <300 caracteres.
+- **Una pregunta / un CTA.** Bajá la fricción de responder.
+- **Vos resolvés algo para ellos**, no "estoy buscando trabajo, ¿me ayudás?". El foco es el valor que aportás al equipo.
+- **Sin paredes de texto, sin CV adjunto en el primer toque** (salvo que lo pidan).
+- **Respetá el "no".** Un follow-up, máximo dos. Nunca insistir agresivo.
+
+## Estructura de un primer mensaje
+
+1. **Gancho personal** (1 línea): por qué *a esta persona*.
+2. **Quién sos + fit** (1–2 líneas): rol + el logro más relevante para ellos.
+3. **CTA suave** (1 línea): ¿15 min para charlar? / ¿abierto a una intro? / dejé mi aplicación, encantado de dar contexto.
+
+## Secuencia de follow-up post-aplicación
+
+- **Día 0** — aplicación enviada (+ mensaje al recruiter/hiring manager si tenés el contacto).
+- **Día 4–5** — follow-up 1: reafirmá interés + agregá *algo nuevo* (un proyecto relevante, una idea sobre su producto). No "¿novedades?".
+- **Día 10–12** — follow-up 2 (último): breve, profesional, dejá la puerta abierta. Si no hay respuesta, cerrás el loop con dignidad.
+
+Cada follow-up debe tener un **gancho propio** y leerse solo, sin depender de los anteriores.
+
+## Proceso
+
+1. Leer la nota de `05-Contactos/` (o crearla) y la de `04-Empresas/`.
+2. Investigar a la persona (rol, equipo, algo reciente) — WebFetch del perfil público si hay URL.
+3. Elegir variante + canal.
+4. Draftear mensaje + 1 variante de apertura.
+5. Registrar en `05-Contactos/` (historial de interacciones) y planificar el follow-up.
+
+> Nota: Claude no accede a tu LinkedIn ni envía mensajes — redacta para que vos copies/pegues y registres la interacción.
+
+## Idioma
+
+Espejá el idioma de la persona/empresa. Inglés por default para roles internacionales.
+
+Ver `references/recruiter-playbook.md` para plantillas por situación y la psicología de por qué responden.
+
+## Handoff
+
+Pedí aprobación (approval) antes de escribir en `05-Contactos/`. Cuando el mensaje está READY para copiar/pegar y el follow-up agendado, prepará la conversación con `/interview-prep` si hay respuesta.

package/skills/cold-outreach/references/recruiter-playbook.md

@@ -0,0 +1,65 @@
+# Recruiter / Hiring Manager Playbook
+
+Plantillas y psicología para outreach de candidato. Adaptá siempre la primera línea — las plantillas son esqueleto, no copy-paste.
+
+## Por qué responden (y por qué no)
+
+Responden cuando: el mensaje es corto, claro sobre el fit, fácil de responder, y se nota que es para *ellos*. No responden cuando: es genérico, largo, pide demasiado de entrada, o suena desesperado. El recruiter recibe decenas por día — el filtro es "¿esto me ahorra trabajo o me lo agrega?".
+
+## Plantillas
+
+### 1. Recruiter que posteó un rol
+```
+Hola {nombre}, vi que están buscando {rol} en {empresa}.
+Soy {rol/seniority} con {logro relevante en 1 línea, con número}.
+Me interesa especialmente {algo real del rol/empresa}.
+¿Te sirve si te paso mi CV o coordinamos 15 min?
+```
+
+### 2. Hiring manager / futuro lead (mensaje de valor)
+```
+Hola {nombre}, sigo {producto/equipo de la empresa} y me llamó {detalle específico}.
+Vengo de {contexto}: {logro mapeado a lo que su equipo necesita}.
+Apliqué a {rol}; si te viene bien, encantado de darte contexto en una charla corta.
+```
+
+### 3. Pedir un referido (a alguien del equipo)
+```
+Hola {nombre}, vi que trabajás en {empresa} como {rol}.
+Estoy aplicando a {rol} ahí y me encantaría tu perspectiva sobre el equipo.
+Si te parece y te hace sentido, ¿estarías abierto a referirme? Sin problema si no.
+Te dejo mi perfil para que veas si encaja: {link}.
+```
+
+### 4. Connection note (<300 chars)
+```
+Hola {nombre}, me interesa mucho {empresa/área}. Vengo de {1 cosa}.
+Me encantaría conectar y, si surge, charlar sobre {rol/equipo}.
+```
+
+### 5. Follow-up 1 (día 4–5) — con valor nuevo
+```
+Hola {nombre}, te escribo para reafirmar mi interés en {rol}.
+Sumo un dato: {proyecto/idea relevante para su producto}.
+Quedo a disposición para lo que necesiten del proceso.
+```
+
+### 6. Follow-up 2 (día 10–12) — cierre digno
+```
+Hola {nombre}, entiendo que están con mucho.
+Dejo la puerta abierta por si avanza {rol}; me encantaría sumar.
+¡Gracias por el tiempo!
+```
+
+## Reglas de cadencia
+
+- Máximo 2 follow-ups. Después, soltar.
+- Cada follow-up agrega algo (no "¿novedades?").
+- Espaciar 4–5 días. Nunca el mismo día ni días consecutivos.
+- Registrar cada toque en la nota de `05-Contactos/`.
+
+## Tono
+
+- Cálido y profesional, nunca servil ni agresivo.
+- Confiado: estás ofreciendo valor, no mendigando.
+- Humano: escribí como hablás, sin jerga corporativa vacía.

package/skills/commerce-analytics/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: commerce-analytics
+description: "Define and audit e-commerce analytics — conversion rate, AOV, CLV, cohort/funnel metrics, and the standard GA4 ecommerce event spec (view_item, add_to_cart, begin_checkout, purchase). Includes a dataLayer event validator. Triggers: defining commerce KPIs, instrumenting GA4 ecommerce events, auditing tracking."
+argument-hint: "[kpis | events | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Commerce Analytics
+
+You cannot optimize what you mis-measure. Define the KPIs that actually move a store and instrument the standard ecommerce event spec correctly — platform-agnostic, with a validator for GA4 dataLayer events.
+
+## Before Starting
+
+Gather: current tracking (GA4/GTM/other), business model (one-time vs subscription), key conversion actions, and goal (define KPIs, design/instrument events, or audit existing tracking).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **KPIs** | `kpis` | KPI framework + dashboard spec |
+| **Events** | `events` | Ecommerce event taxonomy + dataLayer spec |
+| **Audit** | `audit` | Tracking gap + data-quality review |
+
+---
+
+## Phase 1 — Core KPIs
+
+| Metric | Formula | Watch for |
+|--------|---------|-----------|
+| **Conversion rate** | orders / sessions | Segment by device/channel |
+| **AOV** | revenue / orders | Moves with promos/bundles |
+| **CLV** | avg order value × frequency × lifespan | The number that justifies CAC |
+| **Cart abandonment** | 1 − (checkouts / carts) | Diagnoses checkout friction |
+| **Repeat rate** | repeat customers / total | Retention health |
+| **Sell-through** | units sold / units received | Feeds `inventory-stock` forecasts |
+
+**Rule:** Pair every acquisition metric with a margin metric — revenue growth on negative contribution margin is a trap.
+
+---
+
+## Phase 2 — The Ecommerce Event Spec
+
+The standard GA4 ecommerce funnel events, each carrying `currency` + an `items[]` array:
+
+`view_item_list → view_item → add_to_cart → begin_checkout → add_shipping_info → add_payment_info → purchase` (plus `remove_from_cart`, `refund`).
+
+Each `items[]` entry: `item_id`, `item_name`, `price`, `quantity` (+ optional `item_brand`, `item_category`, `item_variant`). `purchase` also needs `transaction_id` and `value`.
+
+Validate a captured dataLayer against this spec:
+
+```bash
+python skills/commerce-analytics/scripts/ga4_ecommerce_validate.py            # demo events
+python skills/commerce-analytics/scripts/ga4_ecommerce_validate.py events.json
+```
+
+It reports PASS/FAIL per event with the missing required fields. For the full taxonomy and parameter reference, see [references/ga4-ecommerce-events.md](references/ga4-ecommerce-events.md).
+
+---
+
+## Phase 3 — Audit & Data Quality
+
+Common faults: missing `transaction_id` (duplicate purchases), `value` excluding/including tax inconsistently, `items[]` absent on purchase, double-firing (GTM + hardcoded). Cross-check store revenue vs GA4 revenue — variance > 5% means a tracking bug.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| KPIs | KPI framework + dashboard layout |
+| Events | Event taxonomy + dataLayer spec |
+| Audit | Gap analysis + data-quality scorecard |
+
+Commerce tracking is **COMPLIANT** when the full funnel fires with valid `items[]` and `currency`, `purchase` carries a unique `transaction_id`, revenue reconciles within 5%, and KPIs pair growth with margin.
+
+---
+
+## Related Skills
+
+- **analytics-tracking**: general GA4/GTM setup this builds on for SaaS-style funnels.
+- **inventory-stock**: sell-through metrics feed restock forecasting.
+- **commerce-data-model**: item taxonomy maps to `items[]` parameters.
+- **ab-test-setup** / **campaign-analytics**: experimentation and campaign measurement.

package/skills/commerce-analytics/references/ga4-ecommerce-events.md

@@ -0,0 +1,63 @@
+# GA4 Ecommerce Event Taxonomy & Parameter Reference
+
+The standard funnel. Fire these with a consistent `items[]` shape so reports, funnels, and audiences work. The `ga4_ecommerce_validate.py` script checks a captured dataLayer against this spec.
+
+## The funnel
+```
+view_item_list → view_item → add_to_cart → view_cart → begin_checkout
+  → add_shipping_info → add_payment_info → purchase
+```
+Plus: `select_item`, `remove_from_cart`, `refund`.
+
+## Required parameters per event
+| Event | Required (beyond items[]) |
+|-------|---------------------------|
+| view_item | currency |
+| add_to_cart / remove_from_cart / view_cart | currency |
+| begin_checkout | currency |
+| add_shipping_info | currency |
+| add_payment_info | currency |
+| purchase | currency, value, transaction_id |
+| refund | currency, transaction_id |
+| view_item_list / select_item | (item_list_id / item_list_name recommended) |
+
+## items[] object
+| Field | Req? | Notes |
+|-------|------|-------|
+| item_id | yes | Map to SKU |
+| item_name | yes | Product/variant name |
+| price | recommended | Unit price (number) |
+| quantity | recommended | Defaults to 1 |
+| item_brand | optional | |
+| item_category | optional | Up to item_category5 |
+| item_variant | optional | e.g. "Red / M" |
+| discount | optional | Per-unit discount |
+| index | optional | Position in list |
+
+## Worked example — purchase
+```json
+{
+  "event": "purchase",
+  "ecommerce": {
+    "currency": "USD",
+    "value": 42.00,
+    "transaction_id": "T-1001",
+    "tax": 3.50,
+    "shipping": 5.00,
+    "items": [
+      { "item_id": "ACME-TEE-RED-M", "item_name": "Acme Cotton Tee",
+        "item_variant": "Red / M", "price": 21.00, "quantity": 2 }
+    ]
+  }
+}
+```
+
+## Common faults (audit checklist)
+- [ ] `purchase` missing `transaction_id` → duplicate purchases on refresh
+- [ ] `value` inconsistent about tax/shipping inclusion (pick one, document it)
+- [ ] `items[]` absent or empty on funnel events
+- [ ] Double-firing (GTM tag + hardcoded gtag)
+- [ ] Currency missing → revenue not attributed
+- [ ] Store revenue vs GA4 revenue variance > 5% → tracking bug
+
+Verdict: **COMPLIANT** when the full funnel fires with valid `items[]` + `currency`, `purchase` has a unique `transaction_id`, and revenue reconciles within 5%.

package/skills/commerce-analytics/scripts/ga4_ecommerce_validate.py

@@ -0,0 +1,134 @@
+"""
+ga4_ecommerce_validate.py — Validate a captured dataLayer against the GA4
+standard ecommerce event spec.
+
+Checks each event for: a known ecommerce event name, required top-level
+parameters (currency/value/transaction_id where applicable), a non-empty
+items[] array, and required per-item fields. No external dependencies.
+
+Usage:
+    python ga4_ecommerce_validate.py                 # built-in demo events
+    python ga4_ecommerce_validate.py events.json     # your captured dataLayer
+
+Input JSON: either a single event object or an array of event objects, each:
+    {"event": "purchase", "ecommerce": {"currency": "USD", "value": 42.0,
+        "transaction_id": "T123", "items": [{"item_id": "SKU1",
+        "item_name": "Tee", "price": 21.0, "quantity": 2}, ...]}}
+
+Some setups put params at the top level instead of under "ecommerce"; both
+shapes are accepted.
+"""
+
+import json
+import sys
+
+
+# event name -> required top-level (ecommerce) params beyond items[]
+EVENT_REQS = {
+    "view_item_list": [],
+    "view_item": ["currency"],
+    "select_item": [],
+    "add_to_cart": ["currency"],
+    "remove_from_cart": ["currency"],
+    "view_cart": ["currency"],
+    "begin_checkout": ["currency"],
+    "add_shipping_info": ["currency"],
+    "add_payment_info": ["currency"],
+    "purchase": ["currency", "value", "transaction_id"],
+    "refund": ["currency", "transaction_id"],
+}
+EVENTS_REQUIRING_ITEMS = set(EVENT_REQS) - {"refund"}
+ITEM_REQUIRED = ["item_id", "item_name"]  # GA4 needs id or name; we require both for quality
+ITEM_RECOMMENDED = ["price", "quantity"]
+
+
+DEMO_EVENTS = [
+    {"event": "view_item", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0}]}},
+    {"event": "add_to_cart", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0, "quantity": 2}]}},
+    {"event": "purchase", "ecommerce": {"currency": "USD", "value": 42.0, "transaction_id": "T-1001",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0, "quantity": 2}]}},
+    # intentionally broken: missing transaction_id + value, item missing name
+    {"event": "purchase", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-MUG", "price": 9.0}]}},
+    {"event": "add_to_cart", "ecommerce": {  # missing currency + empty items
+        "items": []}},
+]
+
+
+def get_ecom(event):
+    """Return the param dict — under 'ecommerce' or at the top level."""
+    if isinstance(event.get("ecommerce"), dict):
+        return event["ecommerce"]
+    return {k: v for k, v in event.items() if k != "event"}
+
+
+def validate_event(event, idx):
+    errors = []
+    name = event.get("event")
+    if not name:
+        return [f"event[{idx}]: missing 'event' name"], None
+    if name not in EVENT_REQS:
+        return [f"event[{idx}] '{name}': not a recognized GA4 ecommerce event"], name
+
+    ecom = get_ecom(event)
+
+    for param in EVENT_REQS[name]:
+        if param not in ecom or ecom[param] in (None, ""):
+            errors.append(f"missing required param '{param}'")
+
+    if name in EVENTS_REQUIRING_ITEMS:
+        items = ecom.get("items")
+        if not isinstance(items, list) or not items:
+            errors.append("missing or empty 'items[]'")
+        else:
+            for i, it in enumerate(items):
+                missing = [f for f in ITEM_REQUIRED if not it.get(f)]
+                if missing:
+                    errors.append(f"items[{i}]: missing {', '.join(missing)}")
+                rec_missing = [f for f in ITEM_RECOMMENDED if it.get(f) in (None, "")]
+                if rec_missing:
+                    errors.append(f"items[{i}]: (recommended) missing {', '.join(rec_missing)}")
+    return errors, name
+
+
+def main():
+    if len(sys.argv) > 1:
+        path = sys.argv[1]
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as e:
+            print(f"[ERROR] cannot read {path}: {e}")
+            sys.exit(1)
+    else:
+        print("[INFO] No JSON given - using built-in demo events.\n")
+        data = DEMO_EVENTS
+
+    events = data if isinstance(data, list) else [data]
+
+    total_fail = 0
+    for idx, event in enumerate(events):
+        errors, name = validate_event(event, idx)
+        hard = [e for e in errors if "(recommended)" not in e]
+        if hard:
+            total_fail += 1
+            print(f"FAIL  [{idx}] {name or '?'}")
+            for e in errors:
+                print(f"        - {e}")
+        else:
+            warn = [e for e in errors if "(recommended)" in e]
+            print(f"PASS  [{idx}] {name}")
+            for w in warn:
+                print(f"        ~ {w}")
+
+    print()
+    passed = len(events) - total_fail
+    verdict = "COMPLIANT" if total_fail == 0 else "NON-COMPLIANT"
+    print(f"{verdict}: {passed}/{len(events)} events passed.")
+    sys.exit(0 if total_fail == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/commerce-data-model/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: commerce-data-model
+description: "Design and audit the core e-commerce domain model — products, variants, SKUs, options, collections, attributes, taxonomy, faceted search and pagination. Language- and platform-agnostic. Triggers: modeling a catalog, reviewing an existing product schema, designing filtering/search."
+argument-hint: "[model | audit | taxonomy]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Commerce Data Model
+
+Design the backbone of any storefront: a product catalog model that survives variants, bundles, localization, and faceted search — independent of language, framework, or database.
+
+> **Note:** This skill may create or modify files in your project (a model spec or schema doc). It will ask before writing.
+
+## Before Starting
+
+Gather: business context (physical/digital/services, single vs multi-vendor, B2C/B2B), scale (SKU count, variant explosion, locales/currencies), and goal (model from scratch, audit an existing schema, or design taxonomy + filtering).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Model** | `model` | Entity model spec: Product, Variant, SKU, Option, Collection, Attribute |
+| **Audit** | `audit` | Gap analysis of an existing schema against commerce best practices |
+| **Taxonomy** | `taxonomy` | Category tree, attribute schema, faceted-search and pagination design |
+
+---
+
+## Phase 1 — Core Entities
+
+The canonical separation that prevents 90% of catalog pain:
+
+| Entity | Is | Is NOT | Key fields |
+|--------|----|--------|-----------|
+| **Product** | The marketing/SEO unit ("Acme Tee") | A buyable thing | title, description, slug, status, brand |
+| **Variant** | A buyable combination ("Tee / Red / M") | A category | option values, price, weight, barcode |
+| **SKU** | The stock-keeping identifier | A variant's price | code, variant_id |
+| **Option** | An axis of variation (Color, Size) | A value | name, position |
+| **Collection** | A merchandising grouping | A taxonomy node | title, rules (manual/automatic) |
+
+**Rule:** Price, inventory, and barcode live on the **Variant**, never the Product. A product with no options still has exactly one variant.
+
+For the full field-level spec, identifiers (GTIN/MPN), bundles/kits, and digital vs physical modeling, see [references/data-model-spec.md](references/data-model-spec.md).
+
+---
+
+## Phase 2 — Attributes & Taxonomy
+
+- **Taxonomy** (category tree): hierarchical, navigational, one primary path per product. Stable URLs.
+- **Collections**: many-to-many merchandising overlays (manual or rule-based). A product lives in one category branch but many collections.
+- **Attributes**: typed key-values (`material: cotton`, `sleeve: short`). Drive facets. Define a controlled vocabulary — free-text attributes break filtering.
+
+**Attribute typing:** `text | enum | number | boolean | measurement`. Enums must reference a value list. Measurements carry a unit.
+
+---
+
+## Phase 3 — Faceted Search & Pagination
+
+- Facets come from `enum`/`boolean`/`measurement` attributes, not free text.
+- Multi-select within a facet = OR; across facets = AND.
+- Always show counts; never show zero-result facet values.
+- **Pagination:** prefer cursor/keyset over offset for deep catalogs (offset degrades and double-counts under writes). Cap page size.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Model from scratch | Entity spec + ER sketch + identifier strategy |
+| Audit schema | Verdict per entity: COMPLIANT / CONCERNS, with fixes |
+| Design taxonomy | Category tree + attribute schema + facet plan |
+
+A schema is **COMPLIANT** when price/inventory sit on variants, every product has ≥1 variant, attributes are typed against vocabularies, and URLs are stable.
+
+---
+
+## Related Skills
+
+- **storefront-architecture**: consumes this model to design PLP/PDP pages. Next step after modeling.
+- **merchant-feed**: maps these entities to Google/Meta feed attributes.
+- **inventory-stock**: owns stock levels that hang off the SKU/variant.
+- **order-lifecycle**: references variants as order line items.

package/skills/commerce-data-model/references/data-model-spec.md

@@ -0,0 +1,79 @@
+# Commerce Data Model — Field-Level Spec & Worked Example
+
+A language- and database-agnostic reference for the core catalog entities. Use it as the template for a model spec.
+
+## Entities & Fields
+
+### Product (marketing/SEO unit)
+| Field | Type | Notes |
+|-------|------|-------|
+| id | id | Internal key |
+| title | text | Display name |
+| slug | text | Stable URL segment, unique |
+| description | rich text | Long copy |
+| brand | text | Brand/manufacturer |
+| status | enum | draft / active / archived |
+| options | Option[] | Axes of variation (0..n) |
+| variants | Variant[] | ≥1 always |
+| collections | Collection[] | Many-to-many |
+| primary_category | Category | One navigational path |
+| attributes | Attribute[] | Typed key-values |
+
+### Variant (buyable unit)
+| Field | Type | Notes |
+|-------|------|-------|
+| id | id | |
+| sku | text | Stock-keeping code, unique |
+| option_values | map | e.g. {Color: Red, Size: M} |
+| price | integer (minor units) | Never a float |
+| compare_at_price | integer | For showing discounts |
+| barcode | text | GTIN/UPC/EAN |
+| weight / dimensions | number + unit | For shipping/carrier rates |
+| requires_shipping | bool | False for digital |
+
+### Option / Option Value
+`Option { name, position }` → `OptionValue { option_id, value, position }`. Example: Option "Size" → values S, M, L.
+
+### Collection (merchandising)
+`Collection { title, slug, type: manual|automatic, rules? }`. Automatic collections select by attribute rules (e.g. `tag = summer`).
+
+### Attribute (faceting)
+`Attribute { key, type: text|enum|number|boolean|measurement, value, unit? }`. Enum attributes reference a controlled value list.
+
+## Identifiers
+- **SKU** — your internal stock identifier (required, unique).
+- **GTIN** (UPC/EAN/ISBN) — global trade identifier; required for marketplaces/feeds where one exists.
+- **MPN** — manufacturer part number; fallback when no GTIN.
+
+## Bundles / Kits
+Model as a Product whose variant references component variants with quantities. Decide inventory rule: track by components (decrement each) vs by kit (own stock).
+
+## Worked Example — "Acme Tee"
+
+```yaml
+product:
+  title: "Acme Cotton Tee"
+  slug: "acme-cotton-tee"
+  brand: "Acme"
+  status: active
+  options:
+    - { name: Color, values: [Red, Blue] }
+    - { name: Size,  values: [S, M, L] }
+  attributes:
+    - { key: material, type: enum, value: cotton }
+    - { key: sleeve,   type: enum, value: short }
+  variants:
+    - sku: ACME-TEE-RED-M
+      option_values: { Color: Red, Size: M }
+      price: 2100            # 21.00 in minor units
+      barcode: "0123456789012"
+      weight: { value: 180, unit: g }
+```
+
+## Checklist (verdict: COMPLIANT when all true)
+- [ ] Price + inventory + barcode live on the variant, not the product
+- [ ] Every product has ≥1 variant (even with no options)
+- [ ] Attributes are typed and enums reference a vocabulary
+- [ ] Primary category is single; collections are many-to-many
+- [ ] Money stored as integer minor units
+- [ ] Slugs/URLs stable and unique