barakopress 0.7.0 → 0.8.0

package/README.md

@@ -94,7 +94,7 @@ 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(config)` |
@@ -112,6 +112,16 @@ 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`
@@ -160,12 +170,14 @@ 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`, `photo`, `progress`. 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 |
+| `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`. 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 |
+| `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 |
@@ -193,6 +205,36 @@ an agency's case study gets the band a post has. That needs the CMS AI module: w
 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,
@@ -270,12 +312,24 @@ sits. `tree` names them, and the settings beside them say what the sidebar and t
 | `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
@@ -294,7 +348,118 @@ 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 })`.
+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
 
@@ -358,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" } },
@@ -376,25 +545,38 @@ Blocks come in four layers.
 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`, `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).
+`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 comma separated list of words,
-one shown at a time), `typingTerminal` (lines typed in sequence, held, then started again) and
+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
@@ -408,11 +590,14 @@ shows the finished state too. `src/blocks/motion.test.tsx` strips the guards out
 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`, `inverse` and `gradient` (the inverse band with the theme's three dark roles spread across
-it); 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.
@@ -420,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
@@ -455,14 +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 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.
+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`.
@@ -488,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
@@ -499,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.
@@ -520,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
@@ -544,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
@@ -594,7 +961,10 @@ The blocks in the second half go in the first half's slots: stats in a `statBand
 `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.
+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
@@ -602,10 +972,105 @@ for that entry's option, read through `{{item.Icon}}` and `{{item.Word}}`. With
 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. `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.
+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
 
@@ -651,13 +1116,13 @@ 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 |
+| `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` | Colours, faces, radii and column widths. 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`
@@ -752,13 +1217,17 @@ 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`, `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.
@@ -799,6 +1268,11 @@ some collection has `feed` on, so a clinic with no posts stops advertising an em
 | `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
@@ -894,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
@@ -1061,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
@@ -1387,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