docs: sync documentation to wiki (#24)

Author: NormB

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)

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)
 
 ---
 

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:**