create-cartbase 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -1,4 +1,4 @@
-# Build a storefront — the runbook
+# Build a storefront
 
 **This runbook takes you from a blank Next.js app to a completed checkout
 against your Cartbase store.** It is written to be followed by a developer

package/template/app/docs/README.md

@@ -1,4 +1,4 @@
-# docs/storefront/ — the bulletproof storefront docs
+# Storefront docs
 
 **Audience: an AGENT building a storefront from a blank Next.js app.** These
 docs are the entire knowledge transfer — every call shape, every curl, every

package/template/app/docs/auth.md

@@ -1,4 +1,4 @@
-# Auth — passwordless code login + session discipline
+# Auth
 
 Passwordless email-code login (customer-accounts card, Shopify Customer
 Account API direction). Two calls: **request** emails a 6-digit code,

package/template/app/docs/carts.md

@@ -1,4 +1,4 @@
-# Carts — lifecycle + line items
+# Carts
 
 The cart is the storefront's working document: created anonymously, mutated
 through line-item and update calls, completed into an order (see
@@ -118,8 +118,8 @@ test -n "$CART_ID" && test -n "$REGION_ID"
     "item_total": 54, "item_subtotal": 45, "item_tax_total": 9,
     "original_total": 54, "original_subtotal": 45, "original_tax_total": 9,
     "credit_line_total": 0,
-    "cod_fee_total": 0,              // non-zero only with a live pp_cod session + enabled COD integration
-    "cod_fee_label": null,
+    "payment_method_fee_total": 0,              // the selected method's own fee — non-zero only with a live method session
+    "payment_method_fee_label": null,
     // gift-card tender decoration (totals above NEVER move):
     "gift_cards": [],                // [{id, last4, amount}] in apply order
     "gift_card_total": 0,            // Σ applied-card coverage

package/template/app/docs/categories.md

@@ -1,4 +1,4 @@
-# Categories, tags, types
+# Categories
 
 Taxonomy reads for navigation trees and filter UIs. Categories are
 hierarchical (`parent_category_id`) with optional ancestor/descendant tree

package/template/app/docs/checkout.md

@@ -1,4 +1,4 @@
-# Checkout — shipping options, payment, the Buy click, complete
+# Checkout
 
 This page is the full checkout knowledge transfer: every listing, the
 orchestrated Buy-click sequence, the amount-sync matrix, dead-PI recovery,
@@ -23,10 +23,11 @@ listShippingOptions(cart_id) ─┐  (render pickers)
 listPaymentProviders(cart_id) ┘
         │  Buy click
         ▼
-prepareCheckout(cart, {address, shipping_method_id, carrier_metadata, payment_provider})
+prepareCheckout(cart, {address, shipping_method_id, carrier_metadata,
+                       payment_provider XOR payment_method_id})
         │                         ONE atomic call, compensated on failure
         ├─ pp_stripe → stripe.confirmPayment(client_secret) ─┐
-        └─ pp_cod / pp_manual ───────────────────────────────┤
+        └─ a payment method (Bank transfer, COD…) ───────────┤
                                                              ▼
                                             completeCart(cart) → {type:"order", order}
 ```
@@ -56,17 +57,23 @@ changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
 {
   "shipping_options": [{
     "id": "so_…", "name": "Standard",
-    "provider_id": "fp_manual", "service_zone_id": "sz_…",
-    "shipping_option_type_id": "sotype_…", "shipping_profile_id": "sp_…",
+    "provider_id": null,          // the carrier, when the merchant bound one
+    "service_zone_id": "sz_…", "shipping_profile_id": "sp_…",
     "data": null,
-    "type": { "…": "shipping_option_types row (label/code/description)" },
-    "amount": 5,                 // flat price in the cart currency; null without cart_id
+    "type": { "label": "Express" }, // the option's display label, or null
+    "amount": 5,                 // the price the cart pays; null without cart_id
     "price_type": "flat"         // calculated-rate carriers not wired yet
   }],
   "count": 1, "offset": 0, "limit": 1
 }
 ```
 
+- **Eligibility** — four gates run server-side before an option lists:
+  the option's shipping profile must be among the cart products' profiles;
+  its zone must cover the shipping address; its visibility rules must
+  pass; and a price must exist for the cart. Conditional rates (tiers by
+  order amount, cart weight, or cart volume) resolve here — `amount` is
+  always the tier the cart actually satisfies.
 - **Errors** — 404 `cart_not_found` (bad `cart_id`).
 - **SDK** — `checkout.listShippingOptions(client, {cart_id})`.
 - **Components** — shipping picker, carrier/locker pickers (carrier
@@ -129,33 +136,64 @@ curl -sf -X POST "$BASE/api/store/shipping-options/$SO_ID/calculate" \
   `region_id`: the tenant's enabled providers (global catalog ∩ tenant
   enablement). With it: providers linked to that region. `cart_id` feeds
   the rules engine — storefronts SHOULD pass it during checkout.
-- **Response** — list envelope, full filtered list:
+- **Response** — list envelope, full filtered list. Two entry shapes share
+  the array: connected PROCESSORS (`{id}` — pp_stripe) and merchant
+  payment METHODS (`{payment_method_id, name, kind, instructions,
+  fee_amount, fee_label}` — "Bank transfer", the COD method). Methods
+  carry no provider id anywhere; a fresh store with nothing configured
+  gets an honestly empty list. With `region_id`, BOTH families filter by
+  the region's claims (`region_payment_provider` /
+  `region_payment_method` — availability is a per-region merchant
+  choice):
 
 ```jsonc
 {
   "payment_providers": [
-    { "id": "pp_manual", "is_enabled": true, "created_at": "…" }
-    // pp_stripe / pp_cod appear when their integrations are enabled;
+    { "id": "pp_stripe", "is_enabled": true, "created_at": "…" },
+    // one entry PER enabled, region-claimed merchant method:
+    { "payment_method_id": "pm_…", "name": "Bank transfer",
+      "kind": "manual", "instructions": "IBAN BG…",
+      "fee_amount": null, "fee_label": null },
+    { "payment_method_id": "pm_…", "name": "Cash on delivery",
+      "kind": "cod", "instructions": null,
+      "fee_amount": 4.99, "fee_label": "COD fee" }
     // pp_giftcard is INTERNAL tender and is never listed
   ],
-  "count": 1, "offset": 0, "limit": 1
+  "count": 3, "offset": 0, "limit": 3
 }
 ```
 
