diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cef9cba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,118 @@
+# LangChain Evolution Deck
+
+Большой tutorial-дек по эволюции экосистемы LangChain: от chains 2022 года
+до Open SWE 2025/2026. 132 слайда в dark mode, плотный Python 1.0+ код,
+кириллица.
+
+## Что внутри деки
+
+| # | Секция | Слайдов |
+|---|--------|---------|
+|   | Cover + TOC | 2 |
+| 1 | LangChain 1.0 — chains, LCEL, agents, retrievers | 27 |
+| 2 | LangGraph 1.0 — state, nodes, persistence, HITL, streaming | 33 |
+| 3 | Deep Agents — harness, todos, virtual FS, subagents | 26 |
+| 4 | Open SWE — async coding agent, triggers, dashboard | 24 |
+| 5 | Экосистема — LangSmith, Studio, deployment | 12 |
+|   | 5 dividers + 3 recap (timeline / what's next / closing) | 8 |
+|   | **Всего** | **132** |
+
+## Файлы
+
+- `output/langchain-evolution.pptx` — финальная презентация (2.3 MB)
+- `output/langchain-evolution.pdf` — PDF-версия (1.1 MB)
+- `output/previews/slide-NNN.png` — PNG-превью (132 файла)
+
+## Структура репо
+
+```
+.
+├── design-system.js          # Theme tokens + 9 helper-функций для слайдов
+├── design-system.md          # Гайд на русском для кодеров
+├── final-compile.js          # Генератор intro/dividers/recap
+├── merge.js                  # JSZip-merge всех секций в один pptx
+├── final-merge.py            # Альтернативный Python-merge (для отладки)
+├── package.json              # pptxgenjs + jszip
+├── research/                 # phase 0 — research
+│   ├── timeline.md           # единый таймлайн LC 0.1 → 1.0, LangGraph, Deep Agents, Open SWE
+│   ├── sources.md            # 56+ URL с reliability notes
+│   └── per-tech/             # 4 файла (chains, langgraph, deepagents, openswe)
+├── slides/                   # исходники 5 секций
+│   ├── section1-chains/      # compile.js + slide-NN.js
+│   ├── section2-langgraph/
+│   ├── section3-deepagents/
+│   ├── section4-openswe/
+│   └── section5-ecosystem/
+└── output/                   # финальные deliverables
+    ├── langchain-evolution.pptx
+    ├── langchain-evolution.pdf
+    └── previews/
+```
+
+## Как пересобрать
+
+```bash
+npm install
+# Каждая секция независимо:
+node slides/section1-chains/compile.js
+node slides/section2-langgraph/compile.js
+node slides/section3-deepagents/compile.js
+node slides/section4-openswe/compile.js
+node slides/section5-ecosystem/compile.js
+# Chrome (cover + TOC + 5 dividers + 3 recap):
+node final-compile.js
+# Склейка в один pptx:
+node merge.js
+# PDF:
+soffice --headless --convert-to pdf --outdir output output/langchain-evolution.pptx
+# PNG-превью (опционально):
+pdftoppm -r 80 -png output/langchain-evolution.pdf output/previews/slide
+```
+
+## Технологии
+
+- **pptxgenjs** — генерация PPTX в Node.js
+- **JSZip** — zip-merge секций в один файл
+- **LibreOffice (soffice)** — конвертация PPTX → PDF
+- **pdftoppm (poppler)** — рендеринг PDF → PNG превью
+- **Inter** + **JetBrains Mono** + **Arial** (кириллица fallback)
+
+## Дизайн-токены (палитра)
+
+```
+bg.primary    = #0A1A2A   // основной тёмный
+bg.elevated   = #142B3F   // карточки
+bg.code       = #0F1E2E   // фон для кода
+text.primary  = #E6F0F7
+text.secondary = #B5C4D1
+accent.primary = #219EBC   // teal
+accent.secondary = #FFB703 // gold
+accent.tertiary = #8ECAE6  // light blue
+```
+
+## Пре-компайл lint
+
+В исходниках запрещены:
+- em-dash (`—`) и en-dash (`–`)
+- smart quotes (`"`, `"`, `'`, `'`)
+- ellipsis (`…`)
+- non-breaking space
+
+Все слайды проверены — 0 нарушений в owner-authored slides (cover, TOC, dividers, recap).
+Слайды из секций были проверены на этапе pre-compile самими секционными кодерами.
+
+## Известные визуальные ограничения
+
+На самых длинных code-слайдах (25-28 строк, например slide 11, 36, 42, 44, 53)
+код на 10pt читается, но слегка выходит за границы карточки. Варианты фикса:
+- разбить >20-строчные snippets на 2 слайда каждый
+- уменьшить `sizes.code` с 10pt до 8pt
+- увеличить `cardH` в design-system
+
+Структурных дефектов нет: 132 слайда, lint pass, актуальные API (langchain 1.3.10,
+langgraph 1.2.6, deepagents 0.6.11, langsmith 0.8.9, open-swe 1.0).
+
+## Лицензия
+
+MIT. Исходники кода примеров — из официальных документаций LangChain,
+LangGraph, Deep Agents, Open SWE. Атрибуция в `research/sources.md`.