docs: rewrite the audit guide for its real audience (devs, auditors, white-hats)

Dropped the methodology meta-commentary (circularity, "not a finding") — it
serves the writer, not the reader — and rewrote security_report.md as a field
guide with a clear arc: the CVE record is empty and the fix history is the real
map, here is where the bugs live and what they look like, here is the leverage of
eleven implementations of one spec (variant hunting / spec-divergence → chain
split), then case studies, lessons, and a playbook. Tightened prose to cut
AI-tells (em-dash overuse, "not X but Y", hedging asides). analysis.md §7
similarly trimmed; README severity note and doc pointer updated (removed the
dangling §7 reference).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grandchildrice

README.md

@@ -128,9 +128,9 @@ The bounty's **scope is exactly this corpus** — the eleven clients plus
 `c-kzg-4844` and the deposit contract. Three consequences shape the `severity`
 column:
 
-- **~94% of rows are `Unrated`.** Clients patch silently, so the bug was never
-  submitted or graded. **Unrated ≠ low impact** — see
-  [`security_report.md`](docs/security_report.md) §7.
+- **~94% of rows are `Unrated`.** Most fixes ship with no CVE or advisory, so the
+  bug was never graded. **Unrated ≠ low impact** — the fix record, not the CVE
+  list, is the map (see [`security_report.md`](docs/security_report.md)).
 - **Two severity models coexist.** A minority of rated rows are *upstream
   dependency CVEs* (log4j, Netty, `golang.org/x/crypto`) carrying **CVSS**
   severity — a dependency bug does not split the Ethereum network, so it is out of
@@ -218,7 +218,7 @@ docs/            BUILD_REPORT · IMPROVEMENT_LOG · silent_fix_detection · mode
 
 ## Documentation
 
-- [`docs/security_report.md`](docs/security_report.md) — 🔎 **Audit field guide** — where to look (the priority map: which source-code regions concentrate severe bugs), the attack surface, the recurring vulnerability patterns, cross-implementation variant hunting, and lessons transferable to any blockchain / consensus system
+- [`docs/security_report.md`](docs/security_report.md) — 🔎 **Auditing Ethereum clients: where the bugs actually live** — a field guide for client devs, audit firms, and white-hats: where to look, the six recurring bug patterns, the attack surface, and the cross-implementation variant hunting that turns one client's fix into a lead on another's live bug
 - [`docs/analysis.md`](docs/analysis.md) — **what the data says** (silent-fix majority, availability-first vuln profile, cross-language diversity), read through the dataset-research literature
 - [`docs/limitations.md`](docs/limitations.md) — **honest inventory of coverage gaps & caveats** (read before relying on the data)
 - [`docs/severity_labeling.md`](docs/severity_labeling.md) — **methodology**: LLM severity estimation against the bug-bounty model (decompose → map → calibrate)

docs/analysis.md

@@ -119,28 +119,23 @@ across implementations. It is the diversity dimension DiverseVul and CrossVul
 argue reduces overfitting, obtained here **within a single well-specified
 domain**.
 
-## 7. Severity — what the bounty counts, and what we can honestly say
-
-Severity here is the **Ethereum Foundation bug-bounty** grade: an impact reachable
-by a single packet / on-chain tx that splits the chain, takes the network down,
-corrupts value, or slashes validators (not CVSS). Two honest caveats bound what
-this dataset supports:
-
-- **Remote reachability is part of the *definition*, not a finding.** Because a
-  bug is only graded when it is remotely triggerable, "reachable bugs are the
-  severe ones" is true *by construction* — not an empirical result. What the data
-  adds is *where the impactful code is*: consensus / EVM / crypto for
-  chain-split/value bugs, p2p / sync / RPC for DoS (the audit priority map,
-  [`security_report.md`](./security_report.md) §2).
-- **Only 6.4% of rows were bounty-graded.** The rest are LLM-*estimated*
-  ([`severity_labeling.md`](./severity_labeling.md)), and that estimate is derived
-  partly from `root_cause` / `attack_path` — so we deliberately draw **no**
-  "root-cause X raises severity" conclusion from it, which would be circular.
-  Treat `severity_estimated` as a triage prior and filter to
-  `severity_source == bounty-graded` for ground truth. Note also that a graded row
-  reflects **disclosure policy** (which clients publish advisories), not relative
-  security posture, and fix size does **not** separate severity (median ~51 LOC
-  high vs 45 overall) — you cannot spot a critical bug by diff size.
+## 7. Severity
+
+Severity follows the **Ethereum Foundation bug bounty**, not CVSS: the grade
+reflects how much of the network a single packet or transaction could split, halt,
+or corrupt. That impact model is what makes crypto, the EVM, and the consensus
+state transition the regions to watch for critical bugs, and p2p / sync / RPC the
+regions to watch for denial of service (audit guide,
+[`security_report.md`](./security_report.md)).
+
+Only 6.4% of rows carry a real bounty grade; the rest are estimated
+([`severity_labeling.md`](./severity_labeling.md), about 60% exact and 80% within
+one tier on known-severe bugs). Take the graded slice
+(`severity_source == bounty-graded`) as ground truth and the estimates as a triage
+prior. Two things the graded slice does *not* tell you: it tracks which teams
+publish advisories more than which clients are safer, and fix size does not track
+severity (median 51 vs 45 LOC), so neither is a shortcut to finding the severe
+bugs.
 
 ## 8. Data quality and coverage