diff --git a/README.md b/README.md
index 57c9372..862eb02 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,10 @@
 
 Сервис — обратный прокси статики документации и эндпоинт AI-ассистента.
 
+> 📖 **Полная документация ассистента** (архитектура, поиск, безопасность, деплой,
+> эмбеддинги v2, инциденты): [`llm_project/docs/ASSISTANT_ARCHITECTURE.md`](llm_project/docs/ASSISTANT_ARCHITECTURE.md).
+> Карта файлов проекта: [`llm_project/README.md`](llm_project/README.md).
+
 ### Эндпоинт
 
 `POST /<stand>/_api/assist` — тело `{"question": "текст вопроса"}`.
diff --git a/llm_project/README.md b/llm_project/README.md
new file mode 100644
index 0000000..1caf187
--- /dev/null
+++ b/llm_project/README.md
@@ -0,0 +1,45 @@
+# llm_project — карта файлов AI-ассистента
+
+Всё, что связано с AI-ассистентом документации: планы, документация, тесты, диагностика.
+
+## Главное
+
+| Файл | Что |
+|---|---|
+| **[docs/ASSISTANT_ARCHITECTURE.md](docs/ASSISTANT_ARCHITECTURE.md)** | **Полная документация**: архитектура, API, поиск, безопасность, деплой, тесты, эмбеддинги v2, инциденты |
+| [PLAN_docs_ai_assistant_STEPS.md](PLAN_docs_ai_assistant_STEPS.md) | План по шагам (11 этапов) |
+
+## Диагностика и обоснования
+
+| Файл | Что |
+|---|---|
+| [probe/RESULTS.md](probe/RESULTS.md) | Результаты live-проверки `api.aillm.ru` (response_format, reasoning_effort, лимиты) |
+| [probe/probe_aillm.js](probe/probe_aillm.js) | Скрипт-пробник API |
+| [golden/EVAL_1.md](golden/EVAL_1.md) | Оценка поиска на эталонном наборе |
+| [golden/golden_questions.json](golden/golden_questions.json) | 28 эталонных вопросов с ожидаемыми страницами |
+| [tests/ANALYSIS_bad_llm_output.md](tests/ANALYSIS_bad_llm_output.md) | Разбор отказов 502, причины и фиксы |
+
+## Тесты и авто
+
+| Файл | Что |
+|---|---|
+| [tests/run_e2e_live.js](tests/run_e2e_live.js) | Прогон 62 вопросов по живому эндпоинту (учёт 429) |
+| [tests/redeploy.js](tests/redeploy.js) | Redeploy tf-docs через Nubes API |
+| [tests/debug_bad_llm_output.js](tests/debug_bad_llm_output.js) | Захват сырого ответа LLM (диагностика) |
+| [tests/RESULTS_LIVE.md](tests/RESULTS_LIVE.md) / .json | Результаты прогонов (5 итераций) |
+
+## Как запускать
+
+```bash
+# прогон тестов на живом стенде
+node llm_project/tests/run_e2e_live.js --stand nubes-test
+
+# redeploy сервиса
+node llm_project/tests/redeploy.js
+```
+
+## Связанные HowTo
+
+- `~/nubes/HowTo/howto-publish-docs-site.md` — публикация сайта (виджет).
+- `~/nubes/HowTo/howto-tf-docs-redeploy-api.md` — redeploy через API.
+- `~/nubes/HowTo/howto-sync-to-vm213.md` — синк на ВМ 213.