debutly 0.0.0-stage → 0.2.0

package/src/llm/types.ts

@@ -0,0 +1,36 @@
+export interface LlmMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface LlmUsage {
+  inputTokens: number;
+  outputTokens: number;
+  /** What the provider actually charged in USD, when it says (OpenRouter does). */
+  costUsd?: number;
+}
+
+export interface LlmRequest {
+  system: string;
+  messages: LlmMessage[];
+  maxTokens?: number;
+  /** Called with this request's token counts, so each session can meter its own spend. */
+  onUsage?: (usage: LlmUsage) => void;
+}
+
+export interface LlmClient {
+  complete(req: LlmRequest): Promise<string>;
+}
+
+export const OUT_OF_CREDITS = "The AI provider account is out of credits";
+
+/**
+ * The provider refused for lack of credit (OpenRouter's 402, Anthropic's "credit balance is too
+ * low"). Every later call would be refused too, so clients raise it again without asking.
+ */
+export class OutOfCreditsError extends Error {
+  constructor(detail: string) {
+    super(`${OUT_OF_CREDITS}: ${detail.slice(0, 300)}`);
+    this.name = "OutOfCreditsError";
+  }
+}

package/src/perceive.ts

@@ -0,0 +1,150 @@
+// Perception, grounding and experiments, without a browser per buyer:
+//
+//   npx debutly perceive --icp "…" --url https://app.test/ --url https://app.test/pricing \
+//     [--competitors https://rival.test/pricing,https://other.test/pricing] [--evaluators 50]
+//   npx debutly perceive --icp "…" --variant A=https://app.test/pricing --variant B=pricing-b.md
+//   npx debutly perceive --icp "…" --from-run runs/<dir>          (pages the depth agents saw)
+//   npx debutly perceive --icp "…" --file pitch.md                (idea stage)
+//
+// Pages are read, never submitted to. Writes launch-readiness.md, verdicts.json and
+// market-context.json; with --store the run and its predictions are recorded.
+import "./util/legacy-env";
+import "./util/key-defaults";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { chromium } from "playwright";
+import { estimatePerceptionCost } from "./cost/estimate";
+import { fetchModelPrice } from "./cost/prices";
+import { EVALUATORS, type Tier } from "./cost/tiers";
+import { creditCheck, keyCreditsLeft } from "./llm/credits";
+import { createLlms } from "./llm/factory";
+import { captureExhibits, exhibitFromFile, exhibitsFromSessions, type Exhibit } from "./perception/exhibits";
+import { buildMarketContext, type MarketContext } from "./perception/market-context";
+import { runPerception } from "./perception/run-perception";
+import { renderLaunchReadiness } from "./report/launch-readiness";
+import { openDb } from "./store/db";
+import { PgRunStore } from "./store/pg-run-store";
+import { PgPredictionStore } from "./store/predictions";
+import type { Session } from "./types";
+
+const { values } = parseArgs({
+  options: {
+    icp: { type: "string" },
+    product: { type: "string" },
+    url: { type: "string", multiple: true },
+    file: { type: "string", multiple: true },
+    "from-run": { type: "string" },
+    variant: { type: "string", multiple: true },
+    competitors: { type: "string" },
+    "market-context": { type: "string" },
+    tier: { type: "string", default: "quick" },
+    evaluators: { type: "string" },
+    concurrency: { type: "string", default: "8" },
+    "max-cost": { type: "string" },
+    store: { type: "string" },
+    out: { type: "string" },
+  },
+});
+
+const variantArgs = values.variant ?? [];
+const hasMain = !!(values.url?.length || values.file?.length || values["from-run"]);
+if (!values.icp || (!hasMain && variantArgs.length < 2) || (hasMain && variantArgs.length)) {
+  console.error(
+    'Usage: npx debutly perceive --icp "<buyers>" (--url <url>… | --file <pitch>… | --from-run <dir> | --variant A=<url|file> --variant B=<url|file>) [--competitors url,url] [--market-context file] [--tier quick|standard|deep] [--evaluators N] [--max-cost USD] [--store postgres://…] [--out dir]',
+  );
+  process.exit(1);
+}
+const tier = values.tier as Tier;
+if (!(tier in EVALUATORS)) {
+  console.error("--tier must be quick, standard or deep");
+  process.exit(1);
+}
+const evaluators = values.evaluators !== undefined ? Number(values.evaluators) : EVALUATORS[tier];
+const isUrl = (s: string) => /^https?:\/\//.test(s);
+const experiment = variantArgs.length > 0;
+
+// Before anything is spent: what could this cost?
+const navModel = process.env.DEBUTLY_NAV_MODEL ?? "claude-haiku-4-5";
+const price = await fetchModelPrice(navModel);
+const judgePrice = await fetchModelPrice(process.env.DEBUTLY_JUDGE_MODEL ?? "claude-opus-5");
+const estimate = estimatePerceptionCost({ evaluators, experiment, price });
+console.log(estimate ? `Estimated cost: $${estimate.low.toFixed(2)}–$${estimate.high.toFixed(2)} (${evaluators} evaluators on ${navModel})` : `Estimated cost: unknown (no price for ${navModel})`);
+if (values["max-cost"] !== undefined && (!estimate || estimate.high > Number(values["max-cost"]))) {
+  console.error(`Refusing to start: ${estimate ? `this could cost up to $${estimate.high.toFixed(2)}` : "the price is unknown"}, and --max-cost is $${values["max-cost"]}.`);
+  process.exit(1);
+}
+const credits = creditCheck(await keyCreditsLeft(process.env.DEBUTLY_BASE_URL ?? "", process.env.DEBUTLY_API_KEY ?? ""), estimate);
+if (credits.refuse) {
+  console.error(`Refusing to start: ${credits.refuse}`);
+  process.exit(1);
+}
+if (credits.warn) console.warn(`Warning: ${credits.warn}`);
+
+const { nav, judge } = createLlms(process.env);
+const browser = await chromium.launch();
+const exhibitsByVariant: Record<string, Exhibit[]> = {};
+let market: MarketContext | undefined;
+try {
+  if (experiment) {
+    for (const arg of variantArgs) {
+      const [name, source] = [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)];
+      if (!name || !source) throw new Error(`--variant must look like A=<url|file> (got "${arg}")`);
+      const found = isUrl(source) ? await captureExhibits(browser, [source]) : [await exhibitFromFile(source)];
+      exhibitsByVariant[name] = [...(exhibitsByVariant[name] ?? []), ...found.map((e) => ({ ...e, id: `${name}:${e.id}` }))];
+    }
+    if (Object.keys(exhibitsByVariant).length !== 2) throw new Error("an experiment needs exactly two variants, e.g. --variant A=… --variant B=…");
+  } else {
+    const main: Exhibit[] = [];
+    if (values["from-run"]) main.push(...exhibitsFromSessions(JSON.parse(await readFile(join(values["from-run"], "sessions.json"), "utf8")) as Session[]));
+    if (values.url?.length) main.push(...(await captureExhibits(browser, values.url)));
+    for (const f of values.file ?? []) main.push(await exhibitFromFile(f));
+    exhibitsByVariant.main = main;
+  }
+
+  if (values["market-context"]) {
+    market = JSON.parse(await readFile(values["market-context"], "utf8")) as MarketContext;
+  } else if (values.competitors) {
+    const urls = values.competitors.split(",").map((u) => u.trim()).filter(Boolean);
+    console.log(`Reading ${urls.length} competitor pages for market context...`);
+    market = await buildMarketContext(judge, { icp: values.icp, product: values.product ?? "the product", competitorExhibits: await captureExhibits(browser, urls) });
+  }
+} finally {
+  await browser.close();
+}
+
+const product = values.product ?? (values.url?.[0] ? new URL(values.url[0]).host : "the product");
+console.log(`${evaluators} evaluators judging ${experiment ? Object.keys(exhibitsByVariant).join(" vs ") : `${exhibitsByVariant.main.length} pages`}...`);
+const result = await runPerception({
+  llm: nav,
+  judge,
+  icp: values.icp,
+  product,
+  exhibitsByVariant,
+  evaluators,
+  concurrency: Number(values.concurrency),
+  market,
+  price,
+  judgePrice,
+});
+
+const outDir = values.out ?? `runs/perceive-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+await mkdir(outDir, { recursive: true });
+const report = renderLaunchReadiness({ target: product, icp: values.icp, result });
+await writeFile(join(outDir, "launch-readiness.md"), report);
+await writeFile(join(outDir, "verdicts.json"), JSON.stringify({ verdicts: result.verdicts, pairs: result.pairs, aggregates: result.aggregates, pairAggregate: result.pairAggregate }, null, 2));
+if (market) await writeFile(join(outDir, "market-context.json"), JSON.stringify(market, null, 2));
+
+if (values.store) {
+  const { db, close } = await openDb(values.store);
+  const runs = new PgRunStore(db);
+  const runId = await runs.createRun({ targetUrl: values.url?.[0] ?? product, goal: experiment ? "experiment" : "perception", icp: values.icp, tier, unitKind: "evaluators", model: navModel, estimate });
+  await runs.finishRun(runId, { status: "finished", findings: [], reportMd: report, usage: result.usage, sideEffects: [] });
+  const ids = await new PgPredictionStore(db).add(runId, result.predictions);
+  await close();
+  console.log(`Stored run ${runId} with ${ids.length} predictions:`);
+  result.predictions.forEach((p, i) => console.log(`  ${ids[i]}  ${p.claim}`));
+}
+
+const cost = result.usage.costUsd !== undefined ? `, cost $${result.usage.costUsd.toFixed(4)}` : "";
+console.log(`Done: ${result.evaluators - result.unusable} usable judgments${cost}. Report: ${join(outDir, "launch-readiness.md")}`);

package/src/perception/aggregate.ts

@@ -0,0 +1,111 @@
+import type { PairJudgment } from "./compare";
+import type { ObjectionCategory, Verdict } from "./evaluate";
+
+/** Wilson score interval (95%) for a proportion: sensible even for small samples. */
+export function wilson(successes: number, n: number, z = 1.96): { low: number; high: number } {
+  if (n === 0) return { low: 0, high: 1 };
+  const p = successes / n;
+  const denom = 1 + (z * z) / n;
+  const centre = (p + (z * z) / (2 * n)) / denom;
+  const margin = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / denom;
+  return { low: Math.max(0, centre - margin), high: Math.min(1, centre + margin) };
+}
+
+const median = (xs: number[]) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+export interface VerdictAggregate {
+  evaluators: number;
+  unusable: number;
+  /** Ranked by how many buyers raised each category (at least once). */
+  objections: { category: ObjectionCategory; buyers: number; examples: string[] }[];
+  intent: { no: number; maybe: number; yes: number };
+  meanScores: { clarity: number; credibility: number; value: number; urgency: number };
+  wouldPay: { answers: number; medianUsd: number | null; plans: Record<string, number> };
+  confusions: { exhibitId: string; count: number; examples: string[] }[];
+}
+
+/** Objection categories ranked by how many buyers raised each (at least once), with example quotes. */
+export function rankObjections(perBuyer: { category: ObjectionCategory; text: string }[][]): VerdictAggregate["objections"] {
+  const byCategory = new Map<ObjectionCategory, { buyers: number; examples: string[] }>();
+  for (const objections of perBuyer) {
+    for (const category of new Set(objections.map((o) => o.category))) {
+      const entry = byCategory.get(category) ?? { buyers: 0, examples: [] };
+      entry.buyers++;
+      const quote = objections.find((o) => o.category === category)!.text;
+      if (entry.examples.length < 3 && !entry.examples.includes(quote)) entry.examples.push(quote);
+      byCategory.set(category, entry);
+    }
+  }
+  return [...byCategory.entries()].map(([category, e]) => ({ category, ...e })).sort((a, b) => b.buyers - a.buyers);
+}
+
+export function aggregateVerdicts(verdicts: Verdict[], unusable = 0): VerdictAggregate {
+  const mean = (k: keyof Verdict["scores"]) => (verdicts.length ? verdicts.reduce((n, v) => n + v.scores[k], 0) / verdicts.length : 0);
+  const payers = verdicts.filter((v) => v.intent !== "no" && v.wouldPay).map((v) => v.wouldPay!);
+  const plans: Record<string, number> = {};
+  for (const p of payers) plans[p.plan] = (plans[p.plan] ?? 0) + 1;
+  const confusions = new Map<string, { count: number; examples: string[] }>();
+  for (const c of verdicts.flatMap((v) => v.confusions)) {
+    const key = c.exhibitId ?? "general";
+    const entry = confusions.get(key) ?? { count: 0, examples: [] };
+    entry.count++;
+    if (entry.examples.length < 3 && !entry.examples.includes(c.text)) entry.examples.push(c.text);
+    confusions.set(key, entry);
+  }
+  return {
+    evaluators: verdicts.length,
+    unusable,
+    objections: rankObjections(verdicts.map((v) => v.objections)),
+    intent: {
+      no: verdicts.filter((v) => v.intent === "no").length,
+      maybe: verdicts.filter((v) => v.intent === "maybe").length,
+      yes: verdicts.filter((v) => v.intent === "yes").length,
+    },
+    meanScores: { clarity: mean("clarity"), credibility: mean("credibility"), value: mean("value"), urgency: mean("urgency") },
+    wouldPay: { answers: payers.length, medianUsd: payers.length ? median(payers.map((p) => p.monthlyUsd)) : null, plans },
+    confusions: [...confusions.entries()].map(([exhibitId, e]) => ({ exhibitId, ...e })).sort((a, b) => b.count - a.count),
+  };
+}
+
+export interface PairAggregate {
+  winsA: number;
+  winsB: number;
+  neither: number;
+  /** The variant more buyers chose (ties go to A), and its share of decided judgments. */
+  leader: "A" | "B";
+  winRate: number;
+  interval: { low: number; high: number };
+  /** The interval excludes 50/50: the lead is unlikely to be noise. */
+  decisive: boolean;
+  /** Share of decided judgments won by whichever option was shown first (0.5 = no position bias). */
+  firstShownWinShare: number;
+  reasons: { A: string[]; B: string[] };
+}
+
+export function aggregatePairs(pairs: PairJudgment[]): PairAggregate {
+  const winsA = pairs.filter((p) => p.preferred === "A").length;
+  const winsB = pairs.filter((p) => p.preferred === "B").length;
+  const decided = winsA + winsB;
+  const leader = winsB > winsA ? "B" : "A";
+  const leaderWins = Math.max(winsA, winsB);
+  const interval = wilson(leaderWins, decided);
+  const firstWins = pairs.filter((p) => p.preferred !== "neither" && p.preferred === p.shownFirst).length;
+  return {
+    winsA,
+    winsB,
+    neither: pairs.length - decided,
+    leader,
+    winRate: decided ? leaderWins / decided : 0,
+    interval,
+    decisive: decided > 0 && interval.low > 0.5,
+    firstShownWinShare: decided ? firstWins / decided : 0,
+    reasons: {
+      A: pairs.filter((p) => p.preferred === "A").flatMap((p) => p.reasons).slice(0, 5),
+      B: pairs.filter((p) => p.preferred === "B").flatMap((p) => p.reasons).slice(0, 5),
+    },
+  };
+}

package/src/perception/compare.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import type { LlmClient, LlmMessage, LlmUsage } from "../llm/types";
+import type { Persona } from "../types";
+import { extractJsonObject } from "../util/json";
+import { ATTEMPTS, ObjectionSchema, personaBrief, REPLY_TOKENS, RUBRIC } from "./evaluate";
+import { canonicalExhibitId, renderExhibits, type Exhibit } from "./exhibits";
+
+const PairSchema = z.object({
+  objections1: z.array(ObjectionSchema).min(1),
+  objections2: z.array(ObjectionSchema).min(1),
+  preferred: z.enum(["1", "2", "neither"]),
+  reasons: z.array(z.string()).min(1),
+});
+
+export interface PairJudgment {
+  evaluatorId: string;
+  preferred: "A" | "B" | "neither";
+  reasons: string[];
+  objectionsA: z.infer<typeof ObjectionSchema>[];
+  objectionsB: z.infer<typeof ObjectionSchema>[];
+  /** Which variant was shown first, for checking position bias later. */
+  shownFirst: "A" | "B";
+}
+
+const SHAPE = `Reply with one JSON object: {"objections1":[{"category","text","exhibitId"}],"objections2":[...],"preferred":"1"|"2"|"neither","reasons":[string]}. Name at least one objection to each option before choosing. "neither" is a valid answer.`;
+
+/**
+ * Experiment mode: one buyer sees two variants and picks one (or neither). Variants
+ * appear as Option 1/2 in random order so position bias averages out across evaluators.
+ */
+export async function comparePair(
+  llm: LlmClient,
+  persona: Persona,
+  a: Exhibit[],
+  b: Exhibit[],
+  o: { market?: string; onUsage?: (u: LlmUsage) => void },
+  rng: () => number = Math.random,
+): Promise<PairJudgment | null> {
+  const aFirst = rng() < 0.5;
+  const [first, second] = aFirst ? [a, b] : [b, a];
+  // Blind: no variant names, file names or web addresses, which would give away which is which.
+  const blind = (pages: Exhibit[], option: number) => pages.map((e, i) => ({ ...e, id: `${option}.${i + 1}`, url: undefined }));
+  const shown1 = blind(first, 1);
+  const shown2 = blind(second, 2);
+  const messages: LlmMessage[] = [
+    {
+      role: "user",
+      content: `${o.market ? `${o.market}\n\n` : ""}Two versions of the same product. Which would you rather buy?\n\n## Option 1\n\n${renderExhibits(shown1)}\n\n## Option 2\n\n${renderExhibits(shown2)}\n\n${SHAPE}`,
+    },
+  ];
+  // Maps an objection's page reference ("1.2", "pricing"...) back to the real exhibit id.
+  const realId = (ref: string | undefined, shown: Exhibit[], real: Exhibit[]) => {
+    const id = canonicalExhibitId(ref, shown);
+    return id ? real[shown.findIndex((e) => e.id === id)]?.id : undefined;
+  };
+  const system = `${personaBrief(persona)}\n\n${RUBRIC}`;
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const raw = await llm.complete({ system, messages: [...messages], maxTokens: REPLY_TOKENS, onUsage: o.onUsage });
+    try {
+      const p = PairSchema.parse(extractJsonObject(raw));
+      const toVariant = (opt: "1" | "2") => ((opt === "1") === aFirst ? "A" : "B");
+      p.objections1 = p.objections1.map((o) => ({ ...o, exhibitId: realId(o.exhibitId, shown1, first) }));
+      p.objections2 = p.objections2.map((o) => ({ ...o, exhibitId: realId(o.exhibitId, shown2, second) }));
+      return {
+        evaluatorId: persona.id,
+        preferred: p.preferred === "neither" ? "neither" : toVariant(p.preferred),
+        reasons: p.reasons,
+        objectionsA: aFirst ? p.objections1 : p.objections2,
+        objectionsB: aFirst ? p.objections2 : p.objections1,
+        shownFirst: aFirst ? "A" : "B",
+      };
+    } catch (err) {
+      messages.push({ role: "assistant", content: raw || "(empty)" }, { role: "user", content: `That reply was not valid (${String(err).slice(0, 200)}). ${SHAPE}` });
+    }
+  }
+  return null;
+}

