@khanglvm/relay 0.10.0 → 0.10.1

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

@@ -544,7 +544,14 @@ call rather than calling it repeatedly in a loop.
   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.1",
   "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, 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 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 trivial 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,7 +122,17 @@ 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
@@ -154,6 +167,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,
@@ -210,6 +232,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;
     }
   }