@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/animate.mjs

@@ -0,0 +1,70 @@
+// `palate animate <route>`: a motion pass that serves the content. Runs the motion check (frame strips,
+// invisible content, layout shift, reduced motion, no-JS), finds the motion skills installed here (Emil
+// Kowalski's emil-design-eng, Jakub Krehel's better-ui / better-motion), and writes a brief: where motion
+// would explain something, how to build it so content never hides, and how to verify it.
+// `palate animate <route> --check` runs only the check, to verify the pass.
+import fs from "node:fs";
+import path from "node:path";
+import { slugOf, stamp } from "../look.mjs";
+import { motionCheck } from "../motion.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { craftRubric, skillFiles, slash } from "./craft.mjs";
+
+const SKILLS = [
+  { id: "emil-design-eng", who: "Emil Kowalski", use: "what animates and why, duration and easing, enter/exit, press feedback, interruptibility, reduced motion" },
+  { id: "better-motion", who: "Jakub Krehel", use: "motion values and patterns" },
+  { id: "better-ui", who: "Jakub Krehel", use: "exact values for motion, icon states, shadows and radii" },
+  { id: "review-animations", who: "Emil Kowalski's bar", use: "a strict review of the motion code once it's written" },
+];
+const LIBS = [["motion", "Motion (motion/react)"], ["framer-motion", "Framer Motion"], ["gsap", "GSAP"], ["@react-spring/web", "React Spring"], ["@formkit/auto-animate", "auto-animate"], ["tailwindcss-animate", "tailwindcss-animate"], ["tw-animate-css", "tw-animate-css"]];
+
+export async function animate(dir, rawRoute, { url, checkOnly = false } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const session = path.join(dir, ".palate", "motion", slugOf(route), stamp());
+  const check = await motionCheck(dir, route, { url, out: session });
+  if (checkOnly) return `${check.report}\n\nOpen the strips and confirm: each motion explains something, content is readable in every frame after 400ms, nothing jumps.`;
+
+  let deps = {};
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {}
+  const libs = LIBS.filter(([p]) => p in deps).map(([, n]) => n);
+  const skills = skillFiles(dir, SKILLS.map((s) => s.id)).map((s, i) => ({ ...SKILLS[i], file: s.file }));
+  const rubric = craftRubric(/motion|anim|demo/i);
+  const still = check.data.sections.filter((s) => !s.moved);
+  const brief = [
+    `# Animate: ${route}`,
+    "",
+    "A motion pass that serves the content: motion that explains hierarchy, state and cause, never decoration. Keep the layout and the content; add or fix motion only.",
+    "",
+    check.report,
+    "",
+    "## Where motion should go",
+    check.data.static ? "The page is static: nothing moves on load or on scroll. Add motion in this order, and stop when the page feels alive (three or four well-placed motions beat motion everywhere):" : "Add or fix motion in this order:",
+    "1. **The product doing its job.** If a section shows the product as a static picture, make one of them live: rebuild the key moment in real UI and animate the state change (e.g. variants appear, one is chosen, the result lands). This is the most persuasive motion on a page.",
+    "2. **The first screen.** One short entrance that sets the reading order (headline, then sub-copy, then the action), 300–500ms in total, 8–12px of travel, staggered 40–60ms. Content is visible in the HTML before any script runs.",
+    `3. **Sections as they arrive.** Scroll-linked reveals for sections whose content has an order to it${still.length ? ` (still now: ${still.map((s) => `${s.index} ${s.name.slice(0, 30)}`).join(", ")})` : ""}. Reveal once, small travel, never a whole section fading from nothing.`,
+    "4. **State transitions.** Toggles, tabs, form submit, copy-to-clipboard, expanding rows: animate between states so the change is understood (cross-fade, height with FLIP or Motion layout, icon swaps with a short blur).",
+    "5. **Hover and press feedback.** Buttons press to `scale(0.97)` over 100ms; links and cards shift colour or lift 1–2px over 150ms, hover inside `@media (hover: hover)`.",
+    "",
+    "## How to build it so content never hides",
+    "- Start from visible. Never render `opacity: 0` (or `initial={{ opacity: 0 }}` in Motion) into server HTML for content: with JS slow, failed or off, it stays hidden. Either animate with CSS (`@keyframes` with `animation-fill-mode: both`, which runs without JS), or hide only under a class a script sets (`html.motion-ok .reveal { … }`) and inside `@media (prefers-reduced-motion: no-preference)`.",
+    "- Scroll reveals: CSS scroll-driven animations (`animation-timeline: view()`) inside `@supports` and the no-preference media query, or an IntersectionObserver that adds a class (threshold ~0.15, once). Content must be fully visible within 400ms of entering the viewport, and visible at the end of the page without scrolling back.",
+    "- Animate only `transform` and `opacity` (and `filter: blur()` sparingly). No `transition: all`. No layout properties without FLIP.",
+    "- Durations: 100–200ms for feedback, 200–300ms for state changes, at most 500ms for entrances. Ease-out for things arriving (e.g. `cubic-bezier(0.23, 1, 0.32, 1)`), ease-in-out for things moving on screen, never linear except spinners.",
+    "- `prefers-reduced-motion: reduce`: no travel, no scale, no parallax; keep instant changes or short opacity cross-fades.",
+    "- No layout shift: reserve space for anything that animates in (fixed heights, aspect-ratio, absolutely positioned overlays).",
+    libs.length ? `- This project already has ${libs.join(", ")}: use it, don't add another library.` : "- No motion library installed: use CSS (transitions, @keyframes, scroll-driven animations). Ask the user before installing one.",
+    "",
+    "## Skills to apply",
+    ...skills.map((s) => `- ${s.who}'s ${s.id}: ${s.use}. ${s.file ? `Read ${slash(s.file)} and apply it.` : "Not installed; apply the same principles from your own knowledge."}`),
+    rubric.text ? `\n## Motion checklist (kb/craft)\n${rubric.text}` : "",
+    "",
+    "## Verify",
+    `Run \`palate animate ${route} --check\` after the pass. Open both strips: the motion you added must show between frames, every frame from 400ms on must be readable, and the check must report no hidden content (normal, reduced motion and JavaScript off) and CLS under 0.05. Run the project's typecheck. Keep a motion only if it makes the page clearer.`,
+  ].join("\n");
+  fs.writeFileSync(path.join(session, "brief.md"), brief);
+  return `${brief}\n\n(Brief saved to ${slash(path.join(session, "brief.md"))})`;
+}
+

