@riverbankcms/sdk 0.128.0 → 0.129.1

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

@@ -1,299 +0,0 @@
-# Workflow: Add a Block
-
-This workflow guides you through adding a block to an existing page.
-
-## Prerequisites
-
-- Page already exists in the CMS
-- Latest content pulled: `riverbankcms pull`
-
-## Steps
-
-### 1. Check Available Block Types
-
-View built-in blocks in `block-types.md`. Common block kinds:
-
-| Kind | Description |
-|------|-------------|
-| `block.hero` | Hero sections with heading, subheading, image, CTA |
-| `block.body-text` | Rich text content |
-| `block.image` | Image with caption |
-| `block.cta` | Call-to-action buttons |
-| `block.embed` | Embedded content (videos, iframes) |
-| `block.image-gallery` | Image gallery (grid/carousel/masonry/marquee variants) |
-| `block.quote` | Blockquote with attribution |
-
-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:
-
-```bash
-riverbankcms block list <page-identifier>
-```
-
-**Example:**
-
-```bash
-riverbankcms block list home
-```
-
-### 3. Add the Block
-
-**Basic usage:**
-
-```bash
-riverbankcms block upsert <page-id> <block-id> --kind <block-kind> --data '<json>'
-```
-
-### Authoring Block JSON
-
-Use `block-types.md` and `block-types-site.md` as the source of truth for fields.
-
-- Fields marked `required` must be present with a valid value.
-- Fields not marked `required` may be omitted. You do not need to include every optional key or set unused optional values to `null`.
-- Defaults shown in the block reference are applied by the editor/rendering contract. Include an optional field only when you want to override that default.
-- For nested objects and repeaters, required child fields apply once you include the parent value. For example, an omitted `images` repeater is valid, but `images: [{}]` is not because the item is present and its required `image` field is missing.
-- `null` is only valid for field types that explicitly accept clearing to no value. When in doubt, omit optional fields instead of sending `null`.
-
-**Examples:**
-
-Add a hero block:
-
-```bash
-riverbankcms block upsert home main-hero \
-  --kind block.hero \
-  --data '{"heading": "Welcome", "subheading": "to our website"}'
-```
-
-Add a minimal media and text block:
-
-`block.media-text` has many display and carousel fields, but most are optional controls with defaults. A minimal content-only block only needs rich text:
-
-```json
-{
-  "text": {
-    "type": "doc",
-    "content": [
-      {
-        "type": "paragraph",
-        "content": [{ "type": "text", "text": "Welcome to our space." }]
-      }
-    ]
-  }
-}
-```
-
-Add media only when you have a complete media item:
-
-```json
-{
-  "text": {
-    "type": "doc",
-    "content": [{ "type": "paragraph", "content": [] }]
-  },
-  "images": [
-    {
-      "image": {
-        "type": "image",
-        "src": "/images/studio.jpg",
-        "alt": "A bright studio room"
-      }
-    }
-  ]
-}
-```
-
-Add a body text block:
-
-```bash
-riverbankcms block upsert home intro-content \
-  --kind block.body-text \
-  --data '{"body": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Welcome to our site. We offer..."}]}]}}'
-```
-
-Add an image block:
-
-```bash
-riverbankcms block upsert home feature-image \
-  --kind block.image \
-  --data '{"src": "/images/feature.jpg", "alt": "Feature image", "caption": "Our latest product"}'
-```
-
-Add a CTA block:
-
-```bash
-riverbankcms block upsert home main-cta \
-  --kind block.cta \
-  --data '{"text": "Get Started", "url": "/signup", "style": "primary"}'
-```
-
-### 4. Specify Position (Optional)
-
-Add the block at a specific position (0-indexed):
-
-```bash
-riverbankcms block upsert home new-section \
-  --kind block.body-text \
-  --data '{"content": "<p>...</p>"}' \
-  --position 0
-```
-
-- `--position 0` places it first
-- `--position 1` places it second
-- Omitting position adds it at the end
-
-### 5. Preview the Block
-
-Preview how the block will render:
-
-```bash
-riverbankcms preview block.hero \
-  --data '{"heading": "Welcome", "subheading": "to our website"}' \
-  --open
-```
-
-### 6. Verify the Block
-
-Confirm the block was added:
-
-```bash
-riverbankcms block get home main-hero
-```
-
-List all blocks to see the order:
-
-```bash
-riverbankcms block list home
-```
-
-## Complex Block Content
-
-For blocks with nested or complex content, use a JSON file.
-
-### Example: Hero with Background and CTA
-
-**hero-content.json:**
-
-```json
-{
-  "heading": "Welcome to Our Platform",
-  "subheading": "Build amazing things with us",
-  "backgroundImage": {
-    "src": "/images/hero-bg.jpg",
-    "alt": "Abstract background"
-  },
-  "cta": {
-    "text": "Get Started",
-    "url": "/signup"
-  },
-  "alignment": "center"
-}
-```
-
-```bash
-riverbankcms block upsert home main-hero \
-  --kind block.hero \
-  --file ./hero-content.json
-```
-
-### Example: Gallery Block
-
-**gallery-content.json:**
-
-```json
-{
-  "images": [
-    { "image": { "type": "image", "src": "/images/project-1.jpg", "alt": "Project 1" }, "caption": "E-commerce redesign" },
-    { "image": { "type": "image", "src": "/images/project-2.jpg", "alt": "Project 2" }, "caption": "Mobile app" },
-    { "image": { "type": "image", "src": "/images/project-3.jpg", "alt": "Project 3" }, "caption": "Brand identity" }
-  ],
-  "variant": "grid"
-}
-```
-
-```bash
-riverbankcms block upsert home portfolio-gallery \
-  --kind block.image-gallery \
-  --file ./gallery-content.json
-```
-
-### Example: Marquee Gallery (infinite scroll)
-
-```json
-{
-  "variant": "marquee",
-  "marqueeDirection": "left",
-  "marqueeSpeed": "medium",
-  "marqueePauseOnHover": true,
-  "marqueeImageSize": "md",
-  "images": [
-    { "image": { "type": "image", "src": "/images/project-1.jpg", "alt": "Project 1" }, "caption": "E-commerce redesign" }
-  ]
-}
-```
-
-## Updating Existing Blocks
-
-To update a block, use the same `upsert` command with the same block ID:
-
-```bash
-riverbankcms block upsert home main-hero \
-  --kind block.hero \
-  --data '{"heading": "New Heading", "subheading": "Updated content"}'
-```
-
-The block is replaced with the new content.
-
-## Reordering Blocks
-
-Change the order of blocks on the page:
-
-```bash
-riverbankcms block reorder home main-hero intro-content feature-image main-cta
-```
-
-Blocks appear in the order listed.
-
-## Deleting Blocks
-
-Remove a block:
-
-```bash
-riverbankcms delete block home old-section --yes
-```
-
-## Troubleshooting
-
-### "Invalid block kind"
-
-- Check the kind matches exactly (e.g., `block.hero` not `hero`)
-- See `block-types.md` for valid system blocks
-- See `schema.md` for custom blocks (e.g., `custom.my-block`)
-
-### Block not rendering correctly
-
-- Verify the data structure matches what the block expects
-- Preview the block: `riverbankcms preview <kind> --data '...' --open`
-- Check for required fields in `block-types.md`
-
-### JSON parsing error
-
-- Ensure JSON is properly quoted in the shell
-- Use single quotes around the JSON string
-- For complex content, use `--file` instead of `--data`
-
-### Block at wrong position
-
-- Use `riverbankcms block reorder` to fix the order
-- Or delete and re-add with `--position`
-
-## Related Workflows
-
-- **Block Extensions** - Add layout variants to system blocks: see `block-extensions.md`
-- **Custom Blocks** - Create site-specific blocks: see `custom-block.md`
-- **Content Types** - Embed content entries on pages: see `content-types.md`
-- **CMS-ify a Page** - Convert hard-coded pages to CMS-driven: see `cmsify-page.md`

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

@@ -1,83 +0,0 @@
-# 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 --dry-run
-```
-
-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.
-
-Run `riverbankcms push-config --dry-run` before applying schema/config changes to validate the config and preview the config surfaces without mutating the dashboard.
-
-## 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.