maneshtrader/ONBOARDING.md

# ManeshTrader Onboarding

## 1) What This Tool Does
ManeshTrader analyzes OHLC candles and labels each closed bar as:
- `real_bull`: close is above previous high (or previous body high if wick filter is enabled)
- `real_bear`: close is below previous low (or previous body low if wick filter is enabled)
- `fake`: close is inside previous range (noise)

Trend logic:
- 2 consecutive real bullish bars => bullish trend active
- 2 consecutive real bearish bars => bearish trend active
- Reversal requires 2 consecutive opposite real bars
- Fake bars do not reverse trend

In-app help popup:
- Open from sidebar `Help / Quick Start`
- Uses a multi-screen, child-friendly guide implemented in `web/src/web_core/ui/help_content.py`
- Includes dedicated screens for core setup, filters, training mode, backtest controls, and advanced panels

Beginner interpretation panel:
- Main page always shows `What This Tool Means (Beginner Training)`
- Includes plain-English definitions of top metrics and a historical snapshot table for `1M`, `3M`, `6M`, `1Y`
- Each row includes a simple interpretation so non-traders can quickly understand whether a window was directional or noisy

## 2) Quick Start (Recommended)
From project root:

```bash
./run.sh
```

This script:
- creates `.venv` if needed
- installs dependencies from `requirements.txt`
- launches Streamlit

Then open the shown URL (usually `http://localhost:8501`).

## 3) macOS Double-Click Start
In Finder, double-click:
- `Run ManeshTrader.command`

If macOS blocks first run, execute once:

```bash
xattr -d com.apple.quarantine "Run ManeshTrader.command"
```

### Optional: Build a Real macOS `.app`
From project root:
```bash
./scripts/create_mac_app.sh
```

This generates `ManeshTrader.app`, which you can double-click like a normal app or move to `/Applications`.

Build a distributable installer DMG:
```bash
./scripts/create_installer_dmg.sh
```
Output: `ManeshTrader-YYYYMMDD-HHMMSS.dmg` in project root.

### Share With Non-Technical Users (Self-Contained)
Build a standalone app that includes Python/runtime:
```bash
./scripts/build_standalone_app.sh
```

Then build DMG from that standalone app path:
```bash
APP_BUNDLE_PATH="dist-standalone/<timestamp>/dist/ManeshTrader.app" ./scripts/create_installer_dmg.sh
```

Tip: sign and notarize before sharing broadly, so macOS trust prompts are reduced.

## 4) First Session Walkthrough
1. At app start, complete `Profile Login`:
   - `Login profile name`: type an existing profile, then click `Login`
   - `PIN (if enabled)`: enter PIN for protected profiles
   - `Remember me on this browser`: keeps non-PIN profiles signed in across visits
   - `Create profile name`: type a new unique profile, then click `Create Profile`
   - `Set PIN (optional, 4-6 digits)`: add lightweight profile protection
2. After login, use sidebar `Switch profile` to change users.
3. Note: profile names are case-insensitive for uniqueness (`Matt` and `matt` count as the same profile).
4. Sidebar `Profile` section shows audit stamps for created time, last login, last settings update, and last symbol.
5. Set `Symbol` (examples: `AAPL`, `MSFT`, `BTC-USD`, `ETH-USD`).
6. Optional: choose `Market Preset` (`Stocks Swing` or `Crypto Intraday`) for one-click defaults.
7. Optional: add symbols to `Watchlist` and use quick-select buttons.
8. Set `Timeframe` (start with `1d` to avoid noisy intraday data).
9. Set `Period` (try `6mo` initially).
10. Keep `Ignore potentially live last bar` ON.
11. Keep filters OFF for baseline:
   - `Use previous body range (ignore wicks)` OFF
   - `Enable volume filter` OFF
   - `Hide market-closed gaps (stocks)` ON
12. Review top metrics:
   - Current Trend
   - Real Bullish Bars
   - Real Bearish Bars
   - Fake Bars
13. Read `What This Tool Means (Beginner Training)`:
   - Open `Plain-English metric guide` for quick definitions.
   - Review `1M / 3M / 6M / 1Y` snapshot rows to see how this symbol behaved recently.
   - Use `What this says` to understand if conditions were trend-friendly or choppy.
