uniweb 0.25.3 → 0.25.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.25.3",
+  "version": "0.25.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
     "@uniweb/semantic-parser": "^1.2.3"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.24.3",
+    "@uniweb/build": "^0.24.5",
     "@uniweb/content-reader": "^1.2.3",
     "@uniweb/semantic-parser": "^1.2.3"
   },

package/src/backend/foundation-bring-along.js

@@ -1,10 +1,10 @@
 /**
- * Bring-the-foundation-along — the freshness loop `uniweb publish` runs before
- * it makes a site live (shipping-model.md §4).
+ * Bring-the-foundation-along — the freshness loop `uniweb publish` AND `uniweb
+ * push` run before handing a site to a backend (shipping-model.md §4).
  *
  * A publish must never ship a site pointing at stale or missing foundation code
  * (the footgun: a site goes live referencing a version the catalog doesn't
- * have). So when the site references a LOCAL foundation, publish fingerprints it
+ * have). So when the site references a LOCAL foundation, the verb fingerprints it
  * and reconciles with the catalog. Three cases (§4):
  *
  *   | version not yet registered    | release it, then publish        |
@@ -20,6 +20,16 @@
  * "Release" here is literally `uniweb register` run in the foundation directory
  * — same build-if-stale → schema submit → code upload → digest the standalone
  * verb does, so there is exactly one foundation-release path.
+ *
+ * ⭐ **`push` runs it too, and for a reason publish's framing does not cover.**
+ * [Diego, 2026-08-19] — *"A published site can only reference a registered
+ * foundation … In fact, not even a push can, because we can't preview the site in
+ * the frontend in that case."* A push is the collaboration verb: a teammate opens
+ * the site in the visual app straight after, and the app can only render it against
+ * foundation code the backend can serve. So an unregistered ref is not merely a
+ * publish-time problem — it is a broken preview, which is where a teammate actually
+ * meets it. `verb` names the caller in the messages so the fix the user is told to
+ * run is the command they ran.
  */
 
 import { readFileSync } from 'node:fs'
