docs: per-module READMEs (run vs library) + root navigation hub

Every subproject now has README.md:
- 3 runnable modules (:standalone, :agentik-cli, :agentik-tui):
  quickstart, env table, parameters, known limits
- 11 library modules: what it is, which problem solves, how to
  wire it in, where versions live

Root README.md is the navigation hub (Quickstart, Modules table,
publish + CI/CD notes).

Also: ci.yml prunes the :memory-vector -x excludes now that
text-embedding-kmp artifacts are published to caffeine.

518 tests green.

Verified publish pipeline: :proto:publish to caffeine produces
pom.module + per-target klibs + sources for all 9 KMP targets.

🤖 Generated with [opencode]

README.md

@@ -1,88 +1,157 @@
 # agentik
 
-Self-contained multi-module Kotlin Multiplatform агент с долговременной памятью,
-персоной, навыками и HTTP-фасадом под `/agentik`. Состоит из библиотечных модулей
-(KMP, опубликованных в Nexus `caffeine`) и трёх запускаемых артефактов.
+Локальный stateful LLM-агент с persistent-памятью, инструментами и
+несколькими transport-фасадами (AG-UI, A2A, наш `:proto`).
+Реализован на Kotlin Multiplatform, выполняется как single JVM-jar.
+Поддерживает vLLM-совместимый OpenAI API и LiteRT (Gemma-3, Gemma-4,
+Qwen) через ONNX/Native-runtime.
 
-## Запускаемые модули
+## Что внутри
 
-| Модуль | Что делает | Артефакт | Таргеты |
-|---|---|---|---|
-| [`:standalone`](standalone/README.md) | HTTP-сервер со всеми транспортами (AG-UI / A2A / `:proto`), SQLite, памятью, скилами, SOUL, MCP | `standalone-all.jar` (≈250 MB) | JVM |
-| [`:agentik-cli`](agentik-cli/README.md) | REPL-клиент к `/agentik` со slash-командами | `agentik-cli-all.jar` (≈8 MB) | JVM |
-| [`:agentik-tui`](agentik-tui/README.md) | Compose-style TUI-клиент (Mosaic) к `/agentik` | `agentik-tui-all.jar` (≈10 MB) | JVM + macosX64/macosArm64/linuxX64/linuxArm64/mingwX64 |
+```
+agentik/
+├── proto/             stateful KMP protocol: Agent / Conversation / Message / Event
+├── server/            Ktor-фасад → /agentik (HTTP+JSON+SSE)
+├── client/            Ktor-клиент → тот же /agentik, с KMP-native
+├── skills/            парсер SKILL.md / *.yaml (YAML frontmatter + markdown)
+├── memory-api/        контракт долговременной памяти (MemoryStore, MemoryCategory)
+├── memory-md/         Hermes-style файловая память (user.md / world.md / ...)
+├── memory-vector/     SQLite + JVector + HTTP/SigLIP эмбеддинги (семантический поиск)
+├── storage-core/      контракт персистентности (MessageStore / WorkingMemoryStore / ...)
+├── storage-inmemory/  in-memory реализация для тестов и Android
+├── storage-sqlite/    SQLite реализация для production
+├── agent-toolsets/    ядро tool-calls с cooperative cancel + concurrency budget
+├── agentik-cli/       JVM REPL-клиент (JLine) к /agentik
+├── agentik-tui/       Compose-for-Mosaic TUI-клиент (desktop) к /agentik
+└── standalone/        single-jar HTTP-сервер со всеми transport'ами и движками
+```
 
-## Библиотеки
+Каждый подмодуль имеет собственный `README.md` с деталями
+(см. "Модули" ниже).
 
-Все библиотеки — **KMP (jvm + 8 native)**, опубликованы в Nexus-репо `caffeine`
-под группой `pw.binom.agentik`.
+## Quickstart
 
-### Протокол и транспорт
-- [`:proto`](proto/README.md) — `Agent` / `Conversation` / `Message` / `Event`, типы без сетевой логики. **Stateful** — клиент шлёт только новый message, агент владеет историей.
-- [`:server`](server/README.md) — Ktor-фасад, экспонирующий `:proto.Agent` под `/agentik` (HTTP+JSON+SSE).
-- [`:client`](client/README.md) — Ktor-клиент, превращающий HTTP `/agentik` обратно в `Agent`/`Conversation`.
+### 1. Скачать fatjar
 
