@uniweb/build 1.7.5 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-writer": "~1.3.0",
+    "@uniweb/schemas": "~1.6.5",
     "@uniweb/content-reader": "~1.5.4",
-    "@uniweb/semantic-parser": "~1.12.2",
     "@uniweb/projections": "~1.1.6",
-    "@uniweb/theming": "~1.2.1",
-    "@uniweb/schemas": "~1.6.5"
+    "@uniweb/semantic-parser": "~1.12.2",
+    "@uniweb/theming": "~1.2.1"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.15"

package/src/site/content-collector.js

@@ -540,18 +540,32 @@ function getContentProfile(configFile) {
  */
 async function readFolderConfig(dirPath, inheritedMode) {
   const folderYml = await readYamlFile(join(dirPath, 'folder.yml'))
-  if (Object.keys(folderYml).length > 0) {
-    return { config: folderYml, mode: 'pages', source: 'folder.yml' }
-  }
-  const pageYml = await readYamlFile(join(dirPath, 'page.yml'))
-  if (Object.keys(pageYml).length > 0) {
-    return { config: pageYml, mode: 'sections', source: 'page.yml' }
-  }
-  // Check for empty folder.yml (presence signals folder mode even if empty)
-  if (existsSync(join(dirPath, 'folder.yml'))) {
-    return { config: {}, mode: 'pages', source: 'folder.yml' }
-  }
-  return { config: {}, mode: inheritedMode, source: 'inherited' }
+  const pageYml = Object.keys(folderYml).length > 0 ? {} : await readYamlFile(join(dirPath, 'page.yml'))
+  const { mode, source } = folderContentMode(folderYml, pageYml, existsSync(join(dirPath, 'folder.yml')), inheritedMode)
+  return { config: source === 'folder.yml' ? folderYml : source === 'page.yml' ? pageYml : {}, mode, source }
+}
+
+/**
+ * A folder's content mode from its two config files — `readFolderConfig`'s rule, as a pure
+ * function, so a synchronous reader applies the same one: the pull, which must know which pages
+ * a folder's `.md` files are (`uwx/git-authored.js`).
+ *
+ * - a `folder.yml` with keys → folder mode
+ * - else a `page.yml` with keys → page mode
+ * - else an empty `folder.yml` → folder mode (its presence is the declaration)
+ * - else the parent's mode
+ *
+ * @param {object|null} folderYml - the parsed `folder.yml`, or empty
+ * @param {object|null} pageYml - the parsed `page.yml`, or empty
+ * @param {boolean} hasFolderYml - whether a `folder.yml` exists at all
+ * @param {string} inheritedMode - 'sections' or 'pages'
+ * @returns {{ mode: string, source: string }}
+ */
+export function folderContentMode(folderYml, pageYml, hasFolderYml, inheritedMode) {
+  if (folderYml && Object.keys(folderYml).length > 0) return { mode: 'pages', source: 'folder.yml' }
+  if (pageYml && Object.keys(pageYml).length > 0) return { mode: 'sections', source: 'page.yml' }
+  if (hasFolderYml) return { mode: 'pages', source: 'folder.yml' }
+  return { mode: inheritedMode, source: 'inherited' }
 }
 
 /**
@@ -717,6 +731,63 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
   return resolved.size > 0 ? resolved : null
 }
 
+/**
+ * How a route read from a mount, a local folder of the same name, or both, is shaped: the two
+ * configs layered, the mode it is read in, and the mode its children are walked in. ONE rule, for
+ * the build's walk (`collectPagesRecursive`) and the push's (`uwx/site.js::orderedSubfolders`), so
+ * a mounted route is the same page tree on both lanes.
+ *
+ * The configs LAYER rather than one replacing the other: the mounted repo declares what its content
+ * is (ordering, title, how it nests), the local folder how this site presents it (layout, SEO, menu
+ * visibility). Mode is not a config key — it comes from which config file exists — so it is not
+ * spread: an explicit local declaration wins (a `page.yml` stub with its own markdown is a real
+ * landing page above mounted children); otherwise the mount decides, because it owns the content.
+ * A folder-mode route's children are walked in folder mode; a page-mode route's in the mount's own
+ * mode when they come from one — it is the mount's tree — else in the route's.
+ *
+ * @param {string} name - the route segment
+ * @param {{ config: object, mode: string, source: string }|null} local - the local folder's
+ *   `readFolderConfig`, or null
+ * @param {{ config: object, mode: string, source: string }|null} mounted - the mount target's
+ *   `readFolderConfig`, or null
+ * @param {string} contentMode - the mode of the level the route is on
+ * @returns {{ dirConfig: object, dirMode: string, childMode: string }}
+ */
+export function layerMountedFolder(name, local, mounted, contentMode) {
+  const dirConfig = mounted
+    ? { title: mounted.config.title || name, ...mounted.config, ...local?.config }
+    : local.config
+  const dirMode = local && local.source !== 'inherited'
+    ? local.mode
+    : mounted?.mode ?? local?.mode ?? contentMode
+  const childMode = dirMode === 'pages' ? 'pages' : mounted?.mode ?? dirMode
+  return { dirConfig, dirMode, childMode }
+}
+
+/**
+ * A folder-mode folder's `.md` pages, in the order the build lists them: by filename (numeric
+ * prefix first), then by the folder's own `pages:`. Each name is the page's slug — the filename
+ * without its numeric prefix. Shared by the build's walk and the push's, so the sync lane sends the
+ * pages the build makes, in the build's order.
+ *
+ * @param {string[]} entries - the folder's directory listing
+ * @param {{ pages?: Array }} [orderConfig] - the folder's own config
+ * @returns {{ files: Array<{ file: string, name: string }>, strict: Set<string>|null }} the pages
+ *   in order, and the names a strict `pages:` lists (null when it is not strict)
+ */
+export function folderModePageFiles(entries, orderConfig) {
+  const items = entries.filter(isMarkdownFile).sort(compareFilenames).map((file) => {
+    const { name } = parse(file)
+    return { file, name: parseNumericPrefix(name).name || name }
+  })
+  const parsed = Array.isArray(orderConfig?.pages) ? parseWildcardArray(orderConfig.pages) : null
+  if (!parsed || parsed.mode === 'all') return { files: items, strict: null }
+  return {
+    files: applyWildcardOrder(items, parsed),
+    strict: parsed.mode === 'strict' ? new Set(parsed.before.map(extractItemName).filter(Boolean)) : null
+  }
+}
+
 /**
  * Parse numeric prefix from filename (e.g., "1-hero.md" → { prefix: "1", name: "hero" })
  * Supports:
@@ -1885,21 +1956,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     const mountPath = mounts?.get(name) ?? null
     const localPath = localDirs.has(name) ? join(dirPath, name) : null
 
-    // The content's declaration about itself, then the site's about presenting it.
     const mounted = mountPath ? await readFolderConfig(mountPath, 'pages') : null
     const local = localPath ? await readFolderConfig(localPath, contentMode) : null
-
-    const dirConfig = mounted
-      ? { title: mounted.config.title || name, ...mounted.config, ...local?.config }
-      : local.config
-
-    // Mode is not a config key — it comes from which config file exists, so it
-    // cannot be spread. An explicit local declaration wins (a `page.yml` stub
-    // with its own markdown is a real landing page above mounted children);
-    // otherwise the mount decides, because it owns the content being read.
-    const dirMode = local && local.source !== 'inherited'
-      ? local.mode
-      : mounted?.mode ?? local?.mode ?? contentMode
+    const { dirConfig, dirMode, childMode } = layerMountedFolder(name, local, mounted, contentMode)
 
     const folderLayout = normalizeLayoutConfig(dirConfig.layout)
 
@@ -1909,11 +1968,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined,
       dirConfig,
       dirMode,
-      // The mode the mounted subtree is walked in belongs to the mount: it is
-      // the mount's tree. Without this a `page.yml` stub silently imposed page
-      // mode on a mounted folder of pages, and only every mounted subfolder
-      // carrying its own folder.yml kept that from collapsing them into one page.
-      mountedContentMode: mounted?.mode ?? null,
+      childMode,
       childOrderConfig: {
         pages: dirConfig.pages,
         index: dirConfig.index
@@ -1998,32 +2053,13 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 
   // --- Pages mode: .md files are child pages ---
   if (contentMode === 'pages') {
-    // Collect and process .md files as individual pages
-    const mdFiles = entries.filter(isMarkdownFile).sort(compareFilenames)
-    const mdPageItems = []
-
-    for (const file of mdFiles) {
-      const { name } = parse(file)
-      const { name: stableName } = parseNumericPrefix(name)
+    // Each .md file is a page, in the order `folderModePageFiles` gives — the one the push sends
+    // them in (`uwx/site.js`): by filename, then by this folder's `pages:`.
+    const { files: mdFiles, strict: strictPageNamesFM } = folderModePageFiles(entries, orderConfig)
+    const orderedMdPages = []
+    for (const { file, name } of mdFiles) {
       const result = await processFileAsPage(join(dirPath, file), file, siteRoot, parentRoute)
-      if (result) {
-        mdPageItems.push({ name: stableName || name, result })
-      }
-    }
-
-    // Apply ordering: pages: (wildcard-aware) > order: [array] (backward compat) > default
-    let orderedMdPages
-    let strictPageNamesFM = null
-
-    const pagesParsedFM = Array.isArray(orderConfig?.pages) ? parseWildcardArray(orderConfig.pages) : null
-
-    if (pagesParsedFM && pagesParsedFM.mode !== 'all') {
-      orderedMdPages = applyWildcardOrder(mdPageItems, pagesParsedFM)
-      if (pagesParsedFM.mode === 'strict') {
-        strictPageNamesFM = new Set(pagesParsedFM.before.map(extractItemName).filter(Boolean))
-      }
-    } else {
-      orderedMdPages = mdPageItems
+      if (result) orderedMdPages.push({ name, result })
     }
 
     // In folder mode, determine index page (homepage only).
@@ -2064,7 +2100,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 
     // Process subdirectories
     for (const folder of orderedFolders) {
-      const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+      const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
       assertRouteFolder(entry, parentRoute)
       const isIndex = entry === indexName
       const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
@@ -2102,7 +2138,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
           const childDirPath = mounts?.get(entry) || entryPath
           const childParentRoute = isIndex ? parentRoute : page.route
           const childFetch = page.fetch || parentFetch
-          const childContentMode = mountedContentMode ?? 'sections'
+          const childContentMode = childMode
           const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, childContentMode, null, effectiveLayout)
           pages.push(...subResult.pages)
           assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
@@ -2160,7 +2196,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         // Recurse in folder mode — pass container's own fetch config (or fall back to parent's)
         const childDirPath = mounts?.get(entry) || entryPath
         const containerFetch = containerPage.fetch || parentFetch
-        const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, 'pages', null, effectiveLayout)
+        const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, childMode, null, effectiveLayout)
         pages.push(...subResult.pages)
         assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
         iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2202,7 +2238,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 
   // Second pass: process each page folder
   for (const folder of orderedFolders) {
-    const { name: entry, path: entryPath, dirConfig, dirMode, mountedContentMode, childOrderConfig, childLayout } = folder
+    const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
     assertRouteFolder(entry, parentRoute)
     const isIndex = entry === indexPageName
     const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
@@ -2262,7 +2298,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       // container above passes it.
       const childDirPath = mounts?.get(entry) || entryPath
       const containerFetch = containerPage.fetch || parentFetch
-      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, 'pages', null, effectiveLayout)
+      const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, childMode, null, effectiveLayout)
       pages.push(...subResult.pages)
       assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
       iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2304,7 +2340,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
             ? (hasExplicitOrder ? parentRoute : (page.sourcePath || page.route))
             : page.route
           const childFetch = page.fetch || parentFetch
-          const childContentMode = mountedContentMode ?? dirMode
+          const childContentMode = childMode
           const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, childContentMode, null, effectiveLayout)
           pages.push(...subResult.pages)
           assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
@@ -3099,6 +3135,8 @@ export {
   parseNumericPrefix,
   compareFilenames,
   processMarkdownFile,
+  processFileAsPage,
+  resolveMounts,
   findSectionFile,
   processNesting,
 }

package/src/uwx/git-authored.js

@@ -0,0 +1,85 @@
+// The pages a pull leaves alone: those authored in files a pull cannot write back.
+//
+// ⭐ Two kinds, decided 2026-10-23 [Diego: the pull leaves them alone, since the docs are written in
+// git]. A push sends both whole, read by the build's own rules (`site.js`), so the backend holds
+// the site as the build makes it. A pull writes neither:
+//
+//   · every page under a `paths: { pages/<segment>: <dir> }` mount. Its files are another
+//     repository's, outside the site; the local folder of that name holds only how this site
+//     presents them, and a pull writing the mounted pages into it would grow a second copy there.
+//   · every `.md` page of a folder-mode folder. The file IS the page, and a pull writes a page as a
+//     folder (`page.yml` + its sections), which would turn the author's folder of pages into a
+//     folder of page folders.
+//
+// ⇒ An edit made to one of these pages in the app is not brought back, and the next push replaces
+// it with the file. Pruning skips them too: a pull never deletes what it does not write.
+//
+// A leaf module, read synchronously as the pull projects (`site-project.js`), through the build's
+// mode rule (`folderContentMode`) and its folder-mode page list (`folderModePageFiles`), so the set
+// is the one the push walks.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { isIgnoredFolder } from '../utils/content-files.js'
+import { folderContentMode, folderModePageFiles, mountEntriesOf, parseNumericPrefix } from '../site/content-collector.js'
+
+const DYNAMIC_RE = /^\[(.+)\]$/
+
+// The collector's own reading of a config file (`parseYaml`): absent or unreadable is empty.
+function readYaml(filePath) {
+  try {
+    return yaml.load(readFileSync(filePath, 'utf8'), YAML_OPTIONS) || {}
+  } catch {
+    return {}
+  }
+}
+
+// A folder's mode, as `readFolderConfig` reads it.
+function modeOf(dir, inheritedMode) {
+  const folderYml = readYaml(join(dir, 'folder.yml'))
+  const pageYml = Object.keys(folderYml).length > 0 ? {} : readYaml(join(dir, 'page.yml'))
+  return folderContentMode(folderYml, pageYml, existsSync(join(dir, 'folder.yml')), inheritedMode).mode
+}
+
+/**
+ * The pages of a site a pull leaves alone, by route: each a slug path with no leading slash
+ * (`docs/start/install`), as the pull composes a page's route from the document.
+ *
+ * @param {object|null} siteYml - the parsed `site.yml`
+ * @param {string} pagesDir - the site's pages directory (`siteContentDirs`)
+ * @returns {{ mounted: Set<string>, files: Set<string>, has: (route: string) => boolean }}
+ *   `mounted` — the mounted segments, each leaving its whole route alone; `files` — the routes of
+ *   folder-mode `.md` pages; `has` — whether a route is either
+ */
+export function gitAuthoredPages(siteYml, pagesDir) {
+  const mounted = new Set(mountEntriesOf(siteYml?.paths).map(([segment]) => segment))
+  const files = new Set()
+  const walk = (dir, prefix, inheritedMode) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    const mode = modeOf(dir, inheritedMode)
+    if (mode === 'pages') {
+      for (const { name } of folderModePageFiles(entries.map((e) => e.name)).files) {
+        files.add(prefix + name)
+      }
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || isIgnoredFolder(e.name)) continue
+      if (!prefix && mounted.has(e.name)) continue // the whole route is left alone
+      const dyn = e.name.match(DYNAMIC_RE)
+      walk(join(dir, e.name), `${prefix}${dyn ? dyn[1] : parseNumericPrefix(e.name).name}/`, mode)
+    }
+  }
+  if (existsSync(pagesDir)) walk(pagesDir, '', 'sections')
+  return {
+    mounted,
+    files,
+    has: (route) => mounted.has(String(route).split('/')[0]) || files.has(route),
+  }
+}

