@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/dock-input.md

@@ -1,121 +1,121 @@
----
-title: "Custom dock inputs"
-description: "When a field earns its own input in the editor dock, how to ask the user first, the input contract and protocol, the writes allowlist, the file layout, and the fallback guarantee."
----
-
-# Custom dock inputs
-
-**Outcome.** A field whose choice the stock dock cannot show (a colour, a preset scale, one look
-set by several props) gets a small input the user approved, and every other field keeps the stock
-control. Nothing an author or a visitor sees can break because of it.
-
-## 1. The restraint ladder
-
-Industry practice: a custom input is the last resort. Climb in this order and stop at the first
-rung that works.
-
-1. **The stock control.** The field type already draws one: text, number, select, boolean, image.
-2. **A composition of ui keys.** `ui.control` (`segmented` for a short single choice), `ui.preview`
-   and `ui.layout` for list items, `ui.group` for props, model `fieldsets` for groups, rows and
-   tabs. See editor-chrome.md.
-3. **A custom input.** Only when rungs 1 and 2 cannot show the choice, and only with the user's yes.
-
-A custom input never adds data. It draws fields that already exist in the schema.
-
-## 2. Suggest, then the user approves
-
-`get_next_steps` lists `dock-input-candidate` when a field or prop looks like it needs one. Each
-row has the field `key`, a `reason` and, for a look set by several props, the sibling keys it would
-`writes`. The rule is a candidate list, never a defect.
-
-1. Check rungs 1 and 2 for each row. Drop rows they cover.
-2. Ask the user, in one message per field: name the field, the input you would write and the
-   reason the stock control cannot do it. Wait for an explicit yes.
-3. On yes: write the input file (section 5), then set `ui.input` with `confirmed: true`. These
-   merge into the stored `ui`:
-   `update_content_model { modelId | pageId, fieldUi: { "<path>": { input: { name, writes } } }, ifMatch, confirmed: true }`,
-   `update_component { componentId, propUi: { "<key>": { input: { name, writes } } }, ifMatch, confirmed: true }`.
-   `update_field`'s `ui` MERGES per key into the stored `ui`, as `fieldUi` does: send `null` for a key to clear it.
-4. On no: leave it. Nothing is broken.
-
-A write through the agent tools that sets or changes `ui.input` without `confirmed: true` is
-refused 409 `input_needs_confirmation`, naming each path. `confirmed: true` is true only after the
-user approved that input; never send it to get past the refusal. Removing `ui.input` (send
-`input: null`) needs no approval. The create tools carry no approval: create the field without
-`ui.input`, then add it with `update_field` or `update_component`. A person saving in the
-dashboard is the approver and is never asked.
-
-## 3. The contract
-
-The input is a React component that receives `DockInputProps` from `@bettercms-ai/dock-input`:
-
-| Prop | What it is |
-|---|---|
-| `value` | this field's current value |
-| `field` | `{ key, label, type, required, readOnly, writes, config? }`: the stored options and limits |
-| `document` | a read-only snapshot of the whole document's values, by field key |
-| `readOnly` | true when the author may not edit; draw the value, accept nothing |
-| `theme` | `"light"` or `"dark"`, for the kit theme |
-| `onChange(value)` | set this field |
-| `writeFields(patches)` | set this field and siblings listed in `field.writes`, together |
-
-`writeFields` takes `[{ field, value }]`, applies all of them or none to the DRAFT, as one undo
-step, and resolves `{ ok, reason? }`. Show the `reason` when `ok` is false.
-
-Build the UI from `@bettercms-ai/kit` so it matches the dock in both themes. The input never sees a
-token and makes no network call for content: everything it needs arrives as props.
-
-## 4. Writes discipline
-
-`ui.input.writes` lists EVERY sibling field key the input writes, and nothing else. The dock
-refuses a patch to a key outside it, and checks each value against that field's own schema. A
-button-look input over `buttonVariant` set on `buttonVariant` declares
-`writes: ["buttonSize", "buttonColor"]`. An input that only edits its own field omits `writes`.
-At most 16 keys, each an existing sibling.
-
-## 5. File layout
-
-One file per input, in the site's repository:
-
-```
-bettercms/inputs/<name>.tsx
-```
-
-- `<name>` is the `ui.input.name`: lowercase letters, digits and dashes, 1 to 48 characters,
-  starting with a letter (`button-look`, `brand-swatch`).
-- The default export is the component, and the file does nothing else. The build wraps it in
-  `mountDockInput`, which speaks the protocol (section 6), so the component only deals with props.
-  Never call `mountDockInput` in the file: the input would mount twice.
-- The site needs `react`, `react-dom` and `@bettercms-ai/dock-input` in its `devDependencies`
-  (plus `@bettercms-ai/kit` for kit components). The build bundles them into the input.
-- Keep it small and self-contained: kit components and the field's own data, no app imports.
-
-## 6. Protocol summary
-
-`bcms-input/1`, over `window.postMessage` between the dock and a sandboxed frame served from the
-project's own inputs origin, never the dashboard's. `mountDockInput` handles all of it.
-
-- Dock to input: `init` (field, value, document, theme), `value` (after a commit), `result`
-  (the verdict on a `change`), `readOnly`.
-- Input to dock: `ready`, `change` (an id and its patches), `height`, `focus`, `blur`, `error`.
-- Every message carries the session nonce from `init`; the dock drops anything else.
-- Limits: a patch is at most 64 KB of JSON, at most 10 patches per second, and `ready` must arrive
-  within 3 seconds. Larger or faster messages are refused, never truncated.
-
-## 7. Build, serve and scope
-
-- v1 is managed sites only (BetterCMS hosting). On a headless or hybrid site, do not suggest one.
-- The user's approval (`confirmed: true`) also switches custom inputs on for the project, unless an
-  admin switched them off in Settings → General → Visual editor; then `get_next_steps` lists
-  `dock-inputs-off`, and you tell the user instead of working around it.
-- Once custom inputs are enabled for the project, the inputs are built with the site and served
-  on its inputs origin automatically. Push the file, wait for the build, then open the field in the
-  dock to check it.
-- Name only inputs that exist in `bettercms/inputs/`. An unknown name is not an error, it falls back.
-
-## 8. The fallback guarantee
-
-The stock control comes back whenever the input cannot run: an unknown name, inputs disabled for
-the project, a build that failed, a frame that throws or misses `ready`. The value is unchanged
-and stays editable. So a custom input can only add to the dock, never take a field away from an
-author. Removing `ui.input` returns the field to the stock control at once.
+---
+title: "Custom dock inputs"
+description: "When a field earns its own input in the editor dock, how to ask the user first, the input contract and protocol, the writes allowlist, the file layout, and the fallback guarantee."
+---
+
+# Custom dock inputs
+
+**Outcome.** A field whose choice the stock dock cannot show (a colour, a preset scale, one look
+set by several props) gets a small input the user approved, and every other field keeps the stock
+control. Nothing an author or a visitor sees can break because of it.
+
+## 1. The restraint ladder
+
+Industry practice: a custom input is the last resort. Climb in this order and stop at the first
+rung that works.
+
+1. **The stock control.** The field type already draws one: text, number, select, boolean, image.
+2. **A composition of ui keys.** `ui.control` (`segmented` for a short single choice), `ui.preview`
+   and `ui.layout` for list items, `ui.group` for props, model `fieldsets` for groups, rows and
+   tabs. See editor-chrome.md.
+3. **A custom input.** Only when rungs 1 and 2 cannot show the choice, and only with the user's yes.
+
+A custom input never adds data. It draws fields that already exist in the schema.
+
+## 2. Suggest, then the user approves
+
+`get_next_steps` lists `dock-input-candidate` when a field or prop looks like it needs one. Each
+row has the field `key`, a `reason` and, for a look set by several props, the sibling keys it would
+`writes`. The rule is a candidate list, never a defect.
+
+1. Check rungs 1 and 2 for each row. Drop rows they cover.
+2. Ask the user, in one message per field: name the field, the input you would write and the
+   reason the stock control cannot do it. Wait for an explicit yes.
+3. On yes: write the input file (section 5), then set `ui.input` with `confirmed: true`. These
+   merge into the stored `ui`:
+   `update_content_model { modelId | pageId, fieldUi: { "<path>": { input: { name, writes } } }, ifMatch, confirmed: true }`,
+   `update_component { componentId, propUi: { "<key>": { input: { name, writes } } }, ifMatch, confirmed: true }`.
+   `update_field`'s `ui` MERGES per key into the stored `ui`, as `fieldUi` does: send `null` for a key to clear it.
+4. On no: leave it. Nothing is broken.
+
+A write through the agent tools that sets or changes `ui.input` without `confirmed: true` is
+refused 409 `input_needs_confirmation`, naming each path. `confirmed: true` is true only after the
+user approved that input; never send it to get past the refusal. Removing `ui.input` (send
+`input: null`) needs no approval. The create tools carry no approval: create the field without
+`ui.input`, then add it with `update_field` or `update_component`. A person saving in the
+dashboard is the approver and is never asked.
+
+## 3. The contract
+
+The input is a React component that receives `DockInputProps` from `@bettercms-ai/dock-input`:
+
+| Prop | What it is |
+|---|---|
+| `value` | this field's current value |
+| `field` | `{ key, label, type, required, readOnly, writes, config? }`: the stored options and limits |
+| `document` | a read-only snapshot of the whole document's values, by field key |
+| `readOnly` | true when the author may not edit; draw the value, accept nothing |
+| `theme` | `"light"` or `"dark"`, for the kit theme |
+| `onChange(value)` | set this field |
+| `writeFields(patches)` | set this field and siblings listed in `field.writes`, together |
+
+`writeFields` takes `[{ field, value }]`, applies all of them or none to the DRAFT, as one undo
+step, and resolves `{ ok, reason? }`. Show the `reason` when `ok` is false.
+
+Build the UI from `@bettercms-ai/kit` so it matches the dock in both themes. The input never sees a
+token and makes no network call for content: everything it needs arrives as props.
+
+## 4. Writes discipline
+
+`ui.input.writes` lists EVERY sibling field key the input writes, and nothing else. The dock
+refuses a patch to a key outside it, and checks each value against that field's own schema. A
+button-look input over `buttonVariant` set on `buttonVariant` declares
+`writes: ["buttonSize", "buttonColor"]`. An input that only edits its own field omits `writes`.
+At most 16 keys, each an existing sibling.
+
+## 5. File layout
+
+One file per input, in the site's repository:
+
+```
+bettercms/inputs/<name>.tsx
+```
+
+- `<name>` is the `ui.input.name`: lowercase letters, digits and dashes, 1 to 48 characters,
+  starting with a letter (`button-look`, `brand-swatch`).
+- The default export is the component, and the file does nothing else. The build wraps it in
+  `mountDockInput`, which speaks the protocol (section 6), so the component only deals with props.
+  Never call `mountDockInput` in the file: the input would mount twice.
+- The site needs `react`, `react-dom` and `@bettercms-ai/dock-input` in its `devDependencies`
+  (plus `@bettercms-ai/kit` for kit components). The build bundles them into the input.
+- Keep it small and self-contained: kit components and the field's own data, no app imports.
+
+## 6. Protocol summary
+
+`bcms-input/1`, over `window.postMessage` between the dock and a sandboxed frame served from the
+project's own inputs origin, never the dashboard's. `mountDockInput` handles all of it.
+
+- Dock to input: `init` (field, value, document, theme), `value` (after a commit), `result`
+  (the verdict on a `change`), `readOnly`.
+- Input to dock: `ready`, `change` (an id and its patches), `height`, `focus`, `blur`, `error`.
+- Every message carries the session nonce from `init`; the dock drops anything else.
+- Limits: a patch is at most 64 KB of JSON, at most 10 patches per second, and `ready` must arrive
+  within 3 seconds. Larger or faster messages are refused, never truncated.
+
+## 7. Build, serve and scope
+
+- v1 is managed sites only (BetterCMS hosting). On a headless or hybrid site, do not suggest one.
+- The user's approval (`confirmed: true`) also switches custom inputs on for the project, unless an
+  admin switched them off in Settings → General → Visual editor; then `get_next_steps` lists
+  `dock-inputs-off`, and you tell the user instead of working around it.
+- Once custom inputs are enabled for the project, the inputs are built with the site and served
+  on its inputs origin automatically. Push the file, wait for the build, then open the field in the
+  dock to check it.
+- Name only inputs that exist in `bettercms/inputs/`. An unknown name is not an error, it falls back.
+
+## 8. The fallback guarantee
+
+The stock control comes back whenever the input cannot run: an unknown name, inputs disabled for
+the project, a build that failed, a frame that throws or misses `ready`. The value is unchanged
+and stays editable. So a custom input can only add to the dock, never take a field away from an
+author. Removing `ui.input` returns the field to the stock control at once.

