Skip to content

Decision record · ADR

ADR-0055: Present the TUI as a sidebar console with detected dark and light palettes

Status: accepted | Date: 2026-10-03

References: RFC-0010, ADR-0020

The view-only TUI (RFC-0010) renders four views as an object list beside a detail pane under a three-line header. A review of the real TUI on workspaces with hundreds of records found that its layout and navigation, more than its information, limit the operator. Two-line list rows halve the visible catalog and repeat record-identifier timestamp fragments, while the header spends three rows on identity, counts, and view names. Overview shows running work as plain rows indistinguishable from history. A recipe’s child records appear only as identifiers in the parent’s detail, so a Bench’s metrics need a hop through another record, and a workload record’s metrics are reachable only one at a time through the comparison surface. The fixed palette was tuned for dark terminals, so light terminals show low-contrast text. Detail also has rendering defects: labels collide with their values, wrapped values lose their column, raw JSON reaches the screen, and ages past a day read in hours.

A terminal wide enough for a navigation sidebar beside the two panes presents the sidebar, the object list, and the selected detail. The sidebar carries the workspace identity with its revision and dirty state, the four views with their counts, the status filter of Overview and Records with a count per status, and the display-refresh indicator, replacing the three-row header; below that width a compact header carries the same facts and the existing wide and narrow pane rules apply, so the console keeps two responsive layouts. Overview keeps ATTENTION first, as RFC-0010:C-READ-MODEL prioritizes failed, stale, and unavailable objects, followed by NOW: active operations with phase, elapsed time, and item position as a progress bar when the operation reports one, and running servers with their observed liveness and uptime; RECENT follows, grouped by day. Records becomes a day-grouped timeline in which a parent expands into its explicit child references; a collapsed parent shows that it has children, and an available child is selectable with its own detail and keeps identity-stable selection. The status filter cycles through all, issues (failed, stale, or unavailable), and running with one key, so a status restriction is a visible control rather than a text query. List rows are one line and keep their authority badge. Detail opens with a status chip, an authority chip, and one summary line, and a workload record shows its recorded case metrics as a per-case table beside the existing comparison surface. The visual language uses rounded panels whose border marks the focused pane in the brand blue; status and authority chips drawn as pills; glyphs that carry status meaning (✓ succeeded, × failed, ◆ warning, ○ not run, ● live or running, a spinner for an active operation); smooth eighth-block progress bars; a per-case trend sparkline in the metric table; and key hints drawn as keycaps. While any operation is active, the TUI redraws about ten frames a second from the last complete display generation to animate the spinner, and returns to redrawing on refresh when none is; animation never starts a refresh and never changes the display-refresh indicator. Two palettes, dark and light, are tuned for contrast on their backgrounds; the TUI selects one at startup by asking the terminal for its background color within a short bound, then from COLORFGBG, and otherwise uses the dark palette. Fills keep the brand blue, which the brand-stylesheet check binds; accent text takes each palette’s own contrast-safe shade. No configuration surface selects the theme.

The redesign amends RFC-0010: the refresh indicator lives in persistent chrome rather than a header, available child records become selectable beneath a parent that shows it has children, the arrow keys expand and collapse child references in Records before they move focus, and f cycles the status filter of Overview and Records. Child records already read on every refresh stay in the projection instead of being dropped after classification, so selection adds no reads; Find keeps searching top-level records. The sidebar costs about twenty columns, which raises the width at which the console shows it. Startup gains one bounded terminal query: a reply arriving after the bound must be drained before the event loop reads keys; terminals and multiplexers that do not answer, or answer with their own default, and slow SSH links fall back to COLORFGBG and then the dark palette, which equals today’s palette, so a missed detection does not regress; a non-answering terminal pays the bound at every start, and a background change mid-session is not followed. Animation costs redraws only while an operation is active, and the glyphs stay within standard Unicode so no patched font is required. Text-layout tests and the published TUI screenshot change with the presentation. The four views, their required content, authority labels, refresh semantics, Find, and the narrow single-pane flow are unchanged.

A sidebar console with a dashboard Overview, a Records timeline with selectable children, card detail, and detected dark and light palettes (accepted)

Section titled “A sidebar console with a dashboard Overview, a Records timeline with selectable children, card detail, and detected dark and light palettes (accepted)”
  • Pros: Surfaces running work first, reaches child evidence directly, and returns the three header rows to the list, Each palette is tuned for its own background instead of compromising between both
  • Cons: Amends RFC-0010 navigation and refresh wording and changes every text-layout test, Adds a bounded terminal query at startup whose answer some terminal stacks withhold

Keep the header and two panes, and add only NOW, selectable children, the per-case metric table, and the detected palettes (rejected)

Section titled “Keep the header and two panes, and add only NOW, selectable children, the per-case metric table, and the detected palettes (rejected)”
  • Pros: Delivers the information changes with less layout churn and keeps every list column for content
  • Cons: Keeps three header rows above every list and gives view counts and workspace identity no persistent place

Use only terminal-default colors with reverse-video selection, with no background detection (rejected)

Section titled “Use only terminal-default colors with reverse-video selection, with no background detection (rejected)”
  • Pros: Adapts to any terminal with no query and no palette to maintain
  • Cons: Loses panel and selection tints, which carry most of the hierarchy, and reverse video inverts every color inside the selected row

Detect the background and also offer a –theme dark|light|auto override (rejected)

Section titled “Detect the background and also offer a –theme dark|light|auto override (rejected)”
  • Pros: Covers terminal stacks whose background query fails
  • Cons: Adds a public option now; defer an override until an operator reports a light-terminal stack where detection fails