@nomad-e/bluma-cli 0.11.1 → 0.13.0

package/README.md

@@ -1,573 +1,163 @@
-# BluMa CLI — AI-Powered Agent for Advanced Software Engineering
+# BluMa CLI
 
-![BluMa Background](assets/bg.png)
+![BluMa](assets/bg.png)
 
-[![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)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+[![npm](https://img.shields.io/npm/v/@nomad-e/bluma-cli)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
 
-**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.
-
-**Latest Version:** v0.6.4 (2026-05-10) — Circular dependency resolution, enhanced native tool metadata, improved multi-agent coordination, and professional release engineering.
+**BluMa** é o agente de linha de comando da Nomad-e para engenharia de software: interface terminal, ferramentas nativas, sessões persistentes, memória em disco e integração com o **Factor Router** para modelos. Em modo sandbox, o BluMa cria e faz deploy de apps **FactorAI.sh** dentro de um workspace isolado.
 
 ---
 
-## 🚀 Quick Start
+## Início rápido
 
 ```bash
-# Install globally
 npm install -g @nomad-e/bluma-cli
 
-# Run BluMa (new session)
-bluma
+export FACTOR_ROUTER_URL=https://seu-factor-router/v1
+export FACTOR_ROUTER_KEY=sua-chave
+
+bluma                    # nova sessão
+bluma resume             # retomar (menu)
+bluma resume <session_id>
+```
 
-# Resume a previous session
-bluma resume {session_id}
+**Desenvolvimento local:**
 
-# Or run from source
+```bash
+git clone https://github.com/Nomad-e/bluma-cli.git
+cd bluma-cli
 npm install
+cp .env.example .env
 npm run build
 npm start
 ```
 
 ---
 
-## ✨ 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 file-based communication** between coordinator and workers
-  - **list_mailbox_messages**: Read progress updates, permission requests, and results
-  - **poll_mailbox**: Poll for new messages from workers
-  - **signal_mailbox**: Send ack/nack/progress/heartbeat signals
-  - **File-based storage**: `~/.bluma/mailboxes/{session_id}.in/out/sig` (JSONL format)
-- **Worker Types**: Researchers, implementers, verifiers with specialized roles
-- **Session Registry**: Track and manage agent sessions with lifecycle events
-- **Task Boundary Tracking**: Use `task_boundary` to track orchestration phases (PLANNING, EXECUTION, VERIFICATION)
-
-### 📝 **Slash Commands** (80+ commands)
-Quick access to common operations across 5 categories:
-
-**Session Commands** (25+):
-- `/clear` - Clear current session
-- `/sessions` - List all sessions
-- `/attach` - Attach to existing session
-- `/follow` - Follow session output
-- `/bridge` - Bridge multiple sessions
-- `/status` - Show session status
-- `/logs` - View session logs
-- `/resume` - Resume previous session
-- `/kill` - Terminate session
-- `/compact` - Compress context
-- `/export` - Export session
-- `/summarize` - Summarize conversation
-- `/history` - Command history
-- `/share` - Share session
-- `/copy` - Copy output to clipboard
-- `/commit` - Create git commit
-- `/pr` - Create pull request
-- `/release` - Professional release engineering
-- `/snip` - Extract conversation snippets
-- `/collapse` - Collapse context
-- `/brief` - Generate brief
-- `/undo` - Undo last action
-- `/redo` - Redo undone action
-- `/thread` - Thread management (list/new/resume/fork/rename/archive/delete)
-
-**Inspect Commands** (30+):
-- `/plugins` - List plugins
-- `/plugin` - Plugin details
-- `/diagnostics` - Run diagnostics
-- `/permissions` - Show permissions
-- `/features` - List features
-- `/hooks` - Hook registry
-- `/model` - Model info
-- `/effort` - Effort estimation
-- `/style` - Code style
-- `/sandbox` - Sandbox status
-- `/worktree` - Worktree info
-- `/statusline` - Status line config
-- `/skills` - List skills
-- `/tools` - List tools
-- `/mcp` - MCP resources
-- `/debug-workers` - Worker debug
-- `/cost` - Cost tracking
-- `/memory` - Memory usage
-- `/stats` - Session stats
-- `/theme` - Theme config
-- `/keybindings` - Key bindings
-- `/vim` - Vim mode
-- `/ctx` - Context inspector
-- `/dream` - Dream engine status
-- `/diff` - Show recent changes
-- `/editor` - Open in editor
-- `/config` - Runtime config
-- `/file` - File operations
-- `/search` - Search codebase
-- `/context` - Context management
-- `/token` - Token usage
-- `/settings` - Runtime settings
-- `/alias` - Manage aliases
-- `/macro` - Execute macros
-- `/thread stats` - Thread statistics
-
-**Agent Commands** (15+):
-- `/agent` - Agent info
-- `/agents` - List agents
-- `/img` / `/image` - Image handling
-- `/init` - Initialize project
-- `/review` - Code review
-- `/explain` - Explain code
-- `/fix` - Fix errors
-- `/debug` - Debug issues
-- `/bug` - Report bug
-- `/test` - Run tests
-- `/optimize` - Optimize code
-- `/refactor` - Refactor code
-- `/document` - Generate docs
-- `/chat` - Chat mode
-- `/code` - Code mode
-- `/terminal` - Terminal placeholder
-- `/template` - Create from template
-
-**Input Methods**:
-- `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** (6 skills)
-Extendable expertise modules with **progressive disclosure** — load only when needed:
-
-**Available Skills:**
-- **git-commit**: Conventional commits automation with BluMa watermark
-- **git-pr**: Pull request creation and management (descriptions, reviewers, draft mode)
-- **git-release**: Full release engineering (version bumps, changelog, tags, npm publish, GitHub releases)
-- **pdf**: PDF generation and manipulation (reports, merge, forms, OCR)
-- **xlsx**: Spreadsheet processing (create, edit, formulas, charting, cleaning)
-- **skill-creator**: Create custom skills
-
-**How Skills Work:**
-1. **Discovery**: Skills loaded from `dist/config/skills/`, `{cwd}/.bluma/skills/`, `~/.bluma/skills/`
-2. **Progressive Disclosure**: 
-   - Level 1: One-line description (always visible)
-   - Level 2: Full instructions (loaded on activation)
-   - Level 3: References and scripts (loaded on demand)
-3. **Triggering**: Agent auto-detects when to load skills based on task context
-4. **Priority**: Native > Project > Global (native skills cannot be overridden)
-
-**Create Custom Skills:**
-See [docs/SKILLS.md](docs/SKILLS.md) for complete guide on authoring 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
-- **Parallel tests**: Up to 8 workers for faster test execution
-- **Native modules**: Rust-based clipboard and layout engine for critical paths
-
-### 🔌 **Hooks & Plugins**
-Extensible architecture with hook registry and plugin system:
-
-- **Hook Registry**: Execute custom scripts on events (pre-commit, post-build, etc.)
-- **Plugin System**: Extend BluMa with custom plugins
-- **Event-driven**: Hooks triggered by tool execution, session events, and lifecycle hooks
-
-See [docs/BLUMA_DEVELOPER_GUIDE.md](docs/BLUMA_DEVELOPER_GUIDE.md) for plugin development.
-
-### 🔌 **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
-
-### 🦀 **Native Modules** (Rust)
-High-performance native extensions for critical operations:
-
-- **bluma-clipboard**: Cross-platform clipboard with image support
-  - Built with Rust (arboard crate)
-  - No dependencies on wl-paste/xclip
-  - Native image reading for terminal paste
-- **yoga-layout**: High-performance layout engine for Ink
-  - Facebook's Yoga layout library
-  - Optimized for terminal UI rendering
-
-### 📦 **VS Code Extension**
-Full BluMa capabilities integrated into VS Code:
-
-- **Chat Panel**: Interactive chat interface with full BluMa capabilities
-- **Session Sync**: Real-time synchronization with terminal sessions
-- **Image Support**: Paste and view images directly in VS Code
-- **File Integration**: Open and edit files from within the chat
-- **Streaming**: Real-time response streaming with markdown rendering
-
-See [vscode-extension/README.md](vscode-extension/README.md) for setup instructions.
+## Funcionalidades
 
----
+### Interface terminal
 
-## 🏗️ Architecture
+- Chat com streaming, raciocínio do modelo e execução de ferramentas
+- Histórico e retoma de sessões
+- Comandos `/` para sessão, git, memória, sandbox, inspeção e mais
+- Modos **local** e **sandbox** (permissões e workspace)
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      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      │
-└─────────────────────────────────────────────────────────────┘
-```
+### Modelos (Factor Router)
 
-### Modular Tool Architecture
+O BluMa fala com o Factor Router via API OpenAI-compatible. Configuração:
 
-Each tool in `src/app/agent/tools/` follows a consistent structure:
+| Variável | Descrição |
+|----------|-----------|
+| `FACTOR_ROUTER_URL` | URL base do router (ex. `https://…/v1`) |
+| `FACTOR_ROUTER_KEY` | Chave de autenticação |
 
-```
-ToolName/
-├── index.ts           # Public API exports
-├── ToolName.ts        # Core implementation logic
-├── UI.tsx             # React/Ink UI component
-└── types.ts           # Type definitions
-```
+O router escolhe o modelo; não precisas de configurar endpoints de LLM no BluMa além destas duas variáveis.
 
-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)
-  - **bluma-clipboard**: Cross-platform clipboard with image support
-  - **yoga-layout**: High-performance layout engine for Ink
-- **`vscode-extension/`**: VS Code extension for chat integration
-  - Chat panel with full BluMa capabilities
-  - Real-time session sync
-  - Image and file support
-
----
+### Memória
 
-## 📋 Configuration
+O BluMa guarda contexto persistente em ficheiros sob `~/.bluma`:
 
-### Environment Variables
+| Tipo | Onde | Para quê |
+|------|------|----------|
+| **Auto-memory** | `projects/<projeto>/memory/` (`MEMORY.md` e tópicos `.md`) | Preferências e factos do projeto; entra no prompt; o agente atualiza com as tools de ficheiro |
+| **Extração automática** | Mesma pasta | Após cada turno, um subagente pode consolidar notas (`BLUMA_DISABLE_EXTRACT_MEMORIES=1` desliga) |
+| **Session memory** | `<sessionId>/session-memory/summary.md` | Resumo da conversa atual |
+| **BLUMA.md** | Raiz do projeto ou `~/.bluma` | Instruções e regras do projeto |
+| **Coding memory** | Ficheiro dedicado | Notas de código via tool `coding_memory` |
+| **Agent memory** | `.bluma/agent-memory/` | Memória por perfil de agente (user / project / local) |
 
-Create a `.env` file in your project root:
+Flags úteis: `BLUMA_DISABLE_AUTO_MEMORY`, `BLUMA_DISABLE_SESSION_MEMORY`, `BLUMA_HOME`.
 
-```bash
-# Required for AI features
-FACTOR_ROUTER_KEY=your_key
-FACTOR_ROUTER_URL=https://api.factorai.sh
+### Sandbox e FactorAI.sh
 
-# Optional: MCP Server
-MCP_SSE_URL=http://localhost:3000/sse
+Com sandbox ativo (`BLUMA_SANDBOX`), o BluMa corre no workspace isolado com tools dedicadas:
 
-# Optional: FactorAI Sandbox
-FACTORAI_BASE_URL=http://localhost:8080
-FACTORAI_API_KEY=your-sandbox-key
-```
+- Scaffold Next.js, deploy, edição incremental (`apply_app_changes`), estado e redeploy
+- Deploy empacota o projeto em ZIP no próprio Node (sem depender de `zip` no sistema)
+- Cada `session_id` mantém o seu workspace — uma app por sessão de chat
+- Evento `factor-sh-url-app` com o URL da app publicada
 
-### Runtime Modes
+O orchestrator (ex. sandbox-api) injeta `SEVERINO_URL`, `FACTORAI_BASE_URL`, chaves de API e `BLUMA_SANDBOX_WORKSPACE`.
 
-BluMa supports different permission modes:
+### Modo agente (headless)
 
-- **Local Mode**: Auto-approve safe operations
-- **Sandbox Mode**: Require confirmation for write/execute operations
+Para automação ou gateway (JSON in / JSONL out):
 
-Set via environment or runtime config:
 ```bash
-BLUMA_PERMISSION_MODE=sandbox
+bluma agent --input-file request.json
 ```
 
----
+Eventos: `log`, `backend_message`, `result` (inclui URL da app quando há deploy). Scripts de teste em `scripts/`.
 
-## 🛠️ Development
+### Ferramentas e skills
 
-### Prerequisites
+- **Tools nativas**: ficheiros, shell, planeamento, pesquisa, MCP, multi-agente, FactorAI em sandbox — ver `src/app/agent/tools/`
+- **Skills embutidas**: `factorai-sh`, `git-commit`, `git-pr`, `git-release`, `pdf`, `xlsx`, `skill-creator`
+- Skills extra: `.bluma/skills/`, `~/.bluma/skills/`
 
-- Node.js >= 20
-- npm >= 9
+### Multi-agente
 
-### Setup
+Coordenador, workers e mailbox em `~/.bluma/mailboxes/` (`spawn_agent`, `wait_agent`, `send_message`, …).
 
-```bash
-# Clone the repository
-git clone https://github.com/Nomad-e/bluma-cli.git
-cd bluma-cli
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Start BluMa
-npm start
-```
-
-### Scripts
-
-| 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 |
-
-### Testing
+### Integrações
 
-```bash
-# Run all tests
-npm test
-
-# Run specific test file
-npm test -- tests/tool_invocation.spec.ts
-
-# Watch mode
-npm run test:watch
-
-# Parallel tests (faster)
-npm run test:parallel:fast
-```
-
-### Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
-
----
-
-## 📚 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
+- **MCP** — `~/.bluma/bluma-mcp.json`
+- **VS Code** — extensão em `vscode-extension/`
+- **Native** — clipboard e layout (`native/`)
 
 ---
 
-## 🎯 Use Cases
-
-### 1. **Code Analysis & Refactoring**
-```bash
-# Ask BluMa to analyze your codebase
-bluma
-
-# Then use slash commands
-/explain src/app/agent/core/prompt_builder.ts
-/refactor src/utils/helpers.ts
-/fix src/components/Button.tsx
-```
-
-### 2. **Multi-Agent Development**
-```bash
-# 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
-```
+## Configuração
 
-### 3. **Release Engineering**
-```bash
-/release patch          # Auto-detect version bump
-/release minor --dry-run  # Preview release
-```
+Exemplo mínimo (`.env`):
 
-### 4. **Pull Request Creation**
 ```bash
-/pr "feat: add new authentication"  # Create PR with conventional commit
+FACTOR_ROUTER_URL=https://your-factor-router.example/v1
+FACTOR_ROUTER_KEY=your-key
 ```
 
-### 5. **Web Integration**
-```bash
-# Use the embeddable React chat widget
-import { useChatWidget } from '@nomad-e/bluma-cli/chat-widget';
+Opcionais comuns: `BLUMA_PERMISSION_MODE`, `BLUMA_HOME`, flags de memória, URLs FactorAI para testes de deploy local, `MCP_SSE_URL`. Ver [`.env.example`](.env.example).
 
-// Embed BluMa capabilities in your web app
-const { messages, streamResponse } = useChatWidget();
-```
+### Sessões
 
-### 6. **VS Code Integration**
-```bash
-# Install the VS Code extension
-# Access full BluMa capabilities from within VS Code
-- Chat panel with session sync
-- Image and file support
-- Real-time streaming
-```
+- Índice em SQLite + histórico em disco (`~/.bluma`)
+- `bluma resume` — menu ou ID
+- `bluma sessions` / `bluma logs <id>` — agentes em background
 
 ---
 
-## 📄 License
-
-Apache 2.0 — see [LICENSE](LICENSE) for details.
-
----
+## Desenvolvimento
 
-## 👤 Author
+| Comando | Descrição |
+|---------|-----------|
+| `npm run build` | Compila para `dist/` |
+| `npm run build:all` | Native (Rust) + build |
+| `npm start` | Build e UI |
+| `npm test` | Testes |
+| `npm run lint` | ESLint |
 
-**Alex Fonseca** — [@nomad-e](https://github.com/Nomad-e)
+**Requisitos:** Node.js ≥ 20.
 
 ---
 
-## 📰 Changelog
+## Documentação
 
-See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
-
-### What's New in v0.6.4 (2026-05-10)
-
-**Major Changes:**
-- **Circular Dependency Resolution**: Fixed 'getNativeToolMetadata is not defined' error in tool metadata
-- **Enhanced Native Tool Metadata**: Improved tool descriptions and metadata clarity across all 45+ tools
-- **Improved Multi-Agent Coordination**: Better coordinator-worker communication and task tracking
-- **Permission Mode Enhancement**: Full mode enabled for auto-approve of all tools
-
-**Improvements:**
-- Streamlined tool guidance in prompts
-- Better error handling and user-friendly error messages
-- Enhanced session persistence on LLM errors
-- Improved worker registration for UI visibility
-
-**Fixes:**
-- Resolved circular dependency in tool metadata (prompt → tools → prompt cycle)
-- Fixed worker registration for UI visibility in task_boundary tracking
-- Improved session persistence on LLM errors
+| Documento | Conteúdo |
+|-----------|----------|
+| [CHANGELOG.md](CHANGELOG.md) | Versões |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Como contribuir |
+| [docs/BLUMA_DEVELOPER_GUIDE.md](docs/BLUMA_DEVELOPER_GUIDE.md) | Guia de desenvolvimento |
+| [docs/SKILLS.md](docs/SKILLS.md) | Skills |
+| [docs/FACTOR_ROUTER_TURNS.md](docs/FACTOR_ROUTER_TURNS.md) | Turnos no router |
+| [docs/MAILBOX_IPC.md](docs/MAILBOX_IPC.md) | Mailbox |
 
 ---
 
-### What's New in v0.6.2 (2026-05-09)
+## Licença
 
-**Major Features:**
-- **Modular Tool Architecture**: All 45+ tools now have dedicated directories with separate logic, UI, and types
-- **Native Clipboard Support**: Rust-based clipboard implementation for cross-platform image handling
-- **Thread Management**: Full thread lifecycle with create, resume, fork, rename, archive, delete operations
-- **Enhanced Multi-Agent Orchestration**: Improved coordinator-worker communication with bidirectional mailbox IPC
-- **Chat Widget**: Embeddable React chat component for web integration
-
-**Improvements:**
-- 27 new slash commands for session management, inspection, and agent control
-- Performance optimizations in UI rendering and context management
-- Enhanced sandbox security with improved policy enforcement
-- Better error handling and user-friendly error messages
-
-**Fixes:**
-- Resolved circular dependency in tool metadata
-- Fixed worker registration for UI visibility
-- Improved session persistence on LLM errors
-
----
+Apache 2.0 — [LICENSE](LICENSE)
 
-*BluMa CLI v0.6.4 — Built with TypeScript, React 19, Ink, and ES modules.*
+**Alex Fonseca** · [Nomad-e](https://github.com/Nomad-e)