@bettercms-ai/mcp 0.68.2 → 0.70.0

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

@@ -14,6 +14,16 @@ Doctrine: §1–§5 and §14 of `bettercms://playbook/schema` (schema shape and
 [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,
@@ -33,6 +43,12 @@ collection: the model and its entries both point at the page (`content_models.pa
 `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`. 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 |
@@ -43,6 +59,21 @@ collection: the model and its entries both point at the page (`content_models.pa
 | 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.
@@ -84,8 +115,29 @@ sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item)
   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 shared collection referenced with `multi-reference` (§2), not free text.
+- **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
@@ -97,11 +149,17 @@ sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item)
   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.text` and `props.href` two props target.
+  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).
@@ -117,38 +175,48 @@ 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`). Every field gets help text (below). Group by what renders
+(`.00`). 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
 
-Every field, prop, component, collection and Global section carries help an editor reads under
-its name: `helpText` on a field or prop, `description` on a component, a collection and a Layout
-Section (`update-section`). Write it the way a Sanity schema writes `description`:
+The platform writes a role line on every element, 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:
 
-- **Purpose, placement, constraint.** What it is for, where it shows, and a limit when one is
-  real. One or two sentences, plain words, sentence case.
-- **Never the label or the value again.** `e.g. "Starter Kit"` under an input holding "Starter
-  Kit" tells the editor nothing, and the API refuses help that echoes the value. An example may
-  follow a real sentence when it shows a format.
+| 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. |
 
-| Element | Good | Bad |
+Everything else is left out:
+
+| Never | Bad | Do instead |
 |---|---|---|
-| Hero heading | The page's main heading. One per page; keep it under about 60 characters. | Heading |
-| Button label | Text on the button. Two to four words works best. | e.g. "Get started" |
-| Meta description | Shown in search results under the page title. Aim for 120–160 characters. | The meta description. |
-| Logo | Logo shown in the header. An SVG or transparent PNG works best. | Image |
-| Component | Hero with a heading, supporting text, two buttons and an image. | Hero |
-
-Leave it out and the platform writes a line from the element's role, and 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. `get_next_steps` lists anything left without
-help as `help-text-missing`, and `get_binding_report` and `get_site_composition` carry the
-coverage as `help`: under 100% is a finding. Write your own line wherever the generated one
-is generic and you know more: the audience, the tone, who signs off, what breaks the layout.
+| 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 a field with no help line at all, or one that
+only echoes its label, and `get_binding_report` and `get_site_composition` carry the coverage as
+`help`. Clear the finding by letting the platform's line stand or by writing one of the four
+kinds above, never with filler.
 
 ## 6. Changing a schema safely
 
@@ -217,6 +285,70 @@ authorization and the component readiness and Visual Approval gates.
 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`, `phone` | `text` |
+| `date`, `datetime` | `date`, `datetime` | `date` (`YYYY-MM-DD`); a datetime stays `text` |
+| `color` | `color` | `color` |
+| `select` | `select` | `select` with `config.options` |
+| `multiselect`, `tags` | `multiselect` with `config.options` (a `string[]`; `config.allowCustom` for free tags, `min`/`max` count the choices); a taxonomy with its own pages is a collection plus `multi-reference` | `multiselect` with `config.options` |
+| `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` | a Portable Text table inside `richtext` or `document`, or a `repeater` of rows | `table` |
+| `object` | `group` | `group` |
+| `array` of objects | `repeater` | `table` |
+| `array` of strings | `array` (`itemType: "text"`) | `table` |
+| `array` of several item shapes | `modular` with `config.blockSlugs` (create the block models first) | separate components |
+| `slot` | `sections` or `component-ref` | `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
+and `ui.layout: "table"`, 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 | `modular` field |
+
+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.