@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/blueprint.mjs

@@ -0,0 +1,620 @@
+// `palate blueprint "<job>" --route /`: the design decided before any code. A planner (the agent, or a fresh
+// subagent) expands the one-line job into a spec the way a designer would: who it's for and what they feel, the
+// category's truths to keep and its clichés to avoid, a complete system (colours with named roles including a
+// material tone, type roles, layered shadows, the page's own button language), an imagery and material decision for every
+// section, and one section archetype per section from palate's own library (kb/sections), no two neighbours
+// alike. `palate blueprint --file bp.json` checks it against hard structural rules and, when it passes, saves it
+// with tokens palate computes (tokens.css, tokens.tailwind.css). The build then follows it section by section.
+//
+// Why: free generation regresses to the median page (one template for every section, one flat colour, no
+// imagery). Every tool with a real quality floor commits a system and a section plan before code (research:
+// reports/AI design quality floor.md). The blueprint is that commitment, and palate checks it, so the builder
+// can't drift back to the median.
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, sessionDir } from "./common.mjs";
+import { kindWords, tasteFor } from "./craft.mjs";
+import { chosenDirection } from "./direction.mjs";
+import { plan } from "./plan.mjs";
+import { contrast, loadResearch } from "./research.mjs";
+import { kindTags, projectOf, rulesFor } from "./rules.mjs";
+import { projectId, readLayouts } from "./layouts.mjs";
+import { mark } from "./timeline.mjs";
+import { KB_ROOT } from "../paths.mjs";
+import { CTAS, FRAMES, GROUNDS, HEADERS, MIN_DIFFERENT, describePlanned, lookProblems, plannedLook, recentLooks, recordPlanned } from "./lookplan.mjs";
+import { BUTTON_AXES, BUTTON_LANGUAGES, buttonCss, buttonProblems, buttonsFromCta, ctaOf, describeButtons, rankLanguages, resolveButtons } from "./buttons.mjs";
+
+const Sections = await import("../sections.mjs").catch(() => null);
+const Imagery = await import("./imagery.mjs").catch(() => null);
+
+const slash = (p) => String(p).replace(/\\/g, "/");
+const KB_SECTIONS = path.join(process.env.PALATE_KB ?? KB_ROOT, "sections");
+const hexRgb = (h) => (h && /^#[0-9a-f]{6}$/i.test(h) ? [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)) : null);
+const rgbHex = (rgb) => "#" + rgb.map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0")).join("");
+const mix = (a, b, t) => {
+  const [x, y] = [hexRgb(a), hexRgb(b)];
+  return x && y ? rgbHex(x.map((v, i) => v + (y[i] - v) * t)) : a;
+};
+const rgbTriplet = (h) => (hexRgb(h) ?? [0, 0, 0]).join(" ");
+const lightness = (h) => {
+  const x = hexRgb(h);
+  return x ? (0.2126 * x[0] + 0.7152 * x[1] + 0.0722 * x[2]) / 255 : 0;
+};
+// The colour shadows are tinted with: the ink on a light page; on a dark page (light ink) the darkest colour, since
+// a shadow tinted with cream text glows instead of falling.
+export const shadowTint = (c) => {
+  const ink = c.ink ?? "#111111";
+  if (lightness(ink) < 0.5) return ink;
+  return [c.dark, c.bg, c.surface].filter((x) => hexRgb(x)).map((x) => mix(x, "#000000", 0.55)).sort((a, b) => lightness(a) - lightness(b))[0] ?? "#000000";
+};
+const dist = (a, b) => {
+  const [x, y] = [hexRgb(a), hexRgb(b)];
+  return x && y ? Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2]) : 0;
+};
+
+// The colour roles every blueprint names. material: a tone from the product's own world (clay, paper, steel,
+// leaf), used for a band, a texture or an image treatment, so the page is never one flat colour.
+export const COLOUR_ROLES = ["bg", "surface", "ink", "muted", "line", "accent", "on-accent", "material"];
+export const IMAGERY_KINDS = ["photo", "illustration", "texture", "product-ui", "type", "none"];
+export const SURFACES = ["bg", "surface", "material", "dark", "image", "accent"];
+// Kinds of section a marketing page is planned from (kb/sections kinds).
+export const PAGE_KINDS = ["hero", "demo", "features", "story", "gallery", "stats", "process", "pricing", "proof", "closing", "faq", "footer", "comparison", "about", "signup", "docs"];
+// A job that asks a new page for its own look (a campaign, a microsite, a rebrand) gets the new-page brief.
+const NEW_LOOK = /\b(new|different|fresh|distinct|separate) (look|style|brand(ing)?|identity|visual (language|identity))\b|\b(its|their|a) own (look|style|brand(ing)?|identity)\b|\ba (look|style) of its own\b|\brebrand|\bcampaign\b|\bmicrosite\b|\bstand-?alone\b/i;
+const GENERIC_DISPLAY = /^(inter|roboto|arial|helvetica( neue)?|system-ui|ui-sans-serif|open sans|lato|poppins|montserrat|geist)$/i;
+
+const imageryKind = (v) => String(v ?? "").split(":")[0].trim().toLowerCase();
+
+// The archetype menu for the planner: for each kind, the best matches for this product's tags.
+function menu(tags) {
+  if (!Sections?.matchSections) return ["(palate's section library isn't installed: name a layout in plain words for each section, with a shape from: centred-stack, split, full-bleed-media, object-first, editorial-columns, bento, cards-row, list-ruled, stacked-rows, table, marquee, single-statement, timeline, masonry, form-led)"];
+  const out = [];
+  for (const kind of PAGE_KINDS) {
+    const found = Sections.matchSections({ kind, tags, limit: 6 });
+    if (!found.length) continue;
+    out.push(`- **${kind}**: ${found.map((s) => `\`${s.id}\` (${s.shape}; ${s.layout}${s.imagery && s.imagery !== "none" ? `; imagery ${s.imagery}` : ""})`).join(" · ")}`);
+  }
+  return out;
+}
+
+// An existing page as it is now: its first screen, the whole page and one crop per section (the planner decides
+// what to keep, upgrade, remove or add; the gate later checks the result isn't worse than this).
+async function captureCurrent(dir, route, session, { url } = {}) {
+  const { cropSections, findSections, openPage, withBrowser } = await import("../look.mjs");
+  const at = path.join(session, "current");
+  fs.rmSync(at, { recursive: true, force: true });
+  fs.mkdirSync(at, { recursive: true });
+  return withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440, reducedMotion: true });
+    try {
+      const fold = path.join(at, "fold.png");
+      const full = path.join(at, "full.png");
+      await page.screenshot({ path: fold });
+      await page.screenshot({ path: full, fullPage: true });
+      const crops = await cropSections(page, await findSections(page), path.join(at, "sections"), "w1440");
+      // How much the page says: a scaffold (one empty <main>) is new, not an existing page.
+      const text = await page.evaluate(() => (document.body?.innerText ?? "").replace(/\s+/g, " ").trim().length).catch(() => null);
+      // Every string the page shows (text, alt, labels, placeholders), so the gate can say what a change lost.
+      const strings = path.join(at, "strings.json");
+      fs.writeFileSync(strings, JSON.stringify(await page.evaluate(() => {
+        const out = new Set();
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+          const el = n.parentElement;
+          if (!el || el.closest("script,style,noscript,template,[aria-hidden=true]")) continue;
+          const cs = getComputedStyle(el);
+          if (cs.display === "none" || cs.visibility === "hidden") continue;
+          const t = n.textContent.replace(/\s+/g, " ").trim();
+          if (t.length >= 2) out.add(t);
+        }
+        for (const el of document.querySelectorAll("[alt],[aria-label],[placeholder],[title]")) for (const a of ["alt", "aria-label", "placeholder", "title"]) { const v = (el.getAttribute(a) ?? "").trim(); if (v.length >= 2) out.add(v); }
+        return [...out];
+      }).catch(() => []), null, 1));
+      return { fold, full, text, strings, sections: crops.map((c, i) => ({ n: i + 1, name: c.heading || c.name, file: c.file, height: c.box.height })) };
+    } finally {
+      await ctx.close();
+    }
+  });
+}
+
+// The planner's brief: what to decide and how it's checked. An existing route gets the same brief in its
+// existing-page form: the brand is kept, and each current section is kept, upgraded, removed, or a new one added.
+export async function blueprintBrief(dir, job, opts = {}) {
+  return (await blueprintPlan(dir, job, opts)).text;
+}
+
+// A route file is an existing page only when it really has content. A fresh scaffold (the bench template's
+// `<main></main>`, a starter's demo page) or a page that renders at most one section and almost no text is new.
+export const MIN_EXISTING_TEXT = 80;
+export function hasContent(found, current) {
+  if (!found) return false;
+  if (current && !current.error) return (current.sections?.length ?? 0) > 1 || (current.text ?? Infinity) >= MIN_EXISTING_TEXT;
+  return true;
+}
+
+// The brief and the decision behind it: { text, existing } (palate build words its own lines from it).
+export async function blueprintPlan(dir, job, { route, name, direction, url } = {}) {
+  if (!job?.trim()) throw new Error('Usage: palate blueprint "<the job, in the user\'s words>" --route /x');
+  const d = plan(dir, job, { route, name, mode: "build", log: false });
+  const r = d.route ?? "/";
+  name ??= r === "/" ? "home" : r.replace(/^\//, "").replace(/[^a-z0-9]+/gi, "-");
+  const session = sessionDir(dir, name);
+  const { isScaffold, routeFile } = await import("../look.mjs");
+  const found = routeFile(dir, r);
+  // A scaffold is new without rendering it; otherwise the page as it is now decides (a capture that failed on a
+  // real file keeps it existing).
+  const current = found && !isScaffold(found.file) ? await captureCurrent(dir, r, session, { url }).catch((e) => ({ error: e.message })) : null;
+  const exists = Boolean(current) && hasContent(found, current);
+  if (exists) return { text: existingBrief(dir, job, { d, r, name, session, current }), existing: true };
+  // A new page on a site that already has a look (its home page is real): the site's brand, components and buttons
+  // carry over, unless the job asks for a new look. A docs page for palate's own site was planned with a new
+  // system and press quotes.
+  const home = r !== "/" ? routeFile(dir, "/") : null;
+  if (home && !isScaffold(home.file) && !NEW_LOOK.test(job) && !direction) return { text: existingBrief(dir, job, { d, r, name, session, current: null, site: slash(path.relative(dir, home.file)) }), existing: true };
+  const chosen = chosenDirection(dir, { name: direction, route: r });
+  // The research for this page: the direction's, else the newest research in the project.
+  const research = chosen?.research ? loadResearch(dir, chosen.research) : loadResearch(dir, "latest");
+  const u = research?.understanding ?? null;
+  const tags = [...new Set([...(u?.tags ?? []), ...(u?.mood ?? []), ...kindTags({ screen: d.screen, kind: d.kind, route: r, words: job })])];
+  const taste = tasteFor(kindWords(d.screen, d.kind, name), { sections: 1, lean: true, project: projectOf(dir) });
+  const rules = rulesFor(kindTags({ screen: d.screen, kind: d.kind, route: r, words: job }), { route: r, project: projectOf(dir) });
+  const out = path.join(session, "blueprint.json");
+  const starter = chosen?.idea?.starter ?? null;
+  const recent = recentLooks({ excludePid: projectId(dir) });
+  const brief = [
+    `# Blueprint: ${job}`,
+    "",
+    "You are the art director and planner. Decide the whole design before anyone writes code, then write it as JSON. Don't build anything. Every later step follows this: the builder builds it section by section, and an independent judge checks each section against it and against strong real sites.",
+    "",
+    "## Read first",
+    `- The project's README and data (${slash(dir)}): every fact, record and number on the page comes from there.`,
+    research ? `- The research: ${slash(path.join(research.dir, "research.md"))} and its contact sheet (${slash(path.join(research.dir, "contact.png"))}). Look at the screenshots, not only the notes.` : "- No research for this page. Use what you know of the category's best sites, but copy nothing.",
+    chosen ? `- The chosen direction: **${chosen.idea.name}**: ${chosen.idea.summary}${chosen.idea.metaphor ? ` Metaphor: ${chosen.idea.metaphor}` : ""}${chosen.idea.signature ? ` Signature: ${chosen.idea.signature.move}: ${chosen.idea.signature.moment}` : ""}${chosen.note ? ` The user's note: "${chosen.note}"` : ""}` : "- No direction was chosen: decide one yourself (a metaphor from the product's own world, one signature moment).",
+    starter ? `- The direction's starter system (refine it; keep its spirit): ${JSON.stringify(starter)}` : null,
+    "",
+    "## 1. Understand it like a designer (write it down in `spec`)",
+    "- Who uses it, where, on what device, and the one moment they care about (for a booking tool: the message that their thing is ready, not the booking form).",
+    "- Mood: 3–5 words you can defend from the audience and the product, not from the job sentence alone. A craft product is usually warm and tactile; a developer tool precise; a children's charity bright. Don't default to \"minimal\".",
+    "- **Category truths (keep)**: the materials, objects, rituals and words that make this category itself (pottery: clay, glaze, the kiln, hands, the shelf of finished pieces). Competitors using a truth doesn't make it a cliché.",
+    "- **Clichés (avoid)**: specific executions everyone repeats (the stock photo of hands on a wheel, terracotta-on-beige SaaS template, a centred hero over a framed dashboard, three equal feature cards). Avoid the execution, keep the truth.",
+    "",
+    "## 2. The system (`system`)",
+    `- colours, by role: ${COLOUR_ROLES.map((c) => `\`${c}\``).join(", ")}, optionally \`dark\` (a deep band colour) and \`surface-2\`. \`material\` is a tone from the product's world used for at least one band, texture or image treatment. AA contrast: ink and muted on bg and surface ≥ 4.5, accent on bg ≥ 3, on-accent on accent ≥ 4.5.`,
+    "- type: `display`, `body` (Google Fonts / OFL / system only; a display face with character, not Inter/Roboto/Geist), `source`, `scale` (6–8 px sizes), `numbers` (\"tabular body\": numbers, times and prices in the body face with tabular figures), `mono` only if the page shows real code.",
+    "- radius (3–4 values, nested), spacing (unit and scale), motion (one sentence: the character and the one orchestrated moment).",
+    "- Shadows are computed by palate from your colours (layered, ink-tinted): don't specify them. The buttons are yours to decide (2c); palate writes their CSS.",
+    "",
+    "## 2b. The look (`look`): this product's own, not palate's house style",
+    "Decide the page's visual language from the research (what the category's best sites do, the product's materials and truths), and make it unlike palate's recent pages below. palate refuses a look that repeats one of them on too many of these: the ground, texture, the headline's type genre, the hero composition, the header, the call to action's style, how the main object is framed.",
+    `- \`ground\`: ${GROUNDS.join(" | ")} (white is fine; cream paper is not a default). \`groundWhy\`: which truth or reference it comes from.`,
+    "- `texture`: true only if the product's material calls for it (paper for a bindery, speckle for clay); most pages have none.",
+    `- \`header\`: ${HEADERS.join(" | ")} (not always a logo left, links and a pill on the right); \`frame\`: ${FRAMES.join(" | ")} (how the main object or image is presented). (\`cta\` is derived from the buttons below.)`,
+    "- The headline's type genre comes from system.type.display and the hero composition from the hero's archetype: choose them to fit this product, not palate's habit.",
+    "- `influences`: at least two research references (by their R-ids) and the one decision each one informs (`{ \"ref\": \"R2\", \"takes\": \"a full-bleed photograph as the hero, the way the best bakeries lead with the bread\" }`): ideas, never their expression.",
+    ...(recent.length ? ["", `palate's recent pages (yours must differ from each on at least ${MIN_DIFFERENT} of those axes, and its buttons from each page's):`, ...recent.map((x) => `- ${x.project}: ${describePlanned(x.look)}`)] : []),
+    "",
+    "## 2c. The buttons (`look.buttons`): this product's own button language",
+    "A button carries a lot of a brand's voice. palate's recent pages all had the same one (a filled box about 48px tall, a semi-bold sentence-case label, a small radius, a ring and a soft shadow, beside an underlined link) and only the colour changed: don't repeat it. Look at the buttons in the research screenshots, then choose from what the product is (its counter, its tools, its paper, its keyboard), not from habit. palate refuses a language that repeats a recent page's on most of these axes:",
+    ...Object.entries(BUTTON_AXES).map(([k, v]) => `- \`${k}\`: ${v.join(" | ")}`),
+    "Start from one of palate's languages (ranked for this product) and change an axis or two if the research says so, or set `\"language\": \"custom\"` and all six axes:",
+    ...rankLanguages([...tags, ...String(job).toLowerCase().split(/[^a-z]+/)]).map((n) => `- \`${n}\`: ${BUTTON_LANGUAGES[n].words}. Fits ${BUTTON_LANGUAGES[n].fits}.`),
+    `Write it as \`"buttons": { "language": "stamped-tag", "size": "large", "why": "R3's order slips: the action is a ticket" }\`. palate generates \`.btn-primary\` and \`.btn-secondary\` from it (states, focus, contrast and a 44px tap area included). More on each language: ${slash(path.join(KB_SECTIONS, "_buttons.md"))}.`,
+    "",
+    "## 3. Imagery and material (`imagery`)",
+    "- `treatment`: one treatment for every photo on the page (duotone in ink and material, tone-matched, or none).",
+    "- Every section gets an imagery decision (below). Sources, in order: the user's own photos; CC0 museum objects (The Met, Cleveland), or Commons photos with `--sources commons`, found with ONE batch for the whole page: `palate imagery \"<query 1> | <query 2> | …\"` (6 to 12 searches side by side, about a minute; a second batch only for a slot still empty; never one search per call: 60 single searches cost a benchmark page 37 minutes); code-drawn texture (`texture:grain|paper|speckle|halftone|linen`); the product's own UI built in code (`product-ui`); illustration drawn in code; type alone (`type`) for at most two sections. Never stock photos you can't license, never copied images.",
+    "",
+    "## 4. The sections (`sections`, in order)",
+    "Each: `{ \"id\": \"hero\", \"kind\": \"hero\", \"archetype\": \"<id from the menu>\", \"job\": \"what the visitor must understand or do here\", \"content\": \"the real content it carries, from the README\", \"surface\": \"bg|surface|material|dark|image|accent\", \"imagery\": \"photo:<query>|texture:<name>|product-ui|illustration:<what>|type|none\", \"signature\": true|false }`.",
+    "Hard rules palate checks:",
+    "- An archetype from the menu below for every section (it brings the structure, the finish and the checks the judge will use).",
+    "- No two neighbouring sections share a shape; no shape more than twice on the page; at least 3 different shapes.",
+    "- Surfaces vary: at least two surface tones, no more than two neighbours on the same surface, and at least one band of material, dark or image on a marketing page.",
+    "- At least one section with a photo, illustration or texture; at most two sections that are type or none only.",
+    "- Exactly one section carries the signature moment.",
+    "- Only sections the job needs, in an order that tells the story; every one of them gets the same care as the hero.",
+    "",
+    "### The section menu (palate's archetypes, ranked for this product)",
+    ...menu(tags),
+    "",
+    "## 5. A second option for the hero (`alternatives`)",
+    "Name one other hero archetype that would also fit (`\"alternatives\": { \"hero\": \"<id>\" }`). On a full build, both are built and judged side by side.",
+    "",
+    ...(rules.length ? ["## The user's rules this must respect", ...rules.map((x) => `- ${x.id} ${x.rule}`), ""] : []),
+    taste ? `## Whose taste\n${taste.trim()}\n` : "",
+    "## Write it",
+    `JSON to ${slash(out)}: { "product", "spec": { "audience", "moment", "mood": [..], "truths": [..], "cliches": [..] }, "system": { "colours": {..}, "type": {..}, "radius": [..], "spacing": {..}, "motion": "" }, "look": { "ground", "groundWhy", "texture", "header", "frame", "buttons": { "language", "why" }, "influences": [..] }, "imagery": { "treatment": "" }, "sections": [..], "alternatives": { "hero": "" } }`,
+    `Then: \`palate blueprint --file ${slash(out)}\` (CLI) or palate_blueprint with file. It says what fails; fix and run it again until it passes.`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+  const file = path.join(session, "blueprint-brief.md");
+  fs.mkdirSync(session, { recursive: true });
+  fs.writeFileSync(file, brief);
+  fs.writeFileSync(path.join(session, "blueprint-meta.json"), JSON.stringify({ name, job, route: r, screen: d.screen, kind: d.kind, direction: chosen ? chosen.name : null, created: new Date().toISOString() }, null, 1));
+  // The build's timeline starts here (timeline.mjs needs a loop.json; palate build fills it in later).
+  if (!fs.existsSync(path.join(session, "loop.json"))) fs.writeFileSync(path.join(session, "loop.json"), JSON.stringify({ name, job, mode: "build", stage: "blueprint", route: r, created: new Date().toISOString() }, null, 2));
+  fs.rmSync(path.join(session, "events.jsonl"), { force: true });
+  mark(dir, name, "blueprint_brief");
+  const text = [
+    `# Blueprint ${r}: decide the design before code`,
+    "",
+    found ? `${slash(path.relative(dir, found.file))} is only a scaffold so far (nothing on it to keep): this is a new page.` : null,
+    `Brief: ${slash(file)}`,
+    `Plan it yourself or with a fresh subagent: "Read ${slash(file)} and follow it exactly." Then palate blueprint --file ${slash(out)}.`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+  return { text, existing: false };
+}
+
+// The existing-page form of the brief.
+// site: a new page on a site that already has a look (the home page's file): every section is added, in the site's brand.
+function existingBrief(dir, job, { d, r, name, session, current, site = null }) {
+  const research = loadResearch(dir, "latest");
+  const u = research?.understanding ?? null;
+  const tags = [...new Set([...(u?.tags ?? []), ...(u?.mood ?? []), ...kindTags({ screen: d.screen, kind: d.kind, route: r, words: job })])];
+  const taste = tasteFor(kindWords(d.screen, d.kind, name), { sections: 1, lean: true, project: projectOf(dir) });
+  const rules = rulesFor(kindTags({ screen: d.screen, kind: d.kind, route: r, words: job }), { route: r, project: projectOf(dir) });
+  const out = path.join(session, "blueprint.json");
+  const brief = [
+    site ? `# Blueprint (a new page on an existing site): ${job}` : `# Blueprint (an existing page): ${job}`,
+    "",
+    site ? `You are the art director. This is a new page on a site that already has a look: its home page (${site}), header, footer, tokens, type and buttons. The new page belongs to that site: keep all of it and plan only the new page's sections, every one with "action": "add" and an archetype. Reuse the site's own header, footer and components; don't introduce a new system, button language or look. Write it as JSON; don't build anything. The builder then builds each section, and an independent judge checks the result against strong real sites.` : "You are the art director. This page exists. Decide, before anyone writes code, what changes: which sections stay as they are, which are rebuilt to a stronger archetype, which go, and what's added. Keep the project's brand. Write it as JSON; don't build anything. The builder then rebuilds only what you mark, and an independent judge checks the result against strong real sites and against the page as it is now (it may not get worse).",
+    "",
+    ...(site ? [] : ["## The page as it is now (open every image)"]),
+    ...(site ? [] : current?.sections?.length
+      ? [`- First screen: ${slash(current.fold)} · whole page: ${slash(current.full)}`, ...current.sections.map((s) => `- Section ${s.n}: ${s.name} (${s.height}px): ${slash(s.file)}`)]
+      : [`- palate couldn't render it${current?.error ? ` (${current.error})` : ""}: run the dev server or pass --url, then palate blueprint again.`]),
+    "",
+    "## Read first",
+    site ? `- The project's README and data, its home page (${site}), its layout, global styles and shared components (${slash(dir)}): the tokens, faces, header, footer and buttons this page reuses.` : `- The project's README, data and its current code for this route (${slash(dir)}).`,
+    research ? `- Research for this project: ${slash(path.join(research.dir, "research.md"))}.` : "- No research for this project; use what you know of the category's best sites, copying nothing.",
+    "",
+    "## 1. `spec`",
+    site ? "- audience, the moment they care about, mood (3–5 words, defended from the site as it is), **category truths (keep)** and **clichés (avoid)** for this kind of page." : "- audience, the moment they care about, mood (3–5 words, defended), **category truths (keep)** and **clichés (avoid)**, as for a new page; also `problems`: what's below the bar on the current page, section by section, in plain words.",
+    "",
+    "## 2. `system`: keep the brand",
+    "- `\"keep\": true` and the existing tokens by role, as hex where you can read them (`colours`: bg, surface, ink, muted, line, accent, on-accent, and material if the page has one), plus `type` (the faces already in use). palate computes the finish tokens (layered shadows) from these; the project keeps its own buttons. Change the brand only if the job asks for a rebrand (then `\"keep\": false` and a full system, as for a new page).",
+    "",
+    "## 3. `sections`, in the page's new order",
+    "Each: `{ \"id\", \"kind\", \"action\": \"keep|upgrade|remove|add\", \"current\": <section number now, or null for add>, \"archetype\": \"<id>\" (required for upgrade and add), \"job\", \"content\", \"surface\", \"imagery\", \"why\": \"what's below the bar now, or why it stays\" }`.",
+    "- Upgrade a section only for a reason you can name (the judge will compare before and after). Keep what already works exactly as it is.",
+    "- Add only what the request asks for: one section per thing it names. Content it asks for (answers to buyers' questions, fees, a trial note) goes inside that section unless the request names another section. Never add an ending, a footer or sections it doesn't name: name them to the user as suggestions instead.",
+    "- The rebuilt page still follows the variety rules: no two neighbours with the same shape, surfaces that vary, real material somewhere.",
+    "",
+    "### The section menu (palate's archetypes, ranked for this product)",
+    ...menu(tags),
+    "",
+    ...(rules.length ? ["## The user's rules this must respect", ...rules.map((x) => `- ${x.id} ${x.rule}`), ""] : []),
+    taste ? `## Whose taste\n${taste.trim()}\n` : "",
+    "## Write it",
+    ...(site ? ["## 4. `copy`: new", "Every string is new and comes from the project's README, data and code (commands, versions, prices): `\"copy\": \"edit\"`."] : ["## 4. `copy`: locked by default", "palate captured every string the page shows now. `\"copy\": \"keep\"` (the default): every one stays word for word, and the gate fails a change that loses one. `\"edit\"` only when the job asks for new copy; new labels are listed either way, for the hand-off."]),
+    "",
+    `JSON to ${slash(out)}: { "mode": "existing", "product", "spec": {..}, "system": { "keep": true, "colours": {..}, "type": {..} }, "copy": "${site ? "edit" : "keep"}", "imagery": { "treatment": "" }, "sections": [..] }`,
+    `Then: \`palate blueprint --file ${slash(out)}\` until it passes, then palate build again with the same job.`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+  const file = path.join(session, "blueprint-brief.md");
+  fs.mkdirSync(session, { recursive: true });
+  fs.writeFileSync(file, brief);
+  fs.writeFileSync(path.join(session, "blueprint-meta.json"), JSON.stringify({ name, job, route: r, screen: d.screen, kind: d.kind, existing: true, site: site ?? undefined, before: current?.full ? { fold: current.fold, full: current.full, strings: current.strings ?? null } : null, created: new Date().toISOString() }, null, 1));
+  if (!fs.existsSync(path.join(session, "loop.json"))) fs.writeFileSync(path.join(session, "loop.json"), JSON.stringify({ name, job, mode: "build", stage: "blueprint", route: r, created: new Date().toISOString() }, null, 2));
+  fs.rmSync(path.join(session, "events.jsonl"), { force: true });
+  mark(dir, name, "blueprint_brief");
+  return [site ? `# Blueprint ${r} (a new page on the site, in its own look): decide the sections before code` : `# Blueprint ${r} (existing page): decide what changes before code`, "", `Brief: ${slash(file)}`, `Plan it yourself or with a fresh subagent: "Read ${slash(file)} and follow it exactly." Then palate blueprint --file ${slash(out)}.`].join("\n");
+}
+
+// The hard checks on a blueprint. Returns { ok, problems, warnings }.
+// others: layout records of pages in the user's other projects (readLayouts), to catch a repeated look.
+// recent: palate's recent looks in other projects (lookplan.recentLooks), for the house-look check.
+export function validateBlueprint(bp, { screen = "landing", others = [], recent = [], research = false, tags = [] } = {}) {
+  const problems = [];
+  const warnings = [];
+  if (!bp || typeof bp !== "object") return { ok: false, problems: ["not a JSON object"], warnings };
+  const spec = bp.spec ?? {};
+  if ((spec.mood ?? []).length < 2) problems.push("spec.mood: 3–5 words defended from the audience and product");
+  if ((spec.truths ?? []).length < 2) problems.push("spec.truths: at least two category truths to keep");
+  if ((spec.cliches ?? []).length < 2) problems.push("spec.cliches: at least two specific executions to avoid");
+  if (!spec.moment) warnings.push("spec.moment: the one moment the audience cares about");
+  // An existing page keeps its brand: its colours and faces are the project's, so they aren't held to the new-page
+  // system rules (only checked where given), and only the sections it rebuilds need an archetype.
+  const existing = bp.mode === "existing";
+  const keep = existing && bp.system?.keep !== false;
+  // System
+  const sys = bp.system ?? {};
+  const c = sys.colours ?? sys.colors ?? {};
+  if (!keep) for (const k of COLOUR_ROLES) if (!hexRgb(c[k])) problems.push(`system.colours.${k} must be a hex colour (#rrggbb)`);
+  const need = (fg, bg, min) => {
+    const r = c[fg] && c[bg] ? contrast(c[fg], c[bg]) : null;
+    if (r != null && r < min) problems.push(`contrast: ${fg} ${c[fg]} on ${bg} ${c[bg]} is ${r}:1, needs ${min}:1`);
+  };
+  need("ink", "bg", 4.5);
+  need("muted", "bg", 4.5);
+  need("ink", "surface", 4.5);
+  need("muted", "surface", 4.5);
+  need("accent", "bg", 3);
+  need("on-accent", "accent", 4.5);
+  if (c.dark) need("bg", "dark", 4.5);
+  if (hexRgb(c.bg) && hexRgb(c.surface) && dist(c.bg, c.surface) < 6) warnings.push("bg and surface are almost the same colour: the page will read as one flat tone");
+  if (hexRgb(c.material) && hexRgb(c.bg) && dist(c.material, c.bg) < 18) problems.push("material is too close to bg: it has to read as its own band or texture");
+  const t = sys.type ?? {};
+  if (!keep) {
+  if (!t.display || !t.body) problems.push("system.type needs display and body");
+  if (t.display && GENERIC_DISPLAY.test(String(t.display).trim())) problems.push(`system.type.display ${t.display} is a default face: choose one with character`);
+  if (!/^(google-fonts|ofl|system)$/i.test(t.source ?? "")) problems.push('system.type.source must be "google-fonts", "ofl" or "system"');
+  if (!Array.isArray(t.scale) || t.scale.length < 5) problems.push("system.type.scale: 6–8 sizes in px");
+  if (t.mono && !/code/i.test(String(t.monoFor ?? t.mono_for ?? ""))) warnings.push("system.type.mono: only for real code (say monoFor: \"code\"); numbers use the body face with tabular figures");
+  if (!Array.isArray(sys.radius) || sys.radius.length < 2) problems.push("system.radius: 3–4 values");
+  if (!sys.spacing) problems.push("system.spacing: unit and scale");
+  if (!sys.motion) warnings.push("system.motion: one sentence");
+  }
+  // Another project's look: the same display face and nearly the same accent as a page made elsewhere.
+  for (const o of keep ? [] : others) {
+    const fonts = (o.style?.fonts ?? []).map((f) => String(f).toLowerCase());
+    const sameFace = t.display && fonts.includes(String(t.display).toLowerCase());
+    const nearAccent = hexRgb(o.style?.accent) && hexRgb(c.accent) && dist(o.style.accent, c.accent) < 40;
+    if (sameFace && nearAccent) {
+      problems.push(`the display face ${t.display} and accent ${c.accent} repeat ${o.project} ${o.route ?? ""} (${o.style.accent}): this product needs its own`);
+      break;
+    }
+  }
+  // Sections
+  const s = Array.isArray(bp.sections) ? bp.sections : [];
+  const marketing = !/^(app|dashboard|settings|table|team)$/.test(screen);
+  if (s.length < (marketing && !existing ? 4 : 1)) problems.push(`sections: ${s.length}; a ${screen} page needs at least ${marketing ? 4 : 1}`);
+  if (existing) {
+    s.forEach((x, i) => {
+      if (!["keep", "upgrade", "remove", "add"].includes(x.action)) problems.push(`sections[${i}] (${x.id ?? "?"}): action must be keep, upgrade, remove or add`);
+    });
+    if (!s.some((x) => x.action === "upgrade" || x.action === "add" || x.action === "remove")) problems.push("nothing changes: mark at least one section upgrade, add or remove (or this is a direct fix, not a build)");
+  }
+  // On an existing page, sections that stay as they are have no archetype; removed ones aren't on the new page.
+  const changing = (x) => !existing || x.action === "upgrade" || x.action === "add";
+  const lib = Sections?.getSection ? (id) => Sections.getSection(id) : null;
+  const shapes = [];
+  s.forEach((x, i) => {
+    const at = `sections[${i}] (${x.id ?? x.kind ?? "?"})`;
+    if (!x.kind) problems.push(`${at}: kind missing`);
+    if (existing && x.action === "remove") return shapes.push(null);
+    if (!x.job && changing(x)) problems.push(`${at}: job missing (what the visitor must understand or do here)`);
+    if (!x.content) warnings.push(`${at}: content missing (the real content it carries)`);
+    let shape = x.shape ?? null;
+    if (!changing(x)) {
+      shapes.push(x.archetype && lib?.(x.archetype) ? lib(x.archetype).shape : null);
+      return;
+    }
+    if (lib) {
+      const a = x.archetype ? lib(x.archetype) : null;
+      if (!a) problems.push(`${at}: archetype ${x.archetype ? `"${x.archetype}" isn't in the library` : "missing"}: pick one from the menu`);
+      else {
+        shape = a.shape;
+        if (x.kind && a.kind !== x.kind && !(x.kind === "footer" && a.kind === "footer")) warnings.push(`${at}: archetype ${a.id} is a ${a.kind} archetype, section kind is ${x.kind}`);
+      }
+    } else if (!shape) problems.push(`${at}: shape missing`);
+    shapes.push(shape);
+    if (!SURFACES.includes(x.surface)) problems.push(`${at}: surface must be one of ${SURFACES.join(", ")}`);
+    if (!IMAGERY_KINDS.includes(imageryKind(x.imagery))) problems.push(`${at}: imagery must start with one of ${IMAGERY_KINDS.join(", ")} (e.g. "photo:stoneware bowl", "texture:speckle")`);
+  });
+  // Variety
+  const real = s.map((x, i) => ({ x, shape: shapes[i] })).filter((y) => y.x.kind !== "footer" && !(existing && y.x.action === "remove"));
+  for (let i = 1; i < real.length; i++) if (real[i].shape && real[i].shape === real[i - 1].shape) problems.push(`sections ${real[i - 1].x.id} and ${real[i].x.id} are neighbours with the same shape (${real[i].shape}): change one`);
+  const counts = {};
+  for (const y of real) if (y.shape) counts[y.shape] = (counts[y.shape] ?? 0) + 1;
+  for (const [k, n] of Object.entries(counts)) if (n > 2) problems.push(`shape ${k} is used ${n} times; at most twice`);
+  if (marketing && !existing && Object.keys(counts).length < Math.min(3, real.length)) problems.push(`only ${Object.keys(counts).length} different shapes; at least 3`);
+  const surf = s.filter((x) => !(existing && x.action === "remove")).map((x) => x.surface);
+  // On an existing page the plan can't see every current section's ground and material: those become warnings.
+  // On an existing page the plan can't see the kept sections' grounds and material: those checks don't run there.
+  const soft = (msg) => (existing ? null : problems.push(msg));
+  if (marketing && new Set(surf.filter(Boolean)).size < 2) soft("every section is on the same surface: at least two tones");
+  for (let i = 2; i < surf.length; i++) if (surf[i] && surf[i] === surf[i - 1] && surf[i] === surf[i - 2]) problems.push(`three neighbours on the ${surf[i]} surface (${s[i - 2].id}, ${s[i - 1].id}, ${s[i].id})`);
+  if (marketing && !surf.some((v) => ["material", "dark", "image"].includes(v))) soft("no band of material, dark or image: the page will be one flat colour");
+  const kinds = s.filter((x) => !(existing && x.action === "remove")).map((x) => imageryKind(x.imagery));
+  if (marketing && !kinds.some((k) => ["photo", "illustration", "texture"].includes(k))) soft("no section has a photo, illustration or texture: the page has no material");
+  if (kinds.filter((k) => k === "type" || k === "none").length > 2) problems.push("more than two sections are type or none only");
+  const sig = s.filter((x) => x.signature);
+  if (marketing && !existing && sig.length !== 1) problems.push(`exactly one section carries the signature moment (now ${sig.length})`);
+  if (bp.alternatives?.hero && lib && !lib(bp.alternatives.hero)) warnings.push(`alternatives.hero "${bp.alternatives.hero}" isn't in the library`);
+  // The look: this product's own, not palate's house style (new pages and rebrands; a kept brand is the brand's).
+  if (!keep) {
+    const lk = bp.look ?? {};
+    if (!GROUNDS.includes(lk.ground)) problems.push(`look.ground: one of ${GROUNDS.join(", ")}, decided from the research`);
+    if (typeof lk.texture !== "boolean") problems.push("look.texture: true or false (true only when the product's material calls for it)");
+    if (!HEADERS.includes(lk.header)) problems.push(`look.header: one of ${HEADERS.join(", ")}`);
+    // The buttons: a language from the library (or custom), required; the coarse cta follows from it.
+    const bt = buttonProblems(lk.buttons);
+    problems.push(...bt.problems);
+    warnings.push(...bt.warnings);
+    if (lk.cta != null && !CTAS.includes(lk.cta)) problems.push(`look.cta: one of ${CTAS.join(", ")} (or leave it out: palate derives it from look.buttons)`);
+    else if (lk.cta && lk.buttons && !bt.problems.length && ctaOf(lk.buttons) !== lk.cta) warnings.push(`look.cta says ${lk.cta} but the buttons are ${ctaOf(lk.buttons)}: palate goes by the buttons`);
+    if (!FRAMES.includes(lk.frame)) problems.push(`look.frame: one of ${FRAMES.join(", ")}`);
+    const infl = (lk.influences ?? []).filter((x) => x?.ref && x?.takes);
+    if (research && infl.length < 2) problems.push("look.influences: at least two research references (R-ids) and the decision each informs");
+    if (!research && infl.length < 1) warnings.push("look.influences: name the sites or traditions this look learns from");
+    const hexOk = /^#[0-9a-f]{6}$/i.test(c.bg ?? "");
+    if (hexOk && lk.ground && !["photo", "colour"].includes(lk.ground)) {
+      const g = plannedLook({ system: { colours: { bg: c.bg } } }).ground;
+      if (g && g !== lk.ground && !(lk.ground.startsWith("light") && g.startsWith("light")) && !(lk.ground === "white" && g.startsWith("light"))) warnings.push(`look.ground says ${lk.ground} but colours.bg ${c.bg} reads as ${g}`);
+    }
+    for (const p of lookProblems(plannedLook(bp, { getSection: Sections?.getSection }), recent, { tags })) problems.push(p.line);
+  }
+  return { ok: !problems.length, problems, warnings };
+}
+
+// Finishing values palate derives from the colours, so every build starts from the same craft: layered shadows
+// tinted with the ink, and the primary button's gradient, inner highlight and ring.
+export function finishTokens(c) {
+  const ink = shadowTint(c);
+  const accent = c.accent ?? "#333333";
+  return {
+    "accent-hi": mix(accent, "#ffffff", 0.12),
+    "accent-lo": mix(accent, "#000000", 0.18),
+    "accent-ring": mix(accent, "#000000", 0.32),
+    "shadow-raised": `0 1px 1px rgb(${rgbTriplet(ink)} / 0.04), 0 2px 4px -1px rgb(${rgbTriplet(ink)} / 0.06), 0 12px 24px -8px rgb(${rgbTriplet(ink)} / 0.12)`,
+    "shadow-float": `0 1px 2px rgb(${rgbTriplet(ink)} / 0.05), 0 8px 16px -4px rgb(${rgbTriplet(ink)} / 0.08), 0 32px 64px -16px rgb(${rgbTriplet(ink)} / 0.18)`,
+    "button-primary": `linear-gradient(180deg, ${mix(accent, "#ffffff", 0.12)}, ${accent})`,
+    "button-inset": `inset 0 1px 0 rgb(255 255 255 / 0.22), 0 0 0 1px ${mix(accent, "#000000", 0.32)}, 0 1px 2px rgb(${rgbTriplet(ink)} / 0.18)`,
+    "hairline": `rgb(${rgbTriplet(c.ink ?? "#111111")} / 0.10)`, // lines follow the text colour, light on a dark page
+  };
+}
+
+const fam = (f, fallback) => (f ? `"${f}", ${fallback}` : fallback);
+// Display faces that are serifs (their fallback is a serif; everything else falls back to sans).
+const SERIF_FACE = /serif|fraunces|gloock|playfair|garamond|caslon|baskerville|lora|merriweather|cormorant|newsreader|spectral|crimson|bodoni|didot|literata|source serif|young serif|dm serif|instrument serif|eb garamond|libre|domine|zilla|roboto slab|bitter|vollkorn|alegreya(?! sans)|petrona|gelasio|fraunces|recoleta|tiempos/i;
+// tokens.css (plain custom properties) and tokens.tailwind.css (Tailwind v4 @theme: the same names become
+// utilities like bg-surface, text-ink, font-display, shadow-raised).
+// opts.flatButtons: kept for callers (no button is a gradient now). opts.rules: the user's rule texts, which win
+// over the button language (no pills, no uppercase…).
+export function blueprintTokens(bp, { flatButtons = false, rules = [] } = {}) {
+  const sys = bp.system ?? {};
+  const c = sys.colours ?? sys.colors ?? {};
+  const t = sys.type ?? {};
+  const f = finishTokens(c);
+  const radius = (sys.radius ?? []).map((r, i) => [`--radius-${["sm", "md", "lg", "xl"][i] ?? i}`, String(r).replace(/^(\d+)$/, "$1px")]);
+  const scale = (t.scale ?? []).map((px, i) => [`--text-step-${i + 1}`, `${px}px`]);
+  const vars = [
+    ...Object.entries(c).map(([k, v]) => [`--color-${k}`, v]),
+    ["--font-display", fam(t.display, SERIF_FACE.test(String(t.display ?? "")) ? "ui-serif, Georgia, serif" : "ui-sans-serif, system-ui, sans-serif")],
+    ["--font-body", fam(t.body, "ui-sans-serif, system-ui, sans-serif")],
+    ...(t.mono ? [["--font-mono", fam(t.mono, "ui-monospace, monospace")]] : []),
+    ...scale,
+    ...radius,
+    ["--spacing-unit", `${sys.spacing?.unit ?? 8}px`],
+    ["--shadow-raised", f["shadow-raised"]],
+    ["--shadow-float", f["shadow-float"]],
+    ["--color-accent-hi", f["accent-hi"]],
+    ["--color-accent-lo", f["accent-lo"]],
+    ["--color-accent-ring", f["accent-ring"]],
+    ["--color-hairline", f.hairline],
+  ];
+  const body = vars.map(([k, v]) => `  ${k}: ${v};`).join("\n");
+  // The names kb/sections/_finish.md and every archetype use (--ink, --paper, --brand, --s-7, --r-lg,
+  // --shadow-2, --hairline, --section …), pointed at this blueprint's values.
+  const sc = sys.spacing?.scale?.length ? sys.spacing.scale : [4, 8, 12, 16, 24, 32, 48, 64, 96, 128];
+  const ts = t.scale ?? [];
+  const tAt = (i) => (ts[i] != null ? `${ts[i]}px` : null);
+  const r = sys.radius ?? [];
+  const aliases = [
+    ["--ink", "var(--color-ink)"],
+    ["--ink-2", "var(--color-muted)"],
+    // Tertiary text is the muted colour: the blueprint check holds it to AA (a mix toward bg fell under 4.5:1).
+    ["--ink-3", "var(--color-muted)"],
+    ["--paper", "var(--color-bg)"],
+    ["--paper-2", c["surface-2"] ? "var(--color-surface-2)" : "var(--color-surface)"],
+    ["--surface", "var(--color-surface)"],
+    ["--material", "var(--color-material)"],
+    ["--brand", "var(--color-accent)"],
+    ["--on-brand", "var(--color-on-accent)"],
+    ["--focus", "var(--color-accent)"],
+    ...sc.slice(0, 10).map((v, i) => [`--s-${i + 1}`, `${v}px`]),
+    ["--t-caption", tAt(0)],
+    ["--t-small", tAt(1)],
+    ["--t-body", tAt(2)],
+    ["--t-lead", tAt(3)],
+    ["--t-h3", tAt(4)],
+    ["--t-h2", tAt(ts.length - 2) ?? tAt(5)],
+    ["--t-display", tAt(ts.length - 1)],
+    ["--r-sm", r[0] != null ? String(r[0]).replace(/^(\d+)$/, "$1px") : null],
+    ["--r-md", r[1] != null ? String(r[1]).replace(/^(\d+)$/, "$1px") : null],
+    ["--r-lg", r[2] != null ? String(r[2]).replace(/^(\d+)$/, "$1px") : r[1] != null ? String(r[1]).replace(/^(\d+)$/, "$1px") : null],
+    ["--r-pill", "999px"],
+    ["--sh-tint", shadowTint(c)],
+    ["--shadow-1", "0 0 0 1px color-mix(in oklab, var(--sh-tint) 7%, transparent), 0 1px 2px color-mix(in oklab, var(--sh-tint) 8%, transparent), 0 2px 6px -2px color-mix(in oklab, var(--sh-tint) 8%, transparent)"],
+    ["--shadow-2", "0 0 0 1px color-mix(in oklab, var(--sh-tint) 7%, transparent), 0 2px 4px -2px color-mix(in oklab, var(--sh-tint) 12%, transparent), 0 16px 32px -12px color-mix(in oklab, var(--sh-tint) 18%, transparent)"],
+    ["--shadow-3", "0 0 0 1px color-mix(in oklab, var(--sh-tint) 8%, transparent), 0 4px 8px -4px color-mix(in oklab, var(--sh-tint) 14%, transparent), 0 32px 64px -16px color-mix(in oklab, var(--sh-tint) 26%, transparent)"],
+    ["--hairline", "color-mix(in oklab, var(--color-ink) 12%, transparent)"],
+    ["--hairline-strong", "color-mix(in oklab, var(--color-ink) 22%, transparent)"],
+    ["--section", "clamp(72px, 7vw + 24px, 128px)"],
+    ["--section-tight", "clamp(48px, 4vw + 16px, 80px)"],
+    ["--container", "1240px"],
+    ["--gutter", "24px"],
+    ["--page-x", "clamp(16px, 4vw, 48px)"],
+  ].filter(([, v]) => v != null);
+  const aliasBlock = `/* The names kb/sections/_finish.md and the section archetypes use. */\n:root {\n${aliases.map(([k, v]) => `  ${k}: ${v};`).join("\n")}\n}`;
+  // The buttons: the plan's own language (buttons.mjs), never one anatomy for every product. An older plan with
+  // only a cta gets the language it implies; an existing page that keeps its brand keeps its own buttons.
+  const lang = pageButtons(bp);
+  const helpers = [
+    lang ? buttonCss(lang, c, { rules }).css : "/* Buttons: the project's own (the plan keeps the brand). */",
+    "/* Numbers, times and prices: the body face with tabular figures, never monospace. */",
+    ".num { font-variant-numeric: tabular-nums; font-feature-settings: \"tnum\" 1; }",
+  ].join("\n");
+  return {
+    css: `/* palate blueprint tokens: generated from blueprint.json; edit the blueprint, not this file. */\n:root {\n${body}\n}\n\n${aliasBlock}\n\n${helpers}\n`,
+    tailwind: `/* palate blueprint tokens for Tailwind v4: @import this after "tailwindcss". Generated; edit the blueprint. */\n@theme {\n${body}\n}\n\n${aliasBlock}\n\n${helpers}\n`,
+  };
+}
+
+// The page's button language: look.buttons, else what an older plan's cta implies (on top of plain-solid), else
+// plain-solid for a new page; null for an existing page that keeps its brand.
+export function pageButtons(bp) {
+  const lk = bp?.look ?? {};
+  if (lk.buttons) return resolveButtons(lk.buttons);
+  if (bp?.mode === "existing" && bp.system?.keep !== false) return null;
+  const fromCta = CTAS.includes(lk.cta) ? buttonsFromCta(lk.cta) : null;
+  return { ...resolveButtons("plain-solid"), ...(fromCta ?? {}), language: fromCta ? "custom" : "plain-solid", derived: Boolean(fromCta) };
+}
+
+// The saved blueprint for a route (or name), or null.
+export function loadBlueprint(dir, { name, route } = {}) {
+  const tries = name ? [name] : route ? [route === "/" ? "home" : String(route).replace(/^\//, "").replace(/[^a-z0-9]+/gi, "-")] : ["home"];
+  for (const n of tries) {
+    const f = path.join(dir, ".palate", "variants", n, "blueprint.json");
+    const bp = readJson(f, null);
+    if (bp?.passed) return { ...bp, file: f, session: path.dirname(f) };
+  }
+  return null;
+}
+
+// Checks a blueprint file and, when it passes, saves it with its tokens.
+export function saveBlueprint(dir, file, { name } = {}) {
+  const src = path.resolve(file);
+  let bp;
+  try {
+    bp = JSON.parse(fs.readFileSync(src, "utf8"));
+  } catch (e) {
+    throw new Error(`Can't read ${slash(src)}: ${e.message}`);
+  }
+  const session = name ? sessionDir(dir, name) : path.dirname(src);
+  const meta = readJson(path.join(session, "blueprint-meta.json"), {});
+  const pid = projectId(dir);
+  const others = readLayouts().filter((h) => h.pid !== pid && h.style);
+  const recent = recentLooks({ excludePid: pid });
+  const res = loadResearch(dir, "latest");
+  const v = validateBlueprint(bp, { screen: meta.screen ?? "landing", others, recent, research: Boolean(res), tags: [...(res?.understanding?.tags ?? []), ...(res?.understanding?.mood ?? [])] });
+  const head = `# Blueprint ${meta.route ?? ""}: ${v.ok ? "passes" : "FAILS"}`;
+  if (!v.ok) return [head, "", "Fix these, then run it again:", ...v.problems.map((p) => `- ✗ ${p}`), ...v.warnings.map((w) => `- ! ${w}`)].join("\n");
+  // Tokens when the plan names colours by role (an existing page that keeps its brand may name only some).
+  const cc = bp.system?.colours ?? bp.system?.colors ?? {};
+  const withTokens = Boolean(hexRgb(cc.ink) && hexRgb(cc.accent));
+  if (withTokens) {
+    // The user's rules win over palate's own finish (e.g. a kept "no gradient buttons" rule).
+    const userRules = rulesFor(["all", "landing", "marketing"], { route: meta.route ?? "/", project: projectOf(dir) });
+    const flatButtons = userRules.some((r) => r.check?.metric === "gradientButtons" || /gradient/i.test(r.rule ?? "") && /button|cta/i.test(r.rule ?? ""));
+    const tok = blueprintTokens(bp, { flatButtons, rules: userRules.map((r) => r.rule ?? "") });
+    fs.writeFileSync(path.join(session, "tokens.css"), tok.css);
+    fs.writeFileSync(path.join(session, "tokens.tailwind.css"), tok.tailwind);
+  }
+  const saved = { ...bp, passed: true, route: meta.route ?? bp.route ?? "/", job: meta.job ?? bp.job, before: meta.before ?? null, at: new Date().toISOString() };
+  fs.writeFileSync(path.join(session, "blueprint.json"), JSON.stringify(saved, null, 1));
+  // palate remembers the look it planned, so the next product's plan has to differ from it.
+  if (!(bp.mode === "existing" && bp.system?.keep !== false)) recordPlanned(dir, saved.route, plannedLook(bp, { getSection: Sections?.getSection }), { pid, bench: fs.existsSync(path.join(dir, ".palate", "bench.json")) });
+  mark(dir, path.basename(session), "blueprint_saved");
+  const lines = [
+    head,
+    "",
+    `- Mood: ${(bp.spec?.mood ?? []).join(", ")} · keep: ${(bp.spec?.truths ?? []).join("; ")} · avoid: ${(bp.spec?.cliches ?? []).join("; ")}`,
+    bp.mode === "existing" && bp.system?.keep !== false ? "- System: the project's own brand, kept." : `- System: ${bp.system?.type?.display} / ${bp.system?.type?.body}; accent ${cc.accent}, material ${cc.material}.`,
+    bp.look?.buttons ? `- Buttons: ${describeButtons(pageButtons(bp))} (.btn-primary and .btn-secondary in the tokens).` : null,
+    `- Sections: ${bp.sections.map((s) => `${s.id} (${bp.mode === "existing" ? `${s.action}${s.archetype ? ` → ${s.archetype}` : ""}` : `${s.archetype ?? s.shape}, ${s.surface}, ${s.imagery}${s.signature ? ", signature" : ""}`})`).join(" → ")}`,
+    ...v.warnings.map((w) => `- ! ${w}`),
+    "",
+    withTokens ? `Tokens: ${slash(path.join(session, "tokens.css"))} (plain CSS) and ${slash(path.join(session, "tokens.tailwind.css"))} (Tailwind v4 @theme).` : "Tokens: the project's own (no colours by role in the plan, so palate wrote none).",
+    ...(Imagery?.imageryPlanLines ? ["", "## Imagery to fetch before building", ...[].concat(Imagery.imageryPlanLines(bp.sections.filter((s) => bp.mode !== "existing" || s.action === "upgrade" || s.action === "add").map((s) => ({ section: s.id, imagery: s.imagery }))))] : []),
+    "",
+    `Next: palate build "${meta.job ?? bp.job ?? "<the job>"}" --route ${meta.route ?? "/"}: it builds this blueprint section by section.`,
+  ];
+  return lines.filter((l) => l != null).join("\n");
+}