uniweb 0.60.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/core": "^0.29.6",
-    "@uniweb/kit": "^0.19.3",
-    "@uniweb/runtime": "^0.27.2",
+    "@uniweb/core": "^0.29.7",
+    "@uniweb/kit": "^0.19.4",
     "@uniweb/schemas": "^0.3.3",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/runtime": "^0.27.3",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.56.0",
+    "@uniweb/build": "^0.57.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -845,26 +845,26 @@ It is a small database, not a page tree. Three things, deliberately separate:
 ```
 site/
 ├── pages/
-├── entities/          # your stored things. The folder names their data schema
-│   ├── article/
+├── records/           # your site's records — every file here is one
+│   ├── article/       # the folder names their data schema
 │   │   ├── getting-started.md
 │   │   └── design-tips.md
 │   └── person/
 │       └── alice.yml
-├── records.yml        # what is PUBLISHED
+├── records.yml        # optional: sorts records into folders
 ├── queries.yml        # how content is REACHED
 └── site.yml
 ```
 
-**`entities/{schema}/` — the pool.** The folder names the data schema and nothing else:
+**`records/{schema}/` — the site's records.** Putting a file here is what makes it a record; nothing else lists it. The folder names the data schema and nothing else:
 
 | on disk | schema |
 |---|---|
-| `entities/article/…` | `@/article` — your foundation's own |
-| `entities/std/person/…` | `@std/person` — the shared standard set |
-| `entities/acme/project/…` | `@acme/project` — an org's |
+| `records/article/…` | `@/article` — your foundation's own |
+| `records/std/person/…` | `@std/person` — the shared standard set |
+| `records/acme/project/…` | `@acme/project` — an org's |
 
-Keep those folders flat: `entities/article/design-tips.md` works; `entities/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records.yml` instead.
+Keep those folders flat: `records/article/design-tips.md` works; `records/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records.yml` instead. A file whose name starts with `_` is not a record — somewhere to keep work in progress.
 
 **Four formats, one shape.** All of these produce the same records at runtime:
 
@@ -877,32 +877,22 @@ Keep those folders flat: `entities/article/design-tips.md` works; `entities/arti
 
 **One record per file, or many.** A single mapping at the top of a file makes one record and the filename stem becomes its `slug`. A top-level array (YAML/JSON) or a multi-entry `.bib` makes many, each carrying its own `slug`. You can mix both in one folder — an exported `refs.bib` beside a hand-written `extras.yml`.
 
-Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `published`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. `published: false` hides an item without deleting it; items with no `published` field are included.
+Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. **`draft: true` keeps a record off the live site without deleting it**: it is still a record, in `records/`, and `pnpm dev` shows it so you can preview it, but a build for hosting leaves it out — and `uniweb push` stops at it, naming it. (`published: false`, an older spelling, is refused.)
 
-**`records.yml` — listing an entity is what publishes it.** A file in `entities/` exists; listing it here makes it a record. Anything you leave out is a draft — no flag to set. **The common case is three lines:**
+**`records.yml` — optional, and only for folders.** Every record sits at the top of the site's records folder unless `records.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
 
 ```yaml
-- article/*.md
-- person/*.yml
-```
-
-A bare string is a path under `entities/`, naming one file or matching many.
-
-⚠️ **An empty `records.yml` is not the same as having none.** With no file, a build publishes every entity in `entities/`, and `uniweb push` leaves the published set alone. An empty file means "nothing is published": a build publishes none, and a push REMOVES what is published. The CLI asks before it does that.
-
-**Structure is for querying, not for navigation.** Add a `folder:` only when a query needs to ask for a *slice* of the pool rather than all of it — most sites never do:
-
-```yaml
-- article/2026-*.md
 - folder: archive
   label: The Archive
   records:
     - article/2025-*.md
 ```
 
-A query reads one branch with `scope: archive` — the folder and everything inside it (the older `where: { path: { under: … } }` is refused by the build). An entity belongs to one folder; if you want a computed subset, that is a query, not a second placement.
+A path under a folder is relative to `records/`, naming one file or matching many. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `records.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
+
+⚠️ **With a backend, `records/` is what `uniweb push` sends** — every record in it. A site with no `records/` at all leaves the backend's records alone; an *empty* `records/` removes them, and the CLI asks before it does. Records pushed to a backend are served once the site is published.
 
-**`queries.yml` — how content is reached.** A bare map of name → query. A query names a schema and the published records of that schema are its rows:
+**`queries.yml` — how content is reached.** A bare map of name → query. A query names a schema and the site's records of that schema are its rows:
 
 ```yaml
 recent:
