uniweb 0.84.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,15 +42,15 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/kit": "^0.19.18",
-    "@uniweb/core": "^0.37.2",
+    "@uniweb/core": "^0.38.0",
+    "@uniweb/runtime": "^0.29.3",
     "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/runtime": "^0.29.2",
-    "@uniweb/schemas": "^0.12.0"
+    "@uniweb/schemas": "^0.13.0",
+    "@uniweb/kit": "^0.20.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.77.0",
     "@uniweb/content-reader": "^1.2.8",
+    "@uniweb/build": "^0.79.0",
     "@uniweb/semantic-parser": "^1.5.1"
   },
   "peerDependenciesMeta": {

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:
 
@@ -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.
 
@@ -1962,15 +1975,15 @@ When an external query is enough and when a transport is the answer: `developmen
 
 Full model: `reference/data-fetching.md`. Where-object format with examples: `authoring/predicates.md`.
 
-### Search (`search:`)
+### Search (`services.search`)
 
-Search follows the same arrangement as `fetcher:` — the **site** declares where results come from, and a search UI reads them the same way regardless. Never hardcode a search endpoint in a component; that couples the foundation to one host.
+Search follows the same arrangement as `fetcher:` — the **site** declares where results come from, and a search UI reads them the same way regardless. Never hardcode a search endpoint in a component; that couples the foundation to one host. Search is on by default; its entry under `services:` (see *Services*, below) turns it off, sets options, or — on a site you publish — asks the host for it:
 
 ```yaml
 # site.yml
-search:
-  enabled: true
-  provider: index        # default — download an index, match in the browser
+services:
+  search:
+    provider: index      # default — download an index, match in the browser
 ```
 
 | Provider | Answers with | Trade-off |
@@ -1980,12 +1993,13 @@ search:
 | *any other name* | A foundation-supplied search transport | Fully open — Typesense, Meilisearch, Pagefind, a vendor API |
 
 ```yaml
-search:
-  provider: endpoint
-  endpoint: _search      # REQUIRED — there is no default
+services:
+  search:
+    provider: endpoint
+    endpoint: _search    # REQUIRED — there is no default
 ```
 
-`endpoint:` is **required** with `provider: endpoint`; omit it and the provider refuses the query rather than guessing a path. It resolves against the site's base path — `/` → `/_search`, `base: /docs/` → `/docs/_search`, a subpath-served site follows its subpath. An absolute `https://…` URL points at another origin. A host that serves the site may offer search itself, supplying the address so the site declares none.
+`endpoint:` is **required** with `provider: endpoint`; omit it and the provider refuses the query rather than guessing a path. It resolves against the site's base path — `/` → `/_search`, `base: /docs/` → `/docs/_search`, a subpath-served site follows its subpath. An absolute `https://…` URL points at another origin. A host that serves the site may offer search itself: `search: true` asks for it, and the host supplies the address. An endpoint of your own asks the host to leave its search off, so yours answers.
 
 **Results have one shape, whatever the provider.** Always present: `id`, `type`, `route`, `href`, `title`, `pageTitle`, `excerpt`, `snippetHtml`. Provider-optional (`null` when absent): `sectionId`, `anchor`, `description`, `component`, `snippetText`, `matches`, `group`, `item`. `type` is `page`, `section` or `record`; on a record hit, `item` holds the record's fields and `group` names the set it came from. Whether an optional field arrives is a deployment fact, not a content fact — the same site yields `item` from a server provider and `null` from the local index — so guard them: `result.item?.image`.
 
@@ -2002,29 +2016,30 @@ const { results, isLoading, query } = useSearch(website)   // `query` is a funct
 
 Full reference: `authoring/search.md`.
 
-### Forms (`submit:`)
+### Forms (`services.submit`)
 
 Drawing a form is a foundation's job; delivering what a visitor typed needs a
 server. Where that server is comes from the **site or its host** — never from a
-section type, same arrangement as `fetcher:` and `search:`.
+section type, same arrangement as `fetcher:` and search.
 
 A form gets its destination from the first of these that applies:
 
-1. **One the host supplies** — `services.submit` in the served payload. Where the
-   host handles submissions, that is the destination and nothing in `site.yml`
-   overrides it — so a site published to Uniweb Cloud needs **no `submit:`**: it
-   asks for form handling with `services:` instead (*Uniweb Cloud*, below).
-2. **`submit:` in `site.yml`** — an endpoint you name yourself, for a host that
-   does not handle submissions, or a static site.
+1. **One the host supplies** — `config.services.submit` in the payload it serves. Where the
+   host handles submissions, that is the destination. A site published to Uniweb
+   Cloud asks for it with `submit: true` under `services:` and names no address.
+2. **An address of the site's own** — `submit: <url>` under `services:`, for a
+   static site or a host that does not handle submissions. On a host that does, it
+   asks the host to leave its own off, so this one answers.
 3. **Neither** — there is no destination: render no form, or fall back to contact
    details the site already carries.
 
 That is the general arrangement, not a forms-only one. A host states everything
-it offers in the served payload's `services`, keyed by name, and every service
-resolves by the same rule — the host's offer, then your declaration, then neither.
+it offers in the served payload's `config.services`, keyed by name, and every service
+resolves by the same rule — the host's offer, then the site's own address, then
+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
@@ -2116,10 +2131,15 @@ wherever tracking is configured, with no help from your components. List
 leaving it out does not switch the baseline off.
 
 ```yaml
-# site.yml — only when YOU are providing the endpoint. Publishing to Uniweb
-# Cloud needs nothing here; `uniweb export` and most `deploy --host` targets do.
-submit: /forms                              # base-relative, resolved like search.endpoint
-submit: https://forms.example.com/intake    # or another origin
+# site.yml
+services:
+  submit: true                              # your host's form handling (Uniweb Cloud)
+```
+
+```yaml
+# site.yml — when YOU are providing the endpoint: `uniweb export`, most `deploy --host` targets
+services:
+  submit: https://forms.example.com/intake  # or /forms, base-relative like search's endpoint
 ```
 
 ```jsx
@@ -2138,12 +2158,12 @@ if (!canSubmit) return null    // nowhere to send — render no form, or fall ba
 ```
 
 > **The framework never invents an endpoint — but a host may supply one.** Don't
-> reach for `submit:` reflexively: on Uniweb Cloud the host's form handling wins
-> wherever it is on, so a `submit:` there answers only when it is off — ask for it
-> with `services:` instead. Reach for `submit:` when you are the one hosting.
+> write an address reflexively: on Uniweb Cloud an address asks the host to turn its
+> own form handling off — `submit: true` is the whole declaration there. Reach for an
+> address when you are the one hosting.
 >
-> `canSubmit` is false only when neither a declaration nor a host supplies a
-> destination. **Check it when you render, not only on the button press** — a
+> `canSubmit` is false only when neither the host nor an address of the site's own
+> supplies a destination. **Check it when you render, not only on the button press** — a
 > form nobody can send should not be on the page at all. A read that 404s
 > degrades to `[]` and the page still renders; a write that 404s loses what a
 > person typed, so it gets no silent fallback.
@@ -2197,7 +2217,7 @@ from. `values` keeps the `File` so your input can show its selection.
 
 Full reference: `development/receiving-form-submissions.md`.
 
-### Tracking (`tracking:`)
+### Tracking (`services.tracking`)
 
 A site may declare one **tracking destination**, and everything worth counting
 goes there as an event on a single stream. A page visit is just the event the
@@ -2205,23 +2225,28 @@ runtime emits by itself.
 
 ```yaml
 # site.yml — your own collector, on any host
-tracking: https://collector.example.com/events
+services:
+  tracking: https://collector.example.com/events
+```
 
+```yaml
 # or, when it needs more than an address
-tracking:
-  endpoint: /collect
-  consent: required
+services:
+  tracking:
+    endpoint: /collect
+    consent: required
 ```
 
-A host may also supply one under `services.tracking`, and the usual precedence
-applies: the host's, then yours, then neither.
+A host may also supply one — `tracking: true` asks for it on a site you publish —
+and the usual precedence applies: the host's, then yours, then neither. An
+endpoint of your own asks the host to leave its collector off, so yours answers.
 
 ⚠️ **The endpoint has to accept the framework's own format** — a batched
 `{ "events": [ … ] }` POST, documented in `reference/site-configuration.md`. It
 is not a third-party analytics product's public API, which expects that
 product's own shape.
 
-A site may also name a vendor's own script under `tracking.scripts`, which the
+A site may also name a vendor's own script under `services.tracking.scripts`, which the
 runtime loads once, after consent when a gate is declared, and never in a frame
 or during prerender. That is a **separate path with no connection to the stream
 below** — the vendor measures its own way, and nothing you `track()` reaches it.
@@ -2271,21 +2296,24 @@ Narrow or widen that with `emit`:
 
 ```yaml
 # site.yml — your own collector
-tracking:
-  endpoint: https://collector.example.com/events
-  emit: standard        # minimal | standard | all — or a list of event names
+services:
+  tracking:
+    endpoint: https://collector.example.com/events
+    emit: standard      # minimal | standard | all — or a list of event names
+```
 
+```yaml
 # site.yml — a host that supplies the collector: say what to send, not where
-tracking:
-  emit: minimal
+services:
+  tracking:
+    emit: minimal
 ```
 
 ⭐ **`emit` needs no endpoint of its own.** Where a host provides one, the site
 declares only what it wants sent and the address comes from the host. The two
 are read key by key, so naming `emit` alone overrides nothing else the host
-declared. An `endpoint:` of your own is used wherever the host supplies no
-collector — on a host without one, and on none — and where the host supplies
-one, the host's is used.
+declared. An `endpoint:` of your own means you collect yourself, and asks the host
+to leave its collector off.
 
 `minimal` is `page_view` alone. `standard` is the default when the collector is
 your own. `all` is a standing yes, so an event added in a later framework
@@ -2442,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
@@ -2456,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
@@ -2484,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.
@@ -2540,8 +2568,9 @@ permission model and a CSS one.
 You do not need a live backend to build against one. In `site.yml`:
 
 ```yaml
-api: /_api                 # where it answers — the same value in production
-$devApi: ./mock/api.js     # what answers it locally; `$` keys are never published
+services:
+  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
@@ -2550,8 +2579,10 @@ import { createMockBackend } from '@uniweb/api/mock'
 export default createMockBackend({ seed }).fetch
 ```
 
-`uniweb dev` mounts it at your `api:` address, same-origin, so cookies and your
-site's configuration behave exactly as they will in production. It **enforces** who
+`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
 may edit an entry and `append_only`, so a permission you are relying on fails on your
 machine rather than in front of a user. State is in memory; restart to reset.
 
@@ -2578,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
 
@@ -2655,31 +2686,46 @@ 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` asks your host for services** — site search, form handling, accounts:
+**`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:
 
 ```yaml
 services:
-  search: true       # turn it on
-  submit: false      # turn it off
-  api:               # turn it on, with the service's own settings
+  search: true                                     # on — your host's, or the built-in index
+  submit: false                                    # off
+  tracking: https://collector.example.com/events   # a provider you bring
+  backend:                                         # on, with the service's own settings
     grade: pro
 ```
 
-A service you leave out keeps whatever the site has, and settings you leave out keep theirs — to turn
-one off, say `false`. `uniweb push` and `uniweb publish` send what you changed since your last sync;
-if the site's services changed elsewhere in the meantime — an author in the app — they offer to update
-`site.yml` rather than send your older choice over it, and if both changed the same service they ask
-which to keep. `uniweb pull` writes what the site has into `services:`. A change that needs payment is
-settled in the app: `publish` opens it. ⛔ **Not the same as `search:` / `submit:`**, which configure a
-provider the site brings itself — and `services:` never reaches the built site.
+An entry is `true`, `false`, an address of your own (a string, or `endpoint:` in a map), or a map
+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
+delivered live to the published pages: a query whose records have a data schema shows nothing there
+without it, and `publish` says so; a static build reads records from files and ignores it. An entry
+says everything about its service: a setting you remove from it is removed on the next push, and
+removing the entry switches the service off. `uniweb push` and `uniweb publish` send each service
+`site.yml` lists; a service the site has that this copy has never seen (turned on in the app since
+your last pull) is left as it is, and one changed both in the file and on the site since your last
+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 `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. 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