@uniweb/build 0.57.0 → 0.58.0

package/src/site/records-config.js

@@ -1,9 +1,17 @@
-// `records.yml` — how the site's records folder is ORGANIZED. Optional.
+// `records/folder.yml` — how the site's records folder is ORGANIZED. Optional.
 //
 // ⭐ IT DOES NOT SAY WHAT IS IN THE FOLDER (ruled 2026-09-21 [Diego]). Every file in
 // `records/` is a record — placing it there is what makes one (`entity-pool.js`).
 // This file only sorts records into sub-folders, so a site whose records are one
-// flat set has no `records.yml` at all, which is the common case.
+// flat set has no `folder.yml` at all, which is the common case.
+//
+// ⭐ IT LIVES IN THE DIRECTORY IT ORGANIZES (ruled 2026-09-21 [Diego]) — the one file
+// at the top of `records/` that is not a record. The directory is the site's folder
+// on the file side, and this is that folder's organization: its paths are relative
+// to the directory, it moves with `paths.records`, and it 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, and a file there is
+// refused by name (`entity-pool.js::refuseRetiredFolderFile`), not read.
 //
 // ⛔ UNTIL 2026-09-21 THIS FILE WAS THE MEMBERSHIP LIST: a bare string at the top
 // level listed an entity and made it a record, an unlisted one was left out, and
@@ -34,21 +42,30 @@
 
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
-import { RECORDS_DIR } from './entity-pool.js'
+import { RECORDS_DIR, FOLDER_YML, resolveRecordsDir } from './entity-pool.js'
 
-export const RECORDS_YML_RELPATH = 'records.yml'
+export { FOLDER_YML }
 
