@uniweb/build 0.79.0 → 0.80.1

package/package.json

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

package/src/foundation/default-layout.js

@@ -0,0 +1,52 @@
+/**
+ * The layout a page renders with when it names none — decided once, by the build, and written
+ * into both artifacts: the entry's `capabilities.defaultLayout`, which the runtime reads
+ * (`Website.getDefaultLayoutName`), and `_self.defaultLayout` in the schema, which an editor
+ * reads to offer a page the areas it will draw. One rule, run once, so the two cannot disagree.
+ *
+ * ⭐ THE RULE [2026-10-07; Diego: "I think the default layout maybe called `default`"]:
+ *
+ *   1. `main.js`'s `defaultLayout`, written as that layout's own name — `DocsLayout` for
+ *      `docs` — so a reader finds it in `_layouts` by key. ⛔ One that names none of the
+ *      foundation's layouts stops the build: at render it fell to the built-in layout with
+ *      nothing saying why.
+ *   2. Else the layout whose name is `default`, by the one naming rule (`layoutNameKey`):
+ *      `Default`, `DefaultLayout`, `default-layout`.
+ *   3. Else none — the runtime's built-in layout, which draws `header`, the body and `footer`.
+ *
+ * ⛔ NOT "the only layout". Under that rule, adding a second layout would change the layout of
+ * every page that names none — a non-local effect nobody asked for. A foundation that means its
+ * one layout as the default says so, as every template does.
+ *
+ * ⛔ *Until 2026-10-07 the build copied the declared value and derived nothing, so a layout named
+ * `Default` was the default only when `main.js` said so — and a reader of the schema finding none
+ * had to guess what the runtime would draw.*
+ *
+ * @module @uniweb/build/foundation/default-layout
+ */
+
+import { findLayoutEntry } from '@uniweb/core/layout-name'
+
+/**
+ * @param {*} declared - `main.js`'s `defaultLayout`, as `loadFoundationConfig` reads it
+ * @param {string[]} layoutNames - the foundation's layouts (`discoverLayoutsInPath`)
+ * @returns {string|null} the layout's own name, or null for the built-in layout
+ * @throws {Error} when `declared` names none of the layouts
+ */
+export function resolveDefaultLayout(declared, layoutNames = []) {
+  const byName = Object.fromEntries((layoutNames || []).map((name) => [name, name]))
+
+  if (declared !== undefined && declared !== null && declared !== '') {
+    const name = typeof declared === 'string' ? findLayoutEntry(byName, declared) : undefined
+    if (name) return name
+    const known = Object.keys(byName)
+    throw new Error(
+      `main.js: \`defaultLayout\` names ${JSON.stringify(declared)}, which is not one of this foundation's layouts` +
+        (known.length > 0 ? ` (${known.join(', ')})` : ' — it has none in src/layouts/') +
+        '. Name one of them, or remove the key: a page that names no layout then renders the built-in ' +
+        'layout, or one named `Default`.'
+    )
+  }
+
+  return findLayoutEntry(byName, 'default') ?? null
+}

package/src/generate-entry.js

@@ -32,6 +32,7 @@ import {
   LAYOUTS_PATH
 } from './schema.js'
 import { extractAllRuntimeSchemas, extractAllLayoutRuntimeSchemas, extractFoundationRuntime } from './runtime-schema.js'
