@bettercms-ai/mcp 0.83.0 → 0.83.2

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

@@ -1,289 +1,289 @@
----
-title: "Publishing and sync"
-description: "Publish order, delivery lanes, execute and verify, rollback, reconciling a re-import or continuous sync, and the automation surfaces that exist."
----
-
-# Publishing, release, rollback and sync reconciliation
-
-**Outcome.** The intended revision reaches the right public site with its dependencies, routes,
-forms and cache state checked, and a new source revision lands without overwriting editorial
-work. A dashboard success is not evidence that a public route works.
-
-Order of operations and why a draft renders nothing: §7 of `bettercms://playbook/schema`.
-Component refusal codes: [components.md](components.md) §4. Hosting modes, the SSR switch, env
-names and revalidation: [frameworks.md](frameworks.md).
-
-## 1. Plan the dependency graph
-
-Confirm the project and its hosting mode from `get_project`, never from the repo name (`hybrid`
-is handled exactly like `managed`). Record the source commit, content revision, live baseline,
-release target and rollback point.
-
-Publish in dependency order: component definitions (and nested components), Form documents, the
-global navigation and footer, the Global Layout, pages and entries, SEO, then the frontend code
-that reads them.
-
-- **Chrome**: components first, then `publish_layout`; the order and the logo refusals are in
-  [components.md](components.md) §4.
-- **Forms**: test the destination and consent behaviour, then `publish_form`; a draft form answers
-  403 to every public submission.
-- **Pages and entries are two rows.** Publishing a singleton page publishes its entry too, as the
-  dashboard's publish button does, unless the entry's own gate refuses it (its workflow stage, or
-  the publish permission). `ENTRY_STILL_DRAFT` means the page went live over content that did
-  not, and names the entry and why; `ENTRY_SEED_FAILED` on `create_page` means none of its seed
-  data was saved.
-- Publishing copies the stored draft to live, so what you checked in the draft is what ships.
-- **Many at once**: `publish_entries` { action: 'publish' | 'unpublish', entryIds, pageIds } takes
-  up to 100 of each in one call (pages publish only). Each item still passes its own gates, and
-  nothing stops the run: read `failed` for every refusal and its reason, then `outcome` for what
-  the served pages show (the same shape `update_page` returns on a publish, below).
-- **Throw away a draft**: `discard_draft` with `entryId` or `pageId` returns it to exactly what is
-  live; a page also drops its unpublished Layout overrides (`no_published_version` if it never
-  went live: delete it instead).
-- **Edit a page safely**: read `get_page` and send its `optimisticVersion` as `ifMatch` on
-  `update_page`; a 409 means someone changed it since, so read again. `blockJson` replaces the
-  whole composition, so an unguarded write can erase a concurrent edit.
-
-## 2. Choose the delivery lane
-
-| 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 (`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)).
-
-### What a publish builds
-
-On a site BetterCMS hosts, a publish applies in place with no build: values, Layout values, SEO of a
-page with HTML on disk, and a reorder or removal of sections the build draws from the CMS (every band
-stamped `data-bcms-block`, measured in CMS order). Only what needs new markup builds, by itself: a
-new or removed page, a new section or one whose component changed, a Layout structure change, SEO
-of a page with no HTML on disk, and a list whose published row count the page cannot take (it
-renders rows no address names, or was built empty). That publish waits for its build ("Rebuilding so
-the list shows N rows") and fails with the reason if the build still shows the page's own rows: the
-site's code renders the list itself. `get_next_steps` names what is waiting.
-
-A static page whose own code fixes its sections takes all of it in place too, when the project's
-in-place structure switch is on: the publish writes the page's block list into the built HTML.
-The code's bands stand in the published order, a removed one is cut, a section added in
-BetterCMS is drawn between them, and every root takes its block's style. No repository change
-and no build; each rebuild is put right the same way. The gate's `sections` row says which
-routes take it (`accepts: "in-place"`).
-
-A collection's item pages take it per TEMPLATE: the collection page's sections are the
-template's, held once, so a section added to that page (`update_page` on the collection page)
-stands on every entry's route, and an entry has no sections of its own. Its publish reads one
-row for all of them (`route` `blog/*`). The entry's body is a section too: add sections around
-it or move it, and space it through its field's style, since its element is the field's.
-
-The SEO a page or entry stores is what its `<head>` says, whenever it was set: the title, the
-description, the canonical, the card fields, a `noindex` that is on. A field left empty keeps what
-the build rendered, and a site default only fills a tag the build has none of. Only a real choice
-replaces what the build renders: a meta title that merely repeats the page's name (whatever its
-case), a description that repeats the title or is the entry's auto-filled first paragraph, and
-anything on a row no person or agent has ever written (`origin` `system:*`) are read as not set. To
-change such a head, set the title or description yourself. On a route the site's app renders, no write
-reaches the head: a publish whose SEO the page does not show fails with "Published, but this page's
-code doesn't read this field yet: SEO title", and the fix is to render the head from the published
-values.
-
-Builds run `build:bcms` instead of `build` when `package.json` declares it. Keep CI-only checks out
-of it and every step the build needs in: `"build": "astro check && astro build"` beside
-`"build:bcms": "astro build"`. The convert codemod adds one to a repo whose build chains a check.
-
-### Add a section, or set its spacing
-
-One call each, on any page (a page BetterCMS draws, a code-built one, a collection template):
-
-- **Add a section here**: `update_page { pageId, blockJson: { insertSection: { componentId, after: "<block id>" } } }`.
-  `componentId` is a component from `list_components`; a `builtin:*` id is copied into the project
-  once and the copy is placed. Place it with `at` (an index into the page's sections), `before`
-  or `after` (a section's block id from `get_page`); none of the three adds it last. `style` and
-  `overrides` set its block style and its copy in the same call.
-- **Set spacing on this section**: `update_page { pageId, blockJson: { sectionStyle: { blockId, style } } }`.
-  Each key of `style` replaces the stored one and `null` unsets it: `paddingTop`, `paddingBottom`,
-  `paddingSides` (px, 0 to 240), `spaceTop`, `spaceBottom`, `spaceSides` (the spacing tokens),
-  `bg`, `bgCustom`, `contentWidth`, `contentAlign`, `theme`, `corner`, `shadow`, `border`,
-  `opacity`, `hideOn`. A key the block style does not have is refused (`INVALID_STYLE`).
-
-The server edits the page as stored, so nothing else on it is resent or overwritten; send
-`ifMatch` to refuse a page that changed since you read it. Both save a DRAFT: add
-`status: "published"` to the same call, or publish after. Then read the answer, top down:
-
-1. `held`: the draft is saved and the live page will NOT show it. It names the reason and the one
-   action (below). Do the action; do not report the change as made.
-2. `outcome` (on a publish): `status` `live` is every value found on the served page. `partial`
-   lists what is not in `notLive`, each with its `reason` and `action` (the table under Reading
-   `get_deploy_status`). `next: "get_deploy_status"` means it is not judged whole: nothing has
-   looked at it yet, or a section change is still being written (`NOT_CHECKED`). It resolves by
-   itself to live or held: poll `publishes` there before you say anything is live.
-3. `section`: the block's `id` and `index`, to place the next one beside it.
-4. `warnings`: `COMPONENT_DRAFT` is a section that renders nothing until `publish_component`.
-
-Refusals: `SECTION_NOT_FOUND` (the answer lists the page's section ids), `POSITION_OUT_OF_RANGE`,
-`COMPONENT_NOT_FOUND`, `BUILTIN_NOT_FOUND`. A whole `blockJson` array still replaces the page's
-sections; use it to move or remove one, with `ifMatch`.
-
-### A section change that is held at the write
-
-`update_page` and `compose_pages` save the draft and answer `held` first (with `holds`) when a
-write adds, moves or removes a section the live page cannot show yet. Each hold has a `reason`,
-a `message`, the `sections` it is about and the one `action`. Never report such a write as done:
-
-- `CODE_FIXED_SECTIONS`: the site's code fixes this page's sections, so no publish ships the
-  change. Read the route's `sections` row in `get_next_steps` (`receipt.gate`): its `fixCode`
-  names the lane ([finish-site.md](finish-site.md)). `enable-in-place-structure` is the user's
-  switch and needs no code. `run-sections-conversion` is the wrap: `componentize_sections` with
-  `codemod: true` and the `digest` of `get_componentize_plan`, or, when that answers `skipped`
-  (no repository the platform may commit to), `npx @bettercms-ai/convert@latest --sections --root .`
-  in a checkout ([componentize.md](componentize.md) §5). After its build, publish.
-- `SECTION_NEEDS_BUILD`: the build draws the page's sections from BetterCMS. Publish: the build
-  starts by itself, and a move or a removal needs none.
-- `STRUCTURE_UNMEASURED`: nothing has measured the page. Publish, then read the publish's outcome
-  in `get_deploy_status`.
-
-### Reading `get_deploy_status`
-
-- `release` is the newest release: `id`, `sha`, `status`, `phaseMarks`, `error`, `createdAt`.
-  While an uploaded build is ingested or released the state is `building`, `release.sha` is the
-  new sha and `lastLiveSha` the old one. Sending the live sha again does nothing. A failed deploy
-  has `release.status` `failed` and its `error`.
-- `held` means the release waits until the hold is cleared; `held.by` is `staff`, `archived` or
-  `no-subdomain`.
-- `slot` is where the bytes are: `current` is production, `staging` the staging handle.
-  `productionSha` is what production serves. `awaitingPromote: true` is a build that is verified
-  and ready on staging while production keeps the older sha, until `promote_project` runs.
-- The poll is finished only when `slot` is `current`, or when `awaitingPromote` is false and
-  `productionSha` equals the sha you deployed.
-- `publishes` is the newest publishes, value by value. `status` `live` means every published value
-  was found in the file the site serves that page from. `partial` means some were not: `summary`
-  counts them ("3 of 4 live · 1 held") and `notLive` lists each with its `route`, `address`,
-  `state`, `reason` and the one `action` that fixes it. Never tell the user a publish is live
-  while it reads `partial`: relay the reason and do the action, then poll again.
-
-| `reason` | `state` | The one action |
-|---|---|---|
-| `NOT_STAMPED` | held | Rebuild: the built page has no element for the field and does not show it |
-| `VALUE_REFUSED` | held | Bind the field to an element that can hold its value |
-| `APP_DOES_NOT_READ` | held | Convert in code: make the page's code read the published field |
-| `ROWS_NEED_BUILD`, `SECTION_NEEDS_BUILD`, `NEEDS_BUILD` | held | Wait for the build the publish started |
-| `STRUCTURE_UNBOUND` | refused | The fix the route's `sections` gate row names: the in-place switch, or the sections conversion |
-| `SECTION_MISSING` | held | The same: the served page does not render the section |
-| `SECTION_NOT_ON_PAGE` | held | In place: a section of the site's own code has no band on this page. The sections conversion, or remove the placement |
-| `SECTION_NOT_RENDERABLE` | held | In place: the added section's component is not published, or it needs a form. `publish_component`, then publish the page again |
-| `STYLE_NOT_PAINTABLE` | held | Rebuild once the section root carries the style marker (`sectionRootAttrs`, or the codemod's `--upgrade-sections`: [components.md](components.md)) |
-| `WINDOW_NOT_OPEN` | held | Nothing: it goes live when its window opens |
-| `ROUTE_NOT_OWNED` | held | Change one of the two page paths that share the URL |
-| `APP_UNREACHABLE`, `NOT_CHECKED`, `EDGE_PENDING`, `IMAGE_UNAVAILABLE`, `STRUCTURE_UNMEASURED` | unverified | Poll again; publish again if it stays |
-
-Each row's `action.code` is one of these, and `get_next_steps` lists every held or refused value
-as `publish-held` until it is gone:
-
-| `action.code` | What you do |
-|---|---|
-| `rebuild` | No tool rebuilds: change the site's code if the reason names it, then ask the user to Rebuild from Publishing (or `deploy_project` from a checkout) |
-| `wait_for_build` | Poll `get_deploy_status` until the build the publish started is live |
-| `convert_in_code` | Make the page's code read the field ([bindings.md](bindings.md)), then release |
-| `control_section_order` | The route's `sections` gate row names it: the in-place switch (the user's), or `componentize_sections` with `codemod: true` (else `convert --sections` in a checkout), then release |
-| `editor_setup` | `editor_setup` |
-| `rebind` | Bind the field to an element that can hold it, in the site's code |
-| `resolve_route` | Change one of the two page paths |
-| `wait`, `retry` | Poll again; publish again if it stays |
-
-### Deploy to Vercel or Netlify
-
-To serve a `managed` or `hybrid` site from the owner's own Vercel or Netlify account, call
-`list_hosting_connections` first; with no working connection for that host, hand the user
-`connectUrl` to connect it in the browser and wait. Then `deploy_to_host` with the `provider`:
-BetterCMS builds, the host serves, and calling it again redeploys the same site. Relay any
-refusal's `fixUrl` to the user. Poll `get_host_deploy_status` until the newest deployment is live
-and verify its `providerUrl`. Forms post to the BetterCMS API, so they need no rewrite, and no host
-CLI or pasted host token is ever needed while a connection exists.
-
-## 3. Execute and verify
-
-1. After an authorized release, record the operation ids and revisions from each call.
-2. On a refusal, stop: resolve the cause its code names, then retry only with changed input.
-3. Fetch each touched route directly, cache-busted: status, the copy you published, component
-   overrides, media URLs, metadata and forms. Include one collection detail route, the global
-   navigation and footer, and mobile interaction when affected.
-4. Run the verify loop in SKILL.md, noting each report's freshness.
-5. On a cached site, confirm the publish webhook or rebuild actually refreshed the public page.
-
-## 4. Roll back
-
-Use the known prior content revision and source commit. For an entry, `list_entry_versions` then
-`restore_entry_version`: it writes that version back as the current draft and adds a new version,
-so publish it afterwards. Unpublished edits you do not want are `discard_draft`, not a restore.
-Restore only the affected lane, recheck the live URLs, and never overwrite newer unrelated edits.
-
-## 4b. Stage a change on a branch
-
-A content branch is a copy of the project's content to edit without touching the live site.
-`create_branch` { name } returns it; pass its id as `branchId` on every call made inside it
-(`list_branches` names the one you are on). To merge, `apply_branch` { branchId, dryRun: true }
-returns the diff and its conflicts: show it to the user, then apply, with `include` to take only
-some changes and `fields` to settle each conflicting field (`keep_branch` / `keep_parent`).
-
-## 5. Reconcile a re-import, a push or a continuous sync
-
-Identify the previous source snapshot or commit, the new one, the import manifest, the
-source-to-target id map and the current BetterCMS state. `list_activity` with `since` reads the
-project's durable change feed from an ISO timestamp (up to 100 events per call): call it with the
-time of the previous sync to see every dashboard or agent edit made since. Compare by stable identity, never
-by display name or row order, and confirm it is the same project and source branch. Entries
-written with `externalKey` (the source id) are their own id map: `list_content_entries` with
-`externalKey` finds one, and re-sending the row answers `created`, `updated` or `unchanged`
-([write-limits.md](write-limits.md)). Media, and references to items not yet created, still
-need the map. Without a manifest, keys or an id map this is no longer an automatic sync; treat
-it as a reviewed migration (the `bettercms-migrate` skill).
-
-Classify each difference and keep a three-way view where you can (the value last imported, the
-current source value, the current CMS value). Never flatten a person's CMS edit back to imported
-code because the file was touched.
-
-| Difference | Resolution |
-|---|---|
-| New in source | Import with the normal model and component rules; file into the existing Content sidebar folders |
-| Changed only in source | Update fields that are still code-owned or explicitly synced; CMS-owned values stay |
-| Changed only in CMS | Keep |
-| Changed on both sides | Report both values with provenance; apply a winner only after the user chooses |
-| Missing in source | An orphan, never an automatic delete. Tell removed from moved or renamed; offer archive / keep / relink with the inbound references, routes and redirects each affects |
-| Route or slug change | A URL and redirect plan (`create_redirect`); check collisions, canonicals and internal links first |
-| Assets | Match by source id or path plus checksum; a changed binary is a new revision; a missing source asset never breaks a published reference until the user approves its replacement or removal |
-
-Dry-run the proposed operations, then run the same snapshot again to prove it is idempotent (no
-new changes the second time). Apply only approved, supported changes, then compare counts,
-references, component usage, field bindings, preview and the affected public routes. The rollback
-for a content value the sync got wrong is §4.
-
-## 6. Automation surfaces
-
-"Run X when content changes" maps onto what exists; there is no user-deployed function runtime.
-
-| Need | Surface | Owner |
-|---|---|---|
-| Rebuild or revalidate a site on publish | The publish webhook, signed `X-BetterCMS-Signature` (HMAC-SHA256 of the raw body) with the project's webhook secret ([frameworks.md](frameworks.md) Revalidation) | Secret set in the dashboard; your route verifies it |
-| Notify another system of an event | Event webhooks, `list_webhooks` / `create_webhook`: `content.publish`, `content.unpublish`, `content.stage_changed` (workflow stage), `content.created`, `content.updated`, `content.deleted` and `deployment.triggered`; HMAC-SHA256 signed in `X-BetterCMS-Signature`; payloads carry ids, never content: an entry's `content.publish`/`content.unpublish` carries `data.entryId`, a page's carries `data.pageId` and `kind: "page"` (so `entryId` is not always present). The signing `secret` is returned ONCE, on create. A receiver that writes back on `content.updated` loops unless it skips its own writes. Per-subscription payload filters: dashboard | You |
-| Send form submissions somewhere | Per-form integrations: Google Sheets, Slack, a webhook, email | Dashboard only |
-| Go live or retire at a time | `scheduledAt` (publish a draft at a time; needs publish permission) and `unpublishAt` (return a published row to draft) on `update_content_entry` and `update_page`; `null` cancels either. Campaigns: `publish_campaign` takes both | You. An edit that omits `scheduledAt` CANCELS the pending publish, so resend it with every edit before it fires; omitting `unpublishAt` never cancels it |
-| Show one section only for a period | `window` `{ from?, until? }` on a page block (`update_page` `blockJson`) or on a Layout Section (`update_layout` `add-section`, `update-section`). Shown from `from` until `until`; each is an ISO 8601 datetime with an offset (`2026-11-27T00:00:00+01:00`), stored as UTC, and either may be left out. `null` clears it. Refusals: `invalid_window` (no offset, or not a date), `window_inverted` (`from` not before `until`), `window_in_component` (inside a component's `blockJson`: put it on the placement), `window_in_entry` (on a block inside an entry's sections value: put it on the page block or Layout Section that shows the entry). A Section a page adds or customizes takes a window like a Global one | You. Outside its window the block is in no published output: the page, its Markdown, the delivery API and search. A draft preview draws it, marked. A page BetterCMS renders per request changes at the boundary; a static site catches up within about a minute, in place when a section goes and with a build when one appears. Site code that renders its own header ignores a Section's window |
-| Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed` (with `externalKey` also `updated` or `unchanged`, so a re-run is safe); then `publish_entries` | You |
-| React to edits made elsewhere | Poll `list_activity` with `since` set to the time of your last read (1–100 events per call) | You |
-| Generate or rewrite in bulk with a human gate | AI jobs: `list_ai_jobs`, `get_ai_job`, then `approve_ai_job` or `reject_ai_job` on the user's word | User approves |
-
-Not available, so say so instead of building around it: code that runs inside BetterCMS on a
-content event, and a change subscription over the MCP (poll `list_activity` `since`). Anything
-beyond the table runs in the user's own infrastructure, triggered by a webhook. Why: a timer on the
-delivery API looks like a trigger, but it serves published content only and never sees an edit
-before it ships.
-
-## Report
-
-State what is live, what remains draft, whether a rollback ran, and any owner action still
-required (Visual Approval, a render-mode change, a secret). For a sync, list exact created,
-updated, unchanged, orphaned and conflicted ids, the choices still open, and the rollback point;
-an open conflict is never a successful sync. Do not say "launched" until the public response is
-verified.
+---
+title: "Publishing and sync"
+description: "Publish order, delivery lanes, execute and verify, rollback, reconciling a re-import or continuous sync, and the automation surfaces that exist."
+---
+
+# Publishing, release, rollback and sync reconciliation
+
+**Outcome.** The intended revision reaches the right public site with its dependencies, routes,
+forms and cache state checked, and a new source revision lands without overwriting editorial
+work. A dashboard success is not evidence that a public route works.
+
+Order of operations and why a draft renders nothing: §7 of `bettercms://playbook/schema`.
+Component refusal codes: [components.md](components.md) §4. Hosting modes, the SSR switch, env
+names and revalidation: [frameworks.md](frameworks.md).
+
+## 1. Plan the dependency graph
+
+Confirm the project and its hosting mode from `get_project`, never from the repo name (`hybrid`
+is handled exactly like `managed`). Record the source commit, content revision, live baseline,
+release target and rollback point.
+
+Publish in dependency order: component definitions (and nested components), Form documents, the
+global navigation and footer, the Global Layout, pages and entries, SEO, then the frontend code
+that reads them.
+
+- **Chrome**: components first, then `publish_layout`; the order and the logo refusals are in
+  [components.md](components.md) §4.
+- **Forms**: test the destination and consent behaviour, then `publish_form`; a draft form answers
+  403 to every public submission.
+- **Pages and entries are two rows.** Publishing a singleton page publishes its entry too, as the
+  dashboard's publish button does, unless the entry's own gate refuses it (its workflow stage, or
+  the publish permission). `ENTRY_STILL_DRAFT` means the page went live over content that did
+  not, and names the entry and why; `ENTRY_SEED_FAILED` on `create_page` means none of its seed
+  data was saved.
+- Publishing copies the stored draft to live, so what you checked in the draft is what ships.
+- **Many at once**: `publish_entries` { action: 'publish' | 'unpublish', entryIds, pageIds } takes
+  up to 100 of each in one call (pages publish only). Each item still passes its own gates, and
+  nothing stops the run: read `failed` for every refusal and its reason, then `outcome` for what
+  the served pages show (the same shape `update_page` returns on a publish, below).
+- **Throw away a draft**: `discard_draft` with `entryId` or `pageId` returns it to exactly what is
+  live; a page also drops its unpublished Layout overrides (`no_published_version` if it never
+  went live: delete it instead).
+- **Edit a page safely**: read `get_page` and send its `optimisticVersion` as `ifMatch` on
+  `update_page`; a 409 means someone changed it since, so read again. `blockJson` replaces the
+  whole composition, so an unguarded write can erase a concurrent edit.
+
+## 2. Choose the delivery lane
+
+| 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 (`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)).
+
+### What a publish builds
+
+On a site BetterCMS hosts, a publish applies in place with no build: values, Layout values, SEO of a
+page with HTML on disk, and a reorder or removal of sections the build draws from the CMS (every band
+stamped `data-bcms-block`, measured in CMS order). Only what needs new markup builds, by itself: a
+new or removed page, a new section or one whose component changed, a Layout structure change, SEO
+of a page with no HTML on disk, and a list whose published row count the page cannot take (it
+renders rows no address names, or was built empty). That publish waits for its build ("Rebuilding so
+the list shows N rows") and fails with the reason if the build still shows the page's own rows: the
+site's code renders the list itself. `get_next_steps` names what is waiting.
+
+A static page whose own code fixes its sections takes all of it in place too, when the project's
+in-place structure switch is on: the publish writes the page's block list into the built HTML.
+The code's bands stand in the published order, a removed one is cut, a section added in
+BetterCMS is drawn between them, and every root takes its block's style. No repository change
+and no build; each rebuild is put right the same way. The gate's `sections` row says which
+routes take it (`accepts: "in-place"`).
+
+A collection's item pages take it per TEMPLATE: the collection page's sections are the
+template's, held once, so a section added to that page (`update_page` on the collection page)
+stands on every entry's route, and an entry has no sections of its own. Its publish reads one
+row for all of them (`route` `blog/*`). The entry's body is a section too: add sections around
+it or move it, and space it through its field's style, since its element is the field's.
+
+The SEO a page or entry stores is what its `<head>` says, whenever it was set: the title, the
+description, the canonical, the card fields, a `noindex` that is on. A field left empty keeps what
+the build rendered, and a site default only fills a tag the build has none of. Only a real choice
+replaces what the build renders: a meta title that merely repeats the page's name (whatever its
+case), a description that repeats the title or is the entry's auto-filled first paragraph, and
+anything on a row no person or agent has ever written (`origin` `system:*`) are read as not set. To
+change such a head, set the title or description yourself. On a route the site's app renders, no write
+reaches the head: a publish whose SEO the page does not show fails with "Published, but this page's
+code doesn't read this field yet: SEO title", and the fix is to render the head from the published
+values.
+
+Builds run `build:bcms` instead of `build` when `package.json` declares it. Keep CI-only checks out
+of it and every step the build needs in: `"build": "astro check && astro build"` beside
+`"build:bcms": "astro build"`. The convert codemod adds one to a repo whose build chains a check.
+
+### Add a section, or set its spacing
+
+One call each, on any page (a page BetterCMS draws, a code-built one, a collection template):
+
+- **Add a section here**: `update_page { pageId, blockJson: { insertSection: { componentId, after: "<block id>" } } }`.
+  `componentId` is a component from `list_components`; a `builtin:*` id is copied into the project
+  once and the copy is placed. Place it with `at` (an index into the page's sections), `before`
+  or `after` (a section's block id from `get_page`); none of the three adds it last. `style` and
+  `overrides` set its block style and its copy in the same call.
+- **Set spacing on this section**: `update_page { pageId, blockJson: { sectionStyle: { blockId, style } } }`.
+  Each key of `style` replaces the stored one and `null` unsets it: `paddingTop`, `paddingBottom`,
+  `paddingSides` (px, 0 to 240), `spaceTop`, `spaceBottom`, `spaceSides` (the spacing tokens),
+  `bg`, `bgCustom`, `contentWidth`, `contentAlign`, `theme`, `corner`, `shadow`, `border`,
+  `opacity`, `hideOn`. A key the block style does not have is refused (`INVALID_STYLE`).
+
+The server edits the page as stored, so nothing else on it is resent or overwritten; send
+`ifMatch` to refuse a page that changed since you read it. Both save a DRAFT: add
+`status: "published"` to the same call, or publish after. Then read the answer, top down:
+
+1. `held`: the draft is saved and the live page will NOT show it. It names the reason and the one
+   action (below). Do the action; do not report the change as made.
+2. `outcome` (on a publish): `status` `live` is every value found on the served page. `partial`
+   lists what is not in `notLive`, each with its `reason` and `action` (the table under Reading
+   `get_deploy_status`). `next: "get_deploy_status"` means it is not judged whole: nothing has
+   looked at it yet, or a section change is still being written (`NOT_CHECKED`). It resolves by
+   itself to live or held: poll `publishes` there before you say anything is live.
+3. `section`: the block's `id` and `index`, to place the next one beside it.
+4. `warnings`: `COMPONENT_DRAFT` is a section that renders nothing until `publish_component`.
+
+Refusals: `SECTION_NOT_FOUND` (the answer lists the page's section ids), `POSITION_OUT_OF_RANGE`,
+`COMPONENT_NOT_FOUND`, `BUILTIN_NOT_FOUND`. A whole `blockJson` array still replaces the page's
+sections; use it to move or remove one, with `ifMatch`.
+
+### A section change that is held at the write
+
+`update_page` and `compose_pages` save the draft and answer `held` first (with `holds`) when a
+write adds, moves or removes a section the live page cannot show yet. Each hold has a `reason`,
+a `message`, the `sections` it is about and the one `action`. Never report such a write as done:
+
+- `CODE_FIXED_SECTIONS`: the site's code fixes this page's sections, so no publish ships the
+  change. Read the route's `sections` row in `get_next_steps` (`receipt.gate`): its `fixCode`
+  names the lane ([finish-site.md](finish-site.md)). `enable-in-place-structure` is the user's
+  switch and needs no code. `run-sections-conversion` is the wrap: `componentize_sections` with
+  `codemod: true` and the `digest` of `get_componentize_plan`, or, when that answers `skipped`
+  (no repository the platform may commit to), `npx @bettercms-ai/convert@latest --sections --root .`
+  in a checkout ([componentize.md](componentize.md) §5). After its build, publish.
+- `SECTION_NEEDS_BUILD`: the build draws the page's sections from BetterCMS. Publish: the build
+  starts by itself, and a move or a removal needs none.
+- `STRUCTURE_UNMEASURED`: nothing has measured the page. Publish, then read the publish's outcome
+  in `get_deploy_status`.
+
+### Reading `get_deploy_status`
+
+- `release` is the newest release: `id`, `sha`, `status`, `phaseMarks`, `error`, `createdAt`.
+  While an uploaded build is ingested or released the state is `building`, `release.sha` is the
+  new sha and `lastLiveSha` the old one. Sending the live sha again does nothing. A failed deploy
+  has `release.status` `failed` and its `error`.
+- `held` means the release waits until the hold is cleared; `held.by` is `staff`, `archived` or
+  `no-subdomain`.
+- `slot` is where the bytes are: `current` is production, `staging` the staging handle.
+  `productionSha` is what production serves. `awaitingPromote: true` is a build that is verified
+  and ready on staging while production keeps the older sha, until `promote_project` runs.
+- The poll is finished only when `slot` is `current`, or when `awaitingPromote` is false and
+  `productionSha` equals the sha you deployed.
+- `publishes` is the newest publishes, value by value. `status` `live` means every published value
+  was found in the file the site serves that page from. `partial` means some were not: `summary`
+  counts them ("3 of 4 live · 1 held") and `notLive` lists each with its `route`, `address`,
+  `state`, `reason` and the one `action` that fixes it. Never tell the user a publish is live
+  while it reads `partial`: relay the reason and do the action, then poll again.
+
+| `reason` | `state` | The one action |
+|---|---|---|
+| `NOT_STAMPED` | held | Rebuild: the built page has no element for the field and does not show it |
+| `VALUE_REFUSED` | held | Bind the field to an element that can hold its value |
+| `APP_DOES_NOT_READ` | held | Convert in code: make the page's code read the published field |
+| `ROWS_NEED_BUILD`, `SECTION_NEEDS_BUILD`, `NEEDS_BUILD` | held | Wait for the build the publish started |
+| `STRUCTURE_UNBOUND` | refused | The fix the route's `sections` gate row names: the in-place switch, or the sections conversion |
+| `SECTION_MISSING` | held | The same: the served page does not render the section |
+| `SECTION_NOT_ON_PAGE` | held | In place: a section of the site's own code has no band on this page. The sections conversion, or remove the placement |
+| `SECTION_NOT_RENDERABLE` | held | In place: the added section's component is not published, or it needs a form. `publish_component`, then publish the page again |
+| `STYLE_NOT_PAINTABLE` | held | Rebuild once the section root carries the style marker (`sectionRootAttrs`, or the codemod's `--upgrade-sections`: [components.md](components.md)) |
+| `WINDOW_NOT_OPEN` | held | Nothing: it goes live when its window opens |
+| `ROUTE_NOT_OWNED` | held | Change one of the two page paths that share the URL |
+| `APP_UNREACHABLE`, `NOT_CHECKED`, `EDGE_PENDING`, `IMAGE_UNAVAILABLE`, `STRUCTURE_UNMEASURED` | unverified | Poll again; publish again if it stays |
+
+Each row's `action.code` is one of these, and `get_next_steps` lists every held or refused value
+as `publish-held` until it is gone:
+
+| `action.code` | What you do |
+|---|---|
+| `rebuild` | No tool rebuilds: change the site's code if the reason names it, then ask the user to Rebuild from Publishing (or `deploy_project` from a checkout) |
+| `wait_for_build` | Poll `get_deploy_status` until the build the publish started is live |
+| `convert_in_code` | Make the page's code read the field ([bindings.md](bindings.md)), then release |
+| `control_section_order` | The route's `sections` gate row names it: the in-place switch (the user's), or `componentize_sections` with `codemod: true` (else `convert --sections` in a checkout), then release |
+| `editor_setup` | `editor_setup` |
+| `rebind` | Bind the field to an element that can hold it, in the site's code |
+| `resolve_route` | Change one of the two page paths |
+| `wait`, `retry` | Poll again; publish again if it stays |
+
+### Deploy to Vercel or Netlify
+
+To serve a `managed` or `hybrid` site from the owner's own Vercel or Netlify account, call
+`list_hosting_connections` first; with no working connection for that host, hand the user
+`connectUrl` to connect it in the browser and wait. Then `deploy_to_host` with the `provider`:
+BetterCMS builds, the host serves, and calling it again redeploys the same site. Relay any
+refusal's `fixUrl` to the user. Poll `get_host_deploy_status` until the newest deployment is live
+and verify its `providerUrl`. Forms post to the BetterCMS API, so they need no rewrite, and no host
+CLI or pasted host token is ever needed while a connection exists.
+
+## 3. Execute and verify
+
+1. After an authorized release, record the operation ids and revisions from each call.
+2. On a refusal, stop: resolve the cause its code names, then retry only with changed input.
+3. Fetch each touched route directly, cache-busted: status, the copy you published, component
+   overrides, media URLs, metadata and forms. Include one collection detail route, the global
+   navigation and footer, and mobile interaction when affected.
+4. Run the verify loop in SKILL.md, noting each report's freshness.
+5. On a cached site, confirm the publish webhook or rebuild actually refreshed the public page.
+
+## 4. Roll back
+
+Use the known prior content revision and source commit. For an entry, `list_entry_versions` then
+`restore_entry_version`: it writes that version back as the current draft and adds a new version,
+so publish it afterwards. Unpublished edits you do not want are `discard_draft`, not a restore.
+Restore only the affected lane, recheck the live URLs, and never overwrite newer unrelated edits.
+
+## 4b. Stage a change on a branch
+
+A content branch is a copy of the project's content to edit without touching the live site.
+`create_branch` { name } returns it; pass its id as `branchId` on every call made inside it
+(`list_branches` names the one you are on). To merge, `apply_branch` { branchId, dryRun: true }
+returns the diff and its conflicts: show it to the user, then apply, with `include` to take only
+some changes and `fields` to settle each conflicting field (`keep_branch` / `keep_parent`).
+
+## 5. Reconcile a re-import, a push or a continuous sync
+
+Identify the previous source snapshot or commit, the new one, the import manifest, the
+source-to-target id map and the current BetterCMS state. `list_activity` with `since` reads the
+project's durable change feed from an ISO timestamp (up to 100 events per call): call it with the
+time of the previous sync to see every dashboard or agent edit made since. Compare by stable identity, never
+by display name or row order, and confirm it is the same project and source branch. Entries
+written with `externalKey` (the source id) are their own id map: `list_content_entries` with
+`externalKey` finds one, and re-sending the row answers `created`, `updated` or `unchanged`
+([write-limits.md](write-limits.md)). Media, and references to items not yet created, still
+need the map. Without a manifest, keys or an id map this is no longer an automatic sync; treat
+it as a reviewed migration (the `bettercms-migrate` skill).
+
+Classify each difference and keep a three-way view where you can (the value last imported, the
+current source value, the current CMS value). Never flatten a person's CMS edit back to imported
+code because the file was touched.
+
+| Difference | Resolution |
+|---|---|
+| New in source | Import with the normal model and component rules; file into the existing Content sidebar folders |
+| Changed only in source | Update fields that are still code-owned or explicitly synced; CMS-owned values stay |
+| Changed only in CMS | Keep |
+| Changed on both sides | Report both values with provenance; apply a winner only after the user chooses |
+| Missing in source | An orphan, never an automatic delete. Tell removed from moved or renamed; offer archive / keep / relink with the inbound references, routes and redirects each affects |
+| Route or slug change | A URL and redirect plan (`create_redirect`); check collisions, canonicals and internal links first |
+| Assets | Match by source id or path plus checksum; a changed binary is a new revision; a missing source asset never breaks a published reference until the user approves its replacement or removal |
+
+Dry-run the proposed operations, then run the same snapshot again to prove it is idempotent (no
+new changes the second time). Apply only approved, supported changes, then compare counts,
+references, component usage, field bindings, preview and the affected public routes. The rollback
+for a content value the sync got wrong is §4.
+
+## 6. Automation surfaces
+
+"Run X when content changes" maps onto what exists; there is no user-deployed function runtime.
+
+| Need | Surface | Owner |
+|---|---|---|
+| Rebuild or revalidate a site on publish | The publish webhook, signed `X-BetterCMS-Signature` (HMAC-SHA256 of the raw body) with the project's webhook secret ([frameworks.md](frameworks.md) Revalidation) | Secret set in the dashboard; your route verifies it |
+| Notify another system of an event | Event webhooks, `list_webhooks` / `create_webhook`: `content.publish`, `content.unpublish`, `content.stage_changed` (workflow stage), `content.created`, `content.updated`, `content.deleted` and `deployment.triggered`; HMAC-SHA256 signed in `X-BetterCMS-Signature`; payloads carry ids, never content: an entry's `content.publish`/`content.unpublish` carries `data.entryId`, a page's carries `data.pageId` and `kind: "page"` (so `entryId` is not always present). The signing `secret` is returned ONCE, on create. A receiver that writes back on `content.updated` loops unless it skips its own writes. Per-subscription payload filters: dashboard | You |
+| Send form submissions somewhere | Per-form integrations: Google Sheets, Slack, a webhook, email | Dashboard only |
+| Go live or retire at a time | `scheduledAt` (publish a draft at a time; needs publish permission) and `unpublishAt` (return a published row to draft) on `update_content_entry` and `update_page`; `null` cancels either. Campaigns: `publish_campaign` takes both | You. An edit that omits `scheduledAt` CANCELS the pending publish, so resend it with every edit before it fires; omitting `unpublishAt` never cancels it |
+| Show one section only for a period | `window` `{ from?, until? }` on a page block (`update_page` `blockJson`) or on a Layout Section (`update_layout` `add-section`, `update-section`). Shown from `from` until `until`; each is an ISO 8601 datetime with an offset (`2026-11-27T00:00:00+01:00`), stored as UTC, and either may be left out. `null` clears it. Refusals: `invalid_window` (no offset, or not a date), `window_inverted` (`from` not before `until`), `window_in_component` (inside a component's `blockJson`: put it on the placement), `window_in_entry` (on a block inside an entry's sections value: put it on the page block or Layout Section that shows the entry). A Section a page adds or customizes takes a window like a Global one | You. Outside its window the block is in no published output: the page, its Markdown, the delivery API and search. A draft preview draws it, marked. A page BetterCMS renders per request changes at the boundary; a static site catches up within about a minute, in place when a section goes and with a build when one appears. Site code that renders its own header ignores a Section's window |
+| Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed` (with `externalKey` also `updated` or `unchanged`, so a re-run is safe); then `publish_entries` | You |
+| React to edits made elsewhere | Poll `list_activity` with `since` set to the time of your last read (1–100 events per call) | You |
+| Generate or rewrite in bulk with a human gate | AI jobs: `list_ai_jobs`, `get_ai_job`, then `approve_ai_job` or `reject_ai_job` on the user's word | User approves |
+
+Not available, so say so instead of building around it: code that runs inside BetterCMS on a
+content event, and a change subscription over the MCP (poll `list_activity` `since`). Anything
+beyond the table runs in the user's own infrastructure, triggered by a webhook. Why: a timer on the
+delivery API looks like a trigger, but it serves published content only and never sees an edit
+before it ships.
+
+## Report
+
+State what is live, what remains draft, whether a rollback ran, and any owner action still
+required (Visual Approval, a render-mode change, a secret). For a sync, list exact created,
+updated, unchanged, orphaned and conflicted ids, the choices still open, and the rollback point;
+an open conflict is never a successful sync. Do not say "launched" until the public response is
+verified.