@next-buildr/editor 2.0.0 → 3.0.0-rc.0

package/README.md

@@ -0,0 +1,7 @@
+# @next-buildr/editor
+
+Embeddable visual editor for Buildr documents. The editor connects to a Buildr canvas through the versioned canvas protocol.
+
+Install with `npm install @next-buildr/editor @next-buildr/core react react-dom`. Import `@next-buildr/editor/styles.css` in your application. See the [Buildr repository](https://github.com/czekanskyy/buildr) for integration guidance.
+
+Upgrading from 2.0.1: read `UPGRADING.md` in this package, or [docs/upgrading/v2-to-v3.md](https://github.com/czekanskyy/buildr/blob/main/docs/upgrading/v2-to-v3.md) in the repository. Install all seven `@next-buildr/*` packages at one exact version.

package/UPGRADING.md

@@ -0,0 +1,322 @@
+# Upgrading from Buildr 2.0.1 to 3.0.0
+
+This is the canonical upgrade guide. The same text ships as `UPGRADING.md` in every `@next-buildr/*` package, as the MCP prompt `upgrade-to-v3` and as the MCP resource `buildr://upgrade/v3`. Do not edit the copies: edit this file, then run `pnpm gen:upgrade-guide` in the Buildr repository.
+
+It is written as a checklist an AI coding agent can run. Every step is an instruction. Every change has an ID, a class, a detection command and an action. Run the detection commands from the root of your host repository. They use `git grep` and `pnpm`, which behave the same in bash and PowerShell.
+
+The three classes are the only ones used here:
+
+- **BREAKING**: the host must change something, or the editor will not work.
+- **BEHAVIOUR**: the same code now does something different. Check whether your host depends on the old behaviour.
+- **ADDITIVE**: something new. Nothing changes until you use it, but check that it does not clash with a name you already use.
+
+## 1. Before you start
+
+1. Read this whole guide before you change anything.
+2. Record the current state. Run `pnpm list "@next-buildr/*" --depth 0 --recursive` and write down the version of each of the seven packages: `core`, `react`, `components`, `editor`, `next`, `payload`, `mcp`. This is your rollback target.
+3. Run the host's tests, typecheck, lint and production build. This is your baseline. If the baseline is red, stop and fix it first, or you will not know what the upgrade broke.
+4. Make a copy of the database you will use for trials. Never try the upgrade on production data.
+5. Note which optional features the host uses, because some rows below apply only to them: the editor (`BuilderEditor` or `EditorApp`), the Payload plugin, forms, the MCP server, maps, captcha, external media, author code.
+
+## 2. Pin and upgrade
+
+Upgrade all seven packages to one exact version. Never mix versions: the editor and the canvas must come from the same major, and a host that mixes versions sees the protocol mismatch state first (see B1).
+
+1. Set every `@next-buildr/*` dependency in the host to the same exact version, with no `^` and no `~`. Use the version you were told to install, for example `3.0.0` or a release candidate such as `3.0.0-rc.0`.
+2. Run `pnpm install`.
+3. Run `pnpm why @next-buildr/core`. It must show exactly one version. Run the same for the other six packages.
+4. If the host keeps its own constant that names the renderer version (for example one it passes to the canvas), set it to the new version.
+5. Run the typecheck. Fix every error against the change table below.
+6. Go through the change table (section 3). For each row, run the detection command and apply the action. Skip rows that do not apply to your host.
+7. Decide the palette questions in section 4.
+8. Run the verification gates in section 5.
+9. Only then deploy.
+
+## 3. Change table
+
+Each row has an ID, a class, what changed, a detection command and an action.
+
+### B1 · BREAKING · The canvas protocol goes from 1 to 2
+
+- **What changed:** The message protocol between the editor and the canvas is version 2. A peer that speaks version 1 is rejected. The registry manifest hash also differs between 2.x and 3.x for a registry that includes the Buildr library, so a canvas and an editor from different majors fail on the hash as well.
+- **Symptom:** The editor opens, then shows its error card "The canvas and the editor are different versions. Update them together." (protocol), or "The canvas was built with other components than the editor." (manifest). This is the first sign of mixed package versions.
+- **Detect:**
+
+  ```bash
+  pnpm list "@next-buildr/*" --depth 0 --recursive
+  pnpm why @next-buildr/core
+  ```
+
+  Every `@next-buildr/*` line must show the same version. If the canvas is served from a different deployment than the editor, check that deployment too.
+- **Action:** Pin all seven packages to one exact version in every deployment that serves an editor or a canvas. Redeploy the editor and the canvas together.
+
+### H1 · BEHAVIOUR · Hidden nodes can be moved, reordered and duplicated
+
+- **What changed:** `capabilities.insertable: false` on a component used to stop a node being added, moved and copied. It now stops a node being added only. `canMove`, `node.move`, drag and drop, reordering and `node.duplicate` no longer refuse a node because its component is `insertable: false`. Every other placement rule still applies. `canInsert`, `node.insert`, the palette and pasting are unchanged. Hidden is not forbidden: the flag is not an access control. This also means `buildr/gallery-item` and `buildr/carousel-slide` can be moved, for example into a Loop.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'insertable: *false'
+  ```
+
+- **Action:** If you used `insertable: false` to keep a block in place, add `capabilities: { draggable: false }` to that component as well. If you used it only to keep a block out of the palette, change nothing.
+
+### H2 · BEHAVIOUR · Three components move to a new version (identity migrations)
+
+- **What changed:** `buildr/container` goes from version 2 to 3, `buildr/heading` from 1 to 2 and `buildr/text` from 1 to 2. Each migration is an identity migration: the stored props do not change. A document keeps its old versions until it is saved. A document saved by v3 records container 3, heading 2 and text 2. The document schema version does not change.
+- **Detect:** Export your stored layouts to a JSON file (a database dump of the layout column works) and run:
+
+  ```bash
+  grep -oE '"buildr/(container|heading|text)": *[0-9]+' layouts.json | sort | uniq -c
+  ```
+
+  Before the upgrade you expect container 2, heading 1 and text 1. After editors save pages on v3 you also see container 3, heading 2 and text 2.
+- **Action:** Nothing before the upgrade. Read section 6 (Rollback) before editors save pages on v3, because a 2.0.1 editor treats such a page as read only when the plugin has a registry with `migrations`.
+
+### H3 · BEHAVIOUR · `buildr/container` renders its background through a wrapper
+
+- **What changed:** A container background image is now wrapped in `span.bc-container__media`, which carries fit, position, attachment and overlay settings. Some classes moved onto the wrapper. The `img`, its `src`, its size and its empty `alt` are unchanged. The compared HTML is listed in section 7.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'bc-container|backgroundImage'
+  ```
+
+  Look in host CSS, in snapshot tests and in any script that reads a container's children.
+- **Action:** Review host CSS that targets a container's direct children or its background classes. Update HTML snapshots after you read the diff.
+
+### H4 · BEHAVIOUR · Media trust is tighter
+
+- **What changed:** A media object that the renderer did not resolve from the prepared data renders only when its `url` is a same origin path or an https URL (and, for external media, allowed by the host). Anything else, for example a `data:` or `javascript:` URL, renders nothing. Version 2.0.1 rendered such a container background image. A resolved library file is not affected.
+- **Detect:** Look in a layout export for media URLs that are neither a path nor https:
+
+  ```bash
+  grep -oE '"url": *"[^"]*"' layouts.json | grep -vE '"url": *"(/|https://)' | sort | uniq -c
+  ```
+
+- **Action:** Replace each match with a library file or an https URL. If nothing matches, change nothing.
+
+### H5 · BEHAVIOUR · `compileStyles` output can differ
+
+- **What changed:** `compileStyles` changed its whitespace and takes a new path for compound shadow and filter values. It also takes an optional third argument, `{ capabilities }`. In the legacy corpus (561 documents authored for 2.0.1) no compiled CSS differed, so the visible risk is limited to byte for byte comparisons and to documents that use the new shadow, filter, transform and blend controls.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'compileStyles|toMatchSnapshot|toMatchInlineSnapshot' -- '*.ts' '*.tsx' '*.mjs'
+  ```
+
+- **Action:** If a host test compares compiled CSS byte for byte, regenerate the expected output after you read the diff. Do not regenerate it without reading it.
+
+### H6 · BEHAVIOUR · The form enhancer calls function actions itself
+
+- **What changed:** The `buildr/form` element carries `data-buildr-form` (the form node id) and dispatches a bubbling `buildr-form:settled` event after every submission. A function valued form action (for example a server action passed as `formAction`) is now called by the Buildr form enhancer, with `preventDefault()` and inside `startTransition`, instead of by React's native form action handling.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'formAction|buildr-form|data-buildr-form'
+  ```
+
+- **Action:** If you pass a server action as `formAction`, submit a real form on the rc and check that it settles. If you have HTML snapshots of forms, expect the new attribute.
+
+### H7 · BEHAVIOUR · Editor defaults: viewport gate and tablet width
+
+- **What changed:** `config.minViewportWidth` defaults to 320 instead of 1024, so the "use a computer" notice only appears on very narrow windows. The default `tablet` breakpoint in `DEFAULT_BREAKPOINTS` is 768 instead of 820. This changes the editor only. The breakpoints of the published site are unchanged. Below 1100 px the editor panels become sheets.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'minViewportWidth|DEFAULT_BREAKPOINTS|breakpoints'
+  ```
+
+- **Action:** To keep the old gate, pass `minViewportWidth: 1024`. To keep the old tablet width in the editor, pass your own `breakpoints` with `{ id: 'tablet', width: 820 }`.
+
+### H8 · BEHAVIOUR · Locked blocks stay locked unless the host passes `canUnlock`
+
+- **What changed:** The editor has a new optional `canUnlock` prop (on `BuilderEditor` and `EditorApp`). Without it an author can lock a block but cannot unlock it: the layers panel says unlocking is not allowed, and core refuses with `command.unlock-not-permitted`.
+- **Detect:**
+
+  ```bash
+  git grep -nE '<BuilderEditor|<EditorApp|BuilderEditor\(|canUnlock'
+  ```
+
+- **Action:** If editors must be able to unlock blocks, pass `canUnlock` from the host's own permission, for example `canUnlock={() => true}` for a trusted editor. Leave it out to keep locks permanent.
+
+### H9 · BEHAVIOUR · The palette hides `buildr/rich-text` and the `cms` category
+
+- **What changed:** The Blocks tab of the editor no longer lists `buildr/rich-text` or any component in the `cms` category. The blocks stay registered and documents that use them still render and edit. The Blocks tab uses an explicit ordered list of sections: Layout, Content, Media, Forms, then any other category. A host component whose category is `cms` is hidden by this rule.
+- **Detect:**
+
+  ```bash
+  git grep -nE "category: *'cms'|category: *\"cms\""
+  ```
+
+- **Action:** If a host component has the category `cms` and must stay in the palette, give it another category.
+
+### H10 · BEHAVIOUR · Editor details: recent keys, toast time, preview sandbox, DOM and CSS
+
+- **What changed:**
+  - The "Recently used" palette section is gone, and the stored browser keys `buildr.editor.insert.recent` and `buildr.editor.insert.collapsed` are no longer read.
+  - The toast time goes from 6000 to 5000 ms.
+  - The preview iframe drops `allow-same-origin` from its sandbox when the preview URL is on another origin.
+  - The editor user interface was rebuilt. Some `bd-*` CSS class names and parts of the DOM structure changed.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'bd-[a-z]|buildr\.editor\.insert|previewUrl'
+  ```
+
+- **Action:** Update host CSS or end to end selectors that target `bd-*` classes. If a preview page on another origin needs cookies or storage, serve it from the same origin as the editor or make it work inside a sandboxed frame.
+
+### H11 · BEHAVIOUR · The Payload forms endpoint reserves the field name `buildr-captcha`
+
+- **What changed:** A published form that contains an author field named `buildr-captcha` now answers 503, whether or not the form has a captcha block. HTML submissions use the existing invalid redirect.
+- **Detect:**
+
+  ```bash
+  git grep -n 'buildr-captcha'
+  ```
+
+  Also search your stored form definitions for a field with that name.
+- **Action:** Rename any author field called `buildr-captcha`.
+
+### A1 · ADDITIVE · New blocks
+
+- **What changed:** `buildr/spacer`, `buildr/anchor`, `buildr/fieldset`, `buildr/carousel`, `buildr/carousel-slide`, `buildr/gallery`, `buildr/gallery-item`, `buildr/video`, `buildr/iframe`, `buildr/map` and `buildr/captcha`. All start at version 1, so there is no migration. Slides and gallery items are `insertable: false`. The map needs `Platform.maps` and the captcha needs `Platform.captcha`, and both are off without host config.
+- **Detect:** Look for a host component that already uses one of these type names:
+
+  ```bash
+  git grep -nE "buildr/(spacer|anchor|fieldset|carousel|carousel-slide|gallery|gallery-item|video|iframe|map|captcha)"
+  ```
+
+- **Action:** A clash is not expected, because host components use their own prefix. If a host component does use one of these names, rename the host component. To keep a new block out of the palette, see section 4.
+
+### A2 · ADDITIVE · New options on existing blocks
+
+- **What changed:** `buildr/container` gets background video with a poster, an overlay (`overlayTone`, `overlayOpacity`, `backgroundOverlay`), `backgroundFit`, `backgroundPosition`, `backgroundAttachment` and the `typography` style group. `buildr/heading` gets an optional `tag` (`heading` by default, or `p`, `span`, `div`, `strong`). `buildr/text` gets `mode` (`plain` by default, `rich`, `html`), with the props `rich` and `html`. The `html` mode renders only when the host turns author code on. Every component that had the `effects` style group, except the form controls, now also has `motion`.
+- **Detect:**
+
+  ```bash
+  git grep -nE "buildr/(container|heading|text)'"
+  ```
+
+- **Action:** Nothing is required. A stored text without `mode` means plain, a stored heading without `tag` is a heading, and a container without the new props renders as before.
+
+### A3 · ADDITIVE · The `motion` style group
+
+- **What changed:** A typed, CSS only `motion` style group (entrance, hover, scroll reveal and parallax). It compiles to scoped `@keyframes`, transitions and `animation-timeline` behind `@supports`, all inside `prefers-reduced-motion: no-preference`. There is no runtime script. `compileStyles` also returns each node's `NodeRules.motion` and `keyframes`. Core also gains validated custom and text shadows, ordered filters and transforms, blend modes, radial gradients, background repeat and attachment.
+- **Detect:**
+
+  ```bash
+  git grep -nE "'motion'|keyframes"
+  ```
+
+- **Action:** Nothing is required. Check that a host style group or class named `motion` does not clash.
+
+### A4 · ADDITIVE · Trusted author code and `capabilities`
+
+- **What changed:** Trusted author code (ADR-026) is off by default. A node can carry `customCss`, `classes` and `attributes`, and `textarea` props accept `format: 'html'`. It all needs `capabilities.authorCode === true` and fails closed when the field is absent. New optional options: `capabilities` on `renderDocument`, `DocumentRenderer`, `renderTree` and `CanvasRuntime`; the `capabilities` prop of the editor and `config.capabilities`; the `capabilities` option of `createBuildrConfig`; the Payload `authorCode` plugin option (`false`, `true`, or a function that decides per request; it needs the `registry` option). `HostCapabilities` also carries the optional `externalMediaHosts` and `iframeHosts` allowlists (a host and its subdomains; absent means any https host, `[]` means none). New core exports include `HostCapabilities`, `authorCodeEnabled`, `compileCustomCss`, `sanitizeHtml`, `sanitizeHtmlToString`, `authorNodeAttributes` and `checkAuthorCode`.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'authorCode|externalMediaHosts|iframeHosts|customCss'
+  ```
+
+- **Action:** Nothing is required. Do not turn author code on unless editors are trusted. When you do, pass the same `capabilities` to the editor, the canvas and the renderer, so the preview matches the site.
+
+### A5 · ADDITIVE · `TemplateDefinition.insertable`
+
+- **What changed:** A template can be marked `insertable: false`. It then disappears from the editor palette (patterns and search) and from every MCP template path: `list_templates`, the template resources, "did you mean" hints, `describe_template`, `create_document` and `insert_nodes`. It stays registered, and `instantiateTemplate` by id still works for host code. A hidden id is treated like an unknown id. The field has no default, and the manifest hash of a registry that does not set it is unchanged. `registryManifestSchema` accepts the field.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'defineTemplate'
+  ```
+
+- **Action:** To keep an old template registered but out of the palette, add `insertable: false` to its `defineTemplate` input. See section 4 for the root trap.
+
+### A6 · ADDITIVE · Host platform and Payload options
+
+- **What changed:** `Platform.maps` and `Platform.captcha` (react and next), both off by default. Payload gets the `forms.captcha` option (server side Turnstile verification) and `forms.clientIp` (the trusted client address header). The memory rate limiter gets an optional `failClosed` flag (the default is unchanged). `processLayout` gains the `allowAuthorCode` and `previous` options. The editor gets the optional `historyUrl` prop. `@next-buildr/react` exports `markResolvedMedia` and `isResolvedMedia`. `@next-buildr/mcp` exports `isTemplateVisible`, `visibleTemplate` and `visibleTemplates`.
+- **Detect:**
+
+  ```bash
+  git grep -nE 'Platform|forms:|rateLimiter|processLayout|historyUrl'
+  ```
+
+- **Action:** Nothing is required. If the host uses maps or captcha, add the provider hosts to your Content Security Policy (see section 5) and read `docs/security.md` in the Buildr repository.
+
+### A7 · ADDITIVE · New runtime dependency `parse5` in core
+
+- **What changed:** `@next-buildr/core` depends on `parse5`. It is used only by the sanitiser of the Text `html` mode. Nothing else imports it.
+- **Detect:**
+
+  ```bash
+  pnpm why parse5
+  ```
+
+- **Action:** If your policy reviews new dependencies, review `parse5` once. Otherwise change nothing.
+
+### A8 · ADDITIVE · Canvas protocol 2 messages
+
+- **What changed:** The strict, bounded overlay view updates, the block action and insertion intents, ping and pong messages, and the optional `typeLabels` and `scale` fields of `view:set`. The editor stays the only owner of document changes. Core exports `typeLabelsSchema`, `viewLabelsSchema`, `MAX_HIDDEN_NODES`, `MAX_TYPE_LABELS` and `MAX_VIEW_LABEL_LENGTH` from `@next-buildr/core/protocol`.
+- **Detect:**
+
+  ```bash
+  git grep -nE '@next-buildr/core/protocol|postMessage'
+  ```
+
+- **Action:** If the host talks to the canvas protocol directly (it should not), update it to version 2. See B1.
+
+### Nothing else changed
+
+The document schema version is unchanged (`CURRENT_SCHEMA_VERSION` stays 1). There is no Payload field change and no database migration. No package `exports` entry was removed or renamed. A name by name comparison of every public entry point between the `v2.0.1` tag and this release found no removed export.
+
+## 4. Palette decisions for the host
+
+Decide what editors should see in the palette of the new version.
+
+1. **Hide a host block.** Add `capabilities: { insertable: false }` to the component's metadata. Editors can no longer add it. Blocks of that type already on pages keep working, and, since this release, they can be moved, reordered and duplicated. Add `draggable: false` as well if a block must stay where it is.
+2. **Hide a template.** Add `insertable: false` to its `defineTemplate` input. It stays registered, so `instantiateTemplate` by id and existing pages still work.
+3. **The template root trap.** `canInsert` checks `insertable` on the root of an inserted fragment only, not on its descendants. A template whose root component is `insertable: false` cannot be inserted from the palette. Do not hide a template by hiding its root component: set `insertable: false` on the template. A hidden component can still sit inside an inserted template.
+4. **Hidden is not forbidden.** `insertable: false` is not an access control. It keeps a block out of the palette and listings. It does not stop moving or duplicating a block already in a document.
+5. **How the library blocks appear.** The Blocks tab shows the sections Layout, Content, Media and Forms, then any other category. The new blocks are listed there: Spacer and Anchor under Layout, the media blocks (video, iframe, carousel, gallery, map) under Media, and Fieldset and Captcha under Forms. Carousel slides and gallery items are not listed. `buildr/rich-text` and the `cms` category are hidden. A host that wants none of the library blocks marks every one of them `insertable: false` in its own registry. A registry in which every component and every template is hidden opens the editor with an empty palette and no error.
+
+## 5. Verify
+
+Run all of these after the upgrade, in this order. Stop at the first failure and find the cause before you go on.
+
+1. Run the host's tests, typecheck, lint and production build. Compare the result with the baseline from section 1.
+2. Render parity on a database copy. Build the old version and the new version against the same copy of the production data. Render the same pages with both and compare them: at minimum the page height and the HTML of the sections that use the container background (H3) and forms (H6). Equal heights prove layout only, so also check that a form submits and settles, that resolved media renders, and that the compiled CSS keeps its layer order.
+3. Editor smoke test on the database copy: open a page, edit some text, replace an image, publish, and check that the page revalidates. Do this for each kind of page.
+4. Check the protocol state: open the editor and confirm that it reaches the ready state and shows no mismatch card (B1).
+5. Content Security Policy: only if the host uses maps or captcha. A new `frame-src` or `script-src` directive restricts everything it does not list, so merge the provider hosts into your existing directives.
+
+## 6. Rollback
+
+1. Pin all seven packages back to the version you recorded in section 1 and redeploy. The editor and the canvas must roll back together.
+2. A document saved by v3 records container 3, heading 2 and text 2. The 2.0.1 editor marks such a document read only, and the Payload plugin refuses to save it, **only when** the host gave the Payload plugin a registry with `migrations`. A React registry has them. A registry object with `{ meta }` alone does not. Without `migrations` nothing marks the document. Check which case your host has before editors save pages on v3.
+3. The Payload Versions tab does not bring a Buildr layout back. Its Restore button runs the `layout` write guard without the builder flag, so the current layout stays and only the other fields go back.
+4. To bring back a layout from before the upgrade, use one of these: a restore script that reads the old layout from the Payload versions with `payload.findVersionByID` and writes it with `payload.update` (`draft: true`, `data: { layout, buildrRevision: current + 1 }`, `context: { [BUILDR_WRITE]: true }`; `BUILDR_WRITE` is exported by `@next-buildr/payload/plugin`), or restore the database copy you took before the upgrade. Keep Payload versions turned on, because the script reads the old layout from them. A script that has never been run on a database copy is a plan, not a proven way back: run it once before you need it.
+
+## 7. Known differences
+
+Buildr renders documents authored for 2.0.1 with the new build and compares the HTML and the compiled CSS with goldens generated once from the `@next-buildr/core@2.0.1` tag. These are the only differences that are allowed. Each one is listed with the reason it is not visible to a reader of the page. The table is generated from `tooling/smoke/fixtures/legacy-v2/known-differences.json`; do not edit it here.
+
+<!-- known-differences:start -->
+
+| Difference and reason | Cases | Kind | Before (2.0.1, example) | After (3.0.0, example) |
+|---|---|---|---|---|
+| The form element now carries data-buildr-form=&lt;node id&gt;, the hook the client form enhancer uses to find the form. Attributes, action and method are otherwise unchanged. (PB-160) | 76 | html | <code>&lt;form class="bc-form b-n000000001" action="/corpus/submit" method="post"&gt;</code> | <code>&lt;form class="bc-form b-n000000001" data-buildr-form="n000000001" action="/corpus/submit" method="post"&gt;</code> |
+| A container background image is now wrapped in span.bc-container__media, which carries fit, position, attachment and overlay settings; the img itself, its src, size and empty alt are unchanged. | 5 | html | <code>&lt;img class="bc-container__background" src="/media/cat.jpg" alt="" width="1600" height="900"/&gt;</code> | <code>&lt;span class="bc-container__media" aria-hidden="true" data-fit="cover" data-position="center" data-attachment="scroll" data-overlay="none" style="--bc-overlay-opacity:0.5"&gt;&lt;img c...</code> |
+| The container background URL is now checked by the media trust rules: a data: or javascript: URL is no longer rendered, so the img, the preload link and data-has-background are gone. 2.0.1 rendered the data: image and emitted a javascript: URL. | 3 | html | <code>&lt;div class="bc-container b-n000000001" data-display="flex" data-width="lg" data-has-background=""&gt;&lt;img class="bc-container__background" src="data:image/png;base64,iVBORw0KGgo=" ...</code> | <code>&lt;div class="bc-container b-n000000001" data-display="flex" data-width="lg"&gt;</code> |
+
+<!-- known-differences:end -->
+
+## 8. Block for the host's `AGENTS.md`
+
+Copy this block into the `AGENTS.md` of the host repository:
+
+```markdown
+## Buildr upgrades
+
+Before changing any `@next-buildr/*` version, read `node_modules/@next-buildr/core/UPGRADING.md` and run its verification steps. Never mix versions of the seven packages.
+```