uniweb 1.0.0 → 1.0.2

package/src/index.js

@@ -0,0 +1,2241 @@
+#!/usr/bin/env node
+
+/**
+ * Uniweb CLI
+ *
+ * Scaffolds new Uniweb sites and foundations, builds projects, and generates docs.
+ *
+ * Install globally:
+ *   npm i -g uniweb
+ *
+ * Usage:
+ *   uniweb create [project-name]
+ *   uniweb create --template marketing
+ *   uniweb add foundation [name]
+ *   uniweb build
+ *   uniweb docs
+ *
+ * Global install delegation:
+ *   When installed globally, project-bound commands (build, docs, etc.) are
+ *   delegated to the project-local CLI if one exists in node_modules. This
+ *   ensures version alignment between the CLI and @uniweb/build.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { execSync, spawn as spawnChild } from 'node:child_process'
+import { resolve, join, relative, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import prompts from 'prompts'
+// `doctor`, `add`, `publish`, and `deploy` are loaded lazily via
+// importProjectCommand() — each imports `@uniweb/build` at the top,
+// so a static import here would crash `npx uniweb@latest create …`
+// (no @uniweb/build in the npx scratch dir) before any command runs.
+// Same pattern as `build` and `docs`.
+import { i18n } from './commands/i18n.js'
+import { inspect } from './commands/inspect.js'
+import { invite } from './commands/invite.js'
+import { handoff } from './commands/handoff.js'
+import { update } from './commands/update.js'
+import { clone } from './commands/clone.js'
+import { template } from './commands/template.js'
+import {
+  resolveTemplate,
+  parseTemplateId,
+  buildTemplateChoices,
+  templatePickerPageSize
+} from './templates/index.js'
+import { validateTemplate } from './templates/validator.js'
+import {
+  scaffoldWorkspace,
+  scaffoldFoundation,
+  scaffoldSite,
+  applyContent,
+  applyStarter,
+  mergeTemplateDependencies,
+  getWorkspaceTemplateOutputs
+} from './utils/scaffold.js'
+import {
+  normalizeFoundationName,
+  ensureFoundationName
+} from './utils/foundation-name.js'
+import {
+  detectPackageManager,
+  detectWorkspacePm,
+  filterCmd,
+  installCmd,
+  runCmd,
+  isPnpmAvailable
+} from './utils/pm.js'
+import {
+  isNonInteractive,
+  getCliPrefix,
+  stripNonInteractiveFlag,
+  formatOptions
+} from './utils/interactive.js'
+import { findWorkspaceRoot } from './utils/workspace.js'
+import { exitWhenDrained } from './utils/exit.js'
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+}
+
+// Template choices for the interactive prompt — built-ins first, then every
+// official template in this CLI's snapshot (the list `create` can download),
+// with "Blank" last. Composed by buildTemplateChoices() in templates/resolver.js.
+const TEMPLATE_CHOICES = buildTemplateChoices()
+
+// Files that may pre-exist in the target dir during `uniweb create .` and
+// will be silently overwritten by the scaffold. Anything else colliding
+// causes the verb to abort. README and .gitignore are the only two files
+// the workspace template writes that overlap with what `gh repo create`
+// puts in a fresh repo, and the scaffold's versions are more useful in
+// this context (Vite/Node-aware .gitignore, project-shaped README).
+const IN_PLACE_OVERWRITE_ALLOWED = new Set(['README.md', '.gitignore'])
+
+/**
+ * Slugify a directory name into a valid project slug — lowercase,
+ * `[a-z0-9-]+`, no leading/trailing/duplicated hyphens. Matches the
+ * validation regex used for the interactive name prompt.
+ *
+ * @param {string} name
+ * @returns {string} Slugified name; empty if no valid characters remain.
+ */
+function slugifyName(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+}
+
+function log(message) {
+  console.log(message)
+}
+
+function success(message) {
+  console.log(`${colors.green}✓${colors.reset} ${message}`)
+}
+
+function error(message) {
+  console.error(`${colors.red}✗${colors.reset} ${message}`)
+}
+
+function title(message) {
+  console.log(`\n${colors.cyan}${colors.bright}${message}${colors.reset}\n`)
+}
+
+// CLI version (read once, lazily)
+const __dirname = dirname(fileURLToPath(import.meta.url))
+let _cliVersion = null
+function getCliVersion() {
+  if (!_cliVersion) {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, '..', 'package.json'), 'utf8')
+    )
+    _cliVersion = pkg.version
+  }
+  return _cliVersion
+}
+
+/**
+ * Commands that always run from the global CLI (no project context needed)
+ */
+// Commands that always run from the global CLI, never delegating to a
+// project-local copy. `update` is here because it reconciles the project
+// against *this* CLI's version matrix — when run from a (newer) global
+// install that's the whole point; delegating to the project-local copy
+// would align the project to the version it already has, i.e. a no-op.
+const STANDALONE_COMMANDS = new Set([
+  'create',
+  'clone',
+  '--help',
+  '-h',
+  '--version',
+  '-v',
+  'login',
+  'logout',
+  'update'
+])
+
+/**
+ * Check if this CLI is running from a global install.
+ * When installed globally, process.argv[1] points outside any node_modules.
+ * When run via npx or as a local dependency, it's inside node_modules.
+ */
+function isGlobalInstall() {
+  const scriptPath = process.argv[1]
+  if (!scriptPath) return false
+  // Normalize path separators for Windows compatibility
+  return (
+    !scriptPath.split('/').includes('node_modules') &&
+    !scriptPath.split('\\').includes('node_modules')
+  )
+}
+
+/**
+ * Find the project-local CLI entry point, if one exists.
+ * Walks up from cwd looking for node_modules/uniweb/src/index.js.
+ */
+function findLocalCli() {
+  let dir = process.cwd()
+  while (true) {
+    const localCli = join(dir, 'node_modules', 'uniweb', 'src', 'index.js')
+    if (existsSync(localCli)) return localCli
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * Delegate execution to the project-local CLI.
+ * Spawns the local CLI with the same arguments and inherits stdio.
+ * Warns if the local version differs from the global version.
+ */
+function delegateToLocal(localCliPath) {
+  // Check for version mismatch between global and local CLI
+  try {
+    const localPkgPath = join(dirname(localCliPath), '..', 'package.json')
+    const localPkg = JSON.parse(readFileSync(localPkgPath, 'utf8'))
+    const globalVersion = getCliVersion()
+    if (localPkg.version && localPkg.version !== globalVersion) {
+      const yellow = '\x1b[33m'
+      const dim = '\x1b[2m'
+      const reset = '\x1b[0m'
+      console.error(
+        `${yellow}Note:${reset} Global CLI is ${dim}${globalVersion}${reset}, project has ${dim}${localPkg.version}${reset} ${dim}(using project version)${reset}`
+      )
+    }
+  } catch {
+    /* ignore — version check is best-effort */
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawnChild(
+      process.execPath,
+      [localCliPath, ...process.argv.slice(2)],
+      { stdio: 'inherit' }
+    )
+    child.on('close', (code) => exitWhenDrained(code ?? 0))
+    child.on('error', reject)
+  })
+}
+
+/**
+ * Import a command module that may depend on an optional @uniweb/* peer
+ * (`@uniweb/build` above all). Sixteen commands load through here, so this
+ * is the error most users meet when something is not installed.
+ *
+ * ⛔ IT MUST NOT NAME A CAUSE IT HAS NOT CHECKED. This said "This command
+ * must be run from inside a Uniweb project" for every `ERR_MODULE_NOT_FOUND`
+ * on a `@uniweb/*` specifier — a guess, and wrong in the two cases that do
+ * not involve your location at all: a workspace whose dependencies are simply
+ * not installed, and a CLI installed on its own (the optional peers are not
+ * installed with it, so `npm install uniweb --prefix X` yields exactly this).
+ * Project resolution is cwd-based (`findWorkspaceRoot`) and always was, so
+ * the check the message needed was one call away and already imported here.
+ *
+ * ⚠️ A wrong cause is worse than a vague one: it does not merely fail to
+ * explain, it DIRECTS the investigation. Reported 2026-09-09 by a consumer
+ * who lost an hour testing the cause this text named, having already done
+ * the `cd` and the install it advised.
+ */
+async function importProjectCommand(modulePath) {
+  try {
+    return await import(modulePath)
+  } catch (err) {
+    if (
+      err.code !== 'ERR_MODULE_NOT_FOUND' ||
+      !err.message?.includes('@uniweb/')
+    ) {
+      throw err
+    }
+
+    // Name the package that actually failed to resolve, rather than making
+    // the reader guess which of the optional peers this command needed.
+    const missing =
+      err.message.match(/'(@uniweb\/[^']+)'/)?.[1] ?? 'a @uniweb/* package'
+    const root = findWorkspaceRoot(process.cwd())
+
+    // ⛔ THREE STATES, and the second and third look identical from here — the
+    // import failed either way. Discriminate on what is ON DISK, because
+    // "declared but not installed" and "installed but not reachable from where
+    // THIS CLI lives" have opposite remedies, and telling a fully-installed
+    // workspace to run its installer is the same wrong-cause defect again.
+    const workspaceModules = root ? join(root, 'node_modules') : null
+    const workspaceInstalled = !!workspaceModules && existsSync(workspaceModules)
+    const localCli = root ? join(workspaceModules, '.bin', 'uniweb') : null
+
+    error(`Cannot load ${missing}, which this command needs.`)
+    log('')
+
+    if (!root) {
+      log(
+        `No Uniweb workspace found above ${colors.dim}${process.cwd()}${colors.reset}.`
+      )
+      log(`  ${colors.cyan}cd${colors.reset} into a project, or create one:`)
+      log(`  ${colors.cyan}uniweb create my-project${colors.reset}`)
+      log('')
+      log(
+        `${colors.dim}Driving projects from a standalone CLI? ${missing} is an optional${colors.reset}`
+      )
+      log(
+        `${colors.dim}peer, so a bare \`npm i uniweb\` does not bring it:${colors.reset}`
+      )
+      log(`  ${colors.cyan}npm install uniweb ${missing}${colors.reset}`)
+    } else if (!workspaceInstalled) {
+      // Declared, not on disk. Prefer the workspace's own package manager,
+      // read off its lockfile — but a workspace that has NEVER been installed
+      // has no lockfile to read, so fall back the same way `create` does
+      // rather than to whichever PM happens to be running this process.
+      const pm =
+        detectWorkspacePm(root) ||
+        (isPnpmAvailable() ? 'pnpm' : detectPackageManager())
+      log(`Uniweb workspace: ${colors.dim}${root}${colors.reset}`)
+      log(`Its dependencies are not installed:`)
+      log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+    } else {
+      // Installed, and still unreachable: Node resolves a command's imports
+      // from the CLI's own location, so a CLI installed elsewhere cannot see
+      // this workspace's copy. Both remedies are real; the local bin is the
+      // one that guarantees the project's own pinned toolchain does the work.
+      log(
+        `Uniweb workspace: ${colors.dim}${root}${colors.reset} ${colors.dim}(dependencies are installed)${colors.reset}`
+      )
+      log(
+        `This CLI resolves its imports from its own install location, not from`
+      )
+      log(`the workspace, so it cannot see the workspace's ${missing}.`)
+      log('')
+      log(`Use the project's own CLI:`)
+      log(`  ${colors.cyan}${localCli}${colors.reset}`)
+      log(`or install the peer next to this one:`)
+      log(`  ${colors.cyan}npm install uniweb ${missing}${colors.reset}`)
+    }
+
+    await exitWhenDrained(1)
+  }
+}
+
+/**
+ * Create a project using the new package template flow (default)
+ */
+async function createFromPackageTemplates(
+  projectDir,
+  projectName,
+  options = {}
+) {
+  const { onProgress, onWarning, pm = 'pnpm', includeStarter = true } = options
+
+  onProgress?.('Setting up workspace...')
+
+  // 1. Scaffold workspace.
+  // dev/build go through `uniweb` verbs so the scripts stay PM-agnostic
+  // (the verb resolves the right PM at runtime instead of locking the
+  // root scripts to whichever PM ran `npx uniweb create`). preview stays
+  // PM-filtered until a `uniweb preview` verb exists.
+  await scaffoldWorkspace(
+    projectDir,
+    {
+      projectName,
+      workspaceGlobs: ['site', 'src'],
+      scripts: {
+        dev: 'uniweb dev',
+        build: 'uniweb build',
+        preview: filterCmd(pm, 'site', 'preview')
+      }
+    },
+    { onProgress, onWarning }
+  )
+
+  // 2. Scaffold foundation (folder: src/, package name: src)
+  // The folder name 'src' carries the meaning — a foundation is the site's
+  // source code. The package name 'src' keeps it unique within the
+  // workspace, since 'site' is taken by the site package. Neither is the
+  // foundation's NAME — what it registers as — which is main.js's `name`:
+  // the project's, since a project's code is its foundation.
+  onProgress?.('Creating foundation...')
+  const registryName = normalizeFoundationName(projectName)
+  await scaffoldFoundation(
+    join(projectDir, 'src'),
+    {
+      name: 'src',
+      registryName,
+      projectName,
+      isExtension: false
+    },
+    { onProgress, onWarning }
+  )
+
+  // 3. Scaffold site
+  onProgress?.('Creating site...')
+  await scaffoldSite(
+    join(projectDir, 'site'),
+    {
+      name: 'site',
+      projectName,
+      foundationName: 'src',
+      foundationPath: 'file:../src',
+      foundationRef: 'src'
+    },
+    { onProgress, onWarning }
+  )
+
+  // 4. Apply starter content (unless creating a "none" project). Its main.js
+  // replaces the scaffolded one, so the name is given again.
+  if (includeStarter) {
+    onProgress?.('Adding starter content...')
+    await applyStarter(projectDir, { projectName }, { onProgress, onWarning })
+    ensureFoundationName(join(projectDir, 'src'), registryName)
+  }
+
+  success(`Created project: ${projectName}`)
+}
+
+/**
+ * Create a blank workspace (no packages, grow with `add`)
+ */
+async function createBlankWorkspace(projectDir, projectName, options = {}) {
+  const { onProgress, onWarning } = options
+
+  onProgress?.('Setting up blank workspace...')
+
+  await scaffoldWorkspace(
+    projectDir,
+    {
+      projectName,
+      workspaceGlobs: [],
+      scripts: {
+        build: 'uniweb build'
+      }
+    },
+    { onProgress, onWarning }
+  )
+
+  success(`Created blank workspace: ${projectName}`)
+}
+
+/**
+ * Create a project from a format 2 content template
+ *
+ * Scaffolds workspace structure from package templates, then overlays
+ * content (sections, pages, theme) from the content template.
+ */
+async function createFromContentTemplate(
+  projectDir,
+  projectName,
+  metadata,
+  templateRootPath,
+  options = {}
+) {
+  const { onProgress, onWarning, pm = 'pnpm' } = options
+
+  // Determine packages to create
+  // Default single-foundation single-site project uses package names
+  // 'src' (folder: src/) and 'site' (folder: site/). The folder
+  // convention is set in computePlacement() below.
+  const packages = metadata.packages || [
+    { type: 'foundation', name: 'src' },
+    { type: 'site', name: 'site', foundation: 'src' }
+  ]
+
+  // Compute placement for each package
+  const placed = computePlacement(packages)
+
+  // Compute workspace globs and scripts from placement
+  const workspaceGlobs = placed.map((p) => p.relativePath)
+  const sites = placed.filter((p) => p.type === 'site')
+  const scripts = {
+    build: 'uniweb build'
+  }
+  // dev goes through `uniweb` (PM-agnostic; see computeRootScripts).
+  // preview stays PM-filtered until a `uniweb preview` verb exists.
+  if (sites.length === 1) {
+    scripts.dev = 'uniweb dev'
+    scripts.preview = filterCmd(pm, sites[0].name, 'preview')
+  } else {
+    for (const s of sites) {
+      scripts[`dev:${s.name}`] = `uniweb dev ${s.name}`
+      scripts[`preview:${s.name}`] = filterCmd(pm, s.name, 'preview')
+    }
+    // First site gets unqualified aliases
+    if (sites.length > 0) {
+      scripts.dev = 'uniweb dev'
+      scripts.preview = filterCmd(pm, sites[0].name, 'preview')
+    }
+  }
+
+  // 1. Scaffold workspace
+  onProgress?.('Setting up workspace...')
+  await scaffoldWorkspace(
+    projectDir,
+    {
+      projectName,
+      workspaceGlobs,
+      scripts
+    },
+    { onProgress, onWarning }
+  )
+
+  // 2. Scaffold and apply content for each package
+  const claimed = new Set() // names this project's foundations register as
+  for (const pkg of placed) {
+    const fullPath = join(projectDir, pkg.relativePath)
+
+    // A foundation's name — what it registers as — is the template's name for
+    // the package when that is one, else the project's (`src` and `foundation`
+    // name a folder); `<project>-<package>` if another package here took it. A
+    // template's own main.js `name` outranks all of them.
+    let registryName = null
+    if (pkg.type === 'foundation' || pkg.type === 'extension') {
+      registryName =
+        [
+          normalizeFoundationName(pkg.name) || normalizeFoundationName(projectName),
+          normalizeFoundationName(`${projectName}-${pkg.name}`)
+        ].find((n) => n && !claimed.has(n)) || null
+      if (registryName) claimed.add(registryName)
+    }
+
+    if (pkg.type === 'foundation' || pkg.type === 'extension') {
+      onProgress?.(`Creating ${pkg.type}: ${pkg.name}...`)
+      await scaffoldFoundation(
+        fullPath,
+        {
+          name: pkg.name,
+          registryName,
+          projectName,
+          isExtension: pkg.type === 'extension'
+        },
+        { onProgress, onWarning }
+      )
+    } else if (pkg.type === 'site') {
+      // Find the foundation this site wires to
+      const foundationName = pkg.foundation || 'src'
+      const foundationPkg = placed.find(
+        (p) => p.type === 'foundation' && p.name === foundationName
+      )
+      const foundationPath = foundationPkg
+        ? computeFoundationFilePath(
+            pkg.relativePath,
+            foundationPkg.relativePath
+          )
+        : 'file:../src'
+
+      onProgress?.(`Creating site: ${pkg.name}...`)
+      // Always write `foundation: <name>` to site.yml — the value is
+      // never the implicit default in the new layout (the build's
+      // `detectFoundationType` defaults to 'foundation' when absent,
+      // which doesn't match 'src').
+      await scaffoldSite(
+        fullPath,
+        {
+          name: pkg.name,
+          projectName,
+          foundationName,
+          foundationPath,
+          foundationRef: foundationName
+        },
+        { onProgress, onWarning }
+      )
+    }
+
+    // Apply content from the matching content directory
+    const contentDir = findContentDirFor(metadata.contentDirs, pkg)
+    if (contentDir) {
+      onProgress?.(`Applying ${metadata.name} content to ${pkg.name}...`)
+      await applyContent(
+        contentDir.dir,
+        fullPath,
+        { projectName },
+        { onProgress, onWarning }
+      )
+      ensureFoundationName(fullPath, registryName)
+    }
+
+    // Merge template dependencies into package.json
+    if (metadata.dependencies) {
+      const deps =
+        metadata.dependencies[pkg.name] || metadata.dependencies[pkg.type]
+      if (deps) {
+        await mergeTemplateDependencies(join(fullPath, 'package.json'), deps)
+      }
+    }
+  }
+
+  success(`Created project: ${projectName}`)
+}
+
+/**
+ * Compute placement (relative paths) for packages
+ *
+ * Rules:
+ * - 1 foundation → src/             (folder name is 'src' regardless of package name;
+ *                                    the package name is typically 'src' or
+ *                                    whatever the template declared)
+ * - Multiple foundations → foundations/{name}/
+ * - Extensions → extensions/{name}/
+ * - 1 site named "site" → site/
+ * - Multiple sites → sites/{name}/
+ */
+function computePlacement(packages) {
+  const foundations = packages.filter((p) => p.type === 'foundation')
+  const extensions = packages.filter((p) => p.type === 'extension')
+  const sites = packages.filter((p) => p.type === 'site')
+
+  const placed = []
+
+  for (const f of foundations) {
+    if (foundations.length === 1) {
+      placed.push({ ...f, relativePath: 'src' })
+    } else {
+      placed.push({ ...f, relativePath: `foundations/${f.name}` })
+    }
+  }
+
+  for (const e of extensions) {
+    placed.push({ ...e, relativePath: `extensions/${e.name}` })
+  }
+
+  for (const s of sites) {
+    if (sites.length === 1 && s.name === 'site') {
+      placed.push({ ...s, relativePath: 'site' })
+    } else {
+      placed.push({ ...s, relativePath: `sites/${s.name}` })
+    }
+  }
+
+  return placed
+}
+
+/**
+ * Find the content directory that matches a placed package
+ */
+function findContentDirFor(contentDirs, pkg) {
+  if (!contentDirs) return null
+  // Match by name first, then by type
+  return (
+    contentDirs.find((d) => d.name === pkg.name) ||
+    contentDirs.find((d) => d.type === pkg.type && d.name === pkg.type)
+  )
+}
+
+/**
+ * Compute relative file: path from site to foundation
+ */
+function computeFoundationFilePath(sitePath, foundationPath) {
+  const rel = relative(sitePath, foundationPath)
+  return `file:${rel}`
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2)
+  const nonInteractive = isNonInteractive(rawArgs)
+  const args = stripNonInteractiveFlag(rawArgs)
+  const command = args[0]
+  const pm = detectPackageManager()
+
+  // ⛔ THE VARIABLE THAT AIMS A PROCESS IS UNIWEB_SERVER — UNIWEB_REGISTER_URL until 2026-10-07.
+  // Set ALONE, the old name is refused rather than ignored: ignored, a script that meant a
+  // local or staging backend would go to the default one, uniweb.app, and say nothing. Set
+  // beside the new one it is ignored, so a script can carry both while CLIs of both ages run it.
+  if (process.env.UNIWEB_REGISTER_URL && !process.env.UNIWEB_SERVER) {
+    error('UNIWEB_REGISTER_URL is now UNIWEB_SERVER — rename it, and the command goes to the same backend.')
+    await exitWhenDrained(2)
+  }
+
+  // Handle --version / -v
+  //
+  // Output convention: the version goes to stdout (parseable, scriptable —
+  // `version=$(uniweb --version)` should keep working). Any staleness
+  // notice goes to stderr, so it shows in interactive terminals but
+  // doesn't pollute captured output.
+  //
+  // Two staleness paths split by stdout TTY-ness:
+  //   - TTY (interactive user typed it): fetch the registry with a tight
+  //     timeout. Accuracy matters — a fresh install would otherwise see
+  //     no notice on its first invocation (the cache is empty). Network
+  //     latency is acceptable here, capped at ~1.5s by the abort timeout.
+  //   - Non-TTY (script captured stdout, piped through, etc.): cache-only.
+  //     Scripts must stay fast and offline-safe. The `gh --version` /
+  //     `claude --version` convention.
+  if (command === '--version' || command === '-v') {
+    console.log(`uniweb ${getCliVersion()}`)
+    if (isGlobalInstall()) {
+      try {
+        const { fetchAndNotifyIfNewer, maybeNotifyFromCache } =
+          await import('./utils/update-check.js')
+        if (process.stdout.isTTY) {
+          await fetchAndNotifyIfNewer(getCliVersion())
+        } else {
+          maybeNotifyFromCache(getCliVersion())
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+    return
+  }
+
+  // Global install launcher: delegate project-bound commands to local CLI
+  const global = isGlobalInstall()
+  if (global && command && !STANDALONE_COMMANDS.has(command)) {
+    const localCli = findLocalCli()
+    if (localCli) {
+      await delegateToLocal(localCli)
+      return
+    }
+    // No local CLI found — fall through and try to run the command directly.
+    // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
+  }
+
+  // Update check for global installs.
+  //
+  //   - `create` / `clone` STOP when a newer release exists, before anything is
+  //     written: a project starts on the packages and templates of the CLI that
+  //     creates it, and a global install runs these two itself — there is no
+  //     project CLI to delegate to yet (refuseOutdatedProjectStart). Their
+  //     `--help` still prints.
+  //   - every other verb gets a trailing notice (showUpdateNotification): they
+  //     are project-bound (delegated to local node_modules) or do not depend on
+  //     the version, and the local-vs-global mismatch warning in
+  //     delegateToLocal covers the first case.
+  let showUpdateNotification = () => {}
+  if (global) {
+    let updateCheck = null
+    try {
+      updateCheck = await import('./utils/update-check.js')
+    } catch {
+      // Update check is optional — don't fail if the module is missing
+    }
+    const startsProject = command === 'create' || command === 'clone'
+    const asksForHelp = args.slice(1).some((a) => a === '--help' || a === '-h')
+    if (
+      updateCheck &&
+      startsProject &&
+      !asksForHelp &&
+      (await updateCheck.refuseOutdatedProjectStart(getCliVersion(), args))
+    ) {
+      await exitWhenDrained(1)
+    }
+    if (updateCheck) showUpdateNotification = updateCheck.startUpdateCheck(getCliVersion())
+  }
+
+  // Show help
+  if (!command || command === '--help' || command === '-h') {
+    showHelp()
+    await showUpdateNotification()
+    return
+  }
+
+  // Per-command --help: short-circuit BEFORE the command's side effects run.
+  // Critical for `deploy --help` (used to open a browser to production for
+  // login because deploy.js doesn't parse --help and ensureAuth ran first).
+  // Falls back to the global help when a command has no dedicated block.
+  if (args.slice(1).some((a) => a === '--help' || a === '-h')) {
+    const printed = printCommandHelp(command)
+    if (printed) {
+      await showUpdateNotification()
+      return
+    }
+    // No dedicated block — show global help as a useful fallback rather
+    // than executing the command (which often has side effects).
+    showHelp()
+    await showUpdateNotification()
+    return
+  }
+
+  // Handle build command (dynamic import — depends on @uniweb/build)
+  if (command === 'build') {
+    const { build } = await importProjectCommand('./commands/build.js')
+    await build(args.slice(1))
+    await showUpdateNotification()
+    return
+  }
+
+  // Handle dev command — thin wrapper that shells to the package manager's
+  // workspace-filtered `dev` script (mirrors what `uniweb create` writes
+  // into the root package.json::scripts.dev). Lazy import keeps startup
+  // fast when the user is not running dev.
+  if (command === 'dev') {
+    const { dev } = await import('./commands/dev.js')
+    await dev(args.slice(1))
+    return
+  }
+
+  // Handle snapshot command (dynamic import — depends on @uniweb/build; loads
+  // @uniweb/snapshot itself, from the workspace, and says how to add it if absent)
+  if (command === 'snapshot') {
+    const { snapshot } = await importProjectCommand('./commands/snapshot.js')
+    await snapshot(args.slice(1))
+    await showUpdateNotification()
+    return
+  }
+
+  // Handle docs command (dynamic import — depends on @uniweb/build)
+  if (command === 'docs') {
+    const { docs } = await importProjectCommand('./commands/docs.js')
+    await docs(args.slice(1))
+    await showUpdateNotification()
+    return
+  }
+
+  // Handle i18n command
+  if (command === 'i18n') {
+    await i18n(args.slice(1))
+    return
+  }
+
+  // Handle doctor command (dynamic import — depends on @uniweb/build)
+  if (command === 'doctor') {
+    const { doctor } = await importProjectCommand('./commands/doctor.js')
+    const result = await doctor(args.slice(1))
+    await exitWhenDrained(result?.errors > 0 ? 1 : 0)
+  }
+
+  // Handle validate command (dynamic import — depends on @uniweb/build)
+  if (command === 'validate') {
+    const { validate } = await importProjectCommand('./commands/validate.js')
+    const result = await validate(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle register command (dynamic import — depends on @uniweb/build).
+  // `release` is a code-only synonym: `register` reads naturally the first
+  // time, `release` for updates (shipping-model.md §6.1). Same act, same code.
+  if (command === 'register' || command === 'release') {
+    const { register } = await importProjectCommand('./commands/register.js')
+    const result = await register(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle push command (dynamic import — depends on @uniweb/build)
+  if (command === 'push') {
+    const { push } = await importProjectCommand('./commands/push.js')
+    const result = await push(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle pull command (dynamic import — depends on @uniweb/build)
+  if (command === 'pull') {
+    const { pull } = await importProjectCommand('./commands/pull.js')
+    const result = await pull(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle sync command (refresh + push; both halves imported, never reimplemented)
+  if (command === 'sync') {
+    const { sync } = await importProjectCommand('./commands/sync.js')
+    const result = await sync(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle refresh command (dynamic import — depends on @uniweb/build via pull)
+  if (command === 'refresh') {
+    const { refresh } = await importProjectCommand('./commands/refresh.js')
+    const result = await refresh(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle forget — remove one backend's local records (sync.json, cache, deploy
+  // records), or with --all everything a copied project inherited. Local only: every
+  // site still exists on its backend. Needs @uniweb/build (the store).
+  if (command === 'forget') {
+    const { forget } = await importProjectCommand('./commands/forget.js')
+    const result = await forget(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle status command (dynamic import — offline emit via @uniweb/build)
+  if (command === 'status') {
+    const { status } = await importProjectCommand('./commands/status.js')
+    const result = await status(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle clone command (global — bootstraps a new project from a backend site;
+  // STANDALONE, so a global `uniweb clone` runs here instead of delegating to a
+  // project-local CLI that doesn't exist yet. clone.js avoids any static
+  // @uniweb/build import, then delegates the projection to the project-local
+  // `uniweb pull` after install.)
+  if (command === 'clone') {
+    const result = await clone(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle update command
+  if (command === 'update') {
+    await update(args.slice(1))
+    return
+  }
+
+  // Handle inspect command
+  if (command === 'inspect') {
+    await inspect(args.slice(1))
+    return
+  }
+
+  // Handle add command (dynamic import — depends on @uniweb/build)
+  if (command === 'add') {
+    const { add } = await importProjectCommand('./commands/add.js')
+    await add(args.slice(1))
+    return
+  }
+
+  // Handle rename command (dynamic import — depends on @uniweb/build via deps)
+  if (command === 'rename') {
+    const { rename } = await importProjectCommand('./commands/rename.js')
+    await rename(args.slice(1))
+    return
+  }
+
+  // Handle publish command — the smart Uniweb-hosting path: bring the
+  // foundation along, sync, settle payment, go live. Distinct from `deploy`
+  // (third-party hosts) and `register`/`release` (foundation code → catalog).
+  if (command === 'publish') {
+    const { publish } = await importProjectCommand('./commands/publish.js')
+    const result = await publish(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle deploy command — third-party hosts only (dynamic import — @uniweb/build)
+  if (command === 'deploy') {
+    const { deploy } = await importProjectCommand('./commands/deploy.js')
+    await deploy(args.slice(1))
+    return
+  }
+
+  // Handle export command (dynamic import — depends on @uniweb/build)
+  if (command === 'export') {
+    const { exportSite } = await importProjectCommand('./commands/export.js')
+    await exportSite(args.slice(1))
+    return
+  }
+
+  // Handle content command (dynamic import — depends on @uniweb/build/uwx)
+  if (command === 'content') {
+    const { content } = await importProjectCommand('./commands/content.js')
+    await content(args.slice(1))
+    return
+  }
+
+  // Handle login command — the backend (username/password · paste a token ·
+  // --token <bearer>). ⭐ `--server <url>` names it; without the flag it is the DEFAULT
+  // backend — UNIWEB_SERVER, else ~/.uniweb/config.json, else https://uniweb.app —
+  // and never the project's backend *[Diego, 2026-09-21: "the default backend for login, if
+  // not specified, is uniweb.app"]*. ⭐ Except a WORKSPACE SWITCH — `--org` / `--personal`
+  // and no way of signing in — which acts on the backend you are logged in to *[Diego,
+  // 2026-10-06]* (`resolveLoginOrigin`). The backend logged in to becomes CURRENT, and
+  // every backend command goes there (only UNIWEB_SERVER outranks it) — which is why
+  // this is the one place a backend is chosen.
+  //
+  // ⛔ Until 2026-09-21 a bare login went to the backend of the project in the cwd, and
+  // asked when the machine knew several backends. Both are gone: the default is the
+  // default, and any other backend is named.
+  if (command === 'login') {
+    const loginArgs = args.slice(1)
+    const { readFlagValue } = await import('./utils/args.js')
+    const { runRegistryLogin } = await import('./utils/registry-auth.js')
+    const { resolveLoginOrigin } = await import('./utils/config.js')
+    // `--backend` was this flag's name until 2026-10-07 — renamed so it is not read as a
+    // site's `backend` service. Refused with the new name, never treated as unknown and dropped:
+    // dropped, the login would go to the default backend.
+    if (loginArgs.some((a) => a === '--backend' || a.startsWith('--backend='))) {
+      console.error('\x1b[31m✗\x1b[0m `--backend` is now `--server`: uniweb login --server <url>')
+      await exitWhenDrained(2)
+    }
+    let apiBase
+    try {
+      apiBase = resolveLoginOrigin(readFlagValue(loginArgs, '--server'), loginArgs)
+    } catch (err) {
+      console.error(
+        `\x1b[31m✗\x1b[0m ${err.message} — e.g. uniweb login --server http://localhost:8080`
+      )
+      await exitWhenDrained(2)
+    }
+    await runRegistryLogin({ apiBase, args: loginArgs })
+    return
+  }
+
+  // Handle logout — THE session. ⭐ There is at most one *[Diego, 2026-09-21: "`uniweb
+  // logout` always logs you out of the one backend you may be logged in"]*, so logout
+  // takes no options: `--backend` and `--all` existed only while sessions were kept per
+  // backend. ⚠️ Local only — the token is forgotten here, not revoked on the backend.
+  if (command === 'logout') {
+    const stray = args.slice(1).find((a) => a.startsWith('-') && a !== '--non-interactive')
+    if (stray) {
+      console.error(
+        `\x1b[31m✗\x1b[0m \`uniweb logout\` takes no options (got ${stray}) — it logs you out of the backend you are logged in to.`
+      )
+      await exitWhenDrained(2)
+    }
+    const { clearRegistryAuth } = await import('./utils/registry-auth.js')
+    const { loggedInOrigin } = await import('./utils/config.js')
+    const origin = loggedInOrigin()
+    const cleared = await clearRegistryAuth()
+    if (!cleared.length) {
+      console.log('Not logged in — nothing to clear.')
+      return
+    }
+    console.log(`\x1b[32m✓\x1b[0m Logged out${origin ? ` of ${origin}` : ''}.`)
+    // A file from before sessions were single can hold several; all of them go.
+    const others = cleared.filter((o) => o !== origin)
+    if (others.length)
+      console.log(`\x1b[2mAlso removed stored sessions for: ${others.join(', ')}\x1b[0m`)
+    return
+  }
+
+  // Handle site command — the sites in a workspace: list them, unpublish or delete one.
+  // Runs anywhere: inside a project it can act on the site the project is synced to.
+  if (command === 'site') {
+    const { site } = await import('./commands/site.js')
+    const result = await site(args.slice(1))
+    // Its long list is where a bare exit was first caught cutting a pipe short — pinned by
+    // test/site-list-pipe.test.js; why every exit waits: utils/exit.js.
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle org command (new-backend orgs/units — publish-scope management)
+  if (command === 'org') {
+    const { org } = await import('./commands/org.js')
+    await org(args.slice(1))
+    return
+  }
+
+  // Handle invite command
+  if (command === 'invite') {
+    await invite(args.slice(1))
+    return
+  }
+
+  // Handle handoff command
+  if (command === 'handoff') {
+    await handoff(args.slice(1))
+    return
+  }
+
+  // Handle families command — the standard section families this CLI ships with
+  if (command === 'families') {
+    const { families } = await import('./commands/families.js')
+    await families(args.slice(1))
+    return
+  }
+
+  // Handle template command
+  if (command === 'template') {
+    const result = await template(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
+  }
+
+  // Handle create command
+  if (command !== 'create') {
+    error(`Unknown command: ${command}`)
+    showHelp()
+    await exitWhenDrained(1)
+  }
+
+  title('Uniweb Project Generator')
+
+  // Guard: prevent creating nested workspaces
+  const existingRoot = findWorkspaceRoot(process.cwd())
+  if (existingRoot) {
+    error(`Already inside a Uniweb workspace: ${existingRoot}`)
+    log(`\nTo add packages to this workspace, use:`)
+    log(`  ${colors.cyan}uniweb add foundation [name]${colors.reset}`)
+    log(`  ${colors.cyan}uniweb add site [name]${colors.reset}`)
+    log(
+      `  ${colors.cyan}uniweb add foundation --from <template>${colors.reset}\n`
+    )
+    await exitWhenDrained(1)
+  }
+
+  // Parse arguments
+  let projectName = args[1]
+  let templateType = null // null = use new package template flow
+
+  // In-place mode: `uniweb create .` scaffolds into the current working
+  // directory instead of creating a new one. Pairs with the GitHub-first
+  // workflow where the user already cloned an empty repo (README.md and
+  // optionally .gitignore present) and wants to scaffold inside it.
+  const inPlace = projectName === '.'
+  if (inPlace) {
+    // Clear the positional so downstream logic (template prompt, name
+    // prompt, etc.) doesn't see `.` as a literal name. The actual project
+    // name is derived below from the cwd basename or `--name`.
+    projectName = null
+  }
+
+  // Check for --template flag
+  const templateIndex = args.indexOf('--template')
+  if (templateIndex !== -1 && args[templateIndex + 1]) {
+    templateType = args[templateIndex + 1]
+    // Validate template identifier (will throw if invalid)
+    try {
+      parseTemplateId(templateType)
+    } catch (err) {
+      error(`Invalid template: ${err.message}`)
+      await exitWhenDrained(1)
+    }
+  }
+
+  // Check for --name flag. Accepts both `--name foo` and `--name=foo`.
+  let displayName = null
+  const nameIndex = args.indexOf('--name')
+  if (nameIndex !== -1 && args[nameIndex + 1]) {
+    displayName = args[nameIndex + 1]
+  } else {
+    const nameEq = args.find((a) => a.startsWith('--name='))
+    if (nameEq) displayName = nameEq.slice('--name='.length)
+  }
+
+  // Check for --blank flag
+  let isBlank = args.includes('--blank')
+
+  // Handle --template blank as alias for --blank
+  if (templateType === 'blank') {
+    isBlank = true
+    templateType = null
+  }
+
+  // Check for --no-git flag
+  const noGit = args.includes('--no-git')
+
+  // Skip positional name if it starts with -- (it's a flag, not a name)
+  if (projectName && projectName.startsWith('--')) {
+    projectName = null
+  }
+
+  const prefix = getCliPrefix()
+
+  // In-place: derive the project name from the cwd basename (slugified),
+  // or use --name when provided. Skip the interactive name prompt below.
+  if (inPlace) {
+    if (displayName) {
+      projectName = displayName
+    } else {
+      const dirName = basename(process.cwd())
+      const slug = slugifyName(dirName)
+      if (!slug) {
+        error(
+          `Could not derive a valid project name from the current directory ("${dirName}").`
+        )
+        log(`Re-run with ${colors.cyan}--name=<your-name>${colors.reset}.`)
+        await exitWhenDrained(1)
+      }
+      projectName = slug
+      if (slug !== dirName) {
+        log(
+          `${colors.dim}Project name:${colors.reset} ${slug} ${colors.dim}(slugified from "${dirName}")${colors.reset}`
+        )
+      } else {
+        log(`${colors.dim}Project name:${colors.reset} ${slug}`)
+      }
+    }
+  }
+
+  // Non-interactive: fail with actionable message instead of prompting
+  if (nonInteractive && !projectName) {
+    error(`Missing project name.\n`)
+    log(`Usage: ${prefix} create <project-name> [--template <name>] [--blank]`)
+    await exitWhenDrained(1)
+  }
+
+  // Non-interactive: default to starter when no template specified
+  if (nonInteractive && !templateType && !isBlank) {
+    templateType = 'starter'
+  }
+
+  // Interactive prompts (skipped in in-place mode — name was derived above)
+  const response = await prompts(
+    [
+      {
+        type: projectName ? null : 'text',
+        name: 'projectName',
+        message: 'Project name:',
+        initial: 'website',
+        validate: (value) => {
+          if (!value) return 'Project name is required'
+          if (!/^[a-z0-9-]+$/.test(value)) {
+            return 'Project name can only contain lowercase letters, numbers, and hyphens'
+          }
+          return true
+        }
+      }
+    ],
+    {
+      onCancel: () => {
+        log('\nScaffolding cancelled.')
+        process.exit(0) // a prompt: a terminal, so nothing to drain — and it must stop here, now
+      }
+    }
+  )
+
+  projectName = projectName || response.projectName
+
+  if (!projectName) {
+    error('Missing project name')
+    await exitWhenDrained(1)
+  }
+
+  // Prompt for template if not specified via --template or --blank
+  if (!templateType && !isBlank) {
+    const templateResponse = await prompts(
+      {
+        type: 'select',
+        name: 'template',
+        message: 'Template:',
+        choices: TEMPLATE_CHOICES,
+        initial: 1,
+        optionsPerPage: templatePickerPageSize(TEMPLATE_CHOICES.length)
+      },
+      {
+        onCancel: () => {
+          log('\nScaffolding cancelled.')
+          process.exit(0) // a prompt: a terminal, so nothing to drain — and it must stop here, now
+        }
+      }
+    )
+    templateType = templateResponse.template
+    // Handle "blank" selection from interactive prompt
+    if (templateType === 'blank') {
+      isBlank = true
+      templateType = null
+    }
+  }
+
+  const effectiveName = displayName || projectName
+
+  // Resolve target directory. In-place mode scaffolds into the cwd;
+  // otherwise create `./<projectName>`.
+  const projectDir = inPlace
+    ? process.cwd()
+    : resolve(process.cwd(), projectName)
+
+  if (!inPlace && existsSync(projectDir)) {
+    error(`Directory already exists: ${projectName}`)
+    await exitWhenDrained(1)
+  }
+
+  if (inPlace) {
+    // Conflict check: enumerate the workspace template's would-write paths
+    // (the only stage that touches the project root) and bail if any
+    // collide with existing files outside the small allowlist.
+    //
+    // Allowlist: README.md and .gitignore overwrite cleanly. README is
+    // typically GitHub-generated boilerplate; .gitignore should be ours
+    // since the scaffold ships sensible Vite/Node ignores.
+    const outputs = await getWorkspaceTemplateOutputs({ blank: isBlank })
+    const conflicts = []
+    for (const rel of outputs) {
+      const full = resolve(projectDir, rel)
+      if (existsSync(full) && !IN_PLACE_OVERWRITE_ALLOWED.has(rel)) {
+        conflicts.push(rel)
+      }
+    }
+    if (conflicts.length > 0) {
+      error(`Cannot scaffold in place — these files would be overwritten:`)
+      for (const c of conflicts) log(`  ${colors.yellow}${c}${colors.reset}`)
+      log('')
+      log(
+        `Move or remove them, then re-run ${colors.cyan}uniweb create .${colors.reset}.`
+      )
+      await exitWhenDrained(1)
+    }
+  }
+
+  // Template routing logic
+  const progressCb = (msg) => log(`  ${colors.dim}${msg}${colors.reset}`)
+  const warningCb = (msg) =>
+    log(`  ${colors.yellow}Warning: ${msg}${colors.reset}`)
+
+  if (isBlank) {
+    // Blank workspace (--blank or --template blank)
+    log('\nCreating blank workspace...')
+    await createBlankWorkspace(projectDir, effectiveName, {
+      onProgress: progressCb,
+      onWarning: warningCb
+    })
+  } else if (templateType === 'none') {
+    // Foundation + site with no content
+    log('\nCreating project...')
+    await createFromPackageTemplates(projectDir, effectiveName, {
+      onProgress: progressCb,
+      onWarning: warningCb,
+      pm,
+      includeStarter: false
+    })
+  } else if (templateType === 'starter') {
+    // Starter: foundation + site + sample content
+    log('\nCreating project...')
+    await createFromPackageTemplates(projectDir, effectiveName, {
+      onProgress: progressCb,
+      onWarning: warningCb,
+      pm
+    })
+  } else {
+    // External: official/npm/github/local
+    log(`\nResolving template: ${templateType}...`)
+
+    try {
+      const resolved = await resolveTemplate(templateType, {
+        onProgress: progressCb
+      })
+
+      log(
+        `\nCreating project from ${resolved.name || resolved.package || `${resolved.owner}/${resolved.repo}`}...`
+      )
+
+      // Validate and apply as format 2 content template
+      const metadata = await validateTemplate(resolved.path)
+
+      try {
+        await createFromContentTemplate(
+          projectDir,
+          effectiveName,
+          metadata,
+          resolved.path,
+          {
+            onProgress: progressCb,
+            onWarning: warningCb,
+            pm
+          }
+        )
+      } finally {
+        if (resolved.cleanup) await resolved.cleanup()
+      }
+    } catch (err) {
+      error(`Failed to apply template: ${err.message}`)
+      log('')
+      log(`${colors.yellow}Troubleshooting:${colors.reset}`)
+      log(`  • Check your network connection`)
+      log(
+        `  • Official templates require GitHub access (may be blocked by corporate networks)`
+      )
+      log(
+        `  • Try the starter template instead: ${colors.cyan}uniweb create ${projectName} --template starter${colors.reset}`
+      )
+      await exitWhenDrained(1)
+    }
+  }
+
+  // Initialize git repository
+  if (!noGit) {
+    // Skip git init if already inside a git repo (common for monorepos/workspaces)
+    let insideGitRepo = false
+    try {
+      execSync('git rev-parse --is-inside-work-tree', {
+        cwd: projectDir,
+        stdio: 'ignore'
+      })
+      insideGitRepo = true
+    } catch {
+      // Not inside a git repo — proceed with init
+    }
+
+    if (insideGitRepo) {
+      log(
+        `  ${colors.dim}Skipping git init — already inside a git repository${colors.reset}`
+      )
+    } else {
+      try {
+        execSync('git --version', { stdio: 'ignore' })
+        try {
+          execSync('git init', { cwd: projectDir, stdio: 'ignore' })
+          execSync('git add -A', { cwd: projectDir, stdio: 'ignore' })
+          execSync('git commit -m "Initial commit from uniweb"', {
+            cwd: projectDir,
+            stdio: 'ignore'
+          })
+          success('Git repository initialized')
+        } catch {
+          log(
+            `  ${colors.yellow}Warning: Git repository initialized but initial commit failed${colors.reset}`
+          )
+          log(
+            `  ${colors.dim}Run 'git commit -m "Initial commit"' after configuring git${colors.reset}`
+          )
+        }
+      } catch {
+        // git not available — skip silently
+      }
+    }
+  }
+
+  // Success message
+  title('Project created successfully!')
+
+  // Recommend pnpm (the framework's package manager) when it's installed,
+  // otherwise fall back to however the user invoked the CLI. The scaffold
+  // supports both — the root package.json declares npm `workspaces` and a
+  // pnpm-workspace.yaml ships next to it.
+  const recPm = isPnpmAvailable() ? 'pnpm' : pm
+
+  if (isBlank) {
+    log(`Next steps:\n`)
+    if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} add project${colors.reset}`)
+    log(`  ${colors.cyan}${installCmd(recPm)}${colors.reset}`)
+    log(
+      `  ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset}   ${colors.dim}# start the dev server${colors.reset}`
+    )
+  } else {
+    log(`Next steps:\n`)
+    if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
+    log(`  ${colors.cyan}${installCmd(recPm)}${colors.reset}`)
+    log(
+      `  ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset}   ${colors.dim}# start the dev server${colors.reset}`
+    )
+  }
+  if (recPm !== 'pnpm') {
+    log('')
+    log(
+      `  ${colors.dim}Tip: pnpm is recommended (https://pnpm.io) — npm works too.${colors.reset}`
+    )
+  }
+  log('')
+  log(
+    `  ${colors.dim}See ${colors.reset}${colors.cyan}${prefix} <command> --help${colors.reset}${colors.dim} for command-specific options.${colors.reset}`
+  )
+  log('')
+
+  await showUpdateNotification()
+}
+
+/**
+ * Print help for a specific command. Returns true if a dedicated help
+ * block exists for the command, false to signal "fall back to global
+ * help."
+ *
+ * Help text intentionally lives next to the dispatcher rather than in
+ * the per-command files because most help-seekers haven't run that
+ * command yet — keeping it here means `uniweb foo --help` prints
+ * without loading @uniweb/build or any project context.
+ */
+function printCommandHelp(command) {
+  // `release` is a synonym of `register` (shipping-model.md §6.1) — show the
+  // same help block.
+  if (command === 'release') command = 'register'
+  const blocks = {
+    deploy: `
+${colors.cyan}${colors.bright}uniweb deploy${colors.reset} ${colors.dim}— Ship a site to a host${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb deploy [options]
+
+With no destination configured, opens the WIZARD — "Where should this site go?" —
+and only offers destinations that can actually be acted on. Pick a host and it
+asks whether to set up CI (every push deploys) or upload from this machine now.
+Your answer is remembered in deploy.yml, so later runs go straight there.
+
+Choosing ${colors.bright}Uniweb Cloud${colors.reset} delegates to ${colors.cyan}uniweb publish${colors.reset} (sync + dynamic serving;
+brings the foundation along). Choosing ${colors.bright}Somewhere else${colors.reset} runs ${colors.cyan}uniweb export${colors.reset}.
+
+${colors.bright}Hosts:${colors.reset}
+  github-pages        GitHub Pages — CI workflow, or commit dist/ to gh-pages
+  cloudflare-pages    Cloudflare Pages — CI workflow + PR previews, or wrangler
+  netlify             Netlify — CI workflow + PR previews, or the netlify CLI
+  vercel              Vercel — CI workflow + PR previews, or the vercel CLI
+  s3-cloudfront       AWS S3 + CloudFront — uploads + invalidates via the aws CLI
+  uniweb              Uniweb Cloud (delegates to \`uniweb publish\`)
+
+${colors.bright}Options:${colors.reset}
+  --host <name>       The host to ship to (no value → the wizard, TTY only)
+  --target <name>     Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --dry-run           Resolve the target + adapter; print summary; upload nothing
+  --no-save           Do not record this deploy in deploy.yml
+  --no-validate       Skip the content-conformance check (a static host warns;
+                      Uniweb Cloud stops on content that does not conform)
+  --non-interactive   Fail with usage info instead of prompting
+
+${colors.bright}Examples:${colors.reset}
+  uniweb deploy                              # Wizard: pick a destination
+  uniweb deploy --host=cloudflare-pages      # Build + upload via wrangler
+  uniweb deploy --host=s3-cloudfront         # Build + upload + invalidate
+  uniweb deploy --host=uniweb                # → delegates to \`uniweb publish\`
+  uniweb deploy --target=preview             # Named target from deploy.yml
+
+${colors.dim}To deploy on every push instead, see \`uniweb add ci --help\`.${colors.reset}
+`,
+    publish: `
+${colors.cyan}${colors.bright}uniweb publish${colors.reset} ${colors.dim}— Publish a site to Uniweb hosting (the smart path)${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb publish [options]
+
+The most ergonomic command in the tool: \`uniweb login && uniweb publish\` reads
+your project and makes the site live on Uniweb hosting. It resolves which site,
+BRINGS THE FOUNDATION ALONG (releases the local foundation when its code
+changed — under the next version when its own is registered; commit the
+package.json it writes), syncs content, settles payment when go-live needs it
+(a browser handoff), and goes live. A published-registry foundation needs no
+release; an already-paid site opens no browser.
+
+For a third-party host use \`uniweb deploy --host=<name>\`; to register a
+FOUNDATION on its own use \`uniweb register\` (alias \`uniweb release\`).
+
+${colors.bright}Options:${colors.reset}
+  --dry-run          Resolve everything; release/sync/POST nothing
+  --yes              Skip confirmations (CI); never block on a prompt
+  --no-release       Ship the content against the code already released; release
+                     nothing. For editing content and a component in one sitting
+                     when only the content should go live. Refused if the
+                     foundation has never been released — there is nothing to
+                     bind to, and the app cannot open such a site.
+  --bump             When the registry holds a newer version of the foundation
+                     than yours, release yours above it instead of stopping
+  --no-save          Do not record this deploy in deploy.yml
+  --no-validate      Skip the content-conformance check, which stops a publish
+                     whose content does not conform to its data schemas
+  --org @org         Work in @org for this publish, instead of the workspace
+  --personal         chosen at \`uniweb login\` (or your personal workspace). A
+                     site this publish creates is created — owned — there, and a
+                     site the backend keeps in another workspace stops it.
+`,
+    create: `
+${colors.cyan}${colors.bright}uniweb create${colors.reset} ${colors.dim}— Create a new project${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb create [name] [options]
+  uniweb create .                Scaffold into the current directory
+
+${colors.bright}Options:${colors.reset}
+  --template <type>  Project template (default: starter)
+                     Built-in: starter, none, blank
+                     Official: marketing, docs, … (\`uniweb template list\`)
+                     Local:    ./path/to/template
+                     npm:      @scope/template-name
+                     GitHub:   github:user/repo or https://github.com/user/repo
+  --blank            Create an empty workspace (grow with \`uniweb add\`)
+  --name <name>      Project name (overrides slugified basename when used with \`.\`)
+  --no-git           Skip git repository initialization
+
+${colors.bright}In-place mode (\`uniweb create .\`):${colors.reset}
+  Pairs with the GitHub-first workflow — clone an empty repo locally
+  (README, optional .gitignore), then scaffold inside it. Project name
+  is the cwd basename, slugified to a valid npm name. Pass \`--name\` to
+  override. Pre-existing \`README.md\` and \`.gitignore\` are overwritten;
+  any other collision aborts with the list of conflicting files. Skips
+  \`git init\` when a \`.git/\` directory already exists.
+
+${colors.bright}Examples:${colors.reset}
+  uniweb create my-project                       # Foundation + site + starter content
+  uniweb create my-project --template marketing  # Official template
+  uniweb create my-project --blank               # Empty workspace
+  uniweb create .                                # Scaffold into current dir
+  uniweb create . --template docs                # In place + a content template
+  uniweb create . --name=my-app                  # In place, explicit slug
+`,
+    dev: `
+${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb dev                  Start dev server for the (single) site
+  uniweb dev <site>           Start dev server for a specific site
+  uniweb dev --site <name>    Same, with explicit flag form
+
+Thin wrapper around the package manager's workspace-filtered \`dev\`
+script (\`pnpm --filter <site> dev\` or \`npm -w <site> run dev\`). Picks
+the single site automatically; for multi-site workspaces the first
+site runs by default with a notice pointing at \`--site\` for explicit
+selection.
+`,
+    snapshot: `
+${colors.cyan}${colors.bright}uniweb snapshot${colors.reset} ${colors.dim}— Compose a preview image of a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb snapshot [<site>] [options]
+  uniweb snapshot --compare [options]
+
+Opens the site in a headless Chrome, captures it, and composes the captures into
+one image: by default ${colors.bright}site/public/preview.webp${colors.reset}, recorded as ${colors.cyan}preview:${colors.reset} in site.yml
+when site.yml has none, or only the app's generated one. A URL or image path you
+wrote is never replaced.
+
+A page that scrolls gets the ${colors.bright}split${colors.reset} layout: the first view in a browser window,
+beside a long strip of the page. A page that does not scroll as a page (a docs
+shell, an app) gets ${colors.bright}device${colors.reset}: a desktop window and a phone.
+
+Needs ${colors.cyan}@uniweb/snapshot${colors.reset} in the workspace (\`pnpm add -D -w @uniweb/snapshot\`) and
+Google Chrome, Microsoft Edge, or a Chromium named by $UNIWEB_SNAPSHOT_BROWSER.
+
+${colors.bright}Where the site comes from:${colors.reset}
+  (default)           Build the site, then capture dist/
+  --no-build          Capture the existing dist/ as is
+  --dev               Capture the site's Vite dev server (no build)
+  --url <address>     Capture a site that is already running
+
+${colors.bright}The look:${colors.reset}
+  --layout <name>     auto (default), split, device
+  --gap <px>          Space between the two frames (split default: 48)
+  --overlap <px>      Overlap them instead (device default: 31)
+  --strip <width>     split: fit (default), or 1:N — narrower shows more of a long page
+  --side <side>       Where the strip or phone goes: right (default), left
+  --frame <style>     browser (default, with a title bar), plain
+  --tone <name>       Background: auto (default), light, deep
+
+${colors.bright}Choosing and keeping a look:${colors.reset}
+  --compare           One capture, several looks on one sheet, each captioned with
+                      its flags (site/.uniweb/snapshot/compare.webp)
+  --save              Keep this run's flags in site/snapshot.yml, the site's defaults
+
+${colors.bright}Options:${colors.reset}
+  --site <name>       The site (default: the one you are in, or the only one)
+  --route <path>      The page to capture (default: the home page)
+  --size <WxH>        Image size in CSS pixels (default: 1600x1000)
+  --scale <n>         1 (default) or 2 for a double-density image
+  --quality <n>       Encoder quality, 1–100 (default: 82)
+  --out <file>        Where to write it; .webp, .png, .jpg or .avif
+  --hide <selector>   Hide matching elements before capturing (repeatable)
+  --no-set-preview    Write the image without touching site.yml
+`,
+    build: `
+${colors.cyan}${colors.bright}uniweb build${colors.reset} ${colors.dim}— Build the current project${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb build [options]
+
+At workspace root, builds all foundations first, then all sites.
+Pre-rendering is enabled by default when build.prerender: true in site.yml.
+
+${colors.bright}Options:${colors.reset}
+  --target <type>    Build target (foundation, site) — auto-detected if not specified
+  --prerender        Force pre-rendering (overrides site.yml)
+  --no-prerender     Skip pre-rendering (overrides site.yml)
+  --foundation-dir   Path to foundation directory (for prerendering)
+  --host <name>      Apply host-specific postBuild (e.g., cloudflare-pages emits _redirects)
+  --platform <name>  (Deprecated alias for --host)
+`,
+    add: `
+${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
+
+Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
+
+${colors.bright}Usage:${colors.reset}
+  uniweb add project [name] [options]
+  uniweb add foundation [name] [options]
+  uniweb add site [name] [options]
+  uniweb add extension <name> [options]
+  uniweb add section <name> [options]
+  uniweb add ci [options]
+
+${colors.bright}Common Options:${colors.reset}
+  --from <template>  Apply content from a template after scaffolding
+  --path <dir>       The folder to put the package in
+  --non-interactive  Fail with usage info instead of prompting
+
+${colors.bright}Foundation Options:${colors.reset}
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Site Options:${colors.reset}
+  --foundation <n>   Foundation to wire to (prompted if multiple exist)
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Extension Options:${colors.reset}
+  --site <name>      Site to wire extension URL into
+
+${colors.bright}Section Options:${colors.reset}
+  --foundation <n>   Foundation to add section to (prompted if multiple exist)
+  --starter          Generate starter content from the section's \`content:\`
+                     declaration — what an author would begin editing. Works on
+                     a section that already exists (nothing is written), and on
+                     a new one (the scaffold gets a matching declaration)
+  --preset <name>    Frontmatter the starter content with this preset's params
+  --write <file>     Write the starter markdown to a file instead of printing it
+  --json             Emit the content structure and ProseMirror doc instead
+
+${colors.bright}CI Options:${colors.reset}
+  --host <name>          github-pages | cloudflare-pages | netlify | vercel
+                         (prompted when omitted)
+  --target <what>        site (default) | foundation
+                         'foundation' publishes built foundations at permanent
+                         versioned URLs — the free alternative to the catalog
+  --site <name>          Site the workflow builds (prompted if multiple exist)
+  --foundation <name>    With --target foundation: publish just this one
+  --domain <host>        Custom domain (GitHub Pages: writes CNAME, serves at root)
+  --project-name <name>  Name to register under on the host (default: the
+                         workspace name; Cloudflare Pages project, etc.)
+  --no-previews          Skip the per-PR preview workflow
+  --force                Overwrite an existing workflow file
+
+${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
+GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
+
+${colors.bright}Examples:${colors.reset}
+  uniweb add project docs                              # Create docs/src/ + docs/site/
+  uniweb add project docs --from academic              # Co-located pair + academic content
+  uniweb add foundation                                # Create ./src/ at root
+  uniweb add foundation ui                             # Create ./ui/ — the folder you name
+  uniweb add foundation foundations/ui                 # Create ./foundations/ui/
+  uniweb add site                                      # Create ./site/ at root
+  uniweb add site blog --foundation marketing          # Create ./blog/ wired to marketing
+  uniweb add extension effects --site site             # Create ./effects/ — the folder you name
+  uniweb add extension extensions/effects              # Create ./extensions/effects/
+  uniweb add section Hero                              # Create Hero section type
+  uniweb add section Hero --foundation ui              # Target specific foundation
+  uniweb add section Hero --starter                    # Starter content for an existing Hero
+  uniweb add section Pricing --starter                 # Scaffold Pricing + content that fills it
+  uniweb add section Hero --starter --preset split     # Frontmatter it with the 'split' preset
+  uniweb add section Hero --starter --json             # The structure + ProseMirror, for a script
+  uniweb add foundation --project docs                 # Create ./docs/src/ (co-located)
+  uniweb add site --project docs                       # Create ./docs/site/ (co-located)
+  uniweb add ci                                        # Pick a host, add a deploy workflow
+  uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
+  uniweb add ci --host netlify                         # Deploy + PR-preview workflows
+  uniweb add ci --host vercel --no-previews            # Deploy workflow only
+  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
+  uniweb add ci --target foundation                    # Publish foundations at versioned URLs
+`,
+    export: `
+${colors.cyan}${colors.bright}uniweb export${colors.reset} ${colors.dim}— Export a self-contained site for third-party hosting${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb export [options]
+
+Builds dist/ and prints upload examples for common static hosts. No login,
+no deploy step — you push the artifact to your host of choice yourself.
+For Uniweb-hosted sites, use \`uniweb deploy\`.
+
+${colors.bright}Options:${colors.reset}
+  --no-prerender     Skip per-page prerendered HTML
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, github-pages, …)
+`,
+    doctor: `
+${colors.cyan}${colors.bright}uniweb doctor${colors.reset} ${colors.dim}— Diagnose project configuration issues${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb doctor [options]
+
+${colors.bright}Options:${colors.reset}
+  --fix              Apply fixes for safely-fixable issues
+  --fix <issue-id>   Apply fix for a specific issue id only
+  --non-interactive  Fail with usage info instead of prompting
+
+Exit code is 1 if errors are found (warnings only → exit 0).
+`,
+    validate: `
+${colors.cyan}${colors.bright}uniweb validate${colors.reset} ${colors.dim}— Check your content against your foundation's data schemas${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb validate [path] [options]
+
+Checks each section's file-based data inputs against the schema your
+foundation declared for that input (meta.js \`data:\`). Answers "does my
+data match what I promised?" — distinct from \`doctor\`, which checks your
+project against framework conventions.
+
+Every record file is checked against the schema its folder names, whether or
+not a section reads it. A violation fails the run; \`push\` and \`publish\` refuse
+the same findings. The live render path stays tolerant. Remote (\`url:\`)
+inputs are not in the project, so they're reported as deferred, never silently
+skipped. A reference field's value is not checked against the entity it names.
+
+${colors.bright}Options:${colors.reset}
+  --lax              Report violations without failing (exit 0)
+  --json             Machine-readable output (for CI annotations)
+  --site <name>      Check one site in a multi-site workspace
+
+Exit codes: 0 clean (or --lax), 1 violations, 2 setup error.
+`,
+    register: `
+${colors.cyan}${colors.bright}uniweb register${colors.reset} ${colors.dim}— Register (release) a foundation + its data schemas with the backend registry${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb register [options]
+  uniweb release  [options]      ${colors.dim}(synonym — reads naturally for updates)${colors.reset}
+
+Builds one \`.uwx\` document and submits it to the registry over HTTP. Run
+\`uniweb login\` first. \`register\`/\`release\` are for
+FOUNDATIONS (and schemas) — code only; \`uniweb publish\` makes a synced SITE
+live (and brings its foundation along); \`uniweb deploy\` hosts on a third-party
+host. \`register\` and \`release\` are the same act: \`register\` reads naturally
+the first time, \`release\` for updates.
+
+Auto-detects what you run it in:
+  • a foundation        the foundation + the data schemas it defines/renders
+  • a schemas-only pkg   just its data schemas, no foundation — e.g. @uniweb/schemas,
+                         any @org/schemas package, or a bare schemas/*.yml folder
+
+A foundation's scope is part of its name — name: '@scope/<name>' in main.js. A scope
+is a namespace: your personal one (@<your handle>, no org needed) or an org's. A bare
+name takes --scope, else the workspace you work in (an org's scope, or your personal
+one), and register writes it into the name.
+
+Schema scopes:
+  @/name     your own schema, in the foundation's scope   (@/x -> @org/x)
+  @std/name  a shared standard schema (from @uniweb/schemas)
+  @org/name  another org's published schema, referenced by name
+
+${colors.bright}Options:${colors.reset}
+  --scope @scope     A foundation with a bare name: register under @scope — yours or an
+                     org's — and write it into the name (refused when the name has another
+                     scope). A schemas-only package: publish under @scope; default:
+                     package.json uniweb.scope
+  --org @org         Work in @org for this command: a bare name registers under it
+  --personal         Work in your personal workspace: a bare name registers under your
+                     personal scope
+  --dry-run          Print the .uwx; submit nothing
+  -o, --output <f>   Write the .uwx to a file; submit nothing
+  --non-interactive  Fail with usage info instead of prompting
+
+Run from a foundation, a schemas-only package, or a workspace with a single foundation.
+`,
+    rename: `
+${colors.cyan}${colors.bright}uniweb rename${colors.reset} ${colors.dim}— Rename a workspace package${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb rename foundation <old> <new>
+  uniweb rename site <old> <new>
+  uniweb rename extension <old> <new>
+
+Each subcommand updates a different set of touch points:
+
+  foundation: package.json::name + folder + every dependent site's
+    package.json (dep key + file: path) + every site.yml::foundation +
+    pnpm-workspace.yaml / package.json::workspaces + root scripts.
+
+  site: package.json::name + folder + workspace manifests + root
+    scripts (\`dev\` / \`preview\` are filtered by site name).
+
+  extension: package.json::name + folder + every site.yml::extensions
+    URL whose path matches the old folder + workspace manifests.
+    (Sites don't carry a \`file:\` dep on extensions — they load by
+    URL at runtime, so no per-site package.json updates.)
+
+Transactional — bails on conflict (target name taken, target not found,
+folder collision, type mismatch) before any filesystem mutation.
+
+Type guards: \`rename foundation\` against an extension errors and
+points at \`rename extension\` (and vice versa). They share a build
+shape but the touch-point sets differ; using the wrong subcommand
+would update the wrong things.
+`,
+    login: `
+${colors.cyan}${colors.bright}uniweb login${colors.reset} ${colors.dim}— Log in to your Uniweb account${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb login [options]
+
+Authenticates with a backend and stores its session in
+~/.uniweb/registry-auth.json. ${colors.bright}One backend at a time:${colors.reset} logging in to another one
+logs you out of the first (once the new login succeeds). The backend you are
+logged in to is where the backend commands go (push, pull, publish, status,
+register, clone) — so this is how you switch. Already logged in to it, login
+does nothing; add --password, --browser, --token-paste or --token to log in again.
+
+Without --server: https://uniweb.app (or \$UNIWEB_SERVER). No command talks
+to a backend you are not logged in to — run one before logging in and it asks first.
+
+${colors.bright}The workspace you work in.${colors.reset} A login works in ONE workspace — your
+personal one, or an organization's — and every push, pull and publish works in it:
+a site it creates is created there, and a site kept in another workspace is refused.
+With no organization it is your personal workspace; with organizations you are asked,
+or name it. Already logged in, \`uniweb login --org @other\` (or \`--personal\`) switches
+the workspace on the backend you are logged in to, without logging in again.
+
+${colors.bright}Options:${colors.reset}
+  --server <url>    The backend to log in to (without it: the default backend — or, for
+                     --org / --personal alone, the one you are logged in to)
+  --org @org         Work in @org (an organization you belong to)
+  --personal         Work in your personal workspace
+  --token <bearer>   Seed + verify a session from a bearer token (non-interactive)
+  --browser          Force the browser method
+  --password         Force the username/password method
+  --token-paste      Force the paste-a-token prompt
+
+In non-interactive mode (no TTY — an agent, a script), pass \`--token <bearer>\` with
+\`--org @org\` or \`--personal\`, or set \`UNIWEB_USERNAME\` + \`UNIWEB_PASSWORD\`.
+A login with organizations that names no workspace signs you in but exits 2;
+\`uniweb login --org @org\` (or \`--personal\`) finishes it without signing in again.
+\`uniweb logout\` logs you out.
+
+${colors.bright}Or skip the login.${colors.reset} With \`UNIWEB_TOKEN\` set — and \`UNIWEB_WORKSPACE=@org\` or
+\`personal\` — every backend command in that process uses the token, ahead of any
+session, and nothing is stored. \`uniweb login\` there only checks the token with the
+backend those commands go to — \`UNIWEB_SERVER\`, else the one you are logged in to,
+else the default — and says who and where they work as.
+`,
+    refresh: `
+${colors.cyan}${colors.bright}uniweb refresh${colors.reset} ${colors.dim}— Catch up with teammates AND app authors${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb refresh [options]
+
+A developer on a synced site has TWO external sources: the git remote (teammates'
+commits) and the backend (content authors' edits in the app). Run only \`git pull\`
+and you miss every app edit; run only \`uniweb pull\` and you miss your teammates.
+This does both — git first, then \`pull --merge\`.
+
+${colors.bright}READ-ONLY.${colors.reset} It never pushes and cannot ship anything, so it is safe to run
+reflexively. Exits non-zero if a merge leaves conflicts.
+
+${colors.bright}Options:${colors.reset}
+  --no-git           Skip the git remote; backend only
+  --no-backend       Skip the backend; git only
+
+\`--force\` and \`--merge\` are NOT accepted here: this verb builds the delegated
+pull's arguments itself, and to pull \`--force\` means "discard my local work".
+Use \`uniweb sync\` when you also mean to share.
+`,
+    sync: `
+${colors.cyan}${colors.bright}uniweb sync${colors.reset} ${colors.dim}— Catch up, then share${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb sync [options]
+
+\`uniweb refresh\` followed by \`uniweb push\`, and nothing more. It adds no
+guarantees of its own — refresh stops on conflicts, push refuses when the backend
+has moved under you, and sync inherits both. \`uniweb refresh && uniweb push\`
+behaves identically.
+
+${colors.bright}It does NOT publish.${colors.reset} Sync brings your copy and the backend DRAFT into
+agreement; going live stays a separate act (\`uniweb publish\`). So the worst case
+of an unintended sync is work-in-progress visible to authors, not shipped to
+visitors.
+
+${colors.bright}Options:${colors.reset}
+  Accepts every option of both halves — see \`uniweb refresh --help\` and the push
+  options in \`uniweb --help\`. The common ones:
+
+  --no-git           Skip the git remote half of the refresh
+  --force            Overwrite upstream changes (reaches the PUSH half only)
+
+\`--force\` means "overwrite upstream" to push but "discard my local work" to pull,
+so it is deliberately kept away from the refresh half.
+`,
+    forget: `
+${colors.cyan}${colors.bright}uniweb forget${colors.reset} ${colors.dim}— Remove what this project recorded about where it synced${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb forget --server <url>
+  uniweb forget --all
+
+Local files only. Every site stays where it is on its backend.
+
+${colors.bright}Options:${colors.reset}
+  --server <url>    Forget one backend: its entries in sync.json and in the local
+                     cache, and its deploy records in deploy.yml. Its targets stay,
+                     so the next publish there creates a new site.
+  --all              For a COPY of a project that should become a new one. Deletes
+                     sync.json, deploy.yml and the local cache — everything naming
+                     the original's sites and destinations. Without it, the copy's
+                     first push updates the original's site.
+
+Record files keep their \`$uuid\`: it is the record's own id, not a backend's.
+
+To duplicate a project:
+  cp -r my-site my-site-2 && cd my-site-2 && uniweb forget --all
+`,
+    invite: `
+${colors.cyan}${colors.bright}uniweb invite${colors.reset} ${colors.dim}— (reserved; not available on the new backend yet)${colors.reset}
+
+The foundation client-invite flow was retired with the legacy backend.
+Invite clients to your foundation from the Uniweb app for now.
+`,
+    handoff: `
+${colors.cyan}${colors.bright}uniweb handoff${colors.reset} ${colors.dim}— (reserved; not available on the new backend yet)${colors.reset}
+
+The site-handoff flow was retired with the legacy backend.
+Manage client sites from the Uniweb app for now.
+`,
+    families: `
+${colors.cyan}${colors.bright}uniweb families${colors.reset} ${colors.dim}— The standard section families${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb families                List them, grouped
+  uniweb families <filter>       Match an id, a label or a group name
+  uniweb families --json         Machine-readable (for scripts)
+
+${colors.bright}What a family is for:${colors.reset}
+  It tells an editor which illustration to show for a section type, and gives
+  it a label it can translate. Declare it in a section's meta.js:
+
+    ${colors.dim}export default { title: 'Researcher Profile', family: 'profile' }${colors.reset}
+
+  ${colors.bright}Most components need no declaration.${colors.reset} The section type IS the component
+  name, so \`Hero\`, \`Footer\` and \`Pricing\` already resolve. \`family:\` is for the
+  ones whose name does not give it away — \`ProfileHero\`, \`CvEntry\`.
+
+  An unrecognized value is legal: it falls back to a generic illustration and
+  nothing breaks, so a foundation with its own vocabulary is never blocked.
+
+  \`uniweb doctor\` reports what each of your sections resolved to, and suggests
+  a family for the ones it recognizes by another name.
+
+${colors.bright}Note:${colors.reset} this is the roster ${colors.bright}this CLI ships with${colors.reset}, not a live fetch — and it is
+  the same list \`doctor\` matches against.
+`,
+    template: `
+${colors.cyan}${colors.bright}uniweb template${colors.reset} ${colors.dim}— Official templates${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb template list           List the official templates
+  uniweb template list --json    Same, machine-readable (for scripts)
+
+${colors.bright}What \`list\` reports:${colors.reset}
+  The roster ${colors.bright}this CLI ships with${colors.reset} — a snapshot baked in at publish time,
+  not a live fetch. \`create\` downloads these templates from the release the same
+  snapshot names, which is why \`--json\` stamps \`cliVersion\`. A template newer than
+  your CLI is not listed: \`npx uniweb@latest template list\` shows the current roster.
+
+  It is the ${colors.bright}official${colors.reset} roster, not the set of resolvable names: an unknown
+  name is not fatal, since \`create\` falls through to npm \`@uniweb/template-<name>\`.
+`,
+    docs: `
+${colors.cyan}${colors.bright}uniweb docs${colors.reset} ${colors.dim}— Generate component documentation${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  docs               Generate COMPONENTS.md from foundation schema
+  docs site          Show site.yml configuration reference
+  docs page          Show page.yml configuration reference
+  docs meta          Show component meta.js reference
+
+${colors.bright}Options:${colors.reset}
+  --output <file>    Output filename (default: COMPONENTS.md)
+  --from-source      Read meta.js files directly instead of schema.json
+`,
+    i18n: `
+${colors.cyan}${colors.bright}uniweb i18n${colors.reset} ${colors.dim}— Internationalization workflow${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  i18n extract       Extract translatable strings to manifest
+  i18n sync          Update manifest with content changes
+  i18n status        Show translation coverage per locale
+`,
+    inspect: `
+${colors.cyan}${colors.bright}uniweb inspect${colors.reset} ${colors.dim}— Inspect parsed content shape${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb inspect <path>
+
+Prints the parsed content shape of a markdown file or folder — the
+{ content, params, items, … } object that components actually receive.
+Useful for debugging "why isn't my section getting X?".
+`,
+    update: `
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Align this project with the running CLI${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb update                     Align deps + refresh AGENTS.md
+  uniweb update --deps-only         Only align workspace @uniweb/* deps
+  uniweb update --agents-only       Only refresh AGENTS.md
+  uniweb update --no-deps           Skip the deps-alignment step
+  uniweb update --no-agents         Skip the AGENTS.md step
+  uniweb update --dry-run           Print survey + would-be writes; no mutations
+  uniweb update --allow-mismatch    Refresh AGENTS.md even if declared deps lag
+  uniweb update --yes               Don't prompt — apply edits and run the install
+
+${colors.bright}What it does:${colors.reset}
+  Prints a version survey first (CLI version, AGENTS.md stamp, every
+  @uniweb/* + uniweb dep declared in workspace package.json files,
+  marked aligned / behind / ahead). Then two steps:
+
+  1. ${colors.bright}Align workspace deps${colors.reset} to this CLI's bundled version matrix —
+     rewrites the @uniweb/* + uniweb keys in each package.json that lags
+     (deps ahead of the matrix are left alone — never downgraded;
+     existing indentation is preserved), then offers to run the
+     workspace's package manager (lockfile-detected: pnpm-lock.yaml →
+     pnpm, yarn.lock → yarn, package-lock.json → npm). If the install
+     fails, the package.json edits are kept and a revert command printed.
+  2. ${colors.bright}Refresh AGENTS.md${colors.reset} from this CLI's bundled partial. Won't run
+     if deps were edited but not installed (node_modules would be behind
+     package.json), or while declared deps still lag the CLI (would
+     document features not in your packages) — pass --allow-mismatch for
+     the latter.
+
+${colors.bright}Which matrix?${colors.reset}
+  \`update\` pins to the version matrix *this* CLI shipped with — not
+  necessarily the latest release. To reconcile against the latest release
+  without touching a global install, run \`npx uniweb@latest update\`. This
+  command does NOT update the CLI itself; use your package manager
+  (\`npm i -g uniweb@latest\`, \`pnpm add -g uniweb@latest\`, …).
+
+${colors.bright}Project-local installs:${colors.reset}
+  When run from a project-local CLI (in node_modules), it aligns the
+  project to that pinned version — bump \`uniweb\` in package.json (or use
+  \`npx uniweb@latest update\`) to align to something newer.
+`
+  }
+
+  if (!blocks[command]) return false
+  log(blocks[command])
+  return true
+}
+
+function showHelp() {
+  log(`
+${colors.cyan}${colors.bright}Uniweb CLI${colors.reset} ${colors.dim}v${getCliVersion()}${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb <command> [options]
+
+${colors.bright}Commands:${colors.reset}
+  create [name]      Create a new project
+  clone <site-uuid>  Clone a backend site into a local file project
+  add <type> [name]  Add a foundation, site, or extension to a project
+  rename <type>      Rename a foundation, site, or extension across the workspace
+  dev                Start a dev server for a site
+  build              Build the current project
+  snapshot           Compose a preview image of a site (its site.yml preview:)
+  publish            Publish a site to Uniweb hosting (smart: foundation + sync + go live)
+  deploy             Ship a site to a host (asks where, if not yet configured)
+  export             Export a self-contained site for third-party hosting
+  register           Register a foundation + its data schemas with the backend registry
+  release            Release a foundation version (synonym of register)
+  push               Push a site's content to the backend
+  pull               Pull a site's content from the backend
+  refresh            Catch up with the git remote AND the backend (never pushes)
+  sync               Catch up, then push (refresh + push)
+  status             Show a site's sync state (unpushed content, foundation)
+  forget             Forget a backend, or --all to make a copied project a new one
+  site <cmd>         The sites in a workspace: list, unpublish, delete
+  inspect <path>     Inspect parsed content shape of a markdown file or folder
+  docs               Generate component documentation
+  families           List the standard section families (for meta.js family:)
+  template list      List the official templates (for create --template)
+  doctor             Diagnose project configuration issues
+  validate           Check your content against your foundation's data schemas
+  update             Align workspace deps + AGENTS.md to the running CLI
+  i18n <cmd>         Internationalization (extract, sync, status)
+  login              Log in to your Uniweb account
+  logout             Log out of the backend you are logged in to
+
+${colors.bright}Create Options:${colors.reset}
+  --template <type>  Project template (default: starter)
+  --blank            Create an empty workspace (grow with uniweb add)
+  --name <name>      Project display name
+  --no-git           Skip git repository initialization
+
+${colors.bright}Add Subcommands:${colors.reset}
+  add project [name]      Add a co-located foundation + site pair
+  add foundation [name]   Add a foundation (--from, --path, --project)
+  add site [name]         Add a site (--from, --foundation, --path, --project)
+  add extension <name>    Add an extension (--from, --site, --path)
+  add section <name>      Add a section type to a foundation (--foundation, --starter)
+  add ci                  Add a CI workflow so every push deploys (--host, --target)
+
+${colors.bright}Global Options:${colors.reset}
+  --version, -v        Show version
+  --non-interactive    Fail with usage info instead of prompting
+                       Auto-detected when CI=true or no TTY (pipes, agents)
+
+  Backend commands (push, pull, publish, status, register, clone) go to the
+  backend you are logged in to, with its session. Switch with
+  \`uniweb login --server <url>\` (add \`--token <bearer>\` to sign in with a token);
+  a script can aim and authenticate one process with UNIWEB_SERVER and
+  UNIWEB_TOKEN instead.
+
+${colors.bright}Push Options:${colors.reset}
+  --dry-run          Report what would be pushed; send nothing (-o <file> writes the .uwx)
+  --no-release       Send content against the already-released code; release nothing
+  --bump             Release above a newer registered foundation version
+  --force            Overwrite upstream changes (drop the staleness gate)
+  --all              Send every record (bypass the changed-only cache)
+  --org @org         Work in @org for this push, not your login's workspace
+  --personal         Work in your personal workspace for this push
+  --no-validate      Skip the content-conformance check (it stops a push)
+
+${colors.bright}Publish Options:${colors.reset}
+  --dry-run          Resolve everything; release/sync/POST nothing
+  --yes              Skip confirmations (CI); never block on a prompt
+  --no-release       Ship content against the already-released code; release nothing
+  --bump             Release above a newer registered foundation version
+  --org @org         Work in @org for this publish, not your login's workspace
+  --personal         Work in your personal workspace for this publish
+  --no-save          Do not record this deploy in deploy.yml
+  --no-validate      Skip the content-conformance check (it stops a publish)
+
+  uniweb publish is the smart Uniweb-hosting path: it brings the site's
+  foundation along, syncs, and goes live. To register a foundation on its own
+  use \`uniweb register\` (alias \`uniweb release\`); for a third-party host use
+  \`uniweb deploy --host=<name>\`.
+
+${colors.bright}Deploy Options:${colors.reset}
+  --host <name>      The host to ship to. Omit it (TTY) to open the wizard:
+                     github-pages, cloudflare-pages, netlify, vercel,
+                     s3-cloudfront, or \`uniweb\` (delegates to \`uniweb publish\`).
+  --target <name>    Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --dry-run          Resolve the target + adapter; print summary; upload nothing
+  --no-save          Do not record this deploy in deploy.yml
+  --no-validate      Skip the content-conformance check (a static host warns)
+  To deploy on every push instead, see \`uniweb add ci --help\`.
+
+${colors.bright}Dev Options:${colors.reset}
+  <site>             Site name to run (positional)
+  --site <name>      Site name to run (explicit form)
+
+${colors.bright}Export Options:${colors.reset}
+  --no-prerender     Skip per-page prerendered HTML
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, github-pages, …)
+
+${colors.bright}Build Options:${colors.reset}
+  --target <type>    Build target (foundation, site) — auto-detected if not specified
+  --prerender        Force pre-rendering (overrides site.yml)
+  --no-prerender     Skip pre-rendering (overrides site.yml)
+  --foundation-dir   Path to foundation directory (for prerendering)
+  --host <name>      Apply host-specific postBuild (cloudflare-pages, s3-cloudfront, …)
+  --platform <name>  (Deprecated alias for --host)
+
+  At workspace root, builds all foundations first, then all sites.
+  Pre-rendering is enabled by default when build.prerender: true in site.yml.
+  See \`uniweb <command> --help\` for command-specific detail and examples.
+
+${colors.bright}Docs Subcommands:${colors.reset}
+  docs               Generate COMPONENTS.md from foundation schema
+  docs site          Show site.yml configuration reference
+  docs page          Show page.yml configuration reference
+  docs meta          Show component meta.js reference
+
+${colors.bright}Docs Options:${colors.reset}
+  --output <file>    Output filename (default: COMPONENTS.md)
+  --from-source      Read meta.js files directly instead of schema.json
+
+${colors.bright}i18n Commands:${colors.reset}
+  extract            Extract translatable strings to manifest
+  sync               Update manifest with content changes
+  status             Show translation coverage per locale
+
+${colors.bright}Template Types:${colors.reset}
+  starter                       Foundation + site + sample content (default)
+  none                          Foundation + site with no content
+  marketing                     Official marketing template
+  ./path/to/template            Local directory
+  @scope/template-name          npm package
+  github:user/repo              GitHub repository
+  https://github.com/user/repo  GitHub URL
+
+${colors.bright}Examples:${colors.reset}
+  uniweb create my-project                           # Foundation + site + starter content
+  uniweb create my-project --template none           # Foundation + site, no content
+  uniweb create my-project --blank                   # Empty workspace
+  uniweb create my-project --template marketing      # Official template
+  uniweb create my-project --template ./my-template  # Local template
+
+  cd my-project
+  uniweb add project docs                            # Add docs/src/ + docs/site/
+  uniweb add project docs --from academic            # Co-located pair + academic content
+  uniweb add foundation marketing                    # Add marketing/ at root
+  uniweb add site blog --foundation marketing        # Add blog/ wired to marketing
+  uniweb add extension effects --site site           # Add effects/
+
+  uniweb build
+  uniweb build --target src                          # Build src/ package
+  cd src && uniweb docs                              # Generate COMPONENTS.md
+
+${colors.bright}Install:${colors.reset}
+  npm i -g uniweb          Global install (recommended)
+  npx uniweb <command>     Run without installing
+`)
+}
+
+// Run CLI
+main().catch(async (err) => {
+  error(err.message)
+  await exitWhenDrained(1)
+})