@uniweb/build 0.65.0 → 0.66.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "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.8.0",
-    "@uniweb/projections": "^0.7.5",
-    "@uniweb/theming": "^0.1.15",
+    "@uniweb/projections": "^0.7.6",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.7"
+    "@uniweb/runtime": "^0.27.8"
   },
   "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.31.0",
-    "@uniweb/runtime": "^0.27.7"
+    "@uniweb/core": "^0.32.0",
+    "@uniweb/runtime": "^0.27.8"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/records.js

@@ -361,10 +361,12 @@ function derivesExcerpt(record, whole, dataSchema, config) {
 /**
  * ⛔ 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 `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.
+ * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
+ * record under), and a top-level `slug` is how a record's reader hands the file's name
+ * on. 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.
+ * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
+ * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
  *
  * @param {string|number} key - a field name (an array index is never one)
  * @param {boolean} topLevel - whether the key sits at the record's own level
@@ -372,7 +374,7 @@ function derivesExcerpt(record, whole, dataSchema, config) {
  */
 function isRecordSystemField(key, topLevel) {
   if (typeof key !== 'string') return false
-  return key.startsWith('$') || (topLevel && (key === 'slug' || key === 'path'))
+  return key.startsWith('$') || (topLevel && key === 'slug')
 }
 
 /**

package/src/prerender.js

@@ -14,7 +14,6 @@ import { pathToFileURL } from 'node:url'
 import {
   resolveDefaultLocale,
   resolveFetchConfigs,
-  joinPathCapture,
   pageRouteQuery,
   routeSelection,
   routeParamValues,
@@ -410,13 +409,14 @@ 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 `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
+        // Create concrete route: /blog/:slug → /blog/my-post, and the same under
+        // `[...path]`: a record carries no branch, so its own URL is its handle alone
+        // (ruled 2026-09-27 [Diego]), the URL its `$route` names (`fillRoutePattern`).
+        // ⛔ Until then this prefixed the record's `path`. ⛔ A FILE PATH, so decoded: the
+        // server decodes the request before looking the file up.
+        const capture = catchAll ? String(paramValue) : null
         const concreteRoute = catchAll
-          ? page.route.replace(new RegExp(`:${catchAll}\\*$`), capture)
+          ? page.route.replace(new RegExp(`:${catchAll}\\*$`), () => capture)
           : page.route.replace(`:${paramName}`, paramValue)
 
         // ⛔ TWO RECORDS, ONE ROUTE — normal the moment the route field is not

package/src/site/data-fetcher.js

@@ -88,7 +88,7 @@ export function applyWhere(items, where) {
  * `@uniweb/core`'s `evaluateQuery`, the one order of work the runtime's default
  * fetcher uses too:
  *
- *   1. the query's set — `scope` over each record's placement (`path`), `where`,
+ *   1. the query's set — `scope` over the branch each record is held with (`$branch`), `where`,
  *      `sort`, `limit`;
  *   2. the fetch's `narrow` of it — `where` (and `match`), `sort`, `limit`.
  *

package/src/site/file-transport.js

@@ -72,8 +72,9 @@ export function createFileTransport({ siteRoot, distDir = null, publicDir = 'pub
       const body = await readFile(file, 'utf8')
       return response(body, path.endsWith('.json') ? 'application/json' : 'text/plain')
     }
-    // ⚖️ Not an error here. A page can ask for a per-record file a `deferred:` query never wrote,
-    // and the step reports the outcome so the caller can see it rather than crash a build.
+    // ⚖️ Not an error here. A page can ask for a per-record file that was never written — a
+    // record this run withholds as a draft, say — and the step reports the outcome so the caller
+    // can see it rather than crash a build.
     return missing(path)
   }
 }

package/src/site/query-processor.js

@@ -58,7 +58,7 @@ import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
-import { DATA_DIR, withoutRouteVariables, mapQueryPaths } from '@uniweb/core'
+import { DATA_DIR, withoutRouteVariables, mapQueryPaths, BRANCH_KEY } from '@uniweb/core'
 import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
@@ -760,8 +760,8 @@ export function flatFormRefusal(where, ref, schema, misplaced) {
  * Every source file in a collection, as paths relative to the collection root —
  * `hello.md`, `2024/spring.md`, `2024/q1/notes.yml`.
  *
- * Nesting is how an author gives a collection an internal structure, and it is
- * what the `path` field and the `under` predicate address. Before this walk the
+ * Nesting is how an author organizes the files; the folder branch a record sits in, which a
+ * query's `scope:` reads, is `records/folder.yml`'s to say (`records-config.js`). Before this walk the
  * scan was a flat `readdir`, so a record in a subdirectory was not ignored with
  * a warning — it was invisible, and the site simply rendered without it.
  *
@@ -800,7 +800,7 @@ function warnDuplicateSlugs(items, queryName) {
   for (const item of items) {
     if (!item || item.$name === undefined) continue
     const name = String(item.$name)
-    const where = item.path ? `${item.path}/` : ''
+    const where = item[BRANCH_KEY] ? `${item[BRANCH_KEY]}/` : ''
     if (seen.has(name)) {
       console.warn(
         `[query-processor] Query "${queryName}" has more than one record named ` +
@@ -927,11 +927,21 @@ function pickBrief(record, keys) {
     return out
   }
   for (const [key, value] of Object.entries(record)) {
-    if (!key.startsWith('$') && !['slug', 'path', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
+    if (!key.startsWith('$') && !['slug', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
   }
   return out
 }
 
+// What a record's folder entry says about it, as the keys a record is answered with — `$tags`
+// (in the order written) and `$label` — or null when it says nothing.
+function entryKeys(placed) {
+  if (!placed) return null
+  const out = {}
+  if (Array.isArray(placed.tags) && placed.tags.length) out.$tags = [...placed.tags]
+  if (typeof placed.label === 'string' && placed.label) out.$label = placed.label
+  return Object.keys(out).length ? out : null
+}
+
 // A query's records in folder-tree order (`folderTreeOrder`), before anything reads them — so
 // `where`, `sort` (stable) and `limit` start from the order a records service answers in.
 function inFolderOrder(pooled, rank) {
@@ -966,10 +976,17 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // BibTeX → CSL-JSON bibliography items).
   let items = await readPooledRecords(pooled, config, siteDir, recordsRoot, basePath)
 
-  // ⭐ `path` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
+  // ⭐ `$branch` 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.
   //
+  // ⛔ THE COMPILED FILE'S OWN KEY, NOT THE RECORD'S (ruled 2026-09-27 [Diego]): the
+  // browser evaluates `scope` over this file, so the file holds each record's branch, and
+  // no answer carries it — `@uniweb/core`'s `evaluateQuery` reads it and drops it, as a
+  // records service answers no branch. ⛔ Until then it was `path`: it reached every
+  // component, wrote over an authored field named `path`, and made a `[...path]` record's
+  // link `<branch>/<name>`.
+  //
   // ⛔ THIS WAS HARDCODED TO `''` FOR A WHILE, AND THE COMMENT SAID "until the
   // folder producer lands". It landed, and this was not revisited — so every
   // folder slice matched NOTHING on the delivery lane, silently, which is the one
@@ -978,10 +995,20 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   //
   // ⚠️ It stays a SCALAR. `@uniweb/core`'s `withinScope` matches strings only, so
   // an array would match nothing — one placement per record is the ruling.
+  //
+  // ⭐ AND WHAT THE FOLDER SAYS ABOUT THE RECORD — its entry's `tags` and `label` — rides
+  // beside it as `$tags` and `$label`, in its list and in its own file, as a records service
+  // answers them (ruled 2026-09-27 [Diego]). Absent when the entry says none.
   items = items.map((result, i) => {
-    const path = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
-    if (Array.isArray(result)) return result.map((item) => item && { ...item, path })
-    return result && { ...result, path }
+    const placed = pooled[i] ? config.placements?.get(pooled[i].id) : null
+    const said = entryKeys(placed)
+    const at = (item) => {
+      if (!item) return item
+      const out = { ...item, ...said, [BRANCH_KEY]: placed?.path ?? '' }
+      if (said && out[WHOLE_RECORD]) out[WHOLE_RECORD] = { ...out[WHOLE_RECORD], ...said }
+      return out
+    }
+    return Array.isArray(result) ? result.map(at) : at(result)
   })
 
   // Flatten one level: a .bib file contributes its entries individually. Every other
@@ -1053,7 +1080,8 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // since 2026-09-11, could select anything from it.
 
   // ⭐ EACH RECORD'S BRIEF — what its list holds: the brief's fields at the top, beside the record's
-  // own keys and what the build derives (`excerpt`, `image`, `path`). A record of a schema with no
+  // own keys, what the build derives (`excerpt`, `image`), and the branch the list holds for `scope`
+  // (`$branch`, which no answer carries). A record of a schema with no
   // brief, or of one with a single section, is its brief as it is.
   const briefOf = briefBuilder(config.dataSchema)
   if (briefOf) {
@@ -1127,7 +1155,7 @@ 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/folder.yml` only says which folder each sits in (`path`),
+  // is compiled; `records/folder.yml` only says which folder each sits in (`$branch`),
   // 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.
@@ -1347,7 +1375,9 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
       const handle = item.$name
       if (handle === undefined || handle === null || handle === '') continue
       const filename = `${handle}.json`
-      await writeFile(join(recordsDir, filename), JSON.stringify(item[WHOLE_RECORD] ?? item, null, 2))
+      // The record's own file answers it whole, so it holds no branch (the list does, for `scope`).
+      const { [BRANCH_KEY]: _branch, ...own } = item
+      await writeFile(join(recordsDir, filename), JSON.stringify(item[WHOLE_RECORD] ?? own, null, 2))
       written.add(filename)
     }
     const pruned = await pruneOrphanedRecords(dataDir, name, written)

package/src/site/records-config.js

@@ -153,7 +153,7 @@ export async function readRecordsConfig(siteRoot, { dir } = {}) {
  *
  * ⛔ ONE PLACEMENT PER RECORD. Two entries matching one file is a hard error, not
  * a second placement. The wire could carry many-to-many — `folder.js` nests, and
- * a placement is banked by the record it references — but a record's `path` is one string:
+ * a placement is banked by the record it references — but a record's branch is one string:
  * `@uniweb/core`'s `withinScope` matches nothing that is not a string, so a record
  * with two paths would fall outside every `scope:`, silently. The records service
  * evaluates `scope` natively, so widening it is a cross-lane change to agree first,
@@ -164,9 +164,25 @@ export async function readRecordsConfig(siteRoot, { dir } = {}) {
  * @param {object} [opts]
  * @param {string} [opts.dir] - the records directory as written, for messages
  * @returns {{ nodes: Array, placements: Map, errors: string[], warnings: string[] }}
- *   `nodes` is the folder tree — the declared sub-folders in file order, then every
- *   record no sub-folder names; `placements` maps EVERY record's id to its
- *   `{ entity, path, slug }`, `path` being `''` at the top of the folder.
+ *   `nodes` is the folder tree — the declared entries in file order, then every
+ *   record no entry names; `placements` maps EVERY record's id to its
+ *   `{ entity, path, slug, tags?, label? }`, `path` being `''` at the top of the folder.
+ *
+ * ⭐ WHAT THE FOLDER SAYS ABOUT A RECORD — its entry's `tags` and `label` (ruled
+ * 2026-09-27 [Diego]). A record's entry is a path, or `{ path, tags?, label? }`:
+ *
+ *     - folder: team
+ *       records:
+ *         - team/grace.md
+ *         - path: team/ada.md
+ *           tags: [staff, featured]
+ *           label: Ada Lovelace
+ *
+ * They are the ENTRY's, not the record's — a backend keeps them on the folder entry and
+ * answers them beside the record as `$tags` and `$label`, and so does the static lane.
+ * Tags keep the order written. At the top level an entry is allowed only when it says
+ * one of them: a bare path there would claim to place a record the directory already
+ * placed.
  */
 export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
   // The file as the author sees it, for every message below.
@@ -187,7 +203,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     byRelPath.set(e.poolPath, e)
   }
 
