agentic-ads-engine 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentic-ads-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# agentic-ads-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline tools for ad drafts. Node 20 or later. Plain JavaScript ESM with JSDoc, no build step, and zero runtime dependencies.
+
+## Quick start
+
+Run from this checkout:
+
+```sh
+node bin/agentic-ads list-templates
+node bin/agentic-ads list-hooks
+node bin/agentic-ads lint --copy 'Browse available listings'
+node bin/agentic-ads plan --site demo --goal discovery --dry-run
+node test/e2e.mjs
+```
+
+The package is not published by this task. To install the local package:
+
+```sh
+npm install /path/to/agentic-ads-engine
+npx agentic-ads plan
+```
+
+CLI output is JSON. Exit codes: `0` for a result, `1` for invalid input, and `2` for blocked copy.
+`lint` requires `--copy`. It accepts `--category housing|none`; the default is `housing`.
+`plan` accepts `--site`, `--goal`, `--template`, `--ratio`, `--copy`, and `--category`.
+Use `--option=value` for values that start with `--`: `node bin/agentic-ads lint --copy=--Sale--`.
+This form preserves `=` inside values. Boolean options accept `=true` or `=false`; plans still require dry-run.
+Site names are lowercase slugs. Ratios are `4:5` and `9:16`.
+
+Plans default to dry-run. `--apply` always fails because this slice has no spending or launch implementation.
+Plans return required slots and policy findings. They do not render an image.
+The five templates cover door reveals, first-person UGC, before/after views, news frames, and help with timing.
+Their slots and story beats differ. The HTML stub uses a shared text layout.
+
+## Library
+
+```js
+import {
+  readScores, writeScores, selectFor, templateProvider, guardCost,
+} from 'agentic-ads-engine';
+
+await writeScores('./scores', 'demo', { help: 8 });
+const scores = await readScores('./scores', 'demo');
+const hook = selectFor({ id: 'demo', scores }, 'discovery');
+
+const preview = templateProvider.run({
+  template: 'door-open-teaser',
+  ratio: '4:5',
+  brand: { name: 'Demo', primary: '#2455cc' },
+  slots: {
+    headline: 'Take a closer look',
+    detail: 'Review the available listing details',
+    cta: 'Browse listings',
+  },
+});
+console.log(hook.id, preview.mime); // help text/html
+```
+
+`selectFor(site, goal)` is pure. Supply `{ id, scores }`; it never reads the store itself.
+Only low-risk hooks qualify. Scores rank matching hooks; catalog order resolves ties.
+No match returns `null`. Scores are finite, nonnegative numbers keyed by known hook IDs.
+The caller defines the score metric. This slice does not measure performance or establish sample confidence.
+CLI and MCP plans use cold-start scores. Load saved scores through the library when selecting hooks.
+
+The file store writes one JSON snapshot per site. Replacement is atomic; callers must use one writer.
+A missing file returns `{}`. Invalid files fail. Store directories must be trusted local directories.
+
+Providers implement `capabilities()`, `estimate(input)`, and `run(input)`.
+The stub returns escaped HTML, dimensions, a content hash, zero cost, and an explicit warning.
+It returns `image: null`. It has no browser, remote asset loading, image generation, or raster conversion.
+Brand colors accept six-digit hex values. The brand name is plain text.
+Use the template descriptor to find required slots before calling the provider.
+Call `lint` on every final slot value before external use. The renderer does not grant policy approval.
+
+`guardCost` accepts `costMinor`, `adSpentMinor`, `monthSpentMinor`, `perAdMinor`, `perMonthMinor`, and `apply`.
+All amounts must be nonnegative safe integers in the same currency.
+Positive cost requires `apply: true`. Equal-to-cap amounts are allowed; excess amounts are blocked.
+The caller supplies totals for the current calendar month, including reserved and uncertain charges.
+This pure guard does not persist reservations, handle concurrency, reset monthly totals, or authorize a paid provider.
+A future paid adapter must check and reserve costs atomically before calling a provider.
+
+## MCP
+
+Start `node bin/agentic-ads-mcp`, or use the installed `agentic-ads-mcp` executable.
+Configure the client to use this command with stdio transport.
+The server uses newline-delimited JSON-RPC and protocol version `2024-11-05`.
+It supports `initialize`, `ping`, `tools/list`, and `tools/call`.
+The original four tools use the same names and arguments as the CLI; `--dry-run` becomes `dryRun`.
+Stdout contains protocol messages only. Frames are limited to 65,536 characters.
+Tool results contain JSON text. Blocked copy sets `isError: true` and retains its findings.
+
+## Honest limits
+
+Lint detects selected English patterns. It cannot prove truth, consent, disclosure quality, or compliance.
+It always returns a human review finding. A `review` status does not mean platform approval.
+Housing is the conservative default. Targeting words, guarantees, superlatives, and below-market percentages are blocked.
+News framing, staging, and urgency also require review. Conservative checks can produce false positives.
+The package does not inspect actual audience settings or implement current platform policy in full.
+
+Keep private data out of inputs. Contact-pattern checks are incomplete; they cannot reliably detect names, addresses, or secrets.
+The CLI prints supplied copy in plans. No telemetry, account integration, credentials, or network calls are included.
+No source assets or competitor copy are bundled. Research informs the formats and disclosure needs only.
+
+The E2E script spawns both executables and a library integration process.
+It records assertions in `test/artifacts/e2e.json`, which Git ignores and npm excludes.
+Run `npm run ci:local` before any future push. Publishing and pushing are separate operator actions.
+
+## Video formats
+
+```sh
+node bin/agentic-ads formats
+node bin/agentic-ads formats --cost-class cheap --risk medium
+node bin/agentic-ads formats show sitcom
+node bin/agentic-ads plan --format sitcom --site demo
+```
+
+Twelve formats cover the eight catalog recipes, lo-fi UGC, sitcom, storytime, and talking objects.
+MCP adds `list_formats({costClass?, risk?})`, `get_format({id})`, and `plan_format({format, site, goal?, dryRun?})`.
+These tools return the same JSON as the commands above.
+The library exports `listFormats`, `getFormat`, and `planFormat` from the package root and `agentic-ads-engine/formats`.
+Filters combine with AND. Unknown formats fail. Format plans require a site slug and default to dry-run.
+Plans return ordered stages, stage estimates, total estimates, policy notes, QA gates, and zero actual spend.
+Apply remains unavailable. QA gates describe required checks; this planner does not run them.
+
+Source paths refer to the supplied `directory/ads-research` archive, reviewed on 2026-11-12.
+Provider `verified` records that source review date. It does not promise current prices or successful renders.
+`unverified: true` marks proposed routes or unresolved quality. Local routes can name tools instead of models.
+Costs exclude labour and compute. Stage notes state asset counts and reuse assumptions.
+The sitcom run cost $2.466; four mouth checks still failed. Its selected speech model preserves that limitation.
+Lo-fi costs reference reused assets: $0.881 for three videos6 ads and $0.165 for three videos5 voice edits.
+Fresh generation estimates differ. The style catalog did not render its recommended local recipes.
+No paid calls, current price checks, media QA, or platform approval occur here.
+
+Run `node test/mutate-formats.mjs` to repeat the three deliberate faults and restore the files.
+It records failures and the restored pass in `test/artifacts/formats-mutations.json`.

