# Paper-Trading Run Supervision Pattern

Use this pattern when turning a trading bot from hardened code into an observed paper-trading experiment.

## Safe launch pattern

- Keep live order side effects disabled by construction: paper trading should route execution through a local paper exchange/state file, not the live exchange.
- Distinguish clearly:
  - `dry_run=true`: no execution, not even simulated orders.
  - `paper_trading=true` plus `dry_run=false`: execute simulated orders into paper state.
- Start long-running bot processes under the process manager/background terminal rather than shell `nohup`/`&`, so logs and lifecycle remain inspectable.
- Verify startup from runtime logs before declaring success: mode flags, paper state path, live market-data scan count, and no fatal errors.
- Keep a kill-switch file available and documented; paper runs should exercise it before live deployment.

## Runtime files to collect

Keep all under a runtime/state directory outside Git, for example `~/.local/state/<BotName>/`:

- trading log
- trade journal JSONL
- paper exchange state JSON
- market context JSONL
- collector logs
- kill-switch file

## Monitoring pattern

Create two jobs:

1. **Collector job** — script-only, silent/local delivery, frequent interval such as every 30m. It collects chart/exchange context into JSONL and stays quiet on success.
2. **Analyst monitor job** — LLM-backed, delivered to the trading topic, slower interval such as every 2h. It checks process health, trade journal, paper state, market context, correlation output, and errors.

Monitor prompts should explicitly say:

- never restart the bot automatically;
- never place live trades;
- never change config/code without explicit user approval;
- with fewer than roughly 5 closed paper trades, report observations only and avoid strategy-tuning recommendations.

## Signal-learning loop

Recommended data flow:

```text
Live market data
→ paper entries/exits
→ trade journal
→ market context snapshots
→ signal correlation report
→ human-reviewed strategy hypothesis
→ tested config/code change
```

For each entry, correlate the most recent preceding context snapshot for the same asset. Aggregate tags/sources by sample size, win rate, average PnL, total PnL, time-in-trade, exit reason, and drawdown where available.

## Dashboard boundary

After journal/context/correlation are stable, add a read-only dashboard before adding more noisy signal sources. The dashboard should display:

- bot process status and uptime;
- paper orders and open paper positions;
- journal entries/exits;
- market context per coin;
- signal-correlation report;
- kill-switch status;
- recent errors.

Keep dashboard reads side-effect-free. It should not place orders, edit config, or clear runtime state.