@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/stats.mjs

@@ -0,0 +1,78 @@
+// `palate stats`: how long recent loops took, stage by stage (from ~/.palate/history/loops.jsonl, written
+// when a pick finishes), loops in this project still under way, estimated tokens per mode (costs.jsonl, written
+// when a loop is set up), and what the triage decided lately.
+// Targets: a full page loop under 8 minutes, a section under 3.
+import fs from "node:fs";
+import path from "node:path";
+import { COSTS_LOG, k } from "./cost.mjs";
+import { PLANS_LOG } from "./plan.mjs";
+import { durations, LOOPS_LOG, loopTimeline, minutes } from "./timeline.mjs";
+
+const lines = (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 median = (v) => {
+  const s = v.filter((x) => x != null).sort((a, b) => a - b);
+  return s.length ? s[Math.floor((s.length - 1) / 2)] : null;
+};
+const isSection = (L) => Boolean(L.section);
+
+export function stats(dir, { limit = 10 } = {}) {
+  const done = lines(LOOPS_LOG).slice(-limit).reverse();
+  const out = ["# Recent loops", ""];
+  if (!done.length) out.push("No finished loops logged yet (a loop is logged when its pick finishes).");
+  else {
+    out.push("| when | project / loop | mode | variants | total | setup | build | judge | your pick |", "|---|---|---|---|---|---|---|---|---|");
+    for (const L of done) {
+      const d = L.durations ?? {};
+      out.push(`| ${L.at.slice(5, 16).replace("T", " ")} | ${L.project} / ${L.name} | ${L.mode}${L.stage === "sketch" ? ", sketch" : ""} | ${L.variants ?? L.planned ?? "?"} | ${minutes(d.total)} min | ${minutes(d.setup)} | ${minutes(d.build)} | ${minutes(d.judge)} | ${minutes(d.pick)} |`);
+    }
+    const pages = done.filter((L) => !isSection(L));
+    const sections = done.filter(isSection);
+    const sum = (list, label, target) => {
+      if (!list.length) return null;
+      const m = median(list.map((L) => L.durations?.total));
+      return `- ${label}: median ${minutes(m)} min over ${list.length} loop${list.length > 1 ? "s" : ""} (target under ${target} min${m != null && m > target * 60000 ? "; over" : ""}); build ${minutes(median(list.map((L) => L.durations?.build)))}, judge ${minutes(median(list.map((L) => L.durations?.judge)))}, pick ${minutes(median(list.map((L) => L.durations?.pick)))}`;
+    };
+    out.push("", ...[sum(pages, "Pages", 8), sum(sections, "Sections", 3)].filter(Boolean));
+  }
+  // Loops in this project that haven't been picked yet.
+  const base = path.join(dir, ".palate", "variants");
+  // (Build mode has no pick: its loops never count as under way.)
+  const isBuild = (n) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(base, n, "loop.json"), "utf8")).mode === "build";
+    } catch {
+      return false;
+    }
+  };
+  const open = fs.existsSync(base)
+    ? fs.readdirSync(base).filter((n) => fs.existsSync(path.join(base, n, "events.jsonl")) && !loopTimeline(dir, n)?.pick_done && !isBuild(n)).map((n) => ({ n, t: loopTimeline(dir, n) }))
+    : [];
+  if (open.length) {
+    out.push("", "## Under way in this project");
+    for (const { n, t } of open) {
+      const d = durations(t);
+      const since = t.variants_setup ? Date.now() - Date.parse(t.variants_setup) : null;
+      out.push(`- ${n}: set up ${minutes(since)} min ago; ${Object.keys(t.first_render ?? {}).length} rendered, ${Object.keys(t.ready ?? {}).length} ready${d.firstRender != null ? `; first render after ${minutes(d.firstRender)} min` : ""}${t.judge_rendered ? "; judged" : ""}${t.pick_opened ? "; picker open" : ""}`);
+    }
+  }
+  // Tokens per mode: each setup's brief size and estimated cost (cost.mjs), so the trade is visible.
+  const costs = lines(COSTS_LOG);
+  if (costs.length) {
+    const ORDER = ["research", "direction", "build", "quick", "full"];
+    const by = {};
+    for (const c of costs) (by[c.mode] ??= []).push(c);
+    out.push("", `## Tokens per mode (estimated, ${costs.length} loop${costs.length > 1 ? "s" : ""})`, "", "| mode | loops | median brief | median tokens per loop | total |", "|---|---|---|---|---|");
+    for (const m of Object.keys(by).sort((a, b) => ORDER.indexOf(a) - ORDER.indexOf(b))) {
+      const list = by[m];
+      out.push(`| ${m} | ${list.length} | ${(median(list.map((c) => c.briefBytes)) / 1024).toFixed(1)} KB | ~${k(median(list.map((c) => c.estTokens)))} | ~${k(list.reduce((n, c) => n + (c.estTokens ?? 0), 0))} |`);
+    }
+    out.push("", "Estimates: the briefs as written (4 characters a token) plus typical work per builder, judge render, build-out and finishing pass.");
+  }
+  const plans = lines(PLANS_LOG).slice(-limit).reverse();
+  if (plans.length) {
+    const by = plans.reduce((m, p) => ((m[p.mode] = (m[p.mode] ?? 0) + 1), m), {});
+    out.push("", `## Triage (last ${plans.length}: ${Object.entries(by).map(([k, v]) => `${v} ${k}`).join(", ")})`);
+    for (const p of plans.slice(0, 6)) out.push(`- ${p.mode}${p.variants ? ` (${p.variants})` : ""}${p.cost?.tokens && p.mode !== "direct" ? `, ~${k(p.cost.tokens)} tokens` : ""}:"${p.request.slice(0, 70)}${p.request.length > 70 ? "…" : ""}" (${p.reason})`);
+  }
+  return out.join("\n");
+}

