@rokkit/cli 1.3.6 → 1.3.7

package/README.md

@@ -111,7 +111,7 @@ bunx @rokkit/cli bundle -i ./icons -o ./dist
 
 ## Icon Folder Layout
 
-```
+```text
 src/
   ui/
     menu.svg
@@ -125,7 +125,7 @@ src/
 
 Running `rokkit build -i src -o lib` produces:
 
-```
+```text
 lib/
   ui.json
   solid.json

package/agents/rokkit-components-reviewer.md

@@ -0,0 +1,105 @@
+---
+name: rokkit-components-reviewer
+description: Use this agent to review how a Rokkit-powered app USES components — is it at the simplest customization tier that works (data → data+fields → custom icons → snippets), or did it jump straight to itemContent and re-implement icon/label/badge by hand? It also gives dedicated help for custom icons (UnoCSS i-* classes / @rokkit/icons collections vs literal-text-or-emoji fields) and typography usage (font-heading/font-body/font-mono vs hardcoded font-family). Reviews component usage before coding and verifies after with a build plus Playwright snapshots.\n\n<example>\nContext: A developer built a sidebar with a fully custom itemContent snippet that renders an icon and a badge by hand.\nuser: "Review my List usage — I wrote an itemContent snippet to show an icon, label, and a count badge."\nassistant: "I'll launch the rokkit-components-reviewer agent — icon, label, and badge are all data-driven fields, so this is likely a Tier 0/1 case and the snippet is throwing away the built-in renderer. I'll confirm and verify a clean build plus snapshots."\n<commentary>\nReaching for itemContent to show an icon/badge/description is the single most common Rokkit misuse — this agent steers the developer down to the simplest tier that works.\n</commentary>\n</example>\n\n<example>\nContext: A developer is unsure how to add custom icons and a display font to their Rokkit components.\nuser: "How should I wire custom icons and our brand heading font into these Rokkit lists and tabs?"\nassistant: "I'll use the rokkit-components-reviewer agent to check the icon field usage (UnoCSS i-* classes / @rokkit/icons collections vs literal text/emoji) and confirm typography goes through font-heading/font-body/font-mono rather than a hardcoded font-family."\n<commentary>\nCustom icons and typography usage across components is this agent's dedicated support area, on top of the customization-tier review.\n</commentary>\n</example>
+tools: Read, Grep, Glob, Bash, mcp__plugin_sensei_sensei__*
+model: sonnet
+color: purple
+---
+
+# Rokkit Components Reviewer
+
+You review how an app **uses Rokkit components** — never the Rokkit library itself. Rokkit is
+data-first: pass an array, bind a value, and the component renders icon/label/description/badge/
+avatar/shortcut and handles keyboard + ARIA for free. Customization is a **ladder** — your job is
+to keep consumers on the **lowest rung that works**, and to get **custom icons** and **typography**
+right along the way. The `rokkit-components` skill is the reference for the API and tiers — cite it,
+don't restate it.
+
+## Mindset
+
+- **Simplest tier that works.** Going straight to `itemContent`/`groupContent` is the most common
+  mistake — it discards the built-in renderer and re-implements icon/label/badge by hand for every
+  consumer. Push work **down** the ladder:
+  - **Tier 0** — `<List {items}>`: primitives, or objects whose keys already match defaults
+    (`label`, `icon`, `value`, `badge`, `description`, `avatar`, `shortcut`, `href`, `children`).
+  - **Tier 1** — add `fields={{…}}`: same data, different key names. A read-only remap; never mutates data.
+  - **Tier 2** — per-item/per-group named snippets (`item.snippet = 'name'`): a *few* rows need
+    bespoke markup; every other row keeps the default renderer.
+  - **Tier 3** — `itemContent`/`groupContent`: blanket custom markup for *every* item. Last resort —
+    you now own icon/label/badge layout yourself.
+- **"Is this just an icon / badge / description / avatar / second line?"** If yes, it's **data** —
+  Tier 0/1, not a snippet. Snippets are for structurally different markup (an inline control, a
+  chart, a bespoke layout).
+- **Right component for the need.** `List` (always-visible options) vs `Select` (space-limited,
+  closes); `Toggle` (2–5 mode switch) vs `Tabs` (panels); `Tree` (genuinely hierarchical) vs `List`.
+- **The data-first contract is consistent.** `items`/`options`/`data`, `bind:value`, `fields`,
+  `onchange`/`onselect`. Flag off-contract usage (e.g. manual `focus()` — the component syncs
+  `bind:value` to focus itself; or `onclick` on an element that also carries `data-path`, which
+  the navigator double-fires).
+
+### Custom icons
+
+- The `icon` field is dual-purpose: a **UnoCSS icon class** (`i-lucide:home`, `i-rokkit-ui:menu`,
+  `i-rokkit-solid:action-check`) renders as an icon; **any other string** (a single char, an emoji
+  like `⭐`, `列`) renders as **literal text**. So "1-char text vs icon" is the same field — no snippet
+  needed either way.
+- Custom icon sets come from `@rokkit/icons` (Iconify JSON collections: `ui`, `semantic`, `glyph`,
+  `light`, `solid`, `twotone`, `auth`, `app`), registered via `presetRokkit({ icons: [...] })` in
+  `uno.config.js`. The **semantic** collection backs component icon shortcuts; `icons.style`
+  (e.g. `'solid'`) switches all component icons globally.
+- Findings to raise: an `icon` class whose collection isn't loaded in `uno.config.js` (renders
+  nothing); a snippet written solely to place an `<span class={icon}>` that the `icon` field would
+  render for free; inline `<svg>` where an `i-*` class belongs.
+
+### Typography
+
+- Usage goes through config-mapped utilities: `font-heading` (display face), `font-body` (UI face),
+  `font-mono` — set once in `rokkit.config.js` `typography: { display, ui, mono }`. Flag any
+  hardcoded `font-family:` or arbitrary `font-[...]` in component markup; map it to the right class.
+- Faces belong in config, not per-component. If a needed face isn't declared, the fix is to add it
+  to `typography:` (a styling-config change — hand off to the styles review), not to inline it.
+
+## Procedure
+
+Navigate with the **sensei MCP tools first** (indexed graph, richer than grep); fall back to
+Grep/Glob only if a tool errors or returns empty, and say so.
+
+1. `get_project_summary()` + `get_project_conventions()` + `get_rules()` — stack, house style, rules.
+2. `search("@rokkit/ui")` / `search("List")` / `search("Select")` … to enumerate component usage
+   sites; Read each. For every usage, classify the tier and whether it's the **lowest that works**.
+3. For each `itemContent`/`groupContent` snippet, ask the demotion question: does it render only
+   data-shaped content (icon/label/badge/description/avatar/shortcut)? If so, flag it as
+   over-customized and give the Tier 0/1 rewrite.
+4. Icons: Grep for `icon`, `i-`, and inline `<svg>` in component usage; cross-check icon-class
+   prefixes against the collections loaded in `uno.config.js`. Typography: Grep for `font-family`
+   and `font-[` in `.svelte`/`.css`; map to `font-heading/body/mono`.
+5. Check contract hygiene: `bind:value` present, correct `onchange` vs `onselect`, no manual
+   `focus()`, no `onclick` on `[data-path]` elements, correct data prop per component
+   (`items`/`options`/`data`).
+
+## Verification evidence (required)
+
+Do not report a verdict without pasting **real output** from commands you ran in the consuming app:
+
+1. **Build** — run the app's build (e.g. `bun run build`, or its documented equivalent). Paste the
+   final status lines. A build that fails (missing icon collection, bad snippet, type error) is a FAIL.
+2. **Playwright snapshots** — drive the reviewed screens and capture snapshots proving the components
+   render (icons visible, labels/badges present) in light and dark. Paste the command and pass/fail
+   summary; call out any missing icon or blank render.
+
+If a step can't run, say so and mark the affected criteria unverified — never imply evidence you
+don't have. A piped/`| tail` exit status reports the pipe, not the command: read the real exit status.
+
+## Report Format
+
+- **Summary** — one paragraph: what you reviewed and the headline result.
+- **Customization tier** — a table per usage: `file:line` · component · current tier · recommended
+  tier · the simpler rewrite (when demotable).
+- **Custom icons** — findings: unloaded collections, snippet-for-an-icon, inline SVG → `i-*` class.
+- **Typography** — hardcoded `font-family`/`font-[...]` findings → `font-heading/body/mono` (or a
+  `typography:` config addition to hand off).
+- **Contract hygiene** — off-contract usage (wrong data prop, manual focus, `onclick` on `[data-path]`).
+- **Verification evidence** — the pasted build output + Playwright snapshot summary (light/dark).
+- **### Verdict PASS/FAIL** — PASS only when each usage is at the simplest tier that works, icons and
+  typography go through the intended mechanisms, the contract is respected, and the build + snapshots
+  are green. Otherwise FAIL with the blocking items listed.

