@nomad-e/bluma-cli 0.1.30 → 0.1.32

package/README.md

@@ -8,7 +8,7 @@
   <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 OpenRouter), tool execution, persistent history, session management, and extensibility through external plugins/tools.
+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.
 
 ---
 
@@ -25,8 +25,9 @@ BluMa is a CLI-based model agent responsible for language-level code generation,
 - [Sandbox / Agent Mode](#sandbox-agent-mode)
 - [Configuration and Environment Variables](#configuration-and-environment-variables)
 - [Development and Build](#development-and-build)
-- [Extensibility: Tools and Plugins](#extensibility-tools-and-plugins)
+- [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)
@@ -56,19 +57,21 @@ Choose BluMa for intelligent, efficient, and collaborative software engineering
 ## <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 OpenRouter, enabling natural language-driven automation.
+- **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.
-- **Extensible:** easily add new tools or integrate external SDK/plugins.
+- **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.
 
 ---
 
 ## <a name="requirements"></a>Requirements
 - Node.js >= 18
 - npm >= 9
-- OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai))
+- FactorRouter API key (get one from your FactorRouter admin)
 
 ---
 
@@ -98,17 +101,19 @@ If you get permission errors, EXAMPLES:
 > Only use sudo to install, never to run the CLI.
 
 ### Setting Up Environment Variables
-For BluMa CLI to operate, set the following environment variable globally in your system.
+For BluMa CLI to operate, set the following environment variables globally in your system.
 
 **Required:**
-- `OPENROUTER_API_KEY` (get your key at [openrouter.ai](https://openrouter.ai))
+- `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 OPENROUTER_API_KEY="your_openrouter_key"
+export FACTOR_ROUTER_KEY="your_factor_router_key"
+export FACTOR_ROUTER_URL="http://host:8003/router-api"
 ```
 Then run:
 ```sh
@@ -117,13 +122,15 @@ source ~/.bashrc # or whichever file you edited
 
 **Windows (CMD):**
 ```cmd
-setx OPENROUTER_API_KEY "your_openrouter_key"
+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.)
 
 **Windows (PowerShell):**
 ```powershell
-[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "your_openrouter_key", "Machine")
+[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_KEY", "your_factor_router_key", "Machine")
+[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_URL", "http://host:8003/router-api", "Machine")
 ```
 
 ### ℹ️ Global Installation of npm Packages in PowerShell (Windows)
@@ -166,7 +173,7 @@ Get up and running with BluMa in minutes:
    ```
 
 2. **Configure Environment:**
-   Set your OpenRouter API key (see [Configuration](#configuration-and-environment-variables)).
+   Set your FactorRouter API key and URL (see [Configuration](#configuration-and-environment-variables)).
 
 3. **Launch BluMa:**
    ```bash
@@ -411,17 +418,109 @@ Here's BluMa in action:
 ---
 
 ## <a name="project-structure"></a>Project Structure
+
 ```
-bluma-engineer/
-├── package.json               # npm/project config
-├── tsconfig.json              # TypeScript config
-├── scripts/build.js           # Build script using esbuild
+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 (Ink renderer)
+│   ├── main.ts                # Entry point (CLI bootstrap & agent mode)
 │   └── app/
-│        ├── agent/            # Agent core (session mgmt, tools, MCP, prompt, feedback)
-│        ├── ui/               # Ink/React CLI interface components
+│       ├── 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
@@ -439,10 +538,97 @@ npm run dev      # (If configured, hot-reload/TS watch)
 
 ---
 
-## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools and Plugins
-- Add native tools in `src/app/agent/tools/natives/`
-- Use the MCP SDK for advanced plugins integrating with external APIs
-- Create custom Ink components to expand the interface
+## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools, Skills and Plugins
+
+### Native Tools (20+ Built-in)
+
+BluMa ships with a comprehensive set of native tools for software engineering tasks:
+
+**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
+
+**Code Intelligence:**
+- `grep_search` — Search text patterns with regex support
+- `coding_memory` — Persistent notes about codebase & decisions
+
+**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
+
+**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
+
+To add custom native tools, create a new file in `src/app/agent/tools/natives/` following the existing pattern.
+
+### Skills System (Pluggable Expertise)
+
+BluMa features a **pluggable skills system** that loads domain-specific knowledge modules:
+
+**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
+
+**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
+```
+
+**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
+
+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
 
 ---
 
@@ -551,19 +737,74 @@ Enjoy, hack, and—if possible—contribute!
 ---
 
 ## 🏗 Architecture Diagram
-Below is a simplified diagram showing BluMa CLI's core architecture:
+
+BluMa's architecture is organized in **three layers**: UI, Agent Orchestration, and Core Services.
+
+### High-Level Overview
 ```
-[ main.ts ] → [ App.tsx (UI Layer) ]
-       ↓
-[ Agent (Orchestrator) ]
-       ↓
-[ BluMaAgent (Core Loop & State) ]
-       ↓
-[ MCPClient / Tools / Native Tools / SubAgents ]
-       ↓
-[ External APIs & System Operations ]
+┌─────────────────────────────────────────────────────────────┐
+│                      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       │
+└─────────────────────────────────────────────────────────────┘
 ```
-This flow ensures a clean separation between presentation, orchestration, core logic, and integration layers.
+
+### 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
@@ -661,7 +902,7 @@ stateDiagram-v2
 ```mermaid
 graph TD
     CLI["CLI (BluMa)"] --> LocalFS[("Local File System")]
-    CLI --> OpenRouter[("OpenRouter API")]
+    CLI --> FactorRouter[("FactorRouter API")]
     CLI --> OtherAPIs[("Other External APIs")]
     CLI --> MCPServer[("MCP Server / Plugins")]
 ```
@@ -688,23 +929,140 @@ flowchart LR
 ---
 
 ## 💡 Usage Examples
-- **Run Initialization Command**
+
+### Interactive CLI Mode
+
+**1. Start a Conversation**
+```bash
+bluma
 ```
-/init
+Then ask naturally:
+- "Help me refactor this authentication module"
+- "Run tests and fix any failures"
+- "Create a PDF report from this data"
+
+**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
 ```
-Executes the `init` subagent to prepare the working environment.
 
-- **Confirm an Edit Operation**
-When the system prompts an `edit_tool` operation, review the preview and choose:
+**3. Load Skills for Specialized Tasks**
 ```
-Accept | Decline | Accept Always
+# 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
 ```
 
-- **Live Overlay**
-During a long-running task, you can send hints:
+**4. Live Overlays During Processing**
+While the agent is working, type guidance:
 ```
-[hint] Prefer small batch edits
-[constraint] Avoid editing src/app/ui/**
+[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]
+```
+
+### 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
+
+**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
+```
+
+**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
+```
+
+**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
 ```
 
 ---
@@ -745,15 +1103,47 @@ We welcome contributions! For full details, read [CONTRIBUTING.md](CONTRIBUTING.
 
 ---
 
+## 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"]
+}
+```
+
+---
+
 ## ⚠️ Limitations / Next Steps
-- Current LLM integration uses OpenRouter; add more providers.
 - 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.
 
 ---
 
 ## 🔒 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.
 
 ---
 
@@ -824,7 +1214,3 @@ BluMa handles different classes of errors gracefully:
 - Add unit tests for all business logic.
 
 ---
-- Protect your API keys: never commit `.env` files.
-- `edit_tool` can modify files — review previews before accepting.
-- Use restricted permissions for API tokens wherever possible.
-- If using on shared systems, ensure `.bluma` config is private.