@riverbankcms/sdk 0.129.0 → 0.130.0

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

@@ -1,285 +0,0 @@
-# Workflow: Publish Content
-
-This workflow guides you through safely publishing content to make it live.
-
-## Understanding Draft vs Published
-
-| Status | Behavior |
-|--------|----------|
-| **Draft** | Content is saved but not visible on the live site. Only visible in preview mode. |
-| **Published** | Content is visible to all site visitors. |
-
-By default, new content is created as a draft.
-
-## Publishing Individual Items
-
-### Publish an Entry
-
-```bash
-riverbankcms entry publish <content-type> <identifier>
-```
-
-**Example:**
-
-```bash
-riverbankcms entry publish blog-post my-first-post
-```
-
-### Publish a Page
-
-```bash
-riverbankcms page publish <identifier>
-```
-
-**Example:**
-
-```bash
-riverbankcms page publish about
-```
-
-## Checking Publication Status
-
-### Check Entry Status
-
-```bash
-riverbankcms entry get <content-type> <identifier>
-```
-
-Look for:
-- `status: "published"` or `status: "draft"`
-- `hasUnpublishedChanges: true/false`
-
-### Check Page Status
-
-```bash
-riverbankcms page get <identifier>
-```
-
-### List All with Status (JSON)
-
-Under `--json` every command emits one envelope `{ ok, command, result, warnings, errors }`, so reach into `.result` when parsing with jq.
-
-```bash
-# List entries with status
-riverbankcms entry list blog-post --json
-
-# Filter to see status fields (requires jq)
-riverbankcms entry list blog-post --json | jq '.result.entries[] | {identifier, status, hasUnpublishedChanges}'
-
-# List pages with status
-riverbankcms page list --json
-```
-
-To see everything with pending changes across all content types in one shot — correctly server-filtered, not capped by pagination — use `riverbankcms drafts` instead of scanning `entry list` page by page.
-
-## Bulk Publishing via Push
-
-When using `riverbankcms push`, the status is synced based on your local content files.
-
-### How Status Sync Works
-
-Push compares the `status` field in your local files to the remote status:
-- If local is "published" and remote is "draft" → push will **publish** the content
-- If local is "draft" and remote is "published" → push will **unpublish** the content
-- If statuses match → no status change
-
-### Edit Local Files to Control Status
-
-In your local content files, set the status field:
-
-```json
-{
-  "identifier": "my-post",
-  "status": "published",
-  "data": { "title": "My Post" }
-}
-```
-
-Then push:
-
-```bash
-riverbankcms push
-```
-
-### Push Then Publish Selectively
-
-```bash
-# Push as drafts (default behavior)
-riverbankcms push
-
-# Then publish specific items
-riverbankcms entry publish blog-post featured-post
-riverbankcms page publish landing-page
-```
-
-## Unpublishing Content
-
-### Unpublish an Entry
-
-```bash
-riverbankcms entry unpublish <content-type> <identifier>
-```
-
-**Example:**
-
-```bash
-riverbankcms entry unpublish blog-post old-post
-```
-
-### Unpublish a Page
-
-```bash
-riverbankcms page unpublish <identifier>
-```
-
-**Example:**
-
-```bash
-riverbankcms page unpublish outdated-landing
-```
-
-Unpublishing reverts content to draft status. The content is preserved but no longer visible on the live site.
-
-## Safe Publishing Workflow
-
-Follow these steps to safely publish content:
-
-### 1. Pull Latest Content
-
-Ensure you're working with the current state:
-
-```bash
-riverbankcms pull
-```
-
-### 2. Make and Verify Changes
-
-```bash
-# Make changes via CLI or edit local files
-riverbankcms entry upsert blog-post my-post --data '...'
-
-# Or edit content/entries/blog-post.json
-```
-
-### 3. Preview Changes
-
-```bash
-# Preview what would be pushed
-riverbankcms push --dry-run
-
-# Preview specific blocks visually
-riverbankcms preview block.hero --data '...' --open
-```
-
-### 4. Push Changes (as Draft)
-
-```bash
-riverbankcms push
-```
-
-### 5. Verify in CMS Dashboard
-
-- Log into the dashboard
-- Review the content in preview mode
-- Check formatting, images, links
-
-### 6. Publish
-
-```bash
-riverbankcms entry publish blog-post my-post
-# or
-riverbankcms page publish my-page
-```
-
-### 7. Verify Live
-
-- Check the live site
-- Confirm content appears correctly
-- Test any links or interactive elements
-
-## Handling Unpublished Changes
-
-When you edit published content, it stays published but gains pending changes.
-
-### Check for Pending Changes
-
-```bash
-riverbankcms entry get blog-post my-post --json | grep hasUnpublishedChanges
-```
-
-- `hasUnpublishedChanges: true` - There are edits not yet live
-- `hasUnpublishedChanges: false` - Live version is current
-
-### Apply Pending Changes
-
-Re-publish to make pending changes live:
-
-```bash
-riverbankcms entry publish blog-post my-post
-```
-
-### Discard Pending Changes
-
-To revert to the published version, you would need to:
-
-1. Pull the published content: `riverbankcms pull`
-2. The local files will have the current (modified) state
-3. Manually revert in the dashboard or re-push the original content
-
-## Publishing to Production
-
-For production environments, use `--env=remote`:
-
-```bash
-# Pull from production
-riverbankcms pull --env=remote
-
-# Preview production push
-riverbankcms push --env=remote --dry-run
-
-# Push to production (requires --yes for safety)
-riverbankcms push --env=remote --yes
-
-# Publish specific content on production
-riverbankcms entry publish blog-post my-post --env=remote
-riverbankcms page publish landing --env=remote
-```
-
-**Safety notes:**
-- `--env=remote` targets production environment
-- Push to remote requires `--yes` flag to prevent accidents
-- Always preview with `--dry-run` first
-
-## Publishing Checklist
-
-Before publishing content, verify:
-
-- [ ] Content is accurate and complete
-- [ ] Images load correctly
-- [ ] Links work (internal and external)
-- [ ] SEO metadata is set (title, description)
-- [ ] Mobile layout looks good (if applicable)
-- [ ] No placeholder or test content remains
-- [ ] Spell check / grammar check completed
-
-## Troubleshooting
-
-### Content not appearing on live site
-
-1. Check if published: `riverbankcms entry get <type> <identifier>`
-2. Look for `status: "published"`
-3. If draft, publish it: `riverbankcms entry publish <type> <identifier>`
-4. Check for caching - may need to wait or clear cache
-
-### Published but showing old content
-
-1. Check for pending changes: `hasUnpublishedChanges: true`
-2. Re-publish to apply changes: `riverbankcms entry publish <type> <identifier>`
-3. Clear any CDN or browser cache
-
-### Can't publish - validation error
-
-1. Check required fields are filled
-2. Review the error message for specifics
-3. Get full entry data: `riverbankcms entry get <type> <identifier> --json`
-4. Fix missing/invalid fields and retry

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

