# Architecture

README Harness has one public build function and one read-only review boundary.

```text
user request + repository
          │
          ▼
       writer
          │ draft + compact facts
          ▼
build_readme ── scan / Markdown / command / path / link / secret checks
          │
          ├─ facts.json
          ├─ validation.json
          ├─ README.generated.md
          └─ README.patch
          │
          ▼
read-only reviewer ── review.json ── one revision at most
```

`README.generated.md` is normal GitHub Markdown. Fact bindings live in
`facts.json` and address a natural document block by section, block number, and
text hash. The target README changes only through the explicit `apply` command.