ada-agent 0.1.0 → 0.3.0

package/docs/cloudflare.md

@@ -0,0 +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`.

package/docs/connectors.md

@@ -42,7 +42,8 @@ that project — the connector's tools appear automatically.
 
 - 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.
+- 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

@@ -15,12 +15,15 @@ ada serve            # → http://localhost:8788  (ADA_HTTP_PORT to change)
 ## Typed SDK — `src/sdk`
 
 ```ts
-import { createClient } from "ada/sdk"; // or "./src/sdk/index.ts" in-repo
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ada-agent",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -49,7 +49,9 @@
     "server": "tsx src/server/index.ts",
     "typecheck": "tsc --noEmit",
     "selfcheck": "tsx src/selfcheck.ts",
-    "bench:swebench": "node bench/swebench.mjs"
+    "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",

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.

package/skills/component-library/SKILL.md

@@ -1,23 +1,23 @@
----
-name: component-library
-description: Build a reusable, composable, accessible component library in the shadcn/ui style with design tokens.
-category: ui-design
----
-
-# Component Library
-
-Reach for this when an app has accumulated copy-pasted, drifting UI and needs one coherent, themeable set of primitives that compose cleanly.
-
-1. Establish the token layer first: define semantic CSS custom properties (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--ring`, radii, spacing) so theming/dark mode is a variable swap, not a rewrite.
-2. Build on accessible headless primitives (Radix UI / React Aria) for behavior — focus management, ARIA, keyboard — and own only the styling layer, shadcn/ui style (copy-in components you can edit, not a locked dependency).
-3. Manage variants with a typed API via `cva` (class-variance-authority): explicit `variant` and `size` props, a single source of truth for every visual state, sane defaults.
-4. Make composition the contract: forward refs, spread `...props`, expose `asChild` (Radix Slot) so a `Button` can render as a link, and prefer slots over a sea of boolean props.
-5. Define every interactive state in the recipe — hover, active, `focus-visible` ring, `disabled`, loading, invalid — and wire motion to your shared duration/easing tokens.
-6. Document with live examples (Storybook or an MDX kitchen-sink page) and lock visual regressions; every component ships with usage + a11y notes.
-
-## Rules
-- Components are unopinionated about layout — no fixed margins; spacing belongs to the parent. They size to context.
-- Accessibility is non-negotiable: keyboard-operable, correct roles/labels, `focus-visible` rings, contrast ≥4.5:1 for text.
-- One token system; a hard-coded hex or pixel value inside a component is a leak to fix, not ship.
-- Prefer composition over configuration — when prop count explodes, split the component or expose subcomponents (`Card.Header`).
-- Keep the bundle lean: tree-shakeable exports, no kitchen-sink barrel that drags in everything.
+---
+name: component-library
+description: Build a reusable, composable, accessible component library in the shadcn/ui style with design tokens.
+category: ui-design
+---
+
+# Component Library
+
+Reach for this when an app has accumulated copy-pasted, drifting UI and needs one coherent, themeable set of primitives that compose cleanly.
+
+1. Establish the token layer first: define semantic CSS custom properties (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--ring`, radii, spacing) so theming/dark mode is a variable swap, not a rewrite.
+2. Build on accessible headless primitives (Radix UI / React Aria) for behavior — focus management, ARIA, keyboard — and own only the styling layer, shadcn/ui style (copy-in components you can edit, not a locked dependency).
+3. Manage variants with a typed API via `cva` (class-variance-authority): explicit `variant` and `size` props, a single source of truth for every visual state, sane defaults.
+4. Make composition the contract: forward refs, spread `...props`, expose `asChild` (Radix Slot) so a `Button` can render as a link, and prefer slots over a sea of boolean props.
+5. Define every interactive state in the recipe — hover, active, `focus-visible` ring, `disabled`, loading, invalid — and wire motion to your shared duration/easing tokens.
+6. Document with live examples (Storybook or an MDX kitchen-sink page) and lock visual regressions; every component ships with usage + a11y notes.
+
+## Rules
+- Components are unopinionated about layout — no fixed margins; spacing belongs to the parent. They size to context.
+- Accessibility is non-negotiable: keyboard-operable, correct roles/labels, `focus-visible` rings, contrast ≥4.5:1 for text.
+- One token system; a hard-coded hex or pixel value inside a component is a leak to fix, not ship.
+- Prefer composition over configuration — when prop count explodes, split the component or expose subcomponents (`Card.Header`).
+- Keep the bundle lean: tree-shakeable exports, no kitchen-sink barrel that drags in everything.

