Complete Backtest task routes and verified book guide

docs/book-guide/index.md

@@ -7,19 +7,29 @@ backtest operations. For the library task guide, start at the
 bundled synthetic data, so the book and its datasets are optional. All book
 links below point to one checked companion revision.
 
+Each notebook description distinguishes direct library examples from
+research that supplies inputs or interprets outputs. A case study that uses a
+book-specific helper is labeled as such; its helper and datasets are not part
+of the installed `ml4t-backtest` package. Start with the linked library workflow
+for a standalone example.
+
 ## Chapters and workflows
 
-| Book section and notebook | What it adds | Library workflow |
+| Book section and notebook | Role and learning task | Library workflow |
 |---|---|---|
-| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) | Run one strategy, reconcile fills and trades | [First backtest](../getting-started/quickstart.md) |
-| [16.3 Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/05_stateful_strategies.ipynb) | Carry realized state into later decisions | [Risk and state](../tutorials/risk-and-state.md) |
-| [16.5 Understanding performance metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/09_performance_reporting.ipynb) | Read returns and drawdowns | [Result exports](../tutorials/results-and-analysis.md) |
-| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) | Change one execution assumption at a time | [Profiles and parity](../tutorials/profiles-and-parity.md) |
-| [17.4 Defining Baseline Allocators](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/07_conformal_position_sizing.ipynb) | Turn uncertainty into position sizes | [Accounts and constraints](../tutorials/accounts-and-constraints.md) |
-| [17.7 Comparing Allocator Performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/08_library_comparison.ipynb) | Compare allocators with matched inputs | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
-| [18.7 Transaction Cost Analysis and Model Validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/10_gross_vs_net_performance.ipynb) | Reconcile gross and net performance | [Costs and funding](../tutorials/costs-and-funding.md) |
-| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/02_exit_strategies.ipynb) | Compare fixed and trailing exits | [Risk and state](../tutorials/risk-and-state.md) |
-| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) | Use library position rules and portfolio limits | [Risk management](../user-guide/risk-management.md) |
+| [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) | Calls `DataFeed` and `Engine`. Prepare futures bars and contract specifications. | [Example data](../tutorials/data.md) |
+| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) | Calls `DataFeed` and `Engine`. Run one strategy, reconcile fills and trades. | [First backtest](../getting-started/quickstart.md) |
+| [16.3 Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/05_stateful_strategies.ipynb) | Calls `DataFeed` and `Engine`. Carry realized state into later decisions. | [Risk and state](../tutorials/risk-and-state.md) |
+| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) | Calls `Engine` with controlled settings. Change one execution assumption at a time. | [Profiles and parity](../tutorials/profiles-and-parity.md); [Zipline migration](../user-guide/migrate-from-zipline.md) |
+| [16.5 Understanding performance metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/09_performance_reporting.ipynb) | Calls `Engine` and `ml4t-diagnostic`. Read returns and drawdowns. | [Result exports](../tutorials/results-and-analysis.md) |
+| [Case-study LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/16_case_study_lean_parity.ipynb) | Reads retained comparison evidence. Interpret the bounded framework audit. | [Profiles and parity](../tutorials/profiles-and-parity.md) |
+| [Portfolio performance analysis](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/01_portfolio_metrics.ipynb) | Calls `ml4t-diagnostic` for downstream analysis. Analyze returns and drawdowns. | [Diagnostic handoff](../tutorials/diagnostic-handoff.md) |
+| [17.4 Defining Baseline Allocators](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb) | Teaches sizing from prediction uncertainty. Turn uncertainty into position sizes. | [Accounts and constraints](../tutorials/accounts-and-constraints.md) |
+| [17.7 Comparing Allocator Performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb) | Calls `Engine` for allocator comparison. Compare allocators with matched inputs. | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
+| [Market impact scenarios](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/03_market_impact_calibration.ipynb) | Teaches calibration from market panels. Assess size and capacity assumptions. | [Market impact](../user-guide/market-impact.md) |
+| [18.7 Transaction Cost Analysis and Model Validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb) | Teaches cost analysis from return series. Reconcile gross and net performance. | [Costs and funding](../tutorials/costs-and-funding.md) |
+| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/02_exit_strategies.ipynb) | Uses library risk and trade types in a research comparison. Compare fixed and trailing exits. | [Risk and state](../tutorials/risk-and-state.md) |
+| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) | Calls `ml4t.backtest.risk` directly. Use library position rules and portfolio limits. | [Risk management](../user-guide/risk-management.md) |
 
 The book develops research questions, statistical interpretation, and
 larger datasets. The library pages specify feed contracts, order timing,
