@bettercms-ai/mcp 0.68.2 → 0.69.0

package/dist/skills/bettercms/SKILL.md

@@ -117,12 +117,15 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Set up or resume a project | [getting-started.md](references/getting-started.md) | first contact, or "Continue BetterCMS setup" | setup, resume, onboarding, connect, import my site |
 | Finish an imported or converted site | [finish-site.md](references/finish-site.md) | a convert or build job; "make it fully editable"; the gap ledger | make it editable, finish, gap ledger, convert |
 | Move content out of another CMS (Cosmic, Contentful, Sanity, Strapi, Prismic, WordPress…) | [external-content.md](references/external-content.md) | a CMS SDK in package.json; `envWarning` on import; pages that render empty without a third-party key | Contentful, Sanity, Strapi, envWarning, missing key, empty pages |
-| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field |
+| Read a source site before modelling it | [detection.md](references/detection.md) | converting from a URL or built HTML; deciding what a band, a repeat or a value is | detect, classify, section, repeat, global, carousel clone, hidden state |
+| Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field, listing, filter, locked field |
 | Dock layout: groups, rows, tabs, icons, item names, showIf order | [editor-chrome.md](references/editor-chrome.md) | `get_next_steps` lists a `dock-*` rule; the `field-ui` prompt | dock, fieldset, tab, group, itemLabel, showIf, field-ui |
 | A custom input for one field in the dock: when, the user's approval, the contract | [dock-input.md](references/dock-input.md) | `get_next_steps` lists `dock-input-candidate`; a 409 `input_needs_confirmation` | custom input, ui.input, dock input, confirmed, swatch |
-| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write | validation, maxLength, unique, 400, refused write |
-| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | portfolio, agency, corporate, SaaS/AI or ecommerce IA | new site, IA, sitemap plan, portfolio, SaaS, ecommerce |
+| What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write; a bulk load or re-run | validation, maxLength, unique, 400, refused write, dry run, externalKey, upsert, re-run |
+| Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | the IA of a known site type, with its collections, forms and structured data | new site, IA, portfolio, agency, corporate, SaaS, ecommerce, directory, blog, docs, restaurant, events, course, jobs, real estate, nonprofit, multi-brand |
 | Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
+| One section, source HTML to bound template: hero, feature grid, pricing table, testimonials, FAQ | [worked-examples.md](references/worked-examples.md) | you want the whole path for one section in production shapes | example, hero, pricing, FAQ, testimonial, source to schema |
+| The same for an article entry, navigation in the Global Layout, tabs holding columns | [worked-examples-advanced.md](references/worked-examples-advanced.md) | a collection entry with a body, site chrome, or nested blocks | example, blog post, document body, mega menu, tabs, columns |
 | Componentize a derived site | [componentize.md](references/componentize.md) | `get_site_composition` shows pages made of fields only | componentize, sections, fields-only, get_componentize_plan |
 | Click-to-edit attributes, addresses, declared mode | [bindings.md](references/bindings.md) | `grep -rl "data-bcms-" src` finds files; a value the editor cannot select | data-bcms-field, click to edit, binding report, stega, declared |
 | Wiring, env, hosting modes, media host, snapshots | [frameworks.md](references/frameworks.md) | `package.json` lists an adapter; `bcms-content.json` exists | hosting, headless, env, codegen, types, revalidate, snapshot |
@@ -133,7 +136,8 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Brand kit, tokens, fonts, logo, images, icons | [media-and-brand.md](references/media-and-brand.md) | design fidelity, alt text, a logo or favicon change | brand, tokens, fonts, logo, image, alt text, favicon |
 | Forms, menus, accordions, modals, consent | [forms-and-interactions.md](references/forms-and-interactions.md) | attaching or verifying a form; an interactive section | form, submission, Turnstile, modal, accordion, menu |
 | Languages, locale prefixes, translation, hreflang | [localization.md](references/localization.md) | the build serves `/fr`-style prefixes; `locale-unvarianted` in a binding report | language, locale, /fr, translate, hreflang, i18n |
-| SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, `list_seo_issues` | SEO, meta, JSON-LD, sitemap, robots, OG image, redirect |
+| SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |
+| Accessibility: alt text, form labels, contrast, the audit codes and the manual checks | [accessibility.md](references/accessibility.md) | writing alt text; building a form; before reporting a site done | accessibility, WCAG, alt text, decorative, label, contrast, captions |
 | Page families from data | [programmatic-seo.md](references/programmatic-seo.md) | a keyword list or CSV should become pages | programmatic SEO, CSV, dataset, landing pages, glossary |
 | Publish, deploy, roll back, reconcile a re-import | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits | publish, deploy, rollback, sync, webhook, schedule, automation |
 | Read-only launch review | [site-review.md](references/site-review.md) | "is this ready to launch?" without fixing | launch review, audit, is it ready, QA |

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

