@khanglvm/relay 0.10.0 → 0.10.2

package/README.md

@@ -35,7 +35,8 @@ That's it. Next time your agent needs a decision or wants to show you a plan,
 it opens a board like the ones above and waits for your Submit.
 
 Keep relay current with **`rly upgrade`** — it installs the latest CLI and
-refreshes the skill in one step, leaving any boards you have open untouched.
+refreshes the skill (via `npx skills`, falling back to the bundled copy) in one
+step, leaving any boards you have open untouched.
 
 ## What it improves
 

package/docs/AGENT.md

@@ -11,6 +11,22 @@ leave comments, and select text in markdown blocks to annotate — their comment
 come back in `result.annotations` alongside their answers. Treat annotations as
 first-class feedback.
 
+**Read ALL four feedback channels, not just `answers`.** A result carries the
+user's input across **four** places, each first-class — never act on `answers`
+alone:
+
+- `answers` — the per-question values (what they picked/typed).
+- `notes` — per-question free-text notes (`result.notes[questionId]`): the small
+  note box under a question, where users qualify or override a pick. **Single
+  (radio) questions show this box by default**, so it is a very common place for
+  the real reasoning to land. Easy to miss because empty notes are omitted —
+  **always inspect `result.notes`.**
+- `comment` — one board-level free-text note ("Anything else?").
+- `annotations` — element-level inline comments on specific blocks/data points.
+
+If any of `notes`, `comment`, or `annotations` is non-empty, it can override or
+contradict an `answers` value — reconcile them before generating output.
+
 Everything machine-relevant is on **stdout as JSON**; human-facing logs go to
 stderr. Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
 `4` usage error · `5` not found.
@@ -137,12 +153,18 @@ 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. **`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.
+
+`notes` (a `{ questionId: "text" }` map) is **always present** in a result —
+`{}` when empty — so you can never miss that the channel exists; iterate it
+even when you only expected `answers`. Questions with `"note": true` show a
+small optional free-text field, and only **non-empty** notes appear as keys.
+**`single` (radio) questions show this note by default** so the user can
+qualify or override their pick — set `"note": false` to hide it. A note like
+`notes.approach = "actually B, not A"` is the user's real intent and outranks
+the `answers.approach` radio value — always check `notes` before acting.
+
+On `timeout`/`cancelled`, a `draft` field carries the autosaved partial
+answers, notes, and any annotations written so far.
 
 ## Blocks
 
@@ -277,7 +299,10 @@ Rules of thumb:
 { "type": "html", "htmlFile": "viz.html",   "height": 400 }
 
 // Image — local file path (embedded at spec time, works offline), http(s) URL,
-// or data URI. "height" caps the displayed height; zoom/full-screen included.
+// or data URI. "height" sets only the COMPACT inline preview — every image keeps
+// a full-screen + zoom (⌘/Ctrl+wheel or −/+, up to 8× native) + drag-to-pan
+// viewer, so a small height never hides detail. Local images embed up to 8 MB;
+// for a huge / high-resolution image pass an http(s) URL (streamed, no size cap).
 { "type": "image", "src": "screenshots/variant-a.png", "alt": "Variant A", "height": 220 }
 { "type": "image", "src": "https://example.com/mock.png" }
 ```
@@ -314,7 +339,7 @@ real path over telling the user to paste it into a terminal.
 - `mermaid`: natural flow, max-height 1200 px with internal scroll. Override with `"height"`.
 - `chart`: default 320 px. Override with `"height"`.
 - `html`: default 360 px. Override with `"height"`.
-- `image`: natural size (never upscaled), max-height 1200 px with scroll. `"height"` caps it.
+- `image`: natural size (never upscaled), max-height 1200 px with scroll. `"height"` caps the **inline preview only** — full-screen + zoom (up to 8× native) always reach full detail. Local images embed up to 8 MB; use an http(s) URL for larger.
 - `table`: natural flow.
 - All heights clamp to 100–2400 px.
 - Inside OPTION cards, always set a compact `"height"` (~140–260) on
@@ -538,13 +563,23 @@ call rather than calling it repeatedly in a loop.
   check whether the user has started answering.
 - In the board `intro`, tell users they can hover chart points / select text to
   leave inline comments — they won't discover it otherwise.
