---
schema_version: 1
id: RAC-KTTS6VPMYEBN
type: roadmap
---
# RAC v0.8.10 — Explorer Creation, Stats, and the Directory View

## Status

Planned

## Context

v0.8.9 made the Explorer a live companion: it follows the filesystem,
explains validation in place, and answers schema questions. Three gaps keep
the CLI in the daily loop. Starting a new artifact still means leaving for
`rac new`, even though the Explorer is where the gap was noticed. The
portfolio numbers Core already computes — per-type breakdowns, decision
statuses, relationship coverage — have no navigable home. And the sidebar
shows an organization the repository does not have: artifacts grouped by
type, with the real directory structure (`roadmaps/v0.8.x-explorer/…`)
flattened away.

This milestone closes all three. `/new` creates an artifact from its
canonical template through Core's create service, behind the same
preview-and-confirm write workflow `/import` established in v0.8.4.
`/stats` renders the portfolio statistics the CLI reports, as a view. And
the sidebar gains a directory view that mirrors the repository's actual
structure — as the new default. All consume existing Core services
unchanged (ADR-015).

ADR-024 boundary: creation is not editing. Core's `rac new` already owns
template instantiation and ID minting (ADR-021, ADR-026); the Explorer
drives the existing confirm-write workflow around it and hands authoring to
the external editor, exactly as `/import` writes converted documents today.
The feature produces a validation-passing structure — knowledge
correctness, not document management. No content editing surface is added.

## Outcomes

- The full artifact lifecycle starts in the Explorer: notice the gap,
  `/new` the artifact, confirm the write, and land in your editor — with
  the live watcher folding the new file into the workspace by itself.
- Creation is safe by construction: preview before write, never overwrite,
  IDs minted by Core, clear guidance when the repository is not
  initialized.
- The portfolio is explorable: one view answers what the repository
  contains, how valid it is, and how connected it is — the same facts
  `rac stats` and `rac portfolio` report.
- The sidebar tells the truth about the repository: by default it mirrors
  the directory structure on disk, so the tree the user navigates is the
  tree they see in their editor and in Git.

## Initiatives

### Initiative 1 — Artifact Creation (`/new`)

`/new` joins the command registry. Bare `/new` lists the artifact types
that can be created (the schema registry's names, as `/schema` lists them).
`/new <type> <path>` renders a preview — the canonical template's sections
with a note that the ID is assigned on write — and `y` confirms. The write
goes through Core's `create_artifact`: the ID is minted against the
repository index, an existing file refuses, a missing parent directory or
uninitialized repository (no `rac init`) reports guidance instead of
failing. After a successful write the new artifact opens in the context
view, ready for `e`; the live watcher absorbs the new file into the
sidebar and counts.

### Initiative 2 — Portfolio Stats View (`/stats`)

`/stats` opens a stats view in the context region: artifact totals and
per-type counts with valid/invalid splits, the relationship summary
(total, resolved, broken, coverage, orphaned), completeness, and the
type-specific breakdowns Core's stats service computes (decision statuses,
roadmap versions, unrecognized files). Collection runs off the UI thread;
the view is read-only and `Esc` returns along the normal history.

### Initiative 3 — Directory Structure View

The sidebar gains a third grouping, `folders`, and it becomes the default:
directories from the repository root render as collapsible nodes (name with
a trailing `/` and a dim artifact count), nested exactly as on disk, with
artifact rows as leaves keeping their type tags, validity markers, and
titles. Type and flat grouping remain selectable in `/settings`; the cycle
becomes folders → type → flat. Expansion and cursor survive reloads —
including watcher-driven reloads — and `/open` reveals a nested artifact by
expanding its ancestor chain. `/browse <type>` changes in every mode: it
lists that type's artifacts in the filterable results view instead of
focusing a sidebar group; bare `/browse` still focuses the sidebar.

## Implementation Contract

The following decisions are pinned for v0.8.10.

### Creation