package/skills/dark-mode/SKILL.md

@@ -1,24 +1,24 @@
----
-name: dark-mode
-description: Implement a polished dark mode via semantic tokens and prefers-color-scheme, not naive color inversion
-category: ui-design
----
-
-# Dark Mode
-
-Use this to add a dark theme that looks designed rather than inverted. Good dark mode is a parallel palette tuned for a dark substrate — it's not `filter: invert()`.
-
-1. Theme through semantic tokens only: components read `--bg`, `--surface`, `--text`, `--border`, `--accent`. Dark mode redefines those aliases; component CSS doesn't change.
-2. Avoid pure black (`#000`) backgrounds — use a very dark neutral (~oklch 0.18–0.22) so OLED smearing and harsh contrast soften, and so elevation can read.
-3. Signal elevation with lighter surfaces, not shadows: raised cards get a slightly lighter `--surface-raised`. Shadows mostly disappear on dark; lightness becomes the depth cue.
-4. Soften text: don't use `#fff` for body — drop to ~85–90% lightness to reduce halation, and re-check that muted text still clears 4.5:1 against the dark surface.
-5. Reduce accent chroma slightly and verify it on dark — saturated hues that pop on white can vibrate on dark; tune `--accent` and `--accent-fg` per theme.
-6. Wire it up: default to `@media (prefers-color-scheme: dark)`, allow a manual override via `[data-theme="dark"]` on `<html>`, persist the choice, and set `<meta name="color-scheme">` to avoid a white flash.
-7. Dim large imagery/illustration in dark (e.g. slightly lower brightness) and provide dark-tuned shadows/borders so nothing glows.
-
-## Rules
-- Re-check contrast in dark independently — passing in light guarantees nothing.
-- No pure `#000` background and no pure `#fff` text; both fatigue the eye.
-- Convey depth with surface lightness, not drop shadows, in dark.
-- Respect system preference by default, but let users override and persist it.
-- Theme via token redefinition; never fork component styles per mode.
+---
+name: dark-mode
+description: Implement a polished dark mode via semantic tokens and prefers-color-scheme, not naive color inversion
+category: ui-design
+---
+
+# Dark Mode
+
+Use this to add a dark theme that looks designed rather than inverted. Good dark mode is a parallel palette tuned for a dark substrate — it's not `filter: invert()`.
+
+1. Theme through semantic tokens only: components read `--bg`, `--surface`, `--text`, `--border`, `--accent`. Dark mode redefines those aliases; component CSS doesn't change.
+2. Avoid pure black (`#000`) backgrounds — use a very dark neutral (~oklch 0.18–0.22) so OLED smearing and harsh contrast soften, and so elevation can read.
+3. Signal elevation with lighter surfaces, not shadows: raised cards get a slightly lighter `--surface-raised`. Shadows mostly disappear on dark; lightness becomes the depth cue.
+4. Soften text: don't use `#fff` for body — drop to ~85–90% lightness to reduce halation, and re-check that muted text still clears 4.5:1 against the dark surface.
+5. Reduce accent chroma slightly and verify it on dark — saturated hues that pop on white can vibrate on dark; tune `--accent` and `--accent-fg` per theme.
+6. Wire it up: default to `@media (prefers-color-scheme: dark)`, allow a manual override via `[data-theme="dark"]` on `<html>`, persist the choice, and set `<meta name="color-scheme">` to avoid a white flash.
+7. Dim large imagery/illustration in dark (e.g. slightly lower brightness) and provide dark-tuned shadows/borders so nothing glows.
+
+## Rules
+- Re-check contrast in dark independently — passing in light guarantees nothing.
+- No pure `#000` background and no pure `#fff` text; both fatigue the eye.
+- Convey depth with surface lightness, not drop shadows, in dark.
+- Respect system preference by default, but let users override and persist it.
+- Theme via token redefinition; never fork component styles per mode.

package/skills/dashboard-ui/SKILL.md

