uniweb 0.13.5 → 0.13.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.7.29",
-    "@uniweb/kit": "0.9.37",
-    "@uniweb/runtime": "0.8.36"
+    "@uniweb/core": "0.7.31",
+    "@uniweb/kit": "0.9.39",
+    "@uniweb/runtime": "0.8.38"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "1.1.15",
-    "@uniweb/semantic-parser": "1.1.18",
-    "@uniweb/build": "0.15.5"
+    "@uniweb/content-reader": "1.1.17",
+    "@uniweb/semantic-parser": "1.1.20",
+    "@uniweb/build": "0.15.7"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -472,6 +472,8 @@ Optional attributes: `{size=20}`, `{color=red}`. Custom SVGs: `![Logo](./logo.sv
 
 **Quote values containing spaces:** `{note="Ready to go"}`, not `{note=Ready to go}` — unquoted values end at the first space.
 
+**Separators are forgiving.** `:` works wherever `=` does, and pairs may be separated by whitespace, a comma, or both — `{role=banner width=1200}`, `{role:banner, width:1200}` and `{role:banner,width:1200}` are identical. `=` and spaces are canonical, and that is what gets written back on save. Two rules keep it unambiguous: the separator must **touch** the key (`{note:warning}` is one pair, `{note : warning}` is two flags), and a value containing a **comma** must be quoted (`{style="a, b"}`). A value containing a colon needs no quoting — only the first colon separates, so `{href:https://example.com}` is fine.
+
 Standalone links (alone on a line) become buttons in `content.links[]`. Inline links stay as `<a>` tags inside `content.paragraphs[]`. Multiple links sharing a paragraph are all promoted:
 
 ```markdown
@@ -1278,8 +1280,9 @@ Pages are sequences of sections — the obvious layer. The framework also suppor
 | **Items** (`content.items`) | Heading groups within one `.md` | Repeating content in one section: cards, features, FAQ entries |
 | **Child sections** (`block.childBlocks`) | `@`-prefixed `.md` files + `nest:` | Children needing their own section type, rich content, or independent editing |
 | **Insets** (`block.insets`) | `![](@Component)` in markdown | Self-contained visuals/widgets: charts, diagrams, code demos |
+| **Block insets** (`block.insets`) | ` ```@Component ` fence around markdown | A component that *wraps* authored prose: callouts, disclosures, admonitions |
 
-Does the author write content *inside* the nested element? **Yes** → child sections. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children.
+Does the author write content *inside* the nested element? **Yes** → child sections, or a block inset when the wrapper is presentational and lives mid-page. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children; a block inset can contain both.
 
 **Insets — embedding components in content.** Many section types need a "visual" — a hero's illustration, a split-content section's media. Classically an image or video. But what if it's a JSX + SVG diagram, a ThreeJS animation, an interactive playground? Elsewhere you'd reach for MDX or prop-drilling. Here the author writes standard image syntax:
 
@@ -1297,6 +1300,23 @@ The developer builds `NetworkDiagram` as an ordinary React component with `inset
 
 **Don't use `hidden: true` on insets.** `hidden` means "don't export this component at all" (internal helpers); `inset: true` means "available for `@Component` references in markdown."
 
+**Block insets — a component that wraps content.** The image form is a leaf: it takes params but no body. When the component should surround authored prose — a callout, a disclosure, an admonition — use the fenced form instead. Same `@Component{params}` reference, written as a code fence's info string:
+
+````markdown
+```@Alert{type=warning}
+Back up your database **before** running this.
+
+- The migration is not reversible
+- Allow ten minutes of downtime
+```
+````
+
+The body is ordinary content, not text: it is parsed exactly like the rest of the page, so headings, lists, tables, icons, inline styling, leaf insets and further containers all work inside one. To nest a code block or another container, open the outer fence with more backticks than the inner one.
+
+**The component is yours, and it receives parsed content.** `@Alert` resolves against the foundation through the same lookup as `![](@NetworkDiagram)` — declare it with `inset: true` in `meta.js`. Where a leaf inset gets its alt text as `content.title` and nothing else, a container gets its whole body parsed: `title`, `paragraphs`, `items`, `sequence`. Render it with `<Prose content={content} block={block} />` or read the fields directly. A name the foundation doesn't define falls back to a plain bordered box that still shows the body — never a drop.
+
+Prefer a **child section** when the author needs their own section type and independent editing; prefer a **block inset** when the wrapper is presentational and belongs inline in a single file's prose.
+
 **Child sections.** You hit a complex layout — a 2:1 split with a panel and a main area. Your instinct says build a specialized component. Step back: the panel is a reusable section type, the main area is another, and the split is a Grid with `columns: "1fr 2fr"`. Your child components already adapt to narrow containers — container queries handle that. But hardcoding which components go where means the author can't rearrange or swap them. Child sections solve that:
 
 ```
@@ -1571,6 +1591,46 @@ Recipes for staying on the default fetcher, and for writing a custom transport:
 
 Full model: `reference/data-fetching.md`. Where-object format with examples: `authoring/predicates.md`.
 
+### Search (`search:`)
+
+Search follows the same arrangement as `fetcher:` — the **site** declares where results come from, and a search UI reads them the same way regardless. Never hardcode a search endpoint in a component; that couples the foundation to one host.
+
+```yaml
+# site.yml
+search:
+  enabled: true
+  provider: index        # default — download an index, match in the browser
+```
+
+| Provider | Answers with | Trade-off |
+|---|---|---|
+| `index` (default) | `search-index.json` + Fuse.js in the browser | Free, works on **any** host including a plain static one, tolerates typos. Contains only what existed at build time. |
+| `endpoint` | A server-side search API | Can cover records fetched from an API, and can be re-indexed without rebuilding the site. Requires a host that serves one. |
+| *any other name* | A foundation-supplied search transport | Fully open — Typesense, Meilisearch, Pagefind, a vendor API |
+
+```yaml
+search:
+  provider: endpoint
+  endpoint: _search      # optional; base-RELATIVE, so one spelling works everywhere
+```
+
+`endpoint:` resolves against the site's base path — `/` → `/_search`, `base: /docs/` → `/docs/_search`, a subpath-served site follows its subpath. An absolute `https://…` URL points at another origin.
+
+**Results have one shape, whatever the provider.** Always present: `id`, `type`, `route`, `href`, `title`, `pageTitle`, `excerpt`, `snippetHtml`. Provider-optional (`null` when absent): `sectionId`, `anchor`, `description`, `component`, `snippetText`, `matches`, `collection`, `item`. Whether an optional field arrives is a deployment fact, not a content fact — the same site yields `item` from a server provider and `null` from the local index — so guard them: `result.item?.image`.
+
+`snippetHtml` is HTML with `<mark>`. Render it through `SafeHtml`, never as text.
+
+**Failures degrade rather than break** — a failing provider falls back to the local index when one exists, otherwise returns no results with a console warning. A search box never throws at a visitor.
+
+```jsx
+import { useSearch } from '@uniweb/kit'
+
+const { results, isLoading, query } = useSearch(website)   // `query` is a function
+<input onChange={e => query(e.target.value)} />            // debounced internally
+```
+
+Full reference: `authoring/search.md`.
+
 <!-- template:loom -->
 ### Content handlers
 
@@ -1624,6 +1684,9 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
 uniweb register [--scope @org]        # Register a foundation + its data schemas to the registry
+uniweb login / logout                 # Start or clear the backend session the verbs above reuse
+uniweb org list / create <handle>     # Publish orgs you belong to — the @org in a scoped ref
+uniweb content export [dir]           # Package a site (or a built foundation's schema) as .uwx
 
 uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whole workspace
 uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
@@ -1638,6 +1701,8 @@ uniweb inspect <path>             # Show parsed content for a section or page (-
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
 ```
 
+**Four verbs dispatch but are deliberately not listed above.** `invite`, `handoff` and `template` are **reserved names with no implementation** — the flows they named ran against a backend the CLI no longer talks to, and the names are held so a future rebuild doesn't need a breaking change. `runtime register` uploads a built runtime and is internal. Running any of them is not useful; their absence from this list is the answer, not an omission to fix.
+
 ### Where a site can live
 
 **There is no lock-in, and no default you're pushed toward.** Four independent paths, and a project can change its mind:

package/src/backend/site-media.js

@@ -24,16 +24,24 @@ import { contentTypeFor } from '../utils/code-upload.js'
  * @param {string} siteDir - the site root (site-root refs resolve under public/)
  * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
  * @param {{ onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
- * @returns {Promise<Record<string,string>>} ref → serve URL (only resolved + uploaded refs)
+ * @returns {Promise<{ map: Record<string,string>, missing: string[], failed: Array<{path:string,status:number,detail?:string}> }>}
+ *   `map` is ref → serve URL for refs that resolved AND uploaded. The two failure
+ *   kinds are reported SEPARATELY because callers must treat them differently:
+ *   `missing` is a ref with no file under the site — an authoring mistake, already
+ *   broken before us, worth a warning; `failed` is a ref whose bytes we could not
+ *   store — a transport or QUOTA refusal, and shipping content that still points at
+ *   the local path would publish a broken image while only warning about it.
  */
 export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn } = {}) {
-  if (!refs?.length) return {}
+  if (!refs?.length) return { map: {}, missing: [], failed: [] }
 
   const files = []
+  const missing = []
   for (const ref of refs) {
     const { resolved } = resolveAssetPath(ref, siteDir, siteDir)
     if (!resolved || !existsSync(resolved)) {
       warn?.(`local-media: ${ref} not found under the site (skipped)`)
+      missing.push(ref)
       continue
     }
     const bytes = readFileSync(resolved)
@@ -46,10 +54,11 @@ export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn
       diskPath: resolved,
     })
   }
-  if (!files.length) return {}
+  if (!files.length) return { map: {}, missing, failed: [] }
 
   const result = await client.uploadSiteAssets({ files, onProgress })
-  for (const f of result.failed || []) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
+  const failed = result.failed || []
+  for (const f of failed) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
 
   const config = await client.discover()
   const map = {}
@@ -57,5 +66,25 @@ export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn
     const entry = result.assetsByLocalUrl[ref]
     if (entry) map[ref] = entry.serveUrl || buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
   }
-  return map
+  return { map, missing, failed }
+}
+
+/**
+ * Is this asset-lane error the backend refusing on storage grounds?
+ *
+ * The plan step throws `Asset plan failed: HTTP <status>` for any non-2xx, so a quota
+ * refusal is currently indistinguishable from any other rejection except by status.
+ * These three are the plausible spellings — 402 (payment required), 413 (payload too
+ * large), 507 (insufficient storage).
+ *
+ * DELIBERATELY a heuristic, and it should not stay one: the backend owes a typed
+ * error carrying used / limit / needed so the CLI can say what a push costs and what
+ * is left. Until that contract exists this at least turns an opaque HTTP number into
+ * the right advice. See the collab charter in the handoff.
+ *
+ * @param {Error} err
+ * @returns {boolean}
+ */
+export function isStorageRefusal(err) {
+  return /Asset plan failed: HTTP (402|413|507)\b/.test(err?.message || '')
 }

package/src/backend/site-sync.js

@@ -13,7 +13,64 @@
 
 import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { backfillEntityUuids, writeSiteEntityUuid, emitSyncPackages } from '@uniweb/build/uwx'
+import yaml from 'js-yaml'
+import { hasUncommittedContent } from '../utils/git.js'
+import {
+  backfillEntityUuids,
+  writeSiteEntityUuid,
+  emitSyncPackages,
+  readZip,
+  diffSiteUnits,
+  describeSiteDiff,
+  computeUnitHashes,
+  collectUnitUuids,
+} from '@uniweb/build/uwx'
+
+// First entity `$`-document out of a `.uwx` we produced or the backend served.
+// Deliberately NOT pull.js's `readPullDocuments`: that one is tolerant of JSON
+// envelopes for a lane whose shape may change, and importing it here would be a
+// cycle (pull.js already imports this module). Both lanes here are always ZIPs.
+function entityDocFromUwx(buf) {
+  if (!buf || buf.length < 2 || buf[0] !== 0x50 || buf[1] !== 0x4b) return null
+  for (const [name, data] of readZip(buf)) {
+    if (name === 'manifest.json' || !name.endsWith('.json')) continue
+    try {
+      return JSON.parse(data.toString('utf8'))
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/**
+ * Turn an entity-grained staleness refusal into a file-level account.
+ *
+ * The gate can only report that the site-content document moved. What the user
+ * needs is which FILES — content is split one section per file, so two people
+ * editing different sections of the same page have not conflicted — and, since we
+ * cache per-unit hashes of the last agreed state, which side moved them. Fetches the backend's current document (a plain
+ * read; it writes nothing locally, unlike `uniweb pull`) and diffs.
+ *
+ * Best-effort by design: this runs on a path that has ALREADY failed, so any
+ * problem fetching or parsing must degrade to the plain refusal rather than
+ * replace a clear error with a confusing one.
+ *
+ * @returns {string[]} lines to print, or [] when nothing useful can be said.
+ */
+async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
+  try {
+    if (!uuid) return []
+    const res = await client.pullSiteContent(uuid)
+    if (!res?.ok) return []
+    const remoteDoc = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
+    const localDoc = entityDocFromUwx(localBuffer)
+    if (!remoteDoc || !localDoc) return []
+    return describeSiteDiff(diffSiteUnits(localDoc, remoteDoc, readUnitBases(siteDir)))
+  } catch {
+    return []
+  }
+}
 
 // Pull the finalized entities out of the restore response. The backend returns
 // `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each entry
@@ -35,6 +92,12 @@ export function extractFinalized(payload) {
       index: d?.index,
       uuid: d?.uuid ?? d?.document?.$uuid ?? null,
       changed: d?.changed,
+      // Post-write optimistic-concurrency token, read back from the stored row.
+      // Cache it UNCONDITIONALLY — do not branch on `changed` and do not infer:
+      // the backend pins "zero-write ⇒ version unmoved" with a test, so a no-op
+      // resubmit returns the value we already hold, and anything else is theirs
+      // to report, not ours to derive.
+      version: typeof d?.version === 'string' ? d.version : null,
       document: d?.document ?? null,
     }))
     .filter((e) => Number.isInteger(e.index) && e.uuid)