-  const place = (entity, pathSegs, where) => {
+  const place = (entity, pathSegs, where, said = null) => {
     const key = entity.id
     const prior = claimedBy.get(key)
     if (prior) {
@@ -200,60 +216,94 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     claimedBy.set(key, where)
     const slug = slugForEntity(entity)
     const path = pathSegs.join('/')
-    placements.set(key, { entity, path, slug })
-    return { kind: 'ref', name: slug, $entityId: key }
+    placements.set(key, { entity, path, slug, ...said })
+    return { kind: 'ref', name: slug, $entityId: key, ...said }
+  }
+
+  // The records one path names — a file, or a pattern's matches — placed where the entry sits.
+  const placePath = (raw, pathSegs, where, said = null) => {
+    const pattern = typeof raw === 'string' ? raw.trim() : ''
+    if (!pattern) {
+      errors.push(`${file}: ${where} ${said ? 'has an empty `path:`' : 'is an empty string'}.`)
+      return []
+    }
+    if (!isPattern(pattern)) {
+      const hit = byRelPath.get(pattern)
+      if (!hit) {
+        errors.push(
+          `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
+            `A path is relative to ${dir}/, extension included.`
+        )
+        return []
+      }
+      const leaf = place(hit, pathSegs, where, said)
+      return leaf ? [leaf] : []
+    }
+    // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `artcle/*.md` is the old
+    // empty-branch defect respelled, and it produced a real, reachable, empty
+    // path with no warning.
+    const matches = [...byRelPath.entries()]
+      .filter(([rel]) => matchEntityPattern(pattern, rel))
+      .map(([, e]) => e)
+    if (matches.length === 0) {
+      errors.push(
+        `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
+          `Check the schema folder name and the extension.`
+      )
+      return []
+    }
+    // Matches sort alphanumerically by filename, numeric-aware — so `1-`, `2-`,
+    // `10-` order as written rather than as strings, and `2025-…` precedes
+    // `2026-…`. Ordering only: the number never leaves the name.
+    matches.sort((a, b) => compareByNumericPrefix(a.slug, b.slug))
+    return matches.map((e) => place(e, pathSegs, where, said)).filter(Boolean)
+  }
+
+  // An entry's `tags` and `label` — text, as YAML may type a tag or a label a number
+  // (`2024`). Tags keep the order written; an empty one is dropped. Null when one is
+  // not text (said).
+  const saidOf = (entry, where) => {
+    const said = {}
+    if (entry.tags !== undefined && entry.tags !== null) {
+      const tags = []
+      for (const tag of Array.isArray(entry.tags) ? entry.tags : [entry.tags]) {
+        if (typeof tag !== 'string' && typeof tag !== 'number') {
+          errors.push(`${file}: ${where} has a tag that is not text: ${JSON.stringify(tag)}. Write each tag as a word.`)
+          return null
+        }
+        const text = String(tag).trim()
+        if (text) tags.push(text)
+      }
+      if (tags.length) said.tags = tags
+    }
+    if (entry.label !== undefined && entry.label !== null) {
+      if (typeof entry.label !== 'string' && typeof entry.label !== 'number') {
+        errors.push(`${file}: ${where} has a \`label:\` that is not text. A label is the entry's display text.`)
+        return null
+      }
+      const label = String(entry.label).trim()
+      if (label) said.label = label
+    }
+    return said
   }
 
   const resolveEntry = (entry, pathSegs, index, trail) => {
     const where = `entry ${trail}[${index}]`
 
     if (typeof entry === 'string') {
-      const pattern = entry.trim()
       // ⛔ A PATH AT THE TOP LEVEL SELECTED RECORDS until 2026-09-21 — it was how a
       // file became one. Every file in the directory is a record now, so the line
       // would claim to choose while choosing nothing: refused, with the reason.
       if (pathSegs.length === 0) {
         errors.push(
-          `${file}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
-            `${dir}/ is a record already — ${file} only sorts records into folders. ` +
+          `${file}: ${where} ("${entry.trim()}") lists records at the top level. Every file in ` +
+            `${dir}/ is a record already — ${file} only sorts records into folders, and says ` +
+            `what a folder knows about a record (\`tags:\`, \`label:\`). ` +
             `Remove the entry, or put it under a \`folder:\`.`
         )
         return []
       }
-      if (!pattern) {
-        errors.push(`${file}: ${where} is an empty string.`)
-        return []
-      }
-      if (!isPattern(pattern)) {
-        const hit = byRelPath.get(pattern)
-        if (!hit) {
-          errors.push(
-            `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
-              `A path is relative to ${dir}/, extension included.`
-          )
-          return []
-        }
-        const leaf = place(hit, pathSegs, where)
-        return leaf ? [leaf] : []
-      }
-      // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `artcle/*.md` is the old
-      // empty-branch defect respelled, and it produced a real, reachable, empty
-      // path with no warning.
-      const matches = [...byRelPath.entries()]
-        .filter(([rel]) => matchEntityPattern(pattern, rel))
-        .map(([, e]) => e)
-      if (matches.length === 0) {
-        errors.push(
-          `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
-            `Check the schema folder name and the extension.`
-        )
-        return []
-      }
-      // Matches sort alphanumerically by filename, numeric-aware — so `1-`, `2-`,
-      // `10-` order as written rather than as strings, and `2025-…` precedes
-      // `2026-…`. Ordering only: the number never leaves the name.
-      matches.sort((a, b) => compareByNumericPrefix(a.slug, b.slug))
-      return matches.map((e) => place(e, pathSegs, where)).filter(Boolean)
+      return placePath(entry, pathSegs, where)
     }
 
     if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
@@ -263,6 +313,30 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       return []
     }
 
+    // ⭐ A RECORD'S ENTRY WITH WHAT THE FOLDER SAYS ABOUT IT — `{ path, tags?, label? }`.
+    if (entry.path !== undefined) {
+      const extra = Object.keys(entry).filter((k) => !['path', 'tags', 'label'].includes(k))
+      if (extra.length) {
+        errors.push(
+          `${file}: ${where} is a record's entry (\`path:\`), which takes \`tags:\` and \`label:\` — ` +
+            `not ${extra.map((k) => `\`${k}:\``).join(', ')}.` +
+            (extra.includes('folder') || extra.includes('records') ? ' A folder is its own entry, `folder:`.' : '')
+        )
+        return []
+      }
+      const said = saidOf(entry, where)
+      if (!said) return []
+      if (pathSegs.length === 0 && !said.tags && !said.label) {
+        errors.push(
+          `${file}: ${where} ("${String(entry.path).trim()}") lists a record at the top level and says ` +
+            `nothing about it. Every file in ${dir}/ sits at the top already — give it \`tags:\` or a ` +
+            `\`label:\`, or remove the entry.`
+        )
+        return []
+      }
+      return placePath(entry.path, pathSegs, where, said)
+    }
+
     if (entry.folder !== undefined) {
       // ⚠️ COERCED, because YAML types a bare `2024` as a NUMBER — and a folder
       // named for a year is the single most likely one anybody writes. Both the
@@ -298,6 +372,13 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       folderAt.set(at, where)
       const branch = { kind: 'branch', name: segment }
       if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
+      // A folder takes `tags:` as a record's entry does — kept, sent and pulled back, though
+      // no question answers a folder.
+      if (entry.tags !== undefined && entry.tags !== null) {
+        const said = saidOf({ tags: entry.tags }, where)
+        if (!said) return []
+        if (said.tags) branch.tags = said.tags
+      }
       const kids = Array.isArray(entry.records) ? entry.records : []
       if (kids.length === 0) {
         warnings.push(
@@ -328,8 +409,8 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     errors.push(
       `${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}/.`)
+          ? `Inside a folder, a path names records — or \`path:\` with its \`tags:\` and \`label:\`; anything else says \`folder:\`.`
+          : `An entry is a \`folder:\` — its \`records:\` are paths under ${dir}/ — or a record's \`path:\` with its \`tags:\` or \`label:\`.`)
     )
     return []
   }

package/src/uwx/folder.js

@@ -7,11 +7,12 @@
 //   - `contents` is the self-nesting tree (an array), nesting via `$children` — the
 //     same mechanism site-content pages/sections use. Each node holds REFERENCES,
 //     never content:
-//       - a LEAF references one record entity: `{ kind: 'ref', name, entry }` —
+//       - a LEAF references one record entity: `{ kind: 'ref', name, entry, label?, tags? }` —
 //         `entry: { schema, entity: <uuid> }` once the record was minted (back-filled
 //         into its file), or `entry: { $ref: "<$id>" }` while brand-new (resolved
-//         within this payload).
-//       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, $children }`.
+//         within this payload); `label` (a localized map) and `tags` are what
+//         `records/folder.yml` says about the record, since 2026-09-27.
+//       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, tags?, $children }`.
 //
 // ⭐ A LEAF'S `name` IS ITS RECORD'S HANDLE — the slug, the records service's `$name` —
 // and a branch's `name` is the segment a query's `scope:` names. `label` is a branch's
@@ -99,6 +100,7 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
       // map, like every localized scalar this producer sends — keyed by the
       // site's source locale.
       if (node.label !== undefined) branch.label = { [sourceLocale]: String(node.label) }
+      if (Array.isArray(node.tags) && node.tags.length) branch.tags = [...node.tags]
       branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale)
       out.push(branch)
       continue
@@ -108,7 +110,13 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
       missing.push(node.$entityId)
       continue
     }
-    out.push(refLeaf(entity))
+    const leaf = refLeaf(entity)
+    // ⭐ What the folder says about the record (`records/folder.yml`, ruled 2026-09-27
+    // [Diego]): its display text, localized as a branch's is, and its tags, in the order
+    // written. A records service answers them beside the record as `$label` and `$tags`.
+    if (node.label !== undefined) leaf.label = { [sourceLocale]: String(node.label) }
+    if (Array.isArray(node.tags) && node.tags.length) leaf.tags = [...node.tags]
+    out.push(leaf)
   }
   return out
 }

package/src/uwx/records-project.js

@@ -493,7 +493,9 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * 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.
+ * of the file removes a record, so this cannot empty anything. ⭐ The one exception,
+ * since 2026-09-27: a record whose entry has `tags` or a `label` is written wherever it
+ * sits, as `{ path, tags?, label? }`, since only `folder.yml` can say them.
  *
  * ⛔ A PULL THAT CARRIED NO FOLDER, or one with a placed record that was not written
  * locally, leaves the file alone: it has nothing true to write.
@@ -524,22 +526,34 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
         // does not caption its rows. On the wire the label is a localized map;
         // folder.yml carries the source-locale string (a bare string passes).
         if (node.label !== undefined) entry.label = unwrapLocalized(node.label, sourceLocale)
+        if (Array.isArray(node.tags) && node.tags.length) entry.tags = node.tags.map(String)
         entry.records = walk(node.$children, true)
         out.push(entry)
         continue
       }
       const uuid = node.entry?.entity ?? node.entry
       const rel = typeof uuid === 'string' ? poolPathByUuid.get(uuid) : null
-      // A record at the top of the folder needs no line — but one that did not land
-      // is still said: the next push sends the folder the directory holds, which
-      // would not have it.
+      // ⭐ What the folder says about the record — its entry's `tags` and `label` — comes
+      // back as the entry `{ path, tags?, label? }` (ruled 2026-09-27 [Diego]).
+      const said = {}
+      if (Array.isArray(node.tags) && node.tags.length) said.tags = node.tags.map(String)
+      if (node.label !== undefined && node.label !== null) {
+        const label = unwrapLocalized(node.label, sourceLocale)
+        if (typeof label === 'string' && label) said.label = label
+      }
+      const says = Object.keys(said).length > 0
+      // A record at the top of the folder needs no line unless the folder says something
+      // about it — but one that did not land is still said: the next push sends the folder
+      // the directory holds, which would not have it.
       if (!inBranch) {
         if (!rel) {
           warnings.push(
             `the folder holds a record ("${node.name ?? '?'}") that was not written locally — ` +
               `a push from here would remove it from the folder.`
           )
+          continue
         }
+        if (says && !out.some((e) => e?.path === rel)) out.push({ path: rel, ...said })
         continue
       }
       if (!rel) {
@@ -554,7 +568,8 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
         continue
       }
       // A list file holds several records and is one path — listed once.
-      if (!out.includes(rel)) out.push(rel)
+      if (out.some((e) => e === rel || e?.path === rel)) continue
+      out.push(says ? { path: rel, ...said } : rel)
     }
     return out
   }

package/src/uwx/records.js

@@ -729,8 +729,13 @@ function placeProducedRecords(nodes, producedBy) {
       out.push({ ...node, $children: placeProducedRecords(node.$children, producedBy) })
       continue
     }
+    // What the folder says about the record — its entry's `tags` and `label` — goes with
+    // every record the file produced.
+    const said = {}
+    if (node?.tags) said.tags = node.tags
+    if (node?.label !== undefined) said.label = node.label
     for (const r of producedBy.get(node?.$entityId) || []) {
-      out.push({ kind: 'ref', name: r.slug, $entityId: r.id })
+      out.push({ kind: 'ref', name: r.slug, $entityId: r.id, ...said })
     }
   }
   return out