npm - @khanglvm/relay - Versions diffs - 0.2.0 → 0.4.0 - Mend

@khanglvm/relay 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md +83 -5
package/docs/AGENT.md +117 -4
package/docs/assets/annotations.png +0 -0
package/docs/assets/board-dark.png +0 -0
package/docs/assets/board-light.png +0 -0
package/docs/assets/demo.gif +0 -0
package/docs/assets/mobile.png +0 -0
package/package.json +1 -1
package/skills/relay/SKILL.md +79 -24
package/skills/relay/examples/blocks-showcase.json +9 -0
package/skills/relay/examples/diagram-coedit.json +15 -0
package/src/cli.js +287 -15
package/src/server.js +148 -11
package/src/spec.js +37 -4
package/src/ui/annotate.css +57 -5
package/src/ui/annotate.js +130 -5
package/src/ui/app.js +117 -2
package/src/ui/blocks.css +97 -0
package/src/ui/blocks.js +281 -19
package/src/ui/style.css +9 -0
package/vendor/VERSIONS.json +2 -1
package/vendor/viz-standalone.js +9 -0

package/README.md CHANGED Viewed

@@ -5,23 +5,38 @@
 `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
+charts, diagrams, tables, code, sandboxed HTML, Graphviz and PlantUML diagrams), 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`.
+Agents can reply to those comments and reopen the board as a conversation thread.
 - 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
+- Native content blocks: markdown, mermaid diagrams, Graphviz diagrams, PlantUML, Chart.js charts, tables, code, sandboxed HTML
+- Chart.js, Mermaid, and Graphviz 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`
+- **Threaded annotation replies**: agents can reply to user comments via `rly reopen --replies`; conversations shown inline in the board
+- **Live board mutation**: `rly update` lets an agent push a new spec to an already-open board; the page reloads and prefills answers from draft
 - 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
+## See it
+| Light theme | Dark theme |
+|---|---|
+| ![relay board light theme](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/board-light.png) | ![relay board dark theme](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/board-dark.png) |
+| Annotation popover | Mobile |
+|---|---|
+| ![Annotation comment on a chart bar](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/annotations.png) | ![Mobile view at 375px](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/mobile.png) |
+![relay demo — board to annotation to summary](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/demo.gif)
 ## Install
 ```sh
@@ -198,14 +213,55 @@ 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.
+### Graphviz diagram
+```json
+{ "type": "graphviz", "dot": "digraph { a -> b -> c }", "height": 300 }
+```
+Rendered entirely **offline** via the vendored `viz-standalone.js` (Graphviz compiled to
+WebAssembly). Never upscaled past the diagram's natural width; shrinks on narrow screens;
+container max-height 1200 px with scroll. Nodes (`g.node`) and edges (`g.edge`) are
+individually annotatable. Use Graphviz for precise dependency graphs, call graphs, or
+state machines where Mermaid's auto-layout doesn't give enough control.
+### PlantUML diagram
+```json
+{ "type": "plantuml", "code": "@startuml\nA -> B: request\n@enduml", "height": 340 }
+```
+Rendered via a **PlantUML server** (default: `https://www.plantuml.com/plantuml`). The
+diagram source is deflate-encoded client-side and sent as a URL parameter — no server
+round-trip for the page itself, just an `<img>` request. If the server is unreachable or
+the browser lacks `CompressionStream`, a muted error card is shown.
+**Privacy note:** diagram source is encoded and sent to the configured PlantUML server.
+For sensitive diagrams, host your own server and pass `"server": "https://plantuml.example.com"`.
+The rendered image is registered as a single annotatable element (target kind `image`).
+Use PlantUML for UML sequence diagrams, class diagrams, and component diagrams.
 ## Annotations
 Users can leave inline comments on any annotatable element — chart data points,
-mermaid nodes, table cells, text selections inside markdown, and labelled
+mermaid nodes, graphviz nodes and edges, 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.
+**Threaded replies:** each annotation can have replies. Agents can read
+`result.annotations`, compose replies, and reopen the board as a conversation:
+```sh
+# After reading result.annotations from a previous board:
+rly reopen <id> --replies replies.json
+# replies.json: [{"annotationId":"a1","text":"Good catch — fixed in the next sprint."}]
+```
+The board reopens with agent replies shown inline under each comment. Users can reply
+back; the conversation grows with each `rly reopen --replies` cycle.
 ### result.annotations shape
 ```json
@@ -226,22 +282,31 @@ result.
         "value": 19
       },
       "text": "Feb spike was due to the onboarding push — not repeatable.",
-      "createdAt": "2026-06-11T10:23:00.000Z"
+      "author": "user",
+      "createdAt": "2026-06-11T10:23:00.000Z",
+      "replies": [
+        { "author": "agent", "text": "Confirmed — excluded from the trend line.", "createdAt": "2026-06-11T11:00:00.000Z" }
+      ]
     }
   ],
   "durationMs": 58000
 }
 ```
