@uniweb/build 0.77.0 → 0.79.0

package/src/uwx/shown-records.js

@@ -0,0 +1,52 @@
+/**
+ * The queries whose records a site's pages SHOW live — what the `records` service is for.
+ *
+ * ⭐ `records` is the live delivery of records to a published site, nothing else
+ * [Diego, 2026-10-07: "syncing records is unrelated to `records` being on/off. The
+ * service is the live delivery of records to published site"]. So what decides whether a
+ * site needs it is what its published pages fetch — never whether it has records to sync.
+ * A query counts when a page, a section or the site fetches it, and its records have a
+ * data schema (the declaration names one) and come from the site's own folder (no `url:`).
+ * A schema-less query's records are delivered as static files, which `records` does not
+ * touch; an external query is fetched from its own address.
+ *
+ * @module
+ */
+
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * @param {object} doc - a site-content document, as a push sends it
+ * @returns {string[]} the query names, sorted
+ */
+export function recordQueriesShown(doc) {
+  const fetched = new Set()
+  const take = (fetch) => {
+    for (const one of [fetch].flat()) if (isMap(one) && typeof one.query === 'string' && one.query) fetched.add(one.query)
+  }
+  const walkSections = (sections) => {
+    for (const section of Array.isArray(sections) ? sections : []) {
+      take(section?.params?.fetch)
+      take(section?.fetch)
+      walkSections(section?.$children)
+    }
+  }
+  const walkPages = (pages) => {
+    for (const page of Array.isArray(pages) ? pages : []) {
+      take(page?.fetch)
+      walkSections(page?.page_sections)
+      walkPages(page?.$children)
+    }
+  }
+  take(doc?.settings?.fetch)
+  walkPages(doc?.pages)
+  walkSections(doc?.layout_sections)
+  const live = new Set()
+  for (const query of Array.isArray(doc?.queries) ? doc.queries : []) {
+    if (!isMap(query) || typeof query.name !== 'string') continue
+    if (typeof query.schema !== 'string' || !query.schema) continue
+    if (isMap(query.source) && query.source.url !== undefined) continue
+    live.add(query.name)
+  }
+  return [...fetched].filter((name) => live.has(name)).sort()
+}

package/src/uwx/site-diff.js

@@ -321,3 +321,50 @@ export function collectQueryUuids(doc) {
   }
   return out
 }
+
+// The Sections whose items are matched by a field of their own, and that field — how
+// the backend matches them too. `extensions` has no declared key yet; its `ref` or
+// `url` is what the file names it by.
+const KEYED_SECTIONS = {
+  queries: (item) => item?.name,
+  services: (item) => item?.name,
+  extensions: (item) => item?.ref || item?.url
+}
+
+/**
+ * Every item of a site-content document, under a key that names it the same way in OUR
+ * document and in the BACKEND's, so the two can be paired item by item.
+ *
+ * - units — `site.yml` (the `info` item), pages, page sections and layout sections —
+ *   by the path the projector writes them to (`unit:<path>`), each its OWN content, as
+ *   `collectSiteUnits` keys them;
+ * - `settings`, one item, by its Section;
+ * - `queries`, `services` and `extensions` by the field each is matched by
+ *   (`queries:<name>`, …).
+ *
+ * ⛔ `secrets` is left out on purpose: a push never deletes a secret by leaving it out,
+ * and its values are set in the app, so no version of one is ever kept or sent.
+ * A Section this does not know is left out too — an item that cannot be paired is
+ * never taken as seen.
+ *
+ * @returns {Map<string, { uuid: string|null, record: object }>}
+ */
+export function siteItemsByKey(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+  const out = new Map()
+  const uuidOf = (record) => (typeof record?.$uuid === 'string' && record.$uuid ? record.$uuid : null)
+  const units = collectSiteUnits(doc, sourceLocale)
+  walkSiteUnits(doc, (path, record) => {
+    if (!out.has(`unit:${path}`)) out.set(`unit:${path}`, { uuid: uuidOf(record), record: units.get(path) })
+  }, sourceLocale)
+  if (doc?.settings && typeof doc.settings === 'object' && !Array.isArray(doc.settings)) {
+    out.set('settings', { uuid: uuidOf(doc.settings), record: doc.settings })
+  }
+  for (const [section, keyOf] of Object.entries(KEYED_SECTIONS)) {
+    for (const item of Array.isArray(doc?.[section]) ? doc[section] : []) {
+      const key = keyOf(item)
+      if (typeof key !== 'string' || !key || out.has(`${section}:${key}`)) continue
+      out.set(`${section}:${key}`, { uuid: uuidOf(item), record: item })
+    }
+  }
+  return out
+}

