riverbankcms 0.1.0 → 0.2.2

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
@@ -914,14 +978,14 @@ riverbankcms event get summer-fest
 riverbankcms event upsert summer-fest --file ./content/events/summer-fest.json
 riverbankcms event cancel summer-fest
 riverbankcms event delete summer-fest --yes
-riverbankcms event occurrence list summer-fest
-riverbankcms event occurrence add summer-fest \
+riverbankcms event occurrence list summer-fest summer-run
+riverbankcms event occurrence add summer-fest summer-run \
   --starts-at 2026-08-01T10:00 \
   --duration-minutes 60
-riverbankcms event occurrence update summer-fest <occurrence-uuid> \
+riverbankcms event occurrence update summer-fest summer-run <occurrence-uuid> \
   --capacity 20
-riverbankcms event occurrence cancel summer-fest <occurrence-uuid>
-riverbankcms event occurrence delete summer-fest <occurrence-uuid> --yes
+riverbankcms event occurrence cancel summer-fest summer-run <occurrence-uuid>
+riverbankcms event occurrence delete summer-fest summer-run <occurrence-uuid> --yes
 ```
 
 `event upsert` and `push events` accept canonical event files with `path` and `blocks`. Events use native page authority: an `eventOffering` or `eventSeries` subject owns a page surface, and that surface owns its route, field content, publication state, and slots. `path` updates the page-surface route. `blocks` maps slot keys to surface-slot blocks, for example `blocks.main` for the built-in event template. Use stable block identifiers so repeat pushes update existing slot blocks safely. Unknown slot keys or block kinds fail validation; default slots accept enabled SDK `custom.*` blocks, while explicit template `allowedBlocks` lists remain authoritative. Ordinary editorial entries continue to use the separate `entry` commands and content-entry model described above.
@@ -932,7 +996,9 @@ riverbankcms event occurrence delete summer-fest <occurrence-uuid> --yes
 series. Mutation commands always use the occurrence UUID shown by `list`; a
 calendar date is never accepted as an identity.
 
-- `list <event-identifier>` shows all future dates, including cancelled dates.
+- `list <event-identifier> <run-identifier>` shows all future dates, including
+  cancelled dates. The parent Event and run are both explicit, so multi-run
+  Events never rely on an ambiguous identifier.
   Add `--all` to include history or `--status scheduled|cancelled|completed` to
   filter. The CLI follows the API's bounded pages, while `--json` keeps the
   canonical UTC instants in its single result envelope.

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

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-isr-revalidation.md

@@ -7,12 +7,13 @@ Configure a Riverbank SDK Next.js App Router site to prerender published routes,
 ## Prerequisites
 
 - A Riverbank SDK site using `createCatchAllPage()` in `src/app/[[...slug]]/page.tsx`.
-- A production content API key in `RIVERBANK_API_KEY`.
-- `RIVERBANK_SITE_ID` set to this site's Riverbank site ID.
-- `NEXT_PUBLIC_DASHBOARD_URL` set to the dashboard origin, for example `https://cms.example.com`.
+- A configured `getRiverbankClient()` helper and `siteId` in `riverbank.config.ts`.
 - `RIVERBANK_WEBHOOK_SECRET` set from the CMS-generated Riverbank webhook secret.
 
-Preview deployments should also set `RIVERBANK_PREVIEW_MODE=true` so draft previews stay dynamic instead of serving stale ISR HTML.
+Sites scaffolded with preview support should set `RIVERBANK_PREVIEW_MODE=true` in
+preview deployments. The SDK preview integration reads the request-bound preview
+session and opts those requests into dynamic rendering; the literal ISR interval
+remains unchanged.
 
 ## Configure the Catch-All Route
 
@@ -21,21 +22,26 @@ In `src/app/[[...slug]]/page.tsx`:
 ```tsx
 import {
   createCatchAllPage,
-  generateAllStaticParams,
-  getISRConfig,
+  createGenerateStaticParams,
 } from '@riverbankcms/sdk/next'
 
 import config from '@/riverbank.config'
 import { blockOverrides } from '@/lib/block-overrides'
 import { getRiverbankClient } from '@/lib/riverbank-client'
 
-export const revalidate = getISRConfig().revalidate
+// Next.js route config values must remain statically analyzable literals.
+export const revalidate = 300
 export const dynamicParams = true
-export { generateAllStaticParams as generateStaticParams }
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+  failureMode: 'throw',
+})
 
 const { Page, generateMetadata } = createCatchAllPage({
   getClient: getRiverbankClient,
   config,
+  searchParamsMode: 'ignore',
   blockOverrides,
 })
 
@@ -43,7 +49,18 @@ export default Page
 export { generateMetadata }
 ```
 
-`generateAllStaticParams()` discovers published pages and routable entries at build time. It reads:
+`searchParamsMode: 'ignore'` is required for this ISR shape because reading the
+Next.js page `searchParams` prop opts the route into dynamic rendering. Use the
+default `dynamic` mode only when server-rendered themes, data loaders, redirects,
+or metadata genuinely depend on URL query parameters.
+
+`createGenerateStaticParams()` uses the site's configured client to discover
+published pages and routable entries at build time. The example uses strict
+failure handling so production CI cannot silently publish an incomplete route
+set.
+
+If a site instead uses the SDK's generic environment variable names,
+`generateAllStaticParams()` is available. It reads:
 
 - `RIVERBANK_API_KEY`
 - `RIVERBANK_SITE_ID`
@@ -59,21 +76,6 @@ export function generateStaticParams() {
 }
 ```
 
-If your site already centralizes the SDK client, use the explicit factory:
-
-```tsx
-import { createGenerateStaticParams } from '@riverbankcms/sdk/next'
-
-import config from '@/riverbank.config'
-import { getRiverbankClient } from '@/lib/riverbank-client'
-
-export const generateStaticParams = createGenerateStaticParams({
-  getClient: getRiverbankClient,
-  siteId: config.siteId,
-  failureMode: 'throw',
-})
-```
-
 ## Add the Revalidation Route
 
 Create `src/app/api/revalidate/route.ts`:

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';