+Each annotation has an optional `author` (`"user"` | `"agent"`, default `"user"`) and
+an optional `replies` array (capped at 50; each reply: `{author, text, createdAt}`).
 ### 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` |
+| `graphviz-node` | a node or edge in a Graphviz 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` |
+| `image` | a PlantUML diagram image — includes `label` |
 ### kit.js — annotatable custom HTML
@@ -272,6 +337,8 @@ opens the annotation popover in the parent page anchored to that element.
 | `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 reopen <id> --replies file.json` | Reopen with agent replies appended to matching annotations |
+| `rly update <id> [--file spec.json \| --title T \| --intro I \| -q "…"]` | Push a new spec to a running board — page reloads, answers survive via draft |
 | `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 |
@@ -289,6 +356,17 @@ Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
 Storage: `~/.relay` (override with `RLY_HOME`). Boards bind to `127.0.0.1` only.
+## Presence, push-wake & diagram co-editing (v0.4)
+While a board is open the page reports user activity; `rly result <id>`
+includes `presence` ({visible, focused, secondsSinceActivity}) and
+`rly wait <id> --while-active --idle-grace 180` keeps waiting while the user
+is demonstrably engaged instead of dying on a fixed timer. For pushes,
+`--on-result '<cmd>'` (on ask/show/reopen/reuse) and `rly wait --notify-cmd`
+execute your command with the result JSON on stdin the moment the board
+finishes. Mermaid blocks with `"editable": true` let the user edit the diagram
+source with live preview — their version returns as `result.blockEdits`.
 ## Agent skill (Claude Code, Codex, …)
 A universal [SKILL.md](skills/relay/SKILL.md) is bundled:

package/docs/AGENT.md CHANGED Viewed

@@ -149,6 +149,16 @@ per question (`"blocks": [...]` on a question object). Heights clamp to
 // Mermaid diagram — vendored, lazy-loaded; natural height, max 1200 px + scroll
 { "type": "mermaid", "code": "graph TD; A-->B; B-->C", "height": 400 }
+// Graphviz diagram — vendored viz-standalone.js (Graphviz-WASM), fully offline
+// Nodes (g.node) and edges (g.edge) are individually annotatable
+{ "type": "graphviz", "dot": "digraph { a -> b -> c }", "height": 300 }
+// PlantUML diagram — rendered via a PlantUML server (default: plantuml.com)
+// Source is deflate-encoded client-side; only an img URL is sent to the server.
+// Use "server" for a self-hosted instance to avoid leaking sensitive diagrams.
+{ "type": "plantuml", "code": "@startuml\nA -> B: request\n@enduml", "height": 340 }
+{ "type": "plantuml", "code": "...", "server": "https://plantuml.example.com", "height": 300 }
 // Chart — shorthand (lazy-loads vendored Chart.js; default height 320)
 {
   "type": "chart",
@@ -202,6 +212,8 @@ per question (`"blocks": [...]` on a question object). Heights clamp to
 | Block | Best for |
 |---|---|
 | `mermaid` | flows, state machines, architecture overviews, sequence diagrams |
+| `graphviz` | precise dependency graphs, call graphs, state machines when Mermaid's auto-layout falls short; individually annotatable nodes and edges |
+| `plantuml` | UML diagrams (sequence, class, component) via server rendering; great for detailed interface contracts |
 | `chart` | numbers, trends, comparisons, metrics |
 | `table` | structured comparisons, option matrices, data grids |
 | `markdown` | prose context, background, instructions, section headings |
@@ -262,27 +274,100 @@ intro. Annotations are autosaved with the draft and returned in the final result
     "id": "a1",
     "questionId": "q-id or null for board-level",
     "blockId": "b2",
-    "target": { ... },
-    "text": "user comment text",
-    "createdAt": "2026-06-11T10:23:00.000Z"
+    "target": { "kind": "chart-element", "datasetIndex": 0, "index": 1, "label": "Feb", "value": 19 },
+    "text": "Feb spike was from the onboarding push — not repeatable.",
+    "author": "user",
+    "createdAt": "2026-06-11T10:23:00.000Z",
+    "replies": [
+      { "author": "agent", "text": "Confirmed — excluded from the trend line.", "createdAt": "2026-06-11T11:00:00.000Z" }
+    ]
   }
 ]
 ```
-### All 5 target kinds
+`author` is `"user"` (default, when absent) or `"agent"`. `replies` is an array of
+`{author, text, createdAt}` objects, capped at 50 per annotation.
+### All 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 |
+| `graphviz-node` | `nodeId`, `text` | clicking a Graphviz node or edge |
 | `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 |
