diff --git a/wiki/Documentation-Index.md b/wiki/Documentation-Index.md
index 3ecd035..4856cec 100644
--- a/wiki/Documentation-Index.md
+++ b/wiki/Documentation-Index.md
@@ -69,6 +69,12 @@ This directory contains comprehensive documentation for the DevStack Core projec
   - Performance metrics and security validation
   - Production readiness assessment
 
+- **[NEW_TESTS_SUMMARY.md](./NEW_TESTS_SUMMARY.md)** - Extended test suite summary
+  - New test suites added to the project
+  - Coverage of Vault, PostgreSQL, PgBouncer, Observability
+  - 40+ new test cases across 4 suites
+  - Test statistics and implementation details
+
 ### Architecture & Design
 
 - **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Complete architecture deep-dive
@@ -188,7 +194,7 @@ This directory contains comprehensive documentation for the DevStack Core projec
 
 ### API Development Patterns
 
-- **[../reference-apps/API_PATTERNS.md](../reference-apps/API_PATTERNS.md)** - API design patterns
+- **[.API-Patterns](.API-Patterns)** - API design patterns
   - Code-first vs API-first development
   - Pattern implementations
   - Synchronization strategies
@@ -206,21 +212,21 @@ This directory contains comprehensive documentation for the DevStack Core projec
 
 Located in the project root and `.github/`:
 - [README.md](../README.md) - Main project documentation
-- [CONTRIBUTING.md](../.github/CONTRIBUTING.md) - Contribution guidelines
-- [SECURITY.md](../.github/SECURITY.md) - Security policy and reporting
+- [CONTRIBUTING.md](../Contributing-Guide) - Contribution guidelines
+- [SECURITY.md](../Secrets-Rotation) - Security policy and reporting
 - [CODE_OF_CONDUCT.md](../.github/CODE_OF_CONDUCT.md) - Community standards
-- [CHANGELOG.md](../.github/CHANGELOG.md) - Version history
+- [CHANGELOG.md](../Changelog) - Version history
 
 ### Component Documentation
 
 - **Reference Applications**
-  - [Reference Apps Overview](../reference-apps/README.md)
+  - [Reference Apps Overview](.Development-Workflow)
   - [FastAPI Code-First](../reference-apps/fastapi/README.md)
   - [FastAPI API-First](../reference-apps/fastapi-api-first/README.md)
   - [Go Reference API](../reference-apps/golang/README.md)
   - [Node.js Reference API](../reference-apps/nodejs/README.md)
   - [Rust Reference API](../reference-apps/rust/README.md)
-  - [API Patterns](../reference-apps/API_PATTERNS.md)
+  - [API Patterns](.API-Patterns)
 
 - **Testing Infrastructure**
   - [Tests Overview](../tests/README.md)
@@ -268,14 +274,14 @@ Core documentation files are automatically synced from `docs/` to `wiki/` direct
   - `docs/ARCHITECTURE.md` → `wiki/Architecture-Overview.md`
   - `docs/SERVICE_CATALOG.md` → `wiki/Service-Catalog.md`
   - `README.md` → `wiki/Home.md`
-  - `.github/CHANGELOG.md` → `wiki/Changelog.md`
+  - `Changelog` → `wiki/Changelog.md`
   - And other core documentation files
 
 **Important:** Always update the source file in `docs/`, not the wiki copy. Changes only reach `main` via merged PRs, which trigger the wiki sync workflow.
 
 ## Contributing to Documentation
 
-See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for guidelines on:
+See [CONTRIBUTING.md](../Contributing-Guide) for guidelines on:
 - Documentation style guide
 - Review process
 - Testing documentation changes
@@ -341,13 +347,13 @@ See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for guidelines on:
 
 - **Monthly:** Review for accuracy
 - **Quarterly:** Update test results
-- **Per Release:** Update .github/CHANGELOG.md
+- **Per Release:** Update Changelog
 - **As Needed:** Security documentation
 
 ## Need Help?
 
 - 📖 Start with [README.md](../README.md)
-- 🔒 Security questions? See [SECURITY.md](../.github/SECURITY.md)
+- 🔒 Security questions? See [SECURITY.md](../Secrets-Rotation)
 - 🧪 Testing questions? See [tests/README.md](../tests/README.md)
