uniweb 0.13.5 → 0.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "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/kit": "0.9.38",
+    "@uniweb/core": "0.7.30",
+    "@uniweb/runtime": "0.8.37"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "1.1.15",
-    "@uniweb/semantic-parser": "1.1.18",
-    "@uniweb/build": "0.15.5"
+    "@uniweb/build": "0.15.6",
+    "@uniweb/content-reader": "1.1.16",
+    "@uniweb/semantic-parser": "1.1.19"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1571,6 +1571,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
 

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) {

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,7 +55,15 @@ 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 { bringFoundationAlong } from '../backend/foundation-bring-along.js'
@@ -296,6 +305,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 +329,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 +394,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 +407,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,