doc: развёрнутое объяснение — откуда YAML, зачем from_stands.py, когда запускать

README.md

@@ -49,17 +49,62 @@ cd site && python app.py                          # порт 5000
 pytest tests/ -v                                  # 19 тестов
 ```
 
-## Обновление YAML из terraform
+## Откуда берутся сервисы (YAML)
 
-**Вручную** — при каждом изменении в `~/tf_provider/generated/`:
+Polygon эмулирует API Nubes. Чтобы знать какие сервисы, операции и параметры
+существуют — он читает YAML-конфиги. Но Nubes генерит YAML в **другом формате**,
+неудобном для полигона. Поэтому есть двухэтапный процесс:
+
+```
+~/tf_provider/generated/{dev,test,prod}/resources_yaml/*.yaml   ← источник (терраформ)
+        │
+        │  from_stands.py  —  конвертация формата, дедупликация, нормализация
+        │  Запускается ВРУЧНУЮ при изменении терраформ-репы
+        │
+        ▼
+polygon/site/services/{dev,test,prod}/*.yaml   ← скоммичены в git-репу полигона
+        │
+        │  config/loader.py  —  загрузка ВСЕХ YAML в память при старте
+        │
+        ▼
+Память Flask-процесса  (~0.7 MB на 3 стенда)
+```
+
+### Почему нельзя читать терраформ-формат напрямую?
+
+Терраформ-формат хранит параметры **внутри** операций, с дубликатами.
+Например параметр `resourceRealm` повторяется в create, modify и delete —
+три копии одного и того же.
+
+Полигону нужен плоский список **уникальных** параметров (`cfsParams`),
+плюс индекс «какой параметр к какой операции» (`cfsParamsByOp`).
+Плюс `stateParams` (дефолты для create), `stateOut` (subresource-ключи),
+раскодированные HTML-entities (`"` → `"`).
+
+Всё это делает `from_stands.py` **один раз**, а не на лету при каждом запросе.
+
+### Когда запускать обновление?
+
+Когда терраформ-репа обновилась (добавили/удалили сервис, изменили параметры) —
+нужно перегенерить YAML и передеплоить полигон:
 
 ```bash
 cd site
 python from_stands.py ~/tf_provider/generated/dev/resources_yaml  services/dev
 python from_stands.py ~/tf_provider/generated/test/resources_yaml services/test
 python from_stands.py ~/tf_provider/generated/prod/resources_yaml services/prod
-cd .. && git add services/ && git commit -m "regenerate YAML" && git push
-# → редеплоить через Nubes
+
+cd ..
+git add services/
+git commit -m "regenerate YAML from terraform (добавлен сервис X)"
+git push
+# → редеплоить polygon через Nubes UI
+```
+
+### Как проверить что всё загрузилось?
+
+```bash
+curl https://polygon.pythonk8s.dev.nubes.ru/dev/api/v1/svc/services | python3 -m json.tool | head -20
 ```
 
 ## API (17 эндпоинтов)