feat: add --securities-on-date flag for historical portfolio reconstruction

Reconstructs securities positions as of any historical date using trade
history FIFO and Yahoo Finance historical close prices. Positions are
rebuilt from the full trade history filtered to the target date, with
cached FX rates for currency conversion.

New package ibctlhistorical provides FilterTradesByDate, BuildSnapshot,
and ApplyHistoricalPrices. GetHistoricalClose added to the Yahoo Finance
client. FetchHistoricalPrices added to ibctlrealtime for symbol mapping.

Commands with --securities-on-date: holding list, category list, geo
list, overview, value, lot list, possible-sale list. The value command
scopes YTD realized gains to the target date's year.

Flag validation and data loading branching abstracted into
ValidateSecuritiesOnDate and LoadHoldingsDataForFlags in ibctlcmd.

BuildPositionMap now accepts a symbolTypes map from config for accurate
bond identification regardless of trade-derived AssetCategory values.

Limitations documented in holding-list.md:
- Cash excluded (trade history lacks deposit/withdrawal data)
- Bonds and other Yahoo-unresolvable securities excluded with warnings
- International tickers require realtime_symbols config mapping
- Config addition prices (HOUSE) not used as fallback
- FX rates depend on cache from prior downloads

Author: bufdev

.gitignore

@@ -1,2 +1,3 @@
 /.tmp/
 /book/book/
+/plans/

README.md

@@ -62,7 +62,7 @@ ibctl transaction list --from 20250101 --to 20251231 --base-currency USD
 | `ibctl transaction list` | List all transactions (buys, sells, dividends, interest, WHT, etc.) chronologically |
 | `ibctl realized-sale list` | List realized security sales with FIFO lot matching for tax reporting |
 
-All commands accept `--dir` to specify the ibctl directory (defaults to `.`). All holding and transaction commands accept `--base-currency` (default `USD`) to convert values to a different currency. Holding commands accept `--realtime` to fetch current stock prices and FX rates from Yahoo Finance on-demand. For international symbols where IBKR and Yahoo symbols differ, add mappings to `realtime_symbols` in `ibctl.yaml`. Use `--help` on any command for detailed documentation.
+All commands accept `--dir` to specify the ibctl directory (defaults to `.`). All holding and transaction commands accept `--base-currency` (default `USD`) to convert values to a different currency. Holding commands accept `--realtime` to fetch current stock prices and FX rates from Yahoo Finance on-demand. For international symbols where IBKR and Yahoo symbols differ, add mappings to `realtime_symbols` in `ibctl.yaml`. Holding commands accept `--securities-on-date YYYYMMDD` to reconstruct securities positions as of a historical date by replaying trades and fetching historical close prices from Yahoo Finance. The `--securities-on-date` flag is mutually exclusive with `--realtime` and `--download`. Use `--help` on any command for detailed documentation.
 
 ## Tax Reporting
 

book/src/commands/category-list.md

@@ -1,7 +1,7 @@
 # category list
 
 ```
-ibctl category list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--geo GEO] [--base-currency CURRENCY]
+ibctl category list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--securities-on-date DATE] [--geo GEO] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by category and displays each category's market value, percentage of net liquidation value, and capital gains breakdown.
@@ -39,5 +39,6 @@ Use `--geo` to filter holdings to a single geographic classification before aggr
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--geo` | (all) | Filter by geographic classification before aggregating (e.g., `US`, `INTL`) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |

book/src/commands/geo-list.md

@@ -1,7 +1,7 @@
 # geo list
 
 ```
-ibctl geo list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--category CATEGORY] [--base-currency CURRENCY]
+ibctl geo list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--securities-on-date DATE] [--category CATEGORY] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by geographic classification and displays each geo's market value, percentage of net liquidation value, and capital gains breakdown.
@@ -39,5 +39,6 @@ Use `--category` to filter holdings to a single category before aggregating by g
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--category` | (all) | Filter by category before aggregating (e.g., `EQUITY`, `FIXED_INCOME`) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |

book/src/commands/holding-list.md

