uniweb 0.12.14 → 0.12.16

package/README.md

@@ -294,38 +294,65 @@ pnpm dev     # or npm run dev
 
 The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. The name you provide becomes both the directory name and the package name. Use `--path` to override default placement, or `--project` for explicit co-located layouts.
 
-## The Bigger Picture
+## Deployment
 
-The structure you start with scales without rewrites:
+A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code). **Who manages the content** decides what you ship:
 
-1. **Single project** — One site, one foundation. Develop and deploy together. Most projects stay here.
+- If you (or your dev team) manage the content, you ship them together — the site and its foundation, bundled or linked.
+- If someone else manages the content, you ship only the foundation. Content authors compose sites in the Uniweb apps; there's no site to deploy from your repo.
 
-2. **Published foundation** — Release your foundation as a dynamically linked module to [uniweb.app](https://uniweb.app). Other sites can use it without copying code.
+### Path 1 — You manage the content
 
-3. **Multiple sites** — Several sites share one foundation. Update components once, every site benefits.
+You (or your dev team) write the markdown. Deploy site + foundation together.
 
-4. **Platform-managed sites** — Sites built on [uniweb.app](https://uniweb.app) with visual editing tools can use your foundation. You develop components locally; content teams work in the browser.
+The shortest path to a live site is free, on GitHub Pages, with a custom domain:
 
-Start with local files deployed anywhere. The same foundation works across all these scenarios.
+```bash
+npm create uniweb my-site
+cd my-site
+uniweb add ci --host=github-pages
+# Commit, push to GitHub, enable Pages in repo settings → live site
+```
 
-## Deployment
+`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.
+
+**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.
+
+### Path 2 — Someone else manages the content
+
+You're building a foundation for clients, content authors, or any team that won't write markdown. The foundation is your product; the repo's `site/` is a test harness for the code (run `pnpm dev` to preview your components against sample content). You don't deploy a site — you publish a foundation:
 
-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:
+```bash
+cd src
+uniweb publish @your-org/foundation-name
+```
+
+Real sites built on your foundation are managed in the **Uniweb apps** (web + desktop) — visual editors designed for non-technical authors. They never see git, markdown, yaml, or React. They see *your* components, with live previews and visual controls for the params you defined. The foundation becomes the editor's native vocabulary for that site: you keep creative control of the design system, they get an editor that feels custom-built for them.
+
+This is the best path when site content has a life independent of the foundation's release cycle — agencies, design studios, multi-client teams, or any project where content authors aren't the same people as the developers.
 
-- **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 private catalog product, published once and licensed to consuming sites (`foundation: '@<org>/<name>@<version>'`).
+### Roadmap — Hybrid
 
-`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.
+A future version will let markdown in a git repo and content in the Uniweb apps stay in two-way sync. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. On the roadmap; not available today.
 
-Where can you deploy?
+### Commands at a glance
 
-- **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.
+| 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` | Deploy to Uniweb hosting (default). With `--host=<adapter>`, push directly to a static host — builds, uploads, invalidates in one step. |
+| `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
+| `uniweb publish @org/name` | Publish a foundation to the registry (path 2). |
+| `uniweb build` | Inspect a build locally. For shipping, use `deploy` or `export`. |
+| `uniweb update` | Reconcile workspace state with the CLI: self-update the global install, align `@uniweb/*` deps in every `package.json` to the CLI's matrix, refresh `AGENTS.md`. Refuses to outpace declared deps with a stale doc. |
+
+`--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.
+
+---
 
-→ **[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.
+Both paths use the same framework. The difference is who edits content, where it lives, and what gets deployed. For the deeper menu — site-bound vs cataloged foundations, S3+CloudFront, manual exports, per-host recipes, foundation propagation — see → **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)**.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.14",
+  "version": "0.12.16",
   "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/runtime": "0.8.13",
     "@uniweb/kit": "0.9.11",
+    "@uniweb/runtime": "0.8.13",
     "@uniweb/core": "0.7.11"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.2",
+    "@uniweb/build": "0.14.3",
     "@uniweb/content-reader": "1.1.10",
     "@uniweb/semantic-parser": "1.1.17"
   },

package/partials/agents.md

@@ -150,6 +150,9 @@ uniweb deploy --dry-run           # Resolve foundation/runtime + print summary;
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
 uniweb publish                    # Publish a foundation to the Uniweb registry
 uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
+uniweb update                     # Reconcile workspace state with the CLI: align @uniweb/*
+                                  # deps in every package.json + refresh this AGENTS.md.
+                                  # Use --dry-run to preview, --deps-only to skip the doc.
 
 # Help
 uniweb --help                     # Top-level help
@@ -158,6 +161,8 @@ 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.
 
+If this AGENTS.md was stamped against an older CLI than the workspace's installed `@uniweb/*` packages, run `uniweb update --dry-run` to see the gap. The verb refuses to refresh the doc while declared deps lag the CLI — a stale doc that documents features the installed code doesn't have is worse than no refresh.
+
 ---
 
 ## `package.json` `uniweb` configuration

package/src/commands/add.js

@@ -54,19 +54,26 @@ function info(message) { console.log(`${colors.dim}${message}${colors.reset}`) }
  */
 function parseArgs(args) {
   const result = {
-    subcommand: args[0],   // foundation, site, extension
+    subcommand: args[0],   // foundation, site, extension, ci, …
     name: null,
     path: null,
     project: null,
     foundation: null,
     site: null,
     from: null,
+    host: null,
+    force: false,
+    domain: null,
   }
 
-  // Find positional name (first arg after subcommand that's not a flag)
+  // 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'])
+
+  // Find positional name (first arg after subcommand that's not a flag).
   for (let i = 1; i < args.length; i++) {
     if (args[i].startsWith('--')) {
-      i++ // skip flag value
+      if (!BOOLEAN_FLAGS.has(args[i])) i++ // skip flag value
       continue
     }
     if (!result.name) {
@@ -86,6 +93,12 @@ function parseArgs(args) {
       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') {
+      result.force = true
     }
   }
 
@@ -126,9 +139,10 @@ export async function add(rawArgs) {
         { label: 'site', description: 'Content site' },
         { label: 'extension', description: 'Additional component package' },
         { label: 'section', description: 'Section type in a foundation' },
+        { label: 'ci', description: 'CI deploy workflow for a host (e.g., GitHub Pages)' },
       ]))
       log('')
-      log(`Usage: ${prefix} add <project|foundation|site|extension|section> [name]`)
+      log(`Usage: ${prefix} add <project|foundation|site|extension|section|ci> [name]`)
       process.exit(1)
     }
 
@@ -142,6 +156,7 @@ export async function add(rawArgs) {
         { title: 'Site', value: 'site', description: 'Content site' },
         { title: 'Extension', value: 'extension', description: 'Additional component package' },
         { title: 'Section', value: 'section', description: 'Section type in a foundation' },
+        { title: 'CI workflow', value: 'ci', description: 'Deploy workflow for a host (e.g., GitHub Pages)' },
       ],
     }, {
       onCancel: () => {
@@ -176,9 +191,12 @@ export async function add(rawArgs) {
     case 'section':
       await addSection(rootDir, parsed)
       break
+    case 'ci':
+      await addCi(rootDir, parsed, pm)
+      break
     default:
       error(`Unknown subcommand: ${parsed.subcommand}`)
-      log(`Valid subcommands: project, foundation, site, extension, section`)
+      log(`Valid subcommands: project, foundation, site, extension, section, ci`)
       process.exit(1)
   }
 }
@@ -865,7 +883,7 @@ async function wireExtensionToSite(rootDir, siteName, extensionName, extensionPa
     const config = yaml.load(content) || {}
 
     // Add extension URL
-    const extensionUrl = `/${extensionPath}/dist/foundation.js`
+    const extensionUrl = `/${extensionPath}/dist/entry.js`
     if (!config.extensions) {
       config.extensions = []
     }
@@ -1017,6 +1035,195 @@ export default function ${name}({ content, params }) {
   }
 }
 
+/**
+ * Add a CI deploy workflow for a host adapter.
+ *
+ * Wires through the host-adapter registry: each adapter optionally
+ * exports `initCi({ rootDir, site, packageManager, nodeVersion })`
+ * returning `{ files, postInstructions }`. The CLI handles file writes,
+ * --force overwrite, and consistent output. Today only github-pages
+ * implements initCi; the registry's other adapters (cloudflare-pages,
+ * vercel, s3-cloudfront, generic-static) error out with a clear message
+ * and can plug in later.
+ */
+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
+  try {
+    ({ getAdapter } = 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'
+
+  let adapter
+  try {
+    adapter = getAdapter(host)
+  } catch (err) {
+    error(err.message)
+    process.exit(1)
+  }
+
+  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).`)
+    process.exit(1)
+  }
+
+  // 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).
+  if (opts.domain && !isLikelyDomain(opts.domain)) {
+    error(`Invalid --domain value: '${opts.domain}'`)
+    log(`Expected a bare hostname (e.g., 'mysite.com' or 'docs.mysite.com'). No scheme, no path.`)
+    process.exit(1)
+  }
+
+  // If --domain wasn't passed, fall back to whatever's already in
+  // deploy.yml's targets.<host>.domain. Lets re-running `add ci` (e.g.,
+  // to refresh the workflow after a CLI upgrade) keep the domain
+  // without the user re-typing it.
+  const { loadDeployYml } = await import('@uniweb/build/site')
+  let resolvedDomain = opts.domain
+
+  // Resolve site: --site flag, single site auto, prompt, or error.
+  const sites = await discoverSites(rootDir)
+  if (sites.length === 0) {
+    error('No site found in this workspace. Add one with `uniweb add site` first.')
+    process.exit(1)
+  }
+
+  let site
+  if (opts.site) {
+    site = sites.find(s => s.name === opts.site)
+    if (!site) {
+      error(`Site '${opts.site}' not found.`)
+      log(`Available sites: ${sites.map(s => s.name).join(', ')}`)
+      process.exit(1)
+    }
+  } else if (sites.length === 1) {
+    site = sites[0]
+  } else if (isNonInteractive(process.argv)) {
+    error(`Multiple sites in workspace. Specify --site <name>.`)
+    log(`Available sites: ${sites.map(s => s.name).join(', ')}`)
+    process.exit(1)
+  } else {
+    const sortedSites = [...sites].sort((a, b) => a.name.localeCompare(b.name))
+    const response = await prompts({
+      type: 'select',
+      name: 'site',
+      message: 'Which site should the workflow build?',
+      choices: sortedSites.map(s => ({ title: s.name, description: s.path, value: s })),
+    }, {
+      onCancel: () => {
+        log('\nCancelled.')
+        process.exit(0)
+      },
+    })
+    site = response.site
+  }
+
+  // Read node version from root package.json engines.node if pinned;
+  // otherwise default to 20 (matches the workspace template's >=20.19).
+  const rootPkg = JSON.parse(
+    await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
+  )
+  const nodeVersion = parseNodeMajor(rootPkg.engines?.node) || '20'
+
+  const siteDir = join(rootDir, site.path)
+  if (!resolvedDomain) {
+    try {
+      const deployYml = await loadDeployYml(siteDir)
+      const remembered = deployYml?.targets?.[host]?.domain
+      if (remembered && isLikelyDomain(remembered)) {
+        resolvedDomain = remembered
+        info(`Using domain '${remembered}' from deploy.yml.`)
+      }
+    } catch {
+      // Malformed deploy.yml — surface elsewhere; don't block add ci.
+    }
+  }
+
+  const result = await adapter.initCi({
+    rootDir,
+    site,
+    packageManager: pm,
+    nodeVersion,
+    domain: resolvedDomain,
+  })
+
+  // 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}`)
+  }
+
+  // Persist the adapter's target config into deploy.yml so the user's
+  // intent (host + adapter-specific fields like `domain`) is remembered
+  // across CLI upgrades and re-runs. github-pages deploys via GHA, not
+  // via `uniweb deploy`, so without this its config would never reach
+  // deploy.yml. The writer:
+  //   - scaffolds a fresh deploy.yml on first call (this target is the
+  //     default), or
+  //   - merges into an existing targets.<targetName> without touching
+  //     `default`, `autoSave`, or other targets.
+  if (result.targetConfig) {
+    try {
+      const { recordTarget } = await import('@uniweb/build/site')
+      const writeResult = await recordTarget(siteDir, {
+        targetName: host,
+        targetConfig: result.targetConfig,
+      })
+      success(
+        writeResult.action === 'scaffold'
+          ? `Wrote ${relative(rootDir, writeResult.path)} (default target: ${host})`
+          : `Updated ${relative(rootDir, writeResult.path)} (target: ${host})`
+      )
+    } catch (err) {
+      // deploy.yml persistence is best-effort: the workflow + CNAME
+      // are the load-bearing artifacts. Print a warning and continue.
+      info(`Warning: could not update deploy.yml: ${err.message}`)
+    }
+  }
+
+  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.
+  // Each label is 1–63 chars of [a-z0-9-], no leading/trailing hyphen.
+  // The TLD must be at least 2 characters of letters.
+  return /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(value)
+}
+
+function parseNodeMajor(engines) {
+  if (!engines) return null
+  const match = String(engines).match(/(\d+)/)
+  return match ? match[1] : null
+}
+
 /**
  * Show help for the add command
  */
