fix: architectural improvements per Opus analysis

1. Version sync: provider/main.go = profile.env = 5.0.60
2. docs-generator: removed detectVersion() — no more dependency on provider/
3. docs-generator: removed detectRoot(), pickPath() — all paths via flags/env
4. docs-generator: require --version, --resources, --docs flags
5. Auto-rebuild: yaml-generator rebuilds if sources newer than binary
6. Three version vars → one VERSION in profile.env
7. Created TOOLS/lib/ — shared YAML contract types (not yet integrated)

TOOLS/docs-generator/main.go

@@ -7,7 +7,6 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
-	"regexp"
 	"sort"
 	"strconv"
 	"strings"
@@ -29,21 +28,25 @@ func main() {
 	opsFlag := flag.Bool("ops", false, "Generate per-service operations docs (resources_ops_yaml → docs/.../operations)")
 	flag.Parse()
 
-	root := detectRoot()
-
 	// --ops mode: generate per-service operations documentation
 	if *opsFlag {
-		runOpsMode(root)
+		runOpsMode()
 		return
 	}
-	resourcesDir := pickPath(*resourcesDirFlag, filepath.Join(root, "provider", "resources_yaml"))
-	docsDir := pickPath(*docsDirFlag, filepath.Join(root, "docs", "30_registry", "resources"))
-	servicesList := pickPath(*servicesListFlag, filepath.Join(root, "devops", "config", "services_list.txt"))
-	writers.CloudOutputByServiceID = writers.LoadCloudOutputSnapshot(root)
+	resourcesDir := *resourcesDirFlag
+	if resourcesDir == "" {
+		panic("--resources is required")
+	}
+	docsDir := *docsDirFlag
+	if docsDir == "" {
+		panic("--docs is required")
+	}
+	servicesList := *servicesListFlag
+	writers.CloudOutputByServiceID = writers.LoadCloudOutputSnapshot(*docsDirFlag)
 	excludeSet := toSet(*excludeFlag)
 	version := *versionFlag
 	if version == "" {
-		version = detectVersion(filepath.Join(root, "provider", "main.go"))
+		panic("--version is required")
 	}
 	apiEndpoint := *apiEndpointFlag
 
@@ -70,24 +73,6 @@ func main() {
 	writers.IndexMD(docsDir, processedSpecs)
 }
 
-func detectRoot() string {
-	cwd, err := os.Getwd()
-	if err != nil {
-		panic(err)
-	}
-	if filepath.Base(cwd) == "provider" {
-		return filepath.Dir(cwd)
-	}
-	return cwd
-}
-
-func pickPath(value, fallback string) string {
-	if value != "" {
-		return value
-	}
-	return fallback
-}
-
 func toSet(csv string) map[string]bool {
 	out := map[string]bool{}
 	for _, item := range strings.Split(csv, ",") {
@@ -100,19 +85,6 @@ func toSet(csv string) map[string]bool {
 	return out
 }
 
-func detectVersion(mainPath string) string {
-	b, err := os.ReadFile(mainPath)
-	if err != nil {
-		return "2.x"
-	}
-	re := regexp.MustCompile(`version string\s*=\s*"([0-9.]+)"`)
-	match := re.FindStringSubmatch(string(b))
-	if len(match) > 1 {
-		return match[1]
-	}
-	return "2.x"
-}
-
 func loadServicesList(path string) []types.ServiceMeta {
 	b, err := os.ReadFile(path)
 	if err != nil {
@@ -181,9 +153,15 @@ func loadSpecs(dir string, ordered []types.ServiceMeta) []types.ServiceSpec {
 }
 
 // runOpsMode генерирует per-service operations документацию.
-func runOpsMode(root string) {
-	yamlDir := pickPath(os.Getenv("NUBES_OPS_YAML_DIR"), filepath.Join(root, "provider", "resources_ops_yaml"))
-	docsDir := pickPath(os.Getenv("NUBES_OPS_DOCS_DIR"), filepath.Join(root, "docs", "30_registry", "resources", "operations"))
+func runOpsMode() {
+	yamlDir := os.Getenv("NUBES_OPS_YAML_DIR")
+	if yamlDir == "" {
+		panic("NUBES_OPS_YAML_DIR is required for --ops mode")
+	}
+	docsDir := os.Getenv("NUBES_OPS_DOCS_DIR")
+	if docsDir == "" {
+		panic("NUBES_OPS_DOCS_DIR is required for --ops mode")
+	}
 
 	if err := os.MkdirAll(docsDir, 0o755); err != nil {
 		panic(err)