@uniweb/build 0.76.0 → 0.77.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.76.0",
+  "version": "0.77.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/semantic-parser": "^1.5.1",
+    "@uniweb/theming": "^0.2.0",
+    "@uniweb/schemas": "^0.12.0",
     "@uniweb/content-reader": "^1.2.8",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.14",
-    "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/schemas": "^0.11.0",
-    "@uniweb/theming": "^0.2.0"
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.29.0"
+    "@uniweb/runtime": "^0.29.2"
   },
   "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/runtime": "^0.29.0",
-    "@uniweb/core": "^0.37.0"
+    "@uniweb/core": "^0.37.2",
+    "@uniweb/runtime": "^0.29.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -23,7 +23,7 @@ import {
   deriveCacheKey,
   evaluateQuery,
 } from '@uniweb/core'
-import { recordTitle, routePatternToRegex, routeFieldOf } from '@uniweb/core/route-match'
+import { recordTitle, recordImage, routePatternToRegex, routeFieldOf } from '@uniweb/core/route-match'
 import DataStore from '@uniweb/core/datastore'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
 import { createFileTransport } from './site/file-transport.js'
@@ -473,6 +473,9 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
         const title = recordTitle(item)
         if (title) concretePage.title = title
         if (item.description || item.excerpt) concretePage.description = item.description || item.excerpt
+        // ⭐ And its picture is what a link to the page shows (`recordImage`) — the SPA's rule.
+        const image = recordImage(item)
+        if (image) concretePage.seo = { ...(concretePage.seo || {}), image }
 
         expandedPages.push(concretePage)
       }

package/src/site/content-collector.js

