@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/skills/sf-feature/SKILL.md

@@ -1,31 +1,44 @@
 ---
 name: sf-feature
-description: Add or remove a Thor Commerce storefront feature bundle. Use when the user runs /sf-feature or asks to add/remove a feature such as checkout. Delegates every structural write to the `storefront` CLI.
+description: Add or remove a Thor Commerce storefront feature bundle, and explain how a feature owns views, routes, and state versus mounting into a host view's slot. Use when the user asks to add or remove a feature (for example checkout, customer auth, or a category filter), or asks why a view cannot be added directly. Delegates every structural write to the `storefront` CLI.
 ---
 
 # sf-feature
 
-A **feature** is a capability bundle that owns views plus its state slices,
-handlers, and declared adapter needs, and may declare an owned route and one or
-more instance mounts into a host view's slot. Adding it installs those views,
-routes, and mounts; removing it takes them away. The CLI writes every derived
+A **feature** is a capability bundle. It may own views plus its state slices,
+handlers, and declared adapter needs, and it may declare an owned route and one
+or more instance mounts into a host view's slot. The CLI writes every derived
 file; agents never do.
 
-## Read the registry through the CLI
+## Read the curated feature set through the CLI (never from memory)
 
-Run from the storefront project root (no directory argument):
+Run from the storefront project root (the CLI resolves the project from the
+current directory; do not pass a directory):
 
 ```bash
 npx @thorprovider/storefront features --json
 npx @thorprovider/storefront recipes --json
 ```
 
-## Curated MVP set
-
-The supported (MVP) features are `checkout` (owns the `/checkout` route) and
-`benefits` (mounts at the home `benefits` slot, config selects the
-presentation). Held features (for example `recommendations`) are rejected before
-any write; do not try to install them.
+`features --json` is the registry the CLI validates against, annotated with
+`installed`, `mvp`, `route`, `views`, `state`, `handlers`, `adapter`, `presentations`,
+`mounts`, and `surfaces` per feature. There is **no fixed feature list in this
+skill**: whatever the registry reports is the authoritative set, so a feature
+added to or removed from the registry is reflected without editing this text. Do
+not read the JSON files directly; they are an implementation detail.
+
+## Feature-owned vs mount-only (read this before routing a request)
+
+- **Feature-owned view** — `views` is non-empty (for example a `checkout` feature
+  that owns the `checkout` view). Install and remove the whole bundle through the
+  feature; a direct `view add <owned-view>` is rejected. The CLI installs the
+  owned views, route, and mounts together.
+- **Mount-only feature** — `views` is empty and `mounts` (or `surfaces`) is
+  non-empty. It injects into a host view's declared slot without owning a view.
+  Removing it leaves the host view installed and preserves the host's user-owned
+  content.
+- **Held feature** — `mvp: false`. The CLI rejects it before any write; report it
+  as not available rather than trying to install it.
 
 ## Add a feature
 
