# LLM-генерация документации (120B)

## Идея

Вместо шаблонного `docs-generator` (который просто раскладывает YAML по таблицам), использовать LLM для генерации человекочитаемой документации с пониманием контекста.

## Модель

`gpt-oss-120b` через API `api.aillm.ru`.

## Как работает

1. `yaml-generator` получает полный YAML-спек сервиса из API Nubes
2. YAML (все операции, параметры, подсвойства map-fixed, MAN) подаётся LLM
3. LLM генерирует Markdown-страницу документации
4. Результат сохраняется в `docs/30_registry/resources/{service}.md`

## Универсальный промпт

```
Ты — генератор документации Terraform-провайдера Nubes Cloud.
Отвечай ТОЛЬКО Markdown-кодом.

⛔ ЖЁСТКИЕ ПРАВИЛА (нарушать нельзя):

1. НЕ ВЫДУМЫВАЙ параметры. Только те, что есть в YAML.
   Если у параметра нет description — напиши "—".
   НИКОГДА не придумывай password, role, encoding и т.п.

2. Action-операции. ТОЛЬКО redeploy включается в документацию.
   restart, recovery, reconcile — ИСКЛЮЧИТЬ.

3. Subresource-операции. Каждый subresource → отдельная секция.
   Имя ресурса: nubes_{service}_{subresource}.

4. Lifecycle. suspend_on_destroy=true → "terraform destroy = Suspend".
   adopt_existing_on_create → "terraform apply может подхватить существующий".

5. Outputs. Все поля из outputs.params. vault_secrets помечать как 🔒.

6. MAN. Если service_man есть — вставить как есть в секцию ## MAN.

ФОРМАТ:
# Resource nubes_{name}
## MAN (если есть)
## Instance Operations (таблица)
## Create Parameters (таблица)
## Subresources (таблица по каждому)
## Lifecycle
## Outputs (таблица)

YAML-спек:
```yaml
{содержимое YAML-файла}
```
```

## Результаты тестирования (PostgreSQL)

| Критерий | Результат |
|---|---|
| Выдуманные параметры | ❌ 0 (было: password, roles, encoding) |
| Action-операции исключены | ✅ restart/recovery/reconcile |
| Subresources | ✅ user, database, backup |
| Параметры из YAML | ✅ username, role, dbName, dbOwner |
| Допустимые значения | ✅ app_user/ddl_user |
| Regex-ограничения | ✅ ^[A-Za-z0-9]+$ |
| Outputs | ✅ все 8 полей |
| Lifecycle | ✅ suspend_on_destroy=true |

## Ограничения

- `map-fixed` параметры описываются как "составной параметр" без подсвойств
- Нужен Jenkins-ендпоинт для получения sub_fields для map-fixed
- С полными данными оценка будет 10/10

## Интеграция в пайплайн

Предлагаемое место — после `01_generate_yamls.sh`, вместо текущего `02_generate_resources_and_docs_v2.sh` для docs-части:

```
01_generate_yamls.sh → YAML
                    ↓
              LLM-генератор → Markdown-доки
              resource-generator → Go-ресурсы
```