@@ -1,23 +1,23 @@
----
-name: dashboard-ui
-description: Design a clean, scannable data dashboard — clear hierarchy, restrained color, and fast comprehension.
-category: ui-design
----
-
-# Dashboard UI
-
-Reach for this when building an analytics or operations dashboard, where the job is to surface signal fast and let users act without hunting.
-
-1. Lead with the answer: a top row of 3–5 KPI stat cards (big number, label, trend delta with direction color), then supporting charts, then granular tables — most important, top-left.
-2. Lay out on a 12-column grid with consistent gutters and an 8px spacing rhythm; use container queries so cards reflow by their own width, not just the viewport.
-3. Keep the palette near-monochrome for chrome (neutral surfaces, one muted border token) and reserve saturated color strictly for data and semantic states (up/down, success/warn/error) so meaning pops.
-4. Set an information density that fits the user: align numbers right, use tabular figures (`font-variant-numeric: tabular-nums`), and tighten line-height in tables while keeping comfortable card padding.
-5. Make charts honest and minimal: drop chartjunk, label directly over legends where possible, start bar axes at zero, and cap each chart to one clear question.
-6. Provide structural states — loading skeletons matching card shapes, empty states with a next action, and persistent filters that don't reset on navigation.
-
-## Rules
-- Color carries data meaning; never decorate the UI with the same hues you use for series, or users misread the charts.
-- Whitespace is a feature — resist cramming; a scannable dashboard beats a complete-but-dense one.
-- Use semantic green/red for trends but never rely on color alone — pair with arrows/signs for color-blind users (contrast ≥3:1).
-- Numbers are the hero: tabular figures, right alignment, sensible rounding and units; no jittering digit widths.
-- Keep the navigation/chrome quiet so the data is the brightest thing on screen.
+---
+name: dashboard-ui
+description: Design a clean, scannable data dashboard — clear hierarchy, restrained color, and fast comprehension.
+category: ui-design
+---
+
+# Dashboard UI
+
+Reach for this when building an analytics or operations dashboard, where the job is to surface signal fast and let users act without hunting.
+
+1. Lead with the answer: a top row of 3–5 KPI stat cards (big number, label, trend delta with direction color), then supporting charts, then granular tables — most important, top-left.
+2. Lay out on a 12-column grid with consistent gutters and an 8px spacing rhythm; use container queries so cards reflow by their own width, not just the viewport.
+3. Keep the palette near-monochrome for chrome (neutral surfaces, one muted border token) and reserve saturated color strictly for data and semantic states (up/down, success/warn/error) so meaning pops.
+4. Set an information density that fits the user: align numbers right, use tabular figures (`font-variant-numeric: tabular-nums`), and tighten line-height in tables while keeping comfortable card padding.
+5. Make charts honest and minimal: drop chartjunk, label directly over legends where possible, start bar axes at zero, and cap each chart to one clear question.
+6. Provide structural states — loading skeletons matching card shapes, empty states with a next action, and persistent filters that don't reset on navigation.
+
+## Rules
+- Color carries data meaning; never decorate the UI with the same hues you use for series, or users misread the charts.
+- Whitespace is a feature — resist cramming; a scannable dashboard beats a complete-but-dense one.
+- Use semantic green/red for trends but never rely on color alone — pair with arrows/signs for color-blind users (contrast ≥3:1).
+- Numbers are the hero: tabular figures, right alignment, sensible rounding and units; no jittering digit widths.
+- Keep the navigation/chrome quiet so the data is the brightest thing on screen.

package/skills/design-system/SKILL.md