@@ -33,9 +46,10 @@ any write; do not try to install them.
 npx @thorprovider/storefront feature add <name>
 ```
 
-This installs the feature and every view it owns (e.g. `checkout` installs the
-`checkout` view), and reconciles the state/handlers/adapter wiring. If the CLI
-exits non-zero, show its message; do not hand-edit derived files.
+This installs the feature, every view it owns, its owned route, and its mounts,
+and reconciles the state/handlers/adapter wiring. If the CLI exits non-zero,
+relay its message and the supported options; do not hand-edit derived files to
+work around it.
 
 ## Remove a feature
 
@@ -52,9 +66,8 @@ path to the user.
 
 - UI only `@thorprovider/blocks`; data only `@thorprovider/adapters` +
   `@thorprovider/runtime/commerce`.
-- The `checkout` feature's purchase logic is owned by the separate
-  `single-tenant-commerce-mvp` change; this command only installs its structural
-  wiring.
+- A missing capability is a gap to report, not a reason to install another UI
+  framework or hand-edit a derived file.
 
 ## Workflow model
 

package/skills/sf-setup/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sf-setup
+description: Connect or re-point a Thor Commerce storefront to a Medusa backend — set the backend URL, publishable API key, sales channel id, and region, or preserve the current environment when no key is supplied. Use when the user asks to connect or reconnect the backend, change the region or API key, switch the data source, or "set up" the store's data. Delegates to the `storefront setup` CLI command.
+---
+
+# sf-setup
+
+Connect a storefront to a real Medusa backend, or re-point an already-connected
+store. `setup` takes the sales channel id as an explicit input (there is no store API
+that reads the channels bound to a publishable key), derives the region's currency,
+then writes them to `.env.local`. The CLI writes the file; agents never hand-edit it.
+
+## Run it
+
+Run from the storefront project root:
+
+```bash
+npx @thorprovider/storefront setup \
+  --backend-url http://localhost:9000 \
+  --publishable-key <pk_...> \
+  --sales-channel-id <sc_...> \
+  --region-id <reg_...>
+```
+
+On a terminal with no flags it runs an interactive wizard (backend URL →
+publishable key → sales channel id → region). Pass the flags to run
+non-interactively (CI, scripts).
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--backend-url` | Medusa backend base URL. Defaults to `http://localhost:9000`. |
+| `--publishable-key` | Publishable API key (`pk_...`). Required to connect. |
+| `--sales-channel-id` | Sales channel id (`sc_...`) from the Medusa admin (Settings → Sales Channels). Required without a terminal. |
+| `--region-id` | Region id to bind. Required without a terminal; the wizard offers the available regions. |
+
+## No key — the existing environment is preserved
+
+With no publishable key, `setup` makes no network calls, **changes no files**, and
+exits 0, so it is safe to run in CI/bootstrap without a key. It does not switch
+the store to `mock`: the existing data source is left exactly as it was (`mock`
+stays `mock`, `medusa` stays `medusa`). A freshly created store is already in
+`mock` mode, so running with no key simply leaves it there.
+
+## What it writes
+
+Only the keys `setup` manages are upserted in `.env.local`; everything else (the
+session secret, the site URL, store identity, and any user additions) is
+preserved:
+
+- `THOR_DATA_SOURCE=medusa`
+- `MEDUSA_BASE_URL`
+- `MEDUSA_PUBLISHABLE_KEY`
+- `MEDUSA_REGION_ID`
+- `MEDUSA_SALES_CHANNEL_ID` (from the `--sales-channel-id` input)
+- `MEDUSA_CURRENCY_CODE` (derived from `GET /store/regions`)
+
+Restart the dev server to pick up the change.
+
+## Failure behavior
+
+If the backend is unreachable, the key is rejected, the sales channel id is
+missing, or the region is missing or has no currency, `setup` prints the reason,
+**changes no files**, preserves the existing environment (`mock` stays `mock`,
+`medusa` stays `medusa`), and exits non-zero. The store is placed in `medusa` mode
+only after the backend URL, publishable key, sales channel id, and region are all
+resolved and the region's currency resolves successfully. Relay the message to the
+user and fix the input; do not hand-edit `.env.local`.
+
+## Workflow model
+
+Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
+authority.
+
+## Completion criteria
+
+- `.env.local` contains the managed keys for the chosen backend and region.
+- The dev server starts and loads data from the connected backend.

package/skills/sf-theme-gen/SKILL.md

@@ -1,68 +1,131 @@
 ---
 name: sf-theme-gen
-description: Customize a Thor Commerce storefront's OKLCH color tokens (light/dark), typography, and identity/SEO metadata
+description: Customize a Thor Commerce storefront's theme — OKLCH colors, radius, fonts, shadcn presets and imported themes, plus typography and global identity/SEO metadata. Use when the user asks to change the storefront's colors, brand, theme, typography, site name, or SEO metadata.
 ---
 
 # sf-theme-gen
 
