docs(onboarding): lead the README with a first PDF, then route by task

[DemchaAV]

Why

The README put a tagline, a banner caption, five "Why GraphCompose" bullets and three collapsed install blocks (artifact matrix, fonts and emoji, distribution) ahead of the first line of code. It then ran through a styled hero, the PDF-and-PowerPoint figures, "What's new in 2.0", vector snippets, the architecture diagram and the scope-and-comparison section. Layout snapshots and visual diffs, which keep a production document from drifting, appeared in bullets and table rows but never as code. The hello world also called module(...) just after the README had used "module" for Maven artifacts.

Two of the six shipped template families had no route in. Receipt was named only on the layered-architecture page. Outside the CHANGELOG, rota appeared only in which-template-system.md, which said WeeklyScheduleTemplateV1 had no template although CobaltRota ships. No page listed the families.

Several task pages opened on history rather than a first example: recipes/tables.md on "Phase D of the v1.5 release", recipes/charts.md on how a ChartNode compiles. operations/test-your-document.md still called the pixel pattern test-only, and authoring-presets.md promised visual regression as a future phase, although PdfVisualRegression ships in graph-compose-testing.

What changed

README: one path, top to bottom

• The sections now run in this order:
  1. What it is.
  2. Create your first PDF: the dependency, a complete Hello.java and the four calls.
  3. Grow it into a real document: content modules, told apart from Maven modules, and a labelled bar chart.
  4. Keep production documents from drifting: graph-compose-testing, a LayoutSnapshotAssertions test and PdfVisualRegression.
  5. What to read next: one table routing to the first-document guide, recipes, templates, testing and production rendering.
• Output formats, scope and comparison, and architecture move into collapsed blocks.
• The module table sits under a which-artifact anchor and links every artifact's README. The ten module READMEs, and the template, quickstart and migration pages, point their "which artifact?" links there.
• installation, hello-world, architecture and what-graphcompose-is-not stay as explicit anchors, so existing links still land.
• The landing page drops the styled hero snippet, the twin-output figures, "What's new in 2.0", the vector snippets, the right-to-left and script-family bullets, the distribution notes and the PDFBox and POI badges. That material remains in:
  • the examples gallery;
  • recipes/text-direction.md and fonts/README.md;
  • the backend capability matrix;
  • CONTRIBUTING and the CHANGELOG.

Docs index and first document

• docs/README.md has a five-step learning path and an "I need to…" task table. Architecture, contributing and ADRs fold into one collapsed block.
• docs/first-document.md uses the README's program, names its four ideas and ends on a next-task table.
• getting-started.md and diagrams.md name all six families.

Templates

• New docs/templates/README.md lists every family with its preset count, data package and starting guide: invoice 11, proposal 4, receipt 1, rota 1, CV 26, cover letter 15.
  • It defines DSL, preset and template once.
  • It names where a preset's spec type comes from: the type parameter on its create(). The invoice family alone uses three.
• v2-layered/README.md gains the same families table and sends readers who only render to the overview.
• business-templates.md and quickstart.md say graph-compose-templates is not part of graph-compose.
• which-template-system.md maps WeeklyScheduleTemplateV1 to CobaltRota, which has create() only and takes StructuredRotaDocumentSpec.

Recipes and capabilities

• recipes.md now runs in three parts:
  • where content goes: a section, module or card takes the same blocks as the page, while a row takes a narrower set;
  • three task tables giving the smallest entry point for each feature;
  • the full catalogue.
• recipes/charts.md and recipes/tables.md open with a quick start and a common-changes table.
• capabilities.md adds multi-section documents, SVG icons and emoji, vector paths, sparklines, timelines, fixed width, per-page margins, translucency, keep-together, page previews, page zones, page references and the table of contents.
  • The 1.9.0 appendix folds into the main tables.
  • The 2.1.0 appendix goes. PowerPoint and keep-with-next have rows in the main tables, and slide sizes and backend selection by format are covered by getting started and the backend capability matrix.
  • buildPptx is listed with its Path argument.
• operations/test-your-document.md and authoring-presets.md say PdfVisualRegression is public. A new preset's checklist adds the layout snapshot and the pixel gate.
• The Twin Output row in examples/README.md no longer says the README shows its PowerPoint render.
• The knowledge/claims and knowledge/proofs indexes are regenerated for the recipes/tables.md line shift.

Verification

• CI's reactor gate passes with BUILD SUCCESS across 13 modules:

  ./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,:graph-compose-bundle,:graph-compose-qa,:graph-compose-coverage -am
  

  • Tests: core 762 (2 skipped), render-pdf 274, render-docx 94, render-pptx 138, templates 127, testing 5, qa 1777.
  • This includes the documentation link, recipe-catalogue, coverage and version guards.
  • It also includes DocumentationSnippetCompileTest, which compiles the README's three doc-example snippets.
• Knowledge pack:
  • tool fixtures pass 5/5;
  • extract-api --from-reactor --check reports the surfaces current;
  • check-stability-doc passes;
  • check-claims --check reports 46 claims and 10 proofs current;
  • check-routes reports 5 routes holding up.
• javadoc:javadoc -pl :graph-compose-core reports BUILD SUCCESS, and git diff --check is clean.
• Every Java name on an added line was checked with knowledge/tools/api-query, including those in table cells and in fences no test compiles. Inherited members were confirmed against the class declarations. Preset counts and data packages were checked against templates/src/main/java.

Notes for review

• No public API changes, so no CHANGELOG entry.
• The README's line saying Indic reordering is not performed is gone, and no other page says so.
• assets/readme/twin-output-{pdf,pptx,editing}.png no longer appear on any page, but CommittedAssetDriftTest still regenerates and checks them.

Lane: docs. Touches the README, docs/, the module READMEs, examples/README.md and the regenerated knowledge indexes; no code.