docs(readme): install and a runnable example come before the second showcase

[DemchaAV]

Why

Ninety-one lines and twelve <img> tags stood between the title and ## Installation. Most of that was a second showcase: the "One source → a PDF and an editable PowerPoint deck" section — thirty-five lines, two renders and a PowerPoint screenshot — sitting before the reader had seen a single line of the authoring API. A reader who came for a PDF met a @Beta deck exporter first.

And the first snippet they could copy was forty-two lines with eight imports and eight public types, two lines above a link to a tutorial whose own first example is sixteen lines and four types.

What changed

• The PPTX section moves below ### Next steps. After a reader has written a document, "the same session also emits a deck" reads as a payoff instead of a detour. ## Installation moves from line 92 to line 53: 52 lines and 9 images precede it, seven of the nine being badges. The banner render and ## Why GraphCompose deliberately stay above it — for a rendering library the output image is the reason to keep reading.
• Two directional words invert with the move and are fixed: See [Which artifact?](#installation) below → above, and the in-fence comment see Hello world below → above. The third, "the page below", is left alone — its referent travels with the block.
• The "Upgrading from 1.x / API stability" blockquote moves out of the header into ## Installation, where an upgrader is already headed.
• ## Hello world now leads with the sixteen-line example, copied verbatim from docs/first-document.md so the landing page and the tutorial teach the same first program. The styled block keeps its place directly beneath as ### Make it cinematic — which is what it was always demonstrating — and points at SectionPresetsExample and its committed preview, so the claim is shown rather than asserted.
• docs/capabilities.md is linked from ## Documentation. It had two inbound links in the whole repo, neither from the landing page.

What I deliberately did not do

No new PNG of the styled example. The plan called for one; the repository says no. CommittedAssetDriftTest asserts set equality on the files directly under assets/readme/ against RASTER_FIGURES — the enumerated register of figures nothing can verify. There is no example that renders a Hello-world page, so a new PNG could only be added by declaring it unverifiable, in the same release whose CHANGELOG states that a committed preview cannot fall behind the code that renders it. cut-release.ps1 stages only assets/readme/examples and the banner, so it would also freeze at whatever version it was first rendered at. Linking an existing, gate-covered preview says the same thing and stays true.

## Hello world keeps its heading text. README.md links #hello-world from the API table, CanonicalSurfaceGuardTest.publicMarkdownLinksShouldResolve skips # targets, and 13 files link README.md#installation. Heading text on this page is effectively public API; the new subheading is added below rather than replacing anything.

Verification

./mvnw -B -ntp clean verify — BUILD SUCCESS, exit 0, 692 tests in the closing module.

The guards that constrain this file specifically:

• DocumentationCoverageTest (5) — README must contain GraphCompose.document(, DocumentSession, document.pageFlow( and DocumentTextStyle. The styled block is the only source of the last two, which is why it is kept intact rather than trimmed; the new minimal fence keeps the variable named document, so it carries document.pageFlow( as well.
• DocumentationSnippetCompileTest (6) — the new fence carries <!-- doc-example: id=readme-root-minimal mode=method -->, an id that collides with none of the thirteen in use and sanitizes to a distinct unit name. Its body already compiled elsewhere under first-document-smallest.
• CanonicalSurfaceGuardTest (11) — every relative link still resolves.
• DocsBoldFaceGuardTest (1) — the styled block's FontName.HELVETICA + .decoration(BOLD) is untouched.

Diff is 71/39 on a 400-line file — checked, because this repo's autocrlf will otherwise present a whole-file rewrite.

Lane: docs. No production code, no public API.

[DemchaAV]

Blocker fixed, and you were right about the deeper problem: the sentence was mine and the gate could never have caught it. mode=method proves the body of a method compiles — the synthetic wrapper is exactly what made "that is the whole program" pass review by machine while being false to a reader.

The README example is now a complete file. class Hello { public static void main }, marker switched to mode=members to match the styled block below it. Twenty lines instead of forty-two, four types instead of eight.

Verified the way a reader would, not the way the gate does: extracted the fence verbatim from README.md into Hello.java, compiled it with javac against core + render-pdf (exit 0), ran it — hello.pdf, 893 bytes, starting %PDF-1.6. The prose now says "Save it as Hello.java and run it", which is literally true.

On docs/first-document.md I went a different way than you suggested, and it is worth saying why. That page has three consecutive snippets; wrapping each in main would repeat the boilerplate three times in a document whose subject is the flow, not Java syntax. So the roles are split instead: the landing page carries the runnable file, and the guide now states plainly that its snippets are statements which go inside a method, pointing at the README for the complete version. The dishonesty was the silence, not the fragment form. If you would rather have them identical, say so and I will convert all three.

Minor applied: SectionPresetsExample Javadoc no longer says "v1.4 / v1.5 section preset shortcuts" — the release labels are gone, matching the sweep in #491.

./mvnw -B -ntp clean verify — BUILD SUCCESS, 692 tests. DocumentationSnippetCompileTest 6, DocumentationCoverageTest 5, CanonicalSurfaceGuardTest 11 — all green; the styled block is untouched and still the sole carrier of DocumentTextStyle and document.pageFlow(.

Head is now 2d215efb.