@khanglvm/relay 0.14.2 → 0.16.0

package/README.md

@@ -78,7 +78,7 @@ unchanged; pick whichever surface fits.
 | "Here's the diff — paste it in your editor" | Side-by-side **diff** blocks, syntax-highlighted **code**, **video** walkthroughs, and **file paths you click to open** in the default app |
 | "Which commits should I pick? Resolve this conflict manually." | `rly git pick` / `rly git cherry-pick` boards and color-coded `git-conflict` resolvers with ours/theirs/custom hunk choices |
 | "Type *done* when finished reviewing" | A Submit button; answers, notes, and inline comments returned as JSON |
-| Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence to comment — the agent replies and the thread grows on the board |
+| Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence; hold+drag an image area to attach a local crop — the agent replies and the thread grows on the board |
 
 Everything autosaves in real time, detached board links keep serving after
 agent timeouts, multiple boards run at once, and the package has **zero npm
@@ -93,8 +93,9 @@ actually needs them.
 | `rly help` | every command at a glance |
 | `rly git pick` / `rly git cherry-pick` | choose commit actions and rank the order directly on a board; add `--code` to cherry-pick with split code review and per-hunk Apply/Skip/Hold |
 | `rly git conflict [files…]` | auto-detect unmerged conflict files, or open specific local paths, and return resolved content in `result.blockEdits` |
-| `rly share <board-id>` | activate/list/revoke same-Wi-Fi reviewer or collaborator links for a running browser board |
+| `rly share <board-id>` | activate/list/revoke same-Wi-Fi collaborator, reference-only reviewer, or read-only links for a running browser board |
 | `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s), data files, or PDFs — library-free; great for plans, READMEs, reports, quotes |
+| `rly show --file spec.json --display-only` | present a browser board and continue immediately — no comment/note or acknowledgement required; inline `relay_show` uses this mode by default |
 | `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 |
@@ -110,6 +111,19 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
 
 ## Changelog
 
+### 0.16.0 — native viewer chrome, area comments, and durable agent waits
+
+- Viewer toolbars now use browser-native sticky positioning instead of a
+  scroll-event counter-translation; open comment composers re-anchor on scroll
+  and preserve unsaved per-target drafts.
+- Hold then drag on an image to comment on an exact rectangular area. Relay
+  saves the crop beside the browser-board record and returns its path; comparison
+  crops also identify and capture the selected Before/After source.
+- Browser boards support `responseRequired:false` / `--display-only`; inline
+  `relay_show` is display-only by default. Board and waiter deadlines now default
+  to one day (`--timeout 0` removes Relay's deadline), with client-specific
+  background/polling guidance in the agent docs.
+
 ### 0.11.0 — render inline inside the Claude & Codex apps (MCP App)
 - **`rly mcp` — relay as an MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp),
   extension `io.modelcontextprotocol/ui`). A stdio MCP server with no npm runtime dependencies
@@ -177,7 +191,8 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
   whose connection drops blocks further input instead of losing it, and
   `rly rescue <id>` re-serves on the same port so an open tab reconnects. Active
   same-Wi-Fi share links stay tied to the board and survive a same-port re-serve
-  until revoked.
+  until revoked. Reviewer submissions are isolated, reference-only side reviews
+  that never finish the owner's board; read-only links cannot mutate feedback.
 - Still **zero npm runtime dependencies**, offline, and cross-platform. Vendored
   browser libraries are loaded only for boards that need them.
 

package/docs/AGENT.md

@@ -54,7 +54,7 @@ stderr. Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled
 prints the result JSON:
 
 ```sh
-rly ask --file spec.json --timeout 1800
+rly ask --file spec.json --timeout 86400   # one day; 0 = no Relay deadline
 ```
 
 **2. Detached (recommended when your shell tool has an execution time limit).**
@@ -62,7 +62,7 @@ Returns immediately with the board URL; collect later:
 
 ```sh
 rly ask --file spec.json --detach     # → {"status":"open","boardId":"b-…","url":"…"}
-rly wait b-xxxxx --timeout 3500       # blocks until submit, prints result JSON
+rly wait b-xxxxx --timeout 86400      # default: one day; pass 0 for no deadline
 rly result b-xxxxx                    # non-blocking peek; while open it includes
                                       # the live autosaved draft of the user's answers
 ```
