broll: Instructions file for Claude Code

broll — architecture rules

broll is an MCP server that gives coding agents content-production hands: BYO-key generation, deterministic rendering, draft-first publishing. These rules are binding for all changes.

Non-negotiables

1. The model plans; code renders. Anything that must look consistent (layout, fonts, spacing, captions, branding) lives in TypeScript, never in a prompt. If AI output drifts, the fix is moving that part into code.
2. Determinism. compilePlan and slideOverlaySvg are pure functions: same inputs → same ffmpeg args / same SVG. No Date.now(), no randomness in render paths. IDs come from the injectable IdGenerator.
3. Draft-first publishing. No code path may post to a network without (a) a draft file existing in the outbox and (b) confirm: true from the caller. Never weaken this.
4. BYO keys only. Keys are read from env, sent only to their vendor's API, never logged, never proxied.
5. Errors must be actionable. Every thrown error tells the agent what to do next (which tool to call, which env var to set). ffmpeg failures include the stderr tail.

Layout

• src/config.ts — env + broll.config.json (brand kit). zod-validated.
• src/workspace.ts — on-disk state: assets/renders/drafts/tmp + manifest. All tool outputs are inspectable files.
• src/render/ — the crown jewel. plan.ts compiles declarative RenderPlans to ffmpeg args (pure); renderer.ts is the only orchestrator; ffmpeg.ts is the only place a process spawns; carousel.ts composes slides via sharp+SVG.
• src/providers/ — Strategy pattern. registry.ts picks explicit → config default → first configured → mock. The mock provider must always keep every workflow runnable keyless.
• src/social/ — Adapter pattern per platform + constraints.ts (validate before publish) + drafts.ts (outbox) + publisher.ts (per-platform results, never all-or-nothing).
• src/server.ts — thin MCP tool wrappers only; logic lives in services. src/broll.ts is the composition root.