agent-whiteboard 1.1.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,52 @@
+## 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`).
+
+- **`quiz` render type (F44, F45):** `render({ type: "quiz", ... })` takes a JSON payload of single- and multiple-choice questions, validated by the new `server/quiz.ts` (unique ids, option counts, weight sums). Mode is derived from the answer key: every question keyed → inline, none → deferred, a mix is rejected. Valid in `render()` only, not in slideshows or step-frames.
+- **Scoring (F47):** per question `all_or_nothing` (exact correct set) or `partial` (multiple-choice only; weighted correct options summing to 1, wrong picks earn nothing), with optional `points`.
+- **Quiz renderer + inline evaluation (F44, F46):** new `Quiz.svelte` with radio/checkbox controls and an in-quiz Submit, disabled until every question is answered. Inline quizzes show per-question results and the total score after Submit.
+- **Deferred evaluation (F48, F49):** Submit posts to the new `POST /quiz/submit`; the new `wait_quiz` MCP tool / `POST /wait-quiz` long-poll returns the questions and answers (plus the client-computed score for inline quizzes). 10-minute timeout, submit-before-wait retention, and superseding like `wait_click`.
+- **History & export (F50):** quizzes are snapshotted as questions only and reload fresh; HTML export replaces a quiz with an explanatory note and never leaks its questions or answer key.
+- **Dev/tooling:** `/quiz` added to the Vite dev proxy; README documents the quiz format, `wait_quiz` and the new endpoints; showcase Section 15 (`-q`) demonstrates inline and deferred quizzes.
+- Full suite: 745 unit tests passing; `tsc`/`svelte-check`/`eslint`/`npm run build` clean.
+
+## 1.1.1 — 2026-11-06
+
+**Milestone v1.7 — Unified Import/Export Button (Sprints 87–88) complete.** Pure UI consolidation; no server, API, MCP or snapshot-format changes.
+
+- **Showcase page (F43):** `mockup/import-export-button-options.html` presented icon/tooltip/menu-label candidates; chosen: opposing-arrows icon, "Import / export" tooltip, "Export…" / "Import…" labels.
+- **Single toolbar button (F41):** the separate Export and Import buttons are replaced by one `ImportExportMenu.svelte` button opening a popover with "Export…" (existing export modal) and "Import…" (existing `ImportModal`). Delete and drag-and-drop `.zip` import are unchanged.
+- **ARIA menu behaviour (F42):** `aria-haspopup`/`aria-expanded`, `role="menuitem"`, arrow/Escape handling, focus return to the button, outside-click and Tab dismissal.
+- **Tests (NF56):** new `ImportExportMenu` unit tests plus updated `App` tests.
+
 ## 1.1.0 — 2026-09-07
 
 **Milestone v1.6 — Workspace Export/Import for Sharing (Sprints 85–86) complete.** Adds a full workspace sharing round-trip: export a workspace as a portable `.zip` and import it into another whiteboard instance (FR31 in `01`, F34–F40/NF55 in `03`). The first milestone to ship real new user-facing functionality since 1.0 — correctly a minor bump per the versioning rule in `05`.

package/README.md

@@ -8,7 +8,7 @@ The original goal was simple: instead of explaining everything through long text
 
 As the project evolved, it became clear that the same interaction model is useful far beyond education. Whether an agent is explaining a software architecture, walking through a network protocol, debugging a problem, presenting data, or documenting a system, the ability to communicate visually is just as valuable. Agent Whiteboard is therefore intentionally domain-agnostic.
 
-Through a set of MCP tools, an AI agent can render Mermaid diagrams, SVG, HTML, LaTeX, and Vega-Lite charts, build incremental multi-step explanations, pause until the user is ready to continue, react to clicks on diagrams, and keep a persistent history of snapshots that can later be reloaded or exported.
+Through a set of MCP tools, an AI agent can render Mermaid diagrams, SVG, HTML, LaTeX, Vega-Lite charts, and interactive quizzes, build incremental multi-step explanations, pause until the user is ready to continue, react to clicks on diagrams, and keep a persistent history of snapshots that can later be reloaded or exported.
 
 Unlike collaborative whiteboard applications, Agent Whiteboard is not a canvas that humans edit directly. The whiteboard is controlled by the AI agent, making it a lightweight visual communication surface between the agent and its user. Everything runs locally and integrates naturally with Claude Code through MCP.
 
