Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

README.md

@@ -14,6 +14,7 @@ A Python web app wrapped by a native macOS shell.
 - `web/src/web_core/`: strategy/data/chart/export modules
 - `web/src/requirements.txt`: Python dependencies
 - `web/src/ONBOARDING.md`: in-app onboarding guide content
+- `web/src/PRD.md`: web product rules and behavior spec
 
 ## macOS Shell
 - Project location: `mac/src/` (`*.xcodeproj` auto-discovered by scripts)

web/src/PRD.md

@@ -0,0 +1,125 @@
+# Web PRD (Source of Truth)
+
+## 1. Scope
+This document defines the product behavior for the Streamlit web app in `web/src/`.
+
+This PRD is intentionally web-only:
+- Data fetch and analysis logic
+- Classification/trend rules
+- Filters, chart behavior, exports, and persisted settings
+
+Out of scope:
+- macOS shell/wrapper architecture and packaging
+
+## 2. Product Goal
+Provide an analysis-only charting tool that classifies OHLC bars as real/fake, tracks trend state using only real bars, and exposes clear visual + exportable outputs.
+
+## 3. Inputs and Data Pipeline
+1. User configures:
+- `symbol`
+- `interval`
+- `period`
+- `max_bars`
+- filter/toggle settings
+2. App fetches OHLCV via Yahoo Finance (`yfinance`).
+3. Optional last-bar drop (live-bar guard) for intraday intervals.
+4. Bars are classified (`real_bull`, `real_bear`, `fake`, `unclassified` for first bar).
+5. Trend state is derived from classification sequence.
+6. UI renders metrics, chart, events, and export artifacts.
+
+## 4. Settings Contract
+Persisted settings path:
+- Primary: `~/.web_local_shell/settings.json`
+- Legacy fallback read: `~/.manesh_trader/settings.json`
+
+Normalization constraints:
+- `symbol`: uppercase, non-empty fallback `AAPL`
+- `interval`: must be one of `INTERVAL_OPTIONS`, fallback `1d`
+- `period`: must be one of `PERIOD_OPTIONS`, fallback `6mo`
+- `max_bars`: `[20, 5000]`, fallback `500`
+- `volume_sma_window`: `[2, 100]`, fallback `20`
+- `volume_multiplier`: `[0.1, 3.0]`, rounded to 0.1, fallback `1.0`
+- `refresh_sec`: `[10, 600]`, fallback `60`
+- booleans normalized from common truthy/falsy strings and numbers
+
+## 5. Classification Rules
+For each bar `i` (starting at index 1):
+- Reference prior bar `i-1`.
+- If `use_body_range = false`:
+  - `prev_high = prev.High`
+  - `prev_low = prev.Low`
+- If `use_body_range = true`:
+  - `prev_high = max(prev.Open, prev.Close)`
+  - `prev_low = min(prev.Open, prev.Close)`
+
+Volume filter:
+- If enabled, `volume_ok = Volume >= SMA(Volume, volume_sma_window) * volume_multiplier`
+- If `volume_ok` is false, classification is `fake` regardless of price break.
+
+Price logic (when volume is OK):
+- `Close > prev_high` -> `real_bull`
+- `Close < prev_low` -> `real_bear`
+- otherwise -> `fake`
+
+First bar is always `unclassified`.
+
+## 6. Trend-State Rules
+Trend states:
+- `No Active Trend`
+- `Bullish Trend Active`
+- `Bearish Trend Active`
+
+State machine:
+- From neutral:
+  - 2 consecutive `real_bull` -> bullish trend started
+  - 2 consecutive `real_bear` -> bearish trend started
+- From bullish:
+  - 2 consecutive `real_bear` -> bearish reversal confirmed
+- From bearish:
+  - 2 consecutive `real_bull` -> bullish reversal confirmed
+
+Important:
+- `fake` bars do not increment opposite-run counters enough to reverse trend.
+
+## 7. Chart and Visualization Behavior
+- Main candlestick chart with bullish/bearish markers:
+  - `real_bull`: green triangle-up
+  - `real_bear`: red triangle-down
+- Optional fake-bar de-emphasis via gray candle layer (`gray_fake`).
+- Volume subplot colored by trend state.
+
+Gap handling (`hide_market_closed_gaps`):
+- Always removes weekend gaps (`sat` -> `mon`).
+- For intraday intervals, also removes inferred overnight hours using session bounds.
+- For daily interval, weekend break removal is applied.
+
+## 8. Help and Onboarding Behavior
+- Web-only fallback help entry exists in sidebar:
+  - `Help / Quick Start`
+- Content source: `web/src/ONBOARDING.md`
+- Help appears in a dialog.
+
+## 9. Outputs
+- Metrics:
+  - current trend
+  - real bullish count
+  - real bearish count
+  - fake count
+- Trend events table (latest events)
+- Backtest snapshot:
+  - signal at trend-change rows to active bull/bear states
+  - next-bar close determines win/loss
+- Exports:
+  - CSV always available
+  - PDF via Plotly image export (requires Kaleido runtime)
+
+## 10. Validation Expectations
+Code-level checks:
+- `python -m py_compile web/src/app.py`
+- `PYTHONPATH=web/src pytest -q web/src/tests`
+
+Behavior checks:
+- No crash on missing/invalid persisted settings
+- Symbol/interval/period invalid combinations show actionable data error
+- Trend logic matches two-consecutive-real-bars contract
+- Exports include normalized timestamp column