diff --git a/README.md b/README.md
index 53ac25d..032f7fe 100644
--- a/README.md
+++ b/README.md
@@ -1,97 +1,169 @@
-# КОМПАС-3D в Claude Code, Codex и pi
+
+
+ Детали |
+эскизы списком примитивов (включая текст в кривых), выдавливание, вращение, лофт, кинематика, отверстия, условная резьба, фаски, скругления, оболочка, ребро, массивы, зеркало, уклон, булевы операции |
+
+
+ Параметрика |
+размеры операций — выражения (depth="wall*2"), переменные модели, управляющие размеры эскиза, исполнения в одном файле |
+
+
+ Сборки |
+вставка компонентов с поворотом, семь типов сопряжений (в том числе по вспомогательным плоскостям и осям), фиксация, проверка пересечений (объём и зазор — на v25) |
+
+
+ Чертежи |
+стандартные виды, разрезы и сечения, размеры с допусками, шероховатость, выноски, штамп, технические требования, фрагменты |
+
+
+ Чужая геометрия |
+импорт STEP, IGES, Parasolid, STL, родных форматов NX/Creo/SolidWorks/Inventor/CATIA, DXF/DWG (STL приходит сеткой, не телом); прямая правка B-rep без дерева построения (часть операций — на v25) |
+
+
+ Выход |
+STEP (AP203/214/242) в другую САПР, STL в слайсер, PNG-снимок модели и растр чертежа; раскраска детали, тел, операций, граней и компонентов сборки — цвет, прозрачность, текстуры |
+
+
+ Осмотр |
+один вызов describe_model — дерево, тела, топология, масса, переменные, ошибки, состав сборки; измерение зазоров с двумя ближайшими точками |
+
+
+
+### Чем отличается
+
+- **Успех проверяется, а не принимается на веру.** КОМПАС умеет «успешно» вырезать мимо материала
+ или выдавить не в ту сторону. Сервер сверяет результат с параметрами запроса и говорит прямо,
+ когда вышло не то.
+- **Отказ называет причину.** Не «ошибка построения #37», а «катет больше длины 20 из 54 рёбер:
+ `[110]` 0.171 мм … возьмите меньше» или координаты разомкнутого конца контура.
+- **Модель остаётся параметрической.** Размеры связаны выражениями с переменными, и
+ правка одной переменной перестраивает деталь — как у инженера, а не как у скрипта.
+- **Агенты не мешают друг другу.** Режим `private` (`KOMPAS_MCP_INSTANCE=private` или
+ `kompas_connect(instance="private")`) поднимает собственный скрытый экземпляр КОМПАС, и параллельная
+ сессия не уведёт активный документ. По умолчанию сервер работает в общем окне пользователя.
+
+## Установка
+
+### Что нужно заранее
+
+| | |
+|---|---|
+| **Windows x64** | сервер — COM-клиент КОМПАС и работает только на той же машине |
+| **КОМПАС-3D с компонентом SDK** | проверено на v25 Home, v24 Home тоже поддерживается; запускать заранее не нужно — сервер присоединится к открытому окну или запустит экземпляр сам |
+| **[.NET Runtime](https://dotnet.microsoft.com/download/dotnet) 10+, x64** | сервер поставляется framework-dependent, рантайм берётся с машины; `dotnet --list-runtimes` должен показать `Microsoft.NETCore.App 10.x` или новее |
+| **Папка вне OneDrive** | клон и рабочие файлы не должны лежать в синхронизируемых папках |
+
+Interop-сборки принадлежат АСКОН и в поставку не входят. Они берутся из установки
+(`SDK\Samples\CSharp.zip`, каталог `Common`) и при первом запуске распаковываются в
+`%LOCALAPPDATA%\kompas-mcp\interop\<ключ>`. Без SDK укажите каталог со сборками в
+`KOMPAS_INTEROP_DIR`.
+
+### Claude Code
+
+```text
/plugin marketplace add https://git.shahovalov.ru/mikhail/kompas-plugin.git
/plugin install kompas@kompas-plugin
/kompas:doctor
```
-`/kompas:doctor` — диагностика: версия сервера, установлен ли КОМПАС, на месте ли interop-сборки,
-проходит ли соединение. С неё стоит начинать разбор любой неполадки.
+Обновление:
-## Обновление в Claude Code
-
-```
+```text
/plugin marketplace update kompas-plugin
/plugin update kompas@kompas-plugin
```
Если после обновления инструменты остались прежними — `/reload-plugins`.
-## Что внутри
-
-| | |
-|---|---|
-| **MCP-сервер `kompas`** | 78 инструментов: документы, эскизы, выдавливание/вращение/по сечениям/по траектории, оболочка, рёбра, уклон, скругления и фаски, массивы и зеркало, отверстия, булевы операции, прямое редактирование B-rep, переменные и параметризация, **исполнения** (несколько геометрий одной модели в одном файле), внешний вид (цвет, прозрачность, текстуры), сборки и сопряжения (в том числе по вспомогательным плоскостям и осям), 2D-чертежи (виды, размеры, обозначения, тех. требования), STEP/STL, осмотр (`describe_model`, `list_faces`, `list_edges`, `measure`) |
-| **Навык `kompas-3d`** | методика построения: порядок работы, выбор подхода, проверенные приёмы и ловушки |
-| **Навык `kompas-fdm-design`** | проектирование под FDM/FFF-печать: нависания, толщины стенок, зазоры и посадки, ориентация, бобышки и защёлки |
-| **Команда `/kompas:doctor`** | диагностика установки |
-| **Справка `help`** | инструмент `help(topic=…)` — статьи по механике и ловушкам, прямо в сессии |
-
-## Установка в Codex
-
-В терминале зарегистрируйте публичный каталог:
+### Codex
```powershell
codex plugin marketplace add https://git.shahovalov.ru/mikhail/kompas-plugin.git
```
-Затем откройте каталог плагинов Codex, выберите источник `kompas-plugin` и установите `kompas`.
-Откройте новый чат с плагином: сервер и оба навыка поставляются вместе. Для обновления каталога
-используйте `codex plugin marketplace upgrade kompas-plugin`, затем обновите плагин в интерфейсе.
-Команда `/kompas:doctor` относится к Claude Code; в Codex проверяйте подключение через `kompas_status`.
+Затем откройте каталог плагинов Codex, выберите источник `kompas-plugin`, установите `kompas` и
+начните новый чат. Обновление — `codex plugin marketplace upgrade kompas-plugin`, затем обновите
+плагин в интерфейсе.
-## Установка в pi
+### pi
Прилавок — pi-пакет целиком: расширение регистрирует MCP-сервер, оба навыка идут вместе.
-```
+```text
pi install git:https://git.shahovalov.ru/mikhail/kompas-plugin.git
```
-Обновление — `pi update --extensions`. После обновления новые записи из
-[CHANGELOG.md](CHANGELOG.md) показываются при следующем новом запуске pi
-(при первой загрузке пакета — нет).
+Обновление — `pi update --extensions`; новые записи [истории изменений](CHANGELOG.md) pi покажет при
+следующем запуске (при первой загрузке пакета — нет). Закрепить версию:
-Для закрепления версии:
-
-```
+```text
pi install git:https://git.shahovalov.ru/mikhail/kompas-plugin.git@v0.7.5
```
-Закреплённый тег не обновляется до следующего релиза автоматически: повторите `pi install`
-с новым тегом или без ref, чтобы снова следовать ветке. Проверка соединения — `kompas_status`.
+Закреплённый тег сам не обновляется: повторите `pi install` с новым тегом или без него, чтобы снова
+следовать ветке.
-## Другие агентские харнессы
+### opencode и ручное подключение
-Тот же сервер можно подключить вручную к Codex, opencode и pi — сниппеты конфигурации лежат в
-`plugin/adapters/{codex,opencode,pi}/`.
+Сниппеты конфигурации лежат в [`plugin/adapters/`](plugin/adapters):
+[opencode](plugin/adapters/opencode/README.md), [Codex](plugin/adapters/codex/README.md),
+[pi](plugin/adapters/pi/README.md). Все они запускают тот же сервер, что и плагин.
+
+## Что внутри
+
+| | |
+|---|---|
+| **MCP-сервер `kompas`** | весь каталог инструментов; сервер едет в плагине, отдельно ставить нечего |
+| **Навык `kompas-3d`** | методика построения: порядок работы, выбор подхода, проверенные приёмы и ловушки |
+| **Навык `kompas-fdm-design`** | проектирование под FDM-печать: нависания, толщины стенок, зазоры и посадки, ориентация, бобышки и защёлки |
+| **Справка `help`** | `help(topic=…)` — статьи по механике и ловушкам, прямо в сессии |
+| **Команда `/kompas:doctor`** | диагностика установки в Claude Code |
+
+## Если что-то не работает
+
+| Клиент | Проверка |
+|---|---|
+| Claude Code | `/kompas:doctor` — версия сервера, КОМПАС, interop-сборки, соединение |
+| Codex, pi, opencode | инструмент `kompas_status`; ответ «Не подключено» значит, что сначала нужен `kompas_connect` |
+| Инструментов нет совсем | сервер не запустился: проверьте `dotnet --list-runtimes` |
+
+Это репозиторий поставки: здесь лежат собранный сервер и материалы плагина, исходники сервера не
+публикуются.
## Лицензия
diff --git a/assets/banner.svg b/assets/banner.svg
new file mode 100644
index 0000000..d2b19c6
--- /dev/null
+++ b/assets/banner.svg
@@ -0,0 +1,35 @@
+