@@ -18,18 +18,20 @@ 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
 
 ```
 [Claude Code agent]
     │
-    └── 13 MCP tools — render, step-frames builder, slideshow, wait_click/wait_done, snapshot export (see below)
+    └── 15 MCP tools — render, step-frames builder, slideshow, wait_click/wait_done/wait_quiz, snapshot export (see below)
            │
            ▼
     [Node.js server :3000]  — MCP over SSE + REST fallback + WebSocket
            │
            ▼
-    [Browser tab :5173]  — Svelte SPA, auto-opens on start, with a History panel for browsing/deleting/exporting past snapshots
+    [Browser tab :5173]  — Svelte SPA, auto-opens on start, with a History panel for browsing/deleting/exporting/importing past snapshots
 ```
 
 The server exposes MCP tools over SSE at `http://localhost:3000/mcp`. Claude Code connects automatically when `.mcp.json` is present in the project root.
@@ -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,13 +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). |
+| `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).
 
@@ -161,6 +224,32 @@ Block until the user clicks the **Done** button in the browser tab, then return.
 
 <img src="docs/screenshots/done-button.png" width="700" alt="Done button visible in the controls panel while wait_done() is armed">
 
+### `wait_quiz()`
+
+Block until the user clicks **Submit** on the quiz currently on screen (rendered with `render({ type: "quiz", ... })`), then return the questions and the user's answers. A submission made before you call `wait_quiz()` is kept and returned immediately, as long as that quiz is still on screen. Times out after 10 minutes; a second `wait_quiz()` supersedes a pending one.
+
+**Returns:** `{ "ok": true, "type": "submitted", "questions": {...}, "answers": [{ "questionId": "q1", "selected": ["a"] }] }` — plus `"score": { "earned", "possible" }` for an inline quiz. Also `{ "ok": true, "type": "timeout" | "superseded" }`, or `{ "ok": false, "error": "..." }` if no quiz is on the canvas.
+
+### Quizzes
+
+A quiz is a JSON payload of single- or multiple-choice questions:
+
+```json
+{ "title": "Check-in",
+  "questions": [
+    { "id": "q1", "text": "Which verb is idempotent?", "kind": "single",
+      "options": [{ "id": "a", "text": "PUT", "correct": true }, { "id": "b", "text": "POST" }] },
+    { "id": "q2", "text": "Pick the primes", "kind": "multiple", "scoring": "partial", "points": 2,
+      "options": [{ "id": "a", "text": "2", "correct": true, "weight": 0.5 }, { "id": "b", "text": "3", "correct": true, "weight": 0.5 }, { "id": "c", "text": "4" }] }
+  ] }
+```
+
+- **Inline evaluation** — mark `correct: true` on the right option(s) of *every* question. The browser scores the quiz when the user clicks Submit and shows per-question results plus the total (the answer key is visible to anyone inspecting the page, so use deferred mode for anything you don't want revealed).
+- **Deferred evaluation** — mark none. Submit sends the answers to the agent, which receives them via `wait_quiz()` and evaluates them itself.
+- A payload where only some questions have a key is rejected.
+- **Scoring** (per question): `"all_or_nothing"` (default) earns `points` (default 1) only for the exact correct set. `"partial"` (multiple-choice only) gives every correct option a `weight`; the weights must sum to 1, the score is the sum of the weights of the correct options selected, and wrong picks earn nothing.
+- Quizzes are saved to history (questions only — answers and scores are never persisted) and reload as a fresh quiz. They are not included in HTML exports.
+
 ### `wait_click([node_actions])`
 
 Arm the browser for a single node or edge click on the current Mermaid diagram. Nodes are highlighted with a blue outline and pointer cursor. Applies reliably to `graph`/`flowchart` diagrams; other types are best-effort.
@@ -224,28 +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"> |
+
+## Environment variables
+
+| 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
 
@@ -262,6 +356,8 @@ All tools have HTTP equivalents for scripting or testing without an MCP client:
 | `POST /seek` | `{ "frame": N }` |
 | `POST /user-done` | — (simulates the Done button click) |
 | `POST /wait-done` | — (long-polls until Done is signalled) |
+| `POST /quiz/submit` | `{ "answers": [{ "questionId": "...", "selected": ["optionId", ...] }], "score": { "earned": N, "possible": N } (optional, inline quizzes only) }` (sent by browser) — 400 if no quiz is on screen or the answers don't match it |
+| `POST /wait-quiz` | — (long-polls until the quiz is submitted; REST twin of `wait_quiz`) |
 | `POST /node-click` | `{ "type": "node"\|"edge", "id": "...", "label": "..." }` (sent by browser) |
 | `POST /wait-click` | `{ "node_actions": { "<id>": ["action1", ...] } }` (optional; long-polls until a node/edge click is signalled) |
 | `POST /step-frames/init` | `{ "frame_type": "...", "workspace": "...", "title": "..." }` — starts an incremental builder, returns `{ "ok": true, "id": "<uuid>" }` |
@@ -273,20 +369,29 @@ All tools have HTTP equivalents for scripting or testing without an MCP client:
 | `POST /snapshots/delete-files` | `{ "workspace": "...", "filenames": ["..._screen.json", ...] }` — deletes specific snapshot files |
 | `POST /snapshots/delete-workspace` | `{ "workspace": "..." }` — deletes an entire workspace's snapshot folder |
 | `POST /export-html` | `{ "items": [{ "workspace": "...", "id": "..." }, ...], "mode": "cdn" \| "offline" }` (`mode` optional, defaults to `"cdn"`) — returns the assembled HTML file as a download, not JSON |
+| `POST /export-zip` | `{ "items": [{ "workspace": "...", "id": "..." }, ...] }` — returns a portable `.zip` (the selected snapshots' raw JSON plus a `manifest.json`) as a download, for sharing a workspace |
+| `POST /import` | multipart form: `file` (a `.zip` from `/export-zip`), `mode` (`"create"` \| `"merge"`, default `"create"`), `targetWorkspace` — imports snapshots, deduplicating by snapshot `id`/`timestamp`; 50MB cap |
 
 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 delete and export icon buttons that open a 2-step modal (`client/src/DeleteExportModal.svelte`) for deleting or exporting an entire workspace or a chosen subset of snapshots. Destructive actions require a second confirming click. Exports are produced by the `export_html()` tool / `POST /export-html` endpoint described above.
+Running from source (contributing, or testing an unreleased change) instead of `npx agent-whiteboard`:
 
-| 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"> |
+```bash
+npm install
+npm run dev
+```
 
-| 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"> |
+This starts the Node server (`:3000`), the Vite dev server (`:5173`), and opens the browser tab automatically.
+
+## 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
 
@@ -295,6 +400,7 @@ Exercises every renderer and interactive feature (requires `npm run dev` running
 ```bash
 node tests/human_driven/showcase.js        # Sections 1–8: renderer slideshow + seek
 node tests/human_driven/showcase.js -x    # Section 12: export-by-id (v0.11)
