thetabook 2.2.1__tar.gz → 2.2.3__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 (121) hide show
  1. thetabook-2.2.3/.git-blame-ignore-revs +8 -0
  2. {thetabook-2.2.1 → thetabook-2.2.3}/.github/workflows/ci.yml +3 -0
  3. {thetabook-2.2.1 → thetabook-2.2.3}/.github/workflows/publish.yml +3 -0
  4. thetabook-2.2.3/AGENTS.md +5 -0
  5. {thetabook-2.2.1 → thetabook-2.2.3}/CHANGELOG.md +156 -0
  6. {thetabook-2.2.1 → thetabook-2.2.3}/CLAUDE.md +19 -14
  7. {thetabook-2.2.1 → thetabook-2.2.3}/PKG-INFO +2 -2
  8. {thetabook-2.2.1 → thetabook-2.2.3}/README.md +137 -178
  9. {thetabook-2.2.1 → thetabook-2.2.3}/ROADMAP.md +18 -3
  10. {thetabook-2.2.1 → thetabook-2.2.3}/pyproject.toml +1 -1
  11. thetabook-2.2.3/src/thetabook/CLAUDE.md +46 -0
  12. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/scenarios.py +3 -7
  13. thetabook-2.2.3/src/thetabook/cli/CLAUDE.md +21 -0
  14. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/adjust.py +14 -0
  15. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/evaluate.py +1 -2
  16. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/hv.py +1 -2
  17. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/ideas.py +1 -3
  18. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/import_csv.py +1 -3
  19. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/init.py +2 -4
  20. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/leg_mark.py +9 -2
  21. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/migrate_home.py +2 -8
  22. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/refresh.py +1 -1
  23. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/snapshot.py +1 -4
  24. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/ta.py +1 -2
  25. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/wiki.py +1 -3
  26. thetabook-2.2.3/src/thetabook/config.py +202 -0
  27. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/adjust.py +97 -37
  28. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/core.py +11 -12
  29. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/evaluate_idea.py +3 -7
  30. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/manage_ideas.py +12 -12
  31. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/roll_scenarios.py +20 -6
  32. thetabook-2.2.3/src/thetabook/market/_schwab.py +233 -0
  33. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/bars.py +2 -1
  34. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/chains.py +4 -2
  35. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/dividends.py +5 -10
  36. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/earnings.py +0 -2
  37. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/leg_marks.py +1 -0
  38. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/prices.py +3 -1
  39. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/models.py +41 -1
  40. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/paths.py +21 -2
  41. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/accounts.py +24 -31
  42. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/csv_parsers/__init__.py +3 -5
  43. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/csv_parsers/_base.py +1 -3
  44. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/csv_parsers/empower.py +3 -9
  45. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/csv_parsers/fidelity.py +3 -9
  46. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/diff_snapshots.py +11 -2
  47. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/get_positions.py +41 -41
  48. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/import_csv_snapshot.py +13 -5
  49. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/options_book.py +43 -16
  50. thetabook-2.2.3/src/thetabook/preflight.py +197 -0
  51. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/pricing/greeks.py +148 -30
  52. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/registry.py +4 -5
  53. thetabook-2.2.3/src/thetabook/templates/config.toml.example +42 -0
  54. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/idea.md +13 -1
  55. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/skill.md +1 -1
  56. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/tickers.py +1 -2
  57. {thetabook-2.2.1 → thetabook-2.2.3}/uv.lock +1 -1
  58. thetabook-2.2.1/src/thetabook/config.py +0 -42
  59. thetabook-2.2.1/src/thetabook/market/_schwab.py +0 -77
  60. thetabook-2.2.1/src/thetabook/templates/config.toml.example +0 -18
  61. {thetabook-2.2.1 → thetabook-2.2.3}/.env.example +0 -0
  62. {thetabook-2.2.1 → thetabook-2.2.3}/.gitignore +0 -0
  63. {thetabook-2.2.1 → thetabook-2.2.3}/.python-version +0 -0
  64. {thetabook-2.2.1 → thetabook-2.2.3}/CONTRIBUTING.md +0 -0
  65. {thetabook-2.2.1 → thetabook-2.2.3}/LICENSE +0 -0
  66. {thetabook-2.2.1 → thetabook-2.2.3}/SECURITY.md +0 -0
  67. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/__init__.py +0 -0
  68. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/__init__.py +0 -0
  69. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/em.py +0 -0
  70. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/hv.py +0 -0
  71. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/ta.py +0 -0
  72. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/analysis/vrp.py +0 -0
  73. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cache.py +0 -0
  74. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/__init__.py +0 -0
  75. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/_shared.py +0 -0
  76. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/accounts.py +0 -0
  77. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/bars.py +0 -0
  78. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/bs.py +0 -0
  79. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/chain.py +0 -0
  80. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/diff.py +0 -0
  81. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/dividends.py +0 -0
  82. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/earnings.py +0 -0
  83. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/em.py +0 -0
  84. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/greeks.py +0 -0
  85. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/positions.py +0 -0
  86. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/price.py +0 -0
  87. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/roll.py +0 -0
  88. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/scenarios.py +0 -0
  89. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/skills.py +0 -0
  90. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/tickers.py +0 -0
  91. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/cli/vrp.py +0 -0
  92. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/ideas/__init__.py +0 -0
  93. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/leg_parse.py +0 -0
  94. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/log.py +0 -0
  95. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/__init__.py +0 -0
  96. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/market/vol_lookup.py +0 -0
  97. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/__init__.py +0 -0
  98. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/csv_parsers/schwab.py +0 -0
  99. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/portfolio/scaffold.py +0 -0
  100. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/pricing/__init__.py +0 -0
  101. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/pricing/bs.py +0 -0
  102. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/__init__.py +0 -0
  103. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/install.py +0 -0
  104. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/lint.py +0 -0
  105. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/models.py +0 -0
  106. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/parse.py +0 -0
  107. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/policy.py +0 -0
  108. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/skills/render.py +0 -0
  109. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/README.md +0 -0
  110. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/accounts.toml.example +0 -0
  111. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/journal.md +0 -0
  112. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/learnings.md +0 -0
  113. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
  114. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/wiki/index.md +0 -0
  115. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/wiki/log.md +0 -0
  116. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/wiki/overview.md +0 -0
  117. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/wiki/strategy.md +0 -0
  118. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/templates/wiki/underlying.md +0 -0
  119. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/wiki/__init__.py +0 -0
  120. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/wiki/lint.py +0 -0
  121. {thetabook-2.2.1 → thetabook-2.2.3}/src/thetabook/wiki/render.py +0 -0
