@bettercms-ai/mcp 0.63.2 → 0.64.0

package/dist/skills/bettercms/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: bettercms
+description: "BetterCMS: build, convert, import, edit, publish and verify BetterCMS sites. Use whenever the user names BetterCMS or its MCP, or the repo has @bettercms-ai/* packages, data-bcms- attributes, bcms-content.json or bcms-rebuild.yml, even when they only say 'make it editable', 'import my site', 'convert this repo', 'add a section', 'fix the schema' or 'publish'. Covers setup, the finish-site workflow, content modeling, components, click-to-edit bindings, Portable Text, media, forms, SEO and launch review. Moving off another CMS: bettercms-migrate. ABM campaigns: bettercms-abm."
+license: MIT
+metadata:
+  author: bettercms
+  version: "0.3.0"
+---
+
+# BetterCMS
+
+The BetterCMS MCP serves its own doctrine, so this skill carries only what the server cannot see:
+your repo's framework wiring, binding attributes, env names, stored value shapes and the traps
+that only show up in code. Read doctrine from the MCP, never from memory:
+
+- Schema, sections, variants, publish order: resource `bettercms://playbook/schema` (§1–§14).
+- Content sidebar organisation: resource `bettercms://playbook/structure`.
+- Guided flows: the `studio` prompt routes to the rest (`convert_site` prompt,
+  `build_site` prompt, `componentize_site` prompt, `propose_schema` prompt, `new_page` prompt,
+  `new_component` prompt, `new_form` prompt, `seo_optimize` prompt, `import-site` prompt,
+  `field-ui` prompt, `edit_layout` prompt for the Global Layout, `generate_landing_pages` prompt
+  for page families from data).
+- Import and modelling rule ids: `CM-01`…`CM-83` in the content-modeling standard.
+
+## Start here
+
+Setting up a project, or asked to "Continue BetterCMS setup"? Read
+[references/getting-started.md](references/getting-started.md) first: it owns the setup phases
+and the resume check. For any other task, read the one reference the table below names.
+
+## Connecting (before your first MCP call)
+
+Listing tools needs no sign-in; the first tool **call** does.
+
+1. **A 401 on the first call is the sign-in, not an error.** The client opens a browser sign-in
+   from the `WWW-Authenticate` header. Tell the user to approve it, then retry that same call.
+2. **If `list_projects` lacks the project id you were given, stop and say so.** Consent binds to
+   the workspace the dashboard had active; ask the user to re-authenticate in the right one.
+   Never continue in whichever project IS listed: that writes into someone else's site.
+3. **Pass `projectId` on every project tool, and never ask the user to re-scope.** A
+   workspace-wide connection reaches every project by naming it per call.
+4. **A refusal for access: call `whoami` first.** It names the principal, the workspace, the
+   scope (project or workspace) and, where visible, the grants (publish, code and deploy,
+   sidebar schema), so you can tell the user which one is missing.
+5. **Unsure how a feature works: `search_docs` before guessing.** A tool that fails oddly, a
+   capability you needed and did not have, or docs that misled you: `give_feedback`, and tell the
+   user you sent it.
+
+## Invariants
+
+These hold on every task. The reference in brackets has the detail and the codes.
+
+1. **Confirm the bound project before any write**: §9 of the schema playbook, then `get_project`.
+   Its `authoringPreference` (components, fields, or null while owed) is asked once, can be
+   re-answered, and is the user's answer, never yours.
+2. **Never create SEO fields** (§5b). Page and entry meta are native columns. [seo.md]
+3. **A page is a list of sections**, never loose top-level blocks. [components.md]
+4. **Nothing is live until it is published, and a page is not its content.** A draft form,
+   component or entry renders nothing live. Read `warnings` on every write: `ENTRY_STILL_DRAFT`
+   and `ENTRY_SEED_FAILED` mean content did not ship. [publishing.md]
+5. **Name the folder system every time you say "folder"**: Content sidebar folders never touch a
+   URL, URL page folders are part of the path, media folders organise assets.
+   [content-modeling.md]
+6. **Headless projects are built by their host.** Never `deploy_project` or
+   `create_deploy_upload` there, never add `bcms-rebuild.yml`; deploy = push to the repo the
+   provider builds. [frameworks.md]
+7. **Every refusal has a code. Report it; do not retry blind.** The same call returns the same
+   code. Change the input or stop.
+8. **Media is served by the backend that owns the asset ids.** `mediaUrl` is `mediaBaseUrl` from
+   `get_project`; never hardcode, re-point or re-host media, and never read a bucket or key.
+   [frameworks.md]
+9. **Bind the leaf that renders the value, one address per element.** Attribute values ride
+   `data-bcms-props`; `data-bcms-kind` declares the container, and the MODEL picks the editor.
+   Inside an instance the address is `<instanceId>__overrides.<key>`; chrome uses
+   `data-bcms-layout-field`. [bindings.md]
+10. **Declared mode is a switch you flip** with `set_binding_mode` after the stamped build reports
+    clean: push, release, report clean, flip, release again. [bindings.md]
+11. **A field is not editable because it exists.** It is editable when its value renders from the
+    CMS on a bound leaf and an edit shows in preview and after publish.
+12. **Bulk work runs as code, not as a chain of tool calls.** Propose the mapping and dry-run it
+    before a high-volume write; use the MCP for state, targeted fixes and reports.
+
+## What you do, and what only the owner does
+
+The MCP acts as the signed-in person. Some decisions are theirs by design: no tool makes them,
+and saying you made one is a false report. Name each as an action in your final message.
+
+| Only the owner | Where |
+|---|---|
+| Authoring preference and media delivery answers | you ask; `set_authoring_preference`, `set_media_delivery` |
+| Visual Approval of a component, CI (GitHub Actions) validation | dashboard |
+| Approving a generated job or a flagged ABM entry | the user's explicit yes before `approve_ai_job` / `approve_campaign_entries` |
+| Brand colours and typography; URL page folders; unpublishing a form | dashboard |
+| Hosting **Run as a server app**; form integrations; the Turnstile secret | dashboard |
+| `llms.txt` and Markdown twin switches | dashboard, SEO permission |
+| Publishing to production | the user's authorization, then the tools |
+
+Secrets never go in a tool call, a `PUBLIC_` variable or a client bundle. A 403
+`SCHEMA_ACCESS_REQUIRED` means the person lacks Admin or Developer access: stop and tell them.
+
+## Which reference to read
+
+Read one reference per phase. Each is self-contained; a second one is needed only when the task
+crosses into its topic. When this skill is not installed, the MCP serves the same files as
+resources: `bettercms://skill/bettercms` for this file, and each reference under its file stem
+(`bettercms://skill/seo` for seo.md).
+
+| Task | Reference | Read when | Keywords |
+|---|---|---|---|
+| 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 |
+| 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 |
+| 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 |
+| Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
+| 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 |
+| Astro adapter | [astro.md](references/astro.md) | the repo has `astro.config.*` | astro.config, Astro, BcmsBlocks, getStaticPaths |
+| Next.js adapter | [next.md](references/next.md) | the repo has `next.config.*` | next.config, Next.js, App Router, ISR, notFound, static export |
+| Nuxt, SvelteKit, React Router, Vite: no adapter | [other-frameworks.md](references/other-frameworks.md) | neither `astro.config.*` nor `next.config.*`; `nuxt.config.*`, `svelte.config.*`, `react-router.config.*` | Nuxt, SvelteKit, React Router, Vite, createClient |
+| Rich text and field types | [portable-text.md](references/portable-text.md) | writing a richtext value; converting HTML or Markdown | rich text, Portable Text, richtext, HTML, Markdown |
+| 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 |
+| 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 |
+| A/B tests on section variants | [content-experiments.md](references/content-experiments.md) | an experiment plan or readout | A/B test, experiment, variant test |
+| Headless Shopify storefront | [shopify-headless.md](references/shopify-headless.md) | Shopify owns commerce, BetterCMS the editorial | Shopify, Hydrogen, storefront, product |
+
+Other sites move into BetterCMS with the `bettercms-migrate` skill; per-account campaign pages
+are the `bettercms-abm` skill.
+
+## Context budget
+
+A whole-site job outlives one context window. Spend it on the site, not on re-reading.
+
+- Start from the receipt: `get_next_steps` returns `receipt.done`, `receipt.missing` and
+  `receipt.nextAction`. Plan the session from it, not from re-reading the site.
+- Hold SKILL.md plus only the ONE reference the current phase needs; drop it when the phase ends.
+- Ask the MCP for summaries before reading files: `get_site_composition`, `get_binding_report`
+  and `get_next_steps` answer "what is left" in a few hundred tokens, where built HTML or a whole
+  repo costs tens of thousands.
+- Run bulk edits through the codemod (`npx @bettercms-ai/convert`), not file-by-file hand edits
+  in context; read its receipt, not the diff.
+- Keep the gap ledger in `.bettercms/ledger.json` in the repo (shape in finish-site.md) and
+  re-read it after a reset instead of carrying it in chat.
+- Where your agent supports subagents, fan out per-route verification and have each return only
+  its verdict and the failing evidence.
+- Pass the `projectId` you already have; never re-list projects to find it again.
+- After a reset, say "Continue BetterCMS setup": the resume check rebuilds state from the MCP and
+  the ledger.
+
+## Verify loop (after every change, before you say "done")
+
+Stop at the first step that is not clean, fix, then restart. A report that does not exist yet is
+"not yet generated", which is not the same as dirty; say which.
+
+1. **Fetch the live URL**, cache-busted: a 200 whose body contains copy you just published. The
+   steps below read the control plane, and all of them can be green on a site that answers 404.
+2. `get_binding_report` for every route you touched: `coverage.pending` empty, and
+   `mode: "declared"` on a declared site. `refreshReason: "never-generated"` means no BetterCMS
+   release wrote one (on headless none ever will, so step 1 is the proof); `"outdated"` means
+   the next release rewrites it.
+3. `get_site_composition`: every page you touched is made of sections, with the intended
+   components.
+4. `list_seo_issues`: no issue on a page you created or edited.
+5. `get_next_steps`: nothing left that belongs to your task; owner actions go in your final
+   message by name.
+
+"Done" means the loop is clean, not that a tool call returned 200.

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