+node tests/human_driven/showcase.js -q    # Section 15: quiz, inline + deferred (v1.8)
 node tests/human_driven/showcase.js -a    # All sections
 ```
 
@@ -306,6 +412,9 @@ Section flags (combinable):
 -u, --popup           Section 10: node_actions popup menu
 -e, --edge            Section 11: edge click demo
 -x, --exportid        Section 12: export by graph ID (v0.11)
+-c, --incremental     Section 13: incremental step-frames creation (init/append/commit)
+-n, --nodetoframe     Section 14: node_to_frame autonomous navigation
+-q, --quiz            Section 15: quiz — inline scoring + deferred wait_quiz (v1.8)
 -a, --all             All sections
 -p, --port <port>     Server port (default: 3000)
 -d, --delay <ms>      Delay between slides (default: 5000)
@@ -313,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-CcuBIZ5h.js → abnfDiagram-VCTEODGH-Bwh5lUgu.js}

@@ -1 +1 @@
-import{g as p,r as u,d as a}from"./chunk-SVP7TREG-COihS1MQ.js";import{p as f}from"./chunk-JWPE2WC7-C8Aj4MVR.js";import{_ as n,l as o}from"./mermaid.core-DioArgDk.js";import{M as c,b as d}from"./cynefin-OW5HDTMX-CMVAR4fd.js";import"./index-CFelVSRu.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};