thetabook 2.2.3__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. {thetabook-2.2.3 → thetabook-2.3.0}/CHANGELOG.md +390 -0
  2. {thetabook-2.2.3 → thetabook-2.3.0}/CLAUDE.md +7 -3
  3. {thetabook-2.2.3 → thetabook-2.3.0}/CONTRIBUTING.md +7 -6
  4. {thetabook-2.2.3 → thetabook-2.3.0}/PKG-INFO +2 -2
  5. {thetabook-2.2.3 → thetabook-2.3.0}/README.md +39 -3
  6. {thetabook-2.2.3 → thetabook-2.3.0}/ROADMAP.md +13 -2
  7. {thetabook-2.2.3 → thetabook-2.3.0}/pyproject.toml +10 -3
  8. thetabook-2.3.0/scripts/demo.sh +488 -0
  9. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/CLAUDE.md +14 -5
  10. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/vrp.py +44 -9
  11. thetabook-2.3.0/src/thetabook/backtest/__init__.py +17 -0
  12. thetabook-2.3.0/src/thetabook/backtest/data.py +418 -0
  13. thetabook-2.3.0/src/thetabook/backtest/engine.py +123 -0
  14. thetabook-2.3.0/src/thetabook/backtest/grid.py +531 -0
  15. thetabook-2.3.0/src/thetabook/backtest/manifest.py +302 -0
  16. thetabook-2.3.0/src/thetabook/backtest/metrics.py +240 -0
  17. thetabook-2.3.0/src/thetabook/backtest/report.py +732 -0
  18. thetabook-2.3.0/src/thetabook/backtest/signals.py +112 -0
  19. thetabook-2.3.0/src/thetabook/backtest/strategies/__init__.py +122 -0
  20. thetabook-2.3.0/src/thetabook/backtest/strategies/dual_momentum.py +115 -0
  21. thetabook-2.3.0/src/thetabook/backtest/strategies/sector_rotation.py +173 -0
  22. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/__init__.py +3 -0
  23. thetabook-2.3.0/src/thetabook/cli/backtest.py +334 -0
  24. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/chain.py +5 -2
  25. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/em.py +11 -0
  26. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/evaluate.py +8 -0
  27. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/hv.py +10 -0
  28. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/vrp.py +51 -3
  29. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/adjust.py +371 -56
  30. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/core.py +237 -13
  31. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/evaluate_idea.py +445 -79
  32. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/manage_ideas.py +7 -0
  33. thetabook-2.3.0/src/thetabook/leg_parse.py +368 -0
  34. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/_schwab.py +29 -0
  35. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/bars.py +127 -77
  36. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/chains.py +75 -8
  37. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/dividends.py +2 -2
  38. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/prices.py +2 -2
  39. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/vol_lookup.py +117 -0
  40. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/models.py +74 -8
  41. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/accounts.py +220 -19
  42. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/empower.py +4 -0
  43. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/fidelity.py +36 -9
  44. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/schwab.py +6 -0
  45. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/options_book.py +156 -17
  46. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/greeks.py +23 -3
  47. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/policy.py +7 -0
  48. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/idea.md +10 -2
  49. thetabook-2.3.0/src/thetabook/tickers.py +429 -0
  50. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/render.py +15 -1
  51. {thetabook-2.2.3 → thetabook-2.3.0}/uv.lock +123 -148
  52. thetabook-2.2.3/src/thetabook/leg_parse.py +0 -201
  53. thetabook-2.2.3/src/thetabook/tickers.py +0 -218
  54. {thetabook-2.2.3 → thetabook-2.3.0}/.env.example +0 -0
  55. {thetabook-2.2.3 → thetabook-2.3.0}/.git-blame-ignore-revs +0 -0
  56. {thetabook-2.2.3 → thetabook-2.3.0}/.github/workflows/ci.yml +0 -0
  57. {thetabook-2.2.3 → thetabook-2.3.0}/.github/workflows/publish.yml +0 -0
  58. {thetabook-2.2.3 → thetabook-2.3.0}/.gitignore +0 -0
  59. {thetabook-2.2.3 → thetabook-2.3.0}/.python-version +0 -0
  60. {thetabook-2.2.3 → thetabook-2.3.0}/AGENTS.md +0 -0
  61. {thetabook-2.2.3 → thetabook-2.3.0}/LICENSE +0 -0
  62. {thetabook-2.2.3 → thetabook-2.3.0}/SECURITY.md +0 -0
  63. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/__init__.py +0 -0
  64. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/__init__.py +0 -0
  65. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/em.py +0 -0
  66. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/hv.py +0 -0
  67. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/scenarios.py +0 -0
  68. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/ta.py +0 -0
  69. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cache.py +0 -0
  70. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/CLAUDE.md +0 -0
  71. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/_shared.py +0 -0
  72. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/accounts.py +0 -0
  73. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/adjust.py +0 -0
  74. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/bars.py +0 -0
  75. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/bs.py +0 -0
  76. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/diff.py +0 -0
  77. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/dividends.py +0 -0
  78. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/earnings.py +0 -0
  79. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/greeks.py +0 -0
  80. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/ideas.py +0 -0
  81. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/import_csv.py +0 -0
  82. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/init.py +0 -0
  83. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/leg_mark.py +0 -0
  84. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/migrate_home.py +0 -0
  85. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/positions.py +0 -0
  86. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/price.py +0 -0
  87. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/refresh.py +0 -0
  88. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/roll.py +0 -0
  89. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/scenarios.py +0 -0
  90. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/skills.py +0 -0
  91. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/snapshot.py +0 -0
  92. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/ta.py +0 -0
  93. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/tickers.py +0 -0
  94. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/wiki.py +0 -0
  95. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/config.py +0 -0
  96. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/__init__.py +0 -0
  97. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/roll_scenarios.py +0 -0
  98. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/log.py +0 -0
  99. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/__init__.py +0 -0
  100. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/earnings.py +0 -0
  101. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/leg_marks.py +0 -0
  102. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/paths.py +0 -0
  103. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/__init__.py +0 -0
  104. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/__init__.py +0 -0
  105. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/_base.py +0 -0
  106. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/diff_snapshots.py +0 -0
  107. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/get_positions.py +0 -0
  108. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/import_csv_snapshot.py +0 -0
  109. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/scaffold.py +0 -0
  110. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/preflight.py +0 -0
  111. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/__init__.py +0 -0
  112. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/bs.py +0 -0
  113. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/__init__.py +0 -0
  114. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/install.py +0 -0
  115. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/lint.py +0 -0
  116. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/models.py +0 -0
  117. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/parse.py +0 -0
  118. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/registry.py +0 -0
  119. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/render.py +0 -0
  120. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/README.md +0 -0
  121. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/accounts.toml.example +0 -0
  122. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/config.toml.example +0 -0
  123. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/journal.md +0 -0
  124. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/learnings.md +0 -0
  125. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/skill.md +0 -0
  126. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
  127. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/index.md +0 -0
  128. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/log.md +0 -0
  129. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/overview.md +0 -0
  130. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/strategy.md +0 -0
  131. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/underlying.md +0 -0
  132. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/__init__.py +0 -0
  133. {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/lint.py +0 -0
@@ -5,6 +5,396 @@ All notable changes to this project are recorded here. Format loosely follows
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [2.3.0] — 2026-11-01
9
+
10
+ The first release since v2.2.3. It adds a backtester for systematic
11
+ strategies whose live signal is the backtest's own last row,
12
+ share legs in idea files, and a run of risk-correctness fixes that change
13
+ the numbers `evaluate` records.
14
+
15
+ **Expect existing ideas to move on their next `evaluate`.** PoP now
16
+ integrates a ±5σ grid instead of the ±2σ display domain
17
+ ([#96](https://github.com/subsriram/thetabook/issues/96)); max gain / loss
18
+ are computed in closed form and can read `Unbounded`
19
+ ([#99](https://github.com/subsriram/thetabook/issues/99)), with a one-time,
20
+ announced migration of budgets the old math got wrong; and a covered
21
+ structure keeps evaluating as naked until its shares are declared in
22
+ `## Structure` ([#102](https://github.com/subsriram/thetabook/issues/102)).
23
+ **Re-import Schwab or Empower CSV snapshots that hold options**: their
24
+ `averagePrice` was stored per contract, 100× too large
25
+ ([#109](https://github.com/subsriram/thetabook/pull/109)).
26
+
27
+ ### Added
28
+
29
+ - **`thetabook backtest`: hypothetical strategy backtests, with the live
30
+ signal on the same code path**
31
+ ([#108](https://github.com/subsriram/thetabook/issues/108);
32
+ [#110](https://github.com/subsriram/thetabook/pull/110),
33
+ [#114](https://github.com/subsriram/thetabook/pull/114),
34
+ [#115](https://github.com/subsriram/thetabook/pull/115)). A new
35
+ workflow-layer `backtest/` package and a `backtest list | run | grid |
36
+ signal` sub-app, driven by `/backtest`. `run` builds a total-return panel
37
+ from the bars stitch plus cash dividends and enforces signal-at-close →
38
+ trade at close t+lag → earn from t+lag+1, with non-zero costs and short
39
+ borrow by default. It reports against the strategy's benchmark, the
40
+ equal-weight universe and cash, with t-stats on every active return.
41
+ `signal` is the last completed rebalance of that same simulation, not a
42
+ second implementation, so the weekly call can't drift from the backtest
43
+ that justified it. Two strategies ship: `sector-rotation` (11 SPDR sectors,
44
+ weekly) and `dual-momentum` (SPY / TLT / GLD vs BIL, monthly).
45
+
46
+ `grid` sweeps `--vary` over one data panel, prints how many configurations
47
+ were tried, ranks on in-sample Sharpe only, and reports the **deflated
48
+ Sharpe** (Bailey & López de Prado 2014) of the winner. The paper's §6
49
+ worked example is a known-answer test. `--prior-trials` counts searches
50
+ done elsewhere, and `--walk-forward` re-picks the best config per fold and
51
+ chains the tests into one out-of-sample series.
52
+
53
+ `--save` on `run` / `grid` writes an immutable manifest to
54
+ `$THETABOOK_HOME/backtests/`: the JSON payload plus the code version, git
55
+ SHA, argv, params, a panel fingerprint and a UTC timestamp. The file is
56
+ create-only and chmod 0444, an identical re-run is reported rather than
57
+ duplicated, and stdout is byte-identical with or without the flag. This is
58
+ the package's third write boundary, and `personal/backtests` is now a
59
+ reserved skill write path. Everything prints as *hypothetical backtested
60
+ performance*. Conventions are in
61
+ [docs/behaviors.md](docs/behaviors.md) "Backtests".
62
+
63
+ - **Share legs in idea files**
64
+ ([#102](https://github.com/subsriram/thetabook/issues/102),
65
+ [#103](https://github.com/subsriram/thetabook/pull/103)). `## Structure`
66
+ now takes `TICKER shares qty=+100 cost_basis=150.00` beside option lines.
67
+ Shares were previously dropped on both the read and the `adjust --save`
68
+ write side, so every covered call, buy-write or collar evaluated as naked:
69
+ after #99 that meant a confident `Unbounded` on a position bounded at
70
+ −$14,772, printed beside a net delta of the wrong sign. `cost_basis` is
71
+ required, and a share line without it is refused rather than skipped,
72
+ since a zero default reports a profit as the max loss. `evaluate` gives
73
+ share legs their own Greeks and marks rows. `adjust` carries snapshot
74
+ shares through before and after, so `adjust --assign --save` writes a file
75
+ that evaluates as the covered position it modelled. A structure carrying
76
+ shares must sit on a single underlying. `accounts.check_idea` drops its
77
+ snapshot-derived cover guard and sizes off `evaluated_max_loss` alone.
78
+ Its unbounded-loss message names the share-line syntax.
79
+
80
+ - **`scripts/demo.sh`, a guided walkthrough**
81
+ ([#109](https://github.com/subsriram/thetabook/pull/109)). It runs the
82
+ main loop (snapshot, diff, positions, Greeks, account rules,
83
+ vol/TA/scenarios, chain, ideas, evaluate, adjust/roll, wiki) against a
84
+ throwaway `$THETABOOK_HOME` seeded with a fictional book, so no real
85
+ account data appears on screen. Market data is live, borrowed from your
86
+ `.env` and Schwab token. It refuses to run against, inside, or around
87
+ your real home. Supports `--auto`, `--from N`, `--verbose` and `--reset`.
88
+ Dev checkout only, since `scripts/` isn't in the wheel.
89
+
90
+ - **Index options now work: `VIX`, `SPX`, `NDX` and 22 more CBOE roots**
91
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's canonical
92
+ form for an index carries a `$` prefix. Bare `VIX` failed on the chains
93
+ endpoint with HTTP 400, and — worse — on the *quotes* endpoint with HTTP
94
+ **200 plus an `errors` payload**, so nothing raised and `thetabook price VIX`
95
+ degraded silently through Massive to yfinance. Meanwhile the expiration
96
+ endpoint accepts either form, so `chain VIX` listed 13 expirations and then
97
+ priced nothing, which reads as "VIX has no options". It does — cash-settled
98
+ European on the SOQ, carrying none of the roll decay that makes VXX a poor
99
+ substitute for expressing a vol view.
100
+
101
+ A new `INDEX_ALIASES` map covers 25 verified roots — 10 with listed options
102
+ (`SPX`, `NDX`, `RUT`, `DJX`, `OEX`, `XEO`, `XSP`, `MRUT`, `VIX`, `SPESG`)
103
+ and 15 quote-only vol/stat indices. Every entry was checked against live
104
+ Schwab: bare returns nothing, `$`-prefixed returns a real quote.
105
+
106
+ It is deliberately **separate from `TICKER_ALIASES`** and applied only at
107
+ the market-data boundary, via `tickers.market_symbol()`. `canonicalize` —
108
+ which feeds snapshot symbols, CSV imports, idea-file legs and OCC roots —
109
+ never sees the `$`. Folding the two together would have written
110
+ `$SPX 260116P05000000` on CSV import against the API's
111
+ `SPX 260116P05000000` (so `diff` reported a phantom close *and* a phantom
112
+ open for one position), silently dropped a `$VIX …` line from an idea's
113
+ `## Structure` block, and — worst — priced a genuine equity at the index
114
+ level had one ever listed under a root like `OEX`. The `$` now stays on the
115
+ wire and out of everything persisted.
116
+
117
+ `price` / `chain` / `em --source iv` / `hv` / `vrp` all work on index roots
118
+ now.
119
+
120
+
121
+ - **`evaluate` labels its probabilities as risk-neutral and reports
122
+ `E[payoff]`** ([#88](https://github.com/subsriram/thetabook/issues/88)).
123
+ `Prob. of profit` / `Expected profit` / `Expected loss` were printed with no
124
+ indication they're computed under the pricing measure — drift `r - q`, not
125
+ the instrument's actual expected return. On equities the gap is small; on
126
+ leveraged and volatility ETPs it's 2–3×. A VXX spread was written up as a
127
+ "~1-in-5" trade at PoP 21.1% when the real-world figure is nearer 1-in-10
128
+ with negative expected value. The conditional rows are now marked as
129
+ conditional, and the probability-weighted `E[payoff]` — the only one of the
130
+ three that carries information about edge — sits alongside them. It lands
131
+ ≈ $0 for a fairly-priced structure, which is the signal.
132
+
133
+ The expectations integrate over their own ±5σ grid rather than the ±2σ
134
+ display domain the P&L table is drawn from. `pnl_price_domain` sizes the
135
+ latter for plotting, and at ±2σ the tails still hold ~5% of the mass — for
136
+ an undefined-risk short, exactly where the loss is unbounded. Clamping it to
137
+ the boundary doesn't blur the answer, it inverts it: a fairly-priced ATM
138
+ short call integrated over the display grid reported **+$9.77** against a
139
+ true **−$10.96**, phantom edge on a zero-edge trade. On the wider grid the
140
+ clamped mass is under one part in a million, and `E[payoff]` reproduces the
141
+ closed form `−qty·100·premium·(1 − e^{rT})` to the cent for naked calls,
142
+ puts, longs, and verticals alike.
143
+
144
+ - **`thetabook vrp --dte N`** ([#89](https://github.com/subsriram/thetabook/issues/89)
145
+ Part B). `vrp` sampled the front expiry, which on a liquid name is routinely
146
+ 0–3 DTE — noisy and unrelated to any dated structure. QQQ's 0-DTE ratio read
147
+ **1.12 in the morning and 0.98 the same afternoon** while the Dec 101-DTE leg
148
+ actually being traded sat at **1.78**. `--dte N` selects the nearest expiry at
149
+ least N days out; the sampled DTE is now repeated on the `IV/HV` line (the one
150
+ people copy), a ≤ 7 DTE sample warns, and an unreachable horizon says what it
151
+ sampled instead.
152
+
153
+ - **Structural-decay warnings on `hv` / `em` / `vrp`**
154
+ ([#89](https://github.com/subsriram/thetabook/issues/89) Part A). Realized
155
+ close-to-close vol on a rolling-futures or leveraged-reset product describes
156
+ the current regime rather than the risk being traded: VXX printed HV20 27.1%
157
+ at HV-rank 5.0% while its own ATM IV was ~60%. A static
158
+ `STRUCTURAL_DECAY_TICKERS` list (vol ETPs, leveraged index and single-stock
159
+ funds) drives an advisory warning in each command where its own output is the
160
+ misleading part. Static rather than inferred on purpose — classifying decay
161
+ from price history is its own problem, and a false positive on an ordinary
162
+ equity is worse than a missed exotic.
163
+
164
+ ### Fixed
165
+
166
+ - **Max gain / loss were read off the display grid, understating tail
167
+ risk** ([#99](https://github.com/subsriram/thetabook/issues/99),
168
+ [#101](https://github.com/subsriram/thetabook/pull/101)). They were
169
+ `np.max` / `np.min` over the S ± 30% plotting domain, so any extreme
170
+ outside it was reported at the edge. A 182-DTE AAPL short 160 put read
171
+ −$3,285.62 against a true −$15,535.62, and that is the figure
172
+ `max_position_pct` enforces, so a position 4.7× over its limit passed
173
+ silently. Widening the grid isn't enough: a put bottoms out at S_T = 0,
174
+ which no lognormal grid reaches. P&L at expiry is piecewise-linear with
175
+ kinks only at the strikes, so evaluating at 0, at each strike and along
176
+ the final ray's slope is exact. Unbounded structures now report `±inf`,
177
+ render `Unbounded`, and raise a distinct `max_position_pct` violation.
178
+ `adjust` shows `unbounded → bounded` instead of a NaN delta. Budgets the
179
+ old math got wrong are re-seeded once, with a stderr warning, and stamped
180
+ `budget_basis: analytic`. Budgets it got right, including hand-declared
181
+ ones, are left alone.
182
+
183
+ - **The price behind a cushion or a PoP is now named**
184
+ ([#100](https://github.com/subsriram/thetabook/issues/100),
185
+ [#101](https://github.com/subsriram/thetabook/pull/101)). `positions`
186
+ measured a VIX cushion against the forward while printing spot beside it,
187
+ so a row like "−7.7% cushion on a 17 call at $15.72 spot" was impossible
188
+ on its face. A `fwd` column now shows the reference, and only when some
189
+ row is forward-settled. `?` marks a forward that didn't resolve, such as
190
+ under `--no-fetch`. `adjust` tracks the forward per scenario, so a roll
191
+ across expiries renders `(fwd $18.42 → $19.05)` instead of naming only
192
+ the new leg's future.
193
+
194
+ - **CSV-imported option `averagePrice` was per contract, not per share**
195
+ ([#109](https://github.com/subsriram/thetabook/pull/109)). The Schwab and
196
+ Empower importers divided total cost basis by contract count, so a short
197
+ call sold for $6.20 landed as `620`. Every consumer reads that field per
198
+ share, and `adjust` on such a snapshot reported a $123,170 realized P&L on
199
+ a $410 buyback. Fidelity reads the broker's own per-share column and is
200
+ unchanged. Snapshots imported before this fix keep the inflated value
201
+ until the CSVs are re-imported.
202
+
203
+ - **Deep bar history comes from yfinance when defeatbeta has no coverage**
204
+ ([#111](https://github.com/subsriram/thetabook/issues/111),
205
+ [#112](https://github.com/subsriram/thetabook/pull/112)). The whole window
206
+ used to go through the live cascade, and Schwab's deep daily history
207
+ carries weekend-dated copies of Friday's close, missing sessions, bad
208
+ prints, and a pre-2020 XLE series 4–15% off. yfinance (defeatbeta's own
209
+ upstream) now serves everything older than 14 days, and the live cascade
210
+ only that tail. Weekend-dated daily rows are dropped from every source
211
+ with one warning, and the sources used are recorded on the frame.
212
+
213
+ - **defeatbeta history was 404ing for every uncached ticker**
214
+ ([#113](https://github.com/subsriram/thetabook/pull/113)). The upstream
215
+ dataset moved its parquet files under `data/US/`, which defeatbeta-api
216
+ 0.0.57 hard-coded the old way, so `hv` / `ta` / `scenarios` silently fell
217
+ back to the live cascade. The floor is now `defeatbeta-api>=0.0.63`, and
218
+ the output-silencing wrapper is updated for its new logging (nltk is gone).
219
+
220
+ - **Fidelity CSV edge cases**
221
+ ([3385271](https://github.com/subsriram/thetabook/commit/3385271)).
222
+ Schwab-held options inside a Fidelity FullView export
223
+ (`PUT AMD$475 EXP 07/17/26`, no option root) warn and are skipped, with a
224
+ pointer to `thetabook refresh`, instead of mis-parsing. Header detection
225
+ is case-insensitive, and a missing `Average Cost Basis` column no longer
226
+ raises.
227
+
228
+ - **VIX options were priced off spot, not the futures curve they reference**
229
+ ([#96](https://github.com/subsriram/thetabook/issues/96)). VIX options settle
230
+ to the SOQ and reference the VIX *future* for their expiry; no cash-and-carry
231
+ links future to spot, so no `r`/`q` choice bridges them. On 2026-09-08 spot
232
+ was 15.72 against an October forward of 18.42 — 17.2% contango — and pricing
233
+ off spot underpriced the chain by **56% at the money and 85% on the wings**,
234
+ while centring every probability on a price the contract never settles
235
+ against. "VIX above 18 at expiry" read **21.5%** off spot against **51.2%**
236
+ off the forward.
237
+
238
+ `VolResolver.resolve_forward()` derives the forward from put-call parity on
239
+ the chain already fetched — `F = K + (C − P)·e^{rT}`, median across strikes
240
+ carrying both legs, so one stale wing can't move it. Resolution is per leg,
241
+ since the forward is per expiry and a calendar spread carries a different one
242
+ on each. It feeds `compute_greeks`, `evaluate`'s PoP / `E[payoff]` /
243
+ expectation grid, `adjust`'s opening marks and scenario PoP, portfolio Greeks
244
+ aggregation, and `positions` cushion — where a VIX 20 call reads +27.2% OTM
245
+ off spot and **+8.6%** off the forward.
246
+
247
+ Pricing on that path uses **Black-76** (`q = r`), not Black-Scholes with the
248
+ spot swapped — the forward already embeds the carry, so leaving `q` at 0
249
+ applied it twice. The error is signed opposite by side: calls were overpriced
250
+ (+1.2% to +7.1%) and **puts underpriced** (−9.8% to −1.4%), so a short VIX 15
251
+ put — the position this work is built around — was marked 5.2% light.
252
+
253
+ `tickers.FORWARD_SETTLED` holds `VIX` alone: the other vol indices share the
254
+ structure but CBOE delisted their options. SPX / NDX / RUT are excluded for a
255
+ different reason — they settle on the index itself, so spot *is* the
256
+ underlying and ordinary carry already gives the forward. Every command-level
257
+ caller warns when parity can't be derived rather than silently using spot —
258
+ including `positions --no-fetch`, which can't derive one at all — and both
259
+ `evaluate` and `adjust` name the forward in their headers.
260
+
261
+ PoP now integrates the same ±5σ grid the expectations use, in both `evaluate`
262
+ and `adjust`. The old ±2σ display domain closed an unbounded profitable
263
+ *region* at its edge, so **recorded PoP moves for most structures**, not just
264
+ forward-settled ones. What matters is whether the profitable region is
265
+ bounded on both sides, not whether P&L is capped:
266
+
267
+ | structure | before | after |
268
+ | --- | ---: | ---: |
269
+ | AAPL 182-DTE short put | 62.5% | 73.3% |
270
+ | AAPL 6-month 170/180 debit call vertical | 38.7% | 49.5% |
271
+ | AAPL iron condor 150/160/190/200 | 36.6% | 36.6% |
272
+
273
+ A debit vertical's profit region is `[breakeven, ∞)` even though its P&L is
274
+ capped, so it moves; an iron condor is bounded on both sides and does not.
275
+ The new figures are the correct ones — the old domain simply stopped
276
+ integrating at `S ± 30%` — but expect existing ideas' recorded PoP to change
277
+ on the next `evaluate`.
278
+
279
+ Schwab's broker Greeks for VIX remain suspect — 10 of 36 October calls report
280
+ delta > 1.0 — and are untouched here; `--greeks-source bs` forces the
281
+ corrected path.
282
+
283
+ - **Schwab has never served option expirations**
284
+ ([#91](https://github.com/subsriram/thetabook/issues/91)).
285
+ `list_expirations_schwab` read `year` / `month` / `day` out of
286
+ `expirationList`, keys the payload has never carried — it returns
287
+ `{"expirationDate": "2026-10-21", …}`. It therefore returned `None` for
288
+ *every* ticker and the cascade quietly fell through to yfinance:
289
+ 15-minute-delayed, and empty for index roots, which is what made #91 look
290
+ like an entitlements problem. The test fixture encoded the same invented
291
+ shape, which is why it survived; it now pins a payload captured live.
292
+
293
+ - **Ticker aliases didn't reach the bars backbone**
294
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). `get_bars` never
295
+ canonicalized, so the alias map applied to the live price cascade but not to
296
+ history: `thetabook price BRKB` worked while `thetabook hv BRKB` silently
297
+ returned nothing. Canonicalization now happens at `get_bars` — the one
298
+ chokepoint every bars consumer passes through — matching what `prices.py`
299
+ and `chains.py` already do at their entry points.
300
+
301
+
302
+ - **Schwab HTTP errors now surface the response body**
303
+ ([#91](https://github.com/subsriram/thetabook/issues/91)).
304
+ `raise_for_status()` renders only the status line, so a Schwab 400 arrived as
305
+ `Client error '400 Bad Request' for url ...` with no hint of what Schwab
306
+ objected to — and for a rejected symbol form the body is the whole diagnosis.
307
+ All six Schwab read call sites now append a truncated excerpt.
308
+
309
+ - **`chain` explains the listable-but-unpriceable case**
310
+ ([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's two
311
+ endpoints disagree about symbology: `chain VIX` lists 13 expirations — implying
312
+ the symbol is fine — and then every strike lookup returns empty, so the
313
+ reasonable conclusion is "VIX has no options". It does; VIX options are
314
+ cash-settled European and carry none of the roll decay that cost a VXX
315
+ position 79.3% over three years while VIX itself rose 9.6%. The no-contracts
316
+ path now names index symbology as the likely cause, but only in that
317
+ contradictory case — a date that isn't listed gets different advice, and a
318
+ ticker with no options gets the plain message.
319
+
320
+
321
+
322
+ - **Idea frontmatter and the `## Evaluation` body could disagree about
323
+ max gain/loss** ([#92](https://github.com/subsriram/thetabook/issues/92)).
324
+ `update_idea_file` set `max_gain` / `max_loss` only when unset, while the
325
+ body section was regenerated on every run — so a re-evaluated idea carried a
326
+ frozen frontmatter and a fresh body contradicting each other in the same
327
+ file, with nothing marking which was current (observed: `max_gain: 4490.0`
328
+ against a body reading `$4,480.00`, both written by `evaluate` hours apart).
329
+
330
+ Beyond cosmetics: `accounts.check_idea` enforces `max_position_pct` off the
331
+ frontmatter, so the risk check read a figure the body had already moved past,
332
+ and nothing bounded the gap — an idea first evaluated months ago kept its
333
+ original numbers forever.
334
+
335
+ **The enforced number is deliberately unchanged.** `check_idea` still reads
336
+ the same frozen `max_loss` it always did; what the split fixes is that the
337
+ file no longer presents two contradictory figures under one name, and the
338
+ frozen one is now labelled as what it is. A position limit *should* bind on
339
+ the risk accepted at entry rather than on a mark that moves under you — so
340
+ don't expect `max_position_pct` to start tracking the live number.
341
+
342
+ Split into two pairs. `max_gain` / `max_loss` stay write-once and become the
343
+ **author-declared risk budget**; new `evaluated_max_gain` /
344
+ `evaluated_max_loss` refresh every run. `check_idea` enforces the budget and
345
+ falls back to the computed value only when none was set, so a position limit
346
+ binds on the risk accepted at entry rather than on a mark that moves under
347
+ you, and ideas predating the field stay checkable. Existing files keep
348
+ loading unchanged; the new keys appear on the next `evaluate`.
349
+
350
+ `thetabook evaluate --reseed-budget` re-declares the budget from the current
351
+ run. Write-once with no writer would be a trap: every value in a pre-split
352
+ file was machine-written (one reads `-1223.1980000000003`, float noise off
353
+ `np.min` rather than a number anyone declared), and freezing those forever
354
+ while making them the sole input to a risk rule needs a way out that isn't
355
+ hand-editing frontmatter the CLI otherwise owns.
356
+
357
+ `adjust --save` seeds both pairs, and the wiki ideas roll-up now shows
358
+ `evaluated_max_loss` — it's the cross-session review surface, so it should
359
+ carry what the position risks now rather than the frozen seed.
360
+
361
+ Also routes `evaluate`'s write notice through `log.note` to **stderr** —
362
+ stdout is reserved for parseable output, and a status line there is easy to
363
+ miss when output is piped or read by an agent.
364
+
365
+
366
+
367
+ - **`adjust`'s BS-estimated opening premium used flat vol, not chain IV at the
368
+ strike** ([#32](https://github.com/subsriram/thetabook/issues/32)). When
369
+ `--open` / `--add` got a leg with no `premium=` and the chain had no usable
370
+ quote, `resolve_opening_mark` priced it off the flat 25% default — while
371
+ `compute_greeks` priced the *same hypothetical leg in the same scenario* off
372
+ the chain's IV at that strike. The premium and the Greeks then disagreed
373
+ about what the position was worth inside a single invocation.
374
+
375
+ The two lookups diverge precisely where it hurts: a chain can cover a strike
376
+ for **IV** but not for a usable **quote** — an illiquid wing with no
377
+ bid/ask, a yfinance row carrying `implied_vol` and nothing else, or an
378
+ earnings-week wing where IV ramps. The BS fallback now resolves IV per-leg
379
+ through `VolResolver.resolve_leg_iv`, the same call the Greeks make, so one
380
+ sigma drives both. The error was not small on wings: a 45-DTE OTM call at a
381
+ 62% chain IV prices at **$6.96** against **$0.53** at flat 25%, since option
382
+ value is sharply convex in vol when far OTM.
383
+
384
+ Priority is unchanged from the Greeks path — `--vol` override → chain IV at
385
+ the exact strike → flat default — and both the sigma and its provenance are
386
+ now recorded on the leg (`premium_iv`, `premium_iv_source`) and surfaced in
387
+ the comparison table as `bs @ 62% chain IV`, `bs @ 30% --vol override`, or
388
+ `bs @ 25% flat default`, so a BS-estimated premium is auditable instead of
389
+ an unattributed number. This applies under `--marks frozen` too: frozen
390
+ skips the live chain for *marks*, but the Greeks resolve per-leg chain IV in
391
+ a frozen run regardless, so exempting the premium there would have left the
392
+ same divergence alive. Only a resolver-less caller uses the flat vol.
393
+
394
+ The report header now reads `Vol: chain IV (per-leg)` instead of a single
395
+ flat number whenever `--vol` is absent — it previously printed `Vol: 25%`
396
+ above a table row reading `bs @ 62% chain IV`.
397
+
8
398
  ## [2.2.3] — 2026-09-08
9
399
 
10
400
  Housekeeping release, plus the last uncovered corner of Schwab's 7-day
@@ -24,7 +24,8 @@ The name nods to **theta**, the daily decay that quietly drives most options P&L
24
24
  - **When the CLI doesn't expose what you need, drop into Python** — but always call `thetabook.paths.load_env()` first. Without it, the Schwab client returns `None` and the data cascade silently falls through to a worse source (yfinance), producing answers that disagree with the CLI's. If the gap is reusable, file an issue to surface it via a flag or new subcommand rather than letting the Python escape hatch normalize.
25
25
  - **For technical analysis, use `thetabook hv` / `ta` / `scenarios` / `bars`.** `thetabook ta TICKER` gives RSI/MACD/Bollinger with interpretive labels; `thetabook hv TICKER` gives realized vol + HV-rank/percentile (the IV-rank substitute — there's no historical option IV); `thetabook scenarios match TICKER` answers "has this regime happened before?" with forward-return outcomes (run both `--mode trajectory` and `--mode state`; when they disagree, present both rather than averaging). These read daily *closes* from a historical-bars backbone, not the live price cascade — see [docs/cli.md](docs/cli.md) for the full flag set and [docs/behaviors.md](docs/behaviors.md) for the stitch.
26
26
  - **For vol-to-decision questions, use `thetabook em` / `vrp`.** `thetabook em TICKER --dte N` translates a vol figure into the ±1σ / ±2σ dollar range an option is pricing by expiry (`spot · σ · sqrt(DTE/365)`, calendar-day horizon — deliberately *not* `hv`'s `sqrt(252)`); sigma defaults to HV20, with `--iv` to override or `--source iv` to pull front-month ATM IV from the chain. `thetabook vrp TICKER` ratios that ATM IV against HV to answer "is implied richer than realized right now?" — a *point-in-time* IV-vs-HV read, **not** a historical IV-rank. Unlike the bars commands, both blend the live price/chain cascade (spot, IV) with bars-derived HV, so the IV paths need a Greeks-bearing source (Schwab or Massive) and exit non-zero on a yfinance-only fallback rather than printing a bogus number.
27
- - **Know how fresh each source is before quoting a number.** The historical bars under `hv`/`ta`/`scenarios` are a stitch: defeatbeta (weekly HuggingFace dataset) covers history up to the **most recent Friday's close**, and the rolling tail through today is filled by the **same live cascade as the price pipeline — Schwab → Massive → yfinance** — so the latest *complete* indicator bar is usually last Friday, and intraday moves aren't reflected until the day closes. In the live price cascade, **Massive returns the previous business day's close, not an intraday quote** (Polygon `get_previous_close_agg`; the bars tail instead uses Massive's date-range daily aggregates); only Schwab is real-time and yfinance is ~15-min delayed. When a figure comes from Massive or from the defeatbeta history, say so — don't present it as the current price.
27
+ - **For strategy research, use `thetabook backtest`** (`run` / `grid` / `signal`; `/backtest` drives it), not throwaway scripts over `market.bars`. Everything it prints is *hypothetical backtested performance*, so quote it that way and never as a recommendation. To compare configurations, run one `grid` rather than repeated `run`s, so the trial count and deflated Sharpe see the whole search. Pass `--prior-trials` for configs already tried by hand. Add `--save` only when the user wants a kept record; it writes an immutable manifest under `personal/backtests/`, which must never be edited. Read OOS, the DSR (< 0.95 = indistinguishable from selection luck) and `--walk-forward` rather than the top IS row, and treat |t| < 2 as noise. Conventions are in [docs/behaviors.md](docs/behaviors.md) "Backtests".
28
+ - **Know how fresh each source is before quoting a number.** The historical bars under `hv`/`ta`/`scenarios` are a stitch: defeatbeta (weekly HuggingFace dataset) covers history up to the **most recent Friday's close**, and the rolling tail through today is filled by the **same live cascade as the price pipeline — Schwab → Massive → yfinance** — so the latest *complete* indicator bar is usually last Friday, and intraday moves aren't reflected until the day closes. For a ticker defeatbeta doesn't cover, **yfinance** serves the deep history instead and the live cascade only the last 14 days (#111). In the live price cascade, **Massive returns the previous business day's close, not an intraday quote** (Polygon `get_previous_close_agg`; the bars tail instead uses Massive's date-range daily aggregates); only Schwab is real-time and yfinance is ~15-min delayed. When a figure comes from Massive or from the defeatbeta history, say so — don't present it as the current price.
28
29
 
29
30
  ## Repo layout
30
31
 
@@ -39,6 +40,7 @@ thetabook/
39
40
  │ ├── analysis/ # derived signals: HV, TA, expected move, VRP, scenario lookup
40
41
  │ ├── portfolio/ # snapshot I/O, CSV import, options book, per-account rules, scaffold
41
42
  │ ├── ideas/ # trade-idea workflow (manage / evaluate / adjust / roll)
43
+ │ ├── backtest/ # hypothetical strategy backtests + live signal (one code path)
42
44
  │ ├── wiki/ # personal/wiki/ lint + auto-rendered ideas roll-up
43
45
  │ ├── skills/ # author-time tooling + registry installer for skill files
44
46
  │ ├── templates/ # canonical templates, shipped inside the wheel (idea.md,
@@ -51,6 +53,7 @@ thetabook/
51
53
  │ ├── ideas/ # trade ideas, one file per idea
52
54
  │ ├── accounts.toml # per-account posture + rules
53
55
  │ ├── config.toml # per-clone overrides ([market], [adjust], [schwab], [skills])
56
+ │ ├── backtests/ # immutable run manifests (`backtest run|grid --save`); never edit
54
57
  │ └── wiki/ # LLM-maintained knowledge base — compounds over time
55
58
  └── tests/ # pytest suite — mirrors src/thetabook/ (has its own CLAUDE.md)
56
59
  ```
@@ -83,7 +86,8 @@ The skills CLI (`thetabook skills lint/show/install/installed/sync/remove/render
83
86
  - **Dates**: ISO format (`YYYY-MM-DD`) everywhere — filenames, frontmatter, tables.
84
87
  - **Money**: show dollar amounts with commas and 2 decimals (`$12,345.67`).
85
88
  - **Option contracts**: reference as `TICKER YYYY-MM-DD STRIKE C/P` (e.g. `AAPL 2026-01-16 180 C`).
86
- - **Ideas** use frontmatter: `status: proposed | watching | opened | closed | rejected`, plus `opened_at`, `closed_at`, `thesis`, `outcome`.
89
+ - **Share legs**: an idea's `## Structure` takes share lines beside option lines — `TICKER shares qty=+100 cost_basis=150.00`. `cost_basis` is per-share and required; a share line without it is refused rather than skipped. **Declare the shares for every covered structure** (covered call, buy-write, collar, assigned position) — omitting them is silent, and the position then evaluates as naked: `Max loss: Unbounded` on a structure bounded at −$14,772, and a net delta of the wrong sign. See [docs/behaviors.md](docs/behaviors.md) "Share legs in idea files".
90
+ - **Ideas** use frontmatter: `status: proposed | watching | opened | closed | rejected`, plus `opened_at`, `closed_at`, `thesis`, `outcome`. Dollar fields come in two flavours: `max_gain`/`max_loss` are the author-declared risk budget (seeded by the first `evaluate`, then write-once — the sole exception is a one-time #99 migration, per side, marked by `budget_basis`), while `evaluated_max_gain`/`evaluated_max_loss` refresh on every run. Both pairs are **closed-form extremes over `S_T >= 0`**, not grid reductions, and carry `±inf` (displayed `Unbounded`) for a structure with no bound. `max_position_pct` enforces against the budget, but reads *whether* the position is unbounded off `evaluated_max_loss`, so a frozen budget can't mask a naked short. See [docs/behaviors.md](docs/behaviors.md) "Max profit / max loss are closed form".
87
91
  - **Journal entries** have sections: `Positions reviewed`, `Discussion`, `Ideas generated`, `Learnings`.
88
92
  - **Assignment cost basis**: when a short put is assigned, record the basis components as distinct fields in idea outcomes, wiki trade arcs, and journal entries — **Assigned price (cost basis)** = strike, **Option income** = put premium, **Effective price (reference)** = strike − premium. The IRS-correct share basis for an assigned written put is the *effective price* (Pub 550 — the premium reduces the basis rather than being a separate gain), so don't double-count the premium as separate income on top of it. Quote the strike as the basis only when reconciling against a broker 1099-B that didn't adjust for the premium (`thetabook adjust --assign-basis strike`). See [docs/behaviors.md](docs/behaviors.md) "Assignment cost basis".
89
93
 
@@ -199,7 +203,7 @@ Configuration lives in `pyproject.toml`. Active rule packs: `E, W, F, I, B, UP,
199
203
 
200
204
  ## Mypy
201
205
 
202
- Permissive baseline by default (no `disallow_untyped_defs`); strict in modules that are clean today (currently `bs.py` and `config.py` — list lives in `[[tool.mypy.overrides]]`). Tests are excluded from mypy. With pydantic models everywhere post-M17, fixture types are clear at the call site; ad-hoc test typing isn't worth the churn.
206
+ Permissive baseline by default (no `disallow_untyped_defs`); strict in modules that are clean today (currently `bs.py`, `config.py` and `backtest/{engine,signals,metrics,manifest}.py` — list lives in `[[tool.mypy.overrides]]`). Tests are excluded from mypy. With pydantic models everywhere post-M17, fixture types are clear at the call site; ad-hoc test typing isn't worth the churn.
203
207
 
204
208
  When mypy flags something, prefer fixing the underlying type over adding `# type: ignore`. If you do suppress, use a specific code (`# type: ignore[arg-type]`) and a one-line reason. Never invent fallback branches just to satisfy the type checker — if an upstream contract already excludes the unsafe case, prefer a walrus filter, an `assert` with rationale, or a typed ignore over a defensive code path that's dead at runtime.
205
209
 
@@ -16,17 +16,18 @@ uv sync
16
16
 
17
17
  That's it — `uv sync` installs the project as an editable package, so `thetabook ...` and `uv run pytest` both work immediately.
18
18
 
19
- ## The three gates
19
+ ## The four gates
20
20
 
21
- Every PR has to pass three checks. Run them locally before you push — CI runs the same set ([.github/workflows/ci.yml](.github/workflows/ci.yml)):
21
+ Every PR has to pass four checks. Run them locally before you push — CI runs the same set ([.github/workflows/ci.yml](.github/workflows/ci.yml)):
22
22
 
23
23
  ```bash
24
- uv run pytest # tests
25
- uv run ruff check . # lint + format
26
- uv run mypy . # types
24
+ uv run pytest # tests
25
+ uv run ruff check . # lint
26
+ uv run ruff format --check . # formatting
27
+ uv run mypy . # types
27
28
  ```
28
29
 
29
- `ruff format` is the formatter. If `ruff check` is unhappy with formatting, run `uv run ruff format .` to fix.
30
+ `ruff format` is the formatter. If the format check fails, run `uv run ruff format .` to fix.
30
31
 
31
32
  ## What lands easily
32
33
 
@@ -1,10 +1,10 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: thetabook
3
- Version: 2.2.3
3
+ Version: 2.3.0
4
4
  Summary: A journal for options traders who think in Greeks — Schwab portfolio review and strategy log with an AI copilot.
5
5
  License-File: LICENSE
6
6
  Requires-Python: >=3.12
7
- Requires-Dist: defeatbeta-api>=0.0.57
7
+ Requires-Dist: defeatbeta-api>=0.0.63
8
8
  Requires-Dist: massive>=2.5.0
9
9
  Requires-Dist: numpy>=2.4.4
10
10
  Requires-Dist: pandas>=2.2
@@ -138,6 +138,19 @@ thetabook import-csv schwab.csv fidelity.csv empower.csv
138
138
 
139
139
  This produces the same snapshot format as the API path, so everything downstream works identically. Both option symbols and cash balances are handled.
140
140
 
141
+ ### Guided demo
142
+
143
+ From a dev checkout, `scripts/demo.sh` walks the main loop — snapshot, diff, positions, Greeks, account rules, vol/TA/scenarios, chain, ideas, evaluate, adjust/roll, wiki — one step at a time:
144
+
145
+ ```bash
146
+ scripts/demo.sh # press Enter to advance
147
+ scripts/demo.sh --auto # no pauses (rehearsal)
148
+ scripts/demo.sh --from 7 # resume at step 7
149
+ scripts/demo.sh --reset # wipe the sandbox
150
+ ```
151
+
152
+ It runs against a throwaway `$THETABOOK_HOME` (default `/tmp/thetabook-demo`, override with `DEMO_HOME`) seeded with a fictional book, so no real account data appears on screen, and it refuses to run against, inside, or around your real home. Market data is live: it borrows your `.env` and Schwab token, so run `thetabook refresh --reauth` first if the token is more than 7 days old. Without one it still runs off Massive/yfinance, and the tables flag the previous-close spot. `scripts/demo.sh --help` lists the environment overrides. `scripts/` isn't in the wheel, so this needs a clone.
153
+
141
154
  ## Daily / weekly workflow
142
155
 
143
156
  In a Claude Code session inside this directory:
@@ -187,6 +200,7 @@ In between reviews, use **`/ideas`** to browse:
187
200
  | `/diff [dates]` | Compare two snapshots: positions added/removed/changed, balance moves |
188
201
  | `/accounts-init` | Scaffold `personal/accounts.toml` from latest snapshot (label each type)|
189
202
  | `/wiki-lint` | Health check on the wiki (orphan ideas, stale stats, drift, missing) |
203
+ | `/backtest` | Hypothetical strategy backtest, parameter grid, or this period's signal |
190
204
 
191
205
  > **Note on `/review`:** that name is taken by a Claude Code built-in (GitHub PR reviewer). Use `/portfolio` for portfolio review.
192
206
 
@@ -230,6 +244,12 @@ thetabook vrp AAPL # ATM IV vs realized HV, righ
230
244
  thetabook scenarios match AAPL # historical analogues + forward returns
231
245
  thetabook bars boundary AAPL # the defeatbeta/live stitch seam
232
246
 
247
+ # Backtests (hypothetical; stdout only unless --save)
248
+ thetabook backtest list # registered strategies + params
249
+ thetabook backtest run dual-momentum # vs benchmark / EW universe / cash, IS/OOS
250
+ thetabook backtest grid sector-rotation --vary n=2,3,4 --walk-forward # trials, deflated Sharpe
251
+ thetabook backtest signal sector-rotation # this period's book = last row of the run
252
+
233
253
  # Accounts, tickers, wiki, skills
234
254
  thetabook accounts check-portfolio --show-all --top 10
235
255
  thetabook tickers add BRKB BRK/B
@@ -319,6 +339,10 @@ On transient failures (timeout / connection reset / 5xx), `fetch_prices_massive`
319
339
 
320
340
  Option Greeks are far more price-sensitive than equity delta — a couple of dollars on a near-ATM strike flips the ITM flag and swings delta/theta — so `thetabook greeks` and `thetabook positions` **always re-price option underlyings live**, even when the snapshot is fresh. Equity-only tickers keep the cheaper gap-fill-only path. Both commands render a `Src` column and a freshness label (`live` / `prev-close` / `delayed` / `manual` / `snapshot <date>`) so a Massive previous-close or a snapshot fallback can't masquerade as a live quote. Details in [docs/behaviors.md](docs/behaviors.md).
321
341
 
342
+ ### Backtests
343
+
344
+ `thetabook backtest` tests a systematic rule, such as sector rotation or SPY/TLT/GLD dual momentum, on total-return history built from the bars stitch. It enforces signal-at-close → trade-next-close timing, non-zero costs by default, and benchmarks with t-stats. The live `signal` is the last row of the same run, so the backtest and the weekly call can't drift apart. `backtest grid` sweeps parameters and prints how many configurations were tried. It ranks on in-sample results only, deflates the winner's Sharpe for the search (Bailey & López de Prado), and can chain a walk-forward out-of-sample series. Every output is stamped *hypothetical backtested performance*. Nothing is written to disk unless you pass `--save` to `run` or `grid`. That keeps an immutable manifest (payload, params, code version, data fingerprint) under `$THETABOOK_HOME/backtests/`, as a reproducible record for anything that might be shown to someone else. Flags are in [docs/cli.md](docs/cli.md) "Backtests"; conventions (TR basis, lag, costs, cash proxy, DSR, walk-forward timing) are in [docs/behaviors.md](docs/behaviors.md).
345
+
322
346
  ### Other runtime behaviors
323
347
 
324
348
  Option-symbol parse failures (a one-time deduped warning rather than a silently dropped position), the share-asset filter that keeps `COLLECTIVE_INVESTMENT` ETFs like QQQ in scope, ticker aliases, Schwab token expiry and re-auth, per-account rules, and the idea-lifecycle CLI/Edit boundary are all covered in **[docs/behaviors.md](docs/behaviors.md)**.
@@ -395,6 +419,16 @@ thetabook/
395
419
  │ │ ├── adjust.py # what-if adjustment modeling
396
420
  │ │ └── roll_scenarios.py # roll scenario grid
397
421
  │ │
422
+ │ ├── backtest/ # hypothetical strategy backtests + live signal (one code path)
423
+ │ │ ├── data.py # total-return panel: bars + dividends, holes, outlier screen
424
+ │ │ ├── engine.py # pure: targets → lagged, cost/borrow/cash-adjusted returns
425
+ │ │ ├── signals.py # pure: momentum, residual momentum, dispersion, rebalance dates
426
+ │ │ ├── metrics.py # pure: CAGR / Sharpe / MaxDD / active t / deflated Sharpe
427
+ │ │ ├── strategies/ # sector_rotation.py, dual_momentum.py + REGISTRY
428
+ │ │ ├── report.py # simulate() → backtest + signal reports
429
+ │ │ ├── grid.py # parameter sweeps: IS-only ranking, DSR, walk-forward
430
+ │ │ └── manifest.py # --save: run manifest + panel fingerprint; the only writer here
431
+ │ │
398
432
  │ ├── wiki/ # personal/wiki/ health checks + auto-rendered ideas roll-up
399
433
  │ │ ├── lint.py # compute_lint_report → render_lint_text/json (11 check IDs)
400
434
  │ │ └── render.py # render_ideas_page (marker-region preservation)
@@ -419,7 +453,7 @@ thetabook/
419
453
  │ │
420
454
  │ └── cli/ # typer subcommands — `thetabook <cmd>` enters here
421
455
  │ ├── CLAUDE.md # the add-a-subcommand checklist
422
- │ ├── __init__.py # root Typer app (21 commands + 7 sub-apps)
456
+ │ ├── __init__.py # root Typer app (21 commands + 8 sub-apps)
423
457
  │ ├── _shared.py # shared option types (PricesOpt, MarksOpt, etc.)
424
458
  │ └── <one file per command>
425
459
  │
@@ -430,6 +464,7 @@ thetabook/
430
464
  │ ├── journal/ # one markdown file per review session
431
465
  │ ├── ideas/ # trade ideas (NNN-short-name.md)
432
466
  │ ├── cache/bars/ # cached daily OHLCV (3-day TTL + version probe)
467
+ │ ├── backtests/ # immutable run manifests from `backtest run|grid --save`
433
468
  │ ├── accounts.toml # per-account posture + rules (PII)
434
469
  │ ├── config.toml # per-clone user overrides ([market], [adjust], [schwab], [skills])
435
470
  │ ├── ticker_aliases.toml # user-added symbol aliases
@@ -464,15 +499,16 @@ thetabook/
464
499
  ├── .env.example # template for API credentials
465
500
  │
466
501
  └── .claude/
467
- └── commands/ # project-level slash commands (17 commands)
502
+ └── commands/ # project-level slash commands (18 commands)
468
503
  ├── setup.md / refresh.md / portfolio.md
469
504
  ├── idea.md / ideas.md / evaluate.md / adjust.md
470
505
  ├── open.md / close.md / roll.md / roll-scenarios.md
471
506
  ├── greeks.md / price.md / chain.md / diff.md
472
507
  ├── accounts-init.md / wiki-lint.md
508
+ ├── backtest.md
473
509
  ```
474
510
 
475
- The test suite has 1848 tests as of v2.2.3. Four gates run on every change, all enforced in CI: `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy .`.
511
+ The current test count is pinned in [docs/README.md](docs/README.md) "Ownership rules". Four gates run on every change, all enforced in CI: `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy .`.
476
512
 
477
513
  ## Conventions
478
514