14. Read `Trend Events` for starts and reversals.
15. Use `Live Decision Guide` to translate trend state into a practical bias/action/invalidation workflow.
16. Keep `Show past behavior examples` ON while learning to review historical entry/exit outcomes.
17. Set `Display Timezone (US)` to your preferred timezone (default is `America/Chicago`, CST/CDT).
18. Choose `Use 24-hour time` ON for `13:00` style, or OFF for `1:00 PM` style.

## 4.1) Advanced Features (Optional)
- `Advanced Signals`:
  - `Auto-run advanced panels (slower)`: keeps multi-timeframe/compare updating every rerun
  - `Run advanced panels now`: one-shot run to avoid UI hangs during normal editing
  - `Show multi-timeframe confirmation (1h/4h/1d)`
  - `Regime filter (stand aside in choppy periods)`
- `Training & Guidance`:
  - `Replay mode (hide future bars)` + `Replay bars shown`
- `Monitoring`:
  - `Display Timezone (US)`: controls audit/event/training timestamp timezone (`America/Chicago` default)
  - `Use 24-hour time`: switches between `13:00` and `1:00 PM` time styles
- `Compare Symbols`:
  - enable panel and provide comma-separated symbols (`AAPL, MSFT, NVDA`)
- `Alerts`:
  - enable bullish/bearish rule alerts
  - optional webhook URL for external delivery (Telegram/email automation via Zapier/Make/webhook adapters)
- `Backtest Controls`:
  - slippage/fee bps
  - stop-loss/take-profit %
  - min/max hold bars

## 5) How To Read The Chart
- Candle layer: full price action
- Green triangle-up markers: `real_bull`
- Red triangle-down markers: `real_bear`
- Gray candles (if enabled): visually de-emphasized fake bars
- Volume bars are colored by trend state
- Optional training overlays:
  - blue circle: example long entry
  - orange diamond: example short entry
  - green X: example winning exit
  - red X: example loss/flat exit

## 6) Training Mode (New)
Training toggles are OFF by default.

Use these toggles in sidebar `Training & Guidance`:
- `Show live decision guide`: summarizes current bias, signal status, and invalidation rule.
- `Show past behavior examples`: shows historical hypothetical trades and outcomes.
- `Overlay example entries/exits on chart`: draws example entry/exit markers on candles.
- `Focus chart on selected example`: zooms chart around the clicked training row.
- `Max training examples`: controls how many recent closed examples to include.

Example-trade method:
- Enter on a confirmed trend-change bar close.
- Exit on the opposite confirmed trend-change bar close.
- Direction is `LONG` in bullish trend and `SHORT` in bearish trend.

## 6.1) Tutorial: Use This Like a Training Coach
Goal: learn what the model is signaling and what would have happened if you followed it.

### Step A: Set up a clean training view
1. In sidebar, choose a liquid symbol (`AAPL` or `BTC-USD`).
2. Start with:
   - `Timeframe = 1d` (less noise)
   - `Period = 6mo`
   - `Ignore potentially live last bar = ON`
3. Turn ON:
   - `Show live decision guide`
   - `Show past behavior examples`
   - `Overlay example entries/exits on chart`
   - `Focus chart on selected example` (optional but recommended while learning)
4. Set `Max training examples = 20`.

### Step B: Read current signal (what to do now)
1. Look at `Live Decision Guide`.
2. Use `Bias` as your directional filter:
   - `Long Bias`: only evaluate long ideas.
   - `Short Bias`: only evaluate short ideas.
   - `Stand Aside / Neutral`: wait for clearer confirmation.
3. Read `Signal Status`:
   - `Fresh Confirmation`: a new active trend was confirmed on the latest closed bar.
   - `No New Confirmation`: no fresh reversal confirmation on the latest closed bar.
4. Use `Invalidation rule` as the condition that would cancel your current bias.

### Step C: Study historical behavior (what would have happened)
1. Open `Past Behavior Examples (Training)`.
2. Review summary metrics:
   - `Closed Examples`
   - `Wins / Losses`
   - `Example Win Rate`
   - `Avg P/L per Example`
3. Read the latest row first, then scan older examples.
4. On chart, compare markers to price structure:
   - blue circle: long entry
   - orange diamond: short entry
   - green X: winning exit
   - red X: loss/flat exit
