atm/CLAUDE.md

ATM — Automated Trading Monitor

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

Quick Reference

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
pytest -q                      # 230+ tests (core + 8 scenarii regresie + env loader)
pytest tests/test_scenarios_regression.py -v    # FSM pe imagini reale

Calibration corpus

calibration/ — persistent, auto-suficient. Conține:

• frames/ — PNG-uri raw {ts}_{color}.png scrise automat de live loop la fiecare schimbare de culoare (filename = culoarea detectată, poate fi greșită)
• calibration_labels.json — ground truth manual (gate offline pentru atm validate-calibration)
• scenarios.json — secvențe FSM pentru tests/test_scenarios_regression.py

Workflow după sesiune: review frame-urile noi din frames/, adaugi entry-uri în calibration_labels.json cu culoarea pe care ai văzut-o TU pe chart (nu neapărat cea din filename), rulezi atm validate-calibration.

Telegram commands (live)

/ss /status /pause /resume /rebase /3 (interval min) /stop

• /rebase — propune un baseline_phash nou pentru canary: capturează frame, crop pe canary.roi, phash → trimite screenshot adnotat (cerc roșu pe ROI) cu old/new hash + distance. /rebase confirm în ≤180s aplică: rescrie baseline_phash în TOML-ul activ (păstrează comentariile), mirror în cfg la runtime, clear user_paused + drift_paused. Fără confirm, nimic nu se modifică. Folosește-l când layout-ul TS s-a schimbat intenționat și vrei să re-ancorezi canary-ul fără atm calibrate full.

• /ss — verify multi-bulină: adnotează top-3 buline din dot_roi (cerc roșu gros pe pick-ul FSM, cercuri colorate subțiri pe vecini) + caption cu clasificarea fiecăreia (nume, RGB, distanță, confidence) + config: {version}. Cercul colorat folosește cfg.colors[name].rgb la runtime — DRY cu paleta activă.

• /resume clears BOTH user pause and canary drift-pause in one shot (/resume force still accepted as legacy alias). Trimite un singur Alert cu screenshot adnotat inline (capture rulează înainte de clearing state → zero race cu FSM tick-uri). Dacă capture eșuează, title conține ⚠️ captură eșuată și resume-ul se execută oricum.

• Drift-pause emits a single Telegram alert on transition. While paused, /set_interval is refused and /ss captions warn that detection is off.

• Heartbeat shows ⚠️ pauzat (drift) instead of activ while canary is paused.

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