diff --git a/Dockerfile b/Dockerfile
index 770ced0..3c98179 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,7 +5,7 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci --omit=dev
 
-COPY server.js ./
+COPY server.js assist.js search.js stage1.js stage2.js orchestrator.js ./
 
 ENV NODE_ENV=production
 
diff --git a/README.md b/README.md
index 77cbabd..57c9372 100644
--- a/README.md
+++ b/README.md
@@ -5,3 +5,40 @@
 Репозиторий создан как основа для документации по проекту Terraform (провайдеры, модули, схемы, история изменений и т.д.).
 
 Содержимое будет дополняться по мере развития проекта.
+
+## AI-ассистент документации
+
+Сервис — обратный прокси статики документации и эндпоинт AI-ассистента.
+
+### Эндпоинт
+
+`POST /<stand>/_api/assist` — тело `{"question": "текст вопроса"}`.
+
+Ответ 200:
+```json
+{
+  "answer": "ответ по шаблону Роль/Задача/Контекст/Требования/Ограничения",
+  "sources": [{"title": "...", "url": "/<stand>/..."}],
+  "meta": {"model": "...", "resource_type": "nubes_...", "elapsed_ms": 1234}
+}
+```
+
+Ошибки (JSON `{"error": code, "message": ...}`): 400/413/415 (невалидный ввод), 429 (rate-limit, `Retry-After`), 502 (`bad_llm_output`), 503 (busy / индекс недоступен).
+
+### Переменные окружения
+
+| Имя | По умолчанию | Назначение |
+|---|---|---|
+| `VM_DOCS_BASE_URL` | — (обязательна) | базовый URL статики (upstream) |
+| `LLM_BASE_URL` | — | `https://api.aillm.ru` |
+| `LLM_API_KEY` | — | ключ ЛЛМ (брать из Secret, не логировать) |
+| `LLM_MODEL` | `gpt-oss-120b` | модель |
+| `ASSIST_MAX_CONCURRENT` | `4` | семафор одновременных вызовов ЛЛМ |
+| `ASSIST_TOTAL_DEADLINE_MS` | `40000` | общий дедлайн запроса |
+| `ASSIST_LLM_TIMEOUT_MS` | `25000` | таймаут одного вызова ЛЛМ |
+| `ASSIST_RATE_PER_WINDOW` | `6` | лимит запросов на IP за окно |
+| `ASSIST_RATE_WINDOW_MS` | `60000` | окно rate-limit |
+| `ASSIST_REPLICAS` | `1` | число реплик (для деления лимита) |
+| `ASSIST_MAX_BODY` | `2048` | макс. размер тела запроса |
+| `ASSIST_TRUSTED_PROXY_CIDR` | — | CIDR доверенного proxy (для `X-Forwarded-For`) |
+