videoclaw 3.0.0-alpha.1

package/src/video/obsidian-vault.ts

@@ -0,0 +1,96 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export interface ObsidianVaultScaffoldResult {
+  root: string;
+  dashboardPath: string;
+  templatesDir: string;
+  viewsDir: string;
+}
+
+const PROJECT_TEMPLATE = `---
+title: ""
+slug: ""
+ops_status: planned
+production_mode: storyboard
+next_stage: brief
+completed_stage_count: 0
+pending_stage_count: 5
+artifact_count: 0
+checkpoint_count: 0
+completed_stages: []
+pending_stages: []
+artifact_files: []
+---
+
+# {{title}}
+
+## Summary
+
+- Ops status: \`planned\`
+- Production mode: \`storyboard\`
+- Next stage: \`brief\`
+
+## Checkpoints
+
+## Artifact Files
+`;
+
+const RUNBOOK_NOTE = `# Operations Runbook
+
+## Core workflow
+
+1. Sync projects from \`vclaw-video-core\`
+2. Review \`Dashboard.md\`
+3. Open blocked or active project notes
+4. Update project state through CLI, then re-sync
+
+## Suggested cadence
+
+1. Morning: run \`vclaw video sync-obsidian\`
+2. Midday: review blocked projects
+3. End of day: re-sync and archive completed work
+`;
+
+const KANBAN_GUIDE = `# Board Guide
+
+Recommended Obsidian groupings:
+
+1. \`ops_status\`
+2. \`production_mode\`
+3. \`next_stage\`
+
+Recommended statuses:
+
+1. \`planned\`
+2. \`active\`
+3. \`needs-review\`
+4. \`blocked\`
+5. \`complete\`
+`;
+
+export async function scaffoldObsidianVault(
+  outputDir: string,
+): Promise<ObsidianVaultScaffoldResult> {
+  const root = resolve(outputDir);
+  const projectsDir = join(root, 'Projects');
+  const templatesDir = join(root, 'Templates');
+  const viewsDir = join(root, 'Views');
+  const dashboardPath = join(root, 'Dashboard.md');
+
+  await mkdir(projectsDir, { recursive: true });
+  await mkdir(templatesDir, { recursive: true });
+  await mkdir(viewsDir, { recursive: true });
+
+  await writeFile(dashboardPath, '# Production Dashboard\n\nRun `vclaw video sync-obsidian` to populate this vault.\n');
+  await writeFile(join(templatesDir, 'Project Template.md'), PROJECT_TEMPLATE);
+  await writeFile(join(viewsDir, 'Operations Runbook.md'), RUNBOOK_NOTE);
+  await writeFile(join(viewsDir, 'Board Guide.md'), KANBAN_GUIDE);
+
+  return {
+    root,
+    dashboardPath,
+    templatesDir,
+    viewsDir,
+  };
+}

package/src/video/outfit-prompts.ts

@@ -0,0 +1,14 @@
+/**
+ * Two-reference outfit swap. Order is FIXED: @image1 = outfit/pose,
+ * @image2 = character/identity. Reversing breaks the swap. Lean prompt only —
+ * NO cinema stack appended (the references carry the photographic register).
+ * Prompt-emitter only: the operator pastes this into the external image tool.
+ */
+export function outfitSwapPrompt(): string {
+  return 'Replace the character in @image1 with the character in @image2. Keep the outfit and pose from @image1 exactly. Match the face, bone structure, body type, skin tone, and hair from @image2. Even neutral mid-gray seamless background, soft large-source studio lighting, skin and outfit at their true natural tone against the neutral gray, natural film grain, full body framing.';
+}
+
+/** Step 1 of the two-step build: design the outfit on a bland generic model. */
+export function outfitBuildPrompt(outfit: string): string {
+  return `Build this outfit on a bland generic slim model (no specific identity): ${outfit}. The outfit is the only subject. Even neutral mid-gray seamless background, soft studio lighting, full body framing, natural film grain.`;
+}

package/src/video/outpaint-keyframe.ts

