@uniweb/build 0.56.0 → 0.58.0

package/src/site/entity-pool.js

@@ -1,49 +1,175 @@
-// A site's ENTITY POOL — every stored thing on disk, and the model each one has.
+// A site's RECORDS on disk — every file in `records/`, and the model each one has.
 //
-// ⛔ THE PATH DECLARES THE MODEL, AND NOTHING ELSE. That is the whole point of
-// this directory, and it is the de-conflation the records model is built on:
-// `collections/<name>/` used to mean three things at once — these files are
-// entities, their schema is `@/<name>`, and they are grouped as `<name>` for
-// placement. `entities/{schema}/` declares only the first two. Grouping moved to
-// `records.yml`, which is what makes an entity a RECORD.
+// ⭐ PLACING A FILE IN `records/` IS WHAT MAKES IT A RECORD (ruled 2026-09-21
+// [Diego]). The directory is the file side of the site's records folder: the
+// backend's folder holds references to entities, and putting a ref in it is what
+// makes one a record — putting a file in this directory is the same act. Nothing
+// else is needed, and nothing lists it. A file whose name starts with `_` or `.`
+// is not read, so it is not a record.
 //
-// ⇒ So nothing here reads a query, a folder, or any config. A pool is a fact
-// about the filesystem.
+// ⭐ ONE FILE AT THE TOP IS NOT A RECORD: `folder.yml`, the folder's organization —
+// which records sit in which sub-folder (`records-config.js`). The top of the
+// directory is the one place no record can be (a file there names no model), so the
+// name collides with nothing. It lives here because the directory IS the site's
+// folder on the file side: its organization moves with `paths.records` and travels
+// with a records directory that sites share, as a pages directory's own
+// `folder.yml` does. ⛔ It was `records.yml` at the site root until 2026-09-21
+// [Diego]; that file is refused by name (`refuseRetiredLayout`).
+//
+// ⛔ A RECORD IS NOT "PUBLISHED" BY BEING HERE. `push` sends the site's records to a
+// backend, and they are served once the SITE is published — publishing the site
+// publishes its folder and what is in it. Nothing about a single record decides that.
+//
+// ⛔ THE PATH DECLARES THE MODEL, AND NOTHING ELSE. `collections/<name>/` used to
+// mean three things at once — these files are entities, their schema is
+// `@/<name>`, and they are grouped as `<name>` for placement. A schema folder here
+// declares only the model; grouping is `folder.yml`'s.
+//
+// ⇒ So nothing here reads a query or a folder. A site's records are a fact about
+// the filesystem — plus `site.yml::paths.records`, which says where they live.
 //
 // ⭐ DEPTH NAMES THE SCOPE — the schema-ref grammar, spelled as directories:
 //
-//     entities/person/ada.md         → @/person        (the foundation's own)
-//     entities/std/person/ada.md     → @std/person      (the shared standard set)
-//     entities/acme/project/x.md     → @acme/project    (an org's)
+//     records/person/ada.md         → @/person        (the foundation's own)
+//     records/std/person/ada.md     → @std/person      (the shared standard set)
+//     records/acme/project/x.md     → @acme/project    (an org's)
 //
 // matching `build/src/resolve-data-schema.js`, which is the only grammar there
 // is: a bare directory name can mean `@/<name>` and nothing else.
 //
-// ⛔ BARE, NOT `entities/@std/`. Measured: `@` is a reserved indicator in YAML
+// ⛔ BARE, NOT `records/@std/`. Measured: `@` is a reserved indicator in YAML
 // 1.2, so a bare `@std/person/*.md` scalar throws in js-yaml — and the message is
 // `bad indentation of a sequence entry`, which names neither the cause nor the
-// fix. The `@` form would force quotes on the most common line in `records.yml`
-// and put two spellings in one list.
+// fix. The `@` form would force quotes on every pattern in `folder.yml` that
+// names a scoped schema.
 //
 // ⛔ AND NO NESTING BELOW THE SCHEMA DIR, which is what makes the depth rule
 // total: it is the FILE's depth that decides, so one path answers the question
-// with nothing to classify and no ambiguous case to resolve.
+// with nothing to classify and no ambiguous case to resolve. Organization is a
+// `folder:` in `folder.yml`, never a directory.
 //
