@palate/cli 0.0.0-stage → 0.0.1

package/skill/palate/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: palate
+description: Design intelligence that does the last 20%. Use for any request to build, redesign, improve or polish a screen, page, section or component (dashboards, app screens, landing pages, docs, shops, mobile). It triages each request first; by default it builds once from the user's references, notes and rules, runs the finishing pass (screenshots, details, critique on request), then lets the user point at what's wrong. A job-level question ("users wait 20 seconds here, what should they see?") gets 3 short ideas first; a new screen gets research first (competitors and well-crafted pages looked at live, 3 art directions with a signature moment, then one build); variants only when the user asks to explore. The user's rules are checked on every build, so they never repeat a mistake.
+---
+
+# palate
+
+AI gets a screen 80% of the way. The last 20% is taste, ideas, experience and iteration: the references the user loves and why, the spacing and hierarchy fixes, the details AI overlooks (states, edge cases, motion), and never repeating what they rejected. Palate does that part, the way the user would: **build → finish → point**. It remembers their references and notes, turns what they keep rejecting into rules checked on every build (each one shown with its scope for their OK first), and only explores variants when they ask.
+
+The `palate` command is: `{{PALATE}}`
+Run it from the project folder. Examples below write it as `palate`.
+
+The checks and the finishing pass are free (`palate guard`, `copy`, `check`, `shoot`, `finish`, `states`, `details`, `animate`, `gate`, `imagery`, `texture`, `icons`). The rest is invite-only: if a command answers "This part of palate is invite-only", tell the user and ask for their invite code (`palate-XXXX-XXXX-XXXX`), then run `palate activate <code>` (once per machine; only the code and a random machine id are sent). `palate activate --status` shows the state.
+
+## Always first: triage
+
+```
+palate plan "<the request, in the user's words>" [--route /x]
+```
+
+palate decides what the request deserves, says why, and estimates its token cost. Follow it; the user can override with `--mode`.
+- **direct**: a fix, tweak, copy change, something a critique or details pass already pinpointed, or exact changes to an existing page ("move the button outside the bar", "make the cards play on their own", "pastel instead of dots, no black"). The kind of screen comes from the route (the root page is a landing page), not from words in the request. Take the direct path below.
+- **build** (the default): anything that isn't a fix, a question or an ask to explore. One build of the real route, the finishing pass, then the user points at what's wrong. See "Build mode".
+- **direction**: a job-level question or problem ("users wait ~20 seconds here, what should we show them so they don't leave?", "how should onboarding work?"). 3 short ideas with rough wireframes first, the user picks one, then build mode. See "Direction".
+- **research** (the default for a new screen): a new page or screen with no strong taste history, or an ask for something new or creative ("make it stand out", "not generic"). palate looks at competitors and well-crafted pages live, you propose 3 art directions with one signature moment each, palate picks one from taste or asks, then one build. See "Research and art direction". You run every step yourself; never ask the user to type a command.
+- **match**: the user gave their own design to build ("match this design", "build it from my screenshot / mockup / Figma frame", "make it look exactly like this", an image or a Figma link to implement). The design is the spec, not palate's taste. See "Match mode". An image given as a reference or for inspiration is not this: add it with `palate refs add`.
+- **quick / full (variants, opt-in)**: only when the user asks to explore ("options", "directions", "variants", "a few ideas"). The triage prints their token cost next to build mode's: tell the user and offer build mode as the cheaper choice. See "Variants".
+
+`palate stats` shows how long loops took and the estimated tokens per mode.
+
+Then read the project and **the user's taste profile**:
+
+```
+palate context
+palate taste
+```
+
+`palate taste` opens with **what palate has learned about the user**: their rules by kind of screen, the newest rules, and how often palate's top-ranked variant was their pick. The profile below it is learned from their own picks; the section for this kind of screen matters most.
+
+## The user's references, with their notes
+
+References come first, and what the user says about them matters more than the picture. When the user gives a screenshot, image or URL ("like Stripe's billing page"):
+
+```
+palate refs add <file or url> --like "the calm spacing" --dislike "gradient buttons"
+```
+
+If they didn't say what they like and dislike about it, **ask them**, one short line each, then add the notes. Each note becomes a rule tied to that reference: a like becomes a question for the judge ("does it have the calm spacing of that reference?"), a dislike becomes a measured rule when palate can measure it ("gradient buttons" → no gradient fills on buttons, checked on every shoot) or a judge rule otherwise. Every brief lists each reference with its likes and dislikes. `palate refs mine` lists them; `palate refs rm <id>` removes one and the rules that came only from it.
+
+## The user's rules (must pass)
+
+The profile says what the user likes; **rules say what must hold**. They live in `~/.palate/taste/rules.json`, each short and testable, with a scope (everywhere, kinds of screen like landing, team or settings, one route, or one component) and a check: measured in the page (framed screenshots = 0, kicker labels in at most one section, logo marks ≥ 24px, no step bar before the demo…) or, when it can't be measured, a question the judge must answer. A rule for one component is always the judge's question ("Only for <RoleBadge>: …"), since a measurement reads the whole page.
+
+- **Every brief opens with them**: "Built from N of your rules and M past picks", then "Your rules (must pass)" for this kind of screen and "Don't do this": the user's past failures for it, with screenshots. A rule beats a reference, a direction and your own idea.
+- **`palate shoot` checks them**: "Rules: 7 pass, 1 fail: …". A failing rule is a bug: fix it before anything else, and never call a page done while one fails.
+- **The judge enforces them**: a variant that fails a measured rule ranks below every variant that passes; the rubric asks the unmeasurable ones as true/false questions, and a "false" costs score.
+- **The user's own words apply at once**: when they state a rule, `palate rule add "<rule>" [--kind landing | --only <Component> | --route /x]`. Notes on their references become rules too.
+- **What palate infers is only proposed.** One pin is a one-off fix. A pattern (the same ask twice, a critique finding they agreed with, `palate fail <route> "<their words>"` when they call a screen bad) becomes a *proposed* rule with the scopes its evidence supports and a suggested one (the narrowest that holds: one component, one route, a kind of screen, or everywhere). Nothing carries into later builds until the user keeps it. When `palate taste learn` or `palate fail` proposes rules, run `palate rule review`: a board opens in their browser where they edit the wording, choose where it applies, and keep or discard each one. Or ask in chat and run `palate rule ok <id> [--only <Component> | --route /x | --kind team | --scope all] [--text "…"]` / `palate rule no <id>`. Never keep one they didn't agree to. A discarded proposal is remembered and comes back only with clearly new evidence.
+- `palate rule list` shows the active rules, then the proposals "Waiting for your OK". `palate rule edit <id> "…" | rm <id>`.
+
+## Build mode (the default): build → finish → point
+
+**1. Frame the job** in three lines: who uses it and how often, the one question it must answer, the primary action. **Skin, if needed:** if the project has no deliberate design yet, `palate system pick "<request>"` then `palate system apply <id>` gives it a real design system's tokens and type roles (read `.palate/system.md`). If it already has one, keep it.
+
+**2. One build.**
+```
+palate build "<the job, in the user's words>" --route /x [--refs a.png,https://…] [--direction <name>]
+```
+**A new page is decided before it is built.** `palate build` on a new page answers with the blueprint step first: `palate blueprint "<job>" --route /x` writes a planner brief. Plan it yourself or with a fresh subagent: expand the job into a spec (who it's for, the moment they care about, mood defended from the audience, **category truths to keep** and **clichés to avoid**), the system (colours by role including a `material` tone, a display face with character, numbers in the body face with tabular figures, mono only for real code), an imagery decision for every section (CC0 museum photos via `palate imagery`, textures via `palate texture`, the product's UI built in code, illustration in code, type alone for at most two sections) and one **archetype** per section from palate's library (`palate sections --kind <kind> --tags <mood>`; kb/sections: structure, finish, phone layout and the checks the judge will use). `palate blueprint --file <bp.json>` refuses plans that drift to the median page (neighbours with the same shape, one surface top to bottom, no material, weak contrast, a default display face) and saves the passing one with tokens (layered ink-tinted shadows, the primary button's gradient, inner highlight and ring, and the names the archetypes use).
+
+**Its own look, not palate's house style.** The blueprint also commits the page's visual language (`look`): the ground, texture, header, call-to-action style and how the main object is framed, plus the research references each decision learns from. palate refuses a plan that repeats one of its recent pages (in any project, benchmark pages included) on too many of: the ground, texture, the headline's type genre, the hero composition, the header, the call to action, the framing. The three art directions must span different visual worlds too, and the auto-pick ranks a look unlike palate's recent pages higher. The finish standard is craft (shadows, radii, spacing), never a default look: no default cream paper, no default grain.
+
+**An existing page gets the same, in its own brand.** On a route that exists, `palate build` (build mode) answers with the existing-page blueprint: palate captures the page as it is (first screen, whole page, one crop per section), and the plan keeps the brand (`"system": { "keep": true }`) and marks each section keep, upgrade (to an archetype, with why), remove or add. Only the upgraded and added sections get briefs; the gate also judges the result against the page as it was, and a change that made it worse fails. Small tweaks never come here: the triage sends them to direct mode.
+
+Then `palate build` again: one brief for the real route plus **one brief per section**. Each section builder checks only its own section with `palate section <route> <id>` (a crop at 1440 and 390 plus palate's floor checks for it, in seconds), not a full-page shoot. Build the foundation (tokens, fonts, imagery, the page shell) and the hero yourself, check the hero with `palate shoot <route> --fold`, then build every other section in parallel, one fresh subagent each, each owning its own component file and getting the care the hero got; then stitch the rhythm, the entrance and the phone layout. An existing route is changed in place from one brief: the user's rules, their references with their likes and dislikes, the taste profile's section for this kind of screen, and the direction they chose. Either way: finished, real content, every state the job needs, hover, focus and pressed states.
+
+**Moves (your call, not the user's).** Correct isn't remarkable. When building or upgrading a screen that is right but basic, pick its moves yourself from the moves library (`kb/moves`, named creative techniques with palate's recipes): `palate moves --tags <the brand's mood, e.g. calm,crafted> [--kind hero] [--signature]` (MCP: `palate_moves`, passing the user's kept/reverted history and the kind of screen when you have them), choose one signature move and one or two supporting ones that fit, then `palate moves brief <id,id>` and build from its recipes (perf, a11y, reduced motion and the no-JS fallback included). `palate moves show <id>` reads one in full.
+
+**3. The finishing pass,** on that page, without asking the user anything. `palate finish <route>` runs the shoot, states, details and the motion check in one process (about a minute); or step by step, in order: `palate shoot <route>` (both widths; a failing rule is fixed first, then a failing similarity gate, see below), `palate states <route>` (build the missing states, then `--verify`; see States below), `palate details <route>`, `palate animate <route> --check` if it moves, then `palate gate <route>` (see The quality gate below), `palate critique <route>` only if the user asks for a review. Then `palate check` (it says "Not done" while a rule, the similarity gate or the quality gate fails) and the project's typecheck. Before telling the user UI work is done, `palate guard` must pass: every changed screen looked at after its last edit, the copy (`palate copy`) and code tells clean, every CC BY photo credited, the gates passing. In a project with the guard's stop hook (`palate guard --install`, only when the user asks; Claude Code, Codex, Cursor, Gemini CLI, Copilot, or `--agent git` for a pre-commit check) it runs by itself when you stop. Without a hook, run `palate guard` yourself before saying you're done. A finding that is wrong here: `palate waive <id> --file <f> --reason "…"`, never to get past a real problem. Brand marks for a works-with row: `palate icons <brand…>`, never a drawn logo.
+
+**The similarity gate.** `palate shoot` fails (exit 1) when the page is more than 50% like a screen of the same kind in another of the user's projects (palate's layout memory), or too close to a reference the research step captured (42%, or the first screen as a picture above 72%). It says what is too close (page skeleton, hero structure, palette, type, the first screen as a picture) and what to change. Fix it yourself and shoot again; it isn't a question for the user. Taste is how the user judges (clarity, restraint, real content, their rules), not what their other projects looked like: a new product's colour, type and layout come from its own direction. Only when the user asked to match another project: `--like <project>` on build and shoot.
+
+**The quality gate: judged by someone who didn't build it.** The last step of every finishing pass, run without being asked. A builder grading its own work is too kind (Kiln, Oct 27: self-graded 6.7, about 5 to a person), and pairwise judging against real sites agrees with people far more than 1–10 scores.
+1. `palate gate <route>`: palate's floor checks first (two-sided: dead space, half-empty sections, one template repeated, one flat colour with no material, monospace as decoration, placeholder text, clipped text, a phone section that is an endless stacked list), then judge packets: a yes/no checklist per section (each archetype's checks plus a few for every section, calibrated with the user's own recent corrections from point) and the page beside the research's strongest real sites, in both orders.
+2. Run each packet with its own fresh subagent, in parallel: "Read <packet> and follow it exactly." Never judge your own build, and never tell the judges which page is ours. If you can't start subagents (Codex, Cursor): `palate gate <route> --judge api` runs the packets with a model API itself when a key is set (GEMINI_API_KEY or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY; a family other than the builder's is preferred); with neither, `--judge self`, and tell the user the verdict is self-judged.
+3. `palate gate <route> --answers <the round's folder>`: the verdict. It fails on a floor fail, a section the checklist says is below the bar, a page that doesn't feel like its subject or has no material, or a page clearly worse than a reference in both orders (a split verdict is a tie).
+4. Below the bar: palate snapshots the source and writes one repair brief per failing section (up to three), each scoped to its own section so parallel repairs don't undo each other; run them at the same time, one fresh subagent each. Repair it, then `palate gate <route>` again. Two repair rounds at most; a round that got worse is rolled back with `--restore <round>`. Then tell the user the verdict in one line, honestly: pass, or where it is still below the bar.
+`palate ambition <route>` still exists for an extra push on a page that passes.
+Mark the signature moment's element with `data-signature` so palate can find it.
+
+**4. The user points.** Offer `palate point <route>` (see "Fix it in place"): they click what's wrong in the running app and you fix exactly that. When they reject something, `palate fail`. When they're done, `palate taste learn`, and `palate rule review` if it proposed rules.
+
+## Match mode: the user's own design is the spec
+
+When the user hands you their design and wants it built faithfully, palate's taste steps aside: no blueprint, no archetypes, no house-look check, no similarity gate, and no improvements.
+
+```
+palate match <design.png | https://page | figma frame link> [--route /x] [--width 1440]
+```
+
+The source can be a PNG or JPG (a screenshot or a Figma export; 2400 px and wider is read as @2x unless `--width` says otherwise), a page URL (captured at `--width`, default 1440), or a Figma frame link (right-click the frame, Copy link to selection). A Figma link needs `FIGMA_TOKEN`; without it, tell the user to export the frame as PNG. palate saves the design in `.palate/match/<route>/`, measures what a still image shows (colours by share, surfaces, content blocks, the content's span) and writes `brief.md`. Follow it:
+1. **spec.json first.** Every value tagged `observed` (read from the image: colours, sizes, spacing, radii, positions; each text with its exact words, `size` and `y`), `inferred` (what a still can't show: hover, focus, pressed, the phone layout, hidden content, motion) or `substituted` (a paid or unknown font, a missing photo, another icon set, each with `instead` and `why`).
+2. **Build it** in the project's own stack and tokens: geometry, then type, spacing, colour and details. Content word for word.
+3. **The check.** `palate match --check --route /x` renders the build at the design's width, writes the two side by side and a difference image, measures what it can (colours by ΔE, text sizes and positions against the spec, motion), and writes one judge packet. Run it with a fresh subagent, never yourself, then `palate match --answers <dir> --route /x`: **READY**, **READY WITH SUBSTITUTIONS**, **NOT READY** (what's off, most visible first, with the fix; repair, then check again; two repair rounds at most, `--restore <n>` rolls a worse round back) or **UNVERIFIED** (something couldn't be checked: motion a still can't show, a build longer than the design).
+4. Tell the user the verdict in one line, every substitution, and what you inferred (states, the phone layout), so they can correct it.
+
+On a matched route `palate gate` and `palate build` point to the match brief, and `palate shoot` skips the similarity gate and the look. Contrast and clipping only warn: build the design as it is and tell the user; never change it silently.
+
+## Direction: ideas before a build
+
+For a job-level ask (what the triage calls direction), nothing is built until the user has chosen an idea:
+
+```
+palate direction "<the problem, in the user's words>" [--route /x]
+```
+
+It writes a short brief. Answer it with **3 different ideas**, each a name, 2–3 sentences (what the user sees and why it solves the problem) and a rough ASCII or tiny HTML wireframe; no code and no renders. Write them to the `ideas.json` the brief names, then:
+
+```
+palate direction --ideas <that file>
+```
+
+It opens a small picker in the user's browser: three cards, one click picks, an optional note. It returns their choice. Then build mode: `palate build "<the job>" --route /x` carries the chosen idea, its wireframe and the note into the brief.
+
+## Research and art direction (new screens)
+
+What a designer spends hours on before a new screen, done by you and palate with no human step unless it is a real judgement call. Run it when the triage says research.
+
+**1. Understand and search.**
+```
+palate research "<the job, in the user's words>" [--route /]
+```
+palate reads the job and the project (product, audience, industry, mood, a working metaphor, and whether the project **already has a brand**: its colour tokens, fonts and components, or **starts from scratch**) and prints web searches for competitors and category leaders. palate can't search: run them with your own web search tool and take 4–8 **official product homepages** (not listicles, review sites or design galleries).
+
+**2. Look.**
+```
+palate research "<the job>" --urls https://a.com,https://b.com   [--inspire https://c.com]   (--urls none: palate's own picks only)
+```
+palate looks at those pages plus a few from its own short list (kb/inspiration: links and its own notes, nothing else) **live, on this machine**: robots.txt respected for every page, one page at a time per site a few seconds apart, at most 12 pages, never logging in or submitting anything, skipping bot checks and CAPTCHAs (never working around them), declining cookie banners. It measures each (type scale, palette, spacing rhythm, layout skeleton, devices, motion, the principles pass), ranks them by craft, the user's taste (rules, profile, what they liked or disliked in earlier research) and diversity, keeps 4–6, and writes `.palate/research/<name>/`: `research.md`, `contact.png` and the screenshots (the user's private moodboard; gitignored, never uploaded or shipped). Per reference: what makes it work (drafted from measurements), the moves it uses, one thing this product could learn; and **what the competitors all do** (the cliché to avoid). **Open the contact sheet and the screenshots and refine the drafted notes in plain words.** If the user reacts to a reference ("love R2's type", "not R4"), record it: `palate research --name <n> --like R2 --dislike R4`.
+
+**3. Art directions.**
+```
+palate direction "<the job>" --from-research <name>
+```
+Answer its brief with **3 art directions**, safest to boldest, each with a name, a **metaphor**, **one signature moment** (a `signature: true` move from the moves library, adapted to this product), a section plan, a **provenance line** ("rhythm from R2, texture idea from R4, nothing copied") and a rough wireframe.
+- **The project has a brand**: each direction keeps its palette tokens, fonts and components (`brand`: how the metaphor lives inside them). A new colour or typeface only when the user asks for a rebrand.
+- **From scratch**: each direction defines a complete **starter system** drawn from its metaphor: colour tokens (palate checks AA), a licence-safe type pairing (Google Fonts / OFL or system) with its scale, radius scale, spacing rhythm, motion character, and licence-safe imagery (built in code, CC0 art, generated patterns).
+
+Then `palate direction --ideas <file>`. palate validates them and **decides whether to ask**: it picks a direction itself when the user's taste for this kind of screen is strong and one direction clearly leads, or when the user said "just build it" (`--auto`); otherwise it opens the picker in the user's browser and says why in one line ("Opening the picker: no history for pricing pages yet"). `--choose user` when the user asked to choose. Tell the user in one line what happened.
+
+**4. Build.** `palate build "<the job>" --route /` carries the direction, the signature move's recipe, the research notes (abstract only), the starter tokens to create first (or the brand to keep), and the rule: **use the ideas, never the expression**: no copied code, copy, images, illustrations, logos or paid fonts; nothing that looks like one specific site. **Deliver the signature moment; it will be checked**: `palate shoot` compares the page with every research reference (too close fails) and recalls the promised moment. Then the finishing pass and point, as in build mode.
+
+palate learns from all of it (in `~/.palate/taste`): the direction chosen (or picked and kept), its metaphor, signature move and starter system, the references liked or disliked, and which references fed the build. The next research ranks with it; `palate taste learn` proposes rules from repeats, for the user's OK.
+
+## Variants (opt-in)
+
+Only when the user asks to explore, or the triage says quick/full for a new kind of screen, and after offering build mode as the cheaper choice.
+
+**1. Sketches.**
+```
+palate variants "<the job, in the user's words>" --name <short-name>
+```
+It takes the count from the triage, chooses directions (what has won for this user before, plus one to explore), finds references for each, and writes one lean brief per direction. With `--refs`, one direction follows the user's reference closely, one blends it with their winning direction, and one explores. **The briefs are sketches:** the first screen and the page's centrepiece built to a finished standard, the rest stubbed; only the winner is built out (`--full` builds whole pages, slower). **Build every brief:** with subagents (Claude Code: the Agent/Task tool), start one per brief in parallel, each told to read its brief and follow it exactly; otherwise build them yourself one at a time. Don't install packages while variants are being built in parallel.
+
+**Checking while building is lean:** each builder runs one `palate shoot /<route> --widths 1440 --fold`, fixes the biggest problem and every rule it reports failing, and stops. The 390 check, the principles pass, `details` and `animate` run on the winner only.
+
+**2. Pick as soon as 4 are ready.** Don't wait for the slowest builder. Right after the briefs go out, start (in the background):
+```
+palate pick --name <name> --ready <n>
+```
+`<n>` is the number `palate variants` prints (4 in full mode, all of them in quick mode). It waits until that many variants are built and settled, then opens the picker in the user's browser by itself, blind and shuffled. The user clicks the best one (they can open any at full size first) and may tap reason chips. It returns the winner, the reasons, and how long the loop took. `--pairs` asks every A/B pair instead, for close calls.
+
+With more than 4 variants (full mode), judge first: `palate judge --name <name> --watch --ready 4` renders the first 4 built and writes a rubric. Have a **fresh** subagent score it (a judge must not grade its own work), including the true/false answers to the user's rules the rubric asks, then `palate judge --name <name> --scores <file>`, then `palate pick --name <name>` (it reuses the judge's renders; variants that landed later join only if fewer than 4 survived). The judge measures clarity for the job; it does not decide taste.
+
+**3. Build out the winner.**
+```
+palate build --name <name>
+```
+It writes the brief that completes the winning sketch into the full page: keep the first screen and centrepiece exactly, finish every stub to the same standard, carry over one part of a runner-up only if the user's reasons point to it. One builder. Then, on this page only: `palate shoot <route>` (both widths, principles), `palate details <route>`, `palate animate <route> --check` if it moves. Move it to the real route and delete the other variants.
+
+**4. Polish the winner.**
+```
+palate polish <route>
+```
+It shoots the before and tells you which polish skills are installed: Jakub Krehel's `better-interface` / `better-ui` and Emil Kowalski's `emil-design-eng`. Apply them in order, keep the idea and layout, shoot again, and keep a change only if the screenshot is better.
+
+**5. Finish and learn.**
+```
+palate blueprint "<job>" --route /x   (then --file bp.json: the design decided before code)
+palate gate <route>         (the independent quality gate: floor checks, judge packets, --answers, --restore)
+palate sections · palate imagery · palate texture · palate bench
+palate ambition <route>     (an extra push on a page that already passes the gate)
+palate check
+palate taste learn
+```
+Fix or justify `check` findings and run the project's build and typecheck. `taste learn` first proposes rules from patterns in the evidence (agreed findings, failures, the same ask twice), each with a suggested scope; if it proposed any, run `palate rule review` so the user keeps or discards them (a rule in the critique's words gets general words on the board). Then it prints the new evidence from the user's picks: update their taste profile (the file it names) with what won and why for this kind of screen, in 3–6 concrete bullets. Keep it short; it is read before every design.
+
+## The direct path (what triage calls direct)
+
+1. If it helps, `palate search "<the parts involved>"` and `palate show <ids>`: anatomy entries say what each component needs and how it behaves.
+2. Change it in place, in the project's stack, tokens and components. Real data only.
+3. One check: `palate shoot <route> --widths 1440 --fold` (add 390 only if the change is about the phone layout). Open the screenshot, fix what's wrong once. The plan printed the user's rules for this screen; none may fail after your change.
+4. `palate check`. No variants, judge or pick.
+
+## States (the last 20%)
+
+AI gets a screen 80% of the way. The rest is what designers do by hand and agents skip: every state of every part. After you build or change a screen that has data, lists, forms or images, and whenever the user asks about states, edge cases, loading, empty or errors:
+
+1. `palate states <route>` finds the stateful parts (lists, tables, card grids, forms, numbers, images, text from data, buttons that act) from the DOM and a quick read of the route's source, then renders each state without touching the code:
+   - **Data fetched in the browser:** it rewrites the app's own JSON with Playwright route mocks: empty, one item, 50 items (500 timed), 3× long names, emails and company names. It holds the data (loading at 1.2s and 2.8s; no answer at 8s) and fails it (500, network down).
+   - **Data written in the code** (a static page): it says so, simulates long text, many items and one item in the DOM, and lists what it couldn't simulate. Never pretend a static list can be empty.
+   - **Always:** images answered 404, 320 wide, and 200% zoom with a keyboard-only Tab pass. Every form is filled with test values and pressed twice, failed with a 500, sent offline and sent empty. Buttons outside forms are pressed twice. Every send is answered by palate, so nothing reaches the app's server.
+2. Each state is measured, not just pictured: overflow and clipping, text outside its box, a list with no empty state, nothing shown while loading (or a false "0" or "No items"), errors with no message, double submits, no pending state, values cleared on error, broken-image icons, focus that is hidden or lost, sideways scroll, raw `undefined`, "1 items".
+3. Open the contact sheet (`.palate/states/<route>/<stamp>/sheet.png`: one row per part, one column per state, ✗ on findings), then build what `states.md` lists, most important first. Use the project's own components (it names its Skeleton, Spinner, EmptyState, Alert when it finds them). Empty states say what's empty and what to do next, with the action as a button. Errors say what happened and what to do, with Try again, and never fall through to the empty state. Loading is a skeleton shaped like the content. Pending buttons ignore a second press.
+4. `palate states <route> --verify` renders every state again and puts each finding before | after, measured: fixed or still failing.
+
+`palate fix` includes the missing states. `palate critique` links the states sheet. Rules like "every list has an empty state" (`palate rule add`) are measured from the latest states run on every shoot.
+
+## Commands for specific jobs
+
+For an existing page, when the user asks for one of these (or it's clearly what they need):
+
+| The user wants | Run |
+|---|---|
+| A designer's review ("critique this", "what's wrong with it") | `palate critique <route>`: open every section crop in the sheet it writes (a summary; the rubric, every principle finding and the review guide are files next to it, opened when needed), write findings to its `findings.json` (specific: element, why, the exact fix; whole-page findings for repeated devices, static screenshots, no motion; an idea for each generic section). Then `palate critique --findings <file>`: the user agrees or disagrees on a board in their browser. Change no code during a critique. |
+| Fix it | `palate fix <route>`: a brief from the findings the user agreed with, most severe first (with no critique: what `palate shoot` measures). Afterwards `palate fix <route> --verify` puts each finding's section before \| after; report fixed, partly or not per finding. |
+| New versions of one section | `palate vary <route> --section "<name or selector>"`: copies the page into variant routes and writes one brief each (a different idea and references). Build them, then `palate pick --name <name it gives>`: the user sees each in the page, with the current section as an option. Move the winner into the page and delete the variant routes. |
+| States and edge cases (loading, empty, error, long names, many rows, offline, double submit) | `palate states <route>`: the contact sheet and a brief of the missing states; build them, then `palate states <route> --verify`. See States above. |
+| The small parts look generic (avatars, logos, inputs, empty states, numbers, icons, hover/focus states, favicon) | `palate details <route>`: each part with its crop and upgrade. Real people's photos or generated avatars only; official brand marks only. Run it again to confirm. |
+| The page feels static, or motion is off | `palate animate <route>`: frame strips and a brief for motion that explains something. Verify with `palate animate <route> --check` (no hidden content with motion, reduced motion or JavaScript off; no layout shift). |
+
+After a critique, `palate taste learn` also folds in the user's disagreements, so palate stops raising what they don't consider a problem.
+
+## Fix it in place
+
+When the user wants to point at things in their running app instead of describing them ("this card", "fix that header"), or asks for `palate point`:
+
+1. `palate point [route]` starts (or reuses) the dev server behind a small local proxy and opens the app with palate's overlay. Nothing in the project changes. Give the user the link. They press the palate button (or Alt+P), hover to see each element's box, name, margin and padding, use ↑ ↓ to pick the parent section instead of a leaf, click, type what should change or tap a chip (Fix spacing, Fix alignment, Type hierarchy, Make it premium, Add motion, Real content & avatars, Variants of this) and send with Cmd/Ctrl+Enter. They can queue several; each becomes a numbered pin. Something that needs a click first (an open modal, a dropdown, a tab, a hover menu, an expanded row): they open it with pointing off, press Alt+P and pin inside it. The overlay keeps the steps that opened it ("+2 steps to open") and palate replays them on a fresh load before every crop, at both widths.
+2. Keep listening without being asked: the user should never have to come back to the chat and say "I pinned things". Loop until they say they're done, and don't end your turn while point runs (if they write something else, answer it, then go back to listening). The overlay shows them "Agent listening", "Agent working · pin 3" or "No agent listening", from your calls.
+   - `palate point next` (or `palate_point_next`, up to 55 s a call) waits for the next request and marks it as being worked on. "Still listening" (MCP) means nothing came yet: call it again at once. It prints the user's words, the selector, DOM path, component and owner chain, key styles, trimmed HTML, a crop (`.palate/point/<id>/crop.png`; open it) and the likely source lines. It leads with where the problem appears: "Pinned at 1440×900 (desktop)", or the width the user's words name ("on mobile" → 390).
+   - A pin inside an opened state says so in the brief: "This element is inside a state opened by: click "Invite members" → the modal. palate reopens it for every check." When a check couldn't reopen it (a step's target is gone, say you renamed that button), crop says "couldn't reopen" with the step that failed and shows the page as it loads. That width isn't checked in the opened state; it never counts as broken and never blocks done. Check the change in the code and say so in the summary.
+   - Fix exactly that element or section in the source. Confirm the file by its text and classes. Change nothing around it, and keep the project's tokens and components.
+   - `palate point crop <id>` re-shoots it after the edit; compare it with the crop. Fix once more if it isn't better. Every pin is checked at two widths: the one the user pinned at and the other one (390 for a desktop pin, 1440 for a phone pin, or the width the request names: "on mobile", "at 768px"; judge a request about a width there). The before at the other width was shot when the user pinned. Crop returns before and now at both, and a verdict for the other width: **unchanged**; **changed** (moved, resized or looks different: often expected for shared CSS, look at it); or **broke** (the page now scrolls sideways, the element disappeared, or text in it is cut off). Fix a break too, then crop again.
+   - If the user asked you to remove the element, finish with `--removed` (MCP: `removed: true`): the pin then says "Removed" instead of cropping whatever sits there now.
+   - `palate point done <id> "<one line: what changed>"`. The user's pin turns done and shows before and after at both widths. It refuses while the other width is broken; `--override` (MCP: `override: true`) only when the user accepts it, and the pin keeps the warning. Then straight back to `next`.
+   - Stop when the user says they're done, or when `next` says they pressed **Done** in the overlay (it comes after the pins they already sent). `palate point stop` does the same from a terminal.
+3. "Variants of this" means don't edit in place: `palate vary <route> --section "<the request's selector>"`, build the briefs, `palate pick`, make the winner real, then mark the request done.
+
+With no agent listening, a pin still queues and the overlay tells the user how to start one (`/mcp__palate__point` in Claude Code, or `palate point --auto`); the next agent takes the queue in order.
+
+**Auto mode, no chat at all:** `palate point [route] --auto [--agent claude|codex]`. palate runs the agent's CLI headless on each pin, one at a time, in order (`claude -p` / `codex exec`, brief on stdin, the project as the working folder). Claude Code may only read and edit files and call palate's crop and done (no shell, no web); Codex runs in its workspace-write sandbox. A pin the agent leaves without `done` turns "Failed: retry" with its last lines. If the CLI isn't on PATH, palate says so and stays in manual mode. `--yolo` skips every permission check; only when the user asks for it, and palate warns. If you are the headless agent: do only that one request, verify with `palate point crop <id>` (fix the other width too if it broke; "couldn't reopen" for a pin inside a modal or menu isn't a break), finish with `palate point done <id> "<summary>"` (never `--override`: the user isn't there to accept it), and don't call `next`.
+
+Every request and its before/after go to the user's taste log; `palate taste learn` shows what they keep asking to fix.
+
+## Rules that always apply
+
+- The user's rules (`palate rule list`) hold wherever they apply; when they say something is bad, `palate fail` it, and once they keep the rule it proposes, it never comes back.
+- Every fact, record and number comes from the project. Never invent logos, testimonials, reviews or customer numbers; never copy another company's logo, wording or imagery.
+- Density of content is good; density of chrome is not. At most one crafted touch per screen, at the edge of the content.
+- No emoji or em dashes in UI copy, no gradient text, no `transition: all`; `tabular-nums` only on numbers; one solid primary button per view.
+- Everything visible without animation; respect `prefers-reduced-motion`.

package/src/auth-recheck.mjs

@@ -0,0 +1,4 @@
+// The background re-check, run detached by maybeRecheck() so a command never waits for the network.
+import { recheck } from "./auth.mjs";
+
+await recheck().catch(() => {});