@@ -92,18 +155,175 @@ export function makeModelResolver({ client, offline = false }) {
 function syncCachePath(siteDir) {
   return join(siteDir, '.uniweb', 'sync-cache.json')
 }
-export function readSyncCache(siteDir) {
+function readSyncCacheFile(siteDir) {
   try {
     const obj = JSON.parse(readFileSync(syncCachePath(siteDir), 'utf8'))
-    return obj && typeof obj.hashes === 'object' && obj.hashes ? obj.hashes : {}
+    return obj && typeof obj === 'object' ? obj : {}
   } catch {
     return {} // missing / unreadable → treat everything as changed
   }
 }
-export function writeSyncCache(siteDir, hashes) {
+// The cache holds three maps written on DIFFERENT events — content hashes on a
+// successful push, base versions on push AND pull, unit hashes on push and pull —
+// so every writer must preserve the ones it isn't touching. One merge point rather
+// than three hand-rolled preserves, because getting that wrong silently disarms
+// whichever map got clobbered.
+function updateSyncCache(siteDir, patch) {
   const p = syncCachePath(siteDir)
   mkdirSync(dirname(p), { recursive: true })
-  writeFileSync(p, JSON.stringify({ version: 1, hashes }, null, 2) + '\n')
+  const prior = readSyncCacheFile(siteDir)
+  const out = { version: 1, ...prior, ...patch }
+  delete out.version
+  writeFileSync(p, JSON.stringify({ version: 1, ...out }, null, 2) + '\n')
+}
+const readMap = (siteDir, key) => {
+  const v = readSyncCacheFile(siteDir)[key]
+  return v && typeof v === 'object' ? v : {}
+}
+
+export function readSyncCache(siteDir) {
+  return readMap(siteDir, 'hashes')
+}
+export function writeSyncCache(siteDir, hashes) {
+  updateSyncCache(siteDir, { hashes })
+}
+
+/**
+ * The push gate's optimistic-concurrency tokens: `{ <backend-uuid>: <version> }`.
+ *
+ * Lives beside the content hashes because it is the same kind of thing — "the
+ * backend state this clone last agreed with" — and is already per-entity, which
+ * the per-lane `pull-cache.json` (two ETags) is not. Gitignored, per-clone,
+ * deletable: losing it means the next push is unconditional, i.e. today's
+ * behavior, never a wrong-but-plausible token.
+ *
+ * Fed from BOTH directions, which is what makes the gate usable: `pull` records
+ * the manifest's `extra.version`, and every successful push records the
+ * post-write `finalized[].version` the backend returns. Without the push half a
+ * second consecutive push would be stale by construction and refused.
+ */
+export function readBaseVersions(siteDir) {
+  return readMap(siteDir, 'baseVersions')
+}
+
+/**
+ * Per-ITEM staleness tokens: `{ <record $uuid>: <opaque version> }`.
+ *
+ * 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 and teaches them to reach for `--force`. These gate per record
+ * instead. Same contract as the entity token: opaque, cached, echoed, never parsed.
+ *
+ * Merged rather than replaced: a push carries only CHANGED entities, so a response
+ * reports tokens for a subset of the site. Replacing would drop the tokens of every
+ * record that wasn't in this package and silently degrade those to ungated.
+ */
+export function readItemBaseVersions(siteDir) {
+  return readMap(siteDir, 'itemBaseVersions')
+}
+export function mergeItemBaseVersions(siteDir, versions) {
+  if (!versions || !Object.keys(versions).length) return
+  updateSyncCache(siteDir, { itemBaseVersions: { ...readItemBaseVersions(siteDir), ...versions } })
+}
+export function mergeBaseVersions(siteDir, versions) {
+  if (!versions || !Object.keys(versions).length) return
+  updateSyncCache(siteDir, { baseVersions: { ...readBaseVersions(siteDir), ...versions } })
+}
+
+/**
+ * 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
+ * (`diffSiteUnits`). A unit is a projected file: a page's `page.yml`, each section
+ * `.md`, each layout section.
+ *
+ * Two maps, not one, because our document and the backend's are not byte-comparable
+ * (they carry fields we don't emit and their own key order). A hash from one side
+ * compared against a base from the other differs for a unit nobody touched, so each
+ * side gets a base in its own representation:
+ *   `local`  ← our emitted document
+ *   `remote` ← the backend's own copy (`finalized[].document`, or a pull)
+ *
+ * Replaced wholesale rather than merged: a unit that no longer exists is a unit with
+ * no base, and a stale entry would attribute its next difference to the wrong side.
+ *
+ * Purely an explanation aid — losing either map costs detail in one message, never a
+ * wrong push.
+ */
+/**
+ * Per-item identity: `{ <unit path>: <backend $uuid> }`.
+ *
+ * The backend's reconcile matches a record by `$uuid`. `pages`, `page_sections` and
+ * `layout_sections` are all `multi` sections, where a record WITHOUT a uuid is read
+ * as new — inserted, with its stored counterpart deleted as host-only. So pushing
+ * without this map replaces every page and section row on every push. The content
+ * still lands, which is why it went unnoticed, but the app's per-item concurrency
+ * handles are left pointing at rows that no longer exist.
+ *
+ * Cached here rather than written into `page.yml` / section frontmatter: identity is
+ * a sync concern and author files should not carry sync uuids. Populated from
+ * whatever the backend last told us — a pull, or a push response's
+ * `finalized[].document`, which carries `$uuid` for every item at every nesting
+ * level, so a push alone bootstraps it and no pull is required.
+ *
+ * Losing it (gitignored, per-clone) means the next push would be identity-blind,
+ * which is why `push` repopulates it first — see `ensureItemUuids`. The backend also
+ * refuses an all-blank `multi` section, so a producer that skips that step fails
+ * loudly instead of quietly rebuilding the site's identity.
+ */
+export function readItemUuids(siteDir) {
+  return readMap(siteDir, 'itemUuids')
+}
+export function writeItemUuids(siteDir, map) {
+  if (!map || !Object.keys(map).length) return
+  updateSyncCache(siteDir, { itemUuids: map })
+}
+
+/**
+ * Guarantee we have per-item identity before an identity-bearing push.
+ *
+ * Fires only when the site HAS been pushed before (`$uuid` in site.yml) but the
+ * cache is empty — a fresh `git clone`, or a deleted `.uniweb/`. One read of the
+ * backend's current document, no file writes, no `uniweb pull`. A first-ever push
+ * legitimately has nothing to fetch and is left alone.
+ *
+ * @returns {Promise<Object<string,string>>} the map (possibly empty)
+ */
+export async function ensureItemUuids({ client, siteDir, note }) {
+  const cached = readItemUuids(siteDir)
+  if (Object.keys(cached).length) return cached
+  // A site that has never been pushed has no identity to recover — and nothing to
+  // lose, since every item is genuinely new.
+  let siteContentUuid = null
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    siteContentUuid = typeof y?.$uuid === 'string' ? y.$uuid : null
+  } catch { /* unreadable site.yml — nothing to recover against */ }
+  if (!siteContentUuid) return cached
+  try {
+    const res = await client.pullSiteContent(siteContentUuid)
+    if (!res?.ok) return cached
+    const doc = entityDocFromUwx(Buffer.from(await res.arrayBuffer()))
+    if (!doc) return cached
+    const harvested = collectUnitUuids(doc)
+    if (Object.keys(harvested).length) {
+      writeItemUuids(siteDir, harvested)
+      note?.(`Recovered identity for ${Object.keys(harvested).length} item(s) from the backend.`)
+    }
+    return harvested
+  } catch {
+    // Best-effort: a failure here leaves the push identity-blind, which the backend
+    // refuses rather than silently applying. Better to hit that than to guess.
+    return cached
+  }
+}
+
+export function readUnitBases(siteDir) {
+  const v = readMap(siteDir, 'unitBases')
+  return { local: v.local || {}, remote: v.remote || {} }
+}
+export function writeUnitBases(siteDir, patch) {
+  if (!patch) return
+  updateSyncCache(siteDir, { unitBases: { ...readUnitBases(siteDir), ...patch } })
 }
 
 /**
@@ -157,7 +377,7 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // request fires). The client carries `collision=force` (last-push-wins) + the optional
   // `--as-org`. Returns the parsed payload, or null on any transport/HTTP/parse failure
   // (already reported).
-  const postLane = async (label, doRequest) => {
+  const postLane = async (label, doRequest, explainStale = async () => []) => {
     info(`Pushing ${label} to ${dim(client.origin)} …`)
     let res
     try {
@@ -168,6 +388,53 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       return null
     }
     if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      // Two unrelated conflicts share HTTP 409, so branch on the machine-readable
+      // `reason` — never on `detail`, which is prose the backend may reword.
+      let problem = null
+      if ((res.status === 409 || res.status === 400) && body) {
+        try { problem = JSON.parse(body) } catch { /* not a problem document */ }
+      }
+      // The package carried no identity for records the backend already stores, so
+      // applying it would replace every one of them. `ensureItemUuids` is supposed
+      // to make this unreachable, so reaching it means that recovery failed — say so
+      // rather than surfacing a raw 400.
+      if (problem?.reason === 'identity_required') {
+        error(`${label} push refused — this copy has no record of the site's item identity.`)
+        note('Nothing was written. Pushing without it would have replaced the identity of every stored item.')
+        note('The recovery normally runs automatically, so it likely could not reach the backend.')
+        note('Check your connection and re-run; `uniweb pull` also restores it.')
+        return null
+      }
+      if (problem?.reason === 'stale_base') {
+        error(`${label} push refused — the backend has newer content than your last pull.`)
+        // Page-level account, when we can get one. The gate is entity-grained, so
+        // without this the user only learns "the document moved" and has no basis
+        // for choosing between pulling and forcing.
+        const detail = await explainStale()
+        for (const line of detail) note(line)
+        if (!detail.length) {
+          const stale = Array.isArray(problem.stale_entities) ? problem.stale_entities : []
+          if (stale.length) {
+            note(`Changed upstream: ${stale.length} entit${stale.length === 1 ? 'y' : 'ies'} (${stale.join(', ')})`)
+          }
+        }
+        note('Nothing was written — the whole push was refused before any change.')
+        // Say what will actually work from HERE. Anyone hitting this has local
+        // work — it is why they pushed — and if it is uncommitted then `pull`
+        // refuses too, so bare "run pull" advice walks them into a dead end.
+        if (hasUncommittedContent(siteDir)) {
+          // `--merge` is the recovery that keeps both sides: most of these are two
+          // people editing different parts of one section, which merges silently.
+          // Offer it first, and keep the take-theirs route for anyone who wants it.
+          note('Commit your changes, then `uniweb pull --merge` to combine them with the backend\'s.')
+          note('(Plain `uniweb pull` declines while the work is unsaved — it overwrites rather than merges.)')
+        } else {
+          note('Run `uniweb pull --merge` to combine the changes, or `uniweb pull` to take the backend version.')
+        }
+        note('To overwrite them anyway, re-run with --force (this discards the upstream edits).')
+        return null
+      }
       error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) {
         note("Credentials weren't accepted — supply a bearer with --token <bearer> (or UNIWEB_TOKEN).")
@@ -181,7 +448,6 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
             'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
         )
       }
