---
schema_version: 1
id: RAC-KV2E56SGMYMW
type: roadmap
---
# RAC v0.13.1 — Friendly Empty Corpus

## Status

Planned

## Context

Day one, a corpus is empty. How RAC behaves on an empty or
artifact-free directory is the first impression for a user who installs,
runs a command, and sees what happens. Today that first impression is
inconsistent: `rac validate`, `rac review`, and `rac portfolio` exit 0
with quiet zero-count output, but `rac stats` exits 1 — it treats "no
analysable content" as a failure. A new user running `rac stats rac/`
before authoring anything gets a non-zero exit and no guidance, which
reads as an error when nothing is wrong.

None of these commands tells a new user what to do next. The MCP server
already handles the empty case well — it prints a helpful stderr notice
and `get_summary` reports the empty state (v0.10.1) — but the CLI does
not point a first-time user at `rac quickstart` or `rac new`.

This milestone makes the empty corpus a consistent, friendly state: exit
0 across the read-only summary commands, and a single next-step line
that turns "nothing here" into "here is how to start". It also adds the
same pointer to the MCP `get_summary` empty state, so a cold agent
session has somewhere to begin.

## Outcomes

- Running any read-only summary command (`validate`, `stats`, `review`,
  `portfolio`) on an empty corpus exits 0 — empty is a valid state, not
  a failure.
- Each of those commands prints one next-step line on an empty corpus
  pointing at `rac quickstart` (or `rac new`), so a new user is never
  left at a dead end.
- The MCP `get_summary` empty-state payload carries an additive guidance
  field, so an agent connecting to a fresh repository is told how the
  user can begin authoring.
- Existing non-empty behaviour, exit codes, and JSON contracts are
  unchanged; the next-step line appears only when the corpus is empty.

## Initiatives

### Initiative 1 — Consistent Empty-Corpus Exit Codes

`rac stats` stops treating an empty corpus as a failure: with zero
artifacts of any kind it exits 0, matching `validate`, `review`, and
`portfolio`. The existing "no valid known artifacts among files that do
exist" failure is preserved for the non-empty-but-all-invalid case via a
future `--strict` flag; an empty directory is distinct from a broken
one.

### Initiative 2 — Next-Step Guidance Line

A single shared next-step string ("No artifacts yet — create your first
with: rac quickstart") rendered by the human output layer when a command
reports zero artifacts. It is advisory text on stderr-style guidance
within the human renderer; JSON output gains an additive `empty` marker
rather than prose, keeping the contract machine-stable (ADR-007).

### Initiative 3 — MCP Empty-State Pointer

`get_summary` keeps its current shape and adds, only when the corpus is
empty, an additive `guidance` field telling the agent the corpus is
empty and how the user authors artifacts. The stderr startup notice from
v0.10.1 is unchanged.

## Constraints

- Additive-only JSON changes (ADR-007): no field is removed or
  repurposed; the next-step guidance is human-output text plus an
  additive `empty` boolean in JSON.
- The guidance line appears only for a genuinely empty corpus (zero
  recognised artifacts), never when artifacts exist but have findings.
- No command changes its non-empty exit code; only `stats` on a fully
  empty corpus changes, from 1 to 0.

## Non-Goals

- A `--strict` flag for `stats` (mentioned as the future home for the
  all-invalid failure; not built here).
- Reworking the MCP search empty-result shape, which already returns a
  clean `match_count: 0` (v0.10.1).
- Onboarding content beyond a one-line pointer (the scaffold lives in
  v0.13.0).

## Implementation Contract

The following decisions are pinned for v0.13.1.

### Exit codes

- `rac stats <empty>` exits 0. `rac validate`, `rac review`,
  `rac portfolio` on an empty corpus stay at exit 0.
- The `stats` exit-1 path remains reachable only via a future
  `--strict` flag, documented as out of scope here.

### Output

- Human: when a command reports zero recognised artifacts, append one
  line: `No artifacts yet — create your first with: rac quickstart`.
- JSON: add an additive boolean `empty` to the `stats`, `review`, and
  `portfolio` payloads, true when the corpus holds zero recognised
  artifacts.
- MCP `get_summary`: add an additive `guidance` string, present only
  when `total_artifacts == 0`.

## Success Measures

- `rac stats`, `rac validate`, `rac review`, `rac portfolio` each exit 0
  on an empty directory, asserted by tests.
- The human output of each carries the next-step line on an empty
  corpus and omits it once an artifact exists.
- `get_summary` on an empty corpus includes `guidance`; on a non-empty
  corpus it does not.

## Risks

- Changing the `stats` exit code is an observable contract change for any
  CI relying on exit 1 for an empty directory. Mitigated: empty-directory
  CI failures are not a documented use; the change is noted in the
  release and the strict behaviour gets an explicit future flag.
- A next-step line could add noise for power users scripting against
  human output. Mitigated: it appears only on an empty corpus, and JSON
  (the scripting surface) carries a marker, not prose.

## Assumptions

- `rac quickstart` ships in v0.13.0, so the next-step line can point at
  it; until then the line can name `rac new`.
- Zero recognised artifacts is a reliable signal of "day one" — a
  directory of only unknown-type files is rare and still gets the
  pointer harmlessly.

## Related Decisions

- adr-007
- adr-018

## Related Requirements

- rac-growth-adoption

## Related Roadmaps

- v0.13.0-guided-first-run
