riverbankcms 0.2.0 → 0.4.0

package/dist/cli/init-docs/content/agents-section.md

@@ -1,6 +1,8 @@
 ## RiverbankCMS SDK Context
 
-This repository is a site using **RiverbankCMS** as a headless CMS via the `@riverbankcms/sdk` package.
+This repository is a fully headless site using **RiverbankCMS** as a CMS via
+the `@riverbankcms/sdk` package. The host owns markup, styles, and block
+rendering through the override registry.
 
 ### What This Means
 
@@ -23,7 +25,7 @@ Detailed documentation is available in `.riverbank/docs/`:
 - `content-management.md` - Content model and sync workflows
 - `schema.md` - Site-specific schema (auto-generated from config)
 - `block-types.md` - Available block types (auto-generated)
-- `theme-schema.md` - Theme schema reference (auto-generated from Zod)
+- `theme-schema.md` - Optional theme schema reference (auto-generated from Zod)
 - `workflows/` - Step-by-step guides for common tasks, including editor workflows
   - `workflows/agent-safe-sync.md` - Agent-safe dry-run, scoped push, and `--env` guidance
 - `site-workflows/` - Site-specific workflows and customizations
@@ -46,6 +48,11 @@ Use CLI `--env=remote` / `--env=local` for CMS commands rather than relying on `
 3. **Preview**: `riverbankcms push --dry-run` shows what would change
 4. **Push**: `riverbankcms push` applies changes to CMS
 
+Built-in semantic kinds such as `block.hero` remain in content JSON. Register
+the host-owned override for every kind the site uses in `src/lib/block-overrides.tsx`.
+The generated default uses `SITE_RENDERING` with override-only rendering and no
+CMS theme runtime.
+
 For narrow edits, push the narrowest scope possible, for example `riverbankcms push pages privacy-policy --env=remote --dry-run`. If broad local content is stale or contains unrelated differences, see `.riverbank/docs/workflows/agent-safe-sync.md`.
 
 ### Editing Page Content Directly

package/dist/cli/init-docs/content/cli-reference.md

@@ -10,7 +10,7 @@ All commands support these options:
 | ---------------- | ---------------------------------------------------------- |
 | `--json`         | Output a single JSON envelope for machine parsing          |
 | `--quiet`        | Minimal output (suppress non-essential messages)           |
-| `--env <target>` | Target environment: `local` (default), `remote`, or `both` |
+| `--env <target>` | Target project environment: `local` (default), `remote`, or `both` |
 | `--remote`       | **[Deprecated]** Use `--env=remote` instead                |
 
 **The `--json` envelope (single-document contract):** under `--json`, *every* invocation emits **exactly one** JSON document on stdout:
@@ -25,8 +25,8 @@ All commands support these options:
 
 **Environment targeting:**
 
-- `--env=local` (default): Target local Supabase/development environment
-- `--env=remote`: Target production CMS
+- `--env=local` (default): Target the local development CMS
+- `--env=remote`: Target the production CMS
 - `--env=both`: Run against both environments sequentially
 
 **Safety behavior:**
@@ -67,12 +67,55 @@ RIVERBANK_REMOTE_API_KEY=bld_live_sk_...  # Required for deploy command
 
 - Management API keys start with `bld_mgmt_sk_` (for write operations)
 - Content API keys start with `bld_live_sk_` (for read-only operations)
-- `RIVERBANK_*_SUPABASE_URL` is deprecated and ignored by media sync
 
 ---
 
 ## Setup Commands
 
+### Account authentication and site setup
+
+Account commands use a provider-neutral Riverbank account session. Select the
+account environment independently from the project `--env` target:
+
+Production account OAuth is deliberately rollout-disabled. The examples below
+use staging; use local for development. Do not use
+`--account-env=production` until the production account rollout is explicitly
+enabled.
+
+```bash
+riverbankcms login --account-env=staging
+riverbankcms whoami --account-env=staging
+riverbankcms sites list --account-env=staging
+riverbankcms sites create --account-env=staging --name "Dovetail" --yes
+riverbankcms logout --account-env=staging
+riverbankcms auth revoke --account-env=staging --yes
+```
+
+The CLI stores the refresh session in the OS credential store when available.
+If a locked-file fallback is required, the CLI explains the risk and requires
+`--allow-locked-file`. `logout` removes this machine’s stored session;
+`auth revoke` revokes the account grant so access tokens on other machines can
+no longer refresh. Neither operation removes sites, project credentials, or
+content.
+
+Use `link` for an existing project and `init` for a complete new project:
+
+```bash
+riverbankcms link --project ./my-site --account-env=staging --site <site-id> --preview
+riverbankcms init ./my-site --account-env=staging --name "Dovetail" --preview
+```
+
+Preview is explicit state. `--preview` includes preview routes and a preview
+credential; `--no-preview` omits both. Interactive `init` asks for the choice;
+JSON and other non-interactive mutations require an explicit choice and
+`--yes`. Published CLI projects install packages from npm. Local/tarball
+sources are test-fixture seams and are not public flags.
+
+Generated projects are provider-neutral and contain only Riverbank project
+configuration. The account refresh session is never written to the project
+env file, and no database-provider URL, provider auth token, or service-role
+credential is scaffolded.
+
 ### setup plan
 
 Show the safe site, key, user access, and env setup lifecycle for the selected environment.
@@ -88,10 +131,31 @@ riverbankcms setup plan --env=remote
 riverbankcms setup plan --env=both --json
 ```
 