package/dist/skills/bettercms/references/editor-chrome.md

@@ -1,92 +1,92 @@
----
-title: "Editor chrome (dock layout)"
-description: "Group, row, tab, icon, segmented control, list item names and showIf order for the dashboard dock; the ifMatch rule and the two chrome refusals."
----
-
-# Editor chrome
-
-**Outcome.** Every dock screen an editor opens fits the click budget, every list names its items,
-and a condition is answered before the field it reveals. The delivered content is byte-identical.
-
-Doctrine: §14 of `bettercms://playbook/schema`; flow: `field-ui` prompt. Editor chrome (field
-`ui`, model `fieldsets`, prop `ui`) changes how the dashboard dock draws a field. It never moves a
-delivered value. Each recipe is one write, then a read-back.
-
-## 1. Read, then write with `ifMatch`
-
-Take `optimisticVersion` from `get_content_model` or `get_component`. For a page's own fields call
-`get_page`, send `pageId`, and use `backingModel.optimisticVersion`. The path args (`fieldUi`,
-`fieldFieldset`, `fieldOrder`, `propUi`, `propGroup`) and the layout keys (`kind`, `tab`, `icon`,
-`itemLabel`, `ui.group`) get 428 `precondition-required` without it. A 409 carrying
-`currentVersion` means someone wrote since your read: read again and re-apply the intent, never
-the old body. Why: path args are merged onto the stored row, and the version is what stops them landing on a
-schema you never saw.
-
-## 2. Group, row, tab
-
-Give a fieldset a `kind`:
-
-| `kind` | Draws | Limits |
-|---|---|---|
-| `group` | Fields folded under one header (`collapsed: true` starts it shut) | 12 rows inside one group |
-| `row` | Short fields on one line | at most 3 fields |
-| `tab` | A tab strip | at most 3 tabs, names of 40 characters or fewer, top-level fields only, tabs never nest |
-
-A group joins a tab with `tab: "<tab id>"`. A fieldset with no `kind` stays flat. Props have no
-fieldsets: the first prop of a group sends `ui.group: { id, label, kind }` and each later one
-`{ id }`; `kind` is `group` or `row`.
-
-Stay inside the budget `get_next_steps` measures per screen: 8 ungrouped rows, 12 rows in a group,
-3 levels, any value within 2 activations. Why: past it the rule `dock-budget` keeps listing the
-screen. A closed group in a second tab already costs 2 activations, so leave groups in later tabs
-open.
-
-## 3. Icons
-
-`ui.icon` belongs on nesting fields, fieldsets and a prop's `ui.group`, never on a leaf. Take names
-from the dock icon list the MCP serves as a resource (`resources/list`); any other string is a
-400. Set a sidebar item's icon with `set_icon`.
-
-## 4. Segmented, dropdown or slider
-
-- `ui.control: "segmented"` on a single-choice select with 2–4 short options: one click replaces
-  two. A multi-select or 5+ options is refused; keep the default dropdown there.
-- `"slider"` needs a `number` with numeric `config.min` below `config.max` and at most 1000 steps.
-
-## 5. Name list items
-
-On each repeater or repeatable zone set `ui.itemLabel` (1–24 characters: "Slide", "Person") and
-`ui.preview.title` naming a child key. Without either, every row reads "Item N" and
-`get_next_steps` keeps listing `dock-repeater-unnamed`.
-
-## 6. Conditional fields
-
-A field's `showIf` reads another field's value. Place the field it reads ABOVE it, so the author
-answers the condition first; a `showIf` that reads a later field is listed as `dock-showif-order`.
-Reorder with `fieldOrder` on `update_content_model`.
-
-## 7. Refusals
-
-| Code | Meaning | Do |
-|---|---|---|
-| 428 `precondition-required` | Layout keys without `ifMatch` | Read, send the version |
-| 409 **ui_human_owned** | A person arranged those paths (the body names them) | Leave them out; `override: true` only when the user asked you to replace their layout |
-| 409 **ui_studio_blind** | The Studio agent does not change editor chrome | Echo the chrome exactly as read, or omit it (the stored chrome is kept) |
-| 400 with a code | A vocabulary rule (**tab_max**, **row_member_count**, **control_segmented**…) | Fix what the message names; §14 lists every code |
-
-To undo an agent change, write back the values from your read before the change, with `ifMatch`.
-
-## 8. Chrome once, in the Layout
-
-Navigation, footer and dialogs live in the Global Layout (`get_layout`, `update_layout`). When
-`get_next_steps` reports `chrome-duplicated`, declare the element in the Layout and push; the page
-copies are stripped for you. Never delete them by hand, and never give them dock chrome.
-
-A Global field with `overridable: false` and a `lockReason` is not offered on a page: a page write
-of it answers 403 **LAYOUT_FIELD_NOT_OVERRIDABLE** with the reason. A page value written earlier is
-kept but the Global value renders; `get_layout` scope page lists it under `shadowed`.
-
-## Acceptance
-
-Read back with `get_content_model`, `get_page` or `get_component`. Done means `get_next_steps`
-lists none of `dock-budget`, `dock-repeater-unnamed`, `dock-showif-order`.
+---
+title: "Editor chrome (dock layout)"
+description: "Group, row, tab, icon, segmented control, list item names and showIf order for the dashboard dock; the ifMatch rule and the two chrome refusals."
+---
+
+# Editor chrome
+
+**Outcome.** Every dock screen an editor opens fits the click budget, every list names its items,
+and a condition is answered before the field it reveals. The delivered content is byte-identical.
+
+Doctrine: §14 of `bettercms://playbook/schema`; flow: `field-ui` prompt. Editor chrome (field
+`ui`, model `fieldsets`, prop `ui`) changes how the dashboard dock draws a field. It never moves a
+delivered value. Each recipe is one write, then a read-back.
+
+## 1. Read, then write with `ifMatch`
+
+Take `optimisticVersion` from `get_content_model` or `get_component`. For a page's own fields call
+`get_page`, send `pageId`, and use `backingModel.optimisticVersion`. The path args (`fieldUi`,
+`fieldFieldset`, `fieldOrder`, `propUi`, `propGroup`) and the layout keys (`kind`, `tab`, `icon`,
+`itemLabel`, `ui.group`) get 428 `precondition-required` without it. A 409 carrying
+`currentVersion` means someone wrote since your read: read again and re-apply the intent, never
+the old body. Why: path args are merged onto the stored row, and the version is what stops them landing on a
+schema you never saw.
+
+## 2. Group, row, tab
+
+Give a fieldset a `kind`:
+
+| `kind` | Draws | Limits |
+|---|---|---|
+| `group` | Fields folded under one header (`collapsed: true` starts it shut) | 12 rows inside one group |
+| `row` | Short fields on one line | at most 3 fields |
+| `tab` | A tab strip | at most 3 tabs, names of 40 characters or fewer, top-level fields only, tabs never nest |
+
+A group joins a tab with `tab: "<tab id>"`. A fieldset with no `kind` stays flat. Props have no
+fieldsets: the first prop of a group sends `ui.group: { id, label, kind }` and each later one
+`{ id }`; `kind` is `group` or `row`.
+
+Stay inside the budget `get_next_steps` measures per screen: 8 ungrouped rows, 12 rows in a group,
+3 levels, any value within 2 activations. Why: past it the rule `dock-budget` keeps listing the
+screen. A closed group in a second tab already costs 2 activations, so leave groups in later tabs
+open.
+
+## 3. Icons
+
+`ui.icon` belongs on nesting fields, fieldsets and a prop's `ui.group`, never on a leaf. Take names
+from the dock icon list the MCP serves as a resource (`resources/list`); any other string is a
+400. Set a sidebar item's icon with `set_icon`.
+
+## 4. Segmented, dropdown or slider
+
+- `ui.control: "segmented"` on a single-choice select with 2–4 short options: one click replaces
+  two. A multi-select or 5+ options is refused; keep the default dropdown there.
+- `"slider"` needs a `number` with numeric `config.min` below `config.max` and at most 1000 steps.
+
+## 5. Name list items
+
+On each repeater or repeatable zone set `ui.itemLabel` (1–24 characters: "Slide", "Person") and
+`ui.preview.title` naming a child key. Without either, every row reads "Item N" and
+`get_next_steps` keeps listing `dock-repeater-unnamed`.
+
+## 6. Conditional fields
+
+A field's `showIf` reads another field's value. Place the field it reads ABOVE it, so the author
+answers the condition first; a `showIf` that reads a later field is listed as `dock-showif-order`.
+Reorder with `fieldOrder` on `update_content_model`.
+
+## 7. Refusals
+
+| Code | Meaning | Do |
+|---|---|---|
+| 428 `precondition-required` | Layout keys without `ifMatch` | Read, send the version |
+| 409 **ui_human_owned** | A person arranged those paths (the body names them) | Leave them out; `override: true` only when the user asked you to replace their layout |
+| 409 **ui_studio_blind** | The Studio agent does not change editor chrome | Echo the chrome exactly as read, or omit it (the stored chrome is kept) |
+| 400 with a code | A vocabulary rule (**tab_max**, **row_member_count**, **control_segmented**…) | Fix what the message names; §14 lists every code |
+
+To undo an agent change, write back the values from your read before the change, with `ifMatch`.
+
+## 8. Chrome once, in the Layout
+
+Navigation, footer and dialogs live in the Global Layout (`get_layout`, `update_layout`). When
+`get_next_steps` reports `chrome-duplicated`, declare the element in the Layout and push; the page
+copies are stripped for you. Never delete them by hand, and never give them dock chrome.
+
+A Global field with `overridable: false` and a `lockReason` is not offered on a page: a page write
+of it answers 403 **LAYOUT_FIELD_NOT_OVERRIDABLE** with the reason. A page value written earlier is
+kept but the Global value renders; `get_layout` scope page lists it under `shadowed`.
+
+## Acceptance
+
+Read back with `get_content_model`, `get_page` or `get_component`. Done means `get_next_steps`
+lists none of `dock-budget`, `dock-repeater-unnamed`, `dock-showif-order`.

