uniweb 0.33.1 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.13.1",
-    "@uniweb/kit": "^0.14.0",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/runtime": "^0.13.1"
+    "@uniweb/kit": "^0.15.0",
+    "@uniweb/runtime": "^0.13.2",
+    "@uniweb/core": "^0.14.0",
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.29.1",
-    "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.3.1"
+    "@uniweb/build": "^0.30.0",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/content-reader": "^1.2.4"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -770,24 +770,36 @@ seo:
 
 That emits a `Content-Signal:` line in `robots.txt`. Declare only what you mean — an omitted signal says nothing, which is not the same as saying no.
 
-### Collections and dynamic routes
+### Records, queries and dynamic routes
 
-Most content lives in `pages/` — a fixed composition of sections on a fixed set of pages. **Collections are the other kind: repeating content managed as a set of files**, one item per file, that pages pull from. Blog posts, team members, products, case studies, bibliographies.
+Most content lives in `pages/` — a fixed composition of sections on a fixed set of pages. **The other kind is a set of records: repeating content managed as one file per item**, that pages pull from. Blog posts, team members, products, case studies, bibliographies.
 
-They're delivered through the **same data pipeline as remote APIs**, so from a component's point of view a locally-authored collection and a backend-served one look identical. Whether the records live in files or behind an endpoint is a transport concern (see *Fetching from other sources* in Part 4).
+It is a small database, not a page tree. Three things, deliberately separate:
 
 ```
 site/
 ├── pages/
-├── collections/
-│   ├── articles/
+├── entities/          # your stored things. The folder names their data schema
+│   ├── article/
 │   │   ├── getting-started.md
 │   │   └── design-tips.md
-│   └── team/
+│   └── person/
 │       └── alice.yml
+├── records.yml        # what is PUBLISHED
+├── queries.yml        # how content is REACHED
 └── site.yml
 ```
 
+**`entities/{schema}/` — the pool.** The folder names the data schema and nothing else:
+
+| on disk | schema |
+|---|---|
+| `entities/article/…` | `@/article` — your foundation's own |
+| `entities/std/person/…` | `@std/person` — the shared standard set |
+| `entities/acme/project/…` | `@acme/project` — an org's |
+
+Keep those folders flat: `entities/article/design-tips.md` works; `entities/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records.yml` instead.
+
 **Four formats, one shape.** All of these produce the same records at runtime:
 
 | Format | Best for | Notes |
@@ -799,62 +811,85 @@ site/
 
 **One record per file, or many.** A single mapping at the top of a file makes one record and the filename stem becomes its `slug`. A top-level array (YAML/JSON) or a multi-entry `.bib` makes many, each carrying its own `slug`. You can mix both in one folder — an exported `refs.bib` beside a hand-written `extras.yml`.
 
-**Keep collection folders flat.** `collections/articles/design-tips.md` works; `collections/articles/2025/design-tips.md` does not.
-
 Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `published`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. `published: false` hides an item without deleting it; items with no `published` field are included.
 
-**Declare each collection in `site.yml`:**
+**`records.yml` — listing an entity is what publishes it.** A file in `entities/` exists; listing it here makes it a record. Anything you leave out is a draft — no flag to set. **The common case is three lines:**
 
 ```yaml
-collections:
-  articles: collections/articles         # simple form — just point at the folder
+- article/*.md
+- person/*.yml
+```
+
+A bare string is a path under `entities/`, naming one file or matching many.
+
+⚠️ **An empty `records.yml` is not the same as having none.** No file means "leave the published set alone". An empty file means "the folder holds nothing", which REMOVES what is published. The CLI asks before it does that.
+
+**Structure is for querying, not for navigation.** Add a `folder:` only when a query needs to ask for a *slice* of the pool rather than all of it — most sites never do:
 
