@riverbankcms/sdk 0.7.0 → 0.7.2

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

@@ -0,0 +1,384 @@
+# Content Management Guide
+
+This guide explains the RiverbankCMS content model and how to work with content via the SDK.
+
+## Content Model Overview
+
+RiverbankCMS organizes content into four main types:
+
+### 1. Entries
+
+Content items for a specific content type (e.g., blog posts, products, team members).
+
+- Defined by content types in `riverbank.config.ts`
+- Each entry has an identifier, slug, and type-specific data
+- Can be draft or published
+
+**Local file structure:**
+
+```
+content/
+  entries/
+    blog-post.json    # All blog-post entries
+    product.json      # All product entries
+```
+
+### 2. Pages
+
+Standalone pages that contain blocks.
+
+- Have a path (URL), title, and SEO metadata
+- Contain an ordered list of blocks
+- Can be draft or published
+
+**Local file structure:**
+
+```
+content/
+  pages/
+    home.json         # Home page with blocks
+    about.json        # About page with blocks
+```
+
+### 3. Blocks
+
+Content components within pages.
+
+- Each block has a kind (e.g., `block.hero`, `block.bodyText`)
+- Contains kind-specific content data
+- Ordered by position within a page
+
+**Common block kinds:**
+
+| Kind | Description |
+|------|-------------|
+| `block.hero` | Hero/banner sections with heading, image, CTA |
+| `block.bodyText` | Rich text content |
+| `block.image` | Image with caption |
+| `block.cta` | Call-to-action buttons |
+| `block.embed` | Embedded content (videos, etc.) |
+
+See `block-types.md` for the full list.
+
+### 4. Navigation
+
+Menu structures for site navigation.
+
+- Named menus (e.g., "main", "footer")
+- Hierarchical items with labels, URLs, and children
+
+**Local file structure:**
+
+```
+content/
+  navigation.json     # All navigation menus
+```
+
+---
+
+## Working with Identifiers
+
+Identifiers are stable, human-readable names for content:
+
+- Used by the SDK to reference content reliably
+- Should be kebab-case (e.g., `my-blog-post`, `about-us`)
+- Are idempotent - upserting with same identifier updates existing content
+- Allow content to be tracked across environments
+
+**Examples:**
+
+```bash
+# Entry identifier
+riverbankcms entry upsert blog-post my-first-post --data '...'
+
+# Page identifier
+riverbankcms page upsert about --title "About Us" --path /about
+
+# Block identifier (within a page)
+riverbankcms block upsert about hero-section --kind block.hero --data '...'
+```
+
+**Backfill identifiers for legacy content:**
+
+```bash
+riverbankcms identifiers backfill
+```
+
+---
+
+## Draft vs Published
+
+All content has a publication status:
+
+| Status | Visibility |
+|--------|------------|
+| Draft | Only visible in preview mode |
+| Published | Visible on the live site |
+
+New content is created as a draft by default.
+
+### Checking Status
+
+```bash
+# Check entry status
+riverbankcms entry get blog-post my-post
+
+# Check page status
+riverbankcms page get about
+
+# List with JSON to see status field
+riverbankcms entry list blog-post --json | jq '.items[] | {identifier, status}'
+```
+
+### Publishing Content
+
+```bash
+# Publish entry
+riverbankcms entry publish blog-post my-post
+
+# Publish page
+riverbankcms page publish about
+```
+
+### Unpublishing Content
+
+```bash
+# Unpublish entry (revert to draft)
+riverbankcms entry unpublish blog-post my-post
+
+# Unpublish page
+riverbankcms page unpublish about
+```
+
+### Unpublished Changes
+
+When you modify published content, it stays published but gains unpublished changes. The live site shows the last published version until you publish again.
+
+```bash
+# Check for unpublished changes
+riverbankcms entry get blog-post my-post --json | jq '.hasUnpublishedChanges'
+
+# Publish to apply pending changes
+riverbankcms entry publish blog-post my-post
+```
+
+---
+
+## Content Sync Workflow
+
+### Pulling Content
+
+Downloads CMS content to local JSON files:
+
+```bash
+# Pull all content
+riverbankcms pull
+
+# Pull specific types
+riverbankcms pull entries
+riverbankcms pull entries blog-post
+riverbankcms pull pages
+riverbankcms pull navigation
+```
+
+**Output directory structure:**
+
+```
+content/
+├── entries/
+│   ├── blog-post.json
+│   └── product.json
+├── pages/
+│   ├── home.json
+│   └── about.json
+└── navigation.json
+```
+
+### Pushing Content
+
+Uploads local changes to the CMS:
+
+```bash
+# Preview changes (recommended)
+riverbankcms push --dry-run
+
+# Apply changes
+riverbankcms push
+```
+
+### Sync Configuration
+
+Configure sync behavior in `riverbank.config.ts`:
+
+```typescript
+export default defineConfig({
+  siteId: '...',
+  sync: {
+    // How to handle existing entries during push
+    existingEntries: 'update',  // 'skip' (default) or 'update'
+
+    // Target state for pushed content
+    contentTarget: 'draft',     // 'draft' (default) or 'publish'
+  },
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `existingEntries` | `skip`, `update` | Whether to update entries that already exist |
+| `contentTarget` | `draft`, `publish` | Whether pushed content should be draft or published |
+
+---
+
+## Local Content Files
+
+### Entry File Format
+
+`content/entries/blog-post.json`:
+
+```json
+[
+  {
+    "identifier": "my-first-post",
+    "slug": "my-first-post",
+    "data": {
+      "title": "My First Post",
+      "content": "<p>Hello world!</p>",
+      "publishedAt": "2024-01-15"
+    }
+  },
+  {
+    "identifier": "another-post",
+    "slug": "another-post",
+    "data": {
+      "title": "Another Post",
+      "content": "<p>More content...</p>"
+    }
+  }
+]
+```
+
+### Page File Format
+
+`content/pages/home.json`:
+
+```json
+{
+  "identifier": "home",
+  "title": "Home",
+  "path": "/",
+  "seo": {
+    "title": "Welcome | My Site",
+    "description": "The home page"
+  },
+  "blocks": [
+    {
+      "identifier": "hero-main",
+      "kind": "block.hero",
+      "content": {
+        "heading": "Welcome to My Site",
+        "subheading": "We build great things"
+      }
+    },
+    {
+      "identifier": "intro-text",
+      "kind": "block.bodyText",
+      "content": {
+        "content": "<p>Introduction text here...</p>"
+      }
+    }
+  ]
+}
+```
+
+### Navigation File Format
+
+`content/navigation.json`:
+
+```json
+{
+  "main": [
+    { "label": "Home", "url": "/" },
+    { "label": "About", "url": "/about" },
+    {
+      "label": "Products",
+      "url": "/products",
+      "children": [
+        { "label": "Category A", "url": "/products/a" },
+        { "label": "Category B", "url": "/products/b" }
+      ]
+    }
+  ],
+  "footer": [
+    { "label": "Privacy", "url": "/privacy" },
+    { "label": "Terms", "url": "/terms" }
+  ]
+}
+```
+
+---
+
+## Configuration Reference
+
+### riverbank.config.ts
+
+Main SDK configuration:
+
+```typescript
+import { defineConfig } from '@riverbankcms/sdk';
+
+export default defineConfig({
+  // Required: Your site ID
+  siteId: 'your-site-id',
+
+  // Custom blocks (see schema.md)
+  customBlocks: [...],
+
+  // Extend built-in blocks with new fields
+  blockFieldExtensions: {...},
+
+  // Override select field options
+  blockFieldOptions: {...},
+
+  // Content scaffolding
+  content: {
+    contentTypes: [...],
+    pages: [...],
+    entries: {...},
+    navigation: {...},
+  },
+
+  // Sync settings
+  sync: {
+    existingEntries: 'update',
+    contentTarget: 'draft',
+  },
+});
+```
+
+### Environment Variables
+
+Local development (default):
+
+```bash
+RIVERBANK_LOCAL_SITE_ID=your-site-id
+RIVERBANK_LOCAL_DASHBOARD_URL=http://localhost:4000
+RIVERBANK_LOCAL_MGMT_API_KEY=bld_mgmt_sk_...
+```
+
+Production (`--remote` flag):
+
+```bash
+RIVERBANK_REMOTE_SITE_ID=your-site-id
+RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.riverbankcms.com
+RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
+```
+
+---
+
+## Related Documentation
+
+- `cli-reference.md` - Full CLI command reference
+- `schema.md` - This site's content types and custom blocks
+- `block-types.md` - Available block types
+- `workflows/` - Step-by-step guides for common tasks

package/dist/cli/init-docs/content/context-brand.md

@@ -0,0 +1,125 @@
+# Brand Assets
+
+This document helps AI agents understand the visual brand identity for consistent content creation.
+
+## Purpose
+
+Document brand assets and guidelines including:
+
+- Logo usage and variations
+- Color palette
+- Typography
+- Image and illustration style
+- Design patterns
+
+## Color Palette
+
+Define the brand colors:
+
+```
+Primary:    #______  (e.g., #0066CC - main brand color)
+Secondary:  #______  (e.g., #00CC66 - accent color)
+Accent:     #______  (e.g., #CC6600 - highlight color)
+
+Neutrals:
+- Dark:     #______  (e.g., #1A1A1A - headings, body text)
+- Medium:   #______  (e.g., #666666 - secondary text)
+- Light:    #______  (e.g., #F5F5F5 - backgrounds)
+- White:    #FFFFFF
+
+Status:
+- Success:  #______  (e.g., #22C55E)
+- Warning:  #______  (e.g., #F59E0B)
+- Error:    #______  (e.g., #EF4444)
+- Info:     #______  (e.g., #3B82F6)
+```
+
+## Typography
+
+Define the font families:
+
+```
+Headings:   [Font Name], [weight] (e.g., Inter, bold)
+Body:       [Font Name], [weight] (e.g., Inter, regular)
+Code:       [Font Name] (e.g., JetBrains Mono)
+```
+
+**Heading sizes:**
+- H1: (e.g., 48px / 3rem)
+- H2: (e.g., 36px / 2.25rem)
+- H3: (e.g., 24px / 1.5rem)
+- H4: (e.g., 20px / 1.25rem)
+
+**Body text:** (e.g., 16px / 1rem, line-height 1.6)
+
+## Logo Files
+
+Reference paths to logo files:
+
+| Variant | Path | Usage |
+|---------|------|-------|
+| Primary | `/public/logo.svg` | Main logo for light backgrounds |
+| Dark mode | `/public/logo-dark.svg` | For dark backgrounds |
+| Icon only | `/public/logo-icon.svg` | Favicon, small spaces |
+| Full width | `/public/logo-full.svg` | Header, large displays |
+
+**Logo usage guidelines:**
+- Minimum clear space: (e.g., equal to the height of the logomark)
+- Minimum size: (e.g., 100px width for full logo, 24px for icon)
+- Don't stretch, rotate, or alter colors
+
+## Image Style
+
+Guidelines for imagery:
+
+**Photography:**
+- Style: (e.g., bright and modern, lifestyle-focused, professional)
+- Subjects: (e.g., people using products, workspace shots, abstract)
+- Avoid: (e.g., stock photo cliches, outdated imagery)
+
+**Illustrations:**
+- Style: (e.g., flat design, 3D, hand-drawn, geometric)
+- Color usage: (e.g., use brand colors only, limited palette)
+
+**Aspect ratios:**
+- Hero images: (e.g., 16:9, 1920x1080 minimum)
+- Blog thumbnails: (e.g., 3:2, 1200x800)
+- Social sharing: (e.g., 1.91:1 for Open Graph)
+
+## Icons
+
+Icon style and sources:
+
+- **Icon set**: (e.g., Lucide, Heroicons, custom)
+- **Style**: (e.g., outline, solid, duotone)
+- **Size**: (e.g., 24px default, 16px small, 32px large)
+- **Color**: (e.g., inherit from text, or specific brand color)
+
+## Example Completed Section
+
+```markdown
+## Color Palette
+
+Primary:    #2563EB  (Blue - main brand color)
+Secondary:  #10B981  (Green - success states, CTAs)
+Accent:     #8B5CF6  (Purple - highlights)
+
+Neutrals:
+- Dark:     #111827  (Gray 900 - headings)
+- Medium:   #6B7280  (Gray 500 - body text)
+- Light:    #F9FAFB  (Gray 50 - backgrounds)
+- White:    #FFFFFF
+
+## Typography
+
+Headings:   Inter, semibold (600)
+Body:       Inter, regular (400)
+Code:       Fira Code, regular
+
+## Image Style
+
+Photography: Clean, bright, professional. Real people in real workspaces.
+Illustrations: Flat design with brand colors. Simple, modern, friendly.
+
+Avoid: Dark/moody imagery, overly complex graphics, generic stock photos.
+```

package/dist/cli/init-docs/content/context-brief.md

@@ -0,0 +1,77 @@
+# Site Brief
+
+This document helps AI agents understand the brand, tone, and goals for this site. Fill in the sections below to provide context for content creation.
+
+## Brand Voice
+
+Describe how the brand communicates:
+
+- **Tone**: (e.g., professional, friendly, technical, casual, authoritative)
+- **Personality**: (e.g., helpful, innovative, trustworthy, playful)
+- **Language style**: (e.g., simple and direct, detailed and thorough, conversational)
+
+**Words/phrases to use:**
+- (Add brand-appropriate terminology)
+
+**Words/phrases to avoid:**
+- (Add terms that don't fit the brand)
+
+## Target Audience
+
+Who is this site for?
+
+- **Primary audience**: (e.g., small business owners, developers, enterprise teams)
+- **Secondary audience**: (if applicable)
+- **Technical level**: (e.g., beginner, intermediate, expert)
+- **Key pain points**: (what problems are they trying to solve?)
+
+## Site Purpose
+
+What is this site meant to achieve?
+
+- **Primary goal**: (e.g., generate leads, sell products, provide information)
+- **Secondary goals**: (e.g., build brand awareness, support customers)
+- **Key user journeys**: (what should visitors do on the site?)
+
+## Content Guidelines
+
+Standards for content creation:
+
+- **Preferred content length**: (e.g., blog posts 800-1200 words)
+- **Heading style**: (e.g., sentence case, title case)
+- **Image requirements**: (e.g., minimum resolution, preferred aspect ratios)
+- **SEO focus areas**: (key topics or keywords)
+
+## Example
+
+```markdown
+## Brand Voice
+
+- **Tone**: Professional but approachable
+- **Personality**: Helpful, knowledgeable, straightforward
+- **Language style**: Clear and concise, avoid jargon unless necessary
+
+**Words to use:** streamline, efficient, simple, powerful, reliable
+**Words to avoid:** synergy, leverage, disrupt, revolutionary
+
+## Target Audience
+
+- **Primary**: Small to medium business owners looking for a CMS
+- **Technical level**: Intermediate - comfortable with technology but not developers
+- **Pain points**: Current CMS is too complex, need better content management
+
+## Site Purpose
+
+- **Primary goal**: Convert visitors to trial signups
+- **Key journeys**:
+  1. Learn about features → Start free trial
+  2. Read case studies → Request demo
+  3. Check pricing → Choose plan
+
+## Content Guidelines
+
+- Blog posts: 1000-1500 words
+- All headings in sentence case
+- Include at least one image per blog post
+- Focus on "headless CMS" and "content management" keywords
+```

package/dist/cli/init-docs/content/context-knowledge.md

@@ -0,0 +1,111 @@
+# Knowledge Base
+
+This directory stores domain knowledge, reference information, and facts that AI agents need when working with this site's content.
+
+## Purpose
+
+Help agents understand:
+
+- Industry terminology and definitions
+- Product or service details
+- Technical specifications
+- Frequently asked questions
+- Reference data and statistics
+
+## Suggested Organization
+
+Create files for different knowledge areas:
+
+| File | Purpose |
+|------|---------|
+| `products.md` | Product catalog, features, specifications |
+| `services.md` | Service offerings and descriptions |
+| `faq.md` | Common questions and answers |
+| `glossary.md` | Industry terms and definitions |
+| `competitors.md` | Competitive landscape and differentiation |
+| `stats.md` | Key statistics and data points |
+
+## Example File Format
+
+### products.md
+
+```markdown
+# Products
+
+## Product: Widget Pro
+
+- **SKU**: WP-001
+- **Category**: Automation Tools
+- **Price**: $99/month
+- **Target customer**: Small business teams
+
+### Key Features
+- Feature A: Description of what it does
+- Feature B: Description of what it does
+- Feature C: Description of what it does
+
+### Use Cases
+- Scenario 1: How customers use this
+- Scenario 2: Another common use case
+
+### Comparison to Widget Basic
+- Pro has X, Basic doesn't
+- Pro supports Y users, Basic supports Z
+```
+
+### glossary.md
+
+```markdown
+# Glossary
+
+## A
+
+**API (Application Programming Interface)**
+A set of protocols that allows different software applications to communicate.
+
+**Authentication**
+The process of verifying user identity before granting access.
+
+## B
+
+**Block**
+A modular content component in RiverbankCMS (e.g., hero, text, image).
+
+## C
+
+**CMS (Content Management System)**
+Software for creating, managing, and publishing digital content.
+
+**Content Type**
+A defined structure for a category of content (e.g., blog posts, products).
+```
+
+### faq.md
+
+```markdown
+# Frequently Asked Questions
+
+## General
+
+**Q: What is [Product Name]?**
+A: [Product Name] is a [brief description]. It helps [target audience] to [main benefit].
+
+**Q: How much does it cost?**
+A: Pricing starts at $X/month. See our pricing page for full details.
+
+## Technical
+
+**Q: What integrations are available?**
+A: We integrate with [List of integrations]. Custom integrations are available via our API.
+
+**Q: Is there a free trial?**
+A: Yes, we offer a 14-day free trial with full access to all features.
+```
+
+## Best Practices
+
+- Keep information factual and up-to-date
+- Use consistent formatting across files
+- Include dates when information might become outdated
+- Cross-reference related topics
+- Update when products, services, or facts change