@uniweb/build 0.57.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.57.0",
+  "version": "0.59.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/content-reader": "^1.2.5",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/schemas": "^0.3.4",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/projections": "^0.7.3"
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/projections": "^0.7.3",
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.3"
+    "@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/core": "^0.29.7",
-    "@uniweb/runtime": "^0.27.3"
+    "@uniweb/runtime": "^0.27.4",
+    "@uniweb/core": "^0.29.8"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation-name.js

@@ -0,0 +1,89 @@
+// 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.
+//
+// ⭐ THE SCOPE IS PART OF THE NAME (2026-09-22 [Diego]) — `@acme/marketing` — so the
+// org a foundation registers under lives where the rest of its name does. A bare name
+// has no scope yet; `uniweb register` gives it one and writes it into `main.js`.
+// ⛔ `package.json::uniweb.scope` held it until then, a second home for half of one
+// fact, and the halves disagreed: a foundation named `@acme/fnd` registered its data
+// schemas under whatever `uniweb.scope` said (measured: `@proximify/member`).
+
+/** 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
+}
+
+/**
+ * A foundation's name in its two halves: the scope it registers under, and the name
+ * within that scope. `@acme/marketing` → `{ scope: '@acme', bare: 'marketing' }`;
+ * `marketing` → `{ scope: null, bare: 'marketing' }` — a name that has not registered
+ * yet, since `register` writes the scope it chooses into the name.
+ *
+ * ⭐ The scope is what a foundation's own `@/x` data schemas resolve into — at
+ * register, and in a site's records and queries, which name those same Models.
+ *
+ * @param {unknown} name
+ * @returns {{ scope: string|null, bare: string|null }} `scope` as `@org`
+ */
+export function splitFoundationName(name) {
+  const text = typeof name === 'string' ? name.trim() : ''
+  if (!text) return { scope: null, bare: null }
+  const scoped = /^@([^/]+)\/([^/]+)$/.exec(text)
+  return scoped ? { scope: `@${scoped[1]}`, bare: scoped[2] } : { scope: null, bare: text }
+}

package/src/i18n/records.js

@@ -158,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.
  *

package/src/index.js

@@ -11,8 +11,17 @@ export {
   discoverComponents,
   buildSchema,
   getExposedComponents,
+  readFoundationName,
 } from './schema.js'
 
+// A foundation's name — the one rule the build, `register` and `push` share
+export {
+  foundationNameOf,
+  checkFoundationName,
+  splitFoundationName,
+  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/runtime-schema.js

@@ -194,8 +194,10 @@ function leanDataSchema(value, dataSchemaMap) {
   if (ref) {
     const resolved = dataSchemaMap[ref]
     // ⛔ `flatRecordFields`, NOT `resolved.fields`. `dataSchemaMap` holds each
-    // schema AS AUTHORED — resolution and lowering are different steps, and only
-    // the second normalizes the two authoring forms. `fields:` at the top is the
+    // schema NORMALIZED but still in the form it was authored in — `fields:` or
+    // `sections:` — because only lowering (`uwx/data-schema.js`) folds the two
+    // forms into one. (This said "AS AUTHORED" until 2026-09-22; aliases and
+    // `many:` are already folded here.) `fields:` at the top is the
     // SUGAR for a one-section model; a sections-form schema has no such key, so
     // reading it directly returned null for every `@std/*` binding and the
     // section's `data:` declaration supplied no field defaults at all. Silent:

package/src/schema.js

@@ -23,6 +23,8 @@ import {
   deriveRecordsSupport,
   unnameableIn,
 } from './foundation/derive-supports.js'
+import { foundationNameOf, splitFoundationName } 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,29 @@ 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}').`
+      )
+    }
+    // ⛔ `uniweb.scope` likewise (retired 2026-09-22) — the scope is part of the name.
+    // The build never read it; `uniweb register` refuses it, naming the line to write.
+    if (pkg.uniweb?.scope !== undefined) {
+      console.warn(
+        `[uniweb] ${packagePath}: \`uniweb.scope\` is no longer read — a foundation's scope is ` +
+          `part of its name in main.js's default export (name: '@<org>/<name>').`
+      )
+    }
     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 +215,63 @@ 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) and `uniweb.scope`