-  team:                                  # extended form
-    path: collections/team               # or `url:` for a remote source
-    sort: order asc                       # `date desc`, `title asc`, …
-    where: { published: { ne: false } }   # a predicate — see authoring/predicates.md
-    limit: 100
+```yaml
+- article/2026-*.md
+- folder: archive
+  label: The Archive
+  records:
+    - article/2025-*.md
+```
+
+A query then slices it with `where: { path: { under: 'archive' } }`. An entity belongs to one folder; if you want a computed subset, that is a query, not a second placement.
+
+**`queries.yml` — how content is reached.** A bare map of name → query. A query names a schema and the published records of that schema are its rows:
+
+```yaml
+recent:
+  schema: '@/article'
+  sort: date desc                        # `date desc`, `title asc`, …
+  limit: 10
+
+team:
+  schema: '@std/person'
+  where: { published: { ne: false } }    # a predicate — see authoring/predicates.md
 ```
 
-**Show a collection on a page** with `data:` in `page.yml` (the whole collection), or `fetch:` in a section's frontmatter (a subset):
+You can keep the same declarations under `queries:` in `site.yml` instead, if you would rather have one file.
+
+**Show a query on a page** with `data:` in `page.yml` (the whole result), or `fetch:` in a section's frontmatter (a subset):
 
 ```yaml
 # pages/blog/page.yml          |   # a section on the homepage
 title: Blog                    |   ---
-data: articles                 |   type: ArticleTeaser
-                               |   fetch: { collection: articles, limit: 3, sort: date desc }
+data: recent                   |   type: ArticleTeaser
+                               |   fetch: { query: recent, limit: 3 }
                                |   ---
 ```
 
-**Give each item its own page with a `[slug]/` folder** under the list page:
+**Give each record its own page with a `[slug]/` folder** under the list page:
 
 ```
 pages/blog/
-├── page.yml          # title: Blog / data: articles
+├── page.yml          # title: Blog / data: recent
 ├── list.md
 └── [slug]/
     ├── page.yml
-    └── article.md    # just `type: Article` — the item arrives automatically
+    └── article.md    # just `type: Article` — the record arrives automatically
 ```
 
-`collections/articles/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
+`entities/article/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
 
-> **The record arrives as a single-element array under the collection key** — `content.data.articles[0]`, not `content.data.article`. The runtime never coerces it to an object and never synthesizes a singular key. See *Data* in Part 4.
+> **The record arrives as a single-element array under the query key** — `content.data.recent[0]`, not `content.data.article`. The runtime never coerces it to an object and never synthesizes a singular key. See *Data* in Part 4.
 
-**Two options for bigger collections:**
+**Two options for bigger sets:**
 
-`deferred: [body]` strips heavy fields from the list payload — cards stay light, while a `[slug]` page still receives the full record automatically and other components fetch on demand via `useEntityDetail`. For a remote collection, add `detailUrl: /api/articles/{slug}` so the framework knows how to fetch one full record; file-based collections emit per-record files at `/data/<name>/<slug>.json` and need no configuration.
+`deferred: [body]` strips heavy fields from the list payload — cards stay light, while a `[slug]` page still receives the full record automatically and other components fetch on demand via `useEntityDetail`. For a remote source, add `detailUrl: /api/articles/{slug}` so the framework knows how to fetch one full record; file-based records emit per-record files at `/data/<name>/<slug>.json` and need no configuration.
 
 `queryable:` declares which fields a reader may filter on, with enough metadata for the foundation to render controls:
 
 ```yaml
-collections:
-  members:
-    path: collections/members
-    queryable:
-      department: { type: enum, label: Department, options: [biology, physics, chemistry] }
-      tenured:    { type: boolean, label: Tenured }
-      start_year: { type: range, label: Start year, min: 1800, max: 2025 }
+# queries.yml
+members:
+  schema: '@std/person'
+  queryable:
+    department: { type: enum, label: Department, options: [biology, physics, chemistry] }
+    tenured:    { type: boolean, label: Tenured }
+    start_year: { type: range, label: Start year, min: 1800, max: 2025 }
 ```
 
 The site declares the *surface*; the foundation reads the metadata, renders matching controls (dropdown, toggle, slider), and composes the predicate when the reader picks values.
