feat: add decision calibration, prediction tracking, and reference routing

SKILL.md
- Add triggers/mode to frontmatter for better skill routing
- Add mandatory JSON decision skeleton before every trade
- Add multi-source confirmation rule and common-mistakes guardrails
- Add prediction logging to hourly review workflow
- Restructure References into an explicit routing table

CLAUDE.md
- Add Reference routing table for agent context
- Fix remaining Hermes-only wording in gate description

references/user-data-layout.md
- Add complete log schema: decisions, trades, predictions, errors
- Document predictions_YYYYMMDD.jsonl for calibration feedback loop

README.md
- Mention prediction tracking in "Why it works"
- Update runtime directory layout to include predictions.jsonl

references/shim-templates.md
- Show platform cron config usage examples

references/shim-templates.md

@@ -12,11 +12,11 @@ cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
 cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
 ```
 
-Usage examples:
-- `coinhunter_shim.py pre`
-- `coinhunter_shim.py gate`
-- `coinhunter_shim.py review`
-- `coinhunter_shim.py rotate-log`
+Usage in platform cron configs:
+- `"script": "coinhunter_shim.py pre"` — lightweight gate / precheck
+- `"script": "coinhunter_shim.py gate"` — external gate runner
+- `"script": "coinhunter_shim.py review"` — review context generator
+- `"script": "coinhunter_shim.py rotate-log"` — log rotation helper
 
 The real business logic lives in the external `coinhunter` CLI package (installed from PyPI). This shim only delegates to it.
 

references/user-data-layout.md

@@ -157,6 +157,88 @@ Example:
 ### cache/
 Store disposable API results or normalized snapshots. Never treat this as source-of-truth portfolio state.
 
+## Logs directory
+
+Runtime logs live under `~/.coinhunter/logs/` as daily JSONL files:
+
+```text
+~/.coinhunter/logs/
+├── decisions_YYYYMMDD.jsonl
+├── trades_YYYYMMDD.jsonl
+├── predictions_YYYYMMDD.jsonl
+├── errors_YYYYMMDD.jsonl
+└── external_gate.log
+```
+
+### decisions_YYYYMMDD.jsonl
+One line per agent decision pass.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "decision": "HOLD",
+  "confidence": 0.75,
+  "primary_reason": "BTC regime bearish",
+  "positions_hash": "abc123"
+}
+```
+
+### trades_YYYYMMDD.jsonl
+One line per executed trade.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "symbol": "BTCUSDT",
+  "side": "BUY",
+  "quantity": 0.01,
+  "price": 65000.0,
+  "status": "filled"
+}
+```
+
+### predictions_YYYYMMDD.jsonl
+One line per prediction made during execution. Used by the hourly review to calibrate accuracy.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "symbol": "BTCUSDT",
+  "decision": "HOLD",
+  "predicted_price_low": 64000.0,
+  "predicted_price_high": 67000.0,
+  "predicted_direction": "neutral",
+  "validation_time": "2026-04-16T16:00:00Z",
+  "stop_loss": 63000.0,
+  "take_profit": 68000.0,
+  "confidence": 0.75
+}
+```
+
+Rules for predictions:
+- `validation_time` should be 4 hours after `timestamp` by default.
+- Review logic compares `validation_time` price against `predicted_price_low/high`.
+- Systematic directional misses should trigger parameter tuning recommendations.
+
+### errors_YYYYMMDD.jsonl
+One line per error or reconciliation mismatch.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "error_type": "api_timeout",
+  "message": "Binance fetch_balance timed out after 30s"
+}
+```
+
 ## Rules
 
 - Keep personal data only under `~/.coinhunter/`