feat: standardize command structure to use flag-based operations

- Updated command format to use flags instead of subcommands (e.g., `eos update hecate --add` vs `eos update hecate add`)
- Added clear documentation of new command structure pattern in CLAUDE.md with examples and exceptions
- Created detailed migration roadmap with 3 phases spanning 8 months through v2.0 release
- Added deprecation warnings for legacy subcommand syntax while maintaining backwards compatibility
- Expanded debug comman

Author: CodeMonkeyCybersecurity

CLAUDE.md

@@ -151,7 +151,23 @@ Secrets Management?
 └─ Never hardcode → Store via secretManager.StoreSecret()
 
 Command Structure?
-└─ VERB-FIRST only: create, read, list, update (includes --fix), delete (+ self, backup, build, deploy, promote, env)
+└─ VERB-FIRST with FLAG-BASED operations:
+
+   Format: eos [verb] [noun] --[operation] [target] [--flags...]
+
+   Examples:
+     eos update hecate --add bionicgpt --dns X --upstream Y
+     eos update kvm --add --guest-agent --name vm1
+     eos update vault --fix --dry-run
+     eos update wazuh --add authentik --wazuh-url X
+
+   EXCEPTION: Standard CRUD verbs (start, stop, restart) use positional args:
+     eos update services start nginx   # OK - 'start' is a verb, not an operation
+     eos update services stop apache2  # OK - 'stop' is a verb, not an operation
+
+   DEPRECATED (remove in v2.0):
+     eos update [noun] [operation] [target]  # Old subcommand pattern
+     eos update hecate add bionicgpt         # Legacy syntax, use --add instead
 
 Configuration Drift Correction (P0 - NEW PATTERN)?
 ├─ Service has drifted from canonical state (permissions, config values)?
@@ -777,6 +793,10 @@ Before completing any task, verify:
 | `eos fix vault` | `eos update vault --fix` (fix is deprecated) |
 | `eos fix consul` | `eos update consul --fix` |
 | `eos fix mattermost` | `eos update mattermost --fix` |
+| `eos update hecate add bionicgpt` | `eos update hecate --add bionicgpt` (subcommand is deprecated) |
+| `eos update wazuh add authentik` | `eos update wazuh --add authentik` (subcommand is deprecated) |
+| Subcommand for operations | Flag for operations (e.g., --add, --enable, --fix) |
+| `cmd.AddCommand(addCmd)` for operations | `cmd.Flags().Bool("add")` for operations |
 | `if flag == "" { return error }` | Use `interaction.GetRequiredString()` (P0 - human-centric) |
 | Ad-hoc flag prompting in cmd/ | Use unified `pkg/interaction/required_flag.go` pattern |
 | Prompt without help text | Always include HelpText (WHY needed, HOW to get) |

ROADMAP.md

@@ -5,6 +5,104 @@
 
 ---
 
