@khanglvm/relay 0.5.4 → 0.7.0

package/README.md

@@ -92,6 +92,22 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 ```
 
+## Changelog
+
+### 0.6.0 — comment on anything
+- **Comment on any part of a custom-HTML mockup.** Hover any element — a heading,
+  a button, a card, the price — and a pin appears to leave an inline note. No
+  setup needed; the agent writes zero annotation code. Want to scope it? Mark
+  specific elements with `data-relay-annotate="label"`.
+- **Radio questions can carry a note.** Pick an option *and* say why, in one
+  optional field — now shown by default (set `"note": false` to hide it).
+- **Edge-to-edge fullscreen** for charts and HTML mockups, with the toolbar
+  pinned to the top while you scroll.
+- The board **title and intro are commentable** too.
+
+### 0.5.0
+- Visual answer options, image blocks, viewer redesign, adoption rules.
+
 ## Migration from quest-board
 
 relay was formerly `@khanglvm/quest-board` (CLI: `qbd`) — that package is

package/docs/AGENT.md

@@ -6,9 +6,10 @@ 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.
+points, diagram nodes, table cells, and any element of a custom-HTML block 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 ·
@@ -137,7 +138,9 @@ boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scal
 
 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
+notes come back in `notes` keyed by question id. **`single` (radio) questions
+show this note by default** so the user can qualify their pick — set
+`"note": false` to hide it. On `timeout`/`cancelled`, a
 `draft` field carries the autosaved partial answers and any annotations written
 so far.
 
@@ -186,7 +189,9 @@ Rules of thumb:
 ### All block shapes
 
 ```jsonc
-// Markdown — built-in mini renderer, no library
+// Markdown — built-in mini renderer, no library. Headings, lists, code, quotes,
+// links, and GFM pipe tables all render. For real tabular DATA use a `table`
+// block instead (sortable + per-cell comments); markdown tables are display-only.
 { "type": "markdown", "md": "## Heading\nAny **CommonMark** prose." }
 
 // Mermaid diagram — vendored, lazy-loaded; natural height, max 1200 px + scroll
@@ -226,7 +231,9 @@ Rules of thumb:
   "height": 280
 }
 
