osborn 0.9.251 → 0.9.252

package/dist/content/content-run.js

@@ -0,0 +1,321 @@
+/**
+ * content-run.ts — Stage A orchestrator ("content plan"): step 3 of the
+ * compaction-lens worker, after the library step, and the --content CLI entry.
+ *
+ *   period page (library) → plan pieces → research per topic (demand + §8a
+ *   problems, cited, 7-day cache) → briefs (viewer, tier, format, stake) →
+ *   scripts (≤1 highlight + ≤3 how-tos) → checks (length, dev-voice pre-pass,
+ *   structure, pinned truth-check, audience) → ingest clean drafts (text_post).
+ *
+ * NEVER throws. Idempotent per period via .content-manifest.json (library dir):
+ * a done period costs nothing; settled pieces are never regenerated; a blocked
+ * piece is never ingested and never auto-fixed. Caps ⇒ status "capped".
+ * Flags: OSBORN_CONTENT_PIPELINE (default ON), OSBORN_CONTENT_LENS, OSBORN_CONTENT_INGEST,
+ * OSBORN_CONTENT_STRICT=1 (quality gates block again instead of flagging the draft).
+ * --dry: everything except the ingest (it still spends; the caps apply).
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import Database from 'better-sqlite3';
+import { loadConversationRows, recordView, resolveSessionDb } from './lens-db.js';
+import { readCompactionBoundaries } from './lens-period-boundaries.js';
+import { pageFileName, segmentPeriods } from './lens-library-select.js';
+import { libraryDirFor, readManifest } from './lens-library.js';
+import { CapError, contentCaps, daySpent, genModel, isContentPipelineEnabled, isContentStrict, SpendGuard } from './content-llm.js';
+import { makeScrubber } from './content-redact.js';
+import { CONTENT_DIR, isPieceSettled, periodDirName, periodStatusFor, readContentManifest, writeAtomic, writeContentManifest, } from './content-manifest.js';
+import { buildBriefs, loadOwner, planPieces } from './content-brief.js';
+import { researchCitations, researchDigest, researchTopic } from './content-research.js';
+import { writeScript } from './content-script.js';
+import { runChecks } from './content-checks.js';
+import { ingestScript, isIngestConfigured, pieceContentHash, scriptMarkdown } from './content-ingest.js';
+import { needsIngest } from './lens-ingest.js';
+import { privateSegments } from './content-query-gate.js';
+export { isContentPipelineEnabled } from './content-llm.js';
+/** Stop starting new calls after ~25 minutes; what is left resumes on the next run. */
+export const CONTENT_BUDGET_MS = 25 * 60_000;
+const PAGE_RANGE_RE = /Rows in block: #(\d+)[–-]#(\d+)/;
+/**
+ * Pick the period: the hand-off when given, else the newest of the last three
+ * periods that has a library page on disk and is not done here.
+ */
+export function pickContentPeriod(db, sessionId, dir, m, handoff) {
+    const isDone = (start) => ['done', 'no-pieces'].includes(m.periods[String(start)]?.status ?? '');
+    const hasPage = (p) => existsSync(join(dir, pageFileName(p)));
+    if (handoff) {
+        if (!hasPage(handoff))
+            return { period: null, reason: 'no-page' };
+        return isDone(handoff.startRowId) ? { period: null, reason: 'already-done' } : { period: handoff, page: pageFileName(handoff) };
+    }
+    const rows = loadConversationRows(db, 0).records.map(r => ({ id: r.id, timestamp: r.timestamp }));
+    const seg = segmentPeriods(rows, readCompactionBoundaries(db));
+    const lib = readManifest(dir, sessionId);
+    const recent = [...(seg.tail ? [seg.tail] : []), ...[...seg.closed].reverse()].slice(0, 3);
+    let done = false;
+    for (const p of recent) {
+        const le = lib.periods[String(p.startRowId)];
+        if ((le && le.status !== 'ok') || !hasPage(p))
+            continue;
+        if (!isDone(p.startRowId))
+            return { period: p, page: pageFileName(p) };
+        done = true;
+    }
+    return { period: null, reason: done ? 'already-done' : 'no-page' };
+}
+/** The row range the page itself states (manual backfill pages can run past the segment end). */
+export function pageRange(page, p) {
+    const m = page.match(PAGE_RANGE_RE);
+    const a = m ? Number(m[1]) : NaN;
+    const b = m ? Number(m[2]) : NaN;
+    return { from: Number.isFinite(a) ? Math.min(a, p.startRowId) : p.startRowId, to: Number.isFinite(b) ? Math.max(b, p.endRowId) : p.endRowId };
+}
+/** The session's working directories (session.db cwd column) — for the outbound-query gate. Best-effort. */
+function sessionCwds(db) {
+    try {
+        const d = new Database(db, { readonly: true, fileMustExist: true });
+        try {
+            return d.prepare('SELECT DISTINCT cwd FROM content WHERE cwd IS NOT NULL AND cwd != \'\' LIMIT 20').all().map(r => String(r.cwd));
+        }
+        finally {
+            d.close();
+        }
+    }
+    catch {
+        return [];
+    }
+}
+/** Truth-check ground truth: the page, the rows the script draws on, and the research it speaks to. */
+export function truthSources(page, records, brief, script, researchText) {
+    const cited = new Set(script.lines.map(l => l.row).filter((r) => !!r));
+    const inRange = records.filter(r => cited.has(r.id) || (r.id >= brief.fromRow && r.id <= brief.toRow));
+    let used = 0;
+    const rows = [];
+    for (const r of inRange) {
+        const v = recordView(r);
+        if (used + v.length > 30_000 && !cited.has(r.id))
+            continue;
+        used += v.length;
+        rows.push(v);
+    }
+    return [`LIBRARY PAGE (period map of the session):\n${page.slice(0, 40_000)}`, `SESSION ROWS:\n${rows.join('\n\n')}`, researchText ? `RESEARCH (public threads):\n${researchText}` : ''].filter(Boolean).join('\n\n');
+}
+function scrubScript(s, sc) {
+    return { ...s, title: sc.scrub(s.title), hook: sc.scrub(s.hook), lines: s.lines.map(l => ({ ...l, text: sc.scrub(l.text) })), causes: s.causes.map(sc.scrub), terms: s.terms.map(sc.scrub) };
+}
+const report = (p, d) => ({
+    id: p.id, tier: p.kind, status: p.status, title: p.title, flags: p.flags,
+    seconds: d?.script.estSeconds ?? null, citations: d?.citations.length ?? 0, file: p.file ?? null,
+});
+function readDraft(dir, p) {
+    if (!p.file)
+        return null;
+    try {
+        return JSON.parse(readFileSync(join(dir, p.file), 'utf-8')).draft ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist one piece's draft (JSON for retries + markdown for review). Returns the path relative to the library dir. */
+function saveDraft(dir, d, piece) {
+    const rel = join(CONTENT_DIR, periodDirName(d.period.index), `${piece.id}.json`);
+    mkdirSync(dirname(join(dir, rel)), { recursive: true });
+    writeAtomic(join(dir, rel), JSON.stringify({ status: piece.status, flags: piece.flags, draft: d }, null, 2) + '\n');
+    const flags = piece.flags.length ? `\n\n## BLOCKED — ${piece.flags.length} flag(s), not ingested\n${piece.flags.map(f => `- ${f}`).join('\n')}\n` : '\n';
+    writeAtomic(join(dir, rel.replace(/\.json$/, '.md')), scriptMarkdown(d) + flags);
+    return rel;
+}
+/** Free retry pass: "ready" pieces whose ingest never landed. No model call. Returns true if anything changed. */
+async function retryIngests(dir, m, sc, log, skipKey) {
+    if (!isIngestConfigured())
+        return false;
+    let changed = false;
+    for (const [key, e] of Object.entries(m.periods)) {
+        if (key === skipKey)
+            continue;
+        for (const p of Object.values(e.pieces)) {
+            if (p.status !== 'ready' || !p.contentHash || !needsIngest(p.ingest, p.contentHash))
+                continue;
+            const d = readDraft(dir, p);
+            if (!d)
+                continue;
+            p.ingest = await ingestScript(d, sc.scrubDeep, { log });
+            if (p.ingest.status === 'ok')
+                p.status = 'ingested';
+            changed = true;
+        }
+        if (changed && e.status === 'partial' && !Object.values(e.pieces).some(p => p.status !== 'ingested' && p.status !== 'blocked'))
+            e.status = 'done';
+    }
+    return changed;
+}
+/** Run Stage A once for one period. Never throws. */
+export async function runContentStep(o) {
+    const log = o.log ?? (() => { });
+    const deadline = Date.now() + (o.budgetMs ?? CONTENT_BUDGET_MS);
+    const res = { status: 'failed', libraryDir: null, period: null, pieces: [], costUsd: 0, capHit: null, errors: [] };
+    const timer = o.keepAlive ? setInterval(o.keepAlive, 60_000) : null;
+    timer?.unref();
+    let guard = null;
+    try {
+        if (!isContentPipelineEnabled())
+            return { ...res, status: 'disabled' };
+        const apiKey = (process.env.OPENROUTER_API_KEY || '').trim();
+        if (!apiKey)
+            return { ...res, status: 'no-key' };
+        const db = resolveSessionDb(o.sessionId, o.projectDir, o.cwd);
+        if (!db)
+            return { ...res, status: 'no-db' };
+        const projectDir = dirname(dirname(dirname(db)));
+        const dir = (res.libraryDir = libraryDirFor(db, o.sessionId));
+        const sc = makeScrubber(projectDir);
+        const manifest = readContentManifest(dir, o.sessionId);
+        const pick = pickContentPeriod(db, o.sessionId, dir, manifest, o.period);
+        if ('reason' in pick) {
+            if (!o.dry && (await retryIngests(dir, manifest, sc, log)))
+                writeContentManifest(dir, manifest);
+            log(`content: nothing to do (${pick.reason})`);
+            return { ...res, status: pick.reason };
+        }
+        const p = pick.period;
+        const key = String(p.startRowId);
+        const pageText = sc.scrub(readFileSync(join(dir, pick.page), 'utf-8'));
+        const range = pageRange(pageText, p);
+        const period = (res.period = { index: p.index, startRowId: p.startRowId, endRowId: range.to, page: pick.page });
+        const entry = manifest.periods[key] ?? {
+            startRowId: p.startRowId, endRowId: range.to, index: p.index, page: pick.page, status: 'error', costUsd: 0, pieces: {}, errors: [], updatedAt: '',
+        };
+        entry.errors = [];
+        manifest.periods[key] = entry;
+        const caps = contentCaps();
+        const g = (guard = new SpendGuard(projectDir, caps, entry.costUsd, deadline));
+        const llm = { apiKey, guard: g, scrub: sc.scrub, log };
+        const save = () => {
+            entry.costUsd = Number(g.periodUsd.toFixed(6));
+            entry.updatedAt = new Date().toISOString();
+            writeContentManifest(dir, manifest);
+        };
+        log(`content: period ${p.index} rows #${range.from}–#${range.to} (${pick.page}); spent so far $${entry.costUsd.toFixed(4)} period / $${daySpent().toFixed(4)} today (machine)`);
+        const records = loadConversationRows(db, range.from - 1, sc.scrub, range.to).records;
+        // 1. Plan → research → briefs, once per period.
+        let plan = entry.plan;
+        if (!plan?.briefs) {
+            try {
+                const { candidates } = await planPieces(pageText, range, caps.maxPieces, llm);
+                const research = new Map();
+                // Project basename, slug and every cwd path segment: queries naming any of them never leave the machine.
+                const privateTerms = privateSegments([o.cwd, process.env.OSBORN_CWD, basename(projectDir), ...sessionCwds(db)]);
+                for (const c of candidates) {
+                    o.keepAlive?.();
+                    research.set(c.id, await researchTopic({ subtopic: c.subtopic, queries: c.queries }, { projectDir, llm, refresh: o.researchRefresh, privateTerms }));
+                }
+                const { briefs } = await buildBriefs(candidates, research, loadOwner(projectDir), llm);
+                plan = { candidates, briefs, research: Object.fromEntries([...research].map(([id, r]) => [id, { key: r.key, digest: researchDigest(r), citations: researchCitations(r) }])) };
+                entry.plan = plan;
+            }
+            catch (e) {
+                if (e instanceof CapError)
+                    res.capHit = e.cap;
+                else
+                    res.errors.push(`plan: ${e?.message ?? e}`);
+                entry.status = e instanceof CapError ? 'capped' : 'error';
+                entry.errors = [...res.errors];
+                save();
+                log(`content: planning stopped (${entry.status}) ${res.errors.join('; ')}`);
+                return { ...res, status: entry.status, costUsd: g.runUsd };
+            }
+        }
+        // 2. Script + checks per piece (settled pieces are never regenerated).
+        const drafts = new Map();
+        let capped = false;
+        for (const b of plan.briefs.slice(0, caps.maxPieces)) {
+            const prev = entry.pieces[b.id];
+            if (isPieceSettled(prev))
+                continue;
+            const piece = {
+                id: b.id, kind: b.tier, status: 'error', title: prev?.title || b.subtopic, flags: [], warnings: [], costUsd: prev?.costUsd ?? 0, errors: [],
+                updatedAt: new Date().toISOString(), contentHash: pieceContentHash(o.sessionId, p.startRowId, b.id),
+            };
+            entry.pieces[b.id] = piece;
+            if (capped) {
+                piece.status = 'capped';
+                continue;
+            }
+            if (!b.stake && isContentStrict()) {
+                // Strict: WHAT-WORKS rule 1, no provable before/after ⇒ not scripted (no spend). Default: scripted, flagged "no visible proof".
+                piece.status = 'blocked';
+                piece.flags = ['brief has no before -> after stake quantity (rule 1: stake and proof both visible)'];
+                continue;
+            }
+            const r = plan.research[b.id];
+            const before = g.runUsd;
+            try {
+                o.keepAlive?.();
+                const { script: raw } = await writeScript(b, pageText, records, r?.digest ?? '', llm);
+                const script = scrubScript(raw, sc);
+                piece.title = script.title || piece.title;
+                const sources = truthSources(pageText, records, b, script, r?.digest ?? '');
+                const { summary, flags, warnings } = await runChecks(script, b, { projectDir, llm, records, sources });
+                piece.checks = summary;
+                piece.flags = flags;
+                piece.warnings = warnings;
+                piece.status = flags.length ? 'blocked' : 'ready';
+                const draft = { sessionId: o.sessionId, projectDir, period, brief: b, script, checks: summary, qualityFlags: warnings, citations: r?.citations ?? [], model: genModel() };
+                piece.file = saveDraft(dir, draft, piece);
+                drafts.set(b.id, draft);
+                log(`content: ${b.id} → ${piece.status}${flags.length ? ` (${flags.length} flag(s))` : ''}${warnings.length ? ` (${warnings.length} quality warning(s))` : ''} ~${script.estSeconds}s`);
+            }
+            catch (e) {
+                if (e instanceof CapError) {
+                    capped = true;
+                    res.capHit = e.cap;
+                    piece.status = 'capped';
+                }
+                else {
+                    piece.errors = [String(e?.message ?? e)];
+                    res.errors.push(`${b.id}: ${e?.message ?? e}`);
+                }
+                log(`content: ${b.id} → ${piece.status}${piece.errors.length ? ` ${piece.errors[0]}` : ''}`);
+            }
+            finally {
+                piece.costUsd = Number((piece.costUsd + g.runUsd - before).toFixed(6));
+                piece.updatedAt = new Date().toISOString();
+            }
+            save();
+        }
+        // 3. Ingest clean pieces (never blocked ones). Dry: no ingest.
+        let ingestPending = false;
+        if (!o.dry) {
+            for (const pe of Object.values(entry.pieces)) {
+                if (pe.status !== 'ready' || (pe.ingest && pe.contentHash && !needsIngest(pe.ingest, pe.contentHash)))
+                    continue;
+                const d = drafts.get(pe.id) ?? readDraft(dir, pe);
+                if (!d)
+                    continue;
+                pe.ingest = await ingestScript(d, sc.scrubDeep, { log });
+                if (pe.ingest.status === 'ok')
+                    pe.status = 'ingested';
+                else if (pe.ingest.status === 'error')
+                    ingestPending = true;
+            }
+            await retryIngests(dir, manifest, sc, log, key);
+        }
+        entry.status = periodStatusFor(entry, { dry: !!o.dry, planned: true, ingestPending });
+        entry.errors = [...res.errors];
+        save();
+        res.status = entry.status;
+        res.pieces = Object.values(entry.pieces).map(pe => report(pe, drafts.get(pe.id) ?? readDraft(dir, pe)));
+        res.costUsd = g.runUsd;
+        log(`content: period ${p.index} → ${res.status} pieces=${res.pieces.map(x => `${x.id}:${x.status}`).join(',') || 'none'} $${g.runUsd.toFixed(4)}`);
+        return res;
+    }
+    catch (e) {
+        res.errors.push(String(e?.message ?? e));
+        log(`content: failed (fail-open): ${e?.message ?? e}`);
+        return { ...res, status: 'failed', costUsd: guard?.runUsd ?? 0 };
+    }
+    finally {
+        if (timer)
+            clearInterval(timer);
+    }
+}

package/dist/content/content-script-rules.d.ts

@@ -0,0 +1,74 @@
+/**
+ * content-script-rules.ts — the WRITING rules, format catalog and per-tier
+ * templates for Stage A. Pure data, no pipeline logic.
+ *
+ * This module is the drop-in point for prompt improvements: the separate
+ * "what makes a video postable" analysis replaces/extends SCRIPT_RULES and the
+ * TIER_TEMPLATES beats here without touching content-brief / content-script /
+ * content-run. Source of truth for everything below:
+ *   SYSTEM-content-rules.md (§2 catalog, §3 tiers, §4 audience, §5 story,
+ *   §6 ownership, §7 grounding, §8a problem research) and
+ *   SYSTEM-format-playbook-oct06.md (templates, ~2.5 words/s, audience anchor).
+ */
+export type Tier = 'highlight' | 'howto';
+/** Spoken pace used for every length estimate (playbook: about 2.5 words/s). */
+export declare const WORDS_PER_SECOND = 2.5;
+export interface TierSpec {
+    tier: Tier;
+    label: string;
+    /** Hard bounds on the estimated spoken length (seconds). */
+    minS: number;
+    maxS: number;
+    targetS: number;
+    /** Spoken-word target range from WHAT-WORKS (prompt guidance; the hard gate is minS/maxS). */
+    words: {
+        min: number;
+        max: number;
+    };
+    /** Dev-voice lines allowed (verbatim user rows only). */
+    devLines: {
+        min: number;
+        max: number;
+    };
+    /** The question the piece answers. */
+    promise: string;
+    beats: string[];
+    /** The budget line from WHAT-WORKS for this tier. */
+    budget: string;
+}
+/**
+ * Templates from WHAT-WORKS-video-writing-rules.md (round 2, gate PASS).
+ * Length note: the how-to's 400-440 words is ~160-176s at 2.5 words/s (renders run
+ * TTS at ~1.1x tempo, i.e. ~150s on screen), so its spoken bound is 140-180s.
+ */
+export declare const TIER_TEMPLATES: Record<Tier, TierSpec>;
+export interface ScriptLimits {
+    /** Minimum seconds of runtime per cause (WHAT-WORKS: ~40s). */
+    secondsPerCause: number;
+    maxCauses: Record<Tier, number>;
+    maxTermsPerMin: Record<Tier, number>;
+}
+/**
+ * Deterministic gate thresholds (STARTING VALUES from 12 videos + hand counts).
+ * Env overrides: OSBORN_CONTENT_SECONDS_PER_CAUSE, OSBORN_CONTENT_MAX_CAUSES_HIGHLIGHT,
+ * OSBORN_CONTENT_MAX_CAUSES_HOWTO, OSBORN_CONTENT_TERMS_PER_MIN_HIGHLIGHT, OSBORN_CONTENT_TERMS_PER_MIN_HOWTO.
+ */
+export declare function scriptLimits(): ScriptLimits;
+export interface FormatEntry {
+    id: string;
+    name: string;
+    /** What the format needs from the inputs. */
+    needs: string;
+    beats: string;
+    whenToUse: string;
+    evidence: string;
+    tiers: Tier[];
+}
+/** Rules §2: every entry is first-class; none is the default. */
+export declare const FORMAT_CATALOG: FormatEntry[];
+/** Writing rules shared by every script prompt (rules §4, §5, §7). */
+export declare const SCRIPT_RULES: string[];
+export declare const BRIEF_RULES: string[];
+/** BRIEF_RULES for the current mode: under OSBORN_CONTENT_STRICT a missing stake blocks scripting, so say so. */
+export declare function briefRules(): string[];
+export declare const AUDIENCE_RULES: string;

package/dist/content/content-script-rules.js

@@ -0,0 +1,134 @@
+/**
+ * content-script-rules.ts — the WRITING rules, format catalog and per-tier
+ * templates for Stage A. Pure data, no pipeline logic.
+ *
+ * This module is the drop-in point for prompt improvements: the separate
+ * "what makes a video postable" analysis replaces/extends SCRIPT_RULES and the
+ * TIER_TEMPLATES beats here without touching content-brief / content-script /
+ * content-run. Source of truth for everything below:
+ *   SYSTEM-content-rules.md (§2 catalog, §3 tiers, §4 audience, §5 story,
+ *   §6 ownership, §7 grounding, §8a problem research) and
+ *   SYSTEM-format-playbook-oct06.md (templates, ~2.5 words/s, audience anchor).
+ */
+import { isContentStrict } from './content-llm.js';
+/** Spoken pace used for every length estimate (playbook: about 2.5 words/s). */
+export const WORDS_PER_SECOND = 2.5;
+/**
+ * Templates from WHAT-WORKS-video-writing-rules.md (round 2, gate PASS).
+ * Length note: the how-to's 400-440 words is ~160-176s at 2.5 words/s (renders run
+ * TTS at ~1.1x tempo, i.e. ~150s on screen), so its spoken bound is 140-180s.
+ */
+export const TIER_TEMPLATES = {
+    highlight: {
+        tier: 'highlight',
+        label: '61-90s highlight (narrated timeline)',
+        minS: 61,
+        maxS: 90,
+        targetS: 74,
+        words: { min: 155, max: 200 },
+        devLines: { min: 0, max: 2 },
+        promise: '"Is this possible? Here is how it went." A narrated TIMELINE of what happened, in order. NOT a chain of quotes.',
+        beats: [
+            'Line 1: the claim / paradox = the lesson, in plain words (not a bare number or status)',
+            'Line 2: the stake as a visible quantity or verdict (the BEFORE)',
+            'Line 3: setup, at most 1 new term, defined in the same line',
+            'Lines 4-5: the test, and the "before" result',
+            'Line 6: the cause, in one plain sentence',
+            'Lines 7-8: the fix, and the "after" with the SAME quantity as line 2',
+            'Line 9 (optional): a 2nd instance of the same cause, in line 6\'s words',
+            'Line 10: the rule the viewer can take away',
+            'Line 11: sign-off with the developer\'s name (when known)',
+        ],
+        budget: 'About 13 lines, 155-200 words. At most 2 causes, at most 3.5 load-bearing terms per minute (about 5 at 90s), no spoken versions or error codes, no standalone hedge.',
+    },
+    howto: {
+        tier: 'howto',
+        label: '~150s how-to ("if you\'re in this situation...")',
+        minS: 140,
+        maxS: 180,
+        targetS: 168,
+        words: { min: 400, max: 440 },
+        devLines: { min: 1, max: 6 },
+        promise: '"If you\'re in this situation, here\'s what we said, what happened, and how to do it." ONE specific, useful accomplishment, step by step.',
+        beats: [
+            'Line 1: "If you [situation], here\'s the trap: [claim]. Here\'s how we fixed ours."',
+            'Lines 2-3: the situation and the stake quantity (the BEFORE), in terms of the common problems from the research',
+            'Line 4: what we tried first, and its visible failure',
+            'Line 5: a human reaction or quote (verbatim dev line) that sets up the next beat',
+            'Line 6: the correction or surprise, restating the lesson',
+            'Line 7: the mechanism in firing order (at most 8 terms, each defined)',
+            'Line 8: the proof, the AFTER with the same quantity as line 2',
+            'Line 9 (optional): further instances, each entered by a trigger line (a quote, "you were right", a look at the log)',
+            'Line 10: "To do it yourself: One, Two, Three", each step mapping to a cause shown',
+            'Line 11: sign-off with the developer\'s name (when known)',
+        ],
+        budget: 'About 18 lines, 400-440 words. At most 3 causes, at most 3 load-bearing terms per minute, at most one optional extra instance.',
+    },
+};
+/**
+ * Deterministic gate thresholds (STARTING VALUES from 12 videos + hand counts).
+ * Env overrides: OSBORN_CONTENT_SECONDS_PER_CAUSE, OSBORN_CONTENT_MAX_CAUSES_HIGHLIGHT,
+ * OSBORN_CONTENT_MAX_CAUSES_HOWTO, OSBORN_CONTENT_TERMS_PER_MIN_HIGHLIGHT, OSBORN_CONTENT_TERMS_PER_MIN_HOWTO.
+ */
+export function scriptLimits() {
+    const n = (k, d) => {
+        const v = Number((process.env[k] ?? '').trim());
+        return (process.env[k] ?? '').trim() !== '' && Number.isFinite(v) && v > 0 ? v : d;
+    };
+    return {
+        secondsPerCause: n('OSBORN_CONTENT_SECONDS_PER_CAUSE', 40),
+        maxCauses: { highlight: n('OSBORN_CONTENT_MAX_CAUSES_HIGHLIGHT', 2), howto: n('OSBORN_CONTENT_MAX_CAUSES_HOWTO', 3) },
+        maxTermsPerMin: { highlight: n('OSBORN_CONTENT_TERMS_PER_MIN_HIGHLIGHT', 3.5), howto: n('OSBORN_CONTENT_TERMS_PER_MIN_HOWTO', 3) },
+    };
+}
+/** Rules §2: every entry is first-class; none is the default. */
+export const FORMAT_CATALOG = [
+    { id: 'narrated-timeline', name: 'Narrated timeline trailer', needs: 'one narrator voice; a clean ordered arc', beats: 'situation > goal > attempt > turn > result > lesson', whenToUse: 'a session arc with a clear before/after', evidence: 'v1 cheap-models narration (videos-test-1), user-approved style', tiers: ['highlight'] },
+    { id: 'two-voice-hud', name: 'Two-voice replay with a state HUD', needs: 'a single numeric/state quantity that changes; dev + agent lines', beats: 'cold open (explained) > stakes > attempt > break + clue > fix > proof > takeaway', whenToUse: 'stories with 3+ causal steps around one quantity', evidence: 'F2 memory seam (videos-test-2): HUD made cause->effect followable', tiers: ['highlight', 'howto'] },
+    { id: 'chat-log-replay', name: 'Chat/log replay with a narrator', needs: 'pivotal messages; narrator bridges', beats: 'pivotal message > rewind > context > escalating causes (each defined) > blameless close', whenToUse: 'disaster or surprise stories', evidence: 'Fang GitLab postmortem 3.61M views; F3 fleet sweep (videos-test-2)', tiers: ['highlight', 'howto'] },
+    { id: 'explainer-build', name: 'Explainer screens built up progressively', needs: 'a concept the viewer lacks', beats: 'each sentence ADDS one visual, never replaces', whenToUse: 'the viewer needs a mental model first', evidence: 'Azure tokens 114k on 12.8k subs', tiers: ['highlight', 'howto'] },
+    { id: 'test-scoreboard', name: 'Test and scoreboard', needs: 'a binary or numeric result', beats: 'question hook > stakes > attempt > test > scoreboard + proof > takeaway', whenToUse: 'a comparison with a clear score', evidence: 'F1 cheap models; small-creator ratio 0.05-0.4x (brand via series)', tiers: ['highlight'] },
+    { id: 'two-character-dialogue', name: 'Two-character dialogue', needs: 'real back-and-forth between dev and agent', beats: 'situation > exchange > turn > resolution', whenToUse: 'the conversation itself is the story', evidence: 'AI-convo outliers (Gibberlink 14.1M); no dev-niche proof yet', tiers: ['howto'] },
+    { id: 'chat-bubble', name: 'Chat-bubble / DM replay', needs: 'short dev and agent lines', beats: 'thread scrolls; narrator sets up each turn', whenToUse: 'quick exchanges that read well as text', evidence: 'under-supplied in dev niche (no data)', tiers: ['highlight', 'howto'] },
+    { id: 'audiogram', name: 'Audiogram (waveform + captions)', needs: 'TTS or real audio; captions', beats: 'one continuous spoken thread', whenToUse: 'a monologue-style explanation', evidence: 'catalog (untested)', tiers: ['howto'] },
+    { id: 'podcast-clip', name: 'Animated or avatar podcast clip', needs: 'two voices', beats: 'host frames > guest explains > host lands it', whenToUse: 'interview-style how-to', evidence: 'catalog (untested)', tiers: ['howto'] },
+    { id: 'unrelated-footage', name: 'Audio over unrelated footage', needs: 'a self-contained narrated track', beats: 'narration carries everything', whenToUse: 'broad-audience retention play', evidence: 'catalog (untested in dev niche)', tiers: ['highlight'] },
+    { id: 'phone-call', name: 'Phone-call style', needs: 'two voices, short turns', beats: 'call opens on the problem > back-and-forth > resolution', whenToUse: 'a help-desk style fix', evidence: 'catalog (untested)', tiers: ['howto'] },
+];
+/** Writing rules shared by every script prompt (rules §4, §5, §7). */
+export const SCRIPT_RULES = [
+    'WHO: write to the named viewer, someone living the situation. Context, not explaining every line: terms they already know need no setup; anything outside their world gets just enough setup nearby.',
+    'Every quote, term and number must be understandable to that viewer: either already known to that viewer or explained in the line before or right after it. A quote with no context for THAT viewer fails.',
+    'STORY: the cause -> effect chain must be clean. Every line is the next thing that happened or the reason for it. No unexplained jumps, numbers or version strings.',
+    'Hook placement is free (start, middle or end), but the hook must be explained.',
+    // WHAT-WORKS-video-writing-rules.md (round 2, gate PASS): the rules that separate postable videos from incoherent ones.
+    'STAKE AND PROOF, BOTH VISIBLE: show the problem as a quantity or verdict (the brief\'s stake BEFORE), then the SAME quantity after the fix (AFTER). E.g. 0/4 -> 4/4; bar full -> one fire; zero markers -> reject.',
+    'TERMS: at most ~3.5 load-bearing terms per minute (how-to: ~3), each defined in the line where it first appears.',
+    'CAUSES: at least ~40 seconds per cause. A cause is a distinct fault or catch needing its own fix. Under 60s: 1 cause; 61-90s: at most 2 (the 2nd only if it repeats the 1st\'s cause); ~150s: at most 3, each an instance of the lesson. Cut unrelated catches.',
+    'NO spoken software versions or error codes as story beats (no "0.9.73", "v2.1", "HTTP 502", "1006", "ENOENT") outside a verbatim dev line.',
+    'The CLAIM lands by line 2, in plain words. Do not open on a bare number or status. No standalone hedges.',
+    'GROUNDING: every claim must come from the SESSION material or the RESEARCH given. Never invent numbers, names, products, results or people. If unsure, leave it out.',
+    'Speak to the problems the research shows people actually hit; frame the solution against them.',
+    'DEV VOICE: speaker "dev" lines are copied VERBATIM from ONE user row given (same characters; you may cut words with " … " but every kept piece must be 12+ characters and the cuts must not change the meaning). Put that row number in "row". Never put the assistant\'s findings, or anything paraphrased, in the dev voice.',
+    'Speaker "agent" lines restate what the assistant did or found, plainly. Speaker "narrator" carries the timeline.',
+    'Client work stays redacted: keep tags like [client] as they are, never guess or reintroduce names, companies, IDs or amounts.',
+    'No secrets, keys, tokens, emails, URLs to private systems, or personal details.',
+    'Plain spoken English, short sentences, no markdown, no emojis, no stage directions inside "text".',
+];
+const STAKE_RULE = 'STAKE: name the before -> after quantity or verdict the piece will SHOW (e.g. "facts recalled: 0/4 -> 4/4"), taken from the session.';
+export const BRIEF_RULES = [
+    'Every brief starts with WHO is consuming it and what they are living through, picked from the research (who is living through it / common problems).',
+    'One highlight per period at most; how-tos only where the session shows ONE specific, useful accomplishment someone could copy.',
+    'Pick the format from the catalog by fit (what it needs vs. what the session has). No format is the default.',
+    'Pick the stretch of the session (row range) the piece is built from; dev lines can only come from user rows in it.',
+    `${STAKE_RULE} If the story has no provable before/after in the session, leave stake empty — the draft will be flagged "no visible proof".`,
+];
+/** BRIEF_RULES for the current mode: under OSBORN_CONTENT_STRICT a missing stake blocks scripting, so say so. */
+export function briefRules() {
+    if (!isContentStrict())
+        return BRIEF_RULES;
+    return BRIEF_RULES.map(r => (r.startsWith(STAKE_RULE) ? `${STAKE_RULE} If the story has no provable before/after in the session, leave stake empty — it will not be scripted.` : r));
+}
+export const AUDIENCE_RULES = 'AUDIENCE CHECK (rules §4): for the target viewer named below, is every quote or term either already familiar to them or set up nearby ' +
+    '(in the line before or right after)? A quote or term that lands with no context for THAT viewer fails. Familiar terms pass. ' +
+    'Also fail an unexplained number or version string.';

package/dist/content/content-script.d.ts

@@ -0,0 +1,61 @@
+/**
+ * content-script.ts — Stage A script generation: one script per brief.
+ * A period yields at most 1 highlight (61-90s narrated timeline) + up to 3
+ * how-tos (~150s "if you're in this situation…"); content-run enforces the count.
+ *
+ * Writing rules and per-tier beats come ONLY from content-script-rules.ts
+ * (SCRIPT_RULES / TIER_TEMPLATES), so they can be replaced without touching
+ * this logic. Dev-voice lines must be verbatim user rows: the model is shown
+ * row-tagged rows and must cite the row; content-checks.ts verifies every dev
+ * line deterministically before anything else runs. Throws CapError / Error.
+ */
+import { type DbRecord } from './lens-db.js';
+import { type ContentLlmOptions } from './content-llm.js';
+import { type Tier } from './content-script-rules.js';
+import type { Brief } from './content-brief.js';
+export type Speaker = 'narrator' | 'dev' | 'agent';
+export interface ScriptLine {
+    speaker: Speaker;
+    text: string;
+    /** Source row (required for dev lines). */
+    row?: number;
+}
+export interface Script {
+    id: string;
+    tier: Tier;
+    title: string;
+    hook: string;
+    lines: ScriptLine[];
+    /** Model-declared distinct causes (faults/catches needing their own fix) — gated by content-checks. */
+    causes: string[];
+    /** Model-declared load-bearing terms — gated per minute by content-checks. */
+    terms: string[];
+    words: number;
+    estSeconds: number;
+}
+export declare const countWords: (s: string) => number;
+export declare const estimateSeconds: (lines: Pick<ScriptLine, "text">[]) => number;
+export declare function tierBounds(tier: Tier): {
+    min: number;
+    max: number;
+    target: number;
+};
+export declare function lengthCheck(s: Pick<Script, 'tier' | 'lines'>): {
+    ok: boolean;
+    seconds: number;
+    min: number;
+    max: number;
+};
+/** Row-tagged session rows for the brief's range (widened to the whole period when thin), capped. */
+export declare function rowsForBrief(records: DbRecord[], brief: Pick<Brief, 'fromRow' | 'toRow'>): DbRecord[];
+export declare const SCRIPT_SYSTEM: string;
+export declare function scriptPrompt(brief: Brief, page: string, rows: DbRecord[], researchText: string): string;
+/** Tolerant parse of the model's reply into a Script. Never throws. */
+export declare function normalizeScript(raw: unknown, brief: Pick<Brief, 'id' | 'tier'>): Script;
+/** Generate one script. One model call. */
+export declare function writeScript(brief: Brief, page: string, records: DbRecord[], researchText: string, llm: ContentLlmOptions): Promise<{
+    script: Script;
+    costUsd: number;
+}>;
+/** Plain transcript (one line per spoken line) — the ingest `transcript` field. */
+export declare const scriptTranscript: (s: Script) => string;