uniweb 0.12.9 → 0.12.11

package/README.md

@@ -310,14 +310,22 @@ Start with local files deployed anywhere. The same foundation works across all t
 
 ## Deployment
 
-A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code) — and they don't have to ship together. That opens up deployment options other frameworks can't express:
+A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code) — and they don't have to ship together. Two top-level modes:
 
-- **Bundled mode** — site and foundation built into one self-contained `dist/`, deployed to any static host.
-- **Linked mode** — the foundation lives in any host and the site in any other host; different sites can dynamically link with the same foundation. Update the foundation, every site picks it up — no site rebuilds.
+- **Standalone mode** — site and foundation built into one self-contained `dist/`, deployed to any static host.
+- **Linked mode** — the foundation is a separate file the site loads at runtime, with two flavours:
+  - **Site-bound** — the foundation belongs to one site and rides with it (`foundation: ~self/<name>@<version>` in `site.yml`).
+  - **Cataloged** — the foundation is a catalog product, published once and licensed to consuming sites (`foundation: '@<org>/<name>@<version>'`).
 
-Two verbs handle it: `uniweb publish` sends a foundation to a registry, `uniweb deploy` sends a site to a host. Most projects start bundled (one command, one destination) and grow into linked mode by changing one line in `site.yml`. Mix providers freely — foundation on GitHub Pages, site on Vercel; or use Uniweb's registry + hosting for propagation, gated rollouts, and edge SSR.
+`uniweb publish` ships a cataloged foundation; `uniweb deploy` ships a site (and, for site-bound, the foundation along with it). Most projects start standalone or site-bound and grow into cataloged when a foundation needs to serve more than one site.
 
-→ **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)** — the full menu: bundled vs linked, the two-verb model, one-foundation-many-sites, optimized hosting on the Uniweb platform, and recipes for other hosting services.
+Where can you deploy?
+
+- **Free static hosts** — Vercel, Cloudflare Pages, Netlify, GitHub Pages — work great when you have a site to publish. Built-in adapters: `vercel`, `cloudflare-pages`, `netlify`, `github-pages`. Lifecycle is Git-driven: connect your repo, the host runs `uniweb build` on each push, serves `dist/`. The framework auto-detects the CI host and emits the right helper files.
+- **AWS S3 + CloudFront** — `uniweb deploy --host=s3-cloudfront` builds, syncs, and invalidates in one command.
+- **Uniweb hosting** — paid (starts at $14/month per site). Always serves linked sites with JIT prerender, edge SSR, locale-aware routing, foundation/runtime version propagation, and the multi-tenant CMS for non-technical content authors via the visual editor. The right choice when foundation developers or agencies build for clients who manage their own content. The catalog is private and access-segregated — foundations are commercial products licensed by site, not packages on a public registry.
+
+→ **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)** — the full menu: picking a deploy path (free vs paid), standalone vs linked, site-bound vs cataloged, the two-verb model, CI-detection, and per-host recipes.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,12 +41,12 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "0.9.10",
-    "@uniweb/runtime": "0.8.11",
-    "@uniweb/core": "0.7.10"
+    "@uniweb/runtime": "0.8.13",
+    "@uniweb/core": "0.7.11",
+    "@uniweb/kit": "0.9.11"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.1",
+    "@uniweb/build": "0.14.2",
     "@uniweb/semantic-parser": "1.1.17",
     "@uniweb/content-reader": "1.1.10"
   },

package/partials/agents.md

