uniweb 0.12.10 → 0.12.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.10",
+  "version": "0.12.11",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,8 +42,8 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/runtime": "0.8.13",
-    "@uniweb/kit": "0.9.11",
-    "@uniweb/core": "0.7.11"
+    "@uniweb/core": "0.7.11",
+    "@uniweb/kit": "0.9.11"
   },
   "peerDependencies": {
     "@uniweb/build": "0.14.2",

package/partials/agents.md

@@ -136,11 +136,28 @@ Creates `sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starte
 ## Commands
 
 ```bash
-pnpm install    # Install dependencies
-pnpm dev        # Start dev server
-pnpm build      # Build for production
-pnpm preview    # Preview production build (SSG + SPA)
-```
+# Local development
+uniweb dev                        # Start dev server (picks the site for you)
+pnpm install                      # Install dependencies
+pnpm build                        # Build for production
+pnpm preview                      # Preview production build (SSG + SPA)
+
+# Ship the site (uniweb verbs)
+uniweb deploy                     # Deploy to Uniweb hosting (default; needs `uniweb login` first)
+uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, netlify,
+                                  # vercel, github-pages, s3-cloudfront, generic-static
+uniweb deploy --dry-run           # Resolve foundation/runtime + print summary; no writes
+uniweb export                     # Build dist/ for any static host (no Uniweb account)
+uniweb publish                    # Publish a foundation as a catalog product (deliberate;
+                                  # for site-bound foundations use `uniweb deploy` instead)
+uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
+
+# Help
+uniweb --help                     # Top-level help
+uniweb <command> --help           # Per-command help (no side effects)
+```
+
+`uniweb deploy` auto-publishes a workspace-local foundation as part of the deploy under a site-scoped slot — no separate `uniweb publish` step needed for site-bound foundations.
 
 ---
 

package/src/commands/add.js

@@ -389,7 +389,7 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     success(`Created site ${colors.bright}${siteName}${colors.reset} at ${relativePath}/`)
   }
   log('')
