uniweb 1.7.4 → 1.8.1

package/README.md

@@ -340,7 +340,7 @@ This is the best path when site content has a life independent of the foundation
 
 ### Hybrid
 
-Markdown in a git repo and content in the Uniweb apps can share the same site. Directional sync is available today: `uniweb push` sends local content to the backend, `uniweb pull` brings the backend's content back to local files, and `uniweb clone` bootstraps a local project from a site that already lives in the backend. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. The advanced two-way-merge experience — conflict resolution, branch isolation, and review flows when both surfaces change the same content concurrently — is still evolving.
+Markdown in a git repo and content in the Uniweb apps can share the same site. `uniweb push` sends local content to the backend, `uniweb pull` brings the backend's content back — in a git repository by merging it into your branch, like `git pull`, so edits made on both surfaces at once are combined and only a genuine overlap is a conflict to settle — and `uniweb clone` bootstraps a local project from a site that already lives in the backend. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. Review flows and branch isolation across the two are still evolving.
 
 ### Commands at a glance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "~1.2.2",
     "@uniweb/content-writer": "~1.1.2",
-    "@uniweb/schemas": "~1.3.1",
-    "@uniweb/semantic-parser": "~1.8.1"
+    "@uniweb/core": "~1.2.2",
+    "@uniweb/semantic-parser": "~1.8.1",
+    "@uniweb/schemas": "~1.4.0"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "~1.8.1",
+    "@uniweb/build": "~1.3.10",
     "@uniweb/content-reader": "~1.4.0",
-    "@uniweb/build": "~1.3.9"
+    "@uniweb/semantic-parser": "~1.8.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

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

package/src/backend/client.js

@@ -121,6 +121,18 @@ export const DISCOVERY_DEFAULTS = {}
  */
 export const WORKSPACE_HEADER = 'x-uniweb-workspace'
 