-// ⭐ That costs nothing — it CLOSES a divergence that was live and silent.
-// `uwx/collection-source.js::reportNestedRecords` warns today that records below
-// a collection's top level "build and render locally but are absent from the
-// synced set": the delivery lane recursed and the sync lane was one level deep.
-// `records.yml` replaces on-disk nesting outright, so the two lanes stop
-// disagreeing rather than being taught to agree.
+// ⛔ THE DIRECTORY WAS `entities/` UNTIL 2026-09-21, and `site.yml::paths.entities`
+// the key that moved it. Both are refused by name rather than read (no alias —
+// there is no population to carry): a leftover `entities/` beside `records/` would
+// otherwise hold records nothing reads, silently.
 
 import { readdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { join, extname, basename } from 'node:path'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, extname, basename, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+
+/** Where a site's records live, relative to its root, unless `site.yml::paths.records` moves them. */
+export const RECORDS_DIR = 'records'
+
+/** The directory's name until 2026-09-21. Read only to refuse it. */
+const RETIRED_DIR = 'entities'
+
+/**
+ * The folder's organization, at the top of the records directory — the one file
+ * there that is not a record. See the header, and `records-config.js`.
+ */
+export const FOLDER_YML = 'folder.yml'
+
+/** Where the folder's organization lived until 2026-09-21: the site root. Read only to refuse it. */
+const RETIRED_FOLDER_FILE = 'records.yml'
 
-/** Where a site's entities live, relative to its root. */
-export const ENTITIES_DIR = 'entities'
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function readSitePaths(siteRoot) {
+  const file = join(siteRoot, 'site.yml')
+  if (!existsSync(file)) return {}
+  try {
+    const doc = yaml.load(readFileSync(file, 'utf8'), YAML_OPTIONS)
+    return doc && typeof doc.paths === 'object' && doc.paths !== null ? doc.paths : {}
+  } catch {
+    // An unreadable site.yml is reported by whoever reads the site; this only
+    // needs the one key, and the default is the right answer without it.
+    return {}
+  }
+}
 
-/** Source extensions an entity file may have. Mirrors the sync-lane reader. */
+/**
+ * Refuse the retired `entities/` directory when it is not the one the site reads.
+ *
+ * ⛔ A RENAMED DIRECTORY FAILS SILENTLY — its files are simply not read, and a site
+ * with no records looks exactly like a site whose records moved. So its presence
+ * stops the build, the push and every other reader, naming the new place.
+ */
+export function refuseRetiredRecordsDir(siteRoot, rel) {
+  const retired = resolve(siteRoot, RETIRED_DIR)
+  if (resolve(siteRoot, rel) === retired) return
+  if (!isDirectory(retired)) return
+  throw new Error(
+    `[uniweb] ${RETIRED_DIR}/ is not read — a site's records live in \`${rel}/\` now. ` +
+      `Rename the directory (\`git mv ${RETIRED_DIR} ${rel}\`) and every file in it is a record, ` +
+      `as before; nothing lists them any more.`
+  )
+}
+
+/**
+ * Refuse the retired `records.yml` at the site root: the folder's organization is
+ * `folder.yml` inside the records directory now.
+ *
+ * ⛔ SAME REASON AS THE DIRECTORY ABOVE. Left in place it would be read by nothing,
+ * every record would sit at the top of the folder, and the next push would send
+ * that — replacing the backend folder's sub-folders — with nothing to say why. Its
+ * contents move unchanged: the paths in it were always relative to the records
+ * directory.
+ */
+export function refuseRetiredFolderFile(siteRoot, rel) {
+  const retired = resolve(siteRoot, RETIRED_FOLDER_FILE)
+  // A records directory at the site root itself would make that path a record's.
+  if (resolve(siteRoot, rel) === resolve(siteRoot)) return
+  if (!existsSync(retired)) return
+  throw new Error(
+    `[uniweb] ${RETIRED_FOLDER_FILE} is not read — the records folder's organization is ` +
+      `\`${rel}/${FOLDER_YML}\` now, inside the directory it organizes. Move it ` +
+      `(\`git mv ${RETIRED_FOLDER_FILE} ${rel}/${FOLDER_YML}\`); its contents are unchanged.`
+  )
+}
+
+/** Both retired layouts, refused wherever the records directory is resolved. */
+function refuseRetiredLayout(siteRoot, rel) {
+  refuseRetiredRecordsDir(siteRoot, rel)
+  refuseRetiredFolderFile(siteRoot, rel)
+}
+
+/**
+ * Where a site's records live — `site.yml::paths.records`, else `records/`.
+ *
+ * ⭐ THE ONE RESOLVER, and every lane asks it: the build, the push, the pull and
+ * the CLI. ⛔ Until 2026-09-21 only the build honoured the key — then called
+ * `paths.entities` — while push read the default, so a site that moved its records
+ * built fine and then failed to push, with an error naming a directory it did not
+ * use (measured).
+ *
+ * @param {string} siteRoot
+ * @param {object} [paths] - `site.yml::paths`, when the caller has already read it;
+ *   otherwise `site.yml` is read here.
+ * @returns {{ rel: string, abs: string }} `rel` as written (for messages), `abs`
+ *   resolved against the site root — an absolute `paths.records` is honoured.
+ */
+export function resolveRecordsDir(siteRoot, paths) {
+  const p = paths === undefined ? readSitePaths(siteRoot) : paths || {}
+  if (p.entities !== undefined) {
+    throw new Error(
+      `[uniweb] site.yml: \`paths.entities\` is now \`paths.records\` — the directory a site's ` +
+        `records live in. Rename the key.`
+    )
+  }
+  const rel = typeof p.records === 'string' && p.records.trim() ? p.records.trim().replace(/\/+$/, '') : RECORDS_DIR
+  refuseRetiredLayout(siteRoot, rel)
+  return { rel, abs: resolve(siteRoot, rel) }
+}
+
+/** Source extensions a record file may have. Mirrors the sync-lane reader. */
 export const ENTITY_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
 
 const isHidden = (name) => name.startsWith('_') || name.startsWith('.')
@@ -51,7 +177,7 @@ const isHidden = (name) => name.startsWith('_') || name.startsWith('.')
 /**
  * The schema ref a pool path names.
  *
- * @param {string[]} dirs - the directory segments below `entities/`
+ * @param {string[]} dirs - the directory segments below `records/`
  * @returns {string|null} the ref, or null when the depth names no schema
  */
 export function schemaForPoolDirs(dirs) {
@@ -61,7 +187,7 @@ export function schemaForPoolDirs(dirs) {
 }
 
 /**
- * Where a schema's entities live — the inverse of `schemaForPoolDirs`.
+ * Where a schema's records live — the inverse of `schemaForPoolDirs`.
  *
  * ⛔ ONE IMPLEMENTATION AND ITS INVERSE, IN ONE PLACE, for the reason this file
  * exists at all: the reader derives a model from a path and the pull side derives
@@ -70,7 +196,7 @@ export function schemaForPoolDirs(dirs) {
  * `deferredFromSchema` — a deriver and its recognizer must not be two copies.
  *
  * @param {string} schema - a ref: `@/name` or `@org/name`
- * @returns {string[]|null} the directory segments below `entities/`, or null for
+ * @returns {string[]|null} the directory segments below `records/`, or null for
  *   a ref this layout cannot express
  */
 export function poolDirsForSchema(schema) {
@@ -85,7 +211,7 @@ export function poolDirsForSchema(schema) {
 /**
  * Both readings of a 2-segment pool path, for an error that has to name them.
  *
- * ⚠️ A reader who mistakes `entities/person/2024/ada.md` for "the `person`
+ * ⚠️ A reader who mistakes `records/person/2024/ada.md` for "the `person`
  * schema, organised by year" needs to be told what the build actually did with
  * it, not merely that something did not resolve. The wrong reading is the
  * plausible one, so the message carries both.
@@ -98,33 +224,46 @@ export function poolPathReadings(dirs) {
 }
 
 /**
- * Read a site's entity pool.
+ * Read a site's records.
  *
- * Returns entities in a stable, path-sorted order — the wire's package digest
+ * Returns them in a stable, path-sorted order — the wire's package digest
  * depends on it — each carrying the model its path declares.
  *
  * ⚠️ NOTHING HERE RESOLVES A SCHEMA. Whether `@std/person` is a schema this site
  * can actually see is a question for whoever holds the foundation's built schema
  * map, and only that caller can raise the error §4 of the model asks for. This
- * reports the pool's SHAPE — a file with no schema above it, a file nested too
- * deep — because those are answerable from the filesystem alone.
+ * reports the directory's SHAPE — a file with no schema above it, a file nested
+ * too deep — because those are answerable from the filesystem alone.
  *
  * @param {string} siteRoot
  * @param {object} [opts]
- * @param {string} [opts.dir] - override the pool directory (site-root-relative)
+ * @param {string} [opts.dir] - the records directory, site-root-relative or
+ *   absolute, when the caller already resolved it; otherwise `resolveRecordsDir`
+ *   reads `site.yml::paths.records`.
  * @returns {Promise<{
  *   entities: Array<{ id, schema, slug, dirs, relPath, absPath, ext }>,
  *   errors: string[],
  *   exists: boolean,
+ *   dir: string,
  * }>}
- *   `id` is the entity's path under `entities/` without its extension — unique
+ *   `id` is the record's path under `records/` without its extension — unique
  *   by construction, stable across pushes, and derivable identically on both
- *   sides without either lane holding the other's ids.
+ *   sides without either lane holding the other's ids. `exists` is whether the
+ *   directory is there at all, which is not the same as holding nothing: a push
+ *   leaves the backend's folder alone for a site with no records directory.
  */
 export async function readEntityPool(siteRoot, opts = {}) {
-  const rel = opts.dir || ENTITIES_DIR
-  const base = join(siteRoot, rel)
-  if (!existsSync(base)) return { entities: [], errors: [], exists: false }
+  let rel
+  if (opts.dir) {
+    rel = String(opts.dir).replace(/\/+$/, '')
+    refuseRetiredLayout(siteRoot, rel)
+  } else {
+    rel = resolveRecordsDir(siteRoot).rel
+  }
+  // ⛔ `resolve`, not `join`: an absolute `paths.records` is supported, and
+  // `join(siteRoot, '/abs')` is a path under the site root that does not exist.
+  const base = resolve(siteRoot, rel)
+  if (!isDirectory(base)) return { entities: [], errors: [], exists: false, dir: rel }
 
   const entities = []
   const errors = []
@@ -149,7 +288,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
             `${rel}/${[...dirs, e.name].join('/')}/ is nested below a schema folder. ` +
               `\`${rel}/\` declares a model and nothing else — \`${[...dirs].join('/')}\` ` +
               `already names ${read}, so there is no meaning left for a folder inside it. ` +
-              `Organise records in records.yml (a \`folder:\` entry), not on disk.`
+              `Organise records in ${rel}/${FOLDER_YML} (a \`folder:\` entry), not on disk.`
           )
           continue
         }
@@ -157,13 +296,16 @@ export async function readEntityPool(siteRoot, opts = {}) {
         continue
       }
       if (!e.isFile()) continue
+      // The folder's organization, not a record — see the header.
+      if (dirs.length === 0 && e.name === FOLDER_YML) continue
       const ext = extname(e.name).toLowerCase()
       if (!ENTITY_EXTENSIONS.has(ext)) continue
       if (dirs.length === 0) {
         errors.push(
           `${rel}/${e.name} sits directly in \`${rel}/\`, which names no model. ` +
             `Move it under a schema folder — \`${rel}/<name>/\` for \`@/<name>\`, ` +
-            `or \`${rel}/<org>/<name>/\` for \`@<org>/<name>\`.`
+            `or \`${rel}/<org>/<name>/\` for \`@<org>/<name>\`. The one file that belongs ` +
+            `at the top is \`${FOLDER_YML}\`, the folder's organization.`
         )
         continue
       }
@@ -188,7 +330,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
   }
 
   await walk(base, [])
-  return { entities, errors, exists: true }
+  return { entities, errors, exists: true, dir: rel }
 }
 
 /**

package/src/site/plugin.js

@@ -50,7 +50,7 @@ import { collectSiteContent, mountEntriesOf } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
-import { ENTITIES_DIR } from './entity-pool.js'
+import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
@@ -132,8 +132,10 @@ export function shouldPrefetchInDev(cfg) {
  *   - `'queries'` — re-collect the site, re-materialize every query file from the
  *     query list just collected, reload. `queries.yml` declares queries, and so does
  *     `site.yml` (`queries:`), beside the rest of the site's configuration.
- *   - `'records'` — re-materialize the query files, reload: `records.yml` decides
- *     which entities are records, as an entity change decides what one says.
+ *   - `'records'` — re-materialize the query files, reload. Only the retired
+ *     `records.yml` maps here now, so that the rebuild REPORTS it: the folder's
+ *     organization is `records/folder.yml` since 2026-09-21, and an edit to it is
+ *     seen by the records directory's own recursive watch.
  *   - `'content'` — re-collect the site, reload.
  *
  * ⛔ Until 2026-09-14 nothing watched `records.yml` or `queries.yml`, a `site.yml`
@@ -148,7 +150,7 @@ export function siteRootChange(filename) {
     case 'site.yml':
     case 'queries.yml':
       return 'queries'
-    case 'records.yml':
+    case 'records.yml': // retired — watched so the rebuild refuses it
       return 'records'
     case 'theme.yml':
     case 'head.html':
@@ -665,7 +667,7 @@ export function siteContentPlugin(options = {}) {
   let resolvedPagesPath = null // Resolved from site.yml pagesDir or default
   let resolvedMountPaths = [] // Absolute dirs mounted under pages/ via site.yml paths:
   let resolvedLayoutPath = null // Resolved from site.yml layoutDir or default
-  let resolvedEntitiesDir = null // site.yml `paths.entities`, site-root-relative
+  let resolvedRecordsDir = null // site.yml `paths.records` as written, via `resolveRecordsDir`
   let headHtml = '' // Contents of site/head.html for injection
   let basePath = '/' // Vite's config.base, always has trailing slash
 
@@ -725,8 +727,11 @@ export function siteContentPlugin(options = {}) {
    */
   async function materializeQueries(queries, config) {
     if (!queries) return
-    const byQuery = await processQueries(resolvedSitePath, queries, resolvedEntitiesDir, basePath, {
+    const byQuery = await processQueries(resolvedSitePath, queries, resolvedRecordsDir, basePath, {
       locale: resolveDefaultLocale(config ?? {}) ?? null,
+      // ⭐ A draft is previewable here, as a hidden page is — `pnpm dev` is where the
+      // author looks at it. A production build leaves it out (`buildStart`).
+      includeDrafts: !isProduction,
     })
     await writeQueryFiles(resolvedSitePath, byQuery, queries)
   }
@@ -911,7 +916,7 @@ export function siteContentPlugin(options = {}) {
           resolvedLayoutPath = paths.layout
             ? resolve(resolvedSitePath, paths.layout)
             : resolve(resolvedSitePath, 'layout')
-          resolvedEntitiesDir = paths.entities || null
+          resolvedRecordsDir = resolveRecordsDir(resolvedSitePath, paths).rel
           resolvedMountPaths = mountEntriesOf(paths).map(([, rel]) => resolve(resolvedSitePath, rel))
 
           if (queriesConfig) {
@@ -934,7 +939,7 @@ export function siteContentPlugin(options = {}) {
         resolvedLayoutPath = paths.layout
           ? resolve(resolvedSitePath, paths.layout)
           : resolve(resolvedSitePath, 'layout')
-        resolvedEntitiesDir = paths.entities || null
+        resolvedRecordsDir = resolveRecordsDir(resolvedSitePath, paths).rel
       }
     },
 
@@ -954,7 +959,7 @@ export function siteContentPlugin(options = {}) {
         // In production, do it here
         if (isProduction && siteContent.config?.queries) {
           console.log('[site-content] Materializing queries...')
-          const byQuery = await processQueries(resolvedSitePath, siteContent.config.queries, resolvedEntitiesDir, basePath)
+          const byQuery = await processQueries(resolvedSitePath, siteContent.config.queries, resolvedRecordsDir, basePath)
           await writeQueryFiles(resolvedSitePath, byQuery, siteContent.config.queries)
         }
 
@@ -1093,10 +1098,10 @@ export function siteContentPlugin(options = {}) {
           }
         }
 
-        // Watch the site root — `site.yml`, `queries.yml`, `records.yml`, `theme.yml`,
-        // `head.html` — as ONE directory rather than a watch per file: a file watch
-        // cannot be set on a file created after the server started (a first
-        // `records.yml`), and an editor that saves by replacing a file ends its watch.
+        // Watch the site root — `site.yml`, `queries.yml`, `theme.yml`, `head.html`,
+        // and the retired `records.yml` — as ONE directory rather than a watch per
+        // file: a file watch cannot be set on a file created after the server started
+        // (a first `queries.yml`), and an editor that saves by replacing a file ends its watch.
         // Not recursive, so what the build writes below the root (`public/data/`) is
         // not seen here. What each change redoes is `siteRootChange`.
         try {
@@ -1113,11 +1118,11 @@ export function siteContentPlugin(options = {}) {
         // ⭐ WATCH THE POOL, NOT A DIRECTORY PER QUERY. This used to resolve
         // `config.path` for each declaration and watch each one, so a schema
         // folder no query had mentioned yet — a new one, mid-session — was
-        // watched by nothing and its records never rebuilt. `entities/` is one
+        // watched by nothing and its records never rebuilt. `records/` is one
         // recursive root and covers every schema, present and future.
         {
           const contentPaths = new Set([
-            resolve(resolvedSitePath, resolvedEntitiesDir || ENTITIES_DIR)
+            resolve(resolvedSitePath, resolvedRecordsDir || RECORDS_DIR)
           ])
 
           for (const contentPath of contentPaths) {

package/src/site/queries-config.js

@@ -16,9 +16,9 @@
 // rather keep one file. Precedence (per-query, per-key): queries.yml > site.yml.
 //
 // ⛔ THE THREE JOBS `collections/<name>/` USED TO FUSE ARE NOW THREE THINGS.
-// `entities/{schema}/` is the pool, `records.yml` is the folder (what makes an
-// entity a record), and a query asks the folder for a set. This file resolves the
-// LAST of those only.
+// `records/{schema}/` holds the site's records (placing a file there is what makes
+// it one), `records/folder.yml` sorts them into folders, and a query asks for a set. This
+// file resolves the LAST of those only.
 //
 // ⚠️ `collections.yml` and `site.yml::collections` are GONE, with no alias and no
 // deprecation path — the model's §5 ruling, and there is nothing outside this
@@ -85,7 +85,7 @@ export function defaultSchema(name) {
 // address nothing local can derive.
 function normalizeQueryDecl(name, decl) {
   // ⭐ THE STRING SHORTHAND NAMES THE SCHEMA, because that is what a file-based
-  // query actually needs — `entities/{schema}/` supplies the records, so there is
+  // query actually needs — `records/{schema}/` supplies the records, so there is
   // no directory left to name. (It named a PATH while the pool was
   // `collections/<name>/` and the same directory answered both questions.)
   if (typeof decl === 'string') return { name, schema: decl }
@@ -116,7 +116,7 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
   const ymlPath = join(siteRoot, QUERIES_YML_RELPATH)
   const hasQueriesYml = existsSync(ymlPath)
   // ⛔ A BARE MAP — `queries.yml` has no root key. The file IS the map, the way
-  // `records.yml` IS the list. A `queries:` key inside it would be a name a query
+  // `records/folder.yml` IS the list. A `queries:` key inside it would be a name a query
   // could then collide with.
   const queriesYml = hasQueriesYml ? await readYamlFile(ymlPath) : {}
 
@@ -165,7 +165,7 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
     if (decl.path && decl.url === undefined) {
       console.warn(
         `[uniweb] query "${decl.name}": \`path: ${decl.path}\` is ignored. A query names a ` +
-          `\`schema:\` and \`entities/{schema}/\` supplies its records — there is no directory ` +
+          `\`schema:\` and \`records/{schema}/\` supplies its records — there is no directory ` +
           `for it to name. Move the files under the schema folder instead.`
       )
     }
@@ -234,6 +234,16 @@ export function refuseQueryDeclaration(decl) {
   }
   refuseQueryRoute(decl, where)
   refuseLimit(decl.limit, where)
+  // ⛔ `sync:` IS RETIRED (2026-09-21). `sync: false` kept a query's records off a
+  // backend while a query owned its records; every record in `records/` is pushed
+  // now, whatever reads it, so an ignored `sync: false` would push exactly what the
+  // author meant to hold back. Refused, naming what does that now.
+  if (decl.sync !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: \`sync:\` is retired — a query does not own its records. Every file in ` +
+        `\`records/\` is a record and is pushed; a file whose name starts with \`_\` is not a record.`
+    )
+  }
   const external = decl.url !== undefined
   if (!external) {
     for (const key of ['method', 'body', 'transform', 'record']) {