-  log(`Next: ${colors.cyan}${installCmd(pm)} && ${filterCmd(pm, siteName, 'dev')}${colors.reset}`)
+  log(`Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${siteName}${colors.reset}`)
   if (!opts.from) {
     log('')
     log(`${colors.dim}To add your first page, create ${relativePath}/pages/home/page.yml and a .md file.${colors.reset}`)
@@ -631,7 +631,7 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
   log(`  ${colors.dim}Foundation: ${name}/src/ (${foundationPkgName})${colors.reset}`)
   log(`  ${colors.dim}Site: ${name}/site/ (${sitePkgName})${colors.reset}`)
   log('')
-  log(`Next: ${colors.cyan}${installCmd(pm)} && ${filterCmd(pm, sitePkgName, 'dev')}${colors.reset}`)
+  log(`Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${sitePkgName}${colors.reset}`)
 }
 
 /**

package/src/commands/deploy.js

@@ -401,6 +401,21 @@ export async function deploy(args = []) {
   // of the current source's git sha. This flag opts out.
   const autoPublishFoundation = !args.includes('--no-auto-publish')
 
+  // --local: redirect platform URLs to the unicloud mock (localhost:4001)
+  // for internal end-to-end testing. Documented in the workspace root
+  // CLAUDE.md ("The --local Flag" section). NOT a public user-facing
+  // feature — a real user has no unicloud server running. The flag is
+  // intentionally absent from the global help to avoid leaking it into
+  // user docs; per-command help (uniweb deploy --help) lists it under
+  // an "Internal" caveat for the eval / test team.
+  //
+  // The override unconditionally pins both backend and worker to
+  // http://localhost:4001 (unicloud's default port) regardless of any
+  // env vars set in the calling shell. Auth is NOT skipped — the runbook
+  // expects mock-login.js to seed ~/.uniweb/auth.json with a JWT
+  // unicloud's verifyToken accepts.
+  const isLocal = args.includes('--local')
+
   // Internal escape hatches — see framework/cli/docs/env-vars.md. These
   // are not user-facing flags; they exist for the platform test team,
   // CI scripts, and dev-loop unblockers. The bare `deploy` command should
@@ -415,8 +430,11 @@ export async function deploy(args = []) {
   const treatDirtyAsStale = !parseBoolEnv('UNIWEB_ALLOW_DIRTY_FOUNDATION')
 
   const siteDir = await resolveSiteDir(args)
-  const backendUrl = getBackendUrl()
-  const workerUrl = getRegistryUrl()
+  const backendUrl = isLocal ? 'http://localhost:4001' : getBackendUrl()
+  const workerUrl = isLocal ? 'http://localhost:4001' : getRegistryUrl()
+  if (isLocal) {
+    console.log(`  \x1b[2m→ Local mock mode (unicloud at ${backendUrl}; see workspace root CLAUDE.md)\x1b[0m`)
+  }
 
   // Read site.yml — declares the foundation (required) and optionally the
   // site.id / site.handle from prior deploys.
@@ -599,7 +617,7 @@ export async function deploy(args = []) {
   // doesn't fail the whole deploy.
   const desiredFeatures = readFeaturesFromYaml(siteYml)
 
-  const cliToken = await ensureAuth({ command: 'Deploying' })
+  const cliToken = await ensureAuth({ command: 'Deploying', args })
 
   // Always rebuild unless the user explicitly opts out with --skip-build.
   // A stale dist/ from a previous build + edited content on disk would

package/src/commands/dev.js

@@ -0,0 +1,111 @@
+/**
+ * Dev Command
+ *
+ * Starts a dev server for a site in the current workspace. Wraps the
+ * project's `dev` script (set up by `uniweb create` to filter to the
+ * appropriate site package). Provides discoverability and consistency
+ * with `uniweb build` / `uniweb deploy` — users shouldn't have to know
+ * whether to type `pnpm dev` or `npm run dev` when the rest of the CLI
+ * is verb-shaped.
+ *
+ * Usage:
+ *   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
+ *
+ * Resolution order for which site to launch:
+ *   1. --site <name> (if passed)
+ *   2. Positional <site> arg
+ *   3. The single site in the workspace (if exactly one)
+ *   4. The first site in the workspace, with a "multiple sites" notice
+ *      pointing at --site for explicit selection
+ *
+ * Multi-site workspaces with no positional / flag will run the first
+ * site by default (mirrors the `pnpm dev` shortcut `uniweb create` writes).
+ * Use `--site` to pick a different one without editing the root scripts.
+ *
+ * Implementation: shells out to the package manager that invoked the CLI
+ * (detected via npm_config_user_agent), running the workspace-filtered
+ * dev command (`pnpm --filter <name> dev` or `npm -w <name> run dev`).
+ * No special handling of vite directly — the site package already owns
+ * its dev script, and shelling through pnpm/npm respects whatever the
+ * site has configured (Vite plugins, env vars, port overrides, etc.).
+ */
+
+import { spawn } from 'node:child_process'
+import { join } from 'node:path'
+
+import { detectPackageManager, filterCmd } from '../utils/pm.js'
+import { discoverSites, readWorkspaceConfig } from '../utils/config.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { readFlagValue } from '../utils/args.js'
+
+const RED = '\x1b[31m'
+const YELLOW = '\x1b[33m'
+const DIM = '\x1b[2m'
+const CYAN = '\x1b[36m'
+const RESET = '\x1b[0m'
+
+export async function dev(args = []) {
+  const cwd = process.cwd()
+  const rootDir = findWorkspaceRoot(cwd) || cwd
+
+  // Verify we're in a Uniweb workspace (has pnpm-workspace.yaml or
+  // package.json::workspaces). discoverSites already handles both.
+  let workspaceConfig
+  try {
+    workspaceConfig = await readWorkspaceConfig(rootDir)
+  } catch {
+    workspaceConfig = { packages: [] }
+  }
+  if (workspaceConfig.packages.length === 0) {
+    console.error(`${RED}✗${RESET} Not in a Uniweb workspace (no pnpm-workspace.yaml or package.json::workspaces).`)
+    console.error(`  Run \`uniweb create <name>\` to scaffold a project, or cd into an existing one.`)
+    process.exit(1)
+  }
+
+  const sites = await discoverSites(rootDir)
+  if (sites.length === 0) {
+    console.error(`${RED}✗${RESET} No sites found in this workspace.`)
+    console.error(`  Add one with \`uniweb add site <name>\`.`)
+    process.exit(1)
+  }
+
+  // Pick the site
+  const siteFlag = readFlagValue(args, '--site')
+  const positional = args.find(a => !a.startsWith('-'))
+  const requested = (typeof siteFlag === 'string' ? siteFlag : null) || positional || null
+
+  let site
+  if (requested) {
+    site = sites.find(s => s.name === requested) || sites.find(s => s.path === requested)
+    if (!site) {
+      console.error(`${RED}✗${RESET} Site "${requested}" not found.`)
+      console.error(`  Available: ${sites.map(s => s.name).join(', ')}`)
+      process.exit(1)
+    }
+  } else if (sites.length === 1) {
+    site = sites[0]
+  } else {
+    site = sites[0]
+    console.error(`${YELLOW}⚠${RESET} Multiple sites found; using ${CYAN}${site.name}${RESET}.`)
+    console.error(`  Pick a different one with \`uniweb dev --site <name>\`.`)
+    console.error(`  Available: ${sites.map(s => s.name).join(', ')}`)
+    console.error('')
+  }
+
+  const pm = detectPackageManager()
+  const command = filterCmd(pm, site.name, 'dev')
+  const [bin, ...rest] = command.split(' ')
+  const sitePath = join(rootDir, site.path)
+
+  console.error(`${DIM}→ ${command}${RESET} ${DIM}(site: ${site.name}, dir: ${sitePath})${RESET}`)
+  console.error('')
+
+  const child = spawn(bin, rest, { cwd: rootDir, stdio: 'inherit' })
+  child.on('close', code => process.exit(code ?? 0))
+  child.on('error', err => {
+    console.error(`${RED}✗${RESET} Failed to start dev server: ${err.message}`)
+    process.exit(1)
+  })
+}

