@uniweb/build 0.58.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/schemas": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/projections": "^0.7.3",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.3",
+    "@uniweb/content-reader": "^1.2.5",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.29.8",
-    "@uniweb/runtime": "^0.27.4"
+    "@uniweb/runtime": "^0.27.4",
+    "@uniweb/core": "^0.29.8"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation-name.js

@@ -17,6 +17,13 @@
 // ⛔ `package.json::uniweb.id` WAS A REGISTRY-NAME OVERRIDE, 2026-07-17 → 2026-09-21.
 // It is retired: the name lives in `main.js`, and two homes for one fact is how `push`
 // and `register` came to look the same foundation up under different names.
+//
+// ⭐ THE SCOPE IS PART OF THE NAME (2026-09-22 [Diego]) — `@acme/marketing` — so the
+// org a foundation registers under lives where the rest of its name does. A bare name
+// has no scope yet; `uniweb register` gives it one and writes it into `main.js`.
+// ⛔ `package.json::uniweb.scope` held it until then, a second home for half of one
+// fact, and the halves disagreed: a foundation named `@acme/fnd` registered its data
+// schemas under whatever `uniweb.scope` said (measured: `@proximify/member`).
 
 /** Names that say where the code lives, not what the foundation is. */
 export const FORBIDDEN_FOUNDATION_NAMES = new Set(['src', 'foundation'])
@@ -61,3 +68,22 @@ export function checkFoundationName(name) {
   }
   return null
 }
+
+/**
+ * A foundation's name in its two halves: the scope it registers under, and the name
+ * within that scope. `@acme/marketing` → `{ scope: '@acme', bare: 'marketing' }`;
+ * `marketing` → `{ scope: null, bare: 'marketing' }` — a name that has not registered
+ * yet, since `register` writes the scope it chooses into the name.
+ *
+ * ⭐ The scope is what a foundation's own `@/x` data schemas resolve into — at
+ * register, and in a site's records and queries, which name those same Models.
+ *
+ * @param {unknown} name
+ * @returns {{ scope: string|null, bare: string|null }} `scope` as `@org`
+ */
+export function splitFoundationName(name) {
+  const text = typeof name === 'string' ? name.trim() : ''
+  if (!text) return { scope: null, bare: null }
+  const scoped = /^@([^/]+)\/([^/]+)$/.exec(text)
+  return scoped ? { scope: `@${scoped[1]}`, bare: scoped[2] } : { scope: null, bare: text }
+}

package/src/index.js

