@bettercms-ai/mcp 0.63.2 → 0.64.0

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

@@ -0,0 +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.

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

@@ -0,0 +1,146 @@
+---
+title: "Publishing and sync"
+description: "Publish order, delivery lanes, execute and verify, rollback, reconciling a re-import or continuous sync, and the automation surfaces that exist."
+---
+
+# Publishing, release, rollback and sync reconciliation
+
+**Outcome.** The intended revision reaches the right public site with its dependencies, routes,
+forms and cache state checked, and a new source revision lands without overwriting editorial
+work. A dashboard success is not evidence that a public route works.
+
+Order of operations and why a draft renders nothing: §7 of `bettercms://playbook/schema`.
+Component refusal codes: [components.md](components.md) §4. Hosting modes, the SSR switch, env
+names and revalidation: [frameworks.md](frameworks.md).
+
+## 1. Plan the dependency graph
+
+Confirm the project and its hosting mode from `get_project`, never from the repo name (`hybrid`
+is handled exactly like `managed`). Record the source commit, content revision, live baseline,
+release target and rollback point.
+
+Publish in dependency order: component definitions (and nested components), Form documents, the
+global navigation and footer, the Global Layout, pages and entries, SEO, then the frontend code
+that reads them.
+
+- **Chrome**: components first, then `publish_layout`; the order and the logo refusals are in
+  [components.md](components.md) §4.
+- **Forms**: test the destination and consent behaviour, then `publish_form`; a draft form answers
+  403 to every public submission.
+- **Pages and entries are two rows.** Publishing a singleton page publishes its entry too, as the
+  dashboard's publish button does, unless the entry's own gate refuses it (its workflow stage, or
+  the publish permission). `ENTRY_STILL_DRAFT` means the page went live over content that did
+  not, and names the entry and why; `ENTRY_SEED_FAILED` on `create_page` means none of its seed
+  data was saved.
+- Publishing copies the stored draft to live, so what you checked in the draft is what ships.
+- **Many at once**: `publish_entries` { action: 'publish' | 'unpublish', entryIds, pageIds } takes
+  up to 100 of each in one call (pages publish only). Each item still passes its own gates, and
+  nothing stops the run: read `failed` for every refusal and its reason.
+- **Throw away a draft**: `discard_draft` with `entryId` or `pageId` returns it to exactly what is
+  live; a page also drops its unpublished Layout overrides (`no_published_version` if it never
+  went live: delete it instead).
+- **Edit a page safely**: read `get_page` and send its `optimisticVersion` as `ifMatch` on
+  `update_page`; a 409 means someone changed it since, so read again. `blockJson` replaces the
+  whole composition, so an unguarded write can erase a concurrent edit.
+
+## 2. Choose the delivery lane
+
+| Hosting mode | Release path | Public proof |
+|---|---|---|
+| `managed` or `hybrid` | `deploy_project` or `create_deploy_upload`, then `get_deploy_status` | Cache-busted BetterCMS URL answers 200 with the intended revision |
+| `headless` | Publish content in BetterCMS; the frontend deploys through its own host and rebuild or revalidation | The external host's URL answers 200 with the intended content and metadata |
+
+A managed site renders static unless the owner switches Hosting to **Run as a server app**, which
+must happen before an SSR build ships ([frameworks.md](frameworks.md)).
+
+### Deploy to Vercel or Netlify
+
+To serve a `managed` or `hybrid` site from the owner's own Vercel or Netlify account, call
+`list_hosting_connections` first; with no working connection for that host, hand the user
+`connectUrl` to connect it in the browser and wait. Then `deploy_to_host` with the `provider`:
+BetterCMS builds, the host serves, and calling it again redeploys the same site. Relay any
+refusal's `fixUrl` to the user. Poll `get_host_deploy_status` until the newest deployment is live
+and verify its `providerUrl`. Forms post to the BetterCMS API, so they need no rewrite, and no host
+CLI or pasted host token is ever needed while a connection exists.
+
+## 3. Execute and verify
+
+1. After an authorized release, record the operation ids and revisions from each call.
+2. On a refusal, stop: resolve the cause its code names, then retry only with changed input.
+3. Fetch each touched route directly, cache-busted: status, the copy you published, component
+   overrides, media URLs, metadata and forms. Include one collection detail route, the global
+   navigation and footer, and mobile interaction when affected.
+4. Run the verify loop in SKILL.md, noting each report's freshness.
+5. On a cached site, confirm the publish webhook or rebuild actually refreshed the public page.
+
+## 4. Roll back
+
+Use the known prior content revision and source commit. For an entry, `list_entry_versions` then
+`restore_entry_version`: it writes that version back as the current draft and adds a new version,
+so publish it afterwards. Unpublished edits you do not want are `discard_draft`, not a restore.
+Restore only the affected lane, recheck the live URLs, and never overwrite newer unrelated edits.
+
+## 4b. Stage a change on a branch
+
+A content branch is a copy of the project's content to edit without touching the live site.
+`create_branch` { name } returns it; pass its id as `branchId` on every call made inside it
+(`list_branches` names the one you are on). To merge, `apply_branch` { branchId, dryRun: true }
+returns the diff and its conflicts: show it to the user, then apply, with `include` to take only
+some changes and `fields` to settle each conflicting field (`keep_branch` / `keep_parent`).
+
+## 5. Reconcile a re-import, a push or a continuous sync
+
+Identify the previous source snapshot or commit, the new one, the import manifest, the
+source-to-target id map and the current BetterCMS state. `list_activity` with `since` reads the
+project's durable change feed from an ISO timestamp (up to 100 events per call): call it with the
+time of the previous sync to see every dashboard or agent edit made since. Compare by stable identity, never
+by display name or row order, and confirm it is the same project and source branch. Without a
+manifest or id map this is no longer an automatic sync; treat it as a reviewed migration (the
+`bettercms-migrate` skill).
+
+Classify each difference and keep a three-way view where you can (the value last imported, the
+current source value, the current CMS value). Never flatten a person's CMS edit back to imported
+code because the file was touched.
+
+| Difference | Resolution |
+|---|---|
+| New in source | Import with the normal model and component rules; file into the existing Content sidebar folders |
+| Changed only in source | Update fields that are still code-owned or explicitly synced; CMS-owned values stay |
+| Changed only in CMS | Keep |
+| Changed on both sides | Report both values with provenance; apply a winner only after the user chooses |
+| Missing in source | An orphan, never an automatic delete. Tell removed from moved or renamed; offer archive / keep / relink with the inbound references, routes and redirects each affects |
+| Route or slug change | A URL and redirect plan (`create_redirect`); check collisions, canonicals and internal links first |
+| Assets | Match by source id or path plus checksum; a changed binary is a new revision; a missing source asset never breaks a published reference until the user approves its replacement or removal |
+
+Dry-run the proposed operations, then run the same snapshot again to prove it is idempotent (no
+new changes the second time). Apply only approved, supported changes, then compare counts,
+references, component usage, field bindings, preview and the affected public routes. The rollback
+for a content value the sync got wrong is §4.
+
+## 6. Automation surfaces
+
+"Run X when content changes" maps onto what exists; there is no user-deployed function runtime.
+
+| Need | Surface | Owner |
+|---|---|---|
+| Rebuild or revalidate a site on publish | The publish webhook, signed `X-BetterCMS-Signature` (HMAC-SHA256 of the raw body) with the project's webhook secret ([frameworks.md](frameworks.md) Revalidation) | Secret set in the dashboard; your route verifies it |
+| Notify another system of an event | Event webhooks, `list_webhooks` / `create_webhook`: `content.publish`, `content.unpublish`, `content.stage_changed` (workflow stage), `content.created`, `content.updated`, `content.deleted` and `deployment.triggered`; HMAC-SHA256 signed in `X-BetterCMS-Signature`; payloads carry ids, never content. The signing `secret` is returned ONCE, on create. A receiver that writes back on `content.updated` loops unless it skips its own writes. Per-subscription payload filters: dashboard | You |
+| Send form submissions somewhere | Per-form integrations: Google Sheets, Slack, a webhook, email | Dashboard only |
+| Go live or retire at a time | `scheduledAt` (publish a draft at a time; needs publish permission) and `unpublishAt` (return a published row to draft) on `update_content_entry` and `update_page`; `null` cancels either. Campaigns: `publish_campaign` takes both | You. An edit that omits `scheduledAt` CANCELS the pending publish, so resend it with every edit before it fires; omitting `unpublishAt` never cancels it |
+| Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed`; then `publish_entries` | You |
+| React to edits made elsewhere | Poll `list_activity` with `since` set to the time of your last read (1–100 events per call) | You |
+| Generate or rewrite in bulk with a human gate | AI jobs: `list_ai_jobs`, `get_ai_job`, then `approve_ai_job` or `reject_ai_job` on the user's word | User approves |
+
+Not available, so say so instead of building around it: code that runs inside BetterCMS on a
+content event, and a change subscription over the MCP (poll `list_activity` `since`). Anything
+beyond the table runs in the user's own infrastructure, triggered by a webhook. Why: a timer on the
+delivery API looks like a trigger, but it serves published content only and never sees an edit
+before it ships.
+
+## Report
+
+State what is live, what remains draft, whether a rollback ran, and any owner action still
+required (Visual Approval, a render-mode change, a secret). For a sync, list exact created,
+updated, unchanged, orphaned and conflicted ids, the choices still open, and the rollback point;
+an open conflict is never a successful sync. Do not say "launched" until the public response is
+verified.

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

@@ -0,0 +1,156 @@
+---
+title: "SEO and AEO"
+description: "Native page and entry meta, Markdown twins, route audit, structured data, sitemap and robots, AEO, validators and a generated OG image route."
+---
+
+# SEO and AEO
+
+**Outcome.** Every publishable route sends correct technical signals and carries useful,
+attributable content. Keep an implemented change separate from a search-engine outcome, which
+no one can guarantee.
+
+Doctrine: SEO is native and never modelled (§5b of `bettercms://playbook/schema`); flow:
+`seo_optimize` prompt.
+
+## 1. Where each value lives
+
+| Value | Writer | Notes |
+|---|---|---|
+| Page title, description, `schemaType`, `schema`, noindex, canonical, OG, Twitter | `update_page` | Merges into what is stored: an absent key keeps its value, `null` or `""` clears it |
+| Entry meta (title, description, noindex, canonical, OG, Twitter, schema) | `update_content_entry` with `meta` | Same merge rule |
+| Site defaults (`seoDefaults`: title, description, OG image, Twitter handle, `og`, `twitter`, `collectionSchemaTypes`), site JSON-LD (`siteSchema`), `robotsConfig`, `sitemapConfig`, `rssConfig`, `indexnowConfig`, `searchConfig` | `update_seo`, read with `get_seo` | Each key REPLACES its whole object, so read and send it complete. `collectionSchemaTypes` maps a collection's model id to its entries' schema.org type; a key the plan lacks answers 403 `FEATURE_LOCKED` |
+| Suggestions | `generate_seo_meta` | Returns a suggestion only; apply it with the writers above |
+| Audit | `list_seo_issues` | Computed live from published pages; nothing is stored |
+| Redirects | `list_redirects`, `create_redirect`, `update_redirect`, `delete_redirect` | 301, 302, 307 or 308; 301 when omitted |
+
+Never create `seoTitle`-style fields on a model, page or component: the renderer, the sitemap,
+`llms.txt` and `list_seo_issues` read the native values only. Self-hosted sites own their
+`<head>`, sitemap and robots; the platform renderer emits them only for hosted sites, so confirm
+the frontend emits the native values in its HTML ([next.md](next.md) covers `buildMetadata`).
+There is no hreflang field: translations are native rows (`locale`, `translationOf`). The hosted
+sitemap emits the hreflang alternates from them; a frontend emits the `<head>` links from each
+entry's delivered `translations` ([localization.md](localization.md)).
+
+### Markdown twins
+
+Every published page and entry is also served as Markdown for answer engines, at its own URL plus
+`.md` (the home page at `/index.md`; an entry at its parent page's path, then `/<slug>.md`).
+
+- The twin is generated from the content, per request. Nothing to model or keep in sync.
+- A noindex page or entry has no twin, and is left out of `llms.txt`.
+- To replace one twin, store a Markdown file at the same path in the dashboard (Pages →
+  Markdown). Only a published file serves; deleting it restores the generated twin. A second file
+  at the same path is refused (409, code markdown_path_taken).
+- `llms.txt`, `llms-full.txt` and which pages serve a twin are switched there too. Those writes
+  need the SEO permission, and no MCP tool writes them.
+
+## 2. Route-level audit
+
+Read the route inventory, page and entry records, site defaults, the rendered `<head>`, robots,
+sitemap, structured data and redirects. For each indexable route check:
+
+- HTTP status, canonical, title, description, the main heading, language, breadcrumbs,
+  internal links, image alt text and the social preview.
+- Page type and structured-data eligibility; schema values must match visible content.
+- Duplicate or near-duplicate routes, pagination, query parameters, redirects, trailing slash.
+- Robots and noindex conflicts, staging or private pages that got indexed, sitemap inclusion.
+- Client-rendered content: does the initial HTML carry the key content?
+
+A CMS field holding the right title does not prove the public route emits it. Fetch the HTML.
+
+## 3. Structured data
+
+- With no `schemaType` or `schema`, a BetterCMS page gets automatic JSON-LD from its content
+  (WebSite on the home page, Blog or CollectionPage on a collection list, WebPage otherwise).
+  `schemaType` picks an explicit schema.org type; pasted `schema` wins over both.
+- Prefer a small, accurate graph. Add Article, Product, BreadcrumbList, FAQ or Service only when
+  the page visibly supports it. Keep valid imported JSON-LD, and avoid duplicate nodes from
+  native metadata plus custom head code.
+- Never fabricate ratings, reviews, authors, availability, prices or dates. Valid markup does not
+  guarantee a rich result: [Google structured-data guidelines](https://developers.google.com/search/docs/appearance/structured-data/sd-policies).
+
+## 4. Sitemap, robots, llms.txt
+
+- The hosted sitemap leaves out noindex pages, and the generated robots.txt points at the
+  sitemap. Confirm drafts, private pages and noindex pages are absent from the live file.
+- A translated page or entry carries `<xhtml:link rel="alternate" hreflang>` for each listed
+  sibling (its `locale`, else the project's `localeConfig.defaultLanguage`) plus `x-default` for
+  the source row. A noindex or unpublished sibling is left out of the links as well.
+- `sitemapConfig` sets it `auto` or `custom`, the default changefreq and priority and `extraUrls`;
+  `robotsConfig` is `auto` or `custom` text; `indexnowConfig` { enabled, excludePatterns } pings
+  IndexNow on publish; `searchConfig` { enabled, placeholder, aiEnabled } is site search, which
+  `search_content` queries (published content only).
+- `refresh_search_index` costs nothing: `action: 'indexnow'` submits `urls` (this site's own, up
+  to 1000) or, without them, every change since the last submission; `action: 'reindex'` rebuilds
+  site search after bulk changes. A 503 means the index is unreachable: retry later.
+- `llms.txt` lists one link per published item. Maintain it for its intended readers, but do not
+  sell it as a ranking requirement: Google's [guidance for AI features](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+  says ordinary SEO fundamentals are the base.
+- Check each redirect's real status and target, and detect loops.
+
+## 5. AEO and content quality
+
+Improve the page for people first: clear questions and answers where the topic warrants them,
+descriptive headings, first-hand evidence, dates and named authors where real, text alongside
+media, consistent internal links and accurate structured data. No "AI-only" pages, artificial
+snippets or unverifiable claims.
+
+Report concrete findings ("canonical points to a 404", "OG image missing", "FAQ schema does not
+match the visible answers"), never an untraceable score.
+
+## 6. Publish and verify
+
+After an authorized change ([publishing.md](publishing.md)): inspect the rendered `<head>` and JSON-LD,
+route status, sitemap and robots output, and redirects. Use Search Console or similar only to
+report observed behaviour after launch, never to predict indexing.
+
+Validators, run against the live URL (they read the public HTML, never the CMS):
+
+| Checks | Tool |
+|---|---|
+| Open Graph tags as Facebook reads them; refreshes its cache | [Sharing Debugger](https://developers.facebook.com/tools/debug/) |
+| LinkedIn card | [Post Inspector](https://www.linkedin.com/post-inspector/) |
+| Any OG card | [opengraph.ing](https://opengraph.ing/) |
+| JSON-LD eligibility | [Rich Results Test](https://search.google.com/test/rich-results) |
+| JSON-LD syntax against schema.org | [Schema Markup Validator](https://validator.schema.org/) |
+| Sitemap XML | [XML Sitemaps validator](https://www.xml-sitemaps.com/validate-xml-sitemap.html) |
+
+X (Twitter) has no working public card preview: confirm the `twitter:*` tags in the fetched HTML.
+
+### A generated OG image on a self-hosted Next site
+
+When pages have no designed share image, render one per route instead of modelling an image
+field for it. The image reads the entry's own title, so it follows every content edit:
+
+```tsx
+// app/og/[slug]/route.tsx
+import { ImageResponse } from "next/og";
+import { cms } from "@/lib/cms"; // createBetterCMS(...)
+
+export async function GET(_req: Request, { params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entry = await cms.getEntry<{ title: string }>(slug);
+  if (!entry) return new Response("Not found", { status: 404 });
+  return new ImageResponse(
+    <div style={{ display: "flex", width: "100%", height: "100%", padding: 64, fontSize: 64 }}>
+      {entry.fields.title}
+    </div>,
+    { width: 1200, height: 630 },
+  );
+}
+```
+
+Point the route's OG image at it with `update_content_entry` `meta.og.image` (or `update_page`
+for a page), or from `generateMetadata`. Rules: 1200×630, an absolute URL, a 404 (never a blank image) for a
+missing slug, and strip stega from any preview string first ([bindings.md](bindings.md) §5).
+A hosted site gets its OG image from the native value; this route is for self-hosted Next only.
+
+## Acceptance
+
+- Native values and public HTML agree on representative static and dynamic routes.
+- Canonical, indexable routes are in the sitemap with no conflicting directives.
+- Structured data validates and matches visible content.
+- OG and Twitter previews use valid media and route-specific copy.
+- Internal links and redirects resolve; staging and private pages stay out of the index.
+- The report separates fixed technical issues, content recommendations, and unverified search
+  outcomes.

package/dist/skills/bettercms/references/shopify-headless.md

@@ -0,0 +1,52 @@
+---
+title: "Headless Shopify"
+description: "Shopify owns commerce, BetterCMS the editorial: ownership split, product references, cart, freshness and SEO."
+---
+
+# Headless Shopify with BetterCMS
+
+**Outcome.** Let editors shape the storefront in BetterCMS while Shopify remains authoritative for saleable products and the buyer transaction. The integration may use Hydrogen/Oxygen or another frontend; inspect the existing stack before choosing code paths.
+
+This complements the [large ecommerce blueprint](site-blueprints.md#large-ecommerce-website), [bindings](bindings.md) and [publishing](publishing.md). Do not assume a BetterCMS Shopify connector or native product picker exists; unless the connected project's tools show one, model product links as validated external ids (below).
+
+## Ownership contract
+
+| Concern | Default owner | BetterCMS treatment |
+|---|---|---|
+| Products, variants, SKUs, price, availability, collections, markets | Shopify | Stable references and optional editorial overlays |
+| Cart, discounts, checkout, orders, customer identity | Shopify | Functional UI and handoff; no copy of private transaction records |
+| Campaign pages, category stories, buying guides, banners, content sections | BetterCMS | Pages, collections, global components, instance overrides |
+| Brand tokens, page composition, nav/footer copy, SEO editorial fields | BetterCMS or frontend design system as established | Bind to rendered leaves; verify publication |
+| Product SEO facts and structured data | Rendered commerce data plus editorial fields | Merge with an explicit field precedence and current price/availability |
+
+Before writing, identify Shopify store and sales channel, Storefront API version, authentication approach, existing frontend, checkout/account flow, market and currency behavior, product handle policy, BetterCMS project/hosting mode, and where current canonical/SEO metadata comes from. Shopify's [Storefront API](https://shopify.dev/docs/api/storefront/latest) provides public catalog, cart, and checkout operations; it does not turn BetterCMS into an order platform.
+
+## Reference and rendering model
+
+Use a stable Shopify product or collection ID as the key in BetterCMS references; store the handle only as a display/routing snapshot. Handles can change. A BetterCMS `ProductEditorial` or `CollectionEditorial` entry can hold hero copy, story sections, buying advice, FAQs, related guides, or campaign placement. A missing editorial overlay must fall back to a valid Shopify-only product or collection page if the merchant intends it to be public.
+
+Use one product template and one collection template unless genuine layout families differ. Render price, compare-at price, availability, variant options, and cart eligibility from a current Shopify response. Do not allow an editor field to override these transactional values. Use a product reference picker only if its existence and ID contract are confirmed; otherwise a validated external-ID field plus preview lookup is safer than a fake internal collection.
+
+Model global promotion bars, nav/footer, category hero, product detail editorial slots, recommendations, and buying guides as BetterCMS components where the editor can see their effects. Define fallback behavior when an overlay is unpublished, a product is not published to the headless channel, a Shopify query fails, or a referenced product was deleted.
+
+## Buyer flow and privacy
+
+The variant selected in the UI must be the exact merchandise ID added to the Shopify cart. Check invalid/expired variants, sold-out changes, quantity limits, discounts, market/currency context, cart persistence, checkout return URLs, and error recovery. Customer accounts and order history use Shopify's current account APIs and authentication, not public BetterCMS content fields. [Shopify cart guidance](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart) · [Customer Account API](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api)
+
+Keep private Shopify tokens and customer data server-side. Verify the configured token type and exposure boundary rather than treating every Storefront token as a secret. Never put Admin API credentials in browser code.
+
+## Freshness and publication
+
+Content and commerce can publish independently. Define which events revalidate a product or collection route: BetterCMS editorial publish, Shopify product/collection change, handle change, inventory/price change, or market change. Decide cache TTL by data volatility and verify the host's invalidation mechanism. Never put a personalized cart, account page, or customer response in a shared cache. Shopify's [Hydrogen caching guide](https://shopify.dev/docs/storefronts/headless/hydrogen/caching) documents the risk for customer-scoped data.
+
+Deploy a headless frontend through its actual host (SKILL.md invariant 6). For the on-publish refresh, BetterCMS sends a signed revalidation webhook (header `X-BetterCMS-Signature`) to the URL configured on the project; the Next adapter's revalidate route verifies it ([frameworks.md](frameworks.md) Revalidation). A Shopify webhook or polling job may be needed for catalog freshness; verify subscriptions, idempotent processing, and deleted-product handling before relying on it.
+
+## SEO and sitemap contract
+
+Give product and collection routes a single public canonical form. Resolve Shopify handles and BetterCMS editorial slugs without collisions. If variants have selectable URLs, choose one-page versus multi-page variant policy and validate rendered product/variant metadata accordingly. Product JSON-LD must reflect the current purchasable variant, price/currency, and availability; don't publish stale CMS copies. [Google product variant guide](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
+
+Generate sitemap entries for eligible, live product and collection routes plus BetterCMS editorial pages, with no duplicate URLs across providers. Exclude cart, checkout, account, internal search, unpublished overlay-only landing pages, and unwanted filter combinations; a live Shopify product can remain eligible without an editorial overlay. Hydrogen has its own [SEO/sitemap/robots routes](https://shopify.dev/docs/storefronts/headless/hydrogen/seo); if using Hydrogen, reconcile them with BetterCMS page URLs rather than exposing two competing sitemap inventories. Handle `/robots.txt` and sitemap at the actual public host.
+
+## Verification matrix
+
+Test: product with and without editorial overlay; multiple variants; sold-out and unpublished products; handle rename; missing Shopify ID; empty collection; discount and currency/market change; add-to-cart and checkout; account privacy; CMS preview; CMS publish; Shopify update; stale cache; product removal; canonical, schema, sitemap, and redirects. Verify public HTML and a full purchase flow in a safe test environment. Report which systems were live-tested and which assumptions remain unverified.