package/src/perception/evaluate.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import type { LlmClient, LlmMessage, LlmUsage } from "../llm/types";
+import type { Persona } from "../types";
+import { extractJsonObject } from "../util/json";
+import { canonicalExhibitId, renderExhibits, type Exhibit } from "./exhibits";
+
+export const OBJECTION_CATEGORIES = [
+  "price",
+  "unclear_value",
+  "trust",
+  "missing_feature",
+  "complexity",
+  "switching_cost",
+  "integration",
+  "timing",
+  "other",
+] as const;
+export type ObjectionCategory = (typeof OBJECTION_CATEGORIES)[number];
+
+// Reasoning models spend part of the reply budget thinking and can return nothing if it is
+// tight; allow room, and ask again on an empty or invalid reply.
+export const REPLY_TOKENS = 4000;
+export const ATTEMPTS = 3;
+
+const score = z.number().int().min(1).max(5);
+export const ObjectionSchema = z.object({ category: z.enum(OBJECTION_CATEGORIES), text: z.string().min(3), exhibitId: z.string().optional() });
+
+const VerdictSchema = z.object({
+  objections: z.array(ObjectionSchema).min(2, "list at least 2 objections"),
+  confusions: z.array(z.object({ text: z.string(), exhibitId: z.string().optional() })),
+  scores: z.object({ clarity: score, credibility: score, value: score, urgency: score }),
+  intent: z.enum(["no", "maybe", "yes"]),
+  wouldPay: z.object({ plan: z.string(), monthlyUsd: z.number().nonnegative() }).nullable(),
+  summary: z.string(),
+});
+
+export type Verdict = z.infer<typeof VerdictSchema> & { evaluatorId: string };
+
+// Adversarial by design, to counter LLM agreeableness.
+export const RUBRIC = `You are a skeptical buyer with a limited budget, judging a product only from the pages you are shown.
+Rules:
+- First list at least 2 specific objections, each tied to an exhibit id, with a category: ${OBJECTION_CATEGORIES.join(", ")}.
+- Default to "no". Say "maybe" or "yes" only if the pages give you a concrete reason, and compare against the alternatives you know.
+- Score strictly from 1 (poor) to 5 (excellent): clarity, credibility, value, urgency. A 5 must be earned.
+- Never assume features, prices or guarantees the pages do not show.
+- "wouldPay" is the plan and monthly USD you would actually pay, or null.`;
+
+const SHAPE = `Reply with one JSON object: {"objections":[{"category","text","exhibitId"}],"confusions":[{"text","exhibitId"}],"scores":{"clarity","credibility","value","urgency"},"intent":"no"|"maybe"|"yes","wouldPay":{"plan","monthlyUsd"}|null,"summary":string}.`;
+
+export const personaBrief = (p: Persona) => `You are ${p.name}. ${p.background} What you want: ${p.goal}. Patience: ${p.patience}.`;
+
+/** One evaluator's verdict on the exhibits; null if it never produced a valid one (counted as unusable). */
+export async function evaluate(
+  llm: LlmClient,
+  persona: Persona,
+  exhibits: Exhibit[],
+  o: { market?: string; onUsage?: (u: LlmUsage) => void },
+): Promise<Verdict | null> {
+  const messages: LlmMessage[] = [
+    { role: "user", content: `${o.market ? `${o.market}\n\n` : ""}The product's pages:\n\n${renderExhibits(exhibits)}\n\n${SHAPE}` },
+  ];
+  const system = `${personaBrief(persona)}\n\n${RUBRIC}`;
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const raw = await llm.complete({ system, messages: [...messages], maxTokens: REPLY_TOKENS, onUsage: o.onUsage });
+    try {
+      const v = VerdictSchema.parse(extractJsonObject(raw));
+      const page = (ref?: string) => canonicalExhibitId(ref, exhibits);
+      return {
+        evaluatorId: persona.id,
+        ...v,
+        objections: v.objections.map((o) => ({ ...o, exhibitId: page(o.exhibitId) })),
+        confusions: v.confusions.map((c) => ({ ...c, exhibitId: page(c.exhibitId) })),
+      };
+    } catch (err) {
+      const problem = err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") : String(err);
+      messages.push(
+        { role: "assistant", content: raw || "(empty)" },
+        { role: "user", content: `That reply was not valid (${problem.slice(0, 300)}). Follow the rules, including at least 2 objections. ${SHAPE}` },
+      );
+    }
+  }
+  return null;
+}