@@ -0,0 +1,67 @@
+---
+title: "Astro adapter"
+description: "The @bettercms-ai/astro integration: options and env precedence, draft preview, shipped components, bindings and Astro-specific traps."
+---
+
+# @bettercms-ai/astro
+
+Read this when the repo has `astro.config.*`. Shared rules (hosting modes, env map, tags, value
+shapes) are in [frameworks.md](frameworks.md).
+
+## Integration
+
+Add `bettercms()` to `integrations` in `astro.config.*`. It:
+
+- adds the `@bettercms-ai/astro/middleware` middleware (order `pre`);
+- injects `/api/bcms/draft/enable` and `/api/bcms/draft/disable`;
+- sets a signed `bcms-draft` cookie when draft mode is enabled.
+
+Options win over env, env wins over the snapshot: `apiUrl` → `PUBLIC_BCMS_API_URL` → snapshot,
+`workspace` → `PUBLIC_BCMS_WORKSPACE` → snapshot, `projectId` → `PUBLIC_BCMS_PROJECT_ID`,
+`mediaUrl` → `PUBLIC_BCMS_MEDIA_URL` → the production CDN, `studioUrl` →
+`PUBLIC_BCMS_STUDIO_URL` (no default).
+
+`draft` defaults to `true`, which injects two ON-DEMAND routes (`/api/bcms/draft/{enable,disable}`).
+A static build with no server adapter then fails with `NoAdapterInstalled`. On a static site pass
+`bettercms({ draft: false })`; draft preview needs an adapter AND the Hosting page set to Run as a
+server app (see Hosting modes).
+
+`astro.config.*` runs before Astro loads `.env`, so `PUBLIC_BCMS_*` is empty there on a local
+build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them.
+
+## Draft preview
+
+- Set `BCMS_DRAFT_SECRET` on the server. Without it `/api/bcms/draft/enable` answers 500.
+- The draft routes run on request, so the site needs an on-demand adapter (node, vercel, netlify,
+  cloudflare). A fully static build serves the published snapshot only.
+
+## Components shipped
+
+| Import | Use |
+|---|---|
+| `@bettercms-ai/astro/components/BcmsBlocks.astro` | Server render of a block tree. Pass `components` or instances render nothing |
+| `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | Same tree as a hydrated island that follows the editor's draft bridge |
+| `@bettercms-ai/astro/components/BcmsField.astro` | `path`, `kind` (`richtext`/`image`), `as`; emits `data-bcms-field` + `data-bcms-kind` |
+| `@bettercms-ai/astro/components/BcmsForm.astro` | Renders a delivered form and submits it ([forms-and-interactions.md](forms-and-interactions.md)) |
+
+`BcmsLiveBlocks` rules:
+
+- It needs a React-compatible renderer: add `preact({ compat: true })` next to `bettercms()`.
+- Its CSS class names differ from `BcmsBlocks`. Swapping one for the other unstyles a page unless
+  your stylesheet covers both spellings.
+
+## Bindings
+
+`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
+([bindings.md](bindings.md) §3).
+
+## Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Resized images 404 on a non-production site | `mediaUrl` still the production default | Set `PUBLIC_BCMS_MEDIA_URL` to that rung's API origin |
+| Resized images still on the CDN after moving media | `mediaUrl` not changed | Set it to `mediaBaseUrl` from `get_project` |
+| Component instances empty | `components` prop missing | Pass definitions to `BcmsBlocks` |
+| Draft link 500 | `BCMS_DRAFT_SECRET` unset | Set it on the server env, redeploy |
+| `ReferenceError: X is not defined` from a `[slug].astro` route | `getStaticPaths()` reads a `const` declared in the frontmatter; Astro runs it in its own scope, before the page, seeing only imports | Declare the client or reader call inside `getStaticPaths`, or import it from a module |

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