@@ -79,19 +79,24 @@ click the topbar **Share** icon, or you can manage the same links for the user:
 
 ```sh
 rly share b-xxxxx                         # list active share roles
-rly share b-xxxxx --role review           # reviewer: add comments only
-rly share b-xxxxx --role collab           # collaborator: edit/comment/submit
+rly share b-xxxxx --role review           # reviewer: answer/comment + submit a side review
+rly share b-xxxxx --role collab           # collaborator: edit/comment/final-submit as owner-authorized
+rly share b-xxxxx --role read             # read-only viewer: no answers/comments/submit
 rly share b-xxxxx --role review --revoke  # revoke one role
 rly share b-xxxxx --revoke --all          # revoke all active links
 ```
 
-Use `review` unless the user explicitly wants the other device to submit as the
-owner. Reviewers cannot change answers, submit, edit comments, or delete
-comments; their autosaves merge new comments into the existing draft.
-Collaborators can edit answers, comment, open allowed local file links, and
-submit. Shared viewers refresh from the live draft when another viewer saves,
-deferred while someone is typing/commenting. Active share links keep the same
-token across a same-port `rly reopen`/`rly rescue` until revoked.
+Use `review` for independent feedback: each browser gets an isolated review
+draft and may answer, comment, and submit, but the submission is stored as a
+**reference-only side review**. It does not finish the board, wake the agent, or
+complete `rly wait`; the owner (or an owner-authorized collaborator) must still
+submit the final answer. `rly result <id>` exposes current side-review drafts and
+submissions on demand under `sideReviews`, clearly marked `referenceOnly:true`.
+Use `read` when the other device should only view the board and existing
+feedback. Read-only viewers cannot answer, comment, edit blocks, open local file
+links, or submit. Collaborators retain owner-authorized edit/comment/final-submit
+permission. Active links keep the same token across a same-port
+`rly reopen`/`rly rescue` until revoked.
 
 ## Inline mode — relay as an MCP App (Claude & Codex apps)
 