@@ -28,13 +38,13 @@ reference when a notebook and the current API differ.
 
 ## Case studies
 
-| Companion example | What it adds | Library workflow |
+| Companion example | Role and learning task | Library workflow |
 |---|---|---|
-| [ETF backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/etfs/14_backtest.ipynb) | Weight targets from a prediction stream | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
-| [CME futures backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/cme_futures/13_backtest.ipynb) | Contract multipliers and futures sessions | [Example data](../tutorials/data.md) |
-| [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb) | USD-quoted pairs and signal alignment | [Data Feed](../user-guide/data-feed.md) |
-| [Crypto perpetual funding](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/crypto_perps_funding/16_costs.ipynb) | Funding and transaction-cost assumptions | [Costs and funding](../tutorials/costs-and-funding.md) |
-| [ETF risk controls](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/etfs/16_risk_management.ipynb) | Position exits in a full strategy | [Risk management](../tutorials/risk-and-state.md) |
+| [ETF backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/etfs/14_backtest.ipynb) | Calls the book helper `backtest_runner`, which uses `Engine`. Weight targets from a prediction stream. | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
+| [CME futures backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/cme_futures/13_backtest.ipynb) | Uses a book research workflow. Futures prediction selection and equal-weight baseline. | [Example data](../tutorials/data.md) |
+| [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb) | Uses a book research workflow. FX prediction population and strategy grid. | [Data Feed](../user-guide/data-feed.md) |
+| [Crypto perpetual funding](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/crypto_perps_funding/16_costs.ipynb) | Uses a book research workflow. Funding and transaction-cost assumptions. | [Costs and funding](../tutorials/costs-and-funding.md) |
+| [ETF risk controls](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/etfs/16_risk_management.ipynb) | Calls the book helper `backtest_runner`, which uses `Engine`. Position exits in a full strategy. | [Risk management](../tutorials/risk-and-state.md) |
 
 ## Move from a notebook to a reusable run
 

docs/getting-started/quickstart.md

@@ -81,7 +81,7 @@ choice and timing change fills.
 
 ## In the book
 
-Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/README.md),
-and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
+Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/README.md),
+and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
 extend this first round trip to a stateful RSI rule, explicit costs, and a matched
 comparison with a vectorized backtest.

docs/index.md

@@ -10,7 +10,7 @@ how cash is reserved, and how results change when you match another framework's
 
 -   :material-play-circle:{ .lg .middle } __Run Your First Backtest__
     ---
-    Define a strategy, pick a config profile, get results in 10 lines.
+    Run a complete strategy on bundled synthetic bars and inspect its fills.
     [:octicons-arrow-right-24: Quickstart](getting-started/quickstart.md)
 
 -   :material-tune:{ .lg .middle } __User Guide__
@@ -76,6 +76,9 @@ fills=2 final=$100300.00
 
 Each `Engine` instance is single-use. Create a new instance for every independent run.
 
+Moving a Zipline strategy? Follow the [task-level migration map](user-guide/migrate-from-zipline.md)
+and run its checked target-weight example before comparing framework results.
+
 The convenience function accepts the same price panel and strategy directly:
 
 <!-- ml4t-doc-test: home-convenience -->
