From c77e0327d0d9d00d9a9f3e9cc26bd75ad91e9471 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Mon, 10 Aug 2026 13:52:28 +0400
Subject: [PATCH] feat(Phase 3): anchors for map-fixed, cloud keys in examples,
 russian headers, fix snapshot path

---
 .../internal/writers/writers.go               | 40 ++++++++++++++++---
 TOOLS/docs-generator/main.go                  |  2 +-
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/TOOLS/docs-generator/internal/writers/writers.go b/TOOLS/docs-generator/internal/writers/writers.go
index 02596fe..f99ac01 100644
--- a/TOOLS/docs-generator/internal/writers/writers.go
+++ b/TOOLS/docs-generator/internal/writers/writers.go
@@ -213,16 +213,16 @@ func htmlToMarkdown(s string) string {
 func buildExamplePage(spec types.ServiceSpec, nav string, version string, apiEndpoint string, providerSource string) string {
 	var b strings.Builder
 	b.WriteString(buildHeader(spec, nav, version))
-	b.WriteString(fmt.Sprintf("## Minimal example — only required parameters\n\n"))
+	b.WriteString("## Минимальный пример (только обязательные параметры)\n\n")
 	b.WriteString("```hcl\n")
 	b.WriteString(minimalExampleBlock(spec, version, apiEndpoint, providerSource))
 	b.WriteString("```\n\n")
-	b.WriteString("<details><summary>Full example (all parameters, including defaults)</summary>\n\n")
+	b.WriteString("<details><summary>Полный пример (все параметры, включая значения по умолчанию)</summary>\n\n")
 	b.WriteString("```hcl\n")
 	b.WriteString(exampleBlock(spec, version, apiEndpoint, providerSource))
 	b.WriteString("```\n\n")
 	b.WriteString("</details>\n\n")
-	b.WriteString("## Outputs usage\n\n")
+	b.WriteString("## Использование выходных данных\n\n")
 	b.WriteString("```hcl\n")
 	b.WriteString("# Выходные параметры можно использовать как\n")
 	b.WriteString(fmt.Sprintf("nubes_%s.baza.state_params[\"имя_ключа\"]\n", spec.Name))
@@ -234,6 +234,27 @@ func buildExamplePage(spec types.ServiceSpec, nav string, version string, apiEnd
 	b.WriteString(fmt.Sprintf("nubes_%s.baza.vault_user_path\n", spec.Name))
 	b.WriteString(fmt.Sprintf("nubes_%s.baza.vault_fields\n", spec.Name))
 	b.WriteString("```\n")
+
+	// Реальные ключи из облака
+	snapshot, ok := CloudOutputByServiceID[spec.ServiceID]
+	if ok && (len(snapshot.OutPaths) > 0 || len(snapshot.VaultFields) > 0) {
+		b.WriteString("\n### Реальные ключи из облака\n\n")
+		b.WriteString("```hcl\n")
+		for _, key := range snapshot.OutPaths {
+			if strings.TrimSpace(key) == "" {
+				continue
+			}
+			b.WriteString(fmt.Sprintf("# %s = nubes_%s.baza.state_out_flat[\"%s\"]\n", key, spec.Name, key))
+		}
+		for _, key := range snapshot.VaultFields {
+			if strings.TrimSpace(key) == "" {
+				continue
+			}
+			b.WriteString(fmt.Sprintf("# %s = nubes_%s.baza.vault_secrets[\"%s\"]\n", key, spec.Name, key))
+		}
+		b.WriteString("```\n")
+	}
+
 	return b.String()
 }
 
@@ -297,7 +318,7 @@ func minimalExampleBlock(spec types.ServiceSpec, version string, apiEndpoint str
 	b.WriteString(fmt.Sprintf("  api_endpoint = \"%s\"\n", apiEndpoint))
 	b.WriteString("}\n")
 	b.WriteString(fmt.Sprintf("resource \"nubes_%s\" \"baza\" {\n", spec.Name))
-	b.WriteString("  resource_name = \"my-resource\"\n\n")
+	b.WriteString("  resource_name = \"my-" + spec.Name + "\"\n\n")
 
 	for _, p := range minimalParams {
 		b.WriteString(formatParamOrBlock(p, "  ", true))
@@ -325,6 +346,15 @@ func buildCreateParamsPage(spec types.ServiceSpec, nav string, version string) s
 			}
 			def := defaultCell(p.Default)
 			desc := escapeText(pickTextTable(p))
+			// Якорь-ссылка для map-fixed/array-map-fixed с вложенными параметрами
+			if p.HasSubParams && len(p.SubParams) > 0 && desc == "" {
+				anchor := strings.ToLower(p.Code)
+				if p.IsJson {
+					desc = fmt.Sprintf("[Развернуть ↓](#%s-array-map-fixed)", anchor)
+				} else {
+					desc = fmt.Sprintf("[Развернуть ↓](#%s-map-fixed)", anchor)
+				}
+			}
 			constr := escapeText(collectConstraints(p))
 			b.WriteString(fmt.Sprintf("| %s | %s | %s | %s | %s | %s |\n", code, dtype, req, def, desc, constr))
 		}
@@ -539,7 +569,7 @@ func buildSubresourceExamplePage(spec types.ServiceSpec, srName string, nav stri
 	srResourceName := fmt.Sprintf("nubes_%s_%s", spec.Name, Slug(srName))
 	b.WriteString(fmt.Sprintf("# Resource %s — Example\n\n", srResourceName))
 	b.WriteString(fmt.Sprintf("Service: `nubes_%s` (ID: %d)\n\n", spec.Name, spec.ServiceID))
-	b.WriteString(fmt.Sprintf("## Copy-ready manifest (`%s_%s_main.tf`)\n\n", spec.Name, Slug(srName)))
+	b.WriteString(fmt.Sprintf("## Готовый манифест (`%s_%s_main.tf`)\n\n", spec.Name, Slug(srName)))
 	b.WriteString("```hcl\n")
 
 	b.WriteString("terraform {\n")
diff --git a/TOOLS/docs-generator/main.go b/TOOLS/docs-generator/main.go
index 0187152..fae146c 100644
--- a/TOOLS/docs-generator/main.go
+++ b/TOOLS/docs-generator/main.go
@@ -45,7 +45,7 @@ func main() {
 		panic("--docs is required")
 	}
 	servicesList := *servicesListFlag
-	writers.CloudOutputByServiceID = writers.LoadCloudOutputSnapshot(*docsDirFlag)
+	writers.CloudOutputByServiceID = writers.LoadCloudOutputSnapshot(".")
 	excludeSet := toSet(*excludeFlag)
 	version := *versionFlag
 	if version == "" {