Remove guidance section from CLAUDE.md and add independent versioning design document

.gitignore

@@ -21,6 +21,7 @@ uv.lock
 
 # Wild Cloud
 .envrc
+wild-cloud-redmond-data
 
 # Development working dir
 .working/

.gitmodules

@@ -1,18 +1,6 @@
 [submodule "wild-directory"]
 	path = wild-directory
 	url = https://git.civilsociety.dev/wild-cloud/wild-directory.git
-[submodule "wild-cli"]
-	path = wild-cli
-	url = https://git.civilsociety.dev/wild-cloud/wild-cli.git
-[submodule "wild-cloud-poc"]
-	path = wild-cloud-poc
-	url = https://git.civilsociety.dev/wild-cloud/wild-cloud-poc.git
-[submodule "wild-central-api"]
-	path = wild-central-api
-	url = https://git.civilsociety.dev/wild-cloud/wild-central-api.git
-[submodule "wild-web-app"]
-	path = wild-web-app
-	url = https://git.civilsociety.dev/wild-cloud/wild-web-app.git
-[submodule "wild-central"]
-	path = wild-central
-	url = https://git.civilsociety.dev/wild-cloud/wild-central.git
+[submodule "wild-cloud"]
+	path = wild-cloud
+	url = https://git.civilsociety.dev/wild-cloud/wild-cloud.git

CLAUDE.md

@@ -1,22 +1,25 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
 ## Project Overview
 
 This project is called "Wild Cloud". Wild Cloud is a platform for managing and orchestrating cloud-native applications on local networks using a network appliance called "Wild Central".
 
-Wild Central is a lightweight server that runs on a local machine (e.g., a Raspberry Pi) and provides an API for users to manage their Wild Cloud instances. The Wild Cloud API is implemented in the wild-central-api project. @wild-central-api/README.md . Wild Central devices can be set up using our apt package implemented in the wild-central project. @wild-central/README.md
+Wild Central is a lightweight server that runs on a local machine (e.g., a Raspberry Pi) and provides an API for users to manage their Wild Cloud instances. The core Wild Cloud components are in the `wild-cloud` mono-repo:
+
+- **API** (`wild-cloud/api`): The Wild Cloud API that runs on Wild Central. @wild-cloud/api/CLAUDE.md
+- **CLI** (`wild-cloud/cli`): Command-line interface for managing Wild Cloud instances. @wild-cloud/cli/README.md
+- **Web App** (`wild-cloud/web`): Web-based interface for managing Wild Cloud instances. @wild-cloud/web/CLAUDE.md
+- **Dist** (`wild-cloud/dist`): Distribution package for setting up Wild Central devices via apt. @wild-cloud/dist/README.md
+
+All data and config for an instance of Wild Central is defined in Central's environment in the WILD_API_DATA_DIR variable. For ease of access, a symlink to our Wild API data dir is made at ./wild-cloud-redmond-data.
 
 A Wild Cloud instance is a kubernetes (k8s) environment that runs Wild Cloud services and applications. Wild Cloud instances can be created, managed, and monitored using the Wild Cloud API running on a Wild Central device.
 
-Wild Cloud applications are custom packages designed to be deployed to Wild Cloud instances. They consist of kustomize templates and a Wild Cloud app manifest file that describes the application and how it should be deployed configured and deployed in a Wild Cloud instance. Wild Cloud applications are stored in a "Wild Directory". The directory contained in the wild-directory folder is the official Wild Directory. @wild-directory/README.md
+Wild Cloud applications are custom packages designed to be deployed to Wild Cloud instances. They consist of kustomize templates and a Wild Cloud app manifest file that describes the application and how it should be deployed configured and deployed in a Wild Cloud instance. Wild Cloud applications are stored in a "Wild Directory". The directory contained in the wild-directory folder is the official Wild Directory. @wild-directory/CLAUDE.md
 
