@nomad-e/bluma-cli 0.2.1 → 0.5.0

package/README.md

@@ -1,1237 +1,369 @@
-# BluMa CLI — Base Language Unit · Model Agent
+# BluMa CLI — AI-Powered Agent for Advanced Software Engineering
 
-[![npm version](https://img.shields.io/npm/v/@nomad-e/bluma-cli.svg?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
-[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
-
-![Factorai.sh Banner](assets/bg.png)
-
-
-**BluMa** is a CLI-based model agent for advanced software engineering workflows. Built with React/Ink 5, it provides an interactive terminal interface for LLM-powered automation, code generation, refactoring, and task execution. Features persistent sessions, contextual reasoning, smart feedback, coordinator mode for worker orchestration, and extensible tools/skills architecture.
-
-> **Credit:** BluMa was conceived and architected by **Alex Fonseca**.
-
-**Current Version:** 0.1.84
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Key Features](#key-features)
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Architecture](#architecture)
-- [Native Tools](#native-tools)
-- [Skills System](#skills-system)
-- [Runtime & Orchestration](#runtime--orchestration)
-- [Slash Commands](#slash-commands)
-- [Development](#development)
-- [Testing](#testing)
-- [Contributing](#contributing)
-- [License](#license)
-
----
-
-## Overview
-
-BluMa operates as a **conversational agent** in the terminal, combining:
-
-- **Rich UI Layer**: React/Ink 5 components for interactive prompts, live overlays, and real-time feedback
-- **Agent Layer**: LLM orchestration via FactorRouter with tool invocation and context management
-- **Runtime Layer**: Task tracking, plugin system, hooks, diagnostics, session management, and coordinator mode
-- **Tool Layer**: 50+ native tools + MCP SDK integration for external tools
-
-The agent maintains persistent conversation history, workspace snapshots, and coding memory across sessions.
-
----
-
-## Key Features
-
-### Core Agent
-- **Interactive CLI**: Rich terminal UI with React/Ink 5
-- **Session Persistence**: Automatic save/load of conversation and tool history
-- **Context Management**: Token-aware context compression with history anchoring
-- **Smart Feedback**: Technical suggestions and automated checks
-- **Confirmation System**: Controlled execution with whitelists and previews
-- **Coding Memory**: Persistent notes about codebase decisions (`~/.bluma/coding_memory.json`)
-
-### Runtime & Orchestration (v0.1.41+)
-- **Plugin System**: Load plugins from `.bluma/plugins/` or `~/.bluma/plugins/`
-- **Hook Registry**: Event-driven lifecycle tracking (tool calls, decisions, state changes)
-- **Task Store**: Persistent task management with PLANNING → EXECUTION → VERIFICATION flow
-- **Session Registry**: Multi-session support with process health monitoring
-- **Thread System**: Multi-thread conversation management with isolated contexts
-- **Diagnostics**: Real-time system snapshot (tasks, hooks, plugins, sessions)
-- **Tool Execution Policy**: Intelligent decisions based on sandbox mode and safety
-
-### Tools & Skills
-- **50+ Native Tools**: File operations, search, shell commands, web fetch, agent coordination, task management, MCP resources, cron scheduling, LSP queries, notebook editing, REPL execution
-- **Coordinator Mode**: Orchestrator playbook for delegating work to background workers
-- **MCP Integration**: Model Context Protocol SDK for external tool servers
-- **Skills System**: Pluggable knowledge modules (git, PDF, Excel, etc.)
-- **Agent Coordination**: Spawn/wait/list subagents for parallel work with bidirectional mailbox system
-
-### UI Components
-- **Slash Commands**: 30+ built-in commands (`/help`, `/model`, `/tasks`, `/plugins`, `/threads`, etc.)
-- **Live Overlays**: Working timers, progress indicators, streaming text
-- **Diff Previews**: Side-by-side code comparisons before edits
-- **Tool Result Cards**: Structured display of tool outputs
-- **Session Panels**: Real-time monitoring with log streaming
-- **Thread Management**: Multi-thread conversation UI with thread switching
-
----
+![BluMa Background](assets/bg.png)
 
-## Requirements
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%2.0-blue.svg?style=flat-square)](LICENSE)
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
+[![Version](https://img.shields.io/npm/v/@nomad-e/bluma-cli?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://github.com/Nomad-e/bluma-cli/actions)
+[![Tests](https://img.shields.io/badge/tests-Jest-blue?style=flat-square)](https://jestjs.io/)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Code Style](https://img.shields.io/badge/code_style-Prettier-ff69b4?style=flat-square)](https://prettier.io/)
+[![Downloads](https://img.shields.io/npm/dm/@nomad-e/bluma-cli?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
 
-- **Node.js**: >= 20
-- **npm**: >= 9
-- **FactorRouter**: API key and URL for LLM backend
+**BluMa** is an independent AI agent CLI for automation and advanced software engineering. It combines powerful tool orchestration, multi-agent coordination, and intelligent context management to help you build software faster and with higher quality.
 
 ---
 
-## Installation
-
-### Global Installation (Recommended)
+## 🚀 Quick Start
 
 ```bash
+# Install globally
 npm install -g @nomad-e/bluma-cli
-```
-
-**Linux/macOS** (if permission errors):
-```bash
-sudo npm install -g @nomad-e/bluma-cli
-```
 
-> **macOS Note**: After installation, run `bluma` **without** sudo to avoid permission issues.
+# Run BluMa (new session)
+bluma
 
-### Local Development
+# Resume a previous session
+bluma resume {session_id}
 
-```bash
-git clone <repository-url>
-cd bluma-cli
+# Or run from source
 npm install
 npm run build
-```
-
-### Environment Setup
-
-Set these environment variables globally:
-
-```bash
-# Linux/macOS: Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile
-export FACTOR_ROUTER_KEY="sk-fai-your-key-here"
-export FACTOR_ROUTER_URL="http://host:8003/router-api"
-
-# Then reload
-source ~/.bashrc  # or ~/.zshrc
-```
-
-**Windows (PowerShell)**:
-```powershell
-[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_KEY", "sk-fai-your-key-here", "User")
-[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_URL", "http://host:8003/router-api", "User")
-```
-
----
-
-## Quick Start
-
-```bash
-# Launch BluMa
-bluma
-
-# Or from local development
 npm start
 ```
 
-### First Interaction
-
-```
-> help me create a React component
-> find all files containing "useEffect"
-> run npm test in the background
-> /tasks to see active tasks
-> /model to switch LLM model
-> /threads to manage conversation threads
-```
-
 ---
 
-## Configuration
-
-### Runtime Settings (`~/.bluma/settings.json`)
-
-```json
-{
-  "model": "auto",
-  "reasoningEffort": "medium",
-  "outputStyle": "concise",
-  "sandboxMode": "confirm",
-  "alwaysAcceptTools": ["read_file_lines", "grep_search"],
-  "theme": "default"
-}
-```
-
-| Setting | Values | Description |
-|---------|--------|-------------|
-| `model` | `auto` | LLM model (FactorRouter decides) |
-| `reasoningEffort` | `low`, `medium`, `high` | Reasoning depth |
-| `outputStyle` | `concise`, `balanced`, `verbose` | Response style |
-| `sandboxMode` | `confirm`, `auto`, `strict` | Tool execution policy |
-
-### Directory Structure
-
-```
-~/.bluma/
-├── settings.json          # Runtime configuration
-├── coding_memory.json     # Persistent coding notes
-├── artifacts/             # Saved plans and documents
-├── plugins/               # Global plugins
-├── sessions/              # Session history
-└── threads/               # Thread storage
-```
+## ✨ Key Features
+
+### 🤖 **Native Tools** (45+ tools)
+Comprehensive toolset organized by category with risk levels and auto-approve policies.  
+Tools are now modularly structured in `src/app/agent/tools/` with separate UI components:
+
+**Filesystem** (10 tools):
+- `ls_tool`, `read_file_lines`, `count_file_lines`, `find_by_name`, `grep_search`
+- `view_file_outline`, `edit_tool`, `file_write`, `notebook_edit`, `lsp_query`
+
+**Execution** (6 tools):
+- `shell_command`, `command_status`, `send_command_input`, `kill_command`
+- `repl` (interactive code execution for Python/Node/Bash)
+- `task_output` (real-time output following)
+
+**Communication** (7 tools):
+- `message`, `ask_user_question`, `brief`, `send_message`
+- `list_mailbox_messages`, `poll_mailbox`, `signal_mailbox`
+
+**Planning** (11 tools):
+- `todo`, `task_boundary`, `task_create`, `task_update`, `task_stop`
+- `task_list`, `task_get`, `enter_plan_mode`, `exit_plan_mode`
+- `cron_create`, `cron_list`, `cron_delete`
+
+**Knowledge** (10 tools):
+- `search_web`, `web_fetch`, `load_skill`, `coding_memory`
+- `ctx_inspect`, `dream`, `context_collapse`, `snip`
+- `list_mcp_resources`, `read_mcp_resource`
+
+**Agent Coordination** (4 tools):
+- `spawn_agent`, `wait_agent`, `list_agents`, `kill_agent`
+
+**FactorAI Sandbox** (5 tools):
+- `factorai.sh.create_next_app`, `factorai.sh.deploy_app`
+- `factorai.sh.get_app_status`, `factorai.sh.apply_app_changes`
+- `factorai.sh.redeploy_app`
+
+### 🧠 **Multi-Agent Orchestration**
+- **Coordinator Mode**: Product Owner + Engineering Manager hybrid that delegates to specialist workers
+- **Parallel Execution**: Launch multiple workers concurrently for research, implementation, and verification
+- **Mailbox IPC**: Bidirectional communication between coordinator and workers via `send_message`, `list_mailbox_messages`, `poll_mailbox`, `signal_mailbox`
+- **Worker Types**: Researchers, implementers, verifiers with specialized roles
+- **Session Registry**: Track and manage agent sessions with lifecycle events
+
+### 📝 **Slash Commands** (80+ commands)
+Quick access to common operations across 5 categories:
+
+- **Session** (25+): `/clear`, `/sessions`, `/attach`, `/follow`, `/bridge`, `/status`, `/logs`, `/resume`, `/kill`, `/compact`, `/export`, `/summarize`, `/history`, `/share`, `/copy`, `/commit`, `/pr`, `/release`, `/snip`, `/collapse`, `/brief`, `/undo`, `/redo`, `/thread` (with subcommands: list/new/resume/fork/rename/archive/delete)
+- **Inspect** (30+): `/plugins`, `/plugin`, `/diagnostics`, `/permissions`, `/features`, `/hooks`, `/model`, `/effort`, `/style`, `/sandbox`, `/worktree`, `/statusline`, `/skills`, `/tools`, `/mcp`, `/debug-workers`, `/cost`, `/memory`, `/stats`, `/theme`, `/keybindings`, `/vim`, `/ctx`, `/dream`, `/diff`, `/editor`, `/config`, `/file`, `/search`, `/context`, `/token`, `/settings`, `/alias`, `/macro`, `/thread stats`
+- **Agent** (15+): `/agent`, `/agents`, `/img`, `/image`, `/init`, `/review`, `/explain`, `/fix`, `/debug`, `/bug`, `/test`, `/optimize`, `/refactor`, `/document`, `/chat`, `/code`, `/terminal`, `/template`
+- **Help**: `/help`
+- **Input**: `Ctrl+V`/`Cmd+V` (paste image/text/file), `Ctrl+Shift+I` (same as Ctrl+V)
+
+### 🎯 **Intelligent Context Management**
+- **Auto Memory**: Persistent coding notes across sessions (`coding_memory`)
+- **Context Collapse**: Advanced history compaction with multiple strategies (aggressive, moderate, minimal, target token budget)
+- **Snip Tool**: Extract and remove old conversation snippets (extract/remove/auto modes)
+- **Dream Engine**: Background memory consolidation — deduplicates, merges, prunes, and enriches coding memory entries
+- **Token Tracking**: Real-time token usage monitoring with `ctx_inspect`
+- **Thread Management**: Full thread lifecycle with create, resume, fork, rename, archive, delete operations
+
+### 🛠️ **Plan Mode**
+Structured problem-solving workflow with 3 phases:
+1. **PLANNING**: Research and design
+2. **EXECUTION**: Implementation
+3. **VERIFICATION**: Testing and validation
+
+### 🔧 **Skills System**
+Extendable expertise modules with progressive disclosure:
+- **git-commit**: Conventional commits automation with BluMa watermark
+- **git-pr**: Pull request creation and management
+- **git-release**: Full release engineering workflow (version bumps, changelog, tags, npm publish)
+- **pdf**: PDF generation and manipulation (reports, merge, forms, OCR)
+- **xlsx**: Spreadsheet processing (create, edit, formulas, charting, cleaning)
+- **skill-creator**: Create custom skills
+
+### 🎨 **Modern UI**
+- Built with **Ink** (React for CLI)
+- **Shimmer effects** for working states (WorkingShimmerText, Spinner with ShimmerChar/FlashingChar)
+- **Streamlined transcript** with syntax highlighting (HighlightedCode, MarkdownRenderer)
+- **Bottom dock** for status and controls (BlumaBottomDock, StatusBar)
+- **Worker overlay** for multi-agent visualization (WorkerOverlay, WorkerStatusList)
+- **Real-time streaming** (StreamingMarkdown, StreamingText, TypewriterText)
+- **Animated indicators** (Spinner, ProgressBar)
+- **Theme system** with configurable themes (blumaTerminal theme)
+
+### 🔒 **Sandbox Security**
+- **Permission modes**: Local (auto-approve) vs Sandbox (confirmation required)
+- **Policy enforcement**: `rm -rf` protection, sudo blocking, dangerous command detection
+- **Tool risk levels**: safe, write, execute, network — with per-mode auto-approve settings
+- **FactorAI integration**: Optional sandbox backend for isolated execution with workspace manifest persistence
+
+### 📦 **Performance**
+- **TypeScript**: Full type safety with strict mode
+- **ES Modules**: Modern module system with bundler resolution
+- **React 19**: Latest React with concurrent features
+- **Optimized rendering**: Memoized message blocks, offscreen freeze, expandable previews
+
+### 🔌 **MCP Support**
+- **Model Context Protocol**: Connect to external MCP servers
+- **Resource listing**: Discover and read MCP resources
+- **SSE transport**: Server-Sent Events for real-time communication
+
+### 🧵 **Thread Management**
+- **Thread lifecycle**: Create, resume, fork, rename, archive, delete threads
+- **Thread stats**: View thread metadata and statistics
+- **Codex-style interface**: Familiar thread management commands
 
 ---
 
-## Architecture
+## 🏗️ Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                         UI Layer                            │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
-│  │  Bluma   │ │  Input   │ │  Slash   │ │  ToolResult  │   │
-│  │ Session  │ │  Prompt  │ │ Commands │ │   Display    │   │
-│  │  (Ink)   │ │          │ │          │ │              │   │
-│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘   │
-│       │            │            │              │            │
-│  ┌────┴────────────┴────────────┴──────────────┴─────┐     │
-│  │              BlumaShell / BlumaViewport            │     │
-│  │         BlumaTranscript / BlumaBottomDock          │     │
-│  └────────────────────────────────────────────────────┘     │
-└─────────────────────────────────────────────────────────────┘
-                              │
-┌─────────────────────────────┼────────────────────────────────┐
-│                   Agent Layer                              │
-│  ┌──────────────┐  ┌──────────┐  ┌──────────────────────┐  │
-│  │    Agent     │  │  BluMa   │  │   RouteManager       │  │
-│  │  Orchestrator│  │  Core    │  │   (FactorRouter)     │  │
-│  └──────┬───────┘  └────┬─────┘  └──────────┬───────────┘  │
-│         │               │                    │              │
-│  ┌──────┴───────┐  ┌────┴────┐  ┌───────────┴──────────┐  │
-│  │ ToolInvoker  │  │  LLM    │  │   PromptBuilder      │  │
-│  │              │  │ Client  │  │   + ContextManager   │  │
-│  └──────────────┘  └─────────┘  └──────────────────────┘  │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │              Thread Manager / Thread Store           │  │
-│  └──────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                              │
-┌─────────────────────────────┼────────────────────────────────┐
-│                   Runtime Layer                            │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
-│  │TaskStore │ │HookReg.  │ │PluginReg.│ │SessionReg.   │   │
-│  │          │ │          │ │          │ │              │   │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
-│  │Sandbox   │ │ToolExec  │ │Diagnostics│ │SessionView  │   │
-│  │Policy    │ │Policy    │ │           │ │             │   │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
-│  │Feature   │ │Plan Mode │ │Tool Auto │ │Tool Permission│  │
-│  │Flags     │ │Session   │ │Approve   │ │Classifier    │   │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
-│  │Mailbox   │ │Worker    │ │Permission│ │Thread        │   │
-│  │Registry  │ │Context   │ │Rules     │ │Manager       │   │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-                              │
-┌─────────────────────────────┼────────────────────────────────┐
-│                    Tools Layer                             │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │              Native Tools (50+)                      │  │
-│  │  edit_tool, file_write, shell_command, grep_search,  │  │
-│  │  spawn_agent, wait_agent, list_agents,               │  │
-│  │  send_message, list_mailbox_messages, signal_mailbox,│  │
-│  │  todo, task_boundary, task_create, task_list,        │  │
-│  │  task_get, task_update, task_stop,                   │  │
-│  │  coding_memory, search_web, web_fetch, load_skill,   │  │
-│  │  message, ask_user_question, repl,                   │  │
-│  │  list_mcp_resources, read_mcp_resource,              │  │
-│  │  cron_create, cron_list, cron_delete,                │  │
-│  │  lsp_query, notebook_edit,                           │  │
-│  │  enter_plan_mode, exit_plan_mode, ...                │  │
-│  └──────────────────────────────────────────────────────┘  │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │              MCP SDK Integration                     │  │
-│  │         External tool servers via MCP                │  │
-│  └──────────────────────────────────────────────────────┘  │
+│                      BluMa CLI (Ink UI)                     │
+├─────────────────────────────────────────────────────────────┤
+│  BlumaShell  │  BlumaViewport  │  BlumaTranscript          │
+│  BlumaBottomDock  │  BlumaWorkersOverlay  │  PlanPopup      │
+├─────────────────────────────────────────────────────────────┤
+│              useBlumaSessionRuntime (Hook)                  │
+├─────────────────────────────────────────────────────────────┤
+│  Session Registry  │  Agent Core  │  Tool Invoker          │
+│  Thread Manager  │  Prompt Builder  │  Mailbox IPC         │
+├─────────────────────────────────────────────────────────────┤
+│  Native Tools (45+)  │  Skills (6)  │  MCP Clients         │
+│  FactorAI Sandbox  │  Hook Registry  │  Feature Flags      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
----
-
-## Native Tools
-
-BluMa includes **50+ built-in tools** organized by category:
-
-### File Operations
-| Tool | Description |
-|------|-------------|
-| `edit_tool` | Replace text in files (precise, multi-line, batch edits) |
-| `file_write` | Create/overwrite entire files |
-| `read_file_lines` | Read specific line ranges (up to 2000 lines) |
-| `count_file_lines` | Get file line count |
-| `ls_tool` | List directories with filtering and pagination |
-| `find_by_name` | Glob-based file search |
-| `grep_search` | Text/regex search across files |
-| `view_file_outline` | Show code structure (classes, functions, interfaces) |
-| `notebook_edit` | Edit Jupyter `.ipynb` files (cells operations) |
-
-### Shell & Commands
-| Tool | Description |
-|------|-------------|
-| `shell_command` | Execute background commands |
-| `command_status` | Check command progress/output |
-| `send_command_input` | Send input to running commands' stdin |
-| `kill_command` | Terminate running commands |
-
-### Agent Coordination (v0.1.60+)
-| Tool | Description |
-|------|-------------|
-| `spawn_agent` | Create background worker agents |
-| `wait_agent` | Wait for agent completion |
-| `list_agents` | List active/completed agents |
-| `send_message` | Send follow-up to running worker (continue without re-spawn) |
-| `list_mailbox_messages` | Read messages from workers (progress, permission requests) |
-| `signal_mailbox` | Send ack/nack/progress signals to workers |
-| `poll_mailbox` | Poll mailbox for new messages |
-
-### Task & Project Management
-| Tool | Description |
-|------|-------------|
-| `todo` | Manage task lists |
-| `task_boundary` | Track task phases (PLANNING/EXECUTION/VERIFICATION) |
-| `task_create` | Create session-scoped tasks |
-| `task_list` | List all session tasks |
-| `task_get` | Get one task by id |
-| `task_update` | Update task fields |
-| `task_stop` | Cancel a task |
-| `task_output` | Read task output in real-time |
-| `create_artifact` | Save documents under `<workspace>/.bluma/artifacts/<session>/` |
-| `read_artifact` | Read artifacts from the current session directory |
-
-### Thread Management (v0.1.84+)
-| Tool | Description |
-|------|-------------|
-| `thread_create` | Create new conversation thread |
-| `thread_list` | List all threads |
-| `thread_switch` | Switch to different thread |
-| `thread_archive` | Archive a thread |
-
-### Knowledge & Research
-| Tool | Description |
-|------|-------------|
-| `search_web` | Search programming solutions (Reddit, GitHub, StackOverflow) |
-| `web_fetch` | Fetch and analyze remote URLs |
-| `load_skill` | Activate domain-specific skills |
-| `coding_memory` | CRUD for persistent coding notes |
-
-### Communication & Interaction
-| Tool | Description |
-|------|-------------|
-| `message` | Post user-visible chat (info/result types) |
-| `ask_user_question` | Ask multiple-choice questions in terminal |
-
-### MCP & Resources
-| Tool | Description |
-|------|-------------|
-| `list_mcp_resources` | List resources from MCP servers |
-| `read_mcp_resource` | Read a resource URI from MCP server |
-
-### Scheduling
-| Tool | Description |
-|------|-------------|
-| `cron_create` | Schedule one-shot or repeating reminders |
-| `cron_list` | List scheduled cron jobs |
-| `cron_delete` | Cancel scheduled job |
-
-### Development Tools
-| Tool | Description |
-|------|-------------|
-| `lsp_query` | LSP go-to-definition or references (TS/JS) |
-| `repl` | Interactive code execution (Python, Node, Bash) |
-
-### Specialized
-| Tool | Description |
-|------|-------------|
-| `context_collapse` | Collapse context window |
-| `dream_engine` | Auto-dream feature (coding memory consolidation) |
-| `brief` | Generate project brief |
-| `ctx_inspect` | Inspect current context |
-| `snip` | Code snippet management |
-| `coordinator_tools` | Coordinator mode utilities |
-| `create-next-app` | Scaffold Next.js project with shadcn/ui + Tailwind |
-| `deploy-app` | Deploy Next.js to Severino hosting |
-
-### Plan Mode
-| Tool | Description |
-|------|-------------|
-| `enter_plan_mode` | Enter plan-only mode (edits require confirmation) |
-| `exit_plan_mode` | Leave plan mode |
+### Modular Tool Architecture
+
+Each tool in `src/app/agent/tools/` follows a consistent structure:
+
+```
+ToolName/
+├── index.ts           # Public API exports
+├── ToolName.ts        # Core implementation logic
+├── UI.tsx             # React/Ink UI component
+└── types.ts           # Type definitions
+```
+
+This modular design enables:
+- **Independent testing** of each tool
+- **Clear separation** of logic and presentation
+- **Easy discovery** and maintenance
+- **Consistent patterns** across the codebase
+
+### Core Components
+
+- **`src/main.ts`**: Entry point with CLI mode, agent mode, session management
+- **`src/app/ui/`**: React/Ink UI components
+  - `App.tsx`: Main orchestrator
+  - `BlumaSession.tsx`: Session management and UI lifecycle
+  - `components/`: Reusable UI elements (40+ components)
+  - `hooks/`: React hooks for state management
+  - `theme/`: Theme system and terminal styling
+  - `utils/`: Utility functions and slash command registry
+- **`src/app/agent/`**: AI agent core
+  - `core/`: Prompt building, context management, LLM integration, thread management
+  - `tools/`: **Modular tool architecture** — 43+ tool directories, each with:
+    - Implementation logic (`*.ts`)
+    - UI components (`UI.tsx`)
+    - Type definitions (`types.ts`)
+    - Index exports (`index.ts`)
+  - `runtime/`: Session runtime, sandbox policy, plugin system, hook registry
+  - `session_manager/`: Multi-session orchestration
+  - `subagents/`: Worker system with base LLM subagent and coordinator tools
+  - `bluma/`: BluMa-specific core logic and turn start payload
+- **`src/app/agent/config/`**: Configuration files and skill definitions
+- **`src/ink/`**: Ink renderer shims and compatibility layer
+- **`src/shims/`**: Build-time shims for react-compiler-runtime and bidi-js
+- **`native/`**: Rust-based native modules (clipboard, yoga-layout)
+- **`vscode-extension/`**: VS Code extension for chat integration
 
 ---
 
-## Current Features
-
-### Thread System (v0.1.84+)
-**Multi-thread conversation management** for isolated contexts:
-
-```typescript
-// Create a new thread
-thread_create({
-  name: "Feature Implementation",
-  context: "Working on authentication module"
-})
-
-// List all threads
-thread_list()
-
-// Switch between threads
-thread_switch({ threadId: "thread-123" })
-```
-
-**Key Benefits:**
-- **Isolated contexts** - Each thread maintains separate conversation history
-- **Parallel work** - Work on multiple features simultaneously
-- **Context preservation** - Switch without losing previous context
-- **Thread-specific memory** - Coding memories scoped to threads
-
-### Mailbox System (Bidirectional Communication)
-**Push-based communication** between coordinator and workers using EventEmitter:
-
-```typescript
-// Coordinator sends follow-up to running worker
-send_message({
-  to: "worker-session-id",
-  message: "Fix the null pointer in src/auth/validate.ts:42..."
-})
-
-// Coordinator reads messages from workers
-list_mailbox_messages({
-  from: "worker-session-id",
-  type: "progress_update",
-  unreadOnly: true
-})
-
-// Workers send progress/permission requests
-signal_mailbox({
-  sessionId: "coordinator-session-id",
-  type: "progress",
-  data: { percent: 50 }
-})
-```
-
-**Key Benefits:**
-- **No polling needed** - EventEmitter pushes messages instantly
-- **Permission requests** - Workers can request permissions mid-execution
-- **Progress tracking** - Real-time progress updates
-- **Follow-up commands** - Continue workers without re-spawn
-
-### Permission System
-**Granular permission rules** with allow/deny patterns:
-
-```typescript
-// Check permission for tool invocation
-permissionRulesEngine.checkPermission('edit_tool', {
-  filepath: '/src/auth/validate.ts'
-})
-// Returns: 'allow' | 'deny' | 'ask'
-
-// Add custom rule
-permissionRulesEngine.addRule({
-  type: 'allow',
-  toolPattern: 'read_*',
-  pathPattern: '**/*.md',
-  scope: 'global'
-})
-```
-
-**Features:**
-- **Tool patterns** - Wildcard matching for tool names
-- **Path patterns** - Glob-based file path matching
-- **Command patterns** - Shell command pattern matching
-- **Scopes** - global, workspace, session-level rules
-
-### Worker Context Isolation
-**AsyncLocalStorage-based context** for in-process workers:
-
-```typescript
-import { runWithWorkerContext, createWorkerContext } from './worker_context'
-
-const ctx = createWorkerContext({
-  workerType: 'research',
-  name: 'auth-investigation'
-})
-
-await runWithWorkerContext(ctx, async () => {
-  // Worker code runs with isolated context
-  // Shares LLM/MCP clients but has unique context
-})
-```
-
-### REPL Tool
-**Interactive code execution** for rapid prototyping:
-
-```typescript
-repl({
-  language: 'python',
-  code: `
-import pandas as pd
-df = pd.DataFrame({'a': [1, 2, 3]})
-print(df.sum())
-  `,
-  timeout: 30000
-})
-```
-
-**Supported languages:** Python, Node.js, Bash
-
-### Context Auto-Compact
-**Automatic context compression** with history anchoring:
-
-- **Budget:** 240k tokens
-- **Trigger:** 70% of budget (168k tokens)
-- **Strategy:** Compress old turns, keep last 10 turns complete
-- **Anchor:** System message with compressed summary
-
-```typescript
-const { messages, newAnchor } = await createApiContextWindow(
-  fullHistory,
-  currentAnchor,
-  compressedTurnSliceCount,
-  llmService,
-  userContext
-)
-```
-
-### Session Memory Extractor
-**Automatic memory extraction** from conversations:
-
-```typescript
-const memories = await memoryExtractor.extractMemoriesFromSession(messages)
-// Returns: ExtractedMemory[] with type, content, confidence, tags
-
-// Get relevant memories for query
-const relevant = await memoryExtractor.getRelevantMemories('authentication')
-```
-
-**Memory types:** codebase_knowledge, preference, decision, pattern, bugfix, architecture
-
-### Vim Mode
-**Vim-like keybindings** in input prompt:
-
-- **Modes:** normal, insert, visual, command
-- **Motions:** h/j/k/l, w/b, 0/$, g/G
-- **Operators:** d (delete), c (change), y (yank)
-- **Commands:** `:w`, `:q`, etc.
-
-```typescript
-// Enable vim mode
-/vim toggle
-```
+## 📋 Configuration
 
-### Themes System
-**6 configurable UI themes:**
+### Environment Variables
 
-| Theme | Description |
-|-------|-------------|
-| `default` | Classic dark terminal |
-| `dracula` | Purple accents |
-| `github` | GitHub Dark mode |
-| `monokai` | Vibrant green accents |
-| `nord` | Arctic blue palette |
-| `tokyo` | Tokyo Night blue-purple |
+Create a `.env` file in your project root:
 
 ```bash
-/theme dracula
-```
+# Required for AI features
+FACTOR_ROUTER_KEY=your_key
+FACTOR_ROUTER_URL=https://api.factorai.sh
 
-### Init Subagent
-**Automatic BluMa.md generation:**
+# Optional: MCP Server
+MCP_SSE_URL=http://localhost:3000/sse
 
-```bash
-/init
+# Optional: FactorAI Sandbox
+FACTORAI_BASE_URL=http://localhost:8080
+FACTORAI_API_KEY=your-sandbox-key
 ```
 
-Scans repository and generates comprehensive codebase documentation including:
-- Project overview
-- Technology stack detection
-- Directory structure with annotations
-- Key configs and scripts
-- CLI commands
-- Operational notes
-
-### Coding Memory Consolidate
-**Deduplication of coding memories:**
-
-```typescript
-consolidateCodingMemoryFile()
-// Merges duplicate entries by normalized text
-// Keeps oldest ID, merges tags
-// Creates backup .bak file
-```
+### Runtime Modes
 
----
+BluMa supports different permission modes:
 
-## Skills System
+- **Local Mode**: Auto-approve safe operations
+- **Sandbox Mode**: Require confirmation for write/execute operations
 
-Skills are **self-contained knowledge modules** that extend BluMa with domain expertise. They use **Progressive Disclosure** to manage context efficiently.
-
-### Skill Sources (Priority Order)
-
-| Priority | Source | Path |
-|----------|--------|------|
-| 1 | **Bundled** | `dist/config/skills/` |
-| 2 | **Project** | `{cwd}/.bluma/skills/` |
-| 3 | **Global** | `~/.bluma/skills/` |
-
-### Progressive Disclosure Levels
-
-```
-Level 1: description (frontmatter)
-    Always visible. Cost: ~1 line per skill.
-    Purpose: Let agent DECIDE to activate.
-    
-    ↓ agent calls load_skill(name)
-    
-Level 2: SKILL.md body
-    Injected when activated. Cost: 50-300 lines.
-    Purpose: Core instructions and quick-start.
-    
-    ↓ agent reads reference or runs script (if needed)
-    
-Level 3a: references/*.md
-    Read on-demand. Cost: only when read.
-    Purpose: Advanced documentation.
-    
-Level 3b: scripts/*.py
-    Executed on-demand. Cost: zero context.
-    Purpose: Pre-built utilities.
-```
-
-### Available Skills
-
-| Skill | Description |
-|-------|-------------|
-| `git-commit` | Conventional commits, staging, commit messages |
-| `git-pr` | Pull requests, code review preparation |
-| `git-release` | Version bumps, changelogs, git tags, GitHub releases |
-| `pdf` | PDF creation, extraction, merging, OCR |
-| `xlsx` | Spreadsheet operations, formulas, charts |
-| `skill-creator` | Author new BluMa skills |
-
-### Loading Skills
-
-```typescript
-// Via command
-> load the git-commit skill
-
-// Via tool call
-load_skill({ skill_name: "git-commit" })
+Set via environment or runtime config:
+```bash
+BLUMA_PERMISSION_MODE=sandbox
 ```
 
-Skills inject domain knowledge and best practices into the agent's context. Each skill has:
-- **Frontmatter**: Description and dependencies (always visible)
-- **Body**: Core instructions (injected on activation)
-- **References**: Advanced docs (read on-demand)
-- **Scripts**: Executable utilities (zero context cost)
-
 ---
 
-## Runtime & Orchestration
+## 🛠️ Development
 
-### Task Store
+### Prerequisites
 
-Track work with PLANNING → EXECUTION → VERIFICATION phases:
-
-```typescript
-task_boundary({
-  task_name: "Implementing Authentication",
-  mode: "PLANNING",
-  task_status: "Creating middleware structure"
-});
-```
+- Node.js >= 20
+- npm >= 9
 
-### Thread Manager (v0.1.84+)
+### Setup
 
-Manage multiple conversation threads:
-
-```typescript
-// Thread operations
-thread_create({ name: "Feature A" })
-thread_list()
-thread_switch({ threadId: "..." })
-thread_archive({ threadId: "..." })
-```
+```bash
+# Clone the repository
+git clone https://github.com/Nomad-e/bluma-cli.git
+cd bluma-cli
 
-### Hook Registry
+# Install dependencies
+npm install
 
-Event-driven lifecycle tracking:
+# Build the project
+npm run build
 
-```typescript
-// Hooks fire on: tool_calls, decisions, state_changes
-registerHook('tool_calls', (event) => {
-  console.log(`Tool ${event.toolName} executed`);
-});
+# Start BluMa
+npm start
 ```
 
-### Plugin Registry
-
-Load plugins from `.bluma/plugins/`:
-
-```bash
-> /plugins list          # Show loaded plugins
-> /plugins load my-plugin # Load a plugin
-```
+### Scripts
 
-### Session Registry
+| Script | Description |
+|--------|-------------|
+| `npm run build` | TypeScript check + bundle |
+| `npm run build:native` | Build native modules |
+| `npm run build:all` | Build native + TypeScript |
+| `npm run precommit` | Run pre-commit validation |
+| `npm start` | Build + run BluMa |
+| `npm test` | Run Jest tests |
+| `npm run test:watch` | Watch mode for tests |
+| `npm run test:parallel` | Parallel test execution |
+| `npm run test:parallel:fast` | Fast parallel tests with 8 workers |
+| `npm run lint` | ESLint check |
+| `npm run lint:fix` | Auto-fix lint errors |
 
-Multi-session support with health monitoring:
+### Testing
 
 ```bash
-> /sessions list         # List all sessions
-> /sessions logs <id>    # Stream session logs
-> /sessions kill <id>    # Terminate session
-```
+# Run all tests
+npm test
 
-### Diagnostics
+# Run specific test file
+npm test -- tests/tool_invocation.spec.ts
 
-Real-time system snapshot:
+# Watch mode
+npm run test:watch
 
-```bash
-> /diagnostics           # Full system status
-> /diagnostics tasks     # Task overview
-> /diagnostics hooks     # Hook registry status
-> /diagnostics plugins   # Plugin registry status
-> /diagnostics sessions  # Active sessions
-> /diagnostics threads   # Thread overview
+# Parallel tests (faster)
+npm run test:parallel:fast
 ```
 
-### Runtime Files
-
-| File | Purpose |
-|------|---------|
-| `~/.bluma/task_state.json` | Persistent task tracking |
-| `~/.bluma/hooks.json` | Hook registry state |
-| `~/.bluma/sessions/` | Session history and logs |
-| `~/.bluma/plugins/` | Global plugin storage |
-| `~/.bluma/threads/` | Thread storage |
+### Contributing
 
-### Tool Execution Policy
-
-BluMa uses intelligent tool execution based on sandbox mode:
-
-| Sandbox Mode | Behavior |
-|--------------|----------|
-| `confirm` | Prompt for dangerous tools (shell, edit, write) |
-| `auto` | Auto-approve safe tools, confirm risky ones |
-| `strict` | Require confirmation for all tools |
-
-Safe tools (always auto-approved): `read_file_lines`, `grep_search`, `ls_tool`, `find_by_name`, `count_file_lines`, `view_file_outline`
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 
 ---
 
-## Slash Commands
-
-Built-in terminal commands (type `/` to see all):
-
-### Session & UI
-| Command | Description |
-|---------|-------------|
-| `/clear` | Clear chat below welcome panel |
-| `/sessions` | Show registered sessions (current + historical) |
-| `/attach <id>` | Live-follow a session log stream |
-| `/follow <id>` | Alias of /attach for live session follow |
-| `/bridge` | Show session bridge state and follow instructions |
-| `/status <id>` | Show session status for a session id |
-| `/logs <id>` | Show recent logs for a session id |
-| `/resume <id>` | Resume a session from the current CLI |
-| `/kill <id>` | Send SIGTERM to a session by id |
-| `/tasks [list\|add\|complete\|update\|remove\|clear]` | Manage task list |
-| `/plan [show\|start\|end]` | Manage the active task boundary |
-| `/compact` | Manually compact conversation context |
-| `/export` | Export conversation as markdown |
-
-### Threads (v0.1.84+)
-| Command | Description |
-|---------|-------------|
-| `/threads` | List all conversation threads |
-| `/thread [id]` | Switch to thread or show current |
-| `/thread new [name]` | Create new thread |
-| `/thread archive [id]` | Archive a thread |
-
-### Agent
-| Command | Description |
-|---------|-------------|
-| `/img ./shot.png [question]` | Send local image(s) to the model |
-| `/image` | Alias of /img |
-| `/init` | Run init subagent — BluMa.md codebase documentation |
-| `/agent [default\|coordinator]` | Set prompt profile (coordinator playbook for worker orchestration) |
-| `/agents` | List worker/agent sessions (spawn_agent children) |
-
-### Inspect
-| Command | Description |
-|---------|-------------|
-| `/plugins` | List installed plugins and plugin paths |
-| `/plugin <name>` | Inspect one plugin |
-| `/diagnostics` | Show a consolidated health snapshot |
-| `/permissions` | Inspect sandbox and tool rules; set mode |
-| `/hooks` | Inspect, enable, disable, or clear lifecycle hooks |
-| `/model [list\|name\|auto]` | Show, list, or set the active model |
-| `/effort [low\|medium\|high]` | Show or set reasoning effort |
-| `/style [default\|compact\|brief]` | Show or set output style |
-| `/sandbox [on\|off]` | Show or toggle sandbox mode |
-| `/worktree [path]` | Show or set workspace root |
-| `/statusline` | Show the current session statusline summary |
-| `/skills` | List load_skill modules, dirs, and conflicts |
-| `/tools [grep]` | List native tools (optional filter) |
-| `/mcp [fs]` | List MCP tools (optional filter) |
-| `/features` | Feature flags: `/features` or `/features <key> on\|off` |
-| `/debug-workers` | Show running workers, PIDs, memory, and event bus state |
-| `/cost` | Show session cost and token usage |
-| `/memory` | Manage session memories |
-| `/stats` | Detailed session statistics |
-| `/theme` | Change UI theme |
-| `/keybindings` | Show or configure keybindings |
-| `/vim` | Toggle vim mode |
-
-### Help
-| Command | Description |
-|---------|-------------|
-| `/help` | List all slash commands (grouped) |
-
-### Input (Keyboard Shortcuts)
-| Shortcut | Description |
-|----------|-------------|
-| `Ctrl+V / Cmd+V` | Paste from clipboard: image → cache `~/.cache/bluma/clipboard`; text; or file path as image |
-| `Ctrl+Shift+I` | Same as Ctrl+V (paste image, text, or file path) |
-| `Ctrl+O` | Expand truncated previews in tool results |
+## 📚 Documentation
 
----
+- **[Developer Guide](docs/BLUMA_DEVELOPER_GUIDE.md)**: Complete technical reference
+- **[Skills Guide](docs/SKILLS.md)**: How to create and use skills
+- **[Mailbox IPC](docs/MAILBOX_IPC.md)**: Multi-agent communication
+- **[CI/CD](docs/CI-TEST.md)**: Continuous integration setup
+- **[Message Queue](docs/message-queue-design.md)**: IPC system design
+- **[Parallel Tests](docs/parallel-tests.md)**: Test parallelization guide
 
-## Development
+---
 
-### Build
+## 🎯 Use Cases
 
+### 1. **Code Analysis & Refactoring**
 ```bash
-npm run build        # Production build
-npm run build:native # Build native modules
-npm run build:all    # Build native + main
-npm start           # Build + run
-```
-
-### Lint
+# Ask BluMa to analyze your codebase
+bluma
 
-```bash
-npm run lint        # Check code style
-npm run lint:fix    # Auto-fix issues
+# Then use slash commands
+/explain src/app/agent/core/prompt_builder.ts
+/refactor src/utils/helpers.ts
+/fix src/components/Button.tsx
 ```
 
-### Test
-
+### 2. **Multi-Agent Development**
 ```bash
-npm test            # Run all tests
-npm run test:watch  # Watch mode
-npm run test:parallel        # Parallel test execution
-npm run test:parallel:fast   # Fast parallel with 8 workers
-```
-
-### Project Structure
+# Coordinator mode: delegate to workers
+"Build a new feature with research, implementation, and verification"
 
+# BluMa automatically spawns:
+# - Researcher: Investigate codebase structure
+# - Implementer: Write the code
+# - Verifier: Run tests and validate
 ```
-src/
-├── app/
-│   ├── agent/
-│   │   ├── agent.ts                    # Main orchestrator
-│   │   ├── bluma/                      # Core agent logic
-│   │   │   ├── core/
-│   │   │   │   ├── bluma.ts            # BluMaAgent class
-│   │   │   │   └── turn_start_payload.ts
-│   │   │   ├── context/
-│   │   │   │   └── auto_compact.ts     # Automatic context compaction
-│   │   │   ├── memory/
-│   │   │   │   └── session_memory.ts   # Session memory
-│   │   │   └── types/
-│   │   │       └── errors.ts           # Error type definitions
-│   │   ├── config/
-│   │   │   ├── native_tools.json       # Tool definitions (50+)
-│   │   │   ├── skills/                 # Bundled skills
-│   │   │   │   ├── git-commit/
-│   │   │   │   ├── git-pr/
-│   │   │   │   ├── git-release/        # Version bumps, changelogs, releases
-│   │   │   │   ├── pdf/
-│   │   │   │   ├── skill-creator/
-│   │   │   │   └── xlsx/
-│   │   │   │       └── scripts/
-│   │   │   │           └── office/     # Office document handling
-│   │   ├── core/                       # LLM, context, prompts
-│   │   │   ├── context-api/            # Context management
-│   │   │   │   ├── context_manager.ts  # Token-aware context
-│   │   │   │   ├── history_anchor.ts   # Conversation anchoring
-│   │   │   │   └── token_counter.ts    # Tiktoken integration
-│   │   │   ├── llm/                    # LLM client
-│   │   │   │   ├── llm.ts              # FactorRouter client
-│   │   │   │   ├── llm_errors.ts       # LLM error formatting
-│   │   │   │   ├── streaming_delta.ts  # Streaming delta handling
-│   │   │   │   └── tool_call_normalizer.ts
-│   │   │   ├── prompt/                 # Prompt engineering
-│   │   │   │   ├── prompt_builder.ts   # Dynamic prompts
-│   │   │   │   ├── workspace_snapshot.ts
-│   │   │   │   ├── mcp_instructions.ts
-│   │   │   │   ├── model_info.ts
-│   │   │   │   ├── production_sandbox_prompt.ts
-│   │   │   │   ├── system_prompt_sections.ts
-│   │   │   │   ├── system_reminders.ts
-│   │   │   │   └── tool_guidance.ts
-│   │   │   ├── thread/                 # Thread management (v0.1.84+)
-│   │   │   │   ├── index.ts
-│   │   │   │   ├── thread_manager.ts
-│   │   │   │   ├── thread_store.ts
-│   │   │   │   └── types.ts
-│   │   │   └── context_viz.ts          # Context visualization
-│   │   ├── docs/
-│   │   │   └── TOOL_PARITY.md          # Tool parity documentation
-│   │   ├── feedback/
-│   │   │   └── feedback_system.ts      # Smart feedback system
-│   │   │   └── feedback_scoring.ts     # User feedback scoring
-│   │   ├── runtime/                    # Orchestration layer
-│   │   │   ├── diagnostics.ts          # System snapshots
-│   │   │   ├── feature_flags.ts        # Feature gates
-│   │   │   ├── hook_registry.ts        # Event-driven hooks
-│   │   │   ├── native_tool_catalog.ts  # Tool registry
-│   │   │   ├── permission_bridge.ts    # Leader↔Worker permission system
-│   │   │   ├── permission_rules.ts     # Permission rule definitions
-│   │   │   ├── tool_permission_classifier.ts
-│   │   │   ├── plan_mode_session.ts    # Plan mode state
-│   │   │   ├── plugin_registry.ts      # Plugin system
-│   │   │   ├── plugin_runtime.ts       # Plugin execution
-│   │   │   ├── runtime_config.ts       # Runtime settings
-│   │   │   ├── sandbox_policy.ts       # Safety policies
-│   │   │   ├── session_registry.ts     # Multi-session mgmt
-│   │   │   ├── session_view.ts         # Session monitoring
-│   │   │   ├── task_store.ts           # Task lifecycle
-│   │   │   ├── tool_auto_approve.ts    # Auto-approve rules
-│   │   │   ├── tool_execution_policy.ts
-│   │   │   ├── tool_orchestration.ts   # Parallel read eligibility
-│   │   │   ├── mailbox_registry.ts     # Mailbox system
-│   │   │   ├── worker_context.ts       # Worker context management
-│   │   │   └── factorai_context.ts     # FactorAI app context
-│   │   ├── session_manager/
-│   │   │   └── session_manager.ts      # Session persistence
-│   │   ├── skills/
-│   │   │   └── skill_loader.ts         # 3-source skill loading
-│   │   ├── subagents/                  # Subagent system
-│   │   │   ├── base_llm_subagent.ts
-│   │   │   ├── init/                   # Init subagent (BluMa.md)
-│   │   │   │   ├── init_subagent.ts    # Deep project analysis
-│   │   │   │   ├── init_system_prompt.ts
-│   │   │   │   └── contracts.ts
-│   │   │   ├── registry.ts
-│   │   │   ├── subagents_bluma.ts      # SubAgent orchestration
-│   │   │   ├── types.ts                # SubAgent type definitions
-│   │   │   └── worker_system_prompt.ts
-│   │   ├── tools/
-│   │   │   ├── mcp/
-│   │   │   │   └── mcp_client.ts       # MCP SDK client
-│   │   │   ├── shared/
-│   │   │   │   └── token_utils.ts      # Token utilities
-│   │   │   └── natives/                # 50+ native tool implementations
-│   │   │       ├── agent_coordination.ts
-│   │   │       ├── ask_user_question.ts
-│   │   │       ├── async_command.ts
-│   │   │       ├── coding_memory.ts
-│   │   │       ├── coding_memory_consolidate.ts
-│   │   │       ├── coordinator_tools.ts
-│   │   │       ├── count_lines.ts
-│   │   │       ├── edit.ts
-│   │   │       ├── file_write.ts
-│   │   │       ├── find_by_name.ts
-│   │   │       ├── grep_search.ts
-│   │   │       ├── list_mailbox_messages.ts
-│   │   │       ├── load_skill.ts
-│   │   │       ├── ls.ts
-│   │   │       ├── lsp_query.ts
-│   │   │       ├── mcp_resources.ts
-│   │   │       ├── message.ts
-│   │   │       ├── notebook_edit.ts
-│   │   │       ├── plan_mode_tools.ts
-│   │   │       ├── poll_mailbox.ts
-│   │   │       ├── readLines.ts
-│   │   │       ├── repl.ts
-│   │   │       ├── search_web.ts
-│   │   │       ├── send_message.ts
-│   │   │       ├── session_cron.ts
-│   │   │       ├── shell_command.ts
-│   │   │       ├── signal_mailbox.ts
-│   │   │       ├── task_boundary.ts
-│   │   │       ├── task_output.ts
-│   │   │       ├── task_tools.ts
-│   │   │       ├── todo.ts
-│   │   │       ├── view_file_outline.ts
-│   │   │       └── web_fetch.ts
-│   │   ├── types/
-│   │   │   └── index.ts
-│   │   └── utils/
-│   │       ├── blumamd.ts              # BluMa markdown utilities
-│   │       ├── coordinator_prompt.ts   # Coordinator mode playbook
-│   │       ├── logger.ts               # Logging utilities
-│   │       ├── update_check.ts
-│   │       └── user_message_images.ts
-│   └── ui/
-│       ├── App.tsx                     # Main UI component
-│       ├── BlumaSession.tsx            # Session component (v0.1.84+)
-│       ├── Asci/
-│       │   └── AsciiArt.ts
-│       ├── components/                 # 35+ UI components
-│       │   ├── AnimatedBorder.tsx
-│       │   ├── AskUserQuestionPrompt.tsx
-│       │   ├── AssistantMessageDisplay.tsx
-│       │   ├── BlumaBottomDock.tsx     # Bottom dock (v0.1.84+)
-│       │   ├── BlumaShell.tsx          # Shell container (v0.1.84+)
-│       │   ├── BlumaTranscript.tsx     # Message transcript (v0.1.84+)
-│       │   ├── BlumaViewport.tsx       # Viewport container (v0.1.84+)
-│       │   ├── BlumaWorkersOverlay.tsx # Workers overlay (v0.1.84+)
-│       │   ├── CollapsibleResult.tsx
-│       │   ├── ConfirmationPrompt.tsx  # Permission confirmation dialog
-│       │   ├── CtrlOToExpand.tsx       # Ctrl+O expansion (v0.1.84+)
-│       │   ├── EditToolDiffPanel.tsx   # Diff preview for edits
-│       │   ├── ErrorMessage.tsx
-│       │   ├── ExpandedPreviewBlock.tsx
-│       │   ├── FilePathLink.tsx        # File path links (v0.1.84+)
-│       │   ├── HighlightedCode.tsx     # Syntax highlighting (v0.1.84+)
-│       │   ├── InputPrompt.tsx         # User input
-│       │   ├── InteractiveMenu.tsx     # Interactive menu component
-│       │   ├── MarkdownRenderer.tsx
-│       │   ├── ProgressBar.tsx
-│       │   ├── ReasoningDisplay.tsx    # LLM reasoning
-│       │   ├── SessionStats.tsx
-│       │   ├── SimpleDiff.tsx
-│       │   ├── SlashCommands.tsx       # 30+ commands
-│       │   ├── StartupUpdateGate.tsx   # Update check gate
-│       │   ├── StatusNotification.tsx
-│       │   ├── StreamingText.tsx       # Live text output
-│       │   ├── TaskDisplay.tsx
-│       │   ├── TodoPlanDisplay.tsx     # Task visualization
-│       │   ├── ToolCallDisplay.tsx
-│       │   ├── ToolInvocationBlock.tsx
-│       │   ├── ToolResultCard.tsx      # Structured results
-│       │   ├── ToolResultDisplay.tsx
-│       │   ├── TypewriterText.tsx
-│       │   ├── UpdateNotice.tsx
-│       │   ├── WorkerOverlay.tsx       # Worker status overlay
-│       │   ├── WorkerStatusList.tsx    # Active workers list
-│       │   ├── WorkerTranscript.tsx    # Worker conversation transcript
-│       │   ├── WorkingTimer.tsx        # Work duration timer
-│       │   ├── WorkingShimmerText.tsx  # Shimmer text effect
-│       │   ├── streamingTextFlush.ts
-│       │   ├── toolCallRenderers.tsx
-│       │   └── slash-commands/         # Slash command renderers
-│       │       ├── SessionLivePanel.tsx
-│       │       ├── SlashCommands.types.ts
-│       │       ├── commandHelpers.tsx
-│       │       ├── constants.ts
-│       │       └── renderers/
-│       │           ├── index.ts
-│       │           ├── configRenderers.tsx
-│       │           ├── infoRenderers.tsx
-│       │           ├── permissionRenderers.tsx
-│       │           ├── pluginRenderers.tsx
-│       │           ├── sessionRenderers.tsx
-│       │           ├── staticRenderers.tsx
-│       │           ├── taskRenderers.tsx
-│       │           └── threadRenderers.tsx  # Thread renderers (v0.1.84+)
-│       ├── constants/
-│       │   ├── historyLayout.ts        # History layout constants
-│       │   ├── inputPaste.ts           # Input paste constants
-│       │   ├── toolUiPreview.ts        # Tool UI preview constants
-│       │   └── toolUiSymbols.ts        # Tool UI symbols
-│       ├── hooks/
-│       │   ├── useAtCompletion.ts      # Completion hook
-│       │   ├── useBlumaSessionRuntime.tsx  # Session runtime hook (v0.1.84+)
-│       │   └── useWorkerProgress.ts    # Worker progress hook
-│       ├── prompts/
-│       │   └── initCommandPrompt.ts    # Init command prompt
-│       ├── theme/
-│       │   ├── blumaTerminal.ts
-│       │   ├── themes.ts               # Theme definitions
-│       │   └── m3Layout.tsx            # Material Design 3 layout
-│       └── utils/
-│           ├── clipboardImage.ts
-│           ├── editToolDiffUtils.ts
-│           ├── expandPreviewHotkey.ts
-│           ├── expandablePreviewStore.ts
-│           ├── formatTurnDurationMs.ts
-│           ├── inlineImageInputLabels.ts
-│           ├── pathDisplay.ts
-│           ├── shellToolNames.ts
-│           ├── slashRegistry.ts
-│           ├── terminalTitle.ts        # Terminal title keeper
-│           ├── toolActionLabels.ts     # Tool action labels
-│           ├── toolDisplayLabels.ts    # Tool display labels
-│           ├── toolInvocationPairing.ts
-│           ├── toolResultStatusStore.ts
-│           ├── update_message.ts
-│           ├── useSimpleInputBuffer.ts
-│           └── vim_engine.ts           # Vim mode engine
-├── main.ts                             # Entry point
-└── types/
-    └── semver-functions.d.ts
-```
-
----
-
-## Testing
 
+### 3. **Release Engineering**
 ```bash
-npm test            # Run all tests
-npm run test:watch  # Watch mode
-npm run test:parallel        # Parallel execution
-npm run test:parallel:fast   # Fast mode with 8 workers
+/release patch          # Auto-detect version bump
+/release minor --dry-run  # Preview release
 ```
 
-### Test Structure
-
-```
-tests/                    # 40+ test files
-├── agent_*.spec.ts       # Agent routing, overlays, coordination
-├── edit_tool.spec.ts     # File editing operations
-├── file_write.spec.ts    # File write operations
-├── sandbox_policy.spec.ts # Tool execution policies
-├── task_runtime.integration.spec.ts # Task lifecycle
-├── context_compression.integration.spec.ts # Context management
-├── hook_registry.spec.ts # Hook system and event tracking
-├── plugin_registry.spec.ts # Plugin loading and lifecycle
-├── session_registry.spec.ts # Session management
-├── session_manager.spec.ts # Session lifecycle
-├── tool_execution_policy.spec.ts # Safe vs dangerous tool decisions
-├── diagnostics.spec.ts   # System diagnostics
-├── runtime_config.spec.ts # Runtime configuration
-├── slash_routing.spec.ts # Slash command routing
-├── subagents_flow.integration.spec.ts # Subagent coordination
-├── prompt_builder.spec.ts # Prompt engineering
-├── token_counter.spec.ts # Token counting
-├── coding_memory.spec.ts # Persistent memory
-├── web_fetch.spec.ts     # Web fetching
-├── workspace_snapshot.spec.ts # Workspace analysis
-├── ui_*.spec.ts(x)       # UI component tests
-├── llm_stream_partial.spec.ts # LLM streaming partial handling
-├── llm_errors.spec.ts    # LLM error handling
-├── context_manager_sanitize.spec.ts # Context sanitization
-├── coordinator-worker-mailbox.integration.spec.ts # Mailbox system
-├── jest-resolver.cjs     # Jest resolver configuration
-└── ...                   # Additional integration and unit tests
+### 4. **Pull Request Creation**
+```bash
+/pr "feat: add new authentication"  # Create PR with conventional commit
 ```
 
 ---
 
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-### Quick Contribution Guide
-
-1. **Fork** the repository
-2. Create a branch: `feat/add-feature` or `fix/bug-description`
-3. Make changes following the style guide
-4. Add/update tests
-5. Ensure build passes: `npm run build && npm test`
-6. Open a Pull Request
-
-### Style Guide
-
-- Use **English** for code, comments, and commits
-- 2-space indentation
-- TypeScript with modern React patterns
-- Follow existing code structure
-
----
-
-## License
+## 📄 License
 
 Apache 2.0 — see [LICENSE](LICENSE) for details.
 
 ---
 
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/nomad-e/bluma-cli/issues)
-- **Documentation**: This README + `docs/` directory
-- **Author & Architect**: Alex Fonseca (conceived and architected BluMa)
-- **npm Package**: [@nomad-e/bluma-cli](https://www.npmjs.com/package/@nomad-e/bluma-cli)
-
-### Runtime Modules
-
-BluMa's runtime layer provides enterprise-grade orchestration:
-
-| Module | Purpose | Key Features |
-|--------|---------|--------------|
-| `task_store.ts` | Task lifecycle | PLANNING → EXECUTION → VERIFICATION phases, persistence |
-| `thread_manager.ts` | Thread management | Multi-thread conversations, context isolation |
-| `hook_registry.ts` | Event system | Tool calls, decisions, state changes |
-| `plugin_registry.ts` | Plugin system | Load from `.bluma/plugins/`, lifecycle management |
-| `session_registry.ts` | Multi-session | Process health monitoring, session isolation |
-| `mailbox_registry.ts` | Communication | Bidirectional coordinator-worker messaging |
-| `worker_context.ts` | Worker isolation | AsyncLocalStorage-based context |
-| `permission_rules.ts` | Permissions | Granular allow/deny rules |
-| `sandbox_policy.ts` | Safety | Safe vs dangerous tool classification |
-| `tool_execution_policy.ts` | Execution rules | Auto-approve, confirm, block decisions |
-| `diagnostics.ts` | System snapshots | Tasks, hooks, plugins, sessions overview |
-| `session_view.ts` | Session monitoring | Log streaming, status display |
-| `native_tool_catalog.ts` | Tool registry | Discovery and metadata |
-| `runtime_config.ts` | Settings | Runtime configuration management |
-| `feature_flags.ts` | Feature gates | Opt-in features via env or settings |
-| `plan_mode_session.ts` | Plan mode | Forces confirmation for edits/writes |
-| `tool_auto_approve.ts` | Auto-approve | Effective approve rules |
-| `tool_orchestration.ts` | Parallel reads | Eligibility for parallel execution |
-| `tool_permission_classifier` | Tool classification | Classify tool invocations |
-| `plugin_runtime.ts` | Plugin execution | Plugin runtime context |
-
-### UI Components
-
-Key UI components that power the rich terminal experience:
-
-| Component | Purpose |
-|-----------|---------|
-| `BlumaSession.tsx` | Main session component with event handling |
-| `BlumaShell.tsx` | Shell container for layout |
-| `BlumaViewport.tsx` | Viewport container for responsive layout |
-| `BlumaTranscript.tsx` | Message transcript display |
-| `BlumaBottomDock.tsx` | Bottom dock for status and controls |
-| `BlumaWorkersOverlay.tsx` | Overlay for worker status |
-| `EditToolDiffPanel.tsx` | Side-by-side diff previews before edits |
-| `ToolResultCard.tsx` | Structured tool output display |
-| `SlashCommands.tsx` | Command palette and help |
-| `StreamingText.tsx` | Live text output with typing effects |
-| `ReasoningDisplay.tsx` | LLM reasoning visualization |
-| `TodoPlanDisplay.tsx` | Task list visualization |
-| `SessionStats.tsx` | Session metrics and status |
-| `AnimatedBorder.tsx` | Visual feedback for active elements |
-| `CollapsibleResult.tsx` | Expandable result sections |
-| `ProgressBar.tsx` | Progress indicators |
-| `AskUserQuestionPrompt.tsx` | Multiple-choice question UI |
-| `ToolInvocationBlock.tsx` | Tool call visualization |
-| `AssistantMessageDisplay.tsx` | Assistant message formatting |
-| `CtrlOToExpand.tsx` | Ctrl+O expansion for previews |
-| `FilePathLink.tsx` | Clickable file path links |
-| `HighlightedCode.tsx` | Syntax highlighted code blocks |
-| `WorkingShimmerText.tsx` | Shimmer text effect for loading states |
+## 👤 Author
+
+**Alex Fonseca** — [@nomad-e](https://github.com/Nomad-e)
 
 ---
 
-<p align="center">
-  <sub>Built with ❤️ by NomadEngenuity</sub>
-</p>
+*BluMa CLI v0.3.1 — Built with TypeScript, React/Ink, and ES modules.*