uniweb 0.12.46 → 0.12.48

package/README.md

@@ -321,7 +321,7 @@ uniweb add ci --host=github-pages
 
 `uniweb add ci` scaffolds a GitHub Actions workflow that runs `uniweb build` on each push. Pre-rendering is on by default — static HTML, fast first paint, SEO out of the box. Use `--domain=<domain>` for a custom domain.
 
-**Other free static hosts.** Cloudflare Pages, Netlify, and Vercel auto-build your site when you connect the repo through their dashboard — no scaffolded workflow needed.
+**Other free static hosts.** Cloudflare Pages, Netlify, and Vercel work three ways: `uniweb add ci --host=<adapter>` scaffolds a workflow (and a per-PR preview that comments the URL), connecting the repo through their dashboard lets the host build it with no config at all, or `uniweb deploy --host=<adapter>` uploads from your machine.
 
 **When to choose Uniweb hosting instead** (paid): when you need dynamic-page prerender at the edge (for collections fetched at runtime, not just at build time), foundation/runtime version propagation without redeploying every site, or edge SSR. If your site's content lives in markdown and updates ship via git, free CI is the right call.
 
@@ -346,15 +346,17 @@ Markdown in a git repo and content in the Uniweb apps can share the same site. D
 
 | Command | What it does |
 | --- | --- |
-| `uniweb add ci --host=<adapter>` | Scaffold a CI workflow in your repo (today: `github-pages`). The host runs `uniweb build` on each push. |
+| `uniweb deploy` | Ask where the site should go, then do it. Remembers the answer in `deploy.yml`. |
+| `uniweb add ci --host=<adapter>` | Scaffold a CI workflow (+ PR previews) so every push deploys. `github-pages`, `cloudflare-pages`, `netlify`, `vercel`. |
+| `uniweb add ci --target foundation` | Publish foundations at permanent versioned GitHub Pages URLs — the free alternative to the catalog. |
 | `uniweb publish` | Go live on Uniweb hosting (paid) — syncs content, brings the site's foundation along, and serves dynamically. The canonical verb for Uniweb hosting. |