-// Table — sortable, annotatable cells
+// Table — sortable, with individually annotatable cells. Prefer this over a
+// markdown pipe table whenever you're showing structured data (option matrices,
+// comparisons, workstream/effort grids): users can sort it and comment per cell.
 {
   "type": "table",
   "columns": [
@@ -263,8 +270,8 @@ Rules of thumb:
 | `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 |
+| `table` | structured comparisons, option matrices, data grids — **use this for any tabular data**: it's sortable and every cell is commentable, unlike a markdown pipe table |
+| `markdown` | prose context, background, instructions, section headings (renders GFM pipe tables too, but reach for a `table` block for real data) |
 | `code` | code snippets, config examples, command output |
 | `image` | screenshots, mockup exports, photos — local files embed and work offline |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
@@ -295,23 +302,40 @@ Rules of thumb:
   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
+### Custom HTML is hover-commentable automatically
 
-Load `/kit.js` inside your custom HTML iframe to let users comment on specific
-elements:
+Every custom-HTML block is annotatable out of the box — relay injects a tiny
+runtime that lets the user **hover any meaningful element** (headings,
+paragraphs, list items, buttons, images, cards, table cells…) to get a comment
+pin, exactly like the rest of the board. You don't have to do anything. Comments
+come back in `result.annotations` with `target.kind = "html-element"`, a stable
+`target.ref` (the element), and a `target.label` derived from the element.
+
+Reach for the controls below only when you want to **scope or label** what's
+annotatable — typically for an interactive prototype where blanket hover targets
+would get in the way:
+
+**Declarative signal (preferred)** — mark the elements you want commented. Any
+signal present switches the auto-pick off, so only your marked elements are
+annotatable:
+
+```html
+<button data-relay-annotate="Primary CTA" data-relay-detail="checkout flow">Buy now</button>
+<section data-relay-annotate="Pricing table">…</section>
+```
+
+**Imperative** — same effect from script (needs `/kit.js`, which relay also
+auto-loads):
 
 ```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`.
+**Opt out** of element annotation for a block with `data-relay-annotate="off"`
+on `<html>` or `<body>`.
 
 ## Annotations
 
@@ -349,7 +373,7 @@ intro. Annotations are autosaved with the draft and returned in the final result
 | `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 |
+| `html-element` | `ref`, `label`, `detail?` | hovering any element in a custom-HTML block (auto), or a `data-relay-annotate` / `relayKit.commentable()` element |
 | `image` | `label` | clicking a PlantUML diagram or an image block |
 
 Read annotations as first-class feedback — they often carry the sharpest insight
@@ -390,6 +414,18 @@ 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`.
 
+### A `timeout` on a detached board is NOT the end
+
+For a **detached** board, the `timeout` deadline is *soft*: it hands you a
+`timeout` result (with the autosaved draft) so you regain control, but the
+server stays up and the board stays fully usable — the user can keep
+commenting and still hit Submit. The page tells them you stopped waiting and
+to prompt you afterward. So if you got a `timeout` and the user might still be
+working: re-check later with `rly result <id>` (its status flips to
+`submitted` once they finish), or pass `--on-result` so a late submit
+push-wakes you. A blocking `rly ask` (no `--detach`) still ends hard on
+timeout, since there's no separate waiter to hand back to.
+
 ## Push-wake — get notified instead of polling
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.5.4",
+  "version": "0.7.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

@@ -93,7 +93,8 @@ submit with unanswered questions (returned in `skipped`) unless
 
 Set `"note": true` on a question to add a small optional free-text field under
 it — use when the user may want to qualify their choice. Returned as
-`result.notes[questionId]`.
+`result.notes[questionId]`. `single` (radio) questions include this note by
+default (so a pick can carry a comment); set `"note": false` to hide it.
 
 Quick one-liners without a spec file:
 
@@ -116,6 +117,8 @@ single/multi question.
   "labels": ["Jan","Feb"], "series": [{"label":"x","data":[1,2]}], "height": 320 }
 { "type": "chart",    "config": { /* full Chart.js v4 config */ }, "height": 300 }
 { "type": "table",    "columns": ["A","B"], "rows": [["x","y"]], "sortable": true }
+// ^ use a `table` block for tabular data — sortable + per-cell comments.
+//   (markdown blocks render GFM pipe tables too, but those are display-only.)
 { "type": "code",     "lang": "js",  "code": "const x = 1;" }
 { "type": "html",     "html": "<p>hi</p>",           "height": 360 }
 { "type": "html",     "htmlFile": "viz.html",         "height": 400 }
@@ -153,8 +156,12 @@ pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
 
 ## Annotations
 
-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.
+Users can hover chart points, diagram nodes (mermaid + graphviz), table cells,
+any element of a custom-HTML block, or select text in markdown to leave inline
+comments. Custom HTML is hover-commentable automatically — to scope/label what's
+annotatable, mark elements with `data-relay-annotate="Label"` (any signal turns
+the auto-pick off); opt a block out with `data-relay-annotate="off"`. Always
+mention annotation in the board intro.
 
 `result.annotations` is an array of:
 

package/src/cli.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { CliError, sleep, pollFor } from './util.js';
 import { normalizeSpec, questionFromInline, SPEC_SCHEMA } from './spec.js';
@@ -23,7 +23,9 @@ import { openUrl } from './open.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.join(__dirname, '..');
 const BIN = path.join(PKG_ROOT, 'bin', 'rly.js');
-const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+const PKG_JSON = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+const VERSION = PKG_JSON.version;
+const PKG_NAME = PKG_JSON.name; // e.g. "@khanglvm/relay" — the global package to upgrade
 
 const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
@@ -798,6 +800,113 @@ function cmdAgent() {
   return 0;
 }
 
+// `rly upgrade` — install the latest CLI globally AND refresh the bundled skill
+// in one shot. (`update` is taken by the live-mutate command, so this is
+// `upgrade` / `self-update`.) Running boards are surfaced and handled: a global
+// reinstall overwrites relay's files, but live detached servers snapshot their
+// UI at first request and serve from memory, so they keep working on their own
+// version. Flags: --stop (stop running boards first), --force (upgrade while
+// they keep running), --cli-only / --skill-only (scope).
+async function cmdUpgrade(args) {
+  const force = args.force === true;
+  const doStop = args.stop === true;
+  const wantCli = args.skillOnly !== true;
+  const wantSkill = args.cliOnly !== true;
+
+  const running = listRunning();
+
+  // --dry-run: report the plan (incl. how running boards would be handled)
+  // without installing anything or stopping anything.
+  if (args.dryRun === true) {
+    printJson({
+      dryRun: true,
+      wouldRun: [wantCli && `npm install -g ${PKG_NAME}@latest`, wantSkill && 'rly skill install'].filter(Boolean),
+      runningBoards: running.map((r) => r.id),
+      runningHandling: running.length
+        ? doStop
+          ? 'stop them first'
+          : force
+            ? 'leave them running (snapshotted)'
+            : 'BLOCKED — pass --stop or --force'
+        : 'none running',
+    });
+    return 0;
+  }
+
+  if (running.length) {
+    const ids = running.map((r) => r.id).join(', ');
+    if (doStop) {
+      process.stderr.write(`Stopping ${running.length} running board(s) before upgrading: ${ids}\n`);
+      for (const r of running) {
+        try { process.kill(r.pid, 'SIGTERM'); } catch { /* already gone */ }
+      }
+      for (const r of running) await pollFor(() => (loadRunning(r.id) ? null : true), 5000);
+    } else if (!force) {
+      // Default: don't silently overwrite under live boards — explain + let the
+      // user choose. The boards themselves are safe; this is about clarity.
+      process.stderr.write(
+        `${running.length} board(s) still running: ${ids}\n` +
+          'They keep serving their current version safely (each snapshots its UI in memory),\n' +
+          'and stay readable via `rly result <id>` / `rly wait <id>`. Pick one:\n' +
+          '  • rly stop --all       then re-run `rly upgrade`  (cleanest)\n' +
+          '  • rly upgrade --stop   stop them as part of this upgrade\n' +
+          '  • rly upgrade --force  upgrade now; leave them running on their snapshot\n'
+      );
+      printJson({ upgraded: false, reason: 'running-boards', running: running.map((r) => r.id) });
+      return 0;
+    } else {
+      process.stderr.write(`--force: leaving ${running.length} board(s) running on their snapshotted version: ${ids}\n`);
+    }
+  }
+
+  const did = {};
+
+  if (wantCli) {
+    process.stderr.write(`\nUpgrading ${PKG_NAME} → latest  (npm install -g ${PKG_NAME}@latest)\n`);
+    const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@latest`], { stdio: 'inherit' });
+    if (r.error || r.status !== 0) {
+      throw new CliError(
+        `npm install failed${r.error ? ` (${r.error.message})` : ` (exit ${r.status})`}. ` +
+          `Update manually: npm install -g ${PKG_NAME}@latest`,
+        1
+      );
+    }
+    did.cli = `${PKG_NAME}@latest`;
+  }
+
+  if (wantSkill) {
+    // Spawn the freshly installed binary (on PATH) so the NEW bundled skill is
+    // what lands — this process still holds the previous bundle in memory.
+    process.stderr.write('\nRefreshing the bundled skill  (rly skill install)\n');
+    const r = spawnSync('rly', ['skill', 'install'], { stdio: 'inherit', shell: true });
+    if (r.error || r.status !== 0) {
+      process.stderr.write(
+        `Skill refresh did not complete${r.error ? ` (${r.error.message})` : ` (exit ${r.status})`} — ` +
+          'run `rly skill install` yourself (or `npx skills add khanglvm/relay --skill relay --all`).\n'
+      );
+    } else {
+      did.skill = 'installed';
+    }
+  }
+
+  // Report the now-current global version (best-effort).
+  let nowVersion = null;
+  try {
+    const v = spawnSync('rly', ['--version'], { encoding: 'utf8', shell: true });
+    if (v.status === 0 && v.stdout) nowVersion = String(v.stdout).trim();
+  } catch {
+    // best effort
+  }
+
+  printJson({
+    upgraded: true,
+    ...did,
+    version: nowVersion,
+    note: 'most agents pick the new skill up immediately; if not, re-list skills or restart the session',
+  });
+  return 0;
+}
+
 async function cmdServeInternal(args) {
   const id = args.id;
   if (!id) throw new CliError('__serve: missing --id');
@@ -807,6 +916,9 @@ async function cmdServeInternal(args) {
     open: args.open !== false,
     timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800,
     quiet: true,
+    // Detached board: timeout hands back to the agent but keeps serving so the
+    // user can keep commenting and still submit (seamless past the deadline).
+    keepAliveOnTimeout: true,
   });
   await done;
   return 0;
