uniweb 1.0.0 → 1.0.2

package/src/commands/doctor.js

@@ -0,0 +1,1982 @@
+/**
+ * uniweb doctor - Diagnose project configuration issues
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync
+} 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, AGENTS_KEYS } from '@uniweb/build/site'
+import { listAdapters } from '@uniweb/build/hosts'
+import { RUNTIME_KEYS } from '@uniweb/build/uwx'
+import { getCliVersion } from '../versions.js'
+import { readAgentsVersion } from '../utils/agents-stamp.js'
+import { writeJsonPreservingStyle } from '../utils/json-file.js'
+import { surveyWorkspaceDeps } from '../utils/dep-survey.js'
+import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { checkSiteInstall } from '../utils/install-integrity.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { DATA_DIR } from '@uniweb/core/data-paths'
+import { FAMILIES, resolveFamily } from '@uniweb/schemas/families'
+import { suggestFamily } from '@uniweb/schemas/family-aliases'
+
+/**
+ * Parse the `--fix [<issue-id>]` flag.
+ *
+ * Returns:
+ *   null         — no auto-fix requested.
+ *   'all'        — fix every auto-fixable issue.
+ *   '<issue-id>' — fix only issues with this id.
+ */
+function parseFixFlag(args) {
+  const idx = args.indexOf('--fix')
+  if (idx === -1) return null
+  const next = args[idx + 1]
+  if (!next || next.startsWith('--')) return 'all'
+  return next
+}
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
+}
+
+const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => console.log(`${colors.blue}→${colors.reset} ${msg}`)
+const log = console.log
+
+/**
+ * Check if a directory is a site
+ */
+function isSite(dir) {
+  // Use the canonical classifier; also accept legacy `site.yaml`
+  // (the classifier only recognizes `.yml` and `.document.yml`).
+  return classifyPackage(dir) === 'site' || existsSync(join(dir, 'site.yaml'))
+}
+
+/**
+ * Check if a directory is a foundation
+ */
+function isFoundation(dir) {
+  return classifyPackage(dir) === 'foundation'
+}
+
+/**
+ * Load a foundation's built schema.json.
+ *
+ * ⛔ THE PATH IS `dist/meta/schema.json`, and it read `dist/schema.json` from
+ * 2026-02-06 until 2026-09-15 — a file the build has never written. So this
+ * returned `null` every time, and its one caller (the extension `vars`/layouts
+ * warning, which `framework/CLAUDE.md` gotcha #18 says doctor performs) could
+ * not fire at all.
+ *
+ * ⭐ THE CLASS IS WORTH MORE THAN THE BUG: a wrong PATH returns empty, it does
+ * not throw. `existsSync` said no, the function returned `null`, every caller
+ * used `?.` and skipped — and a check that never fires looks exactly like a
+ * codebase with nothing to report.
+ */
+function loadSchemaJson(dir) {
+  const schemaPath = join(dir, 'dist', 'meta', 'schema.json')
+  if (!existsSync(schemaPath)) return null
+  try {
+    return JSON.parse(readFileSync(schemaPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if a foundation is an extension (via schema.json or foundation.js)
+ */
+function isExtensionPackage(dir) {
+  return buildIsExtensionPackage(dir)
+}
+
+/**
+ * Load package.json from a directory
+ */
+function loadPackageJson(dir) {
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load site.yml from a directory
+ */
+function loadSiteYml(dir) {
+  const ymlPath = join(dir, 'site.yml')
+  const yamlPath = join(dir, 'site.yaml')
+  const configPath = existsSync(ymlPath)
+    ? ymlPath
+    : existsSync(yamlPath)
+      ? yamlPath
+      : null
+  if (!configPath) return null
+  try {
+    return yaml.load(readFileSync(configPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Diagnose the compiled-collection output directory.
+ *
+ * `public/<DATA_DIR>/` holds what the build compiles from `records/`, and
+ * nothing else — `records/` is the only supported way to provide structured
+ * data. Two consequences, both checked here:
+ *
+ * 1. **The mapping is a bijection.** Every entry should be backed by a
+ *    declared collection. An entry that isn't is stale — most often a
+ *    collection removed from `site.yml`, whose compiled records stay on disk
+ *    and keep being deployed. The build reconciles *within* a collection it
+ *    still knows about; it cannot reconcile one it has never heard of, which
+ *    is exactly the case that needs a declaration to compare against.
+ *
+ * 2. **It should not be committed.** It is generated into the source tree
+ *    rather than `dist/`, so without an ignore rule it looks permanent, gets
+ *    committed, and then looks like something you may edit. That is how
+ *    hand-authored files ended up there in the first place.
+ */
+/**
+ * Whether any component source under `dir` matches `pattern`.
+ *
+ * Only the directories a foundation puts components in, and never
+ * `node_modules` — this answers "did the developer write this", so a match
+ * inside a dependency is the wrong answer.
+ */
+/**
+ * Does this foundation render kit's <Prose> or <Article> — under its own name or an alias?
+ *
+ * The JSX tag alone missed `import { Article as ArticleBody } from '@uniweb/kit'`, which
+ * renders `<ArticleBody>`: two official templates shipped that way with no prose styles
+ * until 2026-09-29. So the import counts too. (The foundation build checks the same thing
+ * from its module graph, which no alias can hide from.)
+ *
+ * @param {string} dir - the foundation's source directory
+ * @returns {boolean}
+ */
+export function rendersKitProse(dir) {
+  return (
+    sourceMatches(dir, /<(Prose|Article)\b/) ||
+    sourceMatches(dir, /import\s*\{[^}]*\b(Prose|Article)\b[^}]*\}\s*from\s*['"]@uniweb\/kit['"]/)
+  )
+}
+
+function sourceMatches(dir, pattern) {
+  let found = false
+  forEachSourceFile(dir, (text) => {
+    // `pattern` may carry /g, whose lastIndex persists across .test() calls —
+    // reset so a second file is not silently skipped.
+    pattern.lastIndex = 0
+    if (pattern.test(text)) found = true
+  })
+  return found
+}
+
+/**
+ * Read every component source file under `dir`, handing each one's text to `fn`.
+ *
+ * Same roots and same exclusions as `sourceMatches` (which is built on this):
+ * only where a foundation puts components, never `node_modules`, because the
+ * question is always "did the developer write this".
+ */
+function forEachSourceFile(dir, fn) {
+  const roots = ['sections', 'layouts', 'components', 'utils']
+  const walk = (d, depth = 0) => {
+    if (depth > 6) return
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      const p = join(d, entry.name)
+      if (entry.isDirectory()) {
+        walk(p, depth + 1)
+      } else if (/\.(jsx?|tsx?)$/.test(entry.name)) {
+        try {
+          fn(readFileSync(p, 'utf8'), relative(dir, p))
+        } catch {
+          // unreadable file — not this check's problem to report
+        }
+      }
+    }
+  }
+  for (const r of roots) walk(join(dir, r))
+}
+
+// A fenced data block tagged `form`, in any of the serialization formats the
+// parser accepts for one. Matched on the info string only — the body is the
+// author's business.
+//
+// No whitespace is allowed around the colon, because the parser allows none:
+// `processCodeInfo` in @uniweb/content-reader does a bare `info.split(':')` and
+// trims neither half, so ```` ```yaml: form ```` yields the tag `" form"` and
+// lands at `content.data[" form"]`. Matching it here would warn about a block
+// that is not a form.
+const FORM_BLOCK = /^\s*`{3,}\s*(?:yaml|yml|json):form\b/m
+
+/**
+ * Find the content files declaring a form, so we can tell whether having no
+ * submission destination matters for this site.
+ *
+ * Scans the page tree and layout only. A form is authored where it renders, and
+ * widening this to collections would trade a slower check for cases that do not
+ * occur.
+ */
+export function findFormContent(sitePath, siteYml) {
+  const roots = [
+    siteYml?.paths?.pages ? join(sitePath, siteYml.paths.pages) : join(sitePath, 'pages'),
+    join(sitePath, 'layout')
+  ]
+  const found = []
+
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return // absent or unreadable — not this check's problem to report
+    }
+    for (const entry of entries) {
+      const p = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(p)
+      } else if (entry.name.endsWith('.md')) {
+        try {
+          if (FORM_BLOCK.test(readFileSync(p, 'utf8'))) found.push(relative(sitePath, p))
+        } catch {
+          // unreadable file — skip
+        }
+      }
+    }
+  }
+
+  for (const root of roots) walk(root)
+  return found
+}
+
+/**
+ * A misspelled key in `agents:` is silent everywhere else, forever.
+ *
+ * The block reaches a backend as **opaque JSON** — measured 2026-08-13, and it
+ * is the right design: the vocabulary is the framework's, and a backend that
+ * validated it would be inventing our language. The cost is that nothing
+ * downstream can object. A host receives `expectedOrgins`, stores it, forwards
+ * it, and enforces nothing; the author sees a configured site and gets no
+ * check. **This is the only lane that can catch it.**
+ *
+ * ⛔ Severity is deliberate. It is a `warning` for an unknown key generally,
+ * but the failure it prevents is worst for the keys that RESTRICT something —
+ * an author who writes `expectedOrgins` believes they asked for a check they
+ * did not get. A key that silently does nothing is the recurring wart of this
+ * block: `exclude`'s glob spelling excludes nothing, and a carried key nobody
+ * reads enforces nothing.
+ *
+ * `agents: false` turns the capability off in one word and is not an object —
+ * flagging its absence of keys would be nonsense.
+ */
+export function checkAgentsBlock({ siteName, siteYml, issues }) {
+  const agents = siteYml?.agents
+  if (agents === undefined || agents === false) return
+  if (!agents || typeof agents !== 'object' || Array.isArray(agents)) {
+    const id = 'agents-not-an-object'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`agents:\` should be a map of options, or \`false\` to turn it off`
+    })
+    warn(`[${id}] ${siteName}: \`agents:\` is neither a map of options nor \`false\`.`)
+    return
+  }
+
+  const known = new Set(AGENTS_KEYS)
+  const unknown = Object.keys(agents).filter((k) => !known.has(k))
+  if (unknown.length === 0) return
+
+  const id = 'agents-unknown-key'
+  issues.push({
+    id,
+    type: 'warning',
+    site: siteName,
+    message: `site.yml: \`agents:\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+  })
+  warn(
+    `[${id}] ${siteName}: \`agents:\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+      .map((k) => `'${k}'`)
+      .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
+  )
+  for (const key of unknown) {
+    const near = nearestKnownKey(key, known)
+    if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
+  }
+  log(
+    `    ${colors.dim}Nothing downstream will reject it: the block is forwarded to the host as opaque data,${colors.reset}`
+  )
+  log(
+    `    ${colors.dim}so an unrecognized key is carried and never acted on. Known: ${AGENTS_KEYS.join(', ')}.${colors.reset}`
+  )
+}
+
+/**
+ * The closest known key within a small edit distance, or null.
+ *
+ * Suggestions are capped at distance 3 rather than "closest wins": on a
+ * six-word vocabulary an uncapped nearest-match confidently proposes `index`
+ * for `origins`, and a wrong suggestion is worse than none — it sends the
+ * author to change a line that was not their mistake.
+ */
+function nearestKnownKey(input, known) {
+  let best = null
+  let bestScore = Infinity
+  for (const candidate of known) {
+    const score = editDistance(input.toLowerCase(), candidate.toLowerCase())
+    if (score < bestScore) {
+      bestScore = score
+      best = candidate
+    }
+  }
+  return bestScore <= 3 ? best : null
+}
+
+/**
+ * The options `services.tracking` has a reader for — the build's list, which also
+ * decides what a push sends the host as its settings (`RUNTIME_KEYS`, `@uniweb/build`).
+ * ⛔ *Until 2026-10-06 doctor kept a copy of its own, which had drifted: it lacked
+ * `emit` and `flushIntervalMs`, which `wireTracker` reads.*
+ */
+const TRACKING_KEYS = RUNTIME_KEYS.tracking
+
+/**
+ * Spellings that read as an ATTEMPT to require consent but do not require it.
+ *
+ * `consentRequired` is `options.consent === 'required'` — an exact match — so
+ * every one of these silently means *no gate*. That is the one field in this
+ * block where a silent no-op has a consequence beyond a missing metric.
+ *
+ * ⚖️ Deliberately not "anything that is not `required`": `consent: none` is a
+ * documented, useful value — it is how a site overrides a gate its **host**
+ * declared, under the per-key tier fill. Flagging that would flag correct code.
+ */
+const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true', 'yes', 'on', '1'])
+
+/**
+ * `services.tracking` — flag the keys and values that are carried and never acted on.
+ *
+ * A key the site's tracking does not read goes to the host as a setting, and the
+ * rest is resolved at render, so nothing downstream rejects a mistake in it. Every error here therefore fails
+ * the same way: **silently, at a visitor's browser, as an absence** — which is
+ * also exactly what a site that configured nothing looks like. There is no
+ * symptom to notice and nothing to grep for.
+ *
+ * ⭐ That is the whole argument for checking it at `doctor` time: it is the only
+ * moment in the chain where a person who can fix it is looking at it.
+ *
+ * An address, `true` or `false` carries no options — there is nothing in it to be
+ * wrong.
+ */
+/**
+ * `uniweb doctor` — is `package.json` behind what the build derived?
+ *
+ * A host offers services (`config.services.<name>`); a foundation has to render
+ * something against one, or an operator who provisioned it gets nothing and no
+ * error. `uniweb.supports` states which ones a foundation honours, and it rides
+ * to the registry as `info.supports` (`build/src/uwx/registry-package.js`).
+ *
+ * ## ⭐ THE BUILD ALREADY ANSWERED THIS — so read its answer, do not re-derive
+ *
+ * `@uniweb/build` derives the set from the post-tree-shake module graph and
+ * writes it to `dist/meta/schema.json`'s `_self.supports`
+ * (`build/src/foundation/derive-supports.js`). That value is what publishes,
+ * with or without this check, so the foundation is already correct on the wire.
+ *
+ * ⛔ **What was here before was a regex over `sections/`, `layouts/` and
+ * `components/`, and it did not work.** It knew four spellings and
+ * `useFormSubmit()` — the official submit gate — was not one, so it was silent
+ * on `templates/services`, the template written to demonstrate the feature. Its
+ * test could not find that, because the fixture was a source string written to
+ * match the regex. ⇒ **Do not reintroduce a second, weaker derivation here.**
+ * There is one, it runs in the build, and this reads it.
+ *
+ * ## So what is left for `doctor` to say
+ *
+ * Only that the FILE disagrees with the artifact. Nothing is broken when it
+ * does — but `uniweb.supports` is the one place a human can add a service the
+ * graph cannot see (a computed name), so a developer who never sees the derived
+ * set never learns the key exists, and never adds the one thing only they know.
+ *
+ * `--fix` writes the derived names in, where they land in a diff the developer
+ * reads. ⛔ The build never does this itself: rewriting source on every build is
+ * a surprise, and the artifact needs no help.
+ *
+ * Silent when the foundation has not been built — nothing has been measured, so
+ * there is nothing to compare and a guess would be worse than quiet.
+ */
+export async function checkFoundationSupports({
+  foundationName,
+  folderName,
+  foundationDir,
+  pkg,
+  issues,
+  shouldFix,
+  fixed,
+}) {
+  const schemaPath = join(foundationDir, 'dist', 'meta', 'schema.json')
+  if (!existsSync(schemaPath)) return
+
+  let derived
+  try {
+    derived = JSON.parse(readFileSync(schemaPath, 'utf8'))?._self?.supports
+  } catch {
+    return // unreadable or malformed build output — not this check's to report
+  }
+  // Absent means the build derived nothing and saw a computed name, so it
+  // reported UNKNOWN. There is no gap to name.
+  if (!Array.isArray(derived) || derived.length === 0) return
+
+  const declared = pkg?.uniweb?.supports
+  const hasDeclaration = Array.isArray(declared)
+  const missing = derived.filter((name) => !hasDeclaration || !declared.includes(name)).sort()
+  if (missing.length === 0) return
+
+  const id = 'foundation-supports-incomplete'
+  const list = missing.join(', ')
+  const merged = [...new Set([...(hasDeclaration ? declared : []), ...derived])].sort()
+
+  if (shouldFix?.(id)) {
+    const pkgPath = join(foundationDir, 'package.json')
+    try {
+      const src = readFileSync(pkgPath, 'utf8')
+      const parsed = JSON.parse(src)
+      parsed.uniweb = { ...(parsed.uniweb || {}), supports: merged }
+      writeJsonPreservingStyle(pkgPath, parsed, src)
+      fixed?.(`${folderName}/package.json now declares uniweb.supports: ${merged.join(', ')}`)
+      return
+    } catch (e) {
+      // Fall through to the warning — a failed write must not read as fixed.
+      warn(`[${id}] could not write ${folderName}/package.json: ${e.message}`)
+    }
+  }
+
+  issues.push({
+    id,
+    type: 'warning',
+    foundation: foundationName,
+    message: hasDeclaration
+      ? `${foundationName} builds against ${list} but does not declare ${missing.length === 1 ? 'it' : 'them'} in uniweb.supports`
+      : `${foundationName} builds against ${list} but declares no uniweb.supports`,
+    details: { derived, declared: hasDeclaration ? declared : null },
+    fixable: true,
+  })
+
+  warn(`[${id}] ${foundationName} builds against ${list}, not in ${folderName}/package.json`)
+  log(`    The build already publishes ${colors.dim}${derived.join(', ')}${colors.reset}, so nothing is missing on the wire.`)
+  log(`    Declaring it matters when a service is named by a computed value — the`)
+  log(`    build cannot see those, and yours is the only place they can be added.`)
+  log(`    ${colors.dim}uniweb doctor --fix ${id}${colors.reset}`)
+}
+
+/**
+ * Every section type's standard family — what it resolved to, and HOW.
+ *
+ * ⭐ THIS IS WHERE THE TAXONOMY IS ACTUALLY LEARNED. Nobody reads a word list in
+ * advance; they read the warning that names their own component and proposes the
+ * edit. A foundation developer sees their own picker here before an author does.
+ *
+ * ⛔ AN UNRECOGNIZED NAME IS NOT AN ERROR, and this check must never imply it is.
+ * A foundation with its own vocabulary is a supported choice: the section falls
+ * back to a generic illustration and nothing breaks. What is reported is the
+ * OPPORTUNITY — and only where there is a concrete suggestion to act on.
+ *
+ * ⚠️ READS THE BUILT `schema.json`, so it says nothing before a build. That is
+ * deliberate: schema.json is what a picker actually receives, and inferring from
+ * unbuilt source would report on a state no consumer sees.
+ */
+export function checkSectionFamilies({
+  foundationName,
+  folderName,
+  foundationDir,
+  issues,
+  shouldFixExplicitly,
+  fixed,
+}) {
+  const schema = loadSchemaJson(foundationDir)
+  if (!schema) return
+
+  const familyIds = FAMILIES.map((f) => f.id)
+  const sections = Object.entries(schema)
+    .filter(([key, value]) => !key.startsWith('_') && key !== 'dataSchemas' && value && typeof value === 'object')
+    .map(([name, entry]) => ({ name, entry, ...resolveFamily({ name, family: entry.family }) }))
+
+  if (sections.length === 0) return
+
+  const declared = sections.filter((s) => s.source === 'declared')
+  const byName = sections.filter((s) => s.source === 'name')
+  const misses = sections.filter((s) => !s.id)
+
+  info(
+    `${folderName}: ${sections.length - misses.length}/${sections.length} sections have a standard family ` +
+      `${colors.dim}(${declared.length} declared, ${byName.length} from the name)${colors.reset}`
+  )
+
+  // ── a `family:` that names nothing we know ────────────────────────────────
+  const bogus = misses.filter((s) => s.unknown)
+  for (const s of bogus) {
+    const id = 'section-family-unknown'
+    const near = suggestFamily(s.unknown, familyIds)
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: foundationName,
+      message: `${s.name} declares family '${s.unknown}', which is not a standard family`,
+    })
+    warn(`[${id}] ${folderName}/${s.name}: family '${s.unknown}' is not a standard family`)
+    if (near.id) log(`    Did you mean ${colors.blue}${near.id}${colors.reset}?`)
+    log(`    ${colors.dim}An unrecognized value is legal — it falls back to a generic illustration.${colors.reset}`)
+    log(`    ${colors.dim}uniweb families${colors.reset}`)
+  }
+
+  // ── a name we do not know, WITH something to suggest ──────────────────────
+  const undeclared = misses.filter((s) => !s.unknown)
+  const proposals = undeclared
+    .map((s) => ({ ...s, suggestion: suggestFamily(s.name, familyIds) }))
+    .filter((s) => s.suggestion.id || s.suggestion.ambiguous)
+  if (proposals.length === 0) return
+
+  const id = 'section-family-unrecognized'
+  const writable = proposals.filter((p) => p.suggestion.fixable && p.suggestion.id)
+
+  // ⛔ EXPLICIT ID ONLY — never a bare `--fix`. Every id below is a GUESS from a
+  // table that exists here, rather than in the resolver, precisely so a person
+  // approves it. A bare `--fix` writing them would put the silent-wrong-guess
+  // failure back, one directory deeper.
+  if (shouldFixExplicitly?.(id) && writable.length > 0) {
+    const srcDir = resolveFoundationSrcPath(foundationDir)
+    for (const p of writable) {
+      const metaPath = join(srcDir, p.entry.path || '', 'meta.js')
+      const written = writeFamilyIntoMeta(metaPath, p.suggestion.id)
+      if (written) fixed?.(`${folderName}/${p.entry.path}/meta.js now declares family: '${p.suggestion.id}'`)
+      else warn(`[${id}] could not write ${p.name}'s meta.js — add \`family: '${p.suggestion.id}'\` by hand`)
+    }
+    return
+  }
+
+  issues.push({
+    id,
+    type: 'info',
+    foundation: foundationName,
+    message: `${proposals.length} section(s) in ${foundationName} could declare a standard family`,
+    details: proposals.map((p) => ({ name: p.name, suggested: p.suggestion.id, via: p.suggestion.via })),
+    fixable: writable.length > 0,
+  })
+
+  warn(`[${id}] ${folderName}: ${proposals.length} section(s) have no standard family`)
+  const width = Math.max(...proposals.map((p) => p.name.length))
+  for (const p of proposals) {
+    const { id: hit, via, ambiguous } = p.suggestion
+    if (ambiguous) {
+      log(`    ${p.name.padEnd(width)}  ${colors.dim}ambiguous — ${ambiguous}${colors.reset}`)
+    } else {
+      const how = via === 'near' ? 'possible typo' : via === 'suffix' ? 'name + shape suffix' : 'known alias'
+      log(`    ${p.name.padEnd(width)}  → ${colors.blue}${hit}${colors.reset} ${colors.dim}(${how})${colors.reset}`)
+    }
+  }
+  log(`    ${colors.dim}Nothing is broken — an unrecognized name falls back to a generic illustration.${colors.reset}`)
+  if (writable.length > 0) {
+    log(`    ${colors.dim}uniweb doctor --fix ${id}${colors.reset} ${colors.dim}— writes ${writable.length} \`family:\` line(s). Read the diff: these are guesses.${colors.reset}`)
+  }
+}
+
+/**
+ * Insert `family: '<id>'` as the first key of a meta.js default export.
+ *
+ * ⛔ REFUSES ANYTHING IT DOES NOT RECOGNIZE. A meta.js is hand-written source,
+ * and a half-understood rewrite of someone's file is far worse than telling them
+ * to add one line. A `false` return is reported as "could not write", never as
+ * fixed.
+ */
+function writeFamilyIntoMeta(metaPath, familyId) {
+  if (!existsSync(metaPath)) return false
+  try {
+    const src = readFileSync(metaPath, 'utf8')
+    if (/^\s*family\s*:/m.test(src)) return false // already has one — never overwrite
+    const m = src.match(/export\s+default\s*\{[ \t]*\r?\n/)
+    if (!m) return false
+    const at = m.index + m[0].length
+    const indent = src.slice(at).match(/^([ \t]+)/)?.[1] ?? '  '
+    writeFileSync(metaPath, `${src.slice(0, at)}${indent}family: '${familyId}',\n${src.slice(at)}`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `category:` and `purpose:` were retired when `family:` landed.
+ *
+ * ⚖️ INFO, NOT A WARNING. Both are inert — nothing in the build, the runtime or
+ * the wire has ever read either — so a foundation carrying one is not broken and
+ * does not need to hurry. It is worth saying once, because a developer who sees
+ * `category:` in a neighbour's meta.js will reasonably copy it.
+ */
+export function checkRetiredMetaKeys({ foundationName, folderName, foundationDir, issues }) {
+  const schema = loadSchemaJson(foundationDir)
+  if (!schema) return
+  const stale = Object.entries(schema)
+    .filter(([key, v]) => !key.startsWith('_') && key !== 'dataSchemas' && v && typeof v === 'object')
+    .filter(([, v]) => v.category !== undefined || v.purpose !== undefined)
+  if (stale.length === 0) return
+
+  const id = 'section-retired-meta-key'
+  const keys = [...new Set(stale.flatMap(([, v]) => [
+    v.category !== undefined ? 'category' : null,
+    v.purpose !== undefined ? 'purpose' : null,
+  ].filter(Boolean)))]
+  issues.push({
+    id,
+    type: 'info',
+    foundation: foundationName,
+    message: `${stale.length} section(s) still declare ${keys.join(' / ')}`,
+  })
+  info(
+    `[${id}] ${folderName}: ${stale.length} section(s) still declare ` +
+      `${colors.dim}${keys.join(' / ')}${colors.reset} — retired, and read by nothing`
+  )
+  log(`    ${colors.dim}\`family:\` replaced them. Removing them changes no behaviour.${colors.reset}`)
+}
+
+/**
+ * The gates kit exposes for a host service, and the field that IS the gate.
+ *
+ * Each hook returns a boolean saying whether the site actually has the service.
+ * A component that ignores it draws a control the visitor cannot use — a search
+ * box that searches nothing, a form whose answers have nowhere to go.
+ */
+const SERVICE_GATES = [
+  { hook: 'useFormSubmit', gate: 'canSubmit', alt: 'isSubmitEnabled', draws: 'a form' },
+  { hook: 'useSearch', gate: 'isEnabled', alt: 'isSearchEnabled', draws: 'a search control' },
+  { hook: 'useSearchIndex', gate: 'isEnabled', alt: 'isSearchEnabled', draws: 'a search control' },
+  // Returns everything `useSearch` does, `isEnabled` included, so it gates the
+  // same way. It was missing from this list until the hook was renamed out of
+  // `useSearchWithIntent` — the kind of gap a list of names grows quietly.
+  { hook: 'useSearchPrefetch', gate: 'isEnabled', alt: 'isSearchEnabled', draws: 'a search control' },
+]
+
+/**
+ * `uniweb doctor` — a control drawn for a service the site may not have.
+ *
+ * `resolveService` answers with an address or nothing, and nothing is a normal
+ * state: the operator did not provision that service. ⭐ **The rule is that a
+ * control for a service the site does not have must not be drawn** — no error,
+ * no apology, no explanatory string (there is deliberately none to show, since
+ * any wording would be ours to invent, in one language, for a visitor with no
+ * stake in it). The hooks hand you a boolean for exactly this, and a component
+ * that never reads it renders something permanently dead.
+ *
+ * ## ⚖️ WHY A REGEX IS ACCEPTABLE HERE, HAVING JUST BEEN REJECTED NEXT DOOR
+ *
+ * `checkFoundationSupports` above no longer scans source, because deriving
+ * *which services a foundation reaches* requires following calls through
+ * `@uniweb/kit` into `@uniweb/core`, and a missed match there silently costs a
+ * capability on the wire. This question is a different shape:
+ *
+ *   - it is **local to one file** — the hook call and its gate are in the same
+ *     component, in the developer's own source, with no indirection to follow;
+ *   - the gate names are **fixed by kit's API**, not inferred — with one caveat
+ *     that used to be a live false negative: `isEnabled` is a hook's returned
+ *     field AND, until 2026-09-10, an `@uniweb/api` export. A component holding
+ *     both read as gated. `@uniweb/kit`'s `is<Service>Enabled()` predicates are
+ *     unique per subject, so `alt` below is matched instead and the collision
+ *     cannot recur;
+ *   - it only ever **warns**, and changes no artifact. A miss costs a missing
+ *     warning, which is the safe direction.
+ *
+ * ⛔ Its limits, stated rather than discovered: a component that gates in its
+ * parent reads as ungated here, and one that destructures the gate without
+ * using it reads as gated. Both are warnings about a real smell either way, and
+ * neither can produce a wrong artifact.
+ */
+/**
+ * Source with its comments removed.
+ *
+ * ⚠️ MEASURED, NOT PRECAUTIONARY. The first cut of this check searched the raw
+ * text, and passed on `templates/services` with the gate deliberately deleted
+ * from the code — because the component's JSDoc still said `canSubmit`. Prose
+ * about a gate is not a gate.
+ *
+ * ⛔ Whole-line and block comments only, deliberately. A line that begins with
+ * `//` or `*` is unambiguously a comment, so stripping it can never remove real
+ * code; hunting trailing comments would mean deciding whether a `//` sits
+ * inside a string, and getting that wrong deletes code and invents a warning.
+ * The residue is that a gate named ONLY in a trailing comment still reads as
+ * used, which is a missed warning — the safe direction.
+ */
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '')
+}
+
+export function checkUngatedServiceControls({ foundationName, folderName, srcDir, issues }) {
+  const found = []
+
+  forEachSourceFile(srcDir, (raw, file) => {
+    const text = stripComments(raw)
+    for (const { hook, gate, alt, draws } of SERVICE_GATES) {
+      // A call, not merely an import: re-exporting a hook is not drawing with it.
+      if (!new RegExp(`\\b${hook}\\s*\\(`).test(text)) continue
+      // Either the hook's own returned field, or kit's standalone predicate for
+      // the same service — both are the gate, and a component that reads one
+      // does not need the other.
+      if (new RegExp(`\\b${gate}\\b`).test(text)) continue
+      if (alt && new RegExp(`\\b${alt}\\s*\\(`).test(text)) continue
+      found.push({ file, hook, gate, alt, draws })
+    }
+  })
+
+  if (found.length === 0) return
+
+  const id = 'ungated-service-control'
+  for (const f of found) {
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: foundationName,
+      message: `${foundationName}/${f.file} calls ${f.hook}() without reading ${f.gate}`,
+      details: f,
+    })
+    warn(`[${id}] ${folderName}/${f.file} calls ${f.hook}() and never reads ${f.gate}`)
+    log(`    It draws ${f.draws} even on a site with no such service, where the`)
+    log(`    control cannot work. Gate on it instead:`)
+    log(`      ${colors.dim}const { ${f.gate} } = ${f.hook}(…)${colors.reset}`)
+    log(`      ${colors.dim}if (!${f.gate}) return null${colors.reset}`)
+    if (f.alt) log(`    ${colors.dim}…or ${f.alt}() from @uniweb/kit, which needs no hook.${colors.reset}`)
+  }
+}
+
+export function checkTrackingBlock({ siteName, siteYml, issues }) {
+  const tracking = siteYml?.services?.tracking
+  if (tracking === undefined || tracking === null || typeof tracking === 'boolean') return
+  if (typeof tracking === 'string') return
+
+  if (typeof tracking !== 'object' || Array.isArray(tracking)) {
+    const id = 'tracking-not-an-object'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`services.tracking\` should be true, false, an address, or a map of options`
+    })
+    warn(`[${id}] ${siteName}: \`services.tracking\` is neither true, false, an address nor a map of options.`)
+    return
+  }
+
+  const known = new Set(TRACKING_KEYS)
+  const unknown = Object.keys(tracking).filter((k) => !known.has(k))
+  if (unknown.length > 0) {
+    const id = 'tracking-unknown-key'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`services.tracking\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+    })
+    warn(
+      `[${id}] ${siteName}: \`services.tracking\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+        .map((k) => `'${k}'`)
+        .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
+    )
+    for (const key of unknown) {
+      const near = nearestKnownKey(key, known)
+      if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
+    }
+    log(
+      `    ${colors.dim}Not an option the site's tracking reads — sent to your host as a setting. Known: ${TRACKING_KEYS.join(', ')}.${colors.reset}`
+    )
+  }
+
+  // `consent` is exact-matched against 'required'. A near miss is not a typo
+  // with a cosmetic cost — it is a consent gate the author believes they asked
+  // for and did not get.
+  if ('consent' in tracking) {
+    const value = tracking.consent
+    const spelling = value === null || value === undefined ? '' : String(value).trim().toLowerCase()
+
+    // ⛔ The gate test is against the RAW value, because the runtime's is:
+    // `options.consent === 'required'`, exact and case-sensitive. Lowercasing
+    // before this comparison made `Required` look correct to the checker — the
+    // check stopped testing the thing it was written to catch. The normalized
+    // spelling is only for deciding whether a wrong value reads as an ATTEMPT.
+    const gateIsOn = value === 'required'
+    const looksIntended =
+      spelling === '' || spelling === 'required' || CONSENT_NEAR_MISSES.has(spelling)
+
+    if (!gateIsOn && looksIntended) {
+      const id = 'tracking-consent-not-required'
+      const shown = spelling === '' ? 'an empty value' : `\`${String(value)}\``
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`services.tracking.consent\` is ${shown} — only the exact value \`required\` turns the gate on`
+      })
+      warn(`[${id}] ${siteName}: \`services.tracking.consent\` is ${shown}; the gate is OFF.`)
+      log(
+        `    ${colors.dim}Only \`consent: required\` holds events until a visitor answers. Anything else${colors.reset}`
+      )
+      log(
+        `    ${colors.dim}sends immediately — including a blank value, which YAML reads as null.${colors.reset}`
+      )
+    }
+  }
+
+  // An entry that yields no URL is dropped by the loader without a sound.
+  const declared = tracking.scripts
+  if (declared !== undefined) {
+    const list = Array.isArray(declared) ? declared : [declared]
+    const bad = list.filter(
+      (e) => !(typeof e === 'string' ? e.trim() : typeof e?.src === 'string' && e.src.trim())
+    )
+    if (bad.length > 0) {
+      const id = 'tracking-script-without-url'
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `site.yml: \`services.tracking.scripts\` has ${bad.length} ${bad.length === 1 ? 'entry' : 'entries'} with no URL`
+      })
+      warn(
+        `[${id}] ${siteName}: ${bad.length} \`services.tracking.scripts\` ${bad.length === 1 ? 'entry has' : 'entries have'} no URL and will not load.`
+      )
+      log(
+        `    ${colors.dim}An entry is a URL, or an object with a \`src\`. Anything else is dropped silently.${colors.reset}`
+      )
+    }
+  }
+}
+
+/** Levenshtein distance, iterative two-row form. */
+function editDistance(a, b) {
+  if (a === b) return 0
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        prev[j] + 1,
+        row[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      )
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
+/**
+ * A site whose content declares a form needs somewhere to send it.
+ *
+ * Two things can supply that: `services.submit` in site.yml — asking the host for
+ * form handling, or naming the site's own — or the host at serve time. Doctor can
+ * only see the first — so it warns only when *nothing* could plausibly supply one:
+ * no entry, and no deploy target that would put a host in the picture. On a site
+ * bound to a host, an absent entry can be the correct configuration, and warning
+ * there would nag exactly the people who got it right.
+ *
+ * The consequence of being wrong in the other direction is what justifies the
+ * check at all: a form with no destination is not drawn, which is easy to ship
+ * without noticing.
+ */
+export async function checkFormSubmitTarget({ sitePath, siteName, siteYml, issues }) {
+  if (siteYml?.services?.submit) return
+
+  const forms = findFormContent(sitePath, siteYml)
+  if (forms.length === 0) return
+
+  // A configured deploy target means a host is in the picture and may supply a
+  // destination we cannot see from here.
+  let deployYml = null
+  try {
+    deployYml = await loadDeployYml(sitePath)
+  } catch {
+    // malformed deploy.yml is reported by its own check; treat as absent here
+  }
+  if (deployYml?.targets && Object.keys(deployYml.targets).length > 0) return
+
+  const id = 'form-without-submit-target'
+  const n = forms.length
+  issues.push({
+    id,
+    type: 'warning',
+    site: siteName,
+    message: `${n} content file${n === 1 ? '' : 's'} declare${n === 1 ? 's' : ''} a form, but no submission destination is configured`
+  })
+  warn(`[${id}] ${n} content file${n === 1 ? '' : 's'} declare${n === 1 ? 's' : ''} a form with nowhere to send it`)
+  for (const f of forms.slice(0, 5)) log(`    • ${f}`)
+  if (n > 5) log(`    ${colors.dim}…and ${n - 5} more${colors.reset}`)
+  log(
+    `    Ask your host for form handling — ${colors.green}services: { submit: true }${colors.reset} — or name your own: ${colors.green}services: { submit: https://… }${colors.reset}.`
+  )
+  log(
+    `    ${colors.dim}A host that handles submissions supplies one itself — this check is skipped once a deploy target is configured.${colors.reset}`
+  )
+}
+
+/** The bare map in `queries.yml`, or `{}` when there is none. */
+function readQueriesYml(sitePath) {
+  try {
+    const doc = yaml.load(readFileSync(join(sitePath, 'queries.yml'), 'utf8'))
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {}
+  } catch {
+    return {}
+  }
+}
+
+function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix, fixed }) {
+  const dataDir = join(sitePath, 'public', DATA_DIR)
+  // ⚠️ THE QUERIES, not the pool. `public/<DATA_DIR>/x.json` is a query's
+  // MATERIALIZATION — one file per named query — so the bijection is with the
+  // declared queries, never with the schema folders under `records/`.
+  //
+  // ⛔ BOTH HOMES, or this reports every compiled file as an orphan. A site that
+  // keeps its queries in `queries.yml` has none in `site.yml`, and reading one
+  // file would turn the whole check into a false positive — the loudest possible
+  // failure for a check whose job is to find stale output.
+  //
+  // Read directly rather than through `resolveQueriesConfig`: this pass is
+  // synchronous, and it needs the NAMES rather than resolved declarations.
+  const declared = new Set([
+    ...Object.keys(siteYml.queries || {}),
+    ...Object.keys(readQueriesYml(sitePath))
+  ])
+
+  if (existsSync(dataDir)) {
+    // A query `x` owns `x.json` (its list) and `x/` (its records' own files).
+    // Anything else is unaccounted for.
+    const orphans = readdirSync(dataDir, { withFileTypes: true })
+      .filter((entry) => {
+        const name = entry.isDirectory()
+          ? entry.name
+          : entry.name.replace(/\.json$/i, '')
+        return !declared.has(name)
+      })
+      .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+
+    if (orphans.length > 0) {
+      const id = 'orphaned-query-output'
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: `${orphans.length} entr${orphans.length === 1 ? 'y' : 'ies'} in public/${DATA_DIR}/ with no declared query`
+      })
+      warn(`[${id}] Stale output in public/${DATA_DIR}/: ${orphans.join(', ')}`)
+      log(
+        `    No query produces ${orphans.length === 1 ? 'it' : 'these'}. ` +
+        `${orphans.length === 1 ? 'It is' : 'They are'} still served and deployed.`
+      )
+      if (shouldFix(id)) {
+        for (const entry of orphans) {
+          rmSync(join(dataDir, entry.replace(/\/$/, '')), { recursive: true, force: true })
+        }
+        fixed(`removed ${orphans.length} stale entr${orphans.length === 1 ? 'y' : 'ies'} from public/${DATA_DIR}/`)
+      } else {
+        log(`    ${colors.dim}Run \`uniweb doctor --fix ${id}\` to remove ${orphans.length === 1 ? 'it' : 'them'}.${colors.reset}`)
+      }
+    }
+  }
+
+  // The ignore rule. Checked whether or not the directory exists yet — the
+  // point is to have it in place *before* the first build writes there.
+  const gitignorePath = join(sitePath, '.gitignore')
+  const rule = `public/${DATA_DIR}/`
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : null
+  const covered =
+    existing !== null &&
+    existing
+      .split('\n')
+      .map((line) => line.trim().replace(/\/$/, ''))
+      .includes(rule.replace(/\/$/, ''))
+
+  if (!covered) {
+    const id = 'generated-data-not-ignored'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `public/${DATA_DIR}/ is generated but not gitignored`
+    })
+    warn(`[${id}] public/${DATA_DIR}/ is build output but not in .gitignore`)
+    log(`    Committing it means a diff on every build, and it invites editing what the build overwrites.`)
+    if (shouldFix(id)) {
+      const body = existing === null ? '' : existing.replace(/\n*$/, '\n')
+      writeFileSync(
+        gitignorePath,
+        `${body}\n# Compiled query results — generated from records/ + queries.yml\n${rule}\n`
+      )
+      fixed(`added ${rule} to ${gitignorePath}`)
+      if (existsSync(dataDir)) {
+        log(`    ${colors.dim}Already-committed files need \`git rm -r --cached public/${DATA_DIR}\`.${colors.reset}`)
+      }
+    } else {
+      log(`    ${colors.dim}Run \`uniweb doctor --fix ${id}\` to add it.${colors.reset}`)
+    }
+  }
+}
+
+/**
+ * Main doctor command
+ */
+export async function doctor(args = []) {
+  log('')
+  log(`${colors.blue}${colors.bright}Uniweb Doctor${colors.reset}`)
+  log(`${colors.dim}Checking project configuration...${colors.reset}`)
+
+  // Auto-fix mode. `--fix` alone fixes every recoverable issue;
+  // `--fix <issue-id>` targets one. Per-issue fix logic lives next to
+  // each diagnostic below so the rewrite happens with full context.
+  const fixFlag = parseFixFlag(args)
+  const shouldFix = (id) => fixFlag === 'all' || fixFlag === id
+  // ⛔ SOME FIXES MUST NOT RIDE A BARE `--fix`. A fix derived from a GUESS — the
+  // family aliases, which exist in the CLI precisely so a human approves each
+  // one — becomes a silent write the moment `--fix` alone applies it, which is
+  // the failure the guess was moved here to avoid. Those checks ask for the id.
+  const shouldFixExplicitly = (id) => fixFlag === id
+  const fixed = (msg) =>
+    console.log(`  ${colors.green}↳ Fixed:${colors.reset} ${msg}`)
+
+  const projectDir = resolve(process.cwd())
+
+  // Find workspace root via the canonical primitive (recognizes
+  // pnpm-workspace.yaml or package.json::workspaces).
+  const workspaceDir = findWorkspaceRoot(projectDir)
+
+  if (!workspaceDir) {
+    error('Not in a Uniweb workspace')
+    log(
+      `${colors.dim}Run this command from your project root or a site/foundation directory.${colors.reset}`
+    )
+    process.exit(1)
+  }
+
+  log('')
+  info(`Workspace: ${workspaceDir}`)
+
+  // Workspace manifest sync — keep `pnpm-workspace.yaml::packages` and
+  // `package.json::workspaces` aligned. The CLI writes both on every
+  // mutation (see addWorkspaceGlob in utils/config.js), but a user who
+  // manually edits one can introduce drift. Drift breaks projects that
+  // switch package managers (pnpm-workspace.yaml is pnpm-only;
+  // package.json::workspaces is what npm and yarn read).
+  const issues = []
+  const ymlPath = join(workspaceDir, 'pnpm-workspace.yaml')
+  if (existsSync(ymlPath)) {
+    let ymlPackages = []
+    try {
+      ymlPackages = yaml.load(readFileSync(ymlPath, 'utf8'))?.packages || []
+    } catch {
+      // Malformed yaml — flag separately
+      issues.push({
+        id: 'workspace-yaml-malformed',
+        type: 'error',
+        message: 'pnpm-workspace.yaml is malformed and could not be parsed.'
+      })
+      error('pnpm-workspace.yaml is malformed and could not be parsed.')
+    }
+    const rootPkg = loadPackageJson(workspaceDir)
+    const pkgWorkspaces = Array.isArray(rootPkg?.workspaces)
+      ? rootPkg.workspaces
+      : []
+    const ymlSet = new Set(ymlPackages)
+    const pkgSet = new Set(pkgWorkspaces)
+    const onlyInYml = [...ymlSet].filter((g) => !pkgSet.has(g))
+    const onlyInPkg = [...pkgSet].filter((g) => !ymlSet.has(g))
+    if (onlyInYml.length || onlyInPkg.length) {
+      const issue = {
+        id: 'workspace-manifests-out-of-sync',
+        type: 'warn',
+        message: `pnpm-workspace.yaml and package.json::workspaces declare different package globs.`,
+        details: { onlyInYml, onlyInPkg }
+      }
+      issues.push(issue)
+      warn(
+        `[workspace-manifests-out-of-sync] pnpm-workspace.yaml and package.json::workspaces are out of sync:`
+      )
+      if (onlyInYml.length)
+        log(`    only in pnpm-workspace.yaml:        ${onlyInYml.join(', ')}`)
+      if (onlyInPkg.length)
+        log(`    only in package.json::workspaces:    ${onlyInPkg.join(', ')}`)
+      if (shouldFix('workspace-manifests-out-of-sync')) {
+        // Canonical resolution: write the union to both manifests.
+        const union = Array.from(
+          new Set([...ymlPackages, ...pkgWorkspaces])
+        ).sort()
+        writeFileSync(
+          ymlPath,
+          yaml.dump({ packages: union }, { flowLevel: -1, quotingType: '"' })
+        )
+        const rootPkgPath = join(workspaceDir, 'package.json')
+        const rootPkgSrc = readFileSync(rootPkgPath, 'utf-8')
+        const rootPkg = JSON.parse(rootPkgSrc)
+        rootPkg.workspaces = union
+        writeJsonPreservingStyle(rootPkgPath, rootPkg, rootPkgSrc)
+        issue.fixed = true
+        fixed(`wrote union [${union.join(', ')}] to both manifests`)
+      } else {
+        log(
+          `  ${colors.dim}Pick one set of globs and copy it to the other manifest. The two should always match — pnpm reads pnpm-workspace.yaml, npm/yarn read package.json::workspaces.${colors.reset}`
+        )
+      }
+    }
+  }
+
+  // Discover foundations + sites via the canonical workspace globs.
+  // Doctor used to walk fixed paths (`foundation/`, `foundations/*`) which
+  // missed the default-path `src/` shape that Thread D made canonical.
+  // Using the same primitives every other command uses keeps doctor in
+  // step with whatever layout the workspace has.
+  const discovered = await discoverFoundations(workspaceDir)
+  const foundations = []
+  const extensions = []
+  for (const f of discovered) {
+    const fullPath = join(workspaceDir, f.path)
+    const folderName = basename(f.path)
+    const entry = { path: fullPath, name: f.name, folderName }
+    if (buildIsExtensionPackage(fullPath)) {
+      extensions.push(entry)
+    } else {
+      foundations.push(entry)
+    }
+  }
+
+  if (foundations.length === 0) {
+    warn('No foundations found')
+  } else {
+    success(`Found ${foundations.length} foundation(s):`)
+    for (const f of foundations) {
+      const nameMismatch =
+        f.name !== f.folderName
+          ? ` ${colors.dim}(folder: ${f.folderName}/)${colors.reset}`
+          : ''
+      log(`    • ${f.name}${nameMismatch}`)
+    }
+  }
+
+  // Prose without the tokens — a silent, total loss of styling.
+  //
+  // `@uniweb/kit/prose-tokens.css` brings Tailwind Typography with it and then
+  // points it at the site's theme.yml. A foundation that writes `prose` (or
+  // renders <Prose>/<Article>, which emit it) and does NOT import that file
+  // gets the class and no rules behind it: correct markup, zero styling, and
+  // nothing reported anywhere. Measured 2026-07-30 on a foundation missing only
+  // the plugin — every paragraph `margin-top: 0px`, no warning from Vite,
+  // Tailwind or the browser.
+  //
+  // kit closes this for anyone who imports the file; this closes it for anyone
+  // who does not, which is the case kit cannot reach.
+  for (const f of foundations) {
+    // `f.path` is already absolute (built above with join(workspaceDir, …)).
+    const stylesPath = join(f.path, 'styles.css')
+    if (!existsSync(stylesPath)) continue
+
+    const styles = readFileSync(stylesPath, 'utf8')
+    if (styles.includes('@uniweb/kit/prose-tokens.css')) continue
+
+    // Does anything here actually ask for prose? Either the class in the
+    // stylesheet, or kit's components, which render it.
+    const usesProseComponent = rendersKitProse(f.path)
+    const usesProseClass = /(^|[\s"'`])prose(\s|["'`]|$)/m.test(styles)
+
+    if (!usesProseClass && !usesProseComponent) continue
+
+    const id = 'prose-without-tokens'
+    const reason = usesProseComponent
+      ? 'renders <Prose> or <Article>'
+      : 'uses the `prose` class'
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: f.name,
+      message: `${f.name} ${reason} but does not import prose-tokens.css`
+    })
+    warn(`[${id}] ${f.name} ${reason}, with no prose styling behind it`)
+    log(
+      `    Tailwind Typography supplies the rules and it is not loaded, so the ` +
+      `markup is correct and completely unstyled — silently.`
+    )
+    log(`    Add to ${f.folderName}/styles.css:`)
+    log(`      ${colors.dim}@import "@uniweb/kit/prose-tokens.css";${colors.reset}`)
+  }
+
+  // ⛔ SAY WHEN A CHECK DID NOT RUN. Every foundation check below reads the
+  // BUILT `dist/meta/schema.json` — what a consumer actually receives — and
+  // returns silently when there is none. In a workspace with a site, "Foundation
+  // not built yet" turns up later under that site; in a FOUNDATION-ONLY
+  // workspace, which is the normal shape when a foundation is the product, it
+  // never does. The report then looks clean because nothing ran.
+  //
+  // That is the same class as the `dist/schema.json` path bug (a check that
+  // never fires is indistinguishable from a codebase with nothing to report),
+  // so it is named here rather than left to be rediscovered.
+  for (const f of foundations) {
+    if (!loadSchemaJson(f.path)) {
+      info(
+        `${f.folderName}: not built, so nothing was checked here ` +
+          `${colors.dim}(services, section families, retired keys)${colors.reset}`
+      )
+      log(`    ${colors.dim}Run \`uniweb build\` in ${f.folderName}, then doctor again.${colors.reset}`)
+    }
+  }
+
+  // ── uniweb.supports — the services this foundation says it is built against ──
+  for (const f of foundations) {
+    await checkFoundationSupports({
+      foundationName: f.name,
+      folderName: f.folderName,
+      foundationDir: f.path,
+      pkg: loadPackageJson(f.path),
+      issues,
+      shouldFix,
+      fixed
+    })
+    checkUngatedServiceControls({
+      foundationName: f.name,
+      folderName: f.folderName,
+      srcDir: resolveFoundationSrcPath(f.path),
+      issues
+    })
+    checkSectionFamilies({
+      foundationName: f.name,
+      folderName: f.folderName,
+      foundationDir: f.path,
+      issues,
+      shouldFixExplicitly,
+      fixed
+    })
+    checkRetiredMetaKeys({
+      foundationName: f.name,
+      folderName: f.folderName,
+      foundationDir: f.path,
+      issues
+    })
+  }
+
+  // Extensions carry `uniweb.supports` too — same key, same field, and a site's
+  // answer is the union across its primary foundation and its extensions. The
+  // regex-era check looked at foundations only, so an extension that drew a
+  // search box was never asked about one.
+  for (const e of extensions) {
+    await checkFoundationSupports({
+      foundationName: e.name,
+      folderName: e.folderName,
+      foundationDir: e.path,
+      pkg: loadPackageJson(e.path),
+      issues,
+      shouldFix,
+      fixed
+    })
+    checkUngatedServiceControls({
+      foundationName: e.name,
+      folderName: e.folderName,
+      srcDir: resolveFoundationSrcPath(e.path),
+      issues
+    })
+    // An extension contributes section types by URL and lands in the same
+    // picker, so its sections need a family for exactly the same reason.
+    checkSectionFamilies({
+      foundationName: e.name,
+      folderName: e.folderName,
+      foundationDir: e.path,
+      issues,
+      shouldFixExplicitly,
+      fixed
+    })
+    checkRetiredMetaKeys({
+      foundationName: e.name,
+      folderName: e.folderName,
+      foundationDir: e.path,
+      issues
+    })
+  }
+
+  if (extensions.length > 0) {
+    log('')
+    success(`Found ${extensions.length} extension(s):`)
+    for (const e of extensions) {
+      const nameMismatch =
+        e.name !== e.folderName
+          ? ` ${colors.dim}(folder: ${e.folderName}/)${colors.reset}`
+          : ''
+      log(`    • ${e.name}${nameMismatch}`)
+    }
+  }
+
+  // Discover sites via the canonical workspace globs (same rationale as
+  // foundations above: respects whatever layout the user chose).
+  const sites = (await discoverSites(workspaceDir)).map((s) => ({
+    path: join(workspaceDir, s.path),
+    name: s.name
+  }))
+
+  if (sites.length === 0) {
+    warn('No sites found')
+  } else {
+    log('')
+    success(`Found ${sites.length} site(s):`)
+    for (const s of sites) {
+      log(`    • ${s.name}`)
+    }
+  }
+
+  // Check each site (issues array was declared earlier alongside the
+  // workspace-manifest-sync check).
+  for (const site of sites) {
+    const siteName = site.name
+    const sitePath = site.path
+    const siteYml = loadSiteYml(sitePath)
+    const sitePkg = loadPackageJson(sitePath)
+
+    log('')
+    info(`Checking site: ${siteName}`)
+
+    if (!siteYml) {
+      issues.push({
+        type: 'error',
+        site: siteName,
+        message: 'Missing site.yml'
+      })
+      error('Missing site.yml')
+      continue
+    }
+
+    if (!sitePkg) {
+      issues.push({
+        type: 'error',
+        site: siteName,
+        message: 'Missing package.json'
+      })
+      error('Missing package.json')
+      continue
+    }
+
+    // The agent index ships by default, but it can only carry absolute links
+    // when the site declares where it lives. Root-relative links still work
+    // for an agent that arrived via the index, so this warns rather than
+    // suppressing the artifact the way sitemap.xml does — a silently absent
+    // index is the exact failure the projections exist to prevent.
+    const agentsConfig = siteYml.agents
+    const indexEnabled = agentsConfig !== false && agentsConfig?.index !== false
+    if (indexEnabled && !siteYml.seo?.baseUrl) {
+      const issue = {
+        id: 'agents-index-relative-links',
+        type: 'warning',
+        site: siteName,
+        message:
+          'llms.txt will use root-relative links because seo.baseUrl is unset'
+      }
+      issues.push(issue)
+      warn(`[agents-index-relative-links] llms.txt links will be root-relative`)
+      log(
+        `    Set ${colors.green}seo.baseUrl${colors.reset} in site.yml so agents get absolute URLs`
+      )
+      log(
+        `    (this also turns on sitemap.xml and robots.txt, which are skipped without it)`
+      )
+    }
+
+    // `public/<DATA_DIR>/` is the build's output directory and nothing else —
+    // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed
+    // by a declared QUERY, so anything else is stale, and identifiable.
+    //
+    // It matters because the directory is written into the source tree rather
+    // than dist/, so what lands there persists and gets deployed. A collection
+    // removed from site.yml leaves its compiled records behind — visible to
+    // anyone who knows the URL, listed by nothing.
+    // Forms need a destination, and having none is only visible on the page.
+    await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
+    checkAgentsBlock({ siteName, siteYml, issues })
+    checkTrackingBlock({ siteName, siteYml, issues })
+
+    checkGeneratedDataDir({
+      sitePath,
+      siteName,
+      siteYml,
+      issues,
+      shouldFix,
+      fixed
+    })
+
+    const foundationName = siteYml.foundation
+    if (!foundationName) {
+      warn('No foundation specified in site.yml (using runtime loading?)')
+      continue
+    }
+
+    // Check if foundation name matches a known foundation
+    const matchingFoundation = foundations.find(
+      (f) => f.name === foundationName
+    )
+
+    if (!matchingFoundation) {
+      // Check if it might match a folder name instead
+      const folderMatch = foundations.find(
+        (f) => f.folderName === foundationName
+      )
+      if (folderMatch) {
+        const issue = {
+          id: 'foundation-name-mismatch',
+          type: 'error',
+          site: siteName,
+          message: `Foundation mismatch: site.yml uses folder name "${foundationName}" instead of package name "${folderMatch.name}"`
+        }
+        issues.push(issue)
+        error(`[foundation-name-mismatch] Foundation mismatch:`)
+        log(
+          `    site.yml says: ${colors.yellow}foundation: ${foundationName}${colors.reset}`
+        )
+        log(
+          `    This matches the folder name, but the package name is: ${colors.green}${folderMatch.name}${colors.reset}`
+        )
+        if (shouldFix('foundation-name-mismatch')) {
+          const siteYmlPath = join(sitePath, 'site.yml')
+          const updated = { ...siteYml, foundation: folderMatch.name }
+          writeFileSync(
+            siteYmlPath,
+            yaml.dump(updated, { flowLevel: -1, quotingType: "'" })
+          )
+          issue.fixed = true
+          fixed(
+            `${relative(workspaceDir, siteYmlPath)} now references "${folderMatch.name}"`
+          )
+        } else {
+          log('')
+          log(`  ${colors.dim}To fix, update site.yml:${colors.reset}`)
+          log(`    foundation: ${folderMatch.name}`)
+        }
+        continue
+      }
+
+      issues.push({
+        type: 'error',
+        site: siteName,
+        message: `Foundation "${foundationName}" not found`
+      })
+      error(`Foundation "${foundationName}" not found`)
+      log('')
+      log(`  ${colors.dim}Available foundations:${colors.reset}`)
+      for (const f of foundations) {
+        log(`    • ${f.name} (${f.folderName}/)`)
+      }
+      continue
+    }
+
+    success(`Foundation reference: ${foundationName}`)
+
+    // Check package.json dependency
+    const deps = { ...sitePkg.dependencies, ...sitePkg.devDependencies }
+    const depValue = deps[foundationName]
+
+    if (!depValue) {
+      const issue = {
+        id: 'missing-foundation-dep',
+        type: 'error',
+        site: siteName,
+        message: `Missing dependency "${foundationName}" in package.json`
+      }
+      issues.push(issue)
+      error(
+        `[missing-foundation-dep] Missing dependency "${foundationName}" in package.json`
+      )
+      const expectedPath = `file:${relative(sitePath, matchingFoundation.path)}`
+      if (shouldFix('missing-foundation-dep')) {
+        const sitePkgPath = join(sitePath, 'package.json')
+        const updatedPkg = { ...sitePkg }
+        updatedPkg.dependencies = {
+          ...(updatedPkg.dependencies || {}),
+          [foundationName]: expectedPath
+        }
+        writeJsonPreservingStyle(sitePkgPath, updatedPkg)
+        issue.fixed = true
+        fixed(
+          `added "${foundationName}": "${expectedPath}" to ${relative(workspaceDir, sitePkgPath)}`
+        )
+      } else {
+        log('')
+        log(
+          `  ${colors.dim}Add to site's package.json dependencies:${colors.reset}`
+        )
+        log(`    "${foundationName}": "${expectedPath}"`)
+      }
+      continue
+    }
+
+    if (depValue.startsWith('file:')) {
+      const depPath = join(sitePath, depValue.slice(5))
+      if (!existsSync(depPath)) {
+        const issue = {
+          id: 'stale-file-path',
+          type: 'error',
+          site: siteName,
+          message: `Dependency path doesn't exist: ${depValue}`
+        }
+        issues.push(issue)
+        error(`[stale-file-path] Dependency path doesn't exist: ${depValue}`)
+        const expectedPath = `file:${relative(sitePath, matchingFoundation.path)}`
+        if (shouldFix('stale-file-path')) {
+          const sitePkgPath = join(sitePath, 'package.json')
+          const updatedPkg = { ...sitePkg }
+          updatedPkg.dependencies = {
+            ...(updatedPkg.dependencies || {}),
+            [foundationName]: expectedPath
+          }
+          writeJsonPreservingStyle(sitePkgPath, updatedPkg)
+          issue.fixed = true
+          fixed(
+            `updated "${foundationName}" to "${expectedPath}" in ${relative(workspaceDir, sitePkgPath)}`
+          )
+        } else {
+          log('')
+          log(`  ${colors.dim}Update site's package.json:${colors.reset}`)
+          log(`    "${foundationName}": "${expectedPath}"`)
+        }
+        continue
+      }
+      success(`Dependency path: ${depValue}`)
+    } else {
+      success(`Dependency: ${depValue} (npm package)`)
+    }
+
+    // Is what is installed what is declared? A `file:` dependency can be
+    // satisfied by a link or by a copy, and only the link stays true. The copy
+    // is invisible to a build — which reads the workspace source directly — so
+    // it surfaces as a dev server serving stale code, or nothing at all.
+    for (const finding of checkSiteInstall(
+      { name: siteName, path: sitePath },
+      matchingFoundation,
+      workspaceDir
+    )) {
+      issues.push({
+        id: finding.id,
+        type: finding.severity,
+        site: siteName,
+        message: finding.message
+      })
+      error(`[${finding.id}] ${finding.message}`)
+      log(`${colors.dim}${finding.detail}${colors.reset}`)
+      log('')
+      log(`  ${colors.dim}To fix: ${finding.remedy}${colors.reset}`)
+    }
+
+    // Check if foundation is built
+    const foundationDist = join(matchingFoundation.path, 'dist', 'entry.js')
+    if (!existsSync(foundationDist)) {
+      issues.push({
+        type: 'warn',
+        site: siteName,
+        message: `Foundation not built: ${matchingFoundation.name}`
+      })
+      warn(`Foundation not built yet`)
+      log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
+    } else {
+      success(`Foundation built: dist/entry.js exists`)
+    }
+  }
+
+  // Check extensions
+  for (const ext of extensions) {
+    log('')
+    info(`Checking extension: ${ext.name}`)
+
+    // An extension is a package that declares `extension: true` — that is how it
+    // was told apart from the foundations above, wherever its folder is. (A check
+    // here that it declares it could never fail, and was removed 2026-10-08.)
+    success(`Extension identity: extension: true`)
+
+    // Check for vars or layouts
+    const schema = loadSchemaJson(ext.path)
+
+    if (schema?._self?.vars && Object.keys(schema._self.vars).length > 0) {
+      issues.push({
+        type: 'warn',
+        message: `Extension "${ext.name}" declares theme variables (vars). Extensions don't define theme variables.`
+      })
+      warn(`Extension declares vars — these won't take effect`)
+    }
+
+    if (schema?._layouts && Object.keys(schema._layouts).length > 0) {
+      issues.push({
+        type: 'warn',
+        message: `Extension "${ext.name}" provides layouts. Extensions don't provide layouts.`
+      })
+      warn(`Extension provides layouts — these won't take effect`)
+    }
+
+    // Check if built
+    const extensionDist = join(ext.path, 'dist', 'entry.js')
+    if (!existsSync(extensionDist)) {
+      issues.push({
+        type: 'warn',
+        message: `Extension not built: ${ext.name}`
+      })
+      warn(`Extension not built yet`)
+      log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
+    } else {
+      success(`Extension built: dist/entry.js exists`)
+    }
+  }
+
+  // Check if any foundation with extension: true is wired as a primary foundation
+  for (const f of foundations) {
+    if (isExtensionPackage(f.path)) {
+      const sitesUsingAsPrimary = sites.filter((s) => {
+        const siteYml = loadSiteYml(s.path)
+        return siteYml?.foundation === f.name
+      })
+      for (const site of sitesUsingAsPrimary) {
+        issues.push({
+          type: 'warn',
+          site: site.name,
+          message: `Foundation "${f.name}" declares extension: true but is wired as the primary foundation. It should be in extensions: instead.`
+        })
+        warn(
+          `"${f.name}" is an extension but used as primary foundation in site "${site.name}"`
+        )
+        log(
+          `  ${colors.dim}Move it to extensions: in site.yml instead of foundation:${colors.reset}`
+        )
+      }
+    }
+  }
+
+  // Validate extension URLs in site.yml
+  for (const site of sites) {
+    const siteYml = loadSiteYml(site.path)
+    if (!siteYml?.extensions || !Array.isArray(siteYml.extensions)) continue
+
+    for (const extUrl of siteYml.extensions) {
+      if (typeof extUrl !== 'string') continue
+
+      // Skip remote URLs — can't validate those
+      if (extUrl.startsWith('http://') || extUrl.startsWith('https://'))
+        continue
+
+      // Local extension URL: check if it maps to a known extension
+      // URLs like /effects/foundation.js or /extensions/effects/foundation.js
+      const urlParts = extUrl.replace(/^\//, '').split('/')
+      const extName =
+        urlParts.length >= 2 ? urlParts[urlParts.length - 2] : urlParts[0]
+
+      // Check if a matching extension exists and is built
+      const matchingExt = extensions.find(
+        (e) => e.folderName === extName || e.name === extName
+      )
+      if (
+        matchingExt &&
+        !existsSync(join(matchingExt.path, 'dist', 'entry.js'))
+      ) {
+        issues.push({
+          type: 'warn',
+          site: site.name,
+          message: `Extension "${extName}" referenced in site.yml is not built`
+        })
+      }
+    }
+  }
+
+  // ─── 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}`
+      )
+    }
+  }
+
+  const cliVersion = getCliVersion()
+
+  // Check @uniweb/* dep alignment with the running CLI
+  log('')
+  const depSurvey = await surveyWorkspaceDeps(workspaceDir)
+  const behindDeps = depSurvey.rows.filter((r) => r.status === 'behind')
+  if (behindDeps.length > 0) {
+    const names = [...new Set(behindDeps.map((r) => r.name))].sort()
+    warn(
+      `${behindDeps.length} workspace dep declaration${behindDeps.length === 1 ? '' : 's'} lag the CLI (v${cliVersion}): ${names.join(', ')}`
+    )
+    info(`Run: uniweb update`)
+    issues.push({
+      type: 'warn',
+      message: `${behindDeps.length} @uniweb/* dep declaration(s) behind CLI v${cliVersion}`
+    })
+  } else if (depSurvey.anyAhead) {
+    success(`@uniweb/* deps are aligned or ahead of the CLI (v${cliVersion})`)
+  } else {
+    success(`@uniweb/* deps are aligned with the CLI (v${cliVersion})`)
+  }
+
+  // Check AGENTS.md freshness
+  log('')
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const agentsVersion = readAgentsVersion(agentsPath)
+
+  if (!existsSync(agentsPath)) {
+    warn('AGENTS.md not found')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md not found' })
+  } else if (!agentsVersion) {
+    // No stamp — manually created or pre-stamp version
+    warn('AGENTS.md has no version stamp (may be outdated)')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md has no version stamp' })
+  } else if (agentsVersion !== cliVersion) {
+    warn(`AGENTS.md is outdated (v${agentsVersion} → v${cliVersion})`)
+    info(`Run: uniweb update`)
+    issues.push({
+      type: 'warn',
+      message: `AGENTS.md outdated (v${agentsVersion} → v${cliVersion})`
+    })
+  } else {
+    success(`AGENTS.md is up to date (v${cliVersion})`)
+  }
+
+  // Summary
+  log('')
+  log('─'.repeat(50))
+
+  // Fixed issues no longer count toward errors/warnings — they're
+  // resolved during this run. Exit code is based on what remains.
+  const errors = issues.filter((i) => i.type === 'error' && !i.fixed)
+  const warnings = issues.filter((i) => i.type === 'warn' && !i.fixed)
+  const fixedCount = issues.filter((i) => i.fixed).length
+
+  if (errors.length === 0 && warnings.length === 0 && fixedCount === 0) {
+    log('')
+    log(`${colors.green}${colors.bright}All checks passed!${colors.reset}`)
+    log('')
+  } else {
+    log('')
+    if (fixedCount > 0) {
+      log(`${colors.green}${fixedCount} issue(s) fixed${colors.reset}`)
+    }
+    if (errors.length > 0) {
+      log(`${colors.red}${errors.length} error(s) remaining${colors.reset}`)
+    }
+    if (warnings.length > 0) {
+      log(
+        `${colors.yellow}${warnings.length} warning(s) remaining${colors.reset}`
+      )
+    }
+    if (fixFlag && (errors.length > 0 || warnings.length > 0)) {
+      log(
+        `${colors.dim}Some issues were not auto-fixable. See the diagnostics above.${colors.reset}`
+      )
+    }
+    log('')
+  }
+
+  return {
+    issues,
+    errors: errors.length,
+    warnings: warnings.length,
+    fixed: fixedCount
+  }
+}