@khanglvm/relay 0.12.3 → 0.13.0

package/README.md

@@ -87,6 +87,7 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 | | |
 |---|---|
 | `rly help` | every command at a glance |
+| `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s) — library-free; great for plans, READMEs, reports |
 | `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
 | `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
 | `rly mcp` | run relay as an MCP App server so boards render **inline** in the chat — **stdio** for local desktop hosts (Claude Desktop, Codex), or `rly mcp --http` (Streamable HTTP) for web/mobile/remote; `rly mcp config` / `rly mcp install --target claude\|codex` to register it |

package/docs/AGENT.md

@@ -5,6 +5,15 @@ rich content blocks (markdown, charts, diagrams, tables, code, custom HTML),
 then **wait for them to click Submit** and read the answers as JSON from stdout.
 No "type 'done' in the terminal", no hand-rolled HTML+server.
 
+**Match the surface to the content.** You run inside a terminal, an IDE side-panel
+(VS Code / JetBrains / Cursor), or a plain-text chat — none of which can render a
+markdown file, an image, a chart, a table, a diagram, or a diff. They degrade to
+walls of monospace text, or can't show it at all (a terminal can't draw a PNG).
+relay renders it in a real browser board. So whenever your output would read better
+than monospace — or is a file/visual the user should look at — show it in relay
+instead of printing it. Fast paths: `rly view file.md` (or `data.csv`), `rly diff`,
+or an `image`/`chart`/`table` block on a board.
+
 **Use relay even in plan mode** — for any clarifying or decision question (Claude
 Code / Codex), route it through a relay board, **not** the native
 `AskUserQuestion` / ask-user tool: that tool is **not** a substitute, even though
@@ -135,6 +144,21 @@ Visualization-only (no questions; submit button reads "Acknowledge"):
 rly show --html-file prototype.html --title "Dashboard concept" --height 600
 ```
 
+Read a markdown file (no questions; library-free renderer; submit reads "Done"):
+
+```sh
+rly view PLAN.md                      # one file
+rly view README.md CHANGELOG.md       # several, each under a filename heading
+rly view data.csv                     # .csv/.tsv/.json → a sortable, filterable table
+```
+
+Show a git diff in one step (sugar — runs git diff, opens a diff board):
+
+```sh
+rly diff --detach                     # working-tree diff (git args pass through:
+rly diff --staged --split             #   --staged, HEAD~1, -- path, …); --split = side-by-side
+```
+
 ## Board spec (JSON)
 
 ```jsonc
@@ -188,11 +212,27 @@ rly show --html-file prototype.html --title "Dashboard concept" --height 600
 | `text`     | `"string"`                          |
 | `textarea` | `"string"`                          |
 | `scale`    | number (`min`…`max`, default 1–5)   |
-| `color`    | hex string (e.g. `"#c2674b"`) — native picker + hex field; optional `presets:["#…"]` swatches |
+| `color`    | color string (e.g. `"#c2674b"`, `"rgb(...)"`, a name) — native picker + hex field; optional `presets:["#…"]` small swatches, or a `palette:[…]` of labeled swatch CARDS (click = answer, each card commentable, any CSS color system) |
+| `rank`     | `["b","a","c"]` — ordered option values, highest priority first |
+| `checklist`| `{ "login":"pass", "checkout":"fail" }` — per-item status map |
+| `allocate` | `{ "eng":50, "design":30, "ops":20 }` — budget distributed across options |
+
+`rank` renders the `options` as a reorderable list (drag or ↑/↓ buttons); the
+user prioritizes them and the answer is the ordered array of values. Needs ≥2
+options, takes no "Other", and **always returns a value** (an untouched rank
+submits the authored order), so it never appears in `skipped`. Reach for it on
+roadmap / feature-prioritization questions instead of forcing a single pick.
+
+`checklist` gives each `option` a status control (default Pass / Fail / N·A;
+override with `"statuses"`); answer is `{optionValue: statusValue}`. `allocate`
+distributes a budget (`"total"`, default 100) across the options with sliders +
+a live total bar; answer is `{optionValue: number}`. Both take per-option
+`description`/`blocks` like single/multi.
 
 Aliases accepted: radio/choice/select→single, checkbox→multi,
 boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scale,
-colour/swatch→color.
+colour/swatch→color, ranking/order/ordering/prioritize/sort→rank,
+signoff/qa→checklist, budget/distribute/points→allocate.
 
 ### Result JSON (stdout)
 
@@ -279,11 +319,14 @@ Rules of thumb:
 
 ```jsonc
 // 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.
