uniweb 0.13.5 → 0.13.7

package/src/commands/doctor.js

@@ -297,6 +297,26 @@ export async function doctor(args = []) {
       continue
     }
 
+    // The agent index ships by default, but it can only carry absolute links
+    // when the site declares where it lives. Root-relative links still work
+    // for an agent that arrived via the index, so this warns rather than
+    // suppressing the artifact the way sitemap.xml does — a silently absent
+    // index is the exact failure the projections exist to prevent.
+    const agentsConfig = siteYml.agents
+    const indexEnabled = agentsConfig !== false && agentsConfig?.index !== false
+    if (indexEnabled && !siteYml.seo?.baseUrl) {
+      const issue = {
+        id: 'agents-index-relative-links',
+        type: 'warning',
+        site: siteName,
+        message: 'llms.txt will use root-relative links because seo.baseUrl is unset',
+      }
+      issues.push(issue)
+      warn(`[agents-index-relative-links] llms.txt links will be root-relative`)
+      log(`    Set ${colors.green}seo.baseUrl${colors.reset} in site.yml so agents get absolute URLs`)
+      log(`    (this also turns on sitemap.xml and robots.txt, which are skipped without it)`)
+    }
+
     const foundationName = siteYml.foundation
     if (!foundationName) {
       warn('No foundation specified in site.yml (using runtime loading?)')

package/src/commands/publish.js

@@ -27,6 +27,7 @@
  *   uniweb publish                 Bring the foundation along, sync, and go live
  *   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 --no-save       Skip the deploy.yml lastDeploy auto-save
  *   uniweb publish --backend <url> Override the backend origin
  *   uniweb publish --token <bearer> Auth bearer (skips `uniweb login`)
@@ -54,9 +55,17 @@ import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { readFlagValue } from '../utils/args.js'
 import { isNonInteractive } from '../utils/interactive.js'
-import { makeModelResolver, readSyncCache, pushSyncPackages } from '../backend/site-sync.js'
+import { headProvenance } from '../utils/git.js'
+import {
+  makeModelResolver,
+  readSyncCache,
+  readBaseVersions,
+  readItemBaseVersions,
+  ensureItemUuids,
+  pushSyncPackages,
+} from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
-import { uploadSiteMedia } from '../backend/site-media.js'
+import { uploadSiteMedia, isStorageRefusal } from '../backend/site-media.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import { settlePaymentIfNeeded } from '../backend/payment-handoff.js'
 
@@ -266,14 +275,29 @@ export async function publish(args = []) {
   if (mediaRefs.length) {
     say.info('Uploading media…')
     try {
-      const map = await uploadSiteMedia(client, siteDir, mediaRefs, {
+      const { map, failed } = await uploadSiteMedia(client, siteDir, mediaRefs, {
         onProgress: (m) => say.dim(`  ${m}`),
         warn: (m) => say.dim(`! ${m}`),
       })
+      // A ref whose bytes did not land must NOT be published: the content would go
+      // out still pointing at the local path, so the site ships a broken image and
+      // the only trace is a warning nobody reads. A missing FILE is different —
+      // already broken before us, warned above, and not worth blocking a publish.
+      if (failed.length) {
+        say.err(`${failed.length} asset(s) failed to upload — not publishing.`)
+        for (const f of failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
+        return { exitCode: 1 }
+      }
       if (Object.keys(map).length) assetRewrite = map
       if (ballAssets.length) ball = rewriteBallAssets(ball, map)
       say.dim(`Media          : ${Object.keys(map).length}/${mediaRefs.length} ref(s) → serve URL`)
     } catch (err) {
+      if (isStorageRefusal(err)) {
+        say.err('Storage quota reached — the media in this publish does not fit.')
+        say.dim('  Remove or shrink assets, or raise the plan limit, then re-run.')
+        say.dim(`  ${err.message}`)
+        return { exitCode: 1 }
+      }
       say.err(`Media upload failed: ${err.message}`)
       return { exitCode: 1 }
     }
@@ -296,6 +320,13 @@ export async function publish(args = []) {
   //    the SAME two-lane submission `uniweb push` uses — stamping
   //    info.data_bundle and rewriting local media refs to backend serve URLs.
   const priorHashes = readSyncCache(siteDir)
+  // publish rides the same gated push as `uniweb push`: if an app author has
+  // edited since this clone last synced, the push is refused rather than
+  // overwriting them, and nothing goes live. `--force` drops the precondition.
+  const baseVersions = args.includes('--force') ? null : readBaseVersions(siteDir)
+  // Per-item identity, recovered from the backend when this clone has never seen it.
+  // Without it the backend re-mints every page and section row (see readItemUuids).
+  const itemUuids = await ensureItemUuids({ client, siteDir, note: (m) => say.dim(m) })
   // Stamp deploy-derived info on the site-content entity: the data-bundle URL,
   // and the PINNED foundation ref (`@scope/name@version`) from the bring-along.
   // Delivery is version-pinned end-to-end (the gateway serves a foundation only
@@ -313,6 +344,8 @@ export async function publish(args = []) {
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel,
       priorHashes,
+      itemUuids,
+      ...(baseVersions ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir) } : {}),
       ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
       ...(assetRewrite ? { assetRewrite } : {}),
     })
@@ -376,6 +409,7 @@ export async function publish(args = []) {
   //    foundation version (the bring-along, §4).
   // Record the ref that actually went live: the pinned `@scope/name@version`
   // from the bring-along when present, else the site.yml ref verbatim.
+  const gitAt = headProvenance(siteDir)
   const siteYmlRef = typeof siteYml.foundation === 'string' ? siteYml.foundation : siteYml.foundation?.ref || null
   const recordedRef = fnd.ref || siteYmlRef
   await persistLastDeploy(siteDir, {
@@ -388,6 +422,11 @@ export async function publish(args = []) {
     lastDeploy: {
       at: new Date().toISOString(),
       host: 'uniweb',
+      // What was actually shipped. A version number can't answer that — two
+      // publishes of "0.1.0" are not the same content — and after the fact the
+      // working tree has moved on. `dirty` matters as much as the sha: it says the
+      // publish did NOT correspond to any commit, so the sha alone would mislead.
+      ...(gitAt ? { git: gitAt } : {}),
       backend: client.origin,
       siteUuid,
       url: serveUrl,

package/src/commands/pull.js

@@ -12,9 +12,25 @@
  *     pages/**, layout/**), and
  *   - folder lane  → `collectionsToProject` (the folder + record files).
  *
- * Pull is git-pull-like: it reconciles the working tree to the backend, DELETING
- * pages/sections that no longer exist there (toggle off with `--no-delete`). The
- * deletion is guarded so an empty/partial payload never wipes the tree.
+ * Pull is a CHECKOUT, not a merge — the "git-pull-like" it used to claim here was
+ * misleading. It reconciles the working tree to the backend: section bodies are
+ * rewritten from the fetched document, and pages/sections the backend no longer has
+ * are DELETED (toggle off with `--no-delete`). The deletion is guarded so an
+ * empty/partial payload never wipes the tree.
+ *
+ * Because it overwrites rather than merges, it REFUSES when there is uncommitted
+ * work under the directories it owns — that was the one remaining way the CLI could
+ * destroy a user's work without them agreeing to it. Commit or stash first, or pass
+ * `--force`. Outside a git repository there is nothing to fall back on, so it asks
+ * instead (and refuses when it cannot).
+ *
+ * `--merge` is the third option, and usually the one you want after a refused push:
+ * three-way merge local work with what the backend sends, instead of choosing
+ * between them. Most "conflicts" are two people editing different paragraphs of one
+ * section, which merges silently; only genuine overlaps get conflict markers. The
+ * common ancestor is the COMMITTED version of each file — the backend keeps no
+ * per-version history and does not need to — so `--merge` requires a repo, and the
+ * merge itself is `git merge-file`.
  *
  * `uniweb login && uniweb pull`. Run from a site, or a workspace with one site.
  *
@@ -22,6 +38,8 @@
  *   uniweb pull                          GET both lanes, project to files, prune orphans
  *   uniweb pull --no-collections         Pull pages only; skip the folder (collections) lane
  *   uniweb pull --no-delete              Project, but keep files with no backend item
+ *   uniweb pull --merge                  Three-way merge local changes with the backend's
+ *   uniweb pull --force                  Pull over uncommitted local changes (discards them)
  *   uniweb pull --dry-run                Report what it would GET; write nothing
  *   uniweb pull --registry <url>         Override the backend origin
  *   uniweb pull --token <bearer>         Read with this bearer; skips `uniweb login`
@@ -38,16 +56,29 @@
  * against the playground backend, 2026-06-17.
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { createHash } from 'node:crypto'
+import { createInterface } from 'node:readline/promises'
+import { join, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
 import {
   siteContentDocumentToProject,
   collectionsToProject,
   resolveCollectionsConfig,
   readZip,
+  computeUnitHashes,
+  collectUnitUuids,
 } from '@uniweb/build/uwx'
 import { makeModelResolver } from './push.js'
+import {
+  mergeBaseVersions,
+  mergeItemBaseVersions,
+  writeUnitBases,
+  writeItemUuids,
+} from '../backend/site-sync.js'
+import { uncommittedUnder, siteContentRoots, showAtHead, mergeFile } from '../utils/git.js'
+import { isNonInteractive } from '../utils/interactive.js'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir as defaultResolveSiteDir, resolveSiteBackend } from './deploy.js'
 
@@ -167,11 +198,280 @@ export function readPullDocuments(buf) {
   return single ? [single] : []
 }
 
+// Read the per-entity optimistic-concurrency tokens out of a pull lane's manifest.
+// The backend stamps each entity entry with a top-level `version` (opaque RFC3339);
+// we cache it and echo it back as `base_version` on the next push, so a push
+// against a base the backend has moved past is refused instead of silently
+// overwriting. Returns a `{ <backend-uuid>: <version> }` map — empty for a JSON
+// fallback body (no manifest ⇒ no tokens ⇒ that lane simply stays unconditional).
+//
+// TOP-LEVEL on the entry. The backend's `Entry::extra` is `#[serde(flatten)]`, so
+// it never appears on the wire; reading `extra.version` finds nothing and silently
+// leaves the gate disarmed (which is exactly what it did before 2026-07-26).
+//
+// Keyed by `entries[].uuid`, which on a PULL manifest is the real backend uuid.
+// Note that is NOT symmetric with what we EMIT: on the push side that field is our
+// `$id` handle, and the backend correlates our `base_version` via the body's
+// `$uuid` instead. Same field name, different meaning by direction.
+//
+// This reads the SAME manifest.json that readPullDocuments deliberately skips:
+// there the entity files are the payload, here the manifest is the index we were
+// previously discarding.
+export function readPullVersions(buf) {
+  return readManifestTokens(buf).entity
+}
+
+/**
+ * Per-ITEM staleness tokens: `{ <record $uuid>: <opaque version> }`, from the
+ * entry's `item_versions`.
+ *
+ * The entity token can only say "something in this document moved"; these say
+ * which records did, which is what lets two people editing different sections
+ * both land instead of one being refused. Echoed back as `item_base_versions`.
+ *
+ * Keyed by record uuid rather than by our file path deliberately: the token then
+ * joins to the body by the same identity the backend's reconcile uses, and a file
+ * rename cannot silently re-target it. Absent for an entity with no items, and
+ * absent from an older backend — both mean "no per-item precondition", fall back
+ * to the entity grain.
+ */
+export function readPullItemVersions(buf) {
+  return readManifestTokens(buf).item
+}
+
+// One manifest read for both grains — they arrive on the same entry and must not
+// drift apart by being parsed in two places.
+function readManifestTokens(buf) {
+  const out = { entity: {}, item: {} }
+  if (!(buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b)) return out
+  for (const [name, data] of readZip(buf)) {
+    if (name !== 'manifest.json') continue
+    try {
+      const manifest = JSON.parse(data.toString('utf8'))
+      for (const entry of manifest?.entries || []) {
+        if (entry?.uuid && typeof entry.version === 'string') out.entity[entry.uuid] = entry.version
+        const items = entry?.item_versions
+        if (items && typeof items === 'object') {
+          for (const [uuid, v] of Object.entries(items)) {
+            if (typeof v === 'string') out.item[uuid] = v
+          }
+        }
+      }
+    } catch {
+      /* an unreadable manifest just means no tokens this pull */
+    }
+    break
+  }
+  return out
+}
+
 /**
  * @param {string[]} args
  * @param {object} [deps] - injectable seams for testing: `fetch` (default global
  *   fetch), `resolveSiteDir`, `getToken` (skip auth).
  */
+/**
+ * Refuse a pull that would overwrite unsaved work. Returns a result object to
+ * return from `pull`, or null to proceed.
+ *
+ * With a repo: uncommitted work under pull's roots blocks, naming the files.
+ * Without one: there is nothing standing behind the tree, so ask — and in a
+ * non-interactive context refuse rather than assume consent.
+ */
+async function checkWorkingTree(siteDir, args) {
+  const roots = siteContentRoots(siteDir)
+  let dirty = uncommittedUnder(siteDir, roots)
+
+  if (dirty === null) {
+    // Not a git work tree. Nothing to fall back on if this goes wrong.
+    if (isNonInteractive(args)) {
+      error('Refusing to pull: this site is not in a git repository.')
+      note('Pull rewrites pages, sections and layout from the backend and deletes what it no longer has.')
+      note('Without version control there is no way back, and this session cannot ask.')
+      note('Re-run with --force to accept that, or put the site under git first.')
+      return { exitCode: 1 }
+    }
+    const ok = await confirm(`Pull will overwrite ${roots.length} content location(s) and this site is not in git. Continue?`)
+    if (!ok) {
+      info('Nothing pulled.')
+      return { exitCode: 0 }
+    }
+    return null
+  }
+
+  const written = readWritten(siteDir)
+  dirty = dirty.filter((f) => !isPullOutput(siteDir, f, written))
+  if (!dirty.length) return null
+
+  error(`Refusing to pull: ${dirty.length} uncommitted change(s) under the files pull rewrites.`)
+  for (const f of dirty.slice(0, 12)) note(`  ${f}`)
+  if (dirty.length > 12) note(`  … and ${dirty.length - 12} more`)
+  note('Pull reconciles the working tree to the backend, so these would be overwritten or deleted.')
+  note('Commit or stash them first — then pull, and your work is still in git either way.')
+  note('To discard them and take the backend version, re-run with --force.')
+  return { exitCode: 1 }
+}
+
+// What the last pull wrote: `{ <repo-relative path>: <sha256 of the bytes it wrote> }`.
+//
+// Without this the guard cries wolf: pull rewrites the tree, so the very next pull
+// sees its OWN output as uncommitted work and refuses, listing files the user never
+// touched. A guard that fires on nothing teaches people to reach for --force, which
+// is the destructive option — the same failure mode as a gate that refuses disjoint
+// edits. A file still byte-identical to what pull last wrote is not user work.
+function writtenCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-written.json')
+}
+function readWritten(siteDir) {
+  try {
+    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
+    return {
+      files: o && typeof o.files === 'object' ? o.files : {},
+      deleted: Array.isArray(o?.deleted) ? o.deleted : [],
+    }
+  } catch {
+    return { files: {}, deleted: [] }
+  }
+}
+function recordWritten(siteDir, absPaths, deletedAbs = []) {
+  // MERGE, don't replace. A conditional pull that 304s writes nothing, and a
+  // partial pull writes only some lanes — in both cases the previous record is
+  // still "the last thing pull wrote there". Replacing would forget those paths and
+  // the next pull would see them as the user's work again, which is the false alarm
+  // this cache exists to prevent. A stale entry for a file that no longer exists is
+  // harmless: the hash read fails and it counts as a local change.
+  const prior = readWritten(siteDir)
+  const files = prior.files
+  for (const abs of absPaths) {
+    try {
+      files[relative(siteDir, abs)] = createHash('sha256').update(readFileSync(abs)).digest('hex')
+    } catch { /* deleted or unreadable — nothing to remember */ }
+  }
+  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
+  // Without recording them, pull's own pruning reads as the user having deleted
+  // files — the same false alarm as its writes, arriving by the other door.
+  const deleted = [...new Set([...prior.deleted, ...deletedAbs.map((a) => relative(siteDir, a))])]
+  try {
+    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
+    writeFileSync(writtenCachePath(siteDir), JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n')
+  } catch { /* best-effort: losing it only costs a spurious refusal */ }
+}
+// Is this dirty path just pull's own untouched output?
+function isPullOutput(siteDir, relPath, written) {
+  let exists = true
+  let hash = null
+  try {
+    hash = createHash('sha256').update(readFileSync(join(siteDir, relPath))).digest('hex')
+  } catch {
+    exists = false
+  }
+  // Absent because pull pruned it — not because the user deleted it.
+  if (!exists) return written.deleted.includes(relPath)
+  return written.files[relPath] === hash
+}
+
+/**
+ * `--merge`: keep local work instead of refusing, by three-way merging it with what
+ * the backend sends.
+ *
+ * Without this the recovery from a same-section conflict is commit → pull (which
+ * overwrites your version) → re-apply by hand → push. Yet most such "conflicts"
+ * aren't: two people edited different paragraphs of one section, and a real merge
+ * takes both. Only genuine overlaps need a human.
+ *
+ * Works by capturing local content BEFORE the projection overwrites it, then
+ * merging afterwards — so the projector stays a plain writer and needs no hook, and
+ * nothing is lost in between because "mine" is already in memory.
+ *
+ * Requires a repo, and that is not a mandate creeping in: the ancestor IS the
+ * committed version, and the merge is git's. There is nothing to merge against
+ * without one.
+ *
+ * @returns {Map<string, {content: Buffer, inHead: boolean}>|null} captured work, or
+ *   null when merging isn't possible here (the caller reports and stops).
+ */
+function captureLocalWork(siteDir) {
+  const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
+  if (dirty === null) return null
+  const written = readWritten(siteDir)
+  const out = new Map()
+  for (const rel of dirty) {
+    if (isPullOutput(siteDir, rel, written)) continue // pull's own output, not work
+    try {
+      out.set(rel, { content: readFileSync(join(siteDir, rel)), inHead: showAtHead(siteDir, rel) !== null })
+    } catch {
+      // Locally deleted. Pull will restore the backend's copy, which is the
+      // sensible reading of "I removed this and then asked for their version".
+    }
+  }
+  return out
+}
+
+// Merge captured work back over what the projection just wrote. Returns a report.
+function mergeLocalWork(siteDir, captured) {
+  const clean = []
+  const conflicted = []
+  const kept = []
+  for (const [rel, { content: mine, inHead }] of captured) {
+    const abs = join(siteDir, rel)
+    let theirs = null
+    try { theirs = readFileSync(abs) } catch { /* pruned by the pull */ }
+
+    if (theirs === null) {
+      // The backend no longer has it, but we changed it. Restoring is the
+      // non-destructive reading; the alternative silently discards local work to
+      // honour a deletion the user never saw.
+      mkdirSync(dirname(abs), { recursive: true })
+      writeFileSync(abs, mine)
+      kept.push(`${rel} (removed upstream, kept yours)`)
+      continue
+    }
+    if (theirs.equals(mine)) continue // both sides agree already
+
+    const base = inHead ? showAtHead(siteDir, rel) : null
+    if (!base) {
+      // No committed ancestor — a file added locally and never committed. There is
+      // no third input, so a three-way merge is not defined. Keep ours rather than
+      // guess, and say so.
+      writeFileSync(abs, mine)
+      kept.push(`${rel} (no committed ancestor, kept yours)`)
+      continue
+    }
+
+    const dir = mkdtempSync(join(tmpdir(), 'uniweb-merge-'))
+    try {
+      const basePath = join(dir, 'base')
+      const theirsPath = join(dir, 'theirs')
+      writeFileSync(basePath, base)
+      writeFileSync(theirsPath, theirs)
+      writeFileSync(abs, mine) // merge-file rewrites this in place
+      const r = mergeFile(siteDir, abs, basePath, theirsPath)
+      if (!r.merged) {
+        writeFileSync(abs, mine) // merge couldn't run — never leave a half-state
+        kept.push(`${rel} (merge unavailable, kept yours)`)
+      } else if (r.conflicted) {
+        conflicted.push(rel)
+      } else {
+        clean.push(rel)
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  }
+  return { clean, conflicted, kept }
+}
+
+// Minimal yes/no prompt; defaults to no, because the default must not destroy.
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (await rl.question(`${question} [y/N] `)).trim().toLowerCase()
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
 export async function pull(args = [], deps = {}) {
   const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
 
@@ -179,8 +479,36 @@ export async function pull(args = [], deps = {}) {
   const tokenFlag = flagValue(args, '--token')
   const prune = !(args.includes('--no-delete') || args.includes('--no-prune')) // git-like by default
   const noCollections = args.includes('--no-collections') || args.includes('--content-only')
+  const force = args.includes('--force')
+  const mergeMode = args.includes('--merge')
 
   const siteDir = await resolveSiteDir(args, 'pull')
+
+  // Don't overwrite work that isn't saved anywhere. Pull reconciles the working
+  // tree to the backend — it rewrites section bodies from the fetched document and
+  // prunes what the backend doesn't have — so uncommitted work under the
+  // directories it owns is destroyed with no way back. That is the one place the
+  // CLI could still lose a user's work without them agreeing to it.
+  //
+  // Checked coarsely, by root, on purpose: pull rewrites essentially every file
+  // under those roots, so an exact per-file intersection would refuse the same
+  // cases while being able to miss one.
+  // `--merge` keeps local work instead of refusing it: capture what is dirty now,
+  // let the projection write the backend's version, then merge ours back over it.
+  let captured = null
+  let mergeReport = null
+  if (!dryRun && mergeMode) {
+    captured = captureLocalWork(siteDir)
+    if (captured === null) {
+      error('Cannot merge: this site is not in a git repository.')
+      note('The common ancestor a merge needs is the committed version of each file.')
+      note('Without a repo there is nothing to merge against — use `uniweb pull --force` to take the backend version.')
+      return { exitCode: 1 }
+    }
+  } else if (!dryRun && !force) {
+    const blocked = await checkWorkingTree(siteDir, args)
+    if (blocked) return blocked
+  }
   const siteBackend = await resolveSiteBackend(siteDir)
   const client = new BackendClient({
     originFlag: flagValue(args, '--backend') || flagValue(args, '--registry'),
@@ -236,7 +564,13 @@ export async function pull(args = [], deps = {}) {
     }
     try {
       const etag = res.headers?.get?.('etag') ?? null
-      const docs = readPullDocuments(Buffer.from(await res.arrayBuffer()))
+      const buf = Buffer.from(await res.arrayBuffer())
+      const docs = readPullDocuments(buf)
+      // Bank the per-entity staleness tokens this lane carried, so the next push
+      // is gated against the state we just took. A 304 skips this — correctly:
+      // unchanged upstream means the token we already hold is still current.
+      mergeBaseVersions(siteDir, readPullVersions(buf))
+      mergeItemBaseVersions(siteDir, readPullItemVersions(buf))
       return { docs, etag }
     } catch (err) {
       error(`Could not read the ${label} response: ${err.message}`)
@@ -244,6 +578,10 @@ export async function pull(args = [], deps = {}) {
     }
   }
 
+  // Every file the projection writes, so the next pull can tell its own output
+  // apart from the user's work (see readWritten).
+  const wrote = []
+  const removed = []
   let pages = 0
   let sections = 0
   let records = 0
@@ -261,7 +599,20 @@ export async function pull(args = [], deps = {}) {
   if (content && !content.notModified) {
     const siteDoc = content.docs && (content.docs.find((d) => d?.info || d?.$model) || content.docs[0] || null)
     if (siteDoc) {
+      // Re-base the page attribution. The pulled document IS the backend's own
+      // representation, so it becomes the remote base directly. We deliberately
+      // CLEAR the local base rather than reuse it: our source files were just
+      // rewritten from this document, and what we would emit from them is not
+      // byte-identical to it, so the old local base no longer describes anything.
+      // The next push re-establishes it; until then our side reports as unknown,
+      // which is honest rather than wrong.
+      writeUnitBases(siteDir, { remote: computeUnitHashes(siteDoc), local: {} })
+      // Per-item identity for the next push. Without it the backend reads our
+      // records as new and re-mints every page and section row.
+      writeItemUuids(siteDir, collectUnitUuids(siteDoc))
       const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
+      wrote.push(...report.pages, ...report.sections, ...report.layout)
+      removed.push(...(report.deleted || []), ...(report.renamed || []).map((r) => r.from))
       pages += report.pages.length
       sections += report.sections.length
       deleted += report.deleted.length
@@ -302,9 +653,38 @@ export async function pull(args = [], deps = {}) {
 
   // Persist the ETags so the next pull is conditional (304 when unchanged).
   writePullCache(siteDir, { content: etagContent, folder: etagFolder })
+  // Config files are rewritten every pull whether or not they changed; include the
+  // ones the projector owns so a pull-then-pull doesn't trip on them either.
+  // Merge captured local work back over what the projection just wrote. Runs after
+  // BOTH lanes, so a file either lane produced is merged the same way.
+  if (captured && captured.size) {
+    mergeReport = mergeLocalWork(siteDir, captured)
+    const r = mergeReport
+    if (r.clean.length) {
+      info(`Merged your changes into ${r.clean.length} file(s):`)
+      for (const f of r.clean) note(`  ${f}`)
+    }
+    for (const f of r.kept) note(`\u21b7 ${f}`)
+    if (r.conflicted.length) {
+      error(`${r.conflicted.length} file(s) have conflicts to resolve:`)
+      for (const f of r.conflicted) note(`  ${f}`)
+      note('Conflict markers are in place. Resolve them, then commit and push.')
+    }
+  }
+
+  recordWritten(
+    siteDir,
+    [...wrote, ...['site.yml', 'theme.yml', 'head.html', 'collections.yml'].map((f) => join(siteDir, f))],
+    removed
+  )
 
   success(
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` + (deleted ? `, ${deleted} deleted` : '')
   )
-  return { exitCode: 0 }
+  // Unresolved conflicts are a non-zero exit, the way a conflicted `git merge` is.
+  // The pull itself worked; there is work left for a human. This is what makes a
+  // chained `uniweb pull --merge && uniweb push` safe by construction — without it,
+  // the obvious one-liner pushes conflict markers into live content.
+  const conflicts = mergeReport?.conflicted?.length ?? 0
+  return { exitCode: conflicts ? 1 : 0, merge: mergeReport }
 }