@compilr-dev/cli 0.4.0 → 0.5.1

package/README.md

@@ -1,110 +1,296 @@
 # @compilr-dev/cli
 
-> AI-powered CLI assistant using @compilr-dev/agents
+```
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| CLI
+```
 
-## Overview
+> AI-powered coding assistant for your terminal
 
-An AI coding assistant for the terminal, built with the `@compilr-dev/agents` library. Supports multiple LLM providers (Claude, OpenAI, Gemini, Ollama) with streaming output, tool execution, and context management.
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/cli.svg)](https://www.npmjs.com/package/@compilr-dev/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+> [!WARNING]
+> This package is in beta. APIs may change between minor versions.
+
+## Overview
+
+A structured AI coding assistant that brings discipline to AI-assisted development. Supports 9 LLM providers, multi-agent teams, project workflows, and 25 interactive tutorials -- all in your terminal.
 
-- **Multi-LLM Support** - Claude, OpenAI, Gemini, Ollama
-- **Streaming Output** - Real-time response display with cursor positioning
-- **Tool Execution** - File operations, git, code search, project detection
-- **Context Management** - Auto-compaction, LLM summarization, token tracking
-- **Persistent Footer** - Todo list and input prompt always visible
-- **Input Queueing** - Commands queued during agent execution (FIFO)
-- **Permissions** - Interactive approval for dangerous operations
-- **Esc to Cancel** - Immediately abort running agent
+**Stop vibe coding. Start building.**
 
-## Installation
+## Quick Start
 
 ```bash
+# Install globally
 npm install -g @compilr-dev/cli
+
+# Start the CLI
+compilr
+
+# Set your API key (interactive prompt on first run)
+# Or use /keys inside the CLI
 ```
 
-## Usage
+## Features
 
-```bash
-# Start with default provider (Claude)
-compilr
+### Multi-LLM Support (9 Providers)
+
+Use your preferred AI provider with three tiers per provider (Fast / Balanced / Powerful):
+
+| Provider | Models | API Key |
+|----------|--------|---------|
+| **Claude** | Haiku, Sonnet, Opus | `ANTHROPIC_API_KEY` |
+| **OpenAI** | GPT-4o-mini, GPT-4o, o1 | `OPENAI_API_KEY` |
+| **Gemini** | Flash, Pro, Ultra | `GOOGLE_API_KEY` |
+| **Ollama** | Any local model | None (local) |
+| **Together AI** | Open-source models | `TOGETHER_API_KEY` |
+| **Groq** | Fast inference | `GROQ_API_KEY` |
+| **Fireworks** | Open-source models | `FIREWORKS_API_KEY` |
+| **Perplexity** | Search-augmented | `PERPLEXITY_API_KEY` |
+| **OpenRouter** | Multi-provider | `OPENROUTER_API_KEY` |
+
+Switch models anytime with `/model` -- a visual overlay with provider tabs, model cycling, and connection testing.
+
+### Project Workflows
+
+The CLI guides you through structured development:
+
+| Command | Description |
+|---------|-------------|
+| `/new` | Create a project with guided 8-step wizard |
+| `/design` | AI-driven requirements gathering (creates PRD + backlog) |
+| `/sketch` | Quick 6-question project outline |
+| `/prd` | Update the Product Requirements Document |
+| `/arch` | Create architecture documentation (ADR, diagrams, data model, API) |
+| `/scaffold` | Generate base project structure (folders, config, dependencies) |
+| `/build` | Implement a backlog item end-to-end |
+| `/backlog` | Visual backlog management with filtering and search |
+| `/docs` | Browse and edit all project documents |
+| `/workflow` | Project status, metrics, and actions |
+
+### Multi-Agent Teams
 
-# Use a specific provider
-compilr --provider openai --model gpt-4o
-compilr --provider gemini --model gemini-1.5-pro
-compilr --provider ollama --model llama3.1:8b
+Specialized AI agents with different expertise, tools, and model tiers:
 
-# Verbose mode (show tool filtering)
-compilr --verbose
 ```
+$arch    Architect - System design, patterns, tech decisions
+$dev     Developer - Implementation, coding, debugging
+$qa      QA Engineer - Testing, quality, code review
+$pm      PM - Planning, task tracking, estimation
+$ops     DevOps - Deployment, CI/CD, infrastructure
+$docs    Technical Writer - Documentation, guides
+$ba      Business Analyst - Requirements, metrics
+```
+
+- **`$agent message`** -- switch to an agent and send a message
+- **`$agent message &`** -- run in background (non-blocking)
+- **`/team`** -- visual team management overlay
+- **`/bg`** / **`/fg`** / **`/kill`** -- manage background agents
+- **`/filter`** -- filter conversation by agent
+- **Custom agents** -- 4-step creation wizard with tool profiles
+
+### Context Management
+
+- **Auto-compaction** -- automatically compresses old messages when context fills up
+- **Anchors** (`/anchors`) -- persistent notes that survive compaction and sessions
+- **Token tracking** (`/context`, `/tokens`) -- real-time context window visualization
+- **Session restore** -- pick up where you left off
+- **`COMPILR.md`** -- project-specific instructions loaded automatically
+
+### 418 Terminal Themes
+
+Choose from 418 themes with live preview via `/config` > Theme. Curated favorites plus browsing by Dark/Light.
+
+### Permission System
+
+Fine-grained control over what the AI can do:
+
+- **Permission levels** -- always, session, once, deny
+- **Wildcard rules** -- `git_*` matches all git tools
+- **Permission modes** -- Normal, Plan, Auto-accept
+- **Safety settings** -- delete protection, CWD mismatch warnings
+- **`/permissions`** -- visual overlay for managing rules and grants
+
+### Interactive Tutorials
+
+25 tutorials across 5 tabs, accessible via `/tutorial`:
+
+| Tab | Topics |
+|-----|--------|
+| **Basics** | Welcome, First Project, First Conversation, Navigation |
+| **Projects** | New Project, Import, Managing, Sessions, Anchors |
+| **Plan & Build** | Design, Sketch, Backlog, PRD, Arch, Docs, Scaffold, Build |
+| **Teams** | Overview, Working with Agents, Background Execution, Tasks |
+| **Config** | Model Selection, Settings, Context Management, Permissions |
+
+## Commands Reference
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `/new` | Create or import a project |
+| `/projects` | Switch between projects |
+| `/workflow` | Project status and actions |
+| `/backlog` | Manage work items |
+
+### Development
 
-## Slash Commands
+| Command | Description |
+|---------|-------------|
+| `/design` | Requirements gathering |
+| `/sketch` | Quick project outline |
+| `/prd` | Update PRD |
+| `/arch` | Architecture documentation |
+| `/scaffold` | Generate project structure |
+| `/build` | Implement backlog items |
+| `/docs` | Browse project documents |
+
+### Teams
+
+| Command | Description |
+|---------|-------------|
+| `/team` | Team management overlay |
+| `/bg` | View background agents |
+| `/fg` | Bring agent to foreground |
+| `/kill` | Terminate background agent |
+| `/pending` | View pending requests |
+| `/filter` | Filter conversation by agent |
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `/config` | Settings (4 tabs: Status, Config, Environment, Usage) |
+| `/model` | Select AI model and provider |
+| `/permissions` | Manage tool permissions |
+| `/keys` | Manage API keys |
+| `/anchors` | Persistent notes |
+
+### Context & Session
 
 | Command | Description |
 |---------|-------------|
-| `/help` | Show available commands |
+| `/context` | Context window usage |
+| `/tokens` | Token breakdown |
+| `/compact` | Compress conversation |
+| `/status` | Session overview |
+| `/export` | Save conversation to markdown |
+| `/tutorial` | Interactive guides |
+| `/help` | All commands |
+| `/clear` | Clear screen |
 | `/exit` | Exit the CLI |
-| `/clear` | Clear conversation history |
-| `/compact` | Compress context using LLM summarization |
-| `/tools` | List available tools |
-| `/tokens` | Show token usage |
-| `/context` | Show context statistics |
 
-## Requirements
+## Input Features
+
+| Feature | Syntax |
+|---------|--------|
+| **Slash commands** | `/help`, `/build REQ-003` |
+| **File references** | `@src/index.ts` (with Tab autocomplete) |
+| **Agent switching** | `$arch`, `$dev fix the bug` |
+| **Background exec** | `$qa review this &` |
+| **Tab completion** | Commands, files, and agents |
+| **Esc** | Cancel running operation |
+
+## Configuration
+
+### API Keys
 
-- Node.js 18 or higher
-- API key for your chosen provider:
-  - `ANTHROPIC_API_KEY` for Claude
-  - `OPENAI_API_KEY` for OpenAI
-  - `GOOGLE_API_KEY` for Gemini
-  - Ollama running locally (no API key needed)
+**Option 1: Use `/keys` command (recommended)**
 
-## Development
+Run `/keys` inside the CLI to securely store your API keys. Keys are encrypted and stored locally in `~/.compilr-dev/credentials.enc`.
+
+**Option 2: Environment variables**
 
 ```bash
-# Clone the repository
-git clone https://github.com/scozzola/compilr-dev-cli.git
-cd compilr-dev-cli
+export ANTHROPIC_API_KEY="sk-ant-..."   # Claude
+export OPENAI_API_KEY="sk-..."          # OpenAI
+export GOOGLE_API_KEY="..."             # Google Gemini
+# Ollama: no key needed, just run `ollama serve`
+```
+
+Environment variables take priority over stored keys.
+
+### Project Configuration
+
+Create a `COMPILR.md` file in your project root to provide context:
 
-# Install dependencies
-npm install
+```markdown
+# COMPILR.md
 
-# Run in development mode
-npm run dev
+## Project Overview
+This is a React application using TypeScript...
 
-# Build for production
-npm run build
+## Coding Standards
+- Use functional components
+- Prefer hooks over class components
 ```
 
-## Architecture
+The CLI automatically loads this file at startup.
 
-- **Runtime:** Node.js 18+
-- **Language:** TypeScript
-- **Agent Framework:** @compilr-dev/agents
-- **Coding Tools:** @compilr-dev/agents-coding
-- **UI:** Custom terminal zones (scrolling + persistent footer)
+### Settings
 
-## Documentation
+All settings available via `/config`:
 
-Specs in `/workspace/project-docs/00-requirements/compilr-dev-cli/`:
-- `poc-objectives.md` - Original validation objectives
-- `poc-scope.md` - Feature scope
-- `poc-architecture.md` - Technical design
-- `streaming-output-plan.md` - Streaming implementation
-- `theme-system-spec.md` - Theme configuration
-- `config-overlay-spec.md` - Settings system
+| Setting | Options |
+|---------|---------|
+| Auto-compact | true / false |
+| Permission mode | Normal / Plan / Accept edits / Don't ask |
+| Theme | 418 terminal themes |
+| Model | Per-provider tier selection |
+| Startup behavior | Show menu / Direct to REPL |
+| Session restore | Auto / Ask / Fresh |
+| Mascot | 13 expressions + Random / None |
 
-## License
+## Requirements
+
+- **Node.js** 20 or higher
+- **API Key** for your chosen provider (except Ollama)
+- **Platform:** macOS, Linux, or Windows via WSL2
+
+### Windows Users
+
+The CLI requires a Unix-like shell environment. On Windows, use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux):
+
+```bash
+# 1. Install WSL2 (run in PowerShell as Administrator)
+wsl --install
+
+# 2. Open your WSL terminal, then install Node.js 20+
+#    (see https://nodejs.org for instructions)
+
+# 3. Install the CLI inside WSL
+npm install -g @compilr-dev/cli
 
-MIT
+# 4. Start coding
+compilr
+```
+
+VS Code works seamlessly with WSL via the [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) -- open your project in VS Code, connect to WSL, and use the integrated terminal.
+
+## Built With
+
+- [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) - Multi-LLM agent framework
+- [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) - Coding-specific tools
 
 ## Links
 
-- [compilr.dev](https://compilr.dev) - Main website
-- [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) - Agent library
-- [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) - Coding tools
-- [GitHub](https://github.com/scozzola/compilr-dev-cli) - Source code
+- [Website](https://compilr.dev)
+- [npm Package](https://www.npmjs.com/package/@compilr-dev/cli)
+- [Report Issues](https://github.com/compilr-dev/cli/issues)
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
 
 ---
 
-**Built with @compilr-dev/agents**
+```
+[^_^] Built with @compilr-dev/agents
+```