@@ -0,0 +1,201 @@
+---
+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
+replaces what is inside the element it names. Bind a `<section>` or a card and the band's own
+markup is what you overwrite; the page comes back as bare text where a layout used to be.
+
+`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.
+- **SVG text is never bound.** The platform does not read inside an `<svg>`: no field is derived
+  from its text and no binding there is measured. An icon is media: upload it with
+  `create_media_upload` and bind the `<img>` as an `image`, or leave it in code.
+- **Icon-only links in the nav and footer** take their field name from the anchor's
+  `aria-label`, then the SVG `<title>`. Give each one an `aria-label`, or every social link is
+  named `link` and an editor cannot tell them apart.
+
+### 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.
+
+## 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>` wraps hand-rendered entry values. `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 (with `merge: true` it keeps 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 `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.

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

@@ -0,0 +1,106 @@
+---
+title: "Componentizing a site"
+description: "Turn a derived, fields-only site into sections backed by components: reading the plan, confirming it, applying it, and the repository half with its receipt."
+---
+
+# Componentizing a site, and deciding what each band becomes
+
+Read with [components.md](components.md); § numbers below are that file's. Doctrine: §10 of
+`bettercms://playbook/schema`.
+
+## 1. Classify every band first
+
+Look at the source component, the rendered band, its CSS and its props on every route before
+deciding. Matching copy or a shared class name does not make two bands one component.
+
+| Band | Becomes |
+|---|---|
+| Navigation, footer, a truly sitewide bar | Chrome: a component in the Global Layout (§4) |
+| Same structure and the same editor fields on several pages | One component; layout differences are variants of one `sectionType` |
+| Different content contract (other fields, other order) | Its own family, even when it looks alike |
+| Genuinely unique | Still a section: a one-off `section` block or a single-use component |
+| Card, button, badge, quote inside a section | Part of that section: a `group`/`table` prop, or a nested component |
+
+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.
+
+Never let a component contain itself, directly or through a child.
+
+## 2. The componentize lane (a site whose pages were derived at import)
+
+1. `get_componentize_plan { summary: true }` first (no values; the full plan is hundreds of KB,
+   and `paged: true` reads it 10 pages at a time). It creates nothing and is computed live from
+   the PUBLISHED pages. Each field group is one section, and every page gets its OWN components
+   (`home-hero`, `about-hero`); a locale copy reuses its default page's. A collection template
+   (`pattern: "{slug}"`) is planned once and every prop reads the entry being rendered: only its
+   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). Author the real
+   sections among those with `create_component` and `set_page_content` instead.
+2. Show the user the sections, how many components it creates and which pages it rewrites.
+   Confirm before writing. A group the user says is not a section: `componentize_sections
+   { digest, sections: [groupKey], pageIds, decline: true }` (`decline: false` undoes it). The
+   plan is done when it proposes nothing that was not declined.
+3. `componentize_sections` with the plan's `digest` and `dryRun: true`. Read
+   `components.wouldDuplicate` (§8). A 409 `stale-plan` means the site changed: read the plan
+   again and confirm again. Then run it for real.
+4. What it writes: each component as a DRAFT, and each page's draft blocks as an ordered list of
+   instances. By default each instance carries `props.bind` and the words stay in the page's
+   field group, so bindings and the coverage meter do not move. `copy: "instance"` moves the
+   words onto each placement and marks the old fields `origin: "componentized"`; nothing is
+   deleted. Running it twice is safe: an existing placement comes back as
+   `ALREADY_COMPONENTIZED`.
+5. `publish_component` for each, then publish the pages. An unpublished component renders
+   nothing on the live site.
+6. In the repo, run the codemod with `--componentize` and a `--receipt` file, commit and push the
+   files it wrote, and hand that receipt verbatim to `submit_componentize_receipt`. It records
+   each extracted section as the source of the component with the same slug, so no
+   `set_component_source` per component is needed. Deploy.
+7. Output validation, from step 3 of §6.
+
+## 3. Names and groups
+
+Name a family by what it is (`Hero`, `CTA`, `Testimonials`) and each variant by how it looks
+(`Hero / Split`, `CTA / Centered`). Never put a page name in a reusable definition; which pages
+use it is a usage question (§8). The componentize lane files a section under its page's slug
+(`home-hero`) but keeps the name the section's own (`Hero`). Keep related fields together in the
+order an editor reads them:
+
+```text
+Hero / Split
+  Heading · Description
+  Primary button: Label · Link · Style
+  Secondary button: Label · Link · Style
+  Image: Asset · Alt text
+```
+
+Expose variants and style tokens, never raw class names, CSS strings or HTML.
+
+**Name props from the code, not the copy.** An import labels a prop by its role (`Text`,
+`Heading`) with its copy as help text (`e.g. "49"`), and older imports by the copy itself (`.00`).
+Read the section's source and use its own names: `pricing.starterKit.cents` → `Cents`,
+`billingFrequency` → `Billing frequency`. Give every prop help text showing its shape
+(`e.g. "USD / monthly"`). Apply both in one `update_component` call: `propLabel` and
+`propHelpText`, keyed by prop key. Repeated cards (plans, features, team members) are ONE `table`
+prop whose rows are the cards (`Plans`: Name · Description · Price · Cents · Billing frequency ·
+Features · Button), never a set of props per card, so an editor opens one plan at a time and can
+add a third. `get_next_steps` lists `labels-are-copy` until every field is named.
+
+## 4. Proof, per family
+
+A write that returned 200 proves nothing about the page. For each family, check in the preview
+and after publish:
+
+- one default edit reaches every instance without an override, and no other;
+- one instance override changes only that placement;
+- one variant swap keeps the content (read the swap warnings, §3);
+- one nested child edit stays inside its own instance;
+- one chrome edit reaches every route.
+
+Then `get_binding_report` and `get_site_composition` (§9).