@@ -0,0 +1,8 @@
1
+ # Revisions to skip in `git blame` — formatting-only, no behavior change.
2
+ #
3
+ # Enable locally with:
4
+ # git config blame.ignoreRevsFile .git-blame-ignore-revs
5
+ # (GitHub honors this file automatically.)
6
+
7
+ # style: apply ruff format across the repo
8
+ 8ab618e6a6e7a858116438e4c573e1358d1ff3d3
@@ -24,6 +24,9 @@ jobs:
24
24
  - name: Lint (ruff)
25
25
  run: uv run ruff check .
26
26
 
27
+ - name: Format (ruff)
28
+ run: uv run ruff format --check .
29
+
27
30
  - name: Type-check (mypy)
28
31
  run: uv run mypy .
29
32
 
@@ -50,6 +50,9 @@ jobs:
50
50
  - name: Lint (ruff)
51
51
  run: uv run ruff check .
52
52
 
53
+ - name: Format (ruff)
54
+ run: uv run ruff format --check .
55
+
53
56
  - name: Type-check (mypy)
54
57
  run: uv run mypy .
55
58
 
@@ -0,0 +1,5 @@
1
+ # thetabook — agent instructions
2
+
3
+ Whatever agent you are, the instructions for this repo live in **[CLAUDE.md](CLAUDE.md)**. It is the single source of truth: project conventions, tooling discipline, code standards, and the wiki operations contract. Read it before touching anything here.
4
+
5
+ @CLAUDE.md
@@ -3,6 +3,162 @@
3
3
  All notable changes to this project are recorded here. Format loosely follows
