claude-code-arcane 1.3.0 → 1.4.0

package/skills/merchant-feed/scripts/feed_validate.py

@@ -0,0 +1,140 @@
+"""
+feed_validate.py — Validate a product feed CSV against Google Merchant /
+Meta Catalog requirements (the shared required-attribute core).
+
+Checks every row for required attributes, empty values, valid enums
+(availability, condition), and price+currency formatting. Reports a per-row
+and summary verdict. No external dependencies; cross-platform.
+
+Usage:
+    python feed_validate.py               # built-in demo feed
+    python feed_validate.py feed.csv      # validate your feed
+    python feed_validate.py feed.csv --strict   # treat recommended as required
+
+CSV header (required attributes):
+    id,title,description,link,image_link,availability,price,brand,condition
+Recommended columns (warn if absent/empty): gtin, mpn, item_group_id,
+    google_product_category, sale_price
+"""
+
+import argparse
+import csv
+import re
+import sys
+
+
+REQUIRED = ["id", "title", "description", "link", "image_link",
+            "availability", "price", "brand", "condition"]
+RECOMMENDED = ["gtin", "mpn", "item_group_id", "google_product_category"]
+
+AVAILABILITY = {"in_stock", "out_of_stock", "preorder", "backorder"}
+CONDITION = {"new", "refurbished", "used"}
+# e.g. "21.00 USD" / "9.99 EUR"
+PRICE_RE = re.compile(r"^\d+(\.\d{1,2})?\s+[A-Z]{3}$")
+URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+TITLE_MAX = 150
+DESC_MAX = 5000
+
+
+DEMO_FEED = [
+    {"id": "ACME-TEE-RED-M", "title": "Acme Cotton Tee — Red, Medium",
+     "description": "Soft 100% cotton crew-neck tee.", "link": "https://shop.example.com/p/acme-tee-red-m",
+     "image_link": "https://shop.example.com/img/acme-tee-red-m.jpg", "availability": "in_stock",
+     "price": "21.00 USD", "brand": "Acme", "condition": "new",
+     "gtin": "0123456789012", "item_group_id": "ACME-TEE"},
+    # broken row: bad availability, bad price, missing brand, non-url image
+    {"id": "ACME-MUG-BLUE", "title": "Acme Mug", "description": "",
+     "link": "https://shop.example.com/p/acme-mug", "image_link": "acme-mug.jpg",
+     "availability": "available", "price": "9.99", "brand": "", "condition": "brand-new"},
+]
+
+
+def validate_row(row, idx, strict):
+    errors = []
+    warnings = []
+
+    for attr in REQUIRED:
+        if not (row.get(attr) or "").strip():
+            errors.append(f"missing required '{attr}'")
+
+    avail = (row.get("availability") or "").strip().lower()
+    if avail and avail not in AVAILABILITY:
+        errors.append(f"availability '{avail}' not in {sorted(AVAILABILITY)}")
+
+    cond = (row.get("condition") or "").strip().lower()
+    if cond and cond not in CONDITION:
+        errors.append(f"condition '{cond}' not in {sorted(CONDITION)}")
+
+    price = (row.get("price") or "").strip()
+    if price and not PRICE_RE.match(price):
+        errors.append(f"price '{price}' must be like '21.00 USD' (amount + ISO currency)")
+
+    for url_attr in ("link", "image_link"):
+        val = (row.get(url_attr) or "").strip()
+        if val and not URL_RE.match(val):
+            errors.append(f"{url_attr} '{val}' must be an absolute http(s) URL")
+
+    title = (row.get("title") or "").strip()
+    if len(title) > TITLE_MAX:
+        warnings.append(f"title > {TITLE_MAX} chars ({len(title)})")
+    if len(row.get("description") or "") > DESC_MAX:
+        warnings.append(f"description > {DESC_MAX} chars")
+
+    has_id_link = bool((row.get("item_group_id") or "").strip())
+    if not has_id_link:
+        warnings.append("no item_group_id (variants won't cluster)")
+    if not (row.get("gtin") or "").strip() and not (row.get("mpn") or "").strip():
+        warnings.append("no gtin/mpn (weakens product matching)")
+
+    if strict:
+        errors.extend(f"(strict) {w}" for w in warnings)
+        warnings = []
+    return errors, warnings
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Validate a Google/Meta product feed CSV.")
+    ap.add_argument("csv", nargs="?", help="feed CSV. Omit for demo data.")
+    ap.add_argument("--strict", action="store_true", help="treat recommended issues as failures")
+    args = ap.parse_args()
+
+    if args.csv:
+        try:
+            with open(args.csv, newline="", encoding="utf-8") as f:
+                rows = list(csv.DictReader(f))
+        except OSError as e:
+            print(f"[ERROR] cannot read {args.csv}: {e}")
+            sys.exit(1)
+    else:
+        print("[INFO] No CSV given - using built-in demo feed.\n")
+        rows = DEMO_FEED
+
+    if not rows:
+        print("[ERROR] feed is empty.")
+        sys.exit(1)
+
+    failed = 0
+    for idx, row in enumerate(rows):
+        errors, warnings = validate_row(row, idx, args.strict)
+        rid = row.get("id") or f"row{idx}"
+        if errors:
+            failed += 1
+            print(f"FAIL  {rid}")
+            for e in errors:
+                print(f"        - {e}")
+            for w in warnings:
+                print(f"        ~ {w}")
+        else:
+            print(f"PASS  {rid}")
+            for w in warnings:
+                print(f"        ~ {w}")
+
+    print()
+    passed = len(rows) - failed
+    verdict = "READY" if failed == 0 else "NOT-READY"
+    print(f"{verdict}: {passed}/{len(rows)} items pass required-attribute checks.")
+    sys.exit(0 if failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/order-lifecycle/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: order-lifecycle
+description: "Design the order lifecycle — order state machine, fulfillment workflow, returns/RMA, refunds, cancellations, and order events/webhooks. Platform-agnostic state and event modeling. Triggers: designing order states, modeling returns/refunds, defining order events."
+argument-hint: "[design | states | returns]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Order Lifecycle
+
+An order is a long-lived state machine touched by payments, inventory, shipping, and support. Model its states, transitions, and events explicitly so nothing silently gets stuck — independent of platform.
+
+> **Note:** This skill may create or modify files in your project (a state-machine spec). It will ask before writing.
+
+## Before Starting
+
+Gather: fulfillment model (single vs split/partial shipments), payment capture timing (auth-then-capture vs immediate), returns policy, and goal (design the full lifecycle, define the state machine, or model returns/refunds).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | End-to-end lifecycle + events |
+| **States** | `states` | Formal state machine: states, transitions, guards |
+| **Returns** | `returns` | RMA + refund flow and states |
+
+---
+
+## Phase 1 — The State Machine
+
+Separate **order status** from **payment status** and **fulfillment status** — collapsing them into one field is the most common modeling mistake.
+
+| Dimension | States |
+|-----------|--------|
+| **Order** | pending → confirmed → in_progress → completed / cancelled |
+| **Payment** | pending → authorized → paid → partially_refunded → refunded / failed |
+| **Fulfillment** | unfulfilled → partially_fulfilled → fulfilled → returned |
+
+Each transition has a **guard** (e.g. cannot fulfill before payment authorized) and emits an **event**.
+
+For the full transition table, guards, and partial-shipment handling, see [references/order-state-machine.md](references/order-state-machine.md).
+
+---
+
+## Phase 2 — Events & Webhooks
+
+Every transition emits a durable, ordered event: `order.created`, `order.paid`, `order.fulfilled`, `order.cancelled`, `order.refunded`, `return.requested`, `return.received`.
+
+- Events are **append-only** — never mutate history; the current state is a projection.
+- Outbound webhooks must be **idempotent and retried** with signatures (hand off to `payments-architecture` for the reliability pattern).
+- Carry an idempotency key from order placement through fulfillment.
+
+---
+
+## Phase 3 — Returns & Refunds
+
+Flow: `return.requested → approved → label_sent → in_transit → received → inspected → refunded/rejected`.
+
+| Concern | Rule |
+|---------|------|
+| Restock | Only on `received + inspected` pass, back to `available` |
+| Refund | Full / partial / store-credit; never exceed captured amount |
+| Window | Enforce return-window guard at request time |
+| Partial | Per line-item, not whole-order, for split fulfillment |
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Lifecycle diagram + event catalog |
+| States | State/transition/guard table (the spec) |
+| Returns | RMA flow + refund rules |
+
+A lifecycle design is **COMPLETE** when order/payment/fulfillment statuses are independent, every transition has a guard and an event, and refunds/restocks are gated on inspection.
+
+---
+
+## Related Skills
+
+- **payments-architecture**: capture/refund and webhook reliability for order events.
+- **inventory-stock**: reservations released and stock decremented per fulfillment.
+- **cart-checkout**: hands the placed order into this lifecycle.
+- **commerce-analytics**: order events feed funnel and revenue metrics.

package/skills/order-lifecycle/references/order-state-machine.md

@@ -0,0 +1,53 @@
+# Order State Machine — Transitions, Guards & Events
+
+Three independent dimensions. Keep them separate; the overall order status is a projection, not a stored mega-enum.
+
+## Order status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| (start) | pending | order placed | `order.created` |
+| pending | confirmed | payment authorized | `order.confirmed` |
+| confirmed | in_progress | fulfillment started | `order.processing` |
+| in_progress | completed | all items fulfilled | `order.completed` |
+| pending/confirmed | cancelled | not yet shipped | `order.cancelled` |
+
+## Payment status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| pending | authorized | auth succeeded | `payment.authorized` |
+| authorized | paid | captured | `payment.captured` |
+| paid | partially_refunded | refund < captured | `payment.refunded` |
+| paid | refunded | refund == captured | `payment.refunded` |
+| pending/authorized | failed | gateway decline | `payment.failed` |
+
+## Fulfillment status
+| From | To | Guard | Event |
+|------|----|-------|-------|
+| unfulfilled | partially_fulfilled | some lines shipped | `fulfillment.partial` |
+| partially_fulfilled | fulfilled | all lines shipped | `fulfillment.completed` |
+| fulfilled | returned | RMA received | `return.received` |
+
+## Cross-dimension guards (the important rules)
+- Cannot transition fulfillment past `unfulfilled` until payment is `authorized` (or `paid`, per capture policy).
+- Cannot `cancel` once any line is `fulfilled` — use returns instead.
+- Capture timing: auth at placement, capture at first fulfillment (auth/capture model) OR capture immediately (decide once).
+
+## Returns / RMA sub-flow
+`return.requested → approved → label_sent → in_transit → received → inspected → (refunded | rejected)`
+
+| Concern | Rule |
+|---------|------|
+| Window | Guard `requested` against return-window from delivery date |
+| Restock | Only on `inspected` pass → quantity back to `available` |
+| Refund | ≤ captured amount; full / partial / store-credit |
+| Partial | Per line item for split fulfillment |
+
+## Events are append-only
+Persist every event with: id, order_id, type, payload, timestamp, idempotency_key. Current state = fold over events. Outbound webhooks must be signed, deduplicated, and retried (see `payments-architecture`).
+
+## Verdict: COMPLETE when
+- [ ] Order / payment / fulfillment statuses are independent fields
+- [ ] Every transition has a guard and emits an event
+- [ ] Cancel blocked after fulfillment; returns handle post-ship
+- [ ] Restock gated on inspection; refunds capped at captured amount
+- [ ] Events are append-only with idempotency keys

package/skills/payments-architecture/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: payments-architecture
+description: "Design payment architecture independent of any single processor — gateway selection, payment intents, idempotency, webhook reliability, reconciliation, PCI scope, fraud, and refunds. Complements processor-specific skills. Triggers: choosing a PSP, designing webhook handling, reducing PCI scope, reconciling payments."
+argument-hint: "[design | webhooks | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Payments Architecture
+
+The payment layer must never double-charge, never lose a webhook, and never widen PCI scope. This skill designs the processor-agnostic architecture; processor-specific implementation (e.g. Stripe) is a handoff.
+
+## Before Starting
+
+Gather: markets/currencies, payment methods (cards, wallets, local methods), capture model (immediate vs auth/capture), subscription needs, and goal (design the architecture, harden webhooks, or audit an existing integration).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Gateway choice + payment flow + PCI strategy |
+| **Webhooks** | `webhooks` | Reliable, idempotent webhook handling design |
+| **Audit** | `audit` | Risk review of an existing integration |
+
+---
+
+## Phase 1 — Flow & Idempotency
+
+Use the **payment intent** model regardless of processor: create intent → confirm → succeeded/failed, with status mirrored onto the order.
+
+| Principle | Why |
+|-----------|-----|
+| **Idempotency keys** on every create/charge | A retried request must not double-charge |
+| **Server-authoritative amounts** | Never trust client-sent totals; re-price server-side |
+| **Auth then capture** (where supported) | Capture at fulfillment, not at order placement |
+| **Money as integer minor units** | No floats for currency, ever |
+
+---
+
+## Phase 2 — Webhook Reliability
+
+Webhooks are the source of truth for async payment outcomes — treat them as unreliable transport:
+
+1. **Verify the signature** before doing anything.
+2. **Deduplicate** by event id (idempotent processing) — providers redeliver.
+3. **Persist then process** — store the raw event, ack fast (2xx), process out of band.
+4. **Tolerate out-of-order** delivery; reconcile against current state, don't assume sequence.
+5. **Reconcile** daily against the processor's ledger to catch missed events.
+
+For the persist-ack-process pattern, retry/backoff, and reconciliation report design, apply the principles above and hand processor specifics to `stripe-integration-expert`.
+
+---
+
+## Phase 3 — PCI Scope & Fraud
+
+- **Minimize PCI scope:** use hosted fields / tokenization so raw PAN never touches your servers (SAQ A). Never log card data.
+- **Fraud:** combine processor risk signals with velocity checks, AVS/CVV, and 3-D Secure for high-risk; balance friction vs chargebacks.
+- **Refunds:** never exceed captured amount; support partial; emit `payment.refunded` to the order lifecycle.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Gateway selection + intent flow + PCI scope plan |
+| Webhooks | Idempotent handler design + reconciliation plan |
+| Audit | Findings: SECURE / CONCERNS / FAIL per area |
+
+A payment architecture is **SECURE** when charges are idempotent, amounts are server-authoritative, webhooks are signature-verified and deduplicated, money is integer minor units, and PCI scope is minimized.
+
+---
+
+## Related Skills
+
+- **stripe-integration-expert**: processor-specific implementation once this architecture is set.
+- **cart-checkout**: invokes the payment step.
+- **order-lifecycle**: consumes payment events (paid, refunded).
+- **subscription-billing**: recurring charges build on this layer.

package/skills/product-listing/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: product-listing
+description: "Optimize product detail pages and marketplace listings for discovery and conversion — titles, bullets, descriptions, imagery, A+ content, and marketplace algorithms (Amazon A10/COSMO/Rufus). Includes bulk-copy generation guidance. Triggers: writing/optimizing PDP copy, marketplace listings, bulk product descriptions."
+argument-hint: "[pdp | marketplace | bulk]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Product Listing
+
+A listing has two readers: the ranking algorithm and the buyer. Optimize for both — keyword-relevant enough to surface, persuasive enough to convert — across your own PDP and marketplaces.
+
+## Before Starting
+
+Gather: channel (own store vs Amazon/Meta/etc.), product category and key attributes, target keywords, and goal (optimize a PDP, write a marketplace listing, or generate bulk descriptions).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **PDP** | `pdp` | Optimized own-store product page copy |
+| **Marketplace** | `marketplace` | Channel-specific listing (title/bullets/A+) |
+| **Bulk** | `bulk` | Templated copy for many SKUs at scale |
+
+---
+
+## Phase 1 — PDP Copy Anatomy
+
+| Element | Rule |
+|---------|------|
+| **Title** | Brand + product + key differentiator; front-load the noun |
+| **Bullets** | Benefit-led, scannable; feature → benefit translation |
+| **Description** | Story + specs; answer objections; structured for skim |
+| **Imagery** | Multiple angles, scale/context, zoom; alt text for SEO + a11y |
+| **Trust** | Reviews, ratings, returns, shipping, stock signals near the CTA |
+
+Map product attributes (from `commerce-data-model`) into structured spec tables — buyers filter on them and search engines index them.
+
+---
+
+## Phase 2 — Marketplace Algorithms
+
+Marketplace listings must satisfy ranking systems, not just shoppers:
+
+- **Amazon A10** — keyword/relevance + sales velocity + conversion. Put core keywords in title and bullets naturally.
+- **COSMO** — semantic/intent: write for *purchase intent and use-cases*, not just keyword stuffing.
+- **Rufus / AI assistants** — Q&A-friendly content: cover comparisons, compatibility, use-cases the way a shopper would ask.
+- Localize per marketplace (not just translate) — units, sizing, terminology.
+
+Avoid keyword stuffing; modern algorithms penalize it and shoppers distrust it. Hand SEO structure to `ai-seo` / `seo-audit`.
+
+---
+
+## Phase 3 — Bulk Generation
+
+For large catalogs, template the copy:
+
+1. Define a copy template per product category (slots: hook, benefits, specs, use-case).
+2. Map structured attributes → slots.
+3. Generate, then spot-QA for accuracy and duplicate-content risk (search engines penalize near-duplicates).
+
+Pair with `merchant-feed` (the script there validates the structured attributes that feed both listings and ads).
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| PDP | Title + bullets + description + image/alt brief |
+| Marketplace | Channel-tuned listing with keyword map |
+| Bulk | Category templates + slot mapping |
+
+A listing is **READY** when the title front-loads the product, bullets are benefit-led, intent/use-cases are covered for AI search, trust signals sit by the CTA, and there's no duplicate-content risk.
+
+---
+
+## Related Skills
+
+- **commerce-data-model**: source of the structured attributes copy draws on.
+- **ai-seo** / **seo-audit** / **schema-markup**: organic discovery and markup.
+- **merchant-feed**: same attributes power shopping ads.
+- **copywriting** / **page-cro**: deeper persuasion and conversion testing.

package/skills/promotions-discounts/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: promotions-discounts
+description: "Design a promotions and discount engine — coupon codes, automatic discounts, BOGO, tiered/volume pricing, stacking and exclusivity rules, and gift cards. Platform-agnostic rules modeling that avoids margin leaks. Triggers: designing discounts, defining stacking rules, modeling gift cards/coupons."
+argument-hint: "[design | rules | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Promotions & Discounts
+
+Discounts are easy to add and hard to control. Model the rules so promotions stack predictably, can't be abused, and never quietly destroy margin — independent of platform.
+
+## Before Starting
+
+Gather: promotion types in use, who can stack with what, abuse history (code sharing, repeat redemption), and goal (design the engine, define stacking/exclusivity rules, or audit existing promos for leaks).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Discount engine model + rule schema |
+| **Rules** | `rules` | Stacking, exclusivity, and eligibility matrix |
+| **Audit** | `audit` | Margin-leak and abuse-risk review |
+
+---
+
+## Phase 1 — Discount Model
+
+Model every promotion as **trigger → condition → effect → constraints**:
+
+| Part | Examples |
+|------|----------|
+| **Trigger** | code entered, automatic, cart threshold |
+| **Condition** | min subtotal, specific collection, customer segment, first order |
+| **Effect** | % off, fixed off, free shipping, BOGO, fixed price |
+| **Constraints** | usage cap (global/per-customer), date window, exclusivity |
+
+**Rule:** Discounts apply to a defined scope (line / shipping / order) and are recomputed server-side at checkout — never client-trusted.
+
+---
+
+## Phase 2 — Stacking & Exclusivity
+
+The hard part. Define explicitly:
+
+- **Stackable vs exclusive:** most stores allow one order-level code; auto-discounts may stack with codes. Decide and enforce.
+- **Application order** matters for % vs fixed — define it (typically line discounts → order discounts → shipping).
+- **Priority** when multiple eligible: best-for-customer vs best-for-merchant — pick a policy.
+- **Caps:** max discount per order; floor on post-discount margin.
+
+For the full eligibility matrix and worked stacking examples, model the matrix per the table above.
+
+---
+
+## Phase 3 — Gift Cards & Abuse Prevention
+
+- **Gift cards** are stored-value tender, not discounts — track balance, partial redemption, and never let balance go negative or expire silently where regulated.
+- **Abuse defenses:** per-customer usage caps, one-time codes, segment gating, and minimum-order thresholds. Watch for code leaks to coupon sites.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design | Rule schema + effect/scope model |
+| Rules | Stacking/exclusivity matrix + application order |
+| Audit | Leak/abuse findings: PASS / CONCERNS / FAIL |
+
+A promotion engine is **COMPLIANT** when discounts are server-computed, stacking and application order are explicit, usage caps are enforced, and a margin floor protects every order.
+
+---
+
+## Related Skills
+
+- **cart-checkout**: applies discounts at the cart/checkout.
+- **pricing-strategy**: sets the base prices discounts modify.
+- **commerce-analytics**: measures promo ROI and margin impact.
+- **referral-program**: a specialized promotion type.

package/skills/shipping-tax/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: shipping-tax
+description: "Design shipping and tax logic — shipping zones, rates and methods, carrier integration patterns, plus sales tax/VAT/GST, nexus, and duties. Platform-agnostic rules for correct totals at checkout. Triggers: designing shipping rates, modeling tax/VAT, handling cross-border duties."
+argument-hint: "[shipping | tax | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Shipping & Tax
+
+The two line items most likely to be wrong at checkout — and the ones that cause chargebacks, abandoned carts, and compliance trouble. Model them correctly and computed server-side, independent of platform.
+
+## Before Starting
+
+Gather: markets shipped to/from, carriers, product attributes (weight/dims), tax obligations (countries, nexus, registrations), and goal (design shipping, design tax, or audit existing totals).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Shipping** | `shipping` | Zones, methods, and rate model |
+| **Tax** | `tax` | Tax determination and nexus model |
+| **Audit** | `audit` | Correctness review of current totals |
+
+---
+
+## Phase 1 — Shipping Model
+
+Layer the model as **zones → methods → rates**:
+
+| Layer | Definition |
+|-------|-----------|
+| **Zone** | Geographic grouping (country/region/postal ranges) |
+| **Method** | Service level (standard, express, pickup) per zone |
+| **Rate** | flat / weight-based / price-based / carrier-calculated / free-over-threshold |
+
+- **Free-shipping thresholds** must be computed on the discounted subtotal.
+- **Carrier-calculated** rates need weight + dimensions on the variant — falls back to flat if missing.
+- Show shipping before the payment step; recompute when the address changes.
+
+---
+
+## Phase 2 — Tax Determination
+
+Tax is destination- and product-dependent — never a single flat rate:
+
+| Concept | Rule |
+|---------|------|
+| **Nexus** | You only collect where you have an obligation — model registrations per jurisdiction |
+| **Destination vs origin** | Most VAT/GST is destination-based; some US states origin-based |
+| **Product taxability** | Categories differ (food, digital, apparel) — map products to tax categories |
+| **Price display** | Tax-inclusive (EU/UK) vs tax-exclusive (US) — a presentation rule, get it right per market |
+| **B2B** | Reverse-charge / VAT-ID validation for cross-border EU |
+
+**Rule:** Compute tax at checkout against the shipping destination, using a tax category per product. Round per jurisdiction rules.
+
+---
+
+## Phase 3 — Cross-Border & Duties
+
+- **DDP vs DDU:** decide who pays import duties — DDP (you collect at checkout, best UX) vs DDU (customer pays on delivery, surprise fees → returns).
+- **Landed cost** = item + shipping + duties + tax; show it for cross-border.
+- Capture **HS codes** and country of origin on products for customs.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Shipping | Zone/method/rate model |
+| Tax | Nexus map + product tax-category mapping |
+| Audit | Findings per market: PASS / FAIL with fixes |
+
+Shipping and tax are **READY** when both are computed server-side against the destination, free-shipping uses discounted subtotals, tax categories are mapped, and cross-border shows landed cost.
+
+---
+
+## Related Skills
+
+- **cart-checkout**: displays and recomputes these at the shipping step.
+- **order-lifecycle**: shipping method feeds fulfillment; tax recorded on the order.
+- **commerce-data-model**: weight/dims/HS code/tax category live on the product.
+- **merchant-feed**: shipping and tax attributes appear in product feeds.