[AAASM-4656] ✨ (cli): Add aasm --version and fix README error-handling example

[Chisanan232]

Description

Two small doc/UX fixes for the aasm CLI and the README:

1. aasm --version — previously argparse rejected --version (exit 2). Added an argparse action="version" flag that prints aasm <version> sourced from agent_assembly.__version__ and exits 0.
2. README "Error Handling" example — the snippet passed gateway_url="" inside a try/except ConfigurationError, implying an empty gateway_url raises ConfigurationError. It does not: resolve_gateway_url treats an empty/unset value as unset and falls through to local auto-discovery (probe localhost, then auto-start), which surfaces GatewayError (or ConfigurationError only if the aasm binary is absent). Rewrote the example to demonstrate ConfigurationError with a genuinely-invalid config (an invalid mode), which validation rejects up front before any network I/O, and added a note on the real empty/unset behavior.

Type of Change

• ✨ New feature
• 🔧 Bug fix
• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-4656

Testing

Describe the testing performed for this PR:

• Unit tests added/updated — TestCliMainVersion asserts aasm --version prints the expected version and exits 0.
• Manual testing performed — .venv/bin/aasm --version prints aasm 0.0.1rc5, exit 0.
• ruff check / ruff format --check clean on changed files; mypy agent_assembly/cli/main.py clean; CLI test suite passes (4 passed).
• The README-only change runs no CI (docs excluded from ci.yaml paths).

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed
• All tests passing

🤖 Generated with Claude Code

https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

🤖 Claude Code — PR review

Verdict: ✅ Ready to approve & merge.

1. CI: Green — unit + integration tests pass (3.13/ubuntu), CI Success SUCCESS, SonarCloud SUCCESS, codecov/patch SUCCESS, pip-audit + CodeQL SUCCESS.

2. Scope vs AAASM-4656: Both AC items covered — (a) aasm --version implemented via argparse action="version" sourcing __version__, with a unit test asserting it prints aasm <version> and exits 0; (b) the README 'Error Handling' example is corrected to actually raise ConfigurationError (invalid mode, rejected up front) with a note clarifying that an empty/unset gateway_url is not an error (→ local discovery) and an unreachable gateway raises GatewayError.

3. Side effects: None. --version is additive (no collision with the adapter subcommand). from agent_assembly import __version__ at the CLI module top imports the same package the CLI already belongs to — no new import risk. README change is doc-only.

4. Front-end: N/A.

No changes requested.