@thorprovider/storefront 0.4.0-mvp.0 → 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-08"
+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:
 
@@ -50,37 +55,36 @@ cache (`~/.yarn/berry/cache`); repeat scaffolds then download no packages, and
 
 ### 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). Pressing Enter on an empty
-prompt accepts the suggested default: the storefront name is suggested from the
-target directory basename, and the site name from the Title Case of that name
-(`my-shop` → `My Shop`). 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
 ```
@@ -95,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]
 ```
@@ -105,25 +108,23 @@ 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__`) | Title Case of `<name>` (`my-shop` → `My Shop`) |
-| `--backend-url <url>` | Medusa backend URL | `http://localhost:9000` |
 | `--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 (files only, `--skip-install`) →
-`.yarnrc.yml` (`nodeLinker: node-modules`, retry and concurrency hardening) →
-shadcn base with the preset → 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
 
@@ -134,69 +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 resolve an explicit single-store context from the host
-environment before any commerce call. `create` writes a git-ignored `.env.local`
-with the data source and backend URL you passed, a generated cookie secret, and
-blank placeholders for the store identity, plus a committed `.env.example` that
-documents every variable (never a real secret):
+`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)
-THOR_DATA_SOURCE=medusa
-MEDUSA_BASE_URL=http://localhost:9000
-MEDUSA_PUBLISHABLE_KEY=
-MEDUSA_REGION_ID=
-MEDUSA_SALES_CHANNEL_ID=
+# .env.local (git-ignored) — written by create
+THOR_DATA_SOURCE=mock
 THOR_STORE_ID=my-shop
-THOR_CURRENCY_CODE=
 THOR_SESSION_SECRET=<generated per install>
 ```
 
-The store context is **explicit and validated**:
-
-- `THOR_STORE_ID` — stable store identity (seeded from the manifest name).
-- `MEDUSA_SALES_CHANNEL_ID` — the sales channel the store is scoped to.
-- `MEDUSA_REGION_ID` — the backend region that supplies currency, countries, and
-  shipping.
-- `THOR_CURRENCY_CODE` — ISO 4217 currency, taken from the environment; it is
-  **never hardcoded** in the app.
-- `THOR_SESSION_SECRET` — host-only cookie signing secret (≥16 chars, 32
-  recommended). Generate your own; never commit or log it.
-
-`THOR_DATA_SOURCE` selects the mode **explicitly** and is never inferred from a
-failure:
-
-- `THOR_DATA_SOURCE=mock` renders labelled demo data (`Datos de demostración`).
-  The store context must match the mock fixture: channel
-  `mock-sales-channel`, region `mock-region-us` (currency `USD`) or
-  `mock-region-eu` (currency `EUR`). The committed `.env.example` ships these.
-- `THOR_DATA_SOURCE=medusa` uses the real backend. A missing provider, invalid
-  configuration, or a provider failure is surfaced as a **visible error** — the
-  store never silently degrades to demo data. Until `MEDUSA_PUBLISHABLE_KEY` is
-  set, the home view shows the error notice instead of a fake catalog. Fill in
-  the variables, then restart `yarn dev` to serve real catalog data.
-
-The guest flow is backend-authoritative end to end: the signed host cookie
-issues a shopper identity and 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 after shipping 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.
-
-For offline-only work set `THOR_DATA_SOURCE=mock` on purpose.
+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
+storefront setup --publishable-key <key> --sales-channel-id <id> --region-id <region-id> [--backend-url <url>]
+```
+
+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
 
@@ -205,14 +207,14 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 #### Ancestor `.opencode/`
 
 - **Cause**: an ancestor directory already contains a `.opencode/`.
-- **Symptom**: OpenCode resolves the wrong command set (`/sf-add-view`, `/sf-view`, `/sf-theme`), so you see stale or unrelated behaviour.
+- **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**: `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, use `/sf-add-view`; run `create` in an empty directory.
+- **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`
 
@@ -233,81 +235,92 @@ Each entry below follows the same shape: **cause** → **symptom** → **remedy*
 
 #### Backend not configured
 
