@uniweb/build 0.15.4 → 0.15.6

package/src/site/content-collector.js

@@ -1164,11 +1164,9 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       }
     }
 
-    // Create items with .name property for applyWildcardOrder
-    const allItems = [...discoveredMap.keys()].map(name => ({ name }))
-    const ordered = applyWildcardOrder(allItems, sectionsParsed)
-
     // Collect subsection configs from the original array (e.g., { features: [a, b] })
+    // BEFORE ordering, because the children they name must not also be treated as
+    // top-level sections.
     const subsectionConfigs = new Map()
     for (const item of [...sectionsParsed.before, ...sectionsParsed.after]) {
       if (typeof item === 'object' && item !== null) {
@@ -1179,6 +1177,26 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       }
     }
 
+    // A child named in `nest`-style config is already placed, so it must not fall
+    // into the auto-discovered "rest" as well. `@`-prefixed files are excluded from
+    // discovery above, but a child does NOT have to be `@`-prefixed: `uniweb pull`
+    // writes every section — nested or not — as a flat `<stableId>.md` in the page
+    // dir. Without this, an inclusive list flattens exactly the nesting the list
+    // exists to preserve, promoting each child to a sibling of its own parent.
+    const claimedChildren = new Set()
+    for (const children of subsectionConfigs.values()) {
+      for (const child of children || []) {
+        const name = typeof child === 'string' ? child : Object.keys(child || {})[0]
+        if (name) claimedChildren.add(name)
+      }
+    }
+
+    // Create items with .name property for applyWildcardOrder
+    const allItems = [...discoveredMap.keys()]
+      .filter(name => !claimedChildren.has(name))
+      .map(name => ({ name }))
+    const ordered = applyWildcardOrder(allItems, sectionsParsed)
+
     // Process sections in wildcard-expanded order
     const sections = []
     let sectionIndex = 1

package/src/site/data-ball.js

