# Getting Started with RiverbankCMS SDK

This site uses RiverbankCMS as a headless CMS. Content is managed through the SDK CLI.

## Quick Setup

### 1. Verify Environment Configuration

Check `.env.local` has these variables:

```bash
# Local development
RIVERBANK_LOCAL_SITE_ID=your-site-id
RIVERBANK_LOCAL_DASHBOARD_URL=http://localhost:4000
RIVERBANK_LOCAL_MGMT_API_KEY=bld_mgmt_sk_...

# Production (optional)
RIVERBANK_REMOTE_SITE_ID=your-site-id
RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.riverbankcms.com
RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
```

### 2. Pull Content

Download current content from the CMS:

```bash
riverbankcms pull
```

This creates a `content/` directory with JSON files:

```
content/
├── entries/
│   └── [content-type].json
├── pages/
│   └── [page-identifier].json
├── themes/
│   └── current.json
└── navigation.json
```

You can also pull just the theme:

```bash
riverbankcms pull theme
```

### 3. Make Changes

Edit the JSON files directly, or use CLI commands:

```bash
# Create or update an entry
riverbankcms entry upsert blog-post my-new-post --data '{"title": "New Post"}'

# Create a page
riverbankcms page upsert about --title "About Us" --path /about

# Add a block to a page
riverbankcms block upsert about hero-section --kind block.hero --data '{"heading": "About Us"}'
```

### 4. Push Changes

Preview what would change:

```bash
riverbankcms push --dry-run
```

Apply changes to the CMS:

```bash
riverbankcms push
```

## 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.

## Key Documentation

| Document                | Purpose                                                          |
| ----------------------- | ---------------------------------------------------------------- |
| `cli-reference.md`      | All CLI commands and options                                     |
| `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)                 |
| `workflows/`            | Step-by-step guides for common tasks, including editor workflows |

## Common Tasks

| Task             | Command                                                               |
| ---------------- | --------------------------------------------------------------------- |
| Pull all content | `riverbankcms pull`                                                   |
| Push changes     | `riverbankcms push`                                                   |
| Preview changes  | `riverbankcms push --dry-run`                                         |
| Create a page    | `riverbankcms page upsert <id> --title "..." --path /...`             |
| Add a block      | `riverbankcms block upsert <page> <block-id> --kind ... --data '...'` |
| Publish an entry | `riverbankcms entry publish <type> <id>`                              |
| Publish a page   | `riverbankcms page publish <id>`                                      |
| List entries     | `riverbankcms entry list <type>`                                      |
| Get JSON output  | Add `--json` to any command                                           |

## Configuration Files

### riverbank.config.ts

Main SDK configuration defining:

- Site ID
- Custom blocks
- Block field extensions
- Block field options
- Content type definitions
- Sync settings

### content.config.ts (if present)

Additional content configuration for scaffolding.

## Working with Remote/Production

Use `--env=remote` to target production instead of local:

```bash
# Pull from production
riverbankcms pull --env=remote

# Push to production (requires --yes for safety)
riverbankcms push --env=remote --yes
```

**Safety note:** Remote push requires `--yes` flag to prevent accidental production changes.

## Media Safety (Avoid Broken Images)

- Portable content JSON should store media as **identifier-only** (no `assetId` / storage paths / `src`).
- Download media bytes to disk: `riverbankcms pull --local-media`
- Optional (CMS → CMS): sync media bytes by identifier + checksum: `riverbankcms pull --env=remote --sync-media --yes`

## Next Steps

1. Read `cli-reference.md` for detailed command documentation
2. Review `schema.md` to understand this site's content model
3. Check `workflows/` for step-by-step guides
