uniweb 0.59.1 → 0.60.0

package/src/commands/publish.js

@@ -20,8 +20,9 @@
  * Distinct from `uniweb deploy` (third-party hosts) and `uniweb register`
  * (foundation code → catalog). For a self-contained artifact, see `uniweb export`.
  *
- * Backend: BackendClient. Origin from --backend > UNIWEB_REGISTER_URL
- * > default. Auth: --token > UNIWEB_TOKEN > `uniweb login` session.
+ * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
+ *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
  *
  * Usage:
  *   uniweb publish                 Bring the foundation along, sync, and go live
@@ -37,9 +38,7 @@
  *   uniweb publish --personal      Own the new site personally, deliberately. Sends
  *                                  NO `as_org` — byte-identical to the wire before
  *                                  the owner prompt existed. First publish only.
- *   uniweb publish --no-save       Skip the deploy.yml lastDeploy auto-save
- *   uniweb publish --backend <url> Override the backend origin
- *   uniweb publish --token <bearer> Auth bearer (skips `uniweb login`)
+ *   uniweb publish --no-save       Do not record this publish in deploy.yml
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -50,7 +49,7 @@ import yaml from 'js-yaml'
 
 import {
   loadDeployYml,
-  resolveTarget,
+  resolvePublishTarget,
   recordLastDeploy,
   collectSchemalessData,
   collectSchemalessDataAssets,
@@ -67,16 +66,18 @@ import { isSiteRelativeExtensionUrl } from '@uniweb/build'
 import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 
 import { BackendClient } from '../backend/client.js'
-import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
+import { DEFAULT_BACKEND_ORIGIN } from '../utils/config.js'
+import { resolveSiteDir } 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
+  syncedElsewhere,
+  describeSyncedElsewhere
 } from '../utils/site-identity.js'
 import { isNonInteractive, confirm } from '../utils/interactive.js'
 import { guardEmptyRecords } from '../utils/records-guard.js'
