---
schema_version: 1
id: RAC-KTR5QS8N01WF
type: roadmap
---
# RAC v0.8.1 — Explorer Navigation

## Status

Planned

## Context

v0.8.0 establishes the Explorer shell, adapter layer, and repository model.

The Explorer requirement's first capability is Discover: understand what
product knowledge exists within a repository. Users need to browse artifacts,
inspect them in context, and reach anything in the repository through a single
interaction model — without prior knowledge of RAC commands.

## Outcomes

- Users can browse, open, and inspect every recognized artifact in a
  repository from within Explorer.
- A single command surface (`/`) is the universal entry point for search and
  commands.
- First-time users reach a working repository view in seconds; returning
  users skip onboarding.

## Initiatives

### Initiative 1 — Repository Home

Provide a landing experience summarizing the repository:

```text
RAC Explorer

Health 92%

Attention

2 broken relationships
1 incomplete artifact
```

Health and attention values are rendered from Core services; scoring detail
is delivered by v0.8.2.

### Initiative 2 — Artifact Browser

Support browsing all artifact types:

- Requirements
- Decisions
- Roadmaps
- Prompts
- Designs

Artifacts default to discovery under the `rac/` root while supporting
explicitly supplied paths (ADR-018).

### Initiative 3 — Artifact Context View

Display, for any artifact:

- Metadata and identity
- Validation state
- Completeness
- Relationships
- Diagnostics

### Initiative 4 — Slash Command Surface

Introduce `/` as the universal interaction model, backed by a single command
registry (DESIGN-command-surface):

```text
/open req-001

/find payments

/health
```

- Search and command execution share one entry point; users do not
  distinguish between them.
- Artifact lookup resolves canonical IDs, legacy aliases, and keywords with
  the same semantics as `rac resolve` and `rac find` (ADR-026).
- Commands not present in the registry are not discoverable.
- Empty states teach by example.

### Initiative 5 — Keyboard Model

```text
/      command surface
↑ ↓    navigate
Enter  select
Esc    back
q      quit
```

All functionality works without mouse input.

### Initiative 6 — First Run Experience

Implement onboarding per DESIGN-first-run-experience:

- Existing RAC repository: show artifact and relationship counts, then enter
  the repository.
- Empty repository: offer import, create, or browse options.
- Invalid repository: show issue counts with the option to open anyway or
  view issues.
- Returning users skip onboarding.

Startup reaches repository context in seconds, with no login, cloud, sync, or
forced setup.

## Implementation Contract

The following decisions are pinned for v0.8.1.

### Default Directory (ADR-018)

`rac explorer` without a directory argument opens `rac/` when that directory
exists, falling back to the current directory. An explicitly supplied path is
always used as given. Other commands' defaults are unchanged.

### Repository Model Additions

- `Artifact` gains `missing_recommended: tuple[str, ...]` (empty for unknown
  artifacts), derived from the existing core `missing_sections` rules during
  the same single walk. Already obtainable via `rac inspect`; no JSON change.
- The resolve service gains snapshot seams — `resolve_in_index` and
  `search_index` — so `/open` and `/find` rank with identical semantics to
  `rac resolve` and `rac find` (ADR-026) without re-walking a loaded
  repository.

### Screens and Navigation

- Home evolves the v0.8.0 summary: health score plus an Attention section
  aggregated from portfolio attention items. Scoring detail remains v0.8.2.
- Browser lists artifacts grouped by type (the five canonical types plus
  unknown); Enter opens the selected artifact's context view.
- Context view renders identity and metadata, validation state, completeness
  (missing recommended sections), relationships with resolved titles, and
  diagnostics — all from the loaded repository model.
- Esc pops the screen stack (context → browser → home); `q` quits from
  anywhere; `r` reloads from home. No mouse required (ADR-028).

### Command Surface (DESIGN-command-surface)

- `/` opens a modal command surface backed by a single registry. The v0.8.1
  registry: `open <ref>`, `find <query> [type]`, `browse [type]`, `home`,
  `help`, `quit`. Input matching no registered command is treated as a
  search; users never distinguish search from command.
- `/health` is delivered by v0.8.2 (its roadmap owns the health command);
  the example above is illustrative of the surface, not v0.8.1 scope.
- The empty surface teaches by example. Command routing lives in Explorer;
  every answer comes from Core services (ADR-015).

### First Run Experience (minimal v0.8.1 cut)

- Launch states derive from repository content: existing repository
  (artifact and relationship counts, key cheat sheet, "Press / for
  anything"), empty repository (teaching state pointing at `rac new` and
  `rac ingest` — the guided import workflow is v0.8.4), invalid repository
  (issue counts with open-anyway; full issue navigation arrives with
  v0.8.2 health).
- Returning users skip onboarding via a first-run marker file under the XDG
  state directory (`$XDG_STATE_HOME/rac/`, default `~/.local/state/rac/`).
  The marker is the only persisted state: no last-repository, view, or
  artifact restoration, no recent-repositories list, no preferences
  (v0.8.6), and no repository chooser — the directory comes from the CLI.

### Exit Codes and Contracts

Unchanged from v0.8.0: `0` session quit, `2` usage error or missing
`explorer` extra. No new JSON contracts; existing CLI output remains
byte-identical.

### Testing

- Registry routing (including unknown-input-as-search) is unit-tested
  without Textual; screens are tested headlessly through the existing
  pilot harness, covering browser navigation, context rendering, the
  Esc stack, the command surface, and each first-run state.
- First-run marker tests isolate state via `XDG_STATE_HOME` pointed at a
  temporary directory.
- Resolve seams are covered in the resolve battery; per-artifact
  completeness in the repository battery. The AST isolation battery
  extends to the new `commands` and `firstrun` modules (Textual-free).

## Non-Goals

- Health scoring detail (v0.8.2)
- Recommendations (v0.8.3)
- Editing or authoring artifacts (ADR-024)
- Workspace persistence and preferences (v0.8.6)

## Success Measures

- A first-time user can open a repository and locate a named artifact without
  prior RAC knowledge.
- Every artifact reachable through the browser is also reachable through `/`.
- Everything visible in Explorer navigation is obtainable through existing
  `rac` commands and JSON output (ADR-015).

## Related Decisions

- ADR-015
- ADR-018
- ADR-026
- ADR-028

## Related Designs

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

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.0 Explorer foundation, repository model, and adapter layer
- v0.7.12 artifact lookup and resolution
