echolon 0.3.0__tar.gz → 0.3.2__tar.gz

echolon-0.3.2/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.3.0 — AI-Native Layer (unreleased)
+
+### Added
+- `echolon.native` subpackage with error system, validators, CLI, and templates
+- `EchelonError` class hierarchy with 13 initial error codes
+- `echolon` CLI with 5 commands: `validate`, `init-strategy`, `run`, `schema`, `examples`
+- 3 strategy templates: `minimal`, `momentum_breakout`, `rsi_mean_reversion`
+- 3 working examples at `examples/`
+- `llms.txt` at repo root (AI agent entry point)
+- `docs/` directory with QUICK_START, API_REFERENCE, COMPONENT_GUIDE, CONFIG_REFERENCE, PATTERNS, ERROR_CATALOG, and per-error docs
+
+### Changed
+- Added `typer>=0.9.0` as a dependency for the CLI
+
+## 0.2.0 — Config Interface
+
+### Breaking Changes
+- BacktestRunner, OptunaOptimizer, WFARunner, and PortfolioBacktestRunner now require explicit configs
+- Removed module-level globals from `echolon.config.quant_engine`
+
+### Added
+- BacktestConfig, OptunaConfig, IndicatorConfig Pydantic models
+- `TradingContext.from_market()` classmethod
+- `echolon.quick_start()` convenience helper
+
+## 0.1.0 — Initial Release
+
+Initial extraction from DolphinQuantStrategy monorepo.

