docs: add detailed package-level comments to all TOOLS/ and provider/

TOOLS:
- yaml-generator: types (API↔YAML), client (proxy/REST + retry)
- resource-generator: types (3 resource kinds), loader (pipeline),
  writers (generated files), params (merge/CreateOnly/ForceNew)
- docs-generator, ops-generator — already documented

provider:
- main.go: entrypoint + build instructions
- core: API client (GetInstance, RunOperation, GetInstanceState)
- provider: provider registration (New, Resources, Schema)
- resources_core: shared CRUD, state refresh, params, validation

TOOLS/yaml-generator/internal/client/client.go

@@ -1,4 +1,13 @@
 // Package client — HTTP-клиент для API Nubes.
+//
+// Поддерживает два режима API, автоопределяемых по URL:
+//   - Legacy proxy: содержит "index.cfm" → ?endpoint=/services/123
+//   - REST Gateway: без "index.cfm" → /api/v1/svc/services/123
+//
+// Ретраи: до 3 попыток с экспоненциальной задержкой (2s, 4s, 8s).
+// Ретраятся: сетевые ошибки, 429 (rate limit), 5xx.
+//
+// Все методы возвращают типы из пакета types.
 package client
 
 import (

TOOLS/yaml-generator/internal/types/types.go

@@ -1,4 +1,13 @@
 // Package types — структуры данных для YAML-спеков сервисов.
+//
+// Содержит два набора типов:
+//   - API-ответы (ServiceResponse, ServiceInfo, CfsParam, ...) —
+//     соответствуют JSON-структурам Nubes API /services/{id} и /serviceOperation/{id}.
+//   - Выходные YAML-типы (ServiceSpec, ParamSpec, OperationSpec, ...) —
+//     сериализуются в resources_yaml/*.yaml и читаются генераторами resource-generator и docs-generator.
+//
+// Разделение API-входа и YAML-выхода позволяет менять формат YAML
+// независимо от структуры API.
 package types
 
 // ─── API-ответы ─────────────────────────────────────────────────────────────