diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e7ae3ea
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,68 @@
+# 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.