0.5.0 stabilization & docs polish

[SimonTarara62]

Post-release verification of v0.5.0 — proves the published artifact, CLI, and SDK are stable, and brings the GitHub-published docs into accurate agreement with the code. Tests + docs only; no production source changed.

Badge question (answered, no repo fix)

PyPI has 0.5.0 and the shields.io endpoints already return v0.5.0; the README badges are all dynamic. A stale badge image on GitHub is the Camo image-proxy/browser cache, which self-corrects — nothing in the repo was wrong.

Stability verified

• Published wheel: clean-room pip install capitalcom-cli==0.5.0 imports capital_cli.sdk + capital_cli.services (the new packages shipped); locally-built wheel contains all four subpackages.
• Full CLI e2e against demo: all tests pass; account left flat.
• Expanded SDK e2e against demo (in-process, no CLI subprocess): risk policy, markets/prices, trading preview, watchlist lifecycle, streaming, and a full opt-in trade lifecycle (execute→close, account flat) — proving the SDK is consistent with the CLI.
• Offline: make check green (253 passed, 2 skipped).

Real defects found & fixed (tests/harness only)

1. Stale NDJSON streaming e2e — test_16/test_23 asserted a pre-NDJSON summary shape; latently broken since the P2 NDJSON change. Now parse NDJSON and assert per-line PriceTick/OHLCBar shape.
2. In-process e2e read the wrong env — the offline autouse _credentials fixture mis-pointed CAP_ENV_FILE at a dummy file, so the SDK e2e saw fake creds / CAP_ALLOW_TRADING=false (and only "passed" reads via leaked sessions). Added tests/e2e/conftest.py to re-point in-process e2e at the real .env; the SDK trade lifecycle now passes under the same env the CLI suite uses.
3. SDK streaming test never ran — gated on os.environ but CAP_WS_ENABLED lives in .env; re-gated on the loaded config so it actually exercises SDK streaming against demo.
4. SDK mutation-guard coverage — new offline test proving an SDK consumer with stock config gets ConfirmRequiredError (no silent write) through the real risk engine.

Docs polished

• README: fixed a now-false "session tokens are not persisted" claim, added CAP_PERSIST_SESSION config row, --limit in the command reference, SDK/session-cache discoverability.
• troubleshooting.md: 429→session-cache mitigation, state-file contents.
• CONTRIBUTING.md: project layout updated for services//sdk/.
• Verified docs/sdk.md examples, exit-code tables, api-coverage, and all internal links (0 broken).

Test plan

• make check green; full CLI + SDK e2e green against demo (account flat).
• CI must pass on ubuntu + windows (3.10/3.11/3.12).

🤖 Generated with Claude Code