docs: enrich --help and skills for LLM consumption

  * 27 command modules: enriched every doc: string with:
    - Valid values for enum options (states, types, visibility)
    - Default behaviors (page sizes, sort orders, output format)
    - Output format descriptions (table columns, JSON shape)
    - Argument format hints (GUID vs numeric ID vs name)
    - Practical usage notes (case sensitivity, required permissions)

  * 3 skills rewritten for LLM agent optimization:
    - ado-cli: structured command ref, decision tree, pitfalls,
      non-obvious behaviors (multi-word flags, MSA orgs, exit codes)
    - ado-auth: decision tree for auth method selection,
      troubleshooting table with version-specific fixes,
      CI/headless patterns
    - ado-ci: binary download matrix (5 platforms), PAT scope table,
      GitHub/GitLab CI examples, common CI pitfalls
    - All bumped to v0.4.3 with updated command lists

  * 337 tests pass, credo clean, all 8 CI stages green.
  * 30 files changed, +1620/-676 lines.

Author: gilbertwong96

lib/ado_cli/cli/agent_pools.ex

@@ -16,28 +16,35 @@ defmodule AdoCli.CLI.AgentPools do
   def command do
     [
       name: "ado agent-pools",
-      doc: "Manage Azure DevOps agent pools and queues.",
+      doc:
+        "Manage Azure DevOps agent pools and queues. Pools host agents; queues are project-scoped views into pools used for pipeline runs.",
       subcommands: [
         list: [
           name: "ado agent-pools list",
-          doc: "List agent pools in the organization.",
+          doc:
+            "List every agent pool in the organization. Output is a table by default (ID, Name, Auto-provision, Type); pass --json for a machine-readable array. Use this to discover pool IDs for use with `pipelines-builds queue --pool` or for agent management.",
           execute: &list_pools/1
         ],
         show: [
           name: "ado agent-pools show",
-          doc: "Show details of an agent pool, including agents.",
-          arguments: [pool_id: [type: :integer, doc: "Agent pool ID"]],
+          doc:
+            "Show details of an agent pool, including its agents and their status. The pool ID is an integer (not a name); use `ado agent-pools list` to look it up.",
+          arguments: [pool_id: [type: :integer, doc: "Numeric agent pool ID"]],
           execute: &show_pool/1
         ],
         queues: [
           name: "ado agent-pools queues",
-          doc: "Manage agent queues.",
+          doc:
+            "Manage agent queues. A queue is a project-scoped alias for a pool — pipelines run on a queue, not a pool directly.",
           subcommands: [
             list: [
               name: "ado agent-pools queues list",
-              doc: "List agent queues.",
+              doc:
+                "List agent queues in a project. Output is a table (ID, Name, Pool); pass --json for raw data. Use --pool to filter by a specific pool's queues.",
               arguments: [project: [type: :string, doc: "Project name or ID"]],
-              options: [pool: [type: :integer, doc: "Filter by pool ID", doc_arg: "POOL_ID"]],
+              options: [
+                pool: [type: :integer, doc: "Filter by numeric agent pool ID", doc_arg: "POOL_ID"]
+              ],
               execute: &list_queues/1
             ]
           ]

lib/ado_cli/cli/areas.ex

@@ -11,50 +11,83 @@ defmodule AdoCli.CLI.Areas do
   def command do
     [
       name: "ado areas",
-      doc: "Manage Azure DevOps area paths (classification nodes).",
+      doc:
+        "Manage Azure DevOps area paths (classification nodes). Areas organize work items into a hierarchy (e.g. 'Project\\Team\\Feature') for filtering and reporting.",
       subcommands: [
         list: [
           name: "ado areas list",
-          doc: "List area paths in a project.",
+          doc:
+            "List area paths in a project as a tree (default: only top-level; use --depth for children). Output is a hierarchical tree by default; pass --json for the raw root node with nested children.",
           arguments: [project: [type: :string, doc: "Project name or ID"]],
-          options: [depth: [type: :integer, doc: "Depth of children to retrieve", doc_arg: "N"]],
+          options: [
+            depth: [
+              type: :integer,
+              doc: "Depth of children to retrieve (1 = top-level only, 2 = includes sub-areas)",
+              doc_arg: "N"
+            ]
+          ],
           execute: &list_areas/1
         ],
         show: [
           name: "ado areas show",
-          doc: "Show details of an area path.",
+          doc:
+            "Show details of a single area path (ID, name, full path, structure type). Returns 404 if the path does not exist.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
-            area_path: [type: :string, doc: "Area path (e.g. ProjectName\Area\SubArea)"]
+            area_path: [
+              type: :string,
+              doc:
+                "Area path using backslashes (e.g. MyProject\\Area\\SubArea). Escape the backslash in shells or wrap in single quotes."
+            ]
           ],
           execute: &show_area/1
         ],
         create: [
           name: "ado areas create",
-          doc: "Create an area path.",
+          doc:
+            "Create a new area path. Omit --parent to create at the project root, or pass --parent to nest under an existing area.",
           arguments: [project: [type: :string, doc: "Project name or ID"]],
           options: [
-            name: [type: :string, required: true, doc: "Area name", doc_arg: "NAME"],
-            parent: [type: :string, doc: "Parent area path", doc_arg: "PATH"]
+            name: [
+              type: :string,
+              required: true,
+              doc: "Name for the new area path (no backslashes)",
+              doc_arg: "NAME"
+            ],
+            parent: [
+              type: :string,
+              doc:
+                "Parent area path to nest under (e.g. MyProject\\Team). Omit to create at the root.",
+              doc_arg: "PATH"
+            ]
           ],
           execute: &create_area/1
         ],
         update: [
           name: "ado areas update",
-          doc: "Rename an area path.",
+          doc:
+            "Rename an existing area path. Only the leaf name is changed; the path prefix is preserved.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
-            area_path: [type: :string, doc: "Current area path"]
+            area_path: [type: :string, doc: "Current area path (e.g. MyProject\\OldName)"]
+          ],
+          options: [
+            name: [
+              type: :string,
+              required: true,
+              doc: "New name (no backslashes)",
+              doc_arg: "NAME"
+            ]
           ],
-          options: [name: [type: :string, required: true, doc: "New name", doc_arg: "NAME"]],
           execute: &update_area/1
         ],
         delete: [
           name: "ado areas delete",
-          doc: "Delete an area path.",
+          doc:
+            "Delete an area path. Fails if the area has child areas or work items still assigned to it; reassign or remove those first.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
-            area_path: [type: :string, doc: "Area path to delete"]
+            area_path: [type: :string, doc: "Area path to delete (e.g. MyProject\\OldArea)"]
           ],
           execute: &delete_area/1
         ]

lib/ado_cli/cli/auth_commands.ex

@@ -20,26 +20,31 @@ defmodule AdoCli.CLI.AuthCommands do
   def command do
     [
       name: "ado login",
-      doc: "Authenticate with Azure DevOps.",
+      doc:
+        "Authenticate with Azure DevOps. Default (no --method) opens your browser for interactive OAuth sign-in. For CI or headless environments, use --method pat with a Personal Access Token. Use --method device to print a code+URL for signing in on any device. After login, credentials are stored in ~/.ado_cli/config.json with 0600 permissions.",
       options: [
         method: [
           type: :string,
-          doc: "Auth method: browser (default), pat, device",
+          doc:
+            "Auth method. Valid: browser (default — interactive OAuth, supports AAD and MSA orgs), pat (Personal Access Token; required for CI), device (device code flow; visit URL on any device).",
           doc_arg: "METHOD"
         ],
         org: [
           type: :string,
-          doc: "Azure DevOps organization / collection name",
+          doc:
+            "Azure DevOps organization name. Optional for browser/device login (the org is auto-detected from the token). Required for PAT login. Can also be set via ADO_ORG env var.",
           doc_arg: "ORG"
         ],
         server: [
           type: :string,
-          doc: "Server URL for self-hosted Azure DevOps Server",
+          doc:
+            "Server URL for self-hosted Azure DevOps Server (e.g. https://ado.example.com). Cloud users can omit this. Can also be set via ADO_SERVER env var.",
           doc_arg: "URL"
         ],
         pat: [
           type: :string,
-          doc: "Personal Access Token (for method=pat)",
+          doc:
+            "Personal Access Token. Only used with --method pat. Generate at https://dev.azure.com/{org}/_usersSettings/tokens. Required scopes depend on usage: vso.work (work items), vso.code (repos, PRs), vso.project (projects/teams), vso.build (pipelines), vso.release (releases). Use 'Full access' for broadest coverage.",
           doc_arg: "TOKEN"
         ]
       ],

lib/ado_cli/cli/banners.ex

@@ -11,34 +11,46 @@ defmodule AdoCli.CLI.Banners do
   def command do
     [
       name: "ado banners",
-      doc: "Manage organization-wide notification banners.",
+      doc:
+        "Manage the organization-wide notification banner that appears at the top of the Azure DevOps web UI for every user. Useful for maintenance windows or org-wide announcements.",
       subcommands: [
         show: [
           name: "ado banners show",
-          doc: "Show the current organization banner.",
+          doc:
+            "Show the current organization banner. Prints 'No banner configured.' if no banner is set, or the message, type, and audience level otherwise. Pass --json for raw output.",
           execute: &show_banner/1
         ],
         set: [
           name: "ado banners set",
-          doc: "Set or update the organization banner.",
+          doc:
+            "Set or update the organization banner. The banner appears immediately for all users in the org (or for the chosen audience level). Replaces any existing banner.",
           options: [
-            message: [type: :string, required: true, doc: "Banner text", doc_arg: "MSG"],
+            message: [
+              type: :string,
+              required: true,
+              doc:
+                "Banner text shown to users. Markdown is not supported; the text is rendered as plain text. Multi-word values do not need quoting (joined until next flag). Use @<file> or - to read from a file/stdin.",
+              doc_arg: "MSG"
+            ],
             type: [
               type: :string,
-              doc: "Banner type: info|warning|error (default: info)",
+              doc:
+                "Visual style. Valid: info (default — blue), warning (yellow), error (red). Controls the icon and color in the web UI.",
               doc_arg: "TYPE"
             ],
             level: [
               type: :string,
-              doc: "Audience level (default: projectCollection)",
+              doc:
+                "Audience level. Valid: projectCollection (default — whole org), project (specific project — requires the project context).",
               doc_arg: "LEVEL"
             ]
           ],
           execute: &set_banner/1
         ],
         delete: [
           name: "ado banners delete",
-          doc: "Remove the organization banner.",
+          doc:
+            "Remove the organization banner. Errors if no banner is set; otherwise the banner disappears immediately for all users.",
           execute: &delete_banner/1
         ]
       ]

lib/ado_cli/cli/branch_policies.ex

@@ -12,31 +12,42 @@ defmodule AdoCli.CLI.BranchPolicies do
   def command do
     [
       name: "ado repos policies",
-      doc: "Manage branch policies (pull request, build, status, etc.).",
+      doc:
+        "Manage branch policies that gate pull requests (build validation, required reviewers, status checks, etc.). A policy is a configuration object scoped to a specific branch and repository.",
       subcommands: [
         list: [
           name: "ado repos policies list",
-          doc: "List branch policies in a repository.",
+          doc:
+            "List branch policies in a repository as a table (ID, Type, Branch, Blocking, Enabled). Use --branch to filter to a single branch (e.g. main). Pass --json for the raw array.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
             repo_id: [type: :string, doc: "Repository name or ID"]
           ],
-          options: [branch: [type: :string, doc: "Filter by branch name", doc_arg: "BRANCH"]],
+          options: [
+            branch: [
+              type: :string,
+              doc:
+                "Filter by branch name. Pass the full ref like 'refs/heads/main', or just 'main' (substring match)",
+              doc_arg: "BRANCH"
+            ]
+          ],
           execute: &list_policies/1
         ],
         show: [
           name: "ado repos policies show",
-          doc: "Show details of a policy.",
+          doc:
+            "Show details of a single policy (ID, type, branch, repo, blocking, enabled, created date). Use `list` first to discover the policy ID.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
             repo_id: [type: :string, doc: "Repository name or ID"],
-            policy_id: [type: :integer, doc: "Policy configuration ID"]
+            policy_id: [type: :integer, doc: "Numeric policy configuration ID (from `list`)"]
           ],
           execute: &show_policy/1
         ],
         create: [
           name: "ado repos policies create",
-          doc: "Create a branch policy.",
+          doc:
+            "Create a new branch policy. The policy type is identified by a UUID; common ones are: fa4e907d-c16b-4a4c-9dfa-4906e5d171dd (Build validation), fd2167ab-9d2a-4d8b-b2c9-1cdfbb6d4c34 (Required reviewers), 0609b952-1397-4640-95ec-e121a052fb4b (Status check).",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
             repo_id: [type: :string, doc: "Repository name or ID"]
@@ -45,40 +56,55 @@ defmodule AdoCli.CLI.BranchPolicies do
             type: [
               type: :string,
               required: true,
-              doc: "Policy type id (UUID)",
+              doc:
+                "Policy type UUID. Find these in the Azure DevOps UI under Project Settings > Repos > Policies > any policy > URL contains 'policyType='.",
               doc_arg: "TYPE_ID"
             ],
             branch: [
               type: :string,
               required: true,
-              doc: "Target branch (e.g. refs/heads/main)",
+              doc:
+                "Target branch as a ref (e.g. 'refs/heads/main', 'refs/heads/feature/*' for wildcards)",
               doc_arg: "BRANCH"
             ],
-            blocking: [type: :boolean, default: true, doc: "Block pull request on policy failure"]
+            blocking: [
+              type: :boolean,
+              default: true,
+              doc:
+                "When true (default), PRs cannot be completed until the policy passes. When false, the policy is informational only."
+            ]
           ],
           execute: &create_policy/1
         ],
         update: [
           name: "ado repos policies update",
-          doc: "Update a branch policy.",
+          doc:
+            "Modify an existing policy's blocking flag or enabled state. The policy type and scope are preserved from the existing policy.",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
             repo_id: [type: :string, doc: "Repository name or ID"],
-            policy_id: [type: :integer, doc: "Policy configuration ID"]
+            policy_id: [type: :integer, doc: "Numeric policy configuration ID"]
           ],
           options: [
-            blocking: [type: :boolean, doc: "Block pull request on policy failure"],
-            enabled: [type: :boolean, doc: "Enable or disable the policy"]
+            blocking: [
+              type: :boolean,
+              doc: "Set whether the policy blocks PR completion. Omit to keep current value."
+            ],
+            enabled: [
+              type: :boolean,
+              doc: "Set whether the policy is active. Omit to keep current value."
+            ]
           ],
           execute: &update_policy/1
         ],
         delete: [
           name: "ado repos policies delete",
-          doc: "Delete a branch policy.",
+          doc:
+            "Permanently remove a branch policy. The policy is removed from all branches it was scoped to (usually just one).",
           arguments: [
             project: [type: :string, doc: "Project name or ID"],
             repo_id: [type: :string, doc: "Repository name or ID"],
-            policy_id: [type: :integer, doc: "Policy configuration ID"]
+            policy_id: [type: :integer, doc: "Numeric policy configuration ID"]
           ],
           execute: &delete_policy/1
         ]