@uniweb/build 0.78.0 → 0.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/projections": "^0.7.14",
+    "@uniweb/projections": "^0.7.15",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/schemas": "^0.13.0",
     "@uniweb/content-reader": "^1.2.8",
-    "@uniweb/schemas": "^0.12.0",
     "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.29.2"
+    "@uniweb/runtime": "^0.29.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.37.2",
-    "@uniweb/runtime": "^0.29.2"
+    "@uniweb/runtime": "^0.29.3",
+    "@uniweb/core": "^0.38.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev/api-mount.js

@@ -5,7 +5,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 
 /**
- * Where `uniweb dev` answers the site's `api` service when `$devApi` names a handler.
+ * Where `uniweb dev` answers the site's `backend` service when `$devBackend` names a handler.
  * The dev server is the host here, so the address is its own.
  */
 export const DEV_API_ADDRESS = '/_api'
@@ -16,22 +16,24 @@ export const DEV_API_ADDRESS = '/_api'
  * A site that talks to a backend needs one running to be developed against, and
  * making that a live deployment is slow, costs money, and puts a shared database
  * behind a developer's experiments. So a site may name a **local handler**, and in
- * `uniweb dev` the dev server answers the site's `api` service with it:
+ * `uniweb dev` the dev server answers the site's `backend` service with it:
  *
  * ```yaml
  * # site.yml
  * services:
- *   api: true                # ask your host for an app backend (in production)
- * $devApi: ./mock/api.js     # what answers it in `uniweb dev`, at /_api
+ *   backend: true              # ask your host for it (in production)
+ * $devBackend: ./mock/api.js   # what answers it in `uniweb dev`, at /_api
  * ```
  *
  * ⭐ THE DEV SERVER SUPPLIES THE ADDRESS [Diego, 2026-10-06]. In `uniweb dev` it is
  * the host, so where it answers is its own to choose — `DEV_API_ADDRESS` — and the
- * plugin puts that address in the dev payload's `config.api`, the site tier
+ * plugin puts that address in the dev payload's `config.backend`, the site tier
  * `resolveService` reads when no host speaks. ⛔ *Until then the site wrote it, as a
  * top-level `api: /_api` "the same in development and in production" — an address
  * that, under `services:`, would read as "the site brings its own backend" and ask the
