@uniweb/build 0.26.1 → 0.27.1

package/src/site/data-fetcher.js

@@ -239,6 +239,50 @@ export function applyPostProcessing(data, config) {
  * parseFetchConfig({ collection: 'articles', limit: 3, sort: 'date desc' })
  * // Returns: { path: '/data/articles.json', schema: 'articles', limit: 3, sort: 'date desc', ... }
  */
+// ─── Unrecognized-key reporting ───────────────────────────────────────
+//
+// `parseFetchConfig` reads an explicit allowlist and builds a new object, so
+// anything the author wrote that is not on that list is DROPPED — silently,
+// with no warning and no trace in the output. A typo (`wehre:`), a field from
+// another config block, or a capability the author believed existed all look
+// identical to having written nothing.
+//
+// ⛔ That silence is the defect, not the dropping. We cannot act on a key we do
+// not understand, but we can refuse to pretend it was never there. Reported
+// once per key name per process so a 200-record build does not print 200 lines.
+const RECOGNIZED_FETCH_KEYS = {
+  refine: new Set(['refine', 'inherit', 'detail', 'limit', 'sort', 'where', 'filter']),
+  collection: new Set([
+    'collection', 'schema', 'prerender', 'merge', 'transform',
+    'where', 'limit', 'sort', 'detailPage', 'filter',
+  ]),
+  source: new Set([
+    'path', 'url', 'schema', 'prerender', 'merge', 'transform', 'detail',
+    'detailPage', 'where', 'limit', 'sort', 'filter',
+  ]),
+}
+
+const warnedUnknownFetchKeys = new Set()
+
+function warnUnknownFetchKeys(fetch, shape) {
+  const recognized = RECOGNIZED_FETCH_KEYS[shape]
+  for (const key of Object.keys(fetch)) {
+    if (recognized.has(key)) continue
+    const seenKey = `${shape}:${key}`
+    if (warnedUnknownFetchKeys.has(seenKey)) continue
+    warnedUnknownFetchKeys.add(seenKey)
+    console.warn(
+      `[uniweb] fetch: unrecognized key "${key}" was ignored. ` +
+        `Keys recognized on this declaration: ${[...recognized].sort().join(', ')}.`
+    )
+  }
+}
+
+/** Test seam — reset the once-per-key memo so suites do not leak into each other. */
+export function _resetUnknownFetchKeyWarnings() {
+  warnedUnknownFetchKeys.clear()
+}
+
 export function parseFetchConfig(fetch) {
   if (!fetch) return null
 
@@ -269,6 +313,7 @@ export function parseFetchConfig(fetch) {
   // block are currently accepted by the parser but not honored at runtime.
   // Preserved as-is in this rename commit; revisit separately if needed.
   if (fetch.refine === true || fetch.inherit === true) {
+    warnUnknownFetchKeys(fetch, 'refine')
     if (fetch.inherit === true && fetch.refine !== true) {
       console.warn(
         "[uniweb] 'fetch: { inherit: true }' is deprecated; rename to 'fetch: { refine: true }'. " +
@@ -288,6 +333,7 @@ export function parseFetchConfig(fetch) {
 
   // Collection reference: { collection: 'articles', limit: 3 }
   if (fetch.collection) {
+    warnUnknownFetchKeys(fetch, 'collection')
     if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
       path: collectionDataUrl(fetch.collection),
@@ -308,6 +354,7 @@ export function parseFetchConfig(fetch) {
     }
   }
 
+  warnUnknownFetchKeys(fetch, 'source')
   const {
     path,
     url,

package/src/site/foundation-ref.js

@@ -0,0 +1,207 @@
+/**
+ * Where a site's foundation lives — the ONE resolver for a `site.yml::foundation`
+ * declaration.
+ *
+ * ## Why this is a leaf and not part of the Vite config
+ *
+ * It began in `./config.js`, which imports a Vite plugin. That made it unreachable
+ * from any lane that must not pull Vite — and the sync lane, needing exactly this
+ * answer, grew its own weaker copy instead (`../uwx/collections.js`), which read
+ * `package.json` `dependencies.foundation`: a key no current template produces, so
+ * it returned null for every scaffolded site. A third copy in the CLI describes
+ * itself as mirroring "a subset of" this one.
+ *
+ * Three implementations of one question, none of which agreed, and the cause was
+ * a pure function sitting behind a bundler import. So it moved here, with no
+ * dependency beyond `node:fs` and `node:path`, the same reason `@uniweb/core`'s
+ * `route-match` and `data-paths` are leaves.
+ *
+ * ## What it answers, and what it refuses
+ *
+ * A site names its foundation; it does not name a path. This turns that name into
+ * a location, or says it is a URL, or refuses — loudly — when the declaration is a
+ * shape we do not support.
+ *
+ * ⛔ **A site's `package.json` is CLI scaffolding, not part of the site.** The
+ * `file:` dep is consulted, but keyed by the DECLARED name from `site.yml` — the
+ * declaration leads, and the manifest is one of the places an answer may be found.
+ * Reversing that (starting from the manifest) is what the weaker copies did.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+
+/**
+ * Detect foundation type from the foundation config value
+ *
+ * Foundations are runtime federated modules, never npm packages — there is
+ * no fall-through to `node_modules`. A foundation reference resolves to one
+ * of two types:
+ *
+ *   - `'local'` — workspace-local source (sibling directory, file: dep, or
+ *     `../../foundations/<name>/`). The build inlines or runtime-links it
+ *     depending on the operating mode.
+ *   - `'url'`  — loaded by URL at runtime. Two URL shapes:
+ *       - `@org/name@ver`   → catalog ref (resolves against the registry CDN)
+ *       - `https://...`    → arbitrary URL
+ *
+ * Versionless registry refs (`@org/name`) are rejected with a specific error —
+ * they were a silent fall-through before. Versionless names that don't match
+ * any local resolution path are also rejected, with guidance toward the right
+ * shape.
+ *
+ * @param {string|Object} foundation - Foundation config from site.yml
+ * @param {string} siteRoot - Path to site directory
+ * @returns {{ type: 'local'|'url', name?: string, url?: string, cssUrl?: string, path?: string }}
+ * @throws {Error} when the declaration shape is invalid (versionless registry
+ *   ref, unknown name with no local match, etc.)
+ */
+export function detectFoundationType(foundation, siteRoot) {
+  // Object form with explicit URL
+  if (foundation && typeof foundation === 'object') {
+    if (foundation.url) {
+      return {
+        type: 'url',
+        url: foundation.url,
+        cssUrl: foundation.css || foundation.cssUrl || null
+      }
+    }
+    // Object form with name
+    foundation = foundation.name || 'foundation'
+  }
+
+  // String form
+  const name = foundation || 'foundation'
+
+  // Check if it's a URL
+  if (name.startsWith('http://') || name.startsWith('https://')) {
+    // Try to infer CSS URL from JS URL
+    const cssUrl = name.replace(/\.js$/, '.css').replace(/foundation\.js/, 'assets/style.css')
+    return {
+      type: 'url',
+      url: name,
+      cssUrl
+    }
+  }
+
+  // Catalog registry ref: `@org/name@version`.
+  //
+  // A build does NOT turn this into a URL. Where a foundation is served is the
+  // host's to say — a serve location is READ (from backend discovery, or from an
+  // upload plan's `serve_base`), never reconstructed. `@uniweb/cli`'s
+  // DISCOVERY_DEFAULTS carries no serve-root default for exactly this reason.
+  // A build is offline and backend-optional by design, so it has nothing to ask.
+  //
+  // A ref names a foundation in the Uniweb platform's catalog, and `uniweb
+  // publish` — the verb reserved for that target — has the platform resolve it,
+  // running no vite build. That is one hosting target among many. The others
+  // reach a host through `uniweb deploy --host=<adapter>` or `uniweb export`,
+  // and both need a concrete URL, which the site declares: the runtime accepts
+  // any URL, from any host.
+  //
+  // Until 2026-08-04 this returned `{base}/foundations/{ns}/{name}/{ver}/foundation.js`
+  // against a hardcoded host, overridable only through an env var that did not
+  // 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) {
+    throw new Error(
+      [
+        `Foundation "${name}" is a catalog ref, and a build cannot resolve it to a URL.`,
+        `Where a foundation is served is the host's to declare, so the build does not guess it.`,
+        ``,
+        `  • Deploying to another host (\`uniweb deploy --host=<adapter>\`), or taking`,
+        `    the build anywhere (\`uniweb export\`)? Declare the served URL in site.yml —`,
+        `    the runtime accepts any URL, from any host:`,
+        ``,
+        `      foundation: https://<host>/<path>/entry.js`,
+        ``,
+        `    or the object form when the stylesheet sits elsewhere:`,
+        ``,
+        `      foundation: { url: 'https://…/entry.js', cssUrl: 'https://…/assets/style.css' }`,
+        ``,
+        `  • Iterating locally?`,
+        `    Reference the workspace foundation by package name.`,
+        ``,
+        `  • Targeting the Uniweb platform?`,
+        `    \`uniweb publish\` has the platform resolve the ref — no build-time URL needed.`
+      ].join('\n')
+    )
+  }
+
+  // Versionless scoped names (`@org/name`) are valid as *handles* — they
+  // resolve through the local checks below (file: dep,
+  // workspace sibling) when the developer is iterating locally on a
+  // foundation that will eventually be published as `@org/name@ver`.
+  // Tianyu's uniweb.io site uses this shape:
+  //   site.yml:     foundation: '@uniweb/io'
+  //   package.json: "@uniweb/io": "file:../../foundations/io"
+  // The file: dep check below picks it up. If no local resolution exists
+  // either, the function throws below with a "missing version" hint.
+
+  // Check if it's a local workspace sibling (directory name matches package name)
+  const localPath = resolve(siteRoot, '..', name)
+  if (existsSync(localPath)) {
+    return {
+      type: 'local',
+      name,
+      path: localPath
+    }
+  }
+
+  // Check if it's a file: dependency (co-located projects where dir name ≠ package name)
+  // e.g. "marketing-foundation": "file:../foundation" in marketing/site/package.json
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(siteRoot, 'package.json'), 'utf8'))
+    const dep = pkg.dependencies?.[name]
+    if (dep && dep.startsWith('file:')) {
+      const filePath = resolve(siteRoot, dep.slice(5))
+      if (existsSync(filePath)) {
+        return {
+          type: 'local',
+          name,
+          path: filePath
+        }
+      }
+    }
+  } catch {}
+
+  // Check in foundations/ directory (for multi-site projects)
+  const foundationsPath = resolve(siteRoot, '..', '..', 'foundations', name)
+  if (existsSync(foundationsPath)) {
+    return {
+      type: 'local',
+      name,
+      path: foundationsPath
+    }
+  }
+
+  // Versionless scoped name that didn't resolve locally — likely a typo
+  // or a missing file: dep. Give a specific hint distinguishing the two
+  // common causes (forgot @version vs. forgot to wire the file: dep).
+  if (/^@[a-z0-9_-]+\//.test(name)) {
+    throw new Error(
+      `site.yml foundation: '${name}' did not resolve to a local source and no version was specified.\n` +
+      `If this is a workspace-local foundation, add it to the site's package.json:\n` +
+      `  "dependencies": { "${name}": "file:../path/to/foundation" }\n` +
+      `If this is a published catalog ref, include the version: '${name}@<version>' (e.g. '${name}@0.1.2').`
+    )
+  }
+
+  // Foundations are not npm packages. If we get here, the declaration
+  // didn't match a workspace sibling, a `file:` dep, a foundations/ entry,
+  // a registry ref, or a URL — none of the supported shapes. Fail with
+  // guidance rather than fall through to a node_modules lookup that will
+  // produce a confusing error later in the build.
+  throw new Error(
+    `site.yml foundation: '${name}' did not resolve.\n` +
+    `Foundations must be one of:\n` +
+    `  - a workspace-local sibling (a directory next to the site, named '${name}')\n` +
+    `  - a 'file:' dep in the site's package.json\n` +
+    `  - a directory in '../../foundations/${name}'\n` +
+    `  - a versioned registry ref: '@org/${name}@<version>'\n` +
+    `  - a full URL: 'https://...'\n` +
+    `Foundations are runtime federated modules, not npm packages — there is no fall-through to node_modules.`
+  )
+}

package/src/uwx/collection-source.js

@@ -111,10 +111,15 @@ export async function readCollectionRecords(collectionDir) {
   if (!existsSync(collectionDir)) {
     throw new Error(`uwx/collection-source: collection folder not found: ${collectionDir}`)
   }
-  const files = (await readdir(collectionDir))
+  const entries = await readdir(collectionDir, { withFileTypes: true })
+  const files = entries
+    .filter((e) => e.isFile())
+    .map((e) => e.name)
     .filter((f) => !f.startsWith('_') && SOURCE_EXTENSIONS.has(extname(f).toLowerCase()))
     .sort() // stable order — the wire's package digest depends on it
 
+  await reportNestedRecords(collectionDir, entries)
+
   const records = []
   for (const file of files) {
     const recs = await readOneFile(resolve(collectionDir, file))
@@ -122,3 +127,54 @@ export async function readCollectionRecords(collectionDir) {
   }
   return records
 }
+
+/**
+ * Report source records nested below a collection's top level.
+ *
+ * ⛔ THIS LANE IS FLAT AND THAT IS A CONTRACT, NOT AN OVERSIGHT. The delivery
+ * build reads a collection recursively — an author may organise records into
+ * branches, and `path` + the `under` predicate address them
+ * (`build/src/site/collection-processor.js`). Sync cannot follow yet: the
+ * folder shape agreed with the entity store is one level, records as direct
+ * leaves of a collection's branch, and going deeper needs that renegotiated
+ * with an explicit order axis rather than assumed.
+ *
+ * ⚠️ The two lanes therefore disagree, and the failure mode is the dangerous
+ * shape: a nested record BUILDS and RENDERS locally, then is simply absent from
+ * everything the sync produced — no error, no empty result, just a smaller set
+ * than the author is looking at. Losing records silently is the one outcome
+ * that must not happen, so this says so. It does not throw: a static site with
+ * nested collections is completely valid and must keep working, and an author
+ * who never syncs should not be blocked by a lane they do not use.
+ */
+async function reportNestedRecords(collectionDir, entries) {
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
+  if (dirs.length === 0) return
+
+  const nested = []
+  for (const dir of dirs) {
+    nested.push(...(await findSourceFiles(resolve(collectionDir, dir.name), dir.name)))
+  }
+  if (nested.length === 0) return
+
+  const shown = nested.slice(0, 5).join(', ')
+  const more = nested.length > 5 ? `, and ${nested.length - 5} more` : ''
+  console.warn(
+    `[uwx/collection-source] ${nested.length} record(s) below the top level of ` +
+      `"${basename(collectionDir)}" are NOT synced: ${shown}${more}. ` +
+      `Collection sync is one level deep; these build and render locally but are ` +
+      `absent from the synced set. Move them to the collection's top level to sync them.`
+  )
+}
+
+/** Every source file at or below `dir`, as paths relative to the collection root. */
+async function findSourceFiles(dir, rel) {
+  const out = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue
+    const relPath = `${rel}/${entry.name}`
+    if (entry.isDirectory()) out.push(...(await findSourceFiles(resolve(dir, entry.name), relPath)))
+    else if (SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) out.push(relPath)
+  }
+  return out
+}

package/src/uwx/collections-config.js

@@ -1,125 +1,9 @@
-// Resolve a site's collection configuration from the (optional, local-first)
-// `collections/collections.yml`, layered over the legacy `site.yml::collections`
-// and the zero-config subfolder-name convention.
-//
-// `collections.yml` is the co-located home for FILE-BASED collection declarations
-// (it sits with the data it describes). It is useful with NO backend at all — it
-// maps each subfolder to a data schema, declares query/display config, and can lay
-// out a VIRTUAL folder organization decoupled from the on-disk layout. (Sync holds no
-// folder uuid here — the backend owns the site's `@uniweb/folder`, keyed by the
-// site-content uuid.)
-//
-// Precedence (per-collection, per-key): collections.yml  >  site.yml::collections.
-// `site.yml::collections` stays valid for remote `url:` sources and back-compat.
-// When neither declares a schema, the subfolder-name convention fills it
-// (`articles` → `@/article`). Absent the file entirely, behavior is unchanged.
-
-import { join } from 'node:path'
-import { existsSync } from 'node:fs'
-import { readYamlFile } from '../site/content-collector.js'
-
-export const COLLECTIONS_YML_RELPATH = 'collections/collections.yml'
-
-// Naive English singularization — enough for the schema-name default (an explicit
-// `schema:` always overrides). `categories` → `category`, `boxes` → `box`,
-// `articles` → `article`, `team` → `team` (unchanged).
-function singularize(name) {
-  if (/[^aeiou]ies$/i.test(name)) return name.slice(0, -3) + 'y'
-  if (/(ses|xes|zes|ches|shes)$/i.test(name)) return name.slice(0, -2)
-  if (/[^s]s$/i.test(name)) return name.slice(0, -1)
-  return name
-}
-
-// Default data-schema ref for a collection with no explicit `schema:` — the
-// self-scope (`@/`) singular of its name. `@/` resolves to the local foundation's
-// `schemas/` (named-data-schemas), so this stays backend-independent. Exported so
-// the inverse (projection) can drop a `schema:` that merely restates this default,
-// keeping a projected collections.yml as terse as the author would have left it.
-export function defaultSchema(name) {
-  return `@/${singularize(name)}`
-}
-
-// Normalize one site.yml::collections entry (string shorthand or object) to the
-// internal decl shape. Paths here are already site-root-relative (legacy contract).
-function normalizeSiteDecl(name, decl) {
-  if (typeof decl === 'string') return { name, path: decl }
-  const d = decl && typeof decl === 'object' ? decl : {}
-  return { name, ...d }
-}
-
-// Normalize one collections.yml::collections entry. Its `path:` is relative to the
-// collections/ directory (default = the collection name); we lift it to a
-// site-root-relative path so downstream readers resolve it uniformly.
-function normalizeYmlDecl(name, decl) {
-  const d = decl && typeof decl === 'object' ? decl : {}
-  const rel = typeof d.path === 'string' ? d.path : name
-  return { name, ...d, path: `collections/${rel}` }
-}
-
-/**
- * Resolve the merged collection configuration for a site.
- *
- * @param {string} siteRoot - directory containing site.yml + collections/
- * @param {object} [opts]
- * @param {object} [opts.siteYml] - an already-read site.yml (avoids a re-read)
- * @returns {Promise<{
- *   folderSync: boolean,            // collections.yml `sync` (whole-folder opt-out)
- *   hasCollectionsYml: boolean,
- *   declarations: object,           // { name: decl }  — merged, schema-defaulted
- *   folders: Array|null,            // collections.yml `folders` (virtual org) or null
- * }>}
- */
-export async function resolveCollectionsConfig(siteRoot, opts = {}) {
-  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
-  const ymlPath = join(siteRoot, COLLECTIONS_YML_RELPATH)
-  const hasCollectionsYml = existsSync(ymlPath)
-  const colYml = hasCollectionsYml ? await readYamlFile(ymlPath) : {}
-
-  const declarations = {}
-
-  // Legacy site.yml::collections first (lower precedence).
-  const siteCols = siteYml?.collections
-  if (siteCols && typeof siteCols === 'object' && !Array.isArray(siteCols)) {
-    for (const [name, decl] of Object.entries(siteCols)) {
-      declarations[name] = normalizeSiteDecl(name, decl)
-    }
-  }
-
-  // collections.yml::collections overlay (higher precedence; per-key merge).
-  const ymlCols = colYml?.collections
-  if (ymlCols && typeof ymlCols === 'object' && !Array.isArray(ymlCols)) {
-    for (const [name, decl] of Object.entries(ymlCols)) {
-      const incoming = normalizeYmlDecl(name, decl)
-      declarations[name] = { ...(declarations[name] || {}), ...incoming, name }
-    }
-  }
-
-  // Schema default (subfolder-name convention) + `model:`→`schema:` synonym.
-  // `schemaExplicit` records whether the author asked for this schema: an explicit
-  // schema that fails to resolve is a hard error; a convention-defaulted one that
-  // fails to resolve soft-skips (so a delivery-only collection never breaks sync).
-  for (const decl of Object.values(declarations)) {
-    if (decl.schema) {
-      decl.schemaExplicit = true
-    } else if (decl.model) {
-      decl.schema = decl.model // migration synonym
-      decl.schemaExplicit = true
-    } else if (decl.path || !decl.url) {
-      decl.schema = defaultSchema(decl.name) // subfolder-name convention
-      decl.schemaExplicit = false
-    }
-  }
-
-  const folderSync = colYml?.sync !== false
-  return {
-    folderSync,
-    hasCollectionsYml,
-    declarations,
-    folders: Array.isArray(colYml?.folders) ? colYml.folders : null,
-  }
-}
-
-/** Path to the collections.yml file (whether or not it exists yet). */
-export function collectionsYmlPath(siteRoot) {
-  return join(siteRoot, COLLECTIONS_YML_RELPATH)
-}
+// Moved to `../site/collections-config.js` — a site's collection declarations are
+// a site-build question first, and keeping the resolver here meant the build could
+// not reach it and answered differently. Re-exported so no caller moved.
+export {
+  resolveCollectionsConfig,
+  collectionsYmlPath,
+  defaultSchema,
+  COLLECTIONS_YML_RELPATH,
+} from '../site/collections-config.js'

package/src/uwx/collections.js

@@ -3,7 +3,8 @@
 //
 // Each record becomes a section-keyed `$`-document (docs/reference/entity-content.md):
 // `$id` (the slug — the producer-local handle), `$model` (the Model by name), and
-// the brief section keyed by its name. The backend MINTS `$uuid` on first sync and
+// each SINGLE section keyed by its name — the brief plus any sibling singles, not
+// the brief alone. The backend MINTS `$uuid` on first sync and
 // returns it in the finalized response; the verb back-fills it into the source
 // file. A record that already carries `$uuid` (a prior back-fill) round-trips it
 // for restore-in-place. No id sidecar — identity is the file-embedded `$uuid` plus
@@ -15,11 +16,32 @@
 // via `toDataSchemaDeclaration`, the same path `uniweb register` uses), so it
 // stays offline.
 //
-// v1 scope: a FLAT record -> the Model's brief `single` section. Deferred:
-// multi / nested / non-brief sections (`$children` self-nesting), entity_ref /
-// item_ref / file fields, and remote (non-local) foundations.
+// Scope: this mapper implements the FLAT-RECORD shape — one source file whose
+// frontmatter keys are field names — so it walks the Model's `single` sections
+// and skips `multi` ones.
+//
+// ⛔ That is a property of THIS MAPPER, not of the schema system, and saying
+// otherwise has already misled twice. `multi` is first-class: the author writes
+// `many: true`, which lowers to IR `kind: 'multi'` and to wire `multiple: true`.
+// A Model whose ONLY section is `many` is a supported shape in its own right — a
+// root list, content authored as a bare array (`@uniweb/schemas` `rootListSection`;
+// `@std/nav` and `@std/form` are exactly this). Such a Model has no flat-record
+// surface at all, so it is not that its records "cannot be expressed" — it is
+// that they are not this shape, and this mapper only knows this shape.
+//
+// Nested sections (a `type: section` field) and entity_ref / item_ref / file
+// fields have no branch in `encodeFieldValue`; unverified either way.
+//
+// ⚠️ Two claims that used to sit here were stale and were removed rather than
+// re-worded, because both named real capabilities as missing: NON-BRIEF single
+// sections are handled (see `recordSections` below — the filter is `multiple !==
+// true`, not `brief === true`), and REMOTE foundations are handled through the
+// injected `opts.resolveModel`. A scope note that under-claims is worse than none:
+// it sends a reader to build what is already there.
 
 import { readFileSync, existsSync } from 'node:fs'
+import yaml from 'js-yaml'
+import { detectFoundationType } from '../site/foundation-ref.js'
 import { join, resolve } from 'node:path'
 
 import { resolveCollectionsConfig } from './collections-config.js'
@@ -161,10 +183,27 @@ export function collectionRecordsToEntities({
   if (!briefName) {
     throw new Error(`uwx/collections: Model ${declaration.name} has no brief section`)
   }
-  // The single sections a flat record can populate (the brief + sibling singles),
-  // and a global field→section map across them — for distributing frontmatter and
-  // flagging unknown keys. Field names are unique across a Model's sections (the
-  // declaration's own convention); a collision keeps the first occurrence.
+  // The single sections one record can populate (the brief + sibling singles).
+  //
+  // ⛔ `fieldByKey` IS NOT A FIELD→SECTION ROUTING TABLE, and must not be used as
+  // one. It answers exactly one question — "is this frontmatter key declared
+  // anywhere on this Model?" — for the unknown-key warning below. The assignment
+  // loop does not consult it: it walks each section and reads `record[key]` afresh.
+  //
+  // ⚠️ SO A FIELD NAME DECLARED IN TWO SECTIONS FANS OUT. The same frontmatter
+  // value is written into BOTH sections, each encoded per its own field's type — so
+  // a name shared by, say, a `string` and a `json` field yields one plausible value
+  // and one malformed one, silently. And flat frontmatter has no way to give the
+  // two fields different values in the first place: the representation is lossy
+  // exactly where names collide.
+  //
+  // ⛔ Nothing prevents this. A previous version of this comment asserted that
+  // "field names are unique across a Model's sections (the declaration's own
+  // convention)" — that is FALSE, no such convention holds, and nothing validates
+  // it: `resolve-data-schema.js` throws in 14 places and never checks this, and the
+  // only `unique_field` in the schema translator is a section-scoped constraint on
+  // an open map's KEY VALUE, which is unrelated. The invariant was asserted, relied
+  // on, and never provided.
   const recordSections = sectionEntries.filter(([, s]) => s && s.multiple !== true)
   const fieldByKey = new Map()
   for (const [, sec] of recordSections) {
@@ -327,21 +366,31 @@ function syncableCollections(declarations) {
 // Resolve the foundation dir from an explicit opt, else the site's `file:`
 // foundation dep. A local foundation supplies locally-defined Model declarations
 // offline; non-local Models are fetched via an injected resolver (see below).
+// Where this site's foundation lives, via the ONE resolver for that question
+// (`../site/foundation-ref.js` — a leaf precisely so this lane can import it).
+//
+// This used to be a private copy that read `package.json` `dependencies.foundation`
+// — a key no current template produces, since a site's foundation dep is keyed by
+// the foundation's package name (`"src": "file:../src"`). It returned null for
+// every scaffolded site, so the local-foundation path silently never ran: with a
+// `resolveModel` wired the caller fell back to the backend, and without one every
+// collection soft-skipped to delivery-only.
+//
+// The site declares its foundation in `site.yml`; the resolver turns that
+// declaration into a location. A declaration it refuses (a versionless registry
+// ref, an unknown name) is not this function's error to raise — the caller decides
+// whether a local foundation was required — so a throw becomes "no local
+// foundation" here and the caller's `required` flag still owns the message.
 function resolveFoundationDir(siteRoot, opts) {
   if (opts.foundationDir) return resolve(opts.foundationDir)
-  const pkgPath = join(siteRoot, 'package.json')
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-      const dep = pkg.dependencies?.foundation || pkg.devDependencies?.foundation
-      if (typeof dep === 'string' && dep.startsWith('file:')) {
-        return resolve(siteRoot, dep.slice('file:'.length))
-      }
-    } catch {
-      // fall through to the not-found error below
-    }
+  try {
+    const siteYml = yaml.load(readFileSync(join(siteRoot, 'site.yml'), 'utf8')) || {}
+    if (!siteYml.foundation) return null
+    const info = detectFoundationType(siteYml.foundation, siteRoot)
+    return info?.type === 'local' && info.path ? info.path : null
+  } catch {
+    return null
   }
-  return null
 }
 
 // Load the local foundation's built schema.json (the source of locally-defined
@@ -477,6 +526,30 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
   const entities = []
   const index = []
   const warnings = []
+
+  // ⛔ `@/x` IS A FOUNDATION-RELATIVE ALIAS AND MUST BE RESOLVED BEFORE IT SHIPS.
+  //
+  // `register` resolves it (`uwx/registry-package.js` builds `scoped` from the
+  // publish scope and applies it to BOTH the declaration's name and its refs), so
+  // a foundation's `@/member` is stored as `@org/member`. This path did NOT, and
+  // carried the alias verbatim into `$model` and `models_required.name_at_export`.
+  //
+  // ⚠️ The backend resolves Models BY NAME and never mints, so an unresolved alias
+  // is refused at restore with a message about a missing Model — which reads as a
+  // registration problem rather than a producer one. Measured 2026-08-27 on a live
+  // manor: `register` had already stored `@proximify/member` from the same alias,
+  // and the push then named `@/member`. One CLI, two paths, one resolver.
+  //
+  // ⭐ Resolving BEFORE `declarationFor` is what keeps this to one line of behaviour:
+  // `resolveDeclaration` already matches a fully-qualified name against the
+  // foundation's `@/`-keyed `dataSchemas`, so a resolved name looks up correctly and
+  // `declaration.name` — the value that becomes `$model` — is the resolved one.
+  const selfScopeOrg =
+    typeof opts.org === 'string' ? opts.org.replace(/^@/, '').replace(/\/.*$/, '') : ''
+  const resolveSelfScope = (ref) =>
+    typeof ref === 'string' && ref.startsWith('@/') && selfScopeOrg
+      ? `@${selfScopeOrg}/${ref.slice(2)}`
+      : ref
   // Collections that resolved no data schema (the convention-default soft-skip
   // below) — not synced as folder entities. The composite deploy delivers these
   // statically (the "data ball") instead, so the caller can route them there.
@@ -486,7 +559,18 @@ export async function buildCollectionEntities(siteRoot, opts = {}) {
   // reuse a slug).
   const seen = new Set()
   for (const { name, decl } of mapped) {
-    const modelName = decl.schema || decl.model
+    const declaredModel = decl.schema || decl.model
+    const modelName = resolveSelfScope(declaredModel)
+    // 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.
+    if (modelName === declaredModel && typeof declaredModel === 'string' && declaredModel.startsWith('@/')) {
+      warnings.push(
+        `collection "${name}": \`${declaredModel}\` is foundation-relative and no org is known, ` +
+          `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.`
+      )
+    }
     const declaration = await declarationFor(modelName)
     if (!declaration) {
       // A convention-defaulted schema (subfolder-name) that doesn't resolve is a