Update documentation structure and enhance .gitignore

- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files. - Updated README links to reflect new documentation paths for better navigation. - Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.
2025-12-12 21:18:55 -08:00
parent 664707d912
commit fe0365757a
106 changed files with 4666 additions and 2294 deletions
--- a/docs/meta/ORGANIZATION.md
+++ b/docs/meta/ORGANIZATION.md
@@ -0,0 +1,135 @@
+# Documentation Organization
+
+**Last Updated**: 2025-01-09
+
+This document describes the organization structure of documentation in the `docs/` directory.
+
+---
+
+## Directory Structure
+
+```
+docs/
+├── guides/              # Step-by-step guides and how-to documentation
+├── reference/           # Reference materials and specifications
+├── reports/             # Audit reports, reviews, and analysis
+├── summaries/           # Completion and implementation summaries
+├── deployment/          # Deployment status and planning
+├── vm/                  # Virtual Machine documentation
+├── guest-agent/         # Guest agent documentation
+├── api/                 # API documentation
+├── architecture/        # Architecture documentation
+├── archive/             # Historical/archived documentation
+├── proxmox/             # Proxmox-specific documentation
+├── status/              # Current status reports
+├── runbooks/            # Operational runbooks
+├── brand/               # Brand documentation
+├── compliance/          # Compliance documentation
+└── [root files]         # Top-level documentation and indexes
+```
+
+---
+
+## Root Directory Files
+
+The `docs/` root contains:
+
+### Index Files
+- `README.md` - Main documentation index
+- `ARCHITECTURE_INDEX.md` - Architecture documentation index
+- `DEPLOYMENT_INDEX.md` - Deployment documentation index
+- `GUIDES_INDEX.md` - Guides index
+- `REFERENCE_INDEX.md` - Reference documentation index
+
+### Core Documentation
+- `DEPLOYMENT.md` - Main deployment guide
+- `DEPLOYMENT_REQUIREMENTS.md` - Deployment requirements
+- `DEPLOYMENT_EXECUTION_PLAN.md` - Deployment execution plan
+- `API_DOCUMENTATION.md` - API documentation
+- `DEVELOPMENT.md` - Development guide
+- `TESTING.md` - Testing guide
+- `CONTRIBUTING.md` - Contributing guidelines
+- `TROUBLESHOOTING_GUIDE.md` - Troubleshooting guide
+- `MONITORING_GUIDE.md` - Monitoring guide
+- `OPERATIONS_RUNBOOK.md` - Operations runbook
+- `KEYCLOAK_DEPLOYMENT.md` - Keycloak deployment guide
+- `MIGRATION_GUIDE.md` - Migration guide
+- `DESIGN_SYSTEM.md` - Design system
+- `ENTERPRISE_ARCHITECTURE.md` - Enterprise architecture
+- `PNPM_MIGRATION_GUIDE.md` - pnpm migration guide
+
+### Index Files
+- `MARKDOWN_REFERENCE.md` - Markdown reference index
+- `MARKDOWN_REFERENCE.json` - Machine-readable index
+- `MARKDOWN_DEDUPLICATION_REPORT.md` - Deduplication report
+- `MARKDOWN_INDEX_README.md` - Index usage guide
+
+---
+
+## Organized Directories
+
+### guides/
+Step-by-step guides and how-to documentation.
+
+- `BUILD_AND_DEPLOY_INSTRUCTIONS.md`
+- `FORCE_UNLOCK_INSTRUCTIONS.md`
+- `QUICK_INSTALL_GUEST_AGENT.md`
+- `enable-guest-agent-manual.md`
+
+### reference/
+Reference materials, specifications, and technical details.
+
+- `CODE_INCONSISTENCIES.md`
+- `COPY_SCRIPT_TO_PROXMOX_NODES.md`
+- `SCRIPT_COPIED_TO_PROXMOX_NODES.md`
+
+### reports/
+Audit reports, review reports, and analysis documents.
+
+- `AUDIT_SUMMARY.md`
+- `COMPREHENSIVE_AUDIT_REPORT.md`
+- `PROXMOX_COMPREHENSIVE_AUDIT_REPORT.md`
+- `REPOSITORY_AUDIT_REPORT.md`
+- `PROJECT_COMPREHENSIVE_REVIEW.md`
+- `REVIEW_ITEMS_COMPLETED.md`
+- `DOCUMENTATION_DEEP_DIVE_ANALYSIS.md`
+- `DOCUMENTATION_FIXES_APPLIED.md`
+
+### summaries/
+Completion summaries and implementation summaries.
+
+- `DOCUMENTATION_COMPLETE_SUMMARY.md`
+- `IMPLEMENTATION_SUMMARY.md`
+
+### deployment/
+Deployment-related status and planning documents.
+
+- `DEPLOYMENT_NEXT_STEPS.md`
+- `DEPLOYMENT_READY.md`
+- `PRE_DEPLOYMENT_CHECKLIST.md`
+
+### vm/
+Virtual Machine (VM) related documentation.
+
+- `VM_CREATION_PROCEDURE.md`
+- `VM_DEPLOYMENT_CHECKLIST.md`
+- `VM_SPECIFICATIONS.md`
+
+### guest-agent/
+Guest agent implementation and configuration documentation.
+
+- `GUEST_AGENT_CHECKLIST.md`
+- `GUEST_AGENT_CONFIGURATION_ANALYSIS.md`
+
+---
+
+## Navigation
+
+- Use the index files (`*_INDEX.md`) for navigation
+- Check `README.md` in each directory for contents
+- Use [Markdown Reference Index](./MARKDOWN_REFERENCE.md) for comprehensive search
+
+---
+
+**Last Updated**: 2025-01-09
+