-| `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. |
+| `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. Drives that host's own CLI. |
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
 | `uniweb register --scope @org` | Register a foundation to the registry (path 2). |
 | `uniweb build` | Inspect a build locally. For shipping, use `publish` (Uniweb hosting) or `deploy`/`export` (static hosts). |
 | `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
 
-`--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `cloudflare-pages`, `netlify`, `github-pages`, `vercel`, `s3-cloudfront`, `generic-static`. Each adapter implements only the operations it supports — `add ci` is currently `github-pages`-only because it's the only one that needs a workflow file in the repo.
+`--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, `s3-cloudfront`, and `generic-static` (an artifact shape for `export`, not a deploy target). Each adapter implements only the operations it supports, and the CLI never offers one it can't perform: `add ci` lists only hosts that can scaffold a workflow, and `deploy`'s picker lists only destinations with a working deploy hook.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.46",
+  "version": "0.12.48",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "0.9.24",
     "@uniweb/core": "0.7.20",
+    "@uniweb/kit": "0.9.24",
     "@uniweb/runtime": "0.8.26"
   },
   "peerDependencies": {
+    "@uniweb/build": "0.14.30",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/build": "0.14.28"
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -142,15 +142,23 @@ pnpm install                      # Install dependencies
 pnpm build                        # Build for production
 pnpm preview                      # Preview production build (SSG + SPA)
 
+# Ship a site — `uniweb deploy` asks where, if you haven't chosen yet
+uniweb deploy                     # Wizard: pick a destination, then deploy (or set up CI)
+
 # Ship a site to Uniweb hosting (needs `uniweb login`)
 uniweb publish                    # The smart path: bring the foundation along (releasing it to the
                                   # catalog if its code changed), sync content, and go live
 
 # Ship a site to a third-party host instead
-uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, netlify,
-                                  # vercel, github-pages, s3-cloudfront, generic-static
+uniweb add ci --host=<adapter>    # Set up CI so every push deploys — usually the best answer for a
+                                  # free host. github-pages, cloudflare-pages, netlify, vercel
+uniweb deploy --host=<adapter>    # Build + upload now, from this machine. Same four, plus
+                                  # s3-cloudfront. Drives that host's CLI (wrangler/netlify/vercel/aws)
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
 
+# Publish a foundation for free, at permanent versioned URLs
+uniweb add ci --target foundation # GitHub Pages workflow → foundations/<name>/<version>/entry.js
+
 # Sync a site with the Uniweb backend (git-style; needs `uniweb login`)
 uniweb push                       # Push local content to the backend (creates the site on first push)
 uniweb pull                       # Pull backend content back to local files
@@ -174,6 +182,8 @@ uniweb <command> --help           # Per-command help (no side effects)
 
 `uniweb publish` brings the site's local foundation along — releasing it to the catalog under your `@org` when its code changed — so a single site needs no separate `uniweb register` step.
 
+**Choosing where a site goes.** `uniweb deploy` never assumes a host: with nothing configured it opens a picker listing only destinations it can actually act on, and records the choice in `deploy.yml` so later runs go straight there. For a free static host, prefer `uniweb add ci --host=<adapter>` over a manual `uniweb deploy` — one command, then every push deploys, and on Cloudflare Pages / Netlify / Vercel it also adds a per-PR preview that comments the URL on the pull request. Destination config (bucket, project name, site id) lives in `deploy.yml` beside `site.yml`; host credentials come from the environment, never from that committed file.
+
 **Registering data schemas.** A foundation that defines data schemas (`@/article`, …) uses `uniweb register` to register the foundation together with those schemas in the Uniweb registry — so content authors can create and manage entities of those types. It requires authentication: run `uniweb login`, or supply a bearer token directly with `--token <bearer>` (or the `UNIWEB_TOKEN` env var). Point at a specific registry with `--registry <url>` (or `UNIWEB_REGISTER_URL`). Preview without auth using `--dry-run` (or `-o <file>` to write the submission), and set the org scope with `--scope @org` (default: the foundation's `package.json` `uniweb.scope`).
 
 **Registering standard or shared schemas (no foundation).** Data schemas can also be registered on their own — without a foundation — straight from a schemas package. Run `uniweb register` from a package that *exports* schemas (`@uniweb/schemas`, or any `@org/schemas` you maintain), or from a bare folder of `schemas/*.{yml,json,js}` files: it detects the schemas-only package automatically and submits just the data schemas (no foundation) under `--scope`. This is how the standard schemas are published under `@std`, and how an org publishes its own shared `@org/schemas` once for many foundations to reference. The same flags apply (`--scope`, `--dry-run`, `-o`, `--token`, `--registry`); `--dry-run` (or `-o <file>`) previews the exact submission without authenticating.

package/src/commands/add.js

@@ -13,7 +13,7 @@
 
 import { existsSync } from 'node:fs'
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { join, relative, basename } from 'node:path'
 import prompts from 'prompts'
 import yaml from 'js-yaml'
 import { resolveFoundationSrcPath } from '@uniweb/build'
@@ -27,11 +27,11 @@ import {
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
 import { validatePackageName, getExistingPackageNames, resolveUniqueName } from '../utils/names.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
-import { detectPackageManager, filterCmd, installCmd } from '../utils/pm.js'
+import { detectPackageManager, detectWorkspacePm, filterCmd, installCmd } from '../utils/pm.js'
 import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from '../utils/interactive.js'
 import { resolveTemplate } from '../templates/index.js'
 import { validateTemplate } from '../templates/validator.js'
-import { getVersionsForTemplates, PNPM_VERSION } from '../versions.js'
+import { getVersionsForTemplates, resolveCiPnpmVersion, resolveCiNodeVersion } from '../versions.js'
 
 // Colors for terminal output
 const colors = {
@@ -64,16 +64,53 @@ function parseArgs(args) {
     host: null,
     force: false,
     domain: null,
+    // `add ci` only: what the workflow publishes ('site' | 'foundation'),
+    // the name to register under on the host, and whether to also
+    // scaffold PR-preview workflows.
+    target: null,
+    projectName: null,
+    previews: true,
   }
 
   // Booleans (no value) consumed up-front so the value-flag loop below
   // doesn't accidentally swallow the next positional.
-  const BOOLEAN_FLAGS = new Set(['--force'])
+  const BOOLEAN_FLAGS = new Set(['--force', '--no-previews'])
+
+  // Value flags, mapped to their result key. Both spellings are accepted:
+  // `--host github-pages` and `--host=github-pages`.
+  //
+  // The `=` form used to be dropped silently — every branch matched on an
+  // exact `args[i] === '--flag'`, so `--host=github-pages` fell through
+  // and left `host` null. It went unnoticed because `add ci` defaulted to
+  // github-pages when no host was given, making the one command our docs
+  // print (`uniweb add ci --host=github-pages`) appear to work while
+  // actually ignoring the flag. Requiring a real host surfaced it.
+  const VALUE_FLAGS = {
+    '--path': 'path',
+    '--project': 'project',
+    '--foundation': 'foundation',
+    '--site': 'site',
+    '--from': 'from',
+    '--host': 'host',
+    '--domain': 'domain',
+    '--target': 'target',
+    '--project-name': 'projectName',
+  }
+
+  /** Split `--flag=value` into [flag, value]; `--flag` into [flag, null]. */
+  const splitFlag = (arg) => {
+    const eq = arg.indexOf('=')
+    return eq === -1 ? [arg, null] : [arg.slice(0, eq), arg.slice(eq + 1)]
+  }
 
   // Find positional name (first arg after subcommand that's not a flag).
   for (let i = 1; i < args.length; i++) {
     if (args[i].startsWith('--')) {
-      if (!BOOLEAN_FLAGS.has(args[i])) i++ // skip flag value
+      const [flag, inlineValue] = splitFlag(args[i])
+      // Only skip the next arg when the value is genuinely separate.
+      // Previously an `=`-form flag also consumed the following arg,
+      // which could swallow the positional name.
+      if (!BOOLEAN_FLAGS.has(flag) && inlineValue === null) i++
       continue
     }
     if (!result.name) {
@@ -83,22 +120,18 @@ function parseArgs(args) {
 
   // Parse flags
   for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--path' && args[i + 1]) {
-      result.path = args[++i]
-    } else if (args[i] === '--project' && args[i + 1]) {
-      result.project = args[++i]
-    } else if (args[i] === '--foundation' && args[i + 1]) {
-      result.foundation = args[++i]
-    } else if (args[i] === '--site' && args[i + 1]) {
-      result.site = args[++i]
-    } else if (args[i] === '--from' && args[i + 1]) {
-      result.from = args[++i]
-    } else if (args[i] === '--host' && args[i + 1]) {
-      result.host = args[++i]
-    } else if (args[i] === '--domain' && args[i + 1]) {
-      result.domain = args[++i]
-    } else if (args[i] === '--force') {
+    const [flag, inlineValue] = splitFlag(args[i])
+    const key = VALUE_FLAGS[flag]
+    if (key) {
+      if (inlineValue !== null) {
+        result[key] = inlineValue
+      } else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--')) {
+        result[key] = args[++i]
+      }
+    } else if (flag === '--force') {
       result.force = true
+    } else if (flag === '--no-previews') {
+      result.previews = false
     }
   }
 
@@ -192,7 +225,16 @@ export async function add(rawArgs) {
       await addSection(rootDir, parsed)
       break
     case 'ci':
-      await addCi(rootDir, parsed, pm)
+      // The scaffolded workflow must install the way THIS WORKSPACE
+      // installs, which is a property of the repo (its lockfile), not of
+      // how the CLI happened to be launched. `detectPackageManager()`
+      // reads npm_config_user_agent, so `npx uniweb add ci` in a pnpm
+      // workspace produced a workflow running `npm ci` — which fails on
+      // the first CI run, because there is no package-lock.json to
+      // install from. npx is a normal way to run the CLI, so this broke
+      // the common case. Fall back to the invocation only when the repo
+      // has no lockfile to read.
+      await addCi(rootDir, parsed, detectWorkspacePm(rootDir) || pm)
       break
     default:
       error(`Unknown subcommand: ${parsed.subcommand}`)
@@ -962,18 +1004,65 @@ export default function ${name}({ content, params }) {
 async function addCi(rootDir, opts, pm = 'pnpm') {
   // Lazy-load the host registry so the CLI doesn't pay this import on
   // every add invocation.
-  let getAdapter
+  let getAdapter, listAdapters
   try {
-    ({ getAdapter } = await import('@uniweb/build/hosts'))
+    ({ getAdapter, listAdapters } = await import('@uniweb/build/hosts'))
   } catch {
     error('Failed to load host adapter registry from @uniweb/build/hosts.')
     process.exit(1)
   }
 
-  // Resolve host. With one CI-capable adapter today (github-pages),
-  // default silently when --host isn't passed. If more adapters add
-  // initCi later, this becomes a picker.
-  const host = opts.host || 'github-pages'
+  // What the workflow publishes. 'foundation' scaffolds the versioned
+  // distribution path (foundations/<name>/<version>/entry.js) — the free
+  // alternative to the catalog for a foundation product. Resolved BEFORE
+  // the host, because it narrows which hosts are even eligible.
+  const target = opts.target || 'site'
+  if (!['site', 'foundation'].includes(target)) {
+    error(`Unknown --target '${target}'. Expected 'site' or 'foundation'.`)
+    process.exit(1)
+  }
+
+  // Every adapter that can scaffold CI for this target. Derived from
+  // capability, never a hardcoded list — an adapter that grows an initCi
+  // shows up here with no edit to this file.
+  const ciHosts = listAdapters()
+    .map(name => getAdapter(name))
+    .filter(a => typeof a.initCi === 'function')
+    .filter(a => (target === 'foundation' ? a.display?.foundationCi === true : true))
+    .sort((a, b) => (a.display?.order ?? 999) - (b.display?.order ?? 999))
+
+  if (ciHosts.length === 0) {
+    error(`No host can scaffold CI for a ${target}.`)
+    process.exit(1)
+  }
+
+  let host = opts.host
+  if (!host) {
+    if (ciHosts.length === 1) {
+      host = ciHosts[0].name
+    } else if (isNonInteractive(process.argv)) {
+      error('`uniweb add ci` needs a host.')
+      log(`Available: ${ciHosts.map(a => a.name).join(', ')}`)
+      process.exit(1)
+    } else {
+      const choice = await prompts({
+        type: 'select',
+        name: 'host',
+        message: 'Which host should the workflow deploy to?',
+        choices: ciHosts.map(a => ({
+          title: `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`.trim().replace(/ ·\s*$/, ''),
+          description: a.display?.summary,
+          value: a.name,
+        })),
+      }, {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        },
+      })
+      host = choice.host
+    }
+  }
 
   let adapter
   try {
@@ -984,12 +1073,28 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   }
 
   if (typeof adapter.initCi !== 'function') {
-    error(`Host '${host}' does not provide a CI workflow yet.`)
-    log(`Currently supported: github-pages.`)
-    log(`Other hosts may use platform-side integrations (e.g., Vercel/Netlify connect via dashboard).`)
+    error(`Host '${host}' does not provide a CI workflow.`)
+    log(`Hosts that do: ${ciHosts.map(a => a.name).join(', ')}`)
+    log(`Others are dashboard-driven — connect the repo in the host's UI instead.`)
     process.exit(1)
   }
 
+  // Guard the explicit-host case. Without this, `--host netlify --target
+  // foundation` would call an initCi that ignores `target` and silently
+  // scaffold a SITE workflow — the wrong artifact, with no error.
+  if (target === 'foundation' && adapter.display?.foundationCi !== true) {
+    error(`Host '${host}' cannot publish a foundation.`)
+    log(`Hosts that can: ${ciHosts.map(a => a.name).join(', ')}`)
+    log('')
+    log('Foundation publishing needs permanent versioned URLs, which the')
+    log('gh-pages branch layout provides. Other hosts overwrite on deploy.')
+    process.exit(1)
+  }
+
+  if (target === 'foundation') {
+    return addFoundationCi(rootDir, { ...opts, host }, adapter, pm)
+  }
+
   // Validate --domain (lightweight: must look like a hostname). The
   // adapter decides what to do with it; today only github-pages uses
   // it (writes a CNAME, switches UNIWEB_BASE to root).
@@ -1048,7 +1153,11 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   const rootPkg = JSON.parse(
     await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
   )
-  const nodeVersion = parseNodeMajor(rootPkg.engines?.node) || '20'
+  // CI must run the project's own toolchain. The pnpm major comes from
+  // its `packageManager` field when declared; the node major is the
+  // project's floor, raised if that pnpm needs more.
+  const pnpmVersion = resolveCiPnpmVersion(rootPkg)
+  const nodeVersion = resolveCiNodeVersion(rootPkg.engines?.node, pm, pnpmVersion)
 
   const siteDir = join(rootDir, site.path)
   if (!resolvedDomain) {
@@ -1067,25 +1176,16 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   const result = await adapter.initCi({
     rootDir,
     site,
+    target: 'site',
     packageManager: pm,
     nodeVersion,
-    pnpmVersion: PNPM_VERSION,
+    pnpmVersion,
     domain: resolvedDomain,
+    previews: opts.previews !== false,
+    projectName: resolveHostProjectName(rootDir, rootPkg, site, sites.length, opts),
   })
 
-  // Write files. Refuse to overwrite without --force so re-running
-  // doesn't silently clobber edits the user made to the workflow.
-  for (const file of result.files) {
-    const fullPath = join(rootDir, file.path)
-    if (existsSync(fullPath) && !opts.force) {
-      error(`File already exists: ${file.path}`)
-      log(`Re-run with --force to overwrite.`)
-      process.exit(1)
-    }
-    await mkdir(join(fullPath, '..'), { recursive: true })
-    await writeFile(fullPath, file.content)
-    success(`Wrote ${file.path}`)
-  }
+  await writeCiFiles(rootDir, result.files, opts.force)
 
   // Persist the adapter's target config into deploy.yml so the user's
   // intent (host + adapter-specific fields like `domain`) is remembered
@@ -1124,6 +1224,151 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   }
 }
 
+/**
+ * The name to register this site under on the host (Cloudflare Pages
+ * project, etc.).
+ *
+ * The site package is very often called literally `site` — the scaffold's
+ * default — which makes a terrible project name on a shared host. So:
+ * an explicit `--project-name` wins; otherwise prefer the workspace's own
+ * name (usually the repo name) when the site's name is one of the generic
+ * scaffold defaults; suffix with the site name only when the workspace
+ * holds more than one site and they'd otherwise collide.
+ */
+const GENERIC_SITE_NAMES = new Set(['site', 'sites', 'www', 'web', 'app'])
+
+/**
+ * Public URL segment for a foundation published to GitHub Pages.
+ *
+ * Same problem as the site project name, and it matters more here:
+ * this segment is baked into a PERMANENT url that consuming sites pin
+ * (`foundations/<name>/<version>/entry.js`), so `src` — the single-project
+ * scaffold's directory *and* package name — would be a poor forever-name.
+ * Prefer a meaningful package/directory name; fall back to the workspace
+ * name; disambiguate only when several foundations would collide.
+ */
+const GENERIC_FOUNDATION_NAMES = new Set(['src', 'foundation', 'foundations', 'lib'])
+
+function resolveFoundationPublicNames(rootDir, rootPkg, foundations) {
+  const workspaceName = stripScope(rootPkg?.name) || basename(rootDir)
+
+  return foundations.map((f, i) => {
+    const pkgName = stripScope(f.name)
+    const dirName = basename(f.path)
+    const candidate = !GENERIC_FOUNDATION_NAMES.has(pkgName)
+      ? pkgName
+      : !GENERIC_FOUNDATION_NAMES.has(dirName)
+        ? dirName
+        : foundations.length > 1
+          ? `${workspaceName}-${i + 1}`
+          : workspaceName
+    return { name: candidate, path: f.path }
+  })
+}
+
+function resolveHostProjectName(rootDir, rootPkg, site, siteCount, opts) {
+  if (opts.projectName) return opts.projectName
+
+  const workspaceName = stripScope(rootPkg?.name) || basename(rootDir)
+  const siteName = stripScope(site.name)
+
+  if (!GENERIC_SITE_NAMES.has(siteName)) return siteName
+  if (siteCount > 1) return `${workspaceName}-${siteName}`
+  return workspaceName
+}
+
+function stripScope(name) {
+  if (!name || typeof name !== 'string') return null
+  return name.startsWith('@') ? name.split('/').pop() : name
+}
+
+/**
+ * Write scaffolded CI files. Refuses to overwrite without --force so
+ * re-running doesn't silently clobber edits the user made to a workflow.
+ */
+async function writeCiFiles(rootDir, files, force) {
+  for (const file of files) {
+    const fullPath = join(rootDir, file.path)
+    if (existsSync(fullPath) && !force) {
+      error(`File already exists: ${file.path}`)
+      log(`Re-run with --force to overwrite.`)
+      process.exit(1)
+    }
+    await mkdir(join(fullPath, '..'), { recursive: true })
+    await writeFile(fullPath, file.content)
+    success(`Wrote ${file.path}`)
+  }
+}
+
+/**
+ * `uniweb add ci --target foundation` — scaffold the workflow that
+ * publishes built foundations at permanent versioned URLs.
+ *
+ * This is the free distribution path for a foundation product: sites
+ * reference `https://<user>.github.io/<repo>/foundations/<name>/<ver>/entry.js`
+ * from site.yml. No catalog, no propagation, no license gating — but no
+ * cost either, and the URLs never break.
+ *
+ * Unlike the site path there is no deploy.yml to write: deploy.yml
+ * records where a *site* is deployed, and a foundation isn't a site.
+ */
+async function addFoundationCi(rootDir, opts, adapter, pm) {
+  const all = await discoverFoundations(rootDir)
+  if (all.length === 0) {
+    error('No foundation found in this workspace.')
+    log('Add one with `uniweb add foundation` first.')
+    process.exit(1)
+  }
+
+  // --foundation <name> narrows to one; otherwise publish them all,
+  // which is what a multi-foundation repo almost always wants (each gets
+  // its own versioned directory, so there's no collision).
+  let foundations = all
+  if (opts.foundation) {
+    const match = all.find(f => f.name === opts.foundation || basename(f.path) === opts.foundation)
+    if (!match) {
+      error(`Foundation '${opts.foundation}' not found.`)
+      log(`Available: ${all.map(f => f.name).join(', ')}`)
+      process.exit(1)
+    }
+    foundations = [match]
+  }
+
+  const rootPkg = JSON.parse(
+    await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
+  )
+  // CI must run the project's own toolchain. The pnpm major comes from
+  // its `packageManager` field when declared; the node major is the
+  // project's floor, raised if that pnpm needs more.
+  const pnpmVersion = resolveCiPnpmVersion(rootPkg)
+  const nodeVersion = resolveCiNodeVersion(rootPkg.engines?.node, pm, pnpmVersion)
+
+  let result
+  try {
+    result = await adapter.initCi({
+      rootDir,
+      foundations: resolveFoundationPublicNames(rootDir, rootPkg, foundations),
+      target: 'foundation',
+      packageManager: pm,
+      nodeVersion,
+      pnpmVersion,
+    })
+  } catch (err) {
+    error(err.message)
+    process.exit(1)
+  }
+
+  await writeCiFiles(rootDir, result.files, opts.force)
+
+  if (result.postInstructions?.length) {
+    log('')
+    log(`${colors.bright}Next steps:${colors.reset}`)
+    for (const line of result.postInstructions) {
+      log(line ? `  ${line}` : '')
+    }
+  }
+}
+
 function isLikelyDomain(value) {
   if (typeof value !== 'string' || value.length === 0 || value.length > 253) return false
   // Reject schemes, paths, ports, whitespace, leading/trailing dots/hyphens.
@@ -1173,10 +1418,21 @@ ${colors.bright}Section Options:${colors.reset}
   --foundation <n>   Foundation to add section to (prompted if multiple exist)
 
 ${colors.bright}CI Options:${colors.reset}
-  --host <name>      Host adapter (default: github-pages)
-  --site <name>      Site the workflow builds (prompted if multiple exist)
-  --domain <host>    Custom domain (writes CNAME, serves at root)
-  --force            Overwrite an existing workflow file
+  --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/foundation/ + docs/site/
@@ -1190,8 +1446,11 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add section Hero --foundation ui              # Target specific foundation
   uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
   uniweb add site --project docs                       # Create ./docs/site/ (co-located)
-  uniweb add ci                                        # Add GitHub Pages deploy workflow
+  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
 `)
 }

package/src/commands/build.js

@@ -919,8 +919,9 @@ function showNextSteps(hasFoundations, hasSites) {
   if (hasSites) {
     log('')
     log(`${colors.bright}Ship a site:${colors.reset}`)
-    log(`  ${colors.bright}uniweb publish${colors.reset}            Uniweb hosting (brings the foundation along)`)
-    log(`  ${colors.bright}uniweb deploy --host${colors.reset}=…    Third-party host`)
+    log(`  ${colors.bright}uniweb deploy${colors.reset}             Pick a host and ship (asks where, then remembers)`)
+    log(`  ${colors.bright}uniweb add ci --host${colors.reset}=…    Deploy on every push (free hosts; adds PR previews)`)
+    log(`  ${colors.bright}uniweb publish${colors.reset}            Uniweb Cloud (brings the foundation along)`)
     log(`  Or upload ${colors.cyan}dist/${colors.reset} (\`uniweb export\`) to any static host`)
   }
 }

package/src/commands/deploy.js

@@ -1,29 +1,41 @@
 /**
  * Deploy Command — ship a site to its resolved target.
  *
- * `uniweb deploy` resolves WHERE a site goes from deploy.yml (+ `--host` /
- * `--target`) and ships it there:
- *   - THIRD-PARTY host (`s3-cloudfront`, `cloudflare-pages`, `github-pages`,
- *     `generic-static`, …): build `dist/` in bundle mode and hand it to the
- *     host adapter for upload + invalidation.
- *   - UNIWEB hosting target (an explicit `--host=uniweb`, or a `uniweb` target
- *     in deploy.yml): DELEGATE to `uniweb publish` — the smart path (sync +
- *     dynamic hosting, brings the foundation along). So deploy.yml stays one
- *     actionable "where this site deploys" record, uniweb included.
+ * With a destination already known (a `--host` flag, or a target in
+ * deploy.yml) `uniweb deploy` acts on it directly. With NO destination
+ * known it runs the WIZARD — "Where should this site go?" — rather than
+ * assuming one. Assuming a host was the old behavior and it was wrong;
+ * so was the picker that replaced it, which listed every registered
+ * adapter when only one could actually be deployed to. The wizard offers
+ * only destinations that can be acted on, and says what acting will do.
  *
- * `uniweb publish` is the canonical direct verb for Uniweb hosting (reach for it
- * by default); `uniweb export` writes a self-contained artifact you upload
- * yourself.
+ * Four outcomes, from the wizard or resolved directly:
+ *   - THIRD-PARTY host, upload now: build `dist/` in bundle mode and hand
+ *     it to the adapter's deploy hook (`github-pages`, `cloudflare-pages`,
+ *     `netlify`, `vercel`, `s3-cloudfront`).
+ *   - THIRD-PARTY host, set up CI: delegate to `uniweb add ci --host=…`,
+ *     which scaffolds a workflow so every push deploys. For most free
+ *     hosts this is the better answer, and the wizard says so.
+ *   - UNIWEB hosting (`--host=uniweb`, or a `uniweb` target in deploy.yml,
+ *     or "Uniweb Cloud" in the wizard): DELEGATE to `uniweb publish` — the
+ *     smart path (sync + dynamic hosting, brings the foundation along). So
+ *     deploy.yml stays one actionable "where this site deploys" record.
+ *   - SOMEWHERE ELSE: delegate to `uniweb export` for a self-contained
+ *     artifact you upload yourself.
+ *
+ * `uniweb publish` remains the canonical direct verb for Uniweb hosting.
  *
  * Host resolution:
  *   1. --target <name> picks a target from deploy.yml (full config)
  *   2. deploy.yml's `default:` target when no flag is given
- *   3. with no deploy.yml at all, NO host is chosen → deploy prompts for a
- *      third-party adapter (interactive) rather than assuming Uniweb;
- *      non-interactive → an actionable error pointing at `publish` / `--host`
+ *   3. with no deploy.yml at all, NO host is chosen → the wizard runs
+ *      (interactive); non-interactive → an actionable error listing the
+ *      real options
  *   4. --host <name> is a one-off override (does NOT persist to deploy.yml)
+ *   5. --host with no value jumps straight to the wizard
  *
  * Usage:
+ *   uniweb deploy                  Wizard: pick a destination
  *   uniweb deploy --host <name>    Build bundle-mode dist/ + hand to the host adapter
  *   uniweb deploy --host=uniweb    Delegate to `uniweb publish` (Uniweb hosting)
  *   uniweb deploy --target <name>  Pick a target from deploy.yml
@@ -33,12 +45,12 @@
  * Escape hatch: UNIWEB_SKIP_BUILD=1 reuses an existing dist/.
  */
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { resolve, join } from 'node:path'
 import { execSync } from 'node:child_process'
 
 import { loadDeployYml, resolveTarget, recordLastDeploy } from '@uniweb/build/site'
-import { promptForHost } from '../utils/host-prompt.js'
+import { promptForDestination } from '../utils/destination-prompt.js'
 import { readFlagValue } from '../utils/args.js'
 import { parseBoolEnv } from '../utils/env.js'
 
@@ -76,10 +88,10 @@ export async function deploy(args = []) {
   // Host dispatch. Resolution order:
   //   1. --target <name> picks a target from deploy.yml
   //   2. deploy.yml's `default:` target when no flag is given
-  //   3. with no deploy.yml, the implicit default is host: 'uniweb'
+  //   3. with no deploy.yml, NO host is chosen → the wizard decides
   //   4. --host <name> is a one-off override (does not persist on success)
   const targetFromFlag = readFlagValue(args, '--target')
-  let hostFromFlag = readFlagValue(args, '--host')
+  const hostFromFlag = readFlagValue(args, '--host')
   const noSave = args.includes('--no-save')
 
   let deployYml
@@ -96,50 +108,94 @@ export async function deploy(args = []) {
     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)
-    }
-  }
-  let host = hostFromFlag || resolved.host
-
-  // A Uniweb-hosting target is `publish`'s flow. When the user EXPLICITLY chose
-  // uniweb (a `--host=uniweb`, or a `uniweb` target in deploy.yml), DELEGATE to
-  // `uniweb publish` so deploy.yml stays one actionable record. When NO host was
-  // chosen (the implicit default with no deploy.yml), don't assume uniweb:
-  // prompt for a third-party adapter (interactive) or point at publish / --host
-  // (non-interactive). promptForHost lists only third-party adapters.
-  if (host === 'uniweb') {
-    const explicitUniweb = hostFromFlag === 'uniweb' || (resolved.fromFile && resolved.host === 'uniweb')
-    if (explicitUniweb) {
-      say.info('Uniweb hosting target → running `uniweb publish`.')
-      console.log('')
-      // publish ignores deploy's --host/--target; --dry-run/--no-save/--backend
-      // /--token pass straight through.
-      const { publish } = await import('./publish.js')
-      const result = await publish(args)
-      process.exit(result?.exitCode ?? 0)
-    }
+
+  // Resolve a PLAN — {kind, host?, action?} — before doing anything. A
+  // destination is "known" when the user named it (--host) or deploy.yml
+  // records one. Otherwise the wizard asks; we never assume.
+  //
+  // resolveTarget returns host:'uniweb' with fromFile:false as its
+  // no-deploy.yml fallback. That is NOT a chosen destination — treat it
+  // as "unknown" so a bare `deploy` in a fresh project opens the wizard
+  // instead of silently heading for the paid product.
+  let plan
+  // `--host` with NO value (readFlagValue → null) is an explicit "ask me",
+  // and it must outrank deploy.yml: the user typed the flag precisely to
+  // choose something other than what's recorded. Omitting the flag
+  // entirely (→ undefined) is the different case where deploy.yml wins.
+  const wantsWizard = hostFromFlag === null
+  const knownHost = wantsWizard
+    ? null
+    : (hostFromFlag || (resolved.fromFile ? resolved.host : null))
+
+  if (knownHost === 'uniweb') {
+    plan = { kind: 'uniweb' }
+  } else if (knownHost) {
+    plan = { kind: 'adapter', host: knownHost, action: 'deploy' }
+  } else {
     if (isNonInteractive(args)) {
-      say.err('`uniweb deploy` needs a host. For Uniweb hosting use `uniweb publish`; for a third-party host pass `--host=<adapter>`.')
+      if (wantsWizard) {
+        // They asked to pick, but there's no way to ask. Never silently
+        // fall back to deploy.yml — that would deploy somewhere the user
+        // was in the middle of overriding.
+        const { listAdapters } = await import('@uniweb/build/hosts')
+        say.err('`--host` requires a value when running non-interactively.')
+        say.dim(`Known adapters: ${listAdapters().join(', ')}.`)
+        say.dim('For Uniweb Cloud use `uniweb publish` (or --host=uniweb).')
+        process.exit(1)
+      }
+      say.err('`uniweb deploy` needs a destination.')
       console.log('')
-      say.dim('`uniweb publish`          Uniweb hosting (sync + dynamic hosting; brings the foundation along)')
-      say.dim('`uniweb deploy --host=…`  Third-party host (s3-cloudfront, cloudflare-pages, github-pages, generic-static)')
+      say.dim('`uniweb publish`          Uniweb Cloud (sync + dynamic hosting; brings the foundation along)')
+      say.dim('`uniweb deploy --host=…`  A third-party host — run `uniweb deploy --help` for the list')
+      say.dim('`uniweb add ci --host=…`  Set up CI so every push deploys')
       say.dim('`uniweb export`           Self-contained dist/ artifact you upload anywhere')
       process.exit(1)
     }
-    say.info('`uniweb deploy` ships to a third-party host. (For Uniweb hosting, run `uniweb publish`.)')
     try {
-      host = await promptForHost({ args })
+      plan = await promptForDestination({ args, preselect: resolved.fromFile ? resolved.host : null })
     } catch (err) {
       say.err(err.message)
       process.exit(1)
     }
+    if (!plan) {
+      console.log('\nDeploy cancelled.')
+      process.exit(0)
+    }
+  }
+
+  // Uniweb Cloud is `publish`'s flow — delegate so deploy.yml stays one
+  // actionable record and there's a single implementation of go-live.
+  if (plan.kind === 'uniweb') {
+    say.info('Uniweb Cloud → running `uniweb publish`.')
+    console.log('')
+    // publish ignores deploy's --host/--target; --dry-run/--no-save/--backend
+    // /--token pass straight through.
+    const { publish } = await import('./publish.js')
+    const result = await publish(args)
+    process.exit(result?.exitCode ?? 0)
+  }
+
+  if (plan.kind === 'export') {
+    // `export` has no --dry-run of its own, so handle it here rather than
+    // passing a flag it would ignore — a dry run that actually ran a full
+    // build would be a lie.
+    if (dryRun) {
+      say.info('Dry run — would run `uniweb export` to build a self-contained dist/.')
+      return
+    }
+    say.info('Building a self-contained artifact → running `uniweb export`.')
+    console.log('')
+    const { exportSite } = await import('./export.js')
+    await exportSite([])
+    return
+  }
+
+  // CI setup is `add ci`'s job. Shell out rather than re-implement: add
+  // owns site discovery, package-manager detection, the --force guard,
+  // and the deploy.yml target write.
+  if (plan.action === 'ci') {
+    await delegateToAddCi(siteDir, plan.host, dryRun)
+    return
   }
 
   // Auto-save scope: 'off' from --no-save OR an ad-hoc --host override (we don't
@@ -148,13 +204,48 @@ export async function deploy(args = []) {
   const hostOverridden = !!hostFromFlag && hostFromFlag !== resolved.host
   const autoSave = noSave || hostOverridden ? 'off' : resolved.autoSave
 
-  await deployStaticHost(siteDir, host, resolved, {
+  await deployStaticHost(siteDir, plan.host, resolved, {
     dryRun,
     autoSave,
     hostOverridden,
   })
 }
 
+// ─── CI delegation ──────────────────────────────────────────
+
+async function delegateToAddCi(siteDir, host, dryRun) {
+  const workspaceRoot = findWorkspaceRoot(siteDir) || siteDir
+
+  // Forward the site we already resolved. Without this, `add ci` re-runs
+  // its own discovery and asks "which site?" a second time in a
+  // multi-site workspace — right after the user answered that in the
+  // wizard. `add ci --site` matches on the package name.
+  let siteFlag = ''
+  try {
+    const pkg = JSON.parse(readFileSync(join(siteDir, 'package.json'), 'utf8'))
+    if (pkg.name) siteFlag = ` --site ${JSON.stringify(pkg.name)}`
+  } catch {
+    // No readable package.json — let `add ci` resolve the site itself.
+  }
+
+  const cmd = `add ci --host ${JSON.stringify(host)}${siteFlag}`
+  if (dryRun) {
+    say.info(`Dry run — would run \`uniweb ${cmd}\` in ${workspaceRoot}`)
+    return
+  }
+  say.info(`Setting up CI → running \`uniweb ${cmd}\`.`)
+  console.log('')
+  try {
+    execSync(`node ${JSON.stringify(process.argv[1])} ${cmd}`, {
+      cwd: workspaceRoot,
+      stdio: 'inherit',
+    })
+  } catch {
+    // add ci already printed the reason and set the exit code.
+    process.exit(1)
+  }
+}
+
 // ─── Static-host deploy (S3+CloudFront, etc.) ─────────────────
 //
 // Picked when the resolved deploy.yml target (or --host override) names a
@@ -193,13 +284,23 @@ async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave,
 
   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(`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)'}`)
+    say.dim(`Site dir  : ${siteDir}`)
+    say.dim(`dist/     : ${existsSync(distDir) ? 'exists (would not rebuild)' : 'missing (would build)'}`)
+    say.dim(`Target    : ${resolved.targetName}`)
+    if (adapter.display?.pushWith) say.dim(`Uploads by: ${adapter.display.pushWith}`)
+    // Echo the resolved target's config as-is. Each adapter reads
+    // different keys (bucket/distributionId for s3, projectName for
+    // Cloudflare, siteId for Netlify), so listing a fixed set would be
+    // wrong for four of the five.
+    const configKeys = Object.keys(deployConfig)
+    if (configKeys.length) {
+      say.dim('Config    :')
+      for (const key of configKeys.sort()) {
+        say.dim(`  ${key}: ${typeof deployConfig[key] === 'object' ? JSON.stringify(deployConfig[key]) : deployConfig[key]}`)
+      }
+    } else {
+      say.dim('Config    : (none in deploy.yml — the adapter will say what it needs)')
+    }
     return
   }
 
@@ -234,8 +335,9 @@ async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave,
 
   // Hand off to the adapter. DeployError is the structured shape from
   // @uniweb/build/hosts/s3-cloudfront — translate to user-facing output.
+  let deployResult
   try {
-    await adapter.deploy({
+    deployResult = await adapter.deploy({
       distDir,
       deployConfig,
       env: process.env,
@@ -262,8 +364,12 @@ async function deployStaticHost(siteDir, hostName, resolved, { dryRun, 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.
+      // Adapters that drive a host CLI get the public URL back from it
+      // (wrangler/netlify/vercel print it; github-pages derives it from
+      // the git remote). s3-cloudfront can't — the public URL lives in
+      // the user's CloudFront/DNS config, which we never see — so the
+      // field is simply omitted there rather than guessed.
+      ...(deployResult?.url ? { url: deployResult.url } : {}),
     },
   })
   if (hostOverridden && !dryRun) {

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-18T13:09:21.219Z",
+  "generatedAt": "2026-07-21T20:48:30.091Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.28",
+      "version": "0.14.30",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.35",
+      "version": "0.4.37",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -1092,40 +1092,42 @@ function printCommandHelp(command) {
   if (command === 'release') command = 'register'
   const blocks = {
     deploy: `
-${colors.cyan}${colors.bright}uniweb deploy${colors.reset} ${colors.dim}— Ship a site to its resolved target${colors.reset}
+${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 --host <name> [options]
+  uniweb deploy [options]
 
-Ships a site to its resolved target. A THIRD-PARTY host builds dist/ (bundle
-mode) and hands it to a host adapter for upload + invalidation. A UNIWEB target
-(\`--host=uniweb\`, or a \`uniweb\` target in deploy.yml) delegates to
-${colors.cyan}uniweb publish${colors.reset} (sync + dynamic serving; brings the foundation along) — the
-canonical direct verb for Uniweb hosting. With no host chosen, deploy prompts for
-a third-party adapter. For a self-contained dist/ you upload yourself, use
-${colors.cyan}uniweb export${colors.reset}.
+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}
-  uniweb              Uniweb hosting (delegates to \`uniweb publish\`)
-  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
+  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 → interactive third-party picker, TTY only)
+  --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           Skip the auto-save of lastDeploy in deploy.yml
   --non-interactive   Fail with usage info instead of prompting
 
 ${colors.bright}Examples:${colors.reset}
-  uniweb deploy --host=cloudflare-pages      # Build + upload to Cloudflare Pages
+  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}
@@ -1223,6 +1225,7 @@ ${colors.bright}Subcommands:${colors.reset}
   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)
+  add ci                  Add a CI workflow so every push deploys (--host, --target)
 
 ${colors.bright}Common options:${colors.reset}
   --from <template>       Source content from a template
@@ -1480,7 +1483,7 @@ ${colors.bright}Commands:${colors.reset}
   dev                Start a dev server for a site
   build              Build the current project
   publish            Publish a site to Uniweb hosting (smart: foundation + sync + go live)
-  deploy             Deploy a site to a third-party host (--host=<adapter>)
+  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)
@@ -1509,6 +1512,7 @@ ${colors.bright}Add Subcommands:${colors.reset}
   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)
+  add ci                  Add a CI workflow so every push deploys (--host, --target)
 
 ${colors.bright}Global Options:${colors.reset}
   --version, -v        Show version
@@ -1528,13 +1532,13 @@ ${colors.bright}Publish Options:${colors.reset}
   \`uniweb deploy --host=<name>\`.
 
 ${colors.bright}Deploy Options:${colors.reset}
-  --host <name>      The host to ship to (no value → interactive third-party
-                     picker, TTY only). Third-party: cloudflare-pages, netlify,
-                     vercel, github-pages, s3-cloudfront, generic-static.
-                     \`--host=uniweb\` delegates to \`uniweb publish\`.
+  --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          Skip the auto-save of lastDeploy in deploy.yml
+  To deploy on every push instead, see \`uniweb add ci --help\`.
 
 ${colors.bright}Dev Options:${colors.reset}
   <site>             Site name to run (positional)

package/src/utils/destination-prompt.js

@@ -0,0 +1,136 @@
+/**
+ * The deploy wizard — "Where should this site go?"
+ *
+ * Distinct from `host-prompt.js`, and the split matters. `promptForHost`
+ * answers a *build* question — which host-specific helper files should
+ * land in `dist/` — so it lists every registered adapter, including
+ * shape-only entries like `generic-static`. This module answers a
+ * *shipping* question, so it lists destinations you can actually act on
+ * and says what acting will do.
+ *
+ * The bug that motivated the split: the deploy path used to reuse
+ * `promptForHost`, offering six adapters when only one implemented a
+ * deploy hook. Five of six choices dead-ended on "does not implement a
+ * deploy step". A picker must never offer a door that doesn't open — so
+ * entries are derived from real adapter capability (`deploy` / `initCi`),
+ * not from a registry key list.
+ *
+ * Two synthetic entries round out the menu:
+ *   - Uniweb Cloud — not an adapter; it delegates to `uniweb publish`.
+ *     Listed after the third-party hosts rather than first: the framework
+ *     is backend-optional and standalone-first, so leading a generic
+ *     `deploy` with the paid product would read as an upsell.
+ *   - Somewhere else — delegates to `uniweb export`.
+ */
+
+import { promptSelect } from './workspace.js'
+import { isNonInteractive } from './interactive.js'
+
+export const UNIWEB_DESTINATION = {
+  value: { kind: 'uniweb' },
+  title: 'Uniweb Cloud · paid, dynamic + visual editing',
+  description:
+    'Sync + dynamic SSR, visual editing for content authors, foundation propagation. Runs `uniweb publish`.',
+}
+
+export const EXPORT_DESTINATION = {
+  value: { kind: 'export' },
+  title: 'Somewhere else · export a folder',
+  description:
+    'Builds a self-contained dist/ you upload yourself. Runs `uniweb export`.',
+}
+
+/**
+ * Build the destination list from the adapter registry.
+ *
+ * @returns {Promise<Array<{value: object, title: string, description: string}>>}
+ */
+export async function buildDestinationChoices() {
+  const { listAdapters, getAdapter } = await import('@uniweb/build/hosts')
+
+  const adapters = listAdapters()
+    .map(name => getAdapter(name))
+    .filter(a => a.display?.wizard !== false)
+    // Never offer a door that doesn't open.
+    .filter(a => typeof a.deploy === 'function' || typeof a.initCi === 'function')
+    .sort((a, b) => (a.display?.order ?? 999) - (b.display?.order ?? 999))
+
+  const choices = adapters.map(a => ({
+    value: { kind: 'adapter', host: a.name },
+    title: `${a.display?.title || a.name} · ${a.display?.qualifier || ''}`.trim().replace(/ ·\s*$/, ''),
+    description: a.display?.summary || '',
+  }))
+
+  return [...choices, UNIWEB_DESTINATION, EXPORT_DESTINATION]
+}
+
+/**
+ * Ask *how* to ship to an adapter that supports both paths. Skipped when
+ * the adapter only supports one — no point asking a question with a
+ * single answer.
+ *
+ * @returns {Promise<'ci'|'deploy'|null>} null when cancelled.
+ */
+async function promptForAction(adapter) {
+  const canCi = typeof adapter.initCi === 'function'
+  const canDeploy = typeof adapter.deploy === 'function'
+
+  if (canCi && !canDeploy) return 'ci'
+  if (canDeploy && !canCi) return 'deploy'
+
+  const label = adapter.display?.title || adapter.name
+  const previews = adapter.display?.previews
+    ? ' Pull requests get their own preview URL.'
+    : ''
+
+  return promptSelect(`${label} — how?`, [
+    {
+      value: 'ci',
+      title: 'Set it up to deploy on every push · recommended',
+      description:
+        `Writes a GitHub Actions workflow. One-time setup — after this, pushing to the default branch deploys.${previews}`,
+    },
+    {
+      value: 'deploy',
+      title: 'Upload from this machine now',
+      description:
+        `Builds dist/ here and pushes it with ${adapter.display?.pushWith || 'the host CLI'}.`,
+    },
+  ])
+}
+
+/**
+ * Run the wizard.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.args — Argv, used only to gate non-interactive mode.
+ * @param {string|null} [opts.preselect] — Host name to float to the top, so
+ *   Enter repeats what deploy.yml already records.
+ * @returns {Promise<{kind: string, host?: string, action?: string}|null>}
+ *   null when the user cancels.
+ * @throws {Error} When non-interactive — the caller prints the guidance.
+ */
+export async function promptForDestination({ args = [], preselect = null } = {}) {
+  if (isNonInteractive(args)) {
+    throw new Error('Cannot prompt for a destination when running non-interactively.')
+  }
+
+  let choices = await buildDestinationChoices()
+
+  // Float the remembered target so Enter does the obvious thing.
+  if (preselect) {
+    const idx = choices.findIndex(c => c.value.kind === 'adapter' && c.value.host === preselect)
+    if (idx > 0) choices = [choices[idx], ...choices.filter((_, i) => i !== idx)]
+  }
+
+  const picked = await promptSelect('Where should this site go?', choices)
+  if (!picked) return null
+  if (picked.kind !== 'adapter') return picked
+
+  const { getAdapter } = await import('@uniweb/build/hosts')
+  const adapter = getAdapter(picked.host)
+  const action = await promptForAction(adapter)
+  if (!action) return null
+
+  return { ...picked, action }
+}

package/src/utils/workspace.js

@@ -188,10 +188,16 @@ export function isWorkspaceRoot(dir = process.cwd()) {
 }
 
 /**
- * Interactive prompt to select from multiple options
+ * Interactive prompt to select from multiple options.
+ *
+ * Accepts plain strings (title === value) or `{ title, value, description }`
+ * objects. `prompts` reveals a choice's description only while that row is
+ * highlighted, so put the always-visible qualifier in `title` and the
+ * fuller explanation in `description`.
+ *
  * @param {string} message - Prompt message
- * @param {string[]} choices - Array of choices
- * @returns {Promise<string|null>} - Selected choice or null if cancelled
+ * @param {Array<string|{title: string, value?: any, description?: string}>} choices
+ * @returns {Promise<any|null>} - Selected value, or null if cancelled
  */
 export async function promptSelect(message, choices) {
   const prompts = (await import('prompts')).default
@@ -200,8 +206,12 @@ export async function promptSelect(message, choices) {
     type: 'select',
     name: 'value',
     message,
-    choices: choices.map(c => ({ title: c, value: c })),
+    choices: choices.map(c => (
+      typeof c === 'string'
+        ? { title: c, value: c }
+        : { title: c.title, value: c.value !== undefined ? c.value : c.title, description: c.description }
+    )),
   })
 
-  return response.value || null
+  return response.value ?? null
 }

package/src/versions.js

@@ -53,16 +53,86 @@ let resolvedVersions = null
 export const REACT_VERSION = '^19.0.0'
 
 /**
- * The pnpm major the framework's generated CI standardizes on.
+ * Default pnpm major for generated CI, used only when the project does not
+ * say which pnpm it uses (see `resolveCiPnpmVersion`).
  *
- * Scaffolded CI workflows (`uniweb add ci --host=github-pages`) pin pnpm
- * through `pnpm/action-setup`. This is the one place that value lives, so the
- * pin tracks a single supported major instead of drifting as a hardcoded
- * literal inside each host adapter. A bare major installs the latest patch of
- * that major at CI run time. Bump this when the framework moves to a new pnpm
- * major (latest stable is 11.x as of this writing; pnpm 12 is still alpha).
+ * **This is deliberately 10, not the newest release.** CI must run the same
+ * toolchain the developer runs, or it reports failures that have nothing to
+ * do with their code. Pinning 11 while projects were on 10 produced exactly
+ * that, twice over, on a real repo:
+ *
+ *   - pnpm 11 refuses any dependency published in the last 24 hours
+ *     (`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`). Publish a package and its
+ *     consumer's CI fails until the next day.
+ *   - pnpm 11 changed build-script approval: `onlyBuiltDependencies` in
+ *     `pnpm-workspace.yaml` no longer suffices, and the install exits 1 with
+ *     `ERR_PNPM_IGNORED_BUILDS`. Uniweb sites use `sharp` for image
+ *     processing, so this breaks essentially every site's first CI run.
+ *
+ * Neither is a bug in pnpm — both are reasonable hardening. They are simply
+ * not things a generated workflow should impose on a project that has not
+ * opted into that major.
+ *
+ * A bare major installs the latest patch of that major at CI run time. Before
+ * bumping this, check the new major's release notes for install-time policy
+ * changes, and update `PNPM_MIN_NODE` in the same commit.
  */
-export const PNPM_VERSION = '11'
+export const PNPM_VERSION = '10'
+
+/**
+ * Minimum Node major each supported pnpm major will run on, from that
+ * release's own `engines.node`.
+ *
+ * pnpm 11 declares `>=22.13` and imports `node:sqlite`, which does not exist
+ * before Node 22 — pairing it with Node 20 fails at `pnpm install` with
+ * `ERR_UNKNOWN_BUILTIN_MODULE` before the build is attempted. That was the
+ * default until 2026-07-21, because the CI node major came from the
+ * project's `engines.node` and the workspace template declares `>=20.19`.
+ *
+ * Verify with `npm view pnpm@<major> engines` when adding an entry.
+ */
+export const PNPM_MIN_NODE = { '10': 18, '11': 22 }
+
+/**
+ * Resolve the pnpm major a generated CI workflow should install.
+ *
+ * `packageManager` (the corepack field) is authoritative when present — it is
+ * the project stating which pnpm it is developed and locked against, so CI
+ * should honour it rather than impose a different major.
+ *
+ * `pnpm-lock.yaml`'s `lockfileVersion` is NOT usable as a signal: pnpm 10 and
+ * 11 both write `9.0`, so it cannot distinguish them. Checked, not assumed.
+ *
+ * @param {object|null} rootPkg — the workspace root's parsed package.json.
+ * @returns {string} pnpm major, as a string for YAML interpolation.
+ */
+export function resolveCiPnpmVersion(rootPkg) {
+  const declared = rootPkg?.packageManager
+  const match = typeof declared === 'string' ? declared.match(/^pnpm@(\d+)/) : null
+  return match ? match[1] : PNPM_VERSION
+}
+
+/**
+ * Resolve the Node major a generated CI workflow should install.
+ *
+ * Respects the project's own floor (`engines.node`) but never drops below
+ * what the pinned package manager needs. The project's declared minimum is a
+ * *lower* bound on what its code needs, not a ceiling — running CI on a newer
+ * Node is fine; running it on one the package manager refuses to start on is
+ * not.
+ *
+ * @param {string|null|undefined} enginesNode — the project's `engines.node`.
+ * @param {'pnpm'|'npm'|'yarn'} packageManager
+ * @param {string} [pnpmVersion] — the resolved pnpm major, when pnpm.
+ * @param {string} [fallback='20'] — used when engines.node is absent/unparseable.
+ * @returns {string} Node major, as a string for YAML interpolation.
+ */
+export function resolveCiNodeVersion(enginesNode, packageManager, pnpmVersion = PNPM_VERSION, fallback = '20') {
+  const match = enginesNode ? String(enginesNode).match(/(\d+)/) : null
+  const declared = match ? Number(match[1]) : Number(fallback)
+  const floor = packageManager === 'pnpm' ? (PNPM_MIN_NODE[pnpmVersion] ?? 0) : 0
+  return String(Math.max(declared, floor))
+}
 
 /**
  * Get the CLI's own package.json