Adds docs useful for AI assistant context.

2025-09-28 15:25:43 -07:00
parent 838903e27d
commit 9877d73814
16 changed files with 5887 additions and 0 deletions
--- a/docs/agent-context/wildcloud/README.md
+++ b/docs/agent-context/wildcloud/README.md
@@ -0,0 +1,188 @@
+# Wild Cloud Agent Context Documentation
+
+This directory contains comprehensive documentation about the Wild Cloud project, designed to provide AI agents (like Claude Code) with the context needed to effectively help users with Wild Cloud development, deployment, and operations.
+
+## Documentation Overview
+
+### 📚 Core Documentation Files
+
+1. **[overview.md](./overview.md)** - Complete project introduction and getting started guide
+   - What Wild Cloud is and why it exists
+   - Technology stack and architecture overview
+   - Quick start guide and common use cases
+   - Best practices and troubleshooting
+
+2. **[bin-scripts.md](./bin-scripts.md)** - Complete CLI reference
+   - All 34+ `wild-*` commands with usage examples
+   - Command categories (setup, apps, config, operations)
+   - Script dependencies and execution order
+   - Common usage patterns
+
+3. **[setup-process.md](./setup-process.md)** - Infrastructure deployment deep dive
+   - Complete setup phases and dependencies
+   - Talos Linux and Kubernetes cluster deployment
+   - Core services installation (MetalLB, Traefik, cert-manager, etc.)
+   - Network configuration and DNS management
+
+4. **[apps-system.md](./apps-system.md)** - Application management system
+   - App structure and lifecycle management
+   - Template system and configuration
+   - Available applications and their features
+   - Creating custom applications
+
+5. **[configuration-system.md](./configuration-system.md)** - Configuration and secrets management
+   - `config.yaml` and `secrets.yaml` structure
+   - Template processing with gomplate
+   - Environment setup and validation
+   - Security best practices
+
+6. **[project-architecture.md](./project-architecture.md)** - Project structure and organization
+   - Wild Cloud repository structure
+   - User cloud directory layout
+   - File permissions and security model
+   - Development and deployment patterns
+
+## Quick Reference Guide
+
+### Essential Commands
+```bash
+# Setup & Initialization
+wild-init                    # Initialize new cloud
+wild-setup                   # Complete deployment
+wild-health                  # System health check
+
+# Application Management
+wild-apps-list              # List available apps
+wild-app-add <app>          # Configure app
+wild-app-deploy <app>       # Deploy app
+
+# Configuration
+wild-config <key>           # Read config
+wild-config-set <key> <val> # Set config
+wild-secret <key>           # Read secret
+```
+
+### Key File Locations
+
+**Wild Cloud Repository** (`WC_ROOT`):
+- `bin/` - All CLI commands
+- `apps/` - Application templates
+- `setup/` - Infrastructure templates
+- `docs/` - Documentation
+
+**User Cloud Directory** (`WC_HOME`):
+- `config.yaml` - Main configuration
+- `secrets.yaml` - Sensitive data
+- `apps/` - Deployed app configs
+- `.wildcloud/` - Project marker
+
+### Application Categories
+
+- **Content**: Ghost (blog), Discourse (forum)
+- **Media**: Immich (photos)
+- **Development**: Gitea (Git), Docker Registry
+- **Databases**: PostgreSQL, MySQL, Redis
+- **AI/ML**: vLLM (LLM inference)
+
+## Technology Stack Summary
+
+### Core Infrastructure
+- **Talos Linux** - Immutable Kubernetes OS
+- **Kubernetes** - Container orchestration
+- **MetalLB** - Load balancing
+- **Traefik** - Ingress/reverse proxy
+- **Longhorn** - Distributed storage
+- **cert-manager** - TLS certificates
+
+### Management Tools
+- **gomplate** - Template processing
+- **Kustomize** - Configuration management
+- **restic** - Backup system
+- **kubectl/talosctl** - Cluster management
+
+## Common Agent Tasks
+
+### When Users Ask About...
+
+**"How do I deploy X?"**
+- Check apps-system.md for application management
+- Look for X in available applications list
+- Reference app deployment lifecycle
+
+**"Setup isn't working"**
+- Review setup-process.md for troubleshooting
+- Check bin-scripts.md for command options
+- Verify prerequisites and dependencies
+
+**"How do I configure Y?"**
+- Check configuration-system.md for config management
+- Look at project-architecture.md for file locations
+- Review template processing documentation
+
+**"What does wild-X command do?"**
+- Reference bin-scripts.md for complete command documentation
+- Check command categories and usage patterns
+- Look at dependencies between commands
+
+### Development Tasks
+
+**Creating New Apps**:
+1. Review apps-system.md "Creating Custom Apps" section
+2. Follow Wild Cloud app structure conventions
+3. Use project-architecture.md for file organization
+4. Test with standard app deployment workflow
+
+**Modifying Infrastructure**:
+1. Check setup-process.md for infrastructure components
+2. Review configuration-system.md for template processing
+3. Understand project-architecture.md file relationships
+4. Test changes carefully in development environment
+
+**Troubleshooting Issues**:
+1. Use bin-scripts.md for diagnostic commands
+2. Check setup-process.md for component validation
+3. Review configuration-system.md for config problems
+4. Reference apps-system.md for application issues
+
+## Best Practices for Agents
+
+### Understanding User Context
+- Always check if they're in a Wild Cloud directory (look for `.wildcloud/`)
+- Determine if they need setup help vs operational help
+- Consider their experience level (beginner vs advanced)
+- Check what applications they're trying to deploy
+
+### Providing Help
+- Reference specific documentation sections for detailed info
+- Provide exact command syntax from bin-scripts.md
+- Explain prerequisites and dependencies
+- Offer validation steps to verify success
+
+### Safety Considerations
+- Always recommend testing in development first
+- Warn about destructive operations (delete, reset)
+- Emphasize backup importance before major changes
+- Explain security implications of configuration changes
+
+### Common Gotchas
+- `secrets.yaml` has restricted permissions (600)
+- Templates need processing before deployment
+- Dependencies between applications must be satisfied
+- Node hardware detection requires maintenance mode boot
+
+## Documentation Maintenance
+
+This documentation should be updated when:
+- New commands are added to `bin/`
+- New applications are added to `apps/`
+- Infrastructure components change
+- Configuration schema evolves
+- Best practices are updated
+
+Each documentation file includes:
+- Complete coverage of its topic area
+- Practical examples and use cases
+- Troubleshooting guidance
+- References to related documentation
+
+This comprehensive context should enable AI agents to provide expert-level assistance with Wild Cloud projects across all aspects of the system.
--- a/docs/agent-context/wildcloud/apps-system.md
+++ b/docs/agent-context/wildcloud/apps-system.md
@@ -0,0 +1,603 @@
+# Wild Cloud Apps System
+
+The Wild Cloud apps system provides a streamlined way to deploy and manage applications on your Kubernetes cluster. It uses Kustomize for configuration management and follows a standardized structure for consistent deployment patterns.
+
+## App Structure and Components
+
+### Directory Structure
+Each subdirectory represents a Wild Cloud app. Each app directory contains:
+
+**Required Files:**
+- `manifest.yaml` - App metadata and configuration
+- `kustomization.yaml` - Kustomize configuration with Wild Cloud labels
+
+**Standard Configuration Files (one or more YAML files containing Kubernetes resource definitions):**
+```
+apps/myapp/
+├── manifest.yaml          # Required: App metadata and configuration
+├── kustomization.yaml     # Required: Kustomize configuration with Wild Cloud labels
+├── namespace.yaml         # Kubernetes namespace definition
+├── deployment.yaml        # Application deployment
+├── service.yaml           # Kubernetes service definition
+├── ingress.yaml           # HTTPS ingress with external DNS
+├── pvc.yaml               # Persistent volume claims (if needed)
+├── db-init-job.yaml       # Database initialization (if needed)
+└── configmap.yaml         # Configuration data (if needed)
+```
+
+### App Manifest (`manifest.yaml`)
+
+The required `manifest.yaml` file contains metadata about the app. Here's an example `manifest.yaml` file:
+
+```yaml
+name: myapp
+description: A brief description of the application and its purpose.
+version: 1.0.0
+icon: https://example.com/icon.png
+requires:
+  - name: postgres
+defaultConfig:
+  image: myapp/server:1.0.0
+  domain: myapp.{{ .cloud.domain }}
+  timezone: UTC
+  storage: 10Gi
+  dbHostname: postgres.postgres.svc.cluster.local
+  dbUsername: myapp
+requiredSecrets:
+  - apps.myapp.dbPassword
+  - apps.postgres.password
+```
+
+**Manifest Fields**:
+- `name` - The name of the app, used for identification (must match directory name)
+- `description` - A brief description of the app
+- `version` - The version of the app (should generally follow the versioning scheme of the app itself)
+- `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)
+
+### Kustomization Configuration
+
+Wild Cloud apps use standard Kustomize with required Wild Cloud labels:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: myapp
+labels:
+  - includeSelectors: true
+    pairs:
+      app: myapp
+      managedBy: kustomize
+      partOf: wild-cloud
+resources:
+  - namespace.yaml
+  - deployment.yaml
+  - service.yaml
+  - ingress.yaml
+  - pvc.yaml
+  - db-init-job.yaml
+```
+
+**Kustomization Requirements**:
+- Every Wild Cloud kustomization should include the Wild Cloud labels in its `kustomization.yaml` file (this allows Wild Cloud to identify and manage the app correctly)
+- The `app` label and `namespace` should match the app's name/directory
+- **includeSelectors: true** - Automatically applies labels to all resources AND their selectors
+
+#### Standard Wild Cloud Labels
+
+Wild Cloud uses a consistent labeling strategy across all apps:
+
+```yaml
+labels:
+  - includeSelectors: true
+    pairs:
+      app: myapp              # The app name (matches directory)
+      managedBy: kustomize    # Managed by Kustomize
+      partOf: wild-cloud      # Part of Wild Cloud ecosystem
+```
+
+The `includeSelectors: true` setting automatically applies these labels to all resources AND their selectors, which means:
+
+1. **Resource labels** - All resources get the standard Wild Cloud labels
+2. **Selector labels** - All selectors automatically include these labels for robust selection
+
+This allows individual resources to use simple, component-specific selectors:
+
+```yaml
+selector:
+  matchLabels:
+    component: web
+```
+
+Which Kustomize automatically expands to:
+
+```yaml
+selector:
+  matchLabels:
+    app: myapp
+    component: web
+    managedBy: kustomize
+    partOf: wild-cloud
+```
+
+### Template System
+
+Wild Cloud apps are actually **templates** that get compiled with your specific configuration when you run `wild-app-add`. This allows for:
+
+- **Dynamic Configuration** - Reference user settings via `{{ .apps.appname.key }}`
+- **Gomplate Processing** - Full template capabilities including conditionals and loops
+- **Secret Integration** - Automatic secret generation and referencing
+- **Domain Management** - Automatic subdomain assignment based on your domain
+
+**Template Variable Examples**:
+```yaml
+# Configuration references
+image: "{{ .apps.myapp.image }}"
+domain: "{{ .apps.myapp.domain }}"
+namespace: "{{ .apps.myapp.namespace }}"
+
+# Cloud-wide settings
+timezone: "{{ .cloud.timezone }}"
+domain_suffix: "{{ .cloud.domain }}"
+
+# Conditional logic
+{{- if .apps.myapp.enableSSL }}
+- name: ENABLE_SSL
+  value: "true"
+{{- end }}
+```
+
+## App Lifecycle Management
+
+### 1. Discovery Phase
+**Command**: `wild-apps-list`
+
+Lists all available applications with metadata:
+```bash
+wild-apps-list --verbose    # Detailed view with descriptions
+wild-apps-list --json       # JSON output for automation
+```
+
+Shows:
+- App name and description
+- Version and dependencies
+- Installation status
+- Required configuration
+
+### 2. Fetching Phase
+**Command**: `wild-app-fetch <app-name>`
+
+Downloads app templates to local cache:
+- Copies app directory from Wild Cloud repository
+- Stores in `.wildcloud/cache/apps/`
+- Options: `--update` to overwrite existing cache
+- Required before configuration or deployment
+
+### 3. Configuration Phase
+**Command**: `wild-app-add <app-name>`
+
+Processes app templates and prepares for deployment:
+
+**What it does**:
+1. Reads app manifest from cache
+2. Merges default configuration with existing `config.yaml`
+3. Generates required secrets automatically
+4. Compiles templates with gomplate using your configuration
+5. Creates ready-to-deploy Kustomize files in `apps/<app-name>/`
+
+**Generated Files**:
+- Compiled Kubernetes manifests (no more template variables)
+- Standard Kustomize configuration
+- App-specific configuration merged into your `config.yaml`
+- Required secrets added to your `secrets.yaml`
+
+### 4. Deployment Phase
+**Command**: `wild-app-deploy <app-name>`
+
+Deploys the app to your Kubernetes cluster:
+
+**Deployment Process**:
+1. Creates namespace if it doesn't exist
+2. Handles app dependencies (deploys required apps first)
+3. Creates secrets from your `secrets.yaml`
+4. Applies Kustomize configuration to cluster
+5. Copies TLS certificates to app namespace
+6. Validates deployment success
+
+**Options**:
+- `--force` - Overwrite existing resources
+- `--dry-run` - Preview changes without applying
+
+### 5. Operations Phase
+
+**Monitoring**: `wild-app-doctor <app-name>`
+- Runs app-specific diagnostic tests
+- Checks pod status, resource usage, connectivity
+- Options: `--keep`, `--follow`, `--timeout`
+
+**Updates**: Re-run `wild-app-add` then `wild-app-deploy`
+- Updates configuration changes
+- Handles image updates
+- Preserves persistent data
+
+**Removal**: `wild-app-delete <app-name>`
+- Deletes namespace and all resources
+- Removes local configuration files
+- Options: `--force` for no confirmation
+
+## Configuration System
+
+### Configuration Storage
+
+**Global Configuration** (`config.yaml`):
+```yaml
+cloud:
+  domain: example.com
+  timezone: America/New_York
+apps:
+  myapp:
+    domain: app.example.com
+    image: myapp:1.0.0
+    storage: 20Gi
+    timezone: UTC
+```
+
+**Secrets Management** (`secrets.yaml`):
+```yaml
+apps:
+  myapp:
+    dbPassword: "randomly-generated-password"
+    adminPassword: "user-set-password"
+  postgres:
+    password: "randomly-generated-password"
+```
+
+### Secret Generation
+
+When you run `wild-app-add`, required secrets are automatically generated:
+- **Random Generation**: 32-character base64 strings for passwords/keys
+- **User Prompts**: For secrets that need specific values
+- **Preservation**: Existing secrets are never overwritten
+- **Permissions**: `secrets.yaml` has 600 permissions (owner-only)
+
+### Configuration Commands
+```bash
+# Read app configuration
+wild-config apps.myapp.domain
+
+# Set app configuration
+wild-config-set apps.myapp.storage "50Gi"
+
+# Read app secrets
+wild-secret apps.myapp.dbPassword
+
+# Set app secrets
+wild-secret-set apps.myapp.adminPassword "my-secure-password"
+```
+
+## Networking and DNS
+
+### External DNS Integration
+
+Wild Cloud apps automatically manage DNS records through ingress annotations:
+
+```yaml
+metadata:
+  annotations:
+    external-dns.alpha.kubernetes.io/target: {{ .cloud.domain }}
+    external-dns.alpha.kubernetes.io/cloudflare-proxied: "false"
+```
+
+**How it works**:
+1. App ingress created with external-dns annotations
+2. ExternalDNS controller detects new ingress
+3. Creates CNAME record: `app.yourdomain.com` → `yourdomain.com`
+4. DNS resolves to MetalLB load balancer IP
+5. Traefik routes traffic to appropriate service
+
+### HTTPS Certificate Management
+
+Automatic TLS certificates via cert-manager:
+
+```yaml
+metadata:
+  annotations:
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt
+spec:
+  tls:
+    - hosts:
+        - {{ .apps.myapp.domain }}
+      secretName: myapp-tls
+```
+
+**Certificate Lifecycle**:
+1. Ingress created with TLS configuration
+2. cert-manager detects certificate requirement
+3. Let's Encrypt challenge initiated automatically
+4. Certificate issued and stored in Kubernetes secret
+5. Traefik uses certificate for TLS termination
+6. Automatic renewal before expiration
+
+## Database Integration
+
+### Database Initialization Jobs
+
+Apps that require databases use initialization jobs to set up the database before the main application starts:
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: myapp-db-init
+spec:
+  template:
+    spec:
+      containers:
+      - name: db-init
+        image: postgres:15
+        command:
+          - /bin/bash
+          - -c
+          - |
+            PGPASSWORD=$ROOT_PASSWORD psql -h $DB_HOST -U postgres -c "
+              CREATE DATABASE IF NOT EXISTS $DB_NAME;
+              CREATE USER $DB_USER WITH PASSWORD '$DB_PASSWORD';
+              GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;
+            "
+        env:
+        - name: DB_HOST
+          value: {{ .apps.myapp.dbHostname }}
+        - name: ROOT_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: myapp-secrets
+              key: apps.postgres.password
+      restartPolicy: OnFailure
+```
+
+**Database URL Secrets**: For apps requiring database URLs with embedded credentials, always use dedicated secrets:
+
+```yaml
+# In manifest.yaml
+requiredSecrets:
+  - apps.myapp.dbUrl
+
+# Generated secret (by wild-app-add)
+apps:
+  myapp:
+    dbUrl: "postgresql://myapp:password123@postgres.postgres.svc.cluster.local/myapp"
+```
+
+### Supported Databases
+
+Wild Cloud apps commonly integrate with:
+- **PostgreSQL** - Via `postgres` app dependency
+- **MySQL** - Via `mysql` app dependency
+- **Redis** - Via `redis` app dependency
+- **SQLite** - For apps with embedded database needs
+
+## Storage Management
+
+### Persistent Volume Claims
+
+Apps requiring persistent storage define PVCs:
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: myapp-data
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: longhorn
+  resources:
+    requests:
+      storage: {{ .apps.myapp.storage }}
+```
+
+**Storage Integration**:
+- **Longhorn Storage Class** - Distributed, replicated storage
+- **Dynamic Provisioning** - Automatic volume creation
+- **Backup Support** - Via `wild-app-backup` command
+- **Expansion** - Update storage size in configuration
+
+### Backup and Restore
+
+**Application Backup**: `wild-app-backup <app-name>`
+- Discovers databases and PVCs automatically
+- Creates restic snapshots with deduplication
+- Supports PostgreSQL and MySQL database backups
+- Streams PVC data for efficient storage
+
+**Application Restore**: `wild-app-restore <app-name> <snapshot-id>`
+- Restores from restic snapshots
+- Options: `--db-only`, `--pvc-only`, `--skip-globals`
+- Creates safety snapshots before destructive operations
+
+## Security Considerations
+
+### Pod Security Standards
+
+All Wild Cloud apps comply with Pod Security Standards:
+
+```yaml
+spec:
+  template:
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 999
+        runAsGroup: 999
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+      - name: app
+        securityContext:
+          allowPrivilegeEscalation: false
+          capabilities:
+            drop:
+            - ALL
+          readOnlyRootFilesystem: false  # Set to true when possible
+```
+
+### Secret Management
+
+- **Kubernetes Secrets** - All sensitive data stored as Kubernetes secrets
+- **Secret References** - Apps reference secrets via `secretKeyRef`, never inline
+- **Full Dotted Paths** - Always use complete secret paths (e.g., `apps.myapp.dbPassword`)
+- **No Plaintext** - Secrets never stored in manifests or config files
+
+### Network Policies
+
+Apps can define network policies for traffic isolation:
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: myapp-network-policy
+spec:
+  podSelector:
+    matchLabels:
+      app: myapp
+  ingress:
+  - from:
+    - namespaceSelector:
+        matchLabels:
+          name: traefik
+```
+
+## Available Applications
+
+Wild Cloud includes apps for common self-hosted services:
+
+### Content Management
+- **Ghost** - Publishing platform for blogs and websites
+- **Discourse** - Community discussion platform
+
+### Development & Project Management Tools
+- **Gitea** - Self-hosted Git service with web interface
+- **OpenProject** - Open-source project management software
+- **Docker Registry** - Private container image registry
+
+### Media & File Management
+- **Immich** - Self-hosted photo and video backup solution
+
+### Communication
+- **Keila** - Newsletter and email marketing platform
+- **Listmonk** - Newsletter and mailing list manager
+
+### Databases
+- **PostgreSQL** - Relational database service
+- **MySQL** - Relational database service
+- **Redis** - In-memory data structure store
+- **Memcached** - Distributed memory caching system
+
+### AI/ML
+- **vLLM** - Fast LLM inference server with OpenAI-compatible API
+
+### Examples & Templates
+- **example-admin** - Example admin interface application
+- **example-app** - Template application for development reference
+
+## Creating Custom Apps
+
+### App Development Process
+
+1. **Create Directory**: `apps/myapp/`
+2. **Write Manifest**: Define metadata and configuration
+3. **Create Resources**: Kubernetes manifests with templates
+4. **Test Locally**: Use `wild-app-add` and `wild-app-deploy`
+5. **Validate**: Ensure all resources deploy correctly
+
+### Best Practices
+
+**Manifest Design**:
+- Include comprehensive `defaultConfig` for all configurable values
+- List all `requiredSecrets` the app needs
+- Specify dependencies in `requires` field
+- Use semantic versioning
+
+**Template Usage**:
+- Reference configuration via `{{ .apps.myapp.key }}`
+- Use conditionals for optional features
+- Include proper gomplate syntax for lists and objects
+- Test template compilation
+
+**Resource Configuration**:
+- Always include Wild Cloud standard labels
+- Use appropriate security contexts
+- Define resource requests and limits
+- Include health checks and probes
+
+**Storage and Networking**:
+- Use Longhorn storage class for persistence
+- Include external-dns annotations for automatic DNS
+- Configure TLS certificates via cert-manager annotations
+- Follow database initialization patterns for data apps
+
+### Converting from Helm Charts
+
+Wild Cloud provides tooling to convert Helm charts to Wild Cloud apps:
+
+```bash
+# Convert Helm chart to Kustomize base
+helm fetch --untar --untardir charts stable/mysql
+helm template --output-dir base --namespace mysql mysql charts/mysql
+cd base/mysql
+kustomize create --autodetect
+
+# Then customize for Wild Cloud:
+# 1. Add manifest.yaml
+# 2. Replace hardcoded values with templates
+# 3. Update labels to Wild Cloud standard
+# 4. Configure secrets properly
+```
+
+## Troubleshooting Applications
+
+### Common Issues
+
+**App Won't Start**:
+- Check pod logs: `kubectl logs -n <app-namespace> deployment/<app-name>`
+- Verify secrets exist: `kubectl get secrets -n <app-namespace>`
+- Check resource constraints: `kubectl describe pod -n <app-namespace>`
+
+**Database Connection Issues**:
+- Verify database is running: `kubectl get pods -n <db-namespace>`
+- Check database initialization job: `kubectl logs job/<app>-db-init -n <app-namespace>`
+- Validate database credentials in secrets
+
+**DNS/Certificate Issues**:
+- Check ingress status: `kubectl get ingress -n <app-namespace>`
+- Verify certificate creation: `kubectl get certificates -n <app-namespace>`
+- Check external-dns logs: `kubectl logs -n external-dns deployment/external-dns`
+
+**Storage Issues**:
+- Check PVC status: `kubectl get pvc -n <app-namespace>`
+- Verify Longhorn cluster health: Access Longhorn UI
+- Check storage class availability: `kubectl get storageclass`
+
+### Diagnostic Tools
+
+```bash
+# App-specific diagnostics
+wild-app-doctor <app-name>
+
+# Resource inspection
+kubectl get all -n <app-namespace>
+kubectl describe deployment/<app-name> -n <app-namespace>
+
+# Log analysis
+kubectl logs -f deployment/<app-name> -n <app-namespace>
+kubectl logs job/<app>-db-init -n <app-namespace>
+
+# Configuration verification
+wild-config apps.<app-name>
+wild-secret apps.<app-name>
+```
+
+The Wild Cloud apps system provides a powerful, consistent way to deploy and manage self-hosted applications with enterprise-grade features like automatic HTTPS, DNS management, backup/restore, and integrated security.
--- a/docs/agent-context/wildcloud/bin-scripts.md
+++ b/docs/agent-context/wildcloud/bin-scripts.md
@@ -0,0 +1,264 @@
+# Wild Cloud CLI Scripts Reference
+
+Wild Cloud provides 34+ command-line tools (all prefixed with `wild-`) for managing your personal Kubernetes cloud infrastructure. These scripts handle everything from initial setup to day-to-day operations.
+
+## Script Categories
+
+### 🚀 Initial Setup & Scaffolding
+
+**`wild-init`** - Initialize new Wild Cloud instance
+- Creates `.wildcloud` directory structure
+- Copies template files from repository
+- Sets up basic configuration (email, domains, cluster name)
+- **Usage**: `wild-init`
+- **When to use**: First command to run in a new directory
+
+**`wild-setup`** - Master setup orchestrator
+- Runs complete Wild Cloud deployment sequence
+- Options: `--skip-cluster`, `--skip-services`
+- Executes: cluster setup → services setup
+- **Usage**: `wild-setup [options]`
+- **When to use**: After `wild-init` for complete automated setup
+
+**`wild-update-docs`** - Copy documentation to cloud directory
+- Options: `--force` to overwrite existing docs
+- Copies `/docs` from repository to your cloud home
+- **Usage**: `wild-update-docs [--force]`
+
+### ⚙️ Configuration Management
+
+**`wild-config`** - Read configuration values
+- Access YAML paths from `config.yaml` (e.g., `cluster.name`, `cloud.domain`)
+- Option: `--check` to test key existence
+- **Usage**: `wild-config <key>` or `wild-config --check <key>`
+
+**`wild-config-set`** - Write configuration values
+- Sets values using YAML paths, creates config file if needed
+- **Usage**: `wild-config-set <key> <value>`
+
+**`wild-secret`** - Read secret values
+- Similar to `wild-config` but for sensitive data in `secrets.yaml`
+- File has restrictive permissions (600)
+- **Usage**: `wild-secret <key>` or `wild-secret --check <key>`
+
+**`wild-secret-set`** - Write secret values
+- Generates random values if none provided (32-char base64)
+- **Usage**: `wild-secret-set <key> [value]`
+
+**`wild-compile-template`** - Process gomplate templates
+- Uses `config.yaml` and `secrets.yaml` as template context
+- **Usage**: `wild-compile-template < template.yaml`
+
+**`wild-compile-template-dir`** - Process template directories
+- Options: `--clean` to remove destination first
+- **Usage**: `wild-compile-template-dir <source> <destination>`
+
+### 🏗️ Cluster Infrastructure Management
+
+**`wild-setup-cluster`** - Complete cluster setup (Phases 1-3)
+- Interactive node registration and hardware detection
+- Configures Talos control plane and worker nodes
+- Options: `--skip-installer`, `--skip-hardware`
+- **Usage**: `wild-setup-cluster [options]`
+- **Requires**: `wild-init` completed first
+
+**`wild-cluster-config-generate`** - Generate Talos cluster config
+- Creates base `controlplane.yaml` and `worker.yaml`
+- Generates cluster secrets using `talosctl gen config`
+- **Usage**: `wild-cluster-config-generate`
+
+**`wild-node-detect`** - Hardware detection for nodes
+- Discovers network interfaces and disks from maintenance mode
+- Returns JSON with hardware specifications
+- **Usage**: `wild-node-detect <node-ip>`
+
+**`wild-cluster-node-patch-generate`** - Generate node-specific configs
+- Creates patches based on hardware detection
+- Uses templates with node-specific variables
+- **Usage**: `wild-cluster-node-patch-generate <node-name>`
+
+**`wild-cluster-node-up`** - Apply Talos configuration to nodes
+- Options: `--insecure`, `--force`, `--dry-run`
+- Generates final config from base + patch
+- **Usage**: `wild-cluster-node-up <node-name> [options]`
+
+**`wild-cluster-node-ip`** - Get node IP addresses
+- Sources: config.yaml, kubectl, or talosctl
+- Options: `--from-config`, `--from-talosctl`
+- **Usage**: `wild-cluster-node-ip <node-name> [options]`
+
+### 🔧 Cluster Services Management
+
+**`wild-setup-services`** - Install cluster services (Phase 4)
+- Manages MetalLB, Traefik, cert-manager, etc.
+- Options: `--skip-install` for config generation only
+- **Usage**: `wild-setup-services [options]`
+- **Requires**: Working Kubernetes cluster
+
+**`wild-service-setup`** - Complete service lifecycle management
+- Handles fetch → configure → deploy for individual services
+- Options: `--fetch` for fresh templates, `--no-deploy` for config-only
+- **Usage**: `wild-service-setup <service> [--fetch] [--no-deploy]`
+- **Examples**:
+  - `wild-service-setup cert-manager` (configure + deploy)
+  - `wild-service-setup cert-manager --fetch` (fetch + configure + deploy)
+  - `wild-service-setup cert-manager --no-deploy` (configure only)
+
+**`wild-dashboard-token`** - Get Kubernetes dashboard token
+- Extracts token for dashboard authentication
+- Copies to clipboard if available
+- **Usage**: `wild-dashboard-token`
+
+**`wild-cluster-secret-copy`** - Copy secrets between namespaces
+- **Usage**: `wild-cluster-secret-copy <source-ns:secret> <target-ns1> [target-ns2]`
+
+### 📱 Application Management
+
+**`wild-apps-list`** - List available applications
+- Shows metadata, installation status, dependencies
+- Options: `--verbose`, `--json`, `--yaml`
+- **Usage**: `wild-apps-list [options]`
+
+**`wild-app-fetch`** - Download app templates to cache
+- Options: `--update` to overwrite existing
+- **Usage**: `wild-app-fetch <app-name> [--update]`
+
+**`wild-app-add`** - Configure app from cache
+- Processes manifest.yaml with configuration
+- Generates required secrets automatically
+- Options: `--update` to overwrite existing app files
+- **Usage**: `wild-app-add <app-name> [--update]`
+
+**`wild-app-deploy`** - Deploy application to cluster
+- Creates namespaces, handles dependencies
+- Options: `--force`, `--dry-run`
+- **Usage**: `wild-app-deploy <app-name> [options]`
+
+**`wild-app-delete`** - Remove application
+- Deletes namespace and all resources
+- Options: `--force`, `--dry-run`
+- **Usage**: `wild-app-delete <app-name> [options]`
+
+**`wild-app-doctor`** - Run application diagnostics
+- Executes app-specific diagnostic tests
+- Options: `--keep`, `--follow`, `--timeout`
+- **Usage**: `wild-app-doctor <app-name> [options]`
+
+### 💾 Backup & Restore
+
+**`wild-backup`** - Comprehensive backup system
+- Backs up home directory, apps, and cluster resources
+- Options: `--home-only`, `--apps-only`, `--cluster-only`
+- Uses restic for deduplication
+- **Usage**: `wild-backup [options]`
+
+**`wild-app-backup`** - Application-specific backups
+- Discovers databases and PVCs automatically
+- Supports PostgreSQL and MySQL
+- Options: `--all` for all applications
+- **Usage**: `wild-app-backup <app-name> [--all]`
+
+**`wild-app-restore`** - Application restore
+- Restores databases and/or PVC data
+- Options: `--db-only`, `--pvc-only`, `--skip-globals`
+- **Usage**: `wild-app-restore <app-name> <snapshot-id> [options]`
+
+### 🔍 Utilities & Helpers
+
+**`wild-health`** - System health checks
+- Basic health monitoring for components
+- **Usage**: `wild-health`
+
+**`wild-talos-schema`** - Talos schema management
+- Handles configuration schema operations
+- **Usage**: `wild-talos-schema [options]`
+
+**`wild-cluster-node-boot-assets-download`** - Download Talos assets
+- Downloads installation images for nodes
+- **Usage**: `wild-cluster-node-boot-assets-download`
+
+**`wild-dnsmasq-install`** - Install dnsmasq services
+- Sets up DNS and DHCP for cluster networking
+- **Usage**: `wild-dnsmasq-install`
+
+## Common Usage Patterns
+
+### Complete Setup from Scratch
+```bash
+wild-init                    # Initialize cloud directory
+wild-setup                   # Complete automated setup
+# or step by step:
+wild-setup-cluster           # Just cluster infrastructure
+wild-setup-services          # Just cluster services
+```
+
+### Individual Service Management
+```bash
+# Most common - reconfigure and deploy service
+wild-service-setup cert-manager
+
+# Get fresh templates and deploy (for updates)
+wild-service-setup cert-manager --fetch
+
+# Configure only, don't deploy (for planning)
+wild-service-setup cert-manager --no-deploy
+
+# Fix failed service and resume setup
+wild-service-setup cert-manager --fetch
+wild-setup-services  # Resume full setup if needed
+```
+
+### Application Management
+```bash
+wild-apps-list              # See available apps
+wild-app-fetch ghost        # Download app templates
+wild-app-add ghost          # Configure app
+wild-app-deploy ghost       # Deploy to cluster
+wild-app-doctor ghost       # Troubleshoot issues
+```
+
+### Configuration Management
+```bash
+wild-config cluster.name                    # Read values
+wild-config-set apps.ghost.domain "blog.example.com"  # Write values
+wild-secret apps.ghost.adminPassword       # Read secrets
+wild-secret-set apps.ghost.apiKey          # Generate random secret
+```
+
+### Cluster Operations
+```bash
+wild-cluster-node-ip control-1             # Get node IP
+wild-dashboard-token                        # Get dashboard access
+wild-health                                # Check system health
+```
+
+## Script Design Principles
+
+1. **Consistent Interface**: All scripts use `--help` and follow common argument patterns
+2. **Error Handling**: All scripts use `set -e` and `set -o pipefail` for robust error handling
+3. **Idempotent**: Scripts check existing state before making changes
+4. **Template-Driven**: Extensive use of gomplate for configuration flexibility
+5. **Environment-Aware**: Scripts source `wild-common.sh` and initialize Wild Cloud environment
+6. **Progressive Disclosure**: Complex operations broken into phases with individual controls
+
+## Dependencies Between Scripts
+
+### Setup Phase Dependencies
+1. `wild-init` → creates basic structure
+2. `wild-setup-cluster` → provisions infrastructure
+3. `wild-setup-services` → installs cluster services
+4. `wild-setup` → orchestrates all phases
+
+### App Deployment Pipeline
+1. `wild-apps-list` → discover applications
+2. `wild-app-fetch` → cache app templates
+3. `wild-app-add` → prepare configuration
+4. `wild-app-deploy` → deploy to cluster
+
+### Node Management Flow
+1. `wild-cluster-config-generate` → base configurations
+2. `wild-node-detect` → discover hardware
+3. `wild-cluster-node-patch-generate` → node-specific configs
+4. `wild-cluster-node-up` → apply configurations
+
+All scripts are designed to work together as a cohesive Infrastructure as Code system for personal Kubernetes deployments.
--- a/docs/agent-context/wildcloud/configuration-system.md
+++ b/docs/agent-context/wildcloud/configuration-system.md
@@ -0,0 +1,602 @@
+# Wild Cloud Configuration System
+
+Wild Cloud uses a comprehensive configuration management system that handles both non-sensitive configuration data and sensitive secrets through separate files and commands. The system supports YAML path-based access, template processing, and environment-specific customization.
+
+## Configuration Architecture
+
+### Core Components
+
+1. **`config.yaml`** - Main configuration file for non-sensitive settings
+2. **`secrets.yaml`** - Encrypted/protected storage for sensitive data
+3. **`.wildcloud/`** - Project marker and cache directory
+4. **`env.sh`** - Environment setup and path configuration
+5. **Template System** - gomplate-based dynamic configuration processing
+
+### File Structure of a Wild Cloud Project
+
+```
+your-cloud-directory/
+├── .wildcloud/              # Project marker and cache
+│   ├── cache/              # Downloaded templates and temporary files
+│   └── logs/               # Operation logs
+├── config.yaml             # Main configuration (tracked in git)
+├── secrets.yaml            # Sensitive data (NOT tracked in git, 600 perms)
+├── env.sh                  # Environment setup (auto-generated)
+├── apps/                   # Deployed application configurations
+├── setup/                  # Infrastructure setup files
+└── docs/                   # Project documentation
+```
+
+## Configuration File (`config.yaml`)
+
+### Structure and Organization
+
+The configuration file uses a hierarchical YAML structure for organizing settings:
+
+```yaml
+# Cloud-wide settings
+cloud:
+  domain: "example.com"
+  email: "admin@example.com"
+  timezone: "America/New_York"
+
+# Cluster infrastructure settings
+cluster:
+  name: "wild-cluster"
+  nodeCount: 3
+  network:
+    subnet: "192.168.1.0/24"
+    gateway: "192.168.1.1"
+    dnsServer: "192.168.1.50"
+    metallbPool: "192.168.1.80-89"
+    controlPlaneVip: "192.168.1.90"
+  nodes:
+    control-1:
+      ip: "192.168.1.91"
+      mac: "00:11:22:33:44:55"
+      interface: "eth0"
+      disk: "/dev/sda"
+    control-2:
+      ip: "192.168.1.92"
+      mac: "00:11:22:33:44:56"
+      interface: "eth0"
+      disk: "/dev/sda"
+
+# Application-specific settings
+apps:
+  ghost:
+    domain: "blog.example.com"
+    image: "ghost:5.0.0"
+    storage: "10Gi"
+    timezone: "UTC"
+    namespace: "ghost"
+  immich:
+    domain: "photos.example.com"
+    serverImage: "ghcr.io/immich-app/immich-server:release"
+    storage: "250Gi"
+    namespace: "immich"
+
+# Service configurations
+services:
+  traefik:
+    replicas: 2
+    dashboard: true
+  longhorn:
+    defaultReplicas: 3
+    storageClass: "longhorn"
+```
+
+### Configuration Commands
+
+**Reading Configuration Values**:
+```bash
+# Read simple values
+wild-config cloud.domain                    # "example.com"
+wild-config cluster.name                    # "wild-cluster"
+
+# Read nested values
+wild-config apps.ghost.domain              # "blog.example.com"
+wild-config cluster.nodes.control-1.ip     # "192.168.1.91"
+
+# Check if key exists
+wild-config --check apps.newapp.domain     # Returns exit code 0/1
+```
+
+**Writing Configuration Values**:
+```bash
+# Set simple values
+wild-config-set cloud.domain "newdomain.com"
+wild-config-set cluster.nodeCount 5
+
+# Set nested values
+wild-config-set apps.ghost.storage "20Gi"
+wild-config-set cluster.nodes.worker-1.ip "192.168.1.94"
+
+# Set complex values (JSON format)
+wild-config-set apps.ghost '{"domain":"blog.com","storage":"50Gi"}'
+```
+
+### Configuration Sections
+
+#### Cloud Settings (`cloud.*`)
+Global settings that affect the entire Wild Cloud deployment:
+
+```yaml
+cloud:
+  domain: "example.com"           # Primary domain for services
+  email: "admin@example.com"      # Contact email for certificates
+  timezone: "America/New_York"    # Default timezone for services
+  backupLocation: "s3://backup"   # Backup storage location
+  monitoring: true                # Enable monitoring services
+```
+
+#### Cluster Settings (`cluster.*`)
+Infrastructure and node configuration:
+
+```yaml
+cluster:
+  name: "production-cluster"
+  version: "v1.28.0"
+  network:
+    subnet: "10.0.0.0/16"         # Cluster network range
+    serviceCIDR: "10.96.0.0/12"   # Service network range
+    podCIDR: "10.244.0.0/16"      # Pod network range
+  nodes:
+    control-1:
+      ip: "10.0.0.10"
+      role: "controlplane"
+      taints: []
+    worker-1:
+      ip: "10.0.0.20"
+      role: "worker"
+      labels:
+        node-type: "compute"
+```
+
+#### Application Settings (`apps.*`)
+Per-application configuration that overrides defaults from app manifests:
+
+```yaml
+apps:
+  postgresql:
+    storage: "100Gi"
+    maxConnections: 200
+    sharedBuffers: "256MB"
+  redis:
+    memory: "1Gi"
+    persistence: true
+  ghost:
+    domain: "blog.example.com"
+    theme: "casper"
+    storage: "10Gi"
+    replicas: 2
+```
+
+## Secrets Management (`secrets.yaml`)
+
+### Security Model
+
+The `secrets.yaml` file stores all sensitive data with the following security measures:
+
+- **File Permissions**: Automatically set to 600 (owner read/write only)
+- **Git Exclusion**: Included in `.gitignore` by default
+- **Encryption Support**: Can be encrypted at rest using tools like `age` or `gpg`
+- **Access Control**: Only Wild Cloud commands can read/write secrets
+
+### Secret Structure
+
+```yaml
+# Generated cluster secrets
+cluster:
+  talos:
+    secrets: "base64-encoded-cluster-secrets"
+    adminKey: "talos-admin-private-key"
+  kubernetes:
+    adminToken: "k8s-admin-service-account-token"
+
+# Application secrets
+apps:
+  postgresql:
+    rootPassword: "randomly-generated-32-char-string"
+    replicationPassword: "randomly-generated-32-char-string"
+  ghost:
+    dbPassword: "randomly-generated-password"
+    adminPassword: "user-set-password"
+    jwtSecret: "randomly-generated-jwt-secret"
+  immich:
+    dbPassword: "randomly-generated-password"
+    dbUrl: "postgresql://immich:password@postgres:5432/immich"
+    jwtSecret: "jwt-signing-key"
+
+# External service credentials
+external:
+  cloudflare:
+    apiToken: "cloudflare-dns-api-token"
+  letsencrypt:
+    email: "admin@example.com"
+  backup:
+    s3AccessKey: "backup-s3-access-key"
+    s3SecretKey: "backup-s3-secret-key"
+```
+
+### Secret Commands
+
+**Reading Secrets**:
+```bash
+# Read secret values
+wild-secret apps.postgresql.rootPassword
+wild-secret cluster.kubernetes.adminToken
+
+# Check if secret exists
+wild-secret --check apps.newapp.apiKey
+```
+
+**Writing Secrets**:
+```bash
+# Set specific secret value
+wild-secret-set apps.ghost.adminPassword "my-secure-password"
+
+# Generate random secret (if no value provided)
+wild-secret-set apps.newapp.apiKey        # Generates 32-char base64 string
+
+# Set complex secret (JSON format)
+wild-secret-set apps.database '{"user":"admin","password":"secret"}'
+```
+
+### Automatic Secret Generation
+
+When you run `wild-app-add`, Wild Cloud automatically generates required secrets:
+
+1. **Reads App Manifest**: Identifies `requiredSecrets` 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
+
+**Example App Manifest**:
+```yaml
+name: ghost
+requiredSecrets:
+  - apps.ghost.dbPassword      # Auto-generated if missing
+  - apps.ghost.jwtSecret       # Auto-generated if missing
+  - apps.postgresql.password   # Auto-generated if missing (dependency)
+```
+
+**Resulting secrets.yaml**:
+```yaml
+apps:
+  ghost:
+    dbPassword: "aB3kL9mN2pQ7rS8tU1vW4xY5zA6bC0dE"
+    jwtSecret: "jF2gH5iJ8kL1mN4oP7qR0sT3uV6wX9yZ"
+  postgresql:
+    password: "eE8fF1gG4hH7iI0jJ3kK6lL9mM2nN5oO"
+```
+
+## Template System
+
+### gomplate Integration
+
+Wild Cloud uses [gomplate](https://gomplate.ca/) for dynamic configuration processing, allowing templates to access both configuration and secrets:
+
+```yaml
+# Template example (before processing)
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: ghost-config
+  namespace: {{ .apps.ghost.namespace }}
+data:
+  url: "https://{{ .apps.ghost.domain }}"
+  timezone: "{{ .apps.ghost.timezone | default .cloud.timezone }}"
+  database_host: "{{ .apps.postgresql.hostname }}"
+  # Conditionals
+  {{- if .apps.ghost.enableSSL }}
+  ssl_enabled: "true"
+  {{- end }}
+  # Loops
+  allowed_domains: |
+    {{- range .apps.ghost.allowedDomains }}
+    - {{ . }}
+    {{- end }}
+```
+
+### Template Processing Commands
+
+**Process Single Template**:
+```bash
+# From stdin
+cat template.yaml | wild-compile-template > output.yaml
+
+# With custom context
+echo "domain: {{ .cloud.domain }}" | wild-compile-template
+```
+
+**Process Template Directory**:
+```bash
+# Recursively process all templates
+wild-compile-template-dir source-dir output-dir
+
+# Clean destination first
+wild-compile-template-dir --clean source-dir output-dir
+```
+
+### Template Context
+
+Templates have access to the complete configuration and secrets context:
+
+```go
+// Available template variables
+.cloud.*          // All cloud configuration
+.cluster.*        // All cluster configuration
+.apps.*           // All application configuration
+.services.*       // All service configuration
+
+// Special functions
+.cloud.domain             // Primary domain
+default "fallback"        // Default value if key missing
+env "VAR_NAME"           // Environment variable
+file "path/to/file"      // File contents
+```
+
+**Template Examples**:
+```yaml
+# Basic variable substitution
+domain: {{ .apps.myapp.domain }}
+
+# Default values
+timezone: {{ .apps.myapp.timezone | default .cloud.timezone }}
+
+# Conditionals
+{{- if .apps.myapp.enableFeature }}
+feature_enabled: true
+{{- else }}
+feature_enabled: false
+{{- end }}
+
+# Lists and iteration
+allowed_hosts:
+{{- range .apps.myapp.allowedHosts }}
+  - {{ . }}
+{{- end }}
+
+# Complex expressions
+replicas: {{ if eq .cluster.environment "production" }}3{{ else }}1{{ end }}
+```
+
+## Environment Setup
+
+### Environment Detection
+
+Wild Cloud automatically detects and configures the environment through several mechanisms:
+
+**Project Detection**:
+- Searches for `.wildcloud` directory in current or parent directories
+- Sets `WC_HOME` to the directory containing `.wildcloud`
+- Fails if no Wild Cloud project found
+
+**Repository Detection**:
+- Locates Wild Cloud repository (source code)
+- Sets `WC_ROOT` to repository location
+- Used for accessing app templates and setup scripts
+
+### Environment Variables
+
+**Key Environment Variables**:
+```bash
+WC_HOME="/path/to/your-cloud"           # Your cloud directory
+WC_ROOT="/path/to/wild-cloud-repo"      # Wild Cloud repository
+PATH="$WC_ROOT/bin:$PATH"               # Wild Cloud commands available
+KUBECONFIG="$WC_HOME/.kube/config"      # Kubernetes configuration
+TALOSCONFIG="$WC_HOME/.talos/config"    # Talos configuration
+```
+
+**Environment Setup Script** (`env.sh`):
+```bash
+#!/bin/bash
+# Auto-generated environment setup
+
+export WC_HOME="/home/user/my-cloud"
+export WC_ROOT="/opt/wild-cloud"
+export PATH="$WC_ROOT/bin:$PATH"
+export KUBECONFIG="$WC_HOME/.kubeconfig"
+export TALOSCONFIG="$WC_HOME/setup/cluster-nodes/generated/talosconfig"
+
+# Source this file to set up Wild Cloud environment
+# source env.sh
+```
+
+### Common Script Pattern
+
+Most Wild Cloud scripts follow this initialization pattern:
+
+```bash
+#!/bin/bash
+set -e
+set -o pipefail
+
+# Initialize Wild Cloud environment
+if [ -z "${WC_ROOT}" ]; then
+    print "WC_ROOT is not set."
+    exit 1
+else
+    source "${WC_ROOT}/scripts/common.sh"
+    init_wild_env
+fi
+
+# Script logic here...
+```
+
+## Configuration Validation
+
+### Schema Validation
+
+Wild Cloud validates configuration against expected schemas:
+
+**Cluster Configuration Validation**:
+- Node IP addresses are valid and unique
+- Network ranges don't overlap
+- Required fields are present
+- Hardware specifications meet minimums
+
+**Application Configuration Validation**:
+- Domain names are valid DNS names
+- Storage sizes use valid Kubernetes formats
+- Image references are valid container images
+- Dependencies are satisfied
+
+### Validation Commands
+
+```bash
+# Validate current configuration
+wild-config --validate
+
+# Check specific configuration sections
+wild-config --validate --section cluster
+wild-config --validate --section apps.ghost
+
+# Test template compilation
+wild-compile-template --validate < template.yaml
+```
+
+## Configuration Best Practices
+
+### Organization
+
+**Hierarchical Structure**:
+- Group related settings under common prefixes
+- Use consistent naming conventions
+- Keep application configs under `apps.*`
+- Separate infrastructure from application settings
+
+**Documentation**:
+```yaml
+# Document complex configurations
+cluster:
+  # Node configuration - update IPs after hardware changes
+  nodes:
+    control-1:
+      ip: "192.168.1.91"    # Main control plane node
+      interface: "eth0"      # Primary network interface
+```
+
+### Security
+
+**Configuration Security**:
+- Never store secrets in `config.yaml`
+- Use `wild-secret-set` for all sensitive data
+- Regularly rotate generated secrets
+- Backup `secrets.yaml` securely
+
+**Access Control**:
+```bash
+# Ensure proper permissions
+chmod 600 secrets.yaml
+chmod 644 config.yaml
+
+# Restrict directory access
+chmod 755 your-cloud-directory
+chmod 700 .wildcloud/
+```
+
+### Version Control
+
+**Git Integration**:
+```gitignore
+# .gitignore for Wild Cloud projects
+secrets.yaml          # Never commit secrets
+.wildcloud/cache/      # Temporary files
+.wildcloud/logs/       # Operation logs
+setup/cluster-nodes/generated/  # Generated cluster configs
+.kube/                 # Kubernetes configs
+.talos/                # Talos configs
+```
+
+**Configuration Changes**:
+- Commit `config.yaml` changes with descriptive messages
+- Tag major configuration changes
+- Use branches for experimental configurations
+- Document configuration changes in commit messages
+
+### Backup and Recovery
+
+**Configuration Backup**:
+```bash
+# Backup configuration and secrets
+wild-backup --home-only
+
+# Export configuration for disaster recovery
+cp config.yaml config-backup-$(date +%Y%m%d).yaml
+cp secrets.yaml secrets-backup-$(date +%Y%m%d).yaml.gpg  # Encrypt first
+```
+
+**Recovery Process**:
+1. Restore `config.yaml` from backup
+2. Decrypt and restore `secrets.yaml`
+3. Re-run `wild-setup` if needed
+4. Validate configuration with `wild-config --validate`
+
+## Advanced Configuration
+
+### Multi-Environment Setup
+
+**Development Environment**:
+```yaml
+cloud:
+  domain: "dev.example.com"
+cluster:
+  name: "dev-cluster"
+  nodeCount: 1
+apps:
+  ghost:
+    domain: "blog.dev.example.com"
+    replicas: 1
+```
+
+**Production Environment**:
+```yaml
+cloud:
+  domain: "example.com"
+cluster:
+  name: "prod-cluster"
+  nodeCount: 5
+apps:
+  ghost:
+    domain: "blog.example.com"
+    replicas: 3
+```
+
+### Configuration Inheritance
+
+**Base Configuration**:
+```yaml
+# config.base.yaml
+cloud:
+  timezone: "UTC"
+  email: "admin@example.com"
+apps:
+  postgresql:
+    storage: "10Gi"
+```
+
+**Environment-Specific Override**:
+```yaml
+# config.prod.yaml (merged with base)
+apps:
+  postgresql:
+    storage: "100Gi"    # Override for production
+    replicas: 3         # Additional production setting
+```
+
+### Dynamic Configuration
+
+**Runtime Configuration Updates**:
+```bash
+# Update configuration without restart
+wild-config-set apps.ghost.replicas 3
+wild-app-deploy ghost  # Apply changes
+
+# Rolling updates
+wild-config-set apps.ghost.image "ghost:5.1.0"
+wild-app-deploy ghost --rolling-update
+```
+
+The Wild Cloud configuration system provides a powerful, secure, and flexible foundation for managing complex infrastructure deployments while maintaining simplicity for common use cases.
--- a/docs/agent-context/wildcloud/overview.md
+++ b/docs/agent-context/wildcloud/overview.md
@@ -0,0 +1,450 @@
+# Wild Cloud Overview
+
+Wild Cloud is a complete, production-ready Kubernetes infrastructure designed for personal use. It combines enterprise-grade technologies to create a self-hosted cloud platform with automated deployment, HTTPS certificates, and web management interfaces.
+
+## What is Wild Cloud?
+
+### Vision
+In a world where digital lives are increasingly controlled by large corporations, Wild Cloud puts you back in control by providing:
+
+- **Privacy**: Your data stays on your hardware, under your control
+- **Ownership**: No subscription fees or sudden price increases
+- **Freedom**: Run the apps you want, the way you want them
+- **Learning**: Gain valuable skills in modern cloud technologies
+- **Resilience**: Reduce reliance on third-party services that can disappear
+
+### Core Capabilities
+
+**Complete Infrastructure Stack**:
+- Kubernetes cluster with Talos Linux
+- Automatic HTTPS certificates via Let's Encrypt
+- Load balancing with MetalLB
+- Ingress routing with Traefik
+- Distributed storage with Longhorn
+- DNS management with CoreDNS and ExternalDNS
+
+**Application Platform**:
+- One-command application deployment
+- Pre-built apps for common self-hosted services
+- Automatic database setup and configuration
+- Integrated backup and restore system
+- Web-based management interfaces
+
+**Enterprise Features**:
+- High availability and fault tolerance
+- Automated certificate management
+- Network policies and security contexts
+- Monitoring and observability
+- Infrastructure as code principles
+
+## Technology Stack
+
+### Core Infrastructure
+- **Talos Linux** - Immutable OS designed for Kubernetes
+- **Kubernetes** - Container orchestration platform
+- **MetalLB** - Load balancer for bare metal deployments
+- **Traefik** - HTTP reverse proxy and ingress controller
+- **Longhorn** - Distributed block storage system
+- **cert-manager** - Automatic TLS certificate management
+
+### Supporting Services
+- **CoreDNS** - DNS server for service discovery
+- **ExternalDNS** - Automatic DNS record management
+- **Kubernetes Dashboard** - Web UI for cluster management
+- **restic** - Backup solution with deduplication
+- **gomplate** - Template processor for configurations
+
+### Development Tools
+- **Kustomize** - Kubernetes configuration management
+- **kubectl** - Kubernetes command line interface
+- **talosctl** - Talos Linux management tool
+- **Bats** - Testing framework for bash scripts
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          Internet                               │
+└─────────────────┬───────────────────────────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────────────────────────┐
+│                      DNS Provider                               │
+│              (Cloudflare, Route53, etc.)                        │
+└─────────────────┬───────────────────────────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────────────────────────┐
+│                    Your Network                                 │
+│  ┌─────────────┐  ┌─────────────────────────────────────────┐   │
+│  │   dnsmasq   │  │          Kubernetes Cluster             │   │
+│  │   Server    │  │  ┌─────────────┐ ┌─────────────────┐    │   │
+│  │             │  │  │  MetalLB    │ │    Traefik      │    │   │
+│  │ DNS + DHCP  │  │  │ LoadBalancer│ │   Ingress       │    │   │
+│  └─────────────┘  │  └─────────────┘ └─────────────────┘    │   │
+│                   │  ┌───────────────────────────────────┐  │   │
+│                   │  │           Applications            │  │   │
+│                   │  │   Ghost, Immich, Gitea, vLLM...   │  │   │
+│                   │  └───────────────────────────────────┘  │   │
+│                   └─────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Traffic Flow
+1. **External Request** → DNS resolution via provider
+2. **DNS Response** → Points to your cluster's external IP
+3. **Network Request** → Hits MetalLB load balancer
+4. **Load Balancer** → Routes to Traefik ingress controller
+5. **Ingress Controller** → Terminates TLS and routes to application
+6. **Application** → Serves content from Kubernetes pod
+
+## Getting Started
+
+### Prerequisites
+
+**Hardware Requirements**:
+- Minimum 3 nodes for high availability
+- 8GB RAM per node (16GB+ recommended)
+- 100GB+ storage per node
+- Gigabit network connectivity
+- x86_64 architecture
+
+**Network Requirements**:
+- All nodes on same network segment
+- One dedicated machine for dnsmasq (can be lightweight)
+- Static IP assignments or DHCP reservations
+- Internet connectivity for downloads and certificates
+
+### Quick Start Guide
+
+#### 1. Install Dependencies
+```bash
+# Clone Wild Cloud repository
+git clone https://github.com/your-org/wild-cloud
+cd wild-cloud
+
+# Install required tools
+scripts/setup-utils.sh
+```
+
+#### 2. Initialize Your Cloud
+```bash
+# Create and initialize new cloud directory
+mkdir my-cloud && cd my-cloud
+wild-init
+
+# Follow interactive setup prompts for:
+# - Domain name configuration
+# - Email for certificates
+# - Network settings
+```
+
+#### 3. Deploy Infrastructure
+```bash
+# Complete automated setup
+wild-setup
+
+# Or step-by-step:
+wild-setup-cluster     # Deploy Kubernetes cluster
+wild-setup-services    # Install core services
+```
+
+#### 4. Deploy Your First App
+```bash
+# List available applications
+wild-apps-list
+
+# Deploy a blog
+wild-app-fetch ghost
+wild-app-add ghost
+wild-app-deploy ghost
+
+# Access at https://ghost.yourdomain.com
+```
+
+#### 5. Verify Deployment
+```bash
+# Check system health
+wild-health
+
+# Access Kubernetes dashboard
+wild-dashboard-token
+# Visit https://dashboard.internal.yourdomain.com
+```
+
+## Key Concepts
+
+### Configuration Management
+
+Wild Cloud uses a dual-file configuration system:
+
+**`config.yaml`** - Non-sensitive settings:
+```yaml
+cloud:
+  domain: "example.com"
+  email: "admin@example.com"
+apps:
+  ghost:
+    domain: "blog.example.com"
+    storage: "10Gi"
+```
+
+**`secrets.yaml`** - Sensitive data (auto-generated):
+```yaml
+apps:
+  ghost:
+    dbPassword: "secure-random-password"
+  postgresql:
+    rootPassword: "another-secure-password"
+```
+
+### Template System
+
+All configurations are templates processed with gomplate:
+
+**Before Processing** (in repository):
+```yaml
+domain: {{ .apps.ghost.domain }}
+storage: {{ .apps.ghost.storage | default "5Gi" }}
+```
+
+**After Processing** (in your cloud):
+```yaml
+domain: blog.example.com
+storage: 10Gi
+```
+
+### Application Lifecycle
+
+1. **Discovery**: `wild-apps-list` - Browse available apps
+2. **Fetching**: `wild-app-fetch app-name` - Download templates
+3. **Configuration**: `wild-app-add app-name` - Process and configure
+4. **Deployment**: `wild-app-deploy app-name` - Deploy to cluster
+5. **Operations**: `wild-app-doctor app-name` - Monitor and troubleshoot
+
+## Available Applications
+
+### Content Management & Publishing
+- **Ghost** - Modern publishing platform for blogs and websites
+- **Discourse** - Community discussion platform with modern features
+
+### Media & File Management
+- **Immich** - Self-hosted photo and video backup solution
+
+### Development Tools
+- **Gitea** - Self-hosted Git service with web interface
+- **Docker Registry** - Private container image registry
+
+### Communication & Marketing
+- **Keila** - Newsletter and email marketing platform
+- **Listmonk** - High-performance newsletter and mailing list manager
+
+### Databases & Caching
+- **PostgreSQL** - Advanced open-source relational database
+- **MySQL** - Popular relational database management system
+- **Redis** - In-memory data structure store and cache
+- **Memcached** - Distributed memory caching system
+
+### AI & Machine Learning
+- **vLLM** - High-performance LLM inference server with OpenAI-compatible API
+
+## Core Commands Reference
+
+### Setup & Initialization
+```bash
+wild-init                    # Initialize new cloud directory
+wild-setup                   # Complete infrastructure deployment
+wild-setup-cluster          # Deploy Kubernetes cluster only
+wild-setup-services         # Deploy cluster services only
+```
+
+### Application Management
+```bash
+wild-apps-list              # List available applications
+wild-app-fetch <app>        # Download app templates
+wild-app-add <app>          # Configure application
+wild-app-deploy <app>       # Deploy to cluster
+wild-app-delete <app>       # Remove application
+wild-app-doctor <app>       # Run diagnostics
+```
+
+### Configuration Management
+```bash
+wild-config <key>           # Read configuration value
+wild-config-set <key> <val> # Set configuration value
+wild-secret <key>           # Read secret value
+wild-secret-set <key> <val> # Set secret value
+```
+
+### Operations & Monitoring
+```bash
+wild-health                 # System health check
+wild-dashboard-token        # Get dashboard access token
+wild-backup                 # Backup system and apps
+wild-app-backup <app>       # Backup specific application
+```
+
+## Best Practices
+
+### Security
+- Never commit `secrets.yaml` to version control
+- Use strong, unique passwords for all services
+- Regularly update system and application images
+- Monitor certificate expiration and renewal
+- Implement network policies for production workloads
+
+### Configuration Management
+- Store `config.yaml` in version control with proper .gitignore
+- Document configuration changes in commit messages
+- Use branches for experimental configurations
+- Backup configuration files before major changes
+- Test configuration changes in development environment
+
+### Operations
+- Monitor cluster health with `wild-health`
+- Set up regular backup schedules with `wild-backup`
+- Keep applications updated with latest security patches
+- Monitor disk usage and expand storage as needed
+- Document custom configurations and procedures
+
+### Development
+- Follow Wild Cloud app structure conventions
+- Use proper Kubernetes security contexts
+- Include comprehensive health checks and probes
+- Test applications thoroughly before deployment
+- Document application-specific configuration requirements
+
+## Common Use Cases
+
+### Personal Blog/Website
+```bash
+# Deploy Ghost blog with custom domain
+wild-app-fetch ghost
+wild-config-set apps.ghost.domain "blog.yourdomain.com"
+wild-app-add ghost
+wild-app-deploy ghost
+```
+
+### Photo Management
+```bash
+# Deploy Immich for photo backup and management
+wild-app-fetch immich postgresql
+wild-app-add postgresql immich
+wild-app-deploy postgresql immich
+```
+
+### Development Environment
+```bash
+# Set up Git hosting and container registry
+wild-app-fetch gitea docker-registry
+wild-app-add gitea docker-registry
+wild-app-deploy gitea docker-registry
+```
+
+### AI/ML Workloads
+```bash
+# Deploy vLLM for local AI inference
+wild-app-fetch vllm
+wild-config-set apps.vllm.model "Qwen/Qwen2.5-7B-Instruct"
+wild-app-add vllm
+wild-app-deploy vllm
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Cluster Not Responding**:
+```bash
+# Check node status
+kubectl get nodes
+talosctl health
+
+# Verify network connectivity
+ping <node-ip>
+```
+
+**Applications Not Starting**:
+```bash
+# Check pod status
+kubectl get pods -n <app-namespace>
+
+# View logs
+kubectl logs deployment/<app-name> -n <app-namespace>
+
+# Run diagnostics
+wild-app-doctor <app-name>
+```
+
+**Certificate Issues**:
+```bash
+# Check certificate status
+kubectl get certificates -A
+
+# View cert-manager logs
+kubectl logs -n cert-manager deployment/cert-manager
+```
+
+**DNS Problems**:
+```bash
+# Test DNS resolution
+nslookup <app-domain>
+
+# Check external-dns logs
+kubectl logs -n external-dns deployment/external-dns
+```
+
+### Getting Help
+
+**Documentation**:
+- Check `docs/` directory for detailed guides
+- Review application-specific README files
+- Consult Kubernetes and Talos documentation
+
+**Community Support**:
+- Report issues on GitHub repository
+- Join community forums and discussions
+- Share configurations and troubleshooting tips
+
+**Professional Support**:
+- Consider professional services for production deployments
+- Engage with cloud infrastructure consultants
+- Participate in training and certification programs
+
+## Advanced Topics
+
+### Custom Applications
+
+Create your own Wild Cloud applications:
+
+1. **Create App Directory**: `apps/myapp/`
+2. **Define Manifest**: Include metadata and configuration defaults
+3. **Create Templates**: Kubernetes resources with gomplate variables
+4. **Test Deployment**: Use standard Wild Cloud workflow
+5. **Share**: Contribute back to the community
+
+### Multi-Environment Deployments
+
+Manage multiple Wild Cloud instances:
+
+- **Development**: Single-node cluster for testing
+- **Staging**: Multi-node cluster mirroring production
+- **Production**: Full HA cluster with monitoring and backups
+
+### Integration with External Services
+
+Extend Wild Cloud capabilities:
+
+- **External DNS Providers**: Cloudflare, Route53, Google DNS
+- **Backup Storage**: S3, Google Cloud Storage, Azure Blob
+- **Monitoring**: Prometheus, Grafana, AlertManager
+- **CI/CD**: GitLab CI, GitHub Actions, Jenkins
+
+### Performance Optimization
+
+Optimize for your workloads:
+
+- **Resource Allocation**: CPU and memory limits/requests
+- **Storage Performance**: NVMe SSDs, storage classes
+- **Network Optimization**: Network policies, service mesh
+- **Scaling**: Horizontal pod autoscaling, cluster autoscaling
+
+Wild Cloud provides a solid foundation for personal cloud infrastructure while maintaining the flexibility to grow and adapt to changing needs. Whether you're running a simple blog or a complex multi-service application, Wild Cloud's enterprise-grade technologies ensure your infrastructure is reliable, secure, and maintainable.
--- a/docs/agent-context/wildcloud/project-architecture.md
+++ b/docs/agent-context/wildcloud/project-architecture.md
@@ -0,0 +1,489 @@
+# Wild Cloud Project Architecture
+
+Wild Cloud consists of two main directory structures: the **Wild Cloud Repository** (source code and templates) and **User Cloud Directories** (individual deployments). Understanding this architecture is essential for working with Wild Cloud effectively.
+
+## Architecture Overview
+
+```
+Wild Cloud Repository (/path/to/wild-cloud-repo)  ←  Source code, templates, scripts
+                    ↓
+User Cloud Directory (/path/to/my-cloud)          ←  Individual deployment instance
+                    ↓
+Kubernetes Cluster                                ←  Running infrastructure
+```
+
+## Wild Cloud Repository Structure
+
+The Wild Cloud repository (`WC_ROOT`) contains the source code, templates, and tools:
+
+### `/bin/` - Command Line Interface
+**Purpose**: All Wild Cloud CLI commands and utilities
+```
+bin/
+├── wild-*                    # All user-facing commands (34+ scripts)
+├── wild-common.sh            # Common utilities and functions
+├── README.md                 # CLI documentation
+└── helm-chart-to-kustomize   # Utility for converting Helm charts
+```
+
+**Key Commands**:
+- **Setup**: `wild-init`, `wild-setup`, `wild-setup-cluster`, `wild-setup-services`
+- **Apps**: `wild-app-*`, `wild-apps-list`
+- **Config**: `wild-config*`, `wild-secret*`
+- **Operations**: `wild-backup`, `wild-health`, `wild-dashboard-token`
+
+### `/apps/` - Application Templates
+**Purpose**: Pre-built applications ready for deployment
+```
+apps/
+├── README.md                 # Apps system documentation
+├── ghost/                    # Blog publishing platform
+│   ├── manifest.yaml         # App metadata and defaults
+│   ├── kustomization.yaml    # Kustomize configuration
+│   ├── deployment.yaml       # Kubernetes deployment
+│   ├── service.yaml          # Service definition
+│   ├── ingress.yaml          # HTTPS ingress
+│   └── ...
+├── immich/                   # Photo management
+├── gitea/                    # Git hosting
+├── postgresql/               # Database service
+├── vllm/                     # AI/LLM inference
+└── ...
+```
+
+**Application Categories**:
+- **Content Management**: Ghost, Discourse
+- **Media**: Immich
+- **Development**: Gitea, Docker Registry
+- **Databases**: PostgreSQL, MySQL, Redis
+- **AI/ML**: vLLM
+- **Infrastructure**: Memcached, NFS
+
+### `/setup/` - Infrastructure Templates
+**Purpose**: Cluster and service deployment templates
+```
+setup/
+├── README.md
+├── cluster-nodes/            # Talos node configuration
+│   ├── init-cluster.sh       # Cluster initialization script
+│   ├── patch.templates/      # Node-specific config templates
+│   │   ├── controlplane.yaml # Control plane template
+│   │   └── worker.yaml       # Worker node template
+│   └── talos-schemas.yaml    # Version mappings
+├── cluster-services/         # Core Kubernetes services
+│   ├── README.md
+│   ├── metallb/              # Load balancer
+│   ├── traefik/              # Ingress controller
+│   ├── cert-manager/         # Certificate management
+│   ├── longhorn/             # Distributed storage
+│   ├── coredns/              # DNS resolution
+│   ├── externaldns/          # DNS record management
+│   ├── kubernetes-dashboard/ # Web UI
+│   └── ...
+├── dnsmasq/                  # DNS and PXE boot server
+├── home-scaffold/            # User directory templates
+└── operator/                 # Additional operator tools
+```
+
+### `/experimental/` - Development Projects
+**Purpose**: Experimental features and development tools
+```
+experimental/
+├── daemon/                   # Go API daemon
+│   ├── main.go               # API server
+│   ├── Makefile              # Build automation
+│   └── README.md
+└── app/                      # React dashboard
+    ├── src/                  # React source code
+    ├── package.json          # Dependencies
+    ├── pnpm-lock.yaml        # Lock file
+    └── README.md
+```
+
+### `/scripts/` - Utility Scripts
+**Purpose**: Installation and utility scripts
+```
+scripts/
+├── setup-utils.sh            # Install dependencies
+└── install-wild-cloud-dependencies.sh
+```
+
+### `/docs/` - Documentation
+**Purpose**: User guides and documentation
+```
+docs/
+├── guides/                   # Setup and usage guides
+├── agent-context/           # Agent documentation
+│   └── wildcloud/           # Context files for AI agents
+└── *.md                     # Various documentation files
+```
+
+### `/test/` - Test Suite
+**Purpose**: Automated testing with Bats
+```
+test/
+├── bats/                     # Bats testing framework
+├── fixtures/                 # Test data and configurations
+├── run_bats_tests.sh         # Test runner
+└── *.bats                    # Individual test files
+```
+
+### Root Files
+```
+/
+├── README.md                 # Project overview
+├── CLAUDE.md                 # AI assistant context
+├── LICENSE                   # GNU AGPLv3
+├── CONTRIBUTING.md           # Contribution guidelines
+├── env.sh                    # Environment setup
+├── .gitignore               # Git exclusions
+└── .gitmodules              # Git submodules
+```
+
+## User Cloud Directory Structure
+
+Each user deployment (`WC_HOME`) is an independent cloud instance:
+
+### Directory Layout
+```
+my-cloud/                     # User's cloud directory
+├── .wildcloud/               # Project marker and cache
+│   ├── cache/                # Downloaded templates
+│   │   ├── apps/             # Cached app templates
+│   │   └── services/         # Cached service templates
+│   └── logs/                 # Operation logs
+├── config.yaml               # Main configuration
+├── secrets.yaml              # Sensitive data (600 permissions)
+├── env.sh                    # Environment setup (auto-generated)
+├── apps/                     # Deployed application configs
+│   ├── ghost/                # Compiled ghost configuration
+│   ├── postgresql/           # Database configuration
+│   └── ...
+├── setup/                    # Infrastructure configurations
+│   ├── cluster-nodes/        # Node-specific configurations
+│   │   └── generated/        # Generated Talos configs
+│   └── cluster-services/     # Compiled service configurations
+├── docs/                     # Project-specific documentation
+├── .kube/                    # Kubernetes configuration
+│   └── config                # kubectl configuration
+├── .talos/                   # Talos configuration
+│   └── config                # talosctl configuration
+└── backups/                  # Local backup staging
+```
+
+### Configuration Files
+
+**`config.yaml`** - Main configuration (version controlled):
+```yaml
+cloud:
+  domain: "example.com"
+  email: "admin@example.com"
+cluster:
+  name: "my-cluster"
+  nodeCount: 3
+apps:
+  ghost:
+    domain: "blog.example.com"
+```
+
+**`secrets.yaml`** - Sensitive data (not version controlled):
+```yaml
+apps:
+  ghost:
+    dbPassword: "generated-password"
+  postgresql:
+    rootPassword: "generated-password"
+cluster:
+  talos:
+    secrets: "base64-encoded-secrets"
+```
+
+**`.wildcloud/`** - Project metadata:
+- Marks directory as Wild Cloud project
+- Contains cached templates and temporary files
+- Used for project detection by scripts
+
+### Generated Directories
+
+**`apps/`** - Compiled application configurations:
+- Created by `wild-app-add` command
+- Contains ready-to-deploy Kubernetes manifests
+- Templates processed with user configuration
+- Each app in separate subdirectory
+
+**`setup/cluster-nodes/generated/`** - Talos configurations:
+- Base cluster configuration (`controlplane.yaml`, `worker.yaml`)
+- Node-specific patches and final configs
+- Cluster secrets and certificates
+- Generated by `wild-cluster-config-generate`
+
+**`setup/cluster-services/`** - Kubernetes services:
+- Compiled service configurations
+- Generated by `wild-cluster-services-configure`
+- Ready for deployment to cluster
+
+## Template Processing Flow
+
+### From Repository to Deployment
+
+1. **Template Storage**: Templates stored in repository with placeholder variables
+2. **Template Fetching**: `wild-app-fetch` copies templates to user cache
+3. **Configuration Merge**: `wild-app-add` merges app defaults with user config
+4. **Template Compilation**: gomplate processes templates with user data
+5. **Manifest Generation**: Final Kubernetes manifests created in user directory
+6. **Deployment**: `wild-app-deploy` applies manifests to cluster
+
+### Template Variables
+
+**Repository Templates** (before processing):
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ghost
+  namespace: {{ .apps.ghost.namespace }}
+spec:
+  replicas: {{ .apps.ghost.replicas | default 1 }}
+  template:
+    spec:
+      containers:
+      - name: ghost
+        image: "{{ .apps.ghost.image }}"
+        env:
+        - name: url
+          value: "https://{{ .apps.ghost.domain }}"
+```
+
+**User Directory** (after processing):
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ghost
+  namespace: ghost
+spec:
+  replicas: 2
+  template:
+    spec:
+      containers:
+      - name: ghost
+        image: "ghost:5.0.0"
+        env:
+        - name: url
+          value: "https://blog.example.com"
+```
+
+## File Permissions and Security
+
+### Security Model
+
+**Configuration Security**:
+```bash
+config.yaml         # 644 (readable by group)
+secrets.yaml        # 600 (owner only)
+.wildcloud/         # 755 (standard directory)
+apps/               # 755 (standard directory)
+```
+
+**Git Integration**:
+```gitignore
+# Automatically excluded from version control
+secrets.yaml                    # Never commit secrets
+.wildcloud/cache/              # Temporary files
+.wildcloud/logs/               # Operation logs
+setup/cluster-nodes/generated/ # Generated configs
+.kube/                         # Kubernetes configs
+.talos/                        # Talos configs
+backups/                       # Backup files
+```
+
+### Access Patterns
+
+**Read Operations**:
+- Scripts read config and secrets via `wild-config` and `wild-secret`
+- Template processor accesses both files for compilation
+- Kubernetes tools read generated manifests
+
+**Write Operations**:
+- Only Wild Cloud commands modify config and secrets
+- Manual editing supported but not recommended
+- Backup processes create read-only copies
+
+## Development Workflow
+
+### Repository Development
+
+**Setup Development Environment**:
+```bash
+git clone https://github.com/username/wild-cloud
+cd wild-cloud
+source env.sh                   # Set up environment
+scripts/setup-utils.sh          # Install dependencies
+```
+
+**Testing Changes**:
+```bash
+# Test specific functionality
+test/run_bats_tests.sh
+
+# Test with real cloud directory
+cd /path/to/test-cloud
+wild-app-add myapp              # Test app changes
+wild-setup-cluster --dry-run    # Test cluster changes
+```
+
+### User Workflow
+
+**Initial Setup**:
+```bash
+mkdir my-cloud && cd my-cloud
+wild-init                       # Initialize project
+wild-setup                      # Deploy infrastructure
+```
+
+**Daily Operations**:
+```bash
+wild-apps-list                  # Browse available apps
+wild-app-fetch ghost            # Download app templates
+wild-app-add ghost              # Configure app
+wild-app-deploy ghost           # Deploy to cluster
+```
+
+**Configuration Management**:
+```bash
+wild-config apps.ghost.domain   # Read configuration
+wild-config-set apps.ghost.storage "20Gi"  # Update configuration
+wild-app-deploy ghost           # Apply changes
+```
+
+## Integration Points
+
+### External Systems
+
+**DNS Providers**:
+- Cloudflare API for DNS record management
+- Route53 support for AWS domains
+- Generic webhook support for other providers
+
+**Certificate Authorities**:
+- Let's Encrypt (primary)
+- Custom CA support
+- Manual certificate import
+
+**Storage Backends**:
+- Local storage via Longhorn
+- NFS network storage
+- Cloud storage integration (S3, etc.)
+
+**Backup Systems**:
+- Restic for deduplication and encryption
+- S3-compatible storage backends
+- Local and remote backup targets
+
+### Kubernetes Integration
+
+**Custom Resources**:
+- Traefik IngressRoute and Middleware
+- cert-manager Certificate and Issuer
+- Longhorn Volume and Engine
+- ExternalDNS DNSEndpoint
+
+**Standard Resources**:
+- Deployments, Services, ConfigMaps
+- Ingress, PersistentVolumes, Secrets
+- NetworkPolicies, ServiceAccounts
+- Jobs, CronJobs, DaemonSets
+
+## Extensibility Points
+
+### Custom Applications
+
+**Create New Apps**:
+1. Create directory in `apps/`
+2. Define `manifest.yaml` with metadata
+3. Create Kubernetes resource templates
+4. Test with `wild-app-add` and `wild-app-deploy`
+
+**App Requirements**:
+- Follow Wild Cloud labeling standards
+- Use gomplate template syntax
+- Include external-dns annotations
+- Implement proper security contexts
+
+### Custom Services
+
+**Add Infrastructure Services**:
+1. Create directory in `setup/cluster-services/`
+2. Define installation and configuration scripts
+3. Create Kubernetes manifests with templates
+4. Integrate with service deployment pipeline
+
+### Script Extensions
+
+**Extend CLI**:
+- Add scripts to `bin/` directory with `wild-` prefix
+- Follow common script patterns (error handling, help text)
+- Source `wild-common.sh` for utilities
+- Use configuration system for customization
+
+## Deployment Patterns
+
+### Single-Node Development
+
+**Configuration**:
+```yaml
+cluster:
+  nodeCount: 1
+  nodes:
+    all-in-one:
+      roles: ["controlplane", "worker"]
+```
+
+**Suitable For**:
+- Development and testing
+- Learning Kubernetes concepts
+- Small personal deployments
+- Resource-constrained environments
+
+### Multi-Node Production
+
+**Configuration**:
+```yaml
+cluster:
+  nodeCount: 5
+  nodes:
+    control-1: { role: "controlplane" }
+    control-2: { role: "controlplane" }
+    control-3: { role: "controlplane" }
+    worker-1: { role: "worker" }
+    worker-2: { role: "worker" }
+```
+
+**Suitable For**:
+- Production workloads
+- High availability requirements
+- Scalable application hosting
+- Enterprise-grade deployments
+
+### Hybrid Deployments
+
+**Configuration**:
+```yaml
+cluster:
+  nodes:
+    control-1:
+      role: "controlplane"
+      taints: []                # Allow workloads on control plane
+    worker-gpu:
+      role: "worker"
+      labels:
+        nvidia.com/gpu: "true"  # GPU-enabled node
+```
+
+**Use Cases**:
+- Mixed workload requirements
+- Specialized hardware (GPU, storage)
+- Cost optimization
+- Gradual scaling
+
+The Wild Cloud architecture provides a solid foundation for personal cloud infrastructure while maintaining flexibility for customization and extension.
--- a/docs/agent-context/wildcloud/setup-process.md
+++ b/docs/agent-context/wildcloud/setup-process.md
@@ -0,0 +1,395 @@
+# Wild Cloud Setup Process & Infrastructure
+
+Wild Cloud provides a complete, production-ready Kubernetes infrastructure designed for personal use. It combines enterprise-grade technologies to create a self-hosted cloud platform with automated deployment, HTTPS certificates, and web management interfaces.
+
+## Setup Phases Overview
+
+The Wild Cloud setup follows a sequential, dependency-aware process:
+
+1. **Environment Setup** - Install required tools and dependencies
+2. **DNS/Network Foundation** - Set up dnsmasq for DNS and PXE booting
+3. **Cluster Infrastructure** - Deploy Talos Linux nodes and Kubernetes cluster
+4. **Cluster Services** - Install core services (ingress, storage, certificates, etc.)
+
+## Phase 1: Environment Setup
+
+### Dependencies Installation
+**Script**: `scripts/setup-utils.sh`
+
+**Required Tools**:
+- `kubectl` - Kubernetes CLI
+- `gomplate` - Template processor for configuration
+- `kustomize` - Kubernetes configuration management
+- `yq` - YAML processor
+- `restic` - Backup tool
+- `talosctl` - Talos Linux cluster management
+
+### Project Initialization
+**Command**: `wild-init`
+
+Creates the basic Wild Cloud directory structure:
+- `.wildcloud/` - Project marker and cache
+- `config.yaml` - Main configuration file
+- `secrets.yaml` - Sensitive data storage
+- Basic project scaffolding
+
+## Phase 2: DNS/Network Foundation
+
+### dnsmasq Infrastructure
+**Location**: `setup/dnsmasq/`
+**Requirements**: Dedicated Linux machine with static IP
+
+**Services Provided**:
+1. **LAN DNS Server**
+   - Forwards internal domains (`*.internal.domain.com`) to cluster
+   - Forwards external domains (`*.domain.com`) to cluster
+   - Provides DNS resolution for entire network
+
+2. **PXE Boot Server**
+   - Enables network booting for cluster node installation
+   - DHCP/TFTP services for Talos Linux deployment
+   - Automated node provisioning
+
+**Network Configuration Example**:
+```yaml
+network:
+  subnet: 192.168.1.0/24
+  gateway: 192.168.1.1
+  dnsmasq_ip: 192.168.1.50
+  dhcp_range: 192.168.1.100-200
+  metallb_pool: 192.168.1.80-89
+  control_plane_vip: 192.168.1.90
+  node_ips: 192.168.1.91-93
+```
+
+## Phase 3: Cluster Infrastructure Setup
+
+### Talos Linux Foundation
+**Command**: `wild-setup-cluster`
+
+**Talos Configuration**:
+- **Version**: v1.11.0 (configurable)
+- **Immutable OS**: Designed specifically for Kubernetes
+- **System Extensions**:
+  - Intel microcode updates
+  - iSCSI tools for storage
+  - gVisor container runtime
+  - NVIDIA GPU support (optional)
+  - Additional system utilities
+
+### Cluster Setup Process
+
+#### 1. Configuration Generation
+**Script**: `wild-cluster-config-generate`
+
+- Generates base Talos configurations (`controlplane.yaml`, `worker.yaml`)
+- Creates cluster secrets using `talosctl gen config`
+- Establishes foundation for all node configurations
+
+#### 2. Hardware Detection
+**Script**: `wild-node-detect`
+
+Interactive process for each node:
+- Boots nodes into maintenance mode via PXE
+- Detects network interfaces and storage devices
+- Returns JSON specification of hardware capabilities
+- Records node-specific configuration data
+
+#### 3. Node-Specific Configuration
+**Script**: `wild-cluster-node-patch-generate`
+
+- Generates patches for individual nodes
+- Uses templates with detected hardware specifications
+- Creates node-specific machine configurations
+- Handles IP addresses, interfaces, and disk layout
+
+#### 4. Node Deployment
+**Script**: `wild-cluster-node-up`
+
+- Applies Talos configurations to nodes
+- Supports `--insecure` for maintenance mode
+- Generates final configs from base + patches
+- Deploys both control plane and worker nodes
+
+### Cluster Architecture
+
+**Control Plane**:
+- 3 nodes for high availability
+- Virtual IP (VIP) for load balancing
+- etcd distributed across all control plane nodes
+
+**Worker Nodes**:
+- Variable count (configured during setup)
+- Dedicated workload execution
+- Storage participation via Longhorn
+
+**Networking**:
+- All nodes on same LAN segment
+- Sequential IP assignment
+- MetalLB integration for load balancing
+
+## Phase 4: Cluster Services Installation
+
+### Services Deployment Process
+**Command**: `wild-setup-services`
+
+**New Architecture**: Per-service atomic operations
+- Uses `wild-service-setup <service>` for each service in dependency order
+- Each service handles complete lifecycle: fetch → configure → deploy
+- Dependency validation before each service deployment
+- Fail-fast with clear recovery instructions
+
+**Individual Service Management**: `wild-service-setup <service> [options]`
+- **Default**: Configure and deploy using existing templates
+- **`--fetch`**: Fetch fresh templates before setup
+- **`--no-deploy`**: Configure only, skip deployment
+
+### Core Services (Installed in Order)
+
+#### 1. MetalLB Load Balancer
+**Location**: `setup/cluster-services/metallb/`
+
+- **Purpose**: Provides load balancing for bare metal clusters
+- **Functionality**: Assigns external IPs to Kubernetes services
+- **Configuration**: IP address pool from local network range
+- **Integration**: Foundation for ingress traffic routing
+
+#### 2. Longhorn Distributed Storage
+**Location**: `setup/cluster-services/longhorn/`
+
+- **Purpose**: Distributed block storage for persistent volumes
+- **Features**:
+  - Cross-node data replication
+  - Snapshot and backup capabilities
+  - Volume expansion and management
+  - Web-based management interface
+- **Storage**: Uses local disks from all cluster nodes
+
+#### 3. Traefik Ingress Controller
+**Location**: `setup/cluster-services/traefik/`
+
+- **Purpose**: HTTP/HTTPS reverse proxy and ingress controller
+- **Features**:
+  - Automatic service discovery
+  - TLS termination
+  - Load balancing and routing
+  - Gateway API support
+- **Integration**: Works with MetalLB for external traffic
+
+#### 4. CoreDNS
+**Location**: `setup/cluster-services/coredns/`
+
+- **Purpose**: DNS resolution for cluster services
+- **Integration**: Connects with external DNS providers
+- **Functionality**: Service discovery and DNS forwarding
+
+#### 5. cert-manager
+**Location**: `setup/cluster-services/cert-manager/`
+
+- **Purpose**: Automatic TLS certificate management
+- **Features**:
+  - Let's Encrypt integration
+  - Automatic certificate issuance and renewal
+  - Multiple certificate authorities support
+  - Certificate lifecycle management
+
+#### 6. ExternalDNS
+**Location**: `setup/cluster-services/externaldns/`
+
+- **Purpose**: Automatic DNS record management
+- **Functionality**:
+  - Syncs Kubernetes services with DNS providers
+  - Automatic A/CNAME record creation
+  - Supports multiple DNS providers (Cloudflare, Route53, etc.)
+
+#### 7. Kubernetes Dashboard
+**Location**: `setup/cluster-services/kubernetes-dashboard/`
+
+- **Purpose**: Web UI for cluster management
+- **Access**: `https://dashboard.internal.domain.com`
+- **Authentication**: Token-based access via `wild-dashboard-token`
+- **Features**: Resource management, monitoring, troubleshooting
+
+#### 8. NFS Storage (Optional)
+**Location**: `setup/cluster-services/nfs/`
+
+- **Purpose**: Network file system for shared storage
+- **Use Cases**: Media storage, backups, shared data
+- **Integration**: Mounted as persistent volumes in applications
+
+#### 9. Docker Registry
+**Location**: `setup/cluster-services/docker-registry/`
+
+- **Purpose**: Private container registry
+- **Features**: Store custom images locally
+- **Integration**: Used by applications and CI/CD pipelines
+
+## Infrastructure Components Deep Dive
+
+### DNS and Domain Architecture
+
+```
+Internet → External DNS → MetalLB LoadBalancer → Traefik → Kubernetes Services
+                               ↑
+                           Internal DNS (dnsmasq)
+                               ↑
+                         Internal Network
+```
+
+**Domain Types**:
+- **External**: `app.domain.com` - Public-facing services
+- **Internal**: `app.internal.domain.com` - Admin interfaces only
+- **Resolution**: dnsmasq forwards all domain traffic to cluster
+
+### Certificate and TLS Management
+
+**Automatic Certificate Flow**:
+1. Service deployed with ingress annotation
+2. cert-manager detects certificate requirement
+3. Let's Encrypt challenge initiated
+4. Certificate issued and stored in Kubernetes secret
+5. Traefik uses certificate for TLS termination
+6. Automatic renewal before expiration
+
+### Storage Architecture
+
+**Longhorn Distributed Storage**:
+- Block-level replication across nodes
+- Default 3-replica policy for data durability
+- Automatic failover and recovery
+- Snapshot and backup capabilities
+- Web UI for management and monitoring
+
+**Storage Classes**:
+- `longhorn` - Default replicated storage
+- `longhorn-single` - Single replica for non-critical data
+- `nfs` - Shared network storage (if configured)
+
+### Network Traffic Flow
+
+**External Request Flow**:
+1. DNS resolution via dnsmasq → cluster IP
+2. Traffic hits MetalLB load balancer
+3. MetalLB forwards to Traefik ingress
+4. Traefik terminates TLS and routes to service
+5. Service forwards to appropriate pod
+6. Response follows reverse path
+
+### High Availability Features
+
+**Control Plane HA**:
+- 3 control plane nodes with leader election
+- Virtual IP for API server access
+- etcd cluster with automatic failover
+- Distributed workload scheduling
+
+**Storage HA**:
+- Longhorn 3-way replication
+- Automatic replica placement across nodes
+- Node failure recovery
+- Data integrity verification
+
+**Networking HA**:
+- MetalLB speaker pods on all nodes
+- Automatic load balancer failover
+- Multiple ingress controller replicas
+
+## Hardware Requirements
+
+### Minimum Specifications
+- **Nodes**: 3 control plane + optional workers
+- **RAM**: 8GB minimum per node (16GB+ recommended)
+- **CPU**: 4 cores minimum per node
+- **Storage**: 100GB+ local storage per node
+- **Network**: Gigabit ethernet connectivity
+
+### Network Requirements
+- All nodes on same LAN segment
+- Static IP assignments or DHCP reservations
+- dnsmasq server accessible by all nodes
+- Internet connectivity for image pulls and Let's Encrypt
+
+### Recommended Hardware
+- **Control Plane**: 16GB RAM, 8 cores, 200GB NVMe SSD
+- **Workers**: 32GB RAM, 16 cores, 500GB NVMe SSD
+- **Network**: Dedicated VLAN or network segment
+- **Redundancy**: UPS protection, dual network interfaces
+
+## Configuration Management
+
+### Configuration Files
+- `config.yaml` - Main configuration (domains, network, apps)
+- `secrets.yaml` - Sensitive data (passwords, API keys, certificates)
+- `.wildcloud/` - Cache and temporary files
+
+### Template System
+**gomplate Integration**:
+- All configurations processed as templates
+- Access to config and secrets via template variables
+- Dynamic configuration generation
+- Environment-specific customization
+
+### Configuration Commands
+```bash
+# Read configuration values
+wild-config cluster.name
+wild-config apps.ghost.domain
+
+# Set configuration values
+wild-config-set cloud.domain "example.com"
+wild-config-set cluster.nodeCount 5
+
+# Secret management
+wild-secret apps.database.password
+wild-secret-set apps.api.key "secret-value"
+```
+
+## Setup Commands Reference
+
+### Complete Setup
+```bash
+wild-init              # Initialize project
+wild-setup             # Complete automated setup
+```
+
+### Phase-by-Phase Setup
+```bash
+wild-setup-cluster     # Cluster infrastructure only
+wild-setup-services    # Cluster services only
+```
+
+### Individual Operations
+```bash
+wild-cluster-config-generate     # Generate base configs
+wild-node-detect <ip>           # Hardware detection
+wild-cluster-node-up <node>     # Deploy single node
+wild-dashboard-token            # Get dashboard access
+wild-health                     # System health check
+```
+
+## Troubleshooting and Validation
+
+### Health Checks
+```bash
+wild-health                     # Overall system status
+kubectl get nodes              # Node status
+kubectl get pods -A            # All pod status
+talosctl health                # Talos cluster health
+```
+
+### Service Validation
+```bash
+kubectl get svc -n metallb-system     # MetalLB status
+kubectl get pods -n longhorn-system   # Storage status
+kubectl get pods -n traefik          # Ingress status
+kubectl get certificates -A           # Certificate status
+```
+
+### Log Analysis
+```bash
+talosctl logs -f machined             # Talos system logs
+kubectl logs -n traefik deployment/traefik  # Ingress logs
+kubectl logs -n cert-manager deployment/cert-manager  # Certificate logs
+```
+
+This comprehensive setup process creates a production-ready personal cloud infrastructure with enterprise-grade reliability, security, and management capabilities.