+| `image` | `label` | clicking the PlantUML diagram image |
 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).
+### Threaded replies — `rly reopen --replies`
+After reading `result.annotations`, an agent can reply to specific comments and
+reopen the board as a conversation:
+```sh
+rly reopen <id> --replies replies.json
+```
+`replies.json` is an array of `{"annotationId": "a1", "text": "..."}` objects.
+The server seeds the draft from the saved result, appends each reply with
+`author: "agent"` and `createdAt: now`, then serves the board prefilled. Unknown
+annotation IDs cause a `CliError` (exit 4) listing valid IDs.
+The UI shows agent and user replies as a thread under each comment — agent replies
+use an accent chip, user replies use a muted chip.
+## Presence — is the user still there?
+While a board is open, the page reports activity (visibility, focus, idle
+time). Use it instead of guessing timeouts:
+```sh
+rly result b-xxxxx     # open board → includes "presence":
+                       #   {open, seen, visible, focused, secondsSinceActivity, secondsSincePing}
+rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+```
+`--while-active` keeps extending the wait as long as the user is demonstrably
+active (page visible/focused and interaction within `--idle-grace` seconds,
+default 180); once they go idle it returns the normal `wait-timeout` JSON,
+with `presence` attached so you can decide what to do next. Prefer this over
+raising `--timeout`.
+## Push-wake — get notified instead of polling
+```sh
+rly ask --file spec.json --detach --on-result 'curl -s -X POST localhost:9999/wake -d @-'
+rly wait b-xxxxx --notify-cmd 'touch /tmp/board-done'
+```
+`--on-result` (on ask/show/reopen/reuse) runs your shell command the moment
+the board reaches a terminal status — submitted, acknowledged, timeout, or
+cancelled — with the full result JSON piped to stdin and `RLY_BOARD_ID`,
+`RLY_STATUS`, `RLY_URL` in the environment. `--notify-cmd` does the same from
+a `wait` that obtains a terminal result. Write a file your harness watches,
+hit a webhook — whatever wakes you.
+## Editable diagrams — let the user redraw your mermaid
+Add `"editable": true` to any mermaid block. The user gets an "Edit diagram"
+button with live-preview source editing (syntax errors shown inline without
+destroying the last good render; Reset restores your original). Their edited
+source returns in the result:
+```json
+"blockEdits": { "b2": "graph TD; A-->B; B-->C[their new step]" }
+```
+Diff it against your original to see exactly what the user changed. Recipe:
+propose an architecture as an editable mermaid block + a `yesno` "Does this
+match your mental model?" + a `textarea` for anything the diagram can't say.
+Edits autosave with the draft, so they survive reloads and timeouts too.
 ## Managing boards
 ```sh
@@ -290,6 +375,8 @@ 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 reopen <id> --replies replies.json
+                         # reopen with agent replies (see Threaded replies above)
 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
@@ -300,6 +387,26 @@ 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`).
+## Live board mutation — `rly update`
+Push a new spec to an already-open board without stopping it:
+```sh
+rly update <boardId> --file new-spec.json   # replace the full spec
+rly update <boardId> --title "New title"    # patch just the title
+rly update <boardId> --intro "New intro"    # patch just the intro
+rly update <boardId> -q "!Priority::single::p0,p1,p2"  # append a question
+```
+The page **reloads** for the user and prefills their previous answers from the
+autosaved draft — answers for question IDs that no longer exist are silently
+ignored. A small toast "Board updated by the agent" appears for 4 seconds.
+Stdout: `{"status":"updated","boardId":"…","rev":2,"url":"…"}`.
+**Caution:** the page reloads for the user. Batch your changes into one `rly update`
+call rather than calling it repeatedly in a loop.
 ## Tips for agents
 - Prefer `--detach` + `rly wait` if your shell tool kills long commands.
