cue-ai 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to cue (`cue-ai`) are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/), and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.9.2] — 2026-06-05
+
+### Added
+
+- **Live code-review visibility.** Watch an independent review move file-by-file in
+  real time instead of staring at an opaque "Precipitating…" spinner.
+  - `bin/cue-review-watch` — live renderer; run it in a second pane to follow the
+    latest review (`--id <id>` for a specific one, `--once` for a snapshot).
+  - `bin/cue-review-progress` — append-only progress events to
+    `~/.config/cue/review-progress/<id>.jsonl` (the shared schema every reviewer writes).
+  - `/code-review` now emits per-file / per-dimension / per-finding progress events.
+  - The `auto-review` Stop-hook gate streams its review to the same log, so the
+    independent merge-gate review is watchable live too (invariants unchanged:
+    recursion guard, fail-open, binary verdict).
+  - Docs: [`docs/review-visibility.md`](./docs/review-visibility.md).
+- **Self-learner (experimental · opt-in · default-OFF).** Profiles capture where their
+  skills fell short during a task and feed gated improvements back over time.
+  - `resources/hooks/profile-self-improve.sh` — friction-signal capture plus an optional
+    live critic agent. Recursion-guarded, never blocks Stop, runs the critic at most once
+    per session, fully fail-open.
+  - New `skill_gap` analytics event (`src/lib/analytics.ts`), inert to existing readers.
+  - Piloted on the `skill-writer` profile. Enable with
+    `touch ~/.config/cue/.auto-improve-enabled`. Docs: [`docs/self-learner.md`](./docs/self-learner.md).
+
+### Documentation
+
+- **README — "what you'll see during a run — the reviewer".** Explains the independent
+  review gate that runs during a Claude Code session: why a red "Stop hook error" means
+  the gate is working (not a failure), how to suppress or disable it, and how to watch a
+  review live with `cue-review-watch`. Includes a real catch (a `weight` kg/g unit
+  ambiguity that would have rendered per-kg prices as `€0.00`).
+
+[0.9.2]: https://github.com/opencue/cuecards/compare/v0.9.1...v0.9.2
+[0.9.1]: https://github.com/opencue/cuecards/releases/tag/v0.9.1

package/README.md

@@ -14,10 +14,10 @@
   "applicationCategory": "DeveloperApplication",
   "operatingSystem": "Linux, macOS, Windows (WSL2)",
   "description": "cuecards is an open-source agent profile manager for Claude Code, OpenAI Codex, Cursor, Cline, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, Sourcegraph Amp, and Aider. One cuecard per directory — skills, MCPs, plugins, persona, playbooks, gates. Cut per-message token cost 10–25×.",
-  "url": "https://github.com/opencue/claude-code-skills",
+  "url": "https://github.com/opencue/cuecards",
   "downloadUrl": "https://www.npmjs.com/package/cue-ai",
-  "codeRepository": "https://github.com/opencue/claude-code-skills",
-  "license": "https://github.com/opencue/claude-code-skills/blob/main/LICENSE",
+  "codeRepository": "https://github.com/opencue/cuecards",
+  "license": "https://github.com/opencue/cuecards/blob/main/LICENSE",
   "programmingLanguage": "TypeScript",
   "runtimePlatform": "Bun",
   "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
@@ -48,8 +48,8 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/cue-ai"><img src="https://img.shields.io/npm/v/cue-ai?style=flat-square&label=npm&color=1d1d1f&labelColor=f5f5f7" alt="npm"></a>&nbsp;
   <a href="https://www.npmjs.com/package/cue-ai"><img src="https://img.shields.io/npm/dw/cue-ai?style=flat-square&label=downloads&color=1d1d1f&labelColor=f5f5f7" alt="downloads"></a>&nbsp;