package/src/uwx/site-project.js

@@ -54,6 +54,7 @@ import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 import { documentSourceLocale } from './source-locale.js'
 import { siteContentDirs } from './site-dirs.js'
+import { gitAuthoredPages } from './git-authored.js'
 import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
 import { layoutNameKey } from '@uniweb/core/layout-name'
 import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
@@ -693,8 +694,13 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, {
   if (sectionsArray && sectionsArray.length > 0) {
     const authored = existing?.sections
     if (Array.isArray(authored)) {
-      // Compared by the names the files are found by, so a list naming `1-hero` keeps naming it.
-      const same = JSON.stringify(listedNames(authored.filter((e) => e !== '...'))) === JSON.stringify(sectionsArray)
+      // Compared by the names the files are found by, so a list naming `1-hero` keeps naming it —
+      // and with the author's `nest:` applied, as the build reads the two together: a list beside a
+      // `nest:` that gives the incoming nesting is kept, its `nest:` with it. ⛔ Until 2026-10-23 the
+      // list was compared alone, so a page that lists its sections and nests with `nest:` had both
+      // rewritten into one inclusive list on every pull.
+      const said = withNest(listedNames(authored.filter((e) => e !== '...')), existing?.nest)
+      const same = JSON.stringify(said) === JSON.stringify(sectionsArray)
       y.sections = same ? authored : [...sectionsArray, '...']
     } else if (filesGiveTopOrder && nestSays(existing?.nest, sectionsArray)) {
       // Nothing to list: the files and `nest:` say it, kept below.
@@ -714,6 +720,17 @@ function pageRecordToYml(record, sectionsArray, sourceLocale, existing = null, {
   return y
 }
 
+// A `sections:` list's entries with a page's `nest:` applied, as the build applies it after the list
+// (`content-collector.js::processNesting`): a top-level parent `nest:` names takes the children it
+// lists, in place of any the list gives it.
+function withNest(list, nest) {
+  if (!isPlainRecord(nest)) return list
+  return list.map((entry) => {
+    const name = typeof entry === 'string' ? entry : isPlainRecord(entry) ? Object.keys(entry)[0] : null
+    return name && Array.isArray(nest[name]) ? { [name]: nest[name].map((c) => fileSectionName(String(c))) } : entry
+  })
+}
+
 // Whether a `sections:` list nests: an entry that is a parent with its children.
 function nestsIn(list) {
   return Array.isArray(list) && list.some((entry) => isPlainRecord(entry))
@@ -805,8 +822,17 @@ export function pageDirName(record, sourceLocale) {
 // accumulates the slug-path route (for the free-form translation path; matches the
 // producer's slugPath, normalizeRouteForPath strips any leading slash on both).
 function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/') {
+  let leftAlone = false
   for (const record of pages || []) {
     const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
+    const route = routePrefix ? `${routePrefix}/${slug}` : slug
+    // ⭐ A PAGE AUTHORED IN A FILE THE PULL CANNOT WRITE BACK IS LEFT ALONE — a mount's, or a
+    // folder-mode `.md` page (`git-authored.js`). Its children too: a mount's are the mount's.
+    if (ctx.leave?.has(route)) {
+      report.leftAlone?.push(...subtreeRoutes(record, route, sourceLocale))
+      leftAlone = true
+      continue
+    }
     // The route the build gives the page (`buildRouteOf`, the push's rule): an index page takes its
     // parent's, a parametric one is `:<param>`.
     const canon = buildRouteOf(record, canonParent, sourceLocale)
@@ -829,7 +855,6 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw, meta, text))
     else ctx.collector?.add(record.keywords, meta, text)
 
-    const route = routePrefix ? `${routePrefix}/${slug}` : slug
     // Addressed as the push addresses it: its free-form translations and its translations' contexts
     // are keyed by the build's route. ⛔ Until 2026-09-26 this was the slug path — `home` for a
     // homepage the build reads at `/`.
@@ -865,7 +890,18 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
 
     writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
   }
-  reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage })
+  // A level holding a page left alone keeps the order its files give: reconciling it would write an
+  // `order:` into a page folder that does not exist, or rewrite a `pages:` list the author keeps.
+  if (!leftAlone) reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage })
+}
+
+// A page's route and each of its descendants', as `writePagesTree` composes them.
+function subtreeRoutes(record, route, sourceLocale) {
+  const out = [route]
+  for (const child of record.$children || []) {
+    out.push(...subtreeRoutes(child, `${route}/${unwrapLocalized(child.slug, sourceLocale)}`, sourceLocale))
+  }
+  return out
 }
 
 // ⭐ A PAGE'S LOCALIZED URL SEGMENTS — the other locales of its `slug` (`localizeRouteSlugs`, the push) —
