riverbankcms 0.2.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

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

package/dist/cli/init-docs/content/workflow-remote-setup.md

@@ -1,6 +1,9 @@
 # Remote Site, Key, and User Access Setup
 
-This SDK project can sync content once it has a site ID, dashboard URL, and site-scoped management key. Creating the remote site, issuing keys, and granting dashboard user access are admin operations.
+This SDK project can sync content once it has a site ID, dashboard URL, and
+site-scoped management key. The authenticated Riverbank CLI can create a site
+and link project credentials for the signed-in account. Additional user access
+remains a dashboard operation.
 
 ## Check the Plan
 
@@ -18,18 +21,50 @@ riverbankcms setup plan --env=remote --json
 
 ## Authority Model
 
-- Dashboard/admin users can create sites, issue site-scoped management keys, and grant dashboard access.
-- Approved CMS repo scripts can do the same when run with service-role/admin credentials.
-- SDK management keys can verify access and sync content/config for one site. They cannot create sites, issue new keys, or grant user access.
+- The authenticated Riverbank CLI can create sites and issue project
+  credentials for the signed-in account through `sites create`, `link`, and
+  `init`.
+- Dashboard administrators can manage sites, issue credentials, and grant
+  access to additional users.
+- SDK management keys can verify access and sync content/config for one site.
+  They cannot create sites or grant other users access.
 
-Do not put platform-admin, service-role, or user-session credentials in an SDK site repository.
+The CLI stores its refresh session in the OS credential store when available.
+It never puts account sessions, platform-admin credentials, or service-role
+credentials in an SDK site repository.
+
+Production account OAuth is deliberately rollout-disabled. Use the staging (or
+local) account environment while that rollout is disabled; replace
+`<account-environment>` with `production` only after production account access
+has been explicitly enabled.
 
 ## Remote Setup Lifecycle
 
-1. Create or choose the remote site from the dashboard/admin surface.
-2. Generate a management key for that site.
-3. Grant the site owner or editor dashboard access from the dashboard/admin surface.
-4. Add the remote SDK variables to `.env.local`:
+1. Sign in to the account environment:
+
+```bash
+riverbankcms login --account-env=<account-environment>
+```
+
+2. Create a site or choose one visible to the signed-in account:
+
+```bash
+riverbankcms sites list --account-env=<account-environment>
+riverbankcms sites create --account-env=<account-environment> --name "My Site" --yes
+```
+
+3. Link the project. `--preview` includes preview routes and a preview
+   credential; use `--no-preview` to omit them:
+
+```bash
+riverbankcms link --project . --account-env=<account-environment> --site <site-id> --preview
+```
+
+For a new directory, use `riverbankcms init` instead; it scaffolds, links,
+initializes docs, and builds the complete project.
+
+4. Add the remote SDK variables to `.env.local` when linking an existing
+   project manually:
 
 ```bash
 RIVERBANK_REMOTE_SITE_ID=your-site-id
@@ -48,4 +83,25 @@ riverbankcms push --env=remote --dry-run
 
 ## Existing Sites and Users
 
-For an existing remote site, copy its site ID and create a fresh site-scoped management key if the old one is missing or should be rotated. Associate existing users with the site through the dashboard/admin surface. If the user does not exist yet, invite or create them through that approved flow rather than through the Riverbank CLI.
+For an existing remote site, use `riverbankcms link` so the CLI issues the
+needed site-scoped credentials and writes only ignored project env files.
+Associate additional users with the site through the dashboard/admin surface.
+If local work fails after the site is created, keep the site and resume with
+the reported `riverbankcms init --resume <directory>` command after fixing the
+local error.
+
+## Post-deployment revalidation
+
+`init` scaffolds `/api/revalidate` but does not register a webhook or write a
+webhook secret. Once the deployed site has a public HTTPS origin, activate
+revalidation explicitly:
+
+```bash
+riverbankcms webhooks setup \
+  --env=remote \
+  --url=https://www.example.com/api/revalidate \
+  --yes
+```
+
+Until then, the generated site’s ISR interval is the freshness fallback. Keep
+the one-time webhook secret in the deployment environment, not source control.

package/dist/{eventUpsertInputSchema-BUeXa6jk.mjs → eventUpsertInputSchema-CzMX5BZI.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as classifySdkEventPricing, i as classifySdkEventSchedule, o as classifySdkEventPaymentTerms, r as sdkEventUpsertOptionalFieldSchemas } from "./sdk-event-upsert-CTqsrhFT.mjs";
+import { a as classifySdkEventPricing, i as classifySdkEventSchedule, o as classifySdkEventPaymentTerms, r as sdkEventUpsertOptionalFieldSchemas } from "./sdk-event-upsert-BCZUdIrL.mjs";
 import { z } from "zod";
 
 //#region ../blocks/src/lib/typeGuards.ts
@@ -2044,21 +2044,21 @@ const EVENT_CONTENT_TYPE_SCHEMA = {
 		{
 			id: "summary",
 			type: "textarea",
-			label: "Summary",
-			description: "Short teaser shown in listings.",
+			label: "Short introduction",
+			description: "Write one or two sentences that help people quickly understand what this is. It appears wherever the event is listed and near the top of its page.",
 			rows: 3
 		},
 		{
 			id: "image",
 			type: "media",
-			label: "Listing image",
-			description: "Optional image used for event cards and previews."
+			label: "Event image",
+			description: "Choose the main image people will see wherever the event is listed and on its page."
 		},
 		{
 			id: "body",
 			type: "richText",
-			label: "Details",
-			description: "Full event details and agenda."
+			label: "About this event",
+			description: "Add the main information people need before booking—what to expect, who it’s for, what’s included, and anything they should bring or know."
 		}
 	],
 	routing: {
@@ -4917,6 +4917,7 @@ const eventUpsertInputSchema = z.object({
 		"event",
 		"class",
 		"course",
+		"term",
 		"workshop",
 		"retreat",
 		"performance"

package/dist/load-config-226EuL6w.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import "./sdk-peer-DiZYsNXj.mjs";
+import { t as loadConfigFile } from "./load-config-Boa0tkmk.mjs";
+
+export { loadConfigFile };