-      const body = await res.text().catch(() => '')
       if (body) note(body.slice(0, 800))
       return null
     }
@@ -196,8 +462,8 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // POST a lane that round-trips entity uuids (content UPDATE + the folder): parse the
   // finalized list (for record back-fill + the changed summary). Returns the finalized
   // array, or null on failure (already reported).
-  const pushLane = async (label, doRequest) => {
-    const payload = await postLane(label, doRequest)
+  const pushLane = async (label, doRequest, explainStale) => {
+    const payload = await postLane(label, doRequest, explainStale)
     if (payload === null) return null
     const finalized = extractFinalized(payload)
     if (!finalized) {
@@ -215,13 +481,30 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
   // and returns its uuid, which we record into site.yml). `boundSiteUuid` carries the
   // minted/known uuid forward to key the folder push.
   let boundSiteUuid = siteContentUuid
+  // Post-write tokens harvested from every lane, persisted once at the end so a
+  // partial push (lane 1 ok, lane 2 refused) still banks what actually landed —
+  // otherwise the next attempt would re-send lane 1 with a base the backend has
+  // already moved past, and refuse a push the user just made.
+  const newVersions = {}
+  const harvest = (finalized) => {
+    for (const f of finalized || []) if (f.uuid && f.version) newVersions[f.uuid] = f.version
+  }
+  // The backend's post-write copy of the site-content document, kept for the
+  // remote-side unit base (see writeUnitBases).
+  let siteFinalizedDoc = null
   if (siteContent) {
     if (siteContentUuid) {
       const finalized = await pushLane(
         'site-content',
-        () => client.updateSiteContent(siteContentUuid, siteContent.buffer, { asOrg })
+        () => client.updateSiteContent(siteContentUuid, siteContent.buffer, { asOrg }),
+        () => explainStaleSiteContent({ client, siteDir, localBuffer: siteContent.buffer, uuid: siteContentUuid })
       )
-      if (!finalized) return { exitCode: 1, finalizedTotal, wrote }
+      if (!finalized) {
+        mergeBaseVersions(siteDir, newVersions)
+        return { exitCode: 1, finalizedTotal, wrote }
+      }
+      harvest(finalized)
+      siteFinalizedDoc = finalized[0]?.document || null
       finalizedTotal += finalized.length
     } else {
       const payload = await postLane(
@@ -238,7 +521,10 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       writeSiteEntityUuid(siteDir, minted)
       boundSiteUuid = minted
       wrote.push('recorded site $uuid in site.yml')
-      finalizedTotal += extractFinalized(payload)?.length ?? 1
+      const createdFinalized = extractFinalized(payload)
+      harvest(createdFinalized)
+      siteFinalizedDoc = createdFinalized?.[0]?.document || null
+      finalizedTotal += createdFinalized?.length ?? 1
     }
   }
 
@@ -255,7 +541,11 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
       'collections',
       () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg })
     )
-    if (!finalized) return { exitCode: 1, finalizedTotal, wrote }
+    if (!finalized) {
+      mergeBaseVersions(siteDir, newVersions)
+      return { exitCode: 1, finalizedTotal, wrote }
+    }
+    harvest(finalized)
     const bf = backfillEntityUuids({ index: collections.index, finalized })
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
@@ -263,7 +553,29 @@ export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report })
     finalizedTotal += finalized.length
   }
 