+// links, images, 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." }
+// Load the body from a local .md file instead of inlining it (README, plan, report).
+// Quick view of whole file(s) with no questions: `rly view file.md [more.md …]`.
+{ "type": "markdown", "mdFile": "README.md" }
 
-// Mermaid diagram — vendored, lazy-loaded; natural height, max 1200 px + scroll
+// Mermaid diagram — vendored, lazy-loaded; natural height, max 800 px + scroll (set height: to override)
 { "type": "mermaid", "code": "graph TD; A-->B; B-->C", "height": 400 }
 
 // Graphviz diagram — vendored viz-standalone.js (Graphviz-WASM), fully offline
@@ -397,6 +440,23 @@ real path over telling the user to paste it into a terminal.
 
 ### When to use which block
 
+**Reach for the most specific component — never default to prose.** relay has a
+purpose-built block/question type for most content; falling back to a `markdown`
+block (or terminal text) when a dedicated one fits is the #1 way agents
+under-use relay. A metric → `kpi`, a before/after → `compare`, a priority call →
+a `rank` question. When unsure what exists, consult this table, `rly schema`, and
+the question-types section above.
+
+**By domain** (serve the reader the right shape):
+- **Business / PM / exec** — `kpi` + `chart` + `table` for numbers; `rank`
+  (prioritize), `allocate` (split a budget), `checklist` (sign-off), `scale` (confidence).
+- **Designer** — `image` (+`pins`), `compare` (before/after), `palette`, `typography`;
+  a visual inside each option.
+- **Engineer** — `diff` (`rly diff`), `code` (line-comments), `mermaid`/`graphviz`
+  (architecture; editable mermaid to co-design).
+- **Data / analyst** — `table` with `rowsFile`/`filterable`/`exportable`
+  (`rly view data.csv`), `chart`.
+
 | Block | Best for |
 |---|---|
 | `mermaid` | flows, state machines, architecture overviews, sequence diagrams |
@@ -404,14 +464,23 @@ real path over telling the user to paste it into a terminal.
 | `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 — **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) |
+| `markdown` | prose context, background, instructions, section headings (renders GFM pipe tables + images too, but reach for a `table` block for real data); load a whole `.md` file with `mdFile` — or `rly view file.md` for a quick read-only board |
 | `code` | code snippets, config examples, command output — syntax-highlighted + line-numbered; load from a file with `codeFile` |
 | `diff` | proposed code changes / before-after — a unified diff rendered as a colored git-style comparison (no git needed) |
 | `video` | demos, screen recordings, walkthroughs — YouTube/Vimeo embeds, a media URL, or a local video file (streamed) |
 | `image` | screenshots, mockup exports, photos — local files embed and work offline |
 | `palette` | color palettes / themes — swatch cards with hover-hex + click-to-copy; pair with a `color` question to let the user pick |
+| `kpi` | big-number metric cards (`items:[{label,value,delta?,dir?,sub?}]`) with up/down/flat-tinted deltas — at-a-glance numbers without a chart |
+| `typography` | type specimens (`specimens:[{label?,size?,weight?,font?,text?}]`) — react to type choices like a palette |
+| `compare` | before/after images with a draggable divider (`before`/`after` = url/path/`{src,label}`) — redesigns, before-after fixes |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 
+Two cross-block fields work on **any** block: `"ref":"name"` makes it openable in
+a modal via a markdown `[label](#ref:name)` link (point a question at a visual
+shown earlier — no scrolling); `image` blocks also take `"pins":true` for
+click-to-drop coordinate pin-comments. `table` blocks take `"rowsFile"` (load
+rows from .csv/.tsv/.json), `"filterable"`, and `"exportable"` (CSV download).
+
 ### Height rules
 
 - `markdown`, `code`: natural flow (no fixed height).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "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, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "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) 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."
