@khanglvm/relay 0.6.0 → 0.8.0

package/docs/AGENT.md

@@ -189,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
@@ -229,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": [
@@ -266,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 |
@@ -410,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.6.0",
+  "version": "0.8.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

@@ -117,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 }

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,12 +23,14 @@ 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',
   'submit-label', 'height', 'limit', 'target', 'id', 'replies',
-  'on-result', 'notify-cmd', 'idle-grace',
+  'on-result', 'notify-cmd', 'idle-grace', 'scope',
 ]);
 
 function camel(key) {
@@ -769,6 +771,11 @@ function cmdSkill(rest) {
     const installed = [];
     for (const t of targets) {
       fs.mkdirSync(path.dirname(t), { recursive: true });
+      // Clear whatever is already there first. cpSync refuses to overwrite a
+      // non-directory (a symlink or file at the target — e.g. a skill dir the
+      // user symlinked elsewhere) with a directory, so a plain re-install would
+      // crash. rmSync on a symlink removes the link itself, not its target.
+      fs.rmSync(t, { recursive: true, force: true });
       fs.cpSync(SKILL_SRC, t, { recursive: true });
       fs.writeFileSync(path.join(t, '.rly-version'), VERSION);
       installed.push(t);
@@ -793,11 +800,302 @@ Full guide: \`rly agent\`.`);
   return 0;
 }
 
+// ===========================================================================
+// `rly install` — inject relay's always-read rules into ANY agent's
+// instruction file, cross-platform. `rly skill install` (above) handles the
+// full SKILL.md for skill-aware agents; this covers the long tail (Cursor,
+// Copilot, Kiro, Windsurf, Cline, Gemini, generic AGENTS.md, …) that read a
+// rules/instructions/steering/context markdown file instead.
+// ===========================================================================
+
+const RELAY_BEGIN = '<!-- relay:begin (managed by `rly install` — your edits outside these markers are kept) -->';
+const RELAY_END = '<!-- relay:end -->';
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Resolve OS-specific base dirs from an injectable env/home/platform so the
+// path logic is unit-testable for win32 / linux / darwin without running there.
+function platformDirs({ platform, home, env }) {
+  const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config');
+  const localApp = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  // Copilot-in-JetBrains global instructions dir.
+  const jetbrainsCopilot = platform === 'win32'
+    ? path.join(localApp, 'github-copilot', 'intellij')
+    : path.join(xdg, 'github-copilot', 'intellij');
+  return { jetbrainsCopilot, documents: path.join(home, 'Documents') };
+}
+
+// The relay instruction registry. Each agent declares how to install relay's
+// rules at `global` (user, machine-wide) and/or `project` (cwd) scope, in what
+// `style`, and a `detect` dir whose existence means "you use this agent"
+// (drives `--all`). Styles:
+//   'shared'    — upsert a marked block into a possibly-shared file (CLAUDE.md,
+//                 AGENTS.md, copilot-instructions.md, …); your other content is
+//                 preserved, only relay's block is rewritten.
+//   'dedicated' — relay owns the whole file (.kiro/steering, .windsurf/rules,
+//                 .clinerules, …); safe to overwrite.
+//   'mdc'       — dedicated, with Cursor `.mdc` YAML frontmatter.
+export function agentRegistry({ platform = process.platform, home = os.homedir(), cwd = process.cwd(), env = process.env } = {}) {
+  const d = platformDirs({ platform, home, env });
+  const j = path.join;
+  return [
+    { id: 'claude', label: 'Claude Code',
+      detect: j(home, '.claude'),
+      global: { file: j(home, '.claude', 'CLAUDE.md'), style: 'shared' },
+      project: { file: j(cwd, 'CLAUDE.md'), style: 'shared' },
+      note: 'full skill: `rly skill install`' },
+    { id: 'codex', label: 'OpenAI Codex',
+      detect: j(home, '.codex'),
+      global: { file: j(home, '.codex', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+    { id: 'agents', label: 'AGENTS.md standard (Amp, Jules, Cline, …)',
+      detect: j(home, '.agents'),
+      global: { file: j(home, '.agents', 'AGENTS.md'), style: 'shared' },
+      project: { file: j(cwd, 'AGENTS.md'), style: 'shared' } },
+    { id: 'cursor', label: 'Cursor',
+      detect: j(home, '.cursor'),
+      global: null, // user rules are set in Cursor Settings UI (not file-based)
+      project: { file: j(cwd, '.cursor', 'rules', 'relay.mdc'), style: 'mdc' },
+      note: 'global "User Rules" are set in Settings UI, not a file' },
+    { id: 'copilot', label: 'GitHub Copilot (VS Code / Visual Studio / JetBrains)',
+      detect: path.dirname(d.jetbrainsCopilot), // …/github-copilot
+      global: { file: j(d.jetbrainsCopilot, 'global-copilot-instructions.md'), style: 'shared' },
+      project: { file: j(cwd, '.github', 'copilot-instructions.md'), style: 'shared' },
+      note: 'global file applies in JetBrains IDEs; project file applies everywhere' },
+    { id: 'kiro', label: 'Kiro',
+      detect: j(home, '.kiro'),
+      global: { file: j(home, '.kiro', 'steering', 'relay.md'), style: 'dedicated' },
+      project: { file: j(cwd, '.kiro', 'steering', 'relay.md'), style: 'dedicated' } },
+    { id: 'windsurf', label: 'Windsurf',
+      detect: j(home, '.codeium'),
+      global: { file: j(home, '.codeium', 'windsurf', 'memories', 'global_rules.md'), style: 'shared' },
+      project: { file: j(cwd, '.windsurf', 'rules', 'relay.md'), style: 'dedicated' } },
+    { id: 'cline', label: 'Cline',
+      detect: j(d.documents, 'Cline'),
+      global: { file: j(d.documents, 'Cline', 'Rules', 'relay.md'), style: 'dedicated' },
+      project: { file: j(cwd, '.clinerules', 'relay.md'), style: 'dedicated' } },
+    { id: 'gemini', label: 'Gemini CLI',
+      detect: j(home, '.gemini'),
+      global: { file: j(home, '.gemini', 'GEMINI.md'), style: 'shared' },
+      project: { file: j(cwd, 'GEMINI.md'), style: 'shared' } },
+  ];
+}
+
+// Render the relay rules in the style the target file expects.
+function renderInstruction(style) {
+  if (style === 'mdc') {
+    return `---\ndescription: relay — collect decisions & show rich visuals in the browser, not the terminal\nalwaysApply: true\n---\n\n${SKILL_RULES}\n`;
+  }
+  return `${SKILL_RULES}\n`; // dedicated file — relay owns it
+}
+
+// Upsert relay's marked block into a (possibly shared / pre-existing) file,
+// leaving everything outside the markers untouched. Returns 'added'|'updated'.
+function upsertBlock(file, body) {
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
+  const wrapped = `${RELAY_BEGIN}\n${body}\n${RELAY_END}`;
+  const re = new RegExp(escapeRegExp(RELAY_BEGIN) + '[\\s\\S]*?' + escapeRegExp(RELAY_END));
+  const had = re.test(existing);
+  const next = had
+    ? existing.replace(re, wrapped)
+    : (existing.trim() ? existing.replace(/\s*$/, '') + '\n\n' + wrapped + '\n' : wrapped + '\n');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return had ? 'updated' : 'added';
+}
+
+function writeInstruction(target) {
+  if (target.style === 'shared') return upsertBlock(target.file, SKILL_RULES);
+  const existed = fs.existsSync(target.file);
+  fs.mkdirSync(path.dirname(target.file), { recursive: true });
+  fs.writeFileSync(target.file, renderInstruction(target.style));
+  return existed ? 'updated' : 'added';
+}
+
+function cmdInstall(args) {
+  const reg = agentRegistry();
+  const byId = Object.fromEntries(reg.map((a) => [a.id, a]));
+  const scope = args.scope === 'project' ? 'project' : args.scope === 'global' ? 'global' : null;
+
+  // Pick the target for an agent: explicit --scope wins; else prefer global
+  // (machine-wide), falling back to project when the agent has no global file.
+  const pick = (a) => {
+    if (scope === 'project') return a.project ? { scope: 'project', t: a.project } : null;
+    if (scope === 'global') return a.global ? { scope: 'global', t: a.global } : null;
+    if (a.global) return { scope: 'global', t: a.global };
+    if (a.project) return { scope: 'project', t: a.project };
+    return null;
+  };
+
+  const wantAll = args.all === true || String(args.target || '').toLowerCase() === 'all';
+
+  // No target → show the matrix for THIS platform.
+  if (!wantAll && (args.list === true || !args.target)) {
+    printJson({
+      platform: process.platform,
+      agents: reg.map((a) => ({
+        agent: a.id, label: a.label,
+        global: a.global ? a.global.file : null,
+        project: a.project ? a.project.file : null,
+        note: a.note,
+      })),
+      usage: 'rly install --target <agent>[,<agent>] [--scope global|project] [--print] | rly install --all',
+    });
+    return 0;
+  }
+
+  // Resolve the set of {agent, scope, target} to act on.
+  let chosen;
+  if (wantAll) {
+    chosen = reg
+      .filter((a) => { try { return fs.existsSync(a.detect); } catch { return false; } })
+      .map((a) => ({ a, ...(pick(a) || {}) }))
+      .filter((x) => x.t);
+    if (!chosen.length) {
+      throw new CliError('no known agents detected on this machine (no ~/.claude, ~/.codex, ~/.cursor, ~/.kiro, …). Use --target <agent>.', 4);
+    }
+  } else {
+    const ids = String(args.target).split(',').map((s) => s.trim()).filter(Boolean);
+    chosen = [];
+    for (const id of ids) {
+      const a = byId[id];
+      if (!a) throw new CliError(`unknown agent "${id}". Run \`rly install --list\` to see supported agents.`, 4);
+      const p = pick(a);
+      if (!p) throw new CliError(`${a.label} has no ${scope || 'installable'} instruction file${a.note ? ` — ${a.note}` : ''}. Try \`--scope project\`.`, 4);
+      chosen.push({ a, ...p });
+    }
+  }
+
+  // --print: emit content + resolved path for manual copy/paste; no writes.
+  if (args.print === true) {
+    for (const { a, t } of chosen) {
+      const content = t.style === 'shared' ? `${RELAY_BEGIN}\n${SKILL_RULES}\n${RELAY_END}` : renderInstruction(t.style);
+      process.stdout.write(`# ${a.label}\n# → ${t.file}\n\n${content}\n\n`);
+    }
+    return 0;
+  }
+
+  const installed = chosen.map(({ a, scope: sc, t }) => ({
+    agent: a.id, scope: sc, file: t.file, action: writeInstruction(t),
+  }));
+  printJson({ installed, note: 'reload/re-open your agent (or re-list its rules) if it does not pick this up immediately' });
+  return 0;
+}
+
 function cmdAgent() {
   console.log(fs.readFileSync(path.join(PKG_ROOT, 'docs', 'AGENT.md'), 'utf8'));
   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`);
+    // shell:true so Windows resolves `npm` → `npm.cmd` (same reason the skill /
+    // version spawns below use it); the package name has no shell metacharacters.
+    const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@latest`], { stdio: 'inherit', shell: true });
+    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 +1105,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 +1143,11 @@ 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 install --target <agent>        inject relay's rules into an agent's instruction file
+                                      agents: claude codex cursor copilot kiro windsurf cline gemini agents
+                                      --scope global|project · --print (copy/paste) · --all · --list (no flags)
+  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 +1210,11 @@ export async function main(argv) {
         return cmdRm(parseArgs(rest));
       case 'skill':
         return cmdSkill(rest);
+      case 'install':
+        return cmdInstall(parseArgs(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
@@ -324,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;
@@ -355,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;
@@ -372,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.
@@ -498,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 || {});
@@ -533,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?.();
@@ -551,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

@@ -411,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.' },