package/src/perception/exhibits.ts

@@ -0,0 +1,146 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import type { Browser, Page } from "playwright";
+import { observe } from "../browser/observe";
+import type { Session } from "../types";
+
+export type ExhibitKind = "landing" | "pricing" | "signup" | "onboarding" | "dashboard" | "checkout" | "pitch" | "other";
+
+/** What an evaluator is shown: a page (or pitch) as copy and controls, no browser needed. */
+export interface Exhibit {
+  id: string;
+  kind: ExhibitKind;
+  title: string;
+  url?: string;
+  text: string;
+  elements: string[];
+}
+
+// Pages most telling for a buying decision come first when exhibits are capped.
+const PRIORITY: ExhibitKind[] = ["pricing", "landing", "signup", "onboarding", "checkout", "dashboard", "pitch", "other"];
+const MAX_TEXT = 8000;
+
+const pathOf = (url: string) => {
+  try {
+    return new URL(url).pathname.toLowerCase();
+  } catch {
+    return url.toLowerCase();
+  }
+};
+
+export function kindOf(url: string, title: string, text: string): ExhibitKind {
+  const path = pathOf(url);
+  const words = `${title} ${text.slice(0, 1500)}`.toLowerCase();
+  if (/\/(pricing|plans?|price)(\/|$)/.test(path) || /per month|\/mo(nth)?\b|billed (monthly|annually)/.test(words)) return "pricing";
+  if (/\/(sign-?up|register|join|get-started|start)(\/|$)/.test(path)) return "signup";
+  if (/\/(checkout|billing\/checkout|upgrade)(\/|$)/.test(path)) return "checkout";
+  if (/\/(onboarding|welcome|setup)(\/|$)/.test(path)) return "onboarding";
+  if (/\/(dashboard|app|home)(\/|$)/.test(path)) return "dashboard";
+  if (path === "/" || path === "") return "landing";
+  return "other";
+}
+
+const byPriority = (a: Exhibit, b: Exhibit) => PRIORITY.indexOf(a.kind) - PRIORITY.indexOf(b.kind);
+
+/** The last snapshot of each page the depth agents saw, key pages first. */
+export function exhibitsFromSessions(sessions: Session[], max = 8): Exhibit[] {
+  const latest = new Map<string, Exhibit>();
+  for (const s of sessions) {
+    for (const step of s.steps) {
+      const o = step.observation;
+      const path = pathOf(o.url);
+      latest.set(path, {
+        id: path,
+        kind: kindOf(o.url, o.title, o.text),
+        title: o.title,
+        url: o.url,
+        text: o.text,
+        elements: o.elements.filter((e) => e.name).map((e) => `${e.role}: ${e.name}`),
+      });
+    }
+  }
+  return [...latest.values()].sort(byPriority).slice(0, max);
+}
+
+/**
+ * A person reading a pricing page opens the FAQ; answers hidden in accordions would otherwise
+ * read as unanswered questions. Opens <details> and question-shaped collapsed buttons only.
+ */
+async function openFaqAnswers(page: Page): Promise<void> {
+  await page.evaluate(() => document.querySelectorAll("details").forEach((d) => (d.open = true)));
+  const questions = page.locator('button[aria-expanded="false"]').filter({ hasText: /\?\s*$/ });
+  const n = Math.min(await questions.count(), 30);
+  for (let i = 0; i < n; i++) await questions.nth(i).click({ timeout: 1000 }).catch(() => {});
+  if (n) await page.waitForTimeout(300);
+}
+
+/** Visits each URL and reads it: nothing is typed or submitted; only FAQ answers are opened. */
+export async function captureExhibits(browser: Browser, urls: string[]): Promise<Exhibit[]> {
+  const context = await browser.newContext();
+  try {
+    const out: Exhibit[] = [];
+    for (const url of urls) {
+      const page = await context.newPage();
+      await page.goto(url, { waitUntil: "domcontentloaded" });
+      await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+      await openFaqAnswers(page);
+      const o = await observe(page);
+      const text = (await page.locator("body").innerText()).replace(/\s+/g, " ").trim().slice(0, MAX_TEXT);
+      out.push({
+        id: pathOf(o.url) || url,
+        kind: kindOf(o.url, o.title, text),
+        title: o.title,
+        url: o.url,
+        text,
+        elements: o.elements.filter((e) => e.name).map((e) => `${e.role}: ${e.name}`),
+      });
+      await page.close();
+    }
+    return out;
+  } finally {
+    await context.close();
+  }
+}
+
+/**
+ * An idea-stage artifact or variant: a pitch, pricing sketch or copy draft as text, read as a
+ * buyer would see it (HTML comments are authors' notes and are dropped).
+ */
+export async function exhibitFromFile(path: string): Promise<Exhibit> {
+  const text = (await readFile(path, "utf8")).replace(/<!--[\s\S]*?-->/g, "").trim().slice(0, MAX_TEXT);
+  const name = basename(path);
+  const heading = text.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  const kind = kindOf("file", heading ?? name, text);
+  return { id: name, kind: kind === "other" ? "pitch" : kind, title: heading ?? name, text, elements: [] };
+}
+
+/** Exhibits as prompt text. */
+export function renderExhibits(exhibits: Exhibit[]): string {
+  return exhibits
+    .map(
+      (e) =>
+        `### Exhibit ${e.id} (${e.kind})${e.url ? ` ${e.url}` : ""}\nTitle: ${e.title}\n${e.elements.length ? `Controls: ${e.elements.slice(0, 40).join("; ")}\n` : ""}Copy:\n${e.text}`,
+    )
+    .join("\n\n");
+}
+
+const norm = (s: string) => s.trim().toLowerCase().replace(/\/+$/, "") || "/";
+
+/** Evaluators name pages loosely ("landing", "/pricing/", a full URL, the title); map that back to an exhibit id. */
+export function canonicalExhibitId(ref: string | undefined, exhibits: Exhibit[]): string | undefined {
+  if (!ref) return undefined;
+  const r = norm(ref);
+  const path = (() => {
+    try {
+      return norm(new URL(ref).pathname);
+    } catch {
+      return r;
+    }
+  })();
+  const hit =
+    exhibits.find((e) => norm(e.id) === r || norm(e.id) === path) ??
+    exhibits.find((e) => e.url && (norm(e.url) === r || norm(pathOf(e.url)) === path)) ??
+    exhibits.find((e) => e.kind === r) ??
+    exhibits.find((e) => norm(e.title) === r);
+  return hit?.id;
+}

