# ATM — Automated Trading Monitor

Personal Faza-1 tool for the M2D strategy. Python 3.11+.

## Quick Reference

```bash
pip install -e ".[windows]"    # Windows: live capture
pip install -e ".[dev]"        # Linux/macOS: dev + tests (WSL: create venv first)
cp .env.example .env           # secretele Discord/Telegram (vezi README §Secrets)
atm calibrate                  # Tk wizard
atm debug --delay 5            # one-shot capture + detect
atm validate-calibration calibration/calibration_labels.json   # offline color gate
atm run --start-at 16:30 --stop-at 23:00                   # live session
atm run --tz America/New_York --oh-start 09:30 --oh-stop 16:00  # NYSE window override
atm dryrun samples             # corpus gate
pytest -q                      # 210+ tests (core + 8 scenarii regresie + env loader)
pytest tests/test_scenarios_regression.py -v    # FSM pe imagini reale
```

## Calibration corpus

`calibration/` — persistent, auto-suficient, safe to keep când `samples/` și `logs/fires/` se golesc. Conține:
- `frames/` — PNG-uri `{ts}_{color}.png` (ground truth în nume)
- `calibration_labels.json` — gate offline pentru `atm validate-calibration`
- `scenarios.json` — secvențe FSM pentru `tests/test_scenarios_regression.py`

Când adaugi un frame: copiezi din `logs/fires/` → redenumești `{ts}_{color}.png` → adaugi entry în JSON. Validare după orice recalibrare.

## Telegram commands (live)

`/ss` `/status` `/pause` `/resume` `/resume force` `/3` (interval min) `/stop`

- `/resume` clears only user pause; Canary drift requires `/resume force`.
- Drift-pause now emits a single Telegram alert (was silent pre-refactor — root cause of the 2026-04-17 hang).

## Operating-hours config

`[options.operating_hours]` in TOML: `enabled`, `timezone` (NYSE local, e.g. `America/New_York`), `weekdays`, `start_hhmm`, `stop_hhmm`. Timezone validated at load; `_tz_cache` reused per tick. Boundary crossings log `market_open` / `market_closed` and notify once. Startup in-window is silent.

## Phase-skip backstop

`[options.alerts] fire_on_phase_skip = true` (default) — ARMED→light_*  direct (dark_* missed) still emits a `⚠️ PHASE SKIP` alert using FSM lockout to suppress spam.

## Palette gotcha (2026-04-21 recalibration)

TradeStation M2D indicators paint the four bright colors at near-pure saturation:
turquoise `(0,253,253)`, yellow `(253,253,0)`, light_green `(0,255,0)`, light_red `(255,0,0)`.
If Tk-wizard calibration samples a slightly desaturated pixel, classifier returns `UNKNOWN`
(distance > tolerance=60) → FSM never sees trigger → stuck in PRIMED → scheduler polls
forever. Always run `atm validate-calibration calibration/calibration_labels.json` after
recalibrating. Current active config: `configs/2026-04-21-recalib.toml`.

## Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:
- Product ideas, "is this worth building", brainstorming → invoke office-hours
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
- Ship, deploy, push, create PR → invoke ship
- QA, test the site, find bugs → invoke qa
- Code review, check my diff → invoke review
- Update docs after shipping → invoke document-release
- Weekly retro → invoke retro
- Design system, brand → invoke design-consultation
- Visual audit, design polish → invoke design-review
- Architecture review → invoke plan-eng-review
- Save progress, checkpoint, resume → invoke checkpoint
- Code quality, health check → invoke health