docs(diagrams): agent architecture overview with pre-rendered SVG

PlantUML diagrams for future agent architecture (Android, multi-user
chat, sub-agents, A2A):
- 01-module-layers.md — целевая модульная структура
- 02-agent-composition.md — AgentBuilder DSL + MemoryBackend.exposesTools()
- 03-multi-user-chat.md — mention-detection sequence
- 04-sub-agents.md — spawnChild + Flow<SubAgentEvent> + A2A
- 05-android-stack.md — что меняется на Android vs Standalone

Каждый .md включает пред-рендеренный SVG (показывается во всех markdown
viewers без PlantUML plugin) + PlantUML source в code block (для
редактирования). SVG нужен потому что PlantUML требует Graphviz dot
для рендеринга — без него IntelliJ/VSCode выдают ошибку.

Регенерация SVG после правки PlantUML-source:
  docker run --rm -v "$PWD:/work" plantuml/plantuml -tsvg /work/docs/diagrams/*.md

docs/diagrams/README.md

@@ -0,0 +1,64 @@
+# agentik — диаграммы архитектуры
+
+PlantUML-схемы для обсуждения будущей структуры (Android agent, multi-user chat, sub-agents, A2A). Это **целевое состояние**, не текущее.
+
+## Файлы
+
+Каждый `.md` содержит:
+- Краткое описание (что показывает)
+- **Пред-рендеренный SVG** (`![Diagram](file.svg)`) — гарантированно показывается **везде**
+- PlantUML source в ` ```plantuml ` блоке — для редактирования (требует Graphviz `dot` для рендеринга)
+- Дополнительный markdown-текст (что нужно сделать, текущее vs целевое)
+
+| Файл | Что показывает |
+|---|---|
+| [01-module-layers.md](./01-module-layers.md) | Целевая модульная структура (приложения → runtime → домен → абстракции → платформенные impl). Что в каком слое и кто от кого зависит. |
+| [02-agent-composition.md](./02-agent-composition.md) | Как `AgentBuilder` собирает `BaseAgent` из компонентов. Memory backend сам объявляет свои tools. BackgroundScheduler подписан на события (НЕ interval-poll). |
+| [03-multi-user-chat.md](./03-multi-user-chat.md) | Сценарий: чат с N пользователями, mention-detection, админ-команды, agent отвечает только когда addressed. |
+| [04-sub-agents.md](./04-sub-agents.md) | Orchestrator spawn'ит sub-agent с изолированным контекстом, получает `Flow<SubAgentEvent>`. A2A между независимыми агентами через `:a2a-server`. |
+| [05-android-stack.md](./05-android-stack.md) | Что меняется на Android: on-device LLM (NNAPI), Room/sqlite, ONNX-based vector memory, foreground-service для MCP subprocess. |
+
+## Почему SVG + PlantUML source
+
+PlantUML требует Java + (для component/class/deployment диаграмм) Graphviz `dot`. Если `dot` не установлен — рендерер падает с ошибкой "Executable dot does not exist".
+
+Решение: **пре-рендерим в SVG один раз** и вставляем как `<img>`. Диаграмма гарантированно показывается в любом markdown-viewer (GitHub, IntelliJ, VSCode, GitLab) без зависимостей. PlantUML source в code block остаётся для редактирования.
+
+## Как редактировать диаграмму
+
+1. Меняешь PlantUML-source в ` ```plantuml ` блоке `.md` файла.
+2. Ре-рендеришь SVG:
+   ```bash
+   mkdir -p /tmp/plantuml-work && chmod 777 /tmp/plantuml-work
+   cp docs/diagrams/*.md /tmp/plantuml-work/
+   docker run --rm -v /tmp/plantuml-work:/work plantuml/plantuml -tsvg /work/*.md
+   cp /tmp/plantuml-work/*.svg docs/diagrams/
+   ```
+3. Проверяешь что SVG обновился:
+   ```bash
+   ls -la docs/diagrams/*.svg
+   ```
+4. Коммитишь оба файла: `.md` (source) и `.svg` (rendered).
+
+Требует Docker (или локального PlantUML+Graphviz). `apt install graphviz` для Arch/Manjaro.
+
+## Контекст
+
+Текущий код движется в эту сторону:
+- `:llm-tools` extracted ✅
+- `:mcp-bridge` extracted ✅
+- `BackgroundScheduler` стал event-driven ✅
+- `ConversationLoop` стал отдельным компонентом ✅
+
+Не сделано (см. детали в каждом .md):
+- `:agent-core` (выделить `BaseAgent` + builder)
+- `:background-events` (выделить events + scheduler)
+- `:storage-sqlite-android`, `:memory-vector-android`, `:litert-android`
+- `:agentik-android` (само приложение)
+- `MentionDetector` interface + adapters для multi-user chat
+- `BaseAgent.spawnChild` + `Flow<SubAgentEvent>`
+
+Подробнее:
+- `STANDALONE-REVIEW.md` — что плохо в текущем коде
+- `MEMORY-DESIGN.md` — детали memory архитектуры
+- `STANDALONE.md` — текущий standalone