@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/plan.mjs

@@ -0,0 +1,289 @@
+// `palate plan "<request>" [--route /x] [--mode direct|build|direction|quick|full]`: what this request
+// deserves, decided before anything is built. AI gets a screen 80% of the way; palate does the last 20%. So
+// the default is one build from the user's references and rules, then the finishing pass, then the user
+// points at what's wrong. Exploring costs minutes and tokens; it pays only where palate doesn't yet know what
+// the user wants.
+//   direct     a fix, tweak or copy change, or something a critique or details pass already pinpointed:
+//              change it in place, one check, done.
+//   build      the default: one build of the real route from the user's references, rules and taste, then
+//              the finishing pass (shoot, details, critique on request), then palate point.
+//   direction  a job-level question or problem ("users wait 20 seconds here, what should they see?"): 3 short
+//              ideas with rough wireframes, the user picks one, then build mode. Nothing is rendered.
+//   research   a new screen with no strong taste history, or an ask for something new: competitors and well-crafted
+//              pages looked at live (palate research), 3 art directions with a signature moment (palate picks
+//              one from taste when confident, else the picker), then one build. decision.auto: palate may pick.
+//   quick      variants, only when the user asks to explore one section: 2–3 sketches, no judge, they pick.
+//   full       variants, when the user asks to explore a page, or for a new kind of screen with no taste
+//              history: sketches first, a judge, the pick as soon as 4 are ready.
+// Signals: the wording, whether the route exists, the taste profile's section for this kind of screen and
+// how strong its evidence is, and whether the user's recent picks in this project were clear (palate is
+// learning: explore less) or "none of these" (explore more). Every decision is logged with its reason, and
+// the variant modes say what build mode would cost instead.
+import fs from "node:fs";
+import path from "node:path";
+import { isScaffold, routeFile } from "../look.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { TASTE_DIR, screenKind } from "./common.mjs";
+import { kindWords } from "./craft.mjs";
+import { HISTORY_DIR, screenOf } from "./layouts.mjs";
+import { k, PER, typical } from "./cost.mjs";
+import { kindTags, rulesBlock } from "./rules.mjs";
+
+export const PLANS_LOG = path.join(HISTORY_DIR, "plans.jsonl");
+export const MODES = ["direct", "build", "direction", "research", "quick", "full", "match"];
+// match (since Nov 7): the user's own design is the spec ("match this design", "build it from my Figma frame",
+// "make it look exactly like this", an image or a Figma link to build). palate's taste steps aside; the build is
+// checked for fidelity. An image given as a reference or for inspiration is not this: it goes to refs, then build.
+const MATCH = /\b(match(es|ing)? (this|my|our|the|that|these) (design|mock-?ups?|screenshots?|figma( frame| file| design)?|frames?|comps?|image|layout|png|jpe?g|export)|(build|make|code|implement|recreate|replicate|reproduce|turn|convert|create)\b.{0,50}\bfrom (this|my|our|the|a|these) (screenshots?|mock-?ups?|figma( frames?| files?| designs?)?|designs?( file)?|image|png|jpe?g|comps?|export)|(implement|build|code|recreate|replicate) (this|my|our|the) (figma|mock-?up|design comp|figma design|design file)|look(s|ing)? exactly (like|as)|exactly (like|as) (this|the|my|our|in the) (image|screenshot|design|mock-?up|figma|png|comp|frame)|pixel[- ]perfect|(faithful(ly)?|1:1|one[- ]to[- ]one) (copy|build|implementation|recreation|match|to (the|my|this) (design|mock-?up|figma))|(screenshot|mock-?up|figma( frame)?|design) (to|into) (code|react|html|a page|a component))/i;
+const FIGMA_LINK = /\b(?:https?:\/\/)?(?:www\.)?figma\.com\/(?:file|design|proto|board)\/[A-Za-z0-9]+\S*/i;
+const IMAGE_PATH = /(?:^|[\s"'(])((?:[A-Za-z]:)?[\w./\\~-]*\.(?:png|jpe?g|webp))\b/i;
+const URL_RE = /\bhttps?:\/\/[^\s"'<>)]+/i;
+const BUILD_VERB = /\b(build|implement|code|make|recreate|replicate|reproduce|turn|convert|match|create)\b/i;
+// The image is a reference to learn from, not the spec.
+const AS_REFERENCE = /\b(references?|inspiration|inspired by|similar to|in the spirit of|vibe|feel of|moodboard|like (the|its) .{0,30}(spacing|colou?rs?|type|layout|feel|style)|something like)\b/i;
+// The design's source in the request: a Figma link, an image path, or a page URL (when the request is a match).
+export function matchSource(text) {
+  const t = String(text ?? "");
+  return t.match(FIGMA_LINK)?.[0] ?? t.match(IMAGE_PATH)?.[1] ?? t.match(URL_RE)?.[0]?.replace(/[.,;:!?]+$/, "") ?? null;
+}
+// The match phrase named as a thing rather than asked for ("a docs page: fix, build, match my design, point"): inside
+// brackets, an item in a list, or in a request about docs or features. Only counts when the request has no source.
+const ABOUT_FEATURES = /\b(docs?|documentation|guide|explain(er)?|describe|features?|what (it|palate|this) (can )?does?|what (it|palate|this) can do|changelog|faq)\b/i;
+function mentionedOnly(t) {
+  const m = MATCH.exec(t);
+  if (!m || matchSource(t)) return false;
+  const before = t.slice(0, m.index), after = t.slice(m.index + m[0].length);
+  const inBrackets = (before.match(/\(/g)?.length ?? 0) > (before.match(/\)/g)?.length ?? 0);
+  const inList = /,\s*$/.test(before) && /^\s*([,)]|(and|or)\b)/i.test(after);
+  return inBrackets || inList || ABOUT_FEATURES.test(t);
+}
+// "in the site's style", "matching the rest of the site", "same look as our homepage": a new page in a look that exists.
+const OWN_STYLE = /\b(in|with|using|keep(ing)?|match(es|ing)?|same as|consistent with|like) (the |our |my |this )?(site|website|app|product|brand|homepage|home page|landing page|rest of the (site|app|website))('s|’s)? (own )?(style|look|design|system|brand(ing)?|feel|theme)\b|\b(match(es|ing)?|like|consistent with) the rest of the (site|app|website|product)\b|\bsame (style|look|design) as (the |our )?(site|homepage|home page|rest)\b/i;
+// The request without its lists: bracketed lists, and in a request about docs or features, runs of three or more
+// comma-separated items. What's left is what the user asked for.
+export function askedText(text) {
+  let t = String(text ?? "").replace(/\([^()]*,[^()]*,[^()]*\)/g, " ");
+  if (ABOUT_FEATURES.test(t)) t = t.replace(/(?:[\w'’ -]{1,40},\s*){2,}(?:(?:and|or)\s+)?[\w'’ -]{1,40}/g, " ");
+  return t.replace(/\s+/g, " ").trim();
+}
+export function isMatchRequest(text) {
+  const t = String(text ?? "");
+  if (MATCH.test(t)) return !mentionedOnly(t) && (!AS_REFERENCE.test(t) || /\bexactly\b|pixel[- ]perfect/i.test(t));
+  return (FIGMA_LINK.test(t) || IMAGE_PATH.test(t)) && BUILD_VERB.test(t) && !AS_REFERENCE.test(t);
+}
+// research (since Oct 26): a new screen palate has no strong history for, or an ask for something new or creative:
+// live research of competitors and well-crafted pages, 3 art directions with a signature moment, then one build.
+const CREATIVE = /\b(creative|stand out|distinctive|memorable|fresh (look|take|design)|something (new|different|special|unexpected)|unique|original|inspir(ed|ing|ation)|not (generic|basic|boring|bland)|less (generic|basic|boring)|wow|award[- ]worthy|signature|art direct(ion|ed))\b/i;
+// "Just build it": the agent goes research → direction → build with no picker; palate picks the direction from taste.
+export const JUST_BUILD = /\b(just (build|make|do) it|don'?t ask( me)?|no questions|surprise me|you (decide|choose|pick)|your call|pick (one|for me)|go ahead and build|build it straight)\b/i;
+
+const FIX = /\b(fix|fixes|fixing|tweak|adjust|change|update|rename|move|align|nudge|bump|increase|decrease|reduce|shrink|enlarge|bigger|smaller|larger|darker|lighter|bolder|thinner|tighten|loosen|spacing|padding|margin|gap|colou?rs?|copy|typo|wording|label|bug|broken|overflow|overlap|polish|clean ?up|replace|swap|remove|delete|hide|centre|center|resize|contrast|cut off|wrap|inconsistent|mismatch(ed)?|uneven|misaligned|(one|the same|same|a single) (size|height|width|weight|colou?r|style|spacing)|(different|two|three|four|\d) (sizes|heights|widths|weights|colou?rs|fonts|styles|paddings?|spacings?)|\d+ ?px)\b/i;
+// A small addition to a page that exists ("add a members-are-free note under the plans"): a tweak, not a build.
+const SMALL_ADD = /\badd (a|an|one|some|the)? ?([\w'-]+ ){0,4}(note|line|link|label|badge|caption|sentence|tooltip|icon|hint|disclaimer|footnote|tag|button|arrow|divider)s?\b/i;
+// A feeling, not an instruction ("make it feel more like a real studio"): the page needs a plan, not a tweak.
+const FEEL = /\b(feel|feels|feeling|vibe|more like|less like|look (more|less)|more (premium|modern|polished|professional|alive|human|real))\b/i;
+const DESIGN = /\b(design|redesign|new|create|build|rebuild|make (a|an) (new )?(page|screen|section)|from scratch|add (a|an) [a-z ]*(section|page|screen))\b/i;
+const EXPLORE = /\b(explore|exploration|options|alternatives|directions|ideas|variations|variants|concepts|different (takes|looks|versions|directions)|a few (versions|takes)|several (versions|takes|options)|show me (some|a few))\b/i;
+const PINPOINTED = /\b(findings?|F\d+|critique|details pass|palate details|the review|agreed)\b/;
+const SECTION = /\b(section|hero|footer|header|nav(bar)?|banner|cta|faq|testimonials?|logo (cloud|row)|signup form|form|card|modal|dialog|component|widget|table|chart|sidebar|toolbar|empty state)\b/i;
+const PAGE = /\b(page|screen|site|website|app|dashboard|flow|landing|homepage)\b/i;
+// Concrete instructions: the request already says what to change ("move X outside Y", "make the cards play on
+// their own", "pastel instead of dots", "no black", "a real prompt box"). Nothing to explore: build it.
+const CONCRETE = /\b(instead of|rather than|replace\b.{1,50}\bwith|swap\b.{1,50}\b(for|with)|move\b.{1,50}\b(to|into|outside|out of|below|above|beside|next to|under|over)|(make|let) (the|it|them|each|every|all)\b.{1,60}\b(play|animate|move|sit|look|use|show|stay|finish|start|stop|loop|auto-?play)|turn\b.{1,50}\binto|put\b.{1,50}\b(in|into|outside|beside|under|above)|no (more )?(pure[- ])?(black|grey|gray|dots?|dotted|shadows?|borders?|gradients?|frames?|screenshots?|kickers?|labels?|step bars?)|not (black|grey|gray|inside|in one|dotted)|(a|an) real\b|should (be|sit|play|look|use|show)|use (the )?(brand|pastel|soft|real)|with (skip|replay))/i;
+// The request names parts of a page that exists ("the feature cards", "the demo sidebar").
+const PART = /\bthe (\w+[ -]){0,3}(cards?|demo|sidebar|hero|section|button|form|header|footer|logos?|nav|bar|panel|grid|table|list|signup|input|cta|band|stage|chips?|toolbar|modal|menu|plans?|tiers?|headings?|titles?|h[1-6]s?|prices?|pricing|steps?|quotes?|testimonials?|links?|images?|photos?|copy|text|stats?|faqs?)\b/i;
+const NEW_THING = /\b(redesign(ed)?|rebuil[dt]|new (page|screen|section|version|landing)|from scratch|create (a|an)|(build|design) (a|an|the) (new )?(page|screen|section|landing|home))\b/i;
+// Job-level asks, shaped as a question or a problem: "what could we show them so they don't leave?", "how
+// should onboarding work?", "users wait ~20 seconds here". They need an idea before a build.
+const QUESTION = /^\s*(what|how|which|where|why|should we)\b|\?\s*$|\bwhat (could|should|would|can|do|might) (we|i|they|it|users?|people|visitors?|customers?) (show|see|put|do|say|use|offer|give)\b|\bhow (should|could|can|would|do) (we|i)\b/i;
+// "Can you build the pricing page?" is a request in question form, not a question about the job.
+const POLITE = /^\s*(can|could|would|will) you\b|^\s*please\b/i;
+const PROBLEM = /\b(users?|people|visitors?|customers?|they) (wait|leave|bounce|drop( off)?|churn|quit|give up|get lost|get stuck|are confused|don'?t (understand|know|get|see|find|notice|trust|stay))\b|\bso (they|users?|people|visitors?) (stay|don'?t leave|keep|come back|understand)\b|\bwhile (they|users?|people|visitors?) wait\b/i;
+// Words too generic to pick a profile section ("app" matched "Onboarding / setup screen (app)").
+const SMALL_PAGE = /\b(404|500|not[- ]found|error page|maintenance (page|mode)|offline page|coming soon|thank[- ]you page|success page|unsubscribe|privacy (page|policy)|terms (page|of service)|cookie policy|legal page|imprint)\b/i;
+const GENERIC = new Set(["app", "screen", "page", "section", "loop", "other", "the", "and"]);
+// A site, not an app screen: "homepage", "landing", "website", "portfolio", "a site for <business>".
+const SITE = /\b(home ?page|landing|web ?site|marketing (page|site)|portfolio (site|page|homepage)|(a|the|our) site for)\b/i;
+// Screens that live inside an app, even at "/".
+const APP_SCREENS = new Set(["onboarding", "team", "settings", "table", "dashboard", "auth"]);
+
+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) : []);
+
+// Picks grouped by loop: who won, and whether the pick was clear (one winner over all) or "none".
+function loopsFromPicks() {
+  const by = new Map();
+  for (const p of readLines(path.join(TASTE_DIR, "picks.jsonl"))) {
+    const key = `${p.project}/${p.loop}`;
+    const L = by.get(key) ?? { project: p.project, loop: p.loop, kind: p.kind, job: p.job, wins: {}, none: false, at: p.at, records: 0 };
+    L.records++;
+    L.at = p.at > L.at ? p.at : L.at;
+    if (p.choice === "none") L.none = true;
+    if (p.winner) L.wins[p.winner] = (L.wins[p.winner] ?? 0) + 1;
+    by.set(key, L);
+  }
+  return [...by.values()].map((L) => {
+    const ranked = Object.values(L.wins).sort((a, b) => b - a);
+    return { ...L, screen: screenOf(L.loop, L.job ?? ""), clear: !L.none && ranked.length > 0 && (ranked.length === 1 || ranked[0] > ranked[1]) };
+  });
+}
+
+// The profile's section for this kind of screen, and how strong its evidence reads.
+// screen: the kind asked for ("features"). Its own word outranks the shared marketing words, so a features ask
+// reads the Features section and not Hero (both share "hero" in the words, and a tie went to the first in the file).
+function profileSection(words, screen = "other") {
+  const f = path.join(TASTE_DIR, "profile.md");
+  if (!fs.existsSync(f)) return null;
+  const q = new Set((words.toLowerCase().match(/[a-z]{3,}/g) ?? []).filter((w) => !GENERIC.has(w)));
+  const blocks = fs.readFileSync(f, "utf8").replace(/\r\n/g, "\n").split(/\n(?=## )/).filter((b) => /^## /.test(b));
+  const best = blocks.map((b) => ({ b, head: b.match(/^## (.+)/)[1], s: (b.match(/^## (.+)/)[1].toLowerCase().match(/[a-z]{3,}/g) ?? []).filter((w) => q.has(w) || q.has(w.replace(/s$/, ""))).length + (screen !== "other" && (b.match(/^## (.+)/)[1].toLowerCase().match(/[a-z]{3,}/g) ?? []).some((w) => w === screen || w.replace(/s$/, "") === screen.replace(/s$/, "")) ? 2 : 0) })).sort((a, b) => b.s - a.s)[0];
+  if (!best?.s) return null;
+  const sweeps = [...best.b.matchAll(/\b(\d+) of (\d+)\b/g)].filter((m) => m[1] === m[2] && Number(m[1]) >= 2).length;
+  const unclear = /\btie\b|no variant stood out|coin flip|needs a sharper idea/i.test(best.b);
+  return { head: best.head, sweeps, unclear };
+}
+
+export function plan(dir, request, { route, mode, name, log = true } = {}) {
+  const text = String(request ?? "");
+  // An image path or a link in the request is the design's source, not a route ("/c/Users/me/shot.png").
+  const bare = text.replace(FIGMA_LINK, " ").replace(URL_RE, " ").replace(/\S*\.(png|jpe?g|webp)\b/gi, " ");
+  let r = route ? normalizeRoute(route) : (bare.match(/(?:^|\s)(\/[a-z0-9/_-]*)(?=[\s.,;:!?)]|$)/i)?.[1] ?? null);
+  // No route named, but the request names parts of a page ("the feature cards"): the site's root page, if it has one.
+  // "the landing page" or "the homepage" is the root page too, when the site has one.
+  const assumed = !r && ((PART.test(text) && !NEW_THING.test(text)) || /\bthe (landing|home) ?page\b|\bthe homepage\b/i.test(text)) && Boolean(routeFile(dir, "/"));
+  if (assumed) r = "/";
+  // A scaffold (the bench template's empty <main>, a starter's demo page) is a new page, not an existing one.
+  const file = r ? routeFile(dir, r) : null;
+  const exists = Boolean(file) && !isScaffold(file.file);
+  // "a pricing section on the landing page" is about pricing: the words before "section" name the screen.
+  const sectionOf = text.match(/\b([a-z]+(?: [a-z]+)?) section\b/i)?.[1];
+  // An existing route's own kind beats keywords in the request: the root page is a landing page, even when the
+  // request talks about "agent step components".
+  const routeScreen = exists ? (r === "/" ? "landing" : screenOf(r.replace(/[/_-]+/g, " "))) : "other";
+  const screen = routeScreen !== "other" ? routeScreen : screenOf(name ?? "", sectionOf ?? text);
+  // A homepage, landing page or website for a business is marketing, with or without a route: "a homepage for
+  // Mabel's Bakehouse" was read as an app and skipped the blueprint.
+  const sk = screenKind(name ?? "", text).kind;
+  const site = ["landing", "pricing", "features"].includes(screen) || SITE.test(text) || (r === "/" && !APP_SCREENS.has(screen));
+  const kind = ["landing", "hero", "pricing", "features"].includes(routeScreen) ? "marketing" : sk === "app" && site ? "marketing" : sk;
+  // The wording is read from what was asked, not what was listed: "(fix, build, match my design, point, variants)"
+  // in a docs request named palate's features and was read as a fix that wanted variants.
+  const said = askedText(text);
+  const words = { fix: FIX.test(said) || (SMALL_ADD.test(said) && !NEW_THING.test(said)), design: DESIGN.test(said), explore: EXPLORE.test(said), pinpointed: PINPOINTED.test(said), concrete: CONCRETE.test(said) && !NEW_THING.test(said) && !FEEL.test(said) && said.length <= 400, feel: FEEL.test(said), jobLevel: (QUESTION.test(said) && !POLITE.test(said)) || PROBLEM.test(said), problem: PROBLEM.test(said), section: /\bsection\b/i.test(said) || (SECTION.test(said) && !/\b(page|screen)\b/i.test(said)), page: PAGE.test(said), creative: CREATIVE.test(said), justBuild: JUST_BUILD.test(said) };
+  // Taste: the profile section for this kind, and this kind's loops in the pick log. A kind palate can't
+  // name ("other") has no history of its own.
+  const section = profileSection(`${kindWords(screen, kind, name ?? sectionOf ?? "")} ${screen !== "other" ? screen : ""}`, screen);
+  const loops = loopsFromPicks();
+  const sameKind = screen !== "other" ? loops.filter((L) => L.screen === screen) : [];
+  const clearLoops = sameKind.filter((L) => L.clear).length;
+  const strength = section && !section.unclear && (section.sweeps > 0 || clearLoops > 0) ? "strong" : section || sameKind.length ? "some" : "none";
+  // The user's recent picks in this project.
+  const project = path.basename(path.resolve(dir));
+  const recent = loops.filter((L) => L.project === project).sort((a, b) => (a.at < b.at ? 1 : -1)).slice(0, 3);
+  const exploreMore = recent[0]?.none === true;
+  const learning = !exploreMore && recent.length >= 2 && recent.every((L) => L.clear);
+
+  let m;
+  let why;
+  const kindName = section ? section.head.split(/ [—-] /)[0] : screen !== "other" ? screen : "this kind of screen";
+  const match = isMatchRequest(text);
+  if (mode && MODES.includes(mode)) [m, why] = [mode, `you asked for ${mode}`];
+  // The user's own design is the spec: build it faithfully; palate's taste steps aside.
+  else if (match) [m, why] = ["match", "the user gave their own design to build: it is the spec, so palate builds it faithfully instead of designing its own look"];
+  else if (words.pinpointed && !words.explore) [m, why] = ["direct", "the change is already pinpointed (a critique or details finding)"];
+  else if (words.concrete && !words.explore && exists) [m, why] = ["direct", `the request names exact changes to ${r}, which exists`];
+  // A question or a problem ("what should they see so they stay?") needs an idea first; "can you fix the header?" doesn't.
+  else if (words.jobLevel && (words.problem || words.design || !words.fix)) [m, why] = ["direction", words.problem ? "it describes a problem the user's users have, not a design: it needs an idea before a build" : "it asks what to do, not how it should look: it needs an idea before a build"];
+  else if (words.fix && !words.design && !words.explore && !words.feel) [m, why] = ["direct", `this is a ${words.section ? "fix to an existing section" : "fix or tweak"}${exists ? ` of ${r}, which exists` : ""}`];
+  // Variants only when asked to explore, or for a new kind of screen palate knows nothing about.
+  else if (words.explore) [m, why] = [words.section ? "quick" : "full", "you asked to explore"];
+  // A small system page (404, error, privacy, thank-you…) is one build even with no history: variants would cost
+  // more than the page is worth.
+  else if (SMALL_PAGE.test(`${text} ${r ?? ""}`)) [m, why] = ["build", "a small system page: one build is enough"];
+  // A new page asked for in the look the site already has: its system is the direction, so no new art directions.
+  else if (OWN_STYLE.test(said) && !words.creative) [m, why] = ["build", "a new page in the site's own look: build it from the system the site already has"];
+  // A new screen without strong history, or an ask for something new: research first (it replaced "full" as the
+  // default for new screens; variants stay opt-in).
+  // Strong taste learned on other projects is not this product's history: a new product still researches first
+  // (taste then picks the direction, so it leads with what the user keeps choosing without cloning that project).
+  else if (!words.section && !exists && (strength !== "strong" || !recent.length) && (words.design || words.page))
+    [m, why] = ["research", strength === "strong" ? `a new ${screen !== "other" ? `${screen} ` : ""}screen for a product with no picks yet: your taste for ${kindName} comes from other projects, so look at this product's competitors and well-crafted pages first; palate picks the direction from that taste` : `a new ${screen !== "other" ? `${screen} ` : ""}screen with ${strength === "none" ? "no history" : "only some history"} in your taste: look at competitors and well-crafted pages first`];
+  else if (words.creative && !words.fix && (words.design || words.page || exists)) [m, why] = ["research", "you asked for something new: look at what competitors and the best pages do first"];
+  else [m, why] = ["build", exists ? `${r} exists: build on it from your references and rules` : strength === "strong" ? `you have a clear winner for ${kindName}: build from that` : strength === "some" ? `palate has history for ${kindName}: build from that` : `one ${words.section ? "section" : "screen"}, and you didn't ask to explore`];
+
+  // How many: fewer when taste is known, more after "none of these".
+  let count = 0;
+  let per = 0;
+  if (m === "quick") [count, per] = [!exploreMore && (strength === "strong" || (strength === "some" && learning && !section?.unclear)) ? 2 : 3, 1];
+  if (m === "full") [count, per] = strength === "none" || exploreMore ? [3, 2] : [4, 1];
+  const variants = count * per;
+  const signals = [
+    `wording: ${Object.entries(words).filter(([, v]) => v).map(([k]) => k).join(", ") || "neutral"}`,
+    r ? `route ${r}: ${exists ? "exists" : "new"}${assumed ? " (assumed: the request is about the site's existing root page)" : ""}` : "route: none named",
+    `taste for ${screen !== "other" ? screen : kind}: ${strength}${section ? ` (profile: "${section.head}"${section.sweeps ? `, ${section.sweeps} clean sweep${section.sweeps > 1 ? "s" : ""}` : ""}${section.unclear ? ", unclear" : ""})` : " (no profile section)"}${sameKind.length ? `, ${clearLoops} of ${sameKind.length} past loops with a clear winner` : ""}`,
+    recent.length ? `recent picks in ${project}: ${recent.map((L) => (L.none ? `${L.loop}: none of these` : `${L.loop}: ${L.clear ? "clear" : "split"}`)).join(", ")}${exploreMore ? " → explore more" : learning ? " → palate is learning, explore less" : ""}` : `no picks yet in ${project}`,
+  ];
+  const judge = m === "full" && variants > 4;
+  // What this mode costs, estimated, and what build mode would cost instead.
+  const cost = { tokens: typical(m === "research" ? "research-loop" : m, { variants, judge }), build: typical("build") };
+  if (m === "match") signals.unshift(`design: ${matchSource(text) ?? "none named in the request (ask for the image, URL or Figma frame link)"}`);
+  const decision = { source: m === "match" ? matchSource(text) : null, auto: m === "research" && (words.justBuild || strength === "strong"), mode: m, count, per, variants, ready: m === "full" ? Math.min(4, variants) : variants, judge, reason: why, signals, request: text.slice(0, 300), project, route: r, exists, screen, kind, strength, cost };
+  if (log && !process.env.PALATE_NO_LOG) try {
+    fs.mkdirSync(path.dirname(PLANS_LOG), { recursive: true });
+    fs.appendFileSync(PLANS_LOG, JSON.stringify({ at: new Date().toISOString(), project, name: name ?? null, ...decision }) + "\n");
+  } catch {}
+  return decision;
+}
+
+// The direct path has no brief, so the plan carries the rules: a change in place must keep them too.
+function directRules(d) {
+  const mine = rulesBlock(kindTags({ screen: d.screen, kind: d.kind, route: d.route, words: d.request }), { failures: false, route: d.route, project: d.project });
+  return { line: mine.line, lines: mine.lines.length ? [...mine.lines] : [] };
+}
+
+export function planText(d, { name } = {}) {
+  const tokens = `~${k(d.cost?.tokens)} tokens estimated`;
+  const cheaper = `Cheaper: build mode (--mode build), one build from the user's references and rules, ~${k(d.cost?.build)} tokens instead of ~${k(d.cost?.tokens)}. Offer it to the user.`;
+  const head = {
+    direct: `Direct: ${d.reason}, no variants needed (${tokens}).`,
+    build: `Build: ${d.reason}. One build from your references and rules, then the finishing pass, then you point at what's wrong. No variants (${tokens}).`,
+    direction: `Direction: ${d.reason}. 3 short ideas with rough wireframes first; you pick one, then one build. Nothing is rendered until then (${tokens} for the ideas).`,
+    match: `Match: ${d.reason}. One build to the user's design, then a fidelity check by a fresh judge (${tokens}).`,
+    research: `Research: ${d.reason}. palate looks at competitors and well-crafted pages live, proposes 3 art directions with a signature moment, then one build and the finishing pass (${tokens} for the whole loop; the captures themselves cost no tokens).`,
+    quick: `Quick (variants): ${d.reason}. ${d.variants} sketches, no judge; the user picks (${tokens}).`,
+    full: `Full (variants): ${d.reason}. ${d.variants} sketches (${d.count} directions × ${d.per}), ${d.judge ? "a judge, " : ""}the pick as soon as ${d.ready} are ready (${tokens}).`,
+  }[d.mode];
+  const n = name ?? "<short-name>";
+  const route = d.route ?? "<route>";
+  const next = {
+    direct: [
+      "Next: change it in place (palate search for the component's anatomy if it helps), then one check:",
+      `  palate shoot ${d.route && d.exists ? d.route : "<route>"} --widths 1440 --fold   (fix the biggest problem once, any of your rules it reports failing, and a SYSTEM_DRIFT it names), then palate check.`,
+      "No variants, judge or pick.",
+    ],
+    build: [
+      `Next: palate build "<the job, in the user's words>" --route ${route}   (${d.exists ? "one brief for the real route: your rules, your references with your notes, your taste; the page is changed in place" : "a new page: palate blueprint first (the system, imagery and one archetype per section, checked before code), then one brief per section"})`,
+      `Then the finishing pass on that page: palate shoot ${route} (both widths; its rules and similarity gate must pass), palate states ${route}, palate details ${route}, palate animate ${route} --check if it moves, then palate gate ${route}: the quality floor, judged by fresh subagents (floor checks, a checklist per section, the page beside strong real sites in both orders); repair the one section it names, two rounds at most (~${k(PER.ambition)} tokens, included above). palate critique ${route} only if the user asks for a review.`,
+      `Then palate point ${route}: the user points at what's wrong in the running app and you fix exactly that.`,
+      `To explore first instead: palate direction "<the problem>" (3 ideas, no builds), or --mode quick (2–3 sketches, ~${k(typical("quick", { variants: 3 }))} tokens).`,
+    ],
+    direction: [
+      `Next: palate direction "<the problem, in the user's words>"${d.route ? ` --route ${d.route}` : ""}   (a short brief: answer with 3 ideas and rough wireframes, then the user picks one in their browser)`,
+      `Then palate build "<the job>" --route ${route}: the chosen idea goes into the build brief. No variants.`,
+    ],
+    match: [
+      `Next: palate match ${d.source ? (/\s/.test(d.source) ? `"${d.source}"` : d.source) : "<image | page url | figma frame link>"} --route ${route === "<route>" ? "/" : route}${d.source && /figma\.com/i.test(d.source) ? "   (needs FIGMA_TOKEN; without it, export the frame as PNG and pass the file)" : ""}   (saves the design, measures it, writes the fidelity brief)`,
+      "Then follow the brief: spec.json first (every value observed, inferred or substituted), then the build in this project's stack. No blueprint, archetypes or house-look check: the design is the spec.",
+      `Then palate match --check --route ${route === "<route>" ? "/" : route}, its one judge packet with a fresh subagent, and palate match --answers <dir>: READY, READY WITH SUBSTITUTIONS, NOT READY (fix, two rounds at most) or UNVERIFIED.`,
+    ],
+    research: [
+      `Next, without asking the user: palate_research with the job${d.route ? ` and route ${d.route}` : ""} (CLI: palate research "<job>"). Run the searches it gives with your own web search, then palate_research again with the homepages you found.`,
+      `Then palate_direction with the job and from_research: answer its brief with 3 art directions, then palate_direction with the ideas${JUST_BUILD.test(d.request) ? ' and choose "auto" (the user said to just build it: no picker)' : d.auto ? ": your taste for this kind of screen is strong, so palate picks one itself unless two directions score close (then it opens the picker and says why)" : ": palate picks from taste when it's confident and opens the picker only for a real judgement call"}.`,
+      `Then palate_build with the job${d.route ? ` and route ${d.route}` : ""}: it carries the direction, its signature move and the research. Then the finishing pass and palate point.`,
+      `Cheaper: build mode (--mode build), ~${k(d.cost?.build)} tokens, if the user wants it fast rather than new.`,
+    ],
+    quick: [`Next: palate variants "<the job>" --name ${n}   (${d.variants} sketches), build them in parallel, then palate pick --name ${n}.`, cheaper],
+    full: [`Next: palate variants "<the job>" --name ${n}   (sketches: first screen + centrepiece), build them in parallel, then palate pick --name ${n} --ready ${d.ready}${d.judge ? ` (or palate judge --name ${n} --watch --ready ${d.ready})` : ""}; after the pick, palate build --name ${n}.`, cheaper],
+  }[d.mode];
+  const rules = d.mode === "direct" ? directRules(d) : null;
+  return [...(rules ? [rules.line, ""] : []), head, "", ...(rules?.lines ?? []), "Why:", ...d.signals.map((s) => `- ${s}`), "", ...next, "", "Override with --mode direct|build|direction|research|quick|full|match if the user wants otherwise."].join("\n");
+}

package/src/loop/polish.mjs

@@ -0,0 +1,39 @@
+// `palate polish <route>`: the last step, on the chosen design only. Finds the polish skills this machine
+// has (Jakub Krehel's interface skills, Emil Kowalski's design-engineering skill), shoots the "before",
+// and tells the agent exactly what to run.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { normalizeRoute, shoot } from "../shoot.mjs";
+
+const SKILLS = [
+  { id: "better-interface", who: "Jakub Krehel", install: "npx skills add jakubkrehel/skills", use: "cross-discipline review: accessibility, layout, writing, typography, colour and UI polish (routes to better-ui, better-typography, better-colors, better-layout, better-writing, better-accessibility)" },
+  { id: "better-ui", who: "Jakub Krehel", install: "npx skills add jakubkrehel/skills", use: "exact values for radii, optical alignment, shadows, icon states and motion" },
+  { id: "emil-design-eng", who: "Emil Kowalski", install: "install the emil-design-eng skill", use: "every interaction and animation: what animates and why, duration and easing, press feedback, enter/exit, interruptibility, reduced motion" },
+];
+
+export function findSkill(dir, id) {
+  const roots = [path.join(dir, ".claude", "skills"), path.join(os.homedir(), ".claude", "skills"), path.join(os.homedir(), ".agents", "skills"), path.join(os.homedir(), ".codex", "skills"), path.join(dir, ".agents", "skills")];
+  for (const r of roots) {
+    const f = path.join(r, id, "SKILL.md");
+    if (fs.existsSync(f)) return f;
+  }
+  return null;
+}
+
+export async function polish(dir, rawRoute, opts = {}) {
+  const route = normalizeRoute(rawRoute);
+  const before = await shoot(dir, route, opts);
+  const found = SKILLS.map((s) => ({ ...s, file: findSkill(dir, s.id) }));
+  return [
+    `# Polish ${route}`,
+    "",
+    `Before: ${before.files.filter((f) => f.endsWith("-fold.png")).join(", ")}`,
+    "",
+    "Polish the chosen design only. Keep its idea, layout and content; this is finishing, not redesign. In order:",
+    ...found.map((s, i) => `${i + 1}. ${s.who}'s ${s.id}: ${s.use}.\n   ${s.file ? `Read ${s.file.replace(/\\/g, "/")} and apply it.` : `Not installed (${s.install}). Apply the same checklist from your own knowledge, and tell the user it's missing.`}`),
+    `${found.length + 1}. Typical raw-stage problems: too many font sizes (aim for 4–6 per screen; product mock-ups get their own small scale), text under 12px, mixed radii that don't nest, hover effects on touch devices, animations that fight reduced motion.`,
+    "",
+    `After: run \`palate shoot ${route}\` again and compare with the before shots. Keep a change only if the screenshot is better; revert polish that adds noise.`,
+  ].join("\n");
+}

package/src/loop/research-learn.mjs

@@ -0,0 +1,41 @@
+// palate research → palate taste learn. What the user said about research references (like / dislike, in the
+// direction picker or through palate_research's verdict action) is logged in ~/.palate/taste/research.jsonl with
+// the traits palate measured on each page. The same trait liked or disliked in two different references is a
+// pattern: it becomes a PROPOSED rule for that kind of screen, which waits for the user's OK like every rule palate
+// infers. One verdict is only a ranking signal for the next research. No imports from rules.mjs (it imports this).
+import fs from "node:fs";
+import path from "node:path";
+import { PALATE_HOME } from "../catalog/store.mjs";
+
+const LOG = () => path.join(PALATE_HOME, "taste", "research.jsonl");
+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) : []);
+
+// [{ rule, kinds, source, check, tpl, evidence }] for patterns with at least one verdict newer than `since`.
+export function researchProposals(since = "") {
+  const verdicts = readLines(LOG()).filter((v) => v.kind === "ref-verdict");
+  const groups = new Map();
+  for (const v of verdicts)
+    (v.traits ?? []).forEach((t, i) => {
+      const key = `${v.verdict}|${t}|${v.screen ?? "any"}`;
+      const g = groups.get(key) ?? { verdict: v.verdict, trait: t, label: v.labels?.[i] ?? t.replace(/-/g, " "), screen: v.screen ?? null, list: [] };
+      if (!g.list.some((x) => x.url === v.url)) g.list.push(v);
+      groups.set(key, g);
+    });
+  const out = [];
+  for (const g of groups.values()) {
+    if (g.list.length < 2 || !g.list.some((v) => v.at > since)) continue;
+    // Liked and disliked about as often: no pattern.
+    const other = groups.get(`${g.verdict === "like" ? "dislike" : "like"}|${g.trait}|${g.screen ?? "any"}`);
+    if (other && other.list.length >= g.list.length) continue;
+    const names = g.list.slice(0, 3).map((v) => v.name).join(" and ");
+    const on = g.screen && g.screen !== "other" ? ` on ${g.screen} pages` : "";
+    const kinds = g.screen && g.screen !== "other" ? [g.screen] : ["all"];
+    const evidence = g.list.map((v) => ({ key: `research:${v.research}:${v.ref}:${v.verdict}`, type: "research", said: `${v.verdict === "like" ? "liked" : "disliked"} ${v.name} in research${v.note ? `: ${v.note}` : ""}`, project: v.project, route: null, component: null, kinds, crop: null, at: v.at }));
+    out.push(
+      g.verdict === "dislike"
+        ? { rule: `Avoid ${g.label}${on} (you disliked it in ${names}).`, kinds, source: `research:dislike:${g.trait}`, check: { type: "judge", question: `Is it free of ${g.label}? The user disliked it in ${names}. (present fails)` }, tpl: `research-dislike:${g.trait}:${g.screen ?? "any"}`, evidence }
+        : { rule: `Keep ${g.label}${on} (you liked it in ${names}).`, kinds, source: `research:like:${g.trait}`, check: { type: "judge", question: `Does it have ${g.label}, which the user liked in ${names}?` }, tpl: `research-like:${g.trait}:${g.screen ?? "any"}`, evidence },
+    );
+  }
+  return out;
+}