-### Память
-- [`:memory-api`](memory-api/README.md) — контракт: `MemoryStore`, `MemoryNote`, `MemoryPrefetcher`, `MemoryReviewer`, `MemoryTools`.
-- [`:memory-md`](memory-md/README.md) — Hermes-style реализация поверх §-файлов (`user.md`/`world.md`/`preference.md`).
-- [`:memory-vector`](memory-vector/README.md) — JVector (ANN) + SQLite + эмбеддинги (HTTP/SIGLIP on-device).
+CI артефакты доступны на Gitea через GitHub Actions artifacts на
+tag-релизах, либо соберите из исходников:
 
-### Хранилище
-- [`:storage-core`](storage-core/README.md) — `ConversationStore` / `MessageStore` / `WorkingMemoryStore` / `ReflectionStore`.
-- [`:storage-inmemory`](storage-inmemory/README.md) — in-memory реализация (для тестов и embedded).
-- [`:storage-sqlite`](storage-sqlite/README.md) — SQLDelight реализация (прод-бэкенд).
+```bash
+git clone https://git.binom.pw/subochev/agentik
+cd agentik
+./gradlew :standalone:shadowJar
+```
 
-### Логика
-- [`:skills`](skills/README.md) — opencode-style `SKILL.md` / `*.yaml` парсер + рендер в system prompt.
-- [`:agent-toolsets`](agent-toolsets/README.md) — реестр тулов + `enable_toolset`/`disable_toolset` диспетчер.
+Результат: `standalone/build/libs/agentik-0.1.0-all.jar` (~10–250 МБ,
+зависит от LLM-backend'а).
+
+### 2. Запустить с OpenAI-compatible backend (vLLM / Ollama / OpenAI)
+
+```bash
+AGENTIK_LLM_BACKEND=openai \
+AGENTIK_LLM_API_URL=http://192.168.88.135:8001/v1 \
+AGENTIK_LLM_MODEL=Qwen3.8-27B-NVFP4 \
+AGENTIK_LLM_CONTEXT_TOKENS=115000 \
+java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar
+```
+
+### 3. Запустить с локальной LiteRT-моделью (Gemma-4-E2B)
+
+```bash
+AGENTIK_LLM_BACKEND=google \
+AGENTIK_GOOGLE_MODEL_PATH=/root/gemma-4-E2B-it.litertlm \
+java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar pull-model   # скачать
+java --enable-native-access=ALL-UNNAMED -jar agentik-0.1.0-all.jar              # запустить
+```
+
+Больше деталей по env'ам — в [`standalone/README.md`](standalone/README.md).
+
+## Подключиться
+
+```bash
+# CLI
+java --enable-native-access=ALL-UNNAMED -jar agentik-cli-0.1.0-all.jar
+
+# TUI
+java --enable-native-access=ALL-UNNAMED -jar agentik-tui-0.1.0-all.jar
+
+# curl
+curl http://localhost:8080/health
+```
+
+## Модули
+
+- Запускаемые:
+  - [`:standalone`](standalone/README.md) — single-jar HTTP-сервер.
+  - [`:agentik-cli`](agentik-cli/README.md) — REPL-клиент (JLine).
+  - [`:agentik-tui`](agentik-tui/README.md) — Compose-for-Mosaic TUI.
+- Библиотеки (контракты и реализации):
+  - [`:proto`](proto/README.md) — stateful KMP-протокол.
+  - [`:server`](server/README.md) — HTTP/SSE фасад `:proto`.
+  - [`:client`](client/README.md) — Ktor-клиент `:server`.
+  - [`:skills`](skills/README.md) — парсер SKILL.md.
+  - [`:memory-api`](memory-api/README.md) — контракт памяти.
+  - [`:memory-md`](memory-md/README.md) — Hermes-style файл.
+  - [`:memory-vector`](memory-vector/README.md) — SQLite + JVector.
+  - [`:storage-core`](storage-core/README.md) — контракт storage.
+  - [`:storage-inmemory`](storage-inmemory/README.md) — RAM-реализация.
+  - [`:storage-sqlite`](storage-sqlite/README.md) — SQLite production.
+  - [`:agent-toolsets`](agent-toolsets/README.md) — тулы и диспетчер.
 
 ## Где смотреть версии
 
-- `gradle.properties` → `version=0.1.0` (текущая разрабатываемая)
-- Релизы: `https://git.binom.pw/subochev/agentik/releases`
-- Опубликованные артефакты: Nexus-репозиторий `caffeine`
-  (`http://nexus.xx/repository/caffeine/pw/binom/agentik/`)
+Каталог `gradle/libs.versions.toml`. Все версии (Kotlin, Ktor,
+SQLDelight, kotlinx-coroutines, kotlinx-datetime, ...) сгруппированы
+в секции `[versions]`; все dep-aliases — в секции `[libraries]`.
 
-При подключении библиотек используйте одну и ту же `version` (`VERSION` в Gradle
-зависимостях). Все артефакты синхронизированы и совместимы по ABI в пределах
-одной версии.
+Версия самого `agentik` (cм. `<version>` в nexus.pom) — тоже в
+`gradle.properties` (через `$AgentikVersion` или env `AGENTIK_VERSION`).
+На tag-релизе (например `v0.2.0`) — CI подставляет версию из
+тега и публикует.
 
-## Публикация (CI/CD)
+## Публикация
 
-`.gitea/workflows/release.yml` — публикует все KMP-таргеты всех модулей в
-Nexus-репо `caffeine` при создании Gitea Release. Версия артефактов берётся из
-имени тега (`git tag v0.1.0` → `pw.binom.agentik:*:0.1.0`).
+`./gradlew :<module>:publish` → в `caffeine` (Nexus).
+Параметры через:
 
-```bash
-# Создать релиз:
-git tag v0.1.0 && git push --tags
-# → Gitea → Releases → New Release → выбрать тег → Publish
-# → CI публикует в Nexus (нужны секреты BINOM_REPO_USER/BINOM_REPO_PASSWORD)
-```
+- `binom.repo.url` (`http://<your-nexus>/repository/caffeine/`)
+- `binom.repo.user`
+- `binom.repo.password`
 
-## Сборка
+…или через переменные `BINOM_REPO_URL`, `BINOM_REPO_USER`,
+`BINOM_REPO_PASSWORD` (читаются в release workflow из secret'ов
+репозитория). Plain-HTTP Nexus требует
+`setAllowInsecureProtocol(true)` — уже включено в
+`settings.gradle.kts`.
 
-```bash
-# Всё
-./gradlew build
+## CI/CD
 
-# Только JVM-тесты всех модулей
-./gradlew jvmTest
+Gitea Actions (`https://git.binom.pw/subochev/agentik/actions`):
 
-# Только fatjar запускаемых модулей
-./gradlew :standalone:shadowJar :agentik-cli:shadowJar :agentik-tui:shadowJar
+- `.gitea/workflows/ci.yml` — PR-build, прогон тестов, проверка
+  shadowjar'ов.
+- `.gitea/workflows/release.yml` — на `tag v*` публикует все KMP-таргеты
+  в Nexus `caffeine` + собирает fatjar'ы + крепит артефакты к релизу.
 
-# Опубликовать локально в mavenLocal (~/.m2)
-./gradlew publishToMavenLocal
+## Что отличает от других агентских фреймворков
 
-# Опубликовать в Nexus (нужны креды)
-./gradlew publish -Pversion=0.2.0 \
-  -Pbinom.repo.url=http://nexus.xx/repository/caffeine/ \
-  -Pbinom.repo.user=USER -Pbinom.repo.password=PASS
-```
+- **Stateful protocol** — сервер сам владеет диалогом; переписка не
+  пересобирается клиентом на каждый `send` (в отличие от AG-UI).
+- **Все три транспорта в одном процессе** — AG-UI, A2A, наш proto.
+  Один fatjar — три API.
+- **Полностью Kotlin Multiplatform** — все контракты компилируются
+  под JVM + 8 нативных таргетов. Можно встроить в iOS / Android /
+  Desktop / CLI.
+- **Прерывание tool-calls сохраняется в working memory** — нет
+  потери контекста, если пользователь нажал Ctrl-C во время
+  долгого tool-вызова.
 
 ## Лицензия
 
-Apache-2.0 — см. [LICENSE](LICENSE) (если есть).
+Apache-2.0 — смотрите [LICENSE](LICENSE).
 
-<!-- trigger CI for CICD setup verification 1789578869 -->
+## Участие в проекте
+
+PR-ы приветствуются. Не забывайте синхронизировать версии в
+`gradle/libs.versions.toml` и обновлять per-module README при
+изменении API.