package/src/loop/taste.mjs

@@ -0,0 +1,81 @@
+// `palate taste`: the user's own taste profile, which grows with every pick. It lives on their machine
+// (~/.palate/taste), never in a shared model: shared training data is why AI UI looks the same everywhere.
+//   palate taste                    show the profile
+//   palate taste init --from <file> start it from an existing write-up (e.g. a designer's notes)
+//   palate taste learn              evidence from picks since the last update, for the agent to fold in
+import fs from "node:fs";
+import path from "node:path";
+import { TASTE_DIR, readJson } from "./common.mjs";
+import { learnedLines, learnedText, learnRules, RULES_FILE } from "./rules.mjs";
+
+const PROFILE = path.join(TASTE_DIR, "profile.md");
+const STATE = path.join(TASTE_DIR, "state.json");
+
+export function taste(sub, { from, dir } = {}) {
+  fs.mkdirSync(TASTE_DIR, { recursive: true });
+  if (sub === "init") {
+    if (!from) throw new Error("Usage: palate taste init --from <file>[,<file>]");
+    const text = from.split(",").map((f) => fs.readFileSync(f.trim(), "utf8").replace(/^---[\s\S]*?---\n/, "").trim()).join("\n\n");
+    fs.writeFileSync(PROFILE, `# Taste profile\n\n${text}\n`);
+    return `Taste profile started at ${PROFILE}`;
+  }
+  if (sub === "learn") {
+    const read = (f) => (fs.existsSync(path.join(TASTE_DIR, f)) ? fs.readFileSync(path.join(TASTE_DIR, f), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)) : []);
+    const since = readJson(STATE, {}).learnedAt ?? "";
+    const fresh = read("picks.jsonl").filter((p) => p.at > since);
+    // Critique verdicts (palate critique): disagreements say what the user does not consider a problem.
+    const verdicts = read("critiques.jsonl").filter((c) => c.at > since && c.verdict);
+    // palate point: what the user pointed at and asked to change in their running app (one entry per request).
+    const points = [...new Map(read("point.jsonl").filter((x) => x.at > since).map((x) => [x.id, x])).values()].filter((x) => x.kind !== "point-cancel");
+    // Rules first: agreed findings, failures and repeated asks become proposed rules (de-duplicated) before any
+    // prose; nothing applies until the user keeps it.
+    const rules = [`# Rules (${RULES_FILE.replace(/\\/g, "/")})`, ...learnedLines(learnRules()), ""];
+    if (!fresh.length && !verdicts.length && !points.length) return [...rules, "No new picks, critique verdicts or point requests since the last update."].join("\n");
+    const byLoop = {};
+    for (const p of fresh) (byLoop[`${p.project}/${p.loop}`] ??= { kind: p.kind, job: p.job, wins: {}, reasons: {} });
+    for (const p of fresh) {
+      const L = byLoop[`${p.project}/${p.loop}`];
+      if (!p.winner) continue;
+      L.wins[p.winner] = (L.wins[p.winner] ?? 0) + 1;
+      for (const r of p.reasons) (L.reasons[p.winner] ??= {})[r] = ((L.reasons[p.winner] ?? {})[r] ?? 0) + 1;
+    }
+    const byPage = {};
+    for (const c of verdicts) (byPage[`${c.project}${c.route} (${c.kind ?? "page"})`] ??= []).push(c);
+    fs.writeFileSync(STATE, JSON.stringify({ ...readJson(STATE, {}), learnedAt: new Date().toISOString() }));
+    return [
+      ...rules,
+      `# New evidence for ${PROFILE}`,
+      "",
+      ...Object.entries(byLoop).map(([k, L]) => [`## ${k} (${L.kind}): ${L.job ?? ""}`, ...Object.entries(L.wins).sort((a, b) => b[1] - a[1]).map(([r, n]) => `- ${r}: ${n} wins${L.reasons[r] ? ` · why: ${Object.entries(L.reasons[r]).map(([x, c]) => `${x} ×${c}`).join(", ")}` : ""}`)].join("\n")),
+      ...Object.entries(byPage).map(([k, list]) =>
+        [
+          `## Critique of ${k}`,
+          ...list.filter((c) => c.verdict === "disagree").map((c) => `- The user does NOT consider this a problem: ${c.what}${c.note ? ` (their note: "${c.note}")` : ""}`),
+          ...list.filter((c) => c.verdict === "agree").map((c) => `- Agreed [${c.severity}]: ${c.what}${c.note ? ` (their note: "${c.note}")` : ""}`),
+        ].join("\n"),
+      ),
+      ...pointLines(points),
+      "",
+      "Look at the winners and losers (screenshots are in each project's .palate/variants/<loop>/shots), then update the profile: in the section for this kind of screen, write what won and why in 3–6 concrete bullets, and adjust the general rules only if the evidence contradicts them. Name the project in the section's heading and keep how the user judged apart from that product's look (its colour, type, hero): briefs for other projects keep the judgement and leave that look out.",
+      verdicts.length ? "From critiques: write each disagreement as a preference (\"dense variant grids are fine: they show range\"), so future critiques and designs stop raising it. Agreed findings are proposed rules (above), waiting for the user's OK." : "",
+      points.length ? "From point requests: what the user keeps asking to fix is what palate should get right the first time. palate proposed rules (above) for the repeated asks it recognised. For another repeated ask (the same complaint on the same kind of element), ask the user whether it should be a rule and where (that component, that page, that kind of screen, or everywhere), and add it only if they say so: palate rule add \"…\" --only <Component> | --route /x | --kind team. A single ask is a one-off fix, not a rule." : "",
+      "Keep it short; it is read before every design.",
+    ]
+      .filter((l) => l !== "")
+      .join("\n");
+  }
+  return `${learnedText(dir)}\n${fs.existsSync(PROFILE) ? fs.readFileSync(PROFILE, "utf8") : `No taste profile yet. It starts with the first \`palate pick\`, or seed it: palate taste init --from <file>`}`;
+}
+
+// Point requests for taste learn: chips tallied, then the asks in the user's words with what was done.
+function pointLines(points) {
+  if (!points.length) return [];
+  const chips = {};
+  for (const p of points) for (const c of p.chips ?? []) chips[c] = (chips[c] ?? 0) + 1;
+  const tally = Object.entries(chips).sort((a, b) => b[1] - a[1]).map(([c, n]) => `${c} ×${n}`).join(", ");
+  return [
+    `## Asked to fix in place (palate point, ${points.length})`,
+    tally ? `- Chips: ${tally}` : "",
+    ...points.slice(-12).map((p) => `- ${p.project}${p.route} ${p.component ? `<${p.component}> ` : ""}${p.tag ?? ""}: ${p.prompt ? `"${p.prompt}"` : (p.chips ?? []).join(", ")}${p.summary ? ` → ${p.summary}` : p.kind === "point-request" ? " (not done yet)" : ""}${p.before && p.after ? ` (before ${p.before}, after ${p.after})` : ""}`),
+  ].filter(Boolean);
+}

