## Summary The CLI uses normal `argparse` global options, so `--repository` and `--config` must appear before the subcommand. This is documented in the reference, but it is an easy mistake during manual or agent operation: ```bash deploybot doctor --repository Forward-Future/DeployBot --json ``` fails with: ```text deploybot: error: unrecognized arguments: --repository Forward-Future/DeployBot ``` The correct form is: ```bash deploybot --repository Forward-Future/DeployBot doctor --json ``` This is not a correctness bug, but it is a usability papercut for an agent-facing tool. ## Evidence The reference documents global options before the command: ```text deploybot [--config PATH] [--repository OWNER/REPO] COMMAND ... ``` The parser defines `--repository` and `--config` on the top-level parser, not on each subcommand. When global options are placed after a subcommand, `argparse` reports them as unrecognized. ## Impact DeployBot is explicitly intended for coding agents and fast operator workflows. Agents frequently synthesize CLI commands in the form: ```bash tool subcommand --global-option value --subcommand-option ``` The current error is technically correct but does not tell the operator the fix. During setup or incident response, this creates unnecessary friction. ## Proposed fix Either: 1. Accept global `--repository` and `--config` after subcommands, or 2. Keep strict top-level parsing but improve the error message/hint when `--repository` or `--config` appears after a subcommand. For example: ```text deploybot: --repository is a global option; put it before the command: deploybot --repository OWNER/REPO doctor --json ``` The lower-risk fix is to add the same optional global flags to subparsers and normalize them into the top-level values, or intercept common parse failures and print a targeted hint. ## Acceptance criteria - [ ] `deploybot doctor --repository owner/repo --json` either works or prints a targeted hint explaining the correct argument order. - [ ] The same behavior applies to `--config`. - [ ] Existing documented command forms continue to work. - [ ] Tests cover global options before and after at least one read-only subcommand. - [ ] The reference docs either document both accepted forms or clearly show the corrected form in the error hint. ## Verification - Add parser tests in `tests/test_cli.py` or `tests/test_docs.py`. - Run `python -m unittest discover -s tests`. - Run `ruff check .`.