@palate/cli 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+palate
+Copyright (c) 2026 Garvit Joshi. All rights reserved.
+
+palate is proprietary software. It is published to the npm registry so that people with an invite can install it;
+being able to download it does not grant any rights to use it.
+
+You may install and run palate's free commands without an activation code: the ones it runs without asking for one
+(the guard, copy, check, shoot, finish, states, details, animate, gate, imagery, texture, icons and the commands that
+report on them). Everything else in palate you may run only with a valid activation code issued to you by its author,
+for as long as that code is active. You may not copy, modify, redistribute, sublicense or sell palate or any part of it (including its
+knowledge base in kb/), remove or work around its activation check, or use it to build a competing product, except
+where the law allows it regardless of this notice.
+
+Third-party material inside palate (reference screenshots, design-system notes, fonts named in its knowledge base)
+keeps its own licence, recorded next to it (for example kb/references/index.json and kb/systems/LICENSE-*).
+
+palate is provided "as is", without warranty of any kind. To the extent the law allows, its author is not liable for
+any damages arising from its use.
+
+Questions or a licence for other use: write to the author through palate's site.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# palate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Design intelligence for coding agents, and it grows with you.**
+
+AI gets a screen most of the way. palate does the last 20%: the research, the plan, the craft in every section, the states nobody remembers, and an honest check by judges who didn't build it. It works inside the agent you already use (Claude Code, Codex, Cursor) as an MCP server, in your own codebase, with your own components and data. And it learns your taste as you go, so your product starts looking like yours, not like everyone else's AI UI.
+
+> **Status:** private preview, invite-only.
+
+## Five products, five looks
+
+AI-built pages look alike because every model falls back on the same defaults. These are five fictional briefs from palate's benchmark, each built from scratch by an agent using palate, with no human edits. palate researched each category, planned a look of its own, and refused plans that repeated its recent pages.
+
+![Tracewell, request tracing for small engineering teams](media/palate/tracewell.jpg)
+<sub>**Tracewell**, request tracing for small teams. The slow request is drawn as an engineering drawing on drafting film, with a parts list of every span.</sub>
+
+![Mabel's Bakehouse, a neighbourhood bakery](media/palate/mabels-bakehouse.jpg)
+<sub>**Mabel's Bakehouse**, a bakery in Leith. A paper-bag white page printed in two riso inks; the picture is a public-domain engraving reprinted in the bakery's colours.</sub>
+
+![Open Shelf, a nonprofit tool library](media/palate/open-shelf.jpg)
+<sub>**Open Shelf**, a nonprofit tool library. The most borrowed tools hang on a rail, each with its shelf tag: "on the shelf" or "out, back Fri".</sub>
+
+![Kiln, a membership and firing-schedule app for pottery studios](media/palate/kiln.jpg)
+<sub>**Kiln**, software for pottery studios. Type a piece's tag and its journey through the kilns lights up, then the member gets the "it's ready" text.</sub>
+
+![Mira Okafor, a documentary wedding photographer](media/palate/mira-okafor.jpg)
+<sub>**Mira Okafor**, a documentary wedding photographer. Full-bleed black and white with the headline over the picture; public-domain prints stand in for her work and are credited as stand-ins.</sub>
+
+---
+
+## How it works
+
+You ask in your own words. palate first sizes the work to the request (`palate plan`), then guides your agent through it.
+
+- **A fix or a tweak** ("the headings are three different sizes") is changed in place and checked once. No loop.
+- **A page** gets the full treatment:
+  1. **Research.** Competitors and well-crafted pages in the category, looked at live: what the category always gets right, and its clichés.
+  2. **Direction.** Three art directions in different visual worlds; palate picks from your taste, or you do.
+  3. **Blueprint.** Before any code: the system, a look of its own (checked against palate's recent pages so it doesn't repeat itself), imagery, and one archetype per section from a library of 70.
+  4. **Build.** The hero and every other section in parallel, each section checking itself.
+  5. **Finish.** Screenshots at four widths, every state (empty, loading, error, long text, offline, keyboard), small details and motion.
+  6. **The quality gate.** Measured checks, then fresh judges who didn't build the page answer a checklist per section and compare it with strong real sites in both orders. Below the bar, palate repairs the weakest sections and checks again.
+  7. **You point.** Click anything in your running app and say what's wrong; the agent fixes it while you keep going.
+- **Your own design** ("build this from my screenshot", a URL or a Figma frame) is built to match, not reinterpreted. palate tags every value as measured, guessed or swapped, then checks your design against the build side by side.
+- **Options** only when you ask: several directions built as sketches, picked side by side in your browser.
+
+Every pick, every pin and every correction teaches palate your taste, by type of screen.
+
+## Why it's different
+
+| Typical AI UI | palate |
+|---|---|
+| The same defaults on every page | A look of its own per product, checked against what it made recently |
+| The model's taste | **Your** taste: learned from your picks and corrections, by type of screen |
+| Grades its own work | Judged by fresh agents that didn't build it, against strong real sites |
+| Instructions and rules | Rendered screenshots at four widths and measured checks |
+| The happy path only | Every state: empty, loading, error, long text, offline, keyboard |
+| A design-system "skin" | Your codebase, your components, your data |
+
+What we learned building it: taste is stable but depends on the job. The founder repeated 94% of his own blind picks, yet preferred dense layouts for a features section and calm ones for pricing. That's why palate learns per type of screen and keeps you in the loop. Generic AI judges agreed with him only 40% of the time.
+
+## Getting started
+
+palate runs locally: Node 22+, and Chrome or Edge for screenshots.
+
+**Free, no code needed:** the checks and the finishing pass on screens you already have. The guard, copy check, `palate check`, shoot, finish (states, details, motion), the quality gate, open-licence imagery and brand icons. **Invite-only:** building from your taste (build briefs, blueprints, research, directions, variants), pointing at what's wrong in your running app, critique and fixes, and the rules palate learns. What the free commands record stays in `~/.palate` and is there when you activate. Activate once per machine with the code from your invite (`npx @palate/cli activate palate-XXXX-XXXX-XXXX`). Until palate is on npm, replace `npx @palate/cli` with the local path shown in [docs/INSTALL.md](docs/INSTALL.md).
+
+**Claude Code**
+
+```bash
+claude mcp add palate -- npx @palate/cli mcp
+```
+
+To have your agent check its UI work before calling it done, add the guard (a stop hook for Claude Code, Codex, Cursor, Gemini CLI and Copilot, or a git pre-commit check for any agent; see [docs/INSTALL.md](docs/INSTALL.md#the-guard)):
+
+```bash
+npx @palate/cli guard --install
+```
+
+Then just ask ("make the pricing section", "build this from my screenshot"), or use `/mcp__palate__design`, `/mcp__palate__direction`, `/mcp__palate__point` and `/mcp__palate__explore`.
+
+**Codex**, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.palate]
+command = "npx"
+args = ["@palate/cli", "mcp"]
+```
+
+**Cursor**, in `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "palate": { "command": "npx", "args": ["@palate/cli", "mcp"] } } }
+```
+
+**Recommended polish skills:**
+
+```bash
+npx skills add jakubkrehel/skills
+```
+
+Full setup, including running from source, is in [docs/INSTALL.md](docs/INSTALL.md).
+
+## Your references and your taste
+
+- **References:** give palate screenshots, images or URLs ("like this"). They come first in every brief; URLs are captured and measured (fonts, type scale, radii). Save them for later with `palate refs add <file or url> --note "what I like"`.
+- **Taste profile:** a short, plain-language profile by type of screen, learned from your picks. Read it any time with `palate taste`.
+- **Privacy:** your references, picks and profile stay on your machine, in `~/.palate`. Screenshots are taken locally; the picker runs on `localhost`.
+
+## The CLI
+
+Everything the MCP server does is also a command:
+
+```
+palate plan "<request>"                how much work the request deserves, and why
+palate research "<job>" --route /x     competitors and well-crafted pages, looked at live
+palate direction "<job>"               three art directions
+palate build "<job>" --route /x        the blueprint, then one brief per section
+palate blueprint --file <plan.json>    check a page's plan before code
+palate finish <route>                  screenshots, states, details and motion in one pass
+palate gate <route>                    the quality gate, judged independently
+palate match <image|url|figma link>    build your own design faithfully, then check it
+palate point <route>                   point at what's wrong in your running app
+palate shoot <route>                   screenshots and measured problems
+palate check                           generated-UI tells and token drift in changed code
+palate variants "<job>" --name <n>     options, when you ask for them
+palate taste [learn]                   your taste profile
+palate refs add <file|url> [--note ...] save your references
+palate stats                           time and tokens, by mode
+palate mcp                             run as an MCP server
+```
+
+## How it's built
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): the pieces, the full flow, what runs where, and how palate grows with each user.
+- [docs/INSPIRATION.md](docs/INSPIRATION.md): the research behind designing from references.
+- [PLAN.md](PLAN.md): the roadmap and the evidence so far.
+
+```
+packages/palate   the CLI and MCP server (triage, research, blueprint, build, finish, gate, match, point)
+packages/eye      research: the reference library and the taste-model experiments
+skill/palate      the same loop as an agent skill
+kb/               section archetypes, the finish standard, moves, references, design systems
+```
+
+## Credits
+
+- Design-system data adapted from [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) (MIT).
+- Polish steps use [Jakub Krehel's interface skills](https://github.com/jakubkrehel/skills) (MIT) and Emil Kowalski's design-engineering skill ([animations.dev](https://animations.dev/)).
+- Reference library research draws on open-source UI libraries including shadcn/ui, Origin UI, Magic UI and HyperUI (all MIT).
+- Ideas, written in our own words and code: match mode's fidelity contract and verdicts from [Atharvsinh-codez/skills](https://github.com/Atharvsinh-codez/skills) (design-to-code, MIT); the bento and product-frame rules from [benjitaylor/skills](https://github.com/benjitaylor/skills) (stageshow).
+
+Built by [Garvit Joshi](https://www.garvit.me/).