@bettercms-ai/mcp 0.83.0 → 0.83.1

package/README.md

@@ -1,86 +1,86 @@
-# @bettercms-ai/mcp
-
-BetterCMS [Model Context Protocol](https://modelcontextprotocol.io) server. Lets an
-AI assistant author your content schema and entries through the BetterCMS Management
-API, authenticated with a short-lived, per-project `content:manage` key minted via
-the OAuth 2.0 Device Authorization Grant (RFC 8628) — no pasted long-lived key.
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `create_model` | Create a content model (schema) with optional initial fields. |
-| `add_field` | Append a field to an existing model (read-modify-write; never removes fields). |
-| `create_entry` | Create a content entry; applies `data`/`status` via a follow-up update. |
-| `create_form` / `update_form` | Author a form (fields + settings) to embed with `<BcmsForm>`. |
-| `create_component` / `update_component` | Author a reusable component (blockJson tree + props) to render with `<BcmsBlocks>`. |
-| `list_forms` / `get_form` / `list_components` / `get_component` | Discover forms & components to wire into site code. |
-
-See [SKILL.md](./SKILL.md) for how an AI agent should author pages, forms, and components.
-
-All operations are **additive** — there are no destructive tools. Deleting models,
-fields, or entries is dashboard-only by design.
-
-## Usage
-
-Add to your MCP client config (e.g. Claude Desktop / Claude Code):
-
-```json
-{
-  "mcpServers": {
-    "bettercms": {
-      "command": "npx",
-      "args": ["-y", "@bettercms-ai/mcp"],
-      "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
-    }
-  }
-}
-```
-
-### Registry auth (current)
-
-This package is published to **GitHub Packages**, which requires authentication
-**even for public scoped packages**. For `npx @bettercms-ai/mcp` to resolve, the
-host machine needs an `~/.npmrc` with:
-
-```
-@bettercms-ai:registry=https://npm.pkg.github.com/
-//npm.pkg.github.com/:_authToken=<a GitHub PAT with read:packages>
-```
-
-> **TODO (future):** publish `@bettercms-ai/mcp` (and `types`/`sdk`) to the public
-> **npmjs.org** registry so `npx @bettercms-ai/mcp` works with zero `.npmrc` setup
-> for any host/user. Until then the GitHub Packages auth above is required.
-
-On the first tool call the server prints an authorization prompt to **stderr**
-(visible in your MCP client's logs):
-
-```
-┌─ BetterCMS authorization required ─────────────────────────
-│ Visit: https://bettercms.ai/activate
-│ Enter code: WDJB-MJHT
-│ Or open: https://bettercms.ai/activate?code=WDJB-MJHT
-└────────────────────────────────────────────────────────────
-```
-
-Approve it in the dashboard (pick a workspace/project) and the server caches the
-minted token. It auto-refreshes on expiry; if the refresh token is revoked it
-re-runs the device flow.
-
-## Environment
-
-| Var | Default | Purpose |
-|-----|---------|---------|
-| `BETTERCMS_API_URL` | `https://api.bettercms.ai` | API origin (device-auth + Management API). |
-| `BETTERCMS_MCP_CREDENTIALS` | `~/.bettercms/mcp-credentials.json` | Token cache path (0600). |
-| `BETTERCMS_MCP_CLIENT_NAME` | `BetterCMS MCP` | Label shown on the approval screen. |
-| `BETTERCMS_MCP_TOOLS` | _(unset)_ | Toolsets to register, a comma list: `core` (core tools only), `abm` (adds the ABM campaign lane), `all`. Unset registers every tool except the ABM lane. The hosted server takes the same list as `?tools=`. |
-
-## Develop
-
-```bash
-bun install
-bun run --filter @bettercms-ai/mcp typecheck
-bun run --filter @bettercms-ai/mcp test
-bun run --filter @bettercms-ai/mcp build
-```
+# @bettercms-ai/mcp
+
+BetterCMS [Model Context Protocol](https://modelcontextprotocol.io) server. Lets an
+AI assistant author your content schema and entries through the BetterCMS Management
+API, authenticated with a short-lived, per-project `content:manage` key minted via
+the OAuth 2.0 Device Authorization Grant (RFC 8628) — no pasted long-lived key.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_model` | Create a content model (schema) with optional initial fields. |
+| `add_field` | Append a field to an existing model (read-modify-write; never removes fields). |
+| `create_entry` | Create a content entry; applies `data`/`status` via a follow-up update. |
+| `create_form` / `update_form` | Author a form (fields + settings) to embed with `<BcmsForm>`. |
+| `create_component` / `update_component` | Author a reusable component (blockJson tree + props) to render with `<BcmsBlocks>`. |
+| `list_forms` / `get_form` / `list_components` / `get_component` | Discover forms & components to wire into site code. |
+
+See [SKILL.md](./SKILL.md) for how an AI agent should author pages, forms, and components.
+
+All operations are **additive** — there are no destructive tools. Deleting models,
+fields, or entries is dashboard-only by design.
+
+## Usage
+
+Add to your MCP client config (e.g. Claude Desktop / Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "bettercms": {
+      "command": "npx",
+      "args": ["-y", "@bettercms-ai/mcp"],
+      "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
+    }
+  }
+}
+```
+
+### Registry auth (current)
+
+This package is published to **GitHub Packages**, which requires authentication
+**even for public scoped packages**. For `npx @bettercms-ai/mcp` to resolve, the
+host machine needs an `~/.npmrc` with:
+
+```
+@bettercms-ai:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=<a GitHub PAT with read:packages>
+```
+
+> **TODO (future):** publish `@bettercms-ai/mcp` (and `types`/`sdk`) to the public
+> **npmjs.org** registry so `npx @bettercms-ai/mcp` works with zero `.npmrc` setup
+> for any host/user. Until then the GitHub Packages auth above is required.
+
+On the first tool call the server prints an authorization prompt to **stderr**
+(visible in your MCP client's logs):
+
+```
+┌─ BetterCMS authorization required ─────────────────────────
+│ Visit: https://bettercms.ai/activate
+│ Enter code: WDJB-MJHT
+│ Or open: https://bettercms.ai/activate?code=WDJB-MJHT
+└────────────────────────────────────────────────────────────
+```
+
+Approve it in the dashboard (pick a workspace/project) and the server caches the
+minted token. It auto-refreshes on expiry; if the refresh token is revoked it
+re-runs the device flow.
+
+## Environment
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `BETTERCMS_API_URL` | `https://api.bettercms.ai` | API origin (device-auth + Management API). |
+| `BETTERCMS_MCP_CREDENTIALS` | `~/.bettercms/mcp-credentials.json` | Token cache path (0600). |
+| `BETTERCMS_MCP_CLIENT_NAME` | `BetterCMS MCP` | Label shown on the approval screen. |
+| `BETTERCMS_MCP_TOOLS` | _(unset)_ | Toolsets to register, a comma list: `core` (core tools only), `abm` (adds the ABM campaign lane), `all`. Unset registers every tool except the ABM lane. The hosted server takes the same list as `?tools=`. |
+
+## Develop
+
+```bash
+bun install
+bun run --filter @bettercms-ai/mcp typecheck
+bun run --filter @bettercms-ai/mcp test
+bun run --filter @bettercms-ai/mcp build
+```

package/SKILL.md

@@ -1,160 +1,160 @@
-# BetterCMS MCP — authoring skill
-
-How an AI agent should author content, schema, **forms**, and **components** in
-BetterCMS through this MCP. The MCP is bound to ONE project (the API key's project);
-everything you create lands there.
-
-The guided prompts ship with the server — prefer them: `studio` (router),
-`propose_schema`, `new_page`, `new_form`, `new_component`. This file is the reference
-behind them.
-
-## Golden rules
-- **Confirm before creating.** Propose the shape (fields / block tree) and get the
-  user's approval (AskUserQuestion) before any create/update. Never silently guess.
-- **Read before you edit.** Use the `list_*` / `get_*` tools first so you keep existing
-  keys/blocks and don't duplicate.
-- **Additive where possible.** `add_field` appends (to a model or a page); passing `fields`
-  to `update_form` or `blockJson` to `update_component` REPLACES — include everything
-  you want to keep.
-- **Drafts are invisible.** A component you create is a DRAFT, and a draft component
-  renders as an empty string on the live site — no error, no placeholder. Call
-  `publish_component` on every component you place, then publish the page.
-
-## Pages & schema
-Decide the architecture before the first call. A marketing site is **components-first**:
-a library of `create_component` sections, each with a `sectionType` and a library
-category, placed on pages via `create_page`'s `blockJson` as `component` blocks. A blog or
-catalogue is **schema-first**: a `create_content_model` collection whose body field is
-`document` (the article canvas — pages or collections, one per schema, top level; cannot coexist with a Section zone).
-
-Within a page's own schema, destructure into a tree: plain fields, **group** (one nested
-object), **repeater** (a repeatable array). Never a 1-item repeater, never a repeater of a
-single text (that is `array`).
-
-### A page is a list of SECTIONS. Never a list of loose blocks.
-
-The top level of a page's `blockJson` holds only `component` blocks or `section` blocks —
-never a bare `heading`/`text`/`image`/`button`/`spacer`.
-
-**Why it matters, concretely:** the visual editor derives one section per TOP-LEVEL block. A
-hero authored as four loose blocks (headline, lede, two CTAs) becomes four separate sections,
-each with its own move / duplicate / delete controls and its own "Add section here" gap — and
-because each top-level block gets its own block box, the two call-to-action buttons stop being
-inline siblings and **stack onto separate lines**. That is not a styling bug to chase in CSS;
-it is the page telling you it was authored flat.
-
-```jsonc
-// ✅ one section, four children — one set of controls, CTAs side by side
-{ "type": "section", "id": "hero",
-  "style": { "bg": "surface", "paddingTop": 96, "paddingBottom": 96, "contentWidth": "default" },
-  "props": { "children": [
-    { "type": "heading", "id": "hero-title", "props": { "text": "Strategic Planning.", "level": 1 } },
-    { "type": "text",    "id": "hero-lede",  "props": { "html": "<p>One place to plan, track and ship.</p>" } },
-    { "type": "button",  "id": "hero-cta",   "props": { "text": "Start a project", "href": "/contact" } },
-    { "type": "button",  "id": "hero-cta2",  "props": { "text": "See our work", "href": "/work", "variant": "secondary" } }
-  ] } }
-```
-
-**Two CTAs are two sibling `button` blocks.** Not a `columns` block — `columns` renders
-`grid-template-columns: repeat(N, 1fr)`, so each CTA would stretch to half the container.
-Buttons are inline-level and flow side by side on their own. This is what the shipped
-`builtin:hero-centered` section does.
-
-### `section` block or `component`? Decide by REUSE.
-
-| | use it when | the catch |
-|---|---|---|
-| **`component`** (+ `sectionType`) | the band appears on more than one page, or needs layout variants — a Hero that is "Centered" on Home and "Two-column" on About | its children render **without field bindings**, so their text is **not click-to-edit on the canvas**. It is edited through the component's declared `props` in the section dock, where an unset prop shows empty and inherits the definition's default. Authors who want the current copy visible in the dock should set the prop explicitly rather than relying on the inherited default. |
-| **`section` block** | a genuinely one-off band on a single page | no family name and no variant switcher, and the editor's "Add a section" picker cannot insert one — only components |
-
-`component` is the shape the product's reuse machinery is built around: variants, the section
-picker and the family name all key off `componentId`. So reach for it whenever a band actually
-recurs — and when you do, **declare a prop for every string, link and image a marketer will
-ever touch**. A component with un-propped editable copy is the defect, not the component.
-
-### Don't hand-write a hero. Start from a built-in section.
-
-There are built-in section components — `hero-centered`, `hero-split`, `feature-grid-three`,
-`feature-grid-two`, `faq-list`, `stats-row`, `logo-cloud-row`, `testimonial-quote`,
-`case-study-story`, `cta-banner`, `cta-split`, `pricing-three`, `contact-simple` — available to
-every project (`list_components` returns them; they have no `projectId`). Every one is already
-rooted in a `section` block with its editable leaves declared as props, and `Hero` ships two
-variants, so the shapes above are worked examples you can read.
-
-Two sanctioned recipes, and which one you want follows the reuse rule above:
-
-1. **Inline it** — copy the builtin's `section` blockJson onto the page as a `section` block and
-   substitute your values. Standard path for a one-off band; children stay click-to-edit.
-2. **Reference it** — place `{ type: "component", props: { componentId, overrides } }`. Use this
-   when the band recurs across pages or needs the variant switcher.
-
-Authoring a hero's JSON from scratch is the slow way to reinvent recipe 1 with more mistakes.
-
-The full decision tree, section anatomy, variant rules and build order live in the
-`propose_schema` prompt and in the `bettercms://playbook/schema` resource.
-
-## Forms
-Tools: `list_forms`, `get_form`, `create_form`, `update_form`.
-
-1. Collect the fields with the user. Field: `{ key, label, type, required?, placeholder?,
-   options?, defaultValue?, showIf? }`. Types: `text, email, textarea, select` (needs
-   `options`), `checkbox, number, phone, date, url, consent, hidden`. `showIf:
-   { field, equals }` shows a field conditionally.
-2. Settings: `name` (the handle for `getForm('Name')`), `submitLabel?`, `successMessage?`,
-   `redirectUrl?`.
-3. Confirm → `create_form { name, fields, ... }` (returns the id) or
-   `update_form { formId, ... }`.
-4. **Wire it into the site**: in a `@bettercms-ai/next` site,
-   `import { getForm } from "@bettercms-ai/next"` then render
-   `<BcmsForm form={await getForm("Name")} />` where the user wants it.
-
-## Components (reusable Webflow-style symbols)
-Tools: `list_components`, `get_component`, `create_component`, `update_component`.
-
-1. Design the `blockJson` tree — an array of blocks `{ type, id, props }`. The full set:
-   `heading {text, level}`, `text {html}`, `richtext {html}`, `image {src, alt}`,
-   `button {text, href, variant?, size?, fullWidth?}`, `spacer {height}`, `video {url}`,
-   `columns {columns: block[][], gap}`, `section {children: block[]}`,
-   `slider {slides}`, `tabs {tabs}`, `navbar {links, logo?, cta?}`, `footer {columns, copyright?}`,
-   `form {formId}`, `component {componentId, overrides?}`, `collection {…}`.
-   `section`, `columns`, `slider` and `tabs` nest child blocks. Every block needs a stable
-   unique `id`.
-
-   ⚠️ `text` and `richtext` carry **`html`**, never `text`. `props.html` is required with no
-   default, so `{ text: "…" }` is a **400 on every save** — not a silent strip. This file said
-   `text {text}` until 2026-08-20; if you learned it from an older copy, unlearn it.
-2. Optional `props` — overridable fields `{ key, label, target: { blockId, path }, type,
-   defaultValue? }` (type: `text|richtext|image|url|boolean`) so each instance can be
-   customized.
-3. Confirm the structure → `create_component { name, slug, category?, blockJson, props? }`
-   (returns the id) or `update_component { componentId, ... }`. **Updating a component
-   re-bakes every page that embeds it.**
-4. **Render it**: `<BcmsBlocks blocks={component.blockJson} components={...} />` from
-   `@bettercms-ai/next`.
-
-Authoring `blockJson` blind is error-prone — keep trees small, confirm with the user,
-and read back with `get_component` to verify.
-
-## AI content & SEO
-Tools: `write_content`, `generate_seo_meta`. Guided prompts: `build_site`,
-`generate_landing_pages`, `seo_optimize`. These use the workspace's own Anthropic key
-(BYOK, unmetered) or platform AI credits, and return a *suggestion* — you apply it.
-
-1. **Write copy** → `write_content { action, text, instructions?, targetLang?, context? }`.
-   `action`: `write` (draft from a brief), `rewrite` (improve existing copy), `translate`
-   (needs `targetLang`). Returns the text — apply it with `set_page_content`, `create_entry`,
-   or `update_entry`.
-2. **SEO meta** → `generate_seo_meta { text, context? }` returns
-   `{ metaTitle, metaDescription, keywords, jsonLd? }`. Read the page/entry, pass its content
-   as `text`, then apply the suggestion via the page/entry update tools.
-3. **Programmatic pages** → for a template + a dataset, loop rows: `write_content` per slot →
-   `create_entry` → `generate_seo_meta`. Confirm the first row or two first. For hundreds of
-   rows, the dashboard AI Page Builder bulk-imports a CSV.
-
-Always show suggestions to the user before applying; never invent brand facts.
-
-## Errors
-- `401/403` → the MCP key needs (re)authorizing (re-run "Connect your AI").
-- `409 slug_taken` → offer a different slug.
-- `create_form`/`create_component` missing → the host has a stale cached MCP; tell the
-  user to `rm -rf ~/.npm/_npx` and restart, or that their connector predates this skill.
+# BetterCMS MCP — authoring skill
+
+How an AI agent should author content, schema, **forms**, and **components** in
+BetterCMS through this MCP. The MCP is bound to ONE project (the API key's project);
+everything you create lands there.
+
+The guided prompts ship with the server — prefer them: `studio` (router),
+`propose_schema`, `new_page`, `new_form`, `new_component`. This file is the reference
+behind them.
+
+## Golden rules
+- **Confirm before creating.** Propose the shape (fields / block tree) and get the
+  user's approval (AskUserQuestion) before any create/update. Never silently guess.
+- **Read before you edit.** Use the `list_*` / `get_*` tools first so you keep existing
+  keys/blocks and don't duplicate.
+- **Additive where possible.** `add_field` appends (to a model or a page); passing `fields`
+  to `update_form` or `blockJson` to `update_component` REPLACES — include everything
+  you want to keep.
+- **Drafts are invisible.** A component you create is a DRAFT, and a draft component
+  renders as an empty string on the live site — no error, no placeholder. Call
+  `publish_component` on every component you place, then publish the page.
+
+## Pages & schema
+Decide the architecture before the first call. A marketing site is **components-first**:
+a library of `create_component` sections, each with a `sectionType` and a library
+category, placed on pages via `create_page`'s `blockJson` as `component` blocks. A blog or
+catalogue is **schema-first**: a `create_content_model` collection whose body field is
+`document` (the article canvas — pages or collections, one per schema, top level; cannot coexist with a Section zone).
+
+Within a page's own schema, destructure into a tree: plain fields, **group** (one nested
+object), **repeater** (a repeatable array). Never a 1-item repeater, never a repeater of a
+single text (that is `array`).
+
+### A page is a list of SECTIONS. Never a list of loose blocks.
+
+The top level of a page's `blockJson` holds only `component` blocks or `section` blocks —
+never a bare `heading`/`text`/`image`/`button`/`spacer`.
+
+**Why it matters, concretely:** the visual editor derives one section per TOP-LEVEL block. A
+hero authored as four loose blocks (headline, lede, two CTAs) becomes four separate sections,
+each with its own move / duplicate / delete controls and its own "Add section here" gap — and
+because each top-level block gets its own block box, the two call-to-action buttons stop being
+inline siblings and **stack onto separate lines**. That is not a styling bug to chase in CSS;
+it is the page telling you it was authored flat.
+
+```jsonc
+// ✅ one section, four children — one set of controls, CTAs side by side
+{ "type": "section", "id": "hero",
+  "style": { "bg": "surface", "paddingTop": 96, "paddingBottom": 96, "contentWidth": "default" },
+  "props": { "children": [
+    { "type": "heading", "id": "hero-title", "props": { "text": "Strategic Planning.", "level": 1 } },
+    { "type": "text",    "id": "hero-lede",  "props": { "html": "<p>One place to plan, track and ship.</p>" } },
+    { "type": "button",  "id": "hero-cta",   "props": { "text": "Start a project", "href": "/contact" } },
+    { "type": "button",  "id": "hero-cta2",  "props": { "text": "See our work", "href": "/work", "variant": "secondary" } }
+  ] } }
+```
+
+**Two CTAs are two sibling `button` blocks.** Not a `columns` block — `columns` renders
+`grid-template-columns: repeat(N, 1fr)`, so each CTA would stretch to half the container.
+Buttons are inline-level and flow side by side on their own. This is what the shipped
+`builtin:hero-centered` section does.
+
+### `section` block or `component`? Decide by REUSE.
+
+| | use it when | the catch |
+|---|---|---|
+| **`component`** (+ `sectionType`) | the band appears on more than one page, or needs layout variants — a Hero that is "Centered" on Home and "Two-column" on About | its children render **without field bindings**, so their text is **not click-to-edit on the canvas**. It is edited through the component's declared `props` in the section dock, where an unset prop shows empty and inherits the definition's default. Authors who want the current copy visible in the dock should set the prop explicitly rather than relying on the inherited default. |
+| **`section` block** | a genuinely one-off band on a single page | no family name and no variant switcher, and the editor's "Add a section" picker cannot insert one — only components |
+
+`component` is the shape the product's reuse machinery is built around: variants, the section
+picker and the family name all key off `componentId`. So reach for it whenever a band actually
+recurs — and when you do, **declare a prop for every string, link and image a marketer will
+ever touch**. A component with un-propped editable copy is the defect, not the component.
+
+### Don't hand-write a hero. Start from a built-in section.
+
+There are built-in section components — `hero-centered`, `hero-split`, `feature-grid-three`,
+`feature-grid-two`, `faq-list`, `stats-row`, `logo-cloud-row`, `testimonial-quote`,
+`case-study-story`, `cta-banner`, `cta-split`, `pricing-three`, `contact-simple` — available to
+every project (`list_components` returns them; they have no `projectId`). Every one is already
+rooted in a `section` block with its editable leaves declared as props, and `Hero` ships two
+variants, so the shapes above are worked examples you can read.
+
+Two sanctioned recipes, and which one you want follows the reuse rule above:
+
+1. **Inline it** — copy the builtin's `section` blockJson onto the page as a `section` block and
+   substitute your values. Standard path for a one-off band; children stay click-to-edit.
+2. **Reference it** — place `{ type: "component", props: { componentId, overrides } }`. Use this
+   when the band recurs across pages or needs the variant switcher.
+
+Authoring a hero's JSON from scratch is the slow way to reinvent recipe 1 with more mistakes.
+
+The full decision tree, section anatomy, variant rules and build order live in the
+`propose_schema` prompt and in the `bettercms://playbook/schema` resource.
+
+## Forms
+Tools: `list_forms`, `get_form`, `create_form`, `update_form`.
+
+1. Collect the fields with the user. Field: `{ key, label, type, required?, placeholder?,
+   options?, defaultValue?, showIf? }`. Types: `text, email, textarea, select` (needs
+   `options`), `checkbox, number, phone, date, url, consent, hidden`. `showIf:
+   { field, equals }` shows a field conditionally.
+2. Settings: `name` (the handle for `getForm('Name')`), `submitLabel?`, `successMessage?`,
+   `redirectUrl?`.
+3. Confirm → `create_form { name, fields, ... }` (returns the id) or
+   `update_form { formId, ... }`.
+4. **Wire it into the site**: in a `@bettercms-ai/next` site,
+   `import { getForm } from "@bettercms-ai/next"` then render
+   `<BcmsForm form={await getForm("Name")} />` where the user wants it.
+
+## Components (reusable Webflow-style symbols)
+Tools: `list_components`, `get_component`, `create_component`, `update_component`.
+
+1. Design the `blockJson` tree — an array of blocks `{ type, id, props }`. The full set:
+   `heading {text, level}`, `text {html}`, `richtext {html}`, `image {src, alt}`,
+   `button {text, href, variant?, size?, fullWidth?}`, `spacer {height}`, `video {url}`,
+   `columns {columns: block[][], gap}`, `section {children: block[]}`,
+   `slider {slides}`, `tabs {tabs}`, `navbar {links, logo?, cta?}`, `footer {columns, copyright?}`,
+   `form {formId}`, `component {componentId, overrides?}`, `collection {…}`.
+   `section`, `columns`, `slider` and `tabs` nest child blocks. Every block needs a stable
+   unique `id`.
+
+   ⚠️ `text` and `richtext` carry **`html`**, never `text`. `props.html` is required with no
+   default, so `{ text: "…" }` is a **400 on every save** — not a silent strip. This file said
+   `text {text}` until 2026-08-20; if you learned it from an older copy, unlearn it.
+2. Optional `props` — overridable fields `{ key, label, target: { blockId, path }, type,
+   defaultValue? }` (type: `text|richtext|image|url|boolean`) so each instance can be
+   customized.
+3. Confirm the structure → `create_component { name, slug, category?, blockJson, props? }`
+   (returns the id) or `update_component { componentId, ... }`. **Updating a component
+   re-bakes every page that embeds it.**
+4. **Render it**: `<BcmsBlocks blocks={component.blockJson} components={...} />` from
+   `@bettercms-ai/next`.
+
+Authoring `blockJson` blind is error-prone — keep trees small, confirm with the user,
+and read back with `get_component` to verify.
+
+## AI content & SEO
+Tools: `write_content`, `generate_seo_meta`. Guided prompts: `build_site`,
+`generate_landing_pages`, `seo_optimize`. These use the workspace's own Anthropic key
+(BYOK, unmetered) or platform AI credits, and return a *suggestion* — you apply it.
+
+1. **Write copy** → `write_content { action, text, instructions?, targetLang?, context? }`.
+   `action`: `write` (draft from a brief), `rewrite` (improve existing copy), `translate`
+   (needs `targetLang`). Returns the text — apply it with `set_page_content`, `create_entry`,
+   or `update_entry`.
+2. **SEO meta** → `generate_seo_meta { text, context? }` returns
+   `{ metaTitle, metaDescription, keywords, jsonLd? }`. Read the page/entry, pass its content
+   as `text`, then apply the suggestion via the page/entry update tools.
+3. **Programmatic pages** → for a template + a dataset, loop rows: `write_content` per slot →
+   `create_entry` → `generate_seo_meta`. Confirm the first row or two first. For hundreds of
+   rows, the dashboard AI Page Builder bulk-imports a CSV.
+
+Always show suggestions to the user before applying; never invent brand facts.
+
+## Errors
+- `401/403` → the MCP key needs (re)authorizing (re-run "Connect your AI").
+- `409 slug_taken` → offer a different slug.
+- `create_form`/`create_component` missing → the host has a stale cached MCP; tell the
+  user to `rm -rf ~/.npm/_npx` and restart, or that their connector predates this skill.

package/dist/index.js

@@ -2899,6 +2899,9 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "translate_entry",
   "update_field",
   "refresh_search_index",
+  // The owner's questions: a core client answers them through editor_setup `declare` (always loaded).
+  "get_editable_plan",
+  "confirm_editable_plan",
   // Automation, branches and AI images.
   "list_webhooks",
   "create_webhook",
@@ -3003,6 +3006,8 @@ var NEW_TOOL_TEXT = {
   refresh_search_index: "Tell search engines and site search about published changes; costs nothing. action 'indexnow' submits `urls` (this site's own, up to 1000) to IndexNow, or every change since the last submission when omitted. action 'reindex' rebuilds the project's site-search index. 503 means the index is unreachable: try again later.",
   import_redirects: "Bulk-create redirects for a migration, from `rows` or from `text` in `format` (our CSV export, a Netlify `_redirects` file, or a vercel.json). Call it with `dryRun: true` FIRST: nothing is written and each row comes back `would-create`, `existing` or `skipped` with a reason. Rows get create_redirect's rules. Max 5000.",
   editor_setup: "Make the live build editable: derives pages, collections, forms, bindings and components from the live release (skill bindings). Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
+  get_editable_plan: "Questions only the owner answers (logo, header, seeds, kit sections, brand, blocks): `rows` with closed `options` and `recommended`. Ask; never guess.",
+  confirm_editable_plan: "Record answers: each `decisions` item is an option's `decision`, unchanged. `check: true` = dry run.",
   transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText).",
   write_alt_text: "Alt text for a Media Library image (mediaId) or an https image URL (url), written from its pixels (1 AI credit). A suggestion: save it with update_media.",
   list_integrations: "List the project's custom integrations (any vendor with a public API) and the workspace's integration `templates`. Each has its hosts, secret NAMES with `secretsPresent` (never a value), syncs, hooks, endpoints, functions and `approved`. Read bettercms://skill/integrations first.",
@@ -3710,10 +3715,15 @@ var HOSTING_TEXT = {
   deploy_to_host: "Deploy this project to the user's own Vercel or Netlify account through their connection. BetterCMS builds the site and the host serves that build (skill publishing). The first call creates the site on the host and makes it the project's host; a later call for the same provider redeploys that site (`redeployed: true`). `connectionId` (from list_hosting_connections) defaults to the newest working one, `siteName` to the project's handle. A refusal carries a `code` and a `fixUrl` (not_connected, reconnect, pick_existing_site, grant_required, ADMIN_REQUIRED): each is fixed by the user at `fixUrl`, so relay it and stop. `deploymentQueued: false` means the project has no live build yet: deploy_project first, and that release reaches the host on its own. Never run the Vercel or Netlify CLI while a connection exists. A headless project is not deployed here: its own front end deploys with `npx @bettercms-ai/cli@latest deploy --to <host>`. Then poll get_host_deploy_status. Needs artifact:write, like deploy_project.",
   get_host_deploy_status: "The connected project's recent deployments to Vercel, Netlify or Cloudflare, newest first: state (queued|deploying|live|failed), providerUrl, error, sha and targetName. Poll it after deploy_to_host until the newest one is `live`, whose `providerUrl` is the live URL to hand the user, or `failed`, whose `error` you read back to them."
 };
-async function builtinCopyId(client, builtinId) {
+async function builtinCopyId(client, builtinId, verdict) {
   const listed = await client.fetchJSON(client.url(`/management/components?select=summary`));
   const copy = (listed.data ?? []).find((row) => row.sourceKey === builtinId && !row.builtin);
   if (copy) return copy.id;
+  try {
+    await verdict();
+  } catch (err) {
+    if (apiError(err)?.bodyCode !== "BUILTIN_NOT_COPIED") throw err;
+  }
   const made = await client.fetchJSON(client.url(`/management/components`), { method: "POST", body: JSON.stringify({ from: builtinId }) });
   return made.data.id;
 }
@@ -4962,13 +4972,16 @@ ${d.outline}` : "Proposed Content structure.", d);
         async (c, a) => {
           const edit = Array.isArray(a.blockJson) ? void 0 : a.blockJson;
           const insert = edit?.insertSection;
-          const insertSection = insert?.componentId.startsWith("builtin:") ? { ...insert, componentId: await builtinCopyId(c, insert.componentId) } : insert;
+          const pageBody = (sectionInsert) => ({ title: a.title, slug: a.slug, blockJson: Array.isArray(a.blockJson) ? a.blockJson : void 0, insertSection: sectionInsert, sectionStyle: edit?.sectionStyle, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status, noindex: a.noindex, canonical: a.canonical, og: a.og, twitter: a.twitter, scheduledAt: a.scheduledAt, unpublishAt: a.unpublishAt, locale: a.locale, translationOf: a.translationOf, ...a.dynamic });
+          const ifMatchHeaders = a.ifMatch !== void 0 ? { headers: { "If-Match": `W/"${a.ifMatch}"` } } : {};
+          const verdict = () => c.fetchJSON(c.url(`/management/pages/${s(a.pageId)}/meta`), { method: "PATCH", ...ifMatchHeaders, body: JSON.stringify({ ...pageBody(insert), dryRun: true }) });
+          const insertSection = insert?.componentId.startsWith("builtin:") ? { ...insert, componentId: await builtinCopyId(c, insert.componentId, verdict) } : insert;
           const res = await c.fetchJSON(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
             {
               method: "PATCH",
-              ...a.ifMatch !== void 0 ? { headers: { "If-Match": `W/"${a.ifMatch}"` } } : {},
-              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: Array.isArray(a.blockJson) ? a.blockJson : void 0, insertSection, sectionStyle: edit?.sectionStyle, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status, noindex: a.noindex, canonical: a.canonical, og: a.og, twitter: a.twitter, scheduledAt: a.scheduledAt, unpublishAt: a.unpublishAt, locale: a.locale, translationOf: a.translationOf, ...a.dynamic })
+              ...ifMatchHeaders,
+              body: JSON.stringify(pageBody(insertSection))
             }
           );
           const note = res.redirectNote;
@@ -5512,7 +5525,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Each release scans the built HTML for the element rendering each CMS field value; per slot this returns `mode` ('text-match' = guessed from rendered text, 'declared' = template-declared), what was bound, and `unmatched`: each path with its reason (reasons: skill bindings). DEPLOY FIRST: before any release there is no report (pages 0, mode null, refreshRequired true). `refreshReason`: a HEADLESS site never gets one (`never-generated`); `layoutRoutes` and `coverage.error`: skill bindings. `unaddressable` is the visible live text no field owns, by route (null = unmeasured: diff visible text against entry values); over `count / visible > 0.02`, fix it in the SOURCE and re-read (playbook \xA711). `entryRowUnbound`: a bound card's words no field of its entry claims, by route, with `reason` (reference, boolean, locale-format, counter, no-field); never also in `unaddressable`. `canvas.lane`: `none` \u2192 get_next_steps.",
+        "The receipt for 'is this site actually EDITABLE?'. Each release scans the built HTML for the element rendering each CMS field value; per slot this returns `mode` ('text-match' = guessed from rendered text, 'declared' = template-declared), what was bound, and `unmatched`: each path with its reason (reasons: skill bindings). DEPLOY FIRST: before any release there is no report (pages 0, mode null, refreshRequired true). `refreshReason`: a HEADLESS site never gets one (`never-generated`); `layoutRoutes` and `coverage.error`: skill bindings. `unaddressable` is the visible live text no field owns, by route (null = unmeasured: diff visible text against entry values); over `count / visible > 0.02`, fix it in the SOURCE and re-read (playbook \xA711). `entryRowUnbound`: a bound card's words no field of its entry claims, by route, with `reason` (reference, boolean, locale-format, counter, no-field); never also in `unaddressable`. `canvas.lane`: `none` \u2192 get_next_steps. `sectionsHeld` likewise; `unstampedIds`: no stamp.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read \u2014 everything here, `unaddressable` included, is measured PER SLOT, so on a promote-gated project pass 'current' to read the tree the editor frames. Defaults to the slot this project's releases land in. The response's `sha` is the build the report describes; `refreshRequired` is true when that is not the build this slot serves. Other per-slot fields: skill bindings.") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -5783,7 +5796,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release`, `held` and `publishes` (each `live` or `partial`): skill publishing. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (skill bindings) and `editorUrl`, the visual editor to hand the user.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release`, `held` and `publishes` (each `live` or `partial`): skill publishing. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (skill bindings) and `editorUrl`, the visual editor to hand the user. `heldSections`: sections held off the page.",
         z.object({ waitSeconds: z.number().optional().describe(PARAM_TEXT.waitSeconds) }).shape,
         // Flat body, no `data` envelope: `data()` read it as undefined.
         async (c, a) => ok("Deploy status.", await c.fetchJSON(c.url(withWait(`/management/projects/deploy-status`, a.waitSeconds)), { method: "GET" }))
@@ -5811,6 +5824,21 @@ ${d.outline}` : "Proposed Content structure.", d);
         // `declare` records binding decisions; with `check: true` it is a dry run (the body's `dryRun`).
         async (c, a) => a.exempt ? ok("Setup gate exceptions.", await c.fetchJSON(c.url(`/management/projects/setup-gate/exceptions`), { method: "POST", body: JSON.stringify({ exempt: a.exempt }) })) : a.declare ? ok("Binding decisions.", await c.fetchJSON(c.url(`/management/projects/binding-decisions`), { method: "POST", body: JSON.stringify({ declare: a.declare, ...a.check === true ? { dryRun: true } : {} }) })) : ok("Editor setup.", await c.fetchJSON(c.url(a.check === true ? withWait(`/management/projects/editor-setup`, a.waitSeconds) : `/management/projects/editor-setup`), a.check === true ? { method: "GET" } : { method: "POST", body: JSON.stringify({ force: a.force }) }))
       ),
+      // Ask, don't guess: the plan, and its answers through editor_setup's declare route.
+      def(
+        "get_editable_plan",
+        "Get the owner's open questions",
+        NEW_TOOL_TEXT.get_editable_plan,
+        z.object({}).shape,
+        async (c) => ok("Editable plan.", await c.fetchJSON(c.url(`/management/projects/editable-plan`), { method: "GET" }))
+      ),
+      def(
+        "confirm_editable_plan",
+        "Record the owner's answers",
+        NEW_TOOL_TEXT.confirm_editable_plan,
+        z.object({ decisions: z.array(z.record(z.string(), z.unknown())), check: z.boolean().optional() }).shape,
+        async (c, a) => ok("Binding decisions.", await c.fetchJSON(c.url(`/management/projects/binding-decisions`), { method: "POST", body: JSON.stringify({ declare: a.decisions, ...a.check === true ? { dryRun: true } : {} }) }))
+      ),
       // ── Deploy to the user's own host (parity with remote /mcp) ──
       // A person connects Vercel or Netlify in the dashboard; nothing here touches OAuth or a host
       // token. deploy_to_host takes artifact:write like deploy_project. @see management/deploy-targets.ts
@@ -6339,7 +6367,7 @@ ${notes.join("\n")}` : summary, created);
       name: "publish_layout",
       config: {
         title: "Publish the Global Layout draft",
-        description: "Publish the connected project's GLOBAL Layout draft (navigation, footer, every reserved section). On a site BetterCMS serves, a Layout publish never builds: it writes the VALUES into the live pages, and a STRUCTURE change (Sections added, removed, moved) waits for a Rebuild or a push (`layout-rebuild-required`); a custom host gets its deploy hook. Until published, get_layout copy:'published' answers PUBLISHED_LAYOUT_UNAVAILABLE. Pass get_layout's `revision` as ifMatch; a stale one returns 409 \u2014 re-read, never retry blindly. A 422 lists validation issues (global, or per page override: pageSlug, copy) to fix with update_layout. A new project's chrome is draft: publish_component navigation-default and footer-default first (the order and the optional logo: skill components). Verify with get_layout copy:'published' \u2014 this response is the write's echo, not a receipt. Page Layout overrides go live with the page (update_page status:'published'). 403 PUBLISH_NOT_GRANTED: this connection may author drafts, not publish \u2014 say so; the user allows it or publishes from the dashboard.",
+        description: "Publish the connected project's GLOBAL Layout draft (navigation, footer, every reserved section). On a site BetterCMS serves, a Layout publish never builds: it writes the VALUES into the live pages, and a STRUCTURE change (Sections added, removed, moved) waits for a Rebuild or a push (`layout-rebuild-required`); a custom host gets its deploy hook. Until published, get_layout copy:'published' answers PUBLISHED_LAYOUT_UNAVAILABLE. Pass get_layout's `revision` as ifMatch; a stale one returns 409 \u2014 re-read, never retry blindly. A 422 lists validation issues (global, or per page override: pageSlug, copy) to fix with update_layout. The platform's Navigation/Footer Defaults publish themselves \u2014 never publish_component them first; the optional logo: skill components. Verify with get_layout copy:'published' \u2014 this response is the write's echo, not a receipt. Page Layout overrides go live with the page (update_page status:'published'). 403 PUBLISH_NOT_GRANTED: this connection may author drafts, not publish \u2014 say so; the user allows it or publishes from the dashboard.",
         inputSchema: publishLayoutInput.shape
       },
       handler: guard(async (args) => withClient(async (client) => {