uniweb 1.8.0 → 1.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.8.0",
+  "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/content-writer": "~1.1.2",
     "@uniweb/core": "~1.2.2",
     "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/content-writer": "~1.1.2",
-    "@uniweb/schemas": "~1.3.1"
+    "@uniweb/schemas": "~1.4.0"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/build": "~1.3.9",
-    "@uniweb/content-reader": "~1.4.0"
+    "@uniweb/build": "~1.3.10",
+    "@uniweb/content-reader": "~1.4.0",
+    "@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. **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`. `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, `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
+**Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. `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.
 

package/src/backend/site-sync.js

@@ -14,7 +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 { repoOf, readSyncPoint, writeSyncPoint, isAncestor } from '../utils/sync-point.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 {
@@ -898,6 +907,31 @@ 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.
  *
@@ -924,6 +958,13 @@ export function untakenBase(siteDir, backend) {
   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: [
@@ -946,6 +987,26 @@ export function untakenBase(siteDir, backend) {
   }
 }
 
+/**
+ * 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

package/src/commands/clone.js

@@ -99,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) {
@@ -173,10 +176,11 @@ function seedSyncJson(siteDir, origin, uuid) {
 /**
  * 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 it is already inside a
- * repository; 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.
+ * ⭐ 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) =>
@@ -307,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.'

package/src/commands/publish.js

@@ -104,6 +104,7 @@ import {
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
   untakenBase,
+  unsettledFiles,
   dropSiteBoundValues,
   pushSyncPackages
 } from '../backend/site-sync.js'
@@ -321,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.
@@ -623,17 +645,6 @@ export async function publish(args = []) {
       `Dropped the previous site's ${droppedValues.join(' and ')} from site.yml.`
     )
   }
-  // ⛔ The gated push publish rides claims a base only while the files hold it — said here,
-  // before anything is uploaded or created (`untakenBase`). `--force` drops the gate.
-  if (!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 }
-    }
-  }
-
   // 3b. Make sure the SITE EXISTS before a single byte is uploaded.
   //
   //     Uploaded bytes are metered against an owning entity and reclaimed by

package/src/commands/pull.js

@@ -110,13 +110,16 @@ import { siteContentRoots } from '../utils/git.js'
 import {
   repoOf,
   mergeInProgress,
+  unmergedPaths,
   isAncestor,
   historySyncPoint,
+  madeOnto,
   newestBase,
   openStandIn,
   mergeSyncPoint,
   takeSyncPoint,
-  changesBetween,
+  snapshotFiles,
+  changedInFiles,
   readSyncPoint,
   writeSyncPoint
 } from '../utils/sync-point.js'
@@ -574,6 +577,13 @@ export async function pull(args = [], deps = {}) {
       note('Finish it (`git commit`) or abandon it (`git merge --abort`), then pull.')
       return { exitCode: 1 }
     }
+    const unsettled = unmergedPaths(repo)
+    if (unsettled.length) {
+      error(`${unsettled.length} file(s) here are in conflict:`)
+      for (const p of unsettled.slice(0, 12)) note(`  ${p}`)
+      note('Settle them first — `git status` says how — then pull.')
+      return { exitCode: 1 }
+    }
   } else if (!repo && !dryRun && !force) {
     const blocked = await checkWorkingTree(siteDir, args)
     if (blocked) return blocked
@@ -887,6 +897,8 @@ export async function pull(args = [], deps = {}) {
     base = newestBase(repo, [
       historySyncPoint(repo, { origin: client.origin, siteUuid: siteContentUuid }),
       held,
+      // What a sync point the branch no longer holds — a merge abandoned — was made onto.
+      ...madeOnto(repo, held, { origin: client.origin, siteUuid: siteContentUuid }),
       content?.source,
       folderLane?.source
     ])
@@ -1114,13 +1126,12 @@ export async function pull(args = [], deps = {}) {
         siteUuid: siteContentUuid,
         always: force || !base
       })
-      standIn.close()
-      standIn = null
       if (!made.commit) {
         // The backend holds what the base holds: nothing to merge.
         writeSyncPoint(siteDir, client.origin, base)
       } else {
-        merge.changed = changesBetween(repo, force || !base ? repo.head : base, made.commit)
+        // The files as they are, to tell what the pull changes in them from what they held.
+        const files = snapshotFiles(repo)
         const result = force
           ? takeSyncPoint(repo, made.commit, { roots, message: takenFrom(client.origin) })
           : mergeSyncPoint(repo, made.commit, { message: mergedFrom(client.origin) })
@@ -1138,15 +1149,40 @@ export async function pull(args = [], deps = {}) {
           } else if (result.reason === 'merge-in-progress') {
             error('A merge is in progress here.')
             note('Finish it (`git commit`) or abandon it (`git merge --abort`), then pull.')
+          } else if (result.reason === 'unmerged') {
+            error(`${result.paths.length} file(s) here are in conflict:`)
+            for (const p of result.paths.slice(0, 12)) note(`  ${p}`)
+            note('Settle them first — `git status` says how — then pull.')
           } else {
             error("Could not merge the backend's content:")
             for (const line of String(result.detail).split('\n').slice(0, 8)) note(`  ${line}`)
           }
         } else {
           merge.conflicted = result.conflicted || []
+          merge.stashKept = Boolean(result.stashKept)
+          merge.noBase = !force && !base
+          merge.changed = changedInFiles(repo, {
+            from: repo.head,
+            files,
+            staged: merge.conflicted.length > 0 && !merge.stashKept,
+            skip: merge.conflicted
+          })
           writeSyncPoint(siteDir, client.origin, made.commit)
         }
       }
