cue-ai 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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 records its review to the same log, so the
+    independent merge-gate review is watchable too (verdict parsed with the progress
+    side-channel filtered out; 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

@@ -1,30 +1,3 @@
-<!--
-  Structured data for AI search engines (ChatGPT, Perplexity, Google AI Overviews)
-  and traditional crawlers. GitHub renders the README as raw HTML on github.com/<repo>
-  and via GitHub Pages, so the JSON-LD blocks below are picked up by both Google's
-  rich-results parser and LLM scrapers.
--->
-<!--
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@type": "SoftwareApplication",
-  "name": "cuecards",
-  "alternateName": ["cue", "cue-ai"],
-  "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/cuecards",
-  "downloadUrl": "https://www.npmjs.com/package/cue-ai",
-  "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" }
-}
-</script>
--->
-
 <br>
 
 <p align="center">
@@ -36,11 +9,11 @@
 <h1 align="center">cuecards.</h1>
 
 <p align="center">
-  <strong>The agent profile manager for AI coding agents.</strong>
+  <strong>The missing layer between you and your coding agent.</strong>
 </p>
 
 <p align="center">
-  <sub>Your agent walks into a directory. The cuecard tells it who to be.</sub>
+  <sub>Your agent walks into a directory. The cuecard tells it who to be — and loads only what the job needs.</sub>
 </p>
 
 <br>
@@ -70,6 +43,43 @@
 
 ---
 
+## the problem.
+
+You installed 330 skills and 15 MCP servers. Your agent re-reads **every one of them, on every message** — including the 320 it doesn't need for the task in front of it.
+
+You pay for that context on every single turn. And the model gets *worse* at picking the right tool, because it's scanning a wall of irrelevant descriptions before it can act.
+
+**cuecards loads only the cuecard for the directory you're in.** One project's skills, MCPs, persona, and gates — not your entire library. Less context, lower cost, sharper tool selection.
+
+<br>
+
+---
+
+## the money shot.
+
+> Loading everything taxes every message. cuecards cut your always-on context **~9–16×** — and you can reproduce every number below with `cue cost --compare`.
+
+| Loadout | Always-on context | Cost / 100 msgs (Sonnet input) |
+|---|---|---|
+| **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 **~9× fewer always-on tokens** on a backend loadout (≈12× on `caveman-quick`, up to ≈16× on the leanest profiles) versus loading everything. The savings compound on every message of every session.
+
+```bash
+cue cost                      # token budget for your active profile
+cue cost --compare            # full table: every profile ranked vs the `full` baseline
+```
+
+<p align="center">
+  <sub><strong>&lt; 5 ms</strong> warm launch&nbsp;·&nbsp;<strong>69</strong> pre-built cuecards&nbsp;·&nbsp;<strong>330+</strong> local skills&nbsp;·&nbsp;<strong>10</strong> AI agents&nbsp;·&nbsp;<strong>MIT</strong>&nbsp;·&nbsp;zero telemetry&nbsp;·&nbsp;no daemon</sub>
+</p>
+
+<br>
+
+---
+
 ## what is a cuecard.
 
 A **cuecard** is everything your AI coding agent needs to be useful in one directory — the skills it loads, the MCP servers it connects to, the plugins it boots with, the persona it adopts, the playbooks it follows, the quality gates that block its "done" claim.
@@ -85,6 +95,8 @@ One cuecard per project. Your agent reads the right one the moment you launch.
 | **playbooks** | the steps the agent follows for known tasks |
 | **gates** | what must pass before the agent says "done" |
 
+This is what separates cuecards from a skills list: a cuecard is *composable expertise* — persona + playbooks + gates + evals + a failure loop — not just "more tools loaded."
+
 <br>
 
 ---
