@uniweb/build 0.78.0 → 0.80.0

package/src/site/queries-config.js

@@ -41,6 +41,7 @@ import { refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { dataKeyTypes } from '../uwx/data-key-types.js'
 
 // Read its own YAML rather than importing the site build's helper. That import
 // pointed the wrong way — a config resolver reaching into the collector that
@@ -320,21 +321,73 @@ function refuseMethod(method, where) {
  * held a key a declaration may want for something else [Diego, 2026-09-27]. Until then every
  * query on the payload read `{ name: 'articles', … }` under `articles`.
  *
+ * ⭐ A query that declares no `schema:` and whose records a data key types carries the TYPE —
+ * `articles` → `@/post` (`dataKeyTyping`) — which is what a push names it on the wire
+ * (`uwx/site.js::queriesNested`). The schema a page's query carries is what a section's key is
+ * filled by at render (automatic `as`), so the two lanes fill the same keys. ⛔ Until 2026-10-08 the
+ * static payload carried the name (`@/articles`), and a key typed `@/post` filled on a hosted site
+ * and stayed empty on a static one.
+ *
  * Returns undefined for a site with no queries, so `config.queries`
  * stays absent rather than becoming an empty object — an empty object reads as
  * "declared, and empty" to anything checking for presence.
+ *
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`
+ * @param {Map<string, string>|null} [typing] - `dataKeyTyping`: name-defaulted ref → its type
  */
-export function toConfigQueries(declarations) {
+export function toConfigQueries(declarations, typing = null) {
   const names = Object.keys(declarations || {})
   if (names.length === 0) return undefined
   const out = {}
   for (const key of names) {
     const { schemaExplicit, name, ...rest } = declarations[key]
-    out[key] = rest
+    const typed = schemaExplicit === false ? typing?.get(rest.schema) : null
+    out[key] = typed ? { ...rest, schema: typed } : rest
   }
   return out
 }
 
+/**
+ * ⭐ THE TYPE A DATA KEY GIVES A NAME — `@/articles` → `@/post` (ruled 2026-09-25 [Diego];
+ * `uwx/data-key-types.js`), decided for the static build as a push decides it
+ * (`uwx/records.js::typedFor`), so both lanes give a query one schema.
+ *
+ * A name-defaulted ref, `@/<name>`, stands for the type of the data key of that name when:
+ *
+ *   - no data schema has the name — `@/<name>` resolves to nothing;
+ *   - the foundation's section types declare the key `<name>` with one type, and it resolves;
+ *   - no query asks for `@/<name>` explicitly — that one is the author's, and fails loudly.
+ *
+ * Then `records/<name>/` holds records of the type, and a query named `<name>` that declares no
+ * schema is a query of it. ⚠️ Where the records live on disk and how their translations are keyed
+ * stay keyed by the name.
+ *
+ * @param {string} siteRoot
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`, for which refs are explicit
+ * @param {object} [opts]
+ * @param {object} [opts.siteYml] - an already-read site.yml
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type; empty when none
+ */
+export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
+  const typing = new Map()
+  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const keyTypes = dataKeyTypes(await foundationSections(siteRoot, siteYml))
+  if (keyTypes.size === 0) return typing
+  const explicit = new Set(
+    Object.values(declarations || {})
+      .filter((d) => d && d.schemaExplicit === true)
+      .map((d) => d.schema)
+  )
+  const named = [...keyTypes.keys()].map(defaultSchema)
+  const { schemas } = await resolveRecordSchemas(siteRoot, [...named, ...keyTypes.values()], { siteYml })
+  for (const [key, type] of keyTypes) {
+    const ref = defaultSchema(key)
+    if (schemas[ref] || explicit.has(ref) || !schemas[type]) continue
+    typing.set(ref, type)
+  }
+  return typing
+}
+
 
 /**
  * The data schemas a site's records are shaped by, keyed by ref — each resolved from

package/src/site/query-processor.js

@@ -65,8 +65,8 @@ import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-p
 import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
 import { isDraftRecord } from './record-draft.js'
 import { refuseNotOneRecord } from './record-file.js'
-import { resolveRecordSchemas, resolveQueriesConfig, foundationSections } from './queries-config.js'
-import { dataKeyTypes } from '../uwx/data-key-types.js'
+import { resolveRecordSchemas, resolveQueriesConfig, dataKeyTyping } from './queries-config.js'
+import { keyOfDefaultRef } from '../uwx/data-key-types.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
 import { collectNestedRefs } from '@uniweb/schemas/format'
@@ -1197,10 +1197,24 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   const poolBySchema = groupPoolBySchema(pool.entities)
   const recordsRoot = resolve(siteDir, pool.dir)
 
+  // ⭐ A FOLDER NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego];
+  // `dataKeyTyping`): `records/articles/`, when no data schema has the name and the foundation types
+  // `articles` as `@/post`, holds `@/post` records — so they join that type's records, as a push
+  // sends them, and any query of `@/post` reads them, as a host answers one. ⛔ Until 2026-10-08 they
+  // stayed under `@/articles`: only a query named `articles` read them, and it carried `@/articles`
+  // on the payload where a push named `@/post`.
+  const typing = await recordTyping(siteDir, queriesConfig, poolBySchema)
+  for (const [ref, type] of typing) {
+    const held = poolBySchema.get(ref)
+    if (!held) continue
+    poolBySchema.delete(ref)
+    poolBySchema.set(type, [...(poolBySchema.get(type) || []), ...held])
+  }
+
   // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
   // from the foundation's source once for every query. A query with none compiles its
   // records as their files hold them.
-  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig))
+  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig, typing))
   const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
 
   const results = {}
@@ -1211,6 +1225,9 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     // be an empty `/data/<name>.json` standing in for a live source.
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const parsed = parseQueryConfig(name, config)
+    // A query that still names its folder (`@/articles`) is a query of the folder's type.
+    const folderRef = parsed.schema
+    if (parsed.schema && typing.has(parsed.schema)) parsed.schema = typing.get(parsed.schema)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder.placements
     parsed.folderRank = folderRank
@@ -1218,7 +1235,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
     parsed.references = references
     if (parsed.poolEntities.length === 0) {
-      const dirs = parsed.schema ? poolDirsForSchema(parsed.schema) : null
+      const dirs = folderRef ? poolDirsForSchema(folderRef) : null
       console.warn(
         `[query-processor] Query "${name}" matches no records — ` +
           (dirs
@@ -1240,12 +1257,12 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
  * its records are compiled as their files hold them, which is not the shape a
  * component receives from a host.
  */
-async function querySchemas(siteDir, queriesConfig) {
-  const refs = []
+async function querySchemas(siteDir, queriesConfig, typing = new Map()) {
+  const refs = [...typing.values()]
   for (const config of Object.values(queriesConfig)) {
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const ref = typeof config === 'string' ? config : config?.schema
-    if (typeof ref === 'string') refs.push(ref)
+    if (typeof ref === 'string' && !typing.has(ref)) refs.push(ref)
   }
   const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
   for (const { ref, message } of failures) {
@@ -1254,28 +1271,25 @@ async function querySchemas(siteDir, queriesConfig) {
         `their files hold them rather than as a component receives them: ${message}`
     )
   }
-  await typeByDataKey(siteDir, queriesConfig, schemas)
   return schemas
 }
 
 /**
- * ⭐ A QUERY NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego],
- * `uwx/data-key-types.js`). `articles:` with no `schema:` names `@/articles`; when no data schema
- * has that name while the foundation's section types declare `data: { articles: '@/post' }`, its
- * records are `@/post` records — a push sends them as such, and they are delivered as such here,
- * where they still live and are keyed by the name (`records/articles/`). Never for a schema the
- * query asked for explicitly: that one is the author's, and does not resolve. ⛔ Until 2026-09-27
- * this lane compiled them as if they had no data schema, while a push typed them.
+ * ⭐ WHICH FOLDERS HOLD RECORDS OF A DATA KEY'S TYPE (ruled 2026-09-25 [Diego]): `@/articles` →
+ * `@/post` — `dataKeyTyping`, the rule a push applies, asked only when the site has a folder or a
+ * query it could apply to: a name-defaulted ref, `@/<name>`. ⛔ Until 2026-10-08 this lane typed a
+ * query's RECORDS by aliasing its `@/<name>` to the type's schema, while its query and its folder
+ * kept the name.
  *
  * @param {string} siteDir
- * @param {Object} queriesConfig
- * @param {Object} schemas - resolved data schemas by ref; a typed query's ref is added to it
+ * @param {Object} queriesConfig - what the build compiles (`config.queries`)
+ * @param {Map<string, Array>} poolBySchema - the records, by the ref their folder names
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type
  */
-async function typeByDataKey(siteDir, queriesConfig, schemas) {
-  const untyped = Object.entries(queriesConfig).filter(
-    ([name, c]) => c && typeof c === 'object' && c.url === undefined && c.schema === `@/${name}` && !schemas[c.schema]
-  )
-  if (untyped.length === 0) return
+async function recordTyping(siteDir, queriesConfig, poolBySchema) {
+  const candidate = (ref) => typeof ref === 'string' && keyOfDefaultRef(ref) !== null
+  const queried = Object.values(queriesConfig).map((c) => (typeof c === 'string' ? c : c?.schema))
+  if (![...poolBySchema.keys(), ...queried].some(candidate)) return new Map()
   // `config.queries` carries no trace of whether its author wrote the schema; the declarations do.
   let declarations = {}
   try {
@@ -1283,17 +1297,11 @@ async function typeByDataKey(siteDir, queriesConfig, schemas) {
   } catch {
     // a declaration the build refuses is reported where the build reads it
   }
-  const pending = untyped.filter(([name]) => declarations[name]?.schemaExplicit !== true)
-  if (pending.length === 0) return
-  const keyTypes = dataKeyTypes(await foundationSections(siteDir))
-  const wanted = new Map()
-  for (const [name, c] of pending) {
-    const type = keyTypes.get(name)
-    if (type) wanted.set(c.schema, type)
+  try {
+    return await dataKeyTyping(siteDir, declarations)
+  } catch {
+    return new Map() // a foundation that does not read is reported by the build that reads it
   }
-  if (wanted.size === 0) return
-  const { schemas: types } = await resolveRecordSchemas(siteDir, wanted.values())
-  for (const [ref, type] of wanted) if (types[type]) schemas[ref] = types[type]
 }
 
 /**
@@ -1376,8 +1384,8 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
 
     // ⭐ TWO PAYLOADS FOR EVERY QUERY (ruled 2026-09-27 [Diego]):
     //   1. Each record WHOLE, as stored, at /data/<name>/<$name>.json — a key per section, the
-    //      brief's included — what a whole question answers: a parametric page's record for a
-    //      component that declares `'@x/y/*'`, and kit's `useWholeRecord`.
+    //      brief's included — what a whole question answers: a record for a component that
+    //      declares its key `whole: true`, and kit's `useWholeRecord`.
     //   2. The list at /data/<name>.json — each record's BRIEF, the brief's fields at the top —
     //      what `query: <name>` delivers everywhere else. ⛔ `deferred:`, which left fields of the
     //      brief out of it, was retired the same day [Diego].

package/src/uwx/data-key-types.js

@@ -7,8 +7,10 @@
 // records folder (`records/team/`). When no data schema has that name, but the foundation's
 // section types declare the data key of that name with a type — `data: { team: '@/member' }` in a
 // `meta.js` — the records ARE of that type: a push sends them as its entities, and the query names
-// it on the wire. ⛔ Until 2026-09-25 they were read as having no data schema at all and went out
-// as static files, although the one section that reads them declared what they are.
+// it on the wire; the static build names it on the payload and reads them as the type's records
+// (`site/queries-config.js::dataKeyTyping`, since 2026-10-08 — until then the payload named the query
+// `@/team`). ⛔ Until 2026-09-25 they were read as having no data schema at all and went out as
+// static files, although the one section that reads them declared what they are.
 //
 // ⚠️ THIS DECIDES ONLY WHICH DATA SCHEMA THE RECORDS BELONG TO. Where they live on disk, how the
 // site builds them and how their translations are keyed stay keyed by the name (`team`), as the

package/src/uwx/index.js

@@ -54,7 +54,8 @@ export {
   queriesYmlPath,
   QUERIES_YML_RELPATH,
 } from './queries-config.js'
-export { upsertYamlScalar, removeYamlScalar } from './yaml-upsert.js'
+// Edits to a YAML file an author wrote — the one editor; files are written through project-writer.js.
+export { editYamlText, setYamlKey, replaceInYamlList } from './yaml-edit.js'
 export { buildFolderEntity,
   collectFolderItemUuids,
   stampFolderItemUuids
@@ -87,6 +88,9 @@ export {
   sectionRecordToFile,
   pageSectionsToFiles,
   siteContentDocumentToProject,
+  // The file the author keeps a section in (`1-hero.md` holds `hero`) — what a section
+  // unit's path names on disk, for a push recording what it delivered.
+  existingSectionFile,
 } from './site-project.js'
 export {
   createTranslationCollector,
@@ -120,6 +124,8 @@ export {
 export {
   RUNTIME_KEYS,
   readServicesRequest,
+  unreadableServices,
+  refuseUnreadableServices,
   statedServices,
   heldServices,
   servicesFromDocument,

package/src/uwx/project-writer.js

@@ -22,6 +22,7 @@ import { canonicalJson, sameMarkdownDocument } from './same-content.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
 import { folderYmlPath } from '../site/records-config.js'
+import { editYamlText, YAML_DUMP_OPTS } from './yaml-edit.js'
 import { DECLARATION_KEYS } from '../site/fetch-shapes.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
@@ -45,9 +46,6 @@ export const DEFAULT_RESERVED_FRONTMATTER = new Set([
   // editor toggles it, so a pull must carry the store's value into the file (2026-09-28).
 ])
 
-// js-yaml dump options shared by every config write, so output is byte-stable.
-export const YAML_DUMP_OPTS = { lineWidth: -1, quotingType: "'", forceQuotes: false, noRefs: true }
-
 /**
  * Write `text` to `filePath` only when it differs from what's on disk, using a
  * tmp-file + rename so a reader never sees a half-written file. Creates the
@@ -216,10 +214,8 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
 // Shallow-merge `changes` into a YAML config file and write idempotently. A key
 // whose value is null/undefined is deleted; an object value is shallow-merged one
 // level deep (so partial `theme` / `build` updates don't drop sibling keys) unless
-// the key is in `replace`; any other value replaces. NOTE: this re-dumps the file,
-// so author comments/order are not preserved — acceptable for machine-owned
-// config, but comment-preserving merges for hand-authored config files are a
-// quality bar to revisit.
+// the key is in `replace`; any other value replaces. The file is edited, not
+// re-dumped: its comments and layout stay (`writeYamlIfChanged`).
 function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   const prior = loadYamlFile(filePath)
   const existing = isPlainObject(prior.value) ? { ...prior.value } : {}
@@ -240,23 +236,37 @@ function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   return writeYamlIfChanged(filePath, existing, prior)
 }
 
-// A YAML file, parsed — and whether there was one: a missing or unreadable file is never "unchanged".
+// A YAML file, parsed, with its text — and whether there was one: a missing file is never "unchanged".
+// ⛔ One that EXISTS and does not parse is refused, never read as missing: read as missing, the writer
+// replaced the author's whole file with only the keys it was writing (until 2026-10-07).
 function loadYamlFile(filePath) {
+  let text
   try {
-    return { value: yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) ?? {}, read: true }
+    text = readFileSync(filePath, 'utf8')
   } catch {
-    return { value: {}, read: false }
+    return { value: {}, read: false, text: null }
+  }
+  try {
+    return { value: yaml.load(text, YAML_OPTIONS) ?? {}, read: true, text }
+  } catch (err) {
+    throw new Error(`${filePath} is not YAML that can be read, so it was not written: ${err.message.split('\n')[0]}`)
   }
 }
 
-// ⭐ A FILE WHOSE MEANING WOULD NOT CHANGE IS LEFT AS ITS AUTHOR WROTE IT. Every writer here re-dumps the
-// whole file — its comments dropped, its strings re-quoted, its lists reflowed — so a pull that restated
-// a file rewrote it all the same. ⛔ Until 2026-09-26 a pull into the copy that pushed it re-dumped
-// `site.yml`, `theme.yml` and every `page.yml` (measured on the `international` template: every comment
-// in its `site.yml` gone, and nothing had changed).
+// ⭐ A FILE WHOSE MEANING WOULD NOT CHANGE IS LEFT AS ITS AUTHOR WROTE IT. ⛔ Until 2026-09-26 a pull into
+// the copy that pushed it re-dumped `site.yml`, `theme.yml` and every `page.yml` (measured on the
+// `international` template: every comment in its `site.yml` gone, and nothing had changed).
+//
+// ⭐ AND ONE THAT CHANGES IS EDITED, NOT RE-DUMPED (2026-10-07): only the entries that differ are
+// rewritten, and every comment, blank line and list the author wrote stays (`editYamlText`). ⛔ Until then
+// every writer here dumped the whole file — a pull that changed one key of `site.yml` left the Starter
+// template's 93 lines as 10, and a `pull --merge` conflicted on the whole commented header. The whole dump
+// remains for a file with nothing to keep (none yet, unreadable) and one the editor declines (an alias or a
+// `<<` merge key, or a result that would read differently).
 function writeYamlIfChanged(filePath, value, prior) {
   if (prior.read && canonicalJson(value) === canonicalJson(prior.value)) return 'unchanged'
-  return writeIfChanged(filePath, yaml.dump(value, YAML_DUMP_OPTS))
+  const edited = prior.read ? editYamlText(prior.text, prior.value, value, YAML_DUMP_OPTS) : null
+  return writeIfChanged(filePath, edited ?? yaml.dump(value, YAML_DUMP_OPTS))
 }
 
 const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
@@ -280,10 +290,10 @@ export function writeSiteConfig(siteRoot, config) {
 const SITE_CONFIG_WHOLE = Object.freeze([...DECLARATION_KEYS, 'services'])
 
 /**
- * Write a YAML object to a file (full dump, idempotent) — for machine-owned
+ * Write a YAML object to a file (idempotent) — for machine-owned
  * config the projector authors wholesale, e.g. a projected `page.yml`/`folder.yml`.
- * (Comment/unknown-key preservation is a later refinement; `site.yml`/
- * `collections.yml` use the merging writers instead.)
+ * An existing file is edited, not re-dumped — its comments stay (`writeYamlIfChanged`);
+ * `site.yml` and `queries.yml` use the merging writers.
  * @returns {'updated'|'unchanged'}
  */
 export function writeYamlFile(filePath, obj) {
@@ -296,7 +306,7 @@ export function writeYamlFile(filePath, obj) {
  * absent from `projected` is removed (the projector owns the managed set
  * wholesale); unknown keys keep their value and relative order. Idempotent.
  *
- * Same key-preserving (comment-dropping) bar as `writeSiteConfig` — for the
+ * Same key- and comment-preserving bar as `writeSiteConfig` — for the
  * hand-authored `page.yml`/`folder.yml`, whose author-added keys must survive a
  * pull rather than being clobbered by a full re-dump.
  *
@@ -323,7 +333,7 @@ export function writeMergedYaml(filePath, projected, managedKeys) {
 /**
  * Merge `queries` into `queries.yml` (shallow). Preserves queries not in the
  * incoming set; each incoming one is replaced wholesale. Same key-preserving
- * (comment-dropping) bar as `writeSiteConfig`.
+ * (and comment-preserving) bar as `writeSiteConfig`.
  *
  * ⛔ `queries.yml` IS THE MAP — there is no root key, so `queries` is passed bare.
  * The predecessor wrote `{ collections: {...} }` into `collections.yml`; handing

package/src/uwx/services-request.js

@@ -8,7 +8,7 @@
  *     exclude: { routes: [/legal] }           # an option the site's runtime reads
  *   submit: https://forms.example.com/f/abc   # an address: a provider the site brings
  *   tracking: { consent: required }
- *   api: { grade: pro }                       # a setting for the host's service
+ *   backend: { grade: pro }                   # a setting for the host's service
  * ```
  *
  * ⭐ ONE PLACE [Diego, 2026-10-06]. Until then the site's own provider and options
@@ -19,8 +19,8 @@
  * Each entry goes ONE place per lane, decided here and nowhere else:
  *
  *   - **a built site** reads it as its own config (`config.<name>` in the payload) —
- *     the switch, an address, the options. ⛔ For `api` only its switch and address:
- *     its settings are for the host that provisions it. Never a credential.
+ *     the switch, an address, the options. ⛔ For `backend` only its switch and
+ *     address: its settings are for the host that provisions it. Never a credential.
  *   - **a push** sends it as the request: ONE row per entry in the `services` Section,
  *     `{ name, enabled?: false, config? }`, whose `config` is the whole entry — an
  *     address, the options, the host's settings — never a credential. What reaches a
@@ -65,9 +65,27 @@ export const RUNTIME_KEYS = Object.freeze({
   submit: Object.freeze(['enabled', 'endpoint']),
   assistant: Object.freeze(['enabled', 'endpoint']),
   tracking: Object.freeze(['enabled', 'endpoint', 'emit', 'consent', 'scripts', 'flushIntervalMs', 'debug']),
-  api: Object.freeze(['enabled', 'endpoint'])
+  backend: Object.freeze(['enabled', 'endpoint'])
 })
 
+/**
+ * Services renamed, by their old name. The old name is refused wherever a service is
+ * named — an entry here, and a foundation's `uniweb.supports` — naming the new one.
+ *
+ * ⛔ No alias, and the reason is the runtime: a name no host offers resolves to
+ * nothing, so a site or a foundation still saying `api` would simply lose the service
+ * on every page, with nothing anywhere saying why. Here it stops where it is written.
+ *
+ * ⭐ `api` → `backend`, 2026-10-07 [Diego: "name the actual service, and not the
+ * interface of the service, which is a route named /api"]. The site's own backend is
+ * named for what it is; `/_api` stays the route it answers on, and `@uniweb/api` is
+ * named for that interface.
+ */
+export const RENAMED_SERVICES = Object.freeze({ api: 'backend' })
+
+/** `site.yml` keys renamed with a service — refused by the old name, like the services. */
+const RENAMED_SITE_KEYS = Object.freeze({ $devApi: '$devBackend' })
+
 /**
  * Services only a host provides, which a site never answers itself: no address, no
  * runtime part. A site does not declare its own record provider — a third-party
@@ -92,6 +110,106 @@ function stable(value) {
   )
 }
 
+/**
+ * YAML 1.1's words for a switch, which js-yaml — YAML 1.2 — reads as TEXT, and `true` /
+ * `false` written in quotes. ⛔ As text, `search: yes` was an address: the site's own
+ * search provider at `yes`, with the host's search asked OFF, while the CLI said
+ * "site.yml turns on search" (measured on 0.85.0, 2026-10-07 — F14).
+ */
+const SWITCH_WORDS = /^(y|yes|on|true|n|no|off|false)$/i
+const ON_WORDS = /^(y|yes|on|true)$/i
+
+/** What a value is, in words — for a message that says what was found. */
+function described(value) {
+  if (value === null || value === undefined) return 'empty'
+  if (Array.isArray(value)) return 'a list'
+  if (typeof value === 'string') return value.trim() ? `the text \`${value}\`` : 'empty'
+  return `\`${JSON.stringify(value)}\``
+}
+
+/** A switch written as a word: what it says, and what to write instead. */
+function switchWord(path, key, value) {
+  const on = ON_WORDS.test(value.trim())
+  return (
+    `\`${path}\` is the text \`${value}\`, not a switch — YAML reads yes, no, on and off as words. ` +
+    `Write \`${key}: ${on}\` to turn it ${on ? 'on' : 'off'}.`
+  )
+}
+
+/**
+ * What is wrong with one entry, or null when it is `true`, `false`, an address or a map —
+ * the one judgement both `readServicesRequest` and `refuseUnreadableServices` make.
+ */
+function entryProblem(name, value) {
+  if (RENAMED_SERVICES[name]) {
+    const now = RENAMED_SERVICES[name]
+    return (
+      `\`services.${name}\` is now \`services.${now}\` — the site's own backend is the \`${now}\` service. ` +
+      `Rename the entry; what it says stays. On a site you push, \`uniweb pull\` brings it renamed.`
+    )
+  }
+  if (typeof value === 'boolean') return null
+  if (typeof value === 'string') {
+    if (SWITCH_WORDS.test(value.trim())) return switchWord(`services.${name}`, name, value)
+    if (!value.trim()) return `\`services.${name}\` is empty — write true, false, an address, or a map.`
+    if (HOST_ONLY.has(name)) return `\`services.${name}\` has no address of its own — your host provides it. Write \`${name}: true\`.`
+    return null
+  }
+  if (!isMap(value)) return `\`services.${name}\` is true, false, an address, or a map — not ${described(value)}.`
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    return typeof value.enabled === 'string' && SWITCH_WORDS.test(value.enabled.trim())
+      ? switchWord(`services.${name}.enabled`, 'enabled', value.enabled)
+      : `\`services.${name}.enabled\` is true or false — not ${described(value.enabled)}.`
+  }
+  if (typeof value.endpoint === 'string' && SWITCH_WORDS.test(value.endpoint.trim())) {
+    return `\`services.${name}.endpoint\` is the text \`${value.endpoint}\`, not an address — an address is a URL or a path. To turn the service on, leave \`endpoint\` out.`
+  }
+  if (HOST_ONLY.has(name) && addressOf(value)) {
+    return `\`services.${name}\` has no address of its own — your host provides it. Remove \`endpoint\`.`
+  }
+  return null
+}
+
+/**
+ * Every entry of `site.yml::services` that neither a build nor a push can read, each said
+ * with its fix — [] when there is none.
+ *
+ * @param {*} declared - the raw `services:` value
+ * @returns {string[]}
+ */
+export function unreadableServices(declared) {
+  if (declared === undefined || declared === null) return []
+  if (!isMap(declared)) return ['`services:` is a map of service names — `services: { search: true }`.']
+  return Object.entries(declared)
+    .map(([name, value]) => entryProblem(name, value))
+    .filter(Boolean)
+}
+
+/**
+ * Stop on a `services:` entry neither lane can read — beside `refuseRetiredServiceKeys`,
+ * in the static build and in the push.
+ *
+ * ⛔ NOT "warn and ignore it". A push states every service the file lists and OFF for each
+ * one this copy holds that it does not (`statedServices`), so an entry it skipped turned
+ * that service off — `search: 7`, or `records: /_query`, switched off on the site under a
+ * warning that said "Ignoring it" (until 2026-10-07). And a word for a switch was not
+ * skipped but read as an address, which asks the host to leave its own off (F14).
+ *
+ * @param {object} siteYml
+ * @param {string} [where]
+ * @throws {Error} naming each entry and what to write
+ */
+export function refuseUnreadableServices(siteYml, where = 'site.yml') {
+  if (!isMap(siteYml)) return
+  const found = unreadableServices(siteYml.services)
+  if (!found.length) return
+  throw new Error(
+    found.length === 1
+      ? `[uniweb] ${where}: ${found[0]}`
+      : `[uniweb] ${where}: \`services:\` has entries that cannot be read:\n${found.map((f) => `  - ${f}`).join('\n')}`
+  )
+}
+
 /** The address an entry names, or null — a string, or a map's `endpoint`. */
 function addressOf(value) {
   if (typeof value === 'string') return value.trim() || null
@@ -132,12 +250,20 @@ function sayCredentials(name, found, warn) {
  */
 export function refuseRetiredServiceKeys(siteYml, where = 'site.yml') {
   if (!isMap(siteYml)) return
+  const renamed = Object.keys(RENAMED_SITE_KEYS).filter((k) => siteYml[k] !== undefined)
+  if (renamed.length) {
+    throw new Error(
+      `[uniweb] ${where}: ${renamed.map((k) => `\`${k}:\` is now \`${RENAMED_SITE_KEYS[k]}:\``).join(', ')} — ` +
+        "it names what answers the site's `backend` service in `uniweb dev`. Rename the key; its value stays."
+    )
+  }
   const found = RETIRED_SERVICE_KEYS.filter((k) => siteYml[k] !== undefined)
   if (!found.length) return
-  const lines = found.map((k) => `  ${k}: …`).join('\n')
+  // The block to move them into names each service as `services:` does now.
+  const lines = found.map((k) => `  ${RENAMED_SERVICES[k] || k}: …`).join('\n')
   const api = found.includes('api')
-    ? '\n  `api:` named the address a local mock answered on — in `uniweb dev`, `$devApi` now ' +
-      'supplies it. Asking your host for an app backend is `api: true` under `services:`.'
+    ? '\n  `api:` named the address a local mock answered on — in `uniweb dev`, `$devBackend` now ' +
+      "supplies it. Asking your host for the site's own backend is `backend: true` under `services:`."
     : ''
   throw new Error(
     `[uniweb] ${where}: ${found.map((k) => `\`${k}:\``).join(', ')} ` +
@@ -148,10 +274,10 @@ export function refuseRetiredServiceKeys(siteYml, where = 'site.yml') {
 
 /**
  * Services whose settings are never published: only the switch and the address reach
- * the site's config. `api`'s settings are for the host that provisions it (a grade,
+ * the site's config. `backend`'s settings are for the host that provisions it (a grade,
  * sign-in providers, billing) and no page reads them.
  */
-const UNPUBLISHED_SETTINGS = new Set(['api'])
+const UNPUBLISHED_SETTINGS = new Set(['backend'])
 
 /**
  * One entry → what the site's config carries: `false`, an address, or the entry's
@@ -217,6 +343,14 @@ export function readServicesRequest(declared, { warn = () => {} } = {}) {
   }
   const asks = []
   for (const [name, value] of Object.entries(declared)) {
+    // ⚠️ Skipped here for a caller that only reads; the build and the push stop on it
+    // first (`refuseUnreadableServices`), since a push would state a skipped one off.
+    // First, so a renamed service is skipped whatever its value — `true` included.
+    const problem = entryProblem(name, value)
+    if (problem) {
+      warn(`${problem} Ignoring \`${name}\`.`)
+      continue
+    }
     if (value === true) {
       asks.push({ name })
       continue
@@ -225,31 +359,18 @@ export function readServicesRequest(declared, { warn = () => {} } = {}) {
       asks.push({ name, enabled: false })
       continue
     }
-    if (typeof value !== 'string' && !isMap(value)) {
-      warn(`\`services.${name}\` is true, false, an address, or a map. Ignoring it.`)
-      continue
-    }
-    if (isMap(value) && value.enabled !== undefined && typeof value.enabled !== 'boolean') {
-      warn(`\`services.${name}.enabled\` is true or false. Ignoring \`${name}\`.`)
-      continue
-    }
     const address = addressOf(value)
-    if (typeof value === 'string' && !address) continue // an empty string asks nothing
-    if (address && HOST_ONLY.has(name)) {
-      warn(`\`services.${name}\` has no address of its own — your host provides it. Ignoring \`${name}\`.`)
-      continue
-    }
     const { enabled, ...entry } = isMap(value) ? value : { endpoint: address }
     const { value: config, found } = withoutCredentials(entry)
     sayCredentials(name, found, warn)
     if (address) {
       config.endpoint = address
-      // ⚠️ Said for `api` because its old spelling invites it: `api: /_api` was where a
-      // local mock answered, and under `services:` an address turns the host's off.
-      if (name === 'api') {
+      // ⚠️ Said for `backend` because its old spelling invites it: `api: /_api` was where
+      // a local mock answered, and under `services:` an address turns the host's off.
+      if (name === 'backend') {
         warn(
-          "`services.api` is an address: it asks your host to leave its own `api` off, so the site uses yours. " +
-            "For your host's, write `api: true`; in `uniweb dev`, `$devApi` answers it."
+          "`services.backend` is an address: it asks your host to leave its own `backend` off, so the site uses yours. " +
+            "For your host's, write `backend: true`; in `uniweb dev`, `$devBackend` answers it."
         )
       }
     }

package/src/uwx/site-diff.js

@@ -96,8 +96,12 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
 export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
-      // The projector's own file rule, so a unit's path here is the file it is
-      // written to — including an app-created section named from its `$uuid`.
+      // The projector's own file rule — including an app-created section named from its
+      // `$uuid`. ⚠️ The path NAMES the unit by its id; it is not always the author's file:
+      // a pull writes into an existing `1-about.md` or `@about.md` in place
+      // (`existingSectionFile`), so a reader mapping a unit to disk looks it up there.
+      // (This said "a unit's path here is the file it is written to" until 2026-10-07,
+      // and a push recorded no file for a numbered section.)
       const base = sectionFileBase(record)
       if (base) cb(`${dir}/${base}.md`, record, 'section')
       walkSections(record.$children, dir)