@@ -0,0 +1,365 @@
+/**
+ * outpaint-keyframe — pad a keyframe to a target canvas and build an
+ * inpainting mask for the new border region.
+ *
+ * Core (pad + mask) is pure/deterministic using only sharp.
+ * Fill is optional/scaffold: if a fill() factory is provided it calls the
+ * go-bananas REST edit endpoint; without a key it is inert.
+ */
+
+import sharp from 'sharp';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface OutpaintKeyframeInput {
+  /** Absolute path to the source keyframe image. */
+  inputPath: string;
+  /** Absolute path to write the output PNG. */
+  outputPath: string;
+  /** Target canvas width in pixels (default 1920). */
+  targetWidth?: number;
+  /** Target canvas height in pixels (default 1080). */
+  targetHeight?: number;
+  /**
+   * Dilation of the mask border into the original image region, expressed as
+   * a fraction of the smaller canvas dimension (default 0.03).
+   * E.g. on a 1920×1080 canvas, 0.03 × 1080 ≈ 32 px of feather overlap.
+   */
+  maskDilation?: number;
+  /**
+   * Optional fill function.  When provided it receives the padded PNG buffer
+   * and the mask PNG buffer; its returned Buffer is written to outputPath
+   * (filled:true).  When absent the padded letterbox image is written
+   * (filled:false).
+   */
+  fill?: (req: {
+    paddedPng: Buffer;
+    maskPng: Buffer;
+    env?: NodeJS.ProcessEnv;
+    fetcher?: typeof fetch;
+  }) => Promise<Buffer>;
+  env?: NodeJS.ProcessEnv;
+  fetcher?: typeof fetch;
+}
+
+export interface OutpaintKeyframeResult {
+  outputPath: string;
+  width: number;
+  height: number;
+  /** true when a fill() was provided and its output was written. */
+  filled: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Core implementation
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TARGET_WIDTH = 1920;
+const DEFAULT_TARGET_HEIGHT = 1080;
+const DEFAULT_MASK_DILATION_FRAC = 0.03;
+
+/**
+ * Pad `inputPath` onto a `targetWidth`×`targetHeight` canvas (centred,
+ * letterboxed, transparent background) and produce an L-mode mask PNG where
+ * the original image area is black (known region) and the padded border is
+ * white (region to fill).  An optional `fill()` factory can call an
+ * inpainting backend and receive the filled result.
+ */
+export async function outpaintKeyframe(
+  input: OutpaintKeyframeInput,
+): Promise<OutpaintKeyframeResult> {
+  const {
+    inputPath,
+    outputPath,
+    targetWidth = DEFAULT_TARGET_WIDTH,
+    targetHeight = DEFAULT_TARGET_HEIGHT,
+    maskDilation = DEFAULT_MASK_DILATION_FRAC,
+    fill,
+    env = process.env,
+    fetcher = fetch,
+  } = input;
+
+  if (!existsSync(inputPath)) {
+    throw new Error(`outpaint-keyframe: input file not found: ${inputPath}`);
+  }
+
+  // ------------------------------------------------------------------
+  // 1. Load source image metadata
+  // ------------------------------------------------------------------
+  const src = sharp(inputPath);
+  const meta = await src.metadata();
+  const srcW = meta.width ?? 0;
+  const srcH = meta.height ?? 0;
+  if (srcW === 0 || srcH === 0) {
+    throw new Error(`outpaint-keyframe: could not read dimensions from ${inputPath}`);
+  }
+
+  // ------------------------------------------------------------------
+  // 2. Compute centred placement on the target canvas
+  // ------------------------------------------------------------------
+  // Scale the source to fit inside the target, preserving aspect ratio.
+  const scaleX = targetWidth / srcW;
+  const scaleY = targetHeight / srcH;
+  const scale = Math.min(scaleX, scaleY, 1); // never upscale beyond 1:1
+
+  const fittedW = Math.round(srcW * scale);
+  const fittedH = Math.round(srcH * scale);
+  const offsetX = Math.floor((targetWidth - fittedW) / 2);
+  const offsetY = Math.floor((targetHeight - fittedH) / 2);
+
+  // ------------------------------------------------------------------
+  // 3. Build the padded (letterboxed) PNG
+  // ------------------------------------------------------------------
+  const resizedBuf = await sharp(inputPath)
+    .resize(fittedW, fittedH, { fit: 'fill' })
+    .png()
+    .toBuffer();
+
+  const paddedPng = await sharp({
+    create: {
+      width: targetWidth,
+      height: targetHeight,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  })
+    .composite([{ input: resizedBuf, left: offsetX, top: offsetY }])
+    .png()
+    .toBuffer();
+
+  // ------------------------------------------------------------------
+  // 4. Build the RGBA alpha mask PNG
+  //    alpha 0 (transparent) = border to fill, alpha 255 (opaque) = keep.
+  //    go-bananas proxies masked edits to OpenAI gpt-image-2, which reads ONLY
+  //    the mask's alpha channel (transparent = edit, opaque = preserve), so the
+  //    mask MUST be RGBA — a grayscale luminance mask is ignored by the model.
+  //    dilation shrinks the opaque (known) region by dilationPx on each side.
+  // ------------------------------------------------------------------
+  const dilationPx = Math.max(
+    0,
+    Math.round(maskDilation * Math.min(targetWidth, targetHeight)),
+  );
+
+  // Inner known rectangle (shrunk INWARD by dilationPx so the transparent fill
+  // region bites slightly into the original image, producing a smooth seam —
+  // standard inpainting convention). The known (opaque) rectangle is therefore
+  // smaller than the placed image by dilationPx on each side.
+  const innerLeft = Math.min(targetWidth, offsetX + dilationPx);
+  const innerTop = Math.min(targetHeight, offsetY + dilationPx);
+  const innerRight = Math.max(0, offsetX + fittedW - dilationPx);
+  const innerBottom = Math.max(0, offsetY + fittedH - dilationPx);
+  const innerW = innerRight - innerLeft;
+  const innerH = innerBottom - innerTop;
+
+  // Build the mask as a raw RGBA buffer: start fully transparent (fill
+  // everywhere), then stamp the inner known rectangle opaque (alpha 255) so the
+  // original image is preserved. RGB is irrelevant to the provider — only the
+  // alpha channel is read — so we leave it black (0,0,0).
+  const maskRaw = Buffer.alloc(targetWidth * targetHeight * 4, 0); // RGBA, transparent
+  for (let row = innerTop; row < innerBottom; row++) {
+    const rowBase = row * targetWidth;
+    for (let col = innerLeft; col < innerRight; col++) {
+      maskRaw[(rowBase + col) * 4 + 3] = 255; // opaque alpha = preserve
+    }
+  }
+
+  const maskPng = await sharp(maskRaw, {
+    raw: { width: targetWidth, height: targetHeight, channels: 4 },
+  })
+    .png()
+    .toBuffer();
+
+  // Suppress unused variable warning: innerW / innerH are derived above and
+  // document the composite geometry; kept for future callers.
+  void innerW;
+  void innerH;
+
+  // ------------------------------------------------------------------
+  // 5. Write output (filled or letterboxed)
+  // ------------------------------------------------------------------
+  await mkdir(dirname(outputPath), { recursive: true });
+
+  let filled = false;
+  if (fill) {
+    const filledBuf = await fill({ paddedPng, maskPng, env, fetcher });
+    await writeFile(outputPath, filledBuf);
+    filled = true;
+  } else {
+    await writeFile(outputPath, paddedPng);
+  }
+
+  return { outputPath, width: targetWidth, height: targetHeight, filled };
+}
+
+// ---------------------------------------------------------------------------
+// go-bananas outpaint fill factory
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_GO_BANANAS_API_BASE = 'https://gobananasai.com/api';
+
+/**
+ * Masked edits go through OpenAI gpt-image-2; go-bananas rejects mask_image_id
+ * for any non-OpenAI model, so this is the only valid default.
+ */
+export const DEFAULT_OUTPAINT_MODEL_ID = 'openai-gpt-image-2';
+
+export const DEFAULT_OUTPAINT_PROMPT =
+  'Outpaint and naturally extend the scene into the transparent border ' +
+  'region. Seamlessly continue the existing lighting, colour, perspective, ' +
+  'textures and composition out to the new edges. Photorealistic, coherent ' +
+  'continuation with no visible seam, no new subjects, no added text, no ' +
+  'frame or border.';
+
+export interface GoBananasOutpaintFillOptions {
+  /** Outpaint instruction sent to the edit model (default DEFAULT_OUTPAINT_PROMPT). */
+  prompt?: string;
+  /**
+   * Edit model id. Must be an OpenAI model for masked edits (go-bananas refuses
+   * mask_image_id otherwise). Default DEFAULT_OUTPAINT_MODEL_ID.
+   */
+  modelId?: string;
+  /** Optional explicit output size (e.g. '1536x1024'); omitted = provider default. */
+  size?: string;
+}
+
+interface GoBananasFillRequest {
+  paddedPng: Buffer;
+  maskPng: Buffer;
+  env?: NodeJS.ProcessEnv;
+  fetcher?: typeof fetch;
+}
+
+/**
+ * Upload one PNG buffer to go-bananas' multipart edit-upload endpoint and
+ * return its stored image id.
+ *
+ * POST {apiBase}/images/upload  (multipart/form-data, field `file`)
+ *   → 201 { image_id, public_url, ... }
+ */
+async function uploadForEditing(
+  png: Buffer,
+  fileName: string,
+  apiBase: string,
+  apiKey: string,
+  fetcher: typeof fetch,
+): Promise<number> {
+  const form = new FormData();
+  // NOTE: do NOT set Content-Type — FormData sets the multipart boundary.
+  form.append('file', new Blob([new Uint8Array(png)], { type: 'image/png' }), fileName);
+
+  const res = await fetcher(`${apiBase}/images/upload`, {
+    method: 'POST',
+    headers: { 'X-API-Key': apiKey },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '(no body)');
+    throw new Error(`go-bananas upload (${fileName}) HTTP ${res.status}: ${text}`);
+  }
+
+  const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const id =
+    (json.image_id as number | undefined) ??
+    (json.imageId as number | undefined) ??
+    ((json.data as Record<string, unknown> | undefined)?.image_id as number | undefined);
+  if (typeof id !== 'number' || !Number.isFinite(id)) {
+    throw new Error(
+      `go-bananas upload (${fileName}): no image_id in response: ${JSON.stringify(json).slice(0, 200)}`,
+    );
+  }
+  return id;
+}
+
+/** Pull the downloadable result URL out of the edit-image response (shape-tolerant). */
+function extractOutpaintResultUrl(json: Record<string, unknown>): string | undefined {
+  const data = json.data as Record<string, unknown> | undefined;
+  const candidates = [
+    json.fullUrl,
+    json.full_url,
+    json.url,
+    json.imageUrl,
+    json.image_url,
+    data?.fullUrl,
+    data?.full_url,
+    data?.url,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) return c;
+  }
+  return undefined;
+}
+
+/**
+ * Build a fill() function that performs a go-bananas masked outpaint via the
+ * upload×2 → edit-by-id → download flow (verified against the live API):
+ *
+ *   1. POST {apiBase}/images/upload  (padded source PNG) → image_id
+ *   2. POST {apiBase}/images/upload  (RGBA alpha mask PNG) → mask_image_id
+ *   3. POST {apiBase}/edit-image     { image_id, mask_image_id, model_id, prompt, size? }
+ *        → { fullUrl, ... }
+ *   4. GET  fullUrl → filled image bytes (returned as a Buffer)
+ *
+ *   - apiBase from env GO_BANANAS_API_URL (default https://gobananasai.com/api)
+ *   - apiKey  from env GO_BANANAS_API_KEY (throws env_var_missing when absent,
+ *     so the factory is inert in offline / CI contexts)
+ *   - injectable fetcher for offline testing
+ */
+export function goBananasOutpaintFill(
+  options: GoBananasOutpaintFillOptions = {},
+): (req: GoBananasFillRequest) => Promise<Buffer> {
+  return async ({ paddedPng, maskPng, env = process.env, fetcher = fetch }) => {
+    const apiKey = env.GO_BANANAS_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'env_var_missing: GO_BANANAS_API_KEY is required for go-bananas outpaint fill',
+      );
+    }
+    const apiBase = env.GO_BANANAS_API_URL?.trim() || DEFAULT_GO_BANANAS_API_BASE;
+    const prompt = options.prompt?.trim() || DEFAULT_OUTPAINT_PROMPT;
+    const modelId = options.modelId?.trim() || DEFAULT_OUTPAINT_MODEL_ID;
+
+    // 1 + 2. Upload the padded source and the alpha mask, get their stored ids.
+    const imageId = await uploadForEditing(paddedPng, 'padded.png', apiBase, apiKey, fetcher);
+    const maskImageId = await uploadForEditing(maskPng, 'mask.png', apiBase, apiKey, fetcher);
+
+    // 3. Edit-by-id with the mask. mask_image_id requires an OpenAI model.
+    const editBody: Record<string, unknown> = {
+      image_id: imageId,
+      mask_image_id: maskImageId,
+      model_id: modelId,
+      prompt,
+    };
+    if (options.size) editBody.size = options.size;
+
+    const editRes = await fetcher(`${apiBase}/edit-image`, {
+      method: 'POST',
+      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify(editBody),
+    });
+    if (!editRes.ok) {
+      const text = await editRes.text().catch(() => '(no body)');
+      throw new Error(`go-bananas edit-image HTTP ${editRes.status}: ${text}`);
+    }
+
+    const editJson = (await editRes.json().catch(() => ({}))) as Record<string, unknown>;
+    const resultUrl = extractOutpaintResultUrl(editJson);
+    if (!resultUrl) {
+      throw new Error(
+        `go-bananas edit-image: no result URL in response: ${JSON.stringify(editJson).slice(0, 300)}`,
+      );
+    }
+
+    // 4. Download the filled image.
+    const dl = await fetcher(resultUrl, {});
+    if (!dl.ok) {
+      throw new Error(`go-bananas outpaint download HTTP ${dl.status} for ${resultUrl}`);
+    }
+    return Buffer.from(await dl.arrayBuffer());
+  };
+}

package/src/video/pipeline-manifest.ts

@@ -0,0 +1,16 @@
+import storyboardManifest from './pipeline-manifests/storyboard.json' with { type: 'json' };
+import directorManifest from './pipeline-manifests/director.json' with { type: 'json' };
+import type { VideoPipelineManifest, VideoProductionMode } from './types.js';
+
+const BUILTIN_PIPELINE_MANIFESTS: Record<VideoProductionMode, VideoPipelineManifest> = {
+  storyboard: storyboardManifest as VideoPipelineManifest,
+  director: directorManifest as VideoPipelineManifest,
+};
+
+export function getBuiltinPipelineManifest(mode: VideoProductionMode): VideoPipelineManifest {
+  return BUILTIN_PIPELINE_MANIFESTS[mode];
+}
+
+export function listBuiltinPipelineManifests(): VideoPipelineManifest[] {
+  return Object.values(BUILTIN_PIPELINE_MANIFESTS);
+}

package/src/video/pipeline-manifests/director.json

@@ -0,0 +1,46 @@
+{
+  "name": "director",
+  "version": "1.0.0",
+  "productionMode": "director",
+  "stages": [
+    {
+      "name": "brief",
+      "produces": ["brief"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["brief artifact exists"]
+    },
+    {
+      "name": "storyboard",
+      "requiredArtifactsIn": ["brief"],
+      "produces": ["storyboard"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["director beat plan exists"]
+    },
+    {
+      "name": "assets",
+      "requiredArtifactsIn": ["storyboard"],
+      "produces": ["asset-manifest"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": false,
+      "successCriteria": ["asset manifest exists"]
+    },
+    {
+      "name": "review",
+      "requiredArtifactsIn": ["asset-manifest"],
+      "produces": ["review-report"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["review verdict is explicit"]
+    },
+    {
+      "name": "publish",
+      "requiredArtifactsIn": ["review-report"],
+      "produces": ["publish-report"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["publish readiness is explicit"]
+    }
+  ]
+}

package/src/video/pipeline-manifests/storyboard.json

@@ -0,0 +1,46 @@
+{
+  "name": "storyboard",
+  "version": "1.0.0",
+  "productionMode": "storyboard",
+  "stages": [
+    {
+      "name": "brief",
+      "produces": ["brief"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["brief artifact exists"]
+    },
+    {
+      "name": "storyboard",
+      "requiredArtifactsIn": ["brief"],
+      "produces": ["storyboard"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["storyboard scenes exist"]
+    },
+    {
+      "name": "assets",
+      "requiredArtifactsIn": ["storyboard"],
+      "produces": ["asset-manifest"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": false,
+      "successCriteria": ["asset manifest exists"]
+    },
+    {
+      "name": "review",
+      "requiredArtifactsIn": ["asset-manifest"],
+      "produces": ["review-report"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["review verdict is explicit"]
+    },
+    {
+      "name": "publish",
+      "requiredArtifactsIn": ["review-report"],
+      "produces": ["publish-report"],
+      "checkpointRequired": true,
+      "humanApprovalDefault": true,
+      "successCriteria": ["publish readiness is explicit"]
+    }
+  ]
+}

package/src/video/platform-specs.ts

@@ -0,0 +1,50 @@
+/**
+ * platform-specs.ts — deterministic per-platform delivery spec table.
+ *
+ * The asset-format analogue of cinematography.ts `--detail` levels: a pure,
+ * no-LLM lookup mapping a social/ad platform id to its aspect ratio and copy
+ * word-caps, so campaign output is correct-by-construction (right dimensions,
+ * platform-appropriate copy length + tone).
+ *
+ * Concept (not code) adapted from the MIT-licensed Open-Pomelli `platforms.ts`.
+ * A `bodyMaxWords`/`ctaMaxWords` of 0 means that surface suppresses that copy
+ * slot (e.g. a thumbnail has a headline but no body).
+ */
+
+export type PlatformAspect = '16:9' | '9:16' | '1:1' | '4:5';
+
+export interface PlatformSpec {
+  id: string;
+  label: string;
+  aspect: PlatformAspect;
+  headlineMaxWords: number;
+  bodyMaxWords: number;
+  ctaMaxWords: number;
+  tone: string;
+}
+
+const SPECS: readonly PlatformSpec[] = [
+  { id: 'tiktok', label: 'TikTok', aspect: '9:16', headlineMaxWords: 8, bodyMaxWords: 22, ctaMaxWords: 4, tone: 'native, fast, conversational' },
+  { id: 'instagram-reel', label: 'Instagram Reel', aspect: '9:16', headlineMaxWords: 8, bodyMaxWords: 22, ctaMaxWords: 4, tone: 'aspirational, punchy' },
+  { id: 'instagram-post', label: 'Instagram Post', aspect: '1:1', headlineMaxWords: 10, bodyMaxWords: 30, ctaMaxWords: 4, tone: 'aspirational, polished' },
+  { id: 'youtube-short', label: 'YouTube Short', aspect: '9:16', headlineMaxWords: 8, bodyMaxWords: 20, ctaMaxWords: 4, tone: 'hooky, high-energy' },
+  { id: 'youtube-thumb', label: 'YouTube Thumbnail', aspect: '16:9', headlineMaxWords: 6, bodyMaxWords: 0, ctaMaxWords: 0, tone: 'bold, curiosity-driving' },
+  { id: 'linkedin', label: 'LinkedIn', aspect: '1:1', headlineMaxWords: 12, bodyMaxWords: 40, ctaMaxWords: 5, tone: 'credible, professional' },
+  { id: 'facebook', label: 'Facebook', aspect: '1:1', headlineMaxWords: 10, bodyMaxWords: 30, ctaMaxWords: 5, tone: 'clear, friendly' },
+  { id: 'x', label: 'X / Twitter', aspect: '16:9', headlineMaxWords: 10, bodyMaxWords: 28, ctaMaxWords: 4, tone: 'sharp, concise' },
+  { id: 'banner', label: 'Web Banner', aspect: '16:9', headlineMaxWords: 6, bodyMaxWords: 12, ctaMaxWords: 3, tone: 'direct, benefit-led' },
+];
+
+const BY_ID = new Map(SPECS.map((spec) => [spec.id, spec]));
+
+export function getPlatformSpec(id: string): PlatformSpec | undefined {
+  return BY_ID.get(id.toLowerCase());
+}
+
+export function listPlatformSpecs(): PlatformSpec[] {
+  return SPECS.map((spec) => ({ ...spec }));
+}
+
+export function platformIds(): string[] {
+  return SPECS.map((spec) => spec.id);
+}

package/src/video/playbooks.ts

@@ -0,0 +1,34 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface VideoPlaybook {
+  name: string;
+  provider: 'veo' | 'seedance';
+  useWhen: string[];
+  promptFormula: string[];
+  constraints: string[];
+  adaptationChecklist: string[];
+}
+
+function playbooksDir(root = process.cwd()): string {
+  return join(resolve(root), 'playbooks');
+}
+
+export async function listPlaybooks(root = process.cwd()): Promise<string[]> {
+  const dir = playbooksDir(root);
+  if (!existsSync(dir)) return [];
+  return (await readdir(dir))
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => entry.replace(/\.json$/, ''))
+    .sort();
+}
+
+export async function readPlaybook(
+  name: string,
+  root = process.cwd(),
+): Promise<VideoPlaybook | null> {
+  const path = join(playbooksDir(root), `${name}.json`);
+  if (!existsSync(path)) return null;
+  return JSON.parse(await readFile(path, 'utf-8')) as VideoPlaybook;
+}