-Customize a storefront's theme and identity. This skill ships with everything it needs: it uses the vendored theming skill alongside it. When a choice is not resolved by those files, ask the user.
+Customize a storefront's theme and identity. Prefer the deterministic
+`storefront theme` controls; fall back to hand-editing the two external files only
+within their bounded surface. When a required choice is not determined by the
+references, ask the user.
 
-## Source of truth
+## Inputs
 
-The manifest (`storefront.config.json`) is the theme authority: `theme --mode`
-updates it and reconciles, so a later `sync` cannot revert the change. Read
-`../storefront-workflow/SKILL.md` for the four phases (bootstrap → compose →
-customize → verify) and the CLI/agent authority.
+- The manifest `storefront.config.json` — the theme authority for the **mode**.
+- The two external files `app/globals.css` and `app/layout.tsx` — the current
+  visual tokens, fonts, and identity.
+- The user's chosen customization area and value.
 
-The workflow uses only the assets in this skill directory and the vendored `../shadcn-theming/` skill next to it. When a required choice is not determined there, ask the user.
+## Outputs
 
-## Inputs (the only target-project facts this skill reads)
+- Edited `app/globals.css` (tokens, `@theme` bridge, font variables) and/or
+  `app/layout.tsx` (font loading, metadata/identity) — produced by
+  `storefront theme` when a control exists, or by hand within the bounds below.
+- A summary listing every file edited and every command run.
 
-- the existence of the target project's `package.json`
-- the existence of `lib/<name>/`
-- the existence of the project's `.opencode/`
-- the values returned by the wizard (which area to customize, and its value)
+## Scope (bounded external surface)
 
-## Outputs (what this skill produces)
+| Area | File | Allowed change |
+|---|---|---|
+| Design tokens (OKLCH, light/dark) | `app/globals.css` | token values + foreground pairs, `@theme` bridge, font variable |
+| Typography | `app/layout.tsx` + `globals.css` | load the font with `next/font`, point `--font-sans` at it |
+| Identity / metadata / Open Graph | `app/layout.tsx` | the `metadata` object |
 
-- generated files: `app/globals.css` and `app/layout.tsx`
-- declared setup commands: the dev server and typecheck commands it reports
-- a summary listing every file edited and every command run
+Everything else in these files is **CLI-managed and must be preserved**: the
+stylesheet import, the provider import and its marker, the theme-mode marker, and
+the block token contract. The CLI appends idempotently; never remove or duplicate
+a marker, and never edit the mode wiring by hand.
 
-## Scope
+## CLI controls (preferred path)
 
-| Area | File |
-|---|---|
-| Design tokens (shadcn) | `app/globals.css` |
-| Typography + metadata | `app/layout.tsx` |
+Visual values live in `app/globals.css`; the mode lives in the manifest. All
+controls are one command and are validated before any write:
 
-## Vendored skill
-Follow `../shadcn-theming/SKILL.md` for OKLCH pair rules and contrast. Paths are relative to this `SKILL.md`.
+```
+storefront theme --inspect [--json]        # read-only: current tokens, names, formats
+storefront theme --mode light|dark|system  # site color mode (manifest + wiring)
+storefront theme --brand orange            # named brand -> full primary family
+storefront theme --primary '#f97316'       # one color (named | #hex | oklch(...))
+storefront theme --accent 'oklch(0.6 0.15 200)'
+storefront theme --radius 0.75rem          # base radius (drives the radius scale)
+storefront theme --font-sans google:Inter  # loads the font, points --font-sans at it
+storefront theme --set light.primary=#f97316   # scope = light | dark | shared; repeatable
+storefront theme --preset <name|code|url> [--only theme|font|theme,font]
+storefront theme --import ./theme.css|./theme.json|<registry-url>
+storefront theme --export ./brand.theme.json   # portable snapshot; never overwrites
+storefront theme ... --dry-run             # describe the change, write nothing
+storefront theme ... --json                # machine-readable result envelope
+```
+
+`--brand`/`--primary` set the primary family (primary, foreground, hover, soft,
+ring, nav) in both modes. Explicit `--set` values win over shortcuts; later
+arguments win over earlier ones. A `--preset` applies **theme and fonts only** —
+it never reinstalls or restyles components.
+
+## Free theme workflow (generator → CLI)
+
+1. Design the palette in a free editor and export its CSS: the official builder
+   at `ui.shadcn.com/create` (preset code/URL) or a CSS export from tweakcn /
+   Shadcn Studio. These are authoring tools; the CLI is the writer.
+2. Apply it: `storefront theme --preset <code>` for a preset, or
+   `storefront theme --import ./exported.css` for a CSS export (only theme tokens
+   and font variables are merged; unrelated CSS is ignored).
+3. Fine-tune: `--brand`, `--primary`, `--accent`, `--radius`, `--set`, `--font-*`.
+4. `storefront theme --export ./brand.theme.json` to keep a portable snapshot;
+   replay it elsewhere with `--import ./brand.theme.json`.
 
 ## Color rules