package/src/perception/market-context.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { LlmClient } from "../llm/types";
+import { extractJsonObject } from "../util/json";
+import { renderExhibits, type Exhibit } from "./exhibits";
+
+const MarketContextSchema = z.object({
+  competitors: z
+    .array(z.object({ name: z.string().min(1), url: z.string().optional(), pricing: z.string(), positioning: z.string() }))
+    .min(1),
+  complaints: z.array(z.string()),
+  switchingTriggers: z.array(z.string()),
+});
+
+/** What buyers in this market compare against, built before personas and verdicts. */
+export type MarketContext = z.infer<typeof MarketContextSchema> & { sources: string[] };
+
+const SYSTEM = `You build a Market Context bundle for a product simulation from competitors' own pages.
+For each competitor, "pricing" and "positioning" must come from the pages you are given (quote or closely summarise; write "not shown" if absent). Never invent prices.
+"complaints" are common frustrations buyers in this category have; "switchingTriggers" are what makes them switch tools. You may use general knowledge for these two, but prefix each such item with "(general knowledge)".
+Reply with one JSON object: {"competitors":[{"name","url","pricing","positioning"}],"complaints":[string],"switchingTriggers":[string]}.`;
+
+export async function buildMarketContext(
+  llm: LlmClient,
+  o: { icp: string; product: string; competitorExhibits: Exhibit[] },
+): Promise<MarketContext> {
+  const raw = await llm.complete({
+    system: SYSTEM,
+    messages: [
+      {
+        role: "user",
+        content: `Product being tested: ${o.product}\nIts buyers: ${o.icp}\n\nCompetitor pages:\n\n${renderExhibits(o.competitorExhibits)}`,
+      },
+    ],
+    maxTokens: 4000,
+  });
+  const parsed = MarketContextSchema.parse(extractJsonObject(raw));
+  return { ...parsed, sources: [...new Set(o.competitorExhibits.map((e) => e.url).filter((u): u is string => !!u))] };
+}
+
+/** A compact brief for persona and evaluator prompts. */
+export function marketBrief(ctx: MarketContext): string {
+  return [
+    "Alternatives these buyers know:",
+    ...ctx.competitors.map((c) => `- ${c.name}: ${c.pricing} (${c.positioning})`),
+    ctx.complaints.length ? `Common frustrations in this category: ${ctx.complaints.join("; ")}` : "",
+    ctx.switchingTriggers.length ? `What makes buyers switch: ${ctx.switchingTriggers.join("; ")}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}