feat: enhance configuration and documentation for Fabrica project

- Updated FabricaConfig structure to include detailed comments on configuration options.
- Deprecated versioning configuration in FabricaConfig; moved to apis.yaml.
- Added readAPIsConfig function to load apis.yaml for versioning.
- Modified generate command to support resource discovery from apis.yaml.
- Improved init command to create apis.yaml alongside .fabrica.yaml during project initialization.
- Added comprehensive documentation for apis.yaml structure and usage.
- Updated versioning command to work with the new apis.yaml format.
- Adjusted generator defaults to disable versioning by default.

Signed-off-by: Alex Lovell-Troy <alovelltroy@lanl.gov>

Author: alexlovelltroy

.github/workflows/regression-tests.yml

@@ -26,7 +26,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Set up Go
       uses: actions/setup-go@v6
@@ -38,8 +38,6 @@ jobs:
       run: make build
 
     - name: Run Go integration tests
-      env:
-        GOPRIVATE: "github.com/me/*,example.com/*"
       run: |
         cd test/integration
         go mod tidy

README.md

@@ -19,6 +19,15 @@ SPDX-License-Identifier: MIT
 > **🏗️ Code Generator for Go REST APIs**
 > Transform Go structs into production-ready REST APIs with OpenAPI specs, storage backends, and middleware in minutes.
 
