uniweb 0.59.2 → 0.61.0

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
       })
@@ -833,18 +843,22 @@ export async function pull(args = [], deps = {}) {
       }
       // ⛔ NO QUERY CONFIG. A record's home is decided by what it IS — its
       // `$model` names the pool folder — not by any query that happens to select
-      // it. `recordsToProject` reads `site.yml::$org` itself, so a `@/x`
-      // model the producer resolved to `@org/x` is placed back where the author
-      // wrote it.
+      // it. `recordsToProject` reads the site's org itself (this backend's, from
+      // `sync.json`), so a `@/x` model the producer resolved to `@org/x` is placed
+      // back where the author wrote it.
       const report = recordsToProject({
         folderDoc,
         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
         }
       })
       if (report.records === 'updated') info('Wrote records.yml')
+      // The backend's folder has no sub-folders, and records.yml holds nothing else.
+      else if (report.records === 'removed') info('Removed records.yml — the folder has no sub-folders')
       records += report.placed.length + report.updated.length
       for (const s of report.skipped)
         note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
@@ -905,7 +919,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.')

package/src/commands/push.js

@@ -5,15 +5,16 @@
  *   - folder lane → one `@uniweb/folder` + the collection-record entities it
  *     references (the dynamic half; the `$ref` closure rides together).
  *
- * Each entity is an entity-content document (`$id` + `$model` + sections). The site
- * holds exactly one identity: `site.yml::$uuid` (the site-content entity). A first
- * push has none — it CREATEs the site (uuid-less), the backend mints + adopts it
- * and returns the new uuid, which `push` records into `site.yml`. Later pushes
+ * Each entity is an entity-content document (`$id` + `$model` + sections). The site's
+ * identity on a backend is its site-content uuid, in that backend's section of
+ * `sync.json`. A first push to a backend has none — it CREATEs the site (uuid-less),
+ * the backend mints + adopts it and returns the new uuid, which `push` records in
+ * `sync.json`. Later pushes
  * UPDATE by that uuid. The folder lane is keyed by the SAME site-content uuid —
  * the backend owns the site's `@uniweb/folder`, so the framework never holds a
  * folder uuid. Records still round-trip their own `$uuid`
  * (back-filled into their source files). site-content items carry a per-item `$uuid`
- * too, stamped at emit from the identity cache rather than from author files — without
+ * too, stamped at emit from `sync.json` rather than from author files — without
  * it the backend reads every record as new and recreates every page and section row.
  * Push-only, and gated on the backend's per-entity `version`
  * (see "Pushes are GATED by default" below); `--force` restores last-push-wins.
@@ -29,15 +30,14 @@
  *   uniweb push --org @org               Own the new site under @org (alias: --as-org).
  *                                        Read only on the FIRST push of a site — it
  *                                        decides which org owns it, and whose storage
- *                                        its assets are charged to. Recorded as
- *                                        `site.yml::$org` and replayed after that.
+ *                                        its assets are charged to. Recorded in
+ *                                        `sync.json` and replayed after that.
  *                                        Without it, you are asked once.
  *   uniweb push --personal               Own the new site personally, deliberately.
  *                                        Sends NO `as_org` — the same wire as before
  *                                        this prompt existed. First push only.
  *   uniweb push --dry-run                Report what would be pushed; submit nothing
  *   uniweb push -o out.uwx               Write the .uwx file(s) per lane; submit nothing
- *   uniweb push --token <bearer>         Submit with this bearer; skips `uniweb login`
  *   uniweb push --foundation <dir>       Use this local foundation for the Model schema
  *   uniweb push --all                    Send every record (bypass the changed-only cache)
  *   uniweb push --force                  Overwrite upstream changes (drop the staleness gate)
@@ -49,9 +49,9 @@
  * backend's reconcile deletes items absent from the package, so an author's NEW page
  * would be hard-deleted). `--force` omits the token and restores last-push-wins.
  *