-- Check `result.annotations` before generating your next output; a comment on a
-  specific data point or a quoted sentence often overrides the checkbox answer.
+- Check `result.notes` AND `result.annotations` before generating your next
+  output — not just `answers`. A per-question note (e.g. `notes.scope = "docs can
+  wait"`) or a comment on a specific data point / quoted sentence often qualifies
+  or overrides the checkbox answer. `notes` is always present (`{}` when empty),
+  so iterate it every time.
 - 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.
+- When the user asks to *see* code changes — "show me the diff", "show me git
+  diff", "review these changes" — capture `git diff` (or `git show <sha>`) and
+  render it in a `diff` block instead of printing it to the terminal; for a
+  brand-new file use a `code` block. Point them at a file to inspect with a
+  clickable local path in markdown.
 - 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 --skill relay --all`.
+  `rly upgrade` refreshes the CLI **and** the skill (via npx skills, falling back
+  to the bundled copy) in one step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, 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

@@ -1,6 +1,6 @@
 ---
 name: relay
-description: "The tool for collecting user requirements, decisions, and answers (choice, yes-no, text, scale questions) and for presenting prototypes, plans, structures, or reports with rich visuals - mermaid/graphviz/plantuml diagrams, charts, sortable tables, custom HTML - plus inline comments on any element. Opens a browser board, waits for Submit, returns JSON answers, comments, and edited diagrams. Use PROACTIVELY instead of (a) native ask-user tools for 2+ answers or options needing explanation, (b) ASCII trees/tables/diagrams in the terminal or prose descriptions of structures/designs/plans, (c) hand-rolled HTML demos. Triggers: collect requirements, ask the user, get decisions/feedback, present a prototype, plan approval, design review, show me the structure, repo/folder structure, file tree, codebase map, architecture overview, dependency graph, visualize, diagram, chart, data table, compare alternatives, survey, which do you prefer, let the user edit the diagram. Skip for a single trivial yes/no confirmation."
+description: "The tool for collecting user requirements, decisions, and answers (choice, yes-no, text, scale) and for presenting prototypes, plans, structures, code changes, or reports with rich visuals - mermaid/graphviz/plantuml diagrams, charts, tables, code, diffs, video, custom HTML, clickable file-links - plus inline comments on any element. Opens a browser board, waits for Submit, returns JSON answers, per-question notes, comments, and annotations. Use PROACTIVELY instead of (a) native ask-user tools for 2+ answers or options needing explanation, (b) ASCII trees/tables/diagrams in the terminal or prose for structures/designs/plans, (c) hand-rolled HTML demos. Triggers: collect requirements, ask the user, get decisions/feedback, present a prototype, plan/design review, show me the structure/file tree, architecture or dependency graph, visualize, diagram, chart, table, compare alternatives, survey, edit the diagram, show me the diff / git diff, video walkthrough, open a file. Skip for a single yes/no confirmation."
 ---
 
 # relay (`rly`)
@@ -28,6 +28,9 @@ Schema).** The essentials are below.
 | Present a prototype / demo an idea | **rly show** — never hand-roll an HTML file + server |
 | Gather requirements / plan approval / feedback round | **rly** |
 | Architecture or flow that benefits from a diagram | **rly** (mermaid block) |
+| "Show me the diff" / git diff / code changes / before-after | **rly** (`diff` block — run `git diff`, render it; never dump it in the terminal) |
+| A demo, screen recording or walkthrough | **rly** (`video` block) |
+| Point the user at a file to open (log, capture, report) | **rly** (a clickable local file-link in markdown) |
 | Something you can decide yourself from context | neither — just decide |
 
 Once the user has answered one board in a session, prefer boards for later
@@ -119,11 +122,25 @@ single/multi question.
 { "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": "code",     "lang": "js",  "code": "const x = 1;", "filename": "demo.js" }
+{ "type": "code",     "codeFile": "src/server.js" }   // load text from a local file
+{ "type": "diff",     "lang": "js",  "filename": "src/auth.js", "view": "split",
+  "diff": "@@ -1,3 +1,3 @@\n ctx\n-old line\n+new line\n ctx" }
+// ^ a unified / `git diff` text rendered as a colored, line-numbered comparison
+//   (no git needed — just paste the diff). "view":"split" = side-by-side; the
+//   viewer also has a live Unified⇄Split toggle. "diffFile" loads it from a file.
+{ "type": "video",    "src": "https://youtu.be/dQw4w9WgXcQ", "title": "Demo walkthrough" }
+{ "type": "video",    "src": "recordings/demo.mp4", "title": "Local capture", "height": 360 }
+// ^ YouTube/Vimeo URL embeds a player; an http(s) media URL or a local video
+//   file (mp4/webm/ogv/mov/mkv/m4v) plays inline (local files stream, not embedded).
 { "type": "html",     "html": "<p>hi</p>",           "height": 360 }
 { "type": "html",     "htmlFile": "viz.html",         "height": 400 }
 { "type": "image",    "src": "screenshot.png" }       // local file, URL, or data URI
 { "type": "image",    "src": "https://…/mock.png", "alt": "Mockup B", "height": 220 }
+// ^ `height` only sets the COMPACT inline preview — every image keeps a full-
+//   screen + zoom (⌘/Ctrl+wheel or −/+, up to 8× native) + drag-to-pan viewer,
+//   so detail is always reachable regardless of height. Local images embed up
+//   to 8 MB; for a huge/high-detail image pass an http(s) URL (streamed, no cap).
 ```
 
 ### Visual options — show each choice, don't describe it