+
 - Colors are CSS variables, never raw Tailwind color utilities.
 - OKLCH only; define complete background/foreground pairs.
-- Lightness rule: bg `L < 0.55` → fg `L >= 0.93`; bg `L >= 0.55` → fg `L <= 0.20`.
-- Named accents can use `accentColorToOklch(name)` from `@thorprovider/runtime/render-core/theme`.
+- The CLI pairs a changed color with its foreground using **measured contrast**
+  (WCAG relative luminance), not a lightness threshold; auto-selected foregrounds
+  meet >= 4.5:1. A contrast below 4.5:1 is reported as a warning but never
+  silently changes an explicit pair — use `--set light.primary-foreground=#fff`
+  to force a specific pairing.
+- Accepts `<name>` (see `storefront theme --inspect`), `#hex`, `oklch(...)`.
 
 ## Workflow
 
-1. Use the `question` tool to ask what to customize: colors, typography, identity, SEO, Open Graph.
-2. **Mode (light/dark/system)**: this is a deterministic option, not a hand edit. Run `npx @thorprovider/storefront theme --mode light|dark|system` to change the site color mode; it rewrites the `ThemeProvider` wiring in `app/layout.tsx` idempotently. Do NOT edit `app/layout.tsx` for the mode yourself. There is no visitor-facing toggle by design — the mode is a site setting.
-3. **Colors**: follow `../shadcn-theming/SKILL.md`; update BOTH `:root` (light) and `.dark` blocks in `app/globals.css`, keeping the `@theme inline` mapping intact.
-4. **Pairs**: every changed color gets its foreground pair in both modes; verify the lightness rule.
-5. **Typography**: load the font with `next/font` in `app/layout.tsx`; point `--font-sans` in `globals.css` at the new variable; keep body >= 1rem / line-height 1.5.
-6. **Identity**: update the `metadata` object in `app/layout.tsx` (title, description) and add Open Graph + Twitter Card fields. Research the current Next.js Metadata API before writing.
-7. **Verify**: run the dev server; confirm both color modes, font, and head metadata. `yarn typecheck` passes.
+1. Ask what to customize: colors/brand, radius, typography, identity, SEO, Open Graph.
+2. **Mode** is deterministic: `storefront theme --mode light|dark|system`; never
+   edit the mode wiring by hand. There is no visitor-facing toggle by design.
+3. **Colors**: prefer `storefront theme --brand/--primary/--accent` or `--set`.
+   For a full palette, import a generator export (see above). Hand-edit only a
+   value the CLI cannot express, updating BOTH `:root` and `.dark`.
+4. **Pairs**: a color change gets its foreground pair; the CLI does this and
+   warns on low contrast.
+5. **Typography**: `storefront theme --font-sans google:Inter` loads the font with
+   `next/font` and points `--font-sans` at it. Use `system:<stack>` for a CSS
+   stack. Existing local fonts are preserved unless explicitly replaced. A font
+   name alone is not proof it loads — verify rendering.
+6. **Identity**: update the `metadata` object in `app/layout.tsx` (title,
+   description) and add Open Graph + Twitter Card fields. Confirm the current
+   Next.js Metadata API before writing.
+7. **Verify**: `storefront theme --dry-run` first, then apply; run the dev server
+   and confirm both color modes, the font, and the head metadata. `yarn build` is
+   the final acceptance. A `sync` must leave the CLI-managed markers intact and
+   the theme unchanged.
+
+## Limits
+
+- A preset changes theme tokens and font wiring only; it cannot redesign
+  package-owned `@thorprovider/blocks` beyond their tokens.
+- `--export` is read-only over the project and refuses to overwrite a file.
+- Invalid input (unknown color/token/length/font, unsupported import) fails with
+  a diagnostic and writes nothing.
 
 ## Error handling