-The setup planner is read-only. It does not create sites, issue API keys, or grant dashboard access. Those operations require a dashboard/admin actor or an approved CMS repo script with service-role/admin credentials. SDK management keys are site-scoped and are only used for verifying access and syncing content/config for an existing site.
+The setup planner is read-only. It reports which values are missing and shows
+the supported lifecycle. Use `riverbankcms sites create`, `riverbankcms link`,
+or `riverbankcms init` with an authenticated account session to create sites
+and issue project credentials for the signed-in account. Use the dashboard to
+grant access to additional users. SDK management keys are site-scoped and are
+used for project sync; they cannot create sites or grant other users access.
 
 Use this command when a project has missing `RIVERBANK_*_SITE_ID`, `RIVERBANK_*_DASHBOARD_URL`, or `RIVERBANK_*_MGMT_API_KEY` values, or when onboarding an existing remote site into an SDK repo.
 
+### Post-deployment revalidation
+
+`init` scaffolds `/api/revalidate` but does not register a webhook or write a
+webhook secret. After the project has a public HTTPS origin, activate it
+explicitly:
+
+```bash
+riverbankcms webhooks setup \
+  --env=remote \
+  --url=https://www.example.com/api/revalidate \
+  --yes
+```
+
+Until setup is complete, the generated site’s ISR interval is the freshness
+fallback. Keep the one-time webhook secret in the deployment environment.
+
 ---
 
 ## Content Sync Commands
@@ -139,7 +203,6 @@ riverbankcms pull --output ./src/content
 | `--yes`             | Skip confirmation prompt                                                             |
 | `--local-media`     | Download media referenced by identifiers to content/media                            |
 | `--sync-media`      | Sync media files between environments                                                |
-| `--overwrite-media` | When using `--sync-media`, overwrite target media on checksum mismatch               |
 | `--with-theme`      | Also pull theme when pulling all content                                             |
 | `--name <name>`     | Theme name for `pull theme` / `pull --with-theme` (default: current)                 |
 | `--no-meta`         | Skip writing `.meta/` and media manifest files (content files still written)         |
@@ -201,14 +264,12 @@ If unrelated local files would be included by a broad scope, stage a temporary c
 | `--dry-run`            | Show changes without applying                                                        |
 | `--yes`                | Skip confirmation (required for `--env=remote` or `--env=both`)                      |
 | `--force`              | Push even if remote is newer (skip stale check)                                      |
-| `--force-update-asset` | Replace CMS media when identifiers conflict (local media sync only)                  |
 | `--allow-truncated`    | Push even if remote content was truncated (may cause incomplete sync)                |
 | `--diff-detail <mode>` | Diff verbosity carried in the `--json` envelope: `summary` (default) or `full`       |
 | `--json-diff [mode]`   | **[Deprecated]** Alias of `--diff-detail`; folded into the `--json` envelope (warns on stderr) |
 | `--with-config`        | Push SDK schema/config before dependent file content                                |
 | `--with-theme`         | Also push theme when pushing all content                                             |
 | `--sync-media`         | Sync media files from local to remote environment                                    |
