cue-ai 0.9.0 → 0.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.
 
@@ -307,8 +317,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 +344,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 +358,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 +451,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 +463,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 +478,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 +489,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).