docs: add user documentation for Destroy Command

[Copilot]

Overview

This PR adds user-facing documentation for the Destroy Command, addressing issue #13 (Sub-issue 9.3 of the Destroy Command Epic). The documentation focuses on end-user guidance while clarifying that the CLI interface is not yet implemented.

What's Changed

New Documentation

User-Facing Documentation

docs/user-guide/commands/destroy.md - End-user guide for the destroy command:

• Implementation Status Warning: Prominent notice that CLI is not yet implemented (coming in issue EPIC: UI Layer Destroy Command #10)
• Command syntax and available options (planned)
• What gets destroyed (VMs, networks, state files, artifacts)
• Common Use Cases: Testing cleanup, failed deployments, scheduled cleanup, emergency teardown
• Idempotency: Explanation of safe multiple executions
• Comprehensive Troubleshooting: Solutions for hangs, partial failures, OpenTofu errors, permission issues
• Safety Considerations: Data loss warnings, backup strategies, confirmation patterns, production best practices
• Automated Cleanup: CI/CD integration examples and cleanup script templates
• Verification: Steps to confirm complete cleanup
• All CLI examples marked as "Planned CLI usage (not yet available)"

docs/user-guide/commands.md - Command index and overview:

• Implementation Status: Clear indication that only DestroyCommand handler exists in Application layer
• Correct MVP command structure with deploy command (not individual provision/configure/release)
• Note that deploy will internally orchestrate: provision → configure → release
• Environment state transitions and lifecycle
• Common options (logging, environment variables)
• Getting started guide
• Links to issue EPIC: UI Layer Destroy Command #10 for CLI implementation details

Updated Documentation

docs/e2e-testing.md:

• Added section on DestroyCommand integration in E2E tests
• Documented fallback cleanup strategy for CI reliability
• Added cross-references to new documentation

docs/contributing/testing.md:

• New section: "Testing Commands" covering command-specific testing patterns
• Test builders documentation with usage examples
• Mock strategies for testing error scenarios
• Integration and E2E testing guidelines
• Destroy command specific testing examples (idempotency, cleanup, error recovery)

project-words.txt:

• Added "mockall" and "runbooks" to the project dictionary

Documentation Structure

docs/
├── contributing/
│   └── testing.md               (UPDATED - Added command testing section)
├── user-guide/
│   ├── commands.md              (NEW - Command index with correct MVP structure)
│   └── commands/
│       └── destroy.md           (NEW - Destroy command user guide with status warnings)
└── e2e-testing.md               (UPDATED - DestroyCommand integration)

Key Features

• Implementation Status Clarity: All documentation clearly indicates that only the Application layer exists, CLI coming in issue EPIC: UI Layer Destroy Command #10
• Accurate Command Structure: Reflects the correct MVP plan with deploy command orchestrating the full workflow
• Practical Examples: Real-world CLI examples marked as planned/future usage
• Cross-Referenced: All documentation properly linked with valid references
• Quality Assured: All linters pass (markdown, yaml, toml, cspell, clippy, rustfmt, shellcheck)
• No Regressions: All 829 unit tests pass

Acceptance Criteria Met

All acceptance criteria from issue #13 have been satisfied:

✅ User-facing documentation with command reference, use cases, and troubleshooting
✅ Command index with correct MVP workflows and getting started guide
✅ E2E testing documentation updated with destroy functionality
✅ Testing conventions updated with command testing patterns
✅ All linters pass and documentation follows project style guidelines
✅ All links are valid and functional
✅ Clear implementation status warnings throughout

Related

• Closes Add Developer Documentation for Destroy Command #13
• Part of Epic EPIC: App Layer Destroy Command #9 - Application Layer Destroy Command
• Depends on Add DestroyCommand in Application Layer #11 (DestroyCommand implementation) and Rename and Update E2E Provision Tests to Include Destroy #12 (E2E tests update)
• CLI implementation tracked in EPIC: UI Layer Destroy Command #10 (UI Layer Destroy Command)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add Developer Documentation for Destroy Command</issue_title>
<issue_description># Add Developer Documentation for Destroy Command

Issue Type: Sub-issue (9.3)
Parent Epic: #9 (epic-app-layer-destroy-command.md)
Related Roadmap: Section 1.2
Dependencies: Issue #11 and #12 should be completed first
Priority: Medium
Estimated Effort: 2-3 hours

---

📋 Issue Overview

Document the destroy command implementation for developers. This includes architecture decisions, usage examples, error handling patterns, and E2E testing integration.

The documentation will help current and future developers understand how to use, maintain, and extend the destroy command functionality.

🎯 Goals

1. Document destroy command architecture and design decisions
2. Provide code examples for using DestroyCommand in development
3. Document error handling patterns and best practices
4. Update E2E testing documentation with destroy functionality
5. Ensure all documentation passes linting requirements

📦 Scope

Core Documentation

The documentation will be organized across three distinct locations:

1. Internal Contributors: docs/contributing/ - Developer-focused implementation details
2. Decision Records: docs/decisions/ - Architectural decisions and rationale
3. User-Facing: docs/user-guide/ - End-user command documentation

Documentation Locations

• docs/contributing/commands.md - Single developer guide covering all commands (update existing or create new)
• docs/decisions/ - Architectural decision records (if significant decisions are made)
• docs/user-guide/commands/destroy.md - User-facing command documentation
• docs/user-guide/commands.md - Command index with descriptions and links
• Updated E2E testing documentation

Content Structure

1. Architecture Overview: How the destroy command fits into DDD layers
2. Usage Examples: Code examples for developers
3. Error Handling: Patterns and best practices
4. Testing Integration: How destroy command integrates with E2E tests
5. Troubleshooting: Common issues and solutions

🏗️ Documentation Structure

New Documentation Files

1. Internal Contributors Documentation: docs/contributing/commands.md

Single developer guide covering all commands (add destroy command section):

• Command Architecture: How all commands fit into DDD Application Layer patterns
• Destroy Command Implementation: Architecture, error handling, testing patterns
• Code Usage: Internal API usage examples for developers (not CLI usage)
• Testing Strategies: Unit test patterns, mock strategies, integration approaches
• Debugging and Development: Internal troubleshooting for contributors

2. User-Facing Documentation: docs/user-guide/commands/destroy.md

End-user command reference covering:

• Command syntax and options
• Usage examples and workflows
• Common use cases and scenarios
• Error messages and troubleshooting
• Safety considerations and best practices

3. Command Index: docs/user-guide/commands.md

Master command reference covering:

• List of all available commands with short descriptions
• Links to detailed command documentation
• Command categories and workflows
• Getting started guide

Updated Files

docs/contributing/testing.md

Add section on:

• Destroy command testing approaches
• E2E integration patterns
• Mock strategies for unit tests

docs/e2e-testing.md

Update with:

• New destroy functionality in E2E tests
• Updated test flow documentation
• Troubleshooting destroy-related test issues

docs/decisions/ (if needed)

Create ADRs for any significant architectural decisions made during implementation.

📋 Content Requirements

1. Internal Contributors Documentation (docs/contributing/commands.md)

Add Destroy Command Section

Add a new section to the existing (or create new) commands developer guide:

Architecture Documentation

Document how DestroyCommand integrates with existing command patterns:

• How it follows established DDD Application Layer patterns (like ProvisionCommand, ConfigCommand)
• Integration with existing infrastructure services (OpenTofu client, state management)
• Error handling and recovery patterns specific to destroy operations
• Command composition and orchestration within the application layer

Internal API Usage Examples

Provide code examples for developers working on the codebase:

// How to use DestroyCommand in applic...

</details>

Fixes torrust/torrust-tracker-deployer#13

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ).

