ada-agent 0.2.0 → 0.3.1

package/docs/cloudflare.md

@@ -1,81 +1,81 @@
-# Using Cloudflare models with ada
-
-Cloudflare gives you two OpenAI-compatible endpoints, and ada speaks OpenAI — so both are just the
-`cloudflare` provider with the right env vars. Pick the one you have:
-
-- **Workers AI** — Cloudflare *hosts* the model (Llama, Qwen, Gemma, Kimi, …). Simplest.
-- **AI Gateway** — Cloudflare *proxies* other providers (OpenAI/Anthropic/Workers AI/…) through one
-  endpoint, with caching + analytics + optional unified billing.
-
-Browse what's available and its pricing any time, offline:
-
-```bash
-ada catalog cloudflare          # Workers AI + AI Gateway models, context + $/1M
-```
-
----
-
-## Workers AI (recommended start)
-
-1. **Cloudflare dashboard → AI → Workers AI → "Use REST API".** Copy your **Account ID** and
-   **create an API token** (Workers AI scope).
-2. Set the env vars for the backend:
-   ```bash
-   export CLOUDFLARE_ACCOUNT_ID=your-32-char-account-id
-   export CLOUDFLARE_API_TOKEN=your-workers-ai-token
-   ```
-3. Start the backend and run ada with a `@cf/…` model id:
-   ```bash
-   ada-server
-   ada --model "@cf/moonshotai/kimi-k2.7-code"     # or any id from `ada catalog cloudflare`
-   ```
-
-That's it. ada routes `@cf/*` to Cloudflare automatically, sends the full id through, and `/cost`
-already knows the price from the catalog.
-
-> The default endpoint ada builds is
-> `https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1` — Workers AI's
-> OpenAI-compatible base. No code change needed.
-
----
-
-## AI Gateway
-
-1. **Cloudflare dashboard → AI → AI Gateway → create a gateway.** Note your **Account ID** and
-   **Gateway ID**, and grab the gateway's **OpenAI-compatible endpoint URL** (the "compat" base).
-2. Point ada at that URL and supply the token it expects (your gateway token, or the upstream
-   provider's key, depending on how the gateway is configured):
-   ```bash
-   export CLOUDFLARE_BASE_URL="https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat"
-   export CLOUDFLARE_API_TOKEN=your-gateway-or-provider-key
-   ```
-   (`CLOUDFLARE_BASE_URL` overrides the Workers AI default, so `CLOUDFLARE_ACCOUNT_ID` isn't needed.)
-3. Use the model id format your gateway expects (often `provider/model`, e.g. `openai/gpt-4o`), and
-   route it explicitly to the `cloudflare` provider — easiest is the `--provider` field or an
-   `@cf/`-style id; otherwise send `provider: "cloudflare"` on the request.
-
-> Copy the exact base URL from your AI Gateway page — Cloudflare shows the OpenAI-compatible endpoint
-> there. ada just proxies to whatever you set.
-
----
-
-## How it works (why it's only ~2 lines in ada)
-
-ada keys providers by **wire format**, not by vendor. Cloudflare's Workers AI and AI Gateway both
-emit the OpenAI Chat Completions format, so they reuse the shared `openai-compat.ts` adapter — no
-Cloudflare-specific SDK or adapter. The whole integration is:
-
-- one `PROVIDERS` entry in [`src/server/config.ts`](../src/server/config.ts) (base URL + key env),
-- one router line in [`src/server/router.ts`](../src/server/router.ts) (`@cf/*` → cloudflare).
-
-(Contrast: opencode pulls in dedicated `workers-ai-provider` / `ai-gateway-provider` packages + a
-custom loader, because it's built on the Vercel AI SDK's per-provider abstraction. ada doesn't need
-that for an OpenAI-shaped endpoint.)
-
-## Troubleshooting
-
-- **401 / 403** — wrong token or scope. Workers AI needs a Workers-AI-scoped token; the Account ID
-  must match the token's account.
-- **404 on the model** — the `@cf/…` id isn't hosted; check `ada catalog cloudflare` or the Workers
-  AI catalog in the dashboard.
-- **`/cost` says "no price table"** — the model isn't in the baked catalog; run `npm run catalog:refresh`.
+# Using Cloudflare models with ada
+
+Cloudflare gives you two OpenAI-compatible endpoints, and ada speaks OpenAI — so both are just the
+`cloudflare` provider with the right env vars. Pick the one you have:
+
+- **Workers AI** — Cloudflare *hosts* the model (Llama, Qwen, Gemma, Kimi, …). Simplest.
+- **AI Gateway** — Cloudflare *proxies* other providers (OpenAI/Anthropic/Workers AI/…) through one
+  endpoint, with caching + analytics + optional unified billing.
+
+Browse what's available and its pricing any time, offline:
+
+```bash
+ada catalog cloudflare          # Workers AI + AI Gateway models, context + $/1M
+```
+
+---
+
+## Workers AI (recommended start)
+
+1. **Cloudflare dashboard → AI → Workers AI → "Use REST API".** Copy your **Account ID** and
+   **create an API token** (Workers AI scope).
+2. Set the env vars for the backend:
+   ```bash
+   export CLOUDFLARE_ACCOUNT_ID=your-32-char-account-id
+   export CLOUDFLARE_API_TOKEN=your-workers-ai-token
+   ```
+3. Start the backend and run ada with a `@cf/…` model id:
+   ```bash
+   ada-server
+   ada --model "@cf/moonshotai/kimi-k2.7-code"     # or any id from `ada catalog cloudflare`
+   ```
+
+That's it. ada routes `@cf/*` to Cloudflare automatically, sends the full id through, and `/cost`
+already knows the price from the catalog.
+
+> The default endpoint ada builds is
+> `https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1` — Workers AI's
+> OpenAI-compatible base. No code change needed.
+
+---
+
+## AI Gateway
+
+1. **Cloudflare dashboard → AI → AI Gateway → create a gateway.** Note your **Account ID** and
+   **Gateway ID**, and grab the gateway's **OpenAI-compatible endpoint URL** (the "compat" base).
+2. Point ada at that URL and supply the token it expects (your gateway token, or the upstream
+   provider's key, depending on how the gateway is configured):
+   ```bash
+   export CLOUDFLARE_BASE_URL="https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat"
+   export CLOUDFLARE_API_TOKEN=your-gateway-or-provider-key
+   ```
+   (`CLOUDFLARE_BASE_URL` overrides the Workers AI default, so `CLOUDFLARE_ACCOUNT_ID` isn't needed.)
+3. Use the model id format your gateway expects (often `provider/model`, e.g. `openai/gpt-4o`), and
+   route it explicitly to the `cloudflare` provider — easiest is the `--provider` field or an
+   `@cf/`-style id; otherwise send `provider: "cloudflare"` on the request.
+
+> Copy the exact base URL from your AI Gateway page — Cloudflare shows the OpenAI-compatible endpoint
+> there. ada just proxies to whatever you set.
+
+---
+
+## How it works (why it's only ~2 lines in ada)
+
+ada keys providers by **wire format**, not by vendor. Cloudflare's Workers AI and AI Gateway both
+emit the OpenAI Chat Completions format, so they reuse the shared `openai-compat.ts` adapter — no
+Cloudflare-specific SDK or adapter. The whole integration is:
+
+- one `PROVIDERS` entry in [`src/server/config.ts`](../src/server/config.ts) (base URL + key env),
+- one router line in [`src/server/router.ts`](../src/server/router.ts) (`@cf/*` → cloudflare).
+
+(Contrast: opencode pulls in dedicated `workers-ai-provider` / `ai-gateway-provider` packages + a
+custom loader, because it's built on the Vercel AI SDK's per-provider abstraction. ada doesn't need
+that for an OpenAI-shaped endpoint.)
+
+## Troubleshooting
+
+- **401 / 403** — wrong token or scope. Workers AI needs a Workers-AI-scoped token; the Account ID
+  must match the token's account.
+- **404 on the model** — the `@cf/…` id isn't hosted; check `ada catalog cloudflare` or the Workers
+  AI catalog in the dashboard.
+- **`/cost` says "no price table"** — the model isn't in the baked catalog; run `npm run catalog:refresh`.

package/docs/connectors.md

@@ -1,49 +1,49 @@
-# Connectors (MCP)
-
-ada connects to external tools and data through the **Model Context Protocol (MCP)**. Each connector
-is an MCP server; ada spawns or calls it, lists its tools, and registers them as ada tools named
-`<server>__<tool>` — approval-gated, and only loaded for **trusted projects**.
-
-## Quick start
-
-```bash
-ada mcp                       # list the connector catalog (● configured · ○ available)
-ada mcp add github            # write the github entry into .ada/mcp.json
-ada mcp remove github         # remove it
-```
-
-After `add`, set any env vars it prints (e.g. `GITHUB_PERSONAL_ACCESS_TOKEN`), then start `ada` in
-that project — the connector's tools appear automatically.
-
-## Catalog
-
-`filesystem` · `github` · `git` · `postgres` · `sqlite` · `fetch` · `brave-search` · `puppeteer` ·
-`slack` · `memory` · `sentry`. Run `ada mcp` for the live list and which env vars each needs.
-
-## Config: `.ada/mcp.json`
-
-`ada mcp add` edits this file, but you can also write entries by hand. Two transports:
-
-```jsonc
-{
-  "servers": {
-    // local stdio server (a subprocess)
-    "fs":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
-    // remote server over Streamable HTTP
-    "remote": { "url": "https://mcp.example.com/v1", "headers": { "Authorization": "Bearer <token>" } }
-  }
-}
-```
-
-- **stdio** — `{ command, args, env }`: ada launches the process and speaks JSON-RPC over stdin/stdout.
-- **http** — `{ url, headers }`: ada POSTs JSON-RPC and reads a JSON or SSE response (Streamable HTTP).
-
-## Notes
-
-- MCP servers run code / reach the network, so they load **only in trusted projects** (the same trust
-  gate as `.ada` prompts and settings). Untrusted projects skip them.
-- Every MCP tool is **approval-gated** — ada prompts before each call (in `ask` mode).
-- A server's **resources** are reachable through a generated `<server>__read_resource` tool.
-- Secrets come from **env vars** (referenced in the server's `env`), never committed to `.ada/mcp.json`.
-- See the `connectors` skill category (`list_skills {category: "connectors"}`) for per-connector setup
-  walk-throughs, and the `mcp-server` skill to build your own.
+# Connectors (MCP)
+
+ada connects to external tools and data through the **Model Context Protocol (MCP)**. Each connector
+is an MCP server; ada spawns or calls it, lists its tools, and registers them as ada tools named
+`<server>__<tool>` — approval-gated, and only loaded for **trusted projects**.
+
+## Quick start
+
+```bash
+ada mcp                       # list the connector catalog (● configured · ○ available)
+ada mcp add github            # write the github entry into .ada/mcp.json
+ada mcp remove github         # remove it
+```
+
+After `add`, set any env vars it prints (e.g. `GITHUB_PERSONAL_ACCESS_TOKEN`), then start `ada` in
+that project — the connector's tools appear automatically.
+
+## Catalog
+
+`filesystem` · `github` · `git` · `postgres` · `sqlite` · `fetch` · `brave-search` · `puppeteer` ·
+`slack` · `memory` · `sentry`. Run `ada mcp` for the live list and which env vars each needs.
+
+## Config: `.ada/mcp.json`
+
+`ada mcp add` edits this file, but you can also write entries by hand. Two transports:
+
+```jsonc
+{
+  "servers": {
+    // local stdio server (a subprocess)
+    "fs":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
+    // remote server over Streamable HTTP
+    "remote": { "url": "https://mcp.example.com/v1", "headers": { "Authorization": "Bearer <token>" } }
+  }
+}
+```
+
+- **stdio** — `{ command, args, env }`: ada launches the process and speaks JSON-RPC over stdin/stdout.
+- **http** — `{ url, headers }`: ada POSTs JSON-RPC and reads a JSON or SSE response (Streamable HTTP).
+
+## Notes
+
+- MCP servers run code / reach the network, so they load **only in trusted projects** (the same trust
+  gate as `.ada` prompts and settings). Untrusted projects skip them.
+- Every MCP tool is **approval-gated** — ada prompts before each call (in `ask` mode).
+- A server's **resources** are reachable through a generated `<server>__read_resource` tool.
+- Secrets come from **env vars** (referenced in the server's `env`), never committed to `.ada/mcp.json`.
+- See the `connectors` skill category (`list_skills {category: "connectors"}`) for per-connector setup
+  walk-throughs, and the `mcp-server` skill to build your own.

package/docs/integrations.md

@@ -1,62 +1,62 @@
-# Integrating with ada
-
-ada exposes a few programmatic surfaces so other tools can drive it. The buildable foundations are
-shipped; the product surfaces that need *external* infrastructure (a Slack app, hosting, an Electron
-build, an IdP) are described with what they'd take — they can't be "live" without your accounts.
-
-## HTTP API — `ada serve`
-
-```bash
-ada serve            # → http://localhost:8788  (ADA_HTTP_PORT to change)
-```
-- `GET /health` → `{ ok, model }`
-- `POST /v1/prompt` `{ "text": "...", "model"?: "..." }` → `{ text, usage }` (runs a fresh agent turn)
-
-## Typed SDK — `src/sdk`
-
-```ts
-import { createClient } from "ada-agent/sdk"; // in-repo: "./src/sdk/index.ts"
-const ada = createClient("http://localhost:8788");
-console.log(await ada.health());
-const { text } = await ada.prompt("list the files in this project");
-```
-
-It's a ~30-line `fetch` wrapper over the HTTP API above — if you'd rather not pull in the source,
-just POST to `/v1/prompt` directly.
-
-## ACP bridge — `ada acp`
-
-A minimal Agent Client Protocol bridge over stdio (JSON-RPC 2.0, newline-delimited): handles
-`initialize` and `session/prompt`, so an ACP-aware editor can drive ada. It's a **scaffold** — method
-names and framing may need adjusting to your client's ACP version.
-
-## Session share — `ada share`
-
-```bash
-ada share              # serve the latest session as a read-only web page (localhost)
-ada share <name|file>  # a specific session
-```
-Local and read-only. A *public* share link would need a hosted backend to receive and serve the
-transcript (see below).
-
----
-
-## Needs your infrastructure (foundations are here; the rest is your accounts/hosting)
-
-These are all buildable **on top of the HTTP API / SDK above** — what's missing is the external
-service, which only you can provision.
-
-- **Slack bot** — a [Slack Bolt](https://slack.dev/bolt-js) app that, per thread, calls
-  `createClient().prompt(message)` and posts the reply. Needs a **Slack app + bot token** (`SLACK_BOT_TOKEN`)
-  and a running process. ~30 lines on top of the SDK.
-- **Web console** — a single page that POSTs to `/v1/prompt` and renders the reply (the `ada share`
-  server is a minimal read-only version). Needs **hosting** + CORS if cross-origin.
-- **Desktop app** — an Electron shell that spawns `ada serve` and points a webview at it. Needs the
-  **Electron build/packaging** pipeline (you already have the separate `ada-ide` VS Code fork).
-- **Public session sharing** — `ada share` is local; a public link needs a **hosted endpoint** to
-  receive the transcript and a viewer (like opencode's `console.opncd.ai`).
-- **Enterprise / identity / teams** — multi-tenant accounts + SSO need an **IdP and a control plane**;
-  out of scope for a single-binary CLI.
-- **SQLite session store** — ada uses append-only JSONL (`.ada/sessions/*.jsonl`) by design (no native
-  dep, greppable, trivially portable). Node 24 ships an experimental `node:sqlite`; a SQLite backend is
-  a drop-in for `session.ts` if you want indexed queries — say the word and it's a small module.
+# Integrating with ada
+
+ada exposes a few programmatic surfaces so other tools can drive it. The buildable foundations are
+shipped; the product surfaces that need *external* infrastructure (a Slack app, hosting, an Electron
+build, an IdP) are described with what they'd take — they can't be "live" without your accounts.
+
+## HTTP API — `ada serve`
+
+```bash
+ada serve            # → http://localhost:8788  (ADA_HTTP_PORT to change)
+```
+- `GET /health` → `{ ok, model }`
+- `POST /v1/prompt` `{ "text": "...", "model"?: "..." }` → `{ text, usage }` (runs a fresh agent turn)
+
+## Typed SDK — `src/sdk`
+
+```ts
+import { createClient } from "ada-agent/sdk"; // in-repo: "./src/sdk/index.ts"
+const ada = createClient("http://localhost:8788");
+console.log(await ada.health());
+const { text } = await ada.prompt("list the files in this project");
+```
+
+It's a ~30-line `fetch` wrapper over the HTTP API above — if you'd rather not pull in the source,
+just POST to `/v1/prompt` directly.
+
+## ACP bridge — `ada acp`
+
+A minimal Agent Client Protocol bridge over stdio (JSON-RPC 2.0, newline-delimited): handles
+`initialize` and `session/prompt`, so an ACP-aware editor can drive ada. It's a **scaffold** — method
+names and framing may need adjusting to your client's ACP version.
+
+## Session share — `ada share`
+
+```bash
+ada share              # serve the latest session as a read-only web page (localhost)
+ada share <name|file>  # a specific session
+```
+Local and read-only. A *public* share link would need a hosted backend to receive and serve the
+transcript (see below).
+
+---
+
+## Needs your infrastructure (foundations are here; the rest is your accounts/hosting)
+
+These are all buildable **on top of the HTTP API / SDK above** — what's missing is the external
+service, which only you can provision.
+
+- **Slack bot** — a [Slack Bolt](https://slack.dev/bolt-js) app that, per thread, calls
+  `createClient().prompt(message)` and posts the reply. Needs a **Slack app + bot token** (`SLACK_BOT_TOKEN`)
+  and a running process. ~30 lines on top of the SDK.
+- **Web console** — a single page that POSTs to `/v1/prompt` and renders the reply (the `ada share`
+  server is a minimal read-only version). Needs **hosting** + CORS if cross-origin.
+- **Desktop app** — an Electron shell that spawns `ada serve` and points a webview at it. Needs the
+  **Electron build/packaging** pipeline (you already have the separate `ada-ide` VS Code fork).
+- **Public session sharing** — `ada share` is local; a public link needs a **hosted endpoint** to
+  receive the transcript and a viewer (like opencode's `console.opncd.ai`).
+- **Enterprise / identity / teams** — multi-tenant accounts + SSO need an **IdP and a control plane**;
+  out of scope for a single-binary CLI.
+- **SQLite session store** — ada uses append-only JSONL (`.ada/sessions/*.jsonl`) by design (no native
+  dep, greppable, trivially portable). Node 24 ships an experimental `node:sqlite`; a SQLite backend is
+  a drop-in for `session.ts` if you want indexed queries — say the word and it's a small module.

package/package.json

@@ -1,65 +1,67 @@
-{
-  "name": "ada-agent",
-  "version": "0.2.0",
-  "description": "A from-zero terminal coding agent with a Cursor-style routing backend, ~285 skills, MCP connectors, and ask/plan/auto modes",
-  "type": "module",
-  "license": "MIT",
-  "author": "Aditya",
-  "homepage": "https://github.com/black141312/ada#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/black141312/ada.git"
-  },
-  "bugs": {
-    "url": "https://github.com/black141312/ada/issues"
-  },
-  "keywords": [
-    "coding-agent",
-    "ai-agent",
-    "llm",
-    "cli",
-    "terminal",
-    "tui",
-    "mcp",
-    "openai",
-    "anthropic",
-    "ollama",
-    "agentic",
-    "developer-tools"
-  ],
-  "bin": {
-    "ada": "bin/ada.mjs",
-    "ada-server": "bin/ada-server.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "skills/",
-    "docs/",
-    "bench/",
-    "tsconfig.json",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "start": "tsx src/client/cli.ts",
-    "server": "tsx src/server/index.ts",
-    "typecheck": "tsc --noEmit",
-    "selfcheck": "tsx src/selfcheck.ts",
-    "bench:swebench": "node bench/swebench.mjs",
-    "catalog:refresh": "node scripts/refresh-catalog.mjs"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.106.0",
-    "node-pty": "^1.1.0",
-    "openai": "^6.45.0",
-    "tsx": "^4.22.4"
-  },
-  "devDependencies": {
-    "@types/node": "^26.0.1",
-    "typescript": "^6.0.3"
-  }
-}
+{
+  "name": "ada-agent",
+  "version": "0.3.1",
+  "description": "A from-zero terminal coding agent with a Cursor-style routing backend, ~285 skills, MCP connectors, and ask/plan/auto modes",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aditya",
+  "homepage": "https://github.com/black141312/ada#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/black141312/ada.git"
+  },
+  "bugs": {
+    "url": "https://github.com/black141312/ada/issues"
+  },
+  "keywords": [
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "cli",
+    "terminal",
+    "tui",
+    "mcp",
+    "openai",
+    "anthropic",
+    "ollama",
+    "agentic",
+    "developer-tools"
+  ],
+  "bin": {
+    "ada": "bin/ada.mjs",
+    "ada-agent": "bin/ada.mjs",
+    "ada-server": "bin/ada-server.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "docs/",
+    "bench/",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "tsx src/client/cli.ts",
+    "server": "tsx src/server/index.ts",
+    "typecheck": "tsc --noEmit",
+    "selfcheck": "tsx src/selfcheck.ts",
+    "bench:swebench": "node bench/swebench.mjs",
+    "catalog:refresh": "node scripts/refresh-catalog.mjs",
+    "release": "node scripts/release.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.106.0",
+    "node-pty": "^1.1.0",
+    "openai": "^6.45.0",
+    "tsx": "^4.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3"
+  }
+}

package/skills/aesthetic-direction/SKILL.md

@@ -1,24 +1,24 @@
----
-name: aesthetic-direction
-description: Choose an intentional, non-templated visual direction and reference before building any UI
-category: ui-design
----
-
-# Aesthetic Direction
-
-Do this before writing component code. The difference between a forgettable, templated UI and a memorable one is a deliberate point of view chosen up front — not defaults stacked by accident.
-
-1. Name the feeling in 2–3 adjectives and a reference: "editorial and confident, like Linear meets a print magazine" or "warm utilitarian, like a well-made tool." Vague intent yields vague output.
-2. Pick a stance on each axis deliberately: density (airy vs. compact), shape language (sharp vs. rounded), contrast (muted vs. punchy), and ornament (flat vs. layered/textured). Write the choices down.
-3. Choose ONE signature move the design hangs on — a distinctive typeface, a bold accent, a grain/noise texture, an unusual grid, a motion personality. Without a signature, it reads generic.
-4. Anchor with real references: pull 3–5 screenshots you admire and articulate *what specifically* works (the oversized headers, the restrained palette, the tight grid) — then translate, don't copy.
-5. Pressure-test against templates: if it could be any Bootstrap/default-shadcn site, push harder — change the type, break the symmetry, commit to one strong color, vary the rhythm.
-6. Encode the direction into tokens immediately so the rest of the build inherits the decision instead of re-litigating it per component.
-7. Sanity-check feasibility and accessibility — a daring direction still has to pass contrast and perform.
-
-## Rules
-- Decide the direction before components; retrofitting taste onto built UI rarely works.
-- Commit to one signature element rather than three half-measures.
-- "Modern/clean/minimal" is not a direction — name a feeling, a reference, and a specific move.
-- Default shadcn/Bootstrap/Tailwind-gray is a starting point to subvert, not a destination.
-- Distinctive still means accessible and fast — daring is not an excuse for 2:1 contrast.
+---
+name: aesthetic-direction
+description: Choose an intentional, non-templated visual direction and reference before building any UI
+category: ui-design
+---
+
+# Aesthetic Direction
+
+Do this before writing component code. The difference between a forgettable, templated UI and a memorable one is a deliberate point of view chosen up front — not defaults stacked by accident.
+
+1. Name the feeling in 2–3 adjectives and a reference: "editorial and confident, like Linear meets a print magazine" or "warm utilitarian, like a well-made tool." Vague intent yields vague output.
+2. Pick a stance on each axis deliberately: density (airy vs. compact), shape language (sharp vs. rounded), contrast (muted vs. punchy), and ornament (flat vs. layered/textured). Write the choices down.
+3. Choose ONE signature move the design hangs on — a distinctive typeface, a bold accent, a grain/noise texture, an unusual grid, a motion personality. Without a signature, it reads generic.
+4. Anchor with real references: pull 3–5 screenshots you admire and articulate *what specifically* works (the oversized headers, the restrained palette, the tight grid) — then translate, don't copy.
+5. Pressure-test against templates: if it could be any Bootstrap/default-shadcn site, push harder — change the type, break the symmetry, commit to one strong color, vary the rhythm.
+6. Encode the direction into tokens immediately so the rest of the build inherits the decision instead of re-litigating it per component.
+7. Sanity-check feasibility and accessibility — a daring direction still has to pass contrast and perform.
+
+## Rules
+- Decide the direction before components; retrofitting taste onto built UI rarely works.
+- Commit to one signature element rather than three half-measures.
+- "Modern/clean/minimal" is not a direction — name a feeling, a reference, and a specific move.
+- Default shadcn/Bootstrap/Tailwind-gray is a starting point to subvert, not a destination.
+- Distinctive still means accessible and fast — daring is not an excuse for 2:1 contrast.

package/skills/color-palette/SKILL.md

@@ -1,24 +1,24 @@
----
-name: color-palette
-description: Craft an accessible on-brand palette with checked contrast, perceptual ramps, and semantic color roles
-category: ui-design
----
-
-# Color Palette
-
-Use this when choosing or fixing a product's colors — to get past "pick a brand hue and tint it" into a palette that's coherent, accessible, and works in both light and dark.
-
-1. Start from one or two brand hues and build perceptually even ramps in `oklch()` (11 steps, 50–950). Even lightness steps mean predictable contrast — RGB tinting gives muddy, uneven ramps.
-2. Reserve saturation for intent: keep most surfaces near-neutral (low-chroma grays carrying a hint of the brand hue) and spend vivid color only on the accent and on calls to action.
-3. Define semantic roles, not raw swatches: `--bg`, `--surface`, `--surface-raised`, `--text`, `--text-muted`, `--border`, `--accent`, `--accent-fg`, plus state colors success/warning/danger/info.
-4. Check contrast for real: body text ≥ 4.5:1, large text and UI components ≥ 3:1 (WCAG AA). Pair every background token with a foreground that passes against it.
-5. Design the dark variant as a sibling, not an inversion — raise surface lightness for elevation instead of adding shadows, and slightly lower accent chroma so it doesn't vibrate on dark.
-6. Don't rely on hue alone to convey meaning; back status colors with an icon or label for color-blind users, and test with a deuteranopia simulation.
-7. Constrain the whole palette: ~2 brand hues + neutrals + 4 state colors. A palette with 9 unrelated hues never feels designed.
-
-## Rules
-- Every text/background pairing passes WCAG AA (4.5:1 body, 3:1 large/UI) — verify, don't eyeball.
-- Build ramps in oklch/HSL for even steps; avoid hand-picked hex stops.
-- Most of the screen is neutral; saturated color is an accent, not a background.
-- Name by role (`--accent`, `--danger`) so themes remap meaning, not pixels.
-- Never encode state in color alone — add an icon, label, or shape.
+---
+name: color-palette
+description: Craft an accessible on-brand palette with checked contrast, perceptual ramps, and semantic color roles
+category: ui-design
+---
+
+# Color Palette
+
+Use this when choosing or fixing a product's colors — to get past "pick a brand hue and tint it" into a palette that's coherent, accessible, and works in both light and dark.
+
+1. Start from one or two brand hues and build perceptually even ramps in `oklch()` (11 steps, 50–950). Even lightness steps mean predictable contrast — RGB tinting gives muddy, uneven ramps.
+2. Reserve saturation for intent: keep most surfaces near-neutral (low-chroma grays carrying a hint of the brand hue) and spend vivid color only on the accent and on calls to action.
+3. Define semantic roles, not raw swatches: `--bg`, `--surface`, `--surface-raised`, `--text`, `--text-muted`, `--border`, `--accent`, `--accent-fg`, plus state colors success/warning/danger/info.
+4. Check contrast for real: body text ≥ 4.5:1, large text and UI components ≥ 3:1 (WCAG AA). Pair every background token with a foreground that passes against it.
+5. Design the dark variant as a sibling, not an inversion — raise surface lightness for elevation instead of adding shadows, and slightly lower accent chroma so it doesn't vibrate on dark.
+6. Don't rely on hue alone to convey meaning; back status colors with an icon or label for color-blind users, and test with a deuteranopia simulation.
+7. Constrain the whole palette: ~2 brand hues + neutrals + 4 state colors. A palette with 9 unrelated hues never feels designed.
+
+## Rules
+- Every text/background pairing passes WCAG AA (4.5:1 body, 3:1 large/UI) — verify, don't eyeball.
+- Build ramps in oklch/HSL for even steps; avoid hand-picked hex stops.
+- Most of the screen is neutral; saturated color is an accent, not a background.
+- Name by role (`--accent`, `--danger`) so themes remap meaning, not pixels.
+- Never encode state in color alone — add an icon, label, or shape.