+ * (retired 2026-09-22 — the scope is part of the name). 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)
+  const read = foundationNameOf({ config, pkg })
+  // ⛔ `package.json::uniweb.scope` is retired (2026-09-22): a foundation's scope is
+  // part of its name. Refused here, the reader whose answer registers, because a
+  // leftover would register the name and the data schemas under two different orgs.
+  if (pkg.uniweb?.scope !== undefined) {
+    throw new Error(retiredScopeMessage(pkgPath, pkg.uniweb.scope, read.name))
+  }
+  return {
+    ...read,
+    mainFile: join(srcDir, FOUNDATION_FILE_NAMES[0]),
+  }
+}
+
+/**
+ * What to say about a leftover `package.json::uniweb.scope`: the `main.js` line that
+ * replaces it, or — when `main.js` already scopes the name — that it can go.
+ */
+function retiredScopeMessage(pkgPath, scope, name) {
+  const { scope: nameScope, bare } = splitFoundationName(name)
+  const intro = `${pkgPath}: \`uniweb.scope\` is no longer read — a foundation's scope is part of its name, \`name\` in main.js's default export.`
+  if (nameScope) return `${intro} main.js already names it '${name}', so remove uniweb.scope.`
+  const handle = String(scope ?? '').replace(/^@/, '').replace(/\/.*$/, '') || '<org>'
+  return `${intro} Move it there (name: '@${handle}/${bare || '<name>'}') and remove uniweb.scope.`
+}
+
 /**
  * Load the foundation's declarations from `src/main.js`.
  *
@@ -310,7 +385,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 +413,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 +1012,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/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.
 

package/src/site/entity-pool.js

@@ -4,10 +4,18 @@
 // [Diego]). The directory is the file side of the site's records folder: the
 // backend's folder holds references to entities, and putting a ref in it is what
 // makes one a record — putting a file in this directory is the same act. Nothing
-// else is needed, and nothing lists it. (`records.yml` only organizes records into
-// sub-folders; see `records-config.js`.) A file whose name starts with `_` or `.`
+// else is needed, and nothing lists it. A file whose name starts with `_` or `.`
 // is not read, so it is not a record.
 //
+// ⭐ ONE FILE AT THE TOP IS NOT A RECORD: `folder.yml`, the folder's organization —
+// which records sit in which sub-folder (`records-config.js`). The top of the
+// directory is the one place no record can be (a file there names no model), so the
+// name collides with nothing. It lives here because the directory IS the site's
+// folder on the file side: its organization moves with `paths.records` and travels
+// with a records directory that sites share, as a pages directory's own
+// `folder.yml` does. ⛔ It was `records.yml` at the site root until 2026-09-21
+// [Diego]; that file is refused by name (`refuseRetiredLayout`).
+//
 // ⛔ A RECORD IS NOT "PUBLISHED" BY BEING HERE. `push` sends the site's records to a
 // backend, and they are served once the SITE is published — publishing the site
 // publishes its folder and what is in it. Nothing about a single record decides that.
@@ -15,7 +23,7 @@
 // ⛔ THE PATH DECLARES THE MODEL, AND NOTHING ELSE. `collections/<name>/` used to
 // mean three things at once — these files are entities, their schema is
 // `@/<name>`, and they are grouped as `<name>` for placement. A schema folder here
-// declares only the model; grouping is `records.yml`'s.
+// declares only the model; grouping is `folder.yml`'s.
 //
 // ⇒ So nothing here reads a query or a folder. A site's records are a fact about
 // the filesystem — plus `site.yml::paths.records`, which says where they live.
@@ -32,13 +40,13 @@
 // ⛔ BARE, NOT `records/@std/`. Measured: `@` is a reserved indicator in YAML
 // 1.2, so a bare `@std/person/*.md` scalar throws in js-yaml — and the message is
 // `bad indentation of a sequence entry`, which names neither the cause nor the
-// fix. The `@` form would force quotes on every pattern in `records.yml` that
+// fix. The `@` form would force quotes on every pattern in `folder.yml` that
 // names a scoped schema.
 //
 // ⛔ AND NO NESTING BELOW THE SCHEMA DIR, which is what makes the depth rule
 // total: it is the FILE's depth that decides, so one path answers the question
 // with nothing to classify and no ambiguous case to resolve. Organization is a
-// `folder:` in `records.yml`, never a directory.
+// `folder:` in `folder.yml`, never a directory.
 //
 // ⛔ THE DIRECTORY WAS `entities/` UNTIL 2026-09-21, and `site.yml::paths.entities`
 // the key that moved it. Both are refused by name rather than read (no alias —
@@ -57,6 +65,15 @@ export const RECORDS_DIR = 'records'
 /** The directory's name until 2026-09-21. Read only to refuse it. */
 const RETIRED_DIR = 'entities'
 
