micro-models-agent 0.3.0 → 0.4.0

package/README.md

@@ -1,436 +1,436 @@
-# 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
+
+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