docs(cli): document --quiet/--silent as global options that precede the subcommand

CHANGELOG.md

@@ -70,6 +70,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   stays clickable for running items too.
   ([#273](https://github.com/microsoft/conductor/pull/273))
 
+### Documentation
+
+- **`--quiet` / `--silent` documented as `run` options** — both flags are
+  root-level options defined on the app callback, so they must appear *before*
+  the subcommand (`conductor --quiet run workflow.yaml`); placing them after it
+  is rejected with "No such option". `docs/cli-reference.md` and the README
+  listed them in the `conductor run` options table, while `docs/cli-reference.md`
+  also showed post-subcommand examples (`conductor run workflow.yaml --quiet`)
+  that fail as written — as did the `conductor run --help` epilog. Moved the
+  flags to a new Root-Level Options section, corrected the examples (docs and
+  `--help` text), and fixed the same mis-ordering in the conductor skill's
+  quick reference.
+
 ## [0.1.20](https://github.com/microsoft/conductor/compare/v0.1.19...v0.1.20) - 2026-06-26
 
 ### Added

README.md

@@ -305,10 +305,16 @@ conductor run <workflow.yaml> [OPTIONS]
 | `--web` | Start real-time web dashboard |
 | `--web-bg` | Run in background, print dashboard URL, exit |
 | `--web-port PORT` | Port for web dashboard (0 = auto) |
-| `-q, --quiet` | Suppress progress output |
-| `-s, --silent` | Suppress all output except errors |
 | `-l, --log-file PATH` | Write logs to file |
 
+Output verbosity is controlled by **root-level options**, which must appear
+*before* the subcommand:
+
+```bash
+conductor --quiet run workflow.yaml    # -q: minimal output (agent lifecycle and routing only)
+conductor --silent run workflow.yaml   # -s: no progress output (JSON result only)
+```
+
 ### `conductor validate`
 
 Validate a workflow file without executing.

docs/cli-reference.md

@@ -4,13 +4,40 @@ Complete command-line reference for Conductor.
 
 ## Table of Contents
 
+- [Root-Level Options](#root-level-options)
 - [`conductor run`](#conductor-run)
 - [`conductor stop`](#conductor-stop)
 - [`conductor gate-respond`](#conductor-gate-respond)
 - [`conductor validate`](#conductor-validate)
 - [`conductor doctor`](#conductor-doctor)
 - [`conductor registry`](#conductor-registry)
 
+## Root-Level Options
+
+The following root-level options **must appear before the
+subcommand name**:
+
+```bash
+conductor [ROOT OPTIONS] <command> [ARGS] [OPTIONS]
+```
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--quiet` | `-q` | Minimal output (agent lifecycle and routing only) |
+| `--silent` | `-s` | No progress output (JSON result only) |
+| `--version` | `-v` | Show version and exit |
+
+`--quiet` and `--silent` are mutually exclusive. They control workflow
+progress output (`run` / `resume`); other commands may not be affected.
+
+```bash
+# Correct: root-level option before the subcommand
+conductor --quiet run workflow.yaml
+
+# Incorrect: rejected with "No such option: --quiet"
+conductor run workflow.yaml --quiet
+```
+
 ## `conductor run`
 
 Execute a workflow from a YAML file.
@@ -31,14 +58,16 @@ conductor run <workflow.yaml> [OPTIONS]
 | `--provider PROVIDER` | `-p` | Override provider (copilot, claude, claude-agent-sdk, hermes) |
 | `--dry-run` | | Show execution plan without running |
 | `--skip-gates` | | Auto-select first option at human gates |
-| `--quiet` | `-q` | Minimal output (agent lifecycle and routing only) |
-| `--silent` | `-s` | No progress output (JSON result only) |
 | `--log-file <auto\|PATH>` | `-l` | Write full debug output to a file |
 | `--web` | | Start a real-time web dashboard |
 | `--web-bg` | | Run in background, print dashboard URL, exit |
 | `--web-port PORT` | | Port for web dashboard (0 = auto-select) |
 | `--no-interactive` | | Disable Esc-to-interrupt capability |
 
+> **Note:** Output verbosity (`--quiet`/`-q`, `--silent`/`-s`) is controlled by
+> [root-level options](#root-level-options), which must appear *before* the
+> `run` subcommand: `conductor --quiet run workflow.yaml`.
+
 ### Examples
 
 #### Basic Execution
@@ -70,8 +99,9 @@ conductor run workflow.yaml -p copilot
 # Preview execution plan without running
 conductor run workflow.yaml --dry-run
 
-# Quiet output (agent lifecycle only)
-conductor run workflow.yaml --quiet --input question="Test"
+# Quiet output (agent lifecycle only) — note: --quiet is a root-level option
+# and must come before the run subcommand
+conductor --quiet run workflow.yaml --input question="Test"
 
 # Write full debug log to a file
 conductor run workflow.yaml --log-file debug.log
@@ -122,7 +152,8 @@ Background workflows can be stopped with `conductor stop` (see below) or via the
 conductor run workflow.yaml --skip-gates
 
 # CI/CD pattern: silent console + full file log
-conductor run workflow.yaml --silent --log-file auto --skip-gates --input question="Automated test"
+# (--silent is a root-level option and must come before the run subcommand)
+conductor --silent run workflow.yaml --log-file auto --skip-gates --input question="Automated test"
 ```
 
 #### Metadata and Instructions

plugins/conductor/skills/conductor/SKILL.md

@@ -24,8 +24,8 @@ Conductor is installed automatically when needed. If a `conductor` command fails
 
 ```bash
 conductor run workflow.yaml --input question="Hello"     # Execute (full output by default)
-conductor run workflow.yaml -q --input question="Hello"  # Quiet: lifecycle + routing only
-conductor run workflow.yaml -s --input question="Hello"  # Silent: JSON result only
+conductor -q run workflow.yaml --input question="Hello"  # Quiet: lifecycle + routing only
+conductor -s run workflow.yaml --input question="Hello"  # Silent: JSON result only
 conductor run workflow.yaml --log-file auto               # Log full debug output to file
 conductor run workflow.yaml --web --input q="Hello"       # Real-time web dashboard
 conductor run workflow.yaml --web-bg --input q="Hello"    # Background mode (prints URL, exits)
@@ -45,7 +45,7 @@ conductor resume workflow.yaml --web                     # Resume with dashboard
 conductor checkpoints                                    # List available checkpoints
 ```
 
-Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only.
+Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only — both are root-level options and must come *before* the subcommand (`conductor -q run ...`, not `conductor run ... -q`).
 
 ## When to Use Each Guide
 

src/conductor/cli/app.py

@@ -406,7 +406,7 @@ def run(
         conductor run workflow.yaml --skip-gates
         conductor run workflow.yaml --log-file auto
         conductor run workflow.yaml --log-file debug.log
-        conductor run workflow.yaml --silent --log-file auto
+        conductor --silent run workflow.yaml --log-file auto
         conductor run workflow.yaml --no-interactive
         conductor run workflow.yaml --web
         conductor run workflow.yaml --web --web-port 8080