uniweb 1.20.4 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.20.4",
+  "version": "1.21.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {

package/partials/agents.md

@@ -33,15 +33,18 @@ You're building a *system* of section types, not individual pages. That's what m
 | Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
 | Porting a design from React / Next / a generated site | **Part 1**, then Part 5 → *Migrating* |
 
-### Three commands that replace guessing
+### Four commands that replace guessing
 
 ```bash
+uniweb status                # what changed in the app, in git and in Uniweb — and what to run
 uniweb inspect <path>        # print the parsed content shape of a section or page
 uniweb <command> --help      # exact flags, always current — no side effects
 uniweb doctor                # diagnose project configuration (--fix to repair)
 ```
 
-`uniweb inspect` is the important one. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+`uniweb inspect` is the important one for content. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+
+`uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, before you push, and after a command refuses: it changes nothing, and ends with the commands to run, in order (`--json` for a script).
 
 ### The four silent failures
 
@@ -189,6 +192,8 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 
 ### 1. Orient — what kind of workspace is this?
 
+**Run `uniweb status` first.** It says whether the site changed in the app since this copy last synced, whether git or Uniweb has something newer, and what to run about each — before you edit something someone else just changed.
+
 **There is no single layout. Read `pnpm-workspace.yaml` first** — its `packages:` globs name the shape in one glance:
 
 | Globs | Layout | What it implies |
@@ -2818,7 +2823,8 @@ uniweb publish                    # Ship to Uniweb hosting, foundation included
 uniweb add ci --target foundation # Publish a foundation for free at permanent versioned URLs
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
-uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb status                         # What changed in the app, in git and in Uniweb — and what to run
+uniweb push / pull / clone            # Git-style content sync with the Uniweb backend
 uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
 uniweb login --org @acme              # The workspace you work in — new sites are created there (see below)
 uniweb register [--scope @scope]      # Register a foundation + its data schemas to the registry
@@ -2830,7 +2836,7 @@ uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whol
 uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
 uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 
-uniweb -v                         # Installed CLI version — and whether a newer one exists
+uniweb -v                         # CLI version — only a global install also says whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
 uniweb validate                   # Check file-based data against declared schemas (fails on a violation; --lax)
 npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
@@ -2896,6 +2902,8 @@ 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.
 
+**Working on a site others edit — run `uniweb status` when you begin, before you push, and after any refusal.** It reads the backend without taking anything: what changed there since this copy last synced, file by file; what you hold that it lacks; whether the site is live; who has it open in the app right now, and on which file. Then it lists the commands to run, in an order that works from the top — `uniweb pull` before the push it would otherwise refuse. Three habits go with it: take what changed (`pull`, or `refresh`) before you edit; never `--force` past a refusal; and when someone has a page open in the app, tell the person before you change that page. A step marked *ask the person first* — going live, which may cost money — is theirs to decide.
+
 **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. **In a git repository a push sends what you have committed:** with the site's content not committed it is refused before anything is sent, naming the files — commit them, or run `uniweb push --commit -m "…"` (it commits the site's content only, and leaves anything else staged as it is); `publish` and `sync` take `--commit` too. That commit is where the next pull merges from, which is how the pull tells your changes from the backend's. What the push writes back into the files — the ids the backend assigned — it commits itself, as `uniweb`. When the backend has nothing new, a pull says so and lists the files where yours hold changes it lacks. `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`. In a git repository the push commits 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.
@@ -2942,12 +2950,15 @@ Either side can publish. Nothing about this changes how you build: the same foun
 ### Staying current
 
 ```bash
-uniweb -v                  # installed CLI version, and whether a newer one is available
+uniweb status              # among its checks: whether a newer Uniweb is out than this project runs
+uniweb -v                  # CLI version — only a global install also says whether a newer one exists
 uniweb doctor              # report drift in this project, changing nothing
 npx uniweb@latest update --dry-run   # preview exactly what update would change
 npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
 ```
 
+When `status` names a newer release, take it: `npx uniweb@latest update`, then build and look at the pages. Releases rarely ask anything of a project.
+
 **`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
 
 **What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so build and check the project before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.

package/partials/start.md

@@ -60,6 +60,19 @@ which parts your task needs.
 
 Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
 wrong. AGENTS.md says how to check.