@@ -135,8 +140,9 @@ Both take **the exact same board spec** documented below (the tool `inputSchema`
 fills it in, and their answers come back to you (answers, per-question notes,
 comment) as a user-message turn, with structured context synced when the host
 supports it — read them just as you would the CLI's result JSON. There is **no
-`--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode; the
-board stays live until the user submits and the host delivers the result.
+`--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode.
+`relay_ask` stays live until the user submits and the host delivers the result;
+`relay_show` is display-only by default and the agent continues immediately.
 
 **Near-full parity with the browser board.** Local `codeFile` / `htmlFile` /
 `diffFile` and local **image** files work inline too — the server inlines them
@@ -161,12 +167,25 @@ rly ask -q "Deploy to prod now?::yesno" -q "!Environment::single::dev,staging,pr
 #         label::type::comma,separated,options          leading "!" = required
 ```
 
-Visualization-only (no questions; submit button reads "Acknowledge"):
+Visualization-only, with acknowledgement/feedback:
 
 ```sh
 rly show --html-file prototype.html --title "Dashboard concept" --height 600
 ```
 
+Display-only (the agent continues immediately; no note, comments, or
+Submit/Acknowledge action):
+
+```sh
+rly show --file spec.json --display-only
+# equivalent spec field: {"responseRequired": false, "blocks": [...]}
+```
+
+`--display-only` automatically detaches the browser board. In MCP App mode,
+`relay_show` is display-only by default; set `responseRequired:true` only when
+the user really needs to acknowledge or leave feedback. `relay_ask` remains the
+response-bearing tool.
+
 Read a markdown file (no questions; library-free renderer; submit reads "Done"):
 
 ```sh
@@ -214,6 +233,7 @@ choices plus the full resolved file in `result.blockEdits[blockId]`:
   "allowPartial": true,             // default true: user may submit with gaps -> "skipped"
   "note": true,                     // default true: optional free-text box -> result "comment"
   "autoClose": true,                // default true: tab tries to close itself after submit
+  "responseRequired": true,         // false = display-only; no feedback/action, agent continues
   "submitLabel": "Submit",
   "questions": [
     { "id": "approach", "type": "single", "label": "Which approach?", "required": true,
@@ -516,11 +536,11 @@ the question-types section above.
 | `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) |
 | `pdf` | quotes, reports, exports, forms — local `.pdf` files or PDF URLs rendered inline; local files stream from the board server |
-| `image` | screenshots, mockup exports, photos — local files embed and work offline |
+| `image` | screenshots, mockup exports, photos — local files embed and work offline; hold then drag to comment on an exact area |
 | `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 |
+| `compare` | before/after images with a draggable divider (`before`/`after` = url/path/`{src,label}`); area comments preserve which side was selected |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 
 Two cross-block fields work on **any** block: `"ref":"name"` makes it openable in
@@ -529,6 +549,14 @@ 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).
 
+Every interactive `image` and `compare` block also supports area feedback:
+hold briefly, then drag a rectangle. Relay saves a pixel crop beside the board
+record and returns its local path with the annotation, so the agent can open the
+exact pixels instead of inferring from a whole-image comment. In a comparison,
+the side visible where the hold began is recorded as `before` or `after` and the
+crop comes from that source image. Remote images that prevent browser canvas
+access still return coordinates and a `cropUnavailable` marker.
+
 ### Height rules
 
 - `markdown`, `code`: natural flow (no fixed height).
@@ -628,6 +656,8 @@ intro. Annotations are autosaved with the draft and returned in the final result
 | `text` | `quote`, `prefix` (≤30 chars before), `suffix` (≤30 after) | selecting text in a markdown block |
 | `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 |
+| `image-point` | `x`, `y`, `label` | clicking an image authored with `pins:true` |
+| `image-region` | `x`, `y`, `w`, `h`, `label`, optional `side`, `crop` | holding then dragging on an image or comparison; `crop.path` is the local image artifact in browser mode |
 
 Read annotations as first-class feedback — they often carry the sharpest insight
 (e.g. a user circling the one data point that concerns them, or quoting the exact
@@ -658,14 +688,15 @@ time). Use it instead of guessing timeouts:
 ```sh
 rly result b-xxxxx     # open board → includes "presence":
                        #   {open, seen, visible, focused, secondsSinceActivity, secondsSincePing}
-rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 `--while-active` keeps extending the wait as long as the user is demonstrably
 active (page visible/focused and interaction within `--idle-grace` seconds,
-default 180); once they go idle it returns the normal `wait-timeout` JSON,
-with `presence` attached so you can decide what to do next. Prefer this over
-raising `--timeout`.
+default 180); once the deadline is reached and they are idle it returns the
+normal `wait-timeout` JSON, with `presence` attached. Relay now defaults both a
+board and `rly wait` to 86,400 seconds (one day); pass `--timeout 0` for no Relay
+deadline when the host can safely own a long-running waiter.
 
 ### A `timeout` on a detached board is NOT the end
 
@@ -680,7 +711,7 @@ tells them you stopped waiting and to prompt you afterward. So if you got a
 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
+## Waiting and push-wake across agent clients
 
 ```sh
 rly ask --file spec.json --detach --on-result 'curl -s -X POST localhost:9999/wake -d @-'
@@ -692,7 +723,19 @@ the board reaches a terminal status — submitted, acknowledged, timeout, or
 cancelled — with the full result JSON piped to stdin and `RLY_BOARD_ID`,
 `RLY_STATUS`, `RLY_URL` in the environment. `--notify-cmd` does the same from
 a `wait` that obtains a terminal result. Write a file your harness watches,
-hit a webhook — whatever wakes you.
+hit a webhook — whatever wakes you. This is passive only when that client or
+harness has an actual inbound wake mechanism; Relay does not pretend that a
+file write alone starts a new model turn.
+
+| Client/surface | Recommended Relay return path |
+|---|---|
+| MCP App (`relay_ask`) | No CLI wait. The inline board stays live and sends `ui/message` on submit, which starts the user-return turn. |
+| MCP App (`relay_show`) | Display-only by default. Present it and continue immediately; no acknowledgement is requested. |
+| Claude Code | Run `rly wait <id> --timeout 0` as a [background Bash task](https://docs.anthropic.com/en/docs/claude-code/interactive-mode#background-bash-commands); retain its task id/output rather than opening a second board. |
+| Gemini CLI | Run the waiter in the background and set [`tools.shell.backgroundCompletionBehavior` to `"inject"`](https://geminicli.com/docs/reference/configuration/) so completion is returned to the agent; `"notify"` only informs the chat UI. |
+| Codex | Keep one foreground waiter. Codex background terminals use explicit `write_stdin` polling (the [poll window defaults to five minutes](https://developers.openai.com/codex/config-reference)); the process can outlive each poll, but no portable browser-submit API wakes a stopped turn. |
+| OpenCode | Core Bash is foreground. Its [ecosystem](https://opencode.ai/docs/ecosystem/) lists background-PTY extensions; use one only when installed, otherwise keep the waiter foreground. |
+| Pi | Core intentionally has [no background Bash](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/usage.md); keep the waiter foreground or use an explicitly installed background-task extension. |
 
 ### Codex browser-board pattern
 
@@ -704,7 +747,7 @@ submits:
 
 ```sh
 rly ask --file spec.json --detach
-rly wait b-xxxxx --timeout 1800 --while-active --idle-grace 300
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.

package/package.json

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

@@ -85,8 +85,8 @@ priority call in a `rank` question — not in paragraphs. Unsure which exists? R
 | `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) |
 | `git-conflict` | conflict-marker files — side-by-side ours/theirs/base with hunk choices; returns resolved content in `result.blockEdits[blockId]` |
-| `image` | screenshots / mockups / renders — zoom+pan; `pins:true` → click-to-drop point comments |
-| `compare` | a before/after pair — draggable divider |
+| `image` | screenshots / mockups / renders — zoom+pan; hold+drag → area crop comment; `pins:true` → point comments |
+| `compare` | a before/after pair — draggable divider; area comments retain the selected side |
 | `video` | a demo / screen recording / walkthrough |
 | `pdf` | a quote / report / exported document that should render inline |
 | `palette` | color schemes — swatch cards, hover-hex, click-to-copy |
@@ -130,7 +130,7 @@ blocking `rly ask` that gets killed cancels the board. Always prefer:
 
 ```sh
 rly ask --file spec.json --detach    # returns {"boardId":"b-…","url":…} immediately
-rly wait b-xxxxx --timeout 550       # blocks until submit, prints result JSON
+rly wait b-xxxxx --timeout 86400     # default: one day; 0 = no Relay deadline
                                      # (on exit 2 "wait-timeout" just run wait again)
 rly result b-xxxxx                   # non-blocking peek (includes live draft)
 ```
@@ -142,7 +142,7 @@ create a new board just because a wait timed out.
 For long waits prefer presence-aware waiting over a huge --timeout:
 
 ```sh
-rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 # keeps extending while the user is demonstrably viewing/typing on the board;
 # returns wait-timeout promptly once they are idle/gone (presence included)
 rly result b-xxxxx        # while open also shows presence {visible, focused, secondsSinceActivity}
@@ -159,7 +159,7 @@ So in Codex, keep the waiter in the foreground until the user submits:
 
 ```sh
 rly ask --file spec.json --detach
-rly wait b-xxxxx --timeout 1800 --while-active --idle-grace 300
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.
@@ -168,9 +168,30 @@ If it is still open and the user may continue, run `rly wait` again. Do not use
 webhooks, but normal Codex CLI sessions do not expose a portable inbound API
 that wakes the current agent turn.
 
-Blocking mode (`rly ask --file spec.json --timeout 1800`, no --detach) is fine
+Blocking mode (`rly ask --file spec.json --timeout 86400`, no `--detach`) is fine
 ONLY when your shell tool has no execution time limit.
 
+Relay defaults board and waiter deadlines to one day; use `--timeout 0` when the
+client can safely own an indefinite process. Choose the return path by host:
+
+- Inline MCP `relay_ask`: no CLI wait; its `ui/message` submission wakes the
+  return turn. Inline `relay_show` is display-only by default and does not wait.
+- Claude Code: background `rly wait <id> --timeout 0` as a background Bash task.
+- Gemini CLI: background the waiter and use
+  `tools.shell.backgroundCompletionBehavior: "inject"`.
+- Codex: keep one foreground waiter; background terminals require explicit
+  polling and do not expose a portable browser-submit wake API.
+- OpenCode/Pi: keep it foreground unless a background-task extension is
+  explicitly installed (Pi core has no background Bash).
+
+Use `--on-result`/`--notify-cmd` only when the surrounding harness exposes a real
+webhook, file watcher, or inbound wake path.
+
+To present without asking for any response, use
+`rly show --file spec.json --display-only` (equivalent to
+`"responseRequired":false`). It returns immediately and shows no note,
+comments, or Submit/Acknowledge action.
+
 Useful flags: `--no-open` (don't auto-open the browser — for tests/CI; real
 users need the tab, so omit it normally) · `--title` · `--timeout <sec>`.
 
@@ -189,16 +210,22 @@ with `rly share`:
 rly share b-xxxxx                         # list active share roles
 rly share b-xxxxx --role review           # activate a reviewer link
 rly share b-xxxxx --role collab           # activate a collaborator link
+rly share b-xxxxx --role read             # activate a read-only link
 rly share b-xxxxx --role review --revoke  # revoke one role
 rly share b-xxxxx --revoke --all          # revoke all active share links
 ```
 
-Use `review` when the other device should add comments only. Reviewers cannot
-change answers, submit, edit comments, or delete comments; their autosaves merge
-new comments into the existing draft. Use `collab` only when the user explicitly
+Use `review` for independent feedback. Each reviewer browser gets an isolated
+draft and can answer, comment, and submit a **reference-only side review**. That
+submission never finishes the board or wakes/completes the waiting agent; the
+owner (or owner-authorized collaborator) must still provide the final answer.
+When the owner asks for current reviewer input, run `rly result <id>` and inspect
+`sideReviews.submissions` plus `sideReviews.drafts`; both are explicitly marked
+reference-only. Use `read` for a view-only link with no answers, comments, block
+edits, local-file opening, or submit. Use `collab` only when the user explicitly
 wants that device to act as the owner: collaborators can edit answers, comment,
-open allowed local file links, and submit. Shared viewers refresh from the live
-draft when another viewer saves, deferred while someone is typing/commenting.
+open allowed local file links, and final-submit. Shared viewers refresh from the
+relevant live draft when another viewer in the same role/session saves.
 Active share links are durable too: they keep the same token across a same-port
 `rly reopen`/`rly rescue` until `rly share --revoke` disables them.
 
@@ -412,6 +439,15 @@ Add `"pins": true` to an `image` block: the user clicks any point on the image t
 drop a comment anchored to that exact spot (Figma-style), returned as an
 `{kind:"image-point", x, y}` annotation. Ideal for design/mockup review.
 
+### Comment on an exact image area (local crop)
+
+Every interactive `image` and `compare` block supports hold-then-drag area
+feedback without another spec flag. Relay returns an `image-region` target with
+normalized `x`, `y`, `w`, and `h`; browser boards also save the selected pixels
+beside the board and return `target.crop.path`, which the agent should open with
+its image viewer. Comparison targets include `side:"before"|"after"`, and the
+crop comes from that source image rather than the composited slider view.
+
 ### Show a git diff in one step — `rly diff`
 
 `rly diff [git args…]` runs `git diff` and opens the result as a diff board —
@@ -443,7 +479,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 | image-point | code-line", "..." },
+  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image | image-point | image-region | code-line", "..." },
   "text": "user comment",
   "author": "user",
   "createdAt": "ISO",

package/src/cli.js

@@ -28,6 +28,8 @@ const BIN = path.join(PKG_ROOT, 'bin', 'rly.js');
 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 DEFAULT_BOARD_TIMEOUT_SEC = 86400;
+const DEFAULT_WAIT_TIMEOUT_SEC = 86400;
 
 const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
@@ -171,6 +173,7 @@ async function resolveSpecInput(args, mode) {
   if (args.htmlFile) raw.htmlFile = args.htmlFile;
   if (args.height) raw.htmlHeight = args.height;
   if (args.submitLabel) raw.submitLabel = args.submitLabel;
+  if (args.displayOnly === true) raw.responseRequired = false;
   if (args.q.length) {
     raw.questions = [...(raw.questions || []), ...args.q.map((s, i) => questionFromInline(s, i))];
   }
@@ -198,7 +201,7 @@ function readFileOrThrow(p) {
 
 async function runOrDetach(record, args) {
   await assertSpecReady(record.spec);
-  const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800;
+  const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_BOARD_TIMEOUT_SEC;
   const port = args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0;
   const open = args.open !== false;
 
@@ -231,7 +234,9 @@ async function runOrDetach(record, args) {
       boardId: record.id,
       url: info.url,
       port: info.port,
-      hint: `block for the answers with: rly wait ${record.id}`,
+      hint: record.spec.responseRequired === false
+        ? 'display-only board opened; no response will be collected'
+        : `block for the answers with: rly wait ${record.id}`,
     });
     return 0;
   }
@@ -247,7 +252,7 @@ async function cmdAsk(args, mode) {
   const spec = normalizeSpec(raw);
   await assertSpecReady(spec);
   const record = createBoard(spec);
-  return runOrDetach(record, args);
+  return runOrDetach(record, spec.responseRequired === false ? { ...args, detach: true } : args);
 }
 
 // `rly diff [git args…]` — run `git diff` for the user and open the result as a
@@ -639,11 +644,11 @@ async function fetchPresence(url) {
 async function cmdWait(args) {
   const id = args._[0];
   if (!id) throw new CliError('usage: rly wait <board-id> [--timeout <sec>] [--while-active] [--idle-grace <sec>] [--notify-cmd <cmd>]');
-  const timeoutSec = args.timeout !== undefined ? Math.max(1, Number.parseInt(args.timeout, 10) || 1) : 3600;
+  const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_WAIT_TIMEOUT_SEC;
   const whileActive = args.whileActive === true;
   const idleGrace = args.idleGrace !== undefined ? Math.max(0, Number.parseInt(args.idleGrace, 10) || 0) : 180;
   const notifyCmd = typeof args.notifyCmd === 'string' && args.notifyCmd.trim() ? args.notifyCmd : null;
-  let deadline = Date.now() + timeoutSec * 1000;
+  let deadline = timeoutSec === 0 ? Number.POSITIVE_INFINITY : Date.now() + timeoutSec * 1000;
   mustLoad(id);
 
   // Push-wake: run the agent's --notify-cmd after a TERMINAL result, then print.
@@ -761,21 +766,27 @@ async function cmdWaitLoop(id, deadline, opts) {
 
 async function cmdResult(args) {
   const record = mustLoad(args._[0]);
+  const sideReviews = {
+    referenceOnly: true,
+    note: 'Side reviews are reference only. Wait for the board owner (or owner-authorized collaborator) to submit the final answer.',
+    submissions: Array.isArray(record.sideReviews) ? record.sideReviews : [],
+    drafts: record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {},
+  };
   if (record.result && record.result.finishedAt) {
-    printResult(record.result);
+    printResult({ ...record.result, sideReviews });
     return exitCodeFor(record.result.status);
   }
   const running = loadRunning(record.id);
   if (running && isAlive(running.pid)) {
     // While open, expose the real-time autosaved draft so agents can peek, plus
     // best-effort presence (whether the user is still viewing/focused/active).
-    const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null };
+    const out = { status: 'open', boardId: record.id, url: running.url, draft: record.draft ?? null, sideReviews };
     const presence = await fetchPresence(running.url);
     if (presence) out.presence = presence;
     printResult(out); // draft can hold many annotations — sidecar it too
     return 0;
   }
-  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null });
+  printResult({ status: 'lost', boardId: record.id, draft: record.draft ?? null, sideReviews });
   return 5;
 }
 
@@ -785,9 +796,10 @@ async function cmdShare(args) {
   if (!running || !isAlive(running.pid)) {
     throw new CliError(`board "${record.id}" is not running. Use \`rly reopen ${record.id} --detach\` first.`, 5);
   }
-  const role = args.all ? 'all' : args.role;
-  if (role !== undefined && !['collab', 'review', 'all'].includes(role)) {
-    throw new CliError('--role must be collab or review.', 4);
+  let role = args.all ? 'all' : args.role;
+  if (role === 'readonly' || role === 'read-only') role = 'read';
+  if (role !== undefined && !['collab', 'review', 'read', 'all'].includes(role)) {
+    throw new CliError('--role must be collab, review, or read.', 4);
   }
   const shareUrl = new URL('/api/share', running.url);
   let res;
@@ -1079,7 +1091,7 @@ the user should view — put it in relay instead of printing it.**
   user-facing "wake this agent turn from a browser submit" command. In Codex,
   keep the waiter in the foreground until the user submits:
   \`rly ask --file spec.json --detach\` then
-  \`rly wait <boardId> --timeout 1800 --while-active --idle-grace 300\`.
+  \`rly wait <boardId> --timeout 86400 --while-active --idle-grace 3600\`.
   If wait exits with \`wait-timeout\`, immediately run \`rly result <boardId>\`;
   if it is still open and the user may continue, run \`rly wait\` again. Do not
   use \`--on-result\` as the primary Codex return path; normal Codex CLI sessions
@@ -1087,6 +1099,10 @@ the user should view — put it in relay instead of printing it.**
   Detached boards are durable: a board timeout hands the agent a \`timeout\`
   result but keeps the same URL/port serving until Submit or \`rly stop\`. Do
   not create a new board just because a wait timed out.
+- **No response needed** → \`rly show --file spec.json --display-only\`. It
+  returns immediately and shows no note, comments, or Submit/Acknowledge action.
+  In MCP App mode, \`relay_show\` is display-only by default; \`relay_ask\` is the
+  response-bearing tool.
 - **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 →
@@ -1100,14 +1116,16 @@ the user should view — put it in relay instead of printing it.**
   option its own visual (\`options[].blocks\`) so the user picks by looking.
 - Same-Wi-Fi sharing is locked by default. When the user wants another device to
   review or co-fill a running board, manage explicit links with \`rly share <id>\`:
-  \`--role review\` creates a comments-only reviewer link, \`--role collab\` creates
-  an edit/comment/submit link, and \`--revoke\` disables active links. Active
+  \`--role review\` creates an answer/comment link whose submissions are reference-only
+  side reviews (\`rly result\` exposes them but they never complete \`rly wait\`),
+  \`--role collab\` creates an owner-authorized edit/comment/final-submit link,
+  \`--role read\` creates a view-only link, and \`--revoke\` disables active links. Active
   share links are durable across same-port \`rly reopen\`/\`rly rescue\` until
   revoked.
 - **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\`, \`git-conflict\`, \`image\` (+\`pins\`), \`compare\` (before/after), \`video\`, \`pdf\`, \`palette\`,
+  \`code\`, \`diff\`, \`git-conflict\`, \`image\` (hold+drag area crops; +\`pins\` for points), \`compare\` (before/after with side-aware area crops), \`video\`, \`pdf\`, \`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
@@ -1571,7 +1589,7 @@ async function cmdServeInternal(args) {
     id,
     port: args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0,
     open: args.open !== false,
-    timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800,
+    timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_BOARD_TIMEOUT_SEC,
     quiet: true,
     // Detached board: timeout hands back to the agent but keeps the same
     // URL/port serving until Submit or explicit stop.
@@ -1591,7 +1609,9 @@ USAGE
                                       quick inline questions ("!" = required, label::type::options)
   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 show --html-file viz.html       visualization board (submit button = acknowledge)
+  rly show --file spec.json --display-only
+                                      present without comments/acknowledgement; returns immediately
   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;
                                        .pdf streams in an inline PDF viewer)
@@ -1602,7 +1622,7 @@ USAGE
                                       add --code for split code view with per-hunk Apply/Skip/Hold
   rly git conflict [files…]           board for resolving conflict-marker files; with no files, auto-detects
                                       unmerged git files and returns resolved content in result.blockEdits
-  rly wait <id> [--timeout 3600]      block until board finishes, print result JSON
+  rly wait <id> [--timeout 86400]     block up to one day until the board finishes (0 = no deadline)
                                       --while-active [--idle-grace 180]: keep waiting past the deadline
                                         while the user is still viewing/focused & recently active
                                       --notify-cmd "<cmd>": run <cmd> on a terminal result (JSON on stdin)
@@ -1610,8 +1630,9 @@ USAGE
                                         read that file if your shell truncates stdout; never pipe to head/tail
   rly result <id>                     result/status now (includes live autosaved draft + presence while open)
   rly share <id>                      list active same-Wi-Fi share links for a running board
-  rly share <id> --role review        activate a reviewer link (comments only)
-  rly share <id> --role collab        activate a collaborator link (edit/comment/submit)
+  rly share <id> --role review        reviewer: answer/comment/submit a reference-only side review
+  rly share <id> --role collab        collaborator: edit/comment/final-submit as owner-authorized
+  rly share <id> --role read          activate a read-only viewer link
   rly share <id> --role review --revoke
                                       revoke one share role; use --revoke --all to disable all roles
                                       active links survive same-port reopen/rescue until revoked
@@ -1645,7 +1666,7 @@ USAGE
 
 COMMON FLAGS
   --title <s> --intro <s> --html-file <f> --height <px> --submit-label <s>
-  --timeout <sec> (default 1800; 0 = none) --port <n> --no-open --detach
+  --timeout <sec> (default 86400; 0 = none) --port <n> --no-open --detach --display-only
 
 EXIT CODES   0 submitted/acknowledged · 2 timeout · 3 cancelled · 4 usage · 5 not found