@uniweb/build 0.43.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,14 +57,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.5.13",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/schemas": "^0.2.13",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/projections": "^0.5.13"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.19.0"
+    "@uniweb/runtime": "^0.19.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,7 +73,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.24.1"
+    "@uniweb/core": "^0.24.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -758,13 +758,26 @@ function reportSupports(srcDir, authored, derived, emitted) {
     }
   }
 
-  if (derived.blind && (emitted === undefined || emitted.length === 0)) {
-    // The one case where an empty result is NOT a proven "none": something
-    // named a service in a way the AST could not read, so the set is short by
-    // an unknown amount and absent/UNKNOWN is the honest wire value.
+  // ⛔ WARN WHENEVER THE DERIVATION WAS BLIND — not only when it came back empty.
+  //
+  // This used to require an empty result, which left the more likely case
+  // silent: a foundation that reaches `submit` through a literal and `booking`
+  // through a computed name publishes `["submit"]` — short, with no warning, and
+  // the one person who could fix it never hears about it.
+  //
+  // ⭐ That is what makes the lower bound tolerable. How often a foundation
+  // computes a service name is unknowable from here — foundations are
+  // third-party — but it does not need to be known, because the build detects
+  // its own blindness and can say so to the developer at the moment they build.
+  if (derived.blind) {
+    const empty = emitted === undefined || emitted.length === 0
     console.warn(
-      `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
-        `derived and is left undeclared. List it in package.json to publish it.`,
+      empty
+        ? `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
+            `derived and is left undeclared. List it in package.json to publish it.`
+        : `Warning: a service is resolved by a computed name, so the derived ` +
+            `\`uniweb.supports\` may be incomplete. Add any service missing from ` +
+            `[${(emitted || []).join(', ')}] to package.json.`,
     )
     for (const at of derived.blindAt || []) console.warn(`  at ${at}`)
   }

package/src/site/content-collector.js

@@ -190,7 +190,7 @@ function detectVersions(folderNames) {
  * @param {string|Array<string>|undefined} data
  * @returns {Object|Array<Object>|undefined}
  */
-function fetchFromDataShorthand(data) {
+export function fetchFromDataShorthand(data) {
   if (!data) return undefined
   if (Array.isArray(data)) return data.map((query) => ({ query }))
   return { query: data }
@@ -1164,7 +1164,44 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
  * @param {Object} options.versionContext - Version context from parent { version, versionMeta, scope }
  * @returns {Object} Page data with assets manifest
  */
-async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, versionContext = null, layoutName = null } = {}) {
+/**
+ * Normalize an authored `layout:` into `{ name?, hide?, params? }`.
+ *
+ * ⭐ The authored form is documented in two shapes — the string shorthand
+ * (`layout: DocsLayout`) and the expanded object (`{ name, hide, params }`,
+ * `docs/reference/page-configuration.md`). Both reduce to the same record here so
+ * every tier can be merged with the same rule.
+ *
+ * ⚠️ Only present keys are set. `hide: []` is a real value (hide nothing,
+ * overriding an ancestor) and must survive; an absent `hide` must not shadow one.
+ */
+function normalizeLayoutConfig(raw) {
+  if (typeof raw === 'string') return raw ? { name: raw } : {}
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {}
+  const out = {}
+  if (typeof raw.name === 'string' && raw.name) out.name = raw.name
+  if (Array.isArray(raw.hide)) out.hide = raw.hide
+  if (raw.params && typeof raw.params === 'object') out.params = raw.params
+  return out
+}
+
+/**
+ * Merge an inherited layout config with a nearer one — site → folder → page.
+ *
+ * ⭐ PER-FIELD, nearest wins, which is the cascade `seo` already documents:
+ * *"the page wins, the site fills the gaps"*. So a page that sets only `hide`
+ * keeps an ancestor's `name`.
+ *
+ * ⛔ NOT a union on `hide`. A page saying `hide: [footer]` under a site saying
+ * `hide: [right]` hides the footer and shows the right rail — it REPLACES the
+ * ancestor's list. Union would make an ancestor's hide impossible to undo from a
+ * page, which is the one thing an override is for.
+ */
+function mergeLayoutConfig(inherited, own) {
+  return { ...(inherited || {}), ...(own || {}) }
+}
+
+async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, versionContext = null, inheritedLayout = null } = {}) {
   const pageConfig = await readYamlFile(join(pagePath, 'page.yml'))
 
   // Note: We no longer skip hidden pages here - they still exist as valid pages,
@@ -1455,13 +1492,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   // Extract configuration
   const { seo = {}, layout: layoutConfig, ...restConfig } = pageConfig
 
-  // Resolve layout name: page.yml layout (string or object.name) > inherited from parent > null
-  const pageLayoutName = typeof layoutConfig === 'string' ? layoutConfig
-    : layoutConfig?.name || null
-  const resolvedLayoutName = pageLayoutName || layoutName || null
-
-  // Layout panel visibility (from object form of layout config)
-  const layoutObj = typeof layoutConfig === 'object' && layoutConfig !== null ? layoutConfig : {}
+  // Resolve the effective layout by cascading site → folder → page, per field.
+  // ⛔ Until 2026-09-09 only `name` cascaded and `hide` / `params` were read from
+  // the PAGE's own config alone, so the documented expanded form was silently
+  // two-thirds ignored at every tier above the page — including `site.yml`, whose
+  // `layout:` the collector already read for its name.
+  const layoutObj = mergeLayoutConfig(inheritedLayout, normalizeLayoutConfig(layoutConfig))
+  const resolvedLayoutName = layoutObj.name || null
 
   // For dynamic routes, determine the parent's data schema — this tells
   // prerender which data array to iterate over.
@@ -1611,7 +1648,7 @@ function determineIndexPage(orderConfig, availableFolders) {
  * @param {string} contentMode - 'sections' (default) or 'pages' (md files are child pages)
  * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound, versionedScopes }
  */
-async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null, contentMode = 'sections', mounts = null, parentLayoutName = null) {
+async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null, contentMode = 'sections', mounts = null, parentLayout = null) {
   const entries = await readdir(dirPath)
   const pages = []
   let assetCollection = {
@@ -1667,8 +1704,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       ? local.mode
       : mounted?.mode ?? local?.mode ?? contentMode
 
-    const folderLayout = typeof dirConfig.layout === 'string' ? dirConfig.layout
-      : dirConfig.layout?.name || null
+    const folderLayout = normalizeLayoutConfig(dirConfig.layout)
 
     pageFolders.push({
       name,
@@ -1685,7 +1721,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         pages: dirConfig.pages,
         index: dirConfig.index
       },
-      childLayoutName: folderLayout
+      childLayout: folderLayout
     })
   }
 
@@ -1724,7 +1760,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     versionedScopes.set(parentRoute, versionMeta)
 
     for (const folder of orderedFolders) {
-      const { name: entry, path: entryPath, childOrderConfig, childLayoutName } = folder
+      const { name: entry, path: entryPath, childOrderConfig, childLayout } = folder
 
       if (isVersionFolder(entry)) {
         const versionInfo = versionMeta.versions.find(v => v.id === entry)
@@ -1738,7 +1774,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         const subResult = await collectPagesRecursive(
           entryPath, versionRoute, siteRoot, childOrderConfig, parentFetch,
           { version: versionInfo, versionMeta, scope: parentRoute },
-          'sections', null, childLayoutName || parentLayoutName
+          'sections', null, mergeLayoutConfig(parentLayout, childLayout)
         )
 
         pages.push(...subResult.pages)
@@ -1750,7 +1786,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       } else {
         const result = await processPage(entryPath, entry, siteRoot, {
           isIndex: false, parentRoute, parentFetch,
-          layoutName: childLayoutName || parentLayoutName
+          inheritedLayout: mergeLayoutConfig(parentLayout, childLayout)
         })
         if (result) {
           pages.push(result.page)
@@ -1818,25 +1854,32 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         page.route = parentRoute
       }
 
-      // Inherit layout name from parent (folder.yml or site.yml cascade)
-      if (parentLayoutName && !page.layout.name) {
-        page.layout.name = parentLayoutName
-      }
+      // Inherit the layout from the folder / site cascade.
+      //
+      // ⭐ THE WHOLE OBJECT, not just the name. `processFileAsPage` (folder-mode
+      // `.md`-as-pages) takes no layout argument, so this post-hoc merge is where
+      // the cascade reaches these pages at all — the threaded path above covers
+      // every other kind. Until 2026-09-09 it patched `name` only, which is why a
+      // folder or site `hide:` never reached a folder-mode page.
+      //
+      // `normalizeLayoutConfig` first so the page's own record has no undefined
+      // keys to shadow an inherited value through the spread.
+      page.layout = mergeLayoutConfig(parentLayout, normalizeLayoutConfig(page.layout))
 
       pages.push(page)
     }
 
     // Process subdirectories
     for (const folder of orderedFolders) {
-      const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayoutName } = folder
+      const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
       const isIndex = entry === indexName
-      const effectiveLayout = childLayoutName || parentLayoutName
+      const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
       if (dirMode === 'sections') {
         // Subdirectory overrides to page mode — process normally
         const result = await processPage(entryPath, entry, siteRoot, {
           isIndex, parentRoute, parentFetch, versionContext,
-          layoutName: effectiveLayout
+          inheritedLayout: effectiveLayout
         })
 
         if (result) {
@@ -1875,7 +1918,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           : parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`
 
         // Resolve layout for container page
-        const containerLayoutObj = typeof dirConfig.layout === 'object' && dirConfig.layout !== null ? dirConfig.layout : {}
 
         const containerPage = {
           route: containerRoute,
@@ -1895,11 +1937,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           hidden: dirConfig.hidden || false,
           hideIn: normalizeHideIn(dirConfig),
           ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
-          layout: {
-            ...(effectiveLayout ? { name: effectiveLayout } : {}),
-            ...(containerLayoutObj.hide ? { hide: containerLayoutObj.hide } : {}),
-            ...(containerLayoutObj.params ? { params: containerLayoutObj.params } : {}),
-          },
+          // `effectiveLayout` is ALREADY this container's resolved layout —
+          // `mergeLayoutConfig(parentLayout, normalizeLayoutConfig(dirConfig.layout))`
+          // — so re-reading `dirConfig.layout` here would drop the inherited half.
+          layout: effectiveLayout,
           seo: {
             noindex: dirConfig.seo?.noindex || false,
             image: dirConfig.seo?.image || null,
@@ -1959,9 +2000,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 
   // Second pass: process each page folder
   for (const folder of orderedFolders) {
-    const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayoutName } = folder
+    const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
     const isIndex = entry === indexPageName
-    const effectiveLayout = childLayoutName || parentLayoutName
+    const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
 
     if (dirMode === 'pages') {
       // Child directory switches to folder mode (has folder.yml) —
@@ -1971,7 +2012,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         : parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`
 
       // Resolve layout for container page
-      const containerLayoutObj = typeof dirConfig.layout === 'object' && dirConfig.layout !== null ? dirConfig.layout : {}
 
       const containerPage = {
         route: containerRoute,
@@ -1991,11 +2031,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         hidden: dirConfig.hidden || false,
         hideIn: normalizeHideIn(dirConfig),
         ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
-        layout: {
-          ...(effectiveLayout ? { name: effectiveLayout } : {}),
-          ...(containerLayoutObj.hide ? { hide: containerLayoutObj.hide } : {}),
-          ...(containerLayoutObj.params ? { params: containerLayoutObj.params } : {}),
-        },
+        // Already resolved — see the note on the sibling container above.
+        layout: effectiveLayout,
         seo: {
           noindex: dirConfig.seo?.noindex || false,
           image: dirConfig.seo?.image || null,
@@ -2026,7 +2063,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       // Sections mode — process directory as a page (existing behavior)
       const result = await processPage(entryPath, entry, siteRoot, {
         isIndex, parentRoute, parentFetch, versionContext,
-        layoutName: effectiveLayout
+        inheritedLayout: effectiveLayout
       })
 
       if (result) {
@@ -2095,11 +2132,19 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 /**
  * Load foundation schema data needed by the content collector.
  *
+ * `hasContentHandler` reports whether the foundation declares `handlers.content`
+ * — the hook that resolves `{…}` in page content. It is NOT used to decide
+ * anything about the build; its only consumer is the `placeholders:` warning at
+ * the call site, which needs to know whether a declared value has any reader.
+ * ⚠️ It cannot tell WHICH engine the handler uses (a handler is a function, and
+ * the build never calls it), so it answers "something could resolve this",
+ * never "Loom will".
+ *
  * @param {string} foundationPath - Path to foundation directory
- * @returns {Promise<{ vars: Object, layoutNames: Set<string> }>}
+ * @returns {Promise<{ vars: Object, layoutNames: Set<string>, hasContentHandler: boolean }>}
  */
 export async function loadFoundationInfo(foundationPath) {
-  if (!foundationPath) return { vars: {}, layoutNames: new Set() }
+  if (!foundationPath) return { vars: {}, layoutNames: new Set(), hasContentHandler: false }
 
   // ⛔ **NOT `dist/meta/schema.json`.** That file is the EDITOR's artifact — the
   // rich per-section declaration a visual editor needs to render parameter forms
@@ -2133,9 +2178,13 @@ export async function loadFoundationInfo(foundationPath) {
   // Two independent reads, so a failure in one does not cost the other. The
   // previous single try/catch lost the layouts when only the config was broken.
   let vars = {}
+  let hasContentHandler = false
   try {
     const config = await loadFoundationConfig(srcDir)
     vars = config?.vars || {}
+    // `loadFoundationConfig` spreads the module's default export, so `handlers`
+    // arrives intact even though it holds functions and never reaches schema.json.
+    hasContentHandler = typeof config?.handlers?.content === 'function'
   } catch (err) {
     console.warn(
       `[content-collector] Could not read the foundation's declared theme vars from ${srcDir}: ${err.message}\n` +
@@ -2154,7 +2203,7 @@ export async function loadFoundationInfo(foundationPath) {
     )
   }
 
-  return { vars, layoutNames }
+  return { vars, layoutNames, hasContentHandler }
 }
 
 /**
@@ -2372,7 +2421,27 @@ export async function collectSiteContent(sitePath, options = {}) {
   const rawThemeConfig = await readYamlFile(join(sitePath, 'theme.yml'))
 
   // Load foundation info (vars + layout names) and process theme
-  const { vars: foundationVars, layoutNames: layoutNames } = await loadFoundationInfo(foundationPath)
+  const { vars: foundationVars, layoutNames: layoutNames, hasContentHandler } =
+    await loadFoundationInfo(foundationPath)
+
+  // ⭐ `placeholders:` IS DECLARED FOR A READER THAT MAY NOT EXIST, and that is
+  // the one way this feature fails. Resolving `{…}` in page content is a
+  // FOUNDATION capability (`handlers.content`, normally @uniweb/loom), not
+  // something the framework does for every site — so on a foundation that
+  // declares no content handler the block is inert and the page renders the
+  // literal `{vendor.email}`. That reads as an authoring typo, which is why it
+  // is worth a build-time line rather than leaving the author to find it.
+  //
+  // ⚖️ A WARNING, never an error: the site may be mid-migration, or the author
+  // may be about to switch foundations, and a declared-but-unread value harms
+  // nothing. Same rule as the retired-`fetcher:` keys above — warn once, carry on.
+  if (siteConfig.placeholders && !hasContentHandler) {
+    console.warn(
+      `[uniweb] site.yml declares \`placeholders:\` but the foundation has no \`handlers.content\`, ` +
+        `so nothing will resolve them — pages will render the literal \`{name}\` text.\n` +
+        `[uniweb]   A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
+    )
+  }
   // `base` reaches the theme because self-hosted font faces are authored
   // root-relative (`/fonts/x.woff2`) and the emitted @font-face lives in an
   // inline <style> — under a subdirectory deployment it must carry the base.
@@ -2416,13 +2485,13 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Collect layout areas from layout/ directory (including named layout subdirectories)
   const { layouts } = await collectLayouts(layoutPath, sitePath, layoutNames)
 
-  // Site-level layout name (from site.yml layout: field)
-  const siteLayoutName = typeof siteConfig.layout === 'string' ? siteConfig.layout
-    : siteConfig.layout?.name || null
+  // Site-level layout (from `site.yml::layout`) — the ROOT of the cascade, and
+  // the whole object, not just its name.
+  const siteLayout = normalizeLayoutConfig(siteConfig.layout)
 
   // Recursively collect all pages
   let { pages, assetCollection, iconCollection, notFound, versionedScopes } =
-    await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, null, rootContentMode, mounts, siteLayoutName)
+    await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, null, rootContentMode, mounts, siteLayout)
 
   // Merge top-level config assets (e.g. document.yml's book.covers.front,
   // banner images, logos) into the manifest. The compile pipeline reads
@@ -2611,7 +2680,13 @@ export async function collectSiteContent(sitePath, options = {}) {
       ...(publishFilterActive && Array.isArray(siteConfig.languages)
         ? { languages: publishable }
         : {}),
-      fetch: parseFetchConfig(siteConfig.fetch),
+      // ⛔ `data:` IS THE SHORTHAND FOR `fetch:` AND BOTH LANES MUST READ IT.
+      // This read `siteConfig.fetch` alone until 2026-09-09, so a site-level
+      // `data: articles` reached a backend on the sync lane and was silently
+      // ignored on a static build — the works-on-one-lane shape. The page level
+      // has always used this helper (`pageConfig.fetch || fetchFromDataShorthand(…)`);
+      // the site level simply never did.
+      fetch: parseFetchConfig(siteConfig.fetch || fetchFromDataShorthand(siteConfig.data)),
       fetcher: warnRetiredFetcherKeys(siteConfig.fetcher),
       // NOTE: `intelligence.yml` was read here and emitted as `config.intelligence`.
       // Removed 2026-08-12 — the assistant surface is `site.yml::assistant`, which

package/src/uwx/site-project.js

@@ -108,22 +108,13 @@ const INFO_TO_SITE_YML = {
   // shape it is writing into — and it needs the build's own resolver to know, which is
   // why that check is not made here (it would drag the vite chain into `uwx/`).
   foundation: 'foundation',
-  languages: 'languages',
-  default_language: 'defaultLanguage',
   // Publish intent — verbatim both ways, dangling codes included (they carry
   // the preserved publish intent of a temporarily-undeclared language).
-  publish_languages: 'publishLanguages',
-  base: 'base',
   favicon: 'favicon',
-  fetcher: 'fetcher',
-  build: 'build',
-  search: 'search',
   // 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`.
-  submit: 'submit',
-  agents: 'agents',
   // 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.
@@ -144,17 +135,62 @@ const INFO_TO_SITE_YML = {
   // 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.
-  assistant: 'assistant',
   // 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.
-  tracking: 'tracking',
-  paths: 'paths',
-  data: 'data',
+  // ⛔ `data` IS NOT VERBATIM — see the explicit branch below. It projects to
+  // `site.yml::fetch`, not `site.yml::data`.
   template: 'template',
+  // ⭐ `tags` — authored, non-localized tokens; the filter facet for a list of site
+  // cards. Round-trips verbatim like any authored list.
+  tags: 'tags',
+  // ⛔ `url` and `preview_image` ARE DELIBERATELY ABSENT and must stay absent. Both are
+  // BACKEND-STAMPED — a site's live address and its card image URL are assigned by
+  // the host — so writing either into `site.yml` would launder a deploy-derived value
+  // into authored config, which is the hazard `submit` / `assistant` / `tracking` are
+  // annotated against above. Framework emits neither and must project neither.
+}
+
+// ── `settings` Section → site.yml ─────────────────────────────────────────────
+//
+// The `config` Section (see `site.js::configNested`) carries authored
+// configuration that does not belong on `info`. Each key maps to a
+// top-level `site.yml` key of the same name, verbatim, so the author's file
+// round-trips unchanged.
+//
+// ⛔ THIS MAP IS THE HALF THAT GETS LEFT OUT. The push side tests green entirely
+// on its own, so a missing entry here is invisible until someone pulls and finds
+// their block gone from site.yml. Every key `configNested` emits needs a line.
+//
+// 📌 `theme` will belong here after the stage-2 move off `info` — it is projected
+// to `theme.yml` (not site.yml) and so will need its own handling, not a row.
+const SETTINGS_TO_SITE_YML = {
+  placeholders: 'placeholders',
+  // The locale keys — moved, reverted and moved again on 2026-09-09; see `site.js`
+  // for why the middle step happened.
+  languages: 'languages',
+  default_language: 'defaultLanguage',
+  // Publish intent — verbatim both ways, dangling codes included (they carry the
+  // preserved publish intent of a temporarily-undeclared language).
+  publish_languages: 'publishLanguages',
+  base: 'base',
+  fetcher: 'fetcher',
+  build: 'build',
+  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
+  // offered through `config.services` and resolved at render, never entering the
+  // stored record.
+  search: 'search',
+  submit: 'submit',
+  assistant: 'assistant',
+  tracking: 'tracking',
+  agents: 'agents',
 }
 
+
 /**
  * Project a site-content document's `info` (+ `extensions`) onto the site's
  * config files: `site.yml`, `theme.yml`, and `head.html`. Idempotent; only the
@@ -170,6 +206,7 @@ const INFO_TO_SITE_YML = {
  */
 export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
   const info = document?.info || {}
+  const settingsSection = document?.settings || {}
 
   const siteChanges = {}
   // Localized text fields → unwrapped to the source locale (the target locales are
@@ -183,9 +220,9 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
 
   // `keywords` is a localized list (mirrors page keywords) → unwrap to the
   // source locale; the target locales are captured into the locales/ collector.
-  if (Array.isArray(info.keywords)) info.keywords.forEach((kw) => collector?.add(kw))
-  const keywords = unwrapLocalizedList(info.keywords, sourceLocale)
-  if (keywords !== undefined) siteChanges.keywords = keywords
+  // (`keywords` moved to the `settings` Section on 2026-09-09 — it renders into
+  // `<meta name="keywords">`, so it is seo by function. Handled with the rest of
+  // that Section below.)
 
   // Verbatim fields (includes `seo` — the site-level social/SEO block).
   for (const [infoKey, ymlKey] of Object.entries(INFO_TO_SITE_YML)) {
@@ -193,6 +230,37 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
     if (info[infoKey] !== undefined) siteChanges[ymlKey] = info[infoKey]
   }
 
+  // ⭐ `settings.fetch` → `site.yml::fetch`.
+  //
+  // `data:` is the authoring SHORTHAND for `fetch:` and the wire carries the
+  // desugared form, so `fetch:` is the key that describes what came back. The page
+  // lane has always projected this way (`y.fetch = authorableFetch(record.fetch)`);
+  // the site lane wrote `data:` verbatim, so an author who typed `fetch:` pushed,
+  // pulled, and got a `data:` block back — the value survived and the authored key
+  // did not, which the round-trip law forbids (uwx-format.md).
+  //
+  // ⛔ The producer always desugars, so the wire carries a config or a list of them —
+  // never a bare string. Nothing here accommodates an older shape.
+  const wireFetch = settingsSection.fetch
+  if (wireFetch !== undefined) {
+    siteChanges.fetch = Array.isArray(wireFetch)
+      ? wireFetch.map((f) => authorableFetch(f))
+      : authorableFetch(wireFetch)
+  }
+
+  // The `settings` Section — authored configuration that is not identity, so it is
+  // not on the brief. Same verbatim treatment as the `info` block above; a Section
+  // the document does not carry writes nothing, like every other absent key here.
+  for (const [settingsKey, ymlKey] of Object.entries(SETTINGS_TO_SITE_YML)) {
+    if (settingsSection[settingsKey] !== undefined) siteChanges[ymlKey] = settingsSection[settingsKey]
+  }
+
+  // `settings.keywords` is a LOCALIZED list (it renders into `<meta name="keywords">`)
+  // → unwrap to the source locale; the target locales go to the collector.
+  if (Array.isArray(settingsSection.keywords)) settingsSection.keywords.forEach((kw) => collector?.add(kw))
+  const settingsKeywords = unwrapLocalizedList(settingsSection.keywords, sourceLocale)
+  if (settingsKeywords !== undefined) siteChanges.keywords = settingsKeywords
+
   // extensions[] → site.yml::extensions. Each entry carries EITHER `ref` (a
   // catalog ref or a local name — an extension is a foundation and is declared
   // like one) OR `url`. Project back whichever is present so a ref survives a
@@ -236,18 +304,22 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
   const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
 
   // theme (whole object) → theme.yml.
-  if (info.theme && typeof info.theme === 'object') {
-    result.theme = writeThemeFile(siteRoot, info.theme)
+  if (settingsSection.theme && typeof settingsSection.theme === 'object') {
+    result.theme = writeThemeFile(siteRoot, settingsSection.theme)
   }
 
   // head_html → head.html (a raw file, not YAML).
-  if (info.head_html != null) {
-    result.headHtml = writeIfChanged(join(siteRoot, 'head.html'), info.head_html)
+  if (settingsSection.head_html != null) {
+    result.headHtml = writeIfChanged(join(siteRoot, 'head.html'), settingsSection.head_html)
   }
 
   // `info.favicon` rides the verbatim INFO_TO_SITE_YML map above (→ site.yml).
-  // `info.assets` is intentionally NOT projected: it is a build-derived upload
-  // manifest, not authored config, so a pull never writes it back to the site.
+  // ⛔ `info.assets` WAS DELETED FROM THE MODEL (2026-09-09), along with `app`,
+  // `data_bundle` and `foundation_schema`. It had been a build-derived upload
+  // manifest that a pull deliberately never wrote back; framework never populated
+  // it. Nothing to project, and nothing here to remove — the note is kept because
+  // `assets.json` (the committed local path → id map) is a DIFFERENT thing and the
+  // two get confused.
 
   return result
 }

package/src/uwx/site.js

@@ -52,6 +52,7 @@ import {
   parseWildcardArray,
   applyWildcardOrder,
   processMarkdownFile,
+  fetchFromDataShorthand,
 } from '../site/content-collector.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
@@ -223,11 +224,7 @@ function buildPageData(config, ctx) {
   // ⭐ A `data:` LIST means "fetch each" — one declaration per entry. Before
   // 2026-09-02 this kept `[0]` and dropped the rest silently, so the wire
   // carried one dataset for a page that asked for several.
-  let fetch =
-    config.fetch ??
-    (config.data
-      ? (Array.isArray(config.data) ? config.data.map((query) => ({ query })) : { query: config.data })
-      : undefined)
+  let fetch = config.fetch ?? fetchFromDataShorthand(config.data)
   // Resolve the authored `query:` shorthand to the runtime-fetchable
   // `path: /data/<name>.json` (the static convention the default-fetcher uses).
   // A shell/backend-hosted site renders client-side with NO prerender, so the
@@ -955,6 +952,115 @@ function secretsNested(siteYml) {
   )
 }
 
+// ── `settings` — the site's authored configuration ────────────────────────────
+//
+// ⭐ THE LINE IS IDENTITY vs CONFIGURATION. `info` answers *"which site is this?"* —
+// the name/label record a card or a select dropdown renders, and the set a listing
+// can filter on. `settings` answers *"what does this site render with?"*.
+//
+// A `single` Section: one record, each block verbatim under its own key. Verbatim is
+// the point — the authored shape is a nested map and it comes back as one, so
+// nothing has to be flattened on push or rebuilt on pull.
+//
+// ⚠️ AUTHORS NEVER SEE THIS NAME. It is a wire and Model name; `site-project.js`
+// writes each key back to its authored home (`site.yml`, `theme.yml`, `head.html`).
+// So it is named flatly for what it holds, like `pages` / `queries` / `records`.
+//
+// ⛔ NEVER EMIT `{}`. On a `single` Section the value must be an object, so `{}` is
+// ONE RECORD WITH NO FIELDS, not zero records — there is no `[]` analogue. With
+// nineteen fields on it, `{}` means *clear all nineteen*. Emit only what the file
+// declares; if an explicit clear is ever wanted, ask backend for a real form rather
+// than inferring one from an empty object.
+//
+// ⛔ AND EVERY KEY HERE MUST ROUND-TRIP — an authored value that reaches the server
+// and cannot come back is data loss with a delay on it (uwx-format.md § THE
+// ROUND-TRIP LAW). `site-project.js::SETTINGS_TO_SITE_YML` plus its explicit
+// branches is the other half, and `producer-list-drift.test.js` fails if a key
+// emitted here has neither.
+function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations } = {}) {
+  const settings = {}
+
+  // Site-wide values an author declares once and references from page content as
+  // ordinary Loom variables (`{vendor.email}`). The Section's first field.
+  setIf(settings, 'placeholders', siteYml.placeholders)
+
+  // Verbatim authored blocks. ⭐ `theme` is `theme.yml` VERBATIM — the built theme
+  // is computed (defaults filled, palettes generated), so comparing the two shows a
+  // difference every time and a propagation check has to say which artifact it holds.
+  if (themeYml && Object.keys(themeYml).length > 0) settings.theme = themeYml
+  setIf(settings, 'head_html', headHtml)
+  setIf(settings, 'fetcher', siteYml.fetcher)
+  setIf(settings, 'build', siteYml.build)
+  setIf(settings, 'paths', siteYml.paths)
+  setIf(settings, 'base', siteYml.base)
+
+  // Locale configuration.
+  //
+  // ⚠️ THESE MOVED, WERE REVERTED, AND MOVED AGAIN IN ONE DAY — the history is here
+  // so nobody re-litigates it from half of it. Backend refused the move on a measured
+  // constraint: three call sites read these off `entity.brief`, and their
+  // default-locale accessor falls back to `"en"` without erroring, so moving them
+  // would have resolved every site to English silently. Framework reverted.
+  //
+  // ⭐ The constraint had already been LIFTED when the refusal was written. Backend
+  // had reworked those readers to take the stored Item through a name-keyed accessor
+  // rather than the brief, then made the move (generation 15) — and did not withdraw
+  // the refusal. So framework reverted against a rule its author had personally
+  // retired an hour earlier. **The fixture was current; the message was stale.**
+  //
+  // ⇒ `settings` is where they live. `publish_languages` rides VERBATIM, dangling
+  // codes included: sync carries the full working set and only *publish* filters,
+  // which preserves a locale's publish intent across a remove + re-add in `languages:`.
+  setIf(settings, 'languages', siteYml.languages)
+  setIf(settings, 'default_language', siteYml.defaultLanguage)
+  setIf(settings, 'publish_languages', siteYml.publishLanguages)
+
+  // SEO. ⛔ `seo` is SIX crawler/sitemap directives and one card field — `image`,
+  // `ogTitle`, `ogDescription`, `noindex`, `canonical`, `changefreq`, `priority`
+  // (`core/src/seo.js`). Two of those are literally sitemap.xml columns. It only
+  // ever passed the card test because `image` was inside it; the card's picture is
+  // `info.preview_image` now.
+  setIf(settings, 'seo', siteYml.seo)
+  // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
+  // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
+  // convenience, not because it is a different kind of thing. Localized, so it
+  // 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.
+  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'))
+
+  // Projections opt-out + route exclusions. Carried because the app is a second
+  // PUBLISHER of projections and derives them from stored content: without this 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.
+  setIf(settings, 'agents', siteYml.agents)
+
+  // ⭐ The site-level fetch, DESUGARED and under its real name. `data:` is the
+  // authoring shorthand for `fetch:` and every other tier already calls the wire
+  // field `fetch`; the site tier called it `data` until 2026-09-09.
+  setIf(settings, 'fetch', siteYml.fetch ?? fetchFromDataShorthand(siteYml.data))
+
+  // ⭐ The SITE TIER of framework's own `{name, hide, params}` layout object, which
+  // the page and folder tiers have always had. `hide` is a non-destructive per-area
+  // disable the runtime honours (`core/src/page.js`). Framework read only `.name`
+  // at this tier and emitted nothing at all until 2026-09-09; the app had been
+  // editing the field on the server with framework unable to see or carry it.
+  setIf(settings, 'layout', siteYml.layout)
+
+  return Object.keys(settings).length > 0 ? settings : undefined
+}
+
 /**
  * Map a file site project to the nested `@uniweb/site-content` `$`-document
  * (see the lane header above). PURE — reads the project, never mints, never writes.
@@ -1023,19 +1129,14 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // title/slug/label/keywords, the body) stay localized. (uwx-format.md → identity-label names.)
   info.name = siteYml.name
   setIf(info, 'description', localizeScalar(siteYml.description, sourceLocale, translations))
-  if (themeYml && Object.keys(themeYml).length > 0) info.theme = themeYml
-  setIf(info, 'languages', siteYml.languages)
-  setIf(info, 'default_language', siteYml.defaultLanguage)
   // Publish intent (site.yml `publishLanguages:`) rides VERBATIM — dangling
   // codes included. Sync carries the full working set; only *publish* filters
   // (backend projection / static-build filter). The verbatim carry is what
   // preserves a locale's publish intent across a remove + re-add in
   // `languages:` (uwx-format.md → "Per-locale publish readiness").
-  setIf(info, 'publish_languages', siteYml.publishLanguages)
   // `foundation` (required) — the verbatim `site.yml::foundation` string
   // (registry ref / URL / local path), the round-trip source of truth.
   info.foundation = siteYml.foundation
-  setIf(info, 'base', siteYml.base)
   // favicon — a verbatim URL/path string. ⚠️ This comment claimed "the kit
   // resolves it, like other media refs" until 2026-08-17; measured, `favicon`
   // appears nowhere in `kit/src` or `runtime/src`. The real consumer is
@@ -1047,32 +1148,33 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //
   // `assets` is a build-DERIVED upload manifest, not authored config, so it
   // is never produced from / projected to the site files.
+  //
+  // ⛔ AND `info.assets` IS GONE — deleted from the Model 2026-09-09 with `app`,
+  // `data_bundle` and `foundation_schema`. Framework never stamped it; the only
+  // deploy-derived `info` field framework sends is `foundation`, via `injectInfo`
+  // in `publish`.
+  //
+  // ⚠️ The note stays because `assets.json` — the COMMITTED local map from an
+  // author's asset path to the backend's content-addressed id — is a different
+  // thing with a similar name, and it is very much alive.
   setIf(info, 'favicon', siteYml.favicon)
   // Site-level SEO/social metadata — the same shape as page.yml's `seo:` + the
   // top-level `keywords`, hoisted to the site root so the homepage social card
   // 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).
-  setIf(info, 'seo', siteYml.seo)
-  setIf(info, 'keywords', localizeScalarList(siteYml.keywords, sourceLocale, translations))
-  setIf(info, 'head_html', headHtml)
-  setIf(info, 'fetcher', siteYml.fetcher)
-  setIf(info, 'build', siteYml.build)
-  setIf(info, 'search', siteYml.search)
   // `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.
-  setIf(info, 'submit', siteYml.submit)
   // `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.)
-  setIf(info, 'agents', siteYml.agents)
   // `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
@@ -1088,7 +1190,6 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // line.
   //
   // ⛔ Credentials are stripped, not trusted — see `stripCredentials`.
-  setIf(info, 'assistant', stripCredentials(siteYml.assistant, 'assistant'))
   // `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
@@ -1102,7 +1203,6 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // (`https://collector/e?key=…`) is invisible here and is disclosed. The host's
   // secret store is the only right home either way.
 
-  setIf(info, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
   // ⛔ `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.
@@ -1122,8 +1222,28 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // with the RIGHT one.
   //
   // The provisioned record rides the `$services` section instead (see servicesNested).
-  setIf(info, 'paths', siteYml.paths)
-  setIf(info, 'data', siteYml.data ?? siteYml.fetch)
+  // ⭐ DESUGARED, like every other tier. `data:` is the shorthand for `fetch:`
+  // (`data: articles` → `{ query: 'articles' }`), and the page level has always
+  // desugared before emitting. The site level shipped the bare string until
+  // 2026-09-09, so `info.data` carried two different shapes depending on which
+  // key the author happened to type.
+  //
+  // 📌 The wire NAME is still `data` and becomes `fetch` when the Section moves —
+  // renaming it now would be a second destructive wire change for a cosmetic gain;
+  // renaming it during the move is free.
+  // ⛔ 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
+  // 2026-09-09 because a brief was never meant to carry configuration.
+  //
+  // ⛔ AND THIS ALLOWLIST IS A KNOWN LIABILITY, not a design to copy. `info` is built
+  // from a fixed list of keys framework knows, so any AUTHORED field on the Model that
+  // framework does not model is dropped on pull and — on a Section that replaces
+  // wholesale — destroyed on push, silently. That is what `queriesNested` uses a
+  // DENY-list to avoid ("EMIT WHAT WE DO NOT MODEL"), and it is illegal under the
+  // round-trip law (uwx-format.md). `info.layout` was the live instance and has now
+  // moved to `settings`; the general defect is open.
+  //
   // ⛔ `app` IS RETIRED — do not reintroduce it, in either direction. It carried an
   // opaque uuid naming a separate entity a host bound to the site; that entity is
   // gone, a site's services belong to the site itself, and NOTHING replaces the key.
@@ -1139,6 +1259,19 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // backend applies a clonability designation to this site-content entity (it is
   // NOT a registry artifact). Verbatim; absent → a normal (non-template) site.
   setIf(info, 'template', siteYml.template)
+  // ⭐ `tags` — the filter facet for a list of site cards, chiefly the template
+  // picker. An array of NON-LOCALIZED tokens (`[academic, portfolio]`); the site
+  // never renders them and carries no labels for them, because the chip a user
+  // reads belongs to the picker and is translated app-side from a vocabulary it
+  // knows. Two filterings were being discussed as one: the picker filters in JS
+  // over an already-fetched list and never asks the database, while a DB-filterable
+  // facet is separately useful — only the second needs a predicable brief field.
+  setIf(info, 'tags', siteYml.tags)
+  // ⛔ `url` and `preview_image` are BACKEND-STAMPED and framework emits NEITHER.
+  // A site's live address is assigned at publish and its card image needs a servable
+  // URL; a serve location is a per-response answer the host owns — read, never
+  // constructed. `site-project.js` must also never write them into `site.yml`, or a
+  // pull launders a deploy-derived value into authored config.
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages
@@ -1177,6 +1310,9 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   doc.$id = SITE_ENTITY_KEY // one site-content entity per project (stable handle)
   doc.$model = SITE_MODEL_NAME
   doc.info = info
+  // Emitted only when the file declares something — see `settingsNested`.
+  const settings = settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translations })
+  if (settings) doc.settings = settings
   doc.pages = pages
   doc.layout_sections = layoutSections
   doc.extensions = extensionsNested(siteYml)
@@ -1191,9 +1327,26 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.
-  const services = servicesNested(siteYml)
+  //
+  // ⭐ 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.
+  //
+  // ⚖️ Default is to declare, so every existing caller is unchanged and the
+  // withholding is opt-in.
+  const declare = opts.declareServices !== false
+  const services = declare ? servicesNested(siteYml) : undefined
   if (services) doc.services = services
-  const secrets = secretsNested(siteYml)
+  const secrets = declare ? secretsNested(siteYml) : undefined
   if (secrets) doc.secrets = secrets
   return doc
 }

package/src/uwx/sync-package.js

@@ -220,8 +220,13 @@ function rewriteEntityAssets(node, map, ids) {
  *        to push unconditionally — that IS the force path.
  * @param {boolean} [opts.includeSite]    - include the site-content lane (default true)
  * @param {object} [opts.injectInfo]      - deploy-derived `info.*` to stamp on the
- *        site-content document (e.g. `{ data_bundle }`, the static-data ball URL);
- *        wire-only — never authored in site.yml, never projected back on pull.
+ *        site-content document. ⭐ TODAY THAT IS `{ foundation }` AND NOTHING ELSE —
+ *        the released ref, stamped by `publish` when it releases a local foundation.
+ *        Deploy-derived means wire-only: never authored in site.yml, never projected
+ *        back on pull, which is the round-trip law's derived exception.
+ *        ⚠️ This example read `{ data_bundle }` until 2026-09-09; that field was
+ *        RETIRED 2026-08-18 (the static-data ball is gone — collection data lands at
+ *        its serving tail), so the example named a key nothing emits.
  * @param {Object<string,string>} [opts.injectExtensions] - authored extension
  *        declaration (`$id`) → the pinned `@scope/name@version` to stamp over it.
  *        `publish` fills this for the site's LOCAL extensions after releasing them;
@@ -305,13 +310,22 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const siteDoc = includeSite
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
-        ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {})
+        ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
+        // 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`.
+        ...(opts.declareServices === false ? { declareServices: false } : {})
       })
     : null
-  // Deploy-derived `info` fields (e.g. `data_bundle`, the static-data ball URL) are
-  // stamped here — NOT authored in site.yml, so they ride the wire but never project
-  // back on pull (the `info.assets` precedent). They are part of the hashed content,
-  // so a changed bundle URL correctly re-fires the site-content lane.
+  // Deploy-derived `info` fields are stamped here — NOT authored in site.yml, so they
+  // ride the wire but never project back on pull. They are part of the hashed content,
+  // so a changed value correctly re-fires the site-content lane.
+  //
+  // ⭐ TODAY THE SET IS `{ foundation }` AND NOTHING ELSE. ⚠️ This comment named
+  // `data_bundle` (retired 2026-08-18) as the example and `info.assets` as the
+  // precedent; framework stamps neither, so both were pointing a reader at keys this
+  // producer does not write.
   const injectInfo =
     opts.injectInfo && typeof opts.injectInfo === 'object' ? opts.injectInfo : null
   if (siteDoc && injectInfo) {