uniweb 0.60.0 → 0.62.0

package/src/backend/site-sync.js

@@ -12,7 +12,7 @@
  */
 
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, relative, isAbsolute } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { humanBytes } from '../utils/bytes.js'
@@ -276,17 +276,17 @@ const readMap = (siteDir, backend, key) => {
  * Drop every cache map that describes a BACKEND site, when this clone is bound to
  * none. Returns the names dropped (empty when there was nothing to do).
  *
- * `.uniweb/sync-cache.json` holds five maps keyed by *unit path* — item uuids,
- * content hashes, the injections those hashes were taken over, entity base versions,
- * unit bases — and a unit path (`site.yml`, `pages/about/about.md`) is the same
- * string for every site. So the cache does not
- * self-invalidate when the site's uuid goes away (a delete in the app, or
- * `uniweb forget`): it keeps describing the site this folder used to be.
+ * Five maps are keyed by *unit path* — item uuids (`sync.json`'s `items`) and, in
+ * `.uniweb/backend-cache.json`, content hashes, the injections those hashes were
+ * taken over, entity base versions and unit bases — and a unit path (`site.yml`,
+ * `pages/about/about.md`) is the same string for every site. So nothing in them
+ * self-invalidates when the site's uuid goes away: they keep describing the site
+ * this folder used to be.
  *
- * Which is a state we ACTIVELY TELL PEOPLE TO ENTER. The 404 guidance on a
- * uuid-bound lane says to clear `$uuid` to re-publish as a new site — the documented
- * recovery after a site is deleted in the app. Following it left the stale maps in
- * place, and the next publish failed two ways:
+ * Which was a state we ACTIVELY TOLD PEOPLE TO ENTER. Until 2026-09-21 the 404
+ * guidance on a uuid-bound lane said to clear `$uuid` to re-publish as a new site —
+ * the documented recovery after a site is deleted in the app. Following it left the
+ * stale maps in place, and the next publish failed two ways:
  *
  *   - **item uuids** — the new site's document carried the OLD site's item
  *     identities, and the backend correctly refused: *"item uuid … is already
@@ -298,6 +298,9 @@ const readMap = (siteDir, backend, key) => {
  *     not change** — a partial site, published successfully, with nothing to
  *     indicate it.
  *
+ * The guidance is `uniweb forget --backend <url>` now, which removes the uuid and the
+ * maps together, so following it no longer leads here.
+ *
  * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
  * the clone look bound before the check runs.
  */
@@ -377,13 +380,13 @@ export function clearRemoteSyncStateIfUnbound(siteDir, backend) {
     return []
   }
 
-  // Two ways the cache can describe a site this clone is not working with:
+  // Two ways the maps can describe a site this clone is not working with:
   //
-  //   1. UNBOUND — no `$uuid` at all, so there is no backend site for any of it to
-  //      be about. This is the state the documented "clear `$uuid` to re-publish as
-  //      a new site" recovery puts you in.
-  //   2. BOUND TO A DIFFERENT SITE — `$uuid` names one site and the cache was
-  //      written for another. Reachable in one step: the create mints a uuid and
+  //   1. UNBOUND — no site uuid for this backend, so there is no backend site for any
+  //      of it to be about. This was the state the old "clear `$uuid` to re-publish
+  //      as a new site" recovery put you in; `uniweb forget` clears the maps with it.
+  //   2. BOUND TO A DIFFERENT SITE — this backend's site uuid names one site and the
+  //      cache was written for another. Reachable in one step: the create mints a uuid and
   //      writes it BEFORE the push, so a push that then fails leaves exactly this.
   //      Without the identity stamp it is invisible, and every later publish fails
   //      the same way with no path out but deleting `.uniweb/` by hand.
@@ -458,10 +461,11 @@ export function readSyncCache(siteDir, backend) {
  * exact shape `emitSyncPackages` takes back as opts.
  *
  * ⛔ **Only the ones nothing else records.** `assetIds` is deliberately NOT banked
- * here even though the emit applies it: `assets.json` is COMMITTED project state
- * holding exactly that map (local ref → `{id, ext}`), written by the same push, and
- * a gitignored second copy would be a second thing to disagree — the reason that
- * file itself refuses to hold a serve URL. It also has the worse lifetime of the
+ * here even though the emit applies it: this backend's `assets` in `sync.json` is
+ * COMMITTED project state holding exactly that map (local ref → `{id, ext}`), written
+ * by the same push, and a gitignored second copy would be a second thing to
+ * disagree — the reason that map itself holds a fingerprint of a serve URL and never
+ * the URL. It also has the worse lifetime of the
  * two: `clearRemoteSyncState` wipes this cache, and the committed map correctly
  * survives. ⇒ Bank what a reader cannot re-derive; re-derive the rest.
  *
@@ -479,7 +483,7 @@ export function readSyncCache(siteDir, backend) {
  * zero HTTP requests, a property the cross-client flows rely on). ⚠️ Note the serve
  * URL is REPLAYED, never composed: we re-use the string the host handed us, which is
  * a different act from reconstructing one, and the distinction is the same one that
- * keeps `assets.json` id-only. An asset genuinely new to the site has no recorded
+ * keeps the asset map in `sync.json` to ids and a fingerprint. An asset genuinely new to the site has no recorded
  * mapping and still reads as changed, which is correct.
  */
 export function readAppliedInjections(siteDir, backend) {
@@ -494,10 +498,11 @@ export function readAppliedInjections(siteDir, backend) {
  * leftover from an earlier push describing hashes it no longer matches.
  *
  * `assetIds` is dropped rather than stored — see readAppliedInjections: it has a
- * committed source of truth in `assets.json`, and the reader re-derives it there.
+ * committed source of truth in `sync.json` (this backend's `assets`), and the reader
+ * re-derives it there.
  */
 export function writeSyncCache(siteDir, backend, hashes, applied) {
-  const { assetIds: _inAssetsJson, ...bankable } = applied || {}
+  const { assetIds: _inSyncJson, ...bankable } = applied || {}
   updateSyncCache(siteDir, backend, { hashes, applied: bankable })
 }
 
@@ -643,14 +648,16 @@ export function writeItemUuids(siteDir, backend, map) {
 /**
  * The org this site was created under, as `@handle`, or null.
  *
- * Read back from `site.yml::$org` (stored bare — see `writeSiteOrg`) and re-dressed
- * with the `@` the CLI and the wire both use. Callers pass it as `--as-org`'s default
- * so an org named once, at create, does not have to be re-typed on every later push.
+ * Read back from `backend`'s `site.org` in `sync.json` (stored bare — see
+ * `writeSiteOrg`) and re-dressed with the `@` the CLI and the wire both use. Callers
+ * pass it as `--as-org`'s default so an org named once, at create, does not have to
+ * be re-typed on every later push.
  *
  * Deliberately NOT a fallback for the flag: an explicit `--as-org` always wins and
  * rides verbatim, so this can only add a value where the CLI previously sent none.
  *
  * @param {string} siteDir
+ * @param {string} backend - the origin whose record to read
  * @returns {string|null}
  */
 export function readSiteOrg(siteDir, backend) {
@@ -697,15 +704,20 @@ function recordSiteOrg(siteDir, backend, asOrg) {
  * to several orgs could put a company site, and the storage it bills, somewhere
  * they never named.
  *
- * `register` has refused to guess a scope for the foundation lane since it shipped
- * (`deriveScope` → `package.json::uniweb.scope`). This is the same refusal, one
- * lane over.
+ * `register` resolves a foundation's scope in the same order — explicit, then
+ * recorded (`package.json::uniweb.scope`), then asked (`deriveScope`) — with one
+ * difference: non-interactive, it PICKS the one org you belong to, else your
+ * personal org, else the primary, and says which. This refuses instead, because a
+ * site's owner is the one-shot decision above. ⚠️ Until 2026-09-21 this said
+ * `register` "has refused to guess a scope", which is wrong for a non-interactive
+ * run by anyone with an org.
  *
  * Order, and only the last step is new:
  *   1. `--as-org @org`      — explicit, rides verbatim
  *   2. `--personal`         — explicit "no org, I mean it" → sends NO `as_org`
- *   3. `site.yml::$org`     — recorded at this site's own create
- *   4. the site already exists (`$uuid`) → null; ownership is settled, ask nothing
+ *   3. the recorded org     — `sync.json`, written at this site's own create
+ *   4. the site already exists on this backend (a recorded uuid) → null; ownership
+ *      is settled, ask nothing
  *   5. otherwise ASK (TTY) or REFUSE (non-interactive)
  *
  * ⛔ **`--personal` sends no `as_org`, and is NOT the same as `--as-org @<handle>`.**
@@ -1062,10 +1074,12 @@ async function recordAndDescribeOwner({
 /**
  * Guarantee we have per-item identity before an identity-bearing push.
  *
- * Fires only when the site HAS been pushed before (`$uuid` in site.yml) but the
- * cache is empty — a fresh `git clone`, or a deleted `.uniweb/`. One read of the
- * backend's current document, no file writes, no `uniweb pull`. A first-ever push
- * legitimately has nothing to fetch and is left alone.
+ * Fires only when the site HAS been pushed to this backend before (its uuid is in
+ * `sync.json`) but that backend's item map there is empty. One read of the
+ * backend's current document, recorded into that map — no content file is written,
+ * and no `uniweb pull`. A first-ever push legitimately has nothing to fetch and is
+ * left alone. (The map sat in the gitignored cache until 2026-09-20, so a fresh
+ * `git clone` or a deleted `.uniweb/` was what emptied it; it is committed now.)
  *
  * @returns {Promise<Object<string,string>>} the map (possibly empty)
  */
@@ -1129,12 +1143,11 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   //     for a cache written before this was banked (and for a never-pushed site),
   //     which is the pre-fix behaviour and self-heals on the next push. It can never
   //     point at the wrong document: it is written with the hashes it belongs to.
-  //   · RE-DERIVED — asset identity, from the COMMITTED `assets.json` the same push
-  //     wrote. Reading the live file rather than a snapshot is what makes a moved
-  //     map (a teammate's push, a pull) read as changed instead of matching a copy
-  //     of itself.
-  //   · RECORDED — the site's own org, from `site.yml::$org`, written by the push
-  //     that banked these hashes.
+  //   · RE-DERIVED — asset identity, from this backend's COMMITTED asset map in
+  //     `sync.json`, which the same push wrote. Reading the live file rather than a
+  //     snapshot is what makes a moved map (a teammate's push, a pull) read as
+  //     changed instead of matching a copy of itself.
+  //   · RECORDED — the site's own org, from `sync.json` (this backend's `site.org`).
   //
   // ⛔ THE ORG IS NOT OPTIONAL HERE, AND OMITTING IT WAS SILENT. It is what resolves
   // a foundation-relative `@/member` into the `@org/member` the push shipped and
@@ -1164,12 +1177,17 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
  *
  *   · BANKED     the injections the push applied before hashing — serve URLs and
  *                the pinned foundation ref, which only a round trip produces.
- *   · RE-DERIVED asset identity, from the COMMITTED `assets.json`, so a moved map
- *                reads as changed rather than matching a copy of itself.
+ *   · RE-DERIVED asset identity, from this backend's COMMITTED asset map in
+ *                `sync.json`, so a moved map reads as changed rather than matching
+ *                a copy of itself.
  *   · RECORDED   the site's org, which resolves a foundation-relative `@/x` into
  *                the `@org/x` the push keyed its hashes by, and the collection
- *                identity a push stamps — so `status` hashes the same document a
- *                push would send rather than one missing a section's `$uuid`s.
+ *                identity a push stamps, so the document is the one a push builds.
+ *                ⚠️ Identity is parity, not correctness: `entityContentHash` strips
+ *                `$`-sigils, so a query's `$uuid` never moves a hash (measured
+ *                2026-09-21). This read no backend from 2026-09-20 to 2026-09-21 —
+ *                an empty map — which is why no `status` ever showed it, and why this
+ *                bullet was then misread as naming a live defect.
  *
  * Offline by design — measured at zero HTTP requests, a property the cross-client
  * flows rely on.
@@ -1184,7 +1202,7 @@ async function comparisonEmit(
   // honest rather than a default — no backend, no known ids.
   const assetIds = backend ? readBackendState(siteDir, backend).assets || {} : {}
   const org = readSiteOrg(siteDir, backend)
-  const queryUuids = readQueryUuids(siteDir)
+  const queryUuids = readQueryUuids(siteDir, backend)
   return emitSyncPackages(siteDir, {
     backend,
     resolveModel: makeModelResolver({ client: null, offline: true }),
@@ -1252,6 +1270,8 @@ export async function pushSyncPackages({
 
   const wrote = []
   let finalizedTotal = 0
+  // Records sent as drafts that the backend stored enabled — reported at the end.
+  let draftsNotKept = []
 
   // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
   // returning the client's Response promise (so the "Pushing …" line prints before the
@@ -1426,12 +1446,17 @@ export async function pushSyncPackages({
         // this branch named only the deletion and went straight to "clear `$uuid`" — and
         // that advice, followed for the OTHER cause, destroys a live binding: the site is
         // fine, you are simply pointed at the wrong backend, and clearing the uuid orphans
-        // it. (A wrong-BACKEND binding can no longer occur — identity is read per
-        // origin from sync.json — so what reaches here is a site deleted on this backend.)
-        // Before any request goes
-        // out, so reaching here usually does mean a deletion; "usually" is not "always"
-        // (a project predating `$backend` records no scope to check), which is why the
-        // cheap cause is still named before the destructive fix.
+        // it. The uuid sent here is the one this project recorded for THIS origin
+        // (sync.json), so another backend's uuid cannot reach it; what does is a site
+        // this origin no longer has — deleted there, or a backend rebuilt at the same
+        // address. Being logged in to a backend you did not mean is still the cheaper
+        // thing to rule out, so it still comes first. (Until 2026-09-21 this paragraph
+        // leaned on a scope check against `site.yml::$backend`; both were deleted on
+        // 2026-09-20.)
+        //
+        // ⛔ The fix for a deletion was "clear `$uuid` from site.yml" until 2026-09-21 — a
+        // key that left site.yml the day before, so the advice named nothing to clear.
+        // The binding is this backend's section of sync.json, and `forget` drops it.
         note(
           `The backend at ${client.origin} has no site with uuid ${boundUuid}.`
         )
@@ -1442,7 +1467,7 @@ export async function pushSyncPackages({
           `  wrong backend  →  uniweb login --backend <the right one>   (nothing is lost)`
         )
         note(
-          `  deleted in the app  →  clearing \`$uuid\` from site.yml re-publishes it as a NEW site`
+          `  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) {
@@ -1451,8 +1476,8 @@ export async function pushSyncPackages({
         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: delete the deployed site and ' +
-            'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
+            '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).`
         )
       }
       if (body) note(body.slice(0, 800))
@@ -1487,8 +1512,8 @@ export async function pushSyncPackages({
 
   // Lane 1 — site-content (the site is born here; it must exist before its folder). A
   // known site uuid → UPDATE by uuid; none → CREATE (the backend mints + adopts the site
-  // and returns its uuid, which we record into site.yml). `boundSiteUuid` carries the
-  // minted/known uuid forward to key the folder push.
+  // and returns its uuid, which we record in sync.json, under this backend).
+  // `boundSiteUuid` carries the minted/known uuid forward to key the folder push.
   let boundSiteUuid = siteContentUuid
   // Post-write tokens harvested from every lane, persisted once at the end so a
   // partial push (lane 1 ok, lane 2 refused) still banks what actually landed —
@@ -1556,8 +1581,8 @@ export async function pushSyncPackages({
       // ⭐ BANK COLLECTION-DECLARATION IDENTITY, the sibling of the folder's
       // placements below. These items have no file to back-fill into — they all
       // come from one `collections/collections.yml` — so the only place their
-      // `$uuid` can live is the cache, keyed by the name the backend enforces
-      // unique. Without it every push after the first re-sends the whole
+      // `$uuid` can live is `sync.json` (this backend's `queries` map), keyed by the
+      // name the backend enforces unique. Without it every push after the first re-sends the whole
       // `collections` section uuid-less and is refused.
       if (siteFinalizedDoc) {
         const recordIds = collectQueryUuids(siteFinalizedDoc)
@@ -1581,11 +1606,11 @@ export async function pushSyncPackages({
       writeSiteEntityUuid(siteDir, client.origin, minted)
       updateSyncCache(siteDir, client.origin, { siteUuid: minted })
       boundSiteUuid = minted
-      wrote.push('recorded site $uuid in site.yml')
+      wrote.push('recorded the site in sync.json')
       // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
       // which is gated on the site having local media). Both mint a site, so both
-      // owe the same record — recording it in only one place would make `$org`
-      // present or absent depending on whether the site happens to have images.
+      // owe the same record — recording it in only one place would make the recorded
+      // owner present or absent depending on whether the site happens to have images.
       // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
       // and `site` (NOT beside `finalized`, which lives at report.finalized).
       const createdOrg = await recordAndDescribeOwner({
@@ -1596,7 +1621,7 @@ export async function pushSyncPackages({
         note
       })
       if (createdOrg)
-        wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
+        wrote.push(`recorded its owner (${createdOrg}) in sync.json`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
@@ -1635,6 +1660,7 @@ export async function pushSyncPackages({
     }
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    draftsNotKept = bf.notKeptAsDrafts || []
     if (bf.updated.length)
       wrote.push(`wrote ${bf.updated.length} record file(s)`)
     // ⭐ BANK THE FOLDER'S PLACEMENT IDENTITY. The records carry their own `$uuid`
@@ -1700,5 +1726,21 @@ export async function pushSyncPackages({
       )
     }
   }
+  // ⛔ A DRAFT THE BACKEND STORED ENABLED FAILS THE PUSH, and only here, after every
+  // piece of sync state above is banked: the push itself happened, and the next one must
+  // see it. What must not happen is a publish that goes live on top of it, which is why
+  // the exit code carries it (publish stops on anything but 0). The files keep their
+  // `draft: true` (see backfillEntityUuids).
+  if (draftsNotKept.length) {
+    const one = draftsNotKept.length === 1
+    const shown = draftsNotKept.map((p) => (isAbsolute(p) ? relative(siteDir, p) : p))
+    error(
+      `This backend did not keep ${one ? 'a record' : `${shown.length} records`} as a draft, ` +
+        `so ${one ? 'it' : 'they'} would be delivered once the site is published:\n  ` +
+        shown.join('\n  ') +
+        '\n  The backend does not support `draft: true` yet. Once it does, push again with --all.'
+    )
+    return { exitCode: 1, boundSiteUuid, finalizedTotal, wrote }
+  }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }

package/src/commands/add.js

@@ -16,7 +16,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 import prompts from 'prompts'
 import yaml from 'js-yaml'
-import { resolveFoundationSrcPath } from '@uniweb/build'
+import { resolveFoundationSrcPath, readFoundationName } from '@uniweb/build'
 import {
   scaffoldFoundation,
   scaffoldSite,
@@ -42,6 +42,10 @@ import {
   resolveUniqueName
 } from '../utils/names.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
+import {
+  normalizeFoundationName,
+  ensureFoundationName
+} from '../utils/foundation-name.js'
 import {
   detectPackageManager,
   detectWorkspacePm,
@@ -366,6 +370,12 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   let { packageName } = placement
   const fullPath = join(rootDir, relativePath)
 
+  // The foundation's own name — what it registers as, written to main.js — is
+  // the name asked for, before any workspace suffix below; with none (`src`),
+  // the project's.
+  const askedName =
+    normalizeFoundationName(packageName) || normalizeFoundationName(projectName)
+
   // Validate the derived package name (format + reserved-name check). The
   // auto-derived `src` default is grandfathered in (`src` IS reserved
   // but `src` is the convention for "the package that lives in src/").
@@ -435,10 +445,15 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   }
 
   // Scaffold
+  const registryName = await unclaimedFoundationName(rootDir, [
+    askedName,
+    normalizeFoundationName(packageName)
+  ])
   await scaffoldFoundation(
     fullPath,
     {
       name: packageName,
+      registryName,
       projectName,
       isExtension: false
     },
@@ -447,9 +462,11 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
     }
   )
 
-  // Apply template content if --from specified
+  // Apply template content if --from specified. Its main.js replaces the
+  // scaffolded one, so the name is given again unless the template names it.
   if (opts.from) {
     await applyFromTemplate(opts.from, 'foundation', fullPath, projectName)
+    ensureFoundationName(fullPath, registryName)
   }
 
   // Register the package in pnpm-workspace.yaml — by exact path, not by glob.
@@ -685,11 +702,18 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
     process.exit(1)
   }
 
-  // Scaffold foundation with extension flag
+  // Scaffold foundation with extension flag. Its name — what it registers as —
+  // is the one asked for, not the package's suffixed one, unless a foundation in
+  // the workspace already registers as that.
+  const registryName = await unclaimedFoundationName(rootDir, [
+    normalizeFoundationName(name),
+    normalizeFoundationName(extensionPackageName)
+  ])
   await scaffoldFoundation(
     fullPath,
     {
       name: extensionPackageName,
+      registryName,
       projectName,
       isExtension: true
     },
@@ -701,6 +725,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   // Apply template content if --from specified
   if (opts.from) {
     await applyFromTemplate(opts.from, 'extension', fullPath, projectName)
+    ensureFoundationName(fullPath, registryName)
   }
 
   // Update workspace globs
@@ -848,12 +873,18 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
 
   const progressCb = (msg) => info(`  ${msg}`)
 
-  // Scaffold foundation (folder: src/, package name: <project>-src)
+  // Scaffold foundation (folder: src/, package name: <project>-src, name — what
+  // it registers as — <project>)
   info(`Creating foundation: ${foundationPkgName}...`)
+  const registryName = await unclaimedFoundationName(rootDir, [
+    normalizeFoundationName(name),
+    normalizeFoundationName(foundationPkgName)
+  ])
   await scaffoldFoundation(
     join(projectDir, 'src'),
     {
       name: foundationPkgName,
+      registryName,
       projectName,
       isExtension: false
     },
@@ -882,6 +913,7 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
       join(projectDir, 'src'),
       projectName
     )
+    ensureFoundationName(join(projectDir, 'src'), registryName)
     await applyFromTemplate(
       opts.from,
       'site',
@@ -987,6 +1019,32 @@ function computeFoundationPath(sitePath, foundationPath) {
   return `file:${rel}`
 }
 
+/**
+ * The first of `candidates` that no foundation or extension in the workspace
+ * registers as — null when each is taken or missing, and `uniweb register` asks.
+ *
+ * A package name is kept unique by suffixing (`ui-ext`), but what a package
+ * REGISTERS as is its main.js name: two foundations named `ui` in one workspace
+ * would both register `@org/ui`, and the second would land on the first's
+ * version. Compared without scope, so `@acme/ui` counts as `ui`.
+ *
+ * @param {string} rootDir
+ * @param {Array<string|null>} candidates
+ * @returns {Promise<string|null>}
+ */
+async function unclaimedFoundationName(rootDir, candidates) {
+  const taken = new Set()
+  for (const f of await discoverFoundations(rootDir)) {
+    try {
+      const { name } = await readFoundationName(join(rootDir, f.path))
+      if (name) taken.add(name.replace(/^@[^/]+\//, ''))
+    } catch {
+      // An unreadable main.js — the build reports it; it claims no name here.
+    }
+  }
+  return candidates.find((c) => c && !taken.has(c)) || null
+}
+
 /**
  * Apply content from a template to a scaffolded package
  *

package/src/commands/clone.js

@@ -399,7 +399,7 @@ export async function clone(args = [], deps = {}) {
   // bytes on disk, not of what the scaffolder first wrote.
   recordWritten(
     siteDir,
-    ['site.yml', 'theme.yml', 'head.html', 'queries.yml', 'records.yml']
+    ['site.yml', 'theme.yml', 'head.html', 'queries.yml', join('records', 'folder.yml')]
       .map((f) => join(siteDir, f))
       .filter((p) => existsSync(p))
   )

package/src/commands/doctor.js

@@ -166,9 +166,9 @@ function loadSiteYml(dir) {
 /**
  * Diagnose the compiled-collection output directory.
  *
- * `public/<DATA_DIR>/` holds what the build compiles from `entities/`, and
- * nothing else — `entities/` + `records.yml` is the only supported way to provide
- * structured data. Two consequences, both checked here:
+ * `public/<DATA_DIR>/` holds what the build compiles from `records/`, and
+ * nothing else — `records/` is the only supported way to provide structured
+ * data. Two consequences, both checked here:
  *
  * 1. **The mapping is a bijection.** Every entry should be backed by a
  *    declared collection. An entry that isn't is stale — most often a
@@ -969,7 +969,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
   const dataDir = join(sitePath, 'public', DATA_DIR)
   // ⚠️ THE QUERIES, not the pool. `public/<DATA_DIR>/x.json` is a query's
   // MATERIALIZATION — one file per named query — so the bijection is with the
-  // declared queries, never with the schema folders under `entities/`.
+  // declared queries, never with the schema folders under `records/`.
   //
   // ⛔ BOTH HOMES, or this reports every compiled file as an orphan. A site that
   // keeps its queries in `queries.yml` has none in `site.yml`, and reading one
@@ -1045,7 +1045,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
       const body = existing === null ? '' : existing.replace(/\n*$/, '\n')
       writeFileSync(
         gitignorePath,
-        `${body}\n# Compiled query results — generated from entities/ + queries.yml\n${rule}\n`
+        `${body}\n# Compiled query results — generated from records/ + queries.yml\n${rule}\n`
       )
       fixed(`added ${rule} to ${gitignorePath}`)
       if (existsSync(dataDir)) {
@@ -1418,8 +1418,7 @@ export async function doctor(args = []) {
     }
 
     // `public/<DATA_DIR>/` is the build's output directory and nothing else —
-    // `entities/` + `records.yml` is the only supported way to provide structured
-    // data. That makes the mapping a bijection: every entry there should be backed
+    // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed
     // by a declared QUERY, so anything else is stale, and identifiable.
     //
     // It matters because the directory is written into the source tree rather

package/src/commands/i18n.js

@@ -319,7 +319,7 @@ async function runExtract(siteRoot, config, args) {
     const dataDir = join(siteRoot, 'public', DATA_DIR)
     if (!existsSync(dataDir)) {
       if (recordsOnly) {
-        error('No records found. Add entities under entities/ and list them in records.yml.')
+        error('No records found. Every file in records/<schema>/ is a record — add some there.')
         process.exit(1)
       }
       log(`${colors.dim}No records found in public/data/.${colors.reset}`)
@@ -1022,11 +1022,11 @@ async function runAudit(siteRoot, config, args) {
  * Usage:
  *   uniweb i18n init-freeform es pages/about hero
  *   uniweb i18n init-freeform es page-ids/installation intro
- *   uniweb i18n init-freeform es entities/article getting-started
+ *   uniweb i18n init-freeform es records/article getting-started
  */
 async function runInitFreeform(siteRoot, config, args) {
   const locale = args[0]
-  const pathType = args[1] // pages/about, page-ids/installation, entities/article
+  const pathType = args[1] // pages/about, page-ids/installation, records/article
   const sectionId = args[2] // hero, intro, getting-started
 
   if (!locale || !pathType || !sectionId) {
@@ -1035,11 +1035,20 @@ async function runInitFreeform(siteRoot, config, args) {
     log('  uniweb i18n init-freeform es pages/about hero')
     log('  uniweb i18n init-freeform es page-ids/installation intro')
     log(
-      `  uniweb i18n init-freeform es entities/article getting-started${colors.reset}`
+      `  uniweb i18n init-freeform es records/article getting-started${colors.reset}`
     )
     process.exit(1)
   }
 
+  // A path names a page by route, a page by id, or a record by its schema folder —
+  // and nothing else. Said up front: past this point an unknown kind would only
+  // surface as "source content not found", which names the wrong cause.
+  if (!/^(pages|page-ids|records)\//.test(pathType)) {
+    error(`Unknown kind of path: ${pathType}`)
+    log(`${colors.dim}A path starts with pages/, page-ids/ or records/ (a record's schema folder).${colors.reset}`)
+    process.exit(1)
+  }
+
   const localesPath = join(siteRoot, config.localesDir)
   const freeformDir = join(localesPath, 'freeform', locale)
 
@@ -1091,15 +1100,15 @@ async function runInitFreeform(siteRoot, config, args) {
           if (sourceContent) break
         }
       }
-    } else if (pathType.startsWith('entities/')) {
+    } else if (pathType.startsWith('records/')) {
       // ⛔ ADDRESSED BY THE RECORD, matching where the loader reads. The freeform
-      // tree is `entities/<schema dirs>/<slug>.md`; this used to take
+      // tree is `records/<schema dirs>/<slug>.md`; this used to take
       // `collections/<query>` and write a path nothing read — the loader moved
       // and this did not.
       //
       // The record's CONTENT still lives in a query's materialization, so the
       // query that covers this schema is resolved rather than named.
-      const poolDirs = pathType.replace('entities/', '')
+      const poolDirs = pathType.slice('records/'.length)
       const { resolveQueriesConfig, poolDirsForSchema } = await import('@uniweb/build/uwx')
       let queryName = null
       try {
@@ -1509,7 +1518,7 @@ async function runPrune(siteRoot, config, args) {
     // reads one (`freeformSourceIndex`, the build's own index): every path a section's
     // translation is read from — ⛔ until 2026-09-14 only `page-ids/<id>/…` on a page with
     // an `id`, so a route-addressed translation the page rendered was deleted — and only
-    // what the built content can see: never a record's translation (`entities/…`), and
+    // what the built content can see: never a record's translation (`records/…`), and
     // never one for a page whose sections the content does not carry.
     const { validPaths, canJudge } = freeformSourceIndex(siteContent)
 
@@ -1657,7 +1666,7 @@ ${colors.bright}File Structure:${colors.reset}
         .manifest.json       Staleness tracking
         pages/about/hero.md  Translated content for /about page, hero section
         page-ids/install/intro.md  Translated content by page ID
-        entities/article/getting-started.md
+        records/article/getting-started.md
 
 ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Hash-based workflow${colors.reset}
@@ -1677,7 +1686,7 @@ ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Free-form workflow (complete section replacement)${colors.reset}
   uniweb i18n init-freeform es pages/about hero
   uniweb i18n init-freeform es page-ids/installation intro
-  uniweb i18n init-freeform es entities/article getting-started
+  uniweb i18n init-freeform es records/article getting-started
   uniweb i18n status --freeform    # Show free-form translation status
   uniweb i18n update-hash es --all-stale  # Update hashes after review
   uniweb i18n move pages/docs/setup pages/getting-started