feat(explorer): v0.8.7–v0.8.9 — workspace frame, command palette, live workspace

[tcballard]

Summary

Implements rac/roadmaps/v0.8.x-explorer/v0.8.7-explorer-visual-overhaul.md, rac/roadmaps/v0.8.x-explorer/v0.8.8-explorer-command-palette.md, and rac/roadmaps/v0.8.x-explorer/v0.8.9-explorer-live-workspace.md. The branch carries three unmerged releases: v0.8.7 is the workspace frame, v0.8.8 the command surface and reading flow built on it, and v0.8.9 makes the workspace live — the Explorer follows the filesystem and invalid artifacts explain themselves in place.

Adds:

• One persistent workspace frame (sidebar, context panel, status line, app bar) replacing the screen-per-view shell; views swap in place and Esc unwinds history (v0.8.7)
• A summoned command palette on / — empty input lists the registry, a prefix filters and completes commands, other text quick-opens artifacts (v0.8.8)
• Interactive /settings editing explorer.json in place: theme with live preview, mascot, animations, grouping, and a new editor preference with terminal-editor suspend/resume (v0.8.8)
• First-class reading: focused, scrollable Content tab with capped width; artifact references in rendered Markdown navigate in-app with history; tab count badges (v0.8.8)
• Mascot frame-sequence animation engine (placeholder art; future frames are data-only drops) (v0.8.8)
• Live reload: a 2-second path/mtime scan (no parsing, no new dependency) reloads on change, preserving the sidebar, the open artifact's tab, and its scroll position; the watcher holds during terminal-editor suspension and rescans on resume (v0.8.9)
• Validation drill-down: health attention items land on the artifact's Inspection tab (badged with its diagnostics count); recommendations land on its Findings tab (v0.8.9)
• Improvement suggestions from rac improve on the Findings tab — one row per missing section with the schema's guidance question; rendered, never applied (v0.8.9)
• Command-surface depth: /schema [type], recent artifacts in the palette's empty state, and an f-cycled type filter on artifact results (v0.8.9)
• The rac-lantern theme as default; tests, fixtures, docs, and changelog for all three releases

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.8.x-explorer/v0.8.7-explorer-visual-overhaul.md
• rac/roadmaps/v0.8.x-explorer/v0.8.8-explorer-command-palette.md
• rac/roadmaps/v0.8.x-explorer/v0.8.9-explorer-live-workspace.md

Relevant ADRs:

• rac/decisions/adr-015-explorer-as-consumer.md — every v0.8.9 surface consumes an existing Core service (validate, improve, core.schema, core.fs); the adapter remains the only boundary and no Core or service module changed
• rac/decisions/adr-023-clean-break-internal-refactors.md — widgets/commandbar.py deleted, not shimmed
• rac/decisions/adr-024-rac-not-content-store.md — Explorer writes only explorer.json; improvement suggestions are rendered, never applied
• rac/decisions/adr-028-explorer-surface.md — every state keeps a text label under any palette

Scope

Included

• Sidebar: type-tagged artifact tree (grouped or flat), titles over IDs, ✗ validity markers, expansion/cursor preserved across reloads, e opens in editor
• Palette: full registry listing, prefix completion, quick-open with search fallback, and per-repository recent artifacts (limit 8, additive workspace JSON) offered before a character is typed
• Settings view persisting every change via save_preferences; editor resolution order is preference → $VISUAL → $EDITOR; known terminal editors run under App.suspend()
• Content tab takes focus on open, j/k/PgUp/PgDn scrolling, link resolution via adapter.open_ref with unresolvable-link reporting
• Live watcher: never runs before the first successful load or after a load error; a change debounces into the existing exclusive load worker; an open artifact that disappears falls back home; manual r also refreshes the visible view in place now
• Validation drill-down, Improvement findings group, /schema, results type filter — the full v0.8.9 contract

Excluded

• Artifact creation (/new) — deferred pending an ADR-024 write-boundary review
• Stats/portfolio view — candidate for v0.8.10
• Diff views, bulk operations, relationship graph visualization
• Third-party filesystem watching (watchfiles, inotify) — the stdlib mtime scan is the pinned design point for repositories of this corpus's scale
• Final mascot artwork — frames arrive separately as data

Product / Architecture Decisions