+description: "Collect user decisions & answers — choice, multi, yes-no, text, scale, rank (prioritize), checklist (sign-off), allocate (split a budget), color — and present plans, data, code, or designs with blocks: diagrams (mermaid/graphviz/plantuml), charts, KPI cards, tables (sortable/filterable/CSV, load .csv/.json), code, multi-file diffs, before/after compare, typography, palettes, video, images (click-to-pin), HTML — plus inline element comments and links that open a visual in a modal. Opens a browser board (or inline in Claude/Codex), returns JSON answers/notes/comments/annotations on Submit. Use PROACTIVELY over native ask tools (2+ answers), ASCII/prose for structures/metrics/designs, or printing a file/image/chart/diff the terminal can't render. A dedicated component exists for most content — use the most specific, don't fall back to prose. Triggers: ask the user, decisions, prioritize, sign-off, allocate, plan review, chart, metrics, table, view a CSV, before/after, git diff, markdown file. Skip single yes/no."
 ---
 
 # relay (`rly`)
@@ -25,9 +25,19 @@ Schema).** The essentials are below.
 
 ## When to use rly vs your native question tool
 
+**The core principle — match the surface to the content.** You run inside a
+terminal, an IDE side-panel (VS Code / JetBrains / Cursor), or a plain-text chat.
+None of those can actually render a markdown file, an image, a chart, a table, a
+diagram, or a diff — they degrade to walls of monospace text, or can't show it at
+all (a terminal can't draw a PNG). relay opens a real browser board that renders it
+properly and reads the user's reply back as JSON. **So whenever what you're about to
+output would read better than monospace — or is a file/visual the user should look
+at — show it in a relay board instead of printing it.**
+
 | Situation | Use |
 |---|---|
 | One trivial confirmation ("proceed?") | native tool |
+| Show an image / screenshot / mockup / rendered output | **rly** (`image` block — the terminal can't display pixels) |
 | 2+ questions, or options that need descriptions | **rly** |
 | Choice is easier to make visually (layouts, designs, diagrams) | **rly** (blocks per question) |
 | Each OPTION has its own visual (design variants, screenshots, charts) | **rly** (blocks per option) |
@@ -38,6 +48,7 @@ Schema).** The essentials are below.
 | "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) |
+| Let the user read a markdown file (README, plan, report) | **rly view file.md** (or a `markdown` block with `mdFile`) — never dump the file into the terminal |
 | Plan-mode clarifying question (Claude Code / Codex) | **rly** (not AskUserQuestion / the native ask tool) |
 | Something you can decide yourself from context | neither — just decide |
 
@@ -51,6 +62,64 @@ Once the user has answered one board in a session, prefer boards for later
 question rounds too — they've shown they engage with them. Batch related
 questions into ONE board rather than opening several in a row.
 
+## The full toolbox — reach for the MOST SPECIFIC component
+
+relay ships a purpose-built component for most kinds of content. **Before you
+build a board, scan this list and pick the most specific component that fits — do
+NOT fall back to a plain `markdown`/prose block (or the terminal) when a dedicated
+one renders it better.** A KPI belongs in `kpi`, a before/after in `compare`, a
+priority call in a `rank` question — not in paragraphs. Unsure which exists? Run
+`rly agent` (full guide) and `rly schema` (every field).
+
+**Blocks** — add under `"blocks": [...]` at the board, a question, or an option:
+
+| Block | Reach for it when you have… |
+|---|---|
+| `table` | tabular data — sortable, per-cell comments; `rowsFile` (.csv/.json), `filterable`, `exportable` |
+| `chart` | numbers / trends / comparisons (bar·line·pie·doughnut·radar·scatter) |
+| `kpi` | headline metrics — big-number cards with ↑/↓/flat deltas (no chart needed) |
+| `mermaid` | flows, sequences, state machines, architecture (set `editable:true` to co-edit) |
+| `graphviz` | precise dependency / call graphs |
+| `plantuml` | UML (sequence / class / component) |
+| `code` | source / config / command output — highlighted, line numbers, hover-a-line to comment |
+| `diff` | code changes — colored unified/split, multi-file (`rly diff` builds the whole board) |
+| `image` | screenshots / mockups / renders — zoom+pan; `pins:true` → click-to-drop point comments |
+| `compare` | a before/after pair — draggable divider |
+| `video` | a demo / screen recording / walkthrough |
+| `palette` | color schemes — swatch cards, hover-hex, click-to-copy |
+| `typography` | type choices — specimens at given size/weight/font |
+| `html` | anything bespoke — custom widgets, pixel-perfect mockups |
+| `markdown` | prose / context ONLY (not data, metrics, or visuals — those have their own block) |
+
+Any block also takes `"ref":"name"` → a question can link to it with
+`[label](#ref:name)` and it opens **in a full-screen modal**, so the user views the
+data without scrolling back up.
+
+**Question types** — pick by the shape of the answer you need:
+
+| Type | Reach for it when you need… | Answer JSON |
+|---|---|---|
+| `single` | one choice (radio; "Other" + a note are on by default) | `"value"` |
+| `multi` | several choices | `["a","b"]` |
+| `rank` | a **priority order** over options (roadmap, triage) | `["b","a","c"]` |
+| `allocate` | a **budget split** across options (tradeoffs, %, points) | `{opt: number}` |
+| `checklist` | **per-item sign-off / QA** (Pass·Fail·N·A, or custom) | `{opt: status}` |
+| `scale` | a rating on a 1–N scale | number |
+| `yesno` | a binary decision | `"yes"`/`"no"` |
+| `color` | a color pick — native picker + presets, or a `palette` of labeled swatch cards (each commentable); any CSS color system | color string |
+| `text` / `textarea` | short / long free text | string |
+
+**By who you're serving** (don't make a business user read a wall of prose):
+
+- **Business / PM / exec** → `kpi` + `chart` + `table` for the numbers; `rank` to
+  prioritize, `allocate` for tradeoffs, `checklist` for sign-off, `scale` for confidence.
+- **Designer** → `image` (+`pins` for point feedback), `compare` (before/after),
+  `palette`, `typography`; put a visual INSIDE each option so they pick by looking.
+- **Engineer** → `diff` (`rly diff`), `code` (line-comments), `mermaid`/`graphviz`
+  for architecture, editable mermaid to co-design.
+- **Data / analyst** → `table` with `rowsFile`/`filterable`/`exportable`
+  (`rly view data.csv`), `chart` for the shape of it.
+
 ## Choose a pattern
 
 **DEFAULT: detached.** Most agent shell tools kill long-running commands, and a