-  <a href="https://github.com/opencue/claude-code-skills/stargazers"><img src="https://img.shields.io/github/stars/opencue/claude-code-skills?style=flat-square&label=stars&color=1d1d1f&labelColor=f5f5f7" alt="stars"></a>&nbsp;
-  <a href="./LICENSE"><img src="https://img.shields.io/github/license/opencue/claude-code-skills?style=flat-square&label=license&color=1d1d1f&labelColor=f5f5f7" alt="MIT"></a>&nbsp;
+  <a href="https://github.com/opencue/cuecards/stargazers"><img src="https://img.shields.io/github/stars/opencue/cuecards?style=flat-square&label=stars&color=1d1d1f&labelColor=f5f5f7" alt="stars"></a>&nbsp;
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/opencue/cuecards?style=flat-square&label=license&color=1d1d1f&labelColor=f5f5f7" alt="MIT"></a>&nbsp;
   <img src="https://img.shields.io/badge/telemetry-none-1d1d1f?style=flat-square&labelColor=f5f5f7" alt="zero telemetry">
 </p>
 
@@ -59,6 +59,12 @@
   <code>npm install -g cue-ai</code>
 </p>
 
+<p align="center">
+  <sub>Requires Node ≥20 and an existing <a href="https://github.com/anthropics/claude-code">Claude Code</a> or <a href="https://github.com/openai/codex">Codex</a> install — cue is a thin shim that exec's your agent, not a replacement.</sub>
+  <br>
+  <sub>package <code>cue-ai</code> &nbsp;·&nbsp; command <code>cue</code> &nbsp;·&nbsp; repo <a href="https://github.com/opencue/cuecards"><code>opencue/cuecards</code></a></sub>
+</p>
+
 <br>
 <br>
 
@@ -87,11 +93,15 @@ One cuecard per project. Your agent reads the right one the moment you launch.
 
 ```bash
 npm install -g cue-ai                          # 1. install
-cue discover search "code review"              # 2. find a skill
-cue discover install review/code-review        # 3. add it
-claude                                         # 4. launch — the cuecard is loaded
+cue shell install                              # 2. activate the claude shim (one-time; --codex adds codex)
+cue discover search "code review"              # 3. find a skill
+cue discover install review/code-review        # 4. add it
+claude                                         # 5. launch — the cuecard is loaded
 ```
 
+> Step 2 is what makes `claude` load your cuecard: it installs a `~/.local/bin/claude`
+> shim that hands off to `cue launch`. Skip it and `claude` just runs vanilla Claude Code.
+
 Search. Install. Use. No config files to edit. Works the same with `codex`, `cursor`, `cline`, `gemini`, and five other agents.
 
 <p align="center">
@@ -132,11 +142,11 @@ Search. Install. Use. No config files to edit. Works the same with `codex`, `cur
 ## by the numbers.
 
 <p align="center">
-  <strong>10–25×</strong>&nbsp;&nbsp;token cost reduction
+  <strong>up to ~16×</strong>&nbsp;&nbsp;leaner always-on context
   <br><br>
   <strong>&lt; 5 ms</strong>&nbsp;&nbsp;warm launch overhead
   <br><br>
-  <strong>69</strong>&nbsp;&nbsp;pre-built cuecards · <strong>110+</strong> local skills
+  <strong>69</strong>&nbsp;&nbsp;pre-built cuecards · <strong>330+</strong> local skills
   <br><br>
   <strong>10</strong>&nbsp;&nbsp;AI coding agents supported
   <br><br>
@@ -149,19 +159,19 @@ Search. Install. Use. No config files to edit. Works the same with `codex`, `cur
 
 ## the money shot.
 
-> Loading everything costs you tokens on every single message. cuecards cut context size by 10–25×.
+> Loading everything costs you tokens on every single message. cuecards cut your always-on context ~9–16× — and you can reproduce every number below with `cue cost --compare`.
 
-| Scenario | Context loaded | Cost per session (Sonnet) |
+| Loadout | Always-on context | Cost / 100 msgs (Sonnet input) |
 |---|---|---|
