uniweb 1.0.0 → 1.0.2

package/partials/agents.md

@@ -0,0 +1,3000 @@
+# AGENTS.md
+
+## Part 0 — Read this first
+
+A Uniweb project separates **what the site says** from **how it's built**. Content authors write markdown — choosing section types, setting params, composing pages. Component developers build section types that receive pre-parsed content and render it. Neither touches the other's files.
+
+**Why that separation is cheap rather than ceremonial.** Every Uniweb site ships a runtime. A foundation is an ES module that plugs into it — either **standalone** (inlined into the site's own bundle, one self-describing artifact) or **linked** (loaded by URL at runtime as a federated module). Same foundation either way; the packaging is a deploy-time decision, not something your components know about. The runtime owns the content pipeline, section wrapping, backgrounds, theming, light/dark, prerendering, routing, and i18n; it orchestrates rendering and bridges the author's world into yours. Your components receive `{ content, params }` and render. **These are enforced guarantees, not conventions you have to uphold** — so you can drop the defensive code you'd write elsewhere.
+
+| The runtime handles | So components should NOT contain |
+|---|---|
+| Section backgrounds (image, video, gradient, color, overlay) from `background:` | Background rendering code, `bg-white`/`bg-gray-900` on the wrapper |
+| Context classes (`context-light`/`medium`/`dark`) on every section | Theme maps: `const themes = { light: {…}, dark: {…} }` |
+| Token resolution — `text-heading` adapts automatically | Conditionals: `isDark ? 'text-white' : 'text-gray-900'` |
+| Content parsing with a guaranteed shape | Defensive null checks on content fields |
+| Section wrapping in `<section>` with context class | An outer `<section>` with background/theme classes |
+| Light/dark scheme resolution before first paint | `localStorage` reads, `typeof window` guards |
+| i18n via locale-specific content directories | String wrapping with `t()` or `<Trans>` |
+
+Concretely, the code you don't write: no theme maps, no `isDark ? … : …`, no null checks on content fields, no `t()` wrapping, no per-component background rendering, no SSR guards, no outer `<section>`. A hero that's 200 lines of undifferentiated React elsewhere is a 40-line component plus a markdown file here — and the markdown is editable by someone who has never opened your code.
+
+Components *should* contain: layout (`grid`, `flex`, `max-w-7xl`), spacing (`p-6`, `gap-8`), typography scale (`text-3xl`, `font-bold`), animations, border-radius — anything that stays the same regardless of theme context.
+
+Once content reaches your component, **it's standard React.** Standard Tailwind. Import any library, use any pattern. The `{ content, params }` interface applies only to *section types* (the components authors select in markdown); everything else in your foundation is ordinary React with ordinary props.
+
+You're building a *system* of section types, not individual pages. That's what makes theming, i18n, and multi-site tractable — they're properties of the system rather than things bolted onto each component.
+
+### Route yourself
+
+| Your situation | Start at |
+|---|---|
+| New or nearly empty project | **Part 1**, then Part 4 |
+| Existing project, content task (pages, copy, colors, nav) | **Part 2**, then Part 3 |
+| Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
+| Porting a design from React / Next / a generated site | **Part 1**, then Part 5 → *Migrating* |
+
+### Three commands that replace guessing
+
+```bash
+uniweb inspect <path>        # print the parsed content shape of a section or page
+uniweb <command> --help      # exact flags, always current — no side effects
+uniweb doctor                # diagnose project configuration (--fix to repair)
+```
+
+`uniweb inspect` is the important one. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+
+### The four silent failures
+
+Most Uniweb mistakes do not fail the build. The build goes green, the terminal is clean, and the page is wrong. If you don't look at the page or run `inspect`, you will report success on broken output.
+
+1. **An unknown section type renders a red `Component not found: <Type>` box.** The build does not fail. Never write a `type:` you haven't confirmed exists — see Part 2, step 2.
+2. **An undeclared param is accepted and does nothing.** Frontmatter keys no `meta.js` declares are passed through and ignored, not rejected.
+3. **Content lands in the wrong field.** A heading becomes a `subtitle` when you wanted an item, or the reverse. That's the level rule (Part 3). `uniweb inspect` settles it.
+4. **A section silently doesn't render.** `@`-prefixed files are child sections (only rendered via `nest:`), `_`-prefixed files are drafts, and section types nested below the root of `sections/` without a `meta.js` are never discovered.
+
+### Documentation
+
+This guide covers what you can't derive by reading code. Everything else is in the full documentation — and **you can reach all of it without guessing at URLs.**
+
+**Start at the index.** One address, and it's the only documentation URL worth memorizing:
+
+```
+https://www.uniweb.io/llms.txt
+```
+
+It lists every documentation page with a one-line description and a fetchable link. Go there whenever your question isn't answered in this file — and *especially* when you don't know whether a feature exists at all. That's where guessing does the most damage: **a 404 on a path you invented tells you your guess was wrong, not that the feature is missing.** Concluding "the framework doesn't support X" from a failed fetch is a mistake worth actively guarding against; the index answers the existence question directly.
+
+Then **follow the link the index gives you** rather than constructing one yourself. The index is the source of truth for where pages live, so it stays correct when the site's URL conventions change. (Pages also serve markdown to any client that sends `Accept: text/markdown`.)
+
+**Clone the repo instead** when you expect several lookups, or may lose network access later:
+
+```bash
+git clone --depth 1 https://github.com/uniweb/docs .uniweb-docs   # then gitignore it
+```
+
+Same content, greppable, and one network operation instead of many. `grep -ri "queryable" .uniweb-docs` beats any number of fetches while you're still exploring.
+
+Documentation paths in this guide are given bare — `development/creating-components.md` — so they resolve three ways: as a key in the index, as a file in a clone, or at `https://raw.githubusercontent.com/uniweb/docs/main/{path}`.
+
+> **Don't confuse the two doc sites.** `www.uniweb.io/docs` is the **developer** documentation — this is the one you want. `docs.uniweb.app` is the *author-facing* app documentation, written for non-technical people using the visual editor; it won't answer framework questions.
+
+**The table below saves you the round trip** for the tasks that come up most:
+
+| Task | Page |
+|------|------|
+| Writing page content | `authoring/writing-content.md` |
+| Theming and styling | `authoring/theming.md` |
+| Working with records and queries | `authoring/collections.md` |
+| Where-object predicate format | `authoring/predicates.md` |
+| Data sources / custom transports | `development/data-sources.md` |
+| Building components | `development/creating-components.md` |
+| Schemas in practice | `development/schemas-in-practice.md` |
+| Workspace layouts and their wiring | `development/project-structures.md` |
+| Migrating an existing design | `development/converting-existing.md` |
+| Internationalization (full model) | `development/internationalization.md` |
+| Kit API (hooks, components) | `reference/kit-reference.md` |
+| Content shape reference | `reference/content-structure.md` |
+| Component metadata (`meta.js`) | `reference/component-metadata.md` |
+| Site configuration | `reference/site-configuration.md` |
+| Queries — everything a query can say | `reference/queries.md` |
+| Data fetching model | `reference/data-fetching.md` |
+| Navigation patterns | `reference/navigation-patterns.md` |
+
+For anything not in that table, start at the index. For CLI flags, prefer `uniweb <command> --help` over any of this — it's always current.
+
+---
+
+## Part 1 — Starting a project
+
+**Always use the CLI to scaffold — never hand-write `package.json`, `vite.config.js`, `entry.js`, or `index.html`.** The CLI resolves correct versions and structure; hand-written config is the most common way to end up with a project that can't build.
+
+```bash
+npx uniweb@latest create my-project --template marketing
+cd my-project && pnpm install
+uniweb dev
+```
+
+`@latest` matters: a project starts on the packages and templates of the CLI that creates it, and a bare `npx uniweb` runs a globally installed `uniweb` when there is one, however old.
+
+**Choosing a template.** `--template <name>` gives you a working site plus a foundation you can study and edit. `--template none` gives you the same two packages with no content — the right choice when you're building a foundation from scratch or porting a design. `--blank` gives you an empty workspace and assumes you'll add packages with `uniweb add`; use it only if you already know the framework.
+
+Official templates include `marketing` (tokens, insets, grids, multi-line headings), `docs` (sidebar nav, code highlighting), `blog` (records of the standard `@std/article` schema, a query, a parametric `[slug]` page), `dynamic` (live API data, loading states), `international` (i18n, records, multi-locale routing), `store` (product grids, e-commerce), `academic` (publications, timeline, math), `extensions` (multi-foundation, runtime loading). `uniweb template list` shows them all.
+
+**npm or pnpm.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command in this guide.
+
+### What you get
+
+```
+my-project/
+├── src/            # the foundation — component developer's domain
+├── site/           # the site — content author's domain
+└── pnpm-workspace.yaml
+```
+
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. **`src` and `foundation` are never a foundation's name** — `uniweb register` refuses them, because every project in an org would register the same one.
+
+- **Foundation** (`src/`): React components. Those in `sections/` and `layouts/` are *section types* — selectable by authors via `type:`, or used for layout areas. Everything in `components/` and `utils/` is ordinary React and JS: the developer's workbench, not visible to authors.
+- **Site** (`site/`): markdown content and configuration, plus optional records of structured content and the queries that reach them or an external data source.
+
+**The composition boundary.** Authors compose pages from finished section types — choosing types, writing content, setting params. Developers compose section types from building blocks — importing helpers, using libraries, writing JSX. Two different levels of composition, and the section type is the boundary between them. Don't expose building-block composition to authors; build complete, self-contained section types that handle their own internal structure.
+
+### Growing the workspace
+
+```bash
+uniweb add project docs                            # co-located pair → docs/src + docs/site
+uniweb add foundation [name|path] [--path parent]  # no name → ./src/, bare name → ./name/, slash → that path
+uniweb add site [name|path]
+uniweb add extension <name> [--site <name>]        # secondary foundation, wired to a site
+uniweb add section Hero [--foundation ui]          # sections/Hero/{index.jsx,meta.js}
+```
+
+The CLI creates exactly the folder you ask for — no silent nesting under `foundations/` or `sites/`. If the target exists or the package name is taken, it stops with a precise error and suggests alternatives (using the same `classifyPackage` logic the build uses, so cross-type collisions are caught: you can't `add site marketing` when a foundation named `marketing` exists).
+
+`uniweb add section` scaffolds a CCA-proper starter, and the dev server picks it up with no build or install.
+
+### Learn from a working template
+
+**When you're unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — read a real one instead of guessing.** Install an official template as a second project in your workspace:
+
+```bash
+uniweb add project marketing --from marketing
+pnpm install
+```
+
+That creates `marketing/src/` + `marketing/site/` alongside your project. You don't need to build or run it. Read:
+
+- `marketing/src/sections/` — components with `meta.js`: what content they expect, what params they accept, what presets they define
+- `marketing/site/pages/` — real content files, showing the markdown → component mapping
+- `marketing/site/theme.yml` and `site.yml` — theming and configuration in practice
+
+This is the highest-bandwidth way to learn the framework, and it works with no network access. Install several if you like; each is independent. To run one: `cd marketing/site && pnpm dev`.
+
+### The loop
+
+```bash
+uniweb dev            # from the workspace root; it picks the site for you
+pnpm build            # production build (SSG + SPA)
+pnpm preview          # preview the production build
+```
+
+Markdown, `theme.yml`, and component edits hot-reload. New section types are picked up without a restart.
+
+---
+
+## Part 2 — Working in an existing project
+
+The rest of this guide explains how Uniweb works. This part is what to do *first* when you've been handed a project that already uses it, plus a task.
+
+### 1. Orient — what kind of workspace is this?
+
+**There is no single layout. Read `pnpm-workspace.yaml` first** — its `packages:` globs name the shape in one glance:
+
+| Globs | Layout | What it implies |
+|---|---|---|
+| `src`, `site` | **single** (the default) | foundation in `src/`, site in `site/` |
+| `foundations/*`, `sites/*` | **segregated** | several sites may share one foundation — a foundation edit hits all of them |
+| `*/src`, `*/site` | **co-located projects** | one self-contained pair per project: `docs/src` + `docs/site` |
+| a package whose `main.js` says `extension: true` — `effects`, `extensions/*` (alongside any of the above) | extensions present | extra section types, runtime-loaded — see step 2 |
+
+Those names are convention; the globs are the truth. Full guide with the wiring for each: `development/project-structures.md`.
+
+**A site is any package with a `site.yml` and a `pages/` folder** — a workspace can hold several. Everything below calls yours `<site>/`.
+
+**Find the foundation by following the wiring, not by guessing the folder.** `foundation:` in `site.yml` is a **package name**, not a path, and folder name matches package name only by convention — co-located projects break it deliberately (folder `docs/src`, package `docs-src`). Go from name to folder via the matching `file:` dependency in `<site>/package.json`:
+
+```json
+// docs/site/package.json  →  the foundation is at docs/src/
+{ "dependencies": { "docs-src": "file:../src" } }
+```
+
+If `foundation:` isn't a workspace package name, the source isn't in this repo at all:
+
+| `foundation:` value | What it means | Can you add a section type? |
+|---|---|---|
+| a workspace package name (`src`, `docs-src`, `marketing`) | source is in this repo — follow the `file:` dep to it | **Yes** |
+| a versioned registry ref (`@org/name@1.2.3`) | published; **its source is not in this repo** | **No** — work within the types it offers |
+| an `https://…` URL, or `{ url: … }` | same, loaded from that URL | **No** |
+
+A versionless `@org/name` is an error rather than a shorthand — the build rejects it and asks for a version.
+
+> **Foundations are never npm packages.** They're runtime federated modules, not libraries. Don't `npm install` one, and don't add one to `dependencies` by hand. The four supported shapes are exactly the ones above: a workspace sibling, a `file:` dependency, a versioned registry ref, or a full URL.
+
+> **The same `@scope/name` shape means different things in different places.** As a `foundation:` value it is a **catalog** ref (never npm). As a data-schema ref in `meta.js` it resolves on disk from an **npm package** — `@std/*` from `@uniweb/schemas`, any other `@org/*` from that org's `@org/schemas`. And `@uniweb/kit` in `dependencies` is an ordinary npm package. Position decides the registry; the shape tells you nothing.
+
+**Check `paths:` in `site.yml` before going looking for content.** It mounts outside directories into the page tree (`paths: { pages/docs: ../../../docs }`), so a route's markdown may live in another repo or a submodule rather than under `<site>/pages/`.
+
+### 2. Learn this project's vocabulary — before you write anything
+
+**A foundation is a fixed vocabulary of section types, and every project's is different.** Nothing in the framework tells you what a given project offers; you read it — in the foundation folder you resolved in step 1, not a guessed `src/`:
+
+```bash
+ls <foundation>/sections/                    # the section types available
+cat <foundation>/sections/Hero/meta.js       # what one expects and accepts
+```
+
+**Extensions add to that vocabulary.** If `site.yml` carries an `extensions:` list, each entry is a second foundation contributing its own section types, usable by name in exactly the same way. Enumerate their `sections/` too. The primary foundation wins on a name collision, and extensions are checked in declared order.
+
+**An extension *is* a foundation** — same build, same output; it just contributes no Layout or theme variables. So each entry takes the **same shapes** `foundation:` does: a workspace package name, a versioned catalog ref (`@org/name@1.2.3`), or a full URL. Use the same table above to decide whether you can add a section type to one.
+
+> **A site-relative URL (`/effects/entry.js`) only works where the site serves its own files** — `uniweb export` and `uniweb deploy --host=<adapter>`. A site published to Uniweb hosting ships no JS, so nothing serves that path, and `uniweb publish` rejects it with a pointer to the catalog-ref form. Register the extension (`uniweb register` in its directory) and reference it like any other foundation. When you reference a workspace-local extension, `uniweb publish` brings it along exactly as it does the primary — releasing it if its code changed, and pinning the released version on the published site.
+
+Each `meta.js` is a catalog entry: `description` (what the type is for), `content:` (what markdown it expects), `params:` (what frontmatter it accepts, with defaults), `presets:` (named param bundles), and optionally `family:` (the standard section family it belongs to). Read them as a menu — that is what they are. There is no CLI command that lists them; reading the folder *is* the discovery step.
+
+> **Never write a `type:` or a param you haven't confirmed exists.** Both failures are silent (Part 0) — invisible from the terminal, visible only on the page.
+
+#### `family:` — so an editor can draw your section
+
+An editor showing an author a section picker has to know what each section type
+**is**, to pick its illustration and a label it can translate. Two ways to tell
+it, in this order:
+
+1. **Name the component for its family.** Run `uniweb families`, and use one of
+   those names when it fits — `Hero`, `Footer`, `Pricing`, `FAQ`, `CardGrid`.
+   Then there is nothing to declare: the name resolves on its own.
+2. **Declare `family:`** when the name is yours — a variant, or your own
+   vocabulary:
+   ```js
+   // sections/ProfileHero/meta.js
+   export default { title: 'Researcher Profile', family: 'profile' }
+   ```
+   One value, the dominant shape: a `HeroWithEstimate` is `family: 'hero'`.
+
+**Leave it off when nothing fits.** A section that is genuinely specific to this
+site gets a generic illustration, and that is the right outcome — do not force it
+into the nearest family. `uniweb doctor` shows what each of your sections
+resolved to, and suggests a family for any it recognises by another name.
+
+### 3. Find your lane
+
+The architecture exists to keep content and code separate. Your task sits in one of them. Decide before you edit, then stay there.
+
+| Task | Lane | Files you touch |
+|---|---|---|
+| Add / edit / reorder a section on a page | content | `<site>/pages/**` |
+| Add a page | content | `<site>/pages/<name>/` |
+| Change colors, fonts, light/dark | content | `<site>/theme.yml` |
+| Change header, footer, or nav content | content | `<site>/layout/*.md`, or page order in `site.yml` |
+| Change how a section type *looks* everywhere | foundation | `<foundation>/sections/<Type>/` |
+| Add a new section type | foundation | `<foundation>/sections/<NewType>/` |
+| Expose a new knob to authors | foundation | `<foundation>/sections/<Type>/meta.js` + the component |
+
+**If you're on a content task and find yourself wanting to open the foundation, stop.** Usually it means you missed a param the section type already exposes — re-read its `meta.js`. If the knob genuinely doesn't exist, that's a foundation change: say so explicitly rather than quietly crossing the boundary. Editing a section type changes it for every page that uses it — and in a segregated workspace, for **every site in the repo sharing that foundation**, which is exactly the layout chosen when a foundation is the primary deliverable. Check who else depends on it before you edit.
+
+### 4. The loop
+
+```bash
+uniweb dev                         # from the workspace root; it picks the site
+```
+
+**When you're unsure what shape your markdown produces, don't reason about it — run it.** From the *site* directory (paths resolve against your shell's working directory):
+
+```bash
+uniweb inspect pages/home/hero.md              # the parsed content shape
+uniweb inspect pages/home/                     # every section on the page
+uniweb inspect pages/home/hero.md --full       # include empty fields (matches runtime)
+uniweb inspect pages/home/hero.md --sequence   # include the sequence array
+uniweb inspect pages/home/hero.md --raw        # the ProseMirror AST
+```
+
+This settles any question in Part 3 — whether a heading became a subtitle or an item, whether the parser saw your data block, why `content.title` is an array. One command beats re-deriving the rules.
+
+### 5. Recipes
+
+Paths are relative to the site package you identified in step 1 — `site/` in the default layout, `sites/main/` or `docs/site/` in others.
+
+**Add a section to a page.** `ls <site>/pages/<page>/` to see the existing sections and their numeric prefixes → pick a `type:` from the vocabulary (step 2) → create `<site>/pages/<page>/N-name.md` with frontmatter plus markdown. Use a decimal (`2.5-…`) to slot between existing sections without renaming them.
+
+**Add a page.** Create `<site>/pages/<name>/`, add `page.yml` (at minimum `title:`), add one or more section `.md` files. It gets the route `/<name>` automatically. Only touch `pages:` in the parent `page.yml` / `site.yml` if you need a specific order.
+
+**Change the brand color.** `<site>/theme.yml` → `colors.primary`. One line, and every component follows. Do **not** edit Tailwind color classes in components to change brand color — that is the exact anti-pattern this system removes.
+
+**Change how code blocks look.** `<site>/theme.yml` → `code:`. Name one of Shiki's 65 bundled themes (`code: dracula`), name one per scheme (`code: { light: github-light, dark: github-dark }`), or take a theme and adjust it (`code: { theme: github-dark, background: '#0D0D0D' }`). Hand-picking every syntax colour is possible and is the last thing to reach for.
+
+**Change a nav item.** First check how nav is produced. If `<site>/layout/header.md` lists the links (a markdown list, or a `yaml:nav` block), edit it there. If it doesn't, the Header is generating nav from the page hierarchy — change page titles and order in `site.yml` / `page.yml` instead.
+
+**Update the project's Uniweb dependencies — and this file.** `npx uniweb@latest update`. One command aligns every `@uniweb/*` dependency *and* refreshes this AGENTS.md together. Preview with `--dry-run`. ⛔ **The `@latest` is doing the work** — a bare `uniweb update` runs the CLI this project already pins, which aligns you to the matrix you already have and correctly reports nothing to do. **Don't reach for `npm update` / `pnpm update`** — see *Staying current* in Part 5 for why that breaks things quietly.
+
+**Change one section's columns / spacing / variant.** Check that type's `meta.js` `params:` first. If the knob exists, set it in that section's frontmatter and you're done, in the content lane. If it doesn't, it's a foundation change — see the warning in step 3.
+
+---
+
+## Part 3 — The content lane
+
+### Section format
+
+Each `.md` file is a section. Frontmatter on top, content below:
+
+```markdown
+---
+type: Hero
+theme: dark
+---
+
+#> New in v1              ← pretitle (the label line above the title)
+
+# Build the system.       ← title (the big headline)
+
+## Not every page.        ← subtitle (one step smaller, directly below)
+
+Description paragraph.
+
+[Call to Action](/link)
+
+![Image](./image.jpg)
+```
+
+Heading levels set *structure* (pretitle, title, subtitle), not font size — the component controls visual sizing. Write a pretitle as a `#>` label line — any number of leading `#`s spells the same label, so match the heading you are labelling. A smaller ordinary heading directly above the title is *also* read as a pretitle, which is how files written before label lines keep working; prefer `#>`, because it says what it is wherever it lands rather than depending on what follows it.
+
+**A section with no `type:` renders through the foundation's default section type — a component named `Section`, unless the foundation's `main.js` sets `defaultSection` to something else.** This is what lets a folder of plain markdown with no frontmatter at all become pages: mounted documentation, an imported wiki, anything written before it met this framework. If such content renders blank, the foundation has no `Section` — that, not the markdown, is what to fix.
+
+**Markdown order ≠ rendering order.** The parser extracts content into a flat structure; the component decides how to arrange it visually. Write markdown in semantic order, not visual order — start with the heading, then add icons, images, and text in any order.
+
+**Placing content *before* the first heading changes the parse:** headings after body content become items, not the section title. This is by design — it's how repeating content groups are created.
+
+### The parsed object
+
+The semantic parser produces a flat, guaranteed structure. No null checks needed — empty strings and arrays when content is absent:
+
+```js
+content = {
+  title: '',        // Main heading (string or string[] for multi-line)
+  pretitle: '',     // `#>` label line(s) — also filled by smaller headings
+                    //   stacked above the title, for older content
+                    //   (string or string[])
+  subtitle: '',     // Line(s) one step below the title — each further
+                    //   one-step descent is another line (string or string[])
+  paragraphs: [],   // Text blocks
+  links: [],        // { href, label, role } — standalone links (not inside lists)
+  images: [],       // { src, alt, role, href }
+  icons: [],        // { library, name, role }
+  videos: [],       // { src, alt, role, poster, href }
+  documents: [],    // { url, alt, caption, role: 'pdf', preview?, author?, description? } — from {role=pdf}
+  insets: [],       // Inline @Component references — { refId }
+  lists: [],        // [[{ paragraphs, links, lists, … }]] — each item is an object, not a string
+  quotes: [],       // Blockquotes
+  snippets: [],     // Fenced code — [{ language, code }]
+  data: {},         // Tagged blocks — ```yaml:tag / ```json:tag give the parsed value,
+                    //   ```md:tag gives { items, sequence } (see Concept blocks)
+  tables: [],       // Only when present — [{ rows: [{ cells: [{ children, header, align }] }] }]
+  headings: [],     // Only from nested content (quote/list bodies) — a
+                    //   section's headline never spills here
+  items: [],        // Each has the same flat structure — from headings after body content
+  sequence: [],     // All elements in document order
+}
+```
+
+> **Don't predict this — print it.** `uniweb inspect <path>` shows the actual parsed shape of any section or page. The rules below are the ones most often gotten wrong from memory.
+
+### Markdown → content, side by side
+
+```markdown
+#> Eyebrow                     │  content.pretitle = "Eyebrow"
+# Our Features                 │  content.title = "Our Features"
+## Build better products       │  content.subtitle = "Build better products"
+                               │
+We help teams ship faster.     │  content.paragraphs[0] = "We help teams…"
+                               │
+[Get Started](/start)          │  content.links[0] = { href: "/start", label: "Get Started" }
+                               │
+### Fast                       │  content.items[0].title = "Fast"
+![](lu-zap)                    │  content.items[0].icons[0] = { library: "lu", name: "zap" }
+Lightning quick.               │  content.items[0].paragraphs[0] = "Lightning quick."
+                               │
+### Secure                     │  content.items[1].title = "Secure"
+![](lu-shield)                 │  content.items[1].icons[0] = { library: "lu", name: "shield" }
+Enterprise-grade security.     │  content.items[1].paragraphs[0] = "Enterprise-grade…"
+```
+
+The staircase rule produces this — each heading relates to the one before it: the same size adds another line to the same part; **one step smaller** joins the headline as the next part down (the subtitle, then further subtitle lines); **two steps smaller** starts an item; and once body content has begun, *any* heading starts an item. `#>` label lines become `pretitle`; so do smaller headings stacked above the title, which is the older spelling.
+
+### Items have the full content shape
+
+This is the most commonly overlooked feature. Each item has `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `icons`, `lists`, `snippets`, and `data` — you don't need workarounds for structured content inside items. Heading hierarchy within an item follows the same rules (`####` inside a `###` item becomes that item's `subtitle`).
+
+````markdown
+### Starter               ← items[0].title
+$9/month                  ← items[0].paragraphs[0]
+
+```yaml:details
+trial: 14 days
+seats: 1
+```                       ← items[0].data.details = { trial: "14 days", seats: 1 }
+````
+
+### Subtitle vs items — the step rule
+
+A heading directly after the title becomes `subtitle` **only when it is exactly one step smaller** (H1→H2, H2→H3) — and each *further* one-step line continues the subtitle (a three-line header is `subtitle: [line2, line3]`). **Two steps smaller starts items** — the idiom for entries with no lead paragraph:
+
+```markdown
+# Our Stats                       │  content.title = "Our Stats"
+### 15,000+                       │  content.items[0].title = "15,000+"
+Students from 90 countries        │  content.items[0].paragraphs[0]
+                                  │
+### 200+                          │  content.items[1].title = "200+"
+Programs offered                  │  content.items[1].paragraphs[0]
+```
+
+With `## 15,000+` instead, the first stat would join the headline as `content.subtitle`. A `---` divider, or any body content after the headline, also closes it — after body, headings of *any* size start items.
+
+### Multi-line headings
+
+Consecutive headings at the same level merge into a title array — one heading split across visual lines. Kit's `<H1>`, `<H2>`, … render arrays as a single tag with line breaks.
+
+```markdown
+# Build the future              │  content.title = ["Build the future", "with confidence"]
+# with confidence               │
+
+# Build the future              │  content.title = [
+# [with confidence]{accent}     │    "Build the future",
+                                │    "<span accent=\"true\">with confidence</span>"
+                                │  ]
+```
+
+**Rule:** a repeated size always continues the part it repeats — title lines, or subtitle lines once the headline has stepped down. Use `---` to force separate items where adjacent headings would otherwise continue the headline.
+
+### Sequential content
+
+`content.sequence` is the flat, ordered list of all elements before any grouping. Each element has a `type` (`heading`, `paragraph`, `image`, `codeBlock`, `dataBlock`, `list`, `link`, `divider`, `inset`, …) plus type-specific fields. Use it when grouping isn't the right lens — rendering prose in document order, or finding elements regardless of which group they landed in:
+
+```js
+const allData = {}
+for (const el of content.sequence) {
+  if (el.type === 'dataBlock') allData[el.tag] = el.data
+}
+```
+
+Grouped fields and `sequence` are two interpretations of the same content. Grouped suits structured layouts (cards, features); sequential suits prose and cross-group searching.
+
+### Choosing how to model content
+
+The decision rule: **would a content author need to change this?** Yes → markdown, frontmatter, or a tagged data block. No → component code.
+
+Start with the content, not the component. Write the markdown an author would naturally write, check what shape the parser produces (`uniweb inspect <file>`), *then* build the component to receive it. You have three layers, and most of the design skill is choosing between them:
+
+**Pure markdown** — headings, paragraphs, links, images, lists, items. The default. If the content reads naturally as markdown and the parser captures it, stop here.
+
+**Frontmatter params** — `columns: 3`, `variant: centered`. Configuration an author might change but that isn't *content*. Would changing this alter the section's *meaning* or just its *presentation*? Presentation → param. Meaning → content.
+
+**Tagged data blocks** — for content that doesn't fit markdown patterns: products with SKUs, team members with roles, event schedules, form definitions. When information is genuinely structured data that an author still owns, a well-named block (`yaml:pricing`, `yaml:speakers`) is clearer than contorting markdown. Formats: `yaml` and `json`. Parsed at build time into `content.data.tagName`.
+
+Read the markdown out loud. If an author would understand what every line does, you've chosen right. The moment markdown feels like it's encoding data rather than expressing content, step up to a tagged block.
+
+**When you are building the foundation, you are designing these, not choosing from a menu.** The examples in this guide illustrate patterns, not exhaustive inventories. Any param name works in `meta.js`, any tag name works for data blocks, any section type name works. The framework has fixed mechanisms (content shape, context modes, token system); nearly everything else is yours to define.
+
+**When you are writing content against a foundation that already exists, the opposite holds.** The vocabulary is fixed and finite: the section types are exactly what `sections/**` declares, and their params are exactly what each `meta.js` lists. Inventing a name there doesn't extend the system — it renders a red `Component not found` box on a build that otherwise reports success.
+
+**Parameter naming matters.** Would an author understand it without reading code? `columns: 3` yes, `gridCols: 3` no. `variant: centered` yes, `renderMode: flex-center` no. `align: left` yes, `contentAlignment: flex-start` no.
+
+### Repeated values — `placeholders:`
+
+A value that appears on many pages goes in `site.yml` once, not in a dozen markdown files:
+
+```yaml
+placeholders:
+  product: Uniweb
+  vendor:
+    email: billing@acme.example
+```
+
+Any page then references it by name — `Write to {vendor.email}.` Dot paths work, and a record's own field of the same name always wins, so `{title}` on an article page is that article's title regardless of what the site declares.
+
+⛔ **Resolution is a foundation capability, not a framework one.** `{…}` is resolved by the foundation's `handlers.content` hook — normally `createLoomHandlers` from `@uniweb/loom`. Under a foundation without one, `placeholders:` is inert and pages render the literal `{vendor.email}`, which reads as a typo. The build warns when a site declares the key and the foundation has no content handler.
+
+```js
+// main.js — a foundation opts in
+import { createLoomHandlers } from '@uniweb/loom'
+export default { handlers: createLoomHandlers({ vars: (data) => data?.profile?.[0] }) }
+```
+
+Placeholders are the simplest case of a larger language: the same expressions filter, sort, count and format live data (`{COUNT OF publications WHERE refereed}`). Reach for one when a value repeats; reach for the rest when content is genuinely derived from records.
+
+### Icons
+
+Image syntax with a library prefix — **two interchangeable spellings, the same everywhere** (markdown, and Kit's `<Icon name>`):
+
+```markdown
+![](lucide:house)     colon + friendly name — every library
+![](lu:house)         colon + short code
+![](lu-house)         dash — short codes only, to stay unambiguous with ordinary paths
+```
+
+Short codes: `lu` (Lucide), `hi` / `hi2` (Heroicons v1 / v2), `fi` (Feather), `pi` (Phosphor), `tb` (Tabler), `bs` (Bootstrap), `md` (Material), `ai` (Ant Design), `ri` (Remix), `si` (Simple Icons), `io5` (Ionicons), `bi` (Boxicons), `vsc` (VS Code), `wi` (Weather), `gi` (Game), `fa` / `fa6` (Font Awesome 5 / 6). Browse at [react-icons.github.io/react-icons](https://react-icons.github.io/react-icons/).
+
+Optional attributes: `{size=20}`, `{color=red}`. Custom SVGs: `![Logo](./logo.svg){role=icon}` (or `![Logo](icon:./logo.svg)`) — always available, no library needed.
+
+### Links and media attributes
+
+```markdown
+[text](url){target=_blank}              <!-- Open in new tab -->
+[text](./file.pdf){download}            <!-- Download -->
+![alt](./img.jpg){role=banner}          <!-- Role determines array: images, icons, videos or documents -->
+![alt](./demo.mp4){role=video}          <!-- → content.videos[], not content.images[] -->
+![alt](./report.pdf){role=pdf}          <!-- → content.documents[] — a file, drawn as a link -->
+![alt](./img.jpg){href=/products}       <!-- Clickable media: href + target ride along -->
+```
+
+Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=cover position=center}`. A video adds `{poster=./thumb.jpg autoplay muted loop controls}`; a `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}` and arrives in `content.documents` — `{ url, name, mime, size?, alt, caption, … }` — declare it in `content:` as `documents`.
+
+**Quote values containing spaces:** `{note="Ready to go"}`, not `{note=Ready to go}` — unquoted values end at the first space.
+
+**Separators are forgiving.** `:` works wherever `=` does, and pairs may be separated by whitespace, a comma, or both — `{role=banner width=1200}`, `{role:banner, width:1200}` and `{role:banner,width:1200}` are identical. `=` and spaces are canonical, and that is what gets written back on save. Two rules keep it unambiguous: the separator must **touch** the key (`{note:warning}` is one pair, `{note : warning}` is two flags), and a value containing a **comma** must be quoted (`{style="a, b"}`). A value containing a colon needs no quoting — only the first colon separates, so `{href:https://example.com}` is fine.
+
+Standalone links (alone on a line) become buttons in `content.links[]`. Inline links stay as `<a>` tags inside `content.paragraphs[]`. Multiple links sharing a paragraph are all promoted:
+
+```markdown
+[Primary](/start)              ← standalone → content.links[0]
+[One](/a) [Two](/b)            ← links-only paragraph → both in content.links[]
+Check out [this](/a) link.     ← inline → stays in paragraphs as an <a> tag
+```
+
+### Inline text styling
+
+```markdown
+# Build [faster]{accent} with structure
+This is [less important]{muted} context.
+```
+
+`accent` and `callout` (both accent-colored + bold) and `muted` (subtle) are built-in defaults that adapt to context. `--accent` is your brand color unless you declare a separate `colors.accent`, and resolves to the shade you authored — not a darkened one, since accent is decorative emphasis rather than body-size link text. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
+
+Sites can adjust these or add named styles in `theme.yml`'s `inline:` section. Overrides merge **property by property**, so declare only what differs (`accent: { font-weight: inherit }` keeps the default color); to drop a default property rather than change it, give it a neutral value (`initial`, `inherit`, `unset`).
+
+> **On a site synced with Uniweb Cloud, the built-in style names round-trip *editable*** — an author who opens a page containing `[Get started]{accent}` gets the editor's own styling control for it, and can change or remove it like any text they styled there.
+>
+> **A name the editor doesn't know is preserved exactly, but not editable** — a style you defined yourself in `inline:`, two names on one span, or a `class`/`id` set. Nothing is lost and nothing is approximated: it survives every edit and save untouched, the editor simply offers no control for it. That is a permanent property rather than a gap, because the name set is open by design — you can add styles the editor has no way to know about.
+
+### Fenced code: data blocks vs snippets
+
+Fenced code serves three purposes depending on its info string: `yaml:`/`json:` for data, `md:` for a named kind of prose (see *Concept blocks*), and a bare language for a code sample.
+
+**Tagged data blocks** — structured data parsed into JS objects. The tag is the key in `content.data` — for a section whose component declares that key in `meta.js` `data:`; the format (`yaml`/`yml`/`json`) is a serialization format, not a display language.
+
+````markdown
+```yaml:form
+fields:
+  - name: email
+    type: email
+submitLabel: Send
+```
+````
+
+→ `content.data?.form` = `{ fields: [...], submitLabel: "Send" }`, when the component declares `data: { form: … }`. A block under a key the component does not declare stays out of `content.data` (the dev console says so) and is still in `content.sequence`.
+
+**Code snippets** — display content with a language for syntax highlighting, collected in `content.snippets` as `[{ language, code }]`. Filter with `content.snippets.filter(s => s.language === 'css')`.
+
+Both appear in `content.sequence`. `<Prose>` handles the difference automatically — it renders snippets with highlighting and skips tagged data blocks, which components access separately via `content.data`.
+
+### Math (LaTeX)
+
+Authors write LaTeX directly; it compiles to MathML Core **at build time** — no runtime math library, no extra CSS. Three forms, matching Pandoc / GitHub / VS Code / Jupyter / Obsidian convention:
+
+| Form | Mode |
+|---|---|
+| `$x^2$` | Inline |
+| `$$x^2$$` | Display (block on its own line, inline display mid-paragraph) |
+| ` ```math ` fence | Display (multi-line friendly) |
+| `\$` | Literal `$` |
+
+**Disambiguation gotcha:** a `$…$` span counts as math only when the body has no whitespace next to the delimiters *and* the closing `$` isn't immediately followed by a digit. So `It costs $5 and $10 total` and `Budget: $200` stay prose without escaping, while `Let $f(x) = 5$ be a function` is math. Use `\$` when the rules would otherwise trip.
+
+Math rides the normal content pipeline — it appears in prerendered HTML, survives `compile('epub')` and `compile('pagedjs')`, and roundtrips through the editor. Component code needs nothing special.
+
+### Lists as navigation menus
+
+Markdown lists model nav, menus, and grouped links. Each list item is a full content object with `paragraphs`, `links`, `icons`, and nested `lists`.
+
+```markdown
+- ![](lu-home) [Home](/)          ← content.lists[0], each item.links[0] + item.icons[0]
+- ![](lu-book) [Docs](/docs)
+
+- Product                          ← nested: group.paragraphs[0] is the label,
+  - [Features](/features)          ←   group.lists[0] holds sub-items
+  - [Pricing](/pricing)
+```
+
+**For richer navigation** with icons, descriptions, or hierarchy, use a `yaml:nav` tagged block:
+
+````markdown
+```yaml:nav
+- label: Dashboard
+  href: /
+  icon: lu:layout-grid       # same icon spellings as anywhere else —
+- label: Docs                # lu:name, lucide:name, lu-name, or an SVG path
+  href: /docs
+  icon: /icons/book.svg
+  children:
+    - label: Getting Started
+      href: /docs/quickstart
+```
+````
+
+Access: `content.data?.nav`, with `data: { nav: {} }` in the component's `meta.js` — an array of `{ label, href, icon, text, children, target }`. Components can support both modes: use `content.data?.nav` when provided, fall back to `website.getPageHierarchy()`. Full pattern: `reference/navigation-patterns.md`.
+
+### Section backgrounds
+
+Set `background` in frontmatter — the runtime renders it:
+
+```yaml
+background: /images/hero.jpg                             # Image
+background: /videos/hero.mp4                             # Video
+background: linear-gradient(135deg, #667eea, #764ba2)    # Gradient
+background: '#1a1a2e'                                    # Color (hex — quote in YAML)
+background: primary-900                                  # Palette token (bare name or var())
+
+background:                                              # Object form for more control
+  image: { src: /img.jpg, position: center top }
+  overlay: { enabled: true, type: dark, opacity: 0.5 }
+```
+
+Components that render their own background declare `background: 'self'` in `meta.js`, and the runtime then draws none; to draw the author's background themselves they render kit's `<SectionBackground block={block} />`.
+
+### Page organization
+
+```
+site/layout/          # header.md, footer.md, left.md — rendered on every page
+site/pages/home/
+    ├── page.yml      # title, description, order
+    ├── 1-hero.md     # Numeric prefix sets order
+    ├── 2-features.md
+    └── 3-cta.md
+```
+
+Decimals insert between: `2.5-testimonials.md` goes between `2-` and `3-`. **Ignored:** `README.md`, and `_*.md` / `_*/` (drafts and private files).
+
+```yaml
+# page.yml
+title: About Us
+id: about                   # Stable identity (for page: links, survives moves)
+order: 2                    # Navigation sort position
+sections: [hero, team, ...] # Section order within this page (same ... rule)
+pages: [team, history, ...] # Child page order, when this page has child folders
+redirect: academic          # Redirect to a child page (relative/absolute path, or URL)
+slug: { fr: a-propos }      # Localized URL segment per language
+
+# folder.yml  — a folder OF PAGES, where page.yml means a page built from sections
+title: Getting Started
+pages: [quickstart, app-tour, ...]  # Child page order (... = rest)
+
+# site.yml
+index: home                 # Just set the homepage
+pages: [home, about, ...]   # Order pages (... = rest, first = homepage)
+foundation: '@acme/ui@1.2.0'  # The component system (see Part 2, step 1)
+extensions: ['@acme/fx@0.3.1'] # Secondary foundations — same shapes as foundation:
+```
+
+**The trailing `...` is not decoration — dropping it changes behaviour.** `pages:`
+in `folder.yml` and `site.yml`, and `sections:` in `page.yml`, all read it the same way:
+
+| written | means |
+|---|---|
+| `[a, b, ...]` | **inclusive** — `a` and `b` pinned in that order, **everything else follows** |
+| `['...']` | identical to omitting the key |
+| `[a, b]` — no `...` | **strict** — and every unlisted sibling is dropped from **every** menu |
+
+⚠️ **Strict is a navigation filter, not a delete, which is what makes it easy to
+miss.** Unlisted pages stay routed, stay in `dist/`, stay in `llms.txt` and still
+resolve by URL — only the links to them disappear. Your route count does not
+change and nothing warns. **If you list pages in order and mean "these first",
+end the list with `...`.**
+
+**Configuration cascades: `page.yml` → `folder.yml` → `site.yml` → foundation defaults.** Each level inherits from the one above and overrides specific values, the way CSS specificity works. This is what makes bulk assignment natural — put `layout: marketing` in a `folder.yml` and every page in that folder inherits it, while one page can still override with its own `page.yml`. Reach for `folder.yml` before editing the same key into a dozen `page.yml` files.
+
+**Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/` — declared in `site.yml`, or in the pages directory's own `folder.yml` / `page.yml` (how a content repo carries its order), with `site.yml` winning.
+
+**Content-less containers:** folders with `page.yml` but no markdown are structural groups (`hasContent: false`). Visiting one auto-redirects to the first descendant with content — this is what supports courses → modules → lessons at any depth.
+
+**A local folder for a mounted route should use `folder.yml`, not `page.yml`.** The filename is how you say what the folder holds — `page.yml` for a page built from sections, `folder.yml` for a folder of pages — and for a mount that answer also decides how the mounted tree is read. A `page.yml` stub over a mounted folder of pages says "sections", and top-level markdown in the mounted repo collapses into one page instead of becoming pages of its own. Keep `layout:`, `title:` and SEO in that stub; the mounted repo's own `folder.yml` supplies its ordering and title where the stub is silent.
+
+**SEO & social cards:** set site-wide defaults in `site.yml`; any page overrides per-field in `page.yml` (page wins, site fills gaps). These render into every page's static `<head>` — Open Graph, Twitter Card, canonical, robots — so shares and crawlers see them without running JS. The social `image` is the field most worth setting once at site level.
+
+```yaml
+# site.yml
+keywords: [components, react, cms]
+seo:
+  image: /og-default.png
+  noindex: false                    # true keeps the WHOLE site out of search
+
+# page.yml
+seo:
+  image: /og-about.png
+  canonical: https://acme.com/about
+```
+
+**Localized URLs:** on a multilingual site (`languages:` in site.yml), `slug: { <lang>: <segment> }` gives a page a native URL segment per language; the folder name stays the canonical route. Nested folders compose automatically, and localized URLs flow through navigation, the language switcher, and the sitemap. See Part 5 for the translation workflow.
+
+**Knowledge pages — content for an AI agent, not for a visitor.** `knowledge: true` in a `page.yml` or `folder.yml` marks a page as agent-only: it is **never rendered** — no route, no HTML — and it cascades to the whole subtree by route prefix, so one marker on `pages/kb/` covers everything under it and `/kb` never claims `/kbase`. Write plain markdown; a section `type:` there never selects a component, because nothing renders these pages.
+
+⚠️ **A knowledge page is not published to anyone — it powers a service your site offers.** Everything your site *does* publish is published on equal terms: an AI visiting your site sees exactly what a person sees. `llms.txt` and the per-page `.md` files are a convenience for that reader, not a privileged tier — no visitor, human or machine, gets more than another.
+
+A knowledge page is different in kind, not in audience. It is never a page anyone reads; it is source material for an assistant the site offers **to its visitors** — they ask, they get an answer, and the material behind it stays unpublished. That is why it is kept out of `llms.txt`, the `.md` projections and the search index: not because some readers are trusted less, but because a knowledge page was never a page.
+
+⇒ If what you want is "make this readable by any AI that visits", write an ordinary page. It is already published to them, on the same terms as to everyone else.
+
+⛔ **`knowledge:` is not a security control — don't put secrets there.** "Not published" is about who the prose is *written for*, not about confidentiality. The assistant's job is to answer visitors using this material and it can quote it back to whoever asks, so a visitor who prompts it can surface what a knowledge page says — **by design, not by leak.** The test for what belongs here is "is this written for the assistant to reason with?", not "do I want to keep this from people?" Anything that genuinely must not reach a visitor doesn't belong in your site's content at all.
+
+```yaml
+# pages/kb/page.yml
+title: Product Knowledge
+knowledge: true
+```
+
+What can actually *read* it depends on where you deploy, because reading it needs a server:
+
+- **`uniweb deploy`** (backend-hosted) — the content travels with the site, so an assistant running over it can grep and read your knowledge material alongside the public content when answering a visitor's question.
+- **`uniweb export` / `uniweb deploy --host <adapter>`** (static host) — **the build drops these pages and says so**: `Dropped 2 knowledge page(s) from this build: /kb, /kb/pricing`. Files are served as files here; there is no assistant, so nothing would read them. The warning means the flag was honoured.
+
+The artifacts **your build emits** to describe the public site never name them — `llms.txt`, the per-page `.md` projections, and the search index all describe pages a visitor reads, and a knowledge page's prose was written for the assistant instead. Two settings **outrank** `knowledge:`, so a contradiction resolves toward the narrower reach: `agents.exclude` in `site.yml`, and any `_`-prefixed route segment. *(A host that derives these artifacts itself, rather than serving the ones your build produced, applies its own rules — ask your host what it does with `knowledge:` before relying on it there.)*
+
+Don't confuse it with the visibility flags: `hidden: true` is a **draft** (not published at all), `hideIn` only controls **nav placement** (still reachable by URL), and `knowledge: true` is a **different audience** (never rendered for anyone). ⛔ `hidden: true` on `pages/404/` means a **draft 404** — it is not published and the site falls back to the generic `404.html`; an authored 404 needs no flag, since it is never listed in navigation anyway. A **section** takes `hidden: true` in its frontmatter with the same meaning: previewed in `uniweb dev`, left out of a published build with its child sections, and never passed to the component as a param. (`_name.md` is the other way to keep a section out: no build reads it, dev included.)
+
+**A site can be nothing but knowledge — that is a real and useful shape.** A site is a set of routes; it does not have to have HTML pages. Mark the root `knowledge: true` and every page inherits it, so the site renders nothing at all and exists to *be* an agent: a `/_agent/chat` URL that a web app, a mobile app, or someone else's backend sends requests to.
+
+```
+site/pages/
+├── page.yml          # knowledge: true — cascades to everything
+├── house-style.md
+├── pricing.md
+└── support.md
+```
+
+Measured on exactly that shape: **the agent corpus holds every page; the public projections hold nothing** — `llms.txt` lists no pages, the search index has 0 entries, and no `.md` files are emitted. Nothing leaks, by construction rather than by configuration, because there is no public surface to leak onto.
+
+⛔ **This shape needs a host that actually runs an agent, and deploying is not the same as having one.** Two ways to end up with nothing:
+
+- **A static host** (`uniweb export`, `deploy --host`) drops every page — they have no reader there — and you get an empty SPA shell. The build still says *"complete"*, because 0 pages is not an error: it reports `Collected 0 pages` and pre-renders none.
+- **A backend-hosted deployment that does not offer the service.** Whether an agent endpoint exists is the host's to decide, per site — it is not implied by deploying successfully.
+
+⇒ **The way to know is to ask, at render:** `isAssistantEnabled()` from `@uniweb/kit` is true only where an agent endpoint is declared. On a site that is *only* knowledge there is no component to ask — so confirm with your host that the agent is enabled for that site before you build an integration against it. If you meant to build an agent endpoint and got silence, this is where to look.
+
+### Your site is readable by agents, automatically
+
+Every build emits two things an AI agent can use directly, alongside the HTML. **Free, on by default, nothing to install.**
+
+| Artifact | What it is |
+|---|---|
+| `/llms.txt` | An annotated index of the site — every page, with a one-line description, linking to the `.md` below |
+| `/{route}.md` | Each page as clean markdown: the content, no navigation, no chrome |
+
+The point is the pair. An agent fetches the index, *reads* what each page is about, and goes straight to the one it needs — two requests, no HTML stripping, no guessing at URLs. Descriptions come from `page.yml`'s `description:`, then `seo.ogDescription`, then the page's opening paragraph, so a site usually gets a complete index without writing any of them.
+
+**Large sites also get per-branch indexes.** A branch with at least 5 pages gets its own — `/docs/llms.txt` lists just the docs, titled by that folder. The site index still lists everything; a branch index is an extra entry point, not a replacement, so an agent that starts at `/llms.txt` still reaches any page in two hops.
+
+```yaml
+# site.yml — all optional; these are the defaults
+agents:
+  index: true            # /llms.txt
+  markdown: true         # /{route}.md
+  branchIndexes: true    # /docs/llms.txt for branches big enough to want one
+  branchMinPages: 5      # how big is big enough
+  exclude: [/internal]   # keep a branch out of both (cascades)
+
+agents: false            # or turn the whole thing off in one word
+```
+
+#### Expecting agent traffic from somewhere specific
+
+If your site runs an agent (see *Knowledge pages* above), you can declare where its requests are expected to come from. Useful when the site exists to serve someone else's app rather than its own visitors — a chat endpoint your web app calls.
+
+```yaml
+# site.yml
+agents:
+  expectedOrigins:
+    - https://app.example.com
+    - https://partner.example.org
+```
+
+**It is a declaration, not a gate — the name is the contract.** You are telling the host where you expect callers from; a host that offers an agent may then decline requests whose browser-sent `Origin` is not one of them, before it spends anything answering. Behaviour where it is honoured:
+
+| | |
+|---|---|
+| not declared | no check at all — nothing happens unless you ask for it |
+| your own site's origin | always fine, without listing it — declaring a partner must not take down your own chat box |
+| a request with **no** `Origin` | **allowed** — see below, this is deliberate |
+| matching | exact, per entry; no wildcards |
+
+⛔ **It is not a spend limit, and it cannot be.** `Origin` is set by the browser and enforced by the browser: anything that is not a browser sends whatever it likes, or nothing at all. So this stops **casual misuse and third-party embedding** — someone dropping your endpoint into their own page — and it does **not** stop anyone determined to run up your bill. Do not size your budget on it.
+
+⭐ **And that is why a request with no `Origin` is allowed rather than refused.** There are two shapes of caller and this check only sees one:
+
+- your app's **JavaScript**, in a browser — sends `Origin`, covered here;
+- your app's **server**, calling from its own backend — never sends one, and refusing it would break the integration this feature partly exists for.
+
+Server-to-server callers are authenticated by other means, arranged with your host — not by anything in `site.yml`. **Never put a shared secret in `site.yml`:** everything in it is delivered to every visitor as part of the site payload.
+
+⚠️ Spelling matters and nothing downstream will catch it — the block is forwarded to your host as opaque data, so a typo is carried and simply never acted on. `uniweb doctor` flags unknown keys in `agents:` for exactly this reason; run it before you rely on one.
+
+**Set `seo.baseUrl` if you want absolute links** in the index — without it the links are root-relative, which still works for an agent that arrived via the index. `uniweb doctor` warns when it's unset.
+
+**What's excluded, and it's deliberate:** `seo.noindex` pages, `hidden` pages, `_`-prefixed drafts, and a parametric page's URL pattern (`/blog/:slug`). An index *describes* pages rather than merely listing them, so an unlinked page would become both discoverable and summarized — which is why these exclusions are load-bearing rather than tidy-up. `noindex` or `hidden` on a **folder** takes the whole branch with it.
+
+**Declaring how your content may be used** is a separate axis from whether it may be fetched, and it goes in `seo.robots`:
+
+```yaml
+# site.yml
+seo:
+  robots:
+    contentSignals:
+      search: true       # may appear in search results
+      ai-input: true     # may be retrieved at inference time
+      ai-train: false    # may not be used to train a model
+```
+
+That emits a `Content-Signal:` line in `robots.txt`. Declare only what you mean — an omitted signal says nothing, which is not the same as saying no.
+
+### Records, queries and parametric pages
+
+Most content lives in `pages/` — a fixed composition of sections on a fixed set of pages. **The other kind is a set of records: repeating content managed as one file per item**, that pages pull from. Blog posts, team members, products, case studies, bibliographies.
+
+It is a small database, not a page tree. Three things, deliberately separate:
+
+```
+site/
+├── pages/
+├── records/           # your site's records — every file in a schema folder is one
+│   ├── article/       # the folder names their data schema
+│   │   ├── getting-started.md
+│   │   └── design-tips.md
+│   ├── person/
+│   │   └── alice.yml
+│   └── folder.yml     # optional: sorts records into folders
+├── queries.yml        # how content is REACHED
+└── site.yml
+```
+
+**`records/{schema}/` — the site's records.** Putting a file here is what makes it a record; nothing else lists it. The folder names the data schema and nothing else:
+
+| on disk | schema |
+|---|---|
+| `records/article/…` | `@/article` — your foundation's own |
+| `records/std/person/…` | `@std/person` — the shared standard set |
+| `records/acme/project/…` | `@acme/project` — an org's |
+
+Keep those folders flat: `records/article/design-tips.md` works; `records/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records/folder.yml` instead. A file whose name starts with `_` is not a record — somewhere to keep work in progress.
+
+**Links are records too — `@uniweb/link`.** A file in `records/uniweb/link/` holding `url:` and nothing else is a link record (one per file; no body, no other fields). Its display text and tags go on its `records/folder.yml` entry (`- path: uniweb/link/launch-video.yml` with `label:` / `tags:`), like any record's. Select links with a query `schema: '@uniweb/link'` and declare them in `meta.js` as `data: { videos: '@uniweb/link' }`; each arrives as `{ url, $name, $label, $tags }`. A link's `url` is absolute (`https://…`), and `uniweb push` refuses a relative one and a `draft: true` link.
+
+**Files are records too — `@uniweb/file`.** The file itself is the record: any file dropped into `records/uniweb/file/` (a PDF, a spreadsheet, any type) is a record named by its file name without the extension; nothing in it is read. Its label and tags go on its `records/folder.yml` entry (`- path: uniweb/file/brochure.pdf`). Query with `schema: '@uniweb/file'`, declare with `data: { downloads: '@uniweb/file' }`; each arrives as `{ file: { url, name, mime, size }, $name, $label, $tags }` — link to `file.url`. `uniweb push` uploads the file with the site's media; a pull fetches it back. Two files of one name with different extensions clash — rename one. On a site that goes to a backend, a component must declare the type (`@uniweb/link` or `@uniweb/file`) for a query over it to be accepted.
+
+**Four formats, one shape.** All of these produce the same records at runtime:
+
+| Format | Best for | Notes |
+|---|---|---|
+| `.md` | Items with prose — articles, case studies | Frontmatter holds fields, body holds text; auto-excerpt and first-image extraction |
+| `.yml` / `.yaml` | Structured records with no prose body — team, products | Cleaner than a markdown file with an empty body |
+| `.json` | Same as YAML | When the data comes out of another tool |
+| `.bib` | Bibliographies | Each `@entry{key, …}` is a record, its cite key its name (`$name`); normalized to CSL-JSON, LaTeX accents converted to Unicode |
+
+**One record per file.** A file's name is its record's name (`records/team/alice.yml` is `alice`); a `slug:` key at its top, or a file holding a list, stops the build — to rename a record, rename its file. A `.bib` file holds many entries, each named by its cite key. **A component reads a record's name as `$name`** — the one name it carries on every site; the delivered record has no `slug`. You can mix both in one folder — an exported `refs.bib` beside a hand-written `extras.yml`.
+
+Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. **`draft: true` keeps a record off the live site without deleting it**: it is still a record, in `records/`, and `pnpm dev` shows it so you can preview it, but a build for hosting leaves it out, and a backend you `uniweb push` it to keeps it in the site's folder without delivering it. (`published: false`, an older spelling, is refused.)
+
+**A record's file follows its data schema's sections.** A schema with one section (the `fields:` form) is written flat, as above. A schema with more than one is written **by section** — each field under its section's name — and a field left at the top stops the build and a push, naming where it goes. `@std/article` has two, its card `brief` and `body`:
+
+```markdown
+<!-- records/std/article/hello.md -->
+---
+brief:
+  title: Hello
+  author: Ada
+  date: 2026-05-01
+---
+
+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: { 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.
+
+**`records/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
+
+```yaml
+- folder: archive
+  label: The Archive
+  records:
+    - article/2025-*.md
+```
+
+A path under a folder is relative to `records/`, naming one file or matching many. A record's entry can instead be `{ path, tags, label }` — what the folder says about the record: a component receives them beside it as `$tags` (in the order written) and `$label`, and a query reads them like any key (`where: { $tags: featured }`); such an entry may sit at the top level, where a bare path is refused. A `label` — a record entry's or a folder's — is one text in the site's language, or one per language (`label: { en: Launch video, fr: Vidéo de lancement }`); `$label` is the page's language, else its base language, else the site's. A folder takes `tags:` too. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `folder.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
+
+⚠️ **With a backend, `records/` is what `uniweb push` sends** — every record in it. A site with no `records/` at all leaves the backend's records alone; an *empty* `records/` removes them, and the CLI asks before it does. Records pushed to a backend are served once the site is published.
+
+**`queries.yml` — how content is reached.** A bare map of name → query. A query names a schema and the site's records of that schema are its rows:
+
+```yaml
+recent:
+  schema: '@/article'
+  sort: date desc                        # `date desc`, `title asc`, …
+  limit: 10
+
+team:
+  schema: '@std/person'
+  where: { active: true }                # a predicate — see authoring/predicates.md
+```
+
+You can keep the same declarations under `queries:` in `site.yml` instead, if you would rather have one file.
+
+**Show a query on a page** with `query:` in `page.yml` or a section's frontmatter (the whole result), or `fetch:` for anything more — a `limit`, a `where`. A list — `query: [team, articles]` — declares several, each filling its own key in the sections whose components declare it. `query:` takes names only; `data:`, its old name, is now an error.
+
+**Who receives it:** a section's own declaration reaches that section; a page's, every section on the page; a parent page's, the sections of the pages directly under it. **The site is the root page:** `query:` in `site.yml` reaches the layout areas (header, footer, …) and the sections of top-level pages — the homepage included — and no page further down. A section on `/docs/setup` that needs site-wide data names the query itself.
+
+**A fetch always names a query.** A string in `fetch:` is a query name: `fetch: team` is `fetch: { query: team }`, and `fetch: [team, articles]` is a list of those. A fetch never names a file — `/data/<query>.json` is what the build generates from a query for a site with no backend, and writing that path in a `fetch:` stops the build. That is what keeps a site portable: name the query, debug locally against the generated data, publish, and the same page reads live records from the host with nothing changed.
+
+**A query selects a set of records; a `fetch:` takes from that set, never adding to it.** The query's `scope`, `where`, `sort` and `limit` decide which records it selects — its `limit` included: `recent` above is the 10 newest articles. A fetch's `where` keeps the ones that also match, its `sort` re-orders them, and its `limit` takes the first N — never more than the query selects. That is the whole list — `scope` belongs to the query, and the build stops on a `fetch:` that carries one; for another folder branch, declare another query. **Which records get a page is the query's to decide, never a fetch's:** each record `recent` selects gets its page, an 11th-newest article gets none, and a list's `limit: 3` still leaves all 10 their pages — so a condition or count that should decide which pages exist belongs on the query. Two fetches under one key at one level: the first is used, and the build warns.
+
+```yaml
+# pages/blog/page.yml          |   # a section on the homepage
+title: Blog                    |   ---
+query: recent                  |   type: ArticleTeaser
+                               |   fetch: { query: recent, limit: 3 }
+                               |   ---
+```
+
+**Give each record its own page with a `[slug]/` folder** — a *parametric page*, what other frameworks call a dynamic route — inside the page that names the query:
+
+```
+pages/blog/
+├── page.yml          # title: Blog / query: recent
+├── list.md
+└── [slug]/
+    ├── page.yml
+    └── article.md    # just `type: Article` — the record arrives automatically
+```
+
+`records/article/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
+
+**Link a card with `item.$route` — never compose the URL.** Every record a query delivers carries `$route`, the URL of the parametric page whose route query is that query (`/blog/design-tips`), wherever the list appears — the query's own page, the homepage, a sidebar. No page for the query, or no value for the field its URL is built from, means no `$route`, never a broken one. `detailPage: page:<id>` on a fetch links the records to another page instead. `$` marks a field the framework fills, so a record's own `route` field is left alone. ⛔ `route:` on a query is retired and stops the build.
+
+**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 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 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 `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:
+
+```yaml
+# queries.yml
+members:
+  schema: '@std/person'
+  queryable:
+    department: { type: enum, label: Department, options: [biology, physics, chemistry] }
+    tenured:    { type: boolean, label: Tenured }
+    start_year: { type: range, label: Start year, min: 1800, max: 2025 }
+```
+
+The site declares the *surface*; the foundation reads the metadata, renders matching controls (dropdown, toggle, slider), and composes the predicate when the reader picks values.
+
+Full author guide: `authoring/collections.md`. Every key a query takes: `reference/queries.md`. Predicate operators: `authoring/predicates.md`.
+
+---
+
+## Part 4 — The foundation lane
+
+You're not building pages — you're building a **system** of section types that authors compose into pages. Name by purpose, not content: `Testimonial` not `WhatClientsSay`, `SplitContent` not `AboutSection`. Expect consolidation: a React site with 30+ components typically maps to 8–15 Uniweb section types.
+
+### Where things go
+
+```
+src/                     # the foundation package (folder name is `src`)
+├── sections/            # Section types (auto-discovered)
+│   ├── Hero.jsx         # Bare file — no folder needed
+│   ├── Features/        # Folder when you need meta.js
+│   │   ├── index.jsx
+│   │   └── meta.js
+│   └── insets/          # Organizational subdirectory (lowercase)
+├── layouts/             # Custom layouts (optional, auto-discovered)
+├── components/          # Your React components — any props you like, no meta.js
+├── utils/               # Helper functions, non-React logic
+├── main.js
+├── styles.css
+└── package.json         # name: "src"
+```
+
+**Discovery:** PascalCase files and folders at the root of `sections/` are auto-discovered. Nested levels require a `meta.js`. Lowercase directories are organizational only. `hidden: true` excludes a component entirely. Everything outside `sections/` and `layouts/` is ordinary React.
+
+**JSX goes in `.jsx` files** (or `.tsx`). Discovery also accepts a `.js` component, but only one without JSX: JSX compiles in no `.js` file, and the build stops on one, naming the file to rename.
+
+**Source root.** The foundation package's source lives at the package root — the `src/` folder *is* the foundation. The build reads `package.json::main` (for new scaffolds, `main: "./_entry.generated.js"`). Older foundations nest source in `foundation/src/` with `main` pointing at `./src/_entry.generated.js`; both work through the same code path.
+
+**Import aliases.** Foundations include subpath imports for shared internals — use them instead of brittle relative paths:
+
+| Alias | Maps to | Use for |
+|-------|---------|---------|
+| `#components/*` | `./components/*` | Shared React components |
+| `#utils/*` | `./utils/*` | Helper functions, non-React logic |
+
+```jsx
+import LessonHeader from '#components/LessonHeader'      // ✅
+import LessonHeader from '../../components/LessonHeader' // ❌ breaks if you reorganize sections/
+```
+
+Within the same directory, use normal relative imports (`./AIFeedbackCard`).
+
+**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the foundation's identity — `name` (what it registers as, `@org/<name>`) and `description` — and the capabilities it provides — `defaultLayout`, `defaultSection`, `viewTransitions`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. The capabilities are read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build carries into `default.capabilities` in `dist/entry.js` only what a published page reads of your default export — the code it calls (`handlers`, `defaultInsets`, `xref`, `transports`, `outputs`) and its data, lean (`defaultLayout`, `defaultSection`, `viewTransitions`, `scroll`, each var's `default`, `type` and `applyTo`, each `data:` key's schema ref). `name`, `description`, a var's label or description and any key the framework does not read stay out of the published bundle: they are for the editor, which reads them from the foundation's schema. You never write that wrapper. The file is `main.js` — never `main.jsx`, which the build refuses — and it is plain JavaScript: a component it declares (in `defaultInsets`, `xref`) lives in a `.jsx` file it imports. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+
+### Props interface
+
+```jsx
+function MyComponent({ content, params, block }) {
+  const { title, paragraphs, links, items } = content   // Guaranteed shape
+  const { columns, variant } = params                   // Defaults from meta.js
+  const { website } = useWebsite()                      // Or block.website
+}
+```
+
+**Frontmatter becomes `params` — except the names framework keeps for itself.** Every section can be given these, whatever its type, and none of them reaches your component as a param. So **never declare one in `meta.js` `params:`** — a component that does never receives what an author writes.
+
+| in a section's frontmatter | what it is | a component reads it from |
+|---|---|---|
+| `type`, `id`, `hidden` | the section itself — its section type, its id, and a draft (`hidden: true`: left out of a published build, kept by `uniweb dev`) | — |
+| `query`, `fetch` | the section's data | `content.data`, under the keys its `meta.js` `data:` declares |
+| `theme`, `background`, `grid`, `vars` | the section's settings, which framework applies — the color context and the background around your component, the section's theme and your component's CSS variables in the page stylesheet, the child layout | `block`, when the component needs one for its own logic: `useColorContext(block)` for the context (a light vs. dark logo, say), `<SectionBackground block={block} />` to draw the background itself, `<ChildGrid from={block} />` for the grid |
+| `props` | params written as one map | `params` — its keys are merged in, one by one |
+| `data`, `preset`, `input` | nothing: `data:` is refused (it was `query:`'s old name); `preset:` and `input:` are ignored with a warning | — |
+
+The build warns when `params:` declares any of them. A preset may still set `theme` or `background` — a preset's params are written into the section's frontmatter when an author starts a section from it, so `dark: { label: 'Dark', params: { theme: 'dark' } }` is a dark section. Every other key is a param, declared or not; components ignore the ones they don't use.
+
+### Rendering content with Kit
+
+Content fields are **HTML strings** — they contain `<strong>`, `<em>`, `<a>` from markdown. **Never render them with raw `{content.title}` in JSX** — that shows HTML tags as visible text. Use Kit components:
+
+```jsx
+import { H1, H2, H3, P, Span } from '@uniweb/kit'
+
+<H1 text={content.title} className="text-heading text-5xl font-bold" />
+<H2 text={content.subtitle} className="text-heading text-2xl" />
+<P text={content.paragraphs} className="text-body" />
+<Span text={listItem.paragraphs[0]} className="text-subtle" />
+```
+
+Kit provides `H1`–`H6`. These render their own HTML tag — **don't wrap them**: `<H2 text={…} />`, not `<h2><H2 text={…} /></h2>`.
+
+**Full content rendering** (article/docs sections where the author controls the flow):
+
+```jsx
+import { Section, Prose } from '@uniweb/kit'
+
+<Section block={block} width="lg" padding="md" />
+<Prose content={content} block={block} />
+```
+
+`Prose` renders from the parsed sequence — headings, paragraphs, images, snippets, lists — with prose typography. Tagged data blocks are **skipped**; access them via `content.data` for custom rendering. Pass `content` (needs `.sequence`), and `block` too if the content uses insets. Also works as a pure typography wrapper: `<Prose>{children}</Prose>`.
+
+`Article` is an older alternative rendering from `block.rawContent` (raw ProseMirror), including data blocks. Prefer `Prose` for new components.
+
+### The Kit, by use case
+
+Names only — for signatures and props, read the package: it's on disk at `node_modules/@uniweb/kit`, and `reference/kit-reference.md` has the full API.
+
+**Text:** `H1`–`H6`, `P`, `Span`, `Div`, `Text` (with `as`)
+**Content:** `Section`, `Prose`, `Article`, `Render` (ProseMirror → React), `ChildBlocks`, `splitContent()`
+**Media:** `Visual` (a `content.media` item by its kind; or the first of inset/video/image), `Image`, `Media` (video), `Icon`, `Asset`
+**Navigation:** `Link`, `useActiveRoute()`, `useWebsite()`, `useRouting()`
+**Header/layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()`
+**Overlays:** `Overlay` (modals, palettes, drawers, toasts — portals out of the layout, contains focus; read the note below before hand-rolling one)
+**Keyboard:** `useShortcut('mod+k', fn)`, `useShortcuts({…})`, `useShortcutLabel('mod+k')` — `mod` is Cmd on Apple platforms and Ctrl elsewhere, and the label renders per-platform so a hint never shows the wrong key
+**Long-form prose:** `<Prose>` and the container you put `<Render>` output in both use Tailwind Typography's `prose` classes. One line in the foundation's `styles.css` supplies them and points them at the site's theme:
+
+```css
+@import "@uniweb/kit/prose-tokens.css";   /* the plugin, wired to theme.yml */
+```
+
+Nothing to install — the import brings the plugin with it. **Skip the import and prose is completely unstyled** — lists lose their bullets and numbers, and text its typography — while the markup looks right. The foundation build warns about it, and `uniweb doctor` flags it. Use **one** `prose` container per subtree — the `--tw-prose-*` variables are inherited, so a nested one silently resets them and the outer container goes on looking correct. The section that renders the document is usually the better owner; a layout should supply column width and padding.
+
+**Documentation shells:** `useHeadings()` (the page's headings + the one being read, derived from content so it prerenders), `website.getBranchHierarchy({ route, for })` (the page tree for one branch). Kit ships no ready-made layout — a layout is your foundation's design; write it in `src/layouts/` and use these for the behaviour.
+**Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`
+**Theming data:** `useThemeData()`, `useColorContext(block)`
+**Data fetching:** `useFetched`, `useCacheEntry`, `useWholeRecord`
+**Forms:** `useFormValues` (an author-designed form's state), `valueAt(values, path)`, `useFormSubmit`, `submitForm`, `resolveSubmitTarget` — see *Forms* below
+**Utilities:** `cn()`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`, `getLocaleLabel(locale)`
+**Other styled:** `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
+
+Four things you won't discover by reading exports:
+
+> **Content fields are HTML strings.** Covered above — it's the single most common rendering bug.
+
+> **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page ID (survives moves), external URLs get `target="_blank"` automatically, and `reload` forces a full page load.
+
+> **`cn()` gotcha — a later `text-<size>` silently drops an earlier `leading-*`.** Tailwind's size classes set line height too, so `cn()` treats the size as replacing the leading: `cn('leading-[1.1] text-4xl')` → `text-4xl`. Put the size first, or fold the leading into it (`text-[clamp(2rem,5vw,4rem)]/[1.1]`). Most likely to bite when the size comes from a lookup and the leading sits in a shared base string.
+
+> **Kit hooks are SSR-safe by design.** If you hit "document is not defined" during a build, don't add `typeof document` guards — reach for the hook instead (`useAppearance()` for scheme, `useScrolled()` for scroll position).
+
+> **A modal needs `<Overlay>`, not a bigger z-index.** The runtime gives each layout area its own `view-transition-name` so header, rails and body animate independently. That makes each area a stacking context *and* a containing block for `fixed` children — so a dialog rendered from inside your Header is sealed into the header's context and paints *under* the page body no matter what z-index it carries. Raising the number looks like it should work and never does. `<Overlay onClose={close}>…</Overlay>` renders into `document.body`, where the z-index means what you expect.
+>
+> It also does the part that is easy to skip: a modal overlay **contains focus** — moves focus in, cycles Tab within, marks the rest of the page `inert`, and returns focus to whatever opened it. That is what makes the `role="dialog" aria-modal="true"` on your box true rather than merely asserted; without it a keyboard user Tabs straight out into a page a screen-reader user has been told is unreachable. Plus Escape, the scrim click, the scroll lock, and a dimmed scrim you override with `className` (`bg-transparent` removes it). `modal={false}` for a toast: it escapes the stacking context and nothing else, so the page stays usable. Your dialog's markup stays yours.
+
+### Icon component
+
+```jsx
+{content.icons.map((icon, i) => <Icon key={i} {...icon} />)}   // From content
+<Icon name="search" />                                          // Lucide (default)
+<Icon name="hi2-arrow-right" />                                 // Other library by prefix
+<Icon name="close" />                                           // Built-in (no network)
+```
+
+Built-ins (instant, no network): `check`, `close`, `menu`, `chevronDown`, `chevronRight`, `externalLink`, `download`, `play`, and a few others. Other props: `svg`, `url`, `size` (default `'24'`), `className`.
+
+### Section wrapper
+
+The runtime wraps every section in `<section>` with its context class and background. Customize with static properties:
+
+```jsx
+function Hero({ content, params }) {
+  return <div className="max-w-7xl mx-auto px-6">…</div>
+}
+
+Hero.className = 'pt-32 md:pt-48'   // adds classes to the runtime wrapper
+Hero.as = 'div'                      // changes the wrapper element
+export default Hero
+```
+
+**Layout components typically need `p-0`** to suppress default padding:
+
+```jsx
+Header.className = 'p-0'
+Header.as = 'header'
+```
+
+### meta.js
+
+```javascript
+export default {
+  title: 'Feature Grid',
+  description: 'Grid of feature cards with icons',
+  family: 'features',       // the standard section type it is — the editor's
+                            // illustration and label (`uniweb families`). Optional;
+                            // a name like `Features` resolves on its own
+  // hidden: true,          // Exclude from export entirely (internal helpers)
+  // background: 'self',    // Component renders its own background
+  // inset: true,           // Available for @ComponentName in markdown
+  // children: true,        // Accepts child sections
+
+  content: {
+    title: 'Section heading',
+    paragraphs: 'Introduction [0-1]',
+    items: {
+      label: 'Feature cards [3-6]',
+      content: { icon: 'Icon [1]', title: 'Feature', paragraphs: 'Description' },  // one entry
+    },
+    // media: 'Photo, video or diagram [1]',  // an image, a video, or an embedded component
+    // sequence: 'Prose and media',           // renders content.sequence — the section as written
+  },
+
+  params: {
+    columns: { type: 'number', default: 3 },
+    variant: { type: 'select', options: ['default', 'centered', 'split'], default: 'default' },
+  },
+
+  presets: {
+    default: { label: 'Standard', params: { columns: 3 } },
+    compact: { label: 'Compact', params: { columns: 4 } },
+  },
+
+  // context / initialState: keys are developer-defined, not framework fields.
+  context: {},        // Static — neighbors read via getNextBlockInfo().context
+  initialState: {},   // Dynamic — neighbors read .state; component updates via useBlockState()
+}
+```
+
+**All defaults belong in `meta.js`, not inline in component code.** `meta.js` is also the catalog entry another agent reads to discover your section type (Part 2, step 2) — write `description` and `content:` for that reader.
+
+**`content:` names what the component reads**, each as a label for the author with an optional count (`'Cards [3-6]'`): `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `lists`, `items`, `media`, `icons`, `documents`, `snippets`, `tables`, `math`, `quotes`, `sequence`.
+
+- **`media` is an image, a video, or an embedded component.** `media: 'Hero media [1]'` takes any of the three; `media: { label, types: ['image'] }` narrows it; `image:`, `videos:` and `insets:` are the same slot narrowed to one type. Read it as `content.media` — the author's order, each item with its `kind` — and render it with `<Visual media={content.media} block={block} />`. Rendering the slot with `<Image>` drops a diagram an author placed there, and kit's `<Media>` is a video player.
+- **`sequence`** says the component renders `content.sequence` — the whole section as written, headline included. `{ label, except: ['table', 'math'] }` names the kinds it leaves out.
+- **`items: { label, content: { … } }`** says what each entry holds, in the same vocabulary.
+- The build warns on what it can't read, and refuses `visuals:` (declare `media`) and the `content:` element `data` (declare the block's tag in `data:`).
+
+> **`meta.js` is a user interface, not just metadata.** When a foundation is published, every `meta.js` is registered as the foundation's schema, and the visual editor builds its controls from it: the build generates a `schema.json` from every `meta.js` in the foundation, and the editor renders it: a `select` param with `options` becomes a dropdown, a `boolean` becomes a toggle, `label` and `description` become the words a non-technical author reads, and each entry in `presets` becomes a one-click choice. That's the real reason param naming matters — `variant: centered` and `renderMode: flex-center` aren't a style preference, they're the difference between a legible control and a baffling one. Write `meta.js` as though someone who will never see your code has to use it, because that's exactly who does.
+
+### Two worlds: section types and your own components
+
+The `{ content, params, block }` interface is not "how components work in Uniweb." It is how **section types** work — the components an author names with `type:` in frontmatter. A section type is a *public interface*: its name, params, and content expectations are a contract with content authors, and `meta.js` is its documentation.
+
+**Everything under `components/` is yours.** It's a normal React project in there, and the framework has no opinion about it:
+
+- **Any props you want** — `<PricingCard tier={tier} price={price} featured />`. No `content`, no `params`, no `block` unless you choose to pass them.
+- **Any composition** — children, render props, context, `forwardRef`, custom hooks, whatever the job needs.
+- **Any library** — install it and import it.
+- **No `meta.js`, no naming convention, no auto-discovery, no author visibility.**
+
+Two symptoms of getting this backwards, both worth checking yourself against:
+
+> **Don't give helper components a `{ content, params }` signature.** Copying the section interface downward is the most common version of this mistake. It makes every helper harder to reuse and hides what it actually needs. A card that takes `title`, `price`, and `features` is better than one that takes `content` and digs through it.
+
+> **Don't put helpers in `sections/`.** Anything at the root of `sections/` becomes author-selectable vocabulary. A `Button` or `Card` appearing in the editor's section picker is a bug in your foundation's interface design, not a harmless extra.
+
+**A section type is usually a composite.** Its job is to translate parsed content into whatever your own components expect, then arrange them:
+
+```jsx
+// sections/Pricing/index.jsx
+import PricingCard from '#components/PricingCard'
+import formatPrice from '#utils/formatPrice'
+
+export default function Pricing({ content, params }) {
+  const currency = params.currency || 'USD'
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-3 gap-8 max-w-6xl mx-auto">
+      {content.items.map((tier, i) => (
+        <PricingCard key={i} tier={tier} price={formatPrice(tier.data, currency)} />
+      ))}
+    </div>
+  )
+}
+```
+
+The author writes `type: Pricing` and defines tiers as content items. `PricingCard` knows nothing about Uniweb — it takes a tier and a price. That boundary is what makes it testable, reusable across section types, and replaceable without touching the author-facing contract.
+
+**There are many ways to use `components/`**, and no expected shape. Presentational primitives shared across section types (buttons, cards, badges). A thin wrapper adapting the parsed content shape to a third-party component's props. Layout scaffolding several section types share. Stateful widgets. Legacy components carried in during a migration. The Front Desk pattern below is *one* specific arrangement worth knowing — not a requirement, and not the main reason to have helper components.
+
+### The Front Desk pattern
+
+One arrangement of the above is worth naming, because it comes up whenever a single `type:` needs to cover genuinely different renderings.
+
+Section types naturally use params to adjust their own rendering — `variant: flipped` reverses a flex direction, `columns: 3` sets a grid. That's the baseline, not a pattern. The **Front Desk pattern** is the step beyond it: a section type that does virtually no rendering itself, instead reading the author's params, picking the right helper component, and translating author-friendly vocabulary into developer-oriented props.
+
+The workers behind the desk need not share an interface. A `Hero` might delegate to a `SliderHero` (image carousel) and a `ContactHero` (quote form) expecting different content and different props. The front desk declares the **union** of everything its workers might need — some content goes unused for a given variant, and that's normal in CCA: params change behavior, and that includes not rendering some content.
+
+```js
+// meta.js — the union of all variants' needs
+export default {
+  params: {
+    variant: { type: 'select', options: ['slider', 'contact'], default: 'slider' },
+    slideInterval: { type: 'number', default: 5 },
+    density: { type: 'select', options: ['default', 'compact'], default: 'default' },
+    style: { type: 'select', options: ['default', 'dramatic'], default: 'default' },
+  }
+}
+```
+
+```jsx
+// sections/Hero/index.jsx — the front desk
+import { SliderHero } from '#components/SliderHero'
+import { ContactHero } from '#components/ContactHero'
+
+const variants = { slider: SliderHero, contact: ContactHero }
+
+export default function Hero({ content, block, params }) {
+  const Variant = variants[params.variant] || SliderHero
+  return (
+    <Variant
+      title={content.title} subtitle={content.paragraphs[0]} links={content.links} block={block}
+      images={content.images}                                 // only some variants use these
+      formData={content.data?.quote}
+      interval={params.slideInterval}                         // author vocabulary → developer props
+      compact={params.density === 'compact'}
+      transition={params.style === 'dramatic' ? 'zoom' : 'fade'}
+    />
+  )
+}
+```
+
+`SliderHero` uses `images`, `interval`, `transition` and ignores the rest; `ContactHero` uses `formData` and `compact` and ignores the rest. The author writes `variant: contact` — they don't know or care that `ContactHero` exists.
+
+This is the system-building pattern at its clearest: **section types are the public interface** (author-friendly names, documented in `meta.js`); **helper components are the implementation** (ordinary React props). The section type is the thin translation layer between the two worlds.
+
+
+**When to reach for this pattern:** when a page type has consistent structural elements — header bars, navigation footers, contextual sidebars — that the content author shouldn't have to add as separate sections. If the author would otherwise repeat the same boilerplate sections on every page of a given type, the section component should compose them internally.
+
+**Common mistake:** solving structural repetition at the layout level. If only some page types need a content header (lessons do, the homepage doesn't), that's a section concern. The layout owns page-wide chrome; the section owns its internal structure.
+
+### Params, component vars, foundation vars
+
+Three places a value can live, and picking the right one is most of the design:
+
+| | Declared in | Reaches the component as | Author overrides in | CSS scope |
+|---|---|---|---|---|
+| **Param** | `meta.js` `params:` | a JS prop | section frontmatter | — |
+| **Component var** | `meta.js` `vars:` | a CSS custom property | section frontmatter `vars:` | `#section-{id}` |
+| **Foundation var** | `main.js` `vars:` | a CSS custom property | `theme.yml` `vars:` | `:root` (global) |
+
+**Param when the value drives logic** — a count, a variant name, a boolean the JSX branches on. **Component var when it only drives CSS** and belongs to one section type; it never enters JS, so it doesn't re-render anything:
+
+```js
+// meta.js — same schema as foundation vars (default, label, type, options, group, description)
+vars: {
+  'card-gap':    { default: '1.5rem', label: 'Card Gap', type: 'select', options: ['1rem', '1.5rem', '2rem'] },
+  'card-radius': { default: 'var(--radius-md)', description: 'Inherits the foundation var by default' },
+}
+```
+
+```jsx
+<div className="grid gap-[var(--card-gap)]">          // emitted on #section-{id}
+```
+
+```yaml
+---
+type: PricingTable
+vars: { card-gap: 2rem }        # author override — only declared names apply
+---
+```
+
+Unknown var names in frontmatter are ignored, and component vars are always context-independent (unlike foundation `color`/`gradient` vars, which resolve per light/dark context).
+
+**Foundation var when the value must stay consistent *across* components** — shared radii, spacing scales, extra typefaces. A header height is a layout param, not a foundation var; a sidebar width is a layout param too. Declare foundation vars in **`main.js`**, the single source of truth:
+
+```js
+export const vars = {
+  'radius-lg': { default: '1rem', description: 'Large border radius' },
+  'section-padding-y': { default: 'clamp(4rem, 6vw, 7rem)', description: 'Vertical section padding' },
+}
+```
+
+Each entry ships the default as a CSS custom property (so `var(--section-padding-y)` resolves everywhere), gives the visual editor a description and type, and is what a site overrides under `vars:` in `theme.yml`. You don't declare these anywhere else — the defaults reach the browser on their own, in dev and production, bundled or runtime-loaded.
+
+A `styles.css` `@theme` block is a different tool: it registers a token so **Tailwind generates utilities** from it (`@theme { --breakpoint-xs: 30rem }` → `xs:` variants). Use it to extend Tailwind's vocabulary, not to ship a plain default.
+
+**A name matching a Tailwind namespace is an intentional override.** A var named after a Tailwind v4 scale — `radius-*`, `shadow-*`, `spacing`, `font-*` — redefines that scale wherever the matching utility appears: declaring `radius-lg` retunes every `rounded-lg` in the foundation. That's the point when you mean it — name deliberately so you don't reshape a utility by accident.
+
+### Semantic theming
+
+Components use **semantic CSS tokens** instead of hardcoded colors. The runtime applies a context class (`context-light`, `context-medium`, `context-dark`) to each section from its `theme:` frontmatter.
+
+```jsx
+<h2 className="text-slate-900">…</h2>   // ❌ Hardcoded — breaks in dark context
+<h2 className="text-heading">…</h2>     // ✅ Semantic — adapts to any context and brand
+```
+
+**Semantic tokens** (available as Tailwind `text-*`, `bg-*`, `border-*` classes):
+
+| Token | Purpose |
+|-------|---------|
+| `heading` | Heading text |
+| `body` | Body text |
+| `subtle` | Secondary/de-emphasized text |
+| `section` | Section background |
+| `card` | Card/panel/well background |
+| `muted` | Hover states, zebra rows |
+| `border` | Lines, dividers |
+| `ring` | Focus indicators |
+| `link` / `link-hover` | Link colors |
+| `primary` / `primary-foreground` / `primary-hover` / `primary-border` | Primary actions |
+| `secondary` / `secondary-foreground` / `secondary-hover` / `secondary-border` | Secondary actions |
+| `success` / `warning` / `error` / `info` | Status colors |
+| `success-subtle` / `warning-subtle` / `error-subtle` / `info-subtle` | Status backgrounds (alerts) |
+
+**Palette shades** are also available — `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 11 shades (50–950) per palette color (primary, secondary, accent, neutral). See `theme-tokens.css` for the complete mapping.
+
+> **Debugging a token that "does nothing": don't probe it in the browser.** Tailwind v4 is JIT — it emits only the classes it finds in *scanned source*. So a class you assign from JavaScript, to a `<div>` you created in the console, **has never been scanned and can never resolve**, whatever the token. A comparison against a deliberately bogus class agrees with you either way, because both are ungenerated, and classes that happen to appear in source elsewhere look like they "pass" — so the probe confirms whichever answer you started with.
+>
+> **Ask the build instead.** The one command that splits the question:
+>
+> ```bash
+> grep -o '\.text-link{[^}]*}' dist/assets/*.css
+> ```
+>
+> A rule prints → the utility exists, and something at runtime is overriding it. Nothing prints → Tailwind never generated it, and there are only two reasons: your `styles.css` doesn't `@import "@uniweb/kit/theme-tokens.css"` (or declares its own `@theme inline` that omits the token), or your `@source` globs don't cover the file the class is written in. Either way, write the class into a real source file first — a token that's only ever composed at runtime is invisible to the scanner by design.
+
+**Authors control context** via `theme: dark` in frontmatter, alternating `light` (default), `medium`, and `dark` across sections for visual rhythm. **The three presets aren't the limit** — a section's `theme:` is `theme.yml` for that section: tokens beside `mode`, and `theme.yml`'s own `colors`, `contexts` and `vars`, scoped to it:
+
+```yaml
+theme:
+  mode: light
+  section: neutral-100               # Subtle off-white surface
+  card: neutral-50                   # Cards lighter than surface
+  primary: neutral-900               # Dark buttons instead of brand color
+  colors: { accent: '#e65100' }      # A palette for this section only
+  contexts:                          # Per context, for a section that follows the site's scheme
+    dark: { link: accent-300 }
+```
+
+`background:` also accepts CSS variables and hex, so authors can alternate `var(--neutral-50)` / `var(--primary-50)` surfaces with no component code. If a source design uses subtle surface variations (`--surface-base` vs `--surface-sunken`), map those to backgrounds or token overrides in frontmatter — not to component code.
+
+### Section context vs site scheme
+
+Uniweb splits what other frameworks fuse into one "dark mode":
+
+- **Section context** — the `theme:` field on one section (`light`/`medium`/`dark`). Per-section, author-controlled.
+- **Site scheme** — the global light/dark preference under `appearance:` in `theme.yml`. The site-wide toggle a visitor flips.
+
+They compose rather than fight: a section with **no `theme:`** inherits the site scheme and follows the toggle; a section that **pins** `theme: dark` stays dark in either scheme. A dark site can carry one bright white CTA. You never write `isDark ? … : …` — semantic tokens adapt to whichever scheme and context resolve around them.
+
+```yaml
+appearance:
+  default: light                # 'light' | 'dark' | 'system'
+  allowToggle: true             # offer a visitor switch (also generates the dark tokens)
+  respectSystemPreference: true # first visit follows the OS; false pins `default`
+  schemes: [light, dark]        # optional — declares the available set
+```
+
+Shorthands: `appearance: light` / `dark` (fixed, no toggle), `appearance: system` (follow the OS).
+
+A site **has dark mode** whenever it offers a toggle, defaults to `dark`/`system`, or lists `dark` in `schemes:`. Precedence: a stored choice wins over the OS, which wins over `default:`. Note that `default: light` is a *fallback*, not a guarantee — a dark OS still wins on first visit unless `respectSystemPreference: false`. (`default: system` is just the honest way to say "there is no fixed default — use the OS.")
+
+| Goal | `theme.yml` |
+|---|---|
+| Always light, no switch | `appearance: light` |
+| Always dark, no switch | `appearance: dark` |
+| Toggle, follow the OS on first visit | `appearance: { default: system, allowToggle: true }` |
+| Toggle, but always start light | `appearance: { default: light, allowToggle: true, respectSystemPreference: false }` |
+
+**Rendering a toggle.** The runtime resolves the scheme and applies it to `<html>` (`scheme-dark`/`scheme-light`) *before the page paints* — never touch `localStorage` or `document` yourself, and there's no flash of the wrong scheme. A section type only renders the button:
+
+```jsx
+import { useAppearance } from '@uniweb/kit'
+
+function SchemeToggle() {
+  const { scheme, toggle, canToggle } = useAppearance()
+  if (!canToggle) return null            // hidden unless the site enables toggling
+  return <button onClick={toggle}>{scheme === 'dark' ? 'Light' : 'Dark'}</button>
+}
+```
+
+**Tailwind `dark:` variant.** If your foundation uses `dark:` utilities, bind them to the site scheme so they track the toggle. In `styles.css`:
+
+```css
+@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));
+```
+
+Without this, `dark:` falls back to `@media (prefers-color-scheme: dark)` and ignores the site's setting. Prefer semantic tokens over `dark:` where you can — they adapt to per-section context, which a global `dark:` cannot.
+
+### theme.yml
+
+```yaml
+# site/theme.yml
+colors:
+  primary: '#3b82f6'          # Your exact hex appears at shade 500
+  secondary: '#64748b'
+  accent: '#8b5cf6'
+  neutral: stone              # Named preset: stone, zinc, gray, slate, neutral
+
+contexts:
+  light:
+    section: '#fafaf9'        # Override individual tokens per context
+
+appearance: { default: light, allowToggle: true }
+
+fonts:
+  heading: "'Inter', system-ui, sans-serif"
+  body: "'Inter', system-ui, sans-serif"
+
+inline:
+  callout: { color: var(--accent), font-weight: '600' }
+
+vars:
+  radius: 0.75rem
+```
+
+Each color generates 11 OKLCH shades (50–950); shade 500 is your exact input. `neutral` takes a named preset rather than hex. Context override keys match token names: `section:` not `bg:`, `primary:` not `btn-primary-bg:`.
+
+**How colors reach components:** your hex → 11 shades → semantic tokens → components. In light/medium, `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark, `--primary` uses 500 and `--link` 400.
+
+**Buttons use shade 600 — darker than your input color.** That's an accessibility choice for contrast with white text. For brand-exact buttons:
+
+```yaml
+colors: { primary: "#E35D25" }
+contexts:
+  light:
+    primary: primary-500         # Your exact color on buttons
+    primary-hover: primary-600
+```
+
+> **Contrast warning:** bright brand colors (orange, yellow, light green) at shade 500 may fail WCAG 4.5:1 against white text. Test for readability — if contrast is insufficient, keep the default 600 mapping.
+
+### Fonts
+
+Font families are a **site** setting, under `fonts:` in `theme.yml`. A foundation never installs a font package (no `@fontsource/*`) and never hardcodes a family — if you reach for either, you're off the paved path. Three roles are wired onto standard elements for you:
+
+| Role | Wired onto | Typical use |
+|---|---|---|
+| `body` | `body` (all text by default) | paragraphs, UI |
+| `heading` | `h1, h2, h3` | titles |
+| `code` | `code, pre, kbd, samp` | code, monospace |
+
+(`code` was previously named `mono`; `fonts.mono` is no longer an alias — rename it.)
+
+Because the site wires families onto real elements, **the norm is that a foundation doesn't set fonts itself** — render semantic markup (`<H1>`, `<P>`, `<code>` from the kit) and the roles apply. Everything else stays Tailwind.
+
+**In a component, weight is yours; family is the site's.** Weight/size/style utilities (`font-bold`, `italic`, `text-xl`) are ordinary design vocabulary. A font-**family** utility is different: `font-sans`/`font-serif` resolve to Tailwind's built-in stacks unless the foundation makes them site-controlled, so a bare `font-serif` silently hardcodes a typeface.
+
+**When a design needs typefaces the three roles can't express** — an editorial serif, a display face for hero titles — declare each as a **font var** in `main.js`. A `font-*`-named var is recognized as a typeface automatically (no `type` needed); a bare-named one takes `type: 'font'`. Either way the site loads and owns the family:
+
+```js
+// foundation src/main.js
+export const vars = {
+  'font-serif': {
+    default: 'ui-serif, Georgia, serif',
+    description: 'Editorial serif — blurbs, taglines, quotes',
+    applyTo: ['blockquote', '.tagline'],   // framework emits the rule, like a built-in role
+  },
+  'font-display': {
+    default: 'ui-sans-serif, system-ui, sans-serif',
+    // no applyTo → the component wires it (a `font-display` utility, or var(--font-display))
+  },
+}
+```
+
+The `fonts:` block takes **any** role name, built-in or foundation-added, so a site sets its whole type system in one place. The three roles are defaults you can **retarget** too — redeclaring a role's var with a new `applyTo` changes which elements it paints, while the site still owns the family.
+
+```yaml
+# site/theme.yml — loading, hosted or self-hosted; both config-only, no dependency
+fonts:
+  heading: "Poppins, sans-serif"
+  serif: '"Fraunces", Georgia, serif'      # a foundation-declared role, set by name
+  import:
+    - url: "https://fonts.googleapis.com/css2?family=Poppins:wght@600;700"
+  faces:
+    - { family: "Fraunces", src: /fonts/fraunces.woff2, weight: "100 900" }
+```
+
+The build auto-adds preconnect hints for imports, emits `@font-face` + preload for faces, and drops any family no role references.
+
+> **`serif` and `font-serif` are the same font var** — the `font-` spelling is just the one Tailwind's `font-serif` utility reads. Declare it either way in `main.js`; the site sets it by the bare role name under `fonts:`.
+
+> The `code` role owns `--font-code`. Tailwind's `font-mono` utility (which reads `--font-mono`) is a **separate** concern — control it by declaring your own `font-mono` font var. So `fonts.code` styles code without disturbing `font-mono`-styled labels, and vice-versa.
+
+### Tailwind v4 and styles.css
+
+```css
+@import "tailwindcss";
+@import "@uniweb/kit/theme-tokens.css";
+@source "./sections/**/*.{js,jsx}";
+@source "./components/**/*.{js,jsx}";
+@source "../node_modules/@uniweb/kit/src/**/*.jsx";
+
+@theme {
+  --breakpoint-xs: 30rem;
+}
+```
+
+Semantic tokens come from `theme-tokens.css` (populated from `theme.yml`). Use `@theme` only for values tokens don't cover. **Custom CSS is expected alongside Tailwind** — shadow systems, border hierarchies, gradients, glassmorphism. Tailwind handles layout; tokens handle context; `styles.css` handles everything else.
+
+**Tokens are a floor, not a ceiling.** They solve context adaptation — the hard problem. A great foundation adds design vocabulary on top:
+
+```css
+.border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
+.text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
+```
+
+These compose with tokens — they adapt per context because they reference token variables — while adding nuance the token set doesn't provide. Use palette shades directly (`var(--primary-300)`, `bg-neutral-200`) for fine-grained control. **The priority: design quality > portability > configurability.** A beautiful foundation for one site is worth more than a generic one that looks flat.
+
+Two lines a ported CSS reset will try to bring with it, both of which break things:
+
+> **Don't set `scroll-behavior: smooth` globally.** The runtime owns scrolling: it already smooth-scrolls anchor targets itself (`scrollIntoView({ behavior: 'smooth' })`), so the CSS adds nothing there — but it resets and restores scroll on route changes with the two-argument `scrollTo(x, y)`, which *inherits* the property. Route changes then animate their scroll-to-top, and back-button restoration (which scrolls, checks the position on the next frame, and retries) keeps interrupting its own animation. Scope it to a specific scrollable element if you need it; never to `html` or `body`.
+
+> **Font smoothing is a per-scheme decision, not a reset.** `-webkit-font-smoothing: antialiased` (macOS only) forces grayscale rasterization, which thins strokes. On dark surfaces that usefully counteracts the bloom of light text on near-black; on light surfaces it costs contrast and makes body text spindly. Scope it — `.scheme-dark { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }` — rather than putting it on `html`.
+
+### Composition: items, child sections, insets
+
+Pages are sequences of sections — the obvious layer. The framework also supports real nesting, without leaving markdown.
+
+| Pattern | How authored | Use when |
+|---|---|---|
+| **Items** (`content.items`) | Heading groups within one `.md` | Repeating content in one section: cards, features, FAQ entries |
+| **Concept blocks** (`content.data[tag]`) | ` ```md:<tag> ` fence around markdown | A named *kind* of content — an FAQ, a callout, a set of steps |
+| **Child sections** (`block.childBlocks`) | `@`-prefixed `.md` files + `nest:` | Children needing their own section type, rich content, or independent editing |
+| **Insets** (`block.insets`) | `![](@Component)` in markdown | Self-contained visuals/widgets: charts, diagrams, code demos |
+| **Block insets** (`block.insets`) | ` ```@Component ` fence around markdown | A component that *wraps* authored prose: callouts, disclosures, admonitions |
+
+Does the author write content *inside* the nested element? **Yes** → child sections, or a block inset when the wrapper is presentational and lives mid-page. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children; a block inset can contain both.
+
+**Child sections in columns.** A section type that lays its children out in a grid offers layouts in `meta.js` — `children: { grid: [3, 2, '40/60'] }`, the first being its default — and renders them with kit's `<ChildGrid from={block} fallback={3} />`. The author picks one with `grid:` in the parent's frontmatter (`grid: 3`, `grid: '40/60'`), a section key like `type`, not a param. Each child renders as a section, so its own `theme:` and `background:` apply. Don't declare a param named `grid`.
+
+### Concept blocks — naming *what* content is
+
+A ` ```md:<tag> ` fence marks a run of prose as a named kind of thing. The author writes ordinary markdown; the tag says what it is:
+
+````markdown
+```md:faq
+# What plans do you have?
+Three — Starter, Team and Enterprise.
+
+# Can I change later?
+Any time, and we prorate the difference.
+```
+````
+
+Every `#` heading starts an item, so this arrives as `content.data.faq`:
+
+```js
+{
+  items:    [ { title, paragraphs, links, … }, … ],  // one per heading
+  sequence: [ … ]                                    // the same content, in document order
+}
+```
+
+**The shape is fixed by the fence, not by the tag.** Any tag works and none is special — the framework never learns what `faq` means. A body with **no** headings is the same block with a single titleless item, which is what a callout is:
+
+````markdown
+```md:warning
+Back up your database **before** running this. It is not reversible.
+```
+````
+
+**Why this instead of a component reference.** ` ```@Alert ` names *which component renders this*, which is a rendering decision sitting in content. `md:warning` names *what the content is* and leaves rendering to the foundation — so the same content works under a different foundation, and an editor can recognize the concept and offer a surface built for it.
+
+**A data block whose value is itself a schema.** An author can design a form in the visual editor; it lands as a ` ```yaml:form ` block at `content.data.form`. A component that renders one is the inverse of every other component: it declares the key (`data: { form: … }`) but not the fields — it *receives* them and draws whatever it's given, since the field names are the author's and aren't knowable when you write `meta.js`.
+
+That makes one distinction worth holding onto. You **may** declare a schema describing the form *definition's envelope* — `title`, `description`, `fields` as a map — and get build-time validation that an authored form is well-formed. What you can't declare is a schema whose fields are *the form's* fields (`name`, `email`, …); that's describing the visitor's answers, which arrive at runtime and belong to a form you've never seen. Declare the key either way — it is what delivers the block — and give it a schema only if you want it checked, and only of the envelope (`{}` declares the key with none).
+
+**Reading one in a component.** Declare it the way the author writes the fence — `data: { 'md:faq': 'Questions and answers [3+]' }`. The value is the author's label (its count counts the entries), or `{ label, hint, content: { title: 'Question', paragraphs: 'Answer' } }` to say what each entry holds. The component still reads `content.data.faq`, which gives you both views: `items` for anything row-shaped (an accordion, a step list), `sequence` when you don't recognize the tag and want to render it faithfully in document order. Both are derived, so nothing is stored twice. (`faq: {}` also declares the key, saying nothing about the block.)
+
+```jsx
+function Faq({ content }) {
+  const faq = content.data?.faq
+  if (!faq) return null
+  return faq.items.map((item, i) => <Disclosure key={i} q={item.title} a={item.paragraphs} />)
+}
+```
+
+**Two tags, not a tag plus a variant.** A warning and a note are different concepts, so they are `md:warning` and `md:note`. The fence takes no params.
+
+**Insets — embedding components in content.** Many section types need a "visual" — a hero's illustration, a split-content section's media. Classically an image or video. But what if it's a JSX + SVG diagram, a ThreeJS animation, an interactive playground? Elsewhere you'd reach for MDX or prop-drilling. Here the author writes standard image syntax:
+
+```markdown
+![Architecture overview](@NetworkDiagram){variant=compact}
+```
+
+The developer builds `NetworkDiagram` as an ordinary React component with `inset: true` in `meta.js`. The section that hosts it declares a `media` slot, and kit's `<Visual>` renders the author's item by its kind — so one section type works whether the author supplies an image, a video, or an interactive component:
+
+```jsx
+// meta.js: content: { title: 'Headline', media: 'Illustration [1]' }
+<Visual media={content.media} block={block} className="rounded-2xl" />
+```
+
+**Insets are full section types** — they receive `{ content, params, block }`. The alt text becomes `content.title` and attributes become `params`: `![npm create uniweb](@CommandBlock){note="Ready to go"}` → `content.title = "npm create uniweb"`, `params.note = "Ready to go"`.
+
+**Don't use `hidden: true` on insets.** `hidden` means "don't export this component at all" (internal helpers); `inset: true` means "available for `@Component` references in markdown" — and a visual editor then offers it as an inset only. For a component placed both as a section and as an inset, add `section: true`.
+
+**Block insets — a component that wraps content.** The image form is a leaf: it takes params but no body. When the component should surround authored prose — a callout, a disclosure, an admonition — use the fenced form instead. Same `@Component{params}` reference, written as a code fence's info string:
+
+````markdown
+```@Alert{type=warning}
+Back up your database **before** running this.
+
+- The migration is not reversible
+- Allow ten minutes of downtime
+```
+````
+
+The body is ordinary content, not text: it is parsed exactly like the rest of the page, so headings, lists, tables, icons, inline styling, leaf insets and further containers all work inside one. To nest a code block or another container, open the outer fence with more backticks than the inner one.
+
+**The component is yours, and it receives parsed content.** `@Alert` resolves against the foundation through the same lookup as `![](@NetworkDiagram)` — declare it with `inset: true` in `meta.js`. Where a leaf inset gets its alt text as `content.title` and nothing else, a container gets its whole body parsed: `title`, `paragraphs`, `items`, `sequence`. Render it with `<Prose content={content} block={block} />` or read the fields directly. A name the foundation doesn't define renders a visible `Component not found: <Name>` error in place of the inset — deliberately, so a typo or a missing declaration is obvious on the page instead of quietly looking like a design choice.
+
+Prefer a **child section** when the author needs their own section type and independent editing; prefer a **block inset** when the wrapper is presentational and belongs inline in a single file's prose.
+
+**Child sections.** You hit a complex layout — a 2:1 split with a panel and a main area. Your instinct says build a specialized component. Step back: the panel is a reusable section type, the main area is another, and the split is a Grid with `columns: "1fr 2fr"`. Your child components already adapt to narrow containers — container queries handle that. But hardcoding which components go where means the author can't rearrange or swap them. Child sections solve that:
+
+```
+pages/home/
+├── page.yml
+├── 2-dashboard.md          # Parent section (type: Grid, columns: "1fr 2fr")
+├── @sidebar-stats.md       # Child (@ = not top-level)
+└── @main-chart.md
+```
+
+```yaml
+# page.yml
+nest:
+  dashboard: [sidebar-stats, main-chart]
+```
+
+**Rules:**
+- `@`-prefixed files are excluded from the top-level section list; `@@` nests deeper (grandchildren)
+- `nest:` maps parent name → child names, and is **flat**: `{ features: [a, b], a: [sub-1] }`
+- Children are ordered by position in the `nest:` array
+
+```jsx
+import { ChildBlocks } from '@uniweb/kit'
+
+export default function Grid({ block, params }) {
+  return <div className={`grid grid-cols-${params.columns || 2} gap-6`}><ChildBlocks from={block} /></div>
+}
+```
+
+`ChildBlocks` renders each child as a **bare component by default** — no wrapper, no context class, no background. That's right for grid cells, tab panels, carousel slides. For the rare case where children should be independent sections with their own theming and backgrounds, pass `wrapAs="div"`.
+
+Each child is a regular section with its own type, params, and content — and you're in the middle: wrap each child, filter by type, reorder, add container classes. The author decides *what* goes in the grid; your component decides *how* it renders. Tomorrow the author can swap a child for a different section type with no code change, and your components stay reusable wherever child sections are accepted.
+
+**Data and child blocks:** page-level `query:` (or `fetch:`) is available to all blocks including children, and each child resolves data independently through the page → parent page → site hierarchy (the site's only on a top-level page). If a child needs data no ancestor declares, give it its own in its frontmatter (`query: articles`, or `fetch:`). Its `meta.js` `data:` declares the keys it receives and their shapes, never where the data comes from — it fetches nothing.
+
+**SSG:** insets, `<ChildBlocks>`, and `<Visual>` all render correctly during prerender. Inset components using React hooks internally trigger prerender warnings — expected and harmless; the page renders correctly client-side.
+
+### Dividers — content boundaries
+
+`---` creates a boundary between content regions; the developer decides what each region means.
+
+**UI regions.** `splitContent()` from `@uniweb/kit` splits parsed content at divider elements — e.g. lesson prose vs challenge content:
+
+```jsx
+const [lesson, challenge] = splitContent(content)
+```
+
+<!-- template:loom -->
+**Data-driven iteration (Loom).** Dividers separate header/body/footer in a repeated template. The split happens *before* Loom runs, because each segment gets a different variable context — the body contains item-level fields that don't exist on the top-level data. Header and footer are instantiated once against the full data; the body repeats per item.
+
+```markdown
+---
+type: CvEntry
+source: education
+---
+# Education
+{COUNT OF education} degrees.
+---
+## {degree}
+{institution} — {field} ({start}–{end})
+```
+
+**Which to use:** different data contexts per region → Loom pre-parse split (content handler). Same data, different UI treatment → kit post-parse split (`splitContent`). A foundation can use both — Loom splits and iterates to produce final content, then the component splits the result to route regions to different UI.
+<!-- /template:loom -->
+
+### Custom layouts
+
+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
+export default function DocsLayout({ header, body, footer, left, right, params }) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      {header && <header>{header}</header>}
+      <div className="flex-1 flex">
+        {left && <aside className="w-64">{left}</aside>}
+        <main className="flex-1">{body}</main>
+        {right && <aside className="w-64">{right}</aside>}
+      </div>
+      {footer && <footer>{footer}</footer>}
+    </div>
+  )
+}
+```
+
+Layouts are full components with their own `params` in `meta.js`, not just structural wrappers — a header height or sidebar width is a layout param.
+
+**Layout `meta.js`** declares areas and optional scroll behavior: `{ areas: ['header', 'footer', 'left'], scroll: 'self' }`. Area names are arbitrary. `areas` tells an editor what to offer; a page renders the areas its site's `layout/` folder fills. `scroll` controls scroll restoration: unset = runtime manages `window` (default), `'self'` = the layout scrolls itself, or a CSS selector (`'main'`) = runtime manages that element.
+
+Two optional keys tune how areas behave across a navigation. `transitions` renames or opts regions out of per-area view transitions (`{ left: null }`, or `false` for the whole layout). `layers` sets which area paints on top — every area is stacked above the body by default, so a fixed header works without declaring anything, but areas are equal to each other, so a layout whose chrome overlaps says which wins: `layers: { header: 2, left: 1 }`. Both take an object to override per region, or `false` to opt out. **A `z-index` inside an area cannot lift it past another area** — each area is its own stacking context — so reach for `layers` rather than a bigger number, and for `<Overlay>` when a modal needs to escape the area entirely.
+
+**Layout content** lives in `site/layout/` — `header.md`, `footer.md` for the default layout, or a named subdirectory (`site/layout/marketing/`) for named layouts. Named subdirectories are self-contained — no inheritance. Cascade: `page.yml` → `folder.yml` → `site.yml` → foundation `defaultLayout` → `"default"`. The structure alone decides what an entry is: every folder directly under `layout/` is a named layout (its name matched regardless of case and of a trailing `Layout` — `site/layout/docs/` serves the foundation's `DocsLayout`), and an area with several sections is a folder inside a layout's folder — `site/layout/default/header/1-topbar.md` for the default layout. An area has no `page.yml`; its sections render in filename order.
+
+Layout sections are regular section types — they support the full content shape, including tagged data blocks, lists, links, and items. The only difference is they render on every page. Each content category takes a different role:
+
+````markdown
+---
+type: Header
+---
+# Acme Inc                              ← content.title — the logo
+
+- ![](lu-search) [How It Works](/how)   ← content.lists[0] — the nav
+- ![](lu-book) [Docs](/docs)
+
+[Get Started](/docs/quickstart)         ← content.links[0] — the CTA
+
+```yaml:config
+github: https://github.com/acme         ← content.data.config — everything else
+```
+````
+
+```jsx
+function Header({ content }) {
+  const logo = content.title
+  const navItems = content.lists[0] || []
+  const cta = content.links[0]
+  const config = content.data?.config        // with `data: { config: {} }` in Header's meta.js
+}
+
+function Footer({ content }) {
+  const tagline = content.paragraphs[0]      // a plain paragraph
+  const columns = (content.lists[0] || []).map(group => ({
+    label: group.paragraphs[0],              // nested list → columns
+    links: group.lists[0]?.map(item => item.links[0])
+  }))
+}
+```
+
+### Cross-block communication
+
+Section types sometimes coordinate — the typical case is a Header that needs to know whether the section below supports a floating translucent overlay (a Hero with a full-bleed background does, a plain text section doesn't). The section that **owns the capability declares it**; the section that **needs to adapt reads it**. `getNextBlockInfo()` — and `getPrevBlockInfo()`, `page.getFirstBodyBlockInfo()` — expose two channels:
+
+- **`context`** — static capabilities from `meta.js`. Never changes.
+- **`state`** — dynamic runtime state via `useBlockState()`. Initial value from `initialState` in `meta.js`.
+
+```js
+// Hero/meta.js
+export default {
+  context:      { allowTranslucentTop: true },   // "I always support this"
+  initialState: { allowTranslucentTop: true },   // …or start true and let logic change it
+}
+```
+
+```jsx
+// Hero/index.jsx — dynamic case
+const [state, setState] = block.useBlockState(useState)
+
+// Header/index.jsx — reads dynamic state, falls back to static context
+const info = block.getNextBlockInfo()
+const isFloating = info?.state?.allowTranslucentTop ?? info?.context?.allowTranslucentTop ?? false
+```
+
+The key names are yours to design — they're not framework fields.
+
+### block, website, and page
+
+```jsx
+const { website } = useWebsite()
+const page = website.activePage
+```
+
+| `block` property | Description |
+|----------|-------------|
+| `block.page` / `block.website` | Parent page / site-level data and navigation |
+| `block.type` | Component type name |
+| `block.childBlocks` / `block.insets` | Child sections / inline `@Component` references |
+| `block.getInset(refId)` | Lookup an inset by refId |
+| `block.properties` | Raw frontmatter |
+| `block.rawContent` | ProseMirror document — passed internally by `<Article block={block} />` |
+| `block.themeName` | `"light"`, `"medium"`, `"dark"` |
+| `block.stableId` / `block.key` | Stable ID from filename or `id:` / unique key across pages — use as React key |
+| `block.path` | Page route this block belongs to |
+| `block.dataLoading` | True while declared data is still resolving |
+| `block.dataError` | `{ <key>: message }` when the fetch filling a declared key FAILED, else `null`. A failed key is `null` in `content.data` — never `[]`, which means "no records" |
+
+```jsx
+// getPageHierarchy(options) →
+//   [{ id, route, navigableRoute, translatedRoute, title, label, description, hasContent, version, children }]
+// Options: for: 'header'|'footer'|<area> (respects hideIn) · nested: true (default)
+//          includeHidden: false · filter: (page) => bool · sort: (a, b) => number
+website.getPageHierarchy({ for: 'header' })      // = website.getHeaderPages()
+website.getPageHierarchy({ nested: false })      // = website.getAllPages()
+
+website.name, website.basePath
+website.hasMultipleLocales(), website.getLocales(), website.getActiveLocale(), website.getLocaleUrl('es')
+
+page.title, page.label, page.route, page.description
+page.isHidden(), page.showInHeader(), page.showInFooter()
+page.hasContent()          // true if the page has its own content (not just a folder)
+page.hasChildren(), page.children, page.parent
+page.getNavigableRoute()   // first descendant route with content (for linking)
+```
+
+Content-less containers appear as group nodes (`hasContent: false`) — use `navigableRoute` for links, `title` for display, `hasContent` to style differently.
+
+### Data
+
+**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 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:
+
+```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 }) {   // data: { article: { schema: '@std/article', single: true } }
+  if (block.dataLoading) return <DataPlaceholder />
+  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} />
+}
+```
+
+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.
+
+```js
+// meta.js
+export default {
+  data: {
+    articles: '@/article',                               // named ref (this foundation)
+    authors:  '@std/person',                             // named ref (shared standard)
+    pricing:  { tier: { type: 'string' } },              // inline field map
+  },
+}
+```
+
+A foundation can route a scope to a plain folder of schema files instead of a package via an optional `schemas.config.js` at its root — `export default { '@acme': '../shared/acme-schemas' }`. A routed scope wins over the package convention; `@/` and `@uniweb` are never routable; a routed scope has no package fallback for a missing schema (it errors rather than silently loading a different definition). Per-schema keys override single entries (most-specific wins: file › directory › package). Worked examples: `development/schemas-in-practice.md`.
+
+**Authoring queries.** Queries and fetch declarations accept `where:` (a where-object predicate), `sort:` (ONE key, e.g. `date desc` — text sorts in the page's language, and a record with no value for the key sorts last either way), and `limit:` — on a query they select its records, on a fetch they take from those. The framework evaluates them in the browser over the records it fetched, the query's first; a host that answers queries evaluates the same language at the source; a foundation transport decides for itself — it receives the query's fields and the fetch's own under `narrow`. The declaration is identical in every case.
+
+```yaml
+# pages/blog/page.yml
+fetch:
+  query: recent
+  where: { tags: featured }
+  sort: date desc
+  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 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.
+
+**Validate before shipping.** `uniweb validate` checks file-based data against your declared schemas — missing required fields, type/enum/format mismatches, nested fields. A violation fails it (`--lax` only reports); it checks every record file in `records/`, and `push` / `publish` refuse the same findings before sending anything. Distinct from `uniweb doctor` (project structure): `validate` checks your *data* against the schemas you *declared*. External queries (`url:`) are reported as deferred — their data isn't in the project; the value of a `ref`/`options` field is not checked against the entity it names.
+
+### Fetching from other sources (`fetcher:`)
+
+A site isn't limited to its own records. A public, keyless JSON API is an **external query** — a query with `url:`, declared beside the others and named by pages the same way (`query: posts`):
+
+```yaml
+# queries.yml
+posts:
+  url: https://api.example.com/posts
+  transform: data.items                    # dot-path to the records in the response
+  record:                                  # one whole post, for a [id] page
+    url: https://api.example.com/posts/{id}
+```
+
+It also takes `method: POST` with a `body`, `where` / `sort` / `limit` (evaluated over what arrived, after `transform`), and `queryable`. Its records are entries in no folder and have no `$name`, so a `[slug]` page over it names the field the URL is in the query's own `where` — `where: { slug: :slug }` — which drops on the query's own page. `record:` takes `url`, `method`, `body` and `transform`: `url` and `method` default to the query's, `body` and `transform` never carry over, and a placeholder named by the page's folder (`{id}` for `[id]`, `{slug}` for `[slug]`) is its URL segment. `schema`, `scope`, `deferred`, `excerpt` and `path` are refused beside `url:` — they describe the site's own records. The visitor's browser fetches an external query (a `fetch:` with `prerender: true` makes the build fetch it instead); it is never asked of a host's records service and compiles no `/data` file. On a `[id]` page the list still decides which records exist — `record:` fetches the one it found, whole. A site published to a Uniweb host reads the host's records with no configuration at all.
+
+⛔ A `fetch:` never carries a source: `path`, `url`, `method`, `body`, `transform`, `detail` and `scope` on a fetch stop the build. The `detail:` forms (`rest`, `query`, a URL pattern) are now an external query's `record:`, and `detailUrl:` is `record.url`.
+
+A backend that needs a key, headers, paging, its own wire or query language is a **transport**: a named `{ resolve, cacheKey? }` exported by the foundation (or an extension), which the site selects per data key in `fetcher:` — the only thing that block is for:
+
+```yaml
+# site.yml
+fetcher:
+  transports:
+    articles: acme                   # a foundation-registered transport handles `query: articles`
+    events: default                  # explicitly route back to the default fetcher
+  acme:                              # binding config that transport reads
+    apiKey: pk_public_123
+```
+
+**Selection is explicit and site-owned.** For each request: `fetcher.transports[as]` wins if set; otherwise `fetcher.transports.default` if set; otherwise the framework's default fetcher. No route-walking, no `match()` predicates, no silent foundation-owned routing — the site picks.
+
+⛔ `fetcher.baseUrl`, `headers`, `envelope`, `supports` and `request.*` are **retired**: a third party's conventions belong in a transport, not in the runtime every site loads. The build warns once and ignores them.
+
+> **Never put secrets in `site.yml` or `queries.yml`** — every value in them is public to the browser. Sites needing private credentials proxy through the same origin at the deployment layer, so the site fetches `/api/…` and the proxy attaches the credential server-side.
+
+**Failures are visible, not empty:** a fetch that failed leaves its key `null` in `content.data` and names the message on `block.dataError[key]`; it is never delivered as `[]`, which means "no records". The page still renders — a section reads `dataError` to tell the two apart.
+
+When an external query is enough and when a transport is the answer: `development/data-sources.md`.
+
+Full model: `reference/data-fetching.md`. Where-object format with examples: `authoring/predicates.md`.
+
+### 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 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
+services:
+  search:
+    provider: index      # default — download an index, match in the browser
+```
+
+| Provider | Answers with | Trade-off |
+|---|---|---|
+| `index` (default) | `search-index.json`, ranked in the browser | Free, works on **any** host including a plain static one, tolerates typos. Contains only what existed at build time. |
+| `endpoint` | A server-side search API | Can cover records fetched from an API, and can be re-indexed without rebuilding the site. Requires a host that serves one. |
+| *any other name* | A foundation-supplied search transport | Fully open — Typesense, Meilisearch, Pagefind, a vendor API |
+
+```yaml
+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: `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`.
+
+`snippetHtml` is HTML with `<mark>`. Render it through `SafeHtml`, never as text.
+
+**Failures degrade rather than break** — a failing provider falls back to the local index when one exists, otherwise returns no results with a console warning. A search box never throws at a visitor.
+
+```jsx
+import { useSearch } from '@uniweb/kit'
+
+const { results, isLoading, query } = useSearch(website)   // `query` is a function
+<input onChange={e => query(e.target.value)} />            // debounced internally
+```
+
+Full reference: `authoring/search.md`.
+
+### 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.
+
+A form gets its destination from the first of these that applies:
+
+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 `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()`, `isBackendEnabled()`, `isAssistantEnabled()`,
+`isTrackingEnabled()`.
+
+```jsx
+import { isSearchEnabled } from '@uniweb/kit'
+
+if (!isSearchEnabled()) return null   // false ⇒ draw nothing
+```
+
+Each answers the same question — *would UI for this service work on this site?* — and `false`
+always means the same thing: **draw nothing.** `isSearchEnabled()` is true whenever *any* provider
+answers, including the prebuilt index a static site ships, so a search box gated on it appears
+wherever search works. The hooks that draw a feature hand you the same answer as a field
+(`useSearch().isEnabled`, `useFormSubmit().canSubmit`), so a component already using one needs
+nothing extra.
+
+When you need the **address** itself, not just whether one exists, ask for it:
+
+```jsx
+import { resolveService } from '@uniweb/kit'
+
+const { url, source } = resolveService(website, 'assistant')   // or 'search', or your own
+```
+
+**The name is open**: the framework ships clients for what it implements and
+resolution for anything, so a foundation can define a service the framework has
+never heard of and a host can fill it — ask for it with
+`website.isServiceEnabled('booking')`. Same escalation `fetcher.transports`
+offers for data.
+
+**Building an "Ask AI" component?** The service name is `assistant`, and a host that runs an agent for a site typically serves it at the conventional path `/_agent`. **You should never need to write that path** — ask the runtime instead:
+
+```jsx
+const { url } = resolveService(website, 'assistant')
+if (!url) return null          // this site has no agent — render nothing, or a static fallback
+```
+
+**This is a synchronous read, not a request.** Which services a site has was settled when the site was last published and travels in its metadata, so the runtime already holds the answer — there is no handshake, no probe, no await. Your component asks the runtime; the runtime does not ask anyone.
+
+⛔ **Absent is the answer, not a lookup that failed.** No `url` means the site has no agent — never enabled, or this host runs none. Render for that case; don't retry it. And don't hardcode `/_agent/chat` when nothing was declared: on a static host that turns "no agent here" into a 404 your component can't tell from a broken endpoint. The path is named above so you recognize the shape, not so you can construct it.
+
+⛔ **And don't tell the visitor.** `resolveService` returns `{ url, source }` and **deliberately nothing else** — there is no explanatory string and there was one, removed because it was a mistake. A visitor has no stake in which services the operator provisioned, and "this site has no assistant configured" reports someone's billing state to the public while reading like a breakage. It is neither. Worse, it is unfixably the wrong language: sites here are multilingual, or unilingual and not English, and a canned constant bypasses the site's whole localization pipeline. **Absence is a rendering decision, not a message**, and a generic component is expected to be smart about it. No assistant → no Ask-AI affordance. No submit endpoint → no form, or degrade to a `mailto:` the site already carries in its content. Any text a visitor should read is *site content* — authored and localized.
+
+`source` is `'site'`, `'host'` or `null`, and it is a **diagnostic for you** while you wire a site up: it says which tier answered, which is the thing to check when a host's value appears not to be taking effect. `'host'` with a null `url` means the host answered and offered no address.
+
+*(A live agent that errors mid-conversation is a different problem — that's ordinary request failure, handled where you make the request.)*
+
+### Declaring what your foundation supports
+
+The predicates above, and `resolveService`, are how you ask at render time. The other direction — telling a
+host, *before* anything renders, which services your foundation is built to use —
+is one line in the foundation's `package.json`:
+
+```json
+{
+  "uniweb": { "supports": ["search", "submit", "tracking"] }
+}
+```
+
+Service names, the same ones you pass to `resolveService`. It reaches a host when
+the foundation is registered, and it answers a question a host cannot otherwise
+answer: **a service only does something if the foundation renders something
+against it.** A host that offers search has no way to know whether your sections
+draw a search box, so without this it either offers a site something its code
+will ignore, or withholds something it would have used.
+
+**What a host receives is one of three answers:**
+
+| | |
+|---|---|
+| a list — `["search"]` | the services this foundation renders against, and only these |
+| `[]` | none — proven by the build, not assumed |
+| absent | *unknown* — the build could not tell, and nothing was declared |
+
+⭐ **The build reads the set off your code.** When the foundation is built, `supports` is derived
+from what the bundle actually reaches — `resolveService(website, 'search')`, or a predicate like
+`isSearchEnabled()` — so a foundation that never writes the key still publishes an accurate set.
+What you write in `package.json` is a **supplement**: the build publishes the union, so a
+declaration can add a service but never remove one the code reaches.
+
+**Declare only what the build cannot see.** A service reached through a *computed* name —
+`resolveService(website, name)` where `name` is a variable — is invisible to it, and the build
+warns when that happens. List those. `uniweb doctor` compares what you declared with what the build
+found.
+
+⚖️ **Baseline behaviour is not yours to declare.** Some services do something for
+a site whether or not a foundation cooperates — the runtime reports page views
+wherever tracking is configured, with no help from your components. List
+`tracking` when you go *beyond* that (your own events on your own components);
+leaving it out does not switch the baseline off.
+
+```yaml
+# 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
+import { useFormSubmit } from '@uniweb/kit'
+
+const { submit, status, error, canSubmit } = useFormSubmit({
+  block,                                    // supplies section + page context
+  context: { formId: 'contact' },
+  summary: (v) => ({ title: v.name, subtitle: v.email }),
+})
+
+if (!canSubmit) return null    // nowhere to send — render no form, or fall back
+                               // to contact details from the site's own content
+
+<button type="submit" disabled={status === 'submitting'}>Send</button>
+```
+
+> **The framework never invents an endpoint — but a host may supply one.** Don't
+> 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 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.
+>
+> ⛔ **Don't tell the visitor why.** There is deliberately no explanatory string:
+> which services an operator bought is none of a visitor's business, "not enabled
+> for this site" reads like a breakage when nothing is broken, and any such
+> sentence would be one language on a site that is often multilingual and rarely
+> English. Text a visitor reads is **site content** — authored, and localized with
+> everything else. Degrade to something useful instead: a `mailto:`, a phone
+> number, an address the site already carries.
+
+`status` runs `idle → submitting → success | error`; a non-2xx becomes a thrown
+`Error` carrying the endpoint's own `error` message when it sends one. For file
+fields, declare `fileSlots` and the endpoint replies with `uploadUrls` — the
+bytes never ride inside the JSON. `submitForm()` / `resolveSubmitTarget(website)`
+are the same behaviour without React.
+
+**Rendering a form the AUTHOR designed** — a `yaml:form` block at
+`content.data.form` — is the inverse of every other component: you don't declare
+the fields, you receive them and draw whatever you're given. `useFormValues` owns
+the part that's identical in every such component, so you write only the controls:
+
+```jsx
+import { useFormValues, useFormSubmit, valueAt } from '@uniweb/kit'
+
+const { controls, values, setValue, missing, formData, files } =
+  useFormValues(content.data.form)
+const { submit, canSubmit, status } = useFormSubmit({ block })
+
+{controls.map((c) => (
+  <MyControl key={c.path} control={c}          // branch on c.type — your design
+             value={valueAt(values, c.path)}
+             onChange={(v) => setValue(c.path, v)} />
+))}
+<button disabled={!canSubmit || missing.length > 0} onClick={() => submit(formData, { files })}>
+```
+
+`valueAt(values, path)` reads one control's value back out. It is the companion
+of `setValue` and is exported for exactly this loop: `values` is **nested**, so a
+control at `address.street` lives at `values.address.street`, and `values[c.path]`
+returns `undefined` for every nested control — a form that silently renders blank
+inputs and submits empty answers. Use `valueAt`, never index by path.
+
+It seeds each control's `default`, tracks edits, and reports `missing` — the
+`required` controls still empty — without enforcing anything, the same line
+`canSubmit` draws. **Submit `formData`, not `values`:** they differ because a
+`File` inside `formData` would be JSON-serialized to `{}`, so file controls are
+omitted from it and ride in `files` instead, each tagged with the control it came
+from. `values` keeps the `File` so your input can show its selection.
+
+Full reference: `development/receiving-form-submissions.md`.
+
+### 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
+runtime emits by itself.
+
+```yaml
+# site.yml — your own collector, on any host
+services:
+  tracking: https://collector.example.com/events
+```
+
+```yaml
+# or, when it needs more than an address
+services:
+  tracking:
+    endpoint: /collect
+    consent: required
+```
+
+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 `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.
+
+**Some events you get for free.** These are reported for you, with no call from
+your foundation and regardless of how it renders:
+
+| event | when |
+|---|---|
+| `page_view` | every route change, including the first |
+| `outbound_click` | a visitor follows a link off the site — the destination **host** only, never the full URL |
+| `section_view` | a section first becomes half-visible, on pages that ask for it (`trackSections`, below) |
+
+⛔ **So don't write your own link-click or scroll-into-view listener for these.**
+A second one double-counts against a collector that already has them.
+
+Everything else is yours to report:
+
+```jsx
+// In a section type, the block is already in your props.
+block.track('video_milestone', { milestone: 50 })
+```
+
+`block.track` attaches the page path and the section type for you. For an event
+with no block in hand, use the hook:
+
+```jsx
+import { useTracker } from '@uniweb/kit'
+
+const { track } = useTracker()
+<button onClick={() => track('brochure_download', { file: 'specs.pdf' })}>…</button>
+```
+
+The event name is yours — there is no list of permitted names. Five are already
+in use, so reach for these rather than inventing a synonym: the three automatic
+ones above — **`page_view`**, **`outbound_click`**, **`section_view`** — plus
+**`video_milestone`**, which kit's `<Media>` reports for any video you render
+through it, and **`read_depth`** from `useReadingDepth()` below. Put the
+varying part in a **field**, never in the name — four names for one event turn a
+collector's event dimension into a cardinality problem.
+
+### Choosing what a site sends
+
+By default a site sends `page_view`, `outbound_click` and `section_view` — or,
+where a host supplies the collector, whatever that host declares it collects.
+Narrow or widen that with `emit`:
+
+```yaml
+# site.yml — your own collector
+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
+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 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
+release is included without you changing anything — which is exactly why
+`standard` exists as well: it is a curated set that a release cannot grow behind
+your back.
+
+⭐ **Saying nothing means two different things, and which one depends on who
+supplies the address.** A site sending to its own `endpoint:` gets `standard`. A site
+on a **host-supplied** collector gets **whatever that host declares it
+collects** — it has no address of its own, so the arrangement is that the host
+does analytics for it, and the set grows when the host starts collecting
+something new. **Naming `emit` always wins**, so pin it if you would rather not
+follow your host.
+
+A site can also set **`flushIntervalMs`** to widen the batching window (default
+5000, milliseconds — `30` is thirty *milliseconds*). A host that supplies your
+collector may set it for you and your own value wins; the trade is fewer
+requests against more tail loss at the end of a visit.
+
+⚠️ **`emit` never limits what YOU send.** `block.track()` and `useTracker()` are
+not filtered by it — the registry is open, and your events are yours. It governs
+only the ones the framework emits on its own. A host may narrow the list further
+if it will not store an event, and it can never widen past what you asked for.
+
+### Reading depth in a long section
+
+`section_view` tells you a reader *arrived* at a section. For a long-form one —
+an article, a report, a case study — the question is how far they got:
+
+```jsx
+import { useRef } from 'react'
+import { useReadingDepth } from '@uniweb/kit'
+
+export default function Article({ content, block }) {
+  const ref = useRef(null)
+  useReadingDepth({ ref, block })
+  return <article ref={ref}>{/* … */}</article>
+}
+```
+
+That reports `read_depth` at 25 / 50 / 75 / 100% **of that element**, once each.
+Measuring the element rather than the page is the point: two long sections on
+one page report independently, and adding a section above them changes neither.
+
+⭐ **This one is a hook rather than automatic because only you know a section is
+long-form reading.** The framework cannot tell an essay from a row of logos, so
+it does not guess — and a foundation that never calls this pays nothing for it.
+
+**`trackSections`** is one page's answer on `section_view`, and it overrides the
+site in **both** directions — instrument one page of a site that sends `minimal`,
+or exempt a noisy page of a site that sends `standard`. Say nothing and the
+site's `emit` decides.
+
+⭐ **This is the only event with a per-page control, and the asymmetry is the
+point.** A page view is one event whatever the page and an outbound click is
+bounded by what a visitor does, but a section view is **one per section** — so a
+long page costs many times what a short one does. The control sits at the
+granularity the cost actually varies at.
+
+```yaml
+# page.yml
+trackSections: true     # or false to exempt this page
+```
+
+⛔ **Never guard a `track()` call.** A site with **no** tracking destination is
+the default and the majority: the call returns having done nothing, opened no
+connection, and thrown nothing. Absent is the normal state, not an error — so
+don't check whether tracking is on, and never render differently because of it.
+There is no "is tracking enabled" question a component should be asking.
+
+⚠️ **If a site asks for consent**, tracking holds everything until a visitor
+answers; granting sends what was buffered, denying discards it. A consent banner
+is an ordinary component:
+
+```jsx
+import { useTrackingConsent } from '@uniweb/kit'
+
+const { status, grant, deny } = useTrackingConsent()
+if (status !== 'pending') return null
+return <CookieBanner onAccept={grant} onReject={deny} />
+```
+
+Without `consent: required`, tracking starts immediately — declaring a
+destination is the site owner's decision to make, not the framework's.
+
+Every event carries a **`visit`** key on the envelope — opaque, generated at page
+load, the same for every event of that page load — so a collector can order what
+happened into a journey.
+
+> **What is never sent:** no visitor id, no fingerprint, no session spanning days
+> or tabs, and **nothing is written to the visitor's device** — no cookie, no
+> local storage. The `visit` key lives in memory and dies with the document, so
+> it identifies one page load rather than a person. A `page_view` carries the
+> path; two booleans about the page load — `first_of_load` on the view that
+> opened the document, and `continues` when the load came from one of your own
+> pages; and — captured once when the page first loads, then replayed on each
+> view — the external referrer and any `utm_*` the visitor arrived with. Nothing
+> else. **Both booleans describe the load, never the visitor**, and neither links
+> two loads to each other.
+
+### ⛔ Use kit. Never touch the `uniweb` global
+
+Everything above reaches the runtime through `@uniweb/kit` or through something
+handed to your component as a prop. That is the rule, not a stylistic preference:
+
+- ✅ `useWebsite()`, `useTracker()`, `isSearchEnabled()` and the other service
+  predicates, `resolveService(website, …)` — kit hooks and utilities.
+- ✅ `block.track(…)`, `block.page`, `block.website` — the block **arrives in your
+  props**, so calling methods on it is not reaching for a global.
+- ⛔ `globalThis.uniweb`, `window.uniweb` — never, in a foundation.
+
+The singleton is framework internals: its shape is not part of the contract with
+foundations, and code that reads it directly breaks on changes that were never
+breaking changes. If you need something kit does not expose yet, that is worth
+reporting — not worth reaching around.
+
+<!-- template:loom -->
+### Content handlers
+
+Content handlers are a transform layer between data assembly and the component, declared in `main.js` and applied to every section in the foundation. The standard content shape is the default; handlers reshape it. All three are optional, run per block, and are error-isolated — a failing handler logs a warning and falls back to default behavior.
+
+| Handler | When it runs | Receives | Returns | Purpose |
+|---|---|---|---|---|
+| `data` | After data assembly, before content transform | `(data, block)` | New data object, or null | Filter, reshape, or augment assembled data |
+| `content` | After the data handler | `(data, block)` | ProseMirror document, or null | Transform raw content (Loom instantiation, template expansion) |
+| `props` | After parsing, defaults, and guarantees | `(content, params, block)` | `{ content, params }`, or null | Post-process the final shape before the component sees it |
+
+The `content` handler receives `block.parsedContent.data` — the section's declared keys, its foundation's `main.js` `data:` included, so **declare there every key a handler reads** — and reads raw ProseMirror from `block.rawContent`, returning a new ProseMirror document that the framework re-parses through the semantic parser. Returning `null` — or the same reference as `block.rawContent` — signals no change. Anything that is not a document is ignored, with a warning once per handler: the first argument is the section's *data*, so a pass-through `(x) => x` returns the data, not the content.
+
+> **`block.rawContent` may or may not be wrapped.** Unwrap it defensively — `const doc = block.rawContent?.doc ?? block.rawContent` — before passing it to `instantiateContent` / `instantiateRepeated`. This is the first thing a hand-written handler gets wrong.
+
+**Loom integration** is the most common use: resolving `{placeholder}` expressions against live data. `@uniweb/loom` provides a factory:
+
+```js
+import { createLoomHandlers } from '@uniweb/loom'
+
+export default {
+  handlers: createLoomHandlers({ vars: (data) => data?.profile?.[0] }),
+}
+```
+
+`vars` extracts the Loom variable namespace. The returned `content` handler reads the `source` and `where` frontmatter params: without `source` it does simple substitution; with `source` it splits the markdown at `---` dividers and repeats the body per data item. `where` filters the source array first — `type = 'book'` (equality), `year > 1870` (comparison), `refereed` (truthy), `type = 'book' AND refereed` (combination). Aggregates like `{COUNT OF publications}` reflect the filtered set.
+
+For cases the factory doesn't cover, write handlers directly using `Loom`, `instantiateContent`, and `instantiateRepeated` from `@uniweb/loom`.
+
+> **`instantiateContent` resolves `{placeholders}` in text nodes only** — not in link `href`s or other node/mark attributes. So `[{email}](mailto:{email})` fills the visible label but leaves the `mailto:` URL literal. For dynamic URLs, emit the value as plain text and let the component linkify it, or build the href in the handler yourself.
+
+**`source` and `where` are ordinary params** that the Loom handler reads — they reach both `block.properties` (for handler access) and `params` (visible to components). Components can ignore them. List them in `meta.js` params with descriptions so the editor and schema recognize them. (Unlike `theme` and `background`, which are the section's own settings and never reach `params` — see the table under *Frontmatter becomes `params`*.)
+<!-- /template:loom -->
+
+---
+
+## 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 **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
+the normal case, and a foundation that assumes one breaks on every other site it is
+used with.
+
+```bash
+npm install @uniweb/api      # in the FOUNDATION, beside @uniweb/kit
+```
+
+### Ask before you draw
+
+```jsx
+import { isBackendEnabled } from '@uniweb/kit'
+import { useSession, SignedIn, SignedOut } from '@uniweb/api'
+
+if (!isBackendEnabled()) return <StaticVersion />   // synchronous — nothing to await
+```
+
+⛔ **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
+component that never needed one.
+
+### Reading
+
+```jsx
+const { status, records } = useRecords({ schema: '@/track' })   // summaries: record.brief, no items
+const { entity } = useEntity({ schema: '@/track', uuid: record.uuid })
+const sessions = entity?.hydrated?.items.filter((item) => item.section === 'sessions')
+```
+
+⛔ **A listed record is a summary, not the entity.** `record.brief` holds the brief
+section's fields (`record.brief.name`, not `record.name`), and a record carries **no
+items**. Read one entity for its items. Each item carries `section`, its section's name
+(the word a write takes), and `id`, which is what the writer takes to update, move or
+remove it. `scope: 'mine'` lists only the viewer's own records; without it, a list also
+holds what was shared with the viewer.
+
+⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
+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.
+
+### Writing
+
+```jsx
+const writer = useEntityWriter({ schema: '@/track', uuid: track.uuid })
+
+await writer.create({ title: 'Keynote' }, { section: 'sessions', position: 'last' })
+await writer.update(itemId, { ...item.data, room: 'Hall A' })   // whole-data replace
+await writer.move(itemId, { after: previousItemId })            // never an index
+await writer.remove(itemId)
+```
+
+- **`section` is required on `create`.** An entity has several, and a rule declared on
+  one — insert-only, say — does not reach an item that landed in another. Getting it
+  wrong stores the item happily and quietly voids the rule.
+- **`update` replaces the item's data whole.** Spread what you are not editing.
+- **Ordering is the server's.** Say `'first'`, `'last'` or `{ after }` — never compute
+  an order number, or two people arranging one list will produce an order neither
+  chose.
+- ⛔ **`writer.conflict` is reported, not retried.** Someone else changed the item
+  first; a retry would succeed by overwriting a change nobody looked at. Tell the
+  person.
+
+### ⛔ Permissions are the SERVER'S, and your UI is only a courtesy
+
+Gate your controls on what the viewer may do — a record's own `can_edit` from a
+single-entity read — but **never rely on that for safety**. A foundation runs with
+exactly the viewer's own authority, so hiding a button hides a button. ⛔ **Not on
+`viewer.roles`:** a session signed in on a site holds a member's rights — the operator's
+too — so its roles never name an administrator, and a gate on `system_admin` shows the
+operator nothing.
+
+What protects content is the **entry**: a member writes their own entries and not
+another's, and the store enforces it. **Models are open** — anyone signed in may
+create entries of any Model, so a data schema does not restrict who creates
+(`creatable_by` is retired and refused). What a schema can protect is how an item
+changes:
+
+```yaml
+# foundation/schemas/attendance.yml
+sections:
+  checkins:
+    many: true
+    append_only: true          # may be added; never edited or removed, by anyone
+```
+
+`append_only` holds against the item's own author. That is the difference between a
+permission model and a CSS one.
+
+### The Admin link
+
+```jsx
+const { adminHref } = useSession()
+{adminHref && <a href={adminHref}>Admin</a>}
+```
+
+`adminHref` is set only for a signed-in account the backend's administration admits —
+the operator, and whoever else administers it — and is `null` for everyone else. It
+takes them there already signed in. ⛔ **Navigate to it, never `fetch` it**: the answer is
+a redirect carrying a one-time credential no script on the site is to hold. It decides
+what to offer, not what is allowed — on the site the operator acts as a member.
+
+### The links the backend mails
+
+A sign-up's confirmation, a password reset and an invitation to an address with no
+account all arrive as a link to the site's root, a token in the query — `?verify=`,
+`?reset=`, `?offer=` — and the page it lands on finishes the step:
+
+```jsx
+const { step, status, result, error, confirm } = useMailedLink()
+// step: null | 'verify' | 'reset' | 'offer'     status: 'idle' | 'working' | 'done' | 'error'
+```
+
+- `verify` finishes by itself; then the member signs in.
+- `reset` waits for `confirm({ new_password })`, and the hook supplies the token. A
+  password the rule refuses is `error.extensions.reason === 'password_too_short'`, and
+  the same link works again.
+- `offer` waits for a sign-in, then claims by itself. `result` is counts,
+  `{ invitations, grants }`, never names. ⛔ `error.kind === 'absent'` means unknown,
+  revoked or already used, alike: one sentence, no cause. It does not mean "no
+  invitation": a member who confirmed the invited address already holds it.
+
+Render it where the root renders it — a header or a layout is on every page. ⛔ Never
+copy the token anywhere: it is a credential, it stays in the URL until the backend has
+judged it, and then the hook takes it off.
+
+### Invitations
+
+An invitation to join an organization waits for the member's answer, whether it was
+sent to their account or taken up from an `?offer=` link:
+
+```jsx
+const { status, invitations, accept, decline, answering } = useInvitations()
+// invitations: [{ id, unit_uuid, unit_handle, unit_name, invited_by_account_id, created_at }]
+```
+
+Draw it wherever a signed-in member lands, not only after a mailed link — an invitation
+sent to an account comes with no link to follow. `unit_name` may be `null`.
+`accept(id)` and `decline(id)` answer one, and the list reads again. One that no longer
+waits — answered in another tab, or withdrawn — is refused with `kind: 'rule'` and
+leaves the list; its `detail` is for people, so branch on `kind`.
+
+### A backend on your machine
+
+You do not need a live backend to build against one. In `site.yml`:
+
+```yaml
+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
+// site/mock/api.js
+import { createMockBackend } from '@uniweb/api/mock'
+export default createMockBackend({ seed }).fetch
+```
+
+`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. The mail it would send is printed in the dev
+server's terminal, its link on your site's root — follow it to try your page. Seed
+`offers: [{ email, invitations: 1 }]` to try an invitation: mailed to an address no
+account holds, or waiting at once for the seeded account whose address it is. State is
+in memory; restart to reset.
+
+`uniweb create my-event --template conference` is a worked example of all of this.
+
+---
+
+## Part 5 — Commands, shipping, and migration
+
+```bash
+uniweb dev                        # Start dev server (picks the site for you)
+pnpm build / pnpm preview         # Build for production / preview the build (SSG + SPA)
+
+uniweb deploy                     # Wizard: pick a destination, then deploy (or set up CI)
+uniweb deploy --host=<adapter>    # Build + upload now, from this machine
+uniweb add ci --host=<adapter>    # CI so every push deploys — usually best for a free host
+uniweb export                     # Build dist/ for any static host (no Uniweb account)
+uniweb publish                    # Ship to Uniweb hosting, foundation included (needs `uniweb login`)
+
+uniweb add ci --target foundation # Publish a foundation for free at permanent versioned URLs
+                                  # (GitHub Pages → foundations/<name>/<version>/entry.js)
+
+uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+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 (--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
+
+uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whole workspace
+uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
+uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
+
+uniweb -v                         # Installed CLI version — and whether a newer one exists
+uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
+uniweb validate                   # Check file-based data against declared schemas (fails on a violation; --lax)
+npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
+                                  #   bare `uniweb update` aligns to the CLI you ALREADY have
+uniweb inspect <path>             # Show parsed content for a section or page (--raw for the AST)
+uniweb snapshot                   # Compose site/public/preview.webp from the site; sets preview: if unset
+                                  #   needs `pnpm add -D -w @uniweb/snapshot` and Chrome or Edge
+uniweb snapshot --compare         # Several looks on one sheet; take one with its flags + --save (site/snapshot.yml)
+
+uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
+```
+
+**Three verbs dispatch but are deliberately not listed above.** `invite`, `handoff` and `template` are **reserved names with no implementation** — the flows they named ran against a backend the CLI no longer talks to, and the names are held so a future rebuild doesn't need a breaking change. Running any of them is not useful; their absence from this list is the answer, not an omission to fix.
+
+### Where a site can live
+
+**There is no lock-in, and no default you're pushed toward.** Four independent paths, and a project can change its mind:
+
+| Path | Command | Good for |
+|---|---|---|
+| Free static host, via CI | `uniweb add ci --host=<adapter>` | most self-hosted sites — one command, then every push deploys |
+| Free static host, from this machine | `uniweb deploy --host=<adapter>` | one-off or manual deploys |
+| Any static host at all | `uniweb export` | full control; no Uniweb account needed |
+| Uniweb Cloud | `uniweb publish` | teams with non-technical content authors, or client work |
+
+`uniweb deploy` never assumes a host: with nothing configured it opens a picker listing only destinations it can act on, and records the choice in `deploy.yml` so later runs go straight there. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews that comment the URL. Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. That record is `deploy.yml`, beside `site.yml` — **the CLI writes it, you don't create it**: the first successful deploy scaffolds the whole file, and later deploys rewrite only its `deploys:` block. Edit `targets:` when you want to change where a site ships. Host credentials come from the environment, never from that committed file.
+
+Foundations have their own free path too: `uniweb add ci --target foundation` publishes to permanent versioned URLs on GitHub Pages.
+
+### Uniweb Cloud and the two-sided workflow
+
+`uniweb publish` ships to Uniweb Cloud, and it's worth understanding what that buys, because it isn't only hosting — it's how a team of technical and non-technical people works on one site.
+
+**Content authors work visually in the Uniweb App.** They compose the same extended markdown and set the same component params you defined, through a visual editor — never touching code, git, or the CLI. They see exactly the section types your foundation offers and exactly the knobs each one exposes, because **every `meta.js` is registered as the foundation's schema** when you publish. Your `meta.js` is the app's UI (see *meta.js* in Part 4).
+
+> ⚠️ **Every push, pull and publish works in ONE workspace — the one chosen at `uniweb login`.**
+> A workspace is your personal one or an organization's. A site a push or publish **creates** is
+> created — owned, and its storage billed — there, and there is no CLI command to move it
+> afterwards. A site the backend keeps in **another** workspace stops the command, which says how
+> to switch. With no organization, the login works in your personal workspace; with
+> organizations, the login asks, or you name it:
+>
+> ```bash
+> uniweb login --org @acme      # work in an organization
+> uniweb login --personal       # work in your personal workspace
+> uniweb push --org @acme       # this command only
+> ```
+>
+> Already logged in, `uniweb login --org @other` (or `--personal`) switches the workspace on the
+> backend you are logged in to, without logging in again. **Without a
+> terminal — you, an agent — a login with organizations and no workspace named signs you in but
+> exits 2**: `uniweb login --org @acme` (or `--personal`) finishes it without signing in again.
+> Until then every command that works on a site refuses, and so does registering a foundation whose
+> name has no scope. A process logged in with `UNIWEB_TOKEN` names its workspace with
+> `UNIWEB_WORKSPACE=@acme` (or `personal`). **Ask the human which workspace to use** rather than
+> picking for them — a site created in the wrong one cannot be moved from here.
+>
+> Relatedly: these commands now **reject flags they do not recognize** instead of ignoring them.
+> If you get `Unknown flag`, read the suggestion — it is usually a near miss.
+
+**Sync is developer-only and one-sided by design.** `uniweb push` and `uniweb pull` are your commands, not theirs:
+
+- **The app is the live source of truth for content** — where authors work and where your push lands live.
+- **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
+- **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
+
+**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 --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:
+
+```yaml
+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
+  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; 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 --server <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
+
+### Staying current
+
+```bash
+uniweb -v                  # installed CLI version, and whether a newer one is available
+uniweb doctor              # report drift in this project, changing nothing
+npx uniweb@latest update --dry-run   # preview exactly what update would change
+npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
+```
+
+**`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
+
+**What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so read those before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.
+
+> ### ⛔ WRITE `@latest`. A BARE `uniweb update` IS USUALLY A NO-OP, AND IT SAYS SO CONVINCINGLY
+>
+> `update` reconciles this project against **the matrix of the CLI that runs it** — and in a project,
+> `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`. That
+> copy has no way to know a newer release exists.
+>
+> ⇒ **It reports everything aligned and changes nothing — correctly.** It answered the question it
+> was asked, which is why the output looks like success rather than a mistake. The same applies to
+> `pnpm uniweb update` and to a stale global install.
+>
+> ⭐ **`@latest` is what makes it a question about the newest release** rather than about the one you
+> already have. It also bumps the pin, so the next bare invocation is no longer stale.
+
+> **Don't run `npm update` or `pnpm update` on the `@uniweb/*` packages.** They're a matched set resolved by the CLI's version matrix, not independently versioned libraries you upgrade one at a time. Updating them directly gets you a combination nobody tested, and it won't refresh AGENTS.md — so this guide silently drifts out of sync with the code it describes, which is worse than being out of date, because nothing looks wrong.
+
+Two ordering rules: `update` won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed — either would put the doc ahead of the code. And updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`); `uniweb update` does not do that.
+
+### `package.json` `uniweb` block
+
+Platform-specific configuration that doesn't belong in npm-standard fields. All fields optional.
+
+| Field | Where used | Default | Purpose |
+|---|---|---|---|
+| `runtimePolicy` | `dist/runtime-pin.json` | unset | Declares how far past the recorded runtime version a host may move a site. |
+
+**The foundation's name is not here — it is `name` in `main.js`** (else `package.json`'s `name`), **and so is the scope it registers under: the scope is part of the name**, `name: '@acme/marketing'`. A scope is a namespace — your personal one, `@<your handle>`, which needs no org, or an org's. A name with no scope has not been registered yet: the first `uniweb register` takes `--scope`, else the workspace you work in — an org's scope, or your personal one; when you belong to orgs and chose no workspace, it asks at a terminal and refuses without one — and writes it into the name; a `--scope` naming another scope than the name's is refused. The foundation's own data schemas register under the same scope (`@/article` → `@acme/article`). ⛔ `uniweb.id` and `uniweb.scope` are no longer read for a foundation: `uniweb register` refuses them and prints the `main.js` line to write instead. (A schemas-only package has no `main.js`, and still records its scope in `uniweb.scope`.)
+
+**Runtime updates — handled for you.** Your foundation's code links against the runtime: it externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, and the runtime supplies all of them at load time. So a build is bound to *that* React and *that* core API.
+
+You don't declare anything for this. At build time your foundation records the `@uniweb/runtime` version it actually linked against (read from `node_modules`, not chosen) into `dist/runtime-pin.json`, and `uniweb register` sends it with your foundation, so the version you built against travels with it. **Whether two runtime versions are compatible is our determination, not a setting** — you have no way to know whether we changed anything your code can reach, so we don't ask you to guess.
+
+⚠️ **Nothing acts on the recorded version yet** — today it is stated and carried, not enforced. Don't design around it having an effect.
+
+**The escape hatch,** for the one thing only you can know: if your foundation reaches into undocumented runtime internals, or you have audited it against exactly one runtime build and want no movement at all, set
+
+```json
+{ "uniweb": { "runtimePolicy": "exact" } }
+```
+
+That freezes sites using your foundation on the recorded version. Only reach for it if one of those two things is actually true — a frozen foundation stops receiving runtime fixes, including security ones. Sites cannot override your choice.
+
+> Older releases documented `auto-patch` and `auto-minor` here as well. They asked you to pick a compatibility rule out of our version numbers, which was never something you were in a position to evaluate — that determination is ours. Both values are still accepted so existing foundations keep working; neither is worth setting.
+
+`@uniweb/runtime` arrives **transitively** through `@uniweb/build`, so your foundation pins a runtime version without declaring one — that's intentional. **Don't add `@uniweb/runtime` to your foundation's dependencies**; to bump the pinned version, bump `@uniweb/build`. If `@uniweb/runtime` isn't resolvable at build time the pin is simply not emitted, and the build still succeeds — nothing in the toolchain requires it.
+
+### Localization
+
+**Content reaches components already translated.** There is no `t()`, no runtime lookup, no string wrapping — each language is a complete static build with its own HTML, `hreflang` tags, and search index. The default language has no URL prefix (`/about`); others are prefixed (`/es/about`).
+
+**Translations live in `locales/`, a sibling of `pages/` at the site root — never inside `pages/`.** The markdown under `pages/` is one language: the default.
+
+```yaml
+# site.yml
+defaultLanguage: en
+languages: [en, es, fr]        # codes only — a language's name comes from its code;
+                               # or '*' to auto-discover from the locales/ folder
+publishLanguages: [en, es]     # optional — fr stays a dev-previewable draft,
+                               # excluded from production output entirely
+```
+
+```bash
+uniweb build                   # FIRST — extract scans built content, not source
+uniweb i18n extract            # → locales/manifest.json, keyed by 8-char content hash
+uniweb i18n init es fr         # → locales/es.json, locales/fr.json, pre-filled with source
+#  …translate the values…
+uniweb build                   # merges translations, emits dist/es/, dist/fr/
+```
+
+Running `extract` before a build is the usual first mistake — it reads the compiled content, so a stale build yields a stale manifest. After content changes, `uniweb i18n sync` updates the manifest and `init` refreshes the language files; `status` and `audit` report coverage and stale entries.
+
+**A value is inline Markdown.** A sentence's links and bold go into its translation — `"Voir [Rôles](page:docs/roles)."` — or it renders without them, and coverage still counts it; `uniweb i18n status` lists these under *Loses markup*. A **button** — a line that is only a link — is the exception: translate its label alone and it keeps its link and options (`{role=primary}`). Buttons on consecutive lines are one string; give one label per line (`"Créer un groupe\nEn savoir plus"`).
+
+**Two mechanisms.** *Hash-based strings* (the default) — `locales/{locale}.json` maps content hash → translation, so structure stays identical across languages. When one source string needs different translations depending on where it appears, the value takes an override form:
+
+```json
+{ "e5f6g7h8": { "default": "Learn More", "overrides": { "/pricing:cta": "See Pricing" } } }
+```
+
+An override key is the page's route and the section's id (`cta` for `2-cta.md`); a page's own title, label, description and keywords are `/pricing:_meta`, and in `locales/records/` a record is named by its manifest context (`std/article/launch`).
+
+*Free-form bodies* — when a language needs different structure, different images, or copy rewritten rather than translated. The file replaces one section's content:
+
+```
+locales/freeform/es/pages/about/hero.md        # by page route
+locales/freeform/es/records/article/x.md       # records work too
+```
+
+These are **body only — no frontmatter**; params and config still come from the source section. `uniweb i18n init-freeform es pages/about hero` creates one pre-filled and records a source hash, so `uniweb i18n status --freeform` can tell you when the original moved on (`update-hash` to acknowledge). `move`, `rename`, and `prune --freeform` keep them aligned when pages get reorganized.
+
+**A tagged data block translates by the shape its key declares** in the component's `meta.js` `data:` — a data schema or an inline field map: its text fields, never an enum, a URL or a `translatable: false` field. A key declared `{}` leaves its blocks to a heuristic that offers any string whose field name and value don't look structural, so a `style: display-black` naming one of your component's looks gets translated too. Declare the shape of every block a translator will see — `{ name: 'string', style: { type: 'string', enum: [...] } }`.
+
+**Records translate in the same `extract` run**, into their own manifest at `locales/records/manifest.json` — keyed by the RECORD, so a record translated once is found by every query that returns it. A record whose query has a data schema translates exactly the fields the schema says are text — never an enum, a URL, a date, a number, a file, a reference or a `translatable: false` field — which are the fields a push carries in each language; mark a string that is a code or a key `translatable: false` and no translator is asked for it. An excerpt the build derives is re-derived from each language's body.
+
+**Component side.** Nothing to do: `content.title` arrives in the active language. The one thing a foundation builds is a switcher.
+
+```jsx
+import { useWebsite, Link, getLocaleLabel } from '@uniweb/kit'
+
+function LanguageSwitcher() {
+  const { website } = useWebsite()
+  if (!website.hasMultipleLocales()) return null
+
+  return website.getLocales().map(locale => (
+    <Link reload key={locale.code} href={website.getLocaleUrl(locale.code)}>
+      {getLocaleLabel(locale)}
+    </Link>
+  ))
+}
+```
+
+> **Use `<Link reload>` — not a plain `<a>`, and not `window.location.href`.** `getLocaleUrl()` returns a root-relative path that does **not** include the deployment base path, so under a subdirectory deploy (`base: /docs/` in `site.yml`) a raw href sends the visitor outside the site. `<Link reload>` prepends `website.basePath` and forces the full page load a locale switch requires — an SPA `<Link>` won't do, because the other language is a different build.
+
+Full model: `development/internationalization.md`. Author's view: `authoring/translating.md`.
+
+### Migrating from other frameworks
+
+Don't port line-by-line. Study the source, then rebuild from first principles. Other frameworks produce far more components than Uniweb needs — expect consolidation, not 1:1 correspondence.
+
+| React / conventional | Uniweb equivalent |
+|---|---|
+| Props with typed data | Frontmatter params + `meta.js` |
+| Component variants via props | `variant` param; Front Desk pattern for complex routing |
+| Context / ThemeProvider | `theme:` frontmatter + semantic tokens (automatic) |
+| Wrapper/layout components | Section nesting or custom layouts |
+| Prop-drilling visuals into containers | Insets — `![](@Component)` rendered via `<Visual>` |
+| Content in JSX or `.js` data files | Markdown → parser → `content` prop |
+| CSS color tokens / design systems | `theme.yml` → palette shades + semantic tokens |
+| `isDark ? … : …` conditionals | `text-heading` — context classes handle it |
+| Per-component backgrounds | `background:` in frontmatter |
+| Multiple near-identical components | One section type + `variant` param, or Front Desk |
+| i18n wrapping (`t()` / `<Trans>`) | Locale-specific content directories |
+
+**Approach:** scaffold with `--template none` → use named layouts for different page groups → dump legacy components under `components/` (they're not section types; import them from section types during transition) → create section types one at a time.
+
+**It's incremental, not a rewrite.** Level **0** — paste the original as one section type; routing and dev tooling work immediately, and you have a running site. Level **1** — decompose into section types, consolidating duplicates via `variant` params or Front Desk. Level **2** — move content from JSX to markdown, so authors can edit without code. Level **3** — replace hardcoded colors with semantic tokens, so components work in any context. Each level is shippable; stopping at 1 is a legitimate outcome.
+
+**The most common mistake** is recreating source colors as CSS custom properties — that bypasses the token system. Instead: primary color → `colors.primary` in `theme.yml`, neutral tone → `colors.neutral`, context needs → `theme:` frontmatter.
+
+Also: name by purpose, not content (`TheModel` → `SplitContent`, `WorkModes` → `FeatureColumns`), and put UI helpers (buttons, badges, cards) in `components/` with no `meta.js`.
+
+Full guide: `development/converting-existing.md`.
+
+---
+
+## Part 6 — Troubleshooting
+
+Most Uniweb failures are **silent** — the build succeeds and the page is wrong. Check these first, because nothing in the terminal will point you at them.
+
+**A red `Component not found: <Type>` box where a section should be** — the `type:` in that section's frontmatter names a section type this foundation doesn't have. `ls <foundation>/sections/` for the real list. The build does not fail on this, so it only surfaces by looking at the page.
+
+**A param has no effect** — it isn't declared in that section type's `meta.js` `params:`. Undeclared frontmatter is passed through and ignored rather than rejected. Read the `meta.js` for the real knobs; if the one you want doesn't exist, exposing it is a foundation change.
+
+**A section doesn't appear at all** — the file is `@`-prefixed (a child section, only rendered via `nest:`), or `_`-prefixed (treated as a draft and skipped), or it's a section type nested below the root of `sections/` without a `meta.js`, which means it was never discovered.
+
+**Content lands in the wrong field** — a heading became a `subtitle` when you wanted an item, or the reverse. That's the step rule (one step smaller and adjacent = the next headline line; two steps, a divider, or any body content first = items). Run `uniweb inspect <path>` rather than re-deriving it.
+
+**A var in frontmatter does nothing** — component vars only apply when declared in that section type's `meta.js` `vars:`. Unknown names are ignored silently.
+
+Loud failures:
+
+**"Could not load foundation"** — check that the site's `package.json` depends on the foundation *by its workspace package name*. For the default layout that's `"src": "file:../src"`; for a co-located project (`docs/src` + `docs/site`) it's `"docs-src": "file:../src"`. The key must match the foundation's `package.json::name`, not the folder it happens to sit in.
+
+**Component not appearing** — verify `meta.js` exists; check for `hidden: true`; rebuild the foundation.
+
+**Styles not applying** — verify `@source` in `styles.css` includes your component paths.
+
+**Prerender warnings about hooks** — components with `useState`/`useEffect` show SSG warnings during build in local symlinked mode. Expected and harmless.
+
+**"document is not defined" during build** — your component touches `document`, `window`, or `localStorage` during render rather than inside `useEffect`. **Don't add `typeof document` guards** — use the kit hook instead: dark mode → `useAppearance()`, scroll detection → `useScrolled()`. Kit hooks are SSR-safe by design.
+
+**A modal renders behind the page** — page content or a sidebar paints over your dialog and its backdrop, and raising the z-index changes nothing. Each layout area carries a `view-transition-name`, which makes it a stacking context your `fixed` element cannot escape. Render through `<Overlay>` from `@uniweb/kit` (see Part 4) instead of a bare `fixed inset-0 z-…` div.
+
+**Content not parsing as expected** — `uniweb inspect pages/home/hero.md` (add `--raw` for the ProseMirror AST), or point it at a folder for a whole page.
+
+---
+
+## Documentation index
+
+**Index of every page: https://www.uniweb.io/llms.txt** — start there when you don't know which page you need.
+
+Source repo (public, cloneable): **https://github.com/uniweb/docs** · any page as raw markdown at `https://raw.githubusercontent.com/uniweb/docs/main/{section}/{page}.md`. See *Documentation* in Part 0 for when to fetch versus clone.
+
+| Section | Covers |
+|---------|--------|
+| `architecture/` | Component Content Architecture — the why behind the patterns in this file |
+| `getting-started/` | What is Uniweb, quickstart, templates |
+| `authoring/` | Writing content, site setup, records, theming, translations, predicates |
+| `development/` | Foundations, component patterns, project structures, data, layouts, i18n, migration, schemas |
+| `reference/` | site.yml, page.yml, content structure, meta.js, kit API, navigation, records, queries, data fetching, parametric pages, CLI, deployment |
+
+The by-task table is in Part 0. For CLI flags, prefer `uniweb <command> --help` over this file — it's always current.
+
+## Notes about this project
+
+Conventions, decisions, where things are — keep them in a file of your own (`NOTES.md`, say). `uniweb update` rewrites this file for each new version, and the one part it keeps is a block between `<!-- project-notes:start -->` and `<!-- project-notes:end -->`, each on a line of its own, which it moves to the end of the file. That block is the place for a line pointing to your notes, or for short notes themselves.