uniweb 0.85.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.85.0",
+  "version": "0.87.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/runtime": "^0.29.2",
-    "@uniweb/kit": "^0.19.18",
-    "@uniweb/schemas": "^0.12.0",
-    "@uniweb/core": "^0.37.2",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/kit": "^0.20.0",
+    "@uniweb/runtime": "^0.29.4",
+    "@uniweb/core": "^0.38.0",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/schemas": "^0.13.0",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "^1.2.8",
-    "@uniweb/build": "^0.78.0",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/build": "^0.80.0",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/content-reader": "^1.2.8"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -899,7 +899,7 @@ brief:
 The body — the value of the schema's content field, `body.content`.
 ```
 
-**A component receives it in one of two shapes, and its `meta.js` says which**, per `data:` key — the same on a static site and a hosted one. `data: { articles: '@std/article' }` gets **briefs**: the brief's fields at the top (`article.title`), no other section. `data: { articles: '@std/article/*' }` gets each record **whole**, as stored: every section under its own name, the brief's included (`article.brief.title`, `article.body.content`). Both carry `$name`, the handle. Lists carry briefs; a section that shows a record in full declares `/*`. A `fields:` schema's brief is the whole record, so its components need no `/*`. Full rules: `reference/entity-content.md`.
+**A component receives it in one of two shapes, and its `meta.js` says which**, per `data:` key — the same on a static site and a hosted one. `data: { articles: '@std/article' }` gets **briefs**: the brief's fields at the top (`article.title`), no other section. `data: { articles: { schema: '@std/article', whole: true } }` gets each record **whole**, as stored: every section under its own name, the brief's included (`article.brief.title`, `article.body.content`). Both carry `$name`, the handle. Lists carry briefs; a section that shows a record in full declares `whole: true`. A `fields:` schema's brief is the whole record, so its components need no `whole: true`. Full rules: `reference/entity-content.md`.
 
 **A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (in the same push when that record is new too), and a pull writes the name back.
 
@@ -962,15 +962,15 @@ pages/blog/
 
 **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.
 
-**Which query the URL narrows — the page's route query:** the `[slug]` page's own `query:`, else its parent page's (the usual shape, above), else `site.yml`'s (for a top-level `pages/[slug]/` only — the site's reaches no deeper page); if none declares one, the query its sections all declare. The first query of that level wins. Every section the route query reaches gets the one record; a section declaring a *different* query of its own gets that query as declared. The folder name says what the URL segment matches: `[slug]` the record's name (`$name`, a compiled record's file name) — or the field its route query binds `:slug` to (`where: { slug: :slug }`, how an external API's records, which have no `$name`, get pages), `[uuid]` its `$uuid`, any other `[name]` the record's own field of that name — and when that field holds several values, **any member** matches (the record's own link is its first value). Routing by a field that is not unique picks one record and which one is not guaranteed; the build warns. A folder inside `[slug]/` (`[slug]/cv/` → `/blog/:slug/cv`) is a parametric page too, about the same record: its route query is the `[slug]` page's, wherever that is declared, and a query `cv/` declares itself arrives under its own key. **A section chooses how it uses the page's record with `current:`** on its own `fetch:` — `only` (the default: the record, as a list of one), `exclude` (the others: "related"), `include` (all of them: a pager) — e.g. `fetch: { query: articles, as: related, current: exclude, limit: 3 }`, where `limit` counts the others, all from the query's set. **`current:` follows the query, not the key:** a fetch of the route query gets the record unless it says otherwise, whatever its `as`; a fetch of another query gets that query's records and reads `current:` only when written (`exclude` drops the page's record, `only` keeps just it). `refine: true` / `detail: false` are retired and stop the build. `[dir]` and `[path]` are refused as folder names, and so is any folder inside `[...path]/`.
+**Which query the URL narrows — the page's route query:** the `[slug]` page's own `query:`, else its parent page's (the usual shape, above), else `site.yml`'s (for a top-level `pages/[slug]/` only — the site's reaches no deeper page); if none declares one, the query its sections all declare. The first query of that level wins. Every section the route query reaches gets the one record; a section declaring a *different* query of its own gets that query as declared. The folder name says what the URL segment matches: `[slug]` the record's name (`$name`, a compiled record's file name) — or the field its route query binds `:slug` to (`where: { slug: :slug }`, how an external API's records, which have no `$name`, get pages), `[uuid]` its `$uuid`, any other `[name]` the record's own field of that name — and when that field holds several values, **any member** matches (the record's own link is its first value). Routing by a field that is not unique picks one record and which one is not guaranteed; the build warns. A folder inside `[slug]/` (`[slug]/cv/` → `/blog/:slug/cv`) is a parametric page too, about the same record: its route query is the `[slug]` page's, wherever that is declared, and a query `cv/` declares itself arrives under its own key. **A section chooses how it uses the page's record with `current:`** on its own `fetch:` — `only` (the default: the record), `exclude` (the others: "related"), `include` (all of them: a pager) — e.g. `fetch: { query: articles, as: related, current: exclude, limit: 3 }`, where `limit` counts the others, all from the query's set. **`current:` follows the query, not the key:** a fetch of the route query gets the record unless it says otherwise, whatever its `as`; a fetch of another query gets that query's records and reads `current:` only when written (`exclude` drops the page's record, `only` keeps just it). `refine: true` / `detail: false` are retired and stop the build. `[dir]` and `[path]` are refused as folder names, and so is any folder inside `[...path]/`.
 
-> **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. It is the record's brief, or the record whole where the key declares `/*` — a section that shows an article's body declares `/*`. The runtime never coerces it to an object. See *Data* in Part 4.
+> **The record arrives under the key the component declares, as that key says** — one record for a key declared `single: true` (`content.data.article` for `article: { schema: '@std/article', single: true }` over an `@std/article` query; `null` when the URL names none), a single-element array for any other key (`content.data.recent[0]`). It is the record's brief, or the record whole where the key declares `whole: true` — a section that shows an article's body declares `whole: true`. 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 own URL (`$route`, and the page a static build writes) is its name, as under `[slug]`: `/blog/my-post` wherever `records/folder.yml` places it — a record does not carry its folder. 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 it 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 own URL (`$route`, and the page a static build writes) is its name, as under `[slug]`: `/blog/my-post` wherever `records/folder.yml` places it — a record does not carry its folder. 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:**
 
-A list carries briefs, so a schema that keeps its heavy parts out of the brief — `@std/article`'s body is its own section — keeps lists light with no configuration, while a section declaring `/*` still receives the whole record on a `[slug]` page, and other components fetch it on demand with `useWholeRecord`. File-based records are written one file per record, whole, at `/data/<name>/<name of the record>.json`; an external query names its one-record request with `record:` instead (*Fetching from other sources* in Part 4). (`deferred:` is removed: a schema's brief decides what a list holds.)
+A list carries briefs, so a schema that keeps its heavy parts out of the brief — `@std/article`'s body is its own section — keeps lists light with no configuration, while a section declaring `whole: true` still receives the whole record on a `[slug]` page, and other components fetch it on demand with `useWholeRecord`. File-based records are written one file per record, whole, at `/data/<name>/<name of the record>.json`; an external query names its one-record request with `record:` instead (*Fetching from other sources* in Part 4). (`deferred:` is removed: a schema's brief decides what a list holds.)
 
 `queryable:` declares which fields a reader may filter on, with enough metadata for the foundation to render controls:
 
@@ -1740,7 +1740,7 @@ source: education
 
 ### Custom layouts
 
-Layouts live in `layouts/` inside the foundation and are auto-discovered. Set `defaultLayout` in `main.js`.
+Layouts live in `layouts/` inside the foundation and are auto-discovered. Set `defaultLayout` in `main.js`, or name a layout `Default`. With neither, a page that names no layout gets the built-in layout — `header`, the page, `footer`, nothing else — and a `defaultLayout` that names none of your layouts stops the build.
 
 ```jsx
 // layouts/DocsLayout/index.jsx
@@ -1873,21 +1873,34 @@ Content-less containers appear as group nodes (`hasContent: false`) — use `nav
 
 **A section receives the keys its component declares in `meta.js` `data:` — and nothing else** (plus any its foundation declares in `main.js` `data:`). A component that reads `content.data.articles` declares `articles`. Each declared key is filled by, in order: a tagged data block in the section; else the fetch that fills it, level by level from the section's own to the site's — a fetch whose `as` (its query's name by default) is the key, or else, **automatic `as`**, the first fetch under an undeclared key whose query's schema is the key's (`@/x` matches any scope's `x`); else `null`. So `data: { related: '@std/article' }` receives an `articles` query under `related`. `as:` on a fetch picks the key when two keys or two fetches share a schema. A fetch that fills none of a section's keys is not requested for it.
 
-**A query's records always arrive as an array.** On the query's own page, `content.data.articles` holds every record the fetch takes. On a parametric page (`[slug]/`), the record the URL names is delivered as a single-element array under the key the component declares — the section showing it reads `content.data.articles[0]` (or `content.data.article[0]` with `data: { article: '@std/article/*' }`). When nothing matches, the key is `[]`; when nothing fills it, `null`. The runtime never coerces to a single object.
+**A key says how many records it holds, and how much of each — two flags, independent.** A ref alone (`'@std/article'`) is a **list of briefs**: on the query's own page every record the fetch takes, on a parametric page (`[slug]/`) a single-element array, `[]` when nothing matches. Write the key long to change either:
 
-**Briefs or whole records — `/*`.** A key declared with a bare ref (`'@std/article'`) receives each record's **brief**: the brief section's fields at the top, the section not named. A key declared with `/*` (`'@std/article/*'`) receives each record **whole**, as stored: every section under its own name, the brief's included — `article.brief.title`, `article.body.content`. The runtime asks for what the key declares, lists and parametric pages alike; a `/*` key its source cannot answer whole is `null`. A `fields:` schema's brief is the whole record, so `/*` is only needed for a schema with more than one section. An external query's records have no schema and arrive as its source answers them. Reference: `reference/component-metadata.md` § *Briefs or whole records*.
+```js
+data: {
+  articles: '@std/article',                                         // a list of briefs
+  article:  { schema: '@std/article', single: true, whole: true },  // one record, whole
+  card:     { schema: '@std/article', single: true },               // one record's brief
+  archive:  { schema: '@std/article', whole: true },                // a list of whole records
+}
+```
+
+- **`single: true`** — the key holds **one record**: the first its binding selects (on a `[slug]` page, the record the URL names), or `null` when there is none. The runtime asks for just that one. A binding over many gives the first: sort the query, or give the binding `limit: 1`.
+- **`whole: true`** — each record **whole**, as stored: every section under its own name, the brief's included — `article.brief.title`, `article.body.content`. Without it, each record is its **brief**: the brief section's fields at the top, the section not named. The runtime asks for what the key declares; a `whole` key its source cannot answer whole is `null`. A `fields:` schema's brief is the whole record, so `whole` is only needed for a schema with more than one section.
+- The long form takes `schema`, `single` and `whole`, nothing else — the build stops on any other property, and on `single` or `whole` over a schema whose root is a list (`@std/nav`, `@std/form`: the key holds that list). ⛔ `'@std/article/*'` is retired and stops the build: write `whole: true`.
+
+When nothing fills a key it is `null`. An external query's records have no schema and arrive as its source answers them. Reference: `reference/component-metadata.md` § *One record, or a list* and § *Briefs or whole records*.
 
 ```jsx
-function Article({ content, block }) {
+function Article({ content, block }) {   // data: { article: { schema: '@std/article', single: true } }
   if (block.dataLoading) return <DataPlaceholder />
-  if (block.dataError?.articles) return <LoadFailed />   // the request failed — not "no records"
-  const article = content.data.articles?.[0]   // focused record on a [slug] page
+  if (block.dataError?.article) return <LoadFailed />   // the request failed — not "no records"
+  const article = content.data.article   // the record the [slug] page's URL names, or null
   if (!article) return <NotFound />
   return <ArticleView article={article} />
 }
 ```
 
-When a record genuinely needs to be a single object, that's the foundation's job — read `[0]`, or reshape once with a `handlers.data` hook.
+Any other reshaping is the foundation's job — once, with a `handlers.data` hook.
 
 **Declaring keys and schemas.** `meta.js` declares each `content.data` key the component receives, with its schema, in a single `data:` field — there is no separate `schemas:` key. Each value is a **named ref**, an **inline field map**, an **inline rich-form** (`{ fields: [...] }`, an editor form), or `{}` for a key with no schema (an external API's records). Refs resolve on disk at build time, never fetched: `@/name` (this foundation's `schemas/`), `@std/name` (shared standards, from `@uniweb/schemas`), `@org/name` (an org's own `@org/schemas` package). A schema drives the editor, checks your data (`uniweb validate`), and lets a fetch of another name fill the key — it fills no field: **a record reaches the component as it is**, so a field it lacks is absent, and what that renders as is your component's choice (`record.status ?? 'published'`). **A named schema declares no `default:`** — the build refuses one; a `default:` belongs only in an inline field map or form, where an editor pre-fills from it. ⛔ **Delivery was default-on until this change** — every fetched key reached every component, and `data:` was a hint; a component that reads a key it does not declare now receives nothing under it. `data: false` declares nothing, like no `data:`. Keys a foundation's handlers (or a shared hook) read go in `main.js` `data:`, in the same form, and every section receives them.
 
@@ -1915,7 +1928,7 @@ fetch:
   limit: 3
 ```
 
-**Lean lists.** A list carries each record's brief, so heavy parts belong in a section of their own — `@std/article`'s body is `body` — and never ride a list. A section that shows them declares `/*`; elsewhere components fetch the whole record on demand with `useWholeRecord(record, { query })`, which returns it as stored — `full.body.content`. Every file-based record gets its own file, `/data/<name>/<name of the record>.json`. An external query's whole record comes from its `record:` request, below. (`deferred:` is removed — the build stops on it.) The hook is safe to call on any query: when the query has no separate source for one record it returns the record you passed in.
+**Lean lists.** A list carries each record's brief, so heavy parts belong in a section of their own — `@std/article`'s body is `body` — and never ride a list. A section that shows them declares its key `whole: true`; elsewhere components fetch the whole record on demand with `useWholeRecord(record, { query })`, which returns it as stored — `full.body.content`. Every file-based record gets its own file, `/data/<name>/<name of the record>.json`. An external query's whole record comes from its `record:` request, below. (`deferred:` is removed — the build stops on it.) The hook is safe to call on any query: when the query has no separate source for one record it returns the record you passed in.
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useWholeRecord`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 
@@ -2026,7 +2039,7 @@ resolves by the same rule — the host's offer, then the site's own address, the
 neither.
 
 ⭐ **Before you render UI for a service, ask whether the site has it** — one predicate per service,
-no arguments: `isSearchEnabled()`, `isSubmitEnabled()`, `isApiEnabled()`, `isAssistantEnabled()`,
+no arguments: `isSearchEnabled()`, `isSubmitEnabled()`, `isBackendEnabled()`, `isAssistantEnabled()`,
 `isTrackingEnabled()`.
 
 ```jsx
@@ -2457,7 +2470,7 @@ For cases the factory doesn't cover, write handlers directly using `Loom`, `inst
 ## Part 4b — When the site is also an app
 
 Everything above is a site: content the author writes, built into pages. Some sites
-also have **an `api` service** — accounts, per-visitor data, records their members
+also have **their own backend, the `backend` service** — accounts, per-visitor data, records their members
 create and edit. `@uniweb/api` is its client.
 
 ⛔ **Only reach for this when the site actually has one.** A site without one is
@@ -2471,13 +2484,13 @@ npm install @uniweb/api      # in the FOUNDATION, beside @uniweb/kit
 ### Ask before you draw
 
 ```jsx
-import { isApiEnabled } from '@uniweb/kit'
+import { isBackendEnabled } from '@uniweb/kit'
 import { useSession, SignedIn, SignedOut } from '@uniweb/api'
 
-if (!isApiEnabled()) return <StaticVersion />   // synchronous — nothing to await
+if (!isBackendEnabled()) return <StaticVersion />   // synchronous — nothing to await
 ```
 
-⛔ **When the site has no `api` service, draw nothing** — not a disabled control, and not an
+⛔ **When the site has no `backend` service, draw nothing** — not a disabled control, and not an
 explanation. Same rule as `services` in Part 4: which capabilities a site's operator
 set up is none of a visitor's business, and "sign-in unavailable" reads as breakage
 when it is simply a feature this site does not have. Render the version of your
@@ -2499,7 +2512,7 @@ remove it. `scope: 'mine'` lists only the viewer's own records. Without it, the
 also gets everyone else's.
 
 ⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
-mistake to avoid.** `absent` = there is no live source (no `api` service, or nobody signed
+mistake to avoid.** `absent` = there is no live source (no `backend` service, or nobody signed
 in) → render the site's authored content. `ready` with `records: []` = the service
 answered and there is nothing there → render your empty state. Showing "nothing yet"
 for the first tells a visitor their content is gone when it was never requested.
@@ -2556,8 +2569,8 @@ You do not need a live backend to build against one. In `site.yml`:
 
 ```yaml
 services:
-  api: true                # ask your host for an app backend when you publish
-$devApi: ./mock/api.js     # what answers it in `uniweb dev`; `$` keys are never published
+  backend: true              # ask your host for it when you publish
+$devBackend: ./mock/api.js   # what answers it in `uniweb dev`; `$` keys are never published
 ```
 
 ```js
@@ -2566,7 +2579,7 @@ import { createMockBackend } from '@uniweb/api/mock'
 export default createMockBackend({ seed }).fetch
 ```
 
-`uniweb dev` answers your site's `api` service with it, at an address the dev server
+`uniweb dev` answers your site's `backend` service with it, at an address the dev server
 supplies on its own origin, so cookies behave exactly as they will in production. Write
 no address of your own for it: under `services:` an address means a backend you run, and
 asks your host to leave its own off. It **enforces** who
@@ -2596,7 +2609,7 @@ uniweb push / pull / clone / status   # Git-style content sync with the Uniweb b
 uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
 uniweb login --org @acme              # The workspace you work in — new sites are created there (see below)
 uniweb register [--scope @scope]      # Register a foundation + its data schemas to the registry
-uniweb login / logout                 # One backend, one workspace at a time: log in (--backend, --org) or out
+uniweb login / logout                 # One backend, one workspace at a time: log in (--server, --org) or out
 uniweb org list / create <handle>     # Your personal scope, and the orgs you belong to
 uniweb content export [dir]           # Package a site (or a built foundation's schema) as .uwx
 
@@ -2673,7 +2686,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 **Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. `uniweb pull` overwrites rather than merges, so it refuses while you have uncommitted changes. The recovery for both is `uniweb pull --merge` (or `uniweb refresh`, which runs `git pull` first): changes to different parts of a file combine silently, and a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull --merge && uniweb push` never ships markers. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 
-**`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. Commit it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --backend <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --backend <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--backend` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
+**`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. Commit it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --server <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --server <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--server` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
 
 **`services:` in `site.yml` is where a site says which services it uses** — site search, form
 handling, analytics, an assistant, accounts — one entry per service:
@@ -2683,12 +2696,13 @@ services:
   search: true                                     # on — your host's, or the built-in index
   submit: false                                    # off
   tracking: https://collector.example.com/events   # a provider you bring
-  api:                                             # on, with the service's own settings
+  backend:                                         # on, with the service's own settings
     grade: pro
 ```
 
 An entry is `true`, `false`, an address of your own (a string, or `endpoint:` in a map), or a map
-of options. On a site you push or publish it is also **what you ask your host for**: `true` asks for
+of options; anything else stops the build and the push. ⚠️ `yes`, `no`, `on` and `off` are text to
+YAML, not switches — write `true` or `false`. On a site you push or publish it is also **what you ask your host for**: `true` asks for
 its service, `false` asks it to turn its service off, and an address asks it to leave its own off so
 yours answers. **On a site your host publishes, a service is off unless `services:` asks for it** —
 list the ones the site uses (the templates list theirs). `records: true` asks for your records to be
@@ -2701,15 +2715,17 @@ your last pull) is left as it is, and one changed both in the file and on the si
 pull stops the push, naming it — `uniweb pull --merge`, then push. `uniweb pull` writes what the site
 has into `services:` (an off service with no settings only where the file already names it) — pull
 before you edit. A change that needs payment is settled in the app: `publish` opens it. **Everything in an entry but a
-credential is public** — it is built into the site, except `api`'s settings, which only your host
+credential is public** — it is built into the site, except `backend`'s settings, which only your host
 reads; a key or token is set in the app. ⛔ The top-level `search:` / `submit:` / `assistant:` /
-`tracking:` / `api:` keys are retired: the build stops on them and says where each one moves.
+`tracking:` / `api:` keys are retired: the build stops on them and says where each one moves. So
+does `api` under `services:` — the site's own backend is the `backend` service — and `$devApi:`,
+which is `$devBackend:`.
 
 **The Cloud also provides a real backend for structured data:** a database for every registered data schema, and a CMS that edits both static page content and dynamic data entities typed by those schemas. That's the piece that makes it viable for teams and client work — the client manages records, not markdown files.
 
 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` — `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. A registered version is immutable, so when the foundation's code changed under a version already registered, `push` and `publish` release the change under the next version and write it into the foundation's `package.json` — commit that file (`--no-release` sends the content without the code). The version it picks is always the next patch: for a change that is not backwards compatible, set a higher minor or major version in the foundation's `package.json` yourself before you push. They stop when the registry holds a version newer than yours, released from another copy: pull that change first, or pass `--bump` to release yours above it. 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. A registered version is immutable, so when the foundation's code changed under a version already registered, `push` and `publish` release the change under the next version and write it into the foundation's `package.json` — commit that file (`--no-release` sends the content without the code). The version it picks is always the next patch: for a change that is not backwards compatible, set a higher minor or major version in the foundation's `package.json` yourself before you push. They stop when the registry holds a version newer than yours, released from another copy: pull that change first, or pass `--bump` to release yours above it. 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 --server <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
 
 ### Staying current
 

package/src/backend/client.js

@@ -7,7 +7,7 @@
  * `fetch(… Authorization: Bearer …)` against a per-command default origin. It
  * owns the three things that were previously scattered across a dozen files:
  *
- *   1. ORIGIN   — where the backend is. resolveBackendOrigin(): UNIWEB_REGISTER_URL >
+ *   1. ORIGIN   — where the backend is. resolveBackendOrigin(): UNIWEB_SERVER >
  *                 the backend you are logged in to > the default backend (below).
  *                 Each is reduced to its origin, http(s) only. *(This named a
  *                 `--backend` flag as the first tier until 2026-10-05; the verbs
@@ -46,7 +46,7 @@ import { uploadSiteAssets } from '../utils/asset-upload.js'
 /**
  * Resolve the backend a command talks to:
  *
- *   1. UNIWEB_REGISTER_URL env — the override for automation (CI, scripts), one process
+ *   1. UNIWEB_SERVER env — the override for automation (CI, scripts), one process
  *   2. ⭐ the backend the user is LOGGED IN TO — the one session there is
  *   3. the default backend — ~/.uniweb/config.json `registryApiUrl`, else uniweb.app —
  *      where the command's first request then asks the user to log in
@@ -60,9 +60,10 @@ import { uploadSiteAssets } from '../utils/asset-upload.js'
  * ⛔ **No `--backend` tier, and no project tier.** The backend verbs had a per-command
  * `--backend` until 2026-09-21 — it predates per-backend sessions, when one session
  * slot made "aim this one command elsewhere" a flag's job; switching is a login now, and
- * a script aims with UNIWEB_REGISTER_URL without touching the machine's login. A
+ * a script aims with UNIWEB_SERVER without touching the machine's login. A
  * project's sync.json and deploy.yml routed commands too, until the same day.
- * `--backend` survives only where it SELECTS rather than routes: `login` (where to log
+ * A backend flag survives only where it SELECTS rather than routes — `--server`, `--backend`
+ * until 2026-10-07: `login` (where to log
  * in) and `forget` (which backend's records to remove). `logout` needs none: there is
  * one session.
  *
@@ -227,6 +228,27 @@ export class WorkspaceMismatchError extends Error {
   }
 }
 
+/**
+ * The backend could not be reached at all — the request never got an answer.
+ *
+ * ⛔ Not an answer, so it must not be read as one. A lookup that folds this into "not
+ * found" sends its caller down the not-found path: `readFoundationLatest` did, and a
+ * publish with the backend down announced "Releasing the foundation (not yet
+ * registered)…", failed inside `register`, and ended on "Fix the foundation".
+ */
+export class BackendUnreachableError extends Error {
+  /**
+   * @param {string} origin
+   * @param {unknown} cause - the transport error `fetch` threw
+   */
+  constructor(origin, cause) {
+    super(`Could not reach the backend at ${origin}: ${cause?.message ?? cause}`)
+    this.name = 'BackendUnreachableError'
+    this.origin = origin
+    this.cause = cause
+  }
+}
+
 /**
  * The line to print when a request THREW rather than answered.
  *
@@ -562,7 +584,9 @@ export class BackendClient {
 
   /**
    * GET /dev/registry/{scope}/{name} → the latest registered foundation version
-   * + its content digest, or null on 404 / any failure (callers degrade).
+   * + its content digest, or null when the backend answers with anything else (callers
+   * degrade). ⛔ A backend that cannot be reached is not an answer: that throws
+   * `BackendUnreachableError` rather than reading as "not registered".
    *
    * The bare `{scope}/{name}` path resolves the latest foundation version (the
    * data-schema sibling is `/dev/registry/data-schemas/{scope}/{name}`). The
@@ -589,7 +613,11 @@ export class BackendClient {
         ...body,
         latest_version: body.latest_version ?? body.version ?? null
       }
-    } catch {
+    } catch (err) {
+      // Node's `fetch` throws `TypeError: fetch failed` when nothing answered.
+      if (err instanceof TypeError && /fetch failed/i.test(err.message)) {
+        throw new BackendUnreachableError(this.origin, err)
+      }
       return null
     }
   }
@@ -785,6 +813,31 @@ export class BackendClient {
     })
   }
 
+  /**
+   * GET /dev/site — one page of the sites in the workspace the client names
+   * (`setWorkspace`; none ⇒ personal): `{ sites: [{ uuid, name?, updated_at,
+   * deployment?: { status, published_url, … } }] }`. A page shorter than `limit` is
+   * the last. `deployment` is absent for a site never published.
+   *
+   * @param {{ limit?: number, offset?: number }} [opts]
+   * @returns {Promise<Response>}
+   */
+  async listSites({ limit = 100, offset = 0 } = {}) {
+    return this.request('/dev/site', { query: { limit, offset } })
+  }
+
+  /**
+   * DELETE /dev/site/{uuid} — delete a site, finally: no trash, no restore. Only an
+   * admin of the site may. Refused `409` with `blockers: [{ resource, detail }]` while
+   * anything is still active — `published` among them, which `unpublishSite` clears.
+   *
+   * @param {string} uuid - the site-content uuid
+   * @returns {Promise<Response>}
+   */
+  async deleteSite(uuid) {
+    return this.request(`/dev/site/${encodeURIComponent(uuid)}`, { method: 'DELETE' })
+  }
+
   /**
    * GET /dev/site/status/{uuid} → the site's publish lifecycle (Contract 3,
    * shipped backend-side — collab backend↔framework):

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

@@ -197,7 +197,7 @@ function writePkgVersion(dir, version) {
 // and the WORKSPACE this command names (`--org` / `--personal`). The BACKEND travels in
 // the child's environment (releaseFoundation), and the SESSION is the shared session
 // file — or UNIWEB_TOKEN, which the child inherits. The backend commands take no
-// `--backend` or `--token`.
+// backend flag (`--server` is the login's) and no `--token`.
 //
 // ⭐ The workspace travels because a bare name registers under the workspace the command
 // works in *[Diego, 2026-10-06]*, and a workspace named on this command is this command's
@@ -577,7 +577,9 @@ function buildFoundation(local, cliBin) {
   execFileSync('node', [cliBin, 'build', '--target', 'foundation'], {
     cwd: local.dir,
     stdio: 'inherit',
-    env: process.env
+    // A step of this command, so the build skips the next-step hints meant for
+    // someone who ran `uniweb build` themselves.
+    env: { ...process.env, UNIWEB_BUILD_STEP: '1' }
   })
 }
 
@@ -592,7 +594,7 @@ function releaseFoundation(local, args, cliBin, say, origin) {
   execFileSync('node', [cliBin, 'register', ...forwardedFlags(args)], {
     cwd: local.dir,
     stdio: 'inherit',
-    env: origin ? { ...process.env, UNIWEB_REGISTER_URL: origin } : process.env
+    env: origin ? { ...process.env, UNIWEB_SERVER: origin } : process.env
   })
   console.log('')
   return true

package/src/backend/service-request.js

@@ -28,7 +28,7 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { readServicesRequest } from '@uniweb/build/uwx'
+import { readServicesRequest, unreadableServices } from '@uniweb/build/uwx'
 
 /**
  * A stable fingerprint of one declared value, or `null` when the key is absent.
@@ -148,7 +148,7 @@ const names = (list) => list.map((n) => `\`${n}\``).join(', ')
 
 /**
  * Say what `site.yml::services` asks that will not be sent as written — a credential,
- * an entry that is not one, an `api` address — and where it and the foundation disagree,
+ * an entry that is not one, a `backend` address — and where it and the foundation disagree,
  * before a push or publish sends the rest. What a push sends is the producer's
  * (`statedServices`), from the same file.
  *
@@ -165,6 +165,10 @@ const names = (list) => list.map((n) => `\`${n}\``).join(', ')
  * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
  */
 export function announceServices({ siteYml, say, supports = null }) {
+  // An entry the push cannot read stops the package build next, which says what to write
+  // (`refuseUnreadableServices`). Nothing to add before it — and what this would say, read
+  // past that entry, is wrong: `search: yes` was "site.yml turns on `search`" (F14).
+  if (unreadableServices(siteYml?.services).length) return
   const asks = readServicesRequest(siteYml?.services, { warn: (m) => say.warn(m) }) || []
   if (!Array.isArray(supports)) return
   const ignored = new Set(['tracking', 'records'])

package/src/backend/site-preview.js

@@ -46,7 +46,7 @@ export async function readSitePreview({ siteDir, args = [], client = null }) {
       refused: [
         `This site's foundation is ${ref}, and the backend the site is on says where that version is served.`,
         known.length
-          ? `The site is on ${known.join(', ')} — not on ${client.origin}, the backend you are logged in to. To preview it: uniweb login --backend <url>`
+          ? `The site is on ${known.join(', ')} — not on ${client.origin}, the backend you are logged in to. To preview it: uniweb login --server <url>`
           : `The site is on no backend yet: \`uniweb push\` puts it on ${client.origin}.`
       ]
     }

package/src/backend/site-sync.js

@@ -12,7 +12,7 @@
  */
 
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs'
-import { join, dirname, relative, isAbsolute } from 'node:path'
+import { join, dirname, relative, isAbsolute, basename } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { recordWritten } from '../utils/pull-written.js'
@@ -44,7 +44,7 @@ import {
   updateBackendMap,
   clearBackendSections,
   normalizeBackendOrigin,
-  removeYamlScalar,
+  writeSiteConfig,
   harvestRecordItems,
   storedRecordItems,
   reprintRecordItems,
@@ -54,7 +54,8 @@ import {
   writeRegisteredFoundation,
   backfillLinkUuids,
   LINK_MODEL,
-  bankedFileUuids
+  bankedFileUuids,
+  existingSectionFile
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -295,7 +296,15 @@ export function pulledItemVersions(doc, itemVersions) {
 // The files a unit projects to, under the site's own roots — `site.yml::paths` can
 // relocate `pages` and `layout`. `site.yml` stands for the `info` unit, which projects
 // to three files.
-function unitFilesOf(siteDir, unitPath) {
+//
+// ⭐ A section unit's path names it by its id (`pages/about/about.md`), and the author's
+// file may carry an ordering prefix or a child mark (`1-about.md`, `@about.md`), which a
+// pull writes back into in place. So the unit is looked up as a pull finds it
+// (`existingSectionFile`). ⛔ Until 2026-10-07 the id path was taken as the file: a push
+// recorded no file for a numbered section, and the next `pull --merge` merged against an
+// older version — a false conflict on a line only the other side had changed (measured
+// on the starter's `1-welcome.md`).
+export function unitFilesOf(siteDir, unitPath) {
   if (unitPath === 'site.yml') return ['site.yml', 'theme.yml', 'head.html']
   let paths = {}
   try {
@@ -304,7 +313,12 @@ function unitFilesOf(siteDir, unitPath) {
     /* no or unreadable site.yml — the defaults are right */
   }
   for (const root of ['pages', 'layout']) {
-    if (unitPath.startsWith(`${root}/`)) return [`${paths[root] || root}${unitPath.slice(root.length)}`]
+    if (!unitPath.startsWith(`${root}/`)) continue
+    const rel = `${paths[root] || root}${unitPath.slice(root.length)}`
+    if (!rel.endsWith('.md') || existsSync(join(siteDir, rel))) return [rel]
+    const id = basename(rel, '.md')
+    const found = existingSectionFile(join(siteDir, dirname(rel)), id, id, { child: true })
+    return [found ? relative(siteDir, found) : rel]
   }
   return []
 }
@@ -571,7 +585,7 @@ const readMap = (siteDir, backend, key) => {
  *     not change** — a partial site, published successfully, with nothing to
  *     indicate it.
  *
- * The guidance is `uniweb forget --backend <url>` now, which removes the uuid and the
+ * The guidance is `uniweb forget --server <url>` now, which removes the uuid and the
  * maps together, so following it no longer leads here.
  *
  * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
@@ -718,7 +732,7 @@ export function dropSiteBoundValues(siteDir, backend) {
   if (
     y.preview !== undefined &&
     !isAuthoredPreview(y.preview) &&
-    removeYamlScalar(file, 'preview')
+    writeSiteConfig(siteDir, { preview: null }) === 'updated'
   ) {
     dropped.push('preview')
   }
@@ -1902,7 +1916,7 @@ export async function pushSyncPackages({
     } catch (err) {
       error(describeRequestError(err, client.origin))
       if (!(err instanceof WorkspaceMismatchError))
-        note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+        note('Is that the backend you meant? Switch with: uniweb login --server <url>')
       return null
     }
     if (!res.ok) {
@@ -2067,7 +2081,7 @@ export async function pushSyncPackages({
       error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) {
         note(
-          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
+          "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
         )
       } else if (res.status === 404 && boundUuid) {
         // The clone is bound to a site the backend does not have. There is no CLI
@@ -2097,10 +2111,10 @@ export async function pushSyncPackages({
           'Two causes. Check the cheap one first: is this the backend the site lives on?'
         )
         note(
-          `  wrong backend  →  uniweb login --backend <the right one>   (nothing is lost)`
+          `  wrong backend  →  uniweb login --server <the right one>   (nothing is lost)`
         )
         note(
-          `  deleted there  →  uniweb forget --backend ${client.origin}, then push again: it creates a NEW site`
+          `  deleted there  →  uniweb forget --server ${client.origin}, then push again: it creates a NEW site`
         )
         note('Deleting this folder removes only your local copy, either way.')
       } else if (problem?.reason === 'template_records_not_copyable' && Array.isArray(problem.records)) {
@@ -2467,7 +2481,10 @@ export async function pushSyncPackages({
   // What the backend holds that this copy doesn't. None of it was overwritten, and no
   // later push will overwrite it — but the files are behind until a pull.
   if (notHeld.kept.length || notHeld.foreign.length) {
-    const paths = [...new Set([...notHeld.kept, ...notHeld.foreign])].sort()
+    // Named by the file it is in here, not by its id (`unitFilesOf`).
+    const paths = [
+      ...new Set([...notHeld.kept, ...notHeld.foreign].map((p) => (p === 'site.yml' ? p : unitFilesOf(siteDir, p)[0] || p)))
+    ].sort()
     note(`Changed on the backend by someone else, not in your files yet: ${paths.join(', ')}`)
     note('Take them with `uniweb refresh` (or `uniweb pull --merge`). Until then, pushing leaves them as they are.')
   }

package/src/commands/build.js

@@ -138,10 +138,11 @@ function detectProjectType(projectDir) {
  */
 function runCommand(command, args, cwd) {
   return new Promise((resolve, reject) => {
+    // No shell: the command is node and a script path, which needs none — and a shell
+    // splits a path with a space in it. (Node warns DEP0190 on args passed with one.)
     const proc = spawn(command, args, {
       cwd,
-      stdio: 'inherit',
-      shell: true
+      stdio: 'inherit'
     })
 
     proc.on('close', (code) => {
@@ -246,6 +247,9 @@ async function buildFoundation(projectDir, options = {}) {
   log('')
   log(`${colors.green}${colors.bright}Build complete!${colors.reset}`)
 
+  // The next step is for someone who ran `uniweb build` — not for a push or publish
+  // that builds the foundation as one of its own steps (UNIWEB_BUILD_STEP).
+  if (process.env.UNIWEB_BUILD_STEP) return
   log('')
   log(`${colors.bright}Share with clients:${colors.reset}`)
   log(

package/src/commands/clone.js

@@ -44,7 +44,7 @@
  *                                        another workspace stops it.
  *
  * Backend: via BackendClient (the site-content pull lane). Origin from
- *   UNIWEB_REGISTER_URL  >  the local default (internal dev overrides;
+ *   UNIWEB_SERVER  >  the local default (internal dev overrides;
  *   not the user-facing path — `uniweb login` determines the origin).
  * Auth:  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`. No `--token` (retired
  *   from the backend commands 2026-09-21).