uniweb 0.61.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.61.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/core": "^0.29.7",
-    "@uniweb/kit": "^0.19.4",
+    "@uniweb/core": "^0.29.8",
     "@uniweb/schemas": "^0.3.3",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/runtime": "^0.27.3",
+    "@uniweb/kit": "^0.19.4",
+    "@uniweb/runtime": "^0.27.4",
     "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.57.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,13 +845,13 @@ It is a small database, not a page tree. Three things, deliberately separate:
 ```
 site/
 ├── pages/
-├── records/           # your site's records — every file here is one
+├── 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        # optional: sorts records into folders
+│   ├── person/
+│   │   └── alice.yml
+│   └── folder.yml     # optional: sorts records into folders
 ├── queries.yml        # how content is REACHED
 └── site.yml
 ```
@@ -864,7 +864,7 @@ site/
 | `records/std/person/…` | `@std/person` — the shared standard set |
 | `records/acme/project/…` | `@acme/project` — an org's |
 
-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.
+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,9 +877,9 @@ Keep those folders flat: `records/article/design-tips.md` works; `records/articl
 
 **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`, `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.)
+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` — 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:
+**`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
 - folder: archive
@@ -888,7 +888,7 @@ Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `descript
     - article/2025-*.md
 ```
 
-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).
+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).
 
 ⚠️ **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.
 
@@ -942,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:**
 
@@ -1006,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
 
@@ -2594,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
 
@@ -2630,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.

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

@@ -36,7 +36,12 @@ 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'
@@ -48,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
@@ -64,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') }
 }
 
 /**
@@ -82,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.
  */
@@ -107,41 +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.
-//
-// ⛔ 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) {
+/**
+ * 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 = publishScope(pkg?.uniweb?.scope)
-    if (scope && name) return `${scope}/${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) {
@@ -225,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 }>}
  */
@@ -241,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') ||
@@ -266,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
   }
