---
schema_version: 1
id: RAC-KV2E55ZGZX8W
type: roadmap
---
# RAC v0.13.0 — Guided First Run

## Status

Planned

## Context

The Adoption Surface requirement (`rac-growth-adoption`) sets a
five-minute cold-start budget: install, then reach a first artifact that
passes `rac validate`. Today that path is three commands a new user must
assemble themselves — `rac init`, then `rac new <type> <path>`, then
`rac validate <path>` — and `rac new` fails outright until `rac init`
has run, so the ordering is load-bearing and unforgiving. Every extra
command before first value loses evaluators, and the first run is the one
most likely to stumble on the ordering.

`rac-growth-adoption` REQ-005 already records the fix as a proposed RAC
core change: a guided first-run path that establishes identity and
scaffolds a first artifact in one step. This milestone implements it and
un-defers REQ-005. It collapses the cold start from three commands to
one, printing the single next step (`rac validate`) so the loop stays
visible rather than memorised.

The scaffold writes one artifact into the corpus. That brushes against
ADR-018 (the `rac/` directory is the knowledge root, not imposed
structure) and ADR-024 (RAC is not a content store): RAC creates
identity configuration, never content. ADR-044 records the narrow
exception — a one-time onboarding convenience that writes a single
starter artifact only into an empty corpus, never managing content
thereafter.

## Outcomes

- A new user goes from a clean checkout to a first artifact passing
  `rac validate` with one command instead of three.
- The command refuses to touch an already-initialised or non-empty
  corpus, so it is safe to run by mistake and never overwrites work.
- The existing `rac init`, `rac new`, and `rac validate` commands keep
  their current contracts unchanged; the guided path composes them, it
  does not replace them.
- The five-minute cold-start claim in `rac-growth-adoption` becomes
  reachable in a single step, ready for the timed measurement REQ-003
  records.

## Initiatives

### Initiative 1 — Quickstart Service

A `quickstart` service in the services layer composes the existing
identity and creation capabilities: establish the repository key
(reusing `init_repository`), then create one starter artifact (reusing
`create_artifact`) under the conventional `rac/<family>/` path. It owns
the empty-corpus safety check and a single result model, so the CLI and
any future consumer (Explorer, an IDE action) share one onboarding path.

### Initiative 2 — `rac quickstart` Command

`rac quickstart [DIR] [--key KEY] [--type TYPE]` runs the service and
prints, in human mode, what it established, what it created (id and
path), and the single next step: `rac validate <path>`. `--json` emits
the stable contract (ADR-007). The command never overwrites: an existing
`.rac/config.yaml` with a different key, or a corpus that already holds
artifacts, is refused before anything is written.

### Initiative 3 — First-Value Documentation

The README "Author and enforce artifacts" section and the quickstart
docs lead with `rac quickstart` as the one-command path, keeping the
explicit `init` → `new` → `validate` sequence documented underneath for
users who want the steps.

## Constraints

- The scaffold writes exactly one artifact and only when the corpus is
  empty (ADR-044). RAC does not manage, update, or track that artifact
  afterwards — it is a starting point, not owned content.
- Identity assignment stays with `create_artifact`: the starter artifact
  carries a system-assigned opaque id (ADR-026) like any other.
- The command composes existing services; it introduces no new
  validation, classification, or template logic.

## Non-Goals

- A multi-artifact scaffold, sample corpus, or example library
  (`rac-growth-adoption` keeps the demo corpus a documentation concern).
- An interactive wizard or prompts beyond the existing one-time
  usage-sharing question (ADR-041).
- Changing `rac init` or `rac new` semantics, or adding an implicit init
  to `rac new` (the v0.7.11 no-implicit-init contract stands).

## Implementation Contract

The following decisions are pinned for v0.13.0.

### Command

- `rac quickstart [directory] [--key KEY] [--type TYPE] [--json]`.
- `directory` defaults to the current directory; `--key` defaults to
  `RAC` (the `rac init` default); `--type` defaults to `requirement`.
- The starter artifact path is `<directory>/rac/<family>/first-<type>.md`
  where `<family>` is the type's plural directory used elsewhere in the
  corpus (`requirements`, `decisions`, ...); parent directories are
  created.

### Behaviour and exit codes

- Success: establish the key (idempotent if already set to the same
  key), create the starter artifact, exit 0.
- Refuse (exit 1): the corpus already contains a recognised artifact, or
  the established key conflicts with `--key` — nothing is written.
- Usage error (exit 2): `directory` is not a directory, or `--key` fails
  the key syntax — matching `rac init` and `rac new`.

### Output

- Human: "Initialized repository key KEY", the created id and path, then
  "Next: rac validate <path>".
- `--json`: `{schema_version, repository_key, config_path, created,
  artifact: {type, path, id}}` — additive over `rac init`'s contract.

## Success Measures

- From a clean directory, `rac quickstart` followed by `rac validate` on
  the printed path exits 0 — a two-command cold start, one of them the
  validation check itself.
- Running `rac quickstart` again, or in a corpus that already has
  artifacts, exits 1 and writes nothing.
- The created artifact is byte-compatible with one produced by
  `rac init` + `rac new` of the same type (same frontmatter shape, a
  valid opaque id).

## Risks

- Writing content during onboarding could be read as RAC owning content,
  against ADR-024. Mitigated by ADR-044's narrow scope: one artifact,
  empty corpus only, never tracked afterwards.
- The starter path convention could diverge from how a user organises
  their corpus. Mitigated: it is a conventional starting point the user
  is free to move; RAC imposes no structure (ADR-018).

## Assumptions

- Python 3.11+ and a writable working directory, as the rest of the CLI
  assumes.
- `requirement` is the most useful default first artifact; the maintainer
  can revisit the default without changing the contract.

## Related Decisions

- adr-018
- adr-021
- adr-024
- adr-026
- adr-044

## Related Requirements

- rac-growth-adoption

## Related Roadmaps

- v0.13.1-friendly-empty-corpus
