# 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 source:
- Primary: `web/src/web_core/help.html`
- Fallback: this `web/src/ONBOARDING.md`

## 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. Set `Symbol` (examples: `AAPL`, `MSFT`, `BTC-USD`, `ETH-USD`).
2. Set `Timeframe` (start with `1d` to avoid noisy intraday data).
3. Set `Period` (try `6mo` initially).
4. Keep `Ignore potentially live last bar` ON.
5. Keep filters OFF for baseline:
   - `Use previous body range (ignore wicks)` OFF
   - `Enable volume filter` OFF
   - `Hide market-closed gaps (stocks)` ON
6. Review top metrics:
   - Current Trend
   - Real Bullish Bars
   - Real Bearish Bars
   - Fake Bars
7. Read `Trend Events` for starts and reversals.
8. Use `Live Decision Guide` to translate trend state into a practical bias/action/invalidation workflow.
9. Keep `Show past behavior examples` ON while learning to review historical entry/exit outcomes.

## 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)
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 weekend spacing
- intraday (`1m`..`1h`): removes weekends and overnight closed hours

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
```

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

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

### I still see some time gaps
- For stocks, keep `Hide market-closed gaps (stocks)` ON.
- Daily charts remove weekends; intraday removes weekends + closed hours.
- Some exchange holidays/half-days can still produce spacing depending on the data feed.

### 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
```
