@uniweb/build 0.15.14 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.15.14",
+  "version": "0.16.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,13 +59,14 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/projections": "0.1.6",
+    "@uniweb/projections": "0.2.1",
     "@uniweb/theming": "0.1.15",
-    "@uniweb/content-writer": "0.2.9"
+    "@uniweb/content-writer": "0.3.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.8.42",
-    "@uniweb/content-reader": "1.1.19",
+    "@uniweb/content-reader": "1.2.0",
+    "@uniweb/semantic-parser": "1.2.0",
+    "@uniweb/runtime": "0.9.0",
     "@uniweb/schemas": "0.2.4"
   },
   "peerDependencies": {
@@ -75,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.34"
+    "@uniweb/core": "0.8.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/collections.js

@@ -14,51 +14,23 @@ import { readFile, writeFile, readdir, mkdir } from 'fs/promises'
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { pathToFileURL } from 'url'
+import { DATA_DIR } from '@uniweb/core'
 import { computeHash } from './hash.js'
 import { loadFreeformCollectionItem } from './freeform.js'
+// The heuristic judgement about which strings inside structured data are prose.
+// It lives in its own module because the page lane needs exactly the same
+// answer for a tagged data block's payload — a `label` is prose and an `href`
+// is not, wherever the value came from. Moved rather than copied: two tuned
+// denylists would drift, and drift here is silent.
+import {
+  NON_TRANSLATABLE_TYPES,
+  HEURISTIC_SKIP_FIELDS,
+  MAX_HEURISTIC_DEPTH,
+  isStructuralString,
+} from './data-strings.js'
 
 export const COLLECTIONS_DIR = 'collections'
 
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Types that are never translatable regardless of schema */
-const NON_TRANSLATABLE_TYPES = new Set([
-  'number', 'boolean', 'date', 'datetime', 'url', 'email', 'image'
-])
-
-/** Field names skipped by the heuristic extractor (structural, not human-readable) */
-const HEURISTIC_SKIP_FIELDS = new Set([
-  'slug', 'id', 'type', 'status', 'href', 'url', 'src', 'icon',
-  'target', 'email', 'phone', 'orcid', 'doi', 'arxiv', 'isbn',
-  'pmid', 'bibtex', 'pdf', 'code', 'data', 'slides', 'video',
-  'repository', 'caseStudy', 'website', 'avatar', 'image',
-  'thumbnail', 'currency', 'order', 'hidden', 'current',
-  'featured', 'published', 'allDay', 'remote', 'hybrid',
-  'noindex', 'corresponding', 'required', 'virtual',
-  'lastModified', 'date', 'updated', 'posted', 'submitted',
-  'accepted', 'startDate', 'endDate', 'deadline',
-  'readTime', 'citations', 'capacity', 'volume', 'issue', 'pages',
-  'time', 'timezone',
-])
-
-/** String patterns that indicate non-translatable values */
-const HEURISTIC_SKIP_PATTERNS = [
-  /^https?:\/\//,                  // URLs
-  /^mailto:/,                      // mailto links
-  /^[^\s@]+@[^\s@]+\.[^\s@]+$/,   // email addresses
-  /^\d{4}-\d{2}-\d{2}/,           // ISO dates
-  /^#[0-9a-fA-F]{3,8}$/,          // hex colors
-  /^[\w./\\-]+\.\w{2,4}$/,        // file paths (e.g., ./logo.svg, /img/hero.jpg)
-  /^[A-Z]{3}$/,                   // currency codes (USD, EUR)
-  /^\d+(\.\d+)?$/,                // plain numbers as strings
-  /^\d{1,2}:\d{2}(:\d{2})?$/,    // times (09:00, 14:30:00)
-]
-
-/** Max recursion depth for heuristic extraction */
-const MAX_HEURISTIC_DEPTH = 5
-
 // ---------------------------------------------------------------------------
 // Schema resolution
 // ---------------------------------------------------------------------------
@@ -85,8 +57,14 @@ async function resolveSchema(collectionName, siteRoot) {
 
   let schema = null
 
-  // 1. Companion schema file
-  const companionPath = join(siteRoot, 'public', 'data', `${collectionName}.schema.js`)
+  // 1. Companion schema file, beside the collection it describes.
+  //
+  // This used to be looked up in `public/<DATA_DIR>/` — next to the compiled
+  // output rather than the source. That directory is the build's, and asking
+  // an author to write into it was the one remaining place the framework
+  // contradicted its own rule that `collections/` is the only way to provide
+  // structured data. The schema describes the source, so it lives with it.
+  const companionPath = join(siteRoot, 'collections', `${collectionName}.schema.js`)
   if (existsSync(companionPath)) {
     try {
       const mod = await import(pathToFileURL(companionPath).href)
@@ -290,13 +268,6 @@ function extractFromItemHeuristic(data, pathPrefix, context, units, depth) {
   }
 }
 
-/**
- * Check if a string value looks structural (not human-readable).
- */
-function isStructuralString(value) {
-  return HEURISTIC_SKIP_PATTERNS.some(pattern => pattern.test(value))
-}
-
 // ---------------------------------------------------------------------------
 // Schema-guided translation
 // ---------------------------------------------------------------------------
@@ -412,7 +383,7 @@ function translateItemHeuristic(data, context, translations, depth) {
  * @returns {Promise<Object>} Manifest with translation units
  */
 export async function extractCollectionContent(siteRoot, options = {}) {
-  const dataDir = join(siteRoot, 'public', 'data')
+  const dataDir = join(siteRoot, 'public', DATA_DIR)
 
   if (!existsSync(dataDir)) {
     return { version: '1.0', units: {} }
@@ -577,7 +548,7 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
     freeformEnabled = true
   } = options
 
-  const dataDir = join(siteRoot, 'public', 'data')
+  const dataDir = join(siteRoot, 'public', DATA_DIR)
 
   if (!existsSync(dataDir)) {
     return {}
@@ -615,7 +586,7 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
     const hasFreeform = freeformEnabled && existsSync(freeformDir)
 
     // Create locale data directory
-    const localeDataDir = join(outputDir, locale, 'data')
+    const localeDataDir = join(outputDir, locale, DATA_DIR)
     await mkdir(localeDataDir, { recursive: true })
 
     outputs[locale] = {}

package/src/i18n/data-strings.js

@@ -0,0 +1,114 @@
+/**
+ * Which strings inside STRUCTURED DATA are human-readable prose.
+ *
+ * A tagged data block (```yaml:nav, ```json:pricing) carries an arbitrary shape,
+ * so there is no element to key a translation unit to — only a tree of values,
+ * most of which are machinery. A nav's `label` is prose; its `href` and `icon`
+ * are not. Guessing wrong in one direction leaves a site half-translated; in the
+ * other it rewrites a URL into another language and breaks the link.
+ *
+ * The judgement was already made and tuned for collections, which have exactly
+ * this problem. This module is that judgement, moved somewhere both lanes can
+ * reach rather than copied — the copy is how the two would drift, and the whole
+ * point is that a `label` means the same thing in a collection record and in a
+ * data block.
+ *
+ * An ALLOWLIST of shapes is impossible here (the data is author-defined), so
+ * this is necessarily a denylist, and it is deliberately conservative: a missed
+ * skip shows up as a translatable string an author can leave alone, while a
+ * missed field shows up as untranslated content nobody notices.
+ */
+
+/** Types that are never translatable regardless of schema. */
+export const NON_TRANSLATABLE_TYPES = new Set([
+  'number', 'boolean', 'date', 'datetime', 'url', 'email', 'image'
+])
+
+/** Field names skipped by the heuristic extractor (structural, not human-readable). */
+export const HEURISTIC_SKIP_FIELDS = new Set([
+  'slug', 'id', 'type', 'status', 'href', 'url', 'src', 'icon',
+  'target', 'email', 'phone', 'orcid', 'doi', 'arxiv', 'isbn',
+  'pmid', 'bibtex', 'pdf', 'code', 'data', 'slides', 'video',
+  'repository', 'caseStudy', 'website', 'avatar', 'image',
+  'thumbnail', 'currency', 'order', 'hidden', 'current',
+  'featured', 'published', 'allDay', 'remote', 'hybrid',
+  'noindex', 'corresponding', 'required', 'virtual',
+  'lastModified', 'date', 'updated', 'posted', 'submitted',
+  'accepted', 'startDate', 'endDate', 'deadline',
+  'readTime', 'citations', 'capacity', 'volume', 'issue', 'pages',
+  'time', 'timezone',
+])
+
+/** String patterns that indicate non-translatable values. */
+export const HEURISTIC_SKIP_PATTERNS = [
+  /^https?:\/\//,                  // URLs
+  /^mailto:/,                      // mailto links
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/,   // email addresses
+  /^\d{4}-\d{2}-\d{2}/,           // ISO dates
+  /^#[0-9a-fA-F]{3,8}$/,          // hex colors
+  /^[\w./\\-]+\.\w{2,4}$/,        // file paths (e.g., ./logo.svg, /img/hero.jpg)
+  /^[A-Z]{3}$/,                   // currency codes (USD, EUR)
+  /^\d+(\.\d+)?$/,                // plain numbers as strings
+  /^\d{1,2}:\d{2}(:\d{2})?$/,    // times (09:00, 14:30:00)
+]
+
+/** Max recursion depth for heuristic extraction. */
+export const MAX_HEURISTIC_DEPTH = 5
+
+/** Whether a string value looks structural rather than human-readable. */
+export function isStructuralString(value) {
+  return HEURISTIC_SKIP_PATTERNS.some((pattern) => pattern.test(value))
+}
+
+/**
+ * Walk structured data and hand every translatable-looking STRING to `visit`.
+ *
+ * One walker for both directions, the same discipline the document walk uses:
+ * extraction returns nothing and collects, application returns a replacement and
+ * the walker writes it back. Two copies of a rule this fiddly is how the
+ * extracted set and the applied set end up different, which fails as content
+ * that appears in the manifest, gets translated by a human, and still renders in
+ * the source language.
+ *
+ * Mutates `data` in place when `visit` returns a different string, so callers
+ * that must not mutate should pass a clone.
+ *
+ * @param {*} data - any parsed YAML/JSON value
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {string} [path] - dotted path, for the unit's `field` metadata
+ * @param {number} [depth]
+ */
+export function visitDataStrings(data, visit, path = '', depth = 0) {
+  if (!data || typeof data !== 'object' || depth > MAX_HEURISTIC_DEPTH) return
+
+  const isArray = Array.isArray(data)
+  const keys = isArray ? data.map((_, i) => i) : Object.keys(data)
+
+  for (const key of keys) {
+    const value = data[key]
+    if (value === undefined || value === null) continue
+
+    const fieldPath = isArray
+      ? `${path}[${key}]`
+      : path
+        ? `${path}.${key}`
+        : String(key)
+
+    if (typeof value === 'string') {
+      // A skip-list entry applies to a NAMED field. Inside an array the key is
+      // an index and carries no meaning, so only the value patterns apply —
+      // otherwise a list of prose strings would be skipped by position.
+      if (!isArray && HEURISTIC_SKIP_FIELDS.has(key)) continue
+      if (isStructuralString(value)) continue
+      if (!value.trim()) continue
+
+      const replacement = visit(value, fieldPath)
+      if (typeof replacement === 'string' && replacement !== value) {
+        data[key] = replacement
+      }
+    } else if (typeof value === 'object') {
+      visitDataStrings(value, visit, fieldPath, depth + 1)
+    }
+    // numbers and booleans are never prose
+  }
+}

package/src/i18n/extract.js

@@ -7,6 +7,7 @@
 
 import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
+import { visitDataStrings } from './data-strings.js'
 
 /**
  * Extract all translatable units from site content
@@ -130,6 +131,7 @@ function extractFromSection(section, pageRoute, units) {
 
   if (section.content?.type === 'doc') {
     extractFromProseMirrorDoc(section.content, context, units)
+    extractFromDataBlocks(section.content, context, units)
   }
 
   // Recursively process subsections
@@ -138,6 +140,61 @@ function extractFromSection(section, pageRoute, units) {
   }
 }
 
+/**
+ * Extract the human-readable strings inside a section's TAGGED DATA BLOCKS.
+ *
+ * A ```yaml:nav block's link labels, a ```yaml:pricing block's plan names — the
+ * strings an author most expects to see translated, and which stayed in the
+ * source language on every multilingual site until 2026-07-30 because nothing
+ * in this file mentioned `dataBlock`.
+ *
+ * Which strings count is not this file's judgement to make: it is the same
+ * question collections answer for a record's fields, so the same detection runs
+ * here (`data-strings.js`).
+ *
+ * DELIBERATELY SEPARATE from `extractFromProseMirrorDoc`, and not folded into
+ * it. That function is also `extractUnitsFromDoc`, which publishes the
+ * structural-keying contract pinned by tests/i18n/structural-keying-vectors.json
+ * — units keyed by a BLOCK ELEMENT's text. A data string is not a block
+ * element's text and has no place in that map. The consequence is real rather
+ * than tidy: `deriveStructuralMap` recovers a pulled translation by walking
+ * block elements, so a data string translated on the sync wire would be
+ * invisible to it — neither captured in the map nor counted as divergence — and
+ * would be silently lost on the next pull. So this lane is the BUILD lane only
+ * (the manifest, and `dist/{locale}/`), which is where the reported bug lives.
+ * Carrying data-block translations across the sync wire needs a representation
+ * that contract does not have yet.
+ */
+function extractFromDataBlocks(doc, context, units) {
+  for (const node of dataBlockNodes(doc)) {
+    const { tag, data } = node.attrs || {}
+    if (!tag || !data || typeof data !== 'object') continue
+
+    visitDataStrings(data, (value, fieldPath) => {
+      addUnit(units, value, `data.${tag}.${fieldPath}`, context)
+    })
+  }
+}
+
+/**
+ * Every tagged data block in a doc, including any nested inside a container.
+ */
+function dataBlockNodes(doc) {
+  const out = []
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue
+      if (node.type === 'dataBlock') out.push(node)
+      else if (CONTAINER_BLOCKS.has(node.type)) walk(node.content)
+      else if (node.type === 'bulletList' || node.type === 'orderedList') {
+        for (const listItem of node.content || []) walk(listItem.content)
+      }
+    }
+  }
+  walk(doc?.content)
+  return out
+}
+
 /**
  * Extract translatable strings from ProseMirror document
  * @param {Object} doc - ProseMirror document
@@ -165,28 +222,103 @@ function extractFromProseMirrorDoc(doc, context, units) {
   let headingIndex = { h1: 0, h2: 0, h3: 0, h4: 0 }
   let paragraphIndex = 0
 
-  for (const node of doc.content) {
+  visitTranslatableBlocks(doc.content, (node, listIndex) => {
     if (node.type === 'heading') {
       const text = elementText(node)
-      if (!text) continue
+      if (!text) return
 
       const level = node.attrs?.level || 1
       const field = getHeadingField(level, headingIndex)
       headingIndex[`h${level}`]++
 
       addUnit(units, text, field, context)
-    } else if (node.type === 'paragraph') {
-      // Whole-element keying: ONE unit per paragraph, with link text kept INLINE
-      // (not split into a separate link.label unit). The conformance gate is
-      // tests/i18n/structural-keying-vectors.json (vectors A–H).
-      const text = elementText(node)
-      if (text) {
-        const field = paragraphIndex === 0 ? 'paragraph' : `paragraph.${paragraphIndex}`
-        addUnit(units, text, field, context)
-        paragraphIndex++
-      }
+      return
+    }
+
+    // Whole-element keying: ONE unit per paragraph, with link text kept INLINE
+    // (not split into a separate link.label unit). The conformance gate is
+    // tests/i18n/structural-keying-vectors.json.
+    const text = elementText(node)
+    if (!text) return
+
+    if (listIndex !== null) {
+      addUnit(units, text, `list.${listIndex}`, context)
+      return
+    }
+
+    const field = paragraphIndex === 0 ? 'paragraph' : `paragraph.${paragraphIndex}`
+    addUnit(units, text, field, context)
+    paragraphIndex++
+  })
+}
+
+/**
+ * Block node types whose children carry translatable prose, so the walk has to
+ * descend into them.
+ *
+ * WHY THIS EXISTS. The walk used to handle four node types and recurse into
+ * nothing, so a string inside ANY container was invisible to translation: a
+ * callout's body, a table cell, a blockquote. On a multilingual site those
+ * silently stayed in the source language, and nothing reported it. That
+ * predates concept blocks — adding one more prose container without fixing the
+ * walk would have inherited the hole in the place it hurts most, since a
+ * concept block is prose, which is the thing translation exists for.
+ *
+ * An explicit set rather than "recurse into anything with content", because the
+ * denylist version is the dangerous one: `codeBlock` also has content, and
+ * extracting source code as translatable prose would be worse than missing it.
+ *
+ * KEEP IN SYNC with the editor's own container list. It maintains a second
+ * implementation of this walk over the same documents and already recursed
+ * containers when this one did not, so the two disagreed — the shared vectors
+ * in tests/i18n/structural-keying-vectors.json are the only thing pinning them
+ * together, and they are kept in step by hand.
+ */
+export const CONTAINER_BLOCKS = new Set([
+  'concept_block', // ```md:<tag> — a concept's body is authored prose
+  'inset_block', // ```@Component{params} — a callout's body is authored prose
+  'blockquote',
+  'table',
+  'tableRow',
+  'tableCell',
+])
+
+/**
+ * Walk a content array and hand every translatable BLOCK element to `visit`, in
+ * document order, descending into containers.
+ *
+ * ONE walker with two consumers, deliberately. Extraction (into the manifest)
+ * and resolution (applying a translation) used to be two separate walks over
+ * the same four node types. Two copies of one rule is the shape that fails
+ * halfway: teach only the extractor about a container and its strings reach the
+ * manifest but are never applied; teach only the resolver and there is nothing
+ * to apply. Neither half fails loudly. They cannot drift now because there is
+ * only one of them.
+ *
+ * @param {Array} nodes - a content array
+ * @param {(node: Object, listIndex: number|null) => void} visit
+ */
+function visitTranslatableBlocks(nodes, visit) {
+  for (const node of nodes || []) {
+    if (!node) continue
+
+    if (node.type === 'heading' || node.type === 'paragraph') {
+      visit(node, null)
     } else if (node.type === 'bulletList' || node.type === 'orderedList') {
-      extractFromList(node, context, units)
+      // A list item's index is part of its unit's field name, so lists keep
+      // their own branch rather than folding into the container recursion.
+      ;(node.content || []).forEach((listItem, index) => {
+        if (listItem.type !== 'listItem') return
+        for (const child of listItem.content || []) {
+          if (child.type === 'paragraph') {
+            visit(child, index)
+          } else if (CONTAINER_BLOCKS.has(child.type)) {
+            visitTranslatableBlocks([child], visit)
+          }
+        }
+      })
+    } else if (CONTAINER_BLOCKS.has(node.type)) {
+      visitTranslatableBlocks(node.content, visit)
     }
   }
 }
@@ -203,27 +335,6 @@ function getHeadingField(level, index) {
   return `heading.h${level}.${index[`h${level}`]}`
 }
 
-/**
- * Extract from list items — one whole-element unit per list item (link text
- * stays inline, same rule as paragraphs; vectors G and H).
- */
-function extractFromList(listNode, context, units) {
-  if (!listNode.content) return
-
-  listNode.content.forEach((listItem, index) => {
-    if (listItem.type === 'listItem' && listItem.content) {
-      for (const child of listItem.content) {
-        if (child.type === 'paragraph') {
-          const text = elementText(child)
-          if (text) {
-            addUnit(units, text, `list.${index}`, context)
-          }
-        }
-      }
-    }
-  })
-}
-
 /**
  * A block element's cleaned source text — the WHOLE-ELEMENT translation key.
  * ALL inline marks (bold, italic, link, span, …) flatten into the text: link
@@ -259,27 +370,14 @@ function collectInlineText(node) {
 
 /**
  * The translatable block elements of a content doc, in document order, with the
- * SAME coverage as extraction above (headings, paragraphs, and each list item's
- * paragraphs). Shared by the merge resolver (push) and the pull-side
- * structural-map derivation so all paths walk identically and keys never drift.
- * Returns the element nodes themselves — callers read `.type`/`.content` and key
- * them via elementText.
+ * SAME coverage as extraction above — because it is the same walk. Shared by the
+ * merge resolver (push) and the pull-side structural-map derivation so all paths
+ * walk identically and keys never drift. Returns the element nodes themselves —
+ * callers read `.type`/`.content` and key them via elementText.
  */
 export function blockElements(doc) {
   const out = []
-  for (const node of doc?.content || []) {
-    if (node.type === 'heading' || node.type === 'paragraph') {
-      out.push(node)
-    } else if (node.type === 'bulletList' || node.type === 'orderedList') {
-      for (const listItem of node.content || []) {
-        if (listItem.type === 'listItem' && listItem.content) {
-          for (const child of listItem.content) {
-            if (child.type === 'paragraph') out.push(child)
-          }
-        }
-      }
-    }
-  }
+  visitTranslatableBlocks(doc?.content, (node) => out.push(node))
   return out
 }
 

package/src/i18n/merge.js

@@ -15,6 +15,7 @@
 import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
 import { elementText, blockElements } from './extract.js'
+import { visitDataStrings } from './data-strings.js'
 
 // Inline-markdown → ProseMirror inline fragment, for resolving a whole-element
 // translation VALUE (which carries marks/links/icons as inline markdown). Same
@@ -227,6 +228,7 @@ function translateSectionSync(section, pageRoute, translations, fallbackToSource
 
   if (section.content?.type === 'doc') {
     translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
+    translateDataBlocks(section.content, context, translations, fallbackToSource)
   }
 
   // Recursively translate subsections
@@ -259,6 +261,7 @@ async function translateSectionAsync(section, page, translations, options) {
     // Fall back to hash-based translation
     if (section.content?.type === 'doc') {
       translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
+      translateDataBlocks(section.content, context, translations, fallbackToSource)
     }
   }
 
@@ -302,6 +305,37 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
   return false
 }
 
+/**
+ * Translate the human-readable strings inside a section's TAGGED DATA BLOCKS,
+ * in place. The other half of the fix in `extract.js` — a manifest entry nobody
+ * applies is worse than no entry, because a translator has already done the work.
+ *
+ * Called from the two BUILD-lane section walks only, deliberately, and NOT from
+ * `resolveDocForLocale`. See `extractFromDataBlocks` for why: the sync wire's
+ * structural map is derived by walking block elements, so a translated data
+ * payload there would be neither captured nor flagged as divergent, and would be
+ * dropped on the next pull. Losing a translation silently is worse than not
+ * carrying one yet.
+ */
+function translateDataBlocks(doc, context, translations, fallbackToSource) {
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue
+      if (node.type === 'dataBlock') {
+        const data = node.attrs?.data
+        if (data && typeof data === 'object') {
+          visitDataStrings(data, (value) =>
+            lookupTranslation(value, context, translations, fallbackToSource)
+          )
+        }
+      } else if (Array.isArray(node.content)) {
+        walk(node.content)
+      }
+    }
+  }
+  walk(doc?.content)
+}
+
 /**
  * Resolve ONE ProseMirror content doc for a single target locale: a deep clone of
  * the source doc with each whole-element translated (inline content replaced from

package/src/index.js

@@ -18,6 +18,7 @@ export {
 export {
   validateItem,
   validateDataInputs,
+  validateConceptBlocks,
   isStaticallyCheckable,
 } from './validate-data.js'
 

package/src/prerender.js

@@ -11,7 +11,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { resolveDefaultLocale } from '@uniweb/core'
+import { resolveDefaultLocale, isDataUrl } from '@uniweb/core'
 import { executeFetch, mergeDataIntoContent } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
@@ -81,7 +81,7 @@ async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
     localeInfo.distDir
 
   function localizeFetch(config) {
-    if (!isNonDefaultLocale || !config.path?.startsWith('/data/')) return config
+    if (!isNonDefaultLocale || !isDataUrl(config.path)) return config
     return { ...config, path: `/${localeInfo.locale}${config.path}` }
   }
 

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

@@ -21,7 +21,7 @@ import { writeFile, readFile, mkdir, cp } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, dirname } from 'node:path'
 
-import { resolveDefaultLocale } from '@uniweb/core'
+import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processCollections, writeCollectionFiles } from './collection-processor.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
@@ -35,7 +35,9 @@ import {
   renderPageMarkdown,
   resolveAgentsConfig,
   selectIndexablePages,
+  selectIndexBranches,
   pageMarkdownFilename,
+  branchIndexFilename,
   INDEX_FILENAME
 } from '@uniweb/projections'
 
@@ -133,8 +135,8 @@ export async function buildSiteData({
     )
     await writeCollectionFiles(resolvedSiteRoot, collections, siteContent.config.collections)
 
-    const publicDataDir = join(resolvedSiteRoot, 'public', 'data')
-    const distDataDir = join(resolvedDistDir, 'data')
+    const publicDataDir = join(resolvedSiteRoot, 'public', DATA_DIR)
+    const distDataDir = join(resolvedDistDir, DATA_DIR)
     if (existsSync(publicDataDir)) {
       await cp(publicDataDir, distDataDir, { recursive: true })
     }
@@ -228,7 +230,7 @@ export async function buildSiteData({
     const collectionIndexes = []
     for (const [collName, collConfig] of Object.entries(collections)) {
       if (!collConfig.search?.enabled || !collConfig.route) continue
-      const cascadeFile = join(resolvedDistDir, 'data', `${collName}.json`)
+      const cascadeFile = join(resolvedDistDir, DATA_DIR, `${collName}.json`)
       if (!existsSync(cascadeFile)) continue
       let collectionData
       try {
@@ -297,6 +299,23 @@ async function writeProjections(siteContent, distDir) {
   if (agents.index) {
     const index = renderSiteIndex(siteContent, { ...options, exclude: agents.exclude })
     await writeFile(join(distDir, INDEX_FILENAME), index)
+
+    // Additive scoped indexes; the root one above stays complete. See
+    // `selectIndexBranches` for why this is not a delegation.
+    if (agents.branchIndexes) {
+      const branches = selectIndexBranches(siteContent.pages, {
+        exclude: agents.exclude,
+        minPages: agents.branchMinPages
+      })
+      for (const branch of branches) {
+        const target = join(distDir, branchIndexFilename(branch.route))
+        await mkdir(dirname(target), { recursive: true })
+        await writeFile(
+          target,
+          renderSiteIndex(siteContent, { ...options, exclude: agents.exclude, branch: branch.route })
+        )
+      }
+    }
   }
 
   if (!agents.markdown) return

package/src/site/collection-processor.js

@@ -32,11 +32,12 @@
  * await writeCollectionFiles(siteDir, collections)
  */
 
-import { readFile, readdir, stat, writeFile, mkdir, copyFile } from 'node:fs/promises'
-import { join, basename, extname, dirname, relative, resolve } from 'node:path'
+import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
+import { join, basename, extname, dirname, relative, resolve, sep } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { parseBibtex } from '@citestyle/bibtex'
+import { DATA_DIR } from '@uniweb/core'
 import { applyFilter, applySort } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 
@@ -642,6 +643,62 @@ export async function processCollections(siteDir, collectionsConfig, collections
   return results
 }
 
+/**
+ * Reconcile a deferred collection's per-record directory with the records it
+ * should hold this run — delete the `<slug>.json` files that are no longer
+ * backed by a record.
+ *
+ * Why this is not optional. `public/data/` is a persistent, normally-committed
+ * directory, so anything written there survives until something removes it.
+ * Without this, unpublishing a record (`published: false`, which the build
+ * honours automatically) or deleting its source file drops it from the cascade
+ * listing — it vanishes from the site — while its per-record file stays on
+ * disk with the full body, gets committed, and gets deployed. The author has
+ * every reason to believe the content is gone. It is still fetchable at a URL
+ * that was public a moment ago.
+ *
+ * `public/data/` is the build's output directory and nothing else — authors
+ * provide structured data through `collections/`, which is the only supported
+ * way. So `<name>/` is entirely ours and the reconciliation is total: anything
+ * in it that this run did not write is stale by definition. `expected` is
+ * empty when a collection stops declaring `deferred:`, which correctly clears
+ * a directory that will otherwise never be written again.
+ *
+ * NOT covered: a collection removed from `site.yml` entirely. There is no
+ * declaration left to reconcile against, so pruning it would mean the build
+ * asserting ownership of a directory on a name match alone. That needs the
+ * ownership question answered on purpose, not as a side effect of this.
+ *
+ * @param {string} dataDir - `public/data/`, the containing output directory
+ * @param {string} name - the declared collection name
+ * @param {Set<string>} expected - filenames this run wrote, e.g. `hello.json`
+ * @returns {Promise<string[]>} the entry names removed
+ */
+async function pruneOrphanedRecords(dataDir, name, expected) {
+  const recordsDir = join(dataDir, name)
+
+  // This routine deletes, and `name` reaches it from site.yml. A name that
+  // resolves outside the output directory would make the traversal somebody
+  // else's files, so refuse rather than trust the caller.
+  const contained = resolve(recordsDir)
+  if (contained !== resolve(dataDir, name) || !contained.startsWith(resolve(dataDir) + sep)) {
+    console.warn(
+      `[collection-processor] Refusing to prune "${name}" — it does not resolve ` +
+      `inside ${dataDir}`
+    )
+    return []
+  }
+  if (!existsSync(recordsDir)) return []
+
+  const removed = []
+  for (const entry of await readdir(recordsDir, { withFileTypes: true })) {
+    if (expected.has(entry.name)) continue
+    await rm(join(recordsDir, entry.name), { recursive: true, force: true })
+    removed.push(entry.isDirectory() ? `${entry.name}/` : entry.name)
+  }
+  return removed
+}
+
 /**
  * Write collection data to JSON files in public/data/
  *
@@ -660,7 +717,7 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
     return
   }
 
-  const dataDir = join(siteDir, 'public', 'data')
+  const dataDir = join(siteDir, 'public', DATA_DIR)
   await mkdir(dataDir, { recursive: true })
 
   for (const [name, items] of Object.entries(collections)) {
@@ -677,13 +734,15 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
       const recordsDir = join(dataDir, name)
       await mkdir(recordsDir, { recursive: true })
 
-      let perRecordCount = 0
+      const written = new Set()
       for (const item of items) {
         if (!item || typeof item !== 'object' || !item.slug) continue
-        const recordPath = join(recordsDir, `${item.slug}.json`)
-        await writeFile(recordPath, JSON.stringify(item, null, 2))
-        perRecordCount++
+        const filename = `${item.slug}.json`
+        await writeFile(join(recordsDir, filename), JSON.stringify(item, null, 2))
+        written.add(filename)
       }
+      const perRecordCount = written.size
+      const pruned = await pruneOrphanedRecords(dataDir, name, written)
 
       const stripped = items.map((item) => {
         if (!item || typeof item !== 'object') return item
@@ -697,10 +756,29 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
         `[collection-processor] Generated ${cascadePath} (${items.length} items, ` +
         `deferred: [${deferred.join(', ')}]) + ${perRecordCount} per-record files`
       )
+      if (pruned.length > 0) {
+        // A deletion is always worth naming. These files were public a moment
+        // ago, so "which ones went" is the question an author will have.
+        console.log(
+          `[collection-processor] Removed ${pruned.length} stale per-record ` +
+          `file(s) from ${recordsDir}: ${pruned.join(', ')}`
+        )
+      }
     } else {
       const filepath = join(dataDir, `${name}.json`)
       await writeFile(filepath, JSON.stringify(items, null, 2))
       console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+
+      // This collection is not deferred, so it has no per-record files. If it
+      // used to, the directory is still there and will never be written again
+      // — every file in it is stale. Same reconciliation, empty expected set.
+      const pruned = await pruneOrphanedRecords(dataDir, name, new Set())
+      if (pruned.length > 0) {
+        console.log(
+          `[collection-processor] Removed ${pruned.length} per-record file(s) ` +
+          `from ${join(dataDir, name)} — "${name}" no longer declares deferred:`
+        )
+      }
     }
   }
 }

package/src/site/content-collector.js

@@ -2152,9 +2152,10 @@ export async function collectSiteContent(sitePath, options = {}) {
   // base prefix while the hydrated browser routes were fine.
   //
   // Only a real base is written. At '/' the field stays absent, because in
-  // shell mode `config.base` is the SERVING layer's channel (it injects the
-  // served subpath, e.g. /gateway/site/<uuid>/) and a build-time '/' would
-  // be a meaningless value sitting in its slot.
+  // shell mode `config.base` is the SERVING layer's channel — the host injects
+  // whatever subpath it serves the site under, and a build-time '/' would be a
+  // meaningless value sitting in its slot. The build deliberately does not model
+  // what that subpath looks like; that is the host's shape, not ours.
   if (base && base !== '/') {
     siteConfig.base = base
   }

package/src/site/data-ball.js

@@ -19,6 +19,7 @@
 import { existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
+import { DATA_DIR } from '@uniweb/core'
 import { isLocalAssetPath } from './assets.js'
 
 // Walk a dist subdir for *.json → { "<posix-relpath>": <parsedJson> }. Unparseable
@@ -58,7 +59,7 @@ function collectionOf(relPath) {
  */
 export async function assembleDataBall(distDir, schemalessNames = []) {
   const schemaless = new Set(schemalessNames)
-  const allData = await readJsonTree(join(distDir, 'data'))
+  const allData = await readJsonTree(join(distDir, DATA_DIR))
   const data = {}
   for (const [relPath, value] of Object.entries(allData)) {
     if (schemaless.has(collectionOf(relPath))) data[relPath] = value

package/src/site/data-fetcher.js

@@ -20,7 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere } from '@uniweb/core'
+import { matchWhere, collectionDataUrl } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -290,7 +290,7 @@ export function parseFetchConfig(fetch) {
   if (fetch.collection) {
     if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
-      path: `/data/${fetch.collection}.json`,
+      path: collectionDataUrl(fetch.collection),
       url: undefined,
       schema: fetch.schema || fetch.collection,
       prerender: fetch.prerender ?? true,

package/src/site/plugin.js

@@ -33,13 +33,15 @@
 import { resolve, join } from 'node:path'
 import { watch, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
-import { resolveDefaultLocale } from '@uniweb/core'
+import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import {
   renderSiteIndex,
   renderPageMarkdown,
   resolveAgentsConfig,
   selectIndexablePages,
+  selectIndexBranches,
   pageMarkdownFilename,
+  branchIndexFilename,
   applyRouteTranslation,
   INDEX_FILENAME
 } from '@uniweb/projections'
@@ -275,19 +277,68 @@ function escapeXml(str) {
     .replace(/'/g, ''')
 }
 
+/** The three defined Content Signals, in the order they are emitted. */
+const CONTENT_SIGNAL_KEYS = ['search', 'ai-input', 'ai-train']
+
+/**
+ * Format the `Content-Signal:` directive from `seo.robots.contentSignals`.
+ *
+ * Content Signals express what a site permits its content to be *used for*,
+ * which is a different axis from `Disallow:` — that governs fetching, this
+ * governs use after fetching. The three defined signals:
+ *
+ * - `search`    — appear in search results
+ * - `ai-input`  — be retrieved at inference time (RAG, grounding)
+ * - `ai-train`  — be used to train a model
+ *
+ * **Emitted only when declared.** There is no default: a preference the site
+ * owner did not state is not ours to assert, in either direction. An absent
+ * signal means "unstated", which is not the same as `no`.
+ *
+ * Unknown keys are ignored rather than passed through — the vocabulary is a
+ * closed set, and forwarding an invented signal would produce a directive no
+ * crawler honors while reading as though it were doing something.
+ *
+ * @param {Object|null} signals - e.g. `{ search: true, 'ai-input': true, 'ai-train': false }`
+ * @returns {string} The directive line, or `''` when nothing is declared
+ */
+export function formatContentSignals(signals) {
+  if (!signals || typeof signals !== 'object') return ''
+
+  const parts = []
+  for (const key of CONTENT_SIGNAL_KEYS) {
+    if (!(key in signals)) continue
+    const value = signals[key]
+    const yes = value === true || value === 'yes'
+    const no = value === false || value === 'no'
+    if (!yes && !no) continue
+    parts.push(`${key}=${yes ? 'yes' : 'no'}`)
+  }
+
+  return parts.length ? `Content-Signal: ${parts.join(', ')}` : ''
+}
+
 /**
  * Generate robots.txt content
  */
-function generateRobotsTxt(baseUrl, options = {}) {
+export function generateRobotsTxt(baseUrl, options = {}) {
   const {
     disallow = [],
     allow = [],
     crawlDelay = null,
-    additionalSitemaps = []
+    additionalSitemaps = [],
+    contentSignals = null
   } = options
 
   let content = 'User-agent: *\n'
 
+  const signals = formatContentSignals(contentSignals)
+  if (signals) {
+    // Inside the User-agent group, before the rules — the directive applies to
+    // the group it sits in.
+    content += `${signals}\n`
+  }
+
   for (const path of allow) {
     content += `Allow: ${path}\n`
   }
@@ -622,6 +673,31 @@ export function siteContentPlugin(options = {}) {
         source: renderSiteIndex(content, { ...options, exclude: agents.exclude })
       })
       console.log(`[site-content] Generated ${localeDir}${INDEX_FILENAME}`)
+
+      // Branch indexes are ADDITIVE — the root index above still enumerates
+      // every page, because the two-hop criterion depends on it. These are a
+      // scoped entry point for an agent already inside a branch.
+      if (agents.branchIndexes) {
+        const branches = selectIndexBranches(content.pages, {
+          exclude: agents.exclude,
+          minPages: agents.branchMinPages
+        })
+        for (const branch of branches) {
+          this.emitFile({
+            type: 'asset',
+            fileName: `${localeDir}${branchIndexFilename(branch.route)}`,
+            source: renderSiteIndex(content, {
+              ...options,
+              exclude: agents.exclude,
+              branch: branch.route
+            })
+          })
+        }
+        if (branches.length) {
+          const names = branches.map(b => `${b.route} (${b.count})`).join(', ')
+          console.log(`[site-content] Generated ${branches.length} branch index(es): ${names}`)
+        }
+      }
     }
 
     if (agents.markdown) {
@@ -1006,18 +1082,39 @@ export function siteContentPlugin(options = {}) {
           const agents = resolveAgentsConfig(siteContent.config)
           const url = req.url.split('?')[0]
 
-          const indexMatch = url.match(new RegExp(`^(?:\\/(${LOCALE_RE}))?\\/${INDEX_FILENAME}$`))
+          // `/llms.txt`, `/fr/llms.txt`, and the branch form `/docs/llms.txt`.
+          // The optional middle group is the branch route; an empty one is the
+          // site index, so a single pattern serves both rather than two that
+          // could drift.
+          const indexMatch = url.match(
+            new RegExp(`^(?:\\/(${LOCALE_RE}))?((?:\\/[^/]+)*)\\/${INDEX_FILENAME}$`)
+          )
           if (indexMatch && agents.index) {
             const localized = (indexMatch[1] ? await getTranslatedContent(indexMatch[1]) : null) || siteContent
-            res.setHeader('Content-Type', 'text/plain; charset=utf-8')
-            res.end(
-              renderSiteIndex(localized, {
-                ...projectionOptions(localized),
-                locale: indexMatch[1] || projectionOptions(localized).locale,
-                exclude: agents.exclude
-              })
-            )
-            return
+            const branch = indexMatch[2] || null
+
+            // Serve a branch index only where the build would emit one, or dev
+            // and the built output disagree about which URLs exist.
+            const served =
+              !branch ||
+              (agents.branchIndexes &&
+                selectIndexBranches(localized.pages, {
+                  exclude: agents.exclude,
+                  minPages: agents.branchMinPages
+                }).some(b => b.route === branch))
+
+            if (served) {
+              res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+              res.end(
+                renderSiteIndex(localized, {
+                  ...projectionOptions(localized),
+                  locale: indexMatch[1] || projectionOptions(localized).locale,
+                  exclude: agents.exclude,
+                  branch
+                })
+              )
+              return
+            }
           }
 
           const markdownMatch = url.match(new RegExp(`^(?:\\/(${LOCALE_RE}))?\\/(.+)\\.md$`))
@@ -1038,12 +1135,12 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Handle localized collection data (e.g., /fr/data/articles.json)
-        const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/data\\/(.+\\.json)$`))
+        const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/${DATA_DIR}\\/(.+\\.json)$`))
         if (localeDataMatch) {
           const locale = localeDataMatch[1]
           const filename = localeDataMatch[2]
           const collectionName = filename.replace('.json', '')
-          const sourcePath = join(resolvedSitePath, 'public', 'data', filename)
+          const sourcePath = join(resolvedSitePath, 'public', DATA_DIR, filename)
 
           if (existsSync(sourcePath)) {
             try {

package/src/uwx/site.js

@@ -54,7 +54,7 @@ import {
   processMarkdownFile,
 } from '../site/content-collector.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
-import { resolveDefaultLocale, validateLanguageConfig } from '@uniweb/core'
+import { resolveDefaultLocale, validateLanguageConfig, collectionDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
@@ -182,7 +182,7 @@ function buildPageData(config, ctx) {
     // `schema` (the collection name) is BOTH the content.data key and part of the
     // dataStore cache key (deriveCacheKey hashes {path,url,schema,…}; `collection`
     // is ignored). Mirrors the static build's parseFetchConfig resolution.
-    fetch = { path: `/data/${collection}.json`, schema: collection, ...rest }
+    fetch = { path: collectionDataUrl(collection), schema: collection, ...rest }
   }
   setIf(data, 'fetch', fetch)
   if (isDynamic) {

package/src/validate-data.js

@@ -29,8 +29,9 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
+import { collectionNameFromUrl } from '@uniweb/core'
 
-import { SCALAR_KINDS, FORMAT_TYPES } from './resolve-data-schema.js'
+import { SCALAR_KINDS, FORMAT_TYPES, validateAndNormalizeSchema } from './resolve-data-schema.js'
 import { buildSchema } from './schema.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
@@ -352,6 +353,13 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
     })
   }
 
+  // Pass 3 — concept blocks, which join to a schema by CONVENTION rather than
+  // by a foundation binding. Additive and silent unless a schema resolves.
+  const concepts = await validateConceptBlocks(site)
+  violations.push(...concepts.violations)
+  for (const ref of concepts.schemas) schemasSeen.add(ref)
+  recordCount += concepts.checked
+
   return {
     violations,
     deferred,
@@ -365,6 +373,161 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
   }
 }
 
+/**
+ * Check each ```md:<tag> concept block against `@std/<tag>`, when that schema
+ * exists.
+ *
+ * THREE PROPERTIES MAKE THIS SAFE, and all three have to hold:
+ *
+ * 1. It adds NO REGISTRY. The resolution is mechanical — `md:faq` → `@std/faq`,
+ *    the same `@std` → `@uniweb/schemas` mapping every other ref uses. What the
+ *    framework gains is a naming convention; no code branches on the value of a
+ *    tag, and nothing here knows which concepts exist. A hardcoded list of
+ *    concept names is the thing this whole design exists to avoid, and it would
+ *    arrive through this door if the check needed to know what `faq` means.
+ *
+ * 2. It never touches SHAPE. A concept block's shape comes from its fence,
+ *    unconditionally. This runs after the parse and changes nothing: a block
+ *    with no resolvable schema still parses, still delivers items, still
+ *    renders. The schema is a check, never a gate.
+ *
+ * 3. It never fails at RENDER. Findings only — this whole module is a pre-live
+ *    dev/CI gate and the runtime stays tolerant.
+ *
+ * ⛔ A standard schema for a concept MUST be authored in the ITEM vocabulary —
+ * `title`, `paragraphs`, and the rest of the parsed shape — because that is what
+ * a concept block always produces. An `@std/faq` written as `{ question, answer }`
+ * could only be checked with a per-concept field mapping, which is the forbidden
+ * registry arriving by the back door. Author the schema to match the parse, or
+ * do not ship the schema.
+ *
+ * ⛔ AND FOR A PROSE CONCEPT, NO FACET CAN FIRE AT ALL — so do not write an
+ * `@std` schema for one. Measured 2026-07-30:
+ *
+ *   - `required` is inert. The item vocabulary is TOTAL — `flattenGroup` fills
+ *     every field it declares, so a titleless item has `title: ''` rather than
+ *     no title, and `required` fires only on absent or null. "The author
+ *     actually wrote a question" is not expressible.
+ *   - `type` cannot fail either. Inside a concept block `title` is always a
+ *     string (never an array — `alwaysItems` suppresses the same-level merge
+ *     that would make one) and `paragraphs` is always an array of strings.
+ *   - which leaves `enum` / `format`, and neither has a natural application to
+ *     a question or an answer. The test suite had to invent `format: 'url'` on
+ *     a question to make anything fire — that is the tell, not a fixture quirk.
+ *
+ * The mechanism still earns its place, but it is waiting for a different shape:
+ * a concept that carries a tagged DATA BLOCK. Verified that one reaches the item
+ * — ```` ```md:steps ```` holding a ```` ```yaml:meta ```` gives
+ * `items[0].data.meta` — and there `required` fires when an author omits the
+ * block, `enum` constrains a status, `format` constrains a duration. That is the
+ * trigger to write a schema. Until then the frontend holds the concept names and
+ * their shapes, which is where they belong: its extension encodes the shape
+ * executably, and a `standard/faq.js` in `@uniweb/schemas` whose only consumer is
+ * that app would be this framework stating which concepts exist — the registry
+ * this design forbids, spelled as a filename instead of a switch.
+ *
+ * Note on resolution: this deliberately does NOT go through `resolveSchemaRef`,
+ * which resolves a package from a FOUNDATION's node_modules and throws when a
+ * ref is unknown. Neither fits — a concept block needs no foundation (so this
+ * works on a link-mode site whose foundation is a registry ref with nothing
+ * local), and an unresolved tag must be silent rather than an error. So the
+ * package is resolved from this build's own graph, where it is an
+ * optionalDependency, exactly as `i18n/collections.js` resolves it.
+ *
+ * @param {Object} site - collected site content (`{ pages }`)
+ * @returns {Promise<{ violations: Array, schemas: Set<string>, checked: number }>}
+ */
+export async function validateConceptBlocks(site) {
+  const empty = { violations: [], schemas: new Set(), checked: 0 }
+
+  const parse = await loadSemanticParser()
+  if (!parse) return empty // no parser available — nothing to derive items from
+
+  const standards = await loadStandardSchemas()
+  if (!standards) return empty // @uniweb/schemas absent — nothing to check against
+
+  const violations = []
+  const schemasSeen = new Set()
+  let checked = 0
+
+  for (const page of site.pages || []) {
+    walkSections(page.sections || [], (section) => {
+      const doc = section.content
+      if (doc?.type !== 'doc') return
+
+      for (const node of conceptBlockNodes(doc)) {
+        const tag = node.attrs?.tag
+        if (!tag) continue
+
+        const raw = standards(tag)
+        if (!raw) continue // no `@std/<tag>` — say nothing, by design
+
+        let schema
+        try {
+          schema = validateAndNormalizeSchema(raw, `@std/${tag}`)
+        } catch {
+          continue // a malformed standard schema is that package's problem
+        }
+        if (!isStaticallyCheckable(schema)) continue
+
+        schemasSeen.add(`@std/${tag}`)
+        const { items } = parse({ type: 'doc', content: node.content || [] }, { alwaysItems: true })
+
+        items.forEach((item, idx) => {
+          checked++
+          for (const finding of validateItem(schema, item)) {
+            violations.push({
+              file: `${page.route || '/'} › ${section.type || 'section'} › md:${tag}`,
+              schema: `@std/${tag}`,
+              item: `item ${idx + 1}`,
+              users: [{ route: page.route, section: section.type, key: tag }],
+              ...finding,
+            })
+          }
+        })
+      }
+    })
+  }
+
+  return { violations, schemas: schemasSeen, checked }
+}
+
+/** Every concept block in a doc, including any nested inside a container. */
+function conceptBlockNodes(doc) {
+  const out = []
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue
+      if (node.type === 'concept_block') out.push(node)
+      else if (Array.isArray(node.content)) walk(node.content)
+    }
+  }
+  walk(doc?.content)
+  return out
+}
+
+/** `parseContent`, or null when the parser is not installed. */
+async function loadSemanticParser() {
+  try {
+    const mod = await import('@uniweb/semantic-parser')
+    return typeof mod.parseContent === 'function' ? mod.parseContent : null
+  } catch {
+    return null
+  }
+}
+
+/** A `(name) => schema | undefined` lookup over `@std`, or null when absent. */
+async function loadStandardSchemas() {
+  try {
+    const mod = await import('@uniweb/schemas')
+    if (typeof mod.getSchema === 'function') return (name) => mod.getSchema(name)
+    const table = mod.schemas ?? mod.default
+    return table ? (name) => table[name] : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * The data inputs available to a section, deduped by key. A section receives
  * its own fetch plus any inherited page-level and site-level fetch (default-on
@@ -402,8 +565,9 @@ function walkSections(sections, visit) {
  * (hand-authored data) is read from disk. Either way no prior build is needed.
  */
 async function resolveRecords(path, { collections, siteRoot }) {
-  // `/data/<name>.json` → a declared collection? Use the compiled records.
-  const name = path.replace(/^\/?data\//, '').replace(/\.json$/i, '')
+  // A compiled-collection URL → a declared collection? Use the compiled
+  // records. Anything else falls through to the file read below.
+  const name = collectionNameFromUrl(path)
   let records
   if (Object.prototype.hasOwnProperty.call(collections, name)) {
     records = collections[name]