@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/content-modeling.md

@@ -1,382 +1,382 @@
----
-title: "Structure and content modeling"
-description: "Pages vs collections, the four folder layers, field decisions and naming, and changing a schema safely, including retiring a field in stages."
----
-
-# Structure and content modeling
-
-**Outcome.** A content tree an editor understands on day one, durable relationships between
-records, no accidental URL change, and model changes that every consuming site builds against.
-
-Doctrine: §1–§5 and §14 of `bettercms://playbook/schema` (schema shape and sections) and
-`bettercms://playbook/structure` (sidebar); flow: `propose_schema` prompt; rule ids
-`CM-10`…`CM-14`, `CM-40`…`CM-44`. What the server does and does not check on a write:
-[write-limits.md](write-limits.md). Planning a whole site by business type:
-[site-blueprints.md](site-blueprints.md).
-
-## Contents
-
-1. Read the site before modeling
-2. Pages, collections and entries (thresholds, promoting items to a collection)
-3. Four structure layers, four meanings
-4. Field decisions (references, lists, listings, the `document` body, buttons)
-5. Editor labels and order (when to write help text)
-6. Changing a schema safely
-7. Reading a schema written in the V2 language (field type map, glossary)
-
-## 1. Read the site before modeling
-
-Inventory route files and rendered routes, source data schemas, repeated records, page templates,
-navigation, taxonomies, authors, tags, media references, SEO, forms, locales and publishing
-states. Compare with the project's pages, collections and entries (`list_pages`,
-`list_content_models`, `get_content_structure`). Note where a value is shared, where it is an
-instance override, and where one entry owns it outright.
-
-## 2. Pages, collections and entries
-
-A page is `singleton` (one page and its own content: home, about, a legal page) or `dynamic`
-(one template page whose collection entries each render at the page's path plus the entry slug).
-Choose by repetition: a shape that repeats per item is a collection; a one-off is a singleton,
-even when it lists items, because the list page reads the collection. A dynamic page is its
-collection: the model and its entries both point at the page (`content_models.page_id`,
-`content_entries.page_id`), so never create a separate page per entry. A dynamic page made with
-`create_page` takes its route pattern and its collection through `update_page { dynamic:
-{ previewPath, modelId } }`: `/blog/{slug}`, and an existing collection with no page yet.
-
-A listing elsewhere (latest posts on home, related posts on an article) is a `collection` block
-with `source: { modelId }`, never copied entries. It also takes `filters` (max 5, `{ field, op,
-value }` with the content API operators), `sort` (`-publishedAt,title`), `pinnedIds` (max 10,
-shown first), `excludeCurrent` and `limit` (default 20), beside `order` (`newest` or `oldest`) and
-`emptyText`. `cardComponentId` names the component each card is drawn through; without one a card
-shows the entry's `titleField` (default `title`) and `excerptField`. On a `dynamic` page the block
-lists that page's collection and draws ONE entry on `/<page>/<entrySlug>`, through
-`detailComponentId` when set. BetterCMS-rendered pages read it on every request;
-a route the repo builds does not draw this block, so list there with the content API.
-
-| Source pattern | BetterCMS destination |
-|---|---|
-| Home, about, contact, legal, editorial landing page | Singleton page with its own content |
-| Blog / case-study / product list URL | A list page plus a separate collection |
-| Repeated records sharing one template | One collection and one dynamic detail page |
-| 404, search, gated page | A page that keeps its access and noindex behaviour |
-| Author, category, tag, company reused by entries | A shared collection, referenced from the entries |
-| Data from an external runtime API | Keep the adapter and its owner; never fabricate entries |
-| Sitewide nav, footer, promo bar | Global Layout, never copied page fields |
-
-**Thresholds.** Three or more pages sharing a URL pattern and a card or detail layout are a
-collection. Two are a collection when the set will grow (jobs, case studies). Otherwise they are
-singletons.
-
-**Promote repeater items to a collection** when any one holds; keep them inline when none does
-(pricing bullets, a hero proof line, quotes on a one-off campaign page):
-
-| Signal | Example |
-|---|---|
-| The item has its own URL | A case-study card linking to its detail page |
-| The same item shows on two or more pages | A testimonial on home and on a product page |
-| It carries facts that must not drift between copies | Price, stock, rating, job status, a person's photo |
-| Another entry points at it | A post's author, an event's speaker |
-| Editors will filter, sort or count the items | Jobs by team, events by date |
-
-## 3. Four structure layers, four meanings
-
-Name the layer every time you say "folder". The answer to "where does X live" differs per layer.
-
-1. **Content sidebar folders** organise the dashboard only: nothing here reads or writes a URL,
-   slug, schema, content or publish state. Read with `get_content_structure`, get a proposal from
-   `suggest_content_structure`, apply it whole with `set_content_structure` once the user agrees,
-   or change one thing with `create_folder`, `rename_folder`, `move_to_folder` or `delete_folder`
-   (deleting a folder moves its contents up). `set_content_structure` replaces the whole document:
-   send the `version` you read; a 412 `VERSION_CONFLICT` means someone changed it, so read and
-   re-apply. It refuses duplicate folder ids, a parent not in the doc, a cycle, and nesting deeper
-   than 4. The standard pins the home page and each list page at the top, gives each content
-   family one folder named for its detail type (the list page and its collection are two items),
-   keeps other standalone pages in Pages (Pages › <language> on a multilingual site),
-   taxonomies used by two or more families in
-   Shared, and Settings last. Components are not sidebar items. Whether folders show depends on a
-   dashboard feature flag, so an empty sidebar is not proof the structure is missing.
-2. **URL page folders** are part of a page's path unless set not to be included in it. Renaming
-   or moving one 301s every affected URL and queues a rebuild: a routing change that needs the
-   user's review. They are set in the dashboard, not through the sidebar tools.
-3. **Component groups** (`component_groups`) organise definitions by family or role
-   (Navigation, Hero, CTA, Forms), never by the page that uses them ([components.md](components.md) §8).
-4. **Media library folders** organise assets (`folderId` on `create_media_upload`) and never
-   rewrite a stored content URL.
-
-What reads published structure: the sitemap (skips noindex pages), robots.txt (points at the
-sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item).
-
-## 4. Field decisions
-
-Before designing a section's fields, find the closest component-kit entry: the chooser by
-category and edge tag is [kit-scenarios.md](kit-scenarios.md), the full list is the
-`bettercms://kit` resource and [kit-catalog.md](kit-catalog.md). The entry's notes are the
-field mapping and its pitfalls the review list; the rules below still decide the storage.
-
-- **Model each visual band as a `group` field (or a repeater), or a component instance.** The
-  schema's shape decides whether the site can ever be componentized. The componentize lane finds
-  a section in a `group`, a repeater, or two or more top-level keys sharing a prefix before `-` or
-  `_` (`"hero_title"` + `"hero_subtitle"` → `hero`). A key with NO shared prefix (`title`,
-  `intro`) is a lone scalar, refused `NOT_A_SECTION`. Keep ONE separator per band: a `-` family
-  and a `_` family never share a component. A `group` is the robust choice, and child keys inside
-  it follow the flat-namespace rule (`"hero_title"`).
-- A collection for an entity with its own lifecycle and relationships; a nested group for values
-  one page or section owns.
-- A reference for reusable entities and internal links where the model supports it; an external
-  URL for links that leave the site.
-- **Resolve references before creating anything.** Build the target collection and its entries
-  first, then the model that points at them. Match each source item to an existing entry by
-  stable facts (a slug, a product handle, a name plus the start of the quote) and create only what
-  is missing. Store the entry id, never an href or a title. A write naming a target that does not
-  exist is refused with 400 (ref_missing). Flag an item with no identity (a quote with no name);
-  never import it.
-- A repeater for small, same-shaped items (cards, FAQ rows, links, social accounts); a nested
-  component or slot when an item has its own layout or variants.
-- **Lists are arrays; tags are taxonomy.** Features, steps, benefits and "what's included" are an
-  `array` (`itemType: "text"`), or a repeater when each item carries its own state (included or
-  not, an icon). Never a group holding one field. A label set that filters or classifies entries
-  is a `tags` field; when each label has its own page, a collection referenced with `multi-reference` (§2).
-- **Never freeze a feed.** A list of entries on the source stays a listing: copying the nine
-  visible cards into a repeater stops it updating. On a page BetterCMS renders, that is the
-  `collection` block: on the collection's own dynamic page it lists that collection, and with
-  `source: { modelId }` it lists any collection on any hosted page (§2). It takes `limit` (1 to
-  200), `order` (`newest` or `oldest`) or `sort`, `filters`, `pinnedIds`, `excludeCurrent` and
-  `emptyText`; in an article template a filter value may be `{{field}}` of the entry shown, which
-  is a "related" list. Pagination and grouping stay a query in the site's code. Always set the
-  empty state, never write card titles or images into the listing, and put "read next" on the
-  template once, not on each entry.
-- **`document` is the one long body.** A page schema or a collection may hold it, one at
-  most, and only as a top-level field: a group or a repeater cannot contain it. Label it Body. Short formatted copy stays `richtext`.
-- **Model a call to action as a single `button` field.** It stores `{ label, href }` plus the
-  optional look keys `variant`, `size`, `arrow`, `icon` and `newTab`, and the site draws it with
-  `BcmsButton` ([astro.md](astro.md), [next.md](next.md)). Never a text
-  field beside a link field: the pair has nowhere to keep a look, and a new pair in the importer's
-  spelling (`hero-span-go` + `hero-a-go-href`) is refused with 400 `cta_pair` on `add_field`,
-  `create_page` and model writes. A page that already holds a pair (`primaryCtaText` +
-  `primaryCtaHref`) becomes one button with `update_field` `{ pageId, path: "primaryCtaText",
-  mergeHref: "primaryCtaHref" }`: each entry's DRAFT gets `{ label, href }` and keeps the old values,
-  so code still reading them keeps rendering; the live copy changes on publish. On a route the
-  site's app renders at request time the merge is refused (409 `CODE_RENDERED_ROUTE`): change the
-  code to draw the CTA with `BcmsButton`, and the next build adds the button field. Inside a component
-  a CTA is a `button` block whose `props` one `button` prop targets ([components.md](components.md) §1).
-- A sponsored, untrusted or user-generated link takes `rel` (`nofollow`, `sponsored` or `ugc`) on the
-  button, or a `link` field value written as `{ href, rel?, newTab? }`; code that opts into the object reads `.href`.
-- A `date` field with a time takes `timezone` (`site` or an IANA name such as `Europe/Paris`) in its config;
-  values must then end in `Z` or an offset, and a bracketed zone suffix is dropped on save.
-- Never model SEO columns ([seo.md](seo.md)), Form questions (they live on the Form document) or
-  Global Layout values as content fields.
-- Keep source ids, slugs, locale, status and previous URLs as migration metadata, stable across
-  re-imports.
-- Lock a field whose value another system owns (a store, job board or feed id): `readOnly: "developer"` with a `lockReason`.
-  Only schema access may then change the value or the lock; other writes are refused (403 `FIELD_LOCKED`) unless they send the stored value back.
-- **Prefer a `select` over a `boolean` for a state that may grow** (`draft | review | live`, not
-  `isLive`). Why: no tool retypes a field, so a third state later costs a new field and a value
-  migration (§6).
-- Choose field types before the first write. A `link` accepts any scheme-less href (`/about`,
-  `about.html`, `#section`) and `http(s):`, `mailto:`, `tel:`; every other scheme is refused.
-  Choose the type from what the rendered value is, not habit ([portable-text.md](portable-text.md)).
-
-## 5. Editor labels and order
-
-**Name for meaning, not look.** Before writing a key or label, ask: would the name survive a
-redesign? `ctaText`, `authorBio` and `features` pass; `blueButton`, `leftColumn` and `bigHeading`
-fail, because the next redesign makes them lie.
-
-Short labels named for what the editor sees: Heading, Body, Primary button, Label, Link, Image,
-Alt text — or the name the site's code already uses (`cents` → Cents), never the copy itself
-(`.00`). An import names every field it derives the same way, by its section and its role
-there: "Hero headline", "Hero intro", "Hero primary button", "Pricing plans", "Footer link 2
-URL", "Header logo"; a list's columns by their role in the row ("Title", "Description", "Link
-URL"). A role is numbered only where it repeats in one section, and labels are unique on a page.
-Keys never change. Rename a label where the site's code has a better word: a name you give is
-kept on every later release, and one the import gave follows the import. Most fields need no help line from you (below). Group by what renders
-together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Repeatable items need a meaningful preview label (the FAQ question, the
-button label), reorder, and stable item ids. An empty optional field removes its element without
-leaving a gap; a long value wraps, and clamps only where the design intends it.
-
-### Writing help text
-
-Most fields get no help. The platform writes a line only where one of the four reasons below
-holds and leaves every other element with none, so leaving `helpText` out is the default, not a
-gap. It says so: `helpText: { source: "auto" }` in the response, `helpSource: "auto"` on the
-stored field. Text you send is stored as yours (`helpSource: "agent"`) and is never rewritten;
-`editor_setup` rewrites only its own lines and never a person's.
-
-Ask one question per field: does the editor need this line to type the right value? Write your
-own `helpText` (on a field or a prop) only for one of four reasons, written as one short plain
-sentence under 90 characters, with no semicolon, no dash and no figure taken from the page.
-
-| Reason | Good |
-|---|---|
-| A format or unit the label cannot show | Price in cents. · Length in minutes. · A .vtt caption file. |
-| Where the value shows, when the canvas cannot show it | Shown in search results and link previews. · Read by screen readers, not shown. |
-| A real constraint or consequence | Changing this breaks existing links. · Must be later than the start date. |
-| A fallback | Leave empty to use the page title. |
-
-Everything else is left out:
-
-| Never | Bad | Do instead |
-|---|---|---|
-| The label or the value again | Heading: "The section's main heading." · `e.g. "Starter Kit"` | Nothing. The API refuses help that echoes the value |
-| Coaching the writing | "Keep it short." · "Two to four words works best." · "Start with a verb." | A length is a counter: a number in `config` (`"maxLength": 60`, §6) |
-| An example of the value | Badge: "e.g. Most popular" | A `placeholder` where the control takes one (component props do) |
-| Strategy | Secondary button: "A lower-commitment option that builds trust." | Nothing. The label says which button it is |
-| Internal notes | "Renders as h2." · "Label and link are one unit." · a ticket or decision id | Keep them in the code or the report, never in the form |
-| Generic good practice | "Add alt text for screen readers." on every image | Nothing |
-
-One sentence, plain words, sentence case. If more than about one field in five carries your own
-line, you are over-writing. A component, a collection and a Layout Section (`update-section`)
-still take a `description` that says what the thing is ("Hero with a heading, supporting text,
-two buttons and an image"), never its name again.
-
-`get_next_steps` lists `help-text-missing` for an element the editor setup has not settled yet, or
-one whose line only echoes its label, and `get_binding_report` and `get_site_composition` carry the
-coverage as `help`. The platform writes a line only for the four reasons above and leaves most
-elements with none; clear the finding by running `editor_setup`, or by writing one of the four
-kinds yourself, never with filler.
-
-**Config keys.** Write only the `config` keys a field type documents (`maxLength`, `min`/`max`,
-`options`, `itemType`, `zones`, a rich text's `accept`/`inline`): any other key sends that field to
-the old classic editor. The import's own keys (`attr`, `numeric`, `units`, `band`, `seeded`, …) are the
-server's: both MCP surfaces drop them from what you write.
-
-## 6. Changing a schema safely
-
-A schema write alone is not a release. Before one, read the model with `get_content_model`, a few
-sample entries, the component definitions that touch it and the frontend readers, and write a
-before/after field map: key, type, label, required, default, validation, editor group, and what
-happens to existing values.
-
-1. **Guard concurrent edits.** Pass the model's `optimisticVersion` as `ifMatch` to
-   `update_content_model`. A 409 means it changed since you read it: re-read and re-plan, never
-   resend. Omitted, the last write wins, except on the editor-chrome args, which refuse without
-   it (428).
-2. **Know what the MCP can do.** `add_field` (a model's `modelId` or a page's `pageId`) appends
-   and never overwrites or retypes. `update_field` changes ONE existing field, addressed by a dot
-   path through its groups and repeaters (`hero.title`): its label, help text, `required`,
-   validation `config` (merged by key; null deletes one), `showIf`, `ui` or placement, written at
-   the version it read. A retype needs `allowRetype: true`, because stored values that do not fit
-   the new type are lost; a key rename needs the migration in step 3. `update_content_model` edits
-   the model's name, slug, URL pattern and fieldsets, and removes model fields only with
-   `removeFields` (step 3). The home page cannot be deleted, and changing a local type file is not
-   a schema change.
-3. **Retire or rename a field in stages, never in one write.** Renaming a key re-addresses its
-   content: `update_field` with a new `key` is refused with 409 and the count of entries holding
-   the old key, unless `allowFieldRemoval: true` discards their values. So a rename is a new field
-   plus a migration:
-   1. Relabel the old field "Old title (Deprecated)" and set help text naming its replacement
-      (`update_field` `label` and `helpText`).
-   2. Move it into a `collapsed: true` fieldset so editors stop reaching for it
-      ([editor-chrome.md](editor-chrome.md) §2).
-   3. Add the replacement (`add_field`, with `modelId` or `pageId`) with the final type and name.
-   4. Migrate values in code, draft first, and have the frontend read the new key.
-   5. Remove the old one. Page fields: `remove_page_fields` (dry run by default) returns
-      `keysWithContent` and writes nothing; read it, then run it with `dryRun: false` and
-      `discardContent: true` only for keys you migrated. Model fields: `update_content_model` with
-      `removeFields: ["oldKey"]` and `allowFieldRemoval: true`, sent with the `ifMatch` of your
-      read. It has NO dry run and discards that key's value in every entry, so count the entries
-      holding it first (`list_content_entries` with `modelId`: `meta.total` is the count, `page`
-      walks past the 200-row `limit`). Top-level keys only; an unknown key refuses the
-      whole call; a page's own fields go through `remove_page_fields`. Both discard data: removal
-      is the last step, with the user's yes.
-   Why: every stage before 5 is reversible, and a site built against the old key keeps rendering
-   until its next release reads the new one.
-4. **Put numeric limits in `config` as numbers** (`"maxLength": 60`), with `update_field` on a
-   field that exists. A numeric string is converted on save; an impossible value is refused with
-   `FIELD_CONFIG_INVALID`.
-5. **Check existing records before tightening validation.** Backfill or give a real default
-   before making a field required; keep a source-to-target map and a snapshot for any high-volume
-   transform.
-6. **Validate on a draft.** Entries written through the MCP pass one write path (request schema,
-   normalisation, per-field checks, uniqueness), and a write failing any step stores nothing.
-   Publishing copies the draft to live, so a draft that passes is the value that ships.
-7. **Change a component family together** (same prop keys and types on every variant;
-   [components.md](components.md) §1 and §3).
-8. **Regenerate types** with `bettercms-codegen` in every consuming site after any model or field
-   change, commit the output if the repo commits it, and run that repo's build and typecheck with
-   the script it already has. Templates typed against an old schema compile and read `undefined`.
-9. **Verify** the editor's grouping and controls, one draft edit per changed field class, the
-   preview binding, the static or headless reading path, and the public output once a release is
-   authorized.
-
-Content models, frontend types, component definitions and live content have separate lifecycles;
-there is no single "deploy schema" action. Production publication stays behind the user's
-authorization and the component readiness and Visual Approval gates.
-
-**Evidence to return:** model and field ids, the version you wrote against, migrated record
-count, codegen and build result, one editor check and one rendered-page check, warnings, and any
-change the platform could not make (an open dependency, never a success).
-
-## 7. Reading a schema written in the V2 language
-
-A plan or Kit sample may arrive in the V2 schema language. It is an intermediate model only:
-production cannot store it. Translate before the first write.
-
-- **Keys.** V2 names are camelCase and scoped per object (`hero.heading`). Production keys are
-  flat, one namespace per model, prefixed by section: `"hero_heading"`.
-- **Labels and help.** V2 `title` is `label`; V2 `description` is `helpText` (§5 decides whether
-  it is written at all).
-- **Limits.** V2 `validation` becomes numbers in `config` (§6 step 4).
-
-| V2 type | Model field (`create_content_model`, `add_field`) | Component prop (`create_component`) |
-|---|---|---|
-| `string` | `text` with `richText: false` | `text` |
-| `text` | `longtext` | `text` |
-| `richtext` | `richtext` for section copy; `document` for the one body | `richtext` |
-| `number` | `number` | `number` |
-| `rating` | `number` with `config.min`, `max`, `step` and `ui.control: "rating"` (stars) | `number` |
-| `boolean` | `boolean` | `boolean` |
-| `slug` | `slug` (an entry's own slug stays on the entry) | `text` |
-| `url`, `link` | `link` | `link`; `url` for a media or embed address |
-| `email`, `phone` | `email`; a phone number is `text` with `richText: false` (`phone` opens only in the classic editor) | `text` |
-| `date`, `datetime` | `date`, `datetime` | `date` (`YYYY-MM-DD`); a datetime stays `text` |
-| `color` | `color` | `color` |
-| `select` | `select` | `select` with `config.options` |
-| `multiselect` | `multiselect` with `config.options` (a closed `string[]` choice list; `min`/`max` count the choices) | `multiselect` with `config.options` |
-| `tags` | `tags` (a `string[]`; `config.options` are suggestions, `allowCustom: false` closes the list); a taxonomy with its own pages is a collection plus `multi-reference` | `tags` |
-| `image` | `image` | `image` |
-| `file`, `video` | `file`; a hosted video URL is a `link` | `file`; `url` for a hosted video |
-| `icon` | `icon` (an icon name or an uploaded image) | `icon` (an icon name or an image) |
-| `button` | `button` | `button`: one prop targeting the `props` of a `button` block (§4) |
-| `reference` | `reference`; `multi-reference` for many | none: keep it on the model |
-| `code` | `longtext` | `text` |
-| `json` | `json` | `text` |
-| `geopoint` | `location` (`{ lat, lng, label? }`) | `group` of two `number` props |
-| `table` | `table` with `config.mode: "data"` (one data table: the editor's Columns and Rows drill-in); a Portable Text table inside `richtext` or `document` when it belongs to running copy | `table` with `config.mode: "data"` |
-| `object` | `group` | `group` |
-| `array` of objects | `repeater`; item limits in `config.minItems` / `config.maxItems` (the editor shows "max N") | `table` |
-| `array` of strings | `array` (`itemType: "text"`) | `table` |
-| `array` of several item shapes | one component per shape, placed as sections; on a model, a `repeater` whose rows carry each shape's fields (`modular` opens only in the classic editor) | separate components |
-| `slot` | components placed on the page (componentize); never a `sections` or `component-ref` field, which the page form cannot edit | `slot` (one instance; a list with `config.multiple`) |
-| a form `reference` | a `form` block inside the section | `form` |
-
-V2 features with no production shape are dropped and reported, never faked: a per-cell table
-type, per-breakpoint values (only `style.hideOn` differs by breakpoint) and per-field
-localization. Two have a shape now: typed table columns are a `repeater` with one field per column
-(never `ui.layout: "table"`, which the editor cannot draw), and a slot with several children is a `slot` prop with `config.multiple`
-([components.md](components.md) §1).
-
-| The plan says | Production word |
-|---|---|
-| Block | Component (the type); section or component instance (the placed band) |
-| Site-wide block, global | Global Layout (`update_layout`) |
-| CMS item | Entry |
-| Collection page | An entry shown through its collection's dynamic page |
-| Static page | `singleton` page |
-| Collection | Content model plus its `dynamic` page |
-| Variant, layout | Components sharing one `sectionType` ([components.md](components.md)) |
-| Listing | `collection` block (§4) |
-| Picks | `multi-reference` |
-| Polymorphic array, modules | one component per shape |
-
-Tools and reports use the production word. Labels and help an editor reads never say
-"document": the `document` field is labelled Body.
-
-## Acceptance
-
-- Every imported route and collection has one clear home; one dynamic template per collection.
-- Sidebar moves keep every public route and record id; URL changes carry explicit redirects
-  (`create_redirect`).
-- Repeated data is modelled once, with references or reusable components.
-- Editors find and understand the fields without reading source code.
-- Model changes compile in each consuming site and keep the published output unchanged.
+---
+title: "Structure and content modeling"
+description: "Pages vs collections, the four folder layers, field decisions and naming, and changing a schema safely, including retiring a field in stages."
+---
+
+# Structure and content modeling
+
+**Outcome.** A content tree an editor understands on day one, durable relationships between
+records, no accidental URL change, and model changes that every consuming site builds against.
+
+Doctrine: §1–§5 and §14 of `bettercms://playbook/schema` (schema shape and sections) and
+`bettercms://playbook/structure` (sidebar); flow: `propose_schema` prompt; rule ids
+`CM-10`…`CM-14`, `CM-40`…`CM-44`. What the server does and does not check on a write:
+[write-limits.md](write-limits.md). Planning a whole site by business type:
+[site-blueprints.md](site-blueprints.md).
+
+## Contents
+
+1. Read the site before modeling
+2. Pages, collections and entries (thresholds, promoting items to a collection)
+3. Four structure layers, four meanings
+4. Field decisions (references, lists, listings, the `document` body, buttons)
+5. Editor labels and order (when to write help text)
+6. Changing a schema safely
+7. Reading a schema written in the V2 language (field type map, glossary)
+
+## 1. Read the site before modeling
+
+Inventory route files and rendered routes, source data schemas, repeated records, page templates,
+navigation, taxonomies, authors, tags, media references, SEO, forms, locales and publishing
+states. Compare with the project's pages, collections and entries (`list_pages`,
+`list_content_models`, `get_content_structure`). Note where a value is shared, where it is an
+instance override, and where one entry owns it outright.
+
+## 2. Pages, collections and entries
+
+A page is `singleton` (one page and its own content: home, about, a legal page) or `dynamic`
+(one template page whose collection entries each render at the page's path plus the entry slug).
+Choose by repetition: a shape that repeats per item is a collection; a one-off is a singleton,
+even when it lists items, because the list page reads the collection. A dynamic page is its
+collection: the model and its entries both point at the page (`content_models.page_id`,
+`content_entries.page_id`), so never create a separate page per entry. A dynamic page made with
+`create_page` takes its route pattern and its collection through `update_page { dynamic:
+{ previewPath, modelId } }`: `/blog/{slug}`, and an existing collection with no page yet.
+
+A listing elsewhere (latest posts on home, related posts on an article) is a `collection` block
+with `source: { modelId }`, never copied entries. It also takes `filters` (max 5, `{ field, op,
+value }` with the content API operators), `sort` (`-publishedAt,title`), `pinnedIds` (max 10,
+shown first), `excludeCurrent` and `limit` (default 20), beside `order` (`newest` or `oldest`) and
+`emptyText`. `cardComponentId` names the component each card is drawn through; without one a card
+shows the entry's `titleField` (default `title`) and `excerptField`. On a `dynamic` page the block
+lists that page's collection and draws ONE entry on `/<page>/<entrySlug>`, through
+`detailComponentId` when set. BetterCMS-rendered pages read it on every request;
+a route the repo builds does not draw this block, so list there with the content API.
+
+| Source pattern | BetterCMS destination |
+|---|---|
+| Home, about, contact, legal, editorial landing page | Singleton page with its own content |
+| Blog / case-study / product list URL | A list page plus a separate collection |
+| Repeated records sharing one template | One collection and one dynamic detail page |
+| 404, search, gated page | A page that keeps its access and noindex behaviour |
+| Author, category, tag, company reused by entries | A shared collection, referenced from the entries |
+| Data from an external runtime API | Keep the adapter and its owner; never fabricate entries |
+| Sitewide nav, footer, promo bar | Global Layout, never copied page fields |
+
+**Thresholds.** Three or more pages sharing a URL pattern and a card or detail layout are a
+collection. Two are a collection when the set will grow (jobs, case studies). Otherwise they are
+singletons.
+
+**Promote repeater items to a collection** when any one holds; keep them inline when none does
+(pricing bullets, a hero proof line, quotes on a one-off campaign page):
+
+| Signal | Example |
+|---|---|
+| The item has its own URL | A case-study card linking to its detail page |
+| The same item shows on two or more pages | A testimonial on home and on a product page |
+| It carries facts that must not drift between copies | Price, stock, rating, job status, a person's photo |
+| Another entry points at it | A post's author, an event's speaker |
+| Editors will filter, sort or count the items | Jobs by team, events by date |
+
+## 3. Four structure layers, four meanings
+
+Name the layer every time you say "folder". The answer to "where does X live" differs per layer.
+
+1. **Content sidebar folders** organise the dashboard only: nothing here reads or writes a URL,
+   slug, schema, content or publish state. Read with `get_content_structure`, get a proposal from
+   `suggest_content_structure`, apply it whole with `set_content_structure` once the user agrees,
+   or change one thing with `create_folder`, `rename_folder`, `move_to_folder` or `delete_folder`
+   (deleting a folder moves its contents up). `set_content_structure` replaces the whole document:
+   send the `version` you read; a 412 `VERSION_CONFLICT` means someone changed it, so read and
+   re-apply. It refuses duplicate folder ids, a parent not in the doc, a cycle, and nesting deeper
+   than 4. The standard pins the home page and each list page at the top, gives each content
+   family one folder named for its detail type (the list page and its collection are two items),
+   keeps other standalone pages in Pages (Pages › <language> on a multilingual site),
+   taxonomies used by two or more families in
+   Shared, and Settings last. Components are not sidebar items. Whether folders show depends on a
+   dashboard feature flag, so an empty sidebar is not proof the structure is missing.
+2. **URL page folders** are part of a page's path unless set not to be included in it. Renaming
+   or moving one 301s every affected URL and queues a rebuild: a routing change that needs the
+   user's review. They are set in the dashboard, not through the sidebar tools.
+3. **Component groups** (`component_groups`) organise definitions by family or role
+   (Navigation, Hero, CTA, Forms), never by the page that uses them ([components.md](components.md) §8).
+4. **Media library folders** organise assets (`folderId` on `create_media_upload`) and never
+   rewrite a stored content URL.
+
+What reads published structure: the sitemap (skips noindex pages), robots.txt (points at the
+sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item).
+
+## 4. Field decisions
+
+Before designing a section's fields, find the closest component-kit entry: the chooser by
+category and edge tag is [kit-scenarios.md](kit-scenarios.md), the full list is the
+`bettercms://kit` resource and [kit-catalog.md](kit-catalog.md). The entry's notes are the
+field mapping and its pitfalls the review list; the rules below still decide the storage.
+
+- **Model each visual band as a `group` field (or a repeater), or a component instance.** The
+  schema's shape decides whether the site can ever be componentized. The componentize lane finds
+  a section in a `group`, a repeater, or two or more top-level keys sharing a prefix before `-` or
+  `_` (`"hero_title"` + `"hero_subtitle"` → `hero`). A key with NO shared prefix (`title`,
+  `intro`) is a lone scalar, refused `NOT_A_SECTION`. Keep ONE separator per band: a `-` family
+  and a `_` family never share a component. A `group` is the robust choice, and child keys inside
+  it follow the flat-namespace rule (`"hero_title"`).
+- A collection for an entity with its own lifecycle and relationships; a nested group for values
+  one page or section owns.
+- A reference for reusable entities and internal links where the model supports it; an external
+  URL for links that leave the site.
+- **Resolve references before creating anything.** Build the target collection and its entries
+  first, then the model that points at them. Match each source item to an existing entry by
+  stable facts (a slug, a product handle, a name plus the start of the quote) and create only what
+  is missing. Store the entry id, never an href or a title. A write naming a target that does not
+  exist is refused with 400 (ref_missing). Flag an item with no identity (a quote with no name);
+  never import it.
+- A repeater for small, same-shaped items (cards, FAQ rows, links, social accounts); a nested
+  component or slot when an item has its own layout or variants.
+- **Lists are arrays; tags are taxonomy.** Features, steps, benefits and "what's included" are an
+  `array` (`itemType: "text"`), or a repeater when each item carries its own state (included or
+  not, an icon). Never a group holding one field. A label set that filters or classifies entries
+  is a `tags` field; when each label has its own page, a collection referenced with `multi-reference` (§2).
+- **Never freeze a feed.** A list of entries on the source stays a listing: copying the nine
+  visible cards into a repeater stops it updating. On a page BetterCMS renders, that is the
+  `collection` block: on the collection's own dynamic page it lists that collection, and with
+  `source: { modelId }` it lists any collection on any hosted page (§2). It takes `limit` (1 to
+  200), `order` (`newest` or `oldest`) or `sort`, `filters`, `pinnedIds`, `excludeCurrent` and
+  `emptyText`; in an article template a filter value may be `{{field}}` of the entry shown, which
+  is a "related" list. Pagination and grouping stay a query in the site's code. Always set the
+  empty state, never write card titles or images into the listing, and put "read next" on the
+  template once, not on each entry.
+- **`document` is the one long body.** A page schema or a collection may hold it, one at
+  most, and only as a top-level field: a group or a repeater cannot contain it. Label it Body. Short formatted copy stays `richtext`.
+- **Model a call to action as a single `button` field.** It stores `{ label, href }` plus the
+  optional look keys `variant`, `size`, `arrow`, `icon` and `newTab`, and the site draws it with
+  `BcmsButton` ([astro.md](astro.md), [next.md](next.md)). Never a text
+  field beside a link field: the pair has nowhere to keep a look, and a new pair in the importer's
+  spelling (`hero-span-go` + `hero-a-go-href`) is refused with 400 `cta_pair` on `add_field`,
+  `create_page` and model writes. A page that already holds a pair (`primaryCtaText` +
+  `primaryCtaHref`) becomes one button with `update_field` `{ pageId, path: "primaryCtaText",
+  mergeHref: "primaryCtaHref" }`: each entry's DRAFT gets `{ label, href }` and keeps the old values,
+  so code still reading them keeps rendering; the live copy changes on publish. On a route the
+  site's app renders at request time the merge is refused (409 `CODE_RENDERED_ROUTE`): change the
+  code to draw the CTA with `BcmsButton`, and the next build adds the button field. Inside a component
+  a CTA is a `button` block whose `props` one `button` prop targets ([components.md](components.md) §1).
+- A sponsored, untrusted or user-generated link takes `rel` (`nofollow`, `sponsored` or `ugc`) on the
+  button, or a `link` field value written as `{ href, rel?, newTab? }`; code that opts into the object reads `.href`.
+- A `date` field with a time takes `timezone` (`site` or an IANA name such as `Europe/Paris`) in its config;
+  values must then end in `Z` or an offset, and a bracketed zone suffix is dropped on save.
+- Never model SEO columns ([seo.md](seo.md)), Form questions (they live on the Form document) or
+  Global Layout values as content fields.
+- Keep source ids, slugs, locale, status and previous URLs as migration metadata, stable across
+  re-imports.
+- Lock a field whose value another system owns (a store, job board or feed id): `readOnly: "developer"` with a `lockReason`.
+  Only schema access may then change the value or the lock; other writes are refused (403 `FIELD_LOCKED`) unless they send the stored value back.
+- **Prefer a `select` over a `boolean` for a state that may grow** (`draft | review | live`, not
+  `isLive`). Why: no tool retypes a field, so a third state later costs a new field and a value
+  migration (§6).
+- Choose field types before the first write. A `link` accepts any scheme-less href (`/about`,
+  `about.html`, `#section`) and `http(s):`, `mailto:`, `tel:`; every other scheme is refused.
+  Choose the type from what the rendered value is, not habit ([portable-text.md](portable-text.md)).
+
+## 5. Editor labels and order
+
+**Name for meaning, not look.** Before writing a key or label, ask: would the name survive a
+redesign? `ctaText`, `authorBio` and `features` pass; `blueButton`, `leftColumn` and `bigHeading`
+fail, because the next redesign makes them lie.
+
+Short labels named for what the editor sees: Heading, Body, Primary button, Label, Link, Image,
+Alt text — or the name the site's code already uses (`cents` → Cents), never the copy itself
+(`.00`). An import names every field it derives the same way, by its section and its role
+there: "Hero headline", "Hero intro", "Hero primary button", "Pricing plans", "Footer link 2
+URL", "Header logo"; a list's columns by their role in the row ("Title", "Description", "Link
+URL"). A role is numbered only where it repeats in one section, and labels are unique on a page.
+Keys never change. Rename a label where the site's code has a better word: a name you give is
+kept on every later release, and one the import gave follows the import. Most fields need no help line from you (below). Group by what renders
+together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Repeatable items need a meaningful preview label (the FAQ question, the
+button label), reorder, and stable item ids. An empty optional field removes its element without
+leaving a gap; a long value wraps, and clamps only where the design intends it.
+
+### Writing help text
+
+Most fields get no help. The platform writes a line only where one of the four reasons below
+holds and leaves every other element with none, so leaving `helpText` out is the default, not a
+gap. It says so: `helpText: { source: "auto" }` in the response, `helpSource: "auto"` on the
+stored field. Text you send is stored as yours (`helpSource: "agent"`) and is never rewritten;
+`editor_setup` rewrites only its own lines and never a person's.
+
+Ask one question per field: does the editor need this line to type the right value? Write your
+own `helpText` (on a field or a prop) only for one of four reasons, written as one short plain
+sentence under 90 characters, with no semicolon, no dash and no figure taken from the page.
+
+| Reason | Good |
+|---|---|
+| A format or unit the label cannot show | Price in cents. · Length in minutes. · A .vtt caption file. |
+| Where the value shows, when the canvas cannot show it | Shown in search results and link previews. · Read by screen readers, not shown. |
+| A real constraint or consequence | Changing this breaks existing links. · Must be later than the start date. |
+| A fallback | Leave empty to use the page title. |
+
+Everything else is left out:
+
+| Never | Bad | Do instead |
+|---|---|---|
+| The label or the value again | Heading: "The section's main heading." · `e.g. "Starter Kit"` | Nothing. The API refuses help that echoes the value |
+| Coaching the writing | "Keep it short." · "Two to four words works best." · "Start with a verb." | A length is a counter: a number in `config` (`"maxLength": 60`, §6) |
+| An example of the value | Badge: "e.g. Most popular" | A `placeholder` where the control takes one (component props do) |
+| Strategy | Secondary button: "A lower-commitment option that builds trust." | Nothing. The label says which button it is |
+| Internal notes | "Renders as h2." · "Label and link are one unit." · a ticket or decision id | Keep them in the code or the report, never in the form |
+| Generic good practice | "Add alt text for screen readers." on every image | Nothing |
+
+One sentence, plain words, sentence case. If more than about one field in five carries your own
+line, you are over-writing. A component, a collection and a Layout Section (`update-section`)
+still take a `description` that says what the thing is ("Hero with a heading, supporting text,
+two buttons and an image"), never its name again.
+
+`get_next_steps` lists `help-text-missing` for an element the editor setup has not settled yet, or
+one whose line only echoes its label, and `get_binding_report` and `get_site_composition` carry the
+coverage as `help`. The platform writes a line only for the four reasons above and leaves most
+elements with none; clear the finding by running `editor_setup`, or by writing one of the four
+kinds yourself, never with filler.
+
+**Config keys.** Write only the `config` keys a field type documents (`maxLength`, `min`/`max`,
+`options`, `itemType`, `zones`, a rich text's `accept`/`inline`): any other key sends that field to
+the old classic editor. The import's own keys (`attr`, `numeric`, `units`, `band`, `seeded`, …) are the
+server's: both MCP surfaces drop them from what you write.
+
+## 6. Changing a schema safely
+
+A schema write alone is not a release. Before one, read the model with `get_content_model`, a few
+sample entries, the component definitions that touch it and the frontend readers, and write a
+before/after field map: key, type, label, required, default, validation, editor group, and what
+happens to existing values.
+
+1. **Guard concurrent edits.** Pass the model's `optimisticVersion` as `ifMatch` to
+   `update_content_model`. A 409 means it changed since you read it: re-read and re-plan, never
+   resend. Omitted, the last write wins, except on the editor-chrome args, which refuse without
+   it (428).
+2. **Know what the MCP can do.** `add_field` (a model's `modelId` or a page's `pageId`) appends
+   and never overwrites or retypes. `update_field` changes ONE existing field, addressed by a dot
+   path through its groups and repeaters (`hero.title`): its label, help text, `required`,
+   validation `config` (merged by key; null deletes one), `showIf`, `ui` or placement, written at
+   the version it read. A retype needs `allowRetype: true`, because stored values that do not fit
+   the new type are lost; a key rename needs the migration in step 3. `update_content_model` edits
+   the model's name, slug, URL pattern and fieldsets, and removes model fields only with
+   `removeFields` (step 3). The home page cannot be deleted, and changing a local type file is not
+   a schema change.
+3. **Retire or rename a field in stages, never in one write.** Renaming a key re-addresses its
+   content: `update_field` with a new `key` is refused with 409 and the count of entries holding
+   the old key, unless `allowFieldRemoval: true` discards their values. So a rename is a new field
+   plus a migration:
+   1. Relabel the old field "Old title (Deprecated)" and set help text naming its replacement
+      (`update_field` `label` and `helpText`).
+   2. Move it into a `collapsed: true` fieldset so editors stop reaching for it
+      ([editor-chrome.md](editor-chrome.md) §2).
+   3. Add the replacement (`add_field`, with `modelId` or `pageId`) with the final type and name.
+   4. Migrate values in code, draft first, and have the frontend read the new key.
+   5. Remove the old one. Page fields: `remove_page_fields` (dry run by default) returns
+      `keysWithContent` and writes nothing; read it, then run it with `dryRun: false` and
+      `discardContent: true` only for keys you migrated. Model fields: `update_content_model` with
+      `removeFields: ["oldKey"]` and `allowFieldRemoval: true`, sent with the `ifMatch` of your
+      read. It has NO dry run and discards that key's value in every entry, so count the entries
+      holding it first (`list_content_entries` with `modelId`: `meta.total` is the count, `page`
+      walks past the 200-row `limit`). Top-level keys only; an unknown key refuses the
+      whole call; a page's own fields go through `remove_page_fields`. Both discard data: removal
+      is the last step, with the user's yes.
+   Why: every stage before 5 is reversible, and a site built against the old key keeps rendering
+   until its next release reads the new one.
+4. **Put numeric limits in `config` as numbers** (`"maxLength": 60`), with `update_field` on a
+   field that exists. A numeric string is converted on save; an impossible value is refused with
+   `FIELD_CONFIG_INVALID`.
+5. **Check existing records before tightening validation.** Backfill or give a real default
+   before making a field required; keep a source-to-target map and a snapshot for any high-volume
+   transform.
+6. **Validate on a draft.** Entries written through the MCP pass one write path (request schema,
+   normalisation, per-field checks, uniqueness), and a write failing any step stores nothing.
+   Publishing copies the draft to live, so a draft that passes is the value that ships.
+7. **Change a component family together** (same prop keys and types on every variant;
+   [components.md](components.md) §1 and §3).
+8. **Regenerate types** with `bettercms-codegen` in every consuming site after any model or field
+   change, commit the output if the repo commits it, and run that repo's build and typecheck with
+   the script it already has. Templates typed against an old schema compile and read `undefined`.
+9. **Verify** the editor's grouping and controls, one draft edit per changed field class, the
+   preview binding, the static or headless reading path, and the public output once a release is
+   authorized.
+
+Content models, frontend types, component definitions and live content have separate lifecycles;
+there is no single "deploy schema" action. Production publication stays behind the user's
+authorization and the component readiness and Visual Approval gates.
+
+**Evidence to return:** model and field ids, the version you wrote against, migrated record
+count, codegen and build result, one editor check and one rendered-page check, warnings, and any
+change the platform could not make (an open dependency, never a success).
+
+## 7. Reading a schema written in the V2 language
+
+A plan or Kit sample may arrive in the V2 schema language. It is an intermediate model only:
+production cannot store it. Translate before the first write.
+
+- **Keys.** V2 names are camelCase and scoped per object (`hero.heading`). Production keys are
+  flat, one namespace per model, prefixed by section: `"hero_heading"`.
+- **Labels and help.** V2 `title` is `label`; V2 `description` is `helpText` (§5 decides whether
+  it is written at all).
+- **Limits.** V2 `validation` becomes numbers in `config` (§6 step 4).
+
+| V2 type | Model field (`create_content_model`, `add_field`) | Component prop (`create_component`) |
+|---|---|---|
+| `string` | `text` with `richText: false` | `text` |
+| `text` | `longtext` | `text` |
+| `richtext` | `richtext` for section copy; `document` for the one body | `richtext` |
+| `number` | `number` | `number` |
+| `rating` | `number` with `config.min`, `max`, `step` and `ui.control: "rating"` (stars) | `number` |
+| `boolean` | `boolean` | `boolean` |
+| `slug` | `slug` (an entry's own slug stays on the entry) | `text` |
+| `url`, `link` | `link` | `link`; `url` for a media or embed address |
+| `email`, `phone` | `email`; a phone number is `text` with `richText: false` (`phone` opens only in the classic editor) | `text` |
+| `date`, `datetime` | `date`, `datetime` | `date` (`YYYY-MM-DD`); a datetime stays `text` |
+| `color` | `color` | `color` |
+| `select` | `select` | `select` with `config.options` |
+| `multiselect` | `multiselect` with `config.options` (a closed `string[]` choice list; `min`/`max` count the choices) | `multiselect` with `config.options` |
+| `tags` | `tags` (a `string[]`; `config.options` are suggestions, `allowCustom: false` closes the list); a taxonomy with its own pages is a collection plus `multi-reference` | `tags` |
+| `image` | `image` | `image` |
+| `file`, `video` | `file`; a hosted video URL is a `link` | `file`; `url` for a hosted video |
+| `icon` | `icon` (an icon name or an uploaded image) | `icon` (an icon name or an image) |
+| `button` | `button` | `button`: one prop targeting the `props` of a `button` block (§4) |
+| `reference` | `reference`; `multi-reference` for many | none: keep it on the model |
+| `code` | `longtext` | `text` |
+| `json` | `json` | `text` |
+| `geopoint` | `location` (`{ lat, lng, label? }`) | `group` of two `number` props |
+| `table` | `table` with `config.mode: "data"` (one data table: the editor's Columns and Rows drill-in); a Portable Text table inside `richtext` or `document` when it belongs to running copy | `table` with `config.mode: "data"` |
+| `object` | `group` | `group` |
+| `array` of objects | `repeater`; item limits in `config.minItems` / `config.maxItems` (the editor shows "max N") | `table` |
+| `array` of strings | `array` (`itemType: "text"`) | `table` |
+| `array` of several item shapes | one component per shape, placed as sections; on a model, a `repeater` whose rows carry each shape's fields (`modular` opens only in the classic editor) | separate components |
+| `slot` | components placed on the page (componentize); never a `sections` or `component-ref` field, which the page form cannot edit | `slot` (one instance; a list with `config.multiple`) |
+| a form `reference` | a `form` block inside the section | `form` |
+
+V2 features with no production shape are dropped and reported, never faked: a per-cell table
+type, per-breakpoint values (only `style.hideOn` differs by breakpoint) and per-field
+localization. Two have a shape now: typed table columns are a `repeater` with one field per column
+(never `ui.layout: "table"`, which the editor cannot draw), and a slot with several children is a `slot` prop with `config.multiple`
+([components.md](components.md) §1).
+
+| The plan says | Production word |
+|---|---|
+| Block | Component (the type); section or component instance (the placed band) |
+| Site-wide block, global | Global Layout (`update_layout`) |
+| CMS item | Entry |
+| Collection page | An entry shown through its collection's dynamic page |
+| Static page | `singleton` page |
+| Collection | Content model plus its `dynamic` page |
+| Variant, layout | Components sharing one `sectionType` ([components.md](components.md)) |
+| Listing | `collection` block (§4) |
+| Picks | `multi-reference` |
+| Polymorphic array, modules | one component per shape |
+
+Tools and reports use the production word. Labels and help an editor reads never say
+"document": the `document` field is labelled Body.
+
+## Acceptance
+
+- Every imported route and collection has one clear home; one dynamic template per collection.
+- Sidebar moves keep every public route and record id; URL changes carry explicit redirects
+  (`create_redirect`).
+- Repeated data is modelled once, with references or reusable components.
+- Editors find and understand the fields without reading source code.
+- Model changes compile in each consuming site and keep the published output unchanged.