docs: organize SSH bug documentation into structured archive

- Create infrastructure/docs/bugs/ directory for systematic bug documentation
- Move SSH authentication failure documentation to 001-ssh-authentication-failure/
- Organize content into logical structure:
  - README.md: Bug overview and quick reference
  - SSH_BUG_ANALYSIS.md: Initial investigation and analysis
  - SSH_BUG_SUMMARY.md: Complete timeline and resolution
  - test-configs/: All 17 test configurations used during debugging

- Add comprehensive README.md for bugs directory explaining:
  - Purpose and scope of bug documentation archive
  - Directory structure and naming conventions
  - Content guidelines and quality standards
  - Usage examples for contributors and maintainers

- Fix markdown linting issues in all documentation files
- Add markdownlint disable for technical content with long lines

This establishes a systematic approach for documenting infrastructure bugs
with complete investigation trails, test artifacts, and lessons learned.
Future bugs can follow this template for consistent documentation quality.

infrastructure/docs/bugs/001-ssh-authentication-failure/README.md

@@ -0,0 +1,104 @@
+# SSH Authentication Failure Bug - #001
+
+**Date Resolved:** July 4, 2025  
+**Status:** ✅ Resolved  
+**Impact:** High - Blocked VM access completely  
+**Root Cause:** YAML document start marker (`---`) breaking cloud-init parsing
+
+## Problem Summary
+
+The full cloud-init configuration (`user-data.yaml.tpl`) for the Torrust Tracker
+Demo VM was causing SSH authentication failures for both SSH key and password
+authentication, preventing users from accessing deployed VMs.
+
+## Root Cause
+
+The issue was caused by using the YAML document start marker (`---`) at the
+beginning of the cloud-init configuration file instead of the required
+`#cloud-config` header. This caused cloud-init to misprocess the entire
+configuration, resulting in:
+
+- Empty SSH authorized_keys (SSH key variable not templated)
+- Broken password authentication setup
+- Schema validation errors in cloud-init
+
+## The Fix
+
+**Simple but Critical Change:**
+
+```yaml
+# BEFORE (BROKEN):
+---
+# cloud-config
+
+# AFTER (FIXED):
+#cloud-config
+```
+
+**File Changed:** `infrastructure/cloud-init/user-data.yaml.tpl`
+
+## Investigation Process
+
+This bug was resolved through systematic incremental testing:
+
+1. **Incremental Testing**: Created 15+ test configurations, adding features one by one
+2. **Root Cause Isolation**: Compared working vs. broken configurations using diff analysis
+3. **Hypothesis Formation**: Identified YAML header as the key difference
+4. **Validation**: Deployed fresh VM with corrected header and confirmed fix
+
+## Validation Results
+
+After applying the fix:
+
+- ✅ SSH Key Authentication: Works perfectly
+- ✅ Password Authentication: Works perfectly
+- ✅ All Cloud-Init Features: Docker, UFW, packages, etc. - ALL WORKING
+- ✅ Integration Tests: Complete test suite passes
+- ✅ Make Commands: Standard workflow (`make init`, `make plan`, `make apply`) works
+
+## Files in This Directory
+
+### Core Documentation
+
+- `SSH_BUG_ANALYSIS.md` - Initial analysis and hypothesis formation
+- `SSH_BUG_SUMMARY.md` - Complete investigation summary with detailed timeline
+
+### Test Artifacts
+
+- `test-configs/` - All 16 test configurations used during incremental testing
+  - `user-data-test-1.1.yaml.tpl` through `user-data-test-15.1.yaml.tpl`
+  - `user-data-test-header.yaml.tpl` - Final test that confirmed the fix
+
+### Validation
+
+- `validation/` - (Currently empty, reserved for future validation scripts)
+
+## Lessons Learned
+
+1. **Cloud-init requires specific headers**: `#cloud-config` is mandatory, not `---`
+2. **Incremental testing is powerful**: Systematic approach isolated the issue effectively
+3. **Template variable validation**: Always verify that template variables are being substituted correctly
+4. **Integration testing is crucial**: End-to-end testing revealed the full scope of the issue
+
+## Prevention
+
+To prevent similar issues:
+
+- Always use `#cloud-config` as the first line in cloud-init files
+- Test template variable substitution in terraform plans
+- Run integration tests after any cloud-init configuration changes
+- Use the documented make workflow for deployments
+
+## Related Issues
+
+This fix resolves SSH access problems that were preventing users from following
+the integration testing guide and deploying the Torrust Tracker Demo
+successfully.
+
+## Technical Details
+
+For complete technical details, debugging methodology, and step-by-step
+investigation process, see:
+
+- [SSH_BUG_ANALYSIS.md](SSH_BUG_ANALYSIS.md) - Initial investigation
+- [SSH_BUG_SUMMARY.md](SSH_BUG_SUMMARY.md) - Comprehensive analysis with timeline

infrastructure/cloud-init/SSH_BUG_ANALYSIS.md → infrastructure/docs/bugs/001-ssh-authentication-failure/SSH_BUG_ANALYSIS.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD013 -->
+
 # SSH Authentication Bug Analysis - Cloud-Init Configuration
 
 ## Problem Summary

infrastructure/cloud-init/SSH_BUG_SUMMARY.md → infrastructure/docs/bugs/001-ssh-authentication-failure/SSH_BUG_SUMMARY.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD013 -->
+
 # SSH Authentication Bug Analysis Summary
 
 **Date:** July 4, 2025  