+- **Selecting a method** — initiate the session with the method id alone:
+  `POST …/payment-sessions { payment_method_id: "pm_…" }`. The server
+  validates it (tenant's, enabled, claimed for the cart's region — 400
+  otherwise), the session lands with `provider_id` NULL, and the method's
+  identity is snapshotted into `session.data`
+  (`payment_method_id/name/kind`) so payment surfaces say "Bank
+  transfer" without a join. Render `instructions` to the shopper after
+  selection and on the confirmation screen. `fee_amount`/`fee_label` let
+  the checkout PREDICT the fee before the session exists — the authority
+  stays the server totals (`payment_method_fee_total`).
 - **Errors** — none beyond the standard envelope (empty list when nothing
-  is enabled).
+  is enabled); initiate 400s on unknown/disabled/foreign method ids and
+  `payment_method_not_in_region` for an unclaimed region.
 - **SDK** — `checkout.listPaymentProviders(client, {region_id, cart_id})`.
 - **Components** — payment picker.
-- **Settings** — admin integrations provision providers (enabling COD
-  provisions `pp_cod` + its fee config; enabling Stripe provisions
-  `pp_stripe` + credentials); checkout rules
-  (`target_type=payment_method`) + `checkout_method_order`.
+- **Settings** — Stripe connects in Settings, Payments (provisions
+  `pp_stripe` + credentials); payment methods live in the same screen
+  (the COD switch + named manual methods, each with optional
+  `fee_amount`/`fee_label` and per-region availability); checkout rules
+  (`target_type=payment_method`, method entries participate under their
+  `payment_method_id`) + `checkout_method_order`.
 
 ```bash
 curl -sf "$BASE/api/store/payment-providers?cart_id=$CART_ID" \
-  -H "x-client-id: $CLIENT_ID" | grep -q '"pp_manual"'
-curl -sf "$BASE/api/store/payment-providers?region_id=$REGION_ID&cart_id=$CART_ID" \
-  -H "x-client-id: $CLIENT_ID" | grep -q '"pp_manual"'
+  -H "x-client-id: $CLIENT_ID" | grep -q '"payment_method_id"'
+PAY_JSON=$(curl -sf "$BASE/api/store/payment-providers?region_id=$REGION_ID&cart_id=$CART_ID" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$PAY_JSON" | grep -q '"payment_method_id"'
+# The seeded Bank transfer method carries the rest of this page.
+PM_ID=$(echo "$PAY_JSON" | grep -o '"payment_method_id":"pm_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$PM_ID"
 ```
 
 ---