@@ -1745,13 +1780,13 @@ A foundation can route a scope to a plain folder of schema files instead of a pa
 ```yaml
 # pages/blog/page.yml
 fetch:
-  collection: articles
+  query: recent
   where: { published: true, tags: featured }
   sort: date desc
   limit: 3
 ```
 
-**Lean lists with `deferred:`.** Collections with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` in `site.yml`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based collections) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`. The hook is safe to call on any collection: when there is no separate detail source it returns the record you passed in, because nothing was stripped from it.
+**Lean lists with `deferred:`.** A query over records with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based records) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`. The hook is safe to call on any query: when there is no separate detail source it returns the record you passed in, because nothing was stripped from it.
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useEntityDetail`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 
@@ -1766,7 +1801,7 @@ A site isn't limited to file-based collections. The `fetcher:` block in `site.ym
 fetcher:
   baseUrl: https://api.example.com
   headers: { X-Tenant: acme }
-  envelope: { collection: data.items, item: data.article, error: errors.0.message }
+  envelope: { list: data.items, item: data.article, error: errors.0.message }
 
   supports: [where, limit, sort]     # which operators the source evaluates natively
 
@@ -2383,12 +2418,12 @@ Running `extract` before a build is the usual first mistake — it reads the com
 
 ```
 locales/freeform/es/pages/about/hero.md        # by page route
-locales/freeform/es/collections/articles/x.md  # collections work too
+locales/freeform/es/entities/article/x.md      # records work too
 ```
 
 These are **body only — no frontmatter**; params and config still come from the source section. `uniweb i18n init-freeform es pages/about hero` creates one pre-filled and records a source hash, so `uniweb i18n status --freeform` can tell you when the original moved on (`update-hash` to acknowledge). `move`, `rename`, and `prune --freeform` keep them aligned when pages get reorganized.
 
-**Collections translate in the same `extract` run**, into their own manifest at `locales/collections/manifest.json`.
+**Records translate in the same `extract` run**, into their own manifest at `locales/records/manifest.json` — keyed by the RECORD, so a record translated once is found by every query that returns it.
 
 **Component side.** Nothing to do: `content.title` arrives in the active language. The one thing a foundation builds is a switcher.
 

package/src/backend/site-sync.js

@@ -27,7 +27,7 @@ import {
   computeUnitHashes,
   collectUnitUuids,
   collectFolderItemUuids,
-  collectCollectionUuids,
+  collectQueryUuids,
   readAssetMap
 } from '@uniweb/build/uwx'
 
