cue-ai 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -15,9 +15,10 @@ adheres to [Semantic Versioning](https://semver.org/).
   - `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).
+  - 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.

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,63 +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>
-
----
-
-## 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.
@@ -319,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
@@ -346,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
@@ -359,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
@@ -435,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>
 
@@ -467,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)