@@ -166,8 +204,8 @@ ONE call writes everything the customer toggled on /checkout, in the only
 safe order: **address first** (option pricing reads the destination) →
 **shipping method** → **payment collection** at the shipped total →
 **payment session LAST** at the FINAL amount (real Stripe PaymentIntent,
-idempotency key = session id; plain row for `pp_cod`/`pp_manual`). For
-`pp_cod` the native fee only applies once the session exists, so amounts
+idempotency key = session id; a plain NULL-provider row for a payment
+method). A method's fee only applies once its session exists, so amounts
 are re-synced after it. Fully compensated: any failure rolls back session
 → collection → shipping method → addresses/metadata to the pre-call
 snapshot (recorded in the execution ledger, workflow `prepare-checkout`,
@@ -178,8 +216,10 @@ states done/reverted; failures also land in `checkout_error_logs`, step
 - **Request** (`.strict()`; DTO verbatim from
   `src/lib/checkout-orchestration/prepare.ts`) — all address fields
   required except `address_2`/`company`/`province`; `phone` is required
-  (courier recovery channel). `payment_provider` = `pp_stripe` | `pp_cod` |
-  `pp_manual`, never `pp_giftcard`:
+  (courier recovery channel). The tender is exactly ONE of
+  `payment_provider` (a connected processor — `pp_stripe`, never
+  `pp_giftcard`) or `payment_method_id` (a merchant method from the
+  listing):
 
 ```jsonc
 {
@@ -195,7 +235,7 @@ states done/reverted; failures also land in `checkout_error_logs`, step
   "carrier_metadata": {                  // optional, opaque per-carrier keys
     "office_code": "X1", "office_name": "Center"
   },
-  "payment_provider": "pp_manual",
+  "payment_method_id": "pm_…",           // XOR payment_provider: "pp_stripe"
   "save_payment_method": false           // optional — subscription carts only;
                                          // same semantics + consent duty as on
                                          // payment-sessions below
@@ -214,15 +254,17 @@ states done/reverted; failures also land in `checkout_error_logs`, step
 {
   "cart_id": "cart_…",
   "payment_collection_id": "pc_…",
-  "client_secret": "pi_…_secret_…",   // Stripe only; null for pp_cod/pp_manual AND zero-remainder carts
-  "provider_id": "pp_manual"          // null when zero-remainder skipped the provider session
+  "client_secret": "pi_…_secret_…",   // Stripe only; null for method sessions AND zero-remainder carts
+  "provider_id": null,                // the processor, when one was chosen
+  "payment_method_id": "pm_…"         // the method, when one was chosen
 }
 ```
 
 - **Zero-remainder gift path** — when applied gift cards cover the whole
-  total, the provider session is skipped entirely (`client_secret` and
-  `provider_id` come back null) and the cart completes on the gift session
-  alone — no Stripe involved ([gift-cards.md](gift-cards.md)).
+  total, the tender session is skipped entirely (`client_secret`,
+  `provider_id` and `payment_method_id` come back null) and the cart
+  completes on the gift session alone — no Stripe involved
+  ([gift-cards.md](gift-cards.md)).
 - **Errors** — 404 `cart_not_found` | `shipping_option_not_found`; 409
   `cart_completed`; 400 `validation_failed` | `invalid_provider`
   (pp_giftcard) | `shipping_price_missing` | `stripe_not_configured`.
@@ -241,8 +283,8 @@ PREP_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/prepare-checkout" \
         "country_code":"bg","phone":"+359888123456"},
        "shipping_method_id":"'"$SO_ID"'",
        "carrier_metadata":{"office_code":"X1"},
-       "payment_provider":"pp_manual"}')
-echo "$PREP_JSON" | grep -q '"provider_id":"pp_manual"'
+       "payment_method_id":"'"$PM_ID"'"}')
+echo "$PREP_JSON" | grep -q '"payment_method_id":"'"$PM_ID"'"'
 echo "$PREP_JSON" | grep -q '"client_secret":null'
 PC_ID=$(echo "$PREP_JSON" | grep -o '"payment_collection_id":"pc_[^"]*"' | cut -d'"' -f4)
 test -n "$PC_ID"