@@ -842,6 +954,8 @@ USAGE
   rly agent                           FULL GUIDE for AI agents (spec format, blocks, sizing, patterns)
   rly skill [install|rules|path]      bundled universal agent skill (Claude Code, Codex, …)
                                       \`rly skill rules >> CLAUDE.md\` adds always-read usage rules
+  rly upgrade                         install the latest CLI globally + refresh the skill in one step
+                                      --stop/--force handle running boards · --dry-run · --cli-only/--skill-only
 
 COMMON FLAGS
   --title <s> --intro <s> --html-file <f> --height <px> --submit-label <s>
@@ -904,6 +1018,9 @@ export async function main(argv) {
         return cmdRm(parseArgs(rest));
       case 'skill':
         return cmdSkill(rest);
+      case 'upgrade':
+      case 'self-update':
+        return await cmdUpgrade(parseArgs(rest));
       case 'agent':
         return cmdAgent();
       case 'schema':

package/src/server.js

@@ -16,12 +16,25 @@ const escapeHtml = (s) =>
 
 // Concurrently authored UI assets (blocks/annotate) may not exist yet at this
 // phase's runtime — read-guard so the server still boots with empty fallbacks.
+//
+// Successful reads are cached for the lifetime of the process. A running board
+// thus serves one consistent UI snapshot taken at first request: if the relay
+// package is updated on disk (e.g. `rly upgrade`) while this server is live, it
+// keeps serving its own version instead of mixing new assets with old in-memory
+// server logic. Empty/failed reads are NOT cached, preserving the boot-time
+// fallback for assets authored concurrently during a build.
+const _uiCache = new Map();
 function readUi(name) {
+  const hit = _uiCache.get(name);
+  if (hit) return hit;
+  let content = '';
   try {
-    return fs.readFileSync(path.join(UI_DIR, name), 'utf8');
+    content = fs.readFileSync(path.join(UI_DIR, name), 'utf8');
   } catch {
     return '';
   }
+  if (content) _uiCache.set(name, content);
+  return content;
 }
 
 // Strips block bodies for the client payload: html blocks ship only metadata
@@ -230,16 +243,35 @@ function sendFromDir(res, dir, name, contentType) {
   return true;
 }
 
+// Loaded into every custom-HTML iframe so users can hover any element to leave a
+// comment (relayKit.annotate.auto). Idempotent with an author-added /kit.js, and
+// a no-op when the author opts out via data-relay-annotate="off".
+const ANNOTATE_BOOTSTRAP =
+  '<script>(function(){function go(){try{window.relayKit&&window.relayKit.annotate&&window.relayKit.annotate.auto();}catch(e){}}' +
+  'if(window.relayKit&&window.relayKit.annotate)return go();' +
+  "var s=document.createElement('script');s.src='/kit.js';s.onload=go;s.onerror=go;" +
+  '(document.head||document.documentElement).appendChild(s);})();<\/script>';
+
+// Insert a snippet right before </body> (else </html>, else append).
+function injectBeforeBodyEnd(html, snippet) {
+  const lower = html.toLowerCase();
+  let idx = lower.lastIndexOf('</body>');
+  if (idx === -1) idx = lower.lastIndexOf('</html>');
+  if (idx === -1) return html + snippet;
+  return html.slice(0, idx) + snippet + html.slice(idx);
+}
+
 // Custom-HTML fragments (no <html> tag) get wrapped in a minimal document that
 // matches the user's theme, so e.g. "<b>hi</b>" doesn't paint a stark white
 // block in dark mode. Full documents are served verbatim — their authors can
-// read the ?theme=light|dark query param themselves.
+// read the ?theme=light|dark query param themselves. Either way the annotate
+// bootstrap is injected so every element is hover-commentable.
 function wrapFragment(content, theme) {
-  if (/<html[\s>]/i.test(content)) return content;
+  if (/<html[\s>]/i.test(content)) return injectBeforeBodyEnd(content, ANNOTATE_BOOTSTRAP);
   const dark = theme === 'dark';
   const bg = dark ? '#282624' : '#ffffff';
   const fg = dark ? '#edeae4' : '#1c1b19';
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}</body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}${ANNOTATE_BOOTSTRAP}</body></html>`;
 }
 
 function readBody(req, limit = 5 * 1024 * 1024) {
@@ -305,7 +337,7 @@ function runOnResult(cmd, result, { quiet = false } = {}) {
 // (submitted / acknowledged / timeout / cancelled). The result is also
 // persisted into the board record so `rly wait` / `rly result` can read it
 // from another process.
-export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, quiet = false }) {
+export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, quiet = false, keepAliveOnTimeout = false }) {
   const record = loadBoard(id);
   if (!record) throw new Error(`board ${id} not found`);
   const spec = record.spec;
@@ -336,6 +368,11 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   let rev = 1;
   let status = 'open';
   let finished = false;
+  // Soft timeout: the board's time is up and a `timeout` result was handed back
+  // to the waiting agent, but the server stays live so the user can keep
+  // working and still submit. Surfaced via /api/status so the page can show a
+  // calm "agent stopped waiting" note instead of disconnecting.
+  let softTimedOut = false;
   // Latest client presence ping (null until the first ping arrives).
   let presence = null;
   let resolveDone;
@@ -353,7 +390,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       } else if (req.method === 'GET' && pathname === '/api/board') {
         sendJson(res, 200, { id: record.id, spec: record.spec, draft: record.draft, result: record.result });
       } else if (req.method === 'GET' && pathname === '/api/status') {
-        sendJson(res, 200, { status, rev });
+        sendJson(res, 200, { status, rev, softTimedOut });
       } else if (req.method === 'POST' && pathname === '/api/ping') {
         const body = JSON.parse((await readBody(req)) || '{}');
         // Validate body shape: visible/focused booleans, idleMs finite >= 0.
@@ -479,15 +516,25 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   });
 
   let timer = null;
