@riverbankcms/sdk 0.82.0 → 0.84.1

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

@@ -25,6 +25,7 @@ Detailed documentation is available in `.riverbank/docs/`:
 - `block-types.md` - Available block types (auto-generated)
 - `theme-schema.md` - 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
 
 ### Quick Commands
@@ -36,6 +37,8 @@ riverbankcms push              # Push local changes to CMS
 riverbankcms push-config       # Sync riverbank.config.ts schema/config to CMS
 ```
 
+Use CLI `--env=remote` / `--env=local` for CMS commands rather than relying on `RIVERBANK_ENV=...` shell prefixes. Site `.env.local` files may set `RIVERBANK_ENV`, and the CLI flag is the explicit source of truth for sync operations.
+
 ### Working with Content
 
 1. **Pull latest**: `riverbankcms pull` downloads content to `content/` directory
@@ -43,6 +46,8 @@ riverbankcms push-config       # Sync riverbank.config.ts schema/config to CMS
 3. **Preview**: `riverbankcms push --dry-run` shows what would change
 4. **Push**: `riverbankcms push` applies changes to CMS
 
+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
 
 Page content lives in `content/pages/[identifier].json`. Each page has a `blocks` array containing the actual content. To edit copy:

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

@@ -25,6 +25,8 @@ All commands support these options:
 - Remote operations default to dry-run and require `--yes` to execute
 - When using `--env=both`, local runs first, then remote with the same safety rules
 
+Prefer the CLI `--env` flag over shell prefixes such as `RIVERBANK_ENV=remote riverbankcms ...`. Site `.env.local` files may define `RIVERBANK_ENV`, and command-specific `--env` is the reliable way to target local or remote CMS sync.
+
 ## Environment Variables
 
 ### Local Environment (default)
@@ -148,6 +150,15 @@ riverbankcms push --dry-run --json-diff=summary
 riverbankcms push --dry-run --json-diff=full
 ```
 
+**Agent-safe scoped push example:**
+
+```bash
+riverbankcms push pages privacy-policy --env=remote --dry-run
+riverbankcms push pages privacy-policy --env=remote --yes
+```
+
+If unrelated local files would be included by a broad scope, stage a temporary content directory containing only the intended file(s) and use `--content-dir`; see `workflows/agent-safe-sync.md`.
+
 **Options:**
 
 | Option                 | Description                                                                          |
@@ -284,6 +295,8 @@ riverbankcms push-config --config ./src/riverbank.config.ts
 
 Syncs SDK schema/config surfaces such as custom blocks, block field options/extensions, content type definitions/templates, SDK-managed site settings, and footer blocks. Pages, entries, and navigation menus are synced with explicit `riverbankcms push` scopes.
 
+If `push-config` returns template binding validation errors, treat them as schema feedback. For example, a content type `reference` field should bind to a custom block `reference` field with the same `referenceKind`, not to a plain `text` field.
+
 This syncs:
 
 - Custom blocks

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

@@ -314,6 +314,35 @@ riverbankcms push --dry-run
 riverbankcms push
 ```
 
+For agent work, prefer scoped pushes over broad pushes:
+
+```bash
+# One page
+riverbankcms push pages privacy-policy --env=remote --dry-run
+riverbankcms push pages privacy-policy --env=remote --yes
+
+# One content type or entry
+riverbankcms push entries blog-post --env=remote --dry-run
+riverbankcms push entries blog-post welcome --env=remote --dry-run
+```
+
+Use CLI `--env=local` / `--env=remote` rather than `RIVERBANK_ENV=...` shell prefixes for sync commands. Site `.env.local` files may set `RIVERBANK_ENV`, while the CLI flag explicitly selects the sync target.
+
+If local files include unrelated page or entry differences, isolate the changed files with `--content-dir`:
+
+```bash
+tmpdir=$(mktemp -d)
+mkdir -p "$tmpdir/pages"
+cp content/pages/privacy-policy.json "$tmpdir/pages/privacy-policy.json"
+
+riverbankcms push pages --content-dir "$tmpdir" --env=remote --dry-run
+riverbankcms push pages --content-dir "$tmpdir" --env=remote --yes
+
+rm -rf "$tmpdir"
+```
+
+See `workflows/agent-safe-sync.md` for the full safe-push checklist.
+
 ### Sync Configuration
 
 Configure sync behavior in `riverbank.config.ts`:
@@ -328,6 +357,8 @@ export default defineConfig({
 });
 ```
 
