@bettercms-ai/mcp 0.68.2 → 0.70.0

package/dist/skills/bettercms/SKILL.md

@@ -117,12 +117,15 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Set up or resume a project | [getting-started.md](references/getting-started.md) | first contact, or "Continue BetterCMS setup" | setup, resume, onboarding, connect, import my site |
 | Finish an imported or converted site | [finish-site.md](references/finish-site.md) | a convert or build job; "make it fully editable"; the gap ledger | make it editable, finish, gap ledger, convert |
 | Move content out of another CMS (Cosmic, Contentful, Sanity, Strapi, Prismic, WordPress…) | [external-content.md](references/external-content.md) | a CMS SDK in package.json; `envWarning` on import; pages that render empty without a third-party key | Contentful, Sanity, Strapi, envWarning, missing key, empty pages |
-| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field |
+| Read a source site before modelling it | [detection.md](references/detection.md) | converting from a URL or built HTML; deciding what a band, a repeat or a value is | detect, classify, section, repeat, global, carousel clone, hidden state |
+| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field, listing, filter, locked field |
 | Dock layout: groups, rows, tabs, icons, item names, showIf order | [editor-chrome.md](references/editor-chrome.md) | `get_next_steps` lists a `dock-*` rule; the `field-ui` prompt | dock, fieldset, tab, group, itemLabel, showIf, field-ui |
 | A custom input for one field in the dock: when, the user's approval, the contract | [dock-input.md](references/dock-input.md) | `get_next_steps` lists `dock-input-candidate`; a 409 `input_needs_confirmation` | custom input, ui.input, dock input, confirmed, swatch |
-| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write | validation, maxLength, unique, 400, refused write |
-| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | portfolio, agency, corporate, SaaS/AI or ecommerce IA | new site, IA, sitemap plan, portfolio, SaaS, ecommerce |
+| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write; a bulk load or re-run | validation, maxLength, unique, 400, refused write, dry run, externalKey, upsert, re-run |
+| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | the IA of a known site type, with its collections, forms and structured data | new site, IA, portfolio, agency, corporate, SaaS, ecommerce, directory, blog, docs, restaurant, events, course, jobs, real estate, nonprofit, multi-brand |
 | Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
+| One section, source HTML to bound template: hero, feature grid, pricing table, testimonials, FAQ | [worked-examples.md](references/worked-examples.md) | you want the whole path for one section in production shapes | example, hero, pricing, FAQ, testimonial, source to schema |
+| The same for an article entry, navigation in the Global Layout, tabs holding columns | [worked-examples-advanced.md](references/worked-examples-advanced.md) | a collection entry with a body, site chrome, or nested blocks | example, blog post, document body, mega menu, tabs, columns |
 | Componentize a derived site | [componentize.md](references/componentize.md) | `get_site_composition` shows pages made of fields only | componentize, sections, fields-only, get_componentize_plan |
 | Click-to-edit attributes, addresses, declared mode | [bindings.md](references/bindings.md) | `grep -rl "data-bcms-" src` finds files; a value the editor cannot select | data-bcms-field, click to edit, binding report, stega, declared |
 | Wiring, env, hosting modes, media host, snapshots | [frameworks.md](references/frameworks.md) | `package.json` lists an adapter; `bcms-content.json` exists | hosting, headless, env, codegen, types, revalidate, snapshot |
@@ -133,7 +136,8 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Brand kit, tokens, fonts, logo, images, icons | [media-and-brand.md](references/media-and-brand.md) | design fidelity, alt text, a logo or favicon change | brand, tokens, fonts, logo, image, alt text, favicon |
 | Forms, menus, accordions, modals, consent | [forms-and-interactions.md](references/forms-and-interactions.md) | attaching or verifying a form; an interactive section | form, submission, Turnstile, modal, accordion, menu |
 | Languages, locale prefixes, translation, hreflang | [localization.md](references/localization.md) | the build serves `/fr`-style prefixes; `locale-unvarianted` in a binding report | language, locale, /fr, translate, hreflang, i18n |
-| SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, `list_seo_issues` | SEO, meta, JSON-LD, sitemap, robots, OG image, redirect |
+| SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |
+| Accessibility: alt text, form labels, contrast, the audit codes and the manual checks | [accessibility.md](references/accessibility.md) | writing alt text; building a form; before reporting a site done | accessibility, WCAG, alt text, decorative, label, contrast, captions |
 | Page families from data | [programmatic-seo.md](references/programmatic-seo.md) | a keyword list or CSV should become pages | programmatic SEO, CSV, dataset, landing pages, glossary |
 | Publish, deploy, roll back, reconcile a re-import | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits | publish, deploy, rollback, sync, webhook, schedule, automation |
 | Read-only launch review | [site-review.md](references/site-review.md) | "is this ready to launch?" without fixing | launch review, audit, is it ready, QA |

package/dist/skills/bettercms/references/accessibility.md

@@ -0,0 +1,171 @@
+---
+title: "Accessibility"
+description: "WCAG 2.2 AA rules for converted and built sites: alt text, media, forms, contrast, links, motion, the audit codes, and the manual check list to run before reporting done."
+---
+
+# Accessibility
+
+**Outcome.** A converted or built site meets WCAG 2.2 AA where BetterCMS lets an agent control
+it, and the report says plainly what was checked and what was not.
+
+`list_seo_issues` reports the checkable items as `a11y.` codes, from the stored blocks of
+published pages: image alt missing, h1 missing, several h1, an h1 inside body text, a skipped
+heading level, generic link or button text, a video with no transcript. Each names the page and
+its block ids. It cannot see inside a `component` or `collection` block, an entry's fields, or a
+route the repo's code renders, and a clean result says nothing about contrast, focus order,
+keyboard use or form behaviour. Those stay manual: read the rendered page, then report what you
+saw. Never write "WCAG compliant"; write "checked against this list, with these exceptions".
+
+Related: [media-and-brand.md](media-and-brand.md) (assets, SVG, video, focal point),
+[forms-and-interactions.md](forms-and-interactions.md) (form fields, interactive patterns),
+[portable-text.md](portable-text.md) (heading levels, lists, tables), [seo.md](seo.md).
+
+## Contents
+
+- [Where each fact is stored](#where-each-fact-is-stored) · [Alt text](#alt-text)
+- [Video and audio](#video-and-audio) · [Forms](#forms) · [Structure and links](#structure-and-links)
+- [Colour, contrast and motion](#colour-contrast-and-motion) · [Check list before done](#check-list-before-done)
+- [What to report](#what-to-report)
+
+## Where each fact is stored
+
+| Fact | Lives in | Write with |
+|---|---|---|
+| Alt text of an image | `altText` on the image value, and on the media asset | the value in the entry or page write; `update_media` `altText` for the asset |
+| Caption | `caption` on the asset | `update_media` `caption` |
+| Transcript (video or audio) | the asset, published wherever the file is used | `update_media` `transcript` (at most 100,000 characters) |
+| Decorative image | `decorative` on the asset; an empty `altText` on one value | `update_media` `decorative: true`; the value in the entry or page write |
+| Captions track (`.vtt`) | not stored by any tool | report as missing; the owner adds it |
+| Form label, required mark, help text, consent wording | the Form's fields | `create_form` / `update_form` |
+| Icon-only link or button label | the element's `aria-label` or visually hidden text in the code, or the component prop that feeds it | code, or the component prop |
+| Page language | the page or entry `locale` | see [localization.md](localization.md) |
+| Page title | `metaTitle` | see [seo.md](seo.md) |
+
+An image value is an object, never a bare string. Alt on the asset is the default; alt on the
+value is for this placement only. Set both when the same file reads differently in two places.
+
+## Alt text
+
+An asset that is decoration wherever it is used takes `update_media` `decorative: true`: the
+audit stops asking for its alt text. An image VALUE has no such flag; an empty alt marks that one
+placement as decoration. A missing alt and a deliberately empty alt look the same to the next
+reader, so list every empty alt you left on purpose.
+
+| Image | Alt |
+|---|---|
+| Informative | What it shows that matters in this place. Never the file name, "image of", "photo" or "logo" |
+| Logo | The company name. A linked logo says where it goes ("Caldera home") |
+| Person | "Portrait of {name}" |
+| Product | The product name and what the photo shows |
+| Chart or diagram | One sentence with the trend or the point; put the numbers in real text nearby |
+| Image of text (size guide, menu) | Rebuild it as a table or list; keep the image only as a diagram |
+| Background image that carries meaning | Make it an image with alt, or mark it decorative |
+| Decorative (rule, flourish, duplicate of nearby text) | Empty alt; `decorative: true` on the asset when it is never informative |
+
+- Copy the source's real alt when it is good. Rewrite "image of ..." and file-name alt to
+  describe the image.
+- Missing or junk alt on a meaningful image: write it from the visible context and flag
+  `alt-written` for review. With no context to draw on, leave it empty and flag `alt-missing`.
+- An empty alt is right for decoration and wrong on a portfolio, product or team photo. Flag
+  every empty alt on a content image.
+- Generated images (`generate_image`, `transform_image`) always get `altText`.
+
+## Video and audio
+
+- Never invent captions or a transcript. If the source has none, leave the field empty, and
+  report it.
+- A transcript you produced from your own speech-to-text goes on the asset with `update_media`
+  `transcript`. It then publishes on the page, the Markdown twin, llms-full.txt and the delivery
+  API. BetterCMS does not generate transcripts.
+- Captions are `.vtt` files and no BetterCMS field stores them. State "captions missing" in the
+  report for any video with speech.
+- A video needs a poster image and autoplays only muted.
+- An embed needs a `title` naming the provider and what it shows. Write one when missing.
+- An animation, Lottie or 3D scene needs a poster or fallback image and a text label, and must
+  stop for reduced motion.
+
+## Forms
+
+Forms are Form records, so the rules apply to the form's fields ([forms-and-interactions.md](forms-and-interactions.md)).
+
+- Every field has a `label`, which the renderer shows as a visible label. A placeholder is not a
+  label. If the source used placeholders only, write a label from each, and flag it.
+- Mark required fields with `required: true`. The hosted renderer adds an asterisk; say in the
+  field's `helpText` or the form intro that starred fields are required, so colour or a symbol is
+  never the only signal.
+- `helpText` carries the format or constraint ("Use the number on your invoice"). A refused
+  submission returns `issues[].field` and `issues[].rule`; show the field name and the fix in the
+  form's error copy.
+- Consent: a `consent` field starts unticked and must be ticked to submit. Import a source's
+  pre-ticked box as unticked, and flag it. Import confirmshaming copy as written, then flag it
+  with a neutral rewrite.
+- `autocomplete` is not a field setting. The hosted and Next renderers set it where they know
+  it (phone). For a self-hosted form with its own markup, keep the source's values (`email`,
+  `given-name`, `tel`, `postal-code`).
+- A form result (success, error) must be announced. The Next `BcmsForm` uses a live region; check
+  that a custom form does too.
+
+## Structure and links
+
+- Heading levels follow the outline: one H1, no skipped level. How a heading level is chosen and
+  stored is in [portable-text.md](portable-text.md). Size is a style token, never a reason to
+  pick a level.
+- Lists, tables and quotes use their real Portable Text blocks, never lines of text with
+  bullets or spaces.
+- Link text says where it goes. Replace "click here", "read more" and "learn more" on their own
+  with the target ("Read the care guide"). Where the card layout forces a short visible label,
+  add the target as visually hidden text or an `aria-label` in code.
+- Icon-only links and buttons (social icons, close, menu, carousel arrows) have an `aria-label`
+  or hidden text. A dot or a map pin that links needs one too. Draft the label and flag it; never
+  leave it empty.
+- Navigation, footer and announcement bar belong in Global Layout (`update_layout`). Check the
+  skip link, the landmark roles (`header`, `nav`, `main`, `footer`) and that the mobile menu
+  opens by keyboard and returns focus.
+- Set the page `locale`. Mark a foreign phrase inside text with `lang` in code.
+- DOM order is reading order; never reorder with CSS. Targets are at least 24 by 24 CSS pixels.
+
+## Colour, contrast and motion
+
+- Contrast: 4.5:1 for body text, 3:1 for large text (24px, or 19px bold) and for borders of
+  controls and icons that carry meaning. Check each theme and each variant the editor can pick,
+  including text over photos.
+- Take colour from brand tokens and section styles, never from a copied hex
+  ([media-and-brand.md](media-and-brand.md)). A brand colour that fails contrast is reported
+  with the pair and ratio; never change the kit unasked.
+- Information is never colour alone: a status dot has a word beside it; a check mark has
+  "Included" beside it.
+- Respect reduced motion: scroll stories stack, parallax goes still, Lottie shows its fallback.
+- Carousels, marquees and auto-advancing tabs need a pause control and stop when focused.
+
+## Check list before done
+
+Run `list_seo_issues` first and fix every `a11y.` code (rows 1, 3, 4 and 5 for hosted pages).
+Then run these on the rendered pages (desktop and a 390 px mobile width), not on the stored data.
+Cover the home page, one page per template, one entry per collection, and every form page.
+
+| # | Check | How |
+|---|---|---|
+| 1 | Every informative image has alt; every empty alt is intentional | read each image's `altText` in the page output; list empties |
+| 2 | No alt is a file name, "image of" or "logo" | scan the same list |
+| 3 | Video and audio: transcript on the asset, captions reported | `get_media`, then the player |
+| 4 | One H1, no skipped heading levels | outline the headings in order |
+| 5 | Link text is meaningful out of context | list all links; fix vague ones |
+| 6 | Icon-only controls have a name | inspect each; draft and flag |
+| 7 | Every form field has a visible label, required is stated in text, consent is unticked | `get_form`, then the page |
+| 8 | A refused submission names the field and the fix | send one bad test submission |
+| 9 | Contrast meets 4.5:1 and 3:1 in every theme | measure real colour pairs |
+| 10 | Whole page works by keyboard: tab order, visible focus, menu, dialog, accordion, tabs | tab through it |
+| 12 | Motion stops or stills under reduced motion | emulate the preference |
+| 13 | Page has a title and a language | `list_seo_issues` for title; check `locale` |
+| 14 | Embeds have a title; moving content can pause | inspect each |
+
+## What to report
+
+Report accessibility as its own short block in the final report:
+
+- Checked: the pages and the rows above you ran.
+- Written: drafted alt (`alt-written`), labels and transcripts. Left empty on purpose: decorative
+  images, and each asset marked `decorative`.
+- Open: `alt-missing`, captions missing, contrast failures with the measured ratio, controls you
+  could not test (a third-party embed, a payment step).
+- Not claimed: conformance. No tool certifies it; the audit covers stored blocks only.

package/dist/skills/bettercms/references/astro.md

@@ -55,7 +55,11 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 
 A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
 (`data-bcms-block`, `data-bcms-style` and the block's style), so the editor can move it and offer
-its spacing handles ([components.md](components.md) §5).
+its spacing handles ([components.md](components.md) §5). It adds `data-bcms-hide` when `style.hideOn` is set: put `RESPONSIVE_CSS` (exported here) in your global CSS.
+
+`<BcmsBlocks>` does not render a block outside its `window`, read against the `now` prop (default:
+render time). Pass `showScheduled` on a draft preview to draw it, marked `data-bcms-window`
+([publishing.md](publishing.md) §6).
 
 `bind` and `bindProps` from `@bettercms-ai/astro/bindings` produce the same attributes as the Next
 helpers. Use them inside component instances so addresses resolve to the instance

package/dist/skills/bettercms/references/bindings.md

@@ -207,3 +207,50 @@ still renders hard-coded copy is not connected. Client components never receive
 - `get_binding_report`'s `help.percent` is 100: every bound field also tells its editor what it
   is for. Binding a leaf makes it editable; help text makes it usable
   ([content-modeling.md](content-modeling.md), "Writing help text").
+
+## Reading the binding report and the conversion receipt
+
+`get_binding_report` per slot (`slot` is `current` or `staging`; on a promote-gated project read
+`current`, the tree the editor frames). Every figure, `unaddressable` included, is measured per
+slot. `sha` is the build the report describes; `refreshRequired` is true when that is not the
+build the slot serves. `builtRoutes` lists the routes the live build has HTML for (null = cannot
+say). `layoutIncomplete` lists Layout paths the last content apply could not write (their publish
+waits); `layoutUnread` lists Layout fields no route reads (`layoutUnreadJudged` false = not
+judged).
+
+- **Before any release** there is no report: pages 0, mode null, `refreshRequired` true.
+  `refreshReason` `never-generated` means only a release BetterCMS builds and serves writes a
+  report, so a headless site never gets one, redeploy or not; `outdated` means the next release
+  rewrites it.
+- **`unmatched` reasons**: `not-declared`, `ambiguous-text`, `no-element`, `declared-only`,
+  `needs-wrap`, `refused`, `layout-owned`, `page-owned`, `layout-locator-stale`,
+  `locale-unvarianted`, `svg-unavailable`, `partial`, `unstamped` (a page list the content apply
+  left as built; `kind` reads `list <bound>/<total>`), `mismatch` (a text-match stamp whose element
+  shows more than the value, or no longer the text it was matched on, `data-bcms-from`; never
+  written) and `report-outdated`.
+- A clean report proves each non-empty field has an element carrying its path, nothing more. A Global
+  Section counts only on the routes that render it (`layoutRoutes`).
+- **`unaddressable`** is the copy the report cannot see: visible live text no field owns, by
+  route and bucket, biggest first (null = unmeasured: diff the visible text against the entry
+  values). Over `count / visible > 0.02`, fix it in the source (wrap the run in an element the
+  codemod can bind, or declare `<BcmsField path=…>`), deploy and read again (playbook §11).
+- `canvas.lane` is the editor's live-preview lane (`bridge`, `draft-route`; `none` sends you to
+  `get_next_steps`). `coverage.error` `nothing-bound` means no element of this build is bound, so
+  its percentage describes another site.
+
+`submit_conversion_receipt` answers `complete` (`sourceComplete` is the receipt's own verdict;
+`liveChecks` gives the last release's `structureUnstamped` route count and `reportSha`) and
+`pendingTotal`, and echoes the first 40 pending rows with their `fix`:
+`{ action, file, line, col?, snippet, why?, kind? }`. `action` is one of `wrap-span`,
+`declare-attr`, `bind-expression`, `declare-richtext`, `bind-data`, `manual`; `snippet` and `why`
+say what to change. On a `declare-richtext` with `kind: document`, bind the one element wrapping
+every block of the Body, never the paragraph holding its first. A 404 `unknown-brief` means that
+digest was never issued here. The same run owes the `--forms` receipt, submitted as a second call
+under the same `briefDigest`, and the `styleEdits` of `convert --verify-styles` inside this
+receipt; one listing a changed class, className or style is refused with 409 `style-edits`.
+
+The complete brief (`get_conversion_brief { complete: true }`) also carries `forms` (id, status,
+fields, submitUrl). After the binding pass, run the codemod's forms mode (`npx
+@bettercms-ai/convert --forms`, with the brief and a receipt file) to wire them into the
+repository's own `<form>` elements. Read `forms.pending`, and publish every form `forms.notes` names in the Forms tab: a draft
+form rejects every submission with a 403.

package/dist/skills/bettercms/references/componentize.md

@@ -25,8 +25,9 @@ Inside a section, pick the smallest shape that holds the children:
 
 - **Small identical items** (FAQ rows, feature bullets, logos): a `group` or `table` prop.
 - **One replaceable child with its own layout or variants** (a hero's media treatment): a `slot`
-  prop. It holds exactly one instance, and never sits inside a `group` or `table` row.
-- **Several different children**: the section's ordered children, not a list of slots.
+  prop. It holds one instance, and never sits inside a `group` or `table` row.
+- **Several different children**: the section's ordered children when the set is fixed; a `slot`
+  prop with `config.multiple` when the editor picks and orders them.
 
 Never let a component contain itself, directly or through a child.
 
@@ -40,8 +41,9 @@ Never let a component contain itself, directly or through a child.
    prose body and lists of object rows are sections. Read `pending` for what it will not offer:
    `NO_GROUP_ROOT` (keys are still the derive lane's own, such as `h1-welcome`: rename them into
    families first), `NOT_A_SECTION` (a lone scalar or page metadata; `detail: ENTRY_METADATA` is
-   a template's frontmatter, `detail: DECLINED` a group the user declined) and `IMAGE_AS_TEXT`
-   (a text field holding an image path; it plans once the field is an image). A nav, footer or
+   a template's frontmatter: author, images, tags and dates stay entry fields; `detail: DECLINED`
+   is a group the user declined) and `IMAGE_AS_TEXT` (a text field holding an image path; it plans
+   once the field is an image). A nav, footer or
    modal group is `NOT_A_SECTION` with `detail: LAYOUT_CHROME`: chrome is the Layout on every
    site, never a page band. Author the real sections among those with `create_component` and
    `set_page_content` instead.

package/dist/skills/bettercms/references/components.md

@@ -10,26 +10,62 @@ Doctrine (components vs collections, section anatomy, variants): §3 and §4 of
 reference is what the code does with what you write. Componentizing a derived site end to end:
 [componentize.md](componentize.md).
 
+## Contents
+
+- [1. The prop contract](#1-the-prop-contract) · [2. Instances](#2-instances) ·
+  [3. Sections, families and variants](#3-sections-families-and-variants) ·
+  [4. Publishing](#4-publishing) · [5. Rendering components in your site](#5-rendering-components-in-your-site)
+- [6. Preview source](#6-preview-source) · [7. The values popover](#7-the-values-popover-dashboard) ·
+  [8. Groups](#8-groups) · [9. Verify](#9-verify)
+
 ## 1. The prop contract
 
 A component declares `props`. Each prop is `{ key, label, type, target: { blockId, path },
 defaultValue? }`.
 
-- `type` is one of exactly 11: `text`, `richtext`, `image`, `url`, `boolean`, `number`,
-  `select`, `group`, `table`, `slot`, `form`.
+- `type` is one of exactly 18: `text`, `richtext`, `image`, `url`, `boolean`, `number`,
+  `select`, `group`, `table`, `slot`, `form`, then `date`, `color`, `file`, `link`, `icon`,
+  `multiselect` and `button`.
+- The last seven store what the same-named model field stores: `date` is `YYYY-MM-DD`, `color` a
+  hex, `file` `{ url, name?, size? }`, `link` an href string or `{ href, rel?, newTab? }`, `icon` an icon name or an image
+  value, `multiselect` a `string[]` drawn from `config.options`. A bad `defaultValue` is a 400.
+- **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
+  newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
+  declare a label prop plus a url prop: the two drift apart on the first edit.
 - `target.blockId` + `target.path` must point at a real block and property inside the
   component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
   that does not exist renders the default and the edit goes nowhere.
 - Every prop takes `helpText` and the component a `description` ("Hero with a heading,
   supporting text and two buttons."). Leave them out and the platform writes them; write your
   own by the rules in [content-modeling.md](content-modeling.md) ("Writing help text").
+- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in` or `isSet` (no `value`); model fields take the same four.
 - `update_component` replaces the whole `props` array. Read with `get_component`, change, write
   all props back.
-- `select` needs `config.options`; `slot` holds one nested component instance; `form` holds one
-  Form document.
+- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
+  or a list of them with `config.multiple`; `form` holds one Form document.
 - `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
   empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
   `{ formId }`. Neither may appear inside a `group` or `table` row.
+- **A `slot` with `config.multiple: true` holds a list.** Its value is
+  `[{ componentId, overrides? }, ...]` and its `target.path` is a container's child list:
+  `props.children` on a `section` block, or `props.columns.<n>` on a `columns` block (never
+  `props` on a `component` block). Each item is drawn there as a child component, in order.
+  Until a placement sets the slot, the children the definition holds in that list are shown;
+  `[]` shows none.
+  - `config.maxItems` defaults to 12 and cannot pass 50. `config.minItems` and
+    `config.componentIds` (which components may be listed) are checked on every write.
+  - An item may also carry `style` (use it for `hideOn`) and `window` with `from` / `until`
+    as UTC to the second (`2026-11-27T00:00:00Z`). A `defaultValue` must be an array and takes
+    no `window`.
+  - A write is a 400 whose message starts with the code: `slot_too_many`, `slot_too_few`,
+    `slot_item_invalid`, `slot_component_not_allowed`, `slot_component_unknown` (not a
+    component of this project), `component_cycle` (a component would end up inside itself,
+    through any chain), `component_too_deep` (more than 10 levels), `slot_target_invalid`,
+    `slot_not_multiple` (a list sent to a single slot). A value that is already stored is not
+    refused when the page is saved again.
+  - A child's copy is not click-to-edit on the canvas. Change it in the placement's
+    `overrides.<slot key>` list with `update_page`.
+  - Publish every listed component: a draft child renders nothing, like any draft component.
 - **A `form` prop stores an id, nothing more.** Modelling the questions again as props gives you
   two answers to "what does this form ask?", and they diverge at the first edit on either side.
   The save schema is `.strict()`, so posting the hydrated form object back is a 400, not a silent
@@ -65,6 +101,12 @@ source? } }`.
   component with a `sectionType`. A true one-off is a `section` block whose `props.children` hold
   its blocks.
 - Components that share a `sectionType` are one family: its variants.
+- **A built-in section is a starting point, not a thing you place.** `list_components` shows the
+  locked `builtin:*` blueprints; `create_component` with `from: "builtin:hero-centered"` copies
+  one into the project as an ordinary draft component, then edit and publish it like any other.
+  Whatever you send (`name`, `slug`, `props`, `blockJson`, `sectionType`, `category`) wins over
+  the copy. `list_components` `sourceKey` says which built-in a component came from. A copy
+  never follows later changes to the built-in. An unknown id is 404 `BUILTIN_NOT_FOUND`.
 - **Give every component a library `category` as well.** Why: `sectionType` groups a family, the
   category is how the component library lists it — an uncategorised component is created fine and
   is then hard to find in the picker, which is where a human looks for it.
@@ -112,7 +154,7 @@ Handle by code, never by retrying the same call:
 |---|---|---|
 | `COMPONENT_BLUEPRINT_MATERIALIZATION_REQUIRED` | You tried to publish a platform built-in | Create a project-local component from it, publish that |
 | `COMPONENT_PROJECT_SCOPED_RELEASE_REQUIRED` | The component is workspace-global | Create a project-local variant, publish that |
-| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member's family contract is unpublished. Never a `create_component` component outside a variant group | Report `readiness`; the owner resolves it in the dashboard |
+| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member (the provisioned navigation and footer) has a family contract that is unpublished. Never a `create_component` component outside a variant group: that one is dashboard-managed and publishes on the preflight alone | Report `readiness`; the owner resolves it in the dashboard |
 | `COMPONENT_ORCHESTRATION_V2_REQUIRED` | The project runs implementation in Agent Dock | Continue there; stop here |
 | `COMPONENT_PUBLISH_CONFLICT` | The component or its evidence changed mid-publish | Re-read with `get_component`, then publish once more |
 | `COMPONENT_PROJECT_CONTEXT_MISMATCH` | The component's `projectId` differs from the request's project scope | Call with the component's own project |
@@ -295,4 +337,13 @@ stored list.
    siblings.
 2. `get_site_composition`: every page is sections; every component you meant to publish is
    published.
+   - Per page: `kind` is `blocks`, `fields-only` or `empty`. `nonComponentBlocks` are loose
+     top-level bands the editor's section lane cannot outline.
+   - Per placement: the component's `status` is `published`, `draft` or `missing`. `inPicker` is
+     false for a component with no `sectionType`: "Add a section" does not offer it.
+     `emptyRequiredProps` is reported only here.
+   - Site-wide: `components` counts published and draft, `awaitingEvidence` and
+     `awaitingApproval`. A person approves in the dashboard, one component at a time. Then the
+     `notInPicker` and `unused` ids, and `layout.placements`: the chrome placed in the Global
+     Layout draft.
 3. `get_binding_report` on a page that uses the component: instance values bind.