package/src/uwx/site-project.js

@@ -36,7 +36,7 @@ import { foldOpenGraph } from './open-graph.js'
 import { join, relative, extname, basename, dirname } from 'node:path'
 import { restoreAssetRefs } from './asset-map.js'
 import { readBackendState, updateBackendState } from './sync-store.js'
-import { servicesRequestFromRows } from './services-request.js'
+import { servicesFromDocument, heldServices } from './services-request.js'
 import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
@@ -56,7 +56,6 @@ import { siteContentDirs } from './site-dirs.js'
 import { layoutAreaRoute } from '../site/layout-folder.js'
 import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
-import { upsertYamlScalar } from './yaml-upsert.js'
 
 // The pull-side identity index: a per-clone, GITIGNORED `uuid → relative path`
 // map under `.uniweb/`, the home for the backend's per-item identity so that
@@ -124,33 +123,15 @@ const INFO_TO_SITE_YML = {
   // Publish intent — verbatim both ways, dangling codes included (they carry
   // the preserved publish intent of a temporarily-undeclared language).
   favicon: 'favicon',
-  // Safe to project back because nothing STAMPS it: `submit` is authored-only,
-  // so a pull can never launder a deploy-derived value into authored config the
-  // way a key carried by both would. A host-supplied destination is resolved at
-  // render time and never enters `info`.
-  // Authored-only, like `submit` above — a host's assistant endpoint is offered
-  // through `config.services` and resolved at render time, so it never enters
-  // `info` and a pull cannot launder it into authored config.
-  //
-  // ⚠️ Credential-shaped keys are STRIPPED ON PUSH (`stripCredentials`), so the
-  // backend never stores one and it cannot come back. What that does to the
-  // author's file depends on which direction they are pulling into, and the two
-  // differ — ⛔ this comment asserted the wrong one until it was run:
-  //
-  //   - `pull` over an EXISTING site.yml — the local `apiKey` SURVIVES.
-  //     `mergeYamlConfig` spreads one level (`{...existing[key], ...value}`), so
-  //     the projected `{endpoint, …}` merges over the local block and nothing
-  //     removes a key the document does not carry.
-  //   - `clone` into a fresh directory — no local block exists, so the file is
-  //     written from the document alone and has no `apiKey`.
-  //
-  // Both are correct: a pull does not silently delete something the author
-  // typed, and the push already warned them. The security property is upheld at
-  // the push, not by the pull. Measured end-to-end against a live uniwebd —
-  // every unit test passed before and after, so only a real push touched it.
-  // Authored-only, like `submit` and `assistant`: a host's tracking endpoint is
-  // offered through `config.services.tracking` and resolved at render, so it
-  // never enters `info` and a pull cannot launder it into authored config.
+  // ⛔ `submit` / `assistant` / `tracking` are not `info` keys: they left it for the
+  // `settings` Section on 2026-09-09, and on 2026-10-06 left that for each service's
+  // row — a pull writes `site.yml::services` from the rows (`servicesFromDocument`).
+  // Two behaviours measured while they were here still hold, now in
+  // `keepCredentials`: a credential is stripped on push and a pull over an existing
+  // file keeps the author's (a `clone` into a fresh directory has none to keep) — a
+  // pull does not silently delete what the author typed, and the push already warned
+  // them; and a host's endpoint never enters the record, so a pull cannot launder it
+  // into authored config.
   // ⛔ The site's declaration is not verbatim — see the explicit `settings.fetch`
   // branch below: it projects to `site.yml::query` or `site.yml::fetch`.
   template: 'template',
@@ -200,14 +181,12 @@ const SETTINGS_TO_SITE_YML = {
   paths: 'paths',
   seo: 'seo',
   layout: 'layout',
-  // Authored-only service declarations: nothing STAMPS them, so a pull cannot
-  // launder a host-supplied endpoint into authored config. A host's own address is
+  // ⛔ `search` / `submit` / `assistant` / `tracking` are not here: each service rides
+  // its row in the `services` Section, whole, and a pull writes it into
+  // `site.yml::services` (`servicesFromDocument`, below). They were top-level keys
+  // until 2026-10-06 and `settings` keys until that evening. A host's own address is
   // offered through `config.services` and resolved at render, never entering the
-  // stored record.
-  search: 'search',
-  submit: 'submit',
-  assistant: 'assistant',
-  tracking: 'tracking',
+  // stored record, so a pull cannot launder it into authored config.
   agents: 'agents',
 }
 
@@ -310,30 +289,36 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 
-  // services[] → site.yml::services, and the same rows → sync.json as the record.
+  // services → site.yml::services, one entry per service; which services this copy
+  // now holds → sync.json.
   //
-  // ⭐ `site.yml` TAKES WHAT WAS DECIDED [Diego, 2026-10-06: "pull writes it"]. The
-  // stored list is the site's settled request, so the author's map becomes it, whole: a
-  // row is `true`, `false`, or its settings (`servicesRequestFromRows`). An empty list
-  // removes the key; a document with no `services` Section writes nothing.
+  // ⭐ `site.yml` TAKES WHAT WAS DECIDED [Diego, 2026-10-06: "pull writes it"]. Each
+  // entry is its row in the `services` Section — the whole entry in its `config`
+  // (`servicesFromDocument`) — except an off service with no settings, written only
+  // where the file already names it [Diego, 2026-10-07]. The map is written whole,
+  // keeping only the credentials an author typed, which a push never sends; a document
+  // with no Section writes nothing. The retired top-level keys go, so a pulled file
+  // builds.
   //
-  // ⭐ The record goes to `sync.json`, under this backend: the rows as the site holds
-  // them — the last state both sides agreed on, which push and publish compare the file
-  // against (`reconcileServices`). `$id` is dropped, being derived; everything else rides
-  // VERBATIM, `config` included — it is opaque, per-service and will grow, and the next
-  // push sends the stored rows as its base. `secrets` likewise: an inventory of names
-  // whose values are set in the app. `[]` is written as `[]`: "the site holds no rows" is
-  // a state a pull must be able to deliver.
-  // ⛔ The record needs a backend: with none there is nowhere coherent to file it.
+  // ⭐ `sync.json` takes, under this backend, the services this copy now HOLDS —
+  // `{ name: $uuid }`, every row the site has, written to the file or not
+  // (`heldServices`). A push states each one the file does not list as off, so the site
+  // keeps what it has. `secrets` is an inventory of names whose values are set in the
+  // app, `$id` dropped. ⛔ *Until 2026-10-07 `services` held the rows themselves, the
+  // record a push compared the file against, with `servicesNamed` beside it.*
+  // ⛔ What is held needs a backend: with none there is nowhere coherent to file it.
   if (Array.isArray(document?.services)) {
-    siteChanges.services = servicesRequestFromRows(document.services)
+    siteChanges.services = servicesFromDocument({
+      rows: document.services,
+      local: readAuthoredYaml(join(siteRoot, 'site.yml'))?.services
+    })
+    for (const retired of ['search', 'submit', 'assistant', 'tracking', 'api']) siteChanges[retired] = null
   }
   if (backend) {
     const provisioned = {}
-    for (const section of ['services', 'secrets']) {
-      const records = document?.[section]
-      if (!Array.isArray(records)) continue
-      provisioned[section] = records.map(({ $id: _id, ...fields }) => fields)
+    if (Array.isArray(document?.services)) provisioned.services = heldServices({ written: document.services })
+    if (Array.isArray(document?.secrets)) {
+      provisioned.secrets = document.secrets.map(({ $id: _id, ...fields }) => fields)
     }
     if (Object.keys(provisioned).length) {
       updateBackendState(siteRoot, backend, provisioned)
@@ -1169,7 +1154,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
       const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
       // A list that names the homepage first beats `index:`, so it opens with `...` instead.
       if (listed && listed.before.length > 0) root.write(['...', ...root.pages.filter((e) => e !== '...')])
-      upsertYamlScalar(join(siteRoot, 'site.yml'), 'index', ctx.homepage)
+      writeSiteConfig(siteRoot, { index: ctx.homepage })
     }
   }
   projectLayout(document?.layout_sections, layoutBaseDir, report, prune, ctx)

package/src/uwx/site.js

@@ -80,8 +80,12 @@ import { resolveLocaleList } from '../i18n/locales.js'
 import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { splitOpenGraph, openGraphValue, seoBesideOpenGraph } from './open-graph.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
-import { readServicesRequest, mergeServiceRows } from './services-request.js'
-import { upsertYamlScalar } from './yaml-upsert.js'
+import {
+  readServicesRequest,
+  statedServices,
+  refuseRetiredServiceKeys,
+  refuseUnreadableServices
+} from './services-request.js'
 import { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { siteContentDirs } from './site-dirs.js'
@@ -103,46 +107,6 @@ function scalarString(value) {
   return undefined
 }
 
-// Credential-shaped keys, mirroring the set the delivery edge strips on the
-// reading side. Deliberately the SAME list rather than a stricter one, so the
-// two guards are visibly twins and a key added to one is obviously owed to the
-// other.
-const CREDENTIAL_KEYS = ['apiKey', 'api_key', 'key', 'token', 'secret']
-
-/**
- * Drop credential-shaped keys out of an authored service block.
- *
- * An authored block crosses into backend storage here and is served from there
- * in a published payload — which is world-readable. So a credential in
- * `site.yml` is not merely untidy, it is disclosed. The host's secret store is
- * the only right home, resolved at request time.
- *
- * Warns rather than throwing: the fix belongs to the author, a failed push
- * helps nobody, and the block is still useful without the key. Returns the
- * value untouched when there is nothing to strip, so `setIf`'s absent-vs-empty
- * behaviour is unchanged — a block that carried ONLY a credential arrives as
- * `{}` rather than vanishing, keeping the mistake visible where the author
- * looks for it.
- *
- * @param {*} block - the authored value, any shape
- * @param {string} label - the site.yml key, for the warning
- * @returns {*} the block, minus anything credential-shaped
- */
-function stripCredentials(block, label) {
-  if (!block || typeof block !== 'object' || Array.isArray(block)) return block
-  const found = CREDENTIAL_KEYS.filter(key => key in block)
-  if (found.length === 0) return block
-
-  console.warn(
-    `uwx/site: dropped ${found.join(', ')} from \`${label}:\` — authored config is published ` +
-      'world-readable, so a credential belongs in the host secret store, never in site.yml.'
-  )
-
-  const cleaned = { ...block }
-  for (const key of found) delete cleaned[key]
-  return cleaned
-}
-
 // page_sections and layout_sections share this content shape.
 // processMarkdownFile takes only type/hidden/props/fetch/query/data/id out of the
 // frontmatter (and drops preset/input), so `background:` and `theme:` stay
@@ -1038,8 +1002,8 @@ const DECL_NOT_ON_WIRE = new Set([
   // passed unknown keys through blindly and would have sent `route` from every site
   // that declared one.
   'route',
-  // Legacy predicate, translated to the canonical `where` upstream. No legacy
-  // fields on the wire.
+  // ⛔ RETIRED 2026-10-06 — the build refuses it (`refuseQueryDeclaration`), so it is never sent.
+  // ⚠️ This said it was "translated to the canonical `where` upstream"; nothing translated it.
   'filter',
   // ⛔ RETIRED 2026-09-27 — the build refuses it (`refuseQueryDeclaration`), so it is never sent.
   'deferred',
@@ -1089,8 +1053,6 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
     // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
     if (typed && Array.isArray(queryFields) && queryFields.includes('typed_by_data_key')) data.typed_by_data_key = true
     setIf(data, 'sort', d.sort)
-    // Legacy `filter:` is not synced — it is translated to `where` upstream
-    // (the canonical predicate). No legacy fields on the wire.
     setIf(data, 'where', d.where)
     setIf(data, 'limit', d.limit)
     setIf(data, 'excerpt', d.excerpt)
@@ -1134,14 +1096,16 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
 //
 // ⭐ THE `services` SECTION IS THE OWNER'S REQUEST, AUTHORED IN `site.yml::services` — a
 // map from service name to `true`, `false` or the service's settings (spec:
-// kb/framework/reference/site-services-request.md). It is sent as a FULL LIST: the
-// site's rows, with the owner's asks applied by name (`mergeServiceRows`), because the
-// backend REPLACES the Section with what it is sent and a row left out would lose its
-// stored settings. The site's rows come from the caller when it has just read them
-// (`opts.serviceRows`, already merged), else from the record of the last agreement —
-// that backend's entry in `sync.json`, written by pull and by a push that succeeded.
-// ⛔ *The rows lived only in `sync.json` from 2026-09-20 to 2026-10-06, which left a
-// CLI user nowhere to ask; `site.yml::$services` / `$secrets` before that.*
+// kb/framework/reference/site-services-request.md). A push STATES: every service the
+// file lists, as it says it, and OFF for every service this copy holds that the file no
+// longer lists (`statedServices`). The services it holds are named in that backend's
+// entry in `sync.json`, `{ name: $uuid }`, written by pull and by a push that succeeded;
+// one it never saw is not sent, and the site keeps it. The backend decides per service
+// from the versions the push sends [Diego, 2026-10-07 — kb/framework/plans/services-exchange.md].
+// ⛔ *Until then the Section went as a FULL LIST — the site's rows, read just before the
+// push, with the file's changed asks applied — because the backend replaced the Section
+// with what it was sent; and from 2026-09-20 to 2026-10-06 the rows lived only in
+// `sync.json`, which left a CLI user nowhere to ask.*
 //
 // `secrets` stays in `sync.json`: an inventory of names a pull writes, whose values are
 // set in the app — `#ref` marks one as set.
@@ -1153,12 +1117,8 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
 // A row here is read by the service's owner and reaches neither tier, so an address
 // filed here would reach no page.
 //
-// ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is REPLACED
-// by what we send, so `[]` means "drop every stored row" while a missing key means "I
-// am not telling you about this". So `services` is emitted only when `site.yml` asks
-// for something and there is a list to apply it to — never for a file that says
-// nothing, and never as a partial list for a site whose rows this project does not
-// know. A site with no entry in `sync.json` has nothing stored yet.
+// The Section is emitted only when there is something to state: a file that lists no
+// service, on a copy that holds none, sends no `services`.
 
 /**
  * A backend's provisioned `services` / `secrets` (its `sync.json` entry) → Section
@@ -1220,25 +1180,22 @@ function servicesNested(rows) {
 }
 
 /**
- * The `services` Section for this push, or undefined when there is nothing to send:
- * the caller's rows when it passes them (the site's, read just now, with the asks it
- * decided to send applied), else the file's asks over the record of the site's rows.
+ * The `services` Section for this push — the file's services, and the held ones it no
+ * longer lists stated off (`statedServices`) — or undefined when there is nothing to state.
  *
  * @param {object} siteYml
- * @param {object|null} provisioned - the backend's entry in `sync.json`
- * @param {object[]} [serviceRows]
+ * @param {object|null} provisioned - the backend's entry in `sync.json`; its `services`
+ *   is `{ <name>: <$uuid> }`, the services this copy holds
  * @returns {object[]|undefined}
  */
-function requestedServices(siteYml, provisioned, serviceRows) {
-  if (Array.isArray(serviceRows)) return servicesNested(serviceRows)
-  const asks = readServicesRequest(siteYml.services)
-  if (!asks) return undefined
-  const base = Array.isArray(provisioned?.services)
-    ? provisioned.services
-    : provisioned?.site?.uuid
-      ? null
-      : []
-  return base ? servicesNested(mergeServiceRows(base, asks)) : undefined
+function requestedServices(siteYml, provisioned) {
+  const held = provisioned?.services
+  const rows = statedServices(
+    readServicesRequest(siteYml.services),
+    held && typeof held === 'object' && !Array.isArray(held) ? held : {}
+  )
+  // `$uuid` rides beside the payload-local `$id`, as on a query's row.
+  return rows.length ? servicesNested(rows) : undefined
 }
 
 /**
@@ -1352,19 +1309,11 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // carries the translation collector with it.
   setIf(settings, 'keywords', localizeScalarList(siteYml.keywords, sourceLocale, translations))
 
-  // Authored service declarations. ⛔ These must NOT be filed with the `services`
-  // Section. Here they are the SITE tier, `config.<name>` — the address
-  // `@uniweb/core`'s `resolveService` uses wherever the host offers none. That
-  // Section is a provisioning request whose rows reach neither tier, so filed there
-  // a site's own search endpoint would reach no page, and on a host whose services
-  // block does not name search the site would lose search with no error and no
-  // message (`core/src/services.js`). *(Until 2026-10-06 this called that Section
-  // "the HOST tier"; it is a request about what the host provides.)*
-  setIf(settings, 'search', siteYml.search)
-  setIf(settings, 'submit', siteYml.submit)
-  // ⛔ Credentials are stripped, not trusted — this block is published world-readable.
-  setIf(settings, 'assistant', stripCredentials(siteYml.assistant, 'assistant'))
-  setIf(settings, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
+  // ⛔ NO SERVICE IS HERE. A service's address and options ride its row in the
+  // `services` Section, whole (`requestedServices`) [Diego, 2026-10-06: "If it's on and
+  // has configuration, it can all be in the same place"]. *Until that evening
+  // `settings.search` / `.submit` / `.assistant` / `.tracking` carried them beside the
+  // row, and until that morning they were top-level `site.yml` keys.*
 
   // Projections opt-out + route exclusions. Carried because the app is a second
   // PUBLISHER of projections and derives them from stored content: without this it
@@ -1415,10 +1364,6 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  *        known, `@/x` ships as written.
  * @param {string[]} [opts.schemaless] - the queries whose records resolved no data schema
  *        (the records lane's `schemaless`): their declarations name no `schema`.
- * @param {object[]} [opts.serviceRows] - the `services` Section to send, as the caller
- *        decided it (the site's rows with the owner's asks applied). Default: the
- *        file's asks over the record in `sync.json`.
- * @param {boolean} [opts.declareServices] - `false` withholds `services` and `secrets`.
  * @returns {Promise<object>} the section-keyed `$`-document:
  *        `{ $uuid?, $id, $schema, info, settings?, pages, layout_sections, extensions,
  *        queries, services?, secrets? }`
@@ -1426,6 +1371,8 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
 export async function siteProjectToDocument(siteRoot, opts = {}) {
   refuseOrgOption(opts, 'uwx/site')
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
+  refuseRetiredServiceKeys(siteYml)
+  refuseUnreadableServices(siteYml)
   const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
     throw new Error('uwx/site: site.yml::name is required')
@@ -1514,68 +1461,30 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // and default keywords exist for any share/SSR/crawler. `seo` rides verbatim
   // as authored config (round-trips like favicon); `keywords` is a localized
   // list (like page keywords).
-  // `submit` — where this site's forms send submissions. Same family as
-  // `fetcher`/`search`: the site declares it, the runtime reads it, and it
-  // round-trips verbatim. It has to be listed HERE because this lane is an
-  // explicit allowlist while the bundle lane spreads all of site.yml — without
-  // the line a `submit:` block works on a static host and vanishes silently on
-  // the synced lane, which is the worst shape a config bug can take.
   // `agents` — the projections opt-out + route exclusions. Carried because the
   // app is a second PUBLISHER of projections and derives them from stored
   // content: without this block it cannot see `agents: false` or
   // `agents.exclude`, so an author's opt-out is silently reversed and an
   // excluded branch becomes both discoverable AND summarized by the index.
   // (The CLI lane reads site.yml directly and honors it either way.)
-  // `assistant` — the site's own declaration for an AI assistant: where it
-  // lives (`endpoint`, read by kit's `resolveService`) plus authored settings a
-  // host reads (`system` persona, model hints). Same family as
-  // `search`/`submit`, and here for the reason spelled out above them — the
-  // bundle lane spreads all of site.yml while this one is an allowlist, so
-  // without this line the block works on a static host and vanishes silently
-  // on the synced lane.
-  //
-  // ⚠️ That is not hypothetical: this replaces `intelligence.yml`, a SEPARATE
-  // file, which needed a bespoke line in each lane and got one in only the
-  // bundle lane — so an authored persona never reached a hosted site at all.
-  // A key inside site.yml cannot repeat that, because only this lane needs a
-  // line.
   //
-  // ⛔ Credentials are stripped, not trusted — see `stripCredentials`.
-  // `tracking` — where this site's usage events go (`endpoint`, read by the
-  // runtime through `resolveService`, plus `consent:`). Same family as
-  // `search`/`submit`/`assistant` and here for the same reason: the bundle lane
-  // spreads all of site.yml while this one is an allowlist, so without this line
-  // an authored `tracking:` works on a static host and vanishes silently on the
-  // synced lane.
+  // The services — `site.yml::services` — ride the `services` Section: one row per
+  // entry, the whole entry in its `config` (`requestedServices`). ⚠️ An entry must
+  // reach this lane whole because the bundle lane spreads it into the payload, and a
+  // block that works on a static host and vanishes on the synced lane is the worst
+  // shape a config bug can take — `intelligence.yml`, a separate file the assistant's
+  // persona once lived in, reached only the bundle lane, so a persona never reached a
+  // hosted site. ⛔ A credential is dropped (`readServicesRequest`) — but only as a
+  // KEYED FIELD: one embedded in an endpoint URL (`https://collector/e?key=…`) is
+  // invisible there and is disclosed. The host's secret store is the only right home.
   //
-  // ⛔ Credentials stripped like `assistant`. A collector that wants a write key
-  // is a real shape, and this block is published world-readable — but note the
-  // strip only reaches a KEYED FIELD: a key embedded in the endpoint URL itself
-  // (`https://collector/e?key=…`) is invisible here and is disclosed. The host's
-  // secret store is the only right home either way.
-
-  // ⛔ `api` IS DELIBERATELY NOT HERE, and this note exists because every comment
-  // above it argues the opposite — three services are on this allowlist precisely so
-  // an authored block cannot work on a static host and vanish on the synced one.
-  // Without this paragraph the next reader adds the missing fourth line and calls it
-  // a bug fix.
-  //
-  // ⭐ `api` is the one service a site does not AUTHOR. It is a real backend that is
-  // provisioned, so its address is the host's to supply — it arrives as
-  // `config.services.api` and `@uniweb/api` reads it there (`resolveBase`). An
-  // authored `api:` is the SITE tier: it yields to a host that offers the service,
-  // and is the answer wherever one does not.
-  //
-  // ⇒ Carrying it would turn a local-dev address into a production one the moment
-  // someone pushed: the host would store `settings.api` and serve it back as
-  // `config.api`, and a site with no `api` service of its own would draw sign-in
-  // against an address nobody answers — where the absence would have drawn
-  // nothing. The vanish on this lane is the correct behaviour, not the bug the
-  // comments above describe — there, a dropped block leaves a site with NO
-  // endpoint; here it leaves the site with the RIGHT answer.
-  //
-  // Asking for the `api` service is `site.yml::services` → the `services` Section (see
-  // requestedServices); its address still comes from the host.
+  // ⛔ `backend`'S ADDRESS IS THE HOST'S TO SUPPLY — `config.services.backend`, read by
+  // `@uniweb/api` (`resolveBase`). Asking for it is `services: { backend: true }`, or a
+  // map of the host's settings; an address of the site's own asks the host to leave its
+  // own off, and `readServicesRequest` says so, because `/_api` — where a local mock
+  // used to answer — reads that way. In `uniweb dev`, `$devBackend` supplies the mock's
+  // address (`dev/api-mount.js`). *(The service was `api` until 2026-10-07; that name is
+  // refused — `RENAMED_SERVICES`.)*
   // ⛔ THE CONFIGURATION KEYS ARE NOT HERE — they ride the `settings` Section
   // (`settingsNested` above). `info` is the BRIEF: what a card or a select dropdown
   // renders, plus what a listing can filter on. Eighteen keys moved off it on
@@ -1739,24 +1648,14 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
     opts.queryFields,
     Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
   )
-  // Emitted ONLY when there is something to say — see the header above
-  // `serviceRecords`: on a replaced Section, absent and empty are different
-  // requests and one of them is destructive.
-  //
-  // ⭐ WHICH ASKS GO IS THE CALLER'S. Push and publish read the site's rows and the
-  // record of the last agreement, apply only what the owner changed, and pass the
-  // result as `opts.serviceRows` — so an ask the site has since decided otherwise is
-  // never re-sent over that decision (`reconcileServices`). Without them, the file's
-  // asks apply over the record, which is what `status` and a pull's re-bank compare.
-  //
-  // `opts.declareServices === false` withholds both Sections for THIS push.
-  const declare = opts.declareServices !== false
-  // ⭐ The rows are per backend — a service is bought on the backend that sold it —
-  // and the request is one, in `site.yml`.
+  // Emitted only when there is something to state — see the header above
+  // `serviceRecords`. ⭐ What this copy holds is per backend — a service is bought on
+  // the backend that sold it — and the request is one, in `site.yml`. Push, publish,
+  // `status` and a pull's re-bank all build it alike, from the file and `sync.json`.
   const provisioned = opts.backend ? readBackendState(siteRoot, opts.backend) : null
-  const services = declare ? requestedServices(siteYml, provisioned, opts.serviceRows) : undefined
+  const services = requestedServices(siteYml, provisioned)
   if (services) doc.services = services
-  const secrets = declare ? secretsNested(provisioned) : undefined
+  const secrets = secretsNested(provisioned)
   if (secrets) doc.secrets = secrets
   return doc
 }