+/**
+ * The header naming where a push's content came from — the commit it was made from — and
+ * where a pull's content last came from, as the backend recorded it.
+ *
+ * ⭐ Opaque to the backend: it stores the value a push sends, with the version that push
+ * produced, and returns it on every pull of that entity. A copy whose history holds that
+ * commit merges from it (`utils/sync-point.js`) — the precise base, for a teammate or a
+ * fresh clone that never saw the push. Absent on a pull, there is simply no such base.
+ */
+export const SOURCE_HEADER = 'x-uniweb-source'
+const sourceHeaders = (source) => (source ? { [SOURCE_HEADER]: source } : {})
+
 /**
  * Whether a request works IN a workspace — a site route, `/dev/site…`.
  *
@@ -788,29 +800,35 @@ export class BackendClient {
     })
   }
 
-  /** POST /dev/site/content — CREATE a site from its content lane (.uwx zip). */
-  async createSiteContent(buffer) {
+  /**
+   * POST /dev/site/content — CREATE a site from its content lane (.uwx zip). `source`: the
+   * commit the content came from (`SOURCE_HEADER`).
+   */
+  async createSiteContent(buffer, { source } = {}) {
     return this.request('/dev/site/content', {
       method: 'POST',
       body: buffer,
+      headers: sourceHeaders(source),
       query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/content/push/{uuid} — UPDATE the content lane by site uuid (.uwx zip). */
-  async updateSiteContent(uuid, buffer) {
+  async updateSiteContent(uuid, buffer, { source } = {}) {
     return this.request(`/dev/site/content/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
+      headers: sourceHeaders(source),
       query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/folder/push/{uuid} — push the folder lane, keyed by the site uuid (.uwx zip). */
-  async pushFolder(uuid, buffer) {
+  async pushFolder(uuid, buffer, { source } = {}) {
     return this.request(`/dev/site/folder/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
+      headers: sourceHeaders(source),
       query: PUSH_QUERY
     })
   }

package/src/backend/site-sync.js

@@ -14,8 +14,16 @@
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
 import { join, dirname, relative, isAbsolute, basename } from 'node:path'
 import yaml from 'js-yaml'
-import { hasUncommittedContent } from '../utils/git.js'
-import { recordWritten } from '../utils/pull-written.js'
+import {
+  repoOf,
+  readSyncPoint,
+  writeSyncPoint,
+  isAncestor,
+  contentCommitted,
+  unmergedPaths,
+  mergeInProgress
+} from '../utils/sync-point.js'
+import { siteContentRoots } from '../utils/git.js'
 import { humanBytes } from '../utils/bytes.js'
 import { isAuthoredPreview } from '../utils/preview.js'
 import {
@@ -301,10 +309,8 @@ export function pulledItemVersions(doc, itemVersions) {
 // ⭐ A section unit's path names it by its id (`pages/about/about.md`), and the author's
 // file may carry an ordering prefix or a child mark (`1-about.md`, `@about.md`), which a
 // pull writes back into in place. So the unit is looked up as a pull finds it
-// (`existingSectionFile`). ⛔ Until 2026-10-07 the id path was taken as the file: a push
-// recorded no file for a numbered section, and the next `pull --merge` merged against an
-// older version — a false conflict on a line only the other side had changed (measured
-// on the starter's `1-welcome.md`).
+// (`existingSectionFile`). ⛔ Until 2026-10-07 the id path was taken as the file, which
+// names nothing for a numbered section (measured on the starter's `1-welcome.md`).
 export function unitFilesOf(siteDir, unitPath) {
   if (unitPath === 'site.yml') return ['site.yml', 'theme.yml', 'head.html']
   let paths = {}
@@ -330,24 +336,6 @@ export function unitFilesOf(siteDir, unitPath) {
   return []
 }
 
-/**
- * Record, as synced, the files of the units a push left on the backend as we sent them.
- *
- * ⭐ WHAT A PUSH DELIVERED IS THE NEXT MERGE'S ANCESTOR. `pull --merge` finds the
- * version a file last synced at by the hash in `pull-written.json`. A pull records what
- * it wrote; this records what a push delivered — the units `heldTokens` says the
- * backend holds as ours, never one it kept for someone else. Without it, after a merge
- * and a push the ancestor was the pull's raw output, which nobody commits: the next
- * merge found no common version and put both whole files under conflict markers, for
- * edits on different lines (measured 2026-09-23).
- */
-function recordPushedUnits(siteDir, unitPaths) {
-  const files = new Set()
-  for (const p of unitPaths) for (const f of unitFilesOf(siteDir, p)) files.add(f)
-  const present = [...files].map((f) => join(siteDir, f)).filter((abs) => existsSync(abs))
-  if (present.length) recordWritten(siteDir, present)
-}
-
 // Pull the finalized entities out of the restore response. The backend returns
 // `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each entry
 // carries its position in the SUBMITTED sequence (`index`, the correlation key — `$id`
@@ -919,6 +907,106 @@ export function mergeBaseVersions(siteDir, backend, versions) {
   })
 }
 
+/**
+ * ⛔ A PUSH NEVER SENDS A FILE IN CONFLICT. Where git marks a file under the site unmerged — a
+ * merge stopped on it, or uncommitted work a merge could not put back — the file holds markers,
+ * and a push hands them to every author editing the site, then to its visitors once published.
+ * Refused whatever the flags: `--force` overwrites the backend's changes, it never sends
+ * markers. Returns the refusal, or null.
+ *
+ * ⛔ Until 2026-10-17 nothing checked it: a pull whose stash could not be put back exited 0,
+ * and the push after it sent the markers [flows, measured against a real backend, 1.8.0].
+ */
+export function unsettledFiles(siteDir) {
+  const repo = repoOf(siteDir)
+  if (!repo) return null
+  const paths = unmergedPaths(repo).filter((p) => !repo.prefix || p.startsWith(repo.prefix))
+  if (!paths.length) return null
+  return {
+    headline: `Not pushed — ${paths.length} file(s) here are in conflict:`,
+    lines: [
+      ...paths.slice(0, 12).map((p) => `  ${p}`),
+      ...(paths.length > 12 ? [`  … and ${paths.length - 12} more`] : []),
+      'Settle each one and `git add` it, then push.'
+    ]
+  }
+}
+
+/**
+ * Why a gated push must not go — or null when it may.
+ *
+ * ⛔ A PUSH CLAIMS A BASE ONLY WHILE ITS FILES HOLD IT. The versions it sends say "my content
+ * descends from the backend's at these versions". In a repository they describe one commit,
+ * the sync point this copy's last pull merged or its last push was made from
+ * (`utils/sync-point.js`), and they are true of the files only while HEAD's history holds
+ * it: a merge abandoned or a branch reset, and the push would put back what the backend's
+ * newer content replaced.
+ *
+ * ⛔ AND A SITE THE BACKEND HAS, PUSHED WITH NO VERSIONS AT ALL, GOES OVER WHATEVER CHANGED
+ * THERE — an entry without a token falls back to the `collision` policy, which the client
+ * sends as `force`. Until 2026-10-17 that was a fresh clone's first push, or any copy whose
+ * cache was gone.
+ *
+ * A push that creates the site has nothing to be stale against.
+ *
+ * @returns {null | { headline: string, lines: string[] }}
+ */
+export function untakenBase(siteDir, backend) {
+  if (!readBackendState(siteDir, backend).site?.uuid) return null
+  const held = Object.keys(readBaseVersions(siteDir, backend)).length > 0
+  const repo = repoOf(siteDir)
+  if (repo?.head) {
+    const point = readSyncPoint(siteDir, backend)
+    if (held && point && isAncestor(repo, point)) return null
+    // A pull's merge waiting for its commit is not one abandoned: say which.
+    if (held && point && mergeInProgress(repo)) {
+      return {
+        headline: 'Not pushed — a merge is in progress here.',
+        lines: ['Finish it (`git commit`), then push — or abandon it (`git merge --abort`) and pull again.']
+      }
+    }
+    return {
+      headline: "Not pushed — your branch does not hold the backend content this copy last took.",
+      lines: [
+        point && held
+          ? 'The pull or push it came from is not in your history — a merge abandoned, or the branch moved.'
+          : 'This copy has not taken the site from this backend yet.',
+        "Run `uniweb pull` to merge the backend's content with yours, then push.",
+        'To push over it regardless, re-run with --force (this discards changes made there).'
+      ]
+    }
+  }
+  if (held) return null
+  return {
+    headline: 'Not pushed — this copy holds no record of the backend content it last took.',
+    lines: [
+      'A push now would go over whatever changed there.',
+      "`uniweb pull` takes the backend's version over your files here, outside git; under git a pull merges instead.",
+      'To push over it regardless, re-run with --force (this discards changes made there).'
+    ]
+  }
+}
+
+/**
+ * A push that finds nothing to send has learned that the backend holds what this commit
+ * sends — so the commit is a sync point, as the one a push is made from is
+ * (`pushSyncPackages`). Kept only where HEAD holds the site's content as the files do: with
+ * a change under the roots not committed, HEAD is not what was compared, and a base the
+ * backend's content does not descend from would read a committed change the backend lacks
+ * as its removal. Returns the commit kept, or null.
+ *
+ * ⛔ Until 2026-10-17 it kept nothing, so a paragraph re-wrapped and committed — which a push
+ * calls "nothing to push", a plain newline being a space — was merged on the next pull from
+ * the commit before it, and conflicted with an author's words typed into it since.
+ */
+export function holdUnchangedPush(siteDir, backend) {
+  const repo = repoOf(siteDir)
+  if (!repo?.head || !readBackendState(siteDir, backend).site?.uuid) return null
+  if (!contentCommitted(repo, [...siteContentRoots(siteDir), 'public'])) return null
+  writeSyncPoint(siteDir, backend, repo.head)
+  return repo.head
+}
+
 /**
  * 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
@@ -1905,6 +1993,12 @@ export async function pushSyncPackages({
   let finalizedTotal = 0
   // Records sent as drafts that the backend stored enabled — reported at the end.
   let draftsNotKept = []
+  // ⭐ THE COMMIT THIS PUSH IS MADE FROM — sent with each lane, so the backend can name it on
+  // a pull, and kept here as this copy's sync point once a lane lands: what the backend
+  // holds descends from it (`utils/sync-point.js`). ⚖️ Uncommitted edits ride on top of it,
+  // and it stays a safe base for them — both sides hold them, so a merge takes them once.
+  const repo = repoOf(siteDir)
+  const source = repo?.head || null
 
   // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
   // returning the client's Response promise (so the "Pushing …" line prints before the
@@ -2067,22 +2161,14 @@ export async function pushSyncPackages({
         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.)'
-          )
+        // Say what will actually work from HERE. Anyone hitting this has local work — it is
+        // why they pushed. In a repository a pull merges it with the backend's, committed or
+        // not; outside one a pull takes the backend's version over the files.
+        if (repo) {
+          note("Run `uniweb pull` to merge the backend's changes with yours, then push again.")
         } else {
           note(
-            'Run `uniweb pull --merge` to combine the changes, or `uniweb pull` to take the backend version.'
+            "Outside git, `uniweb pull` takes the backend's version over your files. Put the site under git and a pull merges instead."
           )
         }
         note(
@@ -2226,10 +2312,12 @@ export async function pushSyncPackages({
       if (f.uuid && f.version) newVersions[f.uuid] = f.version
     }
   }
-  // Both grains land together, at every point the old code banked the entity one.
+  // Both grains land together, at every point the old code banked the entity one — and
+  // with them the commit they describe.
   const mergeHarvested = () => {
     mergeBaseVersions(siteDir, client.origin, newVersions)
     if (heldItemVersions) writeItemBaseVersions(siteDir, client.origin, heldItemVersions)
+    if (source && (Object.keys(newVersions).length || heldItemVersions)) writeSyncPoint(siteDir, client.origin, source)
   }
   // ⛔ The site-content lane banks only the tokens for content this copy holds — the
   // document we sent against the one the backend stored (`heldTokens`, and the two
@@ -2237,7 +2325,6 @@ export async function pushSyncPackages({
   // collected here, to re-base attribution and to say so.
   const sentSiteDoc = siteContent ? entityDocFromUwx(siteContent.buffer) : null
   const notHeld = { kept: [], foreign: [] }
-  const heldUnits = []
   const harvestSiteContent = (finalized) => {
     for (const f of finalized || []) {
       const held = heldTokens({
@@ -2249,7 +2336,6 @@ export async function pushSyncPackages({
       })
       harvest([{ ...f, version: held.version }])
       if (held.itemVersions) heldItemVersions = held.itemVersions
-      heldUnits.push(...held.held)
       notHeld.kept.push(...held.kept)
       notHeld.foreign.push(...held.foreign)
     }
@@ -2331,16 +2417,13 @@ export async function pushSyncPackages({
           'may refuse it. `uniweb pull` re-arms identity if that happens.'
       )
     }
-    // The files of the units the backend now holds as ours are the synced version — the
-    // ancestor the next `pull --merge` merges from.
-    if (heldUnits.length) recordPushedUnits(siteDir, heldUnits)
   }
   if (siteContent) {
     if (siteContentUuid) {
       const finalized = await pushLane(
         'site-content',
         () =>
-          client.updateSiteContent(siteContentUuid, siteContent.buffer),
+          client.updateSiteContent(siteContentUuid, siteContent.buffer, { source }),
         () =>
           explainStaleSiteContent({
             client,
@@ -2361,7 +2444,7 @@ export async function pushSyncPackages({
     } else {
       const payload = await postLane(
         'site-content',
-        () => client.createSiteContent(siteContent.buffer),
+        () => client.createSiteContent(siteContent.buffer, { source }),
         undefined,
         { reportTemplate: true }
       )
@@ -2408,7 +2491,7 @@ export async function pushSyncPackages({
     }
     const finalized = await pushLane(
       'records',
-      () => client.pushFolder(boundSiteUuid, records.buffer),
+      () => client.pushFolder(boundSiteUuid, records.buffer, { source }),
       undefined,
       { boundUuid: boundSiteUuid }
     )
@@ -2498,7 +2581,7 @@ export async function pushSyncPackages({
       ...new Set([...notHeld.kept, ...notHeld.foreign].map((p) => (p === 'site.yml' ? p : unitFilesOf(siteDir, p)[0] || p)))
     ].sort()
     note(`Changed on the backend by someone else, not in your files yet: ${paths.join(', ')}`)
-    note('Take them with `uniweb refresh` (or `uniweb pull --merge`). Until then, pushing leaves them as they are.')
+    note('Take them with `uniweb refresh` (or `uniweb pull`). Until then, pushing leaves them as they are.')
   }
   // ⛔ A DRAFT THE BACKEND STORED ENABLED FAILS THE PUSH, and only here, after every
   // piece of sync state above is banked: the push itself happened, and the next one must

package/src/commands/clone.js

@@ -39,6 +39,7 @@
  *   uniweb clone <uuid> --path sites     Place under sites/ (segregated layout)
  *   uniweb clone <uuid> --project docs   Co-located docs/site
  *   uniweb clone <uuid> --no-records Pull pages only; skip records
+ *   uniweb clone <uuid> --no-git     Do not start a git repository for the new project
  *   uniweb clone <uuid> --org @org       Work in @org for this clone, instead of the
  *                                        workspace chosen at `uniweb login`. A site in
  *                                        another workspace stops it.
@@ -51,8 +52,8 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join, resolve, basename, dirname } from 'node:path'
-import { spawnSync } from 'node:child_process'
+import { join, resolve, basename, dirname, relative, sep } from 'node:path'
+import { spawnSync, execFileSync } from 'node:child_process'
 import { scaffoldWorkspace, scaffoldSite } from '../utils/scaffold.js'
 import { resolvePlacement, projectConflictLines, SITE_KIND } from '../utils/placement.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
@@ -63,8 +64,8 @@ import { resolveWorkspace } from '../backend/workspace.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 import { extractFoundationRef } from '../utils/site-content-refs.js'
 import { readUwxDocuments } from '../utils/uwx-read.js'
-import { recordWritten } from '../utils/pull-written.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import { repoOf, writeSyncPoint, SYNC_TRAILER, SITE_TRAILER } from '../utils/sync-point.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -98,6 +99,9 @@ function slugify(s) {
     .replace(/^-+|-+$/g, '')
 }
 
+// The data schema a site's own document names (`$schema`, as the push writes it).
+const SITE_MODEL = '@uniweb/site-content'
+
 // Tolerant single-entity document extraction (mirrors pull.js; duplicated rather
 // than imported because pull.js statically imports @uniweb/build).
 export function extractDocument(payload) {
@@ -169,6 +173,48 @@ function seedSyncJson(siteDir, origin, uuid) {
   writeFileSync(file, JSON.stringify(doc, null, 2) + '\n')
 }
 
+/**
+ * Start the new project's history at a sync point — the site as the backend has it.
+ *
+ * ⭐ Like `uniweb create`, a clone puts its project under git unless a repository already
+ * holds it — one it is inside, in a folder that repository does not ignore (`repoOf`); and
+ * its first commit holds the site as the backend has it, marked so a pull merges from it
+ * (`utils/sync-point.js`). Inside a repository the clone's pull already left one, in the
+ * commit that took the site.
+ */
+function startHistory({ projectDir, siteDir, origin, siteUuid }) {
+  const git = (args, input) =>
+    execFileSync('git', args, {
+      cwd: projectDir,
+      encoding: 'utf8',
+      input,
+      stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'pipe']
+    })
+  try {
+    git(['--version'])
+  } catch {
+    return // no git here: the project works without one, and a pull checks out
+  }
+  if (repoOf(projectDir)) return
+  try {
+    git(['init', '-q'])
+    git(['add', '-A'])
+    const sitePath = relative(projectDir, siteDir).split(sep).join('/')
+    const siteTree = git(sitePath ? ['write-tree', `--prefix=${sitePath}/`] : ['write-tree']).trim()
+    git(
+      ['commit', '-q', '-F', '-'],
+      `Clone the site from ${origin}\n\n${SYNC_TRAILER}: ${origin} ${siteUuid}\n${SITE_TRAILER}: ${sitePath || '.'}:${siteTree}\n`
+    )
+    writeSyncPoint(siteDir, origin, git(['rev-parse', 'HEAD']).trim())
+    success('Git repository initialized, its first commit the site as the backend has it')
+  } catch (err) {
+    note(
+      `! A git repository was started, but its first commit failed${err?.stderr ? `: ${String(err.stderr).trim().split('\n')[0]}` : ''}.`
+    )
+    note('  Commit the project before your first `uniweb pull`, so the pull has something to merge into.')
+  }
+}
+
 // Build the package-manager argv to run the project-local `uniweb pull`.
 function pullExecArgv(pm, extra) {
   // npm needs `exec --` to forward flags to the binary; pnpm/yarn don't.
@@ -265,6 +311,15 @@ export async function clone(args = [], deps = {}) {
     return { exitCode: 1 }
   }
   const { foundationRef, name: siteDisplayName } = extractCloneSeeds(document)
+  // ⛔ An id that names another entity — a record's, say — comes back as that entity. Say
+  // so, rather than ask for a foundation and a name it could never have: only where it
+  // names another data schema AND carries neither, so a site is never turned away.
+  const named = typeof document.$schema === 'string' ? document.$schema : null
+  if (named && named !== SITE_MODEL && !foundationRef && !siteDisplayName) {
+    error(`${siteUuid} is not a site on ${client.origin} — it is a ${named} entity.`)
+    note('`uniweb clone` takes a site\'s id: `uniweb site list` shows each site with its id.')
+    return { exitCode: 1 }
+  }
   if (!foundationRef) {
     note(
       '! The pulled site declares no foundation ref — set `foundation:` in site.yml after clone.'
@@ -411,32 +466,12 @@ export async function clone(args = [], deps = {}) {
     }
   }
 
-  // Tell the delegated pull which files WE wrote, or it refuses on them.
-  //
-  // Pull guards against overwriting uncommitted work under the paths it rewrites,
-  // and `site.yml` / `theme.yml` are exactly those paths — uncommitted here
-  // because clone scaffolded them seconds ago. Without this, clone reliably ends
-  // in "Refusing to pull: 2 uncommitted change(s)" on a project it just created,
-  // where there is no user work to protect. The advice it prints (`--force`) is
-  // both unreachable — clone does not forward that flag — and wrong, since it
-  // means "discard my changes" and the changes are ours.
-  //
-  // ⭐ This exempts them for the RIGHT reason rather than overriding the guard.
-  // `recordWritten` stores a content hash, so a file the user edits between
-  // scaffold and pull no longer matches and the refusal correctly stands. The
-  // guard keeps its teeth; it just stops firing on machine output, which is what
-  // it already does for pull's own writes.
-  //
-  // Recorded AFTER the uuid seeding above — the hash has to be of the final
-  // bytes on disk, not of what the scaffolder first wrote.
-  recordWritten(
-    siteDir,
-    ['site.yml', 'theme.yml', 'head.html', 'queries.yml', join('records', 'folder.yml')]
-      .map((f) => join(siteDir, f))
-      .filter((p) => existsSync(p))
-  )
-
-  const pullExtra = []
+  // ⭐ The delegated pull takes the backend's version whole (`--force`): every file under
+  // what it writes is one this clone scaffolded seconds ago — the site directory is new
+  // (refused above when it is not) — so there is nothing of the author's to protect.
+  // ⛔ Until 2026-10-17 clone recorded its scaffold as pull output instead, so the pull's
+  // guard let it through; a pull inside a repository merges now, and has no such guard.
+  const pullExtra = ['--force']
   if (noRecords) pullExtra.push('--no-records')
   // The workspace this clone was told to work in: the pull is another process, and asks the same
   // question. ⛔ Until 2026-09-26 it was not told, so it used the login's — or, with none chosen,
@@ -463,6 +498,10 @@ export async function clone(args = [], deps = {}) {
     }
   }
 
+  if (!deps.skipGit && !args.includes('--no-git')) {
+    startHistory({ projectDir, siteDir, origin: client.origin, siteUuid })
+  }
+
   log('')
   success(
     `Cloned site into ${colors.bright}${isNewWorkspace && !inPlace ? workspaceName : siteDir}${colors.reset}`

package/src/commands/publish.js

@@ -103,6 +103,8 @@ import {
   ensureSiteExists,
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
+  untakenBase,
+  unsettledFiles,
   dropSiteBoundValues,
   pushSyncPackages
 } from '../backend/site-sync.js'
@@ -320,6 +322,27 @@ export async function publish(args = []) {
     }
   }
 
+  // ⛔ The gated push publish rides claims a base only while the files hold it
+  // (`untakenBase`) — said before anything reaches the backend, the foundation's release
+  // included. `--force` drops the gate; a dry run does not preview it. ⛔ *Until 2026-10-17
+  // it ran after the bring-along and the build, so a refused publish could release a local
+  // foundation first.*
+  // ⛔ Never a file in conflict — whatever the flags (`unsettledFiles`).
+  const unsettled = unsettledFiles(siteDir)
+  if (unsettled) {
+    say.err(unsettled.headline)
+    for (const line of unsettled.lines) say.dim(line)
+    return { exitCode: 1 }
+  }
+  if (!dryRun && !args.includes('--force')) {
+    const untaken = untakenBase(siteDir, client.origin)
+    if (untaken) {
+      say.err(untaken.headline)
+      for (const line of untaken.lines) say.dim(line)
+      return { exitCode: 1 }
+    }
+  }
+
   // ⭐ THE WORKSPACE THIS PUBLISH WORKS IN — the one chosen with the login, unless this
   // command names another (`workspace.js`). Resolved up front: `ensureSiteExists` below
   // creates the site in it, and a site the backend keeps elsewhere is refused.
@@ -622,7 +645,6 @@ export async function publish(args = []) {
       `Dropped the previous site's ${droppedValues.join(' and ')} from site.yml.`
     )
   }
-
   // 3b. Make sure the SITE EXISTS before a single byte is uploaded.
   //
   //     Uploaded bytes are metered against an owning entity and reclaimed by