@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/SKILL.md

@@ -1,206 +1,206 @@
----
-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`.
-- Section patterns (149 worked kit entries by category and edge tag): resource `bettercms://kit`.
-- 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. **"Invalid tool parameters" is the client, not BetterCMS.** A client with tool search (Claude
-   Code) lists most of the 150 tools by name and loads a schema on demand; a call to a tool whose
-   schema it has not loaded is refused before it is sent. Load the tool with the client's tool
-   search, every tool the step needs in one search, then make the same call again. Never change
-   the arguments because of it. The tools a setup starts with are always loaded.
-6. **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` defaults to components (recorded by a deploy, a promote or setup)
-   and is never asked; the owner can switch it to fields.
-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, and never a nav, footer or
-   modal: chrome is the Layout. A call to action is one `button` field, never a text field
-   beside a link field. [components.md, content-modeling.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. An answer that leads with `held`, and a
-   publish reading `outcome.status: "partial"`, did not reach the site: do the action it names
-   before you report it.
-   [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`, `deploy_to_host` or
-   `create_deploy_upload` there, never add `bcms-rebuild.yml`; deploy with
-   `npx @bettercms-ai/cli@latest deploy --to <host>`, or push to the repo the host builds.
-   Done = `receipt.frontEnd` closed. [getting-started.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.
-13. **A build makes a site live, not editable.** It brings in SEO and meta, media, the brand and
-    the models `bcms-content.json` declares. Pages, collections, forms, bindings and components
-    are `editor_setup`'s: run it after an import or a rebuild (`get_deploy_status` `editorSetup`
-    `never` or `stale`). It also fills missing meta, merges identical components and adopts
-    declared bindings when proven; do only what get_next_steps still lists. [getting-started.md]
-
-## 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, headless, own front end, SDK, CLI |
-| 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 |
-| Read a source site before modelling it | [detection.md](references/detection.md) | converting from a URL or built HTML; deciding what a band, a repeat or a value is | detect, classify, section, repeat, global, carousel clone, hidden state |
-| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field, listing, filter, locked field |
-| Dock layout: groups, rows, tabs, icons, item names, showIf order | [editor-chrome.md](references/editor-chrome.md) | after any import, convert, componentize or extract (the gate's `dock` row); a `dock-*` rule; the `field-ui` prompt | dock, fieldset, tab, group, itemLabel, showIf, field-ui |
-| A custom input for one field in the dock: when, the user's approval, the contract | [dock-input.md](references/dock-input.md) | `get_next_steps` lists `dock-input-candidate`; a 409 `input_needs_confirmation` | custom input, ui.input, dock input, confirmed, swatch |
-| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write; a bulk load or re-run | validation, maxLength, unique, 400, refused write, dry run, externalKey, upsert, re-run |
-| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | the IA of a known site type, with its collections, forms and structured data | new site, IA, portfolio, agency, corporate, SaaS, ecommerce, directory, blog, docs, restaurant, events, course, jobs, real estate, nonprofit, multi-brand |
-| Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
-| Which kit pattern fits a section, and its shape and pitfalls, by category and edge tag | [kit-scenarios.md](references/kit-scenarios.md) | before designing any section's fields or props; a band detection.md classified | kit, pattern, scenario, edge tag, events, locations, calculator, map, chart, docs, team, bento, slots, personalization, localized |
-| One section, source HTML to bound template: hero, feature grid, pricing table, testimonials, FAQ, bento | [worked-examples.md](references/worked-examples.md) | you want the whole path for one section in production shapes | example, hero, pricing, FAQ, testimonial, source to schema |
-| The same for an article entry, navigation in the Global Layout, tabs holding columns | [worked-examples-advanced.md](references/worked-examples-advanced.md) | a collection entry with a body, site chrome, or nested blocks | example, blog post, document body, mega menu, tabs, columns |
-| The modelled section closest to the one you are building: schema, HTML signals, mcp steps, pitfalls | [kit-catalog.md](references/kit-catalog.md) | before designing a section or its props; matching source HTML to a known pattern | kit, catalogue, edge tag, section pattern, bento, localized, personalization, a11y, responsive |
-| 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, BcmsSections, --sections |
-| 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 |
-| Animated sites: GSAP, ScrollTrigger, split text, Motion, Lenis, Locomotive, three.js and WebGL, marquees, carousels, Lottie, hydrated islands, and what must stand down in the editor's canvas (`inEditor()`) | [animation.md](references/animation.md) | `package.json` lists `gsap`, `lenis`, `locomotive-scroll`, `framer-motion` or `motion`, `three`, `swiper` or a text splitter; a publish refused with `SPLIT_PATTERN_UNKNOWN` or `ISLAND_PROPS_UNMATCHED`; a `client-only-island` gate exception | animation, GSAP, ScrollTrigger, SplitText, Lenis, Framer Motion, marquee, Swiper, Lottie, island, client:only, data-bcms-split |
-| 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 |
-| Connect a vendor with a public API (jobs board, store, CRM, video): declare, approve, call, recipes | [integrations.md](references/integrations.md) | the user names Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo or any API; a 409 `integration_not_approved` | integration, API key, Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo, sync, vendor, token |
-| 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, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |
-| Accessibility: alt text, form labels, contrast, the audit codes and the manual checks | [accessibility.md](references/accessibility.md) | writing alt text; building a form; before reporting a site done | accessibility, WCAG, alt text, decorative, label, contrast, captions |
-| Page families from data | [programmatic-seo.md](references/programmatic-seo.md) | a keyword list or CSV should become pages | programmatic SEO, CSV, dataset, landing pages, glossary |
-| Publish, deploy, roll back, reconcile a re-import; add a section to a page or set its spacing | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits; "add a section here", "more padding on this section"; a write that answers `held` or a publish that reads `partial` | publish, deploy, rollback, sync, webhook, schedule, automation, add section, insertSection, sectionStyle, spacing, padding, margin, held, partial |
-| 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: `unaddressable` under 2%, and, where the
-   source declares its bindings, `coverage.pending` empty and `mode: "declared"`. `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`: `receipt.complete` is `true`. While it is `false`, run
-   `receipt.gate.nextAction` and read again after each batch; nothing else ends an imported
-   site's setup, and an exception is recorded only for a reason that is true. The gate, its bars and the exceptions it accepts are in
-   [finish-site.md](references/finish-site.md). Suggestions still in `missing` after that, and
-   owner actions, go in your final message by name.
-
-"Done" means the loop is clean and the gate reads complete, not that a tool call returned 200.
-`bettercms init` reads the gate again when you exit and prints its numbers per page, so the
-user sees them whatever your last message said.
+---
+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`.
+- Section patterns (149 worked kit entries by category and edge tag): resource `bettercms://kit`.
+- 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. **"Invalid tool parameters" is the client, not BetterCMS.** A client with tool search (Claude
+   Code) lists most of the 150 tools by name and loads a schema on demand; a call to a tool whose
+   schema it has not loaded is refused before it is sent. Load the tool with the client's tool
+   search, every tool the step needs in one search, then make the same call again. Never change
+   the arguments because of it. The tools a setup starts with are always loaded.
+6. **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` defaults to components (recorded by a deploy, a promote or setup)
+   and is never asked; the owner can switch it to fields.
+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, and never a nav, footer or
+   modal: chrome is the Layout. A call to action is one `button` field, never a text field
+   beside a link field. [components.md, content-modeling.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. An answer that leads with `held`, and a
+   publish reading `outcome.status: "partial"`, did not reach the site: do the action it names
+   before you report it.
+   [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`, `deploy_to_host` or
+   `create_deploy_upload` there, never add `bcms-rebuild.yml`; deploy with
+   `npx @bettercms-ai/cli@latest deploy --to <host>`, or push to the repo the host builds.
+   Done = `receipt.frontEnd` closed. [getting-started.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.
+13. **A build makes a site live, not editable.** It brings in SEO and meta, media, the brand and
+    the models `bcms-content.json` declares. Pages, collections, forms, bindings and components
+    are `editor_setup`'s: run it after an import or a rebuild (`get_deploy_status` `editorSetup`
+    `never` or `stale`). It also fills missing meta, merges identical components and adopts
+    declared bindings when proven; do only what get_next_steps still lists. [getting-started.md]
+
+## 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, headless, own front end, SDK, CLI |
+| 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 |
+| Read a source site before modelling it | [detection.md](references/detection.md) | converting from a URL or built HTML; deciding what a band, a repeat or a value is | detect, classify, section, repeat, global, carousel clone, hidden state |
+| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field, listing, filter, locked field |
+| Dock layout: groups, rows, tabs, icons, item names, showIf order | [editor-chrome.md](references/editor-chrome.md) | after any import, convert, componentize or extract (the gate's `dock` row); a `dock-*` rule; the `field-ui` prompt | dock, fieldset, tab, group, itemLabel, showIf, field-ui |
+| A custom input for one field in the dock: when, the user's approval, the contract | [dock-input.md](references/dock-input.md) | `get_next_steps` lists `dock-input-candidate`; a 409 `input_needs_confirmation` | custom input, ui.input, dock input, confirmed, swatch |
+| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write; a bulk load or re-run | validation, maxLength, unique, 400, refused write, dry run, externalKey, upsert, re-run |
+| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | the IA of a known site type, with its collections, forms and structured data | new site, IA, portfolio, agency, corporate, SaaS, ecommerce, directory, blog, docs, restaurant, events, course, jobs, real estate, nonprofit, multi-brand |
+| Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
+| Which kit pattern fits a section, and its shape and pitfalls, by category and edge tag | [kit-scenarios.md](references/kit-scenarios.md) | before designing any section's fields or props; a band detection.md classified | kit, pattern, scenario, edge tag, events, locations, calculator, map, chart, docs, team, bento, slots, personalization, localized |
+| One section, source HTML to bound template: hero, feature grid, pricing table, testimonials, FAQ, bento | [worked-examples.md](references/worked-examples.md) | you want the whole path for one section in production shapes | example, hero, pricing, FAQ, testimonial, source to schema |
+| The same for an article entry, navigation in the Global Layout, tabs holding columns | [worked-examples-advanced.md](references/worked-examples-advanced.md) | a collection entry with a body, site chrome, or nested blocks | example, blog post, document body, mega menu, tabs, columns |
+| The modelled section closest to the one you are building: schema, HTML signals, mcp steps, pitfalls | [kit-catalog.md](references/kit-catalog.md) | before designing a section or its props; matching source HTML to a known pattern | kit, catalogue, edge tag, section pattern, bento, localized, personalization, a11y, responsive |
+| 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, BcmsSections, --sections |
+| 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 |
+| Animated sites: GSAP, ScrollTrigger, split text, Motion, Lenis, Locomotive, three.js and WebGL, marquees, carousels, Lottie, hydrated islands, and what must stand down in the editor's canvas (`inEditor()`) | [animation.md](references/animation.md) | `package.json` lists `gsap`, `lenis`, `locomotive-scroll`, `framer-motion` or `motion`, `three`, `swiper` or a text splitter; a publish refused with `SPLIT_PATTERN_UNKNOWN` or `ISLAND_PROPS_UNMATCHED`; a `client-only-island` gate exception | animation, GSAP, ScrollTrigger, SplitText, Lenis, Framer Motion, marquee, Swiper, Lottie, island, client:only, data-bcms-split |
+| 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 |
+| Connect a vendor with a public API (jobs board, store, CRM, video): declare, approve, call, recipes | [integrations.md](references/integrations.md) | the user names Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo or any API; a 409 `integration_not_approved` | integration, API key, Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo, sync, vendor, token |
+| 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, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |
+| Accessibility: alt text, form labels, contrast, the audit codes and the manual checks | [accessibility.md](references/accessibility.md) | writing alt text; building a form; before reporting a site done | accessibility, WCAG, alt text, decorative, label, contrast, captions |
+| Page families from data | [programmatic-seo.md](references/programmatic-seo.md) | a keyword list or CSV should become pages | programmatic SEO, CSV, dataset, landing pages, glossary |
+| Publish, deploy, roll back, reconcile a re-import; add a section to a page or set its spacing | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits; "add a section here", "more padding on this section"; a write that answers `held` or a publish that reads `partial` | publish, deploy, rollback, sync, webhook, schedule, automation, add section, insertSection, sectionStyle, spacing, padding, margin, held, partial |
+| 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: `unaddressable` under 2%, and, where the
+   source declares its bindings, `coverage.pending` empty and `mode: "declared"`. `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`: `receipt.complete` is `true`. While it is `false`, run
+   `receipt.gate.nextAction` and read again after each batch; nothing else ends an imported
+   site's setup, and an exception is recorded only for a reason that is true. The gate, its bars and the exceptions it accepts are in
+   [finish-site.md](references/finish-site.md). Suggestions still in `missing` after that, and
+   owner actions, go in your final message by name.
+
+"Done" means the loop is clean and the gate reads complete, not that a tool call returned 200.
+`bettercms init` reads the gate again when you exit and prints its numbers per page, so the
+user sees them whatever your last message said.