---
schema_version: 1
id: RAC-KTW0M84YXJ5A
type: roadmap
---
# RAC v0.10.1 — Guide Onboarding

## Status

Planned

## Context

v0.10.0 delivers a working server; this milestone makes it adoptable. An MCP
server nobody can configure in under five minutes will not be adopted, and a
server that only works against artifacts the user must author first will not
be tried at all.

Distribution is part of the product, not an afterthought. The Agent Context
Guide requirement (REQ-004) sets the bar: zero-flag startup, verified
copy-paste configuration for the three target clients, and an examples
corpus a new user can point the server at immediately.

## Outcomes

- A user on a clean machine goes from `pip install requirements-as-code` to
  a connected agent client in under five minutes using only the
  documentation.
- Each target client — Claude Code, Claude Desktop, Cursor — has one
  verified copy-paste configuration block.
- A new user can demo Guide against a shipped examples corpus without
  authoring artifacts first.

## Initiatives

### Initiative 1 — Zero-Flag Startup Hardening

`rac mcp` from a repository root works with no flags. When the root contains
no RAC corpus, the server starts and reports the empty state helpfully on
stderr and through `get_summary`, rather than failing opaquely — the first
run is most likely to be the misconfigured one.

### Initiative 2 — Verified Client Configuration

Copy-paste configuration blocks for:

- Claude Code (`claude mcp add` command form and `.mcp.json` form)
- Claude Desktop (`claude_desktop_config.json` `mcpServers` entry)
- Cursor (`.cursor/mcp.json`)

Each block is exercised against the named client before the documentation
merges, and instructions are pinned to the client versions they were
verified against.

### Initiative 3 — Examples Corpus

A small, valid RAC corpus under `examples/guide/` — one connected
requirement, decision, design, and roadmap with its own `.rac/config.yaml`
— that `rac mcp --root` can serve immediately. The corpus doubles as the
substrate the v0.10.2 demo scenario builds on, and leaves the existing
`examples/example_dashboard_v*.md` walkthrough files untouched.

## Constraints

- Documentation-and-packaging milestone: no tool surface changes, no new
  Core capability, no JSON contract changes (ADR-007).
- The examples corpus passes `rac validate` and relationship validation.
- Configuration blocks are verified against current client versions, not
  assumed from client documentation.

## Non-Goals

- The demo script, measurement, and recording (v0.10.2)
- Registry submission and announcement (v0.10.2)
- Supporting every runner (`uvx`, etc.); the supported path is documented,
  alternatives are not chased in v1

## Implementation Contract

The following decisions are pinned for v0.10.1.

### Documentation Locations

- The README gains a Guide section: what it is in two sentences, the three
  client configuration blocks, and a pointer to the examples corpus.
- `docs/mcp.md` carries the full onboarding path: install, configure per
  client, point at a repository, first grounded question, troubleshooting
  (server not listed, wrong root, empty corpus).

### Examples Corpus

- `examples/guide/.rac/config.yaml` plus `examples/guide/rac/` containing
  one requirement, one decision, one design, and one roadmap, connected
  through their relationship sections.
- Artifact IDs are minted with `rac migrate metadata` against the example
  corpus's own repository key.

### Verification

- Each configuration block is verified by connecting the named client and
  exercising at least `get_summary` and one `get_artifact` call against
  the examples corpus; the verifying client version is recorded in the
  documentation.
- At least one configuration block is verified by someone other than the
  author before release.

### Testing

- The examples corpus joins the dogfood validation path so corpus
  regressions fail CI.
- Startup behaviour for a root without a corpus is covered in the `mcp`
  battery (helpful stderr, functional `get_summary`).

## Success Measures

- Clean-machine walkthrough: nothing to grounded answer in under five
  minutes using only the README.
- Three verified configuration blocks, each pinned to a client version.
- Zero onboarding steps require flags beyond the optional `--root`.

## Risks

- Client configuration formats drift between verification and a user's
  install. Mitigated by pinning instructions to verified client versions
  and re-verifying at release.
- The examples corpus reads as a toy. Mitigated by reusing the
  true-to-life bar from the demo design for its decision artifact.

## Assumptions

- The PyPI publishing pipeline handles the `mcp` dependency without
  changes.
- The three named clients remain the right target set at release time.

## Related Decisions

- ADR-029
- ADR-007

## Related Designs

- guide-tool-surface
- guide-grounding-demo

## Related Requirements

- rac-agent-context-guide

## Dependencies

- v0.10.0 server and tool surface
