@palate/cli 0.0.0-stage → 0.0.1

package/src/check.mjs

@@ -0,0 +1,93 @@
+// `palate check`: scans the lines you changed (git diff plus new files) for generated-UI tells and
+// for drift from the project's own system. Signals to fix or justify, not a score.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { finishBlockers } from "./loop/similar.mjs";
+import { copyReport, lintFiles } from "./copy.mjs";
+
+const CHECKS = [
+  ["transition-all", /\btransition-all\b|transition:\s*all\b/, "Animate named properties (transform, opacity, colour), not `all`."],
+  ["gradient-text", /bg-clip-text|background-clip:\s*text/, "Gradient text reads as generated. Use weight, size or one accent colour."],
+  ["purple-gradient", /\b(from|via|to)-(purple|violet|indigo|fuchsia)-\d+/, "Purple/indigo gradients are the default AI look. Use the project's own colours."],
+  ["scale-zero", /\bscale-0\b|scale\(0\)/, "Enter from scale(0.95) and opacity 0, not scale(0)."],
+  ["pulse-bounce", /\banimate-(pulse|bounce|ping)\b/, "Pulsing or bouncing implies live activity. Only use it for something actually live."],
+  ["glass", /\bbackdrop-blur|backdrop-filter:\s*blur/, "Glass blur: only where content scrolls under a bar."],
+  ["emoji", /\p{Extended_Pictographic}/u, "Emoji in UI copy. Use icons from the project's icon set or plain words."],
+  ["em-dash", /—/, "Em dashes in UI copy read as generated. Use a comma, colon or full stop."],
+  ["placeholder", /lorem ipsum|placeholder\.com|picsum\.photos/i, "Placeholder content. Use the real data."],
+  ["tnum-wide", /fontFeatureSettings:\s*["']['"]?tnum|font-feature-settings:\s*["']?tnum/, "Tabular figures set on a wide scope. Put tabular-nums on number cells only."],
+  ["google-font", /fonts\.googleapis\.com|@fontsource/, "New web font. Only if the project has no type system or the brief asks for one; the Decision Record must say why."],
+  ["hex", /#[0-9a-fA-F]{3,8}\b(?![0-9a-zA-Z-])|\brgba?\(\s*\d/, "Hard-coded colour. Use a token, or add one to the token file if it is genuinely new."],
+];
+
+// When a design system is applied (.palate/system.md), everything must go through its roles and tokens.
+const SYSTEM_CHECKS = [
+  ["type-off-scale", /\btext-(xs|sm|base|lg|[2-9]?xl)\b|\btext-\[\d/, "Type outside the system's roles. Use text-display, text-h1 … text-caption (see .palate/system.md)."],
+  ["arbitrary-value", /\b(rounded|tracking|leading|font|shadow|p[xytrbl]?|m[xytrbl]?|gap|w|h)-\[[^\]]*\d/, "Arbitrary value. Use the system's scale (radii, spacing, roles) or add a token."],
+];
+const HAIRLINE_SHADOW = ["shadow-in-hairline-system", /\bshadow-(sm|md|lg|xl|2xl)\b/, "This system gets depth from hairlines and stepped surfaces; shadows only on overlays."];
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, { cwd, encoding: "utf8" });
+  return r.stdout ?? "";
+}
+
+// The findings as data: { findings: [{ id, file, line, text, fix }], blockers: [string] }. `only` limits them to
+// those files (the guard passes the files changed in this session).
+export function checkFindings(dir, { only } = {}) {
+  const tokenFiles = new Set(["src/index.css", "src/styles/tokens.css", "app/globals.css", "styles/globals.css"]);
+  const added = new Map();
+  let file = null;
+  for (const line of run("git", ["diff", "HEAD", "--unified=0", "--", "."], dir).split("\n")) {
+    if (line.startsWith("+++ ")) file = line.slice(4).replace(/^b\//, "");
+    else if (file && line.startsWith("+") && !line.startsWith("+++")) (added.get(file) ?? added.set(file, []).get(file)).push(line.slice(1));
+  }
+  for (const f of run("git", ["ls-files", "--others", "--exclude-standard"], dir).split("\n").filter(Boolean)) {
+    if (!/\.(tsx|jsx|ts|js|css|scss|html|vue|svelte)$/.test(f)) continue;
+    added.set(f, fs.readFileSync(path.join(dir, f), "utf8").split("\n"));
+  }
+
+  const systemFile = path.join(dir, ".palate", "system.md");
+  const system = fs.existsSync(systemFile) ? fs.readFileSync(systemFile, "utf8") : null;
+  const checks = system ? [...CHECKS, ...SYSTEM_CHECKS, ...(/Depth comes from 1px hairlines/.test(system) ? [HAIRLINE_SHADOW] : [])] : CHECKS;
+  const systemIds = new Set([...SYSTEM_CHECKS, HAIRLINE_SHADOW].map(([id]) => id));
+  const findings = [];
+  const keep = only ? new Set(only.map((f) => f.replace(/\\/g, "/"))) : null;
+  for (const [f, lines] of added) {
+    if (!/\.(tsx|jsx|ts|js|css|scss|html|vue|svelte)$/.test(f) || f.includes(".palate/")) continue;
+    if (keep && !keep.has(f)) continue;
+    lines.forEach((line, i) => {
+      if (/^\s*(\/\/|\/?\*)/.test(line)) return;
+      for (const [id, re, fix] of checks) {
+        if (id === "hex" && (tokenFiles.has(f) || /\.svg|CandleArt/.test(f))) continue;
+        if (id === "google-font" && system && tokenFiles.has(f)) continue;
+        // shadcn's own primitives (components/ui) keep their stock classes.
+        if (systemIds.has(id) && /components\/ui\//.test(f)) continue;
+        if ((id === "emoji" || id === "em-dash") && !/\.(tsx|jsx|html|vue|svelte)$/.test(f)) continue;
+        if (re.test(line)) findings.push({ id, file: f, line: i + 1, text: line.trim().slice(0, 100), fix });
+      }
+    });
+  }
+
+  // A page isn't done while its latest shoot fails the similarity gate or one of the user's rules.
+  return { findings, blockers: finishBlockers(dir), files: [...added.keys()] };
+}
+
+export function check(dir) {
+  const { findings, blockers, files } = checkFindings(dir);
+  // The words on the changed files (palate copy): hype, filler and placeholder copy, with what to write instead.
+  const copy = lintFiles(dir, files);
+  const copyLines = copy.findings.some((f) => f.weight !== "habit" || f.over) ? ["", copyReport(copy, { files: files.length })] : [];
+  const notDone = blockers.length ? ["", `✗ Not done: ${blockers.length} page${blockers.length > 1 ? "s" : ""} still fail${blockers.length > 1 ? "" : "s"} a gate. Fix ${blockers.length > 1 ? "them" : "it"} before calling the work done (yourself; don't ask the user):`, ...blockers.map((b) => `- ${b}`)] : [];
+  if (!findings.length) return ["palate check: nothing found in the changed lines.", ...copyLines, ...notDone].join("\n");
+  const byId = new Map();
+  for (const f of findings) (byId.get(f.id) ?? byId.set(f.id, []).get(f.id)).push(f);
+  const out = [`palate check: ${findings.length} finding(s) in changed lines`, ""];
+  for (const [id, fs_] of byId) {
+    out.push(`## ${id} ×${fs_.length}: ${fs_[0].fix}`);
+    for (const f of fs_.slice(0, 5)) out.push(`- ${f.file}: ${f.text}`);
+    out.push("");
+  }
+  return [...out, ...copyLines, ...notDone].join("\n");
+}

package/src/concept.mjs

@@ -0,0 +1,157 @@
+// `palate concept "<request>"`: the creative step. The design system fixes how things look; the concept
+// decides what this screen does that a template wouldn't. It picks one signature move and a few
+// supporting moves that fit the request and the applied system, steers away from moves this project
+// and this machine used recently, and names the AI defaults to avoid. `palate concept record` remembers
+// what was used, so the next screen (and the next project) doesn't repeat it.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import { PALATE_HOME } from "./catalog/store.mjs";
+import { loadSystems } from "./systems/load.mjs";
+import { pickSystems, readKind } from "./systems/pick.mjs";
+import { KB_ROOT } from "./paths.mjs";
+
+const MOVES_FILE = path.join(KB_ROOT, "moves", "moves.yaml");
+const GLOBAL_HISTORY = path.join(PALATE_HOME, "history.json");
+
+const words = (s) => String(s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? [];
+const readJson = (f, fallback) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return fallback;
+  }
+};
+
+export function loadMoves() {
+  return YAML.parse(fs.readFileSync(MOVES_FILE, "utf8"));
+}
+
+// Deterministic per project and request, but different across projects and as history grows:
+// two people asking for "a landing page" don't get the same moves.
+function seeded(seed) {
+  let h = 2166136261;
+  for (const c of seed) h = Math.imul(h ^ c.charCodeAt(0), 16777619);
+  return () => {
+    h = Math.imul(h ^ (h >>> 15), 2246822507);
+    h = Math.imul(h ^ (h >>> 13), 3266489909);
+    return ((h ^= h >>> 16) >>> 0) / 4294967296;
+  };
+}
+
+function appliedSystem(dir) {
+  const last = readJson(path.join(dir, ".palate", "systems.json"), []).at(-1);
+  return last ? loadSystems().find((s) => s.id === last.id) : undefined;
+}
+
+function fits(move, sys) {
+  if (!sys) return true;
+  for (const [facet, allowed] of Object.entries(move.fits ?? {})) if (sys.facets[facet] && !allowed.includes(sys.facets[facet])) return false;
+  for (const [facet, banned] of Object.entries(move.avoid ?? {})) if (banned.includes(sys.facets[facet])) return false;
+  return true;
+}
+
+export function concept(request, { dir, count = 3 } = {}) {
+  const { moves, cliches } = loadMoves();
+  const kind = readKind(request);
+  const q = new Set(words(request).flatMap((w) => [w, w.replace(/s$/, "")]));
+  const sys = dir ? appliedSystem(dir) : undefined;
+  const local = dir ? readJson(path.join(dir, ".palate", "history.json"), []) : [];
+  const global = readJson(GLOBAL_HISTORY, []).slice(-40);
+  const localUses = (id) => local.filter((h) => h.moves?.includes(id)).length;
+  const globalUses = (id) => global.filter((h) => h.moves?.includes(id)).length;
+  const rand = seeded(`${request}|${dir ?? ""}|${local.length}`);
+
+  // Moves without signals are craft every screen of this kind gets; the rest compete as ideas.
+  const always = moves.filter((m) => m.kinds.includes(kind) && !m.signals?.length);
+  const scored = moves
+    .filter((m) => m.kinds.includes(kind) && m.signals?.length && fits(m, sys))
+    .map((m) => {
+      const hits = (m.signals ?? []).filter((s) => words(s).every((w) => q.has(w)));
+      let score = 0.3 + hits.length * 1.2;
+      score -= 1.6 * localUses(m.id) + 0.35 * globalUses(m.id);
+      score += rand() * 0.9;
+      return { m, score, hits, reused: localUses(m.id), seen: globalUses(m.id) };
+    })
+    .sort((a, b) => b.score - a.score);
+
+  // One signature move with real impact, then supporting moves from other families.
+  const signature = scored.find((s) => s.m.cost !== "low") ?? scored[0];
+  const support = [];
+  const families = new Set([signature?.m.family]);
+  for (const s of scored) {
+    if (support.length >= count - 1) break;
+    if (s === signature || families.has(s.m.family)) continue;
+    support.push(s);
+    families.add(s.m.family);
+  }
+  const alternates = scored.filter((s) => s !== signature && !support.includes(s)).slice(0, 4);
+
+  // Blending: borrow the display type of a different, still-fitting system so the look isn't a copy.
+  let blend;
+  if (sys && (kind === "marketing" || kind === "commerce")) {
+    const other = pickSystems(request, { dir, count: 6 }).picked.map((p) => p.system).find((s) => s.id !== sys.id && s.facets.displayClass !== sys.facets.displayClass);
+    if (other) blend = other;
+  }
+
+  const recentCliches = local.flatMap((h) => h.cliches ?? []);
+  return { kind, sys, signature, support, alternates, blend, always, cliches: cliches.filter((c) => c.kinds.includes(kind)), recentCliches, history: local.slice(-5) };
+}
+
+const line = (s) => `**${s.m.id}** (${s.m.family}${s.hits.length ? `; fits: ${s.hits.join(", ")}` : ""}${s.reused ? `; used ${s.reused}× in this project` : ""})\n  ${s.m.do}\n  Test: ${s.m.test}`;
+
+export function conceptReport(request, opts) {
+  const c = concept(request, opts);
+  const out = [`# Concept for: ${request}`, "", `A ${c.kind} screen${c.sys ? ` in the ${c.sys.name} system` : " (no system applied yet: run palate system pick first)"}.`, ""];
+  out.push(
+    "## 1. Find the idea in the domain (answer these before you design)",
+    "- What does the work in this domain physically look like? Name its objects (a docket, a pour, a manifest, a set list).",
+    "- What's the unit people count, and the rhythm they work in (per shift, per pour, per sprint, per close)?",
+    "- What's the one moment that matters most on this screen, the one people open it for?",
+    "- What would a person from this field find wrong or fake in a generic version of this screen?",
+    "Write the concept in one sentence: \"This screen is a ___ that lets ___ ___ at a glance.\" Every move below should serve that sentence.",
+    "",
+  );
+  if (c.signature) out.push("## 2. Signature move (the one thing people will remember)", line(c.signature), "");
+  if (c.support.length) out.push("## 3. Supporting moves", ...c.support.map(line), "");
+  if (c.always.length) out.push("## Always (craft, not ideas)", ...c.always.map((m) => `- **${m.id}**: ${m.do}`), "");
+  if (c.alternates.length) out.push("Swap in if one doesn't serve the concept: " + c.alternates.map((s) => s.m.id).join(", "), "");
+  if (c.blend)
+    out.push(
+      "## 4. Blend (optional, for a look that isn't one brand's)",
+      `Keep ${c.sys.name}'s surfaces, spacing and colour, but take display type from ${c.blend.name} (${c.blend.facets.displayClass ?? "its display face"}, ${c.blend.facets.displaySize}px/${c.blend.facets.displayWeight}):`,
+      `  palate system apply ${c.sys.id} --type-from ${c.blend.id}`,
+      "",
+    );
+  out.push(
+    "## 5. The AI defaults (each one makes a screen look generated)",
+    ...c.cliches.map((x) => `- ${x.id}: ${x.what}${c.recentCliches.includes(x.id) ? " ← already on another screen in this project" : ""}`),
+    "Use one only when the job needs it, and then change it in a way the concept explains.",
+    "",
+  );
+  if (c.history.length) out.push("## Recently in this project", ...c.history.map((h) => `- ${h.screen}: ${h.moves.join(", ")}`), "");
+  out.push(`When the screen is built, record it so the next one doesn't repeat it:\n  palate concept record "<screen name>" --moves ${[c.signature, ...c.support].filter(Boolean).map((s) => s.m.id).join(",")}`);
+  return out.join("\n");
+}
+
+export function recordConcept(dir, screen, moveIds) {
+  const { moves } = loadMoves();
+  const known = new Set(moves.map((m) => m.id));
+  const unknown = moveIds.filter((id) => !known.has(id));
+  if (unknown.length) throw new Error(`Unknown move(s): ${unknown.join(", ")}`);
+  const at = new Date().toISOString();
+  const file = path.join(dir, ".palate", "history.json");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const local = readJson(file, []);
+  const fp = readJson(path.join(dir, ".palate", "fingerprints.json"), {});
+  const cliches = [...new Set(Object.values(fp).flatMap((f) => f.cliches ?? []))];
+  local.push({ screen, moves: moveIds, cliches, at });
+  fs.writeFileSync(file, JSON.stringify(local, null, 2));
+  // Machine-wide memory holds only move ids and time: no project names or content.
+  fs.mkdirSync(PALATE_HOME, { recursive: true });
+  const global = readJson(GLOBAL_HISTORY, []);
+  global.push({ moves: moveIds, at });
+  fs.writeFileSync(GLOBAL_HISTORY, JSON.stringify(global.slice(-200), null, 2));
+  return `Recorded ${moveIds.length} move(s) for "${screen}".`;
+}

package/src/context.mjs

@@ -0,0 +1,226 @@
+// `palate context`: what a designer checks before touching a codebase. Deterministic, no model calls.
+import fs from "node:fs";
+import path from "node:path";
+
+const read = (f) => {
+  try {
+    return fs.readFileSync(f, "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+function walk(dir, depth = 4, out = []) {
+  if (depth < 0 || !fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (["node_modules", ".git", "dist", "build", ".next", ".palate"].includes(e.name) || e.name.startsWith(".")) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, depth - 1, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+function detect(deps, files, dir) {
+  const has = (n) => Object.prototype.hasOwnProperty.call(deps, n);
+  const ver = (n) => (deps[n] ?? "").replace(/^[^\d]*/, "");
+  const rel = (f) => path.relative(dir, f).split(path.sep).join("/");
+
+  const framework = has("next") ? `Next.js ${ver("next")}` : has("nuxt") ? "Nuxt" : has("@sveltejs/kit") ? "SvelteKit" : has("astro") ? "Astro" : has("vite") ? `Vite ${ver("vite")}` : "unknown";
+  const ui = has("react") ? `React ${ver("react")}` : has("vue") ? "Vue" : has("svelte") ? "Svelte" : "unknown";
+
+  const styling = [];
+  if (has("tailwindcss")) styling.push(`Tailwind ${ver("tailwindcss")}${ver("tailwindcss").startsWith("4") ? " (CSS-first, @theme)" : ""}`);
+  const modules = files.filter((f) => /\.module\.(css|scss)$/.test(f));
+  if (modules.length) styling.push(`CSS Modules (${modules.length} files)`);
+  if (has("styled-components")) styling.push("styled-components");
+  if (has("@emotion/react")) styling.push("Emotion");
+  if (has("@vanilla-extract/css")) styling.push("vanilla-extract");
+
+  const components = [];
+  const shadcn = read(path.join(dir, "components.json"));
+  if (shadcn) {
+    try {
+      const c = JSON.parse(shadcn);
+      components.push(`shadcn/ui (style ${c.style ?? "?"}, base colour ${c.tailwind?.baseColor ?? "?"}, alias ${c.aliases?.ui ?? "?"})`);
+    } catch {
+      components.push("shadcn/ui");
+    }
+  }
+  for (const [pkg, name] of [["@mui/material", "MUI"], ["@chakra-ui/react", "Chakra"], ["@mantine/core", "Mantine"], ["@headlessui/react", "Headless UI"], ["react-aria-components", "React Aria"], ["@radix-ui/themes", "Radix Themes"]]) if (has(pkg)) components.push(name);
+  if (Object.keys(deps).some((d) => d.startsWith("@radix-ui/react-"))) components.push("Radix primitives");
+
+  const icons = [["lucide-react", "Lucide"], ["@heroicons/react", "Heroicons"], ["react-icons", "react-icons"], ["@phosphor-icons/react", "Phosphor"], ["@tabler/icons-react", "Tabler"]].filter(([p]) => has(p)).map(([, n]) => n);
+  const motion = [["motion", "Motion"], ["framer-motion", "Framer Motion"], ["gsap", "GSAP"], ["@react-spring/web", "React Spring"], ["@formkit/auto-animate", "auto-animate"]].filter(([p]) => has(p)).map(([, n]) => n);
+  const charts = [["recharts", "Recharts"], ["@nivo/core", "Nivo"], ["chart.js", "Chart.js"], ["@visx/visx", "visx"], ["d3", "d3"], ["echarts", "ECharts"]].filter(([p]) => has(p)).map(([, n]) => n);
+
+  // Fonts actually loaded or declared.
+  const fonts = new Set();
+  const html = read(path.join(dir, "index.html")) ?? "";
+  for (const m of html.matchAll(/fonts\.googleapis\.com\/css2?\?family=([^"&]+)/g)) fonts.add(decodeURIComponent(m[1]).replace(/\+/g, " ").split(":")[0] + " (Google Fonts link)");
+  for (const d of Object.keys(deps)) if (d.startsWith("@fontsource")) fonts.add(d.replace(/^@fontsource(-variable)?\//, "") + " (@fontsource)");
+  if (has("geist")) fonts.add("Geist (geist package)");
+
+  const cssFiles = files.filter((f) => /\.(css|scss)$/.test(f) && !/\.module\./.test(f));
+  const tokens = [];
+  for (const f of cssFiles) {
+    const css = read(f) ?? "";
+    for (const m of css.matchAll(/font-family:\s*([^;]+);/g)) fonts.add(m[1].split(",")[0].trim().replace(/["']/g, "") + ` (declared in ${rel(f)})`);
+    for (const m of css.matchAll(/--font-[\w-]+:\s*([^;]+);/g)) fonts.add(m[1].split(",")[0].trim().replace(/["']/g, "") + ` (token in ${rel(f)})`);
+    const vars = [...css.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)].map((m) => [m[1], m[2].trim()]);
+    if (vars.length) tokens.push({ file: rel(f), vars });
+  }
+
+  const uiDir = ["src/components/ui", "components/ui"].map((d) => path.join(dir, d)).find((d) => fs.existsSync(d));
+  const uiComponents = uiDir ? fs.readdirSync(uiDir).map((f) => f.replace(/\.(tsx|jsx|ts|js|vue|svelte)$/, "")) : [];
+  const otherComponents = files
+    .filter((f) => /[\\/]components[\\/]/.test(f) && !/[\\/]ui[\\/]/.test(f) && /\.(tsx|jsx|vue|svelte)$/.test(f))
+    .map(rel);
+  const routes = files.filter((f) => /[\\/](routes|pages|app)[\\/]/.test(f) && /\.(tsx|jsx|vue|svelte|astro)$/.test(f)).map(rel);
+  const data = files.filter((f) => /[\\/]data[\\/]/.test(f)).map(rel);
+  const docs = ["README.md", "DESIGN.md", "PRODUCT.md", "AGENTS.md", "CLAUDE.md"].filter((f) => fs.existsSync(path.join(dir, f)));
+
+  return { framework, ui, styling, components, icons, motion, charts, fonts: [...fonts], tokens, uiComponents, otherComponents, routes, data, docs };
+}
+
+function groupVars(vars) {
+  const groups = {};
+  for (const [name, value] of vars) {
+    const key = /color|--(bg|fg|ink|paper|line|background|foreground|primary|secondary|muted|accent|border|card|popover|destructive|ring|input|chart|success|warning|danger|info)/.test(name)
+      ? "colour"
+      : /radius/.test(name)
+        ? "radius"
+        : /shadow/.test(name)
+          ? "shadow"
+          : /font|text|leading|tracking/.test(name)
+            ? "type"
+            : /space|gutter|gap/.test(name)
+              ? "space"
+              : /ease|duration/.test(name)
+                ? "motion"
+                : "other";
+    (groups[key] ??= []).push(`${name}: ${value}`);
+  }
+  return groups;
+}
+
+// The short version for briefs (about 40 lines): stack, tokens, components and screens, each capped. A
+// builder opens the files it names for the rest.
+export function contextSummary(dir, { maxLines = 40 } = {}) {
+  const pkg = JSON.parse(read(path.join(dir, "package.json")) ?? "{}");
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const c = detect(deps, walk(dir), dir);
+  const cap = (items, n) => (items.length > n ? `${items.slice(0, n).join(", ")} (+${items.length - n} more)` : items.join(", "));
+  // Loop variants (name-a1 …) are not the project's screens.
+  const screens = c.routes.filter((r) => !/-[a-z]\d+([\\/]|\.)/.test(r));
+  const lines = [
+    `- Stack: ${[c.framework, c.ui, ...c.styling].join(", ")}; components: ${c.components.join(", ") || "hand-built"}; icons: ${c.icons.join(", ") || "none"}; motion: ${c.motion.join(", ") || "CSS only"}; charts: ${c.charts.join(", ") || "none (inline SVG is fine)"}`,
+    `- Fonts: ${cap([...new Set(c.fonts.map((f) => f.replace(/ \((declared|token) in .+\)$/, "")))], 4) || "system fonts"}. Keep them; don't load another font for one screen.`,
+    c.docs.length ? `- Read first: ${c.docs.join(", ")}` : null,
+  ];
+  for (const t of c.tokens.slice(0, 3)) {
+    lines.push(`- Tokens in ${t.file} (use these, don't invent new ones):`);
+    for (const [g, vs] of Object.entries(groupVars(t.vars))) lines.push(`  - ${g}: ${cap(vs, 10).slice(0, 400)}`);
+  }
+  if (c.uiComponents.length) lines.push(`- UI components: ${cap(c.uiComponents, 30)}`);
+  if (c.otherComponents.length) lines.push(`- Other components: ${cap(c.otherComponents, 12)}`);
+  if (screens.length) lines.push(`- Screens: ${cap(screens, 12)}`);
+  if (c.data.length) lines.push(`- Data: ${cap(c.data, 8)}`);
+  const out = lines.filter(Boolean);
+  return (out.length > maxLines ? [...out.slice(0, maxLines - 1), "- … (run palate context for the rest)"] : out).join("\n");
+}
+
+export function context(dir) {
+  const pkg = JSON.parse(read(path.join(dir, "package.json")) ?? "{}");
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const files = walk(dir);
+  const c = detect(deps, files, dir);
+  const lines = [];
+  const list = (label, items, empty = "none") => lines.push(`- **${label}:** ${items.length ? items.join(", ") : empty}`);
+
+  lines.push(`# Project context: ${pkg.name ?? path.basename(dir)}`, "");
+  list("Framework", [c.framework, c.ui]);
+  list("Styling", c.styling);
+  list("Component library", c.components, "none, hand-built components");
+  list("Icons", c.icons);
+  list("Motion", c.motion, "none installed (CSS transitions only)");
+  list("Charts", c.charts, "none installed");
+  list("Fonts", c.fonts, "system fonts only");
+  list("Docs to read", c.docs);
+  lines.push("");
+
+  if (c.tokens.length) {
+    lines.push("## Design tokens (use these, don't invent new ones)");
+    for (const t of c.tokens) {
+      lines.push(`### ${t.file}`);
+      const groups = groupVars(t.vars);
+      for (const [g, vs] of Object.entries(groups)) {
+        const shown = vs.slice(0, 40);
+        lines.push(`- ${g}: ${shown.join(" · ")}${vs.length > shown.length ? ` · …${vs.length - shown.length} more` : ""}`);
+      }
+    }
+    lines.push("");
+  }
+  if (c.uiComponents.length) lines.push(`## UI components available\n${c.uiComponents.join(", ")}\n`);
+  if (c.otherComponents.length) lines.push(`## Other components\n${c.otherComponents.join(", ")}\n`);
+  if (c.routes.length) lines.push(`## Existing screens\n${c.routes.join(", ")}\nOpen one or two of these to see how the app already looks before designing a new screen.\n`);
+  if (c.data.length) lines.push(`## Data files\n${c.data.join(", ")}\n`);
+
+  lines.push("## Rules this implies");
+  if (c.tokens.length) lines.push("- Colours, radii, shadows and type come from the tokens above. A hard-coded hex value or new font is a decision you must justify in the Decision Record.");
+  if (c.components.length || c.uiComponents.length) lines.push("- Build from the existing components. Extend them with variants instead of writing parallel ones.");
+  if (c.fonts.length) lines.push(`- Keep the existing type (${c.fonts[0]}). Don't load another font for one screen.`);
+  else lines.push("- No custom font is loaded. Use the system stack unless the brief asks for a brand typeface.");
+  if (c.styling.some((s) => s.startsWith("CSS Modules"))) lines.push("- Write styles as a CSS Module next to the screen, using the CSS variables. No Tailwind here.");
+  if (!c.charts.length) lines.push("- No chart library: small inline SVG is fine for sparklines and bars; add a library only for real charts.");
+  return lines.join("\n");
+}
+
+// ---- brand or scratch (palate research and direction): does the project already have a brand to work inside?
+// A brand: at least one chromatic colour token (a real hue, not a framework's neutral greys), or a custom font
+// with a set of colour tokens. Otherwise palate treats it as starting from scratch, and each art direction must
+// define a complete starter system. A request for a rebrand ("rebrand", "new look", "new identity") is scratch
+// even when a brand exists.
+const SYSTEM_FONT = /^(ui-sans-serif|ui-serif|ui-monospace|system-ui|-apple-system|blinkmacsystemfont|sans-serif|serif|monospace|segoe ui|roboto|arial|helvetica( neue)?|inherit|var\(.*)$/i;
+const REBRAND = /\b(rebrand(ing)?|new (brand|look|identity|visual identity|palette)|from scratch|fresh brand|brand refresh)\b/i;
+function hueOf(value) {
+  const v = String(value).trim().toLowerCase();
+  let m = v.match(/^#([0-9a-f]{3}|[0-9a-f]{6})\b/);
+  if (m) {
+    const h = m[1].length === 3 ? m[1].split("").map((c) => c + c).join("") : m[1];
+    const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+    const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2;
+    const s = max === min ? 0 : (max - min) / (1 - Math.abs(2 * l - 1));
+    return { chromatic: s > 0.18 && l > 0.08 && l < 0.92 };
+  }
+  if ((m = v.match(/^oklch\(\s*([\d.]+%?)\s+([\d.]+)/))) return { chromatic: Number(m[2]) > 0.04 };
+  if ((m = v.match(/^(?:hsla?\()?\s*[\d.]+(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/))) return { chromatic: Number(m[1]) > 18 && Number(m[2]) > 8 && Number(m[2]) < 92 };
+  if ((m = v.match(/^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/))) {
+    const [r, g, b] = m.slice(1, 4).map(Number);
+    return { chromatic: Math.max(r, g, b) - Math.min(r, g, b) > 40 };
+  }
+  return null;
+}
+export function brandOf(dir, job = "") {
+  const pkg = JSON.parse(read(path.join(dir, "package.json")) ?? "{}");
+  const c = detect({ ...pkg.dependencies, ...pkg.devDependencies }, walk(dir), dir);
+  const vars = c.tokens.flatMap((t) => t.vars.map(([name, value]) => ({ name, value, file: t.file })));
+  const colours = vars.filter((v) => /color|colour|--(bg|fg|ink|paper|brand|primary|accent|background|foreground|surface|canvas)/i.test(v.name) && hueOf(v.value));
+  const chromatic = colours.filter((v) => hueOf(v.value)?.chromatic);
+  const brandColour = chromatic.find((v) => /brand|primary|accent/i.test(v.name)) ?? chromatic[0] ?? null;
+  const fonts = [...new Set(c.fonts.map((f) => f.replace(/ \((declared|token|Google Fonts|@fontsource|geist).*\)$/i, "").trim()))];
+  const custom = fonts.filter((f) => !SYSTEM_FONT.test(f));
+  const radii = vars.filter((v) => /radius/i.test(v.name)).map((v) => `${v.name} ${v.value}`);
+  const components = [...c.uiComponents, ...c.otherComponents.map((f) => path.basename(f).replace(/\.\w+$/, ""))].slice(0, 12);
+  const hasBrand = chromatic.length >= 1 || (custom.length >= 1 && colours.length >= 4);
+  const rebrand = REBRAND.test(job);
+  const mode = hasBrand && !rebrand ? "brand" : "scratch";
+  const typeLabel = custom.length ? custom.slice(0, 2).join(" + ") : fonts.length ? "the system sans stack" : "system fonts";
+  const line =
+    mode === "brand"
+      ? `Using your brand: ${brandColour ? `${brandColour.name} ${brandColour.value}` : `${colours.length} colour tokens`}, ${typeLabel}${radii.length ? `, radii ${radii.slice(0, 3).map((r) => r.split(" ")[1]).join("/")}` : ""}${components.length ? `, your ${components.slice(0, 4).join("/")} components` : ""}.`
+      : rebrand && hasBrand
+        ? `A rebrand: your current tokens (${brandColour ? `${brandColour.name} ${brandColour.value}` : `${colours.length} colour tokens`}, ${typeLabel}) are replaced by each direction's starter system.`
+        : `Starting from scratch: ${colours.length ? `only ${colours.length} neutral colour token(s)` : "no colour tokens"}, ${custom.length ? custom.join(", ") : "default fonts"}. Each direction defines a complete starter system.`;
+  return { mode, rebrand, line, colours: colours.map((v) => ({ name: v.name, value: v.value, file: v.file })), brandColour, fonts, customFonts: custom, radii, components, tokenFiles: c.tokens.map((t) => t.file) };
+}