uniweb 0.60.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "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.8",
     "@uniweb/schemas": "^0.3.3",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/kit": "^0.19.4",
+    "@uniweb/runtime": "^0.27.4",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.56.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/build": "^0.58.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -129,7 +129,7 @@ my-project/
 └── pnpm-workspace.yaml
 ```
 
-A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site`.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. **`src` and `foundation` are never a foundation's name** — `uniweb register` refuses them, because every project in an org would register the same one.
 
 - **Foundation** (`src/`): React components. Those in `sections/` and `layouts/` are *section types* — selectable by authors via `type:`, or used for layout areas. Everything in `components/` and `utils/` is ordinary React and JS: the developer's workbench, not visible to authors.
 - **Site** (`site/`): markdown content and configuration, plus optional records of structured content and the queries that reach them or an external data source.
@@ -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 in a schema folder is one
+│   ├── article/       # the folder names their data schema
 │   │   ├── getting-started.md
 │   │   └── design-tips.md
-│   └── person/
-│       └── alice.yml
-├── records.yml        # what is PUBLISHED
+│   ├── person/
+│   │   └── alice.yml
+│   └── folder.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/folder.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 a backend you `uniweb push` it to keeps it in the site's folder without delivering 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/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.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 `folder.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
 
-**`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:
+⚠️ **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 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.
 
@@ -952,7 +942,7 @@ pages/blog/
 
 > **The record arrives as a single-element array under the key the component declares** — `content.data.recent[0]` for a component declaring `recent`, `content.data.article[0]` for one declaring `article: '@std/article'` over an `@std/article` query. The runtime never coerces it to an object. See *Data* in Part 4.
 
-**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by its handle, so the section reads `content.data.recent[0]` as before. The same three variables exist under every parametric page: under `[slug]`, `:slug` and `:path` are the segment and `:dir` is empty. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound or empty variable drops its clause, so one saved query serves the query's page and its parametric page, on a static site and a hosted one alike. Without `scope: :dir` the directory is decoration: the record is found by its handle wherever it sits. Reference: `reference/dynamic-routes.md`.
+**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by its handle, so the section reads `content.data.recent[0]` as before. The same three variables exist under every parametric page: under `[slug]`, `:slug` and `:path` are the segment and `:dir` is empty. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records/folder.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound or empty variable drops its clause, so one saved query serves the query's page and its parametric page, on a static site and a hosted one alike. Without `scope: :dir` the directory is decoration: the record is found by its handle wherever it sits. Reference: `reference/dynamic-routes.md`.
 
 **Two options for bigger sets:**
 
@@ -1016,7 +1006,7 @@ import LessonHeader from '../../components/LessonHeader' // ❌ breaks if you re
 
 Within the same directory, use normal relative imports (`./AIFeedbackCard`).
 
-**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. Everything here is read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in `dist/entry.js`; you never write that wrapper. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the foundation's identity — `name` (what it registers as, `@org/<name>`) and `description` — and the capabilities it provides — `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. The capabilities are read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in `dist/entry.js`; you never write that wrapper. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
 
 ### Props interface
 
@@ -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
 ```
@@ -2604,7 +2594,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 Either side can publish. Nothing about this changes how you build: the same foundation and the same site run under `uniweb dev`, `uniweb export`, or a CI deploy with no account at all.
 
-**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
+**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version` — `name` from the foundation's `main.js`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
 
 ### Staying current
 
@@ -2640,10 +2630,11 @@ Platform-specific configuration that doesn't belong in npm-standard fields. All
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `id` | `uniweb register` | bare segment of a scoped `name` | The foundation's registered id — the bare name in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming on the registry doesn't ripple through site dependencies. |
-| `namespace` | `uniweb register` | none | Legacy explicit org-namespace override; equivalent to a scoped `package.json::name`. Rarely needed. |
+| `scope` | `uniweb register` | derived from your login, then saved here | The org the foundation registers under (`@acme`, or `acme`): a bare `main.js` name `marketing` registers as `@acme/marketing`. `--scope @org` overrides it for one run. |
 | `runtimePolicy` | `dist/runtime-pin.json` | unset | Declares how far past the recorded runtime version a host may move a site. |
 