@@ -0,0 +1,171 @@
+---
+title: "Accessibility"
+description: "WCAG 2.2 AA rules for converted and built sites: alt text, media, forms, contrast, links, motion, the audit codes, and the manual check list to run before reporting done."
+---
+
+# Accessibility
+
+**Outcome.** A converted or built site meets WCAG 2.2 AA where BetterCMS lets an agent control
+it, and the report says plainly what was checked and what was not.
+
+`list_seo_issues` reports the checkable items as `a11y.` codes, from the stored blocks of
+published pages: image alt missing, h1 missing, several h1, an h1 inside body text, a skipped
+heading level, generic link or button text, a video with no transcript. Each names the page and
+its block ids. It cannot see inside a `component` or `collection` block, an entry's fields, or a
+route the repo's code renders, and a clean result says nothing about contrast, focus order,
+keyboard use or form behaviour. Those stay manual: read the rendered page, then report what you
+saw. Never write "WCAG compliant"; write "checked against this list, with these exceptions".
+
+Related: [media-and-brand.md](media-and-brand.md) (assets, SVG, video, focal point),
+[forms-and-interactions.md](forms-and-interactions.md) (form fields, interactive patterns),
+[portable-text.md](portable-text.md) (heading levels, lists, tables), [seo.md](seo.md).
+
+## Contents
+
+- [Where each fact is stored](#where-each-fact-is-stored) · [Alt text](#alt-text)
+- [Video and audio](#video-and-audio) · [Forms](#forms) · [Structure and links](#structure-and-links)
+- [Colour, contrast and motion](#colour-contrast-and-motion) · [Check list before done](#check-list-before-done)
+- [What to report](#what-to-report)
+
+## Where each fact is stored
+
+| Fact | Lives in | Write with |
+|---|---|---|
+| Alt text of an image | `altText` on the image value, and on the media asset | the value in the entry or page write; `update_media` `altText` for the asset |
+| Caption | `caption` on the asset | `update_media` `caption` |
+| Transcript (video or audio) | the asset, published wherever the file is used | `update_media` `transcript` (at most 100,000 characters) |
+| Decorative image | `decorative` on the asset; an empty `altText` on one value | `update_media` `decorative: true`; the value in the entry or page write |
+| Captions track (`.vtt`) | not stored by any tool | report as missing; the owner adds it |
+| Form label, required mark, help text, consent wording | the Form's fields | `create_form` / `update_form` |
+| Icon-only link or button label | the element's `aria-label` or visually hidden text in the code, or the component prop that feeds it | code, or the component prop |
+| Page language | the page or entry `locale` | see [localization.md](localization.md) |
+| Page title | `metaTitle` | see [seo.md](seo.md) |
+
+An image value is an object, never a bare string. Alt on the asset is the default; alt on the
+value is for this placement only. Set both when the same file reads differently in two places.
+
+## Alt text
+
+An asset that is decoration wherever it is used takes `update_media` `decorative: true`: the
+audit stops asking for its alt text. An image VALUE has no such flag; an empty alt marks that one
+placement as decoration. A missing alt and a deliberately empty alt look the same to the next
+reader, so list every empty alt you left on purpose.
+
+| Image | Alt |
+|---|---|
+| Informative | What it shows that matters in this place. Never the file name, "image of", "photo" or "logo" |
+| Logo | The company name. A linked logo says where it goes ("Caldera home") |
+| Person | "Portrait of {name}" |
+| Product | The product name and what the photo shows |
+| Chart or diagram | One sentence with the trend or the point; put the numbers in real text nearby |
+| Image of text (size guide, menu) | Rebuild it as a table or list; keep the image only as a diagram |
+| Background image that carries meaning | Make it an image with alt, or mark it decorative |
+| Decorative (rule, flourish, duplicate of nearby text) | Empty alt; `decorative: true` on the asset when it is never informative |
+
+- Copy the source's real alt when it is good. Rewrite "image of ..." and file-name alt to
+  describe the image.
+- Missing or junk alt on a meaningful image: write it from the visible context and flag
+  `alt-written` for review. With no context to draw on, leave it empty and flag `alt-missing`.
+- An empty alt is right for decoration and wrong on a portfolio, product or team photo. Flag
+  every empty alt on a content image.
+- Generated images (`generate_image`, `transform_image`) always get `altText`.
+
+## Video and audio
+
+- Never invent captions or a transcript. If the source has none, leave the field empty, and
+  report it.
+- A transcript you produced from your own speech-to-text goes on the asset with `update_media`
+  `transcript`. It then publishes on the page, the Markdown twin, llms-full.txt and the delivery
+  API. BetterCMS does not generate transcripts.
+- Captions are `.vtt` files and no BetterCMS field stores them. State "captions missing" in the
+  report for any video with speech.
+- A video needs a poster image and autoplays only muted.
+- An embed needs a `title` naming the provider and what it shows. Write one when missing.
+- An animation, Lottie or 3D scene needs a poster or fallback image and a text label, and must
+  stop for reduced motion.
+
+## Forms
+
+Forms are Form records, so the rules apply to the form's fields ([forms-and-interactions.md](forms-and-interactions.md)).
+
+- Every field has a `label`, which the renderer shows as a visible label. A placeholder is not a
+  label. If the source used placeholders only, write a label from each, and flag it.
+- Mark required fields with `required: true`. The hosted renderer adds an asterisk; say in the
+  field's `helpText` or the form intro that starred fields are required, so colour or a symbol is
+  never the only signal.
+- `helpText` carries the format or constraint ("Use the number on your invoice"). A refused
+  submission returns `issues[].field` and `issues[].rule`; show the field name and the fix in the
+  form's error copy.
+- Consent: a `consent` field starts unticked and must be ticked to submit. Import a source's
+  pre-ticked box as unticked, and flag it. Import confirmshaming copy as written, then flag it
+  with a neutral rewrite.
+- `autocomplete` is not a field setting. The hosted and Next renderers set it where they know
+  it (phone). For a self-hosted form with its own markup, keep the source's values (`email`,
+  `given-name`, `tel`, `postal-code`).
+- A form result (success, error) must be announced. The Next `BcmsForm` uses a live region; check
+  that a custom form does too.
+
+## Structure and links
+
+- Heading levels follow the outline: one H1, no skipped level. How a heading level is chosen and
+  stored is in [portable-text.md](portable-text.md). Size is a style token, never a reason to
+  pick a level.
+- Lists, tables and quotes use their real Portable Text blocks, never lines of text with
+  bullets or spaces.
+- Link text says where it goes. Replace "click here", "read more" and "learn more" on their own
+  with the target ("Read the care guide"). Where the card layout forces a short visible label,
+  add the target as visually hidden text or an `aria-label` in code.
+- Icon-only links and buttons (social icons, close, menu, carousel arrows) have an `aria-label`
+  or hidden text. A dot or a map pin that links needs one too. Draft the label and flag it; never
+  leave it empty.
+- Navigation, footer and announcement bar belong in Global Layout (`update_layout`). Check the
+  skip link, the landmark roles (`header`, `nav`, `main`, `footer`) and that the mobile menu
+  opens by keyboard and returns focus.
+- Set the page `locale`. Mark a foreign phrase inside text with `lang` in code.
+- DOM order is reading order; never reorder with CSS. Targets are at least 24 by 24 CSS pixels.
+
+## Colour, contrast and motion
+
+- Contrast: 4.5:1 for body text, 3:1 for large text (24px, or 19px bold) and for borders of
+  controls and icons that carry meaning. Check each theme and each variant the editor can pick,
+  including text over photos.
+- Take colour from brand tokens and section styles, never from a copied hex
+  ([media-and-brand.md](media-and-brand.md)). A brand colour that fails contrast is reported
+  with the pair and ratio; never change the kit unasked.
+- Information is never colour alone: a status dot has a word beside it; a check mark has
+  "Included" beside it.
+- Respect reduced motion: scroll stories stack, parallax goes still, Lottie shows its fallback.
+- Carousels, marquees and auto-advancing tabs need a pause control and stop when focused.
+
+## Check list before done
+
+Run `list_seo_issues` first and fix every `a11y.` code (rows 1, 3, 4 and 5 for hosted pages).
+Then run these on the rendered pages (desktop and a 390 px mobile width), not on the stored data.
+Cover the home page, one page per template, one entry per collection, and every form page.
+
+| # | Check | How |
+|---|---|---|
+| 1 | Every informative image has alt; every empty alt is intentional | read each image's `altText` in the page output; list empties |
+| 2 | No alt is a file name, "image of" or "logo" | scan the same list |
+| 3 | Video and audio: transcript on the asset, captions reported | `get_media`, then the player |
+| 4 | One H1, no skipped heading levels | outline the headings in order |
+| 5 | Link text is meaningful out of context | list all links; fix vague ones |
+| 6 | Icon-only controls have a name | inspect each; draft and flag |
+| 7 | Every form field has a visible label, required is stated in text, consent is unticked | `get_form`, then the page |
+| 8 | A refused submission names the field and the fix | send one bad test submission |
+| 9 | Contrast meets 4.5:1 and 3:1 in every theme | measure real colour pairs |
+| 10 | Whole page works by keyboard: tab order, visible focus, menu, dialog, accordion, tabs | tab through it |
+| 12 | Motion stops or stills under reduced motion | emulate the preference |
+| 13 | Page has a title and a language | `list_seo_issues` for title; check `locale` |
+| 14 | Embeds have a title; moving content can pause | inspect each |
+
+## What to report
+
+Report accessibility as its own short block in the final report:
+
+- Checked: the pages and the rows above you ran.
+- Written: drafted alt (`alt-written`), labels and transcripts. Left empty on purpose: decorative
+  images, and each asset marked `decorative`.
+- Open: `alt-missing`, captions missing, contrast failures with the measured ratio, controls you
+  could not test (a third-party embed, a payment step).
+- Not claimed: conformance. No tool certifies it; the audit covers stored blocks only.

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

@@ -10,23 +10,39 @@ Doctrine (components vs collections, section anatomy, variants): §3 and §4 of
 reference is what the code does with what you write. Componentizing a derived site end to end:
 [componentize.md](componentize.md).
 
+## Contents
+
+- [1. The prop contract](#1-the-prop-contract) · [2. Instances](#2-instances) ·
+  [3. Sections, families and variants](#3-sections-families-and-variants) ·
+  [4. Publishing](#4-publishing) · [5. Rendering components in your site](#5-rendering-components-in-your-site)
+- [6. Preview source](#6-preview-source) · [7. The values popover](#7-the-values-popover-dashboard) ·
+  [8. Groups](#8-groups) · [9. Verify](#9-verify)
+
 ## 1. The prop contract
 
 A component declares `props`. Each prop is `{ key, label, type, target: { blockId, path },
 defaultValue? }`.
 
-- `type` is one of exactly 11: `text`, `richtext`, `image`, `url`, `boolean`, `number`,
-  `select`, `group`, `table`, `slot`, `form`.
+- `type` is one of exactly 18: `text`, `richtext`, `image`, `url`, `boolean`, `number`,
+  `select`, `group`, `table`, `slot`, `form`, then `date`, `color`, `file`, `link`, `icon`,
+  `multiselect` and `button`.
+- The last seven store what the same-named model field stores: `date` is `YYYY-MM-DD`, `color` a
+  hex, `file` `{ url, name?, size? }`, `link` an href string or `{ href, rel?, newTab? }`, `icon` an icon name or an image
+  value, `multiselect` a `string[]` drawn from `config.options`. A bad `defaultValue` is a 400.
+- **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
+  newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
+  declare a label prop plus a url prop: the two drift apart on the first edit.
 - `target.blockId` + `target.path` must point at a real block and property inside the
   component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
   that does not exist renders the default and the edit goes nowhere.
 - Every prop takes `helpText` and the component a `description` ("Hero with a heading,
   supporting text and two buttons."). Leave them out and the platform writes them; write your
   own by the rules in [content-modeling.md](content-modeling.md) ("Writing help text").
+- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in` or `isSet` (no `value`); model fields take the same four.
 - `update_component` replaces the whole `props` array. Read with `get_component`, change, write
   all props back.
-- `select` needs `config.options`; `slot` holds one nested component instance; `form` holds one
-  Form document.
+- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance;
+  `form` holds one Form document.
 - `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
   empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
   `{ formId }`. Neither may appear inside a `group` or `table` row.

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,67 @@ 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`, `rating` | `number` | `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` | `array` (`itemType: "text"`); a taxonomy 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` | `text` with `richText: false` | `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 form `reference` | a `form` block inside the section | `form` |
+
+V2 features with no production shape are dropped and reported, never faked: typed table columns,
+per-breakpoint values, per-field localization, a slot with several
+children (several sections or nested components instead).
+
+| 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.