storyforge 0.4.21 → 0.5.3

package/dist/bridge-poller-WEKSUZMT.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+import {
+  log
+} from "./chunk-GJQ45C5W.js";
+
+// src/bridge-poller.ts
+import { spawn, spawnSync } from "child_process";
+import * as crypto from "crypto";
+import * as fs from "fs";
+var HEARTBEAT_INTERVAL_MS = 6e4;
+var POLL_INTERVAL_MS = 8e3;
+var CLI_TIMEOUT_MS = Number(process.env.SCRIPT_GEN_TIMEOUT_MS) || 20 * 60 * 1e3;
+var IMAGE_GEN_TIMEOUT_MS = Number(process.env.CODEX_IMAGE_GEN_TIMEOUT_MS) || Number(process.env.IMAGE_GEN_TIMEOUT_MS) || 8 * 60 * 1e3;
+var MAX_IN_FLIGHT_JOBS = Math.max(1, Math.min(6, Number(process.env.FORGE_BRIDGE_MAX_IN_FLIGHT) || 4));
+var CODEX_IMAGEGEN_AGENT_MODELS = ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"];
+var CODEX_AGENT_MODEL_RE = /^gpt-5(?:$|[.\-])/i;
+var BridgePoller = class {
+  baseUrl;
+  token;
+  clientVersion;
+  instanceId;
+  heartbeatTimer = null;
+  pollTimer = null;
+  inFlight = /* @__PURE__ */ new Set();
+  stopped = false;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.token = opts.token;
+    this.clientVersion = opts.clientVersion;
+    this.instanceId = `${process.pid}-${crypto.randomBytes(2).toString("hex")}-${Date.now()}`;
+  }
+  start() {
+    if (this.heartbeatTimer || this.pollTimer) return;
+    log.info(`[bridge] poller starting \xB7 ${this.baseUrl} \xB7 instance=${this.instanceId}`);
+    void this.heartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      void this.heartbeat();
+    }, HEARTBEAT_INTERVAL_MS);
+    this.pollTimer = setInterval(() => {
+      void this.poll();
+    }, POLL_INTERVAL_MS);
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.heartbeatTimer = null;
+    this.pollTimer = null;
+  }
+  probeBinary(name) {
+    if (!/^[a-z][a-z0-9-]*$/i.test(name)) return { available: false, path: null };
+    const r = spawnSync("which", [name], { encoding: "utf-8", timeout: 2e3 });
+    if (r.status !== 0) return { available: false, path: null };
+    const path = (r.stdout ?? "").trim();
+    return { available: !!path, path: path || null };
+  }
+  async heartbeat() {
+    if (this.stopped) return;
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/heartbeat`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          availableClis: {
+            claude: this.probeBinary("claude"),
+            codex: this.probeBinary("codex")
+          },
+          clientVersion: this.clientVersion,
+          instanceId: this.instanceId
+        }),
+        signal: AbortSignal.timeout(45e3)
+      });
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        log.warn(`[bridge] heartbeat HTTP ${resp.status}: ${text.slice(0, 120)}`);
+      }
+    } catch (err) {
+      log.warn(`[bridge] heartbeat failed: ${err.message}`);
+    }
+  }
+  async poll() {
+    if (this.stopped) return;
+    const availableSlots = MAX_IN_FLIGHT_JOBS - this.inFlight.size;
+    if (availableSlots <= 0) return;
+    let jobs = [];
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/claim`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ instanceId: this.instanceId, limit: Math.min(3, availableSlots) }),
+        signal: AbortSignal.timeout(45e3)
+      });
+      if (!resp.ok) {
+        if (resp.status === 401) {
+          log.warn("[bridge] 401 \u2014 bridge token rejected. Stopping poller. Set BRIDGE_TOKEN to the value Vercel has and restart.");
+          await this.stop();
+          return;
+        }
+        const text = await resp.text().catch(() => "");
+        log.warn(`[bridge] claim HTTP ${resp.status}: ${text.slice(0, 120)}`);
+        return;
+      }
+      const data = await resp.json();
+      jobs = data.jobs ?? [];
+    } catch (err) {
+      log.warn(`[bridge] claim failed: ${err.message}`);
+      return;
+    }
+    if (jobs.length === 0) return;
+    await Promise.all(jobs.map((job) => this.runJob(job)));
+  }
+  async runJob(job) {
+    if (this.inFlight.has(job.id)) return;
+    this.inFlight.add(job.id);
+    const imagePayload = parseImageGenPayload(job.prompt);
+    const modelLabel = imagePayload && job.cli === "codex" ? `codex:imagegen via ${codexImagegenModelCandidates(job.model)[0]}${job.model ? ` (requested ${job.model})` : ""}` : `${job.cli}${job.model ? `:${job.model}` : ""}`;
+    log.info(`[bridge] running job ${job.id.slice(0, 8)} \xB7 ${modelLabel}`);
+    const startedAt = Date.now();
+    try {
+      const { text, modelUsed, error } = await this.invokeJob(job);
+      const latencyMs = Date.now() - startedAt;
+      await this.respond(job.id, { text, modelUsed, latencyMs, error });
+      if (error) {
+        log.warn(`[bridge] job ${job.id.slice(0, 8)} failed (${latencyMs}ms): ${error.slice(0, 120)}`);
+      } else {
+        log.success(`[bridge] job ${job.id.slice(0, 8)} done (${latencyMs}ms \xB7 ${modelUsed})`);
+      }
+    } catch (err) {
+      const latencyMs = Date.now() - startedAt;
+      await this.respond(job.id, { error: err.message, latencyMs });
+    } finally {
+      this.inFlight.delete(job.id);
+    }
+  }
+  async invokeCli(cli, model, prompt) {
+    const candidates = cli === "codex" ? model && /^[a-z0-9.\-]+$/i.test(model) ? [model] : ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"] : model && /^[a-z0-9-]+$/i.test(model) ? [model] : ["opus", "sonnet"];
+    let lastErr = "";
+    for (const m of candidates) {
+      try {
+        const args = cli === "codex" ? ["exec", "-", "--model", m, "--search"] : [
+          "-p",
+          "--model",
+          m,
+          "--no-session-persistence",
+          "--allowedTools",
+          "WebSearch,WebFetch"
+        ];
+        const text = await runSpawn(cli, args, prompt, CLI_TIMEOUT_MS);
+        if (text.trim()) return { text, modelUsed: `${cli}:${m}` };
+        lastErr = `${cli}/${m} returned empty stdout`;
+      } catch (err) {
+        lastErr = `${cli}/${m}: ${err.message}`;
+      }
+    }
+    return { error: lastErr || "no model produced output" };
+  }
+  async invokeJob(job) {
+    const claudePromptEnvelope = parseClaudePromptEnvelope(job.prompt);
+    if (claudePromptEnvelope) {
+      if (job.cli !== "claude") return { error: `${claudePromptEnvelope.__forgeJobKind} envelope requires claude CLI` };
+      return this.invokeClaudeWithEnvelope(job.model, claudePromptEnvelope);
+    }
+    const imagePayload = parseImageGenPayload(job.prompt);
+    if (imagePayload) {
+      if (job.cli !== "codex") return { error: "image-gen bridge jobs require codex CLI" };
+      return this.invokeCodexImageGen(job.model, imagePayload);
+    }
+    return this.invokeCli(job.cli, job.model, job.prompt);
+  }
+  /**
+   * Run a Claude prompt envelope. Web tools are gated by envelope.webTools:
+   *   ['WebSearch','WebFetch'] for fact-pack-build (research stage)
+   *   []                       for script-from-pack (pack-only writing)
+   */
+  async invokeClaudeWithEnvelope(jobModel, envelope) {
+    const requestedModel = envelope.model || jobModel;
+    const fallbackChain = envelope.__forgeJobKind === "fact-pack-build" ? ["opus", "sonnet"] : ["sonnet", "haiku"];
+    const candidates = requestedModel && /^[a-z0-9-]+$/i.test(requestedModel) ? [requestedModel] : fallbackChain;
+    const tools = (envelope.webTools ?? []).filter((t) => t === "WebSearch" || t === "WebFetch");
+    const baseArgs = ["-p", "--model", "<m>", "--no-session-persistence"];
+    if (tools.length > 0) {
+      baseArgs.push("--allowedTools", tools.join(","));
+    }
+    let lastErr = "";
+    for (const m of candidates) {
+      try {
+        const args = baseArgs.map((a) => a === "<m>" ? m : a);
+        const text = await runSpawn("claude", args, envelope.prompt, CLI_TIMEOUT_MS);
+        if (text.trim()) return { text, modelUsed: `claude:${m}${tools.length === 0 ? " (no-web)" : ""}` };
+        lastErr = `claude/${m} returned empty stdout`;
+      } catch (err) {
+        lastErr = `claude/${m}: ${err.message}`;
+      }
+    }
+    return { error: lastErr || "no model produced output" };
+  }
+  async invokeCodexImageGen(model, payload) {
+    const candidates = codexImagegenModelCandidates(model);
+    const count = Math.max(1, Math.min(4, Number(payload.count) || 1));
+    const prompt = [
+      "Use Codex imagegen to generate raster image assets for Forge.",
+      "Use the installed imagegen skill in its default built-in tool mode.",
+      `Generate exactly ${count} image${count === 1 ? "" : "s"}.`,
+      `Aspect: ${payload.aspect ?? "16:9"}. Quality: ${payload.quality ?? "medium"}.`,
+      payload.size ? `Preferred size: ${payload.size}.` : "",
+      "",
+      "Image prompt:",
+      payload.prompt,
+      "",
+      "After the file(s) are generated, return ONLY strict JSON in this shape:",
+      '{"images":[{"path":"/absolute/path/to/generated.png","mimeType":"image/png"}]}',
+      "No markdown, no prose, no thumbnails, no relative paths."
+    ].filter(Boolean).join("\n");
+    let lastErr = "";
+    for (const m of candidates) {
+      try {
+        const stdout = await runSpawn("codex", ["exec", "-", "--model", m], prompt, IMAGE_GEN_TIMEOUT_MS);
+        const images = collectImagesFromCodexStdout(stdout, count);
+        if (images.length === 0) {
+          lastErr = `codex/${m} imagegen returned no readable image paths`;
+          continue;
+        }
+        return {
+          text: JSON.stringify({ images, model: `codex-cli:${m}` }),
+          modelUsed: `codex-cli:${m}`
+        };
+      } catch (err) {
+        lastErr = `codex/${m}: ${err.message}`;
+      }
+    }
+    return { error: lastErr || "codex imagegen produced no output" };
+  }
+  async respond(jobId, body) {
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/respond`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ jobId, ...body }),
+        signal: AbortSignal.timeout(45e3)
+      });
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        log.warn(`[bridge] respond HTTP ${resp.status}: ${text.slice(0, 120)}`);
+      }
+    } catch (err) {
+      log.warn(`[bridge] respond failed for ${jobId.slice(0, 8)}: ${err.message}`);
+    }
+  }
+};
+function codexImagegenModelCandidates(model) {
+  const requested = model?.trim();
+  if (requested && /^[a-z0-9.\-]+$/i.test(requested) && CODEX_AGENT_MODEL_RE.test(requested)) {
+    return [requested];
+  }
+  return CODEX_IMAGEGEN_AGENT_MODELS;
+}
+function parseImageGenPayload(prompt) {
+  try {
+    const parsed = JSON.parse(prompt);
+    if (parsed.__forgeJobKind === "image-gen" && typeof parsed.prompt === "string" && parsed.prompt.trim()) {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+var CLAUDE_JOB_KINDS = [
+  "fact-pack-build",
+  "script-from-pack",
+  "script-evaluate",
+  "script-improve"
+];
+function parseClaudePromptEnvelope(prompt) {
+  try {
+    const parsed = JSON.parse(prompt);
+    const kind = parsed.__forgeJobKind;
+    if (kind && CLAUDE_JOB_KINDS.includes(kind) && typeof parsed.prompt === "string" && parsed.prompt.length > 0) {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function collectImagesFromCodexStdout(stdout, maxCount) {
+  const parsedPaths = parseImagePathsFromJson(stdout);
+  const regexPaths = Array.from(stdout.matchAll(/(?:^|["`\s])(\/[^"`\n\r]+\.(?:png|jpe?g|webp))(?:["`\s]|$)/gi)).map((match) => match[1]);
+  const paths = Array.from(/* @__PURE__ */ new Set([...parsedPaths, ...regexPaths]));
+  const images = [];
+  for (const p of paths) {
+    if (images.length >= maxCount) break;
+    try {
+      const stat = fs.statSync(p);
+      if (!stat.isFile() || stat.size <= 0) continue;
+      images.push({
+        base64: fs.readFileSync(p).toString("base64"),
+        mimeType: mimeTypeForPath(p),
+        model: "codex-cli:imagegen"
+      });
+    } catch {
+    }
+  }
+  return images;
+}
+function parseImagePathsFromJson(stdout) {
+  const trimmed = stdout.replace(/^```(?:json)?\s*/, "").replace(/```\s*$/, "").trim();
+  const candidates = [trimmed];
+  const objectMatch = trimmed.match(/\{[\s\S]*\}/);
+  if (objectMatch) candidates.push(objectMatch[0]);
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (Array.isArray(parsed.images)) {
+        return parsed.images.map((img) => img.path).filter((p) => typeof p === "string");
+      }
+    } catch {
+    }
+  }
+  return [];
+}
+function mimeTypeForPath(p) {
+  const lower = p.toLowerCase();
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  return "image/png";
+}
+function runSpawn(cmd, args, stdin, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+      }
+      reject(new Error(`${cmd} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString("utf-8");
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString("utf-8");
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) reject(new Error(`${cmd} exit ${code}: ${stderr.slice(-300)}`));
+      else resolve(stdout);
+    });
+    proc.stdin.end(stdin);
+  });
+}
+export {
+  BridgePoller
+};