@@ -1,24 +1,24 @@
----
-name: design-system
-description: Build a cohesive design system from tokens up to components, with one source of truth and zero magic numbers
-category: ui-design
----
-
-# Design System
-
-Reach for this when a UI has grown inconsistent — drifting spacings, one-off colors, copy-pasted buttons — or when starting a product that needs to scale past a few screens.
-
-1. Audit what exists: screenshot every surface, list every distinct color, font size, radius, shadow, and spacing in use. The sprawl you find is the problem statement.
-2. Define the token layer first (see the design-tokens skill): primitives (`--blue-500`), then semantic aliases (`--color-accent`, `--bg-surface`, `--text-muted`). Components reference semantics only, never primitives.
-3. Lock the foundations: a modular type scale (1.2–1.25 ratio), a 4px spacing base, a radius set (sm/md/lg/full), and 2–3 elevation shadows. Everything downstream composes from these.
-4. Build primitives as composable components: Button (variant × size × state), Input, Card, Badge. Encode every visual decision as a token, so a theme swap is a token swap.
-5. Codify states explicitly — default, hover, focus-visible, active, disabled, loading. A system that only specifies the resting state isn't a system.
-6. Document usage with live examples and do/don't pairs (Storybook or an MDX page). A token nobody knows about gets bypassed.
-7. Ship with lint guardrails: reject raw hex and arbitrary px in PRs so drift can't creep back in.
-
-## Rules
-- One source of truth: a value lives in exactly one token; if you typed a hex or px in a component, it's a bug.
-- Two-tier tokens always — primitive then semantic — so re-theming touches the alias layer only.
-- Name by role, not by look: `--color-danger`, not `--color-red` (red may become orange later).
-- Every interactive component must define focus-visible and disabled, not just hover.
-- Prefer composition over variant explosion; if a component has 12 boolean props, split it.
+---
+name: design-system
+description: Build a cohesive design system from tokens up to components, with one source of truth and zero magic numbers
+category: ui-design
+---
+
+# Design System
+
+Reach for this when a UI has grown inconsistent — drifting spacings, one-off colors, copy-pasted buttons — or when starting a product that needs to scale past a few screens.
+
+1. Audit what exists: screenshot every surface, list every distinct color, font size, radius, shadow, and spacing in use. The sprawl you find is the problem statement.
+2. Define the token layer first (see the design-tokens skill): primitives (`--blue-500`), then semantic aliases (`--color-accent`, `--bg-surface`, `--text-muted`). Components reference semantics only, never primitives.
+3. Lock the foundations: a modular type scale (1.2–1.25 ratio), a 4px spacing base, a radius set (sm/md/lg/full), and 2–3 elevation shadows. Everything downstream composes from these.
+4. Build primitives as composable components: Button (variant × size × state), Input, Card, Badge. Encode every visual decision as a token, so a theme swap is a token swap.
+5. Codify states explicitly — default, hover, focus-visible, active, disabled, loading. A system that only specifies the resting state isn't a system.
+6. Document usage with live examples and do/don't pairs (Storybook or an MDX page). A token nobody knows about gets bypassed.
+7. Ship with lint guardrails: reject raw hex and arbitrary px in PRs so drift can't creep back in.
+
+## Rules
+- One source of truth: a value lives in exactly one token; if you typed a hex or px in a component, it's a bug.
+- Two-tier tokens always — primitive then semantic — so re-theming touches the alias layer only.
+- Name by role, not by look: `--color-danger`, not `--color-red` (red may become orange later).
+- Every interactive component must define focus-visible and disabled, not just hover.
+- Prefer composition over variant explosion; if a component has 12 boolean props, split it.

package/skills/design-tokens/SKILL.md

@@ -1,24 +1,24 @@
----
-name: design-tokens
-description: Define color, space, type, radius, and shadow tokens as layered CSS custom properties with semantic roles
-category: ui-design
----
-
-# Design Tokens
-
-Use this to turn scattered hardcoded values into a small, principled set of variables that every component reads from — the foundation under any design system or theme.
-
-1. Split into two tiers: a primitive scale (`--gray-50`…`--gray-950`, `--blue-500`) that names raw values, and a semantic layer (`--bg`, `--surface`, `--text`, `--border`, `--accent`) that maps roles onto primitives.
-2. Build space on a 4px base as a scale, not ad-hoc: `--space-1: 4px` … `--space-8: 32px`. Components only ever use scale steps, killing 13px and 27px outliers.
-3. Define type tokens from a ratio (see typography): `--text-sm/base/lg/xl/2xl` plus `--leading-tight/normal/relaxed` and `--tracking-tight`. Pair each size with a sensible line-height.
-4. Standardize radius (`--radius-sm/md/lg/full`) and elevation (`--shadow-sm/md/lg`) as layered, low-alpha shadows — never a single harsh `0 2px 4px #000`.
-5. Express color in `oklch()` for perceptually even ramps and easy lightness flips; provide `--color-*` semantic aliases so dark mode redefines the alias, not the component.
-6. Scope tokens to `:root`, override per-theme via `[data-theme]` or `@media (prefers-color-scheme)`, and expose only semantic tokens to component code.
-7. Generate platform outputs (CSS vars, Tailwind config, JSON) from one source file (e.g. Style Dictionary) so web and native never diverge.
-
-## Rules
-- Components consume semantic tokens only; primitives are private implementation detail.
-- No naked values in component CSS — every color, space, radius, and shadow is a `var(--…)`.
-- Name tokens by purpose (`--text-muted`) not appearance (`--gray-400`).
-- Keep each scale short (5–9 steps); an infinite ramp invites inconsistency.
-- Use `oklch()`/`hsl()` over hex so you can derive hover/active states by nudging lightness.
+---
+name: design-tokens
+description: Define color, space, type, radius, and shadow tokens as layered CSS custom properties with semantic roles
+category: ui-design
+---
+
+# Design Tokens
+
+Use this to turn scattered hardcoded values into a small, principled set of variables that every component reads from — the foundation under any design system or theme.
+
+1. Split into two tiers: a primitive scale (`--gray-50`…`--gray-950`, `--blue-500`) that names raw values, and a semantic layer (`--bg`, `--surface`, `--text`, `--border`, `--accent`) that maps roles onto primitives.
+2. Build space on a 4px base as a scale, not ad-hoc: `--space-1: 4px` … `--space-8: 32px`. Components only ever use scale steps, killing 13px and 27px outliers.
+3. Define type tokens from a ratio (see typography): `--text-sm/base/lg/xl/2xl` plus `--leading-tight/normal/relaxed` and `--tracking-tight`. Pair each size with a sensible line-height.
+4. Standardize radius (`--radius-sm/md/lg/full`) and elevation (`--shadow-sm/md/lg`) as layered, low-alpha shadows — never a single harsh `0 2px 4px #000`.
+5. Express color in `oklch()` for perceptually even ramps and easy lightness flips; provide `--color-*` semantic aliases so dark mode redefines the alias, not the component.
+6. Scope tokens to `:root`, override per-theme via `[data-theme]` or `@media (prefers-color-scheme)`, and expose only semantic tokens to component code.
+7. Generate platform outputs (CSS vars, Tailwind config, JSON) from one source file (e.g. Style Dictionary) so web and native never diverge.
+
+## Rules
+- Components consume semantic tokens only; primitives are private implementation detail.
+- No naked values in component CSS — every color, space, radius, and shadow is a `var(--…)`.
+- Name tokens by purpose (`--text-muted`) not appearance (`--gray-400`).
+- Keep each scale short (5–9 steps); an infinite ramp invites inconsistency.
+- Use `oklch()`/`hsl()` over hex so you can derive hover/active states by nudging lightness.