@@ -912,7 +902,7 @@ recent:
 
 team:
   schema: '@std/person'
-  where: { published: { ne: false } }    # a predicate — see authoring/predicates.md
+  where: { active: true }                # a predicate — see authoring/predicates.md
 ```
 
 You can keep the same declarations under `queries:` in `site.yml` instead, if you would rather have one file.
@@ -944,7 +934,7 @@ pages/blog/
     └── article.md    # just `type: Article` — the record arrives automatically
 ```
 
-`entities/article/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
+`records/article/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
 
 **Link a card with `item.$route` — never compose the URL.** Every record a query delivers carries `$route`, the URL of the parametric page whose route query is that query (`/blog/design-tips`), wherever the list appears — the query's own page, the homepage, a sidebar. No page for the query, or no value for the field its URL is built from, means no `$route`, never a broken one. `detailPage: page:<id>` on a fetch links the records to another page instead. `$` marks a field the framework fills, so a record's own `route` field is left alone. ⛔ `route:` on a query is retired and stops the build.
 
@@ -1871,7 +1861,7 @@ A foundation can route a scope to a plain folder of schema files instead of a pa
 # pages/blog/page.yml
 fetch:
   query: recent
-  where: { published: true, tags: featured }
+  where: { tags: featured }
   sort: date desc
   limit: 3
 ```
@@ -2697,7 +2687,7 @@ Running `extract` before a build is the usual first mistake — it reads the com
 
 ```
 locales/freeform/es/pages/about/hero.md        # by page route
