uniweb 0.12.7 → 0.12.9

package/src/commands/deploy.js

@@ -1,12 +1,23 @@
 /**
  * Deploy Command
  *
- * Deploys a built site to Uniweb hosting. Phase 1 — link-mode, content + theme
- * + locales only (no binary assets yet).
+ * Deploys a site. Host is determined by `deploy.host` in site.yml (or
+ * `--host <name>` flag). The default is `uniweb`:
  *
- * Flow:
+ *   - `uniweb` (default): Uniweb hosting — link-mode + edge JIT prerender.
+ *     Foundation loaded by URL from the registry. Requires `uniweb login`
+ *     and a `foundation:` declaration in site.yml.
+ *
+ *   - Static-host adapters (`s3-cloudfront`, `cloudflare-pages`,
+ *     `github-pages`, `generic-static`, …): build dist/ in bundle-mode
+ *     and hand it to a host adapter for upload + invalidation. No login,
+ *     no edge. See kb/framework/plans/static-host-deploy-adapters.md.
+ *
+ * For static-host artifacts WITHOUT upload, see `uniweb export`.
+ *
+ * Default-flow steps:
  *   1. Read site.yml → { site.id?, site.handle?, foundation, runtime? }.
- *   2. Resolve runtime (default: GET /api/runtime/latest from the Worker).
+ *   2. Resolve runtime (default: GET /runtime/latest from the Worker).
  *   3. ensureAuth() → bearer CLI JWT from ~/.uniweb/auth.json.
  *   4. Build `dist/` if missing.
  *   5. Load dist/site-content.json → extract `languages` for the capability
@@ -18,19 +29,25 @@
  *        - publishToken returned → fast path.
  *        - needsReview:true + reviewUrl → open browser, wait for callback,
  *          consume { publishToken, siteId, handle }.
- *   9. POST Worker /api/publish/validate to confirm foundation + runtime
+ *   9. POST Worker /publish/check to confirm foundation + runtime
  *      exist and the token's namespace claim matches.
- *  10. POST Worker /api/publish/process with the full payload.
+ *  10. POST Worker /publish with the full payload.
  *  11. On first-deploy create flow: write site.id + site.handle back into
  *      site.yml so subsequent deploys fast-path.
  *
  * Usage:
  *   uniweb deploy                          Normal deploy (browser may open on first deploy)
- *   uniweb deploy --skip-build             Don't rebuild even if dist/ is stale
  *   uniweb deploy --dry-run                Resolve everything but skip the Worker POST
- *   uniweb deploy --skip-billing           Admin-only: bypass billing gate (dev/testing)
- *   uniweb deploy --review                 Force the browser review path even when
- *                                          there's no drift (e.g., to change features)
+ *   uniweb deploy --no-auto-publish        Don't auto-publish workspace-local foundation
+ *   uniweb deploy --host <name>            Static-host flow (e.g., s3-cloudfront,
+ *                                          generic-static). Overrides site.yml deploy.host.
+ *
+ * Internal escape hatches (UNIWEB_* env vars — see framework/cli/docs/env-vars.md):
+ *   UNIWEB_SKIP_BUILD=1                    Reuse existing dist/ instead of rebuilding
+ *   UNIWEB_SKIP_ASSETS=1                   Skip the asset upload step
+ *   UNIWEB_SKIP_BILLING=1                  Admin-only: bypass billing gate
+ *   UNIWEB_FORCE_REVIEW=1                  Force the browser review flow
+ *   UNIWEB_ALLOW_DIRTY_FOUNDATION=1        Don't treat a dirty workspace as stale
  *
  * See kb/platform/plans/cli-site-deploy-decisions.md for the full design.
  */
@@ -46,8 +63,20 @@ import { detectFoundationType } from '@uniweb/build'
 
 import { ensureAuth, readAuth, decodeJwtPayload } from '../utils/auth.js'
 import { getBackendUrl, getRegistryUrl } from '../utils/config.js'
+import { parseBoolEnv } from '../utils/env.js'
 import { RemoteRegistry } from '../utils/registry.js'