@@ -270,8 +312,9 @@ changes the total while checkout is mounted (quantity change, gift card
 applied/removed, shipping switch).
 
 - **Auth** — anon `x-client-id`.
-- **Request** — `{provider_id?}` (`.strict()`; empty object fine). Passing
-  a DIFFERENT provider than the pending session's forces rotation to it.
+- **Request** — `{provider_id? | payment_method_id?}` (`.strict()`; empty
+  object fine, never both). Passing a DIFFERENT tender than the pending
+  session's forces rotation to it.
 - **Response matrix** (verbatim `src/lib/checkout-orchestration/sync.ts`):
 
 | state | response |
@@ -279,29 +322,31 @@ applied/removed, shipping switch).
 | completed cart | `{"synced":false,"reason":"cart-completed"}` |
 | no payment collection | `{"synced":false,"reason":"no_payment_collection"}` |
 | no pending provider session (gift sessions excluded) | `{"synced":false,"reason":"no_pending_session"}` |
-| provider matches, amount current | `{"synced":true,"rotated":false,"client_secret":…,"provider_id":…}` (no-op) |
-| provider matches, amount drifted | in-place update (Stripe `paymentIntents.update`; plain field for pp_cod/pp_manual) → `{"synced":true,"rotated":false,…}` — same secret |
-| provider mismatch OR update refused (terminal PI) | rotation: old session retired (+ PI voided best-effort), fresh session at the new remainder → `{"synced":true,"rotated":true,"client_secret":…,"provider_id":…}` |
+| tender matches, amount current | `{"synced":true,"rotated":false,"client_secret":…,"provider_id":…,"payment_method_id":…}` (no-op) |
+| tender matches, amount drifted | in-place update (Stripe `paymentIntents.update`; plain field for method sessions) → `{"synced":true,"rotated":false,…}` — same secret |
+| tender mismatch OR update refused (terminal PI) | rotation: old session retired (+ PI voided best-effort), fresh session at the new remainder → `{"synced":true,"rotated":true,…}` |
 
-  Rotation retires the old session BEFORE recomputing so session-dependent
-  totals (the COD fee) settle for the NEW provider; a final resync pass
-  aligns collection + session + PI. `client_secret` is null for non-Stripe
-  sessions.
+  A session's tender identity is its `provider_id` for processors and its
+  snapshot `payment_method_id` for NULL-provider method sessions. Rotation
+  retires the old session BEFORE recomputing so session-dependent totals
+  (the method fee) settle for the NEW tender; a final resync pass aligns
+  collection + session + PI. `client_secret` is null for method sessions.
 
 - **Errors** — 404 `cart_not_found`; 400 `validation_failed` |
   `stripe_not_configured`. Failures land in `checkout_error_logs`
   (step `sync-payment-amount`).
-- **SDK** — `checkout.syncPaymentAmount(client, cartId, {provider_id})`.
+- **SDK** — `checkout.syncPaymentAmount(client, cartId, {provider_id?,
+  payment_method_id?})`.
 - **Components** — checkout totals watcher (debounced), payment-method
-  switcher (pass the new `provider_id`).
+  switcher (pass the new tender id).
 
 ```bash
-# No-drift no-op on the prepared pp_manual cart: same-session, not rotated.
+# No-drift no-op on the prepared method cart: same-session, not rotated.
 SYNC_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/sync-payment-amount" \
   -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
 echo "$SYNC_JSON" | grep -q '"synced":true'
 echo "$SYNC_JSON" | grep -q '"rotated":false'
-echo "$SYNC_JSON" | grep -q '"provider_id":"pp_manual"'
+echo "$SYNC_JSON" | grep -q '"payment_method_id":"pm_'
 ```
 
 ---