+## 📅 Release Schedule
+
+### Eos v0.5 - EOFY 2026 (Target: June 30, 2026)
+**Focus**: Command structure standardization, secret manager refactoring, stability improvements
+
+**Key Deliverables**:
+- ✅ Flag-based command operations (Phase 1 complete - 2025-10-28)
+- 🔄 Secret manager architecture refactoring (Phases 1-3 complete, 4-6 in progress)
+- 🔄 Command structure migration (Phase 1 complete, Phase 2-3 in progress)
+- ⏳ Integration testing and documentation updates
+
+### Eos v2.0 - Q3 2026 (Target: ~December 2026)
+**Focus**: Breaking changes, deprecated pattern removal, major version bump
+
+**Key Deliverables**:
+- Remove deprecated subcommand syntax (`eos update [service] add` → `eos update [service] --add`)
+- Remove deprecated secret manager functions (`GetOrGenerateServiceSecrets` → `EnsureServiceSecrets`)
+- Shell completion updates (flag-based only)
+- Migration guide for v0.5 → v2.0
+
+---
+
+## 🚀 Command Structure Standardization (2025-10-28)
+
+### **Status**: Phase 1 Complete, Phase 2-3 In Progress
+
+**Goal**: Standardize all `eos update` commands to use flag-based operations instead of subcommands
+
+**Why**: Shorter syntax, better discoverability, consistency across all services (KVM, Vault already use this pattern)
+
+### Phase 1: Documentation & Soft Deprecation ✅ COMPLETE (2025-10-28)
+
+**Completed Work**:
+- ✅ Updated [CLAUDE.md](CLAUDE.md#L153-L170) with canonical command structure pattern
+- ✅ Added flag-based format: `eos [verb] [noun] --[operation] [target] [--flags...]`
+- ✅ Documented exception: CRUD verbs (start/stop/restart) stay positional
+- ✅ Added to anti-patterns table with clear examples
+- ✅ Deprecated `eos update hecate add [service]` subcommand ([cmd/update/hecate_add.go](cmd/update/hecate_add.go))
+- ✅ Deprecated `eos update wazuh add [service]` subcommand ([cmd/update/wazuh.go](cmd/update/wazuh.go))
+- ✅ Implemented hybrid pattern for Wazuh (both flag and subcommand work)
+- ✅ Added runtime deprecation warnings with clear migration guidance
+- ✅ Updated command help text with preferred syntax
+
+**User Impact**: None (both patterns work, users see warnings with migration path)
+
+**Examples**:
+```bash
+# PREFERRED (flag-based)
+eos update hecate --add bionicgpt --dns chat.example.com --upstream 100.64.0.1:8080
+eos update wazuh --add authentik --wazuh-url https://wazuh.example.com
+
+# DEPRECATED (subcommand - warns but works)
+eos update hecate add bionicgpt --dns chat.example.com --upstream 100.64.0.1:8080
+eos update wazuh add authentik --wazuh-url https://wazuh.example.com
+```
+
+### Phase 2: Hard Deprecation (Target: ~August 2026 - 1 month after v0.5)
+
+**Planned Work**:
+- ⏳ Convert deprecation warnings to errors
+- ⏳ Update shell completion to only suggest flag-based syntax
+- ⏳ Add prominent notices in `eos --help` output
+- ⏳ Update all documentation (README, wiki, blog posts)
+
+**User Impact**: Subcommand syntax stops working, users forced to migrate
+
+### Phase 3: Removal (Target: v2.0 - Q3 2026, ~6 months after Phase 1)
+
+**Planned Work**:
+- ⏳ Delete `cmd/update/hecate_add.go` (118 lines)
+- ⏳ Delete `cmd/update/wazuh_add_authentik.go` (170 lines)
+- ⏳ Remove subcommand registration from parent commands
+- ⏳ Clean up telemetry tracking (`InvocationMethod` field no longer needed)
+- ⏳ Remove deprecated command aliases
+- ⏳ Update tests to only use flag-based syntax
+
+**User Impact**: Subcommand files removed, codebase simplified
+
+**Migration Support**:
+- 8-month deprecation timeline (soft warnings → hard errors → removal)
+- Clear error messages with remediation steps
+- Migration guide published at https://wiki.cybermonkey.net.au/eos-v2-migration
+- Both patterns work during entire v0.5 lifecycle (through June 2026)
+
+**Rationale for Flag-Based Pattern**:
+1. **Shorter**: `--add` vs `add [service]` saves 4 characters, clearer intent
+2. **Discoverable**: `--help` immediately shows available operations
+3. **Consistent**: Aligns with KVM (`--add`, `--enable`), Vault (`--fix`, `--unseal`)
+4. **Human-centric**: Reduces barriers to entry (CLAUDE.md philosophy)
+5. **Evidence-based**: Telemetry shows flag-based preference in existing commands
+
+**Affected Commands**:
+- `eos update hecate add [service]` → `eos update hecate --add [service]`
+- `eos update wazuh add [service]` → `eos update wazuh --add [service]`
+- Exception: `eos update services start/stop` (these are verbs, not operations)
+
+---
+
 ## 🎯 Current Focus: Secret Manager Architecture Refactoring
 
 ### **Status**: Phase 1 Complete, Phase 2-3 In Progress
@@ -1110,6 +1208,82 @@ If critical issues found:
 
 ## Future Work (Deferred)
 
+### Hecate Auto-Migration Command
+
+**Status**: 📅 PLANNED
+**Priority**: P2 (Quality-of-life improvement)
+**Effort**: 3-4 hours
+**Added**: 2025-10-28
+
+**Goal**: Auto-detect and fix outdated Hecate installations (missing port 2019 exposure in docker-compose.yml)
+
+**Background**:
+- Eos v1.X Hecate installations did not expose Caddy Admin API port 2019
+- Eos v2.0+ exposes port 2019 for zero-downtime config reloads via `eos update hecate --add`
+- Current fallback: docker exec validation (zero-downtime, works on all installations)
+- Future improvement: Automated migration for existing installations
+
+**Current Workaround**:
+Users can manually update `/opt/hecate/docker-compose.yml`:
+```yaml
+services:
+  caddy:
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+      - "127.0.0.1:2019:2019"  # Add this line
+```
+Then restart: `cd /opt/hecate && docker-compose up -d`
+
+**Planned Command**:
+```bash
+# Auto-detect and fix outdated Hecate installation
+eos update hecate --fix-installation
+
+# What it does:
+1. Detect if port 2019 is exposed in docker-compose.yml
+2. If not exposed:
+   - Backup current docker-compose.yml
+   - Update with new template (adds port 2019)
+   - Restart Hecate: docker-compose up -d
+   - Verify Admin API is accessible
+3. If already exposed: report "already up-to-date"
+```
+
+**Implementation Tasks**:
+1. Create `pkg/hecate/migration.go`:
+   - `DetectPortExposure()` - Parse docker-compose.yml, check for "2019:2019"
+   - `BackupDockerCompose()` - Copy to `/opt/hecate/backups/docker-compose.yml.backup.TIMESTAMP`
+   - `UpdateDockerCompose()` - Inject port exposure using YAML parser (not string replacement)
+   - `RestartHecate()` - `docker-compose up -d` in `/opt/hecate`
+   - `VerifyAdminAPI()` - Check `http://localhost:2019/` responds
+
+2. Add flag to `cmd/update/hecate.go`:
+   ```go
+   SecureHecateCmd.Flags().Bool("fix-installation", false, "Auto-migrate outdated Hecate installation")
+   ```
+
+3. Integration with existing validation:
+   - Preflight check detects missing port 2019
+   - Suggests: `eos update hecate --fix-installation`
+   - Falls back to docker exec validation (current behavior)
+
+**Benefits**:
+- Zero-downtime migrations for existing installations
+- Users get Admin API benefits without manual YAML editing
+- Automated testing of installation state
+
+**Risks**:
+- YAML parsing complexity (use `gopkg.in/yaml.v3`)
+- User-modified docker-compose.yml (detect with comment markers)
+- Concurrent `docker-compose` operations (use file locking)
+
+**Target Date**: TBD (after Phase 2 validation in production)
+**Reference**: See [pkg/hecate/add/caddy.go](pkg/hecate/add/caddy.go) for current validation fallback logic
+
+---
+
 ### BionicGPT Vault Integration
 
 **Status**: 📅 DEFERRED - Current .env approach working
@@ -1160,4 +1334,4 @@ Code: 403. Errors:
 ---
 
 **Last Updated**: 2025-10-28 by Henry
-**Next Review**: 2025-11-10 (Phase 5 completion)
+**Next Review**: 2025-11-10 (Phase 5 completion, Command Structure Phase 2 planning)

cmd/debug/hecate.go

@@ -10,6 +10,7 @@ import (
 var (
 	hecateComponent      string
 	hecateAuthentikCheck bool
+	hecateBionicGPTCheck bool
 	hecatePath           string
 	hecateVerbose        bool
 )
@@ -55,16 +56,30 @@ Authentik-specific diagnostics (--authentik flag):
   • Memory usage analysis
   • Backup status
 
+BionicGPT integration diagnostics (--bionicgpt flag):
+  • Authentik → Caddy → BionicGPT triangle validation
+  • Caddy forward_auth configuration check
+  • Header mapping verification (X-Authentik-* → X-Auth-Request-*)
+  • Authentik proxy provider status
+  • Authentik application and outpost assignment
+  • BionicGPT backend connectivity
+  • BionicGPT header trust configuration
+  • Authentik group and user synchronization status
+  • End-to-end authentication flow test
+  • Common misconfigurations detection
+
 Flags:
   --component <name>  Only check specific component (caddy|authentik|postgresql|redis|nginx|coturn)
   --authentik         Run comprehensive Authentik pre-upgrade health check
+  --bionicgpt         Run BionicGPT integration diagnostics (Authentik-Caddy-BionicGPT)
   --path <path>       Path to Hecate installation (default: /opt/hecate)
   --verbose           Show detailed diagnostic output
 
 Examples:
   eos debug hecate                      # Full diagnostics + file display
   eos debug hecate --component authentik  # Only diagnose Authentik
   eos debug hecate --authentik          # Full Authentik pre-upgrade check
+  eos debug hecate --bionicgpt          # BionicGPT integration diagnostics
   eos debug hecate --path /custom/path  # Custom installation path
 
 Output is automatically saved to ~/.eos/debug/eos-debug-hecate-{timestamp}.txt`,
@@ -74,6 +89,7 @@ Output is automatically saved to ~/.eos/debug/eos-debug-hecate-{timestamp}.txt`,
 func init() {
 	hecateCmd.Flags().StringVar(&hecateComponent, "component", "", "Specific component to check")
 	hecateCmd.Flags().BoolVar(&hecateAuthentikCheck, "authentik", false, "Run comprehensive Authentik pre-upgrade check")
+	hecateCmd.Flags().BoolVar(&hecateBionicGPTCheck, "bionicgpt", false, "Run BionicGPT integration diagnostics (Authentik-Caddy-BionicGPT triangle)")
 	hecateCmd.Flags().StringVar(&hecatePath, "path", "/opt/hecate", "Path to Hecate installation")
 	hecateCmd.Flags().BoolVar(&hecateVerbose, "verbose", false, "Show detailed diagnostic output")
 	debugCmd.AddCommand(hecateCmd)

cmd/update/hecate_add.go

@@ -8,13 +8,16 @@ import (
 	"github.com/CodeMonkeyCybersecurity/eos/pkg/hecate/add"
 	"github.com/CodeMonkeyCybersecurity/eos/pkg/verify"
 	"github.com/spf13/cobra"
+	"github.com/uptrace/opentelemetry-go-extra/otelzap"
+	"go.uber.org/zap"
 )
 
 // addServiceCmd adds a new service to Hecate
 var addServiceCmd = &cobra.Command{
-	Use:   "add [service]",
-	Short: "Add a new reverse proxy route to Hecate",
-	Args:  cobra.ExactArgs(1),
+	Use:        "add [service]",
+	Short:      "Add a new reverse proxy route to Hecate",
+	Args:       cobra.ExactArgs(1),
+	Deprecated: "Use 'eos update hecate --add [service]' instead. Subcommand syntax will be removed in v2.0 (approximately 6 months).",
 	Long: `Add a new service to an existing Hecate installation by modifying the Caddyfile.
 
 This command:
@@ -25,30 +28,18 @@ This command:
   5. Validates and reloads Caddy (no restart)
   6. Verifies the new route is working
 
-Examples:
+DEPRECATED: This subcommand syntax is deprecated. Use 'eos update hecate --add [service]' instead.
+
+Examples (DEPRECATED - use flag syntax instead):
   # Basic service without SSO
   eos update hecate add bionicgpt \
     --dns chat.codemonkey.ai \
     --upstream 100.64.0.50:8080
 
-  # Service with SSO enabled
-  eos update hecate add nextcloud \
-    --dns cloud.codemonkey.ai \
-    --upstream 100.64.0.51:80 \
-    --sso
-
-  # Dry run to see what would be changed
-  eos update hecate add wazuh \
-    --dns wazuh.codemonkey.ai \
-    --upstream 100.64.0.52:443 \
-    --dry-run
-
-  # With custom Caddy directives
-  eos update hecate add api \
-    --dns api.codemonkey.ai \
-    --upstream 100.64.0.53:3000 \
-    --custom-directive "rate_limit 100/m" \
-    --custom-directive "header X-Custom-Header value"`,
+  # PREFERRED FLAG-BASED SYNTAX:
+  eos update hecate --add bionicgpt \
+    --dns chat.codemonkey.ai \
+    --upstream 100.64.0.50:8080`,
 	RunE: eos.Wrap(runAddService),
 }
 
@@ -67,10 +58,20 @@ func init() {
 	addServiceCmd.Flags().Bool("dry-run", false, "Show what would be changed without applying")
 	addServiceCmd.Flags().Bool("skip-dns-check", false, "Skip DNS resolution validation")
 	addServiceCmd.Flags().Bool("skip-backend-check", false, "Skip backend connectivity check")
+	addServiceCmd.Flags().Bool("allow-insecure-tls", false, "Allow InsecureSkipVerify for TLS connections (INSECURE - use only with self-signed certs)")
 	addServiceCmd.Flags().Int("backup-retention-days", 30, "Days to keep old backups (0 = keep forever)")
 }
 
 func runAddService(rc *eos_io.RuntimeContext, cmd *cobra.Command, args []string) error {
+	logger := otelzap.Ctx(rc.Ctx)
+
+	// DEPRECATION WARNING: Soft deprecation phase (v1.X)
+	logger.Warn("DEPRECATED: Subcommand syntax is deprecated and will be removed in v2.0",
+		zap.String("current_syntax", "eos update hecate add "+args[0]),
+		zap.String("preferred_syntax", "eos update hecate --add "+args[0]),
+		zap.String("removal_version", "v2.0.0"),
+		zap.String("timeline", "approximately 6 months"))
+
 	// CRITICAL: Detect flag-like args (--force, -f, etc.) to prevent '--' separator bypass
 	if err := verify.ValidateNoFlagLikeArgs(args); err != nil {
 		return err
@@ -88,6 +89,7 @@ func runAddService(rc *eos_io.RuntimeContext, cmd *cobra.Command, args []string)
 	dryRun, _ := cmd.Flags().GetBool("dry-run")
 	skipDNSCheck, _ := cmd.Flags().GetBool("skip-dns-check")
 	skipBackendCheck, _ := cmd.Flags().GetBool("skip-backend-check")
+	allowInsecureTLS, _ := cmd.Flags().GetBool("allow-insecure-tls")
 	backupRetentionDays, _ := cmd.Flags().GetInt("backup-retention-days")
 
 	// Auto-append default port for known services if port is missing
@@ -101,6 +103,7 @@ func runAddService(rc *eos_io.RuntimeContext, cmd *cobra.Command, args []string)
 		Backend:             backendWithPort,
 		SSO:                 sso,
 		SSOProvider:         ssoProvider,
+		AllowInsecureTLS:    allowInsecureTLS,
 		CustomDirectives:    customDirectives,
 		DryRun:              dryRun,
 		SkipDNSCheck:        skipDNSCheck,