barakopress 0.4.0 → 0.8.0

package/README.md

@@ -83,7 +83,7 @@ decision, not the engine's.
 
 | Create | Export | From |
 | --- | --- | --- |
-| `app/page.tsx` | `default` | `createBlogIndex(config)` |
+| `app/page.tsx` | `default`, `generateMetadata` | `createHome(config, blocks)`, `createHomeMetadata(config)` |
 | `app/blog/[slug]/page.tsx` | `default`, `generateMetadata` | `createBlogPost(config)`, `createPostMetadata(config)` |
 | `app/authors/[slug]/page.tsx` | `default` | `createArchive(config, "author")` |
 | `app/categories/[slug]/page.tsx` | `default` | `createArchive(config, "category")` |
@@ -94,11 +94,16 @@ decision, not the engine's.
 | `app/[...path]/page.tsx` | `default`, `generateMetadata` | `createPage(config, blocks)`, `createPageMetadata(config)` |
 | `app/doctors/page.tsx` | `default` | `createCollectionIndex(config, "doctors")` |
 | `app/doctors/[slug]/page.tsx` | `default`, `generateMetadata`, `generateStaticParams` | `createCollectionDetail(config, "doctors")`, `createCollectionMetadata(config, "doctors")`, `createCollectionStaticParams(config, "doctors")` |
-| `app/api/blocks/route.ts` | `GET`, `OPTIONS` | `createBlockSchemaRoute(blocks)`, `createBlockSchemaPreflight()` |
+| `app/api/blocks/route.ts` | `GET`, `OPTIONS` | `createBlockSchemaRoute(config, blocks)`, `createBlockSchemaPreflight()` |
+| `app/api/blocks/bindings/route.ts` | `GET`, `OPTIONS` | `createBindingReportRoute(config, blocks)`, `createBindingReportPreflight()` |
 | `app/layout.tsx` | `default`, `generateMetadata` | `createSiteLayout(config, { blocks })`, `createSiteMetadata(config)` |
-| `app/%5Fshare/route.ts` | `GET` | `createSharePage()` |
+| `app/%5Fshare/route.ts` | `GET` | `createSharePage(config)` |
 | `app/api/share/redeem/route.ts` | `POST` | `createShareRedeemRoute(config)` |
 
+`createHome` serves whatever the tenant picked for `/`: the page at `HomePath`, the index of
+`HomeCollection`, or the post index when it picked neither, which is what `createBlogIndex` did and
+still does for a site that mounts that instead.
+
 Mount only what you want. Nothing requires anything else. The paths only have to agree with the
 `routes` in your config, which is what every generated link is built from.
 
@@ -107,6 +112,27 @@ It reads `searchParams`, which forces the route dynamic, so a site using `output
 `createBlogPost` and gives up preview. `createPostStaticParams` and `createArchiveStaticParams` exist
 for that static case.
 
+A site that draws its own post page keeps preview by giving the detail route its own view, and maps
+the item with the engine's own mapping:
+
+```tsx
+export default createCollectionDetail(config, POST_COLLECTION, {
+  preview: true,
+  view: ({ config, item, preview }) => <MyPost post={postFromItem(config, item)} preview={preview} />,
+});
+```
+
+The binding report says why a binding on a page did not resolve, so an editor fixes it in barakoBrew
+instead of asking whoever can read the server log. Ask for one page at a time, by `?slug=` or
+`?path=`, and each problem names the binding as typed, the reason (`unknown scope`, `unbound scope`
+or `no value`), and the block and field it came from. It reports the page as rendered, not as
+stored, so a `{{item.X}}` outside a repeat is reported as an unbound scope. Give it the same `query`
+option the page route has: off, which is the default, a `{{query.X}}` is an unbound scope for every
+visitor and the report says so, and a report that resolved one anyway would tell an editor a field
+works where it does not. It is never anonymous:
+the caller presents the tenant's key as `Authorization: Bearer`, derived from `PRESS_SECRET` and
+printed by `barakopress bindings-key <tenant>`. Answers are never cached.
+
 `Card` and `PostView` are exported too, for a site that wants its own page but the engine's markup.
 
 ### Collections: any content type as a list and a detail page
@@ -144,20 +170,26 @@ merged over the configured collections by key. A build-time site passes `collect
 | --- | --- |
 | `type` | The content type. Required |
 | `route` | The index is served at the route and an item at `route/slug`. Absent, items are listed and never linked |
-| `fields` | `title` (required), `slug`, `summary`, `body` (markdown), `date`, `image`, `imageAlt`, `featured`, `tags`, `url`. Each is a field name or a list tried in order; `@createdAt` and `@updatedAt` read the entry itself |
+| `fields` | `title` (required), `slug`, `summary`, `body` (markdown), `date`, `image`, `imageAlt`, `featured`, `tags`, `url`, `photo`, `progress`, `progressCount`, `progressTotal`, `href`. Each is a field name or a list tried in order; `@createdAt` and `@updatedAt` read the entry itself. `photo` is a portrait drawn above the title, `image` the wide one, and `progress` is a number from 0 to 100 that `progressList` draws. `progressCount` and `progressTotal` draw the same bar from two counts instead, for a source that gives those rather than a figure already worked out; `progress` wins when both are set. `href` is where a card links when that is not the item's own route: a collection filled by a sync usually carries the source's own URL and has no route on this site |
 | `references` | Reference fields, each naming the collection it points into and the word a card puts before the link. Resolved in the same request |
 | `sort` | Sent to the API, for example `-PublishedAt` |
 | `feed` | Whether `createFeed(config, key)` serves it |
-| `sitemap` | On unless `false` |
-| `index` | Whether the root catch-all serves an index at the route. On unless `false`; the derived `author` and `category` have it off, so `/authors` stays a 404 unless a route file mounts it |
+| `sitemap` | On unless `false`. A collection is paged to `pageSizes.sitemap` entries; the file stops at the standard's 50,000 URLs and says so in the log |
+| `index` | Whether the root catch-all serves an index at the route. On unless `false`; the derived `author` and `category` have it off, so `/authors` stays a 404 unless a route file mounts it. An object is the index's copy, and the index is on. See below |
+| `indexPage` | A site path such as `/site/blog`. The blocks of the page served there are drawn above the list on the index. See below |
+| `defaultAuthor` | The byline name on an entry that names no author, on its card and on its `article` page |
 | `pageSize`, `label`, `noun` | Items on the index, its heading, and how a count reads |
 | `colorBy` | A choice field whose option colours the item. See below |
+| `related` | What an item page lists under the item: `"semantic"` for the items of this collection closest to it by meaning, `false` for none. Unset, the first collection that references this one |
+| `readingTime` | Whether an item page shows a read time worked out from its body. Off unless `true` |
+| `layout` | How an item page is drawn: `"list"`, the shell markup every collection has had, or `"article"`, the reading column the blog's posts are drawn in. See below |
+| `tree` | Set when the collection is a manual rather than a flat list: sections, an order, nesting, products. See below |
 
 A settings entry that does not read as a collection is left out whole: a type or field that is not a
-plain identifier, a route that is not a plain site path, or no title field. The keys `post`, `author`
-and `category` are refused from settings, because the blog factories map posts through `types` and
-`fields`. A build-time collection mounted at `/` throws in `defineConfig`. When two routes match, the
-longer one wins.
+plain identifier, a route that is not a plain site path, or no title field. `post`, `author` and
+`category` are replaceable by key like any other collection, since every read goes through the
+collection's own field map. A build-time collection mounted at `/` throws in `defineConfig`. When two
+routes match, the longer one wins.
 
 A request-time site cannot add a route file per tenant, so the root catch-all from the pages section
 also serves every collection with a route: its index at the route, and an item one segment below. A