@@ -333,7 +378,7 @@ production reload loop).
 - **Components** — Stripe Elements mount error handler.
 
 ```bash
-# pp_manual session ⇒ documented no-op reason (Stripe-specific rotation
+# Method session ⇒ documented no-op reason (Stripe-specific rotation
 # needs STRIPE credentials — proven by tests/store/checkout-orchestration-sync.test.ts).
 curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
   -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"no-stripe-session"'
@@ -350,7 +395,7 @@ reservation (kit-aware) → order creation (rows copied cart→order) →
 cycle 1 tied to this order, cycle 2 scheduled at the next CHARGE date;
 guests are refused with 400 `customer_required`) → **payment authorization
 LAST** (gift tender redeemed atomically first; real Stripe authorize for
-`pp_stripe`; best-effort stub for `pp_cod`/`pp_manual`) → `order.placed`
+`pp_stripe`; best-effort stub for method sessions) → `order.placed`
 (+ `subscription.created` per contract) on the durable bus. Any failure
 before authorize compensates fully (order deleted, contracts deleted,
 inventory released, gift tender reversed, cart unlocked) — the cart stays
@@ -378,9 +423,11 @@ the mandate already exists.
     `customer_required` (plan lines on a guest cart — subscribing needs an
     account; normally already refused at the payment-session step).
   - 400 `checkout_method_hidden` — **the checkout-rules security
-    boundary**: every live payment session's provider (except internal
-    `pp_giftcard`) and every chosen shipping option is re-validated
-    against the live rules with the full cart context. A stale session
+    boundary**: every live payment session's chosen tender (the method's
+    `payment_method_id` for NULL-provider sessions, else the provider id;
+    internal `pp_giftcard` exempt) and every chosen shipping option is
+    re-validated against the live rules with the full cart context. A
+    stale session
     that picked a method before a rule started matching, or a hostile
     client that skipped the filtered listings, is rejected here and the
     rejection is recorded in `checkout_error_logs` (step `complete`).
@@ -395,14 +442,15 @@ the mandate already exists.
   `@cartbase/storefront/api/carts`).
 - **Components** — Buy button (orchestrated path), order-confirmation
   page.
-- **Settings** — checkout rules; `accounts_mode`; COD fee (**timing**: the
-  fee exists only while a live `pp_cod` session does — it appears on the
-  cart at prepare, rides `cart.total`, and is carried onto the order via
+- **Settings** — checkout rules; `accounts_mode`; the payment method fee
+  (**timing**: a method's fee exists only while ITS live session does — it
+  appears on the cart at prepare as `payment_method_fee_total`, rides
+  `cart.total`, and is carried onto the order via
   `order_summaries.totals`, where waybill COD amounts read it); gift-card
   tender (zero-remainder carts complete on the gift session alone).
 
 ```bash
