@bettercms-ai/mcp 0.81.0 → 0.83.0

package/dist/skills/bettercms/SKILL.md

@@ -72,9 +72,10 @@ These hold on every task. The reference in brackets has the detail and the codes
 5. **Name the folder system every time you say "folder"**: Content sidebar folders never touch a
    URL, URL page folders are part of the path, media folders organise assets.
    [content-modeling.md]
-6. **Headless projects are built by their host.** Never `deploy_project` or
-   `create_deploy_upload` there, never add `bcms-rebuild.yml`; deploy = push to the repo the
-   provider builds. [frameworks.md]
+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
@@ -123,7 +124,7 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 
 | 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 |
+| 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 |

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

@@ -19,13 +19,13 @@ A project's `hostingMode` is `managed`, `hybrid` or `headless`.
 |---|---|---|
 | managed | BetterCMS | `deploy_project` / `create_deploy_upload` are the deploy path |
 | hybrid | BetterCMS, and the client also reads content headlessly | Treat exactly like managed for builds and hosting |
-| headless | The client's own host (Vercel, Netlify, Cloudflare Pages) | Never call `deploy_project` or `create_deploy_upload`; never add `bcms-rebuild.yml`. Deploy = push to the repo the host builds |
+| headless | The client's own host (Vercel, Netlify, Cloudflare Pages) | Never call `deploy_project`, `deploy_to_host` or `create_deploy_upload`; never add `bcms-rebuild.yml`. Deploy = `npx @bettercms-ai/cli@latest deploy --to <host>`, or push to the repo the host builds. Done = `receipt.frontEnd` closed ([getting-started.md](getting-started.md)) |
 
 Headless refusals, by code:
 
 | Code | Cause | Fix |
 |---|---|---|
-| `HEADLESS_NO_BUILD` | A build, release or deploy was sent for a headless project | Stop; push to the provider instead |
+| `HEADLESS_NO_BUILD` | A build, release or deploy was sent for a headless project | Stop; `bettercms deploy --to <host>` or push to the provider instead |
 | `HEADLESS_NEEDS_CUSTOM_HOST` | GitHub connect without a provider host | Add Vercel, Netlify or Cloudflare Pages under Custom hosting in the dashboard, then connect |
 | `HEADLESS_ARTIFACT_TARGET` | The custom host expects builds from BetterCMS | Switch the host to build from the repo |
 
@@ -45,6 +45,9 @@ found itself. So: switch Hosting first (ask the owner), then ship the build, the
 | `@bettercms-ai/astro` | `PUBLIC_BCMS_API_URL`, `PUBLIC_BCMS_WORKSPACE`, `PUBLIC_BCMS_PROJECT_ID` | Where reads go |
 | `@bettercms-ai/astro` | `PUBLIC_BCMS_MEDIA_URL`, `PUBLIC_BCMS_STUDIO_URL` | Media host, editor origin |
 | `@bettercms-ai/astro` | `BCMS_API_KEY`, `BCMS_DRAFT_SECRET` | Server-only key; draft cookie signing |
+| `@bettercms-ai/react` | `VITE_BCMS_API_URL`, `VITE_BCMS_WORKSPACE`, `VITE_BCMS_PROJECT_ID` | Where reads go (no key, no secret: a browser app) |
+| `@bettercms-ai/sveltekit` | `PUBLIC_BCMS_API_URL`, `PUBLIC_BCMS_WORKSPACE`, `PUBLIC_BCMS_PROJECT_ID`; `BCMS_DRAFT_SECRET` | Where reads go; draft cookie signing |
+| `@bettercms-ai/nuxt` | `NUXT_PUBLIC_BCMS_API_URL`, `NUXT_PUBLIC_BCMS_WORKSPACE`, `NUXT_PUBLIC_BCMS_PROJECT_ID`; `BCMS_DRAFT_SECRET` | Where reads go; draft cookie signing |
 | `@bettercms-ai/next` (snapshot bin) | `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE` | Pull `bcms-content.json` |
 | `@bettercms-ai/next` | `BETTERCMS_PREVIEW=1` | Read live instead of the snapshot in a preview build |
 | `@bettercms-ai/codegen` | `BETTERCMS_API_URL`, `BETTERCMS_API_KEY` | Fetch models for typegen |

package/dist/skills/bettercms/references/getting-started.md

@@ -38,7 +38,7 @@ Check: the MCP answers for this project id, and this folder is its repo.
      failed, run the command the warning prints, inside the clone.
    - Either way, stop and ask the user to restart you **inside** the repo folder: an MCP entry
      added while you run loads only when the agent starts, and every step below works on that
-     folder's source.
+     folder's source. Not when `init` launched you: you already run there, connected.
 
 ### Phase 2 — No questions: the defaults are recorded
 
@@ -117,3 +117,40 @@ Check: the deployed site passes the numbers below on every route.
    ([site-blueprints.md](site-blueprints.md)), then build sections ([components.md](components.md)).
 3. When a repo exists, clone it with the `init` command above, restart inside it, and continue
    from Phase 3.
