uniweb 0.33.1 → 0.34.1

package/src/commands/pull.js

@@ -10,7 +10,7 @@
  *
  *   - content lane → `siteContentDocumentToProject` (site.yml/theme.yml/head.html,
  *     pages/**, layout/**), and
- *   - folder lane  → `collectionsToProject` (the folder + record files).
+ *   - folder lane  → `recordsToProject` (the folder + record files).
  *
  * Pull is a CHECKOUT, not a merge — the "git-pull-like" it used to claim here was
  * misleading. It reconciles the working tree to the backend: section bodies are
@@ -36,7 +36,7 @@
  *
  * Usage:
  *   uniweb pull                          GET both lanes, project to files, prune orphans
- *   uniweb pull --no-collections         Pull pages only; skip the folder (collections) lane
+ *   uniweb pull --no-records         Pull pages only; skip the folder (records) lane
  *   uniweb pull --no-delete              Project, but keep files with no backend item
  *   uniweb pull --merge                  Three-way merge local changes with the backend's
  *   uniweb pull --force                  Pull over uncommitted local changes (discards them)
@@ -52,7 +52,7 @@
  * 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` +
  * `entities/<uuid>.json`); `readPullDocuments` reads the entity files out of it, with
- * a tolerant JSON fallback (`extractDocument` / `splitCollectionsPull`). Verified live
+ * a tolerant JSON fallback (`extractDocument` / `splitRecordsPull`). Verified live
  * against the playground backend, 2026-06-17.
  */
 
@@ -71,12 +71,11 @@ import yaml from 'js-yaml'
 import { downloadMissingAssets } from '../backend/asset-download.js'
 import {
   siteContentDocumentToProject,
-  collectionsToProject,
-  resolveCollectionsConfig,
+  recordsToProject,
   readZip,
   computeUnitHashes,
   collectUnitUuids,
-  collectCollectionUuids
+  collectQueryUuids
 } from '@uniweb/build/uwx'
 import {
   readWritten,
@@ -86,7 +85,7 @@ import {
 import {
   makeModelResolver,
   rebankSyncHashes,
-  writeCollectionUuids,
+  writeQueryUuids,
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,
@@ -203,7 +202,7 @@ export function extractDocument(payload) {
 // Split a collections pull (the folder + the entities it references) into the
 // folder document and the record documents. Tolerant of an array, an
 // `{ entities }` / `{ documents }` list, or an explicit `{ folder, records }`.
-export function splitCollectionsPull(payload) {
+export function splitRecordsPull(payload) {
   if (payload?.folder)
     return { folderDoc: payload.folder, recordDocs: payload.records || [] }
   const list = Array.isArray(payload)
@@ -240,7 +239,7 @@ export function readPullDocuments(buf) {
     }
     return docs
   }
-  // JSON fallback — flatten any envelope splitCollectionsPull understands into a
+  // JSON fallback — flatten any envelope splitRecordsPull understands into a
   // flat `$`-document list (a raw doc, a list, `{entities}`/`{documents}`, or
   // `{folder, records}`).
   let payload
@@ -519,8 +518,8 @@ export async function pull(args = [], deps = {}) {
   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 noCollections =
-    args.includes('--no-collections') || args.includes('--content-only')
+  const noRecords =
+    args.includes('--no-records') || args.includes('--content-only')
   const force = args.includes('--force')
   const mergeMode = args.includes('--merge')
 
@@ -598,7 +597,7 @@ export async function pull(args = [], deps = {}) {
     info(
       `Dry run — would pull content from ${colors.dim}${client.origin}${colors.reset}`
     )
-    if (!noCollections) info(`Dry run — would also pull collections`)
+    if (!noRecords) info(`Dry run — would also pull records`)
     return { exitCode: 0 }
   }
 
@@ -691,8 +690,8 @@ export async function pull(args = [], deps = {}) {
       writeItemUuids(siteDir, 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 readCollectionUuids).
-      writeCollectionUuids(siteDir, collectCollectionUuids(siteDoc))
+      // copy can recover it (see readQueryUuids).
+      writeQueryUuids(siteDir, 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
@@ -777,13 +776,13 @@ export async function pull(args = [], deps = {}) {
   // Lane 2 — folder → the folder + record files, keyed by the SAME site-content uuid
   // (the backend resolves the site's `@uniweb/folder` from it; the framework never
   // holds a folder uuid). Models are resolved by name (async) up front, so
-  // collectionsToProject keeps its synchronous contract. A 304 leaves files as-is.
-  if (!noCollections) {
-    const folder = await getDocs('collections', () =>
+  // recordsToProject keeps its synchronous contract. A 304 leaves files as-is.
+  if (!noRecords) {
+    const folder = await getDocs('records', () =>
       client.pullFolder(siteContentUuid, { etag: etagFolder })
     )
     if (folder && !folder.notModified && folder.docs?.length) {
-      const { folderDoc, recordDocs } = splitCollectionsPull(folder.docs)
+      const { folderDoc, recordDocs } = splitRecordsPull(folder.docs)
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
       for (const model of [
@@ -795,18 +794,20 @@ export async function pull(args = [], deps = {}) {
           note(`! could not resolve model ${model}: ${err.message}`)
         }
       }
-      const collectionsConfig = await resolveCollectionsConfig(siteDir).catch(
-        () => null
-      )
-      const report = collectionsToProject({
+      // ⛔ 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.
+      const report = recordsToProject({
         folderDoc,
         recordDocs,
         siteRoot: siteDir,
         opts: {
-          resolveDeclaration: (name) => declByModel.get(name) || null,
-          collectionsConfig
+          resolveDeclaration: (name) => declByModel.get(name) || null
         }
       })
+      if (report.records === 'updated') info('Wrote records.yml')
       records += report.placed.length + report.updated.length
       for (const s of report.skipped)
         note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
@@ -840,7 +841,7 @@ export async function pull(args = [], deps = {}) {
     siteDir,
     [
       ...wrote,
-      ...['site.yml', 'theme.yml', 'head.html', 'collections.yml'].map((f) =>
+      ...['site.yml', 'theme.yml', 'head.html', 'queries.yml', 'records.yml'].map((f) =>
         join(siteDir, f)
       )
     ],

package/src/commands/push.js

@@ -69,7 +69,7 @@ import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
-import { reportSchemalessCollections } from '../utils/schemaless-report.js'
+import { reportSchemalessQueries } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
 import {
@@ -77,6 +77,7 @@ import {
   readSiteIdentity
 } from '../utils/site-identity.js'
 import { confirm } from '../utils/interactive.js'
+import { guardEmptyRecords } from '../utils/records-guard.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
   makeModelResolver,
@@ -85,7 +86,7 @@ import {
   readItemBaseVersions,
   readItemUuids,
   readFolderItemUuids,
-  readCollectionUuids,
+  readQueryUuids,
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
@@ -369,6 +370,15 @@ 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.
+  if (!dryRun) {
+    const guard = await guardEmptyRecords({ siteDir, args, warn, note })
+    if (!guard.ok) return { exitCode: 1 }
+  }
+
   let assetRewrite = null
   let assetIds = null
   if (!output && !dryRun) {
@@ -475,9 +485,9 @@ export async function push(args = [], deps = {}) {
     pkg = await emitSyncPackages(siteDir, {
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir),
-      // Identity for the `collections` section — see readCollectionUuids. Keyed by
+      // Identity for the `queries` section — see readQueryUuids. Keyed by
       // name, because a declaration has no file for a path-keyed map to hold.
-      collectionUuids: readCollectionUuids(siteDir),
+      queryUuids: readQueryUuids(siteDir),
       // Resolves a foundation-relative `@/x` model ref into `@org/x`.
       ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
@@ -509,14 +519,14 @@ export async function push(args = [], deps = {}) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
   }
-  const { siteContent, collections, siteContentUuid, warnings, skipped } = pkg
+  const { siteContent, records, siteContentUuid, warnings, skipped } = pkg
   log('')
   for (const w of warnings) note(`! ${w}`)
   // Warn level, not dim: this is the author choosing entities vs static files.
-  reportSchemalessCollections(pkg.schemaless, { warn, dim: note })
+  reportSchemalessQueries(pkg.schemaless, { warn, dim: note })
 
   const totalEntities =
-    (siteContent?.entityCount || 0) + (collections?.entityCount || 0)
+    (siteContent?.entityCount || 0) + (records?.entityCount || 0)
 
   // Nothing changed since the last push — the backend is already up to date.
   if (totalEntities === 0) {
@@ -529,10 +539,10 @@ export async function push(args = [], deps = {}) {
     info(
       `${colors.bright}site-content${colors.reset} → ${siteContent.models.join(', ')}`
     )
-  if (collections) {
-    const n = collections.entityCount
+  if (records) {
+    const n = records.entityCount
     info(
-      `${colors.bright}collections${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${collections.models.join(', ')}`
+      `${colors.bright}records${colors.reset} (${n} entit${n === 1 ? 'y' : 'ies'}) → ${records.models.join(', ')}`
     )
   }
   if (skipped) note(`${skipped} unchanged, skipped`)
@@ -542,11 +552,11 @@ export async function push(args = [], deps = {}) {
     const base = output.replace(/\.uwx$/, '')
     if (siteContent)
       writeFileSync(resolve(`${base}.site-content.uwx`), siteContent.buffer)
-    if (collections)
-      writeFileSync(resolve(`${base}.collections.uwx`), collections.buffer)
+    if (records)
+      writeFileSync(resolve(`${base}.records.uwx`), records.buffer)
     const lanes = [
       siteContent && 'site-content',
-      collections && 'collections'
+      records && 'records'
     ].filter(Boolean)
     success(`Wrote ${lanes.join(' + ')} .uwx — not submitted`)
     return { exitCode: 0 }
@@ -558,7 +568,7 @@ export async function push(args = [], deps = {}) {
         `Dry run — would ${verb} content at ${colors.dim}${client.origin}${colors.reset}`
       )
     }
-    if (collections) {
+    if (records) {
       info(
         `Dry run — would push the folder at ${colors.dim}${client.origin}${colors.reset}`
       )

package/src/commands/validate.js

@@ -269,7 +269,7 @@ export async function validate(args = []) {
     return { exitCode: 0 }
   }
 
-  // The data pipeline (collectSiteContent / processCollections) prints progress
+  // The data pipeline (collectSiteContent / processQueries) prints progress
   // via console.log. Route that to stderr while the engine runs so stdout stays
   // clean — pure JSON for `--json`, just the report otherwise. `log` captured
   // the original stdout writer at module load, so our own output is unaffected.

package/src/framework-index.json

@@ -1,9 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-28T23:49:23.885Z",
+  "generatedAt": "2026-08-31T13:37:55.117Z",
   "packages": {
+    "@uniweb/api": {
+      "version": "0.1.0",
+      "path": "framework/api",
+      "deps": [
+        "@uniweb/core"
+      ]
+    },
     "@uniweb/build": {
-      "version": "0.29.1",
+      "version": "0.30.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -27,7 +34,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.13.1",
+      "version": "0.14.1",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -40,14 +47,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.4",
+      "version": "0.4.5",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.14.0",
+      "version": "0.15.0",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -66,7 +73,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.5.1",
+      "version": "0.5.2",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -74,7 +81,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.13.1",
+      "version": "0.13.3",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -102,7 +109,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.10.0",
+      "version": "0.11.0",
       "path": "framework/templates",
       "deps": []
     },
@@ -112,7 +119,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.16",
+      "version": "0.8.17",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -814,10 +814,45 @@ async function main() {
     const originFlag =
       readFlagValue(loginArgs, '--backend') ||
       readFlagValue(loginArgs, '--registry')
-    await runRegistryLogin({
-      apiBase: resolveBackendOrigin(originFlag),
-      args: loginArgs
-    })
+    const apiBase = resolveBackendOrigin(originFlag)
+
+    // ⭐ The project says where it belongs — say so BEFORE authenticating elsewhere.
+    //
+    // `login` is deliberately NOT given the `site.yml::$backend` tier the site verbs
+    // get (see resolveBackendOrigin): the session it writes is machine-wide, so letting
+    // cwd pick the account you log into would be a silent surprise. But staying silent
+    // does not remove the failure, it MOVES it — you log into the default, and the next
+    // push/pull/publish resolves to `$backend` and warns about the mismatch. That is the
+    // routed-not-nagged case `$backend` was added for, missing at the one command a
+    // teammate runs FIRST after cloning.
+    //
+    // ⛔ Silent when the origin was named explicitly (--backend / --registry /
+    // UNIWEB_REGISTER_URL). A deliberate aim is not a mistake to warn about; a genuinely
+    // wrong one is still caught by the session-mismatch guard in BackendClient.token().
+    if (!originFlag && !process.env.UNIWEB_REGISTER_URL) {
+      try {
+        const { findNearbySiteBackend } = await import(
+          './utils/site-identity.js'
+        )
+        const nearby = findNearbySiteBackend(process.cwd())
+        if (nearby && nearby.backend !== apiBase) {
+          console.error(
+            `\x1b[33m⚠\x1b[0m This project syncs with ${nearby.backend} (site.yml::$backend), but login is targeting ${apiBase}.`
+          )
+          console.error(
+            `  Log in where the project belongs:  uniweb login --backend ${nearby.backend}`
+          )
+          console.error(
+            `  Continuing with ${apiBase} — a session is machine-wide, so this is a heads-up, not a block.\n`
+          )
+        }
+      } catch {
+        // Advisory only. A malformed site.yml, an unreadable directory or anything else
+        // here must never be the reason someone cannot log in.
+      }
+    }
+
+    await runRegistryLogin({ apiBase, args: loginArgs })
     return
   }
 

package/src/utils/flag-guard.js

@@ -77,12 +77,12 @@ const VERBS = {
   pull: [
     '--backend', '--content-only', '--dry-run', '--force', '--merge',
     '--no-assets',
-    '--no-collections', '--no-delete', '--no-prune', '--registry', '--token',
+    '--no-records', '--no-delete', '--no-prune', '--registry', '--token',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
     '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
-    '--backend', '--content-only', '--no-assets', '--no-collections', '--path',
+    '--backend', '--content-only', '--no-assets', '--no-records', '--path',
     '--project', '--registry', '--token', '--org', '--as-org'
   ],
   register: [

package/src/utils/git.js

@@ -32,11 +32,17 @@ import yaml from 'js-yaml'
  * rather than assuming the defaults.
  */
 export function siteContentRoots(siteDir) {
+  // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
+  // Its predecessor lived at `collections/collections.yml`, so the `collections`
+  // root added below already covered it and the bare `'collections.yml'` entry
+  // that used to sit in this list resolved to a path no site ever had. A
+  // root-level file has no directory entry standing in for it.
   const roots = new Set([
     'site.yml',
     'theme.yml',
     'head.html',
-    'collections.yml',
+    'queries.yml',
+    'records.yml',
     'locales'
   ])
   let paths = {}
@@ -48,7 +54,7 @@ export function siteContentRoots(siteDir) {
   }
   roots.add(paths.pages || 'pages')
   roots.add(paths.layout || 'layout')
-  roots.add(paths.collections || 'collections')
+  roots.add(paths.entities || 'entities')
   return [...roots]
 }
 

package/src/utils/records-guard.js

@@ -0,0 +1,80 @@
+// ⛔ THE ONE PLACE AN ORDINARY ACT IS DESTRUCTIVE.
+//
+// `records.yml` is the sync control, and `missing` and `empty` deliberately mean
+// different things: missing leaves the server's folder untouched, empty says the
+// folder holds nothing and the backend removes what is there. The asymmetry is
+// well-shaped — the safe state is the ABSENCE of a file, so a live folder cannot
+// be wiped by deleting one, and the destructive act requires affirmatively
+// creating one.
+//
+// ⚠️ WHICH LEAVES EXACTLY ONE SHARP EDGE: a PLACEHOLDER. Someone creates an empty
+// `records.yml` intending to fill it in, pushes, and the live folder empties.
+// That is plausible and it is the only path where a normal act destroys content.
+//
+// ⭐ THE FORMAT STAYS HONEST AND THE CLI DOES THE ASKING. Never make "empty" mean
+// "missing" to dodge this: that would delete a capability to avoid writing a
+// prompt.
+//
+// The count comes from the placement identity a previous push banked — what WE
+// last saw the folder hold. It needs no network call, and it is the right source:
+// a site that has never pushed has nothing to lose and is never asked.
+
+import { readRecordsConfig, FOLDER_EMPTY } from '@uniweb/build/uwx'
+import { readFolderItemUuids } from '../backend/site-sync.js'
+import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
+
+/**
+ * Leaf placements in a banked path→uuid map.
+ *
+ * A branch's path is a prefix of every path beneath it, so anything that is a
+ * prefix of another key is a folder rather than a record. Counting raw keys would
+ * report a two-record site inside one folder as three things to lose.
+ */
+export function countPlacedRecords(pathToUuid) {
+  const paths = Object.keys(pathToUuid || {})
+  return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(`${p}/`))).length
+}
+
+/**
+ * Stop an empty `records.yml` from silently emptying a live folder.
+ *
+ * @param {object} params
+ * @param {string} params.siteDir
+ * @param {string[]} params.args - the verb's argv, for --yes / non-interactive
+ * @param {(m: string) => void} params.warn - the CALLER's reporter. Each verb owns
+ *        its own output style; a second copy here would drift from all of them.
+ * @param {(m: string) => void} params.note
+ * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
+ */
+export async function guardEmptyRecords({ siteDir, args = [], warn, note }) {
+  const cfg = await readRecordsConfig(siteDir)
+  if (cfg.state !== FOLDER_EMPTY) return { ok: true, count: 0 }
+
+  const count = countPlacedRecords(readFolderItemUuids(siteDir))
+  // Nothing banked ⇒ nothing this push can remove. A first push of an empty
+  // folder is a legitimate (if odd) thing to do, and asking about it would train
+  // people to type y.
+  if (count === 0) return { ok: true, count: 0 }
+
+  warn(
+    `records.yml is empty, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the live folder.`
+  )
+  note(
+    'An empty records.yml means "the folder holds nothing" — it is not the same as ' +
+      'having no records.yml, which leaves the live folder alone. If you meant to ' +
+      'start listing records, delete the file until you have.'
+  )
+
+  // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
+  // would have been caught by `flag-guard-coverage.test.js` — which it was.
+  if (args.includes('--yes')) return { ok: true, count }
+  if (isNonInteractive(args)) {
+    warn(`Refusing to remove ${count} record${count === 1 ? '' : 's'} without confirmation.`)
+    note(`Re-run with --yes if that is what you want: ${getCliPrefix()} push --yes`)
+    return { ok: false, count }
+  }
+
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the live folder?`, false)
+  return { ok: yes, count }
+}

package/src/utils/schemaless-report.js

@@ -1,5 +1,5 @@
 /**
- * Report collections publishing without a data schema.
+ * Report queries publishing without a data schema.
  *
  * ⭐ This is a PRODUCT decision the author is making, usually without knowing:
  * entities or static files. It is reported at warn level for that reason — the
@@ -14,10 +14,10 @@
  * @param {Array<{name: string, model?: string}>} schemaless
  * @param {{ warn: (m: string) => void, dim: (m: string) => void }} out
  */
-export function reportSchemalessCollections(schemaless, out) {
+export function reportSchemalessQueries(schemaless, out) {
   if (!schemaless?.length) return
   const names = schemaless.map((c) => c.name)
-  const label = names.length === 1 ? 'collection' : 'collections'
+  const label = names.length === 1 ? 'query' : 'queries'
   out.warn(
     `${names.length} ${label} shipping as STATIC FILES, not entities: ${names.join(', ')}`
   )
@@ -25,6 +25,6 @@ export function reportSchemalessCollections(schemaless, out) {
   out.dim(
     `Declare a data schema to get entities. Each resolves its schema by subfolder name (${schemaless
       .map((c) => `${c.name} → ${c.model || c.name}`)
-      .join(', ')}), or set \`schema:\` on the collection.`
+      .join(', ')}), or set \`schema:\` on the query.`
   )
 }

package/src/utils/site-data-upload.js

@@ -1,7 +1,7 @@
 /**
  * Static collection data — the passthrough lane.
  *
- * A site's **schema-less** collections have no entity model, so their compiled
+ * A site's **schema-less** queries have no entity model, so their compiled
  * `dist/data/**` JSON is delivered as files rather than synced as entities.
  * This plans and uploads that set: one plan call, one object per file, each
  * PUT to the target the backend returns.
@@ -93,7 +93,7 @@ export async function uploadSiteData({
       //
       // ⛔ And the failure is INVISIBLE from here: the plan succeeds, the PUT
       // succeeds, and only a visitor's fetch 404s. Confirmed against the
-      // shipped contract's own example (`collections/articles.json` with a
+      // shipped contract's own example (`data/articles.json` with a
       // `/data/`-bearing `serve_base`), which supersedes an earlier
       // parenthetical that showed the prefix.
       path: relPath,

package/src/utils/site-identity.js

@@ -28,8 +28,8 @@
  * 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 { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { DEFAULT_BACKEND_ORIGIN } from './config.js'
 
@@ -232,3 +232,66 @@ export function assertSiteBackendScope(siteDir, origin) {
     hint
   }
 }
+
+/**
+ * The `$backend` of the site project `startDir` sits in — for verbs that are NOT site
+ * verbs and so never resolve a site directory of their own.
+ *
+ * ⛔ **This does NOT feed the origin ladder, deliberately.** `login` writes a
+ * MACHINE-WIDE session (`~/.uniweb/registry-auth.json`), not a per-project one, so
+ * letting whichever directory you happen to stand in decide which backend you
+ * authenticate against would be a silent surprise — the same class of surprise
+ * `$backend` exists to remove. What this enables is a **notice**: the project says
+ * where it belongs, so we say so before authenticating somewhere else.
+ *
+ * ⭐ **Conservative by construction — it answers only when there is exactly ONE
+ * candidate.** A workspace of several sites has no single answer, and a confident
+ * *"did you mean localhost?"* aimed at the wrong one of three sites is worse than
+ * saying nothing. Ambiguity returns null and the caller stays quiet.
+ *
+ * ⚠️ Build-free, like everything else in this file — `login` is a STANDALONE command
+ * that must work outside a project, where `@uniweb/build` is not installed. That is why
+ * this cannot reuse `resolveSiteDir` (`commands/deploy.js`), which pulls build in.
+ *
+ * @param {string} startDir
+ * @returns {{ siteDir: string, backend: string }|null}
+ */
+export function findNearbySiteBackend(startDir) {
+  // 1. Walk UP for the site we are standing in or under. Bounded: a `site.yml` more
+  //    than a few levels above is not "the project you are in", it is a coincidence,
+  //    and at the filesystem root it would be someone else's entirely.
+  let dir = startDir
+  for (let i = 0; i < 4; i++) {
+    if (existsSync(join(dir, 'site.yml'))) {
+      const { backend } = readSiteIdentity(dir)
+      return backend ? { siteDir: dir, backend } : null
+    }
+    const up = dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+
+  // 2. Standing AT a project root, the site is one level down — `site/` in the default
+  //    layout, or a lone entry under `sites/`. Two or more candidates is a workspace,
+  //    which is exactly the ambiguity above.
+  const candidates = []
+  if (existsSync(join(startDir, 'site', 'site.yml')))
+    candidates.push(join(startDir, 'site'))
+  const sitesDir = join(startDir, 'sites')
+  if (existsSync(sitesDir)) {
+    let entries = []
+    try {
+      entries = readdirSync(sitesDir, { withFileTypes: true })
+    } catch {
+      entries = []
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const d = join(sitesDir, e.name)
+      if (existsSync(join(d, 'site.yml'))) candidates.push(d)
+    }
+  }
+  if (candidates.length !== 1) return null
+  const { backend } = readSiteIdentity(candidates[0])
+  return backend ? { siteDir: candidates[0], backend } : null
+}