-locales/freeform/es/entities/article/x.md      # records work too
+locales/freeform/es/records/article/x.md       # records work too
 ```
 
 These are **body only — no frontmatter**; params and config still come from the source section. `uniweb i18n init-freeform es pages/about hero` creates one pre-filled and records a source hash, so `uniweb i18n status --freeform` can tell you when the original moved on (`update-hash` to acknowledge). `move`, `rename`, and `prune --freeform` keep them aligned when pages get reorganized.

package/src/backend/asset-download.js

@@ -7,9 +7,9 @@
  *
  * ## Where an asset lands, and why there are two answers
  *
- * - **The map knows it** (`assets.json`) — the file goes back to the path its
- *   author wrote. That is the whole reason the map is committed: a fresh clone
- *   restores `public/images/hero.png`, not a hash.
+ * - **The map knows it** (this backend's `assets` in `sync.json`) — the file goes
+ *   back to the path its author wrote. That is the whole reason the map is
+ *   committed: a fresh clone restores `public/images/hero.png`, not a hash.
  * - **The map does not know it** — this project has never held these bytes:
  *   authored in the app, or pushed from a machine whose map entry has not
  *   arrived. There is no local path to guess, so it lands at a **generic,
@@ -21,8 +21,8 @@
  * Identity rides beside the reference (`sync-package.js` stamps `assetId` next
  * to the serve URL), so the address is already on the node. Composing one would
  * mean holding the host's route layout — the coupling deleting `buildAssetUrl`
- * removed from this CLI, and the reason `assets.json` stores no URL either. An
- * id with no URL beside it is skipped, not guessed at.
+ * removed from this CLI, and the reason the asset map stores no URL either (only a
+ * fingerprint of one). An id with no URL beside it is skipped, not guessed at.
  *
  * ## ⛔ A failed download is a WARNING, never a failed pull
  *

package/src/backend/foundation-bring-along.js

@@ -39,6 +39,7 @@ import { execFileSync } from 'node:child_process'
 import { detectFoundationType, isExtensionUrl } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { isNonInteractive } from '../utils/interactive.js'
+import { publishScope } from '../utils/registry-orgs.js'
 import { compareSemverPrecedence } from '../utils/semver-precedence.js'
 
 /**
@@ -126,13 +127,17 @@ export function resolveLocalExtensions(siteDir, siteYml) {
 // as this did until 2026-09-17 — looked a `uniweb.id` foundation up under a name
 // the catalog does not have, so every push re-released it, and pinned the site
 // to that same wrong name.
+//
+// ⛔ And the scope goes through `publishScope`, as `register`'s does: `uniweb.scope`
+// may read `acme` as well as `@acme`, and until 2026-09-21 this joined it raw — so a
+// bare one looked the foundation up as `acme/src` and pinned the site to that.
 function foundationScopedName(dir) {
   try {
     const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
     const name = pkg?.uniweb?.id || pkg?.name
     if (typeof name === 'string' && name.startsWith('@')) return name
-    const scope = pkg?.uniweb?.scope
-    if (scope && name) return `${String(scope).replace(/\/+$/, '')}/${name}`
+    const scope = publishScope(pkg?.uniweb?.scope)
+    if (scope && name) return `${scope}/${name}`
     return null
   } catch {
     return null

package/src/backend/service-request.js

@@ -61,7 +61,8 @@ import { createHash } from 'node:crypto'
  * Rows are ordered by their serialized form and object keys sorted, so reordering
  * rows or keys in the file is not a change. It is not a request to move a line.
  *
- * @param {*} declared - the raw `site.yml::$services` / `$secrets` value
+ * @param {*} declared - the raw value: provisioned `services` / `secrets` rows (from
+ *   `sync.json`), what the site has stored for them, or `site.yml::publishLanguages`
  * @returns {string|null} 16 hex chars, or null when undeclared
  */
 export function fingerprintDeclaration(declared) {

package/src/backend/site-media.js

@@ -72,18 +72,18 @@ export async function uploadSiteMedia(
     warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
 
   const map = {}
-  // The identity half, for `assets.json`. The plan returns an authoritative
-  // `id`+`ext` for every entry INCLUDING a `present: true` dedup skip, so a
-  // re-push of unchanged media still records identity without moving bytes —
-  // which is what makes the committed map cheap to keep accurate.
+  // The identity half, for this backend's asset map in `sync.json`. The plan
+  // returns an authoritative `id`+`ext` for every entry INCLUDING a `present: true`
+  // dedup skip, so a re-push of unchanged media still records identity without
+  // moving bytes — which is what makes the committed map cheap to keep accurate.
   const ids = {}
   for (const ref of refs) {
     const entry = result.assetsByLocalUrl[ref]
     if (!entry) continue
     // `served` — a fingerprint of the address, never the address. It is how a pull
     // recognizes this asset where the reference is a bare string with no room for an
-    // id beside it (`info.preview`, `seo.image`, a section param); `assets.json`'s
-    // header says why a hash and not the URL.
+    // id beside it (`info.preview`, `seo.image`, a section param); the header of
+    // `@uniweb/build`'s asset-map.js says why a hash and not the URL.
     if (entry.id) {
       ids[ref] = {
         id: entry.id,

package/src/backend/site-sync.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.
- *
- * 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:
+ * 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 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 }),
@@ -1426,12 +1444,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 +1465,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 +1474,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 +1510,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 +1579,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 +1604,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 +1619,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

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

package/src/commands/publish.js

@@ -33,7 +33,7 @@
  *                                  FIRST publish of a site reads it — that create is
  *                                  what decides which org owns the site and whose
  *                                  storage its assets are charged to. It is then
- *                                  recorded as `site.yml::$org` and replayed, so it
+ *                                  recorded in `sync.json` and replayed, so it
  *                                  never has to be re-typed.
  *   uniweb publish --personal      Own the new site personally, deliberately. Sends
  *                                  NO `as_org` — byte-identical to the wire before
@@ -535,12 +535,18 @@ export async function publish(args = []) {
   // Non-local @std/registry Model schemas resolve through the backend (same as push).
   const resolveModel = makeModelResolver({ client, offline: false })
 
-  // ⛔ AN EMPTY `records.yml` REMOVES. It is the one path where an ordinary act is
-  // destructive — a placeholder file, created meaning to fill it in — so the count
-  // is reported and confirmed before anything is sent.
+  // ⛔ AN EMPTY RECORDS DIRECTORY REMOVES. It is the one path where an ordinary act
+  // is destructive — a directory emptied by accident, or kept with only a
+  // placeholder — so the count is reported and confirmed before anything is sent.
+  //
+  // ⛔ `backend` WAS MISSING HERE until 2026-09-21, and it is what the count is read
+  // under: placements are banked per backend, so with none the guard counted zero
+  // and never asked — `publish` sent an empty folder without a word while `push`
+  // stopped for the same one.
   {
     const guard = await guardEmptyRecords({
       siteDir,
+      backend: client.origin,
       args,
       warn: say.warn,
       note: say.dim

package/src/commands/pull.js

@@ -843,9 +843,9 @@ export async function pull(args = [], deps = {}) {
       }
       // ⛔ NO QUERY CONFIG. A record's home is decided by what it IS — its
       // `$model` names the pool folder — not by any query that happens to select
-      // it. `recordsToProject` reads `site.yml::$org` itself, so a `@/x`
-      // model the producer resolved to `@org/x` is placed back where the author
-      // wrote it.
+      // it. `recordsToProject` reads the site's org itself (this backend's, from
+      // `sync.json`), so a `@/x` model the producer resolved to `@org/x` is placed
+      // back where the author wrote it.
       const report = recordsToProject({
         folderDoc,
         recordDocs,
@@ -857,6 +857,8 @@ export async function pull(args = [], deps = {}) {
         }
       })
       if (report.records === 'updated') info('Wrote records.yml')
+      // The backend's folder has no sub-folders, and records.yml holds nothing else.
+      else if (report.records === 'removed') info('Removed records.yml — the folder has no sub-folders')
       records += report.placed.length + report.updated.length
       for (const s of report.skipped)
         note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)

package/src/commands/push.js

@@ -14,7 +14,7 @@
  * the backend owns the site's `@uniweb/folder`, so the framework never holds a
  * folder uuid. Records still round-trip their own `$uuid`
  * (back-filled into their source files). site-content items carry a per-item `$uuid`
- * too, stamped at emit from the identity cache rather than from author files — without
+ * too, stamped at emit from `sync.json` rather than from author files — without
  * it the backend reads every record as new and recreates every page and section row.
  * Push-only, and gated on the backend's per-entity `version`
  * (see "Pushes are GATED by default" below); `--force` restores last-push-wins.
@@ -30,8 +30,8 @@
  *   uniweb push --org @org               Own the new site under @org (alias: --as-org).
  *                                        Read only on the FIRST push of a site — it
  *                                        decides which org owns it, and whose storage
- *                                        its assets are charged to. Recorded as
- *                                        `site.yml::$org` and replayed after that.
+ *                                        its assets are charged to. Recorded in
+ *                                        `sync.json` and replayed after that.
  *                                        Without it, you are asked once.
  *   uniweb push --personal               Own the new site personally, deliberately.
  *                                        Sends NO `as_org` — the same wire as before
@@ -388,10 +388,10 @@ export async function push(args = [], deps = {}) {
   // It also has to be this emit that carries `assetRewrite` below: the push cache
   // stores hashes of the REWRITTEN content, so the emit compared against it must
   // rewrite too, or every entity reads as changed forever.
-  // ⛔ AN EMPTY `records.yml` REMOVES. It is the one path where an ordinary act is
-  // destructive — a placeholder file, created meaning to fill it in — so the count
-  // is reported and confirmed before anything is sent. The format stays honest;
-  // the asking happens here.
+  // ⛔ AN EMPTY RECORDS DIRECTORY REMOVES. It is the one path where an ordinary act
+  // is destructive — a directory emptied by accident, or kept with only a
+  // placeholder — so the count is reported and confirmed before anything is sent.
+  // The format stays honest; the asking happens here.
   if (!dryRun) {
     const guard = await guardEmptyRecords({ siteDir, backend: client.origin, args, warn, note })
     if (!guard.ok) return { exitCode: 1 }

package/src/commands/register.js

@@ -77,7 +77,7 @@ import {
   computeFoundationDigest,
   readRuntimePin
 } from '../utils/code-upload.js'
-import { deriveScope } from '../utils/registry-orgs.js'
+import { deriveScope, publishScope } from '../utils/registry-orgs.js'
 import { BackendClient } from '../backend/client.js'
 import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import {
@@ -404,14 +404,24 @@ async function runRegister(args = []) {
     : await resolveFoundationDir(args)
 
   // Scope: --scope flag, else package.json `uniweb.scope`, else (real submit
-  // only) derived from login membership in the bootstrap below.
+  // only) derived from login membership in the bootstrap below. Either spelling,
+  // `@acme` or `acme`, and from here on the one form: `@acme` (publishScope).
   const pkgScope = readPkgScope(targetDir)
-  let scope = scopeFlag || pkgScope
+  const givenScope = scopeFlag || pkgScope
+  let scope = publishScope(givenScope)
   let scopeSource = scopeFlag
     ? '--scope'
     : pkgScope
       ? 'package.json uniweb.scope'
       : null
+  // A scope that was GIVEN but names no org (`--scope @`) is refused, never read as
+  // absent: absent derives one from the login, which would register under an org the
+  // caller did not name.
+  if (givenScope && !scope) {
+    error(`Not an org scope: ${givenScope} (from ${scopeSource})`)
+    log(`  ${colors.dim}Pass --scope @org.${colors.reset}`)
+    return { exitCode: 2 }
+  }
   const isPreview = !!output || dryRun
 
   // Each path supplies a different schema source: the standalone path discovers
@@ -671,11 +681,17 @@ async function runRegister(args = []) {
       return { exitCode: 1 }
     }
   }
+  // The foundation's name as the registry holds it (`@org/name`) — read from the
+  // document just submitted, never composed again. See phase 2.
+  const registeredName = standalone
+    ? null
+    : doc.entities.find((e) => e.model === '@uniweb/foundation-schema')?.info
+        ?.name
   if (!alreadyRegistered) {
     success(
       standalone
         ? `Registered ${defined.length} data schema(s)${scope ? ` under ${scope}` : ''}`
-        : `Registered ${schema._self.name}@${schema._self.version}${defined.length ? ` + ${defined.length} data schema(s)` : ''}`
+        : `Registered ${registeredName}@${schema._self.version}${defined.length ? ` + ${defined.length} data schema(s)` : ''}`
     )
   }
 
@@ -684,11 +700,13 @@ async function runRegister(args = []) {
   // only packages have no dist; --schema-only skips deliberately.
   if (!standalone && !args.includes('--schema-only')) {
     const distDir = join(targetDir, 'dist')
-    // The registry's vocabulary is the SCOPED name (`@org/name`). A scoped
-    // package name passes through; a bare one gets the chosen scope — the
-    // same resolution the .uwx submission applied.
-    const bareName = schema._self.name
-    const name = bareName.startsWith('@') ? bareName : `${scope}/${bareName}`
+    // ⭐ The plan authorizes against the REGISTERED (name, version), so the name here
+    // is the one phase 1 registered — the `.uwx`'s own `info.name`, where a scoped
+    // package name passes through and a bare one gets the scope. ⛔ Not composed a
+    // second time: this line composed it from the raw scope until 2026-09-21, so
+    // `--scope std` registered `@std/src` and then asked to deliver `std/src`, which
+    // the registry refuses. One name, read from the one place it was decided.
+    const name = registeredName
     const version = schema._self.version
     info(
       `Delivering code for ${colors.bright}${name}@${version}${colors.reset} …`

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-21T13:20:05.572Z",
+  "generatedAt": "2026-09-21T21:47:05.925Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.4.1",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.56.0",
+      "version": "0.57.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -35,7 +35,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.29.6",
+      "version": "0.29.7",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -55,7 +55,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.19.3",
+      "version": "0.19.4",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -83,7 +83,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.27.2",
+      "version": "0.27.3",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.14.8",
+      "version": "0.15.0",
       "path": "framework/templates",
       "deps": []
     },
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.9.27",
+      "version": "0.10.0",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -1432,7 +1432,7 @@ ${colors.bright}Options:${colors.reset}
   --org @org         Publish under @org (membership-gated; alias: --as-org). Read
                      only on a site's FIRST publish — that create decides which org
                      owns the site, and whose storage its assets are charged to.
-                     Recorded as site.yml \$org and replayed, so it is never
+                     Recorded in sync.json and replayed, so it is never
                      re-typed. Without it, you are asked once.
   --personal         Create the site under your personal account, deliberately.
                      Only needed on a first publish, and only to answer the owner

package/src/utils/git.js

@@ -54,7 +54,7 @@ export function siteContentRoots(siteDir) {
   }
   roots.add(paths.pages || 'pages')
   roots.add(paths.layout || 'layout')
-  roots.add(paths.entities || 'entities')
+  roots.add(paths.records || 'records')
   return [...roots]
 }
 

package/src/utils/records-guard.js

@@ -1,42 +1,47 @@
 // ⛔ THE ONE PLACE AN ORDINARY ACT IS DESTRUCTIVE.
 //
-// `records.yml` is the sync control, and `missing` and `empty` deliberately mean
-// different things: missing leaves the server's folder untouched, empty says the
-// folder holds nothing and the backend removes what is there. The asymmetry is
-// well-shaped — the safe state is the ABSENCE of a file, so a live folder cannot
-// be wiped by deleting one, and the destructive act requires affirmatively
-// creating one.
+// A push sends the site's records folder whole, and it REPLACES the backend's. A site
+// with no records directory sends none and leaves the backend's alone; a records
+// directory that holds no records sends an EMPTY folder, and the backend removes what
+// is there. The asymmetry is well-shaped — the safe state is the ABSENCE of the
+// directory, so a site whose records live only on the backend is never emptied by a
+// push of its pages — and it leaves exactly one sharp edge: a directory emptied by
+// accident, or kept with only a placeholder (`records/.gitkeep`), and pushed.
 //
-// ⚠️ WHICH LEAVES EXACTLY ONE SHARP EDGE: a PLACEHOLDER. Someone creates an empty
-// `records.yml` intending to fill it in, pushes, and the live folder empties.
-// That is plausible and it is the only path where a normal act destroys content.
+// ⭐ THE CLI DOES THE ASKING. Never make "empty" mean "missing" to dodge this: that
+// would delete a capability to avoid writing a prompt.
 //
-// ⭐ THE FORMAT STAYS HONEST AND THE CLI DOES THE ASKING. Never make "empty" mean
-// "missing" to dodge this: that would delete a capability to avoid writing a
-// prompt.
+// ⛔ Until 2026-09-21 both states were `records.yml`'s — missing and empty — because
+// that file listed the records. The directory holds them now (`@uniweb/build`'s
+// `sendsFolder` decides what a push sends, and this asks about exactly its empty case).
 //
 // The count comes from the placement identity a previous push banked — what WE
 // last saw the folder hold. It needs no network call, and it is the right source:
 // a site that has never pushed has nothing to lose and is never asked.
 
-import { readRecordsConfig, FOLDER_EMPTY } from '@uniweb/build/uwx'
+import { readEntityPool } from '@uniweb/build/uwx'
 import { readFolderItemUuids } from '../backend/site-sync.js'
 import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
 
 /**
- * Leaf placements in a banked path→uuid map.
+ * Record placements in a banked placement map.
  *
- * A branch's path is a prefix of every path beneath it, so anything that is a
- * prefix of another key is a folder rather than a record. Counting raw keys would
- * report a two-record site inside one folder as three things to lose.
+ * ⭐ A placement banked since 2026-09-21 is keyed by the record it references —
+ * `@<record uuid>`, one per record — so where those exist they ARE the count. A map
+ * banked before holds `name` chains only: a branch's path is a prefix of every path
+ * beneath it, so anything that is a prefix of another key is a folder rather than a
+ * record. Counting raw keys would report a two-record site inside one folder as
+ * three things to lose — or, with both kinds of key, each record twice.
  */
 export function countPlacedRecords(pathToUuid) {
-  const paths = Object.keys(pathToUuid || {})
-  return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(`${p}/`))).length
+  const keys = Object.keys(pathToUuid || {})
+  const byRecord = keys.filter((k) => k.startsWith('@'))
+  if (byRecord.length) return byRecord.length
+  return keys.filter((p) => !keys.some((q) => q !== p && q.startsWith(`${p}/`))).length
 }
 
 /**
- * Stop an empty `records.yml` from silently emptying a live folder.
+ * Stop an empty records directory from silently emptying the backend's folder.
  *
  * @param {object} params
  * @param {string} params.siteDir
@@ -48,8 +53,10 @@ export function countPlacedRecords(pathToUuid) {
  * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
  */
 export async function guardEmptyRecords({ siteDir, backend, args = [], warn, note }) {
-  const cfg = await readRecordsConfig(siteDir)
-  if (cfg.state !== FOLDER_EMPTY) return { ok: true, count: 0 }
+  const pool = await readEntityPool(siteDir)
+  // Only a directory that is there and holds nothing at all — no records, and no
+  // files that fail to be records — sends the empty folder.
+  if (!pool.exists || pool.entities.length > 0 || pool.errors.length > 0) return { ok: true, count: 0 }
 
   const count = countPlacedRecords(readFolderItemUuids(siteDir, backend))
   // Nothing banked ⇒ nothing this push can remove. A first push of an empty
@@ -58,13 +65,13 @@ export async function guardEmptyRecords({ siteDir, backend, args = [], warn, not
   if (count === 0) return { ok: true, count: 0 }
 
   warn(
-    `records.yml is empty, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
-      `from the live folder.`
+    `${pool.dir}/ holds no records, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the site's folder on the backend.`
   )
   note(
-    'An empty records.yml means "the folder holds nothing" — it is not the same as ' +
-      'having no records.yml, which leaves the live folder alone. If you meant to ' +
-      'start listing records, delete the file until you have.'
+    `An empty ${pool.dir}/ means "the folder holds nothing" — it is not the same as having no ` +
+      `${pool.dir}/ at all, which leaves the backend's folder alone. If you did not mean to remove ` +
+      `them, put the files back (or pull) before pushing.`
   )
 
   // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