@@ -154,6 +171,15 @@ 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.
 
+### Local file links — clickable, open in the default app
+
+Write a local path in any markdown (the `intro` or a `markdown` block) — `~/clip.mp4`,
+`./src/app.ts`, `/abs/report.pdf`, a `file://` URL, or a backtick-wrapped path — and it
+renders as a click-to-open link that opens the file in the user's OS default app
+(editor, video player, viewer …); `[label](~/path)` works too. Only paths you actually
+wrote on the board can be opened (same-origin + allowlist guarded). Surface a real
+clickable path instead of telling the user to paste it into a terminal.
+
 ## Annotations
 
 Users can hover chart points, diagram nodes (mermaid + graphviz), table cells,
@@ -181,6 +207,23 @@ mention annotation in the board intro.
 Read annotations before generating your next output — a comment on a specific
 data point often carries sharper signal than a checkbox answer.
 
+## Reading the result — four feedback channels
+
+A result is more than `answers`. **Always read all four** — never act on
+`answers` alone; the user's real intent often lives in the others:
+
+| field | what it is |
+|---|---|
+| `answers` | per-question values `{ questionId: value }` (skipped ones absent, listed in `skipped`) |
+| `notes` | **per-question free-text notes** `{ questionId: "text" }` — the note box under a question. **Always present (`{}` when empty)**; iterate it every time. `single` (radio) questions show this box by default, so it's a very common place for the user's reasoning — and easy to miss. |
+| `comment` | one board-level free-text note ("Anything else?") |
+| `annotations` | element-level inline comments (array; see below) |
+
+A `notes[questionId]`, a `comment`, or an `annotation` can qualify or override
+the matching `answers` value (e.g. `answers.approach = "a"` but
+`notes.approach = "actually B"` → the user means B). Reconcile them before
+generating output. The same channels appear under `draft` on timeout/cancel.
+
 ### Reply to annotations (agent → user conversation)
 
 ```sh
@@ -210,6 +253,14 @@ urgency, `textarea` for constraints.
 `html`/`image` block rendering that variant (see Visual options above); `scale`
 for confidence; `textarea` for what's missing from both.
 
+**Show a git diff / code changes** — when the user says "show me the diff" /
+"show me git diff" / "review these changes": capture `git diff` (or `git diff
+<ref>`, `git show <sha>`) and present it in a `diff` block — set `"view":
+"split"` for side-by-side — instead of dumping it in the terminal. Pair it with
+a `yesno` "Apply these changes?" and a `textarea` for feedback; users can select
+diff text to comment on a specific line. For a brand-new file prefer a `code` block; for a
+recorded walkthrough of the change add a `video` block.
+
 **Metrics review** — board-level `chart` block (bar or line) showing the key
 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

package/src/cli.js

@@ -773,6 +773,25 @@ function removeLegacySkills() {
   return removed;
 }
 
+// Stamps the current CLI version into every installed skill dir's .rly-version.
+// `rly skill install` writes this itself, but an `npx skills add` refresh does
+// not — so after any refresh we re-stamp the dirs that now have a SKILL.md,
+// keeping skillFreshnessWarning() from nagging about a just-refreshed skill.
+function stampSkillVersion() {
+  const stamped = [];
+  for (const dir of Object.values(KNOWN_SKILL_DIRS())) {
+    try {
+      if (fs.existsSync(path.join(dir, 'SKILL.md'))) {
+        fs.writeFileSync(path.join(dir, '.rly-version'), VERSION);
+        stamped.push(dir);
+      }
+    } catch {
+      // best effort — a marker we couldn't write just re-triggers the nudge
+    }
+  }
+  return stamped;
+}
+
 // Short instruction block for an agent's main instruction file (CLAUDE.md,
 // AGENTS.md, …). A skill is only a tier-1 hint that agents can ignore; these
 // rules, appended to the instructions the agent always reads, enforce usage.
@@ -783,8 +802,12 @@ const SKILL_RULES = `## relay — ask & show in the browser, not the terminal
   beyond one trivial yes/no)? Do NOT ask in plain terminal text. Build a board
   spec and run: \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`.
 - Presenting a plan, structure, architecture, data, or a prototype? Show a
-  relay board with mermaid/graphviz/chart/table/image/html blocks — never
-  ASCII diagrams or walls of prose.
+  relay board with mermaid/graphviz/chart/table/code/diff/video/image/html
+  blocks — never ASCII diagrams or walls of prose.
+- "Show me the diff / git diff / these changes"? Run \`git diff\` (or \`git show\`)
+  and render the output in a \`diff\` block — never paste a raw diff in the
+  terminal. Point the user at a file with a clickable local path in a markdown
+  block, and embed a screen recording with a \`video\` block.
 - When answer choices are visual (designs, layouts, variants), give each
   option its own visual (\`options[].blocks\`) so the user picks by looking.
 - Read the result JSON from stdout; treat \`comment\` and \`annotations\` as
@@ -1031,8 +1054,9 @@ 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
+// `rly upgrade` — install the latest CLI globally AND refresh the skill (via the
+// npx-skills package manager, falling back to the bundled copy) 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
@@ -1051,7 +1075,7 @@ async function cmdUpgrade(args) {
   if (args.dryRun === true) {
     printJson({
       dryRun: true,
-      wouldRun: [wantCli && `npm install -g ${PKG_NAME}@latest`, wantSkill && 'rly skill install'].filter(Boolean),
+      wouldRun: [wantCli && `npm install -g ${PKG_NAME}@latest`, wantSkill && 'npx skills add khanglvm/relay --skill relay --all'].filter(Boolean),
       runningBoards: running.map((r) => r.id),
       runningHandling: running.length
         ? doStop
@@ -1108,17 +1132,30 @@ async function cmdUpgrade(args) {
   }
 
   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 });
+    // Refresh the skill through the npx-skills package manager — the same channel
+    // the skill is normally managed by (skills-lock.json, ~/.agents, ~/.claude, …)
+    // — so the global install stays in sync and pulls the freshest skill for
+    // khanglvm/relay. `npx -y` so the one-off download needs no prompt.
+    process.stderr.write('\nRefreshing the relay skill  (npx skills add khanglvm/relay --skill relay --all)\n');
+    let r = spawnSync('npx', ['-y', 'skills', 'add', 'khanglvm/relay', '--skill', 'relay', '--all'], { stdio: 'inherit', shell: true });
+    let how = 'npx-skills';
+    if (r.error || r.status !== 0) {
+      // Fallback: install the skill bundled with the CLI we just upgraded. Works
+      // offline / when the skills CLI is unreachable, and matches this version.
+      process.stderr.write('\nnpx skills unavailable — falling back to the bundled skill  (rly skill install)\n');
+      r = spawnSync('rly', ['skill', 'install'], { stdio: 'inherit', shell: true });
+      how = 'bundled';
+    }
     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'
+          'run `npx skills add khanglvm/relay --skill relay --all` (or `rly skill install`) yourself.\n'
       );
     } else {
-      did.skill = 'installed';
+      // Keep the freshness marker accurate however the skill landed, so the next
+      // `rly` run doesn't nag that the just-refreshed skill is stale.
+      stampSkillVersion();
+      did.skill = how;
     }
   }
 

package/src/server.js

@@ -740,7 +740,11 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       answers: partial.answers ?? null,
       skipped: partial.skipped ?? null,
       comment: partial.comment ?? '',
-      notes: partial.notes ?? null,
+      // Per-question notes are first-class feedback. Always emit the key (even
+      // empty {}) so a consumer can SEE it exists and never silently misses a
+      // note the user left under a question. Falls back to the autosaved draft
+      // on timeout/cancel.
+      notes: partial.notes ?? (record.draft?.notes || {}),
       annotations: partial.annotations ?? (record.draft?.annotations || []),
       blockEdits,
       createdAt: record.createdAt,

package/src/ui/blocks.css

@@ -440,6 +440,10 @@
   object-fit: contain;
   object-position: left top;
 }
+/* In full-screen a per-block height must never keep the image small — that
+   height only shapes the inline preview; the detail view needs every pixel.
+   (Belt-and-suspenders alongside the viewer's reapply() on full-screen toggle.) */
+.blk-imagewrap.blk-full .blk-img { max-height: none !important; }
 
 /* ---------- viewer controls (full-screen) ---------- */
 /* The full-screen button lives in a reserved strip ABOVE the visual (user

package/src/ui/blocks.js

@@ -1398,7 +1398,10 @@
       alt: block.alt || 'image',
       loading: 'lazy',
     });
-    if (block.height) img.style.maxHeight = clampHeight(block.height, 360) + 'px';
+    // The per-block height only caps the COMPACT inline preview — the viewer
+    // lifts it on zoom / full-screen so the user can always reach full detail.
+    const fitMaxHeight = block.height ? clampHeight(block.height, 360) : null;
+    if (fitMaxHeight) img.style.maxHeight = fitMaxHeight + 'px';
     img.addEventListener('error', () => {
       container.replaceChildren(el('div', { class: 'blk-error' }, 'Image failed to load'));
     });
@@ -1409,6 +1412,7 @@
         natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
         label: 'image',
         comment: wholeBlockComment(ctx, blockId, 'image'),
+        fitMaxHeight,
       });
     if (img.complete && img.naturalWidth > 0) attachImgViewer();
     else img.addEventListener('load', attachImgViewer, { once: true });
@@ -1450,6 +1454,7 @@
     fullOpen = null;
     window.dispatchEvent(new Event('resize'));
     if (c._rlyToolsSync) c._rlyToolsSync(); // re-pin toolbar to its scrolled corner
+    if (c._rlyZoom) c._rlyZoom.reapply(); // restore the compact inline height cap
   }
   document.addEventListener('keydown', (e) => {
     if (e.key === 'Escape' && fullOpen) exitFull();
@@ -1569,6 +1574,13 @@
       const target = opts.zoomEl;
       const nat = opts.natural();
       const z = container._rlyZ;
+      // A per-block height caps only the compact inline preview. The moment the
+      // user zooms in (z !== null) or goes full-screen they want pixel detail, so
+      // lift the cap there; restore it when back to the inline fit view.
+      if (opts.fitMaxHeight != null) {
+        const fit = z === null && !container.classList.contains('blk-full');
+        target.style.maxHeight = fit ? opts.fitMaxHeight + 'px' : 'none';
+      }
       if (z === null || !nat || !nat.w) {
         target.style.width = '100%';
         target.style.maxWidth = nat && nat.w ? Math.ceil(nat.w) + 'px' : '100%';
@@ -1592,10 +1604,10 @@
       return shown > 0 ? shown / nat.w : 1;
     }
     function setZoom(next) {
-      container._rlyZ = next === null ? null : Math.min(5, Math.max(0.2, next));
+      container._rlyZ = next === null ? null : Math.min(8, Math.max(0.2, next));
       apply();
     }
-    container._rlyZoom = { setZoom, currentZ };
+    container._rlyZoom = { setZoom, currentZ, reapply: apply };
 
     const tools = el('div', { class: 'blk-tools' });
 
@@ -1652,6 +1664,7 @@
       fullBtn.textContent = '✕';
       window.dispatchEvent(new Event('resize'));
       container._rlyToolsSync();
+      if (container._rlyZoom) container._rlyZoom.reapply(); // lift any inline height cap
     });
     tools.append(fullBtn);