# Repository Guidelines

## Project Structure & Module Organization
This is a Python 3.11+ package for Binance spot trading automation. Source code lives in `src/binance_quant/`, with CLI entry points in `cli.py`, configuration in `config.py`, exchange access in `exchange.py`, execution/risk logic in `execution.py` and `risk.py`, and workflow modules such as `auto_buy.py`, `auto_sell.py`, and `ai_trader.py`. Tests are in `tests/` and mirror the package by behavior or module name, for example `tests/test_cli.py` and `tests/test_auto_buy_runner.py`. Operational helpers are in `scripts/`; design notes and plans are under `docs/superpowers/`. Runtime artifacts such as `logs/`, `.pytest_cache/`, virtualenvs, and SQLite databases should remain untracked.

## Build, Test, and Development Commands
- `python -m pip install -e ".[dev]"`: install the package and pytest tooling in editable mode.
- `python -m pytest`: run the full quiet test suite configured by `pyproject.toml`.
- `python -m pytest tests/test_cli.py -q`: run a focused test file while iterating.
- `binance-quant version`: verify the Typer CLI entry point is installed.
- `.\scripts\run.ps1 -Action dry-run-order`: exercise the safe dry-run order path.
- `.\scripts\run.ps1 -Action quote`: fetch a market quote using current configuration.

## Coding Style & Naming Conventions
Use 4-space indentation, type hints, `from __future__ import annotations` for new modules, and explicit domain models rather than raw dictionaries at module boundaries. Keep functions and modules in `snake_case`, classes in `PascalCase`, constants in `UPPER_SNAKE_CASE`, and CLI options in kebab case. Prefer `Decimal` for monetary amounts and avoid logging secrets, signed URLs, or request signatures.

## Testing Guidelines
Pytest is the test framework. Add or update tests in `tests/test_<feature>.py` for every behavior change, especially trading mode checks, risk decisions, persistence, and CLI output. Use fixtures, monkeypatching, and temporary paths instead of live Binance calls. The existing autouse fixture clears `BINANCE_*` environment variables; set only the variables each test needs.

## Commit & Pull Request Guidelines
Recent history uses Conventional Commit prefixes such as `feat:`, `test:`, and `chore:`. Keep commit subjects imperative and specific, for example `feat: add live auto-sell preflight`. Pull requests should describe behavior changes, list verification commands run, call out configuration or trading-mode impact, and include screenshots only when CLI/table output materially changes.

## Security & Configuration Tips
Default to `BINANCE_MODE=dry_run` during development. Live and testnet workflows require explicit enablement flags and confirmation switches; do not bypass those guards. Treat `.env`, API keys, SQLite audit data, and log files as sensitive, and avoid adding new secrets to the repository.