@@ -56,7 +56,7 @@ function collectionOf(relPath) {
  * @returns {Promise<{ data: Object, search: Object }|null>} null when there is nothing
  *          to deliver (no schema-less data AND no search index).
  */
-export async function assembleDataBall(distDir, schemalessNames = []) {
+export async function assembleDataBall(distDir, schemalessNames = [], { projections = false } = {}) {
   const schemaless = new Set(schemalessNames)
   const allData = await readJsonTree(join(distDir, 'data'))
   const data = {}
@@ -64,8 +64,48 @@ export async function assembleDataBall(distDir, schemalessNames = []) {
     if (schemaless.has(collectionOf(relPath))) data[relPath] = value
   }
   const search = await readJsonTree(join(distDir, '_search'))
-  if (Object.keys(data).length === 0 && Object.keys(search).length === 0) return null
-  return { data, search }
+
+  // Agent projections ride the same ball — same shape of thing (precomputed
+  // at publish, opaque to the backend, served as-is), just text rather than
+  // JSON. Off by default: what the artifacts are called and how they are
+  // addressed on the serving side is the backend's to specify, and shipping
+  // an unrecognized key into a payload the backend unwraps is not something
+  // to decide unilaterally. Flip this on once that contract is agreed.
+  const projectionFiles = projections ? await readTextTree(distDir) : {}
+
+  const empty =
+    Object.keys(data).length === 0 &&
+    Object.keys(search).length === 0 &&
+    Object.keys(projectionFiles).length === 0
+  if (empty) return null
+
+  return projections ? { data, search, projections: projectionFiles } : { data, search }
+}
+
+/**
+ * Collect the agent projections from a built dist/ — `llms.txt` plus every
+ * `.md` page projection, keyed by their served path.
+ *
+ * Deliberately excludes `node_modules`-shaped noise and anything under the
+ * bundle's own asset directories; a site's `dist/` at this point holds only
+ * what the link lane emitted.
+ *
+ * @param {string} distDir
+ * @returns {Promise<Object<string, string>>}
+ */
+async function readTextTree(distDir) {
+  if (!existsSync(distDir)) return {}
+  const out = {}
+  const entries = await readdir(distDir, { withFileTypes: true, recursive: true })
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const isProjection = entry.name === 'llms.txt' || entry.name.endsWith('.md')
+    if (!isProjection) continue
+    const full = join(entry.parentPath || entry.path, entry.name)
+    const rel = relative(distDir, full).split(sep).join('/')
+    out[rel] = await readFile(full, 'utf8')
+  }
+  return out
 }
 
 // --- local media in the ball -------------------------------------------------

package/src/site/plugin.js

@@ -34,6 +34,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 {
+  renderSiteIndex,
+  renderPageMarkdown,
+  resolveAgentsConfig,
+  selectIndexablePages,
+  pageMarkdownFilename,
+  applyRouteTranslation,
+  INDEX_FILENAME
+} from '@uniweb/projections'
 import { collectSiteContent } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
@@ -187,23 +196,12 @@ async function processDevSectionFetches(sections, fetchOptions) {
 import { generateSearchIndex, isSearchEnabled, getSearchIndexFilename } from '../search/index.js'
 import { mergeTranslations } from '../i18n/merge.js'
 
-/**
- * Translate a canonical route for a given locale using route translations config
- * Supports exact and prefix matching (e.g., /blog → /noticias also applies to /blog/post)
+/*
+ * `applyRouteTranslation` now comes from `@uniweb/projections` (imported
+ * above). It used to be defined here; the agent index builds localized URLs
+ * from the same rule, and two copies would eventually disagree about where a
+ * localized page lives.
  */
-function applyRouteTranslation(route, locale, routeTranslations) {
-  const localeMap = routeTranslations?.[locale]
-  if (!localeMap) return route
-  // Exact match
-  if (localeMap[route]) return localeMap[route]
-  // Prefix match
-  for (const [canonical, translated] of Object.entries(localeMap)) {
-    if (route.startsWith(canonical + '/')) {
-      return translated + route.slice(canonical.length)
-    }
-  }
-  return route
-}
 
 /**
  * Restrict authored `seo.locales` hreflang entries to locales the payload
@@ -577,6 +575,76 @@ export function siteContentPlugin(options = {}) {
     })
   }
 
+  /**
+   * Options shared by every projection call, so the dev middleware and the
+   * build emit cannot drift apart in how they build URLs.
+   */
+  function projectionOptions(content) {
+    const defaultLocale = resolveDefaultLocale(content.config)
+    return {
+      baseUrl: seoOptions.baseUrl,
+      basePath,
+      locale: content.config?.activeLocale || defaultLocale,
+      defaultLocale
+    }
+  }
+
+  /**
+   * Emit `llms.txt` and the per-page `.md` projections.
+   *
+   * Called with the Rollup plugin context, so `this.emitFile` is available.
+   * Sits beside the sitemap and search-index emits because it is the same kind
+   * of thing: an artifact derived from the site's content alone.
+   *
+   * Unlike the SEO artifacts, this does NOT silently skip when `seo.baseUrl`
+   * is unset — it falls back to root-relative links and `uniweb doctor` warns.
+   * An agent that arrived via the index can still follow a relative link, and
+   * a silently-absent index is the failure mode the whole feature exists to
+   * prevent.
+   *
+   * @param {Object} content - Final site content for this locale
+   */
+  function emitProjections(content) {
+    const agents = resolveAgentsConfig(content?.config)
+    if (!agents.index && !agents.markdown) return
+    if (!content?.pages?.length) return
+
+    const options = projectionOptions(content)
+    const localeDir =
+      options.locale && options.defaultLocale && options.locale !== options.defaultLocale
+        ? `${options.locale}/`
+        : ''
+
+    if (agents.index) {
+      this.emitFile({
+        type: 'asset',
+        fileName: `${localeDir}${INDEX_FILENAME}`,
+        source: renderSiteIndex(content, { ...options, exclude: agents.exclude })
+      })
+      console.log(`[site-content] Generated ${localeDir}${INDEX_FILENAME}`)
+    }
+
+    if (agents.markdown) {
+      const pages = selectIndexablePages(content.pages, { exclude: agents.exclude })
+      let emitted = 0
+      for (const page of pages) {
+        const markdown = renderPageMarkdown(page)
+        if (!markdown) continue
+        const route =
+          options.locale !== options.defaultLocale
+            ? applyRouteTranslation(page.route, options.locale, content.config?.i18n?.routeTranslations)
+            : page.route
+        this.emitFile({
+          type: 'asset',
+          fileName: `${localeDir}${pageMarkdownFilename(route)}`,
+          source: markdown
+        })
+        emitted++
+      }
+      if (emitted) console.log(`[site-content] Generated ${emitted} page markdown projections`)
+    }
+  }
+
   return {
     name: 'uniweb:site-content',
 
@@ -928,6 +996,47 @@ export function siteContentPlugin(options = {}) {
           }
         }
 
+        // Serve the agent projections in dev mode.
+        //
+        // Without this the artifacts can only be inspected by deploying, and
+        // `uniweb doctor`'s baseUrl warning describes something invisible
+        // locally. Both routes reuse the build's generators, so what a
+        // developer sees here is what ships.
+        if (siteContent) {
+          const agents = resolveAgentsConfig(siteContent.config)
+          const url = req.url.split('?')[0]
+
+          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 markdownMatch = url.match(new RegExp(`^(?:\\/(${LOCALE_RE}))?\\/(.+)\\.md$`))
+          if (markdownMatch && agents.markdown) {
+            const localized = (markdownMatch[1] ? await getTranslatedContent(markdownMatch[1]) : null) || siteContent
+            const requested = markdownMatch[2] === 'index' ? '/' : `/${markdownMatch[2]}`
+            const pages = selectIndexablePages(localized.pages, { exclude: agents.exclude })
+            const page = pages.find(p => p.route === requested)
+            if (page) {
+              const markdown = renderPageMarkdown(page)
+              if (markdown) {
+                res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
+                res.end(markdown)
+                return
+              }
+            }
+          }
+        }
+
         // Handle localized collection data (e.g., /fr/data/articles.json)
         const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/data\\/(.+\\.json)$`))
         if (localeDataMatch) {
@@ -1234,6 +1343,11 @@ export function siteContentPlugin(options = {}) {
 
         console.log(`[site-content] Generated ${searchFilename} (${searchIndex.count} entries)`)
       }
+
+      // Agent-readable projections: the index (discovery) and per-page
+      // markdown (retrieval). Free and on by default; a site opts out under
+      // `agents:` in site.yml.
+      emitProjections.call(this, finalContent)
     },
 
     closeBundle() {

package/src/uwx/collections-project.js

@@ -43,7 +43,6 @@ import { createTranslationCollector, writeLocaleTranslations, writeFreeformTrans
 import { buildFreeformCollectionPath } from '../i18n/freeform.js'
 
 // Single-record source extensions we scan + place (BibTeX is multi-record → out).
-const SINGLE_RECORD_EXTS = ['.md', '.yml', '.yaml', '.json']
 const EXT_FOR_FORMAT = { md: '.md', yaml: '.yml', json: '.json' }
 
 function formatForExt(ext) {

package/src/uwx/entity-document.js

@@ -68,7 +68,7 @@ export function emitEntitySyncPackage({
   for (const entity of entities) {
     const data = toJsonBuffer(entity.document)
     files.push({ name: entity.file, data })
-    entries.push({
+    const entry = {
       kind: 'entity',
       // `$id` as the handle label — NOT the identity key on the sync lane (the
       // backend reads identity from the body) and never uuid-parsed for entities.
@@ -83,7 +83,39 @@ export function emitEntitySyncPackage({
       updated_at: null,
       file: entity.file,
       sha256: sha256Hex(data),
-    })
+    }
+    // Optimistic-concurrency precondition (the push gate). When present, the
+    // backend compares it against the entity's stored version and refuses the
+    // WHOLE package atomically if it has moved (409 `reason: "stale_base"`),
+    // before any write. OMITTING it is the force path — the backend then falls
+    // back to the `collision` policy. Note `collision=force` does NOT override a
+    // present token: the token wins, so `--force` must DROP this, never flip
+    // `collision`. The value is the opaque RFC3339 `version` the backend stamped
+    // on the entity — read from the pull manifest's top-level `version` or from a
+    // prior push's `finalized[].version`, and never parsed or synthesized here.
+    //
+    // TOP-LEVEL on the entry, beside `sha256` — not nested under an `extra`
+    // object. The backend's Rust struct has an `extra` field but it is
+    // `#[serde(flatten)]`, so those keys serialize beside the others and `extra`
+    // never appears on the wire in either direction. Its pull manifests emit a
+    // top-level `version` for the same reason.
+    //
+    // The backend correlates this to an entity by the BODY's `$uuid`, not by
+    // `entries[].uuid` — which stays the `$id` handle above. Don't be tempted to
+    // write a real uuid into that field to "help": it would make the field mean
+    // two different things depending on sync state, and the backend has no use
+    // for it (it reads identity from the body everywhere else too).
+    if (entity.baseVersion) entry.base_version = entity.baseVersion
+    // Per-ITEM preconditions, keyed by each record's `$uuid`. The entity token
+    // gates the whole document, so a stale base on any one record refuses the
+    // entire push — which fires on the common case of two people editing different
+    // sections. These let the backend accept the records we may touch and refuse
+    // only the ones that genuinely moved. Same rules as the entity token: opaque,
+    // top-level on the entry (no `extra` wrapper), omitted = unconditional.
+    if (entity.itemBaseVersions && Object.keys(entity.itemBaseVersions).length) {
+      entry.item_base_versions = entity.itemBaseVersions
+    }
+    entries.push(entry)
   }
 
   const manifest = buildManifest({

package/src/uwx/index.js

@@ -68,6 +68,15 @@ export {
   localeFilePath,
 } from './locale-sync.js'
 export { emitSyncPackages } from './sync-package.js'
+export {
+  diffSiteUnits,
+  describeSiteDiff,
+  computeUnitHashes,
+  collectSiteUnits,
+  walkSiteUnits,
+  collectUnitUuids,
+  stampUnitUuids,
+} from './site-diff.js'
 export {
   collectionRecordsToEntities,
   buildCollectionEntities,

package/src/uwx/site-diff.js

@@ -0,0 +1,294 @@
+// File-level diff of two `@uniweb/site-content` documents.
+//
+// The push staleness gate is ENTITY-grained: a site's whole page tree is one
+// entity, so a refusal can only say "the document moved". That leaves the user
+// with "pull and lose yours, or force and lose theirs" and no way to judge either.
+// This turns the refusal into an account of which units diverged and which side
+// moved them.
+//
+// THE UNIT IS THE FILE, NOT THE PAGE. A site's content is already split one
+// section per file, so two people editing different sections — even of the SAME
+// page — have not conflicted. Diffing at page granularity reports that as a
+// conflict, and a false conflict is not a harmless imprecision: the only moves it
+// leaves are pulling (loses their work) or forcing (loses the other side's), so it
+// actively pushes people toward the destructive one. Three unit kinds, matching
+// exactly what someone would open:
+//
+//   site.yml                      site info (name, theme, foundation ref)
+//   pages/<route>/page.yml        page metadata (title, slug, section order, …)
+//   pages/<route>/<section>.md    one section — including nested `$children`,
+//                                 which the projector also writes flat here
+//   layout/<section>.md           a layout section
+//
+// Units are DISJOINT: a page's hash excludes its sections, a section's excludes its
+// children, so a change lands in exactly one unit and is never double-reported.
+// Naming comes from the projector's own helpers (`pageDirName`,
+// `safeStableIdFilename`) rather than a local copy, so a label always names a file
+// that really exists.
+//
+// It needs TWO bases, and that is the non-obvious part.
+//
+// Our document and the backend's are not byte-comparable renderings of the same
+// unit: the backend's copy carries fields we don't emit (`params`,
+// `theme_override`, its own `$uuid`) and serializes in its own key order. So a hash
+// taken on our side and one taken on theirs differ for a unit NEITHER side touched.
+// A single base therefore validates exactly one comparison and silently corrupts
+// the other — with a local-representation base every unit looks "changed
+// upstream", which is worse than saying nothing.
+//
+// So each side is compared only against a base in its OWN representation:
+//   local  vs localBase   → did WE change it
+//   remote vs remoteBase  → did THEY change it
+// and local-vs-remote is never compared directly. Both bases are captured at the
+// same two moments (a successful push, a pull) from sources already to hand: our
+// emitted document, and the backend's `finalized[].document` / the pulled document.
+//
+// Either base may be missing; the affected side degrades to "unknown" and is
+// reported as unattributed rather than guessed at.
+
+import { entityContentHash } from './collections.js'
+import { recordStableId, safeStableIdFilename, pageDirName } from './site-project.js'
+import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+
+// A unit's own content, with the nested collections that are their own units
+// removed — so editing a section never also marks its page (or its parent
+// section) as changed.
+const ownContent = (record, ...childKeys) => {
+  const copy = { ...record }
+  for (const k of childKeys) delete copy[k]
+  return copy
+}
+
+/**
+ * Every diffable unit of a site-content document, keyed by the repo-relative path
+ * the projector would write it to.
+ *
+ * Paths use the conventional `pages/` and `layout/` roots. A site that relocates
+ * them via `info.paths` still gets stable, unique keys — only the displayed prefix
+ * would differ from disk, which is a labelling nicety, not a correctness issue.
+ *
+ * @returns {Map<string, object>} path → the unit's own record
+ */
+export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+  const units = new Map()
+  walkSiteUnits(doc, (path, record, kind) => {
+    units.set(
+      path,
+      kind === 'page' ? ownContent(record, 'page_sections', '$children')
+        : kind === 'info' ? ownContent(record)
+          : ownContent(record, '$children')
+    )
+  }, sourceLocale)
+  return units
+}
+
+/**
+ * Walk every unit of a site-content document, handing the callback the path and the
+ * LIVE record (not a copy — mutating it mutates the document).
+ *
+ * The single traversal behind hashing, uuid harvesting, and uuid stamping, so those
+ * three can never disagree about what a unit is or where it lives. A path that
+ * differs between them would silently mis-key a cache.
+ *
+ * @param {(path: string, record: object, kind: 'info'|'page'|'section') => void} cb
+ */
+export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+  const walkSections = (sections, dir) => {
+    for (const record of sections || []) {
+      const id = recordStableId(record)
+      // Anonymous and id-less: the projector cannot place it either, so there is
+      // no file to name and nothing to attribute.
+      if (id) cb(`${dir}/${safeStableIdFilename(id)}.md`, record, 'section')
+      walkSections(record.$children, dir)
+    }
+  }
+  const walkPages = (pages, parentDir) => {
+    for (const record of pages || []) {
+      const dirName = pageDirName(record, sourceLocale)
+      if (!dirName) continue
+      const dir = `${parentDir}/${dirName}`
+      cb(`${dir}/${record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
+      if (record.mode !== 'folder') walkSections(record.page_sections, dir)
+      walkPages(record.$children, dir)
+    }
+  }
+  // `info` is an item too — it carries its own `$uuid` and its own per-item token,
+  // and it holds the site's name, theme and foundation ref. Omitting it left those
+  // ungated (an upstream theme change would not be caught) and invisible in the
+  // diff. It projects to several files (site.yml, theme.yml, head.html); `site.yml`
+  // is the label, since that is where its identity-bearing fields live.
+  if (doc?.info && typeof doc.info === 'object') cb('site.yml', doc.info, 'info')
+  walkPages(doc?.pages, 'pages')
+  walkSections(doc?.layout_sections, 'layout')
+}
+
+/** Per-unit content hashes: `{ <path>: <sha256> }`. */
+export function computeUnitHashes(doc, sourceLocale) {
+  const out = {}
+  for (const [path, record] of collectSiteUnits(doc, sourceLocale)) out[path] = entityContentHash(record)
+  return out
+}
+
+/**
+ * Harvest per-item identity from a document the BACKEND produced (a pull, or a push
+ * response's `finalized[].document`): `{ <path>: <$uuid> }`.
+ *
+ * This is the map that has to be echoed back on the next push. Without it the
+ * backend cannot match our items — a uuid-less record in a `multi` section (which
+ * `pages`, `page_sections` and `layout_sections` all are) is read as new, so it is
+ * inserted and its stored counterpart is deleted. That silently replaces every
+ * page and section identity on every push, which in turn destroys the per-item
+ * handles the app holds for its own concurrency. Identity is not decoration here.
+ */
+export function collectUnitUuids(doc, sourceLocale) {
+  const out = {}
+  walkSiteUnits(doc, (path, record) => {
+    if (typeof record?.$uuid === 'string' && record.$uuid) out[path] = record.$uuid
+  }, sourceLocale)
+  return out
+}
+
+/**
+ * Stamp known `$uuid`s onto a document we are about to push, so the backend matches
+ * our items instead of re-minting them.
+ *
+ * A unit the map doesn't know is left alone: that is genuinely new content on its
+ * first push, and minting is the only coherent reading. The map's absence entirely
+ * is the dangerous case — see `collectUnitUuids` — and the caller is responsible for
+ * not pushing blind (the backend also refuses an all-blank `multi` section).
+ *
+ * @returns {{ stamped: number, unknown: number }}
+ */
+export function stampUnitUuids(doc, pathToUuid = {}, sourceLocale) {
+  let stamped = 0
+  let unknown = 0
+  const seen = new Set()
+  const collisions = []
+  walkSiteUnits(doc, (path, record) => {
+    // Two records can resolve to ONE path when their stable ids collide — most
+    // easily `1-hero.md` and `hero.md` in the same page dir, since the numeric
+    // prefix is stripped. Stamping both with the same uuid produces a package the
+    // backend rejects outright ("a `$uuid` must be unique within the entity"), so
+    // only the first occurrence takes the identity; the rest push as new. The
+    // collision is reported because it is an authoring problem either way — the
+    // projector writes `<stableId>.md`, so a pull would collapse the two files
+    // into one.
+    if (seen.has(path)) {
+      collisions.push(path)
+      unknown++
+      return
+    }
+    seen.add(path)
+    const uuid = pathToUuid[path]
+    if (uuid) {
+      record.$uuid = uuid
+      stamped++
+    } else {
+      unknown++
+    }
+  }, sourceLocale)
+  return { stamped, unknown, collisions }
+}
+
+/**
+ * Compare the local and remote site-content documents unit by unit, attributing
+ * each side's changes against a base in that side's own representation.
+ *
+ * @param {object} localDoc  - the document we were about to push
+ * @param {object} remoteDoc - the backend's current document
+ * @param {object} [bases]
+ * @param {Object<string,string>} [bases.local]  - unit hashes of OUR document as of
+ *        the last sync. Enables "did we change it".
+ * @param {Object<string,string>} [bases.remote] - unit hashes of THEIR document as
+ *        of the last sync. Enables "did they change it". Never compare this against
+ *        a locally-derived hash.
+ * @returns {{
+ *   knowsLocal: boolean, knowsRemote: boolean,
+ *   changedUpstream: string[], changedLocally: string[], changedBoth: string[],
+ *   changedUnattributed: string[],
+ *   addedUpstream: string[], addedLocally: string[], identical: string[],
+ * }} each list holding repo-relative paths, sorted.
+ */
+export function diffSiteUnits(localDoc, remoteDoc, bases = {}) {
+  const localBase = bases.local || {}
+  const remoteBase = bases.remote || {}
+  const knowsLocal = Object.keys(localBase).length > 0
+  const knowsRemote = Object.keys(remoteBase).length > 0
+
+  const local = collectSiteUnits(localDoc)
+  const remote = collectSiteUnits(remoteDoc)
+
+  const out = {
+    knowsLocal, knowsRemote,
+    changedUpstream: [], changedLocally: [], changedBoth: [], changedUnattributed: [],
+    addedUpstream: [], addedLocally: [], identical: [],
+  }
+
+  for (const path of new Set([...local.keys(), ...remote.keys()])) {
+    const l = local.get(path)
+    const r = remote.get(path)
+    // Present on one side only. Set membership is representation-independent, so
+    // these are sound even with no bases at all — and `addedUpstream` is the
+    // dangerous one: forcing does not revert it, it deletes it.
+    if (l && !r) { out.addedLocally.push(path); continue }
+    if (r && !l) { out.addedUpstream.push(path); continue }
+
+    // Each side against its OWN base. A missing base entry is UNKNOWN, not unchanged.
+    const weChanged = knowsLocal && localBase[path] ? entityContentHash(l) !== localBase[path] : null
+    const theyChanged = knowsRemote && remoteBase[path] ? entityContentHash(r) !== remoteBase[path] : null
+
+    // An UNKNOWN side is only worth reporting when the other side doesn't already
+    // settle the question. If the remote is known to sit at its base, this unit is
+    // not contested no matter what we did to it — pushing our version is the whole
+    // point — so "differs, side unknown" would be both untrue and noise. That
+    // combination is the normal state right after a pull (which clears the local
+    // base), which is exactly when a refusal is most likely, so getting it wrong
+    // buried the one contested file under a list of perfectly fine ones.
+    if (weChanged === true && theyChanged === true) out.changedBoth.push(path)
+    else if (theyChanged === true) out.changedUpstream.push(path)
+    else if (weChanged === true) out.changedLocally.push(path)
+    else if (weChanged === null && theyChanged === null) out.changedUnattributed.push(path)
+    else out.identical.push(path)
+  }
+
+  for (const k of Object.keys(out)) if (Array.isArray(out[k])) out[k].sort()
+  return out
+}
+
+/**
+ * Render a diff as the lines a CLI shows after a staleness refusal, ordered by the
+ * cost of getting each one wrong. Returns `[]` when there is nothing to say.
+ */
+export function describeSiteDiff(diff, { limit = 8 } = {}) {
+  const lines = []
+  // Never let a long list silently truncate into something that reads complete.
+  const list = (xs) =>
+    xs.length > limit ? `${xs.slice(0, limit).join(', ')} … and ${xs.length - limit} more` : xs.join(', ')
+
+  if (diff.addedUpstream.length) lines.push(`Added upstream — forcing DELETES these: ${list(diff.addedUpstream)}`)
+  if (diff.changedBoth.length) lines.push(`Changed on both sides: ${list(diff.changedBoth)}`)
+  if (diff.changedUpstream.length) lines.push(`Changed upstream — forcing discards these: ${list(diff.changedUpstream)}`)
+  if (diff.changedLocally.length) lines.push(`Changed by you — pulling discards these: ${list(diff.changedLocally)}`)
+  if (diff.changedUnattributed.length) lines.push(`Differs, side unknown: ${list(diff.changedUnattributed)}`)
+  if (diff.addedLocally.length) lines.push(`Added by you (not upstream yet): ${list(diff.addedLocally)}`)
+
+  // The good news is worth saying — but only when BOTH sides are actually known.
+  // Without the local base we cannot see our own edits, so "nothing was changed on
+  // both sides" would be a claim about evidence we don't have: the user could pull
+  // on the strength of it and lose the very edit they were trying to push. A
+  // reassurance that can't be backed is worse than no reassurance.
+  if (
+    lines.length && diff.knowsLocal && diff.knowsRemote &&
+    !diff.changedBoth.length && !diff.changedUnattributed.length
+  ) {
+    lines.push('No unit was changed on both sides — pulling should merge cleanly.')
+  }
+  // Say which half of the attribution is missing rather than under-reporting silently.
+  if (lines.length && !diff.knowsRemote) {
+    lines.push("No record of the backend's last state, so upstream edits to existing units are not listed.")
+  }
+  if (lines.length && !diff.knowsLocal) {
+    lines.push('No record of your last sync, so your own edits are not listed.')
+  }
+  return lines
+}