micro-models-agent 0.6.4 → 0.7.0

package/README.md

@@ -1,436 +1,286 @@
-# MMA — Micro Models Agent
-
-LLM-агент, который работает на маленьких моделях (Qwen3.5-9B, 32K-64K контекст). Пишет код, редактирует файлы, ищет баги, выполняет bash-команды, читает документацию — и всё это на моделях, которые запускаются на обычном ноутбуке без GPU.
-
-**Чем MMA отличается от больших агентов (OpenCode, Claude Code, Cursor):**
-
-- **Лёгкий**: не требует GPT-4 или Claude Sonnet. Работает на Qwen3.5-9B, DeepSeek-Coder и других opensource-моделях. Всё локально.
-- **ReAct-цикл**: модель сама планирует и вызывает инструменты через `<tool_call>` — читает/пишет/редактирует файлы, ищет по проекту, выполняет bash.
-- **Навыки (Skills)**: подгружаемые markdown-инструкции для специализированных задач (Docker, CSS, auth, и т.д.).
-- **Индексация кода**: AST-индекс символов + карта проекта (project map) для навигации по любой кодовой базе.
-- **Память**: долговременная память агента — запоминает факты между сессиями.
-- **Веб-поиск**: может искать информацию в интернете.
-- **Браузер**: интерактивный headless-браузер (Playwright) — навигация, клики, ввод текста, скриншоты, извлечение данных со страниц.
-- **Плагины**: мощная система плагинов на lifecycle events. [PLUGINS.md](./PLUGINS.md)
-- **Планирование**: создаёт и утверждает планы через PLAN.md перед выполнением.
-- **Сессии**: сохранение, восстановление, список сессий.
-- **MCP интеграция**: поддержка Model Context Protocol для внешних инструментов.
-- **Вопросы пользователю**: может уточнять детали задачи, запрашивать одобрение.
-- **Синтаксис @file**: загрузка файлов/директорий прямо в промпт.
-- **Стилизация**: сменные темы оформления.
-- **Мастер первого запуска**: интерактивная настройка провайдера и модели.
-- **12 файловых инструментов**: read, write, edit, list, create, delete, copy, move, info, glob, grep, tree.
-- **Браузерный инструмент**: `web_browse` — navigate, click, type, extract, screenshot, scroll, wait, get_links, evaluate, close.
-- **Простая установка**: `npm install -g micro-models-agent` и готово.
-
-Поддерживает OpenAI-совместимые API: LM Studio, Ollama, vLLM, Together AI и другие.
-
-## Установка
-
-### Глобально через npm (рекомендуется)
-
-```bash
-npm install -g micro-models-agent
-
-# Проверка:
-mma --version
-```
-
-### Из исходников
-
-```bash
-git clone <repo>
-cd mma
-npm install
-npm run build
-npm link
-```
-
-## Удаление
-
-```bash
-npm uninstall -g micro-models-agent   # удалить пакет
-rm -rf ~/.mma                          # удалить конфиг, кэш, логи, сессии
-```
-
-> `~/.mma/` можно не удалять — данные останутся на случай повторной установки.
-
-## Быстрый старт
-
-### Интерактивный режим (REPL) — самый простой способ
-
-```bash
-# Установите
-npm install -g micro-models-agent
-
-# И просто запустите
-mma
-```
-
-> **Совет:** перед первым запуском запустите LM Studio → вкладка Local Server → Start Server → загрузите модель (например, [Qwen 3.5-9B](https://huggingface.co/Qwen/Qwen3.5-9B-Instruct-GGUF)). Мастер сам найдёт её и настроит.
-
-**При первом запуске** появится мастер настройки:
-1. Выберите провайдера (LM Studio, Ollama или Remote API)
-2. Мастер найдёт доступные модели и протестирует соединение
-3. Готово — вы в REPL, можно писать запросы
-
-**При повторных запусках** REPL открывается сразу.
-
-В REPL работаете как в чате: пишете задачу, агент думает и выполняет. Доступны служебные команды:
-
-| Команда | Описание |
-|---------|----------|
-| `/help` | Справка |
-| `/read <file>` | Показать файл |
-| `/write <file>` | Записать файл |
-| `/bash <cmd>` | Выполнить команду |
-| `/clear` | Очистить контекст |
-| `/exit` | Выход |
-
-### One-shot (быстрый запрос)
-
-```bash
-mma "Создай React-компонент для формы входа"
-```
-
-Можно передать провайдера и модель флагами:
-
-```bash
-mma --provider ollama --model qwen3.5-9b "Напиши Dockerfile"
-```
-
-### С пайпом (stdin)
-
-```bash
-cat package.json | mma "Опиши зависимости"
-```
-
-## Настройка провайдеров и моделей
-
-По умолчанию конфиг настроен на LM Studio (`localhost:1234`). Если нужно добавить другой сервер:
-
-```bash
-# Добавить провайдера
-mma provider add ollama http://localhost:11434/v1
-
-# Переключиться на него
-mma provider use ollama
-
-# Добавить модель к активному провайдеру
-mma model add qwen3.5-9b qwen3.5-9b-instruct 32768
-
-# Выбрать модель (model add не активирует автоматически)
-mma model use qwen3.5-9b
-```
-
-### Все команды управления
-
-```bash
-# Провайдеры
-mma provider list              # Список провайдеров
-mma provider use ollama        # Переключиться на провайдера
-mma provider add <имя> <url>   # Добавить провайдера
-mma provider remove <имя>      # Удалить провайдера
-
-# Модели
-mma model list                 # Список моделей активного провайдера
-mma model use <имя>            # Переключиться на модель
-mma model current              # Показать активную модель
-mma model add <имя> <id> <ctx> # Добавить модель
-mma model remove <имя>         # Удалить модель
-mma model params [имя]         # Параметры модели
-mma model set <имя> k=v        # Изменить параметр (temperature=0.5)
-
-# Конфиг
-mma config show                # Показать весь конфиг
-mma config reset               # Сбросить настройки
-mma config thinking [on/off]   # Включить/выключить скрытие размышлений модели
-
-# Обновления
-mma update                     # Проверить наличие обновлений
-mma update check               # Проверить версию
-mma update install             # Скачать и установить обновление
-```
-
-### Параметры моделей
-
-По умолчанию:
-- `temperature`: 0.7
-- `max_tokens`: 4096
-- `top_p`: 0.9
-
-Изменить:
-
-```bash
-mma model set qwen3.5-9b temperature=0.3 max_tokens=8192
-mma model set qwen3.5-9b seed=42        # для воспроизводимости
-mma model set qwen3.5-9b seed=null      # сбросить seed
-```
-
-## Конфигурация
-
-Конфиг хранится в `~/.mma/config.json`.
-
-```json
-{
-  "providers": {
-    "lmstudio": {
-      "type": "openai-compat",
-      "url": "http://localhost:1234/v1",
-      "apiKey": null,
-      "models": {
-        "qwen3.5-9b": {
-          "model": "qwen3.5-9b-instruct",
-          "contextWindow": 32768,
-          "params": {
-            "temperature": 0.7,
-            "max_tokens": 4096
-          }
-        }
-      }
-    }
-  },
-  "active": {
-    "provider": "lmstudio",
-    "model": "qwen3.5-9b"
-  },
-  "agent": {
-    "maxSteps": 50,
-    "autoCompact": true,
-    "compactThreshold": 0.85,
-    "toolTimeout": 120,
-    "maxOutputLength": 2000
-  }
-}
-```
-
-Можно также создать `.mmrc` в корне проекта — он смержится поверх глобального конфига.
-
-### Переменные окружения
-
-| Переменная | Описание |
-|-----------|----------|
-| `MMA_PROVIDER` | Провайдер по умолчанию |
-| `MMA_MODEL` | Модель по умолчанию |
-| `MMA_STDIN=1` | Принудительное чтение stdin |
-
-## Режимы запуска
-
-### One-shot
-
-```bash
-mma "Объясни этот код: function fib(n) { return n < 2 ? n : fib(n-1) + fib(n-2); }"
-```
-
-### Stdin (пайп)
-
-```bash
-cat main.ts | mma "Найди потенциальные баги"
-curl -s https://api.example.com/data | mma "Проанализируй JSON"
-```
-
-### REPL
-
-```bash
-mma
-```
-
-В REPL доступны команды:
-
-| Команда | Описание |
-|---------|----------|
-| `/read <file>` | Показать файл с нумерацией строк |
-| `/write <file>` | Записать файл (до EOF) |
-| `/edit <file> <n>` | Заменить строку N в файле |
-| `/find <pattern>` | Поиск файлов по glob |
-| `/search <pattern>` | Поиск содержимого |
-| `/bash <cmd>` | Выполнить shell-команду |
-| `/git <args>` | Git-операции |
-| `/memory` | Показать память |
-| `/memory add <type> <text>` | Добавить в память |
-| `/memory search <query>` | Поиск в памяти |
-| `/skill` | Список навыков |
-| `/sessions` | Список сессий |
-| `/resume <id>` | Восстановить сессию |
-| `/save [name]` | Сохранить сессию |
-| `/clear` | Очистить контекст |
-| `/help` | Справка |
-| `/exit` | Выход |
-
-## Синтаксис `@file`
-
-Загружает файлы в контекст агента:
-
-```bash
-mma "@src/index.ts -- объясни эту функцию"
-
-# Несколько файлов
-mma "@src/auth/login.ts @src/auth/jwt.ts -- сравни"
-
-# Диапазон строк
-mma "@src/index.ts:10-30 -- что здесь происходит?"
-
-# Вся директория
-mma "@src/auth/ -- покажи структуру модуля"
-```
-
-## Навыки (Skills)
-
-Навыки — это Markdown-файлы с инструкциями для модели. Загружаются из:
-- `~/.mma/skills/<name>/SKILL.md`
-- `.agents/skills/<name>/SKILL.md`
-- `.claude/skills/<name>/SKILL.md`
-
-```bash
-# Использовать навык
-mma "@docker -- помоги контейнеризовать приложение"
-```
-
-## Агент: как это работает
-
-1. Вы даёте задачу (prompt)
-2. Модель генерирует план и вызывает инструменты через `<tool_call>`
-3. Агент выполняет инструменты и возвращает результат модели
-4. Модель анализирует результат и решает, что делать дальше
-5. Цикл продолжается до завершения задачи (макс. 50 шагов)
-
-### Инструменты агента
-
-| Инструмент | Описание |
-|-----------|----------|
-| `read_file` | Чтение файла с нумерацией строк |
-| `write_file` | Атомарная запись/создание файла |
-| `edit_file` | Find & replace (точное совпадение) |
-| `list_dir` | Список директории |
-| `create_dir` | Рекурсивное создание директории |
-| `delete_file` | Удаление файла/директории |
-| `copy_file` | Копирование |
-| `move_file` | Перемещение/переименование |
-| `file_info` | Метаданные файла |
-| `glob_search` | Поиск по паттерну |
-| `grep_search` | Поиск по содержимому (regex) |
-| `tree` | Дерево директорий |
-| `bash` | Выполнение команд (npm, git, docker) |
-
-## Архитектура
-
-### Плагины
-
-Система плагинов на жизненных циклах (lifecycle events). Плагины реализуют интерфейс `AgentPlugin` и подписываются на события (`tool:before`, `tool:after`, `agent:done` и др.). Управляются через `PluginManager` с event bus.
-
-Плагины — это директории с `manifest.json` + точкой входа (.ts/.js). Они могут лежать в трёх местах (сканируются в порядке приоритета):
-
-| Источник | Путь | Описание |
-|----------|------|----------|
-| builtin | `dist/plugins/builtin/` | Встроенные плагины, поставляются с MMA |
-| project | `.mma/plugins/<name>/` | Проектные плагины (в репозитории) |
-| user | `~/.mma/plugins/<name>/` | Личные плагины пользователя |
-
-**Встроенные плагины:**
-
-| Плагин | Описание |
-|--------|----------|
-| `notify` | OS desktop-уведомления (Windows/macOS/Linux) |
-| `lint-on-write` | Авто-запуск линтера после write_file/edit_file |
-
-**CLI-команды:**
-
-```bash
-mma plugin list                # Список всех обнаруженных плагинов
-mma plugin create <name>       # Создать новый плагин в .mma/plugins/
-```
-
-**REPL-команда:** `/plugins` — показать плагины, их источник и статус.
-
-**Конфигурация:**
-
-Плагины активируются автоматически: все builtin, плюс указанные в `config.agent.plugins`:
-
-```json
-{
-  "agent": {
-    "plugins": ["my-plugin"]
-  }
-}
-```
-
-Также плагины можно привязать к режиму через `ModeConfig.plugins` (режим `pro` включает `hooks-adapter`).
-
-Подробнее: [PLUGINS.md](./PLUGINS.md) — документация по созданию и устройству плагинов.
-
-### Субагенты
-
-Повторно используемый ReAct-цикл (`src/agent/react-loop.ts`) для запуска дочерних агентов внутри сессии. Используется субагентом (`src/agent/subagent.ts`) для параллельного выполнения подзадач. Основной цикл (`loop.ts`) имеет собственный встроенный ReAct-цикл.
-
-### Режимы (Modes)
-
-Три встроенных режима через `ModeRegistry` (`src/agent/modes/`):
-
-| Режим | Описание |
-|-------|----------|
-| `fast` | Без навыков, урезанный системный промпт |
-| `base` | Полный набор инструментов и навыков |
-| `pro` | Расширенный цикл с верификацией |
-
-Пользовательские режимы задаются через `AppConfig.modes`.
-
-### ToolHandler и ToolExecutor
-
-Все 20 инструментов (12 FS + bash + 2 web + 6 native) реализуют интерфейс `ToolHandler` из `src/tools/types.ts`. `ToolExecutor` в `src/agent/tool-executor.ts` — чистый диспетчер с конвейером: pre-hooks → execute → post-hooks → truncate.
-
-### Карта исходников
-
-| Компонент | Путь | Назначение |
-|-----------|------|------------|
-| Точка входа | `src/index.ts` → `src/cli.ts` | Commander CLI |
-| Цикл агента | `src/agent/loop.ts` | ReAct-цикл, ядро |
-| Исполнитель инструментов | `src/agent/tool-executor.ts` | Диспетчер с конвейером |
-| Субагент | `src/agent/subagent.ts` | Дочерний агент |
-| ReAct-loop | `src/agent/react-loop.ts` | Переиспользуемый ReAct-цикл |
-| Плагины | `src/plugins/` | Менеджер плагинов с шиной событий |
-| LLM провайдер | `src/llm/openai-compat.ts` | REST-клиент |
-| Системный промпт | `src/agent/system-prompt.ts` | Сборка системного промпта |
-
-## Индексация проекта
-
-Агент автоматически строит карту проекта и индекс кода:
-
-```bash
-# Вручную перестроить
-/build index rebuild
-/build project-map
-```
-
-## Работа с сессиями
-
-```bash
-# Автосохранение при выходе
-/save my-session-name
-
-# Список сессий
-/sessions
-
-# Восстановить
-/resume my-session-name
-```
-
-## Разработка
-
-```bash
-npm run build          # Компиляция TypeScript
-npm run dev            # Watch-режим
-npm test               # Тесты
-npm run test:all       # Все тесты
-npm run test:watch     # vitest watch
-```
-
-### Публикация новой версии
-
-```bash
-npm version patch     # или minor, major
-npm publish
-```
-
-## Лицензия
-
-MIT
+# MMA — Micro Models Agent v2
+
+[![npm version](https://img.shields.io/npm/v/micro-models-agent)](https://www.npmjs.com/package/micro-models-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**MMA** — modular AI coding agent harness designed for **small local language models** (9B params, 32K–64K context). Runs on your laptop, no cloud API needed.
+
+```bash
+npm install -g micro-models-agent
+mma "refactor the auth module to use JWT"
+```
+
+Built for and tested with [Qwen3.5-9B](https://qwen.readthedocs.io/) via LM Studio / Ollama / llama.cpp.
+
+---
+
+## Why MMA?
+
+Most AI coding agents (Devin, Cursor, Copilot) depend on massive cloud models or expensive APIs. MMA is built differently:
+
+- **Designed for 9B models** — optimized for Qwen3.5-9B running locally on consumer hardware
+- **No cloud dependency** — works fully offline with any OpenAI-compatible backend
+- **Survives small context windows** — sophisticated sliding-window compaction keeps 32K models productive
+- **Catches hallucinations** — 3-stage validation pipeline catches the confabulations small models are prone to
+- **Agent-Level MoE** — hierarchical task decomposition so small models handle complex multi-step work
+
+---
+
+## Features
+
+- **6-state agent loop** (INIT → THINK → ACT → OBSERVE → OUTPUT → ERROR) — clean, predictable, debuggable
+- **Context budget management** — dynamic per-model budget, sliding-window compaction with fact/decision/error extraction
+- **Hallucination detection** — factual (file paths), consistency (decision reversals), confidence (short/repetitive responses)
+- **Execution guarantees** — auto-planning via LLM (no keyword heuristics), stuck detection, off-track warnings, plan auto-advance
+- **Agent-Level MoE** — Router + Expert sub-agents with filtered tools, isolated context, file scope, and topological parallel execution
+- **20+ tools** — filesystem, shell, web search/fetch, browser (Playwright), planning, interaction, subagent, MCP, pipelines
+- **13 modules** — skills, plugins, MCP client, pipelines, project indexer, persistent memory, context, sessions, browser, execution, hallucination detection, updater, user profile
+- **MCP client** — connect to any MCP server (stdio or SSE)
+- **YAML pipelines** — DAG-based workflow engine with parallel waves, dependencies, and retries
+- **Multi-session management** — persistent JSONL sessions with REPL commands
+- **Project map** — automatic file walker + export extraction + disk cache
+- **i18n** — all user-facing strings via `t()`, English and Russian included
+- **8K–120K context** — adapts to any model's context window
+- **No TUI** — minimal CLI + REPL with markdown-to-ANSI formatting
+- **llama.cpp / Jinja proven** — battle-tested against Jinja template edge cases (system-first, streaming fallback, explicit `stream: false`)
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Runtime:** [Bun](https://bun.sh) (recommended) or Node.js ≥ 20
+- **LLM backend:** Any OpenAI-compatible server (LM Studio, Ollama, vLLM, llama.cpp, Together AI)
+
+### From npm
+
+```bash
+npm install -g micro-models-agent
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-org/micro-models-agent
+cd micro-models-agent
+bun install
+bun run build
+```
+
+---
+
+## Quick Start
+
+### 1. Start your LLM backend
+
+Point MMA to any OpenAI-compatible endpoint. Example with LM Studio:
+
+```bash
+# LM Studio listens on http://localhost:1234 by default
+```
+
+### 2. Run the setup wizard
+
+```bash
+bun run mma init
+```
+
+Scans local ports, finds your model, tests the connection, and writes config.
+
+### 3. Use the agent
+
+```bash
+# One-shot mode
+bun run mma "create a REST API with Express and add tests"
+
+# Interactive REPL
+bun run dev
+```
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+bun run mma "<prompt>"
+
+# Subcommands
+bun run mma init                       # Interactive setup wizard
+bun run mma config set model qwen3.5-9b
+bun run mma config show
+bun run mma model list                 # List available models
+bun run mma model use qwen3.5-9b       # Switch model
+bun run mma provider list              # List configured providers
+bun run mma session list               # List sessions
+bun run mma session show <id>          # Show session details
+bun run mma session delete <id>        # Delete a session
+```
+
+### REPL
+
+```bash
+bun run dev
+```
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `/help` | | Show help |
+| `/sessions` | `/ls` | List all sessions (* = active) |
+| `/new <name>` | `/create` | Create a new session |
+| `/resume <id\|name>` | `/switch`, `/use` | Switch to a session |
+| `/rename <name>` | | Rename current session |
+| `/delete <id>` | `/rm` | Delete a session |
+| `/config set <key> <value>` | | Set a config value |
+| `/exit` | | Exit REPL |
+
+### Development
+
+```bash
+bun run mma "fix the login page"       # Run agent
+bun run dev                            # Watch mode (auto-restart on changes)
+bun run build                          # TypeScript build
+bun test                               # Run tests
+tsc --noEmit                           # Type-check
+```
+
+---
+
+## Configuration
+
+3-layer config: `defaults.ts` → `~/.mma/config.json` (global) → `.mmrc` (project) + env vars.
+
+Key options (see `src/config/defaults.ts` for full list):
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `model` | `qwen3.5-9b` | Model name sent to backend |
+| `provider.baseUrl` | `http://localhost:1234/v1` | OpenAI-compatible API URL |
+| `contextWindow` | `32768` | Model's context window in tokens |
+| `autoPlan` | `true` | Auto-create plans for multi-step tasks |
+| `maxToolIterations` | `25` | Max tool calls per agent run |
+| `stuckThreshold` | `8` | Iterations without progress before stuck detection |
+| `moe.enabled` | `false` | Enable Agent-Level MoE |
+| `locale` | `en` | UI locale (`en` / `ru`) |
+| `logLevel` | `info` | Log level |
+
+### Agent-Level MoE
+
+```json
+{
+  "moe": { "enabled": true },
+  "orchestrator": {
+    "model": "qwen3-70b-414k",
+    "provider": { "baseUrl": "http://localhost:1234/v1" }
+  },
+  "experts": {
+    "code": { "model": "qwen3.5-9b", "tool_tags": ["file", "code", "shell"], "max_attempts": 3 },
+    "research": { "model": "qwen3.5-9b", "tool_tags": ["research"], "max_attempts": 3 },
+    "browser": { "model": "qwen3.5-9b", "tool_tags": ["browser", "vision"], "max_attempts": 3 }
+  }
+}
+```
+
+---
+
+## Architecture
+
+```
+CLI (main.ts → commands.ts / repl.ts / setup.ts)
+  → Core (agent.ts state machine → prompt-builder.ts)
+    → LLM Layer (provider.ts → openai-compat.ts → response.ts → token-counter.ts)
+      → Tools (registry.ts → executor.ts → 20+ tools)
+        → Modules (skills, plugins, mcp, pipelines, indexer, memory, context, session,
+                   hallucination, execution, updater, user-profile, browser)
+```
+
+### Project Structure
+
+```
+src/
+├── core/          # Agent loop, prompt builder, types
+├── llm/           # Provider abstraction, OpenAI-compat, streaming, token counting
+├── tools/         # 20+ tools with registry, executor, scope guards
+├── modules/       # 13 modules (skills, plugins, mcp, pipelines, indexer, memory, context, session, hallucination, execution, updater, user-profile, browser)
+├── cli/           # Entry point, commands, REPL, setup wizard
+├── config/        # 3-layer config: defaults → global → project
+├── i18n/          # en.json + ru.json + t() function
+├── ui/            # Markdown→ANSI formatter
+└── logger/        # Structured logger with levels + child loggers
+```
+
+---
+
+## Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file with offset/limit |
+| `write_file` | Create/overwrite with directory creation |
+| `edit_file` | Find-replace in existing files |
+| `glob` | Glob pattern matching |
+| `grep` | Regex content search via ripgrep |
+| `list_dir` | List directory contents |
+| `create_dir` | Create directory (recursive) |
+| `delete_file` | Delete file or empty directory |
+| `move_file` | Move/rename file or directory |
+| `file_info` | File/directory metadata |
+| `bash` | Shell command execution |
+| `subagent` | Isolated sub-agent with scope |
+| `web_search` | Web search |
+| `web_fetch` | Web page fetch (15K chars, 15s timeout) |
+| `web_browse` | Playwright browser (click, type, scroll, screenshot) |
+| `plan` | Create/update/cancel plans |
+| `todo` | Track todo items |
+| `question` | Ask user for input |
+| `approve` | Request user approval |
+| `load_skill` | Load a skill at runtime |
+| `pipeline_run` | Execute a YAML pipeline |
+| `mcp_call` | Call an MCP server tool |
+| `search_history` | Search session history |
+| `project_map` | Query project index (summary, refresh, find) |
+
+---
+
+## Testing
+
+```bash
+bun test                    # Unit + component tests
+bun test tests/agent.test.ts   # Single file
+bun run test:integration    # Integration tests (requires LLM backend)
+tsc --noEmit                # Type-check
+```
+
+---
+
+## Design Principles
+
+1. **No file >300 lines** — split when approaching limit
+2. **Small files, single responsibility** — each file does one thing
+3. **KISS state machine** — no god objects, no if-else nesting in agent loop
+4. **Plugin error isolation** — one plugin crash never stops others
+5. **Path safety** — all filesystem tools check `targetPath.startsWith(baseDir)`
+6. **TDD** — write test first, then implement, then commit
+7. **No hardcoded user-facing strings** — all text through `t()` i18n function
+8. **No keyword matching** — LLM decides when to plan, not heuristics
+9. **No TUI** — minimal CLI + REPL with markdown→ANSI
+
+---
+
+## License
+
+MIT
+
+---
+
+## Acknowledgments
+
+- [Qwen3.5-9B](https://qwen.readthedocs.io/) — the primary target model
+- [LM Studio](https://lmstudio.ai/) — recommended local inference server
+- [llama.cpp](https://github.com/ggerganov/llama.cpp) — the inference engine
+
+---
+
+**Made for local models. Runs everywhere.**