@bettercms-ai/mcp 0.68.2 → 0.69.0

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

@@ -1,6 +1,6 @@
 ---
 title: "Site blueprints"
-description: "Route, collection and section plans per business type: portfolio, agency, corporate, SaaS/AI and ecommerce."
+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
@@ -15,6 +15,8 @@ working site's taxonomy. The platform rules behind each layer are in
 - [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
@@ -26,6 +28,18 @@ working site's taxonomy. The platform rules behind each layer are in
     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).
 
@@ -78,6 +92,122 @@ Return a route tree, route matrix, content and model matrix, folder plan, compon
 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 |
+| 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 | `modular` |
+| 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`, `phone` |
+| 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` of label and value rows. Models have no typed table field |
+
+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`. 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.
+
 ## 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.
@@ -108,6 +238,32 @@ Use repeatable gallery items rather than a long list of `image1` fields. Give ea
 
 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"` | `modular`, or `document` | `modular` (text, image, gallery, quote, video, stats blocks) 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.
@@ -138,6 +294,27 @@ Content sidebar folders should match editor work: `Core pages`, `Services`, `Ind
 
 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.
@@ -212,6 +389,33 @@ Build topic hubs and link related solution, industry, integration, case, and glo
 
 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**.
@@ -233,7 +437,7 @@ Products, variants, SKUs, price, availability, tax, orders, checkout, customer a
 | 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 return 404/410 based on permanence and user value. Do not redirect every missing product to the homepage.
+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
 
@@ -248,3 +452,430 @@ Provide crawlable category → subcategory → product links and paginated resul
 ### 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. 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.