feat: add CLI JSON documentation generation

[josecelano]

Overview

This PR adds automatic CLI documentation generation in machine-readable JSON format. This enables AI agents, documentation generators, and IDE integrations to easily understand and interact with the CLI without needing to run commands with --help or parse source code.

What's Added

New docs Command

Generate comprehensive CLI documentation in JSON format:

# Generate to stdout (pipeable)
torrust-tracker-deployer docs

# Save to file
torrust-tracker-deployer docs docs/cli/commands.json

Pre-Generated Documentation

A complete, up-to-date CLI documentation file is maintained at:

• Location: docs/cli/commands.json
• Format: Structured JSON with commands, arguments, descriptions, and metadata
• Version: Automatically includes CLI version information

Why This Matters

For AI Agents:

• Instantly understand all available commands and their arguments
• No need for trial-and-error with --help flags
• Complete command structure in a single file

For Documentation Generators:

• Use as input for automated reference documentation
• Keep docs in sync with actual CLI implementation

For IDE Integrations:

• Enable autocomplete and inline help
• Provide command suggestions as users type

For Version Control:

• Track CLI interface changes over time
• Catch unintended breaking changes in code review

JSON Format

The generated documentation includes:

{
  "format": "cli-documentation",
  "format_version": "1.0",
  "cli": {
    "name": "torrust-tracker-deployer",
    "version": "0.1.0",
    "commands": [
      {
        "name": "provision",
        "description": "...",
        "arguments": [...],
        "subcommands": [...]
      }
    ]
  }
}

Enhanced Help Text

As part of this work, all CLI command help text has been significantly improved with:

• State transitions: Shows what state changes occur (e.g., Created → Provisioned)
• Workflow position: Indicates where command fits in deployment workflow (Step X of 8)
• Next steps: Actionable guidance on what to do after command completes
• Clear exclusions: Explicitly states what the command does NOT do
• Execution estimates: Expected duration for long-running commands

All 16 commands now provide comprehensive guidance to help users understand the deployment workflow.

Usage Example

# Generate documentation
cargo run -- docs docs/cli/commands.json

# Query with jq
jq '.cli.commands[].name' docs/cli/commands.json

# Use in AI agent context
cat docs/cli/commands.json | ai-agent "explain deployment workflow"

Testing

• ✅ All 412 tests passing
• ✅ JSON documentation generates successfully
• ✅ Help text renders correctly in terminal
• ✅ All linters passing

Documentation

• User guide: docs/user-guide/commands/docs.md
• Pre-generated file: docs/cli/commands.json
• Agent skill: .github/skills/regenerate-cli-docs/skill.md

[josecelano]

ACK d1e1a14