add: documentation

docs/20_discovery/s3-storage-and-docs-architecture.md

@@ -0,0 +1,21 @@
+# Discovery: S3 Storage & Documentation Architecture
+
+## Архитектура хранения (S3 Cloud)
+В ходе эволюции проекта мы отказались от локального хранилища в пользу облачного Nubes Cloud S3 (`s3.msk-1.ngcloud.ru`).
+
+### Преимущества облачного S3:
+1. **Персистентность:** Артефакты провайдера и файлы документации теперь хранятся независимо от жизненного цикла подов в Kubernetes.
+2. **Безопасность:** Доступ по HTTPS (SSL) и использование выделенных IAM-пользователей.
+3. **Совместимость:** Реестр использует S3‑совместимый SDK, что подтверждает совместимость Nubes S3 с протоколами Amazon.
+
+## Подход к документации (Registry Style)
+Мы внедрили стандарт "Strict Branding", имитирующий официальный реестр Terraform, но в стиле Nubes.
+
+### Ключевые концепции:
+- **Zero-Logic Pathing:** Сервер документации (`docsHandler`) проксирует запросы напрямую в S3 бакет `terraform-registry`. Пути формируются как `docs/{ns}/{name}/{version}/{path}`.
+- **Soft Delete Visibility:** Документирование статусов `Suspended` и `Retention Period` — это критический элемент "правды" между Terraform State и UI облака. Пользователь должен понимать, что ресурс в режиме ожидания удаления — это осознанное состояние платформы.
+
+### Инструментарий:
+- **MkDocs Material:** Генерация статических страниц из Markdown.
+- **Docker-based Build:** Сборка документации изолирована от хоста (используется `squidfunk/mkdocs-material`).
+- **mc (S3 client):** Основной инструмент синхронизации (`mc mirror`) локальных артефактов с облаком.