uniweb 1.12.0 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/semantic-parser": "~1.12.0",
-    "@uniweb/core": "~1.3.0",
     "@uniweb/content-writer": "~1.3.0",
-    "@uniweb/schemas": "~1.5.0"
+    "@uniweb/schemas": "~1.5.0",
+    "@uniweb/semantic-parser": "~1.12.0",
+    "@uniweb/core": "~1.3.0"
   },
   "peerDependencies": {
+    "@uniweb/content-reader": "~1.5.2",
     "@uniweb/semantic-parser": "~1.12.0",
-    "@uniweb/content-reader": "~1.5.1",
-    "@uniweb/build": "~1.5.0"
+    "@uniweb/build": "~1.5.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -2848,9 +2848,9 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 - **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
 - **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
 
-**Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. `uniweb refresh` runs `git pull` first, then the same pull. A push is also refused when your branch does not hold what this copy last took from the backend — after `git merge --abort`, or in a fresh clone that has not pulled — so pull, then push. Outside git — which includes a folder the repository around it ignores, such as a scratch directory — `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
+**Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. **In a git repository a push sends what you have committed:** with the site's content not committed it is refused before anything is sent, naming the files — commit them, or run `uniweb push --commit -m "…"` (it commits the site's content only, and leaves anything else staged as it is); `publish` and `sync` take `--commit` too. That commit is where the next pull merges from, which is how the pull tells your changes from the backend's. What the push writes back into the files — the ids the backend assigned — it commits itself, as `uniweb`. When the backend has nothing new, a pull says so and lists the files where yours hold changes it lacks. `uniweb refresh` runs `git pull` first, then the same pull. A push is also refused when your branch does not hold what this copy last took from the backend — after `git merge --abort`, or in a fresh clone that has not pulled — so pull, then push. Outside git — which includes a folder the repository around it ignores, such as a scratch directory — `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 
-**`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. Commit it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --server <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --server <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--server` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
+**`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. In a git repository the push commits it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --server <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --server <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--server` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
 
 **`services:` in `site.yml` is where a site says which services it uses** — site search, form
 handling, analytics, an assistant, accounts — one entry per service:

package/src/backend/commit-before-sending.js

@@ -0,0 +1,49 @@
+/**
+ * `--commit` on the verbs that send a site — `push` and `publish` (and `sync`, through its
+ * push). In a repository they send what is committed (`uncommittedContent`,
+ * backend/site-sync.js); this is the stop where it is not, and the commit that makes it so.
+ *
+ * Its own module so the flags it reads stay out of the import graph of every verb that only
+ * shares site-sync.js — `pull`, `status`, `refresh` take no `--commit`
+ * (`test/flag-guard-coverage.test.js`).
+ */
+
+import { uncommittedContent, commitSiteContent } from './site-sync.js'
+
+/**
+ * The stop before a push or publish sends anything, where the site's content is not
+ * committed — or, with `--commit`, the commit that makes it so, which a dry run only says.
+ * Returns `{ exitCode }` to stop, or null to go on.
+ */
+export function commitBeforeSending(siteDir, args, { verb, dryRun, say }) {
+  const pending = uncommittedContent(siteDir, { verb })
+  if (!pending) return null
+  if (!args.includes('--commit') || pending.merge) {
+    say.error(pending.headline)
+    for (const line of pending.lines) say.note(line)
+    return { exitCode: 1 }
+  }
+  if (dryRun) {
+    say.info(`Dry run — would commit ${pending.paths.length} file(s) of the site first.`)
+    return null
+  }
+  const made = commitSiteContent(siteDir, { message: commitMessage(args) })
+  if (made.error) {
+    say.error("Could not commit the site's content:")
+    for (const line of String(made.error).split('\n').slice(0, 8)) say.note(`  ${line}`)
+    return { exitCode: 1 }
+  }
+  if (made.commit) say.success(`Committed ${made.paths.length} file(s) of the site — ${made.commit.slice(0, 7)}`)
+  return null
+}
+
+/** `-m` / `--message` for `--commit`, as `git commit` takes it. */
+function commitMessage(args) {
+  for (const name of ['-m', '--message']) {
+    const eq = args.find((a) => a.startsWith(`${name}=`))
+    if (eq) return eq.slice(name.length + 1)
+    const i = args.indexOf(name)
+    if (i !== -1 && args[i + 1] != null) return args[i + 1]
+  }
+  return "Update the site's content"
+}

package/src/backend/site-sync.js

@@ -20,6 +20,10 @@ import {
   writeSyncPoint,
   isAncestor,
   contentCommitted,
+  uncommittedPaths,
+  commitRoots,
+  gitError,
+  RECORDED_TRAILER,
   unmergedPaths,
   mergeInProgress
 } from '../utils/sync-point.js'
@@ -64,7 +68,11 @@ import {
   LINK_MODEL,
   bankedFileUuids,
   existingSectionFile,
-  layoutUnitFile
+  layoutUnitFile,
+  siteContentRemovals,
+  recordRemovals,
+  cleanedRecord,
+  SYNC_STORE_FILE
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -84,6 +92,26 @@ function entityDocFromUwx(buf) {
   return null
 }
 
+// Every entity `$`-document of a `.uwx` in the order it was submitted — the manifest's, which is
+// what a push's `finalized[].index` counts in. null where a listed file is missing or unreadable.
+function submittedDocsFromUwx(buf) {
+  if (!buf || buf.length < 2 || buf[0] !== 0x50 || buf[1] !== 0x4b) return []
+  const files = readZip(buf)
+  let entries
+  try {
+    entries = JSON.parse(files.get('manifest.json')?.toString('utf8') ?? '{}').entries
+  } catch {
+    return []
+  }
+  return (Array.isArray(entries) ? entries : []).map((entry) => {
+    try {
+      return JSON.parse(files.get(entry?.file).toString('utf8'))
+    } catch {
+      return null
+    }
+  })
+}
+
 // Every entity `$`-document of a `.uwx` — the folder lane holds the folder and its records.
 function entityDocsFromUwx(buf) {
   const docs = []
@@ -223,6 +251,10 @@ function writtenAsSent(sent, written) {
  * (`siteItemsByKey`), and it replaces the one held before:
  *
  *   - an item the backend holds as we sent it → its new version;
+ *   - an item it holds as we sent it once cleaned to the rich-text vocabulary → its new version
+ *     too: what a backend that cleans at write removed is not someone else's content
+ *     (`cleanedRecord`). ⛔ Until 2026-10-18 it was, so a push with a link the store removed
+ *     said the section had changed on the backend, and kept the version for what was sent;
  *   - an item we sent that it kept for someone else → the version we held, for OUR content;
  *   - an item it holds that we did not send → the version we held, if we had seen it, and
  *     none if we had not (a unit of it is `foreign`);
@@ -232,7 +264,7 @@ function writtenAsSent(sent, written) {
  * the backend returned it — harmless only while none of them was ever sent.
  *
  * A service is compared by its switch and its whole `config` (`sameServiceRow`), every
- * other item on the keys we sent (`writtenAsSent`).
+ * other item on the keys we sent (`writtenAsSent`), as sent or as cleaned.
  *
  * With either document missing there is nothing to compare, and with no versions
  * returned (an older backend) nothing to bank: `itemVersions` is null, and the versions
@@ -255,7 +287,8 @@ export function heldTokens({ sent, written, version = null, itemVersions = null,
   const prior = before && typeof before === 'object' ? before : {}
   const ours = siteItemsByKey(sent)
   const theirs = siteItemsByKey(written)
-  const same = (key, a, b) => (key.startsWith('services:') ? sameServiceRow(a, b) : writtenAsSent(a, b))
+  const same = (key, a, b) =>
+    key.startsWith('services:') ? sameServiceRow(a, b) : writtenAsSent(a, b) || writtenAsSent(cleanedRecord(a), b)
   const held = []
   const kept = []
   const foreign = []
@@ -371,7 +404,10 @@ export function extractFinalized(payload) {
         d?.item_versions && typeof d.item_versions === 'object'
           ? d.item_versions
           : null,
-      document: d?.document ?? null
+      document: d?.document ?? null,
+      // What a backend that cleans rich text at write removed from what was sent, each
+      // `{ $uuid, field, path, rule }` — the key absent when nothing was (`uwx/cleaned.js`).
+      ...(Array.isArray(d?.cleaned) && d.cleaned.length ? { cleaned: d.cleaned } : {})
     }))
     .filter((e) => Number.isInteger(e.index) && e.uuid)
 }
@@ -1002,11 +1038,136 @@ export function untakenBase(siteDir, backend) {
 export function holdUnchangedPush(siteDir, backend) {
   const repo = repoOf(siteDir)
   if (!repo?.head || !readBackendState(siteDir, backend).site?.uuid) return null
-  if (!contentCommitted(repo, [...siteContentRoots(siteDir), 'public'])) return null
+  if (!contentCommitted(repo, sentRoots(siteDir))) return null
   writeSyncPoint(siteDir, backend, repo.head)
   return repo.head
 }
 
+/** What a push sends from the files: the site's content, and its media (`public/`). */
+export const sentRoots = (siteDir) => [...siteContentRoots(siteDir), 'public']
+
+/**
+ * ⛔ IN A REPOSITORY, A PUSH SENDS WHAT IS COMMITTED. The commit a push is made from is where
+ * the next pull merges from — this copy's, and every copy the backend names it to — so what
+ * the push sends must be what that commit holds. Returns the refusal, or null: outside a
+ * repository nothing is kept to merge from.
+ *
+ * ⛔ Until 2026-10-18 a push sent uncommitted edits on top of HEAD and recorded HEAD. Measured
+ * against a real backend: an edit pushed that way and undone before the next pull came back
+ * with it — exit 0, no conflict, reported as the backend's change. Every such push also had
+ * the next pull commit those edits as the backend's, and conflict with one changed again.
+ */
+export function uncommittedContent(siteDir, { verb = 'push' } = {}) {
+  const repo = repoOf(siteDir)
+  if (!repo) return null
+  const paths = uncommittedPaths(repo, sentRoots(siteDir))
+  if (!paths?.length) return null
+  const done = verb === 'publish' ? 'published' : 'pushed'
+  // A merge waiting for its commit is finished with one, never by committing a part of it.
+  if (mergeInProgress(repo)) {
+    return {
+      paths,
+      merge: true,
+      headline: `Not ${done} — a merge is in progress here.`,
+      lines: [`Finish it (\`git commit\`), then ${verb} — or abandon it (\`git merge --abort\`) and pull again.`]
+    }
+  }
+  // ⭐ A repository with no commit yet is still the one that will hold the site's history —
+  // and holds none of it, so every file is listed as not committed. Said as that, not as
+  // edits. ⛔ Not taken for a folder outside git: its first push would keep nothing to merge
+  // from, and the pull after its first commit would read every difference as a conflict.
+  if (!repo.head) {
+    return {
+      paths,
+      headline: `Not ${done} — this repository has no commit yet, so none of the site's ${paths.length} file(s) is committed.`,
+      lines: [
+        `In a repository a ${verb} sends what you have committed, so a later pull can tell your changes from the backend's.`,
+        `Commit the site, then ${verb} again — or re-run with --commit (and -m "…") to make that first commit.`
+      ]
+    }
+  }
+  return {
+    paths,
+    headline: `Not ${done} — ${paths.length} file(s) of the site are not committed:`,
+    lines: [
+      ...paths.slice(0, 12).map((p) => `  ${p}`),
+      ...(paths.length > 12 ? [`  … and ${paths.length - 12} more`] : []),
+      `In a repository a ${verb} sends what you have committed, so a later pull can tell your changes from the backend's.`,
+      `Commit them, then ${verb} again — or re-run with --commit (and -m "…") to commit them first.`
+    ]
+  }
+}
+
+/** Says what `commitWriteBacks` committed, or that it could not. */
+export function reportWriteBacks(made, { note }) {
+  if (!made) return
+  if (made.error) {
+    note('! Could not commit what the push wrote into your files — commit them yourself:')
+    for (const line of String(made.error).split('\n').slice(0, 4)) note(`  ${line}`)
+    return
+  }
+  note(`Committed what the backend gave the site — ${made.paths.length} file(s), ${made.commit.slice(0, 7)}.`)
+}
+
+/**
+ * `--commit`: the site's content committed as the files hold it — the person's own commit,
+ * of what a push sends and nothing else they have staged.
+ *
+ * @returns {{ commit: string|null, paths?: string[] } | { error: string }}
+ */
+export function commitSiteContent(siteDir, { message }) {
+  const repo = repoOf(siteDir)
+  if (!repo) return { commit: null }
+  if (mergeInProgress(repo)) return { error: 'A merge is in progress here — finish it (`git commit`) first.' }
+  try {
+    return commitRoots(repo, sentRoots(siteDir), { message }) || { commit: null }
+  } catch (err) {
+    return { error: gitError(err) }
+  }
+}
+
+/**
+ * ⭐ A PUSH COMMITS WHAT IT WROTE. It writes what the backend gave it into the site's files —
+ * the ids it minted, into each new record's file and `sync.json` — and in a repository it
+ * commits those writes as uniweb's own, as a pull's merge is. The content was committed
+ * before it was sent, so what changed under the site since is the push's. That commit holds
+ * what the backend now holds, so once every lane landed it is this copy's sync point.
+ *
+ * ⛔ Until 2026-10-18 they were left to the person to commit, and a project pushed once and
+ * not committed after had no `sync.json` in the history its clones got.
+ *
+ * @returns {{ commit: string, paths: string[] } | { error: string } | null}
+ */
+export function commitWriteBacks(siteDir, backend, { complete = false } = {}) {
+  const repo = repoOf(siteDir)
+  if (!repo?.head || mergeInProgress(repo)) return null
+  let host = 'backend'
+  try {
+    host = new URL(backend).host
+  } catch {
+    /* the name only */
+  }
+  const identity = {
+    GIT_AUTHOR_NAME: 'uniweb',
+    GIT_AUTHOR_EMAIL: `sync@${host}`,
+    GIT_COMMITTER_NAME: 'uniweb',
+    GIT_COMMITTER_EMAIL: `sync@${host}`
+  }
+  try {
+    // ⭐ Marked with the backend and the site, so a pull reads the commit a lane names through
+    // it (`recordedAfter`, utils/sync-point.js): the ids written back are what the backend holds.
+    const site = readBackendState(siteDir, backend).site?.uuid
+    const made = commitRoots(repo, [...sentRoots(siteDir), SYNC_STORE_FILE], {
+      message: `Record what ${backend} gave the site${site ? `\n\n${RECORDED_TRAILER}: ${backend} ${site}` : ''}`,
+      identity
+    })
+    if (made && complete) writeSyncPoint(siteDir, backend, made.commit)
+    return made
+  } catch (err) {
+    return { error: gitError(err) }
+  }
+}
+
 /**
  * Per-unit content hashes of the last synced state, kept in BOTH representations —
  * the bases for the file-level attribution shown after a staleness refusal
@@ -1976,8 +2137,9 @@ const TEMPLATE_SAID = {
  * @param {object} params.pkg - the `emitSyncPackages` result
  *        ({ siteContent, collections, siteContentUuid, hashes })
  * @param {{info,note,error,dim?:Function}} params.report - injected logging
- * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[] }>}
+ * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[], complete?: true }>}
  *   exitCode 1 on any lane failure (already reported, cache NOT persisted); 0 on success.
+ *   `complete` once every lane with something to send has landed.
  */
 export async function pushSyncPackages({
   client,
@@ -1995,8 +2157,10 @@ export async function pushSyncPackages({
   let draftsNotKept = []
   // ⭐ THE COMMIT THIS PUSH IS MADE FROM — sent with each lane, so the backend can name it on
   // a pull, and kept here as this copy's sync point once a lane lands: what the backend
-  // holds descends from it (`utils/sync-point.js`). ⚖️ Uncommitted edits ride on top of it,
-  // and it stays a safe base for them — both sides hold them, so a merge takes them once.
+  // holds descends from it (`utils/sync-point.js`). In a repository it is exactly what is
+  // sent: a push sends only committed content (`uncommittedContent`). ⛔ Until 2026-10-18
+  // uncommitted edits rode on top of it, and this said it "stays a safe base for them" — but
+  // one undone before the next pull read as no change against it, and the pull put it back.
   const repo = repoOf(siteDir)
   const source = repo?.head || null
 
@@ -2314,10 +2478,14 @@ export async function pushSyncPackages({
   }
   // Both grains land together, at every point the old code banked the entity one — and
   // with them the commit they describe.
-  const mergeHarvested = () => {
+  // ⛔ `point: false` where a lane was refused after another landed: the commit then describes
+  // one lane and not the other, and as the base it would read what the refused lane lacks as
+  // the backend's removal — measured, a pull after a push whose records were refused reverted
+  // the record edits, exit 0. The versions of the lane that landed are still banked.
+  const mergeHarvested = ({ point = true } = {}) => {
     mergeBaseVersions(siteDir, client.origin, newVersions)
     if (heldItemVersions) writeItemBaseVersions(siteDir, client.origin, heldItemVersions)
-    if (source && (Object.keys(newVersions).length || heldItemVersions)) writeSyncPoint(siteDir, client.origin, source)
+    if (point && source && (Object.keys(newVersions).length || heldItemVersions)) writeSyncPoint(siteDir, client.origin, source)
   }
   // ⛔ The site-content lane banks only the tokens for content this copy holds — the
   // document we sent against the one the backend stored (`heldTokens`, and the two
@@ -2325,6 +2493,25 @@ export async function pushSyncPackages({
   // collected here, to re-base attribution and to say so.
   const sentSiteDoc = siteContent ? entityDocFromUwx(siteContent.buffer) : null
   const notHeld = { kept: [], foreign: [] }
+  // ⭐ WHAT THE BACKEND REMOVED, beside the file it came from. A backend that cleans each
+  // rich-text write to the vocabulary answers what it took out of each item
+  // (`finalized[].cleaned`). The push never writes the returned document over the file, so the
+  // file still holds it, and only this says so — on every push that sends it again.
+  let toldRemoved = false
+  const reportRemovals = (removals) => {
+    for (const r of removals) note(`! ${r.where}${r.locale ? ` (${r.locale})` : ''}: ${r.says}`)
+    if (removals.length && !toldRemoved) {
+      note('Your files still hold what the backend removed; a pull would write them without it.')
+      toldRemoved = true
+    }
+  }
+  const reportSiteContentRemovals = (finalized) =>
+    reportRemovals(
+      siteContentRemovals({ finalized, sent: sentSiteDoc }).map((r) => ({
+        ...r,
+        where: r.unit ? unitFilesOf(siteDir, r.unit)[0] || r.unit : 'the site'
+      }))
+    )
   const harvestSiteContent = (finalized) => {
     for (const f of finalized || []) {
       const held = heldTokens({
@@ -2438,6 +2625,7 @@ export async function pushSyncPackages({
         return { exitCode: 1, finalizedTotal, wrote }
       }
       harvestSiteContent(finalized)
+      reportSiteContentRemovals(finalized)
       siteFinalizedDoc = finalized[0]?.document || null
       finalizedTotal += finalized.length
       settleSiteContent()
@@ -2472,6 +2660,7 @@ export async function pushSyncPackages({
         wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
       harvestSiteContent(createdFinalized)
+      reportSiteContentRemovals(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
       finalizedTotal += createdFinalized?.length ?? 1
       settleSiteContent()
@@ -2496,10 +2685,17 @@ export async function pushSyncPackages({
       { boundUuid: boundSiteUuid }
     )
     if (!finalized) {
-      mergeHarvested()
+      mergeHarvested({ point: false })
       return { exitCode: 1, finalizedTotal, wrote }
     }
     harvest(finalized)
+    reportRemovals(
+      recordRemovals({ finalized, sent: submittedDocsFromUwx(records.buffer) }).map((r) => {
+        const entry = records.index?.[r.index]
+        const file = entry?.sourceFile
+        return { ...r, where: file ? (isAbsolute(file) ? relative(siteDir, file) : file) : entry?.id || 'a record' }
+      })
+    )
     const bf = backfillEntityUuids({ index: records.index, finalized })
     // ⭐ Record which uuid THIS backend minted for each record, keyed by the record's
     // own id. The file keeps that own id; the next push to this backend sends the
@@ -2597,7 +2793,7 @@ export async function pushSyncPackages({
         shown.join('\n  ') +
         '\n  The backend does not support `draft: true` yet. Once it does, push again with --all.'
     )
-    return { exitCode: 1, boundSiteUuid, finalizedTotal, wrote }
+    return { exitCode: 1, boundSiteUuid, finalizedTotal, wrote, complete: true }
   }
-  return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
+  return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote, complete: true }
 }

package/src/commands/publish.js

@@ -37,6 +37,9 @@
  *   uniweb publish --dry-run       Resolve everything; POST nothing
  *   uniweb publish --yes           Skip confirmations (CI); never block on a prompt
  *   uniweb publish --force         Overwrite upstream app-side edits (drop the push gate)
+ *   uniweb publish --commit [-m <message>]
+ *                                  In a repository, commit the site's content first — a
+ *                                  publish there sends only what is committed
  *   uniweb publish --org @org      Work in @org for this publish, instead of the
  *   uniweb publish --personal      workspace chosen at `uniweb login` (or your
  *                                  personal workspace). A site it creates is created
@@ -105,9 +108,13 @@ import {
   clearRemoteSyncStateIfUnbound,
   untakenBase,
   unsettledFiles,
+  commitWriteBacks,
+  reportWriteBacks,
   dropSiteBoundValues,
   pushSyncPackages
 } from '../backend/site-sync.js'
+import { repoOf } from '../utils/sync-point.js'
+import { commitBeforeSending } from '../backend/commit-before-sending.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import {
@@ -334,6 +341,16 @@ export async function publish(args = []) {
     for (const line of unsettled.lines) say.dim(line)
     return { exitCode: 1 }
   }
+  // ⛔ In a repository a publish sends what is committed (`uncommittedContent`), whatever the
+  // flags. `--commit` commits it first; a dry run says it would.
+  {
+    const stop = commitBeforeSending(siteDir, args, {
+      verb: 'publish',
+      dryRun,
+      say: { success: say.ok, info: say.info, error: say.err, note: say.dim }
+    })
+    if (stop) return stop
+  }
   if (!dryRun && !args.includes('--force')) {
     const untaken = untakenBase(siteDir, client.origin)
     if (untaken) {
@@ -711,7 +728,9 @@ export async function publish(args = []) {
       const rec = updateBackendMap(siteDir, client.origin, 'assets', ids, carryServed)
       if (rec.written) {
         say.dim(
-          `${SYNC_STORE_FILE}   : ${rec.added.length} asset(s) added, ${rec.changed.length} changed — commit it`
+          `${SYNC_STORE_FILE}   : ${rec.added.length} asset(s) added, ${rec.changed.length} changed` +
+            // In a repository the publish commits it (`commitWriteBacks`).
+            (repoOf(siteDir) ? '' : ' — commit it')
         )
       }
       if (ballAssets.length) ball = rewriteSchemalessDataAssets(ball, map)
@@ -955,6 +974,8 @@ export async function publish(args = []) {
     pkg,
     report
   })
+  // What the push wrote into the files is committed, whatever became of the lanes.
+  reportWriteBacks(commitWriteBacks(siteDir, client.origin, { complete: pushResult.complete }), { note: say.dim })
   if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
   const siteUuid = pushResult.boundSiteUuid
   if (!siteUuid) {

package/src/commands/pull.js

@@ -106,7 +106,7 @@ import {
   writeFolderItemUuids
 } from '../backend/site-sync.js'
 import { resolveWorkspace } from '../backend/workspace.js'
-import { siteContentRoots } from '../utils/git.js'
+import { siteContentRoots, siteLaneRoots } from '../utils/git.js'
 import {
   repoOf,
   mergeInProgress,
@@ -115,12 +115,13 @@ import {
   isAncestor,
   historySyncPoint,
   madeOnto,
-  newestBase,
+  baseFor,
   openStandIn,
   mergeSyncPoint,
   takeSyncPoint,
   snapshotFiles,
   changedInFiles,
+  filesDifferFrom,
   readSyncPoint,
   writeSyncPoint
 } from '../utils/sync-point.js'
@@ -904,14 +905,25 @@ export async function pull(args = [], deps = {}) {
   let onto = null
   let standIn = null
   if (repo && projected) {
-    base = newestBase(repo, [
+    // The bases this copy knows of itself — then what the backend names, per lane.
+    const known = [
       historySyncPoint(repo, { origin: client.origin, siteUuid: siteContentUuid }),
       held,
       // What a sync point the branch no longer holds — a merge abandoned — was made onto.
-      ...madeOnto(repo, held, { origin: client.origin, siteUuid: siteContentUuid }),
-      content?.source,
-      folderLane?.source
-    ])
+      ...madeOnto(repo, held, { origin: client.origin, siteUuid: siteContentUuid })
+    ]
+    const laneRoots = siteLaneRoots(siteDir)
+    const taken = (lane) => lane && !lane.notModified && !lane.refused
+    base = baseFor(repo, {
+      known,
+      // ⛔ What each lane the backend answered names is a base only where every lane holds it (`baseFor`).
+      lanes: [
+        ...(taken(content) ? [{ source: content.source, roots: laneRoots.content }] : []),
+        ...(taken(folderLane) ? [{ source: folderLane.source, roots: laneRoots.records }] : [])
+      ],
+      origin: client.origin,
+      siteUuid: siteContentUuid
+    })
     onto = force || !base ? repo.head : base
     try {
       standIn = openStandIn(repo, { roots, rev: onto })
@@ -1136,6 +1148,9 @@ export async function pull(args = [], deps = {}) {
         siteUuid: siteContentUuid,
         always: force || !base
       })
+      // The commit that holds the backend's content as the files would — the base itself when
+      // they hold the same.
+      merge.theirs = made.commit || base
       if (!made.commit) {
         // The backend holds what the base holds: nothing to merge.
         writeSyncPoint(siteDir, client.origin, base)
@@ -1170,6 +1185,8 @@ export async function pull(args = [], deps = {}) {
         } else {
           merge.conflicted = result.conflicted || []
           merge.stashKept = Boolean(result.stashKept)
+          // Whether anything was set aside for the merge: the files as they were, against HEAD.
+          merge.setAside = files !== repo.head
           merge.noBase = !force && !base
           merge.changed = changedInFiles(repo, {
             from: repo.head,
@@ -1249,7 +1266,16 @@ export async function pull(args = [], deps = {}) {
       if (merge.changed.length > 12) note(`  … and ${merge.changed.length - 12} more`)
       if (force) note('What they held is in the commit before this one (`git diff HEAD^1 HEAD`), unless it was never committed.')
     } else if (!merge.conflicted.length) {
-      note(`Your files already hold what ${client.origin} has.`)
+      // ⛔ Nothing changed in the files is not the files holding what the backend has: what
+      // this copy changed since the base, the backend lacks. Until 2026-10-18 it said they
+      // held it either way — measured over a revert the backend did not have yet.
+      const ahead = merge.theirs ? filesDifferFrom(repo, merge.theirs, roots) : []
+      if (!ahead.length) note(`Your files already hold what ${client.origin} has.`)
+      else {
+        note(`Nothing new from ${client.origin}. ${ahead.length} file(s) here hold changes it does not have yet — \`uniweb push\` sends them:`)
+        for (const p of ahead.slice(0, 12)) note(`  ${p}`)
+        if (ahead.length > 12) note(`  … and ${ahead.length - 12} more`)
+      }
     }
     if (merge.conflicted.length) {
       error(`${merge.conflicted.length} file(s) have conflicts to resolve:`)
@@ -1264,7 +1290,9 @@ export async function pull(args = [], deps = {}) {
           note("your changes from the backend's: each file where they differ is a conflict, yours against the backend's.")
           note('Once this merge is committed, later pulls merge from it.')
         }
-        note('Settle them and `git add` each, then `git commit` to finish the merge — your uncommitted changes come back with it.')
+        note(
+          `Settle them and \`git add\` each, then \`git commit\` to finish the merge${merge.setAside ? ' — your uncommitted changes come back with it' : ''}.`
+        )
       }
     }
   }

package/src/commands/push.js

@@ -37,6 +37,8 @@
  *   uniweb push --foundation <dir>       Use this local foundation for the Model schema
  *   uniweb push --all                    Send every record (bypass the changed-only cache)
  *   uniweb push --force                  Overwrite upstream changes (drop the staleness gate)
+ *   uniweb push --commit [-m <message>]  In a repository, commit the site's content first —
+ *                                        a push there sends only what is committed
  *   uniweb push --no-release             Send content against the foundation already
  *                                        released; release nothing
  *   uniweb push --bump                   Release above a newer registered version
@@ -78,6 +80,7 @@ import { confirm, isNonInteractive } from '../utils/interactive.js'
 import { announceServices, foundationSupports } from '../backend/service-request.js'
 import { guardEmptyRecords } from '../utils/records-guard.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
+import { repoOf } from '../utils/sync-point.js'
 import {
   makeModelResolver,
   readSyncCache,
@@ -97,9 +100,12 @@ import {
   dropSiteBoundValues,
   untakenBase,
   unsettledFiles,
+  commitWriteBacks,
+  reportWriteBacks,
   holdUnchangedPush,
   pushSyncPackages
 } from '../backend/site-sync.js'
+import { commitBeforeSending } from '../backend/commit-before-sending.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
@@ -223,6 +229,12 @@ export async function push(args = [], deps = {}) {
     for (const line of unsettled.lines) note(line)
     return { exitCode: 1 }
   }
+  // ⛔ In a repository a push sends what is committed (`uncommittedContent`), whatever the
+  // flags but `-o`, which sends nothing. `--commit` commits it first; a dry run says it would.
+  if (!output) {
+    const stop = commitBeforeSending(siteDir, args, { verb: 'push', dryRun, say: { success, info, error, note } })
+    if (stop) return stop
+  }
   if (!output && !force) {
     const untaken = untakenBase(siteDir, client.origin)
     if (untaken) {
@@ -514,8 +526,10 @@ export async function push(args = [], deps = {}) {
         // carries only the refs its content touched.
         const rec = updateBackendMap(siteDir, client.origin, 'assets', ids, carryServed)
         if (rec.written) {
+          // In a repository the push commits it (`commitWriteBacks`).
           note(
-            `${SYNC_STORE_FILE}: ${rec.added.length} asset(s) added, ${rec.changed.length} changed — commit it`
+            `${SYNC_STORE_FILE}: ${rec.added.length} asset(s) added, ${rec.changed.length} changed` +
+              (repoOf(siteDir) ? '' : ' — commit it')
           )
         }
       } catch (err) {
@@ -626,7 +640,11 @@ export async function push(args = [], deps = {}) {
     )
     // ⭐ And so the backend holds what this commit sends: it is where the next pull merges
     // from (`holdUnchangedPush`). Not for a preview, which keeps nothing.
-    if (!output && !dryRun) holdUnchangedPush(siteDir, client.origin)
+    if (!output && !dryRun) {
+      holdUnchangedPush(siteDir, client.origin)
+      // What it recorded on the way — a media map, an identity recovered — is committed too.
+      reportWriteBacks(commitWriteBacks(siteDir, client.origin), { note })
+    }
     return { exitCode: 0 }
   }
   if (siteContent)
@@ -683,10 +701,16 @@ export async function push(args = [], deps = {}) {
       dim: (s) => `${colors.dim}${s}${colors.reset}`
     }
   })
-  if (result.exitCode !== 0) return { exitCode: result.exitCode }
+  // What the push wrote into the files is committed, whatever became of the lanes.
+  const written = commitWriteBacks(siteDir, client.origin, { complete: result.complete })
+  if (result.exitCode !== 0) {
+    reportWriteBacks(written, { note })
+    return { exitCode: result.exitCode }
+  }
   success(
     `Pushed ${result.finalizedTotal} entit${result.finalizedTotal === 1 ? 'y' : 'ies'}` +
       (result.wrote.length ? ` — ${result.wrote.join(', ')}` : '')
   )
+  reportWriteBacks(written, { note })
   return { exitCode: 0 }
 }

package/src/commands/sync.js

@@ -35,6 +35,9 @@
  *   uniweb sync                    refresh, then push
  *   uniweb sync --no-git           skip the git remote half of the refresh
  *   uniweb sync --force            forwarded to push (overwrite upstream changes)
+ *   uniweb sync --commit [-m <msg>]
+ *                                  forwarded to push (commit the site's content first —
+ *                                  in a repository a push sends only what is committed)
  */
 
 import { checkFlags } from '../utils/flag-guard.js'
@@ -73,8 +76,9 @@ export async function sync(args = [], deps = {}) {
 
   // `--force` means "overwrite upstream" and belongs to the push half only. Passing
   // it to the refresh would ask pull to DISCARD the local work this command exists
-  // to send — the same word meaning opposite things on the two halves.
-  const refreshArgs = args.filter((a) => a !== '--force')
+  // to send — the same word meaning opposite things on the two halves. `--commit` and
+  // its message are the push's too: the refresh merges with the work as it is.
+  const refreshArgs = pushOnly(args)
 
   const r = await refresh(refreshArgs, { skipFlagCheck: true })
   if (r?.exitCode) {
@@ -90,4 +94,19 @@ export async function sync(args = [], deps = {}) {
   return { exitCode: p?.exitCode ?? 0 }
 }
 
+/** The argv without the push half's own flags — `--force`, `--commit`, `-m <message>`. */
+function pushOnly(args) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--force' || a === '--commit' || a.startsWith('-m=') || a.startsWith('--message=')) continue
+    if (a === '-m' || a === '--message') {
+      i++ // its value
+      continue
+    }
+    out.push(a)
+  }
+  return out
+}
+
 export default sync

package/src/framework-index.json

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-18T21:49:47.266Z",
+  "generatedAt": "2026-10-19T02:42:59.650Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.5.2"
     },
     "@uniweb/build": {
-      "version": "1.5.0"
+      "version": "1.5.1"
     },
     "@uniweb/content-reader": {
-      "version": "1.5.1"
+      "version": "1.5.2"
     },
     "@uniweb/content-writer": {
       "version": "1.3.0"

package/src/index.js

@@ -1470,6 +1470,8 @@ ${colors.bright}Options:${colors.reset}
                      bind to, and the app cannot open such a site.
   --bump             When the registry holds a newer version of the foundation
                      than yours, release yours above it instead of stopping
+  --commit           In a git repository, commit the site's content first
+                     (-m <message>) — a publish there sends only what is committed
   --no-save          Do not record this deploy in deploy.yml
   --no-validate      Skip the content-conformance check, which stops a publish
                      whose content does not conform to its data schemas
@@ -2105,6 +2107,8 @@ ${colors.bright}Push Options:${colors.reset}
   --no-release       Send content against the already-released code; release nothing
   --bump             Release above a newer registered foundation version
   --force            Overwrite upstream changes (drop the staleness gate)
+  --commit           In a git repository, commit the site's content first (-m <message>);
+                     a push there sends only what is committed
   --all              Send every record (bypass the changed-only cache)
   --org @org         Work in @org for this push, not your login's workspace
   --personal         Work in your personal workspace for this push
@@ -2115,6 +2119,7 @@ ${colors.bright}Publish Options:${colors.reset}
   --yes              Skip confirmations (CI); never block on a prompt
   --no-release       Ship content against the already-released code; release nothing
   --bump             Release above a newer registered foundation version
+  --commit           In a git repository, commit the site's content first (-m <message>)
   --org @org         Work in @org for this publish, not your login's workspace
   --personal         Work in your personal workspace for this publish
   --no-save          Do not record this deploy in deploy.yml

package/src/utils/flag-guard.js

@@ -67,14 +67,17 @@ const VERBS = {
     '--no-verify',
     // ship content against the already-released code, releasing nothing — or
     // release above a newer registered version instead of stopping (both bring-along)
-    '--no-release', '--bump', ...VIA_DEPLOY
+    '--no-release', '--bump',
+    // commit the site's content first, with this message (backend/site-sync.js)
+    '--commit', '-m', '--message', ...VIA_DEPLOY
   ],
   publish: [
     '--org', '--dry-run', '--force', '--foundation',
     '--personal',
     // read in utils/conformance.js, backend/site-sync.js, and
     // backend/foundation-bring-along.js — none appear in publish.js
-    '--no-validate', '--yes', '--no-verify', '--no-release', '--bump', ...VIA_DEPLOY
+    '--no-validate', '--yes', '--no-verify', '--no-release', '--bump',
+    '--commit', '-m', '--message', ...VIA_DEPLOY
   ],
   pull: [
     '--content-only', '--dry-run', '--force',

package/src/utils/git.js

@@ -66,6 +66,25 @@ export function siteContentRoots(siteDir) {
   return [...roots]
 }
 
+/**
+ * What each lane of a push carries, as roots: the folder lane the records — their files,
+ * and their translations — and the content lane everything else a pull writes, media
+ * (`public/`) included. ⚠️ `locales` stays whole on the content side, record translations
+ * with it: a root too many there costs a less precise base, never a wrong one.
+ */
+export function siteLaneRoots(siteDir) {
+  let records = 'records'
+  try {
+    records = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths?.records || 'records'
+  } catch {
+    /* no or unreadable site.yml — the default is right */
+  }
+  return {
+    content: [...siteContentRoots(siteDir), 'public'].filter((r) => r !== records),
+    records: [records, 'locales/records']
+  }
+}
+
 function git(args, cwd) {
   return execFileSync('git', args, {
     cwd,

package/src/utils/sync-point.js

@@ -53,6 +53,8 @@ import { join, dirname } from 'node:path'
 
 export const SYNC_TRAILER = 'Uniweb-Sync'
 export const SITE_TRAILER = 'Uniweb-Site'
+/** Marks the commit a push makes of what it wrote back: `Uniweb-Recorded: <origin> <site>`. */
+export const RECORDED_TRAILER = 'Uniweb-Recorded'
 
 const MAX_BUFFER = 1024 * 1024 * 1024
 
@@ -292,6 +294,70 @@ export function newestBase(repo, candidates) {
   }
 }
 
+/**
+ * The base a pull merges from, given the bases this copy knows of itself and what the backend
+ * names for each lane it answered (`x-uniweb-source`).
+ *
+ * ⭐ THIS COPY'S OWN BASES ARE EXACT BY CONSTRUCTION — a pull's commit, the commit a push was
+ * made from once every lane landed, one a push found nothing to send from — and are never
+ * second-guessed here.
+ *
+ * ⛔ ONE MERGE TAKES ONE BASE FOR EVERY LANE, and what the backend names is exact for its own
+ * lane only. A commit one lane names that is newer than another lane's, with that lane's files
+ * different, would read what that lane lacks — a push of it the backend refused while it took the
+ * other — as the backend's removal, and the merge would drop it. So it is not a base. A lane is
+ * held to the commit it names, read through the commit its push made of what it wrote back
+ * (`recordedAfter`), and a lane that names none to the newest base this copy knows.
+ *
+ * ⛔ Until 2026-10-19 (cli 713f62d, uniweb 1.13.0) every candidate was held to that, this copy's
+ * own included, and a lane to the commit it names alone. A first push writes each new record's
+ * `$uuid` back, so the records differed from the commit the folder lane names in every commit after
+ * it, and each was dropped: a pull merged from the site's first push, measured by flows against a
+ * real backend — a reverted change came back (A18), a re-wrap and six pushed edits conflicted.
+ */
+export function baseFor(repo, { known = [], lanes = [], origin, siteUuid }) {
+  const held = (s) => Boolean(s) && isCommit(repo, s) && isAncestor(repo, s)
+  const fallback = newestBase(repo, known)
+  const refs = lanes.map(({ source, roots }) => ({
+    roots,
+    ref: held(source) ? recordedAfter(repo, source, { origin, siteUuid }) || source : fallback
+  }))
+  const named = lanes.flatMap(({ source }) => (held(source) ? [source, recordedAfter(repo, source, { origin, siteUuid })] : []))
+  const taken = named.filter(Boolean).filter((s) =>
+    refs.every(({ ref, roots }) => Boolean(ref) && (s === ref || isAncestor(repo, s, ref) || !differsIn(repo, ref, s, roots)))
+  )
+  return newestBase(repo, [...known, ...taken])
+}
+
+/**
+ * The commit a push made of what it wrote back, after being made from `sha` — its first parent,
+ * marked with the push's backend and site — when HEAD's history holds it; else null.
+ */
+export function recordedAfter(repo, sha, { origin, siteUuid }) {
+  if (!sha || !origin || !siteUuid) return null
+  let out
+  try {
+    out = gitText(repo.top, ['log', '--fixed-strings', `--grep=${RECORDED_TRAILER}: ${origin} ${siteUuid}`, '--format=%H %P', 'HEAD'])
+  } catch {
+    return null
+  }
+  for (const line of out.split('\n')) {
+    const [commit, first] = line.trim().split(' ')
+    if (commit && first && (first === sha || first.startsWith(sha))) return commit
+  }
+  return null
+}
+
+/** Does the content under `roots` differ between two commits? Anything but "no" counts as yes. */
+function differsIn(repo, a, b, roots) {
+  try {
+    git(repo.top, ['diff', '--quiet', a, b, '--', ...roots.map((r) => `${repo.prefix}${r}`)])
+    return false
+  } catch {
+    return true
+  }
+}
+
 // ── the stand-in ────────────────────────────────────────────────────────────
 
 /**
@@ -652,14 +718,79 @@ export function snapshotFiles(repo) {
  * under the roots? (What the repository ignores is no change.)
  */
 export function contentCommitted(repo, roots) {
+  return uncommittedPaths(repo, roots)?.length === 0
+}
+
+/**
+ * The files under the roots that HEAD does not hold as they are — staged, changed, deleted
+ * or untracked, and both sides of a rename — relative to the site; null when git cannot
+ * say. What the repository ignores is no change.
+ */
+export function uncommittedPaths(repo, roots) {
+  let parts
   try {
-    const full = roots.map((r) => `${repo.prefix}${r}`)
-    return git(repo.top, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...full]).length === 0
+    parts = zlist(git(repo.top, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...roots.map((r) => `${repo.prefix}${r}`)]))
   } catch {
-    return false
+    return null
+  }
+  const out = []
+  for (let i = 0; i < parts.length; i++) {
+    out.push(parts[i].slice(3))
+    if (/[RC]/.test(parts[i].slice(0, 2))) out.push(parts[++i]) // a rename's source follows it
   }
+  return [...new Set(out.map((p) => siteRelative(repo, p)))]
 }
 
+/**
+ * The files under the roots that differ from what `rev` holds there — changed, deleted, or
+ * new and not ignored — relative to the site.
+ */
+export function filesDifferFrom(repo, rev, roots) {
+  const full = roots.map((r) => `${repo.prefix}${r}`)
+  try {
+    const changed = zlist(git(repo.top, ['diff', '--name-only', '-z', '--no-renames', rev, '--', ...full]))
+    const added = zlist(git(repo.top, ['ls-files', '--others', '--exclude-standard', '-z', '--', ...full]))
+    return [...new Set([...changed, ...added].map((p) => siteRelative(repo, p)))]
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Commit what the files hold under the roots — added, changed, deleted or renamed — and
+ * nothing else that is staged. With `identity` it is uniweb's commit, made as a pull's merge
+ * is: no hooks, unsigned. Without it, the person's own, as their `git commit` makes it.
+ *
+ * ⛔ Staged by ROOT, committed by NAME: `git add` refuses a path that is on neither the disk
+ * nor the index — a rename's source — and the commit takes exactly what was staged.
+ *
+ * @returns {{ commit: string, paths: string[] } | null} null when there was nothing to commit
+ */
+export function commitRoots(repo, roots, { message, identity = null }) {
+  const full = roots.map((r) => `${repo.prefix}${r}`)
+  const present = full.filter((p) => existsSync(join(repo.top, p)) || zlist(git(repo.top, ['ls-files', '-z', '--', p])).length)
+  let addable = present
+  if (present.length) {
+    try {
+      const ignored = zlist(git(repo.top, ['check-ignore', '-z', '--stdin'], { input: `${present.join('\0')}\0` }))
+      addable = present.filter((p) => !ignored.includes(p))
+    } catch (err) {
+      if (err?.status !== 1) throw err // 1: none of them is ignored
+    }
+  }
+  if (addable.length) git(repo.top, ['--literal-pathspecs', 'add', '-A', '--', ...addable])
+  const staged = zlist(git(repo.top, ['diff', '--cached', '--name-only', '-z', '--no-renames', '--', ...full]))
+  if (!staged.length) return null
+  git(
+    repo.top,
+    ['--literal-pathspecs', 'commit', '-q', ...(identity ? ['--no-verify', '--no-gpg-sign'] : []), '-m', message, '--pathspec-from-file=-', '--pathspec-file-nul'],
+    { input: `${staged.join('\0')}\0`, ...(identity ? { env: identity } : {}) }
+  )
+  return { commit: gitText(repo.top, ['rev-parse', 'HEAD']).trim(), paths: staged.map((p) => siteRelative(repo, p)) }
+}
+
+const siteRelative = (repo, p) => (repo.prefix && p.startsWith(repo.prefix) ? p.slice(repo.prefix.length) : p)
+
 // ── this copy's own sync point ──────────────────────────────────────────────
 
 const cachePath = (siteDir) => join(siteDir, '.uniweb', 'backend-cache.json')