• The palette is a MainScreen widget on a CSS layer (display: none when idle), not a pushed screen — the screen stack still carries only the confirm-write modal
• The persistent command bar is removed outright rather than hidden (ADR-023); / reclaims two content rows
• The watcher fingerprint reuses find_markdown_files — the loader's own discovery — so watch and load can never disagree about which files count; the baseline is snapshotted before each load, so a save landing mid-load is caught by the next tick and converges
• Textual 8.x keeps suspend signals private, so the watcher pause is explicit: launch_editor calls duck-typed pause_watching/resume_watching screen hooks around App.suspend() (a MainScreen import there would be circular)
• Improvement analysis runs on artifact open only, never during repository load; unreadable-mid-edit files degrade to review-only findings rather than erroring
• The results type filter is presentation state over rows the search already returned — no second query path
• Preferences.editor defaults to the empty string and Workspace.recent_artifacts is an additive JSON key, so existing config and state files load unchanged

User-Facing Contract

CLI

No CLI command surface changes. Entry point remains:

rac explore [directory]

Human Output (Explorer)

• / summons the palette (recents above the registry when history exists); Esc dismisses; ? opens help
• /settings (alias preferences) edits theme, mascot, animations, grouping, editor in place
• /schema lists artifact types; /schema decision (any registered type) renders required/recommended/optional sections with descriptions and metadata values
• Saving an artifact in an external editor updates the open Explorer within ~2 seconds, no keystroke
• Attention items open on Inspection (badged), recommendations on Findings; f cycles the type filter on artifact results (status-line chip added)
• Status chips use one casing: ✓ Valid, ! Warning, ✗ Error; default theme is rac-lantern

JSON Output

No JSON contract movement. explorer.json gains the additive editor field; explorer-workspace.json gains the additive recent_artifacts map (per repository, newest first, capped at 8). Files written by earlier versions load unchanged.

Exit Codes

Unchanged.

Verification

Ran

pytest --ignore=tests/test_ingest.py   # 820 passed
ruff check .
rac validate rac/                       # PASS — 84 valid, 0 invalid
rac relationships rac/ --validate       # 0 issues (150 checked)
rac review rac/                         # no priority 1–2 findings

tests/test_ingest.py was excluded only in the development container, where a pre-existing cryptography wheel incompatibility breaks docx ingestion imports; the exclusion is unrelated to this diff.

Covered

• Watcher: fingerprint reacts to edit/add/remove and ignores non-Markdown and dotted dirs; a disk change reloads and updates the summary; the open artifact refreshes in place; a deleted open artifact falls back home; paused and error states stay quiet; resume scans immediately
• Drill-down: attention → Inspection tab with diagnostics visible; recommendation → Findings tab; Inspection badge counts diagnostics
• Improvements: sparse requirement yields per-section suggestions with guidance actions; empty before load and for unknown paths
• Command surface: /schema overview and detail, unknown-type message; palette recents appear and Enter reopens; f cycles all → type → type → all with a live count line; registry contract re-pinned for v0.8.9
• Plus the v0.8.7/v0.8.8 batteries: palette completion and focus, settings round-trips, reading focus/scroll/links, Esc history, resume, mascot timer

Review Path

1. src/rac/explorer/screens/main.py — the watcher (tick → scan worker → debounced reload → in-place view refresh) and command routing
2. src/rac/explorer/adapter.py — fingerprint, improvement_rows, schema_overview/schema_detail, recent_rows
3. src/rac/explorer/widgets/views.py — drill-down landing tabs, Inspection badge, the filterable ResultsView, watcher pause hooks in launch_editor
4. src/rac/explorer/widgets/palette.py and workspace.py — recents
5. tests/test_explorer_app.py (watcher, drill-down, command-surface sections) and tests/test_explorer_adapter.py / test_explorer_workspace.py
6. docs/cli.md, the four design artifacts, CHANGELOG.md, and the three roadmap contracts

Notes For Reviewer

• tests/test_explorer_app.py is the single battery absorbing all three releases; the v0.8.9 sections are at the end of the file
• The watcher's reload path is the existing exclusive repository-load worker, so manual r, watch-triggered reloads, and load-error recovery share one code path
• A reload racing an in-progress save can render a half-written artifact for one cycle; the next tick re-detects and converges (pinned as an accepted risk in the v0.8.9 contract)
• Mascot frames are placeholders; final art replaces FRAMES data and nothing else

Implementation Process

Implemented with AI assistance under the roadmap contracts. Final scope, review, and acceptance decisions were made by the maintainer.