+`push-config` syncs schema/config surfaces such as custom blocks, block extensions/options, content type schemas/templates, SDK-managed settings, and footer blocks. It does not replace `push pages`, `push entries`, or `push navigation` for file-backed content.
+
 | Option            | Values           | Description                                  |
 | ----------------- | ---------------- | -------------------------------------------- |
 | `existingEntries` | `skip`, `update` | Whether to update entries that already exist |

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

@@ -80,6 +80,8 @@ riverbankcms push
 
 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.
 
+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.
+
 ## Key Documentation
 
 | Document                | Purpose                                                          |
@@ -90,6 +92,7 @@ If your SDK site uses `createCatchAllPage()`, you can render with local theme ob
 | `block-types.md`        | Available block types (auto-generated)                           |
 | `theme-schema.md`       | 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 |
 
 ## Common Tasks
 
@@ -136,6 +139,17 @@ riverbankcms push --env=remote --yes
 
 **Safety note:** Remote push requires `--yes` flag to prevent accidental production changes.
 
+Prefer the CLI `--env` flag over shell prefixes such as `RIVERBANK_ENV=remote riverbankcms ...`. Site `.env.local` files often contain their own `RIVERBANK_ENV` value, while `--env=remote` is explicit and reliable for CLI sync commands.
+
+For narrow production edits, dry-run and apply the smallest scope:
+
+```bash
+riverbankcms push pages privacy-policy --env=remote --dry-run
+riverbankcms push pages privacy-policy --env=remote --yes
+```
+
+If local content includes unrelated differences, see `workflows/agent-safe-sync.md` for the temporary `--content-dir` pattern.
+
 ## Media Safety (Avoid Broken Images)
 
 - Portable content JSON should store media as **identifier-only** (no `assetId` / storage paths / `src`).

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

@@ -25,6 +25,8 @@ 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.
+
 ### 2. List Existing Blocks
 
 See what blocks are already on the page:
@@ -62,7 +64,7 @@ Add a body text block:
 ```bash
 riverbankcms block upsert home intro-content \
   --kind block.body-text \
-  --data '{"content": "<p>Welcome to our site. We offer...</p>"}'
+  --data '{"body": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Welcome to our site. We offer..."}]}]}}'
 ```
 
 Add an image block:

package/dist/cli/init-docs/content/workflow-agent-safe-sync.md

@@ -0,0 +1,81 @@
+# Workflow: Agent-Safe Sync
+
+Use this workflow when an agent needs to push a narrow CMS change without overwriting unrelated dashboard edits.
+
+## Golden Rules
+
+1. Prefer the CLI `--env` flag over shell environment overrides.
+2. Dry-run the exact scope you plan to apply.
+3. Push the narrowest possible content scope.
+4. Treat stale-content warnings as evidence of unrelated remote edits.
+5. Use `push-config` for schema/config only; use `push` for pages, entries, navigation, settings, and other content files.
+
+## Environment Targeting
+
+Use the CLI environment flag:
+
+```bash
+riverbankcms pull --env=remote
+riverbankcms push pages privacy-policy --env=remote --dry-run
+riverbankcms push-config --env=remote
+```
+
+Do not rely on `RIVERBANK_ENV=remote riverbankcms ...` for CLI sync commands. Site projects often load `.env.local`, and an existing `RIVERBANK_ENV=local` value can override the shell value in config-loading paths. The CLI `--env` flag is explicit and survives project env defaults.
+
+## Narrow Page Push
+
+For a single page, push the page identifier rather than all pages:
+
+```bash
+riverbankcms push pages privacy-policy --env=remote --dry-run --force
+riverbankcms push pages privacy-policy --env=remote --yes --force
+```
+
+If you need to isolate a local file snapshot from the rest of `content/pages`, use a temporary content directory:
+
+```bash
+tmpdir=$(mktemp -d)
+mkdir -p "$tmpdir/pages"
+cp content/pages/privacy-policy.json "$tmpdir/pages/privacy-policy.json"
+
+riverbankcms push pages --content-dir "$tmpdir" --env=remote --dry-run --force
+riverbankcms push pages --content-dir "$tmpdir" --env=remote --yes --force
+
+rm -rf "$tmpdir"
+```
+
+This is useful when local content files include older or unrelated page differences that should not be pushed.
+
+## Stale Content
+
+If a push aborts because unrelated remote content is newer:
+
+- Do not blindly run a broad `push --force`.
+- Prefer pushing the exact changed page, entry, or navigation scope.
+- Use `--force` only after a dry-run confirms the planned changes are limited to the intended objects.
+- If you truly need the latest remote state, run a scoped pull first, for example `riverbankcms pull pages privacy-policy --env=remote`.
+
+## Content vs Config
+
+Use these commands for different surfaces:
+
+```bash
+# Pages, entries, navigation, settings, forms, footer content, themes
+riverbankcms push <scope> ...
+
+# Custom blocks, block extensions/options, content type schemas/templates,
+# SDK-managed settings, footer blocks/layout config
+riverbankcms push-config ...
+```
+
+`push-config` does not replace `push pages` or `push entries`; it syncs schema/config surfaces. If config validation fails, read the field errors as schema feedback before working around them in the site.
+
+## Before Applying
+
+Checklist:
+
+- [ ] I used `--env=local`, `--env=remote`, or `--env=both` explicitly.
+- [ ] I ran a dry-run for the same scope and target environment.
+- [ ] The dry-run contains only intended creates/updates/deletes.
+- [ ] I understand any stale-content warnings.
+- [ ] For remote writes, I included `--yes` only after reviewing the dry-run.