-  if (timeoutSec > 0) timer = setTimeout(() => finish({ status: 'timeout' }), timeoutSec * 1000);
+  let idleTimer = null;
+  // The detached server's timeout is SOFT (keepAliveOnTimeout): at the deadline
+  // we hand a `timeout` result back to the waiting agent (so `rly wait` returns
+  // with the autosaved draft) but keep the server listening, so the user can
+  // keep working and still submit. A late submit overwrites the result with
+  // `submitted` and re-fires the push-wake; the board only truly closes on
+  // submit, an explicit stop, or once the user has clearly left (idle
+  // watchdog). A BLOCKING `rly ask` has no separate waiter to hand back to, so
+  // its timeout stays hard (close + resolve, exit 2).
+  if (timeoutSec > 0) {
+    timer = setTimeout(keepAliveOnTimeout ? softTimeout : () => finish({ status: 'timeout' }), timeoutSec * 1000);
+  }
   const onSignal = () => finish({ status: 'cancelled' });
   process.on('SIGINT', onSignal);
   process.on('SIGTERM', onSignal);
 
-  function finish(partial) {
-    if (finished) return;
-    finished = true;
-    status = partial.status;
+  // Build + persist a result object onto the record (read cross-process by
+  // `rly wait` / `rly result`). Does NOT touch the server lifecycle.
+  function persistResult(partial) {
     // blockEdits: from this submit, else fall back to the autosaved draft
     // (timeout/cancel). null when there are none.
     const editsRaw = partial.blockEdits ?? (record.draft?.blockEdits || {});
@@ -514,13 +561,17 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     }
     record.result = result;
     saveBoard(record);
-    // Push-wake: run the agent's local command for EVERY terminal status.
-    runOnResult(record.onResult, result, { quiet });
+    return result;
+  }
+
+  // Tear the HTTP server down after a short grace (so the success page renders
+  // and auto-closes first). The result is assumed already persisted.
+  function closeServer(result) {
     removeRunning(record.id);
     if (timer) clearTimeout(timer);
+    if (idleTimer) clearInterval(idleTimer);
     process.removeListener('SIGINT', onSignal);
     process.removeListener('SIGTERM', onSignal);
-    // Grace period so the success page renders (and auto-closes) first.
     setTimeout(() => {
       try {
         server.closeAllConnections?.();
@@ -532,6 +583,52 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     }, 600);
   }
 
+  // Terminal finish (submit / acknowledge / explicit cancel): persist the
+  // result, push-wake the agent for EVERY terminal status, and close the
+  // server. A late submit after a soft timeout lands here and overwrites the
+  // earlier `timeout` result with `submitted` (re-firing the push-wake).
+  function finish(partial) {
+    if (finished) return;
+    finished = true;
+    status = partial.status;
+    const result = persistResult(partial);
+    runOnResult(record.onResult, result, { quiet });
+    closeServer(result);
+  }
+
+  // SOFT timeout — hand a `timeout` result to the agent but keep the board live
+  // and submittable. The agent's `rly wait` returns now; the user can carry on.
+  function softTimeout() {
+    if (finished || softTimedOut) return;
+    softTimedOut = true;
+    const result = persistResult({ status: 'timeout' });
+    runOnResult(record.onResult, result, { quiet });
+    startIdleWatchdog();
+  }
+
+  // After a soft timeout, close the board for real once the user has clearly
+  // left (no presence ping for IDLE_CLOSE_MS) or a hard absolute cap is hit, so
+  // an abandoned board doesn't keep a server alive forever. Re-persists the
+  // latest draft as the final `timeout` result; no double push-wake.
+  function startIdleWatchdog() {
+    const IDLE_CLOSE_MS = 15 * 60 * 1000;
+    const HARD_CAP_MS = 6 * 60 * 60 * 1000;
+    const softAt = Date.now();
+    idleTimer = setInterval(() => {
+      if (finished) {
+        clearInterval(idleTimer);
+        return;
+      }
+      const lastSeen = presence ? presence.atMs : softAt;
+      if (Date.now() - lastSeen > IDLE_CLOSE_MS || Date.now() - softAt > HARD_CAP_MS) {
+        finished = true;
+        clearInterval(idleTimer);
+        closeServer(persistResult({ status: 'timeout' }));
+      }
+    }, 60 * 1000);
+    idleTimer.unref?.();
+  }
+
   if (open) openUrl(url);
   if (!quiet) {
     process.stderr.write(

package/src/spec.js

@@ -332,7 +332,10 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
       label,
       description: asStr(rq.description),
       required: rq.required === true,
-      note: rq.note === true,
+      // Radio (single) questions show the optional per-answer note by default so
+      // the user can qualify their pick; other types stay opt-in. An explicit
+      // note:false turns it off for a single question.
+      note: rq.note === undefined ? type === 'single' : rq.note === true,
       blocks: buildBlocks(rq, cwd, where, `${id}-`),
       placeholder: asStr(rq.placeholder),
     };
@@ -408,7 +411,7 @@ const BLOCK_SCHEMA = {
     required: ['type'],
     properties: {
       type: { type: 'string', enum: BLOCK_TYPES },
-      md: { type: 'string', description: 'markdown: built-in mini renderer (no external library). Text selections are commentable.' },
+      md: { type: 'string', description: 'markdown: built-in mini renderer (no external library) — headings, lists, code, quotes, links, and GFM pipe tables. Text selections are commentable. For real tabular data prefer a "table" block (sortable + per-cell comments).' },
       code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display.' },
       editable: { type: 'boolean', description: 'mermaid: when true, render an "Edit diagram" toggle so the user can edit the diagram source live. The edited source is returned in result.blockEdits[<blockId>].' },
       dot: { type: 'string', description: 'graphviz: DOT source (e.g. "digraph { a -> b }"). Rendered offline via vendored Viz.js; nodes and edges are individually commentable.' },
@@ -486,7 +489,7 @@ export const SPEC_SCHEMA = {
             },
           },
           other: { type: 'boolean', default: false, description: 'single/multi: add a free-text "Other" option. Its text is returned verbatim as the value.' },
-          note: { type: 'boolean', default: false, description: 'Add a small optional free-text field under the question (e.g. to qualify a choice). Returned separately as result.notes[questionId].' },
+          note: { type: 'boolean', description: 'Small optional free-text field under the question (to qualify an answer). Returned separately as result.notes[questionId]. Defaults to true for "single" (radio) questions so users can comment on their pick, false for other types; set note:false to hide it on a single question.' },
           placeholder: { type: 'string', description: 'For text/textarea.' },
           default: { description: 'Pre-selected value. Shape matches the answer shape for the type.' },
           min: { type: 'integer', default: 1, description: 'scale only' },
@@ -504,7 +507,7 @@ export const SPEC_SCHEMA = {
       type: 'array',
       readOnly: true,
       description:
-        'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"table-cell"|"text"|"html-element", …}, text, createdAt}.',
+        'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"graphviz-node"|"table-cell"|"text"|"html-element"|"image", …}, text, createdAt}. For html-element, target carries a stable ref + label; users can hover any element of a custom-HTML block (automatic) or ones the author marked with data-relay-annotate.',
     },
     blockEdits: {
       type: 'object',