@@ -1,7 +1,7 @@
 # holding list
 
 ```
-ibctl holding list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--base-currency CURRENCY]
+ibctl holding list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--securities-on-date DATE] [--base-currency CURRENCY]
 ```
 
 Shows combined positions across all accounts. Positions are computed via FIFO tax lot matching with weighted average cost basis, then verified against IBKR-reported positions.
@@ -68,6 +68,21 @@ Use `--realtime` to fetch current market prices and FX rates from Yahoo Finance
 
 For international symbols where IBKR and Yahoo Finance symbols differ (e.g., Canadian equities), add symbol mappings to the `realtime_symbols` section of your config. Real-time data is not cached — each run fetches fresh prices from Yahoo Finance.
 
+## Historical portfolio reconstruction
+
+Use `--securities-on-date YYYYMMDD` to reconstruct securities positions as of a historical date. Positions are rebuilt by replaying all trades up to that date using FIFO lot computation. Historical close prices are fetched from Yahoo Finance; FX rates use cached historical data.
+
+The flag is mutually exclusive with `--realtime` and `--download`.
+
+**Limitations:**
+
+- **Cash excluded.** Trade history does not track deposits, withdrawals, or FX conversions. Cash positions (USD, CAD) and config cash adjustments are omitted from the output.
+- **Bonds and other Yahoo-unresolvable securities excluded.** Yahoo Finance does not quote individual corporate bonds. Any security that Yahoo cannot price is excluded with a warning. No config fallback prices or cost basis estimates are used — every price in the output is a real historical market price.
+- **International tickers require `realtime_symbols` mapping.** Tickers where IBKR and Yahoo symbols differ (e.g., HK-listed stocks) must be mapped in `ibctl.yaml` under `realtime_symbols`, the same mapping used by `--realtime`.
+- **Addition prices are not date-aware.** Config additions (like HOUSE) that Yahoo cannot price are excluded. The config `last_price` is a static current estimate, not a historical value.
+- **FX rates depend on cache.** Historical FX rates come from the frankfurter.dev/Bank of Canada cache. Dates before the first `ibctl download` may have missing rates.
+- **Position verification suppressed.** The normal FIFO-vs-IBKR verification is not meaningful for reconstructed positions and may produce spurious warnings.
+
 ## Flags
 
 | Flag | Default | Description |
