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

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,25 @@ 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 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`.
+
+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
+   `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
+   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
+   (`preview`); editors' "Preview on site" opens drafts there.
+5. **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/other-frameworks.md

@@ -25,7 +25,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.82.0",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {