@bettercms-ai/mcp 0.63.1 → 0.64.0

package/dist/skills/bettercms/references/finish-site.md

@@ -0,0 +1,123 @@
+---
+title: "Finish an imported site"
+description: "Take an imported or converted site to fully editable: the gap ledger in .bettercms/ledger.json, the repair order, and the proof loop per route."
+---
+
+# Finish an imported or converted site
+
+**Outcome.** Every intended value editable, sections reusable, design faithful, and launch
+verified with evidence. "Fully editable" is a measured result, never an inference from imported
+schemas. New to the project, or no repo on disk yet: [getting-started.md](getting-started.md).
+
+## Inputs and baseline
+
+Require the project, source repository or import snapshot, site URL, import manifest, hosting
+mode and the user's goal. Confirm the bound project with `get_project` (hosting mode,
+`authoringPreference`), read `bettercms://playbook/schema`, and inspect the repository and the
+previous import report. If any are unavailable, continue with a read-only gap analysis and name
+the missing evidence.
+
+Capture a baseline before editing: routes, screenshots at representative widths, content model
+and entry counts, component and global-layout inventory (`get_site_composition`, `get_layout`),
+media and form inventory, `list_seo_issues`, `get_deploy_status`, `get_binding_report`, and the
+source commit. Keep existing URLs and behaviour unless the user asked for a change.
+
+## The finish line for a convert or build job
+
+A conversion is done only when the `convert_site` prompt's loop is: `submit_conversion_receipt`
+answers `complete: true` (no path left in `paths.pending`), and after the deploy
+`get_binding_report` shows `unmatched` at 0, `coverage.pending` empty and, once
+`set_binding_mode` has flipped the site to declared and a second release has run, mode
+`declared`. A build job works from `bettercms://playbook/schema` (the `build_site` prompt carries
+the same flow on a local MCP) and is done when the site is deployed, `get_component_readiness`
+is clean for every component it placed, and `get_next_steps` lists nothing left to do from code.
+Both end in the verify loop of SKILL.md. One converted page, or a receipt with paths still
+pending, is not a finished site; report the numbers, not an impression.
+
+Git belongs to the owner. Verification releases go out from the working tree, so the job never
+needs a commit to prove itself. After the final report, ask whether they want the changes
+committed and pushed, committed only, or left uncommitted, and mention that an unpushed
+conversion is lost on the next rebuild from their repository.
+
+## The gap ledger: `.bettercms/ledger.json`
+
+Keep the ledger as a file in the repo, not in chat: it survives a context reset, a new session
+and a second agent, and "Continue BetterCMS setup" re-reads it. It holds no secrets. One row per
+actionable gap:
+
+| Field | Meaning |
+|---|---|
+| `id`, `category`, `severity` | Stable issue identity and priority |
+| `route`, `sourcePath`, `cmsId` | Where the issue lives |
+| `expected`, `observed` | Evidence, not a vague opinion |
+| `repair`, `owner`, `status` | Planned action and accountable party |
+| `verification` | Link, receipt or screenshot proving the fix |
+
+```json
+{ "projectId": "…", "updatedAt": "…", "gaps": [
+  { "id": "pricing-cta-href", "category": "bindings", "severity": "high", "route": "/pricing",
+    "sourcePath": "src/components/Cta.astro", "cmsId": null,
+    "expected": "CTA href editable", "observed": "hard-coded href", "repair": "bind via data-bcms-props",
+    "owner": "agent", "status": "open", "verification": null } ] }
+```
+
+Statuses: `open`, `in-progress`, `verified`, `requires-decision`, `blocked-by-platform`,
+`excluded` (with a reason). Never erase a gap after a failed repair: keep the prior observation
+and add the new result. Update the file as each row moves, so a reset loses at most one row.
+
+## Repair order, and the reference for each step
+
+| # | Step | Reference |
+|---|---|---|
+| 1 | Routing and data shape: page / collection / entry classification and folders; keep public URLs | [content-modeling.md](content-modeling.md) |
+| 2 | Sections and reuse: every band a section; dedupe compatible patterns into variants and overrides; nav and footer as globals (`get_componentize_plan`, `componentize_sections` on a components project) | [components.md](components.md), [componentize.md](componentize.md) |
+| 3 | Editor contract: field types, labels, validation, Portable Text accept lists, nested groups | [portable-text.md](portable-text.md) |
+| 4 | Design: media, logo roles, fonts and brand tokens, without changing visual intent | [media-and-brand.md](media-and-brand.md) |
+| 5 | Bindings: the site reads BetterCMS data and each intended leaf or attribute is bound; build, preview and runtime agree | [bindings.md](bindings.md), [frameworks.md](frameworks.md) |
+| 6 | Behaviour: forms, links, menus, accordions, modals, consent, custom code | [forms-and-interactions.md](forms-and-interactions.md) |
+| 7 | Discoverability: native SEO, structured data, robots and sitemap, redirects, internal links | [seo.md](seo.md) |
+
+Load the step's reference when the step starts, and let it go when the step's rows are verified.
+
+## Proof loop
+
+For each route class and component family, test one safe draft edit for every field class:
+plain text, rich text, image, alt text, link, repeatable group, component slot, and form
+reference where present. Confirm the correct element changes in preview and other instances do
+not change by accident. Restore test values. Verify a default change reaches only instances
+without an override.
+
+Build with the repository's own build script. Fetch live or staging URLs and check HTTP status
+and the rendered copy, not dashboard status. Check responsive screenshots, keyboard use, form
+status, assets, SEO output and broken links. Record the freshness of `get_site_composition`,
+`get_binding_report` and `list_seo_issues`: a binding report whose `refreshReason` is
+never-generated or outdated is not proof, and on a headless site no BetterCMS release ever
+writes one. Per-route checks fan out well to subagents; have each return its verdict and the
+failing evidence only.
+
+**Coverage:** `verified intended fields / discovered intended fields`, plus route, section, asset
+and form counts. A gap is excluded only with a reason, and 100% is never reported while
+exclusions hide core editorial content.
+
+Cases that must be tested:
+
+- A hero repeated on two pages: one instance override changes only one page; a definition
+  default changes the other.
+- A collection detail template with at least two entries and an entry-specific image and SEO
+  value.
+- Long and empty copy at desktop and mobile widths.
+- A rich-text custom block, a missing asset, a broken internal link, and a form with an
+  unverified destination.
+- A component whose CMS field saves while hard-coded source still renders.
+
+## Launch decision
+
+1. **Completed:** the routes and components repaired, with evidence.
+2. **Remaining:** gaps that need a product change, an integration credential, a licence
+   decision, an editor decision or a manual approval.
+3. **Recommendation:** ready, ready with named non-critical exceptions, or not ready, with
+   reasons and the rollback point.
+
+A clean draft audit is not the user's publish authorization. On headless, verify the external
+host's deployed code and content; on managed and hybrid, verify the release with
+`get_deploy_status` and a cache-busted public response ([publishing.md](publishing.md)).

package/dist/skills/bettercms/references/forms-and-interactions.md

@@ -0,0 +1,203 @@
+---
+title: "Forms and interactions"
+description: "Attaching, publishing and verifying forms, and interactive sections: menus, accordions, modals and consent."
+---
+
+# Forms and interactive components
+
+**Outcome.** Interactive sections keep working after componentization, and editors change the
+intended content without touching unsafe implementation controls.
+
+Doctrine: `new_form` prompt, `CM-72`. Component props and slots: [components.md](components.md)
+(its §1 shows where a `form` prop actually renders).
+
+## Contents
+
+- [Inventory behaviour](#inventory-behaviour) · [Pattern contracts](#pattern-contracts)
+- [Forms: the rules](#forms-the-rules) · [Editor UX](#editor-ux) · [Acceptance](#acceptance)
+- Forms as code: [pipeline](#1-pipeline) · [field types](#2-field-types-and-server-checks) ·
+  [MCP versus dashboard](#3-mcp-versus-dashboard) · [self-hosted wiring](#4-wiring-a-self-hosted-site) ·
+  [per-rung facts](#5-per-rung-facts) · [traps](#6-traps)
+
+## Inventory behaviour
+
+For each interaction record its markup, state management, dependencies, events, destinations,
+responsive behaviour, accessibility semantics and persistence. Then sort what it exposes:
+
+- **Content-configurable:** labels, headings, body, images, links, items, variants.
+- **Behaviour-configurable:** a closed choice such as initial open state, autoplay, modal
+  size, display frequency, or which form.
+- **Code-owned:** search algorithms, authentication, payments, booking, complex validation,
+  server actions, experiments.
+
+Code-owned behaviour never becomes a free text field, and never a promise that editors can
+change it safely.
+
+## Pattern contracts
+
+| Pattern | Editor model | Runtime checks |
+|---|---|---|
+| Navigation / mobile menu | global layout component; repeatable link groups; logo; explicit CTA | keyboard and touch, focus return, active route, breakpoint, skip link |
+| Accordion / FAQ | one section with a repeatable Question + narrowed rich-text Answer | button trigger, `aria-expanded`, panel association, focus, single or multi open |
+| Tabs | repeatable label + panel, or a nested component per panel when layouts differ | stable ids, arrow-key navigation, selected state, responsive fallback |
+| Modal / dialog | trigger + modal content in a slot or section; size as a variant | focus trap, Escape, focus return, scroll lock, accessible name, reduced motion |
+| Pop-up / promo bar | sitewide or page component; message, CTA, variant, closed display rules | frequency and dismiss persistence, mobile layout, consent |
+| Carousel | repeatable items or nested slides; limited motion controls | pause, keyboard, announcements, reduced motion, no hidden content loss |
+| Cookie consent | global component with policy links and category labels | consent storage, script gating, change-choice path; legal settings need owner review |
+| Search / filter | labels and options editable; query and index logic code-owned | empty, loading and error states, URL state, keyboard, result accuracy |
+
+For a complex one-off component, keep the working code and expose only an intentional prop
+contract. A nested child is edited through a `slot` prop or its own instance; the edit must
+address the child instance, never the parent definition. A `slot` holds exactly one nested
+component; for several heterogeneous children use the section's ordered children. Prevent
+circular nesting.
+
+## Forms: the rules
+
+Detect each form's fields, labels, types, required states, validation, consent copy, spam
+controls, endpoint, uploads, confirmation and error states, notifications and integrations.
+
+- **A form is a Form document, and a section references it.** Create it as a draft
+  (`create_form`) and place it with a `form` block `{ formId }` inside a section. To make WHICH
+  form editable per placement, declare a `form` prop on the component targeting that block's
+  `props`. The prop stores `{ formId }` and nothing else: never re-model the questions as
+  component props, or the same fields live in two places and drift at the first edit.
+- **Draft until published.** A draft form renders nothing live and every public submission is
+  refused with 403. Publish it with `publish_form` (it needs the publish permission) only after
+  its destination and consent behaviour are tested.
+- **Spam controls** are per form: Turnstile on or off and a honeypot field name. The Turnstile
+  secret key is dashboard-only.
+- **Self-hosted renderers** render only forms whose `status` is `"published"` and post to
+  `${apiUrl}/api/v1/forms/public/:formId/submissions` through the SDK's `submitForm`, never to the
+  forms worker directly and never with an API key in the browser.
+- **Integrations** are configured in the dashboard. A submission classified as spam is stored
+  and triggers none of them.
+
+Classify each form:
+
+1. **Native:** BetterCMS owns fields, validation, submissions and delivery.
+2. **Connected provider:** BetterCMS owns the presentation or the reference; a provider owns
+   delivery. Keep provider ids; the owner sets up the credentials.
+3. **Custom action:** keep the existing code path until an adapter passes the same tests.
+
+A form rendering is not a working integration. Require a test submission that shows the
+expected record (`list_form_submissions`), the notification, the failure state, spam handling
+and consent handling.
+
+## Editor UX
+
+Label fields the way editors think: `Question`, `Answer`, `Add FAQ item`; `Open modal`,
+`Modal title`, `Modal body`, `Close label`. CSS selectors, callbacks, endpoint URLs and secret
+keys stay out of editor fields. Expose curated variants and behaviour switches whose effect is
+obvious. An empty optional field should remove its element cleanly.
+
+## Acceptance
+
+- Interactions work with keyboard, touch, screen-reader semantics, mobile layouts and reduced
+  motion where relevant.
+- Editing a label, body or item changes the intended instance without breaking its state.
+- Nested elements keep their order, ids and edit scope.
+- Every form is `draft`, `ready for verification` or `verified live`; only the last has an
+  end-to-end submission receipt.
+- Consent-dependent scripts do not run before consent is given.
+
+## Forms as code
+
+The pipeline with the code that enforces each hop.
+
+### 1. Pipeline
+
+| # | Hop | Code |
+|---|---|---|
+| 1 | Define: `create_form` / `update_form`, or the dashboard. Postgres `forms` row, `status` defaults to `draft` | `packages/db/src/schema/forms.ts:35` |
+| 2 | Publish: `publish_form`, or the dashboard Forms tab. Both need publish permission | `src/routes/management/forms.ts:276`, `src/routes/admin/forms.ts:529`, `:530` |
+| 3 | Place: a `form` block `{ formId }` inside a section | `packages/types/src/block.ts:253`, `:257` |
+| 4 | Render: hosted renderer, Next `BcmsForm`, or Astro `BcmsForm.astro` | `packages/next/src/form.tsx:74` |
+| 5 | Submit: `POST /api/v1/forms/public/:formId/submissions` with `{ data, "cf-turnstile-response"? }` | `src/routes/delivery/forms-public.ts:48`, `src/lib/validation/schemas/forms.ts:297`, `:298` |
+| 6a | Ingress: rate limit per client IP (10), before anything else | `src/routes/delivery/forms-public.ts:61`, `src/lib/forms/submit-gate.ts:23` |
+| 6b | Ingress: form lookup, 404 when missing; draft form, 403 | `src/routes/delivery/forms-public.ts:65`, `:71` |
+| 6c | Ingress: Turnstile; 403 on a failed token; skipped when not configured | `src/routes/delivery/forms-public.ts:80`, `:89` |
+| 6d | Ingress: field validation, 400 `{ code: "FORM_FIELD_INVALID", errors, issues }` | `src/lib/forms/submit-gate.ts:75` |
+| 6e | Ingress: spam classification (honeypot) | `src/lib/forms/spam.ts:40` |
+| 6f | Ingress: rate limit per workspace (100 per 60 s), one bucket shared with the API-key route | `src/lib/forms/submit-gate.ts:80` |
+| 7 | Store: forms worker writes the submission to D1 (`FORMS_DB`); CRM intents to `crm_intents` | `workers/bcms-forms-worker/src/index.ts:2`, `workers/bcms-forms-worker/migrations/0004_crm_intents.sql:1` |
+| 8 | Inbox side effects (non-spam only): contact upsert, integrations, notification | `src/routes/delivery/forms-public.ts:120`, `:144`, `:158` |
+| 9 | CRM delivery drain: `POST /api/v1/internal/crm/drain` | `src/index.ts:976`, `src/routes/internal/crm.ts:4` |
+| 10 | Read: `list_form_submissions`, dashboard inbox | `packages/mcp/src/tools.ts:1600` |
+
+### 2. Field types and server checks
+
+Thirteen types exist (`src/lib/validation/schemas/forms.ts:61`, `:62`, `:65`). No file upload.
+
+| Type | The server checks |
+|---|---|
+| `email` | Address shape; optional `emailPolicy: "business"` rule |
+| `number` | Numeric; optional `min` / `max` rules |
+| `select`, `radio`, `checkboxes` | Value is one of the listed options; a field saved with an empty options list accepts nothing |
+| `consent` | Must be truthy |
+| `phone` | Digits, spaces, `+ ( ) -`; stricter with `phoneFormat: "e164"` |
+| `text` / `textarea` | At most 1000 / 10000 characters; optional `pattern` rule |
+| `url` | Starts with `http://` or `https://` |
+| `date` | `YYYY-MM-DD` |
+| `checkbox`, `hidden` | Nothing beyond `required` |
+
+Any field with `required` is checked for presence. Every value must be a plain value or a flat
+list of them; a nested object is refused with rule `scalar`. Each refusal is
+`FORM_FIELD_INVALID` with `issues: [{ field, rule, message }]`. Keys that are not fields are not
+refused.
+
+The API-key submit route runs the same validation, spam check and workspace limit, but no per-IP
+limit (`src/routes/delivery/forms.ts:106`).
+
+Definition refusals (`create_form` / `update_form`) carry `FORM_DEFINITION_INVALID`: duplicate or
+over-long keys, too many fields or options, and a `showIf` that names a field not on the form.
+That last one is refused on create and kept as sent on update.
+
+Rules:
+
+- Send only the form's field keys (plus the honeypot and Turnstile token), each as a plain value.
+- Read `issues[].field` and `issues[].rule` to fix a refused submission; retrying unchanged returns
+  the same refusal.
+
+### 3. MCP versus dashboard
+
+| Operation | Where |
+|---|---|
+| List, read, create, update, delete forms | MCP: `list_forms`, `get_form`, `create_form`, `update_form`, `delete_form` |
+| Read and delete submissions | MCP: `list_form_submissions`, `delete_form_submission` |
+| Publish | MCP: `publish_form`. Unpublish: dashboard Forms tab |
+| Integrations (Google Sheets, Slack, webhook, email, HubSpot, Salesforce) | Dashboard |
+| Turnstile on/off, honeypot field name, notification emails | MCP: `create_form` / `update_form` (`turnstileEnabled`, `honeypotField`, `notifyEmails`). The Turnstile secret key: dashboard only; sending `turnstileSecretKey` through the API is refused with 403 `FORM_SECRET_DASHBOARD_ONLY` |
+
+`update_form` with `fields` replaces the whole array: send every field you want to keep.
+
+### 4. Wiring a self-hosted site
+
+- **Next**: `getForm('Name')` (or an id) reads the form from `bcms-content.json`; render
+  `<BcmsForm form={form} />`. It renders the honeypot input under the form's own
+  `honeypotField` name, reads the `cf-turnstile-response` token when a Turnstile widget is on the
+  page, and submits through the SDK `submitForm`.
+- **Astro**: `BcmsForm.astro` renders the same hidden honeypot input and sends
+  `cf-turnstile-response` when present.
+- Neither component checks `status`. Render a form only when `form.status === "published"`.
+- The honeypot name is per form. Never hardcode it; read `form.honeypotField`.
+
+### 5. Per-rung facts
+
+| Situation | Answer |
+|---|---|
+| `FORMS_WORKER_URL` set but blank on the API | 503 `FORMS_WORKER_NOT_CONFIGURED`. A blank never falls back to the default worker |
+| Worker without `FORMS_SHARED_SECRET` | 503 `FORMS_WORKER_SECRET_UNSET` on data routes |
+| No Turnstile secret for the form or env | Token not verified; the submission continues |
+| Rate-limit store unavailable | Limits allow the request |
+| Management delete of a submission not in that form | 404 `FORM_SUBMISSION_NOT_FOUND` |
+
+### 6. Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Every submission 403 | Form still draft | Call `publish_form` |
+| Submissions 503 on a dev or preview API | Worker URL blank or worker secret unset | Report the code to the owner; do not change the site |
+| Lead stored but no contact, integration or notification | Classified as spam (honeypot filled); side effects run for inbox leads only | Keep the honeypot input hidden and empty |
+| Submission 400 `FORM_FIELD_INVALID` rule `scalar` | A field value sent as an object | Send plain values; checkboxes as a flat list |
+| Webhook integration never fires | Target is not a public http(s) host | Use a public https endpoint |

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

@@ -0,0 +1,149 @@
+---
+title: "Framework wiring"
+description: "Hosting modes, the env map, TypeGen with bettercms-codegen, value shapes, revalidation tags, the media host, static snapshots and the verify steps shared by every framework."
+---
+
+# Framework wiring, hosting modes and media
+
+Doctrine (what a headless or imported site needs first): §10 and §13 of
+`bettercms://playbook/schema`. This is the code side shared by both adapters. The repo root has
+`astro.config.*`: also read [astro.md](astro.md); `next.config.*`: [next.md](next.md); neither:
+[other-frameworks.md](other-frameworks.md) (`@bettercms-ai/sdk` `createClient`), and classify the
+codebase first ([bindings.md](bindings.md) §6). Read the adapter reference before writing code; env names differ between the two.
+
+## Hosting modes
+
+A project's `hostingMode` is `managed`, `hybrid` or `headless`.
+
+| Mode | Who builds and serves production | Rule |
+|---|---|---|
+| managed | BetterCMS | `deploy_project` / `create_deploy_upload` are the deploy path |
+| hybrid | BetterCMS, and the client also reads content headlessly | Treat exactly like managed for builds and hosting |
+| headless | The client's own host (Vercel, Netlify, Cloudflare Pages) | Never call `deploy_project` or `create_deploy_upload`; never add `bcms-rebuild.yml`. Deploy = push to the repo the host builds |
+
+Headless refusals, by code:
+
+| Code | Cause | Fix |
+|---|---|---|
+| `HEADLESS_NO_BUILD` | A build, release or deploy was sent for a headless project | Stop; push to the provider instead |
+| `HEADLESS_NEEDS_CUSTOM_HOST` | GitHub connect without a provider host | Add Vercel, Netlify or Cloudflare Pages under Custom hosting in the dashboard, then connect |
+| `HEADLESS_ARTIFACT_TARGET` | The custom host expects builds from BetterCMS | Switch the host to build from the repo |
+
+**Server rendering is one change across four systems, or none.** An SSR build (`output: 'server'`
+with `@astrojs/node`) emits `dist/client` + `dist/server` and no `index.html` at the root. A
+managed project serves that from its build directory only when the Hosting page is set to
+**Run as a server app** — a dashboard setting no tool can change. Until it is set, the server never
+runs: only prerendered pages and assets are served, and every other route answers 404 while the
+build, the release and `get_deploy_status` read green. The deploy workflow refuses an SSR build
+pointed to by `BCMS_BUILD_DIR` (`STATIC_HOST_GOT_SSR_ARTIFACT`) and warns when it packages one it
+found itself. So: switch Hosting first (ask the owner), then ship the build, then fetch the URL.
+
+## Env map
+
+| Package | Variable | Purpose |
+|---|---|---|
+| `@bettercms-ai/astro` | `PUBLIC_BCMS_API_URL`, `PUBLIC_BCMS_WORKSPACE`, `PUBLIC_BCMS_PROJECT_ID` | Where reads go |
+| `@bettercms-ai/astro` | `PUBLIC_BCMS_MEDIA_URL`, `PUBLIC_BCMS_STUDIO_URL` | Media host, editor origin |
+| `@bettercms-ai/astro` | `BCMS_API_KEY`, `BCMS_DRAFT_SECRET` | Server-only key; draft cookie signing |
+| `@bettercms-ai/next` (snapshot bin) | `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE` | Pull `bcms-content.json` |
+| `@bettercms-ai/next` | `BETTERCMS_PREVIEW=1` | Read live instead of the snapshot in a preview build |
+| `@bettercms-ai/codegen` | `BETTERCMS_API_URL`, `BETTERCMS_API_KEY` | Fetch models for typegen |
+| `@bettercms-ai/mcp` | `BETTERCMS_API_URL` | A rung name `prod`, `dev`, `local`, or a full URL |
+
+Rule: Astro names start `PUBLIC_BCMS_`/`BCMS_`; Next and codegen names start `BETTERCMS_`. Never
+copy one adapter's `.env` into the other. Keys never go in a `PUBLIC_` variable.
+
+## Types
+
+Run `bettercms-codegen` after every model or field change and commit the generated file. Why:
+templates typed against an old schema compile and then read `undefined` for a renamed field.
+
+1. **Generate into the compiled tree:**
+   `npx @bettercms-ai/codegen --out src/bettercms.generated.ts`. The default output is
+   `bettercms.generated.ts` at the repo root, which a `tsconfig.json` whose `include` is `src/**`
+   never type-checks. `--bindings-out <path>` also writes the Live Preview bindings module,
+   `--components-out <path>` typed React `RichText`/`Image` components.
+2. **Auth:** `BETTERCMS_API_KEY` (or `--key`) must be a management key; `BETTERCMS_API_URL` (or
+   `--api-url`) picks the rung. The key is a secret: a CI secret or a local `.env` that git
+   ignores, never a `PUBLIC_` variable.
+3. **Commit, and let CI check.** Output is sorted and byte-stable, so a committed file diffs
+   cleanly. In CI, run the same command, then `git diff --exit-code` on the file: a failure means
+   the schema moved and nobody regenerated. Generating only in CI (not committed) also works, but
+   then every local typecheck needs the key.
+4. **Never edit the file by hand**; it says so in its header, and the next run overwrites it.
+5. **Without a key** (an agent session, a quick check), `get_content_types` returns the same
+   generated types over the MCP. Paste them only as a stopgap; the CLI is the repeatable path.
+
+## Value shapes templates read
+
+- **Richtext**: `{ format, value, html }`. Render `value` (Portable Text) or `html`; write rules
+  are in [portable-text.md](portable-text.md).
+- **Image**: an object `{ id, url, name, altText }`. Read `.url` and `.altText`, never treat the
+  field as a string.
+- **Repeater / zoned array**: stored as `{ repeatable: [...] }`. Read `field.repeatable`, not
+  `field` as an array. A bare array written to such a field is wrapped on write.
+
+## Revalidation
+
+- On publish BetterCMS sends a webhook signed with `X-BetterCMS-Signature` (HMAC-SHA256 of the raw
+  body, using the webhook secret configured on the project in the dashboard).
+- The backend invalidates tags `bcms:{workspaceSlug}:all` and `bcms:{workspaceSlug}:{type}:{slug}`.
+  The SDK tags reads `bcms:{workspace}:{resource}:{id}`.
+- Rule: tag every cached read with those exact strings. A tag you invent (`post:${slug}`) is never
+  revalidated and the page stays stale until the cache window expires.
+
+## Media host
+
+A stored image value is `{ id, url, name, altText }`. `url` is absolute and already right for the
+plan: platform CDN, API origin, or the project's own CDN base. Rendering `url` as-is works on
+every plan.
+
+Resized images are a second lane. `@bettercms-ai/image-url` and `BcmsImage.astro` mint
+`<mediaUrl>/media/<id>?w=…`, and the backend serves that for every plan, including a project that
+keeps media in its own bucket.
+
+- Hand the builder the asset object or its `id`, never the `url` string. A URL with no `/media/`
+  segment (own-bucket plan) resolves its last path segment as the id and 404s.
+- `mediaUrl` is the origin that owns the asset ids: `mediaBaseUrl` from `get_project`, always.
+  The package default is right only when `mediaBaseUrl` is the production CDN; any other value —
+  the API origin, another rung — goes in `PUBLIC_BCMS_MEDIA_URL`. On a backend too old to return
+  `mediaBaseUrl`, read one `get_media` url: if it contains `/media/`, its origin is the value; if
+  it does not (own bucket), use this project's API URL.
+- `set_media_delivery` changes future mints only, and only between the CDN and the API origin;
+  stored URLs keep resolving. It is the owner's call. After it, set `PUBLIC_BCMS_MEDIA_URL` to the
+  same origin.
+- A stored `url` that itself answers 404 is storage or the wrong rung, not the template. Report
+  it; never rewrite URLs in content.
+- A media host from another project, a document or the conversation is never a value for
+  `mediaUrl`.
+
+## Static builds
+
+A static build reads content from the `bcms-content.json` snapshot. Produce the snapshot before
+the build, every build. Details per adapter are in the references.
+
+Producing it is half the job. A source file must READ it — `readPages`, `getEntry`, or the
+generated reader. A build that fetches the snapshot and never reads it still renders the
+hard-coded copy, so every edit saves, publishes and changes nothing on the page. Grep the source
+for a reader before calling a site wired.
+
+Build with the repo's own `build` script (`pnpm build`, `bun run build`), never the framework CLI
+directly: a repo's script often adds a type check or a post-process step the CLI skips.
+
+## Verify
+
+1. Fetch the live URL, cache-busted, and confirm a 200 whose body contains copy you just
+   published. Every other check below is a control-plane read and can be green on a dead site.
+2. The site builds with the snapshot present and renders published content.
+3. Publish a small change; the page updates (revalidation reached the right tag) or the host
+   rebuilds (headless). Editable means that round trip was shown, not that fields exist.
+4. `get_binding_report` for a changed route: `coverage.pending` empty. `refreshReason:
+   never-generated` means no BetterCMS release wrote one — on a headless site it never will, so
+   step 1 is the proof there. `outdated` means the report predates the current shape; the next
+   release rewrites it.
+5. **Smoke-test both render paths** on the dev server or a preview deploy: load a list page,
+   click through to a detail page with the site's own link (never paste the URL), and read the
+   browser console: clean, no `ReferenceError`, no hard reload to `/`. Then reload that detail
+   page from the URL bar. Why: a client-side route transition loads lazy chunks that read env and
+   the snapshot through a different code path than the server render, and that is where a
+   missing public variable or a server-only import surfaces.

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

@@ -0,0 +1,106 @@
+---
+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"), ask
+direct questions, and skip narrating what you are about to do. Give numbers, not adjectives.
+
+Before starting, tell the user they can pause and resume anytime by saying
+**"Continue BetterCMS setup"**.
+
+**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.
+
+### Phase 2 — The questions the MCP requires, and no others
+
+Check: `get_project` shows `authoringPreference` set and the user has answered media delivery.
+
+Ask exactly these two, each through its tool, and never answer them yourself:
+
+1. **Authoring**: `set_authoring_preference` (components or fields). Recommend components for a
+   marketing site. It is asked once per project and can be re-answered.
+2. **Media delivery**: `set_media_delivery` (the BetterCMS CDN, recommended, or the API origin).
+
+Everything else has a default. 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: `submit_conversion_receipt` returned complete and `get_componentize_plan` proposes
+nothing more.
+
+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. Run the `convert_site` prompt end to end. Its finish line is the only one; repeat until the
+   receipt is complete, never stop at a partial one.
+4. When the answer was components: `get_componentize_plan`, confirm it with the user, apply it
+   with `componentize_sections`, then the repository half 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).
+
+### 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_binding_report` is the finish line: zero unmatched, an empty `coverage.pending`, and
+   `unaddressable` below 2% on each route. `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.