# Project root README (/README.md)

Truth document. Use for: the repository root `/README.md`. It opens outward — what the product does, for whom, and where it runs, in a user's terms — then turns inward for the team and coding agents: what state the repo is in, how it works, what its parts are and what must not break, then routes every other question into `docs/`. The outward part comes first because it is what a stranger reads; the inward part is longer because it is what the team uses. **It hosts nothing it can link to.** It is distinct from `docs/README.md`, which describes the folders of the docs tree, and from `CLAUDE.md` / `AGENTS.md`, the standing rules an agent loads. It points at both and restates neither.

### What it carries

Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onward the inward page. Skip any section the repo cannot fill truthfully. Never pad it, and never leave a stub.

1. **Identity.** The H1 plus two or three sentences in a user's terms: what the product is, where it runs, and what using it is like.
2. **Capabilities.** Two to four paragraphs, outward-facing: the core loop as a person meets it, what surrounds that loop, how the product follows the person across its surfaces, and who it is for, closing with what it deliberately is not. Plain words, no feature roster, no superlatives.
3. **Deployment.** One paragraph: the addresses, the distributed artifacts and where they are published, where identity comes from, and whether a self-hosted edition exists.
4. **The turn.** A rule and one paragraph saying the rest is for the team and agents, with the scope line: what lives in this repo and what lives elsewhere.
5. **State.** Optional: a one-line blockquote, present only while something repo-wide is true that a newcomer must know (frozen, mid-migration, mid-breaking-change on `dev`). It links the plan or runbook that owns the change. Say here which units publish and where, if any do.
6. **The main path.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
7. **Repository map.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
8. **Load-bearing rules.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
9. **Destinations.** An intent-to-destination table. Its last row is the one for agents.
10. **Everyday commands.** Optional. At most four commands run on every change, ending at the gate a push must pass. First-run commands are never here.

### What it leaves out

| Left out | Lives in |
| --- | --- |
| Getting started, install, prerequisites, env files, first run, troubleshooting | `docs/operations/setup.md` |
| Stack: technologies, what each is for, where its version is pinned | `docs/operations/setup.md` § Stack. Why it was chosen goes in `docs/architecture/` |
| Directory or file tree | `docs/structure.md`, the only tree |
| Daily loop, watch modes, per-package traps | `docs/operations/local-development.md` |
| Contributing procedure, branch model, commit rules | `CLAUDE.md` and `docs/operations/` |
| Feature list, news, "what's new", roadmap, changelog | `docs/features/`, `docs/history/` |
| Badges, logos, images, screenshots, social links, sponsors, hand-written TOC, license text, superlatives | Nowhere. The outward sections are plain prose too. Agents cannot read them and the team does not need them. License is one line or absent |

### Writing rules

- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Load-bearing rules read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
- **Every section is either a fact the reader acts on or a link.** If a section needs a paragraph, it needs a doc.
- **One H1, then H2 sections, in plain Markdown.** Sentence-case headings, no emoji, no HTML layout, and no `#` comment lines inside code blocks (they parse as H1s).
- **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md`, `AGENTS.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
- **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
- **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc the index resolves for that path. When the two disagree the index wins, and the Map row is fixed in the same change.
- **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
- **State rules, don't argue them.** One line each. The reasoning lives in the linked doc, and agent process rules stay in `CLAUDE.md`.
- **Commands come from the repo.** Detect the package manager from the lockfile (`pnpm-lock.yaml` gives pnpm, `yarn.lock` gives yarn, otherwise npm). Use only scripts that exist, each with a trailing comment saying what it does.

### Template

