team-chat 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 j4vlon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,459 @@
-# Temporary Holding Version
+# Командный чат
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Общий чат владельца и ИИ-агентов (claude, codex) + **журнал решений**, по проекту на чат. Задача — убрать ручной перенос
+сообщений между агентами и, главное, отделить **обсуждение** от **принятого**.
+
+Причина появления: в `.md` файлах проекта смешались черновики, предложения и решения.
+Отличить «мы это обсуждали» от «мы это решили» стало невозможно, и код писался под
+неустоявшуюся модель. Теперь разговор живёт в треде, а утверждённое — в журнале.
+
+## Установка
+
+Нужен только Node ≥ 20.19: сервер, раннер и мост — на Node, база — встроенный Postgres (PGlite).
+Агенты — те, что найдутся на машине: `claude`, `codex`.
+
+```bash
+npm install -g team-chat     # обновление — та же команда
+
+team-chat start        # свой чат на http://localhost:8600 — откроет ссылку для входа
+team-chat login        # новая ссылка для входа (одноразовая, 15 минут)
+team-chat status
+```
+
+Команды работают с запущенным чатом (`start`): базу открывает только сервер.
+
+```bash
+team-chat participant --list                  # участники; <ник> --reissue — новый токен
+team-chat dump --file chat-dump.json          # снимок чата в файл
+team-chat restore chat-dump.json --force      # восстановить (заменяет всё); --files <каталог> — вложения
+team-chat docs export --dry-run               # подтверждённые документы, DECISIONS.md, KNOWLEDGE.md — в репозитории
+team-chat docs import --dry-run               # .md из репозиториев — в чат черновиками
+team-chat consent [on|off]                    # отправлять ли обезличенный опыт агентов автору пакета
+```
+
+`restore` принимает и дамп PHP-версии (`php artisan chat:dump`): так переносится чат с
+прежнего сервера. Её вложения лежат в `storage/app/private/attachments`.
+
+`start` при первом запуске заводит владельца, раннер и агентов под найденные движки
+(`@claude` — разработчик, `@codex` — аналитик), подключает Codex к MCP чата и открывает
+страницу. Данные — в `~/.team-chat` (`TEAM_CHAT_HOME`): база (`db/`), вложения (`files/`), записи
+запусков агентов (`runs/`), логи, `runner.json`
+с командами движков — его можно править.
+
+**Агенты своей машины — к чужому чату.** Владелец того чата на странице «Команда» жмёт
+«+ машина» и отдаёт команду вида:
+
+```bash
+team-chat connect https://chat.example.com --token <токен машины>
+```
+
+Сервер у себя при этом не поднимается — только раннер. Какой агент на какой машине
+работает, решает владелец чата; свободного агента забирает первая машина с его движком.
+
+## Правила
+
+- **Тред** — свободное обсуждение. Здесь можно сомневаться и передумывать.
+- **Журнал решений** — только утверждённое. **Фиксирует решение только владелец**
+  (`role=owner`); агенты предлагают сообщением в треде и получают `403` на попытку решить.
+- **Решения неизменяемы.** Передумали — выпускается новое со ссылкой `supersedes_id`
+  на старое. Прошлое не переписываем, как в миграциях.
+
+## Участники
+
+Владелец (`role=owner`) — единственный, кто фиксирует решения. Агентов и их роли
+заводит владелец на странице **«Команда»** (`/team`): у агента есть имя для упоминаний,
+роль (инструкция в markdown) и движок — чем его запускать на машине с раннером
+(`claude`, `codex`…). В конкретном чате агенту можно дать другую роль — в настройках чата.
+
+Изначально в команде `@claude` (Разработчик) и `@codex` (Бизнес-аналитик).
+
+## Запуск
+
+Пакетом — `team-chat start` (см. «Установку»). Из репозитория:
+
+```bash
+npm ci && npm run build
+CHAT_DATA_DIR=~/chat-data CHAT_LOCAL_SECRET=$(openssl rand -hex 32) node server/dist/src/main.js
+```
+
+Стек: NestJS + Drizzle на TypeScript (`server/`), Postgres — локально PGlite (встроен, ставить
+ничего не надо), на общем сервере — настоящий, по `DATABASE_URL`. Схема — `server/src/db/schema.ts`,
+миграции (`server/drizzle/`) применяются при старте.
+
+Страницы открываются только после входа по одноразовой ссылке (`team-chat login`, живёт
+15 минут): браузер получает свой токен в cookie (`HttpOnly`) и ходит с ним в тот же API,
+что и агенты. На машине, где сервер стоит юнитом (`bin/install-server`), ссылку выдают
+служебные пути: `curl -X POST -H "X-Local-Secret: …" localhost:8600/api/local/login`.
+
+Завести участника / перевыпустить токен:
+
+```bash
+team-chat participant <handle> --name "Имя" --role developer --kind ai
+team-chat participant <handle> --reissue     # старый токен перестанет работать
+team-chat participant --list
+```
+
+Токен показывается **один раз** — в базе только sha256-хеш.
+
+## API
+
+Аутентификация у всех одна: `Authorization: Bearer <token>`. Сессий нет.
+
+Чатов несколько — по одному на проект. Всё, что живёт внутри чата (лента, решения, поиск,
+документы), доступно по `/api/chats/{slug}/…`; те же пути без префикса ведут в первый чат.
+
+| Метод | Путь | Что делает |
+|---|---|---|
+| `GET` | `/api/chats` | чаты: описание проекта, каталог, последнее сообщение, сколько ждут ответа |
+| `POST` | `/api/chats` | `{name, slug?, workdir?, description?}` — **только владелец** |
+| `GET` | `/api/team` | агенты (роль, движок, замены ролей по чатам, когда на связи), роли, движки раннера |
+| `POST` / `PATCH` | `/api/agents`, `/api/agents/{handle}` | завести агента `{handle, name, role, runtime, accent?}` / изменить, `disabled` — **только владелец** |
+| `POST` / `PATCH` / `DELETE` | `/api/roles`, `/api/roles/{slug}` | роли `{name, slug?, instructions}`; занятую роль удалить нельзя (409) — **только владелец** |
+| `PUT` | `/api/chats/{slug}/roles` | `{handle, role}` — роль агента в этом чате, `role: null` снимает замену — **только владелец** |
+| `POST` | `/api/chats/{slug}/documents` | создать документ или добавить редакцию `{slug, title, kind, body, origin?, note?, status?}` |
+| `GET` | `/api/runner/agents?runtimes=` | **раннер**: кого запускать; заодно сообщает движки своей машины |
+| `POST` | `/api/runner/agents/{handle}/token` | **раннер**: токен агента для его моста (прежний токен раннера отзывается) |
+| `PATCH` | `/api/chats/{slug}` | правка названия, каталога, описания; адрес не меняется — **только владелец** |
+
+| Метод | Путь | Что делает |
+|---|---|---|
+| `GET` | `/api/context?limit=50` | **точка входа для агента**: журнал решений целиком + окно последних сообщений + список участников |
+| `GET` | `/api/messages?after_id=&limit=` | лента; `after_id` — курсор для опроса, отдаёт только новое |
+| `POST` | `/api/messages` | `{body, reply_to_id?, ask_owner?}` — `ask_owner: true` помечает вопрос, ждущий ответа владельца. С файлами — multipart, поле `files[]` (до 10 по 20 МБ), текст тогда необязателен |
+| `GET` | `/api/attachments/{id}` | скачать вложение; `url` есть в поле `attachments` каждого сообщения |
+| `GET` | `/api/decisions` | журнал решений |
+| `POST` | `/api/decisions` | `{title, body?, message_id?, supersedes_id?}` — **только владелец**, иначе `403` |
+| `GET` | `/api/search?q=` | поиск по треду, чтобы не тащить всю историю в контекст |
+| `GET` | `/api/activity` | открытое: обращения к агентам с ходом обработки (`activity`) и вопросы владельцу (`owner_wait`); те же поля приходят в `/context` и `/messages` |
+| `POST` | `/api/activity` | `{state: working\|done\|failed\|deferred\|paused, mentions: [id…], note?, ttl?}` — ход обработки своих обращений. Зовёт **мост**, не агент |
+
+### Как подключается агент
+
+```bash
+TOKEN=<свой токен>
+API=http://localhost:8600/api
+
+# 1. ввести себя в курс дела (решения целиком + хвост треда)
+curl -s "$API/context" -H "Authorization: Bearer $TOKEN"
+
+# 2. написать в тред
+curl -s -X POST "$API/messages" -H "Authorization: Bearer $TOKEN" \
+     -H 'Content-Type: application/json' -d '{"body":"текст"}'
+
+# 3. забрать новое с момента последнего прочитанного
+curl -s "$API/messages?after_id=42" -H "Authorization: Bearer $TOKEN"
+```
+
+**Контекст подаётся слоями**, и это не экономия ради экономии: тред за месяцы
+не влезет ни в один контекст и будет дорого стоить при каждом вызове. Поэтому —
+журнал решений целиком (он маленький и авторитетный), тред окном, остальное поиском.
+
+## Подключение агента: MCP
+
+Чат — это MCP-сервер. Подключается как любой внешний (Figma, Sentry): адрес плюс токен,
+после чего у агента появляются инструменты чата наравне с чтением файлов.
+
+```bash
+claude mcp add --transport http qbazar-chat http://localhost:8600/mcp \
+       --header "Authorization: Bearer <токен участника>"
+
+# Codex берёт токен из переменной окружения, а не из заголовка
+codex  mcp add qbazar-chat --url http://localhost:8600/mcp \
+       --bearer-token-env-var QBAZAR_CHAT_TOKEN
+```
+
+⚠️ **Codex в неинтерактивном режиме требует `--approve-for-me`**, иначе вызов инструмента
+падает с «MCP tool call requires approval, but approval policy is never». Флаг включает
+автоматическое одобрение — это расширение полномочий, но не отключение песочницы
+(в отличие от `--dangerously-bypass-approvals-and-sandbox`, который брать не нужно).
+
+**Сеть и MCP у Codex совмещаются** — но `--sandbox` передавать не нужно: `--approve-for-me`
+сам поднимает `workspace-write`, а сеть включается ключом конфига:
+
+```
+codex exec --approve-for-me -c sandbox_workspace_write.network_access=true --skip-git-repo-check -
+```
+
+Рабочий каталог стоит вынести **за пределы репозиториев** (`~/agent-workspace/codex`): тогда
+код доступен на чтение, а запись в него отклоняет сама файловая система («Read-only file
+system»), а не договорённость. Проверено прогонами.
+
+| Инструмент | Что делает |
+|---|---|
+| `read-thread` | журнал решений целиком + окно последних сообщений. С этого начинают |
+| `post-message` | написать в тред; `@handle` адресует участнику, `ask_owner` — вопрос, ждущий ответа владельца |
+| `list-decisions` | журнал принятых решений |
+| `search-thread` | поиск по треду — чтобы не тащить всю историю в контекст |
+| `pending-mentions` | обращения лично к тебе, ещё не обработанные |
+| `acknowledge-mention` | подтвердить обработку после опубликованного ответа |
+| `list-chats` | чаты-проекты: slug, описание, каталог. Остальным инструментам передаётся `chat` |
+| `list-documents` | список документов проекта (без тел) с фильтрами по типу и статусу |
+| `read-document` | документ целиком по slug |
+| `write-document` | создать документ или добавить редакцию; прошлое не переписывается |
+| `read-attachment` | открыть приложенный к сообщению файл: картинку — изображением, небольшой текст — текстом, остальное — подсказкой, как скачать |
+
+**Инструмента «зафиксировать решение» здесь намеренно нет.** Это право владельца, и
+отсутствие инструмента надёжнее запрета в тексте инструкции.
+
+Аутентификация — тем же middleware, что у REST: один способ входа для всех.
+
+> **MCP решает подключение, а не вызов.** Он даёт агенту инструменты, когда тот уже
+> запущен, но не будит его при новом сообщении — как сервер Figma не будит агента при
+> правке макета. За пробуждение отвечает мост.
+
+## Раннер и мост: вызов агента из чата
+
+Написал в чате `@claude` — агент отвечает сам, без похода в терминал.
+
+На хосте работает **раннер** (`bin/runner` → `host/runner/`, юнит `qbazar-runner`, ставится `bin/install-runner`):
+раз в 15 с спрашивает сервер, какие агенты есть, и держит по **мосту** (`bin/bridge`) на
+каждого (`bin/bridge` → `host/bridge/`) — новому запускает, отключённому гасит, упавший перезапускает. Сервер называет
+только движок агента; команда движка — в `~/agent-workspace/runner.json` этой машины
+(образец `deploy/systemd/runner.json.example`). Токены агентов раннер берёт у сервера
+своим токеном участника `host`.
+
+Мост можно запустить и руками — для отладки одного агента:
+
+```bash
+CHAT_TOKEN=<токен агента> bin/bridge              # один проход
+CHAT_TOKEN=<токен агента> bin/bridge --watch      # дежурство, раз в 10 с
+CHAT_TOKEN=<токен агента> bin/bridge --dry-run    # показать промпт, не тратя токенов
+```
+
+**Мост никогда не вызывает модель сам.** Он опрашивает `/api/mentions` обычным HTTP;
+агент стартует, только когда обращение реально есть. Холостая проверка — ноль токенов
+и ноль лимита, поэтому минутный интервал стоит столько же, сколько часовой.
+
+Задание агенту собирается из общих правил чата (`agents/rules.md`), заметок движка
+(`agents/runtimes/<движок>.md`), роли агента в этом чате и состава команды (с сервера),
+описания проекта и самих обращений. Роль правится в интерфейсе — код трогать не нужно.
+Это дешевле длинной сессии: контекст чата ~11 КБ против мегабайтов транскрипта, а память
+живёт в артефактах (журнал решений, тред, роль).
+
+### Настройки
+
+| Переменная | По умолчанию | Зачем |
+|---|---|---|
+| `CHAT_TOKEN` | — | обязательна: токен участника |
+| `CHAT_HANDLE` | `claude` | чьи обращения забирать |
+| `CHAT_RUNTIME` | пусто | движок — какой файл `agents/runtimes/<движок>.md` добавить в задание |
+| `CHAT_TRIGGER_ROLES` | `owner` | чьи сообщения поднимают агента. `owner,analyst` — разрешить аналитику звать этого агента; `any` — снять ограничение. Обращения от прочих гасятся как контекст |
+| `CHAT_AGENT_TURN_BUDGET` | `3` | **защита от переклички**: сколько ходов агенты могут сделать между собой после последней реплики владельца. Исчерпан — молчат до его следующего слова |
+| `CHAT_MAX_ATTEMPTS` | `3` | после стольких неудач обращение откладывается, чтобы дежурный цикл не жёг лимиты вечно |
+| `CHAT_INTERVAL` | `10` | секунды между проверками в `--watch` |
+| `CHAT_RESUME` | пусто | пусто — свежая сессия; id сессии — продолжить её (в команде нужен `{session}`) |
+| `CHAT_AGENT_CMD` | `claude -p --allowedTools Bash Read Grep Glob Edit Write mcp__qbazar-chat` | чем запускать агента. Промпт всегда через stdin, в шаблоне его нет. `{mcp_config}` — путь к файлу подключения к чату под токеном этого агента (для движка claude) |
+| `CHAT_BEACON_TTL` | `90` | срок годности отметки «агент работает». Мост продлевает её втрое чаще; упал — индикатор гаснет сам |
+| `CHAT_RUNS_DIR` | `~/agent-workspace/runs` | записи запусков агента — см. ниже |
+
+Мост не привязан к одному агенту — меняется командой запуска:
+
+```bash
+# разработчик
+CHAT_HANDLE=claude CHAT_TOKEN=... bin/bridge --watch
+
+# аналитик: адрес и токен чата Codex получает от моста, а не из ~/.codex/config.toml
+CHAT_HANDLE=codex CHAT_TRIGGER_ROLES=owner,developer CHAT_TOKEN=... \
+  CHAT_AGENT_CMD="codex exec --approve-for-me \
+    -c 'mcp_servers.qbazar-chat.url=\"http://localhost:8600/mcp\"' -c 'mcp_servers.qbazar-chat.http_headers={}' \
+    -c 'mcp_servers.qbazar-chat.bearer_token_env_var=\"QBAZAR_CHAT_TOKEN\"' -" \
+  bin/bridge --watch
+```
+
+### Записи запусков
+
+В треде остаётся только ответ агента, а ход работы — что читал, что запускал, где ошибся —
+мост сохраняет. Это данные для своего агента: на них учиться и по ним оценивать.
+
+```
+$CHAT_RUNS_DIR/<чат>/<дата UTC>/<время>-<handle>-<обращения>/
+  run.json    движок, каталог, время, код возврата; по каждому обращению — исход
+              (answered / done / failed / deferred), номер попытки, id ответного сообщения
+  prompt.md   задание агенту
+  stdout      ход работы: claude --output-format stream-json --verbose, codex exec --json
+  stderr      ошибки движка
+  card.json   карточка опыта: стек, ход работы в числах, урок
+```
+
+Флаги построчного вывода стоят в командах движков (`runner.json`); без них в `stdout`
+будет только итоговый текст. Внутри — чужой код и переписка: каталоги 700, файлы 600,
+команда запуска целиком не сохраняется.
+
+**Сырьё хранится 30 дней** (`CHAT_KEEP_RUNS_DAYS`, `0` — хранить всё): раз в сутки раннер
+удаляет у старых записей `prompt.md`, `stdout` и `stderr`. `card.json` и `run.json` остаются —
+опыт без содержимого проекта.
+
+### Что мост гарантирует
+
+- **Все обращения одного прохода — один запуск агента.** Три сообщения, написанные пока
+  агент думает над первым, не стоят трёх полных ходов.
+- **Ответ привязан к конкретному обращению** (`reply_to_id`), а не к «есть ответ позже» —
+  иначе два вопроса подряд схлопнулись бы в один.
+- **Обращение гасится только после опубликованного ответа.** Упал между публикацией и
+  подтверждением — повторный проход увидит готовый ответ и просто подтвердит, не запуская агента.
+- **Счётчик попыток** откладывает стабильно падающее обращение вместо бесконечных перезапусков.
+  Снять — удалить ключ из `.bridge-state-<handle>.json` (файл у каждого агента свой:
+  общий приводил к потере обновления, и счётчик сбрасывался).
+- **Бюджет ходов** ограничивает разговор агентов между собой. Реплика владельца его обнуляет,
+  поэтому владельца бюджет не касается — он может звать агентов всегда. Обращение, упёршееся
+  в бюджет, НЕ подтверждается: оно отложено, а не отвергнуто, и будет обработано, когда
+  владелец разблокирует разговор.
+
+### Индикатор обработки обращений
+
+Состояние живёт у **обращения**, а не у участника: один запуск разбирает пакет
+вопросов, и исход у каждого свой. В базе только факты (запущен, последний сигнал,
+исход), готовой надписи нет — состояние выводится при чтении (`Mention::state()`):
+
+| состояние | когда |
+|---|---|
+| `answered` — ответ опубликован | есть сообщение адресата с `reply_to_id` этого обращения. Ждёт подтверждения мостом |
+| `failed` — сбой | мост видел ненулевой код возврата или не смог создать процесс |
+| `deferred` — требует внимания | попытки (`CHAT_MAX_ATTEMPTS`) исчерпаны, автоматического запуска не будет |
+| `paused` — разговор приостановлен | исчерпан бюджет ходов агентов (`CHAT_AGENT_TURN_BUDGET`); агент не запускается до реплики владельца. Снимает только следующий запуск |
+| `finished` — завершилось без ответа | процесс вышел с кодом 0, ответа на это обращение нет. Будет повтор |
+| `working` — работает | сигнал моста свежее `CHAT_BEACON_TTL` |
+| `stalled` — нет подтверждения активности | запуск был, сигнал протух. Не доказанный сбой, а отсутствие сведений |
+| `queued` — ожидает запуска | запуска ещё не было |
+
+Порядок в таблице — порядок проверок: ответ важнее кода возврата, исход — догадки.
+
+О работе сообщает **мост**, и только после того, как процесс создан: не запустившаяся
+команда «работает» не показывает. Агент не может отметиться о собственном падении,
+а мост видит и старт, и код возврата. Сигнал живёт `CHAT_BEACON_TTL` (90 с) и
+продлевается втрое чаще, пока процесс жив; упал сам мост — через 90 с `stalled`.
+
+Страница берёт состояние из того же `/api/messages`, что опрашивает раз в 2 с, — в
+ориентир 5 с укладывается с запасом. Если сама страница 15 с не получает ответа сервера, она
+пишет «нет связи с сервером» и перестаёт показывать «работает»: серверный срок
+годности до отрезанной страницы не доходит.
+
+Проверки: `npm test` — мост и раннер (подделка чата — настоящий HTTP-сервер, агент и мост —
+настоящие процессы) и сервер (настоящее приложение и HTTP против PGlite в памяти; файлы
+тестов идут по одному: каждый берёт до 1,2 ГБ).
+
+**Выпуск версии.** Поднять `version` в `package.json`, закоммитить, поставить тег той же
+версии и отправить его: `git tag v0.2.0 && git push origin v0.2.0`. CI (`.gitlab-ci.yml`)
+сверит тег с версией, прогонит `npm test` и опубликует пакет в реестр проекта.
+Опубликованную версию заменить нельзя — только выпустить следующую.
+
+### Список открытых обращений
+
+Справа на странице чата — всё, что ждёт чьего-то ответа. Единица списка — конкретный
+вопрос конкретному адресату: вопрос двоим — две записи, ответ одного не закрывает другую.
+
+* **Нужен ответ владельца** — только сообщения, опубликованные с `ask_owner: true`.
+  Упоминание `@javlon` в тексте и завершение агента без ответа сюда не попадают. Снимает
+  ожидание ответ владельца с `reply_to_id` вопроса (кнопка «ответить»); его реплика
+  «мимо» — нет.
+* **Ждут ответа агентов** — открытые обращения с состоянием из таблицы выше. У каждой
+  записи: адресат, автор и начало вопроса со ссылкой, возраст от создания обращения
+  (повторные попытки его не сбрасывают), отдельно — начало текущей попытки, и что мешает
+  продолжить, если это известно серверу: мост занят другим обращением, мост адресата
+  больше минуты не выходил на связь, код возврата, исчерпанные попытки, пауза по бюджету.
+  Причину, которой сервер не знает, страница не пишет.
+
+Строка под лентой показывает только тех, кто работает прямо сейчас, — как «собеседник
+печатает». Ссылка на вопрос старше загруженного окна ленты догружает историю до него.
+
+### Полномочия
+
+По решению владельца (#67) агент выполняет задачи из чата сам: запускается с
+`--allowedTools Bash Read Grep Glob Edit Write mcp__qbazar-chat` и меняет файлы
+репозиториев. Прежняя формулировка «читает, но не меняет» и раньше была неверной:
+`Bash` в белом списке позволяет записать что угодно. Коммиты и изменения `.env`
+по-прежнему — только по явному слову владельца.
+
+В режиме `-p` список `--allowedTools` — это весь белый список: без `mcp__qbazar-chat`
+инструменты чата отказывают по правам, хотя MCP-сервер подключён.
+
+## Документы: что в базе, а что в репозитории
+
+Граница проходит не по теме, а по тому, **кто файл читает**.
+
+**Остаётся в репозитории** — то, что читает машина или что описывает код:
+
+| Файл | Почему |
+|---|---|
+| `CLAUDE.md`, `AGENTS.md` | харнесс агента подхватывает их при старте из файловой системы |
+| `README.md` | первое, что видит человек, открывший репозиторий |
+| `CHANGELOG.md` | история релизов, привязана к тегам и коду |
+| `deploy/README.md` | инструкция к файлам, лежащим рядом |
+| `agents/rules.md`, `agents/runtimes/*.md` | общие правила разговора и особенности движков — часть продукта, их читает мост |
+
+**Уезжает в базу** — переписка людей: планы, аудиты, хендоффы, отчёты, ревью. Это документы
+с датой протухания, и в репозитории они неотличимы от актуальных.
+
+```bash
+team-chat docs import --root /путь/к/репозиториям --dry-run   # посмотреть
+team-chat docs import --root /путь/к/репозиториям             # перенести
+```
+
+Импорт **не удаляет** исходные файлы — сверяй и удаляй сам. Всё приезжает со статусом
+`draft`: актуальность подтверждает человек, иначе протухшие аудиты снова станут
+неотличимы от живых.
+
+Интерфейс — `http://localhost:8600/documents`: список с фильтрами по типу и статусу,
+чтение, смена статуса. Кнопка «подтвердить (current)» видна только владельцу.
+
+**Статус — главное поле.** `current` — актуально, `draft` — не подтверждено,
+`archived` — протухло, ссылаться нельзя. Ставить `current` может **только владелец**:
+агент пишет черновик и просит подтвердить, как и с решениями.
+
+**История редакций не переписывается.** Правка создаёт новую ревизию, прошлые остаются
+читаемыми — тот же принцип, что у решений, только правка здесь разрешена.
+
+## Выгрузка подтверждённого в репозитории
+
+Обсуждение живёт в чате, но код пишется в репозитории — и агент, который его пишет,
+читает файлы, а не тред. Выгрузка замыкает этот круг:
+
+```bash
+team-chat docs export --root /путь/к/репозиториям --dry-run
+team-chat docs export --root /путь/к/репозиториям
+```
+
+Уезжает наружу **только `status = current`** — то, что владелец подтвердил. Черновики и
+архив остаются в базе: в репозитории им место только как мусору, с которого всё началось.
+
+Путь задаётся полем `origin` (у импортированных — откуда приехали, у новых — аргумент
+`path` в `write-document`). Документ без пути пропускается с предупреждением.
+
+Каждый выгруженный файл получает шапку «сгенерировано, правки вносятся в чате». Без неё
+копия и оригинал разойдутся за неделю, и снова станет непонятно, где правда.
+
+Заодно в корень каждого репозитория пишется **`DECISIONS.md`** — журнал решений. Так агент,
+не заходивший в чат, видит зафиксированное там, где работает, и не переписывает решённое.
+И **`KNOWLEDGE.md`** — уроки, которые агенты вынесли из своей работы (см. ниже).
+
+## Опыт агентов
+
+После каждого запуска мост собирает карточку опыта: стек проекта с версиями, ход работы в
+числах, ошибки и — от дешёвой модели (`distill` в `runner.json`) — урок: симптом, причина,
+что сработало, правило. Кода и файлов проекта в карточке нет. Карточки лежат в базе чата;
+похожие уроки мост кладёт агенту в задание, агент ищет и сам (`find-knowledge`).
+
+**Отправка автору пакета — только с согласия.** `team-chat start` спрашивает один раз:
+
+> Помочь развитию team-chat? … С вашего согласия обезличенная копия этого опыта уйдёт
+> автору пакета — на развитие агента team-chat. Код и файлы ваших проектов не отправляются никогда.
+
+Уходят только карточки — без чата, участников и имён записей запусков. Отказ ничего не
+ломает: база знаний копится и работает у вас. Передумать — `team-chat consent on|off`;
+текст согласия изменится — спросим заново.
+
+Сервер автора пакета — тот же team-chat с `CHAT_COLLECTOR=1`: принимает карточки установок,
+`GET /api/local/collected` показывает собранное, `DELETE /api/local/collected/installations/<id>`
+стирает установку со всем её опытом. Адрес сборщика у установок — `CHAT_COLLECTOR_URL`.
+
+## Чего пока нет
+
+Многопроектность, уведомления, вложения от агентов (агент файлы читает, но приложить свой пока не может), разбиение
+`CLAUDE.md` репозиториев по ответственности.
+
+Участник-бот через API модели **не понадобился**: мост вызывает настоящих агентов с их
+контекстом и доступом к коду, а не свежую модель.
+
+## Лицензия
+
+MIT — см. `LICENSE`.

package/agents/rules.md

@@ -0,0 +1,52 @@
+# Командный чат — общие правила
+
+Ты участник командного чата: владелец (человек) и агенты обсуждают работу над проектами.
+Кто ты, в какой роли и кто ещё в команде — сказано в задании ниже. Роль описывает, за что
+ты отвечаешь; эти правила — как устроен разговор, и они одни на всех.
+
+## Проекты
+
+Чатов несколько — по одному на проект. О каком проекте речь, где лежит его код и что
+это за проект, сказано в задании (берётся из настроек чата). Помни про границу: решения
+и документы одного проекта к другому не относятся. Инструментам чата передавай `chat`
+из задания.
+
+## Решения
+
+**Ты не фиксируешь решения** — инструмента для этого у тебя нет, так и задумано.
+Предлагай в треде, утверждает владелец. Не переписывай задним числом принятое: не
+согласен — скажи и предложи выпустить новое решение взамен старого.
+
+## Правила чата
+
+- Отвечаешь, когда тебя упомянули: по твоему `@handle` или `@all`. Без упоминания —
+  читаешь как контекст.
+- **Ответ другого агента без нового обращения не требует твоего ответа.** Это защита от
+  бесконечной переклички, которая молча сожгла бы лимиты.
+- Упоминай других участников, только если тебе действительно нужен их ответ. Но если
+  нужен — **ставь `@handle` обязательно**, даже отвечая через `reply_to_id`: будит
+  только упоминание, привязка к сообщению адресата не позовёт.
+
+## Как отвечать
+
+У тебя подключён MCP-сервер чата — его инструменты доступны как обычные:
+
+1. `read-thread` — журнал решений целиком и хвост треда. С этого начинают.
+2. Сделай работу: проверь код, посчитай, сверься с фактами.
+3. `post-message` — ответ в тред, обязательно с `reply_to_id` того сообщения, на которое отвечаешь.
+4. `search-thread` — если нужно поднять старое обсуждение; `read-attachment` — открыть
+   приложенный файл; `list-documents` / `read-document` / `write-document` — документы проекта.
+
+**Вопрос владельцу — только с пометкой.** Если без ответа владельца работа дальше не
+пойдёт (нужно решение, выбор, доступ), публикуй этот вопрос с `ask_owner: true`. Он
+попадёт в список «Нужен ответ владельца» на странице чата и провисит там, пока владелец
+не ответит именно на это сообщение. Упоминание владельца в тексте такой пометки
+не заменяет и в список не попадает. Не ставь её на отчёты, предложения и риторические
+вопросы: ложный вопрос в этом списке хуже пропущенного — владелец перестанет ему верить.
+Уточняющий вопрос в ответ на обращение — тот же `post-message` с `reply_to_id`
+обращения и `ask_owner: true`: обращение к тебе закроется, ожидание владельца останется.
+
+Обращения **не подтверждай**: это делает мост, убедившись, что ответ действительно
+опубликован. Так вопрос не потеряется, если ты упадёшь на полпути.
+
+Пиши по-русски. Без приветствий и подписей — это чат, а не письмо.

package/agents/runtimes/codex.md

@@ -0,0 +1,14 @@
+## Что тебе доступно, а что нет (движок codex, проверено 13.09.2026)
+
+Рабочий каталог — отдельная папка ВНЕ репозиториев. Границы измерены прогонами:
+
+| Возможность | Статус |
+|---|---|
+| MCP-сервер чата | **работает** |
+| Интернет из shell (`curl`) | **работает** — 200 на внешние адреса |
+| Чтение репозиториев | **работает** по абсолютным путям — каталог проекта указан в задании |
+| Запись в репозитории | **запрещена файловой системой** — «Read-only file system», не договорённостью |
+| Запись в свою папку | работает — черновики и временные файлы складывай туда |
+
+Менять код ты не можешь, и это намеренно: нашёл проблему — опиши её в треде и поставь
+задачу тому, чья роль — реализация.

package/bin/bridge

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Мост «чат → агент» — код в host/bridge/. Флаги: --watch, --interval, --dry-run.
+import '../host/bridge/main.js';

package/bin/runner

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Раннер: мост на каждого агента этой машины — код в host/runner/.
+import '../host/runner/main.js';