@phuetz/code-buddy 0.1.25 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Code Buddy
 
-### Multi-AI Personal Assistant with OpenClaw-Inspired Architecture
+### Your AI-Powered Development Tool & Personal Assistant
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@phuetz/code-buddy"><img src="https://img.shields.io/npm/v/@phuetz/code-buddy.svg?style=flat-square&color=ff6b6b&label=version" alt="npm version"/></a>
@@ -22,149 +22,62 @@
 
 <br/>
 
-**A powerful multi-AI terminal agent inspired by [OpenClaw](https://github.com/openclaw/openclaw) architecture. Supports Grok, Claude, ChatGPT, Gemini, LM Studio, and Ollama with advanced memory, multi-channel messaging, and intelligent context management.**
+**A multi-AI terminal agent that writes code, runs commands, searches the web, talks to you, and manages your projects — from your terminal, your phone, or running 24/7 in the background.**
 
 <br/>
 
-[Quick Start](#-quick-start) |
+[Quick Start](#quick-start) |
+[Development Tool](#development-tool) |
+[Personal Assistant](#personal-assistant) |
+[Channels](#multi-channel-messaging) |
+[Autonomous Agent](#autonomous-agent) |
+[Security](#security--trust) |
 [CLI Reference](#cli-reference) |
-[Architecture](#-architecture) |
-[Channels](#-multi-channel-support) |
-[Security](#-security) |
-[API](#-api-server)
+[API](#api-server--integrations)
 
 </div>
 
 ---
 
-## What's New
-
-### OpenClaw-Inspired Features
-
-Code Buddy incorporates advanced patterns from the [OpenClaw](https://github.com/openclaw/openclaw) project:
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Tool Policy System** | ✅ 100% | Fine-grained tool permissions with allowlist/denylist |
-| **Bash Allowlist** | ✅ 100% | Secure command execution with pattern matching |
-| **Context Window Guard** | ✅ 100% | Automatic context management with 34 test cases |
-| **Smart Compaction** | ✅ 100% | Multi-stage conversation compression |
-| **Context Pruning** | ✅ 100% | TTL-based message expiration |
-| **Hybrid Search** | ✅ 100% | Combined keyword + semantic search |
-| **Lifecycle Hooks** | ✅ 100% | Pre/post hooks with 52 test cases |
-| **Connection Profiles** | ✅ 100% | Multi-provider switching with 57 tests |
-| **Desktop Automation** | ✅ 100% | Screen capture, OCR, UI control |
-| **Gemini Vision** | ✅ 100% | Native image support via `inlineData` (base64 data URLs) |
-| **Auto-Capture Memory** | ✅ 100% | Pattern-based memory extraction |
-| **Memory Lifecycle** | ✅ 100% | Auto-recall and auto-capture hooks |
-
-### Phase 3 — Streaming & Security
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Middleware Pipeline** | ✅ 100% | Composable before/after turn hooks (cost limit, context warning, turn limit) |
-| **Reasoning Events** | ✅ 100% | Streaming chain-of-thought display with collapsible UI |
-| **Trust Folders** | ✅ 100% | Directory-level tool permissions via `.codebuddy-trust.json` |
-| **Agent Profiles** | ✅ 100% | Predefined agent configs (secure, minimal, power-user) |
-| **Tool Streaming** | ✅ 100% | Real-time bash output via AsyncGenerator |
-| **TabbedQuestion UI** | ✅ 100% | Multi-option interactive prompts |
-
-### Phase 4 — Autonomous Agent
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Daemon Mode** | ✅ 100% | Background process with PID management, auto-restart (max 3) |
-| **Cron-Agent Bridge** | ✅ 100% | Scheduled task execution via CodeBuddyAgent instances |
-| **Task Planner** | ✅ 100% | DAG-based decomposition with topological sort and parallel execution |
-| **Screen Observer** | ✅ 100% | Periodic screenshots, perceptual diff, event triggers |
-| **Proactive Agent** | ✅ 100% | Push notifications, question/response, rate limiting, quiet hours |
-| **Orchestrator** | ✅ 100% | Multi-agent supervisor (sequential/parallel/race/all strategies) |
-| **Self-Healing** | ✅ 100% | Error pattern recognition, auto-recovery with exponential backoff |
-| **Checkpoint Rollback** | ✅ 100% | Auto-checkpoint before risky ops, rollback to last good state |
-| **Shared Context** | ✅ 100% | Thread-safe key-value store with optimistic locking |
-
-### Phase 5 — OpenClaw-Inspired Platform
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Doctor Command** | ✅ 100% | Environment/deps/config diagnostics (`buddy doctor`) |
-| **Onboarding Wizard** | ✅ 100% | Interactive setup wizard (`buddy onboard`) |
-| **Model Failover Chain** | ✅ 100% | Cascading provider fallback with health tracking |
-| **Webhook Triggers** | ✅ 100% | HMAC-verified HTTP triggers + CLI + API routes |
-| **Typing Indicators** | ✅ 100% | Presence & typing events for channels |
-| **Live Canvas** | ✅ 100% | WebSocket-driven visual workspace (A2UI) |
-| **Docker Sandbox** | ✅ 100% | Containerized command execution with resource limits |
-| **Skills Registry** | ✅ 100% | Bundled/managed/workspace skills with YAML frontmatter |
-| **Media Pipeline** | ✅ 100% | Ingest, track, transcode with transcription hooks |
-| **ACP Protocol** | ✅ 100% | Inter-agent communication router with request/response |
-| **Extension System** | ✅ 100% | Manifest-based plugin loader with lifecycle hooks |
-| **Copilot Proxy** | ✅ 100% | IDE-compatible completions backend (`/v1/completions`) |
-
-### Phase 6 — Robustness & Developer Experience
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Web Search 5-Provider Chain** | ✅ 100% | Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo with country/freshness/lang |
-| **Apply Patch Tool** | ✅ 100% | Unified diff parser and applier with fuzz factor (Codex-inspired) |
-| **Bash Parser** | ✅ 100% | AST-based command parsing via tree-sitter-bash with state-machine fallback |
-| **Per-Model Tool Config** | ✅ 100% | Capabilities, context window, patch format per model family |
-| **Head/Tail Truncation** | ✅ 100% | Smart output truncation keeping start + end of large results |
-| **Session Locks** | ✅ 100% | PID-based file locking with stale detection |
-| **Skill Scanner** | ✅ 100% | Static analysis of SKILL.md files for dangerous patterns (24 rules) |
-| **History Repair** | ✅ 100% | 5-pass self-repair for malformed LLM message sequences |
-| **Cache Trace** | ✅ 100% | Debug prompt construction stages (`CACHE_TRACE=true`) |
-| **Turn Diff Tracker** | ✅ 100% | Per-turn file change tracking with rollback capability |
-| **MCP Predefined Servers** | ✅ 100% | Brave Search, Playwright, Exa pre-configured in MCP |
-| **Headless Mode Fixes** | ✅ 100% | Clean JSON stdout, `process.exit(0)`, Gemini message sanitization |
-| **Gemini Conversation Repair** | ✅ 100% | 3-pass sanitization after context compression (orphan cleanup, role merge, user-start) |
-
-### Phase 7 — Code Generation Security
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Centralized Dangerous Patterns** | ✅ 100% | Single registry for all dangerous patterns (bash, code, skills) with severity levels |
-| **Generated Code Validator** | ✅ 100% | Pre-write security scan for eval, XSS, SQL injection, hardcoded secrets, prototype pollution |
-| **Pre-Write Syntax Validator** | ✅ 100% | Balanced delimiters, template literals, indentation (JS/TS/Python/YAML/HTML/CSS/JSON) |
-| **Atomic Rollback (apply-patch)** | ✅ 100% | All-or-nothing patch application with full file state backup |
-| **Atomic Transactions (multi-edit)** | ✅ 100% | Multi-file edits rolled back on first failure |
-| **AST Bash Command Validation** | ✅ 100% | tree-sitter integration in command validator with centralized pattern checks |
-| **Bash Checkpoint** | ✅ 100% | Pre-snapshot of files targeted by destructive commands (rm, mv, truncate) |
-| **Shell Injection Fix** | ✅ 100% | Code formatter uses `spawnSync` stdin pipe instead of `execSync` echo |
-| **Diff Preview in Confirmation** | ✅ 100% | Shows actual diffs before approval, magnitude-based re-confirmation for large changes |
-| **Architect Parallel Execution** | ✅ 100% | Dependency-wave-based parallel step execution with DAG ordering |
-| **Semantic Truncation** | ✅ 100% | Error-preserving output truncation (keeps error lines, stack traces from middle sections) |
-| **Auto-Sandbox Router** | ✅ 100% | Automatic Docker routing for dangerous commands (npm, pip, cargo, make) |
-| **Security Audit Logging** | ✅ 100% | JSONL audit trail for all code generation security decisions |
-| **Copilot Proxy Hardening** | ✅ 100% | Per-IP rate limiting, token clamping, auth bypass fix, sanitized error messages |
-
-### Phase 8 — OpenClaw Parity (Final)
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **Skills Auto-Discovery** | ✅ 100% | Agent auto-finds/installs skills from hub when tool confidence is low |
-| **Device Node Connectors** | ✅ 100% | Real SSH, ADB, and local transports with platform-specific commands |
-| **Canvas Bidirectional Events** | ✅ 100% | Browser→agent event routing, data binding observers, state queries |
-
-### Phase 9 — External Tool Integration
-
-| Module | Status | Description |
-|:-------|:------:|:------------|
-| **RTK Output Compressor** | ✅ 100% | [RTK](https://github.com/rtk-ai/rtk) integration — compresses bash output 60-90% via format-aware parsing, reducing token usage |
-| **ICM Memory Bridge** | ✅ 100% | [ICM](https://github.com/rtk-ai/icm) MCP server — persistent cross-session memory with episodic + semantic dual architecture |
-| **RTK Tool Hook** | ✅ 100% | After-hook at priority 90 auto-compresses bash results > 500 chars (configurable) |
-| **ICM MCP Predefined Server** | ✅ 100% | Pre-configured `icm mcp` stdio transport in MCP predefined servers |
-| **Integrations Config** | ✅ 100% | New `[integrations]` TOML section for RTK/ICM enable/disable and thresholds |
-| **Doctor RTK/ICM Checks** | ✅ 100% | `buddy doctor` reports RTK and ICM binary availability |
+## What is Code Buddy?
+
+Code Buddy is an open-source multi-provider AI coding agent that runs in your terminal. It supports **Grok, Claude, ChatGPT, Gemini, LM Studio, and Ollama** via OpenAI-compatible APIs and provider-specific SDKs.
+
+It works as two things at once:
+
+- **A development tool** — reads files, writes code, runs commands, creates PRs, plans complex tasks, and fixes its own mistakes across 5-50 tool calls per task.
+- **A personal assistant** — talks to you by voice, remembers your preferences, monitors your screen, sends notifications to your phone via Telegram/Discord/Slack, and runs scheduled tasks 24/7 in the background.
+
+**Key highlights:**
+- 6 AI providers with automatic failover
+- 40 bundled skills (PR workflow, DevOps, creative tools, smart home, media)
+- 11 messaging channels (Terminal, Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, Google Chat, WebChat, HTTP API)
+- Daemon mode for 24/7 background operation
+- Multi-agent orchestration with self-healing
+- Voice conversation with wake word detection
+- OS sandbox with workspace-write mode (read-only / workspace-write / danger-full-access tiers)
+- Docker sandbox for untrusted code execution
+- Knowledge base injection (Knowledge.md files loaded into agent system prompt)
+- Wide Research mode (parallel sub-agents decompose and research topics concurrently)
+- Todo.md attention bias (task list appended to end of every LLM context turn — Manus AI pattern)
+- Lessons.md self-improvement loop (PATTERN/RULE/CONTEXT/INSIGHT lessons injected before every turn — persists corrections across sessions)
+- Workflow orchestration rules in system prompt (concrete plan triggers, auto-correction protocol, verification contract)
+- Restorable context compression (identifiers preserved, full content recoverable on demand)
+- Pre-compaction memory flush (facts saved to MEMORY.md before context is compacted — OpenClaw pattern)
+- Anthropic prompt cache breakpoints (stable/dynamic split → 10× token cost savings)
+- Per-channel streaming policies (Telegram, Discord, Slack, WhatsApp each get their own chunking/format rules)
+- SSRF guard on all outbound fetches (IPv4 + IPv6 bypass vector blocking)
+- Tool prefix naming convention (`shell_exec`, `file_read`, `browser_search`, … — Codex-style canonical aliases)
 
 ---
 
-## Installation
+## Quick Start
 
 ### Prerequisites
 
 - **Node.js** 18.0.0 or higher
 - **ripgrep** (recommended for faster search)
-- **tree-sitter** + **tree-sitter-bash** (optional, for AST-based bash command parsing)
+- **Docker** (required for CodeAct / Open Manus mode)
 
 ```bash
 # macOS
@@ -175,12 +88,9 @@ sudo apt-get install ripgrep
 
 # Windows
 choco install ripgrep
-
-# Optional: tree-sitter for enhanced bash security parsing
-npm install tree-sitter tree-sitter-bash
 ```
 
-### Install Code Buddy
+### Install
 
 ```bash
 # npm (recommended)
@@ -190,9 +100,7 @@ npm install -g @phuetz/code-buddy
 npx @phuetz/code-buddy@latest
 ```
 
----
-
-## Quick Start
+### First Run
 
 ```bash
 # Configure API key (Grok/xAI)
@@ -277,210 +185,190 @@ Code Buddy autonomously reads files, writes code, runs commands, and fixes error
 
 ---
 
-## Architecture
+## Development Tool
 
-Code Buddy uses a **facade architecture** for clean separation of concerns:
+### Agentic Coding
 
-```
-CodeBuddyAgent
-    │
-    ├── AgentContextFacade      # Context window and memory management
-    │       - Token counting, compression, memory retrieval
-    │
-    ├── SessionFacade           # Session persistence and checkpoints
-    │       - Save/load, checkpoint creation, rewind
-    │
-    ├── ModelRoutingFacade      # Model routing and cost tracking
-    │       - Provider selection, cost calculation
-    │
-    ├── InfrastructureFacade    # MCP, sandbox, hooks, plugins
-    │       - Hook execution, plugin loading
-    │
-    └── MessageHistoryManager   # Chat and LLM message history
-```
+Code Buddy operates as an autonomous coding agent. It reads your codebase, makes changes, runs commands, and iterates until the task is done.
 
-### Autonomy Layer (Phase 4)
+**Built-in tools:**
 
-```
-CodeBuddyAgent
-    │
-    ├── TaskPlanner             # DAG decomposition of complex requests
-    │       - needsPlanning() heuristic
-    │       - createPlan() → TaskGraph → parallel execution
-    │
-    ├── SupervisorAgent         # Multi-agent orchestration
-    │       - Sequential, parallel, race, all strategies
-    │       - SharedContext with optimistic locking
-    │
-    ├── SelfHealing             # Automatic error recovery
-    │       - Pattern recognition (6 built-in patterns)
-    │       - Retry with exponential backoff
-    │
-    ├── ScreenObserver          # Environment monitoring
-    │       - Periodic screenshots with perceptual diff
-    │       - Event triggers (file_change, screen_change, time, webhook)
-    │
-    ├── ProactiveAgent          # Agent-initiated communication
-    │       - Push notifications with priority levels
-    │       - Rate limiting and quiet hours
-    │
-    └── DaemonManager           # Background process lifecycle
-            - PID file management, auto-restart
-            - Service registry, health monitoring
-```
+| Category | Tools |
+|:---------|:------|
+| **File Operations** | `view_file`, `create_file`, `str_replace_editor`, `edit_file`, `multi_edit` |
+| **Search** | `search`, `codebase_map` |
+| **System** | `bash`, `docker`, `kubernetes` |
+| **CodeAct** | `run_script` (Python/JS/TS in Docker), `plan` (Persistent Planner) |
+| **Web** | `web_search`, `web_fetch`, `browser` |
+| **Patching** | `apply_patch` (unified diff with fuzz factor, Codex-inspired) |
+| **Planning** | `create_todo_list`, `get_todo_list`, `update_todo_list` |
+| **Media** | `screenshot`, `audio`, `video`, `ocr`, `clipboard` |
+| **Documents** | `pdf`, `document`, `archive` |
+| **Knowledge** | `knowledge_search`, `knowledge_add` — search/add knowledge base entries |
+| **Human Input** | `ask_human` — pause execution for mid-task user clarification (120s timeout) |
+| **Self-Extension** | `create_skill` — write new SKILL.md files at runtime (self-authoring) |
+| **Self-Improvement** | `lessons_add`, `lessons_search`, `lessons_list` — persist and recall learned patterns across sessions |
+| **Verification** | `task_verify` — run tsc/tests/lint before marking tasks complete (Verification Contract) |
 
-### Core Flow
+**RAG-based tool selection** filters tools per query to reduce prompt tokens — only relevant tools are included in each API call.
 
-```
-User Input → ChatInterface (Ink/React) → CodeBuddyAgent → AI Provider
-                                              │
-                                         Tool Calls (max 50/400 rounds)
-                                              │
-                                      Tool Execution + Confirmation
-                                              │
-                                        Results back to API (loop)
-```
+### Code Intelligence
 
----
+**Web Search (5-Provider Fallback Chain):**
 
-## CLI Reference
+| Priority | Provider | API Key Required | Features |
+|:---------|:---------|:-----------------|:---------|
+| 1 | **Brave MCP** | `BRAVE_API_KEY` + MCP enabled | Full MCP integration, richest results |
+| 2 | **Brave API** | `BRAVE_API_KEY` | Country, language, freshness filters |
+| 3 | **Perplexity** | `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` | AI-synthesized answers with citations |
+| 4 | **Serper** | `SERPER_API_KEY` | Google Search results |
+| 5 | **DuckDuckGo** | None | Free fallback (no API key needed) |
 
-### Global Options
+Search parameters: `country` (ISO 3166), `search_lang`, `ui_lang`, `freshness` (`pd`/`pw`/`pm`/`py` or date range), `provider` (force specific).
 
-| Flag | Short | Description | Default |
-|:-----|:------|:------------|:--------|
-| `--version` | `-V` | Show version number | - |
-| `--directory <dir>` | `-d` | Set working directory | `.` |
-| `--api-key <key>` | `-k` | API key (or `GROK_API_KEY` env) | - |
-| `--base-url <url>` | `-u` | API base URL (or `GROK_BASE_URL` env) | - |
-| `--model <model>` | `-m` | AI model to use (or `GROK_MODEL` env) | auto-detect |
-| `--prompt <prompt>` | `-p` | Single prompt, headless mode | - |
-| `--browser` | `-b` | Launch browser UI instead of terminal | `false` |
-| `--max-tool-rounds <n>` | | Max tool execution rounds | `400` |
-| `--security-mode <mode>` | `-s` | `suggest`, `auto-edit`, or `full-auto` | `suggest` |
-| `--output-format <fmt>` | `-o` | Headless output: `json`, `stream-json`, `text`, `markdown` | `json` |
-| `--context <patterns>` | `-c` | Glob patterns to load into context | - |
+**Context management** uses smart multi-stage compaction (remove stale tool results, summarize older messages, aggressive truncation) to keep conversations within token limits across long sessions.
 
-### Session & Cost
+**Hybrid search** combines keyword + semantic search with configurable weights for memory retrieval.
 
-| Flag | Description | Default |
-|:-----|:------------|:--------|
-| `--continue` | Resume the most recent saved session | - |
-| `--resume <id>` | Resume a specific session (supports partial ID matching) | - |
-| `--max-price <dollars>` | Maximum cost in dollars before stopping | `10.0` |
-| `--no-cache` | Disable response caching | - |
+### 🚀 Open Manus Features (CodeAct)
 
-### Autonomy & Permissions
+Code Buddy implements the **Open Manus / CodeAct** architecture in a structured, phased approach, allowing it to write and execute code (Python, TypeScript, Node.js) in a secure Docker sandbox instead of relying solely on pre-defined tools.
 
-| Flag | Description | Default |
-|:-----|:------------|:--------|
-| `--auto-approve` | Automatically approve all tool executions | `false` |
-| `--dangerously-skip-permissions` | Bypass all permission checks (trusted containers only) | `false` |
-| `--no-self-heal` | Disable self-healing auto-correction | - |
-| `--allow-outside` | Allow file operations outside workspace directory | `false` |
+**Phase 1: Sandboxed Execution (Hybrid Agent)**
+*   **RunScriptTool:** Writes and runs scripts in ephemeral Docker containers (`ubuntu:latest`, `node:22-slim`, `python:3.11-slim`).
+*   **Browser Automation:** Uses `Playwright` in Docker to scrape websites, interact with SPAs, and take screenshots programmatically.
+*   **Safety First:** Timeout (120s), Memory Limit (1GB), and ephemeral containers prevent runaway processes.
 
-### Tool Control
+**Phase 2: Persistent State & Planning**
+*   **Persistent Workspace:** Files created in `.codebuddy/workspace` persist between script executions, allowing multi-step workflows (e.g., scrape → save CSV → analyze CSV → plot chart).
+*   **PlanTool:** The agent maintains a `PLAN.md` file in your project root to track complex, multi-step objectives statefully.
+*   **Structured Loop:** The system prompt enforces a strict **PLAN → THINK → CODE → OBSERVE → UPDATE** cognitive cycle to prevent chaotic behavior.
 
-| Flag | Description | Example |
-|:-----|:------------|:--------|
-| `--force-tools` | Force-enable function calling for local models | - |
-| `--probe-tools` | Auto-detect tool support at startup | - |
-| `--enabled-tools <patterns>` | Only enable matching tools (glob, comma-separated) | `bash,*file*,search` |
-| `--disabled-tools <patterns>` | Disable matching tools (glob, comma-separated) | `bash,web_*` |
-| `--allowed-tools <patterns>` | Alias for `--enabled-tools` (Claude Code compat) | - |
+**Phase 3: Wide Research (Parallel Agents)**
+*   **WideResearchOrchestrator:** Decomposes a topic into N independent subtopics via LLM, spawns N parallel CodeBuddyAgent workers (default: 5, max: 20), then aggregates results into a single comprehensive report.
+*   **Progress streaming:** Emits real-time events as each worker completes.
+*   **CLI:** `buddy research "quantum computing breakthroughs" --workers 8 --output report.md`
 
-### Agent & Prompt Configuration
+**Phase 4: Context Engineering (Manus AI + OpenClaw patterns)**
 
-| Flag | Description | Default |
-|:-----|:------------|:--------|
-| `--system-prompt <id>` | System prompt: `default`, `minimal`, `secure`, `code-reviewer`, `architect` (or custom from `~/.codebuddy/prompts/`) | `default` |
-| `--list-prompts` | List available system prompts and exit | - |
-| `--agent <name>` | Use a custom agent from `~/.codebuddy/agents/` | - |
-| `--list-agents` | List available custom agents and exit | - |
+*   **Todo.md Attention Bias** — The agent maintains a `todo.md` task list that is automatically appended at the **end** of the LLM context on every turn. Because transformers attend more strongly to recent tokens, this keeps objectives in focus across long sessions without modifying the system prompt. Use `buddy todo add/done/list` or the `todo_update` tool.
+*   **Restorable Compression** — When the context window is compressed, file paths and URLs are extracted as identifiers and the original content is stored. The agent can call `restore_context("src/agent/types.ts")` to retrieve the full content on demand, making compression lossless for structured identifiers.
+*   **Pre-compaction Memory Flush (NO_REPLY)** — Before compaction triggers, a silent background LLM turn extracts durable facts and saves them to `MEMORY.md`. If the model returns the `NO_REPLY` sentinel with no meaningful content, the output is suppressed entirely (no notification spam).
+*   **Inline Citations** — Web search results now include `[1]` `[2]` citation markers inline and a **Sources** block listing all referenced URLs.
+*   **Lessons.md Self-Improvement Loop** — After any user correction, the agent calls `lessons_add` to persist the lesson (category: PATTERN, RULE, CONTEXT, or INSIGHT) to `.codebuddy/lessons.md`. On every turn, active lessons are injected as a `<lessons_context>` block BEFORE the todo suffix so learned patterns are always visible. Use `buddy lessons add/search/list` or the `lessons_add`/`lessons_search` tools. The `task_verify` tool runs the **Verification Contract** (tsc + tests + lint) before any task completion.
 
-### Display & Debugging
+**Example Prompts:**
 
-| Flag | Description |
-|:-----|:------------|
-| `--plain` | Minimal formatting (plain text output) |
-| `--no-color` | Disable colored output |
-| `--no-emoji` | Disable emoji in output |
-| `--vim` | Enable Vim keybindings for input |
-| `--mcp-debug` | Enable MCP protocol debugging output |
+```bash
+> "Go to Google News, scrape the top headlines about AI, save them to a CSV, and then use Python to analyze the sentiment."
+> "Write a script to check broken links on my documentation site."
+> "Calculate the Fibonacci sequence up to 1000 and plot the growth rate."
+```
 
-### Setup & Init
+### 🧬 Roots & Comparison
 
-| Flag | Description |
-|:-----|:------------|
-| `--init` | Initialize `.codebuddy/` directory with templates |
-| `--dry-run` | Preview changes without applying (simulation mode) |
-| `--setup` | Run interactive API key setup wizard |
-| `--list-models` | List available models from the API and exit |
+Code Buddy is an evolution of the **OpenClaw** architecture, modernized for the TypeScript ecosystem and enhanced with **Open Manus** (CodeAct) autonomy.
 
----
+| Feature | OpenClaw | Code Buddy | Open Manus |
+|:---|:---|:---|:---|
+| **Language** | Python | **TypeScript / Node.js** | Python |
+| **Philosophy** | Tool-Based | **Hybrid (Tool + CodeAct)** | Pure CodeAct |
+| **Messaging** | Multi-channel | **11+ Channels (Telegram focus)** | Web Interface |
+| **Task State** | Heartbeat | **Persistent PLAN.md + Workspace** | Transient Session |
+| **Concurrency** | Lane Queue | **Advanced Lane Queue + DAG** | Sequential |
+| **Extensibility** | SKILL.md | **Skills Hub + Plugins + MCP** | Custom Scripts |
 
-## AI Providers
+**Why Code Buddy?**
+It combines the **industrial-grade reliability** of OpenClaw (concurrency control, security policies, multi-channel messaging) with the **infinite flexibility** of Open Manus (dynamic script generation and execution).
 
-Code Buddy supports multiple AI providers with automatic failover:
+> **Manus AI influence:** Wide Research (parallel sub-agent research workers), Knowledge Base injection, **todo.md attention bias** (task list at end of context each turn), and **restorable context compression** (identifier-based content recovery) are all inspired by Manus AI's context engineering research. The **pre-compaction NO_REPLY flush** pattern is from OpenClaw's compaction documentation.
 
-| Provider | Models | Context | Configuration |
-|:---------|:-------|:--------|:--------------|
-| **Grok** (xAI) | grok-4, grok-code-fast-1 | 128K | `GROK_API_KEY` |
-| **Claude** (Anthropic) | claude-sonnet-4, opus | 200K | `ANTHROPIC_API_KEY` |
-| **ChatGPT** (OpenAI) | gpt-4o, gpt-4-turbo | 128K | `OPENAI_API_KEY` |
-| **Gemini** (Google) | gemini-2.0-flash (+ vision) | 2M | `GOOGLE_API_KEY` |
-| **LM Studio** | Any local model | Varies | `--base-url http://localhost:1234/v1` |
-| **Ollama** | llama3, codellama, etc. | Varies | `--base-url http://localhost:11434/v1` |
+### Code Safety
 
-### Connection Profiles
+Code Buddy validates everything before it touches your files:
 
-Switch between providers using CLI options or configuration:
+| Feature | Description |
+|:--------|:------------|
+| **Generated Code Validator** | Pre-write scan for eval, XSS, SQL injection, hardcoded secrets, prototype pollution |
+| **Pre-Write Syntax Validator** | Balanced delimiters, template literals, indentation (JS/TS/Python/YAML/HTML/CSS/JSON) |
+| **Atomic Rollback (apply-patch)** | All-or-nothing patch application with full file state backup |
+| **Atomic Transactions (multi-edit)** | Multi-file edits rolled back on first failure |
+| **AST Bash Validation** | tree-sitter-based command parsing with centralized dangerous pattern checks |
+| **Bash Checkpoints** | Pre-snapshot of files targeted by destructive commands (rm, mv, truncate) |
+| **Diff Preview** | Shows actual diffs before approval, magnitude-based re-confirmation for large changes |
+| **Semantic Truncation** | Error-preserving output truncation (keeps error lines and stack traces) |
+| **Security Audit Logging** | JSONL audit trail for all code generation security decisions |
 
-```bash
-# Use LM Studio (local)
-buddy --base-url http://localhost:1234/v1 --api-key lm-studio
+### Task Planning
 
-# Use Ollama (local)
-buddy --base-url http://localhost:11434/v1 --model llama3
+For complex multi-step requests, Code Buddy decomposes work into a **DAG (directed acyclic graph)** and executes steps in parallel where possible.
 
-# Use a specific model
-buddy --model grok-code-fast-1
-```
+- **TaskPlanner** — `needsPlanning()` heuristic detects complex requests, `createPlan()` produces a TaskGraph
+- **Topological sort** — determines execution order with dependency tracking
+- **Parallel execution** — independent steps run concurrently via dependency waves
+- **Architect mode** — `--system-prompt architect` enables plan-first coding with per-step checkpoints
 
-### Profile Configuration
+### CI/CD Integration
+
+| Feature | Description |
+|:--------|:------------|
+| **CI Watcher** | GitHub Actions / GitLab CI / Jenkins alerts with "Fix it" auto-agent |
+| **Webhook Triggers** | HMAC-SHA256 verified HTTP triggers — connect CI, monitoring, or any service |
+| **Headless Mode** | `buddy -p "run tests and fix failures" --dangerously-skip-permissions` for CI pipelines |
+
+### Git Workflow
+
+Code Buddy handles the full Git lifecycle through natural language:
 
-```json
-// ~/.codebuddy/user-settings.json
-{
-  "connection": {
-    "activeProfileId": "grok",
-    "profiles": [
-      {
-        "id": "grok",
-        "name": "Grok API (xAI)",
-        "provider": "grok",
-        "baseURL": "https://api.x.ai/v1",
-        "model": "grok-4-latest"
-      },
-      {
-        "id": "lmstudio",
-        "name": "LM Studio Local",
-        "provider": "lmstudio",
-        "baseURL": "http://localhost:1234/v1",
-        "apiKey": "lm-studio"
-      }
-    ]
-  }
-}
 ```
+> "Create a PR for the auth changes"
+> "Review the open PRs"
+> "Fix the merge conflicts on feature-branch"
+> "Commit everything with a good message"
+```
+
+**Telegram enhanced commands** for remote Git operations:
+
+| Command | Description |
+|:--------|:------------|
+| `/repo` | Repository info, recent commits, open PRs |
+| `/branch [name]` | Branch diff stats vs main |
+| `/pr [number]` | List or view PRs with merge/review buttons |
 
 ---
 
-## Memory System
+## Personal Assistant
+
+### Voice Conversation
 
-Code Buddy features a sophisticated memory system inspired by OpenClaw:
+Full hands-free voice interaction with wake word detection:
 
-### Three Memory Subsystems
+```bash
+buddy speak "Hello, I am Code Buddy"         # Synthesize and play speech
+buddy speak --voice af_bella "Hello world"    # Use a specific voice
+buddy speak --list-voices                     # List available voices
+buddy speak --speed 1.5 "Fast speech"         # Adjust speed (0.25-4.0)
+buddy speak --format mp3 "Hello"              # Output format (wav, mp3)
+buddy speak --url http://host:8000 "Hello"    # Custom AudioReader URL
+```
+
+**7 TTS providers:** Edge TTS, espeak, macOS `say`, Piper, OpenAI, ElevenLabs, AudioReader (Kokoro-82M local)
+
+**In-chat voice commands:**
+
+| Command | Description |
+|:--------|:------------|
+| `/speak <text>` | Speak text with current TTS provider |
+| `/tts on\|off` | Enable/disable TTS |
+| `/tts auto` | Auto-speak all agent responses |
+| `/tts provider audioreader` | Switch to AudioReader (Kokoro-82M, local, free) |
+| `/tts voice ff_siwis` | Set voice (e.g., `ff_siwis` FR, `af_bella` EN) |
+
+**Wake word detection** via Porcupine (Picovoice) with text-match fallback. Set `PICOVOICE_ACCESS_KEY` for hardware-accelerated detection, or use the built-in text matcher for free.
+
+**Infinite voice conversation:** Enable `continuousListening` + `autoSpeak` with AudioReader for a hands-free loop: listen → STT → agent → TTS → listen.
+
+### Memory System
 
 | Subsystem | Storage | Purpose |
 |:----------|:--------|:--------|
@@ -489,12 +377,9 @@ Code Buddy features a sophisticated memory system inspired by OpenClaw:
 | **Prospective Memory** | SQLite | Tasks, goals, reminders |
 | **ICM (optional)** | [ICM MCP server](https://github.com/rtk-ai/icm) | Persistent cross-session memory via episodic + semantic dual architecture |
 
-### Auto-Capture (OpenClaw Pattern)
-
-Automatically detects and stores important information:
+**Auto-capture** detects and stores important information from conversations:
 
-```typescript
-// Detected patterns (English + French)
+```
 "Remember that..."        → Stored as instruction
 "I prefer..."             → Stored as preference
 "This project uses..."    → Stored as project fact
@@ -502,220 +387,604 @@ Automatically detects and stores important information:
 "We decided to..."        → Stored as decision
 ```
 
-### Memory Lifecycle Hooks
-
-```typescript
-// Before execution: Inject relevant memories
-beforeExecute(context) → { injectedContext, recalledMemories }
-
-// After response: Capture important info
-afterResponse(context) → { capturedCount, capturedMemories }
-
-// Session end: Summarize conversation
-sessionEnd(sessionId) → { summaryId, memoriesStored }
-```
-
-### Deduplication
-
-- Jaccard similarity threshold: 0.95
-- Hash-based recent capture cache
-- Automatic duplicate detection
-
----
-
-## Multi-Channel Support
-
-Code Buddy supports multiple messaging channels:
-
-| Channel | Status | Features |
-|:--------|:------:|:---------|
-| **Terminal** | ✅ Full | Native CLI interface (Ink/React) |
-| **HTTP API** | ✅ Full | REST + WebSocket |
-| **WebChat** | ✅ Full | Built-in HTTP + WebSocket with browser UI |
-| **Discord** | 🟡 Base | Bot integration, slash commands |
-| **Telegram** | 🟡 Base | Bot API, message handlers |
-| **Slack** | 🟡 Base | Bolt framework, events |
-| **WhatsApp** | 🟡 Base | Baileys (QR pairing, media, reconnect) |
-| **Signal** | 🟡 Base | signal-cli REST API (polling, groups) |
-| **Google Chat** | 🟡 Base | Workspace API (JWT auth, webhook events) |
-| **Microsoft Teams** | 🟡 Base | Bot Framework (OAuth2, adaptive cards) |
-| **Matrix** | 🟡 Base | matrix-js-sdk (E2EE, threads, media) |
-
-### Channel Configuration
-
-```typescript
-// Enable Discord channel
-const discord = new DiscordChannel({
-  token: process.env.DISCORD_TOKEN,
-  allowedGuilds: ['guild-id'],
-});
-await discord.connect();
-```
-
----
-
-## Security
+**Memory lifecycle hooks** inject relevant memories before execution, capture important info after responses, and summarize conversations at session end. Deduplication via Jaccard similarity (0.95 threshold) prevents duplicates.
 
-### Tool Policy System
-
-Fine-grained control over tool execution:
-
-```typescript
-const policy = new ToolPolicy({
-  allowlist: ['read_file', 'search', 'web_fetch'],
-  denylist: ['bash', 'write_file'],
-  requireConfirmation: ['delete_file'],
-});
-```
+### Knowledge Base
 
-### Bash Allowlist
+Domain knowledge injected into the agent system prompt at startup (`src/knowledge/knowledge-manager.ts`):
 
-Secure command execution:
+* **Sources:** `Knowledge.md` (project root), `.codebuddy/knowledge/*.md` (project-level), `~/.codebuddy/knowledge/*.md` (global)
+* **YAML frontmatter:** `title`, `tags`, `scope` (restrict to specific agent modes), `priority` (injection order)
+* **Agent tools:** `knowledge_search` (keyword search across all entries), `knowledge_add` (persist new knowledge to disk)
+* **Injection:** Loaded entries are wrapped in a `<knowledge>` block and included in the system prompt automatically.
 
-```typescript
-const bashPolicy = new BashAllowlist({
-  patterns: [
-    /^npm (install|test|run)/,
-    /^git (status|diff|log)/,
-    /^ls -la?/,
-  ],
-  blocked: [
-    /rm -rf/,
-    /sudo/,
-    /curl.*\|.*sh/,
-  ],
-});
+```bash
+buddy knowledge list             # List all loaded knowledge entries
+buddy knowledge show <title>     # Show a specific entry
+buddy knowledge search "TypeScript conventions"
+buddy knowledge add              # Interactive: add a new knowledge entry
+buddy knowledge remove <title>   # Remove an entry
+buddy knowledge context          # Show the full <knowledge> block the agent sees
 ```
 
-### Security Modes
+### Skills Library (40 Bundled Skills)
 
-| Mode | Description |
-|:-----|:------------|
-| `suggest` | Confirm all operations |
-| `auto-edit` | Auto-approve safe ops |
-| `full-auto` | Full autonomy (YOLO) |
+Code Buddy includes 40 built-in SKILL.md files that provide domain-specific knowledge, best practices, and MCP server integration. Skills are loaded contextually when relevant to your project.
 
-```bash
-/mode suggest    # Maximum safety
-/mode full-auto  # Full autonomy
+| Category | Skill | Description |
+|----------|-------|-------------|
+| **PR Workflow** | `review-pr` | Code review checklist, inline comments, approval criteria |
+| | `prepare-pr` | Branch naming, commit cleanup, PR description template |
+| | `merge-pr` | Merge strategies, conflict resolution, post-merge cleanup |
+| **Dev Tools** | `github` | Issues, releases, Actions workflows, gh CLI |
+| | `gitlab` | GitLab API, glab CLI, CI/CD pipelines, merge requests |
+| | `session-logs` | Export/search conversation history and session metadata |
+| | `model-usage` | Token tracking, cost analysis, provider comparison |
+| | `tmux-sessions` | Terminal multiplexing, pane layouts, session management |
+| | `healthcheck` | Service monitoring, endpoint checks, alerting |
+| **Project** | `project-best-practices` | Project scaffolding, structure, linting, testing conventions |
+| | `csharp-avalonia` | Cross-platform desktop/mobile with C# and Avalonia UI |
+| | `coding-agent` | Autonomous multi-step coding with planning and validation |
+| | `skill-creator` | Author new SKILL.md files with YAML frontmatter |
+| **Creative & 3D** | `blender` | Python bpy scripting, CLI rendering, Geometry Nodes |
+| | `unreal-engine` | Remote Control API, Python editor scripting, Movie Render Queue |
+| | `davinci-resolve` | DaVinciResolveScript Python API, color grading, render queue |
+| | `ableton-live` | OSC protocol, MIDI Remote Scripts, Max for Live |
+| **Design** | `figma` | REST API, Plugin API, design tokens extraction |
+| | `gimp` | Python-Fu / Script-Fu scripting, batch image processing |
+| | `inkscape` | Extensions API, CLI export, SVG manipulation |
+| **DevOps & Infra** | `kubernetes` | kubectl, Helm, ArgoCD GitOps |
+| | `terraform-ansible` | Terraform IaC + Ansible configuration management |
+| | `grafana-prometheus` | Grafana HTTP API, PromQL, alerting pipelines |
+| | `jenkins-ci` | Jenkins API, Groovy pipelines, shared libraries |
+| **Workflow & Data** | `n8n` | REST API, webhook triggers, workflow automation |
+| | `databases` | PostgreSQL, MongoDB, Redis CLI and automation |
+| | `game-engines` | Unity C# + Godot GDScript, builds, scene management |
+| **Utilities** | `summarize` | Text/file/URL summarization with configurable length |
+| | `weather` | Weather lookups via wttr.in and OpenWeatherMap |
+| **Media** | `image-gen` | Image generation via DALL-E, Stable Diffusion, Midjourney |
+| | `whisper-transcribe` | Audio/video transcription with OpenAI Whisper |
+| | `pdf-tools` | PDF creation, merging, text extraction, conversion |
+| | `screenshot` | Screen capture, annotation, OCR text extraction |
+| | `video-tools` | FFmpeg video editing, conversion, thumbnails, GIFs |
+| | `gif-search` | GIF search via Giphy and Tenor APIs |
+| **Communication** | `email-tools` | Email send/read via himalaya CLI and SMTP |
+| | `notion` | Notion API for pages, databases, search, content blocks |
+| | `blog-watcher` | RSS/Atom feed monitoring, web page change detection |
+| **Smart Home** | `spotify` | Spotify playback control via spotify_player and Web API |
+| | `smart-home` | Philips Hue and Home Assistant control |
+
+Each skill includes **Direct Control** (CLI/API/scripting commands), **MCP Server Integration** (config for `.codebuddy/mcp.json`), and **Common Workflows** (step-by-step recipes). Skills are stored in `.codebuddy/skills/bundled/` and can be extended with managed or workspace skills via the Skills Registry and Hub.
+
+**Self-authoring skills:** The agent can extend its own skill set at runtime using the `create_skill` tool, writing new SKILL.md files to `.codebuddy/skills/workspace/`. The SkillRegistry hot-reloads them within ~250ms, so newly created skills are immediately available without restarting.
+
+### Proactive Notifications
+
+The agent can reach out to you — not just respond:
+
+- **Push notifications** with priority levels (info, warning, critical)
+- **Rate limiting** prevents notification spam
+- **Quiet hours** — suppress non-critical notifications during configured periods
+- **Multi-channel delivery** — notifications route to Telegram, Discord, Slack, or any connected channel
+
+### Screen Observer
+
+Monitor your screen and environment for events:
+
+- **Periodic screenshots** with perceptual diff detection
+- **Event triggers** — `file_change`, `screen_change`, `time`, `webhook`
+- **Trigger registry** — add/remove triggers dynamically
+
+```bash
+buddy trigger list             # List all event triggers
+buddy trigger add <spec>       # Add a trigger (format: type:condition action:target)
+buddy trigger remove <id>      # Remove a trigger
 ```
 
-### Sandbox Isolation
+---
+
+## Multi-Channel Messaging
+
+Code Buddy supports 11 messaging channels:
+
+| Channel | Features |
+|:--------|:---------|
+| **Terminal** | Native CLI interface (Ink/React) |
+| **HTTP API** | REST + WebSocket |
+| **WebChat** | Built-in HTTP + WebSocket with browser UI |
+| **Discord** | Bot integration, slash commands |
+| **Telegram** | Bot API, pro features, scoped auth, CI watcher |
+| **Slack** | Bolt framework, events |
+| **WhatsApp** | Baileys (QR pairing, media, reconnect) |
+| **Signal** | signal-cli REST API (polling, groups) |
+| **Google Chat** | Workspace API (JWT auth, webhook events) |
+| **Microsoft Teams** | Bot Framework (OAuth2, adaptive cards) |
+| **Matrix** | matrix-js-sdk (E2EE, threads, media) |
+
+### Telegram (Deep Dive)
+
+Telegram is the most feature-rich channel, giving you full agent capabilities from your phone.
+
+**Setup:**
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) on Telegram (`/newbot`)
+2. Configure the token:
+
+```bash
+export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+```
+
+Or in `.codebuddy/settings.json`:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "type": "telegram",
+      "token": "123456:ABC-DEF...",
+      "adminUsers": ["your_telegram_user_id"],
+      "defaultParseMode": "Markdown"
+    }
+  }
+}
+```
+
+3. Start Code Buddy with Telegram:
+
+```bash
+buddy --channel telegram        # Interactive with Telegram
+buddy daemon start              # 24/7 background mode
+```
+
+**Deployment modes:**
+
+| Mode | Config | Best for |
+|:-----|:-------|:---------|
+| **Polling** (default) | No extra config | Development, behind NAT |
+| **Webhook** | `"webhookUrl": "https://your-domain.com/telegram"` | Production, lower latency |
+
+**Supported message types:** text, images, audio, video, documents, stickers, locations, contacts, inline buttons, reply threads, typing indicators.
+
+**What you can do via Telegram:**
+
+| Category | Capabilities |
+|:---------|:-------------|
+| **Remote Coding** | Code modifications, bug fixes, refactoring, file analysis, create commits & PRs |
+| **Bash Execution** | Run build, test, deploy commands — with confirmation for destructive ops |
+| **Rich Media** | Send images → Gemini Vision analysis, send files (code, logs) → processed by agent |
+| **Voice Messages** | Send voice notes → STT transcription → agent response |
+| **Daemon Mode** | 24/7 background operation (`buddy daemon start`), cron jobs, proactive alerts |
+| **Notifications** | Build failures, test results, heartbeat alerts pushed to your Telegram |
+| **Interactive** | Inline buttons for confirmations, Markdown-formatted responses |
+
+**Pro features:**
 
-Docker-based execution environment:
+| Feature | Description |
+|:--------|:------------|
+| **Scoped Authorization** | Tiered permissions: `read-only` → `write-patch` → `run-tests` → `deploy` |
+| **Diff-First Mode** | Preview all code changes before applying — Apply / Full Diff / Cancel buttons |
+| **Run Tracker** | Step-by-step timeline of agent runs with cost, duration, artifacts |
+| **CI Watcher** | GitHub Actions / GitLab CI / Jenkins alerts with "Fix it" auto-agent |
+| **Secret Handles** | Map friendly names to env vars — secrets never enter LLM context |
+| **Context Pins** | Pin important decisions or facts for the agent to remember |
+
+**Enhanced commands:**
+
+| Command | Description |
+|:--------|:------------|
+| `/repo` | Repository info, recent commits, open PRs |
+| `/branch [name]` | Branch diff stats vs main |
+| `/pr [number]` | List or view PRs with merge/review buttons |
+| `/task <desc>` | Create an agent task with objective |
+| `/runs` | List recent agent runs with timeline |
+| `/run <id>` | View run details with Re-run/Tests/Rollback buttons |
+| `/yolo [minutes]` | Timed full access (1-60 min, auto-revokes) |
+| `/pins` | View pinned context |
+
+**Example workflows:**
+
+Fix CI failure:
+```
+CI alert arrives → cause analysis → "Fix it" button
+→ agent creates fix → diff preview → Apply/Cancel
+→ changes applied → tests re-run
+```
+
+Add feature + tests + PR:
+```
+/task "add user search with tests"
+→ plan-first preview → approve plan
+→ diff-first preview → apply changes
+→ agent creates PR → link in chat
+```
+
+### DM Pairing (Access Control)
+
+Prevents unauthorized users from consuming API credits:
+
+1. Unknown user messages the bot → receives a **6-character pairing code** (expires in 15 min)
+2. Bot owner approves via CLI: `buddy pairing approve --channel telegram ABC123`
+3. User is added to the persistent allowlist (`~/.codebuddy/credentials/telegram-allowFrom.json`)
+
+Security features: rate limiting (5 failed attempts → 1h block), per-channel allowlists, admin bypass.
+
+**Pairing CLI commands:**
+
+```bash
+buddy pairing status             # Show pairing system status
+buddy pairing list               # List all approved users
+buddy pairing pending            # List pending pairing requests
+buddy pairing approve <code>     # Approve a pairing request by code
+buddy pairing add <id>           # Manually add a user to the allowlist
+buddy pairing revoke <id>        # Revoke access for a user
+```
+
+### Other Channels
 
 ```typescript
-const sandbox = new DockerSandbox({
-  image: 'codebuddy/sandbox:latest',
-  memoryLimit: '512m',
-  networkMode: 'none',
-  timeout: 30000,
+// Discord
+const discord = new DiscordChannel({
+  token: process.env.DISCORD_TOKEN,
+  allowedGuilds: ['guild-id'],
 });
+await discord.connect();
+
+// WhatsApp (Baileys, QR pairing)
+const whatsapp = new WhatsAppChannel({ dataPath: '~/.codebuddy/whatsapp' });
+await whatsapp.connect(); // Scan QR code
+
+// Signal (signal-cli REST API)
+const signal = new SignalChannel({ apiUrl: 'http://localhost:8080', phoneNumber: '+1234567890' });
+await signal.connect();
+
+// Matrix (E2EE, threads)
+const matrix = new MatrixChannel({ homeserverUrl: 'https://matrix.org', accessToken: '...' });
+await matrix.connect();
 ```
 
 ---
 
-## Context Management
+## Autonomous Agent
 
-### Context Window Guard
+### Daemon Mode
 
-Automatic context management with configurable thresholds:
+Run Code Buddy 24/7 in the background:
 
-```typescript
-const guard = new ContextWindowGuard({
-  maxTokens: 128000,
-  warningThreshold: 0.8,  // Warn at 80%
-  compactionThreshold: 0.9,  // Compact at 90%
-});
+```bash
+buddy daemon start [--detach]  # Start background daemon
+buddy daemon stop              # Stop daemon
+buddy daemon restart           # Restart daemon
+buddy daemon status            # Show daemon status and services
+buddy daemon logs [--lines N]  # View daemon logs
+```
+
+Features:
+- PID file management with stale detection
+- Auto-restart on crash (max 3 retries)
+- Service registry and health monitoring (CPU, memory)
+- **Heartbeat engine** — periodic agent wake with HEARTBEAT.md checklist, smart suppression, active hours
+
+```bash
+buddy heartbeat start          # Start the heartbeat engine
+buddy heartbeat stop           # Stop the heartbeat engine
+buddy heartbeat status         # Show heartbeat status
+buddy heartbeat tick           # Manually trigger a single tick
+```
+
+### Multi-Agent Orchestration
+
+The **SupervisorAgent** coordinates multiple agent instances:
+
+- **Strategies** — sequential, parallel, race, all
+- **Shared context** — thread-safe key-value store with optimistic locking
+- **Self-healing** — error pattern recognition (6 built-in patterns), auto-recovery with exponential backoff
+- **Checkpoint rollback** — auto-checkpoint before risky ops, rollback to last good state
+
+### YOLO Mode (Autonomous Execution)
+
+Full autonomy with built-in guardrails for safe unattended operation:
+
+```bash
+# Enable via CLI
+/yolo on           # Enable (50 auto-edits, 100 auto-commands)
+/yolo safe         # Restricted mode (20 edits, 30 commands, limited paths)
+/yolo off          # Disable
+/yolo status       # Show limits, counters, allow/deny lists
+
+# Or via environment
+YOLO_MODE=true buddy   # Still requires /yolo on confirmation in chat
+```
+
+**What changes in YOLO mode:**
+
+| Setting | Normal | YOLO |
+|:--------|:-------|:-----|
+| Tool rounds | 50 | 400 |
+| Cost limit | $10 | $100 (cap $1,000) |
+| File edits | Confirm each | Auto-approve (up to limit) |
+| Bash commands | Confirm each | Auto-execute safe commands |
+
+**Autonomy levels** (fine-grained control):
+
+```bash
+/autonomy suggest   # Confirm everything
+/autonomy confirm   # Confirm important ops (default)
+/autonomy auto      # Auto-approve safe ops, confirm dangerous
+/autonomy full      # Auto-approve all except critical
+/autonomy yolo      # Full auto with guardrails
+```
+
+**Customize allow/deny lists:**
+
+```bash
+/yolo allow "npm run dev"      # Add to auto-execute list
+/yolo deny "docker rm -f"      # Block a command pattern
+```
+
+**Built-in guardrails (always active, even in YOLO):**
+- Blocked paths: `.env`, `.git`, `node_modules`, `*.pem`, `*.key`, `credentials`
+- Blocked commands: `rm -rf /`, `sudo`, `git push --force origin main`, `DROP DATABASE`
+- Per-session limits on edits and commands
+- Hard cost cap ($1,000 max even with `MAX_COST` override)
+
+### Cron & Scheduling
+
+The **Cron-Agent Bridge** connects the scheduler to CodeBuddyAgent instances for recurring tasks:
+
+```bash
+buddy trigger add time:*/30 action:run-tests    # Run tests every 30 min
+buddy trigger add webhook:deploy action:notify   # Notify on deploy webhook
+```
+
+Webhook triggers use HMAC-SHA256 verification with template placeholders for flexible integration.
+
+---
+
+## AI Providers
+
+Code Buddy supports multiple AI providers with automatic failover:
+
+| Provider | Models | Context | Configuration |
+|:---------|:-------|:--------|:--------------|
+| **Grok** (xAI) | grok-4, grok-code-fast-1 | 128K | `GROK_API_KEY` |
+| **Claude** (Anthropic) | claude-sonnet-4, opus | 200K | `ANTHROPIC_API_KEY` |
+| **ChatGPT** (OpenAI) | gpt-4o, gpt-4-turbo | 128K | `OPENAI_API_KEY` |
+| **Gemini** (Google) | gemini-2.0-flash (+ vision) | 2M | `GOOGLE_API_KEY` |
+| **LM Studio** | Any local model | Varies | `--base-url http://localhost:1234/v1` |
+| **Ollama** | llama3, codellama, etc. | Varies | `--base-url http://localhost:11434/v1` |
+
+**Model failover chain** — cascading provider fallback with health tracking and cooldown periods.
+
+### Connection Profiles
+
+```bash
+# Use LM Studio (local)
+buddy --base-url http://localhost:1234/v1 --api-key lm-studio
+
+# Use Ollama (local)
+buddy --base-url http://localhost:11434/v1 --model llama3
+
+# Use a specific model
+buddy --model grok-code-fast-1
+```
+
+**Profile configuration** in `~/.codebuddy/user-settings.json`:
+
+```json
+{
+  "connection": {
+    "activeProfileId": "grok",
+    "profiles": [
+      {
+        "id": "grok",
+        "name": "Grok API (xAI)",
+        "provider": "grok",
+        "baseURL": "https://api.x.ai/v1",
+        "model": "grok-4-latest"
+      },
+      {
+        "id": "lmstudio",
+        "name": "LM Studio Local",
+        "provider": "lmstudio",
+        "baseURL": "http://localhost:1234/v1",
+        "apiKey": "lm-studio"
+      }
+    ]
+  }
+}
 ```
 
-### Smart Compaction
+**Auth profile manager** — API key rotation (round-robin/priority/random strategies), session stickiness, exponential backoff on failures.
+
+```bash
+buddy auth-profile list                   # List authentication profiles
+buddy auth-profile add <id> <provider>    # Add a profile
+buddy auth-profile remove <id>            # Remove a profile
+buddy auth-profile reset                  # Reset all cooldowns
+```
 
-Multi-stage compression:
+---
 
-1. **Stage 1**: Remove tool results older than TTL
-2. **Stage 2**: Summarize older messages
-3. **Stage 3**: Aggressive truncation if needed
+## Security & Trust
 
-### Hybrid Search
+### Tool Policy & Bash Allowlist
 
-Combined keyword + semantic search:
+Fine-grained control over what tools the agent can use:
 
 ```typescript
-const results = await hybridSearch({
-  query: "authentication flow",
-  keywordWeight: 0.3,
-  semanticWeight: 0.7,
+// Tool-level allow/deny
+const policy = new ToolPolicy({
+  allowlist: ['read_file', 'search', 'web_fetch'],
+  denylist: ['bash', 'write_file'],
+  requireConfirmation: ['delete_file'],
+});
+
+// Bash command patterns
+const bashPolicy = new BashAllowlist({
+  patterns: [/^npm (install|test|run)/, /^git (status|diff|log)/],
+  blocked: [/rm -rf/, /sudo/, /curl.*\|.*sh/],
 });
 ```
 
----
+### Security Modes
 
-## Tools
+| Mode | Description |
+|:-----|:------------|
+| `suggest` | Confirm all operations |
+| `auto-edit` | Auto-approve safe ops |
+| `full-auto` | Full autonomy (YOLO) |
 
-### Built-in Tools
+```bash
+/mode suggest    # Maximum safety
+/mode full-auto  # Full autonomy
+```
 
-| Category | Tools |
-|:---------|:------|
-| **File Operations** | `view_file`, `create_file`, `str_replace_editor`, `edit_file`, `multi_edit` |
-| **Search** | `search`, `codebase_map` |
-| **System** | `bash`, `docker`, `kubernetes` |
-| **Web** | `web_search`, `web_fetch`, `browser` |
-| **Patching** | `apply_patch` (unified diff) |
-| **Planning** | `create_todo_list`, `get_todo_list`, `update_todo_list` |
-| **Media** | `screenshot`, `audio`, `video`, `ocr`, `clipboard` |
-| **Documents** | `pdf`, `document`, `archive` |
+### Trust Folders & Agent Profiles
 
-### Web Search (5-Provider Fallback Chain)
+- **Trust folders** — directory-level tool permissions via `.codebuddy-trust.json`
+- **Agent profiles** — predefined configs: `secure` (read-only), `minimal`, `power-user`
+- **Per-model tool config** — capabilities, context window, and patch format per model family
 
-Code Buddy automatically cascades through available search providers:
+### OS Sandbox — Workspace-Write Mode
 
-| Priority | Provider | API Key Required | Features |
-|:---------|:---------|:-----------------|:---------|
-| 1 | **Brave MCP** | `BRAVE_API_KEY` + MCP enabled | Full MCP integration, richest results |
-| 2 | **Brave API** | `BRAVE_API_KEY` | Country, language, freshness filters |
-| 3 | **Perplexity** | `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` | AI-synthesized answers with citations |
-| 4 | **Serper** | `SERPER_API_KEY` | Google Search results |
-| 5 | **DuckDuckGo** | None | Free fallback (no API key needed) |
+Three sandbox tiers for native OS-level isolation (Codex-inspired):
 
-Search parameters: `country` (ISO 3166), `search_lang`, `ui_lang`, `freshness` (`pd`/`pw`/`pm`/`py` or date range), `provider` (force specific).
+| Mode | Write Access | Use Case |
+|:-----|:------------|:---------|
+| `read-only` | None | Untrusted analysis tasks |
+| `workspace-write` | Git workspace root only | Normal development (default) |
+| `danger-full-access` | Unrestricted | Deployment/release scripts |
 
-### MCP Predefined Servers
+`.git`, `.codebuddy`, `.ssh`, `.gnupg`, `.aws` are **always read-only** regardless of mode.
 
-Four MCP servers are pre-configured (disabled by default):
+```typescript
+const sandbox = await createSandboxForMode('workspace-write', '/my/project');
+await sandbox.exec('npm', ['test']);
+```
+
+### Exec Policy — Prefix Rules
+
+Codex-inspired command authorization with token-array prefix matching (safer than regex — bypasses quoting/encoding tricks):
 
 ```bash
-buddy mcp add brave-search    # Brave Web Search (needs BRAVE_API_KEY)
-buddy mcp add playwright      # Browser automation (no key needed)
-buddy mcp add exa-search      # Exa neural search (needs EXA_API_KEY)
-buddy mcp add icm             # Infinite Context Memory (needs `cargo install icm`)
-buddy mcp list                # Show all configured servers
+buddy execpolicy check "git push --force"          # evaluate a shell string
+buddy execpolicy check-argv git push --force       # token-array (prefix rules first)
+buddy execpolicy add-prefix git push --action deny # block git push with longest-match
+buddy execpolicy dashboard                         # full policy overview
 ```
 
-### RAG-Based Tool Selection
+### SSRF Guard
+
+Comprehensive Server-Side Request Forgery protection on all outbound HTTP calls:
+- Blocks RFC-1918 private ranges + loopback + link-local
+- Blocks IPv4 bypass vectors: octal (`0177.0.0.1`), hex (`0x7f000001`), short form (`127.1`)
+- Blocks IPv6 transition addresses: NAT64 (`64:ff9b::/96`), 6to4, Teredo, IPv4-mapped (`::ffff:127.0.0.1`)
+- Async DNS resolution check before every fetch
+
+### Docker Sandbox
 
-Tools are selected based on query relevance:
+Containerized command execution for untrusted operations:
 
 ```typescript
-// Query: "what's the weather in Paris?"
-// Selected tools: web_search, web_fetch
-// Not selected: bash, edit_file, etc.
+const sandbox = new DockerSandbox({
+  image: 'codebuddy/sandbox:latest',
+  memoryLimit: '512m',
+  networkMode: 'none',
+  timeout: 30000,
+});
 ```
 
+**Auto-sandbox router** automatically routes dangerous commands (npm, pip, cargo, make) to Docker when available.
+
+### Safety Rails
+
+| Rail | Description |
+|:-----|:------------|
+| **Diff-First Mode** | All code changes are previewed before applying. Users see file summaries, line counts, and can view the full unified diff. |
+| **Plan-First Mode** | Multi-step tasks show the execution plan for approval before any changes are made. |
+| **Scoped Permissions** | Users get only the access they need: `read-only` → `write-patch` → `run-tests` → `deploy`. |
+| **Audit Trail** | Every tool execution, confirmation, and security decision is logged. |
+| **Secret Handles** | API tokens and credentials are referenced by handle name only — actual values are resolved from env vars at runtime, never exposed to the LLM context. |
+| **2-Step Confirmation** | Risky operations (rollback, deploy) require double confirmation with a 2-minute timeout window. |
+| **Timed YOLO** | `/yolo` grants temporary full access that auto-revokes after the specified duration. |
+| **DM Pairing** | Unknown users must be approved before they can interact with the bot. |
+
 ---
 
-## API Server
+## Architecture
+
+### Facade Architecture
+
+```
+CodeBuddyAgent
+    │
+    ├── AgentContextFacade      # Context window and memory management
+    │       - Token counting, compression, memory retrieval
+    │
+    ├── SessionFacade           # Session persistence and checkpoints
+    │       - Save/load, checkpoint creation, rewind
+    │
+    ├── ModelRoutingFacade      # Model routing and cost tracking
+    │       - Provider selection, cost calculation
+    │
+    ├── InfrastructureFacade    # MCP, sandbox, hooks, plugins
+    │       - Hook execution, plugin loading
+    │
+    └── MessageHistoryManager   # Chat and LLM message history
+```
+
+### Autonomy Layer
+
+```
+CodeBuddyAgent
+    │
+    ├── TaskPlanner             # DAG decomposition of complex requests
+    │       - needsPlanning() heuristic
+    │       - createPlan() → TaskGraph → parallel execution
+    │
+    ├── SupervisorAgent         # Multi-agent orchestration
+    │       - Sequential, parallel, race, all strategies
+    │       - SharedContext with optimistic locking
+    │
+    ├── SelfHealing             # Automatic error recovery
+    │       - Pattern recognition (6 built-in patterns)
+    │       - Retry with exponential backoff
+    │
+    ├── ScreenObserver          # Environment monitoring
+    │       - Periodic screenshots with perceptual diff
+    │       - Event triggers (file_change, screen_change, time, webhook)
+    │
+    ├── ProactiveAgent          # Agent-initiated communication
+    │       - Push notifications with priority levels
+    │       - Rate limiting and quiet hours
+    │
+    └── DaemonManager           # Background process lifecycle
+            - PID file management, auto-restart
+            - Service registry, health monitoring
+```
+
+### Core Flow
+
+```
+User Input → ChatInterface (Ink/React) → CodeBuddyAgent → AI Provider
+                                              │
+                                         Tool Calls (max 50/400 rounds)
+                                              │
+                                      Tool Execution + Confirmation
+                                              │
+                                        Results back to API (loop)
+```
+
+---
 
-REST API with WebSocket support:
+## API Server & Integrations
 
-### Starting the Server
+### REST API
 
 ```bash
 buddy server --port 3000
 ```
 
-### Endpoints
-
 | Endpoint | Method | Description |
 |:---------|:-------|:------------|
 | `/api/health` | GET | Health check |
@@ -732,9 +1001,7 @@ buddy server --port 3000
 | `/api/cron/jobs/{id}/trigger` | POST | Trigger a cron job |
 | `/api/notifications/preferences` | GET/POST | Notification settings |
 | `/api/heartbeat/status` | GET | Heartbeat engine status |
-| `/api/heartbeat/start` | POST | Start heartbeat |
-| `/api/heartbeat/stop` | POST | Stop heartbeat |
-| `/api/heartbeat/tick` | POST | Trigger a single tick |
+| `/api/heartbeat/start\|stop\|tick` | POST | Heartbeat control |
 | `/api/hub/search?q=...` | GET | Search skills marketplace |
 | `/api/hub/installed` | GET | List installed hub skills |
 | `/api/hub/install` | POST | Install a skill |
@@ -742,34 +1009,173 @@ buddy server --port 3000
 | `/api/identity` | GET | List loaded identity files |
 | `/api/identity/prompt` | GET | Combined identity prompt |
 | `/api/identity/{name}` | PUT | Update an identity file |
-| `/api/groups/status` | GET | Group security status |
-| `/api/groups/list` | GET | List configured groups |
+| `/api/groups/status\|list` | GET | Group security status/config |
 | `/api/groups/block` | POST | Block a user globally |
 | `/api/groups/block/{userId}` | DELETE | Unblock a user |
 | `/api/auth-profiles` | GET/POST/DELETE | Auth profile CRUD |
 | `/api/auth-profiles/reset` | POST | Reset all cooldowns |
 
-### WebSocket Events
+### WebSocket Events
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/ws');
+
+// Authenticate
+ws.send(JSON.stringify({
+  type: 'authenticate',
+  payload: { token: 'jwt-token' }
+}));
+
+// Stream chat
+ws.send(JSON.stringify({
+  type: 'chat_stream',
+  payload: { messages: [{ role: 'user', content: 'Hello' }] }
+}));
+```
+
+### MCP Servers
+
+Four MCP servers are pre-configured (disabled by default):
+
+```bash
+buddy mcp add brave-search    # Brave Web Search (needs BRAVE_API_KEY)
+buddy mcp add playwright      # Browser automation (no key needed)
+buddy mcp add exa-search      # Exa neural search (needs EXA_API_KEY)
+buddy mcp add icm             # Infinite Context Memory (needs `cargo install icm`)
+buddy mcp list                # Show all configured servers
+```
+
+### Plugin System
+
+Plugins extend Code Buddy with custom tools, commands, and providers:
+
+```
+~/.codebuddy/plugins/
+  my-plugin/
+    manifest.json
+    index.js
+```
+
+Plugin types: **Tool**, **Provider** (LLM/embedding/search), **Command**, **Hook**
+
+```typescript
+const plugin: Plugin = {
+  async activate(context: PluginContext) {
+    context.registerTool({
+      name: 'my_tool',
+      description: 'Custom tool',
+      execute: async (args) => {
+        return { success: true, output: 'Done!' };
+      }
+    });
+
+    context.registerProvider({
+      id: 'my-llm',
+      type: 'llm',
+      async chat(messages) { return 'response'; }
+    });
+  }
+};
+```
+
+### Extensions
+
+Manifest-based extension system with lifecycle hooks and config schema. Extensions live in `.codebuddy/extensions/`.
+
+### Copilot Proxy
+
+IDE-compatible completions backend — serves `/v1/completions` with bearer auth, per-IP rate limiting, and token clamping.
+
+### External Tools (RTK & ICM)
+
+| Tool | Install | Purpose |
+|:-----|:--------|:--------|
+| **RTK** | `cargo install --git https://github.com/rtk-ai/rtk` | CLI proxy that wraps commands to reduce LLM token usage 60-90% |
+| **ICM** | `cargo install --git https://github.com/rtk-ai/icm` | MCP server for persistent cross-session memory |
+
+RTK is automatically integrated via a before-hook — supported bash commands are prefixed with `rtk` transparently. Configure in `.codebuddy/config.toml` under `[integrations]`.
+
+---
+
+## CLI Reference
+
+### Global Options
+
+| Flag | Short | Description | Default |
+|:-----|:------|:------------|:--------|
+| `--version` | `-V` | Show version number | - |
+| `--directory <dir>` | `-d` | Set working directory | `.` |
+| `--api-key <key>` | `-k` | API key (or `GROK_API_KEY` env) | - |
+| `--base-url <url>` | `-u` | API base URL (or `GROK_BASE_URL` env) | - |
+| `--model <model>` | `-m` | AI model to use (or `GROK_MODEL` env) | auto-detect |
+| `--prompt <prompt>` | `-p` | Single prompt, headless mode | - |
+| `--browser` | `-b` | Launch browser UI instead of terminal | `false` |
+| `--max-tool-rounds <n>` | | Max tool execution rounds | `400` |
+| `--security-mode <mode>` | `-s` | `suggest`, `auto-edit`, or `full-auto` | `suggest` |
+| `--output-format <fmt>` | `-o` | Headless output: `json`, `stream-json`, `text`, `markdown` | `json` |
+| `--context <patterns>` | `-c` | Glob patterns to load into context | - |
+
+### Session & Cost
+
+| Flag | Description | Default |
+|:-----|:------------|:--------|
+| `--continue` | Resume the most recent saved session | - |
+| `--resume <id>` | Resume a specific session (supports partial ID matching) | - |
+| `--max-price <dollars>` | Maximum cost in dollars before stopping | `10.0` |
+| `--no-cache` | Disable response caching | - |
+
+### Autonomy & Permissions
+
+| Flag | Description | Default |
+|:-----|:------------|:--------|
+| `--auto-approve` | Automatically approve all tool executions | `false` |
+| `--dangerously-skip-permissions` | Bypass all permission checks (trusted containers only) | `false` |
+| `--no-self-heal` | Disable self-healing auto-correction | - |
+| `--allow-outside` | Allow file operations outside workspace directory | `false` |
+
+### Tool Control
+
+| Flag | Description | Example |
+|:-----|:------------|:--------|
+| `--force-tools` | Force-enable function calling for local models | - |
+| `--probe-tools` | Auto-detect tool support at startup | - |
+| `--enabled-tools <patterns>` | Only enable matching tools (glob, comma-separated) | `bash,*file*,search` |
+| `--disabled-tools <patterns>` | Disable matching tools (glob, comma-separated) | `bash,web_*` |
+| `--allowed-tools <patterns>` | Alias for `--enabled-tools` (Claude Code compat) | - |
+
+### Agent & Prompt Configuration
 
-```javascript
-const ws = new WebSocket('ws://localhost:3000/ws');
+| Flag | Description | Default |
+|:-----|:------------|:--------|
+| `--system-prompt <id>` | System prompt: `default`, `minimal`, `secure`, `code-reviewer`, `architect` (or custom from `~/.codebuddy/prompts/`) | `default` |
+| `--list-prompts` | List available system prompts and exit | - |
+| `--agent <name>` | Use a custom agent from `~/.codebuddy/agents/` | - |
+| `--list-agents` | List available custom agents and exit | - |
 
-// Authenticate
-ws.send(JSON.stringify({
-  type: 'authenticate',
-  payload: { token: 'jwt-token' }
-}));
+### Display & Debugging
 
-// Stream chat
-ws.send(JSON.stringify({
-  type: 'chat_stream',
-  payload: { messages: [{ role: 'user', content: 'Hello' }] }
-}));
-```
+| Flag | Description |
+|:-----|:------------|
+| `--plain` | Minimal formatting (plain text output) |
+| `--no-color` | Disable colored output |
+| `--no-emoji` | Disable emoji in output |
+| `--vim` | Enable Vim keybindings for input |
+| `--mcp-debug` | Enable MCP protocol debugging output |
+
+### Setup & Init
+
+| Flag | Description |
+|:-----|:------------|
+| `--init` | Initialize `.codebuddy/` directory with templates |
+| `--dry-run` | Preview changes without applying (simulation mode) |
+| `--setup` | Run interactive API key setup wizard |
+| `--list-models` | List available models from the API and exit |
 
 ---
 
-## Slash Commands
+## Commands
+
+### Slash Commands (In-Chat)
 
 | Command | Description |
 |:--------|:------------|
@@ -784,231 +1190,136 @@ ws.send(JSON.stringify({
 | `/memory` | Memory management |
 | `/hooks list` | List lifecycle hooks |
 | `/plugin list` | List plugins |
+| `/speak <text>` | Speak text with current TTS provider |
+| `/tts on\|off\|auto` | TTS control |
+| `/yolo on\|off\|safe\|status` | YOLO mode control |
+| `/autonomy suggest\|confirm\|auto\|full\|yolo` | Autonomy level |
 
-### Daemon Commands
-
-```bash
-buddy daemon start [--detach]  # Start background daemon
-buddy daemon stop              # Stop daemon
-buddy daemon restart           # Restart daemon
-buddy daemon status            # Show daemon status and services
-buddy daemon logs [--lines N]  # View daemon logs
-```
-
-### Trigger Commands
-
-```bash
-buddy trigger list             # List all event triggers
-buddy trigger add <spec>       # Add a trigger (format: type:condition action:target)
-buddy trigger remove <id>      # Remove a trigger
-```
-
-### Webhook Commands
+### CLI Subcommands
 
 ```bash
-buddy webhook list                          # List registered webhooks
-buddy webhook add <name> <message> [opts]   # Register a new webhook
-buddy webhook remove <id>                   # Remove a webhook
-```
+# Daemon
+buddy daemon start|stop|restart|status|logs
 
-### Hub Commands (Skills Marketplace)
-
-```bash
-buddy hub search <query>       # Search for skills
-buddy hub install <name>       # Install a skill from the hub
-buddy hub uninstall <name>     # Uninstall a skill
-buddy hub update [name]        # Update all or a specific skill
-buddy hub list                 # List installed skills
-buddy hub info <name>          # Show details about a skill
-buddy hub publish <path>       # Publish a skill to the hub
-buddy hub sync                 # Sync installed skills with lockfile
-```
+# Triggers
+buddy trigger list|add|remove
 
-### Heartbeat Commands
+# Webhooks
+buddy webhook list|add|remove
 
-```bash
-buddy heartbeat start [opts]   # Start the heartbeat engine
-buddy heartbeat stop           # Stop the heartbeat engine
-buddy heartbeat status         # Show heartbeat status
-buddy heartbeat tick           # Manually trigger a single tick
-```
+# Skills Hub
+buddy hub search|install|uninstall|update|list|info|publish|sync
 
-### Identity Commands
+# Heartbeat
+buddy heartbeat start|stop|status|tick
 
-```bash
-buddy identity show            # Show loaded identity files (SOUL.md, USER.md, etc.)
-buddy identity get <name>      # Show content of a specific identity file
-buddy identity set <name> <c>  # Set content of an identity file
-buddy identity prompt          # Show the combined identity prompt injection
-```
+# Identity
+buddy identity show|get|set|prompt
 
-### Group Security Commands
+# Groups
+buddy groups status|list|block|unblock
 
-```bash
-buddy groups status            # Show group security status
-buddy groups list              # List configured groups
-buddy groups block <userId>    # Add a user to the global blocklist
-buddy groups unblock <userId>  # Remove a user from the blocklist
-```
+# Auth Profiles
+buddy auth-profile list|add|remove|reset
 
-### Auth Profile Commands
+# Devices
+buddy device list|pair|remove|snap|screenshot|record|run
 
-```bash
-buddy auth-profile list                   # List authentication profiles
-buddy auth-profile add <id> <provider>    # Add a profile (API key rotation)
-buddy auth-profile remove <id>            # Remove a profile
-buddy auth-profile reset                  # Reset all cooldowns
-```
+# Config
+buddy config show|validate|get
 
-### Device Commands
+# Security
+buddy security-audit [--deep] [--fix] [--json]
 
-```bash
-buddy device list                         # List paired devices
-buddy device pair --id <id> --name <name> --transport <ssh|adb|local>  # Pair a device
-buddy device remove <id>                  # Remove a paired device
-buddy device snap <id> [-o output.png]    # Take a screenshot on device
-buddy device screenshot <id> [-o out.png] # Alias for snap
-buddy device record <id> [-d 10] [-o out] # Record screen (duration in seconds)
-buddy device run <id> -- <command>        # Run a command on device
-```
+# Voice
+buddy speak [text] [--voice <name>] [--list-voices] [--speed <n>] [--format <fmt>]
 
-### Config Commands
+# Knowledge Base
+buddy knowledge list|show|search|add|remove|context
 
-```bash
-buddy config show [--json]     # Show all environment variables and values
-buddy config validate          # Validate current environment configuration
-buddy config get <name>        # Show value and definition of a variable
-```
+# DM Pairing
+buddy pairing status|list|pending|approve <code>|add <id>|revoke <id>
 
-### Security Audit
+# Wide Research
+buddy research "<topic>" [--workers N] [--rounds N] [--output file.md]
 
-```bash
-buddy security-audit           # Run security audit of your environment
-buddy security-audit --deep    # Deep scan (git history, npm audit)
-buddy security-audit --fix     # Auto-fix file permission issues
-buddy security-audit --json    # Output as JSON
-```
+# Task List (todo.md attention bias — injected at end of every agent turn)
+buddy todo list                     # Show all items
+buddy todo add "task description" [-p high|medium|low]
+buddy todo done <id>                # Mark completed
+buddy todo update <id> [-s in_progress] [-t "new text"]
+buddy todo remove <id>              # Delete item
+buddy todo clear-done               # Remove all completed
+buddy todo context                  # Preview the block injected into the agent
 
-### Voice & TTS Commands
+# Lessons (self-improvement loop — injected before every agent turn)
+buddy lessons list [--category PATTERN|RULE|CONTEXT|INSIGHT]
+buddy lessons add "what went wrong → correct approach" --category PATTERN
+buddy lessons search "tsc"                 # Find relevant lessons before a task
+buddy lessons clear [--category RULE] --yes
+buddy lessons context                      # Preview the <lessons_context> block
 
-```bash
-buddy speak "Bonjour, je suis Code Buddy"   # Synthesize and play speech
-buddy speak --voice af_bella "Hello world"   # Use a specific voice
-buddy speak --list-voices                    # List available voices
-buddy speak --speed 1.5 "Fast speech"        # Adjust speed (0.25-4.0)
-buddy speak --format mp3 "Hello"             # Output format (wav, mp3)
-buddy speak --url http://host:8000 "Hello"   # Custom AudioReader URL
+# Setup
+buddy onboard          # Interactive setup wizard
+buddy doctor           # Environment diagnostics
 ```
 
-**In-chat voice commands:**
-
-| Command | Description |
-|:--------|:------------|
-| `/speak <text>` | Speak text with current TTS provider |
-| `/tts on\|off` | Enable/disable TTS |
-| `/tts auto` | Auto-speak all agent responses |
-| `/tts provider audioreader` | Switch to AudioReader (Kokoro-82M, local, free) |
-| `/tts voice ff_siwis` | Set voice (e.g., `ff_siwis` FR, `af_bella` EN) |
-
-**Supported TTS providers:** Edge TTS, espeak, macOS `say`, Piper, OpenAI, ElevenLabs, AudioReader (Kokoro-82M)
-
-**Infinite voice conversation:** Enable `continuousListening` + `autoSpeak` with AudioReader for a hands-free loop: listen → STT → agent → TTS → listen.
-
 ---
 
-## Plugin System
+## Configuration
 
-### Plugin Structure
+### Environment Variables
 
-```
-~/.codebuddy/plugins/
-  my-plugin/
-    manifest.json
-    index.js
-```
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `GROK_API_KEY` | xAI API key | Required |
+| `ANTHROPIC_API_KEY` | Anthropic API key | - |
+| `OPENAI_API_KEY` | OpenAI API key | - |
+| `GOOGLE_API_KEY` | Google AI API key | - |
+| `SERPER_API_KEY` | Web search API key | - |
+| `GROK_BASE_URL` | Custom API endpoint | - |
+| `GROK_MODEL` | Default model | - |
+| `BRAVE_API_KEY` | Brave Search API key | - |
+| `EXA_API_KEY` | Exa neural search API key | - |
+| `PERPLEXITY_API_KEY` | Perplexity AI search key (`pplx-...`) | - |
+| `OPENROUTER_API_KEY` | OpenRouter key for Perplexity (`sk-or-...`) | - |
+| `PERPLEXITY_MODEL` | Perplexity model | `perplexity/sonar-pro` |
+| `PICOVOICE_ACCESS_KEY` | Porcupine wake word detection | - |
+| `CACHE_TRACE` | Debug prompt construction stages | `false` |
+| `YOLO_MODE` | Full autonomy | `false` |
+| `MAX_COST` | Cost limit ($) | `10` |
+| `JWT_SECRET` | API server auth | Required in prod |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) | - |
+| `DISCORD_TOKEN` | Discord bot token | - |
+| `SLACK_BOT_TOKEN` | Slack bot token | - |
 
-### Plugin Types
+**Optional Rust tools:**
 
-- **Tool Plugins**: Add custom tools
-- **Provider Plugins**: Add LLM/embedding/search providers
-- **Command Plugins**: Add slash commands
-- **Hook Plugins**: Add lifecycle hooks
+| Tool | Install | Purpose |
+|:-----|:--------|:--------|
+| **RTK** | `cargo install --git https://github.com/rtk-ai/rtk` | CLI proxy that wraps commands to reduce LLM token usage 60-90% |
+| **ICM** | `cargo install --git https://github.com/rtk-ai/icm` | MCP server for persistent cross-session memory |
 
-### Example Plugin
+### Project Settings
 
-```typescript
-const plugin: Plugin = {
-  async activate(context: PluginContext) {
-    context.registerTool({
-      name: 'my_tool',
-      description: 'Custom tool',
-      execute: async (args) => {
-        return { success: true, output: 'Done!' };
-      }
-    });
+Create `.codebuddy/settings.json`:
 
-    context.registerProvider({
-      id: 'my-llm',
-      type: 'llm',
-      async chat(messages) { return 'response'; }
-    });
+```json
+{
+  "systemPrompt": "You are working on a TypeScript project.",
+  "tools": {
+    "enabled": ["read_file", "search", "bash"],
+    "disabled": ["web_search"]
+  },
+  "security": {
+    "mode": "auto-edit",
+    "bashAllowlist": ["npm *", "git *"]
   }
-};
+}
 ```
 
 ---
 
-## Bundled Skills (40)
-
-Code Buddy includes 40 built-in SKILL.md files that provide domain-specific knowledge, best practices, and MCP server integration for popular software. Skills are loaded contextually when relevant to your project.
-
-| Category | Skill | Description |
-|----------|-------|-------------|
-| **PR Workflow** | `review-pr` | Code review checklist, inline comments, approval criteria |
-| | `prepare-pr` | Branch naming, commit cleanup, PR description template |
-| | `merge-pr` | Merge strategies, conflict resolution, post-merge cleanup |
-| **Dev Tools** | `github` | Issues, releases, Actions workflows, gh CLI |
-| | `gitlab` | GitLab API, glab CLI, CI/CD pipelines, merge requests |
-| | `session-logs` | Export/search conversation history and session metadata |
-| | `model-usage` | Token tracking, cost analysis, provider comparison |
-| | `tmux-sessions` | Terminal multiplexing, pane layouts, session management |
-| | `healthcheck` | Service monitoring, endpoint checks, alerting |
-| **Project** | `project-best-practices` | Project scaffolding, structure, linting, testing conventions |
-| | `csharp-avalonia` | Cross-platform desktop/mobile with C# and Avalonia UI |
-| | `coding-agent` | Autonomous multi-step coding with planning and validation |
-| | `skill-creator` | Author new SKILL.md files with YAML frontmatter |
-| **Creative & 3D** | `blender` | Python bpy scripting, CLI rendering, Geometry Nodes |
-| | `unreal-engine` | Remote Control API, Python editor scripting, Movie Render Queue |
-| | `davinci-resolve` | DaVinciResolveScript Python API, color grading, render queue |
-| | `ableton-live` | OSC protocol, MIDI Remote Scripts, Max for Live |
-| **Design** | `figma` | REST API, Plugin API, design tokens extraction |
-| | `gimp` | Python-Fu / Script-Fu scripting, batch image processing |
-| | `inkscape` | Extensions API, CLI export, SVG manipulation |
-| **DevOps & Infra** | `kubernetes` | kubectl, Helm, ArgoCD GitOps |
-| | `terraform-ansible` | Terraform IaC + Ansible configuration management |
-| | `grafana-prometheus` | Grafana HTTP API, PromQL, alerting pipelines |
-| | `jenkins-ci` | Jenkins API, Groovy pipelines, shared libraries |
-| **Workflow & Data** | `n8n` | REST API, webhook triggers, workflow automation |
-| | `databases` | PostgreSQL, MongoDB, Redis CLI and automation |
-| | `game-engines` | Unity C# + Godot GDScript, builds, scene management |
-| **Utilities** | `summarize` | Text/file/URL summarization with configurable length |
-| | `weather` | Weather lookups via wttr.in and OpenWeatherMap |
-| **Media** | `image-gen` | Image generation via DALL-E, Stable Diffusion, Midjourney |
-| | `whisper-transcribe` | Audio/video transcription with OpenAI Whisper |
-| | `pdf-tools` | PDF creation, merging, text extraction, conversion |
-| | `screenshot` | Screen capture, annotation, OCR text extraction |
-| | `video-tools` | FFmpeg video editing, conversion, thumbnails, GIFs |
-| | `gif-search` | GIF search via Giphy and Tenor APIs |
-| **Communication** | `email-tools` | Email send/read via himalaya CLI and SMTP |
-| | `notion` | Notion API for pages, databases, search, content blocks |
-| | `blog-watcher` | RSS/Atom feed monitoring, web page change detection |
-| **Smart Home** | `spotify` | Spotify playback control via spotify_player and Web API |
-| | `smart-home` | Philips Hue and Home Assistant control |
-
-Each skill includes **Direct Control** (CLI/API/scripting commands), **MCP Server Integration** (config for `.codebuddy/mcp.json`), and **Common Workflows** (step-by-step recipes). Skills are stored in `.codebuddy/skills/bundled/` and can be extended with managed or workspace skills via the Skills Registry.
-
----
-
 ## Development
 
 ```bash
@@ -1048,90 +1359,88 @@ npm run build
 
 ---
 
-## Configuration
+## Research & Inspiration
 
-### Environment Variables
+Code Buddy implements techniques from academic research and draws architectural inspiration from leading open-source projects.
 
-| Variable | Description | Default |
-|:---------|:------------|:--------|
-| `GROK_API_KEY` | xAI API key | Required |
-| `ANTHROPIC_API_KEY` | Anthropic API key | - |
-| `OPENAI_API_KEY` | OpenAI API key | - |
-| `GOOGLE_API_KEY` | Google AI API key | - |
-| `SERPER_API_KEY` | Web search API key | - |
-| `GROK_BASE_URL` | Custom API endpoint | - |
-| `GROK_MODEL` | Default model | - |
-| `BRAVE_API_KEY` | Brave Search API key | - |
-| `EXA_API_KEY` | Exa neural search API key | - |
-| `PERPLEXITY_API_KEY` | Perplexity AI search key (`pplx-...`) | - |
-| `OPENROUTER_API_KEY` | OpenRouter key for Perplexity (`sk-or-...`) | - |
-| `PERPLEXITY_MODEL` | Perplexity model | `perplexity/sonar-pro` |
-| `PICOVOICE_ACCESS_KEY` | Porcupine wake word detection | - |
-| `CACHE_TRACE` | Debug prompt construction stages | `false` |
-| `YOLO_MODE` | Full autonomy | `false` |
-| `MAX_COST` | Cost limit ($) | `10` |
-| `JWT_SECRET` | API server auth | Required in prod |
+### Scientific Papers
 
-**Optional Rust tools (install via `cargo install`):**
+**Reasoning & Planning:**
 
-| Tool | Install | Purpose |
-|:-----|:--------|:--------|
-| **RTK** | `cargo install rtk` | Compresses bash output 60-90%, reducing token usage |
-| **ICM** | `cargo install icm` | MCP server for persistent cross-session memory |
+| Paper | Reference | Implementation |
+|:------|:----------|:---------------|
+| Tree of Thoughts | Yao et al., 2023 — [arXiv:2305.10601](https://arxiv.org/abs/2305.10601) | `src/agent/reasoning/tree-of-thought.ts` |
+| RethinkMCTS | Zhang et al., 2024 — [arXiv:2409.09584](https://arxiv.org/abs/2409.09584) | `src/agent/reasoning/mcts.ts` |
+| TALE (Token-Budget-Aware Reasoning) | [arXiv:2412.18547](https://arxiv.org/abs/2412.18547) | `src/agent/token-budget-reasoning.ts` — 68.9% token reduction |
+| FrugalGPT | Stanford, 2023 — [arXiv:2305.05176](https://arxiv.org/abs/2305.05176) | `src/optimization/model-routing.ts` — 30-70% cost reduction |
+| LLMCompiler | [arXiv:2312.04511](https://arxiv.org/abs/2312.04511) | `src/optimization/parallel-executor.ts` — 2.5-4.6x speedup |
 
-### Project Settings
+**Program Repair:**
 
-Create `.codebuddy/settings.json`:
+| Paper | Reference | Implementation |
+|:------|:----------|:---------------|
+| ChatRepair | Xia et al., ISSTA 2024 — [arXiv:2403.12538](https://arxiv.org/abs/2403.12538) | `src/agent/repair/iterative-repair.ts` |
+| ITER | [arXiv:2403.00418](https://arxiv.org/abs/2403.00418) | `src/agent/repair/repair-templates.ts` — iterative template repair |
+| RepairAgent | ICSE 2024 | `src/agent/repair/repair-engine.ts` — autonomous LLM-based repair |
+| AgentCoder | Huang et al., 2023 | `src/agent/multi-agent/multi-agent-system.ts` — hierarchical multi-agent code generation |
 
-```json
-{
-  "systemPrompt": "You are working on a TypeScript project.",
-  "tools": {
-    "enabled": ["read_file", "search", "bash"],
-    "disabled": ["web_search"]
-  },
-  "security": {
-    "mode": "auto-edit",
-    "bashAllowlist": ["npm *", "git *"]
-  }
-}
-```
+**RAG & Context Management:**
 
----
+| Paper | Reference | Implementation |
+|:------|:----------|:---------------|
+| CodeRAG | [arXiv:2509.16112](https://arxiv.org/abs/2509.16112) | `src/context/multi-path-retrieval.ts`, `src/context/dependency-aware-rag.ts` |
+| RAG-MCP | [arXiv:2505.03275](https://arxiv.org/abs/2505.03275) | `src/tools/tool-selector.ts` |
+| ToolLLM | ICLR'24 — [arXiv:2307.16789](https://arxiv.org/abs/2307.16789) | `src/agent/execution/tool-selection-strategy.ts` |
+| Comprehensive RAG Survey | [arXiv:2506.00054](https://arxiv.org/abs/2506.00054) | `src/context/codebase-rag/codebase-rag.ts` |
+| Recurrent Context Compression | [arXiv:2406.06110](https://arxiv.org/abs/2406.06110) | `src/context/context-manager-v2.ts` |
+
+**Observation & Optimization:**
+
+| Paper | Reference | Implementation |
+|:------|:----------|:---------------|
+| JetBrains Context Management | JetBrains Research, 2024 | `src/context/observation-masking.ts` — -7% cost, +2.6% success |
+| Complexity Trap | [arXiv:2508.21433](https://arxiv.org/abs/2508.21433) | `src/context/observation-masking.ts` |
+| Less-is-More (Tool Filtering) | arXiv, 2024 | `src/optimization/tool-filtering.ts` — 70% execution time reduction |
+| The Prompt Report | [arXiv:2406.06608](https://arxiv.org/abs/2406.06608) | `src/prompts/system-base.ts` |
+
+**Testing & Memory:**
+
+| Paper | Reference | Implementation |
+|:------|:----------|:---------------|
+| TDD + LLM | ICSE 2024 | `src/testing/tdd-mode.ts` — TDD improves Pass@1 by 45.97% |
+| MemGPT | UC Berkeley, 2023 | `src/memory/prospective-memory.ts` — stateful AI agents |
 
-## Roadmap
-
-### Planned Features
-
-| Feature | Priority | Status |
-|:--------|:---------|:-------|
-| Daemon Mode (background agent) | HIGH | ✅ Done |
-| Task Planner (DAG decomposition) | HIGH | ✅ Done |
-| Screen Observer & Triggers | HIGH | ✅ Done |
-| Proactive Agent (push notifications) | HIGH | ✅ Done |
-| Multi-Agent Orchestrator | HIGH | ✅ Done |
-| Self-Healing & Checkpoint Rollback | HIGH | ✅ Done |
-| Canvas A2UI Visual Workspace | HIGH | ✅ Done |
-| ClawHub Skills Registry | MEDIUM | ✅ Done |
-| Web Search 5-Provider Chain | HIGH | ✅ Done |
-| Apply Patch & Bash Parser | HIGH | ✅ Done |
-| Per-Model Tool Config | MEDIUM | ✅ Done |
-| Voice Wake Word Detection | MEDIUM | ✅ Done |
-| TTS Providers (OpenAI, ElevenLabs, AudioReader) | MEDIUM | ✅ Done |
-| Code Generation Security (Phase 7) | HIGH | ✅ Done |
-| Auto-Sandbox Router | HIGH | ✅ Done |
-| Semantic Output Truncation | MEDIUM | ✅ Done |
-| Gateway WebSocket Control Plane | HIGH | 🔲 Planned |
-| OAuth Authentication | MEDIUM | 🔲 Planned |
-| Companion Apps (iOS, Android, macOS) | LOW | 🔲 Planned |
-| Tailscale Integration | LOW | 🔲 Planned |
+**Fault Localization:** Ochiai, DStar, and Tarantula (Jones et al., 2002) spectrum-based techniques in `src/agent/repair/fault-localization.ts`.
+
+### Inspiration Projects
+
+Code Buddy's architecture draws from these open-source projects:
+
+| Project | Inspiration | Key Files |
+|:--------|:------------|:----------|
+| **[OpenClaw](https://github.com/openclaw/openclaw)** | Multi-channel messaging, DM pairing, lane queue concurrency, memory lifecycle, tool policy, skills system, heartbeat, identity system, group security, hub marketplace | 40+ files across `src/channels/`, `src/concurrency/`, `src/memory/`, `src/security/`, `src/skills/` |
+| **[OpenAI Codex CLI](https://github.com/openai/codex)** | Apply-patch unified diff, head/tail truncation, per-model tool config, turn diff tracker, security modes, OS sandbox workspace-write tiers, shell-free exec, SSRF guard, exec policy prefix rules, shell env policy, named config profiles, tool prefix naming convention, stable JSON serialization, session fork/rollout unification | `src/tools/apply-patch.ts`, `src/sandbox/os-sandbox.ts`, `src/security/ssrf-guard.ts`, `src/sandbox/execpolicy.ts`, `src/tools/registry/tool-aliases.ts`, `src/utils/stable-json.ts`, `src/observability/run-store.ts` |
+| **[Claude Code](https://github.com/anthropics/claude-code)** | Hook system, slash commands, MCP config, extended thinking, parallel subagents, headless output, Anthropic prompt cache breakpoints | `src/hooks/`, `src/commands/slash-commands.ts`, `src/mcp/config.ts`, `src/optimization/cache-breakpoints.ts` |
+| **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Persistent checkpoints, context files, compress command, shell prefix, multimodal input | `src/checkpoints/`, `src/context/context-files.ts`, `src/input/multimodal-input.ts` |
+| **[Aider](https://github.com/paul-gauthier/aider)** | Repository map, voice input, unified diff editor, watch mode (IDE comments) | `src/context/repository-map.ts`, `src/tools/voice-input.ts`, `src/commands/watch-mode.ts` |
+| **[Cursor](https://www.cursor.com/)** | `.cursorrules` config, parallel agent system, sandboxed terminals, embedded browser | `src/config/codebuddyrules.ts`, `src/agent/parallel/`, `src/browser/embedded-browser.ts` |
+| **[Mistral Vibe](https://github.com/mistralai/mistral-vibe)** | External markdown prompts, TOML config, tool permission system, fuzzy match, update notifier | `src/prompts/`, `src/config/toml-config.ts`, `src/utils/fuzzy-match.ts` |
+| **[Conductor](https://github.com/conductor-is/conductor)** | Spec-driven development, track system | `src/tracks/` |
+| **[RTK](https://github.com/rtk-ai/rtk)** | Command proxy for 60-90% token reduction | `src/utils/rtk-compressor.ts` |
+| **[ICM](https://github.com/rtk-ai/icm)** | Persistent cross-session memory via MCP | `src/memory/icm-bridge.ts` |
+| **[Manus AI](https://manus.im)** | Wide Research (parallel sub-agent research workers), Knowledge Base injection, todo.md attention bias, restorable context compression, pre-compaction NO_REPLY flush, inline web-search citations, observation variator (anti-repetition), structured prompt variation, tool result compaction guard, disk-backed tool results, response prefill modes (tool_choice control), WebSearchMode + domain policy, message queue debounce/cap/overflow | `src/agent/wide-research.ts`, `src/context/observation-variator.ts`, `src/agent/response-constraint.ts`, `src/tools/web-search.ts`, `src/agent/message-queue.ts` |
+| **[OpenClaw](https://github.com/openclaw/openclaw)** | Multi-channel messaging, DM pairing, lane queue concurrency, memory lifecycle, tool policy, skills system, heartbeat, identity system, group security, hub marketplace, daily session reset, per-channel streaming policies | `src/channels/streaming-policy.ts`, `src/channels/`, `src/skills/`, `src/daemon/daily-reset.ts` |
+
+**Other influences:** Rust (Result<T, E> pattern), AutoGPT, MetaGPT, CrewAI, ChatDev (role-based multi-agent), ReAct (reasoning + acting paradigm), Qodo/PR-Agent (RAG for code repos).
+
+**Benchmarks referenced:** SWE-bench, HumanEval, MBPP, BigCodeBench, WebArena, Berkeley Function Calling Leaderboard.
+
+For detailed research notes, see `docs/RESEARCH_IMPROVEMENTS.md`, `docs/RAG_TOOL_SELECTION.md`, and `deep_research/ai-coding-assistant-improvements/`.
 
 ---
 
 ## Troubleshooting
 
-### Common Issues
-
 **API key not working**
 ```bash
 echo $GROK_API_KEY  # Verify key is set
@@ -1161,8 +1470,7 @@ buddy
 - Use a faster model: `buddy --model grok-code-fast-1`
 - Use local LLM: `buddy --base-url http://localhost:11434/v1 --model llama3`
 
-### Debug Mode
-
+**Debug mode**
 ```bash
 DEBUG=codebuddy:* buddy
 ```
@@ -1181,6 +1489,6 @@ MIT License - see [LICENSE](LICENSE) for details.
 **[Request Feature](https://github.com/phuetz/code-buddy/discussions)** |
 **[Star on GitHub](https://github.com/phuetz/code-buddy)**
 
-<sub>Inspired by [OpenClaw](https://github.com/openclaw/openclaw) | Multi-AI: Grok | Claude | ChatGPT | Gemini | LM Studio | Ollama</sub>
+<sub>Multi-AI: Grok | Claude | ChatGPT | Gemini | LM Studio | Ollama</sub>
 
 </div>