-# Complete the prepared pp_manual cart → a real order, no Stripe env needed.
+# Complete the prepared method cart → a real order, no Stripe env needed.
 ORDER_JSON=$(curl -sf -X POST "$BASE/api/store/carts/$CART_ID/complete" \
   -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
 echo "$ORDER_JSON" | grep -q '"type":"order"'
@@ -452,16 +500,19 @@ curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
 
 ### POST /api/store/payment-collections/:id/payment-sessions
 
-- **Purpose** — mint (or repair) the provider session — idempotent per
-  provider. For Stripe the PaymentIntent is minted FIRST (idempotency key
+- **Purpose** — mint (or repair) the tender session — idempotent per
+  tender. For Stripe the PaymentIntent is minted FIRST (idempotency key
   = session id) so a Stripe session row can never exist without its
   intent; amount drift syncs the PI in place; terminal PIs self-heal by
-  rotation.
+  rotation. Method sessions share ONE NULL-provider row per collection —
+  switching methods updates its snapshot in place.
 - **Auth** — anon `x-client-id`.
-- **Request** — `{provider_id, data?, save_payment_method?}`. Keys the
-  server owns (`payment_intent_id`, `client_secret`, `status`,
-  `stripe_customer_id`, `setup_future_usage`) are stripped from `data` —
-  they cannot be forged from the client.
+- **Request** — `{provider_id? XOR payment_method_id?, data?,
+  save_payment_method?}` — exactly one tender. Keys the server owns
+  (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
+  `setup_future_usage`, and the method snapshot
+  `payment_method_id/name/kind`) are stripped from `data` — they cannot
+  be forged from the client.
 - **`save_payment_method`** — saves the card for future off-session
   renewal charges: the server resolves the CART'S customer (never a
   client-supplied id), ensures a Stripe Customer for them, and mints the
@@ -475,21 +526,26 @@ curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
   the plan selection / next to the payment element (e.g. "Your card will
   be saved for future subscription charges"). Re-initiating an existing
   session with the flag (or after a plan line appears) upgrades the live
-  intent in place (same `client_secret`). No-op on non-card providers
-  (COD/manual subscriptions renew offline). Never set the flag on
-  ordinary checkouts.
+  intent in place (same `client_secret`). No card to save on method
+  sessions (COD/manual subscriptions renew offline) — the account gate
+  still applies. Never set the flag on ordinary checkouts.
 - **Response** — `201 {payment_session}` when created, `200` when the
   existing one was returned/repaired: `{id, provider_id, amount,
   currency_code, status:"pending", authorized_at:null, data}` — for
   Stripe, `data` carries `payment_intent_id` + `client_secret` (mount
   Elements with it); with `save_payment_method` it also carries
-  `setup_future_usage: "off_session"` + `stripe_customer_id`. The session
-  `amount` is `collection.amount − gift_card_total` — the remainder.
+  `setup_future_usage: "off_session"` + `stripe_customer_id`. For a
+  method, `provider_id` is null and `data` carries the snapshot
+  (`payment_method_id`, `payment_method_name`, `payment_method_kind`).
+  The session `amount` is `collection.amount − gift_card_total` — the
+  remainder.
 - **Errors** — 404 `payment_collection_not_found`; 400 `invalid_provider`
-  (pp_giftcard) | `stripe_not_configured` | `customer_required` |
-  `validation_failed`.
-- **SDK** — `checkout.initiatePaymentSession(client, pcId, {provider_id,
-  save_payment_method?})`.
+  (pp_giftcard, or an id the catalog doesn't know — the dead pp_ ids land
+  here) | `payment_provider_disabled` | `payment_provider_not_in_region` |
+  `payment_method_not_in_region` | `stripe_not_configured` |
+  `customer_required` | `validation_failed`.
+- **SDK** — `checkout.initiatePaymentSession(client, pcId, {provider_id?,
+  payment_method_id?, save_payment_method?})`.
 
 ### POST /api/store/carts/:id/shipping-methods
 
@@ -532,8 +588,9 @@ PC2_ID=$(echo "$PC2_JSON" | grep -o '"id":"pc_[^"]*"' | head -1 | cut -d'"' -f4)
 SES_JSON=$(curl -sf -X POST \
   "$BASE/api/store/payment-collections/$PC2_ID/payment-sessions" \
   -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-  -d '{"provider_id":"pp_manual"}')
-echo "$SES_JSON" | grep -q '"provider_id":"pp_manual"'
+  -d '{"payment_method_id":"'"$PM_ID"'"}')
+echo "$SES_JSON" | grep -q '"provider_id":null'
+echo "$SES_JSON" | grep -q '"payment_method_name"'
 echo "$SES_JSON" | grep -q '"status":"pending"'
 
 # Error contract: the internal gift tender is not initiable.
@@ -564,7 +621,7 @@ PC3_ID=$(echo "$PC3_JSON" | grep -o '"id":"pc_[^"]*"' | head -1 | cut -d'"' -f4)
 
 curl -s -X POST "$BASE/api/store/payment-collections/$PC3_ID/payment-sessions" \
   -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-  -d '{"provider_id":"pp_manual","save_payment_method":true}' \
+  -d '{"payment_method_id":"'"$PM_ID"'","save_payment_method":true}' \
   | grep -q '"code":"customer_required"'
 ```
 
@@ -597,15 +654,15 @@ rotates only on `succeeded`/`canceled`/`requires_capture`/missing.
   exercised by `tests/store/checkout-rules.test.ts`.
 - **`account_required` (403)** — requires `accounts_mode='required'` on
   the store; exercised by `tests/store/customer-accounts-policy.test.ts`.
-- **COD fee** — requires the admin COD integration
-  (`{config:{fee_amount, fee_label}}`); exercised by
-  `tests/store/checkout-cod-fee.test.ts` and
-  `tests/store/checkout-orchestration.test.ts` (fee-inclusive session on
-  prepare with `pp_cod`).
+- **Payment method fee** — any method may carry `fee_amount`/`fee_label`
+  (the COD method included); exercised by
+  `tests/store/payment-method-fee.test.ts` (method-switch switches the
+  fee) and `tests/store/checkout-orchestration.test.ts` (fee-inclusive
+  session on prepare with the COD method).
 
 ## Cleanup / accretion note
 
-This page creates two carts and completes two `pp_manual` orders on the
+This page creates two carts and completes two method-tender orders on the
 shared dev tenant — the same inert accretion the checkout test suites
 produce (no store-facing delete exists for either; suites always create
 their own carts/orders and never re-read foreign ones).

package/template/app/docs/collections.md

@@ -1,4 +1,4 @@
-# Collections & membership listings
+# Collections
 
 Curated product groupings (manual or smart). The membership listing —
 `/collections/:id/products` — is the collection page's data source: it reads