Merge #55: Document create environment command

7fe3690 docs: fix documentation link in create-environment.md (copilot-swe-agent[bot])
dbf216b docs: add comprehensive create environment command documentation (copilot-swe-agent[bot])
9aa0675 Initial plan (copilot-swe-agent[bot])

Pull request description:

  Adds user-facing documentation for the `create environment` command, completing the final subissue of epic #34.

  ## Documentation Added

  - **Command reference** (`docs/user-guide/commands/create-environment.md`):
    - Syntax with all CLI flags and configuration format
    - JSON schema with field validation rules
    - 8 practical examples covering development, CI/CD, and production setups
    - Troubleshooting section for configuration validation, SSH keys, permissions, and parsing errors
    - Workflow integration with template generation and next steps

  - **Commands index updates** (`docs/user-guide/commands.md`):
    - Mark `create environment` and `create template` as ✅ Fully Implemented
    - Update workflow examples to include environment creation
    - Add `--working-dir` to common options

  ## Example Usage

  ```bash
  # Generate and edit configuration template
  torrust-tracker-deployer create template config.json
  nano config.json  # Replace placeholders

  # Create environment
  torrust-tracker-deployer create environment --env-file config.json

  # With custom working directory
  torrust-tracker-deployer create environment \
    --env-file config.json \
    --working-dir /opt/deployments
  ```

  Configuration format:
  ```json
  {
    "environment": {
      "name": "production"
    },
    "ssh_credentials": {
      "private_key_path": "~/.ssh/id_rsa",
      "public_key_path": "~/.ssh/id_rsa.pub",
      "username": "torrust",
      "port": 22
    }
  }
  ```

  Closes #52

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

  <details>

  <summary>Original prompt</summary>

  ----

  *This section details on the original issue you should resolve*

  <issue_title>[Subissue 10/10] Document Create Environment Command</issue_title>
  <issue_description># Document Create Environment Command

  **Epic Subissue**: 10 of 10
  **Parent Epic**: [#34](#34) - Create Environment Command
  **Related**: [User Guide Commands](../user-guide/commands.md), [Create Environment Command Documentation](../user-guide/commands/create-environment.md)

  ## Overview

  Add comprehensive user-facing documentation for the `create environment` command to the user guide. This documentation will help users understand how to create new deployment environments from configuration files.

  The create environment command is now fully implemented (Subissues 1-7) and needs proper user-facing documentation in the `docs/user-guide/` directory.

  ## Goals

  - [ ] Create detailed command documentation at `docs/user-guide/commands/create-environment.md`
  - [ ] Update `docs/user-guide/commands.md` to mark create command as implemented
  - [ ] Include practical examples for common use cases
  - [ ] Document all command flags and configuration file formats
  - [ ] Provide troubleshooting guidance for common errors

  ## 🏗️ Architecture Requirements

  **Documentation Type**: User Guide
  **Module Path**: `docs/user-guide/commands/`
  **Pattern**: Command Reference Documentation

  ### Documentation Structure Requirements

  - [ ] Follow existing command documentation pattern (see [docs/user-guide/commands/destroy.md](../user-guide/commands/destroy.md))
  - [ ] Include command synopsis, description, usage examples, and troubleshooting
  - [ ] Use clear, actionable language for user-facing documentation
  - [ ] Provide both JSON and TOML configuration examples

  ### Anti-Patterns to Avoid

  - ❌ Developer-focused implementation details in user guide
  - ❌ Missing practical examples
  - ❌ Unclear error troubleshooting guidance
  - ❌ Inconsistent formatting with other command docs

  ## Specifications

  ### Documentation Structure

  The command documentation should follow this structure:

  1. **Command Overview**

     - Brief description of what the command does
     - When to use it
     - Implementation status badge

  2. **Syntax**

     - Command signature with all flags
     - Required vs optional parameters

  3. **Configuration File Format**

     - JSON format example
     - TOML format example
     - Field descriptions with validation rules

  4. **Examples**

     - Basic usage (minimal configuration)
     - Advanced usage (custom working directory)
     - Template generation workflow

  5. **Common Use Cases**

     - Development environment setup
     - Testing environment setup
     - Production environment setup

  6. **Troubleshooting**

     - Configuration validation errors
     - File system permission issues
     - Invalid SSH key paths
     - Environment name conflicts

  7. **Related Commands**
     - Link to provision command
     - Link to destroy command
     - Link to template generation

  ### Content to Include

  #### Command Overview Section

  ```markdown
  # Create Environment Command

  **Status**: ✅ Fully Implemented

  Create a new deployment environment from a configuration file. This command initializes the environment with validated configuration, SSH credentials, and prepares it for provisioning.

  **Use when**:

  - Setting up a new deployment environment
  - Initializing environment configuration from templates
  - Preparing environments for provisioning

  **Command**: `torrust-tracker-deployer create environment`
  ```

  #### Syntax Section

  ````markdown
  ## Syntax

  ```bash
  torrust-tracker-deployer create environment --env-file <path> [options]
  ```
  ````

  ### Required Flags

  - `--env-file <path>` - Path to environment configuration file (JSON or TOML)

  ### Optional Flags

  - `--working-dir <path>` - Working directory for environment data (default: `.`)
  - `--log-output <mode>` - Logging output mode: `stderr`, `file`, `file-and-stderr` (default: `stderr`)

  ````<!-- markdownlint-disable-line MD040 -->

  #### Configuration Format Section

  ```markdown
  ## Configuration File Format

  ### JSON Format

  ```json
  {
    "environment": {
      "name": "my-environment"
    },
    "ssh_credentials": {
      "private_key_path": "~/.ssh/id_rsa",
      "public_key_path": "~/.ssh/id_rsa.pub",
      "username": "deployer",
      "port": 22
    }
  }
  ````

  ### TOML Format

  ```toml
  [environment]
  name = "my-environment"

  [ssh_credentials]
  private_key_path = "~/.ssh/id_rsa"
  public_key_path = "~/.ssh/id_rsa.pub"
  username = "deployer"
  port = 22
  ```

  ### Field Descriptions

  - **environment.name** (required): Unique environment identifier
    - Must be lowercase alphanumeric with hyphens
    - Used for directory names and resource identification
  - **ssh_credentials.private_key_path** (required): Path to SSH private key
    - Supports `~` for home directory expansion
    - File must exist and be readable
  - **ssh_credentials.public_key_path** (required): Path to SSH public key
    - Supports `~` for home directory expansion...

  </details>

  - Fixes #52

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

  ✨ Let Copilot coding agent [set things up for you](https://github.com/torrust/torrust-tracker-deployer/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

ACKs for top commit:
  josecelano:
    ACK 7fe3690

Tree-SHA512: 070ffcc553d9c68bd8b7f0679918c19c009b9e8fa532949f84b8d4f3daf6a5d3b1c4144f41b5971f4017a07b60039e221b1332f18226115eff7c917345d690b6

Author: josecelano

docs/user-guide/commands.md

@@ -4,21 +4,22 @@ This guide provides an overview of the available commands for the Torrust Tracke
 
 ## ⚠️ Implementation Status
 
-**Current State**: The `destroy` command is fully implemented with CLI interface.
+**Current State**: The `create` and `destroy` commands are fully implemented with CLI interface.
 
-- ✅ **Implemented**: `destroy` command
+- ✅ **Implemented**: `create environment`, `create template`, `destroy` commands
 - ❌ **CLI Interface**: Other commands not yet implemented
 
 The CLI commands documented here represent the planned MVP implementation.
 
 ## Planned Commands (MVP)
 
 ```bash
-# Available command
-torrust-tracker-deployer destroy <env>     # Destroy infrastructure and clean up resources
+# Available commands
+torrust-tracker-deployer create environment --env-file <file>  # Create new deployment environment
+torrust-tracker-deployer create template [path]                # Generate configuration template
+torrust-tracker-deployer destroy <env>                         # Destroy infrastructure and clean up resources
 
 # Future commands
-torrust-tracker-deployer create <env>      # Future - Create environment configuration
 torrust-tracker-deployer deploy <env>      # Future - Full deployment (provision → configure → release)
 torrust-tracker-deployer run <env>         # Future - Start application services
 torrust-tracker-deployer status <env>      # Future - Check environment status
@@ -31,6 +32,46 @@ torrust-tracker-deployer test <env>        # Future - Run validation tests
 
 ### Environment Management
 
+#### [`create environment`](commands/create-environment.md)
+
+Create a new deployment environment from a configuration file.
+
+**Status**: ✅ Fully Implemented
+
+**Use when**: Initializing new environments for development, testing, or production
+
+```bash
+torrust-tracker-deployer create environment --env-file ./config/environment.json
+```
+
+Creates:
+
+- Environment data directory
+- Initial environment state (Created)
+- Persistent configuration
+
+---
+
+#### `create template`
+
+Generate a configuration template file for environment creation.
+
+**Status**: ✅ Fully Implemented
+
+**Use when**: Starting a new environment configuration from scratch
+
+```bash
+# Generate template with default name
+torrust-tracker-deployer create template
+
+# Generate template with custom name
+torrust-tracker-deployer create template my-config.json
+```
+
+Creates: JSON configuration template with placeholder values
+
+---
+
 #### [`destroy`](commands/destroy.md)
 
 Remove environment and clean up all resources.
@@ -55,21 +96,6 @@ Removes:
 
 ### Future Commands
 
-#### `create` (Planned)
-
-Create a new environment configuration.
-
-**Status**: ❌ Not Yet Implemented
-
-**Use when**: Initializing a new deployment environment
-
-```bash
-# Planned CLI usage
-torrust-tracker-deployer create my-environment
-```
-
----
-
 #### `deploy` (Planned)
 
 Complete deployment workflow that orchestrates provision → configure → release.
@@ -143,25 +169,36 @@ torrust-tracker-deployer test my-environment
 The recommended workflow once all commands are implemented:
 
 ```bash
-# 1. Create environment configuration
-torrust-tracker-deployer create production
+# 1. Generate configuration template
+torrust-tracker-deployer create template production-config.json
 
-# 2. Deploy complete stack (provision → configure → release)
+# 2. Edit the configuration file
+nano production-config.json
+
+# 3. Create environment configuration
+torrust-tracker-deployer create environment --env-file production-config.json
+
+# 4. Deploy complete stack (provision → configure → release)
 torrust-tracker-deployer deploy production
 
-# 3. Start services
+# 5. Start services
 torrust-tracker-deployer run production
 
-# 4. Verify deployment
+# 6. Verify deployment
 torrust-tracker-deployer status production
 torrust-tracker-deployer test production
 ```
 
 ### Development/Testing Workflow
 
+Current available commands for development and testing:
+
 ```bash
-# Note: Only destroy command is currently implemented
-torrust-tracker-deployer destroy test-env
+# 1. Create environment from configuration
+torrust-tracker-deployer create environment --env-file dev-config.json
+
+# 2. When done, clean up
+torrust-tracker-deployer destroy dev-env
 ```
 
 ## Environment States
@@ -181,13 +218,14 @@ Created → Provisioned → Configured → Released → Running → Destroyed
 
 ## Common Options
 
-The destroy command supports these options:
+The create and destroy commands support these common options:
 
 - `--help` - Display command help
 - `--log-output <OUTPUT>` - Logging destination (`file-only` or `file-and-stderr`)
 - `--log-file-format <FORMAT>` - File log format (`pretty`, `json`, or `compact`)
 - `--log-stderr-format <FORMAT>` - Stderr log format (`pretty`, `json`, or `compact`)
 - `--log-dir <DIR>` - Log directory (default: `./data/logs`)
+- `--working-dir <DIR>` - Working directory for environment data (default: `.`)
 
 ### Environment Variables
 
@@ -197,12 +235,14 @@ The destroy command supports these options:
 
 New users should:
 
-1. Start with the [`destroy` command documentation](commands/destroy.md) to understand the workflow
-2. Review the deployment states and standard workflow
-3. Consult individual command documentation as more commands become available
+1. Start with the [`create environment` command documentation](commands/create-environment.md) to set up your first environment
+2. Use the [`create template` command](#create-template) to generate a configuration file
+3. Review the [`destroy` command documentation](commands/destroy.md) to understand cleanup workflow
+4. Consult individual command documentation as more commands become available
 
 ## Related Documentation
 
+- [Create Environment Command](commands/create-environment.md) - Detailed create environment command documentation
 - [Destroy Command](commands/destroy.md) - Detailed destroy command documentation
 - [Logging Guide](../logging.md) - Configure logging output
 - [E2E Testing](../../e2e-testing.md) - Testing infrastructure and commands