# Документация (единый корень)

Этот каталог — единый вход для всех материалов. Критические темы собраны в верхнем индексе.

## Быстрый старт (критично)
- Архитектура универсального провайдера: [docs/00_overview/ai_universal_provider_gen.md](00_overview/ai_universal_provider_gen.md)
- Обязательная lifecycle-матрица для сервисов с suspend: [docs/60_strategy/provider_philosophy.md](60_strategy/provider_philosophy.md#7-каноничная-lifecycle-логика-для-сервисов-с-suspendresume)
- Чеклист разработки/клона: [docs/00_overview/dev-clone-checklist.md](00_overview/dev-clone-checklist.md)
- НЛИ/чат-материалы: [docs/00_overview/for_nomo_chat.md](00_overview/for_nomo_chat.md)

## ⛔ API: как работать с токеном (читать перед любым curl!)

**Токены НЕ ПРОТУХАЮТ до декабря 2026.** Они в `secrets/{dev,test,prod}.token`.  
Проверить дату: `python3 -c "import json,base64; t=open('secrets/test.token').read().split('.'); d=json.loads(base64.urlsafe_b64decode(t[1]+'==')); from datetime import datetime,timezone; print(datetime.fromtimestamp(d['exp'],tz=timezone.utc))"`

**Старый API (index.cfm) — DDoS-Guard требует 3 заголовка, иначе 403:**
```bash
curl -s --max-time 10 \
  -H "Authorization: Bearer $(cat secrets/test.token)" \
  -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
  -H "Referer: https://deck-test.ngcloud.ru/" \
  "https://deck-api-test.ngcloud.ru/api/v1/index.cfm?endpoint=/services/90"
```
**Referer должен совпадать со стендом!** Без Referer — 403. Без User-Agent — 403.

**Новый Gateway (lk-api-gateway) — только Authorization:**
```bash
curl -s --max-time 10 \
  -H "Authorization: Bearer $(cat secrets/test.token)" \
  "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc/services/90"
```

| Стенд | Старый API | Новый Gateway | Referer |
|-------|-----------|---------------|---------|
| test | `deck-api-test.ngcloud.ru/api/v1/index.cfm` | `lk-api-gateway-test.ngcloud.ru/api/v1/svc` | `https://deck-test.ngcloud.ru/` |
| dev | `deck-api-dev.ngcloud.ru/api/v1/index.cfm` | `lk-api-gateway-dev.ngcloud.ru/api/v1/svc` | `https://deck-dev.ngcloud.ru/` |
| prod | `deck-api.ngcloud.ru/api/v1/index.cfm` | `lk-api-gateway.ngcloud.ru/api/v1/svc` | `https://deck.ngcloud.ru/` |

## API и схемы
- Алгоритмы API-дискавери: [docs/70_api/api-discovery-algorithms.md](70_api/api-discovery-algorithms.md)
- Полный API-дамп: [docs/70_api/api_analysis/API_DOCUMENTATION_SUMMARY.md](70_api/api_analysis/API_DOCUMENTATION_SUMMARY.md)

## Discovery (полевая информация)
- Сервисы и рецепты: [docs/20_discovery](20_discovery)
- Полный дамп параметров API (test): [docs/20_discovery/api_meta_test_dump.md](20_discovery/api_meta_test_dump.md)

## Registry / ресурсы
- Документация реестра: [docs/30_registry](30_registry)

## Аналитика и инциденты
- Анализ HAR: [docs/40_analysis/har](40_analysis/har)
- Анализ провала VM: [docs/40_analysis/vm_creation_failure_analysis.md](40_analysis/vm_creation_failure_analysis.md)
- VDC deployment: [docs/40_analysis/vdc_deployment.md](40_analysis/vdc_deployment.md)

## История изменений
- Хронология: [docs/50_history](50_history)

## Стратегия
- Принципы и подходы: [docs/60_strategy](60_strategy)

## Operations (non-CRUD)
- Операции по каждому сервису: [docs/30_registry/resources/operations/index.md](30_registry/resources/operations/index.md)

## S3 события и интеграции
- Изменения в бакете и вызов функции: [docs/30_registry/guides/s3-bucket-notifications.md](30_registry/guides/s3-bucket-notifications.md)