diff --git a/README.md b/README.md
index 78b5852..b8ee897 100644
--- a/README.md
+++ b/README.md
@@ -1,161 +1,149 @@
-# coinhunter-cli
+
+
+
+
+ 
+
- The executable CLI layer for CoinHunter.
- Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
+ Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
- 
- 
- 
+ 
+ 
+ 
+ 
-## Why this repo exists
+---
-CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.
+## What is this?
-This repository is the tooling layer:
+`coinhunter-cli` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.
-- Code and executable behavior live here.
-- User runtime state lives in `~/.coinhunter/` by default.
-- Hermes skills can call this CLI instead of embedding large script collections.
-- Runtime paths can be overridden with `COINHUNTER_HOME`, `HERMES_HOME`, `COINHUNTER_ENV_FILE`, and `HERMES_BIN`.
+| Layer | Responsibility | Location |
+|-------|----------------|----------|
+| **CLI** | Top-level command router | `cli.py` |
+| **Commands** | Thin argument adapters | `commands/` |
+| **Services** | Orchestration & execution logic | `services/` |
+| **Runtime** | Paths, env, locks, config | `runtime.py` |
+| **User Data** | State, logs, reviews, positions | `~/.coinhunter/` |
-In short:
+> **Separation of concerns:** Code lives in this repo. Your data lives in `~/.coinhunter/`. Strategy and prompting live in Hermes skills.
-- `coinhunter-cli` = tool
-- CoinHunter skill = strategy / workflow / prompting layer
-- `~/.coinhunter` = user data, logs, state, reviews
+---
-## Current architecture
+## Project Structure
```text
-coinhunter-cli/
-├── src/coinhunter/
-│ ├── cli.py # top-level command router
-│ ├── runtime.py # runtime paths + env loading
-│ ├── doctor.py # diagnostics
-│ ├── paths.py # runtime path inspection
-│ ├── commands/ # thin CLI adapters
-│ ├── services/ # orchestration / application services
-│ └── *.py # compatibility modules + legacy logic under extraction
-└── README.md
+src/coinhunter/
+├── cli.py # Unified command router
+├── runtime.py # Runtime paths + env loading
+├── logger.py # Structured logging utilities
+├── commands/ # CLI adapters (thin, stateless)
+│ ├── precheck.py
+│ ├── smart_executor.py
+│ ├── check_api.py
+│ ├── doctor.py
+│ ├── external_gate.py
+│ ├── init_user_state.py
+│ ├── market_probe.py
+│ ├── paths.py
+│ ├── review_context.py
+│ ├── review_engine.py
+│ └── rotate_external_gate_log.py
+├── services/ # Orchestration & domain logic
+│ ├── exchange_service.py
+│ ├── portfolio_service.py
+│ ├── trade_execution.py
+│ ├── smart_executor_service.py
+│ ├── smart_executor_parser.py
+│ ├── execution_state.py
+│ ├── precheck_service.py
+│ ├── precheck_constants.py # thresholds & paths
+│ ├── time_utils.py # UTC/local time helpers
+│ ├── data_utils.py # json, hash, float, symbol norm
+│ ├── state_manager.py # state load/save/sanitize
+│ ├── market_data.py # exchange, OHLCV, metrics
+│ ├── candidate_scoring.py # coin selection & scoring
+│ ├── snapshot_builder.py # precheck snapshot construction
+│ ├── adaptive_profile.py # trigger profile builder
+│ ├── trigger_analyzer.py # trigger analysis core
+│ ├── precheck_analysis.py # failure payloads
+│ ├── precheck_snapshot.py # snapshot facade
+│ ├── precheck_state.py # state facade
+│ └── precheck_core.py # backward-compat export facade
+├── precheck.py # Backward-compat root facade
+├── smart_executor.py # Backward-compat root facade
+└── *.py # Other compat / utility modules
```
-The repo is actively being refactored toward a cleaner split:
-
-- `commands/` → argument / CLI adapters
-- `services/` → orchestration and application workflows
-- `runtime/` → paths, env, files, locks, config
-- future `domain/` → trading and precheck core logic
-
-## Implemented command/service splits
-
-The first extraction pass is already live:
-
-- `smart-executor` → `commands.smart_executor` + `services.smart_executor_service`
-- `precheck` → `commands.precheck` + `services.precheck_service`
-- root modules are compatibility facades only:
- - `src/coinhunter/precheck.py`
- - `src/coinhunter/smart_executor.py`
-- `precheck` internals now live in dedicated service modules:
- - `services.precheck_core`
- - `services.precheck_state`
- - `services.precheck_snapshot`
- - `services.precheck_analysis`
-
-This keeps behavior stable while giving the codebase a cleaner landing zone for deeper refactors.
+---
## Installation
-Dedicated user-local install:
+### Quick user install
```bash
./scripts/install_local.sh
```
-This creates:
+Creates:
+- Virtualenv: `~/.local/share/coinhunter-cli/venv`
+- Launcher: `~/.local/bin/coinhunter`
-- app environment: `~/.local/share/coinhunter-cli/venv`
-- launcher: `~/.local/bin/coinhunter`
-
-The launcher behaves like a normal installed CLI and simply forwards into the dedicated virtualenv.
-
-Editable install for development:
+### Editable dev install
```bash
pip install -e .
```
-Run directly after install:
+Verify:
```bash
coinhunter --help
coinhunter --version
```
-Short aliases are available for the most common commands. The original long-form command names remain supported for backward compatibility.
+---
-## Quickstart
+## Command Reference
-Initialize user state:
+### Short aliases (recommended)
```bash
-coinhunter init
+coinhunter diag # runtime diagnostics
+coinhunter paths # print resolved paths
+coinhunter api-check # validate exchange credentials
+coinhunter precheck # run precheck snapshot + trigger analysis
+coinhunter exec bal # print balances as JSON
+coinhunter exec overview # account overview as JSON
+coinhunter exec hold # record a HOLD decision
+coinhunter exec buy ENJUSDT 50 # buy $50 of ENJUSDT
+coinhunter exec flat ENJUSDT # sell entire ENJUSDT position
+coinhunter exec rotate PEPEUSDT ETHUSDT # rotate exposure
+coinhunter gate # external gate orchestration
+coinhunter review 12 # generate review context (last 12h)
+coinhunter recap 12 # generate review report (last 12h)
+coinhunter probe bybit-ticker BTCUSDT # market probe
+coinhunter rotate-log # rotate external gate logs
```
-Inspect runtime wiring:
-
-```bash
-coinhunter paths
-coinhunter diag
-```
-
-Validate exchange credentials:
-
-```bash
-coinhunter api-check
-```
-
-Run precheck / gate plumbing:
-
-```bash
-coinhunter precheck
-coinhunter precheck --mark-run-requested "external-gate queued cron run"
-coinhunter precheck --ack "analysis finished"
-coinhunter gate
-```
-
-Inspect balances or execute trading actions:
-
-```bash
-coinhunter exec bal
-coinhunter exec overview
-coinhunter exec hold
-coinhunter exec buy ENJUSDT 50
-coinhunter exec flat ENJUSDT
-coinhunter exec rotate PEPEUSDT ETHUSDT
-```
-
-Preferred `exec` verbs are `bal`, `overview`, `hold`, `buy`, `flat`, and `rotate`.
-Legacy forms remain supported for backward compatibility: `balances`, `balance`, `acct`, `status`, `sell-all`, `sell_all`, and `rebalance`.
-
-Generate review data:
-
-```bash
-coinhunter review 12
-coinhunter recap 12
-```
-
-Probe external market data:
-
-```bash
-coinhunter probe bybit-ticker BTCUSDT
-coinhunter probe bybit-klines BTCUSDT 60 20
-```
-
-Long-form equivalents still work:
+### Legacy long forms (still supported)
```bash
coinhunter doctor
@@ -168,109 +156,117 @@ coinhunter external-gate
coinhunter rotate-external-gate-log
```
-Supported top-level commands and aliases remain:
+### All supported commands
-- `check-api` / `api-check`
-- `doctor` / `diag`
-- `external-gate` / `gate`
-- `init`
-- `market-probe` / `probe`
-- `paths`
-- `precheck`
-- `review-context` / `review`
-- `review-engine` / `recap`
-- `rotate-external-gate-log` / `rotate-gate-log` / `rotate-log`
-- `smart-executor` / `exec`
+| Canonical | Aliases |
+|-----------|---------|
+| `check-api` | `api-check` |
+| `doctor` | `diag` |
+| `external-gate` | `gate` |
+| `init` | — |
+| `market-probe` | `probe` |
+| `paths` | — |
+| `precheck` | — |
+| `review-context` | `review` |
+| `review-engine` | `recap` |
+| `rotate-external-gate-log` | `rotate-gate-log`, `rotate-log` |
+| `smart-executor` | `exec` |
-## Runtime model
+---
-Default layout:
+## Quickstart
-```text
-~/.coinhunter/
-├── accounts.json
-├── config.json
-├── executions.json
-├── notes.json
-├── positions.json
-├── watchlist.json
-├── logs/
-├── reviews/
-└── state/
-```
-
-Credential loading:
-
-- Binance credentials are read from `~/.hermes/.env` by default.
-- `COINHUNTER_ENV_FILE` can point to a different env file.
-- `hermes` is resolved from `PATH` first, then `~/.local/bin/hermes`, unless `HERMES_BIN` overrides it.
-
-## Useful commands
-
-### Diagnostics
+Initialize runtime state:
+
+```bash
+coinhunter init
+```
+
+Inspect the environment:
```bash
-coinhunter diag
coinhunter paths
+coinhunter diag
+```
+
+Validate API keys:
+
+```bash
coinhunter api-check
```
-### Trading and execution
-
-```bash
-coinhunter exec bal
-coinhunter exec overview
-coinhunter exec hold
-coinhunter exec buy ENJUSDT 50
-coinhunter exec flat ENJUSDT
-coinhunter exec rotate FROMUSDT TOUSDT
-```
-
-### Precheck and orchestration
+Run the precheck workflow:
```bash
coinhunter precheck
-coinhunter gate
-coinhunter rotate-gate-log
-coinhunter rotate-log
+coinhunter precheck --ack "analysis completed"
```
-### Review and market research
+Run the external gate:
```bash
-coinhunter review 12
-coinhunter recap 12
-coinhunter probe bybit-ticker BTCUSDT
+coinhunter gate
```
-## Development notes
+---
-This project is intentionally moving in small, safe refactor steps:
+## Runtime Model
-1. Separate runtime concerns from hardcoded paths.
-2. Move command dispatch into thin adapters.
-3. Introduce orchestration services.
-4. Extract reusable domain logic from large compatibility modules.
-5. Keep cron / Hermes integration stable during migration.
+Default data layout:
-That means some compatibility modules still exist, but the direction is deliberate.
+```text
+~/.coinhunter/
+├── config.json
+├── positions.json
+├── accounts.json
+├── watchlist.json
+├── notes.json
+├── executions.json
+├── logs/
+├── reviews/
+├── cache/
+└── state/
+ ├── precheck_state.json
+ └── external_gate.lock
+```
-## Near-term roadmap
+Credential resolution:
-- Extract more logic from `smart_executor.py` into dedicated execution / portfolio services.
-- Continue shrinking `precheck.py` by moving snapshot and analysis internals into reusable modules.
-- Add `domain/` models for positions, signals, and trigger analysis.
-- Add tests for runtime paths, precheck service behavior, and CLI stability.
-- Evolve toward a more polished installable CLI workflow.
+- Binance API keys are read from `~/.hermes/.env` by default.
+- Override with `COINHUNTER_ENV_FILE`.
+- Override home with `COINHUNTER_HOME` or `HERMES_HOME`.
+- `hermes` binary is resolved from `PATH`, then `~/.local/bin/hermes`, unless `HERMES_BIN` is set.
+
+---
+
+## Development Status
+
+The codebase is actively maintained and refactored in small, safe steps.
+
+**Recently completed:**
+- ✅ Unified CLI entrypoint with short aliases
+- ✅ Extracted `smart-executor` into `commands/` + `services/`
+- ✅ Extracted `precheck` into 9 focused service modules
+- ✅ Migrated all active command modules into `commands/`
+- ✅ Removed dead `auto-trader` command
+- ✅ Backward-compatible root facades preserved
+
+**Next priorities:**
+- 🧪 Add pytest coverage for runtime paths, state manager, and trigger analyzer
+- 🔧 Extract `review_engine.py` core logic into `services/`
+- 🔧 Unify output contract (JSON-first with `--pretty` option)
+- 🔧 Add basic CI (lint + compileall + pytest)
+
+---
## Philosophy
-CoinHunter should become:
+CoinHunter is evolving toward:
-- more professional
-- more maintainable
-- safer to operate
-- easier for humans and agents to call
-- less dependent on prompt-only correctness
+- **Professional execution** — scientific position sizing, not moonshot gambling
+- **Maintainable architecture** — clear boundaries between CLI, services, and domain logic
+- **Safer operations** — dry-run, validation gates, and explicit decision logging
+- **Agent-friendly interfaces** — stable JSON outputs and predictable command contracts
+- **Less dependence on prompt-only correctness** — logic belongs in code, not just in system prompts
This repo is where that evolution happens.