+/**
+ * The folder's organization, at the top of the records directory — the one file
+ * there that is not a record. See the header, and `records-config.js`.
+ */
+export const FOLDER_YML = 'folder.yml'
+
+/** Where the folder's organization lived until 2026-09-21: the site root. Read only to refuse it. */
+const RETIRED_FOLDER_FILE = 'records.yml'
+
 function isDirectory(path) {
   try {
     return statSync(path).isDirectory()
@@ -92,10 +109,38 @@ export function refuseRetiredRecordsDir(siteRoot, rel) {
   throw new Error(
     `[uniweb] ${RETIRED_DIR}/ is not read — a site's records live in \`${rel}/\` now. ` +
       `Rename the directory (\`git mv ${RETIRED_DIR} ${rel}\`) and every file in it is a record, ` +
-      `as before; records.yml no longer lists them.`
+      `as before; nothing lists them any more.`
+  )
+}
+
+/**
+ * Refuse the retired `records.yml` at the site root: the folder's organization is
+ * `folder.yml` inside the records directory now.
+ *
+ * ⛔ SAME REASON AS THE DIRECTORY ABOVE. Left in place it would be read by nothing,
+ * every record would sit at the top of the folder, and the next push would send
+ * that — replacing the backend folder's sub-folders — with nothing to say why. Its
+ * contents move unchanged: the paths in it were always relative to the records
+ * directory.
+ */
+export function refuseRetiredFolderFile(siteRoot, rel) {
+  const retired = resolve(siteRoot, RETIRED_FOLDER_FILE)
+  // A records directory at the site root itself would make that path a record's.
+  if (resolve(siteRoot, rel) === resolve(siteRoot)) return
+  if (!existsSync(retired)) return
+  throw new Error(
+    `[uniweb] ${RETIRED_FOLDER_FILE} is not read — the records folder's organization is ` +
+      `\`${rel}/${FOLDER_YML}\` now, inside the directory it organizes. Move it ` +
+      `(\`git mv ${RETIRED_FOLDER_FILE} ${rel}/${FOLDER_YML}\`); its contents are unchanged.`
   )
 }
 
+/** Both retired layouts, refused wherever the records directory is resolved. */
+function refuseRetiredLayout(siteRoot, rel) {
+  refuseRetiredRecordsDir(siteRoot, rel)
+  refuseRetiredFolderFile(siteRoot, rel)
+}
+
 /**
  * Where a site's records live — `site.yml::paths.records`, else `records/`.
  *
@@ -120,7 +165,7 @@ export function resolveRecordsDir(siteRoot, paths) {
     )
   }
   const rel = typeof p.records === 'string' && p.records.trim() ? p.records.trim().replace(/\/+$/, '') : RECORDS_DIR
-  refuseRetiredRecordsDir(siteRoot, rel)
+  refuseRetiredLayout(siteRoot, rel)
   return { rel, abs: resolve(siteRoot, rel) }
 }
 
@@ -211,7 +256,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
   let rel
   if (opts.dir) {
     rel = String(opts.dir).replace(/\/+$/, '')
-    refuseRetiredRecordsDir(siteRoot, rel)
+    refuseRetiredLayout(siteRoot, rel)
   } else {
     rel = resolveRecordsDir(siteRoot).rel
   }
@@ -243,7 +288,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
             `${rel}/${[...dirs, e.name].join('/')}/ is nested below a schema folder. ` +
               `\`${rel}/\` declares a model and nothing else — \`${[...dirs].join('/')}\` ` +
               `already names ${read}, so there is no meaning left for a folder inside it. ` +
-              `Organise records in records.yml (a \`folder:\` entry), not on disk.`
+              `Organise records in ${rel}/${FOLDER_YML} (a \`folder:\` entry), not on disk.`
           )
           continue
         }
@@ -251,13 +296,16 @@ export async function readEntityPool(siteRoot, opts = {}) {
         continue
       }
       if (!e.isFile()) continue
+      // The folder's organization, not a record — see the header.
+      if (dirs.length === 0 && e.name === FOLDER_YML) continue
       const ext = extname(e.name).toLowerCase()
       if (!ENTITY_EXTENSIONS.has(ext)) continue
       if (dirs.length === 0) {
         errors.push(
           `${rel}/${e.name} sits directly in \`${rel}/\`, which names no model. ` +
             `Move it under a schema folder — \`${rel}/<name>/\` for \`@/<name>\`, ` +
-            `or \`${rel}/<org>/<name>/\` for \`@<org>/<name>\`.`
+            `or \`${rel}/<org>/<name>/\` for \`@<org>/<name>\`. The one file that belongs ` +
+            `at the top is \`${FOLDER_YML}\`, the folder's organization.`
         )
         continue
       }

package/src/site/foundation-ref.js

@@ -31,6 +31,20 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve, join } from 'node:path'
 
+/**
+ * A catalog ref — `@org/name@version` — in its parts, or null for anything else.
+ *
+ * The grammar lives here once: `detectFoundationType` refuses a ref for a build, and a
+ * site's sync reads the ref's scope to qualify its `@/x` refs (`uwx/self-scope.js`).
+ *
+ * @param {unknown} value
+ * @returns {{ scope: string, name: string, version: string }|null} `scope` as `@org`
+ */
+export function parseCatalogRef(value) {
+  const m = typeof value === 'string' ? /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(value) : null
+  return m ? { scope: `@${m[1]}`, name: m[2], version: m[3] } : null
+}
+
 /**
  * Detect foundation type from the foundation config value
  *
@@ -104,8 +118,7 @@ export function detectFoundationType(foundation, siteRoot) {
   // match the documented backend selection — so `--backend`, `uniweb login
   // --backend` and the documented env var all left it pinned — and the artifact
   // names were the pre-`entry.js` ones the build stopped emitting.
-  const orgScopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
-  if (orgScopedMatch) {
+  if (parseCatalogRef(name)) {
     throw new Error(
       [
         `Foundation "${name}" is a catalog ref, and a build cannot resolve it to a URL.`,

package/src/site/plugin.js

@@ -132,8 +132,10 @@ export function shouldPrefetchInDev(cfg) {
  *   - `'queries'` — re-collect the site, re-materialize every query file from the
  *     query list just collected, reload. `queries.yml` declares queries, and so does
  *     `site.yml` (`queries:`), beside the rest of the site's configuration.
- *   - `'records'` — re-materialize the query files, reload: `records.yml` decides
- *     which folder each record sits in, which a query's `scope:` reads.
+ *   - `'records'` — re-materialize the query files, reload. Only the retired
+ *     `records.yml` maps here now, so that the rebuild REPORTS it: the folder's
+ *     organization is `records/folder.yml` since 2026-09-21, and an edit to it is
+ *     seen by the records directory's own recursive watch.
  *   - `'content'` — re-collect the site, reload.
  *
  * ⛔ Until 2026-09-14 nothing watched `records.yml` or `queries.yml`, a `site.yml`
@@ -148,7 +150,7 @@ export function siteRootChange(filename) {
     case 'site.yml':
     case 'queries.yml':
       return 'queries'
-    case 'records.yml':
+    case 'records.yml': // retired — watched so the rebuild refuses it
       return 'records'
     case 'theme.yml':
     case 'head.html':
@@ -1096,10 +1098,10 @@ export function siteContentPlugin(options = {}) {
           }
         }
 
-        // Watch the site root — `site.yml`, `queries.yml`, `records.yml`, `theme.yml`,
-        // `head.html` — as ONE directory rather than a watch per file: a file watch
-        // cannot be set on a file created after the server started (a first
-        // `records.yml`), and an editor that saves by replacing a file ends its watch.
+        // Watch the site root — `site.yml`, `queries.yml`, `theme.yml`, `head.html`,
+        // and the retired `records.yml` — as ONE directory rather than a watch per
+        // file: a file watch cannot be set on a file created after the server started
+        // (a first `queries.yml`), and an editor that saves by replacing a file ends its watch.
         // Not recursive, so what the build writes below the root (`public/data/`) is
         // not seen here. What each change redoes is `siteRootChange`.
         try {

package/src/site/queries-config.js

@@ -17,7 +17,7 @@
 //
 // ⛔ THE THREE JOBS `collections/<name>/` USED TO FUSE ARE NOW THREE THINGS.
 // `records/{schema}/` holds the site's records (placing a file there is what makes
-// it one), `records.yml` sorts them into folders, and a query asks for a set. This
+// it one), `records/folder.yml` sorts them into folders, and a query asks for a set. This
 // file resolves the LAST of those only.
 //
 // ⚠️ `collections.yml` and `site.yml::collections` are GONE, with no alias and no
@@ -116,7 +116,7 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
   const ymlPath = join(siteRoot, QUERIES_YML_RELPATH)
   const hasQueriesYml = existsSync(ymlPath)
   // ⛔ A BARE MAP — `queries.yml` has no root key. The file IS the map, the way
-  // `records.yml` IS the list. A `queries:` key inside it would be a name a query
+  // `records/folder.yml` IS the list. A `queries:` key inside it would be a name a query
   // could then collide with.
   const queriesYml = hasQueriesYml ? await readYamlFile(ymlPath) : {}
 
@@ -368,7 +368,7 @@ async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
  * The `deferred:` a schema implies — every record field its **brief** does not name.
  *
  * ⛔ ONE IMPLEMENTATION, TWO CALLERS, and that is the point. `deriveDeferredFromSchemas`
- * above uses it to FILL an unstated `deferred:`; `uwx/collections-project.js` uses it to
+ * above uses it to FILL an unstated `deferred:`; `uwx/records-project.js` uses it to
  * RECOGNIZE a derived value on the way back in, so a pull does not write a derivation
  * into the author's file as though they had typed it.
  *

package/src/site/query-processor.js

@@ -136,7 +136,7 @@ function parseQueryConfig(name, config) {
     // model, so the site's records of a schema are the query's records.
     schema: config.schema || null,
     url: config.url || null,
-    // The folder branch the query reads (`records.yml` placement). ⛔ Not read
+    // The folder branch the query reads (`folder.yml` placement). ⛔ Not read
     // here until 2026-09-11: a named query's `scope` was ignored on this lane.
     scope: typeof config.scope === 'string' ? config.scope : null,
     sort: config.sort || null,
@@ -702,7 +702,7 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
     })
   )
 
-  // ⭐ `path` IS THE FOLDER `records.yml` PLACED THE RECORD IN — `''` at the top —
+  // ⭐ `path` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
   // and it is the whole reason folders exist: `scope: archive` is how a query asks
   // for a slice. Structure is query scope, not navigation.
   //
@@ -820,18 +820,19 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   }
 
   // ⭐ EVERY FILE IN `records/` IS A RECORD (ruled 2026-09-21 [Diego]), so every one
-  // is compiled; `records.yml` only says which folder each sits in (`path`), which
-  // is what a query's `scope` reads. ⛔ Until 2026-09-21 `records.yml` listed the
-  // records, and an unlisted file was left out of `/data/<name>.json` here.
+  // is compiled; `records/folder.yml` only says which folder each sits in (`path`),
+  // which is what a query's `scope` reads. ⛔ Until 2026-09-21 `records.yml`, at the
+  // site root, listed the records, and an unlisted file was left out of
+  // `/data/<name>.json` here.
   //
   // ⛔ A MALFORMED FILE STILL STOPS THE BUILD. It read as absent here until
   // 2026-09-14 while the sync lane refused the same file (`uwx/records.js`); what an
   // author meant to organize cannot be guessed.
-  const recordsCfg = await readRecordsConfig(siteDir)
+  const recordsCfg = await readRecordsConfig(siteDir, { dir: pool.dir })
   if (recordsCfg.error) {
     throw new Error(
       `[uniweb] ${recordsCfg.error}\n` +
-        `  records.yml says which folder each record sits in, and a query's \`scope:\` reads that — fix it to build.`
+        `  ${recordsCfg.file} says which folder each record sits in, and a query's \`scope:\` reads that — fix it to build.`
     )
   }
   const folder = resolveFolder(recordsCfg.entries, pool.entities, { dir: pool.dir })