@@ -313,5 +420,11 @@ Storage lives in `~/.relay` (override with `RLY_HOME`).
   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.
+- Use `rly reopen <id> --replies replies.json` to answer the user's element
+  comments and reopen the board as a conversation thread.
+- Use `rly update <id>` to push spec changes to a running board — the page
+  reloads and answers survive via draft autosave. Batch updates; do not spam.
+- For sensitive PlantUML diagrams, set `"server": "https://your-server"` to avoid
+  sending source to the public plantuml.com server.
 - Bundled universal skill (Claude Code, Codex, any SKILL.md-aware agent):
   `rly skill install` — or `npx skills add khanglvm/relay`.

package/docs/assets/annotations.png ADDED Viewed

Binary file

package/docs/assets/board-dark.png ADDED Viewed

Binary file

package/docs/assets/board-light.png ADDED Viewed

Binary file

package/docs/assets/demo.gif ADDED Viewed

Binary file

package/docs/assets/mobile.png ADDED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: relay
-description: Ask the user interactive questions in a browser board (single/multi choice, yes-no, free text, scale) and/or present rich content blocks (markdown, mermaid diagrams, charts, interactive tables, code, sandboxed HTML), then wait for Submit and read JSON answers plus element-level annotations. PROACTIVELY use whenever you would otherwise (a) call a native ask-user/question tool with 2+ questions or options that need explanation, (b) describe a UI/design/plan/architecture in prose that a visual would show better — draft diagrams (mermaid), charts, and interactive tables as native blocks, or (c) hand-roll an HTML file or local server to demo an idea - relay replaces all three. Triggers - clarify requirements before ambiguous work, choose between approaches, plan approval, design/UX feedback, mockup or prototype review, compare alternatives, survey, metrics review, "ask the user", "show the user", "which do you prefer", "get feedback", diagram, chart, data table, architecture overview, metrics. Skip only for a single trivial yes/no confirmation.
+description: Show the user anything visual in an interactive browser board - repo/file structures, architecture diagrams (mermaid, graphviz, plantuml, uml), charts, sortable data tables, code, prototypes - and/or ask structured questions (single/multi choice, yes-no, free text, scale), then wait for Submit and read JSON answers plus element-level comments and user-edited diagrams. PROACTIVELY use whenever you would otherwise (a) draw an ASCII tree/table/diagram in the terminal or describe a structure/design/plan in prose - render it as interactive blocks instead, (b) call a native ask-user/question tool with 2+ questions or options that need explanation, or (c) hand-roll an HTML file or local server to demo an idea - relay replaces all three. Triggers - show me the structure, repo/project/folder structure, file tree, directory layout, codebase map, architecture overview, dependency graph, sequence/class diagram, uml, visualize, diagram, chart, data table, metrics review, mockup or prototype review, plan approval, design/UX feedback, compare alternatives, let the user edit the diagram, clarify requirements before ambiguous work, survey, "ask the user", "show the user", "which do you prefer", "get feedback". Skip only for a single trivial yes/no confirmation.
 ---
 # relay (`rly`)
@@ -35,20 +35,34 @@ questions into ONE board rather than opening several in a row.
 ## Choose a pattern
