docs: archive obsolete documentation and improve cross-references (#108)

- Archive historical documents to docs/archive/:
  - IMPROVEMENTS_2025-11-19.md (point-in-time PR summary)
  - NEW_TESTS_SUMMARY.md (historical test addition summary)
  - PHASE_4_SUMMARY.md (phase completion report)
  - TEST_VALIDATION_REPORT.md (point-in-time validation report)

- Add cross-references between related documents:
  - UPGRADE_GUIDE.md ↔ MIGRATION_GUIDE.md
  - DISASTER_RECOVERY.md ↔ ROLLBACK_PROCEDURES.md
  - All guides now link to related troubleshooting docs

- Update docs/README.md:
  - Remove references to archived documents
  - Update documentation coverage table
  - Add note about archive location

- Update document dates and version numbers

Author: NormB

docs/DISASTER_RECOVERY.md

@@ -2,6 +2,13 @@
 
 Step-by-step procedures for recovering from infrastructure failures, including complete environment loss, Vault data loss, database corruption, and network issues. Target RTO: 30 minutes.
 
+**Last Updated:** 2025-12-30
+
+> **Related Documentation:**
+> - For rolling back upgrades or changes, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md)
+> - For upgrade procedures, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md)
+> - For troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
 ## Table of Contents
 
 - [Overview](#overview)

docs/MIGRATION_GUIDE.md

@@ -1,8 +1,13 @@
 # Migration Guide
 
-Step-by-step instructions for migrating from legacy configurations to DevStack Core v1.3.0+, including AppRole authentication and service profiles.
+Step-by-step instructions for migrating from legacy configurations to DevStack Core v1.3.0+, including AppRole authentication and TLS encryption.
 
-**Version:** 1.0 | **Last Updated:** November 19, 2025
+**Version:** 1.1 | **Last Updated:** 2025-12-30
+
+> **Related Documentation:**
+> - For version upgrades and service upgrades, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md)
+> - For disaster recovery procedures, see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md)
+> - For detailed rollback procedures, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md)
 
 ---
 

docs/README.md

@@ -91,27 +91,16 @@ This directory contains comprehensive documentation for the DevStack Core projec
   - Test environment setup
   - Test execution guidelines
   - Coverage goals and metrics
+  - 571+ tests across 50 bash scripts
 
-- **[RUST_API_TESTING_GUIDE.md](./RUST_API_TESTING_GUIDE.md)** - Rust HTTP API testing guide (NEW)
+- **[RUST_API_TESTING_GUIDE.md](./RUST_API_TESTING_GUIDE.md)** - Rust HTTP API testing guide
   - Comprehensive Actix-web testing patterns
   - Unit tests vs integration tests organization
   - Testing best practices (positive, negative, edge cases)
   - Common testing crates and complete examples
   - Async testing with tokio and actix_rt
   - Production-ready testing patterns
 
-- **[TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md)** - Phase 0-2 validation results (NEW - Nov 2025)
-  - 100% test pass rate confirmation (494+ tests)
-  - Issues found and resolved during validation
-  - 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
@@ -328,19 +317,18 @@ See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for guidelines on:
 
 | Category | Files | Status |
 |----------|-------|--------|
-| Project Information | 1 | ✅ Complete |
+| Getting Started | 4 | ✅ Complete |
 | Security | 2 | ✅ Complete |
-| Testing | 4 | ✅ Complete |
+| Testing | 2 | ✅ Complete |
 | Architecture | 1 | ✅ Complete |
-| Service Profiles (v1.3) | 3 | ✅ Complete |
-| Operational Guides | 9 | ✅ Complete |
-| Upgrade Procedures | 1 | ✅ Complete |
+| Service Profiles | 3 | ✅ Complete |
+| Operational Guides | 12 | ✅ Complete |
 | API Patterns | 1 | ✅ Complete |
 | Reference Apps | 6 | ✅ Complete |
 | VoIP Infrastructure | 3 | ✅ Complete (voip/ subdirectory) |
-| **Total Core Documentation Files** | **~31** | **✅ 99% Coverage** |
+| **Total Core Documentation Files** | **~34** | **✅ Complete** |
 
-**Note:** Work-in-progress files (task tracking, test results) are now located in `docs/.private/` (gitignored).
+**Note:** Historical phase summaries and test reports are archived in `docs/archive/`. Work-in-progress files are in `docs/.private/` (gitignored).
 
 ## Useful Resources
 

docs/ROLLBACK_PROCEDURES.md

@@ -2,7 +2,12 @@
 
 Procedures for safely rolling back DevStack Core changes, including database restores, service reverts, and configuration recovery.
 
-**Document Version:** 1.0 | **Created:** November 14, 2025
+**Document Version:** 1.1 | **Last Updated:** 2025-12-30
+
+> **Related Documentation:**
+> - For disaster recovery (complete environment loss), see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md)
+> - For upgrade procedures, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md)
+> - For AppRole/TLS migration rollback, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
 
 ---
 
@@ -26,7 +31,6 @@ This document provides step-by-step procedures to roll back DevStack Core improv
 - **Quick validation:** `./tests/test-rollback-simple.sh` (⭐ Recommended - 30 seconds)
 - **Comprehensive:** `./tests/test-rollback-comprehensive.sh` (All databases - 2 minutes)
 - **All test scripts:** See [Rollback Testing](#rollback-testing) section below
-- **Test results:** [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md)
 
 ### When to Roll Back
 
@@ -626,8 +630,6 @@ DevStack Core includes **4 automated rollback test scripts** to validate rollbac
 
 **Recommended Test:** Use `test-rollback-simple.sh` for validation - it's proven to work and validates core rollback procedures (AppRole ↔ Root Token migration).
 
-**Latest Test Results:** See [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md) for comprehensive testing analysis.
-
 ### Running Rollback Tests
 
 ```bash
@@ -667,7 +669,7 @@ The following improvements have been implemented in test scripts:
 - Prerequisites validation before test execution
 - Automated cleanup on test failures
 
-See [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md) for detailed test results and analysis.
+See [TESTING_APPROACH.md](./TESTING_APPROACH.md) for test methodology and [tests/TEST_COVERAGE.md](../tests/TEST_COVERAGE.md) for detailed coverage analysis.
 
 ### Pre-Rollback Test
 

docs/UPGRADE_GUIDE.md

@@ -1,10 +1,15 @@
 # Upgrade Guide
 
 **Version:** 1.3.0
-**Last Updated:** 2025-01-18
+**Last Updated:** 2025-12-30
 
 Complete guide for upgrading DevStack Core versions, service versions, and migrating between profiles.
 
+> **Related Documentation:**
+> - For AppRole and TLS migration specifically, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
+> - For disaster recovery procedures, see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md)
+> - For detailed rollback procedures, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md)
+
 ---
 
 ## Table of Contents