# 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

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

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

## 6) 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

## 7) 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.

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

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

## 9) 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)

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

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

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

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