@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/portable-text.md

@@ -1,213 +1,213 @@
----
-title: "Field types and Portable Text"
-description: "Choosing field types, the Portable Text write contract and grammar, converting HTML or Markdown structurally, and serializing rich text."
----
-
-# Field types and Portable Text
-
-**Outcome.** The editor shows the right control for each visible value, the page keeps its
-semantic HTML, a button or card title cannot turn into the wrong heading level, and every rich
-text value you write is stored and rendered as written. Binding grammar:
-[bindings.md](bindings.md); field and schema doctrine: `bettercms://playbook/schema`.
-
-## 1. Decide what the user is editing
-
-Inspect the rendered element, its source component, role, ancestors, repeated instances and
-responsive variants, and the existing schema. Keep four concerns apart; they must not collapse
-into one rich-text field:
-
-- **content** (the words),
-- **semantic tag** (H1, H2, p, button),
-- **presentation** (font, size, colour),
-- **behaviour** (href, modal trigger).
-
-Choose a field's type, label, validation and allowed rich-text features from its context on the
-page, not from a rule that every string is rich text. When one source value renders in two
-semantic contexts, split the display role from the content, or make the level a controlled
-component prop, never an open toolbar choice.
-
-## 2. Semantic field matrix
-
-The model's field types are `text`, `richtext`, `document` (the article body, at most one per
-collection), `image`, `boolean`, `number`, `select` and references, among others. The matrix is
-intended UX; confirm each control exists in the connected editor before promising it.
-
-| Rendered role | Field | Editor options | Render rule |
-|---|---|---|---|
-| Page or hero title | text, or one-block richtext | title role only; inline emphasis if the design needs it | one H1 per page; a title shown twice is not two H1s |
-| Section heading | text | no heading picker; level comes from the component | usually H2, H3 when nested |
-| Card or item title | text | no toolbar | H3/H4 by nesting; a reused card never adds an H1 |
-| Eyebrow, badge, button label, nav item, form label | text | plain | keep the real element (`span`, `a`, `button`, `label`) |
-| Summary | text; richtext only when inline links are needed | normal paragraphs, few marks | `p`; no heading or list controls |
-| Article body | `document` | the schema's allowed blocks | keep the whole outline and every supported node |
-| FAQ question | text | plain | inside an accessible trigger; the component owns the level |
-| FAQ answer, modal body | narrowed richtext | paragraphs, lists, links, emphasis | focus and ARIA live outside the value |
-| Image | image | asset, alt text, caption | bind `src` and `alt` separately |
-| Link | link | the destination | no raw HTML, no `javascript:` URL |
-| Button / call to action | one `button` field | label, link, style, size, arrow, icon, new tab | render with `BcmsButton`; never a text + link pair |
-
-"Disabled" controls mean the field's accept list removes irrelevant formatting; the field stays
-editable. Keep a source's unusual but valid hierarchy when changing it would alter meaning, and
-flag it for review. The page title is the page's `h1`; body rich text starts at `h2`. Group the
-side panel by what the editor sees (`Button → Label, Link, Style`;
-`Image → Asset, Alt text, Caption`) and show the instance scope.
-
-## 3. The write contract
-
-- Write a richtext value as a Portable Text array. An array passes straight through to storage.
-- Never write a bare string to a richtext field. On write a bare string is parsed as HTML or
-  Markdown (a conversion you did not review), while the reader treats a bare string as literal
-  text, so the same string means two different things depending on the path.
-- The stored value is an envelope `{ format: "portable-text-1", value, html }`. `value` is the
-  truth; `html` is a derived cache. Never write or patch `html`.
-- A per-paragraph address (`base#<_key>`) is an edit target, not a write path: write the whole
-  field ([bindings.md](bindings.md) §3).
-- The `/presence/pt-patch` endpoint relays live edits between people in the editor. It is not a
-  save. Persist through the content write tools.
-
-## 4. Portable Text rules
-
-Names come from `packages/richtext/src/schema.ts`. A field's `accept` list narrows them; use only
-names the field accepts.
-
-| Part | Allowed names | Granted by accept element |
-|---|---|---|
-| block `style` | `normal` always; `h1`…`h6`; `blockquote` | heading element; `p` |
-| decorators (span `marks`) | `strong`, `em`, `underline`, `strike-through`, `code`, `highlight` | `b`, `i`, `u`, `s`, `code`, `mark` |
-| annotations (`markDefs`) | `link` {href, target, className}; `styled` {tag, className, attrs} | `link`/`internalLink`; always |
-| `listItem` | `bullet`, `number`, `check` | `ul`, `ol`, `checklist` |
-| block objects | `bcmsDivider`, `pullQuote` {quote, name, role?, link?}; `keyTakeaways` {title?, points}; `bcmsCode` {code, language}; `bcmsBlock` {schemaKey, schemaLabel, fields}; `table` {rows} | `p`; `ul`; `pre`; `image`/`embed`/`columns`; `table` |
-| inline objects | `bcmsMention` {label} | always |
-
-- **Keys**: every block, span, markDef, row and cell has `_key` matching `^[A-Za-z0-9-]{1,32}$`,
-  unique in the document. Keys are editor addresses, so keep existing ones.
-- **Marks**: a span's `marks` entry is a decorator name or the `_key` of a markDef in the same
-  block. Every markDef is referenced by at least one span.
-- **Lists are flat**: a list item is a normal block with `listItem` and `level` (1 = top). Never
-  nest blocks inside a list container. A `check` item carries `checked: true|false`.
-- **Pull quote**: `{_type:"pullQuote", _key, quote, name, role?, link?}`; `quote` and `name` are
-  strings, `link` is a URL (or a link object with `href`) the name links to. A `pullQuote` without
-  string `quote` and `name` is refused on write. Renders `<figure data-rt="pullquote">`.
-- **Key takeaways**: `{_type:"keyTakeaways", _key, title?, points}`; `points` is an array of plain
-  strings, one per bullet. More than 8 points or a title over 40 characters is refused on write,
-  by code and path. Renders `<aside data-rt="takeaways">`.
-- **Tables**: a cell holds blocks in `content`, not a string. `header: true` marks a `<th>` cell;
-  `head: true` puts a row in `<thead>`.
-- **`styled`** carries a site's own inline markup; `tag` is one of `span`, `small`, `sup`, `sub`,
-  `kbd`, `abbr`, `time`, or a decorator tag (`strong`, `em`, `b`, `i`, `u`, `s`, `mark`, `code`, …)
-  that carries a class. A `link` keeps its class as `className`.
-- **Top-level `_type`** is one of `block`, `bcmsBlock`, `table`, `bcmsCode`, `bcmsDivider`,
-  `bcmsMention`, `pullQuote`, `keyTakeaways`. A name outside that list is refused on write, by
-  name and `_key`, because the block would disappear from the live site. The refusal is **top level
-  only**: a foreign mark passes and its text renders unmarked; a foreign inline child passes
-  and renders nothing. Check those yourself.
-
-A paragraph with a bold word and a link:
-
-<!-- pt-example -->
-```json
-[
-  {
-    "_type": "block",
-    "_key": "intro",
-    "style": "normal",
-    "markDefs": [{ "_type": "link", "_key": "lnk1", "href": "/pricing" }],
-    "children": [
-      { "_type": "span", "_key": "s1", "text": "See ", "marks": [] },
-      { "_type": "span", "_key": "s2", "text": "pricing", "marks": ["strong", "lnk1"] }
-    ]
-  }
-]
-```
-
-A flat two-level bullet list:
-
-<!-- pt-example -->
-```json
-[
-  { "_type": "block", "_key": "li1", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "li1s", "text": "Plans", "marks": [] }] },
-  { "_type": "block", "_key": "li2", "style": "normal", "listItem": "bullet", "level": 2, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "li2s", "text": "Monthly", "marks": [] }] }
-]
-```
-
-A table with a header row:
-
-<!-- pt-example -->
-```json
-[
-  {
-    "_type": "table",
-    "_key": "tbl",
-    "rows": [
-      { "_key": "r1", "head": true, "cells": [
-        { "_key": "c1", "header": true, "content": [
-          { "_type": "block", "_key": "c1b", "style": "normal", "markDefs": [],
-            "children": [{ "_type": "span", "_key": "c1s", "text": "Plan", "marks": [] }] }
-        ] }
-      ] },
-      { "_key": "r2", "cells": [
-        { "_key": "c2", "content": [
-          { "_type": "block", "_key": "c2b", "style": "normal", "markDefs": [],
-            "children": [{ "_type": "span", "_key": "c2s", "text": "Pro", "marks": [] }] }
-        ] }
-      ] }
-    ]
-  }
-]
-```
-
-Site markup kept through `styled`:
-
-<!-- pt-example -->
-```json
-[
-  {
-    "_type": "block",
-    "_key": "price",
-    "style": "h2",
-    "markDefs": [{ "_type": "styled", "_key": "sm1", "tag": "small", "className": "muted" }],
-    "children": [
-      { "_type": "span", "_key": "p1", "text": "$29 ", "marks": [] },
-      { "_type": "span", "_key": "p2", "text": "per month", "marks": ["sm1"] }
-    ]
-  }
-]
-```
-
-## 5. Converting into Portable Text
-
-1. Parse HTML, Markdown, MDX or source-CMS blocks structurally; never flatten markup with regex.
-2. Map headings, paragraphs, lists, links, marks, tables, images and embedded components to
-   supported nodes. Resolve internal links to page or entry references where possible.
-3. Sanitise HTML and URLs. Keep the source path and write a loss report for every unsupported
-   node, embed or script. A foreign custom block needs a renderer and a mapping, or a visible
-   conversion warning.
-4. Generate deterministic keys on the first import; preserve them on later edits and re-imports.
-5. Compare text, link count and targets, heading outline, list levels and media references
-   between source and result.
-
-## 6. Serializing out of Portable Text
-
-1. Render every allowed style, list type, decorator, annotation, inline object and custom block
-   explicitly. Report unknown nodes; never drop them silently.
-2. Use a context-aware renderer for internal links, images and embeds, and keep their
-   accessibility labels.
-3. Build plain-text and SEO excerpts from the semantic text, with preview markers stripped
-   (`stripStega`) and no HTML or hidden JSON.
-4. Markdown export loses interactive custom blocks; emit typed references or a loss report, and
-   never claim a lossless round trip.
-
-The public Portable Text specification describes the general block model. BetterCMS's own schema
-and accept list decide the subset; do not paste Sanity-only types or serializers.
-
-## Acceptance
-
-- Page title, section title, card title, button label, summary and article body each open the
-  expected controls; a reused card on a second page adds no H1.
-- Rich text keeps links, nested marks, lists, tables, custom blocks and stable keys; unknown
-  nodes are logged, and nothing disappears silently.
-- Changing a label, a URL or a style changes only that property on that instance.
-- Long, empty and translated text render acceptably.
-- After writing rich text, `get_binding_report` for the route is clean.
+---
+title: "Field types and Portable Text"
+description: "Choosing field types, the Portable Text write contract and grammar, converting HTML or Markdown structurally, and serializing rich text."
+---
+
+# Field types and Portable Text
+
+**Outcome.** The editor shows the right control for each visible value, the page keeps its
+semantic HTML, a button or card title cannot turn into the wrong heading level, and every rich
+text value you write is stored and rendered as written. Binding grammar:
+[bindings.md](bindings.md); field and schema doctrine: `bettercms://playbook/schema`.
+
+## 1. Decide what the user is editing
+
+Inspect the rendered element, its source component, role, ancestors, repeated instances and
+responsive variants, and the existing schema. Keep four concerns apart; they must not collapse
+into one rich-text field:
+
+- **content** (the words),
+- **semantic tag** (H1, H2, p, button),
+- **presentation** (font, size, colour),
+- **behaviour** (href, modal trigger).
+
+Choose a field's type, label, validation and allowed rich-text features from its context on the
+page, not from a rule that every string is rich text. When one source value renders in two
+semantic contexts, split the display role from the content, or make the level a controlled
+component prop, never an open toolbar choice.
+
+## 2. Semantic field matrix
+
+The model's field types are `text`, `richtext`, `document` (the article body, at most one per
+collection), `image`, `boolean`, `number`, `select` and references, among others. The matrix is
+intended UX; confirm each control exists in the connected editor before promising it.
+
+| Rendered role | Field | Editor options | Render rule |
+|---|---|---|---|
+| Page or hero title | text, or one-block richtext | title role only; inline emphasis if the design needs it | one H1 per page; a title shown twice is not two H1s |
+| Section heading | text | no heading picker; level comes from the component | usually H2, H3 when nested |
+| Card or item title | text | no toolbar | H3/H4 by nesting; a reused card never adds an H1 |
+| Eyebrow, badge, button label, nav item, form label | text | plain | keep the real element (`span`, `a`, `button`, `label`) |
+| Summary | text; richtext only when inline links are needed | normal paragraphs, few marks | `p`; no heading or list controls |
+| Article body | `document` | the schema's allowed blocks | keep the whole outline and every supported node |
+| FAQ question | text | plain | inside an accessible trigger; the component owns the level |
+| FAQ answer, modal body | narrowed richtext | paragraphs, lists, links, emphasis | focus and ARIA live outside the value |
+| Image | image | asset, alt text, caption | bind `src` and `alt` separately |
+| Link | link | the destination | no raw HTML, no `javascript:` URL |
+| Button / call to action | one `button` field | label, link, style, size, arrow, icon, new tab | render with `BcmsButton`; never a text + link pair |
+
+"Disabled" controls mean the field's accept list removes irrelevant formatting; the field stays
+editable. Keep a source's unusual but valid hierarchy when changing it would alter meaning, and
+flag it for review. The page title is the page's `h1`; body rich text starts at `h2`. Group the
+side panel by what the editor sees (`Button → Label, Link, Style`;
+`Image → Asset, Alt text, Caption`) and show the instance scope.
+
+## 3. The write contract
+
+- Write a richtext value as a Portable Text array. An array passes straight through to storage.
+- Never write a bare string to a richtext field. On write a bare string is parsed as HTML or
+  Markdown (a conversion you did not review), while the reader treats a bare string as literal
+  text, so the same string means two different things depending on the path.
+- The stored value is an envelope `{ format: "portable-text-1", value, html }`. `value` is the
+  truth; `html` is a derived cache. Never write or patch `html`.
+- A per-paragraph address (`base#<_key>`) is an edit target, not a write path: write the whole
+  field ([bindings.md](bindings.md) §3).
+- The `/presence/pt-patch` endpoint relays live edits between people in the editor. It is not a
+  save. Persist through the content write tools.
+
+## 4. Portable Text rules
+
+Names come from `packages/richtext/src/schema.ts`. A field's `accept` list narrows them; use only
+names the field accepts.
+
+| Part | Allowed names | Granted by accept element |
+|---|---|---|
+| block `style` | `normal` always; `h1`…`h6`; `blockquote` | heading element; `p` |
+| decorators (span `marks`) | `strong`, `em`, `underline`, `strike-through`, `code`, `highlight` | `b`, `i`, `u`, `s`, `code`, `mark` |
+| annotations (`markDefs`) | `link` {href, target, className}; `styled` {tag, className, attrs} | `link`/`internalLink`; always |
+| `listItem` | `bullet`, `number`, `check` | `ul`, `ol`, `checklist` |
+| block objects | `bcmsDivider`, `pullQuote` {quote, name, role?, link?}; `keyTakeaways` {title?, points}; `bcmsCode` {code, language}; `bcmsBlock` {schemaKey, schemaLabel, fields}; `table` {rows} | `p`; `ul`; `pre`; `image`/`embed`/`columns`; `table` |
+| inline objects | `bcmsMention` {label} | always |
+
+- **Keys**: every block, span, markDef, row and cell has `_key` matching `^[A-Za-z0-9-]{1,32}$`,
+  unique in the document. Keys are editor addresses, so keep existing ones.
+- **Marks**: a span's `marks` entry is a decorator name or the `_key` of a markDef in the same
+  block. Every markDef is referenced by at least one span.
+- **Lists are flat**: a list item is a normal block with `listItem` and `level` (1 = top). Never
+  nest blocks inside a list container. A `check` item carries `checked: true|false`.
+- **Pull quote**: `{_type:"pullQuote", _key, quote, name, role?, link?}`; `quote` and `name` are
+  strings, `link` is a URL (or a link object with `href`) the name links to. A `pullQuote` without
+  string `quote` and `name` is refused on write. Renders `<figure data-rt="pullquote">`.
+- **Key takeaways**: `{_type:"keyTakeaways", _key, title?, points}`; `points` is an array of plain
+  strings, one per bullet. More than 8 points or a title over 40 characters is refused on write,
+  by code and path. Renders `<aside data-rt="takeaways">`.
+- **Tables**: a cell holds blocks in `content`, not a string. `header: true` marks a `<th>` cell;
+  `head: true` puts a row in `<thead>`.
+- **`styled`** carries a site's own inline markup; `tag` is one of `span`, `small`, `sup`, `sub`,
+  `kbd`, `abbr`, `time`, or a decorator tag (`strong`, `em`, `b`, `i`, `u`, `s`, `mark`, `code`, …)
+  that carries a class. A `link` keeps its class as `className`.
+- **Top-level `_type`** is one of `block`, `bcmsBlock`, `table`, `bcmsCode`, `bcmsDivider`,
+  `bcmsMention`, `pullQuote`, `keyTakeaways`. A name outside that list is refused on write, by
+  name and `_key`, because the block would disappear from the live site. The refusal is **top level
+  only**: a foreign mark passes and its text renders unmarked; a foreign inline child passes
+  and renders nothing. Check those yourself.
+
+A paragraph with a bold word and a link:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "block",
+    "_key": "intro",
+    "style": "normal",
+    "markDefs": [{ "_type": "link", "_key": "lnk1", "href": "/pricing" }],
+    "children": [
+      { "_type": "span", "_key": "s1", "text": "See ", "marks": [] },
+      { "_type": "span", "_key": "s2", "text": "pricing", "marks": ["strong", "lnk1"] }
+    ]
+  }
+]
+```
+
+A flat two-level bullet list:
+
+<!-- pt-example -->
+```json
+[
+  { "_type": "block", "_key": "li1", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "li1s", "text": "Plans", "marks": [] }] },
+  { "_type": "block", "_key": "li2", "style": "normal", "listItem": "bullet", "level": 2, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "li2s", "text": "Monthly", "marks": [] }] }
+]
+```
+
+A table with a header row:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "table",
+    "_key": "tbl",
+    "rows": [
+      { "_key": "r1", "head": true, "cells": [
+        { "_key": "c1", "header": true, "content": [
+          { "_type": "block", "_key": "c1b", "style": "normal", "markDefs": [],
+            "children": [{ "_type": "span", "_key": "c1s", "text": "Plan", "marks": [] }] }
+        ] }
+      ] },
+      { "_key": "r2", "cells": [
+        { "_key": "c2", "content": [
+          { "_type": "block", "_key": "c2b", "style": "normal", "markDefs": [],
+            "children": [{ "_type": "span", "_key": "c2s", "text": "Pro", "marks": [] }] }
+        ] }
+      ] }
+    ]
+  }
+]
+```
+
+Site markup kept through `styled`:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "block",
+    "_key": "price",
+    "style": "h2",
+    "markDefs": [{ "_type": "styled", "_key": "sm1", "tag": "small", "className": "muted" }],
+    "children": [
+      { "_type": "span", "_key": "p1", "text": "$29 ", "marks": [] },
+      { "_type": "span", "_key": "p2", "text": "per month", "marks": ["sm1"] }
+    ]
+  }
+]
+```
+
+## 5. Converting into Portable Text
+
+1. Parse HTML, Markdown, MDX or source-CMS blocks structurally; never flatten markup with regex.
+2. Map headings, paragraphs, lists, links, marks, tables, images and embedded components to
+   supported nodes. Resolve internal links to page or entry references where possible.
+3. Sanitise HTML and URLs. Keep the source path and write a loss report for every unsupported
+   node, embed or script. A foreign custom block needs a renderer and a mapping, or a visible
+   conversion warning.
+4. Generate deterministic keys on the first import; preserve them on later edits and re-imports.
+5. Compare text, link count and targets, heading outline, list levels and media references
+   between source and result.
+
+## 6. Serializing out of Portable Text
+
+1. Render every allowed style, list type, decorator, annotation, inline object and custom block
+   explicitly. Report unknown nodes; never drop them silently.
+2. Use a context-aware renderer for internal links, images and embeds, and keep their
+   accessibility labels.
+3. Build plain-text and SEO excerpts from the semantic text, with preview markers stripped
+   (`stripStega`) and no HTML or hidden JSON.
+4. Markdown export loses interactive custom blocks; emit typed references or a loss report, and
+   never claim a lossless round trip.
+
+The public Portable Text specification describes the general block model. BetterCMS's own schema
+and accept list decide the subset; do not paste Sanity-only types or serializers.
+
+## Acceptance
+
+- Page title, section title, card title, button label, summary and article body each open the
+  expected controls; a reused card on a second page adds no H1.
+- Rich text keeps links, nested marks, lists, tables, custom blocks and stable keys; unknown
+  nodes are logged, and nothing disappears silently.
+- Changing a label, a URL or a style changes only that property on that instance.
+- Long, empty and translated text render acceptably.
+- After writing rich text, `get_binding_report` for the route is clean.

package/dist/skills/bettercms/references/programmatic-seo.md

@@ -1,98 +1,98 @@
----
-title: "Programmatic SEO"
-description: "Page families from data: deciding a family should exist, generating from a dataset through a reviewed job, and the indexability gate."
----
-
-# Programmatic SEO: page families from data
-
-**Outcome.** A maintainable family of genuinely useful pages, each with a clear search intent
-and verifiable content, without flooding the index with near-duplicates.
-
-This supplements [site-blueprints.md](site-blueprints.md) (route and model shape) and
-[seo.md](seo.md) (native meta, structured data, sitemap). It never grants permission to publish a large batch.
-
-## 1. Decide whether a family should exist
-
-Build an intent matrix before a model. For each family record audience, intent, the unique
-answer, data source, owner, update cadence, expected URL count and one real example.
-
-| Family | A good reason for a distinct page | Often a poor reason |
-|---|---|---|
-| Glossary term | Precise definition, examples, related concepts, source and review owner | A reworded dictionary sentence per keyword |
-| Solution × industry | Different workflow, constraints, capability and proof | The same template with the industry name swapped |
-| Integration | A shipped connector, setup, limitations, status | An unshipped logo or speculative partnership |
-| Comparison | Fair, current criteria and evidence | Generated competitor assertions |
-| Location | Real local presence, service terms, team or availability | A city name substituted into generic copy |
-
-If a candidate has no unique value, keep it unpublished or fold it into a stronger parent.
-Google's [spam policies](https://developers.google.com/search/docs/essentials/spam-policies)
-name large volumes of unoriginal pages made for rankings as scaled content abuse, and its
-[AI-search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
-warns against a page for every phrasing of a query.
-
-## 2. Model once, generate selectively
-
-1. **One entity collection per durable subject** (`GlossaryTerm`, `Integration`, `Industry`)
-   with one dynamic detail template. The collection's `urlPattern` (for example
-   `/glossary/:slug`) is its entry URL, set with `create_content_model` or
-   `update_content_model`. It must contain `:slug` exactly once, and when an entry's slug
-   changes the platform adds the 301 from the old URL. Connect subjects with references so each
-   fact lives once.
-2. **Cross-product pages need an approved pair record.** Never generate the Cartesian product of
-   two collections. The pair record holds the pair-specific insight, evidence, related entities,
-   owner, last review date and status.
-3. **Fields by editorial responsibility:** title and slug, a concise answer, original body or
-   sections, facts and sources, related links, imagery with alt text, and review state. Meta is
-   native ([seo.md](seo.md)), never a model field. Shape rules: [content-modeling.md](content-modeling.md).
-4. **Routes from stable ids and slugs.** Check case, punctuation, locale, reserved names,
-   collisions with static routes and previously published slugs. Any other moved URL gets a
-   redirect with `create_redirect`. A slug is an address, not a keyword field.
-5. **Everything stays draft until reviewed.** Record provenance for data and AI-assisted copy.
-   Never invent sources, testimonials, integrations or capabilities.
-
-### Generating from a dataset
-
-The `generate_landing_pages` prompt is the guided flow for this step (one template plus a
-dataset; for per-account pages it hands over to the `bettercms-abm` skill's order).
-`generate_pages_from_dataset` turns rows into pages from a template page, a mapping (model, a
-slug template such as `for-{{term}}`, and per-field values that are a column or an AI prompt)
-and the rows. Always run it with `dryRun: true` first and show the user the sample: the dry run
-writes and charges nothing. A real run waits for approval, and only the user's yes releases it
-through `approve_ai_job`; never approve your own plan.
-
-## 3. Indexability gate
-
-Decide `publish`, `publish-noindex`, `merge/redirect` or `omit` for every candidate. An
-indexable page needs:
-
-- a working 200 route with substantial distinct value for its intent;
-- a stable canonical that matches the internal-link and sitemap form;
-- visible facts consistent with the title, description and any structured data;
-- no conflict with a stronger parent, a duplicate, a locale variant or a filtered URL;
-- a path from relevant hubs and child pages, not only the XML sitemap;
-- an accountable owner and review date when facts can change.
-
-A noindex page is left out of the hosted sitemap; keep drafts, empty records, duplicate
-combinations, internal search and facet URLs out too. `robots.txt` does not remove a page from
-the index, and a blocked URL does not belong in the sitemap.
-
-## 4. Navigation, sitemaps and scale
-
-- Give each family a readable hub (`/glossary/`, `/integrations/`) with crawlable `<a href>`
-  links to its children. A sitemap is an inventory aid, not navigation.
-- Split sitemap files before Google's 50,000 URL / 50 MB limit: [sitemap guide](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap).
-- Keep one path pattern per family, and do not move an established path to fit it. Treat
-  locales as explicit equivalents: [URL guidance](https://developers.google.com/search/docs/crawling-indexing/url-structure).
-- At volume, generate inventory and validation reports with deterministic code. Use the MCP for
-  project state, model setup, samples and targeted repairs. Dry-run creates, updates and
-  deletes, confirm exact counts, batch with resumable ids, and reconcile later changes without
-  overwriting editor edits ([publishing.md](publishing.md) §5).
-
-## Acceptance and reporting
-
-Sample one page per family plus edge cases: shortest and longest record, no image, no evidence,
-duplicate slug, archived entry, locale variant, empty hub. Verify edit → preview → public HTML,
-head and JSON-LD, indexability, internal links, sitemap inclusion and redirects.
-
-Report candidates, published and indexable, published noindex, merged, omitted, broken, and
-pending review. A successful bulk write alone never completes the family.
+---
+title: "Programmatic SEO"
+description: "Page families from data: deciding a family should exist, generating from a dataset through a reviewed job, and the indexability gate."
+---
+
+# Programmatic SEO: page families from data
+
+**Outcome.** A maintainable family of genuinely useful pages, each with a clear search intent
+and verifiable content, without flooding the index with near-duplicates.
+
+This supplements [site-blueprints.md](site-blueprints.md) (route and model shape) and
+[seo.md](seo.md) (native meta, structured data, sitemap). It never grants permission to publish a large batch.
+
+## 1. Decide whether a family should exist
+
+Build an intent matrix before a model. For each family record audience, intent, the unique
+answer, data source, owner, update cadence, expected URL count and one real example.
+
+| Family | A good reason for a distinct page | Often a poor reason |
+|---|---|---|
+| Glossary term | Precise definition, examples, related concepts, source and review owner | A reworded dictionary sentence per keyword |
+| Solution × industry | Different workflow, constraints, capability and proof | The same template with the industry name swapped |
+| Integration | A shipped connector, setup, limitations, status | An unshipped logo or speculative partnership |
+| Comparison | Fair, current criteria and evidence | Generated competitor assertions |
+| Location | Real local presence, service terms, team or availability | A city name substituted into generic copy |
+
+If a candidate has no unique value, keep it unpublished or fold it into a stronger parent.
+Google's [spam policies](https://developers.google.com/search/docs/essentials/spam-policies)
+name large volumes of unoriginal pages made for rankings as scaled content abuse, and its
+[AI-search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+warns against a page for every phrasing of a query.
+
+## 2. Model once, generate selectively
+
+1. **One entity collection per durable subject** (`GlossaryTerm`, `Integration`, `Industry`)
+   with one dynamic detail template. The collection's `urlPattern` (for example
+   `/glossary/:slug`) is its entry URL, set with `create_content_model` or
+   `update_content_model`. It must contain `:slug` exactly once, and when an entry's slug
+   changes the platform adds the 301 from the old URL. Connect subjects with references so each
+   fact lives once.
+2. **Cross-product pages need an approved pair record.** Never generate the Cartesian product of
+   two collections. The pair record holds the pair-specific insight, evidence, related entities,
+   owner, last review date and status.
+3. **Fields by editorial responsibility:** title and slug, a concise answer, original body or
+   sections, facts and sources, related links, imagery with alt text, and review state. Meta is
+   native ([seo.md](seo.md)), never a model field. Shape rules: [content-modeling.md](content-modeling.md).
+4. **Routes from stable ids and slugs.** Check case, punctuation, locale, reserved names,
+   collisions with static routes and previously published slugs. Any other moved URL gets a
+   redirect with `create_redirect`. A slug is an address, not a keyword field.
+5. **Everything stays draft until reviewed.** Record provenance for data and AI-assisted copy.
+   Never invent sources, testimonials, integrations or capabilities.
+
+### Generating from a dataset
+
+The `generate_landing_pages` prompt is the guided flow for this step (one template plus a
+dataset; for per-account pages it hands over to the `bettercms-abm` skill's order).
+`generate_pages_from_dataset` turns rows into pages from a template page, a mapping (model, a
+slug template such as `for-{{term}}`, and per-field values that are a column or an AI prompt)
+and the rows. Always run it with `dryRun: true` first and show the user the sample: the dry run
+writes and charges nothing. A real run waits for approval, and only the user's yes releases it
+through `approve_ai_job`; never approve your own plan.
+
+## 3. Indexability gate
+
+Decide `publish`, `publish-noindex`, `merge/redirect` or `omit` for every candidate. An
+indexable page needs:
+
+- a working 200 route with substantial distinct value for its intent;
+- a stable canonical that matches the internal-link and sitemap form;
+- visible facts consistent with the title, description and any structured data;
+- no conflict with a stronger parent, a duplicate, a locale variant or a filtered URL;
+- a path from relevant hubs and child pages, not only the XML sitemap;
+- an accountable owner and review date when facts can change.
+
+A noindex page is left out of the hosted sitemap; keep drafts, empty records, duplicate
+combinations, internal search and facet URLs out too. `robots.txt` does not remove a page from
+the index, and a blocked URL does not belong in the sitemap.
+
+## 4. Navigation, sitemaps and scale
+
+- Give each family a readable hub (`/glossary/`, `/integrations/`) with crawlable `<a href>`
+  links to its children. A sitemap is an inventory aid, not navigation.
+- Split sitemap files before Google's 50,000 URL / 50 MB limit: [sitemap guide](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap).
+- Keep one path pattern per family, and do not move an established path to fit it. Treat
+  locales as explicit equivalents: [URL guidance](https://developers.google.com/search/docs/crawling-indexing/url-structure).
+- At volume, generate inventory and validation reports with deterministic code. Use the MCP for
+  project state, model setup, samples and targeted repairs. Dry-run creates, updates and
+  deletes, confirm exact counts, batch with resumable ids, and reconcile later changes without
+  overwriting editor edits ([publishing.md](publishing.md) §5).
+
+## Acceptance and reporting
+
+Sample one page per family plus edge cases: shortest and longest record, no image, no evidence,
+duplicate slug, archived entry, locale variant, empty hub. Verify edit → preview → public HTML,
+head and JSON-LD, indexability, internal links, sitemap inclusion and redirects.
+
+Report candidates, published and indexable, published noindex, merged, omitted, broken, and
+pending review. A successful bulk write alone never completes the family.