4
4
  [Keep a Changelog](https://keepachangelog.com). Dates are ISO 8601.
5
5
 
6
+ ## [Unreleased]
7
+
8
+ ## [2.2.3] — 2026-09-08
9
+
10
+ Housekeeping release, plus the last uncovered corner of Schwab's 7-day
11
+ token expiry. Three of these fixes broke real installs: every slash command
12
+ shelled out to a hardcoded `~/.local/bin/uv`, which doesn't exist on a
13
+ Homebrew install, so each one died with exit 127 before reaching the CLI;
14
+ `thetabook greeks` dropped the entire equity book whenever Schwab omitted
15
+ `marketPrice` (which is every share row); and `thetabook accounts` raised a
16
+ traceback instead of first-run guidance for any install with
17
+ `$THETABOOK_HOME` outside the checkout. The read paths now also say
18
+ something when the Schwab token is aging or dead, instead of quietly
19
+ serving yfinance data for a week. **1848 tests pass, ruff + mypy clean.**
20
+
21
+ ### Added
22
+
23
+ - **Schwab token-expiry handling now covers the read paths**
24
+ ([#48](https://github.com/subsriram/thetabook/issues/48)). Proactive +
25
+ reactive expiry handling existed only on the write path (`thetabook
26
+ refresh`); `prices` / `chains` / `dividends` / `bars` used a plain
27
+ `client_from_token_file` and cascaded to Massive/yfinance on auth failure.
28
+ Since an expired token is indistinguishable from a source outage in that
29
+ output, `price` / `greeks` / `evaluate` could run on yfinance for a full
30
+ week without saying so — and Schwab is the account-of-truth for real-time
31
+ quotes, broker Greeks, and dividends. Both gaps are now loud: the read
32
+ cascade warns once per resolved path when the cached token crosses
33
+ `[schwab] proactive_reauth_age_days` (reading the same `creation_timestamp`
34
+ field the write path's `easy_client` compares, with a file-mtime fallback
35
+ for hand-copied tokens), and every Schwab read failure that looks like a
36
+ revoked token appends `thetabook refresh --reauth` as the remedy.
37
+
38
+ The read paths deliberately **warn rather than re-auth**. They're called
39
+ from inside other commands — `greeks` fetches every underlying, `evaluate`
40
+ re-marks every leg — so an `easy_client` there would hijack a read-only
41
+ command with an OAuth browser flow and hang outright in a scripted run.
42
+ An aging token is still *used*: at 6 days it has ~24h of life left, and
43
+ degrading to yfinance a day early is the exact data-quality loss the
44
+ warning exists to prevent. The remedy paragraph is latched per process so
45
+ a dead token doesn't repeat it once per underlying; the per-call failure
46
+ line still prints every time.
47
+
48
+ - **Configurable assignment cost basis for `thetabook adjust --assign`**
49
+ ([#71](https://github.com/subsriram/thetabook/pull/71), closes
50
+ [#38](https://github.com/subsriram/thetabook/issues/38)). Cost-basis
51
+ attribution for shares acquired via short-put assignment is now selectable.
52
+ Default `effective` (strike − premium) is the IRS-correct basis for an
53
+ assigned written put (Pub 550: the premium reduces the share basis rather
54
+ than being separately recognized); `strike` mode is opt-in for reconciling
55
+ against a broker 1099-B that didn't auto-adjust, and adds the premium back
56
+ as a realized-income offset so total P&L is invariant either way. `StockLeg`
57
+ carries `assigned_strike` / `assigned_premium` / `basis_mode` so terminal,
58
+ markdown, and idea-file output all derive the basis from one source.
59
+ Configure via `[adjust] assign_cost_basis` in `personal/config.toml` or
60
+ per-run with `--assign-basis {effective,strike}`.
61
+
62
+ - **`[schwab] proactive_reauth_age_days` in `personal/config.toml`**
63
+ ([#84](https://github.com/subsriram/thetabook/pull/84), closes
64
+ [#49](https://github.com/subsriram/thetabook/issues/49)). The token age at
65
+ which `thetabook refresh` proactively re-runs the OAuth login flow is now a
66
+ config knob rather than a source literal, and **the default moves from 6.5
67
+ days to 6.0** — widening the margin under Schwab's 7-day refresh-token
68
+ expiry from 12 hours to 24. The old buffer was thin against clock skew,
69
+ server-side variance in when the cliff actually bites, and the gap between
70
+ one `refresh` and the next: refresh at day 6.4, come back 13 hours later,
71
+ and you crossed it before the check ever ran. Scoped to `[schwab]` rather
72
+ than to the command because 7 days is *Schwab's* policy, not ours — it can
73
+ change without a release of ours, and a second authenticated broker would
74
+ carry its own value. Anything that isn't a number in `0 < days < 7` —
75
+ out of range, quoted, or a stray `true` — falls back to the default and
76
+ warns once on the Schwab auth path; at or beyond Schwab's own expiry the
77
+ proactive re-auth could only fire after the token is already dead.
78
+
79
+ ### Fixed
80
+
81
+ - **Slash commands invoked `uv` at a hardcoded `~/.local/bin/uv`**
82
+ ([#83](https://github.com/subsriram/thetabook/pull/83)). That's the path
83
+ uv's own installer uses; on a Homebrew install uv lives at
84
+ `/opt/homebrew/bin/uv`, so every command that shelled out died with exit 127
85
+ before reaching the CLI. All 16 command files now invoke a bare `uv` and let
86
+ `PATH` resolve it. `src/thetabook/templates/skill.md` is fixed too — it
87
+ ships in the wheel, so it was seeding the same bad path into newly authored
88
+ skills. Skills already installed from an earlier registry version still
89
+ carry the old path and need `thetabook skills sync` or a re-install.
90
+
91
+ - **`thetabook accounts` crashed when `$THETABOOK_HOME` sat outside the
92
+ checkout** ([#74](https://github.com/subsriram/thetabook/pull/74)).
93
+ `ACCOUNTS_FILE.relative_to(REPO_ROOT)` raised `ValueError` on the first-run
94
+ guidance path for any pipx/uvx install or explicit override, turning
95
+ "nothing configured, here's how to fix it" into a traceback. Adds
96
+ `paths.display_path()` — relative when it can be, absolute otherwise, never
97
+ raising — and routes every `.relative_to(REPO_ROOT)` call site through it.
98
+ Also corrects stale `uv run accounts.py init` commands and repoints
99
+ `cmd_init`'s `cp` line at `TEMPLATES_DIR`, stale since templates moved under
100
+ `src/`.
101
+
102
+ - **`thetabook greeks` silently excluded the entire equity book**
103
+ ([#81](https://github.com/subsriram/thetabook/pull/81)). Schwab's positions
104
+ API leaves `marketPrice` at `0.0` on share-like rows, carrying the value in
105
+ `marketValue` instead — all 67 share positions in a live snapshot come back
106
+ that way. The `if symbol and qty != 0 and price:` guard in
107
+ `extract_equity_positions` therefore dropped every one, so a ~$1.04M long
108
+ equity book contributed zero delta and the output read as options-only with
109
+ no warning. `extract_stock_prices` had the same guard, and `aggregate_greeks`
110
+ builds its auto-fetch set from the (empty) equity map, so the fetch path
111
+ never gap-filled them either. A new `share_price()` helper derives
112
+ `abs(marketValue / quantity)` when `marketPrice` is absent, and both
113
+ extractors use it. Rows that still can't be priced now warn instead of
114
+ vanishing: their shares are shown but excluded from delta (no `marketPrice`,
115
+ no `marketValue`, and nothing fetchable means a worthless or delisted
116
+ holding, whose price doesn't move with anything), with `--prices` as the
117
+ override if that's wrong.
118
+ - **`thetabook positions` computed cushion off a snapshot-aged spot.** With
119
+ share rows now carrying a derived snapshot price, `resolve_spots`' fresh-
120
+ snapshot gap-fill-only path stopped live-fetching any underlying held as
121
+ shares — every covered call. Since `snapshot_is_stale` only means "predates
122
+ the last 4pm ET close", a snapshot pulled at 9:35am stays "fresh" all
123
+ session, so a 3:55pm cushion would have been computed on the morning price
124
+ with nothing in the output saying so. `resolve_spots` now takes the same
125
+ always-re-price-option-underlyings carve-out `greeks` got in 2.2.2, and
126
+ snapshot-sourced spots are flagged in the freshness note.
127
+ - **Equity positions held in more than one account were undercounted.**
128
+ `extract_equity_positions` assigned per row, so the last account seen
129
+ overwrote the others. Shares now accumulate across accounts.
130
+
131
+ ## [2.2.2] — 2026-06-11
132
+
133
+ A risk-correctness fix for `thetabook greeks`: option underlyings are now
134
+ always re-priced live, so a fresh-but-aging snapshot can no longer value a
135
+ near-ATM option on a stale price. Per-underlying price provenance is now
136
+ visible in the output. **1723 tests pass, ruff + mypy clean.**
137
+
138
+ ### Fixed
139
+
140
+ - **`thetabook greeks` valued option underlyings on stale snapshot prices**
141
+ ([#73](https://github.com/subsriram/thetabook/pull/73), closes #72). The
142
+ auto-fetch only refreshed prices when the snapshot was deemed *stale*; on a
143
+ *fresh* snapshot, option underlyings already present were used as-is — even
144
+ if hours old. Because option Greeks are far more price-sensitive than equity
145
+ delta (a ~$2 move on a near-ATM strike flips the ITM flag and swings
146
+ delta/theta), this risked materially wrong delta/theta/assignment readouts
147
+ mid-session. Option underlyings now always live-fetch when `fetch_missing`
148
+ is set, regardless of snapshot freshness; equity-only tickers keep the
149
+ gap-fill-only path (no slow 70+ ticker sweep). `--prices` overrides are now
150
+ preserved in *both* the fresh and stale paths — the stale path previously
151
+ clobbered them with the refetched price.
152
+
153
+ ### Added
154
+
155
+ - **Per-underlying price provenance in `thetabook greeks`**
156
+ ([#73](https://github.com/subsriram/thetabook/pull/73)). Each result entry
157
+ now carries `price` + `source`, the result gains `snapshot_fetched_at`, and
158
+ the rendered table gains `Price` / `Src` columns with a freshness label
159
+ (`live` / `prev-close` / `delayed` / `manual` / `snapshot <date>`) so a
160
+ Massive or snapshot fallback can no longer masquerade as a live quote.
161
+
6
162
  ## [2.2.1] — 2026-06-05
7
163
 
8
164
  Two pending medium-priority roadmap items (M24 expected-move / VRP, M20
@@ -31,28 +31,32 @@ The name nods to **theta**, the daily decay that quietly drives most options P&L
31
31
  ```
32
32
  thetabook/
33
33
  ├── CLAUDE.md # this file
34
- ├── docs/ # architecture.md, behaviors.md, skills.md, …
34
+ ├── docs/ # see docs/README.md — index + which file owns what
35
35
  ├── pyproject.toml # project metadata + [project.scripts] = thetabook
36
- ├── src/thetabook/ # the package
36
+ ├── src/thetabook/ # the package (has its own CLAUDE.md — layer boundaries)
37
37
  │ ├── pricing/ # pure math: Black-Scholes, Greeks aggregation
38
38
  │ ├── market/ # data sources + caches (Schwab → Massive → defeatbeta → yfinance)
39
- │ ├── analysis/ # derived signals: HV, TA indicators, scenario lookup
40
- │ ├── portfolio/ # snapshot I/O, diff, per-account rules
39
+ │ ├── analysis/ # derived signals: HV, TA, expected move, VRP, scenario lookup
40
+ │ ├── portfolio/ # snapshot I/O, CSV import, options book, per-account rules, scaffold
41
41
  │ ├── ideas/ # trade-idea workflow (manage / evaluate / adjust / roll)
42
42
  │ ├── wiki/ # personal/wiki/ lint + auto-rendered ideas roll-up
43
43
  │ ├── skills/ # author-time tooling + registry installer for skill files
44
- │ ├── cli/ # typer subcommands — one file per command
45
- │ └── *.py # shared building blocks: models, leg_parse, paths, log, config, cache, tickers
46
- ├── templates/ # canonical templates (idea.md, journal.md, skill.md, accounts.toml.example, wiki/*)
47
- ├── personal/ # PII data, gitignored
44
+ │ ├── templates/ # canonical templates, shipped inside the wheel (idea.md,
45
+ │ │ # journal.md, skill.md, *.toml.example, skills/, wiki/)
46
+ │ ├── cli/ # typer subcommands — one file per command (has its own CLAUDE.md)
47
+ │ └── *.py # shared building blocks: models, leg_parse, paths, log, config, cache, tickers, preflight
48
+ ├── personal/ # PII data, gitignored — this IS $THETABOOK_HOME in a dev checkout
48
49
  │ ├── snapshots/ # dated JSON snapshots of positions
49
50
  │ ├── journal/ # dated review notes
50
51
  │ ├── ideas/ # trade ideas, one file per idea
51
52
  │ ├── accounts.toml # per-account posture + rules
53
+ │ ├── config.toml # per-clone overrides ([market], [adjust], [schwab], [skills])
52
54
  │ └── wiki/ # LLM-maintained knowledge base — compounds over time
53
- └── tests/ # pytest suite — mirrors src/thetabook/
55
+ └── tests/ # pytest suite — mirrors src/thetabook/ (has its own CLAUDE.md)
54
56
  ```
55
57
 
58
+ **`personal/` vs `~/thetabook/`:** the same root, two install modes. `paths.thetabook_home()` resolves `$THETABOOK_HOME` → `<repo>/personal/` if it exists → the main repo's `personal/` when in a worktree → `~/thetabook/`. Paths written as `personal/snapshots/…` throughout these docs mean `$THETABOOK_HOME/snapshots/…`. Templates live *inside the package* (`src/thetabook/templates/`), not at the repo root — they must ship in the wheel or fresh installs break.
59
+
56
60
  For the rationale behind the layers, the data-flow diagram, the source cascade, and a "where to add what" table, see [docs/architecture.md](docs/architecture.md). It's the file-level + design-decision reference; this tree is just the orientation map.
57
61
 
58
62
  ## Running things
@@ -67,7 +71,7 @@ thetabook positions # effective options book
67
71
  thetabook evaluate <id> # P&L, PoP, Greeks for an idea (live re-marks)
68
72
  thetabook chain AAPL 2026-06-20 --type put # browse a chain
69
73
  thetabook ideas record-fill <id> --price 2.95 --qty -1 # status transitions go through the CLI
70
- uv run pytest # tests; ruff and mypy are the other two gates
74
+ uv run pytest # tests; ruff check, ruff format --check, mypy are the other three gates
71
75
  ```
72
76
 
73
77
  The runtime behaviors that govern these commands — source cascades and retries, ticker aliases, Schwab auth, snapshot freshness, mark mode, Greeks source, earnings/dividends handling, per-account rules, and the idea-lifecycle CLI/Edit boundary — live in [docs/behaviors.md](docs/behaviors.md). Read it before debugging surprising output from `evaluate`, `adjust`, `greeks`, or `accounts`.
@@ -81,6 +85,7 @@ The skills CLI (`thetabook skills lint/show/install/installed/sync/remove/render
81
85
  - **Option contracts**: reference as `TICKER YYYY-MM-DD STRIKE C/P` (e.g. `AAPL 2026-01-16 180 C`).
82
86
  - **Ideas** use frontmatter: `status: proposed | watching | opened | closed | rejected`, plus `opened_at`, `closed_at`, `thesis`, `outcome`.
83
87
  - **Journal entries** have sections: `Positions reviewed`, `Discussion`, `Ideas generated`, `Learnings`.
88
+ - **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".
84
89
 
85
90
  ## Wiki — the compounding knowledge layer
86
91
 
@@ -155,7 +160,7 @@ Use these commands:
155
160
 
156
161
  # Code standards
157
162
 
158
- Three gates a change must pass before it lands: `uv run pytest`, `uv run ruff check .`, `uv run mypy .`. Run them locally; the same set is what reviewers will run.
163
+ Four gates a change must pass before it lands: `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy .`. Run them locally; the same set is what CI and reviewers will run.
159
164
 
160
165
  ## Pydantic models — load/save boundaries get validated
161
166
 
@@ -173,7 +178,7 @@ When a function still needs to accept either a dict (test fixture, ad-hoc caller
173
178
 
174
179
  ## Stderr logging — use the `log` helper, not `print(..., file=sys.stderr)`
175
180
 
176
- All stderr output goes through [log.py](log.py):
181
+ All stderr output goes through [log.py](src/thetabook/log.py):
177
182
 
178
183
  - `log.warn(msg)` → `Warning: {msg}` — call succeeded but something is off (stale snapshot, retry, fallback source)
179
184
  - `log.error(msg)` → `Error: {msg}` — something failed; usually followed by `sys.exit(1)`
@@ -190,7 +195,7 @@ Configuration lives in `pyproject.toml`. Active rule packs: `E, W, F, I, B, UP,
190
195
  - `SIM108` — ternary suggestion fights readability for `np.maximum(...) if call else np.maximum(...)` style branches.
191
196
  - `E501` line length, `E741` ambiguous names (`l` = "leg"), `B008` (function calls in defaults are fine for the `sys.stderr` pattern).
192
197
 
193
- `ruff format` is the formatter — drop-in black replacement, no separate dep. Run before committing.
198
+ `ruff format` is the formatter — drop-in black replacement, no separate dep. Run `uv run ruff format .` before committing; CI enforces it via `ruff format --check .`. Note the formatter re-joins hand-wrapped lines out to `line-length = 120`, so don't hand-wrap for style — let the formatter decide.
194
199
 
195
200
  ## Mypy
196
201
 
@@ -200,7 +205,7 @@ When mypy flags something, prefer fixing the underlying type over adding `# type
200
205
 
201
206
  ## Test layout
202
207
 
203
- Tests live in `tests/` and mirror the package tree (`tests/pricing/`, `tests/market/`, `tests/portfolio/`, `tests/ideas/`). Top-level utility tests (`test_log.py`, `test_models.py`, `test_leg_parse.py`, `test_config.py`, `test_cache.py`, `test_factories.py`) stay flat. New tests go alongside the module they cover.
208
+ Tests live in `tests/` and mirror the package tree (`tests/pricing/`, `tests/market/`, `tests/analysis/`, `tests/portfolio/`, `tests/ideas/`, `tests/wiki/`, `tests/skills/`, `tests/cli/`). Top-level utility tests (`test_log.py`, `test_models.py`, `test_leg_parse.py`, `test_config.py`, `test_cache.py`, `test_paths.py`, `test_preflight.py`, `test_tickers.py`, `test_factories.py`) stay flat, alongside `test_cli.py` — the registration smoke test that asserts every subcommand is wired into the root app. New tests go alongside the module they cover. See [tests/CLAUDE.md](tests/CLAUDE.md) for fixture conventions.
204
209
 
205
210
  Shared factories in `tests/conftest.py`:
206
211
 
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: thetabook
3
- Version: 2.2.1
3
+ Version: 2.2.3
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