-- **Cause**: `THOR_DATA_SOURCE=medusa` but `MEDUSA_BASE_URL`/`MEDUSA_PUBLISHABLE_KEY` are missing, empty, or unreachable.
+- **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**: fill in the variables in [Backend configuration](#backend-configuration) and restart `yarn dev`. For offline work set `THOR_DATA_SOURCE=mock` on purpose.
+- **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            # install record: { version, installedAt, pinning }
-                             # pinning separates declared ranges from the resolved
-                             # versions, yarn.lock hash, and owned asset BOM
-  commands/
-    sf-add-view.md
-    sf-view.md
-    sf-feature.md
-    sf-theme.md
-  skills/
-    storefront-workflow/     # the four phases + CLI/manifest authority
-    sf-view-gen/             # assets/recipes/, scripts/validate.mjs
-    sf-feature/
-    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 feature command is
-[`commands/sf-feature.md`](./commands/sf-feature.md) and the workflow model is
+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`.
 
 ## Workflow: bootstrap → compose → customize → verify
 
 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. Read the installed `storefront-workflow` skill for the full
-model. Every command runs from inside the project (no directory argument).
+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`, `theme --mode` |
+| **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 regenerated by the CLI and
-never hand-edited. *User-owned* files (content, props, data, local schema, mapper
-bodies) are consumed through thin derived wrappers and survive `sync` and removal.
-*External* files (`app/layout.tsx`, `app/globals.css`) belong to create-next-app +
-shadcn; the CLI only appends idempotent markers.
-
-**Curated MVP defaults.** Standalone views `home`, `category`, `product`; the
-`checkout` feature (which owns the `checkout` view — a direct `view add checkout`
-is rejected, use `feature add checkout`). Held post-MVP and rejected before any
-write: `user-panel`, recommendations, and sections. A generated storefront is not a
-complete commerce implementation: the `checkout` feature ships structural wiring
-only, and the purchase flow is owned by the separate `single-tenant-commerce-mvp`
-change.
+`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 local `@thorprovider/*` packages from packed
-tarballs via Yarn `resolutions` (`--packs <dir>`), with no publish and no
-workspace import. No package-manager safety policy is suppressed: the generated
+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
-published past Yarn's age gate. `doctor` reports the observed linker/Node/Yarn
+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.
 
@@ -341,7 +354,8 @@ storefront apply --plan plan.json [--json]
 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.
+`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
@@ -354,28 +368,33 @@ options are rejected (`E_UNPROVEN_CHECKOUT_OPTION`). The category filter's actio
 no-op; catalog search/filters (E2) and composable sections (E3) are **not** implemented
 here.
 
-## Commands
+## Agent guidance and skills
 
-| Command | Purpose |
-| --- | --- |
-| `/sf-add-view <view>` | Add a curated view via the CLI (`product`, `category`; `checkout` via `/sf-feature`) |
-| `/sf-view <view> <change>` | Customize a view's user-owned content/props/data, then `sync` |
-| `/sf-feature add\|remove <name>` | Add/remove a feature bundle (e.g. `checkout`) via the CLI |
-| `/sf-theme` | Customize OKLCH color tokens (light/dark), typography, and identity metadata |
+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 itself is `npx @thorprovider/storefront create <dir>` — there is no
-`/sf-init` command; the wizard lives in the CLI and is deterministic. The color
-mode is likewise a CLI capability: `npx @thorprovider/storefront theme --mode light|dark|system`.
+Scaffolding is `npx @thorprovider/storefront create <dir>`; connecting a real backend is
+`storefront setup` from inside the project (see [Backend configuration](#backend-configuration)).
 
 ## 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 --mode`). Repeatable, reviewable, no model in the loop.
+  (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 (`/sf-theme` decides the mode; `storefront theme --mode` applies it).
-- **Pure judgment** → an `sf-*` skill (e.g. `/sf-view`): variant selection, copy, and
+  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
@@ -410,7 +429,7 @@ lib/<name>/
   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 + footer newsletter
+    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/
@@ -432,9 +451,10 @@ The shell's derived `spec/index.ts` imports the user-owned `shell/props.ts`
 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
-(`/`, `/categorias`, `/checkout`), never dead `#` links. `newsletter` defaults to `false`
+(`/`, `/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.
+— 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`.

package/VENDOR.md

@@ -0,0 +1,69 @@
+# Vendored material and provenance
+
+`@thorprovider/storefront` ships exactly five **operative skills** — first-party,
+authored in this package: `storefront-workflow`, `sf-view-gen`, `sf-feature`,
+`sf-setup`, and `sf-theme-gen`. Everything else the suite needs is either retained
+generic knowledge, shipped as a **scoped reference** an operative skill loads by
+relative path, or retired and no longer shipped. This file records the origin and
+the adaptation of that retained material. The generator never reads
+machine-global skills at runtime; the copies below are the authority the suite
+resolves.
+
+## First-party operative skills (not vendored)
+
+| Skill | Path | Purpose |
+|---|---|---|
+| storefront-workflow | `skills/storefront-workflow/` | The four-phase model (bootstrap → compose → customize → verify) and the CLI/manifest authority |
+| sf-view-gen | `skills/sf-view-gen/` | Add/modify a view via the CLI; owns the retained json-render references |
+| sf-feature | `skills/sf-feature/` | Add/remove a feature bundle via the CLI |
+| sf-setup | `skills/sf-setup/` | Connect or re-point the Medusa backend via `storefront setup` |
+| sf-theme-gen | `skills/sf-theme-gen/` | Theme tokens, typography, identity; owns the retained theming references |
+
+## Retained references
+
+Useful generic knowledge is retained **only** as references inside the operative
+skill that owns the procedure. A reference is not an independently selectable
+skill (it is not a `SKILL.md`).
+
+| Retained reference | Owning skill | Upstream source | Refresh date | Adapted |
+|---|---|---|---|---|
+| `references/design-consistency.md` | `skills/storefront-workflow/` | `~/.config/opencode/skills/storefront-best-practices` | 2026-10-14 | Kept as a reference; UX/design-consistency guidance retained, raw Medusa SDK / React Query / direct-`/store` fetching removed |
+| `references/mobile-responsiveness.md` | `skills/storefront-workflow/` | `~/.config/opencode/skills/storefront-best-practices` | 2026-10-14 | Kept as a reference; responsive/mobile guidance retained, raw SDK fetching removed |
+| `references/seo.md` | `skills/storefront-workflow/` | `~/.config/opencode/skills/storefront-best-practices` | 2026-10-14 | Kept as a reference; SEO/accessibility guidance retained, entity-metadata policy preserved |
+| `references/shadcn-theming.md` | `skills/sf-theme-gen/` | `~/.config/opencode/skills/shadcn-theming` | 2026-10-14 | Unavailable tooling (`TeamCreate`, `fuse-ai-pilot`) and raw `shadcn init`/`shadcn add` scaffolding-and-discovery steps removed; OKLCH token/foreground-pair rules and the lightness rule kept |
+| `references/theme-setup.md` | `skills/sf-theme-gen/` | `~/.config/opencode/skills/shadcn-theming/references/templates` | 2026-10-14 | Kept as a reference; adapted to the generated storefront's external-file bounds |
+| `references/theming-guide.md` | `skills/sf-theme-gen/` | `~/.config/opencode/skills/shadcn-theming/references` | 2026-10-14 | Kept as a reference; adapted to the generated storefront's external-file bounds |
+| `references/json-render-core.md` | `skills/sf-view-gen/` | `~/.config/opencode/skills/json-render/core` | 2026-10-14 | Flattened from the standalone `json-render-core` skill to a reference; reachable only by relative path from `sf-view-gen` |
+| `references/json-render-react.md` | `skills/sf-view-gen/` | `~/.config/opencode/skills/json-render/react` | 2026-10-14 | Flattened from the standalone `json-render-react` skill to a reference; reachable only by relative path from `sf-view-gen` |
+| `references/json-render-next.md` | `skills/sf-view-gen/` | `~/.config/opencode/skills/json-render/next` | 2026-10-14 | Flattened from the standalone `json-render-next` skill to a reference; reachable only by relative path from `sf-view-gen` |
+| `references/json-render-shadcn.md` | `skills/sf-view-gen/` | `~/.config/opencode/skills/json-render/shadcn` | 2026-10-14 | Flattened from the standalone `json-render-shadcn` skill to a reference; reachable only by relative path from `sf-view-gen` |
+| `references/views.md` | `skills/sf-view-gen/` | Authored in this package | 2026-10-14 | First-party; documents the curated view set read from `storefront views --json` |
+
+## Retired
+
+These were previously bundled flat under `skills/` as standalone installable
+skills. They are no longer shipped as active skills or as retained reference
+material, and `storefront update` retires an installed copy that is verifiably
+unmodified.
+
+| Retired item | Upstream source | Last bundled | Why retired |
+|---|---|---|---|
+| `nextjs-shadcn` | `~/.config/opencode/skills/nextjs-shadcn` | 2026-09-28 | Broadly-triggering generic skill; `shadcn init`/`shadcn add` scaffolding contradicts the CLI-only generation rule |
+| `shadcn-component-discovery` | `~/.config/opencode/skills/shadcn-component-discovery` | 2026-09-28 | Broadly-triggering generic skill; UI is limited to `@thorprovider/blocks` |
+| `building-storefronts` | `~/.config/opencode/skills/building-storefronts` | 2026-09-28 | Broadly-triggering generic skill; pushes raw SDK / React Query fetching the storefront cannot use |
+| `json-render-solid` | `~/.config/opencode/skills/json-render/solid` | 2026-09-28 | Irrelevant renderer; the generated storefront renders React/Next only |
+| `json-render-remotion` | `~/.config/opencode/skills/json-render/remotion` | 2026-09-28 | Irrelevant renderer; video timelines are out of scope for a spec-based storefront |
+
+## Excluded
+
+Never bundled: the `json-render` `codegen`, `devtools`, `directives`, `image`, and
+`mcp` material. They are irrelevant to a generated storefront and are not shipped
+in any form.
+
+## Maintenance
+
+To refresh a retained reference: re-copy the upstream material to a reference
+file under the owning skill's `references/`, update the `Refresh date` above, and
+bump the package version. If a reference is retired, move it to the **Retired**
+table with its reason; `storefront update` retires a verifiably unmodified
+installed copy of it. See the package README maintenance note.

package/assets/openspec/config.yaml

@@ -0,0 +1,38 @@
+# Storefront OpenSpec configuration — seeded by @thorprovider/storefront.
+#
+# This file is storefront-owned: `storefront update` re-applies it after
+# re-running `openspec init`. Put customization in the storefront's own files,
+# not here.
+schema: spec-driven
+
+context: |
+  This project is a generated Thor Commerce storefront. A storefront is defined by
+  its manifest (storefront.config.json) and produced by the `storefront` CLI. The
+  CLI is the authority for every structural change — views, features, sections,
+  theme, and setup — and it is the only writer of derived files. Manual edits are
+  limited to user-owned files (view content/props/data/schema, mappers, icon-map,
+  shell) plus the bounded external surface of app/globals.css and app/layout.tsx,
+  and must preserve the CLI-managed imports and markers.
+  Determinism first: a change the CLI performs deterministically stays with the CLI.
+  A deterministic change the CLI records in storefront.config.json is trivial and
+  does not require an OpenSpec change; the manifest is its record. A change that
+  requires judgment — content authoring, prop/data mapping, composition reshaping,
+  or a cross-file redesign whose acceptance is not a CLI assertion — is non-trivial
+  and is driven through the spec-driven loop, surfaced to the user as the five
+  stages explore → plan → build → verify → inform, orchestrated by the agent
+  without asking the user to confirm each artifact. Keep any OpenSpec change
+  consistent with the storefront authorities: structural edits still go through
+  the CLI.
+
+rules:
+  proposal:
+    - "State the why, the observable storefront change, and the affected view(s) or feature(s); keep deferred scope explicit."
+    - "Do not restate this context or these rules in the artifact body."
+  specs:
+    - "New capabilities start with ## Purpose and ## ADDED Requirements; scenarios use exactly four hashtags (#### Scenario:) and every requirement has at least one."
+    - "Describe observable behavior, not implementation details."
+  design:
+    - "Record each decision with its why and the alternative considered; state how the change respects the CLI-as-authority and the user-owned surface."
+  tasks:
+    - "Group tasks by dependency; each task is a checkbox and states its own verification."
+    - "Never report the change complete until `storefront sync` and `storefront doctor` pass and the change's acceptance is met."