agent-whiteboard 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 1.3.1 — 2026-11-07
+
+Patch: documentation only.
+
+- **README reordered for users:** quickstart, MCP registration, agent skills, use cases and tools now come first; Environment variables and REST fallback follow; Development, Tests and Manual showcase are at the end. Added a "Jump to" line, moved the `/mcp` enable step into MCP registration, reworded the `.mcp.json` note for non-contributors, and listed `npm run check` under Tests.
+
+## 1.3.0 — 2026-11-07
+
+**Milestone v1.9 — Agent Skills & `install-skills` CLI (Sprint 92) complete.** Adds ready-made agent skills and a one-command installer (FR34 in `01`, F51–F54/NF58 in `03`).
+
+- **Agent skills (F51):** five skills in `skills/` teach an agent when and how to use the tools — `agent-whiteboard` (core rules), `whiteboard-teaching`, `whiteboard-assessment`, `whiteboard-analysis`, `whiteboard-design`. Shipped in the npm package (`files` now includes `skills`, F54).
+- **`install-skills` subcommand (F52):** `npx agent-whiteboard install-skills` copies them into `~/.claude/skills` (`--project` → `./.claude/skills`, `--dir <path>`, `--only a,b`, `--force`, `--list`). Existing skills are never overwritten without `--force`. `bin/cli.js` dispatches it before loading the server, so plain `npx agent-whiteboard` is unchanged.
+- **README (F53):** new Use cases (workflows per context) and Agent skills sections.
+- **Dev tooling:** `npm run check` (typecheck → lint → test → build) mirrors CI locally; ESLint ignores the gitignored `video/` folder. `test_skills.md` documents the manual skills test plan.
+- Tests: `installSkills.test.ts` (10 tests); 755 unit tests passing; `tsc`/`svelte-check`/`eslint`/`npm run build` clean.
+
+## 1.2.2 — 2026-11-07
+
+Patch: test-only fix, no behavioural change.
+
+- **Fix flaky CI test:** `import-zip.test.ts` "cleans up its temp directory" counted `agent-whiteboard-import-*` folders in the shared system tmpdir, which other test files (separate workers) also populate, so the before/after comparison raced. The test now uses a private `TMPDIR` and asserts it ends empty.
+
+## 1.2.1 — 2026-11-07
+
+Patch: lint fix, no behavioural change.
+
+- **Fix CI lint crash:** `Quiz.svelte` used a reactive arrow function (`$: resultFor = ...`) that made `svelte/no-reactive-functions` crash in its autofix under ESLint 10, failing `npm run lint` in CI. Replaced with a reactive `resultById` map.
+
 ## 1.2.0 — 2026-11-06
 
 **Milestone v1.8 — Quiz Support (Sprints 89–91) complete.** Adds interactive quizzes for reviewing the user's knowledge (FR33 in `01`, F44–F50/NF57 in `03`).

package/README.md

@@ -18,6 +18,8 @@ The browser also has a History panel for browsing, reloading, deleting, and expo
 
 <img src="docs/screenshots/history-panel.png" width="700" alt="History panel listing past snapshots grouped by workspace">
 
