FinTech Tools Container — v0.9

## PDF viewing — bookokrat

PDFs (and EPUBs) open in **bookokrat**, a terminal reader that draws inline via
the kitty graphics protocol — which **ghostty** renders straight over SSH, so no
X11/XQuartz and no Mac-side helper are involved. Synctex works both ways because
Neovim and bookokrat run on the same node.

- **Binary** — baked into the image at `/usr/local/bin/bookokrat` (Dockerfile Stage 5f).
- **Wrappers** — synced to `~/.local/bin/` by `sync_configs.sh` (on `$PATH` inside the container):
  - `bookokrat-split` — opens a PDF in a **half split beside the caller** (forwards
    `$NVIM` for inverse search). Opening a second PDF respawns that same reader pane
    rather than splitting again; opening one already on screen just jumps to it.
    Panes carry the pane option `@bkfile`, which is how both are recognised.
  - `bookokrat-forward` — VimTeX forward search (`<localleader>lv`): jumps an open instance, or launches one.
  - `bookokrat-inverse` — synctex inverse search: `gd` / Ctrl-click in the PDF jumps Neovim to the source line.
  - `tmux-kitty-image-gc` — takes the page **off the screen** when you switch away
    from the reader or quit it (bookokrat#179). Under ghostty bookokrat draws a
    classic kitty placement, which **tmux holds no cell for**, so a window switch
    repaints the text and leaves the page painted over the window you switched to.
    This writes the kitty delete escape straight to the client tty — around tmux's
    pane-visibility rules, which would swallow it — then sends `C-l` to any reader
    still on screen. Deletes are targeted at z-index `-1` / image id `1`, where
    bookokrat draws and yazi does not, so a neighbouring preview survives. Wired in
    `configs/tmux/tmux.conf` (`session-window-changed`, `client-session-changed`)
    and appended to the reader's own command line by `bookokrat-split`. The repaint
    on return costs ~1-1.5s here (remote render + re-upload) against ~100-300ms on
    the Mac — that is the SSH page floor.
    Only a reader that is **visible but not focused** actually leaks: with the
    cursor in the reader, bookokrat tears its own placements down on focus-out and
    this script finds nothing to do. That is why the bug reads as intermittent —
    it depends on which pane had the cursor. `focus-events on` is therefore
    load-bearing for images, not just for nvim. Measured 2026-09-07.
- **One file each, shared with the Mac.** `sync_configs.sh` prefers the LIVE
  `~/.local/bin/` copy over the repo-root snapshot, so an edit made live must be
  copied back to the repo **and** an edit made only in the repo is discarded by the
  next sync. Platform differences live inside the scripts (`uname -s`), which is how
  `bookokrat-split` picks Homebrew's binary on the Mac and `/usr/local/bin/bookokrat`
  here.
- **Retired: the `~/.local/bin/override/bookokrat` wrapper** (and its `tmux` shim
  under `~/.local/libexec/`). It answered bookokrat's outer-terminal probe with
  `kitty` to force the Unicode-placeholder anchor path back on. Ghostty 1.3.1 does
  not implement the relative placements that path emits (kitty keys `P=`/`Q=`) — it
  drops them and paints the page at the cursor, i.e. on top of yazi, leaving the
  reader's pane empty. Removed 2026-09-04; it was never viable here in any case,
  the anchor path being implemented only over SHM transmission while the shm object
  lives in `/dev/shm` on the compute node and ghostty runs on the Mac. Do not
  reintroduce it — `tmux-kitty-image-gc` is the supported fix.
- **Config** — `configs/bookokrat/` → `~/.config/bookokrat/` (inverse search wired via `synctex_editor`).
- **Wiring** — VimTeX (`configs/nvim/lua/plugins/vimtex.lua`, `general` viewer), yazi
  (`*.pdf`/`*.epub` opener), and `vim.ui.open` / snacks-explorer
  (`pdf_open.lua`, `snacks.lua`) all route PDFs to bookokrat.

### Test

After SSH'ing in via `./connect_nvim.sh`, from inside the container (in tmux):

```bash
bookokrat-split /work/g/gson/some.pdf   # opens in a new tmux split