@@ -136,12 +136,29 @@ 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.json` `uniweb` configuration
@@ -172,7 +189,7 @@ The `uniweb` block in `package.json` carries platform-specific configuration tha
 **Catalog vs site-bound foundations.** Two distribution intents share the same `dist/foundation.js` artifact:
 
 - A **catalog foundation** is a deliberate product — named, versioned, listed in the catalog, consumable by other developers' sites. Use `uniweb publish @org/name` for these. The CLI requires an explicit name argument so you don't accidentally catalog a foundation that was meant to be site-bound.
-- A **site-bound foundation** powers exactly one site. Don't run `uniweb publish` for it. Just run `uniweb deploy` from the site directory — the CLI auto-publishes your local foundation as part of the deploy, under a registry slot scoped to the site itself, with no naming ceremony. The foundation isn't visible in the catalog and isn't owned by the developer who happened to run the deploy.
+- A **site-bound foundation** powers exactly one site. Don't run `uniweb publish` for it. Just run `uniweb deploy` from the site directory — the CLI auto-publishes your local foundation as part of the deploy, **uploaded with the site's other published assets** (per-site storage, never to the catalog). With no naming ceremony, no catalog visibility, and no developer-vs-site ownership confusion. To later promote the foundation to a catalog product, run `uniweb publish @org/name` from the foundation directory and update the site's `site.yml` to a versioned ref (`foundation: '@org/name@1.2.3'`).
 
 **On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means renaming on the registry (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb publish --name marketing-pro` — it persists to `uniweb.id` without touching the workspace.
 

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/build.js

@@ -35,8 +35,10 @@
  *   uniweb build --target site       # Explicitly build as site
  *   uniweb build --prerender         # Force pre-rendering
  *   uniweb build --no-prerender      # Skip pre-rendering
- *   uniweb build --host <name>       # Override site.yml deploy.host (e.g.
- *                                      netlify, s3-cloudfront, generic-static)
+ *   uniweb build --host <name>       # Pick the host adapter for this build's
+ *                                      postBuild step (e.g. cloudflare-pages,
+ *                                      s3-cloudfront, github-pages,
+ *                                      generic-static). Default: cloudflare-pages.
  *
  * Internal flags (called by `uniweb deploy` / `uniweb export`):
  *   --link              # Data-only pipeline (Uniweb-edge)
@@ -838,12 +840,25 @@ export async function build(args = []) {
     foundationDir = resolve(args[foundationDirIndex + 1])
   }
 
-  // --host overrides site.yml's deploy.host for this build's prerender
-  // step. Validated lazily (inside prerender.js, via the registry).
+  // --host names the host adapter for this build's prerender step.
+  // Default = 'cloudflare-pages' (resolved inside prerender.js, via the
+  // registry). Build does not read deploy.yml; that is the deploy
+  // orchestrator's job. See kb/framework/plans/static-host-deploy-adapters.md.
+  //
+  // `--host` with no value → interactive picker (errors in CI / non-TTY).
+  const { readFlagValue } = await import('../utils/args.js')
+  const hostFlag = readFlagValue(args, '--host')
   let host = null