infrastructure/docs/bugs/README.md

@@ -0,0 +1,133 @@
+# Bug Documentation Archive
+
+This directory contains comprehensive documentation for bugs that have been
+investigated and resolved in the Torrust Tracker Demo infrastructure project.
+
+## Purpose
+
+The purpose of this archive is to:
+
+- **Preserve Investigation Process**: Document the complete debugging methodology
+  and thought process used to identify and resolve infrastructure issues
+- **Enable Knowledge Transfer**: Provide detailed reference material for future
+  contributors who encounter similar problems
+- **Improve Debugging Skills**: Demonstrate systematic approaches to
+  infrastructure troubleshooting
+- **Prevent Regression**: Maintain test cases and validation procedures to
+  ensure fixes remain effective
+
+## Structure
+
+Each bug is documented in its own numbered directory following this convention:
+
+```text
+infrastructure/docs/bugs/
+├── README.md                           # This file
+├── 001-ssh-authentication-failure/     # First documented bug
+│   ├── README.md                       # Bug overview and summary
+│   ├── SSH_BUG_ANALYSIS.md            # Initial analysis and hypothesis
+│   ├── SSH_BUG_SUMMARY.md             # Complete investigation summary
+│   ├── test-configs/                  # Test configurations used
+│   │   ├── user-data-test-1.1.yaml.tpl
+│   │   ├── user-data-test-2.1.yaml.tpl
+│   │   └── ...
+│   └── validation/                    # Final validation artifacts
+└── 002-next-bug/                      # Future bug documentation
+    └── ...
+```
+
+## Documentation Standards
+
+When documenting a new bug, create a new numbered directory and include:
+
+### Required Files
+
+1. **README.md** - Bug overview with:
+
+   - Problem description
+   - Root cause summary
+   - Fix applied
+   - Validation results
+   - References to related files
+
+2. **Analysis Documentation** - Detailed investigation process:
+
+   - Initial symptoms and error messages
+   - Hypothesis formation and testing
+   - Step-by-step debugging methodology
+   - Dead ends and lessons learned
+
+3. **Test Artifacts** - Evidence and test cases:
+   - Configuration files used during testing
+   - Test scripts and validation procedures
+   - Before/after comparisons
+   - Reproducible test cases
+
+### Naming Conventions
+
+- **Directories**: Use format `NNN-short-description` (e.g., `001-ssh-authentication-failure`)
+- **Files**: Use descriptive names with consistent prefixes:
+  - `ANALYSIS_` for investigation documentation
+  - `SUMMARY_` for comprehensive overviews
+  - `test-` for test configurations
+  - `validation-` for final verification artifacts
+
+### Content Guidelines
+
+- **Be Comprehensive**: Include all relevant information, even failed attempts
+- **Document Process**: Explain the reasoning behind each debugging step
+- **Include Context**: Provide enough background for newcomers to understand
+- **Show Evidence**: Include relevant log outputs, error messages, and test results
+- **Explain the Fix**: Detail exactly what was changed and why it works
+- **Provide Validation**: Include steps to verify the fix and prevent regression
+
+## Usage Examples
+
+### For Contributors Encountering Similar Issues
+
+1. **Search by Symptoms**: Look through bug directories for similar error messages
+   or behavior patterns
+2. **Review Methodology**: Study the debugging approach used in similar cases
+3. **Adapt Test Procedures**: Use existing test configurations as templates
+4. **Apply Lessons Learned**: Benefit from documented pitfalls and solutions
+
+### For Maintainers
+
+1. **Validate Fixes**: Use documented test cases to ensure fixes remain effective
+2. **Onboard New Contributors**: Point to relevant bug documentation for learning
+3. **Improve Infrastructure**: Identify patterns in bugs to prevent future issues
+4. **Review Process**: Use documented methodologies to improve debugging practices
+
+## Quality Standards
+
+All bug documentation should:
+
+- ✅ Be reproducible by following the documented steps
+- ✅ Include complete context and background information
+- ✅ Demonstrate systematic debugging methodology
+- ✅ Provide clear validation procedures
+- ✅ Explain both what worked and what didn't work
+- ✅ Include timing information and performance impacts
+- ✅ Reference related infrastructure components
+
+## Contributing
+
+When adding new bug documentation:
+
+1. **Create New Directory**: Use next available number with descriptive name
+2. **Follow Standards**: Use the structure and naming conventions above
+3. **Include All Artifacts**: Don't leave out "failed" attempts or test files
+4. **Write for Others**: Assume the reader is unfamiliar with the specific issue
+5. **Validate Documentation**: Ensure someone else can follow your steps
+6. **Update This README**: Add any new patterns or insights to these guidelines
+
+## Index of Documented Bugs
+
+| Bug ID | Description                | Status      | Impact                   | Date Resolved |
+| ------ | -------------------------- | ----------- | ------------------------ | ------------- |
+| 001    | SSH Authentication Failure | ✅ Resolved | High - Blocked VM access | 2025-07-04    |
+
+---
+
+_This archive serves as a knowledge base for infrastructure debugging and should
+be maintained as a valuable resource for the Torrust community._

project-words.txt

@@ -28,6 +28,7 @@ logpath
 mailcatcher
 Makefiles
 maxretry
+misprocess
 mkisofs
 netdev
 newgrp