```markdown
# {Project name}

{Two or three sentences in a user's terms: what the product is, where it runs, what using it is like.}

## Capabilities

{The core loop as a person meets it: what they bring, what the product does, what they get back and what record it leaves.}

{What surrounds the loop: the capabilities a team needs to run it, named plainly.}

{How it follows the person across surfaces: CLI, desktop, integrations, agents' doors.}

{Who it is for, and what it deliberately is not.}

## Deployment

{Addresses; distributed artifacts and where they publish; where identity comes from; whether a self-hosted edition exists.}

---

The rest of this page is for the team and for coding agents working in this repository. {What lives in this repo and what lives elsewhere.} {One sentence: the sections below route every other question into docs/.}

> **State:** {one line: what is in flux right now; which units publish where} → [{plan or runbook}](docs/history/{plans|migrations}/{file}.md) ← optional; delete when the flux ends

## The main path

1. **{Stage}**: {what happens, naming the mechanism only where it explains the step}.
2. **{Stage}**: {…}.
3. **{Stage}**: {where state lives}.
4. **{Stage}**: {the outbound effect: what is written, deployed or returned}.

{Optional, one sentence naming the seam everything passes through, e.g. "Every client reaches data through `{path}`; nothing else talks to the database."} The full account: [{system overview}](docs/architecture/{overview}.md).

## Repository map

{One or two sentences: the workspace shape and where each unit's design document lives.}

| Path | Role | Owning doc |
| --- | --- | --- |
| [`{packages/unit}/`]({packages/unit}/) | {one line: what it is and who consumes it} | [{doc}](docs/architecture/packages/{unit}.md) |
| [`{packages/unit}/`]({packages/unit}/) | {one line} | [{doc}]({path}) |
| [`{top-folder}/`]({top-folder}/) | {one line; "generated" or "reference only" where true} | — |

{One sentence each for the top folders that are not packages — `registry/`, `scripts/`, `docs/` — with their owning doc.} Where every doc lives: [docs/structure.md](docs/structure.md).

## Load-bearing rules

{One sentence saying these are stated here and argued in the documents they point at.}

- **{Invariant}**: {the rule, one line}. → [{source}]({path})
- **{Boundary}**: `{path}` is the only {public | published} surface; everything else is internal.
- **{Never-edit paths}**: `{path}` is {generated by `{command}` | protected}; edit {the source} instead.
- **Not here:** {a non-goal stated as a refusal}.

## Destinations

| Intent | Destination |
| --- | --- |
| Set up a machine and run it the first time | [docs/operations/setup.md](docs/operations/setup.md) |
| Work on it day to day | [docs/operations/{local-development}.md](docs/operations/{local-development}.md) |
| Understand the design | [docs/architecture/](docs/architecture/) |
| Change a feature | [docs/features/](docs/features/), found through the ownership index |
| Change a contract ({db schema · wire envelope · auth · events · env}) | [{contract doc}]({path}), boundary-checked before the change |
| Ship or release | [docs/operations/{deployment}.md](docs/operations/{deployment}.md) |
| Place a new doc | [docs/structure.md](docs/structure.md) · [docs/README.md](docs/README.md) |
| See what changed and what is open | [CHANGELOG](docs/history/CHANGELOG.md) · [backlog](docs/history/backlog.md) |
| Work here as a coding agent | [CLAUDE.md](CLAUDE.md) ([AGENTS.md](AGENTS.md) for other runtimes): load before any edit |

## Everyday commands

\`\`\`bash
{pm} {typecheck}     # {what it checks}
{pm} {test}          # {the unit suite, from a cold shell}
{pm} {gate}          # {what a change must pass before it is pushed}
\`\`\`

`{pm} --filter <unit> run` lists a unit's own scripts.

{License, one line, e.g. "UNLICENSED, internal use only."} ← optional
```

### Baseline scaffolding behavior

The baseline **does** scaffold `/README.md` when it is missing, and it fills each section from the repo:

- **Identity, Capabilities, Deployment:** from the product charter and vision documents under `docs/architecture/doctrine/` (what the product is, the core loop, who it is for), the package manifests (what publishes where), and the deploy config (addresses). Written in a user's terms; where the charter is missing, the baseline writes Identity only and raises a `note:` row for the rest.
- **The main path:** from the system overview.
- **Map:** from the workspace globs and the ownership index.
- **Rules:** from `docs/operations/protected-files.md` and the architecture doctrine.
- **Commands:** from the lockfile and the root scripts.
- **Destinations:** only the rows whose targets exist.

It drops every section it cannot fill concretely.

**It never overwrites an existing root README.** If one is present, even sparse or outdated, the baseline leaves it untouched and raises a `note:` row proposing the reshape. Reshaping is a separate, explicit request. When it runs, each removed section moves in the same change: getting-started, install and env content and the Stack go to `docs/operations/setup.md`, a drawn tree becomes the Map (the tree itself stays in `structure.md`), and a contributing checklist goes to `docs/operations/`. Nothing is deleted without a home.