+**Jump to:** [Quickstart](#quickstart) · [MCP registration](#mcp-registration) · [Agent skills](#agent-skills) · [Use cases](#use-cases) · [MCP tools](#mcp-tools) · [Environment variables](#environment-variables) · [Development](#development) *(contributors)*
+
 ## How it works
 
 ```
@@ -54,38 +56,98 @@ By default the server only binds to loopback addresses (`localhost`/`127.0.0.1`/
 
 This is a **single-user, local-only** tool: there is no authentication on any endpoint. That's an accepted trade-off, not an oversight — the server refuses to start if `HOST` is set to anything other than a loopback address, unless you explicitly set `ALLOW_NON_LOOPBACK=1` (not recommended; anyone who can reach the port can render arbitrary content, read/delete your snapshot history, and exfiltrate exported data). Don't expose this server beyond your own machine.
 
-## Development
+## MCP registration
 
-Running from source (contributing, or testing an unreleased change) instead of `npx agent-whiteboard`:
+Add a `.mcp.json` to your project root (this repository already has one) and Claude Code picks it up automatically:
+
+```json
+{
+  "mcpServers": {
+    "agent-whiteboard": {
+      "type": "sse",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+The server must be running before Claude Code connects. The first time, run `/mcp` in Claude Code, select `agent-whiteboard` and enable it; the tools are available immediately. If you override `PORT`, update the URL above to match. See [Environment variables](#environment-variables) for the full list of overridable settings.
+
+## Agent skills
+
+The `skills/` folder ships ready-made [agent skills](https://docs.claude.com/en/docs/claude-code/skills) that teach an agent *when and how* to use the tools above. Start with `agent-whiteboard`; the others build on it.
+
+| Skill                   | Covers                                                            |
+|-------------------------|-------------------------------------------------------------------|
+| `agent-whiteboard`      | Core rules: workspaces, render types, pacing, step-frames, export |
+| `whiteboard-teaching`   | Explainers, build-ups, worked examples, guided lessons, branching |
+| `whiteboard-assessment` | Inline and deferred quizzes, remediation, spaced review           |
+| `whiteboard-analysis`   | Charts, exploration loops, findings walkthroughs, derivations     |
+| `whiteboard-design`     | Architecture sessions, option comparison, codebase explanation    |
+
+Install them with one command (no server is started):
 
 ```bash
-npm install
-npm run dev
+npx agent-whiteboard install-skills             # all skills → ~/.claude/skills (every project)
+npx agent-whiteboard install-skills --project   # → ./.claude/skills (this project only)
+npx agent-whiteboard install-skills --only agent-whiteboard,whiteboard-teaching
+npx agent-whiteboard install-skills --force     # overwrite skills that already exist
+npx agent-whiteboard install-skills --list      # show the bundled skills
 ```
 
-This starts the Node server (`:3000`), the Vite dev server (`:5173`), and opens the browser tab automatically.
+Existing skill folders are left untouched unless you pass `--force`. `--dir <path>` installs into any other folder (for agents that keep skills elsewhere). Prefer to do it by hand? Copy the folders from [`skills/`](skills/) yourself. Restart your agent session afterwards so it picks the skills up.
+
+## Use cases
+
+Agent Whiteboard is domain-agnostic; these are the workflows it is built for. Each links the tools involved.
+
+| Context                   | Workflow                                              | Tools                                                 |
+|---------------------------|-------------------------------------------------------|-------------------------------------------------------|
+| **Teaching & training**   | Concept explainer (one visual, then pause)            | `render` → `wait_done`                                |
+|                           | Progressive build-up of a diagram                     | step-frames + `wait_done` per frame                   |
+|                           | Worked example (math / algorithm), one step per frame | `katex` / `mermaid` step-frames, `step` / `seek`      |
+|                           | Learner-driven branching on a topic map               | `wait_click` with `node_actions`                      |
+| **Assessment**            | Inline self-check quiz (scored in the browser)        | `render` quiz with a key → `wait_quiz`                |
+|                           | Deferred quiz graded by the agent                     | `render` quiz without a key → `wait_quiz`             |
+|                           | Teach → quiz → remediate; spaced review               | quizzes + `list_snapshots`                            |
+| **Analysis & data**       | Iterative data exploration, version history           | `vega-lite` + `wait_done`, History panel              |
+|                           | Findings walkthrough / report                         | step-frames (`html` + `vega-lite`) + `export_html`    |
+|                           | Statistics / math derivation with an illustration     | `katex` + `vega-lite`                                 |
+| **Design & architecture** | Iterative system design, click to drill down          | `mermaid` + `wait_click`                              |
+|                           | Option comparison and decision                        | step-frames + `html` table                            |
+|                           | Explaining a codebase or protocol; onboarding pack    | sequence diagrams, step-frames, quiz, `export_html`   |
+| **Sharing**               | Export a lesson or analysis; share a workspace        | `export_html`; zip export/import in the History panel |
 
-Enable the MCP server in Claude Code the first time:
+## Example agent flow
 
 ```
-/mcp
+render(type="mermaid", payload="graph TD; A --> B", options={ workspace: "my-lesson", title: "System overview" })
+→ wait_done()   # agent pauses; user clicks Done when ready
+→ render(type="katex", payload="E = mc^2", options={ workspace: "my-lesson" })
+→ wait_done()
 ```
 
-Select `agent-whiteboard` and enable it. The tools will be available immediately.
+Paced, user-acknowledged reveal — interleave `wait_done()` between `append_frame()` calls so each frame waits for the user before the next one appears (useful for large or complex step-frames sequences the agent is building on the fly):
 
-## Environment variables
+```
+init_step_frames(frame_type="mermaid", workspace="my-lesson", title="TCP handshake")
+→ append_frame(id, payload="graph LR; Client -- SYN --> Server", label="1. SYN")
+→ wait_done()   # user reviews frame 1, clicks Done
+→ append_frame(id, payload="graph LR; Client -- SYN --> Server; Server -- SYN-ACK --> Client", label="2. SYN-ACK")
+→ wait_done()   # user reviews frame 2, clicks Done
+→ append_frame(id, payload="...", label="3. ACK")
+→ commit_step_frames(id)
+```
 
-| Variable                  | Default              | Description |
-|----------------------------|-----------------------|-------------|
-| `PORT`                     | `3000`                | Server port — serves the REST/MCP/WebSocket API, and (via `npx agent-whiteboard`) the built client too. |
-| `HOST`                     | `localhost`           | Bind address. Must resolve to a loopback address (`localhost`, `127.0.0.1`, `::1`) — the server refuses to start otherwise unless `ALLOW_NON_LOOPBACK` is set. See [Trust model](#trust-model). |
-| `ALLOW_NON_LOOPBACK`       | unset                 | Set to `1` to allow binding a non-loopback `HOST`. Not recommended — there is no authentication on any endpoint. |
-| `WHITEBOARD_SNAPSHOTS_DIR` | `~/.agent-whiteboard` | Snapshot storage location. |
-| `CHANNEL_PORT`             | `3001`                | Port for the stdio-channel HTTP relay used by Claude Code's channel forwarding (only relevant if Claude Code was started with channels enabled). |
+`wait_done()` isn't coupled to step-frames — it just blocks on the Done button — so this pattern works with any number of frames and needs no dedicated tool support.
 
-**Port conflicts:** if `:3000` (or `:3001`/`:5173`, see below) is already in use on your machine, set `PORT` (and `CHANNEL_PORT` if needed) to a free port before starting.
+Knowledge check — render a quiz and wait for the user to submit it (see [Quizzes](#quizzes)):
 
-> Dev-only (`npm run dev`, not `npx agent-whiteboard`): the Vite client dev server always runs on `:5173`, hardcoded in `client/vite.config.ts` — not currently configurable via an environment variable.
+```
+render(type="quiz", payload='{"questions":[{"id":"q1","text":"What does SYN start?","kind":"single","options":[{"id":"a","text":"A handshake"},{"id":"b","text":"A teardown"}]}]}', options={ workspace: "my-lesson" })
+→ wait_quiz()   # no answer key in the payload → deferred: the answers come back to the agent
+→ evaluate result.answers, explain the right answers, and score them
+```
 
 ## MCP tools
 
@@ -93,14 +155,14 @@ Select `agent-whiteboard` and enable it. The tools will be available immediately
 
 Push content to the whiteboard canvas. Replaces whatever is currently on screen.
 
-| `type` | `payload` |
-|---|---|
-| `"mermaid"` | Mermaid diagram source. Must begin with a valid keyword (`graph`, `flowchart`, `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `mindmap`). |
-| `"svg"` | Inline SVG markup. |
-| `"html"` | HTML/CSS fragment. Sanitized via DOMPurify — inline styles only; `<script>` and `<style>` tags are stripped. |
-| `"katex"` | LaTeX string, rendered in display mode. |
-| `"vega-lite"` | Vega-Lite JSON spec (must be valid JSON string). |
-| `"quiz"` | JSON quiz — see [Quizzes](#quizzes). Valid in `render()` only (not in `slideshow()` or step-frames). |
+| `type`        | `payload`                                                                                                                                                  |
+|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `"mermaid"`   | Mermaid diagram source. Must begin with a valid keyword (`graph`, `flowchart`, `sequenceDiagram`, `classDiagram`, `erDiagram`, `gantt`, `pie`, `mindmap`). |
+| `"svg"`       | Inline SVG markup.                                                                                                                                         |
+| `"html"`      | HTML/CSS fragment. Sanitized via DOMPurify — inline styles only; `<script>` and `<style>` tags are stripped.                                               |
+| `"katex"`     | LaTeX string, rendered in display mode.                                                                                                                    |
+| `"vega-lite"` | Vega-Lite JSON spec (must be valid JSON string).                                                                                                           |
+| `"quiz"`      | JSON quiz — see [Quizzes](#quizzes). Valid in `render()` only (not in `slideshow()` or step-frames).                                                       |
 
 `render()` is single-frame only. For a step-through sequence (multiple frames navigable via `step()`/`seek()`), use [`init_step_frames`/`append_frame`/`commit_step_frames`](#init_step_framesframe_type-workspace-title) instead — see [Step-frames sequences](#step-frames-sequences).
 
@@ -251,36 +313,33 @@ There is no one-shot way to render a multi-frame sequence — `render()` is sing
 }
 ```
 
-## Example agent flow
+## History & snapshots
 
-```
-render(type="mermaid", payload="graph TD; A --> B", options={ workspace: "my-lesson", title: "System overview" })
-→ wait_done()   # agent pauses; user clicks Done when ready
-→ render(type="katex", payload="E = mc^2", options={ workspace: "my-lesson" })
-→ wait_done()
-```
+Every `render()` / `commit_step_frames()` call writes a JSON snapshot to `~/.agent-whiteboard/<workspace>/` (override with the `WHITEBOARD_SNAPSHOTS_DIR` environment variable). The browser's right-side controls panel has a history toggle that opens a panel for browsing and loading past snapshots grouped by workspace, plus a delete button that opens a 2-step modal (`client/src/DeleteExportModal.svelte`) for deleting an entire workspace or a chosen subset of snapshots. Destructive actions require a second confirming click.
 
-Paced, user-acknowledged reveal — interleave `wait_done()` between `append_frame()` calls so each frame waits for the user before the next one appears (useful for large or complex step-frames sequences the agent is building on the fly):
+A single **Import / export** button (opposing-arrows icon) opens a small keyboard-accessible menu with two entries: **Export…** opens the same modal for exporting a workspace or subset of snapshots as self-contained HTML (the `export_html()` tool / `POST /export-html` endpoint described above) or as a portable `.zip` (`POST /export-zip`), and **Import…** opens a dialog for loading such a `.zip` into this or another whiteboard instance (`POST /import`, merging or creating a new workspace). Dropping a `.zip` anywhere on the page also starts an import.
 
-```
-init_step_frames(frame_type="mermaid", workspace="my-lesson", title="TCP handshake")
-→ append_frame(id, payload="graph LR; Client -- SYN --> Server", label="1. SYN")
-→ wait_done()   # user reviews frame 1, clicks Done
-→ append_frame(id, payload="graph LR; Client -- SYN --> Server; Server -- SYN-ACK --> Client", label="2. SYN-ACK")
-→ wait_done()   # user reviews frame 2, clicks Done
-→ append_frame(id, payload="...", label="3. ACK")
-→ commit_step_frames(id)
-```
+| Step 1 — choose a workspace                                                                                                                  | Step 2 — delete requires a second confirming click                                                                                    |
+|----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| <img src="docs/screenshots/delete-workspace-picker.png" width="380" alt="Delete/Export modal step 1: workspace picker with snapshot counts"> | <img src="docs/screenshots/delete-confirmation.png" width="380" alt="Delete confirmation: button relabels to Click again to confirm"> |
 
-`wait_done()` isn't coupled to step-frames — it just blocks on the Done button — so this pattern works with any number of frames and needs no dedicated tool support.
+| Step 2 — export a subset of snapshots                                                                          | The resulting self-contained HTML, opened directly in a browser |
+|----------------------------------------------------------------------------------------------------------------|---|
+| <img src="docs/screenshots/export-select-item.png" width="380" alt="Selecting individual snapshots to export"> | <img src="docs/screenshots/export-outputhtml.png" width="480" alt="Exported HTML file opened offline, showing the table of contents and rendered diagrams"> |
 
-Knowledge check — render a quiz and wait for the user to submit it (see [Quizzes](#quizzes)):
+## Environment variables
 
-```
-render(type="quiz", payload='{"questions":[{"id":"q1","text":"What does SYN start?","kind":"single","options":[{"id":"a","text":"A handshake"},{"id":"b","text":"A teardown"}]}]}', options={ workspace: "my-lesson" })
-→ wait_quiz()   # no answer key in the payload → deferred: the answers come back to the agent
-→ evaluate result.answers, explain the right answers, and score them
-```
+| Variable                    | Default                | Description                                                                                                                                                                                     |
+|-----------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `PORT`                      | `3000`                 | Server port — serves the REST/MCP/WebSocket API, and (via `npx agent-whiteboard`) the built client too.                                                                                         |
+| `HOST`                      | `localhost`            | Bind address. Must resolve to a loopback address (`localhost`, `127.0.0.1`, `::1`) — the server refuses to start otherwise unless `ALLOW_NON_LOOPBACK` is set. See [Trust model](#trust-model). |
+| `ALLOW_NON_LOOPBACK`        | unset                  | Set to `1` to allow binding a non-loopback `HOST`. Not recommended — there is no authentication on any endpoint.                                                                                |
+| `WHITEBOARD_SNAPSHOTS_DIR`  | `~/.agent-whiteboard`  | Snapshot storage location.                                                                                                                                                                      |
+| `CHANNEL_PORT`              | `3001`                 | Port for the stdio-channel HTTP relay used by Claude Code's channel forwarding (only relevant if Claude Code was started with channels enabled).                                                |
+
+**Port conflicts:** if `:3000` (or `:3001`/`:5173`, see below) is already in use on your machine, set `PORT` (and `CHANNEL_PORT` if needed) to a free port before starting.
+
+> Dev-only (`npm run dev`, not `npx agent-whiteboard`): the Vite client dev server always runs on `:5173`, hardcoded in `client/vite.config.ts` — not currently configurable via an environment variable.
 
 ## REST fallback
 
@@ -315,19 +374,24 @@ All tools have HTTP equivalents for scripting or testing without an MCP client:
 
 All endpoints return the same JSON shapes as the MCP tools, except `POST /export-html`, which streams the HTML file directly (`Content-Disposition: attachment`). `mode: "cdn"` (default) links Mermaid/Bootstrap/KaTeX from a CDN; `mode: "offline"` embeds them for offline reading, at the cost of a much larger file (the Mermaid bundle alone is ~3.3MB).
 
-## History & snapshots
+## Development
 
-Every `render()` / `commit_step_frames()` call writes a JSON snapshot to `~/.agent-whiteboard/<workspace>/` (override with the `WHITEBOARD_SNAPSHOTS_DIR` environment variable). The browser's right-side controls panel has a history toggle that opens a panel for browsing and loading past snapshots grouped by workspace, plus a delete button that opens a 2-step modal (`client/src/DeleteExportModal.svelte`) for deleting an entire workspace or a chosen subset of snapshots. Destructive actions require a second confirming click.
+Running from source (contributing, or testing an unreleased change) instead of `npx agent-whiteboard`:
 
-A single **Import / export** button (opposing-arrows icon) opens a small keyboard-accessible menu with two entries: **Export…** opens the same modal for exporting a workspace or subset of snapshots as self-contained HTML (the `export_html()` tool / `POST /export-html` endpoint described above) or as a portable `.zip` (`POST /export-zip`), and **Import…** opens a dialog for loading such a `.zip` into this or another whiteboard instance (`POST /import`, merging or creating a new workspace). Dropping a `.zip` anywhere on the page also starts an import.
+```bash
+npm install
+npm run dev
+```
 
-| Step 1 — choose a workspace                                                                                                                  | Step 2 — delete requires a second confirming click                                                                                    |
-|----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
-| <img src="docs/screenshots/delete-workspace-picker.png" width="380" alt="Delete/Export modal step 1: workspace picker with snapshot counts"> | <img src="docs/screenshots/delete-confirmation.png" width="380" alt="Delete confirmation: button relabels to Click again to confirm"> |
+This starts the Node server (`:3000`), the Vite dev server (`:5173`), and opens the browser tab automatically.
 
-| Step 2 — export a subset of snapshots                                                                          | The resulting self-contained HTML, opened directly in a browser |
-|----------------------------------------------------------------------------------------------------------------|---|
-| <img src="docs/screenshots/export-select-item.png" width="380" alt="Selecting individual snapshots to export"> | <img src="docs/screenshots/export-outputhtml.png" width="480" alt="Exported HTML file opened offline, showing the table of contents and rendered diagrams"> |
+## Tests
+
+```bash
+npm run check    # everything CI runs: typecheck → lint → unit tests → build
+npm test          # Vitest unit/integration tests (server + client)
+npm run test:e2e  # Playwright end-to-end tests (requires npm run dev:test first)
+```
 
 ## Manual showcase
 
@@ -358,30 +422,6 @@ Section flags (combinable):
 --intro-delay <ms>    How long each intro card stays up (default: 4000)
 ```
 
-## Tests
-
-```bash
-npm test          # Vitest unit/integration tests (server)
-npm run test:e2e  # Playwright end-to-end tests (requires npm run dev:test first)
-```
-
-## MCP registration
-
-`.mcp.json` is committed to the repo root and picked up automatically by Claude Code:
-
-```json
-{
-  "mcpServers": {
-    "agent-whiteboard": {
-      "type": "sse",
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}
-```
-
-The server must be running before Claude Code connects. If you override `PORT`, update the URL above to match. See [Environment variables](#environment-variables) for the full list of overridable settings.
-
 ## License
 
 [PolyForm Noncommercial License 1.0.0](LICENSE) — free to use, modify, and redistribute for any non-commercial purpose. Commercial use isn't covered by this license; if you want to use this commercially, reach out at bobpuley@gmail.com to discuss a license.

package/bin/cli.js

@@ -10,8 +10,17 @@
 
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import open from "open";
-import { startServer } from "../dist/server/index.js";
+
+// Subcommand: `agent-whiteboard install-skills ...` — copies the bundled agent
+// skills and exits, without loading the server. Dispatched before the server
+// imports below (loaded dynamically) so it stays fast and side-effect free.
+if (process.argv[2] === "install-skills") {
+  const { runInstallSkills } = await import("./install-skills.js");
+  process.exit(runInstallSkills(process.argv.slice(3)));
+}
+
+const { default: open } = await import("open");
+const { startServer } = await import("../dist/server/index.js");
 
 const here = dirname(fileURLToPath(import.meta.url));
 const staticRoot = join(here, "..", "dist", "client");

package/bin/install-skills.js

@@ -0,0 +1,108 @@
+// `agent-whiteboard install-skills` — copies the bundled agent skills into a
+// Claude Code skills folder. Plain ESM JS, no dependencies, so it works from
+// the npx cache without touching the server or the "open" package.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const BUNDLED_SKILLS_DIR = join(here, "..", "skills");
+
+export const USAGE = `Usage: agent-whiteboard install-skills [options]
+
+Copies the bundled agent skills into a Claude Code skills folder.
+
+Options:
+  --project        Install into ./.claude/skills (current project) instead of ~/.claude/skills
+  --dir <path>     Install into <path> (overrides --project)
+  --only <a,b,c>   Install only the named skills (comma-separated)
+  --force          Overwrite skills that already exist
+  --list           List the bundled skills and exit
+  -h, --help       Show this help`;
+
+export function listBundledSkills(srcDir = BUNDLED_SKILLS_DIR) {
+  if (!existsSync(srcDir)) return [];
+  return readdirSync(srcDir)
+    .filter((n) => statSync(join(srcDir, n)).isDirectory() && existsSync(join(srcDir, n, "SKILL.md")))
+    .sort();
+}
+
+export function parseArgs(argv) {
+  const opts = { project: false, dir: null, only: null, force: false, list: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project") opts.project = true;
+    else if (a === "--force") opts.force = true;
+    else if (a === "--list") opts.list = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--dir" || a === "--only") {
+      const v = argv[++i];
+      if (!v || v.startsWith("--")) throw new Error(`${a} requires a value`);
+      if (a === "--dir") opts.dir = v;
+      else opts.only = v.split(",").map((s) => s.trim()).filter(Boolean);
+    } else throw new Error(`unknown option: ${a}`);
+  }
+  return opts;
+}
+
+/**
+ * Copy skills. Returns { dest, installed, skipped } (skipped = already present, no --force).
+ * Throws on unknown --only names.
+ */
+export function installSkills({ srcDir = BUNDLED_SKILLS_DIR, dest, only = null, force = false }) {
+  const available = listBundledSkills(srcDir);
+  const names = only ?? available;
+  const unknown = names.filter((n) => !available.includes(n));
+  if (unknown.length) {
+    throw new Error(`unknown skill(s): ${unknown.join(", ")} (available: ${available.join(", ")})`);
+  }
+  mkdirSync(dest, { recursive: true });
+  const installed = [];
+  const skipped = [];
+  for (const name of names) {
+    const target = join(dest, name);
+    if (existsSync(target) && !force) {
+      skipped.push(name);
+      continue;
+    }
+    cpSync(join(srcDir, name), target, { recursive: true, force: true });
+    installed.push(name);
+  }
+  return { dest, installed, skipped };
+}
+
+/** CLI entry. Returns the process exit code. */
+export function runInstallSkills(argv, { log = console.log, err = console.error } = {}) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    err(`${e.message}\n\n${USAGE}`);
+    return 2;
+  }
+  if (opts.help) {
+    log(USAGE);
+    return 0;
+  }
+  if (opts.list) {
+    for (const n of listBundledSkills()) log(n);
+    return 0;
+  }
+  const dest = opts.dir
+    ? resolve(opts.dir)
+    : opts.project
+      ? resolve(process.cwd(), ".claude", "skills")
+      : join(homedir(), ".claude", "skills");
+  try {
+    const { installed, skipped } = installSkills({ dest, only: opts.only, force: opts.force });
+    for (const n of installed) log(`installed  ${n}`);
+    for (const n of skipped) log(`skipped    ${n} (already exists; use --force to overwrite)`);
+    log(`\nSkills folder: ${dest}`);
+    return 0;
+  } catch (e) {
+    err(`error: ${e.message}`);
+    return 1;
+  }
+}

package/dist/client/assets/{abnfDiagram-VCTEODGH-Dj8sd_5g.js → abnfDiagram-VCTEODGH-Bwh5lUgu.js}

@@ -1 +1 @@
-import{g as p,r as u,d as a}from"./chunk-SVP7TREG-COvqzqaO.js";import{p as f}from"./chunk-JWPE2WC7-tyYPyD43.js";import{_ as n,l as o}from"./mermaid.core-CLvSDmrA.js";import{M as c,b as d}from"./cynefin-OW5HDTMX-PWlPYnpn.js";import"./index-CIhkXT_z.js";import"./step-BEQzeS8V.js";var v=d().RailroadAbnf.parser.LangiumParser,i=n(e=>{const r=e.alternatives.map(g);return r.length===1?r[0]:{type:"choice",alternatives:r}},"transformAlternation"),g=n(e=>{const r=e.elements.map(y);return r.length===1?r[0]:{type:"sequence",elements:r}},"transformConcatenation"),b=n(e=>{if(e.includes("*")){const[t,s]=e.split("*"),l=t?parseInt(t,10):0,m=s?parseInt(s,10):1/0;return{min:l,max:m}}const r=parseInt(e,10);return{min:r,max:r}},"parseRepeat"),y=n(e=>{const r=A(e.primary);if(!e.repeat)return r;const{min:t,max:s}=b(e.repeat);return t===0&&s===1?{type:"optional",element:r}:{type:"repetition",element:r,min:t,max:s}},"transformElement"),A=n(e=>{switch(e.$type){case"AbnfStringLiteral":return{type:"terminal",value:e.value};case"AbnfNumVal":return{type:"terminal",value:e.value};case"AbnfRuleName":return{type:"nonterminal",name:e.name};case"AbnfGroup":return i(e.element);case"AbnfOptionalGroup":return{type:"optional",element:i(e.element)};default:throw new Error(`Unsupported ABNF primary node: ${e.$type}`)}},"transformPrimary"),P=n(e=>({name:e.name,definition:i(e.definition)}),"transformRule"),h=n(e=>{f(e,a),e.title&&a.setTitle(e.title),e.rules.map(r=>a.addRule(P(r)))},"populateDb"),R={parse:n(e=>{a.clear(),o.debug("[ABNF Parser] Starting Langium parse");const r=v.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new c(r);const t=r.value;o.debug("[ABNF Parser] Parsed rules:",t.rules.length),h(t),o.debug("[ABNF Parser] Parse complete")},"parse"),parser:{yy:a}},F={parser:R,db:a,renderer:u,styles:p};export{F as diagram};
+import{g as p,r as u,d as a}from"./chunk-SVP7TREG-DPtBhcA2.js";import{p as f}from"./chunk-JWPE2WC7-DVxbj6OP.js";import{_ as n,l as o}from"./mermaid.core-DKnSsFxv.js";import{M as c,b as d}from"./cynefin-OW5HDTMX-yFRC4RbL.js";import"./index-CwpL9TCq.js";import"./step-BEQzeS8V.js";var v=d().RailroadAbnf.parser.LangiumParser,i=n(e=>{const r=e.alternatives.map(g);return r.length===1?r[0]:{type:"choice",alternatives:r}},"transformAlternation"),g=n(e=>{const r=e.elements.map(y);return r.length===1?r[0]:{type:"sequence",elements:r}},"transformConcatenation"),b=n(e=>{if(e.includes("*")){const[t,s]=e.split("*"),l=t?parseInt(t,10):0,m=s?parseInt(s,10):1/0;return{min:l,max:m}}const r=parseInt(e,10);return{min:r,max:r}},"parseRepeat"),y=n(e=>{const r=A(e.primary);if(!e.repeat)return r;const{min:t,max:s}=b(e.repeat);return t===0&&s===1?{type:"optional",element:r}:{type:"repetition",element:r,min:t,max:s}},"transformElement"),A=n(e=>{switch(e.$type){case"AbnfStringLiteral":return{type:"terminal",value:e.value};case"AbnfNumVal":return{type:"terminal",value:e.value};case"AbnfRuleName":return{type:"nonterminal",name:e.name};case"AbnfGroup":return i(e.element);case"AbnfOptionalGroup":return{type:"optional",element:i(e.element)};default:throw new Error(`Unsupported ABNF primary node: ${e.$type}`)}},"transformPrimary"),P=n(e=>({name:e.name,definition:i(e.definition)}),"transformRule"),h=n(e=>{f(e,a),e.title&&a.setTitle(e.title),e.rules.map(r=>a.addRule(P(r)))},"populateDb"),R={parse:n(e=>{a.clear(),o.debug("[ABNF Parser] Starting Langium parse");const r=v.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new c(r);const t=r.value;o.debug("[ABNF Parser] Parsed rules:",t.rules.length),h(t),o.debug("[ABNF Parser] Parse complete")},"parse"),parser:{yy:a}},F={parser:R,db:a,renderer:u,styles:p};export{F as diagram};