@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/README.md

@@ -1,18 +1,23 @@
 ---
 title: "@thorprovider/storefront"
-purpose: "Deterministic storefront scaffolder and installable command suite for Thor Commerce"
-lastReviewed: "2026-10-01"
+purpose: "Deterministic storefront scaffolder and installable skill suite for Thor Commerce"
+lastReviewed: "2026-10-14"
 ---
 
 # @thorprovider/storefront
 
-Deterministic storefront scaffolder and installable command suite for Thor Commerce.
+Deterministic storefront scaffolder and installable skill suite for Thor Commerce.
 
-`npx @thorprovider/storefront create <dir>` scaffolds a complete, buildable storefront
-and installs the `/sf-*` OpenCode command suite into `<dir>/.opencode/` in the same
-run. It ships static project templates, a recipe registry, and vendored skills, and
-installs them into any project's `.opencode/` directory. Nothing else from the Thor
-Commerce monorepo is required at generation time.
+`npx @thorprovider/storefront create <dir>` scaffolds a complete, buildable storefront,
+installs its OpenCode skill suite into `<dir>/.opencode/skills/`, and writes a managed
+root `AGENTS.md` — all from static templates, a recipe registry, and vendored skills,
+with nothing else from the monorepo needed at generation time.
+
+A generated storefront ships **no `/sf-*` commands**. Guidance lives in the root
+`AGENTS.md`, which states the authority rules and routes an intent (add a view, change
+the theme, add a feature, connect a backend) to the skill that owns the procedure: open
+the project in OpenCode and ask in natural language. The `storefront` CLI stays the
+structural authority.
 
 This README is organised in two parts:
 
@@ -36,43 +41,50 @@ storefront it generates resolves its own dependencies from the registry.
 | Package manager | Yarn with the `node-modules` linker (for generated projects) |
 | OpenCode | a version that supports project skills in `.opencode/skills/` |
 | OS | macOS, Linux, Windows (via WSL) |
