cue-ai 0.3.0 → 0.4.0

package/README.md

@@ -1,305 +1,411 @@
-# cue — Agent Profile Manager for Claude Code & Codex
+<p align="center">
+  <img src="./docs/assets/hero.svg" alt="cue — Agent Profile Manager for Claude Code & Codex" width="820">
+</p>
 
-> Pick a profile. Launch with the right skills, MCPs, and plugins. Nothing else.
+<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=6366f1" alt="npm version"></a>
+  <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=22c55e" alt="npm downloads"></a>
+  <a href="https://github.com/recodeee/cue/stargazers"><img src="https://img.shields.io/github/stars/recodeee/cue?style=flat-square&label=★&color=fbbf24" alt="GitHub stars"></a>
+  <a href="https://github.com/recodeee/cue/commits/main"><img src="https://img.shields.io/github/last-commit/recodeee/cue?style=flat-square&label=last%20commit&color=ec4899" alt="last commit"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/recodeee/cue?style=flat-square&color=8b5cf6" alt="MIT license"></a>
+</p>
 
-`cue` is a CLI that sits between your shell and the agent binary. Type `claude` or `codex` and `cue` intercepts: it resolves which profile applies in the current directory, materializes an isolated `CLAUDE_CONFIG_DIR` (or `CODEX_HOME`) with just that profile's skills, MCP servers, and Claude Code plugins, then exec's the real agent. Per-directory pins mean the right loadout follows the project, not the terminal session.
+# cue — Agent Profile Manager for Claude Code, Codex & 8 more
 
