@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/scripts/view-assembly.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// Per-slot / per-variant view assembly (E1 task 2.1).
+//
+// A view template is split into one source fragment per executable slot variant
+// under `assembly/slots/<slot>/<variant>/`, plus two skeletons with markers
+// (`assembly/index.skeleton.tsx`, `assembly/registry.skeleton.tsx`) and an
+// `assembly/assembly.json` declaring slot order and each slot's default.
+//
+// `assembleView` composes the derived `index.tsx` and `registry.tsx` source from
+// the selected variant's fragments. Task 2.1 calls it with the default selection
+// so the fresh scaffold keeps the default composition's identity; task 2.2 will
+// pass the manifest's intent/variant selection through the same function. The
+// assembler is pure (no file writes, no placeholder substitution) so callers own
+// the render + write step.
+//
+// Held variants have no fragment directory, so they can never be assembled: the
+// selectable set is exactly the fragment set, which a parity test pins to the
+// semantic catalog's `executable` entries.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { isSlotSectionEntry } from './section-compat.mjs'
+
+export const ASSEMBLY_DIRNAME = 'assembly'
+
+// Skip predicate for the recursive template copy: the assembly sources are
+// authoring input, never project output, so they must not be copied verbatim.
+export function isAssemblyRel(rel) {
+  return rel.split(path.sep)[0] === ASSEMBLY_DIRNAME || rel.split('/')[0] === ASSEMBLY_DIRNAME
+}
+
+export function assemblyDir(templateDir) {
+  return path.join(templateDir, ASSEMBLY_DIRNAME)
+}
+
+export function hasViewAssembly(templateDir) {
+  return Boolean(templateDir) && existsSync(path.join(assemblyDir(templateDir), 'assembly.json'))
+}
+
+export function loadViewAssembly(templateDir) {
+  const file = path.join(assemblyDir(templateDir), 'assembly.json')
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+// The executable variants for a slot, in deterministic order. A variant is
+// assemblable exactly when its fragment directory exists.
+export function fragmentVariants(templateDir, slot) {
+  const dir = path.join(assemblyDir(templateDir), 'slots', slot)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+// Resolve a `{ slot: variant }` selection against the assembly metadata. An
+// omitted slot falls back to its declared default; an unknown variant throws so
+// a caller never silently renders the wrong (or no) fragment.
+//
+// A slot marked `nested: true` is a presentation slot that is rendered inside
+// its host element (for example the category `productCard` inside the single
+// `CategoryFilter2` listing), so it has no top-level fragment and is skipped
+// here: it stays in the ordered composition (it is a core registered slot) but
+// contributes no top-level element, catalog entry, or route id.
+export function resolveViewSelection(templateDir, selection = {}) {
+  const meta = loadViewAssembly(templateDir)
+  const slots = Array.isArray(meta.slots) ? meta.slots : []
+  const resolved = {}
+  for (const slot of slots) {
+    if (slot.nested === true) continue
+    const chosen = selection[slot.slot] ?? slot.default
+    const variants = fragmentVariants(templateDir, slot.slot)
+    if (!variants.includes(chosen)) {
+      throw new Error(
+        `Variant "${chosen}" has no fragment for slot "${slot.slot}" in view "${meta.view}". Available: ${variants.join(', ') || '(none)'}.`,
+      )
+    }
+    resolved[slot.slot] = chosen
+  }
+  return { meta, selection: resolved }
+}
+
+function readPart(fragmentDir, name) {
+  const file = path.join(fragmentDir, name)
+  if (!existsSync(file)) {
+    throw new Error(`View fragment is missing "${name}": ${fragmentDir}`)
+  }
+  // A fragment is a source snippet; its single trailing newline is provided by
+  // the skeleton, so strip it before joining.
+  return readFileSync(file, 'utf8').replace(/\n$/, '')
+}
+
+// Merge the per-variant block bindings into one import statement per module,
+// sorted by imported name so the output is deterministic. This is what makes
+// swapping a variant (Feature1 -> Feature2) change exactly one binding.
+function renderBlockImports(bindings) {
+  const byModule = new Map()
+  for (const binding of bindings) {
+    if (!byModule.has(binding.module)) byModule.set(binding.module, [])
+    byModule.get(binding.module).push(binding)
+  }
+  const lines = []
+  for (const [moduleName, list] of [...byModule.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const sorted = [...list].sort((a, b) => a.import.localeCompare(b.import))
+    if (sorted.length === 1) {
+      lines.push(`import { ${sorted[0].import} as ${sorted[0].as} } from '${moduleName}'`)
+    } else {
+      lines.push('import {')
+      for (const binding of sorted) lines.push(`  ${binding.import} as ${binding.as},`)
+      lines.push(`} from '${moduleName}'`)
+    }
+  }
+  return lines.join('\n')
+}
+
+// The import line that lets an editorial element read its user-owned instance
+// content from the view's `content.ts` (`sectionContent[id]`). Emitted only when
+// the ordered composition contains at least one editorial instance, so the
+// default (slot-only) composition keeps its exact output.
+function renderSectionImports(modules) {
+  const lines = [...modules]
+    .sort((a, b) => a.localeCompare(b))
+    .map((moduleName) => `import { ${SECTION_CONTENT_EXPORT} } from '${moduleName}'`)
+  return lines.length === 0 ? '' : `\n${lines.join('\n')}`
+}
+
+// The client-registry import for an editorial section's presentation bridge,
+// one per distinct `views/sections/<type>.client` module, sorted by module.
+function renderSectionRegistryImports(byModule) {
+  const lines = [...byModule.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([moduleName, exportName]) => `import { ${exportName} } from '${moduleName}'`)
+  return lines.length === 0 ? '' : `\n${lines.join('\n')}`
+}
+
+const SECTION_CONTENT_EXPORT = 'sectionContent'
+
+// One editorial instance's element: a persisted instance id, the section's
+// registered element type, and its props read from the view's user-owned
+// `content.ts` by id (falling back to the section fragment's declared neutral
+// default so the element is always a valid tree node).
+function renderEditorialElement(entry, def) {
+  const fallback =
+    typeof def.defaultProps === 'string' && def.defaultProps.length > 0 ? def.defaultProps : '{}'
+  const props = `${SECTION_CONTENT_EXPORT}['${entry.id}'] ?? ${fallback}`
+  return `  '${entry.id}': {\n    type: '${def.elementType}',\n    props: ${props},\n  },`
+}
+
+// One editorial instance's client registry binding: the section element type
+// maps to the shared section fragment's registry component.
+function renderEditorialRegistry(entry, def) {
+  return `  ${def.elementType}: ${def.registryExport}.${def.elementType},`
+}
+
+/**
+ * Assemble a view's derived `index.tsx` and `registry.tsx` from the view's
+ * single ordered composition (E3 task 5.1).
+ *
+ * Each ordered entry is either a registered presentation slot
+ * (`{ id: "slot:<slot>", type: "<slot>" }`) — composed from the selected
+ * per-variant fragment — or an editorial section instance
+ * (`{ id, type, variant? }`) — composed from the view assembly's
+ * `meta.sections[type]` editorial fragment. Array order is render order, so a
+ * cross-boundary reorder changes the emitted element/route order. When
+ * `sections` is omitted (or null) the assembly falls back to `meta.slots` order,
+ * which is byte-identical to the committed default template.
+ *
+ * A slot marked `nested: true` (a presentation slot rendered inside its host
+ * element) stays in the ordered composition but is skipped at the top level, so
+ * it contributes no element, catalog entry, registry binding, or route id — the
+ * category `productCard` nested in `CategoryFilter2`. The default category
+ * composition therefore renders exactly the single `category.filter` element.
+ *
+ * Returns the raw source (placeholders intact); callers run
+ * `replacePlaceholders` and write the files.
+ */
+export function assembleView(templateDir, selection = {}, sections = null) {
+  const { meta, selection: resolved } = resolveViewSelection(templateDir, selection)
+  const slotsDir = path.join(assemblyDir(templateDir), 'slots')
+  const slots = Array.isArray(meta.slots) ? meta.slots : []
+  const slotMeta = new Map(slots.map((slot) => [slot.slot, slot]))
+  const sectionMeta =
+    meta.sections && typeof meta.sections === 'object' && !Array.isArray(meta.sections)
+      ? meta.sections
+      : {}
+
+  const ordered = Array.isArray(sections)
+    ? sections
+    : slots
+        .filter((slot) => slot.nested !== true)
+        .map((slot) => ({ id: `slot:${slot.slot}`, type: slot.slot }))
+
+  const elements = []
+  const catalog = []
+  const registry = []
+  const bindings = []
+  const slotIds = []
+  const sectionPropsModules = new Set()
+  const sectionRegistryImports = new Map()
+  for (const entry of ordered) {
+    if (isSlotSectionEntry(entry)) {
+      const slot = slotMeta.get(entry.type)
+      if (!slot) {
+        throw new Error(
+          `View "${meta.view}" has no assembly fragment for registered slot "${entry.type}".`,
+        )
+      }
+      // A nested slot is rendered inside its host element (its own fragment is
+      // authoring-only), so it contributes no top-level output. It stays in the
+      // ordered composition and is validated as a core registered slot.
+      if (slot.nested === true) continue
+      const variant = resolved[slot.slot]
+      const fragmentDir = path.join(slotsDir, slot.slot, variant)
+      elements.push(readPart(fragmentDir, 'element.part'))
+      catalog.push(readPart(fragmentDir, 'catalog.part'))
+      registry.push(readPart(fragmentDir, 'registry.part'))
+      // A fragment may declare no per-variant binding when its block import is
+      // static in the skeleton (a single-variant slot whose import also carries
+      // types the binding format cannot express). Such a fragment adds no import.
+      const bindingPath = path.join(fragmentDir, 'binding.json')
+      if (existsSync(bindingPath)) {
+        bindings.push(JSON.parse(readFileSync(bindingPath, 'utf8')))
+      }
+      slotIds.push(`'${slot.id}'`)
+      continue
+    }
+    const def = sectionMeta[entry.type]
+    if (!def || typeof def.elementType !== 'string' || typeof def.registryExport !== 'string') {
+      throw new Error(
+        `View "${meta.view}" has no editorial fragment for section "${entry.type}".`,
+      )
+    }
+    elements.push(renderEditorialElement(entry, def))
+    registry.push(renderEditorialRegistry(entry, def))
+    slotIds.push(`'${entry.id}'`)
+    sectionPropsModules.add(def.propsModule ?? './content')
+    sectionRegistryImports.set(def.registryModule, def.registryExport)
+  }
+
+  const indexSkeleton = readFileSync(path.join(assemblyDir(templateDir), 'index.skeleton.tsx'), 'utf8')
+  const registrySkeleton = readFileSync(
+    path.join(assemblyDir(templateDir), 'registry.skeleton.tsx'),
+    'utf8',
+  )
+
+  const index = indexSkeleton
+    .replace('@@SECTION_IMPORTS@@', () => renderSectionImports(sectionPropsModules))
+    .replace('@@ELEMENTS@@', () => elements.join('\n'))
+    .replace('@@CATALOG@@', () => catalog.join('\n'))
+    .replace('@@SLOT_IDS@@', () => slotIds.join(', '))
+  const registrySource = registrySkeleton
+    .replace('@@BLOCK_IMPORTS@@', () => renderBlockImports(bindings))
+    .replace('@@SECTION_REGISTRY_IMPORTS@@', () => renderSectionRegistryImports(sectionRegistryImports))
+    .replace('@@REGISTRY@@', () => registry.join('\n'))
+
+  return { index, registry: registrySource, selection: resolved, meta, sections: ordered }
+}
+
+/**
+ * Assemble and write a view's derived `index.tsx` and `registry.tsx` into
+ * `viewDir`. `render` applies placeholder substitution (the caller owns the
+ * subs). Returns the absolute paths that changed; with `dryRun` it reports them
+ * without writing. Idempotent: identical output leaves the files untouched.
+ */
+export async function writeViewAssembly({
+  viewDir,
+  templateDir,
+  selection = {},
+  sections = null,
+  render = (source) => source,
+  dryRun = false,
+} = {}) {
+  const { index, registry } = assembleView(templateDir, selection, sections)
+  const changed = []
+  for (const [name, source] of [
+    ['index.tsx', index],
+    ['registry.tsx', registry],
+  ]) {
+    const dest = path.join(viewDir, name)
+    const next = render(source)
+    const prev = existsSync(dest) ? readFileSync(dest, 'utf8') : null
+    if (prev === next) continue
+    if (!dryRun) {
+      await mkdir(path.dirname(dest), { recursive: true })
+      await writeFile(dest, next)
+    }
+    changed.push(dest)
+  }
+  return changed
+}

package/scripts/view-selection.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// Manifest view selection -> per-slot fragment selection (E1 task 2.2).
+//
+// A view's manifest entry may carry `intents` ({ slot: intentName }) and/or
+// `variants` ({ slot: variantName }). This module is the single resolver that
+// turns either into the `{ slot: variant }` selection the view assembler
+// consumes, so a fresh scaffold and a later reconcile both read the manifest's
+// explicit decisions through one code path.
+//
+// Authority is the single semantic catalog (via `recipes/validate.mjs`): an
+// intent is resolved through the archetype layer and must land on a
+// catalog-executable variant; an explicit variant must itself be
+// catalog-executable. A slot selected by both an intent and a variant has two
+// competing truths and is rejected before any write, matching the `view.add`
+// operation contract. An omitted slot is left out of the selection so the
+// assembler applies the view's declared default.
+
+import {
+  getCatalogVariant,
+  getFeature,
+  isSupportedVariant,
+  normalizeFeatureConfig,
+  resolveIntent,
+  resolveMountClaims,
+} from '../recipes/validate.mjs'
+import { logicalControlFor } from './operation-registry.mjs'
+import { CATALOG_LOGICAL_CONTROL_REGISTRY, logicalControlForMount } from './logical-controls.mjs'
+import { normalizeViewSectionsForView } from './section-compat.mjs'
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Resolve a manifest view entry's explicit selections to a `{ slot: variant }`
+ * map. Returns `{ ok, selection, errors }`; `selection` contains only the slots
+ * the entry selected (omitted slots fall back to the view's defaults).
+ */
+export function resolveViewSelection(viewName, entry = {}) {
+  const errors = []
+  const intents = isPlainObject(entry.intents) ? entry.intents : {}
+  const variants = isPlainObject(entry.variants) ? entry.variants : {}
+  const selection = {}
+
+  for (const slot of Object.keys(intents)) {
+    if (Object.prototype.hasOwnProperty.call(variants, slot)) {
+      errors.push(
+        `Slot "${slot}" in view "${viewName}" is selected by both an intent and a variant; choose exactly one.`,
+      )
+    }
+  }
+
+  for (const [slot, intentName] of Object.entries(intents)) {
+    const resolved = resolveIntent(viewName, slot, intentName)
+    if (!resolved.ok) {
+      errors.push(...resolved.errors)
+      continue
+    }
+    selection[slot] = resolved.variant
+  }
+
+  // An explicit variant is used directly; it never goes through the intent
+  // layer. A slot that also appears in `intents` is a conflict reported above.
+  for (const [slot, variantName] of Object.entries(variants)) {
+    selection[slot] = variantName
+  }
+
+  for (const [slot, variantName] of Object.entries(selection)) {
+    if (isSupportedVariant(viewName, slot, variantName)) continue
+    const held = getCatalogVariant(viewName, slot, variantName)
+    const reason =
+      held?.status === 'held' && typeof held.reason === 'string'
+        ? ` Held reason: ${held.reason}.`
+        : ''
+    errors.push(
+      `Variant "${variantName}" is not executable for ${viewName}.${slot} in the curated MVP set.${reason}`,
+    )
+  }
+
+  return { ok: errors.length === 0, selection, errors }
+}
+
+/**
+ * Resolve the generation-time slot presentation each installed feature instance
+ * mount imposes on its host view (E1 task 3.3). A registry feature declares
+ * `mounts: [{ id, host, slot }]` and a `presentations` map; generation owns the
+ * block wiring by mapping the feature's `config.presentation` through that map
+ * (`compact` -> `Feature1`, `detailed` -> `Feature2`). A mount never carries an
+ * element. Returns
+ * `{ ok, byView: Map<host, { [slot]: { variant, mountId, featureName } }>, errors }`.
+ *
+ * The overrides are generation-only and are never written back to the manifest,
+ * so the view's own stored selection stays dormant and is restored when the
+ * feature is removed. Host-slot claim rules (`E_MOUNT_CONFLICT`,
+ * `E_DUPLICATE_MOUNT_ID`) are resolved through the single registry authority
+ * before any override is built; `options.getFeatureSpec` is the injection seam a
+ * hermetic test uses to exercise a second claim without a generic registry
+ * feature.
+ */
+export function resolveFeatureMountOverrides(manifest, options = {}) {
+  const byView = new Map()
+  const errors = []
+  const featureList = Array.isArray(manifest?.features) ? manifest.features : []
+  const resolve =
+    typeof options.getFeatureSpec === 'function' ? options.getFeatureSpec : getFeature
+  const claims = resolveMountClaims(featureList, { getFeatureSpec: resolve })
+  if (!claims.ok) return { ok: false, byView, errors: claims.errors }
+  for (const feature of featureList) {
+    if (!isPlainObject(feature) || typeof feature.name !== 'string') continue
+    const spec = resolve(feature.name)
+    const mounts = Array.isArray(spec?.mounts) ? spec.mounts : []
+    if (mounts.length === 0) continue
+    // Seed declared defaults so an omitted config resolves to the feature's
+    // default presentation, matching the `feature.add` contract (omitted config
+    // -> the feature's declared defaults).
+    const normalized = normalizeFeatureConfig(
+      feature.name,
+      isPlainObject(feature.config) ? feature.config : {},
+    )
+    if (!normalized.ok) {
+      errors.push(...normalized.errors)
+      continue
+    }
+    const presentations = isPlainObject(spec.presentations) ? spec.presentations : {}
+    const config = normalized.config
+    const presentationKey = config.presentation
+    const variant =
+      typeof presentationKey === 'string' ? presentations[presentationKey] : undefined
+    // E2 task 6.1 (M2 resolution): a mount registered as a logical control is a
+    // contribution to the host's single already-rendered presentation, not a
+    // variant swap. It carries no `presentations` map and no catalog variant, so
+    // the presentation/variant requirement is skipped for exactly those mounts.
+    // The control's visibility is derived at generation time from the installed
+    // manifest (`mountedFeatures`/`mountedFeatureConfigs`), never by replacing
+    // the host slot's selection.
+    const registry = options.logicalControlRegistry ?? CATALOG_LOGICAL_CONTROL_REGISTRY
+    for (const mount of mounts) {
+      if (typeof mount?.host !== 'string' || typeof mount?.slot !== 'string') continue
+      const control =
+        registry === CATALOG_LOGICAL_CONTROL_REGISTRY
+          ? logicalControlForMount(mount.host, mount.slot)
+          : logicalControlFor(registry, mount.host, mount.slot)
+      if (control && control.feature === feature.name) continue
+      if (typeof variant !== 'string') {
+        errors.push(
+          `Feature "${feature.name}" mount "${mount.id}" has no presentation for config.presentation "${presentationKey}".`,
+        )
+        continue
+      }
+      if (!isSupportedVariant(mount.host, mount.slot, variant)) {
+        errors.push(
+          `Feature "${feature.name}" mount "${mount.id}" maps config.presentation "${presentationKey}" to variant "${variant}", which is not executable for ${mount.host}.${mount.slot}.`,
+        )
+        continue
+      }
+      if (!byView.has(mount.host)) byView.set(mount.host, {})
+      byView.get(mount.host)[mount.slot] = {
+        variant,
+        mountId: mount.id,
+        featureName: feature.name,
+      }
+    }
+  }
+  return { ok: errors.length === 0, byView, errors }
+}
+
+/**
+ * Resolve a view's effective generation selection: its own stored selection
+ * overridden by any installed feature instance mount that claims one of its
+ * slots, plus the view's single normalized ordered composition (E3 task 5.1).
+ * `dormant` is the view's stored selection, returned untouched so a later
+ * feature removal restores it. `sections` is the ordered `{ id, type, variant? }`
+ * list from `section-compat.mjs` — the single order truth the view assembler
+ * renders. Returns
+ * `{ ok, selection, dormant, overrides, sections, errors }`.
+ */
+export function resolveViewGenerationSelection(view, byView = new Map()) {
+  const viewName = typeof view === 'string' ? view : view?.name
+  const entry = typeof view === 'string' ? {} : view ?? {}
+  const base = resolveViewSelection(viewName, entry)
+  const overrides = byView.get(viewName) ?? {}
+  // The ordered composition is normalized through the same authority every
+  // section operation uses, so a hand-edited or legacy manifest is either
+  // adapted deterministically or refused (with no output) here, before any
+  // derived file is written.
+  const normalized = normalizeViewSectionsForView(viewName, entry.sections ?? [])
+  if (!base.ok || !normalized.ok) {
+    return {
+      ok: false,
+      selection: {},
+      dormant: {},
+      overrides,
+      sections: null,
+      errors: [...base.errors, ...normalized.diagnostics.map((diagnostic) => diagnostic.message)],
+    }
+  }
+  return {
+    ok: true,
+    selection: { ...base.selection, ...mapOverrideVariants(overrides) },
+    dormant: base.selection,
+    overrides,
+    sections: normalized.sections,
+    errors: [],
+  }
+}
+
+function mapOverrideVariants(overrides) {
+  const out = {}
+  for (const [slot, override] of Object.entries(overrides)) out[slot] = override.variant
+  return out
+}

package/skills/sf-feature/SKILL.md

@@ -0,0 +1,67 @@
+---
+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.
+---
+
+# 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
+file; agents never do.
+
+## Read the registry through the CLI
+
+Run from the storefront project root (no directory argument):
+
+```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.
+
+## Add a feature
+
+```bash
+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.
+
+## Remove a feature
+
+```bash
+npx @thorprovider/storefront feature remove <name>
+```
+
+This removes the bundle, any view no other installed feature owns, its owned
+route, and its mounts. A mount's host view stays installed, so its customized
+content is preserved; if the CLI prints a preserved customized file, relay that
+path to the user.
+
+## Stack constraints
+
+- 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.
+
+## Workflow model
+
+Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
+authority.
+
+## Completion criteria
+
+- The manifest lists (or no longer lists) the feature and its owned views.
+- `npx @thorprovider/storefront sync` reports no drift.

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

@@ -9,6 +9,11 @@ Customize a storefront's theme and identity. This skill ships with everything it
 
 ## Source of truth
 
+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 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.
 
 ## Inputs (the only target-project facts this skill reads)
@@ -43,16 +48,18 @@ Follow `../shadcn-theming/SKILL.md` for OKLCH pair rules and contrast. Paths are
 ## Workflow
 
 1. Use the `question` tool to ask what to customize: colors, typography, identity, SEO, Open Graph.
-2. **Colors**: follow `../shadcn-theming/SKILL.md`; update BOTH `:root` (light) and `.dark` blocks in `app/globals.css`, keeping the `@theme inline` mapping intact.
-3. **Pairs**: every changed color gets its foreground pair in both modes; verify the lightness rule.
-4. **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.
-5. **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.
-6. **Verify**: run the dev server; confirm both color modes, font, and head metadata. `yarn typecheck` passes.
+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.
 
 ## 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.
 
 ## Generation headers
 ```