# Sonnet Briefing: анализ и улучшение документации провайдера

Цель: изучить КАЖДЫЙ шаг генерации документации и предложить конкретные улучшения,
чтобы пользователю было понятно и удобно работать с каждым ресурсом.

---

## ⛔ Файлы — ПРОЧИТАТЬ ОБЯЗАТЕЛЬНО ВСЕ

### Генераторы

| # | Файл | Что смотреть |
|---|------|-------------|
| 1 | `TOOLS/docs-generator/main.go` | весь main — как вызывается, какие флаги |
| 2 | `TOOLS/docs-generator/internal/writers/writers.go` | ВСЕ функции. Особенно: `buildCreateParamsPage`, `buildModifyParamsPage`, `buildOutputsPage`, `buildExamplePage`, `buildManualPage`, `renderParamTable`, `renderNestedParams`, `htmlToMarkdown`, `formatParamOrBlock` |
| 3 | `TOOLS/docs-generator/internal/types/` | структуры YAML-спеки |

### LLM-обработка

| # | Файл | Что смотреть |
|---|------|-------------|
| 4 | `TOOLS/scripts/05_generate_docs_llm.py` | весь скрипт — как вызывается LLM, промпт, как парсится ответ |
| 5 | `docs/LLM_DOCS_GENERATION.md` | архитектура, правила для LLM |

### Результаты генерации (примеры)

| # | Файл | Что смотреть |
|---|------|-------------|
| 6 | `generated/test/docs/postgres_params_create.md` | RAW-вывод docs-generator (без LLM) |
| 7 | `generated/test/docs_llm/90_postgres.md` | ПОСЛЕ LLM-обработки |
| 8 | `generated/test/docs/postgres.md` | главная страница (MAN) |
| 9 | `generated/test/docs/postgres_example.md` | HCL пример |
| 10 | `generated/test/docs/postgres_outputs.md` | выходные параметры |
| 11 | `generated/test/docs/postgres_ops.md` | список операций |

---

## Текущий пайплайн (3 шага)

```
YAML-спеки
  → docs-generator (Go) → raw .md с HTML-таблицами
  → LLM (gpt-oss-120b, по одному файлу) → улучшенные .md
  → mkdocs-material → статический сайт → S3
```

---

## Что видит пользователь СЕЙЧАС (пример: postgres_params_create.md)

### До LLM (raw):
```html
<table><thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Description</th><th>Constraints</th></tr></thead>
<tr><td>788</td><td><strong><code>cluster_configuration</code></strong></td><td><code>map-fixed</code></td><td></td><td></td></tr>
```
- Колонка ID (техническая, пользователю не нужна)
- Английские заголовки (Code, Description, Constraints)
- Пустые ячейки Description
- Raw `value_list=` в Constraints

### После LLM:
```
| clusterConfiguration | map-fixed | да | — | — |
```
- Русские заголовки ✅
- ID убран ✅
- Но: пустые Description (—), value_list не раскрыт

---

## Проблемы (что нужно улучшить)

### 1. Пустые описания параметров
Многие параметры в выводе имеют `—` в колонке «Описание». Если сервис предоставил `descr` или `man` в YAML — он должен быть в документации.

### 2. Технические колонки
- Колонка «Constraints» показывает `value_list=1, 3, 5, 7` вместо читаемого «Допустимые значения: 1, 3, 5, 7»
- Колонка «Default» показывает пустую строку вместо «нет» или «—»
- ID параметров виден в raw-версии, но нужен ли он вообще?

### 3. MAN-секция (service_man)
Это HTML-строка с полным руководством от облачного провайдера. Она обрабатывается `htmlToMarkdown()` — regex-заменами. Часто результат нечитаемый: сломанные списки, потерянные ссылки, HTML-мусор.

### 4. HCL-примеры
`buildExamplePage` генерирует пример с ВСЕМИ параметрами (required + default). Это гигантский манифест на 100+ строк. Может, показывать сначала минимальный working example, а полный — отдельно?

### 5. Навигация
На каждой странице — строка навигации из 6 ссылок. Занимает место, дублируется. Может, сделать сайдбар или хлебные крошки?

### 6. LLM-промпт (05_generate_docs_llm.py)
Промпт просит «улучшить формулировки», но:
- Не просит раскрывать value_list в читаемый вид
- Не просит добавлять «почему» и «зачем» к параметрам
- Не использует `service_man` как дополнительный контекст для обогащения описаний
- Обрабатывает по одному файлу — теряет контекст между страницами

---

## Вопросы

### Q1: Структура страниц
Текущая: Manual | Create params | Modify params | Outputs | Ops | Example.
Удобно ли это? Что переставить/добавить/убрать? Может, всё на одной странице с якорями?

### Q2: HTML-таблицы vs Markdown-таблицы
Сейчас raw — HTML, LLM конвертирует в Markdown-таблицы. Оставить Markdown? Или HTML-таблицы лучше (CSS, выравнивание)?

### Q3: LLM-промпт
Как улучшить промпт чтобы:
- description параметров наполнялся из `service_man` где возможно
- value_list показывался читаемо
- empty cells говорили «не указано» а не «—»

### Q4: HCL-примеры
Минимальный пример + полный? Или только минимальный? Или только полный?

### Q5: Постраничная vs одностраничная документация
7 .md файлов на сервис. Это норм или перебор? Может, генерировать один README.md на сервис со всем внутри?

### Q6: Что ещё можно улучшить для UX?
Посмотри на любые 2-3 страницы из `generated/test/docs_llm/` и скажи: что непонятно, что раздражает, чего не хватает.

---

## Ожидаемый ответ

1. Анализ текущего состояния: что хорошо, что плохо (с конкретными примерами из файлов)
2. Конкретные предложения по каждому из 6 вопросов
3. Unified diff предлагаемых изменений в writers.go и 05_generate_docs_llm.py
4. Пример одной страницы «как должно быть» для postgres (хотя бы params_create)