+**The foundation's name is not here — it is `name` in `main.js`** (else `package.json`'s `name`). ⛔ `uniweb.id` is no longer read: `uniweb register` refuses it and prints the `main.js` line to write instead.
+
 **Runtime updates — handled for you.** Your foundation's code links against the runtime: it externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, and the runtime supplies all of them at load time. So a build is bound to *that* React and *that* core API.
 
 You don't declare anything for this. At build time your foundation records the `@uniweb/runtime` version it actually linked against (read from `node_modules`, not chosen) into `dist/runtime-pin.json`, and `uniweb register` sends it with your foundation, so the version you built against travels with it. **Whether two runtime versions are compatible is our determination, not a setting** — you have no way to know whether we changed anything your code can reach, so we don't ask you to guess.
@@ -2697,7 +2688,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

@@ -36,9 +36,15 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { execFileSync } from 'node:child_process'
 
-import { detectFoundationType, isExtensionUrl } from '@uniweb/build'
+import {
+  detectFoundationType,
+  isExtensionUrl,
+  readFoundationName,
+  checkFoundationName
+} 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'
 
 /**
@@ -47,9 +53,12 @@ import { compareSemverPrecedence } from '../utils/semver-precedence.js'
  * already has it; nothing to do). Uses the SAME resolver the build uses
  * (`detectFoundationType`), so "which foundation" never drifts between them.
  *
+ * Its catalog name is `foundationScopedName(dir)` — a separate, async read, because
+ * the name lives in `main.js`, which is loaded rather than parsed.
+ *
  * @param {string} siteDir
  * @param {object} siteYml - parsed site.yml
- * @returns {{ dir: string, scopedName: string|null, version: string|null }|null}
+ * @returns {{ dir: string, version: string|null }|null}
  */
 export function resolveLocalFoundation(siteDir, siteYml) {
   const decl = siteYml?.foundation
@@ -63,11 +72,7 @@ export function resolveLocalFoundation(siteDir, siteYml) {
     return null
   }
   if (!info || info.type !== 'local' || !info.path) return null
-  return {
-    dir: info.path,
-    scopedName: foundationScopedName(info.path),
-    version: readPkgField(info.path, 'version')
-  }
+  return { dir: info.path, version: readPkgField(info.path, 'version') }
 }
 
 /**
@@ -81,7 +86,7 @@ export function resolveLocalFoundation(siteDir, siteYml) {
  *
  * @param {string} siteDir
  * @param {object} siteYml - parsed site.yml
- * @returns {Array<{ decl: string, dir: string, scopedName: string|null, version: string|null }>}
+ * @returns {Array<{ decl: string, dir: string, version: string|null }>}
  *   `decl` is the authored declaration, which is the wire entry's `$id` — the key
  *   publish stamps the pinned ref back onto.
  */
@@ -106,37 +111,43 @@ export function resolveLocalExtensions(siteDir, siteYml) {
       continue
     }
     if (!info || info.type !== 'local' || !info.path) continue
-    out.push({
-      decl,
-      dir: info.path,
-      scopedName: foundationScopedName(info.path),
-      version: readPkgField(info.path, 'version')
-    })
+    out.push({ decl, dir: info.path, version: readPkgField(info.path, 'version') })
   }
   return out
 }
 
