gloomberb

Stack: Bun + OpenTUI

CONTRIBUTING.md is the contributor guide and applies to agents too: repository layout, the checks CI runs, the test policy, code rules and pull request conventions. The rules below are the short form; each links to its full text there.

Tests (full policy): be selective. Add or keep a test only when it protects behavior that is easy to break and hard to catch in review: parser/math/state complexity, async/cache/persistence behavior, integration boundaries, and regressions with a concrete failure mode that could plausibly return. Static metadata, default props, pass-through wiring, copied UI text and obvious behavior are weak targets. A bug-fix test is kept only when the bug came from non-obvious behavior or a boundary likely to regress, and a test is never kept just because it exists or adds coverage. When touching a test file, trim nearby low-value tests if the cleanup is clear and low-risk.

Public text (full rule): pull request titles, descriptions, comments, commit messages and branch names are public. No internal tracker ids or links, no private repository names or links, no internal notes (deals, pricing plans, people, infrastructure); a change that needs a server change says "needs the matching server change".

Review screenshots and evidence images for a PR go through scripts/pr-assets.sh <slug> <file>..., which pushes them to refs/pr-assets/<slug> and prints the markdown links for the description: never a branch, and never committed to the tree.

Use tmux to test terminal TUI changes (see the tui-testing skill). Always kill the tmux session when done.

Shared machine: several agents often work on one host at the same time.

• Run at most one typecheck or full bun test at a time. Each full run takes 1-3 GB, and parallel runs get OOM-killed.
• Bound test and other risky commands with timeout -k 10 <seconds> .... A hung bun ignores the plain SIGTERM from timeout and keeps its memory for hours. Before you finish, check that nothing of yours is still running: pwdx $(pgrep -f 'bun test') 2>/dev/null | grep -F "$PWD".
• Never run bare gloomberb, bun start or bun dev from a non-interactive shell: the TUI never exits without a TTY, so the call hangs. Use a subcommand or --help, prefix risky commands with timeout -k 10 60, and run interactive checks only in tmux.
• Throwaway profiles (GLOOMBERB_HOME) go on disk under ~/.cache/gloom-smoke/<task>, never under /tmp (one profile is ~29k files and /tmp is a small tmpfs). Remove the profile and kill tmux when done.
• Never message, stop, archive or kill other agents or their processes, and never ask them to wait. If the host is busy, retry later or report it.
• Never use git stash: all worktrees of a repo share one stash list, so a pop or clear can take another agent's entries. Commit work in progress to your own branch instead.

Pane footers/status bars show changing status such as loading, error, live/delayed, stale, or auth state. Preserve existing pane-specific action shortcuts there instead of duplicating them in body toolbars. Do not add fixed pane labels, row counts, or generic keyboard hints. Never show internal provider or source identifiers (provider:*, raw feed names) anywhere in a pane; say what the data is (real-time, 15m delayed, settlement, as of) instead. Gloom Cloud is the public market-data service. See pane-conventions. Recurring methodology, model assumptions, and usage explanations belong in docs, not always-visible pane text or new info buttons. Keep units, source dates, and active data failures in context. Use existing actions instead of adding duplicate toolbars. Information density matters: never repeat the same information in a pane title/header and again in the body. If a stack/detail title already names the item, start the body with metadata or content. Desktop work, bun run typecheck and bun test need Electrobun's SDK in .hutch/devkit: run bun run desktop:sync after bun install (it also applies patches/electrobun-devkit@*.patch). For Electrobun/desktop-web-only work, do not load the OpenTUI or tui-testing skills unless the change also touches terminal OpenTUI behavior or explicitly needs tmux coverage. The OpenTUI skill is not checked in: if .agents/skills/opentui is missing, restore it with bunx skills experimental_install. For desktop/Electrobun/web UI, do not draw GUI primitives with terminal cell characters. Use real DOM/CSS/canvas/SVG primitives for lines, markers, shapes, overlays, and interaction affordances; reserve cell-character drawing for the OpenTUI terminal renderer only. Add mouse/cursor interactivity for everything interactive. Never fix chart issues by disabling / turning off the kitty renderer; preserve kitty support and fix the root cause. Built-in code under src/ imports the host by relative path (../../../ui, ../../../components, ../../../public/react, ../../../theme/colors). The gloomberb/* specifiers are the external-plugin API: Bun on Linux resolves them as a package self-reference, so typecheck and tests pass, but the Windows desktop bundle cannot resolve them and the Windows verify workflow on main fails. See Host imports. Every UI change is benchmarked across all panes and plugins, and its blast-radius sheet is attached to the PR (Holding the line): bun run check:ui-tokens must pass (UI tokens in CI: type, weight, radius and pane inset on every view, exceptions in src/architecture/ui-tokens-allowlist.json with a why), and the UI benchmark's "N of M views changed" comment and sheets (bun run ui:benchmark --base origin/main locally) show only views the change meant to move. When adding or changing a pane/plugin, read PLUGINS.md and load the pane-conventions skill (docs/pane-conventions.md); start with its Principles (one convention per element, tokens instead of raw values, extend the kit, check every UI change against all panes and plugins) and then use it for where actions, status and warnings go, detail stacks, load-more lists, tabs, forms, density, reserved keys, and the new-pane checklist. Basic UI must use the shared kit (full rule): actions, selectable/expandable rows, fields, tabs, lists/tables, headings/sections, labeled values, badges, dividers, and loading/error/empty states. Extend the kit for a missing repeated pattern and migrate its callers; do not create another pane-local implementation. Box/ScrollBox remain layout primitives; raw Text and custom surfaces are appropriate for domain content, charts, and specialized editors. External plugins use the same components through gloomberb/components.