package/dist/cli/init-docs/content/workflow-create-page.md

@@ -10,6 +10,16 @@ This workflow guides you through creating a new page in the CMS.
 
 ## Steps
 
+### Before You Add Custom Blocks
+
+For simple content pages such as privacy policies, terms pages, FAQs, about copy, and editorial articles, start with built-in blocks:
+
+- `block.body-text` for long-form rich text
+- `block.hero` only when the page genuinely needs a visual/intro hero
+- `block.cta-full` or existing CTA blocks for action strips
+
+Check `block-types.md` before creating a custom block. A plain content page should usually be one `block.body-text` block with an `h1` and intro paragraph in the rich text body, not a site-specific custom block.
+
 ### 1. Create the Page
 
 ```bash
@@ -45,7 +55,7 @@ Add a body text block:
 ```bash
 riverbankcms block upsert contact intro-text \
   --kind block.body-text \
-  --data '{"content": "<p>Reach out using the form below or email us directly.</p>"}'
+  --data '{"body": {"type": "doc", "content": [{"type": "heading", "attrs": {"level": 1}, "content": [{"type": "text", "text": "Contact Us"}]}, {"type": "paragraph", "content": [{"type": "text", "text": "Reach out using the form below or email us directly."}]}]}}'
 ```
 
 Add more blocks as needed. See `block-types.md` for available block types.
@@ -159,12 +169,12 @@ riverbankcms block upsert about hero \
 # 3. Add introduction text
 riverbankcms block upsert about intro \
   --kind block.body-text \
-  --data '{"content": "<p>Founded in 2020, we have been...</p>"}'
+  --data '{"body": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Founded in 2020, we have been..."}]}]}}'
 
 # 4. Add team section (if using a team block)
 riverbankcms block upsert about team \
   --kind block.body-text \
-  --data '{"content": "<h2>Our Team</h2><p>Meet the people behind the company.</p>"}'
+  --data '{"body": {"type": "doc", "content": [{"type": "heading", "attrs": {"level": 2}, "content": [{"type": "text", "text": "Our Team"}]}, {"type": "paragraph", "content": [{"type": "text", "text": "Meet the people behind the company."}]}]}}'
 
 # 5. Verify
 riverbankcms page get about

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

@@ -4,6 +4,15 @@ Create a site-specific block with custom fields and rendering when system blocks
 
 ## 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:
+
+- `block.body-text` for policy pages, terms pages, simple articles, and editorial copy
+- `block.hero` for page intros and visual mastheads
+- `block.cta-full` / CTA blocks for call-to-action sections
+- `block.image-gallery`, `block.media-text`, and similar media/content patterns
+
+Do not create a custom block just to get “a rich text area with different spacing.” Use a built-in block and add scoped site CSS or block field extensions when that is enough.
+
 **Use custom blocks when:**
 - You need a completely unique block structure
 - The functionality doesn't map to any system block

package/dist/cli/init-docs/content/workflow-templates.md

@@ -11,8 +11,8 @@ Define default template blocks for content types that generate pages. Templates
 
 **Templates vs manual blocks:**
 - Templates define the *default* blocks for new entries
-- Editors can still modify blocks after entry creation
-- SDK always wins on sync—templates overwrite manual changes
+- Entry slots let editors add per-entry Page Content inside a shared template
+- SDK config owns the template structure; entry slot blocks belong to each entry
 
 ## Prerequisites
 
@@ -92,6 +92,97 @@ Each template block has a scope that determines how its content is sourced:
 }
 ```
 