@@ -18,6 +18,7 @@ export {
 export {
   foundationNameOf,
   checkFoundationName,
+  splitFoundationName,
   FORBIDDEN_FOUNDATION_NAMES,
 } from './foundation-name.js'
 

package/src/runtime-schema.js

@@ -194,8 +194,10 @@ function leanDataSchema(value, dataSchemaMap) {
   if (ref) {
     const resolved = dataSchemaMap[ref]
     // ⛔ `flatRecordFields`, NOT `resolved.fields`. `dataSchemaMap` holds each
-    // schema AS AUTHORED — resolution and lowering are different steps, and only
-    // the second normalizes the two authoring forms. `fields:` at the top is the
+    // schema NORMALIZED but still in the form it was authored in — `fields:` or
+    // `sections:` — because only lowering (`uwx/data-schema.js`) folds the two
+    // forms into one. (This said "AS AUTHORED" until 2026-09-22; aliases and
+    // `many:` are already folded here.) `fields:` at the top is the
     // SUGAR for a one-section model; a sections-form schema has no such key, so
     // reading it directly returned null for every `@std/*` binding and the
     // section's `data:` declaration supplied no field defaults at all. Silent:

package/src/schema.js

@@ -23,7 +23,7 @@ import {
   deriveRecordsSupport,
   unnameableIn,
 } from './foundation/derive-supports.js'
-import { foundationNameOf } from './foundation-name.js'
+import { foundationNameOf, splitFoundationName } from './foundation-name.js'
 import { resolveFoundationSrcDir } from './utils/foundation-source-root.js'
 
 // Component meta file name
@@ -191,6 +191,14 @@ export async function loadPackageJson(srcDir) {
           `\`name\` in main.js's default export (name: '${pkg.uniweb.id}').`
       )
     }
+    // ⛔ `uniweb.scope` likewise (retired 2026-09-22) — the scope is part of the name.
+    // The build never read it; `uniweb register` refuses it, naming the line to write.
+    if (pkg.uniweb?.scope !== undefined) {
+      console.warn(
+        `[uniweb] ${packagePath}: \`uniweb.scope\` is no longer read — a foundation's scope is ` +
+          `part of its name in main.js's default export (name: '@<org>/<name>').`
+      )
+    }
     return {
       name: pkg.name,
       version: pkg.version,
@@ -212,9 +220,10 @@ export async function loadPackageJson(srcDir) {
  * (`foundation-name.js`) — for `uniweb register` and for `push` / `publish` looking
  * the foundation up, which need it before a build, or without one.
  *
- * ⛔ Refuses `package.json::uniweb.id` (retired 2026-09-21). This is the reader
- * whose answer registers, so a leftover stops here rather than registering the
- * foundation under a different name than the one it was given.
+ * ⛔ Refuses `package.json::uniweb.id` (retired 2026-09-21) and `uniweb.scope`
+ * (retired 2026-09-22 — the scope is part of the name). This is the reader whose
+ * answer registers, so a leftover stops here rather than registering the foundation
+ * under a different name than the one it was given.
  *
  * @param {string} foundationDir - the foundation package's root
  * @returns {Promise<{ name: string|null, source: 'main.js'|'package.json'|null, mainFile: string }>}
@@ -238,12 +247,31 @@ export async function readFoundationName(foundationDir) {
   }
   const srcDir = join(foundationDir, resolveFoundationSrcDir(foundationDir))
   const config = await loadFoundationConfig(srcDir)
+  const read = foundationNameOf({ config, pkg })
+  // ⛔ `package.json::uniweb.scope` is retired (2026-09-22): a foundation's scope is
+  // part of its name. Refused here, the reader whose answer registers, because a
+  // leftover would register the name and the data schemas under two different orgs.
+  if (pkg.uniweb?.scope !== undefined) {
+    throw new Error(retiredScopeMessage(pkgPath, pkg.uniweb.scope, read.name))
+  }
   return {
-    ...foundationNameOf({ config, pkg }),
+    ...read,
     mainFile: join(srcDir, FOUNDATION_FILE_NAMES[0]),
   }
 }
 
+/**
+ * What to say about a leftover `package.json::uniweb.scope`: the `main.js` line that
+ * replaces it, or — when `main.js` already scopes the name — that it can go.
+ */
+function retiredScopeMessage(pkgPath, scope, name) {
+  const { scope: nameScope, bare } = splitFoundationName(name)
+  const intro = `${pkgPath}: \`uniweb.scope\` is no longer read — a foundation's scope is part of its name, \`name\` in main.js's default export.`
+  if (nameScope) return `${intro} main.js already names it '${name}', so remove uniweb.scope.`
+  const handle = String(scope ?? '').replace(/^@/, '').replace(/\/.*$/, '') || '<org>'
+  return `${intro} Move it there (name: '@${handle}/${bare || '<name>'}') and remove uniweb.scope.`
+}
+
 /**
  * Load the foundation's declarations from `src/main.js`.
  *

package/src/site/foundation-ref.js

@@ -31,6 +31,20 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve, join } from 'node:path'
 
+/**
+ * A catalog ref — `@org/name@version` — in its parts, or null for anything else.
+ *
+ * The grammar lives here once: `detectFoundationType` refuses a ref for a build, and a
+ * site's sync reads the ref's scope to qualify its `@/x` refs (`uwx/self-scope.js`).
+ *
+ * @param {unknown} value
+ * @returns {{ scope: string, name: string, version: string }|null} `scope` as `@org`
+ */
+export function parseCatalogRef(value) {
+  const m = typeof value === 'string' ? /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(value) : null
+  return m ? { scope: `@${m[1]}`, name: m[2], version: m[3] } : null
+}
+
 /**
  * Detect foundation type from the foundation config value
  *
@@ -104,8 +118,7 @@ export function detectFoundationType(foundation, siteRoot) {
   // match the documented backend selection — so `--backend`, `uniweb login
   // --backend` and the documented env var all left it pinned — and the artifact
   // names were the pre-`entry.js` ones the build stopped emitting.
-  const orgScopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
-  if (orgScopedMatch) {
+  if (parseCatalogRef(name)) {
     throw new Error(
       [
         `Foundation "${name}" is a catalog ref, and a build cannot resolve it to a URL.`,

package/src/site/queries-config.js

@@ -368,7 +368,7 @@ async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
  * The `deferred:` a schema implies — every record field its **brief** does not name.
  *
  * ⛔ ONE IMPLEMENTATION, TWO CALLERS, and that is the point. `deriveDeferredFromSchemas`
- * above uses it to FILL an unstated `deferred:`; `uwx/collections-project.js` uses it to
+ * above uses it to FILL an unstated `deferred:`; `uwx/records-project.js` uses it to
  * RECOGNIZE a derived value on the way back in, so a pull does not write a derivation
  * into the author's file as though they had typed it.
  *

package/src/uwx/index.js

@@ -43,7 +43,6 @@ export {
   siteProjectToDocument,
   emitSiteSyncPackage,
   writeSiteEntityUuid,
-  writeSiteOrg,
   extensionDeclaration,
   isExtensionUrl,
   isSiteRelativeExtensionUrl,
@@ -64,6 +63,9 @@ export {
   folderToFolderYml,
   findRecordFileByUuid,
 } from './records-project.js'
+// The scope a site's `@/x` refs resolve into — its foundation's. A pull resolves it
+// up front and hands it to the synchronous projections above.
+export { siteSelfScope } from './self-scope.js'
 export {
   siteInfoToConfig,
   sectionRecordToFile,

package/src/uwx/records-project.js

@@ -40,7 +40,8 @@ import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './quer
 import { poolDirsForSchema, resolveRecordsDir } from '../site/entity-pool.js'
 import { folderYmlPath } from '../site/records-config.js'
 import { isContentBodyField } from './data-schema.js'
-import { unresolveSelfScope } from './self-scope.js'
+import { unresolveSelfScope, refuseOrgOption } from './self-scope.js'
+import { parseCatalogRef } from '../site/foundation-ref.js'
 import { unwrapLocalized } from './backfill.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
@@ -151,8 +152,8 @@ function indexFolder(folderDoc) {
 // `schemaForPoolDirs`, and deliberately not a second rule: if the two disagreed,
 // a pulled record would land somewhere the next build reads as a different
 // schema — silently, because both paths are well-formed.
-function recordDirFor(recordsRoot, model, selfOrg) {
-  const dirs = poolDirsForSchema(unresolveSelfScope(model, selfOrg))
+function recordDirFor(recordsRoot, model, scope) {
+  const dirs = poolDirsForSchema(unresolveSelfScope(model, scope))
   return dirs ? join(recordsRoot, ...dirs) : null
 }
 
@@ -173,16 +174,6 @@ function locate(document, folderIndex) {
   return fromFolder || null
 }
 
-/** The site's own org on `backend` — its `site.org` in `sync.json` — bare (`acme`), or null. Stored bare — see `writeSiteOrg`. */
-// ⛔ `site.yml::$org` IS GONE (2026-09-20) — the org lives in
-// `sync.json::backends.<origin>.site.org`. This read `site.yml` and, once step 4
-// moved the key, silently returned null: every `@org/x` model a pull met would have
-// been placed back as if the site had no org. No test spanned it.
-function readSiteOrg(siteRoot, backend) {
-  const org = backend ? readBackendState(siteRoot, backend).site?.org : null
-  return typeof org === 'string' && org ? org : null
-}
-
 // Skip undefined when copying optional fields into a projected declaration.
 function setIf(obj, key, value) {
   if (value !== undefined) obj[key] = value
@@ -239,15 +230,15 @@ function isDerivedDeferred(d, dataSchemas) {
   return d.deferred.every((f) => a.has(f))
 }
 
-function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
+function declToFileShape(wire, dataSchemas = null, scope = null) {
   // ⛔ UNDO THE PRODUCER'S QUALIFICATION FIRST, before anything compares against
-  // `schema`. The push qualifies a foundation-relative `@/x` to `@org/x`
+  // `schema`. The push qualifies a foundation-relative `@/x` to `@scope/x`
   // (`site.js::queriesNested`), and both checks below are keyed by the author's
-  // `@/x`: against `@org/x` the query-name default would never match — writing an
+  // `@/x`: against `@scope/x` the query-name default would never match — writing an
   // explicit schema the author never had — and the derived-`deferred` lookup would
   // miss, persisting a derivation into their file (the 2026-08-29 defect).
-  const d = selfOrg && typeof wire.schema === 'string'
-    ? { ...wire, schema: unresolveSelfScope(wire.schema, selfOrg) }
+  const d = scope && typeof wire.schema === 'string'
+    ? { ...wire, schema: unresolveSelfScope(wire.schema, scope) }
     : wire
   const name = d.name || d.$id
   const decl = {}
@@ -329,14 +320,14 @@ function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
  * @param {object} params
  * @param {object} params.document - a site-content `$`-document (`{ queries }`)
  * @param {string} params.siteRoot
- * @param {string} [params.org] - the site's own org, so a `schema` the producer
- *        qualified from `@/x` is written back as `@/x`. Defaults to the org
- *        `sync.json` records for `backend`, the same default `recordsToProject`
- *        places records by.
- * @param {string|null} [params.backend] - whose recorded org is that default
+ * @param {string|null} [params.scope] - the scope the push qualified a `schema` from
+ *        `@/x` with — the site's foundation's — so it is written back as `@/x`.
+ *        Defaults to the scope of the foundation ref the pulled document carries
+ *        (`info.foundation`, the pinned `@org/name@version`), which is that scope.
  * @returns {{ collections?: 'updated'|'unchanged' }}
  */
-export function declarationsToQueriesYml({ document, siteRoot, org, backend = null }) {
+export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest }) {
+  refuseOrgOption(rest, 'declarationsToQueriesYml')
   const decls = Array.isArray(document?.queries) ? document.queries : []
   const report = {}
   if (decls.length === 0) return report
@@ -354,11 +345,12 @@ export function declarationsToQueriesYml({ document, siteRoot, org, backend = nu
     siteYml = null
   }
   const dataSchemas = siteYml ? foundationDataSchemas(siteRoot, siteYml) : null
-  const selfOrg = org ?? readSiteOrg(siteRoot, backend)
+  const selfScope =
+    scope !== undefined ? scope : (parseCatalogRef(document?.info?.foundation)?.scope ?? null)
 
   const queries = {}
   for (const d of decls) {
-    const { name, decl } = declToFileShape(d, dataSchemas, selfOrg)
+    const { name, decl } = declToFileShape(d, dataSchemas, selfScope)
     if (!name) continue
     queries[name] = decl
   }
@@ -469,20 +461,21 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
  * @param {object} params.opts
  * @param {(modelName: string) => object|null|undefined} params.opts.resolveDeclaration
  *        - resolve a Model's data-schema declaration by name (`$model`).
- * @param {string} [params.opts.org] - the site's own org, so a `@org/x` model the
- *        producer resolved from `@/x` is placed back where the author wrote it.
- *        Defaults to the org `sync.json` records for `opts.backend`.
- * @param {string} [params.opts.backend] - whose record map to read and extend, and
- *        whose recorded org is that default
+ * @param {string|null} [params.opts.scope] - the scope the push qualified a record's
+ *        `@/x` Model with — the site's foundation's — so a `@scope/x` model is placed
+ *        back where the author wrote it. The caller resolves it up front, as it does
+ *        Models (`siteSelfScope`); absent, a model is placed under its own scope.
+ * @param {string} [params.opts.backend] - whose record map to read and extend
  * @param {string} [params.opts.sourceLocale]
  * @returns {{ updated: string[], placed: string[], unchanged: string[], skipped: object[], warnings: string[], locales: object }}
  */
 export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts = {} }) {
   const { resolveDeclaration, sourceLocale = 'en' } = opts
-  // The site's own org, so a `@org/x` model the producer resolved from `@/x` is
-  // placed back where the author wrote it. Read from `sync.json` (this backend's
-  // `site.org`) unless the caller already has it.
-  const selfOrg = opts.org ?? readSiteOrg(siteRoot, opts.backend)
+  refuseOrgOption(opts, 'recordsToProject')
+  // The scope the push qualified `@/x` with — the site's foundation's — so a
+  // `@scope/x` model is placed back where the author wrote it. ⛔ It was the site
+  // owner's org, read from `sync.json`, until 2026-09-22 (`self-scope.js`).
+  const selfScope = opts.scope ?? null
   if (typeof resolveDeclaration !== 'function') {
     throw new Error('uwx/records-project: opts.resolveDeclaration(modelName) is required')
   }
@@ -525,7 +518,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
       continue
     }
 
-    const poolDir = recordDirFor(recordsRoot, document.$model, selfOrg)
+    const poolDir = recordDirFor(recordsRoot, document.$model, selfScope)
     if (!poolDir) {
       skipped.push({
         uuid: document.$uuid,

package/src/uwx/records.js

@@ -57,7 +57,7 @@ import {
 } from '../site/entity-pool.js'
 import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isContentBodyField } from './data-schema.js'
 import { emitEntitySyncPackage } from './entity-document.js'
-import { resolveSelfScope } from './self-scope.js'
+import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
 import { LOCALIZED_FIELD_ASSUMPTION, localize } from './localize.js'
@@ -554,6 +554,9 @@ function resolveDeclaration(schema, modelName) {
  *        `@uniweb/data-schema` declaration (or null). The verb wires this to the
  *        backend's Model-read route. Without it, the local foundation is required.
  * @param {string} [opts.sourceLocale]    - localized-field wrap locale
+ * @param {string|null} [opts.scope] - the scope a record's `@/x` Model resolves into.
+ *        Defaults to the site's foundation's (`siteSelfScope`); a caller that has it
+ *        already passes it, so one emit reads it once.
  * @returns {Promise<{ entities: object[], index: object[], warnings: string[],
  *   schemaless: Array<{name: string, model: string}>, colConfig: object,
  *   folder: object, recordsDirExists: boolean }>}
@@ -585,6 +588,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   // twice and the duplicate check refused the push (measured: "appears in more than
   // one query"), and a record no query read was never pushed. Records are walked
   // once, by the schema their folder declares.
+  refuseOrgOption(opts, 'uwx/records')
   const pool = await readEntityPool(siteRoot)
   const recordsCfg = await readRecordsConfig(siteRoot, { dir: pool.dir })
   if (recordsCfg.error) throw new Error(`uwx/records: ${recordsCfg.error}`)
@@ -657,19 +661,25 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   //
   // ⛔ The rule lives in `./self-scope.js`, shared with the `queries` Section
   // (`site.js::queriesNested`): a query's `schema` must name exactly the Model
-  // these records are stored under, so both go through one function with one org.
+  // these records are stored under, so both go through one function with one scope.
+  //
+  // ⭐ THE SCOPE IS THE FOUNDATION'S — the one `register` stored these Models under —
+  // never the site owner's (2026-09-22; `self-scope.js` has the record).
+  const scope =
+    opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot, { foundationDir: opts.foundationDir })
   const warnedUnscoped = new Set()
   const modelFor = (schema, where) => {
-    const modelName = resolveSelfScope(schema, opts.org)
-    // Unresolvable `@/` — no org is known. Ship it rather than throwing (a `status`
-    // probe on a never-pushed site has no org and must still count), but say so:
-    // the backend's refusal names a missing Model and cannot name this cause.
+    const modelName = resolveSelfScope(schema, scope)
+    // Unresolvable `@/` — the foundation has no scope yet. Ship it rather than
+    // throwing (a `status` probe on a never-registered foundation must still count),
+    // but say so: the backend's refusal names a missing Model and cannot name this cause.
     if (modelName === schema && typeof schema === 'string' && schema.startsWith('@/') && !warnedUnscoped.has(schema)) {
       warnedUnscoped.add(schema)
       warnings.push(
-        `${where}: \`${schema}\` is foundation-relative and no org is known, ` +
+        `${where}: \`${schema}\` is foundation-relative and the foundation has no scope yet, ` +
           `so it ships unresolved. The backend resolves Models by name and will refuse it. ` +
-          `Pass \`--org @handle\`, or push once so the site records its org.`
+          `A foundation's scope is part of its name — \`name: '@org/<name>'\` in its main.js, ` +
+          `which \`uniweb register\` writes.`
       )
     }
     return modelName
@@ -863,8 +873,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       ? !unresolved.has(schema)
       : Boolean(await declarationFor(modelFor(schema, `query "${name}"`)))
     if (!resolved) {
-      if (decl.schemaExplicit) throw unresolvedExplicit(resolveSelfScope(schema, opts.org), name)
-      schemaless.push({ name, model: resolveSelfScope(schema, opts.org) })
+      if (decl.schemaExplicit) throw unresolvedExplicit(resolveSelfScope(schema, scope), name)
+      schemaless.push({ name, model: resolveSelfScope(schema, scope) })
       continue
     }
     if (!hasRecords) {

package/src/uwx/registry-package.js

@@ -17,16 +17,17 @@
  * `@uniweb/data-schema` entities, no foundation-schema — for a schemas-only
  * package (the standard schemas under `@std`, or an org's own `@org/schemas`).
  *
- * Scope: pass `scope` ('@acme' or 'acme') to resolve a schema's own `@/x` (and the
- * foundation's `data-schemas.refs`) to a concrete `@acme/x` for submission. With no
- * `scope`, names stay `@/x` (local preview / dry-run). See `uwx-format.md`.
+ * Scope: a foundation whose name is scoped (`@acme/fnd`) registers under that scope —
+ * its name and its schemas' own `@/x` alike. A bare name takes `scope` ('@acme' or
+ * 'acme'). With neither, names stay `@/x` (local preview / dry-run). A schemas-only
+ * package has no name to carry one, so it always takes `scope`. See `uwx-format.md`.
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { toDataSchemaDeclaration } from './data-schema.js'
-import { checkFoundationName } from '../foundation-name.js'
+import { checkFoundationName, splitFoundationName } from '../foundation-name.js'
 
 const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
 const DATA_SCHEMA = '@uniweb/data-schema'
@@ -46,7 +47,9 @@ try {
  * @param {Object} params
  * @param {Object} params.schema - parsed `dist/meta/schema.json`.
  * @param {string} [params.foundationDir] - foundation root, for the `i18n/` bundles.
- * @param {string} [params.scope] - org scope (`@acme` or `acme`) resolving `@/x` -> `@acme/x`.
+ * @param {string} [params.scope] - org scope (`@acme` or `acme`) resolving `@/x` -> `@acme/x`,
+ *   for a foundation whose name is bare. A scoped name's own scope is used instead, and
+ *   a `scope` that contradicts it throws.
  * @param {Object} [params.exporter] - `{ tool, version, instance }` for the envelope.
  * @param {string} [params.exportedAt] - ISO timestamp (default: now).
  * @param {string} [params.runtime] - the `@uniweb/runtime` version this build
@@ -70,7 +73,10 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
   // own `@/x`), each resolved to the concrete publish scope. Shared refs
   // (`@std/x`, `@other/x`) are named in the foundation's data-schemas.refs but
   // their declarations are not bundled — already published.
-  const { entities: dataSchemaEntities, scoped, org } = buildDataSchemaEntities(dataSchemas, scope)
+  const { entities: dataSchemaEntities, scoped, org } = buildDataSchemaEntities(
+    dataSchemas,
+    registrationScope(self.name, scope)
+  )
 
   const foundationEntity = {
     model: FOUNDATION_SCHEMA,
@@ -108,6 +114,27 @@ export function buildSchemaOnlyPackage({ schemas, scope, exporter, exportedAt }
   return wrapEntities(entities, exporter, exportedAt)
 }
 
+// The scope a foundation registers under: the one in its name, else `scope`.
+//
+// ⭐ A SCOPED NAME IS THE SCOPE (2026-09-22). `@acme/fnd` registers under `@acme` —
+// the foundation and its data schemas both, because a site's records name those
+// schemas by the same scope. ⛔ Until then the schemas took `scope` while the name
+// kept its own, so one foundation registered `@acme/fnd` beside `@proximify/member`.
+// A `scope` that contradicts the name is refused rather than chosen between: which
+// org was meant is not ours to guess.
+function registrationScope(name, scope) {
+  const { scope: nameScope } = splitFoundationName(name)
+  const handle = scope ? String(scope).replace(/^@/, '').replace(/\/.*$/, '') : ''
+  const given = handle ? `@${handle}` : null
+  if (nameScope && given && given !== nameScope) {
+    throw new Error(
+      `buildRegistryPackage: the foundation is named ${name}, so it registers under ` +
+        `${nameScope} — not ${given}. A foundation's scope is the one in its name.`
+    )
+  }
+  return nameScope || scope
+}
+
 // Lower a `{ '@/<name>': normalizedSchema }` map into the sorted
 // `@uniweb/data-schema` entity list, resolving each own `@/x` to the publish
 // scope. Shared by the foundation publish (buildRegistryPackage) and the

package/src/uwx/self-scope.js

@@ -1,9 +1,9 @@
-// `@/x` — a Model ref in the site's own foundation scope — and its qualified form.
+// `@/x` — a Model ref in the site's foundation's own scope — and its qualified form.
 //
 // `@/member` names a data schema in the foundation's own `schemas/`. It is
 // AUTHORING shorthand: a backend resolves Models by name and never mints one, so a
 // ref that leaves the CLI must be the name the Model was stored under,
-// `@<org>/member`. Everything that reads a ref off the wire matches it exactly —
+// `@<scope>/member`. Everything that reads a ref off the wire matches it exactly —
 // the entity store at restore, and a records service answering a hosted page's
 // query.
 //
@@ -13,7 +13,7 @@
 //   - a query's `schema`              `site.js::queriesNested` (the `queries` Section)
 //   - the author's spelling, on pull  `records-project.js` (placement and declarations)
 //
-// ⛔ They must agree on one alias. When the query path shipped `@/member` verbatim
+// ⛔ They must agree on one scope. When the query path shipped `@/member` verbatim
 // while the records beside it were qualified, the query named a Model its own
 // records were not stored under: a hosted page's question named a Model that does
 // not exist, the records service refused that key, and the section rendered
@@ -21,39 +21,52 @@
 // `block.dataError`, the console clean. Nothing on either side was malformed; the
 // two paths disagreed.
 //
-// Registering a foundation qualifies its declarations separately, from the
-// foundation's publish scope (`registry-package.js`). That is a different input
-// (the foundation's scope, not the site's publish org) and stays there.
+// ⭐ THE SCOPE IS THE FOUNDATION'S — the one in its name (`@acme/marketing`), which is
+// the scope `register` stored the foundation's own data schemas under
+// (`registry-package.js`). ⛔ Until 2026-09-22 every path above qualified with the org
+// that owns the SITE instead — a stand-in that holds only when one org owns both, and
+// a foundation may be registered under any org its author belongs to [Diego]. A site
+// owned by `@client` on a foundation registered as `@acme/fnd` shipped its records as
+// `@client/member`, a Model `register` never stored; a personal site shipped
+// `@/member` unresolved (both measured). `siteSelfScope` is where the scope comes from.
+
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+import { detectFoundationType, parseCatalogRef } from '../site/foundation-ref.js'
+import { readFoundationName } from '../schema.js'
+import { splitFoundationName } from '../foundation-name.js'
 
 /**
- * An org handle as `--org` or `sync.json` gives it — `@acme`, `acme`, or
- * `@acme/…` — reduced to the bare handle, or `''`.
+ * A scope as it may be written — `@acme`, `acme`, or `@acme/…` — reduced to the bare
+ * handle, or `''`.
  *
- * @param {unknown} org
+ * @param {unknown} scope
  * @returns {string}
  */
-export function bareOrg(org) {
-  return typeof org === 'string' ? org.replace(/^@/, '').replace(/\/.*$/, '') : ''
+export function bareOrg(scope) {
+  return typeof scope === 'string' ? scope.replace(/^@/, '').replace(/\/.*$/, '') : ''
 }
 
 /**
- * `@/x` → `@<org>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
- * does `@/x` when no org is known — callers that ship an unresolved alias say so
+ * `@/x` → `@<scope>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
+ * does `@/x` when no scope is known — callers that ship an unresolved alias say so
  * themselves (`buildRecordEntities` warns per query).
  *
  * @param {unknown} ref
- * @param {unknown} org
+ * @param {unknown} scope - the site's foundation's scope (`siteSelfScope`)
  * @returns {unknown}
  */
-export function resolveSelfScope(ref, org) {
-  const handle = bareOrg(org)
+export function resolveSelfScope(ref, scope) {
+  const handle = bareOrg(scope)
   return typeof ref === 'string' && ref.startsWith('@/') && handle
     ? `@${handle}/${ref.slice(2)}`
     : ref
 }
 
 /**
- * The inverse, for a pull: `@<org>/x` → `@/x` for the site's own org.
+ * The inverse, for a pull: `@<scope>/x` → `@/x` for the site's foundation's scope.
  *
  * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
  * on both ends. A record authored under `records/article/` comes back as
@@ -63,16 +76,90 @@ export function resolveSelfScope(ref, org) {
  * relied on the query-name default comes back with an explicit schema it never
  * had.
  *
- * ⭐ The site records its own org at create (`site.org` in `sync.json`, per backend —
- * "whose this is"), which is exactly the inverse. A model scoped to ANOTHER org is left alone: it
- * genuinely is that org's, and `@/` would be a lie.
+ * A model scoped to ANY OTHER scope is left alone: it genuinely is that org's, and
+ * `@/` would be a lie.
  *
  * @param {unknown} ref
- * @param {unknown} org
+ * @param {unknown} scope - the scope the pulled records were qualified with
  * @returns {unknown}
  */
-export function unresolveSelfScope(ref, org) {
-  const handle = bareOrg(org)
+export function unresolveSelfScope(ref, scope) {
+  const handle = bareOrg(scope)
   if (typeof ref !== 'string' || !handle) return ref
   return ref.startsWith(`@${handle}/`) ? `@/${ref.slice(handle.length + 2)}` : ref
 }
+
+/**
+ * The scope a site's `@/x` refs resolve into: its foundation's, `@org` — or null
+ * when it has none yet.
+ *
+ * - `foundation` given (a pull passes the pinned ref the pushed site carries) — a
+ *   catalog ref's scope, or a local foundation's, resolved from that value.
+ * - else `foundationDir` — that local foundation's.
+ * - else `site.yml::foundation`, the same way.
+ *
+ * A local foundation's scope is the one in its name, read by the one rule
+ * (`readFoundationName`, the reader `register` and `push` use), so what a push pins
+ * and what it qualifies with cannot differ. A bare name has no scope until `register`
+ * gives it one; a URL foundation has none.
+ *
+ * ⚠️ A foundation whose name cannot be read (a leftover `uniweb.scope`, a `main.js`
+ * that fails to load) answers null here. `register` — which a push and a publish run
+ * first — says why; this only qualifies.
+ *
+ * @param {string} siteRoot
+ * @param {{ foundation?: unknown, foundationDir?: string }} [opts]
+ * @returns {Promise<string|null>}
+ */
+export async function siteSelfScope(siteRoot, { foundation, foundationDir } = {}) {
+  if (foundation === undefined && foundationDir) return localFoundationScope(resolve(foundationDir))
+  const declared = foundation !== undefined ? foundation : readDeclaredFoundation(siteRoot)
+  const value = declared && typeof declared === 'object' ? declared.name : declared
+  if (typeof value !== 'string' || !value) return null
+  const ref = parseCatalogRef(value)
+  if (ref) return ref.scope
+  let info = null
+  try {
+    info = detectFoundationType(value, siteRoot)
+  } catch {
+    return null
+  }
+  return info?.type === 'local' && info.path ? localFoundationScope(info.path) : null
+}
+
+async function localFoundationScope(dir) {
+  try {
+    const { name } = await readFoundationName(dir)
+    return splitFoundationName(name).scope
+  } catch {
+    return null
+  }
+}
+
+function readDeclaredFoundation(siteRoot) {
+  try {
+    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8'), YAML_OPTIONS) || {}
+    return siteYml.foundation ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Refuse the retired `org` option.
+ *
+ * ⛔ It carried the org that owns the SITE, and qualified a site's `@/x` refs with it
+ * (until 2026-09-22). Ignoring it would be silent, so a caller still passing it is told
+ * what replaced it: the foundation's scope, derived — or `scope`, to state it.
+ *
+ * @param {object|undefined} opts
+ * @param {string} where - the function, for the message
+ */
+export function refuseOrgOption(opts, where) {
+  if (opts && opts.org !== undefined) {
+    throw new Error(
+      `${where}: \`org\` is no longer read — a site's \`@/x\` refs resolve into its ` +
+        `foundation's scope (the one in the foundation's name). Pass \`scope\` to state it.`
+    )
+  }
+}

package/src/uwx/site-project.js

@@ -868,9 +868,12 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  *        files that have no corresponding incoming item (git-pull-like). Off by
  *        default; `uniweb pull` opts in. Guarded against wiping a level on an
  *        empty set.
+ * @param {string|null} [params.scope] - the scope the push qualified a query's
+ *        `@/x` schema with, so it is written back as `@/x` — see
+ *        `declarationsToQueriesYml`, whose default it overrides.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope }) {
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
@@ -893,7 +896,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   )
 
   report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
-  report.queries = declarationsToQueriesYml({ document, siteRoot, backend })
+  report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
 
   // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
   // rename detection, build a fresh one as we project, then persist it. Items not

package/src/uwx/site.js

@@ -1,5 +1,5 @@
 // Map a file site project to one `@uniweb/site-content` entity, as the
-// section-keyed `-document (docs/reference/entity-content.md), then to a
+// section-keyed `$`-document (docs/reference/entity-content.md), then to a
 // `subtype: entity` .uwx on the SYNC lane.
 //
 // SOURCE LAYER: the content-collector's return is flattened and lossy for
@@ -8,9 +8,13 @@
 // processMarkdownFile, ordering, mode detection) so those semantics stay
 // identical to a normal build — only the directory/mode/order *walk* is ours.
 //
-// The document mirrors the @uniweb/site-content Model: `info` (brief) · `pages`
-// (self-nesting; each page carries its `page_sections` as an inline field) ·
-// `layout_sections` · `extensions` · `queries`. `info.foundation`
+// The document mirrors the @uniweb/site-content Model: `info` (brief) · `settings`
+// · `pages` (self-nesting; each page carries its `page_sections` as an inline
+// field) · `layout_sections` · `extensions` · `queries` · `services` · `secrets`.
+// `settings` is emitted only when non-empty; `services` and `secrets` only when the
+// backend being pushed to has that key in `sync.json` (absent is not empty — see
+// below). `emit-surface.json` states which `site.yml` key lands in `info` and
+// `settings`. `info.foundation`
 // carries the verbatim `site.yml::foundation` string (the round-trip source of
 // truth).
 //
@@ -73,7 +77,7 @@ import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { updateBackendState, readBackendState } from './sync-store.js'
 import { upsertYamlScalar } from './yaml-upsert.js'
 import { resolveQueriesConfig } from './queries-config.js'
-import { resolveSelfScope } from './self-scope.js'
+import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { siteContentDirs } from './site-dirs.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
@@ -915,7 +919,7 @@ function externalSource(d) {
   return source
 }
 
-function queriesNested(declarations, uuids = null, org = null) {
+function queriesNested(declarations, uuids = null, scope = null) {
   const out = []
   for (const [name, d] of Object.entries(declarations)) {
     refuseUnder(d.where, `queries.${name}`)
@@ -926,13 +930,13 @@ function queriesNested(declarations, uuids = null, org = null) {
     // the runtime fetches it from (never the records service).
     const source = d.path ? { path: d.path } : d.url !== undefined ? externalSource(d) : d.source
     setIf(data, 'source', source)
-    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME ORG AS THE RECORDS' `$model`
-    // (`records.js::buildRecordEntities`). A consumer answers a query by matching
-    // this name against the Models its records were stored under, so a verbatim
-    // `@/member` beside records stored as `@org/member` names nothing: the query
-    // resolves no Model and the page that binds it renders empty. The pull puts the
-    // author's `@/` back (`records-project.js::declarationsToQueriesYml`).
-    setIf(data, 'schema', resolveSelfScope(d.schema, org))
+    // ⛔ QUALIFIED, WITH THE SAME RULE AND THE SAME SCOPE AS THE RECORDS' `$model`
+    // (`records.js::buildRecordEntities`) — the site's foundation's. A consumer
+    // answers a query by matching this name against the Models its records were
+    // stored under, so a verbatim `@/member` beside records stored as `@acme/member`
+    // names nothing: the query resolves no Model and the page that binds it renders
+    // empty. The pull puts the author's `@/` back (`records-project.js::declarationsToQueriesYml`).
+    setIf(data, 'schema', resolveSelfScope(d.schema, scope))
     setIf(data, 'sort', d.sort)
     // Legacy `filter:` is not synced — it is translated to `where` upstream
     // (the canonical predicate). No legacy fields on the wire.
@@ -1009,16 +1013,19 @@ function queriesNested(declarations, uuids = null, org = null) {
 // ⛔ ABSENT IS NOT EMPTY, and the difference is destructive. The Section is
 // REPLACED by what we send, so `[]` means "drop every stored config row" while a
 // missing key means "I am not telling you about this". A project that has never
-// pulled has no `$services`, and its ordinary push must not read as a request to
-// wipe a service the operator configured in the app. So: emit the Section only when
-// the file declares the key. Clearing is available and explicit — `$services: []`.
+// pulled has no `services` for that backend, and its ordinary push must not read as
+// a request to wipe a service the operator configured in the app. So: emit the
+// Section only when that backend's entry in `sync.json` carries the key. Clearing is
+// available and explicit — `services: []` there. *(Both said `site.yml::$services`
+// until the move on 2026-09-20.)*
 //
 // ⚠️ The push gate is NOT what makes this safe, though it usually catches it: its
 // tokens live in a gitignored per-clone cache, so a fresh clone pushes
 // unconditionally. Correctness has to sit here.
 
 /**
- * `$services` / `$secrets` → Section records, or undefined when the key is absent.
+ * A backend's provisioned `services` / `secrets` (its `sync.json` entry) → Section
+ * records, or undefined when the key is absent.
  *
  * ⭐ PASSTHROUGH, NOT AN ALLOWLIST — the same rule and the same reason as
  * `queriesNested` above. The field set belongs to the backend's Model, a service's
@@ -1027,7 +1034,8 @@ function queriesNested(declarations, uuids = null, org = null) {
  * would DESTROY whatever is stored under it on every push. Framework can enumerate
  * its own vocabulary and cannot enumerate theirs; withhold ours, forward the rest.
  *
- * @param {*} declared - the raw `$services` / `$secrets` value from site.yml
+ * @param {*} declared - the raw `services` / `secrets` value from that backend's
+ *        `sync.json` entry
  * @param {(entry: object) => string|null} identify - the record's stable `$id`
  * @param {string} label - the key name, for the one warning below
  * @returns {object[]|undefined}
@@ -1229,13 +1237,16 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
  * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
  *        the site's effective default locale (`defaultLanguage || languages[0] ||
  *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
- * @param {string} [opts.org] - the publish org, which qualifies a query's
- *        foundation-relative `schema` (`@/x` → `@org/x`). Pass the same org the
- *        records are emitted with; absent, `@/x` ships as written.
+ * @param {string|null} [opts.scope] - the scope a query's foundation-relative `schema`
+ *        resolves into (`@/x` → `@scope/x`): the site's foundation's. Defaults to
+ *        `siteSelfScope`; pass the scope the records are emitted with. With none
+ *        known, `@/x` ships as written.
  * @returns {Promise<object>} the section-keyed `$`-document:
- *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, queries }`
+ *        `{ $uuid?, $id, $model, info, settings?, pages, layout_sections, extensions,
+ *        queries, services?, secrets? }`
  */
 export async function siteProjectToDocument(siteRoot, opts = {}) {
+  refuseOrgOption(opts, 'uwx/site')
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
   const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
@@ -1533,7 +1544,8 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //
   // ⚠️ `queriesNested` keeps its name. §2's rule: rename what an author or a
   // consumer sees, leave the identifier alone.
-  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, opts.org)
+  const scope = opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot)
+  doc.queries = queriesNested(colConfig.declarations, opts.queryUuids, scope)
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.
@@ -1618,53 +1630,13 @@ export function writeSiteEntityUuid(siteRoot, backend, uuid) {
   return updateBackendState(siteRoot, backend, { site: { uuid } })
 }
 
-/**
- * Record the org the site was CREATED under — `backend`'s `site.org` in `sync.json`,
- * beside the site's uuid. (It was `site.yml::$org` until 2026-09-20.)
- *
- * The org is consumed at exactly one moment — the `as_org` on the create that
- * mints `$uuid` — and after that the uuid carries the ownership binding. So this
- * is not a knob the backend re-reads; it is the answer to *"whose workspace is
- * this site's storage charged to?"*, which `$uuid` alone cannot answer and which
- * otherwise costs a backend round-trip (or is simply unknowable from the repo).
- *
- * Stored as the BARE handle, never `@handle` — the canonical form everywhere else
- * (`deriveScope` returns it, `createOrg` echoes it as `org.handle`,
- * `validateHandle` validates it); the `@` is display sugar the reader re-adds. In
- * `site.yml` it was also the only form that parsed: `@` is a reserved YAML
- * indicator, so `$org: @acme` is an error.
- *
- * ⛔ NOT `deploy.yml`, though that file already holds the bound `backend` and the
- * two look like the same class of fact. Four reasons, and the first is the one that
- * settles it:
- *
- *  1. CARDINALITY. `deploy.yml` is multi-TARGET and `backend` sits *under* a target,
- *     so its shape says "this may vary per target." An org may not: one site has one
- *     owning org, fixed at create and preserved on replace. The org is a property of
- *     the site's uuid, and sits beside it in the same backend's section — filing it
- *     under a target would encode a freedom that does not exist.
- *  2. WHO WRITES. Three paths mint a site (`ensureSiteExists`, the media-less push's
- *     content-lane create, and `clone` seeding an existing one) and **none of them
- *     write `deploy.yml`** — only `deploy` and `publish` call `recordLastDeploy`. The
- *     record would exist or not depending on which verb the developer reached for.
- *  3. SUPPRESSIBLE. `recordLastDeploy` is a no-op under `autoSave: off` / `--no-save`.
- *     Turning off deploy *receipts* would silently drop an *ownership* record.
- *  4. SEMANTICS. `deploy.yml` describes the act of shipping (`lastDeploy` is a
- *     receipt) and is optional entirely. But `push` creates a site and never
- *     publishes — a site can exist, be owned, and accrue storage charges without
- *     ever being deployed. Ownership does not belong in a record of a deploy that
- *     may not have happened.
- *
- * `backend` answers *where this ships*; `site.org` answers *whose this is*.
- *
- * @param {string} siteRoot
- * @param {string} backend - the origin of the backend the site was created on
- * @param {string} handle - the bare org handle (no leading `@`)
- * @returns {boolean} true if sync.json changed
- */
-export function writeSiteOrg(siteRoot, backend, handle) {
-  return updateBackendState(siteRoot, backend, { site: { org: handle } })
-}
+// ⛔ `writeSiteOrg` is GONE (2026-09-23). The workspace a project's requests name is two
+// keys of `site` now — `org` (a handle, bare) and `unit` (the uuid of a workspace with no
+// handle), at most one set — and every site request names it, so it is no longer a note
+// written once at the create. A writer of one key would leave the other stale; write
+// both through `updateBackendState`. Why it lives here rather than in `deploy.yml`: a
+// site has one workspace per backend, fixed by the create, while `deploy.yml` is per
+// target and records the act of shipping, which `push` never does.
 
 // ⛔ `writeSiteBackend` and `site.yml::$backend` are GONE (2026-09-20). The scope is
 // no longer a value recorded beside the uuid — it is the KEY the identity is stored

package/src/uwx/sync-package.js

@@ -23,6 +23,7 @@ import { buildRecordEntities, entityContentHash } from './records.js'
 import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
+import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { isLocalAssetPath } from '../site/assets.js'
@@ -205,6 +206,9 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  * @param {string} siteRoot - directory containing site.yml
  * @param {object} [opts]
  * @param {string} [opts.foundationDir]   - local foundation root (collection Models)
+ * @param {string|null} [opts.scope]      - the scope the site's `@/x` refs resolve
+ *        into. Defaults to its foundation's (`siteSelfScope`) — the one in the
+ *        foundation's name. `org` is refused: it carried the site owner's.
  * @param {Function} [opts.resolveModel]  - async non-local Model resolver
  * @param {string} [opts.sourceLocale]    - localized-field wrap locale
  * @param {Object<string,string>} [opts.priorHashes] - sync-cache (send-only-changed)
@@ -271,6 +275,13 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})
   const exporter = opts.exporter
   const exportedAt = opts.exportedAt
+  refuseOrgOption(opts, 'emitSyncPackages')
+  // ⭐ ONE SCOPE FOR THE WHOLE EMIT — the site's foundation's, the one `register`
+  // stored its Models under — so a record's `$model` and a query's `schema` are
+  // qualified alike. Read once here and handed to both. ⛔ It was the org that owns
+  // the SITE until 2026-09-22 (`self-scope.js`).
+  const scope =
+    opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot, { foundationDir: opts.foundationDir })
 
   const col = await buildRecordEntities(siteRoot, {
     // Which backend's record uuids go on the wire (sync.json) — see records.js.
@@ -278,10 +289,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
     ...(opts.foundationDir ? { foundationDir: opts.foundationDir } : {}),
     ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
     ...(sourceLocale ? { sourceLocale } : {}),
-    // The publish org — resolves a foundation-relative `@/x` model ref into
-    // `@org/x` before it ships. Absent on an offline probe, which is why
-    // buildRecordEntities warns rather than throws.
-    ...(opts.org ? { org: opts.org } : {}),
+    // Resolves a foundation-relative `@/x` model ref into `@scope/x` before it ships.
+    // Null for a foundation with no scope yet, which is why buildRecordEntities
+    // warns rather than throws.
+    scope,
   })
   const warnings = [...col.warnings, ...(col.folder?.warnings ?? [])]
 
@@ -325,10 +336,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
         // Whose $uuid belongs on this wire document — see siteProjectToDocument.
         ...(opts.backend ? { backend: opts.backend } : {}),
         ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
-        // ⛔ THE SAME ORG `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
+        // ⛔ THE SAME SCOPE `buildRecordEntities` WAS GIVEN ABOVE. A query's `schema`
         // must name the Model its records are stored under, and both are qualified
-        // from one `@/x` by one rule (`./self-scope.js`) — so they take one org.
-        ...(opts.org ? { org: opts.org } : {}),
+        // from one `@/x` by one rule (`./self-scope.js`) — so they take one scope.
+        scope,
         // Withhold the `$services`/`$secrets` Sections when the caller has
         // determined the file is not asking for anything new by them. Passed
         // through rather than decided here: the last-agreed state is project