@bettercms-ai/mcp 0.65.1 → 0.66.0

package/dist/index.js

@@ -2676,9 +2676,17 @@ var NEW_TOOL_TEXT = {
   search_docs: "Search the BetterCMS documentation. Returns the best pages (title, url, breadcrumbs, snippet). Use it before guessing how a feature works; `meta.unavailable` means docs search is down right now.",
   generate_image: "Generate an image with AI and add it to the Media Library (5 AI credits; free with the workspace's own Together key). `width`/`height` are 256-1440 in multiples of 16 (default 1024x768). Returns the new asset (id, url, altText): use the url as an 'image' field value. Always set `altText`.",
   refresh_search_index: "Tell search engines and site search about published changes; costs nothing. action 'indexnow' submits `urls` (this site's own, up to 1000) to IndexNow, or every change since the last submission when omitted. action 'reindex' rebuilds the project's site-search index. 503 means the index is unreachable: try again later.",
+  editor_setup: "Make the live build editable. A build imports only SEO/meta, media, brand and the models bcms-content.json declares; this derives the rest from the live release: pages, collections, forms, bindings, button and section components (when the authoring preference is components), Component Groups and the Content sidebar. Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true` or get_deploy_status `editorSetup`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
   transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText)."
 };
 var PARAM_TEXT = {
+  editorSetupForce: "re-run a setup already ready for the live build",
+  editorSetupCheck: "true = only report the state; starts nothing",
+  pageDynamic: "a dynamic (collection template) page only",
+  previewPath: "its route pattern, e.g. /blog/{slug}; null clears",
+  pageModelId: "an existing collection this page lists (when it has no model yet)",
+  formIgnored: "true = not one of the site's forms (a search box, a widget); false restores it",
+  componentizeCodemod: "true = componentize nothing; run the section-order codemod (`--componentize`) in the connected repo on its own Actions, which commits `<Sections>` templates for the next build. After the components and pages are published. `skipped` = no repo to commit to: run the codemod yourself",
   where: "field filters: {field: value} is equality, {field: {op: value}} with op eq|ne|gt|gte|lt|lte|contains|in, and an array means `in`. System fields slug, status, publishedAt, locale work anywhere; a data field needs modelId. Compares the served copy (live for published, working for draft)",
   sort: "comma list, a leading - sorts descending, e.g. '-publishedAt,title'",
   page: "1-based page of `limit` rows; the response's meta says totalPages",
@@ -3227,7 +3235,7 @@ function authPrompt(err) {
 var currentProject = new AsyncLocalStorage();
 var currentBranch = new AsyncLocalStorage();
 var projectIdArg = z.string().min(1).optional().describe(
-  "target project id (from list_projects); only for a workspace-wide grant."
+  "project id (list_projects); workspace-wide grants only"
 );
 var branchIdArg = z.string().min(1).optional().describe("content branch id (from list_branches); omit to work on main");
 var withProjectId = (def) => ({
@@ -3510,7 +3518,8 @@ function buildToolDefs(deps) {
     formId: z.string().min(1).describe("form id (from list_forms)"),
     name: z.string().optional(),
     fields: z.array(formFieldObject).optional().describe("REPLACES the field array \u2014 include all fields to keep"),
-    ...formSettingsShape
+    ...formSettingsShape,
+    ignored: z.boolean().optional().describe(PARAM_TEXT.formIgnored)
   });
   const componentPropObject = z.object({
     key: z.string().min(1),
@@ -4138,7 +4147,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "set_authoring_preference",
         "Set the site's authoring architecture",
-        "Record which authoring architecture this site uses \u2014 'components' (RECOMMENDED: reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema \u2014 recommend it for every marketing, landing, agency or product site) or 'fields' (a typed field schema per page \u2014 only for a blog, catalogue or directory where many rows share one shape). ASK THE USER; do not pick for them. Called without `preference`, this tool asks them directly (or hands you the question to ask). deploy_project and promote_project both refuse with 409 AUTHORING_DECISION_REQUIRED until it is set, carrying this project's real page counts to show the user. Unset, the release lane already acts as `components`; only `fields` stops it. On a site whose pages were DERIVED at import, answering 'components' redoes nothing: after set_authoring_preference, get_componentize_plan proposes one component per section (it reads the PUBLISHED pages \u2014 no deploy needed to reach it), you confirm it with the user, then componentize_sections places them with `props.bind` (dry run first \u2014 they land as drafts and the page keeps its fields, values and bindings, so click-to-edit and the coverage meter are unchanged), then publish_component each one, publish the pages, run `npx @bettercms-ai/convert --componentize` in the repo, and deploy. Asked once per project; re-callable if the user changes their mind.",
+        "Record which authoring architecture this site uses \u2014 'components' (RECOMMENDED: reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema \u2014 recommend it for every marketing, landing, agency or product site) or 'fields' (a typed field schema per page \u2014 only for a blog, catalogue or directory where many rows share one shape). ASK THE USER; do not pick for them. Called without `preference`, this tool asks them directly (or hands you the question to ask). deploy_project and promote_project both refuse with 409 AUTHORING_DECISION_REQUIRED until it is set, carrying this project's real page counts to show the user. Unset, editor_setup componentizes nothing; only `components` lets it place sections. On a site whose pages were DERIVED at import, answering 'components' redoes nothing: after set_authoring_preference, get_componentize_plan proposes one component per section (it reads the PUBLISHED pages \u2014 no deploy needed to reach it), you confirm it with the user, then componentize_sections places them with `props.bind` (dry run first \u2014 they land as drafts and the page keeps its fields, values and bindings, so click-to-edit and the coverage meter are unchanged), then publish_component each one, publish the pages, run `npx @bettercms-ai/convert --componentize` in the repo, and deploy. Asked once per project; re-callable if the user changes their mind.",
         // Optional in the schema for exactly the reason `framework` is above: a required arg is
         // rejected by the SDK before the handler runs, which would kill the elicitation below
         // and leave the model guessing. Optional here, answered by a human there. The backend
@@ -4292,14 +4301,14 @@ ${d.outline}` : "Proposed Content structure.", d);
         "update_page",
         "Edit a page",
         "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first and send its `optimisticVersion` as `ifMatch`). A `blockJson` that swaps a component block to another component comes back with `warnings` (COMPONENT_SWAP_DROPS_OVERRIDES) naming the overrides the new component does not render; they stay on the block, so swapping back restores them. It does NOT change the field SCHEMA \u2014 use add_field (pageId) / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call \u2014 and on a singleton it publishes the page's content entry too; if the entry's workflow stage refuses, the page still goes live and `warnings` carries ENTRY_STILL_DRAFT with the entry id and the reason. STRUCTURED DATA is native SEO, never a field: leave it out and the page gets Automatic JSON-LD from its content (WebSite on the home page, Blog/CollectionPage on a collection's list page, WebPage otherwise); `schemaType` picks an explicit schema.org type whose properties are filled from the content; `schema` is pasted JSON-LD and wins over both (null clears it). " + PAGE_HEAD_NOTE + " " + SECTION_DOCTRINE,
-        z.object({ ...headPatchShape, noindex: z.boolean().optional().describe("hide this page from search engines and site search"), pageId: z.string().min(1), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional(), scheduledAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageScheduledAt), unpublishAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageUnpublishAt), locale: z.string().nullable().optional().describe(PARAM_TEXT.locale), translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf), ifMatch: z.number().int().min(0).optional().describe(UPDATE_PAGE_IF_MATCH_NOTE) }).shape,
+        z.object({ ...headPatchShape, noindex: z.boolean().optional().describe("hide this page from search engines and site search"), pageId: z.string().min(1), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional(), scheduledAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageScheduledAt), unpublishAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageUnpublishAt), locale: z.string().nullable().optional().describe(PARAM_TEXT.locale), translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf), ifMatch: z.number().int().min(0).optional().describe(UPDATE_PAGE_IF_MATCH_NOTE), dynamic: z.object({ previewPath: z.string().nullable().optional().describe(PARAM_TEXT.previewPath), modelId: z.string().min(1).optional().describe(PARAM_TEXT.pageModelId) }).optional().describe(PARAM_TEXT.pageDynamic) }).shape,
         async (c, a) => {
           const res = await c.fetchJSON(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
             {
               method: "PATCH",
               ...a.ifMatch !== void 0 ? { headers: { "If-Match": `W/"${a.ifMatch}"` } } : {},
-              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status, noindex: a.noindex, canonical: a.canonical, og: a.og, twitter: a.twitter, scheduledAt: a.scheduledAt, unpublishAt: a.unpublishAt, locale: a.locale, translationOf: a.translationOf })
+              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status, noindex: a.noindex, canonical: a.canonical, og: a.og, twitter: a.twitter, scheduledAt: a.scheduledAt, unpublishAt: a.unpublishAt, locale: a.locale, translationOf: a.translationOf, ...a.dynamic })
             }
           );
           const note = res.redirectNote;
@@ -4721,7 +4730,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "componentize_sections",
         "Turn this site's derived sections into components",
-        "Turn this site's derived sections into components. CONFIRM WITH THE USER FIRST: show them get_componentize_plan's sections, how many components it will create and which pages it will rewrite; `dryRun` first. It creates each proposed component as a DRAFT and replaces each page's DRAFT blocks with ordered `component` instances, one per group, each carrying `props.bind: \"<groupKey>\"` \u2014 the page field group that already holds the copy. Nothing is copied or moved: the page keeps its `fields`, values and bindings, so click-to-edit and the coverage meter do not change (`copy: \"instance\"` moves the words onto each placement instead \u2014 see `copy`). Pass the plan's `digest`; a 409 `stale-plan` means the site changed: read the plan again, show the user what changed and confirm again. Read `components.wouldDuplicate` first: each id is an existing same-family component a NEW one would sit beside (reuse is by identity and slug, never family). Re-running is safe: a placed group returns as ALREADY_COMPONENTIZED. DRAFTS ONLY \u2014 an unpublished component renders as an EMPTY STRING on the live site, so publish_component each one and publish the pages, then run `npx @bettercms-ai/convert --componentize` in the repo so its templates render these sections from `pages[].blocks`. Every component it CREATES is filed into a Component Group (see `group`). When the user says a proposed group is NOT a section, pass `decline: true` with those `sections` (and `pageIds`): nothing is componentized, the plan reports them `NOT_A_SECTION` / `DECLINED` and stops proposing them, and a plan that proposes nothing undeclined is done.",
+        "Turn this site's derived sections into components. CONFIRM WITH THE USER FIRST: show them get_componentize_plan's sections, how many components it will create and which pages it will rewrite; `dryRun` first. It creates each proposed component as a DRAFT and replaces each page's DRAFT blocks with ordered `component` instances, one per group, each carrying `props.bind: \"<groupKey>\"` \u2014 the page field group that already holds the copy. Nothing is copied or moved: the page keeps its `fields`, values and bindings, so click-to-edit and the coverage meter do not change (`copy: \"instance\"` moves the words onto each placement instead \u2014 see `copy`). Pass the plan's `digest`; a 409 `stale-plan` means the site changed: read the plan again, show the user what changed and confirm again. Read `components.wouldDuplicate` first: each id is an existing same-family component a NEW one would sit beside (reuse is by identity and slug, never family). Re-running is safe: a placed group returns as ALREADY_COMPONENTIZED. DRAFTS ONLY \u2014 an unpublished component renders as an EMPTY STRING on the live site, so publish_component each one and publish the pages, then call it again with `codemod: true` (or run `npx @bettercms-ai/convert --componentize` in the repo) so its templates render these sections from `pages[].blocks`. Every component it CREATES is filed into a Component Group (see `group`). When the user says a proposed group is NOT a section, pass `decline: true` with those `sections` (and `pageIds`): nothing is componentized, the plan reports them `NOT_A_SECTION` / `DECLINED` and stops proposing them, and a plan that proposes nothing undeclined is done.",
         z.object({
           digest: z.string().min(1).describe("The `digest` get_componentize_plan returned. A different one is refused with 409 stale-plan."),
           pageIds: z.array(z.string().min(1)).optional().describe("Componentize only these pages (ids from the plan). Omit for every page the plan lists."),
@@ -4731,9 +4740,10 @@ ${res.warnings.join("\n")}` : summary, res.data);
           dryRun: z.boolean().optional().describe("true = return the receipt without writing anything. Do this first."),
           group: z.string().min(1).max(100).optional().describe("File the components this run creates into this Component Group (a folder of the dashboard's Components tab; by NAME, created when missing), else its section family: nav, header, footer or menu \u2192 Layout, an unnamed section \u2192 Sections, otherwise the family name (Hero, FAQ). A reused component keeps its Group; the receipt's `components.groups` lists the Groups filed into."),
           decline: z.boolean().optional().describe("true = record `sections` as NOT sections (nothing is componentized; the plan stops proposing them). false = offer them again. Needs `sections`."),
-          joinTwins: z.boolean().optional().describe("true = move each locale copy (`/fr`) still on its own component onto its twin's (`bindPaths` keeps its fields). A dry run lists each in `joins`. Whole plan only.")
+          joinTwins: z.boolean().optional().describe("true = move each locale copy (`/fr`) still on its own component onto its twin's (`bindPaths` keeps its fields). A dry run lists each in `joins`. Whole plan only."),
+          codemod: z.boolean().optional().describe(PARAM_TEXT.componentizeCodemod)
         }).shape,
-        async (c, a) => ok("Componentized the sections.", await data(c, "POST", `/management/projects/current/componentize`, { digest: a.digest, pageIds: a.pageIds, pages: a.pages, sections: a.sections, copy: a.copy, dryRun: a.dryRun, group: a.group, decline: a.decline, joinTwins: a.joinTwins }))
+        async (c, a) => ok(a.codemod === true ? "Section-order codemod." : "Componentized the sections.", await data(c, "POST", a.codemod === true ? `/management/projects/current/section-order` : `/management/projects/current/componentize`, { digest: a.digest, pageIds: a.pageIds, pages: a.pages, sections: a.sections, copy: a.copy, dryRun: a.dryRun, group: a.group, decline: a.decline, joinTwins: a.joinTwins, codemod: a.codemod }))
       ),
       def(
         "get_analytics_overview",
@@ -4949,9 +4959,21 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|categorizing|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `categorizing` means the bytes are live (`publishing` false) but the setup lanes (content, pages, bindings) are still running: not ready to edit yet. Poll this after deploy_project until state is idle with your sha live. `release` is the newest release (id, sha, status, phaseMarks, error, createdAt): while an uploaded build ingests or releases, state is `building`, `release.sha` the new sha and `lastLiveSha` still the old one; a failed deploy shows `release.status` failed with its `error`, and `held` state (`held.by`: staff, archived or no-subdomain) means the release waits until that is cleared. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release` is the newest release (id, sha, status, phaseMarks, error, createdAt): while an uploaded build ingests or releases, state is `building`, `release.sha` the new sha and `lastLiveSha` still the old one; a failed deploy shows `release.status` failed with its `error`, and `held` state (`held.by`: staff, archived or no-subdomain) means the release waits until that is cleared. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
         z.object({}).shape,
-        async (c) => ok("Deploy status.", await data(c, "GET", `/management/projects/deploy-status`))
+        // Flat body, no `data` envelope: `data()` read it as undefined.
+        async (c) => ok("Deploy status.", await c.fetchJSON(c.url(`/management/projects/deploy-status`), { method: "GET" }))
+      ),
+      def(
+        "editor_setup",
+        "Set up editing for the live build",
+        NEW_TOOL_TEXT.editor_setup,
+        z.object({
+          force: z.boolean().optional().describe(PARAM_TEXT.editorSetupForce),
+          check: z.boolean().optional().describe(PARAM_TEXT.editorSetupCheck)
+        }).shape,
+        // The route answers `{ state, … }` with no `data` envelope, so the whole body is the result.
+        async (c, a) => ok("Editor setup.", await c.fetchJSON(c.url(`/management/projects/editor-setup`), a.check === true ? { method: "GET" } : { method: "POST", body: JSON.stringify({ force: a.force }) }))
       ),
       // ── Deploy to the user's own host (parity with remote /mcp) ──
       // A person connects Vercel or Netlify in the dashboard; nothing here touches OAuth or a host
@@ -5890,7 +5912,7 @@ A collection (\`create_content_model\`) plus entries.
 
 Most real sites are both: components for the marketing pages, a collection for the blog.
 Decide before your first call; converting later means rewriting content \u2014 unless the site was
-DERIVED at import, where the componentize lane in \xA710 reuses every field.
+DERIVED by \`editor_setup\`, where the componentize lane in \xA710 reuses every field.
 
 ## 2. The decision tree
 
@@ -5967,8 +5989,8 @@ sibling calls it \`headline\` silently drops that content on the swap.
 Pair \`sectionType\` with a library \`category\` (hero, content, social-proof, conversion) or
 the component never appears in the editor's "Add a section" picker.
 
-**An IMPORTED site gets there without you writing any of that.** Its pages were derived at
-import \u2014 flat field groups (\`hero-title\`, \`faq-question\`, the repeaters folded as \`group-*\`)
+**An IMPORTED site gets there without you writing any of that.** Its pages are derived by
+\`editor_setup\` \u2014 flat field groups (\`hero-title\`, \`faq-question\`, the repeaters folded as \`group-*\`)
 and an empty \`blockJson\` \u2014 so there is nothing in the picker and no section to swap. Read
 \`get_componentize_plan\`: it groups those fields into sections, names each family, and proposes
 one component per SHAPE (the same hero on two pages is one component with two placements),
@@ -6096,14 +6118,27 @@ written to the wrong project can only be demoted (\`sectionType: null\`) and lef
 
 ## 10. You imported a site, or you are about to deploy one
 
+**A build imports what the build itself ships, and nothing more:** SEO and meta, every media
+asset, the brand, and the models the repository declares in \`bcms-content.json\`. Everything
+that makes the site EDITABLE \u2014 pages, inferred collections, forms, bindings, button and section
+components \u2014 is \`editor_setup\`, run on demand against the live build. The import recipe:
+
+    import (import_github_repo / deploy_project)  ->  editor_setup (poll { check: true } until ready)
+    ->  the authoring answer  ->  componentize_sections, or get_conversion_brief (\xA713)
+    ->  the codemods (componentize_sections { codemod: true } runs the section-order one in the repo)
+    ->  submit_conversion_receipt / submit_componentize_receipt  ->  deploy
+
+\`get_deploy_status\` \`editorSetup\` (and get_next_steps) say when it has not run for the live
+build: \`never\` or \`stale\` \u2192 run it before anything below.
+
 \`deploy_project\` and \`promote_project\` both answer **409
 AUTHORING_DECISION_REQUIRED** until a human has chosen this project's architecture. This is
 asked ONCE per project, ever. It is not an error to retry or route around: read the message
 out, let the user pick, call \`set_authoring_preference\`, then deploy again.
 
-Until someone answers, the release lane behaves as \`components\`: the preference is null, and
-each release still componentizes the derived pages in bind mode. \`fields\` is the only answer
-that stops it. And a run over the WHOLE plan splits a section component an earlier run placed on
+Until someone answers, \`editor_setup\` derives the pages but componentizes nothing (the
+preference is null). Once \`components\` is recorded, each \`editor_setup\` componentizes the
+derived pages' NEW sections in bind mode; \`fields\` stops it for good. And a run over the WHOLE plan splits a section component an earlier run placed on
 2 pages into one per page (the first page keeps it, the others get a clone), so two pages' heroes
 stop editing each other; a run narrowed to one page or section never splits.
 
@@ -6112,9 +6147,9 @@ It exists because an imported site arrives **field-driven whether anyone chose t
 and an empty block tree, because that is all a crawl can infer. Nobody decided it. On a
 marketing site it is the wrong answer. So the platform stops once, at the last moment it is
 still cheap \u2014 and on a derived site that moment costs nothing, because the componentize lane
-below reuses every field the import already derived.
+below reuses every field \`editor_setup\` already derived.
 
-**Recommend \`components\`.** On a site whose pages were DERIVED at import \u2014 the site \xA713
+**Recommend \`components\`.** On a site whose pages were DERIVED by \`editor_setup\` \u2014 the site \xA713
 describes \u2014 it redoes nothing: the componentize lane turns each top-level field GROUP into a
 component placement, and the page keeps its fields, its values and its bindings. In this order:
 
@@ -6122,7 +6157,7 @@ component placement, and the page keeps its fields, its values and its bindings.
     2. get_componentize_plan    one component per section, computed live; creates nothing. It
                                 reads this project's PUBLISHED pages, so no deploy is needed
                                 to reach it \u2014 the deploy is the last step, not the first.
-                                On a site DERIVED at import, each release after this answer
+                                On a DERIVED site, each editor_setup after this answer
                                 runs this plan in bind mode for NEW sections (it never splits
                                 or joins a placement, and runs nothing while the answer is
                                 unset) and PUBLISHES what it created, so after one expect
@@ -6137,8 +6172,11 @@ component placement, and the page keeps its fields, its values and its bindings.
     5. publish_component        each one \u2014 unpublished renders as NOTHING, on a page that 200s
     5b. publish_layout          if you authored site chrome \u2014 the layout is a separate publish
     6. publish the pages
-    7. npx @bettercms-ai/convert --componentize   in the repo, so its templates render these
-                                sections from \`pages[].blocks\`
+    7. componentize_sections { digest, codemod: true }   the section-order codemod
+                                (\`--componentize\`) on the repo's own Actions, so its templates
+                                render these sections from \`pages[].blocks\`; \`skipped\` = no
+                                repo it may commit to: run \`npx @bettercms-ai/convert
+                                --componentize\` in your checkout
     8. deploy                   the ONLY deploy this sequence needs
 
 Step 5 is not a formality: \`componentize_sections\` and \`create_component\` both land components
@@ -6298,10 +6336,12 @@ but a code-built site ships only what its own templates draw:
   itself, in order, each section root stamped \`data-bcms-block="<blockId>"\`. \`npx @bettercms-ai/convert
   --componentize\` writes that loop (\`src/lib/bcms-sections.ts\`) and the stamps. Until it ships, the canvas
   only ARRANGES the static build to match the draft (a section the build never rendered is stood in for
-  by a server render), the editor locks Add section and reordering on routes whose code sets the
-  sections, and each such route leads \`submit_conversion_receipt\`'s \`pending\` with a
-  \`SECTIONS_UNSTAMPED\` row, so \`complete\` stays false. Never hard-code a page's bands in a template
-  whose order the CMS owns.
+  by a server render); the editor still saves added, moved and swapped sections but says the live site
+  keeps its own order, and offers "Let BetterCMS control section order" (that same codemod, committed
+  to the connected repository); and each such route leads \`submit_conversion_receipt\`'s \`pending\`
+  with a \`SECTIONS_UNSTAMPED\` row, so \`complete\` stays false. Never hard-code a page's bands, or
+  literal \`data-bcms-block\` ids, in a template whose order the CMS owns: a release measures whether
+  the stamped roots come out in the CMS order (\`ordered\` on the binding report's structure row).
 - A placement the site never renders (a leftover nav, footer or modal its layout draws) moves
   nothing: the editor counts section moves in RENDERED sections only and locks that row. Remove
   such placements; do not reorder around them.
@@ -6369,10 +6409,10 @@ JSON. On an IMPORTED site, never materialize a builtin: read the repo's own comp
 (\`src/components\`, its sections folder) and make ONE CMS component per source component, named
 as the source names it \u2014 the site's Pricing section is "Pricing", not "Section 2" or "Simple".
 On a DERIVED site run \`get_componentize_plan\` \u2192 \`componentize_sections\` FIRST \u2014 it does most
-of this in one call, and once \`components\` is recorded each release of a site derived at IMPORT
+of this in one call, and once \`components\` is recorded each \`editor_setup\` of a derived site
 runs it in bind mode and publishes the components, so expect ALREADY_COMPONENTIZED \u2014 the placements it wrote are
-still DRAFT blocks on the pages, so publish the pages, then \`npx @bettercms-ai/convert
---componentize\`.
+still DRAFT blocks on the pages, so publish the pages, then \`componentize_sections { codemod: true }\`
+(or \`npx @bettercms-ai/convert --componentize\` in your checkout).
 
 **3. The hierarchy editors see is the GROUP.** \`create_component\` and \`update_component\` take
 \`group\`: a NAME, resolved against the project's component groups and created when missing. That
@@ -6477,9 +6517,10 @@ anything. See \xA79.
 
 **Which recipe.** There are TWO below and they are not alternatives you pick by taste \u2014 call
 \`get_binding_report\` and \`get_conversion_brief\` first and let the answer choose. A brief that
-comes back WITH PAGES means this project was imported and deployed, so its schema and values were
-derived for you already \u2192 **Recipe A**. A 404 or an empty brief means the site is not in the CMS
-yet \u2192 **Recipe B**. \`get_next_steps\` works on every plan and names the next unfinished step
+comes back WITH PAGES means this project was imported and \`editor_setup\` derived its schema and
+values already \u2192 **Recipe A**. On an import whose \`get_deploy_status\` \`editorSetup\` is \`never\`
+or \`stale\`, run \`editor_setup\` FIRST and read the brief again. A 404 or an empty brief after
+that means the site is not in the CMS yet \u2192 **Recipe B**. \`get_next_steps\` works on every plan and names the next unfinished step
 either way.
 
 **If you know Sanity, this is the same shape under different names:**
@@ -6495,8 +6536,8 @@ either way.
                                     draft reads
     Presentation tool overlays  ->  the visual editor canvas, framing your own build
 
-**Imported site whose pages were DERIVED.** If this project was imported and made editable from
-its build, the schema and the values already exist \u2014 a page per route, a field per element, and
+**Imported site whose pages were DERIVED.** If this project was imported and \`editor_setup\` ran
+over its build, the schema and the values already exist \u2014 a page per route, a field per element, and
 the original copy carried on each field as its \`defaultValue\`. Call \`get_conversion_brief\`
 first: it lists those pages, their routes, every bindable path with its current and original
 value, and the attributes to declare. SKIP Recipe B's steps 3 and 4 below and bind the keys it
@@ -6900,7 +6941,7 @@ Do not stop at the plan or at a partial receipt \u2014 finish the whole site, ne
 
 1. \`list_projects\`; pass \`projectId\`${projectId ? ` (${projectId})` : ""} on every project tool. Not listed = the grant is on
    another workspace: have the user re-authenticate there. Never convert a different project.
-2. \`get_conversion_plan\`. On a 404 \`no-approved-plan\`, call
+2. \`editor_setup\` until it is \`ready\` (poll with \`check: true\`), then \`get_conversion_plan\`; on a 404 \`no-approved-plan\`,
    \`get_conversion_brief { complete: true }\` and follow \`cursor\` to the LAST page, keeping every
    page \u2014 a codemod fed the capped brief converts a truncated site. Write them to \`brief.json\`.
 3. \`pull_project_source\` (or clone the \`github\` remote it names) and work from the SOURCE, never
@@ -7054,8 +7095,8 @@ Read \`bettercms://playbook/schema\` \xA712 first \u2014 this is the short form
 2. **One component per distinct section**, one-offs included. \`sectionType\` is the family;
    components sharing one are VARIANTS and must share prop KEYS. A one-off gets its own family
    plus \`allowedOn: ["slug:<page>"]\`. Start from the \`builtin:*\` blueprints in
-   \`list_components\`. On a DERIVED site run \`get_componentize_plan\` \u2192 \`componentize_sections\`
-   first (dryRun first, and confirm the plan with the user).
+   \`list_components\`. On a DERIVED site (\`editor_setup\` derives it) run \`get_componentize_plan\` \u2192
+   \`componentize_sections\` first (dryRun first, and confirm the plan with the user).
 3. **Hierarchy** = \`group\` on create_component/update_component (a NAME; created when missing).
    Use Global, Navigation, Actions, Content, Forms, Media, Sections, Page-specific. \`category\`
    is the separate picker TAB.
@@ -7459,7 +7500,7 @@ On 401/403, the MCP key needs (re)authorizing.`
     "import-site",
     {
       title: "Make an imported site editable (guided)",
-      description: "After deploying an existing site: bring its content into the CMS so the visual editor can bind it, declare its presentation manifest, and publish everything that renders. A deploy makes a site LIVE, not EDITABLE \u2014 this flow closes that gap.",
+      description: "After importing or deploying an existing site: run the editor setup, componentize or convert it, declare its presentation manifest, and publish everything that renders. A build makes a site LIVE, not EDITABLE \u2014 this flow closes that gap.",
       argsSchema: {
         request: z2.string().optional().describe("scope, e.g. 'all routes' or 'just the home page'")
       }
@@ -7474,17 +7515,22 @@ On 401/403, the MCP key needs (re)authorizing.`
 
 Read bettercms://playbook/schema section 11 first, then work this order:
 
-1. AUTHORING GATE \u2014 if any deploy answered 409 AUTHORING_DECISION_REQUIRED, ask ME
-   components-or-fields (do not choose), then set_authoring_preference.
-2. CONTENT INTO THE CMS, per route: create_page (slug = route) -> add_field {pageId} (or
-   create_component + publish_component + component blocks) -> set_page_content with values
-   EXACTLY equal to the rendered text (binding matches by value; a paraphrase binds nothing)
-   -> update_page status 'published' (the canvas binds the PUBLISHED copy).
-3. PRESENTATION MANIFEST \u2014 add bcms-presentation.json to public/ (container width, type
+1. EDITOR SETUP \u2014 the build imported only SEO/meta, media, brand and the models the repo
+   declares. Call editor_setup and poll editor_setup { check: true } until \`ready\`: it derives
+   the pages, collections, forms and bindings from the live build.
+2. AUTHORING GATE \u2014 if get_next_steps or a deploy (409 AUTHORING_DECISION_REQUIRED) asks,
+   ask ME components-or-fields (do not choose), then set_authoring_preference.
+3. COMPONENTS: get_componentize_plan -> componentize_sections (dryRun first) -> publish the
+   components and pages -> componentize_sections { codemod: true } (the section-order codemod in
+   the repo). FIELDS: the convert_site loop (get_conversion_brief, the codemod, the receipt).
+   Only where the setup derived nothing: create_page (slug = route) -> add_field {pageId} ->
+   set_page_content with values EXACTLY equal to the rendered text (binding matches by value; a
+   paraphrase binds nothing) -> update_page status 'published'.
+4. PRESENTATION MANIFEST \u2014 add bcms-presentation.json to public/ (container width, type
    scale, nav position/background, footer surface as DTCG {"$type","$value"} entries) and
    redeploy, or structural draft previews render in a generic theme, not this site's design.
-4. VERIFY \u2014 call get_next_steps and fix what it lists (it knows about missing manifests,
-   content still only in the build, and placed-but-unpublished components), or tell me why
+5. VERIFY \u2014 call get_next_steps and fix what it lists (it knows about missing manifests,
+   a setup that has not run, and placed-but-unpublished components), or tell me why
    an item is being left.
 
 On 401/403, the MCP key needs (re)authorizing.`