-import { receiptFromRegistryEntry, splitRegistryRef } from '../utils/receipt.js'
+
+/**
+ * Split `@ns/name@ver`, `~user/name@ver`, or `name@ver` into name + version.
+ * Returns null on any shape we don't recognize. Inlined here after the
+ * receipt-cache utility module was removed in Phase 4b — the only
+ * remaining caller is the staleness check below.
+ */
+function splitRegistryRef(ref) {
+  if (typeof ref !== 'string') return null
+  const m = /^(@[^/]+\/[^@]+|~[^/]+\/[^@]+|[^@]+)@(.+)$/.exec(ref)
+  return m ? { name: m[1], version: m[2] } : null
+}
 import {
   findWorkspaceRoot,
   findSites,
@@ -215,46 +244,41 @@ function composeFoundationUrl(ref, registryBase) {
 }
 
 /**
- * Inspect a workspace-local foundation's `dist/publish.json` (Phase 1 receipt)
- * and decide whether it's stale relative to the current source tree.
+ * Decide whether a workspace-local foundation is stale relative to the
+ * registry's record, by comparing per-directory git provenance against
+ * the registry entry's `publishedFromGitSha`. No local cache file —
+ * `dist/publish.json` was deleted in Phase 4b of the CLI ergonomics
+ * overhaul because every fresh clone / CI run / collaborator paid the
+ * registry round-trip anyway, and the local cache only added confusing
+ * "stale receipt" warnings when collaborators had different `dist/`
+ * state.
  *
- * When the receipt file is missing and a `registry` is provided, attempt
- * to refill it from the registry's index entry for `<name>@<version>`.
- * That makes the receipt pure cache: a fresh clone with a matching
- * upstream artifact resolves without an unnecessary republish. If the
- * registry has no record (or the stored entry lacks git provenance), the
- * inspector returns `stale: true` and the caller's auto-publish path
- * runs as before.
- *
- * Returns `{ stale, reason, receipt, refilled? }`. The caller decides
- * whether to auto-publish (Phase 2 default) or fail (`--no-auto-publish`).
+ * Returns `{ stale, reason }`. The caller decides whether to auto-publish
+ * (Phase 2 default) or fail (`--no-auto-publish`).
  */
-async function inspectLocalFoundationReceipt(localPath, { dirtyAsStale, registry }) {
-  const receiptPath = join(localPath, 'dist', 'publish.json')
-  let receipt = null
-  let refilled = false
+async function inspectFoundationStaleness(localPath, { dirtyAsStale, registry, ref }) {
+  const { gitSha, gitDirty } = readGitState(localPath)
+  if (!gitSha) {
+    return { stale: true, reason: 'foundation directory is not in a git repo or has no commits' }
+  }
+
+  const split = splitRegistryRef(ref)
+  if (!split) {
+    return { stale: true, reason: 'cannot derive registry ref from package.json' }
+  }
+
+  let existingEntry
   try {
-    receipt = JSON.parse(await readFile(receiptPath, 'utf8'))
+    existingEntry = await registry.getVersionEntry(split.name, split.version)
   } catch {
-    if (registry) {
-      const refill = await tryRefillReceiptFromRegistry({ localPath, registry })
-      if (refill) {
-        await writeFile(receiptPath, JSON.stringify(refill, null, 2) + '\n')
-        receipt = refill
-        refilled = true
-      }
-    }
-    if (!receipt) {
-      return { stale: true, reason: 'no dist/publish.json (foundation has not been published from this checkout)' }
-    }
+    return { stale: true, reason: 'registry lookup failed' }
   }
-
-  const { gitSha, gitDirty } = readGitState(localPath)
-  if (!gitSha) {
-    return { stale: true, reason: 'foundation directory is not in a git repo or has no commits', receipt }
+  if (!existingEntry) {
+    return { stale: true, reason: `${split.name}@${split.version} not yet published` }
   }
-  if (receipt.publishedFromGitSha && receipt.publishedFromGitSha !== gitSha) {
-    // Receipt's recorded sha differs from the foundation's per-directory
+
+  if (existingEntry.publishedFromGitSha && existingEntry.publishedFromGitSha !== gitSha) {
+    // Recorded sha differs from the foundation's per-directory
     // last-touched commit. Normally that's "real" staleness — somebody
     // committed changes to src/ that haven't been republished.
     //
@@ -268,67 +292,17 @@ async function inspectLocalFoundationReceipt(localPath, { dirtyAsStale, registry
     // hasn't materially changed. Don't fire staleness on the sha
     // alone in that case; let the dirty-tree check below do its job
     // if the tree IS still dirty, and otherwise treat as fresh.
-    //
-    // Edge: if the user committed real source changes ON TOP of the
-    // auto-derive in the same commit, we won't detect that as stale
-    // here — the next publish would 409 against the registry though,
-    // surfacing the issue with a clear "bump the version" message.
-    if (!receipt.publishedFromGitDirty) {
+    if (!existingEntry.publishedFromGitDirty) {
       return {
         stale: true,
-        reason: `foundation has new commits since last publish (${receipt.publishedFromGitSha.slice(0, 7)} → ${gitSha.slice(0, 7)})`,
-        receipt,
+        reason: `foundation has new commits since last publish (${existingEntry.publishedFromGitSha.slice(0, 7)} → ${gitSha.slice(0, 7)})`,
       }
     }
   }
   if (gitDirty && dirtyAsStale) {
-    return { stale: true, reason: 'foundation working tree is dirty', receipt }
+    return { stale: true, reason: 'foundation working tree is dirty' }
   }
-  return { stale: false, receipt, refilled }
-}
-
-/**
- * When a receipt is missing, try to reconstruct it from the registry's
- * own record of the publish. We resolve `name@version` from the same
- * package metadata `deriveLocalFoundationRef` uses, then ask the registry
- * for its stored version entry. The entry's `publishedFromGitSha` is the
- * load-bearing field — without it (entries written before git provenance
- * was added) we can't compare against HEAD, so we don't synthesize a
- * misleading "fresh" receipt and let the caller fall through to the
- * republish path.
- *
- * Returns the receipt body, or null when refill is not possible.
- */
-async function tryRefillReceiptFromRegistry({ localPath, registry }) {
-  // Two ways to derive the canonical `<name>@<version>`:
-  //   1. `deriveLocalFoundationRef` — works for org-scope foundations
-  //      (where the namespace is in package.json) and for any foundation
-  //      where a previous receipt already exists. On the wipe-and-deploy
-  //      path that fired this code, the receipt is gone, so this only
-  //      works for org-scope.
-  //   2. Empty-scope fallback — if package.json has `uniweb.id` and the
-  //      user's auth.json carries a `memberUuid` claim, we can synthesize
-  //      `~<memberUuid>/<id>@<version>` directly. Same shape the server
-  //      stores under.
-  let ref = await deriveLocalFoundationRef(localPath)
-  if (!ref) ref = await refFromAuthAndPkg(localPath)
-  const split = splitRegistryRef(ref)
-  if (!split) return null
-  let existingEntry
-  try {
-    existingEntry = await registry.getVersionEntry(split.name, split.version)
-  } catch {
-    return null
-  }
-  if (!existingEntry) return null
-  return receiptFromRegistryEntry({
-    existingEntry,
-    registry,
-    name: split.name,
-    version: split.version,
-    isLocal: false,
-    isPropagateDefault: false,
-  })
+  return { stale: false }
 }
 
 /**
@@ -365,11 +339,10 @@ async function refFromAuthAndPkg(localPath) {
  *
  * Resolution order:
  *   1. Org scope from `pkg.uniweb.namespace` or `pkg.name`'s `@org/...` prefix.
- *   2. The receipt at `dist/publish.json`. After a successful publish, the
- *      receipt's `url` carries the canonical server-rewritten name —
- *      including empty-scope publishes, which the server rewrites to
- *      `~<memberUuid>/<name>`. The CLI can't synthesize that locally
- *      because the memberUuid lives in the JWT, not in the workspace.
+ *   2. Empty-scope synthesis from `pkg.uniweb.id` + the user's auth claim
+ *      (`~<memberUuid>/<id>@<version>`). Same canonical shape the server
+ *      stores under for empty-scope publishes. Phase 4d will replace this
+ *      with `~{siteId}/...` derived from authorize.
  *   3. null — caller falls through to the helpful "set uniweb.namespace"
  *      error message.
  */
@@ -403,154 +376,37 @@ async function deriveLocalFoundationRef(localPath) {
     return `@${namespace}/${bareName}@${version}`
   }
 
-  // Empty-scope path — read the canonical name from the receipt's URL.
-  // The server rewrites bare names to `~<memberUuid>/<name>`; the URL it
-  // returns carries that canonical form (e.g.
-  // `/foundations/~<uuid>/<name>@<ver>/foundation.js`). Parse it back.
-  const fromReceipt = await refFromReceiptUrl(localPath)
-  if (fromReceipt) return fromReceipt
+  // Empty-scope fallback: synthesize `~<memberUuid>/<id>@<version>` from
+  // the user's auth + package.json::uniweb.id. Same canonical shape the
+  // server stores under for empty-scope publishes. After Phase 4d this
+  // path is replaced by `~{siteId}/...` derived from authorize.
+  const fromAuth = await refFromAuthAndPkg(localPath)
+  if (fromAuth) return fromAuth
 
   return null
 }
 
-// Personal-scope namespaces are base58 memberUuids (mixed case; the
-// alphabet is `[A-HJ-NP-Za-km-z1-9]`). Org-scope handles are
-// lowercase-only. Allow both shapes here so the regex captures personal
-// scopes correctly. The bare-name portion (after the `/`) stays
-// lowercase per BARE_NAME_RE.
-const RECEIPT_URL_REF_RE = /\/foundations\/((?:@[a-z0-9_-]+|~[A-Za-z0-9_-]+)\/[a-z0-9_-]+)@([^/]+)\//
-
-async function refFromReceiptUrl(localPath) {
-  try {
-    const receipt = JSON.parse(await readFile(join(localPath, 'dist', 'publish.json'), 'utf8'))
-    const m = RECEIPT_URL_REF_RE.exec(receipt?.url || '')
-    if (m) return `${m[1]}@${m[2]}`
-  } catch {
-    // No receipt, malformed JSON, or URL doesn't carry the canonical
-    // shape — fall through to null.
-  }
-  return null
-}
-
-/**
- * Resolve the deploy mode for this site.
- *
- * Returns `'link'` or `'bundle'`, optionally prompting the user when
- * neither inference nor an explicit flag yields an answer. Mode choice
- * is persisted server-side after the first successful deploy; switching
- * modes later requires deleting the site and redeploying fresh.
- *
- * Ladder (first match wins):
- *   1. `--link` or `--bundle` flag passed explicitly.
- *   2. `site.yml::foundation` is a registry ref (`@org/x@ver` or
- *      `~uuid/x@ver`) or full HTTPS URL → infer link. The user already
- *      declared "load this foundation by URL at runtime."
- *   3. `site.yml::foundation` is a workspace-local sibling AND that
- *      foundation has a publish receipt (`dist/publish.json` with a
- *      registry URL) → infer link. The user has already done the work
- *      to make the foundation loadable from the registry.
- *   4. Otherwise → ask (TTY prompt) or error (CI).
- *
- * @param {Object} ctx
- * @param {string} ctx.foundationRef - the raw value of site.yml::foundation (string or normalized object).
- * @param {string} ctx.siteDir - absolute path to the site dir (for resolving local foundation siblings).
- * @param {boolean} ctx.linkFlag
- * @param {boolean} ctx.bundleFlag
- * @returns {Promise<{ mode: 'link'|'bundle', source: 'flag'|'inferred-registry-ref'|'inferred-published-local'|'asked' }>}
- */
-async function resolveDeployMode({ foundationRef, siteDir, linkFlag, bundleFlag }) {
-  // 1. Explicit flag wins.
-  if (linkFlag) return { mode: 'link', source: 'flag' }
-  if (bundleFlag) return { mode: 'bundle', source: 'flag' }
-
-  // 2. Registry ref or URL in site.yml → link mode is the only sensible choice.
-  if (typeof foundationRef === 'string') {
-    if (foundationRef.startsWith('http://') || foundationRef.startsWith('https://')) {
-      return { mode: 'link', source: 'inferred-registry-ref' }
-    }
-    if (/^@[a-z0-9_-]+\/[a-z0-9_-]+@/.test(foundationRef)) {
-      return { mode: 'link', source: 'inferred-registry-ref' }
-    }
-    if (/^~[A-Za-z0-9_-]+\/[a-z0-9_-]+@/.test(foundationRef)) {
-      return { mode: 'link', source: 'inferred-registry-ref' }
-    }
-  }
-
-  // 3. Workspace-local foundation with an existing publish receipt → infer link.
-  //    The receipt being there means the user has already published this
-  //    foundation at least once, so they've shown intent to ship via the
-  //    registry. We don't validate the receipt's freshness here — that's
-  //    the existing inspectLocalFoundationReceipt path's job, which runs
-  //    later in the deploy flow.
-  if (typeof foundationRef === 'string') {
-    const detected = detectFoundationType(foundationRef, siteDir)
-    if (detected.type === 'local') {
-      const receiptPath = join(detected.path, 'dist', 'publish.json')
-      if (existsSync(receiptPath)) {
-        return { mode: 'link', source: 'inferred-published-local' }
-      }
-    }
-  }
-
-  // 4. Ambiguous — local foundation never published, or unknown shape. Ask.
-  if (isNonInteractive(process.argv)) {
-    say.err('First deploy of this site needs an explicit mode.')
-    console.log('')
-    console.log('  Pick one and re-run:')
-    console.log(`    ${c.cyan}uniweb deploy --link${c.reset}    ${c.dim}Uniweb-edge hosting (data only; worker generates HTML)${c.reset}`)
-    console.log(`    ${c.cyan}uniweb deploy --bundle${c.reset}  ${c.dim}Static-host artifact (vite build; for non-Uniweb hosts)${c.reset}`)
-    console.log('')
-    console.log(`  ${c.dim}Mode is persisted after the first deploy and can't be changed in place.${c.reset}`)
-    process.exit(1)
-  }
-
-  const prompts = (await import('prompts')).default
-  console.log('')
-  console.log(`${c.dim}First deploy of this site. Pick a deployment mode:${c.reset}`)
-  const resp = await prompts({
-    type: 'select',
-    name: 'mode',
-    message: 'Deployment mode',
-    choices: [
-      { title: 'Link mode (Uniweb-edge hosting)', description: 'Data only; worker generates HTML at request time', value: 'link' },
-      { title: 'Bundle mode (static-host artifact)', description: 'vite-built; deploy to Netlify, Vercel, GitHub Pages, etc.', value: 'bundle' },
-    ],
-    initial: 0,
-  }, {
-    onCancel: () => { console.log(''); console.log('Deploy cancelled.'); process.exit(0) },
-  })
-  if (!resp.mode) process.exit(0)
-  return { mode: resp.mode, source: 'asked' }
-}
-
 // ─── Main ───────────────────────────────────────────────────
 
 export async function deploy(args = []) {
-  const skipBuild = args.includes('--skip-build')
   const dryRun = args.includes('--dry-run')
-  const skipAssets = args.includes('--skip-assets')
-  const skipBilling = args.includes('--skip-billing')
-  // --review forces the browser review path even when there's no drift.
-  // Useful for "I want to look at / change my features" without first
-  // having to edit site.yml. The toggles in the review page persist live
-  // to DB, so any change the user makes there ends up in site.yml after
-  // the loopback finalize roundtrip.
-  const forceReview = args.includes('--review')
-  // Phase 2 (deploy-ux-v4): when `foundation:` in site.yml points at a
-  // workspace-local file: ref, deploy auto-publishes the foundation when
-  // its `dist/publish.json` receipt is missing/stale. These flags opt out.
+  // When `foundation:` in site.yml points at a workspace-local file: ref,
+  // deploy auto-publishes the foundation when the registry has no record
+  // of the current source's git sha. This flag opts out.
   const autoPublishFoundation = !args.includes('--no-auto-publish')
-  const treatDirtyAsStale = !args.includes('--no-dirty-as-stale')
-  // Site mode — `--link` ships data only (Uniweb-edge hosting); `--bundle`
-  // ships a vite-built static-host artifact. Mutually exclusive. Resolution
-  // ladder runs further below: explicit flag → registry-ref / URL infer →
-  // published-local-foundation infer → ask-or-error.
-  const linkFlag = args.includes('--link')
-  const bundleFlag = args.includes('--bundle')
-  if (linkFlag && bundleFlag) {
-    say.err('Cannot pass both --link and --bundle.')
-    process.exit(1)
-  }
+
+  // Internal escape hatches — see framework/cli/docs/env-vars.md. These
+  // are not user-facing flags; they exist for the platform test team,
+  // CI scripts, and dev-loop unblockers. The bare `deploy` command should
+  // do the right thing for normal users without any of them set.
+  const skipBuild = parseBoolEnv('UNIWEB_SKIP_BUILD')
+  const skipAssets = parseBoolEnv('UNIWEB_SKIP_ASSETS')
+  const skipBilling = parseBoolEnv('UNIWEB_SKIP_BILLING')
+  const forceReview = parseBoolEnv('UNIWEB_FORCE_REVIEW')
+  // Inverse of the (now-removed) --no-dirty-as-stale flag. When true, a
+  // dirty workspace will NOT be treated as stale (won't trigger auto-publish
+  // of the foundation). Default: dirty IS stale.
+  const treatDirtyAsStale = !parseBoolEnv('UNIWEB_ALLOW_DIRTY_FOUNDATION')
 
   const siteDir = await resolveSiteDir(args)
   const backendUrl = getBackendUrl()
@@ -560,6 +416,22 @@ export async function deploy(args = []) {
   // site.id / site.handle from prior deploys.
   const siteYmlPath = join(siteDir, 'site.yml')
   const siteYml = await readSiteYml(siteYmlPath)
+
+  // Host dispatch. The default host is `uniweb` — Uniweb hosting
+  // (link-mode + edge JIT prerender), which is the rest of this
+  // function. Any other named host is a static-host adapter; hand off
+  // to it and return. The default flow requires a `foundation:`
+  // declaration; static-host deploys don't, so this branch comes BEFORE
+  // the foundation check.
+  // See kb/framework/plans/static-host-deploy-adapters.md.
+  const hostFlagIndex = args.indexOf('--host')
+  const hostFromFlag = hostFlagIndex !== -1 ? args[hostFlagIndex + 1] : null
+  const host = hostFromFlag || siteYml.deploy?.host || 'uniweb'
+  if (host !== 'uniweb') {
+    await deployStaticHost(siteDir, siteYml, host, { dryRun })
+    return
+  }
+
   if (!siteYml.foundation) {
     say.err('site.yml is missing `foundation`.')
     say.dim('Add a line like:  foundation: \'@uniweb/docs-foundation@0.1.20\'')
@@ -583,29 +455,29 @@ export async function deploy(args = []) {
     say.dim('Foundation policy: exact (pinned)')
   }
 
-  // Resolve deploy mode (link vs bundle) BEFORE the foundation
-  // staleness check, because mode selection feeds into how we run
-  // the site build later. The resolver may prompt the user on first
-  // deploy; subsequent deploys infer or use the explicit flag.
-  // TODO: when PHP authorize starts returning a persisted mode for
-  // this site, reconcile it with the resolved mode here and reject
-  // any mismatch ("delete site and redeploy fresh to change modes").
-  const { mode: deployMode, source: modeSource } = await resolveDeployMode({
-    foundationRef: foundation,
-    siteDir,
-    linkFlag,
-    bundleFlag,
-  })
-  if (modeSource === 'inferred-registry-ref') {
-    say.dim('Deploy mode: link (inferred — foundation is a registry ref)')
-  } else if (modeSource === 'inferred-published-local') {
-    say.dim('Deploy mode: link (inferred — local foundation has a publish receipt)')
-  } else if (modeSource === 'asked') {
-    say.dim(`Deploy mode: ${deployMode} (selected)`)
-  } else {
-    say.dim(`Deploy mode: ${deployMode}`)
+  // --dry-run gate. Must come BEFORE auto-publish (which writes to the
+  // registry) and BEFORE the site build (which writes to dist/). Earlier
+  // versions of this command had the dry-run check after both, which
+  // violated the contract that --dry-run performs zero writes. Languages
+  // and the default locale are unavailable here (they live in
+  // dist/site-content.json, which a dry-run won't build); the trade-off
+  // is intentional. Run `uniweb build` directly if you need that detail.
+  if (dryRun) {
+    say.info('Dry run — would deploy:')
+    say.dim(`Site dir       : ${siteDir}`)
+    say.dim(`site.id        : ${siteYml.site?.id || '(none — would use create flow)'}`)
+    say.dim(`Foundation     : ${typeof foundation === 'string' ? foundation : foundation.ref}`)
+    say.dim(`Runtime        : ${siteYml.runtime || '(latest, resolved at authorize)'}`)
+    say.dim(`Backend (PHP)  : ${backendUrl}`)
+    say.dim(`Worker         : ${workerUrl}`)
+    return
   }
 
+  // `uniweb deploy` always runtime-links: the edge serves a runtime
+  // template + per-site base.html, with the foundation loaded by URL.
+  // The historical --link / --bundle flags are gone (Phase 2 of the CLI
+  // ergonomics overhaul). For static-host artifacts, see `uniweb export`.
+
   // Phase 2: resolve workspace-local `file:` foundation refs.
   //
   // The object form of `foundation:` already requires a registry ref
@@ -616,69 +488,59 @@ export async function deploy(args = []) {
   // build runs in runtime mode against the just-published artifact instead
   // of bundling the local foundation source. site.yml on disk is never
   // modified.
-  let foundationBuildOverride = null
+  // Phase 4d: detect a workspace-local foundation. The actual upload happens
+  // AFTER authorize (which mints siteId), so the canonical site-bound ref
+  // `~{siteId}/{name}@{ver}` is known by the time we publish. For now we
+  // just record what we'll need at upload time and pass a `~self/...`
+  // placeholder to authorize — the server rewrites it.
+  let localFoundation = null
   if (typeof foundation === 'string') {
     const detected = detectFoundationType(foundation, siteDir)
     if (detected.type === 'local') {
       const localPath = detected.path
       const relPath = relative(siteDir, localPath) || localPath
 
-      // Pass a RemoteRegistry into the inspector so it can refill a missing
-      // `dist/publish.json` from the registry's index (fresh-clone case).
-      // No auth needed — `getVersionEntry` reads the public listing.
-      const refillRegistry = new RemoteRegistry(workerUrl)
-      const inspection = await inspectLocalFoundationReceipt(localPath, {
-        dirtyAsStale: treatDirtyAsStale,
-        registry: refillRegistry,
-      })
-      if (inspection.refilled) {
-        say.dim(`Foundation receipt at ${relPath} refilled from registry.`)
-      }
-
-      if (inspection.stale && !autoPublishFoundation) {
-        say.err(`Local foundation at ${relPath} is stale: ${inspection.reason}.`)
-        say.dim(`Run \`${getCliPrefix()} publish\` from ${relPath}, or drop --no-auto-publish to let deploy publish it for you.`)
+      let pkg
+      try {
+        pkg = JSON.parse(await readFile(join(localPath, 'package.json'), 'utf8'))
+      } catch {
+        say.err(`Could not read ${relPath}/package.json.`)
         process.exit(1)
       }
-      if (inspection.stale) {
-        say.info(`Foundation at ${relPath} is stale (${inspection.reason}). Auto-publishing…`)
-        console.log('')
-        try {
-          // Spawn the SAME CLI binary that's currently running, not via
-          // `npx uniweb` — npx resolves through node_modules and could
-          // pick up a stale npm-published version that doesn't share
-          // this CLI's behavior (e.g. doesn't recognize new flags).
-          // Using `process.argv[1]` keeps the outer/inner CLI version
-          // identical, eliminating the skew.
-          execSync(`node ${JSON.stringify(process.argv[1])} publish`, {
-            cwd: localPath,
-            stdio: 'inherit',
-          })
-        } catch {
-          say.err(`Auto-publish of foundation at ${relPath} failed. See output above.`)
-          process.exit(1)
-        }
-        console.log('')
+      const foundationName = pkg.uniweb?.id || pkg.name?.replace(/^[@~][^/]+\//, '') || pkg.name
+      const foundationVersion = pkg.version
+      if (!foundationName || !foundationVersion) {
+        say.err(`Foundation at ${relPath} needs both a name and a version in package.json.`)
+        process.exit(1)
       }
 
-      const resolved = await deriveLocalFoundationRef(localPath)
-      if (!resolved) {
-        say.err(`Could not derive a registry ref for foundation at ${relPath}.`)
-        say.dim(`Make sure its package.json has a name + version and a namespace (uniweb.namespace, scoped name, or run \`uniweb publish --namespace <handle>\` once).`)
-        process.exit(1)
+      localFoundation = {
+        path: localPath,
+        relPath,
+        name: foundationName,
+        version: foundationVersion,
       }
-      say.dim(`Foundation: ${foundation} → ${resolved} (resolved from ${relPath})`)
-      foundation = resolved
-      foundationBuildOverride = resolved
+
+      // Send `~self/{name}@{ver}` as a placeholder. The server will rewrite
+      // to `~{siteId}/{name}@{ver}` once siteId is minted. The CLI uses the
+      // returned canonical ref for both the upload and the publish payload.
+      foundation = `~self/${foundationName}@${foundationVersion}`
     }
   }
+  // Honor --no-auto-publish for local foundations: surface the gate before
+  // we do any work.
+  if (localFoundation && !autoPublishFoundation) {
+    say.err(`Local foundation at ${localFoundation.relPath} would be auto-published as part of deploy.`)
+    say.dim('Drop --no-auto-publish to let deploy publish it, or change site.yml to reference a registry-published foundation.')
+    process.exit(1)
+  }
 
   // Runtime defaults to "latest" resolved at authorize time.
   let runtimeVersion = siteYml.runtime
   if (!runtimeVersion) {
     runtimeVersion = await fetchLatestRuntime(workerUrl)
     if (!runtimeVersion) {
-      say.err('Could not resolve a runtime version (no runtime: in site.yml, /api/runtime/latest failed).')
+      say.err('Could not resolve a runtime version (no runtime: in site.yml, /runtime/latest failed).')
       process.exit(1)
     }
     say.dim(`Runtime: ${runtimeVersion} (latest; pin via \`runtime:\` in site.yml)`)
@@ -705,32 +567,29 @@ export async function deploy(args = []) {
     // detectFoundationType recognizes `@ns/name@version` refs as
     // link-mode URLs, which auto-enters runtime mode. Prerender also
     // auto-skips for link-mode foundations (HTML is rendered on the
-    // serving edge, not here).
+    // serving edge, not here). Always --link: the edge serves a runtime
+    // template + per-site base.html, never a self-contained vite bundle.
     //
-    // For workspace-local foundations (Phase 2 resolution above),
-    // UNIWEB_FOUNDATION_REF tells defineSiteConfig to use the resolved
-    // registry ref instead of site.yml's literal value. In bundle mode
-    // the build produces a runtime-mode bundle pointing at the just-
-    // published foundation rather than embedding the local source.
-    // Link mode doesn't run vite at all, so the env var is harmless
-    // there but still passed through for consistency.
+    // Phase 4d: workspace-local foundations carry the `~self/{name}@{ver}`
+    // placeholder at this point; the canonical `~{siteId}/...` ref isn't
+    // known until authorize returns. Link mode doesn't run vite or fetch
+    // the foundation, so site-content.json's foundation field reflects
+    // whatever's in site.yml — that's fine because the publish payload
+    // overrides it with the canonical form post-authorize.
     //
     // Spawn the SAME CLI binary that's currently running rather than
     // `npx uniweb build` — npx walks node_modules and would resolve to
     // whatever version is installed there (which might be older than
     // the deploy CLI and silently ignore --link). `process.argv[1]`
     // pins the inner build to the outer's exact version.
-    const buildModeFlag = deployMode === 'link' ? '--link' : '--bundle'
-    execSync(`node ${JSON.stringify(process.argv[1])} build ${buildModeFlag}`, {
+    execSync(`node ${JSON.stringify(process.argv[1])} build --link`, {
       cwd: siteDir,
       stdio: 'inherit',
-      env: foundationBuildOverride
-        ? { ...process.env, UNIWEB_FOUNDATION_REF: foundationBuildOverride }
-        : process.env,
+      env: process.env,
     })
     console.log('')
   } else if (!existsSync(contentPath)) {
-    say.err('No build found and --skip-build passed. Run `uniweb build` first.')
+    say.err('No build found and UNIWEB_SKIP_BUILD set. Run `uniweb build` first.')
     process.exit(1)
   }
   if (!existsSync(contentPath)) {
@@ -762,25 +621,13 @@ export async function deploy(args = []) {
     }
   }
 
-  if (dryRun) {
-    say.info('Dry run — showing what would be deployed:')
-    say.dim(`Site dir       : ${siteDir}`)
-    say.dim(`site.id        : ${siteYml.site?.id || '(none — would use create flow)'}`)
-    say.dim(`Foundation     : ${typeof foundation === 'string' ? foundation : foundation.ref}`)
-    say.dim(`Runtime        : ${runtimeVersion}`)
-    say.dim(`Languages      : ${languages.join(', ')}`)
-    say.dim(`Default locale : ${defaultLanguage}`)
-    say.dim(`Backend (PHP)  : ${backendUrl}`)
-    say.dim(`Worker         : ${workerUrl}`)
-    return
-  }
-
   // Spin up the loopback listener eagerly — we need its callback URL for the
   // authorize request even on the fast path (PHP may always return
   // needsReview=true on first deploy / billing drift in future phases).
   const loopback = await startLoopback()
 
   let publishToken, siteIdResolved, handleResolved, publishUrl, validateUrl, mintedFeatures
+  let foundationUploadUrl  // Phase 4d: returned by authorize for site-bound foundation uploads
   try {
     say.info('Requesting deploy authorization…')
     const authorizeBody = {
@@ -805,16 +652,9 @@ export async function deploy(args = []) {
       // Always sent as an array; missing/empty `features:` in site.yml
       // is normalized to `[]`, meaning "no paid features".
       desiredFeatures,
-      // User-forced review (`uniweb deploy --review`). PHP refuses to
+      // User-forced review (UNIWEB_FORCE_REVIEW=1). PHP refuses to
       // fast-path even when nothing else has drifted.
       forceReview: forceReview || undefined,
-      // Deploy mode for this site. On first deploy PHP should persist
-      // it to the site row; on subsequent deploys PHP should return the
-      // persisted value back so the CLI can detect mode mismatches and
-      // refuse with "delete and redeploy fresh" rather than silently
-      // reshape the storage layout. PHP versions that pre-date mode
-      // persistence ignore this field — back-compat is built in.
-      mode: deployMode,
     }
     let authRes
     try {
@@ -829,27 +669,18 @@ export async function deploy(args = []) {
         say.dim('Treating as a new site — the create flow will run in your browser.')
         authorizeBody.siteId = ''
         authRes = await callAuthorize({ backendUrl, cliToken, body: authorizeBody })
+      } else if (err.status === 403 && authorizeBody.siteId) {
+        // Collaborator ACL — the user has the repo (and thus site.id in
+        // site.yml) but isn't owner or editor on this site. The server's
+        // 403 message names the owner; surface it verbatim.
+        say.err(err.message)
+        process.exit(1)
       } else {
         say.err(`Authorize failed: ${err.message}`)
         process.exit(1)
       }
     }
 
-    // Mode lock — once a site has a persisted mode on the server,
-    // deploying with a different mode would silently reshape its R2
-    // storage layout. Refuse and direct the user to start fresh.
-    // Until PHP starts returning `persistedMode`, this check is a
-    // no-op (forward-compatible).
-    if (authRes.persistedMode && authRes.persistedMode !== deployMode) {
-      say.err(`Deploy mode mismatch: this site is configured for ${authRes.persistedMode}, but this deploy resolved to ${deployMode}.`)
-      console.log('')
-      console.log(`  ${c.dim}Mode is locked after the first deploy. To switch:${c.reset}`)
-      console.log(`    1. Delete the site (manage.uniweb.app or the dashboard)`)
-      console.log(`    2. Remove ${c.cyan}site.id${c.reset} and ${c.cyan}site.handle${c.reset} from site.yml`)
-      console.log(`    3. Re-run ${c.cyan}uniweb deploy --${deployMode}${c.reset}`)
-      process.exit(1)
-    }
-
     if (authRes.needsReview) {
       const flowLabel = authRes.intent === 'create' ? 'site creation' : 'review'
       // openBrowser returns a hint about whether a GUI was available. On
@@ -889,16 +720,29 @@ export async function deploy(args = []) {
       // CLI can write `features:` back into site.yml accurately. Older
       // PHP that doesn't include this field is a no-op.
       mintedFeatures = Array.isArray(cb.features) ? cb.features : null
+      // Phase 4d: workspace-local foundation deploys on the create flow
+      // need the rewritten `~{siteId}/{name}@{ver}` ref + upload endpoint.
+      // PHP/unicloud put them in the finalize response; the web app
+      // forwards them to the loopback. Catalog-ref deploys leave them
+      // undefined and we fall back to the placeholder/derived URL below.
+      if (cb.foundationRef) foundation = cb.foundationRef
+      if (cb.foundationUploadUrl) foundationUploadUrl = cb.foundationUploadUrl
       // Review path: Worker URLs are implicit (we derive them from config).
-      publishUrl = `${workerUrl}/api/publish/process`
-      validateUrl = `${workerUrl}/api/publish/validate`
+      publishUrl = `${workerUrl}/publish`
+      validateUrl = `${workerUrl}/publish/check`
     } else {
       publishToken = authRes.publishToken
       siteIdResolved = authRes.siteId
       handleResolved = authRes.handle
       publishUrl = authRes.publishUrl
       validateUrl = authRes.validateUrl
+      foundationUploadUrl = authRes.foundationUploadUrl
       mintedFeatures = Array.isArray(authRes.features) ? authRes.features : null
+      // Phase 4d: server returns the canonical foundation ref. For
+      // `~self/...` placeholders this is the rewritten `~{siteId}/...`
+      // form; catalog refs pass through. The CLI uses this for both the
+      // foundation upload (next step) and the publish payload below.
+      if (authRes.foundationRef) foundation = authRes.foundationRef
     }
   } finally {
     loopback.close()
@@ -918,6 +762,45 @@ export async function deploy(args = []) {
     say.dim(`Linked site.yml to site.id=${siteIdResolved}`)
   }
 
+  // Phase 4d: upload site-bound foundation files directly. Replaces the
+  // pre-Phase-4d `execSync('uniweb publish')` flow — we now know the
+  // canonical `~{siteId}/{name}@{ver}` ref from authorize, and the worker's
+  // /foundations endpoint accepts the publish token's siteId claim
+  // for this scope.
+  if (localFoundation) {
+    say.info(`Building foundation at ${localFoundation.relPath}…`)
+    console.log('')
+    try {
+      execSync(`node ${JSON.stringify(process.argv[1])} build`, {
+        cwd: localFoundation.path,
+        stdio: 'inherit',
+      })
+    } catch {
+      say.err(`Foundation build at ${localFoundation.relPath} failed. See output above.`)
+      process.exit(1)
+    }
+    console.log('')
+
+    say.info(`Uploading foundation as ${foundation}…`)
+    const foundationFiles = await collectFoundationDistFiles(join(localFoundation.path, 'dist'))
+    const foundationPublishUrl = foundationUploadUrl || `${workerUrl}/foundations`
+    const { gitSha: fGitSha, gitDirty: fGitDirty } = readGitState(localFoundation.path)
+    await callFoundationUpload({
+      url: foundationPublishUrl,
+      token: publishToken,
+      body: {
+        name: foundation.replace(/@[^@]+$/, ''),  // strip `@version` to get `~{siteId}/{name}`
+        version: localFoundation.version,
+        files: foundationFiles,
+        metadata: {
+          ...(fGitSha ? { publishedFromGitSha: fGitSha } : {}),
+          ...(typeof fGitDirty === 'boolean' ? { publishedFromGitDirty: fGitDirty } : {}),
+        },
+      },
+    })
+    say.ok(`Foundation uploaded.`)
+  }
+
   // Pre-flight against the Worker. Surfaces "foundation not published" /
   // "runtime not found" / namespace mismatch BEFORE we ship content.
   say.info('Validating foundation + runtime…')
@@ -935,36 +818,60 @@ export async function deploy(args = []) {
     process.exit(1)
   }
 
-  // Asset pipeline — upload dist/assets/* + favicon + fonts to S3, then
-  // rewrite each locale's siteContent so semantic-parser resolves CDN URLs
-  // at render time. Assets themselves are locale-shared (they live in
-  // dist/assets/ regardless of language), so the diff/upload runs once
-  // and the rewrite walks every locale's content tree in localeContents.
+  // Collect compiled collection JSON files from dist/data/. The framework
+  // emits these for `collection:` data sources — `<name>.json` cascade
+  // payloads plus per-record `<name>/<slug>.json` files when `deferred:` is
+  // declared. Editor publish has no equivalent (collections live in the DB);
+  // CLI sites need them shipped as static R2 objects.
+  //
+  // Read BEFORE the asset pipeline so the asset scan can pick up image
+  // refs in collection JSON (e.g. `article.image: "/covers/foo.svg"`)
+  // and the rewrite can swap them for CDN URLs alongside locale content.
+  const dataFiles = await collectDataFiles(distDir)
+  // Decode each data file as JSON so the asset scan can walk the tree;
+  // mutated in place by the rewrite step. Re-stringified before publish.
+  const dataFileObjects = {}
+  for (const [k, raw] of Object.entries(dataFiles)) {
+    try {
+      dataFileObjects[k] = JSON.parse(raw)
+    } catch {
+      dataFileObjects[k] = null // unparseable — skip rewrite, ship as-is
+    }
+  }
+  if (Object.keys(dataFiles).length > 0) {
+    say.dim(`Data files     : ${Object.keys(dataFiles).length} (collection JSON)`)
+  }
+
+  // Asset pipeline — upload dist/assets/* + favicon + fonts + content-scan
+  // hits (public/, data file refs) to S3, then rewrite each locale's
+  // siteContent + each parsed data file so the runtime resolves CDN URLs at
+  // render time. Assets are locale-shared (they live in dist/assets/ +
+  // public/ regardless of language); diff/upload runs once and the rewrite
+  // walks every locale's content tree + every data-file JSON tree.
   // Skipped with --skip-assets.
   if (!skipAssets) {
     await uploadAssetsAndRewriteContent({
       siteDir,
       localeContents,
+      dataFileObjects,
       siteYml,
       theme,
       backendUrl,
       cliToken,
       siteId: siteIdResolved,
     })
+    // Re-stringify any data-file JSON that the rewrite step mutated, so the
+    // publish payload below sees the rewritten URLs. Untouched files round-
+    // trip identically.
+    for (const k of Object.keys(dataFiles)) {
+      if (dataFileObjects[k] !== null) {
+        dataFiles[k] = JSON.stringify(dataFileObjects[k])
+      }
+    }
   } else {
     say.dim('Skipping asset upload (--skip-assets).')
   }
 
-  // Collect compiled collection JSON files from dist/data/. The framework
-  // emits these for `collection:` data sources — `<name>.json` cascade
-  // payloads plus per-record `<name>/<slug>.json` files when `deferred:` is
-  // declared. Editor publish has no equivalent (collections live in the DB);
-  // CLI sites need them shipped as static R2 objects.
-  const dataFiles = await collectDataFiles(distDir)
-  if (Object.keys(dataFiles).length > 0) {
-    say.dim(`Data files     : ${Object.keys(dataFiles).length} (collection JSON)`)
-  }
-
   say.info('Publishing…')
   const publishPayload = {
     foundation,
@@ -1039,6 +946,107 @@ export async function deploy(args = []) {
   }
 }
 
+// ─── Static-host deploy (S3+CloudFront, etc.) ─────────────────
+//
+// Distinct from the uniweb-edge flow above. Picked when site.yml's
+// `deploy.host` (or --host flag) names a static-host adapter
+// registered in @uniweb/build/hosts. Always runs `uniweb build`
+// (bundle mode + prerender) first, then hands dist/ to the adapter's
+// deploy hook for upload + invalidation.
+//
+// See kb/framework/plans/static-host-deploy-adapters.md.
+
+async function deployStaticHost(siteDir, siteYml, hostName, { dryRun }) {
+  let getAdapter
+  try {
+    ({ getAdapter } = await import('@uniweb/build/hosts'))
+  } catch (err) {
+    say.err('Failed to load host adapter registry from @uniweb/build/hosts.')
+    say.dim(err.message)
+    process.exit(1)
+  }
+
+  let adapter
+  try {
+    adapter = getAdapter(hostName)
+  } catch (err) {
+    say.err(err.message)
+    say.dim(`Set deploy.host in site.yml or pass --host=<name>. See \`uniweb deploy --help\`.`)
+    process.exit(1)
+  }
+
+  if (typeof adapter.deploy !== 'function') {
+    say.err(`Host adapter '${hostName}' does not implement a deploy step.`)
+    say.dim(`Build with \`uniweb build --host=${hostName}\` and upload \`dist/\` manually,`)
+    say.dim(`or use a host whose adapter ships a deploy hook (e.g., s3-cloudfront).`)
+    process.exit(1)
+  }
+
+  const deployConfig = siteYml.deploy || {}
+  const distDir = join(siteDir, 'dist')
+
+  if (dryRun) {
+    say.info(`Dry run — would deploy via host adapter: ${c.bold}${adapter.name}${c.reset}`)
+    say.dim(`Site dir       : ${siteDir}`)
+    say.dim(`dist/          : ${existsSync(distDir) ? 'exists (would not rebuild)' : 'missing (would build)'}`)
+    say.dim(`deploy.bucket  : ${deployConfig.bucket || '(unset)'}`)
+    say.dim(`deploy.distId  : ${deployConfig.distributionId || '(unset)'}`)
+    say.dim(`deploy.region  : ${deployConfig.region || '(unset)'}`)
+    say.dim(`deploy.profile : ${deployConfig.profile || '(default AWS chain)'}`)
+    return
+  }
+
+  // Always rebuild — the static-host flow expects fresh dist/ on every
+  // deploy. UNIWEB_SKIP_BUILD env var lets CI / dev loops reuse an
+  // existing build (mirrors the uniweb-edge flow's escape hatch).
+  const skipBuild = parseBoolEnv('UNIWEB_SKIP_BUILD')
+  if (skipBuild) {
+    if (!existsSync(distDir)) {
+      say.err('UNIWEB_SKIP_BUILD is set but dist/ does not exist.')
+      process.exit(1)
+    }
+    say.info('UNIWEB_SKIP_BUILD set — reusing existing dist/.')
+  } else {
+    say.info(`Building site (host: ${adapter.name})…`)
+    console.log('')
+    try {
+      execSync(
+        `node ${JSON.stringify(process.argv[1])} build --bundle --host ${JSON.stringify(adapter.name)}`,
+        { cwd: siteDir, stdio: 'inherit' }
+      )
+    } catch {
+      say.err('Build failed. See output above.')
+      process.exit(1)
+    }
+    if (!existsSync(distDir)) {
+      say.err('Build did not produce dist/.')
+      process.exit(1)
+    }
+    console.log('')
+  }
+
+  // Hand off to the adapter. DeployError is the structured shape from
+  // @uniweb/build/hosts/s3-cloudfront — translate to user-facing output.
+  try {
+    await adapter.deploy({
+      distDir,
+      deployConfig,
+      env: process.env,
+      log: (m) => console.log(m),
+    })
+  } catch (err) {
+    if (err && err.name === 'DeployError') {
+      say.err(err.message)
+      if (err.hint) {
+        console.log('')
+        console.log(err.hint)
+      }
+      process.exit(1)
+    }
+    throw err
+  }
+}
+
 // ─── site.yml ──────────────────────────────────────────────
 
 async function readSiteYml(path) {
@@ -1115,7 +1123,11 @@ async function writeSiteYmlUpdates(path, current, updates) {
 
 // ─── Resolve site dir + runtime ────────────────────────────
 
-async function resolveSiteDir(args) {
+// Exported so `uniweb export` (commands/export.js) can reuse the same
+// site-discovery logic without duplicating it. `verb` is the command
+// being run ("deploy" or "export"); it appears in the error messages
+// so the user gets accurate guidance.
+export async function resolveSiteDir(args, verb = 'deploy') {
   const cwd = process.cwd()
   const prefix = getCliPrefix()
 
@@ -1128,16 +1140,16 @@ async function resolveSiteDir(args) {
     if (sites.length === 1) return resolve(workspaceRoot, sites[0])
     if (sites.length > 1) {
       if (isNonInteractive(args)) {
-        say.err('Multiple sites found. Specify which one to deploy.')
+        say.err(`Multiple sites found. Specify which one to ${verb}.`)
         console.log('')
         for (const s of sites) {
-          console.log(`  ${c.cyan}cd ${s} && ${prefix} deploy${c.reset}`)
+          console.log(`  ${c.cyan}cd ${s} && ${prefix} ${verb}${c.reset}`)
         }
         process.exit(1)
       }
       const choice = await promptSelect('Which site?', sites)
       if (!choice) {
-        console.log('\nDeploy cancelled.')
+        console.log(`\n${verb.charAt(0).toUpperCase() + verb.slice(1)} cancelled.`)
         process.exit(0)
       }
       return resolve(workspaceRoot, choice)
@@ -1145,13 +1157,17 @@ async function resolveSiteDir(args) {
   }
 
   say.err('No site found in this workspace.')
-  say.dim('`deploy` publishes a built Uniweb site to the hosting platform.')
+  if (verb === 'export') {
+    say.dim('`export` produces a self-contained dist/ artifact for third-party hosting.')
+  } else {
+    say.dim('`deploy` publishes a built Uniweb site to the hosting platform.')
+  }
   process.exit(1)
 }
 
 async function fetchLatestRuntime(workerUrl) {
   try {
-    const res = await fetch(`${workerUrl}/api/runtime/latest`)
+    const res = await fetch(`${workerUrl}/runtime/latest`)
     if (!res.ok) return null
     const body = await res.json()
     return body.version || null
@@ -1307,6 +1323,50 @@ async function callPublish({ url, token, body }) {
   return res.json()
 }
 
+// ─── Site-bound foundation upload (Phase 4d) ────────────────
+
+/**
+ * Walk a built foundation's `dist/` directory and return `{ relPath: base64Bytes }`
+ * — the shape `POST /foundations` expects in its `files` field.
+ */
+async function collectFoundationDistFiles(distDir) {
+  if (!existsSync(distDir)) {
+    say.err(`Foundation dist/ not found at ${distDir}.`)
+    process.exit(1)
+  }
+  const files = {}
+  const entries = await readdir(distDir, { withFileTypes: true, recursive: true })
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const fullPath = join(entry.parentPath, entry.name)
+    const relPath = relative(distDir, fullPath).split(sep).join('/')
+    const bytes = await readFile(fullPath)
+    files[relPath] = bytes.toString('base64')
+  }
+  return files
+}
+
+async function callFoundationUpload({ url, token, body }) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) {
+    let err = `HTTP ${res.status}`
+    try {
+      const j = await res.json()
+      err = j.error || err
+    } catch {}
+    say.err(`Foundation upload failed: ${err}`)
+    process.exit(1)
+  }
+  return res.json()
+}
+
 // ─── Asset pipeline (Phase 4) ──────────────────────────────
 
 /**
@@ -1318,13 +1378,37 @@ async function callPublish({ url, token, body }) {
  * siteContent is mutated in place so the caller's publish payload picks up
  * the rewritten nodes without passing anything back.
  */
-async function uploadAssetsAndRewriteContent({ siteDir, localeContents, siteYml, theme, backendUrl, cliToken, siteId }) {
+async function uploadAssetsAndRewriteContent({ siteDir, localeContents, dataFileObjects = {}, siteYml, theme, backendUrl, cliToken, siteId }) {
   const distAssetsDir = join(siteDir, 'dist', 'assets')
   const hasDistAssets = existsSync(distAssetsDir)
 
   // 1. Enumerate local files + read size.
   const localFiles = hasDistAssets ? await walkAssetDir(distAssetsDir) : []
 
+  // 1a. Content-scan: walk site-content.json (and locale variants) for any
+  //     asset references (image/document src/href) and resolve absolute
+  //     paths to local files under `dist/` or `public/`. This catches static
+  //     assets the author placed in `public/covers/`, `public/images/`, etc.
+  //     that the dist/assets walk above misses (vite's image-pipeline only
+  //     produces files for refs that go through it). Each resolved file
+  //     joins the upload pipeline; the rewrite step at the end maps every
+  //     such reference to its CDN identifier so content stays portable
+  //     across site delete / template extraction.
+  const contentRefMap = await scanContentForAssetRefs(localeContents, dataFileObjects, siteDir)
+  const seenPaths = new Set(localFiles.map((f) => f.fullPath))
+  for (const [, info] of contentRefMap) {
+    if (seenPaths.has(info.resolvedPath)) continue
+    const ext = (info.filename.split('.').pop() || '').toLowerCase()
+    const st = await stat(info.resolvedPath)
+    localFiles.push({
+      filename: info.filename,
+      fullPath: info.resolvedPath,
+      size: st.size,
+      mime: MIME_BY_EXT[ext] || 'application/octet-stream',
+    })
+    seenPaths.add(info.resolvedPath)
+  }
+
   // 1a. Favicon — sits at site root, not in dist/assets. Ship it through
   //     the same pipeline so it ends up at assets.uniweb.app with an
   //     identifier; config.favicon gets set further down.
@@ -1444,14 +1528,39 @@ async function uploadAssetsAndRewriteContent({ siteDir, localeContents, siteYml,
   }
 
   // 6. Rewrite each locale's content in place. Image/document nodes whose
-  //    src/href references a local /assets/{filename} get an info.identifier
-  //    pointing to the uploaded (or reused) asset. Walking every locale
-  //    means translated content (which still references the same image
-  //    files via the source ProseMirror tree) gets the same rewrite.
+  //    src/href references an uploaded asset get an info.identifier pointing
+  //    to the CDN. Walking every locale means translated content (which
+  //    still references the same image files via the source ProseMirror
+  //    tree) gets the same rewrite.
+  //
+  //    Two lookup paths:
+  //      - byOriginalRef: full src/href string → identifier (covers static
+  //        public/ assets like `/covers/foo.svg` and dist/-resolved refs)
+  //      - byFilename: legacy match for `assets/{filename}` shape — kept
+  //        for back-compat with content authored against the old vite-
+  //        produced `/assets/...` URLs.
   const byFilenameAll = new Map([...reused, ...fresh])
+  const byOriginalRef = new Map()
+  for (const [ref, info] of contentRefMap) {
+    const id = byFilenameAll.get(info.filename)
+    if (id) byOriginalRef.set(ref, id)
+  }
   let rewritten = 0
   for (const lang of Object.keys(localeContents)) {
-    rewritten += rewriteAssetReferences(localeContents[lang], byFilenameAll)
+    rewritten += rewriteAssetReferences(localeContents[lang], byFilenameAll, byOriginalRef)
+  }
+  // Data files: walk the JSON tree. Two patterns coexist in collection
+  // payloads:
+  //   - Flat fields (e.g. `article.image: "/covers/foo.svg"`) → replace
+  //     the string with a resolveAssetCdnUrl(identifier). The runtime
+  //     reads these as plain URLs, so rewriting at deploy time is the
+  //     simplest path to portability.
+  //   - Nested ProseMirror sub-trees (e.g. `article.content`) → use the
+  //     existing image/document node rewrite (sets `attrs.info.identifier`).
+  for (const k of Object.keys(dataFileObjects)) {
+    if (dataFileObjects[k] === null) continue
+    rewritten += rewriteFlatAssetUrls(dataFileObjects[k], byOriginalRef)
+    rewritten += rewriteAssetReferences(dataFileObjects[k], byFilenameAll, byOriginalRef)
   }
   if (rewritten > 0) {
     say.dim(`Rewrote ${rewritten} asset reference(s) across ${Object.keys(localeContents).length} locale(s).`)
@@ -1725,44 +1834,68 @@ async function runInPool(items, concurrency, worker) {
 
 /**
  * Walk siteContent (ProseMirror-ish JSON tree) and rewrite any node whose
- * `attrs.src` or `attrs.href` references a local `/assets/{filename}` that
- * we've uploaded/reused. Sets `attrs.info.identifier` so semantic-parser
- * resolves the real CDN URL (and optimized variants) at render time.
+ * `attrs.src` or `attrs.href` references an uploaded/reused asset. Sets
+ * `attrs.info.identifier` so semantic-parser resolves the real CDN URL
+ * (and optimized variants) at render time.
+ *
+ * Two lookup paths, in order:
+ *   1. `byOriginalRef` — full src/href string → identifier. Covers static
+ *      public/ assets (`/covers/foo.svg`, `/images/foo.png`) and any
+ *      content-scan-resolved file. Decouples assets from site lifecycle
+ *      (templates can extract content + identifier; assets stay on CDN).
+ *   2. `byFilename` (legacy) — only fires when the path matches the old
+ *      `/assets/{filename}` shape. Kept so re-deploys of content authored
+ *      against pre-content-scan CLIs still work.
  *
  * Returns the number of rewrites performed — useful for reporting, and to
  * detect "nothing matched" (likely a content-shape mismatch worth flagging).
  */
-function rewriteAssetReferences(node, byFilename) {
+function rewriteAssetReferences(node, byFilename, byOriginalRef = new Map()) {
   let count = 0
   const walk = (n) => {
     if (!n || typeof n !== 'object') return
     if (Array.isArray(n)) { for (const child of n) walk(child); return }
     if (n.attrs && typeof n.attrs === 'object') {
-      const srcRef = pickAssetRef(n.attrs.src)
-      const hrefRef = pickAssetRef(n.attrs.href)
-      const ref = srcRef || hrefRef
-      if (ref) {
-        const identifier = byFilename.get(ref)
-        if (identifier) {
-          n.attrs.info = {
-            ...(n.attrs.info || {}),
-            identifier,
-            contentType: 'website',
-            viewType: 'profile',
-          }
-          // Clear the local Vite-hashed path so the runtime resolves via
-          // info.identifier (→ assets.uniweb.app CDN) instead of requesting
-          // a non-existent /assets/... file from the site host.
-          if (srcRef) n.attrs.src = null
-          if (hrefRef) n.attrs.href = null
-          // Match the Editor shape: plain `image` nodes skip identifier
-          // resolution in older runtimes; `ImageBlock` routes through
-          // parseImgBlock which reads info.identifier and fills url.
-          if (n.type === 'image' && n.attrs.role !== 'icon') {
-            n.type = 'ImageBlock'
-          }
-          count++
+      // Prefer full-ref lookup (covers static + dist refs uniformly);
+      // fall back to legacy `assets/{filename}` extraction.
+      let identifier = null
+      let srcMatched = false
+      let hrefMatched = false
+      if (typeof n.attrs.src === 'string' && byOriginalRef.has(n.attrs.src)) {
+        identifier = byOriginalRef.get(n.attrs.src)
+        srcMatched = true
+      } else if (typeof n.attrs.href === 'string' && byOriginalRef.has(n.attrs.href)) {
+        identifier = byOriginalRef.get(n.attrs.href)
+        hrefMatched = true
+      } else {
+        const srcRef = pickAssetRef(n.attrs.src)
+        const hrefRef = pickAssetRef(n.attrs.href)
+        const ref = srcRef || hrefRef
+        if (ref) {
+          identifier = byFilename.get(ref) || null
+          srcMatched = !!srcRef
+          hrefMatched = !srcRef && !!hrefRef
+        }
+      }
+      if (identifier) {
+        n.attrs.info = {
+          ...(n.attrs.info || {}),
+          identifier,
+          contentType: 'website',
+          viewType: 'profile',
         }
+        // Clear the local path so the runtime resolves via info.identifier
+        // (→ assets.uniweb.app CDN) instead of requesting a non-existent
+        // file from the site host.
+        if (srcMatched) n.attrs.src = null
+        if (hrefMatched) n.attrs.href = null
+        // Match the Editor shape: plain `image` nodes skip identifier
+        // resolution in older runtimes; `ImageBlock` routes through
+        // parseImgBlock which reads info.identifier and fills url.
+        if (n.type === 'image' && n.attrs.role !== 'icon') {
+          n.type = 'ImageBlock'
+        }
+        count++
       }
     }
     for (const v of Object.values(n)) if (typeof v === 'object') walk(v)
@@ -1778,6 +1911,153 @@ function pickAssetRef(v) {
   return m ? m[1] : null
 }
 
+/**
+ * Walk every locale's content for `attrs.src` and `attrs.href` strings, and
+ * resolve absolute-path refs (e.g. `/covers/foo.svg`) to local files under
+ * the site root.
+ *
+ * Resolution order per ref:
+ *   1. `dist/{path}`    — vite outputs, link-mode collection JSON, etc.
+ *   2. `public/{path}`  — static author-placed assets (covers, images).
+ *
+ * Returns Map<originalRef, { resolvedPath, filename }> where:
+ *   - `originalRef`  — the exact src/href string from content (used as the
+ *                      lookup key during rewrite).
+ *   - `resolvedPath` — absolute path on disk (used for upload).
+ *   - `filename`     — basename, used as the assets-server upload filename.
+ *                      Server keys by (siteId, filename); collisions across
+ *                      paths with the same basename are flagged as warnings.
+ *
+ * Skips:
+ *   - Non-string values, refs that don't start with `/`, protocol-relative
+ *     refs (`//cdn.example.com/...`), and external URLs.
+ *   - Refs starting with `/api/` or `/_` (worker-internal paths, never
+ *     local files).
+ *   - Nodes already rewritten with `attrs.info.identifier` set (re-deploy).
+ */
+async function scanContentForAssetRefs(localeContents, dataFileObjects, siteDir) {
+  const candidates = new Set()
+  for (const lang of Object.keys(localeContents)) {
+    walkContentForAssetRefs(localeContents[lang], candidates)
+  }
+  // Also walk parsed collection JSON files. These contain BOTH ProseMirror-
+  // shaped sub-trees (article.content) AND flat string fields (article.image,
+  // article.cover, etc.). The walker captures both: any string-valued src/
+  // href/image/cover/thumbnail/icon/poster field, plus any string anywhere
+  // that looks like an absolute path with a known media extension.
+  for (const k of Object.keys(dataFileObjects || {})) {
+    if (dataFileObjects[k] !== null) {
+      walkContentForAssetRefs(dataFileObjects[k], candidates)
+    }
+  }
+
+  const results = new Map()
+  const filenameToRef = new Map() // detect collisions (same basename, different path)
+  for (const ref of candidates) {
+    if (!isResolvableContentRef(ref)) continue
+    const cleanPath = ref.split('?')[0].split('#')[0].slice(1) // drop leading '/'
+    const distCandidate = join(siteDir, 'dist', cleanPath)
+    const publicCandidate = join(siteDir, 'public', cleanPath)
+    let resolvedPath = null
+    if (existsSync(distCandidate)) {
+      try { if ((await stat(distCandidate)).isFile()) resolvedPath = distCandidate } catch {}
+    }
+    if (!resolvedPath && existsSync(publicCandidate)) {
+      try { if ((await stat(publicCandidate)).isFile()) resolvedPath = publicCandidate } catch {}
+    }
+    if (!resolvedPath) continue
+    const filename = resolvedPath.split(sep).pop()
+    const prior = filenameToRef.get(filename)
+    if (prior && prior !== resolvedPath) {
+      // Two different files want the same upload filename — server keys by
+      // filename so the second would clobber the first. Skip + warn rather
+      // than silently overwrite. Caller can rename the file or move one
+      // into a vite-processed path to disambiguate via content hashing.
+      say.warn(
+        `Asset filename collision: "${filename}" exists at multiple paths ` +
+          `(${prior}, ${resolvedPath}). Skipping the second; rename to disambiguate.`
+      )
+      continue
+    }
+    filenameToRef.set(filename, resolvedPath)
+    results.set(ref, { resolvedPath, filename })
+  }
+  return results
+}
+
+// Field names commonly used for media in collection JSON. The walker
+// collects any absolute-path string under these keys as a potential asset
+// reference. ProseMirror image/link nodes are caught separately via attrs.
+const FLAT_ASSET_FIELDS = new Set([
+  'src', 'href', 'image', 'cover', 'thumbnail', 'icon', 'poster', 'logo',
+  'avatar', 'photo', 'banner', 'background',
+])
+
+function walkContentForAssetRefs(node, refs) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) { for (const child of node) walkContentForAssetRefs(child, refs); return }
+  if (node.attrs && typeof node.attrs === 'object') {
+    // Skip nodes already rewritten in a prior deploy — those have an
+    // identifier and the runtime resolves them through the CDN already.
+    if (!node.attrs.info?.identifier) {
+      if (typeof node.attrs.src === 'string') refs.add(node.attrs.src)
+      if (typeof node.attrs.href === 'string') refs.add(node.attrs.href)
+    }
+  }
+  // Flat fields: collection-shaped objects (e.g. an article record) often
+  // carry media URLs as plain string fields rather than ProseMirror nodes.
+  // Capture absolute-path values under known keys.
+  for (const [k, v] of Object.entries(node)) {
+    if (typeof v === 'string' && FLAT_ASSET_FIELDS.has(k) && isResolvableContentRef(v)) {
+      refs.add(v)
+    } else if (typeof v === 'object') {
+      walkContentForAssetRefs(v, refs)
+    }
+  }
+}
+
+/**
+ * Walk an arbitrary JSON tree and replace any string equal to a key in
+ * `byOriginalRef` (and not already a CDN URL) with the asset's CDN URL.
+ * Used for collection JSON files where image refs are flat string fields
+ * (e.g. `article.image: "/covers/foo.svg"`) rather than ProseMirror nodes.
+ *
+ * Returns the number of replacements performed.
+ */
+function rewriteFlatAssetUrls(node, byOriginalRef) {
+  let count = 0
+  const walk = (n, parent, key) => {
+    if (n == null) return
+    if (typeof n === 'string') {
+      const id = byOriginalRef.get(n)
+      if (id && parent != null && key != null) {
+        parent[key] = resolveAssetCdnUrl(id)
+        count++
+      }
+      return
+    }
+    if (typeof n !== 'object') return
+    if (Array.isArray(n)) {
+      for (let i = 0; i < n.length; i++) walk(n[i], n, i)
+      return
+    }
+    for (const [k, v] of Object.entries(n)) walk(v, n, k)
+  }
+  walk(node, null, null)
+  return count
+}
+
+function isResolvableContentRef(ref) {
+  if (typeof ref !== 'string' || !ref) return false
+  // Absolute-path only — relative paths (`./foo`, `foo`) are content-author
+  // shorthand handled elsewhere; URLs (`http://`, `//cdn`) never resolve to
+  // local files; worker-internal paths (`/api/`, `/_`) aren't asset content.
+  if (!ref.startsWith('/')) return false
+  if (ref.startsWith('//')) return false
+  if (ref.startsWith('/api/') || ref.startsWith('/_')) return false
+  return true
+}
+
 // ─── Loopback listener (review path) ───────────────────────
 
 /**