@@ -1024,7 +1231,7 @@ function showAddHelp() {
   log(`
 ${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
 
-Add projects, foundations, sites, extensions, or section types to your workspace.
+Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
 
 ${colors.bright}Usage:${colors.reset}
   uniweb add project [name] [options]
@@ -1032,6 +1239,7 @@ ${colors.bright}Usage:${colors.reset}
   uniweb add site [name] [options]
   uniweb add extension <name> [options]
   uniweb add section <name> [options]
+  uniweb add ci [options]
 
 ${colors.bright}Common Options:${colors.reset}
   --from <template>  Apply content from a template after scaffolding
@@ -1050,6 +1258,12 @@ ${colors.bright}Extension Options:${colors.reset}
 ${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
+
 ${colors.bright}Examples:${colors.reset}
   uniweb add project docs                              # Create docs/foundation/ + docs/site/
   uniweb add project docs --from academic              # Co-located pair + academic content
@@ -1062,5 +1276,8 @@ ${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 --host github-pages --site marketing   # Pick host + site explicitly
+  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
 `)
 }

package/src/commands/build.js

@@ -645,7 +645,7 @@ async function buildSite(projectDir, options = {}) {
         log(`${colors.dim}Check that:${colors.reset}`)
         log(`  • site.yml 'foundation:' matches the package name in your foundation's package.json`)
         log(`  • site's package.json has a dependency pointing to the correct foundation path`)
-        log(`  • The foundation's dist/foundation.js exists (build the foundation first)`)
+        log(`  • The foundation's dist/entry.js exists (build the foundation first)`)
       }
 
       if (process.env.UNIWEB_DEBUG) {
@@ -884,7 +884,7 @@ export async function build(args = []) {
 
   // Validate --link / --bundle are only used with site target.
   // (Foundation builds have no equivalent split — they always produce
-  // dist/foundation.js + schema.json regardless of how a downstream
+  // dist/entry.js + schema.json regardless of how a downstream
   // site consumes the result.)
   if ((linkFlag || bundleFlag) && targetType === 'foundation') {
     error('--link and --bundle apply to site builds only')

package/src/commands/doctor.js

@@ -2,10 +2,12 @@
  * uniweb doctor - Diagnose project configuration issues
  */
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs'
 import { join, resolve, basename, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
 import { resolveFoundationSrcPath, classifyPackage, isExtensionPackage as buildIsExtensionPackage } from '@uniweb/build'
+import { loadDeployYml } from '@uniweb/build/site'
+import { listAdapters } from '@uniweb/build/hosts'
 import { getCliVersion } from '../versions.js'
 import { readAgentsVersion } from '../utils/agents-stamp.js'
 import { discoverFoundations, discoverSites } from '../utils/config.js'
@@ -518,6 +520,158 @@ export async function doctor(args = []) {
     }
   }
 
+  // ─── Deploy configuration ────────────────────────────────────
+  // Sanity-check deploy.yml shape and surface common drift between
+  // deploy.yml, site.yml, and the artifacts the CLI generates.
+  // Failures here would otherwise only surface at deploy / first GHA
+  // run, where the feedback loop is slower.
+  log('')
+  info('Checking deploy configuration...')
+  const knownAdapters = new Set(listAdapters())
+  for (const site of sites) {
+    const sitePath = site.path
+    const siteName = site.name
+    const deployYmlPath = join(sitePath, 'deploy.yml')
+    if (!existsSync(deployYmlPath)) continue
+
+    let deployYml
+    try {
+      deployYml = await loadDeployYml(sitePath)
+    } catch (err) {
+      issues.push({
+        id: 'deploy-yml-malformed',
+        type: 'error',
+        site: siteName,
+        message: `deploy.yml is malformed: ${err.message}`,
+      })
+      error(`[deploy-yml-malformed] ${relative(workspaceDir, deployYmlPath)}: ${err.message}`)
+      continue
+    }
+    if (!deployYml) continue
+
+    const targets = deployYml.targets || {}
+    const targetNames = Object.keys(targets)
+
+    // default: must reference a real target.
+    if (deployYml.default && !targets[deployYml.default]) {
+      issues.push({
+        id: 'deploy-yml-default-unknown-target',
+        type: 'error',
+        site: siteName,
+        message: `deploy.yml: default '${deployYml.default}' is not in targets (known: ${targetNames.join(', ') || '(none)'})`,
+      })
+      error(`[deploy-yml-default-unknown-target] ${siteName}: default '${deployYml.default}' is not declared under \`targets:\`.`)
+      log(`    ${colors.dim}Add it to targets: or change default: to one of: ${targetNames.join(', ') || '(none)'}.${colors.reset}`)
+    }
+
+    // Each target must have a host, and host should be a known adapter.
+    for (const [name, cfg] of Object.entries(targets)) {
+      if (!cfg || typeof cfg !== 'object') continue
+      if (!cfg.host) {
+        issues.push({
+          id: 'deploy-yml-target-missing-host',
+          type: 'error',
+          site: siteName,
+          message: `deploy.yml: targets.${name} is missing \`host\``,
+        })
+        error(`[deploy-yml-target-missing-host] ${siteName}: targets.${name} has no \`host\` field.`)
+        continue
+      }
+      // 'uniweb' is the platform default and isn't in the static-host
+      // adapter registry; treat it as known.
+      if (cfg.host !== 'uniweb' && !knownAdapters.has(cfg.host)) {
+        issues.push({
+          id: 'deploy-yml-unknown-host',
+          type: 'warn',
+          site: siteName,
+          message: `deploy.yml: targets.${name}.host '${cfg.host}' is not a known adapter`,
+        })
+        warn(`[deploy-yml-unknown-host] ${siteName}: targets.${name}.host: '${cfg.host}' is not a known built-in adapter.`)
+        log(`    ${colors.dim}Known: ${[...knownAdapters].sort().join(', ')}, plus 'uniweb'.${colors.reset}`)
+      }
+    }
+
+    // github-pages-specific: if a target has `domain`, `site/public/CNAME`
+    // should exist with that value. Vite copies public/ into dist/, and
+    // GH Pages reads dist/CNAME on each deploy to keep the custom domain
+    // configured. A drift here means a deploy will silently lose the
+    // custom domain.
+    const cnamePath = join(sitePath, 'public', 'CNAME')
+    const ghTarget = Object.entries(targets).find(([, c]) => c?.host === 'github-pages')
+    if (ghTarget) {
+      const [ghName, ghCfg] = ghTarget
+      if (ghCfg.domain) {
+        const expected = String(ghCfg.domain).trim()
+        let actual = null
+        if (existsSync(cnamePath)) {
+          try {
+            actual = readFileSync(cnamePath, 'utf8').trim()
+          } catch {
+            actual = null
+          }
+        }
+        if (actual !== expected) {
+          const issue = {
+            id: 'github-pages-cname-mismatch',
+            type: 'warn',
+            site: siteName,
+            message: actual === null
+              ? `deploy.yml: targets.${ghName}.domain is '${expected}' but ${relative(workspaceDir, cnamePath)} is missing`
+              : `deploy.yml: targets.${ghName}.domain is '${expected}' but ${relative(workspaceDir, cnamePath)} contains '${actual}'`,
+          }
+          issues.push(issue)
+          warn(`[github-pages-cname-mismatch] ${siteName}: ${issue.message}`)
+          if (shouldFix('github-pages-cname-mismatch')) {
+            const dir = dirname(cnamePath)
+            if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+            writeFileSync(cnamePath, expected + '\n')
+            issue.fixed = true
+            fixed(`wrote ${relative(workspaceDir, cnamePath)} = ${expected}`)
+          } else {
+            log(`    ${colors.dim}Re-run \`uniweb add ci --domain ${expected} --force\` (or pass --fix to write CNAME from deploy.yml).${colors.reset}`)
+          }
+        }
+      } else if (existsSync(cnamePath)) {
+        // CNAME exists but the github-pages target has no `domain` set —
+        // either deploy.yml was edited and lost the domain, or someone
+        // hand-authored CNAME without setting the target.
+        let actual = ''
+        try {
+          actual = readFileSync(cnamePath, 'utf8').trim()
+        } catch {
+          // ignore
+        }
+        issues.push({
+          id: 'github-pages-cname-orphan',
+          type: 'warn',
+          site: siteName,
+          message: `${relative(workspaceDir, cnamePath)} exists ('${actual}') but deploy.yml's github-pages target has no \`domain\``,
+        })
+        warn(`[github-pages-cname-orphan] ${siteName}: ${relative(workspaceDir, cnamePath)} exists ('${actual}') but the github-pages target has no \`domain\` set.`)
+        log(`    ${colors.dim}Either add \`domain: ${actual}\` to targets.${ghName}, or delete the CNAME if you no longer want a custom domain.${colors.reset}`)
+      }
+    }
+
+    // site.yml::base + a generated GH Pages workflow → the workflow
+    // sets UNIWEB_BASE at build time, which beats site.yml::base
+    // (site/config.js precedence: explicit > UNIWEB_BASE > site.yml).
+    // Not an error — site.yml's value is just dormant for that target —
+    // but worth flagging so the user knows the value isn't taking effect.
+    const siteYml = loadSiteYml(sitePath)
+    const workflowPath = join(workspaceDir, '.github/workflows/deploy-github-pages.yml')
+    if (siteYml?.base && existsSync(workflowPath) && ghTarget) {
+      issues.push({
+        id: 'site-base-overridden-by-workflow',
+        type: 'warn',
+        site: siteName,
+        message: `site.yml::base ('${siteYml.base}') is dormant — the GH Pages workflow sets UNIWEB_BASE at build time, which takes precedence`,
+      })
+      warn(`[site-base-overridden-by-workflow] ${siteName}: site.yml has \`base: ${siteYml.base}\`, but the GH Pages workflow sets UNIWEB_BASE.`)
+      log(`    ${colors.dim}site.yml::base is the fallback when no UNIWEB_BASE env var is set. The workflow always sets it, so this value is ignored on GH Pages deploys.${colors.reset}`)
+      log(`    ${colors.dim}If the GH Pages deploy is the only target, you can remove \`base:\` from site.yml. Otherwise leave it — it still applies to other deploy targets.${colors.reset}`)
+    }
+  }
+
   // Check AGENTS.md freshness
   log('')
   const agentsPath = join(workspaceDir, 'AGENTS.md')