@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/bin/storefront.js

@@ -8,21 +8,72 @@
 //   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.
+// 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 { randomBytes } from 'node:crypto'
+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 { renderScaffold, toKebab, toTitle, injectThemeMode } from '../scripts/render-templates.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 {
+  buildInstallPlan,
+  CANDIDATE_TOOLSET,
+  findPack,
+  parseRuntimeCommerceImports,
+  verifyPackExports,
+  verifyPackManifest,
+} from '../scripts/candidate.mjs'
+import {
+  hashManagedSuite,
+  hashPaths,
+  managedSuitePaths,
+  readDirectDependencies,
+  readResolvedVersions,
+  readLockfile,
+  readToolchainEvidence,
+  buildPinningRecord,
+  validateDeclaredContract,
+  validatePinning,
+} from '../scripts/pinning.mjs'
+import {
+  loadRecipes,
+  loadArchetypes,
+  loadFeatures,
+  isCuratedView,
+  featureSurfaces,
+  allowedVariantsForView,
+  supportedVariantsForView,
+  supportedIntents,
+  viewCatalog,
+  sectionRegistry,
+} from '../recipes/validate.mjs'
+import { CATALOG_VERSION, loadCatalog } from '../recipes/catalog.mjs'
+import { OPERATION_NAMES } from '../scripts/operations.mjs'
+import { applyProject, executeOperations, planProject, resultEnvelope } from '../scripts/plan-apply.mjs'
+import { SECTION_OPERATION_REGISTRY } from '../scripts/section-operations.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = resolve(__dirname, '..')
@@ -36,6 +87,8 @@ const COPY_DIRS = ['commands', 'skills']
 const PRUNED_PATHS = ['commands/sf-init.md', 'skills/sf-scaffold']
 
 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,17 +103,57 @@ 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 theme [options]          Change the site color mode deterministically
+  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 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>)
+  --site-name <name>   human site name                 (default: Title Case of <name>)
   --backend-url <url>  Medusa backend URL              (default: http://localhost:9000)
   --preset <preset>    maia | nova | vega | luma | lyra | mira (required without a terminal)
+  --mode <mode>        light | dark | system           (default: system)
   --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
 
+theme options:
+  --mode <mode>        light | dark | system (required; rewritten in app/layout.tsx)
+
+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
+
 In a terminal, create prompts for missing inputs (Maia is preselected).
 Without a terminal, every required input must be a flag — the command fails fast.
 `
@@ -73,9 +166,18 @@ function parseArgs(argv) {
     siteName: null,
     backendUrl: null,
     preset: null,
+    mode: null,
     brand: null,
     force: false,
     help: false,
+    intents: {},
+    variants: {},
+    json: false,
+    packs: null,
+    config: null,
+    operations: null,
+    out: null,
+    plan: null,
   }
   const positionals = []
   for (let i = 0; i < argv.length; i++) {
@@ -88,8 +190,46 @@ function parseArgs(argv) {
       out.backendUrl = argv[++i]
     } else if (arg === '--preset') {
       out.preset = argv[++i]
+    } else if (arg === '--mode') {
+      out.mode = argv[++i]
     } else if (arg === '--brand') {
       out.brand = argv[++i]
+    } 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 === '--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 +243,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,28 +344,6 @@ async function prunePath(opencodeDir, relPath) {
   await rm(join(opencodeDir, relPath), { recursive: true, force: true })
 }
 
-function sha256(text) {
-  return createHash('sha256').update(text).digest('hex')
-}
-
-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)
-    }
-  }
-  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'))}`)
-  }
-  return sha256(lines.join('\n'))
-}
-
 function pkgVersion() {
   const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
   return pkg.version
@@ -172,14 +363,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() {
@@ -204,8 +463,11 @@ async function installSuite(opencodeDir, force) {
   return total
 }
 
-function run(cmd, cmdArgs, cwd) {
-  const res = spawnSync(cmd, cmdArgs, { cwd, stdio: 'inherit', shell: false })
+// 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
 }
 
@@ -258,6 +520,7 @@ async function promptScaffoldInputs(args) {
     siteName: args.siteName ?? null,
     backendUrl: args.backendUrl ?? null,
     preset: args.preset ?? null,
+    mode: args.mode ?? null,
     brand: args.brand ?? null,
   }
 
@@ -265,11 +528,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 +551,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.')
@@ -318,6 +592,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 +616,39 @@ 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,
+      siteName: inputs.siteName ?? toTitle(inputs.name),
       backendUrl: inputs.backendUrl ?? DEFAULT_BACKEND_URL,
       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 +658,80 @@ async function create(args) {
     return 1
   }
 
-  const { name, siteName, backendUrl, preset, brand } = inputs
+  const { name, siteName, backendUrl, preset, mode, brand } = inputs
+
+  // 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. `create` always composes the home baseline, but 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 manifest = createManifest({ name, siteName, mode, views: ['home'], 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}`)
 
@@ -381,7 +759,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 +774,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,33 +817,71 @@ 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 })
+  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`
+  //    The store context is explicit host configuration (never hardcoded in the
+  //    app): store identity from the manifest name, channel/region/currency from
+  //    the environment. The session signing secret is generated per install
+  //    (32 bytes) and lives only in the git-ignored `.env.local`; the committed
+  //    `.env.example` carries an empty placeholder, never a real secret.
+  const sessionSecret = randomBytes(32).toString('base64url')
+  const envLocal = [
+    'THOR_DATA_SOURCE=medusa',
+    `MEDUSA_BASE_URL=${backendUrl}`,
+    'MEDUSA_PUBLISHABLE_KEY=',
+    'MEDUSA_REGION_ID=',
+    'MEDUSA_SALES_CHANNEL_ID=',
+    `THOR_STORE_ID=${name}`,
+    'THOR_CURRENCY_CODE=',
+    `THOR_SESSION_SECRET=${sessionSecret}`,
+  ].join('\n') + '\n'
   await writeFile(join(target, '.env.local'), envLocal, 'utf8')
+  const envExample = [
+    '# Data source: "mock" for explicit demo data, "medusa" for a real backend.',
+    'THOR_DATA_SOURCE=mock',
+    '# Store context (validated before any commerce call; currency is never hardcoded).',
+    '# Mock mode must match the fixture context: channel mock-sales-channel,',
+    '# region mock-region-us (USD) or mock-region-eu (EUR).',
+    `THOR_STORE_ID=${name}`,
+    'THOR_CURRENCY_CODE=USD',
+    'MEDUSA_SALES_CHANNEL_ID=mock-sales-channel',
+    'MEDUSA_REGION_ID=mock-region-us',
+    '# Real backend (required only when THOR_DATA_SOURCE=medusa).',
+    'MEDUSA_BASE_URL=http://localhost:9000',
+    'MEDUSA_PUBLISHABLE_KEY=',
+    '# Host-only cookie signing secret; >=16 chars, 32 recommended. Generate your own.',
+    'THOR_SESSION_SECRET=',
+  ].join('\n') + '\n'
+  await writeFile(join(target, '.env.example'), envExample, 'utf8')
 
   const globalsPath = join(target, 'app', 'globals.css')
   if (existsSync(globalsPath)) {
@@ -440,7 +892,12 @@ async function create(args) {
   // 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`)
 
   console.log('')
