Designer × engineer backlog · living document

# Aurora in the terminal. A CLI as beautiful as the brand.

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.

26 Design opportunities
5 Design tracks
0 New dependencies
1:1 Web ↔ CLI parity goal

## The bridge — Aurora web tokens → 24-bit ANSI

Cyan#22d3ee · accent
Violet#a855f7 · brand
Pink#f472d0 · brand
Green#4ade80 · success
Yellow#facc15 · warn
Gradient--grad · headings

## How to read this roadmap

Status
  `Proposed` logged & triaged · `Next` queued · `In progress` being built · `Shipped` done.
Category
  The discipline: `color`, `layout`, `motion`, `typography`, `ux`, `system`, `tooling`.
Complexity
  `S` a focused change · `M` a module-sized effort · `L` a multi-file refactor.
Impact
  How much it lifts the everyday experience: `High` every session · `Med` real polish · `Low` finishing touch.
Wow-factor
  ★ to ★★★★★ — how much delight the win buys relative to the effort spent.
Constraints
  Every proposal stays `zero-dependency`, degrades on `NO_COLOR` / non-TTY, and targets `Python ≥ 3.9`.

Track
Impact

26 of 26 opportunities shown

## Aurora Color Engine

Bring the brand palette and gradient into the terminal — with graceful fallbacks.

4 items
BOOST-D01 Shipped

### 24-bit Aurora palette in `output.py`

The 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.

color Complexity S Impact High★★★★☆
`core/output.py:15–38`
BOOST-D02 Shipped

### Terminal capability detection & graceful degradation

`use_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.

color Complexity M Impact High★★★☆☆
`core/output.py:26–38`
BOOST-D03 Shipped

### Gradient text renderer — the signature move

The 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.

color Complexity M Impact Med★★★★★
`core/output.py · new gradient()`
BOOST-D04 Shipped

### Semantic color roles, not raw codes

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.

color Complexity S Impact Med★★☆☆☆
`core/output.py:ROLES / role() · commands/*.py`

## Structure & Layout

Width-aware output, glass panels, and results that never blow up the pane.

7 items
BOOST-D05 Shipped

### Fix `search`: truncate & width-clamp results

Today `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.

layout Complexity M Impact High★★★★★
`commands/discovery.py · search`
BOOST-D06 Shipped

### Glass-panel box primitives

The 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.

layout Complexity M Impact Med★★★★☆
`core/output.py · new panel()`
BOOST-D07 Shipped

### Relevance visualization in search

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.

layout Complexity M Impact Med★★★★☆
`commands/discovery.py · search`
BOOST-D08 Shipped

### Width-aware, right-aligned tables

`table()` 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.

layout Complexity M Impact Med★★★☆☆
`core/output.py · table()`
BOOST-D09 Shipped

### Terminal-window chrome for `preview` / `cat`

The 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.

layout Complexity M Impact Med★★★★☆
`commands/info.py · preview/cat`
BOOST-D23 Shipped

### `trending` had the same overflow as `search`

Grading 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.

layout Complexity S Impact High★★★★☆
`commands/discovery.py · cmd_trending`
BOOST-D24 Shipped

### Width-aware shared `table()`

`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.

layout Complexity L Impact Med★★★★☆
`core/output.py:table() / _fit_widths / _clip_visible`

## Motion & Feedback

Make it feel snappy — spinners, progress, and instant first paint.

4 items
BOOST-D10 Shipped

### Braille spinner for network waits

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.

motion Complexity S Impact High★★★★☆
`core/output.py · new spinner()`
BOOST-D11 Shipped

### Determinate progress bars for batch ops

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.

motion Complexity M Impact Med★★★★☆
`core/output.py · new progress()`
BOOST-D12 Proposed

### Stream search hits as they rank

`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.

motion Complexity L Impact Med★★★☆☆
`commands/discovery.py · search`
BOOST-D13 Shipped

### Framed success summary with next step

`ok()` 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.

ux Complexity S Impact Low★★★☆☆
`core/output.py:41 · commands/pkg.py`

## Command-by-command Polish

The screens users actually stare at — front door, doctor, list, info, browse.

7 items
BOOST-D14 Shipped

### Front door: gradient wordmark + section glyphs

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 Complexity M Impact Med★★★★★
`commands/info.py · help renderer`
BOOST-D15 Shipped

### `doctor` as a health dashboard

`doctor` 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 Complexity M Impact Med★★★★☆
`commands/quality.py · doctor`
BOOST-D16 Shipped

### `info` skill identity card

`info` 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 Complexity M Impact Med★★★★☆
`commands/info.py:177+`
BOOST-D17 Shipped

### `list` polish — chips & aligned counts

`list` 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 Complexity S Impact Low★★★☆☆
`commands/info.py:130–131`
BOOST-D18 Shipped

### Consistent empty-states & hint styling

Empty 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.

ux Complexity S Impact Low★★☆☆☆
`commands/info.py:117–119 · core/output.py`
BOOST-D25 Shipped

### Branded usage & error output

Grading 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.

ux Complexity L Impact Med★★★☆☆
`cliparse.py (BoostArgumentParser) · all 10 command files`
BOOST-D26 Shipped

### `browse` — Aurora the full-screen TUI

The 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 Complexity L Impact High★★★★★
`commands/discovery.py · _browse_tui / _aurora_theme`

## Design System & Tooling

One source of truth for the brand — and the tools to show it off.

4 items
BOOST-D19 Shipped

### Resolve theme drift: `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.

system Complexity S Impact Med★★★☆☆
`style/boost.css · docs/style/boost.css`
BOOST-D20 Shipped

### Single source of design tokens (web ↔ CLI)

Done: 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.

system Complexity M Impact Med★★★★☆
`core/output.py TOKENS · style/boost.css · future build_tokens.py`
BOOST-D21 Shipped

### Scripted demo recording (VHS / asciinema)

There'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.

tooling Complexity M Impact Med★★★★☆
`docs/demo.tape · Makefile`
BOOST-D22 Shipped

### README / portfolio terminal parity

The 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.

system Complexity S Impact Med★★★★☆
`docs/index.html · README.md · style/demo.html`
No opportunities match these filters.

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.