+### Page Content Slots
+
+Use `system.entry-slot` when every entry should keep the same outer template but needs its own editable Page Content area. The slot must be template-scoped, and it only renders blocks for entries whose current template declares that slot key.
+
+```typescript
+{
+  key: 'article',
+  name: 'Article',
+  hasPages: true,
+  routePattern: '/articles/{slug}',
+  fields: [
+    { id: 'summary', type: 'text', label: 'Summary', multiline: true },
+  ],
+  template: {
+    blocks: [
+      {
+        identifier: 'article-header',
+        kind: 'block.hero',
+        scope: 'entry',
+        bindings: {
+          headline: { source: 'meta', path: 'title' },
+          subheadline: { source: 'field', path: 'summary' },
+        },
+      },
+      {
+        identifier: 'main-content',
+        kind: 'system.entry-slot',
+        scope: 'template',
+        content: {
+          slotKey: 'main',
+          label: 'Page content',
+          allowedBlocks: ['block.body-text', 'block.rich-text', 'custom.article-callout'],
+        },
+      },
+    ],
+  },
+}
+```
+
+Event templates use the same primitive. Keep native event data in event blocks, then place editorial content in the slot:
+
+```typescript
+{
+  key: 'event',
+  name: 'Event',
+  hasPages: true,
+  routePattern: '/events/{slug}',
+  template: {
+    blocks: [
+      { identifier: 'event-hero', kind: 'block.hero', scope: 'entry' },
+      { identifier: 'event-details', kind: 'block.event-details', scope: 'template' },
+      {
+        identifier: 'event-page-content',
+        kind: 'system.entry-slot',
+        scope: 'template',
+        content: {
+          slotKey: 'main',
+          label: 'Page content',
+          allowedBlocks: ['block.body-text', 'block.image-gallery', 'block.cta-full'],
+        },
+      },
+      { identifier: 'registration', kind: 'block.event-registration', scope: 'template' },
+    ],
+  },
+}
+```
+
+For entry content files, use the `blocks` object keyed by slot:
+
+```typescript
+{
+  identifier: 'gentle-essay',
+  contentType: 'article',
+  slug: 'gentle-essay',
+  data: { summary: 'A short introduction.' },
+  blocks: {
+    main: [
+      {
+        identifier: 'intro',
+        kind: 'block.body-text',
+        content: { body: 'The editable article body starts here.' },
+      },
+    ],
+  },
+}
+```
+
+If `allowedBlocks` is omitted, the slot uses the curated Page Content palette. An empty array means the slot is locked and editors cannot add blocks. Template-only system blocks such as event registration are not allowed inside slots; keep those in the outer template.
+
+Use entry fields for structured metadata that code needs to query or validate, such as retreat level, arrival time, teacher references, or event booking settings. Entry slots are for editorial page composition; extending built-in event metadata is a separate structured-data concern.
+
 **Template-scoped blocks** have fixed content:
 ```typescript
 {
@@ -119,6 +210,19 @@ Bindings map block fields to data sources. Available binding sources:
 
 **Valid meta paths:** `title`, `slug`, `publishedAt`, `createdAt`, `updatedAt`
 
+### Binding Type Compatibility
+
+Template bindings must connect compatible source and target field types. `push-config` validates this and will reject mismatches before they reach the dashboard.
+
+Common examples:
+
+- `richText` entry field -> `richText` block field
+- `media` entry field -> `media` block field
+- `reference` entry field -> `reference` block field with the same `referenceKind`
+- `text` entry field -> `text` block field
+
+Do not bind a `reference` source into a `text` target just because the renderer eventually wants an identifier string. Make the custom block field a `reference` too, then convert/normalize the rendered value in code if needed. This keeps the block schema honest and allows dashboard validation/editor UI to work correctly.
+
 ### Step 4: Push Configuration
 
 Push the template to sync it with the CMS:
@@ -274,3 +378,4 @@ When you first push a template to a content type that has existing entries:
 - Check binding keys match block field IDs
 - Verify field paths exist in content type fields
 - Ensure block kinds are valid system or custom blocks
+- Ensure source and target field types are compatible, especially `reference` fields

package/dist/client/{accordion-G34C45TW.mjs → accordion-2UZPBMYM.mjs}

@@ -1,5 +1,5 @@
-import { defineIslandPropsDecoder } from './chunk-RJHTCTCZ.mjs';
-import './chunk-S3MKFGOG.mjs';
+import { defineIslandPropsDecoder } from './chunk-VGDBVNOO.mjs';
+import './chunk-ZE5G642V.mjs';
 
 // src/rendering/islands/enhancers/accordion.ts
 var decode = defineIslandPropsDecoder("accordion");

package/dist/client/{bookingForm-BLBVKSAQ.mjs → bookingForm-DYXT6YB6.mjs}

@@ -1,16 +1,16 @@
 "use client";
-import { usePolling } from './chunk-CSZGLBYR.mjs';
-import { SpinnerNode } from './chunk-SBBSMFFG.mjs';
+import { usePolling } from './chunk-ZKUO52W3.mjs';
+import { SpinnerNode } from './chunk-SYIJ5JO2.mjs';
 import { useDiscountCodeUi } from './chunk-ZFHRN6W2.mjs';
 import { buildRouteIslandApiConfig } from './chunk-L4J5Y62O.mjs';
-import { scrollToBlock, buildCheckoutReturnUrls, DiscountCodeDisclosure, formatPrice } from './chunk-CHAB5ACD.mjs';
+import { scrollToBlock, buildCheckoutReturnUrls, DiscountCodeDisclosure, formatPrice } from './chunk-7UCLJ5SP.mjs';
 import { FieldValidationMessage, getFieldValidationControlProps } from './chunk-3DCJ45Z2.mjs';
 import './chunk-DVNUDUVT.mjs';
 import { isSpamProtectionEnabled, getChallengeUrl, AltchaWidget } from './chunk-GFSQNTRW.mjs';
 import { BlockApiProvider, useBlockApi, FeedbackMessage } from './chunk-UDNSI5PY.mjs';
 import { mountReactIsland } from './chunk-N7PBWBWQ.mjs';
-import { defineIslandPropsDecoder, resolveBookingSiteId, resolveDefaultBookingServiceId, getBookingRedirectStateFromLocation, deriveBookingFormViewState, logger, getBookingSuccessMessage, resolveAppointmentCheckoutVerificationState, themeButtonClassName, toSelectedCollectionOptionKind, assertNever11, prepareBookingSubmission, formatBookingSubmissionPreparationError, resolveBookingPaymentStep, BOOKING_FORM_DATA_RESERVED_KEYS, clearWorkflowFeedback, reportWorkflowError, reportWorkflowSuccess, okWith2, err2 } from './chunk-RJHTCTCZ.mjs';
-import { resolveBookingTimeZoneId, DEFAULT_BOOKING_TIME_ZONE, unsafeAsFormId, unsafeAsAppointmentResourceId, unsafeAsCustomerPassId, unsafeAsAppointmentServiceId, formatLocalScheduleDate, addLocalScheduleDays, parseBookingLocalDate, resolveFlexibleBalanceInitialPaymentCents, resolveFlexibleBalanceDueAt, getBookingInstalmentDepositRefundability, unsafeAsPassId, splitAmountWithRemainderInFirst, addIntervalPreservingMonthAnchor, clampConfiguredAmount, getBookingInstalmentPlanIntervalCount, omitZeroAmountFutureRows, formatBookingInstant } from './chunk-S3MKFGOG.mjs';
+import { defineIslandPropsDecoder, resolveBookingSiteId, resolveDefaultBookingServiceId, getBookingRedirectStateFromLocation, deriveBookingFormViewState, logger, getBookingSuccessMessage, resolveAppointmentCheckoutVerificationState, themeButtonClassName, toSelectedCollectionOptionKind, assertNever11, prepareBookingSubmission, formatBookingSubmissionPreparationError, resolveBookingPaymentStep, BOOKING_FORM_DATA_RESERVED_KEYS, clearWorkflowFeedback, reportWorkflowError, reportWorkflowSuccess, okWith2, err2 } from './chunk-VGDBVNOO.mjs';
+import { resolveBookingTimeZoneId, DEFAULT_BOOKING_TIME_ZONE, unsafeAsFormId, unsafeAsAppointmentResourceId, unsafeAsCustomerPassId, unsafeAsAppointmentServiceId, formatLocalScheduleDate, addLocalScheduleDays, parseBookingLocalDate, resolveFlexibleBalanceInitialPaymentCents, resolveFlexibleBalanceDueAt, getBookingInstalmentDepositRefundability, unsafeAsPassId, splitAmountWithRemainderInFirst, addIntervalPreservingMonthAnchor, clampConfiguredAmount, getBookingInstalmentPlanIntervalCount, omitZeroAmountFutureRows, formatBookingInstant } from './chunk-ZE5G642V.mjs';
 import React2, { useRef, useState, useMemo, useReducer, useEffect, useCallback, useLayoutEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';