@bettercms-ai/mcp 0.82.0 → 0.83.0

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

@@ -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

@@ -121,21 +121,36 @@ Check: the deployed site passes the numbers below on every route.
 ## 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 in get_next_steps: the front end reads the content, has its site
-URL, and rebuilds on publish. Work its rows in order; never `deploy_project` or `deploy_to_host`.
+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
-   front end's folder, already connected; it is the user's existing app or a starter `init`
-   cloned. Do not ask to be restarted.
-2. **Wire and read.** `.env` gets `BCMS_API_URL`, `BCMS_WORKSPACE` and `BCMS_PROJECT_ID` (from
+   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`.
-3. **Deploy.** `npx @bettercms-ai/cli@latest deploy --to vercel|netlify|cloudflare` from the
+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 }`.
-4. **Open it from BetterCMS.** `set_front_end { siteUrl, framework }` with the deployed URL
+   { 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.
-5. **Publish**, then get_next_steps until `receipt.complete` is true. Schema and content work is
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.82.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"
   },