@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/research.mjs

@@ -0,0 +1,1130 @@
+// `palate research "<job>" [--route /] [--urls a,b,c] [--inspire d,e]`: what a designer spends hours on before a new
+// screen, done before any build. palate
+//   1. understands the job (product, audience, industry, mood, a working metaphor, and whether the project already
+//      has a brand to work inside or starts from scratch) and writes the web searches for competitors and category
+//      leaders (palate can't search; the calling agent runs them and calls back with the URLs it found),
+//   2. looks at those pages live, plus a few well-crafted ones from palate's own short list (kb/inspiration),
+//      politely: robots.txt for every page, one page at a time per host a few seconds apart, at most 12 per run,
+//      never logging in, never submitting anything, skipping bot walls and CAPTCHAs,
+//   3. ranks them by craft (measured principles), the user's taste (rules, profile, past research verdicts) and
+//      diversity (no five near-identical heroes), keeping the best 4–6,
+//   4. distils them into abstract notes: what makes each work, the moves it uses (moves library ids), one thing
+//      this product could learn, and what the competitors all do (the cliché to avoid).
+// Everything stays in the project: <project>/.palate/research/<name>/ (gitignored) holds the screenshots (the user's
+// private moodboard), research.md, contact.png and research.json. Nothing is uploaded; palate ships no third-party
+// screenshots, code, copy, images or fonts. `palate direction "<job>" --from-research <name>` turns it into 3 art
+// directions; the chosen one carries into palate build, and novelty.mjs compares the build with every reference.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { MEASURE } from "../capture.mjs";
+import { fontClass } from "../catalog/classify.mjs";
+import { brandOf } from "../context.mjs";
+import { MOTION_INIT, contactSheet, scrollThrough } from "../look.mjs";
+import { acquireBrowser } from "../pool.mjs";
+import { measurePrinciples, principleFindings, principleFacts } from "../principles.mjs";
+import { BOT_WALL, UA_SUFFIX, mayLook, politeRun, publicUrl } from "../robots.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { TASTE_DIR, readJson } from "./common.mjs";
+import { costLine, estimate, logCost } from "./cost.mjs";
+import { ARCH_NAME, DUPLICATE, SIMILAR, compare, layoutRecord, screenOf } from "./layouts.mjs";
+import { activeRules, appliesTo, checkRules, kindTags, measureRules, projectOf } from "./rules.mjs";
+import { KB_ROOT } from "../paths.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const KB_DIR = process.env.PALATE_KB ?? KB_ROOT;
+export const INDEX_FILE = path.join(KB_DIR, "inspiration", "index.json");
+// The user's own growing list: pages their research looked at and kept (links and palate's tags only).
+export const LOCAL_INDEX = path.join(PALATE_HOME, "research", "inspiration.json");
+// What the user said about research references and which ones fed a kept build: palate's learning log.
+export const RESEARCH_LOG = path.join(TASTE_DIR, "research.jsonl");
+export const MAX_CAPTURES = 12;
+const script = (f) => fs.readFileSync(path.join(here, "..", f), "utf8").trim().replace(/;\s*$/, "");
+const slash = (p) => String(p).replace(/\\/g, "/");
+const uniq = (a) => [...new Set(a.filter(Boolean))];
+const readLines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, "utf8").split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean) : []);
+const read = (f) => {
+  try {
+    return fs.readFileSync(f, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+// The rule every brief built from research carries, word for word.
+export const LICENCE_RULE = "Use the ideas, never the expression: no copied code, copy, images, illustrations, logos or paid fonts; nothing that looks like one specific site.";
+
+// The moves library (kb/moves/*.md, src/moves.mjs). If it isn't there, palate's older move list stands in.
+const Moves = await import("../moves.mjs").catch(() => null);
+function fallbackMoves() {
+  try {
+    const yaml = read(path.join(KB_DIR, "moves", "moves.yaml"));
+    return [...yaml.matchAll(/- id: ([\w-]+)\n\s+family: (\w+)[\s\S]*?signals: \[([^\]]*)\][\s\S]*?cost: (\w+)/g)].map((m) => ({ id: m[1], name: m[1].replace(/-/g, " "), kind: m[2], fits: m[3].split(",").map((x) => x.trim()), signature: ["composition", "motion", "interaction"].includes(m[2]) && m[4] !== "low" }));
+  } catch {
+    return [];
+  }
+}
+export function matchMovesSafe(q = {}) {
+  if (Moves?.matchMoves && Moves.loadMoves().length) return Moves.matchMoves(q);
+  const tags = (q.tags ?? []).map((t) => String(t).toLowerCase());
+  return fallbackMoves()
+    .filter((m) => q.signature == null || m.signature === Boolean(q.signature))
+    .filter((m) => !(q.exclude ?? []).includes(m.id))
+    .map((m) => ({ ...m, score: m.fits.filter((f) => tags.includes(f)).length, reason: "palate concept move (the moves library isn't installed)" }))
+    .filter((m) => !tags.length || m.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, q.limit ?? 8);
+}
+export const moveBriefSafe = (ids) => (Moves?.moveBrief ? Moves.moveBrief(ids) : ids.map((id) => `### ${id}\n(the moves library isn't installed: palate concept describes this move)`).join("\n\n"));
+export const moveExists = (id) => (Moves?.loadMoves ? Moves.loadMoves().some((m) => m.id === id) : fallbackMoves().some((m) => m.id === id));
+
+// ---- 1. understand
+// Order matters: the first match leads (it picks the competitors). Specific categories come before generic words,
+// and businesses that aren't software (a bakery, an inn, a nonprofit, a studio) have their own categories, so a
+// bakery isn't read as "commerce" or a tool library as "dev-tools".
+const INDUSTRY = [
+  [/\bshared (inbox|mailbox)|team inbox|group inbox|collaborative inbox\b/, ["shared-inbox", "email", "collaboration"]],
+  [/\b(observability|distributed tracing|tracing|traces|apm|telemetry|opentelemetry|monitoring|log management|error tracking|incident response)\b/, ["observability", "dev-tools"]],
+  [/\b(ci|ci\/cd|continuous integration|build pipelines?|monorepos?|schema migrations?|database migrations?|migration cli|feature flags?|docs-as-code|api documentation)\b/, ["dev-tools"]],
+  [/\b(bakery|bakeries|bakehouse|patisserie|boulangerie|bread|pastry|pastries|croissants?)\b/, ["bakery", "food", "hospitality"]],
+  [/\b(restaurants?|bistro|brasserie|trattoria|caf[eé]s?|coffee (shop|house|roasters?)|diner|eatery|wood-fired|tasting menu|wine bar|cocktail bar|brewery|pub)\b/, ["restaurant", "food", "hospitality"]],
+  [/\b(inns?|hotels?|hostels?|b&b|bed and breakfast|guest ?house|lodges?|resorts?)\b/, ["lodging", "hospitality", "travel"]],
+  [/\b(tour operators?|guided tours|walking tours|travel|(rail|train|walking|cycling|small-group) journeys|trips|holidays|itinerar(y|ies))\b/, ["travel"]],
+  [/\b(architects?|architecture|architectural)\b/, ["architecture", "portfolio"]],
+  [/\b(photograph(er|ers|y)|portraits?|weddings?)\b/, ["photography", "portfolio"]],
+  [/\b(type foundry|typefaces?|font licen[cs]es?)\b/, ["type-foundry", "creative"]],
+  [/\b(risograph|print studio|printmaking|letterpress|screen ?print(ing)?)\b/, ["print", "creative"]],
+  [/\b(sound design|music studio|original music|composers?|recording studio|audio post)\b/, ["music", "creative"]],
+  [/\b(non-?profits?|charit(y|ies)|volunteers?|volunteer programme|foundation|mutual aid|tool library|civic|ballots?|voters?|elections?|nonpartisan)\b/, ["nonprofit", "civic"]],
+  [/\b(river|water quality|conservation|climate|environment(al)?|wildlife)\b/, ["environment"]],
+  [/\b(classes|workshops?|courses?|coding clubs?|after-school|literacy|tutoring|reading and writing|language exchange|teach(ing|ers)?)\b/, ["education"]],
+  [/\b(pottery|ceramics?|bookbinding|hand-bookbinding|woodworking|weaving)\b/, ["craft"]],
+  [/\b(florists?|flowers?|bouquets?)\b/, ["florist", "local-business"]],
+  [/\b(repair shop|bike (shop|repair)|bicycles?|alterations|tailor(ing)?|clothing repair|mending|cobbler|barbers?|salon)\b/, ["local-business"]],
+  [/\b(meal[- ]planning|recipes?|groceries|grocery|cooking|fridge|pantry)\b/, ["food"]],
+  [/\b(football|basketball|soccer|sports?|pickup games?|running club)\b/, ["sports"]],
+  [/\b(budget(s|ing)?|personal finance|savings)\b/, ["finance"]],
+  [/\b(inbox|e-?mails?|mail)\b/, ["email"]],
+  [/\b(support|help ?desk|tickets?|customer service)\b/, ["support", "customer-service"]],
+  [/\b(design studios?|agenc(y|ies)|creative|designers?|studios?|illustrators?|architects?)\b/, ["creative"]],
+  [/\b(developers?|api|sdk|code|devops|deploy(ment)?s?|cli)\b/, ["dev-tools"]],
+  [/\b(bank(ing)?|finance|payments?|invoic(e|es|ing)|accounting|expenses?|payroll)\b/, ["finance"]],
+  [/\b(notes?|writing|docs|documents|knowledge base|wiki)\b/, ["notes", "writing", "docs"]],
+  [/\b(tasks?|to-?dos?|projects?|kanban|issues?|roadmaps?)\b/, ["productivity", "project-management"]],
+  [/\b(calendar|scheduling|bookings?|appointments?)\b/, ["scheduling"]],
+  [/\b(analytics|metrics|insights dashboard)\b/, ["analytics"]],
+  [/\b(crm|sales|pipeline|leads)\b/, ["crm"]],
+  [/\b(shop|store|e-?commerce|retail|checkout)\b/, ["commerce"]],
+  [/\b(health|wellness|meditation|sleep|fitness|therapy)\b/, ["wellness"]],
+  [/\b(ai|agents?|llms?|assistant|copilot)\b/, ["ai"]],
+  [/\b(security|passwords?|auth(entication)?|privacy)\b/, ["security"]],
+  [/\b(chat|messaging|team communication)\b/, ["collaboration"]],
+  [/\b(video|podcasts?|audio|music)\b/, ["video"]],
+  [/\b(research|interviews|user testing)\b/, ["research"]],
+];
+// [words, index moods, moves-library tags]
+const MOOD = [
+  [/\b(calm|calmer|calmly|quiet|peaceful|serene|unhurried|gentle|soft|slow|zen|relaxed)\b/, ["calm", "quiet", "minimal"], ["calm", "quiet"]],
+  [/\b(craft(ed)?|handmade|careful|thoughtful|design studios?|designers?|artisan)\b/, ["crafted", "editorial"], ["crafted", "editorial"]],
+  [/\b(playful|fun|whimsical|delightful|cheeky)\b/, ["playful"], ["playful"]],
+  [/\b(bold|loud|confident|striking|punchy)\b/, ["bold"], ["bold"]],
+  [/\b(premium|luxury|high-end|elegant|refined)\b/, ["premium"], ["premium"]],
+  [/\b(technical|developers?|engineers?)\b/, ["technical", "precise"], ["technical", "developer"]],
+  [/\b(warm|friendly|human|personal|small (teams?|studios?|business(es)?))\b/, ["warm", "friendly", "human"], ["warm", "friendly"]],
+  [/\b(editorial|magazine|story|stories|journal)\b/, ["editorial"], ["editorial"]],
+  [/\b(fast|speed|quick|instant|snappy)\b/, ["fast", "precise"], ["energetic"]],
+  [/\b(simple|minimal|clean|focused)\b/, ["minimal"], ["minimal"]],
+  [/\b(trust(ed|worthy)?|secure|reliable|safe)\b/, [], ["trustworthy"]],
+  [/\b(nature|ocean|sea|tide|forest|garden|river)\b/, ["calm"], ["nature"]],
+];
+const SAAS = new Set(["shared-inbox", "email", "support", "dev-tools", "observability", "finance", "notes", "productivity", "project-management", "scheduling", "analytics", "crm", "ai", "security", "collaboration", "research"]);
+// Categories that are a business, a place or a practice, not software: their searches look for comparable sites
+// ("best bakery websites"), never "<x> software" or "<famous SaaS> alternatives".
+const BUSINESS = new Set(["bakery", "restaurant", "food", "hospitality", "lodging", "travel", "architecture", "photography", "portfolio", "type-foundry", "print", "music", "nonprofit", "civic", "environment", "education", "craft", "florist", "local-business"]);
+// The category's head noun says whether the product is software ("…app", "…CLI", "…service").
+const SOFTWARE_HEAD = /\b(apps?|software|saas|platform|tools?|service|cli|sdk|api|generator|extension|plugin|bot|engine|editor|dashboard|inbox|client|tracker|planner|tracing|monitoring|analytics|crm)$/i;
+// Index entries that aren't software sites (a retailer, a magazine, a hardware maker): the only craft picks a
+// business gets, so a bakery isn't shown three note-taking apps.
+const SOFTWARE_SITE = new Set([...SAAS, "payments", "banking", "infrastructure", "design-tools", "presentation", "browser", "tasks", "reading", "video", "wellness"]);
+const NON_SOFTWARE_SITE = new Set(["retail", "publishing", "hardware", ...BUSINESS]);
+export const softwareSite = (s) => (s.industry ?? []).some((i) => SOFTWARE_SITE.has(i)) || !(s.industry ?? []).some((i) => NON_SOFTWARE_SITE.has(i));
+// When the job names no mood, a guess from the category (the blueprint decides the real mood).
+const CATEGORY_MOOD = [
+  [["bakery", "restaurant", "food", "florist", "local-business", "craft"], ["warm", "crafted"]],
+  [["lodging", "travel", "environment"], ["calm", "warm"]],
+  [["nonprofit", "civic", "education"], ["warm", "friendly"]],
+  [["architecture", "photography"], ["editorial", "quiet"]],
+  [["type-foundry", "print", "music", "creative"], ["crafted", "editorial"]],
+];
+// Images a product name can carry: palate's own short phrases, used as a first working metaphor.
+const IMAGES = {
+  tidepool: "a tide pool: a small, still pool the tide leaves behind, where everything that matters is visible at a glance while the sea keeps moving",
+  tide: "the tide: things arrive in waves and go out again on a rhythm",
+  pool: "a still pool: clear enough to see to the bottom",
+  harbor: "a harbour: what comes in gets tied up and looked after",
+  harbour: "a harbour: what comes in gets tied up and looked after",
+  lantern: "a lantern: one warm light that shows the next step",
+  atlas: "an atlas: the whole territory, folded so you can find your place",
+  ledger: "a ledger: every line accounted for, in order",
+  garden: "a garden: tended a little every day, it grows",
+  orbit: "an orbit: things come round again, on time",
+  field: "a field: open space with room to see far",
+  nest: "a nest: small, built by hand, safe",
+  hive: "a hive: many hands, one shared order",
+  compass: "a compass: one needle that always points the way",
+  anchor: "an anchor: holds steady while things move around it",
+  beacon: "a beacon: seen from far, it says where to go",
+  loom: "a loom: many threads woven into one cloth",
+  river: "a river: a steady current that carries things along",
+  stream: "a stream: a light, steady flow",
+  meadow: "a meadow: open, quiet, unhurried",
+  stone: "a stone: smooth, solid, simple",
+  paper: "paper: a clean sheet, ready to be written on",
+  ink: "ink: one mark, made to last",
+  slate: "a slate: wiped clean at the end of the day",
+  cove: "a cove: a sheltered bay away from the open sea",
+  shore: "the shore: where the waves come in and settle",
+  reef: "a reef: a living structure built up piece by piece",
+  lighthouse: "a lighthouse: a steady signal in rough weather",
+  hearth: "a hearth: the warm centre of the house",
+  shelf: "a shelf: everything in its place, in reach",
+  folio: "a folio: work gathered and bound with care",
+  pebble: "a pebble: small, smooth, worn calm by the water",
+  post: "a post room: every letter sorted and delivered",
+  desk: "a clean desk: only what today needs",
+  studio: "a studio: a working room where things get made",
+  bloom: "a bloom: something opens at the right moment",
+  moss: "moss: soft, slow, quietly covering everything",
+};
+const INDUSTRY_METAPHOR = {
+  "shared-inbox": "a well-run front desk: everything that arrives is seen, owned and answered",
+  email: "a quiet post room: every letter sorted, nothing shouting",
+  support: "a good concierge: you're known, and it's handled",
+  "dev-tools": "a workbench: the right tool in reach, nothing in the way",
+  finance: "a ledger: every line accounted for",
+  notes: "a commonplace book: ideas kept in one well-bound place",
+  productivity: "a clean desk: only what today needs",
+  "project-management": "a map of the work: where everything is and where it's going",
+  scheduling: "a well-kept diary",
+  analytics: "an instrument panel: the few readings that matter",
+  wellness: "a deep breath",
+  commerce: "a shop window: the thing itself, well lit",
+  creative: "a studio wall: work pinned up where everyone can see it",
+};
+const MOOD_METAPHOR = { calm: "slack water: the still moment between tides", warm: "a kitchen table where the team sits down together", crafted: "a well-made tool, worn in", playful: "a toy box", premium: "a quiet hotel lobby", technical: "an engineering drawing", editorial: "a printed journal" };
+
+function splitName(name) {
+  const s = String(name ?? "").toLowerCase().replace(/[^a-z]/g, "");
+  if (IMAGES[s]) return [s];
+  for (let i = 3; i < s.length - 2; i++) if (IMAGES[s.slice(0, i)] && IMAGES[s.slice(i)]) return [s.slice(0, i), s.slice(i)];
+  return [];
+}
+export function metaphorFor({ product, industry = [], mood = [] } = {}) {
+  const parts = splitName(product);
+  const whole = parts.length === 1 ? IMAGES[parts[0]] : parts.length === 2 ? `${IMAGES[parts[0]].split(":")[0]} meets ${IMAGES[parts[1]]}` : null;
+  const fromIndustry = industry.map((i) => INDUSTRY_METAPHOR[i]).find(Boolean);
+  const fromMood = mood.map((m) => MOOD_METAPHOR[m]).find(Boolean);
+  const all = uniq([whole, fromIndustry, fromMood, "the product's own core object, shown plainly"]);
+  return { primary: all[0], alternates: all.slice(1, 3), from: whole ? `the name ${product}` : fromIndustry ? "the category" : "the mood" };
+}
+
+const TEMPLATE_README = /This template provides|Vite \+|bootstrapped with|create-react-app|Getting Started with|npm run dev/i;
+const GENERIC_NAME = /^(app|web|site|demo|template|starter|my-?app|vite|next|react|project)([-_].*)?$|[-_](demo|app|site|web|starter)$/i;
+// Never inside a hyphenated word: "small-group rail journeys" keeps its "small".
+const MOOD_WORDS = /(?<![\w-])(calm|calmer|quiet|simple|modern|beautiful|fast|friendly|playful|bold|premium|minimal|clean|gentle|soft|new|better|smart|powerful|lightweight|focused|tiny|small|little)(?![\w-])/gi;
+// A product name: capitalised words, possessives and apostrophes (Mabel's, Mabel’s), "&" / "and" / "of" between
+// them (Ember & Oak, House of Bread), up to five words (North Arc Architects).
+const NAME = "[A-Z0-9][\\w.'’-]*(?:(?:\\s+(?:&|and|\\+|of|the|de|du|la|le)\\s+|\\s+)[A-Z0-9][\\w.'’-]*){0,4}";
+// People an audience is made of: "for kids aged 9–14" is an audience, "for weekend pickup" is not.
+const PEOPLE = /\b(teams?|people|kids|children|adults|famil(y|ies)|couples|developers|engineers|designers|studios|students|parents|owners|founders|freelancers|nomads|backpackers|travell?ers|members|neighbou?rs|volunteers|businesses|companies|startups|agencies|makers|artists|writers|readers|musicians|athletes|players|seniors|patients|customers|shops|restaurants|creators|marketers|managers|clinics)\b/i;
+const RELATIVE = /\s+(?:that|which|who|whose|where|with|so that|to help)\s+/i;
+// "a neighbourhood bakery that takes pre-orders for weekend pickup" → category "neighbourhood bakery", does
+// "takes pre-orders for weekend pickup", no audience. "a social hostel in Lisbon for backpackers" → category
+// "social hostel", place "Lisbon", audience "backpackers". "distributed tracing for small engineering teams" →
+// category "distributed tracing", audience "small engineering teams".
+export function describe(description) {
+  const d = String(description ?? "").replace(/^(an?|the)\s+/i, "").trim();
+  if (!d) return { category: null, head: null, audience: null, place: null, does: null };
+  const cut = d.search(RELATIVE);
+  let head = cut >= 0 ? d.slice(0, cut) : d;
+  const does = cut >= 0 ? d.slice(cut).trim() : null;
+  let audience = null;
+  const forAt = head.match(/^(.*?)\s+for\s+(.+)$/i);
+  // "an app for organising pickup games": a purpose, not an audience; it stays in the category.
+  if (forAt && !/^[a-z]+ing\b/i.test(forAt[2])) [head, audience] = [forAt[1], forAt[2]];
+  if (!audience && does) audience = does.match(/\bfor\s+((?:small |large |busy |remote |independent |local )?[a-z0-9][a-z0-9 '’–-]{2,60}?)(?=[.,;)]|$)/i)?.[1] ?? null;
+  if (audience && !forAt?.[2]?.startsWith(audience) && !PEOPLE.test(audience)) audience = null;
+  if (audience) audience = audience.split(RELATIVE)[0].trim();
+  const at = head.match(/\s+(?:in|on the|across|near|around)\s+((?:the\s+)?[A-Z][^,;]*)$/);
+  const place = at ? at[1].trim() : (does?.match(/\b(?:in|across|on the)\s+((?:the\s+)?[A-Z][\w'’-]+(?:\s+[A-Z][\w'’-]+)*)/)?.[1] ?? null);
+  if (at) head = head.slice(0, at.index);
+  const forPurpose = head.match(/^(.*?)\s+for\s+[a-z]+ing\b/i)?.[1];
+  const category =
+    head
+      .replace(MOOD_WORDS, "")
+      .replace(/\s+(built|made|designed)$/i, "")
+      .replace(/^\d+[-–]\w+\s+/, "")
+      .replace(/\s+/g, " ")
+      .trim() || null;
+  return { category, head: (forPurpose ?? category ?? "").replace(MOOD_WORDS, "").replace(/\s+(built|made|designed)$/i, "").trim() || null, audience: audience || null, place, does };
+}
+
+export function understand(dir, job, { route } = {}) {
+  const text = String(job ?? "").trim();
+  if (!text) throw new Error('Usage: palate research "<the job, in the user\'s words>" [--route /] [--urls a,b,c]');
+  // Stored in research.json and carried into the direction: a Git Bash path is refused here, never stored.
+  if (route) route = normalizeRoute(route);
+  const pkg = (() => {
+    try {
+      return JSON.parse(read(path.join(dir, "package.json")) || "{}");
+    } catch {
+      return {};
+    }
+  })();
+  const readmeRaw = read(path.join(dir, "README.md")).slice(0, 4000);
+  const readme = TEMPLATE_README.test(readmeRaw) ? "" : readmeRaw;
+  // "for Tidepool, a calm shared inbox for small design studios" · "Tidepool, a calm…" · "called Tidepool" ·
+  // "for Mabel's Bakehouse, a bakery…" · "for Ember & Oak, a restaurant…" · "for North Arc Architects, a…"
+  const named = text.match(new RegExp(`\\b(?:for|called|named|of)\\s+(${NAME})(?=\\s*(?:,|\\(|:|—|–|-\\s|$))`)) ?? text.match(new RegExp(`(?:^|[.!?:—–]\\s*)(${NAME}),\\s+(?:an?|the)\\s`)) ?? text.match(/\b([A-Z][a-z]+[A-Za-z0-9]*),\s+(?:an?|the)\s/);
+  const readmeName = readme.match(/^#\s+([A-Z][\w .'’&-]{1,40})$/m)?.[1]?.trim();
+  const product = named?.[1] ?? readmeName ?? (pkg.name && !GENERIC_NAME.test(pkg.name) ? pkg.name : null);
+  const description = (product && text.match(new RegExp(`${product.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*[,(:—–-]\\s*((?:an?|the)\\s[^.;()]+|[a-z][^.;()]+)`))?.[1]?.trim()) || pkg.description || null;
+  const parts = describe(description);
+  const forPart = description ? parts.audience : text.match(/\bfor ((?:small |large |busy |remote |independent )?[a-z][a-z -]{2,40}?)(?=[.,;)]|$)/i)?.[1]?.trim();
+  const audience = forPart && forPart !== product ? forPart : null;
+  const category = parts.category;
+  // The job names the category; the README only when the job doesn't (its words are noisy: a tracing tool's README
+  // mentions checkout and invoices, which made it "finance, commerce").
+  const fromJob = INDUSTRY.filter(([re]) => re.test(`${text} ${description ?? ""}`.toLowerCase()));
+  const industry = uniq((fromJob.length ? fromJob : INDUSTRY.filter(([re]) => re.test(readme.toLowerCase()))).flatMap(([, t]) => t));
+  const business = industry.some((i) => BUSINESS.has(i));
+  const software = SOFTWARE_HEAD.test(parts.head ?? "") || (industry.some((i) => SAAS.has(i)) && !business);
+  const moodHits = MOOD.filter(([re]) => re.test(`${text} ${description ?? ""}`.toLowerCase()));
+  let mood = uniq(moodHits.flatMap(([, m]) => m));
+  // No mood words in the job: a placeholder for the moves library only. The blueprint decides the real mood
+  // from the audience and product (moodGuessed tells it this one was guessed).
+  const moodGuessed = !mood.length;
+  if (!mood.length) mood = software && industry.includes("dev-tools") ? ["technical", "precise"] : industry.map((i) => CATEGORY_MOOD.find(([of]) => of.includes(i))?.[1]).find(Boolean) ?? ["crafted"];
+  const tags = uniq([...moodHits.flatMap(([, , t]) => t), ...(software && industry.some((i) => SAAS.has(i)) ? ["saas", "b2b"] : []), ...(industry.includes("email") || industry.includes("productivity") ? ["productivity", "daily-tool"] : []), ...(industry.includes("ai") ? ["ai"] : []), ...(industry.includes("finance") ? ["finance"] : []), ...(industry.includes("dev-tools") ? ["developer"] : [])]);
+  const screen = (() => {
+    const s = screenOf("", `${route ?? ""} ${text}`);
+    return s === "other" && (route === "/" || /\bhome ?page|landing\b/i.test(text)) ? "landing" : s;
+  })();
+  const kind = { landing: "landing", hero: "landing", pricing: "pricing", features: "features", docs: "docs" }[screen] ?? "landing";
+  const brand = brandOf(dir, text);
+  const u = { moodGuessed, job: text, product, description, audience, category: category || (industry[0] ?? "").replace(/-/g, " ") || null, industry, software, place: parts.place, does: parts.does, mood, tags, screen, kind, route: route ?? null, metaphor: metaphorFor({ product, industry, mood }), brand: { mode: brand.mode, rebrand: brand.rebrand, line: brand.line, brandColour: brand.brandColour, fonts: brand.fonts, customFonts: brand.customFonts, radii: brand.radii, components: brand.components, colours: brand.colours.slice(0, 24), tokenFiles: brand.tokenFiles } };
+  u.queries = queriesFor(u);
+  return u;
+}
+
+// ---- the shipped list, plus what this user's research added
+export function loadIndex() {
+  const shipped = readJson(INDEX_FILE, { sites: [], browse: [] });
+  const local = readJson(LOCAL_INDEX, { sites: [] });
+  const key = (s) => s.url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "");
+  const by = new Map();
+  for (const s of [...(shipped.sites ?? []), ...(local.sites ?? []).map((s) => ({ ...s, local: true }))]) if (!by.has(key(s))) by.set(key(s), s);
+  return { sites: [...by.values()], browse: shipped.browse ?? [] };
+}
+
+// Index entries for this job: competitors (same category) and well-crafted pages that share its mood.
+export function matchIndex(u, { competitors = 4, craft = 3, exclude = [] } = {}) {
+  const { sites } = loadIndex();
+  const host = (url) => url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/.*$/, "");
+  const skip = new Set(exclude.map(host));
+  const lead = u.industry[0];
+  const scored = sites
+    .filter((s) => !skip.has(host(s.url)))
+    .map((s) => {
+      const ind = (s.industry ?? []).filter((i) => u.industry.includes(i)).length;
+      const mood = (s.mood ?? []).filter((m) => u.mood.includes(m)).length;
+      const kind = (s.kind ?? []).includes(u.kind) ? 1 : 0;
+      return { ...s, competitor: Boolean(lead && (s.industry ?? []).includes(lead)), match: { industry: ind, mood, kind }, score: 3 * ind + 2 * mood + kind + ((s.industry ?? []).includes(lead) ? 2 : 0) };
+    });
+  const comp = scored.filter((s) => s.competitor).sort((a, b) => b.score - a.score || b.match.mood - a.match.mood).slice(0, competitors);
+  // A business (a bakery, an inn, a studio) gets craft picks that aren't software sites, or none: a note-taking
+  // app's landing page teaches a bakery nothing.
+  const crafted = scored.filter((s) => !s.competitor && s.match.mood > 0 && (u.software !== false || !softwareSite(s))).sort((a, b) => b.match.mood - a.match.mood || b.score - a.score).slice(0, craft);
+  return { competitors: comp, craft: crafted };
+}
+
+// "neighbourhood bakery" → "bakery"; "two-person risograph print studio" → "print studio"; "documentary wedding
+// and portrait photographer" → "wedding and portrait photographer".
+const BROAD = new Set(["dev-tools", "productivity", "creative", "collaboration", "ai", "commerce", "finance", "food", "education", "local-business"]);
+const GENERIC_LAST =/^(shop|studio|practice|programme|program|operator|guide|library|workshop|foundry|service|company|agency|club|centre|center|school|house|inn|hostel|hotel|bar|kitchen|market|collective|co-op|cooperative)$/i;
+export function headNoun(cat) {
+  const w = String(cat ?? "").trim().split(/\s+/).filter(Boolean);
+  if (w.length >= 4 && /^(and|&)$/i.test(w.at(-3))) return w.slice(-4).join(" ");
+  if (w.length >= 2 && GENERIC_LAST.test(w.at(-1))) return w.slice(-2).join(" ");
+  return w.at(-1) ?? "";
+}
+
+// The searches the calling agent runs with its own web search (palate can't search).
+export function queriesFor(u) {
+  const cat = u.category || u.industry[0]?.replace(/-/g, " ") || "product";
+  // "<leader> alternatives" only when the leader is in the product's own category: a broad bucket (dev-tools,
+  // finance) would make Linear the alternative to a CI service, or Stripe to a budgeting app.
+  const leaders = BROAD.has(u.industry[0]) ? [] : matchIndex(u, { competitors: 2, craft: 0 }).competitors.map((c) => c.name);
+  const year = new Date().getFullYear();
+  const screenPage = u.screen !== "other" && u.screen !== "landing" ? `${u.screen} page` : null;
+  // A business, not software: comparable businesses' own sites ("best bakery websites", "bakery Lisbon"), the
+  // category's leaders by name when palate knows them, never "<x> software" or "<famous SaaS> alternatives".
+  if (u.software === false) {
+    const noun = headNoun(cat);
+    const does = u.does ? u.does.split(/\s+/).slice(0, 12).join(" ").replace(/(\s+(the|a|an|and|of|on|in|your|their|for|to|with))+$/i, "") : null;
+    return uniq([
+      `best ${noun} websites${u.place ? ` ${u.place}` : ""}`,
+      u.place ? `${cat} ${u.place}` : null,
+      `${cat} website design`,
+      `independent ${noun.replace(/^independent\s+/i, "")} websites`,
+      does ? `${noun} ${does}` : null,
+      ...leaders.map((l) => `sites like ${l}`),
+      u.audience ? `${noun} for ${u.audience}` : null,
+    ]).slice(0, 6);
+  }
+  return uniq([
+    `${cat}${/\b(apps?|software|service|platform|cli|tools?|sdk|api|generator)\b/i.test(cat) ? "" : " software"}${u.audience ? ` for ${u.audience}` : ""}`,
+    /\bapps?$/i.test(cat) ? `best ${cat.replace(/s?$/, "s")} ${year}` : /\bapps?\b/i.test(cat) ? `best ${cat} ${year}` : `best ${cat} tools ${year}`,
+    ...leaders.map((l) => `${l} alternatives`),
+    leaders.length ? null : `${cat} startups ${year}`,
+    `${u.mood[0] ?? "well designed"} ${cat}${/\bapps?\b/i.test(cat) ? "" : " app"}`,
+    screenPage ? `${leaders[0] ?? cat} ${screenPage}` : null,
+    u.brand?.mode === "brand" && screenPage ? `${cat} ${screenPage} examples` : null,
+  ]).slice(0, 6);
+}
+
+// ---- 2. look
+const sectionsScript = script("page-sections.js");
+const devicesScript = script("page-devices.js");
+const fingerprintScript = script("page-fingerprint.js");
+const REJECT = ["Reject all", "Reject All", "Reject", "Decline", "Decline all", "Only necessary", "Necessary only", "Use necessary cookies only", "Allow necessary only", "Deny"];
+// Cookie banners: palate declines (never accepts); when there is no decline button, it hides the banner from the
+// screenshot without answering it.
+async function quietBanners(page) {
+  for (const label of REJECT) {
+    const b = page.getByRole("button", { name: label, exact: true }).first();
+    if (await b.isVisible().catch(() => false)) {
+      await b.click({ timeout: 2000 }).catch(() => {});
+      await page.waitForTimeout(400);
+      return "declined";
+    }
+  }
+  return page
+    .evaluate(() => {
+      let n = 0;
+      for (const el of document.querySelectorAll('[id*="cookie" i],[class*="cookie" i],[id*="consent" i],[class*="consent" i],[aria-label*="cookie" i],#onetrust-banner-sdk,#CybotCookiebotDialog,.cc-window')) {
+        const p = getComputedStyle(el).position;
+        if (p === "fixed" || p === "sticky") {
+          el.style.setProperty("display", "none", "important");
+          n++;
+        }
+      }
+      return n ? "hidden" : "none";
+    })
+    .catch(() => "none");
+}
+
+const slugOf = (url) => {
+  const u = new URL(url);
+  return (u.hostname.replace(/^www\./, "") + u.pathname).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").slice(0, 60);
+};
+
+// One page, live: screenshots (first screen + full page) and every measurement palate takes of its own work.
+export async function lookAt(browser, target, outDir, { dir, robotsCache, allowLocal = false, fetchImpl, rules = [] } = {}) {
+  const t0 = Date.now();
+  const gate = await mayLook(target.url, { allowLocal, cache: robotsCache, fetchImpl });
+  if (!gate.ok) return { ...target, status: "skipped", why: gate.why, ms: Date.now() - t0 };
+  const ua = `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${browser.version?.() ?? "130.0.0.0"} Safari/537.36 ${UA_SUFFIX}`;
+  const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, userAgent: ua, acceptDownloads: false, serviceWorkers: "block", locale: "en-US" });
+  try {
+    const page = await ctx.newPage();
+    await page.addInitScript(MOTION_INIT);
+    let res;
+    try {
+      res = await page.goto(gate.url, { waitUntil: "domcontentloaded", timeout: 45_000 });
+    } catch (e) {
+      return { ...target, status: "skipped", why: `did not load (${String(e.message).split("\n")[0].slice(0, 80)})`, ms: Date.now() - t0 };
+    }
+    const status = res?.status() ?? 0;
+    if (status >= 400) return { ...target, status: "skipped", why: `answered ${status}${status === 403 || status === 429 ? " (blocks bots): skipped, not worked around" : ""}`, ms: Date.now() - t0 };
+    await page.waitForLoadState("networkidle", { timeout: 12_000 }).catch(() => {});
+    await page.waitForTimeout(900);
+    const finalUrl = page.url();
+    if (/\/(login|log-in|signin|sign-in|sso|auth)\b/i.test(new URL(finalUrl).pathname)) return { ...target, status: "skipped", why: "redirected to a sign-in page; palate never logs in", ms: Date.now() - t0 };
+    const wall = await page.evaluate(() => ({ title: document.title, text: (document.body?.innerText ?? "").slice(0, 2000), len: (document.body?.innerText ?? "").length, frames: [...document.querySelectorAll("iframe")].map((f) => f.src).join(" ") })).catch(() => ({ title: "", text: "", len: 0, frames: "" }));
+    if (BOT_WALL.test(wall.title) || (wall.len < 1500 && BOT_WALL.test(`${wall.text} ${wall.frames}`))) return { ...target, status: "skipped", why: "a bot check or CAPTCHA: skipped, never worked around", ms: Date.now() - t0 };
+    if (wall.len < 80) return { ...target, status: "skipped", why: "the page rendered almost no text", ms: Date.now() - t0 };
+    const banner = await quietBanners(page);
+    const slug = slugOf(finalUrl);
+    const fold = path.join(outDir, `${slug}-fold.png`);
+    await page.screenshot({ path: fold });
+    await scrollThrough(page, { pause: 160 }).catch(() => {});
+    const height = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
+    const full = path.join(outDir, `${slug}-full.jpg`);
+    await page.screenshot({ path: full, fullPage: height <= 12_000, type: "jpeg", quality: 60, ...(height > 12_000 ? { clip: { x: 0, y: 0, width: 1440, height: 12_000 }, fullPage: true } : {}) }).catch(() => {});
+    const measures = await page.evaluate(MEASURE).catch(() => null);
+    const fp = await page.evaluate(`(${fingerprintScript})()`).catch(() => null);
+    const sections = await page.evaluate(`(${sectionsScript})()`).catch(() => []);
+    const devices = await page.evaluate(`(${devicesScript})(${JSON.stringify(sections)})`).catch(() => null);
+    const principles = await measurePrinciples(page, { sections }).catch(() => null);
+    const facts = rules.length ? (await measureRules(page, rules).catch(() => null))?.facts ?? null : null;
+    const layout = fp ? layoutRecord(dir ?? process.cwd(), "/", fp, { file: fold, kind: "marketing", source: "reference" }) : null;
+    const findings = principles ? principleFindings(principles) : [];
+    return {
+      ...target,
+      url: finalUrl,
+      host: new URL(finalUrl).host,
+      status: "ok",
+      title: wall.title.slice(0, 120),
+      banner,
+      files: { fold, full: fs.existsSync(full) ? full : null },
+      measures,
+      fingerprint: fp ? { skeleton: fp.skeleton, cliches: fp.cliches, firstScreen: fp.firstScreen, style: fp.style } : null,
+      sections: sections.map((s) => s.name).slice(0, 24),
+      devices: devices ? { kickers: devices.kickers.length, kickerSections: uniq(devices.kickers.map((k) => k.section)).length, media: devices.media.map((m) => ({ kind: m.kind, section: m.section, framed: Boolean(m.framed) })), logoRows: devices.logoRows.map((r) => ({ section: r.section, count: r.count })), repeated: devices.repeated.map((r) => r.device), motion: { entrances: (devices.motion.entrances ?? 0) + (devices.motion.scriptedAnimations ?? 0) + devices.motion.cssAnimations, transitions: devices.motion.transitions } } : null,
+      principles: principles ? { facts: principleFacts(principles), counts: { high: findings.filter((f) => f.severity === "high").length, medium: findings.filter((f) => f.severity === "medium").length, low: findings.filter((f) => f.severity === "low").length }, findings: findings.slice(0, 6).map((f) => ({ id: f.id, area: f.area, severity: f.severity, what: f.what.slice(0, 200) })), spacing: { unit: principles.spacing?.unit ?? null, on8: principles.spacing?.on8 ?? null, offScale: principles.spacing?.offScaleShare ?? null }, type: { sizes: principles.type?.sizes?.length ?? null, scale: principles.type?.scale ?? null, families: (principles.type?.families ?? []).map((f) => f.family), weights: (principles.type?.weights ?? []).map((w) => w.weight) }, colours: { distinct: principles.consistency?.colors?.distinct ?? null, accent: principles.consistency?.colors?.accent ? { color: principles.consistency.colors.accent.colors?.[0], share: principles.consistency.colors.accent.share } : null }, density: (principles.density ?? []).map((d) => d.ink) } : null,
+      ruleFacts: facts,
+      layout: layout ? { shape: layout.shape, skeleton: layout.skeleton, firstScreen: layout.firstScreen, style: layout.style, moves: layout.moves, thumb: layout.thumb } : null,
+      height,
+      ms: Date.now() - t0,
+    };
+  } finally {
+    await ctx.close().catch(() => {});
+  }
+}
+
+// ---- 3. rank
+const median = (a) => {
+  const s = [...a].filter((x) => Number.isFinite(x)).sort((x, y) => x - y);
+  return s.length ? s[s.length >> 1] : null;
+};
+const hexLum = (h) => {
+  const m = String(h ?? "").match(/^#?([0-9a-f]{6})$/i);
+  if (!m) return null;
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+// What a reference does, as named traits: what palate notices, what competitors share, what a product can learn.
+const TRAITS = {
+  "live-product": { label: "the product shown live (video, canvas or real UI), not a still screenshot", lesson: "show the product working, not a still picture of it", tags: ["saas", "technical"] },
+  "serif-display": { label: "a serif display face", lesson: "a serif display face gives the voice a human, editorial register", tags: ["editorial", "crafted"] },
+  "modest-headline": { label: "a modest headline that lets the content lead", lesson: "a smaller headline makes room for the product to be the first thing seen", tags: ["calm", "minimal"] },
+  "huge-headline": { label: "a very large headline", lesson: "one oversized line can carry the whole first screen", tags: ["bold"] },
+  "light-display": { label: "a light-weight display", lesson: "a light display weight reads as quiet confidence", tags: ["calm", "premium"] },
+  airy: { label: "airy sections with lots of space", lesson: "generous space between few elements makes the page feel unhurried", tags: ["calm", "quiet", "minimal"] },
+  dense: { label: "dense, information-rich sections", lesson: "showing a lot at once can read as honesty and depth", tags: ["data-rich", "technical"] },
+  "one-accent": { label: "one accent colour used sparingly", lesson: "one accent, used rarely, makes every use of it mean something", tags: ["calm", "minimal", "premium"] },
+  "strict-rhythm": { label: "a strict spacing rhythm", lesson: "a strict spacing unit makes the whole page feel considered", tags: ["crafted", "technical"] },
+  "left-led": { label: "a left-aligned first screen", lesson: "a left-led first screen reads like a document, not an ad", tags: ["editorial"] },
+  "centred-hero": { label: "a centred hero stack", lesson: "a centred stack is clear but common", tags: [] },
+  "split-hero": { label: "a split hero (words left, product right)", lesson: "a split first screen pairs the claim with its proof", tags: ["saas"] },
+  "framed-shot": { label: "a framed product screenshot near the top", lesson: "a framed screenshot shows the product at a glance", tags: [] },
+  "logo-row": { label: "a customer logo row near the top", lesson: "early logos borrow trust", tags: ["trustworthy"] },
+  kickers: { label: "kicker labels above most headings", lesson: "small labels can organise a long page", tags: [] },
+  "equal-grid": { label: "a grid of equal feature cards", lesson: "a feature grid is scannable", tags: [] },
+  glow: { label: "a glow or gradient behind the hero", lesson: "a glow adds atmosphere", tags: [] },
+  dark: { label: "a dark theme", lesson: "a dark page reads as focused and premium", tags: ["cinematic", "premium"] },
+  pill: { label: "pill-shaped buttons", lesson: "pill buttons feel soft and friendly", tags: ["friendly"] },
+  moving: { label: "things fade or slide in on load and scroll", lesson: "motion that explains the product holds attention", tags: ["energetic"] },
+  still: { label: "a still page (nothing moves on load or scroll)", lesson: "a still page lets the words and type do the work", tags: ["calm", "quiet"] },
+  "long-page": { label: "a long page", lesson: "a long page can argue the case section by section", tags: ["editorial"] },
+  "short-page": { label: "a short page", lesson: "a short page says it once and stops", tags: ["minimal"] },
+};
+// The order a "could learn" pick prefers: distinctive, transferable ideas first.
+const LEARN_ORDER = ["live-product", "serif-display", "modest-headline", "one-accent", "airy", "strict-rhythm", "left-led", "light-display", "still", "short-page", "huge-headline", "dense", "dark", "split-hero", "moving", "long-page", "pill"];
+
+export function traitsOf(r) {
+  const out = [];
+  const m = r.measures ?? {};
+  const h = m.headline ?? {};
+  const p = r.principles ?? {};
+  const d = r.devices ?? {};
+  const shape = r.layout?.shape;
+  const sk = r.layout?.skeleton ?? r.fingerprint?.skeleton ?? [];
+  if (d.media?.some((x) => /^live/.test(x.kind))) out.push("live-product");
+  if (fontClass(h.family) === "serif" || /serif/i.test(h.family ?? "") && !/sans/i.test(h.family ?? "")) out.push("serif-display");
+  if (h.size && h.size <= 44) out.push("modest-headline");
+  if (h.size >= 72) out.push("huge-headline");
+  if (h.weight && Number(h.weight) <= 350) out.push("light-display");
+  const ink = median(p.density ?? []);
+  if (ink != null && ink < 22) out.push("airy");
+  if (ink != null && ink >= 45) out.push("dense");
+  if (p.colours?.accent && p.colours.accent.share != null && p.colours.accent.share < 3) out.push("one-accent");
+  if (p.spacing?.unit && p.spacing.offScale != null && p.spacing.offScale < 15) out.push("strict-rhythm");
+  if (shape === "centred") out.push("centred-hero");
+  if (shape === "split" || shape === "asymmetric") out.push("split-hero");
+  if (shape === "left-stack" || (sk[1] ?? sk[0] ?? "").startsWith("L")) out.push("left-led");
+  if (d.media?.some((x) => x.kind === "static picture" && x.framed && x.section <= 2)) out.push("framed-shot");
+  if (d.logoRows?.some((x) => x.section <= 3)) out.push("logo-row");
+  if ((d.kickerSections ?? 0) >= 3) out.push("kickers");
+  if (sk.some((t) => /g3/.test(t))) out.push("equal-grid");
+  if ((r.fingerprint?.cliches ?? []).includes("glow")) out.push("glow");
+  const bg = hexLum(r.layout?.style?.bg);
+  if (bg != null && bg < 90) out.push("dark");
+  if ((m.radii ?? []).includes("pill")) out.push("pill");
+  if (d.motion) out.push(d.motion.entrances >= 3 ? "moving" : d.motion.entrances === 0 ? "still" : null);
+  if (r.height > 9000) out.push("long-page");
+  if (r.height && r.height < 3600) out.push("short-page");
+  return uniq(out);
+}
+
+// 0–10, from the principles pass: fewer and milder findings, a clear spacing unit and a type scale score higher.
+export function craftScore(r) {
+  const p = r.principles;
+  if (!p) return 5;
+  const c = p.counts ?? {};
+  let s = 10 - Math.min(6, 1.5 * (c.high ?? 0) + 0.6 * (c.medium ?? 0) + 0.15 * (c.low ?? 0));
+  if (p.spacing?.unit && (p.spacing.offScale ?? 100) < 15) s += 0.5;
+  if (p.type?.scale?.fit && p.type.scale.of && p.type.scale.fit / p.type.scale.of >= 0.7) s += 0.5;
+  if ((p.type?.sizes ?? 0) > 10) s -= 0.5;
+  if ((p.type?.families ?? []).length > 2) s -= 0.3 * ((p.type.families.length ?? 2) - 2);
+  return Math.max(0, Math.min(10, +s.toFixed(1)));
+}
+
+// What this user said about research references before (likes and dislikes, by trait), and the directions they
+// chose for this kind of screen: palate's history for ranking and auto-pick.
+export function tasteHistory(screen) {
+  const traits = {};
+  const verdicts = readLines(RESEARCH_LOG).filter((x) => x.kind === "ref-verdict");
+  for (const v of verdicts.filter((v) => !screen || !v.screen || v.screen === screen)) for (const t of v.traits ?? []) traits[t] = (traits[t] ?? 0) + (v.verdict === "like" ? 1 : -1);
+  const chosen = readLines(path.join(TASTE_DIR, "directions.jsonl")).filter((d) => d.chosen && (!screen || d.screen === screen));
+  const moves = {};
+  for (const d of chosen) if (d.signature?.move) moves[d.signature.move] = (moves[d.signature.move] ?? 0) + (d.auto && !d.kept ? 0.5 : 1);
+  return { traits, moves, chosen: chosen.length, verdicts: verdicts.length };
+}
+
+// The user's taste for one reference: their rules (a failing rule costs), their profile's wins and losses, past
+// research verdicts on the same traits, and how well it matches the job's mood.
+export function tasteScore(r, u, { rules = [], profile = "", history = tasteHistory(u.screen) } = {}) {
+  let s = 0.5;
+  const notes = [];
+  if (r.ruleFacts && rules.length) {
+    const fails = checkRules(rules, r.ruleFacts).filter((x) => x.status === "fail");
+    if (fails.length) {
+      s -= 0.15 * fails.length;
+      notes.push(`fails your rule${fails.length > 1 ? "s" : ""} ${fails.map((f) => f.id).join(", ")}`);
+    }
+  }
+  const traits = traitsOf(r);
+  const loses = (profile.match(/\*\*Loses:?\*\*[^\n]*/gi) ?? []).join(" ").toLowerCase();
+  const wins = (profile.match(/\*\*Wins:?\*\*[^\n]*/gi) ?? []).join(" ").toLowerCase();
+  const KEY = { "framed-shot": /screenshot|frame/, kickers: /kicker|label/, "equal-grid": /equal (tiles|cards)|grid of equal/, glow: /glow|gradient/, "centred-hero": /centred hero|centered hero/, dark: /dark/, dense: /dense|density/, airy: /white ?space|airy|calm/, "live-product": /live|real (ui|product)|demo/ };
+  for (const t of traits) {
+    const re = KEY[t];
+    if (re && re.test(loses)) {
+      s -= 0.06;
+      notes.push(`your profile tends to reject ${TRAITS[t].label}`);
+    } else if (re && re.test(wins)) {
+      s += 0.04;
+      notes.push(`your profile tends to keep ${TRAITS[t].label}`);
+    }
+    const past = history.traits[t];
+    if (past) {
+      s += Math.max(-0.2, Math.min(0.2, 0.07 * past));
+      notes.push(`you ${past > 0 ? "liked" : "disliked"} ${TRAITS[t].label} in earlier research (${past > 0 ? "+" : ""}${past})`);
+    }
+  }
+  const moodHit = (r.mood ?? []).filter((m) => u.mood.includes(m)).length;
+  if (moodHit) s += 0.05 * moodHit;
+  return { score: Math.max(0, Math.min(1, +s.toFixed(2))), notes, traits };
+}
+
+// Best 4–6, diverse: at least two competitors (for the cliché list) and the craft picks, never two near-identical.
+export function rankRefs(refs, u, { keep, rules = [], profile = "", history } = {}) {
+  const ok = refs.filter((r) => r.status === "ok");
+  const want = keep ?? Math.min(6, Math.max(4, Math.ceil(ok.length * 0.6)));
+  for (const r of ok) {
+    r.craft = r.craft ?? craftScore(r);
+    const t = tasteScore(r, u, { rules, profile, history });
+    r.taste = t.score;
+    r.tasteNotes = t.notes;
+    r.traits = t.traits;
+    r.score = +(0.6 * (r.craft / 10) + 0.4 * r.taste + (r.role === "competitor" ? 0.03 : 0)).toFixed(3);
+  }
+  const kept = [];
+  const dropped = [];
+  const sim = (a, b) => (a.layout && b.layout ? compare(a.layout, b.layout).total : 0);
+  const take = (pool, n) => {
+    for (let i = 0; i < n; i++) {
+      const cands = pool.filter((r) => !kept.includes(r) && !dropped.some((d) => d.ref === r));
+      if (!cands.length || kept.length >= want) return;
+      let best = null;
+      for (const r of cands) {
+        const near = kept.map((k) => ({ k, s: sim(r, k) })).sort((a, b) => b.s - a.s)[0];
+        if (near && near.s >= DUPLICATE) {
+          dropped.push({ ref: r, why: `near-duplicate of ${near.k.name ?? near.k.host} (${Math.round(near.s * 100)}%)` });
+          continue;
+        }
+        const v = r.score - 0.5 * (near?.s ?? 0);
+        if (!best || v > best.v) best = { r, v, near };
+      }
+      if (best) {
+        best.r.diversity = best.near ? +(1 - best.near.s).toFixed(2) : 1;
+        kept.push(best.r);
+      }
+    }
+  };
+  const byScore = (a, b) => b.score - a.score;
+  // The pages the agent found (--urls) or the user gave (--inspire) are the research: every one that loaded is
+  // kept, first; palate's own picks only fill the slots left and never push one of them out.
+  const theirs = ok.filter((r) => r.source === "found" || r.source === "given").sort(byScore);
+  for (const r of theirs) {
+    const near = kept.map((k) => ({ k, s: sim(r, k) })).sort((a, b) => b.s - a.s)[0];
+    r.diversity = near ? +(1 - near.s).toFixed(2) : 1;
+    kept.push(r);
+  }
+  const mine = ok.filter((r) => !theirs.includes(r));
+  const has = (comp) => kept.filter((r) => (r.role === "competitor") === comp).length;
+  take(mine.filter((r) => r.role === "competitor").sort(byScore), Math.max(0, 2 - has(true)));
+  take(mine.filter((r) => r.role !== "competitor").sort(byScore), Math.max(0, 2 - has(false)));
+  take([...mine].sort(byScore), want);
+  for (const r of ok) if (!kept.includes(r) && !dropped.some((d) => d.ref === r)) dropped.push({ ref: r, why: `lower score (${r.score}) than the kept ${kept.length}` });
+  return { kept, dropped };
+}
+
+// ---- 4. distil
+// Only template-ish habits count as a cliché; a shared virtue (a strict rhythm, one accent) is not one.
+const CLICHE_ELIGIBLE = new Set(["centred-hero", "split-hero", "framed-shot", "logo-row", "kickers", "equal-grid", "glow", "pill", "huge-headline", "dark", "moving", "serif-display"]);
+const SYSTEM_FONT = /^(ui-|system-ui|-apple-system|blinkmacsystemfont|sans-serif|serif|monospace|arial|helvetica|segoe ui|roboto$)/i;
+const fontName = (f) => String(f ?? "").replace(/[-_ ](regular|medium|bold|book|light|\d{2,3}\w*)$/i, "").trim();
+// What the competitors all do: traits shared by at least 60% of them (at least two pages).
+export function clichesOf(refs) {
+  const comp = refs.filter((r) => r.status === "ok" && r.role === "competitor");
+  const pool = comp.length >= 2 ? comp : refs.filter((r) => r.status === "ok");
+  if (pool.length < 2) return [];
+  const count = {};
+  for (const r of pool) for (const t of (r.traits ?? traitsOf(r)).filter((x) => CLICHE_ELIGIBLE.has(x))) count[t] = (count[t] ?? 0) + 1;
+  const shared = Object.entries(count).filter(([, n]) => n >= Math.max(2, Math.ceil(pool.length * 0.6)));
+  // Fonts too: the same family on most of them is a cliché of its own.
+  const fonts = {};
+  for (const r of pool) for (const f of (r.measures?.fonts ?? []).filter((x) => !SYSTEM_FONT.test(x)).slice(0, 1).map(fontName)) fonts[f] = (fonts[f] ?? 0) + 1;
+  const sharedFonts = Object.entries(fonts).filter(([, n]) => n >= Math.max(2, Math.ceil(pool.length * 0.6)));
+  return [
+    ...shared.map(([t, n]) => ({ id: t, label: TRAITS[t]?.label ?? t, of: `${n} of ${pool.length}` })),
+    ...sharedFonts.map(([f, n]) => ({ id: `font:${f}`, label: `${f} as the main typeface`, of: `${n} of ${pool.length}` })),
+  ];
+}
+
+const weightWord = (w) => (Number(w) <= 300 ? "light" : Number(w) <= 450 ? "regular" : Number(w) <= 650 ? "semibold" : "heavy");
+// What makes it work, drafted from the measurements (the calling agent refines it from the screenshot).
+export function whatWorks(r) {
+  const out = [];
+  const m = r.measures ?? {};
+  const h = m.headline ?? {};
+  const p = r.principles ?? {};
+  if (h.size && m.bodySize) out.push(`A ${Math.round(h.size)}px ${weightWord(h.weight)} ${h.family || "?"} headline over ${m.bodySize}px body (a ${(h.size / m.bodySize).toFixed(1)}× step): one clear voice on the first screen.`);
+  if (p.colours?.distinct != null) out.push(`${p.colours.distinct} colours in all${p.colours.accent ? `, one accent (${p.colours.accent.color}) on about ${p.colours.accent.share < 0.1 ? "<0.1" : p.colours.accent.share}% of the page` : ", no accent hue: contrast and type carry it"}.`);
+  const ink = median(p.density ?? []);
+  if (p.spacing) out.push(`${p.spacing.unit ? `A ${p.spacing.unit}px spacing unit (${100 - (p.spacing.offScale ?? 0)}% on scale)` : "No strict spacing unit"}; sections are ${ink == null ? "?" : ink < 22 ? "airy" : ink >= 45 ? "dense" : "balanced"}${ink != null ? ` (median ${ink}% ink)` : ""}.`);
+  if (r.layout?.shape) out.push(`${(ARCH_NAME[r.layout.shape] ?? r.layout.shape).replace(/^./, (c) => c.toUpperCase())} first screen; ${r.layout.skeleton.length} bands (${r.layout.skeleton.slice(0, 7).join(" · ")}).`);
+  const live = r.devices?.media?.filter((x) => /^live/.test(x.kind)).length ?? 0;
+  const pics = r.devices?.media?.filter((x) => x.kind === "static picture").length ?? 0;
+  if (r.devices) out.push(`The product is shown ${live ? `live in ${live} place(s)` : pics ? `as ${pics} still picture(s)` : "in words, not pictures"}; ${r.devices.motion?.entrances ? `${r.devices.motion.entrances} things animate on load or scroll` : "nothing animates on load or scroll"}.`);
+  const c = p.counts;
+  if (c) out.push(c.high + c.medium <= 2 ? "Clean alignment and hierarchy: the principles pass found almost nothing." : `The principles pass found ${c.high} high and ${c.medium} medium issues (${uniq((p.findings ?? []).map((f) => f.area)).slice(0, 3).join(", ")}): good, not flawless.`);
+  return out;
+}
+
+function learnFrom(r, kept, cliches, product, used = new Set()) {
+  const shared = new Set([...cliches.map((c) => c.id), ...used]);
+  const others = kept.filter((k) => k !== r);
+  const own = (r.traits ?? []).filter((t) => !shared.has(t) && TRAITS[t]);
+  const pick = LEARN_ORDER.filter((t) => own.includes(t)).sort((a, b) => others.filter((o) => (o.traits ?? []).includes(a)).length - others.filter((o) => (o.traits ?? []).includes(b)).length)[0];
+  return pick ? { trait: pick, line: `${product ?? "This product"} could learn: ${TRAITS[pick].lesson}.` } : { trait: null, line: `${product ?? "This product"} could learn: (palate found nothing measurable that sets it apart; say what from the screenshot).` };
+}
+
+function movesFor(r, u) {
+  const tags = uniq([...(r.traits ?? []).flatMap((t) => TRAITS[t]?.tags ?? []), ...(r.mood ?? []).filter((m) => ["calm", "crafted", "editorial", "playful", "bold", "technical", "minimal", "premium", "warm", "friendly", "quiet"].includes(m))]);
+  return matchMovesSafe({ tags, limit: 3 }).map((m) => ({ id: m.id, name: m.name, why: m.reason }));
+}
+
+// ---- the whole run
+const nameOf = (u) => [u.product, u.screen !== "other" ? u.screen : null].filter(Boolean).join(" ").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "research";
+export const researchRoot = (dir) => path.join(dir, ".palate", "research");
+export function loadResearch(dir, name) {
+  const root = researchRoot(dir);
+  if (!fs.existsSync(root)) return null;
+  const names = fs.readdirSync(root).filter((n) => fs.existsSync(path.join(root, n, "research.json")));
+  const pick = name && name !== "latest" ? names.find((n) => n === name) : names.map((n) => ({ n, t: fs.statSync(path.join(root, n, "research.json")).mtimeMs })).sort((a, b) => b.t - a.t)[0]?.n;
+  return pick ? { ...readJson(path.join(root, pick, "research.json"), {}), dir: path.join(root, pick) } : null;
+}
+
+function targetsFor(u, { urls = [], inspire = [], index = true } = {}) {
+  const out = [];
+  const seen = new Set();
+  const push = (url, extra) => {
+    const pub = publicUrl(url, { allowLocal: true });
+    if (!pub.ok) return out.push({ url, status: "skipped", why: pub.why, ...extra });
+    const key = pub.url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "");
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ url: pub.url, host: pub.host, ...extra });
+  };
+  const fromIndex = matchIndex(u, { competitors: 6, craft: 6 });
+  const indexed = new Map([...fromIndex.competitors, ...fromIndex.craft].map((s) => [s.url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, ""), s]));
+  const meta = (url) => indexed.get(url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "")) ?? loadIndex().sites.find((s) => s.url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "") === url.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "")) ?? null;
+  for (const url of urls) {
+    const s = meta(publicUrl(url, { allowLocal: true }).url ?? url);
+    push(url, { role: s && !s.industry?.includes(u.industry[0]) ? "craft" : "competitor", source: "found", name: s?.name, mood: s?.mood, industry: s?.industry });
+  }
+  for (const url of inspire) {
+    const s = meta(publicUrl(url, { allowLocal: true }).url ?? url);
+    push(url, { role: "craft", source: "given", name: s?.name, mood: s?.mood, industry: s?.industry });
+  }
+  if (index) {
+    const comps = out.filter((t) => t.role === "competitor").length;
+    for (const s of fromIndex.competitors.slice(0, Math.max(0, 4 - comps))) push(s.url, { role: "competitor", source: "palate list", name: s.name, mood: s.mood, industry: s.industry, note: s.note });
+    const crafts = out.filter((t) => t.role === "craft").length;
+    for (const s of fromIndex.craft.slice(0, Math.max(0, 3 - crafts))) push(s.url, { role: "craft", source: "palate list", name: s.name, mood: s.mood, industry: s.industry, note: s.note });
+  }
+  const live = out.filter((t) => t.status !== "skipped");
+  return { targets: live.slice(0, MAX_CAPTURES), over: live.slice(MAX_CAPTURES), invalid: out.filter((t) => t.status === "skipped") };
+}
+
+const hostName = (r) => r.name ?? r.host?.replace(/^www\./, "") ?? r.url;
+
+// urls: null → step 1 only (the understanding and the searches to run). urls: [] → look at palate's own picks only.
+export async function research(dir, job, { route, urls = null, inspire = [], name, keep, allowLocal = false, fetchImpl, index = true, browser: given, log = true } = {}) {
+  const t0 = Date.now();
+  if (route) route = normalizeRoute(route);
+  const u = understand(dir, job, { route });
+  name ??= nameOf(u);
+  const session = path.join(researchRoot(dir), name);
+  fs.mkdirSync(session, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  const picks = matchIndex(u);
+  if (urls == null) {
+    const data = { name, stage: "understood", created: new Date().toISOString(), understanding: u, picks: { competitors: picks.competitors.map((s) => s.url), craft: picks.craft.map((s) => s.url) } };
+    fs.writeFileSync(path.join(session, "research.json"), JSON.stringify(data, null, 2));
+    return { data, session, text: understoodText(u, data, session, picks) };
+  }
+
+  const { targets, over, invalid } = targetsFor(u, { urls, inspire, index });
+  const rules = activeRules().filter((r) => appliesTo(r, kindTags({ screen: u.screen, kind: "marketing", route }), { route, project: projectOf(dir) }));
+  const profile = read(path.join(TASTE_DIR, "profile.md"));
+  const robotsCache = new Map();
+  const shots = path.join(session, "shots");
+  fs.mkdirSync(shots, { recursive: true });
+  const own = given ? null : await acquireBrowser();
+  const browser = given ?? own.browser;
+  let refs;
+  try {
+    refs = await politeRun(targets.map((t) => ({ host: t.host, run: () => lookAt(browser, t, shots, { dir, robotsCache, allowLocal, fetchImpl, rules }) })));
+    refs = refs.map((r, i) => (r?.error ? { ...targets[i], status: "skipped", why: r.error.slice(0, 120) } : r));
+    const history = tasteHistory(u.screen);
+    const { kept, dropped } = rankRefs(refs, u, { keep, rules, profile, history });
+    const cliches = clichesOf(refs);
+    kept.forEach((r, i) => {
+      r.id = `R${i + 1}`;
+      r.works = whatWorks(r);
+      r.learn = learnFrom(r, kept, cliches, u.product, new Set(kept.slice(0, i).map((k) => k.learn?.trait)));
+      r.moves = movesFor(r, u);
+    });
+    const contact = kept.length ? path.join(session, "contact.png") : null;
+    if (contact) await contactSheet(browser, [{ label: `Kept for ${u.product ?? u.job.slice(0, 40)} (${kept.length} of ${refs.filter((r) => r.status === "ok").length} looked at) · private moodboard, never shipped`, cells: kept.map((r) => ({ caption: `${r.id} ${hostName(r)} · ${r.role} · craft ${r.craft}`, file: r.files.fold })) }], contact, { cell: 360, maxCell: 240 });
+    const data = {
+      name,
+      stage: "done",
+      created: new Date().toISOString(),
+      ms: Date.now() - t0,
+      understanding: u,
+      looked: refs.length,
+      kept: kept.map(slim),
+      cliches,
+      dropped: [...dropped.map((d) => ({ url: d.ref.url, name: hostName(d.ref), why: d.why, layout: d.ref.layout })), ...refs.filter((r) => r.status !== "ok").map((r) => ({ url: r.url, name: hostName(r), why: r.why })), ...over.map((r) => ({ url: r.url, why: `over the ${MAX_CAPTURES}-page limit for one run` })), ...invalid.map((r) => ({ url: r.url, why: r.why }))],
+      fonts: uniq(refs.filter((r) => r.status === "ok").flatMap((r) => (r.measures?.fonts ?? []).filter((x) => !SYSTEM_FONT.test(x)).slice(0, 2).map(fontName))),
+      contact,
+      history: { verdicts: history.verdicts, chosen: history.chosen },
+    };
+    const md = researchMarkdown(data, session);
+    fs.writeFileSync(path.join(session, "research.md"), md);
+    fs.writeFileSync(path.join(session, "research.json"), JSON.stringify(data, null, 1));
+    rememberSites(data);
+    const cost = estimate({ mode: "research", briefs: [md] });
+    if (log) logCost(dir, name, "research", cost, { looked: refs.length, kept: kept.length, ms: data.ms });
+    return { data, session, text: doneText(data, session, cost) };
+  } finally {
+    if (own) await own.release();
+  }
+}
+
+const slim = (r) => ({ id: r.id, url: r.url, name: hostName(r), role: r.role, source: r.source, title: r.title, craft: r.craft, taste: r.taste, tasteNotes: r.tasteNotes, score: r.score, diversity: r.diversity, traits: r.traits, works: r.works, learn: r.learn, moves: r.moves, measures: r.measures ? { headline: r.measures.headline, fonts: r.measures.fonts, typeScale: r.measures.typeScale, bodySize: r.measures.bodySize, weights: r.measures.weights, radii: r.measures.radii, contentWidth: r.measures.contentWidth } : null, palette: r.layout?.style ? { bg: r.layout.style.bg, text: r.layout.style.text, accent: r.layout.style.accent } : null, principles: r.principles ? { facts: r.principles.facts, counts: r.principles.counts } : null, devices: r.devices, sections: r.sections, files: r.files, layout: r.layout, ms: r.ms, mood: r.mood, banner: r.banner });
+
+// Pages this user's research kept join their own list (links and palate's tags only), so the list grows.
+function rememberSites(data) {
+  try {
+    const local = readJson(LOCAL_INDEX, { sites: [] });
+    const has = new Set(local.sites.map((s) => s.url));
+    const shipped = new Set(loadIndex().sites.filter((s) => !s.local).map((s) => s.url.replace(/\/$/, "")));
+    for (const r of data.kept) {
+      const url = r.url.replace(/\/$/, "");
+      if (has.has(url) || shipped.has(url)) continue;
+      local.sites.push({ url, name: r.name, kind: [data.understanding.kind], mood: data.understanding.mood.slice(0, 3), industry: r.role === "competitor" ? data.understanding.industry.slice(0, 2) : [], note: `Kept by your research for ${data.understanding.product ?? data.understanding.job.slice(0, 40)} (craft ${r.craft}).`, added: new Date().toISOString().slice(0, 10) });
+    }
+    fs.mkdirSync(path.dirname(LOCAL_INDEX), { recursive: true });
+    fs.writeFileSync(LOCAL_INDEX, JSON.stringify(local, null, 1));
+  } catch {}
+}
+
+// ---- texts
+function understoodText(u, data, session, picks) {
+  return [
+    `# Research: ${u.product ?? u.job}`,
+    "",
+    understandingLines(u).join("\n"),
+    "",
+    "## Search (you, with your own web search tool: palate can't search)",
+    ...u.queries.map((q) => `- ${q}`),
+    u.software === false
+      ? `From the results take 4–8 **homepages of real ${u.category ?? "businesses"} sites** (each business's own site), the best-made ones you can find. Not listicles, directories, review sites, marketplaces or design galleries.`
+      : "From the results take 4–8 **official product homepages** (the vendor's own site) of competitors and category leaders. Not listicles, review sites, app stores or design galleries.",
+    "",
+    "## palate's own picks (kb/inspiration, added automatically)",
+    ...picks.competitors.map((s) => `- competitor: ${s.name} ${s.url}: ${s.note}`),
+    ...picks.craft.map((s) => `- craft: ${s.name} ${s.url} (${s.mood.join(", ")}): ${s.note}`),
+    "",
+    "## Next (no need to ask the user)",
+    `Call palate_research again with the same job and urls: [the homepages you found] (CLI: palate research "<job>" --urls a,b,c). palate looks at them and its own picks live (robots.txt respected, a few seconds apart per site, at most ${MAX_CAPTURES} pages), ranks them and writes the research. To skip the search: urls: [] (palate's own picks only).`,
+    `State: ${slash(path.join(session, "research.json"))}`,
+  ].join("\n");
+}
+
+export function understandingLines(u) {
+  return [
+    `- Product: ${u.product ?? "(not named)"}${u.description ? `, ${u.description}` : ""}`,
+    `- Audience: ${u.audience ?? "(not named)"} · industry: ${u.industry.join(", ") || "?"} · screen: ${u.screen}`,
+    `- Mood: ${u.mood.join(", ")}${u.moodGuessed ? " (a guess: the job names no mood; the blueprint decides it from the audience and the product)" : ""} · moves tags: ${u.tags.join(", ") || "-"}`,
+    `- Working metaphor (${u.metaphor.from}): ${u.metaphor.primary}${u.metaphor.alternates.length ? `. Also: ${u.metaphor.alternates.join("; ")}` : ""}`,
+    `- ${u.brand.mode === "brand" ? "Brand detected" : "No brand yet"}: ${u.brand.line}`,
+  ];
+}
+
+function researchMarkdown(d, session) {
+  const u = d.understanding;
+  const lines = [
+    `# Research: ${u.product ?? u.job}`,
+    "",
+    `> ${u.job}`,
+    "",
+    ...understandingLines(u),
+    `- Looked at ${d.looked} public page(s) live on ${d.created.slice(0, 10)} (${Math.round(d.ms / 1000)}s), kept ${d.kept.length}. robots.txt respected, one page at a time per site, nothing logged into or submitted. Screenshots are this project's private moodboard (gitignored); nothing was uploaded.`,
+    d.contact ? `- Contact sheet: ${slash(d.contact)}` : null,
+    "",
+    `## The kept references`,
+    "palate drafted the notes below from measurements. **Open the contact sheet and each first-screen screenshot and refine them in plain words**: what makes it work, and the one thing worth learning.",
+    "",
+  ];
+  for (const r of d.kept) {
+    lines.push(
+      `### ${r.id} ${r.name} (${r.url}) · ${r.role}${r.source === "palate list" ? ", from palate's list" : ""}`,
+      `craft ${r.craft}/10 · taste ${r.taste} · diversity ${r.diversity ?? 1}${r.tasteNotes?.length ? ` · ${r.tasteNotes.join("; ")}` : ""}`,
+      "",
+      "**What makes it work** (drafted from measurements)",
+      ...r.works.map((w) => `- ${w}`),
+      "",
+      `**Moves**: ${r.moves.length ? r.moves.map((m) => `${m.id} (${m.name})`).join(", ") : "none matched in the moves library"}`,
+      `**Traits**: ${(r.traits ?? []).map((t) => TRAITS[t]?.label ?? t).join("; ") || "-"}`,
+      `**${r.learn.line.replace(/:.*/, "")}**:${r.learn.line.replace(/^[^:]*:/, "")}`,
+      `Screenshots: ${slash(r.files.fold)}${r.files.full ? ` · ${slash(r.files.full)}` : ""}`,
+      "",
+    );
+  }
+  lines.push("## What the competitors all do (the cliché to avoid)", ...(d.cliches.length ? d.cliches.map((c) => `- ${c.label} (${c.of})`) : ["- Too few competitors looked at to call anything a cliché."]), "");
+  // A cliché is an execution; a truth is what makes the category itself. Avoiding a cliché must not throw away
+  // the truth under it (Kiln, Oct 27: avoiding terracotta-on-beige lost the warmth of clay altogether).
+  lines.push("## Category truths (keep, even when every competitor uses them)", "- (fill in from the screenshots: the materials, objects, rituals and words that make this category itself. For pottery: clay, glaze, the kiln, hands, the shelf of finished pieces. Avoid the cliché's execution, keep its truth.)", "");
+  if (d.fonts.length) lines.push("## Their fonts (measured; theirs, never load them)", `- ${d.fonts.join(", ")}`, "");
+  if (d.dropped.length) lines.push("## Left out", ...d.dropped.map((x) => `- ${x.name ?? x.url}: ${x.why}`), "");
+  lines.push("## The rule for everything built from this", `- ${LICENCE_RULE}`, "", "## Next", `palate_direction with the job and from_research "${d.name}" (CLI: palate direction "<job>" --from-research ${d.name}): 3 art directions, each with a metaphor and one signature moment.`);
+  return lines.filter((l) => l != null).join("\n");
+}
+
+function doneText(d, session, cost) {
+  const md = path.join(session, "research.md");
+  return [
+    `# Research done: ${d.understanding.product ?? d.understanding.job.slice(0, 60)}`,
+    "",
+    `Looked at ${d.looked} page(s) in ${Math.round(d.ms / 1000)}s; kept ${d.kept.length}: ${d.kept.map((r) => `${r.id} ${r.name} (${r.role}, craft ${r.craft})`).join(", ")}.`,
+    d.cliches.length ? `What the competitors all do: ${d.cliches.map((c) => c.label).join("; ")}.` : null,
+    d.understanding.brand.line,
+    d.dropped.length ? `Left out ${d.dropped.length}: ${d.dropped.slice(0, 5).map((x) => `${x.name ?? x.url} (${x.why})`).join("; ")}${d.dropped.length > 5 ? "…" : ""}.` : null,
+    "",
+    `Research: ${slash(md)}`,
+    d.contact ? `Contact sheet: ${slash(d.contact)}` : null,
+    costLine(cost),
+    "",
+    "Now, without asking the user: open the contact sheet and the first-screen screenshots with your image tool, refine each reference's notes in research.md in plain words (what makes it work; the one thing worth learning), then call palate_direction with the job and from_research. If the user reacts to a reference (\"love R2's type\", \"not R4\"), record it: palate_research with action \"verdict\" (it shapes the ranking next time).",
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+// The research, abstract only: for a direction or build brief. No screenshot paths in a build brief.
+export function researchNotes(d, { forBuild = false, only } = {}) {
+  if (!d?.kept?.length) return [];
+  const refs = only ? d.kept.filter((r) => only.includes(r.id)) : d.kept;
+  return [
+    // A builder gets no exact colours of theirs: hex values invite copying.
+    ...refs.map((r) => `- ${r.id} ${r.name} (${r.role}): ${(forBuild ? r.works.map((w) => w.replace(/\s*\(#[0-9a-f]{3,8}\)/gi, "")) : r.works).slice(0, forBuild ? 3 : 4).join(" ")} Moves: ${r.moves.map((m) => m.id).join(", ") || "-"}. ${r.learn.line}`),
+    d.cliches.length ? `- What the competitors all do (avoid): ${d.cliches.map((c) => c.label).join("; ")}.` : null,
+    d.fonts?.length ? `- Their fonts (theirs: never load them): ${d.fonts.join(", ")}.` : null,
+  ].filter(Boolean);
+}
+
+// ---- learning records (~/.palate/taste/research.jsonl)
+export function recordVerdicts(dir, name, verdicts = []) {
+  const d = loadResearch(dir, name);
+  if (!d?.kept) throw new Error(`No research "${name ?? "latest"}" in this project. Run palate research first.`);
+  const out = [];
+  for (const v of verdicts) {
+    const r = d.kept.find((x) => x.id === v.id || x.url === v.id || x.name?.toLowerCase() === String(v.id).toLowerCase());
+    if (!r || !["like", "dislike"].includes(v.verdict)) continue;
+    const rec = { kind: "ref-verdict", at: new Date().toISOString(), project: path.basename(path.resolve(dir)), research: d.name, screen: d.understanding.screen, verdict: v.verdict, url: r.url, name: r.name, ref: r.id, traits: r.traits ?? [], labels: (r.traits ?? []).map((t) => TRAITS[t]?.label ?? t), note: String(v.note ?? "").slice(0, 400) };
+    out.push(rec);
+  }
+  if (out.length) {
+    fs.mkdirSync(TASTE_DIR, { recursive: true });
+    fs.appendFileSync(RESEARCH_LOG, out.map((x) => JSON.stringify(x)).join("\n") + "\n");
+  }
+  return out;
+}
+
+// A build brief was written from a research direction: which references fed it (named in the provenance line).
+export function recordInfluence(dir, chosen, build) {
+  try {
+    const d = loadResearch(dir, chosen.research);
+    const prov = `${chosen.idea.provenance ?? ""}`;
+    const refs = (d?.kept ?? []).filter((r) => new RegExp(`\\b${r.id}\\b`).test(prov) || (r.name && prov.toLowerCase().includes(r.name.toLowerCase())));
+    fs.mkdirSync(TASTE_DIR, { recursive: true });
+    if (!fs.existsSync(path.join(dir, ".palate", "bench.json"))) fs.appendFileSync(RESEARCH_LOG, JSON.stringify({ kind: "influence", at: new Date().toISOString(), project: path.basename(path.resolve(dir)), research: chosen.research, screen: d?.understanding?.screen, build, route: chosen.route, direction: chosen.idea.name, signature: chosen.idea.signature ?? null, refs: refs.map((r) => ({ id: r.id, url: r.url, name: r.name, traits: r.traits })) }) + "\n");
+    return refs;
+  } catch {
+    return [];
+  }
+}
+
+// ---- originality against the references (novelty.mjs): every captured page this project's research looked at.
+export function referenceMatches(dir, rec) {
+  const root = researchRoot(dir);
+  if (!fs.existsSync(root) || !rec) return [];
+  const out = [];
+  for (const n of fs.readdirSync(root)) {
+    const d = readJson(path.join(root, n, "research.json"), null);
+    for (const r of [...(d?.kept ?? []), ...(d?.dropped ?? [])].filter((x) => x.layout)) out.push({ research: n, name: r.name, url: r.url, ...compare(rec, r.layout) });
+  }
+  return out.sort((a, b) => b.total - a.total);
+}
+export const REF_TOO_CLOSE = DUPLICATE;
+export const REF_CLOSE = SIMILAR;
+
+// ---- starter systems (projects with no brand): AA contrast, licence-safe fonts and imagery
+const PAID_FONTS = /\b(söhne|sohne|gt (america|walsheim|sectra|super|alpina|flexa|maru|eesti)|graphik|circular|aeonik|neue haas|helvetica( neue)?|sf pro|san francisco|founders grotesk|tiempos|canela|suisse|abc (diatype|favorit|whyte|monument)|diatype|favorit|untitled sans|untitled serif|lyon|domaine|calibre|national 2|signifier|feature (deck|display)|ogg|editorial new|neue montreal|pp (neue|editorial|mori)|basis grotesque|apercu|brown|gilroy|proxima nova|avenir|futura pt|gotham|freight|chronicle|mercury text|druk|styrene|tobias|copernicus|tiempos)\b/i;
+const IMAGERY_SAFE = /\b(code|svg|css|canvas|webgl|cc0|public domain|generated|generative|pattern|procedural|own photo|photographs? (we|you) (own|take)|commissioned|none|no imagery|type only|typographic)\b/i;
+const hexRgb = (h) => {
+  const m = String(h ?? "").trim().match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!m) return null;
+  const s = m[1].length === 3 ? m[1].split("").map((c) => c + c).join("") : m[1];
+  return [0, 2, 4].map((i) => parseInt(s.slice(i, i + 2), 16));
+};
+const relLum = (rgb) => {
+  const f = (v) => ((v /= 255) <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * f(rgb[0]) + 0.7152 * f(rgb[1]) + 0.0722 * f(rgb[2]);
+};
+export function contrast(a, b) {
+  const [x, y] = [hexRgb(a), hexRgb(b)];
+  if (!x || !y) return null;
+  const [l1, l2] = [relLum(x), relLum(y)].sort((p, q) => q - p);
+  return +((l1 + 0.05) / (l2 + 0.05)).toFixed(2);
+}
+
+export function validateStarter(s) {
+  const problems = [];
+  const warnings = [];
+  const checks = [];
+  if (!s || typeof s !== "object") return { ok: false, problems: ["no starter system: give colours, type, radius, spacing, motion and imagery"], warnings, checks };
+  const c = s.colours ?? s.colors ?? {};
+  for (const k of ["bg", "text", "muted", "accent"]) if (!hexRgb(c[k])) problems.push(`colours.${k} must be a hex colour`);
+  const pair = (fg, bg, min, what) => {
+    if (!c[fg] || !c[bg]) return;
+    const r = contrast(c[fg], c[bg]);
+    if (r == null) return;
+    checks.push({ pair: `${fg} on ${bg}`, ratio: r, min });
+    if (r < min) problems.push(`${what}: ${fg} ${c[fg]} on ${bg} ${c[bg]} is ${r}:1, needs ${min}:1 (AA)`);
+  };
+  pair("text", "bg", 4.5, "body text");
+  pair("muted", "bg", 4.5, "muted text");
+  pair("accent", "bg", 3, "accent (UI, large text)");
+  if (c["on-accent"] ?? c.onAccent) {
+    c["on-accent"] ??= c.onAccent;
+    pair("on-accent", "accent", 4.5, "text on the accent");
+  }
+  if (c.surface) pair("text", "surface", 4.5, "text on surfaces");
+  const t = s.type ?? {};
+  if (!t.display || !t.body) problems.push("type needs display and body families");
+  if (!/^(google-fonts|ofl|system)$/i.test(t.source ?? "")) problems.push('type.source must be "google-fonts", "ofl" or "system" (licence-safe only)');
+  for (const f of [t.display, t.body, t.mono].filter(Boolean)) if (PAID_FONTS.test(f)) problems.push(`${f} is a paid or platform-only font: choose a Google Fonts / OFL family or system fonts`);
+  if (!Array.isArray(t.scale) || t.scale.length < 4 || t.scale.some((x) => !Number.isFinite(Number(x)))) problems.push("type.scale needs at least 4 sizes in px");
+  if (!s.radius || (Array.isArray(s.radius) && !s.radius.length)) problems.push("radius scale missing");
+  if (!s.spacing) problems.push("spacing rhythm missing");
+  if (!s.motion) problems.push("motion character missing");
+  if (!s.imagery) problems.push("imagery approach missing");
+  else if (!IMAGERY_SAFE.test(s.imagery)) problems.push("imagery must be licence-safe: built in code (SVG, CSS, canvas), CC0 / public-domain art, or generated patterns");
+  if (/\b(unsplash|getty|shutterstock|stock photo|their (photos|illustrations))\b/i.test(s.imagery ?? "")) warnings.push("stock or third-party imagery named: make sure the licence allows it, or build it in code");
+  return { ok: !problems.length, problems, warnings, checks };
+}
+
+// The starter system as tokens to create first (build brief).
+export function starterTokens(s) {
+  const c = s.colours ?? s.colors ?? {};
+  const t = s.type ?? {};
+  const fam = (f, fallback) => `"${f}", ${fallback}`;
+  return [
+    "```css",
+    ":root {",
+    ...Object.entries(c).map(([k, v]) => `  --color-${k}: ${v};`),
+    `  --font-display: ${fam(t.display, "ui-serif, Georgia, serif")};`,
+    `  --font-body: ${fam(t.body, "ui-sans-serif, system-ui, sans-serif")};`,
+    t.mono ? `  --font-mono: ${fam(t.mono, "ui-monospace, monospace")};` : null,
+    ...(t.scale ?? []).map((px, i) => `  --text-${i + 1}: ${px}px;`),
+    ...(Array.isArray(s.radius) ? s.radius.map((r, i) => `  --radius-${["sm", "md", "lg", "xl"][i] ?? i}: ${String(r).replace(/^(\d+)$/, "$1px")};`) : [`  /* radius: ${s.radius} */`]),
+    typeof s.spacing === "object" ? `  --space-unit: ${s.spacing.unit ?? 8}px; /* scale: ${(s.spacing.scale ?? []).join(" ")} */` : `  /* spacing: ${s.spacing} */`,
+    "}",
+    "```",
+    `Fonts: ${[t.display, t.body, t.mono].filter(Boolean).join(", ")} (${t.source}${/google/i.test(t.source ?? "") ? ": load from Google Fonts or @fontsource" : ""}). Motion: ${s.motion}. Imagery: ${s.imagery}.`,
+  ].filter((l) => l != null);
+}
+
+// ---- the build brief's research block (build.mjs calls this when the chosen direction came from research)
+// tokens: false when a blueprint exists: its tokens are the only system, so the direction's starter tokens (which
+// the blueprint refined, and which no longer match it) aren't printed.
+export function researchBuildLines(dir, chosen, { tokens = true } = {}) {
+  const d = loadResearch(dir, chosen.research);
+  const idea = chosen.idea;
+  const sig = idea.signature ?? {};
+  const scratch = chosen.brand === "scratch";
+  return [
+    "## The art direction (from research)",
+    `**${idea.name}**: ${idea.metaphor}`,
+    `- Signature moment: **${sig.move}**: ${sig.moment}`,
+    scratch ? null : `- Brand: ${idea.brand ?? "keep the project's tokens, fonts and components"}`,
+    idea.sections?.length ? `- Sections, in order: ${idea.sections.join(" → ")}` : null,
+    `- Provenance: ${idea.provenance}`,
+    "",
+    ...(scratch && idea.starter && !tokens
+      ? ["### The system", "The blueprint's tokens (below) are the only source: the direction's starter system was refined into them. Use no colour, font or size from anywhere else.", ""]
+      : scratch && idea.starter
+      ? ["### Create these tokens first (the direction's starter system)", "This project has no brand yet: write these tokens before any component, then use only them.", ...starterTokens(idea.starter), ""]
+      : [`### The project's brand`, `${d?.understanding?.brand?.line ?? "Keep the project's tokens."} The metaphor and the signature live inside these tokens: no new font, no new brand colour.`, ""]),
+    "### The signature move's recipe",
+    moveBriefSafe([sig.move]),
+    "",
+    ...(d ? ["### What the research found (abstract notes only)", ...researchNotes(d, { forBuild: true }), ""] : []),
+    "### Ideas, not expression",
+    `- ${LICENCE_RULE}`,
+    "- palate shoot compares this page with every page the research looked at; a page too close to one of them fails.",
+    `- **Deliver the signature moment; it will be checked.** palate shoot reminds you of it, and the review asks whether it is there and works.`,
+    "",
+  ].filter((l) => l != null);
+}