boost ships a stunning Aurora living-glass web system — yet the CLI still
renders in plain 8-color ANSI: no gradient, no glass, no motion. This roadmap
closes that gap. Every item was found by driving the real CLI
(boost, doctor, search, list) and
grading its output against style/boost.css — then scored by
category, complexity, impact and wow-factor. Zero new dependencies;
NO_COLOR and non-TTY are always respected.
Proposed logged & triaged · Next queued · In progress being built · Shipped done.color, layout, motion, typography, ux, system, tooling.S a focused change · M a module-sized effort · L a multi-file refactor.High every session · Med real polish · Low finishing touch.zero-dependency, degrades on NO_COLOR / non-TTY, and targets Python ≥ 3.12.Bring the brand palette and gradient into the terminal — with graceful fallbacks.
output.pyThe whole CLI runs on eight legacy SGR codes (RED…CYAN) that don't match the brand at all — the front door paints section headers in generic [33m yellow. Add truecolor rgb() helpers mapping the exact web tokens: cyan #22d3ee, violet #a855f7, pink #f472d0, green #4ade80, yellow #facc15, plus --text/--text-3 greys. One map recolors everything.
core/output.py:15–38use_color() is binary — color or nothing. Add a tier ladder: truecolor (COLORTERM=truecolor/24bit) → 256 → 16 → none, so the Aurora tokens snap to the nearest available color instead of vanishing. Keep the existing NO_COLOR honor, add a BOOST_COLOR=always/auto/never override, and treat TERM=dumb as none.
core/output.py:26–38The brand is the cyan→violet→pink --grad. Interpolate it per-character across a string so headings, the boost wordmark and hero counts shimmer in the terminal exactly like the web hero. A pure-Python lerp over the three stops; falls back to a single accent color when truecolor is unavailable.
core/output.py · new gradient()Commands scattered out.c(x, out.YELLOW) and out.GREEN literally throughout the command layer, so a palette change meant a repo-wide sweep. Now a single ROLES table in output.py maps six named roles — accent, brand, success, warn, danger, muted — resolved through the Aurora palette (truecolor → 16-color → plain), and out.role(text, name) paints by intent. Every color call site across all eight command groups now reads as meaning, not mechanics; brand hues (accent/success/warn) upgraded from flat 16-color to on-theme truecolor in the process. Re-theming is a one-file edit.
core/output.py:ROLES / role() · commands/*.pyWidth-aware output, glass panels, and results that never blow up the pane.
search: truncate & width-clamp resultsToday boost search is the worst screen in the app: a single result can dump a 2,000-character description with literal, unrendered \\n\\n escapes, while names are padded to a fixed 30 columns that waste half the row. Clamp each row to the live terminal width, collapse whitespace/escape artifacts, and ellipsize. This one fix turns a wall of noise into a scannable list.
commands/discovery.py · searchThe web system frames everything in rounded glass; the CLI frames nothing. Add rounded box-drawing primitives (╭─╮ │ ╰─╯) with dim --line borders and an optional title, mirroring the web .glass/.window surfaces. Reusable chrome for doctor, info, snapshot and success summaries.
core/output.py · new panel()Results are "ranked by heuristic relevance" but the ranking is invisible — every row looks equal. Render a tiny gradient relevance bar or score glyph per hit and visually separate curated from GitHub-wide matches, so the eye lands on the best result first.
commands/discovery.py · searchtable() is a naive ljust that ignores terminal width and left-aligns numeric columns. Make it width-aware (shrink the widest text column to fit), right-align counts with tabular figures, and add dim column separators — matching the web's font-variant-numeric: tabular-nums stat blocks.
core/output.py · table()preview / catThe web guide renders skills inside a titled window with traffic-light dots (.window .dots). Give preview/cat the same treatment: a titled frame with the skill name in the bar, so a rendered SKILL.md in the terminal matches the screenshots on the site.
commands/info.py · preview/cattrending had the same overflow as searchGrading the un-touched commands surfaced a sibling of D05: boost trending piped raw catalog descriptions straight into table(), so a single 300-char description blew the table across the pane. Fixed by clipping each description through out.truncate() to the width left after the name/installs/last columns — the same helper the search fix introduced.
commands/discovery.py · cmd_trendingtable()out.table() backs ~28 call sites, and several overflowed: taps padded the NAME column to the widest repo (K-Dense-AI/claude-scientific-skills = 44 cols) and then printed full URLs, so wide catalogs wrapped. Now table() is width-aware itself — when a row would exceed the terminal it shrinks the widest text column and clips its cells with an ellipsis (ANSI-aware, so colored cells keep their color and close cleanly), while numeric columns are right-aligned like tabular figures and never truncated. Narrow tables render byte-identical to before; the logic only engages on overflow or multi-row number columns. Delivered test-first: dedicated unit coverage for _numeric_col, _clip_visible, _fit_widths, and the integrated render keeps the mutation gate green.
core/output.py:table() / _fit_widths / _clip_visibleA narrow-pane audit across all 80 commands fixed the concrete overflow bugs it found — a hardcoded textwrap width in info/preview/explain, two argparse usage lines with no metavar, help text that split a backtick-quoted command across lines, five "nothing here" screens that overflowed unwrapped, and a print_help command column painted in raw 16-color CYAN instead of the Aurora accent role — and added wide-character measurement (unicodedata.east_asian_width) to visible_len()/_clip_visible() so table() stays aligned when a cell holds CJK or an emoji. Three related gaps remain, deliberately left rather than folded into that pass because each is a wider, riskier sweep on its own:
1. dim(" text")'s embedded 2-space indent has no wrap path. 39 call sites (bmad's hint lines, schedule status, impact's caveat, …) hand-embed a leading " " because dim() prints flush-left by contract; passing wrap=True today would silently drop that margin on the first wrapped line (the tokenizer discards leading whitespace). One of the 39 measurably overflows a 60-column pane by a single character (schedule status's enable hint) — not worth an inconsistent one-off fix. dim() needs a real indent/margin parameter (mirroring kv's lead-column math) before any of the 39 can safely opt into wrapping.
2. empty_state() adoption is 7 of ~35 "nothing to show" screens. This pass converted cohort/replay/pulse/who's overflowing messages to the standard helper; roughly 28 more (hooks, hallmarks of "no taps configured", no skills installed across five modules, …) still print via ad hoc out.info("no X"). None of them currently overflow (wrong, see Shipped below), so converting all 28 in one shot would be a same-behavior refactor risking 28 screens' worth of rendered-text drift for no measured bug — better done a few at a time, verified against real content.
3. Wide-character width stopped at visible_len()/_clip_visible(). truncate() (plain-text clipping before coloring) and search_layout()'s column-budget math still count with len(), not display width — so a skill description containing an emoji would still truncate mid-character or throw off a search row's column budget. Not observed in real catalog data (skill names/taps are near-universal ASCII slugs), and widening it touches layout-budget code, not just measurement, so it stayed out of the audit's contained fix.
Shipped, with each gap measured at 60 and 120 columns before and after. 1. dim() takes an indent margin, and a leading run of spaces in the message counts as the same margin, so every dim(" hint") site can opt into wrapping unchanged: the margin is kept on the first and every continuation line, and the wrap budget pays for it. 24 prose hints now pass wrap=True (bmad, compact, create, policy, completions, schedule status, mcp, impact's caveat, install's MCP offer, pin/unpin, trust), plus chat's hand-rolled muted wrap, which became dim(note, wrap=True, indent=2). Lines that carry a path, an arrow to a path, or an unquoted command stay unwrapped as data. Each of the 24 was rendered at 60 and 120 columns. All 24 are byte-identical at 120. Ten of them overflowed a 60-column pane before, at 61 to 109 columns (bmad on's autopilot note was 109 and install's permissions hint was 81). All ten now fold to 60 columns or less, and no backtick span is split. Non-wrapping output is byte-identical everywhere. 2. 17 more "nothing to show" screens use empty_state(), with each em-dash remedy split into its → hint: taps, update, snapshot list, profile list, focus, context status, log, log --crashes, tag --list, quarantine --list, hooks list, attest, test, decay, impact, recommend and trending. out.empty_state( call sites under boost_cli/commands went from 13 to 30. The card's "none of them currently overflow" was wrong: measured in display columns at 60, trending was 68, recommend 66 and log --crashes 62 before, with taps exactly at 60 and snapshot list/focus at 58. All now fit, and tests/functional/test_cli_empty_states.py pins each of them. Action outcomes such as "nothing to change" and "nothing registered" are not empty listings and were left as they are. 3. This gap was already fixed before this card was picked up: 74c4aac9 made truncate() delegate to _clip_visible() and sized search_layout() with visible_len(), and test_output.py's CJK clipping tests pin it. A search row with a CJK name and an emoji description measures 59 columns at 60.
core/output.py · dim(indent=) + empty_state() call sitesMake it feel snappy — spinners, progress, and instant first paint.
Network-bound commands — search (AI rank), tap clone, discover, index — currently freeze silently while they work. Add a lightweight braille-dot spinner (⠋⠙⠹⠸…) tinted with the Aurora accent, auto-suppressed on non-TTY and under NO_COLOR. The single biggest "feels fast" upgrade.
core/output.py · new spinner()Multi-item commands — reindex, update, sync, snapshot restore — give no sense of "how far in." Add a gradient-filled progress bar (N/total + ETA) for anything looping over a known count, so long operations read as intentional rather than hung.
core/output.py · new progress()search computes the full ranking, then prints the whole list at once. The premise that "the terminal sits blank, then floods" was measured on a 1,500-skill / 11,973-passage index and does not hold: the whole command is 180 ms end to end, of which the ranking — the part streaming would overlap — is 11.8 ms. The rest is 70.7 ms importing core modules and 71.4 ms loading the index, both of which finish before the first hit can be known. Streaming a ranked list is also structurally unavailable to BM25: the top hit is not known until every document is scored, and the renderer needs the widest name and the top score across all shown rows to size the meter column (discovery.py). Progressively revealing an already-complete 180 ms result would add latency, not hide it. Parked rather than dropped: if motion work is wanted here the honest target is the 142 ms of import + index load, not the 11.8 ms of ranking.
Declined, and re-measured first on a bigger index rather than closed on the old numbers.
Over the pinned 10,152-entry eval corpus, boost search is
260–300 ms end to end. The shape is the same one that refuted the
premise, and it has not improved with scale: 26 ms Python startup +
44 ms importing boost_cli + ~150 ms retrieval,
of which loading the 8.5 MB index is ~33 ms before a single document has
been scored. Every one of those milliseconds is spent before the first hit can be known,
so there is nothing for a stream to overlap. The structural objection is unchanged and is not a
matter of degree: BM25 cannot name its top hit until every document is scored, and
discovery.py needs the widest name and the highest score across all shown rows to
size the meter column, so the first row cannot be drawn before the last one is known.
Declining it does not discard the perf target. ~70 ms of fixed startup is real and
worth attacking — it is simply a code-board concern about lazy imports and index format,
not a motion one, and keeping it filed under a card about animating a list would put the work
behind the wrong question. scripts/import_budget.py already guards the part of it
that regresses most easily.
One thing checked on the way, and it is a negative result worth recording.
rag._all_postings() takes 1.7 s over this corpus — enough to be
alarming if anything interactive called it. Nothing does: its only callers are
scripts/build_demo_index.py and rag._kept_docs, which runs during an
incremental rebuild, where 1.7 s sits inside a ~13 s reindex. So there is no
hidden hot-path cost hiding behind the one this card measured.
commands/discovery.py · searchok() prints a lone green check, then the command just ends. After install/uninstall, close with a small framed confirmation — what changed, where it landed, and the obvious next step (boost info <skill>) — so a completed action feels finished, not dropped.
core/output.py:41 · commands/pkg.pyThe screens users actually stare at — front door, doctor, list, info, browse.
The boost home screen is the first thing everyone sees. Today the wordmark is plain bold and every group header is the same generic yellow. Paint the boost wordmark with the Aurora gradient and give each command group a colored bullet/glyph keyed to a brand hue — turning a flat list into a branded index.
commands/info.py · help rendererdoctor as a health dashboarddoctor is an undifferentiated wall of green checks — no hierarchy, no headline. Reframe it as a panel with a verdict line (● Healthy in green / ● Attention in amber), grouped checks, dim sub-detail, and severity color so a problem actually stands out instead of hiding among the ✓s.
commands/quality.py · doctorinfo skill identity cardinfo lists kv() pairs as flat dim labels. Promote it to a framed identity card: gradient skill name, status badges (installed / pinned / tap origin) styled like the web .badge pills, then the metadata — a real "detail view," not a key-value dump.
commands/info.py:177+list polish — chips & aligned countslist already uses a nice · agent separator; take it further. Color the agent names as small chips, right-align the count footer with tabular figures, and add a dim header rule so the table reads as a designed object rather than raw columns.
commands/info.py:130–131Empty and hint lines are ad-hoc — info's "no skills installed" hint is a hand-rolled DIM string. Standardize a single empty-state affordance (muted icon + one-line guidance + suggested command) and a single hint style, applied everywhere, so guidance always looks the same.
commands/info.py:117–119 · core/output.pyGrading confirmed this hits every command with a required argument — boost uninstall, boost snapshot and more all dump raw, unstyled argparse: a multi-line usage block with a bare error:, nothing like the branded top-level dispatch (which already routes through Error: + a difflib "did you mean"). The durable fix is a shared BoostArgumentParser subclass whose error()/usage route through the Aurora output layer, adopted across the ~50 per-command parsers — a broad, test-first sweep, so logged rather than rushed.
cliparse.py (BoostArgumentParser) · all 10 command filesbrowse — Aurora the full-screen TUIThe interactive browse pane was the last off-theme surface: a curses screen drawn in raw A_BOLD/A_DIM/A_REVERSE — zero brand color while every other command spoke Aurora. Rebuilt it as a first-class TUI: a macOS titlebar (traffic-light dots + boost browse wordmark under a cyan→violet→pink gradient rule), an ❯ chevron prompt with a live ▏ caret, fuzzy-match highlighting (matched chars glow pink as you type), a cyan selection bar, yellow curated ★, violet tap labels, a right-edge scrollbar, and a gradient-topped detail pane with #tag chips. Colors come from the single-source out.TOKENS via init_color — parity-locked to style/boost.css — and degrade truecolor → 8-color → monochrome. Stdlib only. With this, every boost command is on-theme.
commands/discovery.py · _browse_tui / _aurora_themeOne source of truth for the brand — and the tools to show it off.
style/ vs docs/style/Two copies of boost.css have diverged: the root style/ uses a cyan→violet→pink gradient (--violet #a855f7), while docs/style/ uses an orange→pink→violet one (--violet #a78bfa). Same brand, two looks. Pick style/ as canonical and make docs/style/ a generated copy or symlink so the portfolio, roadmaps and CLI can't drift again.
style/boost.css · docs/style/boost.cssDone: the CLI palette is now single-sourced — one output.TOKENS dict holds every Aurora RGB triple, and the gradient, brand tints and badges all derive from it (previously cyan/violet/pink were re-typed across _AURORA and _GRAD_STOPS). A test locks the contract so a stray hex can't drift. Remaining: lift TOKENS into a shared tokens.json and generate both the CSS custom properties and this map from it, so the site and the terminal move in lockstep. Shipped as enforcement instead of generation: a unit test parses style/boost.css and asserts every --token matches output.TOKENS, so a hex changed in one place and not the other fails CI — the same guarantee without rewriting the hand-authored stylesheet.
core/output.py TOKENS · style/boost.css · future build_tokens.pyThere's a docs/demo.tape + demo.gif, but no repeatable way to re-record once the aesthetic changes — and tmux isn't even installed in the dev box. Add a make demo that drives a scripted session (VHS tape or asciinema, optionally split-pane via tmux) and refreshes the GIF, so the README and portfolio always show the current look.
docs/demo.tape · MakefileThe web .window mock shows an idealized boost session — gradient prompt, clean checks — that the real CLI doesn't yet produce. Once D01–D15 land, update the mock (and README code blocks) to mirror the true output 1:1, so every screenshot is honest and the brand reads identically across web, README and terminal.
docs/index.html · README.md · style/demo.html
A living document — each loop iteration drives the real CLI, grades it against
style/boost.css, and files what it finds here. Sibling to the
Engineering Roadmap.
Everything stays zero-dependency and honors NO_COLOR & non-TTY.