- * host to turn its own off.*
+ * host to turn its own off.* ⛔ *And until 2026-10-07 the service was `api` and this
+ * key `$devApi`; both are refused by those names now — `services.api` by
+ * `refuseUnreadableServices`, `$devApi` by `refuseRetiredServiceKeys`.*
  *
  * ```js
  * // mock/api.js — default-export a fetch handler
@@ -50,9 +52,9 @@ export const DEV_API_ADDRESS = '/_api'
  *
  * ## ⛔ Development only, and it cannot leak
  *
- * `$devApi` is read by the dev plugin and by nothing else: no build reads it, no
+ * `$devBackend` is read by the dev plugin and by nothing else: no build reads it, no
  * `info` key carries it, and only the dev server's payload names its address. What
- * answers the site's `api` service locally is a fact about one machine.
+ * answers the site's `backend` service locally is a fact about one machine.
  *
  * ⚠️ **Same-origin on purpose.** Mounting inside the dev server means cookies and
  * `credentials: 'same-origin'` behave as they do in production, where a site's app
@@ -87,7 +89,7 @@ export function mountDevApi(server, { root }) {
     return null
   }
 
-  const spec = site.$devApi
+  const spec = site.$devBackend
   if (!spec) return null
   const mount = DEV_API_ADDRESS
 

package/src/foundation/derive-supports.js

@@ -75,9 +75,10 @@
  *
  * ⚠️ `@uniweb/api` deliberately needs no entry: it calls
  * `resolveService(website, SERVICE_NAME)` against a module-level `const`, which
- * `readModuleConsts` resolves. Without that resolution `api` would be both
+ * `readModuleConsts` resolves. Without that resolution `backend` would be both
  * missed *and* counted as blindness, marking every foundation that uses it
- * unknowable.
+ * unknowable. ⛔ *The constant was `api` until 2026-10-07, so a foundation built
+ * against an earlier `@uniweb/api` derives `api` — a service no host offers now.*
  *
  * ## Why the AST rather than a regex
  *

package/src/resolve-data-schema.js

@@ -161,7 +161,8 @@ export function collectSchemaRefs(components, foundationData = null) {
   const readData = (data) => {
     if (!data || typeof data !== 'object' || data === false) return
     for (const binding of Object.values(data)) {
-      // `'@std/article/*'` asks for whole records of `@std/article` — the ref is what precedes it.
+      // A ref, short or long (`{ schema, single, whole }`) — the flags change nothing about which
+      // schema the key is typed by.
       const { ref } = dataRefOf(binding)
       if (ref) refs.add(ref)
     }

package/src/runtime-schema.js

@@ -5,8 +5,9 @@
  * reads to render, and nothing else:
  *
  * - background: 'self' when component handles its own background
- * - data: { <key>: <schema ref> | null } — every `content.data` key the component
- *     declares, in order, with its schema ref (null for an inline shape)
+ * - data: { <key>: <schema ref> | { schema, single?, whole? } | null } — every `content.data`
+ *     key the component declares, in order, with its schema ref and the flags set on it (null for
+ *     an inline shape)
  * - vars: { <name>: { default? } } — the CSS variables the component declares
  * - defaults: param default values
  * - context: static capabilities for cross-block coordination
@@ -34,17 +35,34 @@
  */
 
 import { lowerData } from '@uniweb/schemas/content'
+import { schemaDeclarationOf } from '@uniweb/schemas/foundation'
 
 /**
- * A `data:` entry's schema ref — a ref string, or `{ schema }` — or null for an inline
- * shape, which names no schema and is filled only under its own key.
+ * A `data:` entry as the runtime reads it: its schema ref, with the flags set on it — or null for an
+ * inline shape, which names no schema and is filled only under its own key.
  *
- * @param {string|Object} value
- * @returns {string|null}
+ * ⭐ Two flags, independent (ruled 2026-10-07 [Diego]): `single` — one record, not a list — and
+ * `whole` — each record as stored, not its brief.
+ * Lean on purpose: the bare ref when neither is set, which is most keys, and only a flag that is set.
+ * ⛔ Until 2026-10-07 this wrote the ref alone, so `{ schema, whole: true }` lost its flag here and
+ * only the `'…/*'` spelling, now retired, reached the runtime.
+ *
+ * @param {string} key - the key, for a refusal
+ * @param {*} value - its value, as authored
+ * @returns {string|{ schema: string, single?: true, whole?: true }|null}
+ * @throws {Error} for a retired or malformed declaration (`schemaDeclarationOf`)
  */
-function dataRef(value) {
-  if (typeof value === 'string') return value || null
-  return value && typeof value === 'object' && typeof value.schema === 'string' && value.schema ? value.schema : null
+function leanDataValue(key, value) {
+  let declaration
+  try {
+    declaration = schemaDeclarationOf(value)
+  } catch (err) {
+    throw new Error(`[uniweb] Invalid 'data.${key}': ${err.message}`)
+  }
+  if (!declaration || !declaration.schema) return null
+  const { schema, single, whole } = declaration
+  if (!single && !whole) return schema
+  return { schema, ...(single ? { single: true } : {}), ...(whole ? { whole: true } : {}) }
 }
 
 /**
@@ -148,7 +166,7 @@ export function extractRuntimeSchema(fullMeta) {
         )
       }
       runtime.data = runtime.data || {}
-      runtime.data[key] = dataRef(value)
+      runtime.data[key] = leanDataValue(key, value)
     }
   } else if (data !== undefined) {
     throw new Error(
@@ -337,12 +355,12 @@ function leanVars(vars) {
   return Object.keys(out).length > 0 ? out : null
 }
 
-/** A foundation's `data:` as a section type's lean `data` is: each key → its schema ref, or null. */
+/** A foundation's `data:` as a section type's lean `data` is: each key → its ref and flags, or null. */
 function leanDataKeys(data) {
   const lowered = lowerData(data)
   if (!lowered || typeof lowered !== 'object' || Array.isArray(lowered)) return null
   const out = {}
-  for (const [key, value] of Object.entries(lowered)) out[key] = dataRef(value)
+  for (const [key, value] of Object.entries(lowered)) out[key] = leanDataValue(key, value)
   return Object.keys(out).length > 0 ? out : null
 }
 

package/src/schema.js

@@ -18,7 +18,8 @@ import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { describeChildren, describeVisuals, lowerChildren } from '@uniweb/schemas/component'
 import { describeContent, lowerData } from '@uniweb/schemas/content'
-import { normalizeData } from '@uniweb/schemas/foundation'
+import { normalizeData, schemaDeclarationOf } from '@uniweb/schemas/foundation'
+import { rootListSection } from '@uniweb/schemas/conform'
 import { SECTION_PARAMS, SECTION_KEYS } from '@uniweb/schemas/section'
 import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
@@ -26,6 +27,7 @@ import {
   deriveRecordsSupport,
   unnameableIn,
 } from './foundation/derive-supports.js'
+import { RENAMED_SERVICES } from './uwx/services-request.js'
 import { foundationNameOf, splitFoundationName } from './foundation-name.js'
 import { resolveFoundationSrcDir } from './utils/foundation-source-root.js'
 
@@ -635,12 +637,67 @@ function buildComponentEntry(name, relativePath, meta) {
   else delete entry.children
 
   if (meta.data !== undefined) entry.data = lowerData(meta.data)
+  refuseDataDeclarations(`${name} (meta.js)`, entry.data)
 
   const problems = [...content.problems, ...describeChildren(meta).problems]
   if (problems.length > 0) loweringProblems.set(entry, problems)
   return entry
 }
 
+/**
+ * Refuse a `data:` key typed by a schema that is not written as one: the retired `/*` suffix, a
+ * property of the long form other than `schema`, `single` and `whole`, or a flag that is not a
+ * boolean (`schemaDeclarationOf`; ruled 2026-10-07 [Diego]). A refusal, not a warning: the runtime would
+ * read a mistyped flag as absent, and deliver a list where the author asked for one record.
+ *
+ * @param {string} owner - who declares it, for the message
+ * @param {*} data - a `data:` map, lowered
+ */
+function refuseDataDeclarations(owner, data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return
+  for (const [key, value] of Object.entries(data)) {
+    try {
+      schemaDeclarationOf(value)
+    } catch (err) {
+      throw new Error(`[uniweb] ${owner}: data.${key}: ${err.message}`)
+    }
+  }
+}
+
+/**
+ * Refuse `single` or `whole` on a key whose schema is a LIST — `@std/nav`, `@std/form`: a schema
+ * whose root is one list section describes the key's whole value, so the key holds that list, and
+ * neither one record of it nor a record as stored means anything. Checked once the schemas resolve.
+ *
+ * @param {Array<[string, *]>} owners - `[who, data:]` pairs
+ * @param {Object} dataSchemas - normalized schemas by ref
+ * @param {string} srcDir - to resolve a ref no binding brought in (a layout's)
+ */
+async function refuseFlagsOnListSchemas(owners, dataSchemas, srcDir) {
+  for (const [owner, data] of owners) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) continue
+    for (const [key, value] of Object.entries(data)) {
+      const declaration = schemaDeclarationOf(value)
+      if (!declaration || (!declaration.single && !declaration.whole)) continue
+      let schema = dataSchemas[declaration.schema]
+      if (!schema) {
+        try {
+          schema = (await buildDataSchemaMap([declaration.schema], { srcDir }))[declaration.schema]
+        } catch {
+          schema = null // an unresolvable ref is reported where refs resolve
+        }
+      }
+      if (schema && rootListSection(schema)) {
+        const flags = ['single', 'whole'].filter((flag) => declaration[flag]).map((flag) => `\`${flag}\``).join(' and ')
+        throw new Error(
+          `[uniweb] ${owner}: data.${key}: ${declaration.schema} is a list — its key holds that list, so ${flags} ` +
+            `does not apply. Write data.${key}: '${declaration.schema}'.`
+        )
+      }
+    }
+  }
+}
+
 /** `content: {}` or `content: []` — the component's way of saying it takes no content. */
 function declaresNoContent(content) {
   if (Array.isArray(content)) return content.length === 0
@@ -954,6 +1011,29 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
   return sections
 }
 