package/agents/rokkit-styles-reviewer.md

@@ -0,0 +1,92 @@
+---
+name: rokkit-styles-reviewer
+description: Use this agent to review a Rokkit-powered app's styling BEFORE coding and to VERIFY it AFTER — is rokkit.config.js palette/skin/token wiring correct, are components using named tokens (paper/ink/primary/on-primary) instead of raw hex/oklch, and do they respect shape/typography config instead of hardcoding? It reviews config-to-usage wiring and dark-mode correctness, then verifies with a real build plus Playwright theme/mode snapshots.\n\n<example>\nContext: A developer has just wired rokkit.config.js and styled a few screens in a Rokkit app and wants a check before going further.\nuser: "I set up rokkit.config.js and styled the dashboard. Does the theming hold up in dark mode?"\nassistant: "I'll launch the rokkit-styles-reviewer agent to audit the palette→skin→token wiring, confirm components use named tokens rather than raw colors, and verify the dark-mode flip with a build and theme/mode snapshots."\n<commentary>\nStyling/config wiring plus a dark-mode question in a Rokkit app is exactly this agent's remit — it reviews the config-to-usage seam and verifies the flip empirically.\n</commentary>\n</example>\n\n<example>\nContext: A component uses literal oklch/hex colors and the reviewer wants to catch it before it spreads.\nuser: "Review the styling on the new settings panel — I may have hardcoded some colors."\nassistant: "I'll use the rokkit-styles-reviewer agent to find raw hex/oklch and rounded-[..]/font-family literals, map them to the right named tokens and shape/typography classes, then verify a clean build and snapshots."\n<commentary>\nRaw color and shape/typography literals bypass the token pipeline and break theming — the styles reviewer's core catch, with build + snapshot verification.\n</commentary>\n</example>
+tools: Read, Grep, Glob, Bash, mcp__plugin_sensei_sensei__*
+model: sonnet
+color: cyan
+---
+
+# Rokkit Styles Reviewer
+
+You review the **styling of an app that consumes Rokkit** — never the Rokkit library itself.
+Your job is two-phase: **advise before coding** (is the config wiring and token usage right?)
+and **verify after** (does it build, and do the theme/mode snapshots hold?). You default to
+the simplest correct wiring and you refuse to sign off on evidence you did not actually run.
+
+The consistency guarantee is the token pipeline: `rokkit.config.js` (palettes → skin → tokens)
+→ `presetRokkit` → CSS custom properties + named-token utilities. Components read **named
+tokens** (`bg-paper`, `text-ink`, `text-on-primary`), never raw color. Break that indirection
+and the app stops reskinning from config. The `semantic-styles-rokkit` skill is the reference
+for the vocabulary — cite it, don't restate it.
+
+## Mindset
+
+- **Config is the single source of truth.** A color, radius, or font that lives in a component
+  instead of the config is a defect, even if it looks right today — it won't survive a reskin
+  or a dark-mode flip.
+- **Named tokens over raw values, always.** `text-ink` not `color: #3D3730`; `bg-primary` not
+  `oklch(0.58 0.15 35)`; `rounded-md` not `rounded-[6px]`; `font-body` not `font-family: Inter`.
+- **The vocabulary is extensible, not a cage.** If the design needs a token the core set lacks
+  (`on-accent`, `accent-2`, an `-line` color), the fix is `overrides:` (or `tokens: 'extended'`)
+  — not a hardcoded literal. Never conclude "core doesn't have it, so I'll inline a color."
+- **Dark mode is not free.** Named tokens flip only when the skin maps a role dual-palette
+  (`{ light, dark }`) or an override carries a `dark` side. A single-palette `surface` emits no
+  `[data-mode="dark"]` block → effectively light-only.
+- **Evidence beats assertion.** You do not say "theming works" — you build and snapshot and
+  paste what you saw.
+
+### Questions to answer
+
+1. Does `rokkit.config.js` exist and is `presetRokkit(config)` actually used in `uno.config.js`?
+2. Is there an `ink` role in the active colormap? (Without it, `ink-*` text silently falls back
+   to the surface palette.) Is exactly one of `skin:` / `skins:` used (not both)?
+3. Are `surface` and `ink` dual-palette `{ light, dark }` if the app claims dark-mode support?
+4. Do components read named tokens everywhere, or are there raw hex/oklch/rgb literals?
+5. Are radius and font applied via config-mapped utilities (`rounded-md`, `font-heading/body/mono`)
+   or hardcoded (`rounded-[6px]`, `font-family:`)?
+6. For any custom design token, is it declared in `overrides:` with **dot-notation** palette refs
+   (`'sky.600'`, and `sky` present in `palettes:`) — not inlined, not `'sky-600'`?
+7. Is theme application delegated to `vibe` + `themable` + the flash-prevention hook, or hand-rolled?
+
+## Procedure
+
+Navigate with the **sensei MCP tools first** — they use the indexed code graph and return richer
+results than blind grep. Fall back to Grep/Glob only if a tool errors or returns empty, and say so.
+
+1. `get_project_summary()` + `get_project_conventions()` — establish stack, structure, and the
+   house style you are reviewing against. `get_rules()` — honor any project styling rules.
+2. Locate and Read `rokkit.config.js` and `uno.config.js`. Resolve the active colormap the way the
+   preset does: `skins.default ?? skin ?? colors`. Record the roles, `colorSpace`, `tokens` mode,
+   `overrides`, `shape`, and `typography`.
+3. `search("color")` / `search("oklch")` / `search("rgb")` across the app's components, plus
+   Grep for `#[0-9a-fA-F]{3,8}`, `oklch(`, `rgb(`, `rounded-\[`, and `font-family` in `.svelte`/`.css`.
+   Every hit is a candidate finding — map each to the named token / shape / typography class it
+   should be.
+4. Check the dark-mode wiring against Q3/Q7 above (dual-palette roles + `themable`/hook), and run
+   `rokkit doctor` if available — fold its advisory warnings (`skin-ink-role`, `oklch-needs-palettes`,
+   `colors-alias`) into your report.
+
+## Verification evidence (required)
+
+Do not report a verdict without pasting **real output** from commands you ran in the consuming app:
+
+1. **Build** — run the app's build (e.g. `bun run build`, or its documented equivalent). Paste the
+   final status lines. A build that fails on an unknown palette/shade or a bad override is a FAIL.
+2. **Theme/mode snapshots** — drive Playwright to capture the reviewed screens in **light and dark**
+   (and any additional skins the app ships). Paste the command and the pass/fail summary; note any
+   screen that does not visibly flip between modes.
+
+If you cannot run a step, say so explicitly and mark the affected criteria unverified — never imply
+evidence you don't have. A piped/`| tail` exit status reports the pipe, not the command: read the
+real exit status before calling it green.
+
+## Report Format
+
+- **Summary** — one paragraph: what you reviewed and the headline result.
+- **Config wiring** — findings on `rokkit.config.js` / `uno.config.js` (roles, dark mode, overrides).
+- **Token usage** — a table of raw-literal findings: `file:line` · what's hardcoded · the token/class
+  it should be.
+- **Shape / typography** — hardcoded radius/font findings and their config-mapped replacements.
+- **Verification evidence** — the pasted build output + Playwright snapshot summary (light/dark).
+- **### Verdict PASS/FAIL** — PASS only when config wiring is correct, no raw literals remain in the
+  reviewed scope, and the build + snapshots are green. Otherwise FAIL with the blocking items listed.

