From 3f48a5b38c590472c2557d639bb99f913c446d0f Mon Sep 17 00:00:00 2001 From: Emil Lerch Date: Thu, 25 Jun 2026 22:20:32 -0700 Subject: [PATCH] update docs for chart changes --- TODO.md | 24 +++--------------------- docs/guides/snapshots-and-history.md | 5 +++-- docs/reference/cli/history.md | 6 +++++- docs/reference/cli/index.md | 1 + docs/reference/cli/quote.md | 10 ++++++++-- src/commands/history.zig | 3 ++- src/commands/quote.zig | 3 ++- src/main.zig | 5 ++++- 8 files changed, 28 insertions(+), 29 deletions(-) diff --git a/TODO.md b/TODO.md index 83c4a3f..aabc028 100644 --- a/TODO.md +++ b/TODO.md @@ -81,28 +81,10 @@ ranking; unlabeled items are "someday, if the mood strikes." ## `--export-chart` follow-ups - priority LOW -V1 of `--export-chart ` shipped for `quote` and `projections` -(default bands mode only). Several adjacent surfaces still don't -have PNG export and were deferred: +V1 of `--export-chart ` shipped for `quote`, `projections` +(default bands mode only), and `history`. Several adjacent surfaces +still don't have PNG export and were deferred: -- **`history --export-chart`.** The `history` command renders a - single-series braille chart of portfolio value over time - (synthesized into `Candle` records and fed to - `format.computeBrailleChart`). It doesn't share the z2d - pipeline that `quote` (`tui/chart.zig`) and `projections` - (`tui/projection_chart.zig`) use. To export, options: - - **A.** Pipe the synthesized candles through - `tui/chart.zig`'s `renderChart` - but that draws Bollinger - Bands and an RSI panel, both meaningless on a portfolio- - value series. - - **B.** Add a minimal "single-series line chart" z2d - renderer (a slimmed-down `projection_chart.zig` without - bands). ~150 lines. Same renderToSurface shape so PNG - export is trivial after. - - **C.** Skip it permanently; the braille chart is fine for - what `history` is. Document as "not exportable". - B is the right answer if PNG export of the history chart is - ever requested. - **`projections --convergence` / `--return-backtest`.** Both render forecast-evaluation charts via `tui/forecast_chart.zig`. Not refactored to expose a `renderToSurface` seam yet - diff --git a/docs/guides/snapshots-and-history.md b/docs/guides/snapshots-and-history.md index 7d06d97..d25141d 100644 --- a/docs/guides/snapshots-and-history.md +++ b/docs/guides/snapshots-and-history.md @@ -83,8 +83,9 @@ there.) ## 3. Review the timeline with `history` Run [`zfin history`](../reference/cli/history.md) with no symbol for the -portfolio-value timeline: rolling-window changes, a braille chart, and -a recent-snapshots table. +portfolio-value timeline: rolling-window changes, a chart (an inline +Kitty image when your terminal supports it, else braille), and a +recent-snapshots table. ```bash ZFIN_HOME=examples/post-retirement zfin history diff --git a/docs/reference/cli/history.md b/docs/reference/cli/history.md index d0ac6b8..97f86a7 100644 --- a/docs/reference/cli/history.md +++ b/docs/reference/cli/history.md @@ -28,9 +28,13 @@ Price History for VTI (last 30 days) ## Portfolio mode With no symbol, reads your `history/*-portfolio.srf` snapshots and -renders rolling-window returns, a braille chart, and a recent-snapshots +renders rolling-window returns, a chart, and a recent-snapshots table. (Build that history with [`snapshot`](snapshot.md).) +The chart renders as an inline Kitty image when your terminal supports +it, falling back to braille otherwise. Force a mode with the global +[`--chart`](index.md) flag (`auto` / `braille` / `WxH`). + | Flag | Effect | |-----------------------|-------------------------------------------------| | `--since ` | Earliest as-of date (inclusive). | diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index d1fb705..aaa2cac 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -73,6 +73,7 @@ subcommand: | `--refresh-data=` | Cache freshness policy. `auto` (default) respects TTLs; `force` re-fetches everything; `never` is offline. See [offline guide](../../guides/offline-and-refresh.md). | | `-p, --portfolio ` | Portfolio file or glob (repeatable; default `portfolio*.srf`). Resolved against `ZFIN_HOME` when set, else the current directory. Quote globs to prevent shell expansion. | | `-w, --watchlist ` | Watchlist file (default `watchlist.srf`). | +| `--chart ` | Inline chart graphics for `history` / `quote` / `projections`. `auto` (default) renders a Kitty image when the terminal supports it, else braille; `WxH` forces Kitty at that resolution. | ```bash zfin --no-color --refresh-data=never -p 'portfolio_*.srf' analysis diff --git a/docs/reference/cli/quote.md b/docs/reference/cli/quote.md index 5b8a17a..9893a03 100644 --- a/docs/reference/cli/quote.md +++ b/docs/reference/cli/quote.md @@ -8,10 +8,16 @@ Usage: zfin quote ``` Prints the last price, the day's open/high/low, volume, and the -day-over-day change, followed by a 20-day chart. Quotes come from Yahoo +day-over-day change, followed by a price chart of the last 60 candles +and a table of the last 20 trading days. Quotes come from Yahoo (TwelveData fallback) and are **never cached** -- so this command needs network access and does nothing useful in `--refresh-data=never` mode. +The inline chart renders as a Kitty image (price + Bollinger bands + +volume + RSI) when your terminal supports it, falling back to a braille +price line otherwise. Force a mode with the global +[`--chart`](index.md) flag (`auto` / `braille` / `WxH`). + Supports `--export-chart ` to render the chart as a 1920x1080 PNG instead of text (see [export charts](../../guides/offline-and-refresh.md) and the projections page). @@ -32,7 +38,7 @@ SPY $746.74 (close) Volume: 80,875,657 Change: +$5.78 (+0.78%) - ... (20-day braille chart) + ... (60-candle price chart -- inline Kitty image, or braille) ``` ## See also diff --git a/src/commands/history.zig b/src/commands/history.zig index cfae4d7..dfb51f8 100644 --- a/src/commands/history.zig +++ b/src/commands/history.zig @@ -79,7 +79,8 @@ pub const meta: framework.Meta = .{ \\shows the last 30 trading days of candles for that symbol. \\Portfolio mode (no positional, optionally with flags) reads \\`history/*-portfolio.srf` snapshots and renders rolling-windows - \\returns + a braille chart + a recent-snapshots table. + \\returns + a chart (an inline Kitty image when the terminal + \\supports it, braille otherwise) + a recent-snapshots table. \\ \\Portfolio-mode flags: \\ --since earliest as-of date (inclusive) diff --git a/src/commands/quote.zig b/src/commands/quote.zig index 4fb17e3..a9153ca 100644 --- a/src/commands/quote.zig +++ b/src/commands/quote.zig @@ -28,7 +28,8 @@ pub const meta: framework.Meta = .{ \\Usage: zfin quote [--export-chart ] \\ \\Show the latest real-time quote for a symbol (Yahoo / TwelveData) - \\plus a braille price chart of the last 60 candles and a table + \\plus a price chart of the last 60 candles (an inline Kitty image + \\when the terminal supports it, braille otherwise) and a table \\of the last 20 trading days. \\ \\If real-time fetch fails, falls back to the cached close. The diff --git a/src/main.zig b/src/main.zig index dee9808..d9c1592 100644 --- a/src/main.zig +++ b/src/main.zig @@ -88,12 +88,15 @@ const usage_footer = \\ the same directory as the first resolved \\ portfolio file. \\ -w, --watchlist Watchlist file (default: watchlist.srf) + \\ --chart Inline chart graphics for history / quote / + \\ projections: auto (Kitty image when the + \\ terminal supports it, else braille), + \\ braille, or WxH (Kitty at that resolution) \\ \\Interactive command options: \\ -s, --symbol Pre-load a symbol and open on the \\ Quote tab. Without this flag, the TUI \\ opens on the Portfolio tab. - \\ --chart Chart graphics: auto, braille, or WxH \\ --default-keys Print default keybindings \\ --default-theme Print default theme \\