@coppica/persuasion-mcp 1.0.1

package/data/trait-evidence.json

@@ -0,0 +1,187 @@
+{
+ "source": "Upworthy Research Archive (Matias, Munger, Le Quere, Ebersole 2021, Nature Scientific Data), CC BY 4.0",
+ "method": "Within-test trait analysis on the Upworthy Research Archive (CC BY 4.0, Matias et al. 2021).\nUnit = one test x one image (eyecatcher), so only headlines shown with the same image are compared.\nPackages need >= MIN_IMP impressions. For a binary trait, a unit votes 1 if its packages WITH the\ntrait have a higher pooled CTR than those without. For a continuous trait, the unit compares its\nhighest- and lowest-valued packages. Win rate > 50% = the trait tends to win. Tests in the\nbroken-randomization window (2013-06-25 .. 2014-01-10) are excluded.",
+ "min_impressions": 1000,
+ "traits": {
+  "number": {
+   "confirmatory_win_rate": 0.5443,
+   "confirmatory_n": 3316,
+   "ci95": [
+    0.5273,
+    0.5612
+   ],
+   "holdout_win_rate": 0.5811,
+   "holdout_n": 721,
+   "exploratory_win_rate": 0.5405,
+   "verdict": "REPLICATES wins"
+  },
+  "question": {
+   "confirmatory_win_rate": 0.3856,
+   "confirmatory_n": 4217,
+   "ci95": [
+    0.371,
+    0.4004
+   ],
+   "holdout_win_rate": 0.3619,
+   "holdout_n": 923,
+   "exploratory_win_rate": 0.3838,
+   "verdict": "REPLICATES loses"
+  },
+  "you": {
+   "confirmatory_win_rate": 0.487,
+   "confirmatory_n": 5010,
+   "ci95": [
+    0.4732,
+    0.5009
+   ],
+   "holdout_win_rate": 0.5032,
+   "holdout_n": 1099,
+   "exploratory_win_rate": 0.4876,
+   "verdict": "no reliable effect"
+  },
+  "first_person": {
+   "confirmatory_win_rate": 0.5001,
+   "confirmatory_n": 4475,
+   "ci95": [
+    0.4855,
+    0.5148
+   ],
+   "holdout_win_rate": 0.4964,
+   "holdout_n": 985,
+   "exploratory_win_rate": 0.4743,
+   "verdict": "no reliable effect"
+  },
+  "quotation": {
+   "confirmatory_win_rate": 0.4377,
+   "confirmatory_n": 361,
+   "ci95": [
+    0.3874,
+    0.4892
+   ],
+   "holdout_win_rate": 0.4177,
+   "holdout_n": 79,
+   "exploratory_win_rate": 0.4754,
+   "verdict": "no reliable effect"
+  },
+  "negation": {
+   "confirmatory_win_rate": 0.4996,
+   "confirmatory_n": 4548,
+   "ci95": [
+    0.485,
+    0.5141
+   ],
+   "holdout_win_rate": 0.5165,
+   "holdout_n": 999,
+   "exploratory_win_rate": 0.4839,
+   "verdict": "no reliable effect"
+  },
+  "superlative": {
+   "confirmatory_win_rate": 0.5334,
+   "confirmatory_n": 2261,
+   "ci95": [
+    0.5128,
+    0.5539
+   ],
+   "holdout_win_rate": 0.5382,
+   "holdout_n": 524,
+   "exploratory_win_rate": 0.5558,
+   "verdict": "no reliable effect"
+  },
+  "this_these": {
+   "confirmatory_win_rate": 0.5578,
+   "confirmatory_n": 5522,
+   "ci95": [
+    0.5446,
+    0.5708
+   ],
+   "holdout_win_rate": 0.5725,
+   "holdout_n": 1214,
+   "exploratory_win_rate": 0.5526,
+   "verdict": "REPLICATES wins"
+  },
+  "exclamation": {
+   "confirmatory_win_rate": 0.4034,
+   "confirmatory_n": 761,
+   "ci95": [
+    0.3691,
+    0.4387
+   ],
+   "holdout_win_rate": 0.3701,
+   "holdout_n": 154,
+   "exploratory_win_rate": 0.3576,
+   "verdict": "REPLICATES loses"
+  },
+  "emphasis_caps": {
+   "confirmatory_win_rate": 0.4178,
+   "confirmatory_n": 1776,
+   "ci95": [
+    0.3951,
+    0.4409
+   ],
+   "holdout_win_rate": 0.4474,
+   "holdout_n": 380,
+   "exploratory_win_rate": 0.4103,
+   "verdict": "REPLICATES loses"
+  },
+  "how_why_what": {
+   "confirmatory_win_rate": 0.4963,
+   "confirmatory_n": 5561,
+   "ci95": [
+    0.4832,
+    0.5095
+   ],
+   "holdout_win_rate": 0.5033,
+   "holdout_n": 1220,
+   "exploratory_win_rate": 0.5042,
+   "verdict": "no reliable effect"
+  },
+  "time_word": {
+   "confirmatory_win_rate": 0.5366,
+   "confirmatory_n": 2158,
+   "ci95": [
+    0.5155,
+    0.5576
+   ],
+   "holdout_win_rate": 0.5593,
+   "holdout_n": 447,
+   "exploratory_win_rate": 0.5441,
+   "verdict": "REPLICATES wins"
+  },
+  "old_scoreHook": {
+   "confirmatory_win_rate": 0.4632,
+   "confirmatory_n": 7726,
+   "ci95": [
+    0.4521,
+    0.4744
+   ],
+   "holdout_win_rate": 0.4949,
+   "holdout_n": 1673,
+   "exploratory_win_rate": 0.482,
+   "verdict": "no reliable effect"
+  },
+  "word_count": {
+   "confirmatory_win_rate": 0.5385,
+   "confirmatory_n": 9564,
+   "ci95": [
+    0.5285,
+    0.5485
+   ],
+   "holdout_win_rate": 0.5435,
+   "holdout_n": 2079,
+   "exploratory_win_rate": 0.5493,
+   "verdict": "REPLICATES wins"
+  },
+  "article_overlap": {
+   "confirmatory_win_rate": 0.5268,
+   "confirmatory_n": 9406,
+   "ci95": [
+    0.5167,
+    0.5369
+   ],
+   "holdout_win_rate": 0.5164,
+   "holdout_n": 2043,
+   "exploratory_win_rate": 0.5188,
+   "verdict": "no reliable effect"
+  }
+ }
+}