@@ -168,22 +200,267 @@ lists its doctors, the way an author's archive lists their posts. `listRelated(c
 department, { via: "Department" })` returns the same list; `listRelated(config, post)` still returns
 related posts by semantic search.
 
+With `related: "semantic"` it lists the items of its own collection nearest it by meaning instead, so
+an agency's case study gets the band a post has. That needs the CMS AI module: without it the search
+answers nothing and the page draws no band at all, which is the same way the post page degrades.
+`listRelatedItems(config, key, item)` returns that list on its own.
+
+**The index's own words.** An editor sets what a collection's index says in the collection's
+settings, rather than a theme writing a route file for it:
+
+```json
+{
+  "blog": {
+    "type": "post", "route": "/blog", "fields": { "title": "Title" },
+    "index": {
+      "eyebrow": "Changelog", "heading": "What shipped",
+      "lede": "Every release, newest first.",
+      "empty": "Nothing shipped yet.", "unavailable": "The changelog is resting. Try again shortly."
+    },
+    "indexPage": "/site/blog",
+    "defaultAuthor": "The barakoCMS team"
+  }
+}
+```
+
+`eyebrow` is a short line above the heading, `heading` replaces `label`, `lede` replaces the site's
+tagline under it, `empty` is what an index with nothing published says, and `unavailable` what one
+whose read failed says, each in place of the `labels` lines that say it otherwise. Every line is
+optional, one of the wrong kind or too long is dropped on its own, and a route file's own `heading`
+still wins. `indexPage` draws a page's blocks above the list, so the index is composed like any page
+and the route stays the collection's. With `defaultAuthor`, an entry whose first reference (the
+byline) did not come back, or a collection with no reference at all, is signed with that name after
+`labels.by`. Set none of the three and the index and the byline draw what they always did.
+
+A page named by `indexPage` only holds data, the way a header or footer region page does: it answers
+404 at its own path and is left out of the menu and the sitemap.
+
 **Filtering.** `listCollection(config, "doctors", { filter: { Department: "cardiology" } })` takes a
 reference field by the target's slug and any other field by the value it holds, a choice field by its
 option. The API takes five filters. `createCollectionIndex(config, key, { filter })` takes the same,
 and the `collection` block has `filterField` and `filterValue`.
 
-**A colour per option.** With `colorBy: "AreaOfFocus"` on a `project` collection, the site settings
-`OptionColors` entry `{ "project.AreaOfFocus": { "Providing clean water": "sky" } }` names a colour
-from `Colors` (a theme slot or a colour written out also works). Each card, item page and collection
-block item carries it as a left border, with the option beside it. A name that does not resolve to
-something readable as a colour is dropped. A build-time site passes `optionColors` with the colours
-written out.
+**A style per option.** With `colorBy: "AreaOfFocus"` on a `project` collection, the site settings
+`OptionStyles` entry says how each option of that field is shown:
+
+```json
+{
+  "OptionStyles": {
+    "project.AreaOfFocus": {
+      "Providing clean water": { "tone": "sky", "icon": "location", "label": "Water" }
+    }
+  }
+}
+```
+
+`tone` names a colour from `Colors`, a theme slot, or a colour written out, and each card, item page
+and collection block item carries it as a left border. `icon` is one of the engine's icon names, and
+`label` is the word a visitor reads in place of the option's own value; the value stays on the element
+as `data-option`, where a site's own CSS can still find it. A tone that does not resolve to something
+readable as a colour is dropped, a label past 40 characters is dropped, and an icon name nothing
+draws draws nothing, each on its own rather than losing the whole entry.
+
+`OptionColors` is the same thing said shorter, `{ "project.AreaOfFocus": { "Providing clean water":
+"sky" } }`, an option whose style is a tone and nothing else. A tenant that saved colours keeps them,
+and a style for the same option wins field by field. A build-time site passes `optionStyles`, or
+`optionColors`, in the same shapes.
 
 `Card` and `ItemView` are exported for a site that wants its own page, and `Card` still takes a `post`.
 `getItem`, `listCollection` and `getGlobals(config)`, the tenant's settings entry as stored, are
 exported too.
 
+**A long-form layout.** `layout: "article"` draws an item as a reading column: a back link, the title
+and standfirst, a byline from the collection's first reference, the date, a read time worked out from
+the body, the other references, the tags, the cover image, the prose and a band of neighbours under
+it. That is the page the blog's posts have always had, and it is a collection setting rather than a
+blog screen, so a law firm's briefings or a newsroom's features get it by asking. Styled inline from
+the theme, so it looks right whether or not the consumer imports `barakopress/styles.css`.
+`PostView` is a wrapper over the same layout and is `@deprecated` for 1.0.0.
+
+**Docs: a collection as a tree.** A manual is a collection plus four fields saying where each page
+sits. `tree` names them, and the settings beside them say what the sidebar and the switcher show:
+
+```json
+{
+  "docs": {
+    "type": "doc", "route": "/docs", "label": "Documentation", "layout": "article",
+    "fields": { "title": "Title", "slug": "Slug", "body": "Body" },
+    "tree": {
+      "section": "Section", "order": "Order", "parent": "Parent", "product": "Product",
+      "sections": ["Getting started", "Guides", "Reference"],
+      "searchPath": "/docs",
+      "editPath": "Source",
+      "editBase": "https://github.com/owner/repo/edit/master/",
+      "products": [
+        { "key": "cms", "label": "barakoCMS", "href": "/docs" },
+        { "key": "press", "label": "barakoPress", "href": "/docs/press" }
+      ]
+    }
+  }
+}
+```
+
+| Key | What |
+| --- | --- |
+| `section` | The field holding the heading a page is grouped under |
+| `order` | The field holding its position in that section. A page with none comes after those with one |
+| `parent` | The field holding the slug of the page it hangs under, or a reference to it. A parent nobody has leaves the page at the top of its section rather than dropping it |
+| `product` | The field naming the product it documents, matched against a product's `key`. One field name and not a list, since this one goes into an API filter |
+| `sections` | The sections in the order the sidebar shows them. One not named here follows those that are. Named rather than worked out, because no ordering of the pages says which section comes first |
+| `products` | What the switcher offers: a key, the word a reader sees, and where it goes. A destination that is not a site path or an http URL is dropped |
+| `searchPath` | Where the search box submits, and whether one is drawn at all. Unset, no box, because only the site knows which of its routes reads the query |
+| `editPath` | The field holding the page's path in whatever repository it is written in. Its slug when unset |
+| `editBase` | Where "edit this page" points, with that path appended. Unset, no such link is drawn |
+| `limit` | The most pages read to build the tree. 500 unless set, and 500 is the ceiling as well as the default |
+| `variant` | How the parts are laid out. See "Styling the tree" below. Every part is today's layout when unset |
+| `searchIndex` | `true` to search the tree's titles and headings in the page as the reader types. The box is drawn whenever this is set; with `searchPath` too, a reader with no script submits there |
+| `icons` | `{ "search": "#id", "chevron": "#id" }`: symbols already on the page (a site's own sprite) for the compact search box's magnifier and the closed disclosure's chevron. A value that is not `#` and a name is dropped, and the engine draws its own |
+
+A product may also carry a `note`, a few words drawn after its label in the list switcher (`"on GitHub"`).
+
+An item page in such a collection draws the sidebar with the page being read marked, the switcher,
+a search box, previous and next from the tree's reading order, and the edit link. The sidebar is a
+`details` element, so it collapses on a phone with no script. `collectionTree(config, key, { product })`
+and `treeNeighbours(order, slug)` return the same tree and the same neighbours for a site's own page.
+
+An item links where the collection's `href` field says it is read, when the collection maps one and it
+is a path on this site, and at its route and slug otherwise: the sidebar, previous and next, the
+in-page index and the sitemap all follow it (`treeItemHref`). An absolute address is not followed. Slugs are unique across a tenant, so a manual whose products each have a
+quickstart keeps `cms-quickstart` as the slug and names `/docs/cms/quickstart` in the field. The route
+serving that path is the site's own. A site drawing the sidebar on a page the tree does not hold, an
+index, gives `TreeAside` or `TreeSidebar` a `summary` (`{ line, title }`) for the closed control to say.
+
+**Search.** `searchCollection(config, key, query)` goes through barakoCMS's `/api/public/{type}/search`,
+which matches only over the fields a type publishes, so a draft or a field held back from public
+delivery can never come back. `createCollectionIndex(config, key, { search: true })` answers `?q=` with
+what matched instead of the index; that reads the query, so the route is dynamic and `output: "export"`
+refuses it, which is why it is off unless asked for. The box is a `form`, the results are links, and
+the keyboard handling on top ("/" to focus, the arrow keys to walk the results, escape to clear) is the
+one client component in the package. The root catch-all answers `?q=` on a collection index too, but
+only where the route may be dynamic: a request-time site rewrites to a kept route, and a kept route
+asking for the query fails rather than bailing out, so there the index lists and a page of blocks
+holding the `search` block is where a reader searches.
+
+Which is why `searchPath` exists rather than the box pointing at the collection's own route. Only the
+site knows which of its routes reads the query, and a box submitting somewhere that ignores `q` sends
+a reader to an unfiltered index that looks like a search which matched everything. Name the route that
+answers, or name nothing and get no box.
+
+**As blocks.** `docsSidebar`, `docsSwitcher` and `search` draw the same three on a page of blocks, each
+taking a collection key. `search` takes a bindable `query`, so a landing page binds `{{query.q}}` and
+the route file passes the query with `createPage(config, blocks, { query: true })`. `docsSwitcher`
+takes a `variant`, `tabs` or `list`, and follows the collection's own when it is left unset.
+
+**Styling the tree.** A site restyles the tree screens without drawing them itself, three ways.
+
+*Tokens.* Every colour, gap, padding, margin, radius, font size, weight and line height in them is read as
+`var(--t-tree-<name>, <today's value>)`. Letter spacing, and the flex bases that decide when a row wraps, are fixed.
+A token named in the tenant's `Tokens` setting (or `theme.tokens`) lands on the root as `--t-<name>`,
+so `"Tokens": { "tree-link-current-bg": "#FDEBD3" }` restyles the current page's row and nothing else.
+A token in the settings is held to a colour, a length or a font stack; a weight or a unitless line
+height is set from the site's stylesheet under the same name (`:root { --t-tree-link-weight: 500 }`).
+A site that names none draws what it drew before, pixel for pixel.
+
+| Token | Default | What |
+| --- | --- | --- |
+| `tree-gap` | `space.lg` | Between the sidebar and the page, `plain` |
+| `tree-shell-width`, `tree-shell-pad-y`, `tree-shell-pad-x` | `layout.wide`, `space.lg`, `layout.gutter` | The shell's width and padding, `plain` |
+| `tree-edge` | `hairline` | The rules between the columns and above them, `boxed` |
+| `tree-min-height` | `0px` | The shell's least height, `boxed` |
+| `tree-sidebar-width` | `280px` | The sidebar column (its most, `plain`; its width, `boxed`) |
+| `tree-sidebar-bg`, `tree-sidebar-pad-y`, `tree-sidebar-pad-x` | `surface`, `space.lg`, `space.md` | The sidebar column, `boxed` |
+| `tree-body-pad-y`, `tree-body-pad-x` | `space.xl`, `space.xl` | The page column, `boxed` |
+| `tree-aside-gap` | `space.md` | Between the switcher, the search box and the sidebar |
+| `tree-section-gap` | `space.md` | Between sections, and between the list switcher and the sections |
+| `tree-label-gap`, `tree-label-size`, `tree-label-ink` | `space.xs`, `text.meta`, `muted` | Section labels, the list switcher's label and the rail's heading. The size is also the search box's label and the phone control's |
+| `tree-summary-bg`, `tree-summary-edge`, `tree-summary-ink`, `tree-summary-radius`, `tree-summary-space`, `tree-summary-pad-y`, `tree-summary-pad-x` | `surface`, `hairline`, `muted`, `radii.control`, `space.sm`, `10px`, `12px` | The sidebar's control on a phone, and the space under it while open |
+| `tree-summary-pad-y`, `tree-summary-pad-x`, `tree-summary-min-height`, `tree-summary-gap`, `tree-summary-line-gap` | `10px`, `12px`, `0px`, `space.sm`, `3px` | The closed disclosure's control |
+| `tree-summary-title-size`, `tree-summary-title-weight`, `tree-summary-title-ink` | `text.small`, `700`, `ink` | The page it names |
+| `tree-summary-action-size`, `tree-summary-action-weight`, `tree-summary-action-ink`, `tree-summary-action-gap`, `tree-summary-icon-size` | `text.small`, `600`, `accentInk`, `6px`, `13px` | Its "Contents" and "Close", and the chevron |
+| `tree-link-gap`, `tree-indent` | `0px`, `space.md` | Between rows, and a child's indent |
+| `tree-link-pad-y`, `tree-link-pad-x`, `tree-link-radius`, `tree-link-size`, `tree-link-leading` | `6px`, `10px`, `radii.control`, `text.small`, `1.45` | A row in the sidebar, and a product in the list switcher |
+| `tree-link-ink`, `tree-link-weight` | `secondaryInk`, `inherit` | A row that is not the page being read |
+| `tree-link-current-bg`, `tree-link-current-ink`, `tree-link-current-weight` | `accentTint`, `accentInk`, `600` | The page (or product) being read |
+| `tree-note-gap`, `tree-note-size`, `tree-note-weight`, `tree-note-ink` | `6px`, `text.meta`, `inherit`, `muted` | A product's note |
+| `tree-tab-gap`, `tree-tab-pad-y`, `tree-tab-pad-x`, `tree-tab-radius`, `tree-tab-size`, `tree-tab-weight` | `space.xs`, `6px`, `12px`, `radii.pill`, `text.small`, `600` | The tabs switcher |
+| `tree-tab-bg`, `tree-tab-edge`, `tree-tab-ink`, `tree-tab-current-bg`, `tree-tab-current-ink` | `surface`, `hairline`, `secondaryInk`, `accent`, `inverseInk` | The tabs, and the current one |
+| `tree-search-bg`, `tree-search-edge`, `tree-search-ink`, `tree-search-radius`, `tree-search-size`, `tree-search-pad-y`, `tree-search-pad-x` | `surface`, `hairline`, `ink`, `radii.control`, `text.small`, `9px`, `12px` | The search box |
+| `tree-search-label-gap`, `tree-search-label-ink` | `space.xs`, `muted` | Its label |
+| `tree-search-results-gap`, `tree-search-hit-gap`, `tree-search-hit-radius`, `tree-search-hit-ink`, `tree-search-hit-weight`, `tree-search-empty-ink`, `tree-search-hit-pad-y`, `tree-search-hit-pad-x` | `space.sm`, `2px`, `radii.control`, `ink`, `600`, `muted`, `7px`, `10px` | Its results |
+| `tree-search-height`, `tree-search-gap`, `tree-search-icon-size` | `36px`, `9px`, `13px` | The compact well. It also reads `tree-search-bg` (`pageBg` here), `tree-search-radius`, `tree-search-pad-x`, `tree-search-size` (`text.meta` here), `tree-search-ink` and, for the well's own ink, `tree-search-label-ink` |
+| `tree-search-key-pad-y`, `tree-search-key-pad-x`, `tree-search-key-radius`, `tree-search-key-bg`, `tree-search-key-edge`, `tree-search-key-size`, `tree-search-key-weight` | `2px`, `6px`, `6px`, `surface`, `hairline`, `text.meta`, `700` | The "/" key hint |
+| `tree-search-panel-gap`, `tree-search-panel-pad`, `tree-search-panel-bg`, `tree-search-panel-edge`, `tree-search-panel-radius`, `tree-search-panel-shadow` | `6px`, `6px`, `surface`, `hairline`, `radii.panel`, `0 10px 24px -12px rgba(16,18,35,.25)` | The compact box's floating results |
+| `tree-search-hit-size`, `tree-search-empty-pad-y`, `tree-search-empty-pad-x` | `text.small`, `8px`, `10px` | A compact result, and the line saying nothing matched |
+| `tree-rail-width`, `tree-rail-pad-y`, `tree-rail-pad-x`, `tree-rail-label-gap`, `tree-rail-gap` | `layout.columnMin`, `space.xl`, `space.md`, `space.sm`, `2px` | The rail (its padding only when `boxed`) |
+| `tree-rail-link-pad-y`, `tree-rail-link-pad-x`, `tree-rail-link-size`, `tree-rail-link-weight`, `tree-rail-link-ink`, `tree-rail-link-edge` | `6px`, `10px`, `text.small`, `inherit`, `secondaryInk`, `hairline` | A heading in the rail |
+| `tree-pager-top`, `tree-pager-gap`, `tree-pager-pad-y`, `tree-pager-pad-x`, `tree-pager-radius`, `tree-pager-bg`, `tree-pager-edge` | `space.lg`, `space.sm`, `16px`, `18px`, `radii.panel`, `surface`, `hairline` | Previous and next |
+| `tree-pager-label-size`, `tree-pager-label-ink`, `tree-pager-title-gap`, `tree-pager-title-size`, `tree-pager-title-weight`, `tree-pager-title-ink` | `text.meta`, `muted`, `space.xs`, `text.small`, `600`, `ink` | Their words |
+| `tree-edit-top`, `tree-edit-ink`, `tree-edit-size` | `space.md`, `muted`, `text.meta` | "Edit this page" |
+
+*Variants.* What a token cannot say, because it changes which elements are drawn or where they sit, is
+the tree's `variant`, and a `variant` prop on the component:
+
+```json
+"tree": { "variant": { "switcher": "list", "sidebar": "boxed", "rail": true, "pager": "halves" } }
+```
+
+| Part | Values | What |
+| --- | --- | --- |
+| `switcher` | `tabs` (default), `list` | A row of pills above the search box, or a labelled column of rows inside the sidebar above the sections, under the search box, folding away with the pages on a phone |
+| `sidebar` | `plain` (default), `boxed` | The sidebar beside the page in the wide column, or the page split edge to edge with the sidebar a surface column and a hairline between. `boxed` stacks on a phone |
+| `rail` | `false` (default), `true` | An "on this page" column of the item's second level headings at the inline end, linking to the ids its body renders. Hidden below 64rem |
+| `pager` | `wide` (default), `halves` | Previous and next taking the room there is and wrapping on a phone, or two halves that never wrap, next on the right even with no previous |
+| `search` | `box` (default), `compact` | A labelled input with its results under it, or one well holding a magnifier, the input and a "/" key hint, the input named by `aria-label` with no label on screen, and the results in a panel floating over what follows. "/" focuses either |
+| `disclosure` | `open` (default), `closed` | On a phone, the sidebar open under a "Contents" control, or closed until tapped, the control naming the product, the section and the page being read, with "Contents" and a chevron that turn to `closeContents` and point up while open. Above the phone breakpoint both show the whole sidebar and no control. `closed` needs no script: the content is shown above the breakpoint through `::details-content`, and a browser without it keeps the control there too, so the sidebar is one tap away rather than gone |
+
+A value the engine does not know is today's layout for that part.
+
+*Classes.* Each part carries a class a stylesheet can reach, for what neither a token nor a variant
+covers (a hover, a transition): `bp-tree-shell` (and `bp-tree-shell-boxed`), `bp-tree-aside`,
+`bp-tree-body`, `bp-tree-rail`, `bp-tree-sidebar`, `bp-tree-summary`, `bp-tree-sidebar-body`,
+`bp-tree-sections`, `bp-tree-section`, `bp-tree-section-label`, `bp-tree-list`, `bp-tree-item`,
+`bp-tree-link`, `bp-tree-link-current`, `bp-tree-switcher` (with `bp-tree-switcher-tabs` or
+`bp-tree-switcher-list`), `bp-tree-switcher-label`, `bp-tree-tab`, `bp-tree-tab-current`,
+`bp-tree-product`, `bp-tree-product-note`, `bp-tree-search`, `bp-tree-search-label`,
+`bp-tree-search-input`, `bp-tree-search-results`, `bp-tree-search-index`, `bp-tree-search-hit` (a
+result a route answered with), `bp-tree-search-empty`, `bp-tree-rail-nav`,
+`bp-tree-rail-label`, `bp-tree-rail-link`, `bp-tree-pager`, `bp-tree-pager-link`,
+`bp-tree-pager-prev`, `bp-tree-pager-next`, `bp-tree-pager-label`, `bp-tree-pager-title`,
+`bp-tree-pager-empty`, `bp-tree-edit`, and for the variants `bp-tree-search-compact`,
+`bp-tree-search-box`, `bp-tree-search-icon`, `bp-tree-search-key`, `bp-tree-nav-closed`, `bp-tree-summary-closed`, `bp-tree-summary-group`,
+`bp-tree-summary-title`, `bp-tree-summary-action`, `bp-tree-summary-show`, `bp-tree-summary-hide` and
+`bp-tree-summary-chevron`. Every label paragraph (a section's, the list switcher's, the pager's, the
+rail's) also carries `bp-label`, so a rule aimed at running text can skip them all with
+`:not(.bp-label)`. An index entry carries no class of its own, to stay small: it is
+`.bp-tree-search-index li > a`, holding a `span` with the words that matched and, for a heading, a
+second `span` naming its page. The styles are inline, so a stylesheet rule that sets a property the
+part already sets needs `!important`; a token does not. The index's entries are the exception: they
+are styled from one stylesheet scoped to their box, so an ordinary rule of the same or higher
+specificity reaches them.
+
+**The search index.** `treeSearchIndex(tree)` lists every page with a route and then its second level
+headings, in reading order, each heading linked to its anchor. It is built once per tree read and
+shared by everything drawn from that read, and a body's headings (`itemHeadings(item)`, from
+`markdownHeadings` in `barakopress/markdown`) are tokenised once per distinct body and kept, so a static
+build of a manual of n pages lexes each body once rather than n times. With `searchIndex`, the box
+draws the index into the page hidden and its client code shows the entries holding every word typed,
+eight at a time.
+
+What that costs: an entry is a list item, a plain link and its words, styled from one stylesheet, so
+it is its href and its text plus about 50 bytes. The index is part of the server render, so Next
+carries it in the page's payload as well as its HTML, like any other server markup; it is never also
+handed to the client component as props. At most 2000 entries (`TREE_INDEX_LIMIT`) go into a page.
+Past that it is headings that are left out, never a page: every page's title is counted first and
+headings fill the rest in reading order, and the server log says once which manual lost how many.
+A body gives at most 100 headings (`HEADINGS_PER_BODY`), and what is kept between reads is those
+headings under a digest of the body, never the body.
+
+The results are put away, with what was typed kept, when focus leaves the box, when something outside
+it is pressed, when one of them is followed, and on Escape; they come back when the box has focus again. Enter goes to the first
+match. With no `searchPath` there is no form at all, so Enter can never reload the page with the
+query: with script the box answers in the page, and a reader with no script gets a field that does
+nothing, not one that reloads the page and empties itself.
+
 ### Pages and navigation from the Pages module
 
 With `BarakoCMS.Pages` installed, the CMS owns the page tree: which pages are in the menu, their