@@ -1010,19 +1046,27 @@ function collectSectionFileBases(pageSections) {
 
 // Pass 2 — prune orphan section files (per page dir) and orphan page dirs (per
 // level), AFTER every relocation in pass 1. Guarded against wiping an empty level.
-function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null) {
+function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, routePrefix = '') {
   const incomingDirs = new Set()
   for (const record of pages || []) {
     incomingDirs.add(pageDirName(record, sourceLocale))
+    const slug = unwrapLocalized(record.slug, sourceLocale)
+    const route = routePrefix ? `${routePrefix}/${slug}` : slug
+    // Left alone by pass 1, so nothing of it is pruned either (`git-authored.js`).
+    if (ctx?.leave?.has(route)) continue
     const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
     if (record.mode === 'page') {
       // The files pass 1 wrote into — the author's own names among them — else the names it would give.
       const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
       if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
     }
-    prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx)
+    prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route)
   }
-  if (incomingDirs.size > 0) pruneOrphanPageDirs(pagesDir, incomingDirs, report)
+  if (incomingDirs.size === 0) return
+  // A mounted route's local folder is never an orphan, whatever the document holds: what it
+  // presents is another repository's (`git-authored.js`).
+  if (!routePrefix) for (const segment of ctx?.leave?.mounted ?? []) incomingDirs.add(segment)
+  pruneOrphanPageDirs(pagesDir, incomingDirs, report)
 }
 
 /**
@@ -1291,7 +1335,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   // Before anything is written: a pull that would leave content out of the files stops here.
   refuseContentFilesCannotHold(document, sourceLocale)
 
-  const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
+  const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
   // flushed to locales/{locale}.json at the end (the manifest stays derivable).
@@ -1327,7 +1371,11 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   // Where the tree goes is what `site.yml` says NOW — `siteInfoToConfig` above has
   // written the document's `settings.paths` into it — because that is the file the
   // next push and the build read. See `siteContentDirs`.
-  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, readAuthoredYaml(join(siteRoot, 'site.yml')))
+  const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
+  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
+  // ⭐ The pages authored in files a pull cannot write back — a mount's, a folder-mode folder's
+  // `.md` pages — are neither written nor pruned (`git-authored.js`).
+  ctx.leave = gitAuthoredPages(siteYml, pagesDir)
   // The root page the backend marks as the homepage, by the directory it is written to.
   const home = (document?.pages || []).find((p) => p?.is_index)
   ctx.homepage = home ? pageDirName(home, sourceLocale) : null

package/src/uwx/site.js

@@ -40,9 +40,10 @@
 // they ride under their parent section's `$children` (page_sections is
 // self_nesting), via the same `processNesting` the normal build uses.
 //
-// v0 scope (stated, not silent): folder-mode `.md`-as-pages (document/blog-list
-// profile), `paths:` mounts, versioned scopes, and media/asset bytes
-// (favicon/assets — carried out of band).
+// v0 scope (stated, not silent): versioned scopes, and media/asset bytes
+// (favicon/assets — carried out of band). Folder-mode `.md`-as-pages and
+// `paths: { pages/<segment> }` mounts are carried since 2026-10-23, read by the
+// build's own rules; a pull leaves those pages alone (`git-authored.js`).
 
 import { readdir, readFile } from 'node:fs/promises'
 import { dataBlockModels } from '../i18n/data-models.js'
@@ -59,11 +60,14 @@ import {
   compareFilenames,
   orderFolders,
   processMarkdownFile,
+  processFileAsPage,
   declaredFetch,
   checkDeclaration,
   fetchFromQueryShorthand,
   assertRouteFolder,
-  mountEntriesOf,
+  resolveMounts,
+  layerMountedFolder,
+  folderModePageFiles,
   rootOrderConfig,
   composeLocalizedRoute,
   isValidSlugSegment,
@@ -427,24 +431,37 @@ function buildPageData(config, ctx) {
   return data
 }
 
-async function orderedSubfolders(dirPath, inheritedMode, parentConfig) {
+// A level's child folders, each with the config and mode the build reads it with. At the root,
+// `mounts` adds every `paths: { pages/<segment>: … }` route, shaped by the build's own rule
+// (`layerMountedFolder`): the mount's config under the local folder's, the mode the mount gives
+// unless the local folder declares one, and the children read from the mount. ⛔ Until 2026-10-23
+// this lane read no mount, so a mounted route was pushed as an empty container (a local stub) or
+// not at all (none) — measured 2026-09-18 on a documentation site: 49 pages built, 2 pushed.
+async function orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts = null) {
   const entries = await readdir(dirPath, { withFileTypes: true })
-  const folders = []
+  const local = new Map()
   for (const e of entries) {
-    if (!e.isDirectory() || isIgnoredFolder(e.name)) continue
-    const path = join(dirPath, e.name)
-    const { config, mode, source } = await readFolderConfig(
-      path,
-      inheritedMode
-    )
+    if (e.isDirectory() && !isIgnoredFolder(e.name)) local.set(e.name, join(dirPath, e.name))
+  }
+  const folders = []
+  for (const dirName of new Set([...local.keys(), ...(mounts?.keys() ?? [])])) {
+    const localPath = local.get(dirName) ?? null
+    const mountPath = mounts?.get(dirName) ?? null
+    const localConfig = localPath ? await readFolderConfig(localPath, inheritedMode) : null
+    const mountedConfig = mountPath ? await readFolderConfig(mountPath, 'pages') : null
+    const { dirConfig, dirMode, childMode } = layerMountedFolder(dirName, localConfig, mountedConfig, inheritedMode)
     folders.push({
-      dirName: e.name,
-      name: parseNumericPrefix(e.name).name,
-      path,
-      config,
-      internalMode: mode,
-      source,
-      order: typeof config.order === 'number' ? config.order : undefined,
+      dirName,
+      name: parseNumericPrefix(dirName).name,
+      // Where the page's own sections are — the local folder, as the build reads them — and
+      // where its child pages are: the mount's tree, when it has one.
+      path: localPath ?? mountPath,
+      childrenPath: mountPath ?? localPath,
+      config: dirConfig,
+      internalMode: dirMode,
+      childMode,
+      source: (localConfig ?? mountedConfig).source,
+      order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined,
     })
   }
   // Explicit order, then numeric-prefix filename order, then the parent's `pages:` wildcard —
@@ -487,9 +504,10 @@ const CATCH_ALL_MARKER = '...path'
 //     `multi` section is read as new (inserted, stored counterpart deleted). See
 //     the IDENTITY note in the file header and `site-diff.js`.
 //
-// v0 deferrals: folder-mode `.md`-as-pages, `paths:` mounts, versioned scopes, and
-// media/asset bytes (favicon/assets, carried out of band). `@`-prefix `nest:`
-// hierarchy is NOT deferred — it is reconstructed here, same as a normal build.
+// v0 deferrals: versioned scopes, and media/asset bytes (favicon/assets, carried
+// out of band). `@`-prefix `nest:` hierarchy, folder-mode `.md`-as-pages and
+// `paths: { pages/<segment> }` mounts are NOT deferred — each is read here by the
+// build's own rule (folder-mode pages and mounts since 2026-10-23).
 // ===========================================================================
 
 const SITE_MODEL_NAME = '@uniweb/site-content'
@@ -573,7 +591,7 @@ function isExplicitWithRest(sectionsConfig) {
 // a section name (string) or `{ name: [children…] }`, resolved to its file by
 // name (bare / `@` / numeric-prefix tolerant) and recursed. Order and nesting
 // come from the array, not the directory.
-async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, { appendRest = false } = {}) {
+async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, { appendRest = false, nest = null } = {}) {
   const mdFiles = (await readdir(pageDir)).filter(isMarkdownFile).sort(compareFilenames)
   const seen = new Set()
 
@@ -615,15 +633,37 @@ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, {
       sections.push(section)
     }
   }
+
+  // ⭐ `nest:` OVER THE LIST, as the build applies it after one (`processNesting`,
+  // `site/content-collector.js`): each top-level parent it names gets the children it lists, in
+  // that order, replacing any the list nested — "`nest:` wins" (`docs/reference/page-configuration.md`).
+  // ⛔ Until 2026-10-23 an explicit list ignored `nest:` here, so a page listing its sections and
+  // nesting a figure under each pushed none of the figures, which the build renders — and a pull
+  // then deleted their `@` files, absent from the document.
+  if (nest && typeof nest === 'object') {
+    for (const [parentName, childNames] of Object.entries(nest)) {
+      if (!Array.isArray(childNames)) continue
+      const parent = sections.find((s) => s.stableId === parentName)
+      if (!parent) continue
+      parent.subsections = []
+      for (const childName of childNames) {
+        const file = findSectionFileName(mdFiles, childName)
+        if (!file) continue
+        const { section } = await processMarkdownFile(join(pageDir, file), String(parent.subsections.length + 1), siteRoot, childName)
+        section.subsections = []
+        parent.subsections.push(section)
+      }
+    }
+  }
   return sections.map((s, i) => sectionToRecord(s, i))
 }
 
 async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
   if (isFullyExplicitSections(pageConfig?.sections)) {
-    return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections)
+    return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { nest: pageConfig.nest })
   }
   if (isExplicitWithRest(pageConfig?.sections)) {
-    return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { appendRest: true })
+    return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { appendRest: true, nest: pageConfig.nest })
   }
   const mdFiles = (await readdir(pageDir)).filter(isMarkdownFile).sort(compareFilenames)
   const nest = pageConfig?.nest && typeof pageConfig.nest === 'object' ? pageConfig.nest : {}
@@ -678,56 +718,45 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
   return sections.map((s, i) => sectionToRecord(s, i))
 }
 
-// A folder-mode folder's `.md` files are pages to the build and nothing to this
-// lane. Name every one of them, so the shortfall is visible at push time rather
-// than by reading the backend's store or opening the published site.
-//
-// `source` is `readFolderConfig`'s: a folder with no config of its own is in folder
-// mode because a `folder.yml` above it put it there, and the message says so —
-// "it is a folder-mode folder (`folder.yml`)" over a folder that has none would send
-// the author looking for a file that does not exist.
-async function warnFolderModePagesSkipped(dirPath, siteRoot, source = 'folder.yml') {
-  let files
-  try {
-    files = (await readdir(dirPath)).filter(isMarkdownFile)
-  } catch {
-    return
+// A folder-mode folder's `.md` files, as the pages the build makes of them (`processFileAsPage`):
+// each a page whose one section is the file, titled by its first heading, a draft when the file
+// says `hidden: true`, slugged by the filename without its numeric prefix — and in the build's
+// order (`folderModePageFiles`). ⛔ Until 2026-10-23 this lane sent none of them and warned instead;
+// a documentation site — folder-mode pages in a mounted repo — published 2 of its 49 pages.
+async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
+  const { siteRoot, siteIndex, sourceLocale, translations, pageFields } = ctx
+  const { files } = folderModePageFiles(await readdir(dirPath), orderConfig)
+  const records = []
+  for (const { file, name } of files) {
+    const filePath = join(dirPath, file)
+    const { page } = await processFileAsPage(filePath, file, siteRoot, '/')
+    const config = { title: page.title }
+    if (page.hidden) config.hidden = true
+    const data = buildPageData(config, {
+      where: relative(siteRoot, filePath),
+      slug: name,
+      mode: 'page',
+      isDynamic: false,
+      isRoot,
+      siteIndex,
+      sourceLocale,
+      translations,
+      pageFields,
+    })
+    const record = withIdentity(data.stable_id || name, data)
+    record.page_sections = page.sections.map((s, i) => sectionToRecord(s, i))
+    records.push(record)
   }
-  if (files.length === 0) return
-  const where = relative(siteRoot, dirPath)
-  const why = source === 'inherited'
-    ? 'it is a folder-mode folder (it has no `folder.yml` or `page.yml` of its own, so it inherits folder mode from the `folder.yml` above it)'
-    : 'it is a folder-mode folder (`folder.yml`)'
-  console.warn(
-    `uwx/site: ${files.length} page(s) in \`${where}\` will NOT be pushed — ` +
-      `${why}, and pushing \`.md\`-as-pages ` +
-      `is not implemented on the sync lane. A build renders them; the backend ` +
-      `will not have them.\n` +
-      files.map((f) => `  - ${where}/${f}`).join('\n') +
-      `\n  To publish them, make each one a page-mode directory ` +
-      `(\`<name>/page.yml\` + its section files). To ship them as they are, ` +
-      `use \`uniweb export\` or \`uniweb deploy --host <adapter>\`.` +
-      REPUBLISH_CLAUSE
-  )
+  return records
 }
 
-// A push sends the page tree as ONE entity (see site-diff.js), so a republish does
-// not merge: the shorter document becomes the whole tree. Measured by the backend
-// lane 2026-09-18 against a current `uniwebd` — 49 stored pages replaced by 2, the
-// publish reporting success. Both skip warnings carry this, because "will not be
-// pushed" reads as "you publish short" when the real cost on an already-published
-// site is that live pages are REMOVED.
-const REPUBLISH_CLAUSE =
-  `\n  ⚠ If this site has been published before, a push REPLACES its whole page ` +
-  `tree — pages already live that are missing here are REMOVED, and the publish ` +
-  `still reports success.`
-
 // Recursively build the `pages` tree: each record carries its fields, its inline
-// `page_sections` (page mode only), and its child pages under `$children`.
-async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, parentConfig, isRoot) {
+// `page_sections` (page mode only), and its child pages under `$children`. A folder-mode level's
+// own `.md` pages come first, then its folders, as the build lists them.
+async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, parentConfig, isRoot, mounts = null) {
   const { siteRoot, siteIndex, sourceLocale, translations, pageFields } = ctx
-  const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig)
-  const out = []
+  const out = inheritedMode === 'pages' ? await folderModePageRecords(ctx, dirPath, parentConfig, isRoot) : []
+  const folders = await orderedSubfolders(dirPath, inheritedMode, parentConfig, mounts)
   // A folder inside a `[...path]` folder can never be reached, and `[dir]` /
   // `[path]` would name a route variable — refused here as the collector refuses
   // them, so a site that cannot build cannot sync either (ruled 2026-09-11).
@@ -775,26 +804,13 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
       record.slug = { ...record.slug, [sourceLocale]: f.config.slug }
     }
 
+    // A folder-mode folder has no sections: its `.md` files are pages, sent among its children.
     if (mode === 'page') {
       const sections = await collectPageSectionsNested(f.path, siteRoot, f.config)
       if (sections.length > 0) record.page_sections = sections
-    } else {
-      // ⛔ FOLDER MODE: the build makes each `.md` file here a PAGE; this lane
-      // makes it nothing. It is a v0 mapper gap (bidirectional-sync.md §"Other
-      // v0 mapper gaps"), and until it closes the ONLY thing standing between an
-      // author and a site that publishes a fraction of itself is this warning.
-      //
-      // ⭐ It has to be here, not in `status` or `push`. Those compare the built
-      // document against what was last sent, so with the pages already absent
-      // from the document both correctly report "Synced" / "Nothing to push".
-      // The loss happens upstream of every diff, which is why it was invisible:
-      // measured 2026-09-18, a 49-page documentation site published 2 pages with
-      // every CLI instrument reporting success [measured:backend, channel with
-      // backend, and reproduced here against the same site].
-      await warnFolderModePagesSkipped(f.path, siteRoot, f.source)
     }
 
-    const children = await walkPagesNested(ctx, f.path, slugPath, f.internalMode, f.config, false)
+    const children = await walkPagesNested(ctx, f.childrenPath, slugPath, f.childMode, f.config, false)
     if (children.length > 0) record.$children = children
 
     out.push(record)
@@ -1557,50 +1573,25 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // `siteIndex` — the homepage — joins below, once the pages directory's own config is read.
   // …and the keys this deployment's page takes (`siteContent.pageFields`), for its Open Graph texts.
   const ctx = { siteRoot, sourceLocale, translations, pageFields: opts.pageFields }
-  // ⛔ ONE `paths:` CONVENTION, TWO READERS, AND THIS ONE IS A STRICT SUBSET.
-  // The build honours sub-mounts — `paths: { pages/<segment>: <dir> }`, through
-  // `resolveMounts`/`mountEntriesOf` in `site/content-collector.js` — and this
-  // lane reads `paths.pages` alone. A sub-mounted folder therefore syncs as an
-  // EMPTY container: its directory on disk holds only the `folder.yml`, so it
-  // emits with no children and nothing anywhere says so. Measured 2026-09-18 on
-  // a site whose entire corpus was one sub-mount: 49 pages built, 2 pushed.
-  // Deferred by design for now (bidirectional-sync.md); warned about here so it
-  // is not also silent.
-  //
   // The same two directories the pull writes back to — see `siteContentDirs`.
   const { pagesDir: pagesPath, layoutDir } = siteContentDirs(siteRoot, siteYml)
-  for (const [segment] of mountEntriesOf(siteYml.paths)) {
-    // Only a LOCAL stub (`pages/<segment>/`, the folder that gives a mounted route its
-    // layout) is walked, so the route arrives as an empty container; with no stub,
-    // nothing here stands for the route and it is not sent at all. ⚠️ The message
-    // said "empty container" in both cases until 2026-09-19.
-    const fate = existsSync(join(pagesPath, segment))
-      ? 'will be pushed as an empty container'
-      : 'will not be pushed at all'
-    console.warn(
-      `uwx/site: \`paths: { pages/${segment}: … }\` is NOT read on the sync lane — ` +
-        `\`${segment}\` ${fate} and none of the mounted ` +
-        `pages will reach the backend. A build mounts it normally. Inline the ` +
-        `directory under \`pages/${segment}/\` to push it, or ship the site with ` +
-        `\`uniweb export\` / \`uniweb deploy --host <adapter>\`.` +
-        REPUBLISH_CLAUSE
-    )
-  }
   let pages = []
   if (existsSync(pagesPath)) {
-    // The root has a mode too, read as the build reads it (`rootContentMode`):
-    // `pages/folder.yml` puts the whole site in folder mode, and every folder with no
-    // config of its own inherits it. ⛔ This walk started in page mode unconditionally
-    // until 2026-09-19, so such a site's top-level `.md` pages were dropped without a
-    // word and its top-level folders were pushed as pages of sections.
-    const { mode: rootMode, source: rootSource, config: rootConfig } = await readFolderConfig(pagesPath, 'sections')
-    if (rootMode === 'pages') await warnFolderModePagesSkipped(pagesPath, siteRoot, rootSource)
+    // ⭐ SUB-MOUNTS, AS THE BUILD READS THEM — `paths: { pages/<segment>: <dir> }`, through its own
+    // `resolveMounts`, and STRICT as a production build is: a mount with nothing in it (a git
+    // submodule never fetched) stops the push. A push replaces the site's whole page tree, so a
+    // mount read as empty would remove every page it holds from a published site.
+    const mounts = resolveMounts(siteYml.paths, siteRoot, pagesPath, { strict: true })
+    // The root has a mode too, read as the build reads it (`rootContentMode`): `pages/folder.yml`
+    // puts the whole site in folder mode, its `.md` files pages and every folder with no config of
+    // its own in folder mode too.
+    const { mode: rootMode, config: rootConfig } = await readFolderConfig(pagesPath, 'sections')
     // The top level's order and homepage, decided by the build's own function: the
     // site's `pages:` / `index:` over the pages directory's own. ⛔ The homepage read
     // `index:` alone until 2026-09-19, so a site naming it by its first `pages:` entry
     // — as the build does — pushed no homepage at all.
     const top = rootOrderConfig({ pages: siteYml.pages, index: siteYml.index }, rootConfig)
-    pages = await walkPagesNested({ ...ctx, siteIndex: top.homepage }, pagesPath, '', rootMode, { pages: top.pages }, true)
+    pages = await walkPagesNested({ ...ctx, siteIndex: top.homepage }, pagesPath, '', rootMode, { pages: top.pages }, true, mounts)
     localizeRouteSlugs(pages, siteYml, sourceLocale)
   }