uniweb 0.84.0 → 0.86.0

package/src/commands/publish.js

@@ -22,9 +22,9 @@
  * Distinct from `uniweb deploy` (third-party hosts) and `uniweb register`
  * (foundation code → catalog). For a self-contained artifact, see `uniweb export`.
  *
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * Usage:
  *   uniweb publish                 Bring the foundation along, sync, and go live
@@ -57,13 +57,16 @@ import { emitSyncPackages } from '@uniweb/build/uwx'
 import {
   bankLanguages,
   reconcile,
-  settleServices
+  announceServices,
+  foundationSupports,
+  recordsNotAsked
 } from '../backend/service-request.js'
 import { isSiteRelativeExtensionUrl } from '@uniweb/build'
 import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 
 import {
   BackendClient,
+  BackendUnreachableError,
   describeRequestError,
   WorkspaceMismatchError
 } from '../backend/client.js'
@@ -268,10 +271,10 @@ export async function publish(args = []) {
   }
   const siteYml = readSiteYml(join(siteDir, 'site.yml'))
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -301,8 +304,8 @@ export async function publish(args = []) {
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not when
-  // UNIWEB_REGISTER_URL chose the backend — that is already a decision.
-  if (!process.env.UNIWEB_REGISTER_URL) {
+  // UNIWEB_SERVER chose the backend — that is already a decision.
+  if (!process.env.UNIWEB_SERVER) {
     const known = syncedElsewhere(siteDir, client.origin)
     if (known) {
       const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'publish')
@@ -478,6 +481,12 @@ export async function publish(args = []) {
       cliBin: process.argv[1]
     })
   } catch (err) {
+    // A backend that did not answer is said as that — not as a release that failed.
+    if (err instanceof BackendUnreachableError) {
+      say.err(err.message)
+      say.dim('Nothing was released or sent. Check that the backend is running, then re-run `uniweb publish`.')
+      return { exitCode: 1 }
+    }
     // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
     say.err(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
     for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb publish`.']) say.dim(line)
@@ -804,26 +813,16 @@ export async function publish(args = []) {
   const injectInfo = {
     ...(fnd.ref ? { foundation: fnd.ref } : {})
   }
-  // ⭐ WHAT THE SITE HAS — read before the push, for the two requests a publish
-  // carries: the services (`site.yml::services`) and the language selection. Only
-  // this read sees a decision the owner made in the app since this clone last synced.
-  // It reads this backend's site, from sync.json; a never-synced site has none.
+  // ⭐ WHAT THE SITE HAS — read before the push, for the language selection. Only this
+  // read sees a decision the owner made in the app since this clone last synced. It
+  // reads this backend's site, from sync.json; a never-synced site has none.
   const boundUuid = readBackendState(siteDir, client.origin).site?.uuid || null
   const status = boundUuid ? await client.siteStatus(boundUuid) : null
 
-  // ⭐ THE SERVICES: what the owner changed in `site.yml::services` is sent, applied
-  // over the site's own list; what the site changed is kept and offered into the file;
-  // where both changed, the owner is asked (`settleServices`). An ask whose decision is
-  // still open is never sent over the decision the site holds.
-  const services = await settleServices({
-    client,
-    siteDir,
-    siteYml,
-    status,
-    interactive: !isNonInteractive(args),
-    confirm,
-    say
-  })
+  // ⭐ THE SERVICES are stated by the push itself — the file's, and off for each held
+  // one it no longer lists (`statedServices`) — and the backend decides per service.
+  // Said here: what the file asks that will not be sent as written.
+  announceServices({ siteYml, say, supports: await foundationSupports(siteDir, siteYml) })
 
   // ⭐ THE LANGUAGE SELECTION IS A REQUEST TOO, and it is the one that costs.
   //
@@ -873,8 +872,6 @@ export async function publish(args = []) {
     backend: client.origin,
     // The keys this deployment's Sections take — see deploymentFields.
     ...fields,
-    // The `services` Section as settled above — or withheld.
-    ...services.emit,
     // Placement identity for the folder — see writeFolderItemUuids.
     folderItemUuids: readFolderItemUuids(siteDir, client.origin),
     // Identity for the records' list items — see readRecordItemUuids.
@@ -908,6 +905,10 @@ export async function publish(args = []) {
   if (refuseUnsendableRecords(pkg.refusals, { error: say.err, note: say.dim })) {
     return { exitCode: 1 }
   }
+  // ⭐ `records` is what delivers the records the pages show on the published site — said
+  // here, at publish, and never at push: syncing records does not depend on it.
+  const notAsked = recordsNotAsked({ siteYml, shown: pkg.recordsShown })
+  if (notAsked) say.warn(notAsked)
   const report = {
     info: (m) => say.info(m),
     note: (m) => say.dim(m),
@@ -921,9 +922,6 @@ export async function publish(args = []) {
     report
   })
   if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
-  // The push stored what it sent: the services agreed on are recorded now, whether or
-  // not the site then goes live.
-  services.after()
   const siteUuid = pushResult.boundSiteUuid
   if (!siteUuid) {
     say.err('Push did not yield a site uuid — cannot go live.')
@@ -942,7 +940,7 @@ export async function publish(args = []) {
   } catch (err) {
     say.err(describeRequestError(err, client.origin))
     if (!(err instanceof WorkspaceMismatchError))
-      say.dim('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+      say.dim('Is that the backend you meant? Switch with: uniweb login --server <url>')
     return { exitCode: 1 }
   }
   // The body of a publish that did not go through — read once, and kept for the report below.

package/src/commands/pull.js

@@ -44,9 +44,9 @@
  *
  * The content + folder pull lanes are both keyed by the site's uuid on that backend
  *   (sync.json).
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
  * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
@@ -95,7 +95,8 @@ import {
   rebankSyncHashes,
   writeQueryUuids,
   mergeBaseVersions,
-  mergeItemBaseVersions,
+  writeItemBaseVersions,
+  pulledItemVersions,
   writeUnitBases,
   writeItemUuids,
   writeFolderItemUuids
@@ -701,10 +702,10 @@ export async function pull(args = [], deps = {}) {
     if (blocked) return blocked
   }
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -746,14 +747,14 @@ export async function pull(args = [], deps = {}) {
   if (!siteContentUuid) {
     // Following the login can land on a backend with no site for this project while it
     // has one elsewhere — say where, rather than only "push first", which would create a
-    // second site. Not when UNIWEB_REGISTER_URL chose the backend: that is a decision.
-    const known = !process.env.UNIWEB_REGISTER_URL
+    // second site. Not when UNIWEB_SERVER chose the backend: that is a decision.
+    const known = !process.env.UNIWEB_SERVER
       ? syncedElsewhere(siteDir, client.origin)
       : null
     if (known) {
       info(`Nothing to pull — this project has no site on ${client.origin}.`)
       note(
-        `Its ${known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`}. To pull from there: uniweb login --backend <url>`
+        `Its ${known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`}. To pull from there: uniweb login --server <url>`
       )
       return { exitCode: 0 }
     }
@@ -798,7 +799,7 @@ export async function pull(args = [], deps = {}) {
     } catch (err) {
       error(describeRequestError(err, client.origin))
       if (err instanceof WorkspaceMismatchError) return { refused: true }
-      note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+      note('Is that the backend you meant? Switch with: uniweb login --server <url>')
       return null
     }
     if (res.status === 404) {
@@ -815,7 +816,7 @@ export async function pull(args = [], deps = {}) {
       if (detail) note(detail)
       if (res.status === 401 || res.status === 403)
         note(
-          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
+          "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
         )
       return null
     }
@@ -887,6 +888,9 @@ export async function pull(args = [], deps = {}) {
   // The Models the pulled site's queries name, as the push qualified them — the re-bank
   // below resolves with them too (see there).
   let pulledQueryModels = []
+  // The versions this copy holds after the pull: every site-content item the pulled
+  // document carries (`pulledItemVersions`), banked below once the files have taken it.
+  let pulledVersions = null
   if (content && !content.notModified) {
     const siteDoc =
       content.docs &&
@@ -905,6 +909,7 @@ export async function pull(args = [], deps = {}) {
       // The next push re-establishes it; until then our side reports as unknown,
       // which is honest rather than wrong.
       writeUnitBases(siteDir, client.origin, { remote: computeUnitHashes(siteDoc), local: {} })
+      pulledVersions = pulledItemVersions(siteDoc, content.itemVersions)
       // Per-item identity for the next push. Without it the backend reads our
       // records as new and re-mints every page and section row.
       writeItemUuids(siteDir, client.origin, collectUnitUuids(siteDoc))
@@ -1216,7 +1221,13 @@ export async function pull(args = [], deps = {}) {
       // Records this pull did not place were not taken, so neither is their lane.
       if (lane === folderLane && recordsNotPlaced) continue
       mergeBaseVersions(siteDir, client.origin, lane.versions)
-      mergeItemBaseVersions(siteDir, client.origin, lane.itemVersions)
+    }
+    // ⭐ The site-content items' versions REPLACE what this copy held: a pull is how it
+    // sees the site, and a version kept for an item the site no longer has would be sent
+    // again, asking the backend to delete it. The folder lane's are not kept — that lane
+    // is gated by its entity version. (Both were merged into one map until 2026-10-07.)
+    if (pulledVersions && content && !content.notModified && !content.refused) {
+      writeItemBaseVersions(siteDir, client.origin, pulledVersions)
     }
     // Persist the ETags so the next pull is conditional (304 when unchanged). The
     // folder's is DROPPED when records were not placed, so the next pull fetches

package/src/commands/push.js

@@ -48,9 +48,9 @@
  * backend's reconcile deletes items absent from the package, so an author's NEW page
  * would be hard-deleted). `--force` omits the token and restores last-push-wins.
  *
- * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ * Backend: the one you are logged in to — UNIWEB_SERVER overrides it for a script
  *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
- *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
+ *   No `--server` or `--token`: switching and signing in are `uniweb login`.
  *
  * The two-lane SUBMISSION (POST both lanes, back-fill uuids, persist the
  * send-only-changed cache) lives in `../backend/site-sync.js` so `uniweb publish`
@@ -65,7 +65,7 @@ import { emitSyncPackages, readBackendState } from '@uniweb/build/uwx'
 import { findSiteCopies, describeSiteCopies } from '../utils/site-copies.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { updateBackendMap, carryServed, SYNC_STORE_FILE } from '@uniweb/build/uwx'
-import { BackendClient } from '../backend/client.js'
+import { BackendClient, BackendUnreachableError } from '../backend/client.js'
 import { resolveSiteDir } from './deploy.js'
 import { refuseIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
@@ -75,7 +75,7 @@ import {
   describeSyncedElsewhere
 } from '../utils/site-identity.js'
 import { confirm, isNonInteractive } from '../utils/interactive.js'
-import { settleServices } from '../backend/service-request.js'
+import { announceServices, foundationSupports } from '../backend/service-request.js'
 import { guardEmptyRecords } from '../utils/records-guard.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
@@ -162,10 +162,10 @@ export async function push(args = [], deps = {}) {
   // arrival or lose a value on the way. See utils/conformance.js.
   if (await refuseIfContentDoesNotConform(siteDir, { args })) return { exitCode: 1 }
   // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
-  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // backend verb (resolveBackendOrigin). Only UNIWEB_SERVER — the automation
   // override — outranks it, and nothing talks to a backend the user is not logged in to:
   // logged in nowhere, the origin is the default backend and the first request asks for
-  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // that login. ⛔ There is no `--server` here: switching is `uniweb login --server`.
   // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
   // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
   // be reached: *"We do not allow any communication with backend if the user is not
@@ -209,8 +209,8 @@ export async function push(args = [], deps = {}) {
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not for `-o` (nothing is
-  // created) and not when UNIWEB_REGISTER_URL chose the backend — that is a decision.
-  if (!output && !process.env.UNIWEB_REGISTER_URL) {
+  // created) and not when UNIWEB_SERVER chose the backend — that is a decision.
+  if (!output && !process.env.UNIWEB_SERVER) {
     const known = syncedElsewhere(siteDir, client.origin)
     if (known) {
       const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'push')
@@ -278,6 +278,12 @@ export async function push(args = [], deps = {}) {
       verb: 'push'
     })
   } catch (err) {
+    // A backend that did not answer is said as that — not as a release that failed.
+    if (err instanceof BackendUnreachableError) {
+      error(err.message)
+      note('Nothing was released or sent. Check that the backend is running, then re-run `uniweb push`.')
+      return { exitCode: 1 }
+    }
     // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
     error(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
     for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb push`.']) note(line)
@@ -521,20 +527,10 @@ export async function push(args = [], deps = {}) {
       ref: siteYml?.foundation
     })
   }
-  // ⭐ THE SERVICES `site.yml` ASKS FOR — what the owner changed is sent over the site's
-  // own list; what the site changed is kept and offered into the file; where both
-  // changed, the owner is asked. Shared with `uniweb publish` (`settleServices`).
-  // Offline for `-o` and `--dry-run`: nothing is read, and nothing is recorded.
-  const offline = Boolean(output) || dryRun
-  const services = await settleServices({
-    client,
-    siteDir,
-    siteYml,
-    offline,
-    interactive: !offline && !isNonInteractive(args),
-    confirm,
-    say: { info, warn, dim: note, ok: success }
-  })
+  // ⭐ THE SERVICES `site.yml` ASKS FOR are stated by the emit — the file's, and off for
+  // each held one it no longer lists (`statedServices`) — and the backend decides per
+  // service. Said here: what the file asks that will not be sent as written.
+  announceServices({ siteYml, say: { warn }, supports: await foundationSupports(siteDir, siteYml) })
   const emitOptions = {
     backend: client.origin,
     // Placement identity for the folder — see writeFolderItemUuids.
@@ -570,9 +566,7 @@ export async function push(args = [], deps = {}) {
           itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
         }),
     ...(assetRewrite ? { assetRewrite } : {}),
-    ...(assetIds ? { assetIds } : {}),
-    // The `services` Section as settled above — or withheld.
-    ...services.emit
+    ...(assetIds ? { assetIds } : {})
   }
   let pkg
   try {
@@ -601,8 +595,6 @@ export async function push(args = [], deps = {}) {
 
   // Nothing changed since the last push — the backend is already up to date.
   if (totalEntities === 0) {
-    // The site already holds what this copy has, so what was settled is agreed.
-    if (!offline) services.after()
     success(
       `Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`
     )
@@ -663,7 +655,6 @@ export async function push(args = [], deps = {}) {
     }
   })
   if (result.exitCode !== 0) return { exitCode: result.exitCode }
-  services.after()
   success(
     `Pushed ${result.finalizedTotal} entit${result.finalizedTotal === 1 ? 'y' : 'ies'}` +
       (result.wrote.length ? ` — ${result.wrote.join(', ')}` : '')

package/src/commands/refresh.js

@@ -31,7 +31,8 @@
  *   uniweb refresh                 git pull, then merge the backend's content
  *   uniweb refresh --no-git        skip the git remote; backend only
  *   uniweb refresh --no-backend    skip the backend; git only
- *   uniweb refresh --backend <url> Override the backend origin
+ *
+ * The backend is the one you are logged in to, as for every backend verb (no flag picks it).
  */
 
 import { readFileSync } from 'node:fs'

package/src/commands/register.js

@@ -35,9 +35,9 @@
  *                                        ({ok,scope,origin,entities:[{name,uuid,version,unchanged}]}),
  *                                        all human output to stderr — for scripted callers
  *
- * Endpoint: UNIWEB_REGISTER_URL  >  the backend you are logged in to  >  the default
- *   (~/.uniweb/config.json, else uniweb.app) — resolveBackendOrigin. No `--backend`:
- *   switching is `uniweb login --backend <url>`.
+ * Endpoint: UNIWEB_SERVER  >  the backend you are logged in to  >  the default
+ *   (~/.uniweb/config.json, else uniweb.app) — resolveBackendOrigin. No backend flag:
+ *   switching is `uniweb login --server <url>`.
  * Auth (submit only):  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
  */
 
@@ -595,7 +595,7 @@ async function runRegister(args = []) {
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
   const scopeFlag = flagValue(args, '--scope')
-  // The backend you are logged in to (UNIWEB_REGISTER_URL overrides it for a script) —
+  // The backend you are logged in to (UNIWEB_SERVER overrides it for a script) —
   // resolveBackendOrigin, like every backend command.
   const client = new BackendClient({
     args,
@@ -845,7 +845,7 @@ async function runRegister(args = []) {
   } catch (err) {
     error(`Could not reach the registry at ${client.origin}: ${err.message}`)
     log(
-      `  ${colors.dim}Is that the backend you meant? Switch with: uniweb login --backend <url>${colors.reset}`
+      `  ${colors.dim}Is that the backend you meant? Switch with: uniweb login --server <url>${colors.reset}`
     )
     return { exitCode: 2 }
   }
@@ -905,7 +905,7 @@ async function runRegister(args = []) {
           `  ${colors.dim}The registry didn't accept your credentials — it may use different ones than \`uniweb login\`.${colors.reset}`
         )
         log(
-          `  ${colors.dim}Log in again (uniweb login --backend <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
+          `  ${colors.dim}Log in again (uniweb login --server <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
         )
       }
       // ⭐ **Surface `detail` as a sentence, not as a JSON dump.** The registry

package/src/commands/rename.js

@@ -62,7 +62,7 @@ import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import { getExistingPackageNames, validatePackageName } from '../utils/names.js'
 import { detectPackageManager, installCmd } from '../utils/pm.js'
 import { getCliPrefix } from '../utils/interactive.js'
-import { replaceInTopLevelList, setTopLevelScalar } from '../utils/yaml-edit.js'
+import { replaceInYamlList, setYamlKey } from '@uniweb/build/uwx'
 
 const colors = {
   reset: '\x1b[0m',
@@ -307,9 +307,9 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
         pkgSrc,
         sitePkgPath,
         siteYmlPath,
-        // Edited in place — see utils/yaml-edit.js — and computed HERE, before
+        // Edited in place — `setYamlKey`, @uniweb/build — and computed HERE, before
         // anything moves, so a file it cannot edit stops the rename cleanly.
-        newYmlText: ymlMatches ? setTopLevelScalar(ymlText, 'foundation', newName) : null,
+        newYmlText: ymlMatches ? setYamlKey(ymlText, 'foundation', newName) : null,
         hasDep,
         ymlMatches
       })
@@ -318,7 +318,7 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   refuseUneditableSiteYml(
     affectedSites.filter((s) => s.ymlMatches && s.newYmlText === null).map((s) => s.path),
     'foundation',
-    `Write it on one line: \`foundation: ${oldName}\`.`
+    `Write \`foundation: ${oldName}\` as a plain value — not through a YAML alias (\`*name\`) or merge key (\`<<:\`).`
   )
 
   // ─── Print plan, then execute ────────────────────────────────
@@ -530,14 +530,14 @@ async function renameExtension(rootDir, oldName, newName, prefix) {
         siteYmlPath,
         hits,
         // Edited in place, and computed before anything moves — as for foundations.
-        newYmlText: replaceInTopLevelList(ymlText, 'extensions', replacements)
+        newYmlText: replaceInYamlList(ymlText, 'extensions', replacements)
       })
     }
   }
   refuseUneditableSiteYml(
     affectedSites.filter((a) => a.newYmlText === null).map((a) => a.site.path),
     'extensions',
-    `Write each entry on a line of its own, e.g. \`- ${oldUrlPrefix}dist/entry.js\`.`
+    'Write `extensions:` as a plain list — not through a YAML alias (`*name`) or merge key (`<<:`).'
   )
 
   log('')