@@ -466,18 +923,57 @@ async function update(args) {
     return 1
   }
 
-  const total = await installSuite(opencodeDir, args.force)
+  // 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
+  }
+
+  // Refresh the package-managed suite to the current artifact set, 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.
+  const total = await installSuite(opencodeDir, true)
   for (const rel of PRUNED_PATHS) await prunePath(opencodeDir, rel)
-  await writeRecord(target, pkgVersion())
+  if (manifest) {
+    const result = await reconcile(target, manifest)
+    if (!result.ok) return rejectComposition(result.errors)
+  }
+  // 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 })
 
   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(`  recorded version ${version} (${Object.keys(pinning.assets).length} managed asset(s))`)
   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)')
   return 0
 }
 
@@ -489,25 +985,645 @@ 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')
+    }
+  }
+
   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
+}
+
+async function theme(args) {
+  const target = args.dir
+  if (!existsSync(target)) {
+    console.error(`Target directory does not exist: ${target}`)
+    return 1
+  }
+  if (!args.mode) {
+    console.error(`--mode is required (one of: ${THEME_MODES.join(', ')})`)
+    return 1
+  }
+  if (!THEME_MODES.includes(args.mode)) {
+    console.error(`--mode must be one of: ${THEME_MODES.join(', ')}, got: ${args.mode}`)
+    return 1
+  }
+
+  // Gate the existing composition before writing app/layout.tsx. Theme changes
+  // only the color-mode wiring, but it must never stamp a project whose manifest
+  // is not a supported 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 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
+  }
+
+  if (manifest) {
+    // Theme is manifest state: record the mode, then reconcile so the derived
+    // layout (and every other derived file) reflects it. A later `sync` is then
+    // a no-op, so the theme change cannot be reverted by regeneration.
+    manifest.theme = { ...manifest.theme, mode: args.mode }
+    const nextPreflight = preflightManifest(manifest)
+    if (!nextPreflight.ok) return rejectComposition(nextPreflight.errors)
+    await writeManifest(target, manifest)
+    const result = await reconcile(target, manifest)
+    if (!result.ok) return rejectComposition(result.errors)
+    console.log(`Theme mode set to "${args.mode}" in storefront.config.json`)
+    return 0
+  }
+
+  // Legacy project without a manifest: only the layout wiring can be updated.
+  // Deterministic rewrite: same mode -> identical bytes (idempotent).
+  const existing = readFileSync(layoutPath, 'utf8')
+  const next = injectThemeMode(existing, args.mode)
+  if (next === existing) {
+    console.log(`Theme mode already "${args.mode}" — no change.`)
+    return 0
+  }
+  await writeFile(layoutPath, next, 'utf8')
+  console.log(`Theme mode set to "${args.mode}" in ${relative(process.cwd(), layoutPath) || layoutPath}`)
+  return 0
+}
+
+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
+  }
+
+  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
+}
+
+// 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 ?? [],
+    },
+  }
+  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)'}`)
+  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 +1635,96 @@ 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 === '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']
+  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)
+    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
+  })