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

package/bin/storefront.js

@@ -4,10 +4,11 @@
 //
 // 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 —
+// 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
@@ -20,13 +21,27 @@
 import { cp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
 import { existsSync, readFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
-import { randomBytes } from 'node:crypto'
+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 { 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,
@@ -38,6 +53,7 @@ import {
 } 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,
@@ -47,6 +63,7 @@ import {
   verifyPackManifest,
 } from '../scripts/candidate.mjs'
 import {
+  declaredOperativeSkills,
   hashManagedSuite,
   hashPaths,
   managedSuitePaths,
@@ -54,6 +71,8 @@ import {
   readResolvedVersions,
   readLockfile,
   readToolchainEvidence,
+  recordedOwnedSet,
+  retirementCandidates,
   buildPinningRecord,
   validateDeclaredContract,
   validatePinning,
@@ -69,22 +88,44 @@ import {
   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, planProject, resultEnvelope } from '../scripts/plan-apply.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']
@@ -103,13 +144,16 @@ const HELP = `@thorprovider/storefront — scaffold Thor Commerce storefronts
 
 Usage:
   storefront create <dir> [options]   Scaffold a storefront and install the suite
-  storefront theme [options]          Change the site color mode deterministically
+  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
@@ -122,17 +166,42 @@ from the current directory upward (storefront.config.json) and errors outside on
 create options:
   --name <name>        storefront name = lib/<name>/ (required without a terminal)
   --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)
+  --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
 
+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:
-  --mode <mode>        light | dark | system (required; rewritten in app/layout.tsx)
+  (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
@@ -154,7 +223,19 @@ features options:
 recipes options:
   --json                    print the whole curated registry (views + features) as JSON
 
-In a terminal, create prompts for missing inputs (Maia is preselected).
+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.
 `
 
@@ -165,8 +246,12 @@ 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,
@@ -178,6 +263,25 @@ function parseArgs(argv) {
     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++) {
@@ -188,12 +292,44 @@ 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') {
@@ -202,6 +338,20 @@ function parseArgs(argv) {
       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('=')
@@ -344,6 +494,83 @@ async function prunePath(opencodeDir, relPath) {
   await rm(join(opencodeDir, relPath), { recursive: true, force: true })
 }
 
+// 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
+}
+
+// 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`',
+    }
+  }
+}
+
+// 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}` }
+  }
+  await seedOpenSpecConfig(target)
+  return { ok: true, version: resolved.version }
+}
+
 function pkgVersion() {
   const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
   return pkg.version
@@ -454,15 +681,86 @@ 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
 }
 
+// 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.
@@ -471,54 +769,25 @@ function runYarn(yarnSpec, cmdArgs, cwd) {
   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,
@@ -564,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:',
@@ -623,7 +880,6 @@ async function promptScaffoldInputs(args) {
     inputs: {
       name: 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,
@@ -658,7 +914,13 @@ async function create(args) {
     return 1
   }
 
-  const { name, siteName, backendUrl, preset, mode, 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
@@ -704,10 +966,21 @@ async function create(args) {
   }
 
   // Validate the complete desired composition before the first filesystem
-  // operation. `create` always composes the home baseline, but it must pass the
+  // 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 manifest = createManifest({ name, siteName, mode, views: ['home'], features: [] })
+  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)
 
@@ -729,7 +1002,6 @@ async function create(args) {
   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}`)
@@ -743,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
@@ -842,51 +1114,30 @@ async function create(args) {
   //    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 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
-  //    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')
+  //    `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
@@ -900,11 +1151,171 @@ async function create(args) {
   }
   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
 }
 
@@ -947,16 +1358,35 @@ async function update(args) {
     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.
+  // 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)
-  for (const rel of PRUNED_PATHS) await prunePath(opencodeDir, rel)
+  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)
@@ -968,12 +1398,41 @@ async function update(args) {
   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)')
+  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))`)
-  console.log('Done. Available in OpenCode:')
-  console.log('  /sf-add-view  /sf-view  /sf-theme')
+  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
 }
 
@@ -1012,6 +1471,18 @@ async function doctor(args) {
       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')
@@ -1070,24 +1541,195 @@ async function doctor(args) {
   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
   }
-  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}`)
+
+  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 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.
+  // 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}`)
@@ -1098,38 +1740,141 @@ async function theme(args) {
     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
+  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]
   }
 
-  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 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)
-    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
+  return themeReport(args, { status: 'changed', changes, diagnostics: planned.diagnostics, values: planned.values })
 }
 
 async function sync(args) {
@@ -1188,6 +1933,45 @@ async function view(args) {
     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'
@@ -1314,6 +2098,284 @@ async function feature(args) {
   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
@@ -1357,6 +2419,7 @@ function inspect(args) {
       views: manifest?.views ?? [],
       features: manifest?.features ?? [],
     },
+    dataBoundSections: collectDataBoundInstances(manifest, sectionIsDataBound),
   }
   const envelope = resultEnvelope('inspect', true, 0, [], result)
   if (args.json) {
@@ -1368,6 +2431,9 @@ function inspect(args) {
   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
 }
 
@@ -1660,6 +2726,16 @@ async function main() {
     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) {
@@ -1680,7 +2756,7 @@ async function main() {
     return apply({ ...args, dir: root })
   }
 
-  const SCOPED = ['theme', 'update', 'doctor', 'sync']
+  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.`)
@@ -1692,6 +2768,7 @@ async function main() {
     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)
   }