@khanglvm/relay 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Vu Minh Khang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# relay
+
+**The relay between AI agents and humans — boards, blocks, and element-level comments.**
+
+`rly` lets an AI agent (Claude Code, Codex, or anything that can run a CLI) ask
+its user structured questions in a clean browser page — single/multi choice,
+yes-no, free text, rating scales — and/or present rich content blocks (markdown,
+charts, diagrams, tables, code, custom HTML), then **block until the user clicks
+Submit** and read the answers as JSON. No more "type *done* in the terminal",
+no more hand-rolled HTML + throwaway servers.
+
+Users can **hover chart points, diagram nodes, table cells, or select text to
+leave inline comments** — returned alongside answers as `result.annotations`.
+
+- Zero runtime dependencies — plain Node ≥ 18, vanilla HTML/CSS/JS UI
+- Light/dark theme (auto + manual toggle), responsive, content-focused
+- Real-time answer autosave (drafts survive timeout/cancel)
+- Auto-closes the tab after submit and unblocks the CLI
+- Native content blocks: markdown, mermaid diagrams, Chart.js charts, tables, code, sandboxed HTML
+- Chart.js and Mermaid are **vendored and lazy-loaded** only when a board uses them — the base board stays dependency-free and as fast as before
+- Element-level annotations: users comment on chart points, diagram nodes, table cells, text, or custom HTML elements; returned as `result.annotations`
+- Multiple boards at once, local history: reuse / modify / reopen / remove
+- Agent-first: JSON on stdout, logs on stderr, `--detach` + `wait` for shell tools with execution time limits, built-in agent guide & skill
+
+## Install
+
+```sh
+npm i -g @khanglvm/relay     # provides `rly` (and `relay`)
+# or per-invocation:
+npx -y @khanglvm/relay help
+```
+
+## Quick start
+
+```sh
+# Quick inline questions ("!" = required, label::type::options)
+rly ask -q "Deploy to prod?::yesno" -q "!Environment::single::dev,staging,prod"
+
+# Full board from a spec
+rly ask --file spec.json --timeout 1800
+
+# Visualization-only (prototype/idea); submit button = "Acknowledge"
+rly show --html-file prototype.html --title "Dashboard concept" --height 600
+
+# Non-blocking pattern (for agent tools with exec timeouts)
+rly ask --file spec.json --detach   # → {"boardId":"b-…","url":"http://127.0.0.1:…"}
+rly wait b-xxxxx                    # blocks until submit, prints result JSON
+```
+
+The browser opens automatically; the user answers and clicks **Submit**; the
+CLI prints something like:
+
+```json
+{
+  "status": "submitted",
+  "boardId": "b-k3x9q2",
+  "answers": { "q1": "yes", "q2": "staging" },
+  "skipped": [],
+  "comment": "ship it",
+  "annotations": [],
+  "durationMs": 23000
+}
+```
+
+## Board spec
+
+```jsonc
+{
+  "title": "Feature direction",
+  "intro": "Context shown under the title.",
+  "blocks": [
+    { "type": "markdown", "md": "## Background\nUse this context when deciding." }
+  ],
+  "allowPartial": true,        // user may submit with gaps (returned in "skipped")
+  "note": true,                // optional free-text box → result "comment"
+  "autoClose": true,           // tab closes itself after submit
+  "questions": [
+    { "id": "approach", "type": "single", "label": "Which approach?", "required": true,
+      "options": [{ "value": "a", "label": "A", "description": "fast" }, "B"], "other": true },
+    { "id": "scope",  "type": "multi",    "label": "Include?", "options": ["api", "ui", "docs"] },
+    { "id": "ship",   "type": "yesno",    "label": "Ship this week?" },
+    { "id": "name",   "type": "text",     "label": "Codename?", "placeholder": "falcon" },
+    { "id": "notes",  "type": "textarea", "label": "Constraints?" },
+    { "id": "conf",   "type": "scale",    "label": "Confidence?", "min": 1, "max": 5,
+      "minLabel": "low", "maxLabel": "high",
+      "blocks": [{ "type": "markdown", "md": "Rate your confidence in the chosen approach." }] }
+  ]
+}
+```
+
+`rly schema` prints the full JSON Schema; `rly agent` prints the complete
+agent-oriented guide (answer shapes, block reference, annotation shape, patterns).
+
+## Content blocks
+
+Blocks can appear at the board level (`"blocks": [...]` on the root) or per question
+(`"blocks": [...]` on a question object). Legacy `"html"` / `"htmlFile"` fields are
+still accepted and normalised into a single `html` block automatically.
+
+### Markdown
+
+```json
+{ "type": "markdown", "md": "## Section\nAny **CommonMark** prose." }
+```
+
+Built-in mini renderer — no library loaded.
+
+### Mermaid diagram
+
+```json
+{ "type": "mermaid", "code": "graph TD; A-->B; B-->C", "height": 400 }
+```
+
+Lazy-loads the vendored Mermaid bundle only when used. `height` clamps to
+100–2400 px (default: natural flow, max 1200 px with scroll).
+
+### Chart — shorthand
+
+```json
+{
+  "type": "chart",
+  "kind": "bar",
+  "title": "Q1 velocity",
+  "labels": ["Jan", "Feb", "Mar"],
+  "series": [
+    { "label": "Shipped", "data": [12, 19, 14], "color": "#4d8a66" },
+    { "label": "Planned", "data": [15, 15, 15] }
+  ],
+  "height": 320
+}
+```
+
+`kind`: `bar` | `line` | `pie` | `doughnut` | `radar` | `scatter`.
+Omit `color` to use the built-in palette.
+
+### Chart — full Chart.js config
+
+```json
+{
+  "type": "chart",
+  "config": {
+    "type": "bar",
+    "data": { "labels": ["A", "B"], "datasets": [{ "label": "x", "data": [1, 2] }] },
+    "options": { "plugins": { "legend": { "display": false } } }
+  },
+  "height": 280
+}
+```
+
+Pass any valid Chart.js v4 config object to `config`. Lazy-loads the vendored
+Chart.js bundle.
+
+### Table
+
+```json
+{
+  "type": "table",
+  "columns": [
+    { "key": "name", "label": "Name" },
+    { "key": "status", "label": "Status", "align": "center" },
+    { "key": "score", "label": "Score", "align": "right" }
+  ],
+  "rows": [
+    { "name": "Alpha", "status": "done", "score": 92 },
+    { "name": "Beta",  "status": "wip",  "score": 71 }
+  ],
+  "sortable": true
+}
+```
+
+`columns` may also be a plain `["A", "B", "C"]` string array, with `rows` as
+parallel arrays: `[[val, val, val], ...]`. Users can click column headers to
+sort when `"sortable": true`.
+
+### Code
+
+```json
+{ "type": "code", "lang": "js", "code": "const x = 1 + 2;" }
+```
+
+Rendered in a styled pre/code block. `lang` is optional.
+
+### HTML (sandboxed iframe)
+
+```json
+{ "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
+```
+
+or reference a file:
+
+```json
+{ "type": "html", "htmlFile": "viz.html", "height": 400 }
+```
+
+Rendered in a **sandboxed iframe** (`allow-scripts`, no parent access).
+Width: always 100% of the content column — ~820 px max on desktop, ~300 px min
+on phones. Height: 100–2400 px, default 360. Fragments (no `<html>` tag) are
+auto-wrapped to match the current theme; full documents receive a
+`?theme=light|dark` query param.
+
+## Annotations
+
+Users can leave inline comments on any annotatable element — chart data points,
+mermaid nodes, table cells, text selections inside markdown, and labelled
+elements inside custom HTML. A small pin icon appears on hover; clicking opens a
+comment popover. Comments are autosaved with the draft and returned in the final
+result.
+
+### result.annotations shape
+
+```json
+{
+  "status": "submitted",
+  "boardId": "b-k3x9q2",
+  "answers": { "approach": "a" },
+  "annotations": [
+    {
+      "id": "a1",
+      "questionId": null,
+      "blockId": "b2",
+      "target": {
+        "kind": "chart-element",
+        "datasetIndex": 0,
+        "index": 1,
+        "label": "Feb",
+        "value": 19
+      },
+      "text": "Feb spike was due to the onboarding push — not repeatable.",
+      "createdAt": "2026-06-11T10:23:00.000Z"
+    }
+  ],
+  "durationMs": 58000
+}
+```
+
+### Annotation target kinds
+
+| kind | what the user clicked |
+|---|---|
+| `chart-element` | a bar, point, or pie slice — includes `datasetIndex`, `index`, `label`, `value` |
+| `mermaid-node` | a node in a diagram — includes `nodeId`, `text` |
+| `table-cell` | a cell — includes `row` (0-based), `col` (column key), `value` |
+| `text` | a text selection inside a markdown block — includes `quote`, `prefix`, `suffix` |
+| `html-element` | a labelled element inside custom HTML (via `kit.js`) — includes `label`, optional `detail` |
+
+### kit.js — annotatable custom HTML
+
+Inside a custom HTML iframe, load `/kit.js` to make elements commentable:
+
+```html
+<script src="/kit.js"></script>
+<script>
+  // Make any element commentable — users see a hover outline + click to comment
+  relayKit.commentable(document.getElementById('revenue-chart'), 'Revenue chart', 'Q1 2026');
+  relayKit.commentable(document.getElementById('cta-button'), 'CTA button');
+</script>
+```
+
+`relayKit.commentable(el, label, detail?)` — outlines `el` on hover; clicking
+opens the annotation popover in the parent page anchored to that element.
+`label` is shown in the annotation summary; `detail` is optional extra context.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `rly ask [--file spec.json \| --file - \| -q "…"]` | Create board, open browser, block until submit, print answers JSON |
+| `rly ask … --detach` | Don't block — print `{boardId,url}` immediately |
+| `rly show --html-file viz.html` | Visualization-only board (acknowledge) |
+| `rly wait <id> [--timeout s]` | Block until board finishes, print result |
+| `rly result <id>` | Result/status now — includes **live autosaved draft** while open |
+| `rly list [--json]` | Running boards |
+| `rly open [id]` | Re-open the browser tab of a running board |
+| `rly reopen <id>` | Serve a saved board again, **prefilled with saved answers** |
+| `rly reuse <id> [--dump]` | Re-run a past board as a new one (blank) |
+| `rly stop <id> \| --all` | Stop running board(s) — draft preserved |
+| `rly history [--limit n] [--json]` | Saved boards |
+| `rly spec <id>` | Print a saved spec (edit → `rly ask --file`) |
+| `rly rm <id> \| --all` | Delete saved board(s) |
+| `rly schema` | JSON Schema of the spec |
+| `rly agent` | Full guide for AI agents |
+| `rly skill [install\|path]` | Bundled universal agent skill |
+
+Common flags: `--title --intro --html-file --height --submit-label
+--timeout <sec> --port <n> --no-open --detach`.
+
+Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
+`4` usage · `5` not found.
+
+Storage: `~/.relay` (override with `RLY_HOME`). Boards bind to `127.0.0.1` only.
+
+## Agent skill (Claude Code, Codex, …)
+
+A universal [SKILL.md](skills/relay/SKILL.md) is bundled:
+
+```sh
+rly skill install                  # auto-installs into ~/.claude/skills and ~/.codex/skills
+rly skill install --target claude  # or codex | both | <custom dir>
+npx skills add khanglvm/relay      # via the skills installer, straight from this repo
+```
+
+`rly help` and `rly agent` also point agents at the skill, so an agent that
+merely has the CLI installed can discover and self-install it.
+
+## Development
+
+```sh
+npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
+```
+
+## Migration from quest-board
+
+relay was formerly published as `@khanglvm/quest-board` (CLI: `qbd`). That
+package is deprecated; install `@khanglvm/relay` instead.
+
+- Storage moved from `~/.quest-board` to `~/.relay`. Override with `RLY_HOME`.
+  There is no automatic migration — copy boards manually if needed.
+- The old `QUEST_BOARD_HOME` env var is still read as a fallback during the
+  transition period.
+- Legacy `"html"` / `"htmlFile"` / `"htmlHeight"` fields in specs continue to
+  work and are silently normalised into an html block.
+
+## License
+
+[MIT](LICENSE) © Le Vu Minh Khang

