docs(benchmarks): add honest-framing README for the manual benchmark layer (B1)

[DemchaAV]

Summary

Wires up Track B1 — the honest-claims prerequisite before the 1.6.6 Maven Central debut. The benchmarks/ module has no README.md today; this PR adds one and pins the framing.

The page's load-bearing message: the manual benchmark harness is a smoke / diff / endurance tool, not a JMH-grade benchmark. Once GraphCompose ships on Maven Central, downstream callers will read the repo before deciding whether to adopt it; any number quoted from this layer in marketing copy would set false expectations and get torn apart on Hacker News. This page exists to make it embarrassing for any maintainer (or AI agent) to do that without thinking.

What the page covers

Section	What it answers
What this is / is not	Manual harness, not JMH-grade. No warmup control, no forked JVM, no GC profiling rigour.
When to use	Smoke before release, pre/post diff on one machine, stress / endurance overnight runs.
When not to use	Publishable "X% faster than Y" claims. Architectural decisions (pick the right invariant, not a number). Cross-library comparisons that read too much into a single point.
Files in this module	Role table for each *.java — CurrentSpeedBenchmark is the CI smoke runner, ComparativeBenchmark is the iText / openHTMLToPDF / JasperReports comparison (rough local only), etc.
Running	Exact mvnw exec:java invocations matching the CI perf-smoke job — taken straight from ci.yml after PR-7.1 / PR-83 cleanups.
How to read a report	What avgMs / p95Ms / docsPerSec / avgKB / peakMB mean and the limits of each.
Roadmap	Cross-links Track C (B3 → B4 → B5 → B6) in the 1.7.0 plan as the JMH layer that will replace this for rigorous measurements.

Why now (and why this scope)

The B1 row in the readiness taskboard is a soft prereq for the 1.6.6 cut — explicitly because honest framing has to be in place before Maven Central traffic starts looking at the repo. The taskboard's exact wording:

B1 (честные claims) — soft-prereq публичного 1.6.6 (первый Central publish, нужно убрать преувеличения «faster than X» из публичной коммуникации).

Scope is intentionally one file plus a CHANGELOG entry — no measurement-code changes, no fixture restructuring. Those land in Track C (1.7.0).

Verification

$ ./mvnw -B -ntp test -pl . -Dtest='CanonicalSurfaceGuardTest,DocumentationCoverageTest'
Tests run: 7, Failures: 0, Errors: 0, Skipped: 0

benchmarks/README.md contains no legacy-API tokens so no
CanonicalSurfaceGuardTest allowlist entry is needed. (The legacy
inventory in G1 / G3 was the explicit reason for those allowlist
entries; this page doesn't name legacy types — it talks about benchmark
methodology.)

CHANGELOG entry added to v1.6.6 — Planned under ### Build.

Test plan

• Doc guards green locally
• CI green on PR (Guards / JDK 17/21/25 / Examples Smoke / no-poi-suite / binary-compat)
• Reviewer skim — "What this is / is not" + "When not to use" are the load-bearing sections; the rest is mechanical role / invocation documentation
• (Out of scope) follow-up: once Track C B3-B6 ships the JMH layer, update the "Roadmap" section to point at it as the supersedure path