@bettercms-ai/mcp 0.33.0 → 0.34.0

package/dist/index.js

@@ -2958,7 +2958,7 @@ function buildToolDefs(deps) {
       def(
         "pull_project_source",
         "Pull the project's live source",
-        "Get the connected project's CURRENT live source/build so you can edit it locally. Returns a presigned tarball download url (1h) + the live commit sha \u2014 download it, extract, edit the files, then call deploy_project. If the project is connected to a GitHub repo, returns `github: {owner, repo}` so you can `git clone` that instead.",
+        "Get the connected project's CURRENT live source/build so you can edit it locally. Returns a presigned tarball download url (1h) + the live commit sha \u2014 download it, extract, edit the files, then call deploy_project. If the project is connected to a GitHub repo, `github` carries owner, repo, branch and cloneUrl \u2014 clone it and work on THAT branch, because it is the one the provisioned Action builds from; a commit on any other branch never reaches the live site.",
         z.object({}).shape,
         async (c) => ok("Project source.", await data(c, "GET", `/management/projects/source`))
       ),
@@ -4135,6 +4135,13 @@ the canvas but skips release annotation and publish-time injection, because ther
 disk to annotate. Copy rendered on the client must carry the attributes in the HYDRATED DOM,
 and only the canvas sees it \u2014 a release scan cannot.
 
+**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
+either way.
+
 **If you know Sanity, this is the same shape under different names:**
 
     defineType schema in code   ->  content models / page fields (create_content_model,
@@ -4152,11 +4159,12 @@ and only the canvas sees it \u2014 a release scan cannot.
 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 steps 3 and 4 below and bind the keys it names \u2014
-registering the schema again builds a second one over the first.
+value, and the attributes to declare. SKIP Recipe B's steps 3 and 4 below and bind the keys it
+names \u2014 registering the schema again builds a second one over the first.
 
-**Run the CODEMOD rather than editing by hand.** For a derived site the whole of step 5 is
-mechanical, and there is a tool that does it. THE ORDER, and every step of it matters:
+**Recipe A \u2014 imported and deployed: the codemod order.** For a derived site the whole of Recipe
+B's step 5 is mechanical, and there is a tool that does it. Run the codemod rather than editing by
+hand. THE ORDER, and every step of it matters:
 
 1. \`get_conversion_brief { complete: true }\` \u2014 the COMPLETE brief, not the capped one. It comes
    back uncapped and paged (50 pages at a time): follow \`cursor\` until it stops coming back and
@@ -4176,7 +4184,11 @@ mechanical, and there is a tool that does it. THE ORDER, and every step of it ma
    what lets the coverage meter say WHY a path is undeclared instead of only that it is; without
    it every one of them reads \`not-declared\`, which looks like a broken site rather than work
    with a reason. It records and releases nothing.
-5. Push, or \`deploy_project\`, and wait for the release to be live (step 6 below).
+5. Push, or \`deploy_project\`. A PLAIN HTML repo \u2014 no \`package.json\` \u2014 deploys by PUSH ONLY:
+   \`deploy_project\` refuses such an archive by design, so pushing is the whole lane. Either way,
+   poll \`get_deploy_status\` until \`slot\` is \`current\` (or \`awaitingPromote\` is false) before you
+   read the report in step 6 \u2014 a report read against the previous release is the previous
+   release's verdict.
 6. \`get_binding_report\`. Alongside \`unmatched\` it now carries \`coverage\` \u2014 \`declared\` (what the
    brief listed), \`bound\` (what the build declares) and \`pending\` with the reasons. Fix what it
    names and release again until \`coverage.pending\` is empty.
@@ -4185,14 +4197,15 @@ mechanical, and there is a tool that does it. THE ORDER, and every step of it ma
 
 **Or let BetterCMS propose the edit.** \`get_conversion_plan\` returns an APPROVED conversion \u2014 the
 exact new contents of each template file, reviewed by a human in the dashboard and already checked
-against this project's real field paths. When there is one, apply it instead of doing step 5 by
-hand: check out its \`baseHeadOid\`, branch from there, write each file's \`content\` verbatim, and
-carry on from step 6. A 404 with \`code: "no-approved-plan"\` means nobody approved one, so the
+against this project's real field paths. When there is one, apply it instead of Recipe A's step 2
+(the codemod): check out its \`baseHeadOid\`, branch from there, write each file's \`content\`
+verbatim, and carry on from Recipe A's step 5. A 404 with \`code: "no-approved-plan"\` means nobody approved one, so the
 conversion is yours to write.
 
-**The steps.**
+**Recipe B \u2014 not in the CMS yet: the steps.**
 
-1. \`pull_project_source\` (or clone the \`github\` remote it returns). Read the SOURCE. Never
+1. \`pull_project_source\` (or clone the \`github\` remote it returns \u2014 \`cloneUrl\` on the \`branch\`
+   it names, which is the branch the provisioned Action builds). Read the SOURCE. Never
    reconstruct content from the deployed HTML \u2014 that is how a site ends up bound to a copy of
    its own stale build.
 2. Decide the architecture WITH the human (\xA710) and record it: \`set_authoring_preference\`.
@@ -4266,7 +4279,9 @@ conversion is yours to write.
       then switch the project to "Run as a server app" on the Hosting page. Never migrate a
       static site to SSR without asking the human first.
     Then \`get_binding_report.canvas.lane\` reads \`bridge\` or \`draft-route\` instead of \`none\`.
-6. Push, or \`deploy_project\`; poll \`get_deploy_status\` until it is live. Then
+6. Push, or \`deploy_project\`. A PLAIN HTML repo \u2014 no \`package.json\` \u2014 deploys by PUSH ONLY:
+   \`deploy_project\` refuses such an archive by design. Poll \`get_deploy_status\` until \`slot\` is
+   \`current\` (or \`awaitingPromote\` is false). Then
    \`get_binding_report\` \u2014 still \`text-match\`, and \`unmatched\` should be EMPTY because the
    values are byte-equal to what the build renders. On a converted site read \`coverage\` too: it
    counts the PINNED brief's paths, which \`unmatched\` cannot, because \`unmatched\` only ever
@@ -4279,6 +4294,10 @@ conversion is yours to write.
    text against its entry values yourself before you call the page done. Then publish, and
    fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).
    \`get_next_steps\` keeps reporting the gap until every one of these holds.
+
+**Done means.** Whichever recipe you ran: \`get_binding_report\` reads \`mode "declared"\`,
+\`unmatched\` empty, \`bound\` above 0, \`coverage.pending\` empty, and \`canvas.lane\` is \`bridge\` or
+\`draft-route\` when the site should show structural drafts.
 `;
 
 // src/prompts.ts