@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/bin/storefront.js

@@ -4,38 +4,132 @@
 //
 // Actions:
 //   create    Scaffold a complete, runnable storefront AND install the command suite
+//   setup     Connect (or re-point) a real Medusa backend for an existing storefront
 //   update    Refresh an existing install (prunes removed files, migrates the record)
 //   doctor    Report the recorded version and whether the installed skills match this package
 //
-// On a TTY, `create` prompts for missing inputs (name, site name, backend URL, preset —
-// Maia is preselected). Without a TTY, every required input must be a flag; the command
-// fails fast and writes nothing rather than guessing. Brand color is never prompted.
+// On a TTY, `create` prompts for missing inputs (name, site name, preset —
+// Maia is preselected). Empty prompts fall back to their suggested default, so pressing
+// Enter accepts it: the name is suggested from the target directory basename and the
+// site name from the Title Case of that name. Without a TTY, every required input must
+// be a flag; the command fails fast and writes nothing rather than guessing. Brand
+// color is never prompted.
 //
 // The package's generated copies are verified against their source before anything is
 // copied into a target project. On divergence the command stops and writes nothing.
 
-import { cp, mkdir, readdir, readFile, writeFile, rm } from 'node:fs/promises'
+import { cp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
 import { existsSync, readFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { spawnSync } from 'node:child_process'
-import { dirname, join, relative, resolve } from 'node:path'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts'
 import { checkAssets } from '../scripts/sync-assets.mjs'
-import { renderScaffold, toKebab } from '../scripts/render-templates.mjs'
+import { writeInitialEnv, upsertEnv, readEnvFile } from '../scripts/env-file.mjs'
+import { renderScaffold, toKebab, toTitle, injectThemeMode } from '../scripts/render-templates.mjs'
+import { normalizeOperation, planCss, parseSetter } from '../scripts/theme/theme-plan.mjs'
+import { readThemeCss, applyBlockDeclarations } from '../scripts/theme/css-theme.mjs'
+import { applyLayoutFonts, fontCssVars } from '../scripts/theme/fonts.mjs'
+import {
+  buildThemeExport,
+  parseRegistryTheme,
+  parseCssExport,
+  parseThemeExport,
+  classifyImportSource,
+} from '../scripts/theme/import-export.mjs'
+import { resolvePreset, makeShadcnRunner } from '../scripts/theme/preset.mjs'
+import { THEME_COLOR_TOKENS, FONT_VARS, DEFAULT_GLOBALS_TOKENS } from '../scripts/theme/tokens.mjs'
+import { NAMED_COLOR_NAMES, parseColor, formatOklch } from '../scripts/theme/color.mjs'
+import {
+  findProjectRoot,
+  hasManifest,
+  looksLikeStorefront,
+  readManifest,
+  validateManifest,
+  createManifest,
+  writeManifest,
+} from '../scripts/manifest.mjs'
+import { reconcile } from '../scripts/reconcile.mjs'
+import { preflightManifest } from '../scripts/preflight.mjs'
+import { scaffoldComposition } from '../scripts/starter.mjs'
+import {
+  buildInstallPlan,
+  CANDIDATE_TOOLSET,
+  findPack,
+  parseRuntimeCommerceImports,
+  verifyPackExports,
+  verifyPackManifest,
+} from '../scripts/candidate.mjs'
+import {
+  declaredOperativeSkills,
+  hashManagedSuite,
+  hashPaths,
+  managedSuitePaths,
+  readDirectDependencies,
+  readResolvedVersions,
+  readLockfile,
+  readToolchainEvidence,
+  recordedOwnedSet,
+  retirementCandidates,
+  buildPinningRecord,
+  validateDeclaredContract,
+  validatePinning,
+} from '../scripts/pinning.mjs'
+import {
+  loadRecipes,
+  loadArchetypes,
+  loadFeatures,
+  isCuratedView,
+  featureSurfaces,
+  allowedVariantsForView,
+  supportedVariantsForView,
+  supportedIntents,
+  viewCatalog,
+  sectionRegistry,
+  sectionIsDataBound,
+} from '../recipes/validate.mjs'
+import { CATALOG_VERSION, loadCatalog } from '../recipes/catalog.mjs'
+import { OPERATION_NAMES } from '../scripts/operations.mjs'
+import {
+  applyProject,
+  executeOperations,
+  isLegacyViewId,
+  planProject,
+  removeLegacyView,
+  resultEnvelope,
+} from '../scripts/plan-apply.mjs'
+import { SECTION_OPERATION_REGISTRY } from '../scripts/section-operations.mjs'
+import { auditSectionConfig, collectDataBoundInstances } from '../scripts/section-config.mjs'
+import { normalizeViewSectionsForView } from '../scripts/section-compat.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = resolve(__dirname, '..')
 
 const VERSION_RECORD_FILE = 'storefront.json'
 const LEGACY_RECORD_FILE = '.create-storefront.json'
-const COPY_DIRS = ['commands', 'skills']
-// Files that shipped in earlier versions and are no longer part of the suite.
-// `update` prunes them so an upgraded project does not keep running the
-// eliminated /sf-init scaffold wizard.
-const PRUNED_PATHS = ['commands/sf-init.md', 'skills/sf-scaffold']
+// The OpenSpec tool suite owns its own namespace inside the project: it
+// provisions `openspec/`, the `opsx-*` commands, and the `openspec-*` skills.
+// Those files are never storefront-owned, so the suite must not count them as
+// storefront skills, report them as obsolete, or prune them.
+const OPENSPEC_SKILL_PREFIX = 'openspec-'
+// Paths that shipped in earlier versions and are no longer part of the suite.
+// `update` prunes exactly these so an upgraded project does not keep running the
+// eliminated /sf-* commands or the /sf-init scaffold wizard. The whole
+// `commands/` directory is NOT pruned: another tool (OpenSpec) provisions its
+// own commands there, so legacy /sf-* command files are pruned by name and every
+// other command file is preserved. This fixed list is RETAINED: `commands/` is
+// outside the managed suite directories, so the generalized BOM-difference
+// retirement cannot derive it. `skills/sf-scaffold` is additionally reachable
+// through that generalized path (it sits under `skills/`), so the two overlap
+// where ownership is recorded.
+const LEGACY_SKILL_PATHS = ['skills/sf-scaffold']
+const LEGACY_COMMAND_FILE = /^sf-.*\.md$/
 
 const PRESETS = ['maia', 'nova', 'vega', 'luma', 'lyra', 'mira']
+const THEME_MODES = ['light', 'dark', 'system']
+const DEFAULT_THEME_MODE = 'system'
 const PRESET_LABELS = {
   maia: 'Rounded and spacious. Warm and approachable — fits a store.',
   nova: 'Compact and balanced. The neutral default.',
@@ -50,18 +144,98 @@ const HELP = `@thorprovider/storefront — scaffold Thor Commerce storefronts
 
 Usage:
   storefront create <dir> [options]   Scaffold a storefront and install the suite
-  storefront <update|doctor> <dir>    Manage an existing install
+  storefront setup [options]          Connect a real Medusa backend (re-runnable)
+  storefront theme [options]          Customize the theme (mode, colors, fonts, presets)
+  storefront sync                     Reconcile derived files to the manifest
+  storefront views [--json]           List the view registry (recipes, intents, installed)
+  storefront features [--json]        List the feature registry (bundles, installed)
+  storefront recipes [--json]         Print the whole curated registry (views + features)
+  storefront view add|remove <name>   Add or remove a view (reconciles derived files)
+  storefront feature add|remove <name>  Add or remove a feature (installs its views)
+  storefront section add|remove|move <view> ...  Add, remove, or move a section instance
+  storefront sections [<view>] [--json]  List installed views' section instances (read-only)
+  storefront inspect [--json]         Report the versioned catalog and composition (read-only)
+  storefront plan --operations <file> [--out <file>] [--json]
+                                      Validate a whole intended state and emit a plan
+  storefront apply --plan <file> [--json]  Apply a recorded plan from its before-state
+  storefront <update|doctor>          Manage an existing install
+
+Every command except create runs inside the project: it resolves the storefront
+from the current directory upward (storefront.config.json) and errors outside one.
 
 create options:
   --name <name>        storefront name = lib/<name>/ (required without a terminal)
-  --site-name <name>   human site name                 (default: <name>)
-  --backend-url <url>  Medusa backend URL              (default: http://localhost:9000)
+  --site-name <name>   human site name                 (default: Title Case of <name>)
   --preset <preset>    maia | nova | vega | luma | lyra | mira (required without a terminal)
+  --mode <mode>        light | dark | system           (default: system)
+  --starter            install every curated view and feature (a full store),
+                       not just the home+cart baseline
   --brand <color>      brand color over preset tokens  (not prompted by the wizard)
+  --packs <dir>        directory of local @thorprovider/* .tgz tarballs; installs
+                       the local candidate via Yarn resolutions (no publish)
   -f, --force          overwrite files that already exist
   -h, --help           show this help
 
-In a terminal, create prompts for missing inputs (Maia is preselected).
+setup options:
+  --publishable-key <key>  Medusa publishable API key (without a key the store stays
+                           in mock mode)
+  --sales-channel-id <id>  Medusa sales channel id (from the Medusa admin; required)
+  --region-id <id>         Medusa region id (its currency is written)
+  --backend-url <url>      Medusa backend URL        (default: http://localhost:9000)
+
+theme options:
+  (no options)              Inspect the current theme, supported tokens and formats
+  --inspect                 Inspect only (read-only); combine with --json
+  --mode <mode>             light | dark | system (rewritten in app/layout.tsx)
+  --brand <name>            brand color: preset name, #hex or oklch(...) (primary family)
+  --primary <color>         set the primary color (name, #hex, oklch(...))
+  --accent <color>          set the accent color
+  --radius <length>         base corner radius (e.g. 0.75rem); scale derives from it
+  --font-sans <sel>         google:<Family> | system:<stack> (also --font-mono/--font-serif)
+  --set <scope.token=value> set one token (scope: light | dark | shared); repeatable
+  --preset <ref>            shadcn preset name, code or builder URL (theme + fonts only)
+  --only <parts>            with --preset: theme | font | theme,font (default theme,font)
+  --import <source>         import a theme: local .css, local .json, or registry:theme URL
+  --export <file>           write a portable theme snapshot (read-only; never overwrites)
+  --dry-run                 validate and describe the change without writing
+  --json                    machine-readable result
+
+  Visual values live in app/globals.css; the mode lives in storefront.config.json.
+  A later sync never reverts a theme change.
+
+view options:
+  --intent <slot=intent>    choose a slot's intent from the view's recipe
+  --variant <slot=Variant>  choose a slot's variant directly
+  -f, --force               re-add a view that is already installed
+
+feature options:
+  --config <json>           set the feature's config (a JSON object), validated
+                            against its registry contract and persisted
+  -f, --force               re-add a feature that is already installed
+                            (preserves the existing config unless --config is given)
+
+views options:
+  --json                    print the registry (recipes, intents, installed) as JSON
+
+features options:
+  --json                    print the feature registry (bundles, installed) as JSON
+
+recipes options:
+  --json                    print the whole curated registry (views + features) as JSON
+
+section options:
+  --id <id>                 explicit instance id (default: auto-minted <view>-<type>-<n>)
+  --as <Variant>            choose the section's declared variant
+  --after <id> | --before <id>  place relative to an existing instance id
+  --first | --last          place at the start or end of the composition
+  --at <n>                  place at a 0-based index (escape hatch)
+  -f, --force               allow the write when ownership conflicts are detected
+
+sections options:
+  --json                    print the installed views' section instances as JSON
+
+In a terminal, create prompts for missing inputs (Maia is preselected), and setup
+prompts for the backend URL, publishable key, and region.
 Without a terminal, every required input must be a flag — the command fails fast.
 `
 
@@ -72,10 +246,42 @@ function parseArgs(argv) {
     name: null,
     siteName: null,
     backendUrl: null,
+    publishableKey: null,
+    salesChannelId: null,
+    regionId: null,
     preset: null,
+    mode: null,
+    starter: false,
     brand: null,
     force: false,
     help: false,
+    intents: {},
+    variants: {},
+    json: false,
+    packs: null,
+    config: null,
+    operations: null,
+    out: null,
+    plan: null,
+    id: null,
+    as: null,
+    after: null,
+    before: null,
+    first: false,
+    last: false,
+    at: null,
+    primary: null,
+    accent: null,
+    radius: null,
+    sets: [],
+    fontSans: null,
+    fontMono: null,
+    fontSerif: null,
+    inspect: false,
+    only: null,
+    importSource: null,
+    exportPath: null,
+    dryRun: false,
   }
   const positionals = []
   for (let i = 0; i < argv.length; i++) {
@@ -86,10 +292,94 @@ function parseArgs(argv) {
       out.siteName = argv[++i]
     } else if (arg === '--backend-url') {
       out.backendUrl = argv[++i]
+    } else if (arg === '--publishable-key') {
+      out.publishableKey = argv[++i]
+    } else if (arg === '--sales-channel-id') {
+      out.salesChannelId = argv[++i]
+    } else if (arg === '--region-id') {
+      out.regionId = argv[++i]
     } else if (arg === '--preset') {
       out.preset = argv[++i]
+    } else if (arg === '--mode') {
+      out.mode = argv[++i]
+    } else if (arg === '--starter') {
+      out.starter = true
     } else if (arg === '--brand') {
       out.brand = argv[++i]
+    } else if (arg === '--primary') {
+      out.primary = argv[++i]
+    } else if (arg === '--accent') {
+      out.accent = argv[++i]
+    } else if (arg === '--radius') {
+      out.radius = argv[++i]
+    } else if (arg === '--set') {
+      out.sets.push(argv[++i])
+    } else if (arg === '--font-sans') {
+      out.fontSans = argv[++i]
+    } else if (arg === '--font-mono') {
+      out.fontMono = argv[++i]
+    } else if (arg === '--font-serif') {
+      out.fontSerif = argv[++i]
+    } else if (arg === '--inspect') {
+      out.inspect = true
+    } else if (arg === '--only') {
+      out.only = argv[++i]
+    } else if (arg === '--import') {
+      out.importSource = argv[++i]
+    } else if (arg === '--export') {
+      out.exportPath = argv[++i]
+    } else if (arg === '--dry-run') {
+      out.dryRun = true
+    } else if (arg === '--packs') {
+      out.packs = argv[++i]
+    } else if (arg === '--operations') {
+      out.operations = argv[++i]
+    } else if (arg === '--out') {
+      out.out = argv[++i]
+    } else if (arg === '--plan') {
+      out.plan = argv[++i]
+    } else if (arg === '--id') {
+      out.id = argv[++i] ?? null
+    } else if (arg === '--as') {
+      out.as = argv[++i] ?? null
+    } else if (arg === '--after') {
+      out.after = argv[++i] ?? null
+    } else if (arg === '--before') {
+      out.before = argv[++i] ?? null
+    } else if (arg === '--at') {
+      out.at = argv[++i] ?? null
+    } else if (arg === '--first') {
+      out.first = true
+    } else if (arg === '--last') {
+      out.last = true
+    } else if (arg === '--intent') {
+      const pair = argv[++i] ?? ''
+      const eq = pair.indexOf('=')
+      if (eq === -1) {
+        console.error(`--intent expects slot=intent (got "${pair}")`)
+        process.exitCode = 1
+        return null
+      }
+      out.intents[pair.slice(0, eq)] = pair.slice(eq + 1)
+    } else if (arg === '--variant') {
+      const pair = argv[++i] ?? ''
+      const eq = pair.indexOf('=')
+      if (eq === -1) {
+        console.error(`--variant expects slot=Variant (got "${pair}")`)
+        process.exitCode = 1
+        return null
+      }
+      out.variants[pair.slice(0, eq)] = pair.slice(eq + 1)
+    } else if (arg === '--json') {
+      out.json = true
+    } else if (arg === '--config') {
+      const value = argv[++i]
+      if (value === undefined) {
+        console.error('--config expects a JSON object value.')
+        process.exitCode = 1
+        return null
+      }
+      out.config = value
     } else if (arg === '--force' || arg === '-f') {
       out.force = true
     } else if (arg === '--help' || arg === '-h') {
@@ -103,11 +393,84 @@ function parseArgs(argv) {
     }
   }
   out.action = positionals[0] ?? null
+  out.positionals = positionals
   if (positionals[1]) out.dir = resolve(positionals[1])
   else if (!out.dir) out.dir = process.cwd()
   return out
 }
 
+// Only `create` takes a directory. Every other command runs inside the project
+// and resolves the storefront from the current directory upward. When none is
+// found the command fails before touching the filesystem.
+// Search upward for a pre-manifest install record (the old `.create-storefront.json`).
+// Used only as a fallback signal when no storefront-shaped project is found.
+function findLegacyRoot(startDir) {
+  let current = startDir
+  while (true) {
+    if (existsSync(join(current, '.opencode', LEGACY_RECORD_FILE))) return current
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+// Legacy (pre-manifest) projects are detected and refused with a no-write
+// diagnostic. Automatic migration is held post-MVP (see trace-matrix.md), so
+// this must run before any command function and touch nothing on disk.
+function rejectLegacyProject(target) {
+  console.error(`No storefront.config.json found in ${target}, but it looks like a pre-manifest (legacy) storefront.`)
+  console.error('Automatic legacy migration is held post-MVP (traced in trace-matrix.md). No files were changed.')
+  console.error('Run `storefront create <dir>` to scaffold a new storefront, or add storefront.config.json manually.')
+  return 1
+}
+
+function resolveProject({ quiet = false } = {}) {
+  const root = findProjectRoot(process.cwd()) ?? findLegacyRoot(process.cwd())
+  if (!root) {
+    if (!quiet) {
+      console.error('Not inside a storefront project (no storefront.config.json found in this directory or any parent).')
+      console.error('Run `storefront create <dir>` to create one, or run this command from inside a storefront.')
+    }
+    return null
+  }
+  if (!hasManifest(root) && (looksLikeStorefront(root) || existsSync(join(root, '.opencode', LEGACY_RECORD_FILE)))) {
+    if (!quiet) rejectLegacyProject(root)
+    return null
+  }
+  return root
+}
+
+// Read and validate the project manifest, distinguishing a physically absent
+// config (legacy project with no manifest yet) from a present config that parses
+// to a non-object JSON value (`null`, `false`, `0`, `""`, `[]`). A present config
+// is validated against the published shape here, at the shared read boundary, so
+// no caller can mistake an invalid existing config for absence and write around
+// it. Returns { manifest } (object) for a valid config, { manifest: null } for a
+// truly absent one, or { error } with a precise input diagnostic.
+function readManifestOrError(target) {
+  if (!hasManifest(target)) return { manifest: null }
+
+  let manifest
+  try {
+    manifest = readManifest(target)
+  } catch (err) {
+    return { error: `storefront.config.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+    return { error: 'storefront.config.json must contain a JSON object.' }
+  }
+
+  const shape = validateManifest(manifest)
+  if (!shape.ok) {
+    return {
+      error: `storefront.config.json does not satisfy the published schema:\n${shape.errors.map((error) => `    ${error}`).join('\n')}`,
+    }
+  }
+
+  return { manifest }
+}
+
 async function copyDir(from, to, force) {
   const entries = await readdir(from, { withFileTypes: true })
   let copied = 0
@@ -131,26 +494,81 @@ async function prunePath(opencodeDir, relPath) {
   await rm(join(opencodeDir, relPath), { recursive: true, force: true })
 }
 
-function sha256(text) {
-  return createHash('sha256').update(text).digest('hex')
+// Prune the legacy storefront-owned paths an earlier generation left behind,
+// file by file, so a co-tenant tool's files survive. The retired /sf-* command
+// files are removed individually; the `commands/` directory itself is removed
+// only when it is left empty. Every other command file (for example OpenSpec's
+// `opsx-*`) is preserved. Returns the pruned command paths.
+async function pruneLegacySuitePaths(opencodeDir) {
+  for (const rel of LEGACY_SKILL_PATHS) await prunePath(opencodeDir, rel)
+  const commandsDir = join(opencodeDir, 'commands')
+  const pruned = []
+  if (!existsSync(commandsDir)) return pruned
+  for (const entry of await readdir(commandsDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue
+    if (!LEGACY_COMMAND_FILE.test(entry.name)) continue
+    await rm(join(commandsDir, entry.name), { force: true })
+    pruned.push(`commands/${entry.name}`)
+  }
+  // Remove the directory only when nothing else is co-tenanted there.
+  if ((await readdir(commandsDir)).length === 0) await rm(commandsDir, { recursive: true, force: true })
+  return pruned
 }
 
-async function hashDir(dir) {
-  const files = []
-  async function walk(d) {
-    for (const entry of await readdir(d, { withFileTypes: true })) {
-      const full = join(d, entry.name)
-      if (entry.isDirectory()) await walk(full)
-      else files.push(full)
+// Resolve the pinned OpenSpec CLI from the package's own dependency so
+// provisioning is deterministic and offline once installed. `@fission-ai/openspec`
+// declares an `exports` map without `./package.json`, so resolve its entry point
+// and read the `bin` field from the package directory instead.
+function resolveOpenSpecBin() {
+  try {
+    const require = createRequire(import.meta.url)
+    const entry = require.resolve('@fission-ai/openspec')
+    const pkgDir = dirname(dirname(entry))
+    const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'))
+    const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.openspec
+    if (rel) {
+      const abs = resolve(pkgDir, rel)
+      if (existsSync(abs)) return { ok: true, bin: abs, version: pkg.version }
+    }
+    return { ok: false, error: 'the @fission-ai/openspec package has no resolvable bin' }
+  } catch {
+    return {
+      ok: false,
+      error: 'the pinned @fission-ai/openspec dependency is not installed; run `yarn install`',
     }
   }
-  if (existsSync(dir)) await walk(dir)
-  files.sort()
-  const lines = []
-  for (const f of files) {
-    lines.push(`${relative(dir, f)}:${sha256(await readFile(f, 'utf8'))}`)
+}
+
+// Seed the storefront-aware OpenSpec model into the generated project. The
+// config is storefront-owned: `update` re-applies it after re-running init, so
+// the model stays authoritative and customization belongs in storefront files,
+// not in `openspec/`.
+async function seedOpenSpecConfig(target) {
+  const template = join(PKG_ROOT, 'assets', 'openspec', 'config.yaml')
+  const dest = join(target, 'openspec', 'config.yaml')
+  await mkdir(dirname(dest), { recursive: true })
+  await writeFile(dest, readFileSync(template, 'utf8'), 'utf8')
+}
+
+// Provision the OpenSpec spec-driven workflow into the target through the pinned
+// CLI. The CLI runs under the current Node so the invocation is portable and
+// non-interactive; a failure is returned as a diagnostic and never masked. After
+// a successful init the storefront model is seeded into `openspec/config.yaml`.
+async function provisionOpenSpec(target) {
+  const resolved = resolveOpenSpecBin()
+  if (!resolved.ok) return { ok: false, error: resolved.error }
+  const result = spawnSync(
+    process.execPath,
+    [resolved.bin, 'init', '--tools', 'opencode', '--no-animation'],
+    { cwd: target, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  if (result.error) return { ok: false, error: result.error.message }
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim().split('\n').pop()
+    return { ok: false, error: detail || `openspec init exited with code ${result.status}` }
   }
-  return sha256(lines.join('\n'))
+  await seedOpenSpecConfig(target)
+  return { ok: true, version: resolved.version }
 }
 
 function pkgVersion() {
@@ -172,14 +590,82 @@ async function readRecord(opencodeDir) {
   return null
 }
 
+// The installed package-owned suite digests. Only the package's own file set is
+// hashed, so a user's custom skill/command file under `.opencode/` never shows
+// up as drift or gets stamped into the record.
+async function installedSuiteBom(projectDir) {
+  return hashPaths(join(projectDir, '.opencode'), managedSuitePaths(PKG_ROOT))
+}
+
+async function collectLivePinning(projectDir) {
+  const direct = readDirectDependencies(projectDir)
+  if (!direct.ok) return { ok: false, error: direct.error }
+  const resolvedVersions = readResolvedVersions(projectDir, Object.keys(direct.dependencies))
+  const lock = readLockfile(projectDir)
+  if (!lock.ok) return { ok: false, error: lock.error }
+  const toolchain = readToolchainEvidence(projectDir)
+  if (!toolchain.ok) return { ok: false, error: toolchain.error }
+  const assets = await installedSuiteBom(projectDir)
+  return {
+    ok: true,
+    live: {
+      directDependencies: direct.dependencies,
+      resolvedVersions,
+      lockfile: lock.lockfile,
+      toolchain: toolchain.toolchain,
+      assets,
+    },
+  }
+}
+
+// Validate every *precomputable* layer of the incoming record — declared ranges,
+// resolved versions, the lockfile, and the toolchain/linker — BEFORE any
+// structural write. Assets are expected to change when the suite is refreshed,
+// so they are checked after the copy at stamp time (`writeRecord`). Returns
+// `{ ok, errors }`.
+async function validateIncomingContract(projectDir, version) {
+  const collected = await collectLivePinning(projectDir)
+  if (!collected.ok) return { ok: false, errors: [collected.error] }
+  const incoming = buildPinningRecord({
+    cliVersion: version,
+    directDependencies: collected.live.directDependencies,
+    resolvedVersions: collected.live.resolvedVersions,
+    lockfile: collected.live.lockfile,
+    assets: await hashManagedSuite(PKG_ROOT),
+  })
+  return validatePinning(incoming, {
+    distributedVersion: version,
+    live: collected.live,
+    includeAssets: false,
+  })
+}
+
+// Stamp the install record from the actual, complete project evidence. The
+// record pins the *distributed* package BOM; it is validated against the live
+// installed artifacts before it is written, so a failed copy or an incoherent
+// pin set is reported and never stamped.
 async function writeRecord(projectDir, version) {
+  const collected = await collectLivePinning(projectDir)
+  if (!collected.ok) return { ok: false, errors: [collected.error] }
+  const { directDependencies, resolvedVersions, lockfile } = collected.live
+  const assets = await hashManagedSuite(PKG_ROOT)
+  const pinning = buildPinningRecord({
+    cliVersion: version,
+    directDependencies,
+    resolvedVersions,
+    lockfile,
+    assets,
+  })
+  const check = validatePinning(pinning, { distributedVersion: version, live: collected.live })
+  if (!check.ok) return { ok: false, errors: check.errors }
   const opencodeDir = join(projectDir, '.opencode')
   await mkdir(opencodeDir, { recursive: true })
   await writeFile(
     join(opencodeDir, VERSION_RECORD_FILE),
-    JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2) + '\n',
+    JSON.stringify({ version, installedAt: new Date().toISOString(), pinning }, null, 2) + '\n',
     'utf8',
   )
+  return { ok: true, pinning }
 }
 
 async function verifyConsistency() {
@@ -195,69 +681,115 @@ async function verifyConsistency() {
 
 async function installSuite(opencodeDir, force) {
   let total = 0
-  for (const dir of COPY_DIRS) {
-    const from = join(PKG_ROOT, dir)
-    const to = join(opencodeDir, dir)
-    await mkdir(to, { recursive: true })
+  // The operative set comes from the single declared source — the package skill
+  // layout (`skills/<name>/SKILL.md`). A directory without a SKILL.md is not a
+  // skill and is not installed; the files inside an operative skill (its scoped
+  // references, assets, and scripts) travel with it but are never treated as
+  // skills. `create` and `update` read the same source, so the installed set
+  // cannot drift between them.
+  for (const skillRel of declaredOperativeSkills(PKG_ROOT)) {
+    const from = join(PKG_ROOT, skillRel)
+    const to = join(opencodeDir, skillRel)
+    await mkdir(dirname(to), { recursive: true })
     total += await copyDir(from, to, force)
   }
   return total
 }
 
-function run(cmd, cmdArgs, cwd) {
-  const res = spawnSync(cmd, cmdArgs, { cwd, stdio: 'inherit', shell: false })
+// Remove `dir` and any now-empty parent directories up to (but not including)
+// `stopAt`. Used after retiring obsolete owned files so a removed skill does not
+// leave an empty discoverable directory behind.
+async function pruneEmptyParents(dir, stopAt) {
+  let current = dir
+  while (current.startsWith(stopAt) && current !== stopAt) {
+    let entries
+    try {
+      entries = await readdir(current)
+    } catch {
+      return
+    }
+    if (entries.length > 0) return
+    await rm(current, { recursive: true, force: true })
+    current = dirname(current)
+  }
+}
+
+// Retire the recorded owned files the package no longer ships. A candidate is
+// removed ONLY when its live content still matches the recorded package render
+// (its recorded digest). A modified candidate is preserved and returned so the
+// caller can report it; a file with no package record is never a candidate and
+// is left untouched. Returns the retired and preserved (modified) paths.
+async function retireObsoleteOwnedFiles(opencodeDir, recordedAssets) {
+  const retired = []
+  const preserved = []
+  const candidates = retirementCandidates(recordedAssets, managedSuitePaths(PKG_ROOT))
+  for (const rel of candidates) {
+    const abs = join(opencodeDir, rel)
+    if (!existsSync(abs)) continue
+    const liveDigest = hashPaths(opencodeDir, [rel])[rel]
+    if (liveDigest === recordedAssets[rel]) {
+      await rm(abs, { force: true })
+      retired.push(rel)
+    } else {
+      preserved.push(rel)
+    }
+  }
+  for (const rel of retired) await pruneEmptyParents(dirname(join(opencodeDir, rel)), opencodeDir)
+  return { retired, preserved }
+}
+
+// The installed skills that are not part of the package's current operative set.
+// A directory under `.opencode/skills/` containing a `SKILL.md` is a
+// discoverable skill; one the package no longer ships (or that was added by
+// hand) is not in the incoming set. Returned sorted so the completion output can
+// refuse a clean migration while one remains.
+async function remainingNonSuiteSkills(opencodeDir) {
+  const incoming = new Set(
+    declaredOperativeSkills(PKG_ROOT).map((rel) => rel.slice(rel.lastIndexOf('/') + 1)),
+  )
+  const skillsDir = join(opencodeDir, 'skills')
+  const remaining = []
+  if (!existsSync(skillsDir)) return remaining
+  for (const entry of await readdir(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    // The OpenSpec suite owns its own namespaced skills; they are not part of
+    // the storefront operative set and must never be reported as leftovers.
+    if (entry.name.startsWith(OPENSPEC_SKILL_PREFIX)) continue
+    if (!existsSync(join(skillsDir, entry.name, 'SKILL.md'))) continue
+    if (!incoming.has(entry.name)) remaining.push(entry.name)
+  }
+  return remaining.sort()
+}
+
+// Run Yarn under the pinned Corepack version (`yarn@x.y.z`), so the scaffold
+// and every install use the canonical package manager deterministically rather
+// than whatever "known good release" Corepack would otherwise pick.
+function runYarn(yarnSpec, cmdArgs, cwd) {
+  const res = spawnSync('corepack', [yarnSpec, ...cmdArgs], { cwd, stdio: 'inherit', shell: false })
   return res.status ?? 1
 }
 
-const BRAND_TOKEN_KEYS = {
-  light: ['--primary', '--primary-foreground', '--nav', '--ring'],
-  dark: ['--primary', '--primary-foreground', '--nav', '--ring'],
-}
-
-const COLOR_HUES = {
-  red: 27,
-  orange: 55,
-  amber: 75,
-  yellow: 95,
-  lime: 130,
-  green: 155,
-  teal: 185,
-  cyan: 210,
-  blue: 232,
-  indigo: 264,
-  violet: 290,
-  purple: 310,
-  pink: 350,
-  slate: 240,
-  gray: 240,
-  neutral: 0,
-  stone: 60,
-}
-
-function applyBrand(globalsCss, brand) {
-  if (!brand) return globalsCss
-  const hue = COLOR_HUES[brand]
-  if (hue === undefined) {
-    console.error(`Unknown brand color: ${brand}`)
-    process.exitCode = 1
-    return globalsCss
-  }
-  // Swap the hue channel (third component) of each brand token's oklch value in
-  // both modes. Lightness/chroma stay from the preset so the contrast pair rule
-  // is preserved; only the hue carries the brand color.
-  let css = globalsCss
-  for (const key of [...BRAND_TOKEN_KEYS.light, ...BRAND_TOKEN_KEYS.dark]) {
-    css = css.replace(new RegExp(`(${key}: oklch\\([^)]*?\\s)([^\\s)]+)(\\))`, 'g'), `$1${hue}$3`)
-  }
-  return css
+// Apply a named brand color through the same transformation the `theme` command
+// uses, so `create --brand` and `theme --brand` agree: real chromatic palette
+// values (not a hue swap on a possibly-achromatic preset), a measured-contrast
+// foreground, and the documented primary family. Returns `{ css }` or `{ error }`.
+function applyBrandToGlobals(globalsCss, brand) {
+  if (!brand) return { css: globalsCss }
+  const { operation, diagnostics } = normalizeOperation({ brand })
+  const error = diagnostics.find((d) => d.severity === 'error')
+  if (error) return { error: error.message }
+  const planned = planCss(globalsCss, operation)
+  const planError = planned.diagnostics.find((d) => d.severity === 'error')
+  if (planError) return { error: planError.message }
+  return { css: planned.css }
 }
 
 async function promptScaffoldInputs(args) {
   const inputs = {
     name: toKebab(args.name ?? '') || null,
     siteName: args.siteName ?? null,
-    backendUrl: args.backendUrl ?? null,
     preset: args.preset ?? null,
+    mode: args.mode ?? null,
     brand: args.brand ?? null,
   }
 
@@ -265,11 +797,20 @@ async function promptScaffoldInputs(args) {
   if (tty) {
     intro('storefront create')
 
+    // The suggested name comes from the target directory basename, so
+    // `storefront create .` or `../shop` still suggest the right thing.
+    const suggestedName = toKebab(basename(args.dir ?? '')) || 'my-shop'
+
     if (!inputs.name) {
       const value = await text({
         message: 'Storefront name (kebab-case — lib/<name>/):',
-        placeholder: 'my-shop',
-        validate: (v) => (toKebab(v ?? '').length ? undefined : 'Enter a kebab-case name'),
+        placeholder: suggestedName,
+        defaultValue: suggestedName,
+        // Empty is valid: clack validates the raw value before applying
+        // `defaultValue`, so rejecting empty here would block Enter from
+        // accepting the suggested name. Only input that normalizes to nothing
+        // (e.g. "!!!") is rejected.
+        validate: (v) => (!v || toKebab(v).length ? undefined : 'Enter a kebab-case name'),
       })
       if (isCancel(value)) {
         cancel('Operation cancelled.')
@@ -279,9 +820,11 @@ async function promptScaffoldInputs(args) {
     }
 
     if (!inputs.siteName) {
+      const suggestedSiteName = toTitle(inputs.name)
       const value = await text({
         message: 'Site name:',
-        initialValue: inputs.name,
+        placeholder: suggestedSiteName,
+        defaultValue: suggestedSiteName,
       })
       if (isCancel(value)) {
         cancel('Operation cancelled.')
@@ -290,18 +833,6 @@ async function promptScaffoldInputs(args) {
       inputs.siteName = value
     }
 
-    if (!inputs.backendUrl) {
-      const value = await text({
-        message: 'Medusa backend URL:',
-        initialValue: DEFAULT_BACKEND_URL,
-      })
-      if (isCancel(value)) {
-        cancel('Operation cancelled.')
-        process.exit(0)
-      }
-      inputs.backendUrl = value
-    }
-
     if (!inputs.preset) {
       const value = await select({
         message: 'Visual preset:',
@@ -318,6 +849,23 @@ async function promptScaffoldInputs(args) {
       inputs.preset = value
     }
 
+    if (!inputs.mode) {
+      const value = await select({
+        message: 'Site color mode:',
+        initialValue: DEFAULT_THEME_MODE,
+        options: [
+          { value: 'system', label: 'system — follow the visitor’s OS preference' },
+          { value: 'light', label: 'light — always render light' },
+          { value: 'dark', label: 'dark — always render dark' },
+        ],
+      })
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      inputs.mode = value
+    }
+
     outro('Scaffolding…')
   }
 
@@ -325,19 +873,38 @@ async function promptScaffoldInputs(args) {
   if (!inputs.name) missing.push('storefront name (--name <name>)')
   if (!inputs.preset) missing.push('--preset (one of: ' + PRESETS.join(', ') + ')')
   else if (!PRESETS.includes(inputs.preset)) missing.push(`--preset must be one of: ${PRESETS.join(', ')}`)
+  if (inputs.mode && !THEME_MODES.includes(inputs.mode)) missing.push(`--mode must be one of: ${THEME_MODES.join(', ')}`)
 
   if (missing.length > 0) return { missing }
   return {
     inputs: {
       name: inputs.name,
-      siteName: inputs.siteName ?? inputs.name,
-      backendUrl: inputs.backendUrl ?? DEFAULT_BACKEND_URL,
+      siteName: inputs.siteName ?? toTitle(inputs.name),
       preset: inputs.preset,
+      mode: inputs.mode ?? DEFAULT_THEME_MODE,
       brand: inputs.brand,
     },
   }
 }
 
+// Every structural write boundary validates the complete desired composition
+// first. On rejection nothing is written: no manifest, no derived file, and no
+// directory change.
+function rejectComposition(errors) {
+  console.error('Refusing to write: the desired composition is invalid.')
+  for (const err of errors) console.error(`  ${err}`)
+  return 1
+}
+
+// Print the structured diagnostics the operation engine returns, using the same
+// header every structural write boundary prints so existing consumers keep their
+// wording (E1 task 4.1).
+function rejectDiagnostics(diagnostics) {
+  console.error('Refusing to write: the desired composition is invalid.')
+  for (const diag of diagnostics) console.error(`  ${diag.message}`)
+  return 1
+}
+
 async function create(args) {
   const target = args.dir
   const { inputs, missing } = await promptScaffoldInputs(args)
@@ -347,13 +914,96 @@ async function create(args) {
     return 1
   }
 
-  const { name, siteName, backendUrl, preset, brand } = inputs
+  const { name, siteName, preset, mode, brand } = inputs
+
+  if (args.backendUrl) {
+    console.error('storefront create no longer takes --backend-url; a created store starts in mock mode.')
+    console.error('Run `storefront setup` after creating to connect a real backend.')
+    return 1
+  }
+
+  // The candidate CLI is the structural authority; the generated project pins
+  // the exact compatible toolset (and the CLI itself). Declared here so the
+  // contract can be validated before the first write.
+  const cliVersion = pkgVersion()
+  const plan = buildInstallPlan({ cliVersion, packsDir: args.packs ? resolve(args.packs) : null })
+  if (plan.missingPacks.length > 0) {
+    console.error(`Refusing to create: missing packed local candidate(s) in ${resolve(args.packs)}:`)
+    for (const name of plan.missingPacks) console.error(`  ${name}`)
+    console.error('Pack each @thorprovider/* package with `yarn pack --filename <slug>-<version>.tgz`.')
+    return 1
+  }
+
+  // Integrity guard for the local candidate packs. A `--packs` directory can be
+  // stale: a tarball packed before a public export was added still resolves for
+  // the same exact version, so the generated project imports a symbol the
+  // packed dist does not export. Verify each pack declares the expected
+  // name+version (Tier 1) and that the packed runtime actually exports every
+  // value the generated host imports from `@thorprovider/runtime/commerce`
+  // (Tier 2) before the first write.
+  if (args.packs) {
+    const packsDir = resolve(args.packs)
+    const localPacks = { ...CANDIDATE_TOOLSET.local, '@thorprovider/storefront': cliVersion }
+    for (const [name, version] of Object.entries(localPacks)) {
+      const guard = verifyPackManifest({ tgzPath: findPack(packsDir, name, version), name, version })
+      if (!guard.ok) {
+        console.error(`Refusing to create: ${guard.message} (${guard.code})`)
+        return 1
+      }
+    }
+    const commerceTemplate = join(PKG_ROOT, 'assets', 'templates', 'app', 'lib', '__STOREFRONT__', 'commerce.ts')
+    const requiredExports = parseRuntimeCommerceImports(readFileSync(commerceTemplate, 'utf8'))
+    const runtimeName = '@thorprovider/runtime'
+    const runtimeGuard = verifyPackExports({
+      tgzPath: findPack(packsDir, runtimeName, CANDIDATE_TOOLSET.local[runtimeName]),
+      innerPath: 'package/dist/commerce/index.mjs',
+      requiredExports,
+    })
+    if (!runtimeGuard.ok) {
+      console.error(`Refusing to create: ${runtimeGuard.message} (${runtimeGuard.code})`)
+      return 1
+    }
+  }
+
+  // Validate the complete desired composition before the first filesystem
+  // operation. Without `--starter`, `create` composes the home baseline plus the
+  // standalone cart review view. With `--starter`, it composes the full curated
+  // set: every curated feature and every curated view (the standalone views plus
+  // the feature-owned views each feature installs). Either way it must pass the
+  // same preflight as every other write boundary — and it must run before any
+  // mkdir, external scaffold, or write so rejected input leaves no trace.
+  const starter = args.starter === true
+  const composition = scaffoldComposition({ starter })
+  const manifest = createManifest({
+    name,
+    siteName,
+    mode,
+    views: composition.views,
+    features: composition.features,
+  })
+  const preflight = preflightManifest(manifest)
+  if (!preflight.ok) return rejectComposition(preflight.errors)
+
+  // Validate the incoming pinning contract before the first write too. The
+  // generated project declares the exact compatible toolset and pins the CLI
+  // itself; the intended linker is the one `create` writes below.
+  const declared = validateDeclaredContract({
+    directDependencies: plan.dependencies,
+    cliVersion,
+    distributedVersion: cliVersion,
+    toolchain: { linker: 'node-modules', nodeVersion: process.versions.node, yarnVersion: null },
+  })
+  if (!declared.ok) {
+    console.error('Refusing to create: the declared pinning contract is invalid.')
+    for (const err of declared.errors) console.error(`  ${err}`)
+    return 1
+  }
 
   console.log('storefront create — deterministic scaffold')
   console.log(`  name:        ${name}`)
   console.log(`  site name:   ${siteName}`)
-  console.log(`  backend:     ${backendUrl}`)
   console.log(`  preset:      ${preset}`)
+  console.log(`  mode:        ${mode}`)
   if (brand) console.log(`  brand:       ${brand}`)
   console.log(`  target:      ${target}`)
 
@@ -365,7 +1015,7 @@ async function create(args) {
   const libDir = join(target, 'lib', name)
   if (existsSync(libDir)) {
     console.error(`lib/${name}/ already exists — refusing to overwrite.`)
-    console.error('Use /sf-add-view to extend an existing storefront.')
+    console.error('This target already holds a storefront; extend it through the storefront CLI (see AGENTS.md).')
     return 1
   }
   if (!(await verifyConsistency())) return 1
@@ -381,7 +1031,11 @@ async function create(args) {
       await cp(opencodeDir, stash, { recursive: true })
       await rm(opencodeDir, { recursive: true, force: true })
     }
-    const status = run('yarn', ['create', 'next-app', '.', '--ts', '--tailwind', '--app', '--import-alias', '@/*', '--no-turbopack'], target)
+    // --skip-install: the first install is ours to run, under the .yarnrc.yml
+    // written in step 3, so network hardening applies to every install. The
+    // pinned package manager is forced for the bootstrap too (Corepack), so the
+    // whole scaffold runs under the canonical Yarn, not a floating release.
+    const status = runYarn(plan.packageManager, ['dlx', `create-next-app@${plan.scaffolder.createNextApp}`, '.', '--ts', '--tailwind', '--app', '--import-alias', '@/*', '--no-turbopack', '--use-yarn', '--skip-install'], target)
     if (hadOpenCode) {
       await cp(stash, opencodeDir, { recursive: true })
       await rm(stash, { recursive: true, force: true })
@@ -392,10 +1046,42 @@ async function create(args) {
     }
   }
 
-  // 3. shadcn base
-  const shadcnStatus = run(
-    'yarn',
-    ['dlx', 'shadcn@latest', 'init', '--template', 'next', '--base', 'base', '--preset', preset, '--no-monorepo', '--no-rtl', '--yes'],
+  // 3. Yarn config — before ANY install (shadcn included): node-modules linker,
+  //    retries and low concurrency to survive unreliable networks. With the
+  //    global cache warm, repeat scaffolds only need tiny metadata requests —
+  //    or none at all via YARN_ENABLE_OFFLINE_MODE=1. No package-manager safety
+  //    gate is suppressed: the pinned toolset versions are already published
+  //    past Yarn's `npmMinimalAgeGate`, so no allowlist is needed.
+  await writeFile(
+    join(target, '.yarnrc.yml'),
+    [
+      'nodeLinker: node-modules',
+      'httpRetry: 10',
+      'networkConcurrency: 8',
+    ].join('\n') + '\n',
+    'utf8',
+  )
+  await rm(join(target, '.pnp.cjs'), { force: true })
+
+  // 3b. Pin the package manager (Corepack reads `packageManager`) and the local
+  //     candidate. Yarn `resolutions` map each local @thorprovider/* package to
+  //     its packed tarball while the declared dependency ranges stay honest
+  //     semver. Written before any install so the whole tree resolves to the
+  //     local candidate (no publish, no workspace import) under the pinned Yarn.
+  {
+    const pkgPath = join(target, 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    pkg.packageManager = plan.packageManager
+    if (Object.keys(plan.resolutions).length > 0) {
+      pkg.resolutions = { ...(pkg.resolutions ?? {}), ...plan.resolutions }
+    }
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+  }
+
+  // 4. shadcn base
+  const shadcnStatus = runYarn(
+    plan.packageManager,
+    ['dlx', `shadcn@${plan.scaffolder.shadcn}`, 'init', '--template', 'next', '--base', 'base', '--preset', preset, '--no-monorepo', '--no-rtl', '--yes'],
     target,
   )
   if (shadcnStatus !== 0) {
@@ -403,51 +1089,233 @@ async function create(args) {
     return shadcnStatus
   }
 
-  // 4. Yarn node-modules linker
-  await writeFile(join(target, '.yarnrc.yml'), 'nodeLinker: node-modules\n', 'utf8')
-  await rm(join(target, '.pnp.cjs'), { force: true })
+  // 4b. Pin the shadcn CLI exactly. `shadcn init` adds itself with a caret; a
+  //     caret would re-resolve to the newest (possibly age-gated) release on the
+  //     final install, so write the exact scaffolded version first.
+  {
+    const pkgPath = join(target, 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    for (const field of ['dependencies', 'devDependencies']) {
+      if (pkg[field] && pkg[field].shadcn) pkg[field].shadcn = plan.scaffolder.shadcn
+    }
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+  }
 
-  // 5. Dependencies
-  const STOREFRONT_DEPS = [
-    '@thorprovider/blocks',
-    '@thorprovider/adapters',
-    '@thorprovider/runtime',
-    '@json-render/core',
-    '@json-render/react',
-    '@json-render/next',
-    'motion',
-    'zod',
-  ]
-  const addStatus = run('yarn', ['add', ...STOREFRONT_DEPS], target)
+  // 5. Dependencies — every declared dep at its exact compatible version,
+  //    including the exact candidate CLI.
+  const installDeps = Object.entries(plan.dependencies).map(([dep, version]) => `${dep}@${version}`)
+  const addStatus = runYarn(plan.packageManager, ['add', ...installDeps], target)
   if (addStatus !== 0) {
     console.error('yarn add failed.')
     return addStatus
   }
 
-  // 6. Template copy + placeholder substitution
-  await renderScaffold({ targetDir: target, name, siteName })
+  // 6. Template copy + placeholder substitution, then reconcile to the manifest.
+  //    The manifest was built and validated before any write above. Passing its
+  //    view entries means the fresh scaffold resolves explicit slot selections
+  //    through the same pipeline a later reconcile uses.
+  await renderScaffold({ targetDir: target, name, siteName, mode, views: manifest.views, features: manifest.features })
+  await writeManifest(target, manifest)
+  const result = await reconcile(target, manifest)
+  if (!result.ok) return rejectComposition(result.errors)
 
   // 7. .env.local + theme
-  const envLocal = `MEDUSA_BACKEND_URL=${backendUrl}\nMEDUSA_REGION_ID=\nMEDUSA_PUBLISHABLE_KEY=\n`
-  await writeFile(join(target, '.env.local'), envLocal, 'utf8')
+  //    `create` is offline and structural: it starts the store in mock mode, a
+  //    complete state that needs no backend. The only secret it writes is the
+  //    per-install session signing secret, which the guest cart and checkout
+  //    cookie signing requires in every mode. Real backend configuration is
+  //    written by `storefront setup`, never here, so no blank MEDUSA_* value is
+  //    ever produced. An existing .env.local is user-owned (a `setup` run or a
+  //    hand edit) and is left untouched.
+  await writeInitialEnv(target, name)
 
   const globalsPath = join(target, 'app', 'globals.css')
   if (existsSync(globalsPath)) {
     const css = readFileSync(globalsPath, 'utf8')
-    await writeFile(globalsPath, applyBrand(css, brand), 'utf8')
+    const branded = applyBrandToGlobals(css, brand)
+    if (branded.error) {
+      console.error(`Unknown brand color: ${branded.error}`)
+      return 1
+    }
+    if (branded.css !== css) await writeFile(globalsPath, branded.css, 'utf8')
   }
 
   // 8. Suite install + version record
   const opencodeDir = join(target, '.opencode')
   const total = await installSuite(opencodeDir, args.force)
-  await writeRecord(target, pkgVersion())
+  const record = await writeRecord(target, cliVersion)
+  if (!record.ok) {
+    console.error('Refusing to stamp the install record: the pinning contract is not complete.')
+    for (const err of record.errors) console.error(`  ${err}`)
+    return 1
+  }
   console.log(`installed ${total} file(s) and recorded the version`)
 
+  // 9. OpenSpec provisioning (final step). The spec-driven workflow is installed
+  //    last, after the suite and the version record, so a failure never leaves a
+  //    storefront that claims to be fully provisioned. A failure is surfaced as
+  //    a diagnostic; the storefront itself is still created.
+  const provisioned = await provisionOpenSpec(target)
+  if (provisioned.ok) {
+    console.log(`provisioned OpenSpec ${provisioned.version} (openspec init --tools opencode)`)
+  } else {
+    console.error(`Warning: OpenSpec provisioning failed — ${provisioned.error}`)
+    console.error('  The storefront was created but is NOT fully provisioned: the spec-driven')
+    console.error('  workflow is missing. Re-run `npx @thorprovider/storefront update` once fixed.')
+  }
+
   console.log('')
   console.log('Done. Next steps:')
   console.log(`  cd ${relative(process.cwd(), target) || '.'}`)
   console.log('  yarn dev')
-  console.log('Then use /sf-add-view, /sf-view, /sf-theme to extend the store.')
+  console.log('Then open the project in OpenCode and ask in natural language — the router in AGENTS.md points to the right skill.')
+  return 0
+}
+
+// Connect (or re-point) a real Medusa backend for an existing storefront. `create`
+// leaves a store running in mock mode; `setup` is the single, re-runnable step that
+// writes the real-mode environment. The developer supplies the publishable key, the
+// sales channel id (from the Medusa admin), and the region; `setup` derives only the
+// region's currency by reading the store API with the key.
+async function setup(args) {
+  const target = args.dir
+  const envPath = join(target, '.env.local')
+  const tty = Boolean(process.stdout.isTTY)
+
+  let backendUrl = args.backendUrl ?? null
+  let publishableKey = args.publishableKey ?? null
+  let salesChannelId = args.salesChannelId ?? null
+  let regionId = args.regionId ?? null
+
+  if (tty) {
+    intro('storefront setup')
+    if (!backendUrl) {
+      const value = await text({ message: 'Medusa backend URL:', initialValue: DEFAULT_BACKEND_URL })
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      backendUrl = value
+    }
+    if (!publishableKey) {
+      const value = await text({ message: 'Publishable API key (blank to stay in mock mode):', defaultValue: '' })
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      publishableKey = value || null
+    }
+    if (publishableKey && !salesChannelId) {
+      const value = await text({
+        message: 'Sales channel ID (Medusa admin → Settings → Sales Channels):',
+        defaultValue: '',
+      })
+      if (isCancel(value)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      salesChannelId = value || null
+    }
+    outro('Connecting…')
+  }
+  backendUrl = (backendUrl ?? DEFAULT_BACKEND_URL).replace(/\/+$/, '')
+
+  // No publishable key: nothing to connect. Leave the store in mock mode and exit
+  // successfully so `setup` is safe to run in CI/bootstrap without a key.
+  if (!publishableKey) {
+    console.log('storefront setup: no publishable key — leaving THOR_DATA_SOURCE=mock.')
+    return 0
+  }
+
+  // The sales channel is a developer-supplied input, never derived: the store API
+  // cannot report it without a StorefrontConfig row existing for the channel, and the
+  // runtime requires MEDUSA_SALES_CHANNEL_ID in real mode.
+  if (!salesChannelId) {
+    if (!tty) {
+      console.error('storefront setup: --sales-channel-id is required without a terminal.')
+    } else {
+      console.error('storefront setup: a sales channel id is required to connect a backend.')
+    }
+    console.error('Find it in the Medusa admin (Settings → Sales Channels).')
+    return 1
+  }
+
+  // Resolve the region and its currency.
+  let regions
+  try {
+    const res = await fetch(`${backendUrl}/store/regions`, {
+      headers: { 'x-publishable-api-key': publishableKey },
+    })
+    if (!res.ok) {
+      console.error(`storefront setup: GET ${backendUrl}/store/regions failed (${res.status}).`)
+      console.error('Leaving the store in mock mode; no files were changed.')
+      return 1
+    }
+    const body = await res.json()
+    regions = Array.isArray(body?.regions) ? body.regions : []
+  } catch (err) {
+    console.error(`storefront setup: could not reach ${backendUrl} (${err instanceof Error ? err.message : String(err)}).`)
+    console.error('Leaving the store in mock mode; no files were changed.')
+    return 1
+  }
+
+  if (regions.length === 0) {
+    console.error('storefront setup: the backend returned no regions.')
+    console.error('Leaving the store in mock mode; no files were changed.')
+    return 1
+  }
+
+  if (!regionId) {
+    if (!tty) {
+      console.error('storefront setup: --region-id is required without a terminal.')
+      console.error(`Available regions: ${regions.map((region) => region.id).join(', ')}`)
+      return 1
+    }
+    const value = await select({
+      message: 'Region:',
+      options: regions.map((region) => ({
+        value: region.id,
+        label: `${region.name ?? region.id} — ${region.currency_code ?? '?'}`,
+      })),
+    })
+    if (isCancel(value)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    regionId = value
+  }
+
+  const region = regions.find((candidate) => candidate.id === regionId)
+  if (!region) {
+    console.error(`storefront setup: region "${regionId}" not found on the backend.`)
+    console.error(`Available regions: ${regions.map((candidate) => candidate.id).join(', ')}`)
+    return 1
+  }
+  const currencyCode = region.currency_code
+  if (!currencyCode) {
+    console.error(`storefront setup: region "${regionId}" has no currency_code.`)
+    return 1
+  }
+
+  // Upsert only the keys setup manages; preserve everything else (the session
+  // secret, the site URL, the store identity, and any user additions).
+  const managed = {
+    THOR_DATA_SOURCE: 'medusa',
+    MEDUSA_BASE_URL: backendUrl,
+    MEDUSA_PUBLISHABLE_KEY: publishableKey,
+    MEDUSA_REGION_ID: regionId,
+    MEDUSA_SALES_CHANNEL_ID: salesChannelId,
+    MEDUSA_CURRENCY_CODE: currencyCode,
+  }
+  const next = upsertEnv(readEnvFile(envPath), managed)
+  await writeFile(envPath, next, 'utf8')
+
+  console.log('storefront setup — backend connected')
+  console.log(`  backend:        ${backendUrl}`)
+  console.log(`  sales channel:  ${salesChannelId}`)
+  console.log(`  region:         ${regionId}`)
+  console.log(`  currency:       ${currencyCode}`)
+  console.log('Wrote .env.local. Restart the dev server to pick it up.')
   return 0
 }
 
@@ -466,18 +1334,105 @@ async function update(args) {
     return 1
   }
 
-  const total = await installSuite(opencodeDir, args.force)
-  for (const rel of PRUNED_PATHS) await prunePath(opencodeDir, rel)
-  await writeRecord(target, pkgVersion())
+  // Gate the existing composition before any install/prune/stamp write.
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to update: ${error}`)
+    return 1
+  }
+  if (manifest) {
+    const preflight = preflightManifest(manifest)
+    if (!preflight.ok) return rejectComposition(preflight.errors)
+  }
+
+  // Validate every precomputable layer of the incoming pinning contract BEFORE
+  // any write (declared ranges, resolved versions, lockfile, toolchain/linker),
+  // so a bad range, a missing installed version, a CLI mismatch, a missing lock,
+  // or a wrong linker leaves the project intact. Assets are validated after the
+  // suite refresh at stamp time.
+  const version = pkgVersion()
+  const incoming = await validateIncomingContract(target, version)
+  if (!incoming.ok) {
+    console.error('Refusing to update: the incoming pinning contract is invalid.')
+    for (const err of incoming.errors) console.error(`  ${err}`)
+    return 1
+  }
+
+  // Read the previously recorded owned-file set BEFORE the refresh overwrites
+  // the record. It is the only honest basis for retirement: the difference
+  // between what the package shipped last time and what it ships now. A legacy
+  // record has no owned-file set, so `recordedAssets` is null and no file is
+  // retired from an undetermined set.
+  const previousRecord = await readRecord(opencodeDir)
+  const recordedAssets = recordedOwnedSet(previousRecord)
+  const isLegacyRecord = previousRecord !== null && recordedAssets === null
+
+  // Refresh the package-managed suite to the current artifact set, retire the
+  // recorded owned files the package no longer ships (only those that are
+  // verifiably unmodified), prune the fixed legacy paths, reconcile derived
+  // files, then stamp the record from what is actually installed. The managed
+  // suite is package-owned, so it is always refreshed; user-owned storefront
+  // files live outside it and are never touched here. A retirement candidate
+  // that was modified and any unknown file are preserved.
+  const total = await installSuite(opencodeDir, true)
+  const { retired, preserved } = recordedAssets
+    ? await retireObsoleteOwnedFiles(opencodeDir, recordedAssets)
+    : { retired: [], preserved: [] }
+  const prunedCommands = await pruneLegacySuitePaths(opencodeDir)
+  if (manifest) {
+    const result = await reconcile(target, manifest)
+    if (!result.ok) return rejectComposition(result.errors)
+  }
+  // Re-run OpenSpec provisioning so the storefront's OpenSpec commands, skills,
+  // and config track the pinned @fission-ai/openspec version. A failure is
+  // surfaced as a diagnostic; the storefront refresh itself still completes.
+  const provisioned = await provisionOpenSpec(target)
+  // Stamp only a complete, actually-verified record. A failed copy or an
+  // incoherent pin set is reported and never stamped as a clean version.
+  const record = await writeRecord(target, version)
+  if (!record.ok) {
+    console.error('Refusing to stamp the install record: the pinning contract is not complete.')
+    for (const err of record.errors) console.error(`  ${err}`)
+    return 1
+  }
+  const pinning = record.pinning
   await rm(join(opencodeDir, LEGACY_RECORD_FILE), { force: true })
 
+  const remainingSkills = await remainingNonSuiteSkills(opencodeDir)
+
   console.log(`Refreshed install in ${target}:`)
   console.log(`  installed ${total} file(s)`)
-  console.log('  pruned removed files (sf-init, sf-scaffold)')
-  console.log('  migrated version record to storefront.json')
-  console.log('Done. Available in OpenCode:')
-  console.log('  /sf-add-view  /sf-view  /sf-theme')
-  if (args.force) console.log('(used --force: existing files were overwritten)')
+  if (retired.length > 0) {
+    console.log(`  retired ${retired.length} obsolete owned file(s):`)
+    for (const rel of retired) console.log(`    ${rel}`)
+  }
+  if (prunedCommands.length > 0) {
+    console.log(`  pruned legacy suite paths: ${prunedCommands.join(', ')}`)
+  } else {
+    console.log('  pruned legacy suite paths (skills/sf-scaffold, sf-*.md commands) when present')
+  }
+  if (provisioned.ok) {
+    console.log(`  provisioned OpenSpec ${provisioned.version} (openspec init --tools opencode)`)
+  } else {
+    console.error(`  Warning: OpenSpec provisioning failed — ${provisioned.error}`)
+  }
+  console.log(`  recorded version ${version} (${Object.keys(pinning.assets).length} managed asset(s))`)
+  if (isLegacyRecord) {
+    console.log('  install record: legacy format carries no owned-file set —')
+    console.log('  retirement was limited to the fixed pruned paths; no undetermined file was removed.')
+  }
+  // A retirement candidate skipped because it was modified is named explicitly
+  // so the developer can act on it (it is never silently left behind).
+  for (const rel of preserved) {
+    console.log(`  skipped ${rel} — preserved because it was modified, not retired.`)
+  }
+  if (remainingSkills.length > 0) {
+    console.log(`Migration incomplete — ${remainingSkills.length} skill(s) outside the current suite remain:`)
+    for (const name of remainingSkills) console.log(`  skills/${name}`)
+    console.log('Resolve or remove them, then run "storefront update" again.')
+    return 0
+  }
+  console.log('Done. The skill suite is installed; see AGENTS.md for the workflow.')
   return 0
 }
 
@@ -489,25 +1444,1252 @@ async function doctor(args) {
     return 1
   }
 
+  let problems = 0
+
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.log(`  composition: invalid — ${error}`)
+    return 1
+  }
+  if (!manifest) {
+    console.log('  composition: no storefront.config.json found (run "storefront sync" to derive one)')
+  } else {
+    // Dry-run reconcile reports only derived files that diverge; user-owned
+    // files are never drift, so they are excluded by construction.
+    const drift = await reconcile(target, manifest, { dryRun: true })
+    if (!drift.ok) {
+      console.log('  composition: invalid — the manifest is not a supported composition:')
+      for (const err of drift.errors) console.log(`    ${err}`)
+      console.log('  status: fix storefront.config.json before running "storefront sync"')
+      return 1
+    }
+    if (drift.changed.length === 0) {
+      console.log('  composition: derived files match the manifest')
+    } else {
+      problems++
+      console.log(`  composition: ${drift.changed.length} derived file(s) drifted from the manifest:`)
+      for (const rel of drift.changed) console.log(`    ${rel}`)
+      console.log('  status: run "storefront sync" to reconcile')
+    }
+
+    // Data-bound section instances resolve their selection from a user-owned
+    // `sectionSources` entry. `sync` never patches user files, so a freshly
+    // added instance is unconfigured until the user supplies its entry; report
+    // each gap with the file and instance id so the repair is actionable.
+    const sectionConfig = auditSectionConfig({ dir: target, manifest, isDataBound: sectionIsDataBound })
+    if (sectionConfig.diagnostics.length > 0) {
+      problems++
+      console.log(`  section config: ${sectionConfig.diagnostics.length} data-bound section(s) need attention:`)
+      for (const diag of sectionConfig.diagnostics) console.log(`    ${diag.message}`)
+      console.log('  status: supply the missing source configuration, then run "storefront sync"')
+    }
+  }
+
   const opencodeDir = join(target, '.opencode')
   const record = await readRecord(opencodeDir)
   if (!record) {
-    console.log('No version record found in .opencode/.')
-    console.log('Run `storefront update` to install and record the suite.')
-    return 0
+    console.log('  suite: no version record found in .opencode/')
+    console.log('  status: run "storefront update" to install and record the suite')
+    return problems === 0 ? 0 : 1
   }
 
   const version = pkgVersion()
   console.log(`  recorded version: ${record.version} (installed ${record.installedAt})`)
   console.log(`  package version:  ${version}`)
 
-  const installedHash = await hashDir(opencodeDir)
-  const sourceHash = await hashDir(PKG_ROOT)
-  const match = installedHash === sourceHash
-  console.log(`  installed suite matches package: ${match ? 'yes' : 'no'}`)
-  if (!match) {
+  const packageAssets = await hashManagedSuite(PKG_ROOT)
+  console.log(`  distributed assets: ${Object.keys(packageAssets).length} file(s)`)
+
+  // Truthful version: a record that claims a version the installed artifacts
+  // do not match is a mismatch, not a clean stamp.
+  if (record.version !== version) {
+    problems++
+    console.log(`  version mismatch: record says "${record.version}" but the package is "${version}"`)
+  }
+
+  // Compare the record against the live project evidence, not against itself.
+  const collected = await collectLivePinning(target)
+  if (!collected.ok) {
+    problems++
+    console.log(`  pinning: cannot read the live project evidence — ${collected.error}`)
+  } else {
+    const tc = collected.live.toolchain
+    console.log(`  toolchain (observed): linker=${tc.linker} node=${tc.nodeVersion} yarn=${tc.yarnVersion}`)
+    const pinning = validatePinning(record.pinning, {
+      distributedVersion: version,
+      live: collected.live,
+    })
+    if (!pinning.ok) {
+      problems++
+      console.log('  pinning: the compatibility/pinning contract does not match the live project:')
+      for (const err of pinning.errors) console.log(`    ${err}`)
+    } else {
+      console.log('  pinning: declared ranges, resolved versions, lockfile, and asset digests agree')
+    }
+  }
+
+  const installedAssets = await installedSuiteBom(target)
+  const suiteMatches =
+    Object.keys(installedAssets).length === Object.keys(packageAssets).length &&
+    Object.entries(packageAssets).every(([rel, digest]) => installedAssets[rel] === digest)
+  console.log(`  installed suite matches package: ${suiteMatches ? 'yes' : 'no'}`)
+  if (!suiteMatches) {
+    problems++
     console.log('  status: update available — run "storefront update"')
   }
+
+  return problems === 0 ? 0 : 1
+}
+
+// Spawn a command inheriting stdio, for the isolated shadcn preset run.
+function runInherit(cmd, cmdArgs, cwd) {
+  const res = spawnSync(cmd, cmdArgs, { cwd, stdio: 'inherit', shell: false })
+  return res.status ?? 1
+}
+
+// The mode the project currently renders: manifest first (authoritative), then
+// the layout's ThemeProvider wiring, then the default.
+function detectLayoutMode(layout) {
+  const m = layout.match(/defaultTheme="([^"]+)"/)
+  return m && THEME_MODES.includes(m[1]) ? m[1] : null
+}
+
+// Best-effort declarative font export: recover the family slug from the
+// `--font-<slug>-<slot>` variable a `next/font/google` loader declares.
+function detectExportFonts(layout) {
+  const fonts = {}
+  for (const slot of ['sans', 'mono', 'serif']) {
+    const m = layout.match(new RegExp(`variable:\\s*'--font-([a-z0-9-]+)-${slot}'`))
+    if (m) fonts[slot] = { kind: 'google', value: m[1] }
+  }
+  return fonts
+}
+
+// Read-only inspection: current tokens, supported names, accepted formats.
+function themeInspect(args, { globals, currentMode }) {
+  const tokens = readThemeCss(globals)
+  if (args.json) {
+    printEnvelope({
+      success: true,
+      command: 'theme',
+      status: 'inspect',
+      mode: currentMode,
+      tokens: { light: tokens.light, dark: tokens.dark },
+      supportedTokens: THEME_COLOR_TOKENS.map((t) => `--${t}`),
+      colorNames: NAMED_COLOR_NAMES,
+      colorFormats: ['<name>', '#hex', 'oklch(...)'],
+      fontVars: FONT_VARS,
+    })
+    return 0
+  }
+  console.log(`Theme mode: ${currentMode}`)
+  console.log(`Color formats: ${NAMED_COLOR_NAMES.join(', ')}, #hex, oklch(...)`)
+  console.log(`Tokens: ${[...THEME_COLOR_ITEMS()].join(' ')}`)
+  console.log(`Fonts: ${FONT_VARS.join(' ')}`)
+  console.log('Fine-grained: --set light.primary=#f97316 (scopes: light, dark, shared)')
+  return 0
+}
+
+function THEME_COLOR_ITEMS() {
+  return THEME_COLOR_TOKENS.map((t) => `--${t}`)
+}
+
+function themeFail(args, diagnostics) {
+  if (args.json) {
+    printEnvelope({ success: false, command: 'theme', status: 'failed', changes: [], diagnostics })
+  } else {
+    for (const d of diagnostics) console.error(d.message)
+  }
+  return 1
+}
+
+function themeReport(args, { status, changes, diagnostics, values }) {
+  const diags = diagnostics ?? []
+  if (args.json) {
+    printEnvelope({ success: true, command: 'theme', status, changes, diagnostics: diags, values })
+    return 0
+  }
+  if (status === 'noop') {
+    console.log('Theme already up to date — no change.')
+  } else if (status === 'dry-run') {
+    console.log('Dry run — no files written. Planned changes:')
+    for (const c of changes) console.log(`  ${c}`)
+  } else {
+    for (const c of changes) console.log(`Updated ${c}`)
+  }
+  for (const d of diags) if (d.severity === 'warning') console.error(`warning: ${d.message}`)
+  return 0
+}
+
+// Write a portable theme snapshot. Read-only over the project: it never mutates
+// the storefront and refuses to clobber an existing file.
+async function themeExport(args, { globals, layout, currentMode }) {
+  const outPath = resolve(process.cwd(), args.exportPath)
+  if (existsSync(outPath)) {
+    return themeFail(args, [
+      envelopeDiagnostic('E_EXPORT_EXISTS', `Refusing to overwrite existing file: ${args.exportPath}`),
+    ])
+  }
+  const data = buildThemeExport({
+    tokens: readThemeCss(globals),
+    mode: currentMode,
+    fonts: detectExportFonts(layout),
+  })
+  await mkdir(dirname(outPath), { recursive: true })
+  await writeFile(outPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  if (args.json) {
+    printEnvelope({ success: true, command: 'theme', status: 'exported', changes: [args.exportPath] })
+    return 0
+  }
+  console.log(`Exported theme to ${args.exportPath}`)
+  return 0
+}
+
+// Resolve a `--import` source into a normalized importSource for planCss:
+// a local CSS export, a local JSON (registry:theme item or a prior storefront
+// export), or a remote registry:theme URL.
+async function resolveThemeImport(raw) {
+  const kind = classifyImportSource(raw)
+  try {
+    if (kind === 'css' || kind === 'json') {
+      const p = resolve(process.cwd(), raw)
+      if (!existsSync(p)) {
+        return { ok: false, diagnostics: [envelopeDiagnostic('E_IMPORT_PATH', `Import file not found: ${raw}`)] }
+      }
+      const text = readFileSync(p, 'utf8')
+      if (kind === 'json' || text.trimStart().startsWith('{')) {
+        const asExport = parseThemeExport(text)
+        if (asExport.ok) {
+          return {
+            ok: true,
+            importSource: { type: 'tokens', tokens: asExport.tokens },
+            fonts: asExport.fonts ?? {},
+            mode: asExport.mode ?? null,
+          }
+        }
+        let json
+        try {
+          json = JSON.parse(text)
+        } catch (err) {
+          return { ok: false, diagnostics: [envelopeDiagnostic('E_IMPORT_JSON', `Invalid JSON in ${raw}: ${err.message}`)] }
+        }
+        const asRegistry = parseRegistryTheme(json)
+        if (asRegistry.ok) {
+          return { ok: true, importSource: { type: 'tokens', tokens: asRegistry.tokens }, fonts: asRegistry.fonts ?? {} }
+        }
+        return { ok: false, diagnostics: asRegistry.diagnostics }
+      }
+      const parsed = parseCssExport(text)
+      if (!parsed.ok) return { ok: false, diagnostics: parsed.diagnostics }
+      return { ok: true, importSource: { type: 'css', css: text } }
+    }
+    if (kind === 'registry-url') {
+      const res = await fetch(raw)
+      if (!res.ok) {
+        return { ok: false, diagnostics: [envelopeDiagnostic('E_IMPORT_FETCH', `Failed to fetch ${raw}: HTTP ${res.status}`)] }
+      }
+      const parsed = parseRegistryTheme(await res.json())
+      if (!parsed.ok) return { ok: false, diagnostics: parsed.diagnostics }
+      return { ok: true, importSource: { type: 'tokens', tokens: parsed.tokens }, fonts: parsed.fonts ?? {} }
+    }
+    if (kind === 'preset-url') {
+      return {
+        ok: false,
+        diagnostics: [
+          envelopeDiagnostic('E_IMPORT_PRESET', `Use --preset for a builder/preset URL (got "${raw}")`),
+        ],
+      }
+    }
+  } catch (err) {
+    return { ok: false, diagnostics: [envelopeDiagnostic('E_IMPORT', `Failed to read import "${raw}": ${err.message}`)] }
+  }
+  return { ok: false, diagnostics: [envelopeDiagnostic('E_IMPORT', `Unsupported import source: ${raw}`)] }
+}
+
+// Complete theme control: mode + colors + radius + fonts + presets/imports +
+// inspect/export, all resolved into one validated, in-memory change plan over the
+// external files. Visual values live in app/globals.css; the mode stays in the
+// manifest. The whole operation is validated before any write, so a failure (or
+// --dry-run) leaves the project untouched.
+async function theme(args) {
+  const target = args.dir
+  if (!existsSync(target)) {
+    console.error(`Target directory does not exist: ${target}`)
+    return 1
+  }
+
+  const layoutPath = join(target, 'app', 'layout.tsx')
+  if (!existsSync(layoutPath)) {
+    console.error(`No app/layout.tsx found in ${target}`)
+    console.error('Run `storefront create <dir>` to scaffold the storefront first.')
+    return 1
+  }
+  const globalsPath = join(target, 'app', 'globals.css')
+  const globals = existsSync(globalsPath) ? readFileSync(globalsPath, 'utf8') : ''
+  const layout = readFileSync(layoutPath, 'utf8')
+
+  // Gate the existing composition before any write (same contract as the other
+  // scoped commands): never stamp an unsupported or invalid composition.
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to change theme: ${error}`)
+    return 1
+  }
+  if (manifest) {
+    const preflight = preflightManifest(manifest)
+    if (!preflight.ok) return rejectComposition(preflight.errors)
+  }
+
+  const currentMode = manifest?.theme?.mode ?? detectLayoutMode(layout) ?? DEFAULT_THEME_MODE
+  const mutationFlags = Boolean(
+    args.mode ||
+      args.brand ||
+      args.primary ||
+      args.accent ||
+      args.radius ||
+      args.fontSans ||
+      args.fontMono ||
+      args.fontSerif ||
+      (args.sets && args.sets.length) ||
+      args.preset ||
+      args.importSource,
+  )
+
+  // Inspect: explicit --inspect, or a bare `theme` invocation. Read-only.
+  if (args.inspect || (!mutationFlags && !args.exportPath)) {
+    return themeInspect(args, { globals, currentMode })
+  }
+
+  // Export: portable snapshot, never mutates the project.
+  if (args.exportPath) {
+    return themeExport(args, { globals, layout, currentMode })
+  }
+
+  // Resolve a local/remote import source. A versioned storefront export also
+  // carries its recorded mode and declarative font selection, restored unless
+  // the flags override them.
+  let importSource = null
+  let importFonts = {}
+  let importMode = null
+  if (args.importSource) {
+    const resolved = await resolveThemeImport(args.importSource)
+    if (!resolved.ok) return themeFail(args, resolved.diagnostics)
+    importSource = resolved.importSource
+    importFonts = resolved.fonts ?? {}
+    importMode = resolved.mode ?? null
+  }
+
+  // Resolve a shadcn preset through the pinned CLI in isolated staging.
+  let presetFonts = {}
+  if (args.preset) {
+    const only = args.only ?? 'theme,font'
+    const allowed = ['theme', 'font', 'theme,font']
+    if (!allowed.includes(only)) {
+      return themeFail(args, [
+        envelopeDiagnostic('E_ONLY', `--only must be one of ${allowed.join(', ')} (got "${only}")`),
+      ])
+    }
+    const runPreset = makeShadcnRunner({
+      shadcnVersion: CANDIDATE_TOOLSET.shadcn,
+      projectDir: target,
+      run: runInherit,
+    })
+    const resolved = await resolvePreset(args.preset, { projectDir: target, runPreset })
+    if (!resolved.ok) return themeFail(args, resolved.diagnostics)
+    importSource = { type: 'tokens', tokens: resolved.tokens }
+    presetFonts = resolved.fonts ?? {}
+  }
+
+  // Normalize explicit color setters to OKLCH so the stylesheet keeps one
+  // color space; non-color values (lengths, stacks) pass through untouched.
+  const normalizedSets = (args.sets ?? []).map((entry) => {
+    const parsed = parseSetter(entry)
+    if (parsed.error) return entry
+    const color = parseColor(parsed.value)
+    return color ? `${parsed.scope}.${parsed.name}=${formatOklch(color)}` : entry
+  })
+
+  const { operation, diagnostics } = normalizeOperation({
+    mode: args.mode ?? importMode,
+    brand: args.brand,
+    primary: args.primary,
+    accent: args.accent,
+    radius: args.radius,
+    fontSans: args.fontSans,
+    fontMono: args.fontMono,
+    fontSerif: args.fontSerif,
+    sets: normalizedSets,
+    preset: args.preset,
+    presetOnly: args.only,
+    importSource,
+    dryRun: args.dryRun,
+  })
+  if (diagnostics.some((d) => d.severity === 'error')) return themeFail(args, diagnostics)
+  for (const slot of ['sans', 'mono', 'serif']) {
+    if (!operation.fonts[slot] && importFonts[slot]) operation.fonts[slot] = importFonts[slot]
+    if (!operation.fonts[slot] && presetFonts[slot]) operation.fonts[slot] = presetFonts[slot]
+  }
+
+  const planned = planCss(globals, operation)
+  if (planned.diagnostics.some((d) => d.severity === 'error')) return themeFail(args, planned.diagnostics)
+
+  // Font wiring: layout loaders + the CSS variables that point at them. The
+  // `font-*` utilities read the `@theme inline` mapping, so update that block
+  // (falling back to `:root` when the stylesheet has no theme block).
+  const fontResult = applyLayoutFonts(layout, operation.fonts)
+  const fontVars = fontCssVars(operation.fonts, fontResult.loaderVars)
+  const fontEdits = Object.entries(fontVars).map(([name, value]) => ({ name, value }))
+  const nextGlobals = fontEdits.length
+    ? applyBlockDeclarations(planned.css, '@theme inline', fontEdits)
+    : planned.css
+
+  let nextLayout = fontResult.content
+  if (operation.mode) nextLayout = injectThemeMode(nextLayout, operation.mode)
+
+  const changes = []
+  if (nextGlobals !== globals) changes.push(relative(process.cwd(), globalsPath) || globalsPath)
+  if (nextLayout !== layout) changes.push(relative(process.cwd(), layoutPath) || layoutPath)
+  const modeChanged = Boolean(operation.mode) && operation.mode !== currentMode
+  if (modeChanged) changes.push('storefront.config.json#theme.mode')
+
+  if (args.dryRun) {
+    return themeReport(args, { status: 'dry-run', changes, diagnostics: planned.diagnostics, values: planned.values })
+  }
+  if (!changes.length) {
+    return themeReport(args, { status: 'noop', changes: [], diagnostics: planned.diagnostics, values: planned.values })
+  }
+
+  // Commit: manifest mode first (validated), then the external files, then
+  // reconcile so every derived file agrees with the manifest.
+  if (manifest && modeChanged) {
+    manifest.theme = { ...manifest.theme, mode: operation.mode }
+    const nextPreflight = preflightManifest(manifest)
+    if (!nextPreflight.ok) return rejectComposition(nextPreflight.errors)
+    await writeManifest(target, manifest)
+  }
+  if (nextGlobals !== globals) await writeFile(globalsPath, nextGlobals, 'utf8')
+  if (nextLayout !== layout) await writeFile(layoutPath, nextLayout, 'utf8')
+  if (manifest) {
+    const result = await reconcile(target, manifest)
+    if (!result.ok) return rejectComposition(result.errors)
+  }
+
+  return themeReport(args, { status: 'changed', changes, diagnostics: planned.diagnostics, values: planned.values })
+}
+
+async function sync(args) {
+  const target = args.dir
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to sync: ${error}`)
+    return 1
+  }
+  if (!manifest) {
+    // resolveProject already refuses legacy projects before sync runs; this is
+    // a defensive guard so no code path can derive or migrate one.
+    return rejectLegacyProject(target)
+  }
+
+  // Validate the complete desired composition before touching any derived file.
+  const preflight = preflightManifest(manifest)
+  if (!preflight.ok) return rejectComposition(preflight.errors)
+
+  const result = await reconcile(target, manifest)
+  if (!result.ok) return rejectComposition(result.errors)
+  if (result.changed.length === 0) {
+    console.log('No drift detected — the derived files match the manifest.')
+    return 0
+  }
+  console.log(`Repaired ${result.changed.length} derived file(s) drifted from the manifest:`)
+  for (const rel of result.changed) console.log(`  ${rel}`)
+  return 0
+}
+
+// Add or remove a view through the shared operation engine. `view add|remove`
+// is a thin alias over `view.add`/`view.remove`, so it produces the same
+// manifest, derived files, and diagnostics as planning and applying the
+// equivalent operation (E1 task 4.1 / Decision 17).
+async function view(args) {
+  const target = args.dir
+  const sub = args.positionals[1]
+  const name = args.positionals[2]
+
+  if (sub !== 'add' && sub !== 'remove') {
+    console.error('Usage: storefront view <add|remove> <name> [--intent slot=intent] [--variant slot=Variant]')
+    return 1
+  }
+  if (!name) {
+    console.error(`storefront view ${sub} requires a view name.`)
+    return 1
+  }
+
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to modify views: ${error}`)
+    return 1
+  }
+  if (!manifest) {
+    console.error(`No storefront.config.json found in ${target}. Run \`storefront sync\` first.`)
+    return 1
+  }
+
+  // Bounded legacy cleanup (change: storefront-retire-user-panel, AC-UP-1.2): a
+  // manifest written before a view was retired carries an entry the registry no
+  // longer knows, so the normal reduce path refuses the input. `view remove
+  // user-panel` is the single supported transition; every other unknown id
+  // still fails closed through the normal path below.
+  if (sub === 'remove' && isLegacyViewId(name)) {
+    const result = await removeLegacyView(target, name)
+    if (!result.ok) {
+      if (args.json) {
+        printEnvelope(resultEnvelope('view', false, 1, result.diagnostics))
+        return 1
+      }
+      return rejectDiagnostics(result.diagnostics)
+    }
+    if (args.json) {
+      printEnvelope(
+        resultEnvelope('view', true, 0, [], {
+          action: 'remove',
+          view: name,
+          changed: result.changed,
+          preserved: result.preserved,
+          alreadyRemoved: result.alreadyRemoved,
+        }),
+      )
+      return 0
+    }
+    if (result.alreadyRemoved) {
+      console.log(`View "${name}" is already absent; nothing to remove.`)
+      return 0
+    }
+    console.log(`Removed legacy view "${name}".`)
+    if (result.backup) console.log(`  backed up ${result.backup}`)
+    for (const leftover of result.preserved) {
+      console.log(`Preserved user-owned file: ${leftover} (remove it manually if no longer needed).`)
+    }
+    if (result.changed.length > 0) console.log(`  reconciled ${result.changed.length} derived file(s).`)
+    return 0
+  }
+
+  const present = manifest.views.some((v) => v.name === name)
+  const operations =
+    sub === 'add'
+      ? [{ op: 'view.add', view: name, intents: args.intents, variants: args.variants }]
+      : [{ op: 'view.remove', view: name }]
+  const result = await executeOperations(target, manifest, operations, { force: args.force })
+  if (!result.ok) {
+    // `--json` emits the shared versioned envelope (same diagnostics the
+    // plan/apply engine returns); the default human output is unchanged
+    // (E1 task 4.16 / Decision 17).
+    if (args.json) {
+      printEnvelope(resultEnvelope('view', false, 1, result.diagnostics))
+      return 1
+    }
+    return rejectDiagnostics(result.diagnostics)
+  }
+  if (args.json) {
+    printEnvelope(
+      resultEnvelope('view', true, 0, [], {
+        action: sub,
+        view: name,
+        changed: result.changed,
+        preserved: result.preserved,
+      }),
+    )
+    return 0
+  }
+
+  if (sub === 'add') {
+    console.log(`${present ? 'Re-added' : 'Added'} view "${name}".`)
+  } else {
+    console.log(`Removed view "${name}".`)
+    for (const leftover of result.preserved) {
+      console.log(`Preserved user-owned file: ${leftover} (remove it manually if no longer needed).`)
+    }
+    if (result.preserved.length > 0) {
+      console.log(`  ${result.preserved.length} user-owned file(s) left in place.`)
+    }
+  }
+  if (result.changed.length > 0) console.log(`  reconciled ${result.changed.length} derived file(s).`)
+  return 0
+}
+
+// Add or remove a feature (a capability bundle) through the shared operation
+// engine. `feature add|remove` is a thin alias over `feature.add`/`feature.remove`
+// and preserves every flag (`--config`, `--force`), so it produces the same
+// manifest, derived files, and diagnostics as the plan/apply equivalent
+// (E1 task 4.1 / Decision 17).
+async function feature(args) {
+  const target = args.dir
+  const sub = args.positionals[1]
+  const name = args.positionals[2]
+  if (sub !== 'add' && sub !== 'remove') {
+    console.error('Usage: storefront feature <add|remove> <name> [-f]')
+    return 1
+  }
+  if (!name) {
+    console.error(`storefront feature ${sub} requires a feature name.`)
+    return 1
+  }
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to modify features: ${error}`)
+    return 1
+  }
+  if (!manifest) {
+    console.error(`No storefront.config.json found in ${target}. Run \`storefront sync\` first.`)
+    return 1
+  }
+
+  const present = manifest.features.some((f) => f.name === name)
+  let operations
+  if (sub === 'add') {
+    let config
+    if (args.config !== null && args.config !== undefined) {
+      try {
+        config = JSON.parse(args.config)
+      } catch (err) {
+        console.error(
+          `--config expects a JSON object (${err instanceof Error ? err.message : String(err)}).`
+        )
+        return 1
+      }
+    }
+    operations = [
+      { op: 'feature.add', feature: name, ...(config === undefined ? {} : { config }) },
+    ]
+  } else {
+    operations = [{ op: 'feature.remove', feature: name }]
+  }
+  const result = await executeOperations(target, manifest, operations, { force: args.force })
+  if (!result.ok) {
+    // `--json` emits the shared versioned envelope (same diagnostics the
+    // plan/apply engine returns); the default human output is unchanged
+    // (E1 task 4.16 / Decision 17).
+    if (args.json) {
+      printEnvelope(resultEnvelope('feature', false, 1, result.diagnostics))
+      return 1
+    }
+    return rejectDiagnostics(result.diagnostics)
+  }
+  if (args.json) {
+    printEnvelope(
+      resultEnvelope('feature', true, 0, [], {
+        action: sub,
+        feature: name,
+        changed: result.changed,
+        preserved: result.preserved,
+      }),
+    )
+    return 0
+  }
+
+  if (sub === 'add') {
+    console.log(`${present ? 'Re-added' : 'Added'} feature "${name}".`)
+  } else {
+    console.log(`Removed feature "${name}".`)
+    for (const leftover of result.preserved) {
+      console.log(`Preserved customized file: ${leftover} (remove it manually if no longer needed).`)
+    }
+    if (result.preserved.length > 0) console.log(`  ${result.preserved.length} file(s) left in place.`)
+  }
+  if (result.changed.length > 0) console.log(`  reconciled ${result.changed.length} derived file(s).`)
+  return 0
+}
+
+// Collect the position anchors supplied on the command line. Exactly one may be
+// given: `--after`/`--before` name a sibling id, `--first`/`--last` target an
+// extreme, and `--at` is the raw 0-based index escape hatch (change:
+// storefront-section-cli-alias / design D3).
+function readSectionAnchor(args) {
+  const anchors = []
+  if (args.after != null) anchors.push({ kind: 'after', id: args.after })
+  if (args.before != null) anchors.push({ kind: 'before', id: args.before })
+  if (args.first) anchors.push({ kind: 'first' })
+  if (args.last) anchors.push({ kind: 'last' })
+  if (args.at != null) anchors.push({ kind: 'at', value: args.at })
+  return anchors
+}
+
+// The ordered entry ids of a view as the engine sees them: the view's declared
+// `sections` normalized through the single `section-compat.mjs` authority (which
+// turns an empty list into the registered core slots). Returns null when the view
+// cannot be normalized, so the caller defers to the reducer and its canonical
+// diagnostic instead of inventing one.
+function orderedSectionIds(manifest, view) {
+  const installed = (manifest.views ?? []).find((entry) => entry.name === view)
+  const normalized = normalizeViewSectionsForView(view, installed?.sections ?? [])
+  if (!normalized.ok) return null
+  return normalized.sections.map((entry) => entry.id)
+}
+
+// Translate an `add` anchor into the operation's 0-based `at`. An `--after`/
+// `--before` id that is absent fails closed with E_UNKNOWN_SECTION_REF before any
+// write; a view that cannot be normalized defers to the reducer (design D5).
+function resolveAddAnchor(manifest, view, anchor) {
+  if (!anchor) return {}
+  if (anchor.kind === 'at') {
+    const value = Number(anchor.value)
+    if (!Number.isInteger(value) || value < 0) {
+      return {
+        error: {
+          code: 'E_INVALID_OPERATION',
+          message: `--at expects a non-negative integer (got "${anchor.value}").`,
+        },
+      }
+    }
+    return { value }
+  }
+  const ids = orderedSectionIds(manifest, view)
+  if (ids === null) return {}
+  if (anchor.kind === 'first') return { value: 0 }
+  if (anchor.kind === 'last') return { value: ids.length }
+  const index = ids.indexOf(anchor.id)
+  if (index === -1) {
+    return {
+      error: {
+        code: 'E_UNKNOWN_SECTION_REF',
+        message: `--${anchor.kind} names section "${anchor.id}" which is not present in view "${view}".`,
+      },
+    }
+  }
+  return { value: anchor.kind === 'after' ? index + 1 : index }
+}
+
+// Build the full entry order for a `move`: drop the target from the normalized
+// list, resolve the destination against that reduced list, then reinsert. Unknown
+// target -> E_UNKNOWN_ORDER_REF (the same code a direct `section.reorder` emits);
+// unknown sibling anchor -> E_UNKNOWN_SECTION_REF; an unnormalizable view defers
+// to the reducer (change: storefront-section-cli-alias / design D4/D5).
+function buildMoveOrder(manifest, view, id, anchor) {
+  const ids = orderedSectionIds(manifest, view)
+  if (ids === null) return { order: [] }
+  if (!ids.includes(id)) {
+    return {
+      error: {
+        code: 'E_UNKNOWN_ORDER_REF',
+        message: `section.reorder names id "${id}" which is not present in view "${view}".`,
+      },
+    }
+  }
+  const reduced = ids.filter((entryId) => entryId !== id)
+  let index
+  if (anchor.kind === 'at') {
+    index = Number(anchor.value)
+    if (!Number.isInteger(index) || index < 0 || index > reduced.length) {
+      return {
+        error: {
+          code: 'E_INVALID_OPERATION',
+          message: `--at must be an integer between 0 and ${reduced.length}.`,
+        },
+      }
+    }
+  } else if (anchor.kind === 'first') {
+    index = 0
+  } else if (anchor.kind === 'last') {
+    index = reduced.length
+  } else {
+    const sibling = reduced.indexOf(anchor.id)
+    if (sibling === -1) {
+      return {
+        error: {
+          code: 'E_UNKNOWN_SECTION_REF',
+          message: `--${anchor.kind} names section "${anchor.id}" which is not present in view "${view}".`,
+        },
+      }
+    }
+    index = anchor.kind === 'after' ? sibling + 1 : sibling
+  }
+  return { order: [...reduced.slice(0, index), id, ...reduced.slice(index)] }
+}
+
+// Add, remove, or move a section instance through the shared operation engine.
+// `section add|remove|move` is a thin alias over `section.add`/`section.remove`/
+// `section.reorder`, threading SECTION_OPERATION_REGISTRY so the section ops are
+// recognized; it produces the same manifest, derived files, and diagnostics as
+// planning and applying the equivalent operations (change:
+// storefront-section-cli-alias / CU-17).
+async function section(args) {
+  const target = args.dir
+  const sub = args.positionals[1]
+  const view = args.positionals[2]
+  if (sub !== 'add' && sub !== 'remove' && sub !== 'move') {
+    console.error('Usage: storefront section <add|remove|move> <view> [...]')
+    return 1
+  }
+  if (!view) {
+    console.error(`storefront section ${sub} requires a view name.`)
+    return 1
+  }
+
+  const anchors = readSectionAnchor(args)
+  if (anchors.length > 1) {
+    console.error(
+      'Only one position anchor may be given: --after, --before, --first, --last, --at.'
+    )
+    return 1
+  }
+  const anchor = anchors[0] ?? null
+
+  const { manifest, error } = readManifestOrError(target)
+  if (error) {
+    console.error(`Refusing to modify sections: ${error}`)
+    return 1
+  }
+  if (!manifest) {
+    console.error(`No storefront.config.json found in ${target}. Run \`storefront sync\` first.`)
+    return 1
+  }
+
+  // A section edit is deterministic; a usage/validation error is reported the
+  // same way whether or not `--json` is set (the shared versioned envelope).
+  const failWith = (code, message) => {
+    const diagnostics = [envelopeDiagnostic(code, message)]
+    if (args.json) {
+      printEnvelope(resultEnvelope('section', false, 1, diagnostics))
+      return 1
+    }
+    return rejectDiagnostics(diagnostics)
+  }
+
+  let operations
+  if (sub === 'add') {
+    const type = args.positionals[3]
+    if (!type) return failWith('E_INVALID_OPERATION', 'storefront section add requires a section type.')
+    const op = { op: 'section.add', view, type }
+    if (args.id != null) op.id = args.id
+    if (args.as != null) op.variant = args.as
+    const placement = resolveAddAnchor(manifest, view, anchor)
+    if (placement.error) return failWith(placement.error.code, placement.error.message)
+    if (placement.value != null) op.at = placement.value
+    operations = [op]
+  } else if (sub === 'remove') {
+    const id = args.positionals[3]
+    if (!id) return failWith('E_INVALID_OPERATION', 'storefront section remove requires a section id.')
+    if (anchor) {
+      return failWith('E_INVALID_OPERATION', 'storefront section remove does not take a position anchor.')
+    }
+    if (args.id != null) {
+      return failWith('E_INVALID_OPERATION', 'storefront section remove takes the id positionally, not via --id.')
+    }
+    operations = [{ op: 'section.remove', view, id }]
+  } else {
+    const id = args.positionals[3]
+    if (!id) return failWith('E_INVALID_OPERATION', 'storefront section move requires a section id.')
+    if (!anchor) {
+      return failWith(
+        'E_INVALID_OPERATION',
+        'storefront section move requires a destination (--after, --before, --first, --last, --at).'
+      )
+    }
+    const built = buildMoveOrder(manifest, view, id, anchor)
+    if (built.error) return failWith(built.error.code, built.error.message)
+    operations = [{ op: 'section.reorder', view, order: built.order }]
+  }
+
+  const result = await executeOperations(target, manifest, operations, {
+    force: args.force,
+    registry: SECTION_OPERATION_REGISTRY,
+  })
+  if (!result.ok) {
+    if (args.json) {
+      printEnvelope(resultEnvelope('section', false, 1, result.diagnostics))
+      return 1
+    }
+    return rejectDiagnostics(result.diagnostics)
+  }
+  if (args.json) {
+    printEnvelope(
+      resultEnvelope('section', true, 0, [], {
+        action: sub,
+        view,
+        changed: result.changed,
+        preserved: result.preserved,
+      }),
+    )
+    return 0
+  }
+
+  if (sub === 'add') {
+    console.log(`Added a "${args.positionals[3]}" section to view "${view}".`)
+  } else if (sub === 'remove') {
+    console.log(`Removed section "${args.positionals[3]}" from view "${view}".`)
+    for (const leftover of result.preserved) {
+      console.log(`Preserved user-owned file: ${leftover} (remove it manually if no longer needed).`)
+    }
+  } else {
+    console.log(`Moved section "${args.positionals[3]}" in view "${view}".`)
+  }
+  if (result.changed.length > 0) console.log(`  reconciled ${result.changed.length} derived file(s).`)
+  return 0
+}
+
+// List the section instances of installed views, in order, as the engine sees
+// them (the declared list normalized through section-compat). Read-only and
+// deterministic — it writes no file (change: storefront-section-cli-alias /
+// task 3.1). `--json` mirrors the `views` envelope shape.
+async function sections(args) {
+  const target = args.dir
+  const manifest = await readManifest(target)
+  const installed = manifest?.views ?? []
+  const requested = args.positionals[1] ?? null
+  if (requested && !installed.some((view) => view.name === requested)) {
+    console.error(`View "${requested}" is not installed in ${target}.`)
+    return 1
+  }
+  const selected = requested ? installed.filter((view) => view.name === requested) : installed
+
+  const entries = selected.map((view) => {
+    const normalized = normalizeViewSectionsForView(view.name, view.sections ?? [])
+    const list = normalized.ok ? normalized.sections : []
+    return {
+      name: view.name,
+      installed: true,
+      sections: list.map((entry) => ({
+        id: entry.id,
+        type: entry.type,
+        variant: entry.variant ?? null,
+      })),
+    }
+  })
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { catalogVersion: CATALOG_VERSION, sectionTypes: sectionRegistry(), views: entries },
+        null,
+        2,
+      ),
+    )
+    return 0
+  }
+
+  console.log(`Storefront sections (${target}):`)
+  for (const entry of entries) {
+    console.log(`  ${entry.name}`)
+    for (const instance of entry.sections) {
+      const variant = instance.variant ? ` (${instance.variant})` : ''
+      console.log(`    ${instance.id.padEnd(24)} ${instance.type}${variant}`)
+    }
+  }
+  return 0
+}
+
+// Build a diagnostic for the result/error envelope. `path`, when present, is a
+// project-root-relative POSIX file path; operation-field diagnostics use a
+// semantic locator instead (e.g. `operations[0].surprise`), never a filesystem
+// path (E1 task 4.11).
+function envelopeDiagnostic(code, message, extra = {}) {
+  return { code, severity: 'error', message, ...extra }
+}
+
+// Print a versioned result/error envelope. Errors are always emitted as the
+// envelope so a machine caller can read the stable code and exit behavior.
+function printEnvelope(envelope) {
+  console.log(JSON.stringify(envelope, null, 2))
+}
+
+// Read-only, deterministic report of the versioned catalog and the current
+// composition. Writes nothing (E1 task 4.1 foundation; tasks 4.2/4.11 harden
+// the catalog/capability surface and the result envelope).
+function inspect(args) {
+  const target = args.dir
+  let manifest = null
+  if (hasManifest(target)) {
+    const read = readManifestOrError(target)
+    if (read.error) {
+      printEnvelope(
+        resultEnvelope('inspect', false, 1, [
+          envelopeDiagnostic('E_INVALID_COMPOSITION', read.error, {
+            path: 'storefront.config.json',
+          }),
+        ]),
+      )
+      return 1
+    }
+    manifest = read.manifest
+  }
+  const catalog = loadCatalog()
+  const result = {
+    catalogVersion: CATALOG_VERSION,
+    slots: catalog.slots ?? {},
+    capabilities: catalog.capabilities ?? {},
+    composition: {
+      views: manifest?.views ?? [],
+      features: manifest?.features ?? [],
+    },
+    dataBoundSections: collectDataBoundInstances(manifest, sectionIsDataBound),
+  }
+  const envelope = resultEnvelope('inspect', true, 0, [], result)
+  if (args.json) {
+    printEnvelope(envelope)
+    return 0
+  }
+  console.log(`Storefront inspect (${target}):`)
+  console.log(`  catalog version: ${result.catalogVersion}`)
+  console.log(`  slots:           ${Object.keys(result.slots).length}`)
+  console.log(`  views:           ${result.composition.views.map((v) => v.name).join(', ') || '(none)'}`)
+  console.log(`  features:        ${result.composition.features.map((f) => f.name).join(', ') || '(none)'}`)
+  console.log(
+    `  data-bound:      ${result.dataBoundSections.map((s) => `${s.id} (${s.type})`).join(', ') || '(none)'}`,
+  )
+  return 0
+}
+
+// Plan a whole intended state from an operations envelope. Validates every
+// operation against the resulting complete state and reports all errors; on any
+// failure it emits no plan and writes nothing. Without `--out` this is fully
+// read-only and always prints the JSON envelope; with `--out` it writes only the
+// plan artifact and prints a human summary unless `--json` is given
+// (E1 tasks 4.1 and 4.3; task 4.4 hardens identity).
+async function plan(args) {
+  if (!args.operations) {
+    printEnvelope(
+      resultEnvelope('plan', false, 1, [
+        envelopeDiagnostic(
+          'E_INVALID_ENVELOPE',
+          'Usage: storefront plan --operations <file> [--out <file>] [--json]',
+        ),
+      ]),
+    )
+    return 1
+  }
+  // `--operations` resolves against the consumer cwd, not the project root
+  // (Decision 12 / E1 task 4.11); the project root is found upward separately.
+  const operationsPath = resolve(args.operations)
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(operationsPath, 'utf8'))
+  } catch (err) {
+    printEnvelope(
+      resultEnvelope('plan', false, 1, [
+        envelopeDiagnostic(
+          'E_INVALID_ENVELOPE',
+          `Cannot read operations envelope file ${operationsPath}: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      ]),
+    )
+    return 1
+  }
+  const { envelope, exitCode } = await planProject(args.dir, raw, {
+    outPath: args.out ? resolve(args.out) : null,
+    operationsPath,
+    registry: SECTION_OPERATION_REGISTRY,
+  })
+  if (args.json || !args.out || exitCode !== 0) {
+    printEnvelope(envelope)
+  } else {
+    console.log('storefront plan — valid')
+    console.log(`  before: ${envelope.result.beforeFingerprint}`)
+    console.log(`  after:  ${envelope.result.afterFingerprint}`)
+    console.log(`  wrote plan artifact: ${resolve(args.out)}`)
+  }
+  return exitCode
+}
+
+// Apply a recorded plan (E1 task 4.1 foundation; tasks 4.5-4.19 harden the
+// three-state resolution, lock, and rollback branches).
+async function apply(args) {
+  if (!args.plan) {
+    printEnvelope(
+      resultEnvelope('apply', false, 1, [
+        envelopeDiagnostic('E_PLAN_NOT_FOUND', 'Usage: storefront apply --plan <file> [--json]'),
+      ]),
+    )
+    return 1
+  }
+  // `--plan` resolves against the consumer cwd, not the project root
+  // (Decision 12 / E1 task 4.11).
+  const planPath = resolve(args.plan)
+  let artifact
+  try {
+    artifact = JSON.parse(readFileSync(planPath, 'utf8'))
+  } catch (err) {
+    const code = err?.code === 'ENOENT' ? 'E_PLAN_NOT_FOUND' : 'E_PLAN_INVALID'
+    printEnvelope(
+      resultEnvelope('apply', false, 1, [
+        envelopeDiagnostic(
+          code,
+          `Cannot read plan file ${planPath}: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      ]),
+    )
+    return 1
+  }
+  const { envelope, exitCode } = await applyProject(args.dir, artifact, {
+    registry: SECTION_OPERATION_REGISTRY,
+  })
+  if (args.json || exitCode !== 0) {
+    printEnvelope(envelope)
+  } else {
+    console.log(`storefront apply — ${envelope.result?.state ?? 'ok'}`)
+  }
+  return exitCode
+}
+
+// List the view registry — the recipes and intents the CLI validates against —
+// annotated with whether each view is installed in the current storefront.
+async function views(args) {
+  const target = args.dir
+  const manifest = await readManifest(target)
+  const installed = new Set((manifest?.views ?? []).map((v) => v.name))
+  const { views: recipes } = loadRecipes()
+  const { slots } = loadArchetypes()
+
+  const entries = recipes.map((recipe) => {
+    const intents = {}
+    for (const [key, value] of Object.entries(slots ?? {})) {
+      if (!key.startsWith(`${recipe.name}.`)) continue
+      intents[key.slice(recipe.name.length + 1)] = value
+    }
+    return {
+      name: recipe.name,
+      description: recipe.description,
+      route: recipe.route,
+      loader: recipe.loader,
+      requiredDataKeys: recipe.requiredDataKeys ?? [],
+      installed: installed.has(recipe.name),
+      supported: isCuratedView(recipe.name),
+      defaultVariants: recipe.defaultVariants ?? {},
+      // Allowed/supported are derived from the single semantic catalog; a held
+      // variant is reported (with its reason) under `catalog` and never listed
+      // as selectable here.
+      allowedVariants: allowedVariantsForView(recipe.name),
+      supportedVariants: supportedVariantsForView(recipe.name),
+      supportedIntents: supportedIntents(recipe.name),
+      catalog: viewCatalog(recipe.name),
+      optionalSections: recipe.optionalSections ?? [],
+      // E3 section registry (CU-14/CU-16): the ordered, non-removable core
+      // presentation slots, the host allowlist, and the editorial-instance
+      // technical bound. Reported so an agent sees the available hosts without
+      // reading the JSON registry.
+      registeredSlots: recipe.registeredSlots ?? [],
+      allowedSections: recipe.allowedSections ?? [],
+      maxSections: recipe.maxSections ?? 4,
+      intents,
+    }
+  })
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { catalogVersion: CATALOG_VERSION, sectionTypes: sectionRegistry(), views: entries },
+        null,
+        2,
+      ),
+    )
+    return 0
+  }
+
+  console.log(`Storefront views (${target}):`)
+  for (const entry of entries) {
+    const status = entry.installed ? 'installed' : entry.supported ? 'available' : 'held'
+    console.log(`  ${entry.name.padEnd(12)} ${status.padEnd(10)} ${entry.route}`)
+  }
+  return 0
+}
+
+// List the feature registry — the capability bundles the CLI validates against —
+// annotated with whether each feature is installed in the current storefront.
+// Held (non-MVP) features are reported as held, never as available.
+async function features(args) {
+  const target = args.dir
+  const manifest = await readManifest(target)
+  const installed = new Set((manifest?.features ?? []).map((f) => f.name))
+  const { features: specs } = loadFeatures()
+
+  const entries = specs.map((spec) => ({
+    name: spec.name,
+    description: spec.description,
+    mvp: spec.mvp === true,
+    installed: installed.has(spec.name),
+    route: spec.route ?? null,
+    views: spec.views ?? [],
+    state: spec.state ?? [],
+    handlers: spec.handlers ?? [],
+    adapter: spec.adapter ?? null,
+    config: spec.config ?? null,
+    presentations: spec.presentations ?? {},
+    mounts: spec.mounts ?? [],
+    surfaces: featureSurfaces(spec),
+  }))
+
+  if (args.json) {
+    console.log(JSON.stringify({ features: entries }, null, 2))
+    return 0
+  }
+
+  console.log(`Storefront features (${target}):`)
+  for (const entry of entries) {
+    const status = entry.installed ? 'installed' : entry.mvp ? 'available' : 'held'
+    const owned = entry.views.join(', ') || '—'
+    console.log(`  ${entry.name.padEnd(16)} ${status.padEnd(10)} ${owned}`)
+  }
+  return 0
+}
+
+// Print the whole curated registry — views and features — deterministically, so
+// agents can introspect what the CLI will accept without reading the JSON files.
+async function recipes(args) {
+  const { views: viewRecipes } = loadRecipes()
+  const { features: featureSpecs } = loadFeatures()
+
+  const views = viewRecipes.map((recipe) => {
+    return {
+      name: recipe.name,
+      description: recipe.description,
+      route: recipe.route,
+      loader: recipe.loader,
+      mvp: recipe.mvp === true,
+      defaultVariants: recipe.defaultVariants ?? {},
+      // Derived from the single semantic catalog: selectable variants only,
+      // with held variants visible (and reasoned) under `catalog`.
+      allowedVariants: allowedVariantsForView(recipe.name),
+      supportedVariants: supportedVariantsForView(recipe.name),
+      supportedIntents: supportedIntents(recipe.name),
+      catalog: viewCatalog(recipe.name),
+      optionalSections: recipe.optionalSections ?? [],
+      // E3 section registry (CU-14/CU-16): core slots, host allowlist, and the
+      // editorial-instance technical bound, per view.
+      registeredSlots: recipe.registeredSlots ?? [],
+      allowedSections: recipe.allowedSections ?? [],
+      maxSections: recipe.maxSections ?? 4,
+    }
+  })
+  const features = featureSpecs.map((spec) => ({
+    name: spec.name,
+    description: spec.description,
+    mvp: spec.mvp === true,
+    route: spec.route ?? null,
+    views: spec.views ?? [],
+    state: spec.state ?? [],
+    handlers: spec.handlers ?? [],
+    adapter: spec.adapter ?? null,
+    config: spec.config ?? null,
+    presentations: spec.presentations ?? {},
+    mounts: spec.mounts ?? [],
+    surfaces: featureSurfaces(spec),
+  }))
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        {
+          catalogVersion: CATALOG_VERSION,
+          sectionTypes: sectionRegistry(),
+          recipes: { views, features },
+        },
+        null,
+        2,
+      ),
+    )
+    return 0
+  }
+
+  console.log('Storefront recipes:')
+  console.log(`  views    ${views.map((v) => v.name).join(', ')}`)
+  console.log(`  features ${features.map((f) => f.name).join(', ')}`)
   return 0
 }
 
