feat: clarify precipitate pattern as runtime state documentation tool

- Updated ROADMAP.md to redefine precipitate pattern as a display-only observability tool, not disk sync
- Added detailed explanation of what --precipitate does: queries runtime state and displays as declarative config
- Clarified that precipitate never writes to disk, requiring manual user action to persist changes
- Added comparison table between drift detection and precipitate features
- Added new --caddy flag to debug command for

Author: CodeMonkeyCybersecurity

ROADMAP.md

@@ -3702,45 +3702,60 @@ sudo eos update hecate --migrate-to-vault  # Migrates existing .env to Vault
 
 ---
 
-### Phase C: Option C - Precipitate Pattern (Runtime → Disk Sync) 📅 DEFERRED (2026-01 → 2026-02)
-
-**Goal**: Automatically sync live Caddy API state and Docker runtime back to disk files
-
-**Status**: ⚠️ DEFERRED - Blocked by technical challenges (see below)
-
-**Rationale for Deferral**:
-1. **Caddy JSON → Caddyfile conversion is lossy/impossible** (Issue #11 from Option B analysis)
-   - Caddy Admin API returns JSON format
-   - No official JSON → Caddyfile converter exists
-   - Manual conversion loses comments, formatting, and some directives
-   - Would require building custom AST parser (100+ hours effort)
-
-2. **Comment preservation is non-trivial**
-   - User's working Caddyfile has inline comments explaining config
-   - JSON format doesn't preserve comments
-   - Precipitating would destroy all documentation
-
-3. **Secret handling complexity**
-   - Environment variables in docker-compose.yml may contain secrets
-   - Precipitating runtime values could expose secrets in version control
-   - Need secret detection + Vault integration first
-
-4. **Option B (drift detection) solves 80% of the problem**
-   - Users get actionable drift reports with remediation commands
-   - Manual fixes are well-documented and low-risk
-   - Automatic precipitation adds complexity without proportional value
-
-**Alternative Approach** (if demand emerges):
-- **Manual Sync Workflow**: User reviews `21_DRIFT_REPORT.md` → manually applies changes
-- **Assisted Sync**: `eos update hecate --suggest-fixes` generates bash script with recommended changes (user reviews before executing)
-- **Partial Precipitation**: Sync ONLY routes (not env vars) using Caddy Admin API → Caddyfile template regeneration
-
-**Revisit Criteria**:
-- User feedback: 5+ requests for automatic precipitation
-- Caddy upstream: Official JSON → Caddyfile converter released
-- Secret manager: Phase 4-6 complete (Vault integration mature)
-
-**Revisit Date**: January 15, 2026 (after Phase B.2 complete, gather user feedback)
+### Phase C: Option C - Precipitate Pattern (Runtime State Documentation) ✅ CLARIFIED (2025-10-31)
+
+**Goal**: Document live Caddy API state and Docker runtime in declarative format for observability
+
+**Status**: ✅ PATTERN CLARIFIED - Pure observability tool, no disk writes
+
+**What --precipitate Does** (CORRECTED UNDERSTANDING):
+1. **Query runtime state**:
+   - Caddy Admin API: `GET http://localhost:2019/config` (JSON)
+   - Docker API: `docker inspect hecate-*` containers
+2. **Convert to declarative format**:
+   - Caddy JSON → Caddyfile format representation
+   - Docker inspect → docker-compose.yml format representation
+3. **DISPLAY output to terminal** (does NOT write to disk)
+4. **User manually copies** if they want to persist the runtime state
+
+**Use Cases**:
+- **Documentation**: Capture "what's actually running" for disaster recovery planning
+- **Comparison**: Compare runtime state against git-tracked disk files
+- **Drift understanding**: Visualize the delta between disk templates and live state
+- **Troubleshooting**: See actual running config when debugging issues
+
+**NOT Use Cases** (Anti-patterns):
+- ❌ Automatic synchronization (precipitate is display-only)
+- ❌ Writing files to disk (user must manually copy if desired)
+- ❌ Configuration management (use drift detection + manual fixes instead)
+- ❌ Backup/restore workflow (use proper backup tools)
+
+**Why Pure Observability**:
+1. **Comment preservation**: Never overwrites Caddyfiles with inline documentation
+2. **Secret safety**: No risk of writing secrets to version control
+3. **User control**: Explicit consent required for any disk changes
+4. **No conversion challenges**: Display format can be approximate/lossy (not authoritative)
+
+**Implementation Status**:
+- ✅ Pattern documented in [pkg/hecate/authentik/export.go:870-890](pkg/hecate/authentik/export.go#L870-L890)
+- ✅ Pattern documented in [pkg/hecate/authentik/drift.go:501-507, 661-668](pkg/hecate/authentik/drift.go#L501-L507)
+- ⏳ Drift detection (Phase B) provides recommendations to use `--precipitate`
+- ⏳ CLI flag `--precipitate` implementation (pending)
+
+**Comparison with Drift Detection (Phase B)**:
+
+| Feature | Drift Detection (Phase B) | Precipitate (Phase C) |
+|---------|---------------------------|------------------------|
+| **Purpose** | Identify differences | Document runtime state |
+| **Output** | Drift report with remediation | Declarative config (display only) |
+| **Actionable?** | Yes (commands to fix) | No (informational only) |
+| **Writes files?** | Yes (drift report) | No (display only) |
+| **Use case** | Ongoing monitoring | Ad-hoc documentation |
+
+**Implementation Priority**: LOW (2026-02+)
+- Drift detection (Phase B) solves operational monitoring
+- Precipitate adds documentation value but not critical path
+- Wait for user feedback after Phase B deployment
 
 ---
 

cmd/debug/hecate.go

@@ -11,6 +11,7 @@ var (
 	hecateComponent      string
 	hecateAuthentikCheck bool
 	hecateBionicGPTCheck bool
+	hecateCaddyCheck     bool
 	hecatePath           string
 	hecateVerbose        bool
 )
@@ -68,10 +69,20 @@ BionicGPT integration diagnostics (--bionicgpt flag):
   • End-to-end authentication flow test
   • Common misconfigurations detection
 
+Caddy Admin API diagnostics (--caddy flag):
+  • Connection testing with retry attempts
+  • Health endpoint verification
+  • Configuration retrieval and parsing
+  • Route listing and validation
+  • Admin API port accessibility
+  • Network connectivity diagnosis
+  • Timeout and performance analysis
+
 Flags:
   --component <name>  Only check specific component (caddy|authentik|postgresql|redis|nginx|coturn)
   --authentik         Run comprehensive Authentik health check + configuration export
   --bionicgpt         Run BionicGPT integration diagnostics (Authentik-Caddy-BionicGPT)
+  --caddy             Run Caddy Admin API diagnostics (connection, health, routes)
   --path <path>       Path to Hecate installation (default: /opt/hecate)
   --verbose           Show detailed diagnostic output
 
@@ -80,6 +91,7 @@ Examples:
   eos debug hecate --component authentik  # Only diagnose Authentik
   eos debug hecate --authentik          # Full Authentik health check + config export
   eos debug hecate --bionicgpt          # BionicGPT integration diagnostics
+  eos debug hecate --caddy              # Caddy Admin API diagnostics
   eos debug hecate --path /custom/path  # Custom installation path
 
 Output is automatically saved to ~/.eos/debug/eos-debug-hecate-{timestamp}.txt`,
@@ -90,6 +102,7 @@ func init() {
 	hecateCmd.Flags().StringVar(&hecateComponent, "component", "", "Specific component to check")
 	hecateCmd.Flags().BoolVar(&hecateAuthentikCheck, "authentik", false, "Run comprehensive Authentik health check + configuration export")
 	hecateCmd.Flags().BoolVar(&hecateBionicGPTCheck, "bionicgpt", false, "Run BionicGPT integration diagnostics (Authentik-Caddy-BionicGPT triangle)")
+	hecateCmd.Flags().BoolVar(&hecateCaddyCheck, "caddy", false, "Run Caddy Admin API diagnostics (connection, health, routes)")
 	hecateCmd.Flags().StringVar(&hecatePath, "path", "/opt/hecate", "Path to Hecate installation")
 	hecateCmd.Flags().BoolVar(&hecateVerbose, "verbose", false, "Show detailed diagnostic output")
 	debugCmd.AddCommand(hecateCmd)

pkg/hecate/authentik/drift.go

@@ -498,8 +498,13 @@ func generateRecommendations(report *DriftReport) []string {
 		if len(report.CaddyDrift.AddedRoutes) > 0 {
 			recommendations = append(recommendations,
 				"Add missing routes to /opt/hecate/Caddyfile to prevent loss on reload")
+			// PRECIPITATE PATTERN: Query EXISTING RUNNING state → DOCUMENT as declarative .yml
+			// For Caddy: GET /config via Admin API → Convert JSON to Caddyfile → DISPLAY (not write)
+			// For Docker: docker inspect containers → Generate docker-compose.yml → DISPLAY (not write)
+			// GOAL: Show "what's actually running" in declarative format for comparison/documentation
+			// NOTE: Does NOT write to disk - purely observability
 			recommendations = append(recommendations,
-				fmt.Sprintf("Run: eos update hecate --precipitate (Option C) to sync API state to disk"))
+				fmt.Sprintf("Run: eos update hecate --precipitate to document current runtime state"))
 		}
 
 		if len(report.CaddyDrift.RemovedRoutes) > 0 {
@@ -653,8 +658,14 @@ func RenderDriftReport(report *DriftReport) string {
 	// Remediation Commands
 	sb.WriteString("## Remediation Commands\n\n")
 	sb.WriteString("```bash\n")
-	sb.WriteString("# Option 1: Precipitate runtime state to disk (COMING SOON)\n")
-	sb.WriteString("eos update hecate --precipitate\n\n")
+	sb.WriteString("# Option 1: Document runtime state (COMING SOON)\n")
+	sb.WriteString("# PRECIPITATE: Query running state → Display as declarative config\n")
+	sb.WriteString("#   - Caddy Admin API (/config) → Convert to Caddyfile format → DISPLAY\n")
+	sb.WriteString("#   - Docker inspect → Convert to docker-compose.yml → DISPLAY\n")
+	sb.WriteString("#   - Shows what's ACTUALLY running vs what's on disk\n")
+	sb.WriteString("#   - Does NOT write files (purely observability/documentation)\n")
+	sb.WriteString("eos update hecate --precipitate\n")
+	sb.WriteString("# User can then manually copy output to disk files if desired\n\n")
 	sb.WriteString("# Option 2: Reload Caddy from disk Caddyfile (loses API changes)\n")
 	sb.WriteString("docker exec hecate-caddy caddy reload --config /etc/caddy/Caddyfile\n\n")
 	sb.WriteString("# Option 3: Recreate containers from compose file\n")

pkg/hecate/authentik/export.go

@@ -905,11 +905,26 @@ ls -lh 19_Caddyfile.disk 19_Caddyfile.live.json
 
 ### Reconciling Drift:
 
-**Option 1: Precipitate API → Disk (coming soon)**
+**Option 1: Document Runtime State (coming soon)**
 `+"```"+`
-# This will be implemented in Option C
+# PRECIPITATE PATTERN: Query running state → Document as declarative config
+#
+# What --precipitate does:
+# 1. Query Caddy Admin API: GET http://localhost:2019/config
+# 2. Convert JSON response to Caddyfile format
+# 3. Query Docker API: docker inspect hecate-* containers
+# 4. Generate docker-compose.yml with actual networks, volumes, env vars
+# 5. DISPLAY both configs (does NOT write to disk)
+#
+# Output shows:
+# - What Caddyfile SHOULD look like to match runtime
+# - What docker-compose.yml SHOULD look like to match runtime
+#
+# User can then:
+# - Copy output to /opt/hecate/Caddyfile if desired
+# - Version control the "runtime reality" for documentation
+# - Compare against git history to understand drift
 eos update hecate --precipitate
-# Writes live API state back to disk files
 `+"```"+`
 
 **Option 2: Manual Reconciliation**

pkg/hecate/debug.go

@@ -56,14 +56,21 @@ func RunHecateDebug(rc *eos_io.RuntimeContext, cmd *cobra.Command, args []string
 	component, _ := cmd.Flags().GetString("component")
 	authentikCheck, _ := cmd.Flags().GetBool("authentik")
 	bionicgptCheck, _ := cmd.Flags().GetBool("bionicgpt")
+	caddyCheck, _ := cmd.Flags().GetBool("caddy")
 	hecatePath, _ := cmd.Flags().GetString("path")
 	verbose, _ := cmd.Flags().GetBool("verbose")
 
 	logger.Info("Starting Hecate diagnostics",
 		zap.String("component_filter", component),
 		zap.String("path", hecatePath),
 		zap.Bool("authentik_check", authentikCheck),
-		zap.Bool("bionicgpt_check", bionicgptCheck))
+		zap.Bool("bionicgpt_check", bionicgptCheck),
+		zap.Bool("caddy_check", caddyCheck))
+
+	// If --caddy flag is set, run Caddy Admin API diagnostics
+	if caddyCheck {
+		return RunCaddyAdminAPIDebug(rc, hecatePath, verbose)
+	}
 
 	// If --bionicgpt flag is set, run BionicGPT integration diagnostics
 	if bionicgptCheck {