uniweb 0.28.1 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.28.1",
+  "version": "0.30.0",
   "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/runtime": "^0.12.9",
-    "@uniweb/kit": "^0.13.3",
-    "@uniweb/core": "^0.11.2",
-    "@uniweb/semantic-parser": "^1.3.0"
+    "@uniweb/kit": "^0.13.5",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/core": "^0.12.0",
+    "@uniweb/runtime": "^0.12.10"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.3.0",
+    "@uniweb/build": "^0.26.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/build": "^0.25.2"
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -2128,8 +2128,12 @@ happened into a journey.
 > or tabs, and **nothing is written to the visitor's device** — no cookie, no
 > local storage. The `visit` key lives in memory and dies with the document, so
 > it identifies one page load rather than a person. A `page_view` carries the
-> path, and — captured once when the page first loads, then replayed on each view
-> — the external referrer and any `utm_*` the visitor arrived with. Nothing else.
+> path; two booleans about the page load — `first_of_load` on the view that
+> opened the document, and `continues` when the load came from one of your own
+> pages; and — captured once when the page first loads, then replayed on each
+> view — the external referrer and any `utm_*` the visitor arrived with. Nothing
+> else. **Both booleans describe the load, never the visitor**, and neither links
+> two loads to each other.
 
 ### ⛔ Use kit. Never touch the `uniweb` global
 

package/src/backend/client.js

@@ -48,16 +48,35 @@ import { uploadSiteAssets } from '../utils/asset-upload.js'
  *
  *   1. `flag` — the raw --backend / --registry value (this command)
  *   2. UNIWEB_REGISTER_URL env — session-wide override (CI / local dev)
- *   3. `siteBackend` — the site's bound backend from deploy.yml (site verbs)
- *   4–6. the logged-in session origin > ~/.uniweb/config.json > the default
+ *   3. `siteScope` — the project's `site.yml::$backend` (site verbs)
+ *   4. `siteBackend` — the site's bound backend from deploy.yml (site verbs)
+ *   5–7. the logged-in session origin > ~/.uniweb/config.json > the default
  *        (uniweb.app) — all via getRegistryApiBaseUrl()
  *
+ * ⭐ **`siteScope` outranks the SESSION, and that is the whole reason it is a tier.** The
+ * session is a machine-wide default; `$backend` is this project's statement about where
+ * its stored identity is meaningful. Without the tier, a teammate who clones a project
+ * bound to a non-default backend resolves to whatever they last logged into, and is then
+ * REFUSED by `assertSiteBackendScope` — nagged instead of routed, on a question the
+ * project already answered.
+ *
+ * ⭐ **And it outranks `siteBackend`, which looks like the same fact and is not.**
+ * `deploy.yml`'s target `backend` records *where this ships*; `$backend` records *whose
+ * namespace the uuid is in*. They agree in the normal case. When they disagree the
+ * identity wins, because resolving to the other one only reaches the guard and stops.
+ *
+ * ⚠️ The explicit overrides stay ON TOP deliberately. `--backend` and the env var are how
+ * you deliberately aim elsewhere — at a staging mirror, say — and a project file must not
+ * be able to veto a flag the user just typed. A wrong aim is then caught by the guard
+ * rather than silently redirected.
+ *
  * @param {string} [flag] - the raw value of --backend / --registry, if supplied
  * @param {object} [opts]
+ * @param {string} [opts.siteScope] - the project's `site.yml::$backend`
  * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend origin
  * @returns {string} a bare origin with no trailing slash
  */
