uniweb 0.33.1 → 0.34.0

package/src/commands/i18n.js

@@ -242,13 +242,13 @@ async function loadSiteConfig(siteRoot) {
 async function runExtract(siteRoot, config, args) {
   const verbose = args.includes('--verbose') || args.includes('-v')
   const dryRun = args.includes('--dry-run')
-  const collectionsOnly =
-    args.includes('--collections-only') || args.includes('--collections')
-  const noCollections = args.includes('--no-collections')
+  const recordsOnly =
+    args.includes('--records-only') || args.includes('--records')
+  const noRecords = args.includes('--no-records')
   // --with-collections is now a no-op (collections are included by default)
 
-  // Extract page content (unless --collections-only)
-  if (!collectionsOnly) {
+  // Extract page content (unless --records-only)
+  if (!recordsOnly) {
     log(
       `\n${colors.cyan}Extracting translatable content${dryRun ? ' (dry run)' : ''}...${colors.reset}\n`
     )
@@ -309,43 +309,43 @@ async function runExtract(siteRoot, config, args) {
     }
   }
 
-  // Extract collection content (by default, skip with --no-collections)
-  if (!noCollections) {
+  // Extract collection content (by default, skip with --no-records)
+  if (!noRecords) {
     log(
-      `\n${colors.cyan}Extracting collection content${dryRun ? ' (dry run)' : ''}...${colors.reset}\n`
+      `\n${colors.cyan}Extracting record content${dryRun ? ' (dry run)' : ''}...${colors.reset}\n`
     )
 
     // Check if collections exist
     const dataDir = join(siteRoot, 'public', DATA_DIR)
     if (!existsSync(dataDir)) {
-      if (collectionsOnly) {
-        error('No collections found. Create collection data in public/data/.')
+      if (recordsOnly) {
+        error('No records found. Add entities under entities/ and list them in records.yml.')
         process.exit(1)
       }
-      log(`${colors.dim}No collections found in public/data/.${colors.reset}`)
+      log(`${colors.dim}No records found in public/data/.${colors.reset}`)
       return
     }
 
     try {
-      const { extractCollectionManifest, formatSyncReport } =
+      const { extractRecordManifest, formatSyncReport } =
         await import('@uniweb/build/i18n')
 
-      const collectionsManifestPath = join(
+      const recordManifestPath = join(
         siteRoot,
         config.localesDir,
-        'collections',
+        'records',
         'manifest.json'
       )
-      const isUpdate = existsSync(collectionsManifestPath)
+      const isUpdate = existsSync(recordManifestPath)
 
-      const { manifest, report } = await extractCollectionManifest(siteRoot, {
+      const { manifest, report } = await extractRecordManifest(siteRoot, {
         localesDir: config.localesDir,
         dryRun
       })
 
       const unitCount = Object.keys(manifest.units).length
       if (unitCount > 0) {
-        success(`Extracted ${unitCount} translatable strings from collections`)
+        success(`Extracted ${unitCount} translatable strings from records`)
 
         if (report && isUpdate) {
           log('')
@@ -356,18 +356,18 @@ async function runExtract(siteRoot, config, args) {
           log(`\n${colors.dim}Dry run — no files were modified.${colors.reset}`)
         } else {
           log(
-            `\nManifest written to: ${colors.dim}${config.localesDir}/collections/manifest.json${colors.reset}`
+            `\nManifest written to: ${colors.dim}${config.localesDir}/records/manifest.json${colors.reset}`
           )
         }
       } else {
         log(
-          `${colors.dim}No translatable content found in collections.${colors.reset}`
+          `${colors.dim}No translatable content found in records.${colors.reset}`
         )
       }
     } catch (err) {
-      error(`Collection extraction failed: ${err.message}`)
+      error(`Record extraction failed: ${err.message}`)
       if (verbose) console.error(err)
-      if (collectionsOnly) process.exit(1)
+      if (recordsOnly) process.exit(1)
     }
   }
 }
@@ -652,7 +652,7 @@ async function runStatusFreeform(siteRoot, config, locale, options = {}) {
       const allPaths = [
         ...discovered.pages,
         ...discovered.pageIds,
-        ...discovered.collections
+        ...discovered.records
       ]
 
       // Check staleness
@@ -988,11 +988,11 @@ async function runAudit(siteRoot, config, args) {
  * Usage:
  *   uniweb i18n init-freeform es pages/about hero
  *   uniweb i18n init-freeform es page-ids/installation intro
- *   uniweb i18n init-freeform es collections/articles getting-started
+ *   uniweb i18n init-freeform es entities/article getting-started
  */
 async function runInitFreeform(siteRoot, config, args) {
   const locale = args[0]
-  const pathType = args[1] // pages/about, page-ids/installation, collections/articles
+  const pathType = args[1] // pages/about, page-ids/installation, entities/article
   const sectionId = args[2] // hero, intro, getting-started
 
   if (!locale || !pathType || !sectionId) {
@@ -1001,7 +1001,7 @@ async function runInitFreeform(siteRoot, config, args) {
     log('  uniweb i18n init-freeform es pages/about hero')
     log('  uniweb i18n init-freeform es page-ids/installation intro')
     log(
-      `  uniweb i18n init-freeform es collections/articles getting-started${colors.reset}`
+      `  uniweb i18n init-freeform es entities/article getting-started${colors.reset}`
     )
     process.exit(1)
   }
@@ -1057,15 +1057,29 @@ async function runInitFreeform(siteRoot, config, args) {
           if (sourceContent) break
         }
       }
-    } else if (pathType.startsWith('collections/')) {
-      // Find item in collection data
-      const collectionName = pathType.replace('collections/', '')
-      const dataPath = join(
-        siteRoot,
-        'public',
-        'data',
-        `${collectionName}.json`
-      )
+    } else if (pathType.startsWith('entities/')) {
+      // ⛔ ADDRESSED BY THE RECORD, matching where the loader reads. The freeform
+      // tree is `entities/<schema dirs>/<slug>.md`; this used to take
+      // `collections/<query>` and write a path nothing read — the loader moved
+      // and this did not.
+      //
+      // The record's CONTENT still lives in a query's materialization, so the
+      // query that covers this schema is resolved rather than named.
+      const poolDirs = pathType.replace('entities/', '')
+      const { resolveQueriesConfig, poolDirsForSchema } = await import('@uniweb/build/uwx')
+      let queryName = null
+      try {
+        const { declarations } = await resolveQueriesConfig(siteRoot)
+        for (const [name, decl] of Object.entries(declarations || {})) {
+          const dirs = decl.schema ? poolDirsForSchema(decl.schema) : null
+          if (dirs && dirs.join('/') === poolDirs) { queryName = name; break }
+        }
+      } catch {
+        /* no resolvable config — fall through to the not-found message below */
+      }
+      const dataPath = queryName
+        ? join(siteRoot, 'public', 'data', `${queryName}.json`)
+        : join(siteRoot, 'public', 'data', '__none__.json')
 
       if (existsSync(dataPath)) {
         const dataRaw = await readFile(dataPath, 'utf-8')
@@ -1607,8 +1621,8 @@ ${colors.bright}Options:${colors.reset}
   --freeform           (status/prune) Include free-form translation status
   --json               (status) Output as JSON for translation tools
   --by-page            (status --missing) Group missing strings by page
-  --collections-only   (extract/status/audit) Process only collections
-  --no-collections     (extract/status/audit) Skip collections (pages only)
+  --records-only   (extract/status/audit) Process only records
+  --no-records     (extract/status/audit) Skip records (pages only)
   --all-stale          (update-hash) Update all stale translations at once
 
 ${colors.bright}Configuration:${colors.reset}
@@ -1638,14 +1652,14 @@ ${colors.bright}File Structure:${colors.reset}
         .manifest.json       Staleness tracking
         pages/about/hero.md  Translated content for /about page, hero section
         page-ids/install/intro.md  Translated content by page ID
-        collections/articles/getting-started.md
+        entities/article/getting-started.md
 
 ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Hash-based workflow${colors.reset}
   uniweb i18n extract                     # Extract all translatable strings
   uniweb i18n extract --dry-run           # Preview without writing
   uniweb i18n extract --verbose           # Show extracted strings
-  uniweb i18n extract --no-collections    # Pages only (skip collections)
+  uniweb i18n extract --no-records    # Pages only (skip records)
   uniweb i18n generate es fr              # Create starter files for Spanish and French
   uniweb i18n generate --empty            # Create files with empty values (for translators)
   uniweb i18n generate --force            # Overwrite existing locale files
@@ -1658,7 +1672,7 @@ ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Free-form workflow (complete section replacement)${colors.reset}
   uniweb i18n init-freeform es pages/about hero
   uniweb i18n init-freeform es page-ids/installation intro
-  uniweb i18n init-freeform es collections/articles getting-started
+  uniweb i18n init-freeform es entities/article getting-started
   uniweb i18n status --freeform    # Show free-form translation status
   uniweb i18n update-hash es --all-stale  # Update hashes after review
   uniweb i18n move pages/docs/setup pages/getting-started

package/src/commands/publish.js

@@ -70,6 +70,7 @@ import {
   readSiteIdentity
 } from '../utils/site-identity.js'
 import { isNonInteractive, confirm } from '../utils/interactive.js'
+import { guardEmptyRecords } from '../utils/records-guard.js'
 import { headProvenance } from '../utils/git.js'
 import {
   makeModelResolver,
@@ -93,7 +94,7 @@ import {
   readPaymentRefusal,
   reportPaymentRefusal
 } from '../backend/payment-handoff.js'
-import { reportSchemalessCollections } from '../utils/schemaless-report.js'
+import { reportSchemalessQueries } from '../utils/schemaless-report.js'
 import { uploadSiteData } from '../utils/site-data-upload.js'
 
 const c = {
@@ -113,7 +114,20 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
-// Origin-relative serve path → clickable absolute URL (self-serve default).
+// Origin-relative serve path → clickable absolute URL.
+//
+// ⭐ THE TWO SHAPES ARE A CONTRACT, NOT AN INCONSISTENCY — ratified 2026-08-29 and
+// documented in the backend's `wire-layer.md` rather than merely observed. A publish
+// returns an ABSOLUTE url when Cloudflare hosts the site (another origin entirely)
+// and an ORIGIN-RELATIVE path when the backend serves it itself, where its own
+// external origin is not reliably self-reportable from behind an ALB.
+//
+// ⇒ So this branch is implementing the contract, not defending against drift. I
+// reported the two shapes as a violation of "finished values only" in collab
+// framework-backend-812b; the backend checked, found the adjacent ruling that
+// explains the relative arm, and ratified both. Do not "fix" it by demanding one
+// shape — the caller's own origin is the missing half on the relative arm, and we
+// are the caller.
 function absolutizeServeUrl(origin, url) {
   if (!url || typeof url !== 'string') return null
   if (/^https?:\/\//.test(url)) return url
@@ -436,6 +450,14 @@ export async function publish(args = []) {
   // Non-local @std/registry Model schemas resolve through the backend (same as push).
   const resolveModel = makeModelResolver({ client, offline: false })
 
+  // ⛔ AN EMPTY `records.yml` REMOVES. It is the one path where an ordinary act is
+  // destructive — a placeholder file, created meaning to fill it in — so the count
+  // is reported and confirmed before anything is sent.
+  {
+    const guard = await guardEmptyRecords({ siteDir, args, warn: say.warn, note: say.dim })
+    if (!guard.ok) return { exitCode: 1 }
+  }
+
   // 3. Partition collections by schema presence (a first emit reads `schemaless`
   //    — collections with no data schema, delivered statically via the ball).
   let probe
@@ -456,7 +478,7 @@ export async function publish(args = []) {
   // A product decision the author is usually making unknowingly — say it at warn
   // level, not dim among everything else. See the helper for what the old
   // message got wrong.
-  reportSchemalessCollections(probe.schemaless, say)
+  reportSchemalessQueries(probe.schemaless, say)
   const localAssets = probe.localAssets || []
 
   // 3a. A clone with no `$uuid` is bound to no backend site, so every cached map
@@ -579,7 +601,7 @@ export async function publish(args = []) {
   //     `client.discover()` is the mechanism if that changes — `DISCOVERY_DEFAULTS`
   //     makes an absent key non-breaking by construction.
   if (ball) {
-    say.info('Uploading collection data…')
+    say.info('Uploading schema-less record data…')
     try {
       const r = await uploadSiteData({
         apiBase: client.origin,
@@ -595,9 +617,9 @@ export async function publish(args = []) {
         for (const f of r.failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
         return { exitCode: 1 }
       }
-      say.dim(`Collection data : ${r.uploaded.length} file(s) [${r.mode}]`)
+      say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
     } catch (err) {
-      say.err(`Collection data upload failed: ${err.message}`)
+      say.err(`Record data upload failed: ${err.message}`)
       return { exitCode: 1 }
     }
   }

package/src/commands/pull.js

@@ -10,7 +10,7 @@
  *
  *   - content lane → `siteContentDocumentToProject` (site.yml/theme.yml/head.html,
  *     pages/**, layout/**), and
- *   - folder lane  → `collectionsToProject` (the folder + record files).
+ *   - folder lane  → `recordsToProject` (the folder + record files).
  *
  * Pull is a CHECKOUT, not a merge — the "git-pull-like" it used to claim here was
  * misleading. It reconciles the working tree to the backend: section bodies are
@@ -36,7 +36,7 @@
  *
  * Usage:
  *   uniweb pull                          GET both lanes, project to files, prune orphans
- *   uniweb pull --no-collections         Pull pages only; skip the folder (collections) lane
+ *   uniweb pull --no-records         Pull pages only; skip the folder (records) lane
  *   uniweb pull --no-delete              Project, but keep files with no backend item
  *   uniweb pull --merge                  Three-way merge local changes with the backend's
  *   uniweb pull --force                  Pull over uncommitted local changes (discards them)
@@ -52,7 +52,7 @@
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
  * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
  * `entities/<uuid>.json`); `readPullDocuments` reads the entity files out of it, with
- * a tolerant JSON fallback (`extractDocument` / `splitCollectionsPull`). Verified live
+ * a tolerant JSON fallback (`extractDocument` / `splitRecordsPull`). Verified live
  * against the playground backend, 2026-06-17.
  */
 
@@ -71,12 +71,11 @@ import yaml from 'js-yaml'
 import { downloadMissingAssets } from '../backend/asset-download.js'
 import {
   siteContentDocumentToProject,
-  collectionsToProject,
-  resolveCollectionsConfig,
+  recordsToProject,
   readZip,
   computeUnitHashes,
   collectUnitUuids,
-  collectCollectionUuids
+  collectQueryUuids
 } from '@uniweb/build/uwx'
 import {
   readWritten,
@@ -86,7 +85,7 @@ import {
 import {
   makeModelResolver,
   rebankSyncHashes,
-  writeCollectionUuids,
+  writeQueryUuids,
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,
@@ -203,7 +202,7 @@ export function extractDocument(payload) {
 // Split a collections pull (the folder + the entities it references) into the
 // folder document and the record documents. Tolerant of an array, an
 // `{ entities }` / `{ documents }` list, or an explicit `{ folder, records }`.
-export function splitCollectionsPull(payload) {
+export function splitRecordsPull(payload) {
   if (payload?.folder)
     return { folderDoc: payload.folder, recordDocs: payload.records || [] }
   const list = Array.isArray(payload)
@@ -240,7 +239,7 @@ export function readPullDocuments(buf) {
     }
     return docs
   }
-  // JSON fallback — flatten any envelope splitCollectionsPull understands into a
+  // JSON fallback — flatten any envelope splitRecordsPull understands into a
   // flat `$`-document list (a raw doc, a list, `{entities}`/`{documents}`, or
   // `{folder, records}`).
   let payload
@@ -519,8 +518,8 @@ export async function pull(args = [], deps = {}) {
   const dryRun = args.includes('--dry-run')
   const tokenFlag = flagValue(args, '--token')
   const prune = !(args.includes('--no-delete') || args.includes('--no-prune')) // git-like by default
-  const noCollections =
-    args.includes('--no-collections') || args.includes('--content-only')
+  const noRecords =
+    args.includes('--no-records') || args.includes('--content-only')
   const force = args.includes('--force')
   const mergeMode = args.includes('--merge')
 
@@ -598,7 +597,7 @@ export async function pull(args = [], deps = {}) {
     info(
       `Dry run — would pull content from ${colors.dim}${client.origin}${colors.reset}`
     )
-    if (!noCollections) info(`Dry run — would also pull collections`)
+    if (!noRecords) info(`Dry run — would also pull records`)
     return { exitCode: 0 }
   }
 
@@ -691,8 +690,8 @@ export async function pull(args = [], deps = {}) {
       writeItemUuids(siteDir, collectUnitUuids(siteDoc))
       // The collections section's identity has no file to live in either — same
       // reason, same remedy, keyed by name. A pull is the other route by which a
-      // copy can recover it (see readCollectionUuids).
-      writeCollectionUuids(siteDir, collectCollectionUuids(siteDoc))
+      // copy can recover it (see readQueryUuids).
+      writeQueryUuids(siteDir, collectQueryUuids(siteDoc))
       // Bring the media down BEFORE projecting: a newly-landed asset gains a map
       // entry, and the projection reads that map to put authored paths back. Run
       // after, and this pull's new assets would project as URLs and only restore
@@ -777,13 +776,13 @@ export async function pull(args = [], deps = {}) {
   // Lane 2 — folder → the folder + record files, keyed by the SAME site-content uuid
   // (the backend resolves the site's `@uniweb/folder` from it; the framework never
   // holds a folder uuid). Models are resolved by name (async) up front, so
-  // collectionsToProject keeps its synchronous contract. A 304 leaves files as-is.
-  if (!noCollections) {
-    const folder = await getDocs('collections', () =>
+  // recordsToProject keeps its synchronous contract. A 304 leaves files as-is.
+  if (!noRecords) {
+    const folder = await getDocs('records', () =>
       client.pullFolder(siteContentUuid, { etag: etagFolder })
     )
     if (folder && !folder.notModified && folder.docs?.length) {
-      const { folderDoc, recordDocs } = splitCollectionsPull(folder.docs)
+      const { folderDoc, recordDocs } = splitRecordsPull(folder.docs)
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
       for (const model of [
@@ -795,18 +794,20 @@ export async function pull(args = [], deps = {}) {
           note(`! could not resolve model ${model}: ${err.message}`)
         }
       }
-      const collectionsConfig = await resolveCollectionsConfig(siteDir).catch(
-        () => null
-      )
-      const report = collectionsToProject({
+      // ⛔ NO QUERY CONFIG. A record's home is decided by what it IS — its
+      // `$model` names the pool folder — not by any query that happens to select
+      // it. `recordsToProject` reads `site.yml::$org` itself, so a `@/x`
+      // model the producer resolved to `@org/x` is placed back where the author
+      // wrote it.
+      const report = recordsToProject({
         folderDoc,
         recordDocs,
         siteRoot: siteDir,
         opts: {
-          resolveDeclaration: (name) => declByModel.get(name) || null,
-          collectionsConfig
+          resolveDeclaration: (name) => declByModel.get(name) || null
         }
       })
+      if (report.records === 'updated') info('Wrote records.yml')
       records += report.placed.length + report.updated.length
       for (const s of report.skipped)
         note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
@@ -840,7 +841,7 @@ export async function pull(args = [], deps = {}) {
     siteDir,
     [
       ...wrote,
-      ...['site.yml', 'theme.yml', 'head.html', 'collections.yml'].map((f) =>
+      ...['site.yml', 'theme.yml', 'head.html', 'queries.yml', 'records.yml'].map((f) =>
         join(siteDir, f)
       )
     ],

package/src/commands/push.js

@@ -69,7 +69,7 @@ import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
-import { reportSchemalessCollections } from '../utils/schemaless-report.js'
+import { reportSchemalessQueries } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
@@ -77,6 +77,7 @@ import {
   readSiteIdentity
 } from '../utils/site-identity.js'
 import { confirm } from '../utils/interactive.js'
+import { guardEmptyRecords } from '../utils/records-guard.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
   makeModelResolver,
@@ -85,7 +86,7 @@ import {
   readItemBaseVersions,
   readItemUuids,
   readFolderItemUuids,
-  readCollectionUuids,
+  readQueryUuids,
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
@@ -369,6 +370,15 @@ export async function push(args = [], deps = {}) {
   // It also has to be this emit that carries `assetRewrite` below: the push cache
   // stores hashes of the REWRITTEN content, so the emit compared against it must
   // rewrite too, or every entity reads as changed forever.
+  // ⛔ AN EMPTY `records.yml` REMOVES. It is the one path where an ordinary act is
+  // destructive — a placeholder file, created meaning to fill it in — so the count
+  // is reported and confirmed before anything is sent. The format stays honest;
+  // the asking happens here.
+  if (!dryRun) {
+    const guard = await guardEmptyRecords({ siteDir, args, warn, note })
+    if (!guard.ok) return { exitCode: 1 }
+  }
+
   let assetRewrite = null
   let assetIds = null
   if (!output && !dryRun) {
@@ -475,9 +485,9 @@ export async function push(args = [], deps = {}) {
     pkg = await emitSyncPackages(siteDir, {
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir),
-      // Identity for the `collections` section — see readCollectionUuids. Keyed by
+      // Identity for the `queries` section — see readQueryUuids. Keyed by
       // name, because a declaration has no file for a path-keyed map to hold.
-      collectionUuids: readCollectionUuids(siteDir),
+      queryUuids: readQueryUuids(siteDir),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
@@ -509,14 +519,14 @@ export async function push(args = [], deps = {}) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
   }
-  const { siteContent, collections, siteContentUuid, warnings, skipped } = pkg
+  const { siteContent, records, siteContentUuid, warnings, skipped } = pkg
   log('')
   for (const w of warnings) note(`! ${w}`)
   // Warn level, not dim: this is the author choosing entities vs static files.
-  reportSchemalessCollections(pkg.schemaless, { warn, dim: note })
+  reportSchemalessQueries(pkg.schemaless, { warn, dim: note })
 
   const totalEntities =
-    (siteContent?.entityCount || 0) + (collections?.entityCount || 0)
+    (siteContent?.entityCount || 0) + (records?.entityCount || 0)
 
   // Nothing changed since the last push — the backend is already up to date.
   if (totalEntities === 0) {
@@ -529,10 +539,10 @@ export async function push(args = [], deps = {}) {
     info(
       `${colors.bright}site-content${colors.reset} → ${siteContent.models.join(', ')}`
     )
-  if (collections) {
-    const n = collections.entityCount
+  if (records) {
+    const n = records.entityCount
     info(
-      `${colors.bright}collections${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${collections.models.join(', ')}`
+      `${colors.bright}records${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${records.models.join(', ')}`
     )
   }
   if (skipped) note(`${skipped} unchanged, skipped`)
@@ -542,11 +552,11 @@ export async function push(args = [], deps = {}) {
     const base = output.replace(/\.uwx$/, '')
     if (siteContent)
       writeFileSync(resolve(`${base}.site-content.uwx`), siteContent.buffer)
-    if (collections)
-      writeFileSync(resolve(`${base}.collections.uwx`), collections.buffer)
+    if (records)
+      writeFileSync(resolve(`${base}.records.uwx`), records.buffer)
     const lanes = [
       siteContent && 'site-content',
-      collections && 'collections'
+      records && 'records'
     ].filter(Boolean)
     success(`Wrote ${lanes.join(' + ')} .uwx — not submitted`)
     return { exitCode: 0 }
@@ -558,7 +568,7 @@ export async function push(args = [], deps = {}) {
         `Dry run — would ${verb} content at ${colors.dim}${client.origin}${colors.reset}`
       )
     }
-    if (collections) {
+    if (records) {
       info(
         `Dry run — would push the folder at ${colors.dim}${client.origin}${colors.reset}`
       )

package/src/commands/validate.js

@@ -269,7 +269,7 @@ export async function validate(args = []) {
     return { exitCode: 0 }
   }
 
-  // The data pipeline (collectSiteContent / processCollections) prints progress
+  // The data pipeline (collectSiteContent / processQueries) prints progress
   // via console.log. Route that to stderr while the engine runs so stdout stays
   // clean — pure JSON for `--json`, just the report otherwise. `log` captured
   // the original stdout writer at module load, so our own output is unaffected.

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-28T23:49:23.885Z",
+  "generatedAt": "2026-08-29T19:59:22.061Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.29.1",
+      "version": "0.30.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -27,7 +27,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.13.1",
+      "version": "0.14.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -40,14 +40,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.4",
+      "version": "0.4.5",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.14.0",
+      "version": "0.15.0",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -66,7 +66,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.5.1",
+      "version": "0.5.2",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -74,7 +74,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.13.1",
+      "version": "0.13.2",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",

package/src/utils/flag-guard.js

@@ -77,12 +77,12 @@ const VERBS = {
   pull: [
     '--backend', '--content-only', '--dry-run', '--force', '--merge',
     '--no-assets',
-    '--no-collections', '--no-delete', '--no-prune', '--registry', '--token',
+    '--no-records', '--no-delete', '--no-prune', '--registry', '--token',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
     '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
-    '--backend', '--content-only', '--no-assets', '--no-collections', '--path',
+    '--backend', '--content-only', '--no-assets', '--no-records', '--path',
     '--project', '--registry', '--token', '--org', '--as-org'
   ],
   register: [

package/src/utils/git.js

@@ -32,11 +32,17 @@ import yaml from 'js-yaml'
  * rather than assuming the defaults.
  */
 export function siteContentRoots(siteDir) {
+  // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
+  // Its predecessor lived at `collections/collections.yml`, so the `collections`
+  // root added below already covered it and the bare `'collections.yml'` entry
+  // that used to sit in this list resolved to a path no site ever had. A
+  // root-level file has no directory entry standing in for it.
   const roots = new Set([
     'site.yml',
     'theme.yml',
     'head.html',
-    'collections.yml',
+    'queries.yml',
+    'records.yml',
     'locales'
   ])
   let paths = {}
@@ -48,7 +54,7 @@ export function siteContentRoots(siteDir) {
   }
   roots.add(paths.pages || 'pages')
   roots.add(paths.layout || 'layout')
-  roots.add(paths.collections || 'collections')
+  roots.add(paths.entities || 'entities')
   return [...roots]
 }