- * Backend: via BackendClient (the content + folder sync lanes). Origin from
- *   UNIWEB_REGISTER_URL  >  the local 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`.
  *
  * The two-lane SUBMISSION (POST both lanes, back-fill uuids, persist the
  * send-only-changed cache) lives in `../backend/site-sync.js` so `uniweb publish`
@@ -63,17 +63,18 @@ import { readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { emitSyncPackages } from '@uniweb/build/uwx'
+import { findSiteCopies, describeSiteCopies } from '../utils/site-copies.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
-import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
+import { updateBackendMap, carryServed, SYNC_STORE_FILE } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
-import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
+import { resolveSiteDir } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
-  assertSiteBackendScope,
-  readSiteIdentity
+  syncedElsewhere,
+  describeSyncedElsewhere
 } from '../utils/site-identity.js'
 import { confirm } from '../utils/interactive.js'
 import { guardEmptyRecords } from '../utils/records-guard.js'
@@ -141,7 +142,6 @@ export async function push(args = [], deps = {}) {
   }
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
-  const tokenFlag = flagValue(args, '--token')
   const foundationDir = flagValue(args, '--foundation')
   const sendAll = args.includes('--all') // bypass the send-only-changed cache
   // --force drops the optimistic-concurrency precondition, making the push
@@ -156,50 +156,64 @@ 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)
+  // ⭐ 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."*
   // 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
   // offline: it never submits, and its Model resolver never reads from the backend
   // (the `offline` flag below), so it never authenticates — even when a collection
   // references a Model the local foundation doesn't define.
   const client = new BackendClient({
-    originFlag: flagValue(args, '--backend'),
-    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.
+  // ⛔ A COPY OF ANOTHER PROJECT — before anything is sent. A plain directory copy
+  // carries sync.json, so it holds the ORIGINAL's site on this backend and its push
+  // would update that site (see utils/site-copies.js for why the signal is exact).
+  // Refused, not warned: a warning printed while the push goes ahead is printed over
+  // the damage. Runs after the client so it checks the RESOLVED origin.
   //
-  // ⚠️ 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.
+  // ⚠️ NOT for `-o`, which is a LOCAL EMIT and reaches no backend at all — there is no
+  // site for it to update, and refusing would break an operation this command keeps
+  // offline (the `!output && !dryRun` guards below are the same rule).
   //
   // `--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.