[josecelano]

@copilot Thank you for the comprehensive documentation work! I have several change requests to align the documentation with our actual implementation plan:

📝 Change Requests

1. Remove docs/contributing/commands.md

This file should be removed entirely. The content is problematic for two reasons:

• First sections are duplicated: The architecture patterns and DDD explanations are already covered in other documentation
• DestroyCommand section is too verbose: It reads like code documentation that could become deprecated quickly. The code itself with proper inline documentation should be sufficient for developers.

Action: Delete docs/contributing/commands.md

2. Fix Command Plan in docs/user-guide/commands.md

The documented command structure is incorrect. Our actual implementation plan is:

Correct CLI Commands (MVP):

torrust-tracker-deployer create    # Future
torrust-tracker-deployer deploy    # Future (provision -> configure -> release)  
torrust-tracker-deployer run       # Future
torrust-tracker-deployer status    # Future
torrust-tracker-deployer test      # Future
torrust-tracker-deployer destroy   # Only this exists at App layer currently

Notes:

• The deploy command will internally orchestrate: provision → configure → release
• Individual commands (provision, configure, release) might be added later for advanced users
• Currently, only the destroy command handler exists in the Application layer
• No CLI commands are implemented yet - CLI will come in issue EPIC: UI Layer Destroy Command #10 (see docs/issues/10-epic-ui-layer-destroy-command.md)

Action: Update docs/user-guide/commands.md to reflect the correct command structure and clarify that only the internal App layer command exists.

3. Add Implementation Status Warning to docs/user-guide/commands/destroy.md

The destroy command documentation is good, but needs a clear warning that the CLI is not yet implemented.

Action: Add a prominent notice at the top clarifying:

⚠️ Implementation Status: The DestroyCommand exists in the Application layer, but the CLI interface is not yet implemented. CLI functionality will be available after issue #10 is completed.

4. Remove Placeholder Command Files

These files should be deleted as they reference commands that don't exist and won't exist in the planned structure:

• docs/user-guide/commands/provision.md ❌ Delete
• docs/user-guide/commands/configure.md ❌ Delete
• docs/user-guide/commands/status.md ❌ Delete

Action: Delete these files. We'll add documentation when the actual commands are implemented.

📋 Summary

The documentation should focus only on what currently exists:

• ✅ Keep: docs/user-guide/commands/destroy.md (with implementation status warning)
• ✅ Update: docs/user-guide/commands.md (correct command structure + status)
• ❌ Remove: docs/contributing/commands.md (too verbose, duplicated)
• ❌ Remove: All placeholder command files (confusing, incorrect)

This aligns the documentation with reality: we have the DestroyCommand application layer implementation, but no CLI yet (coming in issue #10).

[Copilot]

@copilot Thank you for the comprehensive documentation work! I have several change requests to align the documentation with our actual implementation plan:

📝 Change Requests...

All change requests have been addressed in commit 0711f66:

1. ✅ Removed docs/contributing/commands.md - deleted as too verbose/duplicated
2. ✅ Fixed command plan in docs/user-guide/commands.md - updated to reflect correct MVP structure with deploy command (not individual provision/configure/release)
3. ✅ Added implementation status warning to docs/user-guide/commands/destroy.md - prominent notice at top clarifying CLI not yet implemented
4. ✅ Removed placeholder files - deleted provision.md, configure.md, and status.md
5. ✅ Updated all CLI examples to indicate "Planned CLI usage (not yet available)"
6. ✅ Fixed broken links - removed references to deleted files

All linters pass and 829 unit tests continue to pass.

[josecelano]

ACK 0711f66