package/dist/skills/bettercms/references/external-content.md

@@ -1,78 +1,78 @@
----
-title: "Content in another service"
-description: "Move content a site loads from another CMS or API (Contentful, Sanity, Strapi, Cosmic…) into BetterCMS by rewriting the client module, with the env names the platform supplies."
----
-
-# Content that lives in another service
-
-Read when: the site loads its content from another CMS or content API. Signals:
-
-- A dependency in `package.json`: `cosmicjs` / `@cosmicjs/sdk`, `contentful`, `@sanity/client` /
-  `next-sanity`, `@strapi/*`, `@prismicio/*`, `storyblok-js-client` / `@storyblok/*`,
-  `@datocms/*`, `@wordpress/*`, `graphql-request` or `@apollo/client` pointed at a CMS endpoint.
-- `.env.example` names that service's keys (`*_BUCKET_SLUG`, `*_READ_KEY`, `*_SPACE_ID`,
-  `*_ACCESS_TOKEN`, `*_PROJECT_ID` for another CMS). BetterCMS reports the missing ones on import
-  as `envWarning`.
-- Pages fetch in `getServerSideProps`, `getStaticProps`, server components, `load()` or
-  `useFetch()` from a module that wraps that client.
-
-Two ways out, in this order, and the user types no key in either. When the values already exist
-on this machine, the platform takes them from the user's own files (the first section). When they
-do not, the rule Sanity follows on a migration applies: **the content moves into BetterCMS and the
-site reads it from BetterCMS** (the steps). Never ask the user for a key, and never leave the site
-depending on one it does not have: on BetterCMS it would build and serve, then render empty or
-crash in the browser.
-
-## First: are the values on this machine?
-
-`list_env_vars` names what the repository's `.env.example` declares and the project does not set
-(`missing`). When the user already runs this site, the values are usually in the repository's own
-`.env.local` or `.env`. Then run, in the repository:
-
-    npx @bettercms-ai/cli@latest env push
-
-It uploads the declared variables from those files straight to BetterCMS and prints their names
-only. Never open those files, print a value or ask the user to paste one: a secret in this
-conversation is a secret in a log. Rebuild, and the site runs as it did before.
-
-When `env push` reports the variables as not found, nobody here has the old service's keys. That
-is the case the steps below handle: the content moves into BetterCMS.
-
-## The steps
-
-Check: with every one of the other service's variables unset, `npm run build` succeeds and every
-page renders its content.
-
-1. **Find every read.** List the client module and each function the pages call, with the shape
-   each returns (the fields the components use, not the whole API response).
-2. **Model it** ([content-modeling.md](content-modeling.md)). One model per content type the pages
-   render: a list is a collection, a one-off (navigation, footer, landing hero) is a singleton.
-   Field names follow the code's own names, so the components don't change.
-3. **Seed the content.** If the user can export from the old service themselves, import that.
-   Otherwise create the entries from what the site shows: the repo's fixtures, sample data and
-   README, and the rendered pages in `get_site_composition`. Real-looking copy and working image
-   URLs, never lorem ipsum. The user edits it in BetterCMS afterwards.
-4. **Rewrite the client module, not the pages.** Keep every function's name and return shape, and
-   replace its body with a read from BetterCMS's Delivery API ([frameworks.md](frameworks.md)
-   shows the client per framework). Reading published content needs no key. The platform already
-   sets these on every build and every running server app, under the prefix the framework
-   exposes:
-
-   | Framework | Variables |
-   |---|---|
-   | Next.js | `NEXT_PUBLIC_BCMS_API_URL`, `NEXT_PUBLIC_BCMS_WORKSPACE`, `NEXT_PUBLIC_BCMS_PROJECT_ID` |
-   | Vite (React, Vue, Svelte) | `VITE_BCMS_*` |
-   | Nuxt | `NUXT_PUBLIC_BCMS_*` |
-   | Astro, SvelteKit | `PUBLIC_BCMS_*` |
-   | Create React App | `REACT_APP_BCMS_*` |
-   | Gatsby | `GATSBY_BCMS_*` |
-   | Server code, any framework | `BCMS_API_URL`, `BCMS_WORKSPACE`, `BCMS_PROJECT_ID` |
-
-   Do not add them to `.env` files. They are supplied, like Sanity's project id.
-5. **Keep actions that need the other service's secret working without it.** Payments, uploads and
-   writes to the old service stay in the code, guarded: when the key is unset, the button explains
-   that the feature is not configured. The page never throws.
-6. **Remove what is no longer read.** Drop the old SDK from `package.json` and its keys from
-   `.env.example` once nothing imports them.
-7. **Prove it.** Build with the old variables unset and open every page. Then continue with the
-   `convert_site` prompt: its bindings now point at BetterCMS content, and the Visual Editor edits it.
+---
+title: "Content in another service"
+description: "Move content a site loads from another CMS or API (Contentful, Sanity, Strapi, Cosmic…) into BetterCMS by rewriting the client module, with the env names the platform supplies."
+---
+
+# Content that lives in another service
+
+Read when: the site loads its content from another CMS or content API. Signals:
+
+- A dependency in `package.json`: `cosmicjs` / `@cosmicjs/sdk`, `contentful`, `@sanity/client` /
+  `next-sanity`, `@strapi/*`, `@prismicio/*`, `storyblok-js-client` / `@storyblok/*`,
+  `@datocms/*`, `@wordpress/*`, `graphql-request` or `@apollo/client` pointed at a CMS endpoint.
+- `.env.example` names that service's keys (`*_BUCKET_SLUG`, `*_READ_KEY`, `*_SPACE_ID`,
+  `*_ACCESS_TOKEN`, `*_PROJECT_ID` for another CMS). BetterCMS reports the missing ones on import
+  as `envWarning`.
+- Pages fetch in `getServerSideProps`, `getStaticProps`, server components, `load()` or
+  `useFetch()` from a module that wraps that client.
+
+Two ways out, in this order, and the user types no key in either. When the values already exist
+on this machine, the platform takes them from the user's own files (the first section). When they
+do not, the rule Sanity follows on a migration applies: **the content moves into BetterCMS and the
+site reads it from BetterCMS** (the steps). Never ask the user for a key, and never leave the site
+depending on one it does not have: on BetterCMS it would build and serve, then render empty or
+crash in the browser.
+
+## First: are the values on this machine?
+
+`list_env_vars` names what the repository's `.env.example` declares and the project does not set
+(`missing`). When the user already runs this site, the values are usually in the repository's own
+`.env.local` or `.env`. Then run, in the repository:
+
+    npx @bettercms-ai/cli@latest env push
+
+It uploads the declared variables from those files straight to BetterCMS and prints their names
+only. Never open those files, print a value or ask the user to paste one: a secret in this
+conversation is a secret in a log. Rebuild, and the site runs as it did before.
+
+When `env push` reports the variables as not found, nobody here has the old service's keys. That
+is the case the steps below handle: the content moves into BetterCMS.
+
+## The steps
+
+Check: with every one of the other service's variables unset, `npm run build` succeeds and every
+page renders its content.
+
+1. **Find every read.** List the client module and each function the pages call, with the shape
+   each returns (the fields the components use, not the whole API response).
+2. **Model it** ([content-modeling.md](content-modeling.md)). One model per content type the pages
+   render: a list is a collection, a one-off (navigation, footer, landing hero) is a singleton.
+   Field names follow the code's own names, so the components don't change.
+3. **Seed the content.** If the user can export from the old service themselves, import that.
+   Otherwise create the entries from what the site shows: the repo's fixtures, sample data and
+   README, and the rendered pages in `get_site_composition`. Real-looking copy and working image
+   URLs, never lorem ipsum. The user edits it in BetterCMS afterwards.
+4. **Rewrite the client module, not the pages.** Keep every function's name and return shape, and
+   replace its body with a read from BetterCMS's Delivery API ([frameworks.md](frameworks.md)
+   shows the client per framework). Reading published content needs no key. The platform already
+   sets these on every build and every running server app, under the prefix the framework
+   exposes:
+
+   | Framework | Variables |
+   |---|---|
+   | Next.js | `NEXT_PUBLIC_BCMS_API_URL`, `NEXT_PUBLIC_BCMS_WORKSPACE`, `NEXT_PUBLIC_BCMS_PROJECT_ID` |
+   | Vite (React, Vue, Svelte) | `VITE_BCMS_*` |
+   | Nuxt | `NUXT_PUBLIC_BCMS_*` |
+   | Astro, SvelteKit | `PUBLIC_BCMS_*` |
+   | Create React App | `REACT_APP_BCMS_*` |
+   | Gatsby | `GATSBY_BCMS_*` |
+   | Server code, any framework | `BCMS_API_URL`, `BCMS_WORKSPACE`, `BCMS_PROJECT_ID` |
+
+   Do not add them to `.env` files. They are supplied, like Sanity's project id.
+5. **Keep actions that need the other service's secret working without it.** Payments, uploads and
+   writes to the old service stay in the code, guarded: when the key is unset, the button explains
+   that the feature is not configured. The page never throws.
+6. **Remove what is no longer read.** Drop the old SDK from `package.json` and its keys from
+   `.env.example` once nothing imports them.
+7. **Prove it.** Build with the old variables unset and open every page. Then continue with the
+   `convert_site` prompt: its bindings now point at BetterCMS content, and the Visual Editor edits it.