@adaptic/maestro 1.1.6 → 1.1.8

package/docs/guides/media-generation-setup.md

@@ -0,0 +1,349 @@
+# Media Generation Setup Guide
+
+How to generate branded illustrations, diagrams, and video assets using Google Gemini and Veo APIs. Covers API setup, prompt specification authoring, image generation, video generation, brand alignment, and troubleshooting.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). Node.js 20+ must be installed.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  PROMPT SPECS (TypeScript/ESM files)                             │
+│                                                                   │
+│  scripts/media-generation/prompts/                               │
+│    ├── illustrations/   *.ts / *.mjs                             │
+│    ├── diagrams/        *.ts / *.mjs                             │
+│    └── videos/          *.ts / *.mjs                             │
+│                                                                   │
+│  Each spec exports: { id, slug, title, purpose, style,           │
+│    colorPalette, mood, elements, aspectRatio, ... }              │
+├─────────────────────────────────────────────────────────────────┤
+│  GENERATION                                                      │
+│                                                                   │
+│  generate-assets.mjs                                             │
+│    ├── --illustration <slug> → gemini-image-client.mjs           │
+│    │     └── @google/genai SDK → Gemini 3 Pro / Imagen           │
+│    │         └── public/generated/illustrations/<slug>.png       │
+│    │                                                              │
+│    ├── --video <slug> → veo-video-client.mjs                     │
+│    │     └── @google/genai SDK → Veo 3.1                         │
+│    │         └── public/generated/videos/<slug>.mp4              │
+│    │                                                              │
+│    ├── --all-missing → batch generate all missing illustrations  │
+│    └── --all-missing-videos → batch generate all missing videos  │
+│                                                                   │
+│  Rate limit: 15s between requests                                │
+│  Generation log: scripts/media-generation/generation-log.json    │
+├─────────────────────────────────────────────────────────────────┤
+│  OUTPUT                                                          │
+│                                                                   │
+│  public/generated/                                               │
+│    ├── illustrations/   *.png                                    │
+│    ├── diagrams/        *.png                                    │
+│    └── videos/          *.mp4                                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. API Setup
+
+### 1.1 Get a Gemini API Key
+
+1. Go to https://aistudio.google.com/apikey
+2. Create a new API key (or use an existing one)
+3. The same key works for both image (Gemini/Imagen) and video (Veo) generation
+
+### 1.2 Configure Environment
+
+Add to `.env`:
+
+```bash
+GEMINI_API_KEY=your-api-key-here
+```
+
+### 1.3 Install Dependencies
+
+```bash
+cd ~/agent-repo && npm install
+```
+
+Required packages (in `package.json`):
+- `@google/genai` — Google AI SDK for Gemini and Veo
+- `dotenv` — Environment variable loading
+
+### 1.4 Verify Setup
+
+```bash
+# Quick test — list available prompt specs
+node scripts/media-generation/generate-assets.mjs --list
+```
+
+---
+
+## 2. Image Generation (Gemini / Imagen)
+
+### 2.1 Generate a Single Illustration
+
+```bash
+node scripts/media-generation/generate-assets.mjs --illustration <slug>
+```
+
+The `<slug>` must match a prompt spec file in `scripts/media-generation/prompts/illustrations/`.
+
+### 2.2 Generate All Missing
+
+```bash
+# Generate illustrations for all specs that don't have output files yet
+node scripts/media-generation/generate-assets.mjs --all-missing
+```
+
+### 2.3 Models
+
+| Model | Quality | Speed | Use Case |
+|---|---|---|---|
+| `gemini-3-pro-image-preview` | Best | Slower | Default — board packs, investor materials |
+| `imagen-*` variants | Good | Fast | High-volume generation, social media |
+
+Override via prompt spec or environment:
+
+```bash
+GEMINI_MODEL=imagen-3.0-generate-002 node scripts/media-generation/generate-assets.mjs --illustration <slug>
+```
+
+### 2.4 Aspect Ratios
+
+Supported: `1:1`, `3:4`, `4:3`, `9:16`, `16:9`
+
+Set per prompt spec in the `aspectRatio` field.
+
+---
+
+## 3. Video Generation (Veo 3.1)
+
+### 3.1 Generate a Video
+
+```bash
+node scripts/media-generation/generate-assets.mjs --video <slug>
+```
+
+### 3.2 Generate All Missing Videos
+
+```bash
+node scripts/media-generation/generate-assets.mjs --all-missing-videos
+```
+
+### 3.3 Configuration
+
+| Setting | Default | Options |
+|---|---|---|
+| Model | `veo-3.1-generate-preview` | — |
+| Duration | 8 seconds | 4, 6, 8 |
+| Resolution | 720p | 720p, 1080p, 4k |
+| Modes | text-to-video | text-to-video, image-to-video |
+
+### 3.4 Polling
+
+Video generation is asynchronous. The client:
+1. Submits the generation request
+2. Polls every 10 seconds for completion
+3. Times out after 10 minutes
+4. Downloads the video file on completion
+
+---
+
+## 4. Prompt Specifications
+
+### 4.1 Structure
+
+Prompts are TypeScript (`.ts`) or ESM (`.mjs`) files in `scripts/media-generation/prompts/`:
+
+```
+prompts/
+  illustrations/    # Board pack covers, section illustrations
+  diagrams/         # Architecture diagrams, flow charts
+  videos/           # Animated intros, presentation backgrounds
+```
+
+### 4.2 Writing a Prompt Spec
+
+```typescript
+// scripts/media-generation/prompts/illustrations/board-pack-cover-q2.ts
+export default {
+  id: "board-pack-cover-q2-2026",
+  slug: "board-pack-cover-q2-2026",
+  title: "Q2 2026 Board Pack Cover Illustration",
+  purpose: "Cover page visual for quarterly board materials",
+  imageCategory: "editorial-hand-drawn",
+  colorPalette: ["#1C1917", "#FAFAF9", "#78716C", "#D6D3D1"],
+  mood: ["institutional", "sophisticated", "premium"],
+  elements: [
+    "abstract representation of global financial network",
+    "interconnected nodes suggesting multi-jurisdiction structure",
+    "subtle reference to algorithmic trading"
+  ],
+  style: "Monochromatic NYT-style hand-drawn editorial illustration. " +
+    "Pen-and-ink technique with cross-hatching and stippling. " +
+    "No color, no gradients, no digital effects.",
+  aspectRatio: "3:4",
+};
+```
+
+### 4.3 Key Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | Yes | Unique identifier |
+| `slug` | Yes | Filename-safe identifier (used for output filename) |
+| `title` | Yes | Human-readable title |
+| `purpose` | Yes | What this asset is used for |
+| `style` | Yes | Detailed style description for the AI model |
+| `colorPalette` | No | Hex colour values (brand-aligned) |
+| `mood` | No | Tone descriptors |
+| `elements` | No | Visual elements to include |
+| `aspectRatio` | No | Output aspect ratio (default: `16:9`) |
+| `imageCategory` | No | Category tag for organisation |
+
+### 4.4 TypeScript vs ESM
+
+- `.ts` files require `tsx` (installed via devDependencies) — the generator shells out to `npx tsx` to evaluate them
+- `.mjs` files are imported directly — slightly faster, no build step
+- Both work identically; use `.ts` for consistency with the rest of the project
+
+---
+
+## 5. Brand Alignment
+
+All generated assets must follow `config/brand-assets.yaml`:
+
+### 5.1 Illustration Style
+
+- **Monochromatic editorial hand-drawn** (NYT-style)
+- Pen-and-ink technique: cross-hatching, stippling
+- No colour, no gradients, no digital effects
+- Restrained and institutional mood
+
+### 5.2 Colour Palette
+
+| Colour | Hex | Usage |
+|---|---|---|
+| Near-black | `#1C1917` | Primary line work |
+| Off-white | `#FAFAF9` | Background/negative space |
+| Warm gray | `#78716C` | Secondary elements |
+| Light gray | `#D6D3D1` | Tertiary/halftone areas |
+| Medium gray | `#A8A29E` | Mid-tones |
+
+### 5.3 What to Avoid
+
+- Cartoon or comic styles
+- Isometric SaaS/tech aesthetics
+- Stock photography look
+- Bright colours or saturated palettes
+- Clip art or flat design icons
+
+---
+
+## 6. Output & Logging
+
+### 6.1 Output Directories
+
+| Type | Path |
+|---|---|
+| Illustrations | `public/generated/illustrations/<slug>.png` |
+| Diagrams | `public/generated/diagrams/<slug>.png` |
+| Videos | `public/generated/videos/<slug>.mp4` |
+
+### 6.2 Generation Log
+
+Every generation is recorded in `scripts/media-generation/generation-log.json`:
+
+```json
+[
+  {
+    "slug": "board-pack-cover-q2-2026",
+    "type": "illustration",
+    "model": "gemini-3-pro-image-preview",
+    "generatedAt": "2026-04-09T14:30:00.000Z",
+    "outputPath": "public/generated/illustrations/board-pack-cover-q2-2026.png"
+  }
+]
+```
+
+### 6.3 Rate Limiting
+
+A 15-second delay is enforced between consecutive API requests to avoid rate limits. For batch generation (`--all-missing`), this means ~4 images per minute.
+
+---
+
+## 7. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | API key valid | `node -e "require('dotenv').config(); console.log(process.env.GEMINI_API_KEY?.slice(0,8))"` |
+| 2 | List specs | `node scripts/media-generation/generate-assets.mjs --list` |
+| 3 | Generate image | Generate one illustration and verify output in `public/generated/` |
+| 4 | Generate video | Generate one video (takes several minutes) |
+| 5 | Brand alignment | Verify output matches monochromatic editorial style |
+| 6 | Batch generation | `--all-missing` — should skip already-generated assets |
+| 7 | Generation log | Check `generation-log.json` for entries |
+
+---
+
+## 8. Troubleshooting
+
+### "GEMINI_API_KEY not set"
+
+1. Check `.env` file exists and contains the key
+2. Verify key format (should be a long alphanumeric string)
+3. Get a key from https://aistudio.google.com/apikey
+
+### Rate limit errors
+
+1. The 15-second delay should prevent most rate limits
+2. If hit, wait 60 seconds and retry
+3. For heavy batch generation, consider running overnight
+4. Check your API quota at https://aistudio.google.com/
+
+### "Prompt spec not found"
+
+1. Check the slug matches a file in `scripts/media-generation/prompts/illustrations/` (or `diagrams/`, `videos/`)
+2. File must end in `.ts` or `.mjs`
+3. List available specs: `node scripts/media-generation/generate-assets.mjs --list`
+
+### Image quality issues
+
+1. Review the `style` field in the prompt spec — be more specific about the desired aesthetic
+2. Add negative prompts ("no cartoon", "no digital effects")
+3. Try a different model (Imagen may produce different results than Gemini)
+4. Adjust aspect ratio to match the intended use
+
+### Video generation timeout
+
+1. Default timeout is 10 minutes — video generation can be slow
+2. Check the Veo API status if consistently timing out
+3. Try shorter duration (4s instead of 8s) for faster generation
+4. Lower resolution (720p) generates faster than 1080p/4k
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/media-generation/generate-assets.mjs` | Main generation orchestrator |
+| `scripts/media-generation/gemini-image-client.mjs` | Google Gemini/Imagen image API client |
+| `scripts/media-generation/veo-video-client.mjs` | Veo 3.1 video API client |
+| `scripts/media-generation/prompts/` | Prompt spec directory (illustrations, diagrams, videos) |
+| `scripts/media-generation/generation-log.json` | Generation history log |
+| `public/generated/` | Output directory for all generated assets |
+| `config/brand-assets.yaml` | Brand style guide (colours, typography, illustration style) |
+
+---
+
+## Related Documents
+
+- [PDF Generation Setup](pdf-generation-setup.md) — Using generated assets in branded PDFs
+- [Agent Persona Setup](agent-persona-setup.md) — Brand configuration
+- [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md) — Node.js and dependency installation