@@ -1,51 +0,0 @@
-# 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.
-
-## Check the Plan
-
-Run the setup planner before copying secrets or pushing to production:
-
-```bash
-riverbankcms setup plan --env=remote
-```
-
-For a machine-readable checklist:
-
-```bash
-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.
-
-Do not put platform-admin, service-role, or user-session credentials in an SDK site repository.
-
-## 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`:
-
-```bash
-RIVERBANK_REMOTE_SITE_ID=your-site-id
-RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.example.com
-RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
-RIVERBANK_REMOTE_API_KEY=bld_live_sk_... # optional for public content fetching/deploy
-```
-
-5. Verify the SDK can reach the site:
-
-```bash
-riverbankcms env status --env=remote
-riverbankcms pull --env=remote --dry-run
-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 SDK CLI.

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

@@ -1,381 +0,0 @@
-# Workflow: Content Type Templates
-
-Define default template blocks for content types that generate pages. Templates allow you to specify which blocks appear on entry pages and how entry data maps to block fields.
-
-## When to Use Templates
-
-**Use templates for:**
-- Content types with `hasPages: true` that need consistent page layouts
-- Automating block setup for new entries
-- Binding entry data to block fields (e.g., headline from title)
-
-**Templates vs manual blocks:**
-- Templates define the *default* blocks for new entries
-- 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
-
-- `riverbank.config.ts` with content types defined
-- Understanding of which blocks to use
-- Knowledge of content type fields for bindings
-
-## Steps
-
-### Step 1: Add Template to Content Type
-
-Add the `template` property to your content type:
-
-```typescript
-import { defineConfig } from '@riverbankcms/sdk/config';
-
-export default defineConfig({
-  siteId: '...',
-
-  content: {
-    contentTypes: [
-      {
-        key: 'post',
-        name: 'Blog Post',
-        hasPages: true,
-        routePattern: '/blog/{slug}',
-        fields: [
-          { id: 'excerpt', type: 'text', label: 'Excerpt', multiline: true },
-          { id: 'image', type: 'media', label: 'Featured Image', mediaKinds: ['image'] },
-          { id: 'body', type: 'richText', label: 'Content', required: true },
-        ],
-        template: {
-          blocks: [
-            {
-              identifier: 'hero',
-              kind: 'block.hero',
-              scope: 'entry',
-              bindings: {
-                headline: { source: 'meta', path: 'title' },
-                backgroundImage: { source: 'field', path: 'image' },
-              },
-            },
-            {
-              identifier: 'body',
-              kind: 'block.body-text',
-              scope: 'entry',
-              bindings: {
-                body: { source: 'field', path: 'body' },
-              },
-            },
-          ],
-        },
-      },
-    ],
-  },
-});
-```
-
-### Step 2: Choose Block Scope
-
-Each template block has a scope that determines how its content is sourced:
-
-| Scope | Description |
-|-------|-------------|
-| `entry` | Block content is bound to entry data via bindings |
-| `template` | Block content is static, defined in the template |
-
-**Entry-scoped blocks** pull data from the content entry:
-```typescript
-{
-  identifier: 'hero',
-  kind: 'block.hero',
-  scope: 'entry',
-  bindings: {
-    headline: { source: 'meta', path: 'title' },
-  },
-}
-```
-
-### 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
-{
-  identifier: 'related-posts',
-  kind: 'block.blog-listing',
-  scope: 'template',
-  content: {
-    heading: 'Related Posts',
-    layout: 'grid',
-  },
-}
-```
-
-### Step 3: Configure Bindings
-
-Bindings map block fields to data sources. Available binding sources:
-
-| Source | Description | Example |
-|--------|-------------|---------|
-| `field` | Entry field value | `{ source: 'field', path: 'image' }` |
-| `meta` | Entry metadata | `{ source: 'meta', path: 'title' }` |
-| `literal` | Static value | `{ source: 'literal', value: 'Welcome!' }` |
-| `transform` | Transformed field value | `{ source: 'transform', path: 'body', transform: 'richtext.firstParagraph' }` |
-| `fallback` | Try sources in order | `{ source: 'fallback', 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:
-
-```bash
-riverbankcms push-config
-```
-
-### Step 5: Verify Template
-
-1. Create a new entry for the content type
-2. The entry page should have the template blocks
-3. Entry data should appear in bound block fields
-
-## Complete Example
-
-Blog with hero, body, and related posts:
-
-```typescript
-{
-  key: 'post',
-  name: 'Blog Post',
-  hasPages: true,
-  routePattern: '/blog/{slug}',
-  fields: [
-    { id: 'excerpt', type: 'text', label: 'Excerpt', multiline: true },
-    { id: 'image', type: 'media', label: 'Featured Image', mediaKinds: ['image'] },
-    { id: 'body', type: 'richText', label: 'Content', required: true },
-    { id: 'category', type: 'text', label: 'Category' },
-  ],
-  template: {
-    blocks: [
-      // Hero bound to entry data
-      {
-        identifier: 'hero',
-        kind: 'block.hero',
-        scope: 'entry',
-        bindings: {
-          headline: { source: 'meta', path: 'title' },
-          subheadline: { source: 'field', path: 'excerpt' },
-          backgroundImage: { source: 'field', path: 'image' },
-        },
-      },
-      // Body text bound to entry content
-      {
-        identifier: 'body',
-        kind: 'block.body-text',
-        scope: 'entry',
-        bindings: {
-          body: { source: 'field', path: 'body' },
-        },
-      },
-      // Static related posts section
-      {
-        identifier: 'related',
-        kind: 'block.blog-listing',
-        scope: 'template',
-        content: {
-          heading: 'More Posts',
-          layout: 'grid',
-          limit: 3,
-        },
-      },
-    ],
-  },
-}
-```
-
-## Binding Patterns
-
-### Using Fallback Bindings
-
-Try multiple sources in order:
-
-```typescript
-{
-  identifier: 'hero',
-  kind: 'block.hero',
-  scope: 'entry',
-  bindings: {
-    backgroundImage: {
-      source: 'fallback',
-      sources: [
-        { source: 'field', path: 'heroImage' },
-        { source: 'field', path: 'image' },
-        { source: 'literal', value: { src: '/default-hero.jpg' } },
-      ],
-    },
-  },
-}
-```
-
-### Mixing Scopes
-
-Use entry bindings with literal defaults:
-
-```typescript
-{
-  identifier: 'hero',
-  kind: 'block.hero',
-  scope: 'entry',
-  bindings: {
-    headline: { source: 'meta', path: 'title' },
-    eyebrow: { source: 'literal', value: 'Blog Post' },
-    ctas: {
-      source: 'literal',
-      value: [{ label: 'Back to Blog', link: { kind: 'internal', path: '/blog' } }],
-    },
-  },
-}
-```
-
-## First Sync Behavior
-
-When you first push a template to a content type that has existing entries:
-
-1. **Existing CMS blocks are replaced** with SDK-defined blocks
-2. This only happens on the *first* SDK sync for that template
-3. Subsequent syncs update SDK blocks by identifier
-
-## Sync Rules
-
-| Scenario | Behavior |
-|----------|----------|
-| First SDK sync | Replaces all existing CMS blocks |
-| New block in config | Created with `sdk_identifier` |
-| Block identifier matches | Block is updated |
-| Block removed from config | SDK block is soft-deleted |
-| Non-SDK blocks | Preserved (not deleted) |
-
-## Troubleshooting
-
-### Blocks not appearing on entry pages
-
-- Run `riverbankcms push-config` to sync
-- Verify content type has `hasPages: true`
-- Check that `identifier` is unique within the template
-
-### Binding not working
-
-- Verify `path` matches a field ID in your content type
-- For meta bindings, use valid paths: `title`, `slug`, `publishedAt`, `createdAt`, `updatedAt`
-- Check block manifest supports the binding key
-
-### Template changes not reflecting
-
-- SDK always wins—changes are applied on every push
-- Run `riverbankcms push-config` after config changes
-- Clear any browser/CDN caches
-
-### Validation errors on push
-
-- 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