Accept global CLI options after subcommands or improve the error hint

[coygeek]

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:

deploybot doctor --repository Forward-Future/DeployBot --json

fails with:

deploybot: error: unrecognized arguments: --repository Forward-Future/DeployBot

The correct form is:

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:

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:

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:

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 ..