package/dist/src/agents.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Read the bundled agent catalog (derived from each <name>.md frontmatter).
+ * @param {{ agentsDir?: string }} [opts]
+ * @returns {Array<{ name: string, description: string }>}
+ */
+export function listAgents({ agentsDir }?: {
+    agentsDir?: string;
+}): Array<{
+    name: string;
+    description: string;
+}>;
+/**
+ * Copy named agents into <cwd>/.claude/agents/<name>.md from the bundled catalog (idempotent).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, agentsDir?: string }} [opts]
+ * @returns {Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>}
+ */
+export function installAgents(names: string[], { cwd, force, agentsDir }?: {
+    cwd?: string;
+    force?: boolean;
+    agentsDir?: string;
+}): Array<{
+    name: string;
+    status: "added" | "skipped" | "unknown";
+}>;
+/**
+ * Fetch named agents from the public site and write them into <cwd>/.claude/agents/<name>.md.
+ * Lets the CLI pull from the site when the bundled catalog is absent (or on `--remote`).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, baseUrl?: string, fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>>}
+ */
+export function fetchAgents(names: string[], { cwd, force, baseUrl, fetchImpl }?: {
+    cwd?: string;
+    force?: boolean;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<Array<{
+    name: string;
+    status: "added" | "skipped" | "unknown";
+}>>;
+/**
+ * Print the catalog, marking already-installed agents.
+ * @param {{ agentsDir?: string, cwd?: string }} [opts]
+ */
+export function runAgentsList({ agentsDir, cwd }?: {
+    agentsDir?: string;
+    cwd?: string;
+}): Promise<void>;
+/**
+ * Resolve which agents to install, then copy (or fetch with --remote) and report.
+ * @param {string[]} names
+ * @param {{ all?: boolean, force?: boolean, remote?: boolean, agentsDir?: string, cwd?: string, fetchImpl?: typeof fetch }} [opts]
+ */
+export function runAgentsAdd(names: string[], { all, force, remote, agentsDir, cwd, fetchImpl }?: {
+    all?: boolean;
+    force?: boolean;
+    remote?: boolean;
+    agentsDir?: string;
+    cwd?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<void>;
+/**
+ * CLI entry for `rokkit agents` subcommands.
+ * @param {'list' | 'add'} sub
+ * @param {{ _?: string[], all?: boolean, force?: boolean, remote?: boolean }} [opts]
+ */
+export function agentsCommand(sub: "list" | "add", opts?: {
+    _?: string[];
+    all?: boolean;
+    force?: boolean;
+    remote?: boolean;
+}): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@mdi/svg": "^7.4.47",
-    "@rokkit/unocss": "1.3.6",
+    "@rokkit/unocss": "1.3.7",
     "sade": "^1.8.1",
     "@iconify/tools": "5.0.3",
     "@iconify/types": "^2.0.0",
@@ -38,6 +38,7 @@
     "lib/**/*",
     "src/**/*.js",
     "skills/**",
+    "agents/**",
     "dist/**/*.d.ts",
     "README.md",
     "package.json",

package/skills/command-system-rokkit/SKILL.md

@@ -8,7 +8,7 @@ description: Use when adding keyboard shortcuts, a command palette, or app-level
 Three packages, one coherent system — commands live in a registry, shortcuts fire them from the keyboard,
 the palette lets users search and run them by name.
 
-```
+```text
 @rokkit/states → commands registry (register, execute, resolve, commands.all)
 @rokkit/actions → shortcuts action (use:shortcuts={commands})
 @rokkit/ui → CommandPalette component (<CommandPalette bind:open />)
@@ -22,7 +22,7 @@ Commands are the same shape — registry singleton + action wiring + a ready-mad
 ## The three pieces
 
 | Package | Export | Role |
-|---------|--------|------|
+| --------- | -------- | ------ |
 | `@rokkit/states` | `commands` | Singleton registry — register, resolve, execute |
 | `@rokkit/actions` | `shortcuts` | Svelte action — intercepts `keydown`, delegates to `commands` |
 | `@rokkit/ui` | `CommandPalette` | Searchable dialog — reads `commands.all`, opens on `mod+k` |
@@ -185,7 +185,7 @@ any list reading `commands.all` automatically re-renders when commands are added
 primary shortcuts so they are cross-platform by default.
 
 | Shortcut string | Fires on |
-|-----------------|----------|
+| ----------------- | ---------- |
 | `'mod+k'` | Cmd+K (macOS) / Ctrl+K (other) |
 | `'mod+shift+l'` | Cmd+Shift+L / Ctrl+Shift+L |
 | `'mod+shift+n'` | Cmd+Shift+N / Ctrl+Shift+N |
@@ -247,7 +247,7 @@ Default English values: `placeholder: 'Run a command…'`, `noResults: 'No comma
 ## Common mistakes
 
 | Mistake | Why it fails | Fix |
-|---------|-------------|-----|
+| --------- | ------------- | ----- |
 | Registering at module top-level (not in `onMount`) | The registry is a singleton; commands pile up across hot-reloads in dev and are never cleaned up on unmount | Always register in `onMount`, return the unregister fn |
 | Forgetting `global: true` on `mod+k` (or any Cmd-shortcut) | `shortcuts` skips non-global commands while a text input is focused — Cmd+K fired in the composer silently no-ops | Add `global: true` to any command that must fire during text input |
 | Hand-rolling `window.addEventListener('keydown', ...)` | No conflict detection, no `enabled()` gate, no `commands.all` integration, no cleanup | Use `use:shortcuts={commands}` — it handles all of these |

package/skills/rokkit-components/SKILL.md

@@ -23,7 +23,7 @@ import { List, Tree, Select, MultiSelect, Menu, Table, Tabs, Toggle } from '@rok
 Every Rokkit component follows a consistent API:
 
 | Prop | Purpose |
-|------|---------|
+| ------ | --------- |
 | `items` / `options` / `data` | The data array to render |
 | `bind:value` | Bindable selected value (or values array for MultiSelect) |
 | `fields` | Remap your data's key names to component semantic keys |
@@ -74,7 +74,7 @@ It never mutates your data — it is only a read instruction for the component.
 These are the raw key names each component reads by default. Override only the ones that differ in your data.
 
 | Semantic slot | Default key | Used by |
-|---------------|-------------|---------|
+| --------------- | ------------- | --------- |
 | `label` / `text` | `'label'` / `'text'` | display text (see note) |
 | `value` | `'value'` | selection value |
 | `icon` | `'icon'` | icon CSS class |
@@ -172,7 +172,7 @@ Overrides the group header button content (the expand/collapse header row):
 ### ProxyItem API (passed to all content snippets)
 
 | Property / method | Description |
-|-------------------|-------------|
+| ------------------- | ------------- |
 | `proxy.label` | Mapped display text |
 | `proxy.icon` | Mapped icon CSS class |
 | `proxy.value` | The original raw item (object or primitive) |
@@ -259,7 +259,7 @@ The navigator pattern handles keyboard events on the component's root or dropdow
 ### What you get for free
 
 | Component | Keys | ARIA |
-|-----------|------|------|
+| ----------- | ------ | ------ |
 | List / Tree | `↑↓` move focus, `↵`/`Space` select, `→`/`←` expand/collapse groups, `Home`/`End`, typeahead `a-z` | `role="navigation"`, `aria-current="page"` on active link |
 | Select / MultiSelect | `↑↓` navigate dropdown, `↵` select/toggle, `Esc` close, `Home`/`End` | `role="combobox"`, `aria-expanded`, `aria-selected` |
 | Menu | `↑↓` navigate items, `↵`/`Space` select, `Esc` close + return focus | `role="menu"`, `role="menuitem"` |
@@ -300,7 +300,7 @@ intercepts those clicks and would double-fire.
 ## Which component when
 
 | Need | Component | Data prop | Callback |
-|------|-----------|-----------|----------|
+| ------ | ----------- | ----------- | ---------- |
 | Vertical navigable list (sidebar nav, option list) | `List` | `items` | `onselect` |
 | Hierarchical tree with expand/collapse | `Tree` | `items` | `onselect` |
 | Dropdown single selection | `Select` | `items` | `onchange` |

package/skills/semantic-styles-rokkit/SKILL.md

@@ -10,7 +10,7 @@ set of utility classes. Components use **named tokens** (`bg-paper`, `text-ink`,
 `text-on-primary`) — never raw hex/oklch values. That indirection is the consistency
 guarantee: change the config, the whole app reskins.
 
-```
+```text
 rokkit.config.js
   palettes + skin + colorSpace + tokens
        ↓
@@ -34,6 +34,7 @@ text-on-fill all come from one color family. 11 stops gives resolution without b
 **Two formats:**
 
 *RGB hex* — standard web colors; use when you have an existing brand palette:
+
 ```js
 palettes: { shu: { 50: '#FEF3EE', 500: '#E8552B', 950: '#3C100A' } }
 // colorSpace: 'rgb' (default — may be omitted)
@@ -41,6 +42,7 @@ palettes: { shu: { 50: '#FEF3EE', 500: '#E8552B', 950: '#3C100A' } }
 
 *OKLCH bare components* — perceptual, uniform lightness steps; best for palettes designed
 from scratch (increment L by equal steps for balanced results):
+
 ```js
 palettes: { shu: { 50: '0.970 0.020 35', 500: '0.580 0.150 35', 950: '0.220 0.060 35' } },
 colorSpace: 'oklch'   // REQUIRED when palette values are bare "L C H" components
@@ -61,6 +63,7 @@ them — they only matter if you opt into `tokens: 'extended'` for those roles.)
 `bg-paper` doesn't know whether `surface` is `kami`, `slate`, or `zinc`.
 
 ### Single skin (`skin:`) — one fixed colormap
+
 ```js
 skin: {
   surface: 'slate',  ink: 'slate',   // ink backs the ink-* text tokens
@@ -68,24 +71,29 @@ skin: {
   success: 'green', warning: 'yellow', danger: 'red', error: 'red', info: 'cyan',
 }
 ```
+
 `colors:` is accepted as a back-compat alias but **prefer `skin:`**. Always include an
 `ink` role — without it the `ink-*` text tokens silently fall back to the surface palette.
 
 ### Multi-skin (`skins:`) — named colormaps for runtime switching
+
 ```js
 skins: {
   default: { surface: { light: 'kami', dark: 'sumi' }, ink: { light: 'kami', dark: 'sumi' }, primary: 'shu' },
   ocean:   { surface: 'slate', primary: 'sky', accent: 'teal' },
 }
 ```
+
 `skins.default` is active on first load. **Use `skin:` OR `skins:`, not both** — providing
 `skins:` makes `skin:` ignored.
 
 ### `tokens:` — which CSS the preset emits
+
 ```js
 tokens: 'core'      // default — emit the 24 named tokens (palette values inlined)
 tokens: 'extended'  // also emit the full 11-shade ladder (--color-{role}-{shade}) per role
 ```
+
 `'core'` is the default and what apps should use. Reach for `'extended'` only when you need
 the full ladder (charts / data-viz). Per-role is allowed: `tokens: { surface: 'extended' }`.
 
@@ -154,6 +162,7 @@ flash-prevention init script), **saves on every change**, and syncs across tabs
 ```
 
 **3. Switch the visual style** by setting state — no DOM writes:
+
 ```svelte
 <button onclick={() => (vibe.style = 'minimal')}>Minimal</button>
 ```
@@ -221,17 +230,19 @@ emits no utility (used inside `box-shadow` expressions).
 Named tokens emit `--{token}` vars holding **complete color values** —
 `--paper: oklch(0.985 0.005 85)` (oklch) or `--primary: rgb(232, 85, 43)` (rgb). Use them
 directly in CSS-only contexts; for alpha, use `color-mix` (the form the preset itself uses):
+
 ```css
 .thing      { background: var(--paper); border-color: var(--paper-edge); }
 .thing-50pc { background: color-mix(in oklch, var(--primary) 50%, transparent); }
 ```
+
 Prefer utility classes over raw vars where you can.
 
 ---
 
 ## Layer 3b — Extending the vocabulary (`overrides` + `tokens: extended`)
 
-**The named-token set is the _default_ vocabulary, not a hard limit.** When a design needs
+**The named-token set is the *default* vocabulary, not a hard limit.** When a design needs
 a token the core set lacks — a second accent tone, a dedicated `on-accent` text color, a
 divider-line color — add it. Don't conclude "core only has `accent`/`accent-soft`, so this
 can't be expressed." Two mechanisms:
@@ -299,6 +310,7 @@ Default stays `'core'`.
 
 **`rokkit init`** scaffolds `rokkit.config.js` in the named-token shape (a header comment
 documents the vocabulary). Two starters via the palette prompt:
+
 - **Tailwind (rgb)** — `skin` of Tailwind palette names, `colorSpace: 'rgb'`, `tokens: 'core'`. Single-palette → light-leaning (see Layer 2b).
 - **Zen-Sumi (OKLCH)** — ships `palettes` (kami/sumi/shu/…), `colorSpace: 'oklch'`, dual-palette `surface`/`ink` → full dark mode out of the box.
 
@@ -308,7 +320,7 @@ mode init script), it runs **advisory** config-shape warnings and migration hint
 fail the command or block `--fix`:
 
 | Check | Warns when |
-|-------|-----------|
+| ------- | ----------- |
 | `skin-ink-role` | the active colormap has no `ink` role (text tokens fall back) |
 | `oklch-needs-palettes` | `colorSpace: 'oklch'` but no `palettes` block |
 | `colors-alias` | config uses the legacy `colors:` instead of `skin:` |
@@ -321,6 +333,7 @@ colors`. Run `rokkit doctor --fix` to auto-write a real starter config when one
 ## Typography configuration
 
 Set faces in config; the preset emits CSS vars and Tailwind `fontFamily` keys.
+
 ```js
 typography: {
   display: "'Fraunces', 'Iowan Old Style', Georgia, serif",  // heading/display face
@@ -328,8 +341,10 @@ typography: {
   mono:    "'JetBrains Mono', 'SF Mono', Menlo, monospace",
 }
 ```
+
 Canonical config keys are `display` / `ui` / `mono`; `heading` / `sans` are accepted
 aliases. Usage classes: `font-heading` (display face), `font-body` (UI face), `font-mono`.
+
 ```html
 <h1 class="font-heading text-2xl text-ink">Page Title</h1>
 <p  class="font-body text-[13px] text-ink-mute">Description</p>
@@ -343,7 +358,7 @@ aliases. Usage classes: `font-heading` (display face), `font-body` (UI face), `f
 `shape: { radius: 'soft' }` selects a preset emitting `--radius-{sm,md,lg,xl,full}`.
 
 | Preset | sm | md | lg | xl | full | Personality |
-|--------|----|----|----|----|------|-------------|
+| -------- | ---- | ---- | ---- | ---- | ------ | ------------- |
 | `sharp` | 0 | 0 | 0 | 0 | 9999px | Minimal, editorial |
 | `soft` | 2px | 6px | 10px | 12px | 9999px | Professional, calm |
 | `rounded` | 4px | 8px | 12px | 16px | 9999px | Friendly, modern |
@@ -360,7 +375,7 @@ never `rounded-[6px]`, which bypasses the config.
 Rokkit inherits Tailwind's 4px-grid spacing. **Stay on the 4px grid, use Tailwind names.**
 
 | Tailwind | px | When |
-|----------|----|------|
+| ---------- | ---- | ------ |
 | `1` / `2` / `3` | 4 / 8 / 12 | tight gap · component gap · compact padding |
 | `4` / `6` | 16 / 24 | default padding · panel padding |
 | `8` / `12` / `16` | 32 / 48 / 64 | section separation · page padding · hero whitespace |
@@ -400,7 +415,7 @@ export default {
 ## Common mistakes
 
 | Mistake | Why it fails | Fix |
-|---|---|---|
+| --- | --- | --- |
 | "core only emits `accent`/`accent-soft`, so I can't have `accent-2`/`on-accent`" | the vocabulary is extensible, not fixed | add them under `overrides:` (or use `tokens: 'extended'`) — see Layer 3b |
 | Override palette ref `'sky-600'` (hyphen) | refs use **dot** notation | `'sky.600'` (and `sky` must be in `palettes:`) |
 | `color: #3D3730` in a component | breaks on theme change | `text-ink` (or the right named token) |

package/skills/skin-system-rokkit/SKILL.md

@@ -14,7 +14,7 @@ shifts.
 **Skin vs style vs mode:**
 
 | Dimension | Controls | Example values |
-|-----------|----------|----------------|
+| ----------- | ---------- | ---------------- |
 | **skin** | which palette backs the roles | `default` · `ocean` · `violet` |
 | **style** | which visual theme (border radius, shadow, surface recipe) | `rokkit` · `minimal` · `zen-sumi` |
 | **mode** | light or dark rendering | `light` · `dark` |
@@ -59,7 +59,7 @@ The preset ships five built-in skins in `@rokkit/unocss`. Their `[data-skin='nam
 blocks are emitted automatically — no config needed to use them:
 
 | Skin | Surface | Ink | Primary | Accent |
-|------|---------|-----|---------|--------|
+| ------ | --------- | ----- | --------- | -------- |
 | `default` | (DEFAULT_THEME_MAPPING) | `slate` | — | — |
 | `ocean` | `slate` | `slate` | `sky` | `teal` |
 | `violet` | `zinc` | `zinc` | `violet` | `indigo` |
@@ -124,7 +124,7 @@ When `storageKey` is provided it also loads/saves the persisted skin.
 **`SkinSwitcherToggle` props:**
 
 | Prop | Type | Default | Purpose |
-|------|------|---------|---------|
+| ------ | ------ | --------- | --------- |
 | `skins` | `Array<string \| { name, label?, icon? }>` | `vibe.allowedSkins` | skin options |
 | `labels` | `Record<string, string>` | `{}` | display labels keyed by name |
 | `showLabels` | `boolean` | `false` | show label text in the toggle |
@@ -215,7 +215,7 @@ runtime-only color overrides.
 ## Common mistakes
 
 | Mistake | Why it fails | Fix |
-|---------|-------------|-----|
+| --------- | ------------- | ----- |
 | `vibe.allowedSkins` set after `themable` runs | persisted skin can't restore; `vibe.skin = storedValue` is a no-op because the list defaults to `['default']` only | set `vibe.allowedSkins` before `<svelte:body use:themable ...>` in the root layout |
 | `class="skin-ocean"` on an element | `skin-{name}` class was removed | use `data-skin='ocean'` attribute, or let `themable` write it via `vibe.skin` |
 | Hand-rolling `<style>` injection for a skin | brittle, order-dependent, bypasses named-token aliases | define in `rokkit.config.js` `skins:` + let the preset emit `[data-skin='name']` blocks |

package/src/agents.js

@@ -0,0 +1,170 @@
+/* eslint-disable no-console */
+import {
+	readFileSync,
+	readdirSync,
+	existsSync,
+	mkdirSync,
+	writeFileSync,
+	copyFileSync
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import prompts from 'prompts'
+import { parseFrontmatter } from './skills.js'
+
+// The catalog ships inside the package: packages/cli/agents/ in dev/test,
+// node_modules/@rokkit/cli/agents/ once installed. Agents are single .md files
+// (unlike skills, which are directories with a SKILL.md).
+// Guard against non-file: URLs (e.g. jsdom sets import.meta.url to http://localhost/...).
+const DEFAULT_AGENTS_DIR = (() => {
+	try {
+		return fileURLToPath(new URL('../agents/', import.meta.url))
+	} catch {
+		return resolve(process.cwd(), 'packages/cli/agents')
+	}
+})()
+
+// Public base the CLI can pull agents from when the bundled copy is unavailable
+// (`--remote`). Same corpus that the sensei.library.json manifest advertises.
+const DEFAULT_AGENTS_URL = 'https://rokkit.sensei-hq.com/agents'
+
+/**
+ * Read the bundled agent catalog (derived from each <name>.md frontmatter).
+ * @param {{ agentsDir?: string }} [opts]
+ * @returns {Array<{ name: string, description: string }>}
+ */
+export function listAgents({ agentsDir = DEFAULT_AGENTS_DIR } = {}) {
+	if (!existsSync(agentsDir)) return []
+	return readdirSync(agentsDir)
+		.filter((entry) => entry.endsWith('.md'))
+		.map((entry) => parseFrontmatter(readFileSync(join(agentsDir, entry), 'utf-8')))
+		.filter((a) => a.name)
+		.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Copy named agents into <cwd>/.claude/agents/<name>.md from the bundled catalog (idempotent).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, agentsDir?: string }} [opts]
+ * @returns {Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>}
+ */
+export function installAgents(
+	names,
+	{ cwd = process.cwd(), force = false, agentsDir = DEFAULT_AGENTS_DIR } = {}
+) {
+	const targetRoot = resolve(cwd, '.claude', 'agents')
+	return names.map((name) => {
+		const src = join(agentsDir, `${name}.md`)
+		if (!existsSync(src)) return { name, status: 'unknown' }
+		const dest = join(targetRoot, `${name}.md`)
+		if (existsSync(dest) && !force) return { name, status: 'skipped' }
+		mkdirSync(targetRoot, { recursive: true })
+		copyFileSync(src, dest)
+		return { name, status: 'added' }
+	})
+}
+
+/**
+ * Fetch named agents from the public site and write them into <cwd>/.claude/agents/<name>.md.
+ * Lets the CLI pull from the site when the bundled catalog is absent (or on `--remote`).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, baseUrl?: string, fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>>}
+ */
+export async function fetchAgents(
+	names,
+	{ cwd = process.cwd(), force = false, baseUrl = DEFAULT_AGENTS_URL, fetchImpl = fetch } = {}
+) {
+	const targetRoot = resolve(cwd, '.claude', 'agents')
+	const results = []
+	for (const name of names) {
+		const dest = join(targetRoot, `${name}.md`)
+		if (existsSync(dest) && !force) {
+			results.push({ name, status: 'skipped' })
+			continue
+		}
+		const res = await fetchImpl(`${baseUrl}/${name}.md`)
+		if (!res.ok) {
+			results.push({ name, status: 'unknown' })
+			continue
+		}
+		mkdirSync(targetRoot, { recursive: true })
+		writeFileSync(dest, await res.text())
+		results.push({ name, status: 'added' })
+	}
+	return results
+}
+
+/**
+ * Print the catalog, marking already-installed agents.
+ * @param {{ agentsDir?: string, cwd?: string }} [opts]
+ */
+export async function runAgentsList({ agentsDir, cwd = process.cwd() } = {}) {
+	const catalog = listAgents({ agentsDir })
+	if (catalog.length === 0) {
+		console.info('No agents available.')
+		return
+	}
+	const installedRoot = resolve(cwd, '.claude', 'agents')
+	console.info('Available Rokkit agents:\n')
+	for (const a of catalog) {
+		const mark = existsSync(join(installedRoot, `${a.name}.md`)) ? '✓ ' : '  '
+		console.info(`${mark}${a.name}`)
+		console.info(`     ${a.description}`)
+	}
+	console.info('\nInstall with: rokkit agents add <name> [...]   (or --all)')
+}
+
+/**
+ * Resolve which agents to install, then copy (or fetch with --remote) and report.
+ * @param {string[]} names
+ * @param {{ all?: boolean, force?: boolean, remote?: boolean, agentsDir?: string, cwd?: string, fetchImpl?: typeof fetch }} [opts]
+ */
+export async function runAgentsAdd(
+	names,
+	{ all = false, force = false, remote = false, agentsDir, cwd = process.cwd(), fetchImpl } = {}
+) {
+	const catalog = listAgents({ agentsDir })
+	let selected = names
+	if (all) {
+		selected = catalog.map((a) => a.name)
+	} else if (selected.length === 0) {
+		const res = await prompts({
+			type: 'multiselect',
+			name: 'picked',
+			message: 'Select agents to add',
+			choices: catalog.map((a) => ({ title: a.name, value: a.name, description: a.description }))
+		})
+		selected = res.picked ?? []
+	}
+	if (selected.length === 0) {
+		console.info('No agents selected.')
+		return
+	}
+	const results = remote
+		? await fetchAgents(selected, { cwd, force, fetchImpl })
+		: installAgents(selected, { cwd, force, agentsDir })
+	for (const r of results) {
+		if (r.status === 'added') console.info(`  added .claude/agents/${r.name}.md`)
+		else if (r.status === 'skipped')
+			console.info(`  skipped ${r.name} (exists — use --force to overwrite)`)
+		else console.error(`  unknown agent: ${r.name}`)
+	}
+	if (results.some((r) => r.status === 'unknown')) {
+		if (!remote) console.error(`\nValid agents: ${catalog.map((a) => a.name).join(', ')}`)
+		process.exitCode = 1
+	}
+}
+
+/**
+ * CLI entry for `rokkit agents` subcommands.
+ * @param {'list' | 'add'} sub
+ * @param {{ _?: string[], all?: boolean, force?: boolean, remote?: boolean }} [opts]
+ */
+export async function agentsCommand(sub, opts = {}) {
+	if (sub === 'add') {
+		await runAgentsAdd(opts._ ?? [], { all: opts.all, force: opts.force, remote: opts.remote })
+	} else {
+		await runAgentsList()
+	}
+}

package/src/index.js

@@ -139,4 +139,23 @@ prog
 		await skillsCommand('add', opts)
 	})
 
+prog
+	.command('agents list')
+	.describe('List available Rokkit review agents')
+	.action(async () => {
+		const { agentsCommand } = await import('./agents.js')
+		await agentsCommand('list')
+	})
+
+prog
+	.command('agents add')
+	.describe('Add Rokkit review agents to .claude/agents/')
+	.option('--all', 'Install all available agents')
+	.option('--force', 'Overwrite an existing agent')
+	.option('--remote', 'Pull agents from the site instead of the bundled copy')
+	.action(async (opts) => {
+		const { agentsCommand } = await import('./agents.js')
+		await agentsCommand('add', opts)
+	})
+
 prog.parse(process.argv)