@@ -108,8 +111,8 @@ exercise high event counts.
 
 | Feature | Description |
 |---------|-------------|
-| Event-driven | Point-in-time correctness, no look-ahead bias |
-| 40+ behavioral knobs | Every execution detail is configurable |
+| Event-driven | Explicit decision and fill timing; same-bar settings require a causal-data check |
+| Configurable behavior | Set fill timing, cash, costs, and order processing explicitly |
 | Quote-aware execution | Side-aware fills and separate mark pricing |
 | 10 framework profiles | Configure VectorBT, Backtrader, Zipline, and LEAN semantics |
 | Risk management | Stop-loss, take-profit, trailing stops, portfolio limits |

docs/tutorials/accounts-and-constraints.md

@@ -141,9 +141,9 @@ instead of inferring acceptance from requested weights.
 
 ## In the book
 
-Chapter 17, Section 17.1, [Defining the allocation problem](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/README.md),
+Chapter 17, Section 17.1, [Defining the allocation problem](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/README.md),
 sets out the role of constraints and leverage. [Notebook 07, Conformal position
-sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/07_conformal_position_sizing.ipynb)
+sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb)
 uses registered ETF and futures predictions to study a larger sizing problem.
 The controlled runs here make the account and execution layer inspectable
 before applying a book allocator.

docs/tutorials/costs-and-funding.md

@@ -188,8 +188,8 @@ total commission: $10.00
 
 ## In the book
 
-Chapter 18, Section 18.7, [Transaction cost analysis and model validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/README.md),
-and [notebook 10, Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/10_gross_vs_net_performance.ipynb)
+Chapter 18, Section 18.7, [Transaction cost analysis and model validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/README.md),
+and [notebook 10, Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb)
 extend the cost decomposition to larger strategy runs. The [crypto-perpetual
-cost notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/crypto_perps_funding/16_costs.ipynb)
+cost notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/crypto_perps_funding/16_costs.ipynb)
 adds case-study funding and fee assumptions.

docs/tutorials/data.md

@@ -173,4 +173,4 @@ sources for the synthetic panels.
 
 ## In the book
 
-Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/02_futures_backtesting.ipynb) extends the small synthetic futures panel to a longer contract history. [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb) shows how a research prediction stream becomes aligned feed input.
+Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) extends the small synthetic futures panel to a longer contract history. [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb) shows how a research prediction stream becomes aligned feed input.

docs/tutorials/diagnostic-handoff.md

@@ -48,4 +48,4 @@ reference for trade, fill, and portfolio-state handoffs.
 
 ## In the book
 
-Chapter 17, Section 17.3, [Portfolio metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/01_portfolio_metrics.ipynb) applies `ml4t-diagnostic` to a larger ETF allocation. The small example above tests the bridge before adding benchmark and rolling analyses.
+Chapter 17, Section 17.3, [Portfolio metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/01_portfolio_metrics.ipynb) applies `ml4t-diagnostic` to a larger ETF allocation. The small example above tests the bridge before adding benchmark and rolling analyses.

docs/tutorials/multiasset-rebalancing.md

@@ -228,8 +228,8 @@ guide covers cash and margin settings used by these variants.
 
 ## In the book
 
-Chapter 17, Section 17.7, [Comparing allocator performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/README.md),
-and [notebook 08, Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/08_library_comparison.ipynb)
-compare portfolio construction workflows. [Chapter 16's futures notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/02_futures_backtesting.ipynb)
-adds contract and overnight-session assumptions; the [FX case-study backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb)
+Chapter 17, Section 17.7, [Comparing allocator performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/README.md),
+and [notebook 08, Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb)
+compare portfolio construction workflows. [Chapter 16's futures notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb)
+adds contract and overnight-session assumptions; the [FX case-study backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb)
 applies targets to a larger prediction stream.