docs: update all documentation for unified binary architecture

📚 **Complete Documentation Overhaul** **Updated Files:** ✅ **README.md** - Updated commands, configuration, and workflow ✅ **COMMANDS.md** - New comprehensive command reference ✅ **INTEGRATION-SUMMARY.md** - Updated architecture overview ✅ **insertr-server/README.md** - Redirect to unified binary docs **Key Documentation Changes:** 🔧 **Unified Binary Commands:** - Updated all examples to use `./insertr enhance` and `./insertr serve` - Removed references to separate CLI/server binaries - Added comprehensive configuration documentation ⚙️ **Configuration Section:** - Added YAML configuration examples (`insertr.yaml`) - Documented environment variables (`INSERTR_*`) - Explained configuration precedence (CLI → env → YAML → defaults) 📖 **Command Reference (COMMANDS.md):** - Complete reference for all commands and flags - Usage patterns for development and production - API endpoint documentation - Error handling and debugging guides - CI/CD integration examples 🏗️ **Architecture Updates:** - Updated development workflow instructions - Fixed CLI → Binary terminology - Updated hot reload and build process documentation **Migration Notes:** - All functionality preserved in unified binary - Simplified development workflow with `just dev` - Single executable for all operations
2025-09-10 18:12:31 +02:00
parent e28000fd33
commit ae9ae7e442
4 changed files with 593 additions and 117 deletions
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ Containers with `class="insertr"` automatically make their viable children edita
 - **Professional Editor**: Modal forms, markdown support, authentication system
 - **Content Persistence**: SQLite database with REST API, version control
 - **Version History**: Complete edit history with user attribution and one-click rollback
- **CLI Enhancement**: Parse HTML, inject database content, build-time optimization
+- **Build Enhancement**: Parse HTML, inject database content, build-time optimization
 - **Smart Detection**: Auto-detects content types (text/markdown/link)
 - **Deterministic IDs**: Content-based ID generation for consistent developer experience
 - **Full Integration**: Seamless development workflow with hot reload
@@ -98,10 +98,10 @@ just --list        # Show all available commands
 # Development (Full-Stack by Default)
 just dev           # Start full-stack development (recommended)
 just demo-only     # Demo site only (no content persistence)
-just server        # API server only (localhost:8080)
+just serve         # API server only (localhost:8080)

 # Building  
-just build         # Build library + CLI + server (complete stack)
+just build         # Build library + unified binary (complete stack)
 just build-lib     # Build JavaScript library only

 # Utilities
@@ -118,7 +118,7 @@ Running `just dev` gives you the **complete Insertr CMS**:
 - ✅ **Real-Time Persistence** - SQLite database with REST API
 - ✅ **Version Control** - Complete edit history with user attribution and rollback
 - ✅ **Content Management** - Create, read, update content via browser
- ✅ **Build Integration** - CLI enhances HTML with database content
+- ✅ **Build Integration** - Binary enhances HTML with database content
 - ✅ **Hot Reload** - Changes reflected immediately

 ## 📚 **Version Control Features**
@@ -145,16 +145,7 @@ Every content change is automatically tracked with:
 6. All changes are tracked automatically
 ```

-### **Parse Existing Site**
-```bash
-# Analyze HTML for editable elements
-just parse
-# or: cd insertr-cli && go run main.go parse ../demo-site/

-# Development server with parsing
-just servedev
-# or: cd insertr-cli && go run main.go servedev -i ../demo-site -p 3000
-```

 ## 📊 Parser Output Example

@@ -177,16 +168,23 @@ just servedev
   services-grid → 6 children (3×h3, 3×p)
 ```

-## 🏗️ Architecture: Build-Time Enhancement
+## 🏗️ Architecture: Unified Binary

 ### **Enhancement Pipeline**
 ```
-Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
-     ↓                       ↓                       ↓
-  Pure HTML            Parse + Inject Content    Smart Loading
-                       Auto-generate IDs          (Auth-dependent)
+Static Site Build → insertr enhance → Enhanced Deployment
+     ↓                       ↓                 ↓
+  Pure HTML            Parse + Inject        Smart Loading
+                       Database Content      (Auth-dependent)
+                              ↓
+Runtime Content API ← insertr serve ← Database (SQLite/PostgreSQL)
 ```

+**Unified Commands:**
+- `insertr enhance` - Build-time content injection
+- `insertr serve` - Runtime API server  
+- Single binary handles both development and production workflows
+
 ### **Smart Loading Strategy**
 ```html
 <!-- Regular visitors: zero overhead -->
@@ -203,6 +201,60 @@ Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
 - **Zero configuration**: No schema files or content mappings
 - **Developer friendly**: Stay in HTML markup, no context switching

+## 🔧 Unified Binary Commands
+
+### **Build-Time Enhancement**
+```bash
+# Production build with remote API
+./insertr enhance src/ --output ./dist --api https://cms.example.com --api-key xyz
+
+# Development build with local database
+./insertr enhance demo-site/ --output ./dist --db ./content.db
+
+# Development build with mock data
+./insertr enhance demo-site/ --output ./dist --mock
+
+# Use justfile shortcuts
+just enhance                     # Default: demo-site/ → dist/ with mock data
+just enhance input="src" output="public"  # Custom paths
+```
+
+### **Runtime API Server**
+```bash
+# Production server with PostgreSQL
+./insertr serve --db "postgresql://user:pass@host:5432/dbname"
+
+# Development server with SQLite
+./insertr serve --dev-mode --port 8080 --db ./dev.db
+
+# Production server with custom config
+./insertr --config ./production.yaml serve
+
+# Use justfile shortcuts
+just serve                       # Development server on :8080
+just serve-prod port="443"       # Production server
+```
+
+### **Configuration Options**
+```bash
+# YAML configuration file
+./insertr --config ./custom.yaml [command]
+
+# Environment variables
+export INSERTR_DB_PATH="./content.db"
+export INSERTR_API_URL="https://api.example.com"
+export INSERTR_API_KEY="your-api-key"
+export INSERTR_SITE_ID="production"
+
+# Command-line flags (highest priority)
+./insertr --db ./custom.db --site-id staging serve --port 3000
+
+# Show all options
+./insertr --help
+./insertr enhance --help
+./insertr serve --help
+```
+
 ## 📚 Integration Examples

 ### **GitHub Actions Workflow**
@@ -249,23 +301,22 @@ Static Site Build → Insertr CLI Enhancement → Enhanced Deployment

 ### **Live Development with Hot Reload**
 ```bash