-/** Path to the records.yml file (whether or not it exists yet). */
-export function recordsYmlPath(siteRoot) {
-  return join(siteRoot, RECORDS_YML_RELPATH)
+/**
+ * Where the folder's organization lives — `folder.yml` in the records directory
+ * (`site.yml::paths.records`, else `records/`) — whether or not it exists yet.
+ *
+ * @param {string} siteRoot
+ * @param {string} [dir] - the records directory as written, when the caller has it;
+ *   otherwise it is resolved here, which also refuses the retired layouts
+ * @returns {{ abs: string, rel: string }} `rel` for messages (`records/folder.yml`)
+ */
+export function folderYmlPath(siteRoot, dir) {
+  const rel = dir ?? resolveRecordsDir(siteRoot).rel
+  return { abs: resolve(siteRoot, rel, FOLDER_YML), rel: `${rel}/${FOLDER_YML}` }
 }
 
 /**
- * Match one record path against a `records.yml` pattern.
+ * Match one record path against a `folder.yml` pattern.
  *
  * ⛔ `*` DOES NOT CROSS A `/`, which is what a reader expects of a file pattern
  * and is NOT what `@uniweb/core`'s `globMatch` does. That one backs the `like`
@@ -85,7 +102,7 @@ export function slugForEntity(entity) {
 }
 
 /**
- * Read `records.yml` — the folder's organization.
+ * Read `folder.yml` — the folder's organization, in the records directory.
  *
  * ⭐ MISSING AND EMPTY MEAN THE SAME: no sub-folders, every record at the top.
  * ⛔ Until 2026-09-21 they differed — missing left a backend's folder alone, empty
@@ -94,34 +111,40 @@ export function slugForEntity(entity) {
  *
  * ⛔ A MALFORMED FILE IS STILL AN ERROR: what it meant to organize cannot be guessed.
  *
- * @returns {Promise<{ exists: boolean, entries: Array, error: string|null }>}
+ * @param {string} siteRoot
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - the records directory as written (`readEntityPool`'s
+ *   `dir`), when the caller has it; otherwise it is resolved from `site.yml`
+ * @returns {Promise<{ exists: boolean, entries: Array, error: string|null, file: string }>}
+ *   `file` is where it was looked for, as the author would write it
  */
-export async function readRecordsConfig(siteRoot) {
-  const file = join(siteRoot, RECORDS_YML_RELPATH)
-  if (!existsSync(file)) return { exists: false, entries: [], error: null }
+export async function readRecordsConfig(siteRoot, { dir } = {}) {
+  const { abs, rel: file } = folderYmlPath(siteRoot, dir)
+  if (!existsSync(abs)) return { exists: false, entries: [], error: null, file }
 
   let doc
   try {
-    doc = yaml.load(await readFile(file, 'utf8'), YAML_OPTIONS)
+    doc = yaml.load(await readFile(abs, 'utf8'), YAML_OPTIONS)
   } catch (err) {
-    return { exists: true, entries: [], error: `${RECORDS_YML_RELPATH}: ${err.message}` }
+    return { exists: true, entries: [], error: `${file}: ${err.message}`, file }
   }
 
-  if (doc === null || doc === undefined) return { exists: true, entries: [], error: null }
+  if (doc === null || doc === undefined) return { exists: true, entries: [], error: null, file }
   if (!Array.isArray(doc)) {
     return {
       exists: true,
       entries: [],
       error:
-        `${RECORDS_YML_RELPATH} must be a LIST of folders, not ${typeof doc === 'object' ? 'a mapping' : 'a single value'}. ` +
+        `${file} must be a LIST of folders, not ${typeof doc === 'object' ? 'a mapping' : 'a single value'}. ` +
         `For example:\n  - folder: archive\n    records:\n      - publication/2025-*.md`,
+      file,
     }
   }
-  return { exists: true, entries: doc, error: null }
+  return { exists: true, entries: doc, error: null, file }
 }
 
 /**
- * Place the site's records in its folder: the sub-folders `records.yml` declares,
+ * Place the site's records in its folder: the sub-folders `folder.yml` declares,
  * and the top of the folder for every record no sub-folder names.
  *
  * Every rule here is a guard, and each one exists because its failure was
@@ -136,7 +159,7 @@ export async function readRecordsConfig(siteRoot) {
  * evaluates `scope` natively, so widening it is a cross-lane change to agree first,
  * not to infer. Until then the file lane is the floor: one folder.
  *
- * @param {Array} entries - the parsed `records.yml` list
+ * @param {Array} entries - the parsed `folder.yml` list
  * @param {Array} pool - records from `readEntityPool`
  * @param {object} [opts]
  * @param {string} [opts.dir] - the records directory as written, for messages
@@ -146,11 +169,15 @@ export async function readRecordsConfig(siteRoot) {
  *   `{ entity, path, slug }`, `path` being `''` at the top of the folder.
  */
 export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
+  // The file as the author sees it, for every message below.
+  const file = `${dir}/${FOLDER_YML}`
   const errors = []
   const warnings = []
   const placements = new Map()
   // Which entry claimed a file, so the second one can name the first.
   const claimedBy = new Map()
+  // Which entry declared a folder, by its path, for the same reason.
+  const folderAt = new Map()
 
   const byRelPath = new Map()
   for (const e of pool || []) {
@@ -165,7 +192,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     const prior = claimedBy.get(key)
     if (prior) {
       errors.push(
-        `${RECORDS_YML_RELPATH}: "${entity.relPath}" is placed twice — by ${prior} and by ${where}. ` +
+        `${file}: "${entity.relPath}" is placed twice — by ${prior} and by ${where}. ` +
           `A record sits in one folder; a computed subset is a named query, not a second placement.`
       )
       return null
@@ -187,21 +214,21 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       // would claim to choose while choosing nothing: refused, with the reason.
       if (pathSegs.length === 0) {
         errors.push(
-          `${RECORDS_YML_RELPATH}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
-            `${dir}/ is a record already — ${RECORDS_YML_RELPATH} only sorts records into folders. ` +
+          `${file}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
+            `${dir}/ is a record already — ${file} only sorts records into folders. ` +
             `Remove the entry, or put it under a \`folder:\`.`
         )
         return []
       }
       if (!pattern) {
-        errors.push(`${RECORDS_YML_RELPATH}: ${where} is an empty string.`)
+        errors.push(`${file}: ${where} is an empty string.`)
         return []
       }
       if (!isPattern(pattern)) {
         const hit = byRelPath.get(pattern)
         if (!hit) {
           errors.push(
-            `${RECORDS_YML_RELPATH}: ${where} names "${pattern}", which is not in ${dir}/. ` +
+            `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
               `A path is relative to ${dir}/, extension included.`
           )
           return []
@@ -217,7 +244,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
         .map(([, e]) => e)
       if (matches.length === 0) {
         errors.push(
-          `${RECORDS_YML_RELPATH}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
+          `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
             `Check the schema folder name and the extension.`
         )
         return []
@@ -231,7 +258,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
 
     if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
       errors.push(
-        `${RECORDS_YML_RELPATH}: ${where} is neither ${pathSegs.length ? 'a path nor ' : ''}a \`folder:\` entry.`
+        `${file}: ${where} is neither ${pathSegs.length ? 'a path nor ' : ''}a \`folder:\` entry.`
       )
       return []
     }
@@ -246,7 +273,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       const raw = entry.folder
       const segment = raw === null || raw === undefined ? '' : String(raw).trim()
       if (!segment) {
-        errors.push(`${RECORDS_YML_RELPATH}: ${where} declares a folder with no name.`)
+        errors.push(`${file}: ${where} declares a folder with no name.`)
         return []
       }
       // ⭐ A folder's `name` is the segment a query's `scope:` names; `label` is its
@@ -255,12 +282,26 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       // is the curator's organization and maps to no route unless a query binds
       // `scope: :dir` [Diego]. *("the URL segment, sibling-unique" stood here until
       // 2026-09-21.)*
+      // ⛔ TWO FOLDERS AT ONE LEVEL CANNOT SHARE A NAME. A query's `scope:` names a
+      // folder by its path, so a second `archive` beside the first would make one scope
+      // of both, and a backend refuses a folder holding the pair. Records at one level
+      // may share a name; folders may not.
+      const at = [...pathSegs, segment].join('/')
+      const prior = folderAt.get(at)
+      if (prior) {
+        errors.push(
+          `${file}: folder "${segment}" is declared twice at one level — by ${prior} and by ${where}. ` +
+            `A query's \`scope:\` names a folder by its path, so merge them into one entry.`
+        )
+        return []
+      }
+      folderAt.set(at, where)
       const branch = { kind: 'branch', name: segment }
       if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
       const kids = Array.isArray(entry.records) ? entry.records : []
       if (kids.length === 0) {
         warnings.push(
-          `${RECORDS_YML_RELPATH}: folder "${segment}" (${where}) holds no records. ` +
+          `${file}: folder "${segment}" (${where}) holds no records. ` +
             `A folder exists to be QUERIED — if no query needs the slice, do not make it.`
         )
       }
@@ -277,7 +318,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     if (entry.url !== undefined || entry.asset !== undefined) {
       const kind = entry.url !== undefined ? 'url' : 'asset'
       errors.push(
-        `${RECORDS_YML_RELPATH}: ${where} declares \`${kind}:\`, which the folder producer ` +
+        `${file}: ${where} declares \`${kind}:\`, which the folder producer ` +
           `does not emit yet. A folder holds urls and assets by design, but nothing would ` +
           `be sent for this entry — so it is refused rather than dropped.`
       )
@@ -285,7 +326,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     }
 
     errors.push(
-      `${RECORDS_YML_RELPATH}: ${where} has no recognized kind. ` +
+      `${file}: ${where} has no recognized kind. ` +
         (pathSegs.length
           ? `Inside a folder, a path names records; anything else says \`folder:\`.`
           : `An entry is a \`folder:\` — its \`records:\` are paths under ${dir}/.`)

package/src/utils/numeric-prefix.js

@@ -1,6 +1,6 @@
 // The `01-` filename convention — ONE rule, for pages and for records.
 //
-// ⛔ IT WAS PRIVATE TO THE PAGES LANE, and `records.yml` needs exactly the same
+// ⛔ IT WAS PRIVATE TO THE PAGES LANE, and `records/folder.yml` needs exactly the same
 // rule: a leading `01-` orders a file and is stripped from the name it produces.
 // Two copies would drift, and the drift would be invisible — a section ordering
 // one way and a record another, both plausible, with nothing comparing them.

package/src/uwx/backfill.js

@@ -228,6 +228,8 @@ function briefHasContentBody(declaration) {
  * entity: the entity `$uuid` + the brief section's fields (localized unwrapped,
  * date/scalars verbatim), with the brief record's own `$uuid` DROPPED (the backend
  * matches a single-section item by singularity) and `$model`/`$id`/`$meta` omitted.
+ * A disabled entity (`$disabled: true`) writes `draft: true`, and an enabled one writes
+ * no `draft:` at all.
  * For markdown, the content body field becomes the body; for YAML/JSON it stays a field.
  *
  * @param {object} params
@@ -283,6 +285,11 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
     }
     record[key] = value
   }
+  // ⭐ A DISABLED ENTITY IS A DRAFT ON THE FILE SIDE. It is kept in the folder and never
+  // publicly delivered, which is exactly what `draft: true` means. An enabled entity
+  // carries no key and writes no `draft:`, so a record re-enabled on the backend
+  // comes back without the line.
+  if (document.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
   if (format === 'md') return `---\n${yaml.dump(record)}---\n${body}`
@@ -318,8 +325,9 @@ function writeIfChanged(filePath, text) {
  *        order: `{ id, model, slug, sourceFile, format?, multiRecord?, declaration? }`.
  * @param {object[]} params.finalized - response entries `{ index, uuid, changed?, document? }`.
  * @param {string} [params.sourceLocale]
- * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string> }}
+ * @returns {{ updated: string[], unchanged: string[], deferred: object[], warnings: string[], mapped: Object<string,string>, notKeptAsDrafts: string[] }}
  *   `mapped` is own id → the uuid this backend minted, for the caller to record per backend.
+ *   `notKeptAsDrafts` names records sent as drafts whose returned document is not disabled.
  */
 export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   const updated = []
@@ -336,6 +344,8 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   // Multi-record files are written ONCE per file, applying every (slug → uuid).
   const arrayFiles = new Map() // array-form YAML/JSON: sourceFile -> Map(slug -> uuid)
   const bibFiles = new Map() // BibTeX: sourceFile -> Map(cite key -> uuid)
+  // Records sent as drafts that the backend stored enabled. See the check below.
+  const notKeptAsDrafts = []
 
   for (const fin of finalized || []) {
     const uuid = fin.uuid
@@ -351,6 +361,15 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     // (no uuid to back-fill — the backend owns the site's folder, keyed by the
     // site-content uuid). Both are positional placeholders with no record source file.
     if (entry.kind === 'site' || entry.kind === 'folder') continue
+    // ⛔ A DRAFT THE BACKEND DID NOT KEEP AS ONE. A backend is obliged to echo
+    // `$disabled: true` on the document of an entity it stored disabled. One that predates
+    // the key skips it without a word and stores the record enabled, so it is delivered
+    // once the site is published. Rendering that document over the file (variant A) would
+    // then erase `draft: true` from the author's file as well, so the file keeps its own
+    // text and the caller is told. Only a returned document that lacks the flag counts:
+    // with no document there is nothing to judge.
+    const draftNotKept = entry.draft === true && fin.document && fin.document.$disabled !== true
+    if (draftNotKept) notKeptAsDrafts.push(entry.sourceFile || entry.id)
     if (!entry.sourceFile) {
       deferred.push({ index: i, id: entry.id, reason: 'no source file on disk' })
       continue
@@ -389,6 +408,7 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
     // the declaration, and it's lossless for the format (md needs a content body
     // field for its body). Otherwise variant B: back-fill the uuid in place.
     const canRenderA =
+      !draftNotKept &&
       fin.document &&
       entry.declaration &&
       (entry.format !== 'md' || briefHasContentBody(entry.declaration))
@@ -432,5 +452,5 @@ export function backfillEntityUuids({ index, finalized, sourceLocale = 'en' }) {
   for (const file of ownIdFiles) {
     if (!updated.includes(file) && !unchanged.includes(file)) unchanged.push(file)
   }
-  return { updated, unchanged, deferred, warnings, mapped }
+  return { updated, unchanged, deferred, warnings, mapped, notKeptAsDrafts }
 }

package/src/uwx/entity-source.js

@@ -11,7 +11,7 @@
 // It reported records below a collection's top level as building and rendering
 // locally while being absent from the synced set — the delivery lane recursed,
 // this one was one level deep. `records/{schema}/` has no nesting to disagree
-// about (`site/entity-pool.js` refuses it), and placement moved to `records.yml`,
+// about (`site/entity-pool.js` refuses it), and placement moved to `records/folder.yml`,
 // so both lanes now read the same flat directory. The warning went with the ambiguity.
 //
 // A collection `.md` is NOT a page-section `.md`: its frontmatter is structured

package/src/uwx/folder.js

@@ -30,8 +30,8 @@
 // carry.
 //
 // ⭐ WHAT IS IN THE FOLDER IS THE RECORDS DIRECTORY; HOW IT IS ORGANIZED IS
-// `records.yml` (ruled 2026-09-21 [Diego]). Every file in `records/` is a record and
-// sits at the top of the folder unless `records.yml` places it in a sub-folder. The
+// `records/folder.yml` (ruled 2026-09-21 [Diego]). Every file in `records/` is a
+// record and sits at the top of the folder unless `folder.yml` places it in a sub-folder. The
 // organization used to be DERIVED — one branch per collection, mirroring the
 // `collections/` subfolders — and the difference is the point: a sub-folder is a
 // thing the author states, never a shadow of the schema folders, which declare a
@@ -209,7 +209,7 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  * @param {object} params
  * @param {object[]} params.recordEntities - the record entities (full set, BEFORE
  *        send-only-changed filtering), each `{ id, uuid, slug, model }`
- * @param {Array} params.folderNodes - the placed records: `records.yml`'s sub-folders,
+ * @param {Array} params.folderNodes - the placed records: `folder.yml`'s sub-folders,
  *        then every record at the top
  * @param {boolean} [params.declared] - whether the records DIRECTORY exists. See below.
  * @param {Record<string,string>} [params.itemUuids] - path → `$uuid`, harvested

package/src/uwx/index.js

@@ -61,7 +61,7 @@ export { buildFolderEntity,
 export {
   recordsToProject,
   declarationsToQueriesYml,
-  folderToRecordsYml,
+  folderToFolderYml,
   findRecordFileByUuid,
 } from './records-project.js'
 export {
@@ -127,12 +127,13 @@ export {
   RECORDS_DIR,
 } from '../site/entity-pool.js'
 
-// How the folder is organized, so a verb can ask what `records.yml` SAYS without
+// How the folder is organized, so a verb can ask what `records/folder.yml` SAYS without
 // re-reading or re-parsing it. ⛔ Note the allowlist: an export added to
 // `site/records-config.js` does not reach a caller until it is named here.
 export {
   readRecordsConfig,
-  RECORDS_YML_RELPATH,
+  FOLDER_YML,
+  folderYmlPath,
 } from '../site/records-config.js'
 export {
   findRecordFile,

package/src/uwx/project-writer.js

@@ -19,7 +19,7 @@ import { proseMirrorToMarkdown, serializeFrontmatter } from '@uniweb/content-wri
 import { parseFrontmatter } from './entity-source.js'
 import { renderEntityDocument } from './backfill.js'
 import { queriesYmlPath } from './queries-config.js'
-import { recordsYmlPath } from '../site/records-config.js'
+import { folderYmlPath } from '../site/records-config.js'
 import { DECLARATION_KEYS } from '../site/fetch-shapes.js'
 
 // Frontmatter keys that belong to the CCA framework / the developer's local
@@ -294,23 +294,25 @@ export function writeQueriesConfig(siteRoot, queries) {
 }
 
 /**
- * Write `records.yml` — the site's folder, as a LIST.
+ * Write the records folder's organization — `folder.yml` in the records directory
+ * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
  *
  * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
- * other projected config. `records.yml` IS the folder: concrete refs on both
- * sides, nothing to invert, so a pull is a mirror rather than an update. There is
- * also nothing a shallow merge could mean here — the file is a sequence, and
- * merging two lists either duplicates entries or silently drops them.
+ * other projected config. The file mirrors the folder's sub-folders: concrete refs
+ * on both sides, nothing to invert, so a pull is a mirror rather than an update.
+ * There is also nothing a shallow merge could mean here — the file is a sequence,
+ * and merging two lists either duplicates entries or silently drops them.
  *
- * ⚠️ WHICH IS WHY AN EMPTY LIST IS NOT WRITTEN AS A FILE-WITH-NOTHING BY ACCIDENT.
- * An empty `records.yml` is DESTRUCTIVE on the next push — it says the folder holds
- * nothing. A pull that carried no folder must leave the file alone, so the caller
- * decides, and this only writes what it was actually given.
+ * The caller decides whether there is anything to write: a folder with no
+ * sub-folders is no file at all (`folderToFolderYml` removes it), since missing and
+ * empty mean the same. ⚠️ *Until 2026-09-21 this said an empty file was destructive
+ * on the next push; that stopped being true when the directory, not this file,
+ * became what decides which records the folder holds.*
  *
  * @returns {'updated'|'unchanged'}
  */
 export function writeRecordsConfig(siteRoot, entries) {
-  return writeYamlFile(recordsYmlPath(siteRoot), entries)
+  return writeYamlFile(folderYmlPath(siteRoot).abs, entries)
 }
 
 /**

package/src/uwx/records-project.js

@@ -1,8 +1,8 @@
 // Records projection — write a pulled folder and its records back to the site's
-// `records/**` files and `records.yml`. The inverse of the producer (`records.js`
-// + `folder.js`): the producer reads the records directory and emits the
-// `@uniweb/folder` entity + one section-keyed `$`-document per record; this takes
-// those documents back and renders them to files.
+// `records/**` files and the folder's organization, `records/folder.yml`. The
+// inverse of the producer (`records.js` + `folder.js`): the producer reads the
+// records directory and emits the `@uniweb/folder` entity + one section-keyed
+// `$`-document per record; this takes those documents back and renders them to files.
 //
 // Identity & placement:
 //   - a record's slug comes from the FOLDER document — each ref leaf is
@@ -38,7 +38,7 @@ import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
 import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
 import { poolDirsForSchema, resolveRecordsDir } from '../site/entity-pool.js'
-import { recordsYmlPath } from '../site/records-config.js'
+import { folderYmlPath } from '../site/records-config.js'
 import { isContentBodyField } from './data-schema.js'
 import { unresolveSelfScope } from './self-scope.js'
 import { unwrapLocalized } from './backfill.js'
@@ -370,18 +370,19 @@ export function declarationsToQueriesYml({ document, siteRoot, org, backend = nu
 }
 
 /**
- * Project a pulled `@uniweb/folder` document back to `records.yml`.
+ * Project a pulled `@uniweb/folder` document back to `folder.yml` in the records
+ * directory (`records/folder.yml`, or under `site.yml::paths.records`).
  *
  * ⭐ THE FOLDER ROUND-TRIPS TRIVIALLY, and that is by design rather than luck:
- * `records.yml` holds concrete paths on both sides, so there is nothing to invert.
+ * `folder.yml` holds concrete paths on both sides, so there is nothing to invert.
  * The old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
  * collections — and inverting a macro is not possible in general. Taking queries
  * out of the folder is what dissolved that.
  *
  * ⭐ ONLY THE SUB-FOLDERS ARE WRITTEN (ruled 2026-09-21 [Diego]). A record at the
  * top of the folder needs no line — being in the records directory is what puts it
- * there — so `records.yml` carries the branches and the records placed in them, and
- * a folder with no branches is a site with no `records.yml`: a local one is REMOVED
+ * there — so `folder.yml` carries the branches and the records placed in them, and
+ * a folder with no branches is a site with no `folder.yml`: a local one is REMOVED
  * (it could only describe sub-folders the backend's folder no longer has). No state
  * of the file removes a record, so this cannot empty anything.
  *
@@ -395,11 +396,13 @@ export function declarationsToQueriesYml({ document, siteRoot, org, backend = nu
  *        under `records/` of the file just written for it. Supplied by
  *        `recordsToProject`, which is the only thing that knows the extension
  *        each record landed with.
- * @returns {{ status: 'updated'|'unchanged'|'removed'|'skipped', entries: Array, warnings: string[] }}
+ * @returns {{ status: 'updated'|'unchanged'|'removed'|'skipped', entries: Array, warnings: string[], file: string }}
+ *   `file` is where the organization lives, as the author would write it
  */
-export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = 'en' }) {
+export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = 'en' }) {
   const warnings = []
-  if (!folderDoc) return { status: 'skipped', entries: [], warnings }
+  const { abs, rel: file } = folderYmlPath(siteRoot)
+  if (!folderDoc) return { status: 'skipped', entries: [], warnings, file }
   let unplaceable = false
 
   const walk = (nodes, inBranch) => {
@@ -410,7 +413,7 @@ export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, source
         const entry = { folder: node.name }
         // Only a BRANCH takes a label. A record carries its own title; the folder
         // does not caption its rows. On the wire the label is a localized map;
-        // records.yml carries the source-locale string (a bare string passes).
+        // folder.yml carries the source-locale string (a bare string passes).
         if (node.label !== undefined) entry.label = unwrapLocalized(node.label, sourceLocale)
         entry.records = walk(node.$children, true)
         out.push(entry)
@@ -435,7 +438,7 @@ export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, source
         // means the folder and the directory disagree, and writing the file without
         // it would move that record to the top of the folder on the next push.
         warnings.push(
-          `records.yml: the folder places a record ("${node.name ?? '?'}") that was not ` +
+          `${file}: the folder places a record ("${node.name ?? '?'}") that was not ` +
             `written locally — the file was left unchanged rather than dropping it.`
         )
         unplaceable = true
@@ -447,14 +450,13 @@ export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, source
   }
 
   const entries = walk(folderDoc.contents, false)
-  if (unplaceable) return { status: 'skipped', entries: [], warnings }
+  if (unplaceable) return { status: 'skipped', entries: [], warnings, file }
   if (entries.length === 0) {
-    const file = recordsYmlPath(siteRoot)
-    if (!existsSync(file)) return { status: 'unchanged', entries, warnings }
-    unlinkSync(file)
-    return { status: 'removed', entries, warnings }
+    if (!existsSync(abs)) return { status: 'unchanged', entries, warnings, file }
+    unlinkSync(abs)
+    return { status: 'removed', entries, warnings, file }
   }
-  return { status: writeRecordsConfig(siteRoot, entries), entries, warnings }
+  return { status: writeRecordsConfig(siteRoot, entries), entries, warnings, file }
 }
 
 /**
@@ -506,7 +508,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   // own id → their uuid, for every record this pull wrote. Recorded at the end.
   const learned = {}
   // uuid → the path under `records/` the record landed at. Only this loop knows
-  // the extension each one got, so `records.yml` is written from it rather than
+  // the extension each one got, so `folder.yml` is written from it rather than
   // re-derived (a second rule could pick a different extension and the folder
   // would name a file that is not there).
   const poolPathByUuid = new Map()
@@ -571,20 +573,20 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     else if (isNew) placed.push(filePath)
     else updated.push(filePath)
     // Keyed by THEIR uuid: the folder document references records in the backend's
-    // terms, so that is what `folderToRecordsYml` will look them up by.
+    // terms, so that is what `folderToFolderYml` will look them up by.
     if (theirs) {
       poolPathByUuid.set(theirs, relative(recordsRoot, filePath).split(sep).join('/'))
       if (own) learned[own] = theirs
     }
   }
 
-  // ⭐ THE FOLDER ITSELF, written back as `records.yml`. Steps that only touched the
+  // ⭐ THE FOLDER ITSELF, written back as `folder.yml`. Steps that only touched the
   // READ path would leave every pull authoring the old shape — the site would build
   // from the new layout and be projected back into the one it replaced.
   //
   // The folder ENTITY still carries no `$uuid` we persist: the backend owns the
   // site's folder, keyed by the site-content uuid.
-  const records = folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale })
+  const records = folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale })
   warnings.push(...records.warnings)
 
   // Flush localized record-field translations to locales/records/{locale}.json,
@@ -596,5 +598,5 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
     updateBackendMap(siteRoot, opts.backend, 'records', learned)
   }
 
-  return { updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status }
+  return { updated, placed, unchanged, skipped, warnings, locales, freeform, records: records.status, recordsFile: records.file }
 }