---
schema_version: 1
id: RAC-KTSSZSJXV9B0
type: roadmap
---
# RAC v0.8.7 — Explorer Visual Overhaul

## Status

Planned

## Context

v0.8.0 through v0.8.6 delivered the Explorer's capabilities, but the
presentation never caught up with the design corpus: every view is a single
text widget on a push/pop screen stack, with stock Textual chrome and a few
lines of inline CSS. DESIGN explorer-visual-system specifies a three-tier
depth model, stable Navigation/Context/Status regions, a single accent
colour, and a universal `/` surface — none of which exist visually.

This milestone replaces the screen-per-view shell with one persistent
workspace frame: a navigation sidebar, a tabbed context panel that renders
the artifact's actual Markdown, an always-visible command bar, and a
key-chip status line — under a curated default theme derived from the
Explorer mascot's lantern-amber palette.

The look is modelled on Posting and the Textual demo, guided by GitHub
information architecture, Linear spacing, Notion content focus, LazyGit
keyboard UX, and Textual implementation.

## Outcomes

- The Explorer presents one stable workspace frame; navigation swaps the
  context region only, never the whole layout.
- Opening an artifact shows the knowledge itself — its rendered Markdown —
  with inspection, links, and findings one tab away.
- The interface ships a deliberate visual identity: titled rounded panels,
  one accent colour, type-tagged navigation, key-chip hints, and the
  rac-lantern theme by default.

## Initiatives

### Initiative 1 — Workspace Frame

One `MainScreen` composes the persistent regions: a plain app-bar line
(`RAC Explorer <version>` left, repository path right), the sidebar and
context panel as titled rounded panels, the command bar, and a key-chip
status line replacing the stock Header and Footer. Views (home, context,
health, recommendations, import, results) are widgets swapped inside the
context region; an internal view history backs `Esc`. The screen stack
survives only for the confirm-write modal (ADR-024).

### Initiative 2 — Navigation Sidebar

A persistent artifact tree titled "Artifacts": type groups with counts,
rows rendered as a fixed-width colour-coded type tag plus id and title
(tag text always present — ADR-028), lazily populated from the loaded
repository model, honouring the `artifact_grouping` preference, synced
when a command opens an artifact. The selected artifact's status chip
shows in the panel's border-bottom. The sidebar hides below 80 columns.

### Initiative 3 — Persistent Command Bar

The `/` surface becomes an always-visible bar: `/` focuses it from
anywhere, `Esc` returns focus to the previous region, and results or
ambiguous lookups render in the context region so the layout never jumps.
Routing and the command registry are unchanged.

### Initiative 4 — Visual System Application

The depth model, spacing, and accent rules from DESIGN
explorer-visual-system land as a TCSS stylesheet, and a custom registered
"rac-lantern" theme — lantern amber on near-black, derived from the mascot
asset — becomes the default. The `theme` preference still selects any
Textual theme, and all meaning survives any theme (icons + labels +
chips, ADR-028).

### Initiative 5 — Tabbed Artifact Context

The context panel hosts `Content │ Inspection │ Links │ Findings` tabs.
Content (default) renders the document's Markdown read-only (ADR-024) —
the Explorer presents the knowledge, not only structural metadata.
Inspection carries status, completeness, and diagnostics; Links absorbs
the relationship traversal view; Findings lists the artifact's
recommendations. Health and repository-wide recommendations remain
separate context-region views.

### Initiative 6 — Continuity

Onboarding, the mascot, welcome content, and resume re-home into the new
frame without behaviour change, and the 1000+-artifact responsiveness
target is re-validated against the tree-based sidebar.

## Implementation Contract

The following decisions are pinned for v0.8.7.

### Frame and views

- `rac.explorer.screens.main.MainScreen` owns the frame and the
  repository-load worker; views live in `rac.explorer.widgets.views` and
  swap via `ContentSwitcher` with an internal history list backing `Esc`.
  The old per-view screens are deleted (clean break, ADR-023);
  `ConfirmWriteScreen` stays the sole pushed screen.
- New widgets: `appbar`, `sidebar` (a Textual `Tree`), `commandbar`
  (an `Input` wrapper emitting submit/dismiss messages), `statusline`
  (key chips per focused panel, health chip right-aligned).
- Focus model: `/` focuses the bar from anywhere (not a priority
  binding, so a typed `/` works inside the input); `Esc` returns
  bar → previous region and context → view history; `Tab` cycles
  panels; single-letter shortcuts are suspended while the bar has focus.

### Content rendering

- The adapter gains one additive method returning the artifact's Markdown
  text for a path (ADR-015 boundary preserved); the Content tab renders
  it with Textual's `Markdown` widget, read-only (ADR-024).

### Theme and stylesheet

- `rac.explorer.theme` registers the "rac-lantern" Textual theme (amber
  accent ≈ `#F5A800`, near-black background, dark surfaces) and it is the
  default; the `theme` preference overrides it with any Textual theme.
- Styling moves to `src/rac/explorer/explorer.tcss`, shipped via
  package-data and resolved with `importlib.resources`.

### Scope

- No Core or service changes beyond the additive Markdown accessor; no
  new dependencies (Textual >= 1.0 already provides `Tree`,
  `TabbedContent`, `Markdown`, themes); `adapter.py`, `state.py`, and
  `commands.py` otherwise unchanged.

## Non-Goals

- New commands or repository intelligence
- In-app editing (ADR-024) or new write workflows
- A graph canvas
- Changed key semantics — existing bindings keep their meaning

## Success Measures

- Navigation between home, artifacts, health, and recommendations never
  rebuilds the frame; the sidebar keeps its state.
- An artifact's rendered Markdown is the first thing shown on open.
- The default look is deliberate: rac-lantern theme, titled rounded
  panels, accent on focus, type tags beside names.
- All existing key sequences keep working, and the Explorer stays
  responsive at 1000+ artifacts.

## Related Decisions

- ADR-015
- ADR-023
- ADR-024
- ADR-028

## Related Designs

- explorer-visual-system
- explorer-command-surface
- explorer-first-run-experience
- explorer-mascot

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.0 through v0.8.6 Explorer capabilities
