uniweb 0.70.0 → 0.70.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.70.0",
+  "version": "0.70.2",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,16 +42,16 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/core": "^0.30.0",
-    "@uniweb/runtime": "^0.27.5",
+    "@uniweb/runtime": "^0.27.6",
     "@uniweb/kit": "^0.19.5",
-    "@uniweb/schemas": "^0.7.0",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/core": "^0.30.1",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.7.2"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.64.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/build": "^0.64.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/backend/client.js

@@ -74,10 +74,12 @@ export function resolveBackendOrigin() {
  * The fallback capability doc for when `GET /dev/config` was not asked for (no
  * credential in hand) or did not answer. Keeps the client non-breaking.
  *
- * ⭐ **It is EMPTY, and that is the accurate shape.** The CLI reads exactly one leaf of
- * that document — `delivery.siteSubscriptionRequired` — and its absence is meaningful:
- * unknown reads falsy, and the caller stays silent rather than claiming a deployment
- * does or does not charge. Every other key that used to sit here had no reader.
+ * ⭐ **It is EMPTY, and that is the accurate shape.** The CLI reads only that document's
+ * `siteContent` key lists — `queryFields`, `pageFields`, `settingsFields` — and their absence
+ * is meaningful: unknown means a push sends no optional key, which every deployment accepts,
+ * rather than claiming a deployment takes one. Every other key that used to sit here had no
+ * reader. *(The leaf named here was `delivery.siteSubscriptionRequired` until 2026-09-26; it
+ * went 2026-08-30.)*
  *
  * ⛔ **Do not restore a key "for completeness".** A default for a field nothing reads is
  * a reader waiting to happen, and it is how this file came to describe a client that
@@ -457,9 +459,12 @@ export class BackendClient {
    * were dropped because a serve location is read from the response that carries it
    * (`serve_base`, `serve_url`, `config.base`), never from a handshake; `auth.loginPath`
    * is not read either — the login path is a hardcoded constant
-   * (`utils/registry-auth.js`). What is actually consumed is ONE leaf —
-   * `delivery.siteSubscriptionRequired` — and nothing else. Do not add a reader for the
-   * rest: each one would be a second place a backend's layout is pinned.
+   * (`utils/registry-auth.js`). What is actually consumed is the key lists under
+   * `siteContent` — `queryFields`, `pageFields`, `settingsFields`, the keys the deployment's
+   * Sections declare (`site-sync.js::deploymentFields`) — which is policy, never an address. Do not
+   * add a reader for the rest: each one would be a second place a backend's layout is
+   * pinned. (This named `delivery.siteSubscriptionRequired` until 2026-09-26; that leaf
+   * went 2026-08-30.)
    *
    * @returns {Promise<object>}
    */
@@ -577,6 +582,32 @@ export class BackendClient {
     }
   }
 
+  /**
+   * GET /dev/site/foundation-schema/{site}/{@scope}/{name}/{version} → the registered version of a
+   * foundation a site uses, as the backend holds it: its `schema` (section types with their
+   * `data:`), `info`, `data_schemas` (names), `module_url` and `css_url`. Read through the SITE,
+   * which is the licence: the caller must be able to read the site, and the site must use the
+   * foundation. Null on a 404 (not registered, or not this site's) and on any failure — a caller
+   * degrades, since what it is read for can be done without it, less well.
+   * @param {string} siteUuid - the site-content uuid
+   * @param {string} ref - the catalog ref, `@scope/name@version`
+   * @returns {Promise<object|null>}
+   */
+  async readRegisteredFoundation(siteUuid, ref) {
+    const m = /^(@[^/]+)\/([^@/]+)@(.+)$/.exec(String(ref || ''))
+    if (!siteUuid || !m) return null
+    try {
+      const res = await this.request(
+        `/dev/site/foundation-schema/${encodeURIComponent(siteUuid)}/${m[1]}/${encodeURIComponent(m[2])}/${encodeURIComponent(m[3])}`
+      )
+      if (!res.ok) return null
+      const body = await res.json().catch(() => null)
+      return body && typeof body === 'object' && body.schema && typeof body.schema === 'object' ? body : null
+    } catch {
+      return null
+    }
+  }
+
   // ── Orgs ──────────────────────────────────────────────────────────────────────
 
   /** GET /dev/orgs → { account_handle, orgs[] }. */

package/src/backend/service-request.js

@@ -76,6 +76,11 @@ export function fingerprintDeclaration(declared) {
     .slice(0, 16)
 }
 
+/** Absent, or an empty list — a stored request that asks for nothing. */
+function isNothing(value) {
+  return value === undefined || value === null || (Array.isArray(value) && value.length === 0)
+}
+
 /** Deterministic JSON: object keys sorted at every depth, arrays left in order. */
 function stableString(value) {
   return JSON.stringify(value, (_k, v) =>
@@ -212,6 +217,12 @@ export function reconcile(localValue, remoteValue, baseFingerprint) {
   const base = baseFingerprint || null
 
   if (local === remote) return { action: 'none', local, remote }
+  // ⛔ A FILE THAT DECLARES NOTHING ASKS NOTHING, so it is never one side of a conflict. With
+  // nothing stored either — an empty list is the store's nothing — there is nothing to do; with
+  // something stored, the file is merely behind. Until 2026-09-26 this was a `conflict`, and the
+  // first publish of a site whose file is silent warned that its services "were changed
+  // elsewhere, and site.yml changed too", listing both as nothing.
+  if (local === null) return { action: isNothing(remoteValue) ? 'none' : 'adopt', local, remote }
   if (!base) return { action: 'conflict', local, remote }
 
   const localMoved = local !== base

package/src/backend/site-preview.js

@@ -0,0 +1,77 @@
+/**
+ * What `uniweb dev` asks the backend before previewing a site whose foundation is a catalog ref —
+ * every clone.
+ *
+ * Such a site has no build of its foundation, and a build does not turn a ref into a URL: where a
+ * version is served is the backend's to say. So the dev server is handed the backend's answer, read
+ * for it here through the site — the route push and pull read the version's section types from
+ * (`client.readRegisteredFoundation`) — and passed on in `UNIWEB_PREVIEW` (`@uniweb/build/site`'s
+ * `preview.js` has the contract). The backend it names is also where the site's kept media URLs are
+ * fetched from.
+ *
+ * ⛔ Nothing here is kept. The answer lives as long as the dev server: `site.yml` keeps the ref, and
+ * no file a push or pull reads gets the URL — the round trip never sees it.
+ *
+ * ⚠️ It may not be known. Whether a backend tells the CLI where a version is served is the backend's
+ * to decide, and may change, so an answer without a location is an ordinary outcome: the preview
+ * says so and does not start. Nothing else reads it — push, pull and publish work without it.
+ */
+import { readBackendState, parseCatalogRef } from '@uniweb/build/uwx'
+import { BackendClient } from './client.js'
+import { resolveWorkspace } from './workspace.js'
+import { readDeclaredFoundation } from '../utils/install-integrity.js'
+import { syncedBackends } from '../utils/site-identity.js'
+
+/**
+ * What the dev server of `siteDir` is handed, when its foundation is a catalog ref.
+ *
+ * @param {object} p
+ * @param {string} p.siteDir
+ * @param {string[]} [p.args]
+ * @param {BackendClient} [p.client] - injected in tests
+ * @returns {Promise<null
+ *   | { preview: { backend: string, foundation: { ref: string, url: string, cssUrl: string|null } } }
+ *   | { refused: string[] }>}
+ *   null when there is nothing to ask — the foundation is not a catalog ref
+ */
+export async function readSitePreview({ siteDir, args = [], client = null }) {
+  const ref = readDeclaredFoundation(siteDir)
+  if (!parseCatalogRef(ref)) return null
+
+  client = client || new BackendClient({ args, command: 'Previewing' })
+  const uuid = readBackendState(siteDir, client.origin).site?.uuid
+  if (!uuid) {
+    const known = syncedBackends(siteDir)
+    return {
+      refused: [
+        `This site's foundation is ${ref}, and the backend the site is on says where that version is served.`,
+        known.length
+          ? `The site is on ${known.join(', ')} — not on ${client.origin}, the backend you are logged in to. To preview it: uniweb login --backend <url>`
+          : `The site is on no backend yet: \`uniweb push\` puts it on ${client.origin}.`
+      ]
+    }
+  }
+
+  const ws = await resolveWorkspace({ client, args })
+  if (ws.refused) return { refused: ['A preview reads the site in one workspace, and none is chosen.', ws.reason] }
+  client.setWorkspace(ws.workspace, { source: ws.source })
+
+  const reply = await client.readRegisteredFoundation(uuid, ref)
+  const url = typeof reply?.module_url === 'string' && reply.module_url ? reply.module_url : null
+  if (!url) {
+    return {
+      refused: [
+        reply
+          ? `${client.origin} did not say where ${ref} is served, so this site cannot be previewed here.`
+          : `Could not read ${ref} through this site on ${client.origin}, so this site cannot be previewed here.`,
+        'Push, pull and publish do not need it.'
+      ]
+    }
+  }
+  return {
+    preview: {
+      backend: client.origin,
+      foundation: { ref, url, cssUrl: typeof reply.css_url === 'string' && reply.css_url ? reply.css_url : null }
+    }
+  }
+}

package/src/backend/site-sync.js

@@ -46,7 +46,10 @@ import {
   harvestRecordItems,
   storedRecordItems,
   reprintRecordItems,
-  matchStoredRecords
+  matchStoredRecords,
+  parseCatalogRef,
+  readRegisteredFoundation,
+  writeRegisteredFoundation
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -326,18 +329,46 @@ function changedSummary(finalized) {
 // 404 → null (the emitter then says "register it first"). The bearer is acquired lazily
 // by the client, so a fully-local sync never authenticates.
 //
-// `offline` (set for `-o` / `--dry-run`) forces every non-local Model to null WITHOUT
-// touching the backend — an offline emit must never authenticate.
-export function makeModelResolver({ client, offline = false }) {
+// `offline` (set for `-o` / `--dry-run`, and for `status`) never touches the backend — an
+// offline emit must never authenticate. It answers with the Models a push or a pull KEPT for
+// this backend (`keptModels`), or null. ⭐ With `siteDir`, an online read keeps each Model it
+// reads, per backend — so a clone, whose foundation is not in the project to declare them, can
+// still compare offline. ⛔ Until 2026-09-26 nothing was kept, and `uniweb status` in a clone
+// could not resolve a Model ("… could not be resolved").
+export function makeModelResolver({ client, offline = false, siteDir = null, backend = null }) {
+  const origin = backend ?? client?.origin ?? null
+  const kept = siteDir && origin ? keptModels(siteDir, origin) : {}
   const cache = new Map()
   return async (modelName) => {
     if (cache.has(modelName)) return cache.get(modelName)
-    const decl = offline ? null : await client.readDataSchema(modelName)
+    let decl
+    if (offline) {
+      decl = kept[modelName] ?? null
+    } else {
+      decl = await client.readDataSchema(modelName)
+      if (decl && siteDir && origin) keepModels(siteDir, origin, { [modelName]: decl })
+    }
     cache.set(modelName, decl)
     return decl
   }
 }
 
+/**
+ * The Models a push or a pull read from this backend, by name — kept in `.uniweb/backend-cache.json`
+ * so an offline emit resolves what an online one did. Regenerable: losing them costs `status` its
+ * comparison until the next push or pull, never a wrong answer.
+ */
+export function keptModels(siteDir, backend) {
+  const models = readSyncCacheFile(siteDir, backend).models
+  return models && typeof models === 'object' ? models : {}
+}
+
+/** Keep Models read from this backend, beside the ones already kept. */
+export function keepModels(siteDir, backend, models) {
+  if (!models || !Object.keys(models).length) return
+  updateSyncCache(siteDir, backend, { models: { ...keptModels(siteDir, backend), ...models } })
+}
+
 // `.uniweb/backend-cache.json` — what a backend had and what we last sent it, so the
 // next transfer can skip work. Gitignored, per clone, safe to delete.
 //
@@ -653,6 +684,55 @@ export function readAppliedInjections(siteDir, backend) {
   return readMap(siteDir, backend, 'applied')
 }
 
+/**
+ * ⭐ THE REGISTERED FOUNDATION A CLONE KEEPS. A site whose foundation is a catalog ref has no build of
+ * it in the project, and the section types' `data:` it declares are what type a query named for a
+ * data key — `team:` read as `@acme/member` (`typed_by_data_key`). Read once from the backend,
+ * through the site, and kept under `.uniweb/` (`@uniweb/build`'s `registered-foundation.js`), where
+ * the build, the push and the pull read it; a registered version never changes, so a kept copy is
+ * never read again.
+ *
+ * Null when the foundation is not a catalog ref, the site is not on this backend yet, or the read
+ * fails: nothing is then typed by it — a pull writes such a query's schema out, and a push sends
+ * what that says — so both go on.
+ */
+export async function ensureRegisteredFoundation({ client, siteDir, siteUuid, ref }) {
+  if (!parseCatalogRef(ref)) return null
+  const kept = readRegisteredFoundation(siteDir, ref)
+  if (kept) return kept
+  const reply = siteUuid ? await client.readRegisteredFoundation(siteUuid, ref) : null
+  if (!reply) return null
+  // ⛔ ONLY WHAT WE READ — the section types. The reply carries more than we asked for, a serve
+  // location among it, and a serve location is decided at publish and read from the response that
+  // carries it, never kept. Until 2026-09-26 the whole reply was kept.
+  const sectionTypes = { schema: reply.schema }
+  writeRegisteredFoundation(siteDir, ref, sectionTypes)
+  return sectionTypes
+}
+
+// The Sections whose declared keys a push reads before it sends an optional one.
+const DEPLOYMENT_FIELD_LISTS = ['queryFields', 'pageFields', 'settingsFields']
+
+/**
+ * The keys this deployment's `queries`, page and `settings` Sections declare, as it says so itself —
+ * `GET /dev/config` → `siteContent.queryFields` / `pageFields` / `settingsFields` — so a push sends
+ * an optional key only to a deployment that takes it (`typed_by_data_key`; `og_title` and
+ * `og_description`): one that does not declare a key refuses a push carrying it. Offline — a dry
+ * run, `--output` — the lists the last push to this backend banked, so the package is the one that
+ * push would build.
+ *
+ * Only the lists in hand are returned, as emit options: with none, nothing optional is sent, which
+ * every deployment accepts.
+ */
+export async function deploymentFields({ client, siteDir, offline = false }) {
+  const source = offline
+    ? readAppliedInjections(siteDir, client.origin)
+    : (await client.discover())?.siteContent
+  const out = {}
+  for (const name of DEPLOYMENT_FIELD_LISTS) if (Array.isArray(source?.[name])) out[name] = source[name]
+  return out
+}
+
 /**
  * Bank the content hashes and the injections that produced them. ⛔ ONE call, both
  * maps: they describe the same document, so writing either alone leaves the cache
@@ -1430,7 +1510,7 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
  */
 async function comparisonEmit(
   siteDir,
-  { backend = null, priorHashes = {}, sendAll = false, declarations = null } = {}
+  { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null } = {}
 ) {
   const applied = readAppliedInjections(siteDir, backend)
   // ⛔ Per backend: an asset id is minted by one and means nothing to another, so a
@@ -1446,10 +1526,13 @@ async function comparisonEmit(
     // of its Models here, and nothing is banked.
     resolveModel: declarations
       ? async (name) => declarations.get(name) ?? null
-      : makeModelResolver({ client: null, offline: true }),
+      : makeModelResolver({ client: null, offline: true, siteDir, backend }),
     priorHashes,
     sendAll,
     ...applied,
+    // The deployment's own answer (`deploymentFields`), when the caller has just read it, over what
+    // the last push banked.
+    ...(fields || {}),
     ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
     ...(Object.keys(assetIds).length ? { assetIds } : {})
     // ⛔ No `org`: a site's `@/x` refs resolve into its FOUNDATION's scope, which the
@@ -1484,9 +1567,12 @@ async function comparisonEmit(
  * @param {Map<string,object>} [opts.declarations] - the Models the pull read, by name — so a
  *        site whose foundation is not in the project (a clone's) can be re-banked offline
  */
-export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations } = {}) {
-  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations })
-  writeSyncCache(siteDir, backend, pkg.hashes || {}, pkg.applied || {})
+export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, declarations, fields = null } = {}) {
+  // ⛔ With the keys this deployment's Sections take, when the caller has them (`deploymentFields`):
+  // they shape the document the next push sends (`typed_by_data_key`, `og_title`), so a hash banked
+  // without them marks a clone's first push as changed. Until 2026-09-26 a pull banked none.
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields })
+  writeSyncCache(siteDir, backend, onlyWhatThePullTook(siteDir, backend, pkg, recordDocs), pkg.applied || {})
   // ⭐ And the identity of the records' list items, from the documents the pull just took:
   // the files it wrote hold the stored items in stored order, so the emit over them pairs
   // with each document item for item.
@@ -1505,6 +1591,44 @@ export async function rebankSyncHashes(siteDir, backend = null, { recordDocs, de
   return Object.keys(pkg.hashes || {}).length
 }
 
+/**
+ * The hashes a pull may bank: the tree's, except for a record the pull did not take.
+ *
+ * ⛔ ONLY WHAT CAME FROM THE BACKEND IS AGREED. A record on disk that the backend did not
+ * hand back — written since the last push, or one a push had refused — is not in sync
+ * because a pull ran. Until 2026-09-26 it was banked with the rest, so every later push
+ * skipped it and `uniweb status` said "in sync": a record written before a `uniweb sync`
+ * (which pulls, then pushes) never reached the backend. One this backend never accepted —
+ * no identity from it — is always sent: a hash it has banked can only be that mistake's.
+ * One it did accept keeps what the last push banked. The folder keeps its hash too while
+ * it places such a record. A pull that took no records (`--no-records`, a 304) leaves
+ * every record's hash as it was.
+ *
+ * @param {object[]|undefined} recordDocs - the record documents the pull took
+ */
+function onlyWhatThePullTook(siteDir, backend, pkg, recordDocs) {
+  const hashes = { ...(pkg.hashes || {}) }
+  const prior = readSyncCache(siteDir, backend)
+  const keep = (key) => {
+    if (Object.hasOwn(prior, key)) hashes[key] = prior[key]
+    else delete hashes[key]
+  }
+  const taken = new Set((recordDocs || []).map((d) => d?.$uuid).filter(Boolean))
+  const recordUuids = readBackendState(siteDir, backend).records || {}
+  let notTaken = 0
+  for (const entry of pkg.records?.index || []) {
+    if (entry.kind === 'folder') continue // the folder itself — held below while it places one
+    const theirs = entry.ownId ? recordUuids[entry.ownId] : null
+    if (theirs && taken.has(theirs)) continue
+    notTaken++
+    const key = `${entry.model} ${entry.id}`
+    if (theirs) keep(key)
+    else delete hashes[key]
+  }
+  if (notTaken) for (const key of Object.keys(hashes)) if (key.startsWith('@uniweb/folder ')) keep(key)
+  return hashes
+}
+
 /**
  * Re-bank the hashes of the records a push sent naming a record it created — `keys`,
  * the emit's `namesNew` — as the next push will hash them, and fingerprint their list
@@ -1714,6 +1838,18 @@ export async function pushSyncPackages({
         if (problem.detail) note(String(problem.detail))
         return null
       }
+      // ⭐ A RECORD KEEPS ITS TYPE. A record file moved to another type's folder keeps its `$uuid`, and
+      // the backend refuses it as that type (`type_changed`, naming the record and both types), before
+      // writing anything. Storing it as the new type makes it a new record.
+      if (problem?.reason === 'type_changed') {
+        error(`${label} push refused — a stored record would change its type.`)
+        if (problem.detail) note(String(problem.detail))
+        note(
+          'A record keeps its type. To store it as the new type, make it a new record: delete the ' +
+            '`$uuid` line from its file, then push again.'
+        )
+        return null
+      }
       if (problem?.reason === 'stale_base') {
         error(
           `${label} push refused — the backend has newer content than your last pull.`
@@ -1798,15 +1934,14 @@ export async function pushSyncPackages({
           `  deleted there  →  uniweb forget --backend ${client.origin}, then push again: it creates a NEW site`
         )
         note('Deleting this folder removes only your local copy, either way.')
-      } else if (res.status === 409) {
-        // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
-        // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
-        note(
-          "This site's record structure is already established on the backend and can't be changed " +
-            'in place — e.g. adding or removing a schema-backed query, or switching one between ' +
-            'static (data-bundle) and schema-backed delivery. To change it, push it as a new site: ' +
-            `uniweb forget --backend ${client.origin}, then push again (the old site stays until it is deleted).`
-        )
+      } else if (res.status === 409 && (problem?.title || problem?.detail)) {
+        // ⛔ A 409 names its own cause — a reference the store refuses, a rule of the record's type,
+        // an append-only section — so it is shown as the backend put it, not explained by us. Until
+        // 2026-09-26 every one was explained as "this site's record structure is already established
+        // … push it as a new site", a rule the backend no longer has, and it misled over a refused
+        // reference. (`stale_base` and `item_uuid_conflict` have their own explanations, above.)
+        note([problem.title, problem.detail].filter(Boolean).join(' — '))
+        return null
       }
       if (body) note(body.slice(0, 800))
       return null

package/src/commands/clone.js

@@ -426,6 +426,12 @@ export async function clone(args = [], deps = {}) {
 
   const pullExtra = []
   if (noRecords) pullExtra.push('--no-records')
+  // The workspace this clone was told to work in: the pull is another process, and asks the same
+  // question. ⛔ Until 2026-09-26 it was not told, so it used the login's — or, with none chosen,
+  // refused: "none is chosen". A workspace from the login or the environment reaches it by itself.
+  const orgFlag = flagValue(args, '--org')
+  if (orgFlag) pullExtra.push('--org', orgFlag)
+  if (args.includes('--personal')) pullExtra.push('--personal')
 
   if (deps.skipPull) {
     note('Skipping pull (test mode).')

package/src/commands/dev.js

@@ -24,6 +24,14 @@
  * site by default (mirrors the `pnpm dev` shortcut `uniweb create` writes).
  * Use `--site` to pick a different one without editing the root scripts.
  *
+ * A site whose foundation is a catalog ref — every clone — has no build of it, and
+ * only the backend the site is on can say where that version is served. So `dev`
+ * asks it, through the site, and hands the answer to the dev server it starts in its
+ * environment (`UNIWEB_PREVIEW`), with the backend it asked, which is also where the
+ * site's kept media URLs are fetched from. Nothing is written: `site.yml` keeps the
+ * ref and the round trip never sees the URL. A backend that does not say is an
+ * ordinary answer — `dev` says so and starts nothing (`backend/site-preview.js`).
+ *
  * Implementation: shells out to the package manager that invoked the CLI
  * (detected via npm_config_user_agent), running the workspace-filtered
  * dev command (`pnpm --filter <name> dev` or `npm -w <name> run dev`).
@@ -121,12 +129,32 @@ export async function dev(args = []) {
   const [bin, ...rest] = command.split(' ')
   const sitePath = join(rootDir, site.path)
 
+  // ⭐ A SITE WHOSE FOUNDATION IS A CATALOG REF — a clone — is previewed with what the backend
+  // it is on says: where that version is served. Asked here, for this dev server alone, and
+  // handed to it in its environment; nothing is written (`backend/site-preview.js`). Any other
+  // site needs nothing from a backend, and this asks nothing.
+  const { readSitePreview } = await import('../backend/site-preview.js')
+  const asked = await readSitePreview({ siteDir: sitePath, args })
+  if (asked?.refused) {
+    console.error(`${RED}✗${RESET} ${asked.refused[0]}`)
+    for (const line of asked.refused.slice(1)) console.error(`  ${line}`)
+    process.exit(1)
+  }
+  let env = process.env
+  if (asked?.preview) {
+    const { PREVIEW_ENV, encodePreview } = await import('@uniweb/build/site')
+    env = { ...process.env, [PREVIEW_ENV]: encodePreview(asked.preview) }
+    console.error(
+      `${DIM}→ Previewing with ${asked.preview.foundation.ref}, served by ${asked.preview.backend}${RESET}`
+    )
+  }
+
   console.error(
     `${DIM}→ ${command}${RESET} ${DIM}(site: ${site.name}, dir: ${sitePath})${RESET}`
   )
   console.error('')
 
-  const child = spawn(bin, rest, { cwd: rootDir, stdio: 'inherit' })
+  const child = spawn(bin, rest, { cwd: rootDir, stdio: 'inherit', env })
   child.on('close', (code) => process.exit(code ?? 0))
   child.on('error', (err) => {
     console.error(`${RED}✗${RESET} Failed to start dev server: ${err.message}`)

package/src/commands/publish.js

@@ -87,6 +87,8 @@ import {
   ensureItemUuids,
   readFolderItemUuids,
   readRecordItemUuids,
+  deploymentFields,
+  ensureRegisteredFoundation,
   recoverUnbankedIdentity,
   ensureSiteExists,
   refuseUnsendableRecords,
@@ -339,9 +341,11 @@ export async function publish(args = []) {
   // (2026-08-30). Restoring a reader for it would re-create a check that cannot fail
   // while implying a capability that was never negotiable.
   //
-  // Discovery is not consulted on this path at all. The one leaf the CLI still reads
-  // (`delivery.siteSubscriptionRequired`) is read after the site create, where a
-  // credential is already in hand.
+  // Discovery is not consulted for a gate: the CLI reads the key lists under `siteContent`
+  // (`queryFields`, `pageFields`, `settingsFields`), which say what the push below may SEND
+  // (`deploymentFields`), never whether to publish. (`delivery.siteSubscriptionRequired`
+  // was deleted 2026-08-30; this said it was still read, after the site create, until
+  // 2026-09-26.)
 
   // ⛔ NOTHING about a runtime is sent from here. `site.yml::runtime` was a
   // vestigial prop and is no longer read [Diego, 2026-08-22]; `?runtime=` is no
@@ -550,7 +554,7 @@ export async function publish(args = []) {
   }
 
   // Non-local @std/registry Model schemas resolve through the backend (same as push).
-  const resolveModel = makeModelResolver({ client, offline: false })
+  const resolveModel = makeModelResolver({ client, offline: false, siteDir })
 
   // ⛔ 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
@@ -961,8 +965,19 @@ export async function publish(args = []) {
   // edited since this clone last synced, the push is refused rather than
   // overwriting them, and nothing goes live. `--force` drops the precondition.
   const forced = args.includes('--force')
+  const fields = await deploymentFields({ client, siteDir })
+  // A foundation named by catalog ref — a clone's: its kept registered version types a query named
+  // for a data key (`ensureRegisteredFoundation`).
+  await ensureRegisteredFoundation({
+    client,
+    siteDir,
+    siteUuid: readBackendState(siteDir, client.origin).site?.uuid,
+    ref: siteYml?.foundation
+  })
   const emitOptions = {
     backend: client.origin,
+    // The keys this deployment's Sections take — see deploymentFields.
+    ...fields,
     ...(declaration.declare ? {} : { declareServices: false }),
     // Placement identity for the folder — see writeFolderItemUuids.
     folderItemUuids: readFolderItemUuids(siteDir, client.origin),

package/src/commands/pull.js

@@ -60,7 +60,9 @@ import {
   writeFileSync,
   mkdirSync,
   mkdtempSync,
-  rmSync
+  rmSync,
+  readdirSync,
+  statSync
 } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { createHash } from 'node:crypto'
@@ -87,6 +89,8 @@ import {
 } from '../utils/pull-written.js'
 import {
   makeModelResolver,
+  ensureRegisteredFoundation,
+  deploymentFields,
   rebankSyncHashes,
   writeQueryUuids,
   mergeBaseVersions,
@@ -427,6 +431,27 @@ function readManifestTokens(buf) {
  * @param {object} [deps] - injectable seams for testing: `fetch` (default global
  *   fetch), `resolveSiteDir`, `getToken` (skip auth).
  */
+// Every file under `roots` (site-relative paths, files or directories), site-relative.
+function filesUnder(siteDir, roots) {
+  const out = []
+  const walk = (rel) => {
+    const abs = join(siteDir, rel)
+    let stat
+    try {
+      stat = statSync(abs)
+    } catch {
+      return
+    }
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(abs)) walk(join(rel, name))
+    } else if (stat.isFile()) {
+      out.push(rel)
+    }
+  }
+  for (const root of roots) walk(root)
+  return out
+}
+
 /**
  * Refuse a pull that would overwrite unsaved work. Returns a result object to
  * return from `pull`, or null to proceed.
@@ -440,7 +465,12 @@ async function checkWorkingTree(siteDir, args) {
   let dirty = uncommittedUnder(siteDir, roots)
 
   if (dirty === null) {
-    // Not a git work tree. Nothing to fall back on if this goes wrong.
+    // Not a git work tree. Nothing to fall back on if this goes wrong — unless nothing here is the
+    // author's: every file under pull's roots is one a pull, or the clone that made this site, wrote
+    // and nothing has changed since (`pull-written.js`). ⛔ Until 2026-09-26 a fresh clone's own pull,
+    // which runs with no terminal to ask, refused here, and `uniweb clone` could not finish.
+    const written = readWritten(siteDir)
+    if (filesUnder(siteDir, roots).every((f) => isPullOutput(siteDir, f, written))) return null
     if (isNonInteractive(args)) {
       error('Refusing to pull: this site is not in a git repository.')
       note(
@@ -685,7 +715,7 @@ export async function pull(args = [], deps = {}) {
     command: 'Pulling'
   })
   // One reader of Models for the whole pull, so a Model is read once whichever lane asks first.
-  const readModel = makeModelResolver({ client })
+  const readModel = makeModelResolver({ client, siteDir })
 
   // ⭐ 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
@@ -957,6 +987,11 @@ export async function pull(args = [], deps = {}) {
           // unreadable here
         }
       }
+      // A foundation named by catalog ref — a clone's: keep its registered version before the
+      // queries are written, since its section types are what type a query named for a data key.
+      if (!keepAuthoredFoundation) {
+        await ensureRegisteredFoundation({ client, siteDir, siteUuid: siteContentUuid, ref: siteDoc?.info?.foundation })
+      }
       const report = siteContentDocumentToProject({
         document: siteDoc,
         siteRoot: siteDir,
@@ -1128,7 +1163,8 @@ export async function pull(args = [], deps = {}) {
       }
       await rebankSyncHashes(siteDir, client.origin, {
         recordDocs: pulledRecordDocs,
-        ...(declarations.size ? { declarations } : {})
+        ...(declarations.size ? { declarations } : {}),
+        fields: await deploymentFields({ client, siteDir })
       })
     } catch (err) {
       note(`! could not re-bank the sync cache: ${err.message}`)

package/src/commands/push.js

@@ -83,6 +83,8 @@ import {
   readFolderItemUuids,
   readQueryUuids,
   readRecordItemUuids,
+  deploymentFields,
+  ensureRegisteredFoundation,
   recoverUnbankedIdentity,
   ensureItemUuids,
   refuseUnsendableRecords,
@@ -405,7 +407,7 @@ export async function push(args = [], deps = {}) {
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir, client.origin),
         ...(foundationDir ? { foundationDir } : {}),
-        resolveModel: makeModelResolver({ client, offline: false })
+        resolveModel: makeModelResolver({ client, offline: false, siteDir })
       })
       mediaRefs = probe.localAssets || []
       refusals = probe.refusals || []
@@ -498,6 +500,21 @@ export async function push(args = [], deps = {}) {
     output || dryRun
       ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
+  const fields = await deploymentFields({
+    client,
+    siteDir,
+    offline: Boolean(output) || dryRun
+  })
+  // A foundation named by catalog ref — a clone's: its kept registered version types a query named
+  // for a data key (`ensureRegisteredFoundation`). Offline, only what is already kept.
+  if (!output && !dryRun) {
+    await ensureRegisteredFoundation({
+      client,
+      siteDir,
+      siteUuid: readBackendState(siteDir, client.origin).site?.uuid,
+      ref: siteYml?.foundation
+    })
+  }
   const emitOptions = {
     backend: client.origin,
     // Placement identity for the folder — see writeFolderItemUuids.
@@ -505,12 +522,15 @@ export async function push(args = [], deps = {}) {
     // 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, client.origin),
+    // The keys this deployment's Sections take — see deploymentFields.
+    ...fields,
     // Identity for the records' list items — see readRecordItemUuids.
     recordItemUuids: readRecordItemUuids(siteDir, client.origin),
     ...(foundationDir ? { foundationDir } : {}),
     resolveModel: makeModelResolver({
       client,
-      offline: Boolean(output) || dryRun
+      offline: Boolean(output) || dryRun,
+      siteDir
     }),
     priorHashes,
     sendAll,

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-26T17:05:22.846Z",
+  "generatedAt": "2026-09-27T03:02:47.415Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.3",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.64.0",
+      "version": "0.64.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -35,7 +35,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.30.0",
+      "version": "0.30.1",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -83,7 +83,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.27.5",
+      "version": "0.27.6",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -96,7 +96,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.7.0",
+      "version": "0.7.2",
       "path": "framework/schemas",
       "deps": []
     },