-| **Without cuecards** — all skills + every MCP | ~180k tokens | ~$2.70 😱 |
-| **With cuecards** — `backend` profile | ~8k tokens | ~$0.12 ✅ |
-| **With cuecards** — `caveman-quick` | ~2k tokens | ~$0.03 🚀 |
+| **Without cuecards** — `full` (every skill + MCP) | ~81k tokens | ~$24 😱 |
+| **With cuecards** — `backend` profile | ~9k tokens | ~$2.70 ✅ |
+| **With cuecards** — `caveman-quick` | ~6.8k tokens | ~$2.00 🚀 |
 
-That's **22× fewer tokens** on a real backend loadout vs the unmanaged baseline. Your model picks the right tool faster because it's not scanning irrelevant descriptions on every message.
+That's **~9× fewer always-on tokens** on a backend loadout (≈12× on `caveman-quick`, up to ≈16× on the leanest profiles) versus loading everything. Your model also picks the right tool faster because it's not scanning irrelevant descriptions on every message.
 
 ```bash
 cue cost                      # token budget for your active profile
-cue cost --profile full       # compare against the "everything" baseline
+cue cost --compare            # full table: every profile ranked vs the `full` baseline
 ```
 
 <br>
@@ -170,7 +180,7 @@ cue cost --profile full       # compare against the "everything" baseline
 
 ## why cuecards.
 
-- **Cut per-message token cost 10–25×.** Skills, MCPs, and plugins scoped per directory, not globally loaded into every session.
+- **Cut always-on context up to ~16×.** Skills, MCPs, and plugins scoped per directory, not globally loaded into every session — reproduce it with `cue cost --compare`.
 - **Five-dimensional agents.** Persona + playbooks + quality gates + evals + failure loop. Not just "more tools loaded" — composable expertise.
 - **One cuecard, ten agents.** The same `profile.yaml` materializes into Claude Code, Codex, Cursor, Cline, Gemini, Copilot, Windsurf, Roo, Amp, and Aider native formats.
 