+  // push, so when that push would be refused, saying so is the honest preview.
+  //
+  // *(This spot held the backend SCOPE CHECK, `assertSiteBackendScope`, until
+  // 2026-09-20 — deleted when identity became per-backend and a foreign backend's
+  // uuids stopped being reachable at all.)*
   if (!output) {
-    const scope = assertSiteBackendScope(siteDir, client.origin)
-    if (!scope.ok) {
-      error(scope.message)
-      scope.hint.forEach(note)
+    const copies = findSiteCopies(siteDir, client.origin)
+    if (copies.length) {
+      const said = describeSiteCopies(copies, client.origin, 'push')
+      error(said.headline)
+      for (const line of said.lines) note(line)
       return { exitCode: 1 }
     }
   }
 
+  // ⚠️ Logged in to a backend where this project has no site, while it has one
+  // elsewhere: following the login CREATES a second site. Say so before the owner
+  // question, which otherwise arrives with no reason attached. Not for `-o` (nothing is
+  // created) and not when UNIWEB_REGISTER_URL chose the backend — that is a decision.
+  if (!output && !process.env.UNIWEB_REGISTER_URL) {
+    const known = syncedElsewhere(siteDir, client.origin)
+    if (known) {
+      const [headline, ...rest] = describeSyncedElsewhere(known, client.origin, 'push')
+      info(headline)
+      for (const line of rest) note(line)
+    }
+  }
+
   // 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
@@ -298,18 +312,18 @@ export async function push(args = [], deps = {}) {
   //
   // Still skipped for an offline emit: `-o` / `--dry-run` must not mutate project state.
   if (!output && !dryRun) {
-    const dropped = clearRemoteSyncStateIfUnbound(siteDir)
+    const dropped = clearRemoteSyncStateIfUnbound(siteDir, client.origin)
     if (dropped.length) {
       note(
         `Cleared stale sync state from a previous site (${dropped.join(', ')}).`
       )
     }
-    const stale = dropSiteBoundValues(siteDir)
+    const stale = dropSiteBoundValues(siteDir, client.origin)
     if (stale.length) {
       note(`Dropped the previous site's ${stale.join(' and ')} from site.yml.`)
     }
   }
-  const priorHashes = readSyncCache(siteDir)
+  const priorHashes = readSyncCache(siteDir, client.origin)
   // Per-item identity, without which the backend reads every record as new and
   // recreates every page and section row.
   //
@@ -329,8 +343,8 @@ export async function push(args = [], deps = {}) {
   // The upload runs before `ensureItemUuids`, and the reason once recorded here —
   // "BEFORE `ensureItemUuids`, which mints uuids on the backend, so a refusal
   // leaves nothing minted" — is FALSE. `ensureItemUuids` mints nothing: it reads a
-  // local cache, and if that is empty it reads `site.yml::$uuid` and returns
-  // immediately when there is none (the first-push case). Its only backend call is
+  // local map, and if that is empty it reads this backend's site uuid from sync.json
+  // and returns immediately when there is none (the first-push case). Its only backend call is
   // a GET (`pullSiteContent`); its only write is a local file. So this ordering is
   // not protecting what that comment claimed, and is under review — an upload is a
   // durable, metered write, which makes uploading first the thing that leaves bytes
@@ -374,12 +388,12 @@ export async function push(args = [], deps = {}) {
   // It also has to be this emit that carries `assetRewrite` below: the push cache
   // stores hashes of the REWRITTEN content, so the emit compared against it must
   // rewrite too, or every entity reads as changed forever.
-  // ⛔ AN EMPTY `records.yml` REMOVES. It is the one path where an ordinary act is
-  // destructive — a placeholder file, created meaning to fill it in — so the count
-  // is reported and confirmed before anything is sent. The format stays honest;
-  // the asking happens here.
+  // ⛔ AN EMPTY RECORDS DIRECTORY REMOVES. It is the one path where an ordinary act
+  // is destructive — a directory emptied by accident, or kept with only a
+  // placeholder — so the count is reported and confirmed before anything is sent.
+  // The format stays honest; the asking happens here.
   if (!dryRun) {
-    const guard = await guardEmptyRecords({ siteDir, args, warn, note })
+    const guard = await guardEmptyRecords({ siteDir, backend: client.origin, args, warn, note })
     if (!guard.ok) return { exitCode: 1 }
   }
 
@@ -389,8 +403,9 @@ export async function push(args = [], deps = {}) {
     let mediaRefs = []
     try {
       const 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 } : {}),
@@ -458,10 +473,10 @@ export async function push(args = [], deps = {}) {
         )
         // Record identity in the COMMITTED map. Merge, never replace: this push
         // carries only the refs its content touched.
-        const rec = updateAssetMap(siteDir, ids)
+        const rec = updateBackendMap(siteDir, client.origin, 'assets', ids, carryServed)
         if (rec.written) {
           note(
-            `${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`
           )
         }
       } catch (err) {
@@ -482,16 +497,17 @@ export async function push(args = [], deps = {}) {
 
   const itemUuids =
     output || dryRun
-      ? readItemUuids(siteDir)
+      ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      backend: client.origin,
       // Placement identity for the folder — see writeFolderItemUuids.
-      folderItemUuids: readFolderItemUuids(siteDir),
+      folderItemUuids: readFolderItemUuids(siteDir, client.origin),
       // Identity for the `queries` section — see readQueryUuids. Keyed by
       // name, because a declaration has no file for a path-keyed map to hold.
-      queryUuids: readQueryUuids(siteDir),
+      queryUuids: readQueryUuids(siteDir, client.origin),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
@@ -513,8 +529,8 @@ export async function push(args = [], deps = {}) {
       ...(force
         ? {}
         : {
-            baseVersions: readBaseVersions(siteDir),
-            itemBaseVersions: readItemBaseVersions(siteDir)
+            baseVersions: readBaseVersions(siteDir, client.origin),
+            itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
           }),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})

package/src/commands/refresh.js

@@ -46,6 +46,8 @@ import {
   headProvenance
 } from '../utils/git.js'
 import { probeUnpushed } from '../backend/site-sync.js'
+import { resolveBackendOrigin } from '../backend/client.js'
+import { readBackendState } from '@uniweb/build/uwx'
 import { checkFlags } from '../utils/flag-guard.js'
 
 const c = {
@@ -65,28 +67,16 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
-// Forward a flag AND its value to the delegated verb. `--backend http://x` is two
-// argv entries, so a naive filter passes the flag and drops the URL — leaving the
-// delegated pull pointed at the default backend while the user believes they
-// overrode it. `--backend=http://x` is one entry and passes through as-is.
-function collectPassthrough(args, names) {
-  const out = []
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i]
-    const name = names.find((n) => a === n || a.startsWith(`${n}=`))
-    if (!name) continue
-    out.push(a)
-    if (a === name && args[i + 1] && !args[i + 1].startsWith('-'))
-      out.push(args[++i])
-  }
-  return out
-}
-
-// A site is backend-synced once it has an identity to pull by.
-function siteContentUuid(siteDir) {
+// A site is backend-synced once it has an identity to pull by — on THIS backend,
+// from sync.json. It read `site.yml::$uuid`, so after step 4 refresh treated every
+// project as unsynced and skipped the backend half of its check.
+//
+// ⛔ `backend` is the one the delegated pull will use: the backend the user is logged in
+// to. (For part of 2026-09-21, `refresh --backend X` checked one backend's sync state and
+// pulled from another; the flag is gone from the backend verbs since.)
+function siteContentUuid(siteDir, backend) {
   try {
-    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
-    return typeof y?.$uuid === 'string' ? y.$uuid : null
+    return readBackendState(siteDir, backend).site?.uuid || null
   } catch {
     return null
   }
@@ -155,20 +145,21 @@ export async function refresh(args = [], deps = {}) {
   }
 
   // ── 2. the backend ────────────────────────────────────────────────────────
+  // The backend the delegated pull talks to — the one you are logged in to
+  // (resolveBackendOrigin). Everything below asks about THAT one.
+  const backend = resolveBackendOrigin()
   if (skipBackend) {
     skipped.push('backend (--no-backend)')
-  } else if (!siteContentUuid(siteDir)) {
+  } else if (!siteContentUuid(siteDir, backend)) {
     skipped.push('backend (this site has never been synced)')
   } else {
     say.info("Merging the backend's content…")
     const pull = deps.pull || (await import('./pull.js')).pull
     // `--merge` rather than a plain pull: an author editing a different part of the
     // same section is not a conflict, and should not be presented as one.
-    const passthrough = collectPassthrough(args, [
-      '--backend',
-      '--token'
-    ])
-    const res = await pull(['--merge', ...passthrough])
+    // Nothing of refresh's own argv is forwarded: the pull goes to the backend you are
+    // logged in to, as refresh does, and authenticates the same way.
+    const res = await pull(['--merge'])
     conflicts = res?.merge?.conflicted?.length ?? 0
     if (res?.exitCode && !conflicts) {
       // Failed for a reason other than conflicts — say so plainly rather than
@@ -192,9 +183,11 @@ export async function refresh(args = [], deps = {}) {
 
   // What is still yours to send. The point of a milestone check is knowing both
   // directions, not just that you took what was waiting.
-  if (!skipBackend && siteContentUuid(siteDir)) {
+  if (!skipBackend && siteContentUuid(siteDir, backend)) {
     try {
-      const probe = await probeUnpushed(siteDir)
+      // Whose asset ids the comparison reads — see status.js. Offline, so the
+      // origin is resolved rather than taken from a client.
+      const probe = await probeUnpushed(siteDir, { backend })
       if (probe.changed)
         say.dim(
           `Unpushed: ${probe.changed} entit${probe.changed === 1 ? 'y' : 'ies'} changed locally`