---
schema_version: 1
id: RAC-KTSY9VR329ZM
type: roadmap
---
# RAC v0.8.8 — Explorer Command Palette, Settings, and Product Polish

## Status

Planned

## Context

v0.8.7 delivered the Explorer's persistent workspace frame. Using it surfaced
the next gaps: the always-visible command bar spends two rows advertising one
keystroke; preferences are read-only and the editor cannot be configured at
all; the mascot is a single static frame per state; opening an artifact does
not put the document under the keyboard; and references inside rendered
Markdown — the heart of a requirements corpus — are inert text.

This milestone replaces the bar with a summoned command palette (input on
top, navigable suggestions below, in the manner of Claude Code), makes
settings interactive (including a default Markdown editor with
terminal-editor support), gives the mascot a frame-based animation engine
ready for new art, makes documents scrollable and their artifact references
navigable, and applies a coordinated refinement pass across the frame.

## Outcomes

- `/` summons one palette that teaches, completes, and quick-opens; the idle
  frame carries no input chrome.
- Settings change from inside the Explorer and persist; the editor
  preference works for GUI and terminal editors alike.
- Reading an artifact is a first-class activity: the document scrolls under
  the keyboard and its references are walkable hypertext.
- The mascot animates from drop-in frame data; the visual system gains the
  refinement details (titles over IDs, validity markers, calm states,
  consistent chips).

## Initiatives

### Initiative 1 — Summoned Command Palette

The persistent bar is removed. `/` floats a titled palette over the context
region: an input on top and a navigable menu below it. Empty input lists the
whole registry; a command prefix filters it; any other text shows live
artifact matches (quick-open) plus a search hint. Enter completes
argument-taking commands into the input, runs argless ones, opens a
highlighted match, or routes bare text exactly as before. Esc dismisses and
restores focus. Routing and the registry are unchanged; large result sets
still render in the context region.

### Initiative 2 — Interactive Settings

`/settings` (alias `preferences`) opens a settings view that edits
`explorer.json` in place: theme (cycles registered Textual themes with live
preview), mascot, animations, artifact grouping, and a new `editor`
preference. The editor resolution order becomes preference, then `$VISUAL`,
then `$EDITOR`; terminal editors run with the application suspended and
resume on exit. Explorer writes its own configuration only — never artifacts
(ADR-024).

### Initiative 3 — Mascot Frame Animation

The mascot becomes frame sequences per state: equal-width multi-line frames
cycled on a timer only while visible and while animations are enabled. The
searching state plays during repository load. Current art ships as
placeholder frames; future art replaces the frame data and nothing else.
Every state keeps its text label (ADR-028).

### Initiative 4 — Reading and Link Navigation

The Content tab takes focus on open and scrolls under the keyboard; scroll
position resets per artifact; the Markdown column is capped for readability.
Artifact references inside the rendered document resolve through the
adapter's lookup and navigate in-app with the existing history; unresolvable
links report instead of failing. Links and Findings tabs carry count badges.

### Initiative 5 — Visual and Continuity Refinement

Sidebar rows show the artifact title with the type tag (ID only as
fallback) and mark invalid artifacts; expansion and cursor survive reloads.
Esc never dead-ends (empty history returns home) and resume restores the
last view as well as the last artifact. Hints and border titles that the
chips already carry are removed; chip casing is normalized; load progress is
one calm line; empty results use the mascot's empty state; `?` opens help.
The app bar shows the short version and `~`-contracted paths; the welcome
block centres vertically; `e` works from the sidebar.

## Implementation Contract

The following decisions are pinned for v0.8.8.

### Palette

- `rac.explorer.widgets.palette.CommandPalette` lives inside `MainScreen`
  on a dedicated CSS layer (`display: none` when idle); the screen stack
  still carries only the confirm-write modal. `widgets/commandbar.py` is
  deleted (clean break, ADR-023). Submission routing stays on `MainScreen`.

### Settings

- `rac.explorer.preferences.Preferences` gains `editor: str = ""`
  (backward-compatible). `SettingsView` joins the context-region views and
  persists every change via `save_preferences`. `rac.explorer.editor`
  resolves preference → `$VISUAL` → `$EDITOR` and detects terminal editors
  (vi, vim, nvim, emacs, nano, helix, micro) to run them under
  `App.suspend()`.

### Mascot

- `rac.explorer.mascot.FRAMES` maps each state to a tuple of equal-width
  multi-line frames; `frames(state)` is the API. The home view owns the
  timer (~0.6s) and stops it when the mascot is hidden or animations are
  off.

### Reading

- The Content tab's scroll container is focusable with `j`/`k` bindings and
  receives focus on artifact open. Markdown link activation resolves via
  `adapter.open_ref` and navigates with `open_artifact`; the adapter gains
  no new Core access (ADR-015).

### Scope

- No new dependencies; no Core or service changes; no JSON contract
  movement. The explorer battery absorbs all tests.

## Non-Goals

- Write workflows beyond `explorer.json`
- New repository intelligence or commands beyond the `settings` rename
- Replacing the results view with the palette
- Final mascot artwork (frames arrive separately as data)

## Success Measures

- The idle frame has no input widget; `/` answers within one keystroke with
  navigable, current suggestions.
- A user can configure theme, mascot, animations, grouping, and editor
  without leaving the Explorer, and the choices persist.
- An artifact's references can be followed by keyboard alone, and Esc walks
  back along the same path.
- Disabling animations or the mascot still loses no information.

## Related Decisions

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

## Related Designs

- explorer-command-surface
- explorer-visual-system
- explorer-editor-integrations
- explorer-mascot-animations

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.7 explorer visual overhaul
