Document YTD realized income tax and paid config field

Author: bufdev

book/src/commands/holding-value.md

@@ -22,6 +22,21 @@ LTCG Tax (28.0%):  $27,654.32
 Total Tax:       $32,691.35
 
 After-Tax Value: $1,201,876.54
+
+YTD Realized Income Tax:
+
+Dividends:              $23,456.78
+Dividend Tax (53.5%):   $12,556.38
+Interest:               $5,678.90
+Interest Tax (53.5%):    $3,039.84
+Realized STCG:           $8,901.23
+STCG Tax (40.8%):        $3,631.70
+Realized LTCG:          $45,678.90
+LTCG Tax (28.0%):       $12,790.09
+
+Total Tax Owed:         $32,018.01
+Tax Paid:               $20,000.00
+Tax Remaining:          $12,018.01
 ```
 
 ## Computation
@@ -48,6 +63,36 @@ The formulas are:
 
 Tax-exempt holdings (RRSP, TFSA, additions with `tax_exempt: true`) contribute zero to STCG and LTCG, so they do not affect the tax computation. Gains are taxed and losses reduce taxes (the tax amount can be negative).
 
+## YTD Realized Income Tax
+
+This section shows estimated taxes on realized income and capital gains for the current calendar year (January 1 through today). It uses the full transaction history — dividends, interest, withholding tax, and realized sales — filtered to the current year, converted to the `--base-currency`.
+
+Tax rates are read from the `taxes` section of `ibctl.yaml`:
+
+```yaml
+taxes:
+  stcg: 0.408
+  ltcg: 0.28
+  dividend_tax: 0.5353
+  interest_tax: 0.5353
+  paid:
+    USD: "50000"
+```
+
+| Value | Formula |
+|-------|---------|
+| Dividends | Sum of DIV {BASE} across all YTD DIVIDEND and WHT transactions |
+| Interest | Sum of INT {BASE} across all YTD INTEREST transactions |
+| Realized STCG | Sum of STCG {BASE} across all YTD SELL transactions |
+| Realized LTCG | Sum of LTCG {BASE} across all YTD SELL transactions |
+| Dividend Tax | Dividends * `taxes.dividend_tax` rate |
+| Interest Tax | Interest * `taxes.interest_tax` rate |
+| STCG Tax | Realized STCG * `taxes.stcg` rate |
+| LTCG Tax | Realized LTCG * `taxes.ltcg` rate |
+| Total Tax Owed | Dividend Tax + Interest Tax + STCG Tax + LTCG Tax |
+| Tax Paid | Sum of `taxes.paid` amounts, converted to base currency |
+| Tax Remaining | Total Tax Owed - Tax Paid |
+
 ## Flags
 
 | Flag | Default | Description |

book/src/commands/overview.md

@@ -34,7 +34,7 @@ All holding commands accept `--base-currency` (default `USD`) to convert values
 | `ibctl holding lot list` | List individual FIFO tax lots with per-lot cost basis and P&L |
 | `ibctl holding category list` | Aggregate holdings by category with market value and P&L |
 | `ibctl holding geo list` | Aggregate holdings by geographic classification with market value and P&L |
-| `ibctl holding value` | Display portfolio value with estimated tax impact and after-tax value |
+| `ibctl holding value` | Display portfolio value with estimated unrealized and YTD realized tax impact |
 
 ## Transaction commands
 

book/src/configuration.md

@@ -49,11 +49,16 @@ cash:
   CAD: "-5000.00"
   USD: "1200.50"
 
-# Capital gains tax rates for portfolio value computation.
-# Optional. Used by the "holding value" command to estimate after-tax portfolio value.
+# Tax rates and payment tracking for portfolio tax computation.
+# Optional. Used by "holding value" and "holding overview" commands.
 taxes:
   stcg: 0.408
   ltcg: 0.28
+  dividend_tax: 0.5353
+  interest_tax: 0.5353
+  paid:
+    USD: "50000"
+    CAD: "30000"
 
 # Manually added trades from non-IBKR brokers.
 # Optional. See the Additions chapter for full details.
@@ -120,14 +125,17 @@ Use negative values to subtract (e.g., if you have committed cash that should no
 
 ### `taxes`
 
-**Optional.** Capital gains tax rates used by the `holding value` command to estimate after-tax portfolio value.
+**Optional.** Tax rates and payment tracking used by the `holding value` and `holding overview` commands.
 
 | Field | Description | Example |
 |-------|-------------|---------|
 | `stcg` | Short-term capital gains tax rate (decimal, e.g., 0.408 = 40.8%) | `0.408` |
 | `ltcg` | Long-term capital gains tax rate (decimal, e.g., 0.28 = 28%) | `0.28` |
+| `dividend_tax` | Tax rate on dividend income (decimal, e.g., 0.5353 = 53.53%) | `0.5353` |
+| `interest_tax` | Tax rate on interest and bond coupon income (decimal, e.g., 0.5353 = 53.53%) | `0.5353` |
+| `paid` | Map of currency codes to total tax payments already made this year as decimal strings | `USD: "50000"` |
 
-If not set, both rates default to zero and the `holding value` command shows no tax impact.
+If tax rates are not set, they default to zero and no tax impact is shown. The `paid` map tracks estimated tax payments (quarterly, installments, etc.) so the commands can show how much tax remains after payments. When viewing in a different `--base-currency`, paid amounts are converted using the most recent available FX rate.
 
 ### `additions`