@riverbankcms/sdk 0.84.0 → 0.84.2

package/dist/cli/index.mjs

@@ -110,6 +110,30 @@ var init_collections = __esm({
 });
 
 // ../core/src/event-pricing.ts
+function publicEventPricingType(pricing) {
+  switch (pricing.kind) {
+    case "drop_in":
+    case "free_registration":
+      return "free";
+    case "single_paid":
+    case "ticket_types":
+    case "course":
+      return isFreePublicEventPriceDisplay(pricing.display) ? "free" : "paid";
+  }
+}
+function isFreePublicEventPriceDisplay(display) {
+  switch (display.kind) {
+    case "free":
+      return true;
+    case "course":
+      return display.display.kind === "free";
+    case "exact":
+    case "from":
+    case "mixed":
+    case "unavailable":
+      return false;
+  }
+}
 var init_event_pricing = __esm({
   "../core/src/event-pricing.ts"() {
   }
@@ -140,8 +164,139 @@ var init_booking_instalments = __esm({
 });
 
 // ../core/src/booking-date-time.ts
+function isValidTimeZone(timeZone) {
+  try {
+    new Intl.DateTimeFormat(DEFAULT_LOCALE, { timeZone }).format(/* @__PURE__ */ new Date());
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getSafeTimeZone(timeZone) {
+  const normalized = typeof timeZone === "string" ? timeZone.trim() : "";
+  return normalized && isValidTimeZone(normalized) ? normalized : FALLBACK_TIMEZONE;
+}
+function parseStrictBookingTimeZone(timeZone) {
+  const normalized = timeZone.trim();
+  if (!normalized || !isValidTimeZone(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+function formatParseError(error) {
+  switch (error.reason) {
+    case "invalid_starts_at":
+      return `Expected a valid UTC/offset-aware ISO datetime in startsAt, received "${error.value}"`;
+    case "invalid_ends_at":
+      return `Expected a valid UTC/offset-aware ISO datetime in endsAt, received "${error.value ?? ""}"`;
+    case "invalid_time_zone":
+      return `Expected a valid IANA timezone in timeZone, received "${error.value}"`;
+  }
+}
+function formatToPartsLookup(date, locale, timeZone, format) {
+  return new Map(
+    new Intl.DateTimeFormat(locale, {
+      ...format,
+      timeZone
+    }).formatToParts(date).map((part) => [part.type, part.value])
+  );
+}
+function getZonedDateTimeParts(date, timeZone) {
+  const parts = formatToPartsLookup(date, "en-GB", timeZone, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const read = (type) => Number(parts.get(type) ?? "");
+  return {
+    year: read("year"),
+    month: read("month"),
+    day: read("day"),
+    hour: read("hour"),
+    minute: read("minute"),
+    second: read("second")
+  };
+}
+function formatDateKey(date) {
+  const year = String(date.year).padStart(4, "0");
+  const month = String(date.month).padStart(2, "0");
+  const day = String(date.day).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function parseUtcIsoDateTimeString(value) {
+  const normalized = value.trim();
+  const hasUtcSuffix = normalized.endsWith("Z");
+  const hasExplicitOffset = /[+-]\d{2}:\d{2}$/u.test(normalized);
+  if (!hasUtcSuffix && !hasExplicitOffset) {
+    return err("missing-timezone-offset");
+  }
+  const date = new Date(normalized);
+  if (Number.isNaN(date.getTime())) {
+    return err("invalid-date-time");
+  }
+  return ok(date.toISOString());
+}
+function toUtcIsoDateTimeString(value) {
+  const parsed = parseUtcIsoDateTimeString(value);
+  if (!parsed.ok) {
+    const message = parsed.error === "missing-timezone-offset" ? `Expected an offset-aware ISO datetime, received "${value}"` : `Expected a valid ISO datetime, received "${value}"`;
+    throw new Error(message);
+  }
+  return parsed.value;
+}
+function parseScheduledBookingDateTime(input) {
+  try {
+    const startsAt = toUtcIsoDateTimeString(input.startsAt);
+    const timeZone = parseStrictBookingTimeZone(input.timeZone);
+    if (!timeZone) {
+      return {
+        ok: false,
+        field: "timeZone",
+        reason: "invalid_time_zone",
+        value: input.timeZone
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        startsAt,
+        timeZone,
+        locale: input.locale
+      }
+    };
+  } catch {
+    return {
+      ok: false,
+      field: "startsAt",
+      reason: "invalid_starts_at",
+      value: input.startsAt
+    };
+  }
+}
+function toScheduledBookingDateTime(input) {
+  const result = parseScheduledBookingDateTime(input);
+  if (result.ok) {
+    return result.value;
+  }
+  throw new Error(formatParseError(result));
+}
+function getBookingLocalDateKey(input) {
+  return formatDateKey(getLocalScheduleDate(new Date(input.startsAt), input.timeZone));
+}
+function getLocalScheduleDate(date, timeZone) {
+  const parts = getZonedDateTimeParts(date, getSafeTimeZone(timeZone));
+  return { year: parts.year, month: parts.month, day: parts.day };
+}
+var DEFAULT_LOCALE, FALLBACK_TIMEZONE;
 var init_booking_date_time = __esm({
   "../core/src/booking-date-time.ts"() {
+    init_result();
+    DEFAULT_LOCALE = "en-US";
+    FALLBACK_TIMEZONE = "UTC";
   }
 });
 
@@ -18912,6 +19067,31 @@ var init_event_registration_shared = __esm({
   }
 });
 
+// ../blocks/src/system/constants/events.ts
+function isEventCalendarDisplayMode(value) {
+  return typeof value === "string" && eventCalendarDisplayModeValues.includes(value);
+}
+function isEventCalendarListLayout(value) {
+  return typeof value === "string" && eventCalendarListLayoutValues.includes(value);
+}
+function isEventContentType(slug) {
+  if (!slug) return false;
+  return EVENT_CONTENT_TYPE_SLUGS.includes(slug);
+}
+var EVENT_CONTENT_TYPE_SLUGS, eventCalendarDisplayModeValues, eventCalendarListLayoutValues, eventCalendarListLayoutOptions;
+var init_events = __esm({
+  "../blocks/src/system/constants/events.ts"() {
+    EVENT_CONTENT_TYPE_SLUGS = ["event", "events"];
+    eventCalendarDisplayModeValues = ["combined", "month", "week", "list", "timetable"];
+    eventCalendarListLayoutValues = ["stack", "grid", "compact"];
+    eventCalendarListLayoutOptions = [
+      { id: "stack", label: "Stack" },
+      { id: "grid", label: "Grid" },
+      { id: "compact", label: "Compact" }
+    ];
+  }
+});
+
 // ../blocks/src/system/runtime/nodes/events/shared/pricing.ts
 function resolveRuntimeEventPricing(event) {
   if (isPublicEventPricing(event.pricing)) {
@@ -19036,26 +19216,6 @@ var init_pricing = __esm({
     DEFAULT_EVENT_CURRENCY = "USD";
   }
 });
-
-// ../blocks/src/system/constants/events.ts
-function isEventCalendarDisplayMode(value) {
-  return typeof value === "string" && eventCalendarDisplayModeValues.includes(value);
-}
-function isEventCalendarListLayout(value) {
-  return typeof value === "string" && eventCalendarListLayoutValues.includes(value);
-}
-var eventCalendarDisplayModeValues, eventCalendarListLayoutValues, eventCalendarListLayoutOptions;
-var init_events = __esm({
-  "../blocks/src/system/constants/events.ts"() {
-    eventCalendarDisplayModeValues = ["combined", "month", "week", "list", "timetable"];
-    eventCalendarListLayoutValues = ["stack", "grid", "compact"];
-    eventCalendarListLayoutOptions = [
-      { id: "stack", label: "Stack" },
-      { id: "grid", label: "Grid" },
-      { id: "compact", label: "Compact" }
-    ];
-  }
-});
 var previewStageSchema, registrationButtonVariantSchema, eventButtonVariantSchema, eventLayoutSchema, eventCalendarDisplayModeSchema, columnOptionSchema, weekStartSchema, filterAutoShowSchema, calendarTabViewsSchema;
 var init_contract_schemas = __esm({
   "../blocks/src/system/runtime/nodes/shared/contract-schemas.ts"() {
@@ -19071,17 +19231,148 @@ var init_contract_schemas = __esm({
     calendarTabViewsSchema = z.enum(["both", "month", "week"]);
   }
 });
+
+// ../blocks/src/system/runtime/nodes/event-registration/wizardSteps.ts
+function getWizardStepsForContext(hasPreSelectedContext, needsPaymentStep) {
+  const baseSteps = hasPreSelectedContext ? ["select-tickets", "enter-details"] : ["select-event", "select-tickets", "enter-details"];
+  if (!needsPaymentStep) {
+    return baseSteps;
+  }
+  return [...baseSteps, "select-payment"];
+}
+var init_wizardSteps = __esm({
+  "../blocks/src/system/runtime/nodes/event-registration/wizardSteps.ts"() {
+  }
+});
+
+// ../blocks/src/system/runtime/nodes/event-registration/registrationDerivations.ts
+function eventMatchesOccurrenceId(event, occurrenceId) {
+  return event.registrationOccurrenceId === occurrenceId || event.publicEventId === occurrenceId;
+}
+function findPreSelectedEvent(input) {
+  const occurrenceContext = input.occurrenceContext;
+  if (!occurrenceContext) {
+    return null;
+  }
+  const contextDate = getBookingLocalDateKey(toScheduledBookingDateTime({
+    startsAt: occurrenceContext.startsAt,
+    timeZone: occurrenceContext.timeZone
+  }));
+  return input.scopedEvents.find(
+    (event) => eventMatchesOccurrenceId(event, occurrenceContext.id) || getBookingLocalDateKey(toScheduledBookingDateTime({
+      startsAt: event.startsAt,
+      timeZone: event.timeZone
+    })) === contextDate
+  ) ?? null;
+}
+function resolveEventRequiresPayment(input) {
+  if (input.eligibility) {
+    return input.eligibility.requiresPayment;
+  }
+  if (!input.event) {
+    return false;
+  }
+  return publicEventPricingType(resolveRuntimeEventPricing(input.event)) !== "free";
+}
+var init_registrationDerivations = __esm({
+  "../blocks/src/system/runtime/nodes/event-registration/registrationDerivations.ts"() {
+    init_src();
+    init_pricing();
+  }
+});
+
+// ../blocks/src/system/runtime/nodes/event-registration/registrationEventAdapter.ts
+function toRegistrationEvent(event) {
+  return {
+    ...event,
+    pricing: resolveRuntimeEventPricing(event),
+    publicEventId: event.id,
+    registrationOccurrenceId: event.occurrenceId
+  };
+}
+function toRegistrationEvents(events) {
+  return events.map(toRegistrationEvent);
+}
+var init_registrationEventAdapter = __esm({
+  "../blocks/src/system/runtime/nodes/event-registration/registrationEventAdapter.ts"() {
+    init_pricing();
+  }
+});
 function buildEventRegistrationDisplay(source) {
+  const stepLabels = buildEventRegistrationShellStepLabels(source);
   return {
     kind: "event-registration",
     state: "generic-shell",
     className: source.className ?? null,
     titleText: "Event registration",
-    bodyText: "Preparing dates, tickets, and booking details.",
-    stepLabels: EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS,
+    bodyText: buildEventRegistrationShellBodyText(stepLabels),
+    stepLabels,
     summaryButtonText: source.buttonText?.trim() || "Register"
   };
 }
+function buildEventRegistrationShellStepLabels(source) {
+  const scopedEvents = scopeEventRegistrationEvents(source);
+  if (scopedEvents.length === 0) {
+    return EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS;
+  }
+  const preSelectedEvent = findPreSelectedEvent({
+    scopedEvents,
+    occurrenceContext: source.occurrenceContext
+  });
+  const hasPreSelectedContext = Boolean(source.occurrenceContext || preSelectedEvent);
+  const needsPaymentStep = hasPreSelectedContext && preSelectedEvent ? resolveEventRequiresPayment({
+    eligibility: null,
+    event: preSelectedEvent
+  }) : false;
+  return getWizardStepsForContext(hasPreSelectedContext, needsPaymentStep).map((step) => shellLabelForRegistrationStep(step, scopedEvents));
+}
+function scopeEventRegistrationEvents(source) {
+  const events = toRegistrationEvents(source.events ?? []);
+  if (source.occurrenceContext?.seriesId) {
+    return events.filter((event) => event.seriesId === source.occurrenceContext?.seriesId);
+  }
+  const entrySlug = source.contentEntry?.slug;
+  const entryContentType = source.contentEntry?.contentTypeSlug;
+  if (entrySlug && entryContentType && isEventContentType(entryContentType)) {
+    return events.filter((event) => event.slug === entrySlug);
+  }
+  return events;
+}
+function shellLabelForRegistrationStep(step, events) {
+  switch (step) {
+    case "select-event":
+      return isDateSelection(events) ? "Date" : "Event";
+    case "select-tickets":
+      return "Tickets";
+    case "enter-details":
+      return "Details";
+    case "select-payment":
+      return "Payment";
+    case "error":
+    case "success":
+    case "submitting":
+    case "redirecting":
+    case "verifying-payment":
+    case "verifying-timeout":
+    case "payment-failed":
+      return "Details";
+  }
+}
+function isDateSelection(events) {
+  const firstSeriesId = events[0]?.seriesId;
+  return Boolean(
+    events.length > 1 && firstSeriesId && events.every((event) => event.seriesId === firstSeriesId)
+  );
+}
+function buildEventRegistrationShellBodyText(stepLabels) {
+  if (stepLabels.includes("Payment")) {
+    return "Preparing tickets, details, and payment options.";
+  }
+  if (stepLabels[0] === "Tickets") {
+    return "Preparing tickets and booking details.";
+  }
+  return "Preparing dates, tickets, and booking details.";
+}
 function normalizeEventRegistrationEventInput(value) {
   if (!isRecord5(value)) {
     return value;
@@ -19094,21 +19385,21 @@ function normalizeEventRegistrationEventInput(value) {
 function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS, eventRegistrationGenericDateStepLabel, eventRegistrationGenericTicketsStepLabel, eventRegistrationGenericDetailsStepLabel, contentEntrySchema, eventRegistrationPublicEventSchema, eventRegistrationSourceSchema, eventRegistrationDisplaySchema, eventRegistrationHydrationSchema, eventRegistrationRenderSchema, eventRegistrationBlockRuntime;
+var EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS, EVENT_REGISTRATION_SHELL_STEP_LABELS, contentEntrySchema, eventRegistrationPublicEventSchema, eventRegistrationSourceSchema, eventRegistrationDisplaySchema, eventRegistrationHydrationSchema, eventRegistrationRenderSchema, eventRegistrationBlockRuntime;
 var init_event_registration_interactive = __esm({
   "../blocks/src/system/runtime/nodes/event-registration.interactive.ts"() {
     init_schemas2();
     init_event_registration_shared();
+    init_events();
     init_pricing();
     init_islands();
     init_runtime();
     init_contract_schemas();
+    init_wizardSteps();
+    init_registrationDerivations();
+    init_registrationEventAdapter();
     EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS = ["Date", "Tickets", "Details"];
-    [
-      eventRegistrationGenericDateStepLabel,
-      eventRegistrationGenericTicketsStepLabel,
-      eventRegistrationGenericDetailsStepLabel
-    ] = EVENT_REGISTRATION_GENERIC_SHELL_STEP_LABELS;
+    EVENT_REGISTRATION_SHELL_STEP_LABELS = ["Event", "Date", "Tickets", "Details", "Payment"];
     contentEntrySchema = z.object({
       id: z.string(),
       slug: z.string(),
@@ -19144,11 +19435,7 @@ var init_event_registration_interactive = __esm({
       className: z.string().nullable(),
       titleText: z.string(),
       bodyText: z.string(),
-      stepLabels: z.tuple([
-        z.literal(eventRegistrationGenericDateStepLabel),
-        z.literal(eventRegistrationGenericTicketsStepLabel),
-        z.literal(eventRegistrationGenericDetailsStepLabel)
-      ]),
+      stepLabels: z.array(z.enum(EVENT_REGISTRATION_SHELL_STEP_LABELS)).min(1),
       summaryButtonText: z.string()
     });
     eventRegistrationHydrationSchema = z.object({
@@ -41926,17 +42213,21 @@ function looksLikeLocalAuthority(authority) {
   const normalized = authority.toLowerCase();
   return normalized === "localhost" || normalized.startsWith("localhost:") || normalized.startsWith("127.") || normalized.startsWith("0.0.0.0") || normalized.includes(".localhost") || normalized.endsWith(".local") || normalized.endsWith(".test");
 }
-function normalizeDashboardUrlBase(input) {
+function normalizeDashboardOrigin(input) {
   const trimmed = input.trim();
   if (!trimmed) return "";
   const withoutTrailingSlash = trimmed.replace(/\/+$/, "");
   const withoutApiSuffix = withoutTrailingSlash.replace(/\/api\/?$/, "");
   if (/^https?:\/\//i.test(withoutApiSuffix)) {
-    return withoutApiSuffix;
+    return new URL(withoutApiSuffix).origin;
   }
   const authority = withoutApiSuffix.replace(/^\/+/, "");
   const protocol = looksLikeLocalAuthority(authority) ? "http" : "https";
-  return `${protocol}://${authority}`;
+  return new URL(`${protocol}://${authority}`).origin;
+}
+function deriveCmsApiUrlFromDashboardUrl(input) {
+  const origin = normalizeDashboardOrigin(input);
+  return origin ? `${origin}/api` : "";
 }
 function getCmsApiUrl() {
   if (typeof window !== "undefined") {
@@ -41948,15 +42239,10 @@ function getCmsApiUrl() {
   }
   const dashboardUrl = process.env.NEXT_PUBLIC_DASHBOARD_URL;
   if (dashboardUrl) {
-    const base = normalizeDashboardUrlBase(dashboardUrl);
-    return `${base}/api`;
-  }
-  const legacyApiUrl = process.env.NEXT_PUBLIC_CMS_API_URL;
-  if (legacyApiUrl) {
-    return legacyApiUrl.replace(/\/$/, "");
+    return deriveCmsApiUrlFromDashboardUrl(dashboardUrl);
   }
   throw new Error(
-    "NEXT_PUBLIC_DASHBOARD_URL is not configured. Set it to your dashboard URL (e.g., http://localhost:4000)"
+    "CMS_API_URL or NEXT_PUBLIC_DASHBOARD_URL is not configured. Set NEXT_PUBLIC_DASHBOARD_URL to your dashboard URL (e.g., http://localhost:4000)"
   );
 }
 function resolveApiBaseUrl() {
@@ -63780,7 +64066,8 @@ async function initDocs(options) {
     { filename: "cmsify-page.md", template: "workflow-cmsify-page" },
     { filename: "editor-workflows.md", template: "workflow-editor-workflows" },
     { filename: "preview-mode.md", template: "workflow-preview-mode" },
-    { filename: "isr-revalidation.md", template: "workflow-isr-revalidation" }
+    { filename: "isr-revalidation.md", template: "workflow-isr-revalidation" },
+    { filename: "agent-safe-sync.md", template: "workflow-agent-safe-sync" }
   ];
   await Promise.all(
     coreWorkflows.map(
@@ -64108,7 +64395,7 @@ var SimpleCache = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.84.0";
+var SDK_VERSION = "0.84.2";
 
 // src/client/error.ts
 var RiverbankApiError = class _RiverbankApiError extends Error {

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

@@ -92,6 +92,7 @@ Event registration blocks need both the SDK base stylesheet and a runtime theme
 | `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
 
@@ -138,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: