docs: describe project in CLAUDE.md and ARCHITECTURE.md

Refs #1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -1,15 +1,35 @@
 # Архитектура
 
-{{Карта модулей на одну страницу: что где лежит, границы, потоки данных. Читается агентом перед architectural brainstorming. Обновляется вместе со спеками.}}
+Два процесса, связанные только файлами в `~/.cache/claude-agents/`: хук внутри каждой сессии
+Claude Code пишет события, скрипт iTerm2 их читает и рисует панель.
+
+```
+claude (каждая сессия) ──hook──▶ agents_panel_hook.sh ──append──▶ ~/.cache/claude-agents/<sid>.jsonl
+                                                                         │
+iTerm2 AutoLaunch: claude_agents.py ◀───── read (poll 1.5 s) ────────────┘
+   ├─ + iTerm2 API (вкладки, профиль), ps, tmux, транскрипты ~/.claude/projects, git
+   ├─ + api.anthropic.com oauth/usage, prepaid/credits (OAuth из Keychain)
+   └─ HTTP 127.0.0.1:8766 ──▶ web view tool «Claude» в Toolbelt
+```
 
 ## Модули
 
 | Модуль | Ответственность | Зависит от |
 |---|---|---|
-| | | |
+| `files/agents_panel_hook.sh` | Событие хука → строка jsonl с PID, вкладкой iTerm2 или панелью tmux | `jq`, `ps` |
+| `files/claude_agents.py` — сессии | `load_sessions`/`replay`: jsonl → состояние сессий и субагентов; `build_tree` сводит с живыми вкладками, процессами, tmux | файлы хука, iTerm2 API, `ps`, `tmux`, транскрипты, `git` |
+| `files/claude_agents.py` — лимиты | `fetch_usage`/`fetch_balance` + `parse_limits`/`parse_balance` | Keychain/`~/.claude/.credentials.json`, `~/.claude.json`, api.anthropic.com, claude.ai |
+| `files/claude_agents.py` — UI | `render_*`, `handle` (HTTP), `activate`/`open_worktree`, `theme_poller` | `state`, iTerm2 API |
+| `files/settings_hooks.py` | Идемпотентно добавить/убрать хуки в `~/.claude/settings.json` | — |
+| `install.sh` / `uninstall.sh` | Разложить/убрать файлы, включить Python API iTerm2, перезапустить панель | `settings_hooks.py` |
 
 ## Границы
-- Что не должно импортировать что.
+- Хук не зависит от панели и не должен влиять на Claude Code: без вывода, всегда `exit 0`.
+- Панель только читает данные Claude Code (jsonl, транскрипты, `~/.claude.json`) и ничего туда не пишет;
+  её единственная запись — удаление собственных логов старше `keep_logs_days`.
+- `claude_agents.py` — только стандартная библиотека + `iterm2`; импорт без iTerm2 должен работать.
+- HTTP слушает только `127.0.0.1`.
 
 ## Открытые вопросы
-- 
+- Docstring `claude_agents.py` ссылается на несуществующий `settings-hooks.json` (теперь это `settings_hooks.py` + `install.sh`).
+- Автотестов нет; `claude_agents.py` — один файл на 1500 строк.

CLAUDE.md

@@ -1,28 +1,59 @@
 # cc-agents-iterm-plugin
 
 ## Что это
-{{ОДНИМ АБЗАЦЕМ: что делает система, для кого, главный сценарий.}}
+Панель «Claude» для iTerm2 Toolbelt. Сверху — дерево активных сессий Claude Code и их субагентов
+(название, модель, размер контекста, worktree, статус), снизу — лимиты подписки (5 ч, неделя,
+разбивка по продуктам) и баланс extra usage. Для одного пользователя на его Mac: видеть, что
+делают все запущенные `claude` и сколько осталось лимитов, и в один клик переходить в нужную
+вкладку или панель tmux.
 
 ## Стек и ограничения
-- {{Язык, сборка, тесты — например: Python 3.12, uv, pytest.}}
-- {{Жёсткие ограничения среды исполнения — без чего код не должен собираться.}}
+- Python 3.8+, только стандартная библиотека; модуль `iterm2` предоставляет сам iTerm2
+  (скрипт AutoLaunch). Без зависимостей из pip — пользователь ставит панель `./install.sh`.
+- Хук — POSIX `sh` + `jq`. Хук никогда не мешает Claude Code: ничего не выводит, всегда `exit 0`.
+- Только macOS + iTerm2 с включённым Python API. Токен OAuth берётся из Keychain
+  (`Claude Code-credentials`) или `~/.claude/.credentials.json`.
+- Установщик не трогает чужие хуки и настройки: правит `~/.claude/settings.json` только через
+  `settings_hooks.py` (маркер `agents_panel_hook`), перед заменой кладёт копии в
+  `~/.claude-panel-backup/<дата>/`. Повторный запуск `install.sh` идемпотентен.
 
 ## Архитектура
-- `src/core/` (или {{ваш путь}}) — чистая логика без зависимостей от фреймворка/платформы. Покрывается тестами полностью.
-- `src/{{adapter}}/` — тонкая обёртка над платформой. Тестируется руками или интеграционно.
-- {{Ключевые интерфейсы/порты между ними, если есть.}}
+- `files/agents_panel_hook.sh` — хук Claude Code на SessionStart/End, UserPromptSubmit, Stop,
+  Notification, SubagentStart/Stop, PostModelSwitch, PreToolUse(Agent|Task). Дописывает событие
+  в `~/.cache/claude-agents/<session_id>.jsonl` вместе с PID процесса `claude`,
+  `ITERM_SESSION_ID` или сокетом/панелью tmux.
+- `files/claude_agents.py` — скрипт iTerm2 AutoLaunch, один файл:
+  - `refresher` раз в `poll_sec` перечитывает jsonl (`load_sessions` → `replay`), сверяет с живыми
+    сессиями iTerm2, процессами (`ps`) и панелями tmux, дочитывает из транскриптов модель и токены,
+    из git — worktree; собирает `state["tree"]` (`build_tree`).
+  - `usage_poller` / `balance_poller` ходят в `api.anthropic.com/api/oauth/usage` и
+    `.../prepaid/credits` (запасной путь — claude.ai с `sessionKey` из Keychain).
+  - HTTP-сервер на `127.0.0.1:8766` (`handle`) отдаёт страницу, которую iTerm2 показывает как web view
+    tool: `/`, `/fragment` (дерево), `/limits`, `/message` (последние сообщения), `/activate`,
+    `/open-wt`, `/raw` (отладка).
+  - `theme_poller` подстраивает цвета под профиль iTerm2.
+- `files/settings_hooks.py` — добавляет/убирает хуки панели в `settings.json` (`add` / `remove`).
+- `files/config.example.json` — все ключи настроек; рабочий файл `~/.config/claude-agents/config.json`
+  перечитывается на лету, кроме `port`.
+- `install.sh` / `uninstall.sh [--purge]` — раскладывают файлы по местам (таблица в README.md).
 
 ## Команды
-- `{{npm test / pytest}}` — весь набор тестов. Зелёным считается только весь набор.
-- `{{npm run build / ...}}` — сборка.
-- `{{npm run dev / ...}}` — локальный запуск.
+- `./install.sh` — установить или обновить у себя; затем Toolbelt → Claude и перезапуск сессий `claude`.
+- `./uninstall.sh` — удалить (`--purge` — вместе с настройками и логами).
+- `python3 -m py_compile files/*.py && sh -n files/agents_panel_hook.sh && bash -n install.sh && bash -n uninstall.sh` —
+  синтаксическая проверка; сборки нет.
+- `curl -s http://127.0.0.1:8766/raw` — что видит запущенная панель: логи хука, причины скрытия
+  сессий, ошибки лимитов и баланса.
 
 ## Тесты
-- Golden-тесты: `tests/fixtures/<name>.*` + эталон `<name>.expected.*`. Внешние сервисы в тестах мокаются.
-- {{Где лежит тестовое окружение (vault, БД, песочница).}}
+- Автотестов пока нет. `claude_agents.py` импортируется без iTerm2 (`iterm2 = None`), так что чистые
+  функции (`replay`, `build_tree`, `parse_limits`, `parse_balance`, `session_name`, `settings_hooks.add/remove`)
+  можно покрывать pytest без iTerm2. Сеть, Keychain, `ps` и tmux в тестах мокаются.
+- Фикстуры — образцы jsonl хука и ответов API в `tests/fixtures/`.
 
-## Первая подсистема
-{{Что делается первым и почему. Тестовая инфраструктура — Task 1 первого плана.}}
+## Где лежит код
+- Код — в `files/`; хук require-plan защищает его через `.claude/code-paths`. `install.sh` и
+  `uninstall.sh` в корне хуком не покрыты (он умеет только каталоги).
 
 ## OpenSpec и superpowers
 - Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.