DOCS — Public `README.md` scaffold

README.md is the first file a new reader (human OR agent) opens. One file, nine sections, in this order. Keep ≤ 300 lines; longer material lives in docs/.

Nine-section template:

# {{PROJECT_NAME}}

> One-line pitch (what + why, ≤ 100 chars).

[![CI](badge)](link) [![License](badge)](link) [![Version](badge)](link)

## What
2-3 sentences: what it does, who it's for. No marketing adjectives.

## Why
2-3 sentences: problem this solves, alternatives considered, why this one.
Link to the relevant ADR: [DECISIONS.md](DECISIONS.md#adr-nnnn).

## Install
```bash
# Primary path — the 90% case
<one command>

Prerequisites: = vN, OS constraints, system deps>.

Usage

Smallest working example. Copy-pasteable.

<command producing visible output>

Link to a richer quickstart in docs/quickstart.md if >20 lines.

Development

git clone <repo>
cd <repo>
<bootstrap command, e.g. cargo build>
<test command>

Project layout:

src/ — implementation
tests/ — integration tests
docs/ — long-form docs
`{{STACK}}-specific notes → link>

Deploy

Target: {{DEPLOY}}. One-liner: <deploy command>. Full runbook: docs/runbooks/deploy.md.

Architecture

One paragraph + one Mermaid diagram (see _blocks/docs-architecture-diagrams.md). Detail in docs/architecture.md.

Contributing

Issue tracker:
Commit convention: Conventional Commits (see _blocks/git-conventions in kit)
PR checklist: docs/CONTRIBUTING.md

License

— see LICENSE.


**Rules:**
- No secrets (RULE 0.8). No literal tokens.
- Install command must be ONE command for the happy path.
- Every "see docs/X" link must resolve — scaffolder verifies or creates the target.
- If the project is private / not publicly deployable (banned list per `rules/security.md`), mark the repo header with `<!-- PRIVATE — do not publish -->` and omit public badges.

**Source:** standard-readme spec (RichardLitt/standard-readme) [E4]; GitHub "About READMEs" [E4].

2.1 KiB Raw Blame History

DOCS — Public README.md scaffold