package/dist/{cli-usage-P3LK7WEE.js → cli-usage-FG3YUG3W.js}

@@ -5,6 +5,23 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { loadSessionBlockData } from "ccusage/data-loader";
+var SILENCED_LITELLM_RE = /(LiteLLM|Loaded pricing for \d+ models|Fetching latest model pricing)/;
+function patchWrite(stream) {
+  const orig = stream.write.bind(stream);
+  stream.write = (chunk, ...rest) => {
+    if (typeof chunk === "string" && SILENCED_LITELLM_RE.test(chunk)) return true;
+    if (Buffer.isBuffer(chunk) && SILENCED_LITELLM_RE.test(chunk.toString("utf-8"))) return true;
+    return orig(chunk, ...rest);
+  };
+}
+var writePatchApplied = false;
+function applyWritePatch() {
+  if (writePatchApplied) return;
+  patchWrite(process.stdout);
+  patchWrite(process.stderr);
+  writePatchApplied = true;
+}
+applyWritePatch();
 var PRICES = {
   // Anthropic — claude.com/pricing
   "claude-opus-4-7": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
@@ -39,6 +56,7 @@ function computeCost(model, u) {
   return cost;
 }
 var CLI_USAGE_PARSER_VERSION = 4;
+var warnedCcusageFallback = false;
 function emptyModelUsage(model) {
   return { model, inputTokens: 0, cachedReadTokens: 0, cacheCreateTokens: 0, outputTokens: 0, costUsd: 0 };
 }
@@ -190,7 +208,10 @@ async function gatherCliUsage() {
     claudeFileCount = listJsonlFiles(path.join(os.homedir(), ".claude", "projects")).length;
   } catch (err) {
     claudeError = `ccusage unavailable, using fallback parser (${err.message?.slice(0, 80) ?? "unknown"})`;
-    console.error("[cli-usage] ccusage loader failed, falling back:", claudeError);
+    if (!warnedCcusageFallback) {
+      console.error("[cli-usage] ccusage loader failed, falling back:", claudeError, "(further occurrences suppressed)");
+      warnedCcusageFallback = true;
+    }
     const claudeDir = path.join(os.homedir(), ".claude", "projects");
     const claudeFiles = listJsonlFiles(claudeDir);
     claudeFileCount = claudeFiles.length;

package/dist/index.js

@@ -113,7 +113,7 @@ ${args.referenceScript.slice(0, 8e3)}
 
 === END SAMPLE ===
 
-Use this ONLY to calibrate the channel's voice \u2014 sentence rhythm, tolerance for technical detail, willingness to name real things. Do NOT copy its structure. If the sample opens with historical examples and this topic works better with a counter-intuitive question or a single unfolding metaphor, choose the format that serves the topic. The best script for THIS topic may look structurally different from the sample, and that's correct.` : "";
+Use this ONLY to calibrate the channel's voice: sentence rhythm, specificity, confidence, and tolerance for technical detail. Do NOT copy its hook type, historical sequence, metaphor, beat order, payoff shape, named examples, or chunk structure. Before writing, identify what THIS topic naturally wants: a failure story, mystery, product timeline, human profile, mechanism teardown, market shift, investigation, or another shape. The best script for THIS topic may look structurally nothing like the sample, and that is correct.` : "";
   const guidanceBlock = (args.additionalGuidance ?? "").trim() ? `
 
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
@@ -144,32 +144,34 @@ TARGET LENGTH: ${minMin}-${maxMin} minutes (write to the topic's natural length
 ENGAGEMENT BAR (this overrides everything below \u2014 RULE -1)
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
 
-A previous KV Cache script we got back was technically accurate but
-DEAD on arrival. It read like a textbook chapter. It was a 1/10 on
-retention. Why? It made these mistakes \u2014 DO NOT REPEAT THEM:
+A previous script we got back was technically accurate but DEAD on
+arrival. It read like a textbook chapter. It was a 1/10 on retention.
+Why? It made these mistakes \u2014 DO NOT REPEAT THEM:
 
   1. NO NAMED CHARACTERS. Just "researchers" and "engineers". Real
      scripts have humans with names doing things in specific places.
 
-  2. NO SCENES. Just told us "imagine the librarian". Real scripts
-     SHOW: time of day, location, what's on the screen, what someone
-     said in a meeting, the GPU temperature when something broke.
+  2. NO SCENES. Just named abstractions. Real scripts SHOW the
+     topic-specific scene: time of day, location, what's on the screen,
+     the physical artifact, the number on the dashboard, what someone
+     said in a meeting, or the failure that made the mechanism matter.
 
   3. NO SECOND PERSON. Wrote in detached third person throughout.
      Engaging scripts say "your AI assistant", "you're typing into
      ChatGPT and..." \u2014 pull the viewer into the scene.
 
   4. ACADEMIC SENTENCE STRUCTURE. Long compound sentences with
-     multiple subordinate clauses. "Production inference has two
-     very different phases, and KV Cache explains why they feel
-     different to users." That reads like a paper. The same
-     information as: "Two phases. They feel completely different.
-     KV Cache explains why."
-
-  5. NO ANTAGONIST / NO TENSION. Tesla had Waymo. KV Cache had no
-     foil. Every great explainer has a "vs" \u2014 brute force vs
-     elegance, the old way vs the new way, the hopeful believer vs
-     the cynical realist.
+     multiple subordinate clauses. "This system has two very different
+     phases, and the architecture explains why they feel different to
+     users." That reads like a paper. Prefer shorter,
+     scene-driven sentences that name the specific constraint and why
+     it matters to the viewer.
+
+  5. NO TOPIC-NATIVE TENSION. Every great explainer has pressure, but
+     the pressure must come from THIS topic. It might be brute force vs
+     elegance, promise vs bill, safety vs speed, incumbent vs upstart,
+     customer need vs engineering reality, or something else. Do not
+     import a foil from a reference script.
 
   6. STALE CITATIONS. Cited Gemini 1.5 (2024), Llama 2 (2023), GPT-3
      (2020). The video is being made in April 2026. If you cite
@@ -186,33 +188,32 @@ BORING vs ENGAGING \u2014 concrete A/B examples
 
   HOOK
   Bad (academic):
-    "In 2024, Google DeepMind showed Gemini 1.5 Pro reading up to
-    1 million tokens. That sounds like a bigger brain. It is not."
-  Good (specific scene + character + stakes):
-    "It's 3 AM in March 2026. A junior engineer at OpenAI watches
-    her dashboard turn red as a single user pastes the entire
-    Twilight saga into GPT-5.5. Latency hits 41 seconds. The cost
-    counter ticks past 12 dollars for ONE response. She stares at
-    the number that explains why AI is getting more expensive even
-    though the models are getting cheaper. It's called KV Cache.
-    And right now, it's eating the company alive."
+    Open with a generic date, a vague capability, then a thesis.
+  Good (topic-native):
+    Open on the most cinematic pressure point THIS topic actually has:
+    a named launch day, a dashboard turning red, a failed demo, a court
+    filing, a supply-chain bottleneck, a customer behavior shift, a lab
+    result that contradicted intuition, or a single number that changes
+    the viewer's mental model. The hook type should be different when
+    the topic is a product race, a science mystery, a business collapse,
+    an algorithmic mechanism, or a social consequence.
 
   MECHANISM EXPLANATION
-  Bad: "Each new token has to compare against a long history."
-  Good: "Imagine typing the next word of an email, but before each
-    keystroke your laptop has to re-read every email you've sent
-    this year. That's what a transformer would do without KV Cache.
-    Now imagine your laptop wrote a single Post-it note for every
-    important word and stuck them on a desk. To type the next word,
-    it just glances at the desk. That's KV Cache. The Post-its are
-    the desk's secret. They're also the reason your AI bill has
-    exploded."
+  Bad: State the mechanism as a definition.
+  Good: Build the explanation from objects and constraints that belong
+    to THIS topic. If the topic is chips, show memory lanes, wafers,
+    racks, latency, heat, and cost. If the topic is biology, show cells,
+    assays, instruments, failure modes, and time. If the topic is a
+    company, show product decisions, customers, competitors, margins,
+    and distribution. The analogy is allowed only when it predicts the
+    mechanism better than the literal scene.
 
   SECTION TRANSITION (re-hook)
-  Bad: "Remember the open loop. We asked..."
-  Good: "Stop for a second. The thing we just described \u2014 that
-    desk full of Post-its \u2014 is now eating 80% of an H200's memory
-    on every long conversation. THAT'S the bill nobody talks about."
+  Bad: Repeat the same open-loop phrase.
+  Good: Re-hook with the specific unresolved pressure from the current
+    topic: the bill, the deadline, the missing proof, the user behavior,
+    the regulatory risk, the physical constraint, or the surprising
+    second-order effect.
 
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
 NON-NEGOTIABLE ENGAGEMENT RULES
@@ -272,7 +273,7 @@ H. CURRENT FACTS via web_search: BEFORE writing each chunk that
      OpenAI flagship       \u2192 GPT-5.5 (released April 23 2026)
      Anthropic flagship    \u2192 Claude Opus 4.7
      Meta open-weights     \u2192 Llama 4
-     Google                \u2192 Gemini 2.x family
+     Google                \u2192 Gemini 3.1
    USE WEB_SEARCH to verify. Don't trust your memory.
 
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
@@ -331,26 +332,24 @@ RETENTION PRINCIPLES (these govern every decision you make)
    question. You should have 3-5 of these naturally distributed.
 
 3. ONE DOMINANT METAPHOR \u2014 TEACHING, NOT DECORATION:
-   Pick ONE concrete analogy before you start writing. Thread it
-   through every section. Every time the mechanism gets technical,
-   bend back to the metaphor to scaffold understanding.
+   Pick ONE concrete analogy before you start writing. It must be
+   contextual to THIS topic, not a reusable prep-scene frame.
+   Thread it through every section only if it keeps teaching;
+   otherwise use concrete product scenes and named artifacts.
 
    The metaphor MUST DO WORK \u2014 it must PREDICT the mechanism, not
    merely label it.
 
-   BAD (decoration): "Like our metaphorical chef in the kitchen,
-                      KV Cache speeds things up."
-   GOOD (teaching):  "If our chef can grab pre-prepped ingredients
-                      without looking, what happens when fifty orders
-                      come in at once? Each new order needs the same
-                      lookups \u2014 but the prep is already done. That is
-                      exactly what KV Cache does: it computes each
-                      key-value pair once, then reuses them across
-                      every subsequent token."
+   BAD (decoration): "This mechanism is just a speed-up shortcut."
+   GOOD (teaching):  The viewer can predict what happens next because the
+                      metaphor maps cleanly to the topic's actual parts:
+                      who/what moves, what gets cached or constrained,
+                      what fails under scale, and why the final tradeoff
+                      matters. If the literal domain already has strong
+                      objects and scenes, use those instead of an analogy.
 
-   Banned: the word "metaphorical". The word "akin to" used more
-   than once. Phrases like "back to our chef" used as filler instead
-   of as a vehicle for predicting the next mechanism.
+   Banned: food-prep/cooking language, the word "metaphorical", the word "akin to"
+   used more than once, and "back to our X" filler.
 
    Pick your metaphor in a pre-planning step before you write chunk 1.
    Good metaphor tests: (a) can a non-expert picture it in 2 seconds?
@@ -398,10 +397,9 @@ facts. Examples of stale defaults to avoid:
 
 If web search is unavailable AND you cannot verify a specific current
 name, prefer a generic descriptor over a stale specific:
-  Bad:  "GPT-4 uses KV Cache to speed inference."
-  Good: "The current generation of frontier LLMs \u2014 including OpenAI's
-         flagship and Anthropic's Opus tier \u2014 relies on KV Cache to
-         speed inference."
+  Bad:  "GPT-4 is the current example."
+  Good: "Use a generic current-generation descriptor unless you can
+         verify the exact April 2026 model, product, or paper name."
 
 A wrong stale name is worse than a true descriptor.
 
@@ -418,7 +416,7 @@ ${banList}
 
 ALSO BANNED (regardless of channel DNA):
   - "Imagine teaching a..." / "Imagine taking..." / "Imagine a..."
-  - "Step into the kitchen of..." / "Step into the world of..."
+  - "Step into the world of..." / generic doorstep openers
   - "back to our metaphorical..." / "our metaphorical X"
   - "akin to" used more than once total
   - "Are we prepared for..." / "What if..." as section openers
@@ -434,7 +432,8 @@ STRUCTURE (choose the format that serves THIS topic \u2014 do NOT default)
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
 
 You have multiple formats available. Pick the one this topic is best
-suited to. Do NOT default to Tesla-style "history \u2192 bet \u2192 stakes".
+suited to. Do NOT default to any fixed sample sequence unless THIS topic
+truly demands it.
 
   A. COUNTER-INTUITIVE (Veritasium mode)
      Hook with a wrong-sounding claim. Challenge viewer's intuition.
@@ -497,7 +496,7 @@ PER-CHUNK FIELDS (output JSON \u2014 no extra commentary, no markdown)
     "metaphor":       the single video-wide metaphor you chose (string, same value on every chunk),
     "openLoopId":     present on the chunk that plants a loop + on the chunk that pays it off. Same id links them.
     "imagePromptHints": [
-      "3-5 teaching-oriented image prompts for THIS chunk. Each should illustrate the concept, not decorate it. Example (KV Cache): 'A chef mid-service at a high-end restaurant, every ingredient prepped and labeled in steel containers, hands reaching without looking \u2014 represents instant key-value lookup.' NOT 'glowing neural network nodes over dark background.' Write prompts that a cinematographer could use to teach a 12-year-old the concept."
+      "3-5 teaching-oriented image prompts for THIS chunk. Each should illustrate the concept, not decorate it. Make every prompt contextual to the chunk's actual domain: the real product, place, person, machine, document, material, interface, or physical constraint that the narration is about. Use a metaphor only if it teaches the mechanism better than literal domain visuals. Do not use food-prep scenes or glowing neural-network-node wallpaper. Write prompts that a cinematographer could use to teach a 12-year-old the concept."
     ]
   }
 ]
@@ -841,7 +840,7 @@ async function devCommand(options) {
   }
   void (async () => {
     try {
-      const { gatherCliUsage, CLI_USAGE_PARSER_VERSION } = await import("./cli-usage-P3LK7WEE.js");
+      const { gatherCliUsage, CLI_USAGE_PARSER_VERSION } = await import("./cli-usage-FG3YUG3W.js");
       const report = await gatherCliUsage();
       const g = global;
       g.__forgeCliUsageCache = { at: Date.now(), ver: CLI_USAGE_PARSER_VERSION, data: report };
@@ -877,7 +876,7 @@ async function devCommand(options) {
     const pathname = url.pathname;
     if (pathname === "/api/cli-usage") {
       try {
-        const { gatherCliUsage, CLI_USAGE_PARSER_VERSION } = await import("./cli-usage-P3LK7WEE.js");
+        const { gatherCliUsage, CLI_USAGE_PARSER_VERSION } = await import("./cli-usage-FG3YUG3W.js");
         const g = global;
         const now = Date.now();
         if (g.__forgeCliUsageCache && g.__forgeCliUsageCache.ver === CLI_USAGE_PARSER_VERSION && now - g.__forgeCliUsageCache.at < 3e4) {
@@ -1615,7 +1614,7 @@ Return ONLY the complete updated TSX. No markdown fences, no explanation.`;
         return "0.0.0";
       })();
       void (async () => {
-        const { BridgePoller } = await import("./bridge-poller-MCXVVFXL.js");
+        const { BridgePoller } = await import("./bridge-poller-WEKSUZMT.js");
         const poller = new BridgePoller({ baseUrl: bridgeUrl, token: bridgeToken, clientVersion: `storyforge ${pkgVersion}` });
         poller.start();
       })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyforge",
