Documentation update

docs/README.md

@@ -2,7 +2,7 @@
 
 ## Objective
 
-Build a Python-based trading bot that uses machine learning to determine which assets should be held, then uses the IBKR API to facilitate trades. The first supported trading mode should be paper trading.
+Build a Python-based trading bot that uses machine learning to determine which assets should be held, then uses Alpaca Markets for market data and broker execution. The first supported trading mode is paper trading.
 
 ## Planned Modules
 
@@ -10,9 +10,9 @@ Build a Python-based trading bot that uses machine learning to determine which a
 
 Responsible for acquiring and storing market, asset, and any future feature data needed for model training and evaluation.
 
-The first planned tool is an IBKR daily candle fetcher. It should fetch open, high, low, close, and volume data for a ticker and date range, then eventually persist that data to a ticker-named Parquet file. See [data-fetcher.md](data-fetcher.md).
+The current data tool is an Alpaca daily candle fetcher. It fetches open, high, low, close, and volume data for a ticker and date range, then persists that data to a ticker-named Parquet file. See [data-fetcher.md](data-fetcher.md).
 
-The initial supervised training dataset is documented in [training-dataset.md](training-dataset.md). It derives market-regime features from `SPY`, `VIX`, `TLT`, and `USO`, then labels whether `SPY` closes higher five trading days later.
+The initial supervised training dataset is documented in [training-dataset.md](training-dataset.md). It derives market-regime features from `SPY`, a volatility proxy, `TLT`, and `USO`, then labels whether `SPY` closes higher five trading days later. The checked-in configuration currently maps the volatility input to `VIXY` for Alpaca data availability.
 
 Parquet files are partitioned by ticker, not by date.
 
@@ -29,6 +29,8 @@ Open decisions:
 
 Responsible for building datasets, training models, evaluating candidates, and writing versioned model artifacts.
 
+The main entry point is `src/trading_bot/data/train_pipeline.py`. It reads raw Alpaca Parquet files from `data/alpaca/daily`, builds `data/training/spy_direction_5d.parquet`, trains an XGBoost classifier, and writes model artifacts to `models/`.
+
 Open decisions:
 
 - prediction target;
@@ -41,11 +43,13 @@ Open decisions:
 
 ### Trading Bot
 
-Responsible for loading a model, generating portfolio signals, deciding target holdings, and using the IBKR API to place or simulate orders.
+Responsible for loading a model, generating portfolio signals, deciding target holdings, and using the Alpaca trading API to place paper-trading orders.
+
+The main entry point is `src/trading_bot/models/trade.py`. It loads a model and metadata, optionally refreshes recent Alpaca market data, estimates a target `SPY` exposure from the model probability, cancels open Alpaca orders, and submits a day market order when the desired rebalance exceeds the configured minimum notional amount. Pass `--model-path models/spy_xgb_v1.json --metadata-path models/spy_xgb_v1_meta.json` to trade with artifacts produced by the current training pipeline.
 
 Initial expectations:
 
-- paper trading first;
+- Alpaca paper trading first;
 - real trading later only behind explicit configuration;
 - clear logging of model version, signals, target holdings, generated orders, and broker responses;
 - separation between signal generation, portfolio construction, and broker execution.
@@ -56,7 +60,7 @@ Open decisions:
 - position sizing;
 - risk limits;
 - cash handling;
-- order types;
+- order types and time-in-force choices;
 - failed order handling;
 - market hours behavior;
 - manual override behavior.
@@ -79,9 +83,9 @@ Possible scope:
 1. Decide the initial project package structure.
 2. Keep Python packaging and dependency management current with `uv`.
 3. Add a minimal configuration system.
-4. Define interfaces for data collection, model artifacts, and broker execution.
-5. Add tests for the core trading decision boundaries before connecting real broker behavior.
+4. Harden interfaces for data collection, model artifacts, and Alpaca broker execution.
+5. Expand tests around trading decision boundaries, portfolio sizing, stale data handling, and broker API boundaries.
 
 ## Decisions Deferred
 
-The model, features, labels, asset selection rules, risk management rules, and trading cadence are intentionally deferred for later discussion.
+Broader model design, asset selection rules, risk management rules, live-trading gates, and trading cadence are intentionally deferred for later discussion.