@@ -279,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
@@ -290,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,
@@ -326,7 +333,7 @@ async function bringLocalCodeAlong({
     return {
       released: releaseFoundation(local, args, cliBin, say, client?.origin),
       proceed: true,
-      ref: pinnedRef()
+      ref: await pinnedRef()
     }
   }
 
@@ -339,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.
@@ -369,7 +376,7 @@ async function bringLocalCodeAlong({
     return {
       released: releaseFoundation(local, args, cliBin, say, client?.origin),
       proceed: true,
-      ref: pinnedRef()
+      ref: await pinnedRef()
     }
   }
 
@@ -390,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?`,
@@ -400,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
@@ -438,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
@@ -476,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/site-sync.js

@@ -12,7 +12,7 @@
  */
 
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, relative, isAbsolute } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { humanBytes } from '../utils/bytes.js'
@@ -1270,6 +1270,8 @@ export async function pushSyncPackages({
 
   const wrote = []
   let finalizedTotal = 0
+  // Records sent as drafts that the backend stored enabled — reported at the end.
+  let draftsNotKept = []
 
   // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
   // returning the client's Response promise (so the "Pushing …" line prints before the
@@ -1658,6 +1660,7 @@ export async function pushSyncPackages({
     }
     for (const w of bf.warnings) note(`! ${w}`)
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    draftsNotKept = bf.notKeptAsDrafts || []
     if (bf.updated.length)
       wrote.push(`wrote ${bf.updated.length} record file(s)`)
     // ⭐ BANK THE FOLDER'S PLACEMENT IDENTITY. The records carry their own `$uuid`
@@ -1723,5 +1726,21 @@ export async function pushSyncPackages({
       )
     }
   }
+  // ⛔ A DRAFT THE BACKEND STORED ENABLED FAILS THE PUSH, and only here, after every
+  // piece of sync state above is banked: the push itself happened, and the next one must
+  // see it. What must not happen is a publish that goes live on top of it, which is why
+  // the exit code carries it (publish stops on anything but 0). The files keep their
+  // `draft: true` (see backfillEntityUuids).
+  if (draftsNotKept.length) {
+    const one = draftsNotKept.length === 1
+    const shown = draftsNotKept.map((p) => (isAbsolute(p) ? relative(siteDir, p) : p))
+    error(
+      `This backend did not keep ${one ? 'a record' : `${shown.length} records`} as a draft, ` +
+        `so ${one ? 'it' : 'they'} would be delivered once the site is published:\n  ` +
+        shown.join('\n  ') +
+        '\n  The backend does not support `draft: true` yet. Once it does, push again with --all.'
+    )
+    return { exitCode: 1, boundSiteUuid, finalizedTotal, wrote }
+  }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }

package/src/commands/add.js

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

package/src/commands/clone.js

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

package/src/commands/pull.js

@@ -65,7 +65,7 @@ import {
 import { tmpdir } from 'node:os'
 import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline/promises'
-import { join, dirname, relative } from 'node:path'
+import { join, dirname, relative, resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { downloadMissingAssets } from '../backend/asset-download.js'
 import {
@@ -856,9 +856,16 @@ export async function pull(args = [], deps = {}) {
           resolveDeclaration: (name) => declByModel.get(name) || null
         }
       })
-      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')
+      // The folder's organization, `folder.yml` in the records directory — named as
+      // the author would write it (`records/folder.yml`, or under `paths.records`).
+      if (report.records === 'updated') {
+        info(`Wrote ${report.recordsFile}`)
+        wrote.push(resolve(siteDir, report.recordsFile))
+      } else if (report.records === 'removed') {
+        // The backend's folder has no sub-folders, and the file holds nothing else.
+        info(`Removed ${report.recordsFile} — the folder has no sub-folders`)
+        removed.push(resolve(siteDir, report.recordsFile))
+      }
       records += report.placed.length + report.updated.length
       for (const s of report.skipped)
         note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
@@ -892,7 +899,8 @@ export async function pull(args = [], deps = {}) {
     siteDir,
     [
       ...wrote,
-      ...['site.yml', 'theme.yml', 'head.html', 'queries.yml', 'records.yml'].map((f) =>
+      // The records folder's `folder.yml` is in `wrote` when this pull wrote it.
+      ...['site.yml', 'theme.yml', 'head.html', 'queries.yml'].map((f) =>
         join(siteDir, f)
       )
     ],

package/src/commands/register.js

@@ -3,15 +3,14 @@
  * standalone schemas package (the data schemas alone, no foundation), to the
  * registry as one names-only `.uwx` document (uwx-format.md §5).
  *
- * `uniweb login && uniweb register`. Distinct from `uniweb publish` (which
- * targets the legacy platform) — `register` talks to the registry over HTTP at a
- * configurable endpoint.
+ * `uniweb login && uniweb register`. Distinct from `uniweb publish`, which ships a
+ * SITE — and releases the site's local foundation by running this command
+ * (`backend/foundation-bring-along.js`).
  *
- * If the foundation's `dist/` is missing or version-stale (the baked schema
- * version differs from package.json), `register` builds it first — the same
- * build-if-stale `uniweb publish` does, so `register` is a full drop-in.
- * Preview paths (`--dry-run`, `-o`) never write to `dist/`; they require a
- * pre-built foundation.
+ * If the foundation's `dist/` is missing or stale — no build, a version bump
+ * since it, a source file newer than it, no SSR bundle (`foundationNeedsBuild`)
+ * — `register` builds it first. Preview paths (`--dry-run`, `-o`) never write to
+ * `dist/`; they require a pre-built foundation.
  *
  * Run from a foundation, or from a schemas-only package — a package that exports
  * schemas (e.g. `@uniweb/schemas`, any `@org/schemas`) or a bare `schemas/*.yml`
@@ -64,13 +63,20 @@ import {
   statSync
 } from 'node:fs'
 import { execSync } from 'node:child_process'
-import { resolve, join } from 'node:path'
+import { resolve, join, relative } from 'node:path'
+import prompts from 'prompts'
 import { buildRegistryPackage, buildSchemaOnlyPackage } from '@uniweb/build/uwx'
 import {
   classifyPackage,
   isSchemasPackage,
-  collectStandaloneSchemas
+  collectStandaloneSchemas,
+  readFoundationName,
+  checkFoundationName
 } from '@uniweb/build'
+import {
+  suggestFoundationName,
+  writeFoundationName
+} from '../utils/foundation-name.js'
 import { readRegistryAuth } from '../utils/registry-auth.js'
 import {
   collectDistFiles,
@@ -209,6 +215,84 @@ async function resolveFoundationDir(args) {
   process.exit(1)
 }
 
+/**
+ * The foundation's name, settled before anything is built or sent.
+ *
+ * A foundation registers as `@org/<name>`, and sites pin it by that name. The name
+ * is `main.js`'s `name`, else package.json's — `readFoundationName`, the rule the
+ * build reads for the schema this command submits. ⛔ `src` and `foundation` are
+ * the folder the code sits in, not the code: a project scaffolded before the name
+ * moved to main.js has package name `src`, and every such project in an org would
+ * register the same `@org/src`. So a name that cannot register is ASKED FOR here,
+ * once, and kept in main.js — or, with nobody to ask, refused with the line to add.
+ * Before the build, so a written name is built into the schema like any edit.
+ *
+ * @param {string} targetDir
+ * @param {{ args: string[], isPreview: boolean }} o
+ * @returns {Promise<boolean>} false → stop; the reason is printed
+ */
+export async function settleFoundationName(targetDir, { args, isPreview }) {
+  let read
+  try {
+    read = await readFoundationName(targetDir)
+  } catch (err) {
+    error(err.message)
+    return false
+  }
+  const problem = checkFoundationName(read.name)
+  if (!problem) return true
+
+  const where = relative(process.cwd(), read.mainFile) || read.mainFile
+  const suggestion = suggestFoundationName(targetDir)
+  const reason = `${problem[0].toUpperCase()}${problem.slice(1)}.`
+
+  // Nobody to ask — a script, a preview (which writes nothing), or --json (whose
+  // stdout is a data channel a prompt would corrupt). Name the fix exactly.
+  if (isPreview || jsonMode || isNonInteractive(args)) {
+    error(`This foundation has no name it can register under. ${reason}`)
+    log(`  Name it in ${colors.bright}${where}${colors.reset}, in the default export:`)
+    log(`    ${colors.bright}name: '${suggestion || '<name>'}',${colors.reset}`)
+    log(`  ${colors.dim}It registers as @<org>/<name>, and sites pin that name.${colors.reset}`)
+    return false
+  }
+
+  info(`This foundation needs a name to register under. ${reason}`)
+  const { name } = await prompts(
+    {
+      type: 'text',
+      name: 'name',
+      message: 'Foundation name (it registers as @<org>/<name>):',
+      initial: suggestion || '',
+      validate: (v) => checkFoundationName(String(v).trim()) || true
+    },
+    {
+      onCancel: () => {
+        log('\nRegister cancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  const chosen = String(name || '').trim()
+  if (!chosen) return false
+
+  const written = writeFoundationName(read.mainFile, chosen, {
+    replace: read.source === 'main.js' ? read.name : null
+  })
+  if (!written.ok) {
+    error(`Could not write the name: ${written.reason}.`)
+    log(`  Add it to the default export in ${colors.bright}${where}${colors.reset}:  name: '${chosen}',`)
+    return false
+  }
+  // Read it back through the build's own rule — the text edit is only a means.
+  const again = await readFoundationName(targetDir).catch(() => null)
+  if (again?.name !== chosen) {
+    error(`${where} now names the foundation '${chosen}', but it still reads as "${again?.name}".`)
+    return false
+  }
+  success(`Named the foundation ${colors.bright}${chosen}${colors.reset} — kept in ${where}.`)
+  return true
+}
+
 // Directories that are never foundation source. `dist` is the output we compare
 // against; the rest are tooling. Dotted entries are skipped wholesale.
 const NON_SOURCE_DIRS = new Set(['dist', 'node_modules'])
@@ -443,8 +527,11 @@ async function runRegister(args = []) {
       return { exitCode: 2 }
     }
   } else {
-    // Build-if-stale (mirrors `uniweb publish`): a missing or version-stale
-    // dist/ gets (re)built before we read its schema. Preview paths
+    if (!(await settleFoundationName(targetDir, { args, isPreview }))) {
+      return { exitCode: 2 }
+    }
+    // Build-if-stale (`foundationNeedsBuild`): a missing or stale dist/ gets
+    // (re)built before we read its schema. Preview paths
     // (--dry-run / -o) must not write to dist/, so they require a pre-built
     // foundation and say so instead of building.
     const { needs, reason } = foundationNeedsBuild(targetDir)

package/src/commands/rename.js

@@ -20,7 +20,7 @@
  *
  * Extensions are technically a flavor of foundation (same build, same
  * package.json shape, distinguished only by `extension: true` in
- * src/foundation.js or `role: 'extension'` in the built schema). The
+ * main.js or `role: 'extension'` in the built schema). The
  * rename verb still keeps them on a separate subcommand because the
  * touch-point sets differ — `rename foundation` against an extension
  * would update the wrong things. Each subcommand guards its target
@@ -30,11 +30,13 @@
  * (target name already taken, target not found, folder collision,
  * type mismatch) we bail with a clear message and no partial state.
  *
- * Out of scope: registry side. The registered id (the scoped
- * `package.json::name` / `uniweb.id`) is independent of the workspace name and
- * stays untouched. There is no registry-rename flag — a registered version is
- * immutable; to change a foundation's registered identity, register it under
- * the new name (consuming sites repoint their `foundation:` ref).
+ * Out of scope: registry side. What a foundation registers as is `name` in its
+ * main.js, which is independent of the workspace name and stays untouched —
+ * except for a foundation with no main.js `name`, whose package name IS its name
+ * (`readFoundationName`), so renaming the package renames what it would register
+ * as. There is no registry-rename flag — a registered version is immutable; to
+ * change a foundation's registered name, change main.js's `name` and register
+ * again (consuming sites repoint their `foundation:` ref).
  *
  * Usage:
  *   uniweb rename foundation <old> <new>
@@ -632,9 +634,10 @@ ${colors.bright}What rename extension does:${colors.reset}
   • Updates pnpm-workspace.yaml + package.json::workspaces.
 
 ${colors.bright}What rename does NOT do (any subcommand):${colors.reset}
-  • Push to the registry. The registered id (package.json::uniweb.id) is
-    independent. To register under a new name, set it and run \`${prefix} register\`
-    (alias \`${prefix} release\`) — there is no rename flag.
+  • Push to the registry, or change what a foundation registers as — that is
+    \`name\` in its main.js, independent of the package name. To register under
+    a new name, change it there and run \`${prefix} register\` (alias
+    \`${prefix} release\`) — there is no rename flag.
 
 ${colors.bright}Examples:${colors.reset}
   ${prefix} rename foundation src marketing-src

package/src/commands/status.js

@@ -28,7 +28,10 @@ import { resolveSiteDir } from './deploy.js'
 import { probeUnpushed } from '../backend/site-sync.js'
 import { BackendClient, resolveBackendOrigin } from '../backend/client.js'
 import { readBackendState } from '@uniweb/build/uwx'
-import { resolveLocalFoundation } from '../backend/foundation-bring-along.js'
+import {
+  resolveLocalFoundation,
+  foundationScopedName
+} from '../backend/foundation-bring-along.js'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { checkFlags } from '../utils/flag-guard.js'
 
@@ -124,7 +127,8 @@ export async function status(args = []) {
       // site.yml ref. The digest compare is read-only — it never builds, so it
       // only fires when the local foundation is already built (dist present).
       const local = resolveLocalFoundation(siteDir, siteYml)
-      const lookupName = local?.scopedName || fndScope
+      const lookupName =
+        (local && (await foundationScopedName(local.dir))) || fndScope
       if (lookupName) fdnLatest = await client.readFoundationLatest(lookupName)
       if (local?.dir && fdnLatest?.digest) {
         const localDigest = computeFoundationDigest(join(local.dir, 'dist'))

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-21T21:47:05.925Z",
+  "generatedAt": "2026-09-21T23:16:47.962Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.4.1",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.57.0",
+      "version": "0.58.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -35,7 +35,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.29.7",
+      "version": "0.29.8",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -83,7 +83,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.27.3",
+      "version": "0.27.4",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.15.0",
+      "version": "0.16.0",
       "path": "framework/templates",
       "deps": []
     },
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.0",
+      "version": "0.10.1",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -53,6 +53,10 @@ import {
   mergeTemplateDependencies,
   getWorkspaceTemplateOutputs
 } from './utils/scaffold.js'
+import {
+  normalizeFoundationName,
+  ensureFoundationName
+} from './utils/foundation-name.js'
 import {
   detectPackageManager,
   detectWorkspacePm,
@@ -354,12 +358,16 @@ async function createFromPackageTemplates(
   // 2. Scaffold foundation (folder: src/, package name: src)
   // The folder name 'src' carries the meaning — a foundation is the site's
   // source code. The package name 'src' keeps it unique within the
-  // workspace, since 'site' is taken by the site package.
+  // workspace, since 'site' is taken by the site package. Neither is the
+  // foundation's NAME — what it registers as — which is main.js's `name`:
+  // the project's, since a project's code is its foundation.
   onProgress?.('Creating foundation...')
+  const registryName = normalizeFoundationName(projectName)
   await scaffoldFoundation(
     join(projectDir, 'src'),
     {
       name: 'src',
+      registryName,
       projectName,
       isExtension: false
     },
@@ -380,10 +388,12 @@ async function createFromPackageTemplates(
     { onProgress, onWarning }
   )
 
-  // 4. Apply starter content (unless creating a "none" project)
+  // 4. Apply starter content (unless creating a "none" project). Its main.js
+  // replaces the scaffolded one, so the name is given again.
   if (includeStarter) {
     onProgress?.('Adding starter content...')
     await applyStarter(projectDir, { projectName }, { onProgress, onWarning })
+    ensureFoundationName(join(projectDir, 'src'), registryName)
   }
 
   success(`Created project: ${projectName}`)
@@ -475,15 +485,31 @@ async function createFromContentTemplate(
   )
 
   // 2. Scaffold and apply content for each package
+  const claimed = new Set() // names this project's foundations register as
   for (const pkg of placed) {
     const fullPath = join(projectDir, pkg.relativePath)
 
+    // A foundation's name — what it registers as — is the template's name for
+    // the package when that is one, else the project's (`src` and `foundation`
+    // name a folder); `<project>-<package>` if another package here took it. A
+    // template's own main.js `name` outranks all of them.
+    let registryName = null
+    if (pkg.type === 'foundation' || pkg.type === 'extension') {
+      registryName =
+        [
+          normalizeFoundationName(pkg.name) || normalizeFoundationName(projectName),
+          normalizeFoundationName(`${projectName}-${pkg.name}`)
+        ].find((n) => n && !claimed.has(n)) || null
+      if (registryName) claimed.add(registryName)
+    }
+
     if (pkg.type === 'foundation' || pkg.type === 'extension') {
       onProgress?.(`Creating ${pkg.type}: ${pkg.name}...`)
       await scaffoldFoundation(
         fullPath,
         {
           name: pkg.name,
+          registryName,
           projectName,
           isExtension: pkg.type === 'extension'
         },
@@ -534,6 +560,7 @@ async function createFromContentTemplate(
           renames: contentDir.renames
         }
       )
+      ensureFoundationName(fullPath, registryName)
     }
 
     // Merge template dependencies into package.json

package/src/utils/foundation-name.js

@@ -0,0 +1,179 @@
+/**
+ * Giving a foundation its name — `name` in `main.js`'s default export.
+ *
+ * The rule itself (main.js `name`, else package.json `name`; `src` and `foundation`
+ * refused) is `@uniweb/build`'s `foundation-name.js`, shared by the build, `register`
+ * and `push`. This module only WRITES the name: the scaffold at `create` / `add`, and
+ * `register` when it asks for one.
+ *
+ * ⛔ NO `@uniweb/build` IMPORT, AND NO IMPORT OF main.js. `uniweb create` runs before
+ * any project exists: `@uniweb/build` is an optional peer that may not be installed,
+ * and main.js's own imports may not be either. Hence text scans rather than a load,
+ * and the one duplicated fact below, pinned to the build's list by
+ * `test/foundation-name.test.js`. What a foundation IS named is always read by the
+ * build (`readFoundationName`); these only decide where to write.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+
+// The folders a foundation's code lives in — never a foundation's name
+// (`@uniweb/build`'s FORBIDDEN_FOUNDATION_NAMES; the test keeps them equal).
+export const SCAFFOLD_FOLDER_NAMES = new Set(['src', 'foundation'])
+
+// Written above the name wherever the CLI adds one — the scaffold's main.js
+// template says the same.
+const NAME_COMMENT = '// What this foundation registers as — @<org>/<name> — and what sites pin.'
+
+/**
+ * A name made from free text — a project's name, a folder's — in the form a
+ * foundation name takes: lowercase letters, digits and inner hyphens.
+ * `My Site` → `my-site`. Null when nothing usable is left, or when what is left
+ * names a folder rather than a foundation.
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function normalizeFoundationName(raw) {
+  const name = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@[^/]*\//, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return name && !SCAFFOLD_FOLDER_NAMES.has(name) ? name : null
+}
+
+/**
+ * A name to offer a foundation that has none of its own: its folder's — or, for
+ * the `src/` and `foundation/` a scaffold makes, its project's folder. Null when
+ * neither makes one.
+ *
+ * @param {string} foundationDir
+ * @returns {string|null}
+ */
+export function suggestFoundationName(foundationDir) {
+  const dir = resolve(foundationDir)
+  return (
+    normalizeFoundationName(basename(dir)) ||
+    normalizeFoundationName(basename(dirname(dir)))
+  )
+}
+
+/**
+ * Whether `main.js`'s default export names the foundation — a `name` key at the
+ * export's own level, not one nested in `props` or `vars`.
+ *
+ * A scan, not a parse (see the module note): it skips strings and comments and
+ * counts brackets, which is all an object literal of declarations needs. A name
+ * that arrives by a spread is invisible to it — the build's read is the truth.
+ *
+ * @param {string} text - main.js source
+ * @returns {boolean}
+ */
+export function mainNamesFoundation(text) {
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) return false
+  let depth = 1
+  let atKey = true // just after the opening brace, or a comma at the top level
+  for (let i = opening.index + opening[0].length; i < text.length && depth > 0; i++) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      i = text.indexOf('\n', i)
+      if (i < 0) break
+    } else if (c === '/' && text[i + 1] === '*') {
+      i = text.indexOf('*/', i + 2) + 1
+      if (i <= 0) break
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1
+      while (j < text.length && text[j] !== c) j += text[j] === '\\' ? 2 : 1
+      if (depth === 1 && atKey && text.slice(i + 1, j) === 'name' && /^\s*:/.test(text.slice(j + 1))) {
+        return true
+      }
+      i = j
+      atKey = false
+    } else if ('{[('.includes(c)) {
+      depth++
+      atKey = false
+    } else if ('}])'.includes(c)) {
+      depth--
+    } else if (depth === 1 && c === ',') {
+      atKey = true
+    } else if (depth === 1 && atKey && /[A-Za-z_$]/.test(c)) {
+      const word = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))[0]
+      // `name: 'x'`, or the shorthand `{ name }`
+      if (word === 'name' && /^\s*[:,}]/.test(text.slice(i + word.length))) return true
+      i += word.length - 1
+      atKey = false
+    } else if (!/\s/.test(c)) {
+      atKey = false
+    }
+  }
+  return false
+}
+
+/**
+ * Write `name` into a foundation's `main.js`.
+ *
+ * With `replace`, the one `name: '<replace>'` literal is rewritten — the case where
+ * main.js already names the foundation, with a name that cannot register. Without
+ * it, `name` becomes the default export's first key. A missing main.js is created.
+ *
+ * ⚠️ A text edit, not a parse: it handles `export default { … }` — every scaffold
+ * and every template — and says so otherwise rather than guessing.
+ *
+ * @param {string} mainFile
+ * @param {string} name - already a valid foundation name
+ * @param {{ replace?: string|null }} [opts]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function writeFoundationName(mainFile, name, { replace = null } = {}) {
+  const line = `${NAME_COMMENT}\n  name: '${name}',`
+  if (!existsSync(mainFile)) {
+    writeFileSync(mainFile, `export default {\n  ${line}\n}\n`)
+    return { ok: true }
+  }
+  const text = readFileSync(mainFile, 'utf8')
+
+  if (replace !== null) {
+    const literal = new RegExp(
+      `(\\bname\\s*:\\s*)(['"\`])${replace.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\2`,
+      'g'
+    )
+    const hits = text.match(literal) || []
+    if (hits.length !== 1) {
+      return {
+        ok: false,
+        reason: `main.js does not name the foundation "${replace}" in exactly one place`
+      }
+    }
+    writeFileSync(mainFile, text.replace(literal, `$1'${name}'`))
+    return { ok: true }
+  }
+
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) {
+    return { ok: false, reason: 'main.js has no `export default { … }` to add a name to' }
+  }
+  // The name leads the export — on lines of its own, so a multi-line export keeps
+  // its first line and gains a blank one between.
+  const at = opening.index + opening[0].length
+  writeFileSync(mainFile, `${text.slice(0, at)}\n  ${line}\n${text.slice(at)}`)
+  return { ok: true }
+}
+
+/**
+ * Give a freshly scaffolded foundation its name, unless its main.js already has one.
+ *
+ * Called after template content is applied, because a template's own main.js
+ * replaces the scaffolded one — and with it the name the scaffold wrote.
+ *
+ * @param {string} foundationDir - the scaffolded package (flat layout: main.js at its root)
+ * @param {string|null} name
+ */
+export function ensureFoundationName(foundationDir, name) {
+  if (!name) return
+  const mainFile = join(foundationDir, 'main.js')
+  if (existsSync(mainFile) && mainNamesFoundation(readFileSync(mainFile, 'utf8'))) return
+  writeFoundationName(mainFile, name)
+}

package/src/utils/git.js

@@ -37,12 +37,15 @@ export function siteContentRoots(siteDir) {
   // root added below already covered it and the bare `'collections.yml'` entry
   // that used to sit in this list resolved to a path no site ever had. A
   // root-level file has no directory entry standing in for it.
+  //
+  // The records folder's `folder.yml` is the reverse case: it lives in the records
+  // directory, which is a root below, so it needs no entry. (It was `records.yml` at
+  // the site root until 2026-09-21, and was listed here then.)
   const roots = new Set([
     'site.yml',
     'theme.yml',
     'head.html',
     'queries.yml',
-    'records.yml',
     'locales'
   ])
   let paths = {}

package/src/utils/scaffold.js

@@ -76,14 +76,16 @@ export async function getWorkspaceTemplateOutputs({ blank = false } = {}) {
 }
 
 /**
- * Scaffold a foundation from the foundation package template
+ * Scaffold a foundation from the foundation package template.
  *
- * @param {string} targetDir - Target directory for the foundation
+ * @param {string} targetDir
  * @param {Object} context - Template context
- * @param {string} context.name - Package name
+ * @param {string} context.name - Package name — workspace plumbing (`src`, `docs-src`)
+ * @param {string} [context.registryName] - The foundation's own name, written to
+ *   main.js's `name`: what it registers as (`@org/<name>`). Omitted when none can be
+ *   made, and `uniweb register` asks for one
  * @param {string} context.projectName - Workspace name
- * @param {boolean} [context.isExtension] - Whether this is an extension
- * @param {Object} [options] - Processing options
+ * @param {boolean} [context.isExtension]
  */
 export async function scaffoldFoundation(targetDir, context, options = {}) {
   registerVersions(getVersionsForTemplates())

package/starter/foundation/main.js

@@ -6,7 +6,8 @@
  * - defaultLayout: Name of the default layout from src/layouts/ (optional)
  * - props: Foundation-wide props accessible via website.foundationProps
  *
- * Identity (name, version, description) comes from package.json.
+ * Name: `name` in the default export is what this foundation registers as
+ * (@org/<name>) — `uniweb create` adds it. The version comes from package.json.
  */
 
 // Create a layout at src/layouts/MyLayout/index.jsx

package/templates/foundation/main.js.hbs

@@ -14,10 +14,19 @@
 
 {{#if isExtension}}
 export default {
+{{#if registryName}}
+  name: '{{registryName}}',
+{{/if}}
   extension: true,
 }
 {{else}}
 export default {
+{{#if registryName}}
+  // ─── Name ───────────────────────────────────────────────────────────────────
+  // What this foundation registers as — @<org>/<name> — and what sites pin.
+  name: '{{registryName}}',
+
+{{/if}}
   // ─── Layout ─────────────────────────────────────────────────────────────────
   // Create layouts in layouts/MyLayout/index.jsx (auto-discovered).
   // defaultLayout: 'MyLayout',

package/templates/site/site.yml.hbs

@@ -46,8 +46,9 @@ index: home
 #                          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:
+#   records/folder.yml   OPTIONAL — sorts records into folders a query can slice
+#                        with `scope:`. The one file in records/ that is not a
+#                        record. Most sites have none:
 #                            - folder: archive
 #                              records:
 #                                - article/2025-*.md