docs: options phase-6 (spreads) plan

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016DvdRZkyCy9NJpHYDdPqmS

docs/options-phase.md

@@ -0,0 +1,42 @@
+# Phase 6 (planned) — Options trading
+
+Prereq met: all 3 paper accounts are **options Level 3** (long calls/puts + spreads).
+Build in two increments; ship 6a first.
+
+## 6a — Single-leg long calls/puts
+The smallest coherent options feature: an agent expresses a directional thesis by buying a
+**call** (bullish) or **put** (bearish) instead of / alongside shares.
+
+**Schema** (`agents/schemas.py`)
+- Add `instrument: "equity" | "option"` to `Pick` (default equity — nothing else changes).
+- Option fields: `option_right: "call"|"put"`, `expiry: date`, `strike: float`, and a derived
+  OCC `contract_symbol` (e.g. `AAPL260717C00300000`). Validator: expiry in the future, strike > 0.
+
+**Data tools** (`tools/options.py`, added to `build_toolset`)
+- `get_option_chain(underlying, around="atm", dte=30..45)` → nearby strikes/expiries with
+  bid/ask/last/IV/OI. Backend: alpaca-py `OptionHistoricalDataClient` / option chain endpoint.
+- `get_option_quote(contract_symbol)` → latest premium.
+- Prompt guidance: default ~30–45 DTE, near-the-money, adequate open interest/volume.
+
+**Execution** (`execution/broker.py`, `guardrails.py`, `run_market_open.py`)
+- `submit_option_order(contract_symbol, qty_contracts, side, limit_price)` — Alpaca
+  `LimitOrderRequest` with the OCC symbol. ⚠️ **Verify** Alpaca supports bracket/OTO on options;
+  if not, place entry + a separate take-profit limit (and optional stop) rather than a bracket.
+- Guardrails: size by **premium × 100 × contracts** vs equity cap; `max_contracts`,
+  `max_premium_pct`, min DTE / max DTE, liquidity floor. Whole contracts only.
+
+**State/dashboard**
+- `orders`/`positions` gain `instrument_type` + contract columns; dashboard shows options
+  positions distinctly (premium, expiry, right/strike, Greeks if available).
+
+**Verification**: place one live long call + one long put during market hours; confirm fills,
+position, and that the chosen exit mechanism works.
+
+## 6b — Spreads / multi-leg (later)
+Vertical spreads (defined risk), greeks-aware strike selection, multi-leg order submission.
+Much larger surface (leg pairing, spread margin, assignment/expiry handling) — do after 6a is solid.
+
+## Open risks to resolve during build
+- Alpaca options **bracket/OTO** support (drives the exit design above).
+- Options market-data availability/latency on the paper plan.
+- Expiry & assignment handling for positions held to/near expiration.