@uniweb/build 0.56.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/projections": "^0.7.3",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/projections": "^0.7.3",
     "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.3",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.2"
+    "@uniweb/runtime": "^0.27.4"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.2",
-    "@uniweb/core": "^0.29.6"
+    "@uniweb/core": "^0.29.8",
+    "@uniweb/runtime": "^0.27.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -21,6 +21,9 @@ export {
   writeQueryFiles,
   getQueryLastModified,
 } from '../site/query-processor.js'
+// Where a site's records live — `paths.records`, else `records/` — so a caller
+// holding its own config (a document's, not a `site.yml`) asks the one resolver.
+export { resolveRecordsDir } from '../site/entity-pool.js'
 export {
   parseFetchConfig,
   executeFetch,

package/src/foundation-name.js

@@ -0,0 +1,63 @@
+// A foundation's NAME — what it registers as (`@<org>/<name>`) and what a site pins
+// (`@<org>/<name>@<version>`). A registry keys foundations by it: (name, version) is
+// unique on a backend, and the uuid a backend mints for one never leaves that backend,
+// so the name is the identity that travels.
+//
+// ⭐ ONE RULE, and every reader asks it: the build (`schema.json`'s `_self.name`),
+// `uniweb register`, and `push` / `publish` looking a local foundation up in a
+// catalog. **`main.js`'s `name`, else `package.json`'s `name`.**
+//
+// ⛔ `package.json::name` IS WORKSPACE PLUMBING FIRST. pnpm needs it unique in the
+// workspace, and a site depends on it by that name (`"src": "file:../src"`,
+// `site.yml::foundation: src`). The scaffold names it `src` for exactly that reason,
+// which is why it is only the fallback here — and why `src` and `foundation` are
+// refused as a foundation's name: they name the folder, not the foundation, and every
+// project in an org would register the same one.
+//
+// ⛔ `package.json::uniweb.id` WAS A REGISTRY-NAME OVERRIDE, 2026-07-17 → 2026-09-21.
+// It is retired: the name lives in `main.js`, and two homes for one fact is how `push`
+// and `register` came to look the same foundation up under different names.
+
+/** Names that say where the code lives, not what the foundation is. */
+export const FORBIDDEN_FOUNDATION_NAMES = new Set(['src', 'foundation'])
+
+// One segment of a name: lowercase letters, digits and inner hyphens.
+const SEGMENT = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+
+/**
+ * The foundation's name, by the one rule: `main.js`'s `name`, else `package.json`'s.
+ *
+ * @param {{ config?: object, pkg?: object }} sources - `main.js`'s default export
+ *   and the parsed `package.json`
+ * @returns {{ name: string|null, source: 'main.js'|'package.json'|null }}
+ */
+export function foundationNameOf({ config, pkg } = {}) {
+  const fromConfig = typeof config?.name === 'string' ? config.name.trim() : ''
+  if (fromConfig) return { name: fromConfig, source: 'main.js' }
+  const fromPkg = typeof pkg?.name === 'string' ? pkg.name.trim() : ''
+  if (fromPkg) return { name: fromPkg, source: 'package.json' }
+  return { name: null, source: null }
+}
+
+/**
+ * Is this a name a foundation can register under? `marketing`, or `@acme/marketing`
+ * when the name carries its own scope.
+ *
+ * @param {unknown} name
+ * @returns {string|null} why it cannot, or null when it can
+ */
+export function checkFoundationName(name) {
+  if (typeof name !== 'string' || !name.trim()) return 'the foundation has no name'
+  const scoped = /^@([^/]+)\/([^/]+)$/.exec(name)
+  if (!scoped && name.includes('/')) {
+    return `"${name}" is not a foundation name — it is a name, or @org/name`
+  }
+  const [scope, bare] = scoped ? [scoped[1], scoped[2]] : [null, name]
+  if (FORBIDDEN_FOUNDATION_NAMES.has(bare)) {
+    return `"${bare}" names the folder, not the foundation — and every project in an org would register the same one`
+  }
+  if (!SEGMENT.test(bare) || (scope !== null && !SEGMENT.test(scope))) {
+    return `"${name}" is not a foundation name — use lowercase letters, digits and hyphens (like "marketing")`
+  }
+  return null
+}

package/src/i18n/data-strings.js

@@ -31,7 +31,7 @@ export const HEURISTIC_SKIP_FIELDS = new Set([
   'pmid', 'bibtex', 'pdf', 'code', 'data', 'slides', 'video',
   'repository', 'caseStudy', 'website', 'avatar', 'image',
   'thumbnail', 'currency', 'order', 'hidden', 'current',
-  'featured', 'published', 'allDay', 'remote', 'hybrid',
+  'featured', 'published', 'draft', 'allDay', 'remote', 'hybrid',
   'noindex', 'corresponding', 'required', 'virtual',
   'lastModified', 'date', 'updated', 'posted', 'submitted',
   'accepted', 'startDate', 'endDate', 'deadline',

package/src/i18n/freeform.js

@@ -10,7 +10,7 @@
  *   locales/freeform/{locale}/
  *     pages/{pageRoute}/{stableId}.md      - By route
  *     page-ids/{pageId}/{stableId}.md      - By page ID (stable)
- *     entities/{schema dirs}/{slug}.md     - Records
+ *     records/{schema dirs}/{slug}.md      - Records
  *
  * Resolution order for sections:
  *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
@@ -22,7 +22,7 @@ import { readFile, readdir, stat } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join, relative, dirname, sep } from 'node:path'
 import yaml from 'js-yaml'
-import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, RECORDS_DIR } from '../site/entity-pool.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { computeSourceHash } from './freeform-manifest.js'
 
@@ -101,13 +101,13 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
 }
 
 /**
- * Load a free-form translation for one ENTITY.
+ * Load a free-form translation for one RECORD.
  *
- * Path: entities/{schema dirs}/{slug}.md — mirroring the pool exactly.
+ * Path: records/{schema dirs}/{slug}.md — mirroring the records directory exactly.
  *
- * ⛔ KEYED BY THE ENTITY, NOT BY A QUERY. It used to be
+ * ⛔ KEYED BY THE RECORD, NOT BY A QUERY. It used to be
  * `collections/{queryName}/{slug}.md`, which was fine only while a
- * collection was also a directory of files. With `entities/{schema}/` as the pool,
+ * collection was also a directory of files. With `records/{schema}/` holding records,
  * TWO queries can cover one schema — so a query-keyed path would make an author
  * write the same translation once per query, and finding neither from the other.
  * ⚠️ And a query is renameable where a record's model is not: keying on the query
@@ -185,7 +185,7 @@ async function discoverMarkdownFiles(dir, baseDir) {
  * register a translation that has no manifest entry yet.
  *
  * ⭐ Each path is relative to the locale's free-form directory — `pages/about/story.md`,
- * `page-ids/<id>/intro.md`, `entities/article/hello.md` — the form the manifest keys a
+ * `page-ids/<id>/intro.md`, `records/article/hello.md` — the form the manifest keys a
  * translation by and `freeformPathsFor` derives. ⛔ Until 2026-09-14 each was relative
  * to its own subdirectory (`about/story.md`), so none matched a manifest key: the build
  * registered no new file, and a status counted every stale or orphaned file as up to date.
@@ -217,10 +217,10 @@ export async function discoverFreeformTranslations(locale, localesDir) {
     result.pageIds = (await discoverMarkdownFiles(pageIdsDir, freeformDir)).sort()
   }
 
-  // Discover entity translations
-  const entitiesDir = join(freeformDir, ENTITIES_DIR)
-  if (existsSync(entitiesDir)) {
-    result.records = (await discoverMarkdownFiles(entitiesDir, freeformDir)).sort()
+  // Discover record translations
+  const recordsDir = join(freeformDir, RECORDS_DIR)
+  if (existsSync(recordsDir)) {
+    result.records = (await discoverMarkdownFiles(recordsDir, freeformDir)).sort()
   }
 
   return result
@@ -246,7 +246,7 @@ export async function getFreeformFileMeta(filePath) {
  * Parse a free-form translation file path to extract metadata
  *
  * @param {string} relativePath - Path relative to locale's freeform dir
- * @returns {Object} { type, pageRoute?, pageId?, queryName?, stableId, slug? }
+ * @returns {Object} { type, pageRoute?, pageId?, schema?, stableId, slug? }
  */
 export function parseFreeformPath(relativePath) {
   const parts = relativePath.split('/')
@@ -266,11 +266,12 @@ export function parseFreeformPath(relativePath) {
     return { type: 'pageId', pageId, stableId }
   }
 
-  if (parts[0] === ENTITIES_DIR) {
-    // collections/articles/getting-started.md → { type: 'collection', queryName: 'articles', slug: 'getting-started' }
+  if (parts[0] === RECORDS_DIR) {
+    // records/std/person/ada.md → { type: 'record', schema: '@std/person', slug: 'ada' }
+    // ⛔ This returned `queryName: parts[1]` until 2026-09-21 — the first schema
+    // segment (`std` above), and never a query's name. Nothing read it.
     const slug = parts[parts.length - 1].replace('.md', '')
-    const queryName = parts[1]
-    return { type: 'record', queryName, slug }
+    return { type: 'record', schema: schemaForPoolDirs(parts.slice(1, -1)), slug }
   }
 
   return { type: 'unknown', relativePath }
@@ -343,7 +344,7 @@ function freeformSections(siteContent) {
  *   - `canJudge(path)` — whether this content can say a translation at `path` is
  *     orphaned. ⛔ Only a page section's (`pages/…`, `page-ids/…`), and not one for a page
  *     whose sections the content does not carry — a prerendered site with split content
- *     rewrites `site-content.json` without them. A record's (`entities/…`) is read from
+ *     rewrites `site-content.json` without them. A record's (`records/…`) is read from
  *     records this content does not hold. A check that cannot see the source must never
  *     call its translation orphaned: `prune --freeform` deletes what it is told is.
  *
@@ -413,10 +414,10 @@ export function buildFreeformPath(section, page, preferPageId = true) {
  *
  * @param {string} schema - the entity's model ref (`@/name` or `@org/name`)
  * @param {string} slug - the entity's slug
- * @returns {string|null} e.g. `entities/article/getting-started.md`, or null for a
+ * @returns {string|null} e.g. `records/article/getting-started.md`, or null for a
  *   ref this layout cannot express
  */
 export function buildFreeformRecordPath(schema, slug) {
   const dirs = poolDirsForSchema(schema)
-  return dirs ? `${ENTITIES_DIR}/${dirs.join('/')}/${slug}.md` : null
+  return dirs ? `${RECORDS_DIR}/${dirs.join('/')}/${slug}.md` : null
 }

package/src/i18n/index.js

@@ -21,7 +21,7 @@ import {
   buildLocalizedRecords,
   getRecordLocales,
   translateRecordData,
-  RECORDS_DIR
+  RECORD_LOCALES_DIR
 } from './records.js'
 import { resolveDefaultLocale } from '@uniweb/core'
 import { generateSearchIndex } from '@uniweb/projections'
@@ -75,7 +75,7 @@ export {
   buildLocalizedRecords,
   getRecordLocales,
   translateRecordData,
-  RECORDS_DIR,
+  RECORD_LOCALES_DIR,
 
   // Locale resolution
   getAvailableLocales,
@@ -234,7 +234,7 @@ export async function extractRecordManifest(siteRoot, options = {}) {
   const manifest = await extractRecordContent(siteRoot)
 
   // Ensure collections locales directory exists
-  const recordLocalesDir = join(siteRoot, localesDir, RECORDS_DIR)
+  const recordLocalesDir = join(siteRoot, localesDir, RECORD_LOCALES_DIR)
   if (!existsSync(recordLocalesDir)) {
     await mkdir(recordLocalesDir, { recursive: true })
   }
@@ -517,7 +517,7 @@ async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
     }
 
     // Check for orphaned translations — only those this content can judge: never a
-    // record's (`entities/…`), which is read from records the site content does not hold.
+    // record's (`records/…`), which is read from records the site content does not hold.
     const orphaned = await getOrphanedTranslations(freeformDir, validPaths)
     for (const item of orphaned) {
       if (!canJudge(item.path)) continue

package/src/i18n/records.js

@@ -23,7 +23,7 @@ import { loadFreeformRecord } from './freeform.js'
 // is not, wherever the value came from. Moved rather than copied: two tuned
 // denylists would drift, and drift here is silent.
 import { resolveQueriesConfig } from '../site/queries-config.js'
-import { poolDirsForSchema, schemaForPoolDirs, ENTITIES_DIR } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import {
   NON_TRANSLATABLE_TYPES,
   HEURISTIC_SKIP_FIELDS,
@@ -37,7 +37,11 @@ import {
 // contexts were keyed by the QUERY, so two queries over one schema produced two
 // entries for one record, each invisible from the other, and a renamed query
 // orphaned every translation under it.
-export const RECORDS_DIR = 'records'
+//
+// ⚠️ `RECORD_LOCALES_DIR`, and not `RECORDS_DIR`, since 2026-09-21: that name is the
+// site's own `records/` directory now (`site/entity-pool.js`), and this one is
+// `locales/records/` — two directories, one word, so the constant says which.
+export const RECORD_LOCALES_DIR = 'records'
 
 // ---------------------------------------------------------------------------
 // Schema resolution
@@ -72,7 +76,7 @@ async function resolveSchema(queryName, siteRoot) {
   // an author to write into it was the one remaining place the framework
   // contradicted its own rule that `collections/` is the only way to provide
   // structured data. The schema describes the source, so it lives with it.
-  const companionPath = join(siteRoot, ENTITIES_DIR, `${queryName}.schema.js`)
+  const companionPath = join(resolveRecordsDir(siteRoot).abs, `${queryName}.schema.js`)
   if (existsSync(companionPath)) {
     try {
       const mod = await import(pathToFileURL(companionPath).href)
@@ -154,7 +158,7 @@ function isFieldTranslatable(fieldDef) {
  * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
  * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
  * parametric page's URL names; `$uuid`), and a record's top-level `slug` and `path`
- * are its handle and its placement in `records.yml`. Until 2026-09-14 they became
+ * are its handle and its placement in `folder.yml`. Until 2026-09-14 they became
  * translation units, and a translation whose source happened to equal one rewrote it,
  * so a record's page stopped matching its URL.
  *
@@ -657,7 +661,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
   const {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
-    recordLocalesDir = join(siteRoot, 'locales', RECORDS_DIR),
+    recordLocalesDir = join(siteRoot, 'locales', RECORD_LOCALES_DIR),
     localesDir = join(siteRoot, 'locales'),
     freeformEnabled = true
   } = options
@@ -987,7 +991,7 @@ export async function translateRecordData(items, queryName, siteRoot, options =
  * @returns {Promise<string[]>} Array of locale codes
  */
 export async function getRecordLocales(localesPath) {
-  const recordLocalesDir = join(localesPath, RECORDS_DIR)
+  const recordLocalesDir = join(localesPath, RECORD_LOCALES_DIR)
   if (!existsSync(recordLocalesDir)) return []
 
   try {

package/src/index.js

@@ -11,8 +11,16 @@ export {
   discoverComponents,
   buildSchema,
   getExposedComponents,
+  readFoundationName,
 } from './schema.js'
 
+// A foundation's name — the one rule the build, `register` and `push` share
+export {
+  foundationNameOf,
+  checkFoundationName,
+  FORBIDDEN_FOUNDATION_NAMES,
+} from './foundation-name.js'
+
 // Data-conformance checking (your content vs the schemas your foundation declares)
 export {
   validateItem,

package/src/prerender.js

@@ -407,7 +407,7 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
       for (const paramValue of values) {
 
         // Create concrete route: /blog/:slug → /blog/my-post. Under `[...path]` the
-        // record's URL is its placement (the folder `records.yml` put it in, carried
+        // record's URL is its placement (the folder `folder.yml` put it in, carried
         // as `path`) plus its handle — the split rule in reverse. ⛔ A FILE PATH, so
         // decoded: the server decodes the request before looking the file up.
         const capture = catchAll ? joinPathCapture({ dir: item.path, slug: paramValue }) : null

package/src/schema.js

@@ -23,6 +23,8 @@ import {
   deriveRecordsSupport,
   unnameableIn,
 } from './foundation/derive-supports.js'
+import { foundationNameOf } from './foundation-name.js'
+import { resolveFoundationSrcDir } from './utils/foundation-source-root.js'
 
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
@@ -176,13 +178,21 @@ export async function loadPackageJson(srcDir) {
     const content = await readFile(packagePath, 'utf-8')
     const pkg = JSON.parse(content)
 
-    // Extract only identity fields for schema.
-    // `uniweb.id` is the REGISTERED name (registry identity), decoupled from the
-    // workspace package `name` (pnpm linking / file: deps / site.yml). It lets a
-    // foundation keep a scaffold-default package name like "src" while registering
-    // under a distinct id (e.g. "docs" → @org/docs). Falls back to `name`.
+    // Extract only identity fields for schema. `name` here is the package's — the
+    // FALLBACK for the foundation's name, which `main.js` supplies first
+    // (`foundation-name.js`, applied in `buildSchema`).
+    //
+    // ⛔ `uniweb.id` is no longer read (retired 2026-09-21): it was a registry-name
+    // override, and the name lives in `main.js` now. Said here rather than refused —
+    // a build does not register, and `uniweb register` refuses it by name.
+    if (pkg.uniweb?.id !== undefined) {
+      console.warn(
+        `[uniweb] ${packagePath}: \`uniweb.id\` is no longer read — a foundation's name is ` +
+          `\`name\` in main.js's default export (name: '${pkg.uniweb.id}').`
+      )
+    }
     return {
-      name: pkg.uniweb?.id || pkg.name,
+      name: pkg.name,
       version: pkg.version,
       description: pkg.description,
       // `uniweb.supports` joins them because it is the same KIND of fact: static,
@@ -197,6 +207,43 @@ export async function loadPackageJson(srcDir) {
   }
 }
 
+/**
+ * A local foundation's name, read from its source by the one rule
+ * (`foundation-name.js`) — for `uniweb register` and for `push` / `publish` looking
+ * the foundation up, which need it before a build, or without one.
+ *
+ * ⛔ Refuses `package.json::uniweb.id` (retired 2026-09-21). This is the reader
+ * whose answer registers, so a leftover stops here rather than registering the
+ * foundation under a different name than the one it was given.
+ *
+ * @param {string} foundationDir - the foundation package's root
+ * @returns {Promise<{ name: string|null, source: 'main.js'|'package.json'|null, mainFile: string }>}
+ *   `mainFile` is the foundation's `main.js`, whether or not it exists yet
+ */
+export async function readFoundationName(foundationDir) {
+  const pkgPath = join(foundationDir, 'package.json')
+  let pkg = {}
+  if (existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(await readFile(pkgPath, 'utf-8')) || {}
+    } catch {
+      pkg = {}
+    }
+  }
+  if (pkg.uniweb?.id !== undefined) {
+    throw new Error(
+      `${pkgPath}: \`uniweb.id\` is no longer read — a foundation's name is \`name\` in ` +
+        `main.js's default export. Move it there (name: '${pkg.uniweb.id}') and remove uniweb.id.`
+    )
+  }
+  const srcDir = join(foundationDir, resolveFoundationSrcDir(foundationDir))
+  const config = await loadFoundationConfig(srcDir)
+  return {
+    ...foundationNameOf({ config, pkg }),
+    mainFile: join(srcDir, FOUNDATION_FILE_NAMES[0]),
+  }
+}
+
 /**
  * Load the foundation's declarations from `src/main.js`.
  *
@@ -310,7 +357,12 @@ function warnMisplacedCapabilities(module, filePath) {
  * still resolve from the project's own `node_modules`.
  */
 async function importFoundationConfig(filePath) {
-  const href = pathToFileURL(filePath).href
+  // ⭐ IMPORTED BY CONTENT, as `loadMetaFile` imports `meta.js`: Node caches a module
+  // by URL, so a second read in one process returned the FIRST content. That matters
+  // since 2026-09-21, when `register` can write a `name` into this file and `push`
+  // reads the name again after the release, in the same process that read it before.
+  const content = createHash('sha1').update(await readFile(filePath)).digest('hex').slice(0, 16)
+  const href = `${pathToFileURL(filePath).href}?content=${content}`
   try {
     return await import(href)
   } catch (error) {
@@ -333,7 +385,7 @@ async function importFoundationConfig(filePath) {
         external: ['react', 'react/*', 'react-dom', 'react-dom/*'],
         logLevel: 'silent',
       })
-      return await import(pathToFileURL(outfile).href)
+      return await import(`${pathToFileURL(outfile).href}?content=${content}`)
     } finally {
       await rm(outfile, { force: true }).catch(() => {})
     }
@@ -932,13 +984,18 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
   const supports = composeSupports(identity.supports, derived)
   reportSupports(srcDir, identity.supports, derived, supports.supports)
 
+  // The foundation's name, by the one rule every reader shares (`foundation-name.js`):
+  // `main.js`'s `name`, else `package.json`'s. ⚠️ Until 2026-09-21 the `main.js` value
+  // was described here as "editor-facing identity", as if a display name — but it is
+  // the name that registers, and the only name the framework sends.
+  const { name } = foundationNameOf({ config: foundationConfig, pkg: identity })
+
   return {
     _self: {
       ...configWithoutExtension,
       ...identity,
       ...supports,
-      // foundation.js overrides package.json for editor-facing identity
-      ...(foundationConfig.name && { name: foundationConfig.name }),
+      ...(name && { name }),
       ...(foundationConfig.description && { description: foundationConfig.description }),
       ...(foundationConfig.defaultLayout && { defaultLayout: foundationConfig.defaultLayout }),
       ...(isExtension && { role: 'extension' }),

package/src/site/build-site-data.js

@@ -24,6 +24,7 @@ import { join, resolve, dirname } from 'node:path'
 import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
+import { resolveRecordsDir } from './entity-pool.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import {
@@ -61,7 +62,7 @@ import {
  *     re-derive, so we always ship enough for the ones that do.
  *   - `data/<collection>.json` (+ per-record files for `deferred:`
  *     collections) — same shape `processQueries` produces today.
- *   - `records/<path under entities/>` — the records' co-located assets, where
+ *   - `records/<path under the records directory>` — the records' co-located assets, where
  *     the compiled records point.
  *   - `assets/<media>` — processed images / video posters / PDF
  *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
@@ -143,7 +144,7 @@ export async function buildSiteData({
     const byQuery = await processQueries(
       resolvedSiteRoot,
       siteContent.config.queries,
-      siteContent.config?.paths?.entities,
+      resolveRecordsDir(resolvedSiteRoot, siteContent.config?.paths).rel,
       basePath,
       { locale: resolveDefaultLocale(siteContent.config) ?? null }
     )
@@ -155,7 +156,7 @@ export async function buildSiteData({
       await cp(publicDataDir, distDataDir, { recursive: true })
     }
 
-    // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under entities/>`,
+    // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under records/>`,
     // where the compiled records point (`/records/…`), mirrored the way vite mirrors
     // all of `public/` on the bundle lane. ⛔ Until 2026-09-14 only `public/data` was
     // copied, so a record's image URL named a file this lane's `dist/` did not have.

package/src/site/config.js

@@ -484,7 +484,7 @@ export async function defineSiteConfig(options = {}) {
           const allowed = ['..']
           const parentDir = resolve(siteRoot, '..')
           const paths = siteConfig.paths || {}
-          for (const key of ['pages', 'layout', 'entities']) {
+          for (const key of ['pages', 'layout', 'records']) {
             if (paths[key]) {
               const resolved = resolve(siteRoot, paths[key])
               if (!resolved.startsWith(parentDir)) {

package/src/site/content-collector.js

@@ -822,7 +822,7 @@ function resolveDisplayTitle(declaredTitle, segment, sections) {
   return extractH1(sections[0]?.content) || prettifySlug(segment)
 }
 
-// ⭐ The rule now lives in `utils/numeric-prefix.js` — `records.yml` needs the
+// ⭐ The rule now lives in `utils/numeric-prefix.js` — `records/folder.yml` needs the
 // identical one, and a records reader cannot import this module without closing
 // a cycle. Imported at the top; still re-exported below for existing callers.
 
@@ -2727,9 +2727,10 @@ export async function collectSiteContent(sitePath, options = {}) {
   // The `query:` shorthand ships as `config.fetch`, desugared below; carried raw
   // it would sit beside `config.queries`, the declarations, and read as one.
   const { publishLanguages: _publishLanguages, query: _query, ...runtimeSiteConfig } = siteConfig
-  // ⛔ `$`-prefixed keys are the project's BACKEND-SCOPED state — `$uuid`, `$org`,
-  // `$backend`, `$services`, `$secrets` — and this payload is a PUBLISHED artifact
-  // that a visitor can fetch. They have no runtime reader (nothing in core, runtime
+  // ⛔ `$`-prefixed keys were the project's BACKEND-SCOPED state — `$uuid`, `$org`,
+  // `$backend`, `$services`, `$secrets` — until they moved to `sync.json`
+  // (2026-09-20), and a `site.yml` written before then can still carry them. This
+  // payload is a PUBLISHED artifact that a visitor can fetch. They have no runtime reader (nothing in core, runtime
   // or kit reads a `config.$*` key), so this removes noise for four of them and a
   // real disclosure for the fifth: `$secrets` carries no values, but its entries
   // name every secret the site has, and an inventory of credential names is not