+
 - Invalid color input → re-prompt (accept `<name>`, `#hex`, `oklch(...)`).
-- No `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
-- Unknown token key → check `themeTokenKeys` in `@thorprovider/runtime/contracts` first.
-- Mode change → always via `npx @thorprovider/storefront theme --mode ...`; never edit the layout by hand.
+- Unknown token key → run `storefront theme --inspect` (lists supported tokens).
+- Mode change → always via `storefront theme --mode ...`; never edit by hand.
 
 ## Generation headers
+
 ```
 // Themed by @thorprovider/storefront (sf-theme-gen)
 ```
+
 Never remove existing tokens; only override values.

package/skills/sf-theme-gen/references/shadcn-theming.md

@@ -0,0 +1,87 @@
+# shadcn theming reference
+
+Reference material for the `sf-theme-gen` skill. It documents shadcn/ui design
+tokens, OKLCH color rules, dark/light mode CSS variables, and the Tailwind v4
+`@theme` bridge for the two external files `app/globals.css` and
+`app/layout.tsx`.
+
+## Overview
+
+| Feature | Description |
+|---------|-------------|
+| **CSS Variables** | `--background`, `--foreground`, `--primary`, etc. |
+| **OKLCH Colors** | Wide-gamut P3 color space, perceptually uniform |
+| **Dark Mode** | `.dark` class or `prefers-color-scheme` |
+| **Tailwind v4** | `@theme` directive integration |
+
+## Critical rules
+
+1. **ALWAYS use OKLCH** color space for all tokens.
+2. **ALWAYS define dark mode** overrides for every token.
+3. **NEVER hard-code** hex or rgb in components.
+4. **USE the `@theme`** directive for Tailwind v4 integration.
+5. **MAP semantic tokens** to primitive OKLCH values.
+
+## Lightness rule (contrast)
+
+Apply it to every custom pair (`--secondary`, `--accent`, `--destructive`, `--muted`):
+
+- Background `L < 0.55` → foreground `L >= 0.93`.
+- Background `L >= 0.55` → foreground `L <= 0.20`.
+
+## Token hierarchy
+
+```
+Component:  --card, --card-foreground, --button-*
+     ↑
+Semantic:   --primary, --secondary, --accent, --muted
+     ↑
+Primitive:  oklch(55% 0.20 260), oklch(98% 0.01 260)
+```
+
+## File scope
+
+Only these two external files are touched, and only for tokens, fonts, and
+identity. The CLI-managed imports and markers inside them must survive.
+
+```
+app/globals.css   # :root + .dark token definitions, @theme bridge
+app/layout.tsx    # font wiring (next/font) + metadata/identity
+```
+
+The theme mode (`light` / `dark` / `system`) is a CLI operation
+(`storefront theme --mode ...`); do not hand-edit the `ThemeProvider` wiring in
+`app/layout.tsx`.
+
+## Validation checklist
+
+```
+[ ] CSS variables defined in :root
+[ ] Dark mode overrides in .dark
+[ ] OKLCH color space used
+[ ] Chart variables (--chart-1 to --chart-5) if used
+[ ] Sidebar variables if applicable
+[ ] No hard-coded hex in components
+[ ] @theme bridge maps each semantic token
+```
+
+## Best practices
+
+### DO
+- Use OKLCH for all colors.
+- Define semantic tokens mapped to primitives.
+- Provide dark mode overrides for all tokens.
+- Use `@theme` for Tailwind v4 integration.
+
+### DON'T
+- Hard-code hex or rgb values.
+- Skip dark mode definitions.
+- Mix color spaces (hex + oklch).
+- Define tokens only in a Tailwind config.
+
+## Reference guide
+
+| Topic | Reference | When to consult |
+|-------|-----------|-----------------|
+| Theming guide | [theming-guide.md](theming-guide.md) | CSS variables and OKLCH setup |
+| Complete theme template | [theme-setup.md](theme-setup.md) | Light + dark token definitions and `@theme` bridge |

package/skills/{shadcn-theming/references/templates → sf-theme-gen/references}/theme-setup.md

@@ -1,11 +1,8 @@
----
-name: theme-setup
-description: Complete shadcn/ui theme with CSS variables, dark mode, and Tailwind v4 integration
-keywords: theme, setup, css, oklch, dark-mode, tailwind
----
-
 # Theme Setup
 
+Reference material for the `sf-theme-gen` skill: the complete light + dark theme
+with CSS variables, dark mode, and Tailwind v4 integration.
+
 ## Complete Light + Dark Theme
 
 ```css
