From ae9ae7e4421a7c848e119d75b24f8ecfd936c4ff Mon Sep 17 00:00:00 2001
From: Joakim <joakim@jnss.me>
Date: Wed, 10 Sep 2025 18:12:31 +0200
Subject: [PATCH] docs: update all documentation for unified binary
 architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

📚 **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
---
 COMMANDS.md              | 269 +++++++++++++++++++++++++++++++++++++++
 INTEGRATION-SUMMARY.md   | 138 +++++++++++++-------
 README.md                | 194 ++++++++++++++++++++++++----
 insertr-server/README.md | 109 +++++++++-------
 4 files changed, 593 insertions(+), 117 deletions(-)
 create mode 100644 COMMANDS.md

diff --git a/COMMANDS.md b/COMMANDS.md
new file mode 100644
index 0000000..c035cca
--- /dev/null
+++ b/COMMANDS.md
@@ -0,0 +1,269 @@
+# Insertr Command Reference
+
+Complete reference for the unified `insertr` binary commands, configuration, and usage patterns.
+
+## 🔧 Command Overview
+
+```bash
+insertr [global-flags] <command> [command-flags] [arguments]
+```
+
+## 📚 Global Flags
+
+Available for all commands:
+
+| Flag | Environment Variable | Description | Default |
+|------|---------------------|-------------|---------|
+| `--config` | N/A | Config file path | `./insertr.yaml` |
+| `--db` | `INSERTR_DB_PATH` | Database path or connection string | `./insertr.db` |
+| `--api-url` | `INSERTR_API_URL` | Remote content API URL | `""` |
+| `--api-key` | `INSERTR_API_KEY` | API authentication key | `""` |
+| `--site-id` | `INSERTR_SITE_ID` | Site identifier for content | `"demo"` |
+| `--help` | N/A | Show help information | N/A |
+| `--version` | N/A | Show version information | N/A |
+
+## 🔨 enhance Command
+
+Build-time content injection - processes HTML files and injects database content.
+
+```bash
+insertr enhance [input-dir] [flags]
+```
+
+### Arguments
+- `input-dir` - Directory containing HTML files to enhance (required)
+
+### Flags
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output`, `-o` | Output directory for enhanced files | `./dist` |
+| `--mock` | Use mock content for development | `true` |
+
+### Examples
+
+```bash
+# Basic enhancement with mock data
+./insertr enhance demo-site/
+
+# Production build with custom output
+./insertr enhance src/ --output ./build --mock=false
+
+# Use remote API for content  
+./insertr enhance src/ --api-url https://cms.example.com --api-key xyz123
+
+# Use local database
+./insertr enhance src/ --db ./content.db
+
+# Custom site ID
+./insertr enhance src/ --site-id production
+```
+
+### Content Sources Priority
+1. Remote API (if `--api-url` provided)
+2. Local database (if `--db` points to valid database)
+3. Mock content (if `--mock=true` or fallback)
+
+## 🔌 serve Command
+
+Runtime API server - provides HTTP endpoints for content management.
+
+```bash
+insertr serve [flags]
+```
+
+### Flags
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--port`, `-p` | HTTP server port | `8080` |
+| `--dev-mode` | Enable development mode features | `false` |
+
+### Examples
+
+```bash
+# Development server
+./insertr serve --dev-mode
+
+# Production server
+./insertr serve --port 80
+
+# Custom database
+./insertr serve --db ./production.db
+
+# PostgreSQL database
+./insertr serve --db "postgresql://user:pass@localhost:5432/insertr"
+
+# Custom configuration
+./insertr --config production.yaml serve
+```
+
+### API Endpoints
+
+When running `insertr serve`, these endpoints are available:
+
+#### Health Check
+- `GET /health` - Server health status
+
+#### Content Management
+- `GET /api/content?site_id={site}` - Get all content for site
+- `GET /api/content/{id}?site_id={site}` - Get single content item
+- `GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2}` - Get multiple items
+- `POST /api/content` - Create new content
+- `PUT /api/content/{id}` - Update existing content
+
+#### Version Control
+- `GET /api/content/{id}/versions?site_id={site}` - Get content history
+- `POST /api/content/{id}/rollback` - Rollback to previous version
+
+## ⚙️ Configuration
+
+### YAML Configuration File
+
+Default file: `insertr.yaml`
+
+```yaml
+# Database configuration
+database:
+  path: "./insertr.db"        # SQLite file or PostgreSQL connection
+
+# Remote API configuration  
+api:
+  url: ""                     # Content API URL
+  key: ""                     # API key
+
+# Server configuration
+server:
+  port: 8080                  # HTTP port
+  dev_mode: false             # Development mode
+
+# Build configuration
+build:
+  input: "./src"              # Default input directory
+  output: "./dist"            # Default output directory
+
+# Global settings
+site_id: "demo"              # Site identifier
+mock_content: false          # Use mock data
+```
+
+### Environment Variables
+
+All configuration can be set via environment variables:
+
+```bash
+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"
+
+./insertr serve
+```
+
+### Configuration Precedence
+
+1. **CLI flags** (highest priority)
+2. **Environment variables**
+3. **YAML configuration file**
+4. **Built-in defaults** (lowest priority)
+
+## 📋 Usage Patterns
+
+### Development Workflow
+
+```bash
+# Start full development environment
+just dev                     # Uses justfile for convenience
+
+# Manual development setup
+./insertr serve --dev-mode --db ./dev.db &
+npm run demo                 # Start demo site
+
+# Hot reload development
+air                         # Uses .air.toml configuration
+```
+
+### Production Deployment
+
+```bash
+# Build static site with content
+./insertr enhance ./src --output ./dist --api-url https://api.prod.com
+
+# Start production API server
+./insertr serve --db "postgresql://user:pass@db:5432/prod"
+
+# With custom configuration
+./insertr --config ./production.yaml serve
+```
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Build with Insertr
+  run: |
+    ./insertr enhance ./public --output ./dist
+    
+- name: Deploy enhanced site
+  uses: peaceiris/actions-gh-pages@v3
+  with:
+    publish_dir: ./dist
+```
+
+## 🚨 Error Handling
+
+### Common Issues
+
+**Database Connection Errors:**
+```bash
+# Check database path
+./insertr --db ./nonexistent.db serve
+# Error: failed to initialize database
+
+# Solution: Verify database path or use --mock for development
+./insertr serve --dev-mode  # Creates ./insertr.db automatically
+```
+
+**Port Already in Use:**
+```bash
+# Error: listen tcp :8080: bind: address already in use
+
+# Solution: Use different port
+./insertr serve --port 3001
+```
+
+**Missing Input Directory:**
+```bash
+# Error: Input directory does not exist
+
+# Solution: Verify path exists
+ls -la ./src
+./insertr enhance ./src
+```
+
+## 🔍 Debugging
+
+### Verbose Logging
+
+```bash
+# Enable development mode for more detailed output
+./insertr serve --dev-mode
+
+# Check server health
+curl http://localhost:8080/health
+```
+
+### Configuration Validation
+
+```bash
+# Test configuration loading
+./insertr --config ./test.yaml --help
+
+# Verify environment variables
+./insertr serve --help  # Shows resolved configuration values
+```
+
+---
+
+For more examples and integration patterns, see:
+- [Main README](README.md) - Getting started and overview
+- [Integration Summary](INTEGRATION-SUMMARY.md) - Architecture details
+- [Development Guide](DEVELOPMENT.md) - Contributing and setup
\ No newline at end of file
diff --git a/INTEGRATION-SUMMARY.md b/INTEGRATION-SUMMARY.md
index 7f9732c..9c706f3 100644
--- a/INTEGRATION-SUMMARY.md
+++ b/INTEGRATION-SUMMARY.md
@@ -1,83 +1,125 @@
-# Server Development Integration Complete ✅
+# Unified Binary Architecture Complete ✅
 
 ## 🎯 **What Was Accomplished**
 
-Successfully integrated the **insertr-server** into the development workflow, making **full-stack development the primary experience** while maintaining simplicity.
+Successfully refactored **insertr-cli** and **insertr-server** into a **unified `insertr` binary**, creating a **simpler, more maintainable architecture** while preserving all functionality.
 
-## 🚀 **Unified Development Experience**
+## 🚀 **Unified Binary Experience**
 
-### **Primary Commands**
+### **Single Binary Commands**
+```bash
+./insertr enhance   # 🔨 Build-time content injection
+./insertr serve     # 🔌 Runtime API server
+./insertr --help    # 📖 Complete command reference
+```
+
+### **Simplified Development**
 ```bash
 just dev         # 🔥 Full-stack development (PRIMARY)