+## 📚 Documentation & Resources
+
+| Resource | Description |
+|----------|-------------|
+| **[Full Documentation](https://openchami.github.io/fabrica/)** | Complete guides, tutorials, and best practices |
+| **[API Reference (GoDoc)](https://pkg.go.dev/github.com/openchami/fabrica)** | Comprehensive Go package documentation |
+| **[Getting Started Guide](docs/guides/getting-started.md)** | Step-by-step introduction to Fabrica |
+| **[Examples](examples/)** | Hands-on learning with real-world projects |
+
 Fabrica is a powerful code generation tool that accelerates API development by transforming simple Go struct definitions into complete, production-ready REST APIs. Define your resources once, and Fabrica generates everything you need: handlers, storage layers, clients, validation, OpenAPI documentation, and more.
 
 ## ✨ Key Features
@@ -117,7 +126,7 @@ type DeviceStatus struct {
 fabrica generate
 ```
 
-This generates handlers, storage, and client code. By default, APIs expose `<group>/v1`. To add multiple versions (`v1alpha1`, `v1beta1`, etc.), create an `apis.yaml` file (see [Hub/Spoke Versioning Guide](docs/versioning.md)).
+This generates handlers, storage, and client code. By default, APIs expose `<group>/v1`. Your project includes a root-level `apis.yaml` file defining API groups and versions (see [Hub/Spoke Versioning Guide](docs/versioning.md)). To add more versions, run `fabrica add version <new-version>`.
 
 **5. Update dependencies:**
 
@@ -304,25 +313,32 @@ type DeviceStatus struct {
 > **💡 Pro Tip:** Focus on designing your `spec` and `status` structs - Fabrica handles all the envelope complexity automatically!
 
 
-## 📖 Documentation
+## 📖 In-Depth Documentation
 
-**🚀 Getting Started:**
+**🚀 Quick Learning:**
 - [Complete Getting Started Guide](docs/guides/getting-started.md) - Step-by-step tutorial
-- [Quick Start Examples](examples/) - Hands-on learning
+- [Quickstart Examples](examples/) - Hands-on learning with working code
+- [Full Documentation Website](https://openchami.github.io/fabrica/) - All guides and tutorials
 
 **🏗️ Architecture & Design:**
 - [Architecture Overview](docs/reference/architecture.md) - Understanding Fabrica's design principles
 - [Resource Model Guide](docs/guides/resource-model.md) - How to design and define resources
+- [API Versioning Guide](docs/guides/versioning.md) - Hub/Spoke versioning patterns
+- [API Configuration Reference](docs/apis-yaml.md) - apis.yaml structure and workflows
 
 **💾 Storage & Data:**
 - [Storage Systems](docs/guides/storage.md) - File vs database backends comparison
 - [Ent Storage Integration](docs/guides/storage-ent.md) - Database setup and configuration
 
 **⚙️ Advanced Topics:**
-- [Code Generation](docs/reference/codegen.md) - How templates work and customization
+- [Code Generation Reference](docs/reference/codegen.md) - How templates work and customization
 - [Validation System](docs/guides/validation.md) - Request validation and error handling
-- [Event System](docs/guides/events.md) - CloudEvents integration
+- [Event System](docs/guides/events.md) - CloudEvents integration and event-driven patterns
 - [Reconciliation](docs/guides/reconciliation.md) - Controller pattern for resource management
+- [Conditional Requests & PATCH](docs/guides/conditional-and-patch.md) - ETag-based preconditions
+
+**📖 API Documentation:**
+- [GoDoc Package Reference](https://pkg.go.dev/github.com/openchami/fabrica) - Complete Go API documentation
 
 ## 🤝 Contributing
 

USAGE.md

@@ -224,25 +224,25 @@ open http://localhost:8080/swagger/
 ## Common Workflows
 
 ### 1. Add API Versioning (Hub/Spoke Pattern)
+
+The root-level `apis.yaml` is created by `fabrica init` and drives version management.
+
 ```bash
-# Create apis.yaml in project root
-cat > apis.yaml << 'EOF'
-groups:
-  - name: api.example
-    versions:
-      - v1       # Storage/hub version (v1)
-      - v1beta1  # Conversion to v1beta1
-      - v1alpha1 # Conversion to v1alpha1
-EOF
+# Add a new version (copies types from latest version)
+fabrica add version v1beta1
 
-# Regenerate
+# Or copy from a specific version
+fabrica add version v1beta1 --from v1alpha1
+
+# apis.yaml is updated automatically; regenerate to create handlers
 fabrica generate
 ```
 
 Now your API supports:
-- `api.example/v1` - Current stable (storage version)
-- `api.example/v1beta1` - Experimental
-- `api.example/v1alpha1` - Alpha
+- `infra.example.io/v1` - Storage (hub) version
+- `infra.example.io/v1beta1` - New spoke version
+
+For details, see [docs/apis-yaml.md](docs/apis-yaml.md) and [docs/versioning.md](docs/versioning.md).
 
 ### 2. Switch from File to Database Storage
 ```bash

cmd/fabrica/add.go

@@ -109,55 +109,46 @@ func runAddResource(resourceName string, opts *addOptions) error {
 		return fmt.Errorf("failed to load config: %w", err)
 	}
 
-	// Determine target version and directory
-	var targetDir string
-	var isVersioned bool
-
-	if config.Features.Versioning.Enabled && len(config.Features.Versioning.Versions) > 0 {
-		isVersioned = true
-
-		// Require group to be set for versioned projects
-		if config.Features.Versioning.Group == "" {
-			return fmt.Errorf("versioning is enabled but features.versioning.group is not set in .fabrica.yaml.\nPlease set the API group (e.g., 'infra.example.io') in your configuration")
+	apisConfig, err := LoadAPIsConfig("")
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("apis.yaml not found; run 'fabrica init' to create it")
 		}
+		return fmt.Errorf("failed to load apis.yaml: %w", err)
+	}
 
-		// Version is required for versioned projects
-		if opts.version == "" {
-			// Auto-select storage version (hub) if no version specified
-			if config.Features.Versioning.StorageVersion != "" {
-				opts.version = config.Features.Versioning.StorageVersion
-				fmt.Printf("No version specified, using storage hub version: %s\n", opts.version)
-			} else {
-				return fmt.Errorf("no --version specified and no storage_version configured.\nPlease specify a version with --version or set features.versioning.storage_version in .fabrica.yaml")
-			}
-		} else {
-			// Validate version exists in config
-			found := false
-			for _, v := range config.Features.Versioning.Versions {
-				if v == opts.version {
-					found = true
-					break
-				}
-			}
-			if !found {
-				return fmt.Errorf("version %s not found in .fabrica.yaml (available: %v)", opts.version, config.Features.Versioning.Versions)
-			}
+	group, err := apisConfig.primaryGroup()
+	if err != nil {
+		return err
+	}
 
-			// Check if adding to non-alpha without --force
-			if !strings.Contains(opts.version, "alpha") && !opts.force {
-				return fmt.Errorf("adding resource to non-alpha version %s requires --force flag", opts.version)
+	// Determine target version and directory
+	isVersioned := true
+	if opts.version == "" {
+		opts.version = group.StorageVersion
+		fmt.Printf("No version specified, using storage hub version: %s\n", opts.version)
+	} else {
+		found := false
+		for _, v := range group.Versions {
+			if v == opts.version {
+				found = true
+				break
 			}
 		}
+		if !found {
+			return fmt.Errorf("version %s not found in apis.yaml (available: %v)", opts.version, group.Versions)
+		}
 
-		targetDir = filepath.Join("apis", config.Features.Versioning.Group, opts.version)
-	} else {
-		// Legacy mode is deprecated
-		return fmt.Errorf("legacy mode (pkg/resources/) is deprecated.\nPlease enable versioning in .fabrica.yaml:\n\nfeatures:\n  versioning:\n    enabled: true\n    group: your.api.group\n    storage_version: v1\n    versions:\n      - v1")
+		if !strings.Contains(opts.version, "alpha") && !opts.force {
+			return fmt.Errorf("adding resource to non-alpha version %s requires --force flag", opts.version)
+		}
 	}
 
+	targetDir := filepath.Join("apis", group.Name, opts.version)
+
 	fmt.Printf("📦 Adding resource %s", resourceName)
 	if isVersioned {
-		fmt.Printf(" to %s/%s...\n", config.Features.Versioning.Group, opts.version)
+		fmt.Printf(" to %s/%s...\n", group.Name, opts.version)
 	} else {
 		fmt.Println("...")
 	}
@@ -175,27 +166,17 @@ func runAddResource(resourceName string, opts *addOptions) error {
 		resourceFile = filepath.Join(targetDir, opts.packageName+".go")
 	}
 
-	if err := generateResourceFile(resourceFile, resourceName, isVersioned, opts, config); err != nil {
+	if err := generateResourceFile(resourceFile, resourceName, isVersioned, opts, config.Project.Module, group.StorageVersion, group.Name); err != nil {
 		return err
 	}
 
-	// Update config to add resource to versioning.resources list
+	// Update apis.yaml to include the resource
 	if isVersioned {
-		// Check if resource already in list
-		found := false
-		for _, r := range config.Features.Versioning.Resources {
-			if r == resourceName {
-				found = true
-				break
-			}
-		}
-		if !found {
-			config.Features.Versioning.Resources = append(config.Features.Versioning.Resources, resourceName)
-			if err := SaveConfig("", config); err != nil {
-				return fmt.Errorf("failed to update config: %w", err)
-			}
-			fmt.Printf("  ✓ Added %s to .fabrica.yaml\n", resourceName)
+		apisConfig.addResource(resourceName)
+		if err := SaveAPIsConfig("", apisConfig); err != nil {
+			return fmt.Errorf("failed to update apis.yaml: %w", err)
 		}
+		fmt.Printf("  ✓ Added %s to apis.yaml\n", resourceName)
 	}
 
 	fmt.Println()
@@ -215,7 +196,7 @@ func runAddResource(resourceName string, opts *addOptions) error {
 	return nil
 }
 
-func generateResourceFile(filePath, resourceName string, isVersioned bool, opts *addOptions, config *FabricaConfig) error {
+func generateResourceFile(filePath, resourceName string, isVersioned bool, opts *addOptions, modulePath, hubVersion, groupName string) error {
 	var packageName string
 	if isVersioned {
 		// Use version as package name (e.g., v1alpha1)
@@ -225,10 +206,7 @@ func generateResourceFile(filePath, resourceName string, isVersioned bool, opts
 	}
 
 	// Determine if this is the hub version (storage version)
-	isHub := false
-	if isVersioned && config != nil {
-		isHub = (opts.version == config.Features.Versioning.StorageVersion)
-	}
+	isHub := isVersioned && hubVersion != "" && opts.version == hubVersion
 
 	content := fmt.Sprintf(`// Copyright © 2025 OpenCHAMI a Series of LF Projects, LLC
 //
@@ -245,14 +223,11 @@ import (
 	"github.com/openchami/fabrica/pkg/fabrica"`
 
 		// Add hub package import for spoke versions (for conversions)
-		if !isHub && config != nil {
-			modulePath := config.Project.Module
-			hubVersion := config.Features.Versioning.StorageVersion
-			group := config.Features.Versioning.Group
+		if !isHub && hubVersion != "" && groupName != "" && modulePath != "" {
 			hubPackage := strings.ReplaceAll(hubVersion, ".", "")
 
 			content += `
-	` + hubPackage + ` "` + modulePath + `/apis/` + group + `/` + hubVersion + `"`
+	` + hubPackage + ` "` + modulePath + `/apis/` + groupName + `/` + hubVersion + `"`
 		}
 
 		content += `
@@ -376,9 +351,7 @@ func (r *` + resourceName + `) IsHub() {}
 		}
 
 		// Add conversion stubs for non-hub versions (spokes)
-		if !isHub && config != nil {
-			hubVersion := config.Features.Versioning.StorageVersion
-			group := config.Features.Versioning.Group
+		if !isHub && hubVersion != "" && groupName != "" {
 			hubPackage := strings.ReplaceAll(hubVersion, ".", "")
 
 			content += `
@@ -389,7 +362,7 @@ func (src *` + resourceName + `) ConvertTo(dstRaw interface{}) error {
 	// TODO: Implement conversion logic from ` + packageName + ` to ` + hubVersion + `
 
 	// Copy common fields
-	dst.APIVersion = "` + group + `/` + hubVersion + `"
+	dst.APIVersion = "` + groupName + `/` + hubVersion + `"
 	dst.Kind = src.Kind
 	dst.Metadata = src.Metadata