@uniweb/build 0.45.0 → 0.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.45.0",
+  "version": "0.46.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.4.0",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/schemas": "^0.2.13",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.6.1",
-    "@uniweb/schemas": "^0.2.13",
-    "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.20.0"
+    "@uniweb/runtime": "^0.20.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.25.0"
+    "@uniweb/core": "^0.25.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -129,7 +129,7 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
   const fetched = { site: new Map(), pages: new Map(), sections: new Map() }
 
   // 1. Site-level fetch. ⛔ `toFetchList` rather than a property read: a `fetch:`
-  // or `data:` LIST parses to an array, and `siteFetch.prerender` on one is
+  // or `query:` LIST parses to an array, and `siteFetch.prerender` on one is
   // `undefined` — which passes the `!== false` test and then fetches nothing.
   for (const oneFetch of toFetchList(siteContent.config?.fetch)) {
     if (oneFetch.prerender === false) continue

package/src/site/content-collector.js

@@ -24,7 +24,7 @@
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
-import { join, parse, resolve, sep } from 'node:path'
+import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
@@ -220,27 +220,86 @@ function detectVersions(folderNames) {
 }
 
 /**
- * Desugar a `data:` declaration into a `fetch:` one.
- *
- * `data: team` → `{ query: 'team' }`; `data: [team, articles]` → one config per
- * entry. ⭐ **A list means "fetch each"** — see `parseFetchConfig` for why the
- * declaration is plural by necessity and why that is not a statement about
- * request count.
+ * `query:` — the shorthand for `fetch: { query }`, at every level that declares
+ * data: a section's frontmatter, `page.yml`, `folder.yml` and `site.yml`, on the
+ * build and on the sync push alike. It names a query, or a list of them — "fetch
+ * each", one `content.data` key per name (see `parseFetchConfig` for why a
+ * declaration is plural and why that says nothing about request count). Anything
+ * richer — a `limit`, a `where`, a source — is `fetch:`.
+ *
+ * ⛔ `data:` WAS THIS KEY until 2026-09-11 [Diego], and it is REFUSED, not
+ * ignored: in frontmatter an unreserved key becomes a section param, so a stale
+ * `data:` would render an empty section and say nothing. The word stays where it
+ * names the data itself — a section type's `meta.js` `data:` (the shape of each
+ * `content.data` key, which fetches nothing) and `content.data`.
+ *
+ * ⛔ `query:` beside `fetch:` is refused too. It was silent — `fetch:` won, and
+ * the other declaration was dropped with nothing saying so.
+ *
+ * @param {Object|null|undefined} config - the level's authored config
+ * @param {string} where - the file it was authored in, for the message
+ * @returns {Object|Array<Object>|undefined} the level's `fetch:` declaration, as authored
+ */
+export function declaredFetch(config, where) {
+  checkDeclaration(config, where)
+  return config?.fetch ?? fetchFromQueryShorthand(config?.query)
+}
+
+/**
+ * The refusals `declaredFetch` makes, alone — for a reader that must keep the
+ * desugaring inline (the sync push's `settings.fetch`, whose sources
+ * `scripts/gen-emit-surface.mjs` reads off the expression).
  *
- * ⛔ Before 2026-09-02 a list kept `[0]` and dropped the rest **silently**: no
- * warning, no error, and the array was not carried forward on the section, so
- * nothing downstream could recover it. An author writing a list got one dataset
- * and a section rendering empty.
+ * @param {Object|null|undefined} config
+ * @param {string} where
+ */
+export function checkDeclaration(config, where) {
+  if (!config || typeof config !== 'object') return
+  if (config.data !== undefined) {
+    const other = config.query !== undefined ? 'query' : config.fetch !== undefined ? 'fetch' : null
+    throw new Error(
+      other
+        ? `[uniweb] ${where}: \`data:\` is retired, and this file already declares \`${other}:\` — delete the \`data:\` line.`
+        : `[uniweb] ${where}: \`data:\` is retired — the shorthand for \`fetch: { query }\` is now \`query:\`. ` +
+            `Write \`query: ${formatQueryNames(config.data)}\`.`
+    )
+  }
+  if (config.query !== undefined && config.fetch !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: declare \`query:\` or \`fetch:\`, not both — \`query: x\` is the shorthand for \`fetch: { query: x }\`.`
+    )
+  }
+  if (config.query !== undefined && !isQueryNames(config.query)) {
+    const declaring = config.query && typeof config.query === 'object' && !Array.isArray(config.query)
+    throw new Error(
+      `[uniweb] ${where}: \`query:\` takes a query name or a list of names; anything richer is \`fetch:\` — ` +
+        `e.g. \`fetch: { query: articles, limit: 3 }\`.` +
+        (declaring ? ' Declaring queries? That is `queries:` (in site.yml) or queries.yml.' : '')
+    )
+  }
+}
+
+/**
+ * Desugar a `query:` value: `team` → `{ query: 'team' }`, `[team, articles]` →
+ * one config per name. ⛔ Before 2026-09-02 a list kept `[0]` and dropped the rest
+ * silently — an author writing a list got one dataset and a section rendering
+ * empty.
  *
- * @param {string|Array<string>|undefined} data
+ * @param {string|Array<string>|undefined|null} query - already checked (`checkDeclaration`)
  * @returns {Object|Array<Object>|undefined}
  */
