feat(Phase 2): unified params table (Required col), MAN in details, danger admonition for lifecycle

TOOLS/docs-generator/internal/writers/writers.go

@@ -151,14 +151,23 @@ func buildHeader(spec types.ServiceSpec, nav string, version string) string {
 func buildManualPage(spec types.ServiceSpec, nav string, version string) string {
 	var b strings.Builder
 	b.WriteString(buildHeader(spec, nav, version))
-	b.WriteString("## MAN\n\n")
+
-	man := strings.TrimSpace(spec.ServiceMan)
+	// Краткое описание
-	if man == "" {
+	name := spec.ServiceDisplayName
-		man = "Manual not available."
+	if name == "" {
+		name = spec.Name
 	}
+	b.WriteString(fmt.Sprintf("Сервис **%s** (`nubes_%s`). См. [Create params](%s_params_create.md) для списка параметров.\n\n", name, spec.Name, spec.Name))
+
+	// MAN в раскрывающемся блоке — DevOps читает если застрял
+	man := strings.TrimSpace(spec.ServiceMan)
+	if man != "" {
+		b.WriteString("<details>\n<summary>Справка (MAN)</summary>\n\n")
 		b.WriteString("<div class=\"man-content\" markdown=\"1\">\n\n")
 		b.WriteString(htmlToMarkdown(man))
 		b.WriteString("\n\n</div>\n")
+		b.WriteString("</details>\n")
+	}
 	return b.String()
 }
 
@@ -303,37 +312,45 @@ func buildCreateParamsPage(spec types.ServiceSpec, nav string, version string) s
 	b.WriteString(buildHeader(spec, nav, version))
 	b.WriteString("## Create params\n\n")
 	createParams := FindParams(spec.Operations, "create")
-	requiredParams, defaultParams := SplitParams(createParams)
 
-	if len(requiredParams) > 0 {
+	if len(createParams) > 0 {
-		b.WriteString("**Обязательные параметры (вводимые пользователем)**\n\n")
+		b.WriteString("| Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения |\n")
-		b.WriteString(renderParamTable(requiredParams, true, true))
+		b.WriteString("|----------|-----|-------------|-------------|----------|-------------|\n")
-		for _, p := range requiredParams {
+		for _, p := range createParams {
-			b.WriteString(renderNestedParams(p))
+			code := formatParamCode(p.Code)
+			dtype := formatTypeCell(p)
+			req := "—"
+			if p.Required {
+				req = "**да**"
 			}
+			def := defaultCell(p.Default)
+			desc := escapeText(pickTextTable(p))
+			constr := escapeText(collectConstraints(p))
+			b.WriteString(fmt.Sprintf("| %s | %s | %s | %s | %s | %s |\n", code, dtype, req, def, desc, constr))
 		}
+		b.WriteString("\n")
 
-	if len(defaultParams) > 0 {
+		// Вложенные параметры (map-fixed)
-		b.WriteString("\n**Параметры, имеющие значение по умолчанию, если не меняете - эти параметры не обязательно прописывать в манифесте**\n")
+		for _, p := range createParams {
-		b.WriteString(renderParamTable(defaultParams, false, false))
-		for _, p := range defaultParams {
 			b.WriteString(renderNestedParams(p))
 		}
 	}
 
 	lifecycle := spec.Lifecycle
 	if lifecycle.SuspendOnDestroyDefault || lifecycle.AdoptExistingOnCreateDefault {
-		b.WriteString("\n<div class=\"lifecycle-note\">\n")
+		b.WriteString("\n!!! danger \"Важно: поведение при destroy\"\n")
-		b.WriteString("<strong>Параметры поведения (кратко)</strong><br/>\n")
+		b.WriteString(fmt.Sprintf("    По умолчанию: `suspend_on_destroy = %s`, `adopt_existing_on_create = %s`.\n", formatBoolTitle(lifecycle.SuspendOnDestroyDefault), formatBoolTitle(lifecycle.AdoptExistingOnCreateDefault)))
-		b.WriteString(fmt.Sprintf("По умолчанию: `suspend_on_destroy = %s`, `adopt_existing_on_create = %s`.<br/>\n", formatBoolTitle(lifecycle.SuspendOnDestroyDefault), formatBoolTitle(lifecycle.AdoptExistingOnCreateDefault)))
+		b.WriteString("    \n")
-		b.WriteString("При `terraform destroy` или удалении ресурса из манифеста:<br/>\n")
+		b.WriteString("    При `terraform destroy` или удалении ресурса из манифеста:\n")
-		b.WriteString("- `suspend_on_destroy=true` — инстанс переводится в `Suspend` (не удаляется).<br/>\n")
+		b.WriteString("    - `suspend_on_destroy=true` — инстанс переводится в `Suspend` (не удаляется).\n")
-		b.WriteString("- `suspend_on_destroy=false` — Terraform удаляет ресурс только из state.<br/>\n")
+		b.WriteString("    - `suspend_on_destroy=false` — Terraform удаляет ресурс только из state.\n")
-		b.WriteString("При `apply` флаг `adopt_existing_on_create` работает как авто-`import`:<br/>\n")
+		b.WriteString("    \n")
-		b.WriteString("- `false` — если ресурс уже есть, будет ошибка.<br/>\n")
+		b.WriteString("    При `apply` флаг `adopt_existing_on_create` работает как авто-`import`:\n")
-		b.WriteString("- `true` — Terraform может взять существующий инстанс под управление (`running` → adopt, `suspended` → resume+adopt при совпадении параметров).<br/>\n")
+		b.WriteString("    - `false` — если ресурс уже есть, будет ошибка.\n")
+		b.WriteString("    - `true` — Terraform может взять существующий инстанс под управление.\n")
+		b.WriteString("    \n")
 		b.WriteString("    Важно: один инстанс должен быть только в одном state. Иначе получите конфликт управления.\n")
-		b.WriteString("</div>\n")
+		b.WriteString("\n")
 	}
 
 	return b.String()

TOOLS/scripts/05_generate_docs_llm.py

@@ -25,14 +25,24 @@ SYSTEM_PROMPT = """Ты — технический писатель Nubes Terraf
 - НЕ трогай HCL-блоки (всё внутри ```hcl ... ```)
 - НЕ трогай имена параметров в таблицах (snake_case / camelCase из API)
 - НЕ трогай навигационные строки вида [Manual](x.md) · [Create params](y.md) ...
+- НЕ трогай блоки `!!! danger` — это автоматические предупреждения
 - НЕ добавляй и не удаляй строки/колонки в таблицах
 - Верни ТОЛЬКО готовый текст файла. Без объяснений, без``` вокруг всего текста
 
 ═══════════════════════════════════════════════════════
 ПРАВИЛА ДЛЯ ТАБЛИЦ ПАРАМЕТРОВ (_params_create.md, _params_modify.md)
 ═══════════════════════════════════════════════════════
-Таблицы содержат столбцы: ID | Code | Type | Required | Default | Description | Constraints
+Таблицы create-параметров содержат столбцы:
-Можно менять ТОЛЬКО текст в <td>Description</td> и <td>Constraints</td>.
+  Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения
+
+Таблицы modify-параметров содержат столбцы:
+  Code | Type | Description | Constraints
+
+Таблицы вложенных параметров (### map-fixed) содержат столбцы:
+  Code | Type | Required | Default | Description | Constraints
+
+Можно менять ТОЛЬКО текст в колонках Описание/Description и Ограничения/Constraints.
+НЕ трогай колонки: Параметр/Code, Тип/Type, Обязательный/Required, По умолчанию/Default.
 
 ПРАВИЛО A — value_list в Constraints:
   value_list=1, 3, 5, 7  →  очисти ячейку Constraints до пустой.
@@ -76,9 +86,10 @@ SYSTEM_PROMPT = """Ты — технический писатель Nubes Terraf
   recovery   → «Восстановление из резервной копии»
 
 ═══════════════════════════════════════════════════════
-ПРАВИЛА ДЛЯ ГЛАВНОЙ СТРАНИЦЫ (Name.md — секция ## MAN)
+ПРАВИЛА ДЛЯ ГЛАВНОЙ СТРАНИЦЫ (Name.md — блок <details>)
 ═══════════════════════════════════════════════════════
-Блок ## MAN содержит HTML внутри <div class="man-content">.
+MAN находится внутри `<details><summary>Справка (MAN)</summary>` — НЕ трогай теги details/summary.
+Внутри — HTML в `<div class="man-content" markdown="1">`.
 Преобразуй HTML → читаемый Markdown:
   <h2>/<h3> → ## / ###
   <ul><li>  → - элемент списка