@uniweb/build 0.66.0 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.66.0",
+  "version": "0.67.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-writer": "^0.3.4",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/schemas": "^0.8.0",
-    "@uniweb/projections": "^0.7.6",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/projections": "^0.7.7",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/schemas": "^0.8.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.8"
+    "@uniweb/runtime": "^0.27.9"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.8",
-    "@uniweb/core": "^0.32.0"
+    "@uniweb/core": "^0.32.1",
+    "@uniweb/runtime": "^0.27.9"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -16,7 +16,7 @@ import { createHash } from 'node:crypto'
 import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { inferTitle } from './utils/infer-title.js'
+import { describeChildren, describeVisuals } from '@uniweb/schemas/component'
 import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
   composeSupports,
@@ -547,41 +547,35 @@ function hasEntryFile(dirPath, dirName) {
 /**
  * Create an implicit empty meta for a section type discovered without meta.js
  */
-function createImplicitMeta(name) {
-  return { title: inferTitle(name), titleInferred: true }
+function createImplicitMeta() {
+  return {}
 }
 
 /**
- * Build a component entry with title inference applied.
+ * Build a component entry: the `meta.js` default export, plus the build's `name`
+ * and `path`.
  *
- * ⭐ `titleInferred` SAYS THE TITLE IS OURS, NOT THE AUTHOR'S, and without it a
- * consumer cannot tell. We fill `title` from the component name whenever
- * `meta.js` declares none, so `title` is ALWAYS present — which means an editor
- * showing section names has no way to know that `"Hero"` is a string the build
- * invented rather than one a developer chose.
+ * ⭐ `title` IS THERE ONLY WHEN THE DEVELOPER WROTE ONE, so its absence says the
+ * component is unnamed. That difference decides whether a name can be translated:
+ * an authored title is the foundation's own words and is shown verbatim in every UI
+ * language, while for an unnamed component a consumer has better strings — its
+ * `family`'s translated label, else `inferTitle(name)` from `@uniweb/schemas/component`,
+ * the words this build used to write in.
  *
- * ⛔ THAT DIFFERENCE DECIDES WHETHER THE NAME CAN BE TRANSLATED. An authored
- * title is the foundation's own words and must be shown verbatim in every UI
- * language. An inferred one is a placeholder, and a consumer that knows the
- * section's `family` has a better string available — one it can localize. A
- * foundation that never named its Hero would otherwise ship the English
- * `"Hero"` to every author in the world.
- *
- * ⚖️ The build itself reads neither field. This is a statement ABOUT the title,
- * for whoever renders it.
+ * ⛔ Until 2026-09-27 the build filled `title` from the name whenever `meta.js`
+ * declared none, and added `titleInferred: true` to restore the fact the filling-in
+ * erased. Consumers derive the title where they use it instead [Diego, 2026-09-27].
  */
 function buildComponentEntry(name, relativePath, meta) {
-  const entry = {
+  // ⭐ `name` and `path` are the build's facts, so they are set AFTER the spread: a
+  // `meta.js` declaring either cannot change them. ⛔ Until 2026-09-27 they came first,
+  // and a `meta.js` `name` became the entry's `name` — which an editor reads as the
+  // section type — while the schema stayed keyed by the folder's name.
+  return {
+    ...meta,
     name,
     path: relativePath,
-    ...meta,
-  }
-  // Apply title inference if meta has no explicit title
-  if (!entry.title) {
-    entry.title = inferTitle(name)
-    entry.titleInferred = true
   }
-  return entry
 }
 
 /**
@@ -637,7 +631,7 @@ async function discoverSectionsInPath(srcDir, sectionsRelPath) {
     const name = basename(entry.name, ext)
     if (!isComponentFileName(name)) continue
 
-    const meta = createImplicitMeta(name)
+    const meta = createImplicitMeta()
     components[name] = {
       ...buildComponentEntry(name, sectionsRelPath, meta),
       // Bare file: the entry file IS the file itself (not inside a subdirectory)
@@ -662,7 +656,7 @@ async function discoverSectionsInPath(srcDir, sectionsRelPath) {
         components[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
       } else if (hasEntryFile(dirPath, entry.name)) {
         // No meta.js but has entry file — implicit section type at root
-        components[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta(entry.name))
+        components[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta())
       }
     }
 
@@ -730,7 +724,7 @@ export async function discoverLayoutsInPath(srcDir, layoutsRelPath = LAYOUTS_PAT
     const name = basename(entry.name, ext)
     if (!isLayoutName(name)) continue
 
-    const meta = createImplicitMeta(name)
+    const meta = createImplicitMeta()
     layouts[name] = {
       ...buildComponentEntry(name, layoutsRelPath, meta),
       entryFile: entry.name,
@@ -750,7 +744,7 @@ export async function discoverLayoutsInPath(srcDir, layoutsRelPath = LAYOUTS_PAT
       if (result.meta.hidden) continue
       layouts[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
     } else if (hasEntryFile(dirPath, entry.name)) {
-      layouts[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta(entry.name))
+      layouts[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta())
     }
   }
 
@@ -936,6 +930,45 @@ function reportSupports(srcDir, authored, derived, emitted) {
   }
 }
 
+/**
+ * Warn about `children` and `visuals` declarations an editor cannot use — read with
+ * `@uniweb/schemas`, the grammar the editor reads them with. The entry is emitted as
+ * written either way; these are warnings, never refusals.
+ *
+ * ⭐ A `children.types` entry must name one of this foundation's section types. A hidden
+ * one is not a section type at all, and a child of a type nothing provides renders
+ * "Component not found". The one false alarm is a type an extension provides, which
+ * this foundation cannot see — the message says so.
+ *
+ * @param {Object} components - discovered section types, by name
+ */
+export function reportPlacementDeclarations(components) {
+  for (const [name, entry] of Object.entries(components)) {
+    const children = describeChildren(entry)
+    const visuals = describeVisuals(entry)
+    for (const problem of [...children.problems, ...visuals.problems]) {
+      console.warn(`Warning: ${name} (meta.js): ${problem}`)
+    }
+    for (const type of children.types || []) {
+      if (components[type]) continue
+      console.warn(
+        `Warning: ${name} (meta.js): children.types names "${type}", which is not a section type of this ` +
+          `foundation — hidden, misspelled, or provided by an extension. A child section of a type nothing ` +
+          `provides renders "Component not found".`
+      )
+    }
+    // `grid` is a section key framework reserves for the layout of a section's children,
+    // so a param by that name never receives what an author writes as `grid:`.
+    if (entry.params && typeof entry.params === 'object' && Object.hasOwn(entry.params, 'grid')) {
+      console.warn(
+        `Warning: ${name} (meta.js): a param named "grid" never receives the author's grid: — it is a section ` +
+          `key reserved for the layout of child sections. Offer layouts with children: { grid: [...] } and ` +
+          `lay the children out with kit's ChildGrid, or rename the param.`
+      )
+    }
+  }
+}
+
 /**
  * Build complete schema for a foundation
  * Returns { _self: { identity + config }, ComponentName: componentMeta, ... }
@@ -959,6 +992,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Discover section types
   const components = await discoverComponents(srcDir, sectionPaths)
+  reportPlacementDeclarations(components)
 
   // Resolve the data schemas the foundation DEFINES — every file in its `schemas/`
   // folder (`ownSchemaRefs`) — and the ones its section bindings reference, carried

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

@@ -60,8 +60,8 @@ import {
  *
  *     ⇒ The rule stands on its own: we do not know which consumers
  *     re-derive, so we always ship enough for the ones that do.
- *   - `data/<collection>.json` (+ per-record files for `deferred:`
- *     collections) — same shape `processQueries` produces today.
+ *   - `data/<collection>.json` (+ each record's own file,
+ *     `data/<collection>/<$name>.json`) — same shape `processQueries` produces today.
  *   - `records/<path under the records directory>` — the records' co-located assets, where
  *     the compiled records point.
  *   - `assets/<media>` — processed images / video posters / PDF

package/src/site/content-collector.js

@@ -39,6 +39,7 @@ import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig, pageRouteQuery, currentFor } from '@uniweb/core'
 import { parseFrontmatter } from '../utils/frontmatter.js'
+import { parseGrid } from '@uniweb/schemas/grid'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -456,60 +457,6 @@ async function readYamlFile(filePath) {
   }
 }
 
-/**
- * Extract inset references from a ProseMirror document.
- *
- * Walks the document recursively for `inset_ref` nodes (produced by
- * content-reader for the `![alt](@ComponentName){params}` /
- * `[text](@ComponentName){params}` / `[@key]{params}` forms). Each ref
- * is removed and replaced in-place with an `inset_placeholder` node
- * carrying a unique refId. The extracted refs are returned as an array.
- *
- * Inline insets (mid-paragraph) are kept as inline placeholders so the
- * paragraph's text flow is preserved; block-level insets (own line)
- * stay at the document root. Both share the same refId/getInset(refId)
- * lookup machinery — only the position differs.
- *
- * @param {Object} doc - ProseMirror document (mutated in place)
- * @returns {Array} Array of { refId, type, params, description, embedKind }
- */
-function extractInsets(doc) {
-  if (!doc?.content || !Array.isArray(doc.content)) return []
-
-  const insets = []
-  let refIndex = 0
-
-  function visit(nodes) {
-    if (!Array.isArray(nodes)) return
-    for (let i = 0; i < nodes.length; i++) {
-      const node = nodes[i]
-      if (!node) continue
-      if (node.type === 'inset_ref') {
-        const { component, alt, embedKind, ...params } = node.attrs || {}
-        const refId = `inset_${refIndex++}`
-        insets.push({
-          refId,
-          type: component,
-          embedKind: embedKind || 'visual',
-          params: Object.keys(params).length > 0 ? params : {},
-          title: alt || null,
-        })
-        nodes[i] = {
-          type: 'inset_placeholder',
-          attrs: { refId, embedKind: embedKind || 'visual' },
-        }
-        continue
-      }
-      if (Array.isArray(node.content)) {
-        visit(node.content)
-      }
-    }
-  }
-
-  visit(doc.content)
-  return insets
-}
-
 /**
  * Check if a filename uses the @ prefix (child section convention).
  * @-prefixed files are excluded from auto-discovered top-level sections —
@@ -1064,14 +1011,27 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
 
   // `query`, `fetch` and `data` are never params: `query:` / `fetch:` declare the
   // section's own data, and a leftover `data:` is refused (`declaredFetch`).
-  const { type, preset, input, props, fetch, query, data, id: frontmatterId, ...params } = frontMatter
+  // ⭐ Nor is `grid`: a section key framework reserves for the layout of the section's
+  // child sections — `3` or `'40/60'` [Diego, 2026-09-27] — laid out by kit's
+  // `ChildGrid` from `block.grid`. A component offers layouts in `meta.js`
+  // `children.grid`; it never receives the choice as a param.
+  const { type, preset, input, props, fetch, query, data, grid, id: frontmatterId, ...params } = frontMatter
+  if (grid !== undefined && !parseGrid(grid)) {
+    console.warn(
+      `[content-collector] ${relative(siteRoot, filePath)}: grid: ${JSON.stringify(grid)} is not a layout — ` +
+        `write a column count (grid: 3) or relative widths (grid: '40/60'). The component's own layout applies.`
+    )
+  }
 
-  // Convert markdown to ProseMirror
+  // Convert markdown to ProseMirror. ⭐ Insets stay as the author wrote them —
+  // `inset_ref`, `inset_block` — and `@uniweb/core` lifts both when it builds the
+  // section's Block. ⛔ Until 2026-09-27 this extracted each leaf `inset_ref` into a
+  // section-level `insets[]` and left a placeholder, so any document that did not
+  // come through here (a free-form translation, a record body) kept raw references
+  // nothing resolved, and the same section's content differed between a build and a
+  // document stored as written.
   const proseMirrorContent = markdownToProseMirror(markdown)
 
-  // Extract @ component references → insets (mutates doc)
-  const insets = extractInsets(proseMirrorContent)
-
   // `query: team` → `fetch: { query: team }`; a list, one config per name, each under
   // its own `as` — the one helper every level uses. Unrelated to a section type's
   // `meta.js` `data:`, which declares the `content.data` keys a component receives and
@@ -1092,7 +1052,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     params: { ...params, ...props },
     content: proseMirrorContent,
     fetch: parseFetchConfig(resolvedFetch, relative(siteRoot, filePath), { level: 'section' }),
-    ...(insets.length > 0 ? { insets } : {}),
+    ...(grid !== undefined ? { grid } : {}),
     subsections: []
   }
 
@@ -2994,7 +2954,6 @@ export {
   parseWildcardArray,
   applyWildcardOrder,
   getDirectChildName,
-  extractInsets,
   readYamlFile,
   readFolderConfig,
   isMarkdownFile,

package/src/site/plugin.js

@@ -1335,8 +1335,8 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Handle localized collection data (e.g., /fr/data/articles.json), and a
-        // `deferred:` query's per-record files (/fr/data/articles/<slug>.json) — one
-        // record each, translated the same way.
+        // query's per-record files (/fr/data/articles/<$name>.json) — one record
+        // each, translated the same way.
         const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/${DATA_DIR}\\/(.+\\.json)$`))
         if (localeDataMatch) {
           const locale = localeDataMatch[1]

package/src/site/query-processor.js

@@ -932,6 +932,16 @@ function pickBrief(record, keys) {
   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) {
@@ -985,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 branch = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
-    if (Array.isArray(result)) return result.map((item) => item && { ...item, [BRANCH_KEY]: branch })
-    return result && { ...result, [BRANCH_KEY]: branch }
+    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

package/src/site/records-config.js

@@ -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/site/schemaless-data.js

@@ -6,8 +6,8 @@
  * that resolves a data schema syncs as folder entities — content a backend
  * genuinely consumes, queryable, editable, with a `brief:` for its lean shape.
  * A **schema-less** collection has no entity model, so its compiled
- * `dist/data/<name>.json` (plus any `deferred:` per-record files) is delivered
- * as files instead. That fallback tier is all this module is about.
+ * `dist/data/<name>.json` (plus its per-record files, `<name>/<$name>.json`) is
+ * delivered as files instead. That fallback tier is all this module is about.
  *
  *   { data: { "<relpath under dist/data>": <json> } }   // schema-less only
  *
@@ -67,7 +67,8 @@ function queryOf(relPath) {
 }
 
 /**
- * Assemble the static-data ball from a built site's dist/.
+ * Gather the schema-less set from a built site's dist/ — in memory, one entry per
+ * file; nothing is bundled (see the header).
  *
  * @param {string} distDir - the site's built dist/ directory
  * @param {string[]} [schemalessNames] - collection names with no data schema (from

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

package/src/uwx/site-project.js

@@ -428,8 +428,9 @@ function reinlineInsets(content, insets) {
  * `preset` / `input` / `fetch` / `id` (`stable_id`); the body is the section's
  * content (insets re-inlined) serialized to markdown. Idempotent.
  *
- * Note: `$children` (the `@`-nested child sections) are NOT written here — the
- * page walk places them as `@`-files plus a `nest:` map. This writes one section.
+ * Note: `$children` (a section's child sections) are NOT written here — the page
+ * walk (`pageSectionsToFiles`) writes each to its own file and nests it under its
+ * parent in `page.yml::sections:`, in stored order. This writes one section.
  *
  * @param {object} params
  * @param {string} params.filePath

package/src/uwx/site.js

@@ -312,11 +312,20 @@ function mapSectionData(section) {
   setIf(data, 'preset', section.preset ?? undefined)
   setIf(data, 'input', section.input ?? undefined)
   if (Object.keys(params).length > 0) data.params = params
-  data.content = section.content
-  if (section.insets && section.insets.length > 0) data.insets = section.insets
+  data.content = section.content // leaf insets in it as written — no `insets` field since 2026-09-27
   setIf(data, 'fetch', section.fetch ?? undefined)
   setIf(data, 'background', background)
   setIf(data, 'theme_override', themeOverride)
+  // ⛔ `grid` — the section's layout for its children — is NOT SENT YET: it is a new
+  // field, and the store refuses a whole push carrying a key it has not declared
+  // (kb/framework/build/uwx-format.md § A page section's fields). It goes on the wire
+  // once backend declares it; until then a static build renders it and the file keeps it.
+  if (section.grid !== undefined) {
+    console.warn(
+      `[uwx] section ${section.stableId ?? section.id}: grid: ${JSON.stringify(section.grid)} is not sent — ` +
+        `the backend does not store a section's grid yet. It renders on a static build; the file keeps it.`
+    )
+  }
   return data
 }
 

package/src/utils/infer-title.js

@@ -1,16 +0,0 @@
-/**
- * Infer display title from PascalCase component name.
- *
- * TeamRoster → "Team Roster"
- * CTA → "CTA"
- * FAQSection → "FAQ Section"
- * Hero → "Hero"
- *
- * @param {string} name - PascalCase component name
- * @returns {string} Human-readable title
- */
-export function inferTitle(name) {
-  return name
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-}