# Project Root README

Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.

### Strategy

The root README answers, in order:

1. **What is this?** — one to two sentences, no marketing claims
2. **What do I get if I install it?** — capability families
3. **What's it built on?** — terse stack list with versions
4. **How do I run it?** — the three or four scripts that matter
5. **How is it laid out?** — directory tree, one-liner per significant folder
6. **How do I extend it?** — numbered contribution checklist
7. **What state is it in?** — pre-publish, beta, stable, internal

Skip any section that doesn't apply. Don't pad to fill the template.

### Writing rules

- **Sentence-case headings.** "Getting started", not "Getting Started".
- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
- **Directory tree as a code block**, not a nested markdown list.
- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.

### Template

```markdown
# {package-name}

{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}

## What's in the box

- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
- **{Family 2}** — {what's in it.}
- **{Family 3}** — {what's in it.}

The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries

## Stack

- {Framework} {version} · {Language} {version}
- {Build tool} {version}
- {Other load-bearing deps}

## Getting started

\`\`\`bash
{pm} install
{pm} run dev        # what it does (port, URL)
{pm} run build      # what it does
{pm} run preview    # what it does (omit if not applicable)
\`\`\`

{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}

## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"

{Brief description of the dev/runtime surface.}

| {Thing}              | {What it shows / does} |
| -------------------- | ---------------------- |
| `{route or command}` | {description}          |

## Layout

\`\`\`
src/
├── {entry-file}        # {purpose}
├── {folder}/           # {purpose}
│   └── ...
└── {folder}/           # {purpose}
\`\`\`

## Adding a {primary unit}

1. {Drop the source under the right family/folder.}
2. {Re-export from the public surface.}
3. {Wire into the playground / example app / test harness so reviewers can see it render.}
4. {Document any divergence from upstream in `docs/{...}`.}

## Styling ← optional; replace with whichever cross-cutting concern matters most

{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}

## Status

{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}

## License

{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
```

### Baseline scaffolding behavior

The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.

**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.