docs(api): fix rich(...) lambda examples that render empty paragraphs - #537

Problem

ParagraphBuilder.rich(Consumer<RichText>) and AbstractFlowBuilder.addRich(Consumer<RichText>) documented the lambda form as t -> t.text("Status: ").bold("Pending"). RichText.text(String) is a static factory, and Java resolves a static call made through an instance reference — so the documented line compiles, builds a separate RichText, discards it, and the builder the consumer was handed stays empty. A reader copying the example gets a paragraph that renders no text at all: no compiler warning, no exception.

The shape-as-container recipe carried a second rotted snippet, building its callout body with RichText.of() — a factory that has never existed (git log --all -S 'static RichText of(' comes back empty). It escaped DocumentationSnippetCompileTest because compile coverage under docs/ is opt-in per fence, and that fence references a bare document variable, so it cannot be marked without scaffolding.

Fix

• Both examples now seed the supplied builder with plain(...) — the instance method that appends a plain run — and each Javadoc says why t.text(...) must not be used there.
• RichText.text(String)'s own Javadoc spells out the trap, and the class Javadoc gains a correct lambda example next to the standalone-chain one, so every page a reader lands on tells the same story.
• docs/recipes/shape-as-container.md builds the callout with RichText.text("Status: ").bold("Pending").
• An instance text(String) was considered and rejected: Java forbids a static and an instance method with the same signature in one class (the pair cannot even coexist with the static deprecated), so it would mean deleting the 1.0.0-era static factory used across tests, examples and recipes — a source- and binary-breaking change on a patch line. A runtime "empty builder" guard in rich(Consumer) is also off the table: leaving the builder empty after conditional appends is a legitimate live pattern in templates, so throwing would be a behaviour break.
• CHANGELOG entry under ## v2.1.2 — Planned / ### Documentation.

A sweep of core, templates, examples, docs/** and the local wiki found no call site hitting the trap — the broken pattern existed only in the two Javadoc examples, so no rendered output changes anywhere.

Verification

./mvnw -B -ntp clean verify -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-templates,:graph-compose-testing,:graph-compose-qa,:graph-compose-coverage -am on the current develop head → BUILD SUCCESS, all coverage checks met. ./mvnw -B -ntp javadoc:javadoc -pl :graph-compose-core → BUILD SUCCESS. +1 test: RichTextTest.documentedRichLambdaSeededWithPlainProducesNonEmptyParagraph pins the documented lambda form to a non-empty, correctly-styled paragraph (RichTextTest 26/26 green).

Lane: canonical (document.dsl Javadoc + docs recipe + qa test) — no behaviour change, no public API change.