@@ -246,6 +523,10 @@ curl -X POST "$CMS_URL/api/content-types/page/fields" -H "authorization: Bearer
 A page with a non-empty list renders its blocks. A page without one renders its `Body` as before.
 Field names come from `pageFields` in the config, and the type from `types.page`.
 
+`PageView` draws the page's `Title` above its blocks. A page whose blocks open with their own
+heading sets a boolean `HideTitle` field to stop it drawing twice: `Title` still names the page for
+a tab and for search either way.
+
 ```json
 [
   { "type": "richText", "props": { "markdown": "## Hello" } },
@@ -261,23 +542,62 @@ Blocks come in four layers.
 
 **Layout primitives** hold blocks and no content: `section` (a tone, a width and a padding step),
 `stack`, `row` (side by side, wrapping on a phone), `grid`, `flow`, `panel` (a card with a tone and
-a frame), `spacer` and `divider`.
+a frame), `stickyBar` (a band that stays put while the page moves under it, at the top or the
+bottom), `spacer` and `divider`.
+
+A `stack` or a `panel` given an `href` is a link, the whole of it: a card whose face goes somewhere.
+A site path is drawn with Next's `Link`, anything with a scheme as a plain anchor, and the address is
+held to the same check as any link field. What is inside is the link's name, so nothing inside should
+be a link of its own: one that holds a link, a button, a linked container, a control or a text with
+a markdown link in it is drawn without its `href`, and the server log says so once, since a link
+inside a link is markup a browser rewrites. A `section`, `stack` or `panel` given an `anchor` carries
+it as its `id`, for a link to `#start` elsewhere; one that is not a plain name is left off.
 
 `row` and `grid` take one list per cell, which suits a designer placing each one. `flow` takes a
 single list and lays out whatever is in it, which is what a `repeat` and a preset's `slot` produce:
 a card per row that came back, however many that is. Its column count is a choice and not a number,
 because only a string field takes a binding, and a preset has to pass its own `columns` through.
 