-| Network | access to the npm registry (the generated project installs its dependencies from it) |
+| Network | access to the npm registry — only for the first scaffold per machine (repeat scaffolds can run offline, see [troubleshooting](#flaky-network-etimedout)) |
 
 Generated projects use Yarn with the `node-modules` linker, not Plug'n'Play (PnP).
 Yarn 4 defaults to PnP, which Next.js 16's Turbopack cannot resolve from, so the
 scaffold writes a `.yarnrc.yml` setting `nodeLinker: node-modules` before installing
 dependencies. PnP is not used. You do not need to configure this yourself.
 
+The same `.yarnrc.yml` hardens installs for unreliable networks: `httpRetry: 10`
+and `networkConcurrency: 8`. The first successful scaffold warms the global Yarn
+cache (`~/.yarn/berry/cache`); repeat scaffolds then download no packages, and
+`YARN_ENABLE_OFFLINE_MODE=1` drops even the metadata requests.
+
 ### Install
 
-Run the scaffolder directly from npm — no global install required. `npx` and
-`yarn dlx` are equivalent:
+Run the scaffolder directly from npm — no global install required; the equivalent is
+`yarn dlx @thorprovider/storefront`:
 
 ```bash
 npx @thorprovider/storefront create my-shop \
   --site-name "My Shop" \
-  --backend-url http://localhost:9000 \
   --preset maia
 ```
 
-```bash
-yarn dlx @thorprovider/storefront create my-shop --preset maia
-```
-
 The first positional argument is the target directory: it is created if missing, and
 it is where `.opencode/`, the Next.js app, and `lib/<name>/` live. Run the command
 from the parent directory you want the project created in.
 
 In a terminal, `create` runs an interactive wizard for any input you omit (name,
-site name, backend URL, preset — Maia is preselected). Without a terminal, every
-required input must be passed as a flag; the command fails fast and writes nothing
-rather than guessing. Brand color is never asked by the wizard — apply it later with
-`/sf-theme`, or pass `--brand` on the command line.
+site name, preset — Maia is preselected); an empty prompt accepts the suggested
+default (name from the target basename, site name from its Title Case). Without a
+terminal every required input must be a flag — the command fails fast and writes
+nothing. Brand color is never prompted: pass `--brand`, or change it later in natural
+language (the theme skill runs `storefront theme`).
+
+`create` is structural and offline: it scaffolds a storefront that runs in **mock
+mode** with no backend. Connecting a real backend is a separate, re-runnable step —
+run `storefront setup` from inside the project (see [Backend
+configuration](#backend-configuration)).
 
 Once the package is installed as a dependency, the shorter binary form is available:
 
 ```bash
-storefront create my-shop --preset maia    # scaffold + install the suite
+storefront create my-shop --preset maia    # scaffold + install the suite (mock mode)
+storefront setup --publishable-key <key> --region-id <id>   # connect a real backend
 storefront update                          # refresh an existing install
 storefront doctor                          # report the recorded version and status
 ```
@@ -87,7 +99,6 @@ project root that will hold `.opencode/`:
 storefront create my-shop \
   --name my-shop \
   --site-name "My Shop" \
-  --backend-url http://localhost:9000 \
   --preset maia \
   [--brand orange]
 ```
@@ -96,25 +107,24 @@ storefront create my-shop \
 | --- | --- | --- |
 | `<dir>` (positional) | target project directory (created if missing) | required |
 | `--name <name>` | kebab-case storefront name = `lib/<name>/` = `__STOREFRONT__` | prompted in the wizard |
-| `--site-name <name>` | human site name (`__SITE_NAME__`) | `<name>` |
-| `--backend-url <url>` | Medusa backend URL | `http://localhost:9000` |
+| `--site-name <name>` | human site name (`__SITE_NAME__`) | Title Case of `<name>` (`my-shop` → `My Shop`) |
 | `--preset <preset>` | visual preset: `maia`, `nova`, `vega`, `luma`, `lyra`, `mira` | prompted in the wizard (Maia preselected) |
-| `--brand <color>` | named brand color overriding preset primary/nav/ring tokens (never prompted) | none |
+| `--starter` | seed the full curated composition — every curated view and feature — instead of the minimal `home`+`cart` baseline | off |
+| `--brand <color>` | named brand color (`orange`, `blue`, …) applied as a chromatic primary family (primary/foreground/ring/nav) over the preset tokens (never prompted) | none |
 | `--force`, `-f` | overwrite files that already exist | off |
 
-The pipeline runs: preconditions → Next.js base → shadcn base with the preset →
-`.yarnrc.yml` (`nodeLinker: node-modules`) → dependency install → template copy +
-placeholder substitution → default-page removal → `.env.local` + theme → suite
-install into `.opencode/`.
+The pipeline runs: preconditions → Next.js base (files only) → `.yarnrc.yml`
+(`nodeLinker: node-modules`) → shadcn base with the preset → dependency install →
+template copy + placeholder substitution → mock `.env.local` + theme → suite install.
 
-Same inputs produce a byte-identical tree (verified by recursive `diff -r`). Running
-`create` twice with different inputs is the only reason the output differs.
+Same inputs produce a byte-identical tree (verified by recursive `diff -r`).
 
-The suite install copies `commands/` and the shipped skills under `skills/` (own
-skills and vendored skills, flat) into `<dir>/.opencode/`. It verifies its own
-generated copies against their source before copying, records the installed version
-in `.opencode/storefront.json`, and is idempotent: use `--force` to overwrite files
-that already exist.
+The suite install copies the shipped skills (own and vendored, flat) into
+`<dir>/.opencode/skills/`, verifying generated copies against their source first. It
+records the installed version in `.opencode/storefront.json` and is idempotent
+(`--force` overwrites). `create` also writes the managed root `AGENTS.md` from the
+derived template path, so `storefront sync` refreshes it and `storefront doctor`
+reports drift.
 
 ### Run the storefront
 
@@ -125,31 +135,70 @@ cd my-shop
 yarn dev
 ```
 
-The storefront renders its home view — hero, benefits, and category sections — using
-only `@thorprovider/blocks` for UI and `@thorprovider/adapters` for data. Then grow
-it incrementally from OpenCode:
+A fresh `create` seeds `home` + `cart` (home hero/benefits/category sections, a
+navbar-owned cart sheet, a standalone `/cart` review route). Pass `--starter` to
+seed the full curated composition instead — every curated view and feature, read
+from the registry, held units excluded. Everything renders with only
+`@thorprovider/blocks` (UI) and `@thorprovider/adapters` (data). Then grow it by asking
+in natural language — the `AGENTS.md` router maps each intent to a skill that delegates
+the structural write to the CLI:
 
 ```
-/sf-add-view product      # add a view from its recipe
-/sf-view home add a testimonials section   # modify an existing view
-/sf-theme                 # colors, typography, identity
+add a product view                     # the view skill runs `storefront view add product`
+add a testimonials section to home     # the view skill composes the section, then syncs
+change the theme to dark with a teal brand   # the theme skill runs `storefront theme`
+connect the backend to my Medusa store # the setup skill runs `storefront setup`
 ```
 
 ### Backend configuration
 
-Generated projects expect a Medusa backend. `create` writes a `.env.local` with the
-backend URL you passed and blank placeholders for the rest:
+`create` writes a git-ignored `.env.local` that starts the store in **mock mode** —
+no backend, a generated cookie secret, the store identity — plus a committed
+`.env.example` documenting every variable:
+
+```bash
+# .env.local (git-ignored) — written by create
+THOR_DATA_SOURCE=mock
+THOR_STORE_ID=my-shop
+THOR_SESSION_SECRET=<generated per install>
+```
+
+Mock mode is complete: views and the cart render from labelled demo data with no
+configuration. To connect a real backend, run `storefront setup` from inside the project:
 
 ```bash
-MEDUSA_BACKEND_URL=http://localhost:9000
-MEDUSA_REGION_ID=
-MEDUSA_PUBLISHABLE_KEY=
+storefront setup --publishable-key <key> --sales-channel-id <id> --region-id <region-id> [--backend-url <url>]
 ```
 
-Set `MEDUSA_REGION_ID` and `MEDUSA_PUBLISHABLE_KEY` as needed, then restart
-`yarn dev`. The storefront shows no catalog data until these are set (see
-[Backend not configured](#backend-not-configured)). During local development you can
-use the `mock` adapter data source instead of a live backend.
+In a terminal, `setup` prompts for the backend URL, publishable key, sales channel id,
+and region. It takes the sales channel id as an explicit input (Medusa admin → Settings
+→ Sales Channels), derives the region's currency (`GET /store/regions`), then **upserts**
+only the keys it manages — `THOR_STORE_ID`, `THOR_SESSION_SECRET`, and user additions are
+untouched. It is re-runnable (rotate the key, change the channel or region, re-point the
+backend). Without a publishable key it stays in mock mode; without a channel id it reports the missing input and stays in mock mode.
+
+The store context is **explicit and validated** in real mode: `MEDUSA_SALES_CHANNEL_ID`
+scopes the store, `MEDUSA_REGION_ID` supplies currency, countries, and shipping, and
+`MEDUSA_CURRENCY_CODE` (ISO 4217) comes from the environment and is **never hardcoded**.
+`THOR_SESSION_SECRET` is the host-only cookie signing secret (≥16 chars, 32 recommended).
+
+> **Renamed:** the currency variable was `THOR_CURRENCY_CODE` and is now
+> `MEDUSA_CURRENCY_CODE`. An existing store renames it in `.env.local`, or re-runs
+> `storefront setup`, which writes it.
+
+`THOR_DATA_SOURCE` selects the mode **explicitly** and is never inferred from a failure.
+`mock` renders labelled demo data and resolves a fixture store context in code (channel
+`mock-sales-channel`, region `mock-region-us`, currency `USD`), so no context variables
+are required. `medusa` uses the real backend: a missing provider or invalid config is a
+**visible error** — never a silent fallback to demo data. Run `storefront setup`, then
+restart `yarn dev`.
+
+The guest flow is backend-authoritative end to end: the signed host cookie binds a
+persistent backend cart; the PDP adds the explicitly selected variant; the cart and
+checkout render the backend's totals; checkout applies the one approved manual TEST
+provider and completes the cart with its native discriminator. An ambiguous completion
+is never retried — the shopper reconciles the committed cart, and the active cart is
+cleared only after a confirmed order. No card data is collected at launch.
 
 ### Troubleshooting / Known Issues
 
@@ -157,90 +206,201 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 
 #### Ancestor `.opencode/`
 
-- **Cause**: the project is created under a directory tree in which an ancestor
-  directory already contains a `.opencode/`.
-- **Symptom**: OpenCode resolves the wrong command set — `/sf-add-view`, `/sf-view`,
-  and `/sf-theme` run commands from the ancestor's `.opencode/` instead of the ones
-  this package installed, so you see stale or unrelated behaviour.
-- **Remedy**: scaffold in a clean root with no ancestor `.opencode/` (for example a
-  fresh directory outside the monorepo), or remove/relocate the ancestor `.opencode/`
-  before opening the project.
+- **Cause**: an ancestor directory already contains a `.opencode/`.
+- **Symptom**: OpenCode resolves the wrong skill set or an ancestor's `AGENTS.md`, so you see stale or unrelated behaviour.
+- **Remedy**: scaffold in a clean root with no ancestor `.opencode/`, or remove/relocate the ancestor `.opencode/` before opening the project.
 
 #### Non-empty target directory
 
-- **Cause**: `create` runs against a directory whose `lib/<name>/` already exists (a
-  previous scaffold with the same name), or whose root is already a Next.js project.
-- **Symptom**: the run stops at the preconditions stage with
-  `lib/<name>/ already exists — refusing to overwrite`.
-- **Remedy**: choose a different `--name`, or remove the existing `lib/<name>/`
-  directory. To extend an existing storefront instead of creating one, use
-  `/sf-add-view`. `create-next-app` also refuses to initialize a directory that is
-  already a Next.js project unless it can reuse it; run `create` in an empty directory.
+- **Cause**: `lib/<name>/` already exists, or the root is already a Next.js project.
+- **Symptom**: the run stops at the preconditions stage with `lib/<name>/ already exists — refusing to overwrite`.
+- **Remedy**: choose a different `--name`, or remove the existing `lib/<name>/`. To extend an existing storefront, run the `storefront` CLI from inside it (or ask in natural language — see `AGENTS.md`); run `create` in an empty directory.
 
 #### Missing or invalid `--preset`
 
-- **Cause**: `--preset` was omitted (in a non-interactive run) or the value is not one
-  of the recognized presets.
-- **Symptom**: the run stops at the input-validation stage with
-  `--preset must be one of: maia, nova, vega, luma, lyra, mira`.
-- **Remedy**: pass `--preset` with one of `maia`, `nova`, `vega`, `luma`, `lyra`,
-  `mira`. In a terminal the wizard preselects `maia`, so the preset is only required
-  on the command line for non-interactive runs.
+- **Cause**: `--preset` was omitted (non-interactive) or is not a recognized preset.
+- **Symptom**: the run stops at input validation with `--preset must be one of: maia, nova, vega, luma, lyra, mira`.
+- **Remedy**: pass one of those presets. In a terminal the wizard preselects `maia`, so the flag is only required for non-interactive runs.
 
 #### Yarn Plug'n'Play / linker
 
 - **Cause**: a generated project installed with Yarn's default PnP linker.
-- **Symptom**: Next.js 16's Turbopack fails to resolve the Next.js package
-  (`Could not find the Next.js package`).
-- **Remedy**: this is why `create` writes `.yarnrc.yml` with
-  `nodeLinker: node-modules` before installing. If you set up the project manually,
-  add that file and re-run `yarn install` so a real `node_modules/` is materialized.
-  Do not use PnP.
+- **Symptom**: Next.js 16's Turbopack fails to resolve Next.js (`Could not find the Next.js package`).
+- **Remedy**: `create` writes `.yarnrc.yml` with `nodeLinker: node-modules` before installing; if you set the project up manually, add that file and re-run `yarn install`. Do not use PnP.
+
+#### Flaky network (ETIMEDOUT)
+
+- **Cause**: an unstable connection stalls registry requests mid-transfer (`RequestError … AggregateError [ETIMEDOUT]`).
+- **Remedy**: the scaffolded `.yarnrc.yml` sets `httpRetry: 10` and `networkConcurrency: 8`; that run warms the global cache (`~/.yarn/berry/cache`), which later scaffolds reuse. For offline re-scaffolding run `YARN_ENABLE_OFFLINE_MODE=1 storefront create <dir> …`; the first scaffold per machine still needs one successful online run.
 
 #### Backend not configured
 
-- **Cause**: `MEDUSA_REGION_ID` / `MEDUSA_PUBLISHABLE_KEY` (or a reachable backend) are
-  not set in `.env.local`.
-- **Symptom**: the storefront renders its layout but shows no catalog data.
-- **Remedy**: fill in the variables in [Backend configuration](#backend-configuration)
-  and restart `yarn dev`, or use the `mock` adapter data source during local
-  development.
+- **Cause**: `THOR_DATA_SOURCE=medusa` but `MEDUSA_BASE_URL`/`MEDUSA_PUBLISHABLE_KEY` are missing, empty, or unreachable (for example, a store still in mock mode).
+- **Symptom**: the storefront renders a visible error notice (`role="alert"`) instead of backend data; real-mode failures never degrade to a fake catalog.
+- **Remedy**: run `storefront setup` from inside the project to write the real-mode variables (see [Backend configuration](#backend-configuration)), then restart `yarn dev`. To stay offline, leave `THOR_DATA_SOURCE=mock`.
 
 ---
 
 ## What gets installed
 
 ```
-<project>/.opencode/
-  storefront.json            # { version, installedAt } — what generation is installed
-  commands/
-    sf-add-view.md
-    sf-view.md
-    sf-theme.md
-  skills/
-    sf-view-gen/             # assets/templates/views/, assets/recipes/, scripts/validate.mjs
-    sf-theme-gen/            # assets/
-    nextjs-shadcn/
-    shadcn-theming/
-    shadcn-component-discovery/
-    storefront-best-practices/
-    building-storefronts/
+<project>/
+  AGENTS.md                  # managed (derived): RULE 0 rules + intent router
+  .opencode/
+    storefront.json          # install record: version, pinning, owned asset BOM
+    skills/
+      storefront-workflow/   # four phases, CLI/manifest authority; references/ = design/mobile/SEO
+      sf-view-gen/           # view generation; references/ = json-render + views.md
+      sf-feature/            # feature bundles (feature-owned views + mounts)
+      sf-theme-gen/          # theme; references/ = theming guidance
+      sf-setup/              # connect/re-point a Medusa backend via `storefront setup`
 ```
 
-Each skill carries the templates, recipes, and scripts it uses inside its own
-directory. Skills address them by relative path, so nothing needs the package to be
-located on disk at generation time.
+The suite ships exactly these five operative skills plus their scoped references;
+the retained generic knowledge is loaded explicitly by the owning skill and is not
+separately installable. The workflow model is
+[`skills/storefront-workflow/SKILL.md`](./skills/storefront-workflow/SKILL.md).
+`create`/`update` also provision the pinned `@fission-ai/openspec` suite as a co-tenant (`openspec init --tools opencode` writes `openspec/`, the `openspec-*` skills, and the `opsx-*` commands, then the CLI seeds a storefront-aware `openspec/config.yaml`); the suite never installs over or removes those co-tenanted files. A non-trivial customization runs through the spec-driven loop surfaced as explore → plan → build → verify → inform, while a deterministic CLI change recorded in `storefront.config.json` needs no change and completion waits on `storefront sync` + `storefront doctor`.
 
-## Commands
+## Workflow: bootstrap → compose → customize → verify
 
-| Command | Purpose |
-| --- | --- |
-| `/sf-add-view <view>` | Add one view incrementally (`product`, `category`, `checkout`, `user-panel`) |
-| `/sf-view <view> <change>` | Modify an existing view's spec, preserving structure |
-| `/sf-theme` | Customize OKLCH color tokens (light/dark), typography, and identity metadata |
+The project manifest (`storefront.config.json`) is the structural source of truth;
+the `storefront` CLI is the only writer of derived files; the developer/agent edits
+only user-owned files and the bounded external surface. Read the installed
+`storefront-workflow` skill for the full model. Every command runs from inside the
+project (no directory argument).
+
+| Phase | Authority | Command |
+| --- | --- | --- |
+| **Bootstrap** | CLI only | `npx @thorprovider/storefront create <dir> --name <name> --preset <preset>` |
+| **Compose** | CLI only (agents choose, CLI writes) | `view add\|remove`, `feature add\|remove`, `section add\|remove\|move`, `theme` |
+| **Customize** | developer/agent | edit user-owned `content.ts`/`props.ts`/`data.ts`/`schema.ts`/`mappers.ts` |
+| **Verify** | CLI + build | `npx @thorprovider/storefront sync`, `doctor`, `yarn build` |
+
+**Ownership classes.** *Derived* files (`views/index.ts`, `views/registry.ts`,
+`index.tsx`, `registry.tsx`, `catalog.ts`, `runtime.ts`, `spec/index.ts`,
+`state.ts`, `handlers.ts`, `features/*/adapter.ts`) are CLI-regenerated and never
+hand-edited. *User-owned* files (content, props, data, local schema, mappers)
+survive `sync`. *External* files (`app/layout.tsx`, `app/globals.css`) expose a
+**bounded** surface — theme tokens/foreground pairs, fonts, global identity — that
+must preserve the CLI-managed wiring (stylesheet import, provider/mode markers,
+block token contract); the CLI appends it idempotently.
+
+**Curated composition.** The CLI registry (`storefront views --json`,
+`features --json`, `recipes --json`) is the authority for what is installable.
+Curated MVP views: `home`, `product`, `cart`, `category`, `checkout`, `account`,
+`static`. Curated MVP features: `checkout` (owns the `checkout` view —
+`view add checkout` is rejected, use `feature add checkout`), `customer-auth`
+(owns `account`), `static-pages` (owns `static`), and the mount-only `benefits`,
+`catalog-search`, `category-filters`, and `navigability`. `recommendations` is
+held post-MVP and rejected before any write. `create` seeds `home` and `cart`;
+`--starter` seeds every curated view and feature. Home editorial (`faq`, `cta`) and
+data-bound `products` sections: see [Product sections](docs/product-sections.md).
+
+**Cart lifecycle and checkout independence.** The cart review is a normal view,
+not a shell element: `view add cart` installs it, `view remove cart` drops it
+(which also hides the lateral's "View cart" action and leaves `/cart` unrouted;
+the navbar icon still opens the compact lateral). `sync` never silently adds it
+to an existing store — upgrading is an explicit `view add cart`. Cart and
+checkout are independent: review works without checkout (its action is hidden),
+and adding `checkout` never adds the cart view. The CLI derives
+`cartViewAvailable`/`checkoutAvailable` from the installed views/features into
+`composition.ts`, which the generated wiring reads.
+
+**Prerequisites and pinning.** Node `>=20.9.0`, `node-modules` linker, and the
+canonical Yarn pinned in the generated `package.json` as
+`"packageManager": "yarn@4.5.1"` (Corepack resolves it; the scaffold runs every
+install under that version). The generated project pins an exact compatible
+candidate toolset and installs the `@thorprovider/*` packages from the npm
+registry by default. `--packs <dir>` is an optional path for local candidates
+(published or unpublished): it maps each dependency to a packed tarball via Yarn `resolutions`
+(no workspace import), and the CLI verifies every tarball before writing
+anything — the manifest `name`/`version` must match the expected toolset, and the
+packed `@thorprovider/runtime` must export every value the generated host
+`commerce.ts` imports; a stale or mismatched pack is refused with a named code
+before any file is written. No package-manager safety policy is suppressed: the generated
+`.yarnrc.yml` sets no `npmPreapprovedPackages`, and the pinned versions are
+intended to be published past Yarn's age gate. `doctor` reports the observed linker/Node/Yarn
+against the declared ranges and exits non-zero on a mismatch instead of a false
+clean stamp.
+
+### Configurable composition (E1)
+
+The composition engine is a truthful semantic catalog plus a structured
+`inspect → plan → apply` boundary. Run these inside the project:
+
+```bash
+storefront inspect --json
+storefront plan --operations operations.json [--out plan.json] [--json]
+storefront apply --plan plan.json [--json]
+```
+
+- **`inspect --json`** is read-only and deterministic: `formatVersion: 1` /
+  `catalogVersion: 1`, every slot/variant with `executable` or `held` + a reason, and a
+  capability catalog with `verified`/`unverified` state. A held or unverified unit is
+  never reported as available.
+- **`plan`** validates the whole intended state and emits before/after fingerprints and
+  the exact derived-file diff. Without `--out` it writes nothing and prints the plan to
+  stdout; with `--out` it writes only a safe plan artifact. `--out` is refused
+  (`E_OUT_PATH_REFUSED`) for owned, derived, secret-bearing, or installation paths and
+  for the operation input.
+- **`apply`** is the only composition mutation. It applies from the recorded
+  before-state, reports a **verified no-op** at the recorded after-state, and rejects
+  anything else as stale (`E_STALE_PLAN`); concurrent runs are serialized by a local
+  lock. A handled write failure rolls back every touched file. An abrupt process kill is
+  **not** crash-atomic — the manifest is written last and `sync` detects and repairs the
+  divergence.
+
+The operations envelope is `{ "formatVersion": 1, "operations": [ ... ] }` (missing or
+different `formatVersion` → `E_INVALID_ENVELOPE`). Operation names are
+`view.add|remove|configure` and `feature.add|remove|configure`; `view add|remove` and
+`feature add|remove` remain thin aliases over the same engine, and so do
+`section add|remove|move`/`sections [<view>]` over `section.add|remove|reorder` (see [Product sections](docs/product-sections.md)).
+
+**What E1 proves.** The only executable non-default swap is `home.benefits`
+`Feature1 → Feature2` (identical `BenefitsItem[]` data shape, no bridge); every bridged
+variant is `held`. A feature may declare a `config` and `mounts`; the bounded `benefits`
+feature mounts at `home.benefits` with `{ "presentation": "compact" | "detailed" }`,
+claims the slot exactly once, and preserves user-owned content on removal. Checkout
+keeps its existing feature-owned route only — unproven checkout variants or route
+options are rejected (`E_UNPROVEN_CHECKOUT_OPTION`). The category filter's action is
+**held** (`unverified`, owner E2) and its control is omitted rather than exposed as a
+no-op; catalog search/filters (E2) and composable sections (E3) are **not** implemented
+here.
+
+## Agent guidance and skills
+
+A generated storefront ships a managed root `AGENTS.md` and no `/sf-*` commands.
+`AGENTS.md` states the non-negotiable authority rules (RULE 0) and routes each intent
+to the skill that owns the procedure; the skill then delegates the structural write to
+the `storefront` CLI.
+
+| Intent | Skill | CLI it drives |
+| --- | --- | --- |
+| Add or remove a view; compose a view's sections; edit user-owned content/props/data | `sf-view-gen` | `storefront view add\|remove`, `section …`, `views --json` |
+| Change colors, theme mode, typography, radius, presets, or identity/SEO metadata | `sf-theme-gen` | `storefront theme` (`--brand`, `--primary`, `--accent`, `--radius`, `--font-sans`, `--set`, `--preset`, `--import`, `--export`, `--mode`) |
+| Add or remove a feature bundle (e.g. `checkout`) | `sf-feature` | `storefront feature add\|remove` |
+| Connect or re-point a Medusa backend | `sf-setup` | `storefront setup` |
+| Edit a view's content/props/data, map props or data, reshape composition, or any change whose acceptance is not a CLI assertion (non-trivial) | `storefront-workflow` | the spec-driven loop, surfaced as **explore → plan → build → verify → inform** |
+
+Scaffolding is `npx @thorprovider/storefront create <dir>`; connecting a real backend is
+`storefront setup` from inside the project (see [Backend configuration](#backend-configuration)).
 
-Scaffolding itself is `npx @thorprovider/storefront create <dir>` — there is no
-`/sf-init` command; the wizard lives in the CLI and is deterministic.
+## Philosophy: determinism first; the LLM only where there is judgment
+
+A storefront task is one of three kinds, and the tool follows the kind:
+
+- **Deterministic** (output is a pure function of input) → a CLI subcommand with flags
+  (e.g. `storefront theme --brand orange --radius 0.75rem`). Repeatable, reviewable, no model in the loop.
+- **Mixed** → split it: the script applies the deterministic part, the LLM decides the
+  judgment part (the `sf-theme-gen` skill chooses the brand color; `storefront theme --brand` applies it).
+- **Pure judgment** → an `sf-*` skill (e.g. `sf-view-gen`): variant selection, copy, and
+  layout choices live here.
+
+**Test criterion**: if you can assert the result without a model ("after this, the file
+contains X"), it must be a script; if you cannot, it is skill work. LLM edits are
+non-deterministic and expensive to review, so keep the judgment-heavy work where a
+model adds value and make the rest a reliable script.
 
 ## Design guarantees
 
@@ -252,40 +412,60 @@ Scaffolding itself is `npx @thorprovider/storefront create <dir>` — there is n
   installer copies anything.
 - **Stack-constrained**: UI comes only from `@thorprovider/blocks`; data only from
   `@thorprovider/adapters` and `@thorprovider/runtime/commerce`.
-- **Varied output**: a recipe registry lets the skills pick block variants and optional
-  sections (testimonials, FAQ, statistics, logo cloud, pricing) from your description,
-  so sites are not identical.
+- **Truthful output**: a versioned recipe/catalog exposes every slot and variant with an
+  `executable` or `held` status and a reason. Only executable variants render; a held
+  variant is rejected before any write, so a site is never presented with a choice that
+  silently does nothing. E1 ships a small proven set (`home.benefits` `Feature1`↔
+  `Feature2`); bridged variants and optional sections stay held.
 
 ## Generated project structure
 
-Each view is a self-contained module. Shared files compose whatever the view barrel
-exports and never name a view, so adding one is a copy plus a single registration.
+Each view is a self-contained module. The CLI generates the barrels and wiring
+from the manifest; shared files compose whatever the barrel exports and never name
+a view. Only user-owned files (marked `*`) are hand-edited.
 
 ```
 lib/<name>/
-  catalog.ts, registry.tsx, runtime.ts, handlers.ts, state.ts   # shell; compose the barrel
-  mappers.ts                                                   # CardProduct -> FeaturedProduct / CategoryCard
-  spec/index.ts, spec/page-root.ts, spec/types.ts               # routes built from the barrel
+  catalog.ts, registry.tsx, runtime.ts, handlers.ts, state.ts   # derived shell; compose the barrel
+  mappers.ts *                                                  # user-owned: CardProduct -> block props
+  shell/
+    content.ts *                                                # user-owned: wordmark accents + navbar note + footer newsletter
+    props.ts *                                                  # user-owned: shell element props
+  spec/index.ts, spec/page-root.ts, spec/types.ts               # derived routes built from the barrel
   views/
-    index.ts            # barrel: export const views: ViewModule[] = [home, ...]
-    types.ts            # ViewModule contract
-    sections/*.tsx      # optional-section fragments (testimonials, faq, ...)
-    home/index.tsx      # one folder per view
-    product/index.tsx
-    category/index.tsx
-    checkout/index.tsx
-    user-panel/index.tsx
+    index.ts            # derived server barrel: export const views: ViewModule[] = [home, ...]
+    registry.ts         # derived client barrel: viewRegistries (no server loaders)
+    types.ts            # ViewModule / ViewRegistry contract
+    home/
+      index.tsx         # derived thin wrapper (imports ./content, ./props, ./data)
+      registry.tsx      # derived 'use client' component mappings
+      content.ts *      # user-owned copy/data
+      props.ts *        # user-owned element props
+      data.ts *         # user-owned loader shaping
+      schema.ts *       # user-owned local Zod mirror
+    product/ category/ checkout/   # same shape
 ```
 
-A view folder ships the package's default block variants; `/sf-add-view` picks the
-intent/variant from your description (validated by the skill's `scripts/validate.mjs`)
-and substitutes only the imported block identifier. The scaffold templates live at
-the package root, and the view templates travel inside the skills that use them:
+The shell's derived `spec/index.ts` imports the user-owned `shell/props.ts`
+(`...navbarShellProps`, `...footerShellProps`) and composes it **last**, so the brand
+surface and footer copy are configured without touching derived files. Configure
+`shell/content.ts` (`logoAccent`/`brandAccent`, `navbarClassName`/`footerClassName`,
+`brandDescription`, `linkColumns`); defaults are neutral and link only to served routes
+(`/`, `/categories`, `/checkout`), never dead `#` links. `newsletter` defaults to `false`
+and the scaffold ships no submit callback, so a content-only newsletter renders no form
+— never a fake form. `shippingNote` defaults to `''`: while it is empty (and there are
+no utility links) the navbar renders no utility strip, so no placeholder note is shown.
+
+A view's derived `index.tsx` imports the user-owned `content.ts`/`props.ts`/
+`data.ts`, so a customization changes real spec/loader output and survives `sync`.
+`npx @thorprovider/storefront view add <view>` chooses the intent/variant from the
+registry, writes the derived files, and regenerates the barrels; the agent edits
+only the user-owned files. The scaffold templates live at the package root:
 
 ```
-assets/templates/app/                                 # shell (copied by `create`)
-assets/templates/views/home/                          # home (copied by `create`)
-skills/sf-view-gen/assets/templates/views/<view>/     # the other views (copied by /sf-add-view)
+assets/templates/app/                                 # shell (generated by `create`)
+assets/templates/views/home/                          # home (generated by `create`)
+assets/templates/views/<view>/                        # the other views (generated by `storefront view add`)
 ```
 
 ## Development
@@ -301,24 +481,13 @@ node bin/storefront.js doctor <tmp>                # report the recorded version
 node scripts/render-templates.mjs <tmp> my-shop    # re-render templates only (no install; fast loop)
 ```
 
-`scripts/render-templates.mjs` is the same renderer the `create` action uses for
-stage 6. It copies the templates and substitutes placeholders without touching
-dependencies, so iterating on a template against a persistent project (e.g.
-`projects/<name>/`) costs seconds and no network.
-
-`npm pack` exists to verify a different thing: **what actually ships to npm** —
-the `files` list, and that every asset travels inside its skill. It is only
-meaningful at these moments:
-
-| Moment | Action |
-| --- | --- |
-| Day-to-day development | Nothing — use the local binary above |
-| Changing `files`, moving assets, adding or removing directories | `npm pack --dry-run` to list what would ship |
-| CI, before publishing | `yarn check-assets` + `npm pack --dry-run` as a guard |
-| Publishing a release | `npm pack` / `yarn npm publish` — the real tarball |
-
-A generated `.tgz` goes stale the moment the tree changes, so it is not a
-development tool. Keep it out of the working tree.
+`scripts/render-templates.mjs` is the same renderer `create` uses for stage 6; it copies
+templates and substitutes placeholders without touching dependencies, so iterating on a
+template costs seconds and no network. `npm pack` verifies a different thing — **what
+actually ships to npm** (the `files` list, and that every asset travels inside its
+skill). Use it only when `files`/assets change or before a release (`npm pack --dry-run`
+to list; `yarn check-assets` + `npm pack --dry-run` in CI). A generated `.tgz` goes
+stale the moment the tree changes, so keep it out of the working tree.
 
 ## Maintenance