@uniweb/build 0.29.1 → 0.30.1

package/src/site/data-fetcher.js

@@ -7,7 +7,7 @@
  * Supports:
  * - Simple string paths: "/data/team.json"
  * - Full config objects with schema, prerender, merge, transform options
- * - Collection references: { collection: 'articles', limit: 3 }
+ * - Named-query references: { query: 'articles', limit: 3 }
  * - Local JSON/YAML files
  * - Remote URLs
  * - Transform paths to extract nested data
@@ -20,7 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere, collectionDataUrl } from '@uniweb/core'
+import { matchWhere, queryDataUrl } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -236,7 +236,7 @@ export function applyPostProcessing(data, config) {
  * // Returns: { path: '/team', schema: 'person', prerender: false, merge: false }
  *
  * // Collection reference
- * parseFetchConfig({ collection: 'articles', limit: 3, sort: 'date desc' })
+ * parseFetchConfig({ query: 'articles', limit: 3, sort: 'date desc' })
  * // Returns: { path: '/data/articles.json', schema: 'articles', limit: 3, sort: 'date desc', ... }
  */
 // ─── Unrecognized-key reporting ───────────────────────────────────────
@@ -252,8 +252,8 @@ export function applyPostProcessing(data, config) {
 // once per key name per process so a 200-record build does not print 200 lines.
 const RECOGNIZED_FETCH_KEYS = {
   refine: new Set(['refine', 'inherit', 'detail', 'limit', 'sort', 'where', 'filter']),
-  collection: new Set([
-    'collection', 'schema', 'prerender', 'merge', 'transform',
+  query: new Set([
+    'query', 'schema', 'prerender', 'merge', 'transform',
     'where', 'limit', 'sort', 'detailPage', 'filter',
   ]),
   source: new Set([
@@ -331,14 +331,27 @@ export function parseFetchConfig(fetch) {
     }
   }
 
-  // Collection reference: { collection: 'articles', limit: 3 }
-  if (fetch.collection) {
-    warnUnknownFetchKeys(fetch, 'collection')
+  // ⛔ THE RETIRED SPELLING IS AN ERROR, NOT A WARNING. An unrecognized key is
+  // warned about and IGNORED, so `fetch: { collection: X }` would fall through to
+  // the source shape, find neither `path` nor `url`, and resolve to null — a
+  // SILENTLY EMPTY result, which is worse than the old name simply working. The
+  // author sees a page render with no data and nothing saying why.
+  if (fetch.collection !== undefined) {
+    throw new Error(
+      `[uniweb] fetch: \`collection: ${JSON.stringify(fetch.collection)}\` is retired. ` +
+        `Write \`query: ${JSON.stringify(fetch.collection)}\` and declare it in queries.yml. ` +
+        `A query names a schema and the folder supplies its records.`
+    )
+  }
+
+  // Named-query reference: { query: 'articles', limit: 3 }
+  if (fetch.query) {
+    warnUnknownFetchKeys(fetch, 'query')
     if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
-      path: collectionDataUrl(fetch.collection),
+      path: queryDataUrl(fetch.query),
       url: undefined,
-      schema: fetch.schema || fetch.collection,
+      schema: fetch.schema || fetch.query,
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,

package/src/site/entity-pool.js

@@ -0,0 +1,211 @@
+// A site's ENTITY POOL — every stored thing on disk, 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.
+//
+// ⇒ So nothing here reads a query, a folder, or any config. A pool is a fact
+// about the filesystem.
+//
+// ⭐ 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)
+//
+// 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
+// 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.
+//
+// ⛔ 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.
+//
+// ⭐ 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.
+
+import { readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, extname, basename } from 'node:path'
+
+/** Where a site's entities live, relative to its root. */
+export const ENTITIES_DIR = 'entities'
+
+/** Source extensions an entity 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('.')
+
+/**
+ * The schema ref a pool path names.
+ *
+ * @param {string[]} dirs - the directory segments below `entities/`
+ * @returns {string|null} the ref, or null when the depth names no schema
+ */
+export function schemaForPoolDirs(dirs) {
+  if (dirs.length === 1) return `@/${dirs[0]}`
+  if (dirs.length === 2) return `@${dirs[0]}/${dirs[1]}`
+  return null
+}
+
+/**
+ * Where a schema's entities 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
+ * a path from a model, and if those two ever disagree a pulled record lands
+ * somewhere the next build reads as a different schema. Same rule as
+ * `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
+ *   a ref this layout cannot express
+ */
+export function poolDirsForSchema(schema) {
+  if (typeof schema !== 'string') return null
+  const self = /^@\/([^/]+)$/.exec(schema)
+  if (self) return [self[1]]
+  const scoped = /^@([^/]+)\/([^/]+)$/.exec(schema)
+  if (scoped) return [scoped[1], scoped[2]]
+  return null
+}
+
+/**
+ * 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`
+ * 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.
+ */
+export function poolPathReadings(dirs) {
+  return {
+    read: schemaForPoolDirs(dirs),
+    alternative: dirs.length === 2 ? `@/${dirs[0]}` : null,
+  }
+}
+
+/**
+ * Read a site's entity pool.
+ *
+ * Returns entities 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.
+ *
+ * @param {string} siteRoot
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - override the pool directory (site-root-relative)
+ * @returns {Promise<{
+ *   entities: Array<{ id, schema, slug, dirs, relPath, absPath, ext }>,
+ *   errors: string[],
+ *   exists: boolean,
+ * }>}
+ *   `id` is the entity's path under `entities/` without its extension — unique
+ *   by construction, stable across pushes, and derivable identically on both
+ *   sides without either lane holding the other's ids.
+ */
+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 }
+
+  const entities = []
+  const errors = []
+
+  const walk = async (dir, dirs) => {
+    let listing
+    try {
+      listing = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of listing.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      if (isHidden(e.name)) continue
+      const full = join(dir, e.name)
+      if (e.isDirectory()) {
+        if (dirs.length >= 2) {
+          // Deeper than a schema dir. Say what the path was read AS, because the
+          // author's intent (organising records inside a schema) is the reading
+          // this layout deliberately does not have.
+          const { read } = poolPathReadings(dirs)
+          errors.push(
+            `${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.`
+          )
+          continue
+        }
+        await walk(full, [...dirs, e.name])
+        continue
+      }
+      if (!e.isFile()) 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>\`.`
+        )
+        continue
+      }
+      // ⛔ THE SLUG IS THE FILENAME STEM, WHOLE — nothing is stripped from it.
+      // A leading number orders a set (`01-`, `02-`) at least as often as it is a
+      // DATE (`2026-03-…`), and the two are indistinguishable by shape, so
+      // consuming one into the record's name mangles the other. A number is read
+      // to SORT by (`compareByNumericPrefix`) and never to rename.
+      const slug = basename(e.name, ext)
+      entities.push({
+        id: [...dirs, slug].join('/'),
+        schema: schemaForPoolDirs(dirs),
+        slug,
+        file: e.name,
+        dirs: [...dirs],
+        relPath: [rel, ...dirs, e.name].join('/'),
+        poolPath: [...dirs, e.name].join('/'),
+        absPath: full,
+        ext,
+      })
+    }
+  }
+
+  await walk(base, [])
+  return { entities, errors, exists: true }
+}
+
+/**
+ * The pool grouped by the schema each path declares.
+ *
+ * ⭐ This is what a query resolves against: it names a `schema:` and the pool
+ * follows, so there is no disk path for it to name. (`source:` survives for
+ * REMOTE sources, where the address is genuinely external.)
+ *
+ * @returns {Map<string, Array>} schema ref → entities, in pool order
+ */
+export function groupPoolBySchema(entities) {
+  const bySchema = new Map()
+  for (const e of entities || []) {
+    if (!e?.schema) continue
+    if (!bySchema.has(e.schema)) bySchema.set(e.schema, [])
+    bySchema.get(e.schema).push(e)
+  }
+  return bySchema
+}

package/src/site/fetch-shapes.js

@@ -4,12 +4,13 @@
 // accepts differ (`data-fetcher.js` RECOGNIZED_FETCH_KEYS):
 //
 //   refine      refine · inherit · detail · limit · sort · where · filter
-//   collection  collection · schema · … — and NOT `path`/`url`
+//   query       query · schema · … — and NOT `path`/`url`
 //   source      path · url · schema · …
+
 //
-// The build RESOLVES a `collection:` shorthand into a concrete location, so the
-// declaration that rides the sync wire carries BOTH the authored `collection` and
-// the derived `path`. Projecting that back verbatim writes a file that is neither
+// The build RESOLVES a `query:` shorthand into a concrete location, so the
+// declaration that rides the sync wire carries BOTH the authored `query` and the
+// derived `path`. Projecting that back verbatim writes a file that is neither
 // shape cleanly: `collection` wins the classification, and the `path` beside it is
 // then an unrecognized key on its own declaration.
 //
@@ -19,33 +20,33 @@
 //   fetch:
 //     path: /data/members.json     ← derived; also a build artifact path
 //     schema: members
-//     collection: members          ← what the author actually wrote
+//     query: members               ← what the author actually wrote
 //
 //   [uniweb] fetch: unrecognized key "path" was ignored. Keys recognized on this
-//   declaration: collection, detailPage, filter, limit, merge, prerender, schema,
+//   declaration: detailPage, filter, limit, merge, prerender, query, schema,
 //   sort, transform, where.
 //
 // ⭐ The round trip has to invert the resolution, not copy it. `/data/<name>.json`
-// is a materialization of a collection, never its definition — so it is precisely
-// the thing an authored file should not contain.
+// is a materialization of a query, never its definition — so it is precisely the
+// thing an authored file should not contain.
 //
 // ⚖️ DROPS ONLY WHAT IS DERIVABLE, not everything unrecognized. A key we do not know
 // might be one a newer producer authored, and silently discarding it on every pull
 // would make the round trip lossy in a way nothing reports. `path` and `url` beside
-// a `collection` are recoverable from the collection itself; anything else survives
-// and the validator's warning stays the honest signal.
+// a `query` are recoverable from the query itself; anything else survives and the
+// validator's warning stays the honest signal.
 
 /** Which of the three shapes a declaration is — the same order `data-fetcher` uses. */
 export function fetchShapeOf(fetch) {
   if (!fetch || typeof fetch !== 'object') return null
   if (fetch.refine === true || fetch.inherit === true) return 'refine'
-  if (fetch.collection) return 'collection'
+  if (fetch.query) return 'query'
   return 'source'
 }
 
 /** Keys a shape derives rather than the author writing them. */
 const DERIVED_BY_SHAPE = {
-  collection: ['path', 'url'],
+  query: ['path', 'url'],
   refine: [],
   source: []
 }

package/src/site/foundation-ref.js

@@ -6,7 +6,7 @@
  *
  * It began in `./config.js`, which imports a Vite plugin. That made it unreachable
  * from any lane that must not pull Vite — and the sync lane, needing exactly this
- * answer, grew its own weaker copy instead (`../uwx/collections.js`), which read
+ * answer, grew its own weaker copy instead (`../uwx/records.js`), which read
  * `package.json` `dependencies.foundation`: a key no current template produces, so
  * it returned null for every scaffolded site. A third copy in the CLI describes
  * itself as mirroring "a subset of" this one.

package/src/site/index.js

@@ -38,10 +38,10 @@ export {
   isPdfFile
 } from './advanced-processors.js'
 export {
-  processCollections,
-  writeCollectionFiles,
-  getCollectionLastModified
-} from './collection-processor.js'
+  processQueries,
+  writeQueryFiles,
+  getQueryLastModified
+} from './query-processor.js'
 export { collectSchemalessData, collectSchemalessDataAssets, rewriteSchemalessDataAssets } from './schemaless-data.js'
 export {
   parseFetchConfig,

package/src/site/plugin.js

@@ -49,7 +49,8 @@ import {
 import { collectSiteContent, mountEntriesOf } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
-import { processCollections, writeCollectionFiles } from './collection-processor.js'
+import { processQueries, writeQueryFiles } from './query-processor.js'
+import { ENTITIES_DIR } from './entity-pool.js'
 import { executeFetch, mergeDataIntoContent } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
@@ -566,13 +567,13 @@ export function siteContentPlugin(options = {}) {
   let watcher = null
   let server = null
   let localeTranslations = {} // Cache: { locale: translations }
-  let collectionTranslations = {} // Cache: { locale: collection translations }
+  let recordTranslations = {} // Cache: { locale: record translations }
   let localesDir = 'locales' // Default, updated from site config
-  let collectionsConfig = null // Cached for watcher setup
+  let queriesConfig = null // Cached for watcher setup
   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 resolvedCollectionsBase = null // Resolved from site.yml collectionsDir
+  let resolvedEntitiesDir = null // site.yml `paths.entities`, site-root-relative
   let headHtml = '' // Contents of site/head.html for injection
   let basePath = '/' // Vite's config.base, always has trailing slash
 
@@ -602,12 +603,12 @@ export function siteContentPlugin(options = {}) {
   /**
    * Load collection translations for a specific locale
    */
-  async function loadCollectionTranslations(locale) {
-    if (collectionTranslations[locale]) {
-      return collectionTranslations[locale]
+  async function loadRecordTranslations(locale) {
+    if (recordTranslations[locale]) {
+      return recordTranslations[locale]
     }
 
-    const localePath = join(resolvedSitePath, localesDir, 'collections', `${locale}.json`)
+    const localePath = join(resolvedSitePath, localesDir, 'records', `${locale}.json`)
     if (!existsSync(localePath)) {
       return null
     }
@@ -615,7 +616,7 @@ export function siteContentPlugin(options = {}) {
     try {
       const content = await readFile(localePath, 'utf-8')
       const translations = JSON.parse(content)
-      collectionTranslations[locale] = translations
+      recordTranslations[locale] = translations
       return translations
     } catch {
       return null
@@ -792,7 +793,7 @@ export function siteContentPlugin(options = {}) {
         try {
           // Do an early content collection to get the collections config
           const earlyContent = await collectForBundle(resolvedSitePath, { foundationPath })
-          collectionsConfig = earlyContent.config?.collections
+          queriesConfig = earlyContent.config?.queries
 
           // Resolve content directory paths from site.yml paths: group
           const paths = earlyContent?.config?.paths || {}
@@ -802,18 +803,16 @@ export function siteContentPlugin(options = {}) {
           resolvedLayoutPath = paths.layout
             ? resolve(resolvedSitePath, paths.layout)
             : resolve(resolvedSitePath, 'layout')
-          resolvedCollectionsBase = paths.collections
-            ? resolve(resolvedSitePath, paths.collections)
-            : null
+          resolvedEntitiesDir = paths.entities || null
           resolvedMountPaths = mountEntriesOf(paths).map(([, rel]) => resolve(resolvedSitePath, rel))
 
-          if (collectionsConfig) {
-            console.log('[site-content] Processing content collections...')
-            const collections = await processCollections(resolvedSitePath, collectionsConfig, resolvedCollectionsBase, basePath)
-            await writeCollectionFiles(resolvedSitePath, collections, collectionsConfig)
+          if (queriesConfig) {
+            console.log('[site-content] Materializing queries...')
+            const byQuery = await processQueries(resolvedSitePath, queriesConfig, resolvedEntitiesDir, basePath)
+            await writeQueryFiles(resolvedSitePath, byQuery, queriesConfig)
           }
         } catch (err) {
-          console.warn('[site-content] Early collection processing failed:', err.message)
+          console.warn('[site-content] Early query materialization failed:', err.message)
         }
       }
 
@@ -828,9 +827,7 @@ export function siteContentPlugin(options = {}) {
         resolvedLayoutPath = paths.layout
           ? resolve(resolvedSitePath, paths.layout)
           : resolve(resolvedSitePath, 'layout')
-        resolvedCollectionsBase = paths.collections
-          ? resolve(resolvedSitePath, paths.collections)
-          : null
+        resolvedEntitiesDir = paths.entities || null
       }
     },
 
@@ -845,13 +842,13 @@ export function siteContentPlugin(options = {}) {
         headHtml = await loadHeadHtml()
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
 
-        // Process content collections if defined in site.yml
+        // Materialize each query if the site declares any.
         // In dev mode, this was already done in configResolved (before server starts)
         // In production, do it here
-        if (isProduction && siteContent.config?.collections) {
-          console.log('[site-content] Processing content collections...')
-          const collections = await processCollections(resolvedSitePath, siteContent.config.collections, resolvedCollectionsBase, basePath)
-          await writeCollectionFiles(resolvedSitePath, collections, siteContent.config.collections)
+        if (isProduction && siteContent.config?.queries) {
+          console.log('[site-content] Materializing queries...')
+          const byQuery = await processQueries(resolvedSitePath, siteContent.config.queries, resolvedEntitiesDir, basePath)
+          await writeQueryFiles(resolvedSitePath, byQuery, siteContent.config.queries)
         }
 
         // Execute data fetches in dev mode
@@ -867,7 +864,7 @@ export function siteContentPlugin(options = {}) {
 
         // Clear translation cache on rebuild
         localeTranslations = {}
-        collectionTranslations = {}
+        recordTranslations = {}
       } catch (err) {
         console.error('[site-content] Failed to collect content:', err.message)
         // Production: a failed collect must fail the build — falling through
@@ -909,22 +906,22 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Debounce collection rebuilds separately (writes to file system)
-        let collectionRebuildTimeout = null
-        const scheduleCollectionRebuild = () => {
-          if (collectionRebuildTimeout) clearTimeout(collectionRebuildTimeout)
-          collectionRebuildTimeout = setTimeout(async () => {
-            console.log('[site-content] Collection content changed, regenerating JSON...')
+        let recordRebuildTimeout = null
+        const scheduleRecordRebuild = () => {
+          if (recordRebuildTimeout) clearTimeout(recordRebuildTimeout)
+          recordRebuildTimeout = setTimeout(async () => {
+            console.log('[site-content] Records changed, regenerating JSON...')
             try {
-              // Use collectionsConfig (cached from configResolved) or siteContent
-              const collections = collectionsConfig || siteContent?.config?.collections
-              if (collections) {
-                const processed = await processCollections(resolvedSitePath, collections, resolvedCollectionsBase, basePath)
-                await writeCollectionFiles(resolvedSitePath, processed, collections)
+              // Use queriesConfig (cached from configResolved) or siteContent
+              const byQuery = queriesConfig || siteContent?.config?.queries
+              if (byQuery) {
+                const processed = await processQueries(resolvedSitePath, byQuery, resolvedEntitiesDir, basePath)
+                await writeQueryFiles(resolvedSitePath, processed, byQuery)
               }
               // Send full reload to client
               server.ws.send({ type: 'full-reload' })
             } catch (err) {
-              console.error('[site-content] Collection rebuild failed:', err.message)
+              console.error('[site-content] Record rebuild failed:', err.message)
             }
           }, 100)
         }
@@ -991,23 +988,21 @@ export function siteContentPlugin(options = {}) {
           // head.html may not exist, that's ok
         }
 
-        // Watch content/ folder for collection changes
-        // Use collectionsConfig cached from configResolved (siteContent may be null here)
-        if (collectionsConfig) {
-          const contentPaths = new Set()
-          const collectionBase = resolvedCollectionsBase || resolvedSitePath
-          for (const config of Object.values(collectionsConfig)) {
-            const collectionPath = typeof config === 'string' ? config : config.path
-            if (collectionPath) {
-              contentPaths.add(resolve(collectionBase, collectionPath))
-            }
-          }
+        // ⭐ 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
+        // recursive root and covers every schema, present and future.
+        {
+          const contentPaths = new Set([
+            resolve(resolvedSitePath, resolvedEntitiesDir || ENTITIES_DIR)
+          ])
 
           for (const contentPath of contentPaths) {
             if (existsSync(contentPath)) {
               try {
-                watchers.push(watch(contentPath, { recursive: true }, scheduleCollectionRebuild))
-                console.log(`[site-content] Watching ${contentPath} for collection changes`)
+                watchers.push(watch(contentPath, { recursive: true }, scheduleRecordRebuild))
+                console.log(`[site-content] Watching ${contentPath} for record changes`)
               } catch (err) {
                 console.warn('[site-content] Could not watch content directory:', err.message)
               }
@@ -1028,7 +1023,7 @@ export function siteContentPlugin(options = {}) {
           const localeWatcher = watch(localesPath, { recursive: false }, () => {
             console.log('[site-content] Translation files changed, clearing cache...')
             localeTranslations = {}
-            collectionTranslations = {}
+            recordTranslations = {}
             server.ws.send({ type: 'full-reload' })
           })
           additionalWatchers.push(localeWatcher)
@@ -1053,16 +1048,16 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Watch collection translations directory
-        const collectionsLocalesPath = resolve(localesPath, 'collections')
-        if (existsSync(collectionsLocalesPath)) {
+        const recordLocalesPath = resolve(localesPath, 'records')
+        if (existsSync(recordLocalesPath)) {
           try {
-            const collWatcher = watch(collectionsLocalesPath, { recursive: false }, () => {
-              console.log('[site-content] Collection translations changed, clearing cache...')
-              collectionTranslations = {}
+            const collWatcher = watch(recordLocalesPath, { recursive: false }, () => {
+              console.log('[site-content] Record translations changed, clearing cache...')
+              recordTranslations = {}
               server.ws.send({ type: 'full-reload' })
             })
             additionalWatchers.push(collWatcher)
-            console.log(`[site-content] Watching ${collectionsLocalesPath} for collection translation changes`)
+            console.log(`[site-content] Watching ${recordLocalesPath} for record translation changes`)
           } catch (err) {
             // collections locales dir may not exist, that's ok
           }
@@ -1212,7 +1207,7 @@ export function siteContentPlugin(options = {}) {
         if (localeDataMatch) {
           const locale = localeDataMatch[1]
           const filename = localeDataMatch[2]
-          const collectionName = filename.replace('.json', '')
+          const queryName = filename.replace('.json', '')
           const sourcePath = join(resolvedSitePath, 'public', DATA_DIR, filename)
 
           if (existsSync(sourcePath)) {
@@ -1221,15 +1216,15 @@ export function siteContentPlugin(options = {}) {
               const items = JSON.parse(raw)
 
               // Load collection translations for this locale
-              const translations = await loadCollectionTranslations(locale) || {}
+              const translations = await loadRecordTranslations(locale) || {}
 
               // Check for free-form translations
               const freeformDir = join(resolvedSitePath, localesDir, 'freeform', locale)
               const hasFreeform = existsSync(freeformDir)
 
               // Translate using the collections module
-              const { translateCollectionData } = await import('../i18n/collections.js')
-              const translated = await translateCollectionData(items, collectionName, resolvedSitePath, {
+              const { translateRecordData } = await import('../i18n/records.js')
+              const translated = await translateRecordData(items, queryName, resolvedSitePath, {
                 locale,
                 localesDir: join(resolvedSitePath, localesDir),
                 translations,
@@ -1240,7 +1235,7 @@ export function siteContentPlugin(options = {}) {
               res.end(JSON.stringify(translated, null, 2))
               return
             } catch (err) {
-              console.warn(`[site-content] Failed to serve localized collection ${filename}: ${err.message}`)
+              console.warn(`[site-content] Failed to serve localized records ${filename}: ${err.message}`)
               // Fall through to Vite's static server
             }
           }