@@ -92,18 +89,17 @@ keywords: theme, setup, css, oklch, dark-mode, tailwind
 }
 ```
 
-## Theme Switching (React)
+## Theme switching
 
-```tsx
-// components/theme-provider.tsx
-"use client"
-import { ThemeProvider as NextThemesProvider } from "next-themes"
+The light/dark/system mode is a CLI operation, not a hand edit. Run
+`npx @thorprovider/storefront theme --mode light|dark|system`: it rewrites the
+`ThemeProvider` wiring in `app/layout.tsx` idempotently. Do **not** add your own
+provider or toggle; the mode is a site setting and the CLI-managed import and
+marker must survive. This template covers the `:root` / `.dark` token blocks and
+the `@theme` bridge only.
 
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  return (
-    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem>
-      {children}
-    </NextThemesProvider>
-  )
-}
-```
+## Marker preservation
+
+`app/globals.css` and `app/layout.tsx` are `external` files: keep the CLI-managed
+provider/mode/style imports and block-token markers intact. Change only token
+values, font wiring, and global identity/metadata.

package/skills/{shadcn-theming → sf-theme-gen}/references/theming-guide.md

@@ -1,14 +1,9 @@
----
-name: theming-guide
-description: CSS variables, OKLCH colors, chart/sidebar tokens, and Tailwind integration
-when-to-use: When configuring theme tokens or color system
-keywords: theme, oklch, css-variables, dark-mode, tailwind, tokens, colors
-priority: high
-related: ../SKILL.md
----
-
 # Theming Guide
 
+Reference material for the `sf-theme-gen` skill: CSS variables, OKLCH colors,
+chart/sidebar tokens, and the Tailwind v4 integration used by the external
+`app/globals.css`.
+
 ## Overview
 
 shadcn/ui uses CSS custom properties with OKLCH color space for wide-gamut P3 support and perceptual uniformity. Tokens follow a 3-level hierarchy: primitive -> semantic -> component.
@@ -71,7 +66,7 @@ Use `.dark` class on `<html>` or CSS media query:
 <html className={theme === "dark" ? "dark" : ""}>
 ```
 
-For full setup with next-themes, see [theme-setup.md](templates/theme-setup.md).
+For the full token template, see [theme-setup.md](theme-setup.md).
 
 ---
 
@@ -87,4 +82,4 @@ For full setup with next-themes, see [theme-setup.md](templates/theme-setup.md).
 
 ## Related Templates
 
-- [theme-setup.md](templates/theme-setup.md) - Complete theme configuration
+- [theme-setup.md](theme-setup.md) - Complete theme configuration