diff --git a/CHAT_SUMMARY_2026-08-06.md b/HISTORY/CHAT_SUMMARY_2026-08-06.md
similarity index 100%
rename from CHAT_SUMMARY_2026-08-06.md
rename to HISTORY/CHAT_SUMMARY_2026-08-06.md
diff --git a/REGISTRY_OVERVIEW.md b/HISTORY/REGISTRY_OVERVIEW.md
similarity index 100%
rename from REGISTRY_OVERVIEW.md
rename to HISTORY/REGISTRY_OVERVIEW.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..865ec9f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# Terraform Provider Registry
+
+Реестр Terraform-провайдеров по протоколу HashiCorp.
+Деплой: Docker-контейнер в Nubes Cloud (`containerk8s`).
+
+**URL:** `https://registry.containerk8s.dev.nubes.ru`
+
+## Структура
+
+```
+├── server/           # Go-код HTTP-сервера
+│   ├── main.go       # Роуты, S3, структуры
+│   ├── gpg_key.go    # GPG-ключи (2 шт.)
+│   ├── docs.go       # Статика документации из S3
+│   ├── build-provider.sh  # Сборка и заливка провайдера
+│   ├── go.mod / go.sum
+│   └── gpg/
+├── tests/
+│   └── smoke.sh      # 9 интеграционных тестов
+├── secrets/          # Креды (в .gitignore)
+├── HISTORY/          # Документация, планы, ревью
+├── Dockerfile        # Multi-stage сборка (ветка go-container)
+└── .gitignore
+```
+
+## Эндпоинты
+
+| Метод | URL | Ответ |
+|---|---|---|
+| GET | `/` | HTML с версией |
+| GET | `/.well-known/terraform.json` | `{"providers.v1":"/v1/providers/"}` |
+| GET | `/v1/providers/{ns}/{name}/versions` | JSON: список версий и платформ |
+| GET | `/v1/providers/{ns}/{name}/{ver}/download/{os}/{arch}` | JSON: download_url, shasum, GPG |
+| GET | `/v1/proxy?key=...` | Стриминг файла из S3 |
+| GET | `/docs/{ns}/{name}/{ver}/...` | Статика документации из S3 |
+| GET | `/healthz` | `ok` 200 |
+| GET | `/readyz` | `ok` 200 (проверяет S3) |
+
+## Сборка и деплой
+
+```bash
+# Сборка образа (на ВМ)
+ssh naeel@5.172.178.213
+cd ~/tf_registry && git checkout go-container
+docker build -t gitea.services.ngcloud.ru/nail/tf_registry:latest .
+docker push gitea.services.ngcloud.ru/nail/tf_registry:latest
+
+# Редеплой — через UI modify или пересоздать инстанс
+```
+
+## Заливка провайдера
+
+Подробно: `HISTORY/HOWTO-UPLOAD.md`
+
+Кратко:
+```bash
+export REGISTRY_HOSTNAME=registry.containerk8s.dev.nubes.ru
+export S3_ENDPOINT=http://ceph.tst.nubes.ru
+export S3_ACCESS_KEY=...   # super-креды
+export S3_SECRET_KEY=...
+bash server/build-provider.sh 5.1.17
+```
+
+## Тесты
+
+```bash
+bash tests/smoke.sh
+```
+
+## Конфигурация
+
+| Где | Что |
+|---|---|
+| `jsonEnv` (UI) | Только `S3_ACCESS_KEY`, `S3_SECRET_KEY` (reader) |
+| `Dockerfile ENV` | `S3_ENDPOINT`, `S3_BUCKET`, `S3_PREFIX`, `REGISTRY_HOSTNAME`, `PORT`, `S3_USE_SSL` |
+
+Подробно: `HISTORY/env-config.md`
+
+## Ветки
+
+| Ветка | Назначение |
+|---|---|
+| `master` | Основная, чистый код |
+| `go-container` | Сборка: Go + Dockerfile |
+| `with-flask-legacy` | Архив Flask-версии |
+| `golang` | Архив исходного Go (до правок) |