@@ -76,4 +91,5 @@ For international symbols where IBKR and Yahoo Finance symbols differ (e.g., Can
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |

book/src/commands/lot-list.md

@@ -1,7 +1,7 @@
 # lot list
 
 ```
-ibctl lot list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--symbol SYMBOL] [--base-currency CURRENCY]
+ibctl lot list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--securities-on-date DATE] [--symbol SYMBOL] [--base-currency CURRENCY]
 ```
 
 Lists individual FIFO tax lots. Unlike `holding list`, which aggregates positions by symbol, this command shows each tax lot separately with its own open date, quantity, and cost basis.
@@ -52,5 +52,6 @@ The table output includes a totals row summing P&L {BASE}, STCG {BASE}, LTCG {BA
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--symbol` | (all) | Filter to a specific symbol. Omit to show all symbols. |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |

book/src/commands/overview.md

@@ -59,4 +59,5 @@ Several flags appear across multiple commands:
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--download` | `false` | Download fresh data before displaying results |
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities). Available on holding commands (`holding list`, `lot list`, `category list`, `geo list`, `possible-sale list`, `value`). Mutually exclusive with `--realtime` and `--download`. |
 | `--base-currency` | `USD` | Base currency for value/P&L conversion (case-insensitive, e.g., `USD`, `CAD`). Available on all holding and transaction commands. |

book/src/commands/possible-sale-list.md

@@ -1,7 +1,7 @@
 # possible-sale list
 
 ```
-ibctl possible-sale list [--dir DIR] [--format FORMAT] [--download] [--realtime]
+ibctl possible-sale list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--securities-on-date DATE]
     [--safe | --safe-excluded | --unsafe] [--separate-accounts] [--base-currency CURRENCY]
 ```
 
@@ -125,6 +125,7 @@ ibctl possible-sale list --safe --realtime --base-currency CAD --format csv
 | `--format` | `table` | Output format: `table`, `csv`, or `json` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--safe` | `false` | Show only positions safe to sell (loss or LTCG, respecting FIFO and exclusions) |
 | `--safe-excluded` | `false` | Show only positions excluded from the safe view |
 | `--unsafe` | `false` | Show only positions with STCG exposure (inverse of safe) |

book/src/commands/value.md

@@ -1,7 +1,7 @@
 # value
 
 ```
-ibctl value [--dir DIR] [--download] [--realtime] [--base-currency CURRENCY]
+ibctl value [--dir DIR] [--download] [--realtime] [--securities-on-date DATE] [--base-currency CURRENCY]
 ```
 
 Displays the total portfolio value, unrealized short-term and long-term capital gains, estimated tax liability, and after-tax portfolio value.
@@ -100,4 +100,5 @@ taxes:
 | `--dir` | `.` | The ibctl directory containing `ibctl.yaml` |
 | `--download` | `false` | Download fresh data before displaying |
 | `--realtime` | `false` | Fetch real-time stock quotes and FX rates from Yahoo Finance |
+| `--securities-on-date` | (today) | Show securities positions as of this date (YYYYMMDD format, excludes cash and unpriced securities) |
 | `--base-currency` | `USD` | Base currency for value conversion (case-insensitive, e.g., `USD`, `CAD`) |

cmd/ibctl/internal/command/category/categorylist/categorylist.go

@@ -29,6 +29,8 @@ const (
 	baseCurrencyFlagName = "base-currency"
 	// realtimeFlagName is the flag name for fetching real-time quotes and FX rates.
 	realtimeFlagName = "realtime"
+	// securitiesOnDateFlagName is the flag name for viewing securities positions as of a historical date.
+	securitiesOnDateFlagName = "securities-on-date"
 )
 
 // NewCommand returns a new category list command.
@@ -70,6 +72,8 @@ type flags struct {
 	BaseCurrency string
 	// Realtime fetches real-time quotes and FX rates from Yahoo Finance.
 	Realtime bool
+	// SecuritiesOnDate is the historical date in YYYYMMDD format (empty means current).
+	SecuritiesOnDate string
 }
 
 func newFlags() *flags {
@@ -83,15 +87,22 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	flagSet.StringVar(&f.Geo, geoFlagName, "", "Filter by geo (e.g., US, INTL)")
 	flagSet.StringVar(&f.BaseCurrency, baseCurrencyFlagName, "USD", "Base currency for value conversion (e.g., USD, CAD)")
 	flagSet.BoolVar(&f.Realtime, realtimeFlagName, false, "Fetch real-time quotes and FX rates from Yahoo Finance")
+	// Register --securities-on-date for historical securities position reconstruction.
+	flagSet.StringVar(&f.SecuritiesOnDate, securitiesOnDateFlagName, "", "Show securities positions as of this date (YYYYMMDD format, excludes cash)")
 }
 
 func run(ctx context.Context, container appext.Container, flags *flags) error {
 	format, err := cliio.ParseFormat(flags.Format)
 	if err != nil {
 		return appcmd.NewInvalidArgumentError(err.Error())
 	}
-	// Load data through the common pipeline (config, merge, FX, optional download/realtime).
-	data, err := ibctlcmd.LoadHoldingsData(ctx, container, flags.Download, flags.Realtime, flags.BaseCurrency)
+	// Validate --securities-on-date is not combined with --realtime or --download.
+	if err := ibctlcmd.ValidateSecuritiesOnDate(flags.SecuritiesOnDate, flags.Realtime, flags.Download); err != nil {
+		return appcmd.NewInvalidArgumentError(err.Error())
+	}
+	// Load data through the common pipeline, branching on --securities-on-date.
+	var data *ibctlcmd.HoldingsData
+	data, err = ibctlcmd.LoadHoldingsDataForFlags(ctx, container, flags.Download, flags.Realtime, flags.BaseCurrency, flags.SecuritiesOnDate)
 	if err != nil {
 		return err
 	}