@@ -76,6 +83,6 @@ export async function guardEmptyRecords({ siteDir, backend, args = [], warn, not
     return { ok: false, count }
   }
 
-  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the live folder?`, false)
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the site's folder?`, false)
   return { ok: yes, count }
 }

package/src/utils/registry-orgs.js

@@ -59,6 +59,25 @@ export function bareHandle(scope) {
     .replace(/\/.*$/, '')
 }
 
+/**
+ * A publish scope in the one form the registry names things by — `@acme` — from any
+ * spelling `--scope` or `package.json::uniweb.scope` may carry it in (`@acme`, `acme`,
+ * `@acme/…`). Null when there is no handle in it.
+ *
+ * ⛔ Every name built from a scope goes through this. The `.uwx` assembly
+ * (`@uniweb/build`'s `buildRegistryPackage`) has always accepted `acme` as well as
+ * `@acme`, so a name composed from the RAW value disagreed with the one it registered:
+ * until 2026-09-21 `register --scope std` registered `@std/src` and then asked to
+ * deliver code for `std/src`, which the registry refuses (a scoped name is `@org/name`).
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function publishScope(value) {
+  const handle = bareHandle(value)
+  return handle ? `@${handle}` : null
+}
+
 /**
  * Validate a handle's GRAMMAR client-side (reserved names are the server's
  * call — a 409 carries the verdict). Returns an error string, or null.

package/templates/site/site.yml.hbs

@@ -25,7 +25,7 @@ index: home
 #   pages/docs: ../../../docs       # Mount docs repo at /docs route
 #   pages/blog: ../../blog-content  # Mount blog content at /blog route
 #   layout: ./custom-layout         # Custom layout directory
-#   entities: ./data                # Where this site's entities live
+#   records: ./data                 # Where this site's records live
 #
 # To give a mounted route a layout or a title, add a local folder for it
 # (pages/docs/) holding a folder.yml — folder.yml, not page.yml, because the
@@ -41,14 +41,16 @@ index: home
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose:
 #
-#   entities/{schema}/   your stored records. The folder names their data schema:
-#                          entities/article/       → @/article  (your foundation's)
-#                          entities/std/person/    → @std/person
-#   records.yml          WHAT IS PUBLISHED. Listing an entity here is what makes it
-#                        a record; anything you leave out is a draft. Usually three
-#                        lines:
-#                            - article/*.md
-#                            - person/*.md
+#   records/{schema}/    your site's records — every file here is one. The folder
+#                        names their data schema:
+#                          records/article/        → @/article  (your foundation's)
+#                          records/std/person/     → @std/person
+#                        A file whose name starts with `_` is not a record.
+#   records.yml          OPTIONAL — sorts records into folders a query can slice
+#                        with `scope:`. Most sites have none:
+#                            - folder: archive
+#                              records:
+#                                - article/2025-*.md
 #   queries.yml          HOW CONTENT IS REACHED — named queries over those records:
 #                            recent:
 #                              schema: '@/article'