diff --git a/README.md b/README.md
index e25449a..9897ca8 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,66 @@
Локальный ассистент для поиска по техническим документам и исходному коду, а также подготовки небольших проверяемых изменений.
+## Как система должна работать
+
+На POC все компоненты размещаются на одном домашнем ПК. Разработчик задаёт вопрос или coding-задачу; система находит только разрешённый контекст, передаёт его локальной модели и проверяет ответ или patch. Ни код, ни запросы не отправляются во внешние AI-сервисы.
+
+```mermaid
+flowchart TB
+ subgraph PC["POC: один домашний ПК — целевой RTX 4070 Ti, 32 GB RAM"]
+ DEV["Разработчик
CLI сейчас; IDE-клиент — целевой интерфейс"]
+ AUTH["Проверка пользователя и проекта
локальный token + project ACL"]
+ ORCH["Оркестратор
управляет поиском, моделью и лимитами"]
+
+ subgraph INDEX["Индексация — подготовка данных"]
+ DOCS["Документы
data/synthetic — сейчас"]
+ CODE["Git-код
exchange-demo — сейчас"]
+ PARSE["Разбиение на фрагменты
Tree-sitter для Python"]
+ EMB["Embedding model
должна работать локально
сейчас embeddings fake"]
+ DB[("PostgreSQL + pgvector
текст, векторы, ACL, commit SHA")]
+ DOCS --> PARSE
+ CODE --> PARSE
+ PARSE --> EMB --> DB
+ end
+
+ RETR["RAG retrieval
ACL фильтрует до поиска
text + vector candidates"]
+ RANK["Объединение результатов
RRF + citations
reranker пока не подключён"]
+ LLM["Локальная LLM на этом ПК
provider реализован
реальная модель/GPU ещё не проверены"]
+
+ ANSWER["Проверка ответа
citations и простые проверки
при нехватке evidence — отказ"]
+ RESPONSE["Ответ разработчику
текст + источники"]
+
+ PATCH["Проверка unified diff
пути, формат, git apply --check"]
+ WT["Отдельный Git worktree
исходный checkout не меняется"]
+ BOX["Docker sandbox
network=none, лимиты, timeout"]
+ REPAIR["Проверка compileall + tests
при ошибке: до 2 repair-попыток"]
+ REVIEW["Человек проверяет diff
merge автоматом запрещён"]
+
+ DEV --> AUTH --> ORCH
+ ORCH --> RETR
+ DB --> RETR --> RANK --> LLM
+ LLM --> ANSWER --> RESPONSE
+ LLM --> PATCH --> WT --> BOX --> REPAIR
+ REPAIR -->|"не прошли — ограниченная обратная связь"| LLM
+ REPAIR -->|"прошли"| REVIEW
+ end
+
+ RAGREF["rag-mcp-agent
отдельный RAG/MCP demo"] -. "архитектурный источник опыта;
не runtime-компонент" .-> RANK
+```
+
+### Что происходит на схеме
+
+1. **Индексация:** документы и выбранный Git commit разбиваются на фрагменты. Локальная embedding-модель должна превратить их в векторы; сейчас это место занято fake embeddings. Фрагменты, текстовый индекс, права и версии хранятся в PostgreSQL/pgvector.
+2. **Поиск:** ACL отсекает недоступные проекты до поиска. Текстовый и векторный поиск дают кандидатов; RRF объединяет их. Из найденных фрагментов строятся citations.
+3. **Ответ:** локальная LLM получает вопрос и ограниченный найденный контекст. Проверка не доказывает каждое утверждение модели: она проверяет citations и некоторые простые свойства, а при недостатке evidence должна отказать.
+4. **Изменение кода:** LLM предлагает только diff. Код проверяет diff, применяет его в отдельном worktree, запускает Docker-проверки без сети и возвращает diff человеку. При ошибке разрешено не больше двух повторных попыток.
+
+`rag-mcp-agent` показан пунктиром, потому что это отдельный демонстрационный проект и источник архитектурных идей. Он не запускается внутри приложения. Целевой интерфейс — локальная IDE/оболочка, а не MCP; текущий coding POC запускается через CLI. Provider в имеющемся коде использует loopback-соединение с локальным inference server — это не внешний AI API.
+
+### Домашний POC и enterprise-развёртывание
+
+Схема выше — проверка на одном целевом ПК, а не схема на 100 пользователей. В enterprise те же логические блоки размещаются внутри закрытой сети: разработчики входят через SSO и project/repository ACL, LLM и embeddings обслуживаются внутренним GPU-пулом, запросы идут через очереди с квотами, а coding-проверки запускаются на отдельных изолированных workers. Производительность для 10 проектов и примерно 100 разработчиков пока не измерена и не обещается.
+
## Статус проекта
Это pre-enterprise POC, не готовый продукт для команды и не production-система.