+import { findSiteCopies, describeSiteCopies } from '../utils/site-copies.js'
 import { headProvenance } from '../utils/git.js'
 import {
   makeModelResolver,
@@ -92,7 +93,12 @@ import {
   resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
-import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
+import {
+  updateBackendMap,
+  readBackendState,
+  carryServed,
+  SYNC_STORE_FILE
+} from '@uniweb/build/uwx'
 import {
   bringFoundationAlong,
   bringExtensionsAlong
@@ -158,7 +164,7 @@ function languagesFromSiteYml(siteYml) {
   return [def, ...norm.filter((l) => l !== def)]
 }
 
-// Persist deploy.yml lastDeploy memory (skipped on --no-save / autoSave 'off').
+// Persist the deploys memo in deploy.yml (skipped on --no-save / saveDeploys: false).
 /**
  * A one-line, human-readable account of a service request, for a terminal.
  *
@@ -223,7 +229,7 @@ function describeServices(rows) {
 }
 
 async function persistLastDeploy(siteDir, opts) {
-  if (opts.autoSave === 'off') return
+  if (opts.saveDeploys === false) return
   try {
     const result = await recordLastDeploy(siteDir, opts)
     if (result?.created)
@@ -253,33 +259,48 @@ export async function publish(args = []) {
   // is not a gate.
   await warnIfContentDoesNotConform(siteDir, { 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)
+  // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
+  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // override — outranks it, and nothing talks to a backend the user is not logged in to:
+  // logged in nowhere, the origin is the default backend and the first request asks for
+  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
+  // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
+  // be reached: *"We do not allow any communication with backend if the user is not
+  // logged into a backend."*
 
   const client = new BackendClient({
-    originFlag:
-      readFlagValue(args, '--backend'),
-    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 }
+  // ⛔ A COPY OF ANOTHER PROJECT — before the foundation bring-along, the sync, or the
+  // go-live. A plain directory copy carries sync.json, so it holds the ORIGINAL's site
+  // on this backend and would publish over it (utils/site-copies.js). 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.
+  // *(The backend scope check that stood here went on 2026-09-20 — see push.js.)*
+  {
+    const copies = findSiteCopies(siteDir, client.origin)
+    if (copies.length) {
+      const said = describeSiteCopies(copies, client.origin, 'publish')
+      say.err(said.headline)
+      for (const line of said.lines) say.dim(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 when
+  // UNIWEB_REGISTER_URL chose the backend — that is already a decision.
+  if (!process.env.UNIWEB_REGISTER_URL) {
+    const known = syncedElsewhere(siteDir, client.origin)
+    if (known) {
+      const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'publish')
+      say.info(headline)
+      for (const line of rest) say.dim(line)
+    }
   }
 
   // WHO will own this site, if this publish is the one that creates it. Resolved
@@ -341,35 +362,36 @@ export async function publish(args = []) {
   //     nothing scaffolded ever set it, it is in no public doc, and the backend
   //     may already have been ignoring it.
 
-  // deploy.yml target (the Uniweb hosting memory). No --target on publish — it
-  // always targets Uniweb hosting; resolveTarget gives us the target name +
-  // autoSave for the lastDeploy memo.
+  // deploy.yml target (the Uniweb hosting memory) — the one for the backend this
+  // publish goes to. ⭐ The target follows the backend, never the reverse: the default
+  // target only breaks a tie (resolvePublishTarget). With no deploy.yml, or no target
+  // naming this backend, persistLastDeploy adds one.
+  //
+  // ⛔ This took deploy.yml's DEFAULT target until 2026-09-21, whatever backend it was
+  // publishing to — a publish to a second backend wrote over the default target's
+  // record and compared its request against that target's fingerprint.
   let resolved
   let priorRequest = null
   try {
     const deployYml = await loadDeployYml(siteDir)
-    // No --target on publish — it always targets Uniweb hosting; resolveTarget
-    // returns the uniweb default (fromFile:false) when there's no deploy.yml, so
-    // persistLastDeploy scaffolds the file as the "where it's deployed" record.
-    resolved = resolveTarget(deployYml, null)
-    // The last request we are known to have sent, for the declaration gate below.
-    // Read from the SAME deploy.yml load — one read, and the memo is the only
-    // durable record of it (see backend/service-request.js for why not the cache).
-    priorRequest =
-      deployYml?.lastDeploy?.[resolved?.targetName] ||
-      deployYml?.lastDeploy?.uniweb ||
-      null
+    resolved = resolvePublishTarget(deployYml, client.origin, {
+      defaultBackend: DEFAULT_BACKEND_ORIGIN
+    })
+    // The last request we are known to have sent TO THIS BACKEND, for the declaration
+    // gate below. Read from the SAME deploy.yml load — one read, and the memo is the
+    // only durable record of it (see backend/service-request.js for why not the cache).
+    priorRequest = deployYml?.deploys?.[resolved.targetName] || null
   } catch {
     // Malformed/ambiguous deploy.yml — don't block the publish on the memo.
     resolved = {
       targetName: 'production',
       host: 'uniweb',
       config: {},
-      autoSave: 'lastDeploy',
+      saveDeploys: true,
       fromFile: false
     }
   }
-  const autoSave = noSave ? 'off' : resolved.autoSave || 'lastDeploy'
+  const saveDeploys = !noSave && resolved.saveDeploys !== false
 
   // A SITE-RELATIVE extension URL cannot work on Uniweb hosting: the published
   // site ships no JS, so nothing serves that path. The request falls through to
@@ -410,7 +432,7 @@ export async function publish(args = []) {
     say.info('Dry run — would bring the foundation along, sync, and go live:')
     say.dim(`Backend     : ${client.origin}`)
     say.dim(
-      `site_uuid   : ${siteYml.$uuid || '(none — the site is created before anything uploads)'}`
+      `site_uuid   : ${readBackendState(siteDir, client.origin).site?.uuid || '(none — the site is created before anything uploads)'}`
     )
     const langs = languagesFromSiteYml(siteYml)
     if (langs) say.dim(`Languages   : ${langs.join(', ')}`)
@@ -531,8 +553,9 @@ export async function publish(args = []) {
   let probe
   try {
     probe = await emitSyncPackages(siteDir, {
+      backend: client.origin,
       // Placement identity for the folder — see writeFolderItemUuids.
-      folderItemUuids: readFolderItemUuids(siteDir),
+      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
@@ -553,13 +576,13 @@ export async function publish(args = []) {
   //     that describes one is stale — including after the documented "clear
   //     `$uuid` to re-publish as a new site" recovery. Must run BEFORE the create,
   //     which mints a uuid and would make the clone look bound.
-  const droppedState = clearRemoteSyncStateIfUnbound(siteDir)
+  const droppedState = clearRemoteSyncStateIfUnbound(siteDir, client.origin)
   if (droppedState.length) {
     say.dim(
       `Cleared stale sync state from a previous site (${droppedState.join(', ')}).`
     )
   }
-  const droppedValues = dropSiteBoundValues(siteDir)
+  const droppedValues = dropSiteBoundValues(siteDir, client.origin)
   if (droppedValues.length) {
     say.dim(
       `Dropped the previous site's ${droppedValues.join(' and ')} from site.yml.`
@@ -628,10 +651,10 @@ export async function publish(args = []) {
       if (Object.keys(ids).length) assetIds = ids
       // Identity into the COMMITTED map — see backend/asset-map.js. Merge, not
       // replace: this publish carries only the refs its content touched.
-      const rec = updateAssetMap(siteDir, ids)
+      const rec = updateBackendMap(siteDir, client.origin, 'assets', ids, carryServed)
       if (rec.written) {
         say.dim(
-          `${ASSET_MAP_FILE}   : ${rec.added.length} added, ${rec.changed.length} changed — commit it`
+          `${SYNC_STORE_FILE}   : ${rec.added.length} asset(s) added, ${rec.changed.length} changed — commit it`
         )
       }
       if (ballAssets.length) ball = rewriteSchemalessDataAssets(ball, map)
@@ -731,13 +754,13 @@ export async function publish(args = []) {
   //    the pinned foundation ref and rewriting local media refs to serve URLs.
   //    (It stamped `info.data_bundle` until 2026-08-18; the ball is gone and
   //    collection data now lands at its serving tail, so nothing records it.)
-  const priorHashes = readSyncCache(siteDir)
+  const priorHashes = readSyncCache(siteDir, client.origin)
   // publish rides the same gated push as `uniweb push`: if an app author has
   // edited since this clone last synced, the push is refused rather than
   // overwriting them, and nothing goes live. `--force` drops the precondition.
   const baseVersions = args.includes('--force')
     ? null
-    : readBaseVersions(siteDir)
+    : readBaseVersions(siteDir, client.origin)
   // Per-item identity, recovered from the backend when this clone has never seen it.
   // Without it the backend re-mints every page and section row (see readItemUuids).
   const itemUuids = await ensureItemUuids({
@@ -789,15 +812,20 @@ export async function publish(args = []) {
   // network blip, a site never pushed. That is the shipped behaviour and it is safe:
   // it withholds an unchanged block and sends a changed one; it merely cannot see
   // the app's side.
-  let declaration = decideDeclaration(siteYml, priorRequest)
+  // What this site is PROVISIONED with on the backend being published to.
+  const provisioned = readBackendState(siteDir, client.origin)
+  const boundUuid = provisioned.site?.uuid || null
+  let declaration = decideDeclaration(siteYml, priorRequest, provisioned)
   let adopted = null
   // Before the push, so a never-synced site has no uuid and simply skips this.
   const status =
-    typeof siteYml.$uuid === 'string' && siteYml.$uuid
-      ? await client.siteStatus(siteYml.$uuid)
+    // This backend's site, from sync.json. It read `site.yml::$uuid`, so after step 4
+    // the remote reconcile below never ran and every publish declared blind.
+    boundUuid
+      ? await client.siteStatus(boundUuid)
       : null
   if (status && Array.isArray(status.services)) {
-    const r = reconcileRequest(siteYml, status.services, priorRequest)
+    const r = reconcileRequest(siteYml, status.services, priorRequest, provisioned)
     if (r.action === 'none') {
       declaration = { declare: false, reason: 'in-sync' }
     } else if (r.action === 'send') {
@@ -835,7 +863,7 @@ export async function publish(args = []) {
   // for one commit. Asking is the only thing that resolves it.
   if (declaration.reason === 'conflict') {
     say.warn('Your site\'s services were changed elsewhere, and site.yml changed too.')
-    say.dim(`  in site.yml:  ${describeServices(siteYml.$services)}`)
+    say.dim(`  in sync.json: ${describeServices(provisioned.services)}`)
     say.dim(`  on your site: ${describeServices(adopted)}`)
     if (isNonInteractive(args)) {
       say.dim('  Left your site as it is — run without --non-interactive to choose.')
@@ -886,7 +914,7 @@ export async function publish(args = []) {
     // site refused, where nothing of theirs changed and ours simply did not take.
     // We cannot tell those apart here, so the wording claims neither.
     say.info('Your site has different services than site.yml lists.')
-    say.dim(`  in site.yml:  ${describeServices(siteYml.$services)}`)
+    say.dim(`  in sync.json: ${describeServices(provisioned.services)}`)
     say.dim(`  on your site: ${describeServices(adopted)}`)
     // ⭐ OFFERED, NEVER DONE. site.yml is the owner's file, and a publish that
     // silently rewrites an authored file is the surprise this seam exists to
@@ -911,9 +939,10 @@ export async function publish(args = []) {
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      backend: client.origin,
       ...(declaration.declare ? {} : { declareServices: false }),
       // Placement identity for the folder — see writeFolderItemUuids.
-      folderItemUuids: readFolderItemUuids(siteDir),
+      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
@@ -921,7 +950,7 @@ export async function publish(args = []) {
       priorHashes,
       itemUuids,
       ...(baseVersions
-        ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir) }
+        ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir, client.origin) }
         : {}),
       ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
       ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
@@ -988,7 +1017,7 @@ export async function publish(args = []) {
     say.err(`Publish rejected: HTTP ${pubRes.status} ${pubRes.statusText}`)
     if (pubRes.status === 401 || pubRes.status === 403) {
       say.dim(
-        "Credentials weren't accepted — run `uniweb login` (or pass --token <bearer>)."
+        "Credentials weren't accepted — run `uniweb login` again."
       )
     }
     if (body) say.dim(body.slice(0, 800))
@@ -1008,8 +1037,8 @@ export async function publish(args = []) {
   const serveUrl = typeof result.url === 'string' && result.url ? result.url : null
 
   // 8. Persist deploy.yml memory — a record of what went live (and so a re-run
-  //    reuses the resolved target without re-asking). One identity:
-  //    site.yml::$uuid. `released` records whether this publish shipped a new
+  //    reuses the resolved target without re-asking). Identity is sync.json's,
+  //    per backend. `released` records whether this publish shipped a new
   //    foundation version (the bring-along, §4).
   // Record the ref that actually went live: the pinned `@scope/name@version`
   // from the bring-along when present, else the site.yml ref verbatim.
@@ -1021,13 +1050,13 @@ export async function publish(args = []) {
   const recordedRef = fnd.ref || siteYmlRef
   await persistLastDeploy(siteDir, {
     targetName: resolved.targetName,
-    // First publish scaffolds deploy.yml with the backend recorded on the
-    // target, binding the site to where it went live (uniweb.app, or a B2B
-    // backend). resolveSiteBackend reads it back on later publishes.
+    // A target this file does not have yet — the first publish anywhere (the whole
+    // file is scaffolded), or the first to a backend no target names (the target is
+    // added beside the others) — records the backend it went live on.
     targetConfig: resolved.fromFile
       ? null
       : { host: 'uniweb', backend: client.origin },
-    autoSave,
+    saveDeploys,
     lastDeploy: {
       at: new Date().toISOString(),
       host: 'uniweb',
@@ -1037,7 +1066,7 @@ export async function publish(args = []) {
       // service's `config` is opaque, so recording either verbatim would write
       // them into git. Absent when the file declares no block.
       ...(declaration.declare
-        ? fingerprintRequest(siteYml)
+        ? fingerprintRequest(siteYml, provisioned)
         : {
             // Nothing was sent, so the base is unchanged — carry it forward
             // rather than dropping it, or the next publish would read "no record"

package/src/commands/pull.js

@@ -1,8 +1,8 @@
 /**
  * uniweb pull — bring the backend's copy of a site back to canonical files.
  *
- * The read-side mirror of `uniweb push`. The project holds exactly one identity —
- * `site.yml::$uuid` (the site-content entity) — and BOTH pull lanes are keyed by it
+ * The read-side mirror of `uniweb push`. The project's identity on a backend — its
+ * site-content uuid, in that backend's section of `sync.json` — keys BOTH pull lanes
  * (the backend owns the site's `@uniweb/folder` and resolves it from the site-content
  * uuid, so the framework never holds a folder uuid). It GETs the two lanes and projects
  * the returned documents back to files via the framework's projection layer
@@ -41,12 +41,12 @@
  *   uniweb pull --merge                  Three-way merge local changes with the backend's
  *   uniweb pull --force                  Pull over uncommitted local changes (discards them)
  *   uniweb pull --dry-run                Report what it would GET; write nothing
- *   uniweb pull --token <bearer>         Read with this bearer; skips `uniweb login`
  *
- * Backend: via BackendClient (the content + folder pull lanes), both keyed by
- *   `site.yml::$uuid`. Origin from
- *   UNIWEB_REGISTER_URL  >  the local default.
- * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ * The content + folder pull lanes are both keyed by the site's uuid on that backend
+ *   (sync.json).
+ * Backend: the one you are logged in to — UNIWEB_REGISTER_URL overrides it for a script
+ *   (resolveBackendOrigin). Auth: UNIWEB_TOKEN  >  the stored session  >  `uniweb login`.
+ *   No `--backend` or `--token`: switching and signing in are `uniweb login`.
  *
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
  * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
@@ -69,6 +69,7 @@ import { join, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
 import { downloadMissingAssets } from '../backend/asset-download.js'
 import {
+  readBackendState,
   siteContentDocumentToProject,
   recordsToProject,
   readZip,
@@ -98,14 +99,10 @@ import {
 } from '../utils/git.js'
 import { isNonInteractive } from '../utils/interactive.js'
 import { BackendClient } from '../backend/client.js'
-import {
-  resolveSiteDir as defaultResolveSiteDir,
-  resolveSiteBackend
-} from './deploy.js'
+import { resolveSiteDir as defaultResolveSiteDir } from './deploy.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
-  assertSiteBackendScope,
-  readSiteIdentity
+  syncedElsewhere
 } from '../utils/site-identity.js'
 
 const FOLDER_MODEL = '@uniweb/folder'
@@ -188,7 +185,8 @@ function readYamlUuid(filePath) {
   } catch (err) {
     return { uuid: null, unparsed: err.message.split('\n')[0] }
   }
-  return { uuid: typeof obj?.$uuid === 'string' ? obj.$uuid : null }
+  // Only whether site.yml parses. The uuid itself lives in sync.json now.
+  return { uuid: null }
 }
 
 // Conditional-pull ETag cache (gitignored `.uniweb/pull-cache.json`): the last ETag
@@ -540,7 +538,6 @@ export async function pull(args = [], deps = {}) {
   const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
 
   const dryRun = args.includes('--dry-run')
-  const tokenFlag = flagValue(args, '--token')
   const prune = !(args.includes('--no-delete') || args.includes('--no-prune')) // git-like by default
   const noRecords =
     args.includes('--no-records') || args.includes('--content-only')
@@ -579,35 +576,28 @@ 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)
+  // ⭐ THE BACKEND YOU ARE LOGGED IN TO is where this goes *[Diego, 2026-09-21]*, for every
+  // backend verb (resolveBackendOrigin). Only UNIWEB_REGISTER_URL — the automation
+  // override — outranks it, and nothing talks to a backend the user is not logged in to:
+  // logged in nowhere, the origin is the default backend and the first request asks for
+  // that login. ⛔ There is no `--backend` here: switching is `uniweb login --backend`.
+  // ⛔ The project's own record — its synced backend, deploy.yml's default target — routes
+  // NOTHING. For part of 2026-09-21 it answered a "logged in nowhere" tier, which cannot
+  // be reached: *"We do not allow any communication with backend if the user is not
+  // logged into a backend."*
   const client = new BackendClient({
-    originFlag: flagValue(args, '--backend'),
-    siteScope,
-    siteBackend,
-    token: tokenFlag,
     getToken: deps.getToken,
     fetchImpl: deps.fetch,
     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 }
-  }
+  // ⭐ No scope check any more — and none is needed. This project's identity on
+  // `client.origin` is read from that origin's own section of sync.json, so a
+  // wrong-backend pull cannot happen: it would find no uuid and stop below.
 
-  // 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.
+  // One identity per site per backend. Both lanes (content + folder) are keyed by it —
+  // the backend resolves the site's `@uniweb/folder` from this uuid.
   const siteYmlPath = join(siteDir, 'site.yml')
   const identity = readYamlUuid(siteYmlPath)
 
@@ -621,11 +611,28 @@ export async function pull(args = [], deps = {}) {
     return { exitCode: 1 }
   }
 
-  const siteContentUuid = identity.uuid
+  // ⛔ FROM sync.json, FOR THIS BACKEND. This read `identity.uuid` — site.yml's `$uuid`
+  // — and kept doing so after step 4 moved the key, so EVERY pull of a synced project
+  // answered "Nothing to pull — this project has no $uuid yet". site.yml is still
+  // parsed above, because a file that will not parse is its own error.
+  const siteContentUuid = readBackendState(siteDir, client.origin).site?.uuid || null
 
   if (!siteContentUuid) {
+    // Following the login can land on a backend with no site for this project while it
+    // has one elsewhere — say where, rather than only "push first", which would create a
+    // second site. Not when UNIWEB_REGISTER_URL chose the backend: that is a decision.
+    const known = !process.env.UNIWEB_REGISTER_URL
+      ? syncedElsewhere(siteDir, client.origin)
+      : null
+    if (known) {
+      info(`Nothing to pull — this project has no site on ${client.origin}.`)
+      note(
+        `Its ${known.length === 1 ? `site is on ${known[0]}` : `sites are on ${known.join(', ')}`}. To pull from there: uniweb login --backend <url>`
+      )
+      return { exitCode: 0 }
+    }
     info(
-      'Nothing to pull — this project has no $uuid yet. Run `uniweb push` first.'
+      `Nothing to pull — this project has not synced with ${client.origin} yet. Run \`uniweb push\` first.`
     )
     return { exitCode: 0 }
   }
@@ -652,7 +659,7 @@ export async function pull(args = [], deps = {}) {
       res = await doRequest()
     } catch (err) {
       error(`Could not reach the backend at ${client.origin}: ${err.message}`)
-      note('Set the origin with --backend <url> or UNIWEB_REGISTER_URL.')
+      note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
       return null
     }
     if (res.status === 404) {
@@ -667,7 +674,7 @@ export async function pull(args = [], deps = {}) {
       error(`${label} pull failed: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403)
         note(
-          "Credentials weren't accepted — supply a bearer with --token <bearer>."
+          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
         )
       return null
     }
@@ -678,8 +685,8 @@ export async function pull(args = [], deps = {}) {
       // Bank the per-entity staleness tokens this lane carried, so the next push
       // is gated against the state we just took. A 304 skips this — correctly:
       // unchanged upstream means the token we already hold is still current.
-      mergeBaseVersions(siteDir, readPullVersions(buf))
-      mergeItemBaseVersions(siteDir, readPullItemVersions(buf))
+      mergeBaseVersions(siteDir, client.origin, readPullVersions(buf))
+      mergeItemBaseVersions(siteDir, client.origin, readPullItemVersions(buf))
       return { docs, etag }
     } catch (err) {
       error(`Could not read the ${label} response: ${err.message}`)
@@ -721,14 +728,14 @@ export async function pull(args = [], deps = {}) {
       // byte-identical to it, so the old local base no longer describes anything.
       // The next push re-establishes it; until then our side reports as unknown,
       // which is honest rather than wrong.
-      writeUnitBases(siteDir, { remote: computeUnitHashes(siteDoc), local: {} })
+      writeUnitBases(siteDir, client.origin, { remote: computeUnitHashes(siteDoc), local: {} })
       // Per-item identity for the next push. Without it the backend reads our
       // records as new and re-mints every page and section row.
-      writeItemUuids(siteDir, collectUnitUuids(siteDoc))
+      writeItemUuids(siteDir, client.origin, collectUnitUuids(siteDoc))
       // The collections section's identity has no file to live in either — same
       // reason, same remedy, keyed by name. A pull is the other route by which a
       // copy can recover it (see readQueryUuids).
-      writeQueryUuids(siteDir, collectQueryUuids(siteDoc))
+      writeQueryUuids(siteDir, client.origin, collectQueryUuids(siteDoc))
       // Bring the media down BEFORE projecting: a newly-landed asset gains a map
       // entry, and the projection reads that map to put authored paths back. Run
       // after, and this pull's new assets would project as URLs and only restore
@@ -795,6 +802,9 @@ export async function pull(args = [], deps = {}) {
       const report = siteContentDocumentToProject({
         document: siteDoc,
         siteRoot: siteDir,
+        // Which backend's asset ids to read back as the author's own paths. Without
+        // it a pull leaves every image pointing at a backend route.
+        backend: client.origin,
         prune,
         keepAuthoredFoundation
       })
@@ -841,6 +851,8 @@ export async function pull(args = [], deps = {}) {
         recordDocs,
         siteRoot: siteDir,
         opts: {
+          // Whose record map to read and extend, and whose org to place models under.
+          backend: client.origin,
           resolveDeclaration: (name) => declByModel.get(name) || null
         }
       })
@@ -905,7 +917,7 @@ export async function pull(args = [], deps = {}) {
   // wrong content, and must not fail a pull whose files are already written.
   if (!dryRun) {
     try {
-      await rebankSyncHashes(siteDir)
+      await rebankSyncHashes(siteDir, client.origin)
     } catch (err) {
       note(`! could not re-bank the sync cache: ${err.message}`)
       note('  The next push will re-send content that is already current.')