@bettercms-ai/mcp 0.83.0 → 0.83.2

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

@@ -1,366 +1,366 @@
----
-title: "Bindings and inline editing"
-description: "Click-to-edit attributes and addresses, declared mode and the binding report, stega in preview strings, and classifying an unfamiliar codebase."
----
-
-# Bindings, inline editing and codebase classification
-
-Doctrine (what should be editable, the conversion loop): §11 and §13 of
-`bettercms://playbook/schema`, and the `convert_site` prompt. This is the template side. Rich-text
-values: [portable-text.md](portable-text.md). Adapter wiring and env: [frameworks.md](frameworks.md).
-
-## 1. Why the attributes matter
-
-A `data-bcms-*` attribute is the only thing that locates a stored value on a rendered page. Five
-readers resolve the same address: the Visual Editor canvas, the component Output pane and live
-preview, publish-time value injection, `get_binding_report`, and componentization. A reader that
-cannot resolve an address guesses, which works once.
-
-## 2. Bind the leaf, and know which vocabulary you are writing in
-
-**Put the attributes on the element that renders the value and nothing else: the `<img>` itself,
-the `<h1>` itself. Never a wrapper, never an element whose children you need.** A declared write
-owns what is inside the element it names. Bind a `<section>` or a card and the band's own
-markup is what a rich text or image write overwrites; the page comes back as bare text where a
-layout used to be. A plain-text write keeps the inline elements inside its element (a highlight
-`<span>`, split-text spans, a `<br>`) on a project in the text-node publish mode, and replaces
-them on an older one: [animation.md](animation.md) §1 has both, and the recipe per animation
-library.
-
-`data-bcms-kind` does not choose the editor; the MODEL does. The attribute says **"this element is
-the declared CONTAINER for the field"**, so the canvas repaints it whole. Leave it off and the
-canvas treats the element as one text-matched FRAGMENT of the value and injects an inline render
-instead, which for a Body means the article does not come back until the next rebuild.
-
-Two separate lists, and mixing them is the way to break a page:
-
-| Attribute | The only values it takes |
-|---|---|
-| `data-bcms-kind` | `text` (or omit it) · `richtext` · `image` · `document` |
-| the kind inside `data-bcms-props` | `text` · `richtext` · `image` · `url` · `number` · `array` |
-
-A model's field TYPES (`select`, `boolean`, `date`, `number`) are **not** kinds. Stamping one
-names a value no renderer mints, and the preview writer refuses it with `UNKNOWN_KIND`.
-
-A `document` body: the WRAPPER carries `data-bcms-kind="document"`, and the per-block elements
-inside carry their own `data-bcms-kind="richtext"`. Never `"richtext"` on the wrapper: that takes
-the rich-text arm, which repaints the container from the field's derived PLAIN TEXT and loses the
-article's blocks. Omitting the kind is legal (the hosted renderer emits it that way) and costs the
-container repaint, so a declared template states it.
-
-What the author gets, from the field's type: text is edited in place, an image opens the media
-picker and patches the element's `src`, richtext and document open a Portable Text editor in the
-frame, and a `url` never takes a caret: it is edited in the element toolbar, because a malformed
-URL typed onto the page has nowhere to report itself.
-
-### Lists, labels and icons
-
-An element bound as text or richtext may hold only inline markup (`span`, `a`, `strong`, `em`,
-`b`, `i`, `small`, `sup`, `code`, `br`), classes and inline styles included. A publish writes the
-value over everything else inside it, so:
-
-- **A list item with a marker.** In `<li><span>✓</span>{item}</li>` the `<li>` renders the tick
-  and the item; bind it and the first save erases the tick. Wrap the value in its own `<span>`
-  and bind that. An `<li>` that renders nothing but the value is itself the leaf.
-- **A link or button label beside an icon.** In `<a href="…"><svg/> Sign up</a>`, put the label
-  in its own `<span>` with the field, and the `href` on the anchor through `data-bcms-props`
-  (`cta.href|url|href`). A binding on the anchor's text deletes the icon. A call to action is a
-  `button` field rendered with `BcmsButton` ([components.md](components.md)).
-- **SVG text is never bound; the icon is.** No field is derived from the text inside an `<svg>`,
-  and no binding there is measured. Each inline icon IS an editable `image` field (`config.media:
-  "icon"`, an svg value): an editor swaps it. Never remove one to tidy a form; group it. So is a
-  sprite icon (`<svg><use href="#id">`) whose `<symbol>` is in the same page, a wordmark set in
-  `<text>`, and an illustration up to 64 KB. A swap keeps the element's classes and size and
-  stays inline, so `currentColor` still applies; scripts and remote references are stripped.
-- **Copy in an attribute is a field of its own.** Every release derives a text field for an
-  `aria-label`, a `title`, a `placeholder` outside a form, and the number a count-up script
-  counts to (`data-target`, `data-count`, `data-value` and their kin). Its `config.attr` names the
-  attribute; it is bound on `data-bcms-props` as `<path>|text|<attribute>` and published into that
-  attribute alone, never matched against the page's words. A label that only repeats the words
-  on its own element gets none. To declare one in code, write the same `data-bcms-props` entry.
-- **Text beside an icon in a plain element** (`<span>Pages<svg/></span>`) is a field when it is
-  the element's one text node: the save writes that node and leaves the icon. Split over several
-  text nodes it stays `BARE_TEXT`, so wrap the label in its own `<span>` where you can.
-- **Icon-only links in the nav and footer** take their field name from what a screen reader
-  reads: the anchor's `aria-label`, its `sr-only` text, a `title`, the SVG `<title>` or an `alt`
-  (never `<style>` or `<script>` text). Give each one an `aria-label` or `sr-only` label, or every
-  social link is named `link` and an editor cannot tell them apart. A row of them is a "Links" or
-  "Social links" list; each row keeps its own name in its values.
-
-### The site's design is not yours to change
-
-**Never edit a `class`, `className` or `style`, and never rewrite markup to suit the CMS.** A rich
-text value keeps inline markup exactly as the site wrote it: `Equip <span class="text-yellow-500
-dark:text-yellow-400">ScrewFast</span>` is stored and published with that span and its classes.
-Do not turn it into `<em>` with an `[&_em]:` selector on the parent, and do not turn
-`<span class="font-bold">` into `<b>`. Before submitting a conversion receipt, run
-`npx @bettercms-ai/convert --verify-styles --base <commit before the conversion> --root .` and put
-its `styleEdits` in the receipt; any token it lists is a design change to restore.
-
-### Images
-
-An image the page imports and renders is bound by the codemod, including one the page hands to a
-section component (`<Hero src={heroImage} />` → the component's `<Image src={src}>`): the call site
-reads `bcmsImage(...)` and passes `bcmsBindings`, and the `<Image>` gets
-`data-bcms-field={bcmsBindings?.src} data-bcms-kind="image"`. Keep the `astro:assets` import as
-the fallback; the build renders it and the publish writes the editor's image. Frontmatter images
-(`cardImage: '@/images/blog/post-1.avif'`) become image fields on their own once the build's
-images are in the Media Library, matched by file name. An image rendered inside a loop over a
-list is not bound automatically: bind it in the list's data file.
-
-The codemod knows an image component by its IMPORT, not its name: `Image` and `Picture` from
-`astro:assets` (aliased, or through `import * as assets`), and the default export of
-`next/image` under any name. An import that reaches the page through `getImage()`, `hero.src` or
-a style is refused as `IMAGE_ASSET_UNRESOLVED`, and the row's message names the import: declare
-the element that shows it by hand (`data-bcms-field` + `data-bcms-kind="image"`).
-
-Images need no code at all on a text-matched site. Every release derives an image field for each
-picture a page shows: an `<img>` (its `src`, or where that is a placeholder a lazy loader's
-`data-src`, then the largest `srcset` candidate), a whole `<picture>` as ONE field, a
-`<video poster>`, an inline or STYLESHEET `background-image` (Tailwind `bg-[url(...)]` included)
-and an inline `<svg>`. What it declines is listed with a reason in the binding report's
-`imageGaps`, and everything else it declines in `elementGaps`
-([media-and-brand.md](media-and-brand.md) Where images hide).
-
-Publishing an image keeps the page responsive. A library image re-points every `srcset`
-candidate and each `<source>` at the new picture at that candidate's own width and format, and
-leaves `sizes`, `width`, `loading`, classes, ids and `data-*` as written; never hand-edit those
-after a swap. A stylesheet background gets one inline `background-image` over the rule, removed
-again when the value returns to the sheet's own picture.
-
-To keep an image editable in code you write yourself, render it with `BcmsImage` and its `path`
-(Astro: `@bettercms-ai/astro/components/BcmsImage.astro`; Next: `BcmsImage` from
-`@bettercms-ai/next`): one `<img>` that declares the field, reads the value's alt, crop and focal
-point, and offers a width ladder when given `sizes`.
-
-## 3. Addresses
-
-The grammar is identical in `@bettercms-ai/next` and `@bettercms-ai/astro`; emit it with the SDK
-helpers rather than by hand.
-
-- `data-bcms-field="<address>"` + `data-bcms-kind` on the element whose content is the value.
-- `data-bcms-props="<address>|<kind>|<domAttribute>;…"` for values that live in an attribute
-  (`alt`, `href`, a video `src`). One element carries one field address, so attribute values ride
-  this list. An `href`, an `src` and a `poster` are kind `url` (`cta.href|url|href`, not
-  `|text|`); an `alt` is `text`. The same address on two elements is edited as two copies of one
-  value (numbered `data-node-index`).
-- `<BcmsField path kind as>` binds hand-rendered entry values. Around ONE element it adds no
-  wrapper: the attributes go on that element. Around text or several elements it renders a
-  `display:contents` span, and `as` names a real wrapper. `path` is dotted keys with any
-  number of `[n]` indices: `title`, `hero.title`, `columns[0].links[2].href`.
-- Rich text is addressed per paragraph: `<base>#<_key>`. No write tool takes an address:
-  `update_content_entry` replaces the whole field (it merges by default, keeping the other
-  top-level fields, never other blocks of the same field). The platform's own path writer refuses a
-  `#<_key>` path (`KEYED_PATH_NOT_WRITABLE`), and only the editor patches one block. A `_key` is
-  part of an address, so never regenerate keys of blocks that already exist.
-- **Inside a component instance** the address is `<instanceId>__overrides.<key>`. Block ids
-  inside a component belong to the definition and are shared by every instance, so a
-  definition-scoped address binds to nothing and two instances collide. Use the package `bind` /
-  `bindProps` helpers inside instances; they resolve the instance address for you.
-- **The placement root carries `data-bcms-block="<blockId>"`.** `BcmsBlocks` emits it; without it
-  the Output pane and the section overlay fall back to an ancestor guess.
-- **Chrome is its own lane.** A nav or footer value is
-  `data-bcms-layout-field="layout:<sectionId>:<fieldId>"`, never `data-bcms-field`; the page lane
-  cannot reach a Layout value.
-- **Draft markers come from the SDK.** `BcmsDraftMarker` and the Astro middleware stamp
-  `<html data-bcms-draft="1">`; `BcmsDraftBridge` stamps `data-bcms-canvas="bridge"`. Mount them;
-  never write them by hand. Binding attributes are always rendered and inert for visitors.
-
-## 4. Declared mode, publish, and the report
-
-- Until `set_binding_mode` `{ declaredBindings: true }` the platform text-matches, which holds
-  only while CMS values equal the built copy. Flip it only when the stamped build's report is
-  clean on every route: push, release, read `get_binding_report`, flip, release again, then
-  confirm `mode: "declared"` and `coverage.pending` empty.
-- On a declared site every published value is written into the element that declares it, so the
-  bytes your template renders at build time are replaced on publish; never put markup you need to
-  keep inside a bound element. A value with no element never reaches the page, and one that
-  would corrupt its element is refused and named.
-- Read the report, not the screen. Clean = `coverage.pending` empty and the mode you expect. Each
-  `unmatched` reason names a fix in the source. A field the stamped build renders on no route is flagged `stale: true` on its schema — kept, hidden in the editor, cleared by the release that binds it again — and is not listed. A Global Layout Section is reported only on the
-  routes that render it (`layoutRoutes` lists each route's Sections): a docs page on its own layout
-  is not missing the nav, so never add one there. A `fallback` flag means the build carried no
-  `bcms-brief` meta and was measured against the latest pin. Only a release creates the report;
-  a content apply later updates its Layout rows.
-
-## 5. Preview strings (stega)
-
-Preview responses requested with `stega=1` hide invisible characters inside prose strings so the
-editor can map text back to fields. Two filters decide what is skipped, and you need both:
-
-- by field NAME: `slug`, `url`, `href`, `src`, `id`, `email`, `color`, `icon`, `date`,
-  `datetime`, `locale`, `type`, `target`, `rel`, `_type`, `_key`;
-- by VALUE shape, for fields it cannot recognise by name: anything starting `http:`, `https:`,
-  `mailto:`, `tel:`, `#` or `/`, and ISO dates.
-
-Portable Text arrays and richtext/image envelopes are skipped whole. Never compare, slugify or
-parse a preview string as-is, and never put one in an attribute or SEO output. Compare published
-values, or strip it first with `stripStega` from `@bettercms-ai/sdk`. The editor strips it before
-it saves.
-
-| The string goes to | Strip first? | Why |
-|---|---|---|
-| Visible text a template renders | Never | The markers are how a click finds its field |
-| A Portable Text renderer, `BcmsField`, an image helper | Never | Those values carry no markers; pass them as-is |
-| `===`, `switch`, `includes`, sort order, a lookup key | Always | The hidden characters make equal strings unequal |
-| A React/Astro `key`, an element `id`, a slug, a URL you build | Always | A marked id never matches its published twin |
-| Any HTML attribute (`class`, `href`, `alt`, `aria-label`) | Always | Attributes are not text the editor maps |
-| `<head>`: title, meta, JSON-LD | Always | Crawlers and share cards read the characters |
-| A third-party call (analytics, search, maps, a date parser) | Always | They store or reject what they cannot read |
-
-## 6. Classify an unfamiliar codebase before binding it
-
-Inspect `package.json`, the framework config, route tree, build command, output mode, content
-loaders, deployment config and any existing BetterCMS adapter. Then classify:
-
-1. **First-class adapter**: Astro or Next.js with its BetterCMS package ([astro.md](astro.md),
-   [next.md](next.md)).
-2. **React/Vite or another SDK integration**: find who owns routing and data fetching, call the
-   SDK on the correct side of the server/client boundary, keep an explicit component registry,
-   and state what preview supports. The Astro and Next helpers do not transfer unchanged.
-3. **Static HTML/CSS/JS**: keep the working markup and add a safe content path where supported.
-4. **Other or opaque generated output**: preserve behaviour and produce an adapter plan (fetch
-   typed content, resolve sections and components, render Portable Text, bind editable values,
-   serve media, preview drafts, refresh on publish), marking every unimplemented capability. A
-   source crawl alone never proves full editability.
-
-Use syntax-aware parsing and the build output, never blind string replacement; for bulk stamping
-use the codemod (`npx @bettercms-ai/convert`). Trace the real data flow: where values are
-fetched, normalised, passed as props and rendered. A component that looks like its CMS record but
-still renders hard-coded copy is not connected. Client components never receive server keys.
-
-## 7. Edit-to-render test
-
-1. Pick a safe draft field and record its old value.
-2. Edit it through the dashboard or the MCP; confirm in preview that the intended leaf or
-   attribute changed.
-3. Confirm sibling instances, global layout and other routes behave according to their scope.
-4. Restore the value, or keep the change the user asked for.
-5. After an authorised publish, fetch the public URL cache-busted and check status and body.
-   Repeat for a dynamic entry route and a global element.
-
-## Acceptance
-
-- The site builds with the repository's build command; routes and assets load.
-- Every claimed editable field has a path: schema, reader, component prop, DOM binding, preview,
-  public output.
-- No public secrets, wrong media hosts, unscoped instance ids or hard-coded shadow values.
-- `get_binding_report` for each route is clean, and one value of each bound kind opens the right
-  editor in the Visual Editor.
-- `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.
-
-## Editor setup, proposals and binding decisions
-
-`editor_setup` derives what a build no longer imports: a build brings in SEO/meta, media, brand and
-the models `bcms-content.json` declares; editor setup adds pages, collections, forms, bindings,
-button and section components (when the authoring preference is components), Component Groups and
-the Content sidebar. `get_deploy_status` `editorSetup` reports its state.
-
-The complete brief's `proposals` (page 1, at most 50; `proposalsMore` when there are more) list
-what the last convert found and no field owns: `{ id, kind, target, text, suggested?, evidence? }`.
-`id` is `pr_` and 16 hex and survives re-runs; `target` is a `file:line:col` locator only. Kinds:
-`unaddressable` and `code-candidate` (copy no field owns), `inert` (declared, nothing reads it),
-`mismatch` (declares one path, reads another), `flatten` (two leaves in one element).
-
-Answer them with `editor_setup { declare: [item, …] }` (at most 100 items, one result each;
-`check: true` with `declare` is a dry run that stores nothing):
-
-- `{ op: "accept", ids }` takes each proposal's `suggested` op. A proposal with none refuses.
-- `{ op: "bind", id, path, owner? }` binds the copy to an existing field; `owner` is a route or
-  `layout`. The next convert writes it into the source (a mismatch's declaration is rewritten; an
-  attribute or an expression is reported `manual` in `receipt.decisionsApplied`). A `bind` waits as
-  `decision-pending` until a build proves the new read; one still pending after the next release
-  blocks the gate. A declared element is corrected through its `mismatch` proposal id.
-- `{ op: "code", id, why, system? }` keeps it in code. `why` is one of `runtime`, `external`,
-  `derived`, `stylesheet`, `decorative`, `embed`, `legal`, and the system checks its evidence;
-  without it the item refuses `evidence-missing` (bind it, pick the reason that fits, or a person
-  marks it in Overview). The next convert writes `data-bcms-code-owned="text why:<id>"`; the
-  `code` counts once a build carries it. Each convert re-checks the
-  facts: one whose reason no longer holds becomes `evidence-lost`, blocks the gate, and returns to
-  the proposals to decide again. Facts are same-file only: a value from another file needs a person.
-- `{ op: "reject", ids }` drops the suggestion; the copy stays unaddressable. A person's reject of
-  an AI `code` is its Undo: the next convert removes the token.
-- `{ op: "clear", decisionId }` undoes a decision.
-
-A person's decision beats yours: add `force: true` and a `reason` (shown to them) only when they
-asked for it. Refusals per item: `target-unknown`, `path-not-in-schema`, `owner-mismatch`,
-`locked-by-person`, `slot-mismatch`, `evidence-missing`, `declaration-conflict`, `invalid-item`.
-Until a convert that emits proposals has submitted its receipt, every id refuses `target-unknown`.
-`get_next_steps` `receipt.decisions` counts `stored`, `materialized`, `proven`, `pending` (open
-proposals) and `lost`; stop when `pending` is 0.
-
-### Archive (ZIP) sites
-
-A project with no connected repository and no receipt carrying proposals is an ARCHIVE site: no
-codemod runs, so each release scan mints the proposals itself. `target` is then
-`template|owner|textHash` (owner `page`, `layout` or `entry:<collection>`; Layout copy has template
-`*`, an entry route its collection's `/blog/*`), and translations of a page share one template.
-Decisions are not written into source: every release stamps them into the built HTML wherever
-their anchors (structure, text, nearest declared field) agree 2 of 3, else the row is `lost`
-(`anchor-lost`). A `bind` stamps only when the element's text equals the field's stored value; an
-uploaded copy change loses it (`anchor-text-changed`) and its copy is proposed again. An AI `code`
-for `runtime`, `external`, `derived` or `stylesheet` refuses `evidence-missing` here (there is no
-source to check); `decorative`, `embed` and `legal` are checked on the page, and a person may mark
-any reason. Each such decision lives in BetterCMS, not in the site's code: recommend connecting a
-repository.
-
-Archive sites also take `{ op: "rule", template, match, then }`, one row for every element it
-matches on every route of `template`:
-- `template`: `/`-segments literal or `*`, a trailing `/**`, or `*` alone (every route). No regex.
-- `match`: at least one of `struct` (a proposal's structure anchor), `cls` (one class token),
-  `text` (exact copy); `owner` (`page`, `layout`, `entry`) narrows.
-- `then`: `{ op: "code", why }` or `{ op: "bind", path }`. A bind rule names a `layout` or `entry`
-  owner, and matching more than one element on a route is `ambiguous` there.
-A person beats an AI, then a per-id decision beats a rule; two rules saying different things about
-one element are `declaration-conflict`. On a git site a `rule` refuses `invalid-item`. A lane change
-(a repository connected, or a convert's receipt arriving) loses the other lane's decisions
-(`lane-changed`): decide again on the new proposals.
+---
+title: "Bindings and inline editing"
+description: "Click-to-edit attributes and addresses, declared mode and the binding report, stega in preview strings, and classifying an unfamiliar codebase."
+---
+
+# Bindings, inline editing and codebase classification
+
+Doctrine (what should be editable, the conversion loop): §11 and §13 of
+`bettercms://playbook/schema`, and the `convert_site` prompt. This is the template side. Rich-text
+values: [portable-text.md](portable-text.md). Adapter wiring and env: [frameworks.md](frameworks.md).
+
+## 1. Why the attributes matter
+
+A `data-bcms-*` attribute is the only thing that locates a stored value on a rendered page. Five
+readers resolve the same address: the Visual Editor canvas, the component Output pane and live
+preview, publish-time value injection, `get_binding_report`, and componentization. A reader that
+cannot resolve an address guesses, which works once.
+
+## 2. Bind the leaf, and know which vocabulary you are writing in
+
+**Put the attributes on the element that renders the value and nothing else: the `<img>` itself,
+the `<h1>` itself. Never a wrapper, never an element whose children you need.** A declared write
+owns what is inside the element it names. Bind a `<section>` or a card and the band's own
+markup is what a rich text or image write overwrites; the page comes back as bare text where a
+layout used to be. A plain-text write keeps the inline elements inside its element (a highlight
+`<span>`, split-text spans, a `<br>`) on a project in the text-node publish mode, and replaces
+them on an older one: [animation.md](animation.md) §1 has both, and the recipe per animation
+library.
+
+`data-bcms-kind` does not choose the editor; the MODEL does. The attribute says **"this element is
+the declared CONTAINER for the field"**, so the canvas repaints it whole. Leave it off and the
+canvas treats the element as one text-matched FRAGMENT of the value and injects an inline render
+instead, which for a Body means the article does not come back until the next rebuild.
+
+Two separate lists, and mixing them is the way to break a page:
+
+| Attribute | The only values it takes |
+|---|---|
+| `data-bcms-kind` | `text` (or omit it) · `richtext` · `image` · `document` |
+| the kind inside `data-bcms-props` | `text` · `richtext` · `image` · `url` · `number` · `array` |
+
+A model's field TYPES (`select`, `boolean`, `date`, `number`) are **not** kinds. Stamping one
+names a value no renderer mints, and the preview writer refuses it with `UNKNOWN_KIND`.
+
+A `document` body: the WRAPPER carries `data-bcms-kind="document"`, and the per-block elements
+inside carry their own `data-bcms-kind="richtext"`. Never `"richtext"` on the wrapper: that takes
+the rich-text arm, which repaints the container from the field's derived PLAIN TEXT and loses the
+article's blocks. Omitting the kind is legal (the hosted renderer emits it that way) and costs the
+container repaint, so a declared template states it.
+
+What the author gets, from the field's type: text is edited in place, an image opens the media
+picker and patches the element's `src`, richtext and document open a Portable Text editor in the
+frame, and a `url` never takes a caret: it is edited in the element toolbar, because a malformed
+URL typed onto the page has nowhere to report itself.
+
+### Lists, labels and icons
+
+An element bound as text or richtext may hold only inline markup (`span`, `a`, `strong`, `em`,
+`b`, `i`, `small`, `sup`, `code`, `br`), classes and inline styles included. A publish writes the
+value over everything else inside it, so:
+
+- **A list item with a marker.** In `<li><span>✓</span>{item}</li>` the `<li>` renders the tick
+  and the item; bind it and the first save erases the tick. Wrap the value in its own `<span>`
+  and bind that. An `<li>` that renders nothing but the value is itself the leaf.
+- **A link or button label beside an icon.** In `<a href="…"><svg/> Sign up</a>`, put the label
+  in its own `<span>` with the field, and the `href` on the anchor through `data-bcms-props`
+  (`cta.href|url|href`). A binding on the anchor's text deletes the icon. A call to action is a
+  `button` field rendered with `BcmsButton` ([components.md](components.md)).
+- **SVG text is never bound; the icon is.** No field is derived from the text inside an `<svg>`,
+  and no binding there is measured. Each inline icon IS an editable `image` field (`config.media:
+  "icon"`, an svg value): an editor swaps it. Never remove one to tidy a form; group it. So is a
+  sprite icon (`<svg><use href="#id">`) whose `<symbol>` is in the same page, a wordmark set in
+  `<text>`, and an illustration up to 64 KB. A swap keeps the element's classes and size and
+  stays inline, so `currentColor` still applies; scripts and remote references are stripped.
+- **Copy in an attribute is a field of its own.** Every release derives a text field for an
+  `aria-label`, a `title`, a `placeholder` outside a form, and the number a count-up script
+  counts to (`data-target`, `data-count`, `data-value` and their kin). Its `config.attr` names the
+  attribute; it is bound on `data-bcms-props` as `<path>|text|<attribute>` and published into that
+  attribute alone, never matched against the page's words. A label that only repeats the words
+  on its own element gets none. To declare one in code, write the same `data-bcms-props` entry.
+- **Text beside an icon in a plain element** (`<span>Pages<svg/></span>`) is a field when it is
+  the element's one text node: the save writes that node and leaves the icon. Split over several
+  text nodes it stays `BARE_TEXT`, so wrap the label in its own `<span>` where you can.
+- **Icon-only links in the nav and footer** take their field name from what a screen reader
+  reads: the anchor's `aria-label`, its `sr-only` text, a `title`, the SVG `<title>` or an `alt`
+  (never `<style>` or `<script>` text). Give each one an `aria-label` or `sr-only` label, or every
+  social link is named `link` and an editor cannot tell them apart. A row of them is a "Links" or
+  "Social links" list; each row keeps its own name in its values.
+
+### The site's design is not yours to change
+
+**Never edit a `class`, `className` or `style`, and never rewrite markup to suit the CMS.** A rich
+text value keeps inline markup exactly as the site wrote it: `Equip <span class="text-yellow-500
+dark:text-yellow-400">ScrewFast</span>` is stored and published with that span and its classes.
+Do not turn it into `<em>` with an `[&_em]:` selector on the parent, and do not turn
+`<span class="font-bold">` into `<b>`. Before submitting a conversion receipt, run
+`npx @bettercms-ai/convert --verify-styles --base <commit before the conversion> --root .` and put
+its `styleEdits` in the receipt; any token it lists is a design change to restore.
+
+### Images
+
+An image the page imports and renders is bound by the codemod, including one the page hands to a
+section component (`<Hero src={heroImage} />` → the component's `<Image src={src}>`): the call site
+reads `bcmsImage(...)` and passes `bcmsBindings`, and the `<Image>` gets
+`data-bcms-field={bcmsBindings?.src} data-bcms-kind="image"`. Keep the `astro:assets` import as
+the fallback; the build renders it and the publish writes the editor's image. Frontmatter images
+(`cardImage: '@/images/blog/post-1.avif'`) become image fields on their own once the build's
+images are in the Media Library, matched by file name. An image rendered inside a loop over a
+list is not bound automatically: bind it in the list's data file.
+
+The codemod knows an image component by its IMPORT, not its name: `Image` and `Picture` from
+`astro:assets` (aliased, or through `import * as assets`), and the default export of
+`next/image` under any name. An import that reaches the page through `getImage()`, `hero.src` or
+a style is refused as `IMAGE_ASSET_UNRESOLVED`, and the row's message names the import: declare
+the element that shows it by hand (`data-bcms-field` + `data-bcms-kind="image"`).
+
+Images need no code at all on a text-matched site. Every release derives an image field for each
+picture a page shows: an `<img>` (its `src`, or where that is a placeholder a lazy loader's
+`data-src`, then the largest `srcset` candidate), a whole `<picture>` as ONE field, a
+`<video poster>`, an inline or STYLESHEET `background-image` (Tailwind `bg-[url(...)]` included)
+and an inline `<svg>`. What it declines is listed with a reason in the binding report's
+`imageGaps`, and everything else it declines in `elementGaps`
+([media-and-brand.md](media-and-brand.md) Where images hide).
+
+Publishing an image keeps the page responsive. A library image re-points every `srcset`
+candidate and each `<source>` at the new picture at that candidate's own width and format, and
+leaves `sizes`, `width`, `loading`, classes, ids and `data-*` as written; never hand-edit those
+after a swap. A stylesheet background gets one inline `background-image` over the rule, removed
+again when the value returns to the sheet's own picture.
+
+To keep an image editable in code you write yourself, render it with `BcmsImage` and its `path`
+(Astro: `@bettercms-ai/astro/components/BcmsImage.astro`; Next: `BcmsImage` from
+`@bettercms-ai/next`): one `<img>` that declares the field, reads the value's alt, crop and focal
+point, and offers a width ladder when given `sizes`.
+
+## 3. Addresses
+
+The grammar is identical in `@bettercms-ai/next` and `@bettercms-ai/astro`; emit it with the SDK
+helpers rather than by hand.
+
+- `data-bcms-field="<address>"` + `data-bcms-kind` on the element whose content is the value.
+- `data-bcms-props="<address>|<kind>|<domAttribute>;…"` for values that live in an attribute
+  (`alt`, `href`, a video `src`). One element carries one field address, so attribute values ride
+  this list. An `href`, an `src` and a `poster` are kind `url` (`cta.href|url|href`, not
+  `|text|`); an `alt` is `text`. The same address on two elements is edited as two copies of one
+  value (numbered `data-node-index`).
+- `<BcmsField path kind as>` binds hand-rendered entry values. Around ONE element it adds no
+  wrapper: the attributes go on that element. Around text or several elements it renders a
+  `display:contents` span, and `as` names a real wrapper. `path` is dotted keys with any
+  number of `[n]` indices: `title`, `hero.title`, `columns[0].links[2].href`.
+- Rich text is addressed per paragraph: `<base>#<_key>`. No write tool takes an address:
+  `update_content_entry` replaces the whole field (it merges by default, keeping the other
+  top-level fields, never other blocks of the same field). The platform's own path writer refuses a
+  `#<_key>` path (`KEYED_PATH_NOT_WRITABLE`), and only the editor patches one block. A `_key` is
+  part of an address, so never regenerate keys of blocks that already exist.
+- **Inside a component instance** the address is `<instanceId>__overrides.<key>`. Block ids
+  inside a component belong to the definition and are shared by every instance, so a
+  definition-scoped address binds to nothing and two instances collide. Use the package `bind` /
+  `bindProps` helpers inside instances; they resolve the instance address for you.
+- **The placement root carries `data-bcms-block="<blockId>"`.** `BcmsBlocks` emits it; without it
+  the Output pane and the section overlay fall back to an ancestor guess.
+- **Chrome is its own lane.** A nav or footer value is
+  `data-bcms-layout-field="layout:<sectionId>:<fieldId>"`, never `data-bcms-field`; the page lane
+  cannot reach a Layout value.
+- **Draft markers come from the SDK.** `BcmsDraftMarker` and the Astro middleware stamp
+  `<html data-bcms-draft="1">`; `BcmsDraftBridge` stamps `data-bcms-canvas="bridge"`. Mount them;
+  never write them by hand. Binding attributes are always rendered and inert for visitors.
+
+## 4. Declared mode, publish, and the report
+
+- Until `set_binding_mode` `{ declaredBindings: true }` the platform text-matches, which holds
+  only while CMS values equal the built copy. Flip it only when the stamped build's report is
+  clean on every route: push, release, read `get_binding_report`, flip, release again, then
+  confirm `mode: "declared"` and `coverage.pending` empty.
+- On a declared site every published value is written into the element that declares it, so the
+  bytes your template renders at build time are replaced on publish; never put markup you need to
+  keep inside a bound element. A value with no element never reaches the page, and one that
+  would corrupt its element is refused and named.
+- Read the report, not the screen. Clean = `coverage.pending` empty and the mode you expect. Each
+  `unmatched` reason names a fix in the source. A field the stamped build renders on no route is flagged `stale: true` on its schema — kept, hidden in the editor, cleared by the release that binds it again — and is not listed. A Global Layout Section is reported only on the
+  routes that render it (`layoutRoutes` lists each route's Sections): a docs page on its own layout
+  is not missing the nav, so never add one there. A `fallback` flag means the build carried no
+  `bcms-brief` meta and was measured against the latest pin. Only a release creates the report;
+  a content apply later updates its Layout rows.
+
+## 5. Preview strings (stega)
+
+Preview responses requested with `stega=1` hide invisible characters inside prose strings so the
+editor can map text back to fields. Two filters decide what is skipped, and you need both:
+
+- by field NAME: `slug`, `url`, `href`, `src`, `id`, `email`, `color`, `icon`, `date`,
+  `datetime`, `locale`, `type`, `target`, `rel`, `_type`, `_key`;
+- by VALUE shape, for fields it cannot recognise by name: anything starting `http:`, `https:`,
+  `mailto:`, `tel:`, `#` or `/`, and ISO dates.
+
+Portable Text arrays and richtext/image envelopes are skipped whole. Never compare, slugify or
+parse a preview string as-is, and never put one in an attribute or SEO output. Compare published
+values, or strip it first with `stripStega` from `@bettercms-ai/sdk`. The editor strips it before
+it saves.
+
+| The string goes to | Strip first? | Why |
+|---|---|---|
+| Visible text a template renders | Never | The markers are how a click finds its field |
+| A Portable Text renderer, `BcmsField`, an image helper | Never | Those values carry no markers; pass them as-is |
+| `===`, `switch`, `includes`, sort order, a lookup key | Always | The hidden characters make equal strings unequal |
+| A React/Astro `key`, an element `id`, a slug, a URL you build | Always | A marked id never matches its published twin |
+| Any HTML attribute (`class`, `href`, `alt`, `aria-label`) | Always | Attributes are not text the editor maps |
+| `<head>`: title, meta, JSON-LD | Always | Crawlers and share cards read the characters |
+| A third-party call (analytics, search, maps, a date parser) | Always | They store or reject what they cannot read |
+
+## 6. Classify an unfamiliar codebase before binding it
+
+Inspect `package.json`, the framework config, route tree, build command, output mode, content
+loaders, deployment config and any existing BetterCMS adapter. Then classify:
+
+1. **First-class adapter**: Astro or Next.js with its BetterCMS package ([astro.md](astro.md),
+   [next.md](next.md)).
+2. **React/Vite or another SDK integration**: find who owns routing and data fetching, call the
+   SDK on the correct side of the server/client boundary, keep an explicit component registry,
+   and state what preview supports. The Astro and Next helpers do not transfer unchanged.
+3. **Static HTML/CSS/JS**: keep the working markup and add a safe content path where supported.
+4. **Other or opaque generated output**: preserve behaviour and produce an adapter plan (fetch
+   typed content, resolve sections and components, render Portable Text, bind editable values,
+   serve media, preview drafts, refresh on publish), marking every unimplemented capability. A
+   source crawl alone never proves full editability.
+
+Use syntax-aware parsing and the build output, never blind string replacement; for bulk stamping
+use the codemod (`npx @bettercms-ai/convert`). Trace the real data flow: where values are
+fetched, normalised, passed as props and rendered. A component that looks like its CMS record but
+still renders hard-coded copy is not connected. Client components never receive server keys.
+
+## 7. Edit-to-render test
+
+1. Pick a safe draft field and record its old value.
+2. Edit it through the dashboard or the MCP; confirm in preview that the intended leaf or
+   attribute changed.
+3. Confirm sibling instances, global layout and other routes behave according to their scope.
+4. Restore the value, or keep the change the user asked for.
+5. After an authorised publish, fetch the public URL cache-busted and check status and body.
+   Repeat for a dynamic entry route and a global element.
+
+## Acceptance
+
+- The site builds with the repository's build command; routes and assets load.
+- Every claimed editable field has a path: schema, reader, component prop, DOM binding, preview,
+  public output.
+- No public secrets, wrong media hosts, unscoped instance ids or hard-coded shadow values.
+- `get_binding_report` for each route is clean, and one value of each bound kind opens the right
+  editor in the Visual Editor.
+- `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.
+
+## Editor setup, proposals and binding decisions
+
+`editor_setup` derives what a build no longer imports: a build brings in SEO/meta, media, brand and
+the models `bcms-content.json` declares; editor setup adds pages, collections, forms, bindings,
+button and section components (when the authoring preference is components), Component Groups and
+the Content sidebar. `get_deploy_status` `editorSetup` reports its state.
+
+The complete brief's `proposals` (page 1, at most 50; `proposalsMore` when there are more) list
+what the last convert found and no field owns: `{ id, kind, target, text, suggested?, evidence? }`.
+`id` is `pr_` and 16 hex and survives re-runs; `target` is a `file:line:col` locator only. Kinds:
+`unaddressable` and `code-candidate` (copy no field owns), `inert` (declared, nothing reads it),
+`mismatch` (declares one path, reads another), `flatten` (two leaves in one element).
+
+Answer them with `editor_setup { declare: [item, …] }` (at most 100 items, one result each;
+`check: true` with `declare` is a dry run that stores nothing):
+
+- `{ op: "accept", ids }` takes each proposal's `suggested` op. A proposal with none refuses.
+- `{ op: "bind", id, path, owner? }` binds the copy to an existing field; `owner` is a route or
+  `layout`. The next convert writes it into the source (a mismatch's declaration is rewritten; an
+  attribute or an expression is reported `manual` in `receipt.decisionsApplied`). A `bind` waits as
+  `decision-pending` until a build proves the new read; one still pending after the next release
+  blocks the gate. A declared element is corrected through its `mismatch` proposal id.
+- `{ op: "code", id, why, system? }` keeps it in code. `why` is one of `runtime`, `external`,
+  `derived`, `stylesheet`, `decorative`, `embed`, `legal`, and the system checks its evidence;
+  without it the item refuses `evidence-missing` (bind it, pick the reason that fits, or a person
+  marks it in Overview). The next convert writes `data-bcms-code-owned="text why:<id>"`; the
+  `code` counts once a build carries it. Each convert re-checks the
+  facts: one whose reason no longer holds becomes `evidence-lost`, blocks the gate, and returns to
+  the proposals to decide again. Facts are same-file only: a value from another file needs a person.
+- `{ op: "reject", ids }` drops the suggestion; the copy stays unaddressable. A person's reject of
+  an AI `code` is its Undo: the next convert removes the token.
+- `{ op: "clear", decisionId }` undoes a decision.
+
+A person's decision beats yours: add `force: true` and a `reason` (shown to them) only when they
+asked for it. Refusals per item: `target-unknown`, `path-not-in-schema`, `owner-mismatch`,
+`locked-by-person`, `slot-mismatch`, `evidence-missing`, `declaration-conflict`, `invalid-item`.
+Until a convert that emits proposals has submitted its receipt, every id refuses `target-unknown`.
+`get_next_steps` `receipt.decisions` counts `stored`, `materialized`, `proven`, `pending` (open
+proposals) and `lost`; stop when `pending` is 0.
+
+### Archive (ZIP) sites
+
+A project with no connected repository and no receipt carrying proposals is an ARCHIVE site: no
+codemod runs, so each release scan mints the proposals itself. `target` is then
+`template|owner|textHash` (owner `page`, `layout` or `entry:<collection>`; Layout copy has template
+`*`, an entry route its collection's `/blog/*`), and translations of a page share one template.
+Decisions are not written into source: every release stamps them into the built HTML wherever
+their anchors (structure, text, nearest declared field) agree 2 of 3, else the row is `lost`
+(`anchor-lost`). A `bind` stamps only when the element's text equals the field's stored value; an
+uploaded copy change loses it (`anchor-text-changed`) and its copy is proposed again. An AI `code`
+for `runtime`, `external`, `derived` or `stylesheet` refuses `evidence-missing` here (there is no
+source to check); `decorative`, `embed` and `legal` are checked on the page, and a person may mark
+any reason. Each such decision lives in BetterCMS, not in the site's code: recommend connecting a
+repository.
+
+Archive sites also take `{ op: "rule", template, match, then }`, one row for every element it
+matches on every route of `template`:
+- `template`: `/`-segments literal or `*`, a trailing `/**`, or `*` alone (every route). No regex.
+- `match`: at least one of `struct` (a proposal's structure anchor), `cls` (one class token),
+  `text` (exact copy); `owner` (`page`, `layout`, `entry`) narrows.
+- `then`: `{ op: "code", why }` or `{ op: "bind", path }`. A bind rule names a `layout` or `entry`
+  owner, and matching more than one element on a route is `ambiguous` there.
+A person beats an AI, then a per-id decision beats a rule; two rules saying different things about
+one element are `declaration-conflict`. On a git site a `rule` refuses `invalid-item`. A lane change
+(a repository connected, or a convert's receipt arriving) loses the other lane's decisions
+(`lane-changed`): decide again on the new proposals.