-just demo-only   # Demo site only (special cases)
-just server      # API server only (development)
+just serve       # API server only (development)  
+just enhance     # Build-time enhancement only
 ```
 
 ### **Enhanced Build Pipeline**
 ```bash
-just build       # Now builds: Library + CLI + Server (all-in-one)
+just build       # Now builds: Library + Unified Binary (single executable)
 npm run build    # Same - builds complete stack via scripts/build.js
 ```
 
-### **Smart Development Features**
-- **Auto Server Detection**: Library detects development vs production environment
-- **Helpful Error Messages**: Clear guidance when API server isn't running
-- **Health Monitoring**: `just server-health` checks API server status
-- **Enhanced Status**: `just status` shows complete project state including server
+### **Smart Configuration**
+- **YAML Configuration**: `insertr.yaml` with smart defaults
+- **Environment Variables**: `INSERTR_*` prefix for all settings
+- **CLI Flag Precedence**: Command-line flags override config and env vars
+- **Database Flexibility**: SQLite for development, PostgreSQL for production
 
-## 📋 **Technical Integration Points**
+## 📋 **Technical Architecture Changes**
 
-### **1. Justfile Enhancements** 
-- Added server commands: `server`, `server-build`, `server-dev`, `server-health`
-- Added unified development: `dev-full` (orchestrates both demo + API server)
-- Enhanced status command with server information
+### **1. Unified Command Structure** 
+- **Single Binary**: `insertr` handles both enhance and serve operations
+- **Cobra CLI**: Professional command structure with subcommands
+- **Viper Configuration**: YAML + environment + CLI flag precedence
+- **Shared Database Layer**: Single source of truth for content models
 
-### **2. Build Script Integration**
-- `scripts/build.js` now builds server binary alongside library and CLI
-- Integrated server build into main `npm run build` workflow
-- Enhanced completion messages with server usage instructions
+### **2. Preserved Database Architecture**
+- **sqlc Code Generation**: Maintained type-safe database operations
+- **Multi-Database Support**: SQLite (development) and PostgreSQL (production)
+- **Version Control System**: Complete edit history with rollback capabilities
+- **Database Abstraction**: Runtime database type detection
 
-### **3. Smart API Client**
-- Environment detection (localhost = development server, production = same-origin)
-- Helpful error messages when server unreachable
-- Development logging for API configuration
-- Graceful fallback behavior
+### **3. Enhanced Build Integration**
+- `scripts/build.js` builds unified binary with embedded library assets
+- `justfile` updated for unified binary commands
+- `Air` configuration for hot reload during development
+- Single binary deployment for all use cases
 
-### **4. Enhanced Developer Experience**
-- `npm run dev:check` validates server components
-- Clear development workflow guidance
-- Integrated help messages pointing to `just dev-full`
+### **4. Configuration Flexibility**
+- **YAML Config**: `insertr.yaml` for declarative configuration
+- **Environment Variables**: `INSERTR_*` prefixed for all settings
+- **CLI Precedence**: Command flags override file and env config
+- **Smart Defaults**: Zero-configuration development workflow
 
 ## 🔄 **Simplified Development Workflow**
 
 ### **Primary Development (Default)**
 ```bash
 just dev         # or npm run dev