package/bin/agentic-ads

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { execute, tools } from '../src/index.js';
+try {
+  let [action, ...argv] = process.argv.slice(2);
+  const args = {};
+  if (action === 'formats') {
+    action = argv[0] === 'show' ? 'get_format' : 'list_formats';
+    if (action === 'get_format') { argv.shift(); args.id = argv.shift(); }
+  }
+  if (action === 'plan' && argv.some(arg => arg === '--format' || arg.startsWith('--format='))) action = 'plan_format';
+  const schema = tools.find(t => t.name === action)?.inputSchema;
+  if (!schema) throw new Error('Use formats, list-templates, list-hooks, lint, or plan');
+  while (argv.length) {
+    const option = argv.shift(), separator = option.indexOf('=');
+    const flag = separator < 0 ? option : option.slice(0, separator);
+    const value = separator < 0 ? undefined : option.slice(separator + 1);
+    if (!flag.startsWith('--')) throw new Error('Expected an option');
+    const key = flag === '--dry-run' ? 'dryRun' : flag === '--cost-class' ? 'costClass' : flag.slice(2);
+    if (flag === '--apply' && ['plan', 'plan_format'].includes(action)) throw new Error('Apply is unavailable in this offline slice');
+    if (['--costClass', '--dryRun'].includes(flag) || !Object.hasOwn(schema.properties, key) || Object.hasOwn(args, key)) throw new Error('Unknown or repeated option');
+    if (schema.properties[key].type === 'boolean') {
+      if (value !== undefined && !['true', 'false'].includes(value)) throw new Error('Invalid argument');
+      args[key] = value !== 'false';
+    }
+    else if (value !== undefined) args[key] = value;
+    else {
+      if (!argv.length || argv[0].startsWith('--')) throw new Error(`Missing option value (use ${flag}=VALUE for a value that starts with --)`);
+      args[key] = argv.shift();
+    }
+  }
+  const result = execute(action, args);
+  console.log(JSON.stringify(result));
+  if (result.status === 'blocked' || result.policy?.status === 'blocked') process.exitCode = 2;
+} catch (error) {
+  console.log(JSON.stringify({ error: error.message })); process.exitCode = 1;
+}

package/bin/agentic-ads-mcp

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { execute, tools } from '../src/index.js';
+// MCP stdio uses one JSON-RPC message per line. stdout is protocol-only.
+const send = message => process.stdout.write(JSON.stringify(message) + '\n');
+const fail = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+let initialized = false;
+function receive(line) {
+  let request;
+  try { request = JSON.parse(line); } catch { fail(null, -32700, 'Parse error'); return; }
+  const validId = request && (typeof request.id === 'string' || (typeof request.id === 'number' && Number.isFinite(request.id)));
+  if (!request || Array.isArray(request) || request.jsonrpc !== '2.0' || typeof request.method !== 'string' ||
+      (Object.hasOwn(request, 'id') && !validId)) { fail(null, -32600, 'Invalid request'); return; }
+  if (!Object.hasOwn(request, 'id')) return;
+  const { id, method, params = {} } = request;
+  if (!params || typeof params !== 'object' || Array.isArray(params)) { fail(id, -32602, 'Invalid params'); return; }
+  let result;
+  if (method === 'initialize') {
+    if (typeof params.protocolVersion !== 'string') { fail(id, -32602, 'Missing protocol version'); return; }
+    initialized = true;
+    result = { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'agentic-ads-engine', version: '0.1.0' } };
+  } else if (method === 'ping') result = {};
+  else if (!initialized) { fail(id, -32002, 'Initialize first'); return; }
+  else if (method === 'tools/list') result = { tools };
+  else if (method === 'tools/call') {
+    if (typeof params.name !== 'string' || !tools.some(t => t.name === params.name)) { fail(id, -32602, 'Unknown tool'); return; }
+    try {
+      const value = execute(params.name, params.arguments === undefined ? {} : params.arguments);
+      result = { content: [{ type: 'text', text: JSON.stringify(value) }], isError: value.status === 'blocked' || value.policy?.status === 'blocked' };
+    } catch (error) { result = { content: [{ type: 'text', text: error.message }], isError: true }; }
+  } else { fail(id, -32601, 'Method not found'); return; }
+  send({ jsonrpc: '2.0', id, result });
+}
+let buffer = '', dropping = false;
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  // Bound each frame to prevent unbounded buffering from a malformed client.
+  for (const part of chunk.split(/(?<=\n)/)) {
+    if (!dropping) buffer += part;
+    if (buffer.length > 65536) { buffer = ''; dropping = true; fail(null, -32600, 'Frame too large'); }
+    if (part.endsWith('\n')) {
+      if (!dropping && buffer.trim()) receive(buffer);
+      buffer = ''; dropping = false;
+    }
+  }
+});
+process.stdin.on('end', () => { if (buffer.trim() && !dropping) receive(buffer); });

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "agentic-ads-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Offline ad templates, hook selection, policy lint, and planning tools",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "exports": { ".": "./src/index.js", "./formats": "./src/formats/index.js", "./templates": "./src/templates/index.js", "./hooks": "./src/hooks/index.js", "./policy": "./src/policy/index.js", "./providers": "./src/providers/index.js" },
+  "bin": { "agentic-ads": "./bin/agentic-ads", "agentic-ads-mcp": "./bin/agentic-ads-mcp" },
+  "files": ["src/", "bin/", "README.md", "LICENSE"],
+  "scripts": { "test": "node test/e2e.mjs", "ci:local": "node test/e2e.mjs" },
+  "publishConfig": { "access": "public" }
+}

package/src/formats/index.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+const library = JSON.parse(readFileSync(new URL('./library.json', import.meta.url), 'utf8'));
+const costs = ['free', 'cheap', 'mid', 'expensive'], risks = ['low', 'medium', 'high'];
+function argumentsFor(value, keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !keys.includes(k))) throw new Error('Invalid format arguments');
+}
+/** Return isolated descriptors. Filters combine with AND. No providers run. */
+export function listFormats(filter = {}) {
+  argumentsFor(filter, ['costClass', 'risk']);
+  if (filter.costClass !== undefined && !costs.includes(filter.costClass)) throw new Error('Invalid cost class');
+  if (filter.risk !== undefined && !risks.includes(filter.risk)) throw new Error('Invalid risk');
+  return structuredClone(library.filter(f => (!filter.costClass || f.costClass === filter.costClass) && (!filter.risk || f.policyRisk === filter.risk)));
+}
+export function getFormat(id) {
+  const found = library.find(f => f.id === id);
+  if (!found) throw new Error('Unknown format: ' + String(id));
+  return structuredClone(found);
+}
+/** Costs describe a possible production run, never money spent by this planner. */
+export function planFormat(input = {}) {
+  argumentsFor(input, ['format', 'site', 'goal', 'dryRun', 'apply']);
+  if (input.apply !== undefined && input.apply !== false) throw new Error('Apply is unavailable');
+  if (input.dryRun !== undefined && input.dryRun !== true) throw new Error('Use dry-run; apply is unavailable');
+  const f = getFormat(input.format);
+  if (typeof input.site !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.site) || input.site.length > 80) throw new Error('Site must be a lowercase slug');
+  const goal = input.goal ?? 'discovery';
+  if (typeof goal !== 'string' || !goal.trim() || goal.length > 200) throw new Error('Invalid goal');
+  const stages = f.stages.map(id => ({ id, provider: f.providers[id], estimatedCostUsd: f.providers[id].estimatedCostUsd }));
+  const sum = key => Math.round(stages.reduce((n, s) => n + s.estimatedCostUsd[key], 0) * 1000) / 1000;
+  return { format: f.id, site: input.site, goal, dryRun: true, applied: false, spendUsd: 0, stages,
+    qaGates: f.qaGates, policyRisk: f.policyRisk, riskNotes: f.riskNotes,
+    total: { low: sum('low'), high: sum('high'), note: f.estimatedCostUsd.note },
+    warnings: ['Plan only; no providers or QA checks run.', 'Historical source review dates are not current price verification.'] };
+}