package/src/loop/artdirection.mjs

@@ -0,0 +1,264 @@
+// `palate direction "<job>" --from-research <name>`: ideation after research. The brief asks for 3 art directions,
+// each with a name, a metaphor, ONE signature moment (a signature move from the moves library, adapted to this
+// product), type and colour drawn from the metaphor (or, in a project with a brand, the brand kept and the metaphor
+// living inside it), a section plan, a provenance line ("rhythm from R2, texture idea from R4, nothing copied") and a
+// rough wireframe. A project with no brand gets a complete starter system per direction (AA-checked colours,
+// licence-safe type with its scale, radii, spacing, motion character, licence-safe imagery).
+// The agent drives: palate picks the direction itself when the user's taste for this kind of screen is strong and
+// one direction clearly leads, or when the user said "just build it"; the picker opens only for a real judgement
+// call (no or weak history, directions scoring close, or the user asked to choose), with the reason in one line.
+import fs from "node:fs";
+import path from "node:path";
+import { brandOf } from "../context.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { TASTE_DIR } from "./common.mjs";
+import { costLine, estimate, logCost } from "./cost.mjs";
+import { tasteFor } from "./craft.mjs";
+import { alreadyMade, projectId } from "./layouts.mjs";
+import { describePlanned, ideaLook, recentLooks, sharedAxes } from "./lookplan.mjs";
+import { plan } from "./plan.mjs";
+import { kindTags, projectOf, rulesFor } from "./rules.mjs";
+import { LICENCE_RULE, loadResearch, matchMovesSafe, moveExists, researchNotes, tasteHistory, understandingLines, validateStarter } from "./research.mjs";
+
+const slash = (p) => String(p).replace(/\\/g, "/");
+const uniq = (a) => [...new Set(a.filter(Boolean))];
+const words = (s) => (String(s ?? "").toLowerCase().match(/[a-z]{4,}/g) ?? []);
+const STOP = new Set(["with", "that", "this", "from", "they", "their", "them", "than", "into", "what", "when", "only", "each", "every", "over", "under", "also", "more", "less", "most", "page", "pages", "screen", "screens", "section", "sections", "wins", "loses", "winner", "lost", "variants", "variant", "loop", "plans", "all", "the", "where", "there", "which", "would", "could", "about", "other", "every", "everything", "first", "three", "above", "below", "product", "products", "shows", "these", "those", "while", "after", "before", "being", "still", "really", "whole", "people", "things"]);
+
+// The signature moves that fit this job (signature: true), the user's past choices first.
+export function signatureMoves(u, { history = tasteHistory(u.screen), limit = 6 } = {}) {
+  let rows = matchMovesSafe({ tags: u.tags, signature: true, limit: 12 });
+  if (rows.length < 3) rows = [...rows, ...matchMovesSafe({ signature: true, limit: 12 }).filter((m) => !rows.some((r) => r.id === m.id))];
+  const past = history.moves ?? {};
+  return rows
+    .map((m) => ({ ...m, chosenBefore: past[m.id] ?? 0 }))
+    .sort((a, b) => b.chosenBefore - a.chosenBefore || b.score - a.score)
+    .slice(0, limit);
+}
+
+// The 3 art directions brief. Writes <project>/.palate/direction/<name>/{brief.md,direction.json}.
+export function artDirectionBrief(dir, job, { route, name, fromResearch } = {}) {
+  const d = loadResearch(dir, fromResearch);
+  if (!d) throw new Error(`No research ${fromResearch && fromResearch !== "latest" ? `"${fromResearch}" ` : ""}in this project. Run palate research "<job>" first (MCP: palate_research).`);
+  if (d.stage !== "done") throw new Error(`Research "${d.name}" has only its first step: call palate_research again with the URLs from the searches (or urls: []).`);
+  const u = d.understanding;
+  // A route stored by older research may be a Git Bash path ("C:/Program Files/Git/"): refused here, never copied on.
+  route = route ? normalizeRoute(route) : u.route ? normalizeRoute(u.route) : undefined;
+  name ??= `${d.name}-directions`;
+  const session = path.join(dir, ".palate", "direction", name);
+  fs.mkdirSync(session, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  const brand = brandOf(dir, `${job} ${u.job}`);
+  const history = tasteHistory(u.screen);
+  const sigs = signatureMoves(u, { history });
+  const tags = kindTags({ screen: u.screen, kind: "marketing", route: route ?? u.route, words: job.slice(0, 160) });
+  const rules = rulesFor(tags, { route: route ?? u.route, project: projectOf(dir) });
+  // Only the rules that hold everywhere: type and colour come from the metaphor, not from past projects.
+  const general = tasteFor("", { sections: 0, lean: true });
+  const past = alreadyMade({ dir, kind: "marketing", screen: u.screen, limit: 4 }).filter((r) => r.moves);
+  const chosenBefore = sigs.filter((m) => m.chosenBefore > 0);
+  const ideasFile = path.join(session, "ideas.json");
+  const scratch = brand.mode === "scratch";
+  const recentLooksLines = recentLooks({ excludePid: projectId(dir), limit: 6 }).map((x) => `- ${x.project}: ${describePlanned(x.look)}`);
+  const brief = [
+    `# Art directions: ${job}`,
+    "",
+    `From research "${d.name}": ${d.kept.length} references kept of ${d.looked} looked at (${slash(path.join(d.dir, "research.md"))}${d.contact ? `; contact sheet ${slash(d.contact)}` : ""}).`,
+    ...understandingLines(u),
+    "",
+    "## Your answer: 3 art directions",
+    "Three different answers, not three skins of one: each has its own metaphor, its own signature moment and its own first screen. Order them from the safest to the boldest. They must span different visual worlds: no two share both the ground (white, light, dark, a colour, a photograph) and the headline's type genre (serif, sans, slab, mono, display, script), and at least one leads with imagery or type instead of a product frame where the category allows it. None may be palate's house look (a warm off-white page with grain, a serif headline, a split hero with a framed card, a pill button top right): palate refuses it at the blueprint.",
+    ...(recentLooksLines.length ? ["palate's recent pages, for reference (directions unlike these rank higher):", ...recentLooksLines] : []),
+    "Each has:",
+    "- **name** (2–4 words) and **metaphor**: one sentence, an image the whole page hangs on (the working metaphor above can be one of them).",
+    "- **signature**: `{ \"move\": \"<a move id from the list below>\", \"moment\": \"…\" }`. ONE signature moment, adapted to this product: what the visitor sees and does, where on the page, and why it says what the product does. It will be checked on the built page.",
+    scratch
+      ? "- **starter**: a complete starter system drawn from the metaphor (this project has no brand yet, see below): colours, type, radius, spacing, motion, imagery."
+      : "- **brand**: one sentence on how the direction lives inside the project's brand (which of its tokens carry the metaphor). No new font, no new brand colour.",
+    "- **sections**: the section plan, 5–8 short names in order.",
+    "- **provenance**: one line naming what each idea is learned from, by reference id, e.g. \"rhythm from R2, texture idea from R4, nothing copied\".",
+    "- **summary**: 2 sentences: what the visitor sees first and why it fits the product.",
+    "- **wireframe**: a rough ASCII sketch of the first screen and the signature moment (at most 16 lines × 64 columns).",
+    `- ${LICENCE_RULE}`,
+    "- Avoid what the competitors all do (below) unless a direction turns it into something they don't do.",
+    "",
+    "## Signature moves that fit (moves library, signature: true)",
+    ...sigs.map((m) => `- \`${m.id}\` ${m.name}: ${m.reason}${m.chosenBefore ? ` · the user chose it before (${m.chosenBefore}×)` : ""}`),
+    "Read a move in full with palate moves show <id> before you adapt it.",
+    "",
+    ...(chosenBefore.length || history.chosen
+      ? [
+          "## What this user keeps choosing for this kind of screen",
+          `${history.chosen} direction(s) chosen before${chosenBefore.length ? `; signature moves: ${chosenBefore.map((m) => `${m.id} (${m.chosenBefore}×)`).join(", ")}` : ""}. Lead with what they keep choosing in one direction, made new for this product: never a copy of a past project.`,
+          "",
+        ]
+      : []),
+    scratch
+      ? [
+          "## No brand yet: each direction defines a starter system",
+          brand.line,
+          "Each `starter` is complete and drawn from its metaphor, not from the user's past projects:",
+          '- `colours`: hex values for at least `bg`, `surface`, `text`, `muted`, `accent`, `on-accent`, `line`. palate checks AA: text and muted on bg ≥ 4.5:1, accent on bg ≥ 3:1, on-accent on accent ≥ 4.5:1.',
+          '- `type`: `{ "display": "…", "body": "…", "mono": "…", "source": "google-fonts" | "ofl" | "system", "scale": [12, 14, 16, 20, 28, 40, 64] }`: licence-safe families only (Google Fonts / OFL or system). No paid fonts, and none of the fonts measured on the references.',
+          '- `radius` (e.g. `[4, 8, 16]`), `spacing` (`{ "unit": 8, "scale": [4, 8, 12, 16, 24, 32, 48, 64, 96] }`), `motion` (its character: "calm: 280ms ease-out, one thing moves at a time"), `imagery` (licence-safe: built in code (SVG, CSS, canvas), CC0 / public-domain art, or generated patterns).',
+        ].join("\n")
+      : ["## The project's brand: work inside it", brand.line, `Tokens in ${brand.tokenFiles.join(", ") || "the project's CSS"}: ${brand.colours.slice(0, 12).map((c) => `${c.name} ${c.value}`).join(", ")}${brand.colours.length > 12 ? " …" : ""}.`, "Keep the palette tokens, the fonts and the components; the metaphor and the signature moment are adapted to them. Propose a new colour or type only if the user asks for a rebrand."].join("\n"),
+    "",
+    ...(past.length ? ["## Already made for this kind of screen (don't take type or colour from these)", ...past.map((r) => `- ${r.project} ${r.route}: type ${r.moves.type}; palette ${r.moves.palette}`), ""] : []),
+    "## What the research found (abstract notes)",
+    ...researchNotes(d),
+    "",
+    ...(rules.length ? ["## The user's rules (every direction keeps them)", ...rules.map((x) => `- ${x.id} ${x.rule}`), ""] : []),
+    ...(general ? ["## Whose taste (the rules that hold everywhere)", general.trim(), ""] : []),
+    `Write them to ${slash(ideasFile)}:`,
+    "```json",
+    scratch
+      ? '[{ "name": "…", "metaphor": "…", "signature": { "move": "<id>", "moment": "…" }, "starter": { "colours": { "bg": "#…", "surface": "#…", "text": "#…", "muted": "#…", "accent": "#…", "on-accent": "#…", "line": "#…" }, "type": { "display": "…", "body": "…", "source": "google-fonts", "scale": [13, 16, 20, 28, 40, 64] }, "radius": [4, 8, 16], "spacing": { "unit": 8, "scale": [8, 16, 24, 40, 64, 96] }, "motion": "…", "imagery": "…" }, "sections": ["…"], "provenance": "… nothing copied", "summary": "…", "wireframe": "…", "format": "ascii" }, …]'
+      : '[{ "name": "…", "metaphor": "…", "signature": { "move": "<id>", "moment": "…" }, "brand": "…", "sections": ["…"], "provenance": "… nothing copied", "summary": "…", "wireframe": "…", "format": "ascii" }, …]',
+    "```",
+    `Then palate_direction with the ideas (CLI: palate direction --ideas ${slash(ideasFile)}). palate picks one itself when the user's taste is strong and one direction clearly leads, or when they said "just build it" (choose: "auto"); otherwise it opens the picker in their browser and says why. Don't ask the user which one in chat.`,
+  ].join("\n");
+  fs.writeFileSync(path.join(session, "brief.md"), brief);
+  const cost = estimate({ mode: "direction", briefs: [brief] });
+  fs.writeFileSync(path.join(session, "direction.json"), JSON.stringify({ name, problem: job.trim(), route: route ?? u.route ?? null, exists: false, tags, screen: u.screen, research: d.name, brand: brand.mode, brandLine: brand.line, rebrand: brand.rebrand, moveTags: u.tags, signatures: sigs.map((m) => m.id), created: new Date().toISOString(), cost, ideas: null, chosen: null }, null, 2));
+  logCost(dir, name, "direction", cost, { research: d.name });
+  return [brief, "", "---", `Brief: ${slash(path.join(session, "brief.md"))}`, costLine(cost)].join("\n");
+}
+
+// Ideas from research: every field there and sound. Throws with every problem at once, so one retry fixes them.
+export function normalizeArtIdeas(raw, meta) {
+  const list = Array.isArray(raw) ? raw : raw?.ideas;
+  if (!Array.isArray(list) || list.length < 2 || list.length > 4) throw new Error("Give 3 art directions (2–4 at most).");
+  const problems = [];
+  const warnings = [];
+  const scratch = meta.brand === "scratch";
+  const out = list.map((x, i) => {
+    const n = `Direction ${i + 1}${x?.name ? ` (${x.name})` : ""}`;
+    for (const k of ["name", "metaphor", "provenance", "wireframe"]) if (!x?.[k]) problems.push(`${n}: needs ${k}`);
+    if (!x?.signature?.move || !x?.signature?.moment) problems.push(`${n}: needs signature { move, moment }`);
+    else if (!moveExists(x.signature.move)) warnings.push(`${n}: "${x.signature.move}" isn't in the moves library; palate will check the moment by its description`);
+    if (!Array.isArray(x?.sections) || x.sections.length < 3) problems.push(`${n}: needs a section plan (sections, 3+ names in order)`);
+    let starter = null;
+    if (scratch) {
+      const v = validateStarter(x?.starter);
+      if (!v.ok) problems.push(...v.problems.map((p) => `${n}: starter: ${p}`));
+      warnings.push(...v.warnings.map((w) => `${n}: ${w}`));
+      starter = x?.starter ? { ...x.starter, checks: v.checks } : null;
+    } else {
+      if (x?.starter && !meta.rebrand) problems.push(`${n}: this project has a brand (${meta.brandLine}); keep its tokens and say how the direction lives inside them (brand), or ask the user whether they want a rebrand`);
+      if (!x?.brand) problems.push(`${n}: needs brand: how it lives inside the project's tokens`);
+    }
+    const provenance = x?.provenance ? (/nothing copied/i.test(x.provenance) ? String(x.provenance).trim() : `${String(x.provenance).trim().replace(/[.;,]$/, "")}, nothing copied`) : "";
+    const format = x?.format === "html" || (!x?.format && /^\s*<[a-z]/i.test(x?.wireframe ?? "")) ? "html" : "ascii";
+    return {
+      id: `d${i + 1}`,
+      name: String(x?.name ?? "").trim(),
+      summary: String(x?.summary ?? `${x?.metaphor ?? ""} Signature: ${x?.signature?.moment ?? ""}`).trim(),
+      metaphor: String(x?.metaphor ?? "").trim(),
+      signature: x?.signature ? { move: String(x.signature.move).trim(), moment: String(x.signature.moment).trim() } : null,
+      brand: scratch ? null : String(x?.brand ?? "").trim(),
+      starter,
+      sections: (x?.sections ?? []).map(String),
+      provenance,
+      wireframe: String(x?.wireframe ?? "").replace(/\s+$/, ""),
+      format,
+    };
+  });
+  // Different visual worlds: two directions may not share both the ground and the headline's type genre.
+  if (scratch) {
+    const looks = out.map((x) => ideaLook(x));
+    for (let i = 0; i < looks.length; i++)
+      for (let j = i + 1; j < looks.length; j++) {
+        const [a, b] = [looks[i], looks[j]];
+        const sameGround = a.ground && b.ground && (a.ground === b.ground || (a.ground.startsWith("light") && b.ground.startsWith("light")) || [a.ground, b.ground].every((g) => ["white", "light-neutral", "light-warm", "light-cool"].includes(g)));
+        const sameType = a.display.genre !== "unknown" && a.display.genre === b.display.genre;
+        if (sameGround && sameType) problems.push(`${out[i].name} and ${out[j].name} share both the ground (${a.ground}/${b.ground}) and the headline's type genre (${a.display.genre}): make them different visual worlds`);
+      }
+  }
+  if (problems.length) throw new Error(`The art directions need fixing before the user sees them:\n- ${problems.join("\n- ")}`);
+  return Object.assign(out, { warnings });
+}
+
+// How well each direction fits the user's taste: signature fit for the job, the moves they chose before, their
+// profile's wins and losses, and their rules (an idea that names what a rule forbids loses a lot).
+export function scoreIdeas(ideas, meta, { recent = [], history = tasteHistory(meta.screen), profile = fs.existsSync(path.join(TASTE_DIR, "profile.md")) ? fs.readFileSync(path.join(TASTE_DIR, "profile.md"), "utf8") : "", rules = rulesFor(meta.tags ?? ["all"], { route: meta.route, project: meta.project }) } = {}) {
+  const fit = Object.fromEntries(matchMovesSafe({ tags: meta.moveTags ?? [], signature: true, limit: 200 }).map((m) => [m.id, m.score]));
+  const top = Math.max(1, ...Object.values(fit));
+  const pick = (re) => uniq((profile.match(re) ?? []).join(" ").toLowerCase().match(/[a-z]{5,}/g) ?? []).filter((w) => !STOP.has(w));
+  const wins = new Set(pick(/\*\*Wins:?\*\*[^\n]*/gi));
+  const loses = new Set(pick(/\*\*Loses:?\*\*[^\n]*/gi));
+  const forbidden = rules.flatMap((r) => [...String(r.rule).matchAll(/\b(?:no|never|avoid|without)\s+([a-z][a-z -]{3,30}?)(?=[,.;:)]|\s+(?:on|in|before|after|unless|or)\b|$)/gi)].map((m) => ({ id: r.id, what: m[1].trim().toLowerCase() })));
+  return ideas
+    .map((x, i) => {
+      const text = `${x.name} ${x.metaphor} ${x.summary} ${x.signature?.moment ?? ""} ${(x.sections ?? []).join(" ")} ${x.brand ?? ""}`.toLowerCase();
+      const ws = new Set(words(text));
+      const why = [];
+      let s = 0.5 - i * 0.01;
+      if (x.signature?.move && fit[x.signature.move] != null) {
+        s += 0.2 * (fit[x.signature.move] / top);
+        why.push(`signature fits the job (${fit[x.signature.move]})`);
+      }
+      const before = history.moves?.[x.signature?.move] ?? 0;
+      if (before) {
+        // A small nod to what they chose; more than that turns every product into the last one.
+        s += Math.min(0.06, 0.03 * before);
+        why.push(`you chose ${x.signature.move} before (${before}×)`);
+      }
+      // Novelty: a direction whose look repeats palate's recent pages ranks down; a fresh one up.
+      if (recent.length && x.starter) {
+        const mine = ideaLook(x);
+        const worst = Math.max(0, ...recent.map((r) => sharedAxes(mine, r.look, ["ground", "display", "imagery"]).length));
+        if (worst >= 2) (s -= 0.12 * (worst - 1)), why.push(`its look repeats a recent palate page (${worst} of 3)`);
+        else (s += 0.05), why.push("its look is unlike palate's recent pages");
+      }
+      const w = [...ws].filter((t) => wins.has(t));
+      const l = [...ws].filter((t) => loses.has(t));
+      if (w.length) (s += Math.min(0.15, 0.03 * w.length)), why.push(`profile wins: ${w.slice(0, 4).join(", ")}`);
+      if (l.length) (s -= Math.min(0.25, 0.05 * l.length)), why.push(`profile losses: ${l.slice(0, 4).join(", ")}`);
+      for (const f of forbidden)
+        if (text.includes(f.what)) {
+          s -= 0.2;
+          why.push(`names what ${f.id} forbids (${f.what})`);
+        }
+      return { id: x.id, name: x.name, score: +s.toFixed(3), why };
+    })
+    .sort((a, b) => b.score - a.score);
+}
+
+export const CLOSE_GAP = 0.08;
+// Auto-pick or picker. choose: "auto" (the user said just build it), "user" (they asked to choose), or undefined.
+// strength: the triage's reading of the user's taste for this kind of screen (none | some | strong).
+export function decidePick({ scored, strength = "none", choose, history = { chosen: 0 }, screen = "this kind of screen" }) {
+  const [a, b] = scored;
+  const label = screen === "other" ? "this kind of screen" : `${screen} pages`;
+  if (choose === "user") return { auto: false, why: "Opening the picker: the user asked to choose." };
+  if (choose === "auto") return { auto: true, pick: a, why: `Picked "${a.name}" from your taste: you said to just build it.` };
+  const strong = strength === "strong" || (history.chosen ?? 0) >= 2;
+  if (!strong) return { auto: false, why: `Opening the picker: ${strength === "some" || history.chosen ? "only a little" : "no"} history for ${label} yet.` };
+  if (b && a.score - b.score < CLOSE_GAP) return { auto: false, why: `Opening the picker: "${a.name}" and "${b.name}" score close (${a.score} vs ${b.score}): a real judgement call.` };
+  return { auto: true, pick: a, why: `Picked "${a.name}" from your taste: your history for ${label} is strong and it leads${b ? ` by ${(a.score - b.score).toFixed(2)}` : ""}${a.why.length ? ` (${a.why.slice(0, 2).join("; ")})` : ""}.` };
+}
+
+// The whole decision for a direction session (research or not).
+export function decide(dir, meta, list, { choose } = {}) {
+  const history = tasteHistory(meta.screen);
+  const scored = scoreIdeas(list, { ...meta, project: projectOf(dir) }, { history, recent: recentLooks({ excludePid: projectId(dir) }) });
+  let strength = "none";
+  try {
+    strength = plan(dir, meta.problem, { route: meta.route ?? undefined, mode: "research", log: false }).strength;
+  } catch {}
+  return { ...decidePick({ scored, strength, choose, history, screen: meta.screen ?? "other" }), scored, strength };
+}
+
+// What the picker shows besides the ideas: the brand case and the references (which the user may like or dislike).
+export function pickerState(dir, meta) {
+  const d = loadResearch(dir, meta.research);
+  return { research: d ? { name: d.name, product: d.understanding.product, brand: meta.brand, brandLine: meta.brandLine, refs: d.kept.map((r) => ({ id: r.id, name: r.name, url: r.url, role: r.role, learn: r.learn.line })), cliches: d.cliches.map((c) => c.label) } : null };
+}
+
+// The extra fields a choice logs to ~/.palate/taste/directions.jsonl (palate learns from them).
+export function choiceFields(meta, idea) {
+  if (!idea) return {};
+  return { screen: meta.screen ?? null, research: meta.research ?? null, brand: meta.brand ?? null, metaphor: idea.metaphor ?? null, signature: idea.signature ?? null, starter: idea.starter ? { colours: idea.starter.colours ?? idea.starter.colors, type: idea.starter.type, radius: idea.starter.radius, motion: idea.starter.motion, imagery: idea.starter.imagery } : null, provenance: idea.provenance ?? null };
+}
+