- `commands.REGISTRY` gains `new <type> <path>`; bare `/new` routes to a
  type listing in the results view. The preview/confirm flow reuses the
  v0.8.4 write workflow (preview rendering plus the `y` confirm path);
  the adapter delegates the write to `rac.services.create.create_artifact`
  and translates its exceptions (`OutputPathExists`,
  `OutputDirectoryMissing`, `MissingRepositoryConfig`,
  `IdGenerationExhausted`) into recoverable messages. The Explorer mints
  no IDs and renders no templates of its own (ADR-015, ADR-021, ADR-026).
- The preview shows the template body from `rac.core.schema`
  (`template_sections`) with the ID noted as assigned on write — Core's
  create service remains the only writer, and nothing is written before
  the confirm.
- On success, the screen reloads (the watcher's path) and opens the new
  artifact; on any failure, no file exists and the message says why.

### Stats

- The adapter builds a `StatsState` from
  `rac.services.stats.collect_stats` in a thread worker on `/stats`
  invocation — never during repository load. A `StatsView` joins the
  context-region views (`view-stats`), rendering sections in the
  established terminal-text style (labels beside symbols, ADR-028). No
  Core or service changes; no JSON contract movement.

### Directory view

- The adapter builds the tree (ADR-015): a frozen `DirectoryNode` (name,
  posix relpath from the repository root, child dirs sorted by name,
  artifact rows in repository order) carried on `BrowserState.tree` as an
  additive field. The sidebar derives nothing from paths itself.
- Directory nodes carry `dir:<relpath>` data keys — posix-pinned — so the
  expansion snapshot keeps working across reloads, watcher reloads
  included. The folder tree builds eagerly but collapsed; type grouping
  keeps its lazy population.
- `preferences.artifact_grouping` defaults to `folders`; explicit `type` /
  `flat` values in existing config files stay honored, unknown values fall
  back to the new default.
- `/browse <type>` routes through a new adapter lookup
  (`artifacts_of_type` rendered as `LookupState`) into the results view;
  the sidebar's type-group focusing is removed with it (clean break,
  ADR-023).

### Scope

- No new dependencies; no new screens (the confirm modal remains the only
  stacked screen); the explorer battery absorbs all tests, including
  create-failure messaging, stats rendering, and directory nesting,
  reveal, and reload-continuity coverage.

## Non-Goals

- Editing artifact content in the Explorer — authoring stays in the
  external editor (ADR-024).
- `rac init` from the Explorer — initialization stays a one-time CLI step;
  `/new` reports the guidance when it is missing.
- Directory creation on write — Core's create service refuses missing
  parents, and the Explorer mirrors that contract.
- Charts or graphics in the stats view — terminal text, same as every
  other view.
- Stats export — `/stats` is a view; `rac stats --json` already serves
  automation.

## Success Measures

- A user can go from "this decision is missing" to editing the new
  decision file without leaving the Explorer, and the sidebar shows the
  artifact without a manual reload.
- `/new` into an existing path, a missing directory, or an uninitialized
  repository produces a clear message and writes nothing.
- `/stats` answers per-type composition, validity, and relationship
  coverage in one view, matching `rac stats` output for the same corpus.
- An artifact three directories deep is reachable in the sidebar exactly
  along its filesystem path, and `/browse decision` lists every decision
  in the filterable results view regardless of grouping.

## Assumptions

- `create_artifact` and `collect_stats` remain stable service interfaces;
  the Explorer consumes them as-is.
- The v0.8.9 watcher remains the reload path, so creation needs no
  bespoke sidebar refresh.

## Risks

- The preview-then-create sequence is not atomic: the template preview and
  the written file could diverge if schemas change between render and
  confirm — in practice impossible within one session, and Core remains
  the only writer either way.
- `collect_stats` re-walks the corpus; on very large repositories the
  stats worker may take noticeable time. The view shows its loading state
  through the existing worker pattern, and collection never blocks the UI
  thread.
- Two write-capable commands (`/import`, `/new`) raise the bar for
  ADR-024 vigilance; both are pinned to Core writers behind explicit
  confirmation, and the contract records the boundary reasoning.

## Related Decisions

- ADR-015
- ADR-021
- ADR-024
- ADR-026
- ADR-028

## Related Designs

- explorer-command-surface
- explorer-action-workflows

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.9 explorer live workspace
