docs: refresh README and document how it works

- Add "How It Works": daily load (ordered pipeline steps), intraday flow,
  other jobs, and the score -> activation gate -> top pick chain.
- Add "Key Use Cases" (find today's best long setup; track a paper trade).
- Fix stale facts: user-curated (not auto) watchlist, actual routes/pages,
  scheduler description, wrong env defaults (RR 3.0->1.5, fundamentals
  daily->weekly).
- Add missing surface: paper trading, activation gate, market regime, Telegram
  alerts, backtest; API groups (paper-trades, market/regime, jobs); FRED +
  Telegram env vars; note that pipeline timing is admin-cron, not env.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -4,20 +4,57 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni
 
 **Philosophy:** Don't predict price. Find the path of least resistance, key S/R zones, and asymmetric R:R setups.
 
+## How It Works
+
+Scheduled pipelines turn raw prices into a ranked, gated list of tradeable setups. Everything downstream of OHLCV is recomputed from stored data, so each refresh is cheap and idempotent. Job timing is cron-based and configurable in **Admin → Jobs** (default timezone Europe/Berlin).
+
+### Daily Load — the full refresh
+
+Once a day (default 07:00). Steps run **in dependency order**, each consuming the previous step's fresh output:
+
+1. **OHLCV** — fetch the latest daily bars for every tracked ticker (Alpaca); new tickers backfill ~5 years.
+2. **Sentiment** — fetch sentiment for the names that matter and are stale (> 5 days): top-pick feeders (momentum leaders with a tradeable long setup), the watchlist, and open paper trades, plus a top-N-by-composite discovery net. Runs *before* the scan so the scan sees fresh sentiment.
+3. **R:R Scan** — recompute S/R zones, the 5-dimension scores and long/short setups (ATR stops, S/R targets) for every ticker, and attach each ticker's 12‑1 momentum percentile.
+4. **Outcome Eval** — resolve setups that hit target/stop or expired (default 30 trading days) and close paper trades that hit a level.
+5. **Market Regime** — recompute the regime index (breadth/trend).
+6. **Regime Monitor** — observational early-warning snapshot (VIX, credit spreads via FRED); feeds nothing else.
+
+A failing step is logged; the pipeline continues with the next.
+
+### Intraday — light refresh
+
+Hourly across the US session (Mon–Fri): only **OHLCV → Outcome Eval**, to keep prices current and close paper trades intraday. No scan/sentiment — the dashboard recomputes live R:R from the latest price, so fresh prices are enough.
+
+### Other jobs
+
+Fundamentals (weekly, early Monday) · Alerts (hourly, Telegram) · Backtest (weekly) · Ticker-universe sync (daily). Deep history backfill and event study are manual-only (Admin → Jobs).
+
+### From score to "top pick"
+
+1. **Composite score** — technical, S/R-quality, sentiment, fundamental and momentum sub-scores (0–100) combine into a weighted composite (weights configurable; missing dimensions re-normalize).
+2. **Setups** — the scanner builds long/short setups with ATR stops and S/R targets, then adds a confidence score, conflict flags and a target reach-probability.
+3. **Activation gate** — a setup *qualifies* only if it clears the R:R and confidence floors **and** ranks in the top momentum percentile of the universe (the validated edge is long-only momentum).
+4. **Top pick** — the highest-momentum qualified setup; highlighted on the Dashboard and labelled on the ticker page.
+
+## Key Use Cases
+
+- **Find today's best long setup.** On the **Dashboard**, the *Top Setups* table lists qualified setups ranked by momentum with the #1 flagged "Top pick". Each row opens the ticker page for the chart, scores, S/R targets and entry/stop.
+- **Track a trade you took.** Mark a setup as a **paper trade**: it's marked-to-market against the latest close, auto-closed on stop/target, and its sentiment stays fresh while open. *Signals → Track Record* shows the realized edge.
+
 ## Stack
 
 | Layer | Tech |
 |---|---|
 | Backend | Python 3.12+, FastAPI, Uvicorn, async SQLAlchemy, Alembic |
 | Database | PostgreSQL (asyncpg) |
-| Scheduler | APScheduler — OHLCV, sentiment, fundamentals, R:R scan |
+| Scheduler | APScheduler — daily & intraday pipelines, fundamentals, alerts, regime, backtest |
 | Frontend | React 18, TypeScript, Vite 5 |
 | Styling | Tailwind CSS 3 with custom glassmorphism design system |
 | State | TanStack React Query v5 (server), Zustand (client/auth) |
 | Charts | Canvas 2D candlestick chart with S/R overlays |
 | Routing | React Router v6 (SPA) |
 | HTTP | Axios with JWT interceptor |
-| Data providers | Alpaca (OHLCV), OpenAI (sentiment, optional micro-batch), Fundamentals chain: FMP → Finnhub → Alpha Vantage |
+| Data providers | Alpaca (OHLCV); OpenAI / Gemini / DeepSeek / xAI (sentiment, pluggable); Fundamentals chain: FMP → Finnhub → Alpha Vantage; FRED (regime); Telegram (alerts) |
 
 ## Features
 
@@ -30,10 +67,15 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni
 - Sentiment analysis with time-decay weighted scoring
 - Fundamental data tracking (P/E, revenue growth, earnings surprise, market cap)
 - 5-dimension scoring engine (technical, S/R quality, sentiment, fundamental, momentum) with configurable weights
-- Risk:Reward scanner — long and short setups, ATR-based stops, configurable R:R threshold (default 1.5:1)
+- Risk:Reward scanner — long and short setups, ATR-based stops, S/R-based targets, configurable R:R threshold (default 1.5:1)
-- Auto-populated watchlist (top-10 by composite score) + manual entries (cap: 20)
+- Activation gate — qualifies setups on a momentum-percentile floor plus R:R/confidence (validated long-only edge); ranks the rest by expected value
+- Recommendation layer — directional confidence, conflict detection, per-target reach-probability
+- Paper trading — take a setup, mark-to-market vs. latest close, auto-close on stop/target, realized track record + outcome evaluation
+- Market-regime index + FRED early-warning monitor (VIX, credit spreads); weekly backtest + manual event study
+- Telegram alerts (e.g. regime-quadrant changes)
+- User-curated watchlist (cap: 20), enriched with composite score, R:R and S/R summary
 - JWT auth with admin role, configurable registration, user access control
-- Scheduled jobs with enable/disable control and status monitoring
+- Cron-scheduled pipelines (admin-configurable) with per-job enable/disable and live status monitoring
 - Admin panel: user management, data cleanup, job control, system settings
 
 ### Frontend
@@ -56,12 +98,15 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni
 |---|---|---|
 | `/login` | Login | Public |
 | `/register` | Register | Public (when enabled) |
-| `/watchlist` | Watchlist (default) | Authenticated |
+| `/` | Dashboard — top setups, open trades, regime (default) | Authenticated |
+| `/market` | Market — watchlist + rankings tabs | Authenticated |
+| `/signals` | Signals — scanner + track record tabs | Authenticated |
+| `/regime` | Market Regime | Authenticated |
 | `/ticker/:symbol` | Ticker Detail | Authenticated |
-| `/scanner` | Trade Scanner | Authenticated |
-| `/rankings` | Rankings | Authenticated |
 | `/admin` | Admin Panel | Admin only |
 
+Legacy routes redirect: `/watchlist` → `/market`, `/rankings` → `/market?tab=rankings`, `/scanner` → `/signals`, `/performance` → `/signals?tab=track`.
+
 ## API Endpoints
 
 All under `/api/v1/`. Interactive docs at `/docs` (Swagger) and `/redoc`.
@@ -78,7 +123,10 @@ All under `/api/v1/`. Interactive docs at `/docs` (Swagger) and `/redoc`.
 | Sentiment | `GET /sentiment/{symbol}` |
 | Fundamentals | `GET /fundamentals/{symbol}` |
 | Scores | `GET /scores/{symbol}`, `GET /rankings`, `PUT /scores/weights` |
-| Trades | `GET /trades` |
+| Trades | `GET /trades`, `GET /trades/{symbol}`, `GET /trades/{symbol}/history`, `GET /trades/activation`, `GET /trades/performance` |
+| Paper Trades | `GET /paper-trades`, `POST /paper-trades`, `POST /paper-trades/{id}/close` |
+| Market / Regime | `GET /market/regime`, `GET /regime/monitor`, `GET/PUT /regime/config`, `GET /regime/history`, `GET /regime/event-study`, `GET/PUT /regime/fundamentals`, `GET /backtest/report` |
+| Jobs | `GET /jobs/running` |
 | Watchlist | `GET /watchlist`, `POST /watchlist/{symbol}`, `DELETE /watchlist/{symbol}` |
 | Admin | `GET /admin/users`, `POST /admin/users`, `PUT /admin/users/{id}/access`, `PUT /admin/users/{id}/password`, `PUT /admin/settings/registration`, `GET /admin/settings`, `PUT /admin/settings/{key}`, `GET/PUT /admin/settings/recommendations`, `GET/PUT /admin/settings/ticker-universe`, `POST /admin/tickers/bootstrap`, `POST /admin/data/cleanup`, `GET /admin/jobs`, `POST /admin/jobs/{name}/trigger`, `PUT /admin/jobs/{name}/toggle`, `GET /admin/pipeline/readiness` |
 
@@ -164,17 +212,22 @@ Configure in `.env` (copy from `.env.example`):
 | `FMP_API_KEY` | Optional (fundamentals) | — | Financial Modeling Prep API key (first provider in chain) |
 | `FINNHUB_API_KEY` | Optional (fundamentals) | — | Finnhub API key (fallback provider) |
 | `ALPHA_VANTAGE_API_KEY` | Optional (fundamentals) | — | Alpha Vantage API key (fallback provider) |
-| `DATA_COLLECTOR_FREQUENCY` | No | `daily` | OHLCV collection schedule |
+| `FRED_API_KEY` | Optional (regime) | — | FRED key for the regime monitor (VIX, credit spreads) |
+| `TELEGRAM_BOT_TOKEN` | Optional (alerts) | — | Telegram bot token for alerts (can also be set in Admin) |
+| `TELEGRAM_CHAT_ID` | Optional (alerts) | — | Telegram chat id for alerts |
+| `DATA_COLLECTOR_FREQUENCY` | No | `daily` | OHLCV collection schedule (legacy — see note below) |
 | `SENTIMENT_POLL_INTERVAL_MINUTES` | No | `30` | Sentiment polling interval |
-| `FUNDAMENTAL_FETCH_FREQUENCY` | No | `daily` | Fundamentals fetch schedule |
+| `FUNDAMENTAL_FETCH_FREQUENCY` | No | `weekly` | Fundamentals fetch cadence |
 | `RR_SCAN_FREQUENCY` | No | `daily` | R:R scanner schedule |
 | `FUNDAMENTAL_RATE_LIMIT_RETRIES` | No | `3` | Retries per ticker on fundamentals rate-limit |
 | `FUNDAMENTAL_RATE_LIMIT_BACKOFF_SECONDS` | No | `15` | Base backoff seconds for fundamentals retry (exponential) |
 | `DEFAULT_WATCHLIST_AUTO_SIZE` | No | `10` | Auto-watchlist size |
-| `DEFAULT_RR_THRESHOLD` | No | `3.0` | Minimum R:R ratio for setups |
+| `DEFAULT_RR_THRESHOLD` | No | `1.5` | Minimum R:R ratio for setups |
 | `DB_POOL_SIZE` | No | `5` | Database connection pool size |
 | `LOG_LEVEL` | No | `INFO` | Logging level |
 
+> **Note:** Pipeline timing (daily / intraday / fundamentals cron, timezone) is configured at runtime in **Admin → Jobs** and stored in the DB — the `*_FREQUENCY` env vars are legacy fallbacks for the few jobs still on interval triggers (alerts, universe sync).
+
 ## Production Deployment (Debian 12)
 
 ### 1. Install dependencies
@@ -292,7 +345,7 @@ frontend/
     │   └── watchlist/   # Watchlist table, add ticker form
     ├── hooks/           # React Query hooks (one per resource)
     ├── lib/             # Types, formatting utilities
-    ├── pages/           # Page components (7 pages)
+    ├── pages/           # Page components (Login, Register, Dashboard, Market, Signals, Regime, Ticker, Admin)
     ├── stores/          # Zustand auth store
     └── styles/          # Global CSS with glassmorphism classes