@@ -2437,6 +2437,48 @@ async function collectLayouts(layoutDir, siteRoot) {
  * @param {boolean} [options.strict=false] - Fail on content problems that would ship broken output rather than warning about them. A production build passes true; dev leaves it false, because a folder an author just created is empty for a moment and that is not an error.
  * @returns {Promise<Object>} Site content object with assets manifest
  */
+/**
+ * `site.yml` as a payload carries it — without what is authoring or publish intent,
+ * and without the backend-scoped `$` keys. One rule for every path that ships a
+ * site's config.
+ *
+ * `publishLanguages` is authoring/publish intent — it has no runtime consumer and
+ * never ships in a payload (the visitor runtime is list-unaware; the sync lane reads
+ * site.yml directly, not this output). The `query:` shorthand ships as
+ * `config.fetch`, desugared by the caller; carried raw it would sit beside
+ * `config.queries`, the declarations, and read as one.
+ *
+ * ⛔ `services` is the owner's REQUEST to their host (`uwx/services-request.js`), and
+ * here it would land at `config.services` — the HOST tier, where a present block
+ * declines every service it does not name. A request is never an answer, so it never
+ * ships. *(Until 2026-10-06 it did, and doubled as an undocumented way to simulate a
+ * host's offer locally.)*
+ *
+ * ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
+ * `$backend`, `$services`, `$secrets` — until they moved to `sync.json` (2026-09-20),
+ * and a `site.yml` written before then can still carry them. This payload is a
+ * PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in
+ * core, runtime or kit reads a `config.$*` key), so this removes noise for four of
+ * them and a real disclosure for the fifth: `$secrets` carries no values, but its
+ * entries name every secret the site has, and an inventory of credential names is not
+ * something an `export` should publish.
+ *
+ * @param {object} siteConfig
+ * @returns {object}
+ */
+function payloadSiteConfig(siteConfig) {
+  const {
+    publishLanguages: _publishLanguages,
+    query: _query,
+    services: _services,
+    ...runtimeSiteConfig
+  } = siteConfig
+  for (const key of Object.keys(runtimeSiteConfig)) {
+    if (key.startsWith('$')) delete runtimeSiteConfig[key]
+  }
+  return runtimeSiteConfig
+}
+
 export async function collectSiteContent(sitePath, options = {}) {
   const { foundationPath, configFile = 'site.yml', profile: profileName, dropUnpublished = false, base = '/', strict = false } = options
 
@@ -2547,7 +2589,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Check if pages directory exists
   if (!existsSync(pagesPath)) {
     return {
-      config: siteConfig,
+      config: payloadSiteConfig(siteConfig),
       theme: {
         ...processedTheme,
         css: themeCSS,
@@ -2725,23 +2767,7 @@ export async function collectSiteContent(sitePath, options = {}) {
     if (page.slug) delete page.slug
   }
 
-  // `publishLanguages` is authoring/publish intent — it has no runtime
-  // consumer and never ships in a payload (the visitor runtime is
-  // list-unaware; the sync lane reads site.yml directly, not this output).
-  // The `query:` shorthand ships as `config.fetch`, desugared below; carried raw
-  // it would sit beside `config.queries`, the declarations, and read as one.
-  const { publishLanguages: _publishLanguages, query: _query, ...runtimeSiteConfig } = siteConfig
-  // ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
-  // `$backend`, `$services`, `$secrets` — until they moved to `sync.json`
-  // (2026-09-20), and a `site.yml` written before then can still carry them. This
-  // payload is a PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in core, runtime
-  // or kit reads a `config.$*` key), so this removes noise for four of them and a
-  // real disclosure for the fifth: `$secrets` carries no values, but its entries
-  // name every secret the site has, and an inventory of credential names is not
-  // something an `export` should publish.
-  for (const key of Object.keys(runtimeSiteConfig)) {
-    if (key.startsWith('$')) delete runtimeSiteConfig[key]
-  }
+  const runtimeSiteConfig = payloadSiteConfig(siteConfig)
 
   // ⛔ **A BUILD does not ship a site whose config failed to parse.**
   // `strict` is already this codebase's word for it — `build-site-data.js` sets

package/src/uwx/data-schema.js

@@ -112,7 +112,7 @@ export function isContentBodyField(field) {
  * @param {(ref: string) => string} [opts.resolveOptions] - maps an `options`
  *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
  *   `resolveName` (model only) when not supplied.
- * @returns {Object} the declaration (`{ name, label?, plural?, description?,
+ * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
  *          source_locale?, linkable?, sections }`).
  */
 export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
@@ -137,6 +137,9 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
   const decl = { name }
   if (normalized.label) decl.label = normalized.label
   if (normalized.plural) decl.plural = normalized.plural
+  // The type's icon — a framework icon name (`lu-user`), sent as written; the registry
+  // stores it verbatim and a consumer resolves it. Since 2026-10-05 [Diego].
+  if (normalized.icon) decl.icon = normalized.icon
   if (normalized.description) decl.description = normalized.description
   if (normalized.sourceLocale) decl.source_locale = normalized.sourceLocale
   // ⛔ No `creatable_by`: retired 2026-09-23 — Models are open, and `@uniweb/schemas`

package/src/uwx/emit-surface.json

@@ -106,11 +106,11 @@
     },
     "services": {
       "kind": "passthrough",
-      "authoredAs": "site.yml::$services"
+      "authoredAs": "site.yml::services"
     },
     "secrets": {
       "kind": "passthrough",
-      "authoredAs": "site.yml::$secrets"
+      "authoredAs": "sync.json::backends.<origin>.secrets"
     },
     "pages": {
       "kind": "records"

package/src/uwx/index.js

@@ -113,6 +113,15 @@ export {
   refForAssetId,
   normalizeOrigin as normalizeBackendOrigin,
 } from './sync-store.js'
+// A site's services request — `site.yml::services`, applied over the site's own rows.
+// Spec: kb/framework/reference/site-services-request.md
+export {
+  readServicesRequest,
+  takeServices,
+  mergeServiceRows,
+  reconcileServices,
+  recordAfter,
+} from './services-request.js'
 export {
   diffSiteUnits,
   describeSiteDiff,

package/src/uwx/project-writer.js

@@ -268,13 +268,17 @@ const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArr
  * ⛔ The declaration keys (`query` / `fetch` / `data`) are written WHOLE, never
  * merged: a declaration is one value, and merging an incoming `fetch:` into the
  * local one kept whatever key the remote no longer has — a stale `limit` survived
- * every pull.
+ * every pull. So is `services`: it is the site's settled request, and a service
+ * merged in from the old map would be an ask nobody made.
  * @returns {'updated'|'unchanged'}
  */
 export function writeSiteConfig(siteRoot, config) {
-  return mergeYamlConfig(join(siteRoot, 'site.yml'), config, { replace: DECLARATION_KEYS })
+  return mergeYamlConfig(join(siteRoot, 'site.yml'), config, { replace: SITE_CONFIG_WHOLE })
 }
 
+/** `site.yml` keys a writer replaces whole rather than merging into. */
+const SITE_CONFIG_WHOLE = Object.freeze([...DECLARATION_KEYS, 'services'])
+
 /**
  * Write a YAML object to a file (full dump, idempotent) — for machine-owned
  * config the projector authors wholesale, e.g. a projected `page.yml`/`folder.yml`.

package/src/uwx/services-request.js

@@ -0,0 +1,280 @@
+/**
+ * A site's services request — `site.yml::services`, a map from service name to
+ * what the owner asks their host for.
+ *
+ * ```yaml
+ * services:
+ *   search: true       # turn it on
+ *   submit: false      # turn it off
+ *   api:               # turn it on, with the service's own settings
+ *     grade: pro
+ * ```
+ *
+ * ⭐ ONE REQUEST, WHICHEVER BACKEND A COMMAND TALKS TO. The rows a backend holds
+ * for the site are kept apart from it, in that backend's entry in `sync.json` — the
+ * CLI's record of what it last agreed with that site, which nobody edits.
+ *
+ * ⛔ NOT THE TOP-LEVEL `search:` / `submit:` / `assistant:` / `tracking:` KEYS.
+ * Those say how the site uses a provider it brings itself; this asks the host. A
+ * site's own `submit: https://forms.example.com/…` read as a request would turn on
+ * the host's form handling, whose address then outranks the site's.
+ *
+ * Pure functions, shared by the producer (`site.js`), pull (`site-project.js`) and
+ * the CLI's push and publish.
+ *
+ * @module
+ */
+
+/** Top-level `site.yml` keys that hold an address — named when one is misplaced here. */
+const ADDRESS_KEYS = new Set(['search', 'submit', 'assistant', 'tracking', 'api'])
+
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/** Deterministic JSON: object keys sorted at every depth, arrays left in order. */
+function stable(value) {
+  return JSON.stringify(value ?? null, (_k, v) =>
+    isMap(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]])) : v
+  )
+}
+
+/**
+ * A row as it is stored and compared: no payload-local `$id`, `enabled` only when
+ * it is `false` (absent means on), no empty `config`.
+ */
+function canonicalRow(row) {
+  const { $id: _id, enabled, ...rest } = row
+  const out = { ...rest }
+  if (enabled === false) out.enabled = false
+  if (isMap(out.config) && Object.keys(out.config).length === 0) delete out.config
+  return out
+}
+
+const rowNamed = (rows, name) =>
+  Array.isArray(rows) ? rows.find((r) => isMap(r) && r.name === name) : undefined
+
+/**
+ * `site.yml::services` → the asks, as rows in the `services` Section's shape:
+ * `{ name, enabled?: false, config? }`.
+ *
+ * @param {*} declared - the raw `services:` value
+ * @param {{ warn?: (message: string) => void }} [opts] - told about every value it
+ *   ignores, with the fix
+ * @returns {object[]|null} null when the file asks nothing — no key, or no usable entry
+ */
+export function readServicesRequest(declared, { warn = () => {} } = {}) {
+  if (declared === undefined || declared === null) return null
+  if (!isMap(declared)) {
+    warn('`services:` is a map of service names — `services: { search: true }`. Ignoring it.')
+    return null
+  }
+  const asks = []
+  for (const [name, value] of Object.entries(declared)) {
+    if (value === true) asks.push({ name })
+    else if (value === false) asks.push({ name, enabled: false })
+    else if (isMap(value)) {
+      const { enabled, ...settings } = value
+      if (enabled !== undefined && typeof enabled !== 'boolean') {
+        warn(`\`services.${name}.enabled\` is true or false. Ignoring \`${name}\`.`)
+        continue
+      }
+      asks.push({
+        name,
+        ...(enabled === false ? { enabled: false } : {}),
+        ...(Object.keys(settings).length ? { config: settings } : {})
+      })
+    } else {
+      const address =
+        typeof value === 'string' && ADDRESS_KEYS.has(name)
+          ? ` An address for the site's own ${name} goes in the top-level \`${name}:\` key.`
+          : ''
+      warn(`\`services.${name}\` is true, false, or a map of its settings. Ignoring it.${address}`)
+    }
+  }
+  return asks.length ? asks : null
+}
+
+/**
+ * The site's stored rows → the `site.yml::services` map — what pull writes.
+ *
+ * A row becomes `true` or `false`, or a map of its settings with `enabled: false`
+ * when it is off.
+ *
+ * @param {object[]} rows
+ * @returns {object|null} null when there is nothing to write
+ */
+export function servicesRequestFromRows(rows) {
+  if (!Array.isArray(rows)) return null
+  const out = {}
+  for (const row of rows) {
+    if (!isMap(row) || typeof row.name !== 'string' || !row.name) continue
+    out[row.name] = requestValue(row)
+  }
+  return Object.keys(out).length ? out : null
+}
+
+/** One stored row → its value in the `site.yml::services` map. */
+function requestValue(row) {
+  const off = row.enabled === false
+  const settings = isMap(row.config) && Object.keys(row.config).length ? row.config : null
+  if (!settings) return !off
+  return off ? { enabled: false, ...settings } : { ...settings }
+}
+
+/**
+ * The `site.yml::services` map with these services taken from the site's rows — a
+ * service the site holds no row for leaves the map.
+ *
+ * @param {*} declared - the current `services:` value
+ * @param {object[]} stored - the site's rows now
+ * @param {string[]} names
+ * @returns {object|null} the new map, or null when nothing is left in it
+ */
+export function takeServices(declared, stored, names) {
+  const out = isMap(declared) ? { ...declared } : {}
+  for (const name of names) {
+    const row = rowNamed(stored, name)
+    if (row) out[name] = requestValue(row)
+    else delete out[name]
+  }
+  return Object.keys(out).length ? out : null
+}
+
+/**
+ * Does this stored row already give what the ask asks — the same switch, and every
+ * setting the ask names equal?
+ *
+ * @param {object|undefined} row
+ * @param {object} ask
+ * @returns {boolean}
+ */
+export function satisfies(row, ask) {
+  if (!isMap(row)) return false
+  if ((row.enabled === false) !== (ask.enabled === false)) return false
+  if (!ask.config) return true
+  const stored = isMap(row.config) ? row.config : {}
+  return Object.entries(ask.config).every(([key, value]) => stable(stored[key]) === stable(value))
+}
+
+/** Two rows that are the same as stored — both absent included. */
+function sameRow(a, b) {
+  return stable(isMap(a) ? canonicalRow(a) : null) === stable(isMap(b) ? canonicalRow(b) : null)
+}
+
+/**
+ * The full list to send: the stored rows, with these asks applied by name.
+ *
+ * ⭐ A FULL LIST, because the backend replaces the `services` Section with what it is
+ * sent: a row left out would lose its stored settings. A row no ask names is sent as
+ * stored. A row an ask names takes the ask's switch, and its settings over the
+ * stored ones, key by key. Every field is kept — a row is opaque past `name`,
+ * `enabled` and `config`.
+ *
+ * @param {object[]|null|undefined} base - the site's rows (or the record of them)
+ * @param {object[]} asks - from `readServicesRequest`
+ * @returns {object[]}
+ */
+export function mergeServiceRows(base, asks) {
+  const out = []
+  const at = new Map()
+  for (const row of Array.isArray(base) ? base : []) {
+    if (!isMap(row) || typeof row.name !== 'string' || !row.name || at.has(row.name)) continue
+    at.set(row.name, out.length)
+    out.push(canonicalRow(row))
+  }
+  for (const ask of asks || []) {
+    const index = at.get(ask.name)
+    const next = index === undefined ? { name: ask.name } : { ...out[index] }
+    if (ask.enabled === false) next.enabled = false
+    else delete next.enabled
+    if (ask.config) next.config = { ...(isMap(next.config) ? next.config : {}), ...ask.config }
+    if (index === undefined) {
+      at.set(ask.name, out.length)
+      out.push(next)
+    } else {
+      out[index] = next
+    }
+  }
+  return out
+}
+
+/**
+ * Per service the file names: who moved since the last agreement, and so what to do.
+ *
+ * Three states — the file's asks, the site's rows now (`stored`), and the record of
+ * the last agreement (`record`, from `sync.json`):
+ *
+ * | the file vs the record | the site vs the record | outcome |
+ * |---|---|---|
+ * | unchanged | unchanged | nothing |
+ * | changed | unchanged | `send` |
+ * | unchanged | changed | `adopt` — the site's is kept, and may be taken into the file |
+ * | changed | changed, differently | `conflict` — only the owner can rank the two |
+ *
+ * A service the site already gives as asked is nothing, whoever moved. With no record
+ * the two cannot be told apart: a service the site holds nothing for is sent, one it
+ * holds differently is a conflict. With the site unreadable, what changed against the
+ * record is sent over the record; with neither, nothing can be merged onto for a site
+ * that exists — `unreadable` — while a site not yet created has nothing stored.
+ *
+ * @param {object} p
+ * @param {object[]} p.asks - from `readServicesRequest`
+ * @param {object[]} [p.record] - the rows last agreed, when the project has them
+ * @param {object[]} [p.stored] - the site's rows now, when they could be read
+ * @param {boolean} [p.siteKnown=true] - whether the site exists on this backend
+ * @returns {{ send: string[], adopt: string[], conflict: string[], unreadable: boolean }}
+ */
+export function reconcileServices({ asks, record, stored, siteKnown = true }) {
+  const send = []
+  const adopt = []
+  const conflict = []
+  const haveRecord = Array.isArray(record)
+  const haveStored = Array.isArray(stored)
+  if (!haveRecord && !haveStored) {
+    return siteKnown
+      ? { send, adopt, conflict, unreadable: true }
+      : { send: asks.map((a) => a.name), adopt, conflict, unreadable: false }
+  }
+  for (const ask of asks) {
+    const now = rowNamed(stored, ask.name)
+    const then = rowNamed(record, ask.name)
+    if (!haveStored) {
+      if (!satisfies(then, ask)) send.push(ask.name)
+      continue
+    }
+    if (satisfies(now, ask)) continue
+    if (!haveRecord) {
+      ;(now === undefined ? send : conflict).push(ask.name)
+      continue
+    }
+    const fileMoved = !satisfies(then, ask)
+    const siteMoved = !sameRow(now, then)
+    if (fileMoved && !siteMoved) send.push(ask.name)
+    else if (!fileMoved && siteMoved) adopt.push(ask.name)
+    else conflict.push(ask.name)
+  }
+  return { send, adopt, conflict, unreadable: false }
+}
+
+/**
+ * The record after a push: what this project now agrees with the site on.
+ *
+ * The rows sent, or — when nothing was — the site's rows now. ⛔ For a service left
+ * OPEN (an adopt not taken, a conflict not resolved) the earlier agreement stands,
+ * or the next run would read the site's change as the file's and send the stale ask.
+ *
+ * @param {object} p
+ * @param {object[]} [p.record] - the rows last agreed
+ * @param {object[]} [p.agreed] - the rows sent, or the site's rows now
+ * @param {string[]} [p.open] - services whose decision is still open
+ * @returns {object[]|undefined} undefined when there is nothing to record
+ */
+export function recordAfter({ record, agreed, open = [] }) {
+  if (!Array.isArray(agreed)) return undefined
+  const keep = new Set(open)
+  const out = agreed.filter((r) => isMap(r) && !keep.has(r.name)).map(canonicalRow)
+  for (const name of open) {
+    const then = rowNamed(record, name)
+    if (then) out.push(canonicalRow(then))
+  }
+  return out
+}

package/src/uwx/site-project.js

@@ -36,6 +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 { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { createHash } from 'node:crypto'
@@ -309,30 +310,24 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 
-  // services[] / secrets[] → sync.json::backends.<origin>.{services,secrets}.
+  // services[] → site.yml::services, and the same rows → sync.json as the record.
   //
-  // ⭐ The `$` prefix, and not the bare name, for the reason spelled out in
-  // `uwx/site.js`: `site.yml::services` already means "pretend a host offers these"
-  // on the bundle lane, and one key cannot mean two things.
+  // ⭐ `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.
   //
-  // ⭐ `$id` is DROPPED — it is derived (a service's `name`; a secret's
-  // `service:name` pair), so writing it back would put a redundant handle in the
-  // author's file and invite them to edit the one field that must not drift from
-  // the fields it is derived from. Same call as `extensions` above.
-  //
-  // ⛔ Everything else rides VERBATIM, `config` included: it is opaque, per-service
-  // and will grow, so projecting a known subset would quietly drop whatever the
-  // service gained since this line was written — and the next push would then send
-  // the truncated version back as authoritative.
-  //
-  // ⚠️ An EMPTY section is written as an empty list, not skipped. `[]` is a real
-  // state — "this site has no service rows" — and it is the state a `pull` must be
-  // able to deliver after the last one was removed. Skipping would leave a stale
-  // `$services` on disk that the next push would resurrect.
-  // ⭐ To `sync.json`, under the backend that provisioned them — not `site.yml`.
-  // A service is bought on one backend, so its rows describe that backend alone.
-  // ⛔ Needs a backend: with none there is nowhere coherent to file them, and
-  // writing them to a shared place is exactly the single-copy bug this removed.
+  // ⭐ 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.
+  if (Array.isArray(document?.services)) {
+    siteChanges.services = servicesRequestFromRows(document.services)
+  }
   if (backend) {
     const provisioned = {}
     for (const section of ['services', 'secrets']) {

package/src/uwx/site.js

@@ -80,6 +80,7 @@ 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 { resolveQueriesConfig } from './queries-config.js'
 import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
@@ -1129,48 +1130,35 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
   return out
 }
 
-// ── `services` + `secrets` — a site's own service records ─────────────────────
+// ── `services` + `secrets` — what a site asks of its host ─────────────────────────
 //
-// ⚠️ THESE WERE `site.yml::$services` / `$secrets` UNTIL 2026-09-20. They now live in
-// `sync.json::backends.<origin>.{services,secrets}`, because what a site is PROVISIONED
-// with is a fact about one backend — a service is bought on the backend that sold it.
-// The `$` prefix existed to keep them off `site.yml::services`, which means something
-// else on the bundle lane (the HOST tier); out of `site.yml` entirely, that collision
-// is gone too.
+// ⭐ 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.*
 //
-// The original note, kept because it explains why the names could not simply be reused: `site.yml::services` is ALREADY TAKEN,
-// on the other lane: the bundle lane spreads site.yml whole into the payload, so a
-// `services:` block there lands at `config.services` — the HOST tier — which is the
-// documented way to simulate a host locally (`kit/src/utils/submitTarget.js`).
-// Reusing the name would give one key two meanings that differ per lane, which is
-// the shape of bug nobody finds.
-//
-// `$` already means "backend-scoped, round-tripped, not hand-authored" in this file
-// (`$uuid`, `$org`, `$backend`), and that is exactly what these are: a service's
-// config is bound where the service is provisioned, and arrives here by `pull`.
+// `secrets` stays in `sync.json`: an inventory of names a pull writes, whose values are
+// set in the app — `#ref` marks one as set.
 //
 // ⚖️ WHAT THESE ARE NOT. A site's OWN service declarations — `search:`, `submit:`,
 // `assistant:`, `tracking:` — ride the `settings` Section and are untouched here.
-// (They were top-level `info.*` keys until 2026-09-09; `settingsNested` below is
-// where they are now written.) Those
-// are authored, they resolve at the SITE tier (`config.<name>`, first choice in
-// `@uniweb/core`'s `resolveService`), and moving them here would flip them to the
-// host tier, where a block's mere presence declines every service it does not name.
-// These Sections carry the services a site is PROVISIONED with — `api` above all,
-// which has no file-authored form because it is bought, not declared.
-//
-// ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is
-// REPLACED by what we send, so `[]` means "drop every stored config row" while a
-// missing key means "I am not telling you about this". A project that has never
-// pulled has no `services` for that backend, and its ordinary push must not read as
-// a request to wipe a service the operator configured in the app. So: emit the
-// Section only when that backend's entry in `sync.json` carries the key. Clearing is
-// available and explicit — `services: []` there. *(Both said `site.yml::$services`
-// until the move on 2026-09-20.)*
+// Those are authored addresses and land at the SITE tier, `config.<name>`, which
+// `@uniweb/core`'s `resolveService` reads for any service the host does not offer.
+// A row here is read by the service's owner and reaches neither tier, so an address
+// filed here would reach no page.
 //
-// ⚠️ The push gate is NOT what makes this safe, though it usually catches it: its
-// tokens live in a gitignored per-clone cache, so a fresh clone pushes
-// unconditionally. Correctness has to sit here.
+// ⛔ 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.
 
 /**
  * A backend's provisioned `services` / `secrets` (its `sync.json` entry) → Section
@@ -1223,14 +1211,36 @@ function serviceRecords(declared, identify, label) {
 }
 
 /** One service per `name` — the same keyspace `config.services` uses at runtime. */
-function servicesNested(provisioned) {
+function servicesNested(rows) {
   return serviceRecords(
-    provisioned?.services,
+    rows,
     (e) => (typeof e.name === 'string' && e.name ? e.name : null),
-    '$services'
+    'services'
   )
 }
 
+/**
+ * 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.
+ *
+ * @param {object} siteYml
+ * @param {object|null} provisioned - the backend's entry in `sync.json`
+ * @param {object[]} [serviceRows]
+ * @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
+}
+
 /**
  * One secret per `(service, name)` — the pair the backend merges on. A site-level
  * secret belongs to no service, so `service` is optional and the handle degrades to
@@ -1342,12 +1352,14 @@ 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: authored ones resolve at the SITE tier (`config.<name>`, first choice
-  // in `@uniweb/core`'s `resolveService`) while `$services` is the HOST tier, where
-  // a block's mere PRESENCE declines every service it does not name
-  // (`core/src/services.js`). Moving them there would invert their precedence and
-  // turn a site's own search off with no error and no message.
+  // 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.
@@ -1403,6 +1415,10 @@ 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? }`
@@ -1558,7 +1574,8 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // comments above describe — there, a dropped block leaves a site with NO
   // endpoint; here it leaves the site with the RIGHT answer.
   //
-  // The provisioned record rides the `$services` section instead (see servicesNested).
+  // Asking for the `api` service is `site.yml::services` → the `services` Section (see
+  // requestedServices); its address still comes from the host.
   // ⛔ 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
@@ -1722,31 +1739,22 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
     opts.queryFields,
     Array.isArray(opts.schemaless) ? new Set(opts.schemaless) : null
   )
-  // Emitted ONLY when the file declares the key — see the header above
+  // 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.
   //
-  // ⭐ AND ONLY WHEN THE CALLER SAYS THE DECLARATION IS A REQUEST.
-  // `opts.declareServices === false` withholds both Sections for THIS push, which
-  // is not the same as the file having no key — the file still declares one; the
-  // caller has determined the owner is not asking for anything new by it.
-  //
-  // ⛔ Why this decision cannot live here: the Sections are REPLACED wholesale by
-  // what we send (`SectionScope::DeclaredOnly`), so re-sending an unchanged block
-  // OVERWRITES whatever the stored request has become since — including a decision
-  // the owner made in the app, where the consent workflow's publish happens. But
-  // "has it changed since we last agreed?" needs the last agreed state, which is
-  // project memory (`deploy.yml`) the CLI owns and this pure mapper must not read.
-  // ⇒ The CLI decides; this honours the decision.
+  // ⭐ 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.
   //
-  // ⚖️ Default is to declare, so every existing caller is unchanged and the
-  // withholding is opt-in.
+  // `opts.declareServices === false` withholds both Sections for THIS push.
   const declare = opts.declareServices !== false
-  // ⭐ Provisioned per backend — a service is bought on the backend that sold it,
-  // so which rows exist is a question about ONE backend. They were `site.yml::$services`
-  // / `$secrets`, a single copy that could only ever describe one.
+  // ⭐ The rows are per backend — a service is bought on the backend that sold it —
+  // and the request is one, in `site.yml`.
   const provisioned = opts.backend ? readBackendState(siteRoot, opts.backend) : null
-  const services = declare ? servicesNested(provisioned) : undefined
+  const services = declare ? requestedServices(siteYml, provisioned, opts.serviceRows) : undefined
   if (services) doc.services = services
   const secrets = declare ? secretsNested(provisioned) : undefined
   if (secrets) doc.secrets = secrets

package/src/uwx/sync-package.js

@@ -215,6 +215,8 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @param {string} [opts.sourceLocale]    - localized-field wrap locale
  * @param {Object<string,string>} [opts.priorHashes] - sync-cache (send-only-changed)
  * @param {boolean} [opts.sendAll]        - bypass the prior-hash filter
+ * @param {object[]} [opts.serviceRows]   - the `services` Section to send, as the
+ *                                          caller decided it (site.js `requestedServices`)
  * @param {Object<string,string>} [opts.itemUuids] - unit path → backend `$uuid`,
  *        stamped onto the site-content document so the backend matches our items
  *        instead of re-minting them (which deletes and recreates every page and
@@ -375,10 +377,11 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         ...(Array.isArray(opts.queryFields) ? { queryFields: opts.queryFields } : {}),
         ...(Array.isArray(opts.pageFields) ? { pageFields: opts.pageFields } : {}),
         ...(Array.isArray(opts.settingsFields) ? { settingsFields: opts.settingsFields } : {}),
-        // Withhold the `$services`/`$secrets` Sections when the caller has
-        // determined the file is not asking for anything new by them. Passed
-        // through rather than decided here: the last-agreed state is project
-        // memory the CLI owns. See site.js at `declareServices`.
+        // The `services` Section as the caller decided it — the site's rows with the
+        // owner's changed asks applied — or the Sections withheld. Passed through
+        // rather than decided here: the site's rows and the last agreement are what
+        // the CLI reads. See site.js at `requestedServices`.
+        ...(Array.isArray(opts.serviceRows) ? { serviceRows: opts.serviceRows } : {}),
         ...(opts.declareServices === false ? { declareServices: false } : {})
       })
     : null