feat(explorer): v0.8.6 Explorer maturity — workspace continuity, preferences, mascot

[tcballard]

Summary

Implements rac/roadmaps/v0.8.x-explorer/v0.8.6-explorer-maturity.md — the final v0.8.x milestone.

Adds:

• Workspace continuity — Explorer remembers recently opened repositories and the last artifact per repository; . or /resume reopens it
• Preferences — optional theme / mascot / animations / artifact_grouping, file-based under XDG config, shown via /preferences
• Mascot — a lantern-carrying guide in the welcome and empty states, with text-equivalent feedback so disabling it (or animations) loses nothing
• An Explorer-level responsiveness check over a 1,200-artifact corpus

Roadmap / ADR Trace

Roadmap: rac/roadmaps/v0.8.x-explorer/v0.8.6-explorer-maturity.md (contract pinned in the first commit)

Relevant ADRs and designs:

• ADR-015 — no new repository intelligence; presentation and local state only
• ADR-019, ADR-028 — accessibility, terminal-native, no colour-only meaning
• DESIGN-mascot, DESIGN-mascot-animations, DESIGN-mascot-interaction, DESIGN-first-run-experience, DESIGN-visual-system

Scope

Included

• rac.explorer.preferences — Preferences(theme, mascot, animations, artifact_grouping), JSON under $XDG_CONFIG_HOME/rac/explorer.json, tolerant load; the app applies the theme (guarded) and the browser honours artifact_grouping; /preferences displays values + path
• rac.explorer.workspace — recent repositories + last artifact per repository under $XDG_STATE_HOME/rac/; record_open on launch, record_artifact on context open, resume_path, /resume and the . binding
• rac.explorer.mascot — the lantern guide with state frames (idle/searching/discovery/success/empty/error), shown in welcome/empty; every state carries a text label
• resume and preferences join the command registry

Excluded (deliberately)

• New capabilities or repository intelligence (ADR-015)
• Mascot behaviour that gates features or modifies the repository; game-like or continuous animation
• In-app preference editing — preferences are edited in the file (ADR-024); /preferences is read-only
• Cloud, login, or sync of any kind

Product / Architecture Decisions

• Preferences and workspace are loaded read-only in the adapter constructor; writes happen only on explicit events (launch records the repository, opening a context view records the artifact), so constructing an adapter has no side effects.
• Resume is explicit (. / /resume), not an automatic jump on launch — returning users resume on request without a surprising redirect. resume_path returns the last artifact only if it still exists in the current load.
• The mascot is identity, never a feature: it appears only in welcome/empty states, and every state's meaning is in its text label, so animations = false (steady lantern frame) and mascot = false (text only) both lose no information.
• An unknown theme name must never break startup — applying it is wrapped and falls back to the default.
• Tolerant persistence everywhere: a missing or corrupt preferences/workspace file yields defaults; writes swallow OSError (continuity is a convenience, not a requirement).

User-Facing Contract

CLI / Keys

rac explorer
# .  or  /resume        → reopen the last artifact in this repository
# /preferences          → show theme / mascot / animations / grouping + file path
# edit  $XDG_CONFIG_HOME/rac/explorer.json  to change preferences

Human Output (interactive)

• Welcome/empty states show the mascot (when enabled) plus recent repositories and a resume hint
• /preferences lists current values and Edit <path> to change these.

JSON Output

No changes; no new contracts.

Exit Codes

Unchanged: 0 session quit · 2 not a directory or missing explorer extra.

Verification

Ran

python -m pytest                      # 772 passed
python -m ruff check src/ tests/
python -m ruff format --check src/ tests/
python -m mypy src/
rac validate rac/                     # exit 0
rac relationships rac/ --validate     # exit 0
rac review rac/                       # no priority 1–2 findings

Covered

• Preferences: defaults when no file; round-trip; corrupt file and unknown grouping fall back
• Workspace: records recent (deduped, capped at 10) and resumes the last artifact; corrupt file falls back
• Mascot: every state has a text equivalent present in the figure; animations off keeps the meaning
• App: resume reopens the last artifact across two sessions on the same repository; /preferences shows values and explorer.json; the mascot appears by default and disappears (with no information lost) when mascot = false; the shell renders 1,200 artifacts and browses within a generous time ceiling
• Isolation battery extended to preferences.py, workspace.py, mascot.py (no Textual/Core imports)

Review Path

1. rac/roadmaps/v0.8.x-explorer/v0.8.6-explorer-maturity.md — the pinned contract
2. src/rac/explorer/preferences.py, workspace.py, mascot.py — the three pure modules
3. src/rac/explorer/adapter.py — load/record/resume, grouping, preferences_lines
4. src/rac/explorer/app.py, screens/repository.py, screens/context.py, widgets/__init__.py — theme, welcome header, recording, ./resume
5. src/rac/explorer/commands.py, screens/command.py — /resume, /preferences
6. tests/test_explorer_workspace.py and the app/adapter additions
7. docs/cli.md, CHANGELOG.md

Notes For Reviewer

• Final PR of the v0.8.2–v0.8.6 stack (on top of PRs feat(explorer): v0.8.2 Explorer health — health view, four areas, navigable attention #53–feat(explorer): v0.8.5 Explorer relationship navigation — traverse, impact, lineage #56); until those merge this diff also shows their commits. Merging in order narrows each to its milestone.
• With this, the Explorer requirement's Discover / Understand / Assess / Act capabilities are all delivered; the series is feature-complete against the v0.8.x roadmap.

Implementation Process

Implemented with AI assistance under the roadmap contract.

Final scope, review, and acceptance decisions were made by the maintainer.