{echolon-0.3.0 → echolon-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echolon
-Version: 0.3.0
+Version: 0.3.2
 Summary: See what others can't. Market-agnostic quantitative trading engine for futures backtesting, optimization, and deployment.
 Project-URL: Homepage, https://github.com/dolphinquant/echolon
 Project-URL: Repository, https://github.com/dolphinquant/echolon

echolon-0.3.2/docs/API_REFERENCE.md

@@ -0,0 +1,188 @@
+# API Reference
+
+All public Echolon classes and their signatures.
+
+## BacktestConfig
+
+**Module:** `echolon.config.backtest_config`
+
+**Purpose:** Configuration for a single backtest run — dates, paths, thresholds.
+
+**Signature:**
+
+```python
+BacktestConfig(
+    start_date: str,            # "YYYY-MM-DD"
+    end_date: str,              # "YYYY-MM-DD"
+    strategy_dir: Path,
+    market_data_dir: Path,
+    indicator_dir: Path,
+    results_dir: Path,
+    max_drawdown_pct: float = 15.0,
+    is_end_date: Optional[str] = None,
+    oos_start_date: Optional[str] = None,
+    market_research_end_date: Optional[str] = None,
+)
+```
+
+**Example:**
+
+```python
+from echolon import BacktestConfig
+from pathlib import Path
+
+cfg = BacktestConfig(
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+    strategy_dir=Path("./my_strategy"),
+    market_data_dir=Path("./data/market"),
+    indicator_dir=Path("./data/indicators"),
+    results_dir=Path("./results"),
+)
+```
+
+**Common errors:** CFG-001, CFG-002.
+
+## OptunaConfig
+
+**Module:** `echolon.config.optuna_config`
+
+**Purpose:** Optuna hyperparameter optimization settings.
+
+**Signature:**
+
+```python
+OptunaConfig(
+    n_trials: int = 100,
+    n_jobs: int = -1,
+    timeout: Optional[int] = None,
+    target: Literal["sharpe_ratio", "total_return", "annual_return", "drawdown", "multi_objective"] = "sharpe_ratio",
+    n_trials_debug: int = 20,
+    aggressive_memory_management: bool = False,
+    enhanced_monitoring: bool = True,
+)
+```
+
+## IndicatorConfig
+
+**Module:** `echolon.config.indicator_config`
+
+**Purpose:** Technical indicator period caps (most users never override).
+
+**Signature:**
+
+```python
+IndicatorConfig(
+    interday_caps: dict[str, int],
+    intraday_caps: dict[str, int],
+)
+```
+
+## TradingContext
+
+**Module:** `echolon.config.markets.core.context`
+
+**Purpose:** Market + instrument + frequency runtime context.
+
+**Classmethod:**
+
+```python
+TradingContext.from_market(
+    market: str,           # e.g., "shfe"
+    instrument: str,       # e.g., "cu"
+    frequency: str = "interday",
+    bar_size: str = "1d",
+) -> TradingContext
+```
+
+## quick_start()
+
+**Module:** `echolon`
+
+**Purpose:** Build sensible default configs for common cases.
+
+```python
+from echolon import quick_start
+
+ctx, bt, opt = quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+)
+```
+
+## EntrySignalOutput
+
+**Module:** `echolon.quant_engine.types`
+
+**Returned by:** `entry_rule.generate_signal()`
+
+**Required fields:**
+- `signal: Literal['LONG', 'SHORT', 'HOLD']`
+- `strength: float` (0.0 to 1.0)
+- `type: str`
+- `entry_reason: str`
+- `regime: str`
+
+**Optional:**
+- `intent: Optional[OrderIntent]` — required for non-HOLD signals
+
+**Common errors:** VAL-001, VAL-002.
+
+## ExitSignalOutput
+
+**Returned by:** `exit_rule.should_exit()`
+
+**Required fields:**
+- `should_exit: bool`
+- `exit_reason: str`
+- `position_size: float` (≥ 0)
+- `bars_since_entry: int` (≥ 0)
+
+**Optional:**
+- `intent: Optional[OrderIntent]` — required when `should_exit=True`
+
+## RiskOutput
+
+**Returned by:** `risk_manager.can_trade()`
+
+**Required fields:**
+- `trading_allowed: bool`
+- `risk_reason: str`
+
+## SizerOutput
+
+**Returned by:** `position_sizer.calculate_size(signal_data)`
+
+**Required fields:**
+- `calculated_size: int` (≥ 0, whole contracts)
+- `signal_direction: Literal['LONG', 'SHORT', 'HOLD']`
+- `sizing_reason: str`
+- `raw_size: float` (≥ 0)
+
+## OrderIntent (enum)
+
+**Module:** `echolon.quant_engine.core.interfaces.trading_interfaces`
+
+**Values:**
+- `ENTRY_LONG`, `ENTRY_SHORT`
+- `EXIT_LONG`, `EXIT_SHORT`
+- `FORCED_EXIT`
+- `ROLLOVER_CLOSE`, `ROLLOVER_OPEN`
+
+## EchelonError
+
+**Module:** `echolon` (top-level) or `echolon.native.validation.errors`
+
+**Base class** for all Echolon validation errors. Every error has `code`, `what`, `why`, `fix`, `context`, `docs_url`.
+
+**Subclasses:**
+- `ValidationError` (VAL-xxx)
+- `ConfigError` (CFG-xxx)
+- `StrategyStructureError` (STR-xxx)
+- `IndicatorError` (IND-xxx)
+- `ParameterError` (PRM-xxx)
+- `DataError` (DAT-xxx)
+
+See [ERROR_CATALOG.md](ERROR_CATALOG.md).

echolon-0.3.2/docs/COMPONENT_GUIDE.md

@@ -0,0 +1,115 @@
+# Component Guide
+
+Every Echolon strategy has 4 components. This guide explains each one.
+
+## entry_rule (entry.py)
+
+**Class name:** `entry_rule` (exact — required by StrategyLoader)
+**Base:** `BaseComponent`
+**Method:** `generate_signal() -> EntrySignalOutput`
+
+Called every bar when there is no open position and no pending orders.
+
+**Example:**
+
+```python
+from echolon.quant_engine.core.base.base_component import BaseComponent
+from echolon.quant_engine.core.interfaces.trading_interfaces import OrderIntent
+from echolon.quant_engine.types import EntrySignalOutput
+
+
+class entry_rule(BaseComponent):
+    def __init__(self, trading_engine, **params):
+        super().__init__(trading_engine, **params)
+        self.rsi_period = self.params["rsi_period"]
+
+    def generate_signal(self) -> EntrySignalOutput:
+        rsi = self.get_indicator(f"rsi_{self.rsi_period}")
+        regime = self.get_market_regime()
+        if rsi < 30:
+            return EntrySignalOutput(
+                signal="LONG", strength=1.0,
+                type="oversold_entry",
+                entry_reason=f"RSI({self.rsi_period})={rsi} < 30",
+                intent=OrderIntent.ENTRY_LONG,
+                regime=regime,
+            )
+        return EntrySignalOutput(
+            signal="HOLD", strength=0.0, type="hold",
+            entry_reason="Not oversold", regime=regime,
+        )
+```
+
+**Common errors:**
+- VAL-001: missing required field
+- VAL-003: wrong __init__ signature
+- IND-001: uppercase indicator name
+
+## exit_rule (exit.py)
+
+**Class name:** `exit_rule`
+**Base:** `BaseComponent`
+**Method:** `should_exit() -> ExitSignalOutput`
+
+Called every bar when there is an open position.
+
+Stateful exit rules (trailing stops, bars-held counters) must reset their state when there is no position. See the minimal template's `exit.py`.
+
+## risk_manager (risk.py)
+
+**Class name:** `risk_manager`
+**Base:** `BaseComponent`
+**Method:** `can_trade() -> RiskOutput`
+
+Called at the start of every bar. Returns `trading_allowed=True` to permit trading, `False` to block all new entries.
+
+Use cases: max daily loss, max consecutive losses, trading-hours filter.
+
+## position_sizer (sizer.py)
+
+**Class name:** `position_sizer`
+**Base:** `BaseComponent`
+**Method:** `calculate_size(signal_data: EntrySignalOutput) -> SizerOutput`
+
+Called after `entry_rule.generate_signal()` produces a non-HOLD signal. Receives the signal (so sizer can branch on regime, strength, etc.).
+
+The sizer MUST call `self.validate_and_convert_position_size(raw_float)` before setting `calculated_size` — this rounds to whole contracts and handles edge cases.
+
+## Data access helpers
+
+All components inherit these helpers from `BaseComponent`:
+
+- `self.get_current_price() -> float` — close of current bar
+- `self.get_indicator(name: str) -> float` — value of pre-computed indicator (use lowercase names!)
+- `self.get_market_regime() -> str` — one of: `ranging`, `trending_up`, `trending_down`, `volatile`
+- `self.params: dict` — parameters from strategy_params.py
+- `self.portfolio: IPortfolio` — access position info
+- `self.validate_and_convert_position_size(float) -> int` — sizer helper
+
+## Strategy coordinator (strategy.py)
+
+**Class name:** `strategy_main`
+**Base:** `BaseStrategy`
+**Method:** `_execute_bar() -> None` (not `on_bar`)
+
+The canonical pattern:
+
+```python
+def _execute_bar(self) -> None:
+    risk_out = self.risk_manager.can_trade()
+    if not risk_out.trading_allowed:
+        return
+    if self.has_position() and not self.has_pending_orders():
+        exit_out = self.exit_rule.should_exit()
+        if exit_out.should_exit and exit_out.intent is not None:
+            self.exit(exit_out.intent)
+            return
+    if not self.has_position() and not self.has_pending_orders():
+        entry_out = self.entry_rule.generate_signal()
+        if entry_out.signal != "HOLD" and entry_out.intent is not None:
+            sizer_out = self.position_sizer.calculate_size(entry_out)
+            if sizer_out.calculated_size > 0:
+                self.entry(entry_out.intent, sizer_out.calculated_size)
+```
+
+Every bundled template uses this exact pattern. Only customize if your strategy truly needs a different structure.

echolon-0.3.2/docs/CONFIG_REFERENCE.md

@@ -0,0 +1,68 @@
+# Configuration Reference
+
+Echolon uses Pydantic v2 models for all configuration. Each config class is a typed object — IDEs and LLMs can introspect it.
+
+## BacktestConfig
+
+See [API_REFERENCE.md#backtestconfig](API_REFERENCE.md#backtestconfig).
+
+Common mistakes:
+- `end_date` before `start_date` → CFG-001
+- Missing directory path → CFG-002
+
+## OptunaConfig
+
+See [API_REFERENCE.md#optunaconfig](API_REFERENCE.md#optunaconfig).
+
+The `target` field accepts:
+- `"sharpe_ratio"` — maximize risk-adjusted return (default)
+- `"total_return"` — maximize absolute return
+- `"annual_return"` — maximize annualized return
+- `"drawdown"` — minimize max drawdown
+- `"multi_objective"` — Pareto frontier over Sharpe + drawdown
+
+## TradingContext
+
+Runtime context: market, instrument, frequency, bar size.
+
+```python
+from echolon import TradingContext
+
+ctx = TradingContext.from_market(
+    market="shfe",
+    instrument="cu",
+    frequency="interday",
+    bar_size="1d",
+)
+```
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ECHOLON_WORKSPACE_DIR` | `./workspace` | Workspace root |
+| `ECHOLON_DATA_DIR` | `./data` | Market data + indicators |
+| `ECHOLON_LOG_LEVEL` | `INFO` | Logging verbosity |
+| `ECHOLON_N_JOBS_DEFAULT` | `-1` | Default Optuna parallelism |
+
+Set via shell export, `.env` file, or Docker env config.
+
+## quick_start()
+
+For common cases, use the convenience helper:
+
+```python
+from echolon import quick_start
+
+ctx, bt, opt = quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+)
+# Override anything
+opt.n_trials = 500
+bt.max_drawdown_pct = 20.0
+```
+
+`quick_start` uses env vars for paths with fallbacks to `./workspace` and `./data`.

echolon-0.3.2/docs/ERROR_CATALOG.md

@@ -0,0 +1,19 @@
+# Error Catalog
+
+All Echolon errors use stable codes. Click any code for the full fix guide.
+
+| Code | Category | What went wrong |
+|------|----------|-----------------|
+| [VAL-001](errors/VAL-001.md) | Validation | Missing required field in component output |
+| [VAL-002](errors/VAL-002.md) | Validation | Invalid enum value in signal field |
+| [VAL-003](errors/VAL-003.md) | Validation | Component class signature mismatch |
+| [CFG-001](errors/CFG-001.md) | Config | end_date before start_date |
+| [CFG-002](errors/CFG-002.md) | Config | Required directory does not exist |
+| [STR-001](errors/STR-001.md) | Structure | Strategy directory missing required file |
+| [STR-002](errors/STR-002.md) | Structure | Required class not found in file |
+| [STR-003](errors/STR-003.md) | Structure | Required method not implemented |
+| [IND-001](errors/IND-001.md) | Indicator | Indicator name casing mismatch |
+| [IND-002](errors/IND-002.md) | Indicator | Indicator not declared in JSON |
+| [PRM-001](errors/PRM-001.md) | Parameter | Missing 'printlog' key in component params |
+| [PRM-002](errors/PRM-002.md) | Parameter | DEFAULT_PARAMS structure mismatch |
+| [DAT-001](errors/DAT-001.md) | Data | Missing OHLCV file |

echolon-0.3.2/docs/PATTERNS.md

@@ -0,0 +1,185 @@
+# Patterns
+
+Canonical strategy patterns in Echolon. Each pattern includes when to use it, the core idea, files to customize, and common errors.
+
+## Indicator Naming Rules
+
+1. **Column names are always lowercase.** `ATR` in JSON → `atr_14`, `atr_15`, ... in code.
+2. **Use `self.get_indicator('lowercase_name')`.** Uppercase causes silent `KeyError` or `NaN`.
+3. **Declare every indicator in `strategy_indicator_list.json`.** Undeclared indicators aren't pre-computed.
+4. **System indicators** (`market_regime`, `session_phase`) go in `indicators_with_special_params`.
+
+See [IND-001](errors/IND-001.md) for the casing-mismatch error.
+
+## 1. Trend Breakout
+
+**When to use:** Strong trending markets; instruments with persistent momentum (index futures, commodities in backwardation).
+
+**Key idea:** Enter when price breaks above an N-day rolling high (or below an N-day rolling low for shorts). Exit on a trailing-low stop or opposite-direction break.
+
+**Files to customize:**
+- `entry.py` — compare `self.get_current_price()` to `self.get_indicator('high_20')` (or similar)
+- `exit.py` — track highest-close-since-entry, exit on pullback
+- `strategy_indicator_list.json` — declare `rolling_high`, `rolling_low`, `atr`
+
+**Sketch:**
+
+```python
+def generate_signal(self) -> EntrySignalOutput:
+    price = self.get_current_price()
+    upper = self.get_indicator(f"rolling_high_{self.lookback}")
+    regime = self.get_market_regime()
+    if price > upper:
+        return EntrySignalOutput(
+            signal="LONG", strength=1.0, type="breakout",
+            entry_reason=f"Close {price} > {self.lookback}d high {upper}",
+            intent=OrderIntent.ENTRY_LONG, regime=regime,
+        )
+    return EntrySignalOutput(signal="HOLD", strength=0.0, type="hold",
+                             entry_reason="No breakout", regime=regime)
+```
+
+**Common errors:** IND-001 (uppercase `ROLLING_HIGH`), VAL-001 (missing `regime`).
+
+## 2. Mean Reversion
+
+**When to use:** Range-bound markets; instruments that oscillate around a mean (pairs, yield curve spreads, some FX crosses).
+
+**Key idea:** Enter when an oscillator crosses an oversold/overbought threshold. Exit when it reverts to neutral.
+
+**Files to customize:**
+- `entry.py` — check `self.get_indicator(f"rsi_{period}")` < 30 (oversold)
+- `exit.py` — exit when RSI > 50 or a bars-held cap is reached
+- `strategy_indicator_list.json` — declare `rsi` at your chosen period
+
+**Sketch:**
+
+```python
+def generate_signal(self) -> EntrySignalOutput:
+    rsi = self.get_indicator(f"rsi_{self.rsi_period}")
+    regime = self.get_market_regime()
+    if rsi < self.oversold_threshold:
+        return EntrySignalOutput(
+            signal="LONG", strength=1.0, type="oversold",
+            entry_reason=f"RSI={rsi} below {self.oversold_threshold}",
+            intent=OrderIntent.ENTRY_LONG, regime=regime,
+        )
+    return EntrySignalOutput(signal="HOLD", strength=0.0, type="hold",
+                             entry_reason="Not oversold", regime=regime)
+```
+
+**Common errors:** PRM-001 (missing `printlog` in `entry_params`), VAL-002 (using `BUY` instead of `LONG`).
+
+## 3. Regime-Switching
+
+**When to use:** Strategies that must behave differently based on market condition — e.g., momentum in trending regimes, mean reversion in ranging.
+
+**Key idea:** Branch the entry/exit logic on `self.get_market_regime()`. The system regime indicator classifies bars as `trending_up`, `trending_down`, `ranging`, or `volatile`.
+
+**Files to customize:**
+- `entry.py` — outer `if regime == "trending_up"` branches
+- `strategy_indicator_list.json` — add `market_regime` to `indicators_with_special_params`
+- `strategy_params.py` — define per-regime thresholds (e.g., `trend_threshold`, `range_threshold`)
+
+**Sketch:**
+
+```python
+def generate_signal(self) -> EntrySignalOutput:
+    regime = self.get_market_regime()
+    price = self.get_current_price()
+    if regime == "trending_up":
+        upper = self.get_indicator(f"rolling_high_{self.trend_lookback}")
+        if price > upper:
+            return EntrySignalOutput(
+                signal="LONG", strength=1.0, type="trend_break",
+                entry_reason="Trending regime breakout",
+                intent=OrderIntent.ENTRY_LONG, regime=regime,
+            )
+    elif regime == "ranging":
+        rsi = self.get_indicator(f"rsi_{self.rsi_period}")
+        if rsi < 30:
+            return EntrySignalOutput(
+                signal="LONG", strength=1.0, type="range_revert",
+                entry_reason="Range oversold",
+                intent=OrderIntent.ENTRY_LONG, regime=regime,
+            )
+    return EntrySignalOutput(signal="HOLD", strength=0.0, type="hold",
+                             entry_reason=f"No signal in {regime}", regime=regime)
+```
+
+**Common errors:** IND-002 (forgetting to declare `market_regime` in JSON), VAL-001 (missing `regime` in HOLD branch).
+
+## 4. Multi-Timeframe
+
+**When to use:** Intraday execution informed by a higher-timeframe bias (e.g., take long signals only when daily EMA is rising).
+
+**Key idea:** Pre-compute the higher-timeframe indicator at daily frequency, then expose its last value to each intraday bar via the indicator pipeline. The strategy code sees a single indicator column; resampling is done upstream.
+
+**Files to customize:**
+- `strategy_indicator_list.json` — add a daily-resampled indicator like `ema_daily_50`
+- `entry.py` — gate signals on the daily indicator before checking intraday triggers
+
+**Sketch:**
+
+```python
+def generate_signal(self) -> EntrySignalOutput:
+    daily_ema = self.get_indicator("ema_daily_50")
+    intraday_ema = self.get_indicator(f"ema_{self.fast_period}")
+    price = self.get_current_price()
+    regime = self.get_market_regime()
+    long_bias = price > daily_ema
+    if long_bias and price > intraday_ema:
+        return EntrySignalOutput(
+            signal="LONG", strength=1.0, type="mtf_pullback",
+            entry_reason="Above daily EMA and intraday EMA",
+            intent=OrderIntent.ENTRY_LONG, regime=regime,
+        )
+    return EntrySignalOutput(signal="HOLD", strength=0.0, type="hold",
+                             entry_reason="No MTF alignment", regime=regime)
+```
+
+**Common errors:** IND-002 (daily indicator not declared), DAT-001 (daily data file missing).
+
+## 5. ML Signal
+
+**When to use:** You have a trained model (scikit-learn, XGBoost, small PyTorch) that outputs a directional score from a fixed feature vector.
+
+**Key idea:** Load the pickled model once in `__init__`. In `generate_signal()`, build the feature vector from `self.get_indicator(...)` calls, call `model.predict_proba`, and threshold the output.
+
+**Files to customize:**
+- `entry.py` — `__init__` loads the model; `generate_signal` builds features and predicts
+- `strategy_indicator_list.json` — declare every feature the model expects
+- `strategy_params.py` — expose the probability threshold as a tunable parameter
+
+**Sketch:**
+
+```python
+import joblib
+import numpy as np
+from pathlib import Path
+
+class entry_rule(BaseComponent):
+    def __init__(self, trading_engine, **params):
+        super().__init__(trading_engine, **params)
+        self.model = joblib.load(Path(self.params["model_path"]))
+        self.prob_threshold = self.params["prob_threshold"]
+
+    def generate_signal(self) -> EntrySignalOutput:
+        regime = self.get_market_regime()
+        features = np.array([[
+            self.get_indicator("rsi_14"),
+            self.get_indicator("atr_14"),
+            self.get_indicator("ema_20"),
+        ]])
+        prob_long = float(self.model.predict_proba(features)[0, 1])
+        if prob_long > self.prob_threshold:
+            return EntrySignalOutput(
+                signal="LONG", strength=prob_long, type="ml_long",
+                entry_reason=f"p(long)={prob_long:.3f}",
+                intent=OrderIntent.ENTRY_LONG, regime=regime,
+            )
+        return EntrySignalOutput(signal="HOLD", strength=0.0, type="hold",
+                                 entry_reason="Below threshold", regime=regime)
+```
+
+**Common errors:** DAT-001 (model file missing), IND-002 (feature indicator not declared), PRM-002 (`model_path` missing from `entry_params`).

echolon-0.3.2/docs/QUICK_START.md

@@ -0,0 +1,50 @@
+# Quick Start
+
+Install Echolon, create a minimal strategy, run your first backtest.
+
+## 1. Install
+
+```bash
+pip install echolon
+```
+
+## 2. Create a strategy
+
+```bash
+echolon init-strategy my_first --template minimal
+```
+
+This creates `./my_first/` with 7 files:
+- `strategy.py` — strategy coordinator
+- `entry.py`, `exit.py`, `risk.py`, `sizer.py` — component files
+- `strategy_params.py` — parameter definitions
+- `strategy_indicator_list.json` — which indicators to compute
+- `README.md` — template notes
+
+## 3. Validate it
+
+```bash
+echolon validate my_first/
+```
+
+Should print: `✓ Strategy directory is valid.`
+
+## 4. Customize `entry.py`
+
+Open `my_first/entry.py` and replace the HOLD-forever logic with your signal.
+
+## 5. Run backtest
+
+```bash
+echolon run my_first/ --instrument cu --start 2020-01-01 --end 2023-12-31
+```
+
+## If you hit an error
+
+Every error includes a code like `[VAL-001]`. Look it up in [ERROR_CATALOG.md](ERROR_CATALOG.md) or at `https://echolon.dev/docs/errors/{code}`.
+
+## Next Steps
+
+- Read [COMPONENT_GUIDE.md](COMPONENT_GUIDE.md) to understand each component
+- Browse [PATTERNS.md](PATTERNS.md) for canonical strategy shapes
+- See [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) for full configuration options