glyph-ai 0.4.1 → 0.5.0

package/README.md

@@ -1,34 +1,54 @@
 # glyph-ai
 
-design intelligence for Claude Code/Cursor
+Design intelligence for Claude Code and Cursor.
 
-**Vibe coding is design blind.** You can ship a working app in an afternoon. But Claude Code can't tell why purple looks cheap, or why your app looks like Duolingo from Wish. And if you aren't a designer, it can be a frustrating and time-consuming part of shipping products people love.
+```bash
+npx glyph-ai init
+```
 
-Beautiful UI should be a native output of vibe coding. Glyph gives Claude Code and Cursor a sense of design so that this is possible.
+That's it. Start your dev server, open your app, and ask your AI agent:
 
-## What it does
+> "Create a design direction for this project"
 
-Glyph injects a design layer into your existing Claude Code or Cursor workflow. Tell it what you're building, and it pulls from the best references in the industry to establish a visual direction that fits your app. If you have an existing product, ask your coding agent to redesign any part of the app and watch Glyph work.
+Glyph scans your codebase, picks from the best references in the industry, and generates a visual direction tailored to what you're building. Every page, feature, and component you build after that follows it.
 
-## Install
+## Why
 
-```bash
-npx glyph-ai init
-```
+Vibe coding is design blind. You can ship a working app in an afternoon, but your AI agent can't tell why something looks off — why the spacing feels wrong, why the colors clash, why it looks like every other AI-generated UI.
 
-That's it. Glyph writes `.mcp.json` and `.cursor/mcp.json` automatically so Claude Code and Cursor pick up the MCP server without any manual config.
+Glyph gives your agent a sense of design. Not templates. Not themes. An opinionated visual direction built from real design systems (Linear, Stripe, Vercel, Apple, and more) that fits your specific app.
 
 ## How it works
 
+1. **`npx glyph-ai init`** — Glyph detects your framework, scans your project, and sets up the MCP server
+2. **"Create a design direction"** — Glyph generates `design.md` (new projects) or `redesign.md` (existing projects) with a complete visual system: colors, typography, spacing, components, motion
+3. **"Give me 3 variations of this page"** — Your agent generates variations that follow the direction. They appear in a browser overlay. Click to preview, click to implement.
+
+The direction is the source of truth. Once it exists, every design task follows it. Your agent never freelances — it executes within the constraints Glyph established.
+
+## What you get
+
+- **A visual direction** — not a generic theme, but a design system informed by the best products in your category
+- **Live preview overlay** — variations render in your browser, side by side, with one-click apply
+- **Automatic project detection** — Glyph infers what you're building (dashboard, SaaS, e-commerce, marketing site) and picks references accordingly
+- **Works with your stack** — Next.js, Vite, Create React App. Tailwind or CSS. Your existing tokens are respected.
+
+## Under the hood
+
+Everything runs locally. No API keys, no external services, no data leaving your machine.
+
 ```
 Your app (Next.js / Vite / CRA)
-  └── Glyph overlay (browser)
-        └── Glyph server (local, port 3013)
-              └── MCP → Claude Code / Cursor
-                    └── parallel variation runs
+  └── Glyph overlay (browser, dev only)
+        └── Glyph server (localhost:3013)
+              └── MCP tools → Claude Code / Cursor
 ```
 
-When you ask Claude Code to improve a component, Glyph returns a design brief with an opinionated taste layer, two-pass generation instructions, and a self-evaluation gate. Claude generates variations in parallel -- each with a distinct aesthetic personality -- previews them via screenshot, scores them against a rubric, and iterates before delivering. Results stream into the overlay one by one as they complete. Pick your favorite and click implement.
+- **`glyph init`** writes `.mcp.json` (Claude Code) and `.cursor/mcp.json` (Cursor) so your agent picks up Glyph's tools automatically
+- **The MCP server** runs locally and gives your agent six tools: `generate_design_system`, `generate_variations`, `submit_variations`, `apply_variation`, `preview_draft`, and `scan_design_system`
+- **The browser overlay** injects a dev-only script into your app that connects to the local server via WebSocket — shows variation previews, lets you click to apply
+- **No LLM calls from Glyph** — your agent does the generation using your existing Claude/Cursor subscription. Glyph just provides the design intelligence (briefs, constraints, scoring rubrics)
+- **Backups** are created automatically before any file is written. Click discard to restore.
 
 ## Commands
 
@@ -41,35 +61,3 @@ npx glyph-ai stop   # Stop the server
 
 - Node 18+
 - Claude Code or Cursor
-
-## Development
-
-```bash
-cd glyph
-pnpm install
-pnpm run dev:e2e
-```
-
-Starts three processes concurrently:
-
-| Process  | Location          | Description                                         |
-| -------- | ----------------- | --------------------------------------------------- |
-| Overlay  | packages/overlay/ | React + Tailwind browser overlay (Vite watch build) |
-| Server   | packages/server/  | Express + WebSocket + MCP on :3013                  |
-| Demo app | product/          | Next.js test app on :3000                           |
-
-Open http://localhost:3000 -- the overlay loads at the bottom of the page.
-
-**Build:**
-
-```bash
-pnpm run build         # overlay → server → cli
-pnpm run build:dist    # builds + bundles into packages/cli/bundled/
-```
-
-**Environment variables:**
-
-| Variable             | Default         | Description              |
-| -------------------- | --------------- | ------------------------ |
-| `GLYPH_PORT`         | `3013`          | Server port              |
-| `GLYPH_PROJECT_ROOT` | `process.cwd()` | Root of the user's project |