cue-ai 0.4.1 → 0.5.0

package/README.md

@@ -12,9 +12,9 @@
 
 # cue — Agent Profile Manager for Claude Code, Codex & 8 more
 
-> Every `claude` session loads all **1,927** skills you've ever installed. Your model picks the wrong one. Your tokens evaporate. **cue fixes this in one command.**
+> Every `claude` session loads **all** your skills, MCPs, and plugins — every one you've ever installed. Your model picks the wrong tool. Your tokens evaporate. **cue fixes this in one command.**
 
-**Works with:** Claude Code · Codex · Cursor · Cline · Gemini · GitHub Copilot · Windsurf · Roo Code · Amp · Aider  →   [jump to the full matrix ↓](#agents-cue-supports)
+**Works with:** [![Claude Code](https://img.shields.io/badge/Claude_Code-cc785c?style=flat-square&logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) [![Codex](https://img.shields.io/badge/Codex-000000?style=flat-square&logo=openai&logoColor=white)](https://github.com/openai/codex) [![Cursor](https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.sh) [![Cline](https://img.shields.io/badge/Cline-5A45FF?style=flat-square)](https://github.com/cline/cline) [![Gemini](https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=google&logoColor=white)](https://github.com/google-gemini/gemini-cli) [![Copilot](https://img.shields.io/badge/Copilot-000000?style=flat-square&logo=github&logoColor=white)](https://github.com/features/copilot) [![Windsurf](https://img.shields.io/badge/Windsurf-06B6D4?style=flat-square)](https://windsurf.com) [![Roo Code](https://img.shields.io/badge/Roo_Code-7C3AED?style=flat-square)](https://github.com/RooVetGit/Roo-Code) [![Amp](https://img.shields.io/badge/Amp-FF4500?style=flat-square&logo=sourcegraph&logoColor=white)](https://sourcegraph.com/amp) [![Aider](https://img.shields.io/badge/Aider-14B8A6?style=flat-square)](https://aider.chat)  →  [full matrix ↓](#agents-cue-supports)
 
 ## ⚡ 60-second quickstart
 
@@ -30,28 +30,65 @@ That's it. `cd` into any other repo and `claude` will boot with that repo's prof
   <img src="./docs/assets/demo.gif" alt="cue 30-second demo — install, pin a profile, optimize, launch" width="820" onerror="this.style.display='none'">
 </p>
 
-> **No GIF yet?** Generate it with [`vhs`](https://github.com/charmbracelet/vhs): `vhs docs/demo.tape` → writes `docs/assets/demo.gif`.
-
 <details>
 <summary>📑 <b>Table of contents</b></summary>
 
+- [5 commands you need](#-5-commands-you-need)
+- [Before & After — token cost](#-before--after--token-cost)
 - [Why a profile manager at all?](#why-a-profile-manager-at-all)
+- [Skills are not just prompts](#skills-are-not-just-prompts)
 - [How cue compares](#how-cue-compares)
 - [How it works](#how-it-works)
 - [Agents cue supports](#agents-cue-supports)
 - [`cue optimizer` — see every loadout at a glance](#cue-optimizer--see-every-loadout-at-a-glance)
-- [The 16-profile catalog](#the-16-profile-catalog)
+- [The 23-profile catalog](#the-23-profile-catalog)
+- [Create your own profile in 30 seconds](#️-create-your-own-profile-in-30-seconds)
+- [`cue share` — community profiles](#-cue-share--community-profiles)
 - [Install](#install)
 - [What ships with each profile](#what-ships-with-each-profile-the-lean-stack)
 - [FAQ](#faq)
 - [Repo layout](#repo-layout)
 - [Built with / built on](#built-with--built-on)
+- [Star History](#star-history)
 - [Contributing](#contributing)
 
 </details>
 
 ---
 
+## 🧠 5 commands you need
+
+```bash
+cue use <profile>            # switch profile for this directory
+cue list                     # see all available profiles
+cue optimizer                # audit: skills, MCPs, CLIs, usage per profile
+cue doctor --fix             # diff declared vs actual state, auto-repair
+cue skills add <github-url>  # install a skill from GitHub into a profile
+```
+
+That covers 90% of daily use. Everything else (`cue share`, `cue materialize`, `cue tree`, etc.) is there when you need it — run `cue --help` for the full list.
+
+---
+
+## 📊 Before & After — token cost
+
+> **TL;DR** — loading everything costs you tokens on every single message. cue cuts context size by 10–25×.
+
+| Scenario | Context loaded | Tokens per session | Cost (Sonnet) |
+|---|---|---|---|
+| **Without cue** — all 1,927 skills + 15 MCPs | ~180k tokens | ~$2.70/session | 😱 |
+| **With cue** — `backend` profile (12 skills, 2 MCPs) | ~8k tokens | ~$0.12/session | ✅ |
+| **With cue** — `caveman-quick` (3 skills, 0 MCPs) | ~2k tokens | ~$0.03/session | 🚀 |
+
+That's **22× fewer tokens** for a typical backend session. Over a day of 20 sessions, you save ~$50 in raw API cost — or equivalently, your model picks the right tool on the first try because it's not drowning in 1,900 irrelevant skill descriptions.
+
+```bash
+cue cost                      # see token budget for your active profile
+cue cost --profile full       # compare against the "everything" baseline
+```
+
+---
+
 ## Why a profile manager at all?
 
 > **TL;DR** — without cue, every `claude` session loads every skill, MCP, and plugin you've ever installed. cue scopes the loadout per-directory so each repo only sees what it actually needs.
@@ -67,6 +104,74 @@ That's it. `cd` into any other repo and `claude` will boot with that repo's prof
 - **Materialized, hash-short-circuited.** Each launch rebuilds the runtime only when the resolved profile actually changed. Cold-start cost is a `stat()` + sha256 compare.
 - **No service to run.** No daemon, no background process, no auto-update. Just a Bun CLI and a shim script in `~/.local/bin`.
 
+### Profile inheritance
+
+Profiles compose via single-parent inheritance. Each child adds or overrides what it needs:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  core                                                       │
+│  claude-mem · caveman · RTK · gbrain                        │
+└──────────┬──────────────────┬───────────────────┬───────────┘
+           │                  │                   │
+    ┌──────▼──────┐    ┌──────▼──────┐     ┌──────▼──────┐
+    │  backend    │    │  frontend   │     │  marketing  │
+    │  +12 skills │    │  +8 skills  │     │  +6 skills  │
+    │  +coolify   │    │  +playwright│     │  +seo-mcp   │
+    └──────┬──────┘    └─────────────┘     └─────────────┘
+           │
+    ┌──────▼──────┐
+    │  medusa-dev │
+    │  +medusa/*  │
+    │  +medusadocs│
+    └─────────────┘
+```
+
+Child profiles inherit all skills, MCPs, and plugins from their parent. Override or extend — never duplicate.
+
+---
+
+## Skills are not just prompts
+
+> **TL;DR** — a cue skill isn't a markdown file the model reads and forgets. It's a **wired capability** — a skill declares which CLIs it needs, which MCP tools it calls, and cue ensures all three layers (skill + MCP + CLI) are present and connected before the session starts.
+
+Most "skill" tools stop at prompt injection: paste markdown into the context window and hope the model follows it. That works for style guides. It doesn't work for *doing things*.
+
+A real capability has three layers:
+
+| Layer | What it does | Example |
+|---|---|---|
+| **Skill** (the instruction) | Tells the model *when* and *how* to act | "When user says 'analyze video', extract frames at 1 fps…" |
+| **MCP server** (the tool) | Gives the model a callable function | `video_watch`, `gbrain__put_page`, `excel__create_workbook` |
+| **CLI** (the runtime) | The binary the MCP or skill shells out to | `ffmpeg`, `yt-dlp`, `whisper-cpp`, `uv` |
+
+**Without cue**, you install these independently and pray they line up. A skill references an MCP that isn't running. An MCP calls a CLI that isn't installed. The model hallucinates a tool name because 40 other MCPs are polluting the namespace.
+
+**With cue**, a profile declares all three as a unit:
+
+```yaml
+# profiles/video/profile.yaml
+skills:
+  local:
+    - design/headless-gif-demo     # ← knows it needs ffmpeg
+plugins:
+  - claude-video-vision@jordanrendric  # ← registers video_watch MCP
+mcps: []                               # ← inherited gbrain from core
+```
+
+`cue optimizer` then verifies the full stack:
+
+```
+video profile
+  ✅ ffmpeg        installed (/usr/bin/ffmpeg)
+  ✅ yt-dlp        installed (~/.local/bin/yt-dlp)
+  ❌ whisper-cpp   missing → brew install whisper-cpp
+  ✅ MCP: video_watch (claude-video-vision plugin)
+  ✅ MCP: gbrain (inherited from core)
+```
+
+**The result:** when the model receives a skill, it's not reading a suggestion — it's reading a contract backed by tools that are actually there. Skills become reliable capabilities, not hopeful prompts.
+
 ---
 
 ## How cue compares
@@ -203,16 +308,16 @@ Each card shows what's actually loaded *plus* how often you've reached for each
 
 ---
 
-## The 16-profile catalog
+## The 23-profile catalog
 
-> **TL;DR** — 16 profiles ship with cue: `core`, `backend`, `frontend`, `marketing`, `medusa-dev`, `cybersecurity`, `nvidia`, `creative-media`, `docs-writer`, `caveman-quick`, `coolify`, `hostinger`, `fleet-control`, `readme-writer`, `full`, plus the per-OS `setup` profile. Switch with `cue use <name>`.
+> **TL;DR** — 23 profiles ship with cue: `core`, `backend`, `frontend`, `nextjs`, `python-api`, `rust`, `go-api`, `marketing`, `medusa-dev`, `cybersecurity`, `nvidia`, `creative-media`, `docs-writer`, `caveman-quick`, `coolify`, `hostinger`, `fleet-control`, `readme-writer`, `full`, `research`, `threejs`, `video`, `affiliate`, plus the per-OS `setup` profile. Switch with `cue use <name>`.
 
 <p align="center">
   <img src="./docs/assets/profiles-grid.svg" alt="The 16 profiles shipped with cue" width="820">
 </p>
 
 <details>
-<summary>📋 <b>All 16 profiles as a table</b> (for screen readers / LLM ingestion)</summary>
+<summary>📋 <b>All 23 profiles as a table</b> (for screen readers / LLM ingestion)</summary>
 
 | Profile | Domain |
 |---|---|
@@ -231,6 +336,14 @@ Each card shows what's actually loaded *plus* how often you've reached for each
 | `hostinger` | Hostinger DNS, domain, VPS, hosting management. |
 | `fleet-control` | Multi-agent orchestration, Colony coordination, OMX flows. |
 | `full` | Diagnostic fallback — loads every local skill and MCP. |
+| `research` | Deep research, literature review, citation management. |
+| `threejs` | Three.js 3D scenes, shaders, WebGL, interactive visuals. |
+| `video` | Video/GIF analysis — frame extraction, transcription, Claude Vision. |
+| `affiliate` | Affiliate marketing, link management, conversion tracking. |
+| `nextjs` | Next.js full-stack — App Router, Server Components, API routes, Vercel. |
+| `python-api` | Python API — FastAPI, Django, Flask, SQLAlchemy, Alembic, pytest. |
+| `rust` | Rust — cargo, async, traits, error handling, CLI tools, systems. |
+| `go-api` | Go API — net/http, gin/echo/chi, GORM, migrations, testing. |
 | `setup` | Per-OS install assistant. |
 
 Canonical source: [`docs/data/profiles.md`](./docs/data/profiles.md).
@@ -245,6 +358,54 @@ claude                        # launches with medusa-dev's loadout
 
 ---
 
+## 🛠️ Create your own profile in 30 seconds
+
+```bash
+cue new my-stack                              # scaffold profile.yaml
+```
+
+Edit the generated file:
+
+```yaml
+# profiles/my-stack/profile.yaml
+name: my-stack
+icon: "🔧"
+description: My custom dev environment
+inherits: core                                # gets claude-mem, caveman, RTK, gbrain
+skills:
+  local:
+    - review/code-review
+    - meta/rtk-context-trim
+mcps:
+  - gbrain
+```
+
+Activate it:
+
+```bash
+cue use my-stack                              # pin to current directory
+cue doctor --fix                              # verify everything resolves
+claude                                        # launches with your loadout
+```
+
+Want to start from what's already in a project? `cue init` scans your repo and suggests a profile based on detected languages, frameworks, and config files.
+
+---
+
+## 🌐 `cue share` — community profiles
+
+> **TL;DR** — publish your profile as a GitHub Gist, browse what others have shared, install with one command.
+
+```bash
+cue share publish --profile backend           # upload to your GitHub Gists
+cue share browse                              # see community profiles
+cue share install <gist-id>                   # pull someone else's profile
+```
+
+Shared profiles include the full `profile.yaml` + metadata (skill count, MCP list, description). Browse profiles others have published, fork them, or use them as a starting point for your own.
+
+---
+
 ## Install
 
 > **TL;DR** — `npm install -g cue-ai`, then `echo <profile> > .cue-profile` in any repo. Idempotent. No daemon. Uninstall with `install.sh --uninstall`.
@@ -283,6 +444,22 @@ claude
 | **gbrain** MCP | Personal wiki with embeddings + backlinks |
 | **excel-mcp** / **word-mcp** | Native `.xlsx` / `.docx` read & write |
 
+### 💰 Token savings stack
+
+The combination of **profile isolation + RTK + caveman** compounds:
+
+| Optimization | What it cuts | Savings |
+|---|---|---|
+| **Profile isolation** | Irrelevant skills/MCPs never loaded | 10–25× fewer context tokens |
+| **RTK** | Filters `ls`, `git log`, `cat` output before it hits the model | 60–90% per shell command |
+| **Caveman mode** | Terse responses, no filler | ~40% fewer output tokens |
+| **Combined** | All three together | **$2.70 → $0.08/session** typical |
+
+```bash
+rtk gain                      # see your cumulative RTK savings
+cue cost                      # token budget for active profile
+```
+
 Want to **run 2+ agents in parallel on one repo**? Layer the optional **Colony + gitguardex** tier — see [`setup/parallel-agents.md`](./setup/parallel-agents.md). Skip it for solo work.
 
 ---
@@ -402,6 +579,46 @@ Plus the **brand logos** you see in the optimizer dashboard and hero come from e
 
 ---
 
+## Who uses cue
+
+Projects and teams using `.cue-profile` in production:
+
+| Project | Profile | What they do |
+|---------|---------|-------------|
+| [recodeee/cue](https://github.com/recodeee/cue) | `full`, `readme-writer` | This repo — 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?** Add your project — open a PR or drop a link in [Discussions](https://github.com/recodeee/cue/discussions).
+
+---
+
+## Star History
+
+<a href="https://star-history.com/#recodeee/cue&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=recodeee/cue&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=recodeee/cue&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=recodeee/cue&type=Date" width="720" />
+  </picture>
+</a>
+
+---
+
+## Who uses cue
+
+Projects and teams using `.cue-profile` in production:
+
+| Project | Profile | What they do |
+|---------|---------|-------------|
+| [recodeee/cue](https://github.com/recodeee/cue) | `full`, `readme-writer` | This repo — 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?** Add your project — open a PR or drop a link in [Discussions](https://github.com/recodeee/cue/discussions).
+
+---
+
 ## Contributing
 
 Each skill is a folder with `SKILL.md` (frontmatter + body). The frontmatter `description` is what the LLM matches against — write it as `"when user says X, do Y"`. Copy an existing skill as a template, drop it under `resources/skills/skills/<category>/<slug>/`, and the catalog regenerates on the next sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cue-ai",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "cue — Agent Profile Manager for Claude Code & Codex. Pick a profile, launch with the right skills, MCPs, and plugins.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
   "scripts": {
     "cue": "bun src/index.ts",
     "test": "bun test",
-    "build": "bun build src/index.ts --no-bundle"
+    "build": "bun build src/index.ts --no-bundle",
+    "postinstall": "echo '' && echo '  ✅ cue installed. Run: cue init' && echo '  Docs: https://github.com/recodeee/cue' && echo ''"
   },
   "keywords": [
     "claude-code",

package/profiles/affiliate/profile.yaml

@@ -0,0 +1,67 @@
+name: affiliate
+icon: "💰"
+description: "Affiliate marketing flywheel — 52 skills across research, content, SEO, landing pages, distribution, analytics, and automation"
+inherits: core
+skills:
+  npx:
+    - repo: Affitor/affiliate-skills
+      skills:
+        # S1: Research & Discovery
+        - affiliate-program-search
+        - niche-opportunity-finder
+        - competitor-spy
+        - commission-calculator
+        - monopoly-niche-finder
+        - purple-cow-audit
+        - trending-content-scout
+        - content-angle-ranker
+        - traffic-analyzer
+        # S2: Content Creation
+        - viral-post-writer
+        - twitter-thread-writer
+        - reddit-post-writer
+        - tiktok-script-writer
+        - content-pillar-atomizer
+        - content-research-brief
+        - infographic-generator
+        # S3: Blog & SEO
+        - affiliate-blog-builder
+        - comparison-post-writer
+        - listicle-generator
+        - how-to-tutorial-writer
+        - keyword-cluster-architect
+        - content-moat-calculator
+        - content-decay-detector
+        # S4: Offers & Landing Pages
+        - landing-page-creator
+        - product-showcase-page
+        - squeeze-page-builder
+        - webinar-registration-page
+        - grand-slam-offer
+        - bonus-stack-builder
+        - guarantee-generator
+        - value-ladder-architect
+        # S5: Distribution & Deployment
+        - bio-link-deployer
+        - email-drip-sequence
+        - social-media-scheduler
+        - github-pages-deployer
+        # S6: Analytics & Optimization
+        - conversion-tracker
+        - ab-test-generator
+        - performance-report
+        - seo-audit
+        - internal-linking-optimizer
+        # S7: Automation & Scale
+        - email-automation-builder
+        - content-repurposer
+        - multi-program-manager
+        - paid-ad-copy-writer
+        - proprietary-data-generator
+        # S8: Meta
+        - skill-finder
+        - funnel-planner
+        - compliance-checker
+        - self-improver
+        - category-designer
+mcps: []

package/profiles/go-api/profile.yaml

@@ -0,0 +1,8 @@
+name: go-api
+icon: "🐹"
+description: Go API development — net/http, gin/echo/chi, GORM, migrations, testing
+inherits: core
+skills:
+  local:
+    - review/code-review
+mcps: []

package/profiles/marketing/profile.yaml

@@ -1,6 +1,6 @@
 name: marketing
 icon: "🦜"
-description: Marketing — copywriting, SEO, CRO, growth, channels, brand
+description: Marketing — copywriting, SEO, CRO, growth, channels, brand, awesome-list outreach, X/Twitter
 inherits: core
 skills:
   local:
@@ -8,5 +8,8 @@ skills:
     - design/gpt-taste
     - design/high-end-visual-design
     - design/imagegen-frontend-web
+    - meta/awesome-list-submit
+mcps:
+  - x-api
 plugins:
   - marketing-skills@claude-code-skills

package/profiles/nextjs/profile.yaml

@@ -0,0 +1,8 @@
+name: nextjs
+icon: "▲"
+description: Next.js full-stack — App Router, Server Components, API routes, Vercel deploy
+inherits: frontend
+skills:
+  local:
+    - review/code-review
+mcps: []

package/profiles/python-api/profile.yaml

@@ -0,0 +1,8 @@
+name: python-api
+icon: "🐍"
+description: Python API development — FastAPI, Django, Flask, SQLAlchemy, Alembic, pytest
+inherits: core
+skills:
+  local:
+    - review/code-review
+mcps: []

package/profiles/rust/profile.yaml

@@ -0,0 +1,8 @@
+name: rust
+icon: "🦀"
+description: Rust development — cargo, async, traits, error handling, CLI tools, systems programming
+inherits: core
+skills:
+  local:
+    - review/code-review
+mcps: []

package/profiles/video/profile.yaml

@@ -0,0 +1,10 @@
+name: video
+icon: "🎬"
+description: Video and GIF analysis — frame extraction, audio transcription, and visual understanding via ffmpeg + Claude Vision
+inherits: core
+skills:
+  local:
+    - design/headless-gif-demo
+plugins:
+  - claude-video-vision@jordanrendric
+mcps: []

package/resources/mcps/configs/claude_runtime.sanitized.json

@@ -113,8 +113,22 @@
     },
     "cue-tty-watch": {
       "command": "/home/deadpool/Documents/cue/resources/mcps/cue-tty-watch/bin/cue-tty-watch"
+    },
+    "x-api": {
+      "command": "npm",
+      "args": [
+        "start"
+      ],
+      "cwd": "${HOME}/.x-api-mcp",
+      "env": {
+        "X_API_KEY": "${X_API_KEY}",
+        "X_API_SECRET": "${X_API_SECRET}",
+        "X_BEARER_TOKEN": "${X_BEARER_TOKEN}",
+        "X_ACCESS_TOKEN": "${X_ACCESS_TOKEN}",
+        "X_ACCESS_TOKEN_SECRET": "${X_ACCESS_TOKEN_SECRET}"
+      }
     }
   },
   "source": "claude_runtime",
   "source_path": "~/.claude.json"
-}
+}

package/resources/skills/skills/design/headless-gif-demo/SKILL.md

@@ -1,10 +1,14 @@
 ---
-description: "When user asks to record a high-quality CLI demo GIF that needs Kitty graphics protocol (real PNG icons inline) — use this headless Xvfb + Kitty + tmux + ffmpeg pipeline instead of vhs/asciinema which don't speak the Kitty protocol"
-requires_mcps: []
-allowed-tools: Bash(Xvfb:*), Bash(kitty:*), Bash(tmux:*), Bash(xdotool:*), Bash(ffmpeg:*), Bash(/usr/bin/ffmpeg:*), Read(*), Write(*)
+description: "When user asks to record a high-quality CLI demo GIF that needs Kitty graphics protocol (real PNG icons inline) — use this headless cage/Wayland + Kitty + tmux + ffmpeg pipeline instead of vhs/asciinema which don't speak the Kitty protocol. Includes auto-redaction of moving text via tesseract OCR."
+requires_mcps: [cue-tty-watch]
+allowed-tools: Bash(cage:*), Bash(weston:*), Bash(Xvfb:*), Bash(kitty:*), Bash(tmux:*), Bash(xdotool:*), Bash(wf-recorder:*), Bash(grim:*), Bash(ffmpeg:*), Bash(/usr/bin/ffmpeg:*), Bash(tesseract:*), Bash(convert:*), Read(*), Write(*), mcp__cue-tty-watch__*
 ---
 
-# Headless GIF demos with Kitty + tmux + Xvfb + ffmpeg
+# Headless GIF demos with Cage (Wayland) + Kitty + tmux + auto-redaction
+
+> Updated pipeline: prefer **cage** (headless wlroots compositor) over Xvfb when on a Wayland host.
+> Kitty graphics protocol works through wf-recorder → real brand-icon PNGs render in the GIF.
+> Tesseract OCR + `redact_video` MCP tool handles moving-text redaction automatically.
 
 When you need a demo GIF of a CLI tool that uses **Kitty graphics protocol** (e.g. cue's brand-logo PNGs in `cue optimizer`), `vhs` and `asciinema` won't work — they render in `ttyd` which doesn't speak the protocol. Logos show as garbled placeholder boxes or fall back to emoji.
 
@@ -20,15 +24,19 @@ This skill captures the working pipeline: spin up a virtual X display, run real
 
 ## Required tools
 
-| Tool | Install (apt) | Install (nix) |
+| Tool | Purpose | Install |
 |---|---|---|
-| `Xvfb` | `sudo apt install xvfb` | `nix profile install nixpkgs#xorg.xorgserver` |
-| `xdotool` | `sudo apt install xdotool` | `nix profile install nixpkgs#xdotool` |
-| `ffmpeg` with `x11grab` | `sudo apt install ffmpeg` (**not** nix-pure ffmpeg — that one lacks x11grab) | `nix profile install nixpkgs#ffmpeg-full` |
-| `kitty` | already on your box | — |
-| `tmux` | already on your box | — |
-
-**Gotcha:** verify ffmpeg has x11grab with `ffmpeg -devices | grep x11`. nix's stock `ffmpeg` doesn't ship it — use `/usr/bin/ffmpeg` (apt) or `ffmpeg-full` (nix).
+| `cage` | Headless wlroots compositor (preferred over weston — speaks `wlr-screencopy`) | `sudo apt install cage` |
+| `wf-recorder` | Wayland screen capture (needs wlroots compositor) | `sudo apt install wf-recorder` |
+| `grim` | Wayland screenshot (for preflight checks) | `sudo apt install grim` |
+| `kitty` | Terminal with graphics protocol — renders brand PNGs inline | already there |
+| `tmux` | Drives the demo via `send-keys` (works on any display protocol) | already there |
+| `/usr/bin/ffmpeg` (apt) | Used to convert mp4→gif. Nix's `ffmpeg` lacks `x11grab`/`palettegen` features sometimes — apt build is safer. | `sudo apt install ffmpeg` |
+| `tesseract` | OCR for auto-redaction. Returns bounding boxes per word/line. | `sudo apt install tesseract-ocr tesseract-ocr-eng` |
+| `ollama` + `moondream` | Optional: fast vision Q&A ("is the splash visible yet?") | `ollama pull moondream` |
+| `opencv-python`, `scenedetect`, `numpy`, `pillow` | Vision scripting in `~/.venvs/video` (or similar) | `pip install opencv-python-headless scenedetect numpy pillow` |
+
+**Fallback (X11-only systems):** `Xvfb` + `ffmpeg x11grab` + `xdotool`. Same shape, X-only verbs.
 
 ## The pipeline
 
@@ -166,3 +174,40 @@ Pathological capture (means kitty didn't render to Xvfb):
 3. Test-run; check the preflight screenshot is non-empty
 4. Iterate on timing — pickers and Claude Code splash both need 2–3 s headroom
 5. Commit both the script and the resulting GIF — re-running gives byte-identical output for a fixed tape
+
+## Auto-redaction with the cue-tty-watch MCP
+
+When the demo captures sensitive moving text (email in a splash card that scrolls as content is added below), don't fight per-frame `drawbox` coordinates by hand. The `cue-tty-watch` MCP (autoloaded on every cue profile via `core` inheritance) wraps tesseract + scenedetect + moondream so the agent can do this automatically:
+
+| MCP tool | Backed by | Use when |
+|---|---|---|
+| `screenshot(display)` | `xwd` / `grim` | "What's on the headless display right now?" |
+| `tmux_pane(socket, session)` | `tmux capture-pane -p` | "What text did the inner shell render?" |
+| `send_keys_tmux(...)` | `tmux send-keys` | Drive the demo non-interactively |
+| `find_text(image, query)` | `tesseract` | Get `{x,y,w,h}` for every occurrence of a substring in a frame |
+| `ask_about_image(image, q)` | `ollama` + `moondream` | Fast yes/no-style vision Q&A ("did the splash render?") |
+| `detect_scenes(video)` | `scenedetect` (`ContentDetector`) | Find scene-cut timestamps automatically |
+| **`redact_video(in, out, query)`** | All of the above | **One call**: walks the video, OCRs each sampled frame, finds `query`, builds per-frame drawbox+drawtext filter, encodes the output |
+
+`redact_video` is the killer. The "email scrolls up as Claude responds and my fixed drawbox is in the wrong place" problem reduces to:
+
+```jsonc
+// MCP call
+{
+  "tool": "redact_video",
+  "input_path": "/tmp/cue-demo-raw.mp4",
+  "output_path": "/tmp/cue-demo-redacted.mp4",
+  "query": "webubusiness",
+  "label": "[ account info · redacted ]",
+  "samples_per_second": 4,
+  "pad": 6
+}
+```
+
+Then convert the redacted mp4 → gif with the standard 2-pass palette pipeline.
+
+Why this beats the manual approach:
+- No more 3-phase time-gated drawboxes that leak at transitions
+- Adapts automatically to any future demo (different fonts, scroll speeds, splash layouts)
+- Handles boundaries cleanly — text disappears one frame, box disappears the next
+- Works for ANY moving sensitive text, not just the email row