-1. **Blocking** — simple, but your shell tool must tolerate waiting:
+**DEFAULT: detached.** Most agent shell tools kill long-running commands, and a
+blocking `rly ask` that gets killed cancels the board. Always prefer:
-   ```sh
-   rly ask --file spec.json --timeout 1800   # prints result JSON when user submits
-   ```
+```sh
+rly ask --file spec.json --detach    # returns {"boardId":"b-…","url":…} immediately
+rly wait b-xxxxx --timeout 550       # blocks until submit, prints result JSON
+                                     # (on exit 2 "wait-timeout" just run wait again)
+rly result b-xxxxx                   # non-blocking peek (includes live draft)
+```
+For long waits prefer presence-aware waiting over a huge --timeout:
+```sh
+rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+# keeps extending while the user is demonstrably viewing/typing on the board;
+# returns wait-timeout promptly once they are idle/gone (presence included)
+rly result b-xxxxx        # while open also shows presence {visible, focused, secondsSinceActivity}
+```
-2. **Detached** — use when your shell tool has an execution time limit
-   (e.g. run it, then wait in a separate call):
+Push-wake instead of polling: add --on-result '<shell cmd>' to ask/show/reopen
+(or --notify-cmd on wait) - the command runs the moment the board finishes,
+with the full result JSON on stdin and RLY_BOARD_ID/RLY_STATUS/RLY_URL in env.
-   ```sh
-   rly ask --file spec.json --detach    # → {"boardId":"b-…","url":…} immediately
-   rly wait b-xxxxx --timeout 3500      # blocks until submit, prints result JSON
-   rly result b-xxxxx                   # non-blocking peek (includes live draft)
-   ```
+Blocking mode (`rly ask --file spec.json --timeout 1800`, no --detach) is fine
+ONLY when your shell tool has no execution time limit.
+Useful flags: `--no-open` (don't auto-open the browser — for tests/CI; real
+users need the tab, so omit it normally) · `--title` · `--timeout <sec>`.
 Exit codes: 0 submitted · 2 timeout · 3 cancelled · 5 not found. On
 timeout/cancel the result still contains the autosaved `draft` of partial
@@ -66,7 +80,8 @@ answers and any annotations written so far.
     { "id": "parts", "type": "multi", "label": "Include?", "options": ["api", "ui"], "note": true },
     { "id": "ship", "type": "yesno", "label": "Ship now?" },
     { "id": "why", "type": "textarea", "label": "Reasoning?" },
-    { "id": "conf", "type": "scale", "label": "Confidence", "min": 1, "max": 5 }
+    { "id": "conf", "type": "scale", "label": "Confidence", "min": 1, "max": 5,
+      "minLabel": "low", "maxLabel": "high" }
   ]
 }
 ```
@@ -92,6 +107,9 @@ Add `"blocks": [...]` to the root or to any question.
 ```jsonc
 { "type": "markdown", "md": "## Section\n**prose**" }
 { "type": "mermaid",  "code": "graph TD; A-->B",     "height": 400 }
+{ "type": "graphviz", "dot": "digraph { a -> b }",   "height": 300 }
+{ "type": "plantuml", "code": "@startuml\nA->B\n@enduml", "height": 300 }
+{ "type": "plantuml", "code": "...", "server": "https://plantuml.example.com" }
 { "type": "chart",    "kind": "bar",  "title": "...",
   "labels": ["Jan","Feb"], "series": [{"label":"x","data":[1,2]}], "height": 320 }
 { "type": "chart",    "config": { /* full Chart.js v4 config */ }, "height": 300 }
@@ -101,14 +119,15 @@ Add `"blocks": [...]` to the root or to any question.
 { "type": "html",     "htmlFile": "viz.html",         "height": 400 }
 ```
-Chart.js and Mermaid are **vendored and lazy-loaded** — the base board stays
-dependency-free. Legacy `"html"` / `"htmlFile"` / `"htmlHeight"` on root or
-questions are still accepted and normalised automatically.
+Chart.js, Mermaid, and Graphviz are **vendored and lazy-loaded** — the base board
+stays dependency-free. PlantUML uses the public plantuml.com server by default;
+pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
+`"htmlHeight"` on root or questions are still accepted and normalised automatically.
 ## Annotations
-Users can hover chart points, diagram nodes, table cells, or select text in
-markdown to leave inline comments. Always mention this in the board intro.
+Users can hover chart points, diagram nodes (mermaid + graphviz), table cells, or
+select text in markdown to leave inline comments. Always mention this in the board intro.
 `result.annotations` is an array of:
@@ -117,18 +136,32 @@ markdown to leave inline comments. Always mention this in the board intro.
   "id": "a1",
   "questionId": "q-id or null",
   "blockId": "b2",
-  "target": {
-    "kind": "chart-element | mermaid-node | table-cell | text | html-element",
-    "..."
-  },
+  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image", "..." },
   "text": "user comment",
-  "createdAt": "ISO"
+  "author": "user",
+  "createdAt": "ISO",
+  "replies": [{ "author": "agent", "text": "acknowledged", "createdAt": "ISO" }]
 }
 ```
 Read annotations before generating your next output — a comment on a specific
 data point often carries sharper signal than a checkbox answer.