package/src/loop/timeline.mjs

@@ -0,0 +1,149 @@
+// How long a loop took, stage by stage. Each stage appends one line to the loop's events.jsonl (safe when
+// parallel builders write at once), and loop.json's "timeline" is rebuilt from that log on every write, so
+// a lost write heals on the next. `palate pick` prints the total; `palate stats` summarises recent loops.
+//   variants_start, variants_setup   palate variants began / wrote its briefs
+//   first_render {route}             a variant first rendered (its builder's first shoot, or a render)
+//   shot {route}                     its builder first ran palate shoot on it
+//   ready {route}                    a variant was seen built and settled (pick --ready, judge --watch)
+//   build_done                       the variants judged or picked from were ready
+//   judge_rendered, judge_scored     palate judge rendered / kept the best
+//   pick_opened, pick_done           the picker opened / the user chose
+//   build_brief                      palate build wrote the build-out brief for the winner (or build mode's brief)
+//   blueprint_brief, blueprint_saved the planner brief written / the blueprint passed (build mode, new pages)
+//   gate_round, gate_verdict         palate gate prepared a round / read its judges' answers (the latest of each)
+import fs from "node:fs";
+import path from "node:path";
+import { PALATE_HOME } from "../catalog/store.mjs";
+
+const PER_ROUTE = new Set(["first_render", "shot", "ready"]);
+const FIRST = new Set(["variants_start", "variants_setup", "gate_first", "blueprint_brief"]);
+export const LOOPS_LOG = path.join(PALATE_HOME, "history", "loops.jsonl");
+
+const sessionOf = (dir, name) => path.join(dir, ".palate", "variants", name);
+const readJson = (f, fb) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return fb;
+  }
+};
+
+// The timeline from the events: per-route stages keep their first time, setup stages their first, the rest their latest.
+export function timelineOf(list) {
+  const t = { first_render: {}, shot: {}, ready: {} };
+  for (const e of list) {
+    if (PER_ROUTE.has(e.stage)) {
+      if (e.route && !t[e.stage][e.route]) t[e.stage][e.route] = e.at;
+    } else if (FIRST.has(e.stage)) t[e.stage] ??= e.at;
+    else t[e.stage] = e.at;
+  }
+  return t;
+}
+
+// Records a stage for a loop (no-op when the loop doesn't exist). Returns the timeline.
+export function mark(dir, name, stage, extra = {}) {
+  try {
+    const session = sessionOf(dir, name);
+    const loopFile = path.join(session, "loop.json");
+    if (!fs.existsSync(loopFile)) return null;
+    const ev = path.join(session, "events.jsonl");
+    if (PER_ROUTE.has(stage) && extra.route && fs.existsSync(ev) && fs.readFileSync(ev, "utf8").includes(`"stage":"${stage}","route":"${extra.route}"`)) return null;
+    fs.appendFileSync(ev, JSON.stringify({ stage, ...extra, at: extra.at ?? new Date().toISOString() }) + "\n");
+    const t = timelineOf(readEvents(ev));
+    const meta = readJson(loopFile, {});
+    meta.timeline = t;
+    fs.writeFileSync(loopFile, JSON.stringify(meta, null, 2));
+    return t;
+  } catch {
+    return null;
+  }
+}
+
+function readEvents(file) {
+  return fs
+    .readFileSync(file, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function loopTimeline(dir, name) {
+  const ev = path.join(sessionOf(dir, name), "events.jsonl");
+  return fs.existsSync(ev) ? timelineOf(readEvents(ev)) : readJson(path.join(sessionOf(dir, name), "loop.json"), {}).timeline ?? null;
+}
+
+// The loop a variant route belongs to (/pricing-a1 → pricing), if that loop exists in this project.
+export function loopOfRoute(dir, route) {
+  const m = String(route).match(/^\/?(.+)-[a-z]\d+$/);
+  return m && fs.existsSync(path.join(sessionOf(dir, m[1]), "loop.json")) ? m[1] : null;
+}
+
+const ms = (a, b) => (a && b ? Math.max(0, Date.parse(b) - Date.parse(a)) : null);
+
+// Minutes per stage: setup (variants), build (until the variants used were ready), judge (until the
+// picker opened, rendering included), the user's pick, and the total.
+export function durations(t) {
+  if (!t) return null;
+  const firstRender = Object.values(t.first_render ?? {}).sort()[0];
+  return {
+    setup: ms(t.variants_start, t.variants_setup),
+    build: ms(t.variants_setup, t.build_done),
+    firstRender: ms(t.variants_setup, firstRender),
+    judge: ms(t.build_done, t.pick_opened),
+    pick: ms(t.pick_opened, t.pick_done),
+    total: ms(t.variants_start, t.pick_done ?? t.pick_opened ?? t.build_done),
+  };
+}
+
+export const minutes = (v) => (v == null ? "?" : (v / 60000).toFixed(v < 600000 ? 1 : 0));
+
+export function tookLine(t) {
+  const d = durations(t);
+  if (!d?.total) return "";
+  return `This loop took ${minutes(d.total)} min (setup ${minutes(d.setup)}, build ${minutes(d.build)}, judge ${minutes(d.judge)}, your pick ${minutes(d.pick)}).`;
+}
+
+// At the end of a loop: one line per loop in ~/.palate/history/loops.jsonl, for palate stats.
+export function logLoop(dir, name, meta, extra = {}) {
+  try {
+    const t = loopTimeline(dir, name);
+    fs.mkdirSync(path.dirname(LOOPS_LOG), { recursive: true });
+    fs.appendFileSync(LOOPS_LOG, JSON.stringify({ at: new Date().toISOString(), project: path.basename(path.resolve(dir)), name, kind: meta.kind, screen: meta.screen, mode: meta.mode ?? (meta.quick ? "quick" : "full"), stage: meta.stage ?? "full", planned: meta.planned ?? null, section: Boolean(meta.vary) || /\bsection\b/i.test(meta.job ?? ""), durations: durations(t), ...extra }) + "\n");
+  } catch {}
+}
+
+// Build mode, from the blueprint to the last gate verdict: plan, build (until the first gate round), gate (rounds,
+// repairs and judges), and the total. Times between steps include the agent's own work.
+export function buildDurations(t) {
+  if (!t) return null;
+  const start = t.blueprint_brief ?? t.build_brief;
+  return {
+    plan: ms(t.blueprint_brief, t.blueprint_saved),
+    build: ms(t.build_brief, t.gate_first ?? t.gate_round),
+    gate: ms(t.gate_first ?? t.gate_round, t.gate_verdict),
+    total: ms(start, t.gate_verdict),
+  };
+}
+export function buildTookLine(t) {
+  const d = buildDurations(t);
+  if (!d?.total) return "";
+  return `This build took ${minutes(d.total)} min (plan ${minutes(d.plan)}, build ${minutes(d.build)}, gate and repairs ${minutes(d.gate)}).`;
+}
+
+// Active minutes of a loop: the gaps between its recorded steps, each capped at 20 minutes, so an overnight stall
+// or a lunch break doesn't count as build time (a benchmark run once reported 1,124 minutes).
+export function activeMinutes(dir, name, { cap = 20 * 60_000 } = {}) {
+  const ev = path.join(sessionOf(dir, name), "events.jsonl");
+  if (!fs.existsSync(ev)) return null;
+  const times = readEvents(ev).map((e) => Date.parse(e.at)).filter(Number.isFinite).sort((a, b) => a - b);
+  let total = 0;
+  for (let i = 1; i < times.length; i++) total += Math.min(cap, times[i] - times[i - 1]);
+  return times.length > 1 ? total : null;
+}

package/src/loop/variants.mjs

@@ -0,0 +1,228 @@
+// `palate variants "<job>" --name <loop>`: sets up one design loop. Chooses directions (what has won for
+// this user before, plus one to explore), gives each its own structure and its own references, and writes one
+// brief per direction that carries the job, the user's taste for this kind of screen, the references and what
+// has already been made for it (so it isn't made again). The coding agent then builds the variants (in
+// parallel where it can), and `palate judge` / `palate pick` choose among them.
+// Variants are opt-in: only when the user asks to explore, or for a new kind of screen with no taste history
+// (the triage's quick and full modes); otherwise build mode (`palate build "<job>"`) is the default. Each loop
+// logs its brief size and estimated token cost (loop.json, `palate stats`).
+// How many variants comes from `palate plan` (the triage) unless --count/--per say otherwise. By default the
+// variants are sketches: the first screen and the page's centrepiece, finished; the rest stubbed. Only the
+// winner is built out (`palate build`). --full builds whole pages, as before.
+import fs from "node:fs";
+import path from "node:path";
+import { contextSummary } from "../context.mjs";
+import { screenKind, sessionDir } from "./common.mjs";
+import { kindWords, tasteFor } from "./craft.mjs";
+import { archetypesFor, chooseDirections, nextArchetype, referencePool, splitReferences } from "./explore.mjs";
+import { ARCH_NAME, alreadyMade, screenOf, seenDirections } from "./layouts.mjs";
+import { costLine, estimate, logCost } from "./cost.mjs";
+import { addRefs, refLines, refSheet, rememberedRefs } from "./myrefs.mjs";
+import { plan, planText } from "./plan.mjs";
+import { kindTags, projectOf, rulesBlock } from "./rules.mjs";
+import { mark } from "./timeline.mjs";
+
+const LETTERS = "abcdefgh";
+const slash = (p) => String(p).replace(/\\/g, "/");
+const MADE_LINES = 4;
+
+// One short line per layout already made: its first screen, how it shows the product, its palette.
+const shortly = (r) => (r.moves ? `${r.moves.hero}; product: ${r.moves.product}; ${r.moves.palette.split(",")[0]}` : `${ARCH_NAME[r.shape ?? r.archetype] ?? "layout"}: ${r.skeleton.slice(0, 6).join(" · ")}`);
+
+// The "Already made" section: recent layouts of this kind of screen, here and in the user's other projects.
+function alreadyMadeSection(made) {
+  if (!made.length) return [];
+  return [
+    "## Already made: don't repeat",
+    "Don't share a first-screen structure or more than one signature move with these (the judge drops near-duplicates):",
+    ...made.slice(0, MADE_LINES).map((r) => `- ${r.project} ${r.route}${r.picked ? " (picked)" : r.pickedAs ? ` (shipped from ${r.pickedAs}, picked)` : r.source === "screen" ? " (shipped)" : ""}: ${shortly(r)}`),
+    "",
+  ];
+}
+
+// The structure section: the archetype assigned to this direction, and a different form for each route.
+function structureSection(d, routes, kind) {
+  if (!d.archetype) return [routes.length > 1 ? "Structure: the reference's own layout. One route follows its first screen closely, the other keeps its spirit with a different arrangement of the same parts." : "Structure: the reference's own layout, translated into this product."];
+  const a = archetypesFor(kind).find((x) => x.id === d.archetype);
+  return [
+    `Structure: **${a.name}**: ${a.brief}${d.archetypeWon ? " (It has won for this user before: keep it, change the signature moves.)" : ""}`,
+    ...(routes.length > 1 ? routes.map((r, i) => `- \`${r}\`: ${a.forms[i] ?? "a form of your own within this structure, unlike the other routes"}`) : [`Form: ${a.forms[0]}.`]),
+  ];
+}
+
+// What a sketch builds, by kind of screen.
+const CENTREPIECE = {
+  app: "the main object of the screen (the table, list, board or form) with real records",
+  hero: "the hero and the one thing that proves it right under it (the product working, a real result)",
+  marketing: "the section that carries the page's idea (the live product demo, the plans, the proof): the one a visitor will remember",
+};
+
+export async function variants(dir, job, { name, count, per, quick = false, refs = [], mode, full = false, route } = {}) {
+  if (!name) throw new Error('Usage: palate variants "<what to build, in the user\'s words>" --name <short-name>');
+  const started = new Date().toISOString();
+  // The triage decides how many, unless the caller said.
+  let decision = null;
+  if (count == null && per == null) {
+    decision = plan(dir, job, { name, route, mode: quick ? "quick" : mode });
+    // Variants are opt-in: a request the triage gives to direct, build or direction gets no loop.
+    if (["direct", "build", "direction"].includes(decision.mode)) return `${planText(decision, { name })}\n\nNo loop was set up: variants are for when the user asks to explore. To explore anyway: palate variants "<job>" --name ${name} --mode quick`;
+    ({ count, per } = decision);
+    quick = decision.mode === "quick";
+  }
+  count ??= 3;
+  per ??= quick ? 1 : 2;
+  // Quick mode: one variant per direction, no judge; for small screens and everyday changes.
+  if (quick) per = 1;
+  const stage = full ? "full" : "sketch";
+  const session = sessionDir(dir, name);
+  // A new run of this loop starts a new timeline, and an old run's judge or pick must not stand in for it.
+  for (const f of ["events.jsonl", "judge.json", "judge-key.json", "similarity.json", "result.json", "build.md"]) fs.rmSync(path.join(session, f), { force: true });
+  const { kind } = screenKind(name, job);
+  const screen = screenOf(name, job);
+  // The user's references come first: the ones given now, plus ones they gave earlier for similar jobs.
+  const given = refs.length ? await addRefs(refs, { job }) : [];
+  const userRefs = [...given, ...rememberedRefs(job, { exclude: given.map((r) => r.id) })];
+  const userSheet = userRefs.length ? await refSheet(userRefs, path.join(session, "user-refs.png")) : null;
+  // The library's references for this job: one pool, split so no two directions share one; its style clusters
+  // also become candidate directions.
+  const { searchLibrary, librarySheet } = await import("./library.mjs");
+  const pool = referencePool(searchLibrary, job, { kind, screen });
+  let dirs = chooseDirections(count, { kind, screen, pool, exclude: userRefs.map((r) => r.id) }).directions;
+  if (userRefs.length) {
+    // With a reference, one direction follows it closely, one blends it with what has won for this user, one explores.
+    const top = dirs[0];
+    const explore = dirs.length > 1 ? dirs[dirs.length - 1] : null;
+    dirs = [
+      { id: "follow-reference", name: "Follow your reference", brief: "Stay close to the user's reference: its layout structure, density, type character and mood, translated into this product's content and components. Take its spirit, never its text, logos, imagery or brand colours.", archetype: null },
+      { id: `blend-${top.id}`, name: `Reference + ${top.name}`, brief: `Take the reference's strongest idea and combine it with this direction: ${top.brief}`, style: top.style, archetype: top.archetype, archetypeWon: top.archetypeWon },
+      ...(explore ? [explore] : []),
+    ].slice(0, count);
+    while (dirs.length < count) dirs.push({ ...top, id: `${top.id}-${dirs.length}`, archetype: nextArchetype(kind, new Set(dirs.map((d) => d.archetype)), seenDirections(kind, screen).shapes)?.id });
+  }
+  const made = alreadyMade({ dir, name, kind, screen, limit: MADE_LINES });
+  // Only the profile's section for this kind of screen, plus the rules that hold everywhere.
+  const taste = tasteFor(kindWords(screen, kind, name), { sections: 1, lean: true, project: path.basename(path.resolve(dir)) });
+  let project = "";
+  try {
+    project = contextSummary(dir);
+  } catch {}
+
+  // The user's rules for this kind of screen, and what failed for it before: at the top of every brief.
+  const tags = kindTags({ screen, kind, route, words: `${name} ${job.slice(0, 160)}` });
+  const mine = rulesBlock(tags, { route, project: projectOf(dir) });
+  const directions = dirs.map((d, i) => ({ ...d, letter: LETTERS[i] }));
+  const split = splitReferences(pool, directions, (d) => d.style ?? "", 6);
+  const total = directions.length * per;
+  const briefs = [];
+  for (const [i, d] of directions.entries()) {
+    const sheet = split[i].length >= 3 ? await librarySheet(split[i], path.join(session, `refs-${d.letter}.png`)) : null;
+    const routes = Array.from({ length: per }, (_, k) => `${name}-${d.letter}${k + 1}`);
+    const shoot = routes.map((r) => `\`palate shoot /${r} --widths 1440${stage === "sketch" ? " --fold" : ""}\``).join(", ");
+    const brief = [
+      mine.line,
+      "",
+      `# Brief: ${job}`,
+      "",
+      ...mine.lines,
+      `Project: ${slash(dir)}. Every fact, record and number comes from the project (its README and data). No invented customers, logos, testimonials, stats or reviews.`,
+      "",
+      "## Whose taste",
+      taste ? `From the user's own blind picks (the section for this kind of screen, and the rules that hold everywhere):\n\n${taste.trim()}` : "No taste profile yet: clarity first, one crafted touch at most. This loop's pick starts the profile.",
+      "",
+      ...(userSheet
+        ? [
+            "## The user's own references (these come first)",
+            `Contact sheet: ${slash(userSheet)} (index with full-size paths and the user's notes: ${slash(userSheet.replace(/\.png$/, ".json"))}). Match their spirit (structure, density, type character, mood) more than any library reference. What the user likes about a reference is what to take from it; what they dislike must not appear.`,
+            ...refLines(userRefs),
+            "",
+          ]
+        : []),
+      "## References (inspiration, not templates)",
+      sheet
+        ? `Contact sheet: ${slash(sheet)} (full-size paths: ${slash(sheet.replace(/\.png$/, ".json"))}). Yours alone. Take parts from at least two; at the top of each file, a 3-line comment: which part from which reference number, and how you translate it. Never copy text, logos, imagery or brand colours.`
+        : "No library references; work from the taste and the project's own screens.",
+      "",
+      ...alreadyMadeSection(made),
+      "## What to build",
+      `Direction: **${d.name}**: ${d.brief}`,
+      ...structureSection(d, routes, kind),
+      `Routes: ${routes.map((r) => `\`/${r}\``).join(", ")}, in this project's routing convention (e.g. \`app/${routes[0]}/page.tsx\` in Next.js, \`src/routes/${routes[0]}.tsx\` in file routers).${per > 1 ? " Besides structure, they differ on at least one of: type, how information is shown, density, signature move." : ""}`,
+      stage === "sketch"
+        ? `**This is a sketch.** Build the first screen (what shows at 1440×900) and the centrepiece, ${CENTREPIECE[kind] ?? CENTREPIECE.marketing}, to a finished standard: real content, real state, crafted type and spacing. Everything else is a stub: one short block per remaining part with its heading and one line of real copy, marked \`{/* palate: stub */}\`. The user picks from first screens; only the winner is built out, so time spent below the centrepiece is wasted.`
+        : "Build the whole page, every section finished.",
+      "Don't drift toward a common default (centred headline, two buttons, three cards): the other briefs have other structures and references.",
+      "",
+      "Rules:",
+      "- Each variant file is self-contained: scope custom styles to it. Never edit shared styles or components, never install packages (other agents work here at the same time). Use the project's fonts.",
+      "- Interactions the job needs work, with real state. Accessible: semantic structure, AA contrast, visible focus, reduced motion respected; nothing hidden waiting for scroll.",
+      "- Raw stage: no polish pass (polish happens on the winner).",
+      "",
+      "## Check your work (once)",
+      `One shoot per route, at 1440 only: ${shoot}. Open the screenshot and fix the biggest problem once, and every rule its "Your rules" lines report failing. Its Originality line says if you repeat something already made: if so, change the structure. No 390, details, animate or principles passes now: they run on the winner after the pick. The typecheck must pass for your files. Do not commit.`,
+      "",
+      "Reply with one line per route: the idea, and the reference numbers used.",
+      project ? `\n## Project (palate context, short)\n${project}` : "",
+    ].join("\n");
+    const file = path.join(session, `brief-${d.letter}.md`);
+    fs.writeFileSync(file, brief);
+    briefs.push({ ...d, file, routes, text: brief });
+  }
+  const ready = decision?.ready ?? (quick ? total : Math.min(4, total));
+  const judgeStep = !quick && total > 4;
+  const loopMode = decision?.mode ?? (quick ? "quick" : "full");
+  const cost = estimate({ mode: loopMode, stage, briefs: briefs.map((b) => b.text), builders: total, judged: judgeStep ? total : 0 });
+  logCost(dir, name, loopMode, cost, { stage, variants: total });
+  fs.writeFileSync(
+    path.join(session, "loop.json"),
+    JSON.stringify(
+      {
+        name,
+        job,
+        title: job,
+        kind,
+        screen,
+        ...(route ? { route } : {}),
+        quick,
+        mode: loopMode,
+        stage,
+        planned: total,
+        cost,
+        ready,
+        triage: decision ? { reason: decision.reason, signals: decision.signals } : null,
+        userRefs: userRefs.map((r) => r.id),
+        tags,
+        rules: mine.rules.map((r) => r.id),
+        directions: directions.map(({ id, name: n, letter, archetype, brief, style, generated, explore }) => ({ id, name: n, letter, archetype, brief: generated ? brief : undefined, style: generated ? style : undefined, generated, explore })),
+        created: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
+  mark(dir, name, "variants_start", { at: started });
+  mark(dir, name, "variants_setup");
+
+  const why = (b) => (b.explore ? ` (explore${b.neverSeen ? `: ${b.neverSeen === "direction" ? "a direction" : "a direction × structure pair"} not yet seen for this kind of screen` : ""})` : "");
+  return [
+    decision ? `${planText(decision, { name }).split("\n")[0]}\n` : null,
+    userRefs.length ? `Using ${userRefs.length} of the user's own reference${userRefs.length > 1 ? "s" : ""} (${given.length} given now): ${userRefs.map((r) => r.source).join(", ")}\n` : null,
+    `${mine.line} Rules for ${tags.join(", ")}: ${mine.rules.map((r) => r.id).join(", ") || "none yet"}.`,
+    "",
+    `# Loop "${name}" is set up: ${briefs.length} directions × ${per} = ${total} ${stage === "sketch" ? "sketches (first screen + centrepiece)" : "full pages"}`,
+    "",
+    ...briefs.map((b) => `- ${b.letter}: ${b.name}${b.archetype ? `, ${ARCH_NAME[b.archetype]}` : ""}${why(b)}${b.generated ? ` [generated from ${b.generated === "library" ? "this job's references" : "your saved references"}]` : ""} → ${b.routes.join(", ")}\n  brief: ${slash(b.file)}`),
+    "",
+    costLine(cost),
+    "",
+    "Now build the variants:",
+    "- If you can run subagents (Claude Code: the Agent/Task tool), start one per brief in parallel, each told: \"Read <brief path> and follow it exactly; create only the route files it names.\"",
+    "- Otherwise build them yourself one brief at a time, following each brief exactly.",
+    "",
+    judgeStep
+      ? `Don't wait for the slowest: start \`palate judge --name ${name} --watch --ready ${ready}\` now (in the background); it renders as soon as ${ready} are built. A fresh judge scores, then \`palate pick --name ${name}\`.`
+      : `Don't wait for the slowest: start \`palate pick --name ${name} --ready ${ready}\` now (in the background); it opens the picker in the user's browser as soon as ${ready} are built.`,
+    stage === "sketch" ? `After the pick: \`palate build --name ${name}\` writes the brief that builds the winner out in full.` : null,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}