docs/storefront/ — the bulletproof 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 setting, every component contract. If a storefront can't be built from these files alone, the fix is a doc fix, never tribal knowledge.

Start at BUILD-A-STOREFRONT.md — the runbook. Domain files below are its reference chapters.

Executable-docs contract (docs-truth CI)

Docs that can lie aren't bulletproof, so every ```bash block in every file here is extracted and executed against the real test server by tests/docs/storefront-curls.test.ts. A drifted doc FAILS the build.

Rules for doc authors (agents included):

1. All ```bash blocks in one file form ONE script, executed top-to-bottom with bash -euo pipefail. Later blocks may use variables exported by earlier blocks (CART_ID=$(curl … | grep -o …)).
2. The harness pre-exports: BASE (test-server origin), CLIENT_ID (dev tenant id), PUBLISHABLE_KEY (the B2B-channel dev key — channel-scoped, use only where the doc discusses key scoping).
3. Every curl uses -sf (silent + fail-on-HTTP-error) unless the block demonstrates an error case — then capture the status explicitly (-o /dev/null -w '%{http_code}') and assert it (test "$STATUS" = 404).
4. Assert shape, not just liveness: pipe to grep -q '"key"' (or node -e for anything structural). A block that checks nothing proves nothing.
5. A block that must NOT run (illustrative only, external side effects) starts with # doc-noexec on its first line. Use sparingly — every noexec block is a hole in the truth gate.
6. Blocks must be idempotent-safe on the shared dev tenant: create what you read, suffix names with $RUN (pre-exported unique stamp), and clean up in a final block when you created durable rows.

Per-domain file format

One file per domain. For each endpoint, in order:

• Purpose — one sentence, when a storefront calls it.
• Auth — which headers (anon x-client-id / publishable key / Bearer).
• Request — method, path, query/body shape (jsonc block).
• Response — shape (jsonc block), with field notes.
• Working curl — executable per the contract above.
• Errors — status + code for every contract-listed failure.
• SDK — the @barter/storefront/api function that wraps it.
• Components — which @barter/storefront UI components consume it.
• Settings — admin settings that change its behavior (checkout rules, locales, consent, accounts mode…).

Files

File	Domain
BUILD-A-STOREFRONT.md	The agent runbook — blank app → completed checkout
products.md	Products, variants, pricing context
search.md	Search, facets, related products
collections.md	Collections + membership listings
categories.md	Categories, tags, types
regions.md	Regions, currencies, locales
carts.md	Cart lifecycle + line items
gift-cards.md	Gift-card tender on carts
checkout.md	Shipping options, payment providers/collections, prepare-checkout orchestration, complete
orders.md	Order reads, display-id lookup, transfers
customers.md	Customer profile, addresses, documents
subscriptions.md	Subscription portal: schedule control, contract edits, payment-method recovery
auth.md	Passwordless code login + session discipline
content.md	Pages + blogs
menus.md	Navigation menus
metaobjects.md	Merchant-defined content types
reviews.md	Review widget, token wizard, photo rewards
integrations.md	Store config: carriers, COD, tracking block, lockers
consent.md	Consent Mode v2 banner config
redirects.md	404-path URL redirects
components.md	UI component families: contracts + required SDK calls