@@ -519,13 +2701,107 @@ async function main() {
     return 0
   }
   if (args.action === 'create') return create(args)
-  if (args.action === 'update') return update(args)
-  if (args.action === 'doctor') return doctor(args)
+  if (args.action === 'view') {
+    const root = resolveProject()
+    if (!root) return 1
+    return view({ ...args, dir: root })
+  }
+  if (args.action === 'views') {
+    const root = resolveProject()
+    if (!root) return 1
+    return views({ ...args, dir: root })
+  }
+  if (args.action === 'features') {
+    const root = resolveProject()
+    if (!root) return 1
+    return features({ ...args, dir: root })
+  }
+  if (args.action === 'recipes') {
+    const root = resolveProject()
+    if (!root) return 1
+    return recipes({ ...args, dir: root })
+  }
+  if (args.action === 'feature') {
+    const root = resolveProject()
+    if (!root) return 1
+    return feature({ ...args, dir: root })
+  }
+  if (args.action === 'section') {
+    const root = resolveProject()
+    if (!root) return 1
+    return section({ ...args, dir: root })
+  }
+  if (args.action === 'sections') {
+    const root = resolveProject()
+    if (!root) return 1
+    return sections({ ...args, dir: root })
+  }
+  if (args.action === 'inspect' || args.action === 'plan' || args.action === 'apply') {
+    const root = resolveProject({ quiet: true })
+    if (!root) {
+      // Every inspect/plan/apply invocation emits a versioned error envelope,
+      // including "not inside a project" (E1 task 4.11).
+      printEnvelope(
+        resultEnvelope(args.action, false, 1, [
+          envelopeDiagnostic(
+            'E_NO_MANIFEST',
+            'Not inside a storefront project (no storefront.config.json found in this directory or any parent).',
+          ),
+        ]),
+      )
+      return 1
+    }
+    if (args.action === 'inspect') return inspect({ ...args, dir: root })
+    if (args.action === 'plan') return plan({ ...args, dir: root })
+    return apply({ ...args, dir: root })
+  }
+
+  const SCOPED = ['theme', 'update', 'doctor', 'sync', 'setup']
+  if (SCOPED.includes(args.action)) {
+    if (args.positionals.length > 1) {
+      console.error(`storefront ${args.action} does not take a directory; run it from inside the storefront project.`)
+      return 1
+    }
+    const root = resolveProject()
+    if (!root) return 1
+    const scoped = { ...args, dir: root }
+    if (args.action === 'theme') return theme(scoped)
+    if (args.action === 'update') return update(scoped)
+    if (args.action === 'sync') return sync(scoped)
+    if (args.action === 'setup') return setup(scoped)
+    return doctor(scoped)
+  }
+
   console.error(`Unknown action: ${args.action}`)
   console.log(HELP)
   return 1
 }
 
-main().then((code) => {
-  process.exitCode = code
-})
+main()
+  .then((code) => {
+    process.exitCode = code
+  })
+  .catch((error) => {
+    // An unexpected throw that escaped a handler is an internal error: emit a
+    // sanitized versioned error envelope and exit 2. No stack, absolute path,
+    // or captured value is printed to stdout; the error name/message is logged
+    // (not swallowed) so the failure is still diagnosable.
+    const command = process.argv[2] ?? 'unknown'
+    const name = error instanceof Error ? error.name : 'Error'
+    const rawMessage = error instanceof Error ? error.message : String(error)
+    // Redact the consumer cwd and the OS temp root so the log cannot leak an
+    // absolute machine path.
+    const message = rawMessage.split(process.cwd()).join('<cwd>').split(tmpdir()).join('<tmp>')
+    console.error(`storefront ${command}: unexpected internal error (${name}): ${message}`)
+    printEnvelope(
+      resultEnvelope(command, false, 2, [
+        {
+          code: 'E_UNEXPECTED',
+          severity: 'error',
+          message: 'unexpected internal error',
+          detail: { name },
+        },
+      ]),
+    )
+    process.exitCode = 2
+  })