tradelab 0.3.0 → 0.4.0

package/README.md

@@ -1,55 +1,61 @@
-<img src="https://i.imgur.com/HGvvQbq.png" width="500" alt="tradelab logo"/>
+<div align="center">
+  <img src="https://i.imgur.com/HGvvQbq.png" width="420" alt="tradelab logo" />
 
-# tradelab
+  <p><strong>A Node.js backtesting toolkit for serious trading strategy research.</strong></p>
 
-`tradelab` is a Node.js backtesting toolkit for trading strategy research. It lets you:
-- load candles from Yahoo Finance or CSV
-- run candle-based backtests with sizing, exits, and risk controls
-- export trades, metrics, and HTML reports
+  [![npm version](https://img.shields.io/npm/v/tradelab?color=0f172a&label=npm&logo=npm)](https://www.npmjs.com/package/tradelab)
+  [![GitHub](https://img.shields.io/badge/github-ishsharm0/tradelab-0f172a?logo=github)](https://github.com/ishsharm0/tradelab)
+  [![License: MIT](https://img.shields.io/badge/license-MIT-0f172a)](https://github.com/ishsharm0/tradelab/blob/main/LICENSE)
+  [![Node.js](https://img.shields.io/badge/node-%3E%3D18-0f172a?logo=node.js)](https://nodejs.org)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-ready-0f172a?logo=typescript)](https://github.com/ishsharm0/tradelab/blob/main/types/index.d.ts)
 
-The package is modular by design, so you can use just the parts you need: data loading, backtesting, reporting, or the utility layer on its own.
+</div>
 
-It is built for historical research and testing, not broker connectivity or live trading.
+---
 
-## Features
+**tradelab** handles the simulation, sizing, exits, costs, and result exports — you bring the candles and signal logic.
 
-- Modular structure: use the full workflow or just the engine, data layer, reporting, or helpers
-- Backtest engine with pending entries, OCO exits, scale-outs, pyramiding, cooldowns, daily loss limits, optional replay/equity capture, and configurable slippage/commission modeling
-- Historical data loading from Yahoo Finance, with local caching to avoid repeated downloads
-- CSV import for common OHLCV formats and custom column mappings
-- Position-level and leg-level metrics, including drawdown, expectancy, hold-time stats, and side breakdowns
-- Multi-symbol portfolio aggregation and rolling walk-forward optimization helpers
-- HTML report export, metrics JSON export, and trade CSV export
-- Utility indicators and session helpers for strategy development
-- CLI entrypoint for fetching data and running quick backtests from the terminal
-- TypeScript definitions for the public API
-
-## Installation
+It works cleanly for a single-strategy backtest and scales up to portfolio runs, walk-forward testing, and detailed execution modeling. It is not a broker connector or a live trading tool.
 
 ```bash
 npm install tradelab
 ```
 
-Node `18+` is required.
+---
 
-## Importing
+## Table of contents
 
+- [What it includes](#what-it-includes)
+- [Quick start](#quick-start)
+- [Loading historical data](#loading-historical-data)
+- [Core concepts](#core-concepts)
+- [Portfolio mode](#portfolio-mode)
+- [Walk-forward optimization](#walk-forward-optimization)
+- [Execution and cost modeling](#execution-and-cost-modeling)
+- [Exports and reporting](#exports-and-reporting)
+- [CLI](#cli)
+- [Examples](#examples)
+- [Documentation](#documentation)
 
-### ESM (recommended)
+---
 
-```js
-import { backtest, getHistoricalCandles, ema } from "tradelab";
-import { fetchHistorical } from "tradelab/data";
-```
+## What it includes
 
-### CommonJS
+| Area | What you get |
+|---|---|
+| **Engine** | Candle-based backtests with position sizing, exits, risk controls, replay capture |
+| **Portfolio** | Multi-symbol aggregation with weight-based capital allocation |
+| **Walk-forward** | Rolling train/test validation with parameter search |
+| **Data** | Yahoo Finance downloads, CSV import, and local cache helpers |
+| **Costs** | Slippage, spread, and commission modeling |
+| **Exports** | HTML reports, metrics JSON, and trade CSV |
+| **Dev experience** | TypeScript definitions, ESM/CJS support, CLI for quick runs |
 
-```js
-const { backtest, getHistoricalCandles, ema } = require("tradelab");
-const { fetchHistorical } = require("tradelab/data");
-```
+---
+
+## Quick start
 
-## Quick Start
+If you already have candles, `backtest()` is the main entry point.
 
 ```js
 import { backtest, ema, exportBacktestArtifacts } from "tradelab";
@@ -75,29 +81,23 @@ const result = backtest({
       const risk = entry - stop;
       if (risk <= 0) return null;
 
-      return {
-        side: "long",
-        entry,
-        stop,
-        rr: 2,
-      };
+      return { side: "long", entry, stop, rr: 2 };
     }
 
     return null;
   },
 });
 
-exportBacktestArtifacts({
-  result,
-  outDir: "./output",
-});
+exportBacktestArtifacts({ result, outDir: "./output" });
 ```
 
-## Getting Historical Data
+After the run, check `result.metrics` for the headline numbers and `result.positions` for the trade log.
 
-The simplest entry point is `getHistoricalCandles()`. For most users, it is the only data-loading function you need.
+---
 
-### Yahoo Finance
+## Loading historical data
+
+Most users can start with `getHistoricalCandles()`. It abstracts over Yahoo Finance and CSV, handles caching, and normalizes the output so it feeds straight into `backtest()`.
 
 ```js
 import { getHistoricalCandles, backtest } from "tradelab";
@@ -107,138 +107,277 @@ const candles = await getHistoricalCandles({
   symbol: "SPY",
   interval: "1d",
   period: "2y",
-  cache: true,
+  cache: true,       // reuses local copy on repeated runs
 });
 
-const result = backtest({
-  candles,
-  symbol: "SPY",
-  interval: "1d",
-  range: "2y",
-  signal,
-});
+const result = backtest({ candles, symbol: "SPY", interval: "1d", range: "2y", signal });
 ```
 
-Supported period examples: `5d`, `60d`, `6mo`, `1y`.
+**Supported sources:** `yahoo` · `csv` · `auto`
 
-### CSV
+**Supported periods:** `5d` · `60d` · `6mo` · `1y` · `2y` · and more
 
-```js
-import { getHistoricalCandles } from "tradelab";
+Use `cache: true` for repeatable research runs. It eliminates network noise and makes failures easier to diagnose.
+
+### CSV import
 
+```js
 const candles = await getHistoricalCandles({
   source: "csv",
-  symbol: "BTC-USD",
-  interval: "5m",
-  csvPath: "./data/btc-5m.csv",
+  csvPath: "./data/spy.csv",
   csv: {
-    timeCol: "time",
+    timeCol: "timestamp",
     openCol: "open",
-    highCol: "high",
-    lowCol: "low",
-    closeCol: "close",
-    volumeCol: "volume",
+    // ... optional column mapping
   },
 });
 ```
 
-If you pass `csvPath` and omit `source`, the loader will auto-detect CSV mode.
+If your CSV already uses standard OHLCV column names, no mapping is needed at all.
+
+---
 
-## Signal Contract
+## Core concepts
 
-Your strategy function receives:
+### The signal function
+
+Your signal function is called on every bar. Return `null` to skip, or a signal object to open a trade.
 
 ```js
-{
-  candles,      // history through the current bar
-  index,        // current index in the original candle array
-  bar,          // current candle
-  equity,       // realized equity
-  openPosition, // null or current position
-  pendingOrder  // null or current pending entry
+signal({ candles, index, bar, equity, openPosition, pendingOrder }) {
+  // return null to skip
+  // return a signal to enter
+  return {
+    side: "long",      // "long" | "short" | "buy" | "sell"
+    entry: bar.close,  // defaults to current close if omitted
+    stop: bar.close - 2,
+    rr: 2,             // target = entry + (entry - stop) * rr
+  };
 }
 ```
 
-Return `null` for no trade, or a signal object:
+The minimum viable signal is just `side`, `stop`, and `rr`. Start there and add fields only when the strategy actually needs them.
+
+### Key backtest options
+
+| Option | Purpose |
+|---|---|
+| `equity` | Starting equity (default `10000`) |
+| `riskPct` | Percent of equity risked per trade |
+| `warmupBars` | Bars skipped before signal evaluation starts |
+| `flattenAtClose` | Forces end-of-day exit when enabled |
+| `costs` | Slippage, spread, and commission model |
+| `strict` | Throws on lookahead access |
+| `collectEqSeries` | Enables equity curve output |
+| `collectReplay` | Enables visualization payload |
+
+### Result shape
 
 ```js
 {
-  side: "long" | "short",
-  entry: Number,
-  stop: Number,
-  takeProfit: Number
+  symbol, interval, range,
+  trades,     // every realized leg, including partial exits
+  positions,  // completed positions — start here for analysis
+  metrics,    // winRate, profitFactor, maxDrawdown, sharpe, ...
+  eqSeries,   // [{ time, timestamp, equity }] — equity curve
+  replay,     // visualization frames and events
 }
 ```
 
-Quality-of-life behavior:
+**First checks after any run:**
 
-- `side` also accepts `buy` and `sell`
-- `entry` can be omitted and will default to the current bar close
-- `takeProfit` can be omitted if `rr` or `_rr` is provided
-- `qty` or `size` can override risk-based sizing
-- `riskPct` or `riskFraction` can override the global risk setting per signal
-- `strict: true` throws if the strategy directly accesses candles beyond the current index
+- `metrics.trades` — enough sample size to trust the numbers?
+- `metrics.profitFactor` — do winners beat losers gross of costs?
+- `metrics.maxDrawdown` — is the equity path survivable?
+- `metrics.sideBreakdown` — does one side carry the whole result?
 
-Optional engine hints:
+---
 
-- `_entryExpiryBars`
-- `_cooldownBars`
-- `_breakevenAtR`
-- `_trailAfterR`
-- `_maxBarsInTrade`
-- `_maxHoldMin`
-- `_rr`
-- `_initRisk`
-- `_imb`
+## Portfolio mode
 
-## Result Shape
+Use `backtestPortfolio()` when you have one candle array per symbol and want a single combined result.
 
-`backtest()` returns:
+```js
+import { backtestPortfolio } from "tradelab";
+
+const result = backtestPortfolio({
+  equity: 100_000,
+  systems: [
+    { symbol: "SPY", candles: spy, signal: signalA, weight: 2 },
+    { symbol: "QQQ", candles: qqq, signal: signalB, weight: 1 },
+  ],
+});
+```
 
-- `trades`: every realized leg, including scale-outs
-- `positions`: completed positions only
-- `metrics`: aggregate stats including `winRate`, `expectancy`, `profitFactor`, `maxDrawdown`, `sharpe`, `avgHold`, and `sideBreakdown`
-- `eqSeries`: realized equity history as `{ time, timestamp, equity }`
-- `replay`: chart-friendly frame and event data
+Capital is allocated up front by weight. Each system runs through the normal single-symbol engine, and the portfolio result merges trades, positions, replay events, and the equity series.
 
-## Main Exports
+---
 
-- `backtest(options)`
-- `backtestPortfolio({ systems, equity })`
-- `walkForwardOptimize({ candles, signalFactory, parameterSets, trainBars, testBars })`
-- `backtestHistorical({ data, backtestOptions })`
-- `getHistoricalCandles(options)`
-- `fetchHistorical(symbol, interval, period)`
-- `loadCandlesFromCSV(filePath, options)`
-- `saveCandlesToCache(candles, meta)`
-- `loadCandlesFromCache(symbol, interval, period, outDir)`
-- `exportMetricsJSON({ result, outDir })`
-- `exportBacktestArtifacts({ result, outDir })`
+## Walk-forward optimization
 
-## Reports
+Use `walkForwardOptimize()` when one in-sample backtest is not enough. It runs rolling train/test windows across the full candle history.
 
-The HTML report is self-contained apart from the Plotly CDN script. Report markup, CSS, and client-side chart code live under `templates/`.
+```js
+import { walkForwardOptimize } from "tradelab";
 
-Export helpers default CSV output to completed positions. Use `csvSource: "trades"` if you want every realized leg in the CSV.
+const wf = walkForwardOptimize({
+  candles,
+  trainBars: 180,
+  testBars: 60,
+  stepBars: 60,
+  scoreBy: "profitFactor",
+  parameterSets: [
+    { fast: 8,  slow: 21, rr: 2 },
+    { fast: 10, slow: 30, rr: 2 },
+  ],
+  signalFactory(params) {
+    return createSignalFromParams(params);
+  },
+});
+```
 
-## Examples
+Each window picks the best parameter set in training, then runs it blind on the test slice. The `windows` array in the result shows per-window winners. If the winning parameters swing wildly from window to window, that is a real signal — not a formatting detail.
 
-```bash
-node examples/emaCross.js
-node examples/yahooEmaCross.js SPY 1d 1y
+---
+
+## Execution and cost modeling
+
+```js
+const result = backtest({
+  candles,
+  signal,
+  costs: {
+    slippageBps: 2,
+    spreadBps: 1,
+    slippageByKind: {
+      market: 3,
+      limit: 0.5,
+      stop: 4,
+    },
+    commissionBps: 1,
+    commissionPerUnit: 0,
+    commissionPerOrder: 1,
+    minCommission: 1,
+  },
+});
 ```
 
+- Slippage is applied in the trade direction
+- Spread is modeled as half-spread paid on entry and exit
+- Commission can be percentage-based, per-unit, per-order, or mixed
+- `minCommission` floors the fee per fill
+
+> Leaving costs at zero is the most common cause of inflated backtests. Set them from the start.
+
+---
+
+## Exports and reporting
+
+```js
+import { exportBacktestArtifacts } from "tradelab";
+
+// Writes HTML report + trade CSV + metrics JSON in one call
+exportBacktestArtifacts({ result, outDir: "./output" });
+```
+
+Or use the narrower helpers:
+
+| Helper | Output |
+|---|---|
+| `exportHtmlReport(options)` | Interactive HTML report written to disk |
+| `renderHtmlReport(options)` | HTML report returned as a string |
+| `exportTradesCsv(trades, options)` | Flat trade ledger for spreadsheets or pandas |
+| `exportMetricsJSON(options)` | Machine-readable metrics for dashboards or automation |
+
+For programmatic pipelines, `exportMetricsJSON` is usually the most useful format to build on.
+
+---
+
 ## CLI
 
+The package ships a `tradelab` binary. Best for quick iteration, smoke tests, and trying the package before wiring it into application code.
+
 ```bash
+# Backtest from Yahoo
 npx tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
+
+# Backtest from CSV with a built-in strategy
 npx tradelab backtest --source csv --csvPath ./data/btc.csv --strategy buy-hold --holdBars 3
-npx tradelab walk-forward --source yahoo --symbol QQQ --interval 1d --period 2y --trainBars 180 --testBars 60
+
+# Multi-symbol portfolio
+npx tradelab portfolio \
+  --csvPaths ./data/spy.csv,./data/qqq.csv \
+  --symbols SPY,QQQ \
+  --strategy buy-hold
+
+# Walk-forward validation
+npx tradelab walk-forward \
+  --source yahoo --symbol QQQ --interval 1d --period 2y \
+  --trainBars 180 --testBars 60
+
+# Prefetch and cache data
+npx tradelab prefetch --symbol SPY --interval 1d --period 1y
+npx tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
 ```
 
+**Built-in strategies:** `ema-cross` · `buy-hold`
+
+You can also point `--strategy` at a local module that exports `default(args)`, `createSignal(args)`, or `signal`.
+
+---
+
+## Examples
+
+```bash
+node examples/emaCross.js
+node examples/yahooEmaCross.js SPY 1d 1y
+```
+
+The examples are a good place to start if you want something runnable before wiring the package into your own strategy code.
+
+---
+
+## Importing
+
+### ESM
+
+```js
+import { backtest, getHistoricalCandles, ema } from "tradelab";
+import { fetchHistorical } from "tradelab/data";
+```
+
+### CommonJS
+
+```js
+const { backtest, getHistoricalCandles, ema } = require("tradelab");
+const { fetchHistorical } = require("tradelab/data");
+```
+
+---
+
+## Documentation
+
+| Guide | What it covers |
+|---|---|
+| [Backtest engine](docs/backtest-engine.md) | Signal contract, all options, result shape, portfolio mode, walk-forward |
+| [Data, reporting, and CLI](docs/data-reporting-cli.md) | Data loading, cache behavior, exports, CLI reference |
+| [API reference](docs/api-reference.md) | Compact index of every public export |
+
+---
+
+## Common mistakes
+
+- Using unsorted candles or mixed intervals in a single series
+- Reading `trades` as if they were always full positions — use `positions` for top-line analysis
+- Leaving costs at zero and overestimating edge
+- Trusting one backtest without out-of-sample validation
+- Debugging a strategy with `strict: false` when lookahead is possible
+
+---
+
 ## Notes
 
-- Yahoo downloads can be cached under `output/data` by default.
-- The engine is intended for historical research, not brokerage execution.
-- File output only happens through the reporting and cache helpers.
-- CommonJS and ESM are both supported.
+- Node `18+` is required
+- Yahoo downloads are cached under `output/data` by default
+- CommonJS and ESM are both supported
+- The engine is built for historical research — not brokerage execution, tick-level simulation, or exchange microstructure modeling

package/docs/README.md

@@ -0,0 +1,61 @@
+# tradelab docs
+
+## Guides
+
+- [Backtest engine](backtest-engine.md)
+- [Data, reporting, and CLI](data-reporting-cli.md)
+- [API reference](api-reference.md)
+
+## Choose a path
+
+| Goal | Start here |
+| --- | --- |
+| Run one strategy on one dataset | [Backtest engine](backtest-engine.md) |
+| Load Yahoo or CSV data | [Data, reporting, and CLI](data-reporting-cli.md) |
+| Export reports or machine-readable results | [Data, reporting, and CLI](data-reporting-cli.md) |
+| Run multiple symbols together | [Backtest engine](backtest-engine.md) |
+| Run walk-forward validation | [Backtest engine](backtest-engine.md) |
+| Check the exact public exports | [API reference](api-reference.md) |
+
+## Package scope
+
+tradelab is built for:
+
+- candle-based strategy research
+- historical backtests with configurable fills and costs
+- CSV and Yahoo-based data workflows
+- exportable outputs for review or automation
+
+tradelab is not built for:
+
+- live broker execution
+- tick-level simulation
+- exchange microstructure modeling
+
+## Common workflows
+
+### Single strategy workflow
+
+1. Load candles with `getHistoricalCandles()` or your own dataset
+2. Run `backtest()`
+3. Inspect `result.metrics` and `result.positions`
+4. Export HTML, CSV, or JSON if needed
+
+### Multi-symbol workflow
+
+1. Prepare one candle array per symbol
+2. Run `backtestPortfolio()`
+3. Review combined `metrics`, `positions`, and `eqSeries`
+
+### Validation workflow
+
+1. Build a `signalFactory(params)`
+2. Create parameter sets
+3. Run `walkForwardOptimize()`
+4. Review per-window winners before trusting the aggregate result
+
+## Documentation map
+
+- [Backtest engine](backtest-engine.md): strategy inputs, engine options, result shape, portfolio mode, walk-forward mode
+- [Data, reporting, and CLI](data-reporting-cli.md): data loading, cache behavior, exports, terminal usage
+- [API reference](api-reference.md): compact export index

package/docs/api-reference.md

@@ -0,0 +1,70 @@
+# API reference
+
+This page is the compact index of public exports.
+
+If you are learning the package, start with [backtest-engine.md](backtest-engine.md) or [data-reporting-cli.md](data-reporting-cli.md). This page is for quick lookup.
+
+## Backtesting
+
+| Export | Summary |
+| --- | --- |
+| `backtest(options)` | Run one strategy on one candle series |
+| `backtestPortfolio(options)` | Run multiple systems and merge the result |
+| `walkForwardOptimize(options)` | Run rolling train/test validation |
+| `buildMetrics(input)` | Compute metrics from realized trades and equity data |
+
+## Data
+
+| Export | Summary |
+| --- | --- |
+| `getHistoricalCandles(options)` | Load candles from Yahoo or CSV |
+| `backtestHistorical({ data, backtestOptions })` | Load candles and immediately run `backtest()` |
+| `fetchHistorical(symbol, interval, period, options)` | Call the Yahoo layer directly |
+| `fetchLatestCandle(symbol, interval, options)` | Fetch the latest Yahoo candle |
+| `loadCandlesFromCSV(filePath, options)` | Parse and normalize a CSV file |
+| `normalizeCandles(candles)` | Normalize candle field names and sort/dedupe |
+| `mergeCandles(...arrays)` | Merge multiple candle arrays |
+| `candleStats(candles)` | Return summary stats for a candle array |
+| `saveCandlesToCache(candles, meta)` | Write normalized candles to the local cache |
+| `loadCandlesFromCache(symbol, interval, period, outDir)` | Read normalized candles from the local cache |
+| `cachedCandlesPath(symbol, interval, period, outDir)` | Return the expected cache path |
+
+## Reporting
+
+| Export | Summary |
+| --- | --- |
+| `renderHtmlReport(options)` | Return the HTML report as a string |
+| `exportHtmlReport(options)` | Write the HTML report to disk |
+| `exportTradesCsv(trades, options)` | Write a CSV ledger of trades or positions |
+| `exportMetricsJSON(options)` | Write machine-readable metrics JSON |
+| `exportBacktestArtifacts(options)` | Write HTML, CSV, and metrics JSON together |
+
+## Indicators and utilities
+
+### Indicators
+
+- `ema(values, period)`
+- `atr(bars, period)`
+- `swingHigh(bars, index, left, right)`
+- `swingLow(bars, index, left, right)`
+- `detectFVG(bars, index)`
+- `lastSwing(bars, index, direction)`
+- `structureState(bars, index)`
+- `bpsOf(price, bps)`
+- `pct(a, b)`
+
+### Position sizing
+
+- `calculatePositionSize(input)`
+
+### Time helpers
+
+- `offsetET(timeMs)`
+- `minutesET(timeMs)`
+- `isSession(timeMs, session)`
+- `parseWindowsCSV(csv)`
+- `inWindowsET(timeMs, windows)`
+
+## Types
+
+The package ships declarations in [../types/index.d.ts](../types/index.d.ts). Use that file when you need the exact option and result contracts in TypeScript or editor IntelliSense.

package/docs/backtest-engine.md

@@ -0,0 +1,363 @@
+# Backtest engine
+
+This page covers the simulation layer:
+
+- `backtest(options)`
+- `backtestPortfolio(options)`
+- `walkForwardOptimize(options)`
+- `buildMetrics(input)`
+
+## Overview
+
+Use the engine layer when you already have candles and want to simulate strategy behavior, inspect the result, and export or post-process it.
+
+## Choose the right function
+
+| Use case | Function |
+| --- | --- |
+| One strategy on one candle series | `backtest()` |
+| Multiple symbols with one combined result | `backtestPortfolio()` |
+| Rolling train/test validation | `walkForwardOptimize()` |
+| Recompute metrics from realized trades | `buildMetrics()` |
+
+## Candle input
+
+Candles should be sorted in ascending time order.
+
+```js
+{
+  time: 1735828200000,
+  open: 100,
+  high: 102,
+  low: 99,
+  close: 101,
+  volume: 1000
+}
+```
+
+The package also normalizes common aliases such as `timestamp`, `date`, `o`, `h`, `l`, and `c`.
+
+## `backtest(options)`
+
+`backtest()` is the main single-symbol entry point.
+
+### Minimal example
+
+```js
+import { backtest } from "tradelab";
+
+const result = backtest({
+  candles,
+  signal({ bar, index }) {
+    if (index !== 20) return null;
+    return {
+      side: "long",
+      entry: bar.close,
+      stop: bar.close - 2,
+      rr: 2,
+    };
+  },
+});
+```
+
+### Required fields
+
+```js
+{
+  candles: Candle[],
+  signal: ({ candles, index, bar, equity, openPosition, pendingOrder }) => Signal | null
+}
+```
+
+### Core options
+
+| Option | Purpose |
+| --- | --- |
+| `symbol`, `interval`, `range` | Labels carried into results and exports |
+| `equity` | Starting equity, default `10000` |
+| `riskPct` or `riskFraction` | Default risk per trade when `qty` is not provided |
+| `warmupBars` | Bars skipped before signal evaluation starts |
+| `flattenAtClose` | Forces end-of-day exit when enabled |
+| `collectEqSeries`, `collectReplay` | Builds extra output for charts and exports |
+| `strict` | Throws on direct lookahead access such as `candles[index + 1]` |
+| `costs` | Slippage, spread, and commission model |
+
+If you are starting from scratch, the most useful options to set explicitly are:
+
+- `equity`
+- `riskPct`
+- `warmupBars`
+- `flattenAtClose`
+- `costs`
+
+### Signal contract
+
+The signal function receives:
+
+```js
+{
+  candles,
+  index,
+  bar,
+  equity,
+  openPosition,
+  pendingOrder
+}
+```
+
+Return `null` for no trade, or a signal object:
+
+```js
+{
+  side: "long" | "short",
+  entry: 101.25,
+  stop: 99.75,
+  takeProfit: 104.25
+}
+```
+
+### Signal conveniences
+
+| Field | Behavior |
+| --- | --- |
+| `side` | Accepts `long`, `short`, `buy`, or `sell` |
+| `entry` | Defaults to the current close if omitted |
+| `takeProfit` | Can be derived from `rr` or `_rr` |
+| `qty` or `size` | Overrides risk-based sizing |
+| `riskPct` or `riskFraction` | Overrides the global risk setting for that trade |
+
+Practical rule: return the smallest signal object that expresses the trade clearly. In many strategies that is just `side`, `stop`, and `rr`.
+
+### Optional per-trade hints
+
+These values are read from the signal object when present:
+
+- `_entryExpiryBars`
+- `_cooldownBars`
+- `_breakevenAtR`
+- `_trailAfterR`
+- `_maxBarsInTrade`
+- `_maxHoldMin`
+- `_rr`
+- `_initRisk`
+- `_imb`
+
+### Execution and cost model
+
+Legacy options still work:
+
+- `slippageBps`
+- `feeBps`
+
+For more control, use `costs`:
+
+```js
+{
+  costs: {
+    slippageBps: 2,
+    spreadBps: 1,
+    slippageByKind: {
+      market: 3,
+      limit: 0.5,
+      stop: 4,
+    },
+    commissionBps: 1,
+    commissionPerUnit: 0,
+    commissionPerOrder: 1,
+    minCommission: 1,
+  },
+}
+```
+
+### Cost model behavior
+
+- slippage is applied in trade direction
+- spread is modeled as half-spread paid on entry and exit
+- commission can be percentage-based, per-unit, per-order, or mixed
+- `minCommission` floors the fee for that fill
+
+This is still a bar-based simulation. It does not model queue position, exchange microstructure, or realistic intrabar order priority.
+
+### Advanced trade management
+
+These are optional. Ignore them until the strategy actually needs them.
+
+- `scaleOutAtR`, `scaleOutFrac`, `finalTP_R`
+- `maxDailyLossPct`, `dailyMaxTrades`, `postLossCooldownBars`
+- `atrTrailMult`, `atrTrailPeriod`
+- `mfeTrail`
+- `pyramiding`
+- `volScale`
+- `entryChase`
+- `qtyStep`, `minQty`, `maxLeverage`
+- `reanchorStopOnFill`, `maxSlipROnFill`
+- `oco`
+- `triggerMode`
+
+Recommended order of adoption:
+
+1. Start with `entry`, `stop`, and `rr`
+2. Add `costs`
+3. Add trailing, scale-outs, or pyramiding only if the real strategy uses them
+
+## Result shape
+
+`backtest()` returns:
+
+```js
+{
+  symbol,
+  interval,
+  range,
+  trades,
+  positions,
+  metrics,
+  eqSeries,
+  replay
+}
+```
+
+### `trades`
+
+Every realized leg, including partial exits and scale-outs.
+
+### `positions`
+
+Completed positions only. This is the collection most users want for top-line analysis.
+
+If you are unsure whether to use `trades` or `positions`, start with `positions`.
+
+### `metrics`
+
+Most users start with:
+
+- `trades`
+- `winRate`
+- `expectancy`
+- `profitFactor`
+- `maxDrawdown`
+- `sharpe`
+- `avgHold`
+- `returnPct`
+- `totalPnL`
+- `finalEquity`
+- `sideBreakdown`
+
+Also included:
+
+- position-vs-leg variants such as `profitFactor_pos` and `profitFactor_leg`
+- `rDist` percentiles
+- `holdDistMin` percentiles
+- daily stats under `daily`
+
+Useful first checks after any run:
+
+- `metrics.trades`: enough sample size to care
+- `metrics.profitFactor`: whether winners beat losers gross of the chosen fill model
+- `metrics.maxDrawdown`: whether the path is survivable
+- `metrics.sideBreakdown`: whether one side carries the result
+
+### `eqSeries`
+
+Realized equity points:
+
+```js
+[
+  { time, timestamp, equity }
+]
+```
+
+`time` and `timestamp` contain the same Unix-millisecond value.
+
+### `replay`
+
+Visualization payload:
+
+```js
+{
+  frames: [{ t, price, equity, posSide, posSize }],
+  events: [{ t, price, type, side, size, tradeId, reason, pnl }]
+}
+```
+
+This is meant for charts and reports, not as a full audit log.
+
+## `backtestPortfolio(options)`
+
+Use portfolio mode when you already have one candle array per symbol and want one combined result.
+
+```js
+const result = backtestPortfolio({
+  equity: 100_000,
+  systems: [
+    { symbol: "SPY", candles: spy, signal: signalA, weight: 2 },
+    { symbol: "QQQ", candles: qqq, signal: signalB, weight: 1 },
+  ],
+});
+```
+
+### How it works
+
+- capital is allocated up front by weight
+- each system runs through the normal single-symbol engine
+- the portfolio result merges trades, positions, replay events, and equity series
+
+### What it is not
+
+- a cross-margin broker simulator
+- a portfolio-level fill arbiter
+- a shared capital-locking engine
+
+If you need shared real-time portfolio constraints, this is not that tool yet.
+
+## `walkForwardOptimize(options)`
+
+Use walk-forward mode when one in-sample backtest is not enough and you want rolling train/test validation.
+
+```js
+const wf = walkForwardOptimize({
+  candles,
+  trainBars: 180,
+  testBars: 60,
+  stepBars: 60,
+  scoreBy: "profitFactor",
+  parameterSets: [
+    { fast: 8, slow: 21, rr: 2 },
+    { fast: 10, slow: 30, rr: 2 },
+  ],
+  signalFactory(params) {
+    return createSignalFromParams(params);
+  },
+});
+```
+
+### How it works
+
+1. Evaluate every parameter set on the training slice
+2. Pick the best one by `scoreBy`
+3. Run that parameter set on the next test slice
+4. Repeat for each window
+
+### Return value
+
+- `windows`: per-window summaries and chosen parameters
+- `trades`, `positions`, `metrics`, `eqSeries`
+- `bestParams`: chosen parameters for each window
+
+In practice, the per-window output matters more than the aggregate headline. If the winning parameters swing wildly from one window to the next, treat that as a real signal.
+
+## `buildMetrics(input)`
+
+Most users do not need this directly. Use it when:
+
+- you generate realized trades outside `backtest()`
+- you filter a result and want fresh metrics
+- you combine results manually
+
+## Common mistakes
+
+- using unsorted candles or mixed intervals in one series
+- reading `trades` as if they were always full positions
+- leaving costs at zero and overestimating edge
+- trusting one backtest without out-of-sample validation
+- debugging a strategy with `strict: false` when lookahead is possible

package/docs/data-reporting-cli.md

@@ -0,0 +1,254 @@
+# Data, reporting, and CLI
+
+This page covers the parts of the package around the core engine:
+
+- historical data loading
+- local cache helpers
+- export helpers
+- command-line usage
+
+## Overview
+
+If you are not bringing your own candles yet, start here.
+
+## Choose the right entry point
+
+| Use case | Function |
+| --- | --- |
+| Load data without caring about the source-specific helper | `getHistoricalCandles()` |
+| Fetch directly from Yahoo | `fetchHistorical()` |
+| Load a local CSV file | `loadCandlesFromCSV()` |
+| Reuse saved normalized data | `loadCandlesFromCache()` |
+| Try the package from a terminal first | `tradelab` CLI |
+
+## Historical data
+
+### `getHistoricalCandles(options)`
+
+This is the main data-loading entry point.
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+```
+
+### Sources
+
+- `yahoo`
+- `csv`
+- `auto`
+
+`auto` switches to CSV when `csvPath` or `csv.filePath` is present. Otherwise it uses Yahoo.
+
+If you are writing application code, prefer `getHistoricalCandles()` over calling source-specific helpers directly.
+
+### Yahoo options
+
+| Option | Purpose |
+| --- | --- |
+| `symbol` | Ticker or Yahoo symbol |
+| `interval` | Candle interval such as `1d` or `5m` |
+| `period` | Lookback period such as `6mo` or `1y` |
+| `includePrePost` | Includes premarket and postmarket data when supported |
+| `cache` | Reuses saved normalized data |
+| `refresh` | Forces a fresh download even if cache exists |
+| `cacheDir` | Overrides the default cache directory |
+
+The Yahoo layer retries transient failures with exponential backoff. If the endpoint still fails, the error message points users toward CSV or cached data.
+
+Use caching for repeatable research runs. It reduces network noise and makes failures easier to diagnose.
+
+### CSV options
+
+```js
+const candles = await getHistoricalCandles({
+  source: "csv",
+  csvPath: "./data/spy.csv",
+  csv: {
+    timeCol: "timestamp",
+    openCol: "open",
+    highCol: "high",
+    lowCol: "low",
+    closeCol: "close",
+    volumeCol: "volume",
+  },
+});
+```
+
+CSV parsing can be configured with:
+
+- delimiter
+- header presence
+- column names or indexes
+- start/end date filters
+- custom date parsing
+
+If your CSV already uses common OHLCV column names, you often do not need to pass any mapping at all.
+
+## Cache helpers
+
+Available helpers:
+
+- `saveCandlesToCache(candles, meta)`
+- `loadCandlesFromCache(symbol, interval, period, outDir)`
+- `cachedCandlesPath(symbol, interval, period, outDir)`
+
+The cache is just normalized candle JSON on disk. It is meant for research convenience, not as a durable database layer.
+
+## Common workflows
+
+### Yahoo to backtest
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+});
+```
+
+### CSV to backtest
+
+```js
+const candles = await getHistoricalCandles({
+  source: "csv",
+  csvPath: "./data/spy.csv",
+});
+```
+
+### Cached repeat run
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+  refresh: false,
+});
+```
+
+## Reporting and exports
+
+### `exportBacktestArtifacts({ result, outDir })`
+
+The main bundle export. By default it writes:
+
+- HTML report
+- trade CSV
+- metrics JSON
+
+Return value:
+
+```js
+{
+  csv,
+  html,
+  metrics
+}
+```
+
+If you only need one output type, call the narrower helper directly.
+
+### `exportMetricsJSON({ result, outDir })`
+
+Use this for dashboards, notebooks, or any machine-readable downstream pipeline.
+
+For automation, this is usually the best export format to build on.
+
+### `exportTradesCsv(trades, options)`
+
+Use this when you want a flat trade ledger for spreadsheets or pandas-style workflows.
+
+### `renderHtmlReport(options)` and `exportHtmlReport(options)`
+
+- `renderHtmlReport()` returns an HTML string
+- `exportHtmlReport()` writes the file and returns its path
+
+The report system uses the assets under `templates/`. The renderer injects the payload and keeps markup, CSS, and client script separate from the JS entrypoint.
+
+## CLI
+
+The package ships with a `tradelab` binary.
+
+The CLI is best for quick iteration, smoke tests, and trying the package before building a JS workflow around it.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `tradelab backtest` | Run a single backtest from Yahoo or CSV |
+| `tradelab portfolio` | Run a simple multi-file portfolio backtest |
+| `tradelab walk-forward` | Run rolling validation with the built-in search |
+| `tradelab prefetch` | Download and cache Yahoo data |
+| `tradelab import-csv` | Normalize and cache a CSV file |
+
+### Backtest
+
+```bash
+tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
+tradelab backtest --source csv --csvPath ./data/btc.csv --strategy buy-hold --holdBars 3
+```
+
+Built-in strategies:
+
+- `ema-cross`
+- `buy-hold`
+
+You can also point `--strategy` at a local module. The module should export one of:
+
+- `default(args)`
+- `createSignal(args)`
+- `signal`
+
+That makes it easy to prototype a strategy file before wiring it into a larger application.
+
+### Portfolio
+
+```bash
+tradelab portfolio \
+  --csvPaths ./data/spy.csv,./data/qqq.csv \
+  --symbols SPY,QQQ \
+  --strategy buy-hold
+```
+
+This command is intentionally simple. Use it for quick combined runs, not for custom portfolio logic.
+
+### Walk-forward
+
+```bash
+tradelab walk-forward \
+  --source yahoo \
+  --symbol QQQ \
+  --interval 1d \
+  --period 2y \
+  --trainBars 180 \
+  --testBars 60
+```
+
+The CLI walk-forward command currently uses the built-in `ema-cross` parameter search.
+
+### Cache utilities
+
+```bash
+tradelab prefetch --symbol SPY --interval 1d --period 1y
+tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
+```
+
+## Troubleshooting
+
+| Problem | Check first |
+| --- | --- |
+| Yahoo request errors | enable cache, retry later, or fall back to CSV |
+| Unexpected trade count | `warmupBars`, `flattenAtClose`, and signal frequency |
+| Empty result | candle order, signal logic, and stop/target validity |
+| Confusing CSV import | inspect normalized bars from `loadCandlesFromCSV()` before backtesting |
+| Export confusion | use metrics JSON first if you need programmatic output |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -37,6 +37,7 @@
   },
   "files": [
     "bin",
+    "docs",
     "dist",
     "src",
     "types",