+/**
+ * Stop on a service `uniweb.supports` names by its old name (`RENAMED_SERVICES`), as
+ * `site.yml::services` does. A foundation claiming `api` claims a service no host offers
+ * now — and the build derives `backend` from the code itself, through kit's and
+ * `@uniweb/api`'s literals, so a renamed claim could only ever disagree with it.
+ *
+ * ⛔ Before the dev-rebuild bail, like `reportSupports`' warning: dev is where the
+ * developer is working.
+ *
+ * @param {string} srcDir
+ * @param {string[]|undefined} authored - normalized `uniweb.supports`
+ * @throws {Error} naming each old name and the new one
+ */
+function refuseRenamedSupports(srcDir, authored) {
+  const renamed = (authored || []).filter((s) => RENAMED_SERVICES[s])
+  if (!renamed.length) return
+  throw new Error(
+    `${srcDir}/package.json: \`uniweb.supports\` names ${renamed.map((s) => `\`${s}\``).join(', ')}, which is now ` +
+      `${renamed.map((s) => `\`${RENAMED_SERVICES[s]}\``).join(', ')} — the site's own backend is the \`backend\` ` +
+      'service. Rename it in package.json.',
+  )
+}
+
 /**
  * Say what the derivation added, at the one moment the developer is looking.
  *
@@ -1138,6 +1218,8 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
   // Load configuration from foundation.js
   const foundationConfig = await loadFoundationConfig(srcDir)
 
+  refuseDataDeclarations('the foundation (main.js)', lowerData(foundationConfig.data))
+
   // Discover section types
   const components = await discoverComponents(srcDir, sectionPaths)
   reportPlacementDeclarations(components)
@@ -1154,6 +1236,15 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Discover layouts from src/layouts/
   const layouts = await discoverLayoutsInPath(srcDir)
+  await refuseFlagsOnListSchemas(
+    [
+      ...Object.entries(components).map(([name, entry]) => [`${name} (meta.js)`, entry?.data]),
+      ...Object.entries(layouts).map(([name, entry]) => [`layout ${name} (meta.js)`, entry?.data]),
+      ['the foundation (main.js)', lowerData(foundationConfig.data)],
+    ],
+    dataSchemas,
+    srcDir,
+  )
   reportUnregistrableData(components, layouts, foundationConfig)
 
   // Determine extension role
@@ -1188,6 +1279,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
   // `supports` differs from the one a real build produces is a trap rather than a
   // convenience — the artifact would disagree with itself depending on which
   // command wrote it. One rule: the derivation runs on a real build.
+  refuseRenamedSupports(srcDir, identity.supports)
   const derived = derivedSupports && {
     ...derivedSupports,
     services: deriveRecordsSupport(components, foundationConfig.data)

package/src/site/content-collector.js

@@ -41,7 +41,7 @@ import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig
 import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { parseGrid } from '@uniweb/schemas/grid'
-import { runtimeServicesConfig, refuseRetiredServiceKeys } from '../uwx/services-request.js'
+import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServices } from '../uwx/services-request.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -2503,6 +2503,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))
   refuseRetiredServiceKeys(siteConfig, configFile)
+  refuseUnreadableServices(siteConfig, configFile)
 
   // Queries are declared in TWO files — `site.yml::queries` and `queries.yml`,
   // the latter winning per key — and resolving them is one question with one

package/src/site/deploy-config-writer.js

@@ -7,8 +7,10 @@
  * must not destroy a developer's comments on the targets:/saveDeploys:
  * regions of the file.
  *
- * This is the only place in @uniweb/build that depends on `yaml`. The
- * loader (deploy-config.js) stays on js-yaml for read-only ingestion.
+ * The loader (deploy-config.js) stays on js-yaml for read-only ingestion.
+ * ⚠️ This read "the only place in @uniweb/build that depends on `yaml`" until
+ * 2026-10-07; the pull's config writers locate entries with it too
+ * (`uwx/yaml-edit.js::editYamlText`), and print with js-yaml.
  *
  * `saveDeploys: false` (or `--no-save`) makes this a no-op; otherwise it
  * touches ONLY deploys.<targetName> — plus targets.<targetName> when the file has no

package/src/site/plugin.js

@@ -655,16 +655,16 @@ export function siteContentPlugin(options = {}) {
   }
 
   let siteContent = null
-  // Where `uniweb dev` answers the site's `api` service with `$devApi`'s handler — set
+  // Where `uniweb dev` answers the site's `backend` service with `$devBackend`'s handler — set
   // in `configureServer`, so never in a build.
   let devApiAddress = null
   /**
-   * The dev payload names `$devApi`'s address as the site's `api` service: the site
+   * The dev payload names `$devBackend`'s address as the site's `backend` service: the site
    * tier, which `resolveService` reads when no host speaks. A build never gets here
    * with one.
    */
   const withDevApi = (content) => {
-    if (devApiAddress && content?.config) content.config.api = devApiAddress
+    if (devApiAddress && content?.config) content.config.backend = devApiAddress
     return content
   }
   // What each section type declares its data blocks are — read once per collection of the site.
@@ -1009,10 +1009,10 @@ export function siteContentPlugin(options = {}) {
     configureServer(devServer) {
       server = devServer
 
-      // A site's own backend, answered locally in development. `site.yml::$devApi`
+      // A site's own backend, answered locally in development. `site.yml::$devBackend`
       // names a module that default-exports a fetch handler; the dev server mounts it
       // at an address of its own and names that address in the payload it serves
-      // (`withDevApi`), so the site's `api` service resolves to it.
+      // (`withDevApi`), so the site's `backend` service resolves to it.
       // ⚠️ Synchronous on purpose — see mountDevApi. An await here and the
       // middleware lands after Vite's SPA fallback, which answers the API with
       // index.html and says nothing about why.

package/src/site/query-processor.js

@@ -1376,8 +1376,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/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
@@ -120,6 +121,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