Documentation update

README.md

@@ -1,10 +1,10 @@
 # Trading Bot
 
-Python trading bot project using machine learning to decide which assets should be held. The bot is intended to trade through the IBKR API, beginning with paper trading and potentially supporting real trades later behind explicit safeguards.
+Python trading bot project using machine learning to decide which assets should be held. The bot currently uses the Alpaca Markets API for market data and paper trading, with any future live trading kept behind explicit safeguards.
 
 ## Project Status
 
-This repository is at the planning and scaffolding stage. The machine learning model, trading parameters, asset universe, and risk rules will be designed later.
+This repository now has a working prototype flow for Alpaca market data, dataset generation, XGBoost training, prediction, and paper-trading rebalancing. The strategy is still intentionally narrow: it currently focuses on `SPY` exposure using a small market-regime feature set.
 
 ## Main Parts
 
@@ -29,22 +29,53 @@ The current local Python version is pinned in `.mise.toml`.
 
 Runtime dependencies are declared in `pyproject.toml`.
 
-- `ib-insync` for the IBKR API connection.
+- `alpaca-py` for Alpaca market data and trading clients.
 - `pandas` for tabular candle data handling.
 - `pyarrow` for Parquet file support.
+- `xgboost` and `scikit-learn` for model training and evaluation.
+- `python-dotenv` for loading local Alpaca credentials from `.env`.
 
 ## Trading Safety
 
-The default target is paper trading. Real trading should only be added later with explicit configuration, clear documentation, and tests around order generation and broker integration.
+The default target is Alpaca paper trading. Real trading should only be added later with explicit configuration, clear documentation, and tests around order generation and broker integration.
 
-Do not commit secrets such as IBKR credentials, account identifiers, API tokens, or private configuration.
+Do not commit secrets such as Alpaca API keys, account identifiers, API tokens, or private configuration.
+
+## Current Commands
+
+Fetch Alpaca daily candles:
+
+```sh
+mise exec -- uv run python src/trading_bot/data/fetch_alpaca_daily.py SPY
+```
+
+Build the training dataset and train the current model:
+
+```sh
+mise exec -- uv run python src/trading_bot/data/train_pipeline.py
+```
+
+Run the current Alpaca paper-trading rebalance flow:
+
+```sh
+mise exec -- uv run python src/trading_bot/models/trade.py \
+  --paper \
+  --fetch-recent-data \
+  --model-path models/spy_xgb_v1.json \
+  --metadata-path models/spy_xgb_v1_meta.json
+```
+
+The main Python entry points are:
+
+- `src/trading_bot/data/train_pipeline.py` for dataset generation and model training.
+- `src/trading_bot/models/trade.py` for Alpaca account inspection and SPY rebalancing.
 
 ## Documentation
 
 See [docs/README.md](docs/README.md) for the initial architecture notes and decision log.
 
-The first data collection design note is [docs/data-fetcher.md](docs/data-fetcher.md), and the first training dataset contract is [docs/training-dataset.md](docs/training-dataset.md).
+The current data collection note is [docs/data-fetcher.md](docs/data-fetcher.md), and the training dataset contract is [docs/training-dataset.md](docs/training-dataset.md).
 
 The first dataset generation notebook is [notebooks/spy_direction_dataset.ipynb](notebooks/spy_direction_dataset.ipynb).
 
-Manual test instructions for the IBKR fetcher skeleton are in [docs/manual-test/README.md](docs/manual-test/README.md).
+Manual test instructions for the Alpaca fetcher are in [docs/manual-test/README.md](docs/manual-test/README.md).