-# 🔥 Hot Reload: watches BOTH library AND CLI
+# 🔥 Hot Reload: watches BOTH library AND unified binary
 just air
-# or: cd insertr-cli && air

 # Alternative: Watch library only
 just watch
 # or: cd lib && npm run dev

-# Library changes: lib/src/**/*.js → Auto rebuild library + CLI
-# CLI changes: cmd/**/*.go → Auto rebuild CLI  
+# Library changes: lib/src/**/*.js → Auto rebuild library + binary
+# Binary changes: cmd/**/*.go, internal/**/*.go → Auto rebuild binary
 # Both trigger server restart with latest embedded assets
 # Visit localhost:3000 → Refresh to see changes
 ```

 **What Gets Hot Reloaded:**
 - JavaScript library changes (`lib/src/`)
- Go CLI changes (`insertr-cli/`)  
+- Go unified binary changes (`cmd/`, `internal/`)
 - Enhanced HTML output (real-time content injection)

 ### **Content ID Management**
@@ -276,14 +327,54 @@ just watch

 **Production Phase:**
 - Preserve existing content mappings for stability  
- CLI warns about orphaned content
+- Binary warns about orphaned content
 - Simple migration tools for structural changes

+## ⚙️ Configuration
+
+### **YAML Configuration (insertr.yaml)**
+```yaml
+# Database configuration
+database:
+  path: "./insertr.db"        # SQLite file or PostgreSQL connection string
+
+# API configuration (for remote content API)
+api:
+  url: ""                     # Content API URL (leave empty to use local database)
+  key: ""                     # API authentication key
+
+# Server configuration  
+server:
+  port: 8080                  # HTTP server port
+  dev_mode: false             # Enable development mode features
+
+# Build configuration
+build:
+  input: "./src"              # Default input directory
+  output: "./dist"            # Default output directory
+
+# Global settings
+site_id: "demo"              # Site ID for content lookup
+mock_content: false          # Use mock content instead of real data
+```
+
+### **Configuration Precedence**
+1. **CLI flags** (highest priority) - `./insertr --db ./custom.db serve`
+2. **Environment variables** - `INSERTR_DB_PATH=./custom.db`
+3. **YAML config file** - `insertr.yaml` or `--config custom.yaml`
+4. **Smart defaults** (lowest priority)
+
+### **Environment Variables**
+- `INSERTR_DB_PATH` - Database path
+- `INSERTR_API_URL` - Remote API URL  
+- `INSERTR_API_KEY` - API authentication key
+- `INSERTR_SITE_ID` - Site identifier
+
 ## 📖 Documentation

 - **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
 - **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
- **[Parser Documentation](insertr-cli/README.md)** - CLI usage and API reference
+- **[Integration Summary](INTEGRATION-SUMMARY.md)** - Complete architecture overview

 ## 🎯 Market Position: "The Tailwind of CMS"

@@ -303,6 +394,59 @@ just watch
 - Works with any framework or generator
 - Developer experience focused

+## ⚙️ Configuration
+
+### **YAML Configuration (insertr.yaml)**
+```yaml
+# Database configuration
+database:
+  path: "./insertr.db"  # SQLite file path or PostgreSQL connection string
+
+# API configuration (for remote content API)
+api:
+  url: ""               # Content API URL (leave empty to use local database)
+  key: ""               # API authentication key
+
+# Server configuration
+server:
+  port: 8080            # HTTP server port
+  dev_mode: false       # Enable development mode features
+
+# Build configuration
+build:
+  input: "./src"        # Default input directory for enhancement
+  output: "./dist"      # Default output directory for enhanced files
+
+# Global settings
+site_id: "demo"         # Default site ID for content lookup
+mock_content: false     # Use mock content instead of real data
+```
+
+### **Environment Variables**
+- `INSERTR_DB_PATH` - Database path override
+- `INSERTR_API_URL` - Remote API URL override  
+- `INSERTR_API_KEY` - API authentication key
+- `INSERTR_SITE_ID` - Site identifier override
+
+### **Configuration Precedence**
+1. **CLI flags** (highest priority)
+2. **Environment variables**
+3. **YAML config file**
+4. **Smart defaults** (lowest priority)
+
+### **Database Options**
+```bash
+# SQLite (development)
+./insertr serve --db "./content.db"
+
+# PostgreSQL (production)
+./insertr serve --db "postgresql://user:pass@host:5432/insertr"
+
+# Environment-based
+export INSERTR_DB_PATH="postgresql://prod-host/insertr"
+./insertr serve
+```
+
 ## 🤝 Contributing

 This project follows the "Tailwind philosophy" of developer-first design: