compact-agent 1.24.2 → 1.25.0

package/README.md

@@ -1,352 +1,194 @@
+# compact-agent
 
-# Compact Agent
-
-**A dense, feature-rich AI coding agent for the terminal.**
+A terminal AI coding CLI for any OpenAI-compatible API.
 
 [![npm](https://img.shields.io/npm/v/compact-agent?color=cyan)](https://www.npmjs.com/package/compact-agent)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A518.0-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Hermes](https://img.shields.io/badge/Mode-Hermes-purple)](https://github.com/nousresearch/hermes-agent)
-[![ECC](https://img.shields.io/badge/Bundled-everything--claude--code-orange)](https://github.com/Crownelius/everything-claude-code)
-
-Compact Agent is a single-command terminal AI coding CLI. It speaks any OpenAI-compatible API (OpenRouter, OpenAI, Anthropic via compatible endpoints, Ollama, LM Studio, DeepSeek, GLM). It ships with **80+ slash commands**, **8 operation modes** including the self-improving **Hermes** mode, the bundled **everything-claude-code** skill library, multi-agent orchestration, a cross-session learning system, and zero telemetry.
-
-[Features](#-features) • [Modes](#-operation-modes) • [Skills](#-skills-system) • [Tools](#-tool-arsenal) • [Providers](#-supported-providers) • [Installation](#-installation) • [Commands](#-slash-commands) • [Privacy](#-privacy) • [Architecture](#-architecture)
-
----
-
-## ✨ Features
-
-- **Single-command install** — `npm install -g compact-agent && compact-agent`. No clone, no build step, no Docker, no IDE extension.
-- **Universal LLM transport** — works with any OpenAI-compatible API. Switch providers and models from inside the REPL with `/model`, `/provider`, `/route`.
-- **9 operation modes** — `dev`, `review`, `tdd`, `research`, `plan`, `debug`, `architect`, `hermes` (self-improving learning loop), and `design` (Stitch-powered UI generation — describe what you want, the agent uses Stitch to design it and writes the result into your code). Each rewrites the system prompt to bias the agent toward its specific workflow.
-- **Hermes self-improving mode** — recalls prior sessions, models the user across conversations, parallelizes independent subtasks, distills new skills from experience, and proposes what's worth banking before finishing. Inspired by [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent).
-- **Bundled everything-claude-code library** — 33 high-quality skills, 16 agents, 9 workflow commands, 7 language rule bundles, and 5 default security hooks. Auto-installed on first launch via [Crownelius/everything-claude-code](https://github.com/Crownelius/everything-claude-code).
-- **Unified slash-command surface** — `/tdd`, `/review`, `/security-review`, `/plan`, `/refactor`, `/build-fix` automatically use the ECC prompts when ECC is installed. **No `/ecc-tdd` vs `/tdd` duplication.**
-- **Multi-agent orchestration** — `/orchestrate`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/pr-loop` spawn parallel sub-tasks against the same project.
-- **10 language-specific reviewers** — `/auto-review` (auto-detects the language) plus dedicated reviewers for TS, Python, Go, Rust, Java, C++, Kotlin, PHP, and SQL.
-- **6 language-specific build fixers** — `/ts-build-fix`, `/go-build-fix`, `/rust-build-fix`, `/java-build-fix`, `/cpp-build-fix`, `/pytorch-fix`.
-- **Learning system** — `/learn` extracts patterns from the current session into confidence-scored instincts. `/evolve` promotes high-confidence instincts into reusable skills. Confidence decays automatically; `/prune` removes stale patterns.
-- **Cross-session memory** — `~/.crowcoder/memory/` retains project context across sessions. Hermes mode searches it before answering.
-- **Sessions & checkpoints** — `/sessions`, `/save`, `/resume`, `/delete` for full session snapshots; `/checkpoint` for git-state snapshots inside a session.
-- **Agent-led walkthrough** — type `/walkthrough` (or `/tour`, `/guide`) and the agent walks new users through every feature interactively.
-- **Native security hooks** — by default, block `git --no-verify`, warn on reading `.env`/`.key`/`.pem`, warn when an edit leaves `console.*` statements, suggest tmux for long-running dev servers. Fully configurable in `~/.crowcoder/hooks.json`.
-- **Permission modes** — `/perm ask` prompts before every tool use, `/perm auto` allows non-destructive ops, `/perm yolo` approves everything. Per-tool dry-run via `/dry-run`.
-- **Cost & budget tracking** — `/usage`, `/budget` keep token counts and cost estimates entirely local in `~/.crowcoder/usage.json`. Cost-aware routing via `/route`.
-- **Real web search** — `web_search` tool backed by DuckDuckGo Lite (no API key). The LLM gets unknown-tool errors with the valid tool list so free models that hallucinate `web_search_exa` can self-correct.
-- **Google Stitch integration** — `/stitch <query>` interface to [Stitch](https://stitch.withgoogle.com/), Google's AI UI/UX design tool. List projects, generate UI from text, enhance design prompts. Ports the [gemini-cli-extensions/stitch](https://github.com/gemini-cli-extensions/stitch) extension; API-key auth.
-- **Zero telemetry** — no analytics SDKs, no phone-home, no crash reporting. The only network calls are to your chosen LLM provider when you send a message.
-
----
-
-## 🧠 Operation Modes
-
-Switchable any time with `/mode <name>`. Each mode injects a specialized system-prompt addition.
-
-### ⚡ dev — *default*
-
-General coding. Write features, fix bugs, refactor. Reads files before editing, prefers minimal changes.
-
-### 🔍 review
-
-Code review with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW). Confidence-filtered: only reports issues the model is >80% sure about.
-
-### 🧪 tdd
-
-Strict RED → GREEN → REFACTOR cycle. Will **not** write implementation before a failing test. Lower temperature for tighter cycles.
-
-### 🔭 research
 
-Read-only exploration. The agent reads code, traces execution paths, maps architecture, and reports — without modifying files.
-
-### 📋 plan
-
-Design before building. Produces numbered step-by-step plans with file paths, trade-offs, and risk assessment. Does **not** write code in this mode.
-
-### 🐛 debug
-
-Systematic root-cause hunting. Reproduce → hypothesize → narrow → fix → verify. Never guesses — always confirms with evidence.
-
-### 🏛 architect
-
-System-level design. Component boundaries, data flow, technology choices, scalability, API design, database schemas, deployment.
-
-### 🜲 hermes
-
-**The agent that grows with you.** Recalls prior sessions and instincts before answering, builds a model of the user across conversations, parallelizes independent subtasks, distills skills from experience, nudges to persist knowledge at end of work, and proactively suggests scheduled follow-ups.
-
-Activate with `/hermes` or `/mode hermes`.
-
-### 🎨 design
-
-**UI work without thinking about UI tools.** In design mode, any visual / layout / theming request flows through Google Stitch automatically. The agent creates a Stitch project, generates the screens from a carefully composed prompt (with your aesthetic preferences translated into Stitch-style descriptors), fetches the result, writes the HTML/Tailwind into your code, and adds JS for interactivity. Iterate by just saying what to change.
-
-Example: `/design build me a stock portfolio app where I can add new stocks via a form — edgy aesthetic, lots of red, no blue or green`.
+```bash
+npm install -g compact-agent
+compact-agent
+```
 
-Activate with `/design [task]` or `/mode design`. Requires `/stitch-config` first.
+First run prompts you for a provider, key, model, and permission mode. After that, `compact-agent` from any directory drops you into a REPL with a persistent bottom-anchored input box.
 
 ---
 
-## 🛠 Skills System
-
-Skills are reusable prompt templates stored in `~/.crowcoder/skills/`. Three sources:
+## What it does
 
-| Source | Stored as | Origin |
-| :--- | :--- | :--- |
-| **ECC bundled** | `ecc-<name>.json` | The 33 skills from [everything-claude-code](https://github.com/Crownelius/everything-claude-code), auto-installed on first launch |
-| **ECC agents** | `ecc-agent-<name>.json` | 16 specialized agent prompts (code-reviewer, planner, doc-updater, etc.) |
-| **Your own** | `<id>.json` | Created via `/skill-create` (distilled from git patterns) or `/evolve` (promoted from high-confidence instincts) |
-
-When you send a message, Compact Agent auto-matches the highest-scoring skill against your query and injects its body into the system prompt for that turn. Browse with `/skills`, filter to ECC with `/ecc-skills`.
+- Speaks any OpenAI-compatible Chat Completions endpoint. OpenRouter, OpenAI, NVIDIA, DeepSeek, GLM, Ollama, LM Studio, or anything custom.
+- Tool-call loop with `bash`, `read_file`, `write_file`, `edit_file`, `apply_patch`, `grep`, `glob`, `list_dir`, `web_search`, `web_fetch`, plus optional `stitch` (Google's UI generator) when configured.
+- Permission gating: `/perm ask` prompts every tool call, `/perm auto` lets read-only and safe writes through, `/perm yolo` runs everything.
+- Optional OS sandbox: `/sandbox standard` uses `sandbox-exec` (macOS) or `bwrap` (Linux) when available. No-op on Windows.
+- Multi-key rotation pool: add several provider keys via `/keys add`. The agent round-robins and cools down keys that hit 429 / quota / auth errors so the others keep working.
+- Parallel agent swarm: `/swarm <agent,agent,...> <task>` fans out N specialized ECC agents against the same prompt and prints attributed results.
+- Bundled [everything-claude-code](https://github.com/Crownelius/everything-claude-code): 228 skills, 60 agents, 75 workflow commands, 19 language rule bundles. Auto-installed on first launch; refresh with `/ecc-install`.
+- 9 modes (`/mode <name>`): `dev`, `review`, `tdd`, `research`, `plan`, `debug`, `architect`, `hermes`, `design`. Each rewrites the system-prompt addendum.
+- Optional voice: Whisper dictation (push-to-talk `F5`) and ElevenLabs TTS readout. Screen-reader mode for blind / low-vision users. All off by default — opt in with `/voice on`.
+- Zero telemetry. The only outbound traffic is to your chosen LLM provider when you send a turn.
 
 ---
 
-## 🔧 Tool Arsenal
-
-The LLM has access to these tools. Each call is gated by your permission mode (`ask`/`auto`/`yolo`).
+## Modes
 
-| Tool | Description | R/W |
-| :--- | :--- | :---: |
-| `bash` | Run a shell command. Spawns via Git Bash on Windows, `/bin/bash` elsewhere. | RW |
-| `read_file` | Read a file with paging + size limits. | R |
-| `write_file` | Create or overwrite a file. Auto-creates parent dirs. | W |
-| `edit_file` | Find-and-replace within a file with optional `replace_all`. | W |
-| `grep` | Search file contents. Uses ripgrep when available, falls back to grep. | R |
-| `glob` | Find files by glob pattern (e.g. `src/**/*.ts`). | R |
-| `list_dir` | List directory entries (type, size, name). | R |
-| `web_fetch` | Fetch a URL and convert HTML → readable text. | R |
-| `web_search` | Keyword search via DuckDuckGo Lite. Returns title/URL/snippet. No API key required. | R |
-| `stitch` | Google Stitch MCP server — 12 tools across Project Management, Screen Management, AI Generation (gemini-3-flash / -pro, slow), and Design Systems. Auto-registered when `/stitch-config` has saved an API key. | RW |
+`/mode <name>` swaps the system-prompt addendum.
 
-Unknown-tool calls are intercepted: when a free model hallucinates `web_search_exa`, `TodoWrite`, or similar, the error response lists the valid tool names so the model self-corrects on the next iteration.
+| Mode | What changes |
+| :--- | :--- |
+| `dev` | Default. General coding, minimal-change bias, reads before edits. |
+| `review` | Severity-rated findings (CRITICAL / HIGH / MEDIUM / LOW). Confidence filter — only reports issues it's >80% sure about. |
+| `tdd` | RED → GREEN → REFACTOR. Refuses to write implementation before a failing test. |
+| `research` | Read-only. Maps architecture, traces paths, never modifies files. |
+| `plan` | Numbered step-by-step plans with paths and trade-offs. No code. |
+| `debug` | Reproduce → hypothesize → narrow → fix → verify. Refuses to guess. |
+| `architect` | Component boundaries, data flow, scalability, schemas, deployment. |
+| `hermes` | Recalls prior sessions, parallelizes independent subtasks, distills new skills from experience, suggests what's worth banking. |
+| `design` | UI requests flow through Google Stitch automatically. Requires `/stitch-config`. |
 
 ---
 
-## 🌐 Supported Providers
+## Providers
 
 | Provider | Base URL | Notes |
 | :--- | :--- | :--- |
-| **OpenRouter** | `https://openrouter.ai/api/v1` | One key, hundreds of models, free tier available. Recommended for new users. |
-| **OpenAI** | `https://api.openai.com/v1` | GPT-4o / o-series. |
-| **Anthropic** (via OpenRouter) | `https://openrouter.ai/api/v1` | Use `anthropic/claude-sonnet-4` etc. (native Anthropic API is not OpenAI-compatible). |
-| **DeepSeek** | `https://api.deepseek.com/v1` | Cheap, strong on code. |
-| **GLM (ZhipuAI)** | `https://open.bigmodel.cn/api/paas/v4` | GLM family. |
-| **Ollama** | `http://localhost:11434/v1` | Local models — no API key needed. |
-| **LM Studio** | `http://localhost:1234/v1` | Local models — no API key needed. |
-| **Custom** | you provide | Anything that speaks OpenAI Chat Completions. |
+| OpenRouter | `https://openrouter.ai/api/v1` | One key, hundreds of models, free tier. Recommended default. |
+| OpenAI | `https://api.openai.com/v1` | GPT-4o, o-series. |
+| NVIDIA | `https://integrate.api.nvidia.com/v1` | NIM-hosted Llama, Mistral, DeepSeek, etc. Free tier with rate limits. |
+| DeepSeek | `https://api.deepseek.com/v1` | Cheap, strong on code. |
+| GLM (ZhipuAI) | `https://open.bigmodel.cn/api/paas/v4` | GLM family. |
+| Ollama | `http://localhost:11434/v1` | Local. No key. |
+| LM Studio | `http://localhost:1234/v1` | Local. No key. |
+| Custom | you provide | Anything that speaks OpenAI Chat Completions. |
 
----
+Anthropic models reach you via OpenRouter (`anthropic/claude-sonnet-4` etc.) — the native Anthropic API isn't OpenAI-compatible.
 
-## 📦 Installation
-
-### Prerequisites
+---
 
-- [Node.js](https://nodejs.org/) **18 or newer** (tested on 18, 20, 22, 24)
-- An API key from any supported provider (or use a local Ollama / LM Studio)
-- A POSIX-like shell. Compact Agent spawns Git Bash for shell tools on Windows.
+## Key rotation
 
-### Single-command install
+If you have multiple keys for the same provider (e.g. several free OpenRouter accounts), add them to a pool. The agent round-robins through them and cools off any key that hits 429, quota, or auth errors.
 
-```bash
-npm install -g compact-agent
-compact-agent
 ```
-
-First run launches the setup wizard (provider, key, model, permission mode). After that, `compact-agent` from any directory drops you into the REPL.
-
-### From source (development)
-
-```bash
-git clone https://github.com/Crownelius/Crowcoder.git
-cd Crowcoder
-npm install
-npm link
+/keys add sk-or-v1-…
+/keys add sk-or-v1-…
+/keys status
 ```
 
-Rebuild after edits: `npx tsc` (or `npm run build`). The `prepare` script also runs `tsc` automatically on `npm install`, so a clean clone produces a working `dist/` without an extra step.
+Cool-down policy: 60s for rate-limit (`429`, `rate.?limit`), 1h for quota / auth / 403. 404 model-not-found and 5xx server errors are NOT treated as key problems — they're surfaced upward without burning a key.
 
-### Updating
+---
 
-```bash
-npm install -g compact-agent@latest
-```
+## Swarming
 
-### Uninstalling
+Fan out the same task to N specialized agents in parallel.
 
-```bash
-npm uninstall -g compact-agent
-rm -rf ~/.crowcoder        # remove all local state (config, sessions, skills, ...)
+```
+> /swarm code-architect,silent-failure-hunter,type-design-analyzer  audit the auth flow
+
+══════════════════════════════════════════════
+  code-architect   (12.4s)
+──────────────────────────────────────────────
+…
+══════════════════════════════════════════════
+  silent-failure-hunter   (9.1s)
+──────────────────────────────────────────────
+…
 ```
 
-See [INSTALL.md](INSTALL.md) for the full setup walkthrough including provider-specific tips and troubleshooting.
+Agents are pulled from the bundled ECC harness. Each runs against an empty tool list (analysis only — no edits or shell). Failures in one don't kill the others (`Promise.allSettled`). Cost = N model calls.
 
 ---
 
-## ⌨ Slash commands
+## Slash commands
 
-The most-used commands at a glance. See **[COMMANDS.md](COMMANDS.md)** for the complete reference (~80 commands).
+130+ commands. The common ones:
 
-| Command | Description |
+| Command | What it does |
 | :--- | :--- |
-| `/walkthrough` | Agent-led tour of every feature *(aliases: `/tour`, `/guide`)* |
-| `/help` | Print the full command list |
-| `/mode <name>` | Switch operation mode (dev/review/tdd/research/plan/debug/architect/hermes) |
-| `/model [name]` | Switch model, or show the current one |
-| `/perm <mode>` | Change permission mode (ask/auto/yolo) |
-| `/tdd <feature>` | Test-driven workflow — tests first, then implementation |
-| `/review [target]` | AI code review with severity ratings |
-| `/orchestrate <task>` | Decompose a task and run sub-agents in parallel |
-| `/skills` | List all skills (built-in, ECC bundled, learned) |
-| `/learn` | Extract patterns from the current session into instincts |
-| `/usage` | Show token + cost summary |
-| `/audit` | Local-only project health check (no data leaves your machine) |
-| `/export [md\|json\|txt]` | Save the current conversation to a file |
-| `!<cmd>` | Run a shell command directly without involving the AI |
-| `/exit` | Quit the REPL |
+| `/walkthrough` | Agent-led tour. Aliases: `/tour`, `/guide`. |
+| `/help` | Full command list. |
+| `/mode <name>` | Switch mode. |
+| `/model [name]` | Show or switch model. |
+| `/perm ask\|auto\|yolo` | Change permission mode. |
+| `/sandbox off\|standard\|strict` | OS sandbox level (macOS / Linux only). |
+| `/keys add\|remove\|status\|clear` | Manage the key-rotation pool. |
+| `/swarm <agents> <task>` | Parallel multi-agent fan-out. |
+| `/tdd <feature>` | TDD workflow — failing test first. |
+| `/review [target]` | Severity-rated code review. |
+| `/audit` | Local project health check. Nothing leaves your machine. |
+| `/orchestrate <task>` | Decompose, run sub-agents in parallel. |
+| `/skills`, `/ecc-guide`, `/skill-show <name>` | Browse the bundled skill library. |
+| `/learn`, `/evolve`, `/prune` | Cross-session learning system. |
+| `/memory` | MemPalace-backed persistent memory (rooms, drawers, KG triples). |
+| `/usage`, `/budget` | Local token and cost ledger. |
+| `/voice on\|off\|config` | Toggle dictation + TTS. |
+| `/accessibility screenReader on` | Screen-reader-friendly output. |
+| `/sessions`, `/save`, `/resume` | Full session snapshots. |
+| `/checkpoint` | Git-state snapshot inside a session. |
+| `/export md\|json\|txt` | Save the conversation. |
+| `!<cmd>` | Run a shell command without involving the LLM. |
+| `/exit` | Quit. |
+
+See **[COMMANDS.md](COMMANDS.md)** for the full reference.
 
 ---
 
-## 🔒 Privacy
-
-**Zero telemetry, zero analytics, zero phone-home.**
+## Permissions and safety
 
-| Data | Where it goes |
+| Mode | Behavior |
 | :--- | :--- |
-| Conversation messages | Your chosen LLM provider only (required for the model to respond) |
-| Token counts, costs | `~/.crowcoder/usage.json` — local file only, never transmitted |
-| Sessions | `~/.crowcoder/sessions/*.json` — local files |
-| Learned instincts & skills | `~/.crowcoder/instincts/`, `~/.crowcoder/skills/` — local files |
-| Memory | `~/.crowcoder/memory/` — local files |
-| API keys | `~/.crowcoder/config.json` — plaintext, local only. **Protect this file.** |
-| Hook execution | All hooks run locally in your shell. No external calls. |
+| `ask` | Prompts before each tool call. Default. |
+| `auto` | Reads and safe writes go through. Bash + destructive ops still prompt. |
+| `yolo` | Approves everything. Use with caution. |
 
-The `web_fetch` and `web_search` tools only contact URLs the agent decides to fetch in response to your request. There is no background telemetry, no crash reporting, no auto-update beacon.
-
-**To remove everything:** `rm -rf ~/.crowcoder`.
+A separate execpolicy gate intercepts dangerous bash patterns (`rm -rf`, `git ... --no-verify`, secret scanners) before they reach the shell — independent of the permission mode. Five default hooks (configurable in `~/.compact-agent/hooks.json`) cover console-leftover warnings, `.env` reads, missing tmux for dev servers, and a hard block on `--no-verify`.
 
 ---
 
-## 🪝 Default Hooks
-
-Five hooks ship by default via the bundled everything-claude-code library. Configured in `~/.crowcoder/hooks.json` — disable any you don't want.
+## Privacy
 
-| Event | Match | Behavior |
-| :--- | :--- | :--- |
-| `PreToolUse` | `bash` | **Block** `git ... --no-verify` and `--no-gpg-sign` — they skip pre-commit hooks |
-| `PreToolUse` | `bash` | Warn (non-blocking) when running a dev server outside tmux on POSIX |
-| `PreToolUse` | `read_file` | Warn when reading `.env`, `.key`, `.pem`, or paths containing `credentials`/`secrets`/`id_rsa` |
-| `PostToolUse` | `edit_file` | Warn when an edit leaves `console.log`/`console.warn`/`console.error` statements in `.ts`/`.js` files |
-| `PostToolUse` | `write_file` | Same console-statement warning on new files |
+| Data | Where it lives |
+| :--- | :--- |
+| Conversation messages | Your chosen provider only — required for inference. |
+| Token counts, costs | `~/.compact-agent/usage.json`. Local. |
+| Sessions, skills, instincts, memory | `~/.compact-agent/`. Local. |
+| API keys | `~/.compact-agent/config.json`. Plaintext, local. Protect this file. |
+| Hooks | Run locally in your shell. No outbound calls. |
 
-Set `CROWCODER_HOOK_PROFILE=minimal` to silence all but the blocking ones. Set `=strict` to enable additional reminders (tmux prompts, git-push warnings). Write your own hooks by adding entries to `hooks.json` with `event`, `match`, `command`, `blocking`, `timeout`, `enabled`.
+No analytics SDKs, no crash reporting, no auto-update beacon. `rm -rf ~/.compact-agent` removes everything.
 
 ---
 
-## 🏛 Architecture
+## From source
 
+```bash
+git clone https://github.com/Crownelius/compact-agent.git
+cd compact-agent
+npm install
+npm link
 ```
-src/
-├── index.ts                 # REPL main loop + ~80 slash-command dispatcher
-├── api.ts                   # OpenAI-compatible client (streaming, retries, 429-aware)
-├── query.ts                 # Tool-call loop: stream chat → exec tools → feed back results
-├── system-prompt.ts         # System prompt assembly (env + mode + rules + ECC skill)
-├── config.ts                # ~/.crowcoder/config.json (CROWCODER_HOME-aware)
-├── modes.ts                 # 8 operation modes — dev/review/tdd/research/plan/debug/architect/hermes
-├── walkthrough.ts           # /walkthrough — agent-led tour prompt
-├── ecc.ts                   # everything-claude-code installer + skill/agent/command loader
-├── stitch.ts                # Google Stitch integration (MCP JSON-RPC client + prompt builder)
-├── tools/                   # 9 tools — each implements { name, parameters, call(input, cwd) }
-│   ├── bash.ts              # Shell exec with timeout, 10 MB buffer
-│   ├── read.ts              # Paged file read with size limit
-│   ├── write.ts             # File creation/overwrite, auto mkdir
-│   ├── edit.ts              # Find/replace with optional replace_all
-│   ├── grep.ts              # ripgrep with grep fallback
-│   ├── glob.ts              # File pattern matching
-│   ├── list-dir.ts          # Directory listing
-│   ├── web-fetch.ts         # URL fetch + HTML→text
-│   ├── web-search.ts        # DuckDuckGo Lite — no API key
-│   ├── stitch.ts            # Google Stitch MCP wrapper (opt-in via /stitch-config)
-│   └── index.ts             # ALL_TOOLS registry (stitch only listed when configured)
-├── hooks.ts                 # PreToolUse / PostToolUse / SessionStart / SessionStop dispatcher
-├── hook-controls.ts         # Hook profile system (minimal/standard/strict)
-├── permissions.ts           # ask/auto/yolo gating per tool
-├── security.ts              # Dangerous-command + secret-write scanner
-├── sessions.ts              # ~/.crowcoder/sessions/*.json — save/load/resume
-├── memory.ts                # Cross-session project memory
-├── learning.ts              # Instincts: pattern extraction, confidence decay, pruning
-├── skills.ts                # Skill JSON store + trigger-based auto-injection
-├── skill-create.ts          # Distill new skills from git history patterns
-├── orchestration.ts         # /orchestrate + /multi-* parallel sub-agent prompts
-├── autonomous-loops.ts      # /pr-loop + multi-plan/multi-execute prompts
-├── search-first.ts          # /search-first /docs-lookup research-before-code prompts
-├── modes.ts, codemaps.ts, compaction.ts, strategic-compaction.ts
-├── verification.ts          # /verify /test-coverage prompts + checkpoint helpers
-├── refactor.ts              # /refactor /refactor-clean prompts
-├── evaluation.ts            # /review /tdd /security-review /audit /plan prompts
-├── content-engine.ts        # /article /slides /investor-deck /chief-of-staff prompts
-├── git-workflow.ts          # /commit /pr /diff /log + branch helpers
-├── agents.ts                # 10 language-specific review + build-fix prompt builders
-├── cost-tracker.ts          # ~/.crowcoder/usage.json — token counts, cost estimates
-├── model-router.ts          # /route — complexity-based model switching
-├── docs-sync.ts             # /update-docs + project language detection
-├── package-detect.ts        # /detect — package manager / test runner / build tool
-├── rules.ts                 # Language-specific coding rules (loaded into system prompt)
-├── pm2-manager.ts           # /pm2 wrapper
-├── theme.ts                 # TUI colors + splash + banner + tool-call rendering
-├── retry.ts                 # API call retry with backoff
-├── export.ts                # /export md/json/txt
-├── html-parser.ts           # HTML→text for web_fetch
-└── types.ts                 # CrowcoderConfig, Message, Session, Mode types
-
-bin/
-└── crowcoder.js             # CLI entry — DEP0040 suppress + dynamic import dist/index.js
-
-resources/
-└── ecc/                     # Bundled everything-claude-code library
-    ├── skills/              # 33 SKILL.md files (one per skill)
-    ├── agents/              # 16 kiro agent JSON+MD pairs
-    ├── commands/            # 9 workflow command prompts
-    ├── rules/               # 39 language-specific rule files
-    └── prompts/             # 6 GitHub prompt files
-
-tests/
-├── smoke-commands.mjs       # 88-command dispatch smoke test (no LLM calls)
-├── llm-drive-all.mjs        # End-to-end LLM driver against a real API
-├── users.test.ts            # Vitest unit tests
-└── e2e/                     # Playwright E2E
-```
-
----
-
-## 🤝 Contributing
-
-PRs welcome. Please:
 
-- Strict TypeScript — avoid `any`
-- Focused PRs — one thing per PR
-- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`)
-- Never commit API keys, tokens, or paths containing your username
-- Run `node tests/smoke-commands.mjs` before submitting — must report `88/88 pass`
+Rebuild after edits with `npm run build` (or `npx tsc`). The `prepare` script also runs `tsc` on `npm install`, so a clean clone produces a working `dist/` without an extra step.
 
-For larger features (new mode, new tool, new orchestration pattern), open an issue first to discuss the design.
+Update: `npm install -g compact-agent@latest`. Uninstall: `npm uninstall -g compact-agent && rm -rf ~/.compact-agent`.
 
 ---
 
-## 📜 License
+## Contributing
 
-Distributed under the **[MIT License](LICENSE)**.
+PRs welcome. Strict TypeScript (avoid `any`), one thing per PR, Conventional Commits, no API keys in diffs. Run `node tests/smoke-commands.mjs` before submitting.
 
-Crowcoder bundles content from these projects, each under their own license:
-- [everything-claude-code](https://github.com/Crownelius/everything-claude-code) — agent harness library
-- [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent) — Hermes mode inspiration
+For larger features (new mode, new tool, new orchestration pattern), open an issue first.
 
 ---
 
-<div align="center">
+## License
 
-**Compact Agent** — Built to fit a lot of intelligence in a small command.
+[MIT](LICENSE).
 
-[Bug reports](https://github.com/Crownelius/Crowcoder/issues) • [Install guide](INSTALL.md) • [Command reference](COMMANDS.md) • [npm](https://www.npmjs.com/package/compact-agent)
+Bundles content from:
+- [everything-claude-code](https://github.com/Crownelius/everything-claude-code) — skill / agent / hook harness
+- [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent) — Hermes mode reference
 
-</div>
+[Bug reports](https://github.com/Crownelius/compact-agent/issues) · [Install guide](INSTALL.md) · [Commands](COMMANDS.md) · [npm](https://www.npmjs.com/package/compact-agent)