npm - @nomad-e/bluma-cli - Versions diffs - 0.1.41 → 0.1.43 - Mend

@nomad-e/bluma-cli 0.1.41 → 0.1.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +545 -1057
package/dist/config/native_tools.json +53 -12
package/dist/main.js +4058 -2671
package/package.json +1 -2

package/README.md CHANGED Viewed

@@ -1,1216 +1,704 @@
-# BluMa — Base Language Unit · Model Agent
+# BluMa CLI — Base Language Unit · Model Agent
-[![npm version](https://img.shields.io/npm/v/bluma.svg?style=flat-square)](https://www.npmjs.com/package/bluma)
+[![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)
-[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://shields.io/)
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
-<p align="center">
-  <img src="https://pharmaseedevsa.blob.core.windows.net/pharmassee-dev-storage/bluma.png" alt="Screenshot BluMa CLI" width="1000"/>
-</p>
-BluMa is a CLI-based model agent responsible for language-level code generation, refactoring and semantic transformations in the Factor AI stack. The project is a conversational assistant that interacts via terminal (CLI), built with React/Ink, supporting smart agents (LLM via FactorRouter), tool execution, persistent history, session management, coding memory, and extensibility through external plugins/tools and skills.
+**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, and extensible tools/skills architecture.
 ---
 ## Table of Contents
 - [Overview](#overview)
-- [Why BluMa?](#why-bluma)
 - [Key Features](#key-features)
 - [Requirements](#requirements)
-- [Quick Start](#quick-start)
 - [Installation](#installation)
-- [Screenshots](#screenshots)
-- [Usage](#usage)
-  - [Examples](#-usage-examples)
-- [Sandbox / Agent Mode](#sandbox-agent-mode)
-- [Configuration and Environment Variables](#configuration-and-environment-variables)
-- [Development and Build](#development-and-build)
-- [Extensibility: Tools, Skills and Plugins](#extensibility-tools-and-plugins)
-- [Tests](#tests)
-- [Coding Memory](#coding-memory)
-- [Limitations / Next Steps](#️-limitations--next-steps)
-- [Security Notes](#-security-notes)
-- [Tech Stack Overview](#stack)
-- [Contributing](#-contributing)
+- [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)
 ---
-## <a name="overview"></a>Overview
-BluMa is a CLI-based model agent responsible for language-level code generation, refactoring and semantic transformations in the Factor AI stack. It is a modular conversational agent and task automation framework focused on advanced software engineering workflows. It runs entirely in the terminal using React (via Ink) for a rich interactive UI, and is architected around a **UI layer** (`main.ts` + `App.tsx`) and an **agent layer** (`Agent` orchestrator + `BluMaAgent` core). It enables LLM-powered automation, documentation, refactoring, running complex development tasks, and integrating with both native and external tools. The system features persistent sessions, contextual reasoning, smart feedback, and an interactive confirmation system for controlled execution.
+## 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, and session management
+- **Tool Layer**: 18 native tools + MCP SDK integration for external tools
+The agent maintains persistent conversation history, workspace snapshots, and coding memory across sessions.
 ---
-## Why BluMa?
-BluMa stands out as the premier CLI-based model agent for software engineering:
+## Key Features
-- **Language-Level Expertise:** Specializes in code generation, refactoring, and semantic transformations, making it ideal for Factor AI stack development.
-- **Conversational Automation:** Interact naturally with an AI that understands context, history, and your project's needs.
-- **Secure & Controlled:** Built-in confirmations and whitelists ensure safe execution of powerful tools.
-- **Extensible & Modular:** Easily add tools and plugins to adapt to your workflow.
-- **Real-Time Collaboration:** Live overlays allow pair-programming style guidance during processing.
+### 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`)
-Choose BluMa for intelligent, efficient, and collaborative software engineering automation.
+### 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
+- **Diagnostics**: Real-time system snapshot (tasks, hooks, plugins, sessions)
+- **Tool Execution Policy**: Intelligent decisions based on sandbox mode and safety
----
+### Tools & Skills
+- **25+ Native Tools**: File operations, search, shell commands, web fetch, agent coordination
+- **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
-## <a name="key-features"></a>Key Features
-- **Rich CLI interface** using React/Ink 5, with interactive prompts and custom components.
-- **Session management:** automatic persistence of conversation and tool history via files.
-- **Central agent (LLM):** orchestrated by FactorRouter, enabling natural language-driven automation.
-- **Tool invocation:** native and via MCP SDK for running commands, code manipulation, file management, and more.
-- **Dynamic prompts:** builds live conversational context, behavioral rules, and technical history.
-- **Smart feedback component** with technical suggestions and checks.
-- **ConfirmPrompt & Workflow Decision:** confirmations for sensitive operations, edit/code previews, always-accepted tool whitelists.
-- **Coding Memory:** persistent notes about the codebase, decisions, and context that survive across sessions.
-- **Skills System:** pluggable knowledge modules for domain-specific expertise (git, testing, docker, etc.).
-- **Extensible:** easily add new tools, skills, or integrate external SDK/plugins.
+### UI Components
+- **Slash Commands**: 20+ built-in commands (`/help`, `/model`, `/tasks`, `/plugins`, 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
 ---
-## <a name="requirements"></a>Requirements
-- Node.js >= 18
-- npm >= 9
-- FactorRouter API key (get one from your FactorRouter admin)
+## Requirements
----
+- **Node.js**: >= 20
+- **npm**: >= 9
+- **FactorRouter**: API key and URL for LLM backend
-## <a name="installation"></a>Installation
+---
-### Recommended: Global Installation
+## Installation
-> **Important:** It is recommended to install BluMa globally so the `bluma` command works in any terminal.
+### Global Installation (Recommended)
 ```bash
 npm install -g @nomad-e/bluma-cli
 ```
-If you get permission errors, EXAMPLES:
-  - **Linux:** Run as administrator using `sudo`:
-    ```bash
-    sudo npm install -g @nomad-e/bluma-cli
-    ```
-  - **Windows:** Open Command Prompt/Terminal as Administrator and repeat the command
-> **macOS:** After global installation, **always run the `bluma` command without sudo**:
->
-> ```bash
-> bluma
-> ```
-> Running with sudo may cause permission problems, environment variable issues, and npm cache ownership problems.
-> Only use sudo to install, never to run the CLI.
-### Setting Up Environment Variables
-For BluMa CLI to operate, set the following environment variables globally in your system.
-**Required:**
-- `FACTOR_ROUTER_KEY` — API key from your FactorRouter admin (e.g., `sk-fai-...`)
-- `FACTOR_ROUTER_URL` — FactorRouter gateway base URL (e.g., `http://host:8003/router-api`)
-#### How to set environment variables globally:
-**Linux/macOS:**
-Add to your `~/.bashrc`, `~/.zshrc`, or equivalent:
-```sh
-export FACTOR_ROUTER_KEY="your_factor_router_key"
-export FACTOR_ROUTER_URL="http://host:8003/router-api"
-```
-Then run:
-```sh
-source ~/.bashrc # or whichever file you edited
+**Linux/macOS** (if permission errors):
+```bash
+sudo npm install -g @nomad-e/bluma-cli
 ```
-**Windows (CMD):**
-```cmd
-setx FACTOR_ROUTER_KEY "your_factor_router_key"
-setx FACTOR_ROUTER_URL "http://host:8003/router-api"
-```
-(Only needs to be run once per variable. Restart the terminal after.)
+> **macOS Note**: After installation, run `bluma` **without** sudo to avoid permission issues.
-**Windows (PowerShell):**
-```powershell
-[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_KEY", "your_factor_router_key", "Machine")
-[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_URL", "http://host:8003/router-api", "Machine")
-```
+### Local Development
-### ℹ️ Global Installation of npm Packages in PowerShell (Windows)
-When installing BluMa (or any npm package globally) in PowerShell, you might see:
-```
-Do you want to change the execution policy?
-[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):
+```bash
+git clone <repository-url>
+cd bluma-cli
+npm install
+npm run build
 ```
-👉 **Choose `Y` (Yes) or `A` (Yes to All)**. This will change the execution policy to **RemoteSigned** (only scripts from the internet need a digital signature).
-- This is safe for devs: Windows only requires digital signatures for web scripts—local scripts, from npm, work normally.
-- Read more: [About Execution Policies (Microsoft Docs)](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/about/about_execution_policies)
+### Environment Setup
-**To restore the default policy after installation, run:**
-```powershell
-Set-ExecutionPolicy Default
-```
+Set these environment variables globally:
-> **Tip:** Restart your terminal to ensure the variables are loaded 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
+```
-## <a name="how-to-run"></a>How to Run
-```bash
-npm start
-# Or directly using the built binary
-npx bluma
+**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")
 ```
-==> The CLI will open an interactive terminal interface for dialogue, command execution, and engineering workflow automation.
 ---
 ## Quick Start
-Get up and running with BluMa in minutes:
-1. **Install BluMa:**
-   ```bash
-   npm install -g @nomad-e/bluma-cli
-   ```
-2. **Configure Environment:**
-   Set your FactorRouter API key and URL (see [Configuration](#configuration-and-environment-variables)).
-3. **Launch BluMa:**
-   ```bash
-   bluma
-   ```
-4. **Interact:**
-   Start a conversation! Try commands like "Help me refactor this code" or "Run tests for my project."
-For full installation details, see [Installation](#installation).
----
-## <a name="sandbox-agent-mode"></a>Sandbox / Agent Mode
-BluMa was designed primarily as an **interactive CLI agent**, but it also exposes a **non-interactive “agent mode”** for integration with orchestrators such as AGIWeb Sandbox or other backends.
-### Why Agent Mode Exists
-- Allow external systems (e.g. a Sandbox API, another agent like Severino, CI pipelines) to:
-  - Send a **single JSON payload** describing a task (`action` + `context`).
-  - Receive **only structured JSON Lines (JSONL)** as output (no TUI).
-  - Orchestrate BluMa as a **sub-agent** inside a larger architecture.
-- Guarantee:
-  - Deterministic, parseable logs.
-  - A single, well-defined `result` event per execution.
-  - No interactive prompts or confirmation flows when running in sandbox.
-### How to Call BluMa in Agent Mode
-Agent mode is activated by passing the `agent` subcommand and piping a JSON envelope to stdin:
 ```bash
-BLUMA_SANDBOX=true \
-BLUMA_SANDBOX_NAME="sandbox-api" \
-node dist/main.js agent --input - << 'EOF'
-{
-  "message_id": "job-123",
-  "from_agent": "sandbox-api",
-  "to_agent": "bluma",
-  "action": "echo_test",
-  "context": {
-    "user_request": "Diz-me em uma frase o que é o bluma-cli."
-  },
-  "metadata": {
-    "sandbox": true
-  }
-}
-EOF
-```
-You can also use `--input-file` instead of stdin:
+# Launch BluMa
+bluma
-```bash
-BLUMA_SANDBOX=true BLUMA_SANDBOX_NAME="sandbox-api" \
-node dist/main.js agent --input-file ./payload.json
+# Or from local development
+npm start
 ```
-### Input Envelope Contract
-The JSON payload must follow this envelope:
+### First Interaction
-```json
-{
-  "session_id": "conv-uuid-stable",  // Recomendado: mesma sessão entre jobs (histórico + workspace)
-  "message_id": "job-123",           // Opcional mas recomendado
-  "from_agent": "sandbox-api",
-  "to_agent": "bluma",
-  "action": "generate_app",
-  "context": {
-    "user_request": "Criar dashboard de vendas",
-    "erp_models": ["sale.order"],
-    "permissions": ["sales"]
-  },
-  "user_context": {
-    "userId": "13",
-    "userName": "Nome",
-    "userEmail": "user@example.com",
-    "companyId": "4",
-    "companyName": "Empresa",
-    "conversationId": null
-  },
-  "metadata": {
-    "sandbox": true,
-    "caller": "agiweb"
-  }
-}
 ```
-O campo **`user_context`** (opcional) é enviado ao FactorRouter nos headers `X-User-*` / `X-Company-*` para custos e auditoria. `context.user_request` (primeiros 300 caracteres) vai em `X-User-Message` (URL-encoded).
-Internally, BluMa will:
-- Initialize the agent with a dedicated `eventBus`.
-- Build a single user message containing this JSON.
-- Run the normal reasoning + tool flow, but:
-  - **Without** rendering the Ink UI.
-  - **Without** asking for user confirmations when `BLUMA_SANDBOX=true`.
-### Output: JSON Lines (JSONL)
-In agent mode, BluMa writes **one JSON object per line** to stdout.
-Typical events:
-```json
-{"event_type":"log","level":"info","message":"Starting agent mode execution","timestamp":"...","data":{"message_id":"job-123","action":"echo_test","from_agent":"sandbox-api","to_agent":"bluma"}}
-{"event_type":"action_status","timestamp":"...","payload":{"action":"Thinking"}}
-{"event_type":"backend_message","backend_type":"tool_call","timestamp":"...","payload":{"type":"tool_call","tool_name":"read_file_lines","arguments":{...}}}
-{"event_type":"backend_message","backend_type":"tool_result","timestamp":"...","payload":{"type":"tool_result","tool_name":"read_file_lines","result":"{ ... }"}}
-...
-{"event_type":"result","status":"success","timestamp":"...","data":{"message_id":"job-123","action":"echo_test","last_assistant_message":"...","reasoning":null}}
+> 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
 ```
-Key points:
-- **`event_type: "backend_message"`** mirrors what the CLI UI would receive (`tool_call`, `tool_result`, `reasoning`, `done`, etc.).
-- **`event_type: "action_status"`** surfaces high-level states (Thinking, Reading, Executing, Waiting, Responding).
-- **`event_type: "result"`** appears **exactly once** per execution and contains:
-  - `message_id`: propagated from the input.
-  - `action`: propagated from the input.
-  - `last_assistant_message`: the final message BluMa would send to a human (content of the `message` tool).
-  - `reasoning`: concatenated reasoning text when available (can be `null`).
-  - `attachments`: array of absolute file paths to deliverables generated by the agent (can be `null`).
-### Artifact Delivery & File Lifecycle
-BluMa in sandbox mode follows a strict file lifecycle to ensure deliverables are properly produced and delivered to the orchestrator:
-**Workflow:**
-1. **Analyse** — Parse the job request and plan what to produce.
-2. **Script** — Write a Python script (e.g. `_task_runner.py`) to generate deliverables.
-3. **Execute** — Run the script via `shell_command` (`python _task_runner.py`).
-4. **Deliver** — Place all final documents in `./artifacts/` and include their **absolute paths** in the `attachments` field of the final `message` tool call.
-5. **Clean up** — Delete temporary scripts and intermediate files, leaving only deliverables in `./artifacts/`.
-**What goes in `attachments`:**
-- Reports, CSVs, PDFs, spreadsheets, ZIPs, JSON exports, images — any file the user should consume.
-- Always **absolute paths** (e.g. `/app/artifacts/sales_report.pdf`).
+---
-**What does NOT go in `attachments`:**
-- Scripts (`.py`, `.sh`, `.ipynb`) used to generate the deliverables.
-- Temporary or intermediate files (`.tmp`, `.log`, working data).
+## Configuration
-**Result event with attachments example:**
+### Runtime Settings (`~/.bluma/settings.json`)
 ```json
 {
-  "event_type": "result",
-  "status": "success",
-  "data": {
-    "message_id": "job-456",
-    "action": "generate_report",
-    "last_assistant_message": "Relatório de vendas gerado com sucesso.",
-    "reasoning": "...",
-    "attachments": [
-      "/app/artifacts/sales_report_2026_Q1.pdf",
-      "/app/artifacts/sales_data_2026_Q1.csv"
-    ]
-  }
+  "model": "gpt-4o",
+  "reasoningEffort": "medium",
+  "outputStyle": "concise",
+  "sandboxMode": "confirm",
+  "alwaysAcceptTools": ["read_file_lines", "grep_search"],
+  "theme": "default"
 }
 ```
-The orchestrator uses the `attachments` array to deliver files to the end user. Jobs that omit this field cannot have their deliverables forwarded.
-### Sandbox Behaviour and Permissions
-When `BLUMA_SANDBOX=true`:
+| Setting | Values | Description |
+|---------|--------|-------------|
+| `model` | `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4-20250514` | LLM model |
+| `reasoningEffort` | `low`, `medium`, `high` | Reasoning depth |
+| `outputStyle` | `concise`, `balanced`, `verbose` | Response style |
+| `sandboxMode` | `confirm`, `auto`, `strict` | Tool execution policy |
-- The **system prompt** is augmented with sandbox-specific context, instructing the model that:
-  - It is running **inside a non-interactive sandbox**.
-  - All inputs come from JSON payloads, not from a human on a terminal.
-  - Outputs must be deterministic, concise and suitable for machine parsing.
-  - It must follow a strict file lifecycle: produce → deliver → clean up.
-- Tool execution:
-  - All tools are considered **auto-approved** in sandbox mode (no confirmation prompts from the user).
-  - This allows the orchestrator to let BluMa freely call `shell_command`, `command_status`, `coding_memory`, etc., while still observing every step through JSONL logs.
-- Security:
-  - BluMa is **forbidden** from dumping, enumerating or exposing environment variables, API keys, tokens or any infrastructure details.
-  - Even if the user explicitly asks for env vars, BluMa will refuse and describe capabilities at a high level instead.
-  - This is a zero-tolerance policy — leaking env vars in a shared sandbox is a critical security breach.
+### Directory Structure
-### Example: Generating a Report
-```bash
-BLUMA_SANDBOX=true BLUMA_SANDBOX_NAME="sandbox-api" \
-node dist/main.js agent --input - << 'EOF'
-{
-  "message_id": "job-report-001",
-  "from_agent": "sandbox-api",
-  "to_agent": "bluma",
-  "action": "generate_report",
-  "context": {
-    "user_request": "Gera um relatório PDF com os dados de vendas do Q1 2026.",
-    "data_source": "sales_q1_2026.csv"
-  },
-  "metadata": {
-    "sandbox": true
-  }
-}
-EOF
 ```
-BluMa will typically:
-1. Write a Python script to read the CSV and generate a PDF using reportlab/matplotlib.
-2. Execute the script, placing the PDF in `./artifacts/`.
-3. Return a `message` with `attachments: ["/app/artifacts/sales_q1_2026_report.pdf"]`.
-4. Clean up the temporary script.
-5. Emit the final `result` event:
-```json
-{
-  "event_type": "result",
-  "status": "success",
-  "data": {
-    "message_id": "job-report-001",
-    "action": "generate_report",
-    "last_assistant_message": "Relatório PDF gerado com sucesso com os dados de vendas Q1 2026.",
-    "reasoning": "...",
-    "attachments": ["/app/artifacts/sales_q1_2026_report.pdf"]
-  }
-}
+~/.bluma/
+├── settings.json          # Runtime configuration
+├── coding_memory.json     # Persistent coding notes
+├── artifacts/             # Saved plans and documents
+├── plugins/               # Global plugins
+└── sessions/              # Session history
 ```
-This makes it straightforward for an API layer (AGIWeb Sandbox, Severino, etc.) to:
-- Orchestrate BluMa as a sub-agent.
-- Log all intermediate steps.
-- **Deliver generated files** to end users via the `attachments` array.
-- Present only the final `last_assistant_message` (and optionally `reasoning`) to the end user.
 ---
-## Screenshots
-Here's BluMa in action:
+## Architecture
-![BluMa CLI Interface](https://pharmaseedevsa.blob.core.windows.net/pharmassee-dev-storage/bluma.png)
-*BluMa's interactive CLI interface for conversational software engineering.*
----
-## <a name="project-structure"></a>Project Structure
-```
-bluma-cli/
-├── package.json               # npm project config & dependencies
-├── tsconfig.json              # TypeScript configuration
-├── babel.config.cjs           # Babel presets for Jest/ESBuild
-├── jest.config.cjs            # Jest test configuration
-├── scripts/
-│   └── build.js               # Build script using esbuild
-├── src/
-│   ├── main.ts                # Entry point (CLI bootstrap & agent mode)
-│   └── app/
-│       ├── agent/             # Agent core & orchestration
-│       │   ├── agent.ts       # Main orchestrator (RouteManager integration)
-│       │   ├── routeManager.ts # Route registration & dispatch
-│       │   ├── bluma/
-│       │   │   └── core/
-│       │   │       └── bluma.ts # Core agent loop & state management
-│       │   ├── config/
-│       │   │   ├── native_tools.json # Native tool definitions
-│       │   │   └── skills/    # Built-in skills (git-commit, git-pr, pdf, xlsx, skill-creator)
-│       │   ├── core/
-│       │   │   ├── context-api/ # Context management & token counting
-│       │   │   │   ├── context_manager.ts
-│       │   │   │   ├── history_anchor.ts
-│       │   │   │   └── token_counter.ts
-│       │   │   ├── llm/       # LLM client (FactorRouter/OpenAI SDK)
-│       │   │   │   ├── llm.ts
-│       │   │   │   └── tool_call_normalizer.ts
-│       │   │   └── prompt/    # System prompt builder
-│       │   │       └── prompt_builder.ts
-│       │   ├── feedback/
-│       │   │   └── feedback_system.ts # Smart feedback & suggestions
-│       │   ├── session_manager/
-│       │   │   └── session_manager.ts # Session persistence & history
-│       │   ├── skills/
-│       │   │   └── skill_loader.ts # Pluggable skill system
-│       │   ├── subagents/     # Sub-agent implementations
-│       │   │   ├── registry.ts # Sub-agent registration & lookup
-│       │   │   ├── types.ts
-│       │   │   ├── base_llm_subagent.ts
-│       │   │   └── init/      # Init subagent (environment setup)
-│       │   │       ├── init_subagent.ts
-│       │   │       ├── init_system_prompt.ts
-│       │   │       └── contracts.ts
-│       │   ├── tools/
-│       │   │   ├── mcp/
-│       │   │   │   └── mcp_client.ts # MCP SDK integration
-│       │   │   └── natives/   # Native tools (20+ tools)
-│       │   │       ├── shell_command.ts
-│       │   │       ├── edit.ts
-│       │   │       ├── readLines.ts
-│       │   │       ├── ls.ts
-│       │   │       ├── grep_search.ts
-│       │   │       ├── find_by_name.ts
-│       │   │       ├── coding_memory.ts
-│       │   │       ├── load_skill.ts
-│       │   │       ├── message.ts
-│       │   │       ├── todo.ts
-│       │   │       ├── task_boundary.ts
-│       │   │       └── ... (10 more)
-│       │   ├── types/
-│       │   │   └── index.ts   # TypeScript type definitions
-│       │   └── utils/
-│       │       └── update_check.ts # Version update notifications
-│       └── ui/                # Ink/React CLI interface
-│           ├── App.tsx        # Main React component
-│           ├── layout.tsx     # UI layout components
-│           ├── components/    # Reusable UI components (20+)
-│           │   ├── MarkdownRenderer.tsx
-│           │   ├── ToolCallDisplay.tsx
-│           │   ├── ToolResultCard.tsx
-│           │   ├── InputPrompt.tsx
-│           │   ├── ConfirmationPrompt.tsx
-│           │   ├── SessionStats.tsx
-│           │   └── ... (15 more)
-│           ├── hooks/
-│           │   └── useAtCompletion.ts # Autocomplete hook
-│           ├── theme/
-│           │   ├── blumaTerminal.ts
-│           │   └── m3Layout.tsx
-│           ├── utils/
-│           │   ├── slashRegistry.ts
-│           │   ├── terminalTitle.ts
-│           │   └── ... (4 more)
-│           └── Asci/
-│               └── AsciiArt.ts
-├── tests/                     # Test suite (Jest 30)
-│   ├── *.spec.ts              # Unit & integration tests
-│   └── *.spec.tsx             # UI component tests
-├── artifacts/                 # Generated deliverables (runtime)
-└── docs/                      # Documentation
-    ├── SKILLS.md              # Skills system documentation
-    ├── FACTOR_ROUTER_TURNS.md # FactorRouter integration details
-    └── assets/
-        └── bluma.png          # Project logo
 ```
-**Runtime directories** (created on first run):
-- `~/.bluma/sessions/` — Persistent session history
-- `~/.bluma/coding_memory.json` — Long-term coding notes
-- `~/.bluma/skills/` — User-installed skills
-- `~/.bluma/.env` — Optional local environment overrides
----
-## <a name="development-and-build"></a>Development and Build
-- Build is performed using [esbuild](https://esbuild.github.io/) (see scripts/build.js).
-- TS source files are in `src/` and compiled to `dist/`.
-- Use `npm run build` to compile and get the CLI binary ready.
-- Config files are automatically copied to `dist/config`.
-### Main scripts:
-```bash
-npm run build    # Compiles project to dist/
-npm start        # Runs CLI (after build)
-npm run dev      # (If configured, hot-reload/TS watch)
+┌─────────────────────────────────────────────────────────────┐
+│                         UI Layer                            │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
+│  │   App    │ │ Input    │ │ Slash    │ │  ToolResult  │   │
+│  │  (Ink)   │ │ Prompt   │ │ Commands │ │   Display    │   │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘   │
+└───────┼────────────┼────────────┼──────────────┼───────────┘
+        │            │            │              │
+        └────────────┴────────────┴──────────────┘
+                         │
+┌────────────────────────┼────────────────────────────────────┐
+│                   Agent Layer                               │
+│  ┌──────────────┐  ┌──────────┐  ┌──────────────────────┐  │
+│  │    Agent     │  │  BluMa   │  │   RouteManager       │  │
+│  │  Orchestrator│  │  Core    │  │   (FactorRouter)     │  │
+│  └──────┬───────┘  └────┬─────┘  └──────────┬───────────┘  │
+│         │               │                    │              │
+│  ┌──────┴───────┐  ┌────┴────┐  ┌───────────┴──────────┐  │
+│  │ ToolInvoker  │  │  LLM    │  │   PromptBuilder      │  │
+│  │              │  │ Client  │  │   + ContextManager   │  │
+│  └──────────────┘  └─────────┘  └──────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                         │
+┌────────────────────────┼────────────────────────────────────┐
+│                   Runtime Layer                             │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
+│  │TaskStore │ │HookReg.  │ │PluginReg.│ │SessionReg.   │   │
+│  │          │ │          │ │          │ │              │   │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
+│  │Sandbox   │ │ToolExec  │ │Diagnostics│ │SessionView  │   │
+│  │Policy    │ │Policy    │ │           │ │             │   │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                         │
+┌────────────────────────┼────────────────────────────────────┐
+│                    Tools Layer                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │              Native Tools (25+)                      │  │
+│  │  edit_tool, file_write, shell_command, grep_search,  │  │
+│  │  spawn_agent, todo, task_boundary, coding_memory,    │  │
+│  │  search_web, web_fetch, load_skill, ...              │  │
+│  └──────────────────────────────────────────────────────┘  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │              MCP SDK Integration                     │  │
+│  │         External tool servers via MCP                │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
 ```
 ---
-## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools, Skills and Plugins
-### Native Tools (20+ Built-in)
+## Native Tools
+BluMa includes 25+ built-in tools organized by category:
+### File Operations
+| Tool | Description |
+|------|-------------|
+| `edit_tool` | Replace text in files (precise, multi-line) |
+| `file_write` | Create/overwrite entire files |
+| `read_file_lines` | Read specific line ranges |
+| `count_file_lines` | Get file line count |
+| `ls_tool` | List directories with filtering |
+| `find_by_name` | Glob-based file search |
+| `grep_search` | Text/regex search across files |
+| `view_file_outline` | Show code structure (classes, functions) |
+### Shell & Commands
+| Tool | Description |
+|------|-------------|
+| `shell_command` | Execute background commands |
+| `command_status` | Check command progress/output |
+| `send_command_input` | Send input to running commands |
+| `kill_command` | Terminate running commands |
-BluMa ships with a comprehensive set of native tools for software engineering tasks:
+### Agent Coordination
+| Tool | Description |
+|------|-------------|
+| `spawn_agent` | Create background worker agents |
+| `wait_agent` | Wait for agent completion |
+| `list_agents` | List active/completed agents |
-**File Operations:**
-- `edit_tool` — Precise text replacement with context-aware editing
-- `read_file_lines` — Read specific line ranges from files
-- `ls_tool` — List directory contents with filtering & pagination
-- `count_file_lines` — Count total lines in a file
-- `view_file_outline` — Show code structure (classes, functions, methods)
-- `find_by_name` — Search files by name using glob patterns
+### Task & Project Management
+| Tool | Description |
+|------|-------------|
+| `todo` | Manage task lists |
+| `task_boundary` | Track task phases (PLANNING/EXECUTION/VERIFICATION) |
+| `create_artifact` | Save documents to `~/.bluma/artifacts/` |
+| `read_artifact` | Retrieve saved artifacts |
-**Code Intelligence:**
-- `grep_search` — Search text patterns with regex support
-- `coding_memory` — Persistent notes about codebase & decisions
+### 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` | Persist/retrieve project notes |
-**Shell & Process:**
-- `shell_command` — Execute shell commands (background async)
-- `command_status` — Check command progress & retrieve output
-- `send_command_input` — Send stdin to running commands
-- `kill_command` — Terminate running processes
+### Communication
+| Tool | Description |
+|------|-------------|
+| `message` | Post user-visible chat (info/result types) |
-**Agent Workflow:**
-- `message` — Send messages to user (info or result)
-- `todo` — Manage task lists with completion tracking
-- `task_boundary` — Mark task phases (PLANNING, EXECUTION, VERIFICATION)
-- `load_skill` — Load specialized knowledge modules
+---
-**UI & Navigation:**
-- All tools render rich Ink/React components in the terminal
+## Skills System
-To add custom native tools, create a new file in `src/app/agent/tools/natives/` following the existing pattern.
+Skills are **self-contained knowledge modules** that extend BluMa with domain expertise. They use **Progressive Disclosure** to manage context efficiently.
-### Skills System (Pluggable Expertise)
+### Skill Sources (Priority Order)
-BluMa features a **pluggable skills system** that loads domain-specific knowledge modules:
+| Priority | Source | Path |
+|----------|--------|------|
+| 1 | **Bundled** | `dist/config/skills/` |
+| 2 | **Project** | `{cwd}/.bluma/skills/` |
+| 3 | **Global** | `~/.bluma/skills/` |
-**Built-in Skills:**
-- `git-commit` — Professional Git commit workflows with Conventional Commits
-- `git-pr` — Pull request creation, commit validation, and merge preparation
-- `pdf` — PDF creation, manipulation, text extraction, merging, OCR
-- `xlsx` — Excel spreadsheet manipulation, formulas, data cleaning
-- `skill-creator` — Template and workflow for creating new skills
+### Progressive Disclosure Levels
-**Skill Structure:**
 ```
-skills/
-└── git-commit/
-    ├── SKILL.md              # Main workflow & instructions
-    ├── LICENSE.txt           # License terms
-    ├── references/
-    │   └── REFERENCE.md      # Additional documentation
-    └── scripts/
-        └── validate_commit_msg.py  # Executable helper
+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.
 ```
-**How Skills Work:**
-1. Skills are stored in `src/app/agent/config/skills/` (built-in) or `~/.bluma/skills/` (user)
-2. Each skill includes a `SKILL.md` with YAML frontmatter defining:
-   - `name`, `description`, `version`
-   - `depends_on` (other skills for delegation)
-   - `tools.required` and `tools.recommended`
-3. Load a skill with: `load_skill({ skill_name: "git-commit" })`
-4. Skill body provides workflows, examples, and decision trees
-5. Skills can include `references/` (extra docs) and `scripts/` (Python helpers)
-**Creating Custom Skills:**
-Use the `skill-creator` skill to generate new skill templates. Skills are ideal for:
-- Encoding domain-specific workflows (testing, deployment, frameworks)
-- Packaging best practices and conventions
-- Providing reusable scripts and reference documentation
-### MCP Integration
-BluMa integrates with the **Model Context Protocol (MCP)** SDK for:
-- Connecting to external MCP servers
-- Discovering and invoking remote tools
-- Streaming tool results in real-time
-MCP client is located at `src/app/agent/tools/mcp/mcp_client.ts`.
-### Custom UI Components
+### Available Skills
-Extend the interface by creating custom Ink components in `src/app/ui/components/`. The UI layer supports:
-- React 18 with hooks
-- Custom renderers for tool calls and results
-- Streaming text and typewriter effects
-- Progress bars, spinners, and notifications
-- Markdown rendering with syntax highlighting
+| Skill | Description |
+|-------|-------------|
+| `git-commit` | Conventional commits, staging, commit messages |
+| `git-pr` | Pull requests, code review preparation |
+| `pdf` | PDF creation, extraction, merging, OCR |
+| `xlsx` | Spreadsheet operations, formulas, charts |
+| `skill-creator` | Author new BluMa skills |
----
+### Loading Skills
-## <a name="tests"></a>Tests
-- The repository ships with Jest 30 configured (babel-jest) and TypeScript support.
-- Test files are located under `tests/` and follow `*.spec.ts` naming.
-- Run tests:
+```typescript
+// Via command
+> load the git-commit skill
-```bash
-npm test
-npm run test:watch
+// Via tool call
+load_skill({ skill_name: "git-commit" })
 ```
----
-## Live Dev Overlays (Open Channel During Processing)
-BluMa supports a live side-channel that stays active even while the agent is processing. This lets the dev send guidance or constraints in real-time — like pair programming.
-Key points
-- Permissive mode enabled: during processing, any free text you type is treated as a [hint] automatically.
-- Structured prefixes are also supported at any time:
-  - [hint] Text for immediate guidance to the agent
-  - [constraint] Rules/limits (e.g., "não tocar em src/app/agent/**")
-  - [override] Parameter overrides as key=value pairs (e.g., "file_path=C:/... expected_replacements=2")
-  - [assume] Register explicit assumptions
-  - [cancel] Interrupt safely (already supported)
-How it works
-- Frontend: the input remains active in read-only (processing) mode and emits a dev_overlay event.
-- Agent backend: consumes overlays with precedence (constraint > override > hint). Hints and assumptions are injected into the system context before the next decision; overrides/constraints adjust tool parameters just before execution.
-- Logging & history: every overlay is logged and stored in session history for auditability.
-Examples
-- During a long task, just type:
-  - "Prefer do not touch tests yet" → will be treated as [hint]
-  - "[constraint] não editar src/app/ui/**" → blocks edits under that path
-  - "[override] expected_replacements=2" → adjusts the next edit_tool call
-  - "[assume] target=api" → adds an assumption in context
-Notes
-- The side-channel does not pause the agent — it adapts on the fly.
-- If an overlay conflicts with the current plan: constraint > override > hint.
-- All overlays are acknowledged via standard internal messages and persisted.
----
-## <a name="configuration-and-environment-variables"></a>Configuration and Environment Variables
-**Recommended:** set **`FACTOR_ROUTER_KEY`** and **`FACTOR_ROUTER_URL`** in your **user or system environment** (shell profile, Windows User env, CI secrets, etc.) so every process sees them.
-BluMa also **loads** `~/.bluma/.env` if that file exists (optional merge via `dotenv`); use `.env.example` as a template only if you prefer a local file.
-**LLM routing** uses the FactorRouter gateway (OpenAI-compatible API):
-- `FACTOR_ROUTER_KEY` (required) — e.g. `sk-fai-...` from your FactorRouter admin
-- `FACTOR_ROUTER_URL` (required) — gateway base URL (e.g. `http://host:8003/router-api`; the client appends `/v1` if missing)
-These replace legacy `NOMAD_API_KEY`, `NOMAD_BASE_URL`, and `MODEL_NOMAD` (the router picks the model; requests use `model: "auto"`).
-Optional: `BLUMA_SANDBOX`, `BLUMA_SANDBOX_NAME`, MCP tokens, etc.
-### FactorRouter — headers HTTP (CLI vs sandbox)
-O SDK OpenAI (`openai` npm) envia metadados no **2.º argumento** da chamada `chat.completions.create(body, { headers })` — são **headers HTTP normais**, não um campo `extra_headers` no JSON do body.
-**Modo CLI interativo** (Ink, sem envelope): em cada request ao gateway são acrescentados:
-| Header | Conteúdo típico (exemplo) |
-|--------|---------------------------|
-| `X-Turn-Id` | UUID novo por turno (igual em todo o loop de tools desse turno) |
-| `X-Session-Id` | ID da sessão BluMa (`~/.bluma/sessions/…`) |
-| `X-Conversation-Id` | `null` |
-| `X-User-Message` | Primeiros 300 caracteres do pedido (URL-encoded) |
-| `X-User-Id` | MAC da 1.ª interface não-interna, ou `host:<hostname>` se não houver MAC útil |
-| `X-User-Name` | Utilizador do SO (`os.userInfo().username`, URL-encoded) |
-| `X-User-Email` | `null` |
-| `X-Company-Id` | Igual a `X-User-Id` (identificador da máquina) |
-| `X-Company-Name` | Igual (URL-encoded) |
-**Privacidade (desenvolvedores):** na CLI, estes valores servem para **agregação de custos** no FactorRouter. Não substituem o utilizador real no **agent mode**: aí prevalece o bloco `user_context` do JSON (sandbox / Severino).
-**Agent mode** (`bluma agent`): os mesmos nomes de header; valores vêm do envelope (`session_id`, `user_context`, `context.user_request`). Se `user_context` for omitido, user/company ficam `null` nos headers (não se usa a heurística MAC da CLI).
-Advanced config files are located in `src/app/agent/config/`.
+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)
 ---
-## <a name="stack"></a>Tech Stack Overview
-- Language: TypeScript (ESM)
-- Runtime: Node.js >= 18
-- CLI UI: React 18 via Ink 5, plus `ink-text-input`, `ink-spinner`, `ink-big-text`
-- Bundler: esbuild, with `esbuild-plugin-node-externals`
-- Test Runner: Jest 30 + babel-jest
-- Transpilers: Babel presets (env, react, typescript)
-- LLM/Agent: FactorRouter (OpenAI-compatible API); MCP via `@modelcontextprotocol/sdk`
-- Config loading: dotenv
-- Utilities: uuid, diff, react-devtools-core
----
-## <a name="license"></a>License
-Apache-2.0. Made by Alex Fonseca and NomadEngenuity contributors.
-Enjoy, hack, and—if possible—contribute!
----
+## Runtime & Orchestration
-## 🏗 Architecture Diagram
+### Task Store
-BluMa's architecture is organized in **three layers**: UI, Agent Orchestration, and Core Services.
+Track work with PLANNING → EXECUTION → VERIFICATION phases:
-### High-Level Overview
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      UI Layer (Ink/React)                    │
-│  main.ts → App.tsx → Components (20+) → Layout → Theme      │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│                  Agent Orchestration Layer                   │
-│  agent.ts → RouteManager → BluMaAgent (bluma.ts)            │
-│  ↓                                                           │
-│  SubAgents Registry | Feedback System | Session Manager     │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│                    Core Services Layer                       │
-│  ┌──────────────┬──────────────┬──────────────┐            │
-│  │ Context API  │  LLM Client  │  Prompt Bld  │            │
-│  │ (context     │  (Factor     │  (system     │            │
-│  │  manager)    │   Router)    │  prompts)    │            │
-│  └──────────────┴──────────────┴──────────────┘            │
-│  ┌──────────────┬──────────────┬──────────────┐            │
-│  │ MCP Client   │ Native Tools │  Skills      │            │
-│  │ (external    │  (20+ tools) │  (pluggable) │            │
-│  │  plugins)    │              │              │            │
-│  └──────────────┴──────────────┴──────────────┘            │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│                 External Integrations                        │
-│  FactorRouter API | File System | Shell | MCP Servers       │
-└─────────────────────────────────────────────────────────────┘
+```typescript
+task_boundary({
+  task_name: "Implementing Authentication",
+  mode: "PLANNING",
+  task_status: "Creating middleware structure"
+});
 ```
-### Key Architectural Concepts
-**1. RouteManager Pattern**
-- Central dispatch mechanism for command routing
-- Registers custom route handlers (e.g., `/init`, `/status`)
-- Falls back to core agent loop for unregistered commands
-- Enables extensible command architecture
-**2. SubAgents Registry**
-- Pluggable sub-agent system for specialized tasks
-- Each sub-agent declares capabilities via registry
-- Init subagent handles environment setup
-- Extensible via `registerSubAgent()` API
-**3. Context Management**
-- `ContextManager` handles conversation history
-- `TokenCounter` tracks token usage (tiktoken)
-- `HistoryAnchor` manages context window compression
-- Automatic pruning to stay within LLM limits
-**4. Session Persistence**
-- `SessionManager` persists all interactions
-- Stored in `~/.bluma/sessions/<session-id>.json`
-- Survives across CLI restarts
-- Includes full tool call history and results
-**5. Skills System**
-- Pluggable knowledge modules (`skill_loader.ts`)
-- Built-in skills: `git-commit`, `git-pr`, `pdf`, `xlsx`, `skill-creator`
-- Each skill includes `SKILL.md` with workflows
-- Can include `references/` (docs) and `scripts/` (executables)
-### Sequence Diagram
-```mermaid
-sequenceDiagram
-    participant UI as UI (main.ts + App.tsx)
-    participant Agent as Agent (Orchestrator)
-    participant Core as BluMaAgent (Core Loop)
-    participant MCP as MCPClient / Tools
-    UI->>Agent: Initialize(sessionId, eventBus)
-    Agent->>Core: initialize()
-    Core->>MCP: initialize tools
-    UI->>Agent: processTurn(userInput)
-    Agent->>Core: processTurn(content)
-    Core->>MCP: Get available tools & context
-    MCP-->>Core: Tool list & details
-    Core-->>Agent: Tool call request or LLM message
-    Agent-->>UI: backend_message (e.g., confirmation_request)
-    UI->>Agent: handleToolResponse()
-    Agent->>Core: handleToolResponse(decision)
-    Core->>MCP: Execute tool
-    MCP-->>Core: Tool result
-    Core-->>Agent: backend_message(done)
-    Agent-->>UI: Update history & UI state
-```
+### Hook Registry
----
+Event-driven lifecycle tracking:
-### Component Diagram
-```mermaid
-flowchart TD
-    subgraph UI["UI Layer"]
-        M["main.ts"]
-        A["App.tsx"]
-    end
-    subgraph AG["Agent Layer"]
-        AGN["Agent (Orchestrator)"]
-        CORE["BluMaAgent (Core Loop)"]
-    end
-    subgraph TOOLS["Tools & Integration"]
-        MCP["MCPClient"]
-        NT["Native Tools"]
-        SA["SubAgents"]
-    end
-    EXT["External APIs & FS"]
-    M --> A --> AGN --> CORE --> MCP --> NT
-    CORE --> SA
-    MCP --> EXT
-    NT --> EXT
+```typescript
+// Hooks fire on: tool_calls, decisions, state_changes
+registerHook('tool_calls', (event) => {
+  console.log(`Tool ${event.toolName} executed`);
+});
 ```
----
-### Activity Diagram
-```mermaid
-flowchart TD
-    Start((Start)) --> Input[User Input in UI]
-    Input --> Processing{Command Type?}
-    Processing -->|Slash Command| SC[Handle Slash Command]
-    Processing -->|Normal Input| PT[processTurn]
-    SC --> Done((End))
-    PT --> LLM[Send to LLM]
-    LLM --> ToolCall{Tool Requested?}
-    ToolCall -->|No| Display[Display Assistant Message]
-    ToolCall -->|Yes| Confirm[Ask for Confirmation]
-    Confirm --> Decision{Decision}
-    Decision -->|Accept| Exec[Execute Tool]
-    Decision -->|Decline| Skip[Skip Execution]
-    Exec --> Result[Return Tool Result]
-    Skip --> Done
-    Result --> Done
-    Display --> Done
-```
+### Plugin Registry
----
+Load plugins from `.bluma/plugins/`:
-### State Machine Diagram
-```mermaid
-stateDiagram-v2
-    [*] --> Idle
-    Idle --> Processing: User Input
-    Processing --> Awaiting_Confirmation: Tool Call Needs Approval
-    Awaiting_Confirmation --> Processing: User Accepts
-    Awaiting_Confirmation --> Idle: User Declines
-    Processing --> Completed: Task Completed
-    Processing --> Interrupted: User Interrupt
-    Completed --> Idle
-    Interrupted --> Idle
+```bash
+> /plugins list          # Show loaded plugins
+> /plugins load my-plugin # Load a plugin
 ```
----
+### Session Registry
-### Deployment Diagram
-```mermaid
-graph TD
-    CLI["CLI (BluMa)"] --> LocalFS[("Local File System")]
-    CLI --> FactorRouter[("FactorRouter API")]
-    CLI --> OtherAPIs[("Other External APIs")]
-    CLI --> MCPServer[("MCP Server / Plugins")]
-```
----
+Multi-session support with health monitoring:
-### Data Flow Diagram
-```mermaid
-flowchart LR
-    U[User] --> UI[UI Layer]
-    UI --> Agent[Agent]
-    Agent --> Core[BluMaAgent]
-    Core --> MCP[MCPClient]
-    Core --> Sub[SubAgents]
-    MCP --> Tools[Native Tools & External APIs]
-    Sub --> Tools
-    Tools --> MCP
-    MCP --> Core
-    Core --> Agent
-    Agent --> UI
-    UI --> U
+```bash
+> /sessions list         # List all sessions
+> /sessions logs <id>    # Stream session logs
+> /sessions kill <id>    # Terminate session
 ```
----
-## 💡 Usage Examples
+### Diagnostics
-### Interactive CLI Mode
+Real-time system snapshot:
-**1. Start a Conversation**
 ```bash
-bluma
-```
-Then ask naturally:
-- "Help me refactor this authentication module"
-- "Run tests and fix any failures"
-- "Create a PDF report from this data"
+> /diagnostics           # Full system status
+> /diagnostics tasks     # Task overview
+> /diagnostics hooks     # Hook registry status
+> /diagnostics plugins   # Plugin registry status
+> /diagnostics sessions  # Active sessions
+```
+### 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 |
+### 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`
+---
+## 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 |
+### 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 |
+### 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 execution rules |
+| `/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) |
+### Help
+| Command | Description |
+|---------|-------------|
+| `/help` | List all slash commands (grouped) |
+### Input (Keyboard Shortcuts)
+| Shortcut | Description |
+|----------|-------------|
+| `Ctrl+V / Cmd+V` | Paste from clipboard: image → file path under ~/.cache/bluma/clipboard; else text |
+| `Ctrl+Shift+I` | Same as Ctrl+V / Cmd+V (paste image or text) |
+---
+## Development
+### Build
-**2. Use Slash Commands**
 ```bash
-/init              # Initialize environment with init subagent
-/todo              # View current task list
-/memory list       # List all coding memory entries
-/skills            # List available skills
-```
-**3. Load Skills for Specialized Tasks**
-```
-# The agent will automatically load skills when needed
-"Commit these changes with a proper message"     → loads git-commit skill
-"Create a pull request"                          → loads git-pr skill
-"Generate a PDF report"                          → loads pdf skill
-"Analyze this Excel file"                        → loads xlsx skill
+npm run build        # Production build
+npm start           # Build + run
 ```
-**4. Live Overlays During Processing**
-While the agent is working, type guidance:
-```
-[hint] Focus on the authentication flow first
-[constraint] Don't modify files in tests/ yet
-[override] expected_replacements=2
-[assume] target_database=postgresql
-```
-**5. Tool Confirmation Flow**
-When the agent requests a sensitive operation:
-```
-┌─────────────────────────────────────────┐
-│  EDIT PREVIEW                           │
-│  File: src/auth/login.ts                │
-│  Lines 45-67                            │
-│                                         │
-│  - old code                             │
-│  + new code                             │
-└─────────────────────────────────────────┘
-[Accept] [Decline] [Accept Always] [Expand]
-```
+### Lint
-### Agent Mode (Sandbox / API Integration)
-**6. Call BluMa from Another System**
 ```bash
-BLUMA_SANDBOX=true BLUMA_SANDBOX_NAME="agiweb" \
-node dist/main.js agent --input - << 'EOF'
-{
-  "session_id": "conv-123",
-  "message_id": "job-456",
-  "from_agent": "agiweb",
-  "to_agent": "bluma",
-  "action": "generate_report",
-  "context": {
-    "user_request": "Create sales report PDF"
-  },
-  "user_context": {
-    "userId": "13",
-    "userName": "Alex",
-    "companyId": "4"
-  },
-  "metadata": { "sandbox": true }
-}
-EOF
-```
-**7. Parse JSONL Output**
-The agent outputs structured events:
-```json
-{"event_type":"log","level":"info","message":"Starting..."}
-{"event_type":"action_status","payload":{"action":"Thinking"}}
-{"event_type":"backend_message","backend_type":"tool_call",...}
-{"event_type":"result","status":"success","data":{"attachments":["/app/artifacts/report.pdf"]}}
-```
-**8. Retrieve Generated Artifacts**
-Check the `attachments` array in the final `result` event:
-```json
-{
-  "event_type": "result",
-  "status": "success",
-  "data": {
-    "message_id": "job-456",
-    "last_assistant_message": "Report generated successfully",
-    "attachments": [
-      "/app/artifacts/sales_report.pdf",
-      "/app/artifacts/sales_data.csv"
-    ]
-  }
-}
-```
-### Common Workflows
+npm run lint        # Check code style
+npm run lint:fix    # Auto-fix issues
+```
+### Project Structure
+```
+src/
+├── app/
+│   ├── agent/
+│   │   ├── agent.ts                    # Main orchestrator
+│   │   ├── bluma/                      # Core agent logic
+│   │   ├── 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
+│   │   │   │   └── tool_call_normalizer.ts
+│   │   │   └── prompt/                 # Prompt engineering
+│   │   │       ├── prompt_builder.ts   # Dynamic prompts
+│   │   │       └── workspace_snapshot.ts
+│   │   ├── runtime/                    # Orchestration layer (v0.1.41+)
+│   │   │   ├── diagnostics.ts          # System snapshots
+│   │   │   ├── hook_registry.ts        # Event-driven hooks
+│   │   │   ├── native_tool_catalog.ts  # Tool registry
+│   │   │   ├── plugin_registry.ts      # Plugin system
+│   │   │   ├── 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_execution_policy.ts
+│   │   ├── tools/                      # Tool layer
+│   │   │   └── natives/                # 18 native tools
+│   │   │       ├── agent_coordination.ts
+│   │   │       ├── async_command.ts
+│   │   │       ├── coding_memory.ts
+│   │   │       ├── edit.ts
+│   │   │       ├── file_write.ts
+│   │   │       ├── find_by_name.ts
+│   │   │       ├── grep_search.ts
+│   │   │       ├── load_skill.ts
+│   │   │       ├── ls.ts
+│   │   │       ├── message.ts
+│   │   │       ├── readLines.ts
+│   │   │       ├── search_web.ts
+│   │   │       ├── shell_command.ts
+│   │   │       ├── task_boundary.ts
+│   │   │       ├── todo.ts
+│   │   │       ├── view_file_outline.ts
+│   │   │       └── web_fetch.ts
+│   │   └── types/                      # TypeScript definitions
+│   └── ui/
+│       ├── App.tsx                     # Main UI component
+│       ├── components/                 # 21 UI components
+│       │   ├── AnimatedBorder.tsx
+│       │   ├── CollapsibleResult.tsx
+│       │   ├── EditToolDiffPanel.tsx   # Diff preview for edits
+│       │   ├── ErrorMessage.tsx
+│       │   ├── ExpandedPreviewBlock.tsx
+│       │   ├── InputPrompt.tsx         # User input
+│       │   ├── MarkdownRenderer.tsx
+│       │   ├── ProgressBar.tsx
+│       │   ├── ReasoningDisplay.tsx    # LLM reasoning
+│       │   ├── SessionStats.tsx
+│       │   ├── SimpleDiff.tsx
+│       │   ├── SlashCommands.tsx       # 20+ commands
+│       │   ├── StatusNotification.tsx
+│       │   ├── StreamingText.tsx       # Live text output
+│       │   ├── TodoPlanDisplay.tsx     # Task visualization
+│       │   ├── ToolCallDisplay.tsx
+│       │   ├── ToolResultCard.tsx      # Structured results
+│       │   ├── ToolResultDisplay.tsx
+│       │   ├── TypewriterText.tsx
+│       │   ├── UpdateNotice.tsx
+│       │   └── toolCallRenderers.tsx
+│       ├── theme/                      # Terminal theming
+│       └── utils/                      # UI utilities
+├── main.ts                             # Entry point
+└── types/                              # Global types
+```
+---
+## Testing
-**9. Code Refactoring**
-```
-User: "Refactor this function to use async/await"
-→ Agent reads file with read_file_lines
-→ Plans changes with todo
-→ Applies edits with edit_tool (shows preview)
-→ Runs tests with shell_command
-→ Reports results
+```bash
+npm test            # Run all tests
+npm run test:watch  # Watch mode
 ```
-**10. Git Workflow**
-```
-User: "Commit my changes"
-→ Agent loads git-commit skill
-→ Runs git status --short
-→ Stages files with git add
-→ Writes conventional commit message
-→ Executes git commit
-```
+### Test Structure
-**11. Data Analysis & Reporting**
 ```
-User: "Analyze sales.xlsx and create a summary"
-→ Agent loads xlsx skill
-→ Runs Python script to read Excel
-→ Processes data with pandas
-→ Generates PDF with charts
-→ Returns attachments array
+tests/                    # 33 test files (flat structure)
+├── 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
+└── ...                   # Additional integration and unit tests
 ```
 ---
-## 🤝 Contributing
-We welcome contributions! For full details, read [CONTRIBUTING.md](CONTRIBUTING.md).
-### 📋 Prerequisites
-- **Node.js** >= 18 and **npm** >= 9 installed
-- Dependencies installed via `npm install`
-- Required environment variables configured (see *Configuration* section)
-### 🔄 Contribution Workflow
-1. **Fork** the repository
-2. **Clone** your fork locally
-3. Create a feature branch named according to [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat/add-logging`)
-4. Commit changes with meaningful messages
-5. Push to your fork and open a Pull Request
-### 🛠 Code Standards
-- Follow TypeScript strict mode guidelines
-- Maintain style via ESLint and Prettier (`npm run lint`)
-- Keep functions short, modular, and documented with JSDoc
-- All business logic must have unit tests
-### 🧪 Testing Requirements
-- Run `npm test` and ensure all tests pass
-- Include new tests for any new functionality or bug fix
-- Validate integration tests when adding new tools or APIs
-### 🔍 Code Review Process
-- Minimum of 1 maintainer approval before merge
-- Resolve all review comments and passing CI before merge
-### 📄 Documentation
-- Update README.md or relevant Wiki pages when adding/removing features
-- Add or update CHANGELOG.md for notable changes
----
-## Coding memory
-BluMa includes a **persistent coding memory** system that stores notes about the codebase, decisions, and context that survive across sessions:
-- Memory is stored in `~/.bluma/coding_memory.json`
-- Use the `coding_memory` tool to **add**, **list**, **search**, **update** (by id), or **remove** (one id at a time). There is **no** bulk “clear all” action.
-- Notes can be tagged for easy categorization (e.g., `['api', 'auth', 'performance']`)
-- Memory is loaded at session start and can be searched during tasks
-### When to use Coding Memory:
-- After learning stable facts about architecture or conventions
-- To store important URLs, API endpoints, or design decisions
-- To remember user preferences that should persist across sessions
-- To document invariants or critical system behaviors
-### Example:
-```json
-{
-  "action": "add",
-  "note": "Project uses FactorRouter for LLM routing with model auto-selection",
-  "tags": ["llm", "architecture"]
-}
-```
----
+## Contributing
-## ⚠️ Limitations / Next Steps
-- Logging verbosity could be made configurable.
-- Potential for richer plugin lifecycle (install/remove at runtime).
-- Improve error reporting in subagents.
-- Expand skill library with more domain-specific modules.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
----
+### Quick Contribution Guide
-## 🔒 Security Notes
-- **API Keys:** Never commit `.env` files or hardcode API keys in source code.
-- **File Operations:** `edit_tool` can modify files — always review previews before accepting changes.
-- **Sandbox Mode:** When `BLUMA_SANDBOX=true`, BluMa is forbidden from exposing environment variables, API keys, or infrastructure details.
-- **Permissions:** Use restricted permissions for API tokens wherever possible (principle of least privilege).
-- **Shared Systems:** If using on shared systems, ensure `.bluma` config directory is private (`chmod 700 ~/.bluma`).
-- **Input Validation:** All user inputs are validated and sanitized to prevent prompt injection attacks.
+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
-## 🛠 Error Handling & Recovery Flows
-BluMa handles different classes of errors gracefully:
-- **Network/API Errors**: Retry logic with exponential backoff.
-- **Authentication Failures**: Immediate notification to user, requires updating environment variables.
-- **Tool Execution Errors**: Displayed with detailed message; execution can be retried or skipped.
-- **LLM/API Exceptions**: Fall back to safe mode and keep context intact.
-- **Session/History Save Failures**: Warn user and continue without losing core functionality.
+- Use **English** for code, comments, and commits
+- 2-space indentation
+- TypeScript with modern React patterns
+- Follow existing code structure
 ---
-## 📈 Metrics & Observability
-- **Performance Metrics**: Average response time, tokens used per request, tool execution times.
-- **Usage Tracking**: Number of commands executed, tool calls, sessions created.
-- **Logging**: Structured logs for all events.
-- Integration-ready with Prometheus/Grafana or external observability platforms.
+## License
----
-## 🔐 Advanced Security Practices
-- Use secret management tools (Vault, AWS Secrets Manager) to store environment variables.
-- Apply principle of least privilege for API keys.
-- Validate and sanitize all user inputs to avoid prompt injection attacks.
-- Regularly rotate API keys.
+Apache 2.0 — see [LICENSE](LICENSE) for details.
 ---
-## 🚀 Performance & Scalability
-- Optimize context window by pruning irrelevant history.
-- Batch related operations to reduce LLM calls.
-- Support for distributed execution or remote agent hosting.
-- Cache static responses where possible.
+## Support
----
+- **Issues**: [GitHub Issues](https://github.com/nomad-e/bluma-cli/issues)
+- **Documentation**: This README + `docs/` directory
+- **Author**: Alex Fonseca
+- **npm Package**: [@nomad-e/bluma-cli](https://www.npmjs.com/package/@nomad-e/bluma-cli)
-## 🔄 Development Cycle & CI/CD
-- **Testing**: `npm test` and `npm run test:watch` for development.
-- **Linting**: Enforce coding standards with ESLint/Prettier.
-- **CI/CD**: Recommended GitHub Actions or similar to run tests/build on push.
-- **Deployment**: Automatic packaging to npm or internal registry.
+### Runtime Modules (v0.1.41+)
----
+BluMa's runtime layer provides enterprise-grade orchestration:
-## 🗺 Roadmap & Release Notes
-**Upcoming:**
-- Multi-LLM provider support.
-- Web-based dashboard.
-- Richer subagent plugin APIs.
+| Module | Purpose | Key Features |
+|--------|---------|--------------|
+| `task_store.ts` | Task lifecycle | PLANNING → EXECUTION → VERIFICATION phases, persistence |
+| `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 |
+| `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 |
-**Release Notes**:
-- Follow [CHANGELOG.md](CHANGELOG.md) for version history.
+### UI Components
----
+Key UI components that power the rich terminal experience:
-## 🎯 Advanced Use Cases
-- Chain multiple tools with complex decision-making.
-- Build custom subagents for domain-specific automation.
-- Integrate with CI pipelines for automated code review and refactoring.
+| Component | Purpose |
+|-----------|---------|
+| `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 |
 ---
-## 📏 Code Standards & Contribution Guidelines
-- Follow TypeScript strict mode.
-- Commit messages must follow Conventional Commits (`feat:`, `fix:`, `chore:`).
-- Keep functions short, modular and documented.
-- Add unit tests for all business logic.
----
+<p align="center">
+  <sub>Built with ❤️ by NomadEngenuity</sub>
+</p>