-## Why cue?
+> 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.**
+
+**Works with:** Claude Code · Codex · Cursor · Cline · Gemini · GitHub Copilot · Windsurf · Roo Code · Amp · Aider &nbsp;→ &nbsp; [jump to the full matrix ↓](#agents-cue-supports)
+
+## ⚡ 60-second quickstart
+
+```bash
+npm install -g cue-ai                          # 1. install
+cd ~/projects/q4-launch && echo marketing > .cue-profile   # 2. pin a profile to this repo
+claude                                         # 3. boots with only the marketing loadout
+```
+
+That's it. `cd` into any other repo and `claude` will boot with that repo's profile instead — no flags, no env vars, no daemon.
+
+<p align="center">
+  <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>
+
+- [Why a profile manager at all?](#why-a-profile-manager-at-all)
+- [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)
+- [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)
+- [Contributing](#contributing)
+
+</details>
+
+---
+
+## 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.
+
+<p align="center">
+  <img src="./docs/assets/isolation-comparison.svg" alt="Per-session loadout — without cue vs with cue" width="820">
+</p>
 
 - **Per-profile isolation.** Skills, MCP servers, and Claude Code plugins are scoped to the active profile. Marketing work doesn't see frontend's MCPs; backend doesn't see design's skills. No more "every session has every tool" overload.
 - **Directory-aware.** Pin a profile to a directory (`.cue-profile`), and every `claude` / `codex` you launch from inside boots with that loadout automatically. No flag wrangling.
 - **Composable.** Profiles inherit from a `core` baseline so cross-session memory (claude-mem) and meta skills are shared by default. Add team-wide tools in one place.
 - **Pre-launch picker.** First time you type `claude` in a fresh directory, a TUI picker opens. Pin or one-shot — your choice.
-- **Materialized, hash-short-circuited.** Each launch rebuilds the runtime only when the resolved profile actually changed. Cold-start cost is a stat + sha256 compare.
+- **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`.
 
-## Repo layout
+---
 
-- `profiles/` — one directory per profile; a YAML decides what loads. Inheritance chains depth-3, agents=[claude-code|codex] scoping per resource.
-- `resources/skills/` — local skill library composed into profiles. Source for the `skills/local:` field.
-- `resources/mcps/` — MCP server configs (`claude.sanitized.json`, `codex.sanitized.json`) composed into profiles.
-- `plugins/cue/` — the Claude Code plugin shipping `/cue`, `/cue switch`, `/cue reload`, `/cue current` slash commands.
-- `src/` — the Bun CLI itself: `commands/`, `lib/{cwd-resolver,picker,runtime-materializer,...}`.
-- `setup/` — per-OS install prompts you can paste into an agent session.
-- `docs/` — `launch.md` (hot-path flow), `shell-install.md` (shim install + PATH), `superpowers/specs/` (design + plans).
+## How cue compares
 
-License: [MIT](./LICENSE).
+> **TL;DR** — `claude-code-switcher` swaps MCPs only; `skillport` / `skillshub` / `agent-skills-cli` / `agent-skill-manager` / `add-skills` deliver skills only; Kiro Powers is IDE-locked. **cue is the only tool that composes skills + MCPs + plugins together, per-directory, with inheritance and materialized isolation.**
 
----
+<p align="center">
+  <img src="./docs/assets/comparison.svg" alt="Feature matrix: cue is the only tool covering skills + MCPs + plugins + profiles + per-directory + isolation + inheritance" width="880">
+</p>
 
-## Install (one line)
+Several tools touch parts of the problem — switching MCP configs, distributing skills, installing from marketplaces. **cue is the only one that treats the full agent loadout (skills + MCPs + plugins) as a composable, inheritable, directory-aware profile system.**
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash
-```
+Quick links to each tool: [`claude-code-switcher`](https://github.com/search?q=claude-code-switcher) · [`skillport`](https://github.com/search?q=skillport) · [`agent-skills-cli`](https://github.com/search?q=agent-skills-cli) · [`agent-skill-manager`](https://pypi.org/project/agent-skill-manager/) · [`skillshub`](https://github.com/search?q=skillshub) · [`add-skills`](https://github.com/search?q=add-skills) · **Kiro Powers** (IDE-only).
 
-This installs bun (if needed), clones the repo to `~/Documents/cue`, and runs the interactive installer.
+<details>
+<summary>📊 <b>Same matrix as a markdown table</b> (for screen readers / LLM ingestion)</summary>
 
-**Options:**
+| Tool | skills | MCPs | plugins | profiles | per-dir | isolation | inherit |
+|---|---|---|---|---|---|---|---|
+| **cue** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| claude-code-switcher | — | ✅ | — | ◐ | — | — | — |
+| skillport | ✅ | — | — | — | — | — | — |
+| agent-skills-cli | ✅ | — | — | — | — | — | — |
+| agent-skill-manager | ✅ | — | — | — | — | — | — |
+| skillshub | ✅ | — | — | — | — | — | — |
+| add-skills | ✅ | — | — | — | — | — | — |
+| Kiro Powers | ✅ | ✅ | — | — | ◐ | — | — |
 
-```bash
-# Non-interactive (auto-yes)
-curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash -s -- --yes
+Canonical source: [`docs/data/comparison.md`](./docs/data/comparison.md).
 
-# Custom install location
-CUE_DIR=~/dev/cue curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh | bash
-```
+</details>
 
-**Or clone manually:**
+**Where cue is the only one:**
 
-```bash
-git clone https://github.com/recodeee/cue.git ~/Documents/cue && ~/Documents/cue/install.sh
-```
+1. **`.cue-profile` per-directory pinning** — `cd` into a repo, the right loadout loads automatically.
+2. **Materialized isolation** — builds a real `CLAUDE_CONFIG_DIR` per profile, not just a config swap.
+3. **Hash-cached rebuilds** — content-addressed sha256 check, <5 ms when unchanged.
+4. **Three dimensions as one unit** — skills + MCPs + plugins composed together. Others manage one at a time.
+5. **Inheritance with merge semantics** — `core → backend → medusa-dev` chains; child overrides parent cleanly.
+6. **Shim-based interception** — type `claude` like always. The right environment just shows up.
+7. **No daemon** — pure CLI, no background process, nothing to monitor.
+8. **`cue optimizer` dashboard** — visual audit of every profile's loadout, install status, and per-skill usage scanned from your actual session transcripts.
 
-`install.sh` is interactive: it installs the `claude` shim by default and asks before touching `codex` (in case you already have a wrapper there). Non-interactive variants:
+---
 
-```bash
-~/Documents/cue/install.sh --yes           # install claude shim, skip codex prompt
-~/Documents/cue/install.sh --yes --codex   # install both shims (clobbers existing codex on PATH)
-~/Documents/cue/install.sh --uninstall     # remove the symlinks, leave the repo
-```
+## How it works
 
-### What the installer does
+> **TL;DR** — three steps on every `claude`/`codex` invocation: **resolve** the profile from `.cue-profile` (walks up to `$HOME`), **materialize** `~/.config/cue/runtime/<profile>/` if the content hash changed, then **exec** the real binary with `CLAUDE_CONFIG_DIR` / `CODEX_HOME` set.
 
-1. Verifies `git` and `bun` (Bun ≥ 1.0; install from https://bun.sh)
-2. Runs `bun install` inside the repo
-3. Self-checks `bin/cue --version`
-4. Symlinks `~/.local/bin/cue` → `<repo>/bin/cue`
-5. Checks that `~/.local/bin` is on your `$PATH` (warns if not)
-6. Writes the `~/.local/bin/claude` shim (and optionally `codex`)
+<p align="center">
+  <img src="./docs/assets/architecture.svg" alt="Launch flow: resolve → materialize → exec" width="820">
+</p>
 
-Idempotent. Safe to re-run on any machine that already has cue installed.
+Typing `claude` or `codex` in a repo where cue's shims are installed triggers a three-step launch flow:
 
-### After install
+1. **Resolve** — cue checks for a `.cue-profile` file in the current directory (or any parent up to `$HOME`). If none is found, it falls back to a repo-level default, a global default, or opens the TUI picker.
+2. **Materialize** — cue builds `~/.config/cue/runtime/<profile>/{claude,codex}/` with a content-addressed hash check. If the profile hasn't changed, this is a no-op.
+3. **Exec** — the real `claude` or `codex` binary is launched with `CLAUDE_CONFIG_DIR` (or `CODEX_HOME`) pointing at the materialized runtime tree.
+
+Full resolve-precedence rules and bypass paths: **[docs/launch.md](./docs/launch.md)**.
+
+---
+
+## Agents cue supports
+
+> **TL;DR** — **10 agents**: Claude Code, Codex, Cursor, Cline, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, Sourcegraph Amp, Aider. One `profile.yaml` materializes into each agent's native format (`.cursorrules`, `.clinerules`, `~/.gemini/skills/*.md`, `.github/copilot-instructions.md`, etc.).
+
+Originally built for Claude Code & Codex — now **one profile, ten agents**. The same `profile.yaml` (skills + MCPs) materializes into the exact format each agent expects.
 
 ```bash
-cd ~/projects/q4-launch-campaign
-echo marketing > .cue-profile
-claude          # boots with the marketing profile's skills, MCPs, and plugins
+cue materialize cursor --profile backend     # → .cursorrules + .cursor/mcp.json
+cue materialize cline  --profile backend     # → .clinerules + cline_mcp_settings.json
+cue materialize --all  --profile backend     # → all agents in this profile
 ```
 
-See [docs/launch.md](./docs/launch.md) for the resolve → materialize → exec flow.
+| Agent | `cue materialize` command | What gets written |
+|---|---|---|
+| **Claude Code** | (default — uses shim) | `~/.config/cue/runtime/<profile>/claude/` |
+| **OpenAI Codex** | (default — uses shim) | `~/.config/cue/runtime/<profile>/codex/` |
+| **Cursor** | `cue materialize cursor` | `.cursorrules` · `.cursor/mcp.json` |
+| **Cline** | `cue materialize cline` | `.clinerules` · `cline_mcp_settings.json` |
+| **Google Gemini CLI** | `cue materialize gemini` | `~/.gemini/skills/*.md` |
+| **GitHub Copilot** | `cue materialize copilot` | `.github/copilot-instructions.md` |
+| **Windsurf** | `cue materialize windsurf` | `.windsurfrules` · `.windsurf/mcp.json` |
+| **Roo Code** | `cue materialize roo` | `.roo/rules/*.md` · `.roo/mcp.json` |
+| **Sourcegraph Amp** | `cue materialize amp` | `AGENTS.md` · `.amp/mcp.json` |
+| **Aider** | `cue materialize aider` | `.aider.conventions.md` |
+
+Each adapter writes skills + MCPs in the precise format that agent expects — Cursor's `.cursorrules` syntax, Gemini's per-skill markdown, Copilot's instruction file, etc. **Same profiles, same skills, any agent.** Switch from Claude Code to Cursor on the same repo without touching a single skill definition.
+
+See [`src/commands/materialize.ts`](./src/commands/materialize.ts) for the full flag set (`--all`, `--profile`, `--dir`, dry-run).
 
 ---
 
-## Quick install — pick your OS (legacy soul flow)
+## `cue optimizer` — see every loadout at a glance
 
-Two paths per OS:
+> **TL;DR** — `cue optimizer` prints a visual audit of every profile: skills loaded, MCP servers, required CLIs (install status ✅/❌), GitHub sources, and per-skill usage bars computed from your local session transcripts. No telemetry.
 
-- **Direct** — copy a shell block, paste in a terminal, runs the install end-to-end.
-- **Agent-driven** — paste the corresponding `setup/<os>.md` into Claude Code as your first message; it walks you through the phases interactively (recommended if you've never set this up).
+Run it once and you get a dashboard of every profile: skills (with per-session usage), MCP servers, required CLIs (with install status ✅/❌), GitHub sources, and brand icons.
 
-The shell blocks below trigger GitHub's "copy" button when you hover over them on github.com — one click to clipboard.
+<p align="center">
+  <img src="./docs/assets/optimizer-dashboard.svg" alt="cue optimizer summary: 16 profiles, 1,927 skills, 15 MCPs, 79 CLIs" width="820">
+</p>
 
-### macOS
+What the optimizer scans for you:
 
-Open **Terminal** (⌘+Space → "Terminal"), paste, run once:
+- Every `profile.yaml` (inheritance resolved, `*` wildcards expanded)
+- Each skill's frontmatter for `allowed-tools` and `## Prerequisites` → required CLIs
+- `which <cli>` for every CLI → install status per profile
+- `~/.claude/projects/**/*.jsonl` → per-skill usage counts across all sessions
+- `~/skills-lock.json` → which GitHub repo each skill came from
+
+### Terminal output
+
+<p align="center">
+  <img src="./docs/assets/terminal-optimizer.svg" alt="cue optimizer running in the terminal" width="820">
+</p>
+
+> 🐱 **Recommended terminal: [Kitty](https://sw.kovidgoyal.net/kitty/).** cue's optimizer renders bar charts, gradients, brand glyphs, and inline images via the Kitty graphics protocol. It also works in [WezTerm](https://wezfurlong.org/wezterm/) and [Ghostty](https://ghostty.org/) — but inside macOS Terminal or stock `gnome-terminal` you'll see the ASCII fallback (still readable, just less pretty).
 
 ```bash
-# 1. Homebrew
-[ -x "$(command -v brew)" ] || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-# 2. Core tools
-brew install bun node@22 python@3.12 uv jq rtk
-# 3. Claude Code
-curl -fsSL https://claude.ai/install.sh | sh
-# 4. RTK token-savings hook
-rtk init -g
-echo "Setup complete. Run:  claude  — then paste setup/macos.md as your first message."
+cue optimizer                 # all profiles
+cue optimizer backend         # just one
+cue optimizer --expand        # expand grouped skills (useful for cybersecurity's 754)
 ```
 
-→ Full agent-driven prompt: **[setup/macos.md](./setup/macos.md)** (paste into Claude Code)
+### A single profile, expanded
 
-### Linux (Ubuntu / Debian / Fedora / Arch)
+<p align="center">
+  <img src="./docs/assets/profile-card.svg" alt="frontend profile — skills, MCPs, CLIs, per-session usage" width="820">
+</p>
+
+Each card shows what's actually loaded *plus* how often you've reached for each skill. The bar chart is computed from your local session transcripts — no telemetry leaves the machine.
+
+---
+
+## The 16-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>`.
+
+<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>
+
+| Profile | Domain |
+|---|---|
+| `core` | Baseline shared by every profile — claude-mem, caveman, RTK, gbrain. |
+| `backend` | APIs, webhooks, security review, CI, packaging, databases. |
+| `frontend` | UI implementation, redesign, screenshots, browser testing. |
+| `marketing` | Copywriting, SEO, CRO, growth, channels, brand. |
+| `medusa-dev` | Medusa v2 backend, storefront, admin, migration, shop setup. |
+| `cybersecurity` | 754 cybersecurity skills (red/blue team, forensics, DFIR). |
+| `nvidia` | NVIDIA cuOpt: routing, LP/MILP, GPU-accelerated optimization. |
+| `creative-media` | Image, video, product asset, brand, visual generation. |
+| `docs-writer` | Documentation, Markdown, PDF, Obsidian, structured writing. |
+| `readme-writer` | Beautiful README design with SVG diagrams. |
+| `caveman-quick` | Fast low-context edits, summaries, reviews, notes, commits. |
+| `coolify` | Coolify deploys, server config, app env vars, CI. |
+| `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. |
+| `setup` | Per-OS install assistant. |
+
+Canonical source: [`docs/data/profiles.md`](./docs/data/profiles.md).
+
+</details>
 
 ```bash
-# 1. System packages
-if   command -v apt    >/dev/null; then sudo apt update && sudo apt install -y curl git jq build-essential python3 python3-pip
-elif command -v dnf    >/dev/null; then sudo dnf install -y curl git jq @development-tools python3 python3-pip
-elif command -v pacman >/dev/null; then sudo pacman -S --noconfirm curl git jq base-devel python python-pip
-fi
-# 2. Bun
-[ -x "$(command -v bun)" ] || curl -fsSL https://bun.sh/install | bash
-export PATH="$HOME/.bun/bin:$HOME/.local/bin:$PATH"
-# 3. uv (Python venv manager)
-[ -x "$(command -v uv)" ] || curl -LsSf https://astral.sh/uv/install.sh | sh
-# 4. RTK
-[ -x "$(command -v rtk)" ] || (curl -fsSL https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /tmp && sudo install /tmp/rtk /usr/local/bin/rtk)
-# 5. Claude Code
-curl -fsSL https://claude.ai/install.sh | sh
-rtk init -g
-echo "Setup complete. Run:  claude  — then paste setup/linux.md as your first message."
+cue list                      # show all
+cue use medusa-dev            # pin to current directory
+claude                        # launches with medusa-dev's loadout
 ```
 
-→ Full agent-driven prompt: **[setup/linux.md](./setup/linux.md)**
+---
 
-### Windows 10 / 11 (PowerShell)
+## Install
 
-Open **PowerShell**. First-time only:
+> **TL;DR** — `npm install -g cue-ai`, then `echo <profile> > .cue-profile` in any repo. Idempotent. No daemon. Uninstall with `install.sh --uninstall`.
 
-```powershell
-Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```bash
+npm install -g cue-ai
 ```
 
-Then:
-
-```powershell
-# 1. Core tools via winget
-winget install --id OpenJS.NodeJS.LTS  --silent --accept-source-agreements --accept-package-agreements
-winget install --id Python.Python.3.12 --silent --accept-source-agreements --accept-package-agreements
-winget install --id stedolan.jq        --silent --accept-source-agreements --accept-package-agreements
-winget install --id Git.Git            --silent --accept-source-agreements --accept-package-agreements
-$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
-# 2. Bun + uv
-if (-not (Get-Command bun -ErrorAction SilentlyContinue)) { irm bun.sh/install.ps1 | iex }
-if (-not (Get-Command uv  -ErrorAction SilentlyContinue)) { irm https://astral.sh/uv/install.ps1 | iex }
-# 3. Claude Code via npm
-npm install -g @anthropic-ai/claude-code
-# 4. RTK
-if (-not (Get-Command rtk -ErrorAction SilentlyContinue)) {
-    Invoke-WebRequest -Uri "https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-pc-windows-msvc.zip" -OutFile "$env:TEMP\rtk.zip"
-    Expand-Archive -Path "$env:TEMP\rtk.zip" -DestinationPath "$env:USERPROFILE\.local\bin" -Force
-}
-rtk init -g
-Write-Host "Setup complete. Run:  claude  — then paste setup/windows.md as your first message."
+That's it. Then in any project:
+
+```bash
+cd ~/projects/q4-launch
+echo marketing > .cue-profile
+claude
 ```
 
-→ Full agent-driven prompt: **[setup/windows.md](./setup/windows.md)**
+**Other install paths** (pick what you prefer):
 
-(WSL2 user? Use the Linux block inside your WSL distro instead — cleaner.)
+| Path | Command |
+|---|---|
+| **One-line script** | `curl -fsSL https://raw.githubusercontent.com/recodeee/cue/main/get.sh \| bash` |
+| **Manual clone** | `git clone https://github.com/recodeee/cue.git ~/Documents/cue && ~/Documents/cue/install.sh` |
+| **Per-OS bootstrap (agent-driven)** | paste [`setup/macos.md`](./setup/macos.md) · [`setup/linux.md`](./setup/linux.md) · [`setup/windows.md`](./setup/windows.md) into Claude Code |
+
+`install.sh --help` lists `--yes`, `--codex`, `--uninstall`. Idempotent — safe to re-run.
 
 ---
 
-## Optional — Parallel agents tier (Colony + gitguardex)
+## What ships with each profile (the lean stack)
 
-If you want to run **2+ Codex/Claude agents in parallel on the same repo** without them stomping on each other, layer this tier on top of the lean stack:
+| Layer | What it does |
+|---|---|
+| **claude-mem** plugin | Passive observation capture; `mem-search "topic"` recalls across sessions |
+| **caveman** plugin | `/caveman` terse mode, `/caveman-commit` Conventional Commits |
+| **RTK** CLI hook | Filters shell output — 60-90% token savings on `ls` / `git` / `cat` |
+| **gbrain** MCP | Personal wiki with embeddings + backlinks |
+| **excel-mcp** / **word-mcp** | Native `.xlsx` / `.docx` read & write |
 
-- **[recodeee/gitguardex](https://github.com/recodeee/gitguardex)** — `gx` CLI. Per-agent branch + worktree isolation, file locks, PR-only merges.
-- **[recodeee/colony](https://github.com/recodeee/colony)** — Local-first MCP for fleet coordination. Replaces 30k-token repo handoffs with ~400-token compact state in SQLite at `~/.colony`. Auto-detects file claims, task graphs, and prior decisions so agents see ownership before editing.
+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.
 
-→ Full setup prompt: **[setup/parallel-agents.md](./setup/parallel-agents.md)** (Linux + macOS; Windows via WSL2)
+---
 
-Skip this tier if you only ever run one Claude Code window at a time — claude-mem + gbrain are enough for solo work.
+## FAQ
 
----
+<details>
+<summary><b>Why not just use <code>~/.claude/</code> like everyone else?</b></summary>
 
-## How it works
+That's exactly the problem cue solves. `~/.claude/` is one global folder shared across every repo, so every session loads every skill, every MCP, and every plugin you've ever installed. The model burns tokens picking through irrelevant tools and frequently picks the wrong one. cue gives each project its own isolated `CLAUDE_CONFIG_DIR` materialized just-in-time — only what that project needs.
+</details>
 
-Typing `claude` or `codex` in a repo where cue's shims are installed triggers the launch flow:
+<details>
+<summary><b>Does this break Claude Code's auto-update?</b></summary>
 
-1. **Resolve** — cue checks for a `.cue-profile` file in the current directory (or any parent up to `$HOME`). If none is found, it falls back to a repo-level default, a global default, or opens the TUI picker.
-2. **Materialize** — cue builds `~/.config/cue/runtime/<profile>/{claude,codex}/` with a content-addressed hash check. If the profile hasn't changed, this is a no-op.
-3. **Exec** — the real `claude` or `codex` binary is launched with `CLAUDE_CONFIG_DIR` (or `CODEX_HOME`) pointing at the materialized runtime tree.
+No. cue doesn't touch the `claude` binary — it just intercepts the *call*, sets `CLAUDE_CONFIG_DIR`, and execs the real binary at the end of the shim. Claude Code's update mechanism still runs the same way.
+</details>
 
-The shims are a one-time install: `cue shell install`. See **[docs/launch.md](./docs/launch.md)** for the full resolve-precedence rules and bypass paths.
+<details>
+<summary><b>Can I use cue with only Codex (no Claude Code)?</b></summary>
 
----
+Yes. Run `cue shell install --codex-only` (or skip the `claude` shim during interactive install). cue scopes resources per-agent in `profile.yaml`, so a Codex-only profile only materializes `CODEX_HOME`.
+</details>
 
-## Profiles
+<details>
+<summary><b>What if I only want one global profile and never want to think about this?</b></summary>
 
-Profiles keep each Claude Code or Codex session lean by materializing only the skills and MCPs needed for the current job.
+Set a global default with `cue use <profile> --global`. cue will use it for every directory that doesn't have its own `.cue-profile`. The picker stops appearing.
+</details>
 
-```bash
-cue list
-cue use medusa-dev
-cd profiles/medusa-dev/workspace && claude
-```
+<details>
+<summary><b>Is this a daemon or background service?</b></summary>
 
-Each profile carries an emoji icon shown in the picker:
+No. cue is a pure CLI — when you type `claude`, the shim runs `cue launch`, which does a `stat()` + sha256 compare, materializes the runtime if anything changed (else no-op), and then `exec`s the real binary. Nothing stays resident. Nothing to monitor. Nothing to `systemctl restart`.
+</details>
 
-```
-🐻 backend         APIs, webhooks, security review, CI, package, …
-🦋 frontend        Frontend UI implementation, redesign, screenshots, …
-🦜 marketing       Marketing — copywriting, SEO, CRO, growth, …
-🦉 research        Source-backed lookup, extraction, market research
-🐺 fleet-control   Multi-agent orchestration, Colony, OMX, gx
-🦚 creative-media  Image, video, brand, visual generation
-🐝 docs-writer     Markdown, PDF, Obsidian, structured writing
-🐆 caveman-quick   Fast low-context edits, summaries, reviews
-🦄 full            Diagnostic profile — every local skill + MCP
-🐢 core            Shared baseline (claude-mem, meta skills, …)
-```
+<details>
+<summary><b>How fast is the launch overhead?</b></summary>
 
-Pick or change an icon: `cue icon <profile>` (interactive emoji picker).
+Cold start (first launch of a new profile): typically 50–200 ms depending on how many skills + MCPs are linked. Warm start (profile unchanged): &lt;5 ms — just a sha256 compare and an `exec`. Both are imperceptible vs. Claude Code's own startup.
+</details>
 
-The active profile is also stamped at the top of the materialized `CLAUDE.md`,
-so `/goal` inside Claude Code shows which profile is loaded.
+<details>
+<summary><b>Does cue send telemetry anywhere?</b></summary>
 
-### Saving the current session as a profile
+No. Everything cue computes (including the per-skill usage bars in `cue optimizer`) is read from your local `~/.claude/projects/**/*.jsonl` session transcripts. Nothing leaves the machine.
+</details>
 
-From any Claude Code session, ask: *"save this as a profile"*. The
-`meta/save-profile` skill walks you through the steps and calls
-`cue create-profile` to write the YAML:
+<details>
+<summary><b>What does cue NOT do?</b></summary>
 
-```bash
-cue create-profile my-project \
-  --icon "🦊" \
-  --description "My project work" \
-  --skills design/ui-ux-pro-max,research/find-skills \
-  --pin
-```
+- It does not modify or repackage the Claude Code / Codex binary.
+- It does not host a remote skill marketplace — skills live in your repo or come from [open-source sources](#built-with--built-on).
+- It does not coordinate multi-agent runs (that's [`recodeee/colony`](https://github.com/recodeee/colony) + [`gitguardex`](https://github.com/recodeee/gitguardex), layered on top via the parallel-agents tier).
+- It does not auto-pick a profile from repo contents — you pin once with `echo <profile> > .cue-profile`. (A scan-to-profile flow is on the roadmap.)
 
-### Multi-account flow (with authmux)
+</details>
 
-If you keep separate Claude/Codex accounts (e.g. via `authmux`), point each
-alias at its own `CLAUDE_CONFIG_DIR`:
+---
 
-```bash
-alias claude-account2="CLAUDE_CONFIG_DIR=$HOME/.claude-accounts/account2 cue launch claude"
-```
+## Repo layout
 
-cue detects the pre-set config dir, copies `.credentials.json` and merges the
-account's `settings.json` into the materialized runtime, and **always shows
-the picker** with the previously-pinned profile on top — so you can pick a
-different profile per session without losing the auth.
+```
+cue/
+├── profiles/        one dir per profile, YAML decides what loads (inheritance, agent scoping)
+├── resources/
+│   ├── skills/      110+ local skills (medusa, codex-fleet, higgsfield, caveman, …)
+│   ├── mcps/        MCP server configs (claude.sanitized.json, codex.sanitized.json)
+│   └── icons/       brand icons used in the optimizer dashboard
+├── plugins/cue/     the Claude Code plugin: /cue, /cue switch, /cue reload, /cue current
+├── src/             the Bun CLI — commands/{optimizer,launch,picker,…}, lib/runtime-materializer
+├── setup/           paste-into-agent install prompts (macos, linux, windows, parallel-agents)
+└── docs/            launch.md, shell-install.md, assets/ (the SVGs in this README)
+```
 
-Start with the docs hub at **[docs/profiles/](./docs/profiles/)** for the schema, inheritance model, scan-to-profile flow, and troubleshooting.
+Full docs: **[docs/launch.md](./docs/launch.md)** (resolve → materialize → exec flow) · **[docs/profiles/](./docs/profiles/)** (schema, inheritance, scan-to-profile, troubleshooting) · **[AGENTS.md](./AGENTS.md)** (bootstrap contract for AI agents).
 
 ---
 
-## For AI agents
+## Built with / built on
 
-If you are an AI coding agent helping a human set this up, read **[AGENTS.md](./AGENTS.md)** first — it explains the bootstrap contract (phase-by-phase, ask-before-network, verify-each-step) and points to the per-OS prompt your user should paste.
+cue glues together a small set of excellent open-source projects. Star counts are live from GitHub.
 
----
+**Runtime & dependencies (the CLI itself):**
 
-## What you get
+| Project | What we use it for | |
+|---|---|---|
+| [oven-sh/bun](https://github.com/oven-sh/bun) | TypeScript runtime that ships `bin/cue` | [![stars](https://img.shields.io/github/stars/oven-sh/bun?style=flat-square&label=★&color=6366f1)](https://github.com/oven-sh/bun) |
+| [natemoo-re/clack](https://github.com/natemoo-re/clack) | `@clack/prompts` powers the TUI profile picker | [![stars](https://img.shields.io/github/stars/natemoo-re/clack?style=flat-square&label=★&color=6366f1)](https://github.com/natemoo-re/clack) |
+| [ajv-validator/ajv](https://github.com/ajv-validator/ajv) | JSON Schema validation for `profile.yaml` | [![stars](https://img.shields.io/github/stars/ajv-validator/ajv?style=flat-square&label=★&color=6366f1)](https://github.com/ajv-validator/ajv) |
+| [eemeli/yaml](https://github.com/eemeli/yaml) | YAML parsing for profile definitions | [![stars](https://img.shields.io/github/stars/eemeli/yaml?style=flat-square&label=★&color=6366f1)](https://github.com/eemeli/yaml) |
 
-After bootstrap (~550 MB cold RAM per session):
+**Built-in terminal integration:**
 
-| Layer | What it does |
-|---|---|
-| **claude-mem** plugin | Captures session observations passively; `mem-search "topic"` to recall across sessions |
-| **caveman** plugin | `/caveman` for terse replies, `/caveman-commit` for Conventional Commit messages |
-| **RTK** (CLI hook) | Filters shell-command outputs — 60-90% token savings on `ls` / `git` / `cat` |
-| **gbrain** MCP | Personal knowledge wiki with embeddings, backlinks, timeline |
-| **excel-mcp-server** | Native `.xlsx` read/write/format |
-| **office-word-mcp-server** | Native `.docx` read/write |
+| Project | What we use it for | |
+|---|---|---|
+| [kovidgoyal/kitty](https://github.com/kovidgoyal/kitty) | **Kitty graphics protocol** — inline brand logos & profile icons rendered directly in the terminal (see [`src/lib/kitty-image.ts`](./src/lib/kitty-image.ts), spec [here](https://sw.kovidgoyal.net/kitty/graphics-protocol/)). Auto-detected; falls back to emoji if you're not on Kitty. | [![stars](https://img.shields.io/github/stars/kovidgoyal/kitty?style=flat-square&label=★&color=22c55e)](https://github.com/kovidgoyal/kitty) |
 
-claude-mem (passive) and gbrain (manual wiki) are complementary — both recommended.
+**Agents we shim:**
 
----
+| Project | Role | |
+|---|---|---|
+| [anthropics/claude-code](https://github.com/anthropics/claude-code) | The `claude` binary cue intercepts and re-launches with `CLAUDE_CONFIG_DIR` | [![stars](https://img.shields.io/github/stars/anthropics/claude-code?style=flat-square&label=★&color=f59e0b)](https://github.com/anthropics/claude-code) |
+| [openai/codex](https://github.com/openai/codex) | The `codex` binary cue intercepts and re-launches with `CODEX_HOME` | [![stars](https://img.shields.io/github/stars/openai/codex?style=flat-square&label=★&color=f59e0b)](https://github.com/openai/codex) |
 
-## What's inside the repo
+**Skill packs & sister tools:**
 
-```
-cue/
-├── skills/         110+ Claude Code / Codex skills
-│   ├── medusa/     building-with-medusa, storefront-best-practices, …
-│   ├── codex-fleet/  bringup, dispatch, supervisors, panes, troubleshoot
-│   ├── higgsfield/   generate, marketplace-cards, soul-id
-│   ├── caveman/      caveman, caveman-commit, caveman-compress
-│   └── ...
-├── mcps/           MCP server snapshots + configs
-│   ├── configs/    claude.sanitized.json, codex.sanitized.json, …
-│   ├── mcps/       individual MCP server entries
-│   └── plugins/    Claude Code plugin snapshots
-└── setup/          paste-into-Claude-Code prompts (macos.md, linux.md, windows.md)
-```
+| Project | Role | |
+|---|---|---|
+| [mukul975/Anthropic-Cybersecurity-Skills](https://github.com/mukul975/Anthropic-Cybersecurity-Skills) | 754 cybersecurity skills (red/blue team, forensics, DFIR) loaded by the `cybersecurity` profile | [![stars](https://img.shields.io/github/stars/mukul975/Anthropic-Cybersecurity-Skills?style=flat-square&label=★&color=ef4444)](https://github.com/mukul975/Anthropic-Cybersecurity-Skills) |
+| [recodeee/colony](https://github.com/recodeee/colony) | Local-first MCP for multi-agent coordination — used by the `fleet-control` profile | [![stars](https://img.shields.io/github/stars/recodeee/colony?style=flat-square&label=★&color=ec4899)](https://github.com/recodeee/colony) |
+| [recodeee/gitguardex](https://github.com/recodeee/gitguardex) | `gx` CLI for branch + worktree isolation when running 2+ agents on one repo | [![stars](https://img.shields.io/github/stars/recodeee/gitguardex?style=flat-square&label=★&color=ec4899)](https://github.com/recodeee/gitguardex) |
+| [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | Token-savings hook on shell output (60–90% reduction on `ls`/`git`/`cat`) | [![stars](https://img.shields.io/github/stars/rtk-ai/rtk?style=flat-square&label=★&color=fbbf24)](https://github.com/rtk-ai/rtk) |
+| [astral-sh/uv](https://github.com/astral-sh/uv) | Python venv manager used by `setup/<os>.md` to run uvx-based MCP servers (Excel / Word) | [![stars](https://img.shields.io/github/stars/astral-sh/uv?style=flat-square&label=★&color=22c55e)](https://github.com/astral-sh/uv) |
+
+Plus the **brand logos** you see in the optimizer dashboard and hero come from each vendor's official press kit (OpenAI, NVIDIA, Hostinger, Coolify, Medusa, Stripe, Higgsfield, Obsidian) — see [`resources/icons/`](./resources/icons/).
 
 ---
 
 ## Contributing
 
-Each skill is a folder with `SKILL.md` (frontmatter + body) plus reference files. The frontmatter `description` is what the LLM matches against — write it as `"when user says X, do Y"`.
+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.
 
-To add a new skill: copy an existing one as a template, edit `SKILL.md`, drop it under `skills/skills/<category>/<slug>/`. The catalog regenerates on the next sync.
+The SVGs in this README live in [`docs/assets/`](./docs/assets/) — edit the XML directly or regenerate from the `readme-writer` profile.
+
+License: [MIT](./LICENSE).