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/resource-generator/internal/loader/loader.go

@@ -1,4 +1,13 @@
-// Package loader — загрузка YAML-спеков и построение ресурсов.
+// Package loader — загрузка YAML-спеков и построение GenResource/GenSubresource/GenAction.
+//
+// LoadSpecs — главная функция. Для каждого YAML:
+//  1. Парсит операции (create/modify/delete/suspend/resume/...)
+//  2. Классифицирует их на instance/subresource/action
+//  3. Сливает параметры, вычисляет CreateOnly и ForceNew
+//  4. Строит GenResource/GenSubresource/GenAction
+//  5. Сортирует результат по имени сервиса
+//
+// ValidateSpec — fail-fast валидация (паника при неизвестном Kind).
 package loader
 
 import (

TOOLS/resource-generator/internal/params/params.go

@@ -1,4 +1,11 @@
 // Package params — слияние, фильтрация, анализ параметров и ForceNew.
+//
+// Основные операции:
+//   - Merge — объединяет параметры из нескольких операций по Code
+//   - ComputeCreateOnly — поля, которые есть в create, но отсутствуют в modify
+//   - BuildSubresourceForceNewCodes — поля, требующие пересоздания subresource
+//   - Analyze — определяет используемые типы (bool/int64/string) для импортов
+//   - AnalyzePlanModifiers — ForceNew-поля, требующие planmodifier.*.RequiresReplace()
 package params
 
 import (

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

@@ -1,4 +1,14 @@
 // Package types — структуры данных для генератора Terraform-провайдера.
+//
+// Моделирует три вида ресурсов:
+//   - GenResource  — основной CRUD инстанса (nubes_{service})
+//   - GenSubresource — подресурсы (nubes_{service}_{user}, ...)
+//   - GenAction — действия (почти не используется, redeploy встроен в GenResource.HasRedeploy)
+//
+// Правила обработки action'ов из ARCHITECTURE.md:
+//   - redeploy → HasRedeploy=true, поле git_revision в основном ресурсе
+//   - restart/recovery/reconcile → исключены (ручные, только UI)
+//   - всё остальное → отдельный GenAction
 package types
 
 // ─── Входные структуры (из YAML) ───────────────────────────────────────────

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

@@ -1,4 +1,12 @@
 // Package writers — генерация Go-файлов ресурсов и registry.go.
+//
+// Генерирует три типа файлов в internal/resources_gen/:
+//   - {id}_{service}_resource.go  — основной CRUD инстанса
+//   - {id}_{service}_{sub}_resource.go — подресурсы
+//   - {id}_{service}_{action}_action.go — action-ресурсы (редко)
+//   - registry.go — AllResources() со списком всех ресурсов
+//
+// Каждый файл компилируется через text/template и форматируется через gofmt.
 package writers
 
 import (

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-ответы ─────────────────────────────────────────────────────────────

provider/internal/core/client.go

@@ -1,4 +1,11 @@
-// ВНИМАНИЕ: НЕ ИЗМЕНЯТЬ НИЧЕГО В ЯДРЕ БЕЗ ПРЯМОГО РАЗРЕШЕНИЯ ОПЕРАТОРА.
+// Package core — ядро провайдера: HTTP-клиент Nubes API.
+//
+// Содержит:
+//   - Client — HTTP-клиент с retry, таймаутами, Bearer-токеном
+//   - Методы GetInstance*, RunOperation*, GetInstanceState*
+//   - Логику определения proxy vs REST API (isProxyAPI)
+//
+// ⛔ НЕ ИЗМЕНЯТЬ НИЧЕГО В ЯДРЕ БЕЗ ПРЯМОГО РАЗРЕШЕНИЯ ОПЕРАТОРА.
 package core
 
 import (

provider/internal/provider/provider.go

@@ -1,3 +1,9 @@
+// Package provider — регистрация Terraform-провайдера Nubes.
+//
+// Определяет:
+//   - New() — создание провайдера с конфигурацией (api_token, api_endpoint)
+//   - Resources() — список всех ресурсов из resources_gen.AllResources()
+//   - Schema() — схема конфигурации провайдера
 package provider
 
 import (

provider/internal/resources_core/crud.go

@@ -1,4 +1,13 @@
-// ВНИМАНИЕ: НЕ ИЗМЕНЯТЬ НИЧЕГО В CRUD БЕЗ ПРЯМОГО РАЗРЕШЕНИЯ ОПЕРАТОРА.
+// Package resources_core — общая логика CRUD для сгенерированных ресурсов.
+//
+// Предоставляет функции, используемые всеми ресурсами из resources_gen:
+//   - Create/Read/Update/Delete — базовые CRUD-операции
+//   - State Refresh — обновление состояния из API
+//   - Param Mapping — маппинг параметров Terraform ↔ API
+//   - Validation — валидация обязательных полей и ref_svc
+//   - Plan Modifiers — UUID, JSON-нормализация
+//
+// ⛔ НЕ ИЗМЕНЯТЬ НИЧЕГО В CRUD БЕЗ ПРЯМОГО РАЗРЕШЕНИЯ ОПЕРАТОРА.
 package resources_core
 
 import (

provider/main.go

@@ -1,3 +1,10 @@
+// Terraform-провайдер Nubes Cloud.
+//
+// Регистрирует провайдер в hashicorp/terraform-plugin-framework.
+// Все ресурсы подключаются через resources_gen.AllResources().
+//
+// Сборка: go build -o terraform-provider-nubes .
+// Версия задаётся через ldflags: -ldflags "-X main.version=X.Y.Z"
 package main
 
 import (