-# Starts: API server (8080) + Demo site (3000)  
-# Complete CMS experience with real content persistence
+# Starts: insertr serve (8080) + Demo site (3000)  
+# Complete CMS experience with unified binary
 ```
 
-### **Component Development (Special Cases)**
+### **Build-Time Enhancement**
 ```bash
-just server      # API server only
-just demo-only   # Demo site only (no persistence)
+just enhance     # Build-time content injection
+./insertr enhance demo-site/ --output ./dist --mock
+./insertr enhance src/ --api https://cms.example.com
 ```
 
-## ✅ **Verification**
+### **Production Deployment**
+```bash
+./insertr serve --db "postgresql://user:pass@host/db"
+./insertr --config production.yaml serve
+```
 
-All integration points tested and working:
-- ✅ Server builds via `just build`
-- ✅ Full-stack development via `just dev` 
-- ✅ API client detects environment correctly
-- ✅ Enhanced status and check commands work
-- ✅ Clean, focused development experience
+## ✅ **Migration Benefits Achieved**
+
+All functionality preserved with architectural improvements:
+- ✅ **Single Binary**: No more separate CLI and server binaries
+- ✅ **Shared Codebase**: Database models, validation, and logic unified
+- ✅ **Flexible Configuration**: YAML, environment, and CLI flag support
+- ✅ **Development Workflow**: Hot reload with `air` for unified binary
+- ✅ **Production Ready**: Same binary handles build-time and runtime
+- ✅ **Database Architecture**: Preserved sophisticated sqlc multi-DB setup
+
+## 🏗️ **Architecture Diagram**
+
+### **Before: Separate Binaries**
+```
+insertr-cli/     insertr-server/
+     ↓                ↓
+  enhance          serve
+     ↓                ↓
+  Build-time      Runtime
+```
+
+### **After: Unified Binary**
+```
+       insertr
+      ↙        ↘
+   enhance    serve
+      ↓         ↓
+  Build-time Runtime
+      ↓         ↓
+   Same Database Layer
+   Same Configuration
+   Same Content Models
+```
 
 ## 🎉 **Result**
 
-The development experience is now **simplified and powerful**:
-- **Full-stack by default** - complete CMS experience from day one
-- **Clean command structure** - no confusion about workflows  
-- **Professional tooling** - integrated build, status, and health checking
-- **Ready for production** - complete stack with database persistence
+The architecture is now **unified and maintainable**:
+- **Single Source of Truth** - No duplicate database or content logic
+- **Simplified Deployment** - One binary for all use cases  
+- **Better Developer Experience** - Consistent configuration and commands
+- **Production Flexibility** - Build-time enhancement OR runtime API OR both
 
-**Insertr is now a complete, production-ready CMS!** 🚀
\ No newline at end of file
+**Insertr unified binary is production-ready with improved maintainability!** 🚀
\ No newline at end of file
diff --git a/README.md b/README.md
index ebecc79..ca36d3b 100644
--- 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:
diff --git a/insertr-server/README.md b/insertr-server/README.md
index 86e98a3..aa649bc 100644
--- a/insertr-server/README.md
+++ b/insertr-server/README.md
@@ -1,8 +1,23 @@
-# Insertr Content Server
+# ⚠️ Deprecated: Insertr Content Server
 
-REST API server for the Insertr CMS system. Provides content management with version control and user attribution.
+> **This standalone server has been replaced by the unified `insertr` binary.**  
+> **Please see the [main README](../README.md) for updated instructions.**
 
-## Features
+## 🔄 Migration to Unified Binary
+
+The Insertr Content Server functionality has been integrated into the unified `insertr` binary. Instead of running a separate server binary, use:
+
+```bash
+# Old approach (deprecated)
+./insertr-server --port 8080
+
+# New unified approach
+./insertr serve --port 8080 --dev-mode
+```
+
+## ✅ All Features Preserved
+
+The unified binary includes all server functionality:
 
 - **Content Management**: Full CRUD operations for content items
 - **Version Control**: Complete edit history with rollback functionality  
@@ -10,9 +25,9 @@ REST API server for the Insertr CMS system. Provides content management with ver
 - **Type-Safe Database**: Uses sqlc for generated Go code from SQL
 - **SQLite & PostgreSQL**: Database flexibility for development to production
 
-## API Endpoints
+## 🚀 Updated API Endpoints
 
-### Content Operations
+### Content Operations (Unchanged)
 - `GET /api/content?site_id={site}` - Get all content for a site
 - `GET /api/content/{id}?site_id={site}` - Get single content item
 - `GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2}` - Get multiple content items
@@ -20,16 +35,32 @@ REST API server for the Insertr CMS system. Provides content management with ver
 - `PUT /api/content/{id}?site_id={site}` - Update existing content  
 - `DELETE /api/content/{id}?site_id={site}` - Delete content
 
-### Version Control
+### Version Control (Unchanged)
 - `GET /api/content/{id}/versions?site_id={site}` - Get version history
 - `POST /api/content/{id}/rollback?site_id={site}` - Rollback to specific version
 
-### Health & Status
+### Health & Status (Unchanged)
 - `GET /health` - Server health check
 
-## User Attribution
+## 🚀 New Quick Start (Unified Binary)
 
-All content operations support user attribution via the `X-User-ID` header:
+```bash
+# Build unified binary (from project root)
+go build -o insertr .
+
+# Start server with development mode
+./insertr serve --dev-mode --port 8080
+
+# Start production server  
+./insertr serve --port 8080 --db "postgresql://user:pass@host/db"
+
+# Check health (same endpoint)
+curl http://localhost:8080/health
+```
+
+## User Attribution (Unchanged)
+
+All content operations still support user attribution via the `X-User-ID` header:
 
 ```bash
 curl -X PUT "http://localhost:8080/api/content/hero-title?site_id=demo" \
