# New User Onboarding

Status: Draft

## User Problem

New users need to understand that Singularity Forge is the current product, where decisions live, and how to make changes without breaking repo memory.

## Goals

- Orient a new user from the root docs in under a few minutes.
- Make the canonical homes for specs, design docs, plans, generated references, and records obvious.
- Explain what verification is expected before closing work.

## Non-Goals

- Do not define a marketing journey.
- Do not choose a runtime or frontend framework in this spec.
- Do not require a production onboarding flow before the product surface exists.

## First-Run Experience

Until a runtime exists, onboarding is documentation-based:

1. Start with root `AGENTS.md`.
2. Read `ARCHITECTURE.md` for current state, boundaries, and invariants.
3. Read `docs/PLANS.md` and `docs/exec-plans/active/` for current work.
4. Read `docs/QUALITY_SCORE.md`, `docs/RELIABILITY.md`, and `docs/SECURITY.md` before behavior changes.
5. Use `docs/RECORDS_KEEPER.md` after meaningful changes.

## Success Criteria

- The user can identify the canonical doc for a product decision, architecture decision, active plan, generated artifact, or records note.
- The user can name the command or eval expected to prove their change.
- The user can tell that active CLI source is in `/home/mhugo/code/singularity-forge`, while this `singularity-foundry` checkout is legacy context.

## Failure States

- A new user infers production behavior from placeholders.
- A source change happens without a spec, plan, test, or eval.
- A durable decision is left only in chat or a temporary note.

## Verification

```sh
find . -maxdepth 4 -type f -name '*.md' -print
```