@@ -210,6 +220,44 @@ Full system + when each tag fires: **[`resources/skills/skills/meta/integrity-ta
 
 ---
 
+## what you'll see during a run — the reviewer.
+
+cuecards can ship an **independent review gate**. When the agent finishes a
+code-producing turn in a cuecard that enables it, cue spawns a *fresh, separate*
+reviewer agent over the working-tree diff **before the turn is allowed to finish**.
+It runs as a normal step of a Claude Code run — so expect to see a reviewer agent
+think for a while (a deep pass can run many minutes and tens of thousands of tokens).
+This is by design, and it earns its keep.
+
+A real catch from a live session: the reviewer flagged a **load-bearing unit bug** —
+a product's `weight` was treated as kilograms in one place but grams in two others
+(`weight >= 1000 ? kg : g`). Left in, the per-kg price renders as `€0.00` and a cart
+reads `20000 kg`. The gate held the merge until it was fixed.
+
+Two things so the behavior isn't surprising:
+
+- **A red "Stop hook error" is the gate working, not a failure.** Claude Code renders
+  any *blocking* hook that way. It means the reviewer found a CRITICAL/HIGH issue and is
+  holding the turn until you address it. It caps at 2 rounds, then releases. Suppress it
+  for one turn with `[skip-auto-review]` in your message; turn it off entirely with
+  `rm ~/.config/cue/auto-review-enabled`.
+- **You can watch the review live.** A long review otherwise shows only a spinner. Run
+  `cue-review-watch` in a second pane to see it move file-by-file with findings as they land:
+
+```
+16:42:03  📄 setup-plate-variants.ts
+16:42:03     → unit convention
+16:42:09     🔴 CRITICAL  weight kg/g ambiguity → per-kg price shows €0.00
+16:45:30  ✅ review complete  1 CRITICAL
+```
+
+Enable the gate with `touch ~/.config/cue/auto-review-enabled`. Full details:
+[`docs/review-visibility.md`](./docs/review-visibility.md).
+
+<br>
+
+---
+
 ## the catalog.
 
 > One repo. 69 pre-built expert agents. Pin one with `cue use <name>` and `claude` launches with that cuecard's skills, MCPs, hooks, and commands materialized.
@@ -307,8 +355,7 @@ cue list                      # see all available profiles
 
 # Measure
 cue cost                      # token budget for active profile
-cue eval --breakdown          # per-message vs on-demand
-cue eval --compare a b        # side-by-side delta
+cue cost --compare            # every profile ranked vs the `full` baseline
 
 # System dependencies
 cue cli install --all --yes   # install every missing CLI
@@ -335,12 +382,13 @@ cue doctor --fix              # diff declared vs actual state, auto-repair
 npm install -g cue-ai
 ```
 
-Then in any project:
+Then activate the shim once, and pin a profile in any project:
 
 ```bash
+cue shell install             # one-time: installs the claude shim (--codex for codex)
 cd ~/projects/q4-launch
 echo marketing > .cue-profile
-claude
+claude                        # launches with the marketing cuecard
 ```
 
 <details>
@@ -348,9 +396,10 @@ claude
 
 | Path | Command |
 |---|---|
-| One-line script | `curl -fsSL https://raw.githubusercontent.com/opencue/claude-code-skills/main/get.sh \| bash` |
-| Manual clone | `git clone https://github.com/opencue/claude-code-skills.git ~/Documents/cue && ~/Documents/cue/install.sh` |
-| Per-OS bootstrap | paste [`setup/macos.md`](./setup/macos.md) · [`setup/linux.md`](./setup/linux.md) · [`setup/windows.md`](./setup/windows.md) into Claude Code |
+| One-line script | `curl -fsSL https://raw.githubusercontent.com/opencue/cuecards/main/get.sh \| bash` |
+| Manual clone | `git clone https://github.com/opencue/cuecards.git ~/Documents/cue && ~/Documents/cue/install.sh` |
+| Lean stack (core + caveman + RTK only, cross-OS) | paste [`setup/lean-cue.md`](./setup/lean-cue.md) into Claude Code |
+| Per-OS bootstrap (full stack) | paste [`setup/macos.md`](./setup/macos.md) · [`setup/linux.md`](./setup/linux.md) · [`setup/windows.md`](./setup/windows.md) into Claude Code |
 
 </details>
 
@@ -440,11 +489,11 @@ The bits that didn't fit on the landing page:
 
 | Project | Profile | What they do |
 |---|---|---|
-| [opencue/claude-code-skills](https://github.com/opencue/claude-code-skills) | `full`, `skill-writer` | Dogfooding cue on itself |
+| [opencue/cuecards](https://github.com/opencue/cuecards) | `full`, `skill-writer` | Dogfooding cue on itself |
 | [recodeee/colony](https://github.com/recodeee/colony) | `fleet-control` | Multi-agent coordination MCP |
 | [recodeee/gitguardex](https://github.com/recodeee/gitguardex) | `backend` | Branch + worktree isolation for parallel agents |
 
-> **Using cue?** Open a PR or drop a link in [Discussions](https://github.com/opencue/claude-code-skills/discussions).
+> **Using cue?** Open a PR or drop a link in [Discussions](https://github.com/opencue/cuecards/discussions).
 
 <br>
 
@@ -452,11 +501,11 @@ The bits that didn't fit on the landing page:
 
 ## star history.
 
-<a href="https://star-history.com/#opencue/claude-code-skills&Date">
+<a href="https://star-history.com/#opencue/cuecards&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=opencue/claude-code-skills&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=opencue/claude-code-skills&type=Date" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=opencue/claude-code-skills&type=Date" width="720" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=opencue/cuecards&type=Date" width="720" />
   </picture>
 </a>
 
@@ -467,7 +516,7 @@ The bits that didn't fit on the landing page:
 ## contributing.
 
 ```bash
-git clone https://github.com/opencue/claude-code-skills.git
+git clone https://github.com/opencue/cuecards.git
 cd cue && bun install
 bun test                                      # tests (lib + commands)
 bun run src/index.ts --help                   # run locally
@@ -478,6 +527,6 @@ bun run src/index.ts --help                   # run locally
 | Add a skill | `cue skills-new <name>` then edit `resources/skills/skills/<category>/<name>/SKILL.md` |
 | Add a profile | `cue new <name>` then `cue validate <name>` |
 | Share your profile | `cue share publish --profile <name>` |
-| Report a bug | [Open an issue](https://github.com/opencue/claude-code-skills/issues) |
+| Report a bug | [Open an issue](https://github.com/opencue/cuecards/issues) |
 
 License: [MIT](./LICENSE).

package/bin/cue-review-progress

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# cue-review-progress — emit live code-review progress events to a tail-able JSONL
+# so `cue-review-watch` (or a dashboard panel) can show what a reviewer is doing
+# in REAL TIME instead of an opaque spinner. No external deps.
+#
+# Any reviewer (the auto-review Stop hook, a code-reviewer subagent, /ship Step 9,
+# a review workflow) appends one event per file / dimension / finding. The shared
+# schema is the contract — see docs/review-visibility.md.
+#
+# Storage: ~/.config/cue/review-progress/<id>.jsonl   (append-only)
+#          ~/.config/cue/review-progress/latest        (pointer file holding <id>)
+#
+# Event schema (one JSON object per line):
+#   ts        ISO-8601 UTC (auto)
+#   id        review id
+#   kind      start | file | dim | finding | note | end
+#   file      path under review            (file/dim/finding)
+#   dim       dimension/lens being checked (dim/finding)
+#   severity  CRITICAL|HIGH|MEDIUM|LOW     (finding)
+#   title     short text                   (finding/note/start/end)
+#   detail    longer text                  (optional)
+#
+# Usage:
+#   cue-review-progress start  [--id <id>] [--label <text>] [--files <n>]   # prints id
+#   cue-review-progress emit   [--id <id>] --kind <file|dim|finding|note> \
+#                              [--file <p>] [--dim <d>] [--severity <S>] \
+#                              [--title <t>] [--detail <x>]
+#   cue-review-progress end    [--id <id>] [--summary <text>]
+#   cue-review-progress path   [--id <id>]        # print the jsonl path
+#   cue-review-progress latest                    # print current latest id
+set -euo pipefail
+
+DIR="${XDG_CONFIG_HOME:-$HOME/.config}/cue/review-progress"
+mkdir -p "$DIR"
+
+# JSON string escape: drop C0 control chars (a raw tab/newline breaks the line),
+# then escape backslash and double-quote.
+esc() { printf '%s' "${1:-}" | tr -d '\000-\037' | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+now() { date -u +%Y-%m-%dT%H:%M:%S.000Z; }
+
+resolve_id() { # $1 = explicit id (may be empty)
+  if [[ -n "${1:-}" ]]; then printf '%s' "$1"; return; fi
+  if [[ -r "$DIR/latest" ]]; then head -1 "$DIR/latest"; return; fi
+  printf ''
+}
+
+cmd="${1:-}"; shift || true
+ID="" KIND="" FILE="" DIM="" SEV="" TITLE="" DETAIL="" LABEL="" FILES="" SUMMARY=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id)       ID="$2"; shift 2 ;;
+    --kind)     KIND="$2"; shift 2 ;;
+    --file)     FILE="$2"; shift 2 ;;
+    --dim)      DIM="$2"; shift 2 ;;
+    --severity) SEV="$2"; shift 2 ;;
+    --title)    TITLE="$2"; shift 2 ;;
+    --detail)   DETAIL="$2"; shift 2 ;;
+    --label)    LABEL="$2"; shift 2 ;;
+    --files)    FILES="$2"; shift 2 ;;
+    --summary)  SUMMARY="$2"; shift 2 ;;
+    *) echo "cue-review-progress: unknown flag $1" >&2; exit 1 ;;
+  esac
+done
+
+append() { # $1 = full json object (without trailing newline)
+  printf '%s\n' "$1" >> "$DIR/$RID.jsonl"
+}
+
+case "$cmd" in
+  start)
+    RID="${ID:-rev-$(date -u +%Y%m%dT%H%M%SZ)-$$}"
+    printf '%s' "$RID" > "$DIR/latest"
+    : > "$DIR/$RID.jsonl"
+    append "$(printf '{"ts":"%s","id":"%s","kind":"start","title":"%s","detail":"%s"}' \
+      "$(now)" "$(esc "$RID")" "$(esc "$LABEL")" "$(esc "$FILES")")"
+    printf '%s\n' "$RID"
+    ;;
+  emit)
+    RID="$(resolve_id "$ID")"
+    [[ -z "$RID" ]] && { echo "cue-review-progress emit: no review id (run 'start' first or pass --id)" >&2; exit 1; }
+    case "$KIND" in
+      file|dim|finding|note) ;;
+      "") echo "cue-review-progress emit: --kind required (file|dim|finding|note)" >&2; exit 1 ;;
+      *)  echo "cue-review-progress emit: invalid --kind '$KIND'" >&2; exit 1 ;;
+    esac
+    append "$(printf '{"ts":"%s","id":"%s","kind":"%s","file":"%s","dim":"%s","severity":"%s","title":"%s","detail":"%s"}' \
+      "$(now)" "$(esc "$RID")" "$KIND" "$(esc "$FILE")" "$(esc "$DIM")" "$(esc "$SEV")" "$(esc "$TITLE")" "$(esc "$DETAIL")")"
+    ;;
+  end)
+    RID="$(resolve_id "$ID")"
+    [[ -z "$RID" ]] && exit 0
+    append "$(printf '{"ts":"%s","id":"%s","kind":"end","title":"%s"}' \
+      "$(now)" "$(esc "$RID")" "$(esc "$SUMMARY")")"
+    ;;
+  path)
+    RID="$(resolve_id "$ID")"; [[ -z "$RID" ]] && { echo "no review yet" >&2; exit 1; }
+    printf '%s\n' "$DIR/$RID.jsonl"
+    ;;
+  latest)
+    [[ -r "$DIR/latest" ]] && head -1 "$DIR/latest" || { echo "no review yet" >&2; exit 1; }
+    ;;
+  ""|-h|--help|help)
+    sed -n '2,/^set -e/p' "$0" | sed 's/^# \{0,1\}//; s/^set -.*//'
+    ;;
+  *)
+    echo "cue-review-progress: unknown subcommand '$cmd' (start|emit|end|path|latest)" >&2; exit 1 ;;
+esac

package/bin/cue-review-watch

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# cue-review-watch — live view of a code review in progress. Run it in a second
+# pane and watch the reviewer move file-by-file, dimension-by-dimension, with
+# findings as they land — instead of an opaque "Precipitating…" spinner.
+#
+# Reads the JSONL written by cue-review-progress (and the auto-review Stop hook).
+#
+# Usage:
+#   cue-review-watch                # follow the latest review, live
+#   cue-review-watch --id <id>      # follow a specific review
+#   cue-review-watch --once         # print what's there so far and exit (no follow)
+set -euo pipefail
+
+DIR="${XDG_CONFIG_HOME:-$HOME/.config}/cue/review-progress"
+ID="" ONCE=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id)   ID="$2"; shift 2 ;;
+    --once) ONCE=1; shift ;;
+    -h|--help) grep '^#' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "cue-review-watch: unknown flag $1" >&2; exit 1 ;;
+  esac
+done
+
+# Colors only on a tty.
+if [[ -t 1 ]]; then
+  B=$'\033[1m'; D=$'\033[2m'; R=$'\033[31m'; Y=$'\033[33m'; G=$'\033[32m'; C=$'\033[36m'; M=$'\033[35m'; Z=$'\033[0m'
+else
+  B="" D="" R="" Y="" G="" C="" M="" Z=""
+fi
+
+have_jq=0; command -v jq >/dev/null 2>&1 && have_jq=1
+
+get() { # $1=field  (reads $line); jq if present, grep fallback
+  if [[ $have_jq -eq 1 ]]; then
+    printf '%s' "$line" | jq -r --arg f "$1" '.[$f] // ""' 2>/dev/null
+  else
+    printf '%s' "$line" | grep -oE "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 \
+      | sed -E "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/"
+  fi
+}
+
+hhmmss() { printf '%s' "${1:-}" | sed -E 's/.*T([0-9:]{8}).*/\1/'; }
+
+render() { # reads $line
+  local kind ts t file dim sev title detail
+  kind="$(get kind)"; [[ -z "$kind" ]] && return 0
+  ts="$(get ts)"; t="$(hhmmss "$ts")"
+  file="$(get file)"; dim="$(get dim)"; sev="$(get severity)"; title="$(get title)"; detail="$(get detail)"
+  case "$kind" in
+    start)   printf '%s%s▶ review started%s %s%s%s\n' "$D$t  $Z" "$B$C" "$Z" "$D" "${detail:+($detail files) }${title}" "$Z" ;;
+    file)    printf '%s%s📄 %s%s\n' "$D$t  $Z" "$B" "$file" "$Z" ;;
+    dim)     printf '%s   %s→ %s%s\n' "$D$t  $Z" "$C" "$dim" "$Z" ;;
+    finding)
+      local col gl
+      case "$sev" in
+        CRITICAL) col="$R$B"; gl="🔴" ;;
+        HIGH)     col="$R";   gl="🟠" ;;
+        MEDIUM)   col="$Y";   gl="🟡" ;;
+        *)        col="$D";   gl="⚪" ;;
+      esac
+      printf '%s     %s%s %s%s %s%s\n' "$D$t  $Z" "$col" "$gl" "${sev:-NOTE}" "$Z" "${file:+$file${dim:+ · $dim}  }" "$title"
+      [[ -n "$detail" ]] && printf '          %s%s%s\n' "$D" "$detail" "$Z"
+      ;;
+    note)    printf '%s   %s· %s%s\n' "$D$t  $Z" "$D" "${title}${detail:+: $detail}" "$Z" ;;
+    end)     printf '%s%s✅ review complete%s %s%s%s\n' "$D$t  $Z" "$B$G" "$Z" "$D" "$title" "$Z" ;;
+  esac
+}
+
+# Resolve the review id / file.
+[[ -z "$ID" && -r "$DIR/latest" ]] && ID="$(head -1 "$DIR/latest")"
+if [[ -z "$ID" ]]; then
+  echo "${D}cue-review-watch: no review yet. Start one, or a reviewer will.${Z}" >&2
+fi
+
+# Wait for the file to appear (a reviewer may not have started yet).
+file_path="$DIR/${ID:-__none__}.jsonl"
+if [[ ! -e "$file_path" ]]; then
+  printf '%swaiting for a review to start (%s)…%s\n' "$D" "$DIR" "$Z"
+  while [[ ! -e "$file_path" ]]; do
+    # latest may update to a new id while we wait
+    [[ -r "$DIR/latest" ]] && ID="$(head -1 "$DIR/latest")" && file_path="$DIR/$ID.jsonl"
+    sleep 1
+  done
+fi
+
+printf '%swatching %s%s\n\n' "$D" "$file_path" "$Z"
+
+if [[ $ONCE -eq 1 ]]; then
+  while IFS= read -r line; do render; done < "$file_path"
+  exit 0
+fi
+
+# Follow live. -F keeps following across truncation/rotation.
+tail -n +1 -F "$file_path" 2>/dev/null | while IFS= read -r line; do
+  render
+  printf '%s' "$(get kind)" | grep -q '^end$' && break || true
+done