@@ -38,39 +69,30 @@ curl -X PUT "http://localhost:8080/api/content/hero-title?site_id=demo" \
   -d '{"value": "Updated content"}'
 ```
 
-## Quick Start
+## 🛠️ Development (Updated for Unified Binary)
 
-```bash
-# Build server
-go build -o insertr-server ./cmd/server
-
-# Start server
-./insertr-server --port 8080
-
-# Check health
-curl http://localhost:8080/health
-```
-
-## Development
-
-### Using sqlc
+### Using sqlc (From Project Root)
 
 ```bash
 # Install sqlc
 go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
 
-# Generate Go code from SQL
+# Generate Go code from SQL (from project root)
 sqlc generate
 
-# Build with generated code
-go build ./cmd/server
+# Build unified binary
+go build -o insertr .
+
+# Development with hot reload
+just dev        # Full-stack development
+air             # Hot reload unified binary only
 ```
 
-### Database Schema
+### Database Schema (Location Updated)
 
-See `db/schema/schema.sql` for the complete schema. Key tables:
+See `db/sqlite/schema.sql` and `db/postgresql/schema.sql` for database-specific schemas. Key tables:
 
-- `content` - Current content versions
+- `content` - Current content versions  
 - `content_versions` - Complete version history
 
 ### Example Version Control Workflow
@@ -103,21 +125,20 @@ curl -X POST "http://localhost:8080/api/content/hero-title/rollback?site_id=demo
   -d '{"version_id": 1}'
 ```
 
-## Configuration
+---
 
-### Environment Variables
-- `PORT` - Server port (default: 8080)
-- `DB_PATH` - SQLite database file path (default: ./insertr.db)
+## 📖 For Complete Documentation
 
-### Command Line Flags
-```bash
-./insertr-server --help
-```
+**➡️ See the [main README](../README.md) for:**
+- Unified binary installation and usage
+- Complete configuration options (YAML, environment variables, CLI flags)
+- Development workflow with `just dev`
+- Production deployment guidance
+- Full architecture documentation
 
-## Production Deployment
+**➡️ See [INTEGRATION-SUMMARY.md](../INTEGRATION-SUMMARY.md) for:**
+- Technical architecture details
+- Database schema information  
+- API integration examples
 
-1. **Database**: Consider PostgreSQL for production scale
-2. **Authentication**: Integrate with your auth system via middleware
-3. **CORS**: Configure appropriate CORS policies
-4. **SSL**: Serve over HTTPS
-5. **Monitoring**: Add logging and metrics collection
\ No newline at end of file
+The unified `insertr` binary provides all server functionality with improved developer experience and simplified deployment.
\ No newline at end of file