@palate/cli 0.0.0-stage → 0.0.1

package/bin/palate.mjs

@@ -0,0 +1,894 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { check } from "../src/check.mjs";
+import { context } from "../src/context.mjs";
+import { card, list, search, show } from "../src/kb.mjs";
+import { shoot } from "../src/shoot.mjs";
+import { closePool, keepAlive } from "../src/pool.mjs";
+
+keepAlive();
+
+const HELP = `palate: design intelligence for coding agents
+
+  palate activate <code>             Activate palate with your invite code (palate-XXXX-XXXX-XXXX), once per machine
+  palate activate --status           Whether palate is activated here  ·  palate deactivate: remove it
+  palate version                     The installed version
+
+  palate context                     What this project already uses: stack, tokens, fonts, components, screens
+  palate search <words> [--scope s]  Find patterns and rules for a screen (returns short cards)
+  palate show <id> [id...]           Read full knowledge entries
+  palate list                        Every entry in the knowledge base
+  palate shoot <route> [--widths 1440,390] [--tablet] [--url http://localhost:3000] [--fold] [--like <project>]
+                                     Render a route, save screenshots, report measurable problems
+                                     (--fold: first screen only, no principles pass; for checks while building).
+                                     Fails (exit 1) when the page is over 50% like another of your projects or
+                                     too close to a captured reference; --like <project> when the user asked to match it
+  palate check                       Scan your changed lines for generated-UI tells and token drift; says
+                                     "Not done" while a page fails a rule or the similarity gate
+  palate copy [files…] [--all]       The words a page shows, read from source: hype, filler, placeholder copy and
+                                     proof with no source, each with what to write instead (changed files; --all: every file)
+  palate guard [--install|--uninstall] [--agent claude,codex,cursor,gemini,copilot,git] [--global]
+                                     The stop hook: the agent can't call UI work done until palate looked at every
+                                     changed screen and its copy, code tells, credits and gates pass (3 rounds, then
+                                     it reports). Installs for every agent the project uses (Claude Code, Codex,
+                                     Cursor, Gemini CLI; Copilot reads the Claude hook); --agent git: a pre-commit
+                                     check for any agent
+  palate icons <brand…> [--mono]    Real brand marks (Simple Icons, CC0 set) as local SVGs in the brand's colour, for
+                                     "works with" rows and integration grids; a brand not in the set is reported
+  palate waive <id> [--file f] --reason "…"   A finding that is wrong here, with a reason a reviewer would accept
+  palate waive  ·  palate waive --remove <id>  The project's waivers (every guard report lists them)
+
+  palate refs [words] --shelf <shelf> [--industry ..] [--audience ..] [--tone ..] [--needs ..] [--theme light|dark]
+                                     Pick 3 distinct real-world references for this screen and fetch their images
+  palate refs note <id> "text"       Record what worked from a reference (improves future picks)
+  palate capture <url>               Screenshot any public page and measure its fonts, type scale, colours, radii
+  palate shoot <route> --compare <reference id or image path>
+                                     Also save your first screen side by side with the reference
+  palate system pick "<request>"     Choose the design system whose craft fits this request and codebase
+  palate system apply <id> [--type-from <id>]
+                                     Transfer that craft into the project's tokens (keeps your brand colour);
+                                     --type-from blends in another system's display type
+  palate concept "<request>"         The creative step: a signature move and supporting moves for this screen,
+                                     steering away from what this project and machine used recently
+  palate concept record "<screen>" --moves a,b,c
+                                     Remember the moves a finished screen used, so the next one differs
+  palate moves [--tags calm,crafted] [--kind hero] [--signature] [--limit 8]
+                                     The moves library (kb/moves): named creative techniques with recipes,
+                                     ranked by how well they fit the brand's tags
+  palate moves show <id> [id...]     A move in full  ·  palate moves brief <id,id>: their recipes for a brief
+  palate system list | show <id>     Browse the design systems
+
+  The default (triage → one build → the finishing pass → the user points at what's wrong):
+  palate plan "<request>" [--route /x] [--mode direct|build|direction|research|quick|full|match]
+                                     Run first: what this deserves, and why (direct: change in place; build:
+                                     one build, the default; direction: 3 ideas first; quick/full: variants;
+                                     match: build the user's own design faithfully)
+  palate build "<job>" --route /x [--direction <name>] [--refs a.png,https://…] [--like <project>]
+                                     Build mode: one brief for the real route with the user's rules, references
+                                     and notes, taste and chosen direction; logs its estimated token cost
+  palate blueprint "<job>" --route /x  The design decided before code (a new page's first build step): a planner
+                                     brief for the spec (mood, category truths and clichés), the system, imagery
+                                     per section and one archetype per section from kb/sections
+  palate blueprint --file <bp.json>  Check it (variety, surfaces, material, contrast) and save it with tokens;
+                                     palate build then builds it section by section
+  palate match <image|url|figma link> [--route /x] [--width 1440]
+                                     Build from the user's own design: the screenshot, page or Figma frame is the
+                                     spec (Figma needs FIGMA_TOKEN, else export the frame as PNG). Saves it, measures
+                                     it and writes a fidelity brief; palate's taste, blueprint and house look step aside
+  palate match --check [--route /x]  The build beside the design at its width, a difference image and one judge
+                                     packet (content, geometry, type, assets, spacing, colour, details, motion)
+  palate match --answers <dir> [--route /x]
+                                     The verdict: READY, READY WITH SUBSTITUTIONS, NOT READY (with the fixes, two
+                                     repair rounds) or UNVERIFIED; --restore <n> rolls a worse round back
+  palate gate <route>                The quality floor, judged independently: palate's floor checks, then judge
+                                     packets (a checklist per section, the page beside strong real sites in both
+                                     orders) for fresh subagents
+  palate gate <route> --answers <dir> The verdict; below the bar: one repair brief for one section (2 rounds max)
+  palate gate <route> --judge api    No subagents (Codex, Cursor): palate runs the packets with a model API itself
+                                     (GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY; PALATE_JUDGE picks);
+                                     --judge self: the builder answers, and the verdict says it is self-judged
+  palate gate <route> --restore <n>  Roll the source back to round n's snapshot (a repair made it worse)
+  palate gate <route> --duel hero [--answers <dir>]
+                                     Best of two: the page with ?palate-alt=hero shows the blueprint's alternative;
+                                     blind judges in both orders pick, the user only when they split
+  palate finish <route>              The finishing pass in one process: shoot, states, details and animate
+                                     --check sharing one browser and dev server, one combined report
+  palate section <route> <id|name>   A section builder's own check: that section at 1440 and 390 and palate's
+                                     floor checks for it, in seconds (no full-page shoot)
+  palate sections [--kind pricing] [--tags warm,crafted]
+                                     palate's section archetypes (kb/sections), ranked for the tags
+  palate sections show <id>          One archetype in full: structure, finish, phone layout, floor checks
+  palate imagery "<query>" [--type Photograph] [--artist "<name>"] [--sources met,cleveland,commons] [--count 12]
+                                     Several searches at once: "wedding party | street at dusk | hands" (side by
+                                     side, one shared cache kept a week). Open-licence images for a section: CC0 museum images (The Met, Cleveland), or
+                                     with --sources commons, Wikimedia Commons photos (CC0, public domain, CC BY;
+                                     CC BY needs its credit on the page, which palate writes), on contact sheets of
+                                     12 with pixel sizes. --type: Photograph, Painting, Print, Drawing, Textile,
+                                     Ceramic, Sculpture, Glass. --artist: one maker's work (a photographer's
+                                     name). Answers are cached for 2 hours in .palate (--refresh skips the cache)
+  palate imagery pick <id> [<id>…] [--from <slug>] [--no-trim]
+                                     Download the chosen images into the project with their credits, as web-sized
+                                     JPEGs (longest side 2400 px), a museum mount trimmed (--no-trim keeps it)
+  palate imagery treatment <duotone|tone|natural|grain> [--shadow #hex] [--highlight #hex] [--colour #hex]
+                                     The one photo treatment for the page, as CSS in the project
+  palate texture <grain|paper|speckle|halftone|linen> [--colour #hex] [--opacity 0.1]
+                                     A material drawn in code, written into the project, with its CSS
+  palate bench list [--kind <category>] | new <id> --into <folder> | record <id> --from <gate dir> | report
+                                     The benchmark: 30 fictional briefs judged blind against real sites
+  palate direction "<the problem>" [--route /x]
+                                     A job-level ask ("users wait 20s here, what should they see?"): a brief for
+                                     3 ideas with rough wireframes, no builds
+  palate research "<job>" [--route /] [--urls a,b,c] [--inspire d,e] [--index-only] [--keep 5]
+                                     A new screen (the triage's research mode): understands the job, prints the
+                                     searches for competitors; with --urls looks at those pages and palate's own
+                                     picks live (robots.txt respected, ≤12 pages), ranks them by craft, taste and
+                                     diversity, and writes .palate/research/<name>/ (research.md, contact sheet)
+  palate research --name <n> --like R2 --dislike R4
+                                     What the user thought of a reference (palate learns from it)
+  palate direction "<job>" --from-research <name>
+                                     3 art directions from the research: metaphor, one signature moment, brand
+                                     kept or a starter system, section plan, provenance, wireframe
+  palate direction --ideas <file> [--auto | --choose user] [--no-open]
+                                     The user picks one idea (and may add a note) in their browser; it feeds
+                                     palate build
+  Variants, only when the user asks to explore or for a new kind of screen (sketches → judge → pick → build out):
+  palate variants "<job>" --name <n> [--refs a.png,https://…] [--mode m] [--quick] [--count 3] [--per 2] [--full]
+                                     Choose directions, find references, write one brief per direction; the
+                                     count comes from plan unless given. Sketches (first screen + centrepiece)
+                                     unless --full
+  palate judge --name <n> [--scores f.json] [--keep 4] [--watch --ready 4]
+                                     Render the variants and drop the weakest (a fresh judge scores the rubric);
+                                     --watch waits until 4 are built
+  palate pick --name <n> [--pairs] [--ready 4]
+                                     The user sees the variants side by side, blind, and clicks the best
+                                     (--pairs: answer every A/B pair instead; --ready: open as soon as 4 are built)
+  palate build --name <n>            After the pick: the brief that builds the winning sketch out in full
+  palate forget <project>            Drop a project's records from palate's history (a throwaway folder saved as a
+                                     project); --dry-run counts first. Taste is untouched
+  palate stats                       How long recent loops took, stage by stage, tokens per mode (estimated),
+                                     and the triage decisions
+  palate polish <route>              Final polish on the chosen design (Jakub Krehel + Emil Kowalski skills)
+  Commands for specific jobs:
+  palate critique <route>            A designer's review, section by section: crops, facts, taste and rubric in a
+                                     sheet; the agent writes findings
+  palate critique --findings <file> [--no-open]
+                                     The user agrees or disagrees with each finding in the browser (teaches taste)
+  palate fix <route> [--verify]      A brief from the agreed findings, most severe first (or from shoot's
+                                     measurable problems); --verify re-shoots each finding's section, before | after
+  palate vary <route> --section "<name or selector>" [--count 3] [--brief "<what you want>"]
+                                     Fresh variations of one section, each built as a copy of the page; then pick
+  palate states <route> [--verify]   Every state of the screen, rendered and measured: empty, loading, error,
+                                     long text, 50 items, one item, images failing, 320 wide, 200% zoom with
+                                     the keyboard, forms pressed twice, failing, offline. A contact sheet (a row
+                                     per part, a column per state) and a brief of the missing states;
+                                     --verify renders them again, before | after
+  palate details <route>             Micro-component pass: avatars, brand marks, inputs, empty states, numbers,
+                                     icons, placeholder text, badges, hover/focus/pressed, favicon and OG image
+  palate animate <route> [--check]   Motion pass that serves the content, with a frame-strip motion check
+                                     (--check: only the check, to verify; covers reduced motion and no-JS)
+  palate ambition <route>            The last step of the finishing pass: is it remarkable, not only correct?
+                                     Every section beside the strongest references, measured, with a rubric
+                                     for the agent; picks the weakest section and writes its upgrade brief
+  palate ambition <route> --scores <file>
+                                     Your rubric scores: re-picks the weakest section and rewrites the brief
+  palate ambition <route> --verify [--moves <id>]
+                                     After the one upgrade: that section before | after with new scores; logs
+                                     the move so palate learns which upgrades this user keeps
+  palate point [route] [--url …]     Fix things by pointing at them: opens the running app with palate's overlay;
+                                     the user clicks an element and says what should change
+  palate point [route] --auto [--agent claude|codex] [--yolo]
+                                     The same, and palate runs your coding agent headless on each pin, one at
+                                     a time (claude -p / codex exec); no chat needed. Claude Code may only read
+                                     and edit files and call palate's crop and done; --yolo skips every
+                                     permission check (warned). --agent-cmd "<cmd>": your own command instead
+  palate point next                  Wait for the next request (element, crop, likely source lines) and take it
+  palate point stop                  The same as the overlay's Done: the agent finishes what's queued, then stops
+  palate point crop <id>             Re-shoot that element after an edit at the pinned width and the other
+                                     one (phone or desktop, or the width the request names), with a verdict
+                                     for the other width: unchanged, changed or broke
+  palate point done <id> "<summary>" [--removed] [--override]
+                                     Mark it done; the user's pin shows before and after at both widths
+                                     (--removed: you removed the element, the after says so). Refuses while
+                                     the other width is broken; --override only when the user accepts it
+
+  palate refs add <image|url> [--like "…"] [--dislike "…"] [--kind landing]
+                                     Save the user's own references with what they like and dislike about
+                                     them (several notes: separate with ;); the notes become rules
+  palate refs mine                   List the user's saved references and their notes
+  palate refs rm <id>                Remove a reference and the rules that came only from its notes
+  palate mcp                         Run palate as an MCP server (stdio) for Claude Code, Codex, Cursor
+  palate taste [learn | init --from f]
+                                     What palate has learned (rules, hit rate) and the taste profile; learn turns
+                                     patterns in new evidence into proposed rules (for the user's OK), then lists
+                                     the rest for the profile
+  palate rule add "<rule>" [--kind landing | --only <Component> | --route /x] [--project <name>]
+                                     A rule in the user's words, active at once (it gets a measured check when
+                                     palate knows one). With no scope given, palate picks one: tied to this
+                                     product (a colour, font, its name, agents, demos) → only in this project;
+                                     a judgement about design → everywhere
+  palate rule list [--kind k] | edit <id> ["<rule>"] [--kind k] [--project <name>|all] | rm <id> | learn [--all]
+                                     The user's rules (~/.palate/taste/rules.json): at the top of every brief,
+                                     checked by every shoot, enforced by the judge. Proposed rules are listed apart
+  palate rule review [--no-open]     The rules palate proposed (from repeated asks, agreed critique findings,
+                                     failures), on a board in the browser: wording, where it applies, keep or discard.
+                                     Nothing palate infers applies anywhere until it is kept
+  palate rule ok <id> [--scope <n|id> | --kind team | --only <Component> | --route /x] [--project <name>] [--text "…"]
+                                     Keep a proposed rule (default: its suggested scope). --project <name> keeps a
+                                     rule to one project (its folder's name); it then applies nowhere else
+  palate rule no <id>                Discard a proposed rule; the same evidence won't propose it again
+  palate fail <route> "<why>" [--kind landing] [--shot a.png]
+                                     The user called this screen bad: keeps the screenshot in ~/.palate/failures
+                                     and proposes rules from the why, for the user's OK
+  palate catalog sync vibrant        Maintainers: refresh the vibrant.design discovery list (polite, one request a second)
+  palate catalog index               Maintainers: build kb/index/discovery.json (facts and links) that palate ships
+  palate catalog stats               What's on the shelves
+
+  --dir <path>   project folder (default: current folder)`;
+
+const { values: o, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    dir: { type: "string" },
+    scope: { type: "string" },
+    widths: { type: "string" },
+    url: { type: "string" },
+    limit: { type: "string" },
+    refresh: { type: "boolean" },
+    shelf: { type: "string" },
+    industry: { type: "string" },
+    audience: { type: "string" },
+    tone: { type: "string" },
+    needs: { type: "string" },
+    theme: { type: "string" },
+    count: { type: "string" },
+    compare: { type: "string" },
+    "no-keep-brand": { type: "boolean" },
+    "type-from": { type: "string" },
+    moves: { type: "string" },
+    name: { type: "string" },
+    scores: { type: "string" },
+    keep: { type: "string" },
+    per: { type: "string" },
+    from: { type: "string" },
+    "no-open": { type: "boolean" },
+    "no-trim": { type: "boolean" },
+    artist: { type: "string" },
+    quick: { type: "boolean" },
+    refs: { type: "string" },
+    note: { type: "string" },
+    pairs: { type: "boolean" },
+    findings: { type: "string" },
+    section: { type: "string" },
+    brief: { type: "string" },
+    verify: { type: "boolean" },
+    check: { type: "boolean" },
+    mode: { type: "string" },
+    full: { type: "boolean" },
+    route: { type: "string" },
+    only: { type: "string" },
+    text: { type: "string" },
+    ready: { type: "string" },
+    watch: { type: "boolean" },
+    fold: { type: "boolean" },
+    "dry-run": { type: "boolean" },
+    tablet: { type: "boolean" },
+    kind: { type: "string" },
+    // palate moves
+    tags: { type: "string" },
+    signature: { type: "boolean" },
+    shot: { type: "string" },
+    project: { type: "string" },
+    all: { type: "boolean" },
+    // palate guard / waive / icons
+    mono: { type: "boolean" },
+    hook: { type: "boolean" },
+    commit: { type: "boolean" },
+    // palate section
+    early: { type: "boolean" },
+    verdict: { type: "boolean" },
+    install: { type: "boolean" },
+    uninstall: { type: "boolean" },
+    global: { type: "boolean" },
+    reason: { type: "string" },
+    remove: { type: "string" },
+    source: { type: "string" },
+    like: { type: "string", multiple: true },
+    dislike: { type: "string", multiple: true },
+    direction: { type: "string" },
+    ideas: { type: "string" },
+    auto: { type: "boolean" },
+    agent: { type: "string" },
+    "agent-cmd": { type: "string" },
+    yolo: { type: "boolean" },
+    removed: { type: "boolean" },
+    override: { type: "boolean" },
+    status: { type: "boolean" },
+    // palate research
+    urls: { type: "string" },
+    inspire: { type: "string" },
+    "index-only": { type: "boolean" },
+    "from-research": { type: "string" },
+    choose: { type: "string" },
+    // quality floor: blueprint, gate, imagery, bench
+    file: { type: "string" },
+    answers: { type: "string" },
+    duel: { type: "string" },
+    judge: { type: "string" },
+    dirs: { type: "string" },
+    shadow: { type: "string" },
+    highlight: { type: "string" },
+    restore: { type: "string" },
+    sources: { type: "string" },
+    type: { type: "string" },
+    out: { type: "string" },
+    colour: { type: "string" },
+    opacity: { type: "string" },
+    seed: { type: "string" },
+    into: { type: "string" },
+    minutes: { type: "string" },
+    release: { type: "string" },
+    width: { type: "string" },
+    version: { type: "boolean", short: "v" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+const dir = path.resolve(o.dir ?? process.cwd());
+let [cmd, ...args] = positionals;
+
+// Invite-only: everything but these and the free commands (auth.FREE_COMMANDS) needs activation (palate mcp starts,
+// and its paid tools say so instead).
+const OPEN = new Set([undefined, "activate", "deactivate", "help", "version", "mcp"]);
+
+try {
+  if (o.help) cmd = "help";
+  if (o.version && !cmd) cmd = "version";
+  const { FREE_COMMANDS } = await import("../src/auth.mjs");
+  if (!OPEN.has(cmd) && !FREE_COMMANDS.has(cmd)) {
+    const { ensureGate, maybeRecheck } = await import("../src/auth.mjs");
+    const g = await ensureGate();
+    if (!g.ok) {
+      console.error(g.message);
+      process.exitCode = 1;
+      cmd = "blocked";
+    } else {
+      if (g.note) console.error(g.note);
+      maybeRecheck();
+    }
+  }
+  switch (cmd) {
+    case "blocked":
+      break;
+    case "activate": {
+      const A = await import("../src/auth.mjs");
+      if (o.status || args[0] === "status") console.log(A.status());
+      else if (!args[0]) throw new Error("Usage: palate activate <your code>  (codes look like palate-XXXX-XXXX-XXXX)  ·  palate activate --status");
+      else console.log(await A.activate(args[0]));
+      break;
+    }
+    case "deactivate":
+      console.log((await import("../src/auth.mjs")).deactivate());
+      break;
+    case "version":
+      console.log(JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+      break;
+    case "help":
+      console.log(HELP);
+      break;
+    case "context":
+      console.log(context(dir));
+      break;
+    case "search": {
+      const results = search(args.join(" "), { scope: o.scope });
+      console.log(results.length ? results.map(card).join("\n\n") + "\n\nRead the ones that fit with: palate show <id>" : "No matches. Try other words, or palate list.");
+      break;
+    }
+    case "show":
+      console.log(show(args).join("\n\n---\n\n"));
+      break;
+    case "list":
+      console.log(list().join("\n"));
+      break;
+    case "shoot": {
+      if (!args[0]) throw new Error("Usage: palate shoot <route>, e.g. palate shoot /team");
+      const widths = o.widths ? o.widths.split(",").map(Number) : undefined;
+      const { report, gate } = await shoot(dir, args[0], { widths, tablet: Boolean(o.tablet), url: o.url, compare: o.compare, fold: Boolean(o.fold), like: (o.like ?? []).flatMap((x) => x.split(",")) });
+      console.log(report);
+      // The similarity gate fails the command, like a failing test.
+      if (gate && !gate.pass) process.exitCode = 1;
+      break;
+    }
+    // ── palate ambition: the remarkable-not-only-correct pass (src/loop/ambition.mjs) ──
+    case "ambition": {
+      if (!args[0]) throw new Error("Usage: palate ambition <route> [--scores <file>] [--verify [--moves <id>]]");
+      const { ambition } = await import("../src/loop/ambition.mjs");
+      console.log(await ambition(dir, args[0], { url: o.url, scores: o.scores, verify: Boolean(o.verify), moves: o.moves ? o.moves.split(",").map((x) => x.trim()).filter(Boolean) : undefined }));
+      break;
+    }
+    // ── end palate ambition ──
+    case "check":
+      console.log(check(dir));
+      break;
+    case "copy": {
+      const { lintFiles, copyReport } = await import("../src/copy.mjs");
+      const { changedFiles } = await import("../src/guard.mjs");
+      const { execFileSync } = await import("node:child_process");
+      const files = args.length ? args : o.all ? execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], { cwd: dir, encoding: "utf8" }).split("\n").filter(Boolean) : (changedFiles(dir) ?? []);
+      const r = lintFiles(dir, files);
+      console.log(copyReport(r, { files: files.length }));
+      if (r.findings.some((f) => f.weight === "stop" || f.over)) process.exitCode = 1;
+      break;
+    }
+    case "guard": {
+      const G = await import("../src/guard.mjs");
+      if (o.hook) {
+        // Claude Code's Stop hook: its payload on stdin, the decision as JSON on stdout. Never fails the agent's stop
+        // on palate's own error: an exception allows the stop and says why on stderr.
+        let input = {};
+        try {
+          const raw = fs.readFileSync(0, "utf8");
+          input = raw.trim() ? JSON.parse(raw) : {};
+        } catch {}
+        const A = await import("../src/guard-agents.mjs");
+        const agent = (o.agent ?? "claude").toLowerCase();
+        try {
+          const norm = { ...A.parseInput(agent, input), agent };
+          const d = G.decide(norm, { dir: o.dir ?? norm.cwd });
+          const out = A.formatOutput(agent, d);
+          if (out) console.log(out);
+        } catch (e) {
+          console.error(`palate guard couldn't run (${e.message}); the stop goes ahead.`);
+          if (agent === "cursor") console.log("{}");
+        }
+        break;
+      }
+      if (o.commit) {
+        // The git pre-commit hook: the report on stderr, exit 1 while something is open.
+        const r = G.commitCheck(dir);
+        if (r.text) console.error(r.text);
+        if (!r.ok) process.exitCode = 1;
+        break;
+      }
+      if (o.install || o.uninstall) {
+        const agents = o.agent ? o.agent.split(",").map((a) => a.trim()).filter(Boolean) : undefined;
+        console.log(G.install(dir, { agents, global: o.global, remove: o.uninstall }));
+        break;
+      }
+      console.log(G.report(dir));
+      break;
+    }
+    case "waive": {
+      const G = await import("../src/guard.mjs");
+      if (o.remove) console.log(G.removeWaiver(dir, o.remove, o.file));
+      else if (!args[0]) {
+        const w = G.readWaivers(dir);
+        console.log(w.length ? w.map((x) => `${x.id}${x.file ? ` · ${x.file}` : ""} · ${x.reason} (${x.by}, ${x.at.slice(0, 10)})`).join("\n") : "No waivers in this project.");
+      } else {
+        const r = G.addWaiver(dir, { id: args[0], file: o.file, reason: o.reason, by: "user" });
+        console.log(r.message);
+        if (!r.ok) process.exitCode = 1;
+      }
+      break;
+    }
+    case "refs": {
+      const { refsReport, addNote } = await import("../src/refs.mjs");
+      if (args[0] === "add" || args[0] === "mine" || args[0] === "rm") {
+        const { addRefs, listRefs, refsAddText, removeRef } = await import("../src/loop/myrefs.mjs");
+        if (args[0] === "add") {
+          if (!args[1]) throw new Error('Usage: palate refs add <image or url> [...] [--like "what you like about it"] [--dislike "what you don\'t"] [--kind landing]');
+          const added = await addRefs(args.slice(1), { note: o.note ?? "", like: o.like, dislike: o.dislike, kinds: o.kind ? o.kind.split(",") : undefined });
+          console.log(refsAddText(added));
+        } else if (args[0] === "rm") {
+          if (!args[1]) throw new Error("Usage: palate refs rm <id>");
+          const { ref, rules } = removeRef(args[1]);
+          console.log(`Removed ${ref.source} (${ref.id})${rules.length ? ` and its rules: ${rules.map((r) => `${r.id} ${r.rule}`).join("; ")}` : ""}`);
+        } else {
+          const mine = listRefs();
+          console.log(mine.length ? mine.map((r) => `${r.id}  ${r.source}${r.likes?.length ? `  · likes: ${r.likes.join("; ")}` : ""}${r.dislikes?.length ? `  · dislikes: ${r.dislikes.join("; ")}` : ""}${r.note ? `  · ${r.note}` : ""}${r.rules?.length ? `  · rules ${r.rules.join(", ")}` : ""}`).join("\n") : "No references yet. Add some: palate refs add <image or url> --like \"…\" --dislike \"…\"");
+        }
+        break;
+      }
+      if (args[0] === "note") {
+        if (!args[1] || !args[2]) throw new Error('Usage: palate refs note <id> "what worked"');
+        console.log(`Saved note ${addNote(args[1], args.slice(2).join(" "))} for ${args[1]}`);
+        break;
+      }
+      const query = { shelf: o.shelf, industry: o.industry, audience: o.audience, tone: o.tone, needs: o.needs, theme: o.theme, words: args.join(" ") };
+      console.log(await refsReport(query, { dir, count: o.count ? Number(o.count) : 3 }));
+      break;
+    }
+    case "capture": {
+      if (!args[0]) throw new Error("Usage: palate capture <url> [--widths 1440,390]");
+      const { capture, captureReport } = await import("../src/capture.mjs");
+      const widths = o.widths ? o.widths.split(",").map(Number) : [1440];
+      console.log(captureReport(await capture(args[0], { widths })));
+      break;
+    }
+    case "system": {
+      const [sub, ...rest] = args;
+      if (sub === "pick") {
+        const { pickReport } = await import("../src/systems/pick.mjs");
+        if (!rest.length) throw new Error('Usage: palate system pick "<what you are building, in the user\'s words>"');
+        console.log(pickReport(rest.join(" "), { dir }));
+      } else if (sub === "apply") {
+        const { applySystem } = await import("../src/systems/apply.mjs");
+        if (!rest[0]) throw new Error("Usage: palate system apply <id> [--no-keep-brand]");
+        console.log(applySystem(rest[0], dir, { keepBrand: !o["no-keep-brand"], typeFrom: o["type-from"] }));
+      } else if (sub === "list") {
+        const { loadSystems } = await import("../src/systems/load.mjs");
+        for (const s of loadSystems()) console.log(`${s.id.padEnd(16)} ${s.facets.theme.padEnd(5)} ${s.facets.accent.padEnd(9)} ${s.facets.radius.padEnd(6)} ${s.facets.elevation.padEnd(8)} ${s.name}`);
+      } else if (sub === "show") {
+        const { loadSystems } = await import("../src/systems/load.mjs");
+        const s = loadSystems().find((x) => x.id === rest[0]);
+        if (!s) throw new Error(`No design system "${rest[0]}"`);
+        console.log(fs.readFileSync(s.file, "utf8"));
+      } else {
+        throw new Error("Usage: palate system pick <request> | apply <id> | list | show <id>");
+      }
+      break;
+    }
+    case "mcp": {
+      // The server keeps the process alive on stdin; nothing else to do here.
+      await import("../src/mcp/server.mjs");
+      break;
+    }
+    case "plan": {
+      if (!args.length) throw new Error('Usage: palate plan "<the request, in the user\'s words>" [--route /x] [--mode direct|build|direction|quick|full]');
+      const { plan, planText } = await import("../src/loop/plan.mjs");
+      console.log(planText(plan(dir, args.join(" "), { route: o.route, mode: o.mode, name: o.name }), { name: o.name }));
+      break;
+    }
+    case "variants": {
+      const { variants } = await import("../src/loop/variants.mjs");
+      console.log(await variants(dir, args.join(" "), { name: o.name, count: o.count ? Number(o.count) : undefined, per: o.per ? Number(o.per) : undefined, quick: Boolean(o.quick), refs: o.refs ? o.refs.split(",") : [], mode: o.mode, full: Boolean(o.full), route: o.route }));
+      break;
+    }
+    case "judge": {
+      if (!o.name) throw new Error("Usage: palate judge --name <loop> [--scores file.json] [--keep 4] [--watch --ready 4]");
+      const { judge } = await import("../src/loop/judge.mjs");
+      console.log(await judge(dir, o.name, { scores: o.scores, keep: o.keep ? Number(o.keep) : 4, url: o.url, watch: Boolean(o.watch), ready: o.ready ? Number(o.ready) : undefined }));
+      break;
+    }
+    case "pick": {
+      if (!o.name) throw new Error("Usage: palate pick --name <loop> [--ready 4]");
+      const { pick } = await import("../src/loop/pick.mjs");
+      console.log(await pick(dir, o.name, { routes: args.length ? args : undefined, url: o.url, open: !o["no-open"], pairsMode: Boolean(o.pairs), ready: o.ready ? Number(o.ready) : undefined }));
+      break;
+    }
+    case "build": {
+      if (!o.name && !args[0]) throw new Error('Usage: palate build "<the job>" --route /x  (build mode)  ·  palate build --name <loop>  (after a variants pick)');
+      const { build, buildBrief } = await import("../src/loop/build.mjs");
+      // A job in words is build mode; a lone route or --name alone builds out a variants winner.
+      const winner = (args.length === 1 && /^\/\S*$/.test(args[0])) || (!args.length && o.name);
+      console.log(winner ? build(dir, { name: o.name, route: args[0] }) : await buildBrief(dir, args.join(" "), { route: o.route, name: o.name, direction: o.direction, refs: o.refs ? o.refs.split(",") : [], like: (o.like ?? []).flatMap((x) => x.split(",")), url: o.url, duel: Boolean(o.duel) }));
+      break;
+    }
+    case "blueprint": {
+      const B = await import("../src/loop/blueprint.mjs");
+      if (o.file) console.log(B.saveBlueprint(dir, o.file, { name: o.name }));
+      else console.log(await B.blueprintBrief(dir, args.join(" "), { route: o.route, name: o.name, direction: o.direction, url: o.url }));
+      break;
+    }
+    case "gate": {
+      if (!args[0]) throw new Error("Usage: palate gate <route> [--answers <dir|files>] [--restore <round>]");
+      const { gate, duel } = await import("../src/loop/gate.mjs");
+      if (o.duel) {
+        console.log(await duel(dir, args[0], { section: o.duel, url: o.url, answers: o.answers }));
+        break;
+      }
+      const res = await gate(dir, args[0], { url: o.url, answers: o.answers ? o.answers.split(",") : undefined, restore: o.restore, job: o.text, judge: o.judge });
+      console.log(res);
+      if (/below the bar/.test(res)) process.exitCode = 1;
+      break;
+    }
+    case "match": {
+      const { match } = await import("../src/loop/match.mjs");
+      const res = await match(dir, args[0], { route: o.route ?? "/", width: o.width ? Number(o.width) : undefined, check: Boolean(o.check), answers: o.answers, restore: o.restore, url: o.url });
+      console.log(res.text);
+      if (res.stopped || res.notReady) process.exitCode = 1;
+      break;
+    }
+    case "section": {
+      if (!args[0] || !args[1]) throw new Error("Usage: palate section <route> <section id, name or selector> [--early | --verdict]");
+      const { sectionCheck, sectionVerdict } = await import("../src/loop/gate.mjs");
+      if (o.verdict) console.log(sectionVerdict(dir, args[0], args.slice(1).join(" ")));
+      else console.log(await sectionCheck(dir, args[0], args.slice(1).join(" "), { url: o.url, judge: Boolean(o.early) }));
+      break;
+    }
+    case "sections": {
+      const S = await import("../src/sections.mjs");
+      if (args[0] === "show") {
+        for (const id of args.slice(1)) console.log(S.sectionBrief(id));
+        break;
+      }
+      const tags = o.tags ? o.tags.split(",").map((x) => x.trim()) : [];
+      const list = o.kind ? S.matchSections({ kind: o.kind, tags, limit: o.limit ? Number(o.limit) : 12 }) : S.loadSections();
+      for (const s of list) console.log(`${s.id.padEnd(40)} ${s.kind.padEnd(11)} ${String(s.shape).padEnd(18)} ${s.layout}`);
+      break;
+    }
+    case "imagery": {
+      const I = await import("../src/loop/imagery.mjs");
+      const sources = o.sources ? o.sources.split(",") : undefined;
+      if (args[0] === "treatment") {
+        // The one treatment every photo on the page shares, as a CSS file in the project (import it once).
+        const name = args[1] ?? "duotone";
+        const css = I.treatmentCss(name, { shadow: o.shadow, highlight: o.highlight, colour: o.colour, opacity: o.opacity ? Number(o.opacity) : undefined });
+        const into = fs.existsSync(path.join(dir, "src")) ? path.join(dir, "src", "palate-photo.css") : path.join(dir, "palate-photo.css");
+        fs.writeFileSync(into, `/* palate imagery treatment ${name}: one treatment for every photo on the page. Wrap photos in .palate-photo. */\n${css}\n`);
+        console.log(`Wrote ${into.replace(/\\/g, "/")}. Import it once (e.g. @import "./palate-photo.css"; in your main CSS) and wrap each photo in <div class="palate-photo">.`);
+      } else if (args[0] === "pick") console.log(await I.pickImages(dir, args.slice(1), { slug: o.from, out: o.out, trim: !o["no-trim"] }));
+      else if (/\||\n/.test(args.join(" "))) console.log(await I.imageryMany(dir, args.join(" "), { count: o.count ? Number(o.count) : undefined, sources, type: o.type, refresh: Boolean(o.refresh) }));
+      else console.log(await I.imagery(dir, args.join(" "), { count: o.count ? Number(o.count) : undefined, sources, type: o.type, artist: o.artist, refresh: Boolean(o.refresh) }));
+      break;
+    }
+    case "icons": {
+      const { icons } = await import("../src/loop/icons.mjs");
+      console.log(await icons(dir, args, { mono: o.mono, out: o.out }));
+      break;
+    }
+    case "texture": {
+      if (!args[0]) throw new Error("Usage: palate texture <grain|paper|speckle|halftone|linen> [--colour #hex] [--opacity 0.1]");
+      const I = await import("../src/loop/imagery.mjs");
+      console.log(I.writeTexture(dir, args[0], { colour: o.colour, opacity: o.opacity ? Number(o.opacity) : undefined, seed: o.seed }));
+      break;
+    }
+    case "bench": {
+      const Bn = await import("../src/loop/bench.mjs");
+      const [sub = "list", id] = args;
+      if (sub === "list") for (const b of Bn.listBriefs({ category: o.kind })) console.log(`${b.id.padEnd(24)} ${b.category.padEnd(18)} ${b.job}`);
+      else if (sub === "new") {
+        if (!id || !o.into) throw new Error("Usage: palate bench new <id> --into <folder>");
+        console.log(Bn.scaffold(id, path.resolve(o.into)));
+      } else if (sub === "record") {
+        if (!id) throw new Error("Usage: palate bench record <id> [--from <gate round dir>] [--minutes n] [--note text]");
+        const { benchResultFrom } = await import("../src/loop/gate.mjs");
+        const row = Bn.recordResult(id, { ...benchResultFrom(dir, { from: o.from }), minutes: o.minutes ? Number(o.minutes) : undefined, notes: o.note });
+        console.log(JSON.stringify(row, null, 1));
+      } else if (sub === "report") console.log(Bn.benchReport({ release: o.release }));
+      else if (sub === "pick") {
+        const { benchPick } = await import("../src/loop/benchpick.mjs");
+        console.log(await benchPick({ dirs: o.dirs ? o.dirs.split(",") : [], open: !o["no-open"] }));
+      }
+      else throw new Error("Usage: palate bench list | new <id> --into <folder> | record <id> | report");
+      break;
+    }
+    case "direction": {
+      const D = await import("../src/loop/direction.mjs");
+      // --auto: the user said "just build it" (palate picks from taste); --choose user: always the picker.
+      if (o.ideas) console.log(await D.pickDirection(dir, { file: o.ideas, name: o.name, open: !o["no-open"], choose: o.auto ? "auto" : o.choose }));
+      else console.log(D.direction(dir, args.join(" "), { route: o.route, name: o.name, fromResearch: o["from-research"] }));
+      break;
+    }
+    // ── palate research: competitors and craft, looked at live, before ideation (src/loop/research.mjs) ──
+    case "research": {
+      const R = await import("../src/loop/research.mjs");
+      if (o.like?.length || o.dislike?.length) {
+        const v = [...(o.like ?? []).flatMap((x) => x.split(",")).map((id) => ({ id: id.trim(), verdict: "like" })), ...(o.dislike ?? []).flatMap((x) => x.split(",")).map((id) => ({ id: id.trim(), verdict: "dislike" }))];
+        const saved = R.recordVerdicts(dir, o.name, v);
+        console.log(saved.length ? `Noted: ${saved.map((s) => `${s.verdict} ${s.ref} ${s.name}`).join(", ")}. palate ranks with it next time; the same trait twice becomes a proposed rule at palate taste learn.` : "No matching references (use their ids, R1, R2 …).");
+        break;
+      }
+      const list = (s) => (s == null ? null : s === "none" || s === "" ? [] : s.split(",").map((x) => x.trim()).filter(Boolean));
+      const res = await R.research(dir, args.join(" "), { route: o.route, name: o.name, urls: list(o.urls) ?? (o.inspire || o["index-only"] ? [] : null), inspire: list(o.inspire) ?? [], keep: o.keep ? Number(o.keep) : undefined });
+      console.log(res.text);
+      break;
+    }
+    // ── end palate research ──
+    case "forget": {
+      const { forget } = await import("../src/loop/forget.mjs");
+      console.log(forget(args[0], { dryRun: Boolean(o["dry-run"]) }));
+      break;
+    }
+    case "stats": {
+      const { stats } = await import("../src/loop/stats.mjs");
+      console.log(stats(dir, { limit: o.limit ? Number(o.limit) : 10 }));
+      break;
+    }
+    case "polish": {
+      if (!args[0]) throw new Error("Usage: palate polish <route>");
+      const { polish } = await import("../src/loop/polish.mjs");
+      console.log(await polish(dir, args[0], { url: o.url }));
+      break;
+    }
+    case "critique": {
+      const { critique, reviewFindings } = await import("../src/loop/critique.mjs");
+      if (o.findings) {
+        console.log(await reviewFindings(dir, o.findings, { open: !o["no-open"] }));
+        break;
+      }
+      if (!args[0]) throw new Error("Usage: palate critique <route> [--url …]  ·  palate critique --findings <file>");
+      console.log((await critique(dir, args[0], { url: o.url })).sheet);
+      break;
+    }
+    case "fix": {
+      if (!args[0]) throw new Error("Usage: palate fix <route> [--verify]");
+      const { fix } = await import("../src/loop/fix.mjs");
+      console.log(await fix(dir, args[0], { url: o.url, verify: Boolean(o.verify) }));
+      break;
+    }
+    case "vary": {
+      if (!args[0] || !o.section) throw new Error('Usage: palate vary <route> --section "<name or selector>" [--count 3] [--brief "<what you want>"]');
+      const { vary } = await import("../src/loop/vary.mjs");
+      console.log(await vary(dir, args[0], { section: o.section, count: o.count ? Number(o.count) : 3, url: o.url, brief: o.brief }));
+      break;
+    }
+    case "details": {
+      if (!args[0]) throw new Error("Usage: palate details <route>");
+      const { details } = await import("../src/loop/details.mjs");
+      console.log(await details(dir, args[0], { url: o.url }));
+      break;
+    }
+    case "states": {
+      if (!args[0]) throw new Error("Usage: palate states <route> [--url …] [--verify]");
+      const { states } = await import("../src/loop/states.mjs");
+      console.log((await states(dir, args[0], { url: o.url, verify: Boolean(o.verify) })).text);
+      break;
+    }
+    // ── palate finish: the finishing pass in one process (one browser, one dev server, kept warm between steps) ──
+    case "finish": {
+      if (!args[0]) throw new Error("Usage: palate finish <route> [--url …]");
+      const route = args[0];
+      const t0 = Date.now();
+      const step = async (name, fn) => {
+        const t = Date.now();
+        try {
+          const out = await fn();
+          return { name, out: typeof out === "string" ? out : out?.text ?? out?.report ?? "", ms: Date.now() - t };
+        } catch (e) {
+          return { name, out: `${name} failed: ${e.message}`, ms: Date.now() - t, failed: true };
+        }
+      };
+      const { states } = await import("../src/loop/states.mjs");
+      const { details } = await import("../src/loop/details.mjs");
+      const { animate } = await import("../src/loop/animate.mjs");
+      const parts = [];
+      parts.push(await step("shoot", async () => (await shoot(dir, route, { url: o.url })).report));
+      // The three read the page without changing it: run them side by side on the shared browser and server.
+      parts.push(...(await Promise.all([step("states", () => states(dir, route, { url: o.url })), step("details", () => details(dir, route, { url: o.url })), step("animate", () => animate(dir, route, { url: o.url, checkOnly: true }))])));
+      const { matchedRoute } = await import("../src/loop/matched.mjs");
+      const userDesign = matchedRoute(dir, route);
+      console.log(
+        [
+          ...(userDesign ? [`${route} is built from the user's own design (palate match): fix only what breaks (missing states, contrast, clipping, the phone layout) and never restyle what the design shows. Its gate is palate match --check --route ${route}, not palate gate.`, ""] : []),
+          `# Finishing pass ${route}: ${parts.map((p) => `${p.name} ${(p.ms / 1000).toFixed(0)}s`).join(" · ")} · ${((Date.now() - t0) / 1000).toFixed(0)}s in all`,
+          "",
+          "Fix what each part names (the states and details briefs list their files), in that order, then palate states --verify and palate gate.",
+          "",
+          ...parts.flatMap((p) => [`## ${p.name}`, p.out.trim(), ""]),
+        ].join("\n"),
+      );
+      break;
+    }
+    case "animate": {
+      if (!args[0]) throw new Error("Usage: palate animate <route> [--check]");
+      const { animate } = await import("../src/loop/animate.mjs");
+      console.log(await animate(dir, args[0], { url: o.url, checkOnly: Boolean(o.check) }));
+      break;
+    }
+    case "point": {
+      const P = await import("../src/point/server.mjs");
+      const [sub, ...rest] = args;
+      if (sub === "next") {
+        console.error("Waiting for the user to point at something…");
+        let r = null;
+        while (!r) r = await P.nextRequest(dir, { wait: 55, agent: "cli" });
+        console.log(r.stopped ? "The user stopped point mode (Done in the overlay). Stop waiting for pins." : P.formatRequest(r, dir));
+      } else if (sub === "stop") {
+        await P.stopPointMode(dir);
+        console.log("Point mode stopped: the agent finishes the pins already sent, then its next call says so.");
+      } else if (sub === "done") {
+        if (!rest[0]) throw new Error('Usage: palate point done <id> "<one-line summary>" [--removed] [--override]');
+        const r = await P.doneRequest(dir, rest[0], rest.slice(1).join(" "), { removed: Boolean(o.removed), override: Boolean(o.override) });
+        const ow = r.other?.width ? r.other : null;
+        console.log(`Pin ${r.n} is done.${r.removed ? " Removed: the pin shows that instead of an after crop." : r.after ? ` Before: ${r.crop}  After: ${r.after}` : " (no after crop: the element could not be shot)"}${ow ? `\nAt ${ow.width}: ${ow.after?.removed ? "removed" : `before ${ow.before?.crop ?? "(none)"}  after ${ow.after?.crop ?? "(none)"}`}\n${ow.note ?? ""}${ow.overridden ? " Done anyway (--override)." : ""}` : ""}`);
+      } else if (sub === "crop") {
+        if (!rest[0]) throw new Error("Usage: palate point crop <id>");
+        const c = await P.cropRequest(dir, rest[0]);
+        const ow = c.other;
+        console.log(`${c.removed ? "Removed: the element is gone (as asked)." : `Now: ${c.file}${c.found === false ? " (selector not found; the region where it was)" : ""}`}${c.trail ? `
+Opened by: ${c.trail}${c.reopen?.state === "couldn't reopen" ? `
+Couldn't reopen it for this check: ${c.reopen.why}. Not a break; check the change in the code.` : " (reopened for the check)"}` : ""}
+Before: ${c.before}${ow ? `\nAt ${ow.width}: now ${ow.after ?? "(none)"}  before ${ow.before ?? "(none)"}\n${ow.note}${ow.verdict === "broke" ? `\nFix ${ow.width} before palate point done: it refuses while ${ow.width} is broken.` : ""}` : ""}`);
+      } else {
+        const s = await P.startPoint(dir, { url: o.url, route: sub ?? "/", open: !o["no-open"] });
+        const auto = o.auto || o.agent || o["agent-cmd"] ? await (await import("../src/point/auto.mjs")).runAuto(dir, { agent: o.agent ?? "claude", agentCmd: o["agent-cmd"], yolo: Boolean(o.yolo) }) : null;
+        const live = auto && !auto.missing;
+        console.log(
+          live
+            ? `Point at anything in ${s.link} and send it: palate runs the agent on each pin by itself.${s.reused ? " (point was already running; this process only runs the agent)" : ""}   (Ctrl+C stops)`
+            : s.reused
+              ? `palate point is already running: ${s.link}`
+              : `Point at anything in ${s.link} to ask for a change. Your agent takes the pins: in Claude Code run /mcp__palate__point${auto?.missing ? "" : ", or start this with --auto"}.   (Ctrl+C stops)`,
+        );
+        if (!s.reused || live) {
+          process.on("SIGINT", async () => {
+            await auto?.stop();
+            await s.stop();
+            process.exit(0);
+          });
+          await (s.reused ? auto.done : s.done);
+        }
+      }
+      break;
+    }
+    case "taste": {
+      const { taste } = await import("../src/loop/taste.mjs");
+      console.log(taste(args[0], { from: o.from, dir }));
+      break;
+    }
+    case "rule":
+    case "rules": {
+      const [sub = "list", ...rest] = args;
+      if (sub === "review") {
+        const { reviewRules } = await import("../src/loop/rulereview.mjs");
+        console.log(await reviewRules({ open: !o["no-open"] }));
+        break;
+      }
+      const { rule } = await import("../src/loop/fail.mjs");
+      console.log(rule(sub, o.all ? [...rest, "--all"] : rest, { kind: o.kind, source: o.source, only: o.only, route: o.route, scope: o.scope, text: o.text, project: o.project, dir }));
+      break;
+    }
+    case "fail": {
+      if (!args[0] || !args[1]) throw new Error('Usage: palate fail <route> "<why it is bad>" [--kind landing] [--shot a.png,b.png]');
+      const { fail } = await import("../src/loop/fail.mjs");
+      console.log(await fail(dir, args[0], args.slice(1).join(" "), { kind: o.kind, shots: o.shot != null ? o.shot.split(",").filter(Boolean) : undefined, url: o.url, project: o.project }));
+      break;
+    }
+    // ── palate moves: the moves library (src/moves.mjs) ──
+    case "moves": {
+      const M = await import("../src/moves.mjs");
+      if (args[0] === "show") {
+        if (!args[1]) throw new Error("Usage: palate moves show <id> [id...]");
+        console.log(args.slice(1).map(M.showMove).join("\n\n---\n\n"));
+      } else if (args[0] === "brief") {
+        if (!args[1]) throw new Error("Usage: palate moves brief <id,id,...>");
+        console.log(M.moveBrief(args.slice(1).join(",")));
+      } else {
+        const tags = [o.tags, ...args].filter(Boolean).join(",").split(",").map((t) => t.trim()).filter(Boolean);
+        const q = { tags, kind: o.kind, signature: o.signature ? true : undefined, limit: o.limit ? Number(o.limit) : tags.length ? 8 : 0 };
+        console.log(M.movesReport(M.matchMoves(q), q));
+      }
+      break;
+    }
+    // ── end palate moves ──
+    case "concept": {
+      const { conceptReport, recordConcept } = await import("../src/concept.mjs");
+      if (args[0] === "record") {
+        if (!args[1] || !o.moves) throw new Error('Usage: palate concept record "<screen>" --moves a,b,c');
+        console.log(recordConcept(dir, args.slice(1).join(" "), o.moves.split(",").map((m) => m.trim()).filter(Boolean)));
+        break;
+      }
+      if (!args.length) throw new Error('Usage: palate concept "<what you are building, in the user\'s words>"');
+      console.log(conceptReport(args.join(" "), { dir, count: o.count ? Number(o.count) : 3 }));
+      break;
+    }
+    case "catalog": {
+      const [sub, source] = args;
+      if (sub === "sync" && source === "vibrant") {
+        const { syncVibrant } = await import("../src/catalog/vibrant.mjs");
+        const { file, count } = await syncVibrant({ limit: o.limit ? Number(o.limit) : Infinity, refresh: Boolean(o.refresh) });
+        console.log(`Saved ${count} records to ${file}`);
+      } else if (sub === "index") {
+        const { buildIndex } = await import("../src/catalog/index-build.mjs");
+        const { file, count } = await buildIndex();
+        console.log(`Wrote ${count} records (facts and links only) to ${file}`);
+      } else if (sub === "stats") {
+        const { catalogStats } = await import("../src/refs.mjs");
+        console.log(catalogStats());
+      } else {
+        throw new Error("Usage: palate catalog sync vibrant [--limit n] | palate catalog stats");
+      }
+      break;
+    }
+    default:
+      console.log(HELP);
+      if (cmd) process.exitCode = 1;
+  }
+} catch (err) {
+  console.error(String(err?.message ?? err));
+  process.exitCode = 1;
+} finally {
+  // One browser and dev server served the whole command; close them (the MCP server keeps its own).
+  if (cmd !== "mcp") await closePool();
+}