-// The foundation's scoped catalog name (`@org/name`) from its package.json — an
-// already-scoped name, else `uniweb.scope` + a bare one. Null when neither
-// yields a scoped name (then we can't look up the registered version, so the
-// caller treats the foundation as "release it and let register pick the scope").
-//
-// ⛔ The name is `uniweb.id` when set, exactly as the build reads it for the
-// schema that `register` submits (`build/src/schema.js`). Reading `name` alone —
-// 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.
-function foundationScopedName(dir) {
+/**
+ * The foundation's scoped catalog name (`@org/name`): its name — `main.js`'s
+ * `name`, else package.json's, the one rule the build reads for the schema
+ * `register` submits (`readFoundationName`) — scoped by `uniweb.scope` unless
+ * already scoped. Null when no registrable scoped name can be formed; the caller
+ * then treats the foundation as unreleased, and `register` — which it runs to
+ * release — is where a missing scope is derived and a missing name is asked for.
+ *
+ * ⛔ A NAME THAT CANNOT REGISTER IS NULL, not looked up. `src` and `foundation`
+ * name a folder (`checkFoundationName`); looking one up would find some other
+ * project's `@org/src` — the very collision refusing them prevents.
+ *
+ * ⛔ 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.
+ * *(This read package.json alone until 2026-09-21 — `uniweb.id`, else `name` — and
+ * so named a foundation differently from the build whenever `main.js` named it.)*
+ *
+ * @param {string} dir - the foundation package
+ * @returns {Promise<string|null>}
+ */
+export async function foundationScopedName(dir) {
+  let name
   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}`
-    return null
+    ;({ name } = await readFoundationName(dir))
   } catch {
     return null
   }
+  if (checkFoundationName(name)) return null
+  if (name.startsWith('@')) return name
+  const scope = publishScope(readPkgField(dir, 'uniweb')?.scope)
+  return scope ? `${scope}/${name}` : null
 }
 
 function readPkgField(dir, field) {
@@ -220,7 +231,7 @@ export async function bringFoundationAlong({
  * it in the messages.
  *
  * @param {object} o
- * @param {{dir: string, scopedName: string|null, version: string|null}} o.local
+ * @param {{dir: string, version: string|null}} o.local
  * @param {'foundation'|'extension'} o.kind
  * @returns {Promise<{ released: boolean, proceed: boolean, ref: string|null }>}
  */
@@ -236,9 +247,10 @@ async function bringLocalCodeAlong({
   verb = 'publish'
 }) {
   const Kind = kind === 'extension' ? 'Extension ' : 'Foundation'
+  const scopedName = await foundationScopedName(local.dir)
   const label =
-    local.scopedName || local.version
-      ? `${local.scopedName || kind}${local.version ? `@${local.version}` : ''}`
+    scopedName || local.version
+      ? `${scopedName || kind}${local.version ? `@${local.version}` : ''}`
       : `the local ${kind}`
   const skipPrompts =
     args.includes('--yes') ||
@@ -261,10 +273,11 @@ async function bringLocalCodeAlong({
   const noRelease = args.includes('--no-release')
 
   // The pinned ref to stamp on the pushed site — read at RETURN time (after any
-  // release), so it reflects the released version + the scope register derived.
-  // null when no scoped ref can be formed (then the site.yml ref is forwarded).
-  const pinnedRef = () => {
-    const s = foundationScopedName(local.dir)
+  // release), so it reflects the released version, the scope register derived and
+  // the name it asked for. null when no scoped ref can be formed (then the site.yml
+  // ref is forwarded).
+  const pinnedRef = async () => {
+    const s = await foundationScopedName(local.dir)
     const v = readPkgField(local.dir, 'version')
     return s && v ? `${s}@${v}` : null
   }
@@ -274,8 +287,8 @@ async function bringLocalCodeAlong({
   // so on a bumped-but-unreleased foundation it names a version nobody can serve. Any
   // branch that skips a release must bind to this instead.
   const registeredRef = (reg) =>
-    local.scopedName && reg?.latest_version
-      ? `${local.scopedName}@${reg.latest_version}`
+    scopedName && reg?.latest_version
+      ? `${scopedName}@${reg.latest_version}`
       : null
 
   // Dry-run reports the intent WITHOUT touching the network — it must not force
@@ -285,24 +298,23 @@ async function bringLocalCodeAlong({
       `${Kind}  : ${label} — local; would release if changed or not yet registered`
     )
     // The ref still comes back where one can be formed: it is read from the
-    // foundation's own package.json, so it costs no network, and an offline preview
-    // that omitted it would emit a document the real run would not — the one thing
-    // `-o` exists to avoid.
+    // foundation's own files, so it costs no network, and an offline preview that
+    // omitted it would emit a document the real run would not — the one thing `-o`
+    // exists to avoid.
     //
     // ⚠️ It is null for a foundation that has NEVER been registered and carries no
-    // scope (a freshly scaffolded `name: "src"`), because the scope is what
-    // `register` writes back (`writePkgScope`). So the preview shows the authored
-    // value there, and the first real push — which releases, and so acquires the
-    // scope — sends the pinned ref instead. That gap is unavoidable offline: before
-    // the first release there is no registered name to name.
-    return { released: false, proceed: true, ref: pinnedRef() }
+    // scope (a fresh scaffold), because the scope is what `register` writes back
+    // (`writePkgScope`) — and for one with no name of its own (`src`), which
+    // `register` asks for. So the preview shows the authored value there, and the
+    // first real push — which releases, and so acquires both — sends the pinned ref
+    // instead. That gap is unavoidable offline: before the first release there is
+    // no registered name to name.
+    return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
   // Ask the catalog what it has. Null → not registered (or the backend can't
   // answer / no scoped name to look up) → release.
-  const reg = local.scopedName
-    ? await client.readFoundationLatest(local.scopedName)
-    : null
+  const reg = scopedName ? await client.readFoundationLatest(scopedName) : null
 
   if (!reg) {
     // ⛔ Nothing to bind to. Releasing anyway would be the opposite of what was asked,
@@ -321,7 +333,7 @@ async function bringLocalCodeAlong({
     return {
       released: releaseFoundation(local, args, cliBin, say, client?.origin),
       proceed: true,
-      ref: pinnedRef()
+      ref: await pinnedRef()
     }
   }
 
@@ -334,7 +346,7 @@ async function bringLocalCodeAlong({
     say.dim(
       `${Kind}  : ${label} — unchanged since release (digest matches); nothing to release.`
     )
-    return { released: false, proceed: true, ref: pinnedRef() }
+    return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
   // A different version locally → a new version to release.
@@ -364,7 +376,7 @@ async function bringLocalCodeAlong({
     return {
       released: releaseFoundation(local, args, cliBin, say, client?.origin),
       proceed: true,
-      ref: pinnedRef()
+      ref: await pinnedRef()
     }
   }
 
@@ -385,7 +397,7 @@ async function bringLocalCodeAlong({
       say.dim(
         'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to release a change.'
       )
-      return { released: false, proceed: true, ref: pinnedRef() }
+      return { released: false, proceed: true, ref: await pinnedRef() }
     }
     const reRelease = await confirm(
       `Re-release ${label} to be sure its code is current?`,
@@ -395,9 +407,9 @@ async function bringLocalCodeAlong({
       return {
         released: releaseFoundation(local, args, cliBin, say, client?.origin),
         proceed: true,
-        ref: pinnedRef()
+        ref: await pinnedRef()
       }
-    return { released: false, proceed: true, ref: pinnedRef() }
+    return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
   // Case 3 (§4): the code was edited but the version wasn't bumped. The
@@ -433,7 +445,7 @@ async function bringLocalCodeAlong({
       `Local ${label} differs from the registered ${reg.latest_version} and the version wasn't bumped — ` +
         `shipping against the registered code. Your local changes will NOT be live.`
     )
-    return { released: false, proceed: true, ref: pinnedRef() }
+    return { released: false, proceed: true, ref: await pinnedRef() }
   }
 
   // 2. Nobody to ask. Refuse, and name both real options as runnable commands so
@@ -471,7 +483,7 @@ async function bringLocalCodeAlong({
     )
     return { released: false, proceed: false, ref: null }
   }
-  return { released: false, proceed: true, ref: pinnedRef() }
+  return { released: false, proceed: true, ref: await pinnedRef() }
 }
 
 // Build the foundation so its dist/ can be fingerprinted. Idempotent — the

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,