-- 🚀 API questions? See [reference-apps/README.md](../reference-apps/README.md)
-- 🤝 Want to contribute? See [CONTRIBUTING.md](../.github/CONTRIBUTING.md)
+- 🚀 API questions? See [reference-apps/README.md](.Development-Workflow)
+- 🤝 Want to contribute? See [CONTRIBUTING.md](../Contributing-Guide)
diff --git a/wiki/Home.md b/wiki/Home.md
index c0966bd..50f258d 100644
--- a/wiki/Home.md
+++ b/wiki/Home.md
@@ -14,15 +14,15 @@ A comprehensive, self-contained development environment providing Git hosting (F
 ## ✨ Key Features
 
 - **🚀 [Complete Infrastructure](#️-architecture)** - Everything you need: Git, databases, caching, messaging, secrets, observability
-- **🎯 [Service Profiles](./docs/SERVICE_PROFILES.md)** - Choose your stack: minimal (2GB), standard (4GB), or full (6GB) with observability
+- **🎯 [Service Profiles](Service-Configuration)** - Choose your stack: minimal (2GB), standard (4GB), or full (6GB) with observability
 - **🍎 [Apple Silicon Optimized](#-prerequisites)** - Native ARM64 support via Colima's Virtualization.framework
-- **🔒 [Vault-First Security](./docs/VAULT.md)** - All credentials managed by HashiCorp Vault with AppRole authentication
+- **🔒 [Vault-First Security](Vault-Integration)** - All credentials managed by HashiCorp Vault with AppRole authentication
 - **🛡️ [AppRole Authentication](#-security--approle-authentication)** - Zero hardcoded secrets, least-privilege access for all core services
 - **🔐 [TLS/SSL Support](./docs/TLS_CERTIFICATE_MANAGEMENT.md)** - Dual-mode TLS with automated certificate generation via Vault PKI
 - **📦 [Zero Cloud Dependencies](#-zero-cloud-dependencies)** - Runs entirely on your Mac, perfect for offline development
-- **🛠️ [Easy Management](./docs/PYTHON_MANAGEMENT_SCRIPT.md)** - Single CLI script with 21 commands for all operations
-- **📚 [Reference Apps](./reference-apps/README.md)** - Production-quality examples in Python, Go, Node.js, TypeScript, and Rust
-- **🔍 [Full Observability](./docs/OBSERVABILITY.md)** - Built-in Prometheus, Grafana, and Loki for monitoring and logging
+- **🛠️ [Easy Management](CLI-Reference)** - Single CLI script with 21 commands for all operations
+- **📚 [Reference Apps](Development-Workflow)** - Production-quality examples in Python, Go, Node.js, TypeScript, and Rust
+- **🔍 [Full Observability](Health-Monitoring)** - Built-in Prometheus, Grafana, and Loki for monitoring and logging
 
 ## 🚀 Quick Start
 
@@ -109,7 +109,7 @@ Choose the profile that fits your needs:
 ./devstack health
 ```
 
-**See [Service Profiles Guide](./docs/SERVICE_PROFILES.md) for detailed information.**
+**See [Service Profiles Guide](Service-Configuration) for detailed information.**
 
 ## 🛡️ Security & AppRole Authentication
 
@@ -170,7 +170,7 @@ curl -X POST $VAULT_ADDR/v1/auth/approle/login \
 # 6. Start service with fetched credentials
 ```
 
-**See [Vault Integration Guide](./docs/VAULT.md) for complete details.**
+**See [Vault Integration Guide](Vault-Integration) for complete details.**
 
 ## 🏗️ Architecture
 
@@ -217,13 +217,13 @@ All reference apps demonstrate:
 - Health checks and metrics
 - TLS/SSL support
 
-**See [Reference Apps Overview](./reference-apps/README.md) for details.**
+**See [Reference Apps Overview](Development-Workflow) for details.**
 
 ## 💻 Usage
 
 ### Management Commands
 
-The `devstack` script provides all essential operations:
+The `manage-devstack` script provides all essential operations:
 
 ```bash
 # Service management
@@ -391,40 +391,40 @@ DevStack Core is optimized for **local development** while maintaining patterns
 ## 📚 Documentation
 
 ### Getting Started
-- **[Installation Guide](./docs/INSTALLATION.md)** - Comprehensive setup with troubleshooting
-- **[Quick Start Tutorial](./docs/USAGE.md)** - Step-by-step usage guide
-- **[Service Profiles](./docs/SERVICE_PROFILES.md)** - Profile selection and configuration
+- **[Installation Guide](Installation)** - Comprehensive setup with troubleshooting
+- **[Quick Start Tutorial](Quick-Start-Guide)** - Step-by-step usage guide
+- **[Service Profiles](Service-Configuration)** - Profile selection and configuration
 
 ### Core Documentation
-- **[Architecture Overview](./docs/ARCHITECTURE.md)** - System design with diagrams
-- **[Services Guide](./docs/SERVICES.md)** - Detailed service configurations
-- **[Management Script](./docs/MANAGEMENT.md)** - Complete CLI reference
-- **[Python CLI Guide](./docs/PYTHON_MANAGEMENT_SCRIPT.md)** - Modern Python CLI documentation
+- **[Architecture Overview](Architecture-Overview)** - System design with diagrams
+- **[Services Guide](Service-Overview)** - Detailed service configurations
+- **[Management Script](Management-Commands)** - Complete CLI reference
+- **[Python CLI Guide](CLI-Reference)** - Modern Python CLI documentation
 
 ### Infrastructure
-- **[Vault Integration](./docs/VAULT.md)** - PKI setup and secrets management
-- **[Redis Cluster](./docs/REDIS.md)** - Cluster architecture and operations
-- **[Observability Stack](./docs/OBSERVABILITY.md)** - Prometheus, Grafana, Loki setup
+- **[Vault Integration](Vault-Integration)** - PKI setup and secrets management
+- **[Redis Cluster](Redis-Cluster)** - Cluster architecture and operations
+- **[Observability Stack](Health-Monitoring)** - Prometheus, Grafana, Loki setup
 
 ### Development
-- **[Reference Apps Overview](./reference-apps/README.md)** - Multi-language examples
-- **[Best Practices](./docs/BEST_PRACTICES.md)** - Development patterns
+- **[Reference Apps Overview](Development-Workflow)** - Multi-language examples
+- **[Best Practices](Best-Practices)** - Development patterns
 - **[Testing Guide](./tests/README.md)** - Testing infrastructure
 - **[Test Coverage](./tests/TEST_COVERAGE.md)** - Coverage metrics (571+ tests across 4 test suites)
-- **[Testing Approach](./docs/TESTING_APPROACH.md)** - Best practices for running tests
+- **[Testing Approach](Testing-Guide)** - Best practices for running tests
 - **[Task 2.1 Testing](./docs/.private/TASK_2.1_TESTING.md)** - Backup system test suite (63 tests)
 
 ### Operations
-- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Performance Tuning](./docs/PERFORMANCE_TUNING.md)** - Optimization strategies
-- **[Disaster Recovery](./docs/DISASTER_RECOVERY.md)** - Backup and restore procedures
-- **[Security Assessment](./docs/SECURITY_ASSESSMENT.md)** - Security hardening
+- **[Troubleshooting](Common-Issues)** - Common issues and solutions
+- **[Performance Tuning](Debugging-Techniques)** - Optimization strategies
+- **[Disaster Recovery](Disaster-Recovery)** - Backup and restore procedures
+- **[Security Assessment](Certificate-Management)** - Security hardening
 
 ### Project
-- **[FAQ](./docs/FAQ.md)** - Frequently asked questions
-- **[Changelog](./.github/CHANGELOG.md)** - Version history
-- **[Contributing](./.github/CONTRIBUTING.md)** - Contribution guidelines
-- **[Security Policy](./.github/SECURITY.md)** - Security reporting
+- **[FAQ](FAQ)** - Frequently asked questions
+- **[Changelog](./Changelog)** - Version history
+- **[Contributing](./Contributing-Guide)** - Contribution guidelines
+- **[Security Policy](./Secrets-Rotation)** - Security reporting
 
 ## 🤝 Contributing
 
@@ -446,7 +446,7 @@ We welcome contributions! Here's how to get started:
 - Use conventional commit messages
 - Ensure CI/CD checks pass
 
-**See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for detailed guidelines.**
+**See [CONTRIBUTING.md](./Contributing-Guide) for detailed guidelines.**
 
 ## 🐛 Issues and Support
 
@@ -457,8 +457,8 @@ We welcome contributions! Here's how to get started:
 - System information (OS, Colima version, etc.)
 
 **Need help?**
-1. Check the [FAQ](./docs/FAQ.md)
-2. Review [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
+1. Check the [FAQ](FAQ)
+2. Review [Troubleshooting Guide](Common-Issues)
 3. Search [existing issues](https://github.com/NormB/devstack-core/issues)
 4. Ask in [Discussions](https://github.com/NormB/devstack-core/discussions)
 
@@ -485,7 +485,7 @@ Built with excellent open-source software:
 - [Prometheus](https://prometheus.io/) - Monitoring system
 - [Grafana](https://grafana.com/) - Observability platform
 
-**See complete list:** [ACKNOWLEDGEMENTS.md](./docs/ACKNOWLEDGEMENTS.md)
+**See complete list:** [ACKNOWLEDGEMENTS.md](Acknowledgements)
 
 ---
 
diff --git a/wiki/Installation.md b/wiki/Installation.md
index 9b47d4b..d4ff0e0 100644
--- a/wiki/Installation.md
+++ b/wiki/Installation.md
@@ -737,9 +737,31 @@ tail -5 .env
 
 **What Just Happened:**
 1. **Vault configured** a secrets storage system
-2. **25-character random passwords** generated for each service
-3. **Passwords stored securely** in Vault (not in plain text files)
-4. **TLS certificate system** set up (for HTTPS connections)
+2. **AppRole authentication enabled** - Each service gets its own role-id and secret-id
+3. **Service policies created** - PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ, Forgejo
+4. **AppRole credentials stored** in `~/.config/vault/approles/<service>/role-id` and `secret-id`
+5. **25-character random passwords** generated for each service
+6. **Passwords stored securely** in Vault (not in plain text files)
+7. **TLS certificate system** set up (for HTTPS connections)
+
+**AppRole Authentication:**
+- **role-id**: Identifies which service is connecting (like a username)
+- **secret-id**: Proves the service is authorized (like a password)
+- **Service tokens**: Short-lived (1 hour) tokens generated from AppRole login
+- **Least privilege**: Each service can only access its own credentials
+
+**Where Credentials Are Stored:**
+```
+~/.config/vault/
+├── approles/
+│   ├── postgres/role-id    # PostgreSQL AppRole credentials
+│   ├── postgres/secret-id
+│   ├── mysql/role-id       # MySQL AppRole credentials
+│   ├── mysql/secret-id
+│   └── ...                 # (7 services total with AppRole)
+├── ca/                     # TLS certificates
+└── root-token              # Vault root token (for management)
+```
 
 **7.2 Restart Services to Load Credentials:**
 
diff --git a/wiki/Service-Configuration.md b/wiki/Service-Configuration.md
index 94b0c9a..8d4632d 100644
--- a/wiki/Service-Configuration.md
+++ b/wiki/Service-Configuration.md
@@ -566,34 +566,178 @@ curl http://localhost:8003/health  # Node.js Express
 
 ## Environment Variable Overrides
 
-Each profile can have environment overrides in `configs/profiles/`:
-
-**configs/profiles/minimal.env:**
-```bash
-# Redis single-node mode
-REDIS_CLUSTER_ENABLED=false
-
-# Reduced health check intervals (faster startup)
-POSTGRES_HEALTH_INTERVAL=30s
-VAULT_HEALTH_INTERVAL=30s
-```
-
-**configs/profiles/standard.env:**
-```bash
-# Redis cluster mode
-REDIS_CLUSTER_ENABLED=true
-
-# Standard health checks
-POSTGRES_HEALTH_INTERVAL=60s
-```
-
-**configs/profiles/full.env:**
-```bash
-# Include all observability features
-ENABLE_METRICS=true
-ENABLE_LOGS=true
-PROMETHEUS_SCRAPE_INTERVAL=15s
-```
+Each profile has specific environment variable overrides in `configs/profiles/`. These files customize service behavior based on the profile's use case and resource constraints.
+
+### Profile Configuration Files
+
+- `configs/profiles/minimal.env` - Essential services (5 containers, ~2GB RAM)
+- `configs/profiles/standard.env` - Full dev stack (12 containers, ~4GB RAM)
+- `configs/profiles/full.env` - Complete with observability (18 containers, ~6GB RAM)
+- `configs/profiles/reference.env` - Reference APIs addon (~+1GB RAM)
+
+### Redis Configuration Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `REDIS_CLUSTER_ENABLED` | `false` | `true` | `true` | Minimal uses single Redis instance | Cluster provides HA & sharding |
+| `REDIS_CLUSTER_INIT_REQUIRED` | `false` | `true` | `true` | No cluster init needed for single node | Standard/full require cluster setup |
+| `REDIS_MAX_MEMORY` | `128mb` | `256mb` | `256mb` | Lower memory for single instance | Per-node allocation |
+| `REDIS_HEALTH_INTERVAL` | `30s` | `60s` | `60s` | Faster checks for quicker startup | Standard intervals for production-like |
+
+### PostgreSQL Configuration Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `POSTGRES_MAX_CONNECTIONS` | `50` | `100` | `100` | Fewer services in minimal | Standard supports more clients |
+| `POSTGRES_SHARED_BUFFERS` | `128MB` | `256MB` | `256MB` | Reduced memory allocation | Smaller buffer cache |
+| `POSTGRES_EFFECTIVE_CACHE_SIZE` | `512MB` | `1GB` | `1GB` | Conservative estimate | Query planner optimization |
+| `POSTGRES_WORK_MEM` | `4MB` | `8MB` | `8MB` | Smaller per-operation memory | Sort/hash operation capacity |
+| `POSTGRES_ENABLE_TLS` | `false` | `false` | `false` | Local dev simplicity | TLS optional for all |
+| `POSTGRES_HEALTH_INTERVAL` | `30s` | `60s` | `60s` | Faster startup feedback | Standard production-like |
+| `POSTGRES_MEMORY_LIMIT` | `1G` | `2G` | `2G` | Docker resource constraint | Container memory cap |
+| `POSTGRES_MEMORY_RESERVATION` | `256M` | `512M` | `512M` | Guaranteed minimum | Reserved memory |
+| `POSTGRES_CPU_LIMIT` | `1.5` | `2` | `2` | CPU allocation | Max CPU cores |
+
+### Resource Limits Comparison
+
+| Service | Minimal Memory | Standard Memory | Full Memory | Why Different |
+|---------|---------------|-----------------|-------------|---------------|
+| **PostgreSQL** | 1G limit / 256M reserved | 2G limit / 512M reserved | 2G limit / 512M reserved | More connections/workload |
+| **MySQL** | Not included | 1G limit / 256M reserved | 1G limit / 256M reserved | Only in standard+ |
+| **MongoDB** | Not included | 1G limit / 256M reserved | 1G limit / 256M reserved | Only in standard+ |
+| **Redis (per node)** | 256M limit / 128M reserved | 512M limit / 256M reserved | 512M limit / 256M reserved | Cluster needs more memory |
+| **RabbitMQ** | Not included | 512M limit / 256M reserved | 512M limit / 256M reserved | Only in standard+ |
+| **Vault** | 256M limit / 128M reserved | 512M limit / 128M reserved | 512M limit / 128M reserved | Minimal secrets workload |
+| **Forgejo** | 512M limit / 256M reserved | 1G limit / 256M reserved | 1G limit / 256M reserved | Git server needs more |
+| **Prometheus** | Not included | Not included | 1G limit / 512M reserved | Only in full |
+| **Grafana** | Not included | Not included | 512M limit / 256M reserved | Only in full |
+| **Loki** | Not included | Not included | 512M limit / 256M reserved | Only in full |
+
+### Health Check Configuration Comparison
+
+| Service | Minimal Interval | Standard Interval | Full Interval | Why Different | Impact |
+|---------|------------------|-------------------|---------------|---------------|--------|
+| **Vault** | 30s | 60s | 60s | Faster startup validation | More frequent checks |
+| **PostgreSQL** | 30s | 60s | 60s | Quick feedback loop | Faster detection |
+| **Redis** | 30s | 60s | 60s | Lightweight checks | Minimal overhead |
+| **Forgejo** | 30s | 60s | 60s | Faster ready state | Quick startup |
+| **MySQL** | N/A | 60s | 60s | Only in standard+ | Standard interval |
+| **MongoDB** | N/A | 60s | 60s | Only in standard+ | Standard interval |
+| **RabbitMQ** | N/A | 60s | 60s | Only in standard+ | Standard interval |
+| **Prometheus** | N/A | N/A | 30s | Only in full, lighter | Monitoring service |
+| **Grafana** | N/A | N/A | 30s | Only in full, lighter | UI service |
+
+### Logging Configuration Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `LOG_LEVEL` | `info` | `info` | `info` | Consistent logging | Balanced verbosity |
+| `DOCKER_LOG_MAX_SIZE` | `5m` | `10m` | `20m` | Log retention | Disk space usage |
+| `DOCKER_LOG_MAX_FILE` | `2` | `3` | `5` | File rotation | Total log history |
+| `LOG_FORMAT` | Not set | Not set | `json` | Structured for observability | Loki integration |
+| `LOG_TIMESTAMPS` | Not set | Not set | `true` | Timestamp correlation | Log analysis |
+
+### Feature Flags Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `ENABLE_METRICS` | `false` | `false` | `true` | No Prometheus in minimal/standard | Metrics collection |
+| `ENABLE_LOGS` | `false` | `false` | `true` | No Loki in minimal/standard | Log aggregation |
+| `ENABLE_TLS` | `false` | `false` | `false` | Simplified for dev | Local only |
+| `ENABLE_OBSERVABILITY` | `false` | `false` | `true` | No Vector in minimal/standard | Pipeline processing |
+| `ENABLE_CONTAINER_MONITORING` | `false` | `false` | `true` | No cAdvisor in minimal/standard | Container metrics |
+| `ENABLE_REDIS_EXPORTERS` | `false` | `false` | `true` | No exporters in minimal/standard | Redis metrics |
+
+### PgBouncer Configuration Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `PGBOUNCER_DEFAULT_POOL_SIZE` | `5` | `10` | `10` | Fewer connections needed | Pool capacity |
+| `PGBOUNCER_MAX_CLIENT_CONN` | `25` | `100` | `100` | Limited client count | Connection limit |
+| `PGBOUNCER_MAX_DB_CONNECTIONS` | `10` | `20` | `20` | Total backend connections | PostgreSQL load |
+
+### Backup Configuration Comparison
+
+| Variable | Minimal | Standard | Full | Why Different | Impact |
+|----------|---------|----------|------|---------------|--------|
+| `BACKUP_RETENTION_DAYS` | `7` | `14` | `30` | Storage optimization | Disk usage |
+| `BACKUP_SCHEDULE` | `0 2 * * 0` (weekly) | `0 2 * * *` (daily) | `0 2 * * *` (daily) | Less frequent for minimal | Backup frequency |
+| `BACKUP_COMPRESSION` | `true` | `true` | `true` | Save disk space | File size |
+| `BACKUP_POSTGRES` | `true` | `true` | `true` | All profiles | Data safety |
+| `BACKUP_MYSQL` | `false` | `true` | `true` | Not in minimal | Service presence |
+| `BACKUP_MONGODB` | `false` | `true` | `true` | Not in minimal | Service presence |
+| `BACKUP_PROMETHEUS` | `false` | `false` | `true` | Only full has metrics | Metrics retention |
+| `BACKUP_GRAFANA` | `false` | `false` | `true` | Only full has dashboards | Dashboard config |
+
+### Observability Configuration (Full Profile Only)
+
+| Variable | Value | Purpose | Impact |
+|----------|-------|---------|--------|
+| `PROMETHEUS_SCRAPE_INTERVAL` | `15s` | Metrics collection frequency | Data granularity |
+| `PROMETHEUS_EVALUATION_INTERVAL` | `15s` | Alert evaluation frequency | Alert latency |
+| `PROMETHEUS_RETENTION_TIME` | `15d` | Metrics storage duration | Disk usage |
+| `PROMETHEUS_RETENTION_SIZE` | `10GB` | Max storage size | Disk space limit |
+| `LOKI_RETENTION_PERIOD` | `744h` (31 days) | Log storage duration | Disk usage |
+| `LOKI_CHUNK_TARGET_SIZE` | `1572864` | Chunk compression | Storage efficiency |
+| `VECTOR_LOG_LEVEL` | `info` | Pipeline logging | Debug verbosity |
+| `CADVISOR_HOUSEKEEPING_INTERVAL` | `30s` | Container stats collection | CPU overhead |
+| `REDIS_EXPORTER_SCRAPE_INTERVAL` | `15s` | Redis metrics frequency | Network overhead |
+
+### Reference Profile Configuration (Addon)
+
+| Variable | Value | Purpose | Impact |
+|----------|-------|---------|--------|
+| `ENABLE_REFERENCE_APPS` | `true` | Enable APIs | Service startup |
+| `REFERENCE_API_LOG_LEVEL` | `info` | Application logging | Log volume |
+| `REFERENCE_API_ENABLE_METRICS` | `true` | Prometheus metrics | Metrics endpoints |
+| `REFERENCE_API_ENABLE_TLS` | `true` | HTTPS endpoints | Certificate usage |
+| `REFERENCE_API_STRUCTURED_LOGGING` | `true` | JSON logging | Log parsing |
+| `FASTAPI_WORKERS` | `4` | Uvicorn workers | CPU usage |
+| `GOLANG_API_LOG_LEVEL` | `info` | Go service logging | Log verbosity |
+| `NODEJS_API_CLUSTER_ENABLED` | `false` | Node.js clustering | Process count |
+| `RUST_API_WORKERS` | `4` | Actix workers | Thread pool |
+
+### Network Configuration (All Profiles)
+
+| Variable | Value | Purpose | Impact |
+|----------|-------|---------|--------|
+| `COLIMA_NETWORK_ADDRESS` | `true` | Enable host access | External connectivity |
+| `SERVICE_NETWORK_SUBNET` | `172.20.0.0/16` | Network range | IP allocation |
+
+### Security Settings (All Profiles - Development Mode)
+
+| Variable | Value | Purpose | Why This Value |
+|----------|-------|---------|----------------|
+| `ALLOW_WEAK_PASSWORDS` | `true` | Local development | Convenience over security |
+| `ENABLE_RATE_LIMITING` | `false` | Local development | Testing without limits |
+| `SESSION_TIMEOUT` | `86400` (minimal), `28800` (standard/full) | Session duration | Development convenience |
+| `ENABLE_TLS` | `false` | TLS/SSL | Local development simplicity |
+
+### Complete Variable Summary by Profile
+
+**Minimal Profile** (`configs/profiles/minimal.env`):
+- 298 lines of configuration
+- Focus: Resource efficiency, quick startup
+- Key differences: Single Redis, reduced limits, shorter retention
+- Target: Personal projects, learning, CI/CD
+
+**Standard Profile** (`configs/profiles/standard.env`):
+- 460 lines of configuration
+- Focus: Production parity, multi-database
+- Key differences: Redis cluster, all databases, standard limits
+- Target: Multi-service development, integration testing
+
+**Full Profile** (`configs/profiles/full.env`):
+- 486 lines of configuration
+- Focus: Complete observability, monitoring
+- Key differences: All observability stack, enhanced logging, longer retention
+- Target: Performance analysis, troubleshooting, learning observability
+
+**Reference Profile** (`configs/profiles/reference.env`):
+- 455 lines of configuration
+- Focus: API examples, cross-language patterns
+- Combinable: Must be used with minimal, standard, or full
+- Target: API development, pattern learning, performance comparison
 
 ## Advanced: Custom Profiles
 
diff --git a/wiki/Service-Overview.md b/wiki/Service-Overview.md
index eb61f48..78a03a9 100644
--- a/wiki/Service-Overview.md
+++ b/wiki/Service-Overview.md
@@ -22,14 +22,14 @@
 
 | Service | Version | Port(s) | Purpose | Health Check |
 |---------|---------|---------|---------|--------------|
-| **PostgreSQL** | 16-alpine | 5432 | Git storage + dev database | pg_isready |
+| **PostgreSQL** | 18 | 5432 | Git storage + dev database | pg_isready |
 | **PgBouncer** | latest | 6432 | Connection pooling | psql test |
-| **MySQL** | 8.0 | 3306 | Legacy database support | mysqladmin ping |
-| **Redis Cluster** | 7-alpine | 6379 (non-TLS), 6390 (TLS), 16379 (cluster bus) | Distributed cache (3 nodes) | redis-cli ping |
-| **RabbitMQ** | 3-management-alpine | 5672, 15672 | Message queue + UI | rabbitmq-diagnostics |
-| **MongoDB** | 7 | 27017 | NoSQL database | mongosh ping |
+| **MySQL** | 8.0.40 | 3306 | Legacy database support | mysqladmin ping |
+| **Redis Cluster** | 7.4-alpine | 6379 (non-TLS), 6390 (TLS), 16379 (cluster bus) | Distributed cache (3 nodes) | redis-cli ping |
+| **RabbitMQ** | 3.13-management-alpine | 5672, 15672 | Message queue + UI | rabbitmq-diagnostics |
+| **MongoDB** | 7.0 | 27017 | NoSQL database | mongosh ping |
 | **Forgejo** | 1.21 | 3000, 2222 | Self-hosted Git server | curl /api/healthz |
-| **Vault** | latest | 8200 | Secrets management | wget /sys/health |
+| **Vault** | 1.18 | 8200 | Secrets management | wget /sys/health |
 
 ### Observability Stack
 
@@ -137,7 +137,7 @@ docker exec dev-postgres pg_isready -U $POSTGRES_USER
 
 ### PgBouncer
 
-**Purpose:** Connection pooling for PostgreSQL to reduce connection overhead.
+**Purpose:** Connection pooling for PostgreSQL to reduce connection overhead and improve scalability.
 
 **Configuration:**
 - Pool mode: `transaction` (best for web applications)
@@ -147,26 +147,367 @@ docker exec dev-postgres pg_isready -U $POSTGRES_USER
 - **Authentication:** Uses MD5 (PostgreSQL configured for MD5, not SCRAM-SHA-256)
 - **Credentials:** Loaded from Vault via environment variables (`scripts/load-vault-env.sh`)
 
-**When to Use:**
-- High-frequency connections (web apps, APIs)
-- Connection-per-request patterns
-- Microservices connecting to shared database
+#### Connection Pool Modes
+
+PgBouncer supports three pooling modes, each with different use cases:
+
+**1. Transaction Pooling (Default)**
+```ini
+pool_mode = transaction
+```
+- **How it works:** Connection returned to pool when transaction completes
+- **Best for:** Web applications, REST APIs, microservices
+- **Pros:** Maximum connection reuse, highest efficiency
+- **Cons:** Cannot use session-level features (temp tables, prepared statements, LISTEN/NOTIFY)
+- **Use when:** Most common mode for stateless applications
+
+**2. Session Pooling**
+```ini
+pool_mode = session
+```
+- **How it works:** Connection returned to pool when client disconnects
+- **Best for:** Interactive applications, long-running sessions
+- **Pros:** Full PostgreSQL feature support, no restrictions
+- **Cons:** Lower connection reuse, less efficient
+- **Use when:** Need session-level features (temp tables, advisory locks)
+
+**3. Statement Pooling**
+```ini
+pool_mode = statement
+```
+- **How it works:** Connection returned after each SQL statement
+- **Best for:** Simple read-only queries
+- **Pros:** Highest connection reuse
+- **Cons:** Multi-statement transactions not supported
+- **Use when:** Simple query-only workloads (rare)
+
+#### When to Use PgBouncer
+
+**Ideal Scenarios:**
+
+1. **High Connection Churn**
+   - Web applications with many short-lived connections
+   - Connection-per-request patterns
+   - Serverless functions connecting to database
+
+2. **Connection Limit Constraints**
+   - PostgreSQL `max_connections=100` but need 500 clients
+   - PgBouncer pools 500 clients → 10 actual PostgreSQL connections
+
+3. **Microservices Architecture**
+   - Multiple services sharing single database
+   - Each service maintains connection pool
+   - PgBouncer prevents PostgreSQL connection exhaustion
+
+4. **Database Migration/Failover**
+   - PgBouncer can redirect connections without client changes
+   - Useful for blue-green deployments
+
+**When NOT to Use PgBouncer:**
+
+- Long-running analytical queries (use direct connection)
+- Administrative tasks (backups, maintenance)
+- Applications requiring LISTEN/NOTIFY or advisory locks
+- Single-user development environments
+
+#### Performance Tuning
+
+**Pool Size Configuration:**
+
+```bash
+# In .env or docker-compose.yml environment
+PGBOUNCER_DEFAULT_POOL_SIZE=10      # Connections per user/database
+PGBOUNCER_MIN_POOL_SIZE=5           # Keep minimum connections warm
+PGBOUNCER_RESERVE_POOL_SIZE=5       # Extra connections for bursts
+PGBOUNCER_MAX_CLIENT_CONN=100       # Maximum client connections
+PGBOUNCER_MAX_DB_CONNECTIONS=20     # Total connections to PostgreSQL
+```
+
+**Tuning Guidelines:**
+
+| Scenario | Pool Size | Max Clients | Max DB Connections |
+|----------|-----------|-------------|-------------------|
+| **Development** | 5-10 | 25-50 | 10-20 |
+| **Small Production** | 10-20 | 100-200 | 20-40 |
+| **Medium Production** | 20-50 | 500-1000 | 50-100 |
+| **Large Production** | 50-100 | 2000-5000 | 100-200 |
+
+**Formula:** `max_db_connections = pool_size * (number of databases * number of users)`
+
+**Connection Timeout Settings:**
+
+```bash
+PGBOUNCER_SERVER_IDLE_TIMEOUT=600   # Close idle server connections after 10min
+PGBOUNCER_CLIENT_IDLE_TIMEOUT=300   # Disconnect idle clients after 5min
+PGBOUNCER_QUERY_TIMEOUT=0           # No query timeout (0 = disabled)
+PGBOUNCER_QUERY_WAIT_TIMEOUT=120    # Wait 2min for available connection
+```
+
+#### Monitoring
+
+**Pool Utilization Metrics:**
+
+```bash
+# Connect to PgBouncer admin console
+psql -h localhost -p 6432 -U pgbouncer pgbouncer
+
+# Show pool statistics
+SHOW POOLS;
+# Output: database, user, cl_active, cl_waiting, sv_active, sv_idle, sv_used
+#         dev_database, dev_admin, 5, 0, 3, 2, 8
+
+# Show active clients
+SHOW CLIENTS;
+
+# Show server connections
+SHOW SERVERS;
+
+# Show configuration
+SHOW CONFIG;
+
+# Show statistics
+SHOW STATS;
+```
+
+**Key Metrics to Monitor:**
+
+1. **cl_waiting** - Clients waiting for connection (should be 0)
+2. **sv_active** - Active server connections (should be < pool_size)
+3. **sv_idle** - Idle server connections (pool of ready connections)
+4. **total_xact_count** - Total transactions processed
+5. **avg_xact_time** - Average transaction time
+
+**Prometheus Metrics** (if using pgbouncer_exporter):
+```bash
+# Available at http://localhost:9127/metrics
+pgbouncer_pools_server_active_connections
+pgbouncer_pools_server_idle_connections
+pgbouncer_pools_client_active_connections
+pgbouncer_pools_client_waiting_connections
+pgbouncer_stats_total_xact_count
+pgbouncer_stats_avg_xact_time_microseconds
+```
+
+#### Troubleshooting
+
+**Problem: Connection Pool Exhausted**
+
+**Symptoms:**
+```
+ERROR: connection pool exhausted
+FATAL: sorry, too many clients already
+```
+
+**Solutions:**
+```bash
+# 1. Increase pool size
+PGBOUNCER_DEFAULT_POOL_SIZE=20  # Was: 10
+
+# 2. Increase PostgreSQL max_connections
+POSTGRES_MAX_CONNECTIONS=200    # Was: 100
+
+# 3. Check for connection leaks
+SHOW POOLS;  # Look for high cl_active without corresponding queries
+SHOW CLIENTS;  # Identify misbehaving clients
+
+# 4. Enable connection recycling
+PGBOUNCER_SERVER_IDLE_TIMEOUT=300  # Close idle connections faster
+```
+
+**Problem: Slow Query Performance**
+
+**Symptoms:**
+- Queries slower through PgBouncer than direct connection
+
+**Solutions:**
+```bash
+# 1. Check pool wait time
+SHOW STATS;  # Look at avg_wait_time
+
+# 2. Increase pool size if clients waiting
+PGBOUNCER_DEFAULT_POOL_SIZE=20
+
+# 3. Check for connection mode mismatch
+# Ensure using transaction mode for web apps
+PGBOUNCER_POOL_MODE=transaction
+
+# 4. Monitor query timeouts
+SHOW SERVERS;  # Look for long-running queries blocking pool
+```
+
+**Problem: Authentication Failures**
+
+**Symptoms:**
+```
+FATAL: authentication failed for user "dev_admin"
+FATAL: MD5 authentication failed
+```
+
+**Solutions:**
+```bash
+# 1. Verify PostgreSQL uses MD5 (not SCRAM-SHA-256)
+docker exec dev-postgres grep "password_encryption" /var/lib/postgresql/data/postgresql.conf
+
+# 2. Check userlist.txt has correct credentials
+docker exec dev-pgbouncer cat /etc/pgbouncer/userlist.txt
+
+# 3. Verify Vault credentials match
+./devstack vault-show-password postgres
+
+# 4. Restart PgBouncer after credential changes
+docker compose restart pgbouncer
+```
+
+**Problem: PgBouncer Not Forwarding Queries**
+
+**Symptoms:**
+- Connections succeed but queries hang
+
+**Solutions:**
+```bash
+# 1. Check PgBouncer logs
+docker logs dev-pgbouncer
+
+# 2. Verify PostgreSQL connectivity
+docker exec dev-pgbouncer psql -h postgres -p 5432 -U dev_admin -d dev_database -c "SELECT 1;"
+
+# 3. Check admin console
+psql -h localhost -p 6432 -U pgbouncer pgbouncer -c "SHOW SERVERS;"
+
+# 4. Restart PgBouncer
+docker compose restart pgbouncer
+```
+
+#### Configuration Examples
+
+**High-Throughput Web Application:**
+
+```bash
+# .env configuration
+PGBOUNCER_POOL_MODE=transaction
+PGBOUNCER_DEFAULT_POOL_SIZE=20
+PGBOUNCER_MAX_CLIENT_CONN=500
+PGBOUNCER_MAX_DB_CONNECTIONS=40
+PGBOUNCER_SERVER_IDLE_TIMEOUT=300
+PGBOUNCER_QUERY_WAIT_TIMEOUT=60
+```
+
+**Long-Running Session-Based Application:**
+
+```bash
+PGBOUNCER_POOL_MODE=session
+PGBOUNCER_DEFAULT_POOL_SIZE=50
+PGBOUNCER_MAX_CLIENT_CONN=100
+PGBOUNCER_SERVER_IDLE_TIMEOUT=600
+PGBOUNCER_CLIENT_IDLE_TIMEOUT=3600
+```
+
+**Microservices with Burst Traffic:**
 
-**Connection:**
 ```bash
+PGBOUNCER_POOL_MODE=transaction
+PGBOUNCER_DEFAULT_POOL_SIZE=10
+PGBOUNCER_RESERVE_POOL_SIZE=10
+PGBOUNCER_MAX_CLIENT_CONN=1000
+PGBOUNCER_MAX_DB_CONNECTIONS=30
+PGBOUNCER_QUERY_WAIT_TIMEOUT=30
+```
+
+#### Connection Examples
+
+**Direct PostgreSQL Connection (Port 5432):**
+```bash
+# For long-lived connections, admin tasks
+psql -h localhost -p 5432 -U $POSTGRES_USER -d $POSTGRES_DB
+
+# Use cases:
+# - Database migrations
+# - Backups and restores
+# - pg_dump/pg_restore
+# - Administrative queries
+# - Long-running analytical queries
+```
+
+**PgBouncer Connection (Port 6432):**
+```bash
+# For application connections, APIs
 psql -h localhost -p 6432 -U $POSTGRES_USER -d $POSTGRES_DB
+
+# Use cases:
+# - Web application queries
+# - REST API endpoints
+# - Microservice database access
+# - Connection pool management
+# - High-frequency short transactions
+```
+
+**Application Configuration:**
+
+```python
+# Python (asyncpg example)
+import asyncpg
+
+# Use PgBouncer for application connections
+pool = await asyncpg.create_pool(
+    host='localhost',
+    port=6432,  # PgBouncer port
+    user='dev_admin',
+    password='<from-vault>',
+    database='dev_database',
+    min_size=5,
+    max_size=20,
+    command_timeout=60
+)
 ```
 
-**Direct PostgreSQL vs PgBouncer:**
-- Direct (5432): For long-lived connections, admin tasks
-- PgBouncer (6432): For application connections, APIs
+```javascript
+// Node.js (pg example)
+const { Pool } = require('pg');
+
+// Use PgBouncer for connection pooling
+const pool = new Pool({
+  host: 'localhost',
+  port: 6432,  // PgBouncer port
+  user: 'dev_admin',
+  password: '<from-vault>',
+  database: 'dev_database',
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+```
+
+#### Performance Benchmarks
+
+**Without PgBouncer:**
+- Direct PostgreSQL connections
+- Connection overhead: ~50-100ms per connection
+- Max concurrent connections: 100 (PostgreSQL limit)
+- Connection setup cost: High
+
+**With PgBouncer:**
+- Pooled connections
+- Connection overhead: ~1-5ms (reusing existing connections)
+- Max concurrent clients: 1000+ (configurable)
+- Connection setup cost: Minimal (pool reuse)
+
+**Throughput Improvement:**
+- Simple queries: 50-100% improvement
+- High-frequency requests: 200-300% improvement
+- Connection-intensive workloads: 500% improvement
+
+#### Related Documentation
+
+- PostgreSQL connection management: [PostgreSQL](#postgresql)
+- Performance tuning: `docs/PERFORMANCE_TUNING.md`
+- Connection pooling best practices: `reference-apps/README.md`
 
 ### MySQL
 
 **Purpose:** Legacy database support during migration period.
 
 **Configuration:**
-- Image: `mysql:8.0`
+- Image: `mysql:8.0.40`
 - **Credentials:** Auto-fetched from Vault at startup via `configs/mysql/scripts/init.sh`
   - Stored in Vault at `secret/mysql`
   - Fields: `root_password`, `user`, `password`, `database`
@@ -345,7 +686,7 @@ docker exec dev-rabbitmq rabbitmqctl list_connections
 **Purpose:** NoSQL document database for unstructured data.
 
 **Configuration:**
-- Image: `mongo:7`
+- Image: `mongo:7.0`
 - **Credentials:** Auto-fetched from Vault at startup via `configs/mongodb/scripts/init.sh`
   - Stored in Vault at `secret/mongodb`
   - Fields: `user`, `password`, `database`
@@ -372,50 +713,657 @@ mongodb://dev_admin:password@localhost:27017/dev_database?authSource=admin
 
 ### Forgejo (Git Server)
 
-**Purpose:** Self-hosted Git server (Gitea fork) for private repositories.
+**Purpose:** Self-hosted Git server (Gitea fork) for private repositories with full Git forge capabilities.
 
 **Configuration:**
+- Image: `forgejo:1.21`
 - Uses PostgreSQL for metadata storage
 - Git data stored in Docker volume (`forgejo_data`)
 - SSH port mapped to 2222 (to avoid conflict with Mac's SSH on 22)
+- HTTP/HTTPS ports: 3000 (configurable)
+- **Credentials:** Auto-configured from PostgreSQL Vault credentials
+
+#### First-Time Setup
+
+**Installation Wizard:**
+
+1. **Navigate to Forgejo**
+   ```bash
+   open http://localhost:3000
+   ```
+
+2. **Complete Installation Wizard**
+   - **Database Settings:**
+     - Database type: PostgreSQL
+     - Host: `postgres:5432` (internal Docker network)
+     - Username: `dev_admin` (from Vault)
+     - Password: (auto-filled from environment)
+     - Database name: `forgejo`
+     - SSL Mode: Disable (internal network)
+
+   - **General Settings:**
+     - Site title: "DevStack Git"
+     - Repository root path: `/data/git/repositories`
+     - Git LFS root path: `/data/git/lfs`
+     - Run as username: `git`
+     - SSH server domain: `localhost`
+     - SSH port: `2222`
+     - HTTP listen port: `3000`
+     - Base URL: `http://localhost:3000/`
+
+   - **Optional Settings:**
+     - Email: Configure SMTP for notifications (optional)
+     - Server and Third-Party Services: Enable/disable features
+
+3. **Create Administrator Account**
+   ```
+   Username: admin
+   Email: admin@localhost
+   Password: <secure-password>
+   ```
+
+4. **Initial Configuration Complete**
+   - You'll be automatically logged in
+   - Start creating organizations and repositories
+
+**Automated Setup** (scripted):
 
-**First-Time Setup:**
-1. Navigate to http://localhost:3000
-2. Complete installation wizard:
-   - Database type: PostgreSQL
-   - Host: `postgres:5432` (internal network)
-   - Database: `forgejo`
-   - Username/Password: Same as PostgreSQL (auto-configured via env vars)
-3. Create admin account
-4. Start creating repositories
+```bash
+# Use management script for automated setup
+./devstack forgejo-init
+
+# Or manually via API
+curl -X POST http://localhost:3000/api/v1/user/setup \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_name": "admin",
+    "email": "admin@localhost",
+    "password": "<secure-password>",
+    "admin": true
+  }'
+```
+
+#### Git Operations
 
-**Git Operations:**
+**HTTP Clone:**
 ```bash
-# Clone via HTTP
+# Public repository (read-only)
 git clone http://localhost:3000/username/repo.git
 
-# Clone via SSH
+# Private repository (requires authentication)
+git clone http://admin:password@localhost:3000/username/private-repo.git
+
+# Using credentials helper (recommended)
+git config --global credential.helper store
+git clone http://localhost:3000/username/repo.git
+# Enter username/password once, stored for future use
+```
+
+**SSH Clone:**
+```bash
+# Standard SSH URL
 git clone ssh://git@localhost:2222/username/repo.git
 
-# Configure SSH
-# Add to ~/.ssh/config:
+# Alternative syntax
+git clone git@localhost:2222:username/repo.git
+```
+
+**SSH Configuration** (`~/.ssh/config`):
+```bash
+# Add entry for Forgejo
 Host forgejo
   HostName localhost
   Port 2222
   User git
   IdentityFile ~/.ssh/id_rsa
+  PreferredAuthentications publickey
 
-# Then clone with:
+# Usage
 git clone forgejo:username/repo.git
+git remote add origin forgejo:username/repo.git
+```
+
+**Common Git Workflows:**
+```bash
+# Create new repository on Forgejo first, then:
+mkdir my-project && cd my-project
+git init
+git add README.md
+git commit -m "Initial commit"
+git remote add origin http://localhost:3000/admin/my-project.git
+git push -u origin main
+
+# Clone existing
+git clone http://localhost:3000/admin/my-project.git
+cd my-project
+git checkout -b feature-branch
+# Make changes
+git add .
+git commit -m "Add feature"
+git push origin feature-branch
+```
+
+#### SSH and GPG Key Management
+
+**Adding SSH Keys:**
+
+1. **Generate SSH Key** (if needed)
+   ```bash
+   ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/forgejo_ed25519
+   ```
+
+2. **Add to Forgejo UI**
+   - Navigate to Settings → SSH / GPG Keys
+   - Click "Add Key"
+   - Paste public key: `cat ~/.ssh/forgejo_ed25519.pub`
+   - Give it a descriptive name
+   - Click "Add Key"
+
+3. **Test SSH Connection**
+   ```bash
+   ssh -T -p 2222 git@localhost
+   # Output: Hi there, <username>! You've successfully authenticated...
+   ```
+
+4. **Use SSH for Git Operations**
+   ```bash
+   git clone ssh://git@localhost:2222/username/repo.git
+   ```
+
+**Adding GPG Keys for Signed Commits:**
+
+1. **Generate GPG Key** (if needed)
+   ```bash
+   gpg --full-generate-key
+   # Select: (1) RSA and RSA, 4096 bits, no expiration
+   ```
+
+2. **Get GPG Key ID**
+   ```bash
+   gpg --list-secret-keys --keyid-format=long
+   # Note the key ID (e.g., 3AA5C34371567BD2)
+   ```
+
+3. **Export Public Key**
+   ```bash
+   gpg --armor --export 3AA5C34371567BD2
+   ```
+
+4. **Add to Forgejo UI**
+   - Navigate to Settings → SSH / GPG Keys
+   - Click "Add GPG Key"
+   - Paste exported public key
+   - Click "Add Key"
+
+5. **Configure Git to Sign Commits**
+   ```bash
+   git config --global user.signingkey 3AA5C34371567BD2
+   git config --global commit.gpgsign true
+   ```
+
+6. **Make Signed Commit**
+   ```bash
+   git commit -S -m "Signed commit message"
+   git log --show-signature
+   ```
+
+For detailed SSH and GPG setup, see [CONTRIBUTING.md](../Contributing-Guide#setting-up-ssh-and-gpg-keys-for-forgejo).
+
+#### User Management
+
+**Creating Users (Admin):**
+
+1. **Via Web UI:**
+   - Navigate to Site Administration → User Accounts
+   - Click "Create User Account"
+   - Fill in details (username, email, password)
+   - Set permissions and quotas
+   - Click "Create User Account"
+
+2. **Via API:**
+   ```bash
+   curl -X POST http://localhost:3000/api/v1/admin/users \
+     -H "Authorization: token <admin-token>" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "username": "developer",
+       "email": "dev@example.com",
+       "password": "password123",
+       "must_change_password": true
+     }'
+   ```
+
+**User Permissions:**
+- **Administrator:** Full system access
+- **Regular User:** Can create repos, organizations
+- **Restricted:** Limited permissions
+- **Bot:** Automation accounts
+
+**User Quotas:**
+```bash
+# Set via Site Administration → Users → Edit
+- Max repositories: 10
+- Max organizations: 3
+- Repository size limit: 1GB
+```
+
+#### Repository Mirroring
+
+**Mirror External Repository:**
+
+1. **Via Web UI:**
+   - Click "+" → "New Migration"
+   - Select source (GitHub, GitLab, Gitea, etc.)
+   - Enter repository URL
+   - Configure mirror settings:
+     - Mirror interval: 8 hours (default)
+     - Mirror on push: Enable for two-way sync
+   - Click "Migrate Repository"
+
+2. **Via API:**
+   ```bash
+   curl -X POST http://localhost:3000/api/v1/repos/migrate \
+     -H "Authorization: token <token>" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "clone_addr": "https://github.com/user/repo.git",
+       "repo_name": "mirrored-repo",
+       "mirror": true,
+       "private": false,
+       "uid": 1
+     }'
+   ```
+
+**Mirror Types:**
+- **Pull Mirror:** One-way sync from external source
+- **Push Mirror:** One-way sync to external destination
+- **Two-way Sync:** Bidirectional synchronization (advanced)
+
+**Mirror Configuration:**
+```bash
+# Update mirror manually
+curl -X POST http://localhost:3000/api/v1/repos/{owner}/{repo}/mirror-sync \
+  -H "Authorization: token <token>"
+
+# View mirror status
+curl http://localhost:3000/api/v1/repos/{owner}/{repo} \
+  -H "Authorization: token <token>" | jq '.mirror_interval'
+```
+
+#### Webhook Configuration
+
+**CI/CD Integration:**
+
+1. **Create Webhook:**
+   - Navigate to Repository → Settings → Webhooks
+   - Click "Add Webhook"
+   - Select type (Gitea, Slack, Discord, Generic)
+
+2. **Configure Webhook:**
+   ```json
+   {
+     "type": "gitea",
+     "config": {
+       "url": "https://ci.example.com/webhooks/forgejo",
+       "content_type": "json",
+       "secret": "<webhook-secret>"
+     },
+     "events": [
+       "push",
+       "create",
+       "delete",
+       "pull_request"
+     ],
+     "active": true
+   }
+   ```
+
+3. **Test Webhook:**
+   - Click "Test Delivery"
+   - Check response status
+   - View delivery history
+
+**Common Webhook Events:**
+- `push` - Code pushed to repository
+- `pull_request` - PR opened, closed, merged
+- `issue` - Issue created, edited, closed
+- `release` - Release published
+- `repository` - Repository created, deleted
+
+**Example CI/CD Webhook Handler:**
+```python
+from flask import Flask, request, jsonify
+import hmac, hashlib
+
+app = Flask(__name__)
+WEBHOOK_SECRET = "your-secret-here"
+
+@app.route('/webhooks/forgejo', methods=['POST'])
+def handle_webhook():
+    # Verify signature
+    signature = request.headers.get('X-Gitea-Signature')
+    payload = request.data
+    expected = hmac.new(
+        WEBHOOK_SECRET.encode(),
+        payload,
+        hashlib.sha256
+    ).hexdigest()
+
+    if not hmac.compare_digest(signature, expected):
+        return jsonify({'error': 'Invalid signature'}), 403
+
+    # Process webhook
+    data = request.json
+    if data['event'] == 'push':
+        # Trigger build
+        trigger_ci_build(data['repository']['full_name'])
+
+    return jsonify({'status': 'success'}), 200
+```
+
+#### Backup and Restore
+
+**Backup Forgejo Data:**
+
+1. **Database Backup** (PostgreSQL):
+   ```bash
+   # Backup Forgejo database
+   docker exec dev-postgres pg_dump -U dev_admin forgejo > forgejo-db-backup.sql
+
+   # Or use management script
+   ./devstack backup
+   ```
+
+2. **Git Repository Backup:**
+   ```bash
+   # Backup all repositories (Docker volume)
+   docker run --rm \
+     -v devstack-core_forgejo_data:/data \
+     -v $(pwd):/backup \
+     alpine tar czf /backup/forgejo-repos-backup.tar.gz /data
+   ```
+
+3. **Configuration Backup:**
+   ```bash
+   # Backup Forgejo config
+   docker cp dev-forgejo:/data/gitea/conf/app.ini forgejo-app.ini.backup
+   ```
+
+**Automated Backup Script:**
+```bash
+#!/bin/bash
+# backup-forgejo.sh
+
+BACKUP_DIR="$HOME/backups/forgejo/$(date +%Y%m%d_%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+
+# 1. Backup database
+docker exec dev-postgres pg_dump -U dev_admin forgejo > "$BACKUP_DIR/database.sql"
+
+# 2. Backup repositories and data
+docker run --rm \
+  -v devstack-core_forgejo_data:/data \
+  -v "$BACKUP_DIR":/backup \
+  alpine tar czf /backup/repositories.tar.gz /data
+
+# 3. Backup configuration
+docker cp dev-forgejo:/data/gitea/conf/app.ini "$BACKUP_DIR/app.ini"
+
+echo "Backup completed: $BACKUP_DIR"
+```
+
+**Restore Forgejo:**
+
+1. **Stop Forgejo:**
+   ```bash
+   docker compose stop forgejo
+   ```
+
+2. **Restore Database:**
+   ```bash
+   docker exec -i dev-postgres psql -U dev_admin forgejo < forgejo-db-backup.sql
+   ```
+
+3. **Restore Repositories:**
+   ```bash
+   docker run --rm \
+     -v devstack-core_forgejo_data:/data \
+     -v $(pwd):/backup \
+     alpine sh -c "cd / && tar xzf /backup/forgejo-repos-backup.tar.gz"
+   ```
+
+4. **Restore Configuration:**
+   ```bash
+   docker cp forgejo-app.ini.backup dev-forgejo:/data/gitea/conf/app.ini
+   ```
+
+5. **Restart Forgejo:**
+   ```bash
+   docker compose up -d forgejo
+   ```
+
+#### Performance Optimization
+
+**Large Repository Handling:**
+
+1. **Enable Git LFS:**
+   ```bash
+   # In app.ini (or via environment)
+   [lfs]
+   ENABLED = true
+   PATH = /data/git/lfs
+
+   # Client setup
+   git lfs install
+   git lfs track "*.psd"
+   git lfs track "*.zip"
+   ```
+
+2. **Repository Size Limits:**
+   ```bash
+   # In app.ini
+   [repository]
+   MAX_SIZE = 100  # MB
+   MAX_CREATION_LIMIT = -1  # Unlimited for admins
+   ```
+
+3. **Garbage Collection:**
+   ```bash
+   # Manual GC for specific repository
+   docker exec dev-forgejo sh -c \
+     "cd /data/git/repositories/username/repo.git && git gc --aggressive --prune=now"
+
+   # Automatic GC (scheduled)
+   # In app.ini:
+   [cron.update_mirrors]
+   ENABLED = true
+   SCHEDULE = @every 8h
+   ```
+
+4. **Database Optimization:**
+   ```bash
+   # Vacuum PostgreSQL
+   docker exec dev-postgres psql -U dev_admin forgejo -c "VACUUM ANALYZE;"
+
+   # Reindex
+   docker exec dev-postgres psql -U dev_admin forgejo -c "REINDEX DATABASE forgejo;"
+   ```
+
+**Caching Configuration:**
+```bash
+# In app.ini
+[cache]
+ENABLED = true
+ADAPTER = redis
+HOST = redis-1:6379
+PASSWORD = <from-vault>
+
+[session]
+PROVIDER = redis
+PROVIDER_CONFIG = redis-1:6379
+```
+
+**Resource Tuning:**
+```yaml
+# docker-compose.yml
+forgejo:
+  deploy:
+    resources:
+      limits:
+        cpus: '2.0'
+        memory: 2G
+      reservations:
+        cpus: '1.0'
+        memory: 512M
+```
+
+#### Accessing from Network
+
+**Local Network Access:**
+
+1. **Set Forgejo Domain:**
+   ```bash
+   # In .env
+   FORGEJO_DOMAIN=192.168.106.2  # Colima IP address
+
+   # Or find Colima IP
+   colima status | grep "IP Address"
+   ```
+
+2. **Update Base URL:**
+   ```bash
+   # In Forgejo app.ini
+   [server]
+   ROOT_URL = http://192.168.106.2:3000/
+   ```
+
+3. **Access from Other Machines:**
+   ```bash
+   # From libvirt VM or other computer on network
+   git clone http://192.168.106.2:3000/admin/repo.git
+   ```
+
+**SSH Access from Network:**
+```bash
+# Configure SSH for network access
+Host forgejo-network
+  HostName 192.168.106.2
+  Port 2222
+  User git
+  IdentityFile ~/.ssh/id_rsa
+
+# Clone from network
+git clone forgejo-network:username/repo.git
+```
+
+#### Troubleshooting
+
+**Problem: Cannot Connect to Database**
+
+**Symptoms:**
+- Forgejo fails to start
+- "Failed to connect to database" errors
+
+**Solutions:**
+```bash
+# 1. Verify PostgreSQL is running
+docker compose ps postgres
+
+# 2. Test database connection
+docker exec dev-postgres psql -U dev_admin -d forgejo -c "SELECT 1;"
+
+# 3. Check Forgejo logs
+docker logs dev-forgejo | grep -i database
+
+# 4. Verify credentials
+./devstack vault-show-password postgres
+
+# 5. Restart Forgejo
+docker compose restart forgejo
+```
+
+**Problem: SSH Push/Pull Not Working**
+
+**Symptoms:**
+- `Permission denied (publickey)` errors
+- SSH authentication failures
+
+**Solutions:**
+```bash
+# 1. Test SSH connection
+ssh -vT -p 2222 git@localhost
+
+# 2. Verify SSH key added to Forgejo
+# Check Settings → SSH/GPG Keys in web UI
+
+# 3. Check SSH key permissions
+chmod 600 ~/.ssh/id_rsa
+chmod 644 ~/.ssh/id_rsa.pub
+
+# 4. Verify SSH config
+cat ~/.ssh/config | grep -A 5 forgejo
+
+# 5. Check Forgejo SSH logs
+docker logs dev-forgejo | grep -i ssh
+```
+
+**Problem: Webhook Not Triggering**
+
+**Symptoms:**
+- CI/CD not triggering on push
+- Webhook shows failed deliveries
+
+**Solutions:**
+```bash
+# 1. Test webhook manually
+curl -X POST https://ci.example.com/webhooks/forgejo \
+  -H "Content-Type: application/json" \
+  -d @webhook-payload.json
+
+# 2. Check webhook deliveries
+# Repository → Settings → Webhooks → Edit → Recent Deliveries
+
+# 3. Verify webhook secret
+# Check HMAC signature validation
+
+# 4. Check network connectivity
+docker exec dev-forgejo curl -I https://ci.example.com
+
+# 5. Enable webhook debugging
+# In app.ini: LOG_LEVEL = debug
+```
+
+**Problem: Large Repositories Slow Performance**
+
+**Symptoms:**
+- Slow clone/push operations
+- High memory usage
+
+**Solutions:**
+```bash
+# 1. Enable Git LFS for large files
+git lfs migrate import --include="*.zip,*.tar.gz"
+
+# 2. Run garbage collection
+cd /data/git/repositories/username/repo.git
+git gc --aggressive --prune=now
+
+# 3. Increase resource limits
+# Adjust docker-compose.yml resources
+
+# 4. Enable caching (Redis)
+# Configure [cache] in app.ini
+
+# 5. Archive old repositories
+# Site Administration → Repositories → Archive
 ```
 
-**SSH and GPG Keys:**
-For setting up SSH keys (for authenticated push/pull) and GPG keys (for signed commits), see the detailed guide in [CONTRIBUTING.md](../Contributing-Guide#setting-up-ssh-and-gpg-keys-for-forgejo).
+#### Related Documentation
 
-**Access from Network:**
-- Set `FORGEJO_DOMAIN` to Colima IP in `.env`
-- Access from libvirt VMs or other machines on network
-- Example: http://192.168.106.2:3000
+- SSH/GPG setup: [CONTRIBUTING.md](../Contributing-Guide)
+- Backup procedures: [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md)
+- Performance tuning: [PERFORMANCE_TUNING.md](./PERFORMANCE_TUNING.md)
+- PostgreSQL integration: [PostgreSQL](#postgresql)
 
 ### HashiCorp Vault