package/src/formats/library.json

@@ -0,0 +1,206 @@
+[
+  {
+    "id": "screen-voiceover",
+    "name": "Screen recording + voiceover",
+    "description": "Record a real or generic checklist UI with timed narration.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "Cursor clicks the key step on frame one.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people or brands."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Record only generic UI; exclude real addresses and prices.", "Cut on measured voice beats; dead air must stay below 0.4 seconds."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  },
+  {
+    "id": "text-broll",
+    "name": "Text over b-roll",
+    "description": "Animate exact caption cards over supplied moving footage.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "Bold hook text appears on frame one.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0.02, "note": "estimate: supplied art or 1 text-to-image still at $0.020; videos6/spend.json and videos4/spend.json"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "cheap",
+    "estimatedCostUsd": {"low": 0, "high": 0.02, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people or brands."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Render text as HTML overlays, never generated pixels.", "Use at most eight words per card; hold the end card for 1.5 seconds."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "videos6/spend.json", "videos4/spend.json"]
+  },
+  {
+    "id": "whiteboard",
+    "name": "Whiteboard doodle",
+    "description": "Draw SVG ideas to narration word times.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "The marker draws before the first word ends.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people or brands."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Use a faceless renderer; the whiteboard face recipe needs a face plate.", "Trigger strokes within three frames of their words; avoid static boards over two seconds."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  },
+  {
+    "id": "stickman",
+    "name": "Stickman explainer",
+    "description": "Animate a shared SVG character through a problem and answer.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "The figure moves under a question mark in the first second.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people or brands."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Reuse one SVG character asset for consistent proportions.", "Include motion every two seconds; avoid holds over 2.5 seconds."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  },
+  {
+    "id": "pov",
+    "name": "POV discovery",
+    "description": "Use consistent first-person clips with a title and checklist reveal.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "POV title and moving hands appear on frame one.",
+    "stages": ["script", "set", "character", "still", "angle_still", "tts", "image_to_video", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "set": {"model": "reuse supplied set", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "character": {"model": "reuse character bible", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.02, "high": 0.06, "note": "estimate: 1-3 text-to-image stills at $0.020; videos6/spend.json and videos4/spend.json"}}, "angle_still": {"model": "bytedance/seedream-v5.5/edit", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.056, "high": 0.196, "note": "estimate: 2-7 image edits at $0.028; sitcom3/spend.json, videos6/spend.json, videos4/spend.json"}}, "tts": {"model": "wavespeed-ai/qwen3-tts/text-to-speech", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.03, "high": 0.055, "note": "estimate: 6-11 calls at $0.005; sitcom3/spend.json, videos5/spend.json, videos4/spend.json"}}, "image_to_video": {"model": "wavespeed-ai/wan-2.2/i2v-480p-ultra-fast", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.15, "high": 0.3, "note": "estimate: 3-6 five-second clips at $0.05; sitcom3/spend.json, videos4/spend.json, videos6/spend.json"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "mid",
+    "estimatedCostUsd": {"low": 0.256, "high": 0.611, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Use a DRAMATIZATION label for fictional people and skits.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "continuity", "words_per_second", "black_corners", "eyes"],
+    "learned": ["Chain the final frame into the next shot for continuity.", "Cut on voice beats; keep real listing data out of backgrounds."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "videos6/spend.json", "videos4/spend.json", "sitcom3/spend.json", "videos5/spend.json"]
+  },
+  {
+    "id": "telestrator",
+    "name": "Telestrator annotation",
+    "description": "Circle relevant UI details with word-timed SVG strokes.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "The pen circles the problem in the first second.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people or brands."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Keep annotations clear of the element they explain.", "Use deterministic strokes to avoid drift between frames."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  },
+  {
+    "id": "before-after",
+    "name": "Before and after",
+    "description": "Wipe from confusing paperwork to an actual checklist.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "A split wipe begins on frame one.",
+    "stages": ["script", "set", "character", "still", "angle_still", "tts", "image_to_video", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "set": {"model": "reuse supplied set", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "character": {"model": "reuse character bible", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.02, "high": 0.06, "note": "estimate: 1-3 text-to-image stills at $0.020; videos6/spend.json and videos4/spend.json"}}, "angle_still": {"model": "bytedance/seedream-v5.5/edit", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.056, "high": 0.196, "note": "estimate: 2-7 image edits at $0.028; sitcom3/spend.json, videos6/spend.json, videos4/spend.json"}}, "tts": {"model": "wavespeed-ai/qwen3-tts/text-to-speech", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.03, "high": 0.055, "note": "estimate: 6-11 calls at $0.005; sitcom3/spend.json, videos5/spend.json, videos4/spend.json"}}, "image_to_video": {"model": "wavespeed-ai/wan-2.2/i2v-480p-ultra-fast", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.15, "high": 0.3, "note": "estimate: 3-6 five-second clips at $0.05; sitcom3/spend.json, videos4/spend.json, videos6/spend.json"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "mid",
+    "estimatedCostUsd": {"low": 0.256, "high": 0.611, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Use a DRAMATIZATION label for fictional people and skits.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "continuity", "words_per_second", "black_corners", "eyes"],
+    "learned": ["Align both views before the wipe; match their colour grade.", "Show an achievable checklist result, never promised savings."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "videos6/spend.json", "videos4/spend.json", "sitcom3/spend.json", "videos5/spend.json"]
+  },
+  {
+    "id": "news-parody",
+    "name": "News parody",
+    "description": "Use branded news cards with sourced facts and narration.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "A sting and branded headline start on frame one.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Label parody; do not impersonate a real news outlet.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation"],
+    "learned": ["Trace every fact to a source; never imply a real outlet endorsement.", "Use generic branding and make the parody clear."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  },
+  {
+    "id": "lo-fi",
+    "name": "Handheld lo-fi UGC",
+    "description": "Use synthetic handheld scenes and narration with fast reaction cuts.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "A character is already talking or reacting with camera motion.",
+    "stages": ["script", "set", "character", "still", "angle_still", "tts", "image_to_video", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "set": {"model": "reuse supplied set", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "character": {"model": "reuse character bible", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.02, "high": 0.06, "note": "estimate: 1-3 text-to-image stills at $0.020; videos6/spend.json and videos4/spend.json"}}, "angle_still": {"model": "bytedance/seedream-v5.5/edit", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.056, "high": 0.196, "note": "estimate: 2-7 image edits at $0.028; sitcom3/spend.json, videos6/spend.json, videos4/spend.json"}}, "tts": {"model": "wavespeed-ai/qwen3-tts/voice-design", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.03, "high": 0.08, "note": "estimate: 6-16 calls at $0.005; videos6/spend.json; includes regenerated lines"}}, "image_to_video": {"model": "wavespeed-ai/wan-2.2/i2v-480p-ultra-fast", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.15, "high": 0.3, "note": "estimate: 3-6 five-second clips at $0.05; sitcom3/spend.json, videos4/spend.json, videos6/spend.json"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "mid",
+    "estimatedCostUsd": {"low": 0.256, "high": 0.636, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries; videos6 $0.881 for three reworked ads with reuse; videos5 $0.165 TTS-only for three edits, not fresh generation"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Use a DRAMATIZATION label for fictional people and skits.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "continuity", "words_per_second", "black_corners", "eyes"],
+    "learned": ["No still frames as shots; animate source stills before the edit.", "Keep voice at its native pace; check words per second below 3.4.", "Exclude knob-to-lever morphs and fused fingers before cutting."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "videos6/spend.json", "videos6/voices.md", "videos6/qa.json", "videos5/EDIT_NOTES.md", "videos4/spend.json", "sitcom3/spend.json", "videos5/spend.json"]
+  },
+  {
+    "id": "sitcom",
+    "name": "Multi-camera sitcom",
+    "description": "Cut fictional dialogue between shared sets, angles, and silent reactions.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 18, "max": 22},
+    "hookPattern": "A hand turns the knob before the door falls.",
+    "stages": ["script", "set", "character", "still", "angle_still", "tts", "image_to_video", "talking_head", "laugh_track", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "set": {"model": "reuse supplied set", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "character": {"model": "reuse character bible", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.02, "high": 0.06, "note": "estimate: 1-3 text-to-image stills at $0.020; videos6/spend.json and videos4/spend.json"}}, "angle_still": {"model": "bytedance/seedream-v5.5/edit", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.056, "high": 0.196, "note": "estimate: 2-7 image edits at $0.028; sitcom3/spend.json, videos6/spend.json, videos4/spend.json"}}, "tts": {"model": "wavespeed-ai/qwen3-tts/text-to-speech", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.03, "high": 0.055, "note": "estimate: 6-11 calls at $0.005; sitcom3/spend.json, videos5/spend.json, videos4/spend.json"}}, "image_to_video": {"model": "wavespeed-ai/wan-2.2/i2v-480p-ultra-fast", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.15, "high": 0.3, "note": "estimate: 3-6 five-second clips at $0.05; sitcom3/spend.json, videos4/spend.json, videos6/spend.json"}}, "talking_head": {"model": "wavespeed-ai/wan-2.2/speech-to-video", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 1.5, "high": 1.8, "note": "estimate: 10-12 calls at $0.15 (480p); sitcom3/spend.json; includes test and retry; other endpoint trials excluded"}}, "laugh_track": {"model": "Mixkit laugh/clap + CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "sitcom3: reused licensed sounds at $0"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "expensive",
+    "estimatedCostUsd": {"low": 1.756, "high": 2.411, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries; sitcom3 actual $2.466 includes trials and one retry, four mouth checks failed"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Use a DRAMATIZATION label for fictional people and skits.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "continuity", "words_per_second", "black_corners", "eyes", "mouth_sync"],
+    "learned": ["Use mediums and close-ups for speech; inspect eyes at full size.", "Cut on action for the door fall: knob, crash, then aftermath.", "No still frames as shots; laughs belong on silent reaction shots.", "Trim talks to line plus 0.1 seconds; time captions from actual words.", "Wan passed only six of ten mouth-sync checks; a retry still failed."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "sitcom3/NOTES.md", "sitcom3/qa.json", "videos6/spend.json", "videos4/spend.json", "sitcom3/spend.json", "videos5/spend.json"]
+  },
+  {
+    "id": "storytime",
+    "name": "Storytime twist",
+    "description": "A fictional narrator moves from confession to checklist payoff.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "The narrator starts mid-story in the first second.",
+    "stages": ["script", "set", "character", "still", "angle_still", "tts", "image_to_video", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "set": {"model": "reuse supplied set", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "character": {"model": "reuse character bible", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "bytedance/seedream-v5.5", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.02, "high": 0.06, "note": "estimate: 1-3 text-to-image stills at $0.020; videos6/spend.json and videos4/spend.json"}}, "angle_still": {"model": "bytedance/seedream-v5.5/edit", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.056, "high": 0.196, "note": "estimate: 2-7 image edits at $0.028; sitcom3/spend.json, videos6/spend.json, videos4/spend.json"}}, "tts": {"model": "wavespeed-ai/qwen3-tts/text-to-speech", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.03, "high": 0.055, "note": "estimate: 6-11 calls at $0.005; sitcom3/spend.json, videos5/spend.json, videos4/spend.json"}}, "image_to_video": {"model": "wavespeed-ai/wan-2.2/i2v-480p-ultra-fast", "verified": "2026-11-12", "unverified": false, "estimatedCostUsd": {"low": 0.15, "high": 0.3, "note": "estimate: 3-6 five-second clips at $0.05; sitcom3/spend.json, videos4/spend.json, videos6/spend.json"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "mid",
+    "estimatedCostUsd": {"low": 0.256, "high": 0.611, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "medium",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "Use a DRAMATIZATION label for fictional people and skits.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "continuity", "words_per_second", "black_corners", "eyes"],
+    "learned": ["Keep the character bible identical across shots.", "Use a fictional framing and a checklist payoff, not a testimonial."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md", "videos6/spend.json", "videos4/spend.json", "sitcom3/spend.json", "videos5/spend.json"]
+  },
+  {
+    "id": "talking-object",
+    "name": "Talking checklist",
+    "description": "Animate an illustrated object mouth to narration.",
+    "aspectRatios": ["9:16"],
+    "durationSeconds": {"min": 15, "max": 25},
+    "hookPattern": "The paper talks and moves on frame one.",
+    "stages": ["script", "still", "tts", "sfx", "captions", "edit", "end_card", "mute_test", "qa"],
+    "providers": {"script": {"model": "supplied script / human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "still": {"model": "supplied art / SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "tts": {"model": "Kokoro local", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "sfx": {"model": "ffmpeg lavfi / licensed CC0", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "captions": {"model": "whisper.cpp + HTML", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "edit": {"model": "ffmpeg + SVG", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "end_card": {"model": "HTML overlay", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "mute_test": {"model": "human review of muted render", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}, "qa": {"model": "ffmpeg + human review", "verified": "2026-11-12", "unverified": true, "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: supplied assets or local processing; excludes labour and compute"}}},
+    "costClass": "free",
+    "estimatedCostUsd": {"low": 0, "high": 0, "note": "estimate: sum of stage assumptions; styles catalog recipes; excludes labour, compute, and unbounded retries"},
+    "policyRisk": "low",
+    "riskNotes": ["Use the housing special ad category for housing ads.", "No fake testimonials, eligibility claims, or promised savings.", "No real people. Synthetic people only; no real or named person; no children; no likeness of a real person."],
+    "qaGates": ["caption_timing", "dead_air", "tail", "shot_length", "mute_test", "orientation", "mouth_sync"],
+    "learned": ["Use an illustrated object with simple mouth flaps.", "Keep all readable text in exact overlays."],
+    "sources": ["styles/out-styles.md", "storyboards/INDEX.md", "editing/eval3/engine-ideas.md"]
+  }
+]

package/src/hooks/index.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const hooks = Object.freeze(JSON.parse(readFileSync(new URL('./library.json', import.meta.url), 'utf8'))
+  .map(hook => Object.freeze({ ...hook, tags: Object.freeze(hook.tags) })));
+function validate(scores) {
+  if (!scores || typeof scores !== 'object' || Array.isArray(scores)) throw new Error('Invalid scores');
+  for (const [id, value] of Object.entries(scores)) {
+    if (!hooks.some(h => h.id === id) || !Number.isFinite(value) || value < 0) throw new Error('Invalid score');
+  }
+  return scores;
+}
+function pathFor(directory, site) {
+  if (typeof site !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(site)) throw new Error('Invalid site slug');
+  return join(directory, `${site}.json`);
+}
+/** Read an explicit site snapshot. Missing files are a cold start; corrupt files fail. */
+export async function readScores(directory, site) {
+  const path = pathFor(directory, site);
+  try { return validate(JSON.parse(await readFile(path, 'utf8'))); }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw new Error('Cannot read scores'); }
+}
+/** Replace a site's snapshot atomically. Callers must use a single writer. */
+export async function writeScores(directory, site, scores) {
+  const path = pathFor(directory, site);
+  const data = JSON.stringify(validate(scores));
+  await mkdir(directory, { recursive: true });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  let handle;
+  let created = false;
+  try {
+    handle = await open(temp, 'wx', 0o600);
+    created = true;
+    await handle.writeFile(data);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temp, path);
+  } catch (error) {
+    // Cleanup must never replace the original write, sync, close, or rename error.
+    if (handle) await handle.close().catch(() => {});
+    if (created) await unlink(temp).catch(() => {});
+    throw error;
+  }
+}
+/** Pure selection; scores belong to the supplied site snapshot. No disk, time, or random input.
+ * @param {{id:string, scores?:Record<string,number>}} site
+ * @param {string} goal
+ */
+export function selectFor(site, goal) {
+  if (!site || typeof site !== 'object' || Array.isArray(site)) throw new Error('Invalid site');
+  pathFor('.', site.id);
+  const scores = validate(site.scores ?? {});
+  const eligible = hooks.filter(h => h.risk === 'low' && h.tags.includes(goal));
+  const ranked = eligible.map((hook, order) => ({ hook, order, score: scores[hook.id] ?? 0 }));
+  ranked.sort((a, b) => b.score - a.score || a.order - b.order);
+  return ranked.length ? structuredClone(ranked[0].hook) : null;
+}

package/src/hooks/library.json

@@ -0,0 +1,8 @@
+[
+  {"id":"door","tags":["discovery"],"pattern":"Take a closer look at {{subject}}","risk":"low"},
+  {"id":"compare","tags":["comparison","discovery"],"pattern":"Compare {{subject}} with the details in view","risk":"low"},
+  {"id":"help","tags":["discovery","help"],"pattern":"Need help exploring {{subject}}? Start here","risk":"low"},
+  {"id":"ugc","tags":["experience"],"pattern":"Here is what I observed about {{subject}}","risk":"medium"},
+  {"id":"before-after","tags":["comparison"],"pattern":"Before and after: {{subject}}. Virtual staging preview.","risk":"medium"},
+  {"id":"update","tags":["news"],"pattern":"Brand update: {{subject}} — {{source}}","risk":"high"}
+]

package/src/index.js

@@ -0,0 +1,54 @@
+import { listFormats, getFormat, planFormat } from './formats/index.js';
+export { listFormats, getFormat, planFormat };
+import { templates } from './templates/index.js';
+import { hooks, selectFor } from './hooks/index.js';
+import { lint } from './policy/index.js';
+import { templateProvider, guardCost } from './providers/index.js';
+export { templates, hooks, selectFor, lint, templateProvider, guardCost };
+export { readScores, writeScores } from './hooks/index.js';
+const string = { type: 'string' };
+const fields = {
+  list_formats: { costClass: { type: 'string', enum: ['free', 'cheap', 'mid', 'expensive'] }, risk: { type: 'string', enum: ['low', 'medium', 'high'] } },
+  get_format: { id: string },
+  plan_format: { format: string, site: string, goal: string, dryRun: { type: 'boolean' } },
+  'list-templates': {}, 'list-hooks': {},
+  lint: { copy: string, category: { enum: ['housing', 'none'], type: 'string' } },
+  plan: { site: string, goal: string, template: string, ratio: { enum: ['4:5', '9:16'], type: 'string' }, copy: string, category: { enum: ['housing', 'none'], type: 'string' }, apply: { type: 'boolean' }, dryRun: { type: 'boolean' } },
+};
+export const tools = Object.entries(fields).map(([name, properties]) => ({
+  name, description: ({ list_formats: 'List video formats with optional cost and risk filters.', get_format: 'Get a video format descriptor.', plan_format: 'Plan video stages offline. Apply is unavailable.', 'list-templates': 'List starter template descriptors.', 'list-hooks': 'List hook patterns and risks.', lint: 'Check ad copy; findings always require review.', plan: 'Preview a zero-cost plan. Apply is unavailable.' })[name],
+  inputSchema: { type: 'object', properties, additionalProperties: false, ...({ lint: ['copy'], get_format: ['id'], plan_format: ['format', 'site'] }[name] ? { required: { lint: ['copy'], get_format: ['id'], plan_format: ['format', 'site'] }[name] } : {}) },
+}));
+/** Shared CLI/MCP dispatch. Unknown inputs fail before any action. */
+export function execute(action, args = {}) {
+  if (!Object.hasOwn(fields, action)) throw new Error('Unknown action');
+  if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Invalid arguments');
+  if (args.apply === true && ['plan', 'plan_format'].includes(action)) throw new Error('Apply is unavailable in this offline slice');
+  for (const key of tools.find(t => t.name === action).inputSchema.required ?? []) if (args[key] === undefined) throw new Error('Missing required argument: ' + key);
+  for (const [key, value] of Object.entries(args)) {
+    const field = fields[action][key];
+    if (!Object.hasOwn(fields[action], key) || typeof value !== field.type || (field.enum && !field.enum.includes(value))) throw new Error('Invalid argument');
+    if (typeof value === 'string' && value.length > 20000) throw new Error('Argument too long');
+  }
+  if (action === 'list_formats') return listFormats(args);
+  if (action === 'get_format') return getFormat(args.id);
+  if (action === 'plan_format') return planFormat(args);
+  if (action === 'list-templates') return structuredClone(templates);
+  if (action === 'list-hooks') return structuredClone(hooks);
+  if (action === 'lint') return lint(args.copy, args);
+  if (args.apply === true) throw new Error('Apply is unavailable in this offline slice');
+  if (args.dryRun === false) throw new Error('Use dry-run; apply is unavailable');
+  const descriptor = templates.find(t => t.id === (args.template ?? 'door-open-teaser'));
+  if (!descriptor) throw new Error('Unknown template');
+  const site = args.site ?? 'demo';
+  const hook = selectFor({ id: site }, args.goal ?? 'discovery');
+  if (!hook) throw new Error('No low-risk hook matches this goal');
+  const copy = args.copy ?? hook.pattern.replace('{{subject}}', 'available listings');
+  const policy = lint(copy, args);
+  const estimate = templateProvider.estimate();
+  return { dryRun: true, applied: false, site, template: descriptor.id, ratio: args.ratio ?? '4:5', hook,
+    copy, policy, estimate, costGuard: guardCost({ costMinor: 0, adSpentMinor: 0, monthSpentMinor: 0, perAdMinor: 0, perMonthMinor: 0 }),
+    requiredSlots: descriptor.slots.map(s => s.name),
+    warnings: ['No image is rendered or campaign launched.', 'Supply verified slots and brand tokens to the provider.', ...descriptor.risk === 'high' ? ['High-risk template requires additional review.'] : []],
+  };
+}

package/src/policy/index.js

@@ -0,0 +1,112 @@
+// This lint is a warning tool, not legal advice. It misses cases.
+// Every result still needs a person to review it.
+// Normalize invisible separators and common Latin lookalikes before all checks.
+const lookalikes = { ı: 'i', а: 'a', е: 'e', о: 'o', р: 'p', с: 'c', х: 'x', у: 'y', і: 'i', ј: 'j', ѕ: 's', к: 'k', м: 'm', т: 't', в: 'b', н: 'h', ι: 'i', α: 'a', ε: 'e', ο: 'o', ρ: 'p', χ: 'x', υ: 'y', κ: 'k', τ: 't', ν: 'v' };
+function normalize(copy) {
+  return copy.normalize('NFKC').toLowerCase().normalize('NFD').replace(/\p{M}/gu, '')
+    .replace(/[\u00ad\u034f\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g, '')
+    .replace(/[ıаеорсхуіјѕкмтвнαεορχυκτνι]/g, c => lookalikes[c]);
+}
+function hasContact(text) {
+  // Each token/run is scanned once. Do not retry an unbounded suffix at every character.
+  if (text.split(/\s+/).some(token => /^[^@]+@[^@.]+\.[^@]+$/.test(token))) return true;
+  const withoutDates = text
+    .replace(/\b(?:parcel(?:[ -]+id)?|assessor[ -]+parcel)[ :#-]*[\d-]+\b/g, ' ')
+    .replace(/\b(?:\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{4})\b/g, ' ');
+  for (const match of withoutDates.matchAll(/[+\d][\d\s().-]*/g)) {
+    const digits = match[0].replace(/\D/g, '').length;
+    if (digits >= 10) return true;
+  }
+  return false;
+}
+function hasPlaceholder(text) {
+  const start = text.indexOf('{{');
+  return start !== -1 && text.indexOf('}}', start + 2) !== -1;
+}
+function hasHousing(text) {
+  const subject = text.replace(/\b(?:apartment design games?|auction software|art listings?|lease accounting software|flat tires?|flat rates?|home page|home runs?|house music)\b/g, '');
+  return /\b(?:homes?|housing|houses?|condos?|condominiums?|apartments?|leases?|leasing|renting|rented|townhouses?|duplex(?:es)?|landlords?|tenants?|bedrooms?|studios?|\d+br|flats?|real estate|foreclosures?|rent(?:al|als)?|propert(?:y|ies)|mortgages?|auctions?|listings?)\b/.test(subject);
+}
+// Bounded connectors keep cues attached to people, without scanning arbitrary prose.
+const gap = '[\\s-]+';
+const spaced = pattern => pattern.replaceAll(' ', gap);
+const people = spaced('(?:(?:tenants?|residents?|applicants?|people|persons?|households?|roommates?|family|families|professionals?|with|or|and|pets|grad|job|on|are|is) ){0,4}');
+const modifier = spaced('(?:(?:a|an) )?(?:(?:young|single|mature|professional|traditional|able bodied) )?');
+const cueBefore = spaced('(?:only|no|not|not for|wanted|prefer|prefers|seeking|seeks|preferred|ideal for|great for|perfect for|must be|must have|must speak|exclude|excluding|not suitable for)');
+const cueAfter = spaced('(?:only|preferred|wanted|required|excluded|exclusive|need not apply|not welcome|not accepted|not allowed|not permitted|prohibited|banned)');
+function preference(subject, welcomeSignals = false) {
+  const group = spaced(subject);
+  // 'X welcome' is inclusive for income, family, age, marital status and disability. For religion,
+  // race, origin and sex it signals a preference, so those rules pass welcomeSignals = true.
+  const after = welcomeSignals ? '(?:' + cueAfter + '|welcome)' : cueAfter;
+  return new RegExp('\\b(?:' + cueBefore + gap + people + modifier + '(?:' + group + ')|(?:' + group + ')' + gap + people + after + ')\\b');
+}
+// Keep age numbers bounded, including common written ages.
+const ageNumber = '(?:\\d{1,2}|(?:twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety)(?:[ -](?:one|two|three|four|five|six|seven|eight|nine))?|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen)';
+const ageSpan = ageNumber + '\\s*(?:(?:to|thru|through|[-\\u2013])\\s*' + ageNumber + '|\\+|plus)(?!\\w)';
+const ageRange = new RegExp('\\b(?:age[sd]?(?:[ -]+range)?[\\s-]*' + ageSpan + '|must[ -]+be[ -]+(?:under|over|younger than|older than)[ -]+' + ageNumber + '\\b)');
+const childAmenity = new RegExp('\\b(?:kids|children)[ -]+age[sd]?[\\s-]*' + ageSpan + '[ -]+(?:play[ -]+area|playground)\\b', 'g');
+const ageRestriction = {
+  // Remove only the amenity phrase. Other restrictions in the copy still apply.
+  test: text => ageRange.test(text.replace(childAmenity, ' ')),
+};
+const postalTerm = '(?:(?:zip|postal)(?:[\\s-]*codes?)?|postcodes?)';
+const postalRestriction = new RegExp('\\b(?:' + postalTerm + '[\\s-]+only|(?:only|just)[\\s-]+(?:in[\\s-]+)?(?:these[\\s-]+|the[\\s-]+)?' + postalTerm + '|' + postalTerm + '[\\s-]*(?:targeting|restricted)|' + postalTerm + '[ -]+(?:\\d{5}(?:-\\d{4})?|[a-z]{1,2}\\d[a-z\\d]?[ -]+\\d[a-z]{2})[ -]+(?:residents?[ -]+)?only)\\b');
+const housingRules = [
+  ['targeting_age', preference('young(?: professionals?| adults?)?|seniors?|retirees?|millennials?|students?|mature|elderly|teens?|teenagers?|toddlers?|babies|infants?'), 'Remove age or student restrictions and preferences.'],
+  ['targeting_familial_status', preference('children|child|kids|kiddos|family|families|parents?|mothers?|fathers?|pregnant'), 'Remove family-status restrictions and preferences.'],
+  ['targeting_familial_status', preference('adults?|empty nesters'), 'Remove family-status restrictions and preferences.'],
+  ['targeting_marital_status', preference('singles?|bachelors?|couples?|married|unmarried|divorced'), 'Remove marital-status restrictions and preferences.'],
+  ['targeting_religion', preference('christians?|muslims?|jewish|jews?|hindus?|buddhists?|catholics?|protestants?|believers|religious', true), 'Remove religious targeting or preferences.'],
+  ['targeting_income', preference('section (?:8|eight)|vouchers?|hud|housing assistance|public assistance|income source|job income|welfare|ssi|ssdi|disability income|social security'), 'Remove source-of-income restrictions or preferences.'],
+  ['targeting_sex', preference('men|women|males?|females?|boys?|girls?|gentlemen|ladies|sex|gender|gay|straight', true), 'Remove sex or gender restrictions and preferences.'],
+  ['targeting_origin', preference('americans?|canadians?|chinese|indians?|mexicans?|british|french|arabs?|hispanics?|latinos?|latinas?|africans?|asians?|(?:us )?citizens?|native speakers?|english(?: speakers?)?|immigrants?|foreigners?|national origin|ethnicity|race|whites?|blacks?|minorities', true), 'Remove race or national-origin restrictions and preferences.'],
+  ['targeting_disability', preference('disabled|handicapped|deaf|blind|disability|disabilities|mentally ill|wheelchairs?(?: users?)?|service animals?|able bodied|non disabled|wheelchair accessible'), 'Remove disability restrictions and preferences.'],
+  // Indirect occupancy language needs review even without an explicit restriction.
+  ['targeting_familial_status', /\b(?:traditional[\s-]+family[\s-]+values[\s-]+neighbou?rhood|adult[\s-]+community|only[\s-]+one[\s-]+child)\b/, 'Review possible family-status or occupancy preferences.', 'warning'],
+  ['targeting_religion', /\b(?:christian|muslim|jewish|hindu|buddhist|catholic|protestant)[\s-]+home\b/, 'Review possible religious occupancy preferences.', 'warning'],
+  ['targeting_disability', /\bmust[\s-]+be[\s-]+able[\s-]+to[\s-]+climb[\s-]+stairs\b/, 'Review possible disability restrictions in stair-access requirements.', 'warning'],
+  // These phrases describe eligibility or preferred occupants, rather than a bare class word.
+  ['targeting_age', /\b(?:(?:over|under|older than|younger than)[ -]+\d{1,3}[ -]+(?:community|residents?|tenants?|only)|(?:\d{1,3}|fifty[ -]five)[ -]*(?:\+|plus\b|(?:and|or)[ -]+(?:over|older|up)\b|years?[ -]+(?:old|(?:and|or)[ -]+(?:over|older))\b)|senior living|retirement community)\b/, 'Remove age eligibility language.'],
+  ['targeting_age', /\b\d{1,3}\+(?=[ -]+(?:community|residents?|tenants?|only)\b)/, 'Remove age eligibility language.'],
+  ['targeting_familial_status', /\b(?:family[ -]friendly|child[ -]free)\b/, 'Remove family-status preferences.'],
+  ['targeting_religion', /\b(?:christian|muslim|jewish|hindu|buddhist|catholic|protestant)[ -]+(?:neighbou?rhood|community|building)(?!\s+(?:cent(?:er|re)|hall|school|hospital|museum|library|church|temple|mosque|synagogue))\b/, 'Remove religious neighborhood preferences.'],
+  ['targeting_sex', /\b(?:gay|straight)[ -]friendly\b/, 'Remove sex or gender preferences.'],
+  ['targeting_area', /\b(?:zip|postal)[ -]+(?:code[ -]+)?\d{1,10}[ -]+only\b|\b(?:target|targeting|exclude|excluding)\s+(?:residents?\s+)?(?:in\s+)?(?:(?:this|that|the|these|specific|selected)\s+)?(?:areas?|neighbou?rhoods?|districts?)\b|\b(?:locals?|area residents?)\s+only\b/, 'Remove postal or area targeting language.'],
+  ['targeting_age', ageRestriction, 'Remove age ranges or limits.'],
+  ['targeting_area', postalRestriction, 'Remove ZIP-code targeting.'],
+];
+/** Conservative copy checks, not platform approval or factual verification.
+ * @param {string} copy
+ * @param {{category?:string}} options
+ */
+export function lint(copy, options = {}) {
+  if (typeof copy !== 'string' || copy.length > 20000) throw new Error('Copy must be a string of at most 20000 characters');
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new Error('Invalid lint options');
+  const { category = 'housing' } = options;
+  if (!['housing', 'none'].includes(category)) throw new Error('Unsupported category');
+  const text = normalize(copy);
+  // Preserve punctuation for contact and date checks. Normalize it only for targeting.
+  const targetingText = text.replace(/\bu\.s\.(?=[\s_.-])/g, 'us').replace(/[_.]/g, ' ');
+  const findings = [];
+  const add = (code, message, severity = 'error') => findings.push({ code, severity, message });
+  if (!text.trim()) add('empty', 'Supply ad copy.');
+  const housing = category === 'housing' || hasHousing(text);
+  if (category !== 'housing' && housing) add('housing_category', 'Declare the housing Special Ad Category.');
+  const rules = [
+    ...(housing ? housingRules : []),
+    ['deceptive', /\b(guarantee\w*|risk[ -]?free|zero risk|no risk|double your money|instant profit)\b/, 'Remove promises of certain outcomes.'],
+    ['superlative', /\b(best(?![ -]street\b)|top(?![ -](?:floor\b|\d+\b|rated\b|notch\b|tier\b))|largest|fastest|cheapest|unbeatable|number one)\b|#\s*1\b/, 'Remove banned superlatives.'],
+    ['below_market', /\b(?:below|under|off|less[ -]+than|cheaper[ -]+than|discount(?:ed)?[ -]+(?:from|against|to))[ -]+(?:(?:the|current|local|fair|estimated|average|prevailing|open)[ -]+){0,5}(?:market|appraisal|appraised[ -]+value|comps)\b|\bmarket\s+(?:value|rates?|prices?)\s+(?:minus|less|discount)/, 'A below-market claim needs independent evidence and review.'],
+    ['urgency', /\b(only today|ending soon|limited time|act now|last chance|only \d+ left)\b/, 'Verify scarcity and timing before use.'],
+    ['news', /\b(breaking(?![ -]down\b)|news alert)\b/, 'News framing needs review and a clear ad disclosure.'],
+    ['staging', /\b(before.{0,12}after|virtually staged|virtual staging|ai.staged)\b/, 'Verify the source images and staging disclosure.'],
+  ];
+  for (const [code, pattern, message, severity] of rules) {
+    if (pattern.test(code.startsWith('targeting_') ? targetingText : text)) add(code, message, severity);
+  }
+  if (hasContact(text)) add('private_data', 'Remove contact data.');
+  if (hasPlaceholder(text)) add('placeholder', 'Replace unresolved slots before review.');
+  add('human_review', 'This lint is a warning tool, not legal advice. It misses cases. Every result needs a person to review facts, consent, disclosures, and platform rules.', 'warning');
+  return { status: findings.some(f => f.severity === 'error') ? 'blocked' : 'review', category, findings };
+}

package/src/providers/index.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { templates } from '../templates/index.js';
+/** @typedef {{capabilities:Function, estimate:Function, run:Function}} Provider */
+/** Pure cap check in integer minor units of one caller-selected currency.
+ * Existing spend must include reservations and uncertain charges.
+ */
+export function guardCost(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid cost or cap');
+  const values = {};
+  for (const key of ['costMinor', 'adSpentMinor', 'monthSpentMinor', 'perAdMinor', 'perMonthMinor']) {
+    if (!Object.hasOwn(input, key)) throw new Error(`Invalid cost or cap: ${key} must be an own property`);
+    const value = input[key];
+    values[key] = value;
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error('Invalid cost or cap');
+  }
+  if ('apply' in input && !Object.hasOwn(input, 'apply')) throw new Error('Invalid cost or cap: apply must be an own property');
+  const { costMinor, adSpentMinor, monthSpentMinor, perAdMinor, perMonthMinor } = values;
+  const apply = input.apply;
+  const reasons = [];
+  if (costMinor > 0 && apply !== true) reasons.push('apply_required');
+  if (costMinor > perAdMinor - adSpentMinor) reasons.push('per_ad_cap');
+  if (costMinor > perMonthMinor - monthSpentMinor) reasons.push('monthly_cap');
+  return { ok: reasons.length === 0, reasons };
+}
+const escape = value => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** HTML-to-image adapter stub. It emits deterministic HTML only, never a raster image. */
+export const templateProvider = {
+  id: 'html-template-stub',
+  capabilities: () => ({ formats: ['text/html'], aspectRatios: ['4:5', '9:16'], imageRendering: false }),
+  estimate: () => ({ costMinor: 0, currency: 'USD', confidence: 'exact' }),
+  run(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid provider input');
+    const { template, ratio = '4:5', slots, brand = {} } = input;
+    const descriptor = templates.find(t => t.id === template);
+    if (!descriptor || !descriptor.aspectRatios.includes(ratio)) throw new Error('Invalid template or ratio');
+    if (!slots || typeof slots !== 'object' || Array.isArray(slots)) throw new Error('Invalid slots');
+    if (!brand || typeof brand !== 'object' || Array.isArray(brand)) throw new Error('Invalid brand');
+    if (Object.keys(slots).some(k => !descriptor.slots.some(s => s.name === k))) throw new Error('Unknown slot');
+    if (Object.keys(brand).some(k => !descriptor.brandTokens.includes(k))) throw new Error('Unknown brand token');
+    const colors = { primary: '#2455cc', background: '#ffffff', foreground: '#151515' };
+    for (const key of Object.keys(colors)) {
+      colors[key] = brand[key] ?? colors[key];
+      if (typeof colors[key] !== 'string' || !/^#[0-9a-f]{6}$/i.test(colors[key])) throw new Error('Invalid brand color');
+    }
+    const name = brand.name ?? 'Demo';
+    if (typeof name !== 'string' || !name.trim() || name.length > 80) throw new Error('Invalid brand name');
+    const body = descriptor.slots.map(slot => {
+      const value = Object.hasOwn(slots, slot.name) ? slots[slot.name] : undefined;
+      if (typeof value !== 'string' || !value.trim() || value.length > slot.maxChars) throw new Error('Invalid required slot');
+      return `<section data-slot="${slot.name}">${escape(value)}</section>`;
+    }).join('');
+    const width = 1080, height = ratio === '4:5' ? 1350 : 1920;
+    const html = `<!doctype html><html><head><meta charset="utf-8"><title>Ad preview</title><style>body{margin:0;width:${width}px;height:${height}px;box-sizing:border-box;padding:80px;background:${colors.background};color:${colors.foreground};font:48px sans-serif}header{color:${colors.primary}}section{margin:40px 0;overflow-wrap:anywhere}</style></head><body data-template="${descriptor.id}"><header>${escape(name)}</header>${body}</body></html>`;
+    return { html, mime: 'text/html', width, height, image: null, sha256: createHash('sha256').update(html).digest('hex'), costMinor: 0, warnings: ['Stub: HTML only; image rendering is unavailable.'] };
+  },
+};

package/src/templates/index.js

@@ -0,0 +1,26 @@
+/** @typedef {{name:string, required:boolean, maxChars:number, source:string}} Slot */
+/** @typedef {{id:string, version:number, name:string, aspectRatios:string[], slots:Slot[], beats:string[], risk:string}} Template */
+const slot = (name, source = 'source') => ({ name, source, required: true, maxChars: 240 });
+/** @type {Template[]} */
+export const templates = [
+  ['door-open-teaser', 'Door-open teaser', ['detail'], ['Door reveal', 'Show the actual condition', 'Invite a closer look'], 'low'],
+  ['ugc-first-person', 'UGC first-person', ['experience', 'disclosure'], ['First-person introduction', 'Verified experience', 'Ad disclosure and invitation'], 'medium'],
+  ['honest-before-after', 'Honest before/after', ['before', 'after', 'disclosure'], ['Same view before', 'Same view after', 'Explain actual or virtual changes'], 'medium'],
+  ['breaking-news-frame', 'Breaking-news frame', ['fact', 'source', 'disclosure'], ['Brand update banner', 'Dated and sourced fact', 'Clearly identify this as an ad'], 'high'],
+  ['help-urgency', 'Help/urgency', ['problem', 'help', 'timing'], ['Name the task', 'Offer practical help', 'Use only verified timing'], 'medium'],
+].map(([id, name, extra, beats, risk]) => ({
+  id, name, version: 1, aspectRatios: ['4:5', '9:16'], risk, beats,
+  slots: [slot('headline', 'hook'), ...extra.map(x => slot(x)), slot('cta', 'cta')],
+  brandTokens: ['name', 'primary', 'background', 'foreground'],
+  renderer: 'template', costClass: 'free', policy: { textExact: true, imageMayContainText: false },
+}));
+
+// Freeze every nested descriptor so callers cannot change rendering limits or risk.
+function deepFreeze(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+deepFreeze(templates);