package/bin/rly.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+const code = await main(process.argv.slice(2));
+process.exitCode = code ?? 0;
+// Safety net: if some handle lingers after the work is done (e.g. a browser
+// keep-alive socket that survived server.close), force the exit. unref'd, so
+// a clean run exits naturally before this fires.
+setTimeout(() => process.exit(process.exitCode ?? 0), 3000).unref();

package/docs/AGENT.md

@@ -0,0 +1,317 @@
+# relay (`rly`) — agent guide
+
+Purpose: ask the human structured questions in a browser tab and/or show them
+rich content blocks (markdown, charts, diagrams, tables, code, custom HTML),
+then **wait for them to click Submit** and read the answers as JSON from stdout.
+No "type 'done' in the terminal", no hand-rolled HTML+server.
+
+**Tell the user** at the start of your intro text that they can hover chart
+points, diagram nodes, and table cells to leave comments, and select text in
+markdown blocks to annotate — their comments come back in `result.annotations`
+alongside their answers. Treat annotations as first-class feedback.
+
+Everything machine-relevant is on **stdout as JSON**; human-facing logs go to
+stderr. Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
+`4` usage error · `5` not found.
+
+## Two execution patterns
+
+**1. Blocking (simplest).** The command blocks until the user submits, then
+prints the result JSON:
+
+```sh
+rly ask --file spec.json --timeout 1800
+```
+
+**2. Detached (recommended when your shell tool has an execution time limit).**
+Returns immediately with the board URL; collect later:
+
+```sh
+rly ask --file spec.json --detach     # → {"status":"open","boardId":"b-…","url":"…"}
+rly wait b-xxxxx --timeout 3500       # blocks until submit, prints result JSON
+rly result b-xxxxx                    # non-blocking peek; while open it includes
+                                      # the live autosaved draft of the user's answers
+```
+
+Answers **autosave in real time** as the user fills the board — a page reload
+restores them, and a draft survives timeouts/cancellation (included in those
+results), so partial input is never lost.
+
+## Creating boards
+
+From a JSON spec file (`--file spec.json`), stdin (`--file -`), or quick
+inline questions:
+
+```sh
+rly ask -q "Deploy to prod now?::yesno" -q "!Environment::single::dev,staging,prod"
+#         label::type::comma,separated,options          leading "!" = required
+```
+
+Visualization-only (no questions; submit button reads "Acknowledge"):
+
+```sh
+rly show --html-file prototype.html --title "Dashboard concept" --height 600
+```
+
+## Board spec (JSON)
+
+```jsonc
+{
+  "title": "Feature direction",
+  "intro": "Pick what we build next. Lines are preserved.",
+  "blocks": [
+    { "type": "markdown", "md": "## Background\nContext here." }
+  ],
+  "allowPartial": true,             // default true: user may submit with gaps -> "skipped"
+  "note": true,                     // default true: optional free-text box -> result "comment"
+  "autoClose": true,                // default true: tab tries to close itself after submit
+  "submitLabel": "Submit",
+  "questions": [
+    { "id": "approach", "type": "single", "label": "Which approach?", "required": true,
+      "options": [
+        { "value": "a", "label": "Approach A", "description": "fast, less flexible" },
+        "Approach B"                                    // plain strings work too
+      ],
+      "other": true },                                  // adds a free-text "Other" option
+    { "id": "scope", "type": "multi", "label": "Include which parts?", "options": ["api", "ui", "docs"],
+      "note": true },                                   // optional free-text under the question
+                                                        //   → returned as result.notes.scope
+    { "id": "ship", "type": "yesno", "label": "Ship this week?" },
+    { "id": "name", "type": "text", "label": "Project codename?", "placeholder": "e.g. falcon" },
+    { "id": "notes", "type": "textarea", "label": "Any constraints?" },
+    { "id": "confidence", "type": "scale", "label": "Confidence?", "min": 1, "max": 5,
+      "minLabel": "low", "maxLabel": "high" },
+    { "id": "layout", "type": "single", "label": "Which layout?", "options": ["left", "right"],
+      "blocks": [{ "type": "markdown", "md": "Compare the two options above." }] }
+  ]
+}
+```
+
+`rly schema` prints the full JSON Schema.
+
+### Question types → answer shapes
+
+| type       | answer value in result              |
+|------------|-------------------------------------|
+| `single`   | `"value"` (Other → its text verbatim) |
+| `multi`    | `["a","b"]` (Other text appended)   |
+| `yesno`    | `"yes"` \| `"no"`                   |
+| `text`     | `"string"`                          |
+| `textarea` | `"string"`                          |
+| `scale`    | number (`min`…`max`, default 1–5)   |
+
+Aliases accepted: radio/choice/select→single, checkbox→multi,
+boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scale.
+
+### Result JSON (stdout)
+
+```json
+{
+  "status": "submitted",
+  "boardId": "b-xxxxx",
+  "answers": { "approach": "a", "scope": ["api", "ui"], "ship": "yes", "confidence": 4 },
+  "skipped": ["name"],
+  "comment": "free-text note from the user",
+  "notes": { "scope": "docs can wait until the API settles" },
+  "annotations": [
+    {
+      "id": "a1",
+      "questionId": null,
+      "blockId": "b2",
+      "target": { "kind": "chart-element", "datasetIndex": 0, "index": 1, "label": "Feb", "value": 19 },
+      "text": "Feb spike was from the onboarding push — not repeatable.",
+      "createdAt": "2026-06-11T10:23:00.000Z"
+    }
+  ],
+  "finishedAt": "2026-06-11T03:00:00.000Z",
+  "durationMs": 42000
+}
+```
+
+Unanswered questions are absent from `answers` and listed in `skipped`.
+Questions with `"note": true` show a small optional free-text field; non-empty
+notes come back in `notes` keyed by question id. On `timeout`/`cancelled`, a
+`draft` field carries the autosaved partial answers and any annotations written
+so far.
+
+## Blocks
+
+Blocks can appear at the board level (`"blocks": [...]` on the root object) or
+per question (`"blocks": [...]` on a question object). Heights clamp to
+100–2400 px.
+
+### All block shapes
+
+```jsonc
+// Markdown — built-in mini renderer, no library
+{ "type": "markdown", "md": "## Heading\nAny **CommonMark** prose." }
+
+// Mermaid diagram — vendored, lazy-loaded; natural height, max 1200 px + scroll
+{ "type": "mermaid", "code": "graph TD; A-->B; B-->C", "height": 400 }
+
+// Chart — shorthand (lazy-loads vendored Chart.js; default height 320)
+{
+  "type": "chart",
+  "kind": "bar",             // bar | line | pie | doughnut | radar | scatter
+  "title": "Velocity",
+  "labels": ["Jan", "Feb", "Mar"],
+  "series": [
+    { "label": "Shipped", "data": [12, 19, 14], "color": "#4d8a66" },
+    { "label": "Planned", "data": [15, 15, 15] }
+  ],
+  "height": 320
+}
+
+// Chart — full Chart.js v4 config
+{
+  "type": "chart",
+  "config": {
+    "type": "bar",
+    "data": { "labels": ["A", "B"], "datasets": [{ "label": "x", "data": [1, 2] }] },
+    "options": { "plugins": { "legend": { "display": false } } }
+  },
+  "height": 280
+}
+
+// Table — sortable, annotatable cells
+{
+  "type": "table",
+  "columns": [
+    { "key": "name", "label": "Name" },
+    { "key": "status", "label": "Status", "align": "center" },
+    { "key": "score",  "label": "Score",  "align": "right" }
+  ],
+  "rows": [
+    { "name": "Alpha", "status": "done", "score": 92 },
+    { "name": "Beta",  "status": "wip",  "score": 71 }
+  ],
+  "sortable": true
+}
+// columns may also be plain string array; rows may be parallel arrays [[val,val],...]
+
+// Code — styled pre/code block
+{ "type": "code", "lang": "js", "code": "const x = 1 + 2;" }
+
+// HTML — sandboxed iframe; default height 360
+{ "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
+{ "type": "html", "htmlFile": "viz.html",   "height": 400 }
+```
+
+### When to use which block
+
+| Block | Best for |
+|---|---|
+| `mermaid` | flows, state machines, architecture overviews, sequence diagrams |
+| `chart` | numbers, trends, comparisons, metrics |
+| `table` | structured comparisons, option matrices, data grids |
+| `markdown` | prose context, background, instructions, section headings |
+| `code` | code snippets, config examples, command output |
+| `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
+
+### Height rules
+
+- `markdown`, `code`: natural flow (no fixed height).
+- `mermaid`: natural flow, max-height 1200 px with internal scroll. Override with `"height"`.
+- `chart`: default 320 px. Override with `"height"`.
+- `html`: default 360 px. Override with `"height"`.
+- `table`: natural flow.
+- All heights clamp to 100–2400 px.
+
+## Custom HTML sizing contract
+
+- Rendered in a **sandboxed iframe** (`allow-scripts allow-forms allow-popups
+  allow-modals`, **no** same-origin/parent access). Ship a self-contained HTML
+  document: inline your CSS/JS; external CDN resources do load, but offline-safe
+  inline is better.
+- **Width: always 100% of the content column — up to ~820 px on desktop, as
+  narrow as ~300 px on phones. Design responsively; don't assume fixed width.**
+- **Height: fixed per block via `height` (px, 100–2400). Default 360.**
+  Content taller than that scrolls inside the iframe.
+- **Fragments** (no `<html>` tag) are auto-wrapped in a minimal document whose
+  background/text match the user's current theme. **Full documents** are served
+  verbatim and receive a `?theme=light|dark` query param on theme toggle.
+
+### kit.js — make iframe elements annotatable
+
+Load `/kit.js` inside your custom HTML iframe to let users comment on specific
+elements:
+
+```html
+<script src="/kit.js"></script>
+<script>
+  relayKit.commentable(document.getElementById('chart'), 'Revenue chart', 'Q1 2026');
+  relayKit.commentable(document.getElementById('hero-cta'), 'CTA button');
+</script>
+```
+
+`relayKit.commentable(el, label, detail?)` — outlines `el` on hover; a click
+opens the annotation popover in the parent page anchored to the element.
+Annotations come back in `result.annotations` with `target.kind = "html-element"`,
+`target.label`, and (if provided) `target.detail`.
+
+## Annotations
+
+Users can comment on any annotatable element. Tell them about it in your board
+intro. Annotations are autosaved with the draft and returned in the final result.
+
+### result.annotations shape
+
+```json
+"annotations": [
+  {
+    "id": "a1",
+    "questionId": "q-id or null for board-level",
+    "blockId": "b2",
+    "target": { ... },
+    "text": "user comment text",
+    "createdAt": "2026-06-11T10:23:00.000Z"
+  }
+]
+```
+
+### All 5 target kinds
+
+| kind | Fields | Triggered by |
+|---|---|---|
+| `chart-element` | `datasetIndex`, `index`, `label`, `value` | clicking a bar, point, or pie slice |
+| `mermaid-node` | `nodeId`, `text` | clicking a diagram node |
+| `table-cell` | `row` (0-based), `col` (column key), `value` | clicking a table cell |
+| `text` | `quote`, `prefix` (≤30 chars before), `suffix` (≤30 after) | selecting text in a markdown block |
+| `html-element` | `label`, `detail?` | clicking a `relayKit.commentable()` element |
+
+Read annotations as first-class feedback — they often carry the sharpest insight
+(e.g. a user circling the one data point that concerns them, or quoting the exact
+sentence they disagree with).
+
+## Managing boards
+
+```sh
+rly list [--json]        # running boards (id, url, pid)
+rly open [id]            # re-open the browser tab of a running board
+rly reopen <id>          # serve a SAVED board again, prefilled with its saved
+                         #   answers/draft; user can edit and resubmit
+rly reuse <id>           # re-run a past board as a NEW board (blank answers)
+rly spec <id>            # print a saved spec — edit it, then `rly ask --file`
+rly history [--json]     # saved boards with statuses
+rly stop <id> | --all    # stop running board(s) → status "cancelled", draft kept
+rly rm <id> | --all      # delete saved board(s)
+```
+
+Multiple boards can run at once (each gets its own port on 127.0.0.1).
+Storage lives in `~/.relay` (override with `RLY_HOME`).
+
+## Tips for agents
+
+- Prefer `--detach` + `rly wait` if your shell tool kills long commands.
+- Don't pass `--no-open` for real users — the browser tab opening *is* the
+  notification. Use it only in tests.
+- Quote JSON carefully; prefer writing a spec file or piping via `--file -`.
+- Use stable `id`s on questions so your follow-up logic reads clean keys.
+- `rly result <id>` while a board is open returns the live draft — useful to
+  check whether the user has started answering.
+- In the board `intro`, tell users they can hover chart points / select text to
+  leave inline comments — they won't discover it otherwise.
+- Check `result.annotations` before generating your next output; a comment on a
+  specific data point or a quoted sentence often overrides the checkbox answer.
+- Bundled universal skill (Claude Code, Codex, any SKILL.md-aware agent):
+  `rly skill install` — or `npx skills add khanglvm/relay`.