Make Live workflows and book links verifiable

[stefan-jansen]

Closes #105.

Reader result

The Quickstart now completes a credential-free LiveEngine + SafeBroker shadow run from the published package. The synthetic example requests orderly shutdown after its final bar, so it no longer reports a degraded feed as a successful run. A separate public OKX strategy file makes the bounded CLI shadow command match its feed symbols and emit observable bars without orders.

The Book Guide now links 14 directly rendered notebooks at companion commit d2edec54b1c7a6a9d7a97d8129eb05db4491e1eb. The three stale paths were replaced: 14_backtest -> 13_backtest, 17_risk_management -> 15_risk_management, and the removed okx_funding_rate_demo -> the current 09_crypto_funding_deployment_loop. Each entry says whether it calls Live, teaches a method manually, or shows a related workflow. Major task guides link to matching files and the Book Guide links back.

Capability inventory

Principal task	Task guide	Public reference	Runnable example or check	Book example and status
First strategy and lifecycle	Quickstart; Backtest to Live	LiveEngine, ThreadSafeBrokerWrapper	shadow_mode_demo.py	Unified framework demo calls Live; stable engine
Shadow limits and virtual portfolio	Risk Controls	SafeBroker, LiveRiskConfig, VirtualPortfolio	shadow_mode_demo.py, risk_guard_demo.py	Safety/risk demo calls Live; stable
Broker paper execution	Brokers	IBBroker, AlpacaBroker	ib_paper_equity.py, alpaca_paper_equity.py; preflight is read-only	IB and Alpaca paper notebooks call Live; stable within declared capabilities, service qualification required
Public funding data	Data Feeds; CLI	OKXFundingFeed	okx_shadow_strategy.py with ml4t-live shadow	Crypto funding loop uses OKX data and conditionally calls AlpacaBroker; stable feed, network dependent
Typed aggregation and provider feeds	Data Feeds	BarAggregator, provider feed classes	Feed contract tests; service-specific examples	IB and Alpaca notebooks call Live; aggregation stable, Alpaca/IB/DataBento/CCXT feeds experimental opt-in
Restart and reconciliation	Operator Guide	SafeBroker.reconciliation_report, LiveEngine.runtime_status	startup_reconciliation_demo.py	Runtime safety showcase calls Live; stable reporting, venue reconciliation needed before retry
Backtest-to-live handoff	Backtest to Live; Lifecycle Migration	LiveEngine, canonical order and runtime types	Synthetic shadow run plus existing lifecycle contract tests	Framework parity uses Backtest only; pipeline verification calls Live
Operator inspection	CLI; Operator Guide	CLI and runtime_error_context	status, preflight, bounded shadow	Safe rollout and circuit breaker notebooks teach methods manually

Unsupported order behaviors fail against declared broker capabilities. Experimental feeds require experimental=True and cannot claim stable reconnect continuity. No provider account, paper order, live order, or hardware-dependent path was exercised in this PR.

Verification

• Built the wheel and installed it in an isolated Python 3.12 environment. Ran copied shadow_mode_demo.py, risk_guard_demo.py, and startup_reconciliation_demo.py with python -I; each exited 0 with the documented output markers. The shadow demo ended at final_positions=DEMO:10 without a degraded-runtime message. Also ran the documented uv run --no-project --with ml4t-live command against the published package.
• Ran a 5-second public OKX CLI shadow session: printed a bar, ended with final_health=stopped and orders=0. This checks the public data path at one moment, not provider continuity.
• Checked 25 pinned book file links against the Git tree at d2edec54b1c7a6a9d7a97d8129eb05db4491e1eb; all paths exist. Inspected the corresponding companion scripts for imports and stated workflow. CI now checks the pinned tree.
• Source link check: 130 Markdown links, 0 missing local targets. Rendered content link check: 5,016 links, 0 missing files or anchors. Reviewed Home, Quickstart, and Book Guide in a browser at desktop and 390px width; changed the Book Guide map to readable entries at narrow width.
• uv run mkdocs build --strict: pass.
• uv run ruff check --no-fix src tests examples scripts/qualification: pass.
• uv run ruff format --check src tests examples scripts/qualification: pass.
• uv run ty check: pass.
• uv run pytest -q: 1,051 passed, 29 skipped.

Remaining limits

The Alpaca and IB paper examples need accounts, credentials or TWS/IB Gateway, and market-data access. Experimental feed service behavior requires separate provider qualification. The five-second OKX observation does not establish sustained availability. Live-order examples were reviewed and left unrun. The companion book itself and other repositories are unchanged.

PR checks

At head 588b2d595718e04ea7426e8311afcdc5fbb0a397, all triggered checks completed: 26 passed and the Python 3.15 exception check was skipped as designed. The exact installed-artifact qualification passed.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.