-  "version": "0.4.21",
+  "version": "0.5.3",
   "description": "StoryForge — local bridge for the Forge video production web app. Zero runtime dependencies.",
   "type": "module",
   "bin": {

package/dist/bridge-poller-MCXVVFXL.js

@@ -1,206 +0,0 @@
-#!/usr/bin/env node
-import {
-  log
-} from "./chunk-GJQ45C5W.js";
-
-// src/bridge-poller.ts
-import { spawn, spawnSync } from "child_process";
-import * as crypto from "crypto";
-var HEARTBEAT_INTERVAL_MS = 6e4;
-var POLL_INTERVAL_MS = 8e3;
-var CLI_TIMEOUT_MS = Number(process.env.SCRIPT_GEN_TIMEOUT_MS) || 20 * 60 * 1e3;
-var BridgePoller = class {
-  baseUrl;
-  token;
-  clientVersion;
-  instanceId;
-  heartbeatTimer = null;
-  pollTimer = null;
-  inFlight = /* @__PURE__ */ new Set();
-  stopped = false;
-  constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
-    this.token = opts.token;
-    this.clientVersion = opts.clientVersion;
-    this.instanceId = `${process.pid}-${crypto.randomBytes(2).toString("hex")}-${Date.now()}`;
-  }
-  start() {
-    if (this.heartbeatTimer || this.pollTimer) return;
-    log.info(`[bridge] poller starting \xB7 ${this.baseUrl} \xB7 instance=${this.instanceId}`);
-    void this.heartbeat();
-    this.heartbeatTimer = setInterval(() => {
-      void this.heartbeat();
-    }, HEARTBEAT_INTERVAL_MS);
-    this.pollTimer = setInterval(() => {
-      void this.poll();
-    }, POLL_INTERVAL_MS);
-  }
-  async stop() {
-    this.stopped = true;
-    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-    if (this.pollTimer) clearInterval(this.pollTimer);
-    this.heartbeatTimer = null;
-    this.pollTimer = null;
-  }
-  probeBinary(name) {
-    if (!/^[a-z][a-z0-9-]*$/i.test(name)) return { available: false, path: null };
-    const r = spawnSync("which", [name], { encoding: "utf-8", timeout: 2e3 });
-    if (r.status !== 0) return { available: false, path: null };
-    const path = (r.stdout ?? "").trim();
-    return { available: !!path, path: path || null };
-  }
-  async heartbeat() {
-    if (this.stopped) return;
-    try {
-      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/heartbeat`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          availableClis: {
-            claude: this.probeBinary("claude"),
-            codex: this.probeBinary("codex")
-          },
-          clientVersion: this.clientVersion,
-          instanceId: this.instanceId
-        }),
-        signal: AbortSignal.timeout(45e3)
-      });
-      if (!resp.ok) {
-        const text = await resp.text().catch(() => "");
-        log.warn(`[bridge] heartbeat HTTP ${resp.status}: ${text.slice(0, 120)}`);
-      }
-    } catch (err) {
-      log.warn(`[bridge] heartbeat failed: ${err.message}`);
-    }
-  }
-  async poll() {
-    if (this.stopped) return;
-    let jobs = [];
-    try {
-      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/claim`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ instanceId: this.instanceId, limit: 3 }),
-        signal: AbortSignal.timeout(45e3)
-      });
-      if (!resp.ok) {
-        if (resp.status === 401) {
-          log.warn("[bridge] 401 \u2014 bridge token rejected. Stopping poller. Set BRIDGE_TOKEN to the value Vercel has and restart.");
-          await this.stop();
-          return;
-        }
-        const text = await resp.text().catch(() => "");
-        log.warn(`[bridge] claim HTTP ${resp.status}: ${text.slice(0, 120)}`);
-        return;
-      }
-      const data = await resp.json();
-      jobs = data.jobs ?? [];
-    } catch (err) {
-      log.warn(`[bridge] claim failed: ${err.message}`);
-      return;
-    }
-    if (jobs.length === 0) return;
-    await Promise.all(jobs.map((job) => this.runJob(job)));
-  }
-  async runJob(job) {
-    if (this.inFlight.has(job.id)) return;
-    this.inFlight.add(job.id);
-    log.info(`[bridge] running job ${job.id.slice(0, 8)} \xB7 ${job.cli}${job.model ? `:${job.model}` : ""}`);
-    const startedAt = Date.now();
-    try {
-      const { text, modelUsed, error } = await this.invokeCli(job.cli, job.model, job.prompt);
-      const latencyMs = Date.now() - startedAt;
-      await this.respond(job.id, { text, modelUsed, latencyMs, error });
-      if (error) {
-        log.warn(`[bridge] job ${job.id.slice(0, 8)} failed (${latencyMs}ms): ${error.slice(0, 120)}`);
-      } else {
-        log.success(`[bridge] job ${job.id.slice(0, 8)} done (${latencyMs}ms \xB7 ${modelUsed})`);
-      }
-    } catch (err) {
-      const latencyMs = Date.now() - startedAt;
-      await this.respond(job.id, { error: err.message, latencyMs });
-    } finally {
-      this.inFlight.delete(job.id);
-    }
-  }
-  async invokeCli(cli, model, prompt) {
-    const candidates = cli === "codex" ? model && /^[a-z0-9.\-]+$/i.test(model) ? [model] : ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"] : model && /^[a-z0-9-]+$/i.test(model) ? [model] : ["opus", "sonnet"];
-    let lastErr = "";
-    for (const m of candidates) {
-      try {
-        const args = cli === "codex" ? ["exec", "-", "--model", m, "--search"] : [
-          "-p",
-          "--model",
-          m,
-          "--no-session-persistence",
-          "--allowedTools",
-          "WebSearch,WebFetch"
-        ];
-        const text = await runSpawn(cli, args, prompt, CLI_TIMEOUT_MS);
-        if (text.trim()) return { text, modelUsed: `${cli}:${m}` };
-        lastErr = `${cli}/${m} returned empty stdout`;
-      } catch (err) {
-        lastErr = `${cli}/${m}: ${err.message}`;
-      }
-    }
-    return { error: lastErr || "no model produced output" };
-  }
-  async respond(jobId, body) {
-    try {
-      const resp = await fetch(`${this.baseUrl}/api/cli-bridge/respond`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ jobId, ...body }),
-        signal: AbortSignal.timeout(45e3)
-      });
-      if (!resp.ok) {
-        const text = await resp.text().catch(() => "");
-        log.warn(`[bridge] respond HTTP ${resp.status}: ${text.slice(0, 120)}`);
-      }
-    } catch (err) {
-      log.warn(`[bridge] respond failed for ${jobId.slice(0, 8)}: ${err.message}`);
-    }
-  }
-};
-function runSpawn(cmd, args, stdin, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    const proc = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => {
-      try {
-        proc.kill("SIGKILL");
-      } catch {
-      }
-      reject(new Error(`${cmd} timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-    proc.stdout.on("data", (d) => {
-      stdout += d.toString("utf-8");
-    });
-    proc.stderr.on("data", (d) => {
-      stderr += d.toString("utf-8");
-    });
-    proc.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
-    proc.on("close", (code) => {
-      clearTimeout(timer);
-      if (code !== 0) reject(new Error(`${cmd} exit ${code}: ${stderr.slice(-300)}`));
-      else resolve(stdout);
-    });
-    proc.stdin.end(stdin);
-  });
-}
-export {
-  BridgePoller
-};