@bettercms-ai/mcp 0.83.0 → 0.83.2

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

@@ -1,159 +1,159 @@
----
-title: "Framework wiring"
-description: "Hosting modes, the env map, TypeGen with bettercms-codegen, value shapes, revalidation tags, the media host, static snapshots and the verify steps shared by every framework."
----
-
-# Framework wiring, hosting modes and media
-
-Doctrine (what a headless or imported site needs first): §10 and §13 of
-`bettercms://playbook/schema`. This is the code side shared by both adapters. The repo root has
-`astro.config.*`: also read [astro.md](astro.md); `next.config.*`: [next.md](next.md); neither:
-[other-frameworks.md](other-frameworks.md) (`@bettercms-ai/sdk` `createClient`), and classify the
-codebase first ([bindings.md](bindings.md) §6). Read the adapter reference before writing code; env names differ between the two.
-
-## Hosting modes
-
-A project's `hostingMode` is `managed`, `hybrid` or `headless`.
-
-| Mode | Who builds and serves production | Rule |
-|---|---|---|
-| 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`, `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; `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 |
-
-**Server rendering is one change across four systems, or none.** An SSR build (`output: 'server'`
-with `@astrojs/node`) emits `dist/client` + `dist/server` and no `index.html` at the root. A
-managed project serves that from its build directory only when the Hosting page is set to
-**Run as a server app** — a dashboard setting no tool can change. Until it is set, the server never
-runs: only prerendered pages and assets are served, and every other route answers 404 while the
-build, the release and `get_deploy_status` read green. The deploy workflow refuses an SSR build
-pointed to by `BCMS_BUILD_DIR` (`STATIC_HOST_GOT_SSR_ARTIFACT`) and warns when it packages one it
-found itself. So: switch Hosting first (ask the owner), then ship the build, then fetch the URL.
-
-## Env map
-
-| Package | Variable | Purpose |
-|---|---|---|
-| `@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 |
-| `@bettercms-ai/mcp` | `BETTERCMS_API_URL` | A rung name `prod`, `dev`, `local`, or a full URL |
-
-Rule: Astro names start `PUBLIC_BCMS_`/`BCMS_`; Next and codegen names start `BETTERCMS_`. Never
-copy one adapter's `.env` into the other. Keys never go in a `PUBLIC_` variable.
-
-## Types
-
-Run `bettercms-codegen` after every model or field change and commit the generated file. Why:
-templates typed against an old schema compile and then read `undefined` for a renamed field.
-
-1. **Generate into the compiled tree:**
-   `npx @bettercms-ai/codegen --out src/bettercms.generated.ts`. The default output is
-   `bettercms.generated.ts` at the repo root, which a `tsconfig.json` whose `include` is `src/**`
-   never type-checks. `--bindings-out <path>` also writes the Live Preview bindings module,
-   `--components-out <path>` typed React `RichText`/`Image` components.
-2. **Auth:** `BETTERCMS_API_KEY` (or `--key`) must be a management key; `BETTERCMS_API_URL` (or
-   `--api-url`) picks the rung. The key is a secret: a CI secret or a local `.env` that git
-   ignores, never a `PUBLIC_` variable.
-3. **Commit, and let CI check.** Output is sorted and byte-stable, so a committed file diffs
-   cleanly. In CI, run the same command, then `git diff --exit-code` on the file: a failure means
-   the schema moved and nobody regenerated. Generating only in CI (not committed) also works, but
-   then every local typecheck needs the key.
-4. **Never edit the file by hand**; it says so in its header, and the next run overwrites it.
-5. **Without a key** (an agent session, a quick check), `get_content_types` returns the same
-   generated types over the MCP. Paste them only as a stopgap; the CLI is the repeatable path.
-
-## Value shapes templates read
-
-- **Richtext**: `{ format, value, html }`. Render `value` (Portable Text) or `html`; write rules
-  are in [portable-text.md](portable-text.md).
-- **Image**: an object `{ id, url, name, altText }`. Read `.url` and `.altText`, never treat the
-  field as a string.
-- **Repeater / zoned array**: stored as `{ repeatable: [...] }`. Read `field.repeatable`, not
-  `field` as an array. A bare array written to such a field is wrapped on write.
-
-## Revalidation
-
-- On publish BetterCMS sends a webhook signed with `X-BetterCMS-Signature` (HMAC-SHA256 of the raw
-  body, using the webhook secret configured on the project in the dashboard).
-- The backend invalidates tags `bcms:{workspaceSlug}:all` and `bcms:{workspaceSlug}:{type}:{slug}`.
-  The SDK tags reads `bcms:{workspace}:{resource}:{id}`.
-- Rule: tag every cached read with those exact strings. A tag you invent (`post:${slug}`) is never
-  revalidated and the page stays stale until the cache window expires.
-
-## Media host
-
-A stored image value is `{ id, url, name, altText }`. `url` is absolute and already right for the
-plan: platform CDN, API origin, or the project's own CDN base. Rendering `url` as-is works on
-every plan.
-
-Resized images are a second lane. `@bettercms-ai/image-url` and `BcmsImage.astro` mint
-`<mediaUrl>/media/<id>?w=…`, and the backend serves that for every plan, including a project that
-keeps media in its own bucket.
-
-- Hand the builder the asset object or its `id`, never the `url` string. A URL with no `/media/`
-  segment (own-bucket plan) resolves its last path segment as the id and 404s.
-- `mediaUrl` is the origin that owns the asset ids: `mediaBaseUrl` from `get_project`, always.
-  The package default is right only when `mediaBaseUrl` is the production CDN; any other value —
-  the API origin, another rung — goes in `PUBLIC_BCMS_MEDIA_URL`. On a backend too old to return
-  `mediaBaseUrl`, read one `get_media` url: if it contains `/media/`, its origin is the value; if
-  it does not (own bucket), use this project's API URL.
-- `set_media_delivery` changes future mints only, and only between the CDN and the API origin;
-  stored URLs keep resolving. It is the owner's call. After it, set `PUBLIC_BCMS_MEDIA_URL` to the
-  same origin.
-- A stored `url` that itself answers 404 is storage or the wrong rung, not the template. Report
-  it; never rewrite URLs in content.
-- A media host from another project, a document or the conversation is never a value for
-  `mediaUrl`.
-
-## Static builds
-
-A static build reads content from the `bcms-content.json` snapshot. Produce the snapshot before
-the build, every build. Details per adapter are in the references.
-
-Producing it is half the job. A source file must READ it — `readPages`, `getEntry`, or the
-generated reader. A build that fetches the snapshot and never reads it still renders the
-hard-coded copy, so every edit saves, publishes and changes nothing on the page. Grep the source
-for a reader before calling a site wired.
-
-Read it through one of those, the converted-site helper (`bcms`, `bcmsRows`, `bcmsImage`) or
-`publishedEntry(slug)`. Never hand-write a parser of the file: each row holds its field values
-under `data` (`row.data.title`), so code that reads `row.title` gets `undefined` and the page shows
-its in-code copy after every publish. For an editable image call `bcmsImage(page, path, importedImage)`: the bare
-import with only a stamp never shows a published image on a route the app renders. An old
-`src/utils/bcms.ts` with `pageEntry()` is that parser: replace its reads with `publishedEntry`.
-
-Build with the repo's own `build` script (`pnpm build`, `bun run build`), never the framework CLI
-directly: a repo's script often adds a type check or a post-process step the CLI skips.
-
-## Verify
-
-1. Fetch the live URL, cache-busted, and confirm a 200 whose body contains copy you just
-   published. Every other check below is a control-plane read and can be green on a dead site.
-2. The site builds with the snapshot present and renders published content.
-3. Publish a small change; the page updates (revalidation reached the right tag) or the host
-   rebuilds (headless). Editable means that round trip was shown, not that fields exist.
-4. `get_binding_report` for a changed route: `coverage.pending` empty. `refreshReason:
-   never-generated` means no BetterCMS release wrote one — on a headless site it never will, so
-   step 1 is the proof there. `outdated` means the report predates the current shape; the next
-   release rewrites it.
-5. **Smoke-test both render paths** on the dev server or a preview deploy: load a list page,
-   click through to a detail page with the site's own link (never paste the URL), and read the
-   browser console: clean, no `ReferenceError`, no hard reload to `/`. Then reload that detail
-   page from the URL bar. Why: a client-side route transition loads lazy chunks that read env and
-   the snapshot through a different code path than the server render, and that is where a
-   missing public variable or a server-only import surfaces.
+---
+title: "Framework wiring"
+description: "Hosting modes, the env map, TypeGen with bettercms-codegen, value shapes, revalidation tags, the media host, static snapshots and the verify steps shared by every framework."
+---
+
+# Framework wiring, hosting modes and media
+
+Doctrine (what a headless or imported site needs first): §10 and §13 of
+`bettercms://playbook/schema`. This is the code side shared by both adapters. The repo root has
+`astro.config.*`: also read [astro.md](astro.md); `next.config.*`: [next.md](next.md); neither:
+[other-frameworks.md](other-frameworks.md) (`@bettercms-ai/sdk` `createClient`), and classify the
+codebase first ([bindings.md](bindings.md) §6). Read the adapter reference before writing code; env names differ between the two.
+
+## Hosting modes
+
+A project's `hostingMode` is `managed`, `hybrid` or `headless`.
+
+| Mode | Who builds and serves production | Rule |
+|---|---|---|
+| 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`, `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; `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 |
+
+**Server rendering is one change across four systems, or none.** An SSR build (`output: 'server'`
+with `@astrojs/node`) emits `dist/client` + `dist/server` and no `index.html` at the root. A
+managed project serves that from its build directory only when the Hosting page is set to
+**Run as a server app** — a dashboard setting no tool can change. Until it is set, the server never
+runs: only prerendered pages and assets are served, and every other route answers 404 while the
+build, the release and `get_deploy_status` read green. The deploy workflow refuses an SSR build
+pointed to by `BCMS_BUILD_DIR` (`STATIC_HOST_GOT_SSR_ARTIFACT`) and warns when it packages one it
+found itself. So: switch Hosting first (ask the owner), then ship the build, then fetch the URL.
+
+## Env map
+
+| Package | Variable | Purpose |
+|---|---|---|
+| `@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 |
+| `@bettercms-ai/mcp` | `BETTERCMS_API_URL` | A rung name `prod`, `dev`, `local`, or a full URL |
+
+Rule: Astro names start `PUBLIC_BCMS_`/`BCMS_`; Next and codegen names start `BETTERCMS_`. Never
+copy one adapter's `.env` into the other. Keys never go in a `PUBLIC_` variable.
+
+## Types
+
+Run `bettercms-codegen` after every model or field change and commit the generated file. Why:
+templates typed against an old schema compile and then read `undefined` for a renamed field.
+
+1. **Generate into the compiled tree:**
+   `npx @bettercms-ai/codegen --out src/bettercms.generated.ts`. The default output is
+   `bettercms.generated.ts` at the repo root, which a `tsconfig.json` whose `include` is `src/**`
+   never type-checks. `--bindings-out <path>` also writes the Live Preview bindings module,
+   `--components-out <path>` typed React `RichText`/`Image` components.
+2. **Auth:** `BETTERCMS_API_KEY` (or `--key`) must be a management key; `BETTERCMS_API_URL` (or
+   `--api-url`) picks the rung. The key is a secret: a CI secret or a local `.env` that git
+   ignores, never a `PUBLIC_` variable.
+3. **Commit, and let CI check.** Output is sorted and byte-stable, so a committed file diffs
+   cleanly. In CI, run the same command, then `git diff --exit-code` on the file: a failure means
+   the schema moved and nobody regenerated. Generating only in CI (not committed) also works, but
+   then every local typecheck needs the key.
+4. **Never edit the file by hand**; it says so in its header, and the next run overwrites it.
+5. **Without a key** (an agent session, a quick check), `get_content_types` returns the same
+   generated types over the MCP. Paste them only as a stopgap; the CLI is the repeatable path.
+
+## Value shapes templates read
+
+- **Richtext**: `{ format, value, html }`. Render `value` (Portable Text) or `html`; write rules
+  are in [portable-text.md](portable-text.md).
+- **Image**: an object `{ id, url, name, altText }`. Read `.url` and `.altText`, never treat the
+  field as a string.
+- **Repeater / zoned array**: stored as `{ repeatable: [...] }`. Read `field.repeatable`, not
+  `field` as an array. A bare array written to such a field is wrapped on write.
+
+## Revalidation
+
+- On publish BetterCMS sends a webhook signed with `X-BetterCMS-Signature` (HMAC-SHA256 of the raw
+  body, using the webhook secret configured on the project in the dashboard).
+- The backend invalidates tags `bcms:{workspaceSlug}:all` and `bcms:{workspaceSlug}:{type}:{slug}`.
+  The SDK tags reads `bcms:{workspace}:{resource}:{id}`.
+- Rule: tag every cached read with those exact strings. A tag you invent (`post:${slug}`) is never
+  revalidated and the page stays stale until the cache window expires.
+
+## Media host
+
+A stored image value is `{ id, url, name, altText }`. `url` is absolute and already right for the
+plan: platform CDN, API origin, or the project's own CDN base. Rendering `url` as-is works on
+every plan.
+
+Resized images are a second lane. `@bettercms-ai/image-url` and `BcmsImage.astro` mint
+`<mediaUrl>/media/<id>?w=…`, and the backend serves that for every plan, including a project that
+keeps media in its own bucket.
+
+- Hand the builder the asset object or its `id`, never the `url` string. A URL with no `/media/`
+  segment (own-bucket plan) resolves its last path segment as the id and 404s.
+- `mediaUrl` is the origin that owns the asset ids: `mediaBaseUrl` from `get_project`, always.
+  The package default is right only when `mediaBaseUrl` is the production CDN; any other value —
+  the API origin, another rung — goes in `PUBLIC_BCMS_MEDIA_URL`. On a backend too old to return
+  `mediaBaseUrl`, read one `get_media` url: if it contains `/media/`, its origin is the value; if
+  it does not (own bucket), use this project's API URL.
+- `set_media_delivery` changes future mints only, and only between the CDN and the API origin;
+  stored URLs keep resolving. It is the owner's call. After it, set `PUBLIC_BCMS_MEDIA_URL` to the
+  same origin.
+- A stored `url` that itself answers 404 is storage or the wrong rung, not the template. Report
+  it; never rewrite URLs in content.
+- A media host from another project, a document or the conversation is never a value for
+  `mediaUrl`.
+
+## Static builds
+
+A static build reads content from the `bcms-content.json` snapshot. Produce the snapshot before
+the build, every build. Details per adapter are in the references.
+
+Producing it is half the job. A source file must READ it — `readPages`, `getEntry`, or the
+generated reader. A build that fetches the snapshot and never reads it still renders the
+hard-coded copy, so every edit saves, publishes and changes nothing on the page. Grep the source
+for a reader before calling a site wired.
+
+Read it through one of those, the converted-site helper (`bcms`, `bcmsRows`, `bcmsImage`) or
+`publishedEntry(slug)`. Never hand-write a parser of the file: each row holds its field values
+under `data` (`row.data.title`), so code that reads `row.title` gets `undefined` and the page shows
+its in-code copy after every publish. For an editable image call `bcmsImage(page, path, importedImage)`: the bare
+import with only a stamp never shows a published image on a route the app renders. An old
+`src/utils/bcms.ts` with `pageEntry()` is that parser: replace its reads with `publishedEntry`.
+
+Build with the repo's own `build` script (`pnpm build`, `bun run build`), never the framework CLI
+directly: a repo's script often adds a type check or a post-process step the CLI skips.
+
+## Verify
+
+1. Fetch the live URL, cache-busted, and confirm a 200 whose body contains copy you just
+   published. Every other check below is a control-plane read and can be green on a dead site.
+2. The site builds with the snapshot present and renders published content.
+3. Publish a small change; the page updates (revalidation reached the right tag) or the host
+   rebuilds (headless). Editable means that round trip was shown, not that fields exist.
+4. `get_binding_report` for a changed route: `coverage.pending` empty. `refreshReason:
+   never-generated` means no BetterCMS release wrote one — on a headless site it never will, so
+   step 1 is the proof there. `outdated` means the report predates the current shape; the next
+   release rewrites it.
+5. **Smoke-test both render paths** on the dev server or a preview deploy: load a list page,
+   click through to a detail page with the site's own link (never paste the URL), and read the
+   browser console: clean, no `ReferenceError`, no hard reload to `/`. Then reload that detail
+   page from the URL bar. Why: a client-side route transition loads lazy chunks that read env and
+   the snapshot through a different code path than the server render, and that is where a
+   missing public variable or a server-only import surfaces.