-The Wild Cloud API maintains data for each Wild Cloud instance in its configured WILD_API_DATA_DIR. A data directory is intended to be checked into version control (e.g., git) to track changes to the configuration of Wild Cloud instances and their deployed applications over time. These are designed to follow infrastructure-as-code principles, allowing experienced devops users to manage their Wild Cloud instances using familiar tools and workflows. 
+The Wild Cloud API maintains data for each Wild Cloud instance in its configured WILD_API_DATA_DIR. A data directory is intended to be checked into version control (e.g., git) to track changes to the configuration of Wild Cloud instances and their deployed applications over time. These are designed to follow infrastructure-as-code principles, allowing experienced devops users to manage their Wild Cloud instances using familiar tools and workflows.
 
-We provide a command-line interface (CLI) tool called Wild CLI, implemented in the wild-cli project, that allows users to interact with the Wild Cloud API and manage their Wild Cloud instances from the terminal. This allows users to automate tasks and integrate Wild Cloud management into their existing workflows. @wild-cli/README.md
-
-To make Wild Cloud more accessible to less-experienced users, the Wild Central device hosts a web-based interface for managing Wild Cloud instances, which is implemented in the wild-web-app project. @wild-web-app/README.md
+We have a public website for Wild Cloud (https://mywildcloud.org) with source in `wild-cloud/docs`.
 
 ## Additional Documentation
 

README.md

@@ -2,17 +2,21 @@
 
 ## Overview
 
-This project includes a Claude Code assisted environment for working on all Wild Cloud components at once. Each component of the Wild Cloud project is included as submodules in this repo. This includes:
+This project includes a Claude Code assisted environment for working on all Wild Cloud components at once. The Wild Cloud project is organized as follows:
 
-- [Wild Central](wild-central/README.md): The network appliance.
-- [Wild Centrail API](wild-central-api/README.md): The daemon running on the network appliance.
-- [Wild CLI](wild-cli/README.md): A command line interface to the API.
-- [Wild Web App](wild-web-app/README.md): A web interface to the API.
-- [Wild Directory](wild-directory/README.md): Managed apps to be deployed on wild clouds.
+### Wild Cloud Mono-repo
 
-... and, until this milestone is complete:
+The core components are in the [wild-cloud](wild-cloud/README.md) mono-repo:
 
-- [Wild CLoud PoC](wild-cloud-poc/README.md): The proof-of-concept project that includes functional scripts for running a wild cloud within a development environment. This will be retired as soon as the CLI and web-app are at feature-parity.
+- [API](wild-cloud/api/README.md): The Wild Cloud API that runs on Wild Central.
+- [CLI](wild-cloud/cli/README.md): Command-line interface for managing Wild Cloud instances.
+- [Web App](wild-cloud/web/README.md): Web-based interface for managing Wild Cloud instances.
+- [Dist](wild-cloud/dist/README.md): Distribution package for setting up Wild Central devices via apt.
+- [Docs](wild-cloud/docs/): Public website source (https://mywildcloud.org).
+
+### Other Submodules
+
+- [Wild Directory](wild-directory/README.md): Managed apps to be deployed on Wild Cloud instances.
 
 ## Dev environment setup
 

TODO.md

@@ -1,20 +0,0 @@
-# Development TO DO
-
-## Wild Central
-
-- dnsmasq setup and config for DNS resolution
-- (future) PXE boot setup and config
-- (future) DHCP setup and config
-
-## Wild Daemon (Central Service, wildd)
-
-- Add methods for config get and set and use them consistently instead of yq.
-- Put all directory/setup files inside the daemon itself. These can be versioned with the daemon.
-
-## Wild CLI
-
-- Use common.sh in install.sh scripts.
-
-## Wild App
-
-- Need to build the whole thing.

ai/wildcloud-v.PoC/apps-system.md

@@ -43,7 +43,7 @@ defaultConfig:
   storage: 10Gi
   dbHostname: postgres.postgres.svc.cluster.local
   dbUsername: myapp
-requiredSecrets:
+defaultSecrets:
   - apps.myapp.dbPassword
   - apps.postgres.password
 ```
@@ -55,7 +55,7 @@ requiredSecrets:
 - `icon` - A URL to an icon representing the app
 - `requires` - A list of other apps that this app depends on (each entry should be the name of another app)
 - `defaultConfig` - A set of default configuration values for the app (when an app is added using `wild-app-add`, these values will be added to the Wild Cloud `config.yaml` file)
-- `requiredSecrets` - A list of secrets that must be set in the Wild Cloud `secrets.yaml` file for the app to function properly (these secrets are typically sensitive information like database passwords or API keys; keys with random values will be generated automatically when the app is added)
+- `defaultSecrets` - A list of secrets that must be set in the Wild Cloud `secrets.yaml` file for the app to function properly (these secrets are typically sensitive information like database passwords or API keys; keys with random values will be generated automatically when the app is added)
 
 ### Kustomization Configuration
 
@@ -354,7 +354,7 @@ spec:
 
 ```yaml
 # In manifest.yaml
-requiredSecrets:
+defaultSecrets:
   - apps.myapp.dbUrl
 
 # Generated secret (by wild-app-add)
@@ -509,7 +509,7 @@ Wild Cloud includes apps for common self-hosted services:
 
 **Manifest Design**:
 - Include comprehensive `defaultConfig` for all configurable values
-- List all `requiredSecrets` the app needs
+- List all `defaultSecrets` the app needs
 - Specify dependencies in `requires` field
 - Use semantic versioning
 

ai/wildcloud-v.PoC/configuration-system.md

@@ -247,7 +247,7 @@ wild-secret-set apps.database '{"user":"admin","password":"secret"}'
 
 When you run `wild-app-add`, Wild Cloud automatically generates required secrets:
 
-1. **Reads App Manifest**: Identifies `requiredSecrets` list
+1. **Reads App Manifest**: Identifies `defaultSecrets` list
 2. **Checks Existing Secrets**: Never overwrites existing values
 3. **Generates Missing Secrets**: Creates secure random values
 4. **Updates secrets.yaml**: Adds new secrets with proper structure
@@ -255,7 +255,7 @@ When you run `wild-app-add`, Wild Cloud automatically generates required secrets
 **Example App Manifest**:
 ```yaml
 name: ghost
-requiredSecrets:
+defaultSecrets:
   - apps.ghost.dbPassword      # Auto-generated if missing
   - apps.ghost.jwtSecret       # Auto-generated if missing
   - apps.postgresql.password   # Auto-generated if missing (dependency)

future/independent-versioning.md

@@ -0,0 +1,549 @@
+# Independent Component Versioning (Future Design)
+
+This document describes a future enhancement for Wild Cloud where each component (API, CLI, Web) can have independent versions while still being bundled together in versioned packages.
+
+**Status**: Design document for future implementation
+**Current Implementation**: Unified versioning (single VERSION file)
+**Migration Path**: Can be implemented once we reach v1.0.0 and need API stability
+
+---
+
+## Why Independent Versioning?
+
+### Current Limitations (Unified Versioning)
+- CLI can't be updated without releasing entire package
+- API bug fix requires new package even if CLI/Web unchanged
+- Can't signal API breaking changes vs CLI enhancements independently
+- Users can't install just CLI on CI machines with specific version
+
+### Benefits of Independent Versioning
+- **CLI Independence**: Download/install CLI separately for CI/automation
+- **API Stability Signals**: API version communicates breaking changes
+- **Flexible Release Cadence**: Update components on different schedules
+- **Better Compatibility Communication**: "CLI v0.9 works with API v1.2-1.3"
+- **Reduced Package Churn**: Don't republish entire package for small fixes
+
+---
+
+## Architecture Overview
+
+### Version Files (4 files)
+
+```
+wild-cloud/
+├── VERSION                    # Package/distribution version: 0.1.1
+├── api/VERSION               # API version: 1.2.3
+├── cli/VERSION               # CLI version: 0.8.1
+└── web/VERSION               # Web version: 0.5.2
+```
+
+### Compatibility Matrix
+
+```yaml
+# wild-cloud/MANIFEST.yaml
+package:
+  version: "0.1.1"
+  name: "wild-cloud-central"
+  description: "Wild Cloud Central Management Service"
+
+components:
+  api:
+    version: "1.2.3"
+    compatibility:
+      min_cli_version: "0.7.0"    # Oldest CLI that works
+      max_cli_version: "0.9.x"    # Newest CLI tested
+
+  cli:
+    version: "0.8.1"
+    compatibility:
+      min_api_version: "1.1.0"    # Oldest API supported
+      max_api_version: "1.2.x"    # Newest API supported
+
+  web:
+    version: "0.5.2"
+    compatibility:
+      requires_api_version: "1.2.3"  # Exact API version required
+
+# What combinations have been tested and certified
+tested_combinations:
+  - package: "0.1.1"
+    api: "1.2.3"
+    cli: "0.8.1"
+    web: "0.5.2"
+    notes: "Stable release, all features tested"
+
+  - package: "0.1.0"
+    api: "1.2.2"
+    cli: "0.8.0"
+    web: "0.5.1"
+    notes: "Previous stable release"
+```
+
+---
+
+## Version Semantics
+
+### API Version (Server/Backend)
+**Format**: `MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Breaking API changes
+  - Endpoints removed or renamed
+  - Request/response format changes
+  - Authentication mechanism changes
+  - Example: `1.2.3` → `2.0.0`
+
+- **MINOR**: New features, backward compatible
+  - New endpoints added
+  - New optional parameters
+  - New response fields
+  - Example: `1.2.3` → `1.3.0`
+
+- **PATCH**: Bug fixes only
+  - No API contract changes
+  - Performance improvements
+  - Security patches
+  - Example: `1.2.3` → `1.2.4`
+
+**Stability Promise**:
+- CLI version `0.8.x` guaranteed to work with API `1.2.x`
+- CLI version `0.8.x` should work with API `1.3.x` (newer minor)
+- CLI version `0.8.x` will NOT work with API `2.0.x` (major bump)
+
+### CLI Version (Client Tool)
+**Format**: `MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Breaking CLI changes
+  - Command structure changes
+  - Flag renames or removal
+  - Configuration format changes
+  - Example: `0.8.1` → `1.0.0`
+
+- **MINOR**: New features
+  - New commands
+  - New flags (backward compatible)
+  - Can use new API features if available
+  - Example: `0.8.1` → `0.9.0`
+
+- **PATCH**: Bug fixes and improvements
+  - Error message improvements
+  - Performance fixes
+  - Documentation updates
+  - Example: `0.8.1` → `0.8.2`
+
+**Compatibility Promise**:
+- CLI gracefully degrades when API doesn't support new features
+- `wild app deploy` with new flag works with old API (ignores new features)
+- CLI checks API version and warns about incompatibilities
+
+### Web Version (Frontend UI)
+**Format**: `MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Major UI redesign or breaking changes
+- **MINOR**: New features, new pages
+- **PATCH**: Bug fixes, UX improvements
+
+**Note**: Web is typically tightly coupled to API and bundled together. Rarely released independently.
+
+### Package Version (Distribution)
+**Format**: `MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Major milestone releases (v1.0.0, v2.0.0)
+- **MINOR**: New features or significant updates
+- **PATCH**: Bug fixes, component version bumps
+
+**Purpose**: Tracks the tested, certified combination of components.
+
+---
+
+## Implementation Details
+
+### 1. Build System Changes
+
+#### Makefile Reads All Versions
+```makefile
+# Read all version files
+PACKAGE_VERSION := $(shell cat ../VERSION 2>/dev/null || echo "0.0.0-dev")
+API_VERSION := $(shell cat ../api/VERSION 2>/dev/null || echo "0.0.0-dev")
+CLI_VERSION := $(shell cat ../cli/VERSION 2>/dev/null || echo "0.0.0-dev")
+WEB_VERSION := $(shell cat ../web/VERSION 2>/dev/null || echo "0.0.0-dev")
+
+# Version info target
+version:
+	@echo "Package: v$(PACKAGE_VERSION)"
+	@echo "  API:   v$(API_VERSION)"
+	@echo "  CLI:   v$(CLI_VERSION)"
+	@echo "  Web:   v$(WEB_VERSION)"
+
+# Build with component versions injected
+build-api:
+	cd $(API_SOURCE) && GOOS=linux GOARCH=amd64 \
+		go build -ldflags="-X main.Version=$(API_VERSION) -X main.PackageVersion=$(PACKAGE_VERSION)" \
+		-o ../dist/$(AMD64_BINARY) .
+
+build-cli:
+	cd ../cli && GOOS=linux GOARCH=amd64 \
+		go build -ldflags="-X main.Version=$(CLI_VERSION)" \
+		-o ../dist/build/wild-cli-$(CLI_VERSION)-amd64 .
+```
+
+### 2. CLI Version Command with Compatibility Check
+
+```go
+// cli/cmd/version.go
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+var Version = "dev" // Injected at build time
+
+type APIVersion struct {
+	Version       string `json:"version"`
+	MinCLIVersion string `json:"minCliVersion"`
+}
+
+var versionCmd = &cobra.Command{
+	Use:   "version",
+	Short: "Show version information and API compatibility",
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Printf("Wild CLI v%s\n", Version)
+
+		// Try to get API version if connected
+		apiURL := getAPIURL() // From config
+		if apiURL != "" {
+			apiVersion, err := getAPIVersion(apiURL)
+			if err == nil {
+				compatible := checkCompatibility(Version, apiVersion)
+				status := "✓"
+				if !compatible {
+					status = "⚠️"
+				}
+				fmt.Printf("Connected to API v%s %s\n", apiVersion.Version, status)
+
+				if !compatible {
+					fmt.Printf("  Warning: CLI v%s may not be fully compatible with API v%s\n",
+						Version, apiVersion.Version)
+					fmt.Printf("  Recommended CLI version: >= v%s\n", apiVersion.MinCLIVersion)
+				}
+			}
+		}
+	},
+}
+
+func getAPIVersion(apiURL string) (*APIVersion, error) {
+	resp, err := http.Get(apiURL + "/api/v1/version")
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	var version APIVersion
+	if err := json.NewDecoder(resp.Body).Decode(&version); err != nil {
+		return nil, err
+	}
+	return &version, nil
+}
+
+func checkCompatibility(cliVersion string, apiVersion *APIVersion) bool {
+	// Simple semantic version comparison
+	// Full implementation would use proper semver library
+	cliMajor := strings.Split(cliVersion, ".")[0]
+	minMajor := strings.Split(apiVersion.MinCLIVersion, ".")[0]
+
+	return cliMajor >= minMajor
+}
+```
+
+### 3. API Version Endpoint
+
+```go
+// api/internal/api/v1/handlers_version.go
+package v1
+
+import (
+	"net/http"
+)
+
+var Version = "dev"        // Injected at build
+var PackageVersion = "dev" // Injected at build
+
+type VersionResponse struct {
+	Version        string `json:"version"`
+	PackageVersion string `json:"packageVersion"`
+	MinCLIVersion  string `json:"minCliVersion"`
+	MaxCLIVersion  string `json:"maxCliVersion"`
+}
+
+func (api *API) GetVersion(w http.ResponseWriter, r *http.Request) {
+	respondJSON(w, http.StatusOK, VersionResponse{
+		Version:        Version,
+		PackageVersion: PackageVersion,
+		MinCLIVersion:  "0.7.0",  // Could read from MANIFEST.yaml
+		MaxCLIVersion:  "0.9.x",
+	})
+}
+
+// Register route in handlers.go
+// r.HandleFunc("/api/v1/version", api.GetVersion).Methods("GET")
+```
+
+### 4. Release Script Support for Component Releases
+
+```bash
+#!/bin/bash
+# scripts/create-release.sh
+
+PACKAGE_VERSION=$(cat ../VERSION)
+API_VERSION=$(cat ../api/VERSION)
+CLI_VERSION=$(cat ../cli/VERSION)
+WEB_VERSION=$(cat ../web/VERSION)
+
+RELEASE_TYPE="$1"  # "package", "cli", "api"
+
+case "$RELEASE_TYPE" in
+  "package")
+    # Full package release
+    TAG="v${PACKAGE_VERSION}"
+    TITLE="Wild Cloud Central v${PACKAGE_VERSION}"
+    BODY="Package includes: API v${API_VERSION}, CLI v${CLI_VERSION}, Web v${WEB_VERSION}"
+
+    create_release "$TAG" "$TITLE" "$BODY"
+    upload_debs
+    ;;
+
+  "cli")
+    # CLI-only release
+    TAG="cli-v${CLI_VERSION}"
+    TITLE="Wild CLI v${CLI_VERSION}"
+    BODY="Standalone CLI release. Compatible with API v${API_VERSION}"
+
+    create_release "$TAG" "$TITLE" "$BODY"
+    upload_cli_binaries
+    ;;
+
+  "api")
+    # API update within existing package
+    TAG="v${PACKAGE_VERSION}"
+
+    if release_exists "$TAG"; then
+      update_release_assets "$TAG"
+    else
+      echo "Package version not changed, updating existing release"
+      update_release_assets "$(get_latest_release_tag)"
+    fi
+    ;;
+esac
+```
+
+### 5. Compatibility Validation Script
+
+```bash
+#!/bin/bash
+# scripts/check-compatibility.sh
+
+MANIFEST="wild-cloud/MANIFEST.yaml"
+
+API_VERSION=$(cat wild-cloud/api/VERSION)
+CLI_VERSION=$(cat wild-cloud/cli/VERSION)
+WEB_VERSION=$(cat wild-cloud/web/VERSION)
+
+echo "Checking version compatibility..."
+
+# Check if this combination is in tested_combinations
+TESTED=$(yq eval ".tested_combinations[] | select(.api == \"$API_VERSION\" and .cli == \"$CLI_VERSION\" and .web == \"$WEB_VERSION\")" "$MANIFEST")
+
+if [ -n "$TESTED" ]; then
+  echo "✓ Component versions have been tested together"
+else
+  echo "⚠️  Warning: This combination has not been tested"
+  echo "  API: $API_VERSION"
+  echo "  CLI: $CLI_VERSION"
+  echo "  Web: $WEB_VERSION"
+  echo ""
+  echo "Run full integration tests before release"
+  exit 1
+fi
+
+# Check CLI compatibility with API
+MIN_CLI=$(yq eval ".components.api.compatibility.min_cli_version" "$MANIFEST")
+if version_less_than "$CLI_VERSION" "$MIN_CLI"; then
+  echo "✗ CLI version $CLI_VERSION is older than minimum required $MIN_CLI"
+  exit 1
+fi
+
+echo "✓ All compatibility checks passed"
+```
+
+---
+
+## Migration Path
+
+### Phase 1: Preparation (Current: v0.x.x)
+- Continue using unified VERSION file
+- Build foundation for independent versioning
+- Document API surface and breaking changes
+
+### Phase 2: Soft Migration (v0.9.x)
+- Create component VERSION files
+- Keep them in sync with package VERSION
+- Add compatibility checking code (unused)
+- Test infrastructure
+
+### Phase 3: Independent Releases (v1.0.0+)
+- Start versioning components independently
+- First CLI-only release
+- Update MANIFEST.yaml with compatibility matrix
+- Enable compatibility warnings
+
+### Phase 4: Mature State (v1.1.0+)
+- Components release on different cadences
+- API maintains backward compatibility
+- CLI works with multiple API versions
+- Well-tested compatibility matrix
+
+---
+
+## Release Workflows
+
+### Workflow 1: Bug Fix in API Only
+```bash
+# Bump only API version
+echo "1.2.4" > api/VERSION
+
+# Optionally bump package patch version
+echo "0.1.2" > VERSION
+
+# Build and release
+make package-all
+make release-package  # Updates/creates v0.1.2 with API v1.2.4
+```
+
+### Workflow 2: New CLI Feature (Standalone)
+```bash
+# Bump CLI version
+echo "0.9.0" > cli/VERSION
+
+# Build CLI
+cd cli && make build
+
+# Release CLI independently
+make release-cli  # Creates cli-v0.9.0 tag with standalone binary
+
+# Users can: wget .../cli-v0.9.0/wild-amd64
+```
+
+### Workflow 3: Major Package Release
+```bash
+# Bump all versions
+echo "2.0.0" > api/VERSION      # Breaking API changes
+echo "1.0.0" > cli/VERSION      # CLI redesign
+echo "1.0.0" > web/VERSION      # New UI
+echo "1.0.0" > VERSION          # Major package milestone
+
+# Update MANIFEST.yaml with new compatibility rules
+vim wild-cloud/MANIFEST.yaml
+
+# Run compatibility checks
+./scripts/check-compatibility.sh
+
+# Build and release
+make package-all
+make release-package  # Creates v1.0.0
+```
+
+### Workflow 4: Hotfix in Testing
+```bash
+# Fix bug, no version bump
+git commit -m "Fix: cluster deletion bug"
+
+# Rebuild and update current release
+make package-all
+make release-package  # Updates existing release assets
+```
+
+---
+
+## Benefits Summary
+
+### For Users
+- Download just CLI for automation/CI (smaller, faster)
+- Know when API changes might break scripts (version signals)
+- Get bug fixes without reinstalling entire package
+- Clear compatibility information (`wild --version`)
+
+### For Developers
+- Release components independently (faster iteration)
+- Signal breaking changes appropriately (API major version)
+- Test combinations in compatibility matrix
+- Reduce package release churn
+
+### For DevOps
+- Pin CLI version in CI/CD pipelines
+- Upgrade API without updating all CLI installations
+- Clear upgrade paths and compatibility docs
+- Automated compatibility checking
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Foundation
+- [ ] Create component VERSION files (keep in sync initially)
+- [ ] Add version injection to all components
+- [ ] Create MANIFEST.yaml structure
+- [ ] Add `GET /api/v1/version` endpoint
+- [ ] Add `wild version` command with compatibility check
+
+### Phase 2: Build System
+- [ ] Update Makefile to read all VERSION files
+- [ ] Add compatibility validation script
+- [ ] Create release script for different release types
+- [ ] Test version injection in builds
+- [ ] Document version management workflow
+
+### Phase 3: Release Infrastructure
+- [ ] Support package releases (current behavior)
+- [ ] Support CLI-only releases (new tag structure)
+- [ ] Support updating existing release assets
+- [ ] Create GitHub/Gitea release templates
+- [ ] Add CI/CD integration for automated releases
+
+### Phase 4: Documentation
+- [ ] Document versioning strategy
+- [ ] Create compatibility matrix documentation
+- [ ] Write upgrade guides
+- [ ] Add troubleshooting for version mismatches
+- [ ] Create developer guide for version bumping
+
+---
+
+## Open Questions
+
+1. **CLI Distribution**: Should CLI be in separate GitHub releases or same repo with different tags?
+   - Recommendation: Same repo, different tags (`cli-v0.9.0`)
+
+2. **Version Discovery**: Should CLI auto-update check?
+   - Recommendation: No auto-update, but check for new versions on `--version`
+
+3. **API Version in URL**: Should we support `/api/v2/` for major versions?
+   - Recommendation: Not initially, version in header is sufficient
+
+4. **Deprecation Policy**: How long to support old API versions?
+   - Recommendation: N-1 major version (API v2.x supports v1.x clients)
+
+---
+
+## References
+
+- **Kubernetes**: kubectl ±1 minor version skew policy
+- **Docker**: CLI forward compatibility with engine
+- **Terraform**: Provider versioning model
+- **HashiCorp Consul**: API versioning strategy
+
+This design provides maximum flexibility for component independence while maintaining package simplicity during development.