-  // Persist the full content-hash map so the next push skips unchanged entities.
+  // Persist the full content-hash map so the next push skips unchanged entities,
+  // then bank the post-write tokens so the NEXT push carries a current base.
+  // Entities absent from finalized[] (skipped, or not editable) keep their cached
+  // value — absence is not invalidation.
   writeSyncCache(siteDir, hashes)
+  mergeBaseVersions(siteDir, newVersions)
+  // Re-base the page attribution: our emitted document and the backend's post-write
+  // copy of it are the two sides' new agreed state. Only when the site-content lane
+  // actually shipped — a push that skipped it left that state where it was.
+  if (siteContent) {
+    const patch = {}
+    const ours = entityDocFromUwx(siteContent.buffer)
+    if (ours) patch.local = computeUnitHashes(ours)
+    // `finalized[].document` is the backend's own representation, read back from
+    // the stored row — the only remote-side base a push can produce.
+    const theirs = siteFinalizedDoc?.pages ? siteFinalizedDoc : null
+    if (theirs) patch.remote = computeUnitHashes(theirs)
+    if (Object.keys(patch).length) writeUnitBases(siteDir, patch)
+    // The backend's post-write document carries `$uuid` per item at every nesting
+    // level, so the push that just landed also re-arms identity for the next one.
+    // Replaced wholesale: an item that no longer exists must not keep a uuid that
+    // would re-target something else.
+    if (theirs) writeItemUuids(siteDir, collectUnitUuids(theirs))
+  }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }

