uniweb 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.33.0",
+  "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/runtime": "^0.13.1",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/core": "^0.13.1",
-    "@uniweb/kit": "^0.14.0"
+    "@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.0",
-    "@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,6 +27,7 @@ import {
   computeUnitHashes,
   collectUnitUuids,
   collectFolderItemUuids,
+  collectQueryUuids,
   readAssetMap
 } from '@uniweb/build/uwx'
 
@@ -241,6 +242,7 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
   const prior = readSyncCacheFile(siteDir)
   const dropped = [
     'itemUuids',
+    'queryUuids',
     'hashes',
     'baseVersions',
     'unitBases',
@@ -248,6 +250,9 @@ export function clearRemoteSyncState(siteDir, siteUuid = null) {
   ].filter((k) => prior[k] && Object.keys(prior[k]).length)
   updateSyncCache(siteDir, {
     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.
+    queryUuids: {},
     hashes: {},
     baseVersions: {},
     unitBases: {},
@@ -468,6 +473,32 @@ export function readItemUuids(siteDir) {
 export function readFolderItemUuids(siteDir) {
   return readMap(siteDir, 'folderItemUuids')
 }
+
+/**
+ * Collection-declaration identity: `{ <collection name>: <backend $uuid> }`.
+ *
+ * ⛔ THE THIRD MAP, AND EACH ONE EXISTS FOR THE SAME REASON. `itemUuids` is keyed by
+ * the file an item projects to. Two kinds of item have no file of their own — a
+ * folder's placements, and a collection DECLARATION (they all live in one
+ * `collections/collections.yml`) — so a path-keyed map has no shape either could
+ * occupy, and a push re-sends that whole section uuid-less.
+ *
+ * The backend refuses an all-blank section over stored items rather than applying it,
+ * because applying it would insert every record fresh and delete every stored row —
+ * content survives, identity does not. So `push` worked once and every push after was
+ * refused. Measured 2026-08-29; collab framework-backend-812b.
+ *
+ * ⭐ Keyed by NAME, which the backend enforces unique within the section and uses as
+ * 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 readQueryUuids(siteDir) {
+  return readMap(siteDir, 'queryUuids')
+}
+export function writeQueryUuids(siteDir, map) {
+  if (!map || !Object.keys(map).length) return
+  updateSyncCache(siteDir, { queryUuids: map })
+}
 export function writeFolderItemUuids(siteDir, map) {
   if (!map || !Object.keys(map).length) return
   updateSyncCache(siteDir, { folderItemUuids: map })
@@ -937,31 +968,83 @@ 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
   // resolution one. Measured on matinee 2026-08-29: `status` reported 4 changed
   // 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.records?.entityCount || 0)
+  return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
+}
+
+/**
+ * The emit whose hashes are comparable with the banked ones — ONE definition.
+ *
+ * ⛔ EVERY DEFECT IN THIS AREA HAS BEEN A WRITER AND A READER DISAGREEING ABOUT
+ * WHICH DOCUMENT A HASH DESCRIBES, so the option set that makes them agree must
+ * have a single home. Assembled from three sources, each for a stated reason:
+ *
+ *   · BANKED     the injections the push applied before hashing — serve URLs and
+ *                the pinned foundation ref, which only a round trip produces.
+ *   · RE-DERIVED asset identity, from the COMMITTED `assets.json`, so a moved map
+ *                reads as changed rather than matching a copy of itself.
+ *   · RECORDED   the site's org, which resolves a foundation-relative `@/x` into
+ *                the `@org/x` the push keyed its hashes by, and the collection
+ *                identity a push stamps — so `status` hashes the same document a
+ *                push would send rather than one missing a section's `$uuid`s.
+ *
+ * Offline by design — measured at zero HTTP requests, a property the cross-client
+ * flows rely on.
+ */
+async function comparisonEmit(siteDir, { priorHashes = {}, sendAll = false } = {}) {
   const applied = readAppliedInjections(siteDir)
   const assetIds = readAssetMap(siteDir)
   const org = readSiteOrg(siteDir)
-  const pkg = await emitSyncPackages(siteDir, {
+  const queryUuids = readQueryUuids(siteDir)
+  return emitSyncPackages(siteDir, {
     resolveModel: makeModelResolver({ client: null, offline: true }),
     priorHashes,
     sendAll,
     ...applied,
+    ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
     ...(Object.keys(assetIds).length ? { assetIds } : {}),
     ...(org ? { org } : {})
   })
-  const changed =
-    (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
-  return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
+}
+
+/**
+ * Re-bank the send-only-changed hashes over the files as they NOW stand.
+ *
+ * ⛔ FOR A WRITER THAT REWRITES THE WORKING TREE — today, `uniweb pull`.
+ *
+ * A pull projects the backend's document into source files, and that projection is
+ * canonical rather than byte-identical to what was there: it moves section ordering
+ * out of filename prefixes (`1-hero.md` → `hero.md` plus an explicit `sections:`
+ * list) and stamps each section's `id`. Lossless, and a different document.
+ *
+ * ⚠️ `pull` already knew this for the OTHER map — it clears the `local` unit base
+ * because "what we would emit from them is not byte-identical to it, so the old
+ * local base no longer describes anything". That reasoning was never carried to the
+ * hashes, which were left STALE rather than unknown: the next `uniweb status`
+ * reported the site as having unpushed content immediately after a pull, forever.
+ * Measured on matinee 2026-08-29 — `push → pull` reported 1 changed of 8.
+ *
+ * ⭐ Re-banking is the correct answer rather than clearing, because after a pull the
+ * on-disk state IS the agreed state: it came from the backend. A push with no edits
+ * in between should send nothing, and clearing would make it send everything.
+ */
+export async function rebankSyncHashes(siteDir) {
+  const pkg = await comparisonEmit(siteDir, { sendAll: true })
+  writeSyncCache(siteDir, pkg.hashes || {}, pkg.applied || {})
+  return Object.keys(pkg.hashes || {}).length
 }
 
 /**
@@ -986,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)
 
@@ -1063,18 +1146,47 @@ export async function pushSyncPackages({
         return null
       }
       if (problem?.reason === 'identity_required') {
+        // ⛔ THE REFUSAL IS PER-SECTION, NOT PER-PUSH, AND WE USED TO SAY OTHERWISE.
+        //
+        // The backend asks, of each section independently: is this section's ENTIRE
+        // incoming record set uuid-less while the stored entity already has items in
+        // it? So a push can carry correct identity for most of the document and still
+        // be refused over one section it stamps none of — and the old wording ("this
+        // copy has no record of the site's item identity", "the recovery … could not
+        // reach the backend", "`uniweb pull` also restores it") was wrong on all
+        // three counts in exactly that case: the copy has identity, no recovery was
+        // attempted, and a pull changes nothing.
+        //
+        // ⭐ THE BACKEND ALREADY SENDS WHAT LOCATES IT — `section_id`,
+        // `records_without_uuid`, `stored_items` — and this branch discarded every
+        // one of them, so every refusal anyone collected was missing the only fields
+        // that say WHERE. (Named by backend in collab `framework-backend-812b`,
+        // 2026-08-28: "the offending section and both counts have been in the body of
+        // every refusal you have collected".)
+        const n = problem.records_without_uuid
+        const stored = problem.stored_items
+        // `section_name` landed backend-side 2026-08-28 (`90e7cd7e`), replacing an
+        // i64 row id we could not resolve. The fallback stays for an older backend,
+        // not because the swap is pending — it is done.
+        const where = problem.section_name ?? problem.section_id
         error(
-          `${label} push refused — this copy has no record of the site's item identity.`
-        )
-        note(
-          'Nothing was written. Pushing without it would have replaced the identity of every stored item.'
-        )
-        note(
-          'The recovery normally runs automatically, so it likely could not reach the backend.'
+          `${label} push refused — one section carries no item identity` +
+            (where === undefined ? '.' : ` (section ${where}).`)
         )
+        if (Number.isInteger(n) && Number.isInteger(stored)) {
+          note(
+            `That section sent ${n} record(s), none carrying a \`$uuid\`, while ${stored} item(s) are already stored there.`
+          )
+        }
         note(
-          'Check your connection and re-run; `uniweb pull` also restores it.'
+          'Nothing was written. Applying it would have replaced the identity of every stored item in that section.'
         )
+        // ⚠️ Deliberately NOT "run `uniweb pull`". A pull re-harvests identity from
+        // the backend's own document, so it fixes a LOST cache — and does nothing at
+        // all when the cache is intact and one section simply has no entry in it,
+        // which is the case this message now names. Suggesting it there sends the
+        // user to re-fetch a map they already have.
+        if (problem.detail) note(String(problem.detail))
         return null
       }
       if (problem?.reason === 'stale_base') {
@@ -1160,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.'
         )
@@ -1264,6 +1376,16 @@ export async function pushSyncPackages({
       }
       harvest(finalized)
       siteFinalizedDoc = finalized[0]?.document || null
+      // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
+      // placements below. These items have no file to back-fill into — they all
+      // come from one `collections/collections.yml` — so the only place their
+      // `$uuid` can live is the cache, keyed by the name the backend enforces
+      // unique. Without it every push after the first re-sends the whole
+      // `collections` section uuid-less and is refused.
+      if (siteFinalizedDoc) {
+        const recordIds = collectQueryUuids(siteFinalizedDoc)
+        if (Object.keys(recordIds).length) writeQueryUuids(siteDir, recordIds)
+      }
       finalizedTotal += finalized.length
     } else {
       const payload = await postLane('site-content', () =>
@@ -1307,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 }
     )
@@ -1325,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).')