+import { resolveDefaultLayout } from './foundation/default-layout.js'
 import { SCHEMA_EXTENSIONS } from './resolve-data-schema.js'
 
 /**
@@ -124,6 +125,7 @@ function generateEntrySource(components, options = {}) {
     cssPath = null,
     foundationExports = null,
     foundationRuntime = { code: [], data: {} },
+    defaultLayout = null,
     meta = {},
     layouts = {},
     layoutMeta = {},
@@ -188,6 +190,9 @@ function generateEntrySource(components, options = {}) {
       for (const key of foundationRuntime.code) capParts.push(`${key}: _foundationModule.default?.${key}`)
       for (const [key, value] of Object.entries(foundationRuntime.data)) capParts.push(`${key}: ${JSON.stringify(value)}`)
     }
+    // The resolved default, with or without a main.js — a layout named `Default` is one
+    // (`resolveDefaultLayout`), and `_self.defaultLayout` in the schema carries the same name.
+    if (defaultLayout) capParts.push(`defaultLayout: ${JSON.stringify(defaultLayout)}`)
     if (layoutNames.length > 0) {
       capParts.push(`layouts: { ${layoutNames.join(', ')} }`)
     }
@@ -310,6 +315,11 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   const foundationExports = detectFoundationExports(srcDir)
   const foundationConfig = await loadFoundationConfig(srcDir)
   const foundationRuntime = foundationExports ? extractFoundationRuntime(foundationConfig) : { code: [], data: {} }
+  // Which layout a page that names none renders with — the build's answer, written here and in
+  // the schema's `_self.defaultLayout` (`buildSchema`) from one rule, so the runtime and an editor
+  // agree. It replaces the declared value `extractFoundationRuntime` copied.
+  const defaultLayout = resolveDefaultLayout(foundationConfig.defaultLayout, layoutNames)
+  delete foundationRuntime.data.defaultLayout
 
   // Per-component runtime metadata. ⭐ No data schema is resolved for it: the runtime reads a
   // declared key's ref and nothing of its shape (2026-10-05), so the entry no longer depends on
@@ -329,6 +339,7 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
     cssPath,
     foundationExports,
     foundationRuntime,
+    defaultLayout,
     meta,
     layouts,
     layoutMeta,

package/src/schema.js

@@ -28,6 +28,7 @@ import {
   unnameableIn,
 } from './foundation/derive-supports.js'
 import { RENAMED_SERVICES } from './uwx/services-request.js'
+import { resolveDefaultLayout } from './foundation/default-layout.js'
 import { foundationNameOf, splitFoundationName } from './foundation-name.js'
 import { resolveFoundationSrcDir } from './utils/foundation-source-root.js'
 
@@ -1236,6 +1237,9 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Discover layouts from src/layouts/
   const layouts = await discoverLayoutsInPath(srcDir)
+  // The layout a page that names none renders with — the entry gets the same answer
+  // (`generate-entry.js`), so an editor reading `_self.defaultLayout` offers what the runtime draws.
+  const defaultLayout = resolveDefaultLayout(foundationConfig.defaultLayout, Object.keys(layouts))
   await refuseFlagsOnListSchemas(
     [
       ...Object.entries(components).map(([name, entry]) => [`${name} (meta.js)`, entry?.data]),
@@ -1260,8 +1264,9 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
     }
   }
 
-  // Build _self, stripping the raw extension boolean in favor of normalized role
-  const { extension: _ext, ...configWithoutExtension } = foundationConfig
+  // Build _self, stripping the raw extension boolean in favor of normalized role, and the
+  // declared `defaultLayout` in favor of the resolved one (`resolveDefaultLayout`)
+  const { extension: _ext, defaultLayout: _declaredLayout, ...configWithoutExtension } = foundationConfig
 
   // `supports` is the one identity field the build knows better than the file.
   // `identity.supports` is already normalized (absent stays absent, `[]` stays
@@ -1303,7 +1308,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
       ...supports,
       ...(name && { name }),
       ...(foundationConfig.description && { description: foundationConfig.description }),
-      ...(foundationConfig.defaultLayout && { defaultLayout: foundationConfig.defaultLayout }),
+      ...(defaultLayout && { defaultLayout }),
       ...(isExtension && { role: 'extension' }),
       // The build's fact, last: which form the entries below hold.
       schemaFormat: SCHEMA_FORMAT,

package/src/site/content-collector.js

@@ -22,7 +22,7 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises'
-import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
+import { resolveQueriesConfig, toConfigQueries, dataKeyTyping } from './queries-config.js'
 import { isSectionKey } from '@uniweb/schemas/section'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
@@ -2511,13 +2511,17 @@ export async function collectSiteContent(sitePath, options = {}) {
   // merged both, so a declaration in the second file was invisible here: never
   // compiled, `data: <name>` delivering nothing, while sync pushed it fine.
   //
-  // ⭐ `config.queries` — framework's own payload key, framework's own readers.
-  // The backend's projector never emits it (their measurement: 17 `config` keys,
-  // not this one), and hosting renders with framework's code. There was nobody to
-  // coordinate with, which is exactly why it had no excuse to stay wrong.
-  const byQuery = toConfigQueries(
-    (await resolveQueriesConfig(sitePath, { siteYml: siteConfig })).declarations
-  )
+  // ⭐ `config.queries` — what a page's queries are, which a section's keys are filled by. A
+  // backend-served payload carries its own projection of each (`schema`, `where`, `sort`,
+  // `limit`, `scope`) since 2026-09-05. ⛔ This said the backend's projector never emitted it,
+  // which was true only before then.
+  //
+  // ⭐ A query a data key types carries the type, as a push names it (`dataKeyTyping`), so a key
+  // typed `@/post` fills from `articles:` on a static site as it does on a hosted one.
+  const { declarations } = await resolveQueriesConfig(sitePath, { siteYml: siteConfig })
+  const nameDefaulted = Object.values(declarations).some((d) => d?.schemaExplicit === false)
+  const typing = nameDefaulted ? await dataKeyTyping(sitePath, declarations, { siteYml: siteConfig }) : null
+  const byQuery = toConfigQueries(declarations, typing)
   if (byQuery) siteConfig.queries = byQuery
 
   // Record the RESOLVED base (--base > UNIWEB_BASE > site.yml::base) on the

package/src/site/queries-config.js

@@ -41,6 +41,7 @@ import { refuseQueryRoute, refuseLimit, refuseFilter } from './data-fetcher.js'
 import { readFile } from 'node:fs/promises'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { dataKeyTypes } from '../uwx/data-key-types.js'
 
 // Read its own YAML rather than importing the site build's helper. That import
 // pointed the wrong way — a config resolver reaching into the collector that
@@ -77,8 +78,10 @@ export const QUERIES_YML_RELPATH = 'queries.yml'
 // Identity has no boundary to get wrong, and an author wanting a different schema
 // name writes `schema:`, which is one line and says what it means.
 //
-// Exported so the inverse (projection) can drop a `schema:` that merely restates
-// this default, keeping a projected queries.yml as terse as the author left it.
+// ⛔ A pull does not drop a `schema:` equal to this default: it writes the schema the site holds,
+// in its one spelling (`uwx/records-project.js::declToFileShape`). Until 2026-10-08 it did, keeping
+// a projected queries.yml as terse as the author left it — and a clone, with no author's file to
+// look at, wrote `series: { schema: '@/series' }` back as `series: {}`.
 export function defaultSchema(name) {
   return `@/${name}`
 }
@@ -320,21 +323,73 @@ function refuseMethod(method, where) {
  * held a key a declaration may want for something else [Diego, 2026-09-27]. Until then every
  * query on the payload read `{ name: 'articles', … }` under `articles`.
  *
+ * ⭐ A query that declares no `schema:` and whose records a data key types carries the TYPE —
+ * `articles` → `@/post` (`dataKeyTyping`) — which is what a push names it on the wire
+ * (`uwx/site.js::queriesNested`). The schema a page's query carries is what a section's key is
+ * filled by at render (automatic `as`), so the two lanes fill the same keys. ⛔ Until 2026-10-08 the
+ * static payload carried the name (`@/articles`), and a key typed `@/post` filled on a hosted site
+ * and stayed empty on a static one.
+ *
  * Returns undefined for a site with no queries, so `config.queries`
  * stays absent rather than becoming an empty object — an empty object reads as
  * "declared, and empty" to anything checking for presence.
+ *
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`
+ * @param {Map<string, string>|null} [typing] - `dataKeyTyping`: name-defaulted ref → its type
  */