+### Reply to annotations (agent → user conversation)
+```sh
+# 1. Read result from a previous board
+rly result <id>   # or rly wait <id>
+# 2. Build replies file
+# replies.json: [{"annotationId":"a1","text":"Good catch — fixed."}]
+# 3. Reopen as a conversation
+rly reopen <id> --replies replies.json
+```
+Unknown annotation IDs cause an error listing valid IDs (exit 4).
 ## Recipes
 **Plan approval** — board-level `markdown` block rendering the plan, one `yesno`
@@ -148,9 +181,31 @@ numbers, followed by a `table` block for the raw data; at least one question
 asking what to act on. In the intro, tell the user they can click chart points
 and table cells to comment on specific values.
+## Diagram co-editing (user edits your diagram)
+Add "editable": true to a mermaid block: the user gets an Edit button with
+live-preview source editing. Their version comes back as
+result.blockEdits["<blockId>"] - diff it against your original to see what
+they changed. Recipe: propose an architecture as an editable mermaid block +
+one yesno "Does this match your mental model?" + a textarea for notes.
 ## Reuse & management
 `rly history` (saved boards) · `rly spec <id>` (print spec to modify) ·
 `rly reuse <id>` (re-run blank) · `rly reopen <id>` (re-open with saved
-answers prefilled) · `rly list` / `rly open` / `rly stop <id>` · `rly rm <id>`.
+answers prefilled) · `rly reopen <id> --replies file.json` (add agent replies) ·
+`rly list` / `rly open` / `rly stop <id>` · `rly rm <id>`.
 Multiple boards can run concurrently.
+### Live mutation — `rly update`
+Push a new spec to a running board. The page reloads and prefills answers from the
+autosaved draft — answers survive, the user sees a toast "Board updated by the agent".
+```sh
+rly update <boardId> --file new-spec.json        # replace spec
+rly update <boardId> --title T --intro I         # patch fields
+rly update <boardId> -q "!Priority::single::p0,p1"  # append question
+```
+Batch your changes into one call — the page reloads for the user on each update.

package/skills/relay/examples/blocks-showcase.json CHANGED Viewed

@@ -26,6 +26,15 @@
       "code": "graph LR\n  Client-->|HTTPS|Gateway\n  Gateway-->AuthService\n  Gateway-->APIService\n  APIService-->DB[(Postgres)]\n  APIService-->Cache[(Redis)]\n  APIService-->Queue[[Job queue]]\n  Queue-->Worker\n  Worker-->DB",
       "height": 300
     },
+    {
+      "type": "markdown",
+      "md": "## Service dependency graph\nThe Graphviz diagram below shows precise call-time dependencies between services. Click any node or edge to leave a comment."
+    },
+    {
+      "type": "graphviz",
+      "dot": "digraph services {\n  rankdir=LR\n  node [shape=box style=filled fontname=Helvetica fontsize=11]\n  Gateway    [fillcolor=\"#c8e6c9\"]\n  APIService [fillcolor=\"#fff9c4\"]\n  AuthService[fillcolor=\"#c8e6c9\"]\n  DB         [shape=cylinder fillcolor=\"#bbdefb\"]\n  Cache      [shape=cylinder fillcolor=\"#bbdefb\"]\n  Worker     [fillcolor=\"#fff9c4\"]\n  Gateway    -> APIService\n  Gateway    -> AuthService\n  APIService -> DB\n  APIService -> Cache\n  APIService -> Worker [style=dashed label=\"async\"]\n  Worker     -> DB\n}",
+      "height": 260
+    },
     {
       "type": "markdown",
       "md": "## Service health snapshot\nCurrent status as of the last deployment. Click any cell to comment."

package/skills/relay/examples/diagram-coedit.json ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "title": "Architecture review — redraw it if I got it wrong",
+  "intro": "Below is my proposed architecture. If it doesn't match your mental model, click 'Edit diagram' and change it directly — I'll read your version.",
+  "blocks": [
+    {
+      "type": "mermaid",
+      "editable": true,
+      "code": "graph TD; client[Web Client] --> api[API Gateway]; api --> auth[Auth Service]; api --> core[Core Service]; core --> db[(Postgres)]; core --> queue[[Job Queue]]"
+    }
+  ],
+  "questions": [
+    { "id": "match", "type": "yesno", "label": "Does this match your mental model (after your edits, if any)?", "required": true },
+    { "id": "notes", "type": "textarea", "label": "Anything the diagram can't express?", "placeholder": "constraints, scaling concerns, naming…" }
+  ]
+}