@@ -105,10 +174,49 @@ answers and any annotations written so far.
 ```
 
 Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`, `color`
-(native picker + hex; optional `"presets":["#…"]`, returns a hex string). Users
-may submit with unanswered questions (returned in `skipped`) unless
+(native picker + hex; optional `"presets":["#…"]` or a `"palette"` of labeled,
+commentable swatch cards — any CSS color system), `rank`, `checklist`, `allocate`.
+Users may submit with unanswered questions (returned in `skipped`) unless
 `"allowPartial": false` or per-question `"required": true`.
 
+```jsonc
+{ "id": "brand", "type": "color", "label": "Pick a brand color",
+  "palette": [{ "value": "#c2674b", "label": "Terracotta" }, { "value": "rgb(77,138,102)", "label": "Forest" }, "rebeccapurple"] }
+// clicking a swatch = the answer; hover a swatch to comment on that specific color.
+```
+
+The optional per-question note box (`result.notes[id]`) defaults ON for the
+**decision types** — `single`, `rank`, `checklist`, `allocate` — so the user can
+qualify a pick; `"note": false` hides it, `"note": true` adds it to other types.
+
+`rank` — the user drags (or uses ↑/↓) to order the `options` by priority; the
+answer is the **ordered array of option values**, highest first. Needs ≥2
+options; always returns a value (an untouched rank submits the authored order),
+so it's never `skipped`. Use for roadmap/feature prioritization instead of a
+single pick. Options take `description` and per-option `blocks` like single/multi.
+
+```json
+{ "id": "roadmap", "type": "rank", "label": "Order these by priority",
+  "options": [{ "value": "diff", "label": "rly diff", "description": "git diff → board" }, "rank type", "image pins"] }
+```
+
+`checklist` — each `option` gets a per-item status (default **Pass / Fail / N·A**;
+override with `"statuses"`). Answer is a map `{optionValue: statusValue}`. For QA
+passes and sign-off gates.
+
+```json
+{ "id": "qa", "type": "checklist", "label": "Release sign-off", "options": ["login","search","checkout"] }
+```
+
+`allocate` — the user distributes a budget (`"total"`, default 100) across the
+`options` with sliders + a live running-total bar. Answer is a map
+`{optionValue: number}`. Captures intensity/tradeoffs, not just a pick.
+
+```json
+{ "id": "spend", "type": "allocate", "label": "Split the quarter", "total": 100, "unit": "pts",
+  "options": ["features","tech debt","infra"] }
+```
+
 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]`. `single` (radio) questions include this note by
@@ -127,6 +235,7 @@ single/multi question.
 
 ```jsonc
 { "type": "markdown", "md": "## Section\n**prose**" }