@@ -242,7 +242,7 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
   const prior = readSyncCacheFile(siteDir)
   const dropped = [
     'itemUuids',
-    'collectionUuids',
+    'queryUuids',
     'hashes',
     'baseVersions',
     'unitBases',
@@ -252,7 +252,7 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
     itemUuids: {},
     // Remote-derived exactly like itemUuids — it holds the OLD site's collection
     // ids, and surviving the drop it would offer them for the new site's sections.
-    collectionUuids: {},
+    queryUuids: {},
     hashes: {},
     baseVersions: {},
     unitBases: {},
@@ -492,12 +492,12 @@ export function readFolderItemUuids(siteDir) {
  * its own join key. ⛔ Not `$id`: it holds the same string but is a payload-local
  * handle the backend skips on parse and never stores.
  */
-export function readCollectionUuids(siteDir) {
-  return readMap(siteDir, 'collectionUuids')
+export function readQueryUuids(siteDir) {
+  return readMap(siteDir, 'queryUuids')
 }
-export function writeCollectionUuids(siteDir, map) {
+export function writeQueryUuids(siteDir, map) {
   if (!map || !Object.keys(map).length) return
-  updateSyncCache(siteDir, { collectionUuids: map })
+  updateSyncCache(siteDir, { queryUuids: map })
 }
 export function writeFolderItemUuids(siteDir, map) {
   if (!map || !Object.keys(map).length) return
@@ -968,12 +968,12 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   //
   // ⛔ THE ORG IS NOT OPTIONAL HERE, AND OMITTING IT WAS SILENT. It is what resolves
   // a foundation-relative `@/member` into the `@org/member` the push shipped and
-  // keyed its hashes by. Without it the emit does not fail — `buildCollectionEntities`
+  // keyed its hashes by. Without it the emit does not fail — `buildRecordEntities`
   // WARNS and ships the model unresolved, deliberately, so an org-less export still
   // works — so every record of a `@/`-scoped collection is emitted under a key that
   // can never match its banked one, and reads as changed forever.
   //
-  // ⚠️ It hides in plain sight because `@std/…` collections are unaffected: their
+  // ⚠️ It hides in plain sight because `@std/…` queries are unaffected: their
   // scope is already absolute, so they match. A site mixing both — the marketing
   // fixture has `@std/person` AND `@proximify/member` — shows some records settling
   // and others never settling, which reads like a content problem rather than a
@@ -981,7 +981,7 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
   // immediately after a successful push; passing the org took it to 1.
   const pkg = await comparisonEmit(siteDir, { priorHashes, sendAll })
   const changed =
-    (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
+    (pkg.siteContent?.entityCount || 0) + (pkg.records?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -1008,13 +1008,13 @@ async function comparisonEmit(siteDir, { priorHashes = {}, sendAll = false } = {
   const applied = readAppliedInjections(siteDir)
   const assetIds = readAssetMap(siteDir)
   const org = readSiteOrg(siteDir)
-  const collectionUuids = readCollectionUuids(siteDir)
+  const queryUuids = readQueryUuids(siteDir)
   return emitSyncPackages(siteDir, {
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
     ...applied,
-    ...(Object.keys(collectionUuids).length ? { collectionUuids } : {}),
+    ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
     ...(Object.keys(assetIds).length ? { assetIds } : {}),
     ...(org ? { org } : {})
   })
@@ -1069,7 +1069,7 @@ export async function pushSyncPackages({
   asOrg,
   report
 }) {
-  const { siteContent, collections, siteContentUuid, hashes, applied } = pkg
+  const { siteContent, records, siteContentUuid, hashes, applied } = pkg
   const { info, note, error } = report
   const dim = report.dim || ((s) => s)
 
@@ -1272,8 +1272,8 @@ export async function pushSyncPackages({
         // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
         // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
         note(
-          "This site's collection structure is already established on the backend and can't be changed " +
-            'in place — e.g. adding or removing a schema-backed collection, or switching one between ' +
+          "This site's record structure is already established on the backend and can't be changed " +
+            'in place — e.g. adding or removing a schema-backed query, or switching one between ' +
             'static (data-bundle) and schema-backed delivery. To change it: delete the deployed site and ' +
             'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
         )
@@ -1383,8 +1383,8 @@ export async function pushSyncPackages({
       // unique. Without it every push after the first re-sends the whole
       // `collections` section uuid-less and is refused.
       if (siteFinalizedDoc) {
-        const collectionIds = collectCollectionUuids(siteFinalizedDoc)
-        if (Object.keys(collectionIds).length) writeCollectionUuids(siteDir, collectionIds)
+        const recordIds = collectQueryUuids(siteFinalizedDoc)
+        if (Object.keys(recordIds).length) writeQueryUuids(siteDir, recordIds)
       }
       finalizedTotal += finalized.length
     } else {
@@ -1429,16 +1429,16 @@ export async function pushSyncPackages({
   // site-content uuid. On a brand-new site the backend creates the folder on this first
   // push. Records round-trip their own $uuid (back-filled into source files); the folder
   // itself has no uuid (the backend owns it).
-  if (collections) {
+  if (records) {
     if (!boundSiteUuid) {
       error(
-        'Cannot push collections — the site has no uuid yet. Push the site-content lane first.'
+        'Cannot push records — the site has no uuid yet. Push the site-content lane first.'
       )
       return { exitCode: 1, finalizedTotal, wrote }
     }
     const finalized = await pushLane(
-      'collections',
-      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg }),
+      'records',
+      () => client.pushFolder(boundSiteUuid, records.buffer, { asOrg }),
       undefined,
       { boundUuid: boundSiteUuid }
     )
@@ -1447,7 +1447,7 @@ export async function pushSyncPackages({
       return { exitCode: 1, finalizedTotal, wrote }
     }
     harvest(finalized)
-    const bf = backfillEntityUuids({ index: collections.index, finalized })
+    const bf = backfillEntityUuids({ index: records.index, finalized })
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
     if (bf.updated.length)

package/src/commands/build.js

@@ -592,7 +592,7 @@ function resolveFoundationDir(projectDir, siteConfig) {
  *
  * The `buildLocalizedContent` step is the same call bundle mode makes
  * post-vite, so multi-locale sites get identical per-locale outputs in
- * either mode. Collection translation (`buildLocalizedCollections`)
+ * either mode. Collection translation (`buildLocalizedRecords`)
  * also runs here so deploy ships translated collection JSONs.
  *
  * Bug surfaced + fixed by routing deploy through this path: the bundle
@@ -652,28 +652,28 @@ async function buildSiteLink(projectDir, options = {}) {
       // Collection translations — optional; don't fail the build if
       // missing. Bundle mode does the same.
       try {
-        const { buildLocalizedCollections } = await import('@uniweb/build/i18n')
-        const collectionOutputs = await buildLocalizedCollections(projectDir, {
+        const { buildLocalizedRecords } = await import('@uniweb/build/i18n')
+        const recordOutputs = await buildLocalizedRecords(projectDir, {
           locales: i18nConfig.locales,
           outputDir: distDir,
-          collectionsLocalesDir: join(
+          recordLocalesDir: join(
             projectDir,
             i18nConfig.localesDir,
-            'collections'
+            'records'
           )
         })
-        const collectionCount = Object.values(collectionOutputs).reduce(
+        const recordCount = Object.values(recordOutputs).reduce(
           (sum, localeOutputs) => sum + Object.keys(localeOutputs).length,
           0
         )
-        if (collectionCount > 0) {
+        if (recordCount > 0) {
           success(
-            `Translated collections for ${Object.keys(collectionOutputs).length} locale(s)`
+            `Translated records for ${Object.keys(recordOutputs).length} locale(s)`
           )
         }
       } catch (err) {
         if (process.env.UNIWEB_DEBUG)
-          console.error('Collection translation:', err.message)
+          console.error('Record translation:', err.message)
       }
     } catch (err) {
       error(`i18n build failed: ${err.message}`)
@@ -772,33 +772,33 @@ async function buildSite(projectDir, options = {}) {
 
       // Translate collections if they exist
       try {
-        const { buildLocalizedCollections } = await import('@uniweb/build/i18n')
+        const { buildLocalizedRecords } = await import('@uniweb/build/i18n')
 
-        const collectionOutputs = await buildLocalizedCollections(projectDir, {
+        const recordOutputs = await buildLocalizedRecords(projectDir, {
           locales: i18nConfig.locales,
           outputDir: join(projectDir, 'dist'),
-          collectionsLocalesDir: join(
+          recordLocalesDir: join(
             projectDir,
             i18nConfig.localesDir,
-            'collections'
+            'records'
           )
         })
 
         // Count collections translated
-        const collectionCount = Object.values(collectionOutputs).reduce(
+        const recordCount = Object.values(recordOutputs).reduce(
           (sum, localeOutputs) => sum + Object.keys(localeOutputs).length,
           0
         )
 
-        if (collectionCount > 0) {
+        if (recordCount > 0) {
           success(
-            `Translated collections for ${Object.keys(collectionOutputs).length} locale(s)`
+            `Translated records for ${Object.keys(recordOutputs).length} locale(s)`
           )
         }
       } catch (err) {
         // Collection translation is optional, don't fail build
         if (process.env.UNIWEB_DEBUG) {
-          console.error('Collection translation:', err.message)
+          console.error('Record translation:', err.message)
         }
       }
     } catch (err) {

package/src/commands/clone.js

@@ -24,7 +24,7 @@
  *      seed;
  *   4. install, then delegate the projection to the project-local `uniweb pull` (which
  *      resolves the now-installed project-local `@uniweb/build`; clone forwards
- *      `--no-collections` to it when set).
+ *      `--no-records` to it when set).
  *
  * Sites are private — authenticate with `uniweb login` first; the session carries
  * identity + the backend origin. There is no `--foundation` flag: the site carries
@@ -37,7 +37,7 @@
  *                                        the current workspace when run inside one)
  *   uniweb clone <uuid> --path sites     Place under sites/ (segregated layout)
  *   uniweb clone <uuid> --project docs   Co-located docs/site
- *   uniweb clone <uuid> --no-collections Pull pages only; skip collection records
+ *   uniweb clone <uuid> --no-records Pull pages only; skip records
  *
  * Backend: via BackendClient (the site-content pull lane). Origin from
  *   --registry  >  UNIWEB_REGISTER_URL  >  the local default (internal dev overrides;
@@ -176,7 +176,7 @@ export async function clone(args = [], deps = {}) {
   if (!siteUuid) {
     error('Missing site uuid.')
     log(
-      `\nUsage: ${getCliPrefix()} clone <site-uuid> [name|.] [--path <dir>] [--project <name>] [--no-collections]`
+      `\nUsage: ${getCliPrefix()} clone <site-uuid> [name|.] [--path <dir>] [--project <name>] [--no-records]`
     )
     log(
       `${colors.dim}Sites are private — run \`uniweb login\` first.${colors.reset}`
@@ -184,8 +184,8 @@ export async function clone(args = [], deps = {}) {
     return { exitCode: 2 }
   }
 
-  const noCollections =
-    args.includes('--no-collections') || args.includes('--content-only')
+  const noRecords =
+    args.includes('--no-records') || args.includes('--content-only')
   const pathFlag = flagValue(args, '--path')
   const projectFlag = flagValue(args, '--project')
   const tokenFlag = flagValue(args, '--token')
@@ -386,7 +386,7 @@ export async function clone(args = [], deps = {}) {
   // bytes on disk, not of what the scaffolder first wrote.
   recordWritten(
     siteDir,
-    ['site.yml', 'theme.yml', 'head.html', 'collections.yml']
+    ['site.yml', 'theme.yml', 'head.html', 'queries.yml', 'records.yml']
       .map((f) => join(siteDir, f))
       .filter((p) => existsSync(p))
   )
@@ -394,7 +394,7 @@ export async function clone(args = [], deps = {}) {
   const pullExtra = []
   if (explicitBackend) pullExtra.push('--backend', explicitBackend)
   if (tokenFlag) pullExtra.push('--token', tokenFlag)
-  if (noCollections) pullExtra.push('--no-collections')
+  if (noRecords) pullExtra.push('--no-records')
 
   if (deps.skipPull) {
     note('Skipping pull (test mode).')

package/src/commands/content.js

@@ -162,8 +162,7 @@ async function contentExport(args) {
     if (entity.layout_sections?.length)
       counts.layout_sections = entity.layout_sections.length
     if (entity.extensions?.length) counts.extensions = entity.extensions.length
-    if (entity.collections?.length)
-      counts.collections = entity.collections.length
+    if (entity.queries?.length) counts.queries = entity.queries.length
   }
 
   console.log('')
@@ -198,6 +197,6 @@ async function contentExport(args) {
     )
   }
   console.log('')
-  say.warn('v0 scope: media bytes, collection records, and @-nested section')
+  say.warn('v0 scope: media bytes, records, and @-nested section')
   say.dim('hierarchy are not yet carried (documented).')
 }

package/src/commands/doctor.js

@@ -153,8 +153,8 @@ function loadSiteYml(dir) {
 /**
  * Diagnose the compiled-collection output directory.
  *
- * `public/<DATA_DIR>/` holds what the build compiles from `collections/`, and
- * nothing else — `collections/` is the only supported way to provide
+ * `public/<DATA_DIR>/` holds what the build compiles from `entities/`, and
+ * nothing else — `entities/` + `records.yml` is the only supported way to provide
  * structured data. Two consequences, both checked here:
  *
  * 1. **The mapping is a bijection.** Every entry should be backed by a
@@ -548,9 +548,33 @@ export async function checkFormSubmitTarget({ sitePath, siteName, siteYml, issue
   )
 }
 
+/** The bare map in `queries.yml`, or `{}` when there is none. */
+function readQueriesYml(sitePath) {
+  try {
+    const doc = yaml.load(readFileSync(join(sitePath, 'queries.yml'), 'utf8'))
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {}
+  } catch {
+    return {}
+  }
+}
+
 function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix, fixed }) {
   const dataDir = join(sitePath, 'public', DATA_DIR)
-  const declared = new Set(Object.keys(siteYml.collections || {}))
+  // ⚠️ THE QUERIES, not the pool. `public/<DATA_DIR>/x.json` is a query's
+  // MATERIALIZATION — one file per named query — so the bijection is with the
+  // declared queries, never with the schema folders under `entities/`.
+  //
+  // ⛔ BOTH HOMES, or this reports every compiled file as an orphan. A site that
+  // keeps its queries in `queries.yml` has none in `site.yml`, and reading one
+  // file would turn the whole check into a false positive — the loudest possible
+  // failure for a check whose job is to find stale output.
+  //
+  // Read directly rather than through `resolveQueriesConfig`: this pass is
+  // synchronous, and it needs the NAMES rather than resolved declarations.
+  const declared = new Set([
+    ...Object.keys(siteYml.queries || {}),
+    ...Object.keys(readQueriesYml(sitePath))
+  ])
 
   if (existsSync(dataDir)) {
     // A collection `x` owns `x.json` (the cascade) and `x/` (per-record files
@@ -565,16 +589,16 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
       .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
 
     if (orphans.length > 0) {
-      const id = 'orphaned-collection-output'
+      const id = 'orphaned-query-output'
       issues.push({
         id,
         type: 'warning',
         site: siteName,
-        message: `${orphans.length} entr${orphans.length === 1 ? 'y' : 'ies'} in public/${DATA_DIR}/ with no declared collection`
+        message: `${orphans.length} entr${orphans.length === 1 ? 'y' : 'ies'} in public/${DATA_DIR}/ with no declared query`
       })
       warn(`[${id}] Stale output in public/${DATA_DIR}/: ${orphans.join(', ')}`)
       log(
-        `    No collection in site.yml produces ${orphans.length === 1 ? 'it' : 'these'}. ` +
+        `    No query produces ${orphans.length === 1 ? 'it' : 'these'}. ` +
         `${orphans.length === 1 ? 'It is' : 'They are'} still served and deployed.`
       )
       if (shouldFix(id)) {
@@ -614,7 +638,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
       const body = existing === null ? '' : existing.replace(/\n*$/, '\n')
       writeFileSync(
         gitignorePath,
-        `${body}\n# Compiled collections — generated from collections/\n${rule}\n`
+        `${body}\n# Compiled query results — generated from entities/ + queries.yml\n${rule}\n`
       )
       fixed(`added ${rule} to ${gitignorePath}`)
       if (existsSync(dataDir)) {
@@ -891,9 +915,9 @@ export async function doctor(args = []) {
     }
 
     // `public/<DATA_DIR>/` is the build's output directory and nothing else —
-    // `collections/` is the only supported way to provide structured data. That
-    // makes the mapping a bijection: every entry there should be backed by a
-    // declared collection, so anything else is stale, and identifiable.
+    // `entities/` + `records.yml` is the only supported way to provide structured
+    // data. That makes the mapping a bijection: every entry there should be backed
+    // by a declared QUERY, so anything else is stale, and identifiable.
     //
     // It matters because the directory is written into the source tree rather
     // than dist/, so what lands there persists and gets deployed. A collection