@bettercms-ai/mcp 0.82.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.