5. Click any row in the examples table:
   - app highlights that exact trade path on chart
   - app shows a plain-English explanation of that row

### Step D: Practice loop (recommended)
1. Pick one symbol/timeframe.
2. Hide the table briefly and decide what you would do from `Live Decision Guide`.
3. Re-open table and compare your decision to recent example outcomes.
4. Repeat across different regimes:
   - trending periods
   - choppy/sideways periods
5. Keep notes on where the model performs best/worst.

### Step E: Move from training to live monitoring
1. Keep `Show live decision guide` ON.
2. Keep `Ignore potentially live last bar` ON to reduce unfinished-bar noise.
3. Enable `Auto-refresh` only when actively monitoring.
4. Treat this as a decision-support layer, not an execution signal by itself.

## 7) Recommended Settings By Asset
### Stocks (swing)
- Timeframe: `1d`
- Period: `6mo` or `1y`
- Max bars: `300-800`

### Crypto (shorter horizon)
- Timeframe: `1h` or `4h`
- Period: `1mo-6mo`
- Enable auto-refresh only when monitoring live

## 8) Optional Filters
### Ignore Wicks
Use when long wicks create false breakouts; compares close to previous body only.

### Volume Filter
Treats low-volume bars as fake:
- Enable `Enable volume filter`
- Start with:
  - `Volume SMA window = 20`
  - `Min volume / SMA multiplier = 1.0`

### Hide Market-Closed Gaps (Stocks)
Compresses non-trading time on stock charts:
- `1d`: removes weekends and full missing days (for example exchange holidays with no bars)
- intraday (`1m`..`1h`): removes weekends, full missing days, and overnight closed hours; x-axis labels show one date per trading day

Use OFF for 24/7 markets (for example many crypto workflows) when you want continuous time.

## 9) Exports
- CSV: `Download classified data (CSV)`
- PDF chart: `Download chart (PDF)`

If PDF fails, ensure `kaleido` is installed (already in `requirements.txt`).

## 10) Troubleshooting
### App won’t start
```bash
./run.sh --setup-only
./run.sh
```

### I see a blank/skeleton placeholder on refresh
- A brief placeholder can appear while Streamlit initializes the page.
- Wait a moment; this is expected loading behavior, not an app crash.

### Port already in use
```bash
streamlit run app.py --server.port 8501
```

### Bad symbol/data error
- Verify ticker format (`BTC-USD`, not `BTCUSD`)
- Use compatible `Timeframe` + `Period`

### My settings changed unexpectedly
- Confirm you are logged into your own profile.
- Use sidebar `Switch profile` if needed.
- Share profile-specific links by including `?profile=<your-name>` in the app URL.
- If you were inactive for more than 30 minutes, the app will require login again.

### Watchlist or preset not applying as expected
- Watchlist uses comma-separated symbols and deduplicates automatically.
- Select a non-`Custom` preset and click `Apply Preset` to populate defaults.
- After applying, you can still manually tweak any field.

### Replay mode looks different than normal view
- Replay mode intentionally truncates visible bars to simulate no-hindsight training.
- Disable replay mode to return to full-history analysis.

### Alert webhook errors
- Confirm webhook URL accepts JSON `POST`.
- For Telegram/email, route through an automation endpoint that supports incoming webhooks.

### PIN login fails
- Ensure the profile name is correct (name matching is case-insensitive).
- PIN must be exactly what was set during profile creation (4-6 digits).

### Why did auto-login not happen?
- `Remember me` only auto-restores profiles without PIN.
- PIN-protected profiles still require PIN on a fresh/expired session.

### I still see some time gaps
- For stocks, keep `Hide market-closed gaps (stocks)` ON.
- Daily charts remove weekends + full no-data days; intraday removes weekends + full no-data days + closed hours.
- Day-based periods (`1d`, `5d`) backfill to target trading-day count when provider limits allow.
- Half-days can still look visually compressed because they are partial sessions, not missing sessions.

### Exports crash with timestamp errors
- Pull latest project changes (export logic now handles named index columns)

## 11) Safety Notes
- This app is analysis-only, no trade execution.
- Backtest snapshot is diagnostic and simplistic.
- Not financial advice.

## 12) Useful Commands
Setup only:
```bash
./run.sh --setup-only
```

Run tests:
```bash
make test
```

Run app:
```bash
make run
```