-export function resolveBackendOrigin(flag, { siteBackend } = {}) {
+export function resolveBackendOrigin(flag, { siteScope, siteBackend } = {}) {
   const norm = (v) => {
     try {
       return new URL(v).origin
@@ -74,6 +93,10 @@ export function resolveBackendOrigin(flag, { siteBackend } = {}) {
     const o = norm(env)
     if (o) return o
   }
+  if (siteScope) {
+    const o = norm(siteScope)
+    if (o) return o
+  }
   if (siteBackend) {
     const o = norm(siteBackend)
     if (o) return o
@@ -116,6 +139,7 @@ export class BackendClient {
    * @param {object} [opts]
    * @param {string} [opts.origin] - explicit origin (wins over originFlag/env)
    * @param {string} [opts.originFlag] - raw --backend/--registry value to resolve
+   * @param {string} [opts.siteScope] - the project's `site.yml::$backend` (site verbs)
    * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend (site verbs)
    * @param {string} [opts.token] - explicit bearer (wins over env + stored session)
    * @param {() => Promise<string>} [opts.getToken] - injected bearer resolver (tests, or
@@ -127,6 +151,7 @@ export class BackendClient {
   constructor({
     origin,
     originFlag,
+    siteScope,
     siteBackend,
     token,
     getToken,
@@ -135,7 +160,7 @@ export class BackendClient {
     fetchImpl
   } = {}) {
     this.origin = (
-      origin || resolveBackendOrigin(originFlag, { siteBackend })
+      origin || resolveBackendOrigin(originFlag, { siteScope, siteBackend })
     ).replace(/\/+$/, '')
     this._token = token || process.env.UNIWEB_TOKEN || null
     this._getToken = getToken || null

package/src/backend/site-sync.js

@@ -15,6 +15,7 @@ import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
+import { recordSiteBackend } from '../utils/site-identity.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
@@ -796,6 +797,16 @@ async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note })
     echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
   const org = recordSiteOrg(siteDir, owner)
 
+  // The SYNC SCOPE, recorded here for the same reason `$org` is: this function is the
+  // one place BOTH create paths meet (`ensureSiteExists` for a site with local media,
+  // the content-lane create for one without). Recording it at either call site instead
+  // would make `$backend` present or absent depending on whether the site happens to
+  // have images — the exact drift the comment at the second call site warns about.
+  //
+  // A no-op on the default backend, so the common case writes nothing.
+  const scope = await recordSiteBackend(siteDir, client.origin)
+  if (scope) note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
+
   note?.(
     org
       ? `Created the site on the backend under ${org} (recorded $uuid + $org in site.yml).`
@@ -1088,11 +1099,29 @@ export async function pushSyncPackages({
         // verb that could have removed it — a site is deleted in the Uniweb app,
         // and that is what severs the sync — so the raw 404 leaves the user with
         // no idea that the fix is local and one line.
+        //
+        // ⛔ ORDER THESE TWO CAUSES, and put the RECOVERABLE one first. Until 2026-08-24
+        // this branch named only the deletion and went straight to "clear `$uuid`" — and
+        // that advice, followed for the OTHER cause, destroys a live binding: the site is
+        // fine, you are simply pointed at the wrong backend, and clearing the uuid orphans
+        // it. `assertSiteBackendScope` now catches most of that before any request goes
+        // out, so reaching here usually does mean a deletion; "usually" is not "always"
+        // (a project predating `$backend` records no scope to check), which is why the
+        // cheap cause is still named before the destructive fix.
+        note(
+          `The backend at ${client.origin} has no site with uuid ${boundUuid}.`
+        )
+        note(
+          'Two causes. Check the cheap one first: is this the backend the site lives on?'
+        )
+        note(
+          `  wrong backend  →  uniweb login --backend <the right one>   (nothing is lost)`
+        )
         note(
-          `The backend has no site with uuid ${boundUuid} — the usual cause is that it was deleted in the Uniweb app.`
+          `  deleted in the app  →  clearing \`$uuid\` from site.yml re-publishes it as a NEW site`
         )
         note(
-          'Deleting this folder removes only your local copy; clearing `$uuid` from site.yml re-publishes it as a new site.'
+          'Deleting this folder removes only your local copy, either way.'
         )
       } else if (res.status === 409) {
         // The site's @uniweb/folder is genesis-owned: its structure is fixed on first

package/src/commands/clone.js

@@ -59,6 +59,7 @@ 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 { recordSiteBackend } from '../utils/site-identity.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -335,9 +336,17 @@ export async function clone(args = [], deps = {}) {
   // same uuid (the backend resolves the site's @uniweb/folder from it), so there is no
   // separate folder uuid to seed.
   seedYamlUuid(join(siteDir, 'site.yml'), siteUuid)
+  // …and the SYNC SCOPE that makes it meaningful. `clone` is the sharpest case for it:
+  // the uuid comes from whoever we read, and until now nothing on disk recorded that —
+  // so a teammate who cloned this project and ran `uniweb pull` while logged in
+  // elsewhere sent this backend's uuid to a different one. A no-op on the default
+  // backend. (The two CREATE paths record it via `recordAndDescribeOwner`; clone seeds
+  // an existing site and never reaches them, which is why it is written here too.)
+  const scope = await recordSiteBackend(siteDir, client.origin)
   success(
     `Scaffolded the site harness${foundationRef ? ` (foundation: ${foundationRef})` : ''}.`
   )
+  if (scope) note(`Bound to ${scope} (recorded $backend in site.yml).`)
 
   // 5. Install, then delegate the projection to the project-local `uniweb pull`.
   const pm = detectWorkspacePm(projectDir) || 'pnpm'

package/src/commands/publish.js

@@ -65,6 +65,10 @@ import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { readFlagValue, readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import {
+  assertSiteBackendScope,
+  readSiteIdentity
+} from '../utils/site-identity.js'
 import { isNonInteractive, confirm } from '../utils/interactive.js'
 import { headProvenance } from '../utils/git.js'
 import {
@@ -180,17 +184,33 @@ export async function publish(args = []) {
   const siteYml = readSiteYml(join(siteDir, 'site.yml'))
   // The site's deploy.yml-bound backend (where it was published) feeds the
   // resolution ladder below an explicit --backend / UNIWEB_REGISTER_URL.
+  // The project's own statement of where its identity lives. Feeds the origin ladder
+  // ABOVE the session (see resolveBackendOrigin), so a teammate who cloned this project
+  // targets the backend it is bound to instead of whatever they last logged into.
+  // ⛔ The RAW value, never `resolveSiteScope` — null must mean "defer to the next tier".
+  const siteScope = readSiteIdentity(siteDir).backend
   const siteBackend = await resolveSiteBackend(siteDir)
 
   const client = new BackendClient({
     originFlag:
       readFlagValue(args, '--backend') || readFlagValue(args, '--registry'),
+    siteScope,
     siteBackend,
     token: readFlagValue(args, '--token') || undefined,
     args,
     command: 'Publishing'
   })
 
+  // ⛔ SCOPE CHECK — before the foundation bring-along, the sync, or the go-live. A
+  // publish is the longest of these flows and the most expensive to unwind, so it is
+  // the one that most benefits from failing at the first step rather than at the fifth.
+  const scope = assertSiteBackendScope(siteDir, client.origin)
+  if (!scope.ok) {
+    say.err(scope.message)
+    scope.hint.forEach(say.dim)
+    return { exitCode: 1 }
+  }
+
   // WHO will own this site, if this publish is the one that creates it. Resolved
   // up front: `ensureSiteExists` below is the create, and it must not be reached
   // with the question still open. An already-created site resolves to null without

package/src/commands/pull.js

@@ -102,6 +102,10 @@ import {
   resolveSiteBackend
 } from './deploy.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import {
+  assertSiteBackendScope,
+  readSiteIdentity
+} from '../utils/site-identity.js'
 
 const FOLDER_MODEL = '@uniweb/folder'
 
@@ -549,9 +553,15 @@ export async function pull(args = [], deps = {}) {
     const blocked = await checkWorkingTree(siteDir, args)
     if (blocked) return blocked
   }
+  // The project's own statement of where its identity lives. Feeds the origin ladder
+  // ABOVE the session (see resolveBackendOrigin), so a teammate who cloned this project
+  // targets the backend it is bound to instead of whatever they last logged into.
+  // ⛔ The RAW value, never `resolveSiteScope` — null must mean "defer to the next tier".
+  const siteScope = readSiteIdentity(siteDir).backend
   const siteBackend = await resolveSiteBackend(siteDir)
   const client = new BackendClient({
     originFlag: flagValue(args, '--backend') || flagValue(args, '--registry'),
+    siteScope,
     siteBackend,
     token: tokenFlag,
     getToken: deps.getToken,
@@ -559,6 +569,17 @@ export async function pull(args = [], deps = {}) {
     args,
     command: 'Pulling'
   })
+
+  // ⛔ SCOPE CHECK — before the lanes read. `pull` WRITES the working tree from what it
+  // fetches, so a wrong-backend pull is not merely a failed read: it is the case that
+  // most needs stopping early.
+  const scope = assertSiteBackendScope(siteDir, client.origin)
+  if (!scope.ok) {
+    error(scope.message)
+    scope.hint.forEach(note)
+    return { exitCode: 1 }
+  }
+
   // One identity per site: `site.yml::$uuid`. Both lanes (content + folder) are keyed
   // by it — the backend resolves the site's `@uniweb/folder` from this uuid.
   const siteContentUuid = readYamlUuid(join(siteDir, 'site.yml'))

package/src/commands/push.js

@@ -72,6 +72,10 @@ import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessCollections } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import {
+  assertSiteBackendScope,
+  readSiteIdentity
+} from '../utils/site-identity.js'
 import { confirm } from '../utils/interactive.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
@@ -149,6 +153,11 @@ export async function push(args = [], deps = {}) {
   // Advisory only — warns and pushes. A malformed data block otherwise rides
   // the sync wire unchecked; see utils/conformance.js.
   await warnIfContentDoesNotConform(siteDir, { args })
+  // The project's own statement of where its identity lives. Feeds the origin ladder
+  // ABOVE the session (see resolveBackendOrigin), so a teammate who cloned this project
+  // targets the backend it is bound to instead of whatever they last logged into.
+  // ⛔ The RAW value, never `resolveSiteScope` — null must mean "defer to the next tier".
+  const siteScope = readSiteIdentity(siteDir).backend
   const siteBackend = await resolveSiteBackend(siteDir)
   // One front door. The bearer is resolved lazily on first need (a non-local Model
   // read during the build, or the submit). Offline emit (--dry-run / -o) is fully
@@ -157,12 +166,37 @@ export async function push(args = [], deps = {}) {
   // references a Model the local foundation doesn't define.
   const client = new BackendClient({
     originFlag: flagValue(args, '--backend') || flagValue(args, '--registry'),
+    siteScope,
     siteBackend,
     token: tokenFlag,
     args,
     command: 'Syncing'
   })
 
+  // ⛔ SCOPE CHECK — before anything is sent. A project whose stored identity was minted
+  // by a different backend cannot be pushed here: the uuids, the asset ids and the sync
+  // cache are all foreign at once. Runs after the client so it sees the RESOLVED origin
+  // (flag > env > deploy.yml > session), not the one we guessed.
+  //
+  // ⚠️ NOT for `-o`, which is a LOCAL EMIT and reaches no backend at all. Its output is
+  // built from files on disk; the resolved origin is not an input to it, so a mismatch
+  // cannot make the artifact wrong — and refusing would break an operation this command
+  // deliberately keeps offline (the `!output && !dryRun` guards below are the same rule).
+  // The refusal even says "Sending them elsewhere is refused" over a run that sends
+  // nothing.
+  //
+  // `--dry-run` IS checked, and the asymmetry is the point: a dry run previews a real
+  // push, so when that push would be refused, saying so is the honest preview. Printing
+  // "would update content at <origin>" instead would preview something that cannot happen.
+  if (!output) {
+    const scope = assertSiteBackendScope(siteDir, client.origin)
+    if (!scope.ok) {
+      error(scope.message)
+      scope.hint.forEach(note)
+      return { exitCode: 1 }
+    }
+  }
+
   // WHO will own this site, if this push is the one that creates it. Resolved
   // before any lane runs, because both create paths below consume it and neither
   // should be reached with the question still open. A site that already exists

package/src/commands/status.js

@@ -31,6 +31,7 @@ import { readFlagValue } from '../utils/args.js'
 import { resolveLocalFoundation } from '../backend/foundation-bring-along.js'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import { readSiteIdentity } from '../utils/site-identity.js'
 
 const c = {
   reset: '\x1b[0m',
@@ -109,6 +110,7 @@ export async function status(args = []) {
       const client = new BackendClient({
         originFlag:
           readFlagValue(args, '--backend') || readFlagValue(args, '--registry'),
+        siteScope: readSiteIdentity(siteDir).backend,
         siteBackend: await resolveSiteBackend(siteDir),
         token: readFlagValue(args, '--token') || undefined,
         args,

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-24T14:55:17.484Z",
+  "generatedAt": "2026-08-25T21:53:35.373Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.25.2",
+      "version": "0.26.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -29,7 +29,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.11.2",
+      "version": "0.12.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -37,19 +37,19 @@
       ]
     },
     "@uniweb/frame-bridge": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "path": "framework/frame-bridge",
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.2",
+      "version": "0.4.3",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.13.3",
+      "version": "0.13.5",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -68,7 +68,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.4",
+      "version": "0.3.5",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -76,7 +76,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.12.9",
+      "version": "0.12.10",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.3.0",
+      "version": "1.3.1",
       "path": "framework/semantic-parser",
       "deps": []
     },

package/src/utils/config.js

@@ -105,9 +105,20 @@ export function getRegistryApiBaseUrl() {
       return fromCfg
     }
   }
-  return 'https://uniweb.app'
+  return DEFAULT_BACKEND_ORIGIN
 }
 
+/**
+ * The built-in backend origin — the last tier of the ladder, and the 98% case.
+ *
+ * Exported because `site.yml::$backend` is written ONLY when the backend is NOT this
+ * (`recordSiteBackend`, utils/site-identity.js). That test needs the *built-in* default,
+ * which `getRegistryApiBaseUrl()` cannot give it — that function returns whatever tier
+ * won, so on a machine with a session or a saved config it returns something else
+ * entirely. Two copies of the literal would silently disagree exactly there.
+ */
+export const DEFAULT_BACKEND_ORIGIN = 'https://uniweb.app'
+
 /**
  * Read workspace package globs.
  * Tries pnpm-workspace.yaml first, falls back to package.json workspaces.

package/src/utils/site-identity.js

@@ -0,0 +1,234 @@
+/**
+ * The project's SYNC SCOPE — reading and asserting `site.yml::$backend`.
+ *
+ * A project that has synced holds backend-minted identity on **four** surfaces:
+ *
+ *   · `site.yml::$uuid`               the site-content entity
+ *   · every collection record `$uuid` in its own source file (the pull-side match key)
+ *   · `assets.json`                   local asset path → content-addressed id
+ *   · `.uniweb/sync-cache.json`       item uuids, hashes, base versions
+ *
+ * All four are meaningless against a different backend, and none of them says which
+ * backend it came from. `$backend` is the one fact that scopes all of them — which is
+ * why a mismatch is a **stop**, not a fallback: it does not mean "we guessed the wrong
+ * default", it means the entire stored surface is foreign.
+ *
+ * ⛔ **`$backend` is absent for the default backend, deliberately.** The 98% case keeps a
+ * clean `site.yml`, and an absent value reads as the default — correct both for a project
+ * written before this key existed and for one synced against the default. That inference
+ * is monotone: it is never worse than the pre-`$backend` behaviour, which recorded nothing
+ * at all.
+ *
+ * ⚠️ **Reads `site.yml` only, not the legacy `site.yaml`.** That matches every existing
+ * identity reader AND all three writers (`writeSiteEntityUuid`, `writeSiteOrg`,
+ * `clone.js`'s `seedYamlUuid`), so this module is consistent with what is on disk. It is
+ * also a KNOWN GAP, not an oversight: five other readers do accept `site.yaml`, and
+ * `upsertYamlScalar` creates a file when missing — so on a `site.yaml` project the writers
+ * produce a phantom `site.yml` holding nothing but identity. Closing that is its own change,
+ * and it has to move the readers and the writers together or it makes the split worse.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import { DEFAULT_BACKEND_ORIGIN } from './config.js'
+
+// ⛔ NO STATIC `@uniweb/build` IMPORT IN THIS FILE — it is an OPTIONAL PEER, and this
+// module is reachable from the CLI's startup graph (`index.js` imports `clone` eagerly,
+// and `clone` imports this). A static import here makes `uniweb --version` die with
+// ERR_MODULE_NOT_FOUND on a global install that has no build package:
+//
+//   $ npm i -g uniweb && uniweb --version
+//   Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@uniweb/build'
+//
+// `test/smoke-startup.test.js` catches this structurally — and did, on the commit that
+// introduced this file. The writer below therefore imports lazily, which also keeps the
+// cost off every startup that never writes. Command modules may import build statically;
+// anything a `utils/` leaf pulls in cannot.
+
+/** A bare origin with no trailing slash, or null when unparseable. */
+export function normalizeOrigin(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  try {
+    return new URL(value).origin
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The project's identity trio, read from `site.yml`. Every field is independently
+ * optional — a project may be unsynced (no `uuid`), on the default backend (no
+ * `backend`), or personally owned (no `org`).
+ *
+ * ⚠️ This is NOT yet the single accessor for `$uuid`. Nine other places still read it
+ * directly; they are correct as they stand and were deliberately left alone when the
+ * scope check was centralized here (a per-read accessor was solving a coupling problem
+ * that one guard solves better). Consolidating them is separable cleanup.
+ *
+ * @param {string} siteDir
+ * @returns {{ uuid: string|null, backend: string|null, org: string|null }}
+ */
+export function readSiteIdentity(siteDir) {
+  const path = join(siteDir, 'site.yml')
+  if (!existsSync(path)) return { uuid: null, backend: null, org: null }
+  let y
+  try {
+    y = yaml.load(readFileSync(path, 'utf8'))
+  } catch {
+    // Unreadable or malformed — report "nothing recorded" rather than throwing. Every
+    // caller here is a guard or a default; none of them should be the reason a command
+    // dies, and a malformed site.yml has its own, better error elsewhere.
+    return { uuid: null, backend: null, org: null }
+  }
+  if (!y || typeof y !== 'object') return { uuid: null, backend: null, org: null }
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
+  return {
+    uuid: str(y.$uuid),
+    backend: normalizeOrigin(y.$backend),
+    org: str(y.$org)
+  }
+}
+
+/**
+ * The backend this project is bound to, with the default filled in.
+ *
+ * Use this rather than `readSiteIdentity().backend` wherever an absent value means the
+ * default — which is everywhere except a "was it recorded?" question.
+ *
+ * ⛔ **NOT for the origin ladder.** `resolveBackendOrigin`'s `siteScope` tier must receive
+ * the RAW `readSiteIdentity().backend`, which is null when nothing was recorded. Handing
+ * it this defaulted value would make the tier fire for EVERY project, and since it sits
+ * above the session it would shadow `uniweb login --backend <local>` on any project
+ * without `$backend` — i.e. break local development for the 98% that never record one.
+ * "Absent means the default" is the right rule for a comparison and the wrong one for a
+ * precedence chain, where absent has to mean "defer to the next tier".
+ *
+ * @param {string} siteDir
+ * @returns {string} a bare origin
+ */
+export function resolveSiteScope(siteDir) {
+  return readSiteIdentity(siteDir).backend || DEFAULT_BACKEND_ORIGIN
+}
+
+/**
+ * Record the sync scope on a site that has just been created or seeded.
+ *
+ * A no-op for the default backend (see the ⛔ above) and a no-op when the value is
+ * already what we would write, so a re-push never dirties `git status`.
+ *
+ * @param {string} siteDir
+ * @param {string} origin - the backend the site was just created on
+ * @param {object} [deps]
+ * @param {() => Promise<object>} [deps.loadUwx] - injected module loader. Exists so the
+ *        two failure branches below can be TESTED: both are about which `@uniweb/build`
+ *        happens to be on disk, which a test cannot otherwise vary — and the too-old
+ *        branch is precisely the one that used to fail silently.
+ * @returns {Promise<string|null>} the origin recorded, or null when nothing was written
+ */
+export async function recordSiteBackend(siteDir, origin, deps = {}) {
+  const norm = normalizeOrigin(origin)
+  if (!norm || norm === DEFAULT_BACKEND_ORIGIN) return null
+  if (readSiteIdentity(siteDir).backend === norm) return null
+  const loadUwx = deps.loadUwx || (() => import('@uniweb/build/uwx'))
+  let mod
+  try {
+    // Lazy by necessity, not by taste — see the header.
+    mod = await loadUwx()
+  } catch {
+    // No `@uniweb/build` at all. It is an OPTIONAL peer, so this is a supported
+    // configuration and not worth a word — the scope simply goes unrecorded, which is
+    // the behaviour everyone had before this key existed.
+    return null
+  }
+
+  // ⚠️ PRESENT BUT TOO OLD is a different problem, and it must not look like the one
+  // above. `@uniweb/build` gained `writeSiteBackend` in 0.25.3; against an older copy the
+  // import SUCCEEDS and the export is `undefined`, so calling it throws a TypeError that
+  // a blanket catch would swallow — leaving the scope silently unrecorded on a project
+  // that will later be stopped by the guard and told to add `$backend` by hand. Since the
+  // CLI declares build as a peer at a caret range, a lockfile pinned to an older patch
+  // reaches exactly this state on a CLI-only upgrade. Say so once.
+  if (typeof mod.writeSiteBackend !== 'function') {
+    console.error(
+      `\x1b[33m⚠\x1b[0m This project's @uniweb/build is too old to record which backend it syncs with — upgrade it (\`npx uniweb@latest update\`), or add \`$backend: ${norm}\` to site.yml.`
+    )
+    return null
+  }
+
+  try {
+    mod.writeSiteBackend(siteDir, norm)
+    return norm
+  } catch {
+    // Same rule as `recordSiteOrg`: the uuid is the load-bearing write. Losing the scope
+    // note must never fail a create that already succeeded on the backend — the guard
+    // degrades to the pre-`$backend` behaviour, which is what everyone had until now.
+    return null
+  }
+}
+
+/**
+ * Refuse to act on a site whose stored identity belongs to a different backend.
+ *
+ * ⭐ **A stop, not a warning.** `BackendClient.token()` already carries an advisory
+ * origin-mismatch guard for the SESSION (wrong bearer → a rejected request, recoverable).
+ * This is the third leg and it is categorically worse: the stored surface is foreign, so
+ * proceeding sends one backend's identity to another. The observed outcomes are a 404
+ * whose stock advice destroys the binding, and — on the record lane — a hard refusal
+ * (*"item uuids are globally unique; cross-entity move is not supported"*).
+ *
+ * Silent for an unsynced project (nothing stored yet ⇒ nothing to be foreign) and for a
+ * project on the default backend with no explicit override.
+ *
+ * @param {string} siteDir
+ * @param {string} origin - the backend this command resolved to
+ * @returns {{ ok: true } | { ok: false, message: string, hint: string[] }}
+ */
+export function assertSiteBackendScope(siteDir, origin) {
+  const { uuid, backend } = readSiteIdentity(siteDir)
+  // Nothing minted here yet — a create is exactly what is supposed to happen next, and
+  // it will record the scope itself. Checking a project with no stored identity would
+  // reject the first push of every new site.
+  if (!uuid) return { ok: true }
+
+  const target = normalizeOrigin(origin)
+  const bound = backend || DEFAULT_BACKEND_ORIGIN
+  if (!target || target === bound) return { ok: true }
+
+  const hint = [
+    `site.yml::$uuid (${uuid}) was minted by ${bound}, and the record uuids, assets.json`,
+    'and .uniweb/sync-cache.json are scoped to it too. Sending them elsewhere is refused.',
+    '',
+    `To work with ${bound}:  uniweb login --backend ${bound}   (or pass --backend ${bound})`,
+    `To move this project to ${target}, it becomes a NEW site there — clear $uuid, $org and`,
+    '$backend from site.yml and delete .uniweb/ and assets.json first.'
+  ]
+
+  // ⚠️ THE ONE FALSE POSITIVE, and it prints its own fix.
+  //
+  // `$backend` is omitted for the default backend, so an ABSENT value is ambiguous: it
+  // means "the default" for anything written under this scheme, and "unknown" for a
+  // project that synced to a non-default backend BEFORE the key existed. This branch
+  // reads absent as the default, so that second project is stopped and told it belongs
+  // to a backend it never used.
+  //
+  // Accepted deliberately rather than softened to a warning, because the alternative is
+  // worse in the case that matters: warning-on-absent would leave every DEFAULT-backend
+  // project — the 98% — unprotected forever, since those never record the key. Stopping
+  // on a guess is only tolerable when the guess prints the one-line correction, so it
+  // does. (The population at risk is also near-empty by construction: pre-`$backend`
+  // projects on a non-default backend, at a moment when no such backend is running.)
+  if (!backend) {
+    hint.push(
+      '',
+      `If this project actually syncs with ${target}, nothing recorded that — say so once:`,
+      `  add   $backend: ${target}   to site.yml, and this stops asking.`
+    )
+  }
+
+  return {
+    ok: false,
+    message: `This project's stored identity belongs to ${bound}, but this command targets ${target}.`,
+    hint
+  }
+}