feat: harden live runtime operations and docs

Author: Stefan Jansen

.agents/shared-context.md

@@ -0,0 +1,31 @@
+# Shared Project Context: ml4t-live
+
+## Package
+
+- Package name: `ml4t-live`
+- Import path: `ml4t.live`
+- Purpose: live trading with zero-code migration from `ml4t-backtest`
+
+## Core Surface
+
+- `engine.py` - live engine orchestration
+- `wrappers.py` - sync to async strategy bridge
+- `safety.py` - risk controls, shadow mode, VirtualPortfolio
+- `brokers/` - Interactive Brokers and Alpaca adapters
+- `feeds/` - Alpaca, IB, Databento, CCXT, OKX, and aggregation
+
+## Workflow
+
+```bash
+uv sync
+uv run ruff check src/
+uv run ruff format src/
+uv run ty check
+uv run pytest tests/ -q
+```
+
+## Safety
+
+- Start with `shadow_mode=True`
+- Keep public symbols stable for book and notebook consumers
+- Treat docs, examples, and tests as part of the shipped library surface

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 env:
-  PYTHON_VERSION: "3.11"
+  PYTHON_VERSION: "3.12"
   UV_NO_SOURCES: "1"
 
 jobs:
@@ -60,7 +60,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
     tags: ["v*"]
 
 env:
-  PYTHON_VERSION: "3.11"
+  PYTHON_VERSION: "3.12"
   UV_NO_SOURCES: "1"
 
 jobs:

AGENT.md

@@ -0,0 +1,10 @@
+# ml4t-live
+
+Codex uses `AGENTS.md` as the repo entry point.
+
+@.agents/shared-context.md
+
+## Navigation
+
+- `src/ml4t/live/AGENTS.md` provides the package-level module index
+- Public entry point: `from ml4t.live import LiveEngine`

AGENTS.md

@@ -1,6 +1,6 @@
 # ml4t-live
 
-[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/ml4t-live)](https://pypi.org/project/ml4t-live/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 

README.md

@@ -2,14 +2,14 @@
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.12+
 - A supported broker or data source for live use
 - `ml4t-backtest` is installed automatically as a package dependency
 
 ## Install From PyPI
 
 ```bash
-pip install ml4t-live
+uv add ml4t-live
 ```
 
 ## Optional Add-Ons
@@ -18,7 +18,7 @@ pip install ml4t-live
 be installed separately if you want `DataBentoFeed`:
 
 ```bash
-pip install databento
+uv add databento
 ```
 
 ## Install From Source

docs/getting-started/installation.md

@@ -89,6 +89,9 @@ feed = BarAggregator(raw_feed, bar_size_minutes=1, flush_timeout_seconds=2.0)
 ## Next Steps
 
 - [Installation](installation.md)
+- [Risk Controls](../user-guide/risk.md)
+- [CLI](../user-guide/cli.md)
+- [Examples](../user-guide/examples.md)
+- [Operator Guide](../user-guide/operator-guide.md)
 - [Brokers](../user-guide/brokers.md)
 - [Data Feeds](../user-guide/feeds.md)
-- [Risk Controls](../user-guide/risk.md)

docs/getting-started/quickstart.md

@@ -52,7 +52,9 @@ With `ml4t-live`, you can:
 - connect that strategy to Alpaca or Interactive Brokers
 - replay or stream data through a live-style feed interface
 - start in `shadow_mode=True` so orders are tracked but not routed
-- add hard limits for order size, exposure, order rate, and drawdown before going live
+- add hard limits for order size, exposure, stale data, daily loss, and drawdown before going live
+- inspect persisted state and broker reachability with `ml4t-live status`
+- run bounded shadow sessions from the CLI before promoting to paper or live
 
 If you do not yet have a validated strategy, start in `ml4t-backtest`. If you do have one, this is the
 next layer.
@@ -249,6 +251,11 @@ See [Brokers](user-guide/brokers.md) for connection details and usage patterns.
 
 Use [Data Feeds](user-guide/feeds.md) for examples and feed-specific setup.
 
+## Operator Surfaces
+
+The library now includes a small CLI and a set of bounded operator-focused examples.
+Use [CLI](user-guide/cli.md) for `status` and `shadow`, [Examples](user-guide/examples.md) for runnable scripts, and [Operator Guide](user-guide/operator-guide.md) for the recommended promotion workflow.
+
 ## Installation
 
 ```bash

docs/index.md

@@ -7,11 +7,10 @@
 
 ## Broker Model
 
-The raw broker implementations are asynchronous. They implement `AsyncBrokerProtocol` and are meant
-to be used by `LiveEngine` and `SafeBroker`.
+The raw broker implementations are asynchronous and satisfy `AsyncBrokerProtocol`. In normal usage they sit behind `SafeBroker`, and strategies interact with a synchronous broker wrapper created by `LiveEngine`.
 
-- Strategy code uses synchronous broker calls such as `broker.get_position(...)`
-- Raw broker instances use async methods such as `await broker.get_cash_async()`
+- Strategy code uses synchronous calls such as `broker.get_position(...)` and `broker.submit_order(...)`
+- Infrastructure code uses async methods such as `await broker.get_cash_async()`
 
 ## Interactive Brokers
 
@@ -20,8 +19,9 @@ from ml4t.live import IBBroker
 
 broker = IBBroker(
     host="127.0.0.1",
-    port=7497,  # paper
+    port=7497,  # paper TWS
     client_id=1,
+    account=None,
 )
 
 await broker.connect()
@@ -31,7 +31,8 @@ await broker.connect()
 
 - `7497` is the usual TWS paper port
 - `7496` is the usual TWS live port
-- You must have TWS or IB Gateway running with API access enabled
+- `4002` and `4001` are the usual paper/live IB Gateway ports
+- TWS or IB Gateway must be running with API access enabled before you connect
 
 ## Alpaca
 
@@ -49,9 +50,8 @@ await broker.connect()
 
 ### Notes
 
-- `paper=True` is the safe default
-- The broker maintains positions and pending orders internally from Alpaca account state and trade
-  updates
+- `paper=True` is the safe default and should stay on until you are ready for live deployment
+- The broker tracks positions and pending orders from Alpaca account state plus trade-update callbacks
 
 ## Recommended Wrapper
 
@@ -98,8 +98,7 @@ await broker.disconnect()
 
 ## Error Handling
 
-Broker connection and order failures surface as standard Python exceptions, typically
-`RuntimeError`, broker SDK exceptions, or `RiskLimitError` when wrapped by `SafeBroker`.
+Broker connection and order failures surface as standard Python exceptions, broker-SDK exceptions, or `RiskLimitError` when wrapped by `SafeBroker`.
 
 ```python
 from ml4t.live import RiskLimitError