package/src/commands/handoff.js

@@ -145,7 +145,7 @@ async function readSchema(foundationDir) {
  * Create a RemoteRegistry instance with auth.
  */
 async function createRegistry(args) {
-  const token = await ensureAuth({ command: 'Handing off' })
+  const token = await ensureAuth({ command: 'Handing off', args })
 
   const registryUrl = parseFlag(args, '--registry')
   const url = registryUrl || process.env.UNIWEB_REGISTRY_URL || 'http://localhost:4001'

package/src/commands/invite.js

@@ -146,7 +146,7 @@ async function readSchema(foundationDir) {
  * Create a RemoteRegistry instance with auth.
  */
 async function createRegistry(args) {
-  const token = await ensureAuth({ command: 'Creating invite' })
+  const token = await ensureAuth({ command: 'Creating invite', args })
 
   const registryUrl = parseFlag(args, '--registry')
   const url = registryUrl || process.env.UNIWEB_REGISTRY_URL || 'http://localhost:4001'

package/src/commands/publish.js

@@ -794,7 +794,7 @@ export async function publish(args = []) {
     registry = createLocalRegistry(foundationDir)
   } else {
     // Remote publish — ensure authenticated (inline login if needed)
-    const token = await ensureAuth({ command: 'Publishing' })
+    const token = await ensureAuth({ command: 'Publishing', args })
 
     const url = registryUrl || getRegistryUrl()
     registry = new RemoteRegistry(url, token)

package/src/commands/template.js

@@ -191,7 +191,7 @@ async function templatePublish(args) {
   console.log(`  ${colors.dim}${fileCount} files${colors.reset}`)
 
   // 5. Authenticate
-  const token = await ensureAuth({ command: 'Publishing template' })
+  const token = await ensureAuth({ command: 'Publishing template', args })
 
   // 6. Build payload
   const url = registryUrl || process.env.UNIWEB_REGISTRY_URL || 'http://localhost:4001'

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-05T18:36:54.411Z",
+  "generatedAt": "2026-05-05T20:43:37.314Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.14.2",
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.6",
+      "version": "0.4.7",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -199,12 +199,16 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
 
   onProgress?.('Setting up workspace...')
 
-  // 1. Scaffold 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: filterCmd(pm, 'site', 'dev'),
+      dev: 'uniweb dev',
       build: 'uniweb build',
       preview: filterCmd(pm, 'site', 'preview'),
     },
@@ -286,17 +290,19 @@ async function createFromContentTemplate(projectDir, projectName, metadata, temp
   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 = filterCmd(pm, sites[0].name, 'dev')
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
   } else {
     for (const s of sites) {
-      scripts[`dev:${s.name}`] = filterCmd(pm, s.name, 'dev')
+      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 = filterCmd(pm, sites[0].name, 'dev')
+      scripts.dev = 'uniweb dev'
       scripts.preview = filterCmd(pm, sites[0].name, 'preview')
     }
   }
@@ -452,12 +458,26 @@ async function main() {
     // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
   }
 
-  // Start non-blocking update check for global installs
+  // Start non-blocking update check for global installs.
+  //
+  // Two surfaces:
+  //   - showUpdateNotification (soft, trailing): printed at command end for
+  //     any verb. Doesn't interrupt the user's workflow.
+  //   - eager (loud, leading): printed BEFORE staleness-sensitive verbs do
+  //     their work. Today: only `create` (templates ship with the CLI, so
+  //     a stale CLI scaffolds stale starter content; the user needs to know
+  //     before files hit disk). Other verbs are insensitive — `deploy` etc.
+  //     are project-bound (delegated to local node_modules), and the
+  //     local-vs-global mismatch warning in delegateToLocal already covers
+  //     that case.
   let showUpdateNotification = () => {}
   if (global) {
     try {
-      const { startUpdateCheck } = await import('./utils/update-check.js')
+      const { startUpdateCheck, maybeEagerNotification } = await import('./utils/update-check.js')
       showUpdateNotification = startUpdateCheck(getCliVersion())
+      if (command === 'create') {
+        maybeEagerNotification(getCliVersion())
+      }
     } catch {
       // Update check is optional — don't fail if the module is missing
     }
@@ -470,6 +490,23 @@ async function main() {
     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')
@@ -478,6 +515,16 @@ async function main() {
     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 docs command (dynamic import — depends on @uniweb/build)
   if (command === 'docs') {
     const { docs } = await importProjectCommand('./commands/docs.js')
@@ -807,18 +854,307 @@ async function main() {
     log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${prefix} add project${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
-    log(`  ${colors.cyan}${runCmd(pm, 'dev')}${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
   } else {
     log(`Next steps:\n`)
     log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
-    log(`  ${colors.cyan}${runCmd(pm, 'dev')}${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
   }
   log('')
+  log(`When ready to ship:\n`)
+  log(`  ${colors.cyan}${prefix} deploy${colors.reset}                     ${colors.dim}# Uniweb hosting (default; uniweb login first)${colors.reset}`)
+  log(`  ${colors.cyan}${prefix} deploy --host=<adapter>${colors.reset}    ${colors.dim}# cloudflare-pages, netlify, vercel, github-pages, s3-cloudfront${colors.reset}`)
+  log(`  ${colors.cyan}${prefix} export${colors.reset}                     ${colors.dim}# Build dist/ for any static host (no Uniweb account)${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) {
+  const blocks = {
+    deploy: `
+${colors.cyan}${colors.bright}uniweb deploy${colors.reset} ${colors.dim}— Deploy a site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb deploy [options]
+
+The host is determined by the resolved deploy.yml target. Defaults to
+${colors.cyan}uniweb${colors.reset} hosting (link-mode, edge JIT prerender) when no deploy.yml exists.
+
+${colors.bright}Hosts:${colors.reset}
+  uniweb              Uniweb hosting (default; requires \`uniweb login\`)
+  cloudflare-pages    Cloudflare Pages (build artifact + adapter postBuild)
+  netlify             Netlify (alias of cloudflare-pages adapter)
+  vercel              Vercel (build-only — deploy via \`npx vercel\`)
+  github-pages        GitHub Pages (build-only — push dist/ to gh-pages)
+  s3-cloudfront       AWS S3 + CloudFront (uploads + invalidates via CLI)
+  generic-static      Plain static-host build, no host-specific helpers
+
+${colors.bright}Options:${colors.reset}
+  --target <name>     Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --host <name>       Override the resolved target's host (does not persist)
+  --host              No value → interactive picker (TTY only)
+  --dry-run           Resolve site.yml + foundation/runtime; print summary; no writes
+  --no-auto-publish   Don't auto-publish workspace-local foundation as part of deploy
+  --no-save           Skip the auto-save of lastDeploy in deploy.yml
+  --local             Internal: target the unicloud mock (see workspace root CLAUDE.md)
+  --non-interactive   Fail with usage info instead of prompting
+
+${colors.bright}Auth:${colors.reset}
+  \`host: uniweb\` requires authentication. Run \`uniweb login\` first, set
+  \`UNIWEB_TOKEN=<bearer>\` env var, or use a static-host adapter that
+  doesn't need a Uniweb account. CI / agents / piped stdin auto-detect
+  non-interactive mode and bail with an actionable error instead of
+  hanging on a browser callback.
+
+${colors.bright}Examples:${colors.reset}
+  uniweb deploy                              # Default (host=uniweb)
+  uniweb deploy --dry-run                    # Print summary, no writes
+  uniweb deploy --host=cloudflare-pages      # One-off override
+  uniweb deploy --target=preview             # Pick named target from deploy.yml
+`,
+    publish: `
+${colors.cyan}${colors.bright}uniweb publish${colors.reset} ${colors.dim}— Publish a foundation to the catalog${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb publish [@org/name] [options]
+
+For site-bound foundations (one foundation, one site), use \`uniweb deploy\`
+instead — it auto-publishes under a site-scoped slot, no naming ceremony.
+
+${colors.bright}Options:${colors.reset}
+  --catalog          Confirm publish to the public catalog (required in CI)
+  --propagate        Walk trusting sites' policy waves (default: silent)
+  --name <id>        Foundation id (overrides package.json::uniweb.id)
+  --namespace <ns>   Force org-scope namespace (overrides package.json)
+  --local            Internal: publish to the unicloud mock (see workspace root CLAUDE.md)
+  --registry <url>   Use a specific registry URL
+  --edit-access <p>  "open" or "restricted" (default: restricted)
+  --dry-run          Show what would be published without uploading
+  --non-interactive  Fail with usage info instead of prompting
+`,
+    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]
+
+${colors.bright}Options:${colors.reset}
+  --template <type>  Project template (default: starter)
+                     Built-in: starter, none, marketing
+                     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 display name
+  --no-git           Skip git repository initialization
+
+${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
+`,
+    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.
+`,
+    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} ${colors.dim}— Add a foundation, site, or extension${colors.reset}
+
+${colors.bright}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)
+
+${colors.bright}Common options:${colors.reset}
+  --from <template>       Source content from a template
+  --path <dir>            Override default folder location
+  --foundation <name>     Wire site/extension to this foundation (CI-friendly)
+  --site <name>           Wire extension to this site (CI-friendly)
+  --non-interactive       Fail with usage info instead of prompting
+`,
+    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).
+`,
+    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>
+
+Today supports renaming foundations only. Updates folder name, foundation
+package.json::name, every dependent site's site.yml::foundation, every
+dependent site's package.json::dependencies, pnpm-workspace.yaml, and
+package.json::workspaces. Transactional — bails on conflict before any
+filesystem mutation.
+`,
+    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]
+
+Opens a browser to hub.uniweb.app for OAuth-style login, then captures
+the token via a loopback callback. Falls back to a paste-token prompt
+if the browser flow fails.
+
+${colors.bright}Options:${colors.reset}
+  --backend <url>    Override the auth backend (default: https://hub.uniweb.app)
+
+In non-interactive mode (CI / no TTY / --non-interactive), this command
+errors out — set the \`UNIWEB_TOKEN\` env var instead, or run \`login\`
+once on a machine with a browser to seed ~/.uniweb/auth.json.
+`,
+    invite: `
+${colors.cyan}${colors.bright}uniweb invite${colors.reset} ${colors.dim}— Create a foundation invite for a client${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb invite <email> [options]
+
+${colors.bright}Options:${colors.reset}
+  --uses <n>         Max sites per invite (default: 1)
+  --expires <days>   Days until expiry (default: 30)
+  --version <n>      Major version to license (default: current)
+  --list             List invites for your foundation
+  --revoke <id>      Revoke an invite
+  --resend <id>      Resend an invite
+`,
+    handoff: `
+${colors.cyan}${colors.bright}uniweb handoff${colors.reset} ${colors.dim}— Hand off a site to a client${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb handoff <email> [options]
+
+${colors.bright}Options:${colors.reset}
+  --site <id>        Site identifier (default: auto-generated)
+  --web              Show web-based handoff instructions instead
+`,
+    template: `
+${colors.cyan}${colors.bright}uniweb template${colors.reset} ${colors.dim}— Manage cloud templates${colors.reset}
+
+${colors.bright}Subcommands:${colors.reset}
+  template publish        Publish a site as a cloud template
+
+${colors.bright}Publish Options:${colors.reset}
+  --name <name>      Template registry name (overrides site.yml template: field)
+  --title <title>    Display title (overrides site.yml name: field)
+  --description <t>  Description
+  --registry <url>   Registry URL (default: http://localhost:4001)
+`,
+    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}— Update AGENTS.md to match installed CLI version${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb update
+
+Refreshes the project's AGENTS.md from the CLI's bundled version. Run
+after upgrading the \`uniweb\` package to pick up new content authoring
+patterns and platform documentation.
+`,
+  }
+
+  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}
@@ -830,6 +1166,7 @@ ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   add <type> [name]  Add a foundation, site, or extension to a project
   rename <type>      Rename a workspace package (foundation today)
+  dev                Start a dev server for a site
   build              Build the current project
   deploy             Deploy a site to Uniweb hosting
   export             Export a self-contained site for third-party hosting
@@ -896,21 +1233,34 @@ ${colors.bright}Template Options:${colors.reset}
   --registry <url>   Registry URL (default: http://localhost:4001)
 
 ${colors.bright}Deploy Options:${colors.reset}
+  --target <name>    Pick a target from deploy.yml (default: deploy.yml's \`default:\`)
+  --host <name>      Override the resolved target's host (does not persist).
+                     Without a value, opens an interactive picker (TTY only).
+                     Hosts: uniweb, cloudflare-pages, netlify, vercel,
+                     github-pages, s3-cloudfront, generic-static.
   --dry-run          Resolve site.yml + foundation/runtime; print summary; no writes
   --no-auto-publish  Don't auto-publish workspace-local foundation as part of deploy
+  --no-save          Skip the auto-save of lastDeploy in deploy.yml
+
+${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
+  --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)
-  --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
+  --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
+  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

package/src/utils/auth.js

@@ -153,17 +153,45 @@ export function isExpired(auth) {
  * Ensure the user is authenticated. If not, prompt inline login.
  * Returns the auth token on success, exits the process on cancel.
  *
+ * In non-interactive mode (CI, no TTY, or --non-interactive in args),
+ * bails with an actionable error instead of opening a browser. The browser
+ * login flow waits 120 seconds for a callback that can never arrive without
+ * a user, then drops to a token-paste prompt that pipes can't answer —
+ * silently burning two minutes per invocation. CI / agent / piped callers
+ * must set `UNIWEB_TOKEN`, run `uniweb login` interactively first, or use
+ * `--local` for the unicloud mock (see workspace root CLAUDE.md).
+ *
  * @param {Object} options
  * @param {string} options.command - The command that needs auth (for messaging)
+ * @param {string[]} [options.args] - Argv slice; checked for --non-interactive
  * @returns {Promise<string>} Bearer token
  */
-export async function ensureAuth({ command = 'This command' } = {}) {
+export async function ensureAuth({ command = 'This command', args = [] } = {}) {
+  // Honor explicit token from env — useful for CI and agents.
+  if (process.env.UNIWEB_TOKEN) {
+    return process.env.UNIWEB_TOKEN
+  }
+
   const auth = await readAuth()
 
   if (auth?.token && !isExpired(auth)) {
     return auth.token
   }
 
+  // Non-interactive bail: don't open a browser, don't wait 120s, don't
+  // prompt for a token paste. Print an actionable error and exit.
+  const { isNonInteractive, getCliPrefix } = await import('./interactive.js')
+  if (isNonInteractive(args)) {
+    const prefix = getCliPrefix()
+    const reason = auth && isExpired(auth) ? 'Session expired.' : 'Not logged in.'
+    console.error(`\x1b[31m✗\x1b[0m ${reason} ${command} requires a Uniweb account, and the CLI is in non-interactive mode (CI / no TTY / --non-interactive).`)
+    console.error(`  Options:`)
+    console.error(`    • Run \`${prefix} login\` interactively first, then re-run.`)
+    console.error(`    • Set the \`UNIWEB_TOKEN\` env var to a bearer token.`)
+    console.error(`    • Use \`--local\` to target the unicloud mock (internal testing only — see workspace root CLAUDE.md).`)
+    process.exit(1)
+  }
+
   // Need to log in — delegate to the login command
   if (auth && isExpired(auth)) {
     console.log(`\x1b[33mSession expired.\x1b[0m ${command} requires a Uniweb account.\n`)

package/src/utils/config.js

@@ -157,9 +157,17 @@ export async function writeRootPackageJson(rootDir, pkg) {
 }
 
 /**
- * Compute root scripts based on discovered sites
+ * Compute root scripts based on discovered sites.
+ *
+ * `dev` and `build` route through the uniweb CLI verb (PM-agnostic — they
+ * resolve `uniweb` from the project's local node_modules/.bin, so `pnpm
+ * dev` and `npm run dev` both work without locking the scripts to one PM
+ * at create-time). `preview` stays on a PM-specific filter because there
+ * isn't a `uniweb preview` verb yet (the site's own `vite preview` is what
+ * runs); switch it over when one ships.
+ *
  * @param {Array<{name: string, path: string}>} sites - Discovered sites
- * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager
+ * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager (used only for preview)
  * @returns {Object} Scripts object for package.json
  */
 export function computeRootScripts(sites, pm = 'pnpm') {
@@ -172,16 +180,17 @@ export function computeRootScripts(sites, pm = 'pnpm') {
   }
 
   if (sites.length === 1) {
-    scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
   } else {
-    // First site gets unqualified dev/preview
-    scripts.dev = filterCmd(pm, sites[0].name, 'dev')
+    // First site gets unqualified dev/preview (matches `uniweb dev`'s
+    // default-to-first-site behavior).
+    scripts.dev = 'uniweb dev'
     scripts.preview = filterCmd(pm, sites[0].name, 'preview')
 
     // Subsequent sites get qualified dev:{name}/preview:{name}
     for (let i = 1; i < sites.length; i++) {
-      scripts[`dev:${sites[i].name}`] = filterCmd(pm, sites[i].name, 'dev')
+      scripts[`dev:${sites[i].name}`] = `uniweb dev ${sites[i].name}`
       scripts[`preview:${sites[i].name}`] = filterCmd(pm, sites[i].name, 'preview')
     }
   }

package/src/utils/update-check.js

@@ -52,15 +52,46 @@ function writeState(state) {
 
 /**
  * Print update notification to stderr (doesn't interfere with piped output).
+ * `tone` controls the lead-in: 'soft' (default — trailing notice for finished
+ * commands) vs 'eager' (leading notice for staleness-sensitive commands like
+ * `create`, where the user is about to scaffold files from CLI-bundled
+ * templates and a stale CLI means stale starter content).
  */
-function printNotification(current, latest) {
+function printNotification(current, latest, tone = 'soft') {
   const yellow = '\x1b[33m'
   const cyan = '\x1b[36m'
   const dim = '\x1b[2m'
   const reset = '\x1b[0m'
   console.error('')
-  console.error(`${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`)
-  console.error(`${dim}Run${reset} npm i -g uniweb ${dim}to update${reset}`)
+  if (tone === 'eager') {
+    console.error(`${yellow}Heads up:${reset} this CLI is ${dim}${current}${reset}; latest is ${cyan}${latest}${reset}.`)
+    console.error(`${dim}Templates ship with the CLI — consider updating first:${reset} npm i -g uniweb`)
+    console.error(`${dim}Or run a one-shot fresh:${reset} npx uniweb@latest <command>`)
+  } else {
+    console.error(`${yellow}Update available:${reset} ${dim}${current}${reset} → ${cyan}${latest}${reset}`)
+    console.error(`${dim}Run${reset} npm i -g uniweb ${dim}to update${reset}`)
+  }
+}
+
+/**
+ * Synchronously read the cache and print an eager notification if a newer
+ * version is known. No network fetch — only reads what `startUpdateCheck`
+ * has previously cached. Returns true if a notification was printed.
+ *
+ * Use this for staleness-sensitive verbs (`create`) BEFORE the verb does
+ * its work, so the user sees the warning before any files are written
+ * from CLI-bundled templates. For other verbs, the trailing soft
+ * notification from startUpdateCheck() is sufficient.
+ *
+ * @param {string} currentVersion
+ * @returns {boolean} true if a notification was printed
+ */
+export function maybeEagerNotification(currentVersion) {
+  const state = readState()
+  if (!state.latestVersion) return false
+  if (compareSemver(state.latestVersion, currentVersion) <= 0) return false
+  printNotification(currentVersion, state.latestVersion, 'eager')
+  return true
 }
 
 /**