-**Content primitives** hold content and no layout: `text` (a variant from the theme's type scale),
+**Content primitives** hold content and no layout: `text` (a variant from the theme's type scale,
+and `format: "inline"` for code, emphasis, strong, links and an accent in the line; see
+[Inline marks](#inline-marks-in-a-text-block); `tag` draws it as `p`, `span`, `code`, `strong`,
+`em` or `h1` to `h4` rather than the variant's element, `decorative` hides it from a screen reader,
+for an arrow after a link's words, unless its inline marks hold a link, and `title` is shown on hover),
 `richText` (markdown), `image`, `video`, `embed` (an iframe, only for a host in `embedHosts`),
-`icon`, `button`, `link`, `list` and `disclosure` (a labelled section that opens; give several the
-same `group` and only one is open at a time).
+`icon`, `button`, `link`, `list`, `disclosure` (a labelled section that opens; give several the
+same `group` and only one is open at a time), `comparisonTable` (rows typed as lines with `|`
+between the cells, drawn as a real table with a heading on every column and every row) and
+`progressBar` (how far along one thing is, as `role="progressbar"` so it is read and not only seen,
+from a `value` already worked out, or from a `count` with either a `total` or what is `remaining`).
+
+A comparison's first line is the column headings and the first cell of every line after it is that
+row's heading. What goes in a cell is whatever the tenant types, ticks and dashes included: a mark
+chosen inside the engine would be one more piece of English in the markup.
+
+**Motion primitives** are drawn finished and animate only away from that: `reveal` (a wrapper whose
+content lifts and fades in as it scrolls into view), `rotatingText` (a list of words in
+`words`, one shown at a time; the older comma separated `items` still reads), `typingTerminal` (lines typed in sequence, held, then started again) and
+`codeSample` (a snippet with its language and one click to select the whole of it). `text` takes a
+`motion` of `countUp`, which counts a plain number up to the figure already written in the markup,
+and `flow` takes a `hueRotate` of `subtle` or `wide`, which turns each cell's hue through the
+theme's own colours in a cycle of three.
+
+All of it is CSS. There is no script, so a page with JavaScript off renders the terminal typed out,
+the figure at its number and the first word of the rotation standing, and every animation sits inside
+`prefers-reduced-motion: no-preference`, so a visitor who asked for less motion gets exactly the same
+finished page. "When it comes into view" is `animation-timeline: view()`, and a browser without it
+shows the finished state too. `src/blocks/motion.test.tsx` strips the guards out of every stylesheet
+these emit and fails if anything left animates or hides anything.
 
 Every primitive takes theme tokens and never a colour or a pixel value. Tones are `page`, `surface`,
-`accent` and `inverse`; spacing is `none` to `xxl` from `theme.space`; type is a role from
+`accent`, `inverse`, `gradient` (the inverse band with the theme's three dark roles spread across
+it) and `wash`, plus any the site names in `Tones` (see [Tokens and tones](#tokens-and-tones)); spacing is `none` to `xxl` from `theme.space`; type is a role from
 `theme.text`; corners are `none`, `control`, `panel` or `pill`. A tenant that changes the scale
 changes every page built from primitives, and nobody can put one client's blue into a block.
 
+The one way past the tokens is a [style recipe](#style-recipes): every primitive takes `recipe`, the
+name of a look the site defines in its settings, and draws with it in place of its own.
+
 A tone belongs to the band and everything in it: a `section` or a `panel` publishes its ink, its
 accent and its hairline, and the blocks inside read those rather than the page's. That is what makes
 an inverse band readable, and it is why a block dropped anywhere still looks like it belongs.
@@ -285,7 +605,8 @@ an inverse band readable, and it is why a block dropped anywhere still looks lik
 **Presets** are named arrangements of primitives, stored as data: the shipped library below, plus
 whatever a tenant saves of its own.
 
-**Data blocks** load and choose rather than draw: `source`, `repeat`, `showIf`, `pager` and `slot`.
+**Data blocks** load and choose rather than draw: `source`, `repeat`, `showIf`, `pager`, `filterBar`
+and `slot`.
 See bindings below.
 
 Also built in, from before the layers: `columns` (up to four lists of blocks), `callToAction` and
@@ -320,12 +641,53 @@ allowed. A listed origin gets `Access-Control-Allow-Origin` echoed back on `GET`
 preflight, never `*` and never credentials, and every answer carries `Vary: Origin`. Pass
 `{ consoleOrigins: [...] }` to both factories to set the list in code instead.
 
-Field kinds are `text`, `markdown`, `url`, `number`, `boolean`, `select` (with `options`) and `slots`
-(lists of nested blocks, handed to the component already rendered). The list is editor input, so a
+**Which tenant's schema.** Given the config, `createBlockSchemaRoute(config, blocks)` answers a
+request-time site with the schema of the tenant the request belongs to: its own presets, and its own
+tones on every tone field. The tenant is found as a page finds it, from `CMS_TENANT`, the header the
+operator named, the host through the CMS, or `CMS_DEFAULT_TENANT`, so barakoBrew reads a tenant's
+schema at that tenant's domain. Nothing else a caller sends picks the tenant. A host with no tenant
+gets 404 `{ "error": "no site" }`, and a lookup that fails gets 503. The settings behind it are the
+cached read every page makes, under the tenant's cache tag, so a settings change shows after the
+delivery that purges it. A build-time site with no plugins gets the same answer as
+`createBlockSchemaRoute(blocks)`, which still works and still ignores the request. Given only the
+registry, the route cannot tell which plugins the site enabled, so it offers no plugin's blocks and
+lists every plugin as off; a site with plugins passes the config.
+
+Field kinds are `text`, `markdown`, `url`, `number`, `boolean`, `select` (with `options`), `slots`
+(lists of nested blocks, handed to the component already rendered), `list` and `group` (below). The list is editor input, so a
 block renders only when its type is registered and every prop passes its field. A present but wrong
 value fails the whole block, a `url` must pass the same check markdown links do, and a component
-never receives a prop its fields did not declare. A page reads at most 100 blocks in total, nested
-ones included, and four levels deep.
+never receives a prop its fields did not declare. A page reads at most 400 blocks in total, nested
+ones included, and ten levels deep. The count is spent on every block the binder walks through as
+well as every one that comes out, so a band from the library costs eight or ten of it, and a page
+that goes over loses its tail with nothing said. What a `repeat` draws for its rows is counted
+against a budget of its own; see `mode: "all"` under Bindings.
+
+**Lists and groups.** A block that needs several of one thing declares a `list`, and a thing made
+of parts declares a `group`, rather than numbered fields or text split in the component:
+
+```ts
+fields: [
+  { name: "stages", kind: "list", min: 2, max: 6, item: { kind: "group", label: "Stage", fields: [
+      { name: "label", kind: "text", required: true },
+      { name: "body", kind: "markdown" },
+  ] } },
+  { name: "tags", kind: "list", max: 8, item: { kind: "text" } },
+  { name: "cta", kind: "group", fields: [{ name: "label", kind: "text" }, { name: "href", kind: "url" }] },
+]
+```
+
+A list's `item` is `text`, `url`, `number` (with its own `min` and `max`) or `group`, and the list's
+own `min` and `max` count its entries. A list with no `max` holds at most 100. A group's `fields`
+are any field kind except `slots`, and lists and groups nest three deep. A stored list checks every
+entry, and one wrong entry, a list too short or too long, or a group missing a required part fails
+the block like any wrong value. An empty list reads as absent. A group hands its component only the
+keys its fields declare.
+
+The schema at `app/api/blocks` stays version 2 and publishes `item` and `fields` for these, with
+`bindable` resolved at every level. They only add a kind and two keys, and a console that does not
+know a kind edits that one field as JSON, so a block with no list or group publishes exactly what it
+did before.
 
 `defineBlock<Props, SlotNames>` checks the fields against the props at compile time: every field
 names a prop, its kind suits the prop's type, and a prop that is not optional must be `required`.
@@ -351,8 +713,11 @@ optional format and fallback:
 ```
 
 Scopes are `site` (the tenant's settings and resolved identity), `page` (the entry the page
-renders), `item` (the row inside a `source` or a `repeat`) and `query` (URL parameters). `viewer`
-arrives with #7. Formats are `text`, `date`, `datetime`, `time`, `money`, `number`, `upper` and
+renders), `item` (the row inside a `source` or a `repeat`) and `query` (URL parameters). An item
+reads its entry's own fields by name, with the collection's roles (`Title`, `Summary`, `Body`,
+`Date` and the rest) laid over them only where the collection's `fields` maps that role, so an
+unmapped `Body` is still the entry's own `Body`. `count`, `sum` and `group` are about a set of rows
+rather than one, and are described with `source` below. `viewer` arrives with #7. Formats are `text`, `date`, `datetime`, `time`, `money`, `number`, `upper` and
 `lower`; `money` uses the tenant's `Currency` setting, or a plain amount when it has none.
 
 Paths, formats and fallbacks only. There are no expressions and no JavaScript. Everything resolves
@@ -362,6 +727,14 @@ server log, never a crash. What a binding resolves to is checked against the fie
 whose stored field holds `javascript:` drops the block; and a resolved value is never rescanned, so
 one field cannot reach another through its own contents.
 
+A `list` or a `group` takes its whole value from one placeholder with nothing around it, no format
+and no fallback: `"tags": "{{item.Tags}}"` fills the list with the array itself, and
+`"cta": "{{item.Link}}"` a group with the object. What it resolves to is data. Each entry is checked
+against the field, an entry that fails is left out rather than failing the block, the list is cut at
+its `max` since the data is not the editor's to shorten, and one that comes up short of `min` drops
+the block. Nothing in it is scanned for placeholders. A list or a group typed out in full binds
+each string inside it like any string prop.
+
 `source` loads one entry or a page of them and puts it in scope. `repeat` renders its content once
 per row. `pager` draws prev and next links for the `source` it sits in, paged by the API. `showIf`
 keeps its content only when a bound value has something, or equals what it names.
@@ -383,6 +756,125 @@ A filter narrows what the API already lets the reader see. It is never access co
 which rows is decided in barakoCMS. A page reads at most eight sources, and a `source` at most fifty
 rows a page.
 
+`mode: "all"` is for a page that is the whole of a collection rather than a page of it, a changelog
+say: the source reads every row, fifty to a request, up to 500 (`MAX_ALL_ROWS`). Its first request
+is one of the page's eight reads, and the rest are made at once, out of 16 more a page's `all`
+sources share between them (`MAX_ALL_REQUESTS`). A source past 500 rows, or past what the requests
+cover, reads what it can and says so in the server log, and `{{count}}` stays what the collection
+holds. A `pager` inside it draws nothing, and sums, distinct counts, groups and a filter bar cover
+every row it read. A `repeat` draws every row its source read unless its `limit` names fewer. What
+the rows of a repeat and the groups of a grouped source draw spends a budget of its own, 10,000
+blocks (`MAX_ROW_BLOCKS`), rather than the page's 400, so a long list neither takes the blocks after
+it off the page nor renders without end; rows or groups past it are left out and the log says how
+many were drawn.
+
+**Counts, sums and groups.** `{{count.<collection>}}` anywhere on a page is how many published
+entries the collection has, for example `{{count.posts}}`. It is the delivery API's `totalItems` for
+a page of one row, cached like every other read, and the public API lists published entries only, so
+it is the number of rows the page could list. Inside a `source`, `{{count}}` on its own is how many
+rows that source's filter matched, all of them and not just the page it read:
+
+```json
+{ "type": "source", "props": {
+    "collection": "packages", "mode": "list", "pageSize": 1,
+    "filterField": "Category", "filterValue": "Auth",
+    "content": [[ { "type": "text", "props": { "value": "{{count}} auth modules" } } ]]
+} }
+```
+
+A filtered count is a `source` rather than something like `{{count.packages where Category=Auth}}`
+because a placeholder is paths, formats and fallbacks, and a filter value is free text: a value with a
+space or a hyphen cannot be a path segment, and a placeholder that could carry a condition would be
+the start of an expression language. `filterField` and `filterValue` already bind, so the value can
+come from `{{query.c}}` or an item, and the count costs the one read the source makes anyway. Set
+`pageSize` to 1 when the count is all the source is for.
+
+Each collection counted is one of the page's eight reads, spent the first time a placeholder names
+it and shared by every other placeholder that names it. Sources and counts draw on the same eight, in
+the order the page is written. A count past the budget, one for a collection the tenant does not
+have, and one whose read failed all render the fallback and are reported as `no value`.
+
+`{{sum.<Field>}}` inside a `source` adds that field over the rows the source read, for example the
+open issues across a roadmap's milestones. A number stored as text counts. A field with a word in
+any row is not a sum and renders its fallback, and a source with no rows has no sums, so write
+`{{sum.Open ?? 0}}` where zero is the right answer. A sum covers the rows read: fifty at most in
+`list` mode, where a source that pages sums the page it is on, and up to 500 in `all` mode.
+
+`{{distinct.<Field>}}` is how many different values that field holds among the same rows: the
+repositories a list of issues spans, "16 issues across 3 repositories". Values compare as the text a
+placeholder prints, each entry of a list field counts on its own, and a row with nothing in the field
+adds nothing, so a field no row holds renders its fallback. Inside a group it counts that group's rows.
+It counts only what the source read, so a source that matched more rows than it read (a page of a
+longer list) has no distinct counts and renders the fallback: `{{distinct.Repo ?? several}}`. It
+reads a top-level field; a dotted path such as `Owner.Login` renders the fallback.
+
+`groupBy` names a field, and the source's content then renders once per distinct value of it among
+the rows read, in the order first seen. `groupOrder` is a comma separated list of values to put
+first, in that order; the rest follow in the order first seen. Inside each group `{{group.key}}` is
+the value and `{{group.count}}` how many rows have it, and `repeat` and `{{sum.X}}` work over that
+group's rows. `{{count}}` stays what the whole source matched. A row with nothing in the field is
+kept, in a group whose key is empty, so `{{group.key ?? Other}}` names it. A pager inside a grouped
+source renders nothing, since a page of rows is not a page of groups. One grouped source is one read,
+where a source per value was one read each:
+
+```json
+{ "type": "source", "props": {
+    "collection": "milestones", "mode": "list", "pageSize": 50,
+    "groupBy": "Repository", "groupOrder": "barakoCMS, barakoPress",
+    "content": [[
+      { "type": "text", "props": { "value": "{{group.key}}: {{sum.Open}} open in {{group.count}} milestones" } },
+      { "type": "repeat", "props": { "content": [[ { "type": "text", "props": { "value": "{{item.Title}}" } } ]] } }
+    ]]
+} }
+```
+
+All of it resolves on the server as the request's tenant, so a count or a sum never makes the
+browser call the API. A page that uses none of it reads and renders exactly what it did before.
+
+**Filter buttons.** A `filterBar` inside a `source` draws one button per distinct value of `field`
+among the rows the source read, after an "all" button (`allLabel`, which binds, so `All {{count}}`
+works). The values come in the order first seen; `order` is a comma separated list to put first, and
+a value it names that no row holds gets no button. `separator` splits a text field that holds several
+values, such as `4.4.0, 4.3.0`, and a list field gives one value per entry. A bar offers at most a
+hundred values (`MAX_FILTER_VALUES`), the first hundred in that order, and a row carries only values
+the bar offers. Fewer than two values is no choice, so the bar draws nothing.
+
+```json
+{ "type": "source", "props": {
+    "collection": "packages", "mode": "list", "pageSize": 50,
+    "content": [[
+      { "type": "filterBar", "props": { "field": "Category", "allLabel": "All {{count}}", "label": "Filter by category" } },
+      { "type": "repeat", "props": { "content": [[ { "type": "text", "props": { "value": "{{item.Title}}" } } ]] } }
+    ]]
+} }
+```
+
+The rows stay server-rendered and the buttons read nothing. The binder marks each row's own blocks
+with `data-bp-filter`, the bar's id, and `data-bp-filter-values`, its values, each written as
+`<id>:<value>` with the value percent-encoded so a value with a space is one token. A row of a source
+nested in another source's row belongs to both bars, so each attribute can hold two, and each bar's
+rule reads only its own. The id is `f<n>-<scope>`, where the scope is the part of the page the bind
+draws (`body`, `header`, `footer`, or `index` for a collection's index page, and `scope` in
+`bindBlocks` options for a site that binds its own), so a bar in the header and an identical one in the
+body never share an id, and the same page renders the same bytes every time. A click sets `aria-pressed` on the button and
+`data-bp-filter-value` on the bar, and writes one rule that hides every row of that bar without the
+value, with the value escaped as a CSS string and `!important` so it wins over a row's inline
+`display`. A site writes no rule of its own, so a value nobody planned for still filters, and a
+reader with no script sees every row. The buttons are toggles with `aria-pressed` inside a labelled
+group, not a tablist, since the tab pattern promises arrow keys and panels this does not have. A row
+with nothing in the field has no value, so any choice hides it.
+
+The bar draws its buttons from the theme's colours. `recipe` names a style recipe for the row,
+`buttonRecipe` one for each button and `pressedRecipe` one for the button that is pressed, each
+replacing that look outright as a recipe does on a primitive; a button keeps `cursor: pointer`.
+
+In a grouped source the bar is drawn once, ahead of the groups, and filters all of them. With
+`hideEmptyGroups`, a group's own blocks carry every value its rows hold, so the same rule hides a
+group that has no row left. Without it a group stays with its heading and no rows. Only the first bar
+in a source counts. A grouped source honours only a bar at the top level of its content; one inside a
+band there would repeat with every group, so it draws nothing and marks no row. The
+values are those of the rows read, so a source that pages filters the page it is on.
+
 ### Presets
 
 A preset is a named block saved as data, not code: a few props and an arrangement of primitives that
@@ -407,8 +899,20 @@ published image can use it, with no barakoPress release.
 }
 ```
 
+A preset's fields may be lists and groups, in the same shape a block declares them, and
+`{{props.x}}` of a list passes the list itself into a primitive's list field:
+
+```json
+{
+  "type": "taglines",
+  "fields": [{ "name": "words", "kind": "list", "max": 8, "item": { "kind": "text" } }],
+  "blocks": [{ "type": "rotatingText", "props": { "words": "{{props.words}}" } }]
+}
+```
+
 A request-time site reads its tenant's presets from the `Presets` site setting. A build-time site
-passes them as `presets` in the config. A preset never replaces a block that is code. It does
+passes them as `presets` in the config. `/api/blocks` lists a tenant's own presets beside the shipped ones when
+it is mounted with the config. A preset never replaces a block that is code. It does
 replace a preset, which is how a tenant adjusts one of the shipped blocks below without waiting for
 a release. A preset body may not use another preset saved in the same pass, so a cycle cannot form;
 it may use one compiled earlier, which is how a tenant's own block builds on a shipped one. `slot` marks where the content an editor dropped into the preset
@@ -431,25 +935,142 @@ one to look different saves its own under the same name and that one wins.
 | `hero` | The band at the head of a page | heading, body, image, imageAlt, primaryLabel, primaryHref, secondaryLabel, secondaryHref, tone, columns, align, padding |
 | `band` | Copy with one call to action | tone, heading, body, label, href, align, padding, width |
 | `statBand` | A row of figures | heading, tone, columns, padding, items |
-| `cardGrid` | Cards from a collection | heading, collection, filterField, filterValue, empty, tone, columns, padding |
+| `cardGrid` | Cards from a collection | heading, collection, filterField, filterValue, empty, tone, columns, padding, hueRotate, option |
 | `peopleGrid` | People from a collection, typed in place, or both | heading, collection, filterField, filterValue, role, tone, columns, padding, items |
 | `timeline` | Dated entries | heading, tone, padding, width, items |
 | `steps` | Numbered entries | heading, tone, padding, width, items |
 | `tiers` | Giving or pricing tiers | heading, tone, columns, padding, items |
 | `keyValueTable` | A panel of facts | heading, tone, padding, radius, rows |
 | `tabs` | Sections that open | heading, tone, padding, width, items |
+| `announcement` | The one line above everything, and it stays there | message, label, href, tone, edge, align |
+| `codeTabs` | A snippet to run, with the other ways behind it | heading, body, code, language, selectLabel, tone, padding, width, items |
+| `progressList` | How far along each entry of a collection is | heading, collection, filterField, filterValue, empty, tone, padding, width |
+| `changelogList` | Release entries, with the word for the kind of release | heading, collection, filterField, filterValue, empty, tone, padding, width |
+| `faq` | Questions, all openable at once | heading, body, tone, padding, width, items |
 | `map` | An embedded map, held to `embedHosts` | src, title, heading, aspect, tone, padding |
-| `stat` | One figure and its label | value, label, align |
+| `stat` | One figure and its label | value, label, align, motion |
 | `timelineEntry` | One dated entry | date, title, body |
 | `step` | One numbered step | number, title, body |
 | `tier` | One tier | name, amount, body, label, href, tone |
 | `person` | One person | name, role, photo, href, linkLabel, align |
 | `keyValueRow` | One fact | label, value |
+| `codeTab` | One more way to run it | label, code, language, selectLabel, group |
+| `faqItem` | One question and its answer | question, answer, tone |
 
 The blocks in the second half go in the first half's slots: stats in a `statBand`, entries in a
-`timeline`, `disclosure` blocks in `tabs`. A card grid reads its entries through `{{item.Title}}`,
-`{{item.Summary}}`, `{{item.Date | date}}` and `{{item.Href}}`, so it works against whatever the
-tenant calls those fields, and it takes the collection as a prop rather than knowing any name.
+`timeline`, `disclosure` blocks in `tabs`, `codeTab` blocks in `codeTabs`, `faqItem` blocks in
+`faq`. A card grid reads its entries through `{{item.Title}}`, `{{item.Summary}}`,
+`{{item.Date | date}}` and `{{item.Href}}`, so it works against whatever the tenant calls those
+fields, and it takes the collection as a prop rather than knowing any name. `{{item.Href}}` is the
+collection's `href` field when it has one, and the item's own route otherwise, so a collection with
+no route on this site (one filled by a sync, say) still gets a working card once its entries carry
+their own link.
+
+Set a card grid's `option` to `show` and each card carries the glyph and the word the site declared
+for that entry's option, read through `{{item.Icon}}` and `{{item.Word}}`. With `filterField` and
+`filterValue` picking the category, that is a module grid: one band per category, each card marked
+with its own. It is off by default, so a grid that did not ask for it draws what it always drew.
+
+`progressList` reads its figure through `{{item.Progress}}`, which is the collection's `progress`
+field role: the tenant says which of its own fields holds a number from 0 to 100. Where a source
+gives two counts instead, `progressCount` and `progressTotal` carry those through and the bar does
+the division, so a GitHub milestone's open and closed issues need no field computing a percentage
+first. `changelogList` does not group by itself, because grouping means knowing which field holds
+the kind and that is the tenant's field name. One band per kind with `filterField` and `filterValue`
+is the grouping, and the chip on each entry is the option's own word.
+
+### Plugin packages
+
+When no block covers a need, a developer writes one as a plugin package, and the published image
+stays as it is. A plugin is an npm package that ships built JavaScript, like this one does, and whose
+default export is `definePlugin`:
+
+```tsx
+import { defineBlock, definePlugin } from "barakopress";
+
+type TallyProps = { count: number; label: string };
+
+const tally = defineBlock<TallyProps>({
+  type: "tally",
+  label: "Tally",
+  fields: [
+    { name: "count", kind: "number", required: true },
+    { name: "label", kind: "text", required: true },
+  ],
+  component: ({ props, theme }) => (
+    <p style={{ color: theme.colors.accent }}>{props.count} {props.label}</p>
+  ),
+});
+
+export default definePlugin({ name: "tally", blocks: [tally] });
+```
+
+`defineBlock` checks the fields against the props at compile time, the same as the built-ins: a field
+name the props do not have, a kind that does not suit the prop's type, or an optional field for a prop
+the component treats as always there does not compile. `examples/plugin-sample` is a complete one,
+with its `package.json` and `tsconfig.json`; CI packs it, builds an image with it and renders it.
+
+A plugin block is passed what every block is passed: its props, checked against its fields, its
+slots, rendered, and the theme. It is not passed the config, the CMS address or a token, and data from
+the CMS should reach it through a binding in its props or a module endpoint, not a credential. That is
+what it is handed, not what it can reach: its code runs in the server with full access, `process.env`
+and every `barakopress` export included. Installing a plugin means trusting it with the deployment.
+
+Its name may not be one a built-in, a library block, the site or another plugin already registered.
+Replacing one would change that block for every tenant, including the ones that never enabled the
+plugin.
+
+**Installing: a derived image.** Blocks are registered when the Next build runs, so a package cannot
+be added to a built image. The published image holds the built server and not the source or the
+toolchain, so the derived image is built from the engine's source at a release tag, which is what the
+published image of that tag was built from, with the plugins handed in as a build context:
+
+```bash
+mkdir plugins
+(cd ../my-plugin && npm pack --pack-destination ../site/plugins)   # your own plugin
+npm pack barakopress-plugin-tally@1.2.0 --pack-destination plugins  # one from npm
+
+docker buildx build \
+  --build-context plugins=./plugins \
+  -t my-press:0.8.0-plugins \
+  https://github.com/BaryoDev/barakoPress.git#v0.8.0
+```
+
+`examples/derived-image/compose.yml` is the same thing in compose. The `plugins` directory holds
+tarballs and nothing else, so what is built is exactly the bytes that were packed. The install runs
+offline, so a plugin's own dependencies must travel inside its tarball: list each one in
+`bundleDependencies`, and a tarball with a dependency it does not bundle is refused. So is a plugin
+named like a package the engine already has (`react`, `next`, anything in its lockfile), which would
+otherwise be linked over it. The build installs them beside the engine with no install scripts,
+and writes `press.plugins.ts`, which the reference
+`press.config.ts` passes to `createBlockRegistry(config, [], { plugins })`. An overlay with its own
+`press.config.ts` imports `plugins` from `@/press.plugins` and passes it the same way. Pin the tag,
+and next to it the commit it points at (`git ls-remote https://github.com/BaryoDev/barakoPress.git
+v0.8.0`), since a tag can be moved; building from `#<commit>` is the strict form. The `v0.8.0` tag
+exists from the 0.8.0 release on. Moving it is an engine upgrade, and a plugin should be rebuilt and
+checked against it.
+
+**Enabling: per tenant.** One derived image carries every plugin the deployment installs. A tenant
+renders a plugin's blocks only when the `Plugins` setting in its `site` settings entry names it:
+
+```json
+{ "Plugins": ["tally"] }
+```
+
+Until then, it is as if the plugin were not installed for that tenant: `/api/blocks` does not offer its
+blocks, a page that holds one renders everything around it and not the block, and a preset whose body
+draws one is left out. A list saved empty turns every plugin off; a missing field leaves the ones the
+config names (`plugins` in `defineConfig`, empty unless set). A build-time site enables plugins with
+`plugins` in its config. `/api/blocks` also answers `plugins`, every installed plugin with whether the
+tenant enabled it, which is what barakoBrew reads to show the switch. Each block a plugin added carries
+`plugin` with its name.
+
+What enablement does not do is keep code apart. Every plugin's module is loaded in the container for
+every tenant it serves, and a tenant that has not enabled it is only kept from rendering it. So a
+plugin nobody on the deployment trusts is not installed there. When tenants must not share plugins,
+the answer is a separate deployment, its own barakoCMS, barakoBrew and barakoPress, not a second
+barakoPress against the same API. A hotel's branch landing pages share one deployment; its booking
+system gets its own.
 
 ## Configuring it
 
@@ -481,7 +1102,7 @@ for a post type with no such field.
 | `fields` | the blueprint's PascalCase names | operator only | Which field holds what |
 | `pageFields` | the blueprint's PascalCase names | operator only | Which field on the page type holds what |
 | `routes` | `/blog`, `/authors`, `/categories` | operator only | Where you mounted each route |
-| `pageSizes` | 20, 50, 1000, 50 | `PageSizes` | Index, feed, sitemap, archive |
+| `pageSizes` | 20, 50, 1000, 50 | `PageSizes` | Index, feed, sitemap, archive. The sitemap one bounds the entries one collection contributes, and is not a page size: the sitemap pages to that number at whatever size the API allows |
 | `cacheTag` | `cms` | operator only | The tag this site purges. Two sites on one server need two tags |
 | `backstopSeconds` | 300 | operator only | How long a cached read may live with no webhook. 0 disables it |
 | `cmsTimeoutMs` | 5000 | operator only | How long any one call to the CMS may take, a share link redemption included. Past it the call has failed, and a request-time site answers from its last good copy |
@@ -495,14 +1116,19 @@ for a post type with no such field.
 | `pages` | off | operator only | Where the Pages module's pages are mounted. `""` is the site root. It has to match a route file on disk, which is why it is not a tenant's to set |
 | `reservedSlugs` | the routes and the engine's files | `ReservedSlugs`, added to them | First path segments a root-mounted page may not take. Adds to the defaults |
 | `regions` | off | `HeaderPath`, `HeaderTone`, `FooterPath`, `FooterTone` | The header and the footer as block regions |
-| `collections` | the blog's `post`, `author` and `category` | `Collections` | Content types rendered as lists and detail pages. See Collections |
-| `optionColors` | none | `OptionColors` | CSS colours by `type.field` and option, for `colorBy` |
-| `theme` | the barakoCMS palette | `Colors`, `Fonts`, `Radii`, `Layout`, `Space`, `Text` | Colours, faces, radii and column widths. See below |
+| `collections` | the blog's `post`, `author` and `category` | `Collections` | Content types rendered as lists and detail pages, with each index's copy, index page and default byline. See Collections |
+| `optionStyles` | none | `OptionStyles` | Tone, icon and label by `type.field` and option, for `colorBy` |
+| `optionColors` | none | `OptionColors` | The same, when a tone is all an option has. Read as `optionStyles` |
+| `labels` | English | `Labels` | The words the screens print for a visitor. See below |
+| `store` | in process | operator only | Where the state a fleet has to agree on is kept: kept answers, the host map, the replay guard, the generation of each cache tag. Needed only when more than one container serves the site. See below |
+| `home` | the post index | `HomePath`, `HomeCollection` | What `createHome` serves at `/`. See below |
+| `theme` | the barakoCMS palette | `Colors`, `Fonts`, `Radii`, `Layout`, `Space`, `Text`, `Tokens`, `Tones`, `StyleRecipes` | Colours, faces, radii, column widths, a site's own named values and tones, and the looks its blocks can name. See below |
 
 The third column is the whole of the split. A key marked operator only is one the image decides for
 every tenant it serves, and each is that for a reason you can name: `types`, `fields`, `pageFields`
 and `routes` are what the blog factories compile against, `cacheTag`, `backstopSeconds`,
-`cmsTimeoutMs`, `cmsUrl`, `tenant` and `sites` are facts about the deployment rather than the site,
+`cmsTimeoutMs`, `cmsUrl`, `tenant`, `sites` and `store` are facts about the deployment rather than
+the site,
 and `pages` has to match a route file on disk. Everything else is that tenant's data, edited in
 barakoBrew, and wins over what this file said. A tenant that sets nothing renders exactly as the
 file says.
@@ -591,17 +1217,90 @@ The settings are the singleton `site` type from barakoCMS `docs/site-settings.md
 (`POST /api/content-types/blueprints/site`, then publish its one entry). The engine reads `Name`,
 `Tagline`, `Url`, `Locale`, `Logo`, `LogoAlt`, `FooterLogo`, `Favicon`, `ShareImage`, `Copyright`,
 `Colors` (the theme slots), `Fonts` (a family name per role, and the stylesheet that loads it),
-`Radii`, `Layout`, `TopBar`, `HeaderLinks`, `FooterColumns`, `SocialLinks`, `HeaderPath`,
+`Radii`, `Layout`, `Tokens` and `Tones` (see [Tokens and tones](#tokens-and-tones)), `StyleRecipes` (see [Style recipes](#style-recipes)), `TopBar`, `HeaderLinks`, `MenuLinks`, `HeaderActions`, `FooterColumns`, `SocialLinks`, `HeaderPath`,
 `HeaderTone`, `FooterPath`, `FooterTone`, `AssetsAsSupplied`, `LogoAsSupplied`, `LogoClearSpace`,
-`PageSizes` and `ReservedSlugs`. `Collections` and `OptionColors` are read as the collections section
+`PageSizes`, `ReservedSlugs`, `Labels`, `HomePath` and `HomeCollection`. `Collections`, `OptionStyles` and `OptionColors` are read as the collections section
 describes. `Variants` are not rendered yet. Every value is checked for shape; one that fails, and any the
 entry leaves out, keeps the configured value, so a half-filled theme renders. A link is a path on the
 site or an absolute http or https URL. Set `Url`: without it the feed and sitemap fall back to the
-host the tenant was found by.
+host the tenant was found by. A link in `HeaderLinks`, `TopBar` or `FooterColumns` may also carry
+`badge`, a marker of up to 12 characters drawn beside the label, and `external: true`, which the
+built-in header does not need (every header link is already a plain anchor) and a theme can read.
+A link in `HeaderLinks` or `MenuLinks` may also carry `activeOn` and `children`; see
+[The built-in header](#the-built-in-header).
 
 `createSiteLayout` and `createSiteMetadata` render the root layout from all of this: `lang`, the
 faces, the palette, the top bar, header links, footer columns, social links and the copyright line.
 
+**What the site serves at `/`.** Every site used to be a blog at the root, because the root route
+mounted the post index and nothing else could be named:
+
+| Field | Type | What |
+| --- | --- | --- |
+| `HomePath` | string | A site path such as `/home`. The page the Pages module serves there is the home page. Nothing served there falls back to the index, so naming a page before writing it is safe |
+| `HomeCollection` | string | The key of a collection. Its index is the home page. `HomePath` wins when both are set |
+
+Neither set, `/` is the post index, which is what it was. The blog's own `post`, `author` and
+`category` are ordinary `Collections` entries now, so a school whose news lives in `article` with a
+`Headline` replaces `post` in its settings and gets both its list and its item pages from that entry.
+The RSS link in the built-in header, and the feed alternate in the page metadata, appear only when
+some collection has `feed` on, so a clinic with no posts stops advertising an empty feed.
+
+**The words a visitor reads.** `Labels` is the visitor-facing copy, key by key. A school setting
+`Locale` to `fil-PH` used to get Filipino dates beside English "min read" and "Related":
+
+```json
+{ "Labels": { "minRead": "minutong pagbasa", "by": "ni", "related": "Kaugnay" } }
+```
+
+| Key | English |
+| --- | --- |
+| `minRead` | `min read` |
+| `by` | `by` |
+| `related` | `Related` |
+| `relatedNote` | `cosine similarity, computed on load, not curated` |
+| `featured` | `Featured` |
+| `back` | `Back` |
+| `home` | `Home` |
+| `preview` | The banner over a draft being previewed |
+| `untitled` | `Untitled` |
+| `feed` | `RSS` |
+| `empty`, `emptyNote` | The notice on an index with nothing published |
+| `failed`, `failedNote` | The notice on an index whose read failed |
+| `shareInvalid` | `This link is not valid or has expired.` |
+| `openMenu`, `closeMenu` | `Open menu`, `Close menu`: the header's phone menu button |
+| `menu` | `Menu`: the name of the phone menu's links |
+| `submenu` | `{label} links`: the button beside a header link with children, `{label}` its label |
+| `onThisPage` | `On this page`: the heading over a tree page's rail |
+| `closeContents` | `Close`: the closed phone disclosure's control while it is open |
+
+A key left out, or saved as anything but a word, keeps the English, so a half-filled map reads. A
+build-time site passes `labels` to `defineConfig`. Nothing about a site's own content is here: a
+collection's heading is its `label` and how its count reads is its `noun`.
+
+**The colour slots, by role.** `Colors` sets any slot of the palette, one at a time. The slots are
+`pageBg`, `surface`, `ink`, `proseInk`, `secondaryInk`, `muted`, `hairline`, `accent`, `accentHover`,
+`accentInk`, `accentTint`, `accentTintBorder`, `accentBorderStrong`, `inverse`, `inverseChrome`,
+`inverseInk`, `inverseAccent`, `code` and `success`. A role says where a colour goes rather than what
+it looks like: `inverse` is the band that reverses the page, the footer and a code panel and an
+inverse block, so a bakery with a cream footer sets `inverse` to cream and reads right doing it.
+
+```json
+{ "Colors": { "accent": "#17458F", "inverse": "#F4E3C1", "inverseInk": "#3B2A17" } }
+```
+
+Six slots shipped in 0.3.0 under barakocms.com's own names, and those still work: `darkPanel`,
+`darkPanelChrome`, `darkPanelInk`, `darkPanelAccent`, `codeGreen` and `accentTintBorderStrong` are
+read into `inverse`, `inverseChrome`, `inverseInk`, `inverseAccent`, `code` and `accentBorderStrong`.
+Setting either name sets both, so a tenant saved before the rename keeps its site and a consumer's
+own component reading `theme.colors.darkPanel` keeps compiling. The old names are deprecated and go
+in 2.0.0. An `OptionStyles` or `OptionColors` entry naming an old slot resolves too.
+
+Sizes work the same way. `Text` is the type scale by role, `meta`, `small`, `body`, `lead`,
+`subheading`, `heading`, `title`, `display` and `pageTitle`, and `Space` is the spacing scale. The
+blocks and the screens read those names, so a tenant that wants bigger headings sets `title` once
+instead of asking for a release.
+
 **How many items, per tenant.** `PageSizes` sets the four counts for this site, each on its own:
 
 ```json
@@ -669,17 +1368,39 @@ blocks are drawn there instead, resolved and bound exactly as the page route res
 | Field | Type | What |
 | --- | --- | --- |
 | `HeaderPath` | string | A site path such as `/site/header`. The page served there is drawn in place of the top bar and the header band |
-| `HeaderTone` | string | `page`, `surface`, `accent` or `inverse`: the tone behind the header region. `page` when unset or not one of the four |
+| `HeaderTone` | string | `page`, `surface`, `accent`, `inverse`, `gradient`, `wash`, or a name from `Tones`: the tone behind the header region. `page` when unset or not one of those |
 | `FooterPath` | string | A site path such as `/site/footer`. The page served there is drawn in place of the footer |
-| `FooterTone` | string | The same four names, behind the footer region |
+| `FooterTone` | string | The same names, behind the footer region |
 
 Set neither and nothing changes: `TopBar`, `HeaderLinks`, `FooterColumns`, `SocialLinks` and
 `Copyright` draw the built-in chrome with the markup they always had, which is what keeps a site
 whose own CSS keys off that markup rendering. A path with nothing served at it does the same, so
 naming a page before writing it is safe, and so is a typo.
 
-A region page is chrome rather than somewhere to go, so it is left out of the menu and the sitemap.
-It still answers on its own route, which is how an editor opens it to work on it.
+### The built-in header
+
+With no `HeaderPath`, the header is the logo, the page menu, `HeaderLinks` and the feed link. Four
+more settings shape it:
+
+| Setting | What |
+| --- | --- |
+| `activeOn` on a link | Space separated site paths the link is current on. `/` is the home page alone; any other path covers itself and everything below it, so `/docs` is current on `/docs/intro`. A trailing slash is ignored. The current link gets `aria-current="page"` and the class `bp-current`. It can name a path the link does not point to: a chat server's link can be current on `/community` |
+| `children` on a link | Links under this one, one level deep, each with its own `label`, `href`, `badge`, `external` and `activeOn`. Drawn as a dropdown that opens on hover and on keyboard focus and closes on Escape and when focus leaves, beside a button with `aria-expanded` that opens it too. A child's `activeOn` marks its parent current as well. The parent keeps its own `href` |
+| `MenuLinks` | The rows of the phone menu, in the shape of `HeaderLinks`. Children are drawn as an indented group. Unset or empty, the phone menu shows `HeaderLinks` |
+| `HeaderActions` | Up to four call to action links after the header links, each `{ label, href, variant }` with `badge` and `external` as on any link. `variant` is `primary` (filled with the accent), `secondary` (outlined) or `plain`; unset or unknown is `primary` |
+
+Below 48rem, a site that uses any of these gets a menu button in place of the header links and the
+actions, opening a sheet with the `MenuLinks` rows, the feed link and the actions. The button is a
+`details` element and every link is in the server's HTML, so the menu and the dropdowns work
+without JavaScript; the script adds Escape and keeps `aria-expanded` true to what is shown. The
+words on the controls are `openMenu`, `closeMenu`, `menu` and `submenu` in `Labels` (`submenu` is
+`{label} links`, with the parent's label in place of `{label}`).
+
+A site that sets none of them gets the header it had before, byte for byte.
+
+A region page is chrome rather than somewhere to go, so it is left out of the menu and the sitemap,
+and it answers 404 at its own route: what it holds is already on every page. A collection's
+`indexPage` is treated the same way.
 
 A header region replaces the whole band, the site name, the menu and the RSS link along with the top
 bar. There is no navigation or logo block yet, so a header region lists its own links until the block
@@ -699,12 +1420,14 @@ The registry the regions render with is the one passed to `createSiteLayout(conf
 the built-in blocks when none was passed.
 
 **Caching per tenant.** Every read carries the tenant in `X-Tenant` and in its cache tag,
-`<cacheTag>:<tenant>`. The webhook purges the tag of the tenant its host resolves to, so point each
-tenant's webhook at `https://<that tenant's domain>/api/revalidate`, signed with that tenant's own key
-(see [One key per tenant](#one-key-per-tenant)). A publish on one tenant leaves every other tenant's
-cached reads in place.
-
-**When the CMS is down.** Each successful read is also kept in process, keyed by CMS, tenant and path.
+`<cacheTag>:<tenant>`, and a narrower tag beside it: `<tenant tag>:entry:<type>:<slug>` on a read of
+one entry, `<tenant tag>:type:<type>` on a list, a search, the settings and the page tree. The webhook
+purges the tags of the tenant its host resolves to, so point each tenant's webhook at
+`https://<that tenant's domain>/api/revalidate`, signed with that tenant's own key (see
+[One key per tenant](#one-key-per-tenant)). A publish on one tenant leaves every other tenant's cached
+reads in place.
+
+**When the CMS is down.** Each successful read is also kept in the store, keyed by CMS, tenant and path.
 A read that fails with a network error, a 5xx, or no answer within `cmsTimeoutMs` answers from the
 last good copy and logs a warning; the next successful read replaces it. For ten seconds after such a
 failure that read answers from the copy without asking the CMS, so an outage costs one request per
@@ -739,8 +1462,8 @@ While a tenant is holding, for that tenant only:
 - route handlers (revalidate, blocks, `/_share`, `/api/share/redeem`) and `/_next/static` are served
   as usual.
 
-Switching `Mode` is a publish: the webhook purges the tenant's tag and the next request reads the new
-settings. No deploy.
+Switching `Mode` is a publish: the webhook drops the tag the settings read carries and the next
+request reads the new settings. No deploy.
 
 **Site share links.** barakoCMS creates, lists and revokes them; anyone who may update the `site` type
 can. A client is given `{site Url}/_share#{key}`. The key is in the fragment, so no server log, proxy
@@ -834,9 +1557,197 @@ stylesheet named in `theme.fontSources` when the face is not loaded from there,
 They are not a way to compose a post out of arbitrary sections. Anything that has to sit between two
 paragraphs belongs to the block model, which is issue #6, because only the body knows where it goes.
 
+**A theme that draws the page itself.** A deployment that ports an existing design registers its own
+blocks under the built-in type names and ships its own stylesheet. Two things would still be the
+engine's, and neither can be undone from a stylesheet because both are inline: the page frame
+(`main`, its padding, the title and the breadcrumbs) and the gap between blocks. So:
+
+```tsx
+export default createPage(config, blocks, { bare: true });   // only the blocks
+```
+
+```css
+body { --bp-gap: 0; }   /* every block list, at every level */
+```
+
+`bare` is also taken by `createHome` and `createViewerPage`. `--bp-gap` falls back to
+`theme.space.lg`, so a site that sets neither renders as it did.
+
+### Tokens and tones
+
+The theme's slots are the engine's roles. A design has its own palette on top of them: a colour per
+product, a tint for a badge, a length the design repeats. Those are `Tokens` and `Tones` in the site
+settings, or `theme.tokens` and `theme.tones` in `defineConfig`. A tenant's entries merge over the
+configured ones name by name.
+
+```json
+"Tokens": { "accent": "#E4572E", "cms-ink": "#1D3A8A", "cms-bg": "#E8EEFD", "gutter": "24px", "serif": "'Zilla Slab', Georgia, serif" },
+"Tones":  { "cms": { "ink": "cms-ink", "bg": "cms-bg", "edge": "#B9C8F5" } }
+```
+
+A token is a name and one value: a colour (checked as `Colors` is), a length or a `clamp()` of three
+(checked as `Text` is), or a font stack of plain or quoted family names. A name is a letter, then
+letters, digits and hyphens, up to 40. Each token is emitted on the root as `--t-<name>` by
+`createSiteLayout` (through `themeVariablesCss`), so a site's stylesheet and its blocks write
+`var(--t-accent)` instead of a hex value. A name or a value that fails its check is dropped and the
+rest are kept. Up to 200.
+
+A tone is a name and three colours: `ink`, `bg` and `edge` (hairlines and borders). Each is a token
+name, a `Colors` slot name, or a colour written out, looked up in that order when the tone is drawn,
+so changing a token changes every tone that names it. Text of every kind on the tone is the `ink`,
+and a filled accent is the `ink` with the `bg` as its text. A name is lower case letters, digits and
+hyphens; a built-in name is refused, since those follow `Colors`. A tone with a colour that resolves
+to nothing is dropped. Up to 40.
+
+Every block field that picks a tone offers the site's tones after the built-in six, and a block
+stores `"tone": "cms"` the way it stores `"tone": "accent"`. `HeaderTone` and `FooterTone` take them
+too. `/api/blocks` lists them on every tone field: a build-time site's own, and on a request-time
+site the requesting tenant's, when the route is mounted as `createBlockSchemaRoute(config, blocks)`.
+
+A site that sets neither gets no `--t-` property and no new option anywhere, and renders byte for
+byte as it did.
+
 Read time is derived from the body at 200 words a minute, with fenced code blocks excluded, so there
 is no field to fill in and nothing to keep in sync.
 
+### Style recipes
+
+A primitive draws itself from tokens, which keeps every page one design and also means a designed
+section cannot be built from primitives: a card with its own padding, border, corner and shadow is
+not something any token names. A recipe is that card, said once in the site settings as
+`StyleRecipes` (or `theme.recipes` in `defineConfig`), and a block wears it with `recipe`.
+
+```json
+"StyleRecipes": {
+  "card": {
+    "class": "lift",
+    "style": {
+      "padding": "22px 24px",
+      "background": "{colors.surface}",
+      "border": "1px solid {colors.hairline}",
+      "border-radius": "16px",
+      "box-shadow": "0 1px 2px rgba(16,18,35,.04)",
+      "display": "flex",
+      "flex-direction": "column",
+      "gap": "{space.sm}"
+    }
+  },
+  "eyebrow": {
+    "style": {
+      "font-family": "{fonts.mono}",
+      "font-size": "11px",
+      "letter-spacing": ".16em",
+      "text-transform": "uppercase",
+      "color": "{colors.muted}"
+    }
+  }
+}
+```
+
+```json
+{ "type": "panel", "props": { "recipe": "card", "content": [[
+  { "type": "text", "props": { "value": "01 Products", "recipe": "eyebrow" } }
+]] } }
+```
+
+A recipe is a name and two keys, both optional but not both empty:
+
+- `class`: class names, space separated, put on the element beside the style. A style attribute
+  cannot say `:hover`, a focus ring or a media query, so those go in the site's own stylesheet under
+  this class. Up to 8, each a letter or underscore, then letters, digits, `_` and `-`.
+- `style`: CSS property names, written as a stylesheet writes them, to values. Up to 40.
+
+A value is CSS text, and `{name}` in it stands for a theme value: `{accent}` is the token of that
+name from `Tokens`, and `{colors.<slot>}`, `{space.<step>}`, `{radii.<name>}`, `{text.<role>}`,
+`{fonts.<role>}` and `{layout.<name>}` are the theme's own. References are resolved when the block
+draws, against the requesting tenant's theme, so changing a token changes every recipe that names
+it. A declaration whose reference does not resolve is left out and the rest of the recipe draws.
+
+The properties a recipe may set:
+
+| Group | Properties |
+| --- | --- |
+| box | `display`, `position` (`static` or `relative` only), `box-sizing`, `width`, `min-width`, `max-width`, `height`, `min-height`, `max-height`, `aspect-ratio`, `overflow`, `overflow-x`, `overflow-y`, `vertical-align`, `opacity` |
+| spacing | `margin`, `padding` and their four sides, `margin-block`, `margin-inline`, `padding-block`, `padding-inline`, `gap`, `row-gap`, `column-gap` |
+| typography | `font-family`, `font-size`, `font-weight`, `font-style`, `font-variant-numeric`, `line-height`, `letter-spacing`, `text-align`, `text-transform`, `text-decoration`, `text-underline-offset`, `text-wrap`, `text-overflow`, `white-space`, `overflow-wrap`, `word-break` |
+| colour | `color`, `background`, `background-color` |
+| border | `border`, `border-top`, `border-right`, `border-bottom`, `border-left`, `border-color`, `border-style`, `border-width` |
+| radius | `border-radius` |
+| shadow | `box-shadow`, `text-shadow` |
+| grid | `grid-template-columns`, `grid-template-rows`, `grid-auto-flow`, `grid-auto-rows`, `grid-column`, `grid-row`, `justify-items`, `place-items`, `place-content` |
+| flex | `flex`, `flex-direction`, `flex-wrap`, `flex-grow`, `flex-shrink`, `flex-basis`, `align-items`, `align-content`, `align-self`, `justify-content`, `justify-self`, `order` |
+| engine | `--bp-ink`, `--bp-ink-soft`, `--bp-muted`, `--bp-hairline`, `--bp-accent`, `--bp-on-accent` (the tone the blocks inside read), `--bp-gap`, `--bp-list` (a block list's gap and display), `--bp-code-ink`, `--bp-code-bg`, `--bp-code-size`, `--bp-code-pad`, `--bp-code-radius` (inline code in a text block) |
+
+The list is also exported as `RECIPE_PROPERTY_GROUPS`, for an editor.
+
+The values reach a style attribute, which React writes by joining `name:value;` with no CSS
+escaping, so a value is held to a narrow shape rather than cleaned. It is letters, digits, spaces
+and `# % . , ( ) / + * -`, up to 240 characters, with quotes only around a plain family name
+(`'JetBrains Mono'`). Parentheses balance, and a function is one of `calc`, `min`, `max`, `clamp`,
+`minmax`, `repeat`, `fit-content`, `var` (naming a custom property and nothing else), the colour
+functions (`rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch`, `color-mix`) and the
+gradients. So `;`, `:`, braces, angle brackets, a backslash, `!important`, `@`, a comment, `url()`,
+`expression()`, `image-set()` and `attr()` are all refused: a recipe cannot load anything and
+cannot leave its own declaration. A property off the list, or a value that fails, is dropped and
+the rest of the recipe kept, the way `Colors` drops one bad colour. The check runs again when the
+block draws, on the resolved value, so a theme built by hand gets it too. A name is lower case
+letters, digits and hyphens, up to 40. Up to 400 recipes, merged over the configured ones name by
+name: barakocms.com's pages are about three hundred looks, one per element its design styles.
+
+What wearing one does to a block:
+
+- The block is its own cell. Every block in a list sits in a wrapper, and under a recipe the wrapper
+  is `display: contents`, as a transparent block's is, so the recipe's element is what its parent
+  lays out: a lede that takes `flex: 1 1 420px` beside a claim, a card that is the grid's item. A
+  name the site has no recipe for keeps the wrapper along with the block's own look.
+  That holds for an inline element too. A `link` or a `span` text wearing `display: inline-block`
+  in a list, which is a column, is that column's flex item and is stretched to its width like any
+  other; without a recipe it sits inside a block wrapper at its own width. A recipe that wants its
+  own width says so: `align-self: flex-start`, or `width: fit-content`.
+- The recipe replaces the block's own inline look on its outer element outright. It is not merged
+  over it: the card's own padding under a recipe that only set the corner is a look nobody drew.
+  The block's token props for that element (`padding`, `radius`, `border` and so on) are not
+  applied.
+- What makes the block work stays: a `stickyBar` keeps `position: sticky`, a `flow` keeps its cells
+  (`--bp-list: contents`), a `row` and a `tabGroup` stay wrapping rows, a `list` keeps its marker, a
+  `comparisonTable` keeps its own horizontal scroll, an `embed` keeps its width, shape and no
+  border, a `figure` keeps no margin, and a `rotatingText` keeps the box its words stack in.
+- So does the layout the block's own props ask for: a `grid` or `flow` with `columns` keeps its
+  grid and track list, and `align` and `justify` on a `stack`, `row` or `flow` are kept. A prop left
+  unset leaves the recipe to say it, so a `flow` with no `columns` takes its grid from the recipe.
+- A `tone` named beside a recipe still sets the tone the blocks inside read. Without one, a recipe
+  that changes the background sets `--bp-ink` and its neighbours itself.
+- A `tabPanel`'s recipe is its tab in the strip, and the open tab keeps its colours over it.
+- `recipe` is a text field, so a preset passes its own prop through, and a bound name picks a look
+  per row: `"recipe": "card-{{item.Product}}"`.
+- A name the site has no recipe for draws the block's own look. A block that names none renders
+  byte for byte as it did.
+
+### Inline marks in a text block
+
+`text` takes `format`, `plain` (the default) or `inline`. Inline, its value is one line with marks
+in it: `` `code` ``, `*emphasis*`, `**strong**`, `[links](/docs)` and `==an accent==`, which is drawn
+as `<span class="bp-accent">`. Accents do not nest: `==` inside one ends it. Nothing that makes a
+block of its own is read, so a heading stays one element: `# x`, a list or a quote is the text it
+is, and an image keeps only its alt text. A value longer than 2000 characters is read as plain text,
+since emphasis parsing is quadratic at worst and the value may be bound from content.
+
+It goes through the same safe renderer as a body (`renderInlineMarkdown` in `barakopress/markdown`):
+raw HTML is escaped, a link must be a path, an anchor, http, https or mailto or it keeps its words
+and loses the link, and every attribute is escaped. A path starting `//` or `/\` is another site
+to a browser, so it is refused here and in a body alike.
+
+The marks are styled under `:where(.bp-inline)`, so each rule weighs no more than the element it
+names and a site's own `.lede code` wins. The accent and a link take the band's accent. Code is the
+mono face, and reads `--bp-code-ink`, `--bp-code-bg`, `--bp-code-size`, `--bp-code-pad` and
+`--bp-code-radius` first, so a recipe gives the code in one block a tint and a corner:
+
+```json
+"StyleRecipes": {
+  "grabs-body": { "style": { "font-size": "14px", "--bp-code-bg": "#EEEBFD", "--bp-code-ink": "#4034A8", "--bp-code-pad": "1px 5px", "--bp-code-radius": "5px" } }
+}
+```
+
 ### Assets used exactly as supplied
 
 Some marks come with an identity manual: never recoloured, never outlined, never put in a box, never
@@ -907,6 +1818,49 @@ Every read in `src/delivery.ts` is tagged with your `cacheTag`. `POST /api/reval
 the moment barakoCMS says something changed, so a publish is live in one request and the steady state
 is no database reads.
 
+### What a publish drops
+
+A read carries a second, narrower tag beside the site's own: the entry's when it read one entry, the
+type's when it read a list, a search, the site settings or the page tree. barakoCMS names the content
+type and sends the entry's public data with every delivery, so a publish drops that type's tag and
+that entry's tag, and leaves every other entry of the type cached. Correcting one typo on a school
+with a thousand news posts re-renders that post and the lists it appears in, not the other 999.
+
+A delivery that names no content type, or one this site renders nothing of, drops the site's own tag,
+which is every read it has cached. That is what every delivery did before this, so a workflow posting
+a body of its own keeps working.
+
+A response barakoCMS marks `Cache-Control: no-store` is not cached: the class is remembered against
+that path and every later read of it asks the CMS uncached, carrying no tag. That is how a type that
+has to be fresh to the minute lives beside pages cached for hours.
+
+### Running more than one container
+
+The kept answers, the host to tenant map, the webhook replay guard and the generation of each cache
+tag are in process by default, which is right for one container and wrong for two: a purge reaches
+one of them through the load balancer, and the others keep serving their own copies until the
+backstop runs out.
+
+Pass a `store` on the config and they share it. It is three methods over anything the deployment
+already runs:
+
+```ts
+import type { PressStore } from "barakopress";
+
+const store: PressStore = {
+    async get(key) { return (await redis.get(key)) ?? null; },
+    async set(key, value, ttlSeconds) { await (ttlSeconds ? redis.set(key, value, { EX: ttlSeconds }) : redis.set(key, value)); },
+    async delete(key) { await redis.del(key); },
+    // Only when the key is absent, atomically. This is what honours a replayed delivery once.
+    async add(key, value, ttlSeconds) { return (await redis.set(key, value, { NX: true, ...(ttlSeconds ? { EX: ttlSeconds } : {}) })) !== null; },
+};
+```
+
+A purge one container receives then reaches the rest: the honoured delivery writes a generation
+against each tag it dropped, and a read carries the newest generation of its own tags in the URL it
+asks the CMS for, so a container that was never told is asking for something it has never cached.
+Next's own data cache stays per container; what crosses is the knowledge that it is out of date.
+
 Each read also carries a backstop, 300 seconds by default. That is not for correctness, it is for the
 deployment where nobody ever created the webhook: without it their blog would be empty forever and
 nothing would say why. With it, a missing webhook degrades publishing from instant to a few minutes.
@@ -1117,6 +2071,62 @@ start without that file, and refuses again if `PRESS_SECRET` and `REVALIDATE_SEC
 comes up with no secret can never be told that content changed. Only ports 80 and 443 are published:
 the API, the console and the site are reachable only through Caddy on the compose network.
 
+### The site alone, on a host that already has a proxy
+
+That stack brings its own Caddy, so on a machine already terminating TLS it fights the existing
+proxy for 80 and 443, and on a machine serving other sites that failure is somebody else's outage.
+`compose.site.yml` is the other case: one container on a loopback port, joined to the edge network
+the existing stack created, reached through the proxy the host already runs. The host supplies the
+server block and the certificate.
+
+It is a different compose file and a different manifest, so it is a different registration. `--path`
+is the compose directory, which is where the `.env` lives, and `--file` is what stops BaryoVM
+reaching for `compose.yml` and starting Caddy:
+
+```bash
+baryovm stack add barakopress --vm oracle --sudo \
+  --path /opt/barakopress \
+  --file compose.site.yml \
+  --release-file ./baryovm.site.json
+baryovm stack release barakopress
+```
+
+The manifest syncs to `/opt/barakopress-src`, not to the compose directory, because it syncs with
+`--delete` and that directory holds the `.env`. Its `.env` needs `SITE_PORT`, `CMS_URL` pointing at
+the API's container name on the shared network, `SITE_URL` and `PRESS_SECRET`; `SITE_DOMAIN`,
+`API_DOMAIN` and `CONSOLE_DOMAIN` belong to the full stack and are not read here.
+
+A site deployed this way writes its identity at build time, so it keeps its config and its root
+routes under `deploy/<name>/` and the manifest passes `PRESS_DEPLOY=<name>` to the build. See
+`deploy/press.baryo.dev/`. The reason it cannot use the reference app as it stands: every page there
+lives under `app/%5Fpress/[site]`, which only the proxy's rewrite reaches, and the rewrite only fires
+when the config sets `sites`. With no tenant to resolve to, every page answers 404 while the feed and
+the sitemap still work.
+
+A site with its own theme keeps the overlay in its own repository and passes the directory as a
+build context instead of copying it into `deploy/`:
+
+```bash
+docker buildx build \
+  --build-context overlay=../barakocms-site/theme \
+  --build-arg PRESS_TRAILING_SLASH=true \
+  -t barako-press:barakocms .
+```
+
+In compose that is `build.additional_contexts: { overlay: ../barakocms-site/theme }`. The overlay is
+laid over the reference app the same way. If it ships its own `app/%5Fpress/`, it is a request-time
+site with its own layout and routes, and its tree replaces the reference one; otherwise the tenant
+tree is removed as above. `PRESS_TRAILING_SLASH=true` sets Next's `trailingSlash`, for a site whose
+URLs end in a slash; configure its webhook URL with the slash too (see the revalidate endpoint).
+
+Extra blocks go in the same way, as a `plugins` build context: see
+[Plugin packages](#plugin-packages).
+
+One thing to expect on a first release: the image prerenders during `docker build`, where the CMS is
+not reachable, so the index, the feed and the sitemap are built empty and correct themselves one
+revalidate window later. That is why the manifest's `verify` greps the page rather than reading the
+status code, and why it waits long enough to see it happen.
+
 ## The look check
 
 Before a site's domain moves to this stack, the look check proves the rebuilt pages look like the