-export function toConfigQueries(declarations) {
+export function toConfigQueries(declarations, typing = null) {
   const names = Object.keys(declarations || {})
   if (names.length === 0) return undefined
   const out = {}
   for (const key of names) {
     const { schemaExplicit, name, ...rest } = declarations[key]
-    out[key] = rest
+    const typed = schemaExplicit === false ? typing?.get(rest.schema) : null
+    out[key] = typed ? { ...rest, schema: typed } : rest
   }
   return out
 }
 
+/**
+ * ⭐ THE TYPE A DATA KEY GIVES A NAME — `@/articles` → `@/post` (ruled 2026-09-25 [Diego];
+ * `uwx/data-key-types.js`), decided for the static build as a push decides it
+ * (`uwx/records.js::typedFor`), so both lanes give a query one schema.
+ *
+ * A name-defaulted ref, `@/<name>`, stands for the type of the data key of that name when:
+ *
+ *   - no data schema has the name — `@/<name>` resolves to nothing;
+ *   - the foundation's section types declare the key `<name>` with one type, and it resolves;
+ *   - no query asks for `@/<name>` explicitly — that one is the author's, and fails loudly.
+ *
+ * Then `records/<name>/` holds records of the type, and a query named `<name>` that declares no
+ * schema is a query of it. ⚠️ Where the records live on disk and how their translations are keyed
+ * stay keyed by the name.
+ *
+ * @param {string} siteRoot
+ * @param {object} declarations - `resolveQueriesConfig(…).declarations`, for which refs are explicit
+ * @param {object} [opts]
+ * @param {object} [opts.siteYml] - an already-read site.yml
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type; empty when none
+ */
+export async function dataKeyTyping(siteRoot, declarations, opts = {}) {
+  const typing = new Map()
+  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const keyTypes = dataKeyTypes(await foundationSections(siteRoot, siteYml))
+  if (keyTypes.size === 0) return typing
+  const explicit = new Set(
+    Object.values(declarations || {})
+      .filter((d) => d && d.schemaExplicit === true)
+      .map((d) => d.schema)
+  )
+  const named = [...keyTypes.keys()].map(defaultSchema)
+  const { schemas } = await resolveRecordSchemas(siteRoot, [...named, ...keyTypes.values()], { siteYml })
+  for (const [key, type] of keyTypes) {
+    const ref = defaultSchema(key)
+    if (schemas[ref] || explicit.has(ref) || !schemas[type]) continue
+    typing.set(ref, type)
+  }
+  return typing
+}
+
 
 /**
  * The data schemas a site's records are shaped by, keyed by ref — each resolved from

package/src/site/query-processor.js

@@ -65,8 +65,8 @@ import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-p
 import { readRecordsConfig, resolveFolder, folderTreeOrder } from './records-config.js'
 import { isDraftRecord } from './record-draft.js'
 import { refuseNotOneRecord } from './record-file.js'
-import { resolveRecordSchemas, resolveQueriesConfig, foundationSections } from './queries-config.js'
-import { dataKeyTypes } from '../uwx/data-key-types.js'
+import { resolveRecordSchemas, resolveQueriesConfig, dataKeyTyping } from './queries-config.js'
+import { keyOfDefaultRef } from '../uwx/data-key-types.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
 import { collectNestedRefs } from '@uniweb/schemas/format'
@@ -1197,10 +1197,24 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   const poolBySchema = groupPoolBySchema(pool.entities)
   const recordsRoot = resolve(siteDir, pool.dir)
 
+  // ⭐ A FOLDER NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego];
+  // `dataKeyTyping`): `records/articles/`, when no data schema has the name and the foundation types
+  // `articles` as `@/post`, holds `@/post` records — so they join that type's records, as a push
+  // sends them, and any query of `@/post` reads them, as a host answers one. ⛔ Until 2026-10-08 they
+  // stayed under `@/articles`: only a query named `articles` read them, and it carried `@/articles`
+  // on the payload where a push named `@/post`.
+  const typing = await recordTyping(siteDir, queriesConfig, poolBySchema)
+  for (const [ref, type] of typing) {
+    const held = poolBySchema.get(ref)
+    if (!held) continue
+    poolBySchema.delete(ref)
+    poolBySchema.set(type, [...(poolBySchema.get(type) || []), ...held])
+  }
+
   // ⭐ THE DATA SCHEMA EACH QUERY'S RECORDS ARE DELIVERED IN (`deliverRecord`) — resolved
   // from the foundation's source once for every query. A query with none compiles its
   // records as their files hold them.
-  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig))
+  const dataSchemas = options.dataSchemas ?? (await querySchemas(siteDir, queriesConfig, typing))
   const references = referenceHydrator({ poolBySchema, dataSchemas, siteDir, recordsRoot, basePath, includeDrafts })
 
   const results = {}
@@ -1211,6 +1225,9 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     // be an empty `/data/<name>.json` standing in for a live source.
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const parsed = parseQueryConfig(name, config)
+    // A query that still names its folder (`@/articles`) is a query of the folder's type.
+    const folderRef = parsed.schema
+    if (parsed.schema && typing.has(parsed.schema)) parsed.schema = typing.get(parsed.schema)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder.placements
     parsed.folderRank = folderRank
@@ -1218,7 +1235,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
     parsed.dataSchema = (parsed.schema && dataSchemas[parsed.schema]) || null
     parsed.references = references
     if (parsed.poolEntities.length === 0) {
-      const dirs = parsed.schema ? poolDirsForSchema(parsed.schema) : null
+      const dirs = folderRef ? poolDirsForSchema(folderRef) : null
       console.warn(
         `[query-processor] Query "${name}" matches no records — ` +
           (dirs
@@ -1240,12 +1257,12 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
  * its records are compiled as their files hold them, which is not the shape a
  * component receives from a host.
  */
-async function querySchemas(siteDir, queriesConfig) {
-  const refs = []
+async function querySchemas(siteDir, queriesConfig, typing = new Map()) {
+  const refs = [...typing.values()]
   for (const config of Object.values(queriesConfig)) {
     if (config && typeof config === 'object' && config.url !== undefined) continue
     const ref = typeof config === 'string' ? config : config?.schema
-    if (typeof ref === 'string') refs.push(ref)
+    if (typeof ref === 'string' && !typing.has(ref)) refs.push(ref)
   }
   const { schemas, failures } = await resolveRecordSchemas(siteDir, refs)
   for (const { ref, message } of failures) {
@@ -1254,28 +1271,25 @@ async function querySchemas(siteDir, queriesConfig) {
         `their files hold them rather than as a component receives them: ${message}`
     )
   }
-  await typeByDataKey(siteDir, queriesConfig, schemas)
   return schemas
 }
 
 /**
- * ⭐ A QUERY NAMED FOR A DATA KEY HOLDS RECORDS OF THE KEY'S TYPE (ruled 2026-09-25 [Diego],
- * `uwx/data-key-types.js`). `articles:` with no `schema:` names `@/articles`; when no data schema
- * has that name while the foundation's section types declare `data: { articles: '@/post' }`, its
- * records are `@/post` records — a push sends them as such, and they are delivered as such here,
- * where they still live and are keyed by the name (`records/articles/`). Never for a schema the
- * query asked for explicitly: that one is the author's, and does not resolve. ⛔ Until 2026-09-27
- * this lane compiled them as if they had no data schema, while a push typed them.
+ * ⭐ WHICH FOLDERS HOLD RECORDS OF A DATA KEY'S TYPE (ruled 2026-09-25 [Diego]): `@/articles` →
+ * `@/post` — `dataKeyTyping`, the rule a push applies, asked only when the site has a folder or a
+ * query it could apply to: a name-defaulted ref, `@/<name>`. ⛔ Until 2026-10-08 this lane typed a
+ * query's RECORDS by aliasing its `@/<name>` to the type's schema, while its query and its folder
+ * kept the name.
  *
  * @param {string} siteDir
- * @param {Object} queriesConfig
- * @param {Object} schemas - resolved data schemas by ref; a typed query's ref is added to it
+ * @param {Object} queriesConfig - what the build compiles (`config.queries`)
+ * @param {Map<string, Array>} poolBySchema - the records, by the ref their folder names
+ * @returns {Promise<Map<string, string>>} name-defaulted ref → the type
  */
-async function typeByDataKey(siteDir, queriesConfig, schemas) {
-  const untyped = Object.entries(queriesConfig).filter(
-    ([name, c]) => c && typeof c === 'object' && c.url === undefined && c.schema === `@/${name}` && !schemas[c.schema]
-  )
-  if (untyped.length === 0) return
+async function recordTyping(siteDir, queriesConfig, poolBySchema) {
+  const candidate = (ref) => typeof ref === 'string' && keyOfDefaultRef(ref) !== null
+  const queried = Object.values(queriesConfig).map((c) => (typeof c === 'string' ? c : c?.schema))
+  if (![...poolBySchema.keys(), ...queried].some(candidate)) return new Map()
   // `config.queries` carries no trace of whether its author wrote the schema; the declarations do.
   let declarations = {}
   try {
@@ -1283,17 +1297,11 @@ async function typeByDataKey(siteDir, queriesConfig, schemas) {
   } catch {
     // a declaration the build refuses is reported where the build reads it
   }
-  const pending = untyped.filter(([name]) => declarations[name]?.schemaExplicit !== true)
-  if (pending.length === 0) return
-  const keyTypes = dataKeyTypes(await foundationSections(siteDir))
-  const wanted = new Map()
-  for (const [name, c] of pending) {
-    const type = keyTypes.get(name)
-    if (type) wanted.set(c.schema, type)
+  try {
+    return await dataKeyTyping(siteDir, declarations)
+  } catch {
+    return new Map() // a foundation that does not read is reported by the build that reads it
   }
-  if (wanted.size === 0) return
-  const { schemas: types } = await resolveRecordSchemas(siteDir, wanted.values())
-  for (const [ref, type] of wanted) if (types[type]) schemas[ref] = types[type]
 }
 
 /**

package/src/uwx/data-key-types.js

@@ -7,8 +7,10 @@
 // records folder (`records/team/`). When no data schema has that name, but the foundation's
 // section types declare the data key of that name with a type — `data: { team: '@/member' }` in a
 // `meta.js` — the records ARE of that type: a push sends them as its entities, and the query names
-// it on the wire. ⛔ Until 2026-09-25 they were read as having no data schema at all and went out
-// as static files, although the one section that reads them declared what they are.
+// it on the wire; the static build names it on the payload and reads them as the type's records
+// (`site/queries-config.js::dataKeyTyping`, since 2026-10-08 — until then the payload named the query
+// `@/team`). ⛔ Until 2026-09-25 they were read as having no data schema at all and went out as
+// static files, although the one section that reads them declared what they are.
 //
 // ⚠️ THIS DECIDES ONLY WHICH DATA SCHEMA THE RECORDS BELONG TO. Where they live on disk, how the
 // site builds them and how their translations are keyed stay keyed by the name (`team`), as the

package/src/uwx/index.js

@@ -88,6 +88,9 @@ export {
   sectionRecordToFile,
   pageSectionsToFiles,
   siteContentDocumentToProject,
+  // The file the author keeps a section in (`1-hero.md` holds `hero`) — what a section
+  // unit's path names on disk, for a push recording what it delivered.
+  existingSectionFile,
 } from './site-project.js'
 export {
   createTranslationCollector,

package/src/uwx/queries-config.js

@@ -4,7 +4,6 @@
 export {
   resolveQueriesConfig,
   queriesYmlPath,
-  defaultSchema,
   foundationDataSchemas,
   foundationSchemaJson,
   QUERIES_YML_RELPATH,

package/src/uwx/records-project.js

@@ -41,7 +41,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
-import { defaultSchema, foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
+import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
 import { dataKeyTypes } from './data-key-types.js'
 import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import { folderYmlPath } from '../site/records-config.js'
@@ -277,8 +277,8 @@ function setIf(obj, key, value) {
 //  - `path:` is written VERBATIM, and omitted entirely when it equals the default
 //    (the query's own name under the pool).
 //  - `url:` (remote source) and a bare `source:` object are carried as-is.
-//  - `schema:` is dropped when it only restates the query-name convention default,
-//    so a terse author file stays terse.
+//  - `schema:` is written as the site holds it — the query-name default included —
+//    except a query typed by a data key, kept short where its type can be read again.
 //
 // ⛔ THE `collections/`-PREFIX STRIP AND THE site.yml ROUTING ARE BOTH GONE, and
 // they went together. They existed because `collections.yml` sat INSIDE
@@ -342,24 +342,31 @@ function declToFileShape(wire, scope = null, own = null, keyTypes = null, author
     decl.source = source
   }
 
-  // The default is the query's name — or, when no data schema has that name, the type the
-  // foundation declares for the data key of that name (`data-key-types.js`), which is what a
-  // push sent in its place. Either one stays unwritten, so the terse file stays terse.
-  // ⛔ UNLESS THE AUTHOR WROTE IT: a `schema:` the local file already states for this query is
-  // written back as it is. Until 2026-09-25 a pull into a working copy dropped international's
-  // `articles: { schema: '@std/article' }`, because a section types `articles` as `@std/article`.
-  // ⭐ A CLONE GOES BY THE MARK. Where the key's type comes only from the registered foundation a
-  // project keeps (`markedOnly`: its foundation is a catalog ref), a query is written terse only when
-  // the push marked it `typed_by_data_key` — the author wrote no schema — or when the author's own
-  // file declares it with none. Unmarked, the schema was the author's, and it is written.
+  // ⭐ THE SCHEMA THE SITE HOLDS IS WRITTEN — one spelling per meaning [Diego, 2026-10-08]. A
+  // query left to its name's default (`series` → `@/series`) comes back with that schema stated:
+  // `series: {}` and `series: { schema: '@/series' }` read the same records, and a clone, with no
+  // file of the author's to look at, could not tell which was written. ⛔ Until 2026-10-08 a schema
+  // equal to the default stayed unwritten unless the local file stated it, so a clone turned an
+  // author's `series: { schema: '@/series' }` into `series: {}`.
+  //
+  // ⛔ EXCEPT A QUERY TYPED BY A DATA KEY, which is not a second spelling of anything: `team:` reads
+  // its own folder, `records/team/`, as the type the foundation's data key declares
+  // (`data-key-types.js`), where `team: { schema: '@/member' }` would read `records/member/`. It
+  // stays as written — short — but only where this project can read it as that type again: the
+  // foundation's types (its own, or the registered version a clone keeps) give its name the schema
+  // the site holds. Then the push's mark says so (`typed_by_data_key`), or the author's file
+  // declares it short, or — the foundation in this project — the file does not declare it. An
+  // author's stated schema is never taken for one. ⛔ With no types to read, short would mean
+  // `@/team`: the schema is written, and the records go to its folder, so the copy still pushes it.
   const written = name ? authored?.get(name) : undefined
-  const typedHere = !markedOnly || wire.typed_by_data_key === true || written === null
-  const keyType = name && !own?.has(name) && typedHere ? keyTypes?.get(name) : null
+  const keyType = name && !own?.has(name) ? keyTypes?.get(name) : null
   // In the author's form: the registered version names the type qualified (`@acme/member`).
   const keyDefault = keyType ? unresolveSelfScope(keyType, scope, own) : null
-  if (d.schema && (d.schema === written || (d.schema !== defaultSchema(name) && d.schema !== keyDefault))) {
-    decl.schema = d.schema
-  }
+  const typedByKey =
+    keyDefault !== null &&
+    d.schema === keyDefault &&
+    (wire.typed_by_data_key === true || written === null || (written === undefined && !markedOnly))
+  if (d.schema && !typedByKey) decl.schema = d.schema
   setIf(decl, 'sort', d.sort)
   setIf(decl, 'where', d.where)
   setIf(decl, 'limit', d.limit)

package/src/uwx/site-diff.js

@@ -96,8 +96,12 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
 export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
-      // The projector's own file rule, so a unit's path here is the file it is
-      // written to — including an app-created section named from its `$uuid`.
+      // The projector's own file rule — including an app-created section named from its
+      // `$uuid`. ⚠️ The path NAMES the unit by its id; it is not always the author's file:
+      // a pull writes into an existing `1-about.md` or `@about.md` in place
+      // (`existingSectionFile`), so a reader mapping a unit to disk looks it up there.
+      // (This said "a unit's path here is the file it is written to" until 2026-10-07,
+      // and a push recorded no file for a numbered section.)
       const base = sectionFileBase(record)
       if (base) cb(`${dir}/${base}.md`, record, 'section')
       walkSections(record.$children, dir)

package/src/uwx/site-project.js

@@ -47,8 +47,7 @@ import { declarationsToQueriesYml } from './records-project.js'
 import { FILLED_SECTION_TYPE, buildRouteOf } from './site.js'
 import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
-import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent, localesDir } from './locale-sync.js'
-import { resolveLocaleList } from '../i18n/locales.js'
+import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
 import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
@@ -214,7 +213,7 @@ function readAuthoredYaml(filePath) {
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
  *          write status ('updated' | 'unchanged')
  */
-export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false, deferLanguages = false }) {
+export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
   const info = document?.info || {}
   const settingsSection = document?.settings || {}
 
@@ -325,18 +324,14 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
     }
   }
 
-  // ⭐ `languages` for a site whose `site.yml` declares none is judged once the pull has written the
-  // translation files (`deferLanguages`, `siteContentDocumentToProject`): a push sends the list those
-  // files make (`uwx/site.js::settingsNested`), and writing it back would turn "every translation
-  // file" into a fixed list.
-  let pendingLanguages
-  if (deferLanguages && siteChanges.languages !== undefined && !('languages' in (readAuthoredYaml(join(siteRoot, 'site.yml')) || {}))) {
-    pendingLanguages = siteChanges.languages
-    delete siteChanges.languages
-  }
-
+  // ⭐ `languages` IS WRITTEN AS THE SITE HOLDS IT — one spelling per meaning [Diego, 2026-10-08]:
+  // "It's definitely good for the case of languages." A site whose `site.yml` declared none sent the
+  // list its translation files make (`uwx/site.js::settingsNested`), and that list comes back stated,
+  // so a clone and the copy that pushed it say the same thing. ⛔ Until 2026-10-08 the list was held
+  // back where the translation files the pull wrote made the same one, so a clone of a site that
+  // declared `languages: [en, fr]` had no `languages:` at all — and followed its translation files
+  // where the site it came from had a fixed list.
   const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
-  if (pendingLanguages !== undefined) result.pendingLanguages = pendingLanguages
 
   // theme (whole object) → theme.yml.
   if (settingsSection.theme && typeof settingsSection.theme === 'object') {
@@ -587,7 +582,7 @@ function listedNames(list) {
 //
 // ⛔ A top-level section never takes an `@` file: that is a child's name, and the build renders an
 // `@` file no `nest:` claims only as an orphan appended at the end — listed by name, it is not rendered.
-function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
+export function existingSectionFile(pageDir, fileBase, stableId, { child = false } = {}) {
   if (!existsSync(pageDir)) return null
   const entries = readdirSync(pageDir).filter((e) => isMarkdownFile(e) && (child || !e.startsWith('@')))
   const found =
@@ -1121,7 +1116,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
     backend ? readBackendState(siteRoot, backend).assets || {} : {}
   )
 
-  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation, deferLanguages: true })
+  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
   report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
@@ -1162,18 +1157,6 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   report.locales = writeLocaleTranslations(siteRoot, collector.byLocale)
   // Target-locale FREE-FORM bodies → locales/freeform/{locale}/<relpath> + manifest.
   report.freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
-  // The site's languages, for a site.yml that declares none (`siteInfoToConfig`) — written only where
-  // the translation files, now written, would not make the same list, or where `publishLanguages`
-  // needs a declared list to draw from: the build refuses one without it.
-  if (report.config?.pendingLanguages !== undefined) {
-    const pulled = report.config.pendingLanguages
-    delete report.config.pendingLanguages
-    const site = readAuthoredYaml(join(siteRoot, 'site.yml')) || {}
-    const source = site.defaultLanguage || sourceLocale
-    const made = new Set([source, ...resolveLocaleList(undefined, localesDir(siteRoot))])
-    const same = Array.isArray(pulled) && pulled.length === made.size && pulled.every((l) => made.has(l))
-    if (!same || site.publishLanguages !== undefined) writeSiteConfig(siteRoot, { languages: pulled })
-  }
   writePullIndex(siteRoot, ctx.newIndex)
   return report
 }

package/src/uwx/yaml-edit.js

@@ -45,9 +45,18 @@ function columnOf(text, key) {
   return /^ *$/.test(lead) ? lead.length : null
 }
 
-/** Where a pair's text ends: after its value, its trailing comment and its newline. */
+/**
+ * Where a pair's text ends: after its value, its trailing comment and its newline.
+ *
+ * ⛔ A SCALAR ENDS WHERE ITS OWN TEXT DOES — `range[1]`, then the rest of that line. Its
+ * `range[2]` also spans the comment lines that follow it, and for an empty value (`team:`)
+ * every comment and blank line up to the next key, at any indentation: those belong to what
+ * comes next. ⛔ Until 2026-10-08 this read `range[2]`, and a pull that gave a bare `team:` its
+ * schema deleted the blank line and the `# Build options` heading under it in `site.yml`.
+ */
 function pairEnd(text, pair) {
-  let end = (pair.value ?? pair.key).range[2]
+  const node = pair.value ?? pair.key
+  let end = isScalar(node) ? node.range[1] : node.range[2]
   if (text[end - 1] !== '\n') {
     const nl = text.indexOf('\n', end)
     const rest = nl === -1 ? text.slice(end) : text.slice(end, nl)
@@ -169,6 +178,17 @@ function editMap(text, map, before, after, edits, dump) {
         continue
       }
     }
+    // ⭐ A BARE KEY GIVEN A VALUE KEEPS ITS LINE — and any comment the author wrote on it — and
+    // the value goes under it: `team:  # the people` gains `  schema: '@/team'` beneath.
+    const bare = isScalar(value) && value.value === null && value.range[0] === value.range[1]
+    if (bare && (isPlainObject(next) || Array.isArray(next))) {
+      const whole = indented(dump({ [key]: next }), col, false)
+      const nl = whole.indexOf('\n')
+      if (nl !== -1 && nl < whole.length - 1) {
+        edits.push({ start: stop, end: stop, text: (text[stop - 1] === '\n' ? '' : '\n') + whole.slice(nl + 1) })
+        continue
+      }
+    }
     // Written whole — in flow style when the author wrote it that way (`tags: [a, b]`).
     const flow = (isMap(value) || isSeq(value)) && value.flow
     edits.push({