+{{#if project}}
+
+## Check what changed
+
+```bash
+npx uniweb status
+```
+
+The site may have been edited in the Uniweb app since this copy last synced, by the
+person or someone they work with, and Uniweb may have a newer release. `status` says so,
+changes nothing, and ends with the commands to run, in order. A step it marks "ask the
+person first" is theirs to decide.
+{{/if}}
 
 ## Install and run
 
@@ -103,6 +116,10 @@ If the site needs paying for, `publish` prints an address instead of going live.
 it for the person, tell them it's where they pay, and run `publish` again once they're
 done.
 
+Once the site is in the app, it can be edited there at any time. Before you change it
+again, and before each push, run `npx uniweb status`: it says what changed in the app
+since your last push or pull, and what to run.
+
 ## More
 
 - Documentation index: https://uniweb.io/llms.txt

package/src/backend/app-changes.js

@@ -0,0 +1,153 @@
+/**
+ * What changed on the backend since this copy last synced — READ, never taken.
+ *
+ * `uniweb pull` takes the backend's content; `uniweb status` asks what there is to take.
+ * The two must agree on what "changed" means, so this reads the backend as a pull does —
+ * the same two lanes, the same conditional GET (`etagsHold`) — and compares the answer
+ * with what this copy recorded at its last sync, each in the backend's own representation:
+ *
+ *   - the site-content entity's version against `baseVersions`: nothing moved, said
+ *     precisely;
+ *   - each unit's hash against `unitBases.remote`, which a pull and a push both bank from
+ *     the backend's own copy: which files moved. A unit's hash is only ever compared with a
+ *     base in its own representation (`@uniweb/build`'s `site-diff.js`);
+ *   - each record's version against `baseVersions`: which records moved.
+ *
+ * Whoever made the change — an author in the app, or a push from another copy — it is the
+ * backend's content this copy does not hold yet.
+ *
+ * ⛔ IT TAKES NOTHING. An ETag, a version or a hash banked here would say this copy holds
+ * content it never took, and the next pull would hear 304 and never catch up — the failure
+ * `pull.js` records beside `PULL_CACHE_VERSION`. Nothing here writes a file.
+ */
+
+import { computeUnitHashes, documentSchema, indexFolder, readBackendState } from '@uniweb/build/uwx'
+import {
+  etagsHold,
+  readPullCache,
+  readPullDocuments,
+  readPullVersions,
+  splitRecordsPull
+} from '../commands/pull.js'
+import { readBaseVersions, readUnitBases } from './site-sync.js'
+
+/**
+ * @param {object} p
+ * @param {import('./client.js').BackendClient} p.client - signed in; never prompts here
+ * @param {string} p.siteDir
+ * @param {string} p.siteUuid - the site's uuid on `client.origin` (sync.json)
+ * @returns {Promise<{ content: object, records: object }>} each lane's account:
+ *   `state` — `unchanged`, `changed` or `unknown` (with `detail`) — and what moved:
+ *   content `changed` / `added` / `removed` unit paths and `outsideUnits` (the site's
+ *   settings, services or queries moved, and no page did); records `changed` / `added`
+ *   labels (`<schema>/<slug>`), a `removed` count and `folder` (the records' sub-folders).
+ */
+export async function readAppChanges({ client, siteDir, siteUuid }) {
+  const etags = etagsHold(siteDir, client.origin) ? readPullCache(siteDir) : {}
+  const bases = readBaseVersions(siteDir, client.origin)
+  const [content, folder] = await Promise.all([
+    readLane(() => client.pullSiteContent(siteUuid, { etag: etags.content })),
+    readLane(() => client.pullFolder(siteUuid, { etag: etags.folder }))
+  ])
+  return {
+    content: contentChanges(content, { siteDir, origin: client.origin, siteUuid, bases }),
+    records: recordChanges(folder, { siteDir, origin: client.origin, bases })
+  }
+}
+
+async function readLane(request) {
+  let res
+  try {
+    res = await request()
+  } catch (err) {
+    return { error: err }
+  }
+  if (res.status === 304) return { notModified: true }
+  if (!res.ok) return { status: res.status }
+  try {
+    const buf = Buffer.from(await res.arrayBuffer())
+    return { docs: readPullDocuments(buf), versions: readPullVersions(buf) }
+  } catch (err) {
+    return { error: err }
+  }
+}
+
+function laneDetail(lane) {
+  if (lane.error) return lane.error.message || String(lane.error)
+  if (lane.status === 404) return 'the backend has no such site, or you lack access to it'
+  return `the backend answered HTTP ${lane.status}`
+}
+
+/** The content lane against this copy's last sync — see the header. */
+export function contentChanges(lane, { siteDir, origin, siteUuid, bases }) {
+  const none = { changed: [], added: [], removed: [], outsideUnits: false }
+  if (lane.notModified) return { state: 'unchanged', ...none }
+  if (!lane.docs) return { state: 'unknown', ...none, detail: laneDetail(lane) }
+  const doc = lane.docs.find((d) => d?.info || documentSchema(d)) || lane.docs[0] || null
+  if (!doc) return { state: 'unknown', ...none, detail: 'the backend sent no site content' }
+
+  const now = lane.versions?.[siteUuid]
+  const then = bases[siteUuid]
+  if (now && then && now === then) return { state: 'unchanged', ...none }
+
+  const base = readUnitBases(siteDir, origin).remote
+  if (!Object.keys(base).length) {
+    return { state: 'unknown', ...none, detail: "this copy holds no record of the backend's content at its last sync" }
+  }
+  const hashes = computeUnitHashes(doc)
+  const changed = []
+  const added = []
+  for (const [path, hash] of Object.entries(hashes)) {
+    if (!(path in base)) added.push(path)
+    else if (base[path] !== hash) changed.push(path)
+  }
+  const removed = Object.keys(base).filter((path) => !(path in hashes))
+  const units = changed.length + added.length + removed.length
+  // The entity moved and no unit did: what moved is outside the pages — the site's
+  // settings, its services, its queries.
+  const outsideUnits = !units && Boolean(now && then)
+  return {
+    state: units || outsideUnits ? 'changed' : 'unchanged',
+    changed: changed.sort(),
+    added: added.sort(),
+    removed: removed.sort(),
+    outsideUnits
+  }
+}
+
+// `@acme/article` → `article`: how a record's folder under `records/` is named.
+const shortSchema = (schema) => (typeof schema === 'string' ? schema.replace(/^@[^/]+\//, '') : null)
+
+/** The folder lane against this copy's last sync — see the header. */
+export function recordChanges(lane, { siteDir, origin, bases }) {
+  const none = { changed: [], added: [], removed: 0, folder: false }
+  if (lane.notModified) return { state: 'unchanged', ...none }
+  if (!lane.docs) return { state: 'unknown', ...none, detail: laneDetail(lane) }
+  const { folderDoc, recordDocs } = splitRecordsPull(lane.docs)
+  // The records this copy synced, by the backend's uuid (sync.json's `records`: own id → theirs).
+  const known = new Set(Object.values(readBackendState(siteDir, origin).records || {}))
+  if (!known.size && !recordDocs.length) return { state: 'unchanged', ...none }
+
+  const index = indexFolder(folderDoc)
+  const label = (doc) => {
+    const slug = index.get(doc.$uuid)?.slug ?? (typeof doc.$id === 'string' ? doc.$id.split('/').pop() : null)
+    const schema = shortSchema(documentSchema(doc))
+    return slug ? (schema ? `${schema}/${slug}` : slug) : doc.$uuid
+  }
+  const versions = lane.versions || {}
+  const changed = []
+  const added = []
+  const seen = new Set()
+  for (const doc of recordDocs) {
+    const uuid = doc?.$uuid
+    if (!uuid) continue
+    seen.add(uuid)
+    if (!known.has(uuid)) added.push(label(doc))
+    else if (bases[uuid] && versions[uuid] && bases[uuid] !== versions[uuid]) changed.push(label(doc))
+  }
+  const removed = [...known].filter((uuid) => !seen.has(uuid)).length
+  const folderUuid = folderDoc?.$uuid
+  const folder = Boolean(folderUuid && bases[folderUuid] && versions[folderUuid] && bases[folderUuid] !== versions[folderUuid])
+  const moved = changed.length || added.length || removed || folder
+  return { state: moved ? 'changed' : 'unchanged', changed: changed.sort(), added: added.sort(), removed, folder }
+}

package/src/backend/client.js

@@ -948,7 +948,7 @@ export class BackendClient {
    *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
    * `draft_dirty` = never-published, or the synced draft changed since the last
    * publish ("pushed but not published"). Since 2026-10-13 it also carries `editors`:
-   * who has the site open in the app right now, and on what — `status --remote` shows
+   * who has the site open in the app right now, and on what — `uniweb status` shows
    * it (`describeEditors`, commands/status.js).
    *
    * ⭐ **The backend also serves a LIVE-SITE record here, and nothing in this CLI reads
@@ -974,14 +974,14 @@ export class BackendClient {
    * The path is VERB-FIRST (`status/{uuid}`)
    * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
    * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
-   * 404 (unknown/not-yours) / 401 / any failure — `status --remote` degrades to local.
+   * 404 (unknown/not-yours) / 401 / any failure — `uniweb status` says what it could not tell.
    * @param {string} uuid - the site-content uuid
    * @returns {Promise<object|null>}
    */
   /**
    * Whether the backend holds the site `uuid` names — `live`, `gone` or `unknown`, kept
    * apart — for a script that must decide, before any push, whether a binding still
-   * points at a site (`uniweb status --remote --json`, `remote.site_state`).
+   * points at a site (`uniweb status --json`, its `app.site` check).
    *
    * ⛔ `gone` ONLY ON THE BACKEND'S OWN WORD ABOUT THIS SITE: a `404` whose problem names
    * it — `kind: "site"`, `key: <uuid>`. A push from an unbound copy CREATES a site, so a

package/src/backend/foundation-bring-along.js

@@ -34,7 +34,7 @@
  * no local state, multi-machine-safe. When the site references a published
  * registry ref or a URL there's nothing to bring along. When the backend
  * doesn't expose the stored digest yet, the compare DEGRADES to "ask" (same
- * posture as `status --remote` on a 404).
+ * posture as `uniweb status` on a 404).
  *
  * "Release" here is literally `uniweb register` run in the foundation directory
  * — same build-if-stale → schema submit → code upload → digest the standalone

package/src/commands/doctor.js

@@ -62,11 +62,16 @@ const colors = {
   blue: '\x1b[36m'
 }
 
-const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
-const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
-const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
-const info = (msg) => console.log(`${colors.blue}→${colors.reset} ${msg}`)
-const log = console.log
+// Where the report goes: the terminal — whatever `console.log` is when a line is printed —
+// or nowhere while another command reads the findings (`doctor(args, { quiet: true })`,
+// `uniweb status`).
+const toConsole = (...args) => console.log(...args)
+let print = toConsole
+const success = (msg) => print(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => print(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => print(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => print(`${colors.blue}→${colors.reset} ${msg}`)
+const log = (...args) => print(...args)
 
 /**
  * Check if a directory is a site
@@ -1196,7 +1201,24 @@ export function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, sho
 /**
  * Main doctor command
  */
-export async function doctor(args = []) {
+/**
+ * @param {string[]} [args]
+ * @param {{ quiet?: boolean }} [opts] - `quiet`: print nothing, for a command that reads the
+ *   findings (`uniweb status`). Without `--fix` doctor writes nothing, so a quiet run is a
+ *   read.
+ * @returns {Promise<{ issues: object[], errors: number, warnings: number, fixed: number }>}
+ */
+export async function doctor(args = [], { quiet = false } = {}) {
+  const before = print
+  print = quiet ? () => {} : toConsole
+  try {
+    return await runDoctor(args)
+  } finally {
+    print = before
+  }
+}
+
+async function runDoctor(args = []) {
   log('')
   log(`${colors.blue}${colors.bright}Uniweb Doctor${colors.reset}`)
   log(`${colors.dim}Checking project configuration...${colors.reset}`)
@@ -1212,7 +1234,7 @@ export async function doctor(args = []) {
   // the failure the guess was moved here to avoid. Those checks ask for the id.
   const shouldFixExplicitly = (id) => fixFlag === id
   const fixed = (msg) =>
-    console.log(`  ${colors.green}↳ Fixed:${colors.reset} ${msg}`)
+    print(`  ${colors.green}↳ Fixed:${colors.reset} ${msg}`)
 
   const projectDir = resolve(process.cwd())
 
@@ -1225,7 +1247,14 @@ export async function doctor(args = []) {
     log(
       `${colors.dim}Run this command from your project root or a site/foundation directory.${colors.reset}`
     )
-    process.exit(1)
+    // Returned, not exited, so a command reading the findings gets them; the CLI exits 1 on
+    // an error either way.
+    return {
+      issues: [{ id: 'not-a-workspace', type: 'error', message: 'Not in a Uniweb workspace' }],
+      errors: 1,
+      warnings: 0,
+      fixed: 0
+    }
   }
 
   log('')
@@ -2076,6 +2105,7 @@ export async function doctor(args = []) {
     )
     info(`Run: uniweb update`)
     issues.push({
+      id: 'deps-behind-cli',
       type: 'warn',
       message: `${behindDeps.length} @uniweb/* dep declaration(s) behind CLI v${cliVersion}`
     })
@@ -2093,16 +2123,17 @@ export async function doctor(args = []) {
   if (!existsSync(agentsPath)) {
     warn('AGENTS.md not found')
     info(`Run: uniweb update`)
-    issues.push({ type: 'warn', message: 'AGENTS.md not found' })
+    issues.push({ id: 'agents-md-missing', type: 'warn', message: 'AGENTS.md not found' })
   } else if (!agentsVersion) {
     // No stamp — manually created or pre-stamp version
     warn('AGENTS.md has no version stamp (may be outdated)')
     info(`Run: uniweb update`)
-    issues.push({ type: 'warn', message: 'AGENTS.md has no version stamp' })
+    issues.push({ id: 'agents-md-unstamped', type: 'warn', message: 'AGENTS.md has no version stamp' })
   } else if (agentsVersion !== cliVersion) {
     warn(`AGENTS.md is outdated (v${agentsVersion} → v${cliVersion})`)
     info(`Run: uniweb update`)
     issues.push({
+      id: 'agents-md-outdated',
       type: 'warn',
       message: `AGENTS.md outdated (v${agentsVersion} → v${cliVersion})`
     })

package/src/commands/pull.js

@@ -238,7 +238,7 @@ function pullCachePath(siteDir) {
 // Ignoring those once costs one full pull. (In a repository an ETag is echoed only while
 // the sync point it was banked with is in the history — see `cacheHolds` below.)
 const PULL_CACHE_VERSION = 2
-function readPullCache(siteDir) {
+export function readPullCache(siteDir) {
   try {
     const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
     return obj && typeof obj === 'object' && obj.version >= PULL_CACHE_VERSION ? obj : {}
@@ -246,6 +246,21 @@ function readPullCache(siteDir) {
     return {}
   }
 }
+
+/**
+ * Whether the ETags this copy banked still describe its files — the condition a
+ * conditional GET is sent on. Outside git, always. In a repository, only while HEAD's
+ * history holds the sync point they were banked with: a merge abandoned, a branch reset,
+ * and the backend did not move but the files did.
+ *
+ * One rule for both readers of the lanes — this pull and `uniweb status`, which asks the
+ * same question without taking the answer.
+ */
+export function etagsHold(siteDir, origin, repo = repoOf(siteDir)) {
+  if (!repo) return true
+  const held = readSyncPoint(siteDir, origin)
+  return Boolean(held && isAncestor(repo, held))
+}
 function writePullCache(siteDir, { content, folder }) {
   const p = pullCachePath(siteDir)
   mkdirSync(dirname(p), { recursive: true })
@@ -767,7 +782,7 @@ export async function pull(args = [], deps = {}) {
   // only while the sync point it was banked with is.
   const cache = readPullCache(siteDir)
   const held = repo ? readSyncPoint(siteDir, client.origin) : null
-  const cacheHolds = !repo || Boolean(held && isAncestor(repo, held))
+  const cacheHolds = etagsHold(siteDir, client.origin, repo)
   let etagContent = cache.content
   let etagFolder = cache.folder
 

package/src/commands/register.js

@@ -385,21 +385,6 @@ export async function settleFoundationScope(targetDir, { args, isPreview, flagSc
   return { scope, source }
 }
 
-/**
- * The scope a bare name registers under when `--scope` names none — as `@handle`, or null
- * when none was chosen.
- *
- * ⭐ THE WORKSPACE THIS COMMAND WORKS IN *[Diego, 2026-10-06]* — an organization's handle,
- * or your own for your personal workspace — said, not asked (`scopeOfWorkspace`). A team
- * working in `@acme` registers `@acme/…`, which any of its members can release.
- * ⛔ Until 2026-10-06 the default was your personal scope wherever you worked, so a team's
- * foundation registered as `@jane/…` — releasable by Jane alone, and fixed only by
- * renaming it into a new foundation.
- *
- * When the workspace names no scope — none is chosen, or it is a unit without a handle —
- * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
- * you belong to none, else a pick at a terminal, your personal scope without one.
- */
 /**
  * Refuse a reserved scope wherever it came from, before anything is written or sent —
  * `@uniweb` names the framework's own packages and a system account on every Uniweb
@@ -417,6 +402,21 @@ function refusedReservedScope(scope, lead) {
   return true
 }
 
+/**
+ * The scope a bare name registers under when `--scope` names none — as `@handle`, or null
+ * when none was chosen.
+ *
+ * ⭐ THE WORKSPACE THIS COMMAND WORKS IN *[Diego, 2026-10-06]* — an organization's handle,
+ * or your own for your personal workspace — said, not asked (`scopeOfWorkspace`). A team
+ * working in `@acme` registers `@acme/…`, which any of its members can release.
+ * ⛔ Until 2026-10-06 the default was your personal scope wherever you worked, so a team's
+ * foundation registered as `@jane/…` — releasable by Jane alone, and fixed only by
+ * renaming it into a new foundation.
+ *
+ * When the workspace names no scope — none is chosen, or it is a unit without a handle —
+ * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
+ * you belong to none, else a pick at a terminal, your personal scope without one.
+ */
 async function deriveScopeFromLogin(client, args) {
   const token = await client.token()
   const ws = await resolveWorkspace({ client, args })