package/src/loop/bench.mjs

@@ -0,0 +1,184 @@
+// The benchmark: 30 fictional landing-page briefs (kb/bench/briefs.json) that palate builds end to end with no
+// human input on each release, so quality is measured on pages nobody tuned for, not taken from self-scores.
+// A brief is scaffolded into an empty Vite + React + Tailwind project; whoever runs the build (an agent, a
+// script) records one result per brief, and the report sums them per release: floor pass rate, reference
+// tie-or-win rate (from a judge that saw both orders), build minutes and cost. The references are real sites
+// used only as judging exemplars: never shipped, never copied, never handed to the builder as material.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { KB_ROOT } from "../paths.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = path.resolve(here, "..", "..");
+const KB_DIR = process.env.PALATE_KB ?? KB_ROOT;
+
+export const BENCH_DIR = path.join(PALATE_HOME, "bench");
+export const RESULTS_FILE = path.join(BENCH_DIR, "results.jsonl");
+export const BRIEFS_FILE = path.join(KB_DIR, "bench", "briefs.json");
+export const TEMPLATE_DIR = path.join(PKG_DIR, "templates", "vite-react-tw");
+
+let cached = null;
+function loadBriefs() {
+  if (!cached) cached = JSON.parse(fs.readFileSync(BRIEFS_FILE, "utf8"));
+  return cached;
+}
+
+export const categories = () => loadBriefs().categories ?? [...new Set(loadBriefs().briefs.map((b) => b.category))];
+
+// Every brief, or only one category's.
+export function listBriefs({ category } = {}) {
+  const { briefs } = loadBriefs();
+  if (!category) return briefs;
+  if (!categories().includes(category)) throw new Error(`No bench category "${category}". Categories: ${categories().join(", ")}.`);
+  return briefs.filter((b) => b.category === category);
+}
+
+export function getBrief(id) {
+  const b = loadBriefs().briefs.find((x) => x.id === id);
+  if (!b) throw new Error(`No bench brief "${id}". The ${loadBriefs().briefs.length} briefs are in ${BRIEFS_FILE}.`);
+  return b;
+}
+
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const e of fs.readdirSync(from, { withFileTypes: true })) {
+    // npm drops .gitignore from published packages, so a template may carry it as "gitignore" or "_gitignore".
+    const name = e.isFile() && /^_?gitignore$/.test(e.name) ? ".gitignore" : e.name;
+    if (e.isDirectory()) copyDir(path.join(from, e.name), path.join(to, name));
+    else fs.copyFileSync(path.join(from, e.name), path.join(to, name));
+  }
+}
+
+const npmName = (id) => `bench-${id}`.toLowerCase().replace(/[^a-z0-9-._~]/g, "-");
+
+// Copies the template into `into` (which must be empty or missing), names the project, writes the brief's README
+// and .palate/bench.json, and says what to do next.
+export function scaffold(id, into) {
+  const brief = getBrief(id);
+  if (!into) throw new Error("scaffold needs a folder to build into.");
+  const dir = path.resolve(into);
+  if (fs.existsSync(dir) && (!fs.statSync(dir).isDirectory() || fs.readdirSync(dir).length)) throw new Error(`${dir} is not empty; a bench brief starts from an empty folder.`);
+  copyDir(TEMPLATE_DIR, dir);
+
+  const pkgFile = path.join(dir, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+  pkg.name = npmName(brief.id);
+  fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + "\n");
+  const html = path.join(dir, "index.html");
+  if (fs.existsSync(html)) fs.writeFileSync(html, fs.readFileSync(html, "utf8").replaceAll("{{title}}", brief.product));
+
+  fs.writeFileSync(path.join(dir, "README.md"), brief.readme.endsWith("\n") ? brief.readme : brief.readme + "\n");
+  fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+  const meta = { id: brief.id, job: brief.job, references: brief.references, created: new Date().toISOString() };
+  fs.writeFileSync(path.join(dir, ".palate", "bench.json"), JSON.stringify(meta, null, 2) + "\n");
+
+  return [
+    `Bench brief "${brief.id}" (${brief.category}) is ready in ${dir}.`,
+    `${brief.product}: README.md has the product facts; build from them with no human input.`,
+    "",
+    "Next:",
+    `  cd ${JSON.stringify(dir)}`,
+    "  pnpm install",
+    `  The job: ${brief.job}`,
+    `  palate plan ${JSON.stringify(brief.job)}`,
+  ].join("\n");
+}
+
+// The release a result belongs to: palate's version plus the git commit when palate runs from a checkout.
+export function releaseTag() {
+  const { version } = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "utf8"));
+  let sha = "";
+  try {
+    const r = spawnSync("git", ["rev-parse", "--short", "HEAD"], { cwd: PKG_DIR, encoding: "utf8", windowsHide: true, timeout: 5000 });
+    if (r.status === 0) sha = r.stdout.trim();
+  } catch {}
+  return sha ? `${version}+${sha}` : version;
+}
+
+// One build's result: { floor: {pass, fails:[...]}, vsRefs: {wins, ties, losses, inconsistent}, minutes, tokens, cost?, notes }.
+export function recordResult(id, result = {}) {
+  getBrief(id);
+  const row = { id, release: result.release ?? releaseTag(), at: new Date().toISOString(), ...result };
+  fs.mkdirSync(BENCH_DIR, { recursive: true });
+  fs.appendFileSync(RESULTS_FILE, JSON.stringify(row) + "\n");
+  return row;
+}
+
+export function readResults() {
+  if (!fs.existsSync(RESULTS_FILE)) return [];
+  return fs
+    .readFileSync(RESULTS_FILE, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((l) => {
+      try {
+        return [JSON.parse(l)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+const pct = (n, d) => (d ? `${Math.round((n / d) * 100)}%` : "–");
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+const cell = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+
+// A Markdown summary of one release (the newest one recorded when none is named): the latest result per brief,
+// then the totals the benchmark is judged on.
+export function benchReport({ release } = {}) {
+  const all = readResults();
+  if (!all.length) return `No bench results yet in ${RESULTS_FILE}.`;
+  const rel = release ?? all[all.length - 1].release;
+  const rows = all.filter((r) => r.release === rel);
+  if (!rows.length) return `No bench results for release ${rel}. Recorded releases: ${[...new Set(all.map((r) => r.release))].join(", ")}.`;
+
+  const latest = new Map();
+  for (const r of rows) latest.set(r.id, r); // file order is time order; the last one wins
+  const briefs = loadBriefs().briefs;
+  const order = new Map(briefs.map((b, i) => [b.id, i]));
+  const done = [...latest.values()].sort((a, b) => (order.get(a.id) ?? 1e9) - (order.get(b.id) ?? 1e9));
+
+  const t = { floorRun: 0, floorPass: 0, wins: 0, ties: 0, losses: 0, inconsistent: 0, minutes: [], tokens: 0, tokensSeen: false, cost: 0, costSeen: false };
+  const lines = [
+    `# palate bench · ${rel}`,
+    "",
+    `${done.length} of ${briefs.length} briefs built (${rows.length} result${rows.length === 1 ? "" : "s"} recorded, latest per brief counted).`,
+    "",
+    "| Brief | Category | Floor | Fails | vs refs W/T/L/inc | Minutes | Tokens | Cost | Notes |",
+    "|---|---|---|---|---|---|---|---|---|",
+  ];
+  for (const r of done) {
+    const cat = briefs.find((b) => b.id === r.id)?.category ?? "?";
+    const floor = r.floor && typeof r.floor.pass === "boolean" ? r.floor : null;
+    if (floor) {
+      t.floorRun++;
+      if (floor.pass) t.floorPass++;
+    }
+    const v = r.vsRefs ?? null;
+    if (v) for (const k of ["wins", "ties", "losses", "inconsistent"]) t[k] += num(v[k]) ?? 0;
+    if (num(r.minutes) != null) t.minutes.push(r.minutes);
+    if (num(r.tokens) != null) (t.tokens += r.tokens), (t.tokensSeen = true);
+    if (num(r.cost) != null) (t.cost += r.cost), (t.costSeen = true);
+    lines.push(
+      `| ${cell(r.id)} | ${cell(cat)} | ${floor ? (floor.pass ? "pass" : "FAIL") : "–"} | ${cell((floor?.fails ?? []).join("; ")) || "–"} | ${v ? `${num(v.wins) ?? 0}/${num(v.ties) ?? 0}/${num(v.losses) ?? 0}/${num(v.inconsistent) ?? 0}` : "–"} | ${num(r.minutes) != null ? r.minutes.toFixed(1) : "–"} | ${num(r.tokens) != null ? r.tokens.toLocaleString("en-US") : "–"} | ${num(r.cost) != null ? `$${r.cost.toFixed(2)}` : "–"} | ${cell(r.notes) || ""} |`,
+    );
+  }
+  const judged = t.wins + t.ties + t.losses + t.inconsistent;
+  const meanMin = t.minutes.length ? t.minutes.reduce((a, b) => a + b, 0) / t.minutes.length : null;
+  lines.push(
+    "",
+    "## Totals",
+    "",
+    `- Floor pass rate: ${pct(t.floorPass, t.floorRun)} (${t.floorPass}/${t.floorRun}; target 100%)`,
+    `- Reference tie-or-win rate: ${pct(t.wins + t.ties, judged)} (${t.wins} wins, ${t.ties} ties, ${t.losses} losses, ${t.inconsistent} inconsistent across orders, of ${judged} pairs; tie share ${pct(t.ties, judged)}; inconsistent pairs count as not won)`,
+    `- Mean build: ${meanMin != null ? `${meanMin.toFixed(1)} min` : "–"} over ${t.minutes.length} build${t.minutes.length === 1 ? "" : "s"}`,
+    `- Tokens: ${t.tokensSeen ? t.tokens.toLocaleString("en-US") : "–"}`,
+    `- Cost: ${t.costSeen ? `$${t.cost.toFixed(2)}` : "–"}`,
+  );
+  const missing = briefs.filter((b) => !latest.has(b.id)).map((b) => b.id);
+  if (missing.length) lines.push("", `Not built in this release: ${missing.join(", ")}.`);
+  return lines.join("\n") + "\n";
+}