gloomberb 0.13.3 → 0.14.1

package/README.md

@@ -12,6 +12,8 @@ Desktop app for macOS and Windows. Terminal UI for macOS, Linux, and Windows.
  · 
 <a href="#install"><strong>Install the TUI</strong></a>
 &nbsp;&middot;&nbsp;
+<a href="https://term.gloom.sh"><strong>Open in browser</strong></a>
+&nbsp;&middot;&nbsp;
 <a href="README.zh-CN.md">简体中文</a>
 
 <br />
@@ -21,349 +23,80 @@ Desktop app for macOS and Windows. Terminal UI for macOS, Linux, and Windows.
 
 </div>
 
-## Desktop App or TUI?
-
-Gloomberb has two ways in:
-
-| Surface | Best for | How it runs |
-|---------|----------|-------------|
-| Desktop app | A polished app window, pop-out panes, OS shortcuts, and built-in updates | Published for macOS and Windows. It also installs a `gloomberb` terminal command for the TUI. |
-| Terminal UI | Fast keyboard workflows inside your terminal, SSH/dev boxes, Linux machines, and script-friendly setups | Runs with `gloomberb` on macOS, Linux, and Windows. |
-| Browser app | The shared DOM interface without an install | Open [term.gloom.sh](https://term.gloom.sh). |
-
-The desktop app and TUI share the full command language and plugin system. The browser app uses the same official DOM renderer and layout with a reviewed browser plugin catalog.
-
-## Browser App
+- **Research companies:** quotes, charts, financials, filings, options, and analyst ratings.
+- **Follow markets:** news, global indices, FX, economic events, and market scanners.
+- **Manage your workspace:** portfolios, watchlists, broker connections, alerts, notes, and AI tools.
 
-[term.gloom.sh](https://term.gloom.sh) requires a free Gloom Cloud account. The workspace loads behind a sign-in panel that cannot be dismissed, and a session opens it; configuration, tickers, layouts, session state, and plugin state are stored in the browser. Free accounts receive rate-limited, 15-minute-delayed Gloom Cloud market data and read-only chat until the email is verified; Pro accounts receive realtime market data. Public share pages stay open to everyone with no account. Cloud REST and WebSocket traffic uses the same-origin `/api` path, which the Worker forwards only to `https://api.gloom.sh`; it is not an arbitrary network proxy.
-
-The browser build intentionally omits brokers and native integrations, filesystem notes, local AI, external plugins, updater/debug tools, application menus, native window controls, pop-out native windows, and native context menus. Modules that still depend on desktop-only or CORS-blocked feeds are also absent for now: RSS/Substack, prediction markets and polls, market halts/heatmap/movers, dividend/ownership/SEC panes, earnings/IPO, and TV. Public shares open under `/s/:id` in a separate slim bundle. Share creation and owner deletion use the signed-in Gloom Cloud session through the same fixed API path; public reads require no account.
-
-Local browser development:
-
-```bash
-bun run web:build
-bunx wrangler dev
-```
-
-Validate the public artifacts with `bun run web:audit` and `bun run cloudflare:dry-run`. `wrangler.jsonc` remains generic for local checks. After verification passes on `main`, GitHub Actions deploys `term.gloom.sh` with `wrangler.production.jsonc`. The private Gloom Cloud API is deployed separately.
+The desktop app and TUI share the command language and plugin system. The [browser app](https://term.gloom.sh) offers a smaller feature set and requires a free Gloom Cloud account: free market data is rate-limited and delayed by 15 minutes; Pro provides realtime data. See [browser features and limits](docs/browser.md).
 
 ## Install
 
-### macOS
+### Desktop
 
-Install the desktop app and the `gloomberb` terminal command:
+On **macOS (Apple Silicon)**:
 
 ```bash
 brew install --cask vincelwt/tap/gloomberb
-# or
-curl -fsSL gloom.sh/install | bash
 ```
 
-Both install `Gloomberb.app` and a `gloomberb` command that runs the TUI through the app bundle, so the bundled runtime is stored once.
-
-`Gloomberb.app` is Apple Silicon (arm64) only. On an Intel Mac the install script installs the standalone `gloomberb` terminal app instead, and the Homebrew cask refuses to install rather than leaving an app that cannot launch.
+On **Windows 11**, [download the installer](https://github.com/gloom-sh/gloomberb/releases/latest/download/stable-win-x64-GloomberbSetup.exe). It supports x64, and ARM64 through x64 emulation.
 
-Prefer a direct download?
+Both desktop installers include the `gloomberb` terminal command.
 
-- [Download Gloomberb for Mac](https://gloom.sh/download/desktop)
+### Terminal
 
-### Linux
-
-Install the standalone TUI binary:
+On **macOS or Linux**:
 
 ```bash
 curl -fsSL gloom.sh/install | bash
 ```
 
-This installs `gloomberb` to `~/.local/bin` by default. A Linux desktop package is not published yet.
-
-### Windows
+On Apple Silicon Macs, this installs the desktop app and TUI. On Intel Macs and Linux, it installs the standalone TUI.
 
-Install the desktop app:
-
-- [Download GloomberbSetup.exe for Windows](https://github.com/gloom-sh/gloomberb/releases/latest/download/stable-win-x64-GloomberbSetup.exe)
-
-The installer supports Windows 11 on x64 and ARM64. On ARM64, the desktop app and its bundled `gloomberb` terminal command use Windows' built-in x64 emulation.
-
-For a terminal-only setup on x64, install Bun and use the package:
-
-```powershell
-bun install -g gloomberb
-```
-
-### Terminal Package
-
-Already have Bun installed on any supported OS?
+Or install with [Bun](https://bun.sh) on macOS, Linux, or Windows x64:
 
 ```bash
 bun install -g gloomberb
 ```
 
-Then run:
-
-```bash
-gloomberb
-```
-
-On macOS and Windows, desktop updates replace the installed app in place and keep the terminal command pointing at the updated runtime. Homebrew users can also update through `brew upgrade --cask gloomberb`.
-
-For the best terminal experience, use a [Kitty](https://sw.kovidgoyal.net/kitty/)-compatible terminal such as Ghostty, Kitty, or WezTerm.
-
-Live TV in the terminal also requires `mpv` with Kitty video output. Gloomberb resolves the stream in JavaScript and runs `mpv` with its `yt-dlp` integration disabled, so `yt-dlp` is not required.
+Run `gloomberb` to launch. For graphics, use a Kitty-compatible terminal such as Ghostty, Kitty, or WezTerm. See the [installation guide](docs/installation.md) for direct downloads, install locations, and updates.
 
 ## Start
 
-Open command mode with `Ctrl+P`, then type a command. Press `` ` `` to open ticker search directly.
+Press `Ctrl+P` to open the command bar, or press `` ` `` to search for a ticker. Desktop also supports `Cmd/Ctrl+K`.
 
 | Try | Opens |
 |-----|-------|
-| `DES AAPL` | Security details |
+| `DES AAPL` | Company details |
 | `GP NVDA` | Price chart |
-| `G AAPL:price, MSFT:revenue` | Mixed-series chart |
-| `TOP` | Ranked market stories |
-| `HM` | Market heatmap |
-| `MOST` | Market movers |
-| `HILO` | New highs and new lows |
+| `TOP` | Market stories |
 | `PF` | Portfolios and watchlists |
-| `KELLY AAPL` | Position sizing |
-| `HELP` | Full in-app shortcut list |
+| `HELP` | Commands and keyboard shortcuts |
 
-## What It Does
+Use `Tab` to switch panes and `j` / `k` to navigate lists. The [user guide](docs/usage.md) covers charts, broker setup, keyboard shortcuts, and the full command reference. See [research data conventions](docs/research-data.md) for return definitions, financial sources, and model assumptions.
 
-- Research companies with quotes, charts, financials, filings, holders, insiders, options, analyst ratings, events, and relative valuation.
-- Follow markets with top stories, breaking news, sector feeds, Substack subscriptions, global indices, futures, FX, macro events, yield curves, Treasury auctions, market movers, new-high/new-low and options-flow scanners, and fear/greed.
-- Track portfolios and watchlists, connect brokers, set alerts, keep notes, run AI screens, browse prediction markets, and use Gloom Cloud chat.
+## CLI
 
-### Broker position sync
+Run commands directly from your shell:
 
-Use **New Portfolio** or **Add Broker Account** to connect a broker. Gloomberb can import positions from Interactive Brokers, Public, Robinhood, and SimpleFIN.
+```bash
+gloomberb quote AAPL
+gloomberb quote AAPL --json
+gloomberb help
+```
 
-Each broker is a plugin with its own repository, installed on first launch and updatable on its own. Manage them from the plugin directory, or with `gloomberb install gloom-sh/gloomberb-public` and friends.
+Output is human-readable by default; use `--json`, `--csv`, or `--ndjson` for scripts. See the [CLI reference](docs/usage.md#cli) for commands and flags.
 
-- Robinhood opens a browser sign-in page. Gloomberb uses only the read-only account and equity-position tools from the Robinhood Trading MCP server.
-- Public needs an API secret from Public API settings. Gloomberb creates a short-lived access token and uses only the account and portfolio endpoints.
-- SimpleFIN needs a one-time setup token from SimpleFIN Bridge. Gloomberb exchanges the token and imports only accounts that contain holdings.
+## Plugins and contributing
 
-Gloomberb saves the connection data on the local device. It does not include this data in Gloom Cloud synchronization. A later position sync updates the managed portfolios and removes positions that the broker no longer reports.
+Plugins add panes, data providers, broker connections, and commands. Install one from GitHub:
 
-## CLI
-
-Running `gloomberb` with no arguments launches the terminal UI. Normal commands run through a headless CLI path; use `gloomberb launch-ui` when a script should explicitly open the UI.
-
-Human-readable output is the default. Automation can opt into structured output with `--json`, `--csv`, or `--ndjson`. JSON output favors the richest fetched model available and includes display-column metadata when a command has table columns; CSV and NDJSON use the command's tabular row view. Common global flags include `--limit`, `--refresh`, `--quiet`, `--no-color`, `--dry-run`, and `--yes`.
-
-| Command | Use |
-|---------|-----|
-| `gloomberb` | Launch the terminal UI |
-| `gloomberb launch-ui` | Explicitly launch the terminal UI |
-| `gloomberb help` | Show all CLI commands |
-| `gloomberb api list|get|invoke|subscribe` | Inspect and call plugin capabilities directly |
-| `gloomberb quote <symbols>` | Fetch current quotes |
-| `gloomberb search <query>` / `provider-search <query>` | Search tickers and provider symbols |
-| `gloomberb ticker <symbol>` | Show quote, ownership, and financials |
-| `gloomberb history|financials|fundamentals|options <symbol>` | Fetch research data |
-| `gloomberb news|filings|holders|insider|13f|analyst|events|valuation <symbol>` | Fetch company research feeds |
-| `gloomberb movers|indices|sectors|fx|fear-greed|earnings` | Fetch market overview data |
-| `gloomberb econ|fred|yield-curve` | Fetch macro data |
-| `gloomberb compare|correlation|relationship <symbols>` | Compare securities |
-| `gloomberb portfolio [action]` | Manage manual portfolios |
-| `gloomberb watchlist [action]` | Manage watchlists |
-| `gloomberb notes|alerts [action]` | Manage local notes and alerts |
-| `gloomberb broker|ibkr [action]` | Inspect broker profiles |
-| `gloomberb ai providers|ask` | Use configured AI providers |
-| `gloomberb rss fetch <url>` | Fetch an RSS feed |
-| `gloomberb provider status` | Inspect enabled data providers |
-| `gloomberb config|cache|plugin|layout|pane|debug|doctor|version|changelog` | Inspect and manage local app state |
-| `gloomberb fn [...]` | Run a pane-backed report command |
-| `gloomberb shot [...]` | Capture a pane-backed screenshot |
-| `gloomberb predictions [...]` | Launch Prediction Markets |
-| `gloomberb plugins` | List installed plugins |
-| `gloomberb install <user/repo>` | Install a plugin from GitHub |
-| `gloomberb remove <name>` | Remove an installed plugin |
-| `gloomberb update [name]` | Update plugins |
-
-## Plugins
-
-Everything from the portfolio list to broker integrations is a plugin. Plugins can add panes, tabs, columns, command bar commands, CLI commands, status bar widgets, and data providers.
-
-Core plugin areas include:
-
-- Portfolios, watchlists, manual entry, and broker connections
-- Ticker details, quotes, charts, options, filings, holders, insiders, and research
-- News, Substack reader feeds, market movers, global indices, sectors, FX, earnings, macro data, and yield curves
-- Prediction markets, alerts, notes, chat, AI screeners, and external plugins
-
-See [PLUGINS.md](PLUGINS.md) for the plugin API and the shared UI surface available through `gloomberb/components`.
-
-## Keyboard
-
-| Key | Action |
-|-----|--------|
-| `Ctrl+P` | Open command mode |
-| `` ` `` | Open ticker search |
-| `Ctrl+,` | Open focused pane settings |
-| `Ctrl+W` | Close focused pane |
-| `Ctrl+Shift+M` | Move focused window (`WIN resize` starts resize mode) |
-| `Ctrl+Shift+D` | Dock or float focused pane |
-| `Ctrl+Shift+E` | Export focused pane table as CSV |
-| `Ctrl+Shift+L` | Layout actions |
-| `Ctrl+Shift+G` | Tidy windows |
-| `Tab` | Switch panes |
-| `j` / `k` | Navigate lists |
-| `h` / `l` | Switch tabs |
-| `m` | Cycle chart mode |
-| `q` | Quit |
-
-Desktop builds also accept `Cmd/Ctrl+K` for the command bar, the matching `Cmd` shortcuts on macOS, `Cmd/Ctrl+Shift+O` to pop out a pane, and `Cmd/Ctrl+Shift+C` to copy a focused pane screenshot.
-
-## Command Reference
-
-Use `HELP` inside Gloomberb for the live shortcut list. The common command-bar prefixes are listed here for quick scanning.
-
-### Company Research
-
-| Shortcut | Function |
-|----------|----------|
-| `DES <ticker>` / `T <ticker>` | Security details for a ticker |
-| `FA <ticker>` | Financial statement view |
-| `G <series>` | Custom chart composer |
-| `CAT [query]` | Browse and search chartable series |
-| `GP <ticker>` | Price chart |
-| `GIP <ticker>` | Intraday price chart |
-| `HP <ticker>` | Historical OHLCV prices |
-| `GF <tickers>` | Fundamental statement graph |
-| `GE <tickers>` | Valuation multiple graph |
-| `GR <tickers>` | Security relationship graph |
-| `EE <ticker>` | Events view with earnings and revenue estimates |
-| `EM [tickers]` | Earnings monitor |
-| `SRCH [query]` | Full-text search across earnings call transcripts, news, and SEC filings |
-| `QQ <tickers>` | Ticker quote monitor |
-| `CMP <tickers>` | Normalized price comparison |
-| `CORR <tickers>` | Ticker return correlations |
-| `ANR <ticker>` | Analyst targets and ratings |
-| `DIAG <ticker>` | Equity Diagnostic with cited flags and anomalies |
-| `SEC <ticker>` | SEC filings and company disclosures |
-| `OMON <ticker>` | Options monitor |
-| `OVME` | Black-Scholes option calculator with Greeks and implied volatility |
-| `HDS <ticker>` | Institutional holders |
-| `DVD <ticker>` | Dividend yield and history |
-| `SI <ticker>` | Short interest |
-| `13F [fund/ticker/CIK]` | 13F fund filings and holdings |
-| `INS <ticker>` | Insider activity |
-| `EVT <ticker>` | Corporate actions, earnings, and estimates |
-| `RV <tickers>` | Relative valuation |
-
-### Chart Composer
-
-`G`, `GP`, `GIP`, `CMP`, `GF`, and `GE` all open the same chart composer with different starting presets. `CAT` opens a searchable catalog of those chartable series so you can graph one without typing the expression. A custom expression can mix unrelated data sources on one synchronized timeline:
-
-```text
-G AAPL:price, MSFT:revenue, FRED:CPIAUCSL
+```bash
+gloomberb install gloom-sh/gloomberb-tv
 ```
 
-Open **Series** to add, remove, reorder, or hide series and choose each series' field, chart style, transform, axis, panel, period, and panel scale. Price data supports candles, OHLC, HLC, line, and area; scalar data supports its compatible line, area, step, column, and point modes. Panels can use independent left/right axes and linear or logarithmic scales.
-
-The toolbar controls preset or exact date ranges, intervals from one minute through monthly, the primary chart mode, technical indicators, and pair formulas. Indicators include volume, SMA, EMA, Bollinger Bands, RSI, and MACD; formulas include ratio, spread, and rolling correlation. Mixed-frequency values use as-of alignment: fundamentals use filing dates when available, sparse series carry forward only after becoming available, and missing publication dates are called out in the chart status.
-
-### Markets, News, and Macro
-
-| Shortcut | Function |
-|----------|----------|
-| `TOP` | Ranked market stories |
-| `HM` | Market heatmap for large US stocks and ETFs |
-| `MOST` | Top gainers, losers, most active, and trending tickers |
-| `HILO` | Session new highs and new lows with 30s/1m/5m momentum |
-| `FLOW` | Unusual options activity: sweeps, blocks, and large premium |
-| `PM <query>` | Polymarket and Kalshi prediction data |
-| `N` | News feed |
-| `CN <ticker>` | Ticker news |
-| `NI` | Sector news |
-| `SUB` | Authenticated Substack reader feed |
-| `FIRST` | Breaking news |
-| `TWIT <query>` | Ticker-related market posts |
-| `TBO` | TheBuildout infrastructure intelligence |
-| `CG` | Congress trading disclosures |
-| `WEI` | Global equity indices |
-| `MAP` | Live world venue map with local market status and clocks |
-| `FUT` | Front-month futures across index, rates, energy, metals, grains, and FX |
-| `ECO` | Economic events and releases |
-| `ECST [statistic]` | Economic statistics: inflation, labour, growth, consumer, housing, rates |
-| `GC` | Yield curve |
-| `AUCT` | Treasury auction results: high rate, bid-to-cover, indirect share, and size |
-| `VIX` | VIX 30-day/3-month implied-volatility curve |
-| `CRD` | Credit spreads |
-| `VAL [indicator]` | Whole-market valuation: Buffett, CAPE, excess CAPE yield, Tobin Q, investor equity allocation, dividend yield, margin debt, cap/profits, cap/M2 |
-| `CDS [ticker]` | Single-name corporate CDS activity: most-active issuers, or one issuer's trades |
-| `ERN` | Earnings calendar |
-| `IPO` | Upcoming and recent IPOs |
-| `HALT` | US trading halts with reason and resumption times |
-| `TV` | Live Bloomberg, CNBC, and Yahoo Finance television |
-| `BI` / `SP` | S&P 500 sector performance |
-| `FXC` | Major FX cross rates |
-| `FNG` | Fear and greed market gauge |
-
-### Workspace and App Controls
-
-| Shortcut | Function |
-|----------|----------|
-| `PF` | Portfolio and watchlist workspace |
-| `PORT` | Portfolio risk and sector exposure |
-| `ALRT` | Price alerts |
-| `SA <symbol condition price>` | Create a price alert |
-| `AI <prompt>` | AI screener |
-| `AGENT` | Local AI research workspace |
-| `CHAT [channel]` | Gloom Cloud chat |
-| `DM @user [@user...]` | Open or start a direct or group chat |
-| `ACM` | Gloom Cloud account settings |
-| `NOTE` | Notes |
-| `IBKR` | IBKR trading pane |
-| `BR` | Broker connections |
-| `CHG` | Changelog |
-| `HELP` | Open shortcut and layout help |
-| `AW` / `AP <ticker>` | Add a ticker to the active watchlist or portfolio |
-| `RW` / `RP <ticker>` | Remove a ticker from the active watchlist or portfolio |
-| `PS` | Open focused pane settings |
-| `LAY` | Open the layout browser to switch, publish, or add layouts |
-| `LMA <query>` | Layout and pane arrangement actions |
-| `WIN move\|resize` | Move or resize the focused window |
-| `GL` | Tidy all windows |
-| `SB` | Toggle the status bar |
-| `VF` | Toggle quote value flashing |
-| `TH <theme>` | Change color theme |
-| `FONT+` / `FONT-` | Increase or decrease desktop font size |
-| `CONN` | Connection health |
-| `POLL` | Prediction-market polls |
-| `UPGRADE` | Account upgrade |
-| `CR` | Cycle chart renderer |
-| `LANG <locale>` | Change interface language (`auto`, `en`, `es`, `zh-CN`, `zh-TW`, `ja`, or `ko`) |
-| `PL <plugin>` | Manage plugins |
-
-Published layouts preserve portable pane setup and state, including searches, chart viewport, and drawings. Credentials, accounts, portfolios, and pane fields marked private stay local. Publishing copies a durable `term.gloom.sh/l/...` link for social sharing.
-
-## Gloom Cloud sign-in
-
-Sign in with email and password, or pick `Log In with QR Code` from the command bar and scan the code with the Gloomberb mobile companion app to sign the terminal in without typing. The onboarding wizard offers the same QR option as the recommended path, with email and password as the alternative.
-
-## Localized interface
-
-Gloomberb includes English, Spanish, Simplified Chinese, Traditional Chinese, Japanese, and Korean UI support. English remains the default fallback language.
-
-- **Automatic detection:** supported `LANG` / `LC_ALL` and desktop system locales select the matching interface automatically.
-- **Command switching:** enter `LANG` in the command bar (Ctrl+P) to cycle languages, or use `LANG auto`, `LANG en`, `LANG es`, `LANG zh-CN`, `LANG zh-TW`, `LANG ja`, or `LANG ko`. The choice is persisted in `config.json`.
-- **One-run override:** `GLOOMBERB_LANG=ja gloomberb` (or another supported locale) takes highest priority in environments that expose process locale variables.
-
-Implementation notes:
-
-- Locale dictionaries live in [src/i18n](src/i18n), keyed by the original English UI text. Missing entries safely fall back to English.
-- Shared render sinks call `t()` / `tf()` / `tc()` for pane titles, the command bar, menus, settings, tabs, help, and onboarding.
-- Finance abbreviations such as BID, ASK, and CHG% intentionally remain in English for terminal conventions and fixed-width alignment.
-- CJK wide characters and grapheme clusters are measured by [src/utils/format.ts](src/utils/format.ts) using terminal display-cell widths.
-
-## License
-
-MIT
-
-## Credits
-
-- [OpenTUI](https://opentui.com/) for the layout engine
+See the [plugin development guide](PLUGINS.md), [TV setup](docs/usage.md#live-tv), or [contributing guide](CONTRIBUTING.md) to get started.
+
+Available in English, Spanish, Simplified Chinese, Traditional Chinese, Japanese, and Korean. Use `LANG` in the command bar to switch; see [language settings](docs/usage.md#localized-interface).
+
+[MIT licensed](LICENSE). Built with [OpenTUI](https://opentui.com/).