Align documentation with implementation (#45)

* Initial plan

* Fix documentation inconsistencies: yaml field names and installation instructions

Co-authored-by: jongio <2163001+jongio@users.noreply.github.com>

* Fix reqs command documentation and add global flags

Co-authored-by: jongio <2163001+jongio@users.noreply.github.com>

* Update version examples to current version (0.5.1)

Co-authored-by: jongio <2163001+jongio@users.noreply.github.com>

* Fix broken documentation links and update project structure

Co-authored-by: jongio <2163001+jongio@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jongio <2163001+jongio@users.noreply.github.com>

Author: Copilot

cli/README.md

@@ -28,28 +28,34 @@ App automatically detects and manages dependencies for:
 
 ### For End Users
 
-First, add the extension registry:
+First, enable azd extensions:
 
 ```bash
-azd config set extension.registry https://raw.githubusercontent.com/jongio/azd-app/main/registry.json
+azd config set alpha.extension.enabled on
+```
+
+Then add the extension registry:
+
+```bash
+azd extension source add -n app -t url -l "https://raw.githubusercontent.com/jongio/azd-app/refs/heads/main/registry.json"
 ```
 
 Then install the extension:
 
 ```bash
-azd extension install app
+azd extension install jongio.azd.app
 ```
 
 Or install from a specific version:
 
 ```bash
-azd extension install app --version 0.1.0
+azd extension install jongio.azd.app --version 0.5.1
 ```
 
 To uninstall:
 
 ```bash
-azd extension uninstall app
+azd extension uninstall jongio.azd.app
 ```
 
 ### For Development & Testing
@@ -112,7 +118,7 @@ The devcontainer includes:
 - Mage, golangci-lint, and all development tools
 - Your Azure credentials automatically mounted
 
-See [.devcontainer/README.md](.devcontainer/README.md) for details.
+See [../.devcontainer/README.md](../.devcontainer/README.md) for details.
 
 ### Prerequisites
 
@@ -173,9 +179,9 @@ The generated `azure.yaml`:
 ```yaml
 name: my-project
 reqs:
-  - id: node
+  - name: node
     minVersion: 22.0.0
-  - id: pnpm
+  - name: pnpm
     minVersion: 10.0.0
 ```
 
@@ -191,12 +197,12 @@ reqs:
 ```yaml
 name: my-project
 reqs:
-  - id: docker
+  - name: docker
     minVersion: "20.0.0"
     checkRunning: true
-  - id: nodejs
+  - name: nodejs
     minVersion: "20.0.0"
-  - id: python
+  - name: python
     minVersion: "3.12.0"
 ```
 
@@ -310,7 +316,7 @@ resourceGroup := os.Getenv("AZURE_RESOURCE_GROUP_NAME")
 envName := os.Getenv("AZURE_ENV_NAME")
 ```
 
-See [docs/azd-context.md](docs/azd-context.md) for comprehensive documentation on accessing azd context and environment variables.
+See [docs/dev/azd-context-inheritance.md](docs/dev/azd-context-inheritance.md) for comprehensive documentation on accessing azd context and environment variables.
 
 ## Development
 
@@ -350,11 +356,25 @@ azd-app-extension/
 │       └── azure/
 
 ├── docs/                       # Documentation
-│   ├── quickstart.md
-│   ├── add-command-guide.md
-│   ├── command-dependency-chain.md
-│   ├── azd-context.md
-│   └── reqs-command.md
+│   ├── cli-reference.md
+│   ├── environment-variables.md
+│   ├── environment-variables-quick-reference.md
+│   ├── commands/
+│   │   ├── reqs.md
+│   │   ├── deps.md
+│   │   ├── run.md
+│   │   ├── logs.md
+│   │   ├── info.md
+│   │   └── version.md
+│   ├── dev/
+│   │   ├── azd-context-inheritance.md
+│   │   ├── environment-variables.md
+│   │   ├── testing.md
+│   │   └── release.md
+│   ├── design/
+│   │   └── ports.md
+│   └── schema/
+│       └── azure.yaml.md
 ├── .github/
 │   └── workflows/
 │       ├── ci.yml              # CI pipeline
@@ -523,7 +543,7 @@ azd app deps
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+We welcome contributions! Please see [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
 
 ### Code Quality Requirements
 
@@ -560,7 +580,7 @@ See [LICENSE](LICENSE) for details.
 
 - **Issues**: [GitHub Issues](https://github.com/jongio/azd-app-extension/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/jongio/azd-app-extension/discussions)
-- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md)
 
 ## Acknowledgments
 

cli/docs/cli-reference.md

@@ -6,7 +6,29 @@ Complete reference for all `azd app` commands and flags.
 
 All commands automatically inherit azd environment context when run through `azd app <command>`. This includes Azure subscription information, resource groups, and environment-specific variables.
 
-See [azd-context.md](azd-context.md) for details on accessing azd environment variables.
+See [dev/azd-context-inheritance.md](dev/azd-context-inheritance.md) for details on accessing azd environment variables.
+
+### Global Flags
+
+These flags are available for all commands:
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--output` | `-o` | string | `default` | Output format (default, json) |
+| `--debug` | | bool | `false` | Enable debug logging |
+| `--structured-logs` | | bool | `false` | Enable structured JSON logging to stderr |
+
+**Examples:**
+```bash
+# Output in JSON format
+azd app reqs --output json
+
+# Enable debug logging
+azd app run --debug
+
+# Enable structured logs for log aggregation
+azd app deps --structured-logs
+```
 
 ## Commands Overview
 
@@ -56,7 +78,6 @@ azd app reqs --clear-cache
 | Flag | Short | Type | Default | Description |
 |------|-------|------|---------|-------------|
 | `--generate` | `-g` | bool | `false` | Generate reqs from detected project dependencies |
-| `--gen` | | bool | `false` | Alias for --generate |
 | `--dry-run` | | bool | `false` | Preview changes without modifying azure.yaml |
 | `--no-cache` | | bool | `false` | Force fresh reqs check and bypass cached results |
 | `--clear-cache` | | bool | `false` | Clear cached reqs results |
@@ -400,7 +421,7 @@ azd app version
 
 Displays the current version of the extension:
 ```
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 **→ [See full version command specification](commands/version.md)** for version format details.
@@ -432,7 +453,7 @@ When running through `azd app <command>`, these variables are automatically avai
 - `AZD_SERVER`: gRPC server address for azd communication
 - `AZD_ACCESS_TOKEN`: Authentication token for azd API
 
-See [azd-context.md](azd-context.md) for complete details.
+See [dev/azd-context-inheritance.md](dev/azd-context-inheritance.md) for complete details.
 
 ### Extension-Specific
 

cli/docs/commands/reqs.md

@@ -316,7 +316,7 @@ project-root/
   "timestamp": "2024-11-04T10:30:00Z",
   "results": [
     {
-      "id": "node",
+      "name": "node",
       "installed": true,
       "version": "20.11.0",
       "required": "18.0.0",
@@ -326,7 +326,7 @@ project-root/
       "message": "Satisfied"
     },
     {
-      "id": "docker",
+      "name": "docker",
       "installed": true,
       "version": "24.0.7",
       "required": "20.0.0",
@@ -452,7 +452,7 @@ reqs:
     checkRunning: true
 
   # Custom tool configuration
-  - id: postgres
+  - name: postgres
     minVersion: "15.0.0"
     command: "psql"
     args: ["--version"]
@@ -467,7 +467,7 @@ reqs:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `id` | string | ✅ | Unique tool identifier |
+| `name` | string | ✅ | Unique tool identifier |
 | `minVersion` | string | ✅ | Minimum version (semantic) |
 | `command` | string | ❌ | Override command to execute |
 | `args` | []string | ❌ | Override command arguments |

cli/docs/commands/version.md

@@ -46,7 +46,7 @@ The version follows **semantic versioning** (semver):
 ```
 MAJOR.MINOR.PATCH
 
-Example: 0.1.0
+Example: 0.5.1
   │    │   │
   │    │   └─ Patch: Bug fixes
   │    └───── Minor: New features (backward compatible)
@@ -59,15 +59,15 @@ Example: 0.1.0
 
 ```bash
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 ### JSON Output (future)
 
 ```bash
 $ azd app version --output json
 {
-  "version": "0.1.0",
+  "version": "0.5.1",
   "commit": "abc1234",
   "buildDate": "2024-11-04T10:00:00Z"
 }
@@ -79,7 +79,7 @@ $ azd app version --output json
 
 ```bash
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 ### 2. Verify Installation
@@ -89,7 +89,7 @@ $ which azd-app
 /usr/local/bin/azd-app
 
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 ### 3. Troubleshooting
@@ -98,7 +98,7 @@ When reporting issues, include version information:
 
 ```bash
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 
 # Include in bug report
 ```
@@ -114,7 +114,7 @@ azd version 1.5.0
 
 # Check azd app version
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 ## Version Compatibility
@@ -146,7 +146,7 @@ The extension is designed to be compatible with:
 
 ```bash
 $ azd app version
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```
 
 ### Example 2: In Scripts
@@ -170,5 +170,5 @@ echo "Using azd app version: $VERSION"
 ```bash
 $ azd version && azd app version
 azd version 1.5.0
-azd app extension version 0.1.0
+azd app extension version 0.5.1
 ```