-  const hostIndex = args.indexOf('--host')
-  if (hostIndex !== -1 && args[hostIndex + 1]) {
-    host = args[hostIndex + 1]
+  if (hostFlag === null) {
+    const { promptForHost } = await import('../utils/host-prompt.js')
+    try {
+      host = await promptForHost({ args })
+    } catch (err) {
+      error(err.message)
+      process.exit(1)
+    }
+  } else if (typeof hostFlag === 'string') {
+    host = hostFlag
   }
 
   // Auto-detect project type if not specified

package/src/commands/deploy.js

@@ -1,8 +1,8 @@
 /**
  * Deploy Command
  *
- * Deploys a site. Host is determined by `deploy.host` in site.yml (or
- * `--host <name>` flag). The default is `uniweb`:
+ * Deploys a site. Host is determined by the resolved deploy.yml target
+ * (or `--target <name>` / `--host <name>` flags). The default is `uniweb`:
  *
  *   - `uniweb` (default): Uniweb hosting — link-mode + edge JIT prerender.
  *     Foundation loaded by URL from the registry. Requires `uniweb login`
@@ -39,8 +39,10 @@
  *   uniweb deploy                          Normal deploy (browser may open on first deploy)
  *   uniweb deploy --dry-run                Resolve everything but skip the Worker POST
  *   uniweb deploy --no-auto-publish        Don't auto-publish workspace-local foundation
- *   uniweb deploy --host <name>            Static-host flow (e.g., s3-cloudfront,
- *                                          generic-static). Overrides site.yml deploy.host.
+ *   uniweb deploy --target <name>          Pick a target from deploy.yml (default: deploy.yml's `default:`)
+ *   uniweb deploy --host <name>            Override the resolved target's host adapter
+ *                                          (does not write to deploy.yml on success)
+ *   uniweb deploy --no-save                Skip the auto-save of lastDeploy in deploy.yml
  *
  * Internal escape hatches (UNIWEB_* env vars — see framework/cli/docs/env-vars.md):
  *   UNIWEB_SKIP_BUILD=1                    Reuse existing dist/ instead of rebuilding
@@ -60,6 +62,9 @@ import { execSync } from 'node:child_process'
 import yaml from 'js-yaml'
 
 import { detectFoundationType } from '@uniweb/build'
+import { loadDeployYml, resolveTarget, recordLastDeploy } from '@uniweb/build/site'
+import { promptForHost } from '../utils/host-prompt.js'
+import { readFlagValue } from '../utils/args.js'
 
 import { ensureAuth, readAuth, decodeJwtPayload } from '../utils/auth.js'
 import { getBackendUrl, getRegistryUrl } from '../utils/config.js'
@@ -77,6 +82,7 @@ function splitRegistryRef(ref) {
   const m = /^(@[^/]+\/[^@]+|~[^/]+\/[^@]+|[^@]+)@(.+)$/.exec(ref)
   return m ? { name: m[1], version: m[2] } : null
 }
+
 import {
   findWorkspaceRoot,
   findSites,
@@ -395,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
@@ -409,26 +430,70 @@ 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.
   const siteYmlPath = join(siteDir, 'site.yml')
   const siteYml = await readSiteYml(siteYmlPath)
 
-  // Host dispatch. The default host is `uniweb` — Uniweb hosting
-  // (link-mode + edge JIT prerender), which is the rest of this
-  // function. Any other named host is a static-host adapter; hand off
-  // to it and return. The default flow requires a `foundation:`
-  // declaration; static-host deploys don't, so this branch comes BEFORE
-  // the foundation check.
-  // See kb/framework/plans/static-host-deploy-adapters.md.
-  const hostFlagIndex = args.indexOf('--host')
-  const hostFromFlag = hostFlagIndex !== -1 ? args[hostFlagIndex + 1] : null
-  const host = hostFromFlag || siteYml.deploy?.host || 'uniweb'
+  // Host dispatch.
+  //
+  // Resolution order:
+  //   1. --target <name> picks a target from deploy.yml (full config:
+  //      host + adapter-specific fields)
+  //   2. deploy.yml's `default:` target is used when no flag is given
+  //   3. With no deploy.yml at all, the implicit default is host: 'uniweb'
+  //   4. --host <name> is a one-off override of the resolved target's host
+  //      and does NOT persist on success (see saveDeployTarget below).
+  //
+  // The default flow (`uniweb`) requires a `foundation:` declaration;
+  // static-host deploys don't, so this branch comes BEFORE the foundation
+  // check. See kb/framework/plans/static-host-deploy-adapters.md.
+  const targetFromFlag = readFlagValue(args, '--target')
+  let hostFromFlag = readFlagValue(args, '--host')
+  const noSave = args.includes('--no-save')
+
+  let deployYml
+  try {
+    deployYml = await loadDeployYml(siteDir)
+  } catch (err) {
+    say.err(err.message)
+    process.exit(1)
+  }
+  let resolved
+  try {
+    resolved = resolveTarget(deployYml, targetFromFlag || null)
+  } catch (err) {
+    say.err(err.message)
+    process.exit(1)
+  }
+  // --host with no value → interactive picker. Pre-selects the resolved
+  // target's host so Enter does the obvious thing.
+  if (hostFromFlag === null) {
+    try {
+      hostFromFlag = await promptForHost({ args, preselect: resolved.host })
+    } catch (err) {
+      say.err(err.message)
+      process.exit(1)
+    }
+  }
+  const host = hostFromFlag || resolved.host
+  const hostOverridden = !!hostFromFlag && hostFromFlag !== resolved.host
+  // Auto-save scope: 'off' from --no-save OR an ad-hoc --host override
+  // (we don't want a one-off experiment to rewrite the file).
+  const autoSave = noSave || hostOverridden ? 'off' : resolved.autoSave
+
   if (host !== 'uniweb') {
-    await deployStaticHost(siteDir, siteYml, host, { dryRun })
+    await deployStaticHost(siteDir, host, resolved, {
+      dryRun,
+      autoSave,
+      hostOverridden,
+    })
     return
   }
 
@@ -552,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
@@ -944,19 +1009,40 @@ export async function deploy(args = []) {
   if (handleResolved) {
     console.log(`  ${c.cyan}https://${handleResolved}.uniweb.website/${c.reset}`)
   }
+
+  // Record a fresh lastDeploy.<target> entry. Skipped on --no-save (and
+  // on --host overrides, but uniweb-host can't be reached via override
+  // since the override branches into deployStaticHost above).
+  await persistLastDeploy(siteDir, {
+    targetName: resolved.targetName,
+    targetConfig: resolved.fromFile ? null : { host: 'uniweb' },
+    autoSave,
+    lastDeploy: {
+      at: deployReceipt.deployedAt,
+      host: 'uniweb',
+      url: deployReceipt.url,
+      siteId: siteIdResolved,
+      handle: handleResolved,
+      foundation: {
+        shape: 'linked',
+        ref: foundationRef,
+      },
+      runtime: runtimeVersion,
+    },
+  })
 }
 
 // ─── Static-host deploy (S3+CloudFront, etc.) ─────────────────
 //
-// Distinct from the uniweb-edge flow above. Picked when site.yml's
-// `deploy.host` (or --host flag) names a static-host adapter
-// registered in @uniweb/build/hosts. Always runs `uniweb build`
-// (bundle mode + prerender) first, then hands dist/ to the adapter's
-// deploy hook for upload + invalidation.
+// Distinct from the uniweb-edge flow above. Picked when the resolved
+// deploy.yml target (or --host override) names a static-host adapter
+// registered in @uniweb/build/hosts. Always runs `uniweb build` (bundle
+// mode + prerender) first, then hands dist/ to the adapter's deploy hook
+// for upload + invalidation.
 //
 // See kb/framework/plans/static-host-deploy-adapters.md.
 
-async function deployStaticHost(siteDir, siteYml, hostName, { dryRun }) {
+async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave, hostOverridden }) {
   let getAdapter
   try {
     ({ getAdapter } = await import('@uniweb/build/hosts'))
@@ -971,7 +1057,7 @@ async function deployStaticHost(siteDir, siteYml, hostName, { dryRun }) {
     adapter = getAdapter(hostName)
   } catch (err) {
     say.err(err.message)
-    say.dim(`Set deploy.host in site.yml or pass --host=<name>. See \`uniweb deploy --help\`.`)
+    say.dim('Set the host in deploy.yml or pass --host=<name>. See `uniweb deploy --help`.')
     process.exit(1)
   }
 
@@ -982,17 +1068,18 @@ async function deployStaticHost(siteDir, siteYml, hostName, { dryRun }) {
     process.exit(1)
   }
 
-  const deployConfig = siteYml.deploy || {}
+  const deployConfig = resolved.config || {}
   const distDir = join(siteDir, 'dist')
 
   if (dryRun) {
     say.info(`Dry run — would deploy via host adapter: ${c.bold}${adapter.name}${c.reset}`)
     say.dim(`Site dir       : ${siteDir}`)
     say.dim(`dist/          : ${existsSync(distDir) ? 'exists (would not rebuild)' : 'missing (would build)'}`)
-    say.dim(`deploy.bucket  : ${deployConfig.bucket || '(unset)'}`)
-    say.dim(`deploy.distId  : ${deployConfig.distributionId || '(unset)'}`)
-    say.dim(`deploy.region  : ${deployConfig.region || '(unset)'}`)
-    say.dim(`deploy.profile : ${deployConfig.profile || '(default AWS chain)'}`)
+    say.dim(`Target         : ${resolved.targetName}`)
+    say.dim(`bucket         : ${deployConfig.bucket || '(unset)'}`)
+    say.dim(`distributionId : ${deployConfig.distributionId || '(unset)'}`)
+    say.dim(`region         : ${deployConfig.region || '(unset)'}`)
+    say.dim(`profile        : ${deployConfig.profile || '(default AWS chain)'}`)
     return
   }
 
@@ -1045,6 +1132,39 @@ async function deployStaticHost(siteDir, siteYml, hostName, { dryRun }) {
     }
     throw err
   }
+
+  // Record a fresh lastDeploy.<target> entry. Skipped on --no-save and
+  // on ad-hoc --host overrides — see autoSave gating in deploy().
+  await persistLastDeploy(siteDir, {
+    targetName: resolved.targetName,
+    targetConfig: resolved.fromFile ? null : { host: hostName, ...deployConfig },
+    autoSave,
+    lastDeploy: {
+      at: new Date().toISOString(),
+      host: hostName,
+      // Static hosts know their public URL only via the user's CDN config;
+      // we don't have it on hand. Future: pull from a known field.
+    },
+  })
+  if (hostOverridden && !dryRun) {
+    say.dim('--host override active — did not write to deploy.yml. Edit deploy.yml to make this permanent.')
+  }
+}
+
+// ─── deploy.yml lastDeploy persistence ──────────────────────────
+
+async function persistLastDeploy(siteDir, opts) {
+  if (opts.autoSave === 'off') return
+  try {
+    const result = await recordLastDeploy(siteDir, opts)
+    if (result?.created) {
+      say.dim(`Wrote deploy.yml (target: ${opts.targetName})`)
+    }
+  } catch (err) {
+    // The deploy itself succeeded — never fail the whole command on a
+    // memo-write error. Surface it so the user can fix the file.
+    say.dim(`Could not update deploy.yml: ${err.message}`)
+  }
 }
 
 // ─── site.yml ──────────────────────────────────────────────

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/export.js

@@ -17,9 +17,10 @@
  * Usage:
  *   uniweb export                          Produce dist/ for static hosting
  *   uniweb export --no-prerender           Skip per-page prerendered HTML
- *   uniweb export --host <name>            Select a host adapter (e.g.
- *                                          netlify, s3-cloudfront, generic-static).
- *                                          Overrides site.yml's deploy.host.
+ *   uniweb export --host <name>            Pick a host adapter for postBuild
+ *                                          (e.g. cloudflare-pages, s3-cloudfront,
+ *                                          github-pages, generic-static).
+ *                                          Default: cloudflare-pages.
  */
 
 import { execSync } from 'node:child_process'
@@ -53,9 +54,21 @@ export async function exportSite(args = []) {
   const buildArgs = ['build', '--bundle']
   if (noPrerender) buildArgs.push('--no-prerender')
 
-  const hostIndex = args.indexOf('--host')
-  if (hostIndex !== -1 && args[hostIndex + 1]) {
-    buildArgs.push('--host', args[hostIndex + 1])
+  const { readFlagValue } = await import('../utils/args.js')
+  const hostFlag = readFlagValue(args, '--host')
+  if (hostFlag === null) {
+    // --host with no value → prompt here so the build subprocess gets
+    // a concrete value (and doesn't re-prompt against its own argv).
+    const { promptForHost } = await import('../utils/host-prompt.js')
+    try {
+      const chosen = await promptForHost({ args })
+      buildArgs.push('--host', chosen)
+    } catch (err) {
+      say.err(err.message)
+      process.exit(1)
+    }
+  } else if (typeof hostFlag === 'string') {
+    buildArgs.push('--host', hostFlag)
   }
 
   say.info('Exporting site (vite build → dist/)…')

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'