@@ -116,76 +128,29 @@ Search. Install. Use. No config files to edit. Works the same with `codex`, `cur
 
 ---
 
-## works with.
-
-<p align="center">
-  <a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude_Code-cc785c?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code"></a>&nbsp;
-  <a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-000000?style=flat-square&logo=openai&logoColor=white" alt="Codex"></a>&nbsp;
-  <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=cursor&logoColor=white" alt="Cursor"></a>&nbsp;
-  <a href="https://github.com/cline/cline"><img src="https://img.shields.io/badge/Cline-5A45FF?style=flat-square" alt="Cline"></a>&nbsp;
-  <a href="https://github.com/google-gemini/gemini-cli"><img src="https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=google&logoColor=white" alt="Gemini"></a>&nbsp;
-  <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/Copilot-000000?style=flat-square&logo=github&logoColor=white" alt="Copilot"></a>&nbsp;
-  <a href="https://windsurf.com"><img src="https://img.shields.io/badge/Windsurf-06B6D4?style=flat-square" alt="Windsurf"></a>&nbsp;
-  <a href="https://github.com/RooVetGit/Roo-Code"><img src="https://img.shields.io/badge/Roo-7C3AED?style=flat-square" alt="Roo"></a>&nbsp;
-  <a href="https://sourcegraph.com/amp"><img src="https://img.shields.io/badge/Amp-FF4500?style=flat-square&logo=sourcegraph&logoColor=white" alt="Amp"></a>&nbsp;
-  <a href="https://aider.chat"><img src="https://img.shields.io/badge/Aider-14B8A6?style=flat-square" alt="Aider"></a>
-</p>
-
-<p align="center">
-  <sub>One cuecard. Ten supported agents.</sub>
-</p>
-
-<br>
-
----
-
-## by the numbers.
-
-<p align="center">
-  <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>330+</strong> local skills
-  <br><br>
-  <strong>10</strong>&nbsp;&nbsp;AI coding agents supported
-  <br><br>
-  <strong>MIT</strong>&nbsp;&nbsp;open source · zero telemetry · no daemon
-</p>
-
-<br>
-
----
-
-## the money shot.
-
-> 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`.
-
-| Loadout | Always-on context | Cost / 100 msgs (Sonnet input) |
-|---|---|---|
-| **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 **~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 --compare            # full table: every profile ranked vs the `full` baseline
-```
-
-<br>
-
----
-
-## why cuecards.
+## why cuecards — and how it compares.
 
 - **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.
+- **Five-dimensional agents.** Persona + playbooks + quality gates + evals + failure loop. Composable expertise, not just a longer tool list.
 - **One cuecard, ten agents.** The same `profile.yaml` materializes into Claude Code, Codex, Cursor, Cline, Gemini, Copilot, Windsurf, Roo, Amp, and Aider native formats.
 
+|  | cuecards | skillport / agent-skills-cli | Kiro Powers |
+|---|---|---|---|
+| Skills | ✅ | ✅ | ✅ |
+| MCPs | ✅ | — | ✅ |
+| Plugins | ✅ | — | — |
+| Per-directory profiles | ✅ | — | ◐ (IDE-only) |
+| Inheritance | ✅ | — | — |
+| Persona / playbooks / gates / evals | ✅ | — | — |
+| Multi-agent (Cursor/Cline/Copilot/etc.) | ✅ (10) | Claude only | IDE-only |
+| CLI installer | ✅ | — | — |
+| Failure-feedback loop | ✅ | — | — |
+| Daemon required | None | None | IDE process |
+
+cuecards is the only one that treats agent expertise as a composable, per-directory system.
+
 <details>
-<summary><b>Other wins</b></summary>
+<summary><b>More wins</b></summary>
 
 <br>
 
@@ -201,25 +166,6 @@ cue cost --compare            # full table: every profile ranked vs the `full` b
 
 ---
 
-## reading cue's output — the colored tags.
-
-cuecards-managed agents tag every research- or decision-relevant claim with a colored confidence marker so you can scan trust at a glance:
-
-| Tier | Tag | Meaning |
-|---|---|---|
-| 🟢 Green | `[VERIFIED]` / `[KNOWN]` | Trust it (~90–99%) |
-| 🟡 Yellow | `[INFERRED]` / `[ASSUMED]` | Verify if stakes matter (~50–85%) |
-| 🟠 Orange | `[GUESSED]` / `[STALE]` | Verify before acting (~20–45%) |
-| 🔴 Red | `[UNKNOWN]` | Don't trust; agent refused to fabricate |
-
-Optional decile calibration on yellow/orange: `🟡 [INFERRED ~80%]`, `🟠 [GUESSED ~30%]`. The `~` signals it's a rough self-estimate, not a true probability.
-
-Full system + when each tag fires: **[`resources/skills/skills/meta/integrity-tags/SKILL.md`](./resources/skills/skills/meta/integrity-tags/SKILL.md)** · Canonical protocol: **[`resources/personas/integrity-protocol.md`](./resources/personas/integrity-protocol.md)** (auto-injected into every profile via `persona_includes`).
-
-<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.
@@ -281,6 +227,19 @@ claude                        # launches with that cuecard's loadout
 
 The same `profile.yaml` materializes into each agent's native format — `.cursorrules`, `.clinerules`, `~/.gemini/skills/*.md`, `.github/copilot-instructions.md`, etc.
 
+<p align="center">
+  <a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude_Code-cc785c?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code"></a>&nbsp;
+  <a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-000000?style=flat-square&logo=openai&logoColor=white" alt="Codex"></a>&nbsp;
+  <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=cursor&logoColor=white" alt="Cursor"></a>&nbsp;
+  <a href="https://github.com/cline/cline"><img src="https://img.shields.io/badge/Cline-5A45FF?style=flat-square" alt="Cline"></a>&nbsp;
+  <a href="https://github.com/google-gemini/gemini-cli"><img src="https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=google&logoColor=white" alt="Gemini"></a>&nbsp;
+  <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/Copilot-000000?style=flat-square&logo=github&logoColor=white" alt="Copilot"></a>&nbsp;
+  <a href="https://windsurf.com"><img src="https://img.shields.io/badge/Windsurf-06B6D4?style=flat-square" alt="Windsurf"></a>&nbsp;
+  <a href="https://github.com/RooVetGit/Roo-Code"><img src="https://img.shields.io/badge/Roo-7C3AED?style=flat-square" alt="Roo"></a>&nbsp;
+  <a href="https://sourcegraph.com/amp"><img src="https://img.shields.io/badge/Amp-FF4500?style=flat-square&logo=sourcegraph&logoColor=white" alt="Amp"></a>&nbsp;
+  <a href="https://aider.chat"><img src="https://img.shields.io/badge/Aider-14B8A6?style=flat-square" alt="Aider"></a>
+</p>
+
 ```bash
 cue materialize cursor --profile backend     # → .cursorrules + .cursor/mcp.json
 cue materialize --all --profile backend      # → all 10 agents at once
@@ -308,6 +267,58 @@ cue materialize --all --profile backend      # → all 10 agents at once
 
 ---
 
+## built-in rigor.
+
+cuecards don't just load tools — they hold your agent to a standard.
+
+### The reviewer gate
+
+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**.
+
+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.** 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).
+
+### Confidence tags
+
+cuecards-managed agents tag every research- or decision-relevant claim with a colored confidence marker so you can scan trust at a glance:
+
+| Tier | Tag | Meaning |
+|---|---|---|
+| 🟢 Green | `[VERIFIED]` / `[KNOWN]` | Trust it (~90–99%) |
+| 🟡 Yellow | `[INFERRED]` / `[ASSUMED]` | Verify if stakes matter (~50–85%) |
+| 🟠 Orange | `[GUESSED]` / `[STALE]` | Verify before acting (~20–45%) |
+| 🔴 Red | `[UNKNOWN]` | Don't trust; agent refused to fabricate |
+
+Optional decile calibration on yellow/orange: `🟡 [INFERRED ~80%]`, `🟠 [GUESSED ~30%]`. The `~` signals it's a rough self-estimate, not a true probability. Full system: **[`integrity-tags/SKILL.md`](./resources/skills/skills/meta/integrity-tags/SKILL.md)** · canonical protocol auto-injected into every profile via `persona_includes`.
+
+<br>
+
+---
+
 ## daily commands.
 
 ```bash
@@ -321,10 +332,14 @@ cue cost --compare            # every profile ranked vs the `full` baseline
 
 # System dependencies
 cue cli install --all --yes   # install every missing CLI
+cue install <profile>         # dry-run: prepare Claude/Codex runtimes
+cue install <profile> --with-clis --yes
+cue install repo owner/repo --profile <profile> --yes
 
 # Quality + discovery
 cue lint-skill <path> [--fix]            # validate SKILL.md against R001-R008
 cue marketplace discover --cli-aware     # find skill repos on GitHub
+cue install doctor --all-profiles        # audit prepared runtimes
 cue failures --propose [profile]         # Claude drafts profile improvements
 
 # Audit
@@ -397,25 +412,6 @@ Cold start: 50–200 ms. Warm start: <5 ms (sha256 compare + `exec`). Impercepti
 No. Everything cue computes (including the per-skill usage bars in `cue optimizer`) reads from your local `~/.claude/projects/**/*.jsonl` transcripts. Nothing leaves the machine.
 </details>
 
-<details>
-<summary><b>What's the difference between cue and skillport / Kiro Powers?</b></summary>
-
-| | cue | skillport / agent-skills-cli | Kiro Powers |
-|---|---|---|---|
-| Skills | ✅ | ✅ | ✅ |
-| MCPs | ✅ | — | ✅ |
-| Plugins | ✅ | — | — |
-| Per-directory profiles | ✅ | — | ◐ (IDE-only) |
-| Inheritance | ✅ | — | — |
-| Persona / playbooks / gates / evals | ✅ | — | — |
-| Multi-agent (Cursor/Cline/Copilot/etc.) | ✅ (10) | Claude only | IDE-only |
-| CLI installer | ✅ | — | — |
-| Failure-feedback loop | ✅ | — | — |
-| Daemon required | None | None | IDE process |
-
-cuecards is the only one that treats agent expertise as a composable system.
-</details>
-
 <details>
 <summary><b>What does cue NOT do?</b></summary>
 
@@ -429,6 +425,26 @@ cuecards is the only one that treats agent expertise as a composable system.
 
 ---
 
+## api.
+
+cuecards.cc has free public accounts and per-user API tokens. Register in the
+**API tokens** view, mint a token (shown once), and call the API with a Bearer
+header:
+
+```bash
+curl https://cuecards.cc/api/v1/me \
+  -H "Authorization: Bearer <your-token>"
+# -> { "ok": true, "data": { "id": "...", "email": "...", "name": "..." } }
+```
+
+Auth is [BetterAuth](https://better-auth.com) (email + password) on Vercel
+serverless functions backed by Neon Postgres. Setup, env vars, the migration,
+local dev, and deploy steps live in [`web/AUTH.md`](./web/AUTH.md).
+
+<br>
+
+---
+
 ## deep dives.
 
 The bits that didn't fit on the landing page:

package/bin/cue-learnings

@@ -15,7 +15,9 @@
 #
 # Usage:
 #   cue-learnings log --type <T> --key <K> --insight <S> --confidence <N> \
-#                     --source <S> [--files <comma,list>]
+#                     --source <S> [--files <comma,list>] [--skill <cat/slug>]
+#     --skill: for a pitfall/pattern, also enqueue a skill_gap in analytics.jsonl
+#              so the auto-evolve loop improves that skill (closes learning→skill).
 #   cue-learnings search [pattern]    # most-recent first; jq if present, grep otherwise
 #   cue-learnings list                # same as search with no pattern
 #   cue-learnings path                # print the jsonl path for this project
@@ -41,7 +43,7 @@ cmd="${1:-}"
 case "$cmd" in
   log)
     shift
-    TYPE="" KEY="" INSIGHT="" CONFIDENCE="" SOURCE="" FILES=""
+    TYPE="" KEY="" INSIGHT="" CONFIDENCE="" SOURCE="" FILES="" SKILL=""
     while [[ $# -gt 0 ]]; do
       case "$1" in
         --type)        TYPE="$2"; shift 2 ;;
@@ -50,6 +52,7 @@ case "$cmd" in
         --confidence)  CONFIDENCE="$2"; shift 2 ;;
         --source)      SOURCE="$2"; shift 2 ;;
         --files)       FILES="$2"; shift 2 ;;
+        --skill)       SKILL="$2"; shift 2 ;;
         *) echo "cue-learnings log: unknown flag $1" >&2; exit 1 ;;
       esac
     done
@@ -73,9 +76,13 @@ case "$cmd" in
     fi
 
     # Sanitize key — JSONL is line-delimited; newlines break the format
+    # Strip ALL C0 control chars (not just CR/LF): a raw tab in any field would
+    # make the JSONL line unparseable, and every downstream reader silently skips
+    # a malformed line — losing the learning AND its bridged skill_gap signal.
     KEY=$(printf '%s' "$KEY" | tr -cd 'a-zA-Z0-9._-')
-    INSIGHT=$(printf '%s' "$INSIGHT" | tr -d '\n\r')
-    FILES=$(printf '%s' "$FILES" | tr -d '\n\r')
+    INSIGHT=$(printf '%s' "$INSIGHT" | tr -d '\000-\037')
+    FILES=$(printf '%s' "$FILES" | tr -d '\000-\037')
+    SKILL=$(printf '%s' "$SKILL" | tr -d '\000-\037')
 
     mkdir -p "$PROJECT_DIR"
     TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
@@ -108,6 +115,25 @@ case "$cmd" in
       >> "$LEARNINGS_FILE"
 
     echo "logged: $TYPE/$KEY ($CONFIDENCE/10) → $LEARNINGS_FILE"
+
+    # Bridge to the evolution loop: when a pitfall/pattern names a skill, also
+    # append a skill_gap event to analytics.jsonl so auto-evolve can pick that
+    # skill up. Closes the formerly-open learnings→skill-improvement loop. Only
+    # actionable types (pitfall/pattern) bridge; preferences/operational notes
+    # are about the user/process, not the skill, so they stay out of the queue.
+    if [[ -n "$SKILL" ]] && { [[ "$TYPE" == "pitfall" ]] || [[ "$TYPE" == "pattern" ]]; }; then
+      ANALYTICS="${XDG_CONFIG_HOME:-$HOME/.config}/cue/analytics.jsonl"
+      mkdir -p "$(dirname "$ANALYTICS")" 2>/dev/null || true
+      ATS=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+      # The learning is already safely written; a bridge-write failure (disk full,
+      # perms) must NOT make this command exit non-zero — degrade to a warning.
+      if printf '{"ts":"%s","event":"skill_gap","agent":"claude-code","source":"learning","skill":"%s","gap_type":"weak-body","suggestion":"%s","confidence":%d}\n' \
+          "$ATS" "$(esc "$SKILL")" "$(esc "$INSIGHT")" "$CONFIDENCE" >> "$ANALYTICS" 2>/dev/null; then
+        echo "bridged: skill_gap for '$SKILL' → $ANALYTICS"
+      else
+        echo "cue-learnings: warning — could not bridge skill_gap to analytics (learning still logged)" >&2
+      fi
+    fi
     ;;
 
   search|list)

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