package/src/commands/deploy.js

@@ -53,6 +53,7 @@ import { loadDeployYml, resolveTarget, recordLastDeploy } from '@uniweb/build/si
 import { promptForDestination } from '../utils/destination-prompt.js'
 import { readFlagValue } from '../utils/args.js'
 import { parseBoolEnv } from '../utils/env.js'
+import { headProvenance } from '../utils/git.js'
 
 import {
   findWorkspaceRoot,
@@ -357,12 +358,13 @@ async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave,
 
   // Record a fresh lastDeploy.<target> entry. Skipped on --no-save and
   // on ad-hoc --host overrides — see autoSave gating in deploy().
+  const gitStamp = { at: new Date().toISOString(), git: headProvenance(siteDir) }
   await persistLastDeploy(siteDir, {
     targetName: resolved.targetName,
     targetConfig: resolved.fromFile ? null : { host: hostName, ...deployConfig },
     autoSave,
     lastDeploy: {
-      at: new Date().toISOString(),
+      at: gitStamp.at,
       host: hostName,
       // Adapters that drive a host CLI get the public URL back from it
       // (wrangler/netlify/vercel print it; github-pages derives it from
@@ -370,6 +372,9 @@ async function deployStaticHost(siteDir, hostName, resolved, { dryRun, autoSave,
       // the user's CloudFront/DNS config, which we never see — so the
       // field is simply omitted there rather than guessed.
       ...(deployResult?.url ? { url: deployResult.url } : {}),
+      // Same provenance the Uniweb path records: which commit this artifact came
+      // from, and whether the tree was clean when it was built.
+      ...(gitStamp.git ? { git: gitStamp.git } : {}),
     },
   })
   if (hostOverridden && !dryRun) {