@@ -177,7 +187,8 @@ export async function bringFoundationAlong({
   say,
   confirm,
   cliBin,
-  dryRun = false
+  dryRun = false,
+  verb = 'publish'
 }) {
   const local = resolveLocalFoundation(siteDir, siteYml)
   if (!local) {
@@ -194,7 +205,8 @@ export async function bringFoundationAlong({
     say,
     confirm,
     cliBin,
-    dryRun
+    dryRun,
+    verb
   })
 }
 
@@ -216,7 +228,8 @@ async function bringLocalCodeAlong({
   say,
   confirm,
   cliBin,
-  dryRun = false
+  dryRun = false,
+  verb = 'publish'
 }) {
   const Kind = kind === 'extension' ? 'Extension ' : 'Foundation'
   const label =
@@ -243,7 +256,18 @@ async function bringLocalCodeAlong({
     say.dim(
       `${Kind}  : ${label} — local; would release if changed or not yet registered`
     )
-    return { released: false, proceed: true, ref: null }
+    // The ref still comes back where one can be formed: it is read from the
+    // foundation's own package.json, so it costs no network, and an offline preview
+    // that omitted it would emit a document the real run would not — the one thing
+    // `-o` exists to avoid.
+    //
+    // ⚠️ It is null for a foundation that has NEVER been registered and carries no
+    // scope (a freshly scaffolded `name: "src"`), because the scope is what
+    // `register` writes back (`writePkgScope`). So the preview shows the authored
+    // value there, and the first real push — which releases, and so acquires the
+    // scope — sends the pinned ref instead. That gap is unavoidable offline: before
+    // the first release there is no registered name to name.
+    return { released: false, proceed: true, ref: pinnedRef() }
   }
 
   // Ask the catalog what it has. Null → not registered (or the backend can't
@@ -294,7 +318,7 @@ async function bringLocalCodeAlong({
     )
     if (skipPrompts || isNonInteractive(args)) {
       say.dim(
-        'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to publish a change.'
+        'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to release a change.'
       )
       return { released: false, proceed: true, ref: pinnedRef() }
     }
@@ -318,19 +342,19 @@ async function bringLocalCodeAlong({
     `Your local ${label} differs from the registered version ${reg.latest_version}, but the version wasn't bumped.`
   )
   say.dim(
-    `A registered version is immutable. Bump the ${kind}'s version to release the change, then re-run \`uniweb publish\`.`
+    `A registered version is immutable. Bump the ${kind}'s version to release the change, then re-run \`uniweb ${verb}\`.`
   )
   if (skipPrompts || isNonInteractive(args)) {
     say.dim(`Proceeding with the already-registered ${reg.latest_version}.`)
     return { released: false, proceed: true, ref: pinnedRef() }
   }
   const proceed = await confirm(
-    `Publish with the already-registered ${reg.latest_version} anyway?`,
+    `Continue with the already-registered ${reg.latest_version} anyway?`,
     false
   )
   if (!proceed) {
     say.info(
-      `Aborted — bump the ${kind} version, then re-run \`uniweb publish\`.`
+      `Aborted — bump the ${kind} version, then re-run \`uniweb ${verb}\`.`
     )
     return { released: false, proceed: false, ref: null }
   }

package/src/backend/site-sync.js

@@ -24,7 +24,8 @@ import {
   diffSiteUnits,
   describeSiteDiff,
   computeUnitHashes,
-  collectUnitUuids
+  collectUnitUuids,
+  readAssetMap
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -181,11 +182,11 @@ function readSyncCacheFile(siteDir) {
     return {} // missing / unreadable → treat everything as changed
   }
 }
-// The cache holds three maps written on DIFFERENT events — content hashes on a
-// successful push, base versions on push AND pull, unit hashes on push and pull —
-// so every writer must preserve the ones it isn't touching. One merge point rather
-// than three hand-rolled preserves, because getting that wrong silently disarms
-// whichever map got clobbered.
+// The cache holds several maps written on DIFFERENT events — content hashes and the
+// injections that produced them on a successful push, base versions on push AND
+// pull, unit hashes on push and pull — so every writer must preserve the ones it
+// isn't touching. One merge point rather than a hand-rolled preserve per writer,
+// because getting that wrong silently disarms whichever map got clobbered.
 function updateSyncCache(siteDir, patch) {
   const p = syncCachePath(siteDir)
   mkdirSync(dirname(p), { recursive: true })
@@ -203,9 +204,10 @@ const readMap = (siteDir, key) => {
  * Drop every cache map that describes a BACKEND site, when this clone is bound to
  * none. Returns the names dropped (empty when there was nothing to do).
  *
- * `.uniweb/sync-cache.json` holds four maps keyed by *unit path* — item uuids,
- * content hashes, entity base versions, unit bases — and a unit path (`site.yml`,
- * `pages/about/about.md`) is the same string for every site. So the cache does not
+ * `.uniweb/sync-cache.json` holds five maps keyed by *unit path* — item uuids,
+ * content hashes, the injections those hashes were taken over, entity base versions,
+ * unit bases — and a unit path (`site.yml`, `pages/about/about.md`) is the same
+ * string for every site. So the cache does not
  * self-invalidate when `site.yml::$uuid` goes away: it keeps describing the site
  * this folder used to be.
  *
@@ -228,21 +230,29 @@ const readMap = (siteDir, key) => {
  * the clone look bound before the check runs.
  */
 /**
- * Drop the four remote-derived maps unconditionally, stamping the site they now
+ * Drop the five remote-derived maps unconditionally, stamping the site they now
  * describe (or clearing the stamp when there is none). Shared by the pre-flight
  * guard and the `item_uuid_conflict` recovery — the guard decides WHETHER, this
  * decides WHAT, and they must not drift.
  */
 export function clearRemoteSyncState(siteDir, siteUuid = null) {
   const prior = readSyncCacheFile(siteDir)
-  const dropped = ['itemUuids', 'hashes', 'baseVersions', 'unitBases'].filter(
-    (k) => prior[k] && Object.keys(prior[k]).length
-  )
+  const dropped = [
+    'itemUuids',
+    'hashes',
+    'baseVersions',
+    'unitBases',
+    'applied'
+  ].filter((k) => prior[k] && Object.keys(prior[k]).length)
   updateSyncCache(siteDir, {
     itemUuids: {},
     hashes: {},
     baseVersions: {},
     unitBases: {},
+    // Remote-derived like the rest, and doubly so: it holds the OLD site's asset
+    // serve URLs. Surviving the drop, it would rewrite the new site's media to
+    // bytes owned by the site this folder used to be.
+    applied: {},
     siteUuid: siteUuid || null
   })
   return dropped
@@ -258,7 +268,13 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
   }
 
   const prior = readSyncCacheFile(siteDir)
-  const REMOTE_MAPS = ['itemUuids', 'hashes', 'baseVersions', 'unitBases']
+  const REMOTE_MAPS = [
+    'itemUuids',
+    'hashes',
+    'baseVersions',
+    'unitBases',
+    'applied'
+  ]
   const populated = REMOTE_MAPS.filter(
     (k) => prior[k] && Object.keys(prior[k]).length
   )
@@ -302,8 +318,53 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
 export function readSyncCache(siteDir) {
   return readMap(siteDir, 'hashes')
 }
-export function writeSyncCache(siteDir, hashes) {
-  updateSyncCache(siteDir, { hashes })
+
+/**
+ * The hash-affecting injections the emit that produced those hashes applied, in the
+ * exact shape `emitSyncPackages` takes back as opts.
+ *
+ * ⛔ **Only the ones nothing else records.** `assetIds` is deliberately NOT banked
+ * here even though the emit applies it: `assets.json` is COMMITTED project state
+ * holding exactly that map (local ref → `{id, ext}`), written by the same push, and
+ * a gitignored second copy would be a second thing to disagree — the reason that
+ * file itself refuses to hold a serve URL. It also has the worse lifetime of the
+ * two: `clearRemoteSyncState` wipes this cache, and the committed map correctly
+ * survives. ⇒ Bank what a reader cannot re-derive; re-derive the rest.
+ *
+ * ⛔ Read this whenever you re-emit to COMPARE against `hashes`. A push hashes the
+ * DELIVERED document — local `/images/x.png` rewritten to the backend serve URL it
+ * just uploaded to, `info.foundation` replaced by the version-pinned ref — and banks
+ * that. An offline re-emit produces the AUTHORED document, which is a different
+ * document, so it matches nothing and every entity reads as changed forever. That is
+ * not hypothetical: it is what `uniweb status` did on any site with one local image
+ * (backend-framework-787e, 2026-08-19) — `push` said "1 entity unchanged" and
+ * `status --json` said `changed: 1`, from the same cache, seconds apart.
+ *
+ * ⭐ What is left is what only a backend round-trip produces — an asset **serve URL**
+ * and a released foundation version — and `status` is offline by design (measured at
+ * zero HTTP requests, a property the cross-client flows rely on). ⚠️ Note the serve
+ * URL is REPLAYED, never composed: we re-use the string the host handed us, which is
+ * a different act from reconstructing one, and the distinction is the same one that
+ * keeps `assets.json` id-only. An asset genuinely new to the site has no recorded
+ * mapping and still reads as changed, which is correct.
+ */
+export function readAppliedInjections(siteDir) {
+  return readMap(siteDir, 'applied')
+}
+
+/**
+ * Bank the content hashes and the injections that produced them. ⛔ ONE call, both
+ * maps: they describe the same document, so writing either alone leaves the cache
+ * self-inconsistent — and the failure is silent, since a hash never says which
+ * document it is of. `applied` is written even when empty, so it can never be a
+ * leftover from an earlier push describing hashes it no longer matches.
+ *
+ * `assetIds` is dropped rather than stored — see readAppliedInjections: it has a
+ * committed source of truth in `assets.json`, and the reader re-derives it there.
+ */
+export function writeSyncCache(siteDir, hashes, applied) {
+  const { assetIds: _inAssetsJson, ...bankable } = applied || {}
+  updateSyncCache(siteDir, { hashes, applied: bankable })
 }
 
 /**
@@ -835,10 +896,24 @@ export function writeUnitBases(siteDir, patch) {
  */
 export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   const priorHashes = readSyncCache(siteDir)
+  // Re-emit the document the last push HASHED, not the one the author wrote — see
+  // readAppliedInjections. Two sources, on purpose:
+  //   · BANKED — the serve URLs and pinned refs only a round-trip produces. Empty
+  //     for a cache written before this was banked (and for a never-pushed site),
+  //     which is the pre-fix behaviour and self-heals on the next push. It can never
+  //     point at the wrong document: it is written with the hashes it belongs to.
+  //   · RE-DERIVED — asset identity, from the COMMITTED `assets.json` the same push
+  //     wrote. Reading the live file rather than a snapshot is what makes a moved
+  //     map (a teammate's push, a pull) read as changed instead of matching a copy
+  //     of itself.
+  const applied = readAppliedInjections(siteDir)
+  const assetIds = readAssetMap(siteDir)
   const pkg = await emitSyncPackages(siteDir, {
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
-    sendAll
+    sendAll,
+    ...applied,
+    ...(Object.keys(assetIds).length ? { assetIds } : {})
   })
   const changed =
     (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
@@ -867,7 +942,7 @@ export async function pushSyncPackages({
   asOrg,
   report
 }) {
-  const { siteContent, collections, siteContentUuid, hashes } = pkg
+  const { siteContent, collections, siteContentUuid, hashes, applied } = pkg
   const { info, note, error } = report
   const dim = report.dim || ((s) => s)
 
@@ -1200,7 +1275,7 @@ export async function pushSyncPackages({
   // then bank the post-write tokens so the NEXT push carries a current base.
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
-  writeSyncCache(siteDir, hashes)
+  writeSyncCache(siteDir, hashes, applied)
   mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane

package/src/commands/publish.js

@@ -46,7 +46,6 @@ import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
-import { createInterface } from 'node:readline/promises'
 import yaml from 'js-yaml'
 
 import {
@@ -66,7 +65,7 @@ import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { readFlagValue, readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
-import { isNonInteractive } from '../utils/interactive.js'
+import { isNonInteractive, confirm } from '../utils/interactive.js'
 import { headProvenance } from '../utils/git.js'
 import {
   makeModelResolver,
@@ -106,22 +105,6 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
-// Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
-async function confirm(question, defaultYes = false) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout })
-  try {
-    const a = (
-      await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)
-    )
-      .trim()
-      .toLowerCase()
-    if (!a) return defaultYes
-    return a === 'y' || a === 'yes'
-  } finally {
-    rl.close()
-  }
-}
-
 // Origin-relative serve path → clickable absolute URL (self-serve default).
 function absolutizeServeUrl(origin, url) {
   if (!url || typeof url !== 'string') return null

package/src/commands/pull.js

@@ -692,10 +692,47 @@ export async function pull(args = [], deps = {}) {
         }
       }
 
+      // ⛔ Do NOT overwrite a workspace project's `site.yml::foundation`.
+      //
+      // Same principle as restoring authored asset paths above, and the same
+      // failure it prevents: a round trip must not mangle what the author wrote.
+      // `publish` stamps the RELEASED, version-pinned ref into `info.foundation`
+      // (delivery is version-pinned end to end), so projecting the stored value
+      // back turns `foundation: src` into `@org/x@1.2.3` — which the build then
+      // REFUSES to resolve, leaving the project unable to `build`, `dev` or
+      // `export`. It stays publishable throughout, so nothing surfaces it.
+      //
+      // ⚖️ Only suppressed when the AUTHORED value resolves to a local foundation.
+      // A project from `uniweb clone` has no local foundation on disk, and there
+      // the pinned ref is exactly what site.yml should say — so this is a
+      // question about which project shape we are writing into, not a blanket
+      // "never project it".
+      //
+      // Lazily imported: the resolver lives behind `@uniweb/build`'s root, which
+      // pulls the vite chain, and this file deliberately imports only the `uwx`
+      // leaf. Reused rather than reimplemented so "which foundation" cannot drift
+      // from what the build itself resolves.
+      let keepAuthoredFoundation = false
+      try {
+        const { resolveLocalFoundation } = await import(
+          '../backend/foundation-bring-along.js'
+        )
+        const authored = yaml.load(
+          readFileSync(join(siteDir, 'site.yml'), 'utf8')
+        )
+        keepAuthoredFoundation = Boolean(
+          resolveLocalFoundation(siteDir, authored)
+        )
+      } catch {
+        // No site.yml, unreadable, or nothing local — project the stored value,
+        // which is the pre-existing behaviour and right for a fresh clone.
+      }
+
       const report = siteContentDocumentToProject({
         document: siteDoc,
         siteRoot: siteDir,
-        prune
+        prune,
+        keepAuthoredFoundation
       })
       wrote.push(...report.pages, ...report.sections, ...report.layout)
       removed.push(

package/src/commands/push.js

@@ -60,8 +60,9 @@
  * the emit, and the `-o`/`--dry-run` preview.
  */
 
-import { writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import yaml from 'js-yaml'
 import { emitSyncPackages } from '@uniweb/build/uwx'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
@@ -71,6 +72,8 @@ import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessCollections } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import { confirm } from '../utils/interactive.js'
+import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
   makeModelResolver,
   readSyncCache,
@@ -179,6 +182,61 @@ export async function push(args = [], deps = {}) {
   }
   const asOrg = org.asOrg
 
+  // Bring the foundation along — BEFORE any asset upload, because an upload is
+  // chargeable and a push that aborts after one has spent the user's money for
+  // nothing.
+  //
+  // ⭐ Why push and not just publish. [Diego, 2026-08-19] — *"A published site can
+  // only reference a registered foundation … In fact, not even a push can, because
+  // we can't preview the site in the frontend in that case."* Push is the
+  // collaboration verb: a teammate opens the site in the visual app right after,
+  // and the app can only render against foundation code the backend can serve. So
+  // storing an unregistered ref does not merely defer a problem to publish — it
+  // hands the teammate a site that cannot render, which is where they meet it.
+  //
+  // `fnd.ref` is the pinned `@scope/name@version`, stamped onto the wire below.
+  // That also makes push and publish agree about the document they emit; until now
+  // push sent the authored string and publish sent the pinned ref, so the two saw
+  // each other's pushes as changes.
+  const siteYml = (() => {
+    try {
+      return yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8')) || {}
+    } catch {
+      return {}
+    }
+  })()
+  const say = {
+    ok: success,
+    info,
+    warn,
+    err: error,
+    dim: note
+  }
+  let fnd = { ref: null }
+  try {
+    fnd = await bringFoundationAlong({
+      client,
+      siteDir,
+      siteYml,
+      args,
+      say,
+      confirm,
+      cliBin: process.argv[1],
+      // An offline emit reports what it WOULD do and touches no network; the ref
+      // still comes back (read from the foundation's package.json) so the preview
+      // matches what a real push sends — EXCEPT for a foundation never yet
+      // registered, which has no scope to form a ref from until the first release
+      // writes one. See the dry-run branch in foundation-bring-along.js.
+      dryRun: !!output || dryRun,
+      verb: 'push'
+    })
+  } catch (err) {
+    error(`Foundation release failed: ${err.message}`)
+    note('Fix the foundation, then re-run `uniweb push`.')
+    return { exitCode: 1 }
+  }
+  if (!fnd.proceed) return { exitCode: 1 }
+
   // Build BOTH directional packages (the producer side). Each carries its own
   // `index` — the per-entity source-file map for back-fill, correlated by submission
   // position. Non-local Models are fetched from the registry on demand. `priorHashes`
@@ -346,6 +404,12 @@ export async function push(args = [], deps = {}) {
       priorHashes,
       sendAll,
       itemUuids,
+      // The PINNED foundation ref from the bring-along above, stamped over the
+      // authored `site.yml` string. Delivery is version-pinned end to end, so an
+      // unpinned local name on the wire names code no host can serve. Absent when
+      // the site already references a registry ref or URL — then site.yml's own
+      // value rides verbatim.
+      ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
       // Both grains are dropped together by --force: one flag, one meaning,
       // no partial-force mode.
       ...(force

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-18T22:18:28.572Z",
+  "generatedAt": "2026-08-19T04:22:45.477Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.24.3",
+      "version": "0.24.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",

package/src/utils/flag-guard.js

@@ -58,7 +58,12 @@ const VERBS = {
     '--foundation', '--output', '-o', '--personal', '--registry', '--token',
     // read in utils/conformance.js and backend/site-sync.js respectively —
     // neither appears in push.js
-    '--no-validate', '--yes', ...VIA_DEPLOY
+    '--no-validate', '--yes',
+    // via backend/foundation-bring-along.js, which push runs since 2026-08-19 —
+    // one of the three flags that skip its prompts. Found by
+    // flag-guard-coverage.test.js the moment push gained the import, which is
+    // exactly the hand-enumeration failure that test exists to catch.
+    '--no-verify', ...VIA_DEPLOY
   ],
   publish: [
     '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',

package/src/utils/interactive.js

@@ -18,6 +18,33 @@ export function isNonInteractive(args) {
   return false
 }
 
+/**
+ * Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
+ *
+ * Shared rather than per-command: every verb that can stop and ask needs one, and
+ * three hand-rolled copies would eventually disagree about what a bare Enter means
+ * — which is the answer the user gives most often and thinks about least.
+ *
+ * ⛔ Callers must decide NOT to ask before calling: this always reads stdin, and a
+ * prompt in a non-interactive run hangs a pipeline. Gate on `isNonInteractive(args)`
+ * (and on any --yes/--force style skip the verb defines).
+ */
+export async function confirm(question, defaultYes = false) {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (
+      await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)
+    )
+      .trim()
+      .toLowerCase()
+    if (!a) return defaultYes
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
 /**
  * Get the CLI invocation prefix to use in suggested commands.
  * Mirrors however the user actually ran the CLI.

package/src/utils/site-data-upload.js

@@ -39,7 +39,15 @@
  * an upload landed.
  *
  * Contract ratified 2026-08-18; see `kb/framework/build/data-ball-retirement.md`.
- * ⚠️ **The endpoint is not built yet** — this is unwired until it is.
+ * **Wired into `publish.js` and shipped in `uniweb` 0.25.3.** Both arms of the
+ * endpoint exist (presigned landed 2026-08-18, per Diego).
+ *
+ * ⚠️ **The presigned arm has never been exercised against a real backend from
+ * here.** The branch is one line and unit-tested both ways, but a stub is not a
+ * presigning deployment — three claims diverged that way in a single day while
+ * this lane was being built. A local `uniwebd` answers `direct`, so proving it
+ * needs a presigning deployment and one real publish. **Believed correct, not
+ * demonstrated.**
  */
 
 import { createHash } from 'node:crypto'