@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/site-blueprints.md

@@ -1,895 +1,895 @@
----
-title: "Site blueprints"
-description: "Route, collection, form, structured-data and redirect plans per business type: portfolio, agency, corporate, SaaS/AI, ecommerce, directory, blog or publication, docs or knowledge base, local business or restaurant, events, course, job board, real estate, nonprofit and multi-brand."
----
-
-# Site blueprints by business type
-
-A route and content model that fits the business, while editor folders, public URLs and reusable
-components stay separate. A blueprint is a starting hypothesis, not permission to replace a
-working site's taxonomy. The platform rules behind each layer are in
-[content-modeling.md](content-modeling.md).
-
-## Contents
-
-- [Common decision process](#common-decision-process)
-- [Starter rules](#starter-rules)
-- [Deliverables](#deliverables)
-- [Production shapes every blueprint uses](#production-shapes-every-blueprint-uses): foundations,
-  field types, list limits, URL limits, structured data, forms, checklist
-- Catalogs, read only the one that matches (a mixed site can use two, but give each page family
-  one route owner):
-  - [Portfolio](#portfolio-website): a person or studio presents selected work, services and a
-    contact path
-  - [Agency](#agency-website): services, sectors, proof and lead generation drive the site
-  - [Corporate](#corporate-website): several business units, regions, audiences, governance or
-    regulated content coexist
-  - [SaaS, AI, enterprise tech](#saas-ai-and-enterprise-technology-website): product,
-    solutions, industries, integrations, trust and education need separate models
-  - [Large ecommerce](#large-ecommerce-website): catalog, categories, products and shopping
-    journeys dominate; a Shopify-backed store also reads [shopify-headless.md](shopify-headless.md)
-  - [Directory](#directory-or-listings-website): hundreds of same-shaped listings with category
-    and location hubs
-  - [Blog / publication](#blog-or-publication): dated articles with bylines, taxonomy and a feed
-  - [Docs / knowledge base](#docs-or-knowledge-base): a navigation tree, code, versions, search
-  - [Local business / restaurant](#local-business-or-restaurant): address, hours, menu, booking
-  - [Events](#events-or-conference): dated events, agenda, speakers, venue, sponsors
-  - [Course](#course-or-education): courses, curriculum, instructors, cohorts
-  - [Job board](#job-board-or-careers): open roles, departments, an ATS
-  - [Real estate](#real-estate-or-property-listings): properties, agents, offices, areas
-  - [Nonprofit](#nonprofit): programs, impact, stories, reports, donations
-  - [Multi-brand](#multi-brand-and-multi-language): several brands or languages on one design
-    system
-
-Data-generated page families (glossary, integrations, locations): [programmatic-seo.md](programmatic-seo.md).
-
-## Common decision process
-
-1. Inventory existing public URLs, navigation, templates, source content, business goals,
-   locales, owners, analytics and design tokens. Keep established URLs and brand rules unless a
-   change is in scope.
-2. Give each family a **source of truth**: a BetterCMS page, a collection entry, an external
-   system (commerce, ATS, docs), or application runtime. Name its editorial owner and publishing
-   gate. Record capabilities BetterCMS does not have as gaps; never invent fields that imply
-   them.
-3. Produce a route matrix: pattern, purpose, static / list / detail, content source, template,
-   canonical, indexability, sitemap eligibility, and the redirect it replaces. A collection's
-   list is a page; its entries render through one dynamic detail page.
-4. Produce a model matrix: fields and groups, references, taxonomy, reusable sections, global
-   nav/footer, labels, and variants. Components for reusable presentation, collections for
-   entities with their own lifecycle. Whether bands become components or fields follows
-   `authoringPreference` from `get_project`, which only the owner answers.
-5. Propose **Content sidebar** folders for editor tasks, **component groups** for definitions,
-   and **media folders** for assets. None of these changes a URL. **URL page folders** do change
-   paths, and renaming one 301s its pages, so they need explicit review. Sidebar doctrine:
-   `bettercms://playbook/structure`.
-6. Define per-family SEO policy: one canonical target, real indexable content, native SEO
-   metadata (never modelled fields, §5b of `bettercms://playbook/schema`), structured data only
-   where visible facts support it, and the treatment of filters, search, pagination, drafts,
-   gated pages and deleted records. Pages marked noindex are left out of the generated sitemap.
-7. Validate one representative route per family and the edge cases: empty collection, long
-   title, unpublished detail, duplicate slug, moved URL, mobile nav, optional section, locale,
-   no-result state. Confirm edit, preview and public render, then the build and binding reports.
-
-## Starter rules
-
-- Reference page lists illustrate common shapes; do not create pages the business does not have.
-- Prefer a few stable, human-readable route patterns. The best URL is often the existing one.
-- Keep a slug unique within its route namespace; check static against dynamic paths and locales.
-  When a published URL changes, add a redirect (`create_redirect`).
-- Keep a dedicated 404 and access/error pages. Leave drafts, private areas, internal search,
-  parameter duplicates and 404s out of the sitemap.
-- Sitemaps hold absolute, canonical, indexable URLs; Google documents a limit of 50,000 URLs /
-  50 MB uncompressed per file. [Google sitemap guide](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
-- Content sidebar folders are navigation for editors. Public hierarchy comes from routes and
-  internal links, never from folder labels. [Google ecommerce site structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure)
-- With locale variants, keep explicit equivalent-page mappings and one `hreflang`
-  implementation, verified in the rendered head. [Google localized versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
-
-## Deliverables
-
-Return a route tree, route matrix, content and model matrix, folder plan, component inventory,
-sitemap and redirect policy, open ownership decisions, and a phased implementation plan. On a
-live project, implement only the scope the user asked for and verify the routes you touched.
-
-## Production shapes every blueprint uses
-
-Read this once; every catalog below assumes it. A site is often two types (a SaaS site with a
-blog and docs): open each matching catalog, merge them, and create shared collections (Authors,
-Topics, FAQs, Testimonials) once. Drop any collection the source does not have.
-
-### Foundations
-
-| Piece | Where it lives |
-|---|---|
-| Header, footer, announcement bar | Global Layout via `update_layout`. Never a page section. Footer link columns are a repeater of groups; the newsletter box points at a form. A bar or promo that runs for a period takes a `window` on its Section, and a seasonal band one on its page block ([publishing.md](publishing.md) §6) |
-| Company name, address, phone, social profiles | One place in the Global Layout, read by the footer and the contact page. Site JSON-LD repeats it once in `siteSchema` (`update_seo`) |
-| Cookie consent | A third-party consent tool stays code. Report it; do not rebuild it as content |
-| 404, legal, thank-you pages | Static pages in a `System` Content sidebar folder. Thank-you pages are noindex |
-| Meta and structured data | Native per page and entry, site defaults with `update_seo` ([seo.md](seo.md)). Never modelled |
-
-### Field types
-
-Field keys below are entry keys in one flat namespace per model. `title` and the slug are on
-every entry and are not repeated in the tables. SEO fields are never listed.
-
-| The source shows | Production field |
-|---|---|
-| Short text, long plain text | `text`, `longtext` |
-| The one long body | `document` (one per model, top level). Shorter formatted copy is `richtext` |
-| Image, download | `image`, `file` |
-| Postal address | `group` of `text` children: `"street"`, `"city"`, `"region"`, `"postal_code"`, `"country"` |
-| Map pin | `location` (lat, lng, optional label). Never two text fields |
-| Tags, amenities, bullet lists | `array` with `itemType: "text"`. One choice from a fixed list is `select` |
-| Rows of the same shape (hours, facts, metrics, tickets) | `repeater` of `text`, `number`, `select`, `boolean` children |
-| Mixed ordered blocks in a case study | one component per block shape, placed as sections |
-| One or many other entries | `reference`, `multi-reference`. A missing target is refused on write |
-| Call to action | `button` (label and link in one value). A bare link is `link`; also `email`; a phone number is `text` |
-| Date, date and time | `date`, `datetime`. Keep the zone as a `text` IANA name beside it when the site shows times |
-| A spec or comparison table | `repeater` with one field per column (any field type). There is no separate table field type |
-
-An external system's id (`"store_product_id"`, `"ats_job_id"`, `"feed_id"`, `"lms_course_id"`)
-is a `text` field kept as migration metadata and locked: `readOnly: "developer"` with a
-`lockReason` naming the system it comes from. Place it last. A write that changes it without
-schema access is refused (403 FIELD_LOCKED). The lock is enforced on entries only.
-
-### Lists
-
-A collection's list is its own dynamic page holding one `collection` block. The block takes
-`limit` (1 to 200, default 20), `order` (`newest` or `oldest`, by creation time), `emptyText`,
-and optional card and detail components. Entry URLs are that page's path plus the entry slug.
-
-With `source: { modelId }` the block lists that collection on any hosted page, and takes
-`filters` (max 5; `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`), `sort`
-(`-publishedAt,title`), `pinnedIds` (max 10, shown first) and `excludeCurrent`. In an article
-template a filter value may be `{{field}}` of the entry shown. Filter values are stored on the
-block: a visitor cannot change them, and none means "today".
-
-Not available: pagination, grouping, visitor-driven filters. Only the hosted renderer draws the
-block; a route built from the repo's code queries the Delivery API with the same filter grammar.
-So for each hub the source has, choose and report one of:
-
-| Source list | Production shape |
-|---|---|
-| All entries, newest first | The `collection` block |
-| Filtered by category, location or status | On a hosted page a `collection` block with `source` and `filters`. On a code-built site the site's own code filters the delivered entries |
-| Sorted by a field (A to Z, a date, an order number) | `sort` on a sourced block |
-| Upcoming or past, by today's date | The site's code, or a `"status"` field the block filters on |
-| "Related" row | On a hosted template, a sourced block filtered by a `{{field}}` of the entry shown, with `excludeCurrent` |
-| "Featured" row | `pinnedIds`, a filter on a featured flag, or a short `multi-reference` chosen by hand |
-| Numbered pages, groups under headings, filter chips | The site's code |
-| Counts ("1,240 venues", "42 lessons") | Rendered by code from the entries. Never typed into copy |
-
-### URLs and redirects
-
-- Every collection gets a `urlPattern` holding `:slug` exactly once (`/blog/:slug`). A fixed
-  multi-segment prefix is valid (`/docs/v2/:slug`).
-- Nested (`/:category/:listing`) and dated (`/2024/05/my-post/`) source paths cannot be
-  expressed. Use the flat pattern and add one `create_redirect` (301) per old URL.
-- A slug change on an entry with a pattern 301s by itself.
-- Redirect types are 301, 302, 307, 308 and 410. A retired entry either stays published and
-  marked ended, redirects to a successor, or is unpublished and answers 410 (`create_redirect`
-  with `redirectType: "410"`, no destination).
-
-### Structured data
-
-Order: Automatic, then `schemaType`, then pasted `schema`. `schemaType` accepts `WebPage`,
-`AboutPage`, `ContactPage`, `CollectionPage`, `Blog`, `BlogPosting`, `Article`, `Product`,
-`FAQPage`, `Event`, `Organization`, `LocalBusiness`, `JobPosting`, `Course`, `Recipe`, `HowTo`,
-`Service`, `Person`, `VideoObject`. What the common ones emit from the content:
-
-| `schemaType` | Emits |
-|---|---|
-| `BlogPosting`, `Article` | Headline, description, image, published and modified dates, author |
-| `Product` | Name, description, image, SKU, offer |
-| `Event` | Name, description, image, start, end, a location name |
-| `LocalBusiness`, `Organization` | Name, description, URL, image or logo, telephone, email, address as one line |
-| `FAQPage` | The page's question and answer pairs. Never automatic |
-
-Anything richer is pasted `schema` built only from facts visible on the page: opening hours, geo
-coordinates, event status and offers, salary, `RealEstateListing`, `Restaurant`,
-`SoftwareApplication`, `NewsArticle`. A hosted page gets its `BreadcrumbList` automatically. Set a
-collection-wide default in `collectionSchemaTypes`. Never a self-serving `AggregateRating`.
-
-### Forms
-
-Thirteen field types: `text`, `textarea`, `email`, `phone`, `number`, `url`, `date`, `select`,
-`radio`, `checkbox`, `checkboxes`, `consent`, `hidden`, plus the `step` divider for multi-step forms. No file upload, so CVs, floor plans and
-attachments go to the external system. Payment details never go in a form. Submissions land in
-the inbox; an editor turns one into an entry. Full pipeline:
-[forms-and-interactions.md](forms-and-interactions.md).
-
-### Checklist
-
-- Every collection exists in the source, or was dropped on purpose.
-- Shared collections exist once across merged catalogs.
-- Store, ATS, LMS and feed facts are ids, never copies.
-- Every list has `emptyText` and a stated shape for each filter the source had.
-- Every collection has a `urlPattern`; every changed URL has a 301.
-- Structured data is built from visible fields, with the type its catalog names.
-
-### Built-in sections
-
-The section library ships 23 platform blueprints in 17 families, so a standard band needs no new
-component: Hero, Feature grid (three, two, bento), Feature rows, Steps, Timeline, Stats, Logo cloud,
-Testimonial (quote, three cards), Team, Case study, Comparison, Pricing, FAQ, Call to action,
-Capture (newsletter band) and Listing (latest, related). Read one with `list_components`; inline its
-`blockJson` as a `section` block for a one-off band, or copy it with `create_component` `from:
-"builtin:<key>"` for a recurring one (see [components.md](components.md)). Two ship unbound on purpose: the Capture form has no form until you
-set its `form` prop, and both Listing layouts list the page's own entries until you give them a
-`source`; each shows its empty text meanwhile. Not available as a section, so build it in the repo
-or leave it out: mega menu, docs sidebar, cookie consent, exit intent, store locator, map, billing
-toggle, countdown and anything commerce.
-
-## Portfolio website
-
-Use this when the primary job is to show selected work and make an individual or small studio credible. First determine whether the work is private, client-approved, dated, or still under embargo.
-
-### Route and model starter
-
-| Family | Example path | BetterCMS model | Index and sitemap |
-|---|---|---|---|
-| Home | `/` | Static page with selected projects and clear contact action | Yes |
-| Work index | `/work/` | Static index page querying Projects | Yes if substantive |
-| Project detail | `/work/{slug}/` | Projects collection + one dynamic template | Published, approved projects only |
-| About / services | `/about/`, `/services/` | Static pages unless services need independent owners and detail pages | If public and useful |
-| Writing / speaking | `/writing/`, `/writing/{slug}/` | Optional collection and index | Published articles only |
-| Contact | `/contact/` | Static page + form | Usually yes |
-| Password/preview case study | Existing route | Other page or protected runtime route | No |
-
-Keep the existing work prefix if it is `/projects/`, `/case-studies/`, or another established route; route changes need a redirect map.
-
-### Editor structure
-
-Content sidebar: `Start here` (Home, About, Contact), `Portfolio` (Work index, Projects), `Writing` if used, `Site essentials` (legal/other). Component groups: `Globals`, `Portfolio` (project hero, gallery, outcomes), `Shared sections` (CTA, quote, logo strip). Media folders may separate approved client work, self-initiated work, portraits, and downloadable files. These folders do not determine URLs.
-
-Project entry fields: display title, slug, client display name, service/category references, summary, role, dates when relevant, hero image plus alt text, ordered gallery items with captions/alt, challenge, approach, verified outcomes, credits, related projects, SEO, approval/visibility state. Do not require a public client name, metric, or testimonial when consent is absent. Support anonymous case studies without accidentally exposing the original client in image filenames, alt text, schema, or social previews.
-
-Use repeatable gallery items rather than a long list of `image1` fields. Give each item a meaningful editor label and image metadata. Keep project-specific storytelling sections as instances; make hero/gallery/quote layouts reusable definitions with instance overrides.
-
-### Validation
-
-Check case-study consent, working gallery at different aspect ratios, captions, full-size media performance, downloadable file links, contact submission, related-work references, archived projects, and redirect behavior for renamed slugs. A portfolio with only a few projects does not need auto-generated service × industry pages.
-
-### Production detail
-
-Projects collection, `urlPattern` `/work/:slug` (or the established prefix):
-
-| Field key | Type | Notes |
-|---|---|---|
-| `"client"` | `reference` to Clients, or `text` | A reference only when clients have a logo or page of their own |
-| `"year"` | `number` | |
-| `"services"` | `multi-reference` to Services, or `array` of text | References when service pages exist |
-| `"cover_image"`, `"excerpt"` | `image`, `longtext` | Words baked into a hero image move into fields |
-| `"modules"` or `"body"` | components, or `document` | one component per block (text, image, gallery, quote, video, stats) for image-led studies; `document` when mostly prose |
-| `"results"` | `repeater`: `"value"`, `"label"` | Only verified outcomes |
-| `"credits"` | `repeater`: `"role"`, `"name"` | |
-| `"testimonial"` | `reference` to Testimonials | |
-| `"live_link"` | `link` | |
-| `"is_featured"` | `boolean` | The home grid is a hand-picked `multi-reference` or code filtering on this |
-
-- **Chrome:** a minimal header and a footer with contact details, both in the Global Layout.
-- **Forms:** one enquiry form (name, email, message, consent).
-- **Structured data:** `Article` on projects, `AboutPage` and `ContactPage` on those pages,
-  `Organization` or a `Person` node in `siteSchema`.
-- **Pitfalls:** videos without a poster or captions; scroll-driven storytelling flattened into
-  one blob (keep each step a `modular` item); downscaled uploads (upload the original once, the
-  media pipeline serves sizes); client work under NDA published without confirmed rights (flag
-  it in the report and ask).
-
-## Agency website
-
-Use when the site must explain services, prove results, and convert qualified leads. The key distinction from a portfolio is a durable offer taxonomy and repeatable proof linked to each offer.
-
-### Route and model starter
-
-| Family | Example path | Model and purpose |
-|---|---|---|
-| Home | `/` | Static overview, positioning, primary CTA |
-| Services index/detail | `/services/`, `/services/{slug}/` | Static index + Services collection only if multiple services have owners, proof, and maintained detail content; otherwise static pages |
-| Industries | `/industries/`, `/industries/{slug}/` | Optional collection; publish only distinct industry expertise |
-| Work index/detail | `/work/`, `/work/{slug}/` | Case studies collection and dynamic detail template |
-| Insights | `/insights/`, `/insights/{slug}/` | Editorial collection, authors, categories |
-| Agency | `/about/`, `/team/`, `/careers/` | Static or collection by update cadence |
-| Contact | `/contact/` | Form with routing/consent behavior |
-
-Use the established `/case-studies/`, `/blog/`, etc. when the current site already has them. A service × industry matrix should be created only for combinations with distinct evidence, offer, and maintenance owner; otherwise link the existing service and industry pages instead of generating thin duplicates.
-
-### Content relationships and components
-
-Cases reference services, industries, client permission state, outcome evidence, and optional quotes. Service pages reference relevant cases, deliverables, process, FAQ, and CTA. Industry pages reference services/cases and sector-specific language. Avoid duplicating client logos or metrics across pages: maintain permission and source context on the case/client record.
-
-Component groups: `Globals` (nav/footer), `Proof` (case card, metrics, testimonial), `Offers` (service card, process), `Conversion` (CTA, contact form), `Editorial`. Reuse definitions with page-specific props, and allow section order to vary by page. Editors should see grouped fields such as `Primary button → Label, Link`, `Proof item → Metric, Context, Source`.
-
-Content sidebar folders should match editor work: `Core pages`, `Services`, `Industries`, `Case studies`, `Insights`, `Company`. These are dashboard folders, not paths.
-
-### Validation
-
-Review lead form destination, attribution and consent, internal links from every offer to relevant proof, case-study rights, schema claims, duplicate service routes, old URL redirects, and mobile CTA visibility. Keep draft or client-confidential work out of sitemaps and public data feeds.
-
-### Production detail
-
-| Collection | `urlPattern` | Fields |
-|---|---|---|
-| Case studies | `/work/:slug` | The Projects fields in [Portfolio](#portfolio-website), plus `"industry"` `reference` |
-| Services | `/services/:slug` | `"icon"` `image`, `"excerpt"` `longtext`, `"body"` `document`, `"related_work"` `multi-reference` |
-| Clients | none (no detail page) | `"logo"` `image` with the company name as alt, `"website"` `link` |
-| Team | `/team/:slug`, only when profiles have pages | `"role"` `text`, `"photo"` `image`, `"bio"` `longtext`, `"social_links"` `repeater`: `"network"` `select`, `"url"` `link` |
-| Testimonials | none | `"quote"` `longtext`, `"name"`, `"role"`, `"company"` `text`, `"photo"`, `"logo"` `image` |
-
-- **Lists:** "work by service" on a service page is `"related_work"` picked by hand, code
-  filtering the delivered case studies, or on a hosted page a `collection` block with `source`
-  and a filter on the service.
-- **Forms:** a new-business enquiry with `select` fields for budget and timeline, plus `hidden`
-  fields for campaign attribution.
-- **Structured data:** `Organization` in `siteSchema`, `Article` on case studies, `WebPage` on
-  services, `FAQPage` only where a service page shows real questions. A `Person` node per team
-  page is pasted `schema`.
-- **Pitfalls:** a logo wall with no alt text; client names retyped per page instead of
-  referenced; a testimonial with no record of consent (keep a `"consented_on"` `date`).
-
-## Corporate website
-
-Use for multiple audiences, brands, regions, business units, approval chains, or regulated statements. The main modeling problem is ownership: who can update a statement, which sites reuse it, and when it expires.
-
-### Route and model starter
-
-| Family | Example path | Owner and model |
-|---|---|---|
-| Corporate home | `/` | Global communications; static page |
-| Business units | `/businesses/{slug}/` | Collection if units share a template and lifecycle |
-| Products/services | Existing taxonomy | Collection or static pages by unit ownership |
-| Newsroom | `/news/`, `/news/{slug}/` | News collection, media contact, publish date |
-| Leadership | `/leadership/`, `/leadership/{slug}/` | People collection if profiles recur |
-| Careers | `/careers/` | Landing page; job details may remain in an ATS |
-| Investor / governance | `/investors/`, `/governance/` | Gated approval; files with version/date |
-| Policies and legal | `/privacy/`, `/terms/` | Static pages with accountable owner |
-| Contact / locations | `/contact/`, `/locations/{slug}/` | Form plus locations collection when needed |
-
-Do not copy ATS jobs, stock prices, investor filings, or regulated data into BetterCMS unless BetterCMS is deliberately the system of record. Preserve external systems and public links.
-
-### Governance and editor structure
-
-Record owner, reviewer, source of claim, effective date, review date, and version where these matter. Separate draft, legal-reviewed, approved, and published states with the project's own editorial board: read its stages and which one is the publish gate with `get_workflow_board` before `move_stage`, because stage keys are per project. Do not claim an approval stage exists if the board has none. Scope access and publishing by the product's real permissions. High-risk copy (financial figures, certifications, compliance claims, regulated products) needs a verified source and designated reviewer.
-
-Content sidebar: `Corporate pages`, `Business units`, `Newsroom`, `People`, `Investors`, `Legal`, `Regions` if used. Component groups: `Globals`, `Corporate identity`, `Business unit`, `Newsroom`, `Data/proof`. Distinguish sitewide global identity from unit-specific branding and local navigation. A shared global component should not overwrite an independently branded unit page.
-
-### Regions and languages
-
-Choose a deliberate URL strategy, such as `/{locale}/...` or regional domains. Keep locale-to-locale equivalent-page IDs, fallback behavior, canonical target, and language switcher destinations. Check what the connected project models for locales before planning; implement and verify `hreflang` output in the frontend, where the rendered head is decided. Do not auto-redirect by IP or index machine placeholders. Follow [Google's localized-page guidance](https://developers.google.com/search/docs/specialty/international/localized-versions).
-
-### Validation
-
-Test unit-specific nav/footers, ownership permissions, embargoed news, expiring files, superseded legal pages, regional links, localization fallbacks, 404/redirects, accessibility, and the published head for every major template. Separate search visibility from access control: `noindex` does not protect private information.
-
-## SaaS, AI, and enterprise technology website
-
-Use when a product site must explain a platform to multiple buyers and evaluators. Distinguish product truth, marketing interpretation, developer documentation, and live application behavior.
-
-### Route and model starter
-
-| Family | Example path | Suggested ownership |
-|---|---|---|
-| Home | `/` | Static marketing composition |
-| Product/platform | `/product/`, `/features/{slug}/` | Static overview; Features collection only if repeated and maintained |
-| Solutions | `/solutions/{slug}/` | Collection for distinct jobs-to-be-done/use cases |
-| Industries | `/industries/{slug}/` | Collection where sector-specific workflows/proof exist |
-| Integrations | `/integrations/{slug}/` | Collection with provider status, auth, capability, owner |
-| Customers | `/customers/{slug}/` | Case studies with approvals and proof sources |
-| Pricing | `/pricing/` | Static page or runtime-driven product data; one owner for actual pricing |
-| Resources | `/resources/{slug}/`, `/blog/{slug}/` | Editorial collections and their list pages |
-| Glossary | `/glossary/{term}/` | Definition collection with editorial gates |
-| Comparisons / alternatives | `/compare/{slug}/` | Dedicated reviewed model, never blind competitor templating |
-| Trust and legal | `/security/`, `/privacy/`, `/trust/` | Static pages or external trust center |
-| Docs / API | `/docs/...` | Often a separate docs system/repository; link rather than duplicate |
-| Conversion | `/demo/`, `/contact/` | Forms with routing, consent, and success states |
-
-These are options, not required pages. Keep existing routes and product naming. For a large enterprise site, consider ownership by product line/market and a shared navigation contract; avoid separate page schemas for identical layouts.
-
-### Model and section kit
-
-Entities: Solutions, Industries, Features, Integrations, Cases, Resources, Glossary Terms, and optional Comparisons. Use references across them so an integration or proof item updates once. Each entry needs an owner, lifecycle, canonical URL, native SEO metadata, and sufficient unique content. Integration entries need a clear status (live, beta, planned) and must never imply a planned connector is available.
-
-Shared sections: product hero, outcome grid, workflow steps, feature visual, integration grid, proof strip, case excerpt, FAQ, security/trust callout, pricing CTA. Keep a single component definition per visual family and use variants/instance overrides. Give buttons and media grouped editor controls. Expose only supported rich-text headings; a hero title may be plain text rendered as H1 while an article body may allow H2/H3, links, lists, and code if the renderer supports them.
-
-Content sidebar: `Core pages`, `Product`, `Solutions`, `Industries`, `Integrations`, `Customers`, `Resources`, `Trust`, `Other`. Component groups should reflect role, not route.
-
-### Search and AEO
-
-Build topic hubs and link related solution, industry, integration, case, and glossary pages. Only publish a specific solution × industry page when it adds differentiated workflow, evidence, and value. Answer questions directly with verifiable facts and useful context; do not fabricate FAQ, schema, or “AI answer” pages. Use [programmatic-seo.md](programmatic-seo.md) for generated page families and [Google's AI-search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) for the current search-policy boundary.
-
-### Validation
-
-Verify product claims against shipped capability, integration statuses, pricing consistency, demo form routing, docs links, internal topic paths, glossary duplicates, comparison accuracy, rendering of code/rich text, and desktop/mobile navigation. Noindex preview, gated assets, and incomplete pages.
-
-### Production detail
-
-| Collection | `urlPattern` | Fields |
-|---|---|---|
-| Case studies | `/customers/:slug` | `"customer"` `text`, `"logo"`, `"cover_image"` `image`, `"industry"` `reference`, `"excerpt"` `longtext`, `"metrics"` `repeater` (`"value"`, `"label"`, at most 3 rows), `"quote"` `reference` to Testimonials, `"body"` `document` with challenge, solution, results as H2s, `"facts"` `repeater` (`"label"`, `"value"`) |
-| Testimonials | none | `"quote"`, `"name"`, `"role"`, `"company"`, `"photo"`, `"logo"`, `"source"` `link`, `"consented_on"` `date`. `"rating"` `number` only when the source shows one |
-| Integrations | `/integrations/:slug` | `"logo"`, `"category"` `reference`, `"excerpt"`, `"body"` `document`, `"app_link"` `button`, `"docs_link"` `link`, `"is_native"` `boolean`, `"status"` `select` (live, beta, planned) |
-| Releases | `/changelog/:slug`, or none when releases are anchors on one page | `"version"` `text`, `"published_on"` `datetime`, `"changes"` `repeater` (`"kind"` `select`: new, improved, fixed; `"text"`), `"body"` `richtext` |
-| Comparisons | `/compare/:slug` | `"competitor"` `text`, `"competitor_logo"`, `"intro"` `longtext`, `"matrix"` `repeater` (`"feature"`, `"us"`, `"them"`), `"verified_on"` `date`, `"body"` `document` |
-
-- **Static until repeated:** feature and product pages stay static pages until three or more
-  share one layout. Pricing tiers stay in the pricing page's fields unless the same plans show
-  on two or more pages; then a Plans collection.
-- **Pricing:** store the monthly and the yearly price as two fields read from the source. Never
-  derive one from a discount. The full feature grid is a `repeater` whose row holds one value
-  per plan; inside a component it can be the `table` prop ([components.md](components.md)).
-- **Lists:** customer and integration hubs are one `collection` block each. Category filter
-  chips are code on a code-built site; otherwise leave them out and say so. A home logo wall is
-  a `repeater` of images, or a `multi-reference` when logos link to stories.
-- **Forms:** demo request and contact sales with `hidden` attribution fields, and a newsletter
-  form with `consent`. A gated asset is a form whose success state links the file.
-- **Structured data:** `Organization` and a `WebSite` node in `siteSchema`, `FAQPage` on the
-  pricing page (one per URL), `BlogPosting` on posts. `JobPosting` as the careers collection's
-  `schemaType`; `SoftwareApplication` is pasted `schema` from visible facts.
-- **Pitfalls:** "Trusted by 10,000 teams" style counters with no source (report as unverified);
-  a feature matrix pasted as an image; a screenshot holding the only copy of a claim.
-
-## Large ecommerce website
-
-Use for a catalog-heavy site regardless of commerce engine. The core choice is the boundary between **commerce facts** and **editorial merchandising**.
-
-### Source-of-truth contract
-
-Products, variants, SKUs, price, availability, tax, orders, checkout, customer accounts, and fulfillment normally belong to the commerce platform. BetterCMS owns editorial landing pages, category storytelling, buying guides, banners, proof, and selected product-page content blocks. A CMS reference to a product uses a stable external ID plus a verified lookup; don't silently duplicate transactional fields into editable CMS text.
-
-### Route and model starter
-
-| Family | Example path | Index policy |
-|---|---|---|
-| Home and campaigns | `/`, `/campaigns/{slug}/` | Public, unique campaigns |
-| Catalog root / category | `/shop/`, `/collections/{slug}/` | Curated category pages with products and links |
-| Product | `/products/{slug}/` | Available public products; decide retired-product policy |
-| Brand | `/brands/{slug}/` | Only substantive brand pages |
-| Buying guides | `/guides/{slug}/` | Unique advice with product references |
-| Editorial | `/stories/{slug}/` | Published articles |
-| Search, cart, account, checkout | Runtime routes | Usually excluded from sitemap; private data protected |
-| Filters and sort | Parameters on category routes | Explicit crawl/index policy; avoid unbounded URL combinations |
-
-Keep existing paths if the store already uses another taxonomy. Decide whether unavailable products stay indexable, redirect to a successor, or are unpublished and return 404 or a 410 rule, based on permanence and user value. Do not redirect every missing product to the homepage.
-
-### Editor model and reuse
-
-Models: Campaigns, Buying Guides, optional Brand and Category editorial records, plus product references. Category merchandising groups can include hero, intro, featured products, editorial cards, filters, and FAQs. Components: global store nav, search, promo bar, product card, variant selector, add-to-cart, category hero, recommendation rail, cart feedback. Commerce controls remain functional code tied to live data; an editor can change allowed presentation and copy but must not create an unfulfillable cart action.
-
-Content sidebar: `Campaigns`, `Collections`, `Guides`, `Stories`, `Store pages`; group media by campaigns/editorial needs. Content sidebar folders never change a URL; URL page folders do, and renaming one 301s its pages, so do not turn category folders into URL folders unless a route change is intended.
-
-### Crawl and scale
-
-Provide crawlable category → subcategory → product links and paginated result URLs. Decide which facet combinations deserve dedicated curated landing pages; keep the rest out of the index/crawl space by an intentional policy. Do not rely on canonical alone to control a near-infinite faceted URL space. Keep canonical, internal link, and sitemap URLs consistent. Sitemaps should include only eligible canonical pages and split before protocol limits. Product price/availability markup must match the current displayed commerce data; validate variant markup against Google's current `ProductGroup` guidance. [Google ecommerce structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure) · [Faceted navigation](https://developers.google.com/crawling/docs/faceted-navigation) · [Product variants](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
-
-### Validation
-
-Test a product with several variants, a sold-out product, missing image, empty category, deep pagination, filter combinations, mobile search, currency/market change, cart handoff, and changed price after cache expiry. Verify that sitemap counts match eligible catalog records and that deleted routes/redirects do not strand internal links.
-
-### Production detail
-
-Applies when BetterCMS renders product or category pages. A Shopify-backed store follows
-[shopify-headless.md](shopify-headless.md) first.
-
-| Collection | `urlPattern` | Fields |
-|---|---|---|
-| Products | `/products/:slug`, slug equal to the store handle | `"store_product_id"` `text` (migration metadata), `"excerpt"` `longtext`, `"story"` `document`, `"gallery"` `repeater` (`"image"`, `"caption"`; editorial images only), `"highlights"` `array` of text, `"specs"` `repeater` (`"label"`, `"value"`), `"care"` `richtext`, `"categories"` `multi-reference`, `"badge"` `select`, `"related"` `multi-reference` (at most 4), `"faqs"` `multi-reference` |
-| Categories | `/collections/:slug` | `"intro"` `longtext`, `"image"`, `"parent"` `reference` to Categories (one level), `"store_collection_id"` `text` |
-| FAQs (when shared) | none | `"question"` `text`, `"answer"` `richtext` |
-
-A catalogue with no commerce engine adds `"price"` and `"compare_at_price"` `number`, a
-`"currency"` `select` of ISO codes, `"sku"` `text`, `"is_in_stock"` `boolean`.
-
-- **Lists:** a category's product grid is code filtering by the category, or the store's own
-  listing. A "Staff picks" row is a `multi-reference`.
-- **Chrome:** header (search, account and cart are app state in code, never content), a promo
-  bar, a footer whose payment badges are a fixed set in code.
-- **Forms:** newsletter, contact, wholesale enquiry. Back-in-stock and checkout stay with the
-  store.
-- **Structured data:** `Product` only where price and availability are entry fields. When the
-  store owns them, the site's code emits `Product` with the live `Offer`; do not paste a frozen
-  price. `CollectionPage` on categories. `AggregateRating` only from a connected review source.
-- **Redirects:** facet and sort parameters canonical to the category. Cart, checkout, account
-  and search are noindex.
-- **Pitfalls:** price, stock, options or variants copied into content (they drift within a
-  day); one static page per product, or one entry per variant; a size guide as an image instead
-  of a `repeater`; typed review counts or star scores; editorial images hotlinked from the
-  store CDN instead of uploaded.
-
-## Directory or listings website
-
-Use when the source has hundreds of same-shaped detail pages (businesses, tools, venues,
-vendors), category and location hubs, filters, a "Submit a listing" form, often a map.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Home, submit, featured-listing pricing, about, contact | `/`, `/submit`, ... | Static pages |
-| Listings list and detail | `/listings`, `/listings/:slug` | Listings collection, dynamic page, `urlPattern` `/listings/:slug` |
-| Category hub | `/categories`, `/categories/:slug` | Categories collection |
-| Location hub | `/locations`, `/locations/:slug` | Locations collection (cities or regions) |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Listings | `"logo"`, `"cover_image"` `image`; `"excerpt"` `longtext`; `"body"` `document`; `"category"` `reference` (required); `"subcategories"` `multi-reference`; `"place"` `reference` to Locations; `"address"` `group`; `"map_pin"` `location`; `"website"` `link`; `"email"` `email`; `"phone"` `phone`; `"opening_hours"` `repeater` (`"day"` `select`, `"opens"`, `"closes"` `text`, `"is_closed"` `boolean`); `"amenities"` `array` of text, or `multi-reference` to Features when each has a page; `"facts"` `repeater` (`"label"`, `"value"`); `"gallery"` `repeater` (`"image"`, `"caption"`); `"social_links"` `repeater`; `"plan"` `select` (free, featured, premium); `"is_verified"` `boolean`; `"external_id"` `text` |
-| Categories | `"intro"` `longtext`, `"icon"` `image`, `"parent"` `reference` to Categories |
-| Locations | `"region"` `text`, `"country"` `select`, `"map_pin"` `location`, `"intro"` `longtext`, `"cover_image"` `image` |
-
-`"plan"`, `"is_verified"` and `"external_id"` are locked: `readOnly: "developer"` with a
-`lockReason`. A write without schema access that changes one is refused.
-
-- **Chrome:** header with search, footer, an announcement for featured-listing offers.
-- **Lists:** the all-listings page is a `collection` block. On a hosted page a category or
-  location hub is a block with `source` and a filter, A to Z is `sort`, featured first is
-  `pinnedIds`, and "related listings" is a filter on a `{{field}}` of the listing shown with
-  `excludeCurrent`. Numbered pagination needs the site's code: report the gap. Site search
-  uses the hosted index: run `refresh_search_index` after the import.
-- **Forms:** submit a listing, claim a listing, report a problem, contact. A submission never
-  publishes itself; an editor creates or updates the entry from the inbox.
-- **Structured data:** `schemaType: "LocalBusiness"` on listings that are places. Paste `schema`
-  when the page shows hours or coordinates, or needs a subtype. `CollectionPage` on hubs.
-- **Redirects:** nested source paths (`/:category/:listing`) become `/listings/:slug` plus one
-  301 each.
-- **Pitfalls:** filterable facts stored as free tags (use `select`, `reference`, `number`);
-  duplicate listings from several sources (match on website domain, phone or address before
-  creating); a one-line address when structured data needs the parts; a paid outbound link with
-  no `rel="sponsored"` (the `link` value carries no rel, so the rendering code adds it from
-  `"plan"`); hub pages with fewer than three listings left indexable (set noindex until they
-  grow); thousands of near-empty pages (run `generate_pages_from_dataset` with `dryRun: true`
-  first, and only for rows with real content).
-
-## Blog or publication
-
-Use when the source has dated articles with bylines, categories, an index and a feed.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Home (or the index itself), about, newsletter, contact | `/`, `/about`, ... | Static pages |
-| Post list and detail | `/blog`, `/blog/:slug` (or the site's own word, `/journal/:slug`) | Posts collection, `urlPattern` `/blog/:slug` |
-| Author | `/authors/:slug` | Authors collection |
-| Category, topic | `/category/:slug`, `/topics/:slug` | One collection per taxonomy the source really has |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Posts | `"dek"`, `"excerpt"` `longtext`; `"cover_image"` `image`; `"body"` `document`; `"authors"` `multi-reference` (at least one); `"category"` `reference`; `"topics"` `multi-reference`; `"published_on"`, `"updated_on"` `datetime`; `"series"` `reference`; `"is_featured"` `boolean`; `"related"` `multi-reference` (at most 3) only when the source curates them |
-| Authors | Title is the name. `"role"` `text`, `"photo"` `image`, `"bio"` `longtext`, `"social_links"` `repeater` |
-| Categories, Topics | `"intro"` `longtext` |
-
-- **Chrome:** header, footer with the newsletter form, announcement.
-- **Lists:** the index is a `collection` block, `order: "newest"`. It orders by creation time,
-  so import posts oldest first, or the list will not follow `"published_on"`. A block with
-  `source` takes `sort: "-published_on"` instead. Category, topic and author lists on a hosted
-  page are sourced blocks with a filter; numbered pagination needs the site's code. A pinned
-  feature slot is `pinnedIds` on a sourced block, or a `reference` on the index page.
-- **Forms:** newsletter with `consent`, contact, tips.
-- **Structured data:** `BlogPosting` or `Article` as the collection default in
-  `collectionSchemaTypes`; `Blog` on the index. `NewsArticle` is pasted `schema`; an author page takes
-  `schemaType: "Person"`. Turn the feed on in `rssConfig`; item links come from
-  the `urlPattern`. A syndicated post keeps its cross-site canonical in the entry's `meta`.
-- **Redirects:** dated WordPress paths (`/2024/05/my-post/`) become `/blog/:slug` with a 301
-  per post.
-- **Pitfalls:** share bars, author boxes and related cards inside the body (they are template
-  sections); an H1 inside the body, or the cover repeated as the first body image; authors as
-  strings; a stored reading time (compute it); WordPress shortcodes (`[gallery]`, `[caption]`)
-  left as text (map them to a Portable Text block or a component, report unknown ones); tags
-  and categories that duplicate each other.
-
-## Docs or knowledge base
-
-Use when the source has a left navigation tree, "On this page" anchors, code blocks,
-admonitions, a version switcher, search, "Was this helpful?".
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Docs home, support home, contact support | `/docs`, `/support`, ... | Static pages |
-| Doc page | `/docs/:slug` | Docs collection |
-| Versioned docs | `/docs/v2/:slug` | One collection per supported major version, each with its own fixed-prefix `urlPattern` |
-| Knowledge-base article | `/help/:slug` | KB articles collection |
-| Glossary | `/glossary`, `/glossary/:slug` | Terms collection ([programmatic-seo.md](programmatic-seo.md)) |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Docs | `"excerpt"` `longtext`; `"body"` `document`; `"section"` `reference` to Doc sections (required); `"parent"` `reference` to Docs (at most 3 levels); `"order"` `number`; `"status"` `select` (new, beta, deprecated); `"last_reviewed_on"` `date` |
-| Doc sections | `"icon"` `image`, `"order"` `number` |
-| KB articles | `"body"` `document`, `"category"` `reference`, `"related"` `multi-reference` |
-| Terms | `"definition"` `richtext`, `"related"` `multi-reference` |
-
-- **Chrome:** header with search and footer in the Global Layout. The sidebar tree is rendered
-  by code from `"section"`, `"parent"` and `"order"`; previous and next links and "On this page"
-  are derived the same way. Curate the tree in the Layout only when the source hand-orders it.
-- **Lists:** a section landing page ordered by `"order"` is a `collection` block with `source`,
-  a filter on `"section"` and `sort: "order"` on a hosted page, or the site's code. Run
-  `refresh_search_index` after the import.
-- **Forms:** a one-question feedback form (`radio` plus a `hidden` page path), contact support.
-- **Structured data:** `Article` or `WebPage`; `FAQPage` only on real question pages. A deprecated version is noindex or canonicals to the current one.
-- **Redirects:** relative `.md` links in source files resolve to the target entry's URL. A
-  nested source path (`/docs/guides/setup/install`) becomes `/docs/:slug` plus a 301.
-- **Pitfalls:** the navigation tree copied by hand (it drifts); admonitions flattened to
-  blockquotes with the tone lost (map each to an embedded block that keeps its tone,
-  [portable-text.md](portable-text.md)); code as images or highlighted markup (a `bcmsCode`
-  block keeps the plain text and a language); MDX components with no
-  equivalent (map known ones to components, report the rest as logic left in code); an OpenAPI
-  reference converted by hand (it is generated from the spec: link or embed it and report it).
-
-## Local business or restaurant
-
-Use when the source shows an address, hours, a phone number, a menu, "Book a table", a map, and
-one or a few locations.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| One location | `/visit` | Static page; address and hours live once in the Global Layout |
-| Two or more locations | `/locations`, `/locations/:slug` | Locations collection |
-| Menu | `/menu`, or `/menus/:slug` | A page section; a Menus collection when menus differ per location or season |
-| Events, specials | `/events/:slug` | Collections only when dated |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Locations | `"address"` `group`; `"map_pin"` `location`; `"phone"` `phone`; `"email"` `email`; `"opening_hours"` `repeater` (`"day"` `select`, `"opens"`, `"closes"` `text`, `"is_closed"` `boolean`); `"special_hours"` `repeater` (`"date"` `date`, `"opens"`, `"closes"`, `"is_closed"`, `"note"`); `"time_zone"` `text`; `"cover_image"` `image`; `"menus"` `multi-reference`; `"booking_provider"` `select`; `"booking_id"` `text` |
-| Menus | Title is "Dinner", "Brunch". `"sections"` `repeater` (`"title"`, `"items"` `repeater`: `"name"`, `"description"`, `"price"` `number`, `"dietary"` `array` of text, `"is_new"` `boolean`); `"notes"` `longtext` (allergen statement); `"pdf"` `file` (a download, never the only copy) |
-| Events, Specials | `"starts_at"`, `"ends_at"` `datetime`; `"place"` `reference` to Locations; `"body"` `richtext`; `"image"` |
-
-Give `"opens"` and `"closes"` help text with the format (24-hour `HH:MM`). The currency is a
-site setting in code, not a symbol typed into each price.
-
-- **Chrome:** header with a booking button that links to the provider; footer listing
-  locations. Hours appear in one source: with a Locations collection the footer renders from
-  the entries in code, otherwise from the Global Layout.
-- **Forms:** private-events enquiry, contact, newsletter. Reservations are the provider's
-  embed, stored as provider and id only.
-- **Structured data:** `schemaType: "LocalBusiness"` gives name, phone, email and a one-line
-  address. Hours, geo, a structured postal address and the `Restaurant` subtype need pasted
-  `schema` built from the fields. Same name, address and phone everywhere. `Event` on events.
-- **Redirects:** a single-location site that grows to several moves `/visit` to
-  `/locations/:slug` with a 301.
-- **Pitfalls:** a menu as a PDF or image only; hours typed in the footer, the contact page and
-  the location page; prices as "$14" strings; "Closed" typed as a time; holiday hours
-  forgotten; Google reviews copied as testimonials (connect the source or get consent).
-
-## Events or conference
-
-Use when the source shows dates with times, an agenda, speakers, tickets, a venue, sponsors, a
-countdown.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Current edition home, tickets, travel, code of conduct, call for papers | `/`, `/tickets`, ... | Static pages |
-| Event | `/events`, `/events/:slug` | Events collection |
-| Session | `/sessions/:slug` | Sessions collection |
-| Speaker | `/speakers`, `/speakers/:slug` | Speakers collection |
-| Venue, sponsor | none unless the source has pages | Venues, Sponsors collections |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Events | `"starts_at"`, `"ends_at"` `datetime`; `"time_zone"` `text`; `"status"` `select` (scheduled, postponed, rescheduled, cancelled, moved online); `"attendance"` `select` (in person, online, mixed); `"venue"` `reference`; `"excerpt"`; `"cover_image"`; `"body"` `document`; `"tickets_button"` `button`; `"tickets"` `repeater` (`"name"`, `"price"` `number`, `"currency"` `select`, `"availability"` `select`) only when no ticketing provider owns them; `"speakers"`, `"sponsors"` `multi-reference` |
-| Sessions | `"event"` `reference`; `"starts_at"`, `"ends_at"`; `"room"` `text`; `"track"` `reference` or `select`; `"format"` `select` (talk, workshop, panel, break); `"level"` `select`; `"speakers"` `multi-reference`; `"description"` `richtext`; `"recording_url"` `link` |
-| Speakers | Title is the name. `"role"`, `"company"`, `"photo"`, `"bio"`, `"social_links"` |
-| Venues | `"address"` `group`, `"map_pin"` `location`, `"accessibility"`, `"directions"` `richtext` |
-| Sponsors | `"logo"`, `"tier"` `select`, `"website"` `link` |
-
-- **Chrome:** header with a tickets button; an announcement bar whose countdown end is one
-  `datetime` with its zone, and whose Section `window` ends with it. Never migrate a countdown
-  that resets per visitor.
-- **Lists:** a `collection` block with `source` sorts by `"starts_at"`, but its filter values
-  are fixed: none means "today". Upcoming and past lists, and an agenda grouped by day and
-  track, are the site's code filtering on `"starts_at"`. State that in the report; do not fake
-  it with two hand-kept lists.
-- **Forms:** registration (or the ticketing provider's embed), call for papers (links only, no
-  upload), sponsor enquiry, newsletter.
-- **Structured data:** `schemaType: "Event"` gives name, dates and a location name. Event
-  status, attendance mode, a `Place` with address or a `VirtualLocation`, offers from visible
-  ticket prices and performers need pasted `schema`.
-- **Redirects:** past events keep their URLs and stay published. A yearly path
-  (`/2025/schedule/talk-name`) becomes `/sessions/:slug` plus a 301.
-- **Pitfalls:** times with no zone (ask when the site shows none); the agenda as an image or
-  PDF only; speakers retyped per session; past events deleted; a sponsor link with no
-  `rel="sponsored"` in the rendering code.
-
-## Course or education
-
-Use when the source has courses with a curriculum, instructors, levels, durations, enrol
-buttons, cohorts.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Home, catalogue hub, pricing, for teams, FAQ | `/`, `/courses`, ... | Static pages; the hub holds the `collection` block |
-| Course | `/courses/:slug` | Courses collection |
-| Instructor | `/instructors/:slug` | Instructors collection |
-| Cohort | none | Cohorts collection, only when dated |
-
-Lesson content behind a login belongs to the LMS, not BetterCMS.
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Courses | `"excerpt"`; `"cover_image"`; `"level"` `select`; `"duration"` `text` (ISO 8601, `PT6H30M`); `"category"` `reference`; `"instructors"` `multi-reference`; `"outcomes"`, `"prerequisites"` `array` of text; `"curriculum"` `repeater` (`"title"`, `"lessons"` `repeater`: `"title"`, `"duration"`, `"is_preview"` `boolean`); `"enrol_button"` `button`; `"lms_course_id"` `text`; `"price"` `number` only when no checkout owns it |
-| Cohorts | `"course"` `reference`; `"starts_at"`, `"ends_at"` `datetime`; `"time_zone"` `text`; `"seats"` `text` only when shown; `"status"` `select` |
-| Instructors | Title is the name. `"role"`, `"photo"`, `"bio"` |
-
-- **Chrome:** header with a sign-in link to the LMS, footer.
-- **Lists:** the catalogue is a `collection` block; category and level filter chips need the
-  site's code. A fixed category or level list on a hosted page is a block with `source` and a
-  filter. An instructor's courses are a `multi-reference` or code.
-- **Forms:** waitlist, team enquiry, newsletter.
-- **Structured data:** `Course` as the collection's `schemaType` (name, description, provider);
-  offers and course instances from cohorts need pasted `schema`. `FAQPage` on a course with a real FAQ.
-- **Redirects:** LMS marketing paths (`/p/course-name`) become `/courses/:slug` plus 301s.
-- **Pitfalls:** stored totals ("6 modules, 42 lessons, 8 hours"); lesson videos or paid content
-  copied in; cohort dates with no zone; prices copied from the checkout.
-
-## Job board or careers
-
-Use when the source lists open roles by department, location tags, Apply buttons, Greenhouse,
-Lever or Ashby links, salary ranges, `JobPosting` JSON-LD.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Careers home, benefits, culture, hiring process | `/careers`, ... | Static pages |
-| Job | `/careers/:slug` or `/jobs/:slug` | Jobs collection |
-| Department | `/departments/:slug`, only if the source has them | Departments collection |
-| Employer (multi-company boards) | `/companies/:slug` | Employers collection |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Jobs | `"department"` `reference`; `"offices"` `multi-reference` to Locations; `"workplace"` `select` (on site, hybrid, remote); `"employment_type"` `select` (full time, part time, contract, internship); `"salary"` `group` (`"min"`, `"max"` `number`, `"currency"`, `"period"` `select`) only when shown; `"excerpt"`; `"body"` `document`; `"apply_button"` `button` (the ATS URL); `"posted_on"` `date`; `"closes_at"` `datetime`; `"status"` `select` (open, closed); `"ats_job_id"` `text` |
-| Departments | `"intro"` `longtext` |
-| Employers | `"logo"`, `"about"` `richtext`, `"website"` `link` |
-
-- **Chrome:** the header carries a "Careers" link; no separate chrome.
-- **Lists:** open roles grouped by department with location filter chips need the site's code.
-  On a hosted page a `collection` block with `source` and a filter on `"status"` lists the open
-  jobs, one block per department when the source groups them; set `emptyText` for "no open
-  roles".
-- **Forms:** applications go to the ATS. Forms have no file upload, so never collect a CV in a
-  BetterCMS form. A "Stay in touch" form is fine.
-- **Structured data:** `JobPosting` as the collection's `schemaType`: it fills title,
-  description, posted date, valid through, employment type, hiring organisation and job location
-  from the entry's fields, and is not emitted without a company and a posting date. A remote type
-  with applicant location requirements, or a base salary, needs pasted `schema`, only when
-  visible. Unpublish the entry when the job closes.
-- **Redirects:** closed jobs keep their URLs. ATS-hosted paths that move onto the site get a
-  301 where the old host allows one.
-- **Pitfalls:** hand-copying an ATS (sync by `"ats_job_id"` in code or link out, and report
-  which); deleting closed jobs; one job duplicated per city; invented salaries.
-
-## Real estate or property listings
-
-Use when the source has properties with price, beds, baths, area, status, galleries, floor
-plans, map search, agents, a viewing request form.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Home, valuation, sell, let, about, contact | `/`, `/valuation`, ... | Static pages |
-| Property | `/properties`, `/properties/:slug` | Properties collection |
-| Area guide | `/areas/:slug` | Areas collection |
-| Agent | `/agents/:slug` | Agents collection |
-| Office | `/offices/:slug` | Offices collection, fields as Locations in [Local business](#local-business-or-restaurant) |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Properties | Title is the display address or name. `"status"` `select` (for sale, for rent, under offer, sold, let); `"listing_type"` `select` (sale, rent); `"price"` `number`; `"currency"` `select`; `"price_period"` `select` (month, week); `"price_qualifier"` `select` (guide price, offers over, price on application); `"address"` `group`; `"map_pin"` `location`; `"property_type"` `select`; `"bedrooms"`, `"bathrooms"`, `"receptions"`, `"area"` `number`; `"area_unit"` `select`; `"features"` `array` of text; `"body"` `document`; `"gallery"` `repeater` (`"image"`, `"caption"`; at least one); `"floor_plans"` `repeater` of images with alt; `"virtual_tour"` `link`; `"energy_rating"` `select`; `"facts"` `repeater` (`"label"`, `"value"`); `"agent"`, `"office"`, `"area_guide"` `reference`; `"available_from"` `date`; `"feed_id"` `text` |
-| Agents | Title is the name. `"role"`, `"photo"`, `"phone"` `phone`, `"email"` `email`, `"office"` `reference` |
-| Areas | `"intro"`, `"cover_image"`, `"body"` `document`, `"map_pin"` `location` |
-
-- **Chrome:** header with a valuation button, footer listing offices.
-- **Lists:** search by area, type, price band and bedrooms, the map view and "similar
-  properties" need the site's code or the CRM's search. On a hosted page a `collection` block
-  with `source` gives a fixed list (one area, one type), never a visitor's search.
-- **Forms:** viewing request with the property passed in a `hidden` field, valuation request,
-  contact.
-- **Structured data:** `RealEstateListing` with an `Offer` is pasted `schema` from visible
-  facts. `schemaType: "LocalBusiness"` on offices. A portal copy keeps the canonical on this
-  site.
-- **Redirects:** sold and let properties keep their URLs and stay published. Portal-style
-  paths (`/for-sale/london/3-bed-flat-12345`) become `/properties/:slug` plus 301s.
-- **Pitfalls:** prices as strings ("£450,000"); status typed into the title ("SOLD - 3
-  bed..."); listings hand-imported when a CRM feed owns them (sync by `"feed_id"` in code and
-  report it); images hotlinked from the feed host; floor plans with no alt text; sold
-  properties deleted.
-
-## Nonprofit
-
-Use when the source has a Donate button, programs, impact numbers, stories, annual reports,
-volunteers, a charity number.
-
-### Routes
-
-| Family | Path | Model |
-|---|---|---|
-| Home, mission, impact, donate, get involved, contact | `/`, `/donate`, ... | Static pages |
-| Program or campaign | `/programs/:slug` | Programs collection |
-| Story, news | `/stories/:slug` | Stories collection, post fields from [Blog](#blog-or-publication) |
-| Report | `/reports/:slug` | Reports collection |
-| Events | `/events/:slug` | As [Events](#events-or-conference) |
-| Team and board, partners | none unless the source has pages | People, Partners collections |
-
-### Collections
-
-| Collection | Fields |
-|---|---|
-| Programs | `"excerpt"`; `"cover_image"`; `"body"` `document`; `"impact"` `repeater` (`"value"`, `"label"`, `"as_of"` `date`, `"source"` `link`); `"place"` `reference`; `"is_active"` `boolean`; `"donate_button"` `button` |
-| Stories | Post fields, plus `"consented_on"` `date` for any person shown |
-| Reports | `"year"` `number`; `"file"` `file`; `"cover_image"`; `"summary"` `richtext` holding the key facts as text |
-| Partners | `"logo"`, `"tier"` `select`, `"website"` `link` |
-| People | `"role"`, `"photo"`, `"bio"`, `"team"` `select` (staff, board, advisors) |
-
-- **Chrome:** header with a Donate button; footer with the registered charity number, kept
-  once in the Global Layout.
-- **Donations:** the payment provider (Stripe, Donorbox, Classy, GiveWP) owns amounts,
-  recurring options and payment fields. Store the provider and its id, plus the copy around
-  the widget. The widget script stays code.
-- **Forms:** volunteer sign-up, newsletter, contact, event registration. Never payment details.
-- **Structured data:** `Organization` in `siteSchema` (`NGO` when it fits) with the registered
-  number, `Article` on stories, `Event` on events.
-- **Redirects:** campaign microsite URLs that fold into the main site get 301s to the program.
-- **Pitfalls:** impact numbers with no date or source (fill `"as_of"` and `"source"`, report
-  the rest as unverified); beneficiary photos and stories with no recorded consent (report as
-  rights unconfirmed); annual reports only as PDFs.
-
-## Multi-brand and multi-language
-
-Use when the source has several brands on one design system, `hreflang` alternates, `/de/` and
-`/fr/` paths or country domains, or a language switcher.
-
-### Multi-brand
-
-| Decision | Rule |
-|---|---|
-| Project boundary | One project per brand and domain. Each has its own brand kit, tokens, Global Layout and SEO settings |
-| Starting a new brand | Build one template project, then `clone_project` per brand. The clone copies pages, models, entries, components, media, forms and SEO settings; it leaves out submissions, analytics, domains and secrets |
-| Shared sections | The cloned components. After the clone they are separate copies: a later change is applied per project |
-| Shared content | Projects cannot reference each other's entries. Copy it and note where it came from, or serve it from one project that every brand's code reads. Report the choice |
-| Routes | Each brand keeps its own routes and `urlPattern` values; identical patterns across brands are fine |
-| Structured data | One `Organization` per brand in its own `siteSchema`. A parent company is a `parentOrganization` property, not a shared node |
-
-### Multi-language
-
-Full method: [localization.md](localization.md). The decisions that shape a blueprint:
-
-- A translation is its own page or entry carrying `locale` and `translationOf` (the source id).
-  Per-field localization does not exist. Never model `"title_en"` beside `"title_fr"`.
-- When crawls disagree on the default locale, take the one the root path serves and report
-  it; do not ask. The default fills the source rows; every other locale links back to them.
-- Match sections across locales by position and structure, never by text.
-- Never translate during a conversion. Copy what each locale publishes; report missing
-  translations. `translate_entry` creates drafts, costs AI credits and runs only on request.
-- Slugs are per locale; keep each locale's URLs. Alt text is copy and is translated; the image
-  is shared unless a locale shows a different one.
-- `hreflang` is never a field. The sitemap emits it from `locale` and `translationOf`; the
-  hosted head does not, so a site that needs it in the head renders the links in its own code.
-- A market page with a different structure (a US-only pricing page) is a separate page, not a
-  translation. A per-market header is a Layout locale variant, not a translation of copy.
-- **Structured data:** one canonical per locale. Never canonical every locale to the default.
-- **Redirects:** no IP-based redirects. A retired locale 301s to the default locale's page.
-- **Pitfalls:** machine translation during import; one model with a field per language; a
-  switcher linking to a page that exists in one locale only.
+---
+title: "Site blueprints"
+description: "Route, collection, form, structured-data and redirect plans per business type: portfolio, agency, corporate, SaaS/AI, ecommerce, directory, blog or publication, docs or knowledge base, local business or restaurant, events, course, job board, real estate, nonprofit and multi-brand."
+---
+
+# Site blueprints by business type
+
+A route and content model that fits the business, while editor folders, public URLs and reusable
+components stay separate. A blueprint is a starting hypothesis, not permission to replace a
+working site's taxonomy. The platform rules behind each layer are in
+[content-modeling.md](content-modeling.md).
+
+## Contents
+
+- [Common decision process](#common-decision-process)
+- [Starter rules](#starter-rules)
+- [Deliverables](#deliverables)
+- [Production shapes every blueprint uses](#production-shapes-every-blueprint-uses): foundations,
+  field types, list limits, URL limits, structured data, forms, checklist
+- Catalogs, read only the one that matches (a mixed site can use two, but give each page family
+  one route owner):
+  - [Portfolio](#portfolio-website): a person or studio presents selected work, services and a
+    contact path
+  - [Agency](#agency-website): services, sectors, proof and lead generation drive the site
+  - [Corporate](#corporate-website): several business units, regions, audiences, governance or
+    regulated content coexist
+  - [SaaS, AI, enterprise tech](#saas-ai-and-enterprise-technology-website): product,
+    solutions, industries, integrations, trust and education need separate models
+  - [Large ecommerce](#large-ecommerce-website): catalog, categories, products and shopping
+    journeys dominate; a Shopify-backed store also reads [shopify-headless.md](shopify-headless.md)
+  - [Directory](#directory-or-listings-website): hundreds of same-shaped listings with category
+    and location hubs
+  - [Blog / publication](#blog-or-publication): dated articles with bylines, taxonomy and a feed
+  - [Docs / knowledge base](#docs-or-knowledge-base): a navigation tree, code, versions, search
+  - [Local business / restaurant](#local-business-or-restaurant): address, hours, menu, booking
+  - [Events](#events-or-conference): dated events, agenda, speakers, venue, sponsors
+  - [Course](#course-or-education): courses, curriculum, instructors, cohorts
+  - [Job board](#job-board-or-careers): open roles, departments, an ATS
+  - [Real estate](#real-estate-or-property-listings): properties, agents, offices, areas
+  - [Nonprofit](#nonprofit): programs, impact, stories, reports, donations
+  - [Multi-brand](#multi-brand-and-multi-language): several brands or languages on one design
+    system
+
+Data-generated page families (glossary, integrations, locations): [programmatic-seo.md](programmatic-seo.md).
+
+## Common decision process
+
+1. Inventory existing public URLs, navigation, templates, source content, business goals,
+   locales, owners, analytics and design tokens. Keep established URLs and brand rules unless a
+   change is in scope.
+2. Give each family a **source of truth**: a BetterCMS page, a collection entry, an external
+   system (commerce, ATS, docs), or application runtime. Name its editorial owner and publishing
+   gate. Record capabilities BetterCMS does not have as gaps; never invent fields that imply
+   them.
+3. Produce a route matrix: pattern, purpose, static / list / detail, content source, template,
+   canonical, indexability, sitemap eligibility, and the redirect it replaces. A collection's
+   list is a page; its entries render through one dynamic detail page.
+4. Produce a model matrix: fields and groups, references, taxonomy, reusable sections, global
+   nav/footer, labels, and variants. Components for reusable presentation, collections for
+   entities with their own lifecycle. Whether bands become components or fields follows
+   `authoringPreference` from `get_project`, which only the owner answers.
+5. Propose **Content sidebar** folders for editor tasks, **component groups** for definitions,
+   and **media folders** for assets. None of these changes a URL. **URL page folders** do change
+   paths, and renaming one 301s its pages, so they need explicit review. Sidebar doctrine:
+   `bettercms://playbook/structure`.
+6. Define per-family SEO policy: one canonical target, real indexable content, native SEO
+   metadata (never modelled fields, §5b of `bettercms://playbook/schema`), structured data only
+   where visible facts support it, and the treatment of filters, search, pagination, drafts,
+   gated pages and deleted records. Pages marked noindex are left out of the generated sitemap.
+7. Validate one representative route per family and the edge cases: empty collection, long
+   title, unpublished detail, duplicate slug, moved URL, mobile nav, optional section, locale,
+   no-result state. Confirm edit, preview and public render, then the build and binding reports.
+
+## Starter rules
+
+- Reference page lists illustrate common shapes; do not create pages the business does not have.
+- Prefer a few stable, human-readable route patterns. The best URL is often the existing one.
+- Keep a slug unique within its route namespace; check static against dynamic paths and locales.
+  When a published URL changes, add a redirect (`create_redirect`).
+- Keep a dedicated 404 and access/error pages. Leave drafts, private areas, internal search,
+  parameter duplicates and 404s out of the sitemap.
+- Sitemaps hold absolute, canonical, indexable URLs; Google documents a limit of 50,000 URLs /
+  50 MB uncompressed per file. [Google sitemap guide](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
+- Content sidebar folders are navigation for editors. Public hierarchy comes from routes and
+  internal links, never from folder labels. [Google ecommerce site structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure)
+- With locale variants, keep explicit equivalent-page mappings and one `hreflang`
+  implementation, verified in the rendered head. [Google localized versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
+
+## Deliverables
+
+Return a route tree, route matrix, content and model matrix, folder plan, component inventory,
+sitemap and redirect policy, open ownership decisions, and a phased implementation plan. On a
+live project, implement only the scope the user asked for and verify the routes you touched.
+
+## Production shapes every blueprint uses
+
+Read this once; every catalog below assumes it. A site is often two types (a SaaS site with a
+blog and docs): open each matching catalog, merge them, and create shared collections (Authors,
+Topics, FAQs, Testimonials) once. Drop any collection the source does not have.
+
+### Foundations
+
+| Piece | Where it lives |
+|---|---|
+| Header, footer, announcement bar | Global Layout via `update_layout`. Never a page section. Footer link columns are a repeater of groups; the newsletter box points at a form. A bar or promo that runs for a period takes a `window` on its Section, and a seasonal band one on its page block ([publishing.md](publishing.md) §6) |
+| Company name, address, phone, social profiles | One place in the Global Layout, read by the footer and the contact page. Site JSON-LD repeats it once in `siteSchema` (`update_seo`) |
+| Cookie consent | A third-party consent tool stays code. Report it; do not rebuild it as content |
+| 404, legal, thank-you pages | Static pages in a `System` Content sidebar folder. Thank-you pages are noindex |
+| Meta and structured data | Native per page and entry, site defaults with `update_seo` ([seo.md](seo.md)). Never modelled |
+
+### Field types
+
+Field keys below are entry keys in one flat namespace per model. `title` and the slug are on
+every entry and are not repeated in the tables. SEO fields are never listed.
+
+| The source shows | Production field |
+|---|---|
+| Short text, long plain text | `text`, `longtext` |
+| The one long body | `document` (one per model, top level). Shorter formatted copy is `richtext` |
+| Image, download | `image`, `file` |
+| Postal address | `group` of `text` children: `"street"`, `"city"`, `"region"`, `"postal_code"`, `"country"` |
+| Map pin | `location` (lat, lng, optional label). Never two text fields |
+| Tags, amenities, bullet lists | `array` with `itemType: "text"`. One choice from a fixed list is `select` |
+| Rows of the same shape (hours, facts, metrics, tickets) | `repeater` of `text`, `number`, `select`, `boolean` children |
+| Mixed ordered blocks in a case study | one component per block shape, placed as sections |
+| One or many other entries | `reference`, `multi-reference`. A missing target is refused on write |
+| Call to action | `button` (label and link in one value). A bare link is `link`; also `email`; a phone number is `text` |
+| Date, date and time | `date`, `datetime`. Keep the zone as a `text` IANA name beside it when the site shows times |
+| A spec or comparison table | `repeater` with one field per column (any field type). There is no separate table field type |
+
+An external system's id (`"store_product_id"`, `"ats_job_id"`, `"feed_id"`, `"lms_course_id"`)
+is a `text` field kept as migration metadata and locked: `readOnly: "developer"` with a
+`lockReason` naming the system it comes from. Place it last. A write that changes it without
+schema access is refused (403 FIELD_LOCKED). The lock is enforced on entries only.
+
+### Lists
+
+A collection's list is its own dynamic page holding one `collection` block. The block takes
+`limit` (1 to 200, default 20), `order` (`newest` or `oldest`, by creation time), `emptyText`,
+and optional card and detail components. Entry URLs are that page's path plus the entry slug.
+
+With `source: { modelId }` the block lists that collection on any hosted page, and takes
+`filters` (max 5; `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`), `sort`
+(`-publishedAt,title`), `pinnedIds` (max 10, shown first) and `excludeCurrent`. In an article
+template a filter value may be `{{field}}` of the entry shown. Filter values are stored on the
+block: a visitor cannot change them, and none means "today".
+
+Not available: pagination, grouping, visitor-driven filters. Only the hosted renderer draws the
+block; a route built from the repo's code queries the Delivery API with the same filter grammar.
+So for each hub the source has, choose and report one of:
+
+| Source list | Production shape |
+|---|---|
+| All entries, newest first | The `collection` block |
+| Filtered by category, location or status | On a hosted page a `collection` block with `source` and `filters`. On a code-built site the site's own code filters the delivered entries |
+| Sorted by a field (A to Z, a date, an order number) | `sort` on a sourced block |
+| Upcoming or past, by today's date | The site's code, or a `"status"` field the block filters on |
+| "Related" row | On a hosted template, a sourced block filtered by a `{{field}}` of the entry shown, with `excludeCurrent` |
+| "Featured" row | `pinnedIds`, a filter on a featured flag, or a short `multi-reference` chosen by hand |
+| Numbered pages, groups under headings, filter chips | The site's code |
+| Counts ("1,240 venues", "42 lessons") | Rendered by code from the entries. Never typed into copy |
+
+### URLs and redirects
+
+- Every collection gets a `urlPattern` holding `:slug` exactly once (`/blog/:slug`). A fixed
+  multi-segment prefix is valid (`/docs/v2/:slug`).
+- Nested (`/:category/:listing`) and dated (`/2024/05/my-post/`) source paths cannot be
+  expressed. Use the flat pattern and add one `create_redirect` (301) per old URL.
+- A slug change on an entry with a pattern 301s by itself.
+- Redirect types are 301, 302, 307, 308 and 410. A retired entry either stays published and
+  marked ended, redirects to a successor, or is unpublished and answers 410 (`create_redirect`
+  with `redirectType: "410"`, no destination).
+
+### Structured data
+
+Order: Automatic, then `schemaType`, then pasted `schema`. `schemaType` accepts `WebPage`,
+`AboutPage`, `ContactPage`, `CollectionPage`, `Blog`, `BlogPosting`, `Article`, `Product`,
+`FAQPage`, `Event`, `Organization`, `LocalBusiness`, `JobPosting`, `Course`, `Recipe`, `HowTo`,
+`Service`, `Person`, `VideoObject`. What the common ones emit from the content:
+
+| `schemaType` | Emits |
+|---|---|
+| `BlogPosting`, `Article` | Headline, description, image, published and modified dates, author |
+| `Product` | Name, description, image, SKU, offer |
+| `Event` | Name, description, image, start, end, a location name |
+| `LocalBusiness`, `Organization` | Name, description, URL, image or logo, telephone, email, address as one line |
+| `FAQPage` | The page's question and answer pairs. Never automatic |
+
+Anything richer is pasted `schema` built only from facts visible on the page: opening hours, geo
+coordinates, event status and offers, salary, `RealEstateListing`, `Restaurant`,
+`SoftwareApplication`, `NewsArticle`. A hosted page gets its `BreadcrumbList` automatically. Set a
+collection-wide default in `collectionSchemaTypes`. Never a self-serving `AggregateRating`.
+
+### Forms
+
+Thirteen field types: `text`, `textarea`, `email`, `phone`, `number`, `url`, `date`, `select`,
+`radio`, `checkbox`, `checkboxes`, `consent`, `hidden`, plus the `step` divider for multi-step forms. No file upload, so CVs, floor plans and
+attachments go to the external system. Payment details never go in a form. Submissions land in
+the inbox; an editor turns one into an entry. Full pipeline:
+[forms-and-interactions.md](forms-and-interactions.md).
+
+### Checklist
+
+- Every collection exists in the source, or was dropped on purpose.
+- Shared collections exist once across merged catalogs.
+- Store, ATS, LMS and feed facts are ids, never copies.
+- Every list has `emptyText` and a stated shape for each filter the source had.
+- Every collection has a `urlPattern`; every changed URL has a 301.
+- Structured data is built from visible fields, with the type its catalog names.
+
+### Built-in sections
+
+The section library ships 23 platform blueprints in 17 families, so a standard band needs no new
+component: Hero, Feature grid (three, two, bento), Feature rows, Steps, Timeline, Stats, Logo cloud,
+Testimonial (quote, three cards), Team, Case study, Comparison, Pricing, FAQ, Call to action,
+Capture (newsletter band) and Listing (latest, related). Read one with `list_components`; inline its
+`blockJson` as a `section` block for a one-off band, or copy it with `create_component` `from:
+"builtin:<key>"` for a recurring one (see [components.md](components.md)). Two ship unbound on purpose: the Capture form has no form until you
+set its `form` prop, and both Listing layouts list the page's own entries until you give them a
+`source`; each shows its empty text meanwhile. Not available as a section, so build it in the repo
+or leave it out: mega menu, docs sidebar, cookie consent, exit intent, store locator, map, billing
+toggle, countdown and anything commerce.
+
+## Portfolio website
+
+Use this when the primary job is to show selected work and make an individual or small studio credible. First determine whether the work is private, client-approved, dated, or still under embargo.
+
+### Route and model starter
+
+| Family | Example path | BetterCMS model | Index and sitemap |
+|---|---|---|---|
+| Home | `/` | Static page with selected projects and clear contact action | Yes |
+| Work index | `/work/` | Static index page querying Projects | Yes if substantive |
+| Project detail | `/work/{slug}/` | Projects collection + one dynamic template | Published, approved projects only |
+| About / services | `/about/`, `/services/` | Static pages unless services need independent owners and detail pages | If public and useful |
+| Writing / speaking | `/writing/`, `/writing/{slug}/` | Optional collection and index | Published articles only |
+| Contact | `/contact/` | Static page + form | Usually yes |
+| Password/preview case study | Existing route | Other page or protected runtime route | No |
+
+Keep the existing work prefix if it is `/projects/`, `/case-studies/`, or another established route; route changes need a redirect map.
+
+### Editor structure
+
+Content sidebar: `Start here` (Home, About, Contact), `Portfolio` (Work index, Projects), `Writing` if used, `Site essentials` (legal/other). Component groups: `Globals`, `Portfolio` (project hero, gallery, outcomes), `Shared sections` (CTA, quote, logo strip). Media folders may separate approved client work, self-initiated work, portraits, and downloadable files. These folders do not determine URLs.
+
+Project entry fields: display title, slug, client display name, service/category references, summary, role, dates when relevant, hero image plus alt text, ordered gallery items with captions/alt, challenge, approach, verified outcomes, credits, related projects, SEO, approval/visibility state. Do not require a public client name, metric, or testimonial when consent is absent. Support anonymous case studies without accidentally exposing the original client in image filenames, alt text, schema, or social previews.
+
+Use repeatable gallery items rather than a long list of `image1` fields. Give each item a meaningful editor label and image metadata. Keep project-specific storytelling sections as instances; make hero/gallery/quote layouts reusable definitions with instance overrides.
+
+### Validation
+
+Check case-study consent, working gallery at different aspect ratios, captions, full-size media performance, downloadable file links, contact submission, related-work references, archived projects, and redirect behavior for renamed slugs. A portfolio with only a few projects does not need auto-generated service × industry pages.
+
+### Production detail
+
+Projects collection, `urlPattern` `/work/:slug` (or the established prefix):
+
+| Field key | Type | Notes |
+|---|---|---|
+| `"client"` | `reference` to Clients, or `text` | A reference only when clients have a logo or page of their own |
+| `"year"` | `number` | |
+| `"services"` | `multi-reference` to Services, or `array` of text | References when service pages exist |
+| `"cover_image"`, `"excerpt"` | `image`, `longtext` | Words baked into a hero image move into fields |
+| `"modules"` or `"body"` | components, or `document` | one component per block (text, image, gallery, quote, video, stats) for image-led studies; `document` when mostly prose |
+| `"results"` | `repeater`: `"value"`, `"label"` | Only verified outcomes |
+| `"credits"` | `repeater`: `"role"`, `"name"` | |
+| `"testimonial"` | `reference` to Testimonials | |
+| `"live_link"` | `link` | |
+| `"is_featured"` | `boolean` | The home grid is a hand-picked `multi-reference` or code filtering on this |
+
+- **Chrome:** a minimal header and a footer with contact details, both in the Global Layout.
+- **Forms:** one enquiry form (name, email, message, consent).
+- **Structured data:** `Article` on projects, `AboutPage` and `ContactPage` on those pages,
+  `Organization` or a `Person` node in `siteSchema`.
+- **Pitfalls:** videos without a poster or captions; scroll-driven storytelling flattened into
+  one blob (keep each step a `modular` item); downscaled uploads (upload the original once, the
+  media pipeline serves sizes); client work under NDA published without confirmed rights (flag
+  it in the report and ask).
+
+## Agency website
+
+Use when the site must explain services, prove results, and convert qualified leads. The key distinction from a portfolio is a durable offer taxonomy and repeatable proof linked to each offer.
+
+### Route and model starter
+
+| Family | Example path | Model and purpose |
+|---|---|---|
+| Home | `/` | Static overview, positioning, primary CTA |
+| Services index/detail | `/services/`, `/services/{slug}/` | Static index + Services collection only if multiple services have owners, proof, and maintained detail content; otherwise static pages |
+| Industries | `/industries/`, `/industries/{slug}/` | Optional collection; publish only distinct industry expertise |
+| Work index/detail | `/work/`, `/work/{slug}/` | Case studies collection and dynamic detail template |
+| Insights | `/insights/`, `/insights/{slug}/` | Editorial collection, authors, categories |
+| Agency | `/about/`, `/team/`, `/careers/` | Static or collection by update cadence |
+| Contact | `/contact/` | Form with routing/consent behavior |
+
+Use the established `/case-studies/`, `/blog/`, etc. when the current site already has them. A service × industry matrix should be created only for combinations with distinct evidence, offer, and maintenance owner; otherwise link the existing service and industry pages instead of generating thin duplicates.
+
+### Content relationships and components
+
+Cases reference services, industries, client permission state, outcome evidence, and optional quotes. Service pages reference relevant cases, deliverables, process, FAQ, and CTA. Industry pages reference services/cases and sector-specific language. Avoid duplicating client logos or metrics across pages: maintain permission and source context on the case/client record.
+
+Component groups: `Globals` (nav/footer), `Proof` (case card, metrics, testimonial), `Offers` (service card, process), `Conversion` (CTA, contact form), `Editorial`. Reuse definitions with page-specific props, and allow section order to vary by page. Editors should see grouped fields such as `Primary button → Label, Link`, `Proof item → Metric, Context, Source`.
+
+Content sidebar folders should match editor work: `Core pages`, `Services`, `Industries`, `Case studies`, `Insights`, `Company`. These are dashboard folders, not paths.
+
+### Validation
+
+Review lead form destination, attribution and consent, internal links from every offer to relevant proof, case-study rights, schema claims, duplicate service routes, old URL redirects, and mobile CTA visibility. Keep draft or client-confidential work out of sitemaps and public data feeds.
+
+### Production detail
+
+| Collection | `urlPattern` | Fields |
+|---|---|---|
+| Case studies | `/work/:slug` | The Projects fields in [Portfolio](#portfolio-website), plus `"industry"` `reference` |
+| Services | `/services/:slug` | `"icon"` `image`, `"excerpt"` `longtext`, `"body"` `document`, `"related_work"` `multi-reference` |
+| Clients | none (no detail page) | `"logo"` `image` with the company name as alt, `"website"` `link` |
+| Team | `/team/:slug`, only when profiles have pages | `"role"` `text`, `"photo"` `image`, `"bio"` `longtext`, `"social_links"` `repeater`: `"network"` `select`, `"url"` `link` |
+| Testimonials | none | `"quote"` `longtext`, `"name"`, `"role"`, `"company"` `text`, `"photo"`, `"logo"` `image` |
+
+- **Lists:** "work by service" on a service page is `"related_work"` picked by hand, code
+  filtering the delivered case studies, or on a hosted page a `collection` block with `source`
+  and a filter on the service.
+- **Forms:** a new-business enquiry with `select` fields for budget and timeline, plus `hidden`
+  fields for campaign attribution.
+- **Structured data:** `Organization` in `siteSchema`, `Article` on case studies, `WebPage` on
+  services, `FAQPage` only where a service page shows real questions. A `Person` node per team
+  page is pasted `schema`.
+- **Pitfalls:** a logo wall with no alt text; client names retyped per page instead of
+  referenced; a testimonial with no record of consent (keep a `"consented_on"` `date`).
+
+## Corporate website
+
+Use for multiple audiences, brands, regions, business units, approval chains, or regulated statements. The main modeling problem is ownership: who can update a statement, which sites reuse it, and when it expires.
+
+### Route and model starter
+
+| Family | Example path | Owner and model |
+|---|---|---|
+| Corporate home | `/` | Global communications; static page |
+| Business units | `/businesses/{slug}/` | Collection if units share a template and lifecycle |
+| Products/services | Existing taxonomy | Collection or static pages by unit ownership |
+| Newsroom | `/news/`, `/news/{slug}/` | News collection, media contact, publish date |
+| Leadership | `/leadership/`, `/leadership/{slug}/` | People collection if profiles recur |
+| Careers | `/careers/` | Landing page; job details may remain in an ATS |
+| Investor / governance | `/investors/`, `/governance/` | Gated approval; files with version/date |
+| Policies and legal | `/privacy/`, `/terms/` | Static pages with accountable owner |
+| Contact / locations | `/contact/`, `/locations/{slug}/` | Form plus locations collection when needed |
+
+Do not copy ATS jobs, stock prices, investor filings, or regulated data into BetterCMS unless BetterCMS is deliberately the system of record. Preserve external systems and public links.
+
+### Governance and editor structure
+
+Record owner, reviewer, source of claim, effective date, review date, and version where these matter. Separate draft, legal-reviewed, approved, and published states with the project's own editorial board: read its stages and which one is the publish gate with `get_workflow_board` before `move_stage`, because stage keys are per project. Do not claim an approval stage exists if the board has none. Scope access and publishing by the product's real permissions. High-risk copy (financial figures, certifications, compliance claims, regulated products) needs a verified source and designated reviewer.
+
+Content sidebar: `Corporate pages`, `Business units`, `Newsroom`, `People`, `Investors`, `Legal`, `Regions` if used. Component groups: `Globals`, `Corporate identity`, `Business unit`, `Newsroom`, `Data/proof`. Distinguish sitewide global identity from unit-specific branding and local navigation. A shared global component should not overwrite an independently branded unit page.
+
+### Regions and languages
+
+Choose a deliberate URL strategy, such as `/{locale}/...` or regional domains. Keep locale-to-locale equivalent-page IDs, fallback behavior, canonical target, and language switcher destinations. Check what the connected project models for locales before planning; implement and verify `hreflang` output in the frontend, where the rendered head is decided. Do not auto-redirect by IP or index machine placeholders. Follow [Google's localized-page guidance](https://developers.google.com/search/docs/specialty/international/localized-versions).
+
+### Validation
+
+Test unit-specific nav/footers, ownership permissions, embargoed news, expiring files, superseded legal pages, regional links, localization fallbacks, 404/redirects, accessibility, and the published head for every major template. Separate search visibility from access control: `noindex` does not protect private information.
+
+## SaaS, AI, and enterprise technology website
+
+Use when a product site must explain a platform to multiple buyers and evaluators. Distinguish product truth, marketing interpretation, developer documentation, and live application behavior.
+
+### Route and model starter
+
+| Family | Example path | Suggested ownership |
+|---|---|---|
+| Home | `/` | Static marketing composition |
+| Product/platform | `/product/`, `/features/{slug}/` | Static overview; Features collection only if repeated and maintained |
+| Solutions | `/solutions/{slug}/` | Collection for distinct jobs-to-be-done/use cases |
+| Industries | `/industries/{slug}/` | Collection where sector-specific workflows/proof exist |
+| Integrations | `/integrations/{slug}/` | Collection with provider status, auth, capability, owner |
+| Customers | `/customers/{slug}/` | Case studies with approvals and proof sources |
+| Pricing | `/pricing/` | Static page or runtime-driven product data; one owner for actual pricing |
+| Resources | `/resources/{slug}/`, `/blog/{slug}/` | Editorial collections and their list pages |
+| Glossary | `/glossary/{term}/` | Definition collection with editorial gates |
+| Comparisons / alternatives | `/compare/{slug}/` | Dedicated reviewed model, never blind competitor templating |
+| Trust and legal | `/security/`, `/privacy/`, `/trust/` | Static pages or external trust center |
+| Docs / API | `/docs/...` | Often a separate docs system/repository; link rather than duplicate |
+| Conversion | `/demo/`, `/contact/` | Forms with routing, consent, and success states |
+
+These are options, not required pages. Keep existing routes and product naming. For a large enterprise site, consider ownership by product line/market and a shared navigation contract; avoid separate page schemas for identical layouts.
+
+### Model and section kit
+
+Entities: Solutions, Industries, Features, Integrations, Cases, Resources, Glossary Terms, and optional Comparisons. Use references across them so an integration or proof item updates once. Each entry needs an owner, lifecycle, canonical URL, native SEO metadata, and sufficient unique content. Integration entries need a clear status (live, beta, planned) and must never imply a planned connector is available.
+
+Shared sections: product hero, outcome grid, workflow steps, feature visual, integration grid, proof strip, case excerpt, FAQ, security/trust callout, pricing CTA. Keep a single component definition per visual family and use variants/instance overrides. Give buttons and media grouped editor controls. Expose only supported rich-text headings; a hero title may be plain text rendered as H1 while an article body may allow H2/H3, links, lists, and code if the renderer supports them.
+
+Content sidebar: `Core pages`, `Product`, `Solutions`, `Industries`, `Integrations`, `Customers`, `Resources`, `Trust`, `Other`. Component groups should reflect role, not route.
+
+### Search and AEO
+
+Build topic hubs and link related solution, industry, integration, case, and glossary pages. Only publish a specific solution × industry page when it adds differentiated workflow, evidence, and value. Answer questions directly with verifiable facts and useful context; do not fabricate FAQ, schema, or “AI answer” pages. Use [programmatic-seo.md](programmatic-seo.md) for generated page families and [Google's AI-search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) for the current search-policy boundary.
+
+### Validation
+
+Verify product claims against shipped capability, integration statuses, pricing consistency, demo form routing, docs links, internal topic paths, glossary duplicates, comparison accuracy, rendering of code/rich text, and desktop/mobile navigation. Noindex preview, gated assets, and incomplete pages.
+
+### Production detail
+
+| Collection | `urlPattern` | Fields |
+|---|---|---|
+| Case studies | `/customers/:slug` | `"customer"` `text`, `"logo"`, `"cover_image"` `image`, `"industry"` `reference`, `"excerpt"` `longtext`, `"metrics"` `repeater` (`"value"`, `"label"`, at most 3 rows), `"quote"` `reference` to Testimonials, `"body"` `document` with challenge, solution, results as H2s, `"facts"` `repeater` (`"label"`, `"value"`) |
+| Testimonials | none | `"quote"`, `"name"`, `"role"`, `"company"`, `"photo"`, `"logo"`, `"source"` `link`, `"consented_on"` `date`. `"rating"` `number` only when the source shows one |
+| Integrations | `/integrations/:slug` | `"logo"`, `"category"` `reference`, `"excerpt"`, `"body"` `document`, `"app_link"` `button`, `"docs_link"` `link`, `"is_native"` `boolean`, `"status"` `select` (live, beta, planned) |
+| Releases | `/changelog/:slug`, or none when releases are anchors on one page | `"version"` `text`, `"published_on"` `datetime`, `"changes"` `repeater` (`"kind"` `select`: new, improved, fixed; `"text"`), `"body"` `richtext` |
+| Comparisons | `/compare/:slug` | `"competitor"` `text`, `"competitor_logo"`, `"intro"` `longtext`, `"matrix"` `repeater` (`"feature"`, `"us"`, `"them"`), `"verified_on"` `date`, `"body"` `document` |
+
+- **Static until repeated:** feature and product pages stay static pages until three or more
+  share one layout. Pricing tiers stay in the pricing page's fields unless the same plans show
+  on two or more pages; then a Plans collection.
+- **Pricing:** store the monthly and the yearly price as two fields read from the source. Never
+  derive one from a discount. The full feature grid is a `repeater` whose row holds one value
+  per plan; inside a component it can be the `table` prop ([components.md](components.md)).
+- **Lists:** customer and integration hubs are one `collection` block each. Category filter
+  chips are code on a code-built site; otherwise leave them out and say so. A home logo wall is
+  a `repeater` of images, or a `multi-reference` when logos link to stories.
+- **Forms:** demo request and contact sales with `hidden` attribution fields, and a newsletter
+  form with `consent`. A gated asset is a form whose success state links the file.
+- **Structured data:** `Organization` and a `WebSite` node in `siteSchema`, `FAQPage` on the
+  pricing page (one per URL), `BlogPosting` on posts. `JobPosting` as the careers collection's
+  `schemaType`; `SoftwareApplication` is pasted `schema` from visible facts.
+- **Pitfalls:** "Trusted by 10,000 teams" style counters with no source (report as unverified);
+  a feature matrix pasted as an image; a screenshot holding the only copy of a claim.
+
+## Large ecommerce website
+
+Use for a catalog-heavy site regardless of commerce engine. The core choice is the boundary between **commerce facts** and **editorial merchandising**.
+
+### Source-of-truth contract
+
+Products, variants, SKUs, price, availability, tax, orders, checkout, customer accounts, and fulfillment normally belong to the commerce platform. BetterCMS owns editorial landing pages, category storytelling, buying guides, banners, proof, and selected product-page content blocks. A CMS reference to a product uses a stable external ID plus a verified lookup; don't silently duplicate transactional fields into editable CMS text.
+
+### Route and model starter
+
+| Family | Example path | Index policy |
+|---|---|---|
+| Home and campaigns | `/`, `/campaigns/{slug}/` | Public, unique campaigns |
+| Catalog root / category | `/shop/`, `/collections/{slug}/` | Curated category pages with products and links |
+| Product | `/products/{slug}/` | Available public products; decide retired-product policy |
+| Brand | `/brands/{slug}/` | Only substantive brand pages |
+| Buying guides | `/guides/{slug}/` | Unique advice with product references |
+| Editorial | `/stories/{slug}/` | Published articles |
+| Search, cart, account, checkout | Runtime routes | Usually excluded from sitemap; private data protected |
+| Filters and sort | Parameters on category routes | Explicit crawl/index policy; avoid unbounded URL combinations |
+
+Keep existing paths if the store already uses another taxonomy. Decide whether unavailable products stay indexable, redirect to a successor, or are unpublished and return 404 or a 410 rule, based on permanence and user value. Do not redirect every missing product to the homepage.
+
+### Editor model and reuse
+
+Models: Campaigns, Buying Guides, optional Brand and Category editorial records, plus product references. Category merchandising groups can include hero, intro, featured products, editorial cards, filters, and FAQs. Components: global store nav, search, promo bar, product card, variant selector, add-to-cart, category hero, recommendation rail, cart feedback. Commerce controls remain functional code tied to live data; an editor can change allowed presentation and copy but must not create an unfulfillable cart action.
+
+Content sidebar: `Campaigns`, `Collections`, `Guides`, `Stories`, `Store pages`; group media by campaigns/editorial needs. Content sidebar folders never change a URL; URL page folders do, and renaming one 301s its pages, so do not turn category folders into URL folders unless a route change is intended.
+
+### Crawl and scale
+
+Provide crawlable category → subcategory → product links and paginated result URLs. Decide which facet combinations deserve dedicated curated landing pages; keep the rest out of the index/crawl space by an intentional policy. Do not rely on canonical alone to control a near-infinite faceted URL space. Keep canonical, internal link, and sitemap URLs consistent. Sitemaps should include only eligible canonical pages and split before protocol limits. Product price/availability markup must match the current displayed commerce data; validate variant markup against Google's current `ProductGroup` guidance. [Google ecommerce structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure) · [Faceted navigation](https://developers.google.com/crawling/docs/faceted-navigation) · [Product variants](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
+
+### Validation
+
+Test a product with several variants, a sold-out product, missing image, empty category, deep pagination, filter combinations, mobile search, currency/market change, cart handoff, and changed price after cache expiry. Verify that sitemap counts match eligible catalog records and that deleted routes/redirects do not strand internal links.
+
+### Production detail
+
+Applies when BetterCMS renders product or category pages. A Shopify-backed store follows
+[shopify-headless.md](shopify-headless.md) first.
+
+| Collection | `urlPattern` | Fields |
+|---|---|---|
+| Products | `/products/:slug`, slug equal to the store handle | `"store_product_id"` `text` (migration metadata), `"excerpt"` `longtext`, `"story"` `document`, `"gallery"` `repeater` (`"image"`, `"caption"`; editorial images only), `"highlights"` `array` of text, `"specs"` `repeater` (`"label"`, `"value"`), `"care"` `richtext`, `"categories"` `multi-reference`, `"badge"` `select`, `"related"` `multi-reference` (at most 4), `"faqs"` `multi-reference` |
+| Categories | `/collections/:slug` | `"intro"` `longtext`, `"image"`, `"parent"` `reference` to Categories (one level), `"store_collection_id"` `text` |
+| FAQs (when shared) | none | `"question"` `text`, `"answer"` `richtext` |
+
+A catalogue with no commerce engine adds `"price"` and `"compare_at_price"` `number`, a
+`"currency"` `select` of ISO codes, `"sku"` `text`, `"is_in_stock"` `boolean`.
+
+- **Lists:** a category's product grid is code filtering by the category, or the store's own
+  listing. A "Staff picks" row is a `multi-reference`.
+- **Chrome:** header (search, account and cart are app state in code, never content), a promo
+  bar, a footer whose payment badges are a fixed set in code.
+- **Forms:** newsletter, contact, wholesale enquiry. Back-in-stock and checkout stay with the
+  store.
+- **Structured data:** `Product` only where price and availability are entry fields. When the
+  store owns them, the site's code emits `Product` with the live `Offer`; do not paste a frozen
+  price. `CollectionPage` on categories. `AggregateRating` only from a connected review source.
+- **Redirects:** facet and sort parameters canonical to the category. Cart, checkout, account
+  and search are noindex.
+- **Pitfalls:** price, stock, options or variants copied into content (they drift within a
+  day); one static page per product, or one entry per variant; a size guide as an image instead
+  of a `repeater`; typed review counts or star scores; editorial images hotlinked from the
+  store CDN instead of uploaded.
+
+## Directory or listings website
+
+Use when the source has hundreds of same-shaped detail pages (businesses, tools, venues,
+vendors), category and location hubs, filters, a "Submit a listing" form, often a map.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Home, submit, featured-listing pricing, about, contact | `/`, `/submit`, ... | Static pages |
+| Listings list and detail | `/listings`, `/listings/:slug` | Listings collection, dynamic page, `urlPattern` `/listings/:slug` |
+| Category hub | `/categories`, `/categories/:slug` | Categories collection |
+| Location hub | `/locations`, `/locations/:slug` | Locations collection (cities or regions) |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Listings | `"logo"`, `"cover_image"` `image`; `"excerpt"` `longtext`; `"body"` `document`; `"category"` `reference` (required); `"subcategories"` `multi-reference`; `"place"` `reference` to Locations; `"address"` `group`; `"map_pin"` `location`; `"website"` `link`; `"email"` `email`; `"phone"` `phone`; `"opening_hours"` `repeater` (`"day"` `select`, `"opens"`, `"closes"` `text`, `"is_closed"` `boolean`); `"amenities"` `array` of text, or `multi-reference` to Features when each has a page; `"facts"` `repeater` (`"label"`, `"value"`); `"gallery"` `repeater` (`"image"`, `"caption"`); `"social_links"` `repeater`; `"plan"` `select` (free, featured, premium); `"is_verified"` `boolean`; `"external_id"` `text` |
+| Categories | `"intro"` `longtext`, `"icon"` `image`, `"parent"` `reference` to Categories |
+| Locations | `"region"` `text`, `"country"` `select`, `"map_pin"` `location`, `"intro"` `longtext`, `"cover_image"` `image` |
+
+`"plan"`, `"is_verified"` and `"external_id"` are locked: `readOnly: "developer"` with a
+`lockReason`. A write without schema access that changes one is refused.
+
+- **Chrome:** header with search, footer, an announcement for featured-listing offers.
+- **Lists:** the all-listings page is a `collection` block. On a hosted page a category or
+  location hub is a block with `source` and a filter, A to Z is `sort`, featured first is
+  `pinnedIds`, and "related listings" is a filter on a `{{field}}` of the listing shown with
+  `excludeCurrent`. Numbered pagination needs the site's code: report the gap. Site search
+  uses the hosted index: run `refresh_search_index` after the import.
+- **Forms:** submit a listing, claim a listing, report a problem, contact. A submission never
+  publishes itself; an editor creates or updates the entry from the inbox.
+- **Structured data:** `schemaType: "LocalBusiness"` on listings that are places. Paste `schema`
+  when the page shows hours or coordinates, or needs a subtype. `CollectionPage` on hubs.
+- **Redirects:** nested source paths (`/:category/:listing`) become `/listings/:slug` plus one
+  301 each.
+- **Pitfalls:** filterable facts stored as free tags (use `select`, `reference`, `number`);
+  duplicate listings from several sources (match on website domain, phone or address before
+  creating); a one-line address when structured data needs the parts; a paid outbound link with
+  no `rel="sponsored"` (the `link` value carries no rel, so the rendering code adds it from
+  `"plan"`); hub pages with fewer than three listings left indexable (set noindex until they
+  grow); thousands of near-empty pages (run `generate_pages_from_dataset` with `dryRun: true`
+  first, and only for rows with real content).
+
+## Blog or publication
+
+Use when the source has dated articles with bylines, categories, an index and a feed.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Home (or the index itself), about, newsletter, contact | `/`, `/about`, ... | Static pages |
+| Post list and detail | `/blog`, `/blog/:slug` (or the site's own word, `/journal/:slug`) | Posts collection, `urlPattern` `/blog/:slug` |
+| Author | `/authors/:slug` | Authors collection |
+| Category, topic | `/category/:slug`, `/topics/:slug` | One collection per taxonomy the source really has |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Posts | `"dek"`, `"excerpt"` `longtext`; `"cover_image"` `image`; `"body"` `document`; `"authors"` `multi-reference` (at least one); `"category"` `reference`; `"topics"` `multi-reference`; `"published_on"`, `"updated_on"` `datetime`; `"series"` `reference`; `"is_featured"` `boolean`; `"related"` `multi-reference` (at most 3) only when the source curates them |
+| Authors | Title is the name. `"role"` `text`, `"photo"` `image`, `"bio"` `longtext`, `"social_links"` `repeater` |
+| Categories, Topics | `"intro"` `longtext` |
+
+- **Chrome:** header, footer with the newsletter form, announcement.
+- **Lists:** the index is a `collection` block, `order: "newest"`. It orders by creation time,
+  so import posts oldest first, or the list will not follow `"published_on"`. A block with
+  `source` takes `sort: "-published_on"` instead. Category, topic and author lists on a hosted
+  page are sourced blocks with a filter; numbered pagination needs the site's code. A pinned
+  feature slot is `pinnedIds` on a sourced block, or a `reference` on the index page.
+- **Forms:** newsletter with `consent`, contact, tips.
+- **Structured data:** `BlogPosting` or `Article` as the collection default in
+  `collectionSchemaTypes`; `Blog` on the index. `NewsArticle` is pasted `schema`; an author page takes
+  `schemaType: "Person"`. Turn the feed on in `rssConfig`; item links come from
+  the `urlPattern`. A syndicated post keeps its cross-site canonical in the entry's `meta`.
+- **Redirects:** dated WordPress paths (`/2024/05/my-post/`) become `/blog/:slug` with a 301
+  per post.
+- **Pitfalls:** share bars, author boxes and related cards inside the body (they are template
+  sections); an H1 inside the body, or the cover repeated as the first body image; authors as
+  strings; a stored reading time (compute it); WordPress shortcodes (`[gallery]`, `[caption]`)
+  left as text (map them to a Portable Text block or a component, report unknown ones); tags
+  and categories that duplicate each other.
+
+## Docs or knowledge base
+
+Use when the source has a left navigation tree, "On this page" anchors, code blocks,
+admonitions, a version switcher, search, "Was this helpful?".
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Docs home, support home, contact support | `/docs`, `/support`, ... | Static pages |
+| Doc page | `/docs/:slug` | Docs collection |
+| Versioned docs | `/docs/v2/:slug` | One collection per supported major version, each with its own fixed-prefix `urlPattern` |
+| Knowledge-base article | `/help/:slug` | KB articles collection |
+| Glossary | `/glossary`, `/glossary/:slug` | Terms collection ([programmatic-seo.md](programmatic-seo.md)) |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Docs | `"excerpt"` `longtext`; `"body"` `document`; `"section"` `reference` to Doc sections (required); `"parent"` `reference` to Docs (at most 3 levels); `"order"` `number`; `"status"` `select` (new, beta, deprecated); `"last_reviewed_on"` `date` |
+| Doc sections | `"icon"` `image`, `"order"` `number` |
+| KB articles | `"body"` `document`, `"category"` `reference`, `"related"` `multi-reference` |
+| Terms | `"definition"` `richtext`, `"related"` `multi-reference` |
+
+- **Chrome:** header with search and footer in the Global Layout. The sidebar tree is rendered
+  by code from `"section"`, `"parent"` and `"order"`; previous and next links and "On this page"
+  are derived the same way. Curate the tree in the Layout only when the source hand-orders it.
+- **Lists:** a section landing page ordered by `"order"` is a `collection` block with `source`,
+  a filter on `"section"` and `sort: "order"` on a hosted page, or the site's code. Run
+  `refresh_search_index` after the import.
+- **Forms:** a one-question feedback form (`radio` plus a `hidden` page path), contact support.
+- **Structured data:** `Article` or `WebPage`; `FAQPage` only on real question pages. A deprecated version is noindex or canonicals to the current one.
+- **Redirects:** relative `.md` links in source files resolve to the target entry's URL. A
+  nested source path (`/docs/guides/setup/install`) becomes `/docs/:slug` plus a 301.
+- **Pitfalls:** the navigation tree copied by hand (it drifts); admonitions flattened to
+  blockquotes with the tone lost (map each to an embedded block that keeps its tone,
+  [portable-text.md](portable-text.md)); code as images or highlighted markup (a `bcmsCode`
+  block keeps the plain text and a language); MDX components with no
+  equivalent (map known ones to components, report the rest as logic left in code); an OpenAPI
+  reference converted by hand (it is generated from the spec: link or embed it and report it).
+
+## Local business or restaurant
+
+Use when the source shows an address, hours, a phone number, a menu, "Book a table", a map, and
+one or a few locations.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| One location | `/visit` | Static page; address and hours live once in the Global Layout |
+| Two or more locations | `/locations`, `/locations/:slug` | Locations collection |
+| Menu | `/menu`, or `/menus/:slug` | A page section; a Menus collection when menus differ per location or season |
+| Events, specials | `/events/:slug` | Collections only when dated |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Locations | `"address"` `group`; `"map_pin"` `location`; `"phone"` `phone`; `"email"` `email`; `"opening_hours"` `repeater` (`"day"` `select`, `"opens"`, `"closes"` `text`, `"is_closed"` `boolean`); `"special_hours"` `repeater` (`"date"` `date`, `"opens"`, `"closes"`, `"is_closed"`, `"note"`); `"time_zone"` `text`; `"cover_image"` `image`; `"menus"` `multi-reference`; `"booking_provider"` `select`; `"booking_id"` `text` |
+| Menus | Title is "Dinner", "Brunch". `"sections"` `repeater` (`"title"`, `"items"` `repeater`: `"name"`, `"description"`, `"price"` `number`, `"dietary"` `array` of text, `"is_new"` `boolean`); `"notes"` `longtext` (allergen statement); `"pdf"` `file` (a download, never the only copy) |
+| Events, Specials | `"starts_at"`, `"ends_at"` `datetime`; `"place"` `reference` to Locations; `"body"` `richtext`; `"image"` |
+
+Give `"opens"` and `"closes"` help text with the format (24-hour `HH:MM`). The currency is a
+site setting in code, not a symbol typed into each price.
+
+- **Chrome:** header with a booking button that links to the provider; footer listing
+  locations. Hours appear in one source: with a Locations collection the footer renders from
+  the entries in code, otherwise from the Global Layout.
+- **Forms:** private-events enquiry, contact, newsletter. Reservations are the provider's
+  embed, stored as provider and id only.
+- **Structured data:** `schemaType: "LocalBusiness"` gives name, phone, email and a one-line
+  address. Hours, geo, a structured postal address and the `Restaurant` subtype need pasted
+  `schema` built from the fields. Same name, address and phone everywhere. `Event` on events.
+- **Redirects:** a single-location site that grows to several moves `/visit` to
+  `/locations/:slug` with a 301.
+- **Pitfalls:** a menu as a PDF or image only; hours typed in the footer, the contact page and
+  the location page; prices as "$14" strings; "Closed" typed as a time; holiday hours
+  forgotten; Google reviews copied as testimonials (connect the source or get consent).
+
+## Events or conference
+
+Use when the source shows dates with times, an agenda, speakers, tickets, a venue, sponsors, a
+countdown.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Current edition home, tickets, travel, code of conduct, call for papers | `/`, `/tickets`, ... | Static pages |
+| Event | `/events`, `/events/:slug` | Events collection |
+| Session | `/sessions/:slug` | Sessions collection |
+| Speaker | `/speakers`, `/speakers/:slug` | Speakers collection |
+| Venue, sponsor | none unless the source has pages | Venues, Sponsors collections |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Events | `"starts_at"`, `"ends_at"` `datetime`; `"time_zone"` `text`; `"status"` `select` (scheduled, postponed, rescheduled, cancelled, moved online); `"attendance"` `select` (in person, online, mixed); `"venue"` `reference`; `"excerpt"`; `"cover_image"`; `"body"` `document`; `"tickets_button"` `button`; `"tickets"` `repeater` (`"name"`, `"price"` `number`, `"currency"` `select`, `"availability"` `select`) only when no ticketing provider owns them; `"speakers"`, `"sponsors"` `multi-reference` |
+| Sessions | `"event"` `reference`; `"starts_at"`, `"ends_at"`; `"room"` `text`; `"track"` `reference` or `select`; `"format"` `select` (talk, workshop, panel, break); `"level"` `select`; `"speakers"` `multi-reference`; `"description"` `richtext`; `"recording_url"` `link` |
+| Speakers | Title is the name. `"role"`, `"company"`, `"photo"`, `"bio"`, `"social_links"` |
+| Venues | `"address"` `group`, `"map_pin"` `location`, `"accessibility"`, `"directions"` `richtext` |
+| Sponsors | `"logo"`, `"tier"` `select`, `"website"` `link` |
+
+- **Chrome:** header with a tickets button; an announcement bar whose countdown end is one
+  `datetime` with its zone, and whose Section `window` ends with it. Never migrate a countdown
+  that resets per visitor.
+- **Lists:** a `collection` block with `source` sorts by `"starts_at"`, but its filter values
+  are fixed: none means "today". Upcoming and past lists, and an agenda grouped by day and
+  track, are the site's code filtering on `"starts_at"`. State that in the report; do not fake
+  it with two hand-kept lists.
+- **Forms:** registration (or the ticketing provider's embed), call for papers (links only, no
+  upload), sponsor enquiry, newsletter.
+- **Structured data:** `schemaType: "Event"` gives name, dates and a location name. Event
+  status, attendance mode, a `Place` with address or a `VirtualLocation`, offers from visible
+  ticket prices and performers need pasted `schema`.
+- **Redirects:** past events keep their URLs and stay published. A yearly path
+  (`/2025/schedule/talk-name`) becomes `/sessions/:slug` plus a 301.
+- **Pitfalls:** times with no zone (ask when the site shows none); the agenda as an image or
+  PDF only; speakers retyped per session; past events deleted; a sponsor link with no
+  `rel="sponsored"` in the rendering code.
+
+## Course or education
+
+Use when the source has courses with a curriculum, instructors, levels, durations, enrol
+buttons, cohorts.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Home, catalogue hub, pricing, for teams, FAQ | `/`, `/courses`, ... | Static pages; the hub holds the `collection` block |
+| Course | `/courses/:slug` | Courses collection |
+| Instructor | `/instructors/:slug` | Instructors collection |
+| Cohort | none | Cohorts collection, only when dated |
+
+Lesson content behind a login belongs to the LMS, not BetterCMS.
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Courses | `"excerpt"`; `"cover_image"`; `"level"` `select`; `"duration"` `text` (ISO 8601, `PT6H30M`); `"category"` `reference`; `"instructors"` `multi-reference`; `"outcomes"`, `"prerequisites"` `array` of text; `"curriculum"` `repeater` (`"title"`, `"lessons"` `repeater`: `"title"`, `"duration"`, `"is_preview"` `boolean`); `"enrol_button"` `button`; `"lms_course_id"` `text`; `"price"` `number` only when no checkout owns it |
+| Cohorts | `"course"` `reference`; `"starts_at"`, `"ends_at"` `datetime`; `"time_zone"` `text`; `"seats"` `text` only when shown; `"status"` `select` |
+| Instructors | Title is the name. `"role"`, `"photo"`, `"bio"` |
+
+- **Chrome:** header with a sign-in link to the LMS, footer.
+- **Lists:** the catalogue is a `collection` block; category and level filter chips need the
+  site's code. A fixed category or level list on a hosted page is a block with `source` and a
+  filter. An instructor's courses are a `multi-reference` or code.
+- **Forms:** waitlist, team enquiry, newsletter.
+- **Structured data:** `Course` as the collection's `schemaType` (name, description, provider);
+  offers and course instances from cohorts need pasted `schema`. `FAQPage` on a course with a real FAQ.
+- **Redirects:** LMS marketing paths (`/p/course-name`) become `/courses/:slug` plus 301s.
+- **Pitfalls:** stored totals ("6 modules, 42 lessons, 8 hours"); lesson videos or paid content
+  copied in; cohort dates with no zone; prices copied from the checkout.
+
+## Job board or careers
+
+Use when the source lists open roles by department, location tags, Apply buttons, Greenhouse,
+Lever or Ashby links, salary ranges, `JobPosting` JSON-LD.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Careers home, benefits, culture, hiring process | `/careers`, ... | Static pages |
+| Job | `/careers/:slug` or `/jobs/:slug` | Jobs collection |
+| Department | `/departments/:slug`, only if the source has them | Departments collection |
+| Employer (multi-company boards) | `/companies/:slug` | Employers collection |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Jobs | `"department"` `reference`; `"offices"` `multi-reference` to Locations; `"workplace"` `select` (on site, hybrid, remote); `"employment_type"` `select` (full time, part time, contract, internship); `"salary"` `group` (`"min"`, `"max"` `number`, `"currency"`, `"period"` `select`) only when shown; `"excerpt"`; `"body"` `document`; `"apply_button"` `button` (the ATS URL); `"posted_on"` `date`; `"closes_at"` `datetime`; `"status"` `select` (open, closed); `"ats_job_id"` `text` |
+| Departments | `"intro"` `longtext` |
+| Employers | `"logo"`, `"about"` `richtext`, `"website"` `link` |
+
+- **Chrome:** the header carries a "Careers" link; no separate chrome.
+- **Lists:** open roles grouped by department with location filter chips need the site's code.
+  On a hosted page a `collection` block with `source` and a filter on `"status"` lists the open
+  jobs, one block per department when the source groups them; set `emptyText` for "no open
+  roles".
+- **Forms:** applications go to the ATS. Forms have no file upload, so never collect a CV in a
+  BetterCMS form. A "Stay in touch" form is fine.
+- **Structured data:** `JobPosting` as the collection's `schemaType`: it fills title,
+  description, posted date, valid through, employment type, hiring organisation and job location
+  from the entry's fields, and is not emitted without a company and a posting date. A remote type
+  with applicant location requirements, or a base salary, needs pasted `schema`, only when
+  visible. Unpublish the entry when the job closes.
+- **Redirects:** closed jobs keep their URLs. ATS-hosted paths that move onto the site get a
+  301 where the old host allows one.
+- **Pitfalls:** hand-copying an ATS (sync by `"ats_job_id"` in code or link out, and report
+  which); deleting closed jobs; one job duplicated per city; invented salaries.
+
+## Real estate or property listings
+
+Use when the source has properties with price, beds, baths, area, status, galleries, floor
+plans, map search, agents, a viewing request form.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Home, valuation, sell, let, about, contact | `/`, `/valuation`, ... | Static pages |
+| Property | `/properties`, `/properties/:slug` | Properties collection |
+| Area guide | `/areas/:slug` | Areas collection |
+| Agent | `/agents/:slug` | Agents collection |
+| Office | `/offices/:slug` | Offices collection, fields as Locations in [Local business](#local-business-or-restaurant) |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Properties | Title is the display address or name. `"status"` `select` (for sale, for rent, under offer, sold, let); `"listing_type"` `select` (sale, rent); `"price"` `number`; `"currency"` `select`; `"price_period"` `select` (month, week); `"price_qualifier"` `select` (guide price, offers over, price on application); `"address"` `group`; `"map_pin"` `location`; `"property_type"` `select`; `"bedrooms"`, `"bathrooms"`, `"receptions"`, `"area"` `number`; `"area_unit"` `select`; `"features"` `array` of text; `"body"` `document`; `"gallery"` `repeater` (`"image"`, `"caption"`; at least one); `"floor_plans"` `repeater` of images with alt; `"virtual_tour"` `link`; `"energy_rating"` `select`; `"facts"` `repeater` (`"label"`, `"value"`); `"agent"`, `"office"`, `"area_guide"` `reference`; `"available_from"` `date`; `"feed_id"` `text` |
+| Agents | Title is the name. `"role"`, `"photo"`, `"phone"` `phone`, `"email"` `email`, `"office"` `reference` |
+| Areas | `"intro"`, `"cover_image"`, `"body"` `document`, `"map_pin"` `location` |
+
+- **Chrome:** header with a valuation button, footer listing offices.
+- **Lists:** search by area, type, price band and bedrooms, the map view and "similar
+  properties" need the site's code or the CRM's search. On a hosted page a `collection` block
+  with `source` gives a fixed list (one area, one type), never a visitor's search.
+- **Forms:** viewing request with the property passed in a `hidden` field, valuation request,
+  contact.
+- **Structured data:** `RealEstateListing` with an `Offer` is pasted `schema` from visible
+  facts. `schemaType: "LocalBusiness"` on offices. A portal copy keeps the canonical on this
+  site.
+- **Redirects:** sold and let properties keep their URLs and stay published. Portal-style
+  paths (`/for-sale/london/3-bed-flat-12345`) become `/properties/:slug` plus 301s.
+- **Pitfalls:** prices as strings ("£450,000"); status typed into the title ("SOLD - 3
+  bed..."); listings hand-imported when a CRM feed owns them (sync by `"feed_id"` in code and
+  report it); images hotlinked from the feed host; floor plans with no alt text; sold
+  properties deleted.
+
+## Nonprofit
+
+Use when the source has a Donate button, programs, impact numbers, stories, annual reports,
+volunteers, a charity number.
+
+### Routes
+
+| Family | Path | Model |
+|---|---|---|
+| Home, mission, impact, donate, get involved, contact | `/`, `/donate`, ... | Static pages |
+| Program or campaign | `/programs/:slug` | Programs collection |
+| Story, news | `/stories/:slug` | Stories collection, post fields from [Blog](#blog-or-publication) |
+| Report | `/reports/:slug` | Reports collection |
+| Events | `/events/:slug` | As [Events](#events-or-conference) |
+| Team and board, partners | none unless the source has pages | People, Partners collections |
+
+### Collections
+
+| Collection | Fields |
+|---|---|
+| Programs | `"excerpt"`; `"cover_image"`; `"body"` `document`; `"impact"` `repeater` (`"value"`, `"label"`, `"as_of"` `date`, `"source"` `link`); `"place"` `reference`; `"is_active"` `boolean`; `"donate_button"` `button` |
+| Stories | Post fields, plus `"consented_on"` `date` for any person shown |
+| Reports | `"year"` `number`; `"file"` `file`; `"cover_image"`; `"summary"` `richtext` holding the key facts as text |
+| Partners | `"logo"`, `"tier"` `select`, `"website"` `link` |
+| People | `"role"`, `"photo"`, `"bio"`, `"team"` `select` (staff, board, advisors) |
+
+- **Chrome:** header with a Donate button; footer with the registered charity number, kept
+  once in the Global Layout.
+- **Donations:** the payment provider (Stripe, Donorbox, Classy, GiveWP) owns amounts,
+  recurring options and payment fields. Store the provider and its id, plus the copy around
+  the widget. The widget script stays code.
+- **Forms:** volunteer sign-up, newsletter, contact, event registration. Never payment details.
+- **Structured data:** `Organization` in `siteSchema` (`NGO` when it fits) with the registered
+  number, `Article` on stories, `Event` on events.
+- **Redirects:** campaign microsite URLs that fold into the main site get 301s to the program.
+- **Pitfalls:** impact numbers with no date or source (fill `"as_of"` and `"source"`, report
+  the rest as unverified); beneficiary photos and stories with no recorded consent (report as
+  rights unconfirmed); annual reports only as PDFs.
+
+## Multi-brand and multi-language
+
+Use when the source has several brands on one design system, `hreflang` alternates, `/de/` and
+`/fr/` paths or country domains, or a language switcher.
+
+### Multi-brand
+
+| Decision | Rule |
+|---|---|
+| Project boundary | One project per brand and domain. Each has its own brand kit, tokens, Global Layout and SEO settings |
+| Starting a new brand | Build one template project, then `clone_project` per brand. The clone copies pages, models, entries, components, media, forms and SEO settings; it leaves out submissions, analytics, domains and secrets |
+| Shared sections | The cloned components. After the clone they are separate copies: a later change is applied per project |
+| Shared content | Projects cannot reference each other's entries. Copy it and note where it came from, or serve it from one project that every brand's code reads. Report the choice |
+| Routes | Each brand keeps its own routes and `urlPattern` values; identical patterns across brands are fine |
+| Structured data | One `Organization` per brand in its own `siteSchema`. A parent company is a `parentOrganization` property, not a shared node |
+
+### Multi-language
+
+Full method: [localization.md](localization.md). The decisions that shape a blueprint:
+
+- A translation is its own page or entry carrying `locale` and `translationOf` (the source id).
+  Per-field localization does not exist. Never model `"title_en"` beside `"title_fr"`.
+- When crawls disagree on the default locale, take the one the root path serves and report
+  it; do not ask. The default fills the source rows; every other locale links back to them.
+- Match sections across locales by position and structure, never by text.
+- Never translate during a conversion. Copy what each locale publishes; report missing
+  translations. `translate_entry` creates drafts, costs AI credits and runs only on request.
+- Slugs are per locale; keep each locale's URLs. Alt text is copy and is translated; the image
+  is shared unless a locale shows a different one.
+- `hreflang` is never a field. The sitemap emits it from `locale` and `translationOf`; the
+  hosted head does not, so a site that needs it in the head renders the links in its own code.
+- A market page with a different structure (a US-only pricing page) is a separate page, not a
+  translation. A per-market header is a Layout locale variant, not a translation of copy.
+- **Structured data:** one canonical per locale. Never canonical every locale to the default.
+- **Redirects:** no IP-based redirects. A retired locale 301s to the default locale's page.
+- **Pitfalls:** machine translation during import; one model with a field per language; a
+  switcher linking to a page that exists in one locale only.