-export function fetchFromDataShorthand(data) {
-  if (!data) return undefined
-  if (Array.isArray(data)) return data.map((query) => ({ query }))
-  return { query: data }
+export function fetchFromQueryShorthand(query) {
+  if (query === undefined || query === null) return undefined
+  if (Array.isArray(query)) return query.map((name) => ({ query: name }))
+  return { query }
 }
 
+const isQueryName = (name) => typeof name === 'string' && name.trim() !== ''
+const isQueryNames = (value) =>
+  isQueryName(value) || (Array.isArray(value) && value.length > 0 && value.every(isQueryName))
+const formatQueryNames = (value) =>
+  isQueryNames(value) ? (Array.isArray(value) ? `[${value.join(', ')}]` : value) : '<name>'
+
 /**
  * Build version metadata from detected versions and page.yml config
  * @param {Array<Object>} detectedVersions - Detected version infos
@@ -280,7 +339,7 @@ function buildVersionMetadata(detectedVersions, pageConfig = {}) {
  * this function reads `site.yml`, `page.yml`, `folder.yml`, `theme.yml` and
  * every section's frontmatter — i.e. every configuration surface an author
  * writes. So a single typo silently discarded that file's entire contribution:
- * page order, nesting, `sections:`, `data:` declarations, theme. **The build
+ * page order, nesting, `sections:`, `query:` declarations, theme. **The build
  * succeeded and shipped a site missing what the author asked for**, with one
  * line on stderr that named no file.
  *
@@ -965,7 +1024,9 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     console.warn(`[content-collector] ${err.message}`)
   }
 
-  const { type, preset, input, props, fetch, data, id: frontmatterId, ...params } = frontMatter
+  // `query`, `fetch` and `data` are never params: `query:` / `fetch:` declare the
+  // section's own data, and a leftover `data:` is refused (`declaredFetch`).
+  const { type, preset, input, props, fetch, query, data, id: frontmatterId, ...params } = frontMatter
 
   // Convert markdown to ProseMirror
   const proseMirrorContent = markdownToProseMirror(markdown)
@@ -973,28 +1034,13 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // Extract @ component references → insets (mutates doc)
   const insets = extractInsets(proseMirrorContent)
 
-  // `data:` shorthand — `data: team` → `fetch: { query: team }`.
-  //
-  // ⛔ **A LIST KEEPS ONLY `[0]`. THE REST ARE INERT.** This comment used to say
-  // *"others via inheritData"*, and that is wrong in a way worth spelling out,
-  // because it read as a mechanism and was copied into a second doc as one.
-  //
-  // `inheritData` is a BOOLEAN OPT-OUT on a section's `meta.js`
-  // (`meta.inheritData === false` → deliver nothing). It never consumed list
-  // elements. What actually happens is that delivery is default-on and
-  // collect-all: `EntityStore._getRequestedSchemas` returns `[]`, so a section
-  // receives EVERY fetch config in the section → page → site cascade whether or
-  // not it named any of them.
-  //
-  // ⇒ So `articles` arrives only if something ELSE already declared a fetch for
-  // it — in which case this section would have received it anyway. **Naming it
-  // here contributes nothing.** Measured 2026-09-02: `data: [team, articles]`
-  // with no other declaration yields exactly one config, `team`, and the array
-  // is not carried forward on the section, so nothing downstream can recover it.
-  //
-  // ⚠️ The list form appears in no `docs/` page, so nothing promises it works.
-  // Whether it should mean "fetch each" or be refused outright is undecided.
-  const resolvedFetch = fetch || fetchFromDataShorthand(data)
+  // `query: team` → `fetch: { query: team }`; a list, one config per name, each
+  // delivered under its own `content.data` key — the one helper every level uses.
+  // Unrelated to a section type's `meta.js` `data:`, which declares the SHAPE of
+  // each `content.data` key and fetches nothing: delivery is default-on, so a
+  // section receives every fetch in the section → page → site cascade whether or
+  // not it names one here.
+  const resolvedFetch = declaredFetch({ fetch, query, data }, relative(siteRoot, filePath))
 
   // Stable ID for scroll targeting: frontmatter id > filename-derived > null
   // This ID is stable across reordering (unlike the positional id)
@@ -1619,12 +1665,8 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
         priority: seo.priority || null
       },
 
-      // Data fetching
-      // Support 'data:' shorthand at page level
-      // data: team → fetch: { query: team }
-      fetch: parseFetchConfig(
-        pageConfig.fetch || fetchFromDataShorthand(pageConfig.data)
-      ),
+      // Data fetching — `fetch:`, or the `query:` shorthand (`declaredFetch`)
+      fetch: parseFetchConfig(declaredFetch(pageConfig, relative(siteRoot, join(pagePath, 'page.yml')))),
 
       hasContent: hierarchicalSections.length > 0,
       sections: hierarchicalSections
@@ -1987,7 +2029,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
             changefreq: dirConfig.seo?.changefreq || null,
             priority: dirConfig.seo?.priority || null
           },
-          fetch: parseFetchConfig(dirConfig.fetch) || null,
+          // ⭐ `declaredFetch`, as every other level: this read `dirConfig.fetch`
+          // alone until 2026-09-11, so a container's `folder.yml` shorthand reached
+          // a backend on `push` and was dropped from a static build.
+          fetch: parseFetchConfig(declaredFetch(dirConfig, relative(siteRoot, join(entryPath, 'folder.yml')))) || null,
           hasContent: false,
           sections: [],
           order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
@@ -2079,7 +2124,12 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           changefreq: dirConfig.seo?.changefreq || null,
           priority: dirConfig.seo?.priority || null
         },
-        fetch: null,
+        // ⭐ The folder's own declaration, as the folder-mode container above and
+        // every other level read it. ⛔ This was `fetch: null` until 2026-09-11:
+        // a `folder.yml` here lost its `fetch:` (and its shorthand) on a static
+        // build while `push` carried it, so its pages had the folder's data on a
+        // hosted site and none on an exported one.
+        fetch: parseFetchConfig(declaredFetch(dirConfig, relative(siteRoot, join(entryPath, 'folder.yml')))) || null,
         hasContent: false,
         sections: [],
         order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
@@ -2091,8 +2141,11 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         pages.push(containerPage)
       }
 
+      // The container's own fetch config, or the parent's — as the folder-mode
+      // container above passes it.
       const childDirPath = mounts?.get(entry) || entryPath
-      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, parentFetch, versionContext, 'pages', null, effectiveLayout)
+      const containerFetch = containerPage.fetch || parentFetch
+      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, 'pages', null, effectiveLayout)
       pages.push(...subResult.pages)
       assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
       iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2656,7 +2709,9 @@ export async function collectSiteContent(sitePath, options = {}) {
   // `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).
-  const { publishLanguages: _publishLanguages, ...runtimeSiteConfig } = siteConfig
+  // 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 are the project's BACKEND-SCOPED state — `$uuid`, `$org`,
   // `$backend`, `$services`, `$secrets` — and this payload is a PUBLISHED artifact
   // that a visitor can fetch. They have no runtime reader (nothing in core, runtime
@@ -2700,7 +2755,7 @@ export async function collectSiteContent(sitePath, options = {}) {
       `${distinctFailures.length} file${distinctFailures.length === 1 ? '' : 's'} could not be parsed as YAML:\n` +
         `${lines.join('\n')}\n\n` +
         `  Each one contributed NOTHING to this build — page order, nesting,\n` +
-        `  sections:, data: and theme settings in these files were dropped.\n` +
+        `  sections:, query: and theme settings in these files were dropped.\n` +
         `  Fix them and rebuild; the dev server reports the same files without failing.`
     )
   }
@@ -2720,13 +2775,12 @@ export async function collectSiteContent(sitePath, options = {}) {
       ...(publishFilterActive && Array.isArray(siteConfig.languages)
         ? { languages: publishable }
         : {}),
-      // ⛔ `data:` IS THE SHORTHAND FOR `fetch:` AND BOTH LANES MUST READ IT.
+      // ⛔ `query:` 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)),
+      // shorthand reached a backend on the sync lane and was silently ignored on
+      // a static build — the works-on-one-lane shape. Every level reads it
+      // through `declaredFetch` now.
+      fetch: parseFetchConfig(declaredFetch(siteConfig, 'site.yml')),
       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/site/data-fetcher.js

@@ -274,9 +274,9 @@ export function toFetchList(fetch) {
 }
 
 /**
- * Parse a `fetch:` (or desugared `data:`) declaration.
+ * Parse a `fetch:` (or desugared `query:`) declaration.
  *
- * ⭐ **A LIST MEANS "FETCH EACH".** `data: [team, articles]` declares two needs
+ * ⭐ **A LIST MEANS "FETCH EACH".** `query: [team, articles]` declares two needs
  * and they land under two keys in `content.data` — a component reads
  * `content.data.team` and `content.data.articles` independently, so the
  * declaration is plural by necessity.

package/src/site/fetch-shapes.js

@@ -69,3 +69,57 @@ export function authorableFetch(fetch) {
   }
   return out
 }
+
+// ── `query:` or `fetch:` — the key a projection writes back ─────────────────────
+//
+// An author declares a level's data with `fetch:` or with its shorthand, `query:`
+// (`query: team` ≡ `fetch: { query: team }`). The wire carries only the desugared
+// form, so it cannot say which key was typed — and a pull must give back the
+// authored KEY as well as the value (the round-trip law of the sync format). So a
+// projection writes back the key the file already uses, and a file it creates gets
+// `query:` whenever the declaration is nothing but query names — the form the
+// docs teach. The declaration keys are one group: exactly one is written, and a
+// file holding both is refused by the build.
+
+/** The keys that declare a level's data: the long form, its shorthand, and the retired shorthand. */
+export const DECLARATION_KEYS = Object.freeze(['query', 'fetch', 'data'])
+
+/**
+ * The query names a declaration consists of, when that is ALL it says — what
+ * `query:` can express. Keys the build derives or defaults beside a query (`path`,
+ * `url`, `as` equal to the name, `prerender: true`, `merge: false`) say nothing an
+ * author wrote; any other key makes it a `fetch:`.
+ *
+ * @param {object|object[]} fetch - a declaration (or a list) off the wire
+ * @returns {string|string[]|null} the name(s), or null when `query:` cannot say it
+ */
+export function queryNamesOf(fetch) {
+  const nameOf = (one) => {
+    if (!one || typeof one !== 'object' || typeof one.query !== 'string' || one.query === '') return null
+    for (const [key, value] of Object.entries(one)) {
+      if (key === 'query' || key === 'path' || key === 'url') continue
+      if (key === 'as' && value === one.query) continue
+      if (key === 'prerender' && value === true) continue
+      if (key === 'merge' && value === false) continue
+      return null
+    }
+    return one.query
+  }
+  if (!Array.isArray(fetch)) return nameOf(fetch)
+  const names = fetch.map(nameOf)
+  return names.length > 0 && names.every((n) => n !== null) ? names : null
+}
+
+/**
+ * The declaration to write back, and under which key.
+ *
+ * @param {object|object[]} wireFetch - the level's `fetch` off the wire
+ * @param {object|null} [existing] - the authored file's current keys; null for a new file
+ * @returns {{ key: 'query'|'fetch', value: string|string[]|object|object[] }}
+ */
+export function authorableDeclaration(wireFetch, existing = null) {
+  const fetch = Array.isArray(wireFetch) ? wireFetch.map((one) => authorableFetch(one)) : authorableFetch(wireFetch)
+  const names = queryNamesOf(fetch)
+  const typedFetch = !!existing && typeof existing === 'object' && existing.fetch !== undefined
+  return names !== null && !typedFetch ? { key: 'query', value: names } : { key: 'fetch', value: fetch }
+}

package/src/site/query-processor.js

@@ -147,7 +147,7 @@ function parseQueryConfig(name, config) {
     },
     // `deferred:` lists fields that are heavy (article body, full nested
     // arrays). Those fields are stripped from the cascade payload that
-    // ships with `data: <name>` declarations, and per-record full files
+    // ships with `query: <name>` declarations, and per-record full files
     // are emitted at public/data/<name>/<slug>.json. Components that
     // need the full record fetch the per-record file on demand, either
     // automatically on dynamic-route pages (entity-store routes the
@@ -913,7 +913,7 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
     if (deferred && deferred.length > 0) {
       // `deferred:` is set — emit two payloads:
       //   1. The cascade JSON at /data/<name>.json with deferred fields stripped.
-      //      This is what `data: <name>` declarations deliver everywhere.
+      //      This is what `query: <name>` declarations deliver everywhere.
       //   2. Per-record full files at /data/<name>/<slug>.json with every field.
       //      Dynamic-route singular fetches and useEntityDetail hooks read these.
       const recordsDir = join(dataDir, name)

package/src/uwx/emit-surface.json

@@ -62,7 +62,7 @@
         ],
         "fetch": [
           "site.yml::fetch",
-          "site.yml::data"
+          "site.yml::query"
         ],
         "fetcher": [
           "site.yml::fetcher"

package/src/uwx/project-writer.js

@@ -19,15 +19,22 @@ import { parseFrontmatter } from './entity-source.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
 import { recordsYmlPath } from '../site/records-config.js'
+import { DECLARATION_KEYS } from '../site/fetch-shapes.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
 // authoring, not to externally-editable params. On a section write an existing
 // reserved key is preserved and never overwritten by incoming params, so a
 // projection doesn't churn fields it didn't author (the surgical-update bar).
+//
+// ⭐ The declaration keys — `query`, `fetch`, and the retired `data` — are one
+// group: a section that declares its data locally, under any of them, keeps that
+// declaration, and an incoming one under a different key does not land beside it
+// (a file holding two is refused by the build).
 export const DEFAULT_RESERVED_FRONTMATTER = new Set([
   'type',
   'preset',
   'input',
+  'query',
   'fetch',
   'data',
   'nest',
@@ -168,6 +175,7 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
   const { frontmatter, body: existingBody } = parseFrontmatter(existing, filePath)
 
   const nextFrontmatter = { ...frontmatter }
+  const declaresLocally = DECLARATION_KEYS.some((k) => k in frontmatter)
   if (params) {
     for (const [key, value] of Object.entries(params)) {
       // A reserved key is preserved only when it already exists locally (the
@@ -175,6 +183,7 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
       // there is nothing to protect, so the incoming value fills it — that's
       // how a newly-projected section gets its `type`/`nest`/etc.
       if (reserved.has(key) && key in frontmatter) continue
+      if (reserved.has(key) && DECLARATION_KEYS.includes(key) && declaresLocally) continue
       if (value === null || value === undefined) delete nextFrontmatter[key]
       else nextFrontmatter[key] = value
     }
@@ -186,11 +195,12 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
 
 // Shallow-merge `changes` into a YAML config file and write idempotently. A key
 // whose value is null/undefined is deleted; an object value is shallow-merged one
-// level deep (so partial `theme` / `build` updates don't drop sibling keys); any
-// other value replaces. NOTE: this re-dumps the file, so author comments/order are
-// not preserved — acceptable for machine-owned config, but comment-preserving
-// merges for hand-authored config files are a quality bar to revisit.
-function mergeYamlConfig(filePath, changes) {
+// level deep (so partial `theme` / `build` updates don't drop sibling keys) unless
+// the key is in `replace`; any other value replaces. NOTE: this re-dumps the file,
+// so author comments/order are not preserved — acceptable for machine-owned
+// config, but comment-preserving merges for hand-authored config files are a
+// quality bar to revisit.
+function mergeYamlConfig(filePath, changes, { replace = [] } = {}) {
   let existing = {}
   try {
     existing = yaml.load(readFileSync(filePath, 'utf8')) || {}
@@ -200,7 +210,7 @@ function mergeYamlConfig(filePath, changes) {
   for (const [key, value] of Object.entries(changes)) {
     if (value === null || value === undefined) {
       delete existing[key]
-    } else if (typeof value === 'object' && !Array.isArray(value)) {
+    } else if (typeof value === 'object' && !Array.isArray(value) && !replace.includes(key)) {
       existing[key] = { ...(existing[key] || {}), ...value }
     } else {
       existing[key] = value
@@ -212,10 +222,15 @@ function mergeYamlConfig(filePath, changes) {
 /**
  * Merge `config` into `site.yml` (shallow). Preserves keys not present in the
  * update (foundation, base, paths, …).
+ *
+ * ⛔ 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.
  * @returns {'updated'|'unchanged'}
  */
 export function writeSiteConfig(siteRoot, config) {
-  return mergeYamlConfig(join(siteRoot, 'site.yml'), config)
+  return mergeYamlConfig(join(siteRoot, 'site.yml'), config, { replace: DECLARATION_KEYS })
 }
 
 /**

package/src/uwx/site-project.js

@@ -39,7 +39,7 @@ import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
 import { declarationsToQueriesYml } from './records-project.js'
-import { authorableFetch } from '../site/fetch-shapes.js'
+import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
 import { buildFreeformPath } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
@@ -138,8 +138,8 @@ const INFO_TO_SITE_YML = {
   // 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.
-  // ⛔ `data` IS NOT VERBATIM — see the explicit branch below. It projects to
-  // `site.yml::fetch`, not `site.yml::data`.
+  // ⛔ The site's declaration is not verbatim — see the explicit `settings.fetch`
+  // branch below: it projects to `site.yml::query` or `site.yml::fetch`.
   template: 'template',
   // ⭐ `tags` — authored, non-localized tokens; the filter facet for a list of site
   // cards. Round-trips verbatim like any authored list.
@@ -199,6 +199,16 @@ const SETTINGS_TO_SITE_YML = {
 }
 
 
+/** An authored YAML config as it stands, or null when there is none to read. */
+function readAuthoredYaml(filePath) {
+  try {
+    const value = yaml.load(readFileSync(filePath, 'utf8'))
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Project a site-content document's `info` (+ `extensions`) onto the site's
  * config files: `site.yml`, `theme.yml`, and `head.html`. Idempotent; only the
@@ -238,22 +248,21 @@ 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).
+  // ⭐ `settings.fetch` → `site.yml::query` or `site.yml::fetch` — the key the file
+  // already uses, else `query:` when the declaration is nothing but query names
+  // (`authorableDeclaration`). The wire carries the desugared form and cannot say
+  // which was typed, and the round-trip law keeps the authored KEY as well as the
+  // value (the sync format's round-trip law): the site lane once wrote the shorthand back verbatim,
+  // so an author who typed `fetch:` pushed, pulled, and got the shorthand back.
+  // The other declaration keys are removed, so the file never holds two (the
+  // build refuses that) — a retired `data:` included.
   //
   // ⛔ 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)
+    const { key, value } = authorableDeclaration(wireFetch, readAuthoredYaml(join(siteRoot, 'site.yml')))
+    for (const k of DECLARATION_KEYS) siteChanges[k] = k === key ? value : null
   }
 
   // The `settings` Section — authored configuration that is not identity, so it is
@@ -409,8 +418,13 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
   if (theme_override !== undefined) frontmatter.theme = theme_override
   if (preset !== undefined) frontmatter.preset = preset
   if (input !== undefined) frontmatter.input = input
-  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
-  if (fetch !== undefined) frontmatter.fetch = authorableFetch(fetch)
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js. A new
+  // file gets `query:` for a declaration of names alone; a section that declares
+  // its data locally keeps it (`writeSectionFile`, the declaration keys).
+  if (fetch !== undefined) {
+    const { key, value } = authorableDeclaration(fetch)
+    frontmatter[key] = value
+  }
   if (stable_id !== undefined) frontmatter.id = stable_id
 
   const body = insets ? reinlineInsets(sourceContent, insets) : sourceContent
@@ -496,10 +510,13 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
 // page.yml/folder.yml. On a merge write these are replaced wholesale (a managed
 // key the record no longer carries is dropped); any other key is author-authored
 // and preserved. Keep in sync with pageRecordToYml below.
+// ⚠️ `query` and `data` are managed with `fetch`: the declaration is written under
+// ONE key (`authorableDeclaration`), so the other two — a retired `data:`
+// included — are dropped rather than left beside it.
 const PAGE_YML_MANAGED_KEYS = new Set([
   'id', 'title', 'description', 'label', 'keywords', 'index', 'hidden',
   'hideIn', 'knowledge', 'trackSections', 'redirect', 'rewrite', 'layout', 'seo',
-  'fetch', 'sections',
+  'query', 'fetch', 'data', 'sections',
 ])
 
 // Inverse of site.js buildPageData → the `page.yml` / `folder.yml` object.
@@ -507,7 +524,7 @@ const PAGE_YML_MANAGED_KEYS = new Set([
 // directory (name, page.yml vs folder.yml, `[param]/`), not the config body.
 // Identity (the backend uuid) is NOT written here — it lives in the gitignored
 // `.uniweb/` index so authored files stay clean.
-function pageRecordToYml(record, sectionsArray, sourceLocale) {
+function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null) {
   const y = {}
   if (record.stable_id !== undefined) y.id = record.stable_id
   const title = unwrapLocalized(record.title, sourceLocale)
@@ -531,8 +548,12 @@ function pageRecordToYml(record, sectionsArray, sourceLocale) {
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
   if (record.seo !== undefined) y.seo = record.seo
-  // Invert the build's resolution rather than copy it — see fetch-shapes.js.
-  if (record.fetch !== undefined) y.fetch = authorableFetch(record.fetch)
+  // Invert the build's resolution rather than copy it — see fetch-shapes.js. Under
+  // the key the file already uses (`existing`), else `query:` for names alone.
+  if (record.fetch !== undefined) {
+    const { key, value } = authorableDeclaration(record.fetch, existing)
+    y[key] = value
+  }
   // `sections:` exists to preserve ORDER and NESTING, which the projected filenames
   // can't carry (they're `<stableId>.md`, with no numeric prefix). It must not also
   // decide MEMBERSHIP — and a bare list does: the collector reads a list without
@@ -635,7 +656,7 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     const ymlPath = join(pageDir, ymlName)
     // Merge (not full-dump) so author-added keys survive a pull; the projector
     // owns only PAGE_YML_MANAGED_KEYS.
-    writeMergedYaml(ymlPath, pageRecordToYml(record, sectionsArray, sourceLocale), PAGE_YML_MANAGED_KEYS)
+    writeMergedYaml(ymlPath, pageRecordToYml(record, sectionsArray, sourceLocale, readAuthoredYaml(ymlPath)), PAGE_YML_MANAGED_KEYS)
     report.pages.push(ymlPath)
 
     writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route)

package/src/uwx/site.js

@@ -39,7 +39,7 @@
 
 import { readdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { join, parse } from 'node:path'
+import { join, parse, relative } from 'node:path'
 import {
   readYamlFile,
   readFolderConfig,
@@ -52,7 +52,9 @@ import {
   parseWildcardArray,
   applyWildcardOrder,
   processMarkdownFile,
-  fetchFromDataShorthand,
+  declaredFetch,
+  checkDeclaration,
+  fetchFromQueryShorthand,
   assertRouteFolder,
 } from '../site/content-collector.js'
 import { refuseUnder } from '../site/data-fetcher.js'
@@ -196,7 +198,7 @@ function mapSectionData(section) {
 }
 
 function buildPageData(config, ctx) {
-  const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations } =
+  const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations, where } =
     ctx
   // The page `slug` is the localized route source — a `{lang: slug}` map (the
   // site-content Model declares it localized; greenlit 2026-06-13). A single-locale
@@ -234,10 +236,12 @@ function buildPageData(config, ctx) {
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
   setIf(data, 'seo', config.seo)
-  // ⭐ A `data:` LIST means "fetch each" — one declaration per entry. Before
+  // ⭐ A `query:` or `fetch:` 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 ?? fetchFromDataShorthand(config.data)
+  // `fetch:`, or the `query:` shorthand, read and refused exactly as the build
+  // reads them (`declaredFetch`) — a `folder.yml` as much as a `page.yml`.
+  let fetch = declaredFetch(config, where ?? 'page.yml')
   // `where: { path: { under } }` is refused here as the build refuses it
   // (`parseFetchConfig`): a site that cannot build must not sync either. A
   // section's fetch is refused where the collector parses it.
@@ -249,7 +253,7 @@ function buildPageData(config, ctx) {
   // it would never resolve at render (the static build resolves it the same way
   // in site/data-fetcher.js parseFetchConfig). The gateway serves the collection
   // at `<base>/data/<name>.json`.
-  // ⛔ **Mapped, not read.** A `data:`/`fetch:` LIST reaches here as an array, and
+  // ⛔ **Mapped, not read.** A `query:`/`fetch:` LIST reaches here as an array, and
   // `fetch.query` on one is `undefined` — so a property test would skip the
   // resolution below and put bare `{ query }` entries on the wire with no
   // `path`, no `as` and no `schema`. That is the silent-empty class: a payload
@@ -567,6 +571,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
     const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
 
     const data = buildPageData(f.config, {
+      where: relative(siteRoot, join(f.path, f.source)),
       slug,
       mode,
       isDynamic: !!dyn,
@@ -1080,14 +1085,15 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // summarized.
   setIf(settings, 'agents', siteYml.agents)
 
-  // ⭐ The site-level fetch, DESUGARED and under its real name. `data:` is the
+  // ⭐ The site-level fetch, DESUGARED and under its real name. `query:` 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.
-  // `under` is refused as the build refuses it; the `data:` shorthand carries no
-  // `where`. ⚠️ The source expression stays inside `setIf`: `gen-emit-surface.mjs`
-  // reads the published key's sources off it.
+  // field `fetch`; the site tier's wire field was `data` until 2026-09-09.
+  // `query:` / `fetch:` checked as the build checks them, and `under` refused;
+  // the `query:` shorthand carries no `where`. ⚠️ The desugaring stays inline in
+  // `setIf`: `gen-emit-surface.mjs` reads the published key's sources off it.
+  checkDeclaration(siteYml, 'site.yml')
   for (const one of [siteYml.fetch].flat()) refuseUnder(one?.where, 'site.yml fetch')
-  setIf(settings, 'fetch', siteYml.fetch ?? fetchFromDataShorthand(siteYml.data))
+  setIf(settings, 'fetch', siteYml.fetch ?? fetchFromQueryShorthand(siteYml.query))
 
   // ⭐ 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
@@ -1265,15 +1271,6 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // endpoint; here it leaves the site with the RIGHT answer.
   //
   // The provisioned record rides the `$services` section instead (see servicesNested).
-  // ⭐ 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

package/src/validate-data.js

@@ -54,7 +54,7 @@ import { processQueries } from './site/query-processor.js'
  * agree on which schema governs what by construction.
  *
  * Inputs are consumed from what the canonical build parsers already compute —
- * `section.fetch` (the binding resolved from `data:` / `fetch:`) and
+ * `section.fetch` (the binding resolved from `query:` / `fetch:`) and
  * `schema.json[type].data` (the key→ref bindings). Re-deriving either would let
  * this command and the build disagree about what feeds what.
  *
@@ -139,7 +139,7 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
               `but this page delivers ${delivered.map((k) => `\`${k}\``).join(', ')}. ` +
               `The section will render with no data and nothing else will say so. ` +
               `Name the query for the key the section reads, or give the section its own ` +
-              `\`fetch: { query: <name> }\`.`,
+              `\`query: <name>\`.`,
             // One user per declared key, so `uniweb validate` can print
             // `used by /team › Team › data.team` — the key is the thing to rename.
             users: declaredKeys.map((k) => ({ route: page.route, section: type, key: k })),
@@ -479,7 +479,7 @@ async function loadStandardSchemas() {
  */
 function collectInputs(section, pageFetch, siteFetch) {
   const byKey = new Map()
-  // ⭐ Each level may declare SEVERAL — `data: [team, articles]` — so each is
+  // ⭐ Each level may declare SEVERAL — `query: [team, articles]` — so each is
   // flattened rather than read. Order is least- to most-specific and `set`
   // overwrites, which is what makes a section's declaration win the key.
   for (const source of [siteFetch, pageFetch, section.fetch]) {