+{ "type": "markdown", "mdFile": "README.md" }   // render a local .md file (no lib)
 { "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 }
@@ -137,6 +246,19 @@ 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": "table",    "rowsFile": "data.csv", "filterable": true, "exportable": true }
+// ^ load rows from a local .csv/.tsv/.json; filterable = live filter box,
+//   exportable = CSV download. (`rly view data.csv` does all of this for you.)
+{ "type": "kpi",      "title": "This quarter", "items": [
+  { "label": "Revenue", "value": "$1.2M", "delta": "12%", "dir": "up" },
+  { "label": "Churn",   "value": "2.1%",  "delta": "0.4pp", "dir": "down", "sub": "lower=better" } ] }
+// ^ big-number metric cards with up/down/flat-tinted deltas — no chart needed.
+{ "type": "typography", "font": "Georgia, serif", "specimens": [
+  { "label": "Display", "size": "40px", "weight": "600", "text": "Ship faster" },
+  { "label": "Body",    "size": "16px", "text": "The quick brown fox…" } ] }
+// ^ type specimens at given size/weight/font — react to type like a palette.
+{ "type": "compare",  "before": "v1.png", "after": "v2.png", "beforeLabel": "Old", "afterLabel": "New" }
+// ^ before/after images with a draggable divider (redesign / before-after fix).
 { "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",
@@ -160,6 +282,23 @@ single/multi question.
 // ^ color palettes as swatch cards: hover=hex, click=copy. Shorthand {"type":"palette","colors":[…]}; pair with a `color` question.
 ```
 
+### View a markdown file quickly
+
+To let the user *read* a `.md` file (README, a plan you wrote, a generated
+report), don't paste it into the terminal — render it:
+
+```sh
+rly view PLAN.md                 # one file → board titled "PLAN.md", "Done" button
+rly view README.md CHANGELOG.md  # several files, each with a filename heading
+rly view docs/spec.md --detach   # detached like ask/show; then `rly wait <id>`
+```
+
+`rly view` is sugar over `rly show` with `markdown` blocks (`mdFile`). The
+built-in renderer is library-free and covers headings, lists, `**/_` emphasis,
+code, quotes, GFM pipe tables, remote/data images, and click-to-open local
+links. To mix a file into a larger board, use a `markdown` block with
+`"mdFile"` alongside questions or other blocks.
+
 ### Visual options — show each choice, don't describe it
 
 When the options themselves are visual (design variants, layouts, color
@@ -197,6 +336,43 @@ renders as a click-to-open link that opens the file in the user's OS default app
 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.
 
+### Connect a question to a visual shown above (reference modal)
+
+When a board has visuals up top and questions below, the user loses the link
+between them. Give any block a stable `"ref"` name, then reference it from a
+markdown link — clicking it opens that visual in a full-screen modal **in place**,
+no scrolling:
+
+```jsonc
+{ "type": "chart", "ref": "velocity", "kind": "line", "labels": [...], "series": [...] }
+// then in the intro, a markdown block, or a question's own markdown block:
+{ "type": "markdown", "md": "Decide from the [📈 Velocity](#ref:velocity) chart above." }
+```
+
+`[label](#ref:name)` opens the block named `name`; `[label](#block:b2)` opens by
+id. Use it so every question that depends on data points right at it.
+
+### Pin comments on a mockup (image coordinates)
+
+Add `"pins": true` to an `image` block: the user clicks any point on the image to
+drop a comment anchored to that exact spot (Figma-style), returned as an
+`{kind:"image-point", x, y}` annotation. Ideal for design/mockup review.
+
+### Show a git diff in one step — `rly diff`
+
+`rly diff [git args…]` runs `git diff` and opens the result as a diff board —
+sugar for the "show me the diff" flow. Git args/flags pass straight through; a
+multi-file diff renders with a per-file header + a jump bar.
+
+```sh
+rly diff --detach              # working-tree diff
+rly diff --staged --split      # staged changes, side-by-side
+rly diff HEAD~1 HEAD -- src/   # a commit's diff, scoped to a path
+```
+
+`code` blocks also support **line-anchored comments**: hover a line number to
+comment on that exact line (returned as `{kind:"code-line", line}`).
+
 ## Annotations
 
 Users can hover chart points, diagram nodes (mermaid + graphviz), table cells,
@@ -213,7 +389,7 @@ mention annotation in the board intro.
   "id": "a1",
   "questionId": "q-id or null",
   "blockId": "b2",
-  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image", "..." },
+  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image | image-point | code-line", "..." },
   "text": "user comment",
   "author": "user",
   "createdAt": "ISO",

package/src/cli.js

@@ -236,6 +236,61 @@ async function cmdAsk(args, mode) {
   return runOrDetach(record, args);
 }
 
+// `rly diff [git args…]` — run `git diff` for the user and open the result as a
+// diff-block board in one step (sugar like `rly view`). Everything that isn't a
+// recognized rly flag is forwarded to git verbatim, so `rly diff --staged`,
+// `rly diff HEAD~1`, `rly diff main -- src/` all work. rly flags: --detach,
+// --no-open, --split (side-by-side), --title.
+async function cmdDiff(rest) {
+  const RLY_FLAGS = new Set(['--detach', '--no-open', '--split']);
+  const gitArgs = [];
+  const rlyArgv = [];
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i];
+    if (t === '--title') { rlyArgv.push(t, rest[++i]); continue; }
+    if (t.startsWith('--title=')) { rlyArgv.push(t); continue; }
+    if (RLY_FLAGS.has(t)) { rlyArgv.push(t); continue; }
+    gitArgs.push(t);
+  }
+  const args = parseArgs(rlyArgv);
+  const res = spawnSync('git', ['--no-pager', 'diff', ...gitArgs], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (res.error) throw new CliError(`could not run git: ${res.error.message}. Is git installed and is this a repo?`);
+  if (res.status !== 0 && res.stderr) throw new CliError(`git diff failed: ${res.stderr.trim()}`, res.status || 1);
+  const diff = res.stdout || '';
+  if (!diff.trim()) {
+    printJson({ status: 'no-diff', hint: `git diff${gitArgs.length ? ' ' + gitArgs.join(' ') : ''} produced no output — nothing to show` });
+    return 0;
+  }
+  const title = args.title || ('git diff' + (gitArgs.length ? ' ' + gitArgs.join(' ') : ''));
+  const spec = normalizeSpec({ title, blocks: [{ type: 'diff', diff, view: args.split ? 'split' : 'unified' }] });
+  const record = createBoard(spec);
+  return runOrDetach(record, args);
+}
+
+// `rly view <file.md> [more.md …]` — quick read-only board that renders one or
+// more markdown files (README, plan, report) with the built-in no-library
+// renderer. Each file becomes a markdown block; with 2+ files a small filename
+// heading separates them. Sugar over `rly show` with markdown mdFile blocks.
+async function cmdView(args) {
+  const files = args._;
+  if (!files.length) throw new CliError('usage: rly view <file.md|.csv|.json> [more …] [--title T] [--detach]');
+  const multi = files.length > 1;
+  const DATA_EXT = new Set(['csv', 'tsv', 'json']);
+  const blocks = [];
+  for (const f of files) {
+    if (multi) blocks.push({ type: 'markdown', md: `## ${path.basename(f)}` });
+    const ext = path.extname(f).slice(1).toLowerCase();
+    if (DATA_EXT.has(ext)) blocks.push({ type: 'table', rowsFile: f, sortable: true, filterable: true, exportable: true });
+    else blocks.push({ type: 'markdown', mdFile: f });
+  }
+  const raw = { blocks };
+  raw.title = args.title || (multi ? `${files.length} files` : path.basename(files[0]));
+  raw.submitLabel = args.submitLabel || 'Done';
+  const spec = normalizeSpec(raw); // reads + validates each file, clear error if unreadable
+  const record = createBoard(spec);
+  return runOrDetach(record, args);
+}
+
 // Seeds the draft from the last result (as runBoard would on reopen) and
 // appends agent replies to the matching annotations, so an agent can ANSWER
 // the user's element comments and re-open the board as a conversation.
@@ -798,24 +853,42 @@ function stampSkillVersion() {
 // 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.
 // Printed to stdout so `rly skill rules >> CLAUDE.md` is the whole install.
-const SKILL_RULES = `## relay — ask & show in the browser, not the terminal
-
-- Need the user's decisions, feedback, requirements, or approval (anything
-  beyond one trivial yes/no)? Do NOT ask in plain terminal text **and do NOT use
-  the native \`AskUserQuestion\` / ask-user tool** — for anything beyond one
-  trivial yes/no, open a relay board. Build a board spec and run:
-  \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`. **This holds
-  in plan mode too** — route clarifying/decision questions through relay there as
-  well; reserve \`ExitPlanMode\` for the final plan-approval gate only.
-- Presenting a plan, structure, architecture, data, or a prototype? Show a
-  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
+const SKILL_RULES = `## relay — show it in the browser, don't dump it in the terminal
+
+**Why:** your output surface — a terminal, an IDE side-panel (VS Code, JetBrains,
+Cursor), a plain-text chat — can't actually render a markdown file, an image, a
+chart, a table, a diagram, or a diff. It shows them as walls of monospace text, or
+not at all (a terminal can't display a PNG). relay opens a real browser board that
+renders them properly AND reads the user's reply back as JSON. **Rule of thumb: if
+what you're about to output would look better than monospace text — or is a file
+the user should view — put it in relay instead of printing it.**
+
+- **Markdown file / doc / README / plan / report** → \`rly view file.md\` (renders it
+  in the browser, no library; \`.csv\`/\`.json\` → a sortable table). Never \`cat\` a
+  doc into the terminal for the user to read.
+- **Image / screenshot / mockup / diagram / chart / table** → a relay board with an
+  \`image\` block (or \`mermaid\`/\`graphviz\`/\`chart\`/\`table\`/\`kpi\`/\`compare\`). The
+  terminal can't show pixels; relay can — with click-to-zoom and comment-in-place.
+- **The user's decisions, feedback, requirements, or approval** (anything beyond one
+  trivial yes/no) → a relay board, NOT plain terminal text and NOT the native
+  \`AskUserQuestion\` / ask-user tool. Build a spec and run
+  \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`. **Holds in plan
+  mode too**; reserve \`ExitPlanMode\` for the final plan-approval gate only.
+- **A plan, structure, architecture, data, or prototype** → a relay board with
+  diagram/chart/table/code/image/html blocks — never ASCII diagrams or walls of prose.
+- **"Show me the diff / git diff / these changes"** → \`rly diff\` (runs git diff →
+  a diff board), or render diff text in a \`diff\` block — never paste a raw diff.
+- Point the user at a file with a clickable local path in a markdown block; embed a
+  screen recording with a \`video\` block; when answer choices are visual, give each
   option its own visual (\`options[].blocks\`) so the user picks by looking.
+- **There's a purpose-built component for most content — use the MOST SPECIFIC one,
+  never plain prose when a block fits.** Blocks: \`table\` (sortable/filterable/CSV,
+  load from .csv/.json), \`chart\`, \`kpi\` (stat cards), \`mermaid\`/\`graphviz\`/\`plantuml\`,
+  \`code\`, \`diff\`, \`image\` (+\`pins\`), \`compare\` (before/after), \`video\`, \`palette\`,
+  \`typography\`, \`html\`. Question types: \`single\`/\`multi\`/\`yesno\`/\`scale\`/\`color\`/
+  \`text\`/\`textarea\` plus \`rank\` (prioritize), \`allocate\` (split a budget), \`checklist\`
+  (per-item sign-off). For a business user, reach for \`kpi\`+\`chart\`+\`table\` and
+  \`rank\`/\`allocate\`/\`checklist\`; full menu + fields: \`rly agent\` and \`rly schema\`.
 - Read the result JSON from stdout; treat \`comment\` and \`annotations\` as
   first-class feedback. Full guide: \`rly agent\`.`;
 
@@ -1296,6 +1369,10 @@ USAGE
   rly ask ... --detach                no blocking: prints {boardId,url} now; collect via \`rly wait <id>\`
   rly ask ... --on-result "<cmd>"     push-wake: run <cmd> when the board finishes (result JSON on stdin)
   rly show --html-file viz.html       visualization-only board (submit button = acknowledge)
+  rly view <file.md> [more.md …]      quick read-only board rendering markdown file(s) (no lib)
+                                      (.csv/.tsv/.json render as a filterable, sortable table)
+  rly diff [git args…]                run git diff and show it in a diff board (--split, --detach,
+                                      --title; other args pass to git: rly diff --staged | HEAD~1 | -- path)
   rly wait <id> [--timeout 3600]      block until board finishes, print result JSON
                                       --while-active [--idle-grace 180]: keep waiting past the deadline
                                         while the user is still viewing/focused & recently active
@@ -1366,6 +1443,10 @@ export async function main(argv) {
         return await cmdAsk(parseArgs(rest), 'ask');
       case 'show':
         return await cmdAsk(parseArgs(rest), 'show');
+      case 'view':
+        return await cmdView(parseArgs(rest));
+      case 'diff':
+        return await cmdDiff(rest);
       case 'reopen':
         return await cmdReopen(parseArgs(rest));
       case 'rescue':