From 3248412cae469881d14d8cbd649309024f1cdb8c Mon Sep 17 00:00:00 2001
From: matt2dev <matt2dev@bearsdev.tech>
Date: Sun, 26 Jul 2026 15:41:24 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20add=20AGENTS.md=20+=20CLAUDE.md=20symli?=
 =?UTF-8?q?nk=20+=20docs/HANDOFF.md=20per=20bearsdev-systems=20repo=20stan?=
 =?UTF-8?q?dard=20(=D0=A44=20pilot)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md       | 44 ++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md       |  1 +
 docs/HANDOFF.md | 26 ++++++++++++++++++++++++++
 3 files changed, 71 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md
 create mode 100644 docs/HANDOFF.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..dee722a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# AGENTS.md — agent-news
+
+Telegram-бот на Dart: по команде `/news [тема]` спавнит Claude Code CLI как сабпроцесс для
+ресёрча, финальную выжимку (и промежуточные статусы) Claude сам шлёт в Telegram через
+собственный MCP-сервер. Полное описание архитектуры — `README.md`.
+
+## Структура (монорепо, 3 части)
+
+- `bot/` — Dart, long-polling Telegram-бот. Точка входа `bot/bin/agent_news_bot.dart`.
+  Спавнит `claude` как сабпроцесс (`bot/lib/claude_runner.dart`).
+- `mcp_server/` — Dart, stdio MCP-сервер. Спавнится самим `claude` (не ботом напрямую),
+  экспортирует тул `send_to_telegram`. Точка входа `mcp_server/bin/agent_news_mcp.dart`.
+- `runner/` — `Dockerfile` (3-стадийная сборка: bot-build → mcp-build → runtime с
+  `claude-code` CLI) + `claude-config/mcp.json` (конфиг MCP для Claude Code внутри контейнера).
+
+Все тексты, которые бот показывает пользователю или подставляет в промпт Claude — в одном
+месте: `bot/lib/lexicon.dart`. Новый текст/сообщение — туда, не разбрасывать по коду.
+
+## Сборка и проверка
+
+```bash
+cd bot && dart pub get && dart analyze
+cd ../mcp_server && dart pub get && dart analyze
+```
+
+Тестов (`dart test`) нет — только `dart analyze`. Полная сборка — через Docker
+(`docker compose up -d --build`), см. `README.md` §Запуск локально.
+
+## Конвенции
+
+- SDK `^3.11.0` в обоих `pubspec.yaml` — держать одинаковым между `bot/` и `mcp_server/`.
+- Комментарии в коде — по-русски, только там, где неочевидная причина (не «что», а «почему»),
+  см. стиль в `runner/Dockerfile`.
+
+## Грабли
+
+- **`~/.claude.json` живёт вне `~/.claude/`.** Авторизация Claude Code CLI пишет не только в
+  `~/.claude/`, но и в отдельный файл `~/.claude.json` — поэтому в `docker-compose.yml`
+  примонтирован volume на **весь `/home/agent`**, не только `~/.claude/`. Если когда-нибудь
+  захочется сузить volume до `~/.claude/` — логин будет слетать при каждом рестарте.
+- **`claude-config/` скопирован вне `/home/agent`** (в `/app/claude-config`) по той же причине —
+  положи его внутрь home, и он потеряется под пустым volume при первом старте контейнера.
+- Ресёрч занимает несколько минут (`CLAUDE_TIMEOUT_SECONDS`, по умолчанию 600) — это нормально,
+  не таймаут/баг.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md
new file mode 100644
index 0000000..2fd81b9
--- /dev/null
+++ b/docs/HANDOFF.md
@@ -0,0 +1,26 @@
+# HANDOFF — agent-news
+
+Актуально на: 2026-07-26
+
+## Где мы сейчас
+
+Рабочий прототип: бот на Dart принимает `/news [тема]`, спавнит Claude Code CLI, тот делает
+ресёрч и через собственный MCP-сервер (`send_to_telegram`) шлёт промежуточные статусы и финальную
+выжимку обратно в Telegram. Всё в одном Docker-контейнере (3-стадийная сборка). Последний коммит
+2026-07-21 — «Scope down to local Docker testing, drop Gitea/K3s plumbing for now»: осознанно
+сузили до локального запуска, отложив деплой в кластер и CI.
+
+Гоняется только локально (`docker compose up`), в K3s не задеплоен, CI/deploy-репо нет.
+
+## Следующий шаг
+
+Не зафиксирован явно в репо — решать по факту, когда возвращаться к проекту (например: возврат
+к деплою в кластер по стандартному CI-паттерну, см. `knowledge/cicd.md` в `bearsdev-systems`).
+
+## Открытые вопросы
+
+- Деплой в K3s — реализовать или проект так и останется локальным «для себя»?
+
+## Грабли
+
+См. `AGENTS.md` §Грабли — home-volume для `~/.claude.json`, расположение `claude-config/`.