@bettercms-ai/mcp 0.63.2 → 0.64.0

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

@@ -0,0 +1,228 @@
+---
+title: "Components, props and variants"
+description: "The prop contract, instances, sectionType families and variants, publishing codes, rendering components in a site, preview source and component groups."
+---
+
+# Components, props and section variants
+
+Doctrine (components vs collections, section anatomy, variants): §3 and §4 of
+`bettercms://playbook/schema`; flows: `new_component` prompt, `componentize_site` prompt. This
+reference is what the code does with what you write. Componentizing a derived site end to end:
+[componentize.md](componentize.md).
+
+## 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`.
+- `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.
+- `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.
+- `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 `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
+  strip — you find out at the write, not at the render.
+- A draft form is a 403 at every public ingress, so it renders nothing on the live site. Publish
+  it before pointing a component at it.
+
+### Where a form prop actually renders
+
+The prop binds which form. What the READER does with it depends on how the component was built,
+and only the first row below changes the rendered fields:
+
+| Component | Preview / Output | The form comes from | Does the prop change the fields? |
+|---|---|---|---|
+| Built from blocks (a `form` block in `blockJson`) | no Output — Output needs a recorded source file | the renderer's forms map | **yes**, on the live site and the page preview |
+| A component that renders `<BcmsForm>` / `<BcmsBlocks forms>` | yes | a forms catalogue passed beside the blocks | yes, where the catalogue reaches it |
+| A codemod section (`@bettercms-ai/convert`) | yes | static markup; convert stamps `data-bcms-form` onto the existing `<form>` | no — the fields are hand-written HTML |
+| A page route that fetches `/forms/public/:id` itself | inert (page-kind Output never runs scripts) | its own fetch | no |
+
+## 2. Instances
+
+A placed component is a block `{ type: "component", props: { componentId, overrides?, bind?,
+source? } }`.
+
+- `overrides` is keyed by prop `key`. Rendering walks the definition's props and takes an
+  override only for a declared key. An override under any other key is ignored.
+- A richtext override is a Portable Text array ([portable-text.md](portable-text.md)).
+- Inside an instance, edit addresses are `<instanceId>__overrides.<key>`.
+
+## 3. Sections, families and variants
+
+- A page is made of sections. A band used on more than one page, or with layout variants, is a
+  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.
+- **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.
+- **Spell `sectionType` exactly the same on every variant**, same case, no spaces. Why: the
+  backend (including the key-drift check) groups families case-insensitively but the dashboard
+  picker only trims, so "Hero" and "hero" are one family to the backend and two in the picker.
+- **Every variant in a family declares the same prop keys with the same types.** Why: a variant
+  swap changes only `componentId`; the overrides stay, and only keys the new variant declares
+  are rendered. A key the new variant lacks is dropped from view; a key with a different type
+  renders wrong.
+- Before swapping, compare `get_component` props of both variants. If keys differ, tell the user
+  which values will not show.
+- **A card's or badge's looks are a `variant` select prop, not a family.** A card that comes as
+  Default, Featured and Outline is ONE component with a `select` prop keyed `variant` whose options
+  are the looks, and its markup picks classes from that value. Why: an editor switches the look in
+  place and the content stays put, and the library holds one card, not three. Families of looks
+  (`variantOf`, a style select on every section that places them) are for buttons: a new button
+  look is `get_component`, then `create_component` with `variantOf` naming the base.
+- Read `warnings` and act on them; they never block the write:
+  - `create_component` / `update_component`: `VARIANT_PROP_KEYS_MISMATCH` (a key no sibling
+    declares, or one siblings declare that this variant lacks) and `VARIANT_PROP_TYPE_MISMATCH`
+    (same key, different type).
+  - `update_page` with `blockJson` that swaps a component block: `COMPONENT_SWAP_DROPS_OVERRIDES`
+    (overrides the new component does not render; they stay on the block, so swapping back
+    restores them) and `COMPONENT_SWAP_PROP_TYPE_CHANGED`.
+
+Pitfalls of a component library:
+
+| Pitfall | Signal | Fix |
+|---|---|---|
+| A variant needs keys its siblings lack | `VARIANT_PROP_KEYS_MISMATCH` on every write to it | It is a different band: give it its own `sectionType` family |
+| Near-identical components in separate families ("Hero", "Hero 2", "Home hero") | Several families whose `get_component` props match | One family, variants by layout; every extra family is one more choice in "Add a section" |
+| A component nobody can insert | its id in `get_site_composition` `notInPicker` | Set its `sectionType` |
+| Components nothing places | ids in `get_site_composition` `unused` | Place them or name them to the user; deleting a component is a dashboard action |
+| A required prop left empty | `emptyRequiredProps` on a placement | Fill it; `required` is not enforced on write |
+| Props labelled by their copy or a generic role ("Text") | `get_next_steps` lists `labels-are-copy` | Label and help-text each prop from the site's code (`update_component` `propLabel`, `propHelpText`) |
+| Repeated cards as one prop per card | `plan1Title`, `plan2Title`… | One list prop whose rows are the cards |
+
+## 4. Publishing
+
+Publish with `publish_component` or `publish_components` (batch). A refusal is a 409 with a code.
+Handle by code, never by retrying the same call:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `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_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 |
+
+### Site chrome (navigation and footer)
+
+A new project's navigation and footer are draft components placed in a draft Global Layout.
+Nothing of the chrome is live until all three are published, in this order:
+
+1. `publish_component` for navigation-default and footer-default. Each can be published while the
+   other is still draft; the publish is refused only for problems it would itself create.
+2. `publish_layout` with the revision from `get_layout`.
+3. `get_layout` with copy "published" to confirm.
+
+The navigation's logo is optional. When it is empty, the nav shows the brand mark
+(`set_brand_assets`) or the site name. Never generate or add a logo the site does not have. A
+page that renders its own header or footer does not get the Layout's copy on top of it.
+
+## 5. Rendering components in your site
+
+- **Next**: `readComponents()` from `@bettercms-ai/next` reads definitions from the
+  `bcms-content.json` snapshot. Pass them to `<BcmsBlocks components={…}>`; each `component`
+  block is resolved by applying its overrides to the definition.
+- **Astro**: `BcmsBlocks.astro` takes the same `components` prop. Without it every instance
+  renders nothing. Get definitions from `readComponents()` of `@bettercms-ai/next` or the
+  delivery components endpoint.
+- **SDK only**: `listComponents()` on the read client.
+
+Rule: if an instance renders empty, check that definitions were passed before debugging the
+component.
+
+## 6. Preview source
+
+- `set_component_source` records which file in the repo implements a component;
+  `clear_component_source` removes it. Previews and validation read this mapping.
+- **Call it as soon as you write the file, not at the end of the job.** Why: until the mapping
+  exists a preview refuses with `COMPONENT_SOURCE_NOT_RECORDED`, and that refusal arrives later,
+  in the dashboard, to whoever opened the component — not to you while you still have the path in
+  hand.
+- `@bettercms-ai/preview-runtime` builds component previews for Next and Astro apps and validates
+  components in CI. `@bettercms-ai/component-output` verifies preview sessions and runs the
+  preview bridge in your app.
+
+### Output validation
+
+A component's Output (its live preview) shows only after a validation run renders it. The run
+renders the component from its recorded file, or cuts it out of the deployed page by its
+`data-bcms-block` attribute. A component with neither has nothing to render, so its validation
+can only fail.
+
+Do these steps in order, every time you create or componentize a component:
+
+1. Make it renderable. Either call `set_component_source` with the file that renders it, or, after
+   `componentize_sections`, put each `blockId` from the receipt's `stamps` on its section root as
+   `data-bcms-block` (or run `npx @bettercms-ai/convert --componentize`, then
+   `submit_componentize_receipt`).
+2. Deploy, so the build that validation renders contains that markup.
+3. `get_component_readiness`. If `validation.gap` is set, do what `validation.fix` says first.
+4. `declare_component_route` only when the app serves previews somewhere other than the default route.
+5. `request_component_validation`. It refuses with 422 and the fix when nothing renders the
+   component, and opens no request.
+6. In the app's repository, run
+   `npx @bettercms-ai/preview-runtime validate --local --request <requestId>` with `BCMS_API_URL`,
+   `BCMS_API_KEY` (a project key with artifact write), `BCMS_PROJECT_ID` and `BCMS_PREVIEW_ORIGIN`
+   set in the environment. Never put a key in a tool call.
+7. `get_component_readiness` again. `outputReady` means the Output renders.
+
+Rules:
+
+- Your evidence is self-attested. Publishing still needs the owner's Visual Approval in the
+  dashboard. No tool gives it: never say you approved a component.
+- CI validation (GitHub Actions) runs in the owner's repository at the owner's cost. The tool
+  refuses it with "VALIDATION_PROVIDER_DASHBOARD_ONLY". Ask the owner to start it from the dashboard.
+- A validation failure naming "COMPONENT_SOURCE_NOT_RECORDED" means step 1 or 2 was skipped. It is
+  not a bug in the component.
+
+## 7. The values popover (dashboard)
+
+Where you edit decides what you change:
+
+- On a **placed instance** (a page body or rich-text field): the edit writes that instance's
+  override. Only this placement changes.
+- On the **component's own canvas**: the edit writes the default of the variant being edited
+  (Base, or the open variant). Every instance without an override changes.
+
+Rule: when the user says "change it on this page", edit the instance; "change it everywhere",
+edit the default. Say which one you did.
+
+## 8. Groups
+
+Components are organised into `component_groups` (the folders of the Components tab). A component
+`componentize_sections` creates belongs to ONE page, so it is filed by that page, not by family.
+
+- `componentize_sections` files every component it creates: under `group` when you pass one
+  (found or created by name); otherwise an MCP or release run files it under its page's folder,
+  `Sections/<Page title>` (`Sections/<Page title>/<pattern>` for a template), and a dashboard or
+  studio run leaves it unfiled. The receipt's `components.groups` lists the Groups it filed into.
+  A reused component keeps its Group.
+- Sections a release imports are filed the same way, after the release.
+- `componentize_sections` reuses a component by identity and slug, never by family, so a
+  hand-built `Hero / Split` is not picked for a derived hero band. Run `dryRun: true` and read
+  `components.wouldDuplicate`: each id is an existing same-family component the run would sit a
+  new one beside. Decide with the user before applying.
+- Components componentized from the dashboard are not filed automatically.
+- File one yourself with `create_component` or `update_component` `group` (by name).
+
+Which pages use a component is computed on request by searching page and entry JSON; it is not a
+stored list.
+
+## 9. Verify
+
+1. `get_component` on each component you changed: props complete, `sectionType` spelled like its
+   siblings.
+2. `get_site_composition`: every page is sections; every component you meant to publish is
+   published.
+3. `get_binding_report` on a page that uses the component: instance values bind.

package/dist/skills/bettercms/references/content-experiments.md

@@ -0,0 +1,62 @@
+---
+title: "Content experiments"
+description: "A/B tests on section variants: hypothesis, design, readout and pitfalls."
+---
+
+# Content experiments on section variants
+
+**Outcome.** Editors manage approved variant content, the runtime serves a reproducible
+experiment, and measurement answers the question that was asked. A component variant is a
+presentation option. It is not an A/B test until something assigns, exposes and measures it.
+
+## Decide whether an experiment is viable
+
+Read the connected project (`get_project`) and the site's analytics and consent setup. Write
+down one hypothesis, the primary metric, guardrail metrics, the audience, the unit of assignment
+(user, session or account), the baseline, the planned duration and the stop rules.
+
+Check the MCP tool list for experiment assignment, exposure events or reporting. When none is
+there, assignment and measurement live in a dedicated code or analytics service; BetterCMS owns
+the variant definitions and the editorial values only. Say that to the user rather than implying
+the dashboard runs the test.
+
+Do not start a test when traffic is too low for a useful result, the metric cannot be observed,
+or a legal or consent dependency is unresolved. A plain launch or a qualitative study is the
+better answer there.
+
+## Model and serve variants
+
+- **Treatments are variants of one family.** Components that share a `sectionType` are one
+  family, and every variant declares the same prop keys with the same types. Why: a swap changes
+  only `componentId`, so a key the other variant lacks is silently not rendered. Read both with
+  `get_component` before the test starts; detail in [components.md](components.md) §3.
+- **Keep a stable control.** Freeze the control's copy and tokens for the run, so an unrelated
+  edit does not change the test mid-flight.
+- **Instance override versus default.** An edit on a placed instance writes that placement's
+  override; an edit on the component canvas writes the variant's default and reaches every
+  instance without an override. Decide which one the treatment is before anyone edits.
+- **A swap warns, it does not block.** `update_page` answers a swap that would hide overrides
+  with `COMPONENT_SWAP_DROPS_OVERRIDES` or `COMPONENT_SWAP_PROP_TYPE_CHANGED`. Read the warnings
+  before calling a treatment ready.
+- **Publish both.** A draft component renders nothing on the live site, and publishing copies
+  the draft to live; an unpublished treatment is an empty band, not a variant.
+
+Preview every variant at desktop and mobile widths in its real route. Assignment must be
+sticky for the chosen unit; avoid sending both variants to one person through cache keys,
+server/client hydration or locale routing. Emit an exposure only when the variant was shown.
+Follow the site's consent settings for analytics and personalization. Keep accessible names,
+forms, pricing facts and critical navigation equivalent unless the experiment tests them on
+purpose and the risk is reviewed. Crawlers should see a stable canonical route, never cloaked
+content.
+
+## Measure and finish
+
+Fix the analysis window and the decision rule before reading results. Check sample imbalance,
+missing exposure events, bot and internal traffic, cross-device leakage and guardrail
+regressions before interpreting any uplift. Report the observed estimate with its uncertainty,
+never a guaranteed improvement.
+
+A winner is promoted by an explicit change: make it the default, or set the instances, then
+publish and verify through the normal release path ([publishing.md](publishing.md)). Archive the
+hypothesis, the variants, the measurement definition, the result and the rollback point. Keep
+the losing variant while it is needed for audit or rollback.

package/dist/skills/bettercms/references/content-modeling.md

@@ -0,0 +1,185 @@
+---
+title: "Structure and content modeling"
+description: "Pages vs collections, the four folder layers, field decisions and naming, and changing a schema safely, including retiring a field in stages."
+---
+
+# Structure and content modeling
+
+**Outcome.** A content tree an editor understands on day one, durable relationships between
+records, no accidental URL change, and model changes that every consuming site builds against.
+
+Doctrine: §1–§5 and §14 of `bettercms://playbook/schema` (schema shape and sections) and
+`bettercms://playbook/structure` (sidebar); flow: `propose_schema` prompt; rule ids
+`CM-10`…`CM-14`, `CM-40`…`CM-44`. What the server does and does not check on a write:
+[write-limits.md](write-limits.md). Planning a whole site by business type:
+[site-blueprints.md](site-blueprints.md).
+
+## 1. Read the site before modeling
+
+Inventory route files and rendered routes, source data schemas, repeated records, page templates,
+navigation, taxonomies, authors, tags, media references, SEO, forms, locales and publishing
+states. Compare with the project's pages, collections and entries (`list_pages`,
+`list_content_models`, `get_content_structure`). Note where a value is shared, where it is an
+instance override, and where one entry owns it outright.
+
+## 2. Pages, collections and entries
+
+A page is `singleton` (one page and its own content: home, about, a legal page) or `dynamic`
+(one template page whose collection entries each render at the page's path plus the entry slug).
+Choose by repetition: a shape that repeats per item is a collection; a one-off is a singleton,
+even when it lists items, because the list page reads the collection. A dynamic page is its
+collection: the model and its entries both point at the page (`content_models.page_id`,
+`content_entries.page_id`), so never create a separate page per entry.
+
+| Source pattern | BetterCMS destination |
+|---|---|
+| Home, about, contact, legal, editorial landing page | Singleton page with its own content |
+| Blog / case-study / product list URL | A list page plus a separate collection |
+| Repeated records sharing one template | One collection and one dynamic detail page |
+| 404, search, gated page | A page that keeps its access and noindex behaviour |
+| Author, category, tag, company reused by entries | A shared collection, referenced from the entries |
+| Data from an external runtime API | Keep the adapter and its owner; never fabricate entries |
+| Sitewide nav, footer, promo bar | Global Layout, never copied page fields |
+
+## 3. Four structure layers, four meanings
+
+Name the layer every time you say "folder". The answer to "where does X live" differs per layer.
+
+1. **Content sidebar folders** organise the dashboard only: nothing here reads or writes a URL,
+   slug, schema, content or publish state. Read with `get_content_structure`, get a proposal from
+   `suggest_content_structure`, apply it whole with `set_content_structure` once the user agrees,
+   or change one thing with `create_folder`, `rename_folder`, `move_to_folder` or `delete_folder`
+   (deleting a folder moves its contents up). `set_content_structure` replaces the whole document:
+   send the `version` you read; a 412 `VERSION_CONFLICT` means someone changed it, so read and
+   re-apply. It refuses duplicate folder ids, a parent not in the doc, a cycle, and nesting deeper
+   than 4. The standard pins the home page and each list page at the top, gives each content
+   family one folder named for its detail type (the list page and its collection are two items),
+   keeps other standalone pages in Other pages, taxonomies used by two or more families in
+   Shared, and Settings last. Components are not sidebar items. Whether folders show depends on a
+   dashboard feature flag, so an empty sidebar is not proof the structure is missing.
+2. **URL page folders** are part of a page's path unless set not to be included in it. Renaming
+   or moving one 301s every affected URL and queues a rebuild: a routing change that needs the
+   user's review. They are set in the dashboard, not through the sidebar tools.
+3. **Component groups** (`component_groups`) organise definitions by family or role
+   (Navigation, Hero, CTA, Forms), never by the page that uses them ([components.md](components.md) §8).
+4. **Media library folders** organise assets (`folderId` on `create_media_upload`) and never
+   rewrite a stored content URL.
+
+What reads published structure: the sitemap (skips noindex pages), robots.txt (points at the
+sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item).
+
+## 4. Field decisions
+
+- **Model each visual band as a `group` field (or a repeater), or a component instance.** The
+  schema's shape decides whether the site can ever be componentized. The componentize lane finds
+  a section in a `group`, a repeater, or two or more top-level keys sharing a prefix before `-` or
+  `_` (`"hero_title"` + `"hero_subtitle"` → `hero`). A key with NO shared prefix (`title`,
+  `intro`) is a lone scalar, refused `NOT_A_SECTION`. Keep ONE separator per band: a `-` family
+  and a `_` family never share a component. A `group` is the robust choice, and child keys inside
+  it follow the flat-namespace rule (`"hero_title"`).
+- A collection for an entity with its own lifecycle and relationships; a nested group for values
+  one page or section owns.
+- A reference for reusable entities and internal links where the model supports it; an external
+  URL for links that leave the site.
+- A repeater for small, same-shaped items (cards, FAQ rows, links, social accounts); a nested
+  component or slot when an item has its own layout or variants.
+- Never model SEO columns ([seo.md](seo.md)), Form questions (they live on the Form document) or
+  Global Layout values as content fields.
+- Keep source ids, slugs, locale, status and previous URLs as migration metadata, stable across
+  re-imports.
+- **Prefer a `select` over a `boolean` for a state that may grow** (`draft | review | live`, not
+  `isLive`). Why: no tool retypes a field, so a third state later costs a new field and a value
+  migration (§6).
+- Choose field types before the first write. A `link` accepts any scheme-less href (`/about`,
+  `about.html`, `#section`) and `http(s):`, `mailto:`, `tel:`; every other scheme is refused.
+  Choose the type from what the rendered value is, not habit ([portable-text.md](portable-text.md)).
+
+## 5. Editor labels and order
+
+**Name for meaning, not look.** Before writing a key or label, ask: would the name survive a
+redesign? `ctaText`, `authorBio` and `features` pass; `blueButton`, `leftColumn` and `bigHeading`
+fail, because the next redesign makes them lie.
+
+Short labels named for what the editor sees: Heading, Body, Primary button, Label, Link, Image,
+Alt text — or the name the site's code already uses (`cents` → Cents), never the copy itself
+(`.00`). Every field gets help text showing its shape (`e.g. "49"`). Group by what renders
+together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Help text states an effect ("Shown below the
+heading on this page"). Repeatable items need a meaningful preview label (the FAQ question, the
+button label), reorder, and stable item ids. An empty optional field removes its element without
+leaving a gap; a long value wraps, and clamps only where the design intends it.
+
+## 6. Changing a schema safely
+
+A schema write alone is not a release. Before one, read the model with `get_content_model`, a few
+sample entries, the component definitions that touch it and the frontend readers, and write a
+before/after field map: key, type, label, required, default, validation, editor group, and what
+happens to existing values.
+
+1. **Guard concurrent edits.** Pass the model's `optimisticVersion` as `ifMatch` to
+   `update_content_model`. A 409 means it changed since you read it: re-read and re-plan, never
+   resend. Omitted, the last write wins, except on the editor-chrome args, which refuse without
+   it (428).
+2. **Know what the MCP can do.** `add_field` (a model's `modelId` or a page's `pageId`) appends
+   and never overwrites or retypes. `update_field` changes ONE existing field, addressed by a dot
+   path through its groups and repeaters (`hero.title`): its label, help text, `required`,
+   validation `config` (merged by key; null deletes one), `showIf`, `ui` or placement, written at
+   the version it read. A retype needs `allowRetype: true`, because stored values that do not fit
+   the new type are lost; a key rename needs the migration in step 3. `update_content_model` edits
+   the model's name, slug, URL pattern and fieldsets, and removes model fields only with
+   `removeFields` (step 3). The home page cannot be deleted, and changing a local type file is not
+   a schema change.
+3. **Retire or rename a field in stages, never in one write.** Renaming a key re-addresses its
+   content: `update_field` with a new `key` is refused with 409 and the count of entries holding
+   the old key, unless `allowFieldRemoval: true` discards their values. So a rename is a new field
+   plus a migration:
+   1. Relabel the old field "Old title (Deprecated)" and set help text naming its replacement
+      (`update_field` `label` and `helpText`).
+   2. Move it into a `collapsed: true` fieldset so editors stop reaching for it
+      ([editor-chrome.md](editor-chrome.md) §2).
+   3. Add the replacement (`add_field`, with `modelId` or `pageId`) with the final type and name.
+   4. Migrate values in code, draft first, and have the frontend read the new key.
+   5. Remove the old one. Page fields: `remove_page_fields` (dry run by default) returns
+      `keysWithContent` and writes nothing; read it, then run it with `dryRun: false` and
+      `discardContent: true` only for keys you migrated. Model fields: `update_content_model` with
+      `removeFields: ["oldKey"]` and `allowFieldRemoval: true`, sent with the `ifMatch` of your
+      read. It has NO dry run and discards that key's value in every entry, so count the entries
+      holding it first (`list_content_entries` with `modelId`: `meta.total` is the count, `page`
+      walks past the 200-row `limit`). Top-level keys only; an unknown key refuses the
+      whole call; a page's own fields go through `remove_page_fields`. Both discard data: removal
+      is the last step, with the user's yes.
+   Why: every stage before 5 is reversible, and a site built against the old key keeps rendering
+   until its next release reads the new one.
+4. **Put numeric limits in `config` as numbers** (`"maxLength": 60`), with `update_field` on a
+   field that exists. A numeric string is converted on save; an impossible value is refused with
+   `FIELD_CONFIG_INVALID`.
+5. **Check existing records before tightening validation.** Backfill or give a real default
+   before making a field required; keep a source-to-target map and a snapshot for any high-volume
+   transform.
+6. **Validate on a draft.** Entries written through the MCP pass one write path (request schema,
+   normalisation, per-field checks, uniqueness), and a write failing any step stores nothing.
+   Publishing copies the draft to live, so a draft that passes is the value that ships.
+7. **Change a component family together** (same prop keys and types on every variant;
+   [components.md](components.md) §1 and §3).
+8. **Regenerate types** with `bettercms-codegen` in every consuming site after any model or field
+   change, commit the output if the repo commits it, and run that repo's build and typecheck with
+   the script it already has. Templates typed against an old schema compile and read `undefined`.
+9. **Verify** the editor's grouping and controls, one draft edit per changed field class, the
+   preview binding, the static or headless reading path, and the public output once a release is
+   authorized.
+
+Content models, frontend types, component definitions and live content have separate lifecycles;
+there is no single "deploy schema" action. Production publication stays behind the user's
+authorization and the component readiness and Visual Approval gates.
+
+**Evidence to return:** model and field ids, the version you wrote against, migrated record
+count, codegen and build result, one editor check and one rendered-page check, warnings, and any
+change the platform could not make (an open dependency, never a success).
+
+## Acceptance
+
+- Every imported route and collection has one clear home; one dynamic template per collection.
+- Sidebar moves keep every public route and record id; URL changes carry explicit redirects
+  (`create_redirect`).
+- Repeated data is modelled once, with references or reusable components.
+- Editors find and understand the fields without reading source code.
+- Model changes compile in each consuming site and keep the published output unchanged.

package/dist/skills/bettercms/references/editor-chrome.md

@@ -0,0 +1,88 @@
+---
+title: "Editor chrome (dock layout)"
+description: "Group, row, tab, icon, segmented control, list item names and showIf order for the dashboard dock; the ifMatch rule and the two chrome refusals."
+---
+
+# Editor chrome
+
+**Outcome.** Every dock screen an editor opens fits the click budget, every list names its items,
+and a condition is answered before the field it reveals. The delivered content is byte-identical.
+
+Doctrine: §14 of `bettercms://playbook/schema`; flow: `field-ui` prompt. Editor chrome (field
+`ui`, model `fieldsets`, prop `ui`) changes how the dashboard dock draws a field. It never moves a
+delivered value. Each recipe is one write, then a read-back.
+
+## 1. Read, then write with `ifMatch`
+
+Take `optimisticVersion` from `get_content_model` or `get_component`. For a page's own fields call
+`get_page`, send `pageId`, and use `backingModel.optimisticVersion`. The path args (`fieldUi`,
+`fieldFieldset`, `fieldOrder`, `propUi`, `propGroup`) and the layout keys (`kind`, `tab`, `icon`,
+`itemLabel`, `ui.group`) get 428 `precondition-required` without it. A 409 carrying
+`currentVersion` means someone wrote since your read: read again and re-apply the intent, never
+the old body. Why: path args are merged onto the stored row, and the version is what stops them landing on a
+schema you never saw.
+
+## 2. Group, row, tab
+
+Give a fieldset a `kind`:
+
+| `kind` | Draws | Limits |
+|---|---|---|
+| `group` | Fields folded under one header (`collapsed: true` starts it shut) | 12 rows inside one group |
+| `row` | Short fields on one line | at most 3 fields |
+| `tab` | A tab strip | at most 3 tabs, names of 20 characters or fewer, top-level fields only, tabs never nest |
+
+A group joins a tab with `tab: "<tab id>"`. A fieldset with no `kind` stays flat. Props have no
+fieldsets: the first prop of a group sends `ui.group: { id, label, kind }` and each later one
+`{ id }`; `kind` is `group` or `row`.
+
+Stay inside the budget `get_next_steps` measures per screen: 8 ungrouped rows, 12 rows in a group,
+3 levels, any value within 2 activations. Why: past it the rule `dock-budget` keeps listing the
+screen. A closed group in a second tab already costs 2 activations, so leave groups in later tabs
+open.
+
+## 3. Icons
+
+`ui.icon` belongs on nesting fields, fieldsets and a prop's `ui.group`, never on a leaf. Take names
+from the dock icon list the MCP serves as a resource (`resources/list`); any other string is a
+400. Set a sidebar item's icon with `set_icon`.
+
+## 4. Segmented, dropdown or slider
+
+- `ui.control: "segmented"` on a single-choice select with 2–4 short options: one click replaces
+  two. A multi-select or 5+ options is refused; keep the default dropdown there.
+- `"slider"` needs a `number` with numeric `config.min` below `config.max` and at most 1000 steps.
+
+## 5. Name list items
+
+On each repeater or repeatable zone set `ui.itemLabel` (1–24 characters: "Slide", "Person") and
+`ui.preview.title` naming a child key. Without either, every row reads "Item N" and
+`get_next_steps` keeps listing `dock-repeater-unnamed`.
+
+## 6. Conditional fields
+
+A field's `showIf` reads another field's value. Place the field it reads ABOVE it, so the author
+answers the condition first; a `showIf` that reads a later field is listed as `dock-showif-order`.
+Reorder with `fieldOrder` on `update_content_model`.
+
+## 7. Refusals
+
+| Code | Meaning | Do |
+|---|---|---|
+| 428 `precondition-required` | Layout keys without `ifMatch` | Read, send the version |
+| 409 **ui_human_owned** | A person arranged those paths (the body names them) | Leave them out; `override: true` only when the user asked you to replace their layout |
+| 409 **ui_studio_blind** | The Studio agent does not change editor chrome | Echo the chrome exactly as read, or omit it (the stored chrome is kept) |
+| 400 with a code | A vocabulary rule (**tab_max**, **row_member_count**, **control_segmented**…) | Fix what the message names; §14 lists every code |
+
+To undo an agent change, write back the values from your read before the change, with `ifMatch`.
+
+## 8. Chrome once, in the Layout
+
+Navigation, footer and dialogs live in the Global Layout (`get_layout`, `update_layout`). When
+`get_next_steps` reports `chrome-duplicated`, declare the element in the Layout and push; the page
+copies are stripped for you. Never delete them by hand, and never give them dock chrome.
+
+## Acceptance
+
+Read back with `get_content_model`, `get_page` or `get_component`. Done means `get_next_steps`
+lists none of `dock-budget`, `dock-repeater-unnamed`, `dock-showif-order`.

package/dist/skills/bettercms/references/external-content.md

@@ -0,0 +1,78 @@
+---
+title: "Content in another service"
+description: "Move content a site loads from another CMS or API (Contentful, Sanity, Strapi, Cosmic…) into BetterCMS by rewriting the client module, with the env names the platform supplies."
+---
+
+# Content that lives in another service
+
+Read when: the site loads its content from another CMS or content API. Signals:
+
+- A dependency in `package.json`: `cosmicjs` / `@cosmicjs/sdk`, `contentful`, `@sanity/client` /
+  `next-sanity`, `@strapi/*`, `@prismicio/*`, `storyblok-js-client` / `@storyblok/*`,
+  `@datocms/*`, `@wordpress/*`, `graphql-request` or `@apollo/client` pointed at a CMS endpoint.
+- `.env.example` names that service's keys (`*_BUCKET_SLUG`, `*_READ_KEY`, `*_SPACE_ID`,
+  `*_ACCESS_TOKEN`, `*_PROJECT_ID` for another CMS). BetterCMS reports the missing ones on import
+  as `envWarning`.
+- Pages fetch in `getServerSideProps`, `getStaticProps`, server components, `load()` or
+  `useFetch()` from a module that wraps that client.
+
+Two ways out, in this order, and the user types no key in either. When the values already exist
+on this machine, the platform takes them from the user's own files (the first section). When they
+do not, the rule Sanity follows on a migration applies: **the content moves into BetterCMS and the
+site reads it from BetterCMS** (the steps). Never ask the user for a key, and never leave the site
+depending on one it does not have: on BetterCMS it would build and serve, then render empty or
+crash in the browser.
+
+## First: are the values on this machine?
+
+`list_env_vars` names what the repository's `.env.example` declares and the project does not set
+(`missing`). When the user already runs this site, the values are usually in the repository's own
+`.env.local` or `.env`. Then run, in the repository:
+
+    npx @bettercms-ai/cli@latest env push
+
+It uploads the declared variables from those files straight to BetterCMS and prints their names
+only. Never open those files, print a value or ask the user to paste one: a secret in this
+conversation is a secret in a log. Rebuild, and the site runs as it did before.
+
+When `env push` reports the variables as not found, nobody here has the old service's keys. That
+is the case the steps below handle: the content moves into BetterCMS.
+
+## The steps
+
+Check: with every one of the other service's variables unset, `npm run build` succeeds and every
+page renders its content.
+
+1. **Find every read.** List the client module and each function the pages call, with the shape
+   each returns (the fields the components use, not the whole API response).
+2. **Model it** ([content-modeling.md](content-modeling.md)). One model per content type the pages
+   render: a list is a collection, a one-off (navigation, footer, landing hero) is a singleton.
+   Field names follow the code's own names, so the components don't change.
+3. **Seed the content.** If the user can export from the old service themselves, import that.
+   Otherwise create the entries from what the site shows: the repo's fixtures, sample data and
+   README, and the rendered pages in `get_site_composition`. Real-looking copy and working image
+   URLs, never lorem ipsum. The user edits it in BetterCMS afterwards.
+4. **Rewrite the client module, not the pages.** Keep every function's name and return shape, and
+   replace its body with a read from BetterCMS's Delivery API ([frameworks.md](frameworks.md)
+   shows the client per framework). Reading published content needs no key. The platform already
+   sets these on every build and every running server app, under the prefix the framework
+   exposes:
+
+   | Framework | Variables |
+   |---|---|
+   | Next.js | `NEXT_PUBLIC_BCMS_API_URL`, `NEXT_PUBLIC_BCMS_WORKSPACE`, `NEXT_PUBLIC_BCMS_PROJECT_ID` |
+   | Vite (React, Vue, Svelte) | `VITE_BCMS_*` |
+   | Nuxt | `NUXT_PUBLIC_BCMS_*` |
+   | Astro, SvelteKit | `PUBLIC_BCMS_*` |
+   | Create React App | `REACT_APP_BCMS_*` |
+   | Gatsby | `GATSBY_BCMS_*` |
+   | Server code, any framework | `BCMS_API_URL`, `BCMS_WORKSPACE`, `BCMS_PROJECT_ID` |
+
+   Do not add them to `.env` files. They are supplied, like Sanity's project id.
+5. **Keep actions that need the other service's secret working without it.** Payments, uploads and
+   writes to the old service stay in the code, guarded: when the key is unset, the button explains
+   that the feature is not configured. The page never throws.
+6. **Remove what is no longer read.** Drop the old SDK from `package.json` and its keys from
+   `.env.example` once nothing imports them.
+7. **Prove it.** Build with the old variables unset and open every page. Then continue with the
+   `convert_site` prompt: its bindings now point at BetterCMS content, and the Visual Editor edits it.