@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/getting-started.md

@@ -1,156 +1,156 @@
----
-title: "Getting started"
-description: "Set up or resume a BetterCMS project: connect the MCP, pick or create the project, import or build the site, then publish and verify; the resume check for 'Continue BetterCMS setup'."
----
-
-# Getting started on a BetterCMS project
-
-The dashboard's launcher prompt points here. Its **Context** block holds what the dashboard
-already knows: project name and id, framework, source repo, and the job. Trust it, and ask only
-for what it leaves out.
-
-## Communication style
-
-Be succinct. Say what you did ("Converted 12 routes; 3 values still unmatched on /pricing") and
-skip narrating what you are about to do. Give numbers, not adjectives. Finish the setup in this
-run: do not stop to ask anything the sections below give an answer for.
-
-**RESUME TRIGGER.** On "Continue BetterCMS setup", read `get_project`, `get_next_steps` and
-`get_binding_report` for the project and the gap ledger at `.bettercms/ledger.json` if it exists,
-find the first phase below whose check is not met, say which one in one line, and resume there.
-Never redo a phase whose check already holds.
-
-## An existing site (imported from GitHub or a ZIP)
-
-### Phase 1 — Connect and confirm
-
-Check: the MCP answers for this project id, and this folder is its repo.
-
-1. Read the Connecting section of SKILL.md before your first tool call: a first-call 401 is the
-   sign-in, and a project missing from `list_projects` means the wrong workspace.
-2. `get_project` with the id from Context. Pass `projectId` on every project tool.
-3. Confirm this folder holds the site's `package.json` and source. If it does not:
-   - No repo on disk yet: clone it with `npx @bettercms-ai/cli@latest init --project-id <id>`
-     in the folder where the repo should live. It signs in, clones or downloads the source into
-     a new folder (named for the project unless you pass `--dir <path>`), installs dependencies,
-     pre-fills `.env`, and sets up these skills and the hosted MCP in the user's editors
-     (`npx -y @bettercms-ai/install@latest --global --mcp`). If it warned that the agent setup
-     failed, run the command the warning prints, inside the clone.
-   - Either way, stop and ask the user to restart you **inside** the repo folder: an MCP entry
-     added while you run loads only when the agent starts, and every step below works on that
-     folder's source. Not when `init` launched you: you already run there, connected.
-
-### Phase 2 — No questions: the defaults are recorded
-
-Nothing here is asked. Record and report:
-
-1. **Authoring**: components. A deploy, a promote and every `editor_setup` record it when nothing
-   is set; call `set_authoring_preference` only if the prompt you were started with names `fields`.
-2. **Media delivery**: the BetterCMS CDN, the project's default. Leave it.
-3. **Git**: the prompt you were started with says whether you may push. Follow it; never ask.
-
-Everything else has a default too. Do not ask about it; decide, then report what you decided:
-
-- **Scope is the whole site**: every page, section, heading, paragraph, list item, link and image
-  the site renders. Not the home page first, not "the main copy".
-- **Sections, their names and componentizing**: [components.md](components.md).
-- **Collections vs singletons**: [content-modeling.md](content-modeling.md).
-- **Field types and rich text**: [portable-text.md](portable-text.md).
-
-### Phase 3 — Convert and componentize
-
-Check: `editor_setup { check: true }` reads `ready`, `get_next_steps` returns
-`receipt.complete: true` and `get_componentize_plan` proposes nothing more. Where the job was to
-convert the source, `submit_conversion_receipt` also returned complete.
-
-0. A build brings in only SEO and meta, media, the brand and the models `bcms-content.json`
-   declares. Pages, collections, forms, bindings and components come from `editor_setup`: run it
-   and poll `editor_setup { check: true }` until `ready` before anything below. Run it again
-   whenever `get_deploy_status` reports `editorSetup` `stale`: a re-run flags the auto fields the
-   build no longer renders `stale` (hidden in the editor, never deleted) and never one a person edited, so never delete those by hand. It also fills missing meta from the
-   page copy, merges identical components and switches to declared bindings when the build proves
-   them; the receipt stays yours (it is the codemod's account of your repo).
-1. Explore the repo (the "Read when" column of SKILL.md's reference table names the signals) and
-   read `get_site_composition`.
-2. If `list_env_vars` reports `missing` variables, run `npx @bettercms-ai/cli@latest env push`
-   in the repository: it sets them from the user's own .env files without the values passing
-   through you. If they are not found there and the site loads its content from another CMS,
-   move that content into BetterCMS ([external-content.md](external-content.md)). Never ask the
-   user for a key or read one: a site left depending on missing keys renders empty or crashes.
-3. Work from `get_next_steps`: run `receipt.gate.nextAction`, read it again after each batch, and
-   repeat until `receipt.complete` is true. On a site set up from its build that gate is the only
-   finish line. Run the `convert_site` prompt only when the job is to convert the source (the gate
-   asks for it, the owner wants the code to declare its bindings, or the project is headless), and
-   then to its own complete receipt, never a partial one.
-4. With components recorded: `get_componentize_plan`, then apply it with
-   `componentize_sections` (the owner can undo it), then the repository half (`componentize_sections { codemod: true }`
-   when there is no checkout) and `submit_componentize_receipt` ([componentize.md](componentize.md)).
-5. Work the rest through [finish-site.md](finish-site.md) (gap ledger, repair order, proof loop).
-   The gate's `sections` and `style` rows are part of it: a setup whose pages cannot take a new
-   section, a new order or spacing is not finished.
-6. End Phase 3 on the editor chrome of every component (step 8 of finish-site.md's repair order,
-   [editor-chrome.md](editor-chrome.md)): the gate's `dock` row blocks until each has its V2 `ui`.
-
-### Phase 4 — Publish and verify
-
-Check: the deployed site passes the numbers below on every route.
-
-1. Deploy the way this project deploys: `deploy_project` on BetterCMS hosting; on a headless
-   project, push to the repo its host builds (never `deploy_project` there).
-2. `get_next_steps` reading `receipt.complete: true` is the finish line. `get_binding_report`
-   says why a route is short of it: `unaddressable` below 2% on each route, and, on a source you
-   converted, zero unmatched and an empty `coverage.pending`. `refreshReason: "never-generated"` on headless means
-   fetch the live site instead.
-3. Run the verify loop in SKILL.md against the live URL, then the two-path smoke test (click
-   through to a detail page, clean console, direct reload) in [frameworks.md](frameworks.md)
-   Verify step 5.
-4. Send a coverage report with its denominators, per route: values bound out of values found
-   (bound + unmatched), unaddressable text out of visible text, and routes converted out of
-   `builtRoutes`. A percentage with no denominator is not a report.
-5. Anything only the dashboard can do: name the exact click.
-
-## A new site (nothing built yet)
-
-1. Phase 1 above, then ask the authoring question (`set_authoring_preference`) before any schema
-   write.
-2. Read `bettercms://playbook/schema`. Plan routes and collections first
-   ([site-blueprints.md](site-blueprints.md)), then build sections ([components.md](components.md)).
-3. When a repo exists, clone it with the `init` command above, restart inside it, and continue
-   from Phase 3.
-
-## A headless project (its own front end)
-
-`get_project` says `hostingMode: "headless"`: BetterCMS never builds this site, its own host does.
-Done is `receipt.frontEnd` closed AND `receipt.gate` complete in get_next_steps: BetterCMS derived
-the owner's pages, their code reads the content, the front end has its site URL and rebuilds on
-publish. Work the rows in order; never `deploy_project` or `deploy_to_host`.
-
-1. **Launched by `bettercms init`** (`--agent claude|codex|opencode|cursor|gemini`): you run in the
-   owner's own front end, already connected. Do not ask to be restarted. **Their code, design and
-   copy ARE the site:** keep every component, route, class, style and asset; never redesign a page,
-   rebuild one from scratch or swap their components for new ones. A starter is only ever the
-   starting point when the owner chose one (`init --framework`).
-2. **Derive** (`derive` row). `npx @bettercms-ai/cli@latest derive` in the front end's folder builds
-   the site, renders every page as a visitor sees it and sends the pages to BetterCMS, which derives
-   their pages, fields and today's copy exactly as from a build it made. init runs it first; run it
-   yourself while the row is open. Never model those pages again.
-3. **Convert in place** (`receipt.gate`, the same gate as any built site). `get_conversion_brief
-   { complete: true }`, the convert codemod over this folder (its command is in
-   `bettercms://playbook/schema` §13), then `submit_conversion_receipt` with the receipt it wrote:
-   each literal becomes a read of its field with the markup byte-identical. Bind what it leaves pending by hand the same way. Then
-   start the build script with it, `"build": "bettercms pull-content && next build"`
-   (`@bettercms-ai/cli` a devDependency; not a `prebuild` hook, which Yarn and pnpm skip): the
-   converted pages read `bcms-content/*.json`, which only that step writes on the host's build.
-4. **Wire and read.** `.env` gets `BCMS_API_URL`, `BCMS_WORKSPACE` and `BCMS_PROJECT_ID` (from
-   `get_project`); published content needs no key. A starter whose config reads a key gets one
-   from `create_delivery_key` (`scope: "published"`), written straight into `.env`, never into
-   chat or a commit. Run the app and load a page: its first read closes `read`.
-5. **Deploy.** `npx @bettercms-ai/cli@latest deploy --to vercel|netlify|cloudflare` from the
-   folder: the host's own sign-in, the `BCMS_*` variables set there, and the rebuild hook
-   registered (`publish-hook`). A front end that revalidates instead: `set_front_end
-   { revalidation }`. Then `derive` again, so the gate measures what ships: on headless, every
-   gate fix that says rebuild means deploy, then derive.
-6. **Open it from BetterCMS.** `set_front_end { siteUrl, framework }` with the deployed URL
-   (`preview`); editors' "Preview on site" opens drafts there.
-7. **Publish**, then get_next_steps until `receipt.complete` is true. Schema and content work is
-   the same as on any project ([content-modeling.md](content-modeling.md)).
+---
+title: "Getting started"
+description: "Set up or resume a BetterCMS project: connect the MCP, pick or create the project, import or build the site, then publish and verify; the resume check for 'Continue BetterCMS setup'."
+---
+
+# Getting started on a BetterCMS project
+
+The dashboard's launcher prompt points here. Its **Context** block holds what the dashboard
+already knows: project name and id, framework, source repo, and the job. Trust it, and ask only
+for what it leaves out.
+
+## Communication style
+
+Be succinct. Say what you did ("Converted 12 routes; 3 values still unmatched on /pricing") and
+skip narrating what you are about to do. Give numbers, not adjectives. Finish the setup in this
+run: do not stop to ask anything the sections below give an answer for.
+
+**RESUME TRIGGER.** On "Continue BetterCMS setup", read `get_project`, `get_next_steps` and
+`get_binding_report` for the project and the gap ledger at `.bettercms/ledger.json` if it exists,
+find the first phase below whose check is not met, say which one in one line, and resume there.
+Never redo a phase whose check already holds.
+
+## An existing site (imported from GitHub or a ZIP)
+
+### Phase 1 — Connect and confirm
+
+Check: the MCP answers for this project id, and this folder is its repo.
+
+1. Read the Connecting section of SKILL.md before your first tool call: a first-call 401 is the
+   sign-in, and a project missing from `list_projects` means the wrong workspace.
+2. `get_project` with the id from Context. Pass `projectId` on every project tool.
+3. Confirm this folder holds the site's `package.json` and source. If it does not:
+   - No repo on disk yet: clone it with `npx @bettercms-ai/cli@latest init --project-id <id>`
+     in the folder where the repo should live. It signs in, clones or downloads the source into
+     a new folder (named for the project unless you pass `--dir <path>`), installs dependencies,
+     pre-fills `.env`, and sets up these skills and the hosted MCP in the user's editors
+     (`npx -y @bettercms-ai/install@latest --global --mcp`). If it warned that the agent setup
+     failed, run the command the warning prints, inside the clone.
+   - Either way, stop and ask the user to restart you **inside** the repo folder: an MCP entry
+     added while you run loads only when the agent starts, and every step below works on that
+     folder's source. Not when `init` launched you: you already run there, connected.
+
+### Phase 2 — No questions: the defaults are recorded
+
+Nothing here is asked. Record and report:
+
+1. **Authoring**: components. A deploy, a promote and every `editor_setup` record it when nothing
+   is set; call `set_authoring_preference` only if the prompt you were started with names `fields`.
+2. **Media delivery**: the BetterCMS CDN, the project's default. Leave it.
+3. **Git**: the prompt you were started with says whether you may push. Follow it; never ask.
+
+Everything else has a default too. Do not ask about it; decide, then report what you decided:
+
+- **Scope is the whole site**: every page, section, heading, paragraph, list item, link and image
+  the site renders. Not the home page first, not "the main copy".
+- **Sections, their names and componentizing**: [components.md](components.md).
+- **Collections vs singletons**: [content-modeling.md](content-modeling.md).
+- **Field types and rich text**: [portable-text.md](portable-text.md).
+
+### Phase 3 — Convert and componentize
+
+Check: `editor_setup { check: true }` reads `ready`, `get_next_steps` returns
+`receipt.complete: true` and `get_componentize_plan` proposes nothing more. Where the job was to
+convert the source, `submit_conversion_receipt` also returned complete.
+
+0. A build brings in only SEO and meta, media, the brand and the models `bcms-content.json`
+   declares. Pages, collections, forms, bindings and components come from `editor_setup`: run it
+   and poll `editor_setup { check: true }` until `ready` before anything below. Run it again
+   whenever `get_deploy_status` reports `editorSetup` `stale`: a re-run flags the auto fields the
+   build no longer renders `stale` (hidden in the editor, never deleted) and never one a person edited, so never delete those by hand. It also fills missing meta from the
+   page copy, merges identical components and switches to declared bindings when the build proves
+   them; the receipt stays yours (it is the codemod's account of your repo).
+1. Explore the repo (the "Read when" column of SKILL.md's reference table names the signals) and
+   read `get_site_composition`.
+2. If `list_env_vars` reports `missing` variables, run `npx @bettercms-ai/cli@latest env push`
+   in the repository: it sets them from the user's own .env files without the values passing
+   through you. If they are not found there and the site loads its content from another CMS,
+   move that content into BetterCMS ([external-content.md](external-content.md)). Never ask the
+   user for a key or read one: a site left depending on missing keys renders empty or crashes.
+3. Work from `get_next_steps`: run `receipt.gate.nextAction`, read it again after each batch, and
+   repeat until `receipt.complete` is true. On a site set up from its build that gate is the only
+   finish line. Run the `convert_site` prompt only when the job is to convert the source (the gate
+   asks for it, the owner wants the code to declare its bindings, or the project is headless), and
+   then to its own complete receipt, never a partial one.
+4. With components recorded: `get_componentize_plan`, then apply it with
+   `componentize_sections` (the owner can undo it), then the repository half (`componentize_sections { codemod: true }`
+   when there is no checkout) and `submit_componentize_receipt` ([componentize.md](componentize.md)).
+5. Work the rest through [finish-site.md](finish-site.md) (gap ledger, repair order, proof loop).
+   The gate's `sections` and `style` rows are part of it: a setup whose pages cannot take a new
+   section, a new order or spacing is not finished.
+6. End Phase 3 on the editor chrome of every component (step 8 of finish-site.md's repair order,
+   [editor-chrome.md](editor-chrome.md)): the gate's `dock` row blocks until each has its V2 `ui`.
+
+### Phase 4 — Publish and verify
+
+Check: the deployed site passes the numbers below on every route.
+
+1. Deploy the way this project deploys: `deploy_project` on BetterCMS hosting; on a headless
+   project, push to the repo its host builds (never `deploy_project` there).
+2. `get_next_steps` reading `receipt.complete: true` is the finish line. `get_binding_report`
+   says why a route is short of it: `unaddressable` below 2% on each route, and, on a source you
+   converted, zero unmatched and an empty `coverage.pending`. `refreshReason: "never-generated"` on headless means
+   fetch the live site instead.
+3. Run the verify loop in SKILL.md against the live URL, then the two-path smoke test (click
+   through to a detail page, clean console, direct reload) in [frameworks.md](frameworks.md)
+   Verify step 5.
+4. Send a coverage report with its denominators, per route: values bound out of values found
+   (bound + unmatched), unaddressable text out of visible text, and routes converted out of
+   `builtRoutes`. A percentage with no denominator is not a report.
+5. Anything only the dashboard can do: name the exact click.
+
+## A new site (nothing built yet)
+
+1. Phase 1 above, then ask the authoring question (`set_authoring_preference`) before any schema
+   write.
+2. Read `bettercms://playbook/schema`. Plan routes and collections first
+   ([site-blueprints.md](site-blueprints.md)), then build sections ([components.md](components.md)).
+3. When a repo exists, clone it with the `init` command above, restart inside it, and continue
+   from Phase 3.
+
+## A headless project (its own front end)
+
+`get_project` says `hostingMode: "headless"`: BetterCMS never builds this site, its own host does.
+Done is `receipt.frontEnd` closed AND `receipt.gate` complete in get_next_steps: BetterCMS derived
+the owner's pages, their code reads the content, the front end has its site URL and rebuilds on
+publish. Work the rows in order; never `deploy_project` or `deploy_to_host`.
+
+1. **Launched by `bettercms init`** (`--agent claude|codex|opencode|cursor|gemini`): you run in the
+   owner's own front end, already connected. Do not ask to be restarted. **Their code, design and
+   copy ARE the site:** keep every component, route, class, style and asset; never redesign a page,
+   rebuild one from scratch or swap their components for new ones. A starter is only ever the
+   starting point when the owner chose one (`init --framework`).
+2. **Derive** (`derive` row). `npx @bettercms-ai/cli@latest derive` in the front end's folder builds
+   the site, renders every page as a visitor sees it and sends the pages to BetterCMS, which derives
+   their pages, fields and today's copy exactly as from a build it made. init runs it first; run it
+   yourself while the row is open. Never model those pages again.
+3. **Convert in place** (`receipt.gate`, the same gate as any built site). `get_conversion_brief
+   { complete: true }`, the convert codemod over this folder (its command is in
+   `bettercms://playbook/schema` §13), then `submit_conversion_receipt` with the receipt it wrote:
+   each literal becomes a read of its field with the markup byte-identical. Bind what it leaves pending by hand the same way. Then
+   start the build script with it, `"build": "bettercms pull-content && next build"`
+   (`@bettercms-ai/cli` a devDependency; not a `prebuild` hook, which Yarn and pnpm skip): the
+   converted pages read `bcms-content/*.json`, which only that step writes on the host's build.
+4. **Wire and read.** `.env` gets `BCMS_API_URL`, `BCMS_WORKSPACE` and `BCMS_PROJECT_ID` (from
+   `get_project`); published content needs no key. A starter whose config reads a key gets one
+   from `create_delivery_key` (`scope: "published"`), written straight into `.env`, never into
+   chat or a commit. Run the app and load a page: its first read closes `read`.
+5. **Deploy.** `npx @bettercms-ai/cli@latest deploy --to vercel|netlify|cloudflare` from the
+   folder: the host's own sign-in, the `BCMS_*` variables set there, and the rebuild hook
+   registered (`publish-hook`). A front end that revalidates instead: `set_front_end
+   { revalidation }`. Then `derive` again, so the gate measures what ships: on headless, every
+   gate fix that says rebuild means deploy, then derive.
+6. **Open it from BetterCMS.** `set_front_end { siteUrl, framework }` with the deployed URL
+   (`preview`); editors' "Preview on site" opens drafts there.
+7. **Publish**, then get_next_steps until `receipt.complete` is true. Schema and content work is
+   the same as on any project ([content-modeling.md](content-modeling.md)).