+      // ⭐ What this pull wrote where the repository ignores it travels in no commit — media
+      // in a folder kept out of git — so it is placed where the files lack it, once the
+      // content is taken. Never over a file they have.
+      if (!notTaken) {
+        const placed = standIn.placeIgnored()
+        if (placed.length) {
+          note(`Placed ${placed.length} file(s) the repository ignores, which no commit carries:`)
+          for (const p of placed.slice(0, 12)) note(`  ${p}`)
+          if (placed.length > 12) note(`  … and ${placed.length - 12} more`)
+        }
+      }
+      standIn.close()
+      standIn = null
     }
   } finally {
     standIn?.close()
@@ -1190,19 +1226,36 @@ export async function pull(args = [], deps = {}) {
   if (notTaken || recordsNotPlaced) info(summary)
   else success(summary)
   if (repo && !notTaken) {
-    if (!projected || !merge.changed.length) {
-      note(`Your files already hold what ${client.origin} has.`)
-    } else {
-      const verb = force ? 'Took' : 'Merged'
-      info(`${verb} ${merge.changed.length} change(s) from ${client.origin}:`)
+    // ⭐ What the pull changed in the files — not the backend's content against the base,
+    // which also lists what the files already held (`changedInFiles`).
+    if (projected && merge.changed.length) {
+      info(
+        force
+          ? `Took ${client.origin}'s version of ${merge.changed.length} file(s):`
+          : `Merged ${merge.changed.length} change(s) from ${client.origin}:`
+      )
       const label = { A: 'added', M: 'changed', D: 'removed', R: 'renamed' }
       for (const [s, p] of merge.changed.slice(0, 12)) note(`  ${label[s] || s} ${p}`)
       if (merge.changed.length > 12) note(`  … and ${merge.changed.length - 12} more`)
+      if (force) note('What they held is in the commit before this one (`git diff HEAD^1 HEAD`), unless it was never committed.')
+    } else if (!merge.conflicted.length) {
+      note(`Your files already hold what ${client.origin} has.`)
     }
     if (merge.conflicted.length) {
       error(`${merge.conflicted.length} file(s) have conflicts to resolve:`)
       for (const f of merge.conflicted) note(`  ${f}`)
-      note('Settle them, then `git commit` to finish the merge — your uncommitted changes come back with it.')
+      if (merge.stashKept) {
+        // The merge is made; what clashed is the uncommitted work put back over it.
+        note('Your uncommitted changes there overlap what the pull brought.')
+        note('Settle the markers and `git add` each file, then `git stash drop` — git kept those changes in the stash as well.')
+      } else {
+        if (merge.noBase) {
+          note(`No commit in this history is one ${client.origin}'s content came from, so nothing tells`)
+          note("your changes from the backend's: each file where they differ is a conflict, yours against the backend's.")
+          note('Once this merge is committed, later pulls merge from it.')
+        }
+        note('Settle them and `git add` each, then `git commit` to finish the merge — your uncommitted changes come back with it.')
+      }
     }
   }
   // Unresolved conflicts are a non-zero exit, the way a conflicted `git merge` is.

package/src/commands/push.js

@@ -96,6 +96,8 @@ import {
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
   untakenBase,
+  unsettledFiles,
+  holdUnchangedPush,
   pushSyncPackages
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
@@ -210,6 +212,26 @@ export async function push(args = [], deps = {}) {
     }
   }
 
+  // ⛔ A GATED PUSH CLAIMS A BASE ONLY WHILE THE FILES HOLD IT (`untakenBase`) — said before
+  // anything reaches the backend, the foundation's release included. A dry run previews it;
+  // `-o` reaches no backend, and `--force` drops the gate. ⛔ *Until 2026-10-17 it ran after
+  // the bring-along, so a refused push could release a local foundation first.*
+  // ⛔ Never a file in conflict — whatever the flags (`unsettledFiles`).
+  const unsettled = unsettledFiles(siteDir)
+  if (unsettled) {
+    error(unsettled.headline)
+    for (const line of unsettled.lines) note(line)
+    return { exitCode: 1 }
+  }
+  if (!output && !force) {
+    const untaken = untakenBase(siteDir, client.origin)
+    if (untaken) {
+      error(untaken.headline)
+      for (const line of untaken.lines) note(line)
+      return { exitCode: 1 }
+    }
+  }
+
   // ⚠️ Logged in to a backend where this project has no site, while it has one
   // elsewhere: following the login CREATES a second site. Say so before the owner
   // question, which otherwise arrives with no reason attached. Not for `-o` (nothing is
@@ -337,17 +359,6 @@ export async function push(args = [], deps = {}) {
       note(`Dropped the previous site's ${stale.join(' and ')} from site.yml.`)
     }
   }
-  // ⛔ A GATED PUSH CLAIMS A BASE ONLY WHILE THE FILES HOLD IT (`untakenBase`) — said before
-  // anything is uploaded. A dry run previews it; `-o` reaches no backend, and `--force`
-  // drops the gate.
-  if (!output && !force) {
-    const untaken = untakenBase(siteDir, client.origin)
-    if (untaken) {
-      error(untaken.headline)
-      for (const line of untaken.lines) note(line)
-      return { exitCode: 1 }
-    }
-  }
   const priorHashes = readSyncCache(siteDir, client.origin)
   // Per-item identity, without which the backend reads every record as new and
   // recreates every page and section row.
@@ -613,6 +624,9 @@ export async function push(args = [], deps = {}) {
     success(
       `Nothing to push — ${skipped} entit${skipped === 1 ? 'y' : 'ies'} unchanged since the last push.`
     )
+    // ⭐ And so the backend holds what this commit sends: it is where the next pull merges
+    // from (`holdUnchangedPush`). Not for a preview, which keeps nothing.
+    if (!output && !dryRun) holdUnchangedPush(siteDir, client.origin)
     return { exitCode: 0 }
   }
   if (siteContent)

package/src/commands/refresh.js

@@ -137,7 +137,7 @@ export async function refresh(args = [], deps = {}) {
     say.info('Pulling from the git remote…')
     const r = pullRemote(siteDir)
     if (!r.ok) {
-      say.err('git pull failed — resolve this before continuing.')
+      say.err(r.conflicts ? 'git pull left conflicts — settle them before continuing.' : 'git pull failed — resolve this before continuing.')
       for (const line of r.message.split('\n').slice(0, 6)) say.dim(line)
       // Deliberately stop. Layering the backend's content on top of an unresolved
       // git state gives the user two independent conflicts at once, and no clear

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-17T17:49:32.100Z",
+  "generatedAt": "2026-10-17T22:35:38.030Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.4.0"
+      "version": "1.5.0"
     },
     "@uniweb/build": {
-      "version": "1.3.9"
+      "version": "1.3.10"
     },
     "@uniweb/content-reader": {
       "version": "1.4.0"
@@ -24,7 +24,7 @@
       "version": "1.0.3"
     },
     "@uniweb/kit": {
-      "version": "1.2.4"
+      "version": "1.2.5"
     },
     "@uniweb/loom": {
       "version": "1.1.0"
@@ -42,7 +42,7 @@
       "version": "1.0.1"
     },
     "@uniweb/schemas": {
-      "version": "1.3.1"
+      "version": "1.4.0"
     },
     "@uniweb/scholar": {
       "version": "1.1.0"

package/src/index.js

@@ -74,6 +74,7 @@ import {
 } from './utils/interactive.js'
 import { findWorkspaceRoot } from './utils/workspace.js'
 import { exitWhenDrained } from './utils/exit.js'
+import { isGitRepo } from './utils/git.js'
 
 // Colors for terminal output
 const colors = {
@@ -1327,17 +1328,10 @@ async function main() {
 
   // Initialize git repository
   if (!noGit) {
-    // Skip git init if already inside a git repo (common for monorepos/workspaces)
-    let insideGitRepo = false
-    try {
-      execSync('git rev-parse --is-inside-work-tree', {
-        cwd: projectDir,
-        stdio: 'ignore'
-      })
-      insideGitRepo = true
-    } catch {
-      // Not inside a git repo — proceed with init
-    }
+    // Skip git init if a repository already holds the project (common for
+    // monorepos/workspaces). ⛔ Not one that ignores its folder: that repository can never
+    // hold its history, so the project gets its own (`isGitRepo`, the one rule).
+    const insideGitRepo = isGitRepo(projectDir)
 
     if (insideGitRepo) {
       log(

package/src/utils/git.js

@@ -7,19 +7,25 @@
  * already solves better.
  *
  * DETECTED, NEVER REQUIRED. A project may legitimately have no repo, and — more
- * commonly — may live *inside* a larger one: `uniweb create` already skips
- * `git init` when it finds itself inside a work tree ("common for
- * monorepos/workspaces"), and whole scopes of real projects are versioned by a
- * parent repo rather than being repo roots themselves. So the question is never
- * "is this directory a git root" but "is this path tracked by some repo", which is
- * the question git itself answers. Outside one a pull checks out, asking first; in
- * one it merges (`utils/sync-point.js`).
+ * commonly — may live *inside* a larger one: `uniweb create` skips `git init` when a
+ * repository already holds it ("common for monorepos/workspaces"), and whole scopes of
+ * real projects are versioned by a parent repo rather than being repo roots
+ * themselves. So the question is never "is this directory a git root" but "does a
+ * repository HOLD this path": is it inside a work tree, in a folder that repository
+ * does not ignore. One rule answers it, `repoOf` in `utils/sync-point.js`. Outside
+ * one a pull checks out, asking first; in one it merges.
+ *
+ * ⛔ Until 2026-10-17 this said "is this path tracked by some repo" while the check
+ * was `git rev-parse --is-inside-work-tree` alone. That reads as if a folder the
+ * repository ignores were outside it, and it was not: a harness's ignored scratch
+ * project counted as inside the harness, so `refresh` ran `git pull` on the harness.
  */
 
 import { execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { repoOf } from './sync-point.js'
 
 /**
  * The files and directories `uniweb pull` writes into.
@@ -69,15 +75,12 @@ function git(args, cwd) {
 }
 
 /**
- * Is `dir` inside a git work tree? False when git is absent, when the path isn't
- * tracked, or on any error — the caller treats all three the same way.
+ * Does a repository hold `dir` — is it inside a work tree, in a folder that repository
+ * does not ignore (`repoOf`)? False when git is absent, outside any work tree, in an
+ * ignored folder, or on any error — the caller treats them all the same way.
  */
 export function isGitRepo(dir) {
-  try {
-    return git(['rev-parse', '--is-inside-work-tree'], dir).trim() === 'true'
-  } catch {
-    return false
-  }
+  return Boolean(repoOf(dir))
 }
 
 /** Does this repo have a remote configured to pull from? */
@@ -102,7 +105,7 @@ export function hasRemote(dir) {
  * ⛔ Until 2026-10-17 this was `--ff-only`, which refused once a pull had made a merge
  * commit the remote did not have.
  *
- * @returns {{ ok: boolean, changed: boolean, message: string }}
+ * @returns {{ ok: boolean, conflicts?: boolean, changed: boolean, message: string }}
  */
 export function pullRemote(dir) {
   const before = (() => {
@@ -125,6 +128,23 @@ export function pullRemote(dir) {
         return null
       }
     })()
+    // ⛔ `--autostash` exits 0 when the uncommitted work it set aside cannot be put back over
+    // what the pull brought: the files hold conflict markers and git keeps that work in the
+    // stash as well. That is not a clean pull — refresh must stop before the backend's
+    // content lands on top of it. *(Read as clean until 2026-10-17.)*
+    const unmerged = git(['diff', '--name-only', '--diff-filter=U'], dir).trim()
+    if (unmerged) {
+      return {
+        ok: false,
+        conflicts: true,
+        changed: Boolean(before && after && before !== after),
+        message: [
+          'Your uncommitted changes overlap the commits git pull brought.',
+          'Settle the markers and `git add` each file, then `git stash drop` — git kept those changes in the stash as well:',
+          ...unmerged.split('\n').map((p) => `  ${p}`)
+        ].join('\n')
+      }
+    }
     return {
       ok: true,
       changed: Boolean(before && after && before !== after),

package/src/utils/sync-point.js

@@ -10,13 +10,18 @@
  * A sync point is one of:
  *   · a commit a PULL made — the backend's content written onto the last sync point's
  *     tree, marked by the trailers below, and merged into the branch, so it is shared;
- *   · the commit a PUSH was made from — what the backend then holds. This copy keeps it
- *     (`backend-cache.json`, `syncPoint`), and the backend can name it on a pull
- *     (`x-uniweb-source`, `backend/client.js`), for every copy that has it.
+ *   · the commit a PUSH was made from — what the backend then holds — or one a push found
+ *     nothing to send from. This copy keeps it (`backend-cache.json`, `syncPoint`), and the
+ *     backend can name it on a pull (`x-uniweb-source`, `backend/client.js`), for every
+ *     copy that has it.
  *
- * ⚖️ Any sync point a history holds is a safe base: both the files and the backend's
- * content descend from it, so neither side's change can read as the other's undoing. The
- * newest one is the precise base — an older one costs conflicts, never content.
+ * ⚖️ THE NEWEST ONE IS THE BASE; an older one is not simply less precise. Both the files and
+ * the backend's content descend from any of them, but between an older one and the
+ * newest, both sides hold the same changes — and where one side then changed a hunk back,
+ * the older base already reads the old text, so the change-back looks like no change and
+ * the merge silently takes the other side. ⛔ Until 2026-10-17 this said "an older one
+ * costs conflicts, never content". So no known base is dropped (`madeOnto`), and the
+ * backend naming its source is a matter of correctness, not only of fewer conflicts.
  *
  * ⛔ Until 2026-10-17 the ancestor was a per-machine list of the files this copy's last pull
  * wrote, by hash, found again in history by content — and HEAD where the list had no
@@ -69,8 +74,18 @@ export function gitError(err) {
 }
 
 /**
- * The repository a site is in — its top level, the site's path in it, the git
- * directory and HEAD (null on a branch with no commits) — or null outside one.
+ * The repository that holds a site — its top level, the site's path in it, the git
+ * directory and HEAD (null on a branch with no commits) — or null when none does.
+ *
+ * ⭐ HOLDS: the site's folder is inside a work tree, and that repository does not ignore
+ * it. A repository can never hold the history of a folder it ignores — a harness's
+ * scratch projects, a sandbox — so a site there is outside git, as if no repository were
+ * around it. One committed there anyway (`git add -f`) is held: git does not count a
+ * folder with tracked content as ignored.
+ *
+ * ⛔ Until 2026-10-17 any enclosing work tree counted. In a folder it ignores, a pull
+ * failed on git's "paths are ignored", a push recorded that repository's HEAD as its sync
+ * point, and `refresh` ran `git pull` on it.
  */
 export function repoOf(siteDir) {
   let top, prefix, gitDir
@@ -82,6 +97,7 @@ export function repoOf(siteDir) {
     return null
   }
   if (!top) return null
+  if (prefix && ignoredHere(siteDir)) return null
   let head = null
   try {
     head = gitText(top, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']).trim() || null
@@ -91,6 +107,16 @@ export function repoOf(siteDir) {
   return { top, prefix, path: prefix ? prefix.replace(/\/$/, '') : '.', gitDir, head }
 }
 
+/** Does the repository around `dir` ignore it? `git check-ignore` exits 0 for yes, 1 for no. */
+function ignoredHere(dir) {
+  try {
+    git(dir, ['check-ignore', '-q', '.'])
+    return true
+  } catch {
+    return false
+  }
+}
+
 /** Is `ancestor` in the history of `of` — or `of` itself? */
 export function isAncestor(repo, ancestor, of = 'HEAD') {
   try {
@@ -120,6 +146,15 @@ export function siteTreeIn(repo, rev) {
   }
 }
 
+/** The paths in conflict here, whatever left them — a merge, or a stash put back over one. */
+export function unmergedPaths(repo) {
+  try {
+    return zlist(git(repo.top, ['diff', '--name-only', '-z', '--diff-filter=U']))
+  } catch {
+    return []
+  }
+}
+
 /** Is a merge waiting for its commit here? */
 export function mergeInProgress(repo) {
   try {
@@ -171,17 +206,64 @@ export function historySyncPoint(repo, { origin, siteUuid }) {
   for (const record of out.split('\x1e')) {
     const [sha = '', body = ''] = record.replace(/^\s+/, '').split('\x1f')
     if (!/^[0-9a-f]{40,64}$/.test(sha)) continue
-    const t = trailersOf(body)
-    if (t.origin !== origin || t.siteUuid !== siteUuid || t.path !== repo.path) continue
-    if (siteTreeIn(repo, sha) === t.tree) return sha
+    if (marks(repo, sha, body, { origin, siteUuid })) return sha
   }
   return null
 }
 
+// Does this commit's message mark it a sync point of this site and backend — and does it
+// still hold the site tree its trailer names?
+function marks(repo, sha, body, { origin, siteUuid }) {
+  const t = trailersOf(body)
+  if (t.origin !== origin || t.siteUuid !== siteUuid || t.path !== repo.path) return false
+  return siteTreeIn(repo, sha) === t.tree
+}
+
+/**
+ * The commits a sync point HEAD does not hold still vouches for: the one it was made onto
+ * — its first parent — and that one's, for as long as each is a sync point of this site
+ * HEAD does not hold either.
+ *
+ * ⛔ A merge abandoned (`git merge --abort`) leaves this copy's sync point out of the
+ * history, while the commit it was made onto is still there — and still a state the
+ * backend's content descends from. Until 2026-10-17 it was forgotten with the merge, and
+ * the next pull built on an older sync point, or on none: measured against a real
+ * backend, it conflicted on a section nobody had touched since the commit last pushed from.
+ */
+export function madeOnto(repo, sha, { origin, siteUuid }) {
+  const out = []
+  let at = sha
+  for (let n = 0; n < 16 && isCommit(repo, at) && !isAncestor(repo, at); n++) {
+    let body
+    try {
+      body = gitText(repo.top, ['log', '-1', '--format=%B', at])
+    } catch {
+      break
+    }
+    if (!marks(repo, at, body, { origin, siteUuid })) break
+    let parent = null
+    try {
+      parent = gitText(repo.top, ['rev-parse', '--verify', '-q', `${at}^1`]).trim() || null
+    } catch {
+      // Made onto nothing — a history with no sync point.
+    }
+    if (!parent) break
+    out.push(parent)
+    at = parent
+  }
+  return out
+}
+
 /**
  * The base a pull merges from: the newest of the candidates HEAD descends from. One that
- * descends from all the others is the newest; with none, the most recently committed —
- * any of them is a state both sides descend from, so the choice costs precision at worst.
+ * descends from all the others is the newest; with none, the most recently committed.
+ *
+ * ⚖️ Any of them is a state both sides descend from, but only the newest such state — the
+ * commit the backend's content last came from — merges exactly. An older one costs a
+ * conflict wherever one side changed what the other changed after it, and it silently
+ * undoes a change made after it and then changed BACK on one side: the base already
+ * reads the old text, so the change-back looks like no change at all. ⛔ Until
+ * 2026-10-17 this said an older base "costs precision at worst".
  */
 export function newestBase(repo, candidates) {
   const shas = [...new Set(candidates.filter(Boolean))].filter((s) => isCommit(repo, s) && isAncestor(repo, s))
@@ -210,12 +292,16 @@ export function newestBase(repo, candidates) {
  * ⛔ CLOSE IT. `close()` unlinks every link it made before removing the rest — a recursive
  * remove that followed one would delete the project's own files.
  *
+ * ⚖️ What is written under the roots where the repository ignores it — media in a folder
+ * kept out of git — is in no commit, so no merge brings it. `placeIgnored()` copies it
+ * into the project, where the project lacks it.
+ *
  * @param {object} repo - `repoOf`
  * @param {object} opts
  * @param {string[]} opts.roots - the site's content roots, relative to the site
  * @param {string|null} opts.rev - the commit whose content the roots are filled from;
  *   null for none
- * @returns {{ siteDir: string, commit: Function, close: Function }}
+ * @returns {{ siteDir: string, commit: Function, placeIgnored: Function, close: Function }}
  */
 export function openStandIn(repo, { roots, rev }) {
   for (const r of roots) {
@@ -329,7 +415,7 @@ export function openStandIn(repo, { roots, rev }) {
      * @returns {{ commit: string|null, tree: string, siteTree: string|null }}
      */
     const commit = ({ parent, subject, origin, siteUuid, always = false }) => {
-      const staged = full.filter((f) => present.includes(f) || existsSync(join(root, f)))
+      const staged = held(full.filter((f) => present.includes(f) || existsSync(join(root, f))))
       if (staged.length) at(['add', '-A', '--', ...staged])
       const tree = at(['write-tree']).toString('utf8').trim()
       const before = rev ? gitText(repo.top, ['rev-parse', `${rev}^{tree}`]).trim() : null
@@ -356,7 +442,40 @@ export function openStandIn(repo, { roots, rev }) {
       return { commit: sha, tree, siteTree }
     }
 
-    return { siteDir, commit, close }
+    /**
+     * Copy into the project what the stand-in holds under the roots where the repository
+     * ignores it, wherever the project lacks it. ⛔ Never over a file the project has:
+     * with no history there, nothing tells its version from the author's work.
+     * @returns {string[]} the paths placed, relative to the site
+     */
+    const placeIgnored = () => {
+      const roots = full.filter((f) => existsSync(join(root, f)))
+      if (!roots.length) return []
+      const placed = []
+      for (const p of zlist(at(['ls-files', '--others', '--ignored', '--exclude-standard', '-z', '--', ...roots]))) {
+        const to = join(repo.top, p)
+        if (occupied(to)) continue
+        mkdirSync(dirname(to), { recursive: true })
+        copyFileSync(join(root, p), to)
+        placed.push(sitePrefix && p.startsWith(sitePrefix) ? p.slice(sitePrefix.length) : p)
+      }
+      return placed
+    }
+
+    // The roots git can hold here. ⛔ One the repository ignores whole is not named to
+    // `git add`, which refuses an ignored path; what is written under it is placed instead.
+    const held = (paths) => {
+      if (!paths.length) return paths
+      let ignored = []
+      try {
+        ignored = zlist(at(['check-ignore', '-z', '--stdin'], { input: `${paths.join('\0')}\0` }))
+      } catch (err) {
+        if (err?.status !== 1) throw err // 1: none of them is ignored
+      }
+      return paths.filter((p) => !ignored.includes(p))
+    }
+
+    return { siteDir, commit, placeIgnored, close }
   } catch (err) {
     close()
     throw err
@@ -366,6 +485,15 @@ export function openStandIn(repo, { roots, rev }) {
 // ── merging ─────────────────────────────────────────────────────────────────
 
 const zlist = (buf) => buf.toString('utf8').split('\0').filter(Boolean)
+// Something is at `path` — a dangling link included, which `existsSync` reads as nothing.
+const occupied = (path) => {
+  try {
+    lstatSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
 
 /**
  * Files not under git that the merge would write over: their paths, each with whether the
@@ -404,6 +532,9 @@ function untrackedInTheWay(repo, commit) {
  */
 export function mergeSyncPoint(repo, commit, { message }) {
   if (mergeInProgress(repo)) return { ok: false, reason: 'merge-in-progress' }
+  // Conflicts already here are not this merge's: git would refuse it, and they would read as its own.
+  const unsettled = unmergedPaths(repo)
+  if (unsettled.length) return { ok: false, reason: 'unmerged', paths: unsettled }
   const inTheWay = untrackedInTheWay(repo, commit)
   const blocking = inTheWay.filter((u) => !u.same).map((u) => u.path)
   if (blocking.length) return { ok: false, reason: 'untracked', paths: blocking }
@@ -412,7 +543,13 @@ export function mergeSyncPoint(repo, commit, { message }) {
   for (const u of inTheWay) rmSync(join(repo.top, u.path))
   try {
     git(repo.top, ['merge', '--autostash', '--no-edit', '--no-verify', '--allow-unrelated-histories', '-m', message, commit])
-    return { ok: true, conflicted: [] }
+    // ⛔ THE MERGE IS MADE, AND IT MAY STILL HAVE LEFT CONFLICTS. `--autostash` exits 0 when
+    // the uncommitted work it set aside cannot be put back over what the merge brought: the
+    // files then hold conflict markers, unmerged, and git keeps that work in the stash too.
+    // Until 2026-10-17 that read as a clean merge — a pull that exited 0 over the markers,
+    // so `uniweb pull && uniweb push` would send them.
+    const unstashed = unmergedPaths(repo)
+    return { ok: true, conflicted: unstashed, stashKept: unstashed.length > 0 }
   } catch (err) {
     const conflicted = zlist(git(repo.top, ['diff', '--name-only', '-z', '--diff-filter=U']))
     if (conflicted.length) return { ok: true, conflicted }
@@ -444,26 +581,70 @@ export function takeSyncPoint(repo, commit, { roots, message }) {
   }
 }
 
-/** What the backend changed between two commits, under the site: `[status, path]` pairs. */
-export function changesBetween(repo, from, to) {
+/**
+ * What a pull changed in the files, under the site: `[status, path]` pairs — what the
+ * merge, or the take, moved from `from` (HEAD before it), less what the files already
+ * held as it left them. `files` is the files before it (`snapshotFiles`). `staged` reads a
+ * merge stopped on conflicts from the index; `skip` leaves out the paths in conflict,
+ * which are reported as conflicts.
+ *
+ * ⛔ Until 2026-10-17 a pull listed the backend's content against the base, as "changes
+ * from the backend": a file a push had already written into the files read as one, so
+ * did a person's own edit when there was no base — and `--force` said it "took" a change
+ * where it undid their edit.
+ */
+export function changedInFiles(repo, { from, files, staged = false, skip = [] }) {
+  const scope = ['--', ...(repo.prefix ? [repo.prefix] : [])]
   try {
-    // No base: against the empty tree, in this repository's own hash.
-    const base = from || gitText(repo.top, ['hash-object', '-t', 'tree', '--stdin'], { input: '' }).trim()
-    const out = gitText(repo.top, ['diff', '--name-status', '-z', base, to, '--', ...(repo.prefix ? [repo.prefix] : [])])
-    const parts = out.split('\0').filter(Boolean)
-    const changes = []
+    const parts = zlist(git(repo.top, ['diff', '--name-status', '-z', ...(staged ? ['--cached', from] : [from, 'HEAD']), ...scope]))
+    const moved = []
     for (let i = 0; i < parts.length; ) {
       const status = parts[i++]
       const path = parts[i++]
-      if (/^[RC]/.test(status)) changes.push([status[0], parts[i++]])
-      else changes.push([status, path])
+      moved.push(/^[RC]/.test(status) ? [status[0], parts[i++]] : [status, path])
     }
-    return changes.map(([s, p]) => [s, repo.prefix && p.startsWith(repo.prefix) ? p.slice(repo.prefix.length) : p])
+    // What the files already held as the merge left it is no change to them.
+    const differs = new Set(
+      zlist(git(repo.top, ['diff', '--name-only', '-z', '--no-renames', ...(staged ? ['--cached', files] : [files, 'HEAD']), ...scope]))
+    )
+    return moved
+      .filter(([s, p]) => s !== 'U' && !skip.includes(p) && differs.has(p))
+      .map(([s, p]) => [s, repo.prefix && p.startsWith(repo.prefix) ? p.slice(repo.prefix.length) : p])
   } catch {
     return []
   }
 }
 
+/**
+ * The files as they are, as a commit to compare against — what is tracked, committed or
+ * not (`git stash create`, which touches neither the files nor any ref); HEAD when nothing
+ * is uncommitted.
+ */
+export function snapshotFiles(repo) {
+  try {
+    return (
+      gitText(repo.top, ['stash', 'create'], {
+        env: { GIT_AUTHOR_NAME: 'uniweb', GIT_AUTHOR_EMAIL: 'sync@uniweb', GIT_COMMITTER_NAME: 'uniweb', GIT_COMMITTER_EMAIL: 'sync@uniweb' }
+      }).trim() || repo.head
+    )
+  } catch {
+    return repo.head
+  }
+}
+
+/**
+ * Does HEAD hold the site's content as the files do — nothing staged, changed or untracked
+ * under the roots? (What the repository ignores is no change.)
+ */
+export function contentCommitted(repo, roots) {
+  try {
+    const full = roots.map((r) => `${repo.prefix}${r}`)
+    return git(repo.top, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...full]).length === 0
+  } catch {
+    return false
+  }
+}
+
 // ── this copy's own sync point ──────────────────────────────────────────────
 
 const cachePath = (siteDir) => join(siteDir, '.uniweb', 'backend-cache.json')