# README & Onboarding Guide

Produces the document a new contributor reads first — and can work from without asking a question the document should have answered.

## Deliverable

One Markdown document, `readme.md`, in the structure set out under **Output** below. It is the entry point the rest of a project's documentation is reached from, and an input to **Documentation Audit**.

## Required inputs

- **Repository access** — the tree itself, including the build, dependency and configuration files.
- **A machine the setup can be run on** — every step in this document is executed before it is written down.
- **Who this is for** — someone new to the team, someone contributing from outside, or someone returning after a long absence; they need different things.

Without repository access, stop and report it. Without a machine to run the setup on the guide can still be written, but every step is marked `unverified` and the document says so at the top.

## Optional inputs

- The maintainers, and where they answer questions
- The review and contribution process, and the branch rules that go with it
- An existing onboarding document, and the questions it failed to answer
- The supported operating systems and the differences between them
- The accounts, credentials or access a contributor must request before starting
- Known setup failures and what they turn out to be

An absent optional input becomes a named gap in section 9, not a plausible sentence. A guide that guesses at the access a contributor needs sends them to the wrong person.

## Execution

**1 — State what this is and what it is not.** Two or three sentences: what the project does, who uses it, and the neighbouring things it is not. A contributor who has misunderstood the purpose will misread every instruction that follows.

**2 — Take the prerequisites from the project, not from habit.** Read the dependency, build and configuration files and take the required versions from them. Where a version is pinned, write the pin. Where a range is allowed, write the range. A version taken from what happens to be installed on one machine is a guess with a number on it.

**3 — Run the setup on a clean checkout and write down what you did.** Every command in the order it was run, including the ones that were needed and documented nowhere. If a step required access you already had, say so — it is a prerequisite the contributor does not have yet.

**4 — Run it, then test it.** Record the command that starts the project, what the reader should see when it worked, the command that runs the tests, and what a passing run looks like. A contributor who cannot tell success from silence will carry on and break something further along.

**5 — Map the tree.** The directories a contributor will touch, what lives in each, and where a new thing of each kind goes. Skip the parts nobody edits by hand; here they are noise.

**6 — Write the conventions a contributor would be corrected on.** Commit message shape, branch naming, formatting, the review a change must pass, and anything the project rejects automatically. An unwritten convention is a rule the newcomer finds out about in review.

**7 — Name where to ask.** The place questions go, who answers them, and what to include in the question. Then mark `unverified` every step you could not execute.

## Output

`readme.md`, in this order:

- **1. What this is** — purpose, who uses it, and what it is not
- **2. Prerequisites** — per requirement: what, the version the project requires, and the file that version was read from
- **3. Access and accounts** — what must be requested before starting, and from whom
- **4. Setup** — numbered commands, each with its expected result and whether it was executed
- **5. Running it** — the command, the expected output, and the common first failure
- **6. Testing** — the command, what a passing run looks like, and what to do with a failing one
- **7. Project layout** — directory, what lives there, and where new work of that kind goes
- **8. Conventions** — the rules a change is reviewed against
- **9. Where to ask and what is missing** — who answers, and every step marked `unverified`

## Validation

The document is ready when all of these hold:

- Every command in sections 4 to 6 was executed, or is marked `unverified`
- Every version in section 2 cites the project file it was read from
- Section 4 starts from a clean checkout and assumes no prior state
- Sections 5 and 6 each state what success looks like
- Section 1 says what the project is not, in at least one sentence
- No tool, service or account is named without telling the contributor how to obtain it

Fail the run if a version appears that was not read from a project file, or if a documented command was never executed and is not marked `unverified`.

## Failure handling

- **No repository access** — stop. Report that onboarding cannot be written from a description of a project.
- **The setup cannot be completed** — document up to the step that failed, record the failure and its exact message, mark the remaining steps `unverified`, and list the blocker in section 9. Do not write the steps you expect would follow.
- **Undocumented manual steps** — record them as steps with their own numbers, not as a note in the margin. The step someone does from memory is the step a newcomer never finds.
- **Prerequisites contradict each other across files** — record each version with the file it came from, mark the point `disputed`, and raise it in section 9 as blocking.
- **No named contact** — write `unknown` in section 9 and state that a contributor has nowhere to ask. A guide that ends with no route to a person stops working the first time it is wrong.