From 10c7fd6cbbbe210240f60d8b24e3a1e20435b896 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 30 May 2026 06:16:20 +0000
Subject: [PATCH] docs(site): align CLI command descriptions with actual help
 output

- disable: clarified disabled vs paused behavior (disabled rejects all queue
  requests; paused queues scheduled runs but holds them without executing)
- remove: clarified --yes requirement (more than one match)
- run: added aggregate result note for --wait exit code behavior
- run: clarified --poll-interval and --timeout units (seconds)
- mcp/mcp-http: explained bounding_directory security purpose
- mcp/mcp-http: clarified --enabled-tools behavior (all tools exposed when omitted)
- Standardized "preview" verb for --dry-run (was "print")

All changes verified against actual CLI help output from ado-aw 0.30.2.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 site/src/content/docs/setup/cli.mdx | 30 ++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/site/src/content/docs/setup/cli.mdx b/site/src/content/docs/setup/cli.mdx
index 11a3cb97..407ab843 100644
--- a/site/src/content/docs/setup/cli.mdx
+++ b/site/src/content/docs/setup/cli.mdx
@@ -154,13 +154,13 @@ Options:
 
 ### `disable [path]`
 
-Set `queueStatus` to `disabled` (or `paused`) on every matched ADO definition.
+Set `queueStatus` to `disabled` (or `paused`) on every matched ADO definition. Disabled definitions reject all queue requests; paused definitions queue scheduled runs but hold them without executing.
 
 Options:
 
-- `--paused` -- use `queueStatus: paused` instead of `disabled`; paused definitions still queue scheduled runs but hold the queue, while disabled definitions reject all queue requests
+- `--paused` -- set `queueStatus` to `paused` instead of `disabled`
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned transitions without calling the ADO API
+- `--dry-run` -- preview the planned transitions without calling the ADO API
 
 ### `remove [path]`
 
@@ -168,9 +168,9 @@ Options:
 
 Options:
 
-- `--yes` -- required for bulk deletes and for any delete in a non-tty context
+- `--yes` -- required for bulk deletes (more than one match) and for any delete in a non-tty context
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned deletions without calling the ADO API
+- `--dry-run` -- preview the planned deletions without calling the ADO API
 
 ### `list [path]`
 
@@ -202,12 +202,12 @@ ado-aw run [path] [--wait] [--parameters key=value]
 Options:
 
 - `--branch <ref>` -- source branch to queue (defaults to the definition's `defaultBranch`)
-- `--parameters <k=v>` -- ADO `templateParameters` as `key=value` pairs; repeatable and/or comma-separated. Values must not contain commas — use one `--parameters` flag per pair when values contain commas.
-- `--wait` -- poll each queued build to completion before exiting
-- `--poll-interval <secs>` -- polling interval when `--wait` is set (default: `10`)
-- `--timeout <secs>` -- maximum wait time when `--wait` is set (default: `1800`)
+- `--parameters <k=v>` -- ADO `templateParameters` as `key=value` pairs; repeatable and/or comma-separated. Values must not contain commas — use one `--parameters` flag per pair when values contain commas
+- `--wait` -- poll each queued build to completion before exiting; aggregate result determines the exit code
+- `--poll-interval <secs>` -- seconds between polls when `--wait` is set (default: `10`)
+- `--timeout <secs>` -- maximum seconds to wait when `--wait` is set (default: `1800`)
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned queue body without calling the ADO API
+- `--dry-run` -- preview the planned queue body without calling the ADO API
 
 ## Internal / pipeline runtime commands
 
@@ -215,7 +215,7 @@ These commands are used by the compiled pipeline itself and are not typically ca
 
 ### `mcp <output_directory> <bounding_directory>`
 
-Run SafeOutputs as a stdio MCP server (used by Stage 1).
+Run SafeOutputs as a stdio MCP server (used by Stage 1). The `<bounding_directory>` guards against directory traversal attacks by ensuring the agent cannot influence folders outside this path.
 
 ```bash
 ado-aw mcp <output_directory> <bounding_directory> [--enabled-tools <name>]
@@ -223,11 +223,11 @@ ado-aw mcp <output_directory> <bounding_directory> [--enabled-tools <name>]
 
 Options:
 
-- `--enabled-tools <name>` -- limit the server to specific tools; repeat to allow more than one
+- `--enabled-tools <name>` -- only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed
 
 ### `mcp-http <output_directory> <bounding_directory>`
 
-Run SafeOutputs as an HTTP MCP server (for MCPG integration).
+Run SafeOutputs as an HTTP MCP server (for MCPG integration). The `<bounding_directory>` guards against directory traversal attacks.
 
 ```bash
 ado-aw mcp-http <output_directory> <bounding_directory> [options]
@@ -236,8 +236,8 @@ ado-aw mcp-http <output_directory> <bounding_directory> [options]
 Options:
 
 - `--port <port>` -- port to listen on (default: `8100`)
-- `--api-key <key>` -- API key for authentication (auto-generated if not provided)
-- `--enabled-tools <name>` -- limit the server to specific tools; repeat to allow more than one
+- `--api-key <key>` -- API key for authentication (if not provided, one is generated)
+- `--enabled-tools <name>` -- only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed
 
 ### `execute`