+
+## A headless project (its own front end)
+
+`get_project` says `hostingMode: "headless"`: BetterCMS never builds this site, its own host does.
+Done is `receipt.frontEnd` closed AND `receipt.gate` complete in get_next_steps: BetterCMS derived
+the owner's pages, their code reads the content, the front end has its site URL and rebuilds on
+publish. Work the rows in order; never `deploy_project` or `deploy_to_host`.
+
+1. **Launched by `bettercms init`** (`--agent claude|codex|opencode|cursor|gemini`): you run in the
+   owner's own front end, already connected. Do not ask to be restarted. **Their code, design and
+   copy ARE the site:** keep every component, route, class, style and asset; never redesign a page,
+   rebuild one from scratch or swap their components for new ones. A starter is only ever the
+   starting point when the owner chose one (`init --framework`).
+2. **Derive** (`derive` row). `npx @bettercms-ai/cli@latest derive` in the front end's folder builds
+   the site, renders every page as a visitor sees it and sends the pages to BetterCMS, which derives
+   their pages, fields and today's copy exactly as from a build it made. init runs it first; run it
+   yourself while the row is open. Never model those pages again.
+3. **Convert in place** (`receipt.gate`, the same gate as any built site). `get_conversion_brief
+   { complete: true }`, the convert codemod over this folder (its command is in
+   `bettercms://playbook/schema` §13), then `submit_conversion_receipt` with the receipt it wrote:
+   each literal becomes a read of its field with the markup byte-identical. Bind what it leaves pending by hand the same way. Then
+   start the build script with it, `"build": "bettercms pull-content && next build"`
+   (`@bettercms-ai/cli` a devDependency; not a `prebuild` hook, which Yarn and pnpm skip): the
+   converted pages read `bcms-content/*.json`, which only that step writes on the host's build.
+4. **Wire and read.** `.env` gets `BCMS_API_URL`, `BCMS_WORKSPACE` and `BCMS_PROJECT_ID` (from
+   `get_project`); published content needs no key. A starter whose config reads a key gets one
+   from `create_delivery_key` (`scope: "published"`), written straight into `.env`, never into
+   chat or a commit. Run the app and load a page: its first read closes `read`.
+5. **Deploy.** `npx @bettercms-ai/cli@latest deploy --to vercel|netlify|cloudflare` from the
+   folder: the host's own sign-in, the `BCMS_*` variables set there, and the rebuild hook
+   registered (`publish-hook`). A front end that revalidates instead: `set_front_end
+   { revalidation }`. Then `derive` again, so the gate measures what ships: on headless, every
+   gate fix that says rebuild means deploy, then derive.
+6. **Open it from BetterCMS.** `set_front_end { siteUrl, framework }` with the deployed URL
+   (`preview`); editors' "Preview on site" opens drafts there.
+7. **Publish**, then get_next_steps until `receipt.complete` is true. Schema and content work is
+   the same as on any project ([content-modeling.md](content-modeling.md)).

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

@@ -28,10 +28,10 @@ Nothing is mounted automatically. Add the routes:
 
 ## Revalidation route
 
-`createRevalidateRoute({ secret })` → export `POST`. With `secret` set it verifies
-`X-BetterCMS-Signature` against the raw body, then calls `revalidateTag` for each tag in the
-webhook. Use the project's webhook secret from the dashboard (the package docs name the env
-`BCMS_REVALIDATE_SECRET`; any server env works). Tag your reads with the backend's tag strings
+`createRevalidateRoute()` → export `POST`. It verifies `X-BetterCMS-Signature` against the raw
+body with `secret`, else `BCMS_REVALIDATE_SECRET` (the project's revalidation secret from the
+dashboard), then revalidates every tag (`revalidateTag(tag, "max")`) and every page path
+(`revalidatePath`) the publish changed. Tag your reads with the backend's tag strings
 ([frameworks.md](frameworks.md) Revalidation).
 
 ## Rendering