package/skills/empty-states/SKILL.md

@@ -1,23 +1,23 @@
----
-name: empty-states
-description: Design empty, loading, and error states that orient the user and offer a clear next action.
-category: ui-design
----
-
-# Empty States
-
-Reach for this whenever a view can have no data, be loading, or fail — these states are most of the real experience and deserve the same care as the happy path.
-
-1. Distinguish the three cases and design each: first-run empty (no data yet), cleared empty (filters/search returned nothing), and error (something broke) — they need different copy and actions.
-2. For first-run, make it a launchpad: a short encouraging line, a focused illustration or icon, and one primary CTA that creates the first item — turn the void into onboarding.
-3. For "no results", explain why and give an out: echo the active query/filters and offer "clear filters" or a broader suggestion, not a generic shrug.
-4. For errors, be specific and recoverable: plain-language cause, a "Try again" action, and a path to support — never expose a raw stack trace or a bare "Something went wrong".
-5. Match the layout to the eventual content so the page doesn't jump when data arrives, and keep tone consistent with the product's voice (helpful, not cute-at-the-user's-expense).
-6. Respect hierarchy and restraint: one illustration, one heading, one action; muted supporting text; accessible contrast and a real `role`/announcement for error states.
-
-## Rules
-- Every empty/error state offers at least one obvious next step — a dead end with no action is a bug.
-- Error copy names what happened and what to do; "Oops!" with no recovery path is failure theater.
-- Don't reuse the first-run empty state for "no search results" — they imply different user situations.
-- Keep illustrations subtle and on-brand; they support the message, they aren't the message.
-- Announce errors to assistive tech (`aria-live="assertive"` / `role="alert"`) and keep focus recoverable.
+---
+name: empty-states
+description: Design empty, loading, and error states that orient the user and offer a clear next action.
+category: ui-design
+---
+
+# Empty States
+
+Reach for this whenever a view can have no data, be loading, or fail — these states are most of the real experience and deserve the same care as the happy path.
+
+1. Distinguish the three cases and design each: first-run empty (no data yet), cleared empty (filters/search returned nothing), and error (something broke) — they need different copy and actions.
+2. For first-run, make it a launchpad: a short encouraging line, a focused illustration or icon, and one primary CTA that creates the first item — turn the void into onboarding.
+3. For "no results", explain why and give an out: echo the active query/filters and offer "clear filters" or a broader suggestion, not a generic shrug.
+4. For errors, be specific and recoverable: plain-language cause, a "Try again" action, and a path to support — never expose a raw stack trace or a bare "Something went wrong".
+5. Match the layout to the eventual content so the page doesn't jump when data arrives, and keep tone consistent with the product's voice (helpful, not cute-at-the-user's-expense).
+6. Respect hierarchy and restraint: one illustration, one heading, one action; muted supporting text; accessible contrast and a real `role`/announcement for error states.
+
+## Rules
+- Every empty/error state offers at least one obvious next step — a dead end with no action is a bug.
+- Error copy names what happened and what to do; "Oops!" with no recovery path is failure theater.
+- Don't reuse the first-run empty state for "no search results" — they imply different user situations.
+- Keep illustrations subtle and on-brand; they support the message, they aren't the message.
+- Announce errors to assistive tech (`aria-live="assertive"` / `role="alert"`) and keep focus recoverable.

package/skills/hero-section/SKILL.md

@@ -1,23 +1,23 @@
----
-name: hero-section
-description: Design a striking, conversion-focused hero with one clear message, sharp hierarchy, and a single CTA.
-category: ui-design
----
-
-# Hero Section
-
-Reach for this for the first screen of a landing page — the hero has ~3 seconds to land the value proposition and drive one action.
-
-1. Lock the message architecture: one eyebrow/kicker (optional), one headline stating the outcome (not the feature), one subhead clarifying, one primary CTA. Cut everything else.
-2. Build a real type scale with `clamp()` — e.g. headline `clamp(2.5rem, 5vw + 1rem, 5rem)`, tight `line-height: 1.05`, and `letter-spacing: -0.02em` on large display text for an editorial feel.
-3. Establish hierarchy through contrast, not just size: the CTA is the highest-contrast element on screen; the subhead sits in a muted foreground; supporting visuals never out-shout the headline.
-4. Give it breathing room — generous vertical rhythm on an 8px scale, a constrained measure (~60ch) on the subhead, and asymmetry (off-center text + image) to avoid a sterile centered template.
-5. Add one tasteful motion beat on load: staggered fade-rise of headline → subhead → CTA (40–60ms apart, ease-out, ≤400ms total). Subtle, once, never looping.
-6. Engineer for performance and LCP: the headline is real text (not an image), hero media is `priority`/preloaded and properly sized, and the layout is reserved to prevent CLS.
-
-## Rules
-- One primary CTA. A secondary "Learn more" can exist as a quieter ghost/text link, never a competing button.
-- The headline sells the outcome to the user; if it could appear on a competitor's site verbatim, rewrite it.
-- Maintain ≥4.5:1 contrast for headline text over any image/gradient — add a scrim or duotone rather than risk legibility.
-- Don't center everything by reflex; intentional asymmetry and a strong grid read as designed, not default.
-- Hero must be legible and complete above the fold on a 360px phone before you polish desktop.
+---
+name: hero-section
+description: Design a striking, conversion-focused hero with one clear message, sharp hierarchy, and a single CTA.
+category: ui-design
+---
+
+# Hero Section
+
+Reach for this for the first screen of a landing page — the hero has ~3 seconds to land the value proposition and drive one action.
+
+1. Lock the message architecture: one eyebrow/kicker (optional), one headline stating the outcome (not the feature), one subhead clarifying, one primary CTA. Cut everything else.
+2. Build a real type scale with `clamp()` — e.g. headline `clamp(2.5rem, 5vw + 1rem, 5rem)`, tight `line-height: 1.05`, and `letter-spacing: -0.02em` on large display text for an editorial feel.
+3. Establish hierarchy through contrast, not just size: the CTA is the highest-contrast element on screen; the subhead sits in a muted foreground; supporting visuals never out-shout the headline.
+4. Give it breathing room — generous vertical rhythm on an 8px scale, a constrained measure (~60ch) on the subhead, and asymmetry (off-center text + image) to avoid a sterile centered template.
+5. Add one tasteful motion beat on load: staggered fade-rise of headline → subhead → CTA (40–60ms apart, ease-out, ≤400ms total). Subtle, once, never looping.
+6. Engineer for performance and LCP: the headline is real text (not an image), hero media is `priority`/preloaded and properly sized, and the layout is reserved to prevent CLS.
+
+## Rules
+- One primary CTA. A secondary "Learn more" can exist as a quieter ghost/text link, never a competing button.
+- The headline sells the outcome to the user; if it could appear on a competitor's site verbatim, rewrite it.
+- Maintain ≥4.5:1 contrast for headline text over any image/gradient — add a scrim or duotone rather than risk legibility.
+- Don't center everything by reflex; intentional asymmetry and a strong grid read as designed, not default.
+- Hero must be legible and complete above the fold on a 360px phone before you polish desktop.