-| `--overwrite-media`    | When using `--sync-media`, overwrite target media on checksum mismatch               |
 | `--merge-remote`       | Plan an entries/pages three-way merge for `--env=remote` that preserves remote edits |
 | `--delete-orphaned`    | Delete CMS entries not present in local files                                        |
 | `--auto-pull-stale`    | Automatically pull stale content and retry push                                      |
@@ -356,6 +417,42 @@ export default defineConfig({
 
 **Status Sync**: Push automatically syncs draft/published status based on the `status` field in your local content files. If local content is "published" but remote is "draft", push will publish it. If local is "draft" but remote is "published", push will unpublish it.
 
+### settings booking configure
+
+Configure the site's booking vertical and selected presets through the
+purpose-built settings operation:
+
+```bash
+# Ask the server for an authoritative preview; do not write
+riverbankcms settings booking configure \
+  --vertical fitness_pt \
+  --preset fitness_pt.group_training \
+  --dry-run --json
+
+# Apply locally, or target production with --env=remote --yes
+riverbankcms settings booking configure \
+  --vertical fitness_pt \
+  --preset fitness_pt.group_training \
+  --yes
+```
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `--vertical <vertical>` | Required canonical booking vertical identifier |
+| `--preset <preset>` | Required preset identifier; repeat for multiple presets |
+| `--dry-run` | Show the server-authoritative preview without writing |
+| `--yes` | Skip confirmation; required for JSON/non-interactive writes |
+
+The command validates the selection locally, previews on the server, and
+revalidates immediately before applying. `--env=both` preflights both targets,
+then applies local before remote. Changing the vertical does not rewrite
+existing offerings or their stored presets. The declarative equivalent is
+`verticalConfig` in `content/settings.json` followed by `riverbankcms push
+settings`; `riverbankcms pull settings` writes the canonical configuration
+back to that file.
+
 ### push-config
 
 Push SDK configuration to the CMS dashboard.

package/dist/cli/init-docs/content/content-management.md

@@ -75,16 +75,19 @@ content/
   navigation.json     # All navigation menus
 ```
 
-### 5. Themes
+### 5. Themes (Optional Opt-in)
 
-Site theme objects used for rendering blocks.
+CMS theme objects are optional. Fully headless sites use host-owned markup,
+styles, and block overrides instead of loading a CMS theme or SDK runtime
+styles. Use a theme only when the site intentionally opts into themed built-in
+rendering or local theme iteration.
 
 **Local file structure:**
 
 ```
 content/
   themes/
-    current.json      # Default theme (pulled from CMS or edited locally)
+    current.json      # Optional theme (pulled from CMS or edited locally)
 ```
 
 ### 6. Footer Content
@@ -130,6 +133,12 @@ content/
     yoga-class.json   # Event with schedule, pricing, venue/category refs
 ```
 
+Event registration keeps the semantic `block.event-registration` kind. In the
+fully headless default, register a host-owned `event-registration` override and
+own its markup, accessibility, and styles. Use the public
+`useHeadlessEventRegistrationFlow` controller from `@riverbankcms/sdk/bookings`
+where it fits; controller support varies by functional block.
+
 ---
 
 ## Working with Identifiers
@@ -223,6 +232,42 @@ Notes:
 - `riverbankcms pull settings` warns and omits `logoIdentifier` / `faviconIdentifier` if the current CMS branding asset has no media identifier yet
 - Dashboard branding edits and CLI pushes both update the same site settings row, so treat them as last-write-wins and pull before pushing after dashboard-side edits
 
+### Configure the booking vertical
+
+Booking vertical selection is a purpose-built settings operation rather than a
+generic `settings.update` field. The CLI validates the vertical and every
+preset against the canonical catalog before contacting the CMS:
+
+```bash
+# Preview the server-authoritative result without changing the site
+riverbankcms settings booking configure \
+  --vertical fitness_pt \
+  --preset fitness_pt.group_training \
+  --dry-run --json
+
+# Apply the same configuration to the local CMS
+riverbankcms settings booking configure \
+  --vertical fitness_pt \
+  --preset fitness_pt.group_training \
+  --yes
+```
+
+Repeat `--preset` to select more than one preset. Use `--env=remote` or
+`--env=both --yes` to target the other project environment. The command asks
+the server for a preview before applying and revalidates that preview
+immediately before the write; `--dry-run` reports that authoritative preview
+without writing anything. JSON and other non-interactive writes require
+`--yes`.
+
+Changing the vertical does not rewrite existing offerings. Their stored
+presets remain unchanged; this operation only changes the site-level booking
+configuration.
+
+The declarative equivalent is to add `verticalConfig` to
+`content/settings.json` and run `riverbankcms push settings` (or the relevant
+scope of `riverbankcms push`). Pulling settings writes the canonical vertical
+and preset order back to that file.
+
 ---
 
 ## Draft vs Published
@@ -423,14 +468,12 @@ Use this when you explicitly want to copy media bytes between environments witho
 # Remote storage -> local storage (identifier + checksum based)
 riverbankcms pull --env=remote --sync-media --yes
 
-# Fail-safe by default: checksum mismatches abort unless you explicitly overwrite
-riverbankcms pull --env=remote --sync-media --overwrite-media --yes
+# Checksum mismatches abort; delete the target asset first or use a new identifier
 ```
 
 Notes:
 
-- `--sync-media` is **identifier + checksum** based. If the target already has an identifier with different bytes, the command fails unless you pass `--overwrite-media`.
-- When pulling from remote, `--sync-media` may need to **write to the source CMS** to backfill missing identifiers, so remote sync requires `--yes`.
+- `--sync-media` is **identifier + checksum** based. If the target already has an identifier with different bytes, the command fails without modifying either asset.
 - Local media bytes live under `content/media/`, which is treated as cache/migration working data by default in generated SDK sites.
 
 #### Promote local files → production CMS

package/dist/cli/init-docs/content/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started with RiverbankCMS SDK
 
-This site uses RiverbankCMS as a headless CMS. Content is managed through the Riverbank CLI.
+This site uses RiverbankCMS as a fully headless CMS. Content is managed through the Riverbank CLI, while the host owns markup, styles, and block rendering.
 
 ## Quick Setup
 
@@ -36,12 +36,10 @@ content/
 │   └── [content-type].json
 ├── pages/
 │   └── [page-identifier].json
-├── themes/
-│   └── current.json
 └── navigation.json
 ```
 
-You can also pull just the theme:
+Themes are optional. Only add `content/themes/` when this site explicitly opts into CMS/local theme rendering; fully headless sites use the host-owned `SITE_RENDERING` override-only configuration and do not need a theme file. The CLI still supports pulling a theme when you choose that opt-in:
 
 ```bash
 riverbankcms pull theme
@@ -76,11 +74,11 @@ Apply changes to the CMS:
 riverbankcms push
 ```
 
-## Local Theme Iteration (Edge-safe)
+## Optional Local Theme Iteration (Edge-safe)
 
-If your SDK site uses `createCatchAllPage()`, you can render with local theme objects (and switch themes at runtime) without pushing theme changes to the CMS. See `cli-reference.md` for theme pull/push commands and the SDK README for the `createCatchAllPage({ themes, themeSwitch })` API.
+Fully headless sites do not load CMS themes or SDK runtime styles by default. If a site intentionally opts into themed built-in rendering, `createCatchAllPage()` can render local theme objects (and switch themes at runtime) without pushing theme changes to the CMS. See `cli-reference.md` for the legitimate theme pull/push commands and the SDK README for the `createCatchAllPage({ themes, themeSwitch })` API.
 
-Event registration blocks need both the SDK base stylesheet and a runtime theme scope. Generated SDK pages that render inside `Layout` get `ThemeScope` by default. Standalone `Page` or `Block` usage should wrap registration content in `ThemeBridgeProvider` or manual `generateThemeBridgeCss` with a `data-theme-scope="sdk"` wrapper; keep visual changes in scoped CSS variables instead of forking booking logic.
+Event registration keeps the semantic `block.event-registration` kind, but its UI is host-owned in the fully headless default. Register an `event-registration` override in `src/lib/block-overrides.tsx` and use the public `useHeadlessEventRegistrationFlow` controller from `@riverbankcms/sdk/bookings` where it fits; own the markup, accessibility, and styles in the host. Other functional blocks may have different public controller support, so check their SDK surface rather than assuming a controller exists for every kind.
 
 ## Key Documentation
 
@@ -90,7 +88,7 @@ Event registration blocks need both the SDK base stylesheet and a runtime theme
 | `content-management.md` | How content is structured                                        |
 | `schema.md`             | This site's content types and blocks (auto-generated)            |
 | `block-types.md`        | Available block types (auto-generated)                           |
-| `theme-schema.md`       | Theme schema reference (auto-generated from Zod)                 |
+| `theme-schema.md`       | Optional theme schema reference (auto-generated from Zod)        |
 | `workflows/`            | Step-by-step guides for common tasks, including editor workflows |
 | `workflows/agent-safe-sync.md` | Agent-safe dry-run, scoped push, and stale-content handling |
 
@@ -127,13 +125,13 @@ Additional content configuration for scaffolding.
 
 ## Working with Remote/Production
 
-If the remote site, management key, or dashboard user access is not set up yet, start with the safe setup planner:
+If the remote site or project management key is not set up yet, start with the safe setup planner:
 
 ```bash
 riverbankcms setup plan --env=remote
 ```
 
-See `workflows/remote-setup.md` for the full site/key/user lifecycle. The Riverbank CLI uses site-scoped management keys for sync; remote site creation, key issuance, and user access changes stay in the dashboard/admin surface.
+See `workflows/remote-setup.md` for the full site/key/user lifecycle. The authenticated Riverbank CLI can create a site and link project credentials for the signed-in account. Use the dashboard to grant access to additional users.
 
 Use `--env=remote` to target production instead of local:
 

package/dist/cli/init-docs/content/workflow-add-block.md

@@ -2,6 +2,13 @@
 
 This workflow guides you through adding a block to an existing page.
 
+Generated sites use fully headless, override-only rendering by default. Keep
+the built-in semantic kind in CMS content (for example, `block.hero` or
+`block.body-text`), then register the host-owned renderer for every kind the
+site uses in `src/lib/block-overrides.tsx`. The registry uses short semantic
+keys such as `hero`; an unregistered kind raises `MissingBlockOverrideError`
+instead of falling back to a built-in renderer.
+
 ## Prerequisites
 
 - Page already exists in the CMS
@@ -25,7 +32,7 @@ View built-in blocks in `block-types.md`. Common block kinds:
 
 Check `schema.md` for custom blocks specific to this site.
 
-Prefer built-in blocks before creating a custom block. For a simple policy/terms/about page, use `block.body-text` and put the page title, intro, and section headings in the rich text body. Only create a custom block when the needed structure or behavior cannot be represented by built-in blocks plus styling.
+Prefer built-in blocks before creating a custom block. For a simple policy/terms/about page, use `block.body-text` and put the page title, intro, and section headings in the rich text body. Only create a custom block when the needed structure or behavior cannot be represented by built-in blocks plus a host-owned override or styling.
 
 ### 2. List Existing Blocks
 

package/dist/cli/init-docs/content/workflow-block-extensions.md

@@ -2,6 +2,12 @@
 
 Add layout variants and custom fields to built-in system blocks without creating entirely new custom blocks.
 
+In a fully headless generated site, the CMS kind remains a built-in semantic
+kind such as `block.hero`; the host owns how that kind is rendered. Register
+the host component for the kind in `src/lib/block-overrides.tsx` after adding
+the extension. An extension changes the content contract, not the rendering
+authority.
+
 ## When to Use Block Extensions
 
 **Use block extensions when:**
@@ -24,7 +30,7 @@ See `.riverbank/docs/block-types.md` for which system blocks support variants an
 ## Prerequisites
 
 - `riverbank.config.ts` exists
-- Block overrides file set up (e.g., `src/lib/block-overrides.tsx`)
+- Host override registry set up (e.g., `src/lib/block-overrides.tsx`)
 - Understanding of the system block you're extending
 
 ## Steps
@@ -103,18 +109,23 @@ export function CustomHero({ content, ...props }: BlockOverrideProps<ExtendedHer
 }
 ```
 
-### Step 3: Register in blockOverrides
+### Step 3: Register in `blockOverrides`
 
-Add your override component to the block overrides:
+Add your host-owned override component to the typed registration map. The CMS
+content continues to use `block.hero`; `hero` is the corresponding short
+registry key.
 
 ```typescript
 // src/lib/block-overrides.tsx
-import type { BlockOverrides } from '@riverbankcms/sdk/rendering';
+import {
+  defineBlockOverrideRegistrations,
+  type BlockOverrideRegistrations,
+} from '@riverbankcms/sdk/rendering';
 import { CustomHero } from '@/components/CustomHero';
 
-export const blockOverrides: BlockOverrides = {
+export const blockOverrides = defineBlockOverrideRegistrations({
   hero: CustomHero,
-};
+}) satisfies BlockOverrideRegistrations;
 ```
 
 ### Step 4: Push Config
@@ -323,6 +334,11 @@ blockFieldExtensions: {
 **Override component:**
 
 ```typescript
+import {
+  defineBlockOverrideRegistrations,
+  type BlockOverrideRegistrations,
+} from '@riverbankcms/sdk/rendering';
+
 type ExtendedHeroContent = HeroContent & {
   layout?: 'default' | 'topography';
   topographyColor?: 'teal' | 'green' | 'tan' | 'brown';
@@ -338,9 +354,9 @@ const HeroOverride = (props: BlockOverrideProps<ExtendedHeroContent>) => {
   return <CustomHeroWithCanvas {...props} />;
 };
 
-export const blockOverrides: BlockOverrides = {
+export const blockOverrides = defineBlockOverrideRegistrations({
   hero: HeroOverride,
-};
+}) satisfies BlockOverrideRegistrations;
 ```
 
 ## Troubleshooting
@@ -359,7 +375,7 @@ export const blockOverrides: BlockOverrides = {
 
 ### Override component not rendering
 
-- Verify the override is registered in `blockOverrides`
+- Verify the host override is registered in `blockOverrides`
 - Check the key matches the block name (e.g., `hero` for `block.hero`)
 - Ensure the component is exported correctly
 

package/dist/cli/init-docs/content/workflow-custom-block.md

@@ -2,6 +2,11 @@
 
 Create a site-specific block with custom fields and rendering when system blocks don't meet your needs.
 
+Generated sites are fully headless by default: custom block kinds are content
+semantics, while the host owns their markup and styles. Register each custom
+kind in the host override registry; missing registrations fail visibly instead
+of falling back to a CMS renderer.
+
 ## When to Use Custom Blocks
 
 Before creating a custom block, check `block-types.md` and the site `schema.md`. Many content needs are already covered by system blocks:
@@ -26,7 +31,7 @@ Do not create a custom block just to get “a rich text area with different spac
 ## Prerequisites
 
 - `riverbank.config.ts` exists
-- Block overrides file set up (e.g., `src/lib/block-overrides.tsx`)
+- Host override registry set up (e.g., `src/lib/block-overrides.tsx`)
 - Understanding of the content structure you need
 
 ## Steps
@@ -163,18 +168,40 @@ export function OurFlowBlock({ content }: BlockOverrideProps<OurFlowContent>) {
 }
 ```
 
-### Step 4: Register in blockOverrides
+### Step 4: Register in `blockOverrides`
 
-Add your component to the block overrides:
+Register the host component with the typed registrations helper. The CMS
+content keeps the semantic `custom.our-flow` kind.
 
 ```typescript
 // src/lib/block-overrides.tsx
-import type { BlockOverrides } from '@riverbankcms/sdk/rendering';
+import {
+  defineBlockOverrideRegistrations,
+  type BlockOverrideRegistrations,
+} from '@riverbankcms/sdk/rendering';
 import { OurFlowBlock } from '@/components/OurFlowBlock';
 
-export const blockOverrides: BlockOverrides = {
+export const blockOverrides = defineBlockOverrideRegistrations({
   'custom.our-flow': OurFlowBlock,
-};
+}) satisfies BlockOverrideRegistrations;
+```
+
+For client-heavy or rarely used blocks, wrap the dynamic import with
+`defineLazyBlockOverride` so the component is loaded only when its kind is
+rendered:
+
+```typescript
+import {
+  defineBlockOverrideRegistrations,
+  defineLazyBlockOverride,
+  type BlockOverrideRegistrations,
+} from '@riverbankcms/sdk/rendering';
+
+export const blockOverrides = defineBlockOverrideRegistrations({
+  'custom.our-flow': defineLazyBlockOverride(async () =>
+    import('@/components/OurFlowBlock').then((module) => module.OurFlowBlock),
+  ),
+}) satisfies BlockOverrideRegistrations;
 ```
 
 ### Step 5: Push Config
@@ -453,8 +480,8 @@ Pricing cards with nested features and conditional button actions:
 
 ### Component not rendering
 
-- Verify override is registered with exact block ID
-- Check the key in `blockOverrides` matches (e.g., `'custom.our-flow'`)
+- Verify the host override is registered with the exact block ID
+- Check the key in `blockOverrides` matches the semantic kind (e.g., `'custom.our-flow'`)
 - Ensure component is exported correctly
 
 ### Repeater items not working

package/dist/cli/init-docs/content/workflow-preview-mode.md

@@ -4,6 +4,11 @@
 
 Enable dashboard preview editing for an SDK-hosted Next.js site. Preview mode lets the dashboard open the external site with a short-lived editor session, render draft content, and show the Riverbank preview shell.
 
+The generated fully headless site keeps `SITE_RENDERING` as the rendering
+authority in both the live catch-all route and this preview path. Preserve its
+`overrides-only`/`runtime: none` contract when adding preview behavior: preview
+changes the content/session source, not who owns block markup and styles.
+
 ## Prerequisites
 
 - A Riverbank SDK site using the Next.js App Router.
@@ -111,13 +116,20 @@ import {
 } from '@riverbankcms/sdk/preview-next/client'
 
 import { blockOverrides } from '@/lib/block-overrides'
+import { SITE_RENDERING } from '@/lib/rendering'
 
 export function SdkPreviewModeClient(
   props: SdkPreviewModePropsWithoutBlockOverrides
 ) {
+  const { themeRuntime: _themeRuntime, ...previewProps } = props
+
   return (
     <PreviewQueryProvider>
-      <SdkPreviewMode {...props} blockOverrides={blockOverrides} />
+      <SdkPreviewMode
+        {...previewProps}
+        rendering={SITE_RENDERING}
+        blockOverrides={blockOverrides}
+      />
     </PreviewQueryProvider>
   )
 }
@@ -134,11 +146,13 @@ import { createPreviewModeBeforeRender } from '@riverbankcms/sdk/preview-next/be
 import config from '../../../riverbank.config'
 import { blockOverrides } from '@/lib/block-overrides'
 import { getRiverbankClient } from '@/lib/riverbank-client'
+import { SITE_RENDERING } from '@/lib/rendering'
 import { SdkPreviewModeClient } from '@/components/preview/SdkPreviewModeClient'
 
 const { Page, generateMetadata } = createCatchAllPage({
   getClient: getRiverbankClient,
   config,
+  rendering: SITE_RENDERING,
   blockOverrides,
   beforeRender: createPreviewModeBeforeRender({
     getClient: getRiverbankClient,
@@ -151,9 +165,16 @@ export default Page
 export { generateMetadata }
 ```
 
-## Custom Header/Footer Chrome
+## Optional Custom Preview Chrome
 
-If your site replaces the SDK header or footer, pass that chrome into `PreviewLayoutProvider` only when there is an editable preview session. `RIVERBANK_PREVIEW_MODE=true` makes the route preview-capable, but `getPreviewSession()` tells you whether the current request actually has preview cookies. Regular visitors without preview cookies should keep the normal SDK `Layout`.
+Fully headless generated sites keep a plain host-owned root layout. If the host
+replaces the preview header or footer, pass that chrome into
+`PreviewLayoutProvider` only when there is an editable preview session.
+`RIVERBANK_PREVIEW_MODE=true` makes the route preview-capable, but
+`getPreviewSession()` tells you whether the current request actually has
+preview cookies. Regular visitors without preview cookies should keep the
+site's normal layout. The `Layout` example below is only for a site that
+intentionally opts into themed SDK rendering.
 
 In `src/app/layout.tsx`:
 
@@ -212,9 +233,12 @@ export default async function RootLayout({
 
 If your custom chrome needs CMS navigation data, build the `headerNode` and `footerNode` from the same data used by your normal layout before branching. Calling `getPreviewSession()` in the root layout reads cookies, so the layout becomes dynamic.
 
-## Import Preview CSS
+## Import Preview Editor Chrome CSS
 
-For Tailwind sites, add this to `src/app/globals.css`:
+Preview-enabled sites need the SDK preview editor chrome styles even when they
+are fully headless. These imports provide the preview shell and editor chrome;
+they are not the CMS theme or built-in block styles. A Tailwind site can add
+this to `src/app/globals.css`:
 
 ```css
 @import 'tailwindcss';
@@ -222,7 +246,7 @@ For Tailwind sites, add this to `src/app/globals.css`:
 @import '@riverbankcms/sdk/preview-next/chrome.css';
 ```
 
-For non-Tailwind sites, use the legacy single import:
+For non-Tailwind sites, use the legacy single preview-chrome import:
 
 ```css
 @import '@riverbankcms/sdk/preview-next/styles.css';