@@ -164,8 +164,11 @@ Pages Router the page passes on the prop it got: `<HomeView bcmsSections={bcmsSe
 
 ## Static export (`output: "export"`)
 
-- Run `bettercms-snapshot` before `next build`, every build (make it the prebuild step). It writes
-  `bcms-content.json` from `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE`.
+- Pull the content before `next build`, every build: `"build": "bettercms pull-content && next build"`
+  (what `bettercms init` writes; keyless, it reads the project's published content).
+  `bettercms-snapshot` (from `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE`) does the
+  same with a key. Either writes `bcms-content.json`, and `createBetterCMS()` with no arguments reads
+  its workspace and project from it (after `NEXT_PUBLIC_BCMS_*`).
 - Without the snapshot the reads throw `SNAPSHOT_MISSING`. Why it throws instead of fetching:
   a live fetch would turn pages into dynamic routes, and a static export silently leaves them out
   of `out/`.
@@ -180,7 +183,7 @@ Pages Router the page passes on the prop it got: `<HomeView bcmsSections={bcmsSe
 
 | Symptom | Cause | Rule |
 |---|---|---|
-| Empty `out/` after `next build` | No snapshot | Run `bettercms-snapshot` first |
+| Empty `out/` after `next build` | No snapshot | Run `bettercms pull-content` first |
 | Page never updates after publish | Read tags do not match backend tags | Use `bcms:{workspace}:…` tags |
 | Component instance renders nothing | `components` not passed | `readComponents()` into `BcmsBlocks` |
 | Canonical missing or wrong only on the self-hosted site | `buildMetadata` without `location`, and no `BETTERCMS_SITE_URL` or a prefixed route | Pass `{ siteUrl, path }` |

package/dist/skills/bettercms/references/other-frameworks.md

@@ -5,10 +5,27 @@ description: "Reading BetterCMS content from Nuxt, SvelteKit, React Router or Vi
 
 # Other frameworks
 
-Read this when the repo has neither `astro.config.*` nor `next.config.*`. Only Astro and Next have
-adapters; everything else reads through the framework-agnostic core in `@bettercms-ai/sdk`, the
-same one both adapters wrap. Shared rules (hosting modes, value shapes, media host, revalidation
-tags) are in [frameworks.md](frameworks.md).
+Read this when the repo has neither `astro.config.*` nor `next.config.*`. React (Vite), SvelteKit
+and Nuxt have adapters (§0); anything else reads through the framework-agnostic core in
+`@bettercms-ai/sdk`, the same one every adapter wraps. Shared rules (hosting modes, value shapes,
+media host, revalidation tags) are in [frameworks.md](frameworks.md).
+
+## 0. The adapters
+
+| Repo has | Install | Settings | Sections | Drafts |
+|---|---|---|---|---|
+| `vite.config.*` + React | `@bettercms-ai/react` | `<BcmsProvider env={import.meta.env}>`, `VITE_BCMS_*` | `<BcmsBlocks blocks={page.blocks}>` (Next's markup) | the editor's `/api/draft` link, no server; the host rewrites it to the app |
+| `svelte.config.*` (SvelteKit) | `@bettercms-ai/sveltekit` | `createBcms({ env: { ...publicEnv, ...privateEnv } })`, `PUBLIC_BCMS_*` | `bcms.sections(slug, fetch)` in `load`, then `<div use:bcmsSections={data.sections}>{@html sectionsMarkup(data.sections)}</div>` | `src/routes/api/draft/+server.ts`: `GET = ({ request }) => bcms.draftEnable(request)`; `await bcms.client(request)` reads drafts |
+| `nuxt.config.*` | `@bettercms-ai/nuxt` | `createBcms({ env: process.env })` in `server/utils`, `NUXT_PUBLIC_BCMS_*` | a server route returning `bcms.sections(slug)`, then `<div v-bcms-sections v-html="sectionsMarkup(data)">` | `server/routes/api/draft.get.ts`: `bcms.draftEnable(toWebRequest(e))` |
+
+- SvelteKit and Nuxt sections are server-rendered by BetterCMS (the hosted renderer's markup, a
+  stylesheet scoped to `[data-bcms-rendered="platform"]`, and the form, slider and tab scripts):
+  never rebuild them as components, and never paste their HTML into the repo. Field copy outside
+  the sections is still read with the client and bound with `data-bcms-field`
+  ([bindings.md](bindings.md)).
+- The sections are the PUBLISHED page; draft mode switches the client, not the fragment.
+- Set `BCMS_PROJECT_ID` under the framework's prefix: sections and keyless reads are addressed to it.
+- `BCMS_DRAFT_SECRET` (server-only) signs the draft cookie on SvelteKit and Nuxt; a React SPA has none.
 
 ## 1. The client
 
@@ -25,7 +42,9 @@ export const bcms = createClient({
 Reading published content needs no key. The platform sets `BCMS_API_URL`, `BCMS_WORKSPACE` and
 `BCMS_PROJECT_ID` on every build and running server app, and again under each framework's public
 prefix (`NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`…); the table is in
-[external-content.md](external-content.md). Never add them to `.env`.
+[external-content.md](external-content.md). On a site BetterCMS builds, never add them to `.env`.
+A headless front end on its own host sets them itself: in `.env` locally, and on the host by
+`npx @bettercms-ai/cli@latest deploy --to <host>`.
 
 | Option | Use |
 |---|---|

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

@@ -49,7 +49,7 @@ that reads them.
 | Hosting mode | Release path | Public proof |
 |---|---|---|
 | `managed` or `hybrid` | `deploy_project` or `create_deploy_upload`, then `get_deploy_status` | Cache-busted BetterCMS URL answers 200 with the intended revision |
-| `headless` | Publish content in BetterCMS; the frontend deploys through its own host and rebuild or revalidation | The external host's URL answers 200 with the intended content and metadata |
+| `headless` | Publish content in BetterCMS; the frontend deploys through its own host (`npx @bettercms-ai/cli@latest deploy --to <host>` the first time, which registers the rebuild hook) and rebuild or revalidation | The external host's URL answers 200 with the intended content and metadata |
 
 A managed site renders static unless the owner switches Hosting to **Run as a server app**, which
 must happen before an SSR build ships ([frameworks.md](frameworks.md)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bettercms-ai/device-auth": "^0.2.0",
-    "@bettercms-ai/sdk": "^1.32.0",
+    "@bettercms-ai/sdk": "^1.35.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },