diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3dbc013
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development commands
+
+- **Editable install:** `pip install -e .`
+- **Run the CLI locally:** `python -m coinhunter --help`
+- **Install for end users:** `./scripts/install_local.sh` (creates `~/.local/bin/coinhunter`)
+- **Tests:** There is no test suite yet. The README lists next priorities as adding pytest coverage for runtime paths, state manager, and trigger analyzer.
+- **Lint / type-check:** Not configured yet.
+
+## CLI command routing
+
+`src/coinhunter/cli.py` is the single entrypoint. It resolves aliases to canonical commands, maps canonical commands to Python modules via `MODULE_MAP`, then imports the module and calls `module.main()` after mutating `sys.argv` to match the display name.
+
+Active commands live in `src/coinhunter/commands/` and are thin adapters that delegate to `src/coinhunter/services/`. A few legacy commands (`review_context.py`, `review_engine.py`) still live at the `src/coinhunter/` root and are imported directly by `cli.py`. Root-level backward-compat facades (e.g., `precheck.py`, `smart_executor.py`) re-export the moved commands.
+
+## Architecture
+
+### Layer responsibilities
+
+- **CLI (`cli.py`)** — argument parsing, alias resolution, module dispatch.
+- **Commands (`commands/`)** — thin, stateless adapters that call into services.
+- **Services (`services/`)** — orchestration, domain logic, and exchange interaction.
+- **Runtime (`runtime.py`)** — path resolution, env loading, hermes binary discovery.
+- **Logger (`logger.py`)** — structured JSONL logging to `~/.coinhunter/logs/`.
+
+### Runtime and environment
+
+`runtime.py` defines `RuntimePaths` and `get_runtime_paths()`. User data lives in `~/.coinhunter/` by default (override with `COINHUNTER_HOME`). Credentials are loaded from `~/.hermes/.env` by default (override with `COINHUNTER_ENV_FILE`). Many modules eagerly instantiate `PATHS = get_runtime_paths()` at import time.
+
+### Smart executor (`exec`)
+
+`commands/smart_executor.py` → `services/smart_executor_service.py` → `services/trade_execution.py`.
+
+Supported verbs: `bal`, `overview`, `hold`, `buy SYMBOL USDT`, `flat SYMBOL`, `rotate FROM TO`.
+
+- `smart_executor_parser.py` normalizes legacy argv and exposes `parse_cli_args()`.
+- `trade_common.py` holds a global dry-run flag (`set_dry_run` / `is_dry_run`).
+- `execution_state.py` tracks decision IDs in JSON to prevent duplicate executions.
+- `exchange_service.py` wraps `ccxt.binance` and handles symbol normalization.
+- `portfolio_service.py` manages `positions.json` load/save/reconcile.
+
+### Precheck
+
+`commands/precheck.py` → `services/precheck_service.py`.
+
+The precheck workflow:
+1. Load and sanitize state (`precheck_state.py` — clears stale triggers and run requests).
+2. Build a market snapshot (`precheck_snapshot.py` → `snapshot_builder.py`).
+3. Analyze whether to trigger deep analysis (`precheck_analysis.py` → `trigger_analyzer.py`).
+4. Update and save state (`precheck_state.update_state_after_observation`).
+
+State is stored in `~/.coinhunter/state/precheck_state.json`.
+
+### Review commands
+
+- `review N` (`review_context.py`) — generates review context for the last N hours.
+- `recap N` (`review_engine.py`) — generates a full review report by reading JSONL decision/trade/error logs, computing PnL estimates, missed opportunities, and saving a report to `~/.coinhunter/reviews/`.
+
+### Logging model
+
+`logger.py` writes JSONL to dated files in `~/.coinhunter/logs/`:
+- `decisions_YYYYMMDD.jsonl`
+- `trades_YYYYMMDD.jsonl`
+- `errors_YYYYMMDD.jsonl`
+- `snapshots_YYYYMMDD.jsonl`
+
+Use `get_logs_last_n_hours(log_type, hours)` to query recent entries.
+
+## Common command reference
+
+```bash
+# Diagnostics
+python -m coinhunter diag
+python -m coinhunter paths
+python -m coinhunter api-check
+
+# Execution (dry-run)
+python -m coinhunter exec bal
+python -m coinhunter exec overview
+python -m coinhunter exec buy ENJUSDT 50 --dry-run
+python -m coinhunter exec flat ENJUSDT --dry-run
+
+# Precheck
+python -m coinhunter precheck
+python -m coinhunter precheck --ack "analysis completed"
+python -m coinhunter precheck --mark-run-requested "reason"
+
+# Review
+python -m coinhunter review 12
+python -m coinhunter recap 12
+```
+
+## 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