# Repository Guidelines

## Project Structure & Module Organization

CoinHunter is a Python CLI package using a `src/` layout. Application code lives in `src/coinhunter/`.

- `src/coinhunter/cli.py` defines CLI parsing and command dispatch for `coinhunter` and `coin`.
- `src/coinhunter/binance/` contains thin Binance Spot client wrappers.
- `src/coinhunter/services/` contains domain logic for account, market, trade, portfolio, opportunity, dataset, research, and evaluation flows.
- `src/coinhunter/config.py`, `runtime.py`, and `audit.py` handle runtime config, output, completions, upgrade flow, and logs.
- `tests/` contains pytest/unittest coverage by service area.
- `dist/` contains built release artifacts; do not edit these manually.

## Build, Test, and Development Commands

Install locally with development tools:

```bash
python -m pip install -e '.[dev]'
```

Run the CLI from the working tree:

```bash
coinhunter --help
coin opportunity -s BTCUSDT ETHUSDT --agent
```

Quality checks:

```bash
pytest tests/           # run the full test suite
ruff check src tests    # lint and import ordering
mypy src                # static type checks
```

## Coding Style & Naming Conventions

Use Python 3.10+ syntax and 4-space indentation. Keep modules small and service-oriented; prefer adding logic under `src/coinhunter/services/` and keeping `cli.py` focused on argument parsing and dispatch.

Use `snake_case` for functions, variables, and modules. Use `PascalCase` for classes and dataclasses. Preserve existing payload key naming conventions such as `notional_usdt`, `quote_volume`, and `opportunity_score`.

Ruff enforces `E`, `F`, `I`, `W`, `UP`, `B`, `C4`, and `SIM`; line length `E501` is ignored.

## Testing Guidelines

Tests use `pytest` with `unittest.TestCase`. Add tests near the changed behavior:

- CLI dispatch: `tests/test_cli.py`
- Config/runtime: `tests/test_config_runtime.py`
- Opportunity logic: `tests/test_opportunity_service.py`
- Dataset/evaluation flows: `tests/test_opportunity_dataset_service.py`

Name tests as `test_<behavior>`. Prefer fake clients and injected HTTP functions over live network calls. Run `pytest tests/` before submitting changes.

## Commit & Pull Request Guidelines

Recent history uses short imperative subjects, often Conventional Commit prefixes:

- `feat: configurable ticker window for market stats`
- `fix: use rolling_window_ticker for symbol-specific queries`
- `refactor: flatten account command to a single balances view`

Keep commits focused and describe user-visible behavior. Pull requests should include a concise summary, validation commands run, and any config or CLI changes. Link issues when applicable. For CLI output changes, include before/after examples or JSON snippets.

## Security & Configuration Tips

Never commit Binance API keys, secrets, runtime logs, or local `~/.coinhunter` files. Runtime secrets belong in `~/.coinhunter/.env`; configuration belongs in `~/.coinhunter/config.toml`. Use `COINHUNTER_HOME` for isolated test runs.