package/dist/data.d.ts

@@ -0,0 +1,81 @@
+import { type Role, type Format } from './roles.js';
+export interface Example {
+    brand: string;
+    year: string | null;
+    headline: string;
+    excerpt: string;
+    why: string;
+}
+export interface Technique {
+    slug: string;
+    pt_id: string;
+    name: string;
+    role: Role;
+    family: string | null;
+    parent: string | null;
+    lede: string;
+    what_it_does: string;
+    why_it_works: string;
+    lands_when: string;
+    dilutes_when: string;
+    examples: Example[];
+    sisters: {
+        pt_id: string;
+        name: string;
+    }[];
+    counters: {
+        pt_id: string;
+        name: string;
+    }[];
+    url: string;
+    brands: number;
+    channels: Record<string, number>;
+    /** distinct brands per persuasion mode, from the aggressive / balanced / equity opener tables */
+    modes: Partial<Record<Mode, number>>;
+}
+export type Mode = 'aggressive' | 'balanced' | 'equity';
+export type Tier = 'table_stakes' | 'common' | 'occasional' | 'less_common';
+export declare const CATALOG_META: Record<string, unknown>;
+export declare const TECHNIQUES: Technique[];
+export declare const CATEGORIES: Record<string, {
+    brands: number;
+    tiers: Record<string, Tier>;
+}>;
+export declare const CATEGORY_NAMES: string[];
+export declare const byRole: Map<"DISRUPT" | "IDENTIFY" | "AGITATE" | "REFRAME" | "PROVE" | "ELEVATE" | "RESOLVE" | "COMPEL" | "BOND", Technique[]>;
+export declare function lookupTechnique(id: string): Technique | null;
+/** Accept a category written loosely ("SaaS", "b2b saas", "skincare"). */
+export declare function resolveCategory(input?: string | null): string | null;
+export declare function tierIn(category: string | null, slug: string): Tier | null;
+export declare function prevalenceLabel(t: Technique, category: string | null): string;
+export declare function channelFit(t: Technique, format: Format | null): number;
+/** Share of a technique's opener appearances that come from aggressive-mode copy (null = too little data). */
+export declare function aggressiveShare(t: Technique): number | null;
+/** Multiplier that keeps hard-sell moves out of balanced and equity copy (Coppica's persuasion modes). */
+export declare function modeWeight(t: Technique, mode: Mode): number;
+export declare function searchTechniques(query: string, opts?: {
+    role?: Role | null;
+    format?: Format | null;
+    limit?: number;
+}): Technique[];
+export interface PickedMove {
+    t: Technique;
+    kind: 'established' | 'less_expected';
+}
+/**
+ * Options for answering one reader question: one established move plus less-expected ones.
+ * Ranked by relevance to the brief (BM25 over the brief or copy), fit to the format's
+ * channels in the corpus, and the persuasion mode; then diversified by family and a seed,
+ * so the same brief gets the same options and different briefs get different ones.
+ * "Less expected" = not the category default: the long tail a model would not reach for
+ * on its own (Theses IV, XIV). The calling model makes the final choice.
+ */
+export declare function pickMoves(role: Role, opts: {
+    n: number;
+    format: Format | null;
+    category: string | null;
+    seed: string;
+    context: string;
+    mode: Mode;
+    exclude?: Set<string>;
+}): PickedMove[];

package/dist/data.js

@@ -0,0 +1,207 @@
+/**
+ * The bundled catalog snapshot (data/*.json, written by scripts/export-catalog.mjs)
+ * plus in-memory search and move selection. No database, no network, no AI calls.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { ROLE_NAMES, FORMAT_CHANNELS } from './roles.js';
+const DATA_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'data');
+const catalogFile = JSON.parse(readFileSync(join(DATA_DIR, 'catalog.json'), 'utf8'));
+const categoriesFile = JSON.parse(readFileSync(join(DATA_DIR, 'categories.json'), 'utf8'));
+export const CATALOG_META = catalogFile.meta;
+export const TECHNIQUES = catalogFile.techniques;
+export const CATEGORIES = categoriesFile.categories;
+export const CATEGORY_NAMES = Object.keys(CATEGORIES).sort();
+const byPtId = new Map(TECHNIQUES.map((t) => [t.pt_id.toUpperCase(), t]));
+const bySlug = new Map(TECHNIQUES.map((t) => [t.slug.toLowerCase(), t]));
+const byName = new Map(TECHNIQUES.map((t) => [norm(t.name), t]));
+export const byRole = new Map(ROLE_NAMES.map((r) => [r, TECHNIQUES.filter((t) => t.role === r)]));
+function norm(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+export function lookupTechnique(id) {
+    const raw = id.trim();
+    return byPtId.get(raw.toUpperCase()) ?? bySlug.get(raw.toLowerCase().replace(/[\s-]+/g, '_')) ?? byName.get(norm(raw)) ?? null;
+}
+/** Accept a category written loosely ("SaaS", "b2b saas", "skincare"). */
+export function resolveCategory(input) {
+    if (!input)
+        return null;
+    const n = norm(input).replace(/ /g, '_');
+    if (CATEGORIES[n])
+        return n;
+    const hit = CATEGORY_NAMES.find((c) => c.includes(n) || n.includes(c) || c.replace(/_/g, '').includes(n.replace(/_/g, '')));
+    return hit ?? null;
+}
+export function tierIn(category, slug) {
+    if (!category)
+        return null;
+    return CATEGORIES[category]?.tiers[slug] ?? null;
+}
+export function prevalenceLabel(t, category) {
+    if (category) {
+        const tier = tierIn(category, t.slug);
+        const cat = category.replace(/_/g, ' ');
+        if (tier === 'table_stakes')
+            return `table stakes in ${cat}`;
+        if (tier === 'common')
+            return `common in ${cat}`;
+        if (tier === 'occasional')
+            return `occasional in ${cat}`;
+        if (tier === 'less_common')
+            return `less common in ${cat}`;
+        return `not seen in our ${cat} sample`;
+    }
+    if (t.brands >= 150)
+        return 'widely used';
+    if (t.brands >= 40)
+        return 'established';
+    return 'less common';
+}
+export function channelFit(t, format) {
+    if (!format)
+        return 0;
+    return FORMAT_CHANNELS[format].reduce((s, g) => s + (t.channels[g] ?? 0), 0);
+}
+// ── search (BM25 over name / lede / definitions / family) ─────────────────
+const STOP = new Set('a an the and or of to in on for with by is are be as at it its this that from your you their they them how what when why who make makes making use using get way ways do does into than more most less'.split(' '));
+function tokens(s) {
+    return norm(s).split(' ').filter((w) => w.length > 1 && !STOP.has(w)).map((w) => (w.length > 4 && w.endsWith('ies') ? w.slice(0, -3) + 'y' : w.length > 4 && w.endsWith('s') && !w.endsWith('ss') ? w.slice(0, -1) : w));
+}
+const FIELDS = [['name', 3], ['lede', 2], ['family', 1.5], ['what_it_does', 1], ['why_it_works', 0.5], ['lands_when', 0.5]];
+const docs = TECHNIQUES.map((t) => {
+    const tf = new Map();
+    let len = 0;
+    for (const [f, w] of FIELDS) {
+        const v = t[f];
+        if (typeof v !== 'string')
+            continue;
+        for (const tok of tokens(f === 'family' ? v.replace(/_/g, ' ') : v)) {
+            tf.set(tok, (tf.get(tok) ?? 0) + w);
+            len += w;
+        }
+    }
+    for (const e of t.examples) {
+        for (const tok of tokens(`${e.headline} ${e.why}`)) {
+            tf.set(tok, (tf.get(tok) ?? 0) + 0.4);
+            len += 0.4;
+        }
+    }
+    return { t, tf, len };
+});
+const avgLen = docs.reduce((s, d) => s + d.len, 0) / docs.length;
+const df = new Map();
+for (const d of docs)
+    for (const tok of d.tf.keys())
+        df.set(tok, (df.get(tok) ?? 0) + 1);
+function bm25(d, q) {
+    const N = docs.length;
+    let s = 0;
+    for (const tok of q) {
+        const f = d.tf.get(tok);
+        if (!f)
+            continue;
+        const idf = Math.log(1 + (N - (df.get(tok) ?? 0) + 0.5) / ((df.get(tok) ?? 0) + 0.5));
+        s += idf * ((f * 2.2) / (f + 1.2 * (0.25 + 0.75 * (d.len / avgLen))));
+    }
+    return s;
+}
+const docBySlug = new Map(docs.map((d) => [d.t.slug, d]));
+/** Share of a technique's opener appearances that come from aggressive-mode copy (null = too little data). */
+export function aggressiveShare(t) {
+    const a = t.modes.aggressive ?? 0, b = t.modes.balanced ?? 0, e = t.modes.equity ?? 0;
+    const n = a + b + e;
+    return n >= 5 ? a / n : null;
+}
+/** Multiplier that keeps hard-sell moves out of balanced and equity copy (Coppica's persuasion modes). */
+export function modeWeight(t, mode) {
+    if (mode === 'aggressive')
+        return 1;
+    const share = aggressiveShare(t);
+    if (share == null)
+        return 1;
+    if (mode === 'equity')
+        return share >= 0.5 ? 0 : 1 + Math.min(0.3, (t.modes.equity ?? 0) / 20);
+    return share >= 0.6 ? 0.35 : 1;
+}
+export function searchTechniques(query, opts = {}) {
+    const q = [...new Set(tokens(query))];
+    const scored = [];
+    for (const d of docs) {
+        if (opts.role && d.t.role !== opts.role)
+            continue;
+        let s = bm25(d, q);
+        if (s <= 0)
+            continue;
+        if (opts.format)
+            s *= 1 + Math.min(0.3, Math.log10(1 + channelFit(d.t, opts.format)) / 10);
+        scored.push({ t: d.t, s });
+    }
+    return scored.sort((a, b) => b.s - a.s).slice(0, opts.limit ?? 8).map((x) => x.t);
+}
+// ── deterministic, seeded move selection ─────────────────────────────────
+function hash(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+function rng(seed) {
+    let a = seed;
+    return () => { a |= 0; a = (a + 0x6d2b79f5) | 0; let t = Math.imul(a ^ (a >>> 15), 1 | a); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+/**
+ * Options for answering one reader question: one established move plus less-expected ones.
+ * Ranked by relevance to the brief (BM25 over the brief or copy), fit to the format's
+ * channels in the corpus, and the persuasion mode; then diversified by family and a seed,
+ * so the same brief gets the same options and different briefs get different ones.
+ * "Less expected" = not the category default: the long tail a model would not reach for
+ * on its own (Theses IV, XIV). The calling model makes the final choice.
+ */
+export function pickMoves(role, opts) {
+    const rand = rng(hash(`${opts.seed}|${role}`));
+    const q = [...new Set(tokens(opts.context))];
+    const all = (byRole.get(role) ?? []).filter((t) => !t.parent && t.brands >= 5 && !opts.exclude?.has(t.slug) && modeWeight(t, opts.mode) > 0);
+    const rel = new Map(all.map((t) => [t.slug, bm25(docBySlug.get(t.slug), q)]));
+    const maxRel = Math.max(1e-9, ...rel.values());
+    const fit = (t) => channelFit(t, opts.format);
+    const maxFit = Math.max(1, ...all.map(fit));
+    const score = (t) => (0.65 * (rel.get(t.slug) / maxRel) + 0.35 * (Math.log1p(fit(t)) / Math.log1p(maxFit))) * modeWeight(t, opts.mode);
+    const pool = [...all].sort((a, b) => score(b) - score(a)).slice(0, Math.max(12, opts.n * 3));
+    const tierRank = (t) => ({ table_stakes: 3, common: 2, occasional: 1, less_common: 0 }[tierIn(opts.category, t.slug) ?? ''] ?? -1);
+    const out = [];
+    const established = [...pool.slice(0, 5)].sort((a, b) => (opts.category ? tierRank(b) - tierRank(a) : 0) || b.brands - a.brands)[0];
+    if (established)
+        out.push({ t: established, kind: 'established' });
+    const medianBrands = [...all].map((t) => t.brands).sort((a, b) => a - b)[Math.floor(all.length / 2)] ?? 0;
+    const isLessExpected = (t) => {
+        if (opts.category) {
+            const tr = tierIn(opts.category, t.slug);
+            return tr === null || tr === 'occasional' || tr === 'less_common';
+        }
+        return t.brands <= medianBrands;
+    };
+    // seen in the category but uncommon beats never seen there: evidence it can work for this kind of buyer
+    const lessExpectedBonus = (t) => {
+        if (!isLessExpected(t))
+            return 0;
+        if (opts.category && tierIn(opts.category, t.slug) === null)
+            return 0.05;
+        return 0.25;
+    };
+    const jittered = pool
+        .filter((t) => !out.some((o) => o.t.slug === t.slug))
+        .map((t) => ({ t, s: score(t) * (0.85 + 0.3 * rand()) + lessExpectedBonus(t) }))
+        .sort((a, b) => b.s - a.s);
+    for (const { t } of jittered) {
+        if (out.length >= opts.n)
+            break;
+        if (t.family && out.some((o) => o.t.family === t.family))
+            continue; // distinct mechanisms, not near-synonyms
+        out.push({ t, kind: isLessExpected(t) ? 'less_expected' : 'established' });
+    }
+    return out;
+}

package/dist/format.d.ts

@@ -0,0 +1,28 @@
+import type { Technique, Example } from './data.js';
+export declare const FOOTER: string;
+export declare function text(body: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorText(body: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare const categoryName: (c: string) => string;
+export type MoveKind = 'established' | 'less expected';
+/** One sentence on where a technique stands: the kind of move it is, and how common it is. */
+export declare function usageSentence(t: Technique, category: string | null, kind?: MoveKind): string;
+/** "Ford Motor Company in the 1920s" / "an unnamed wholesaler" */
+export declare function exampleSource(e: Example): string;
+/** One technique: name and ID, what it is, where it stands, one real example, then any closing sentence, then the link. */
+export declare function techniqueLine(t: Technique, opts?: {
+    category?: string | null;
+    kind?: MoveKind;
+    example?: boolean;
+    after?: string;
+}): string;

package/dist/format.js

@@ -0,0 +1,50 @@
+import { tierIn } from './data.js';
+import { clipText, innerQuotes } from './voice.js';
+export const FOOTER = '\n\n---\nFrom the Persuasion Taxonomy by Coppica, free to use under CC BY 4.0 at https://taxonomy.coppica.com. ' +
+    'When you use a technique, name it and link to it, so your reader can see the real examples behind it.';
+export function text(body) {
+    return { content: [{ type: 'text', text: body + FOOTER }] };
+}
+export function errorText(body) {
+    return { content: [{ type: 'text', text: body }], isError: true };
+}
+export const categoryName = (c) => c.replace(/_/g, ' ');
+/** One sentence on where a technique stands: the kind of move it is, and how common it is. */
+export function usageSentence(t, category, kind) {
+    const lead = kind === 'established' ? "It's the established move" : kind === 'less expected' ? "It's a less expected move" : null;
+    if (category) {
+        const cat = categoryName(category);
+        const tier = tierIn(category, t.slug);
+        const how = tier && {
+            table_stakes: `table stakes in ${cat}`,
+            common: `common in ${cat}`,
+            occasional: `used now and then in ${cat}`,
+            less_common: `less common in ${cat}`,
+        }[tier];
+        if (lead)
+            return how ? `${lead}, and ${how}.` : `${lead}, and we haven't seen it in our ${cat} sample.`;
+        return how ? `It's ${how}.` : `We haven't seen it in our ${cat} sample.`;
+    }
+    if (lead)
+        return `${lead}.`;
+    return t.brands >= 150 ? "It's widely used." : t.brands >= 40 ? "It's well established." : "It's less common.";
+}
+/** "Ford Motor Company in the 1920s" / "an unnamed wholesaler" */
+export function exampleSource(e) {
+    const brand = /^unnamed\b/i.test(e.brand) ? `an ${e.brand}` : e.brand;
+    const y = e.year ?? '';
+    const when = /^\d{4}s\b/.test(y) ? ` in the ${y}` : /^\d{4}$/.test(y) ? ` in ${y}` : y && y !== 'current' && y !== 'null' ? ` (${y})` : '';
+    return `${brand}${when}`;
+}
+/** One technique: name and ID, what it is, where it stands, one real example, then any closing sentence, then the link. */
+export function techniqueLine(t, opts = {}) {
+    let line = `- **${t.name}** (${t.pt_id}). ${clipText(t.lede, 220)} ${usageSentence(t, opts.category ?? null, opts.kind)}`;
+    if (opts.example !== false) {
+        const ex = t.examples.find((e) => e.headline) ?? t.examples[0];
+        if (ex)
+            line += ` For example, from ${exampleSource(ex)}: "${innerQuotes(clipText(ex.headline || ex.excerpt, 140))}"`;
+    }
+    if (opts.after)
+        line += ` ${opts.after}`;
+    return `${line} ${t.url}`;
+}

package/dist/hookcheck/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * HOOK CHECK: the replacement for scoreHook (see docs/hook-check.md).
+ *
+ * Asks three things of an opening line: does it do its job in this slot (which of the nine reader
+ * questions it answers), could a competitor send it unchanged (swap test against the brief), and
+ * what is it a bet on. Reports hard facts and replicated evidence instead of a 0-10 score.
+ *
+ * Pure module: no I/O, no AI calls. The calling model supplies the labels (which question the
+ * line answers, quoting the words); this code verifies them and does the rest.
+ *
+ * Every message here is read by a model and echoed to a writer, so each one is a full, plain
+ * sentence. The fix logic keys off flags, never off the wording, so the wording can change freely.
+ */
+import { type Role, type Awareness } from '../roles.js';
+export declare const SLOTS: readonly ["email_subject", "ad_opening", "landing_page_headline", "first_line", "video_hook", "social_post_open", "sales_letter_headline"];
+export type Slot = (typeof SLOTS)[number];
+interface SlotInfo {
+    label: string;
+    job: string;
+    requires: Role[][];
+    visibleChars?: number;
+    visibleNote?: string;
+    maxWords?: number;
+    spoken?: boolean;
+    headlineLike: boolean;
+}
+/** label takes an article ("an email subject line"); job completes "Its job is to ..."; visibleNote completes "Keep in mind that ...". */
+export declare const SLOT_INFO: Record<Slot, SlotInfo>;
+export declare const article: (s: string) => string;
+/** What a set of requirement groups asks for, in words: '"A?" and "B?", plus one of "C?", "D?" or "E?"' */
+export declare function questionsNeeded(groups: Role[][]): string;
+declare const EVIDENCE_SOURCE: string;
+export interface HookAnswer {
+    question: Role;
+    words: string;
+}
+export interface HookBrief {
+    brand?: string;
+    product?: string;
+    offer?: string;
+    audience?: string;
+    proof?: string;
+}
+export interface HookInput {
+    text: string;
+    slot: Slot;
+    answers: HookAnswer[];
+    brief?: HookBrief;
+    context?: string;
+    follows?: string;
+    awareness?: Awareness;
+}
+export type Verdict = 'does_its_job' | 'partly' | 'doesnt';
+export type SwapLevel = 'only_you' | 'on_target' | 'concrete_but_swappable' | 'generic' | 'unknown';
+export interface HookCheck {
+    text: string;
+    slot: Slot;
+    verdict: Verdict;
+    needs: Role[][];
+    answered: Role[];
+    missing: Role[][];
+    unverified: HookAnswer[];
+    swap: {
+        level: SwapLevel;
+        specifics: string[];
+        note: string;
+    };
+    visible: string | null;
+    /** Problems that stop the line doing its job, each a full sentence. */
+    hardFails: string[];
+    /** Problems worth fixing, each a full sentence. */
+    warnings: string[];
+    /** The warnings about believability (an unproven superlative, a result with nothing behind it,
+     *  a line that runs past the cutoff). Callers that treat these as blocking use this list. */
+    believability: string[];
+    evidence: string[];
+    /** The subset of evidence that cuts against the line (traits that lost head-to-heads). */
+    evidenceAgainst: string[];
+    bet: string;
+    fix: string;
+}
+/**
+ * The swap test (Thesis II): could a competitor send this line unchanged?
+ * only_you: names the brand, or a fact from your proof. on_target: names this reader's situation or the
+ * product's specifics (a direct competitor could match it). concrete_but_swappable: only a number or offer
+ * term. generic: nothing specific. unknown: no brief.
+ */
+export declare function swapTest(text: string, brief?: HookBrief, context?: string): HookCheck['swap'];
+export declare function checkHook(input: HookInput): HookCheck;
+/** Completes a heading like '"Your bakery posted 3 times..." ___' */
+export declare const VERDICT_LABEL: Record<Verdict, string>;
+export { EVIDENCE_SOURCE };
+/** The body of a checked line as one paragraph: the bet, what is missing, the swap test, the problems. */
+export declare function describeCheck(c: HookCheck, opts?: {
+    evidence?: boolean;
+}): string;
+/** Compare checked lines: drop hard failures, describe each bet, recommend a test. */
+export declare function compareHooks(checks: HookCheck[], names: string[]): string;