docs: add per-module READMEs

aggregator/README.md

@@ -0,0 +1,22 @@
+# GraphCompose Build Aggregator
+
+**Internal reactor module — not published to Maven Central.** Do not depend on it.
+
+`aggregator/` (artifact `graph-compose-build`) is the non-published reactor parent that builds
+the whole project in one pass — the engine and its sibling modules plus the `examples`,
+`benchmarks`, and `qa` children. It exists to give a single build entry point and to host the
+aggregator-child modules (examples / benchmarks / qa) that inherit their version from it.
+
+The **published** artifacts (`graph-compose-core`, `graph-compose`, the render backends,
+`graph-compose-templates`, `graph-compose-testing`, `graph-compose-bundle`) are standalone
+poms — they do **not** use this aggregator as their Maven parent; it only lists them as
+`<modules>` so a single reactor build compiles everything.
+
+Build everything:
+
+```bash
+./mvnw -f aggregator/pom.xml clean verify
+```
+
+Module layout and per-package ownership: [docs/architecture/package-map.md](../docs/architecture/package-map.md).
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the workflow.

bundle/README.md

@@ -0,0 +1,23 @@
+# GraphCompose Bundle
+
+`io.github.demchaav:graph-compose-bundle`
+
+The batteries-included aggregate (pom-packaged). One dependency pulls the default PDF stack
+(the `graph-compose` wrapper = core + render-pdf), the built-in templates
+(`graph-compose-templates`), the bundled Google fonts (`graph-compose-fonts`), and the
+colour-emoji set (`graph-compose-emoji`) at compatible versions.
+
+## When to depend on it
+
+Depend on it when you want everything wired up in one coordinate — the closest thing to the
+pre-split single jar. The office backends (`graph-compose-render-docx` /
+`graph-compose-render-pptx`) stay opt-in and are **not** bundled.
+
+Because it is `pom`-packaged, a dependency on it needs `<type>pom</type>`.
+
+## Install
+
+The engine/templates track the GraphCompose train version (lockstep); `graph-compose-fonts`
+and `graph-compose-emoji` are pinned to compatible independent versions. Copy-paste snippet
+and the full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

emoji/README.md

@@ -0,0 +1,27 @@
+# GraphCompose Emoji
+
+`io.github.demchaav:graph-compose-emoji`
+
+Colour-emoji SVG glyphs (Noto Emoji) plus a GitHub-shortcode index, packaged as an
+**independently-versioned** companion artifact (its own `emoji-v*` tag line — it changes only
+when the glyph set or shortcode index does, so it does not track the engine version).
+
+## When to depend on it
+
+Add it only to render colour emoji. Text without emoji needs nothing, and an unknown shortcode
+falls back to its literal text — so a document renders unchanged with or without this artifact.
+`graph-compose-bundle` includes it.
+
+## Usage
+
+```java
+RichText.text("").emoji(":star:", size)   // resolves the shortcode to an inline vector glyph
+```
+
+It is a resource-only jar (glyphs + `emoji-index.properties`); the shortcode resolver in the
+engine reads it from the classpath.
+
+## Install
+
+Independent version line (`emoji-v*`), pinned to a version compatible with your engine train.
+See [root README → Installation](../README.md#installation) for the pinned coordinate.

fonts/README.md

@@ -0,0 +1,24 @@
+# GraphCompose Fonts
+
+`io.github.demchaav:graph-compose-fonts`
+
+Bundled Google font binaries for GraphCompose, packaged as an **independently-versioned**
+companion artifact (its own `fonts-v*` tag line — it changes rarely, so it does not track the
+engine version). Split out of the engine jar in v1.8.0 so an engine upgrade never re-downloads
+the curated font set.
+
+## When to depend on it
+
+- Pure-text and **standard-14** documents (`FontName.HELVETICA`, `FontName.COURIER`, `TIMES`)
+  need **nothing extra** — the base-14 are the standard PDF fonts the render backend already
+  provides.
+- Add this artifact only to render in the **bundled Google families**.
+
+It is a resource-only jar (no public Java API); its families become available to the font
+catalog when it is on the classpath. `graph-compose-bundle` includes it.
+
+## Install
+
+Independent version line (`fonts-v*`), pinned to a version compatible with your engine train.
+See [root README → Installation](../README.md#installation) for the pinned coordinate and the
+[v1.8.0 fonts migration note](../docs/migration/v1.8.0-fonts.md).

qa/README.md

@@ -0,0 +1,21 @@
+# GraphCompose QA
+
+**Internal module — not published to Maven Central.** Do not depend on it.
+
+`qa/` (artifact `graph-compose-build`'s `graph-compose-qa` child) holds the **cross-module
+test suites and shared fixtures** that cannot live in any single module's own test scope —
+tests that need a render backend plus the engine test-jar, or that span core + render-pdf +
+templates at once. It is a reactor tail: an aggregator child that depends on the published
+modules at test scope, so heavy render/integration tests run here without creating a reactor
+cycle back into the lean core.
+
+Examples of what lives here: template visual-parity and smoke suites, layout-snapshot
+extraction tests, the documentation snippet-compile guard, and the dev-tool launcher.
+
+Run it as part of the reactor:
+
+```bash
+./mvnw -f aggregator/pom.xml test        # or: ./mvnw verify -pl :graph-compose-qa -am
+```
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the build/test workflow.

render-docx/README.md

@@ -0,0 +1,29 @@
+# GraphCompose Render — DOCX
+
+`io.github.demchaav:graph-compose-render-docx`
+
+The semantic DOCX export backend for GraphCompose, backed by Apache POI. It carries
+`DocxSemanticBackend` and brings POI transitively, so a PDF-only consumer never pays for it.
+
+## When to depend on it
+
+Add it (at compile scope) only when you export `.docx`. It is **not** included by
+`graph-compose`, `graph-compose-core`, or `graph-compose-bundle` — DOCX is opt-in.
+
+## Usage
+
+```java
+try (var doc = GraphCompose.document().create()) {
+    doc.pageFlow().addParagraph("Hello, DOCX").build();
+    doc.export(new DocxSemanticBackend(), docxFile);
+}
+```
+
+DOCX maps the semantic node graph, not the fixed PDF layout — coverage is narrower than the
+PDF backend.
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

render-pdf/README.md

@@ -0,0 +1,37 @@
+# GraphCompose Render — PDF
+
+`io.github.demchaav:graph-compose-render-pdf`
+
+The PDFBox-backed PDF render backend for GraphCompose. It carries the whole
+`com.demcha.compose.document.backend.fixed.pdf` implementation plus the
+`engine.render.pdf` render tree, and brings PDFBox and ZXing (barcodes) transitively.
+
+## When to depend on it
+
+- You depend on **`graph-compose-core`** directly and want it to render PDF.
+- You are **not** already using **`graph-compose`** (the wrapper) or **`graph-compose-bundle`** —
+  both of those include this backend transitively, so add it only for a lean, explicit setup.
+
+A bare `graph-compose-core` renders nothing until this artifact is on the classpath; asking
+it to build a PDF throws `MissingBackendException`, whose message names this coordinate.
+
+## Usage
+
+You don't call the backend directly. It registers a `FixedLayoutBackendProvider` and a
+`FontMetricsProvider` via `META-INF/services`, so the core discovers it at runtime and the
+normal path just works:
+
+```java
+try (var doc = GraphCompose.document(out).create()) {
+    doc.pageFlow().addParagraph("Hello, PDF").build();
+} // buildPdf() / toPdfBytes() / toImages() now resolve the PDF backend
+```
+
+`PdfFixedLayoutBackend` is available if you need the backend explicitly (custom fragment
+handlers, options).
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

render-pptx/README.md

@@ -0,0 +1,24 @@
+# GraphCompose Render — PPTX
+
+`io.github.demchaav:graph-compose-render-pptx`
+
+The semantic PPTX export backend for GraphCompose. Split out of the DOCX artifact so a DOCX
+consumer never pulls the PPTX code (and vice versa).
+
+## Status
+
+`PptxSemanticBackend` is a **slide-safe semantic manifest skeleton** — it validates the node
+graph against what a slide surface can represent; full `.pptx` file emission is not built out
+yet. Depend on it for the semantic manifest / forward-compatibility, not for production slide
+export. Track the [ROADMAP](../ROADMAP.md) for real PPTX output.
+
+## When to depend on it
+
+Opt-in, at compile scope, only if you target the PPTX semantic surface. Not included by any
+of `graph-compose`, `graph-compose-core`, or `graph-compose-bundle`.
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

templates/README.md

@@ -0,0 +1,34 @@
+# GraphCompose Templates
+
+`io.github.demchaav:graph-compose-templates`
+
+The built-in CV, cover-letter, invoice, and proposal document templates
+(`com.demcha.compose.document.templates.**`). Pure authoring code over the canonical DSL —
+no engine internals, no PDFBox — so it depends only on `graph-compose-core`.
+
+## When to depend on it
+
+Add it when you want the ready-made presets. It is **opt-in**: neither the `graph-compose`
+wrapper nor `graph-compose-core` bundles it (`graph-compose-bundle` does). A 1.x caller that
+reached a preset through the single jar must add this artifact — the packages are unchanged.
+
+## Usage
+
+Each preset is a final class with a `create(BrandTheme)` factory returning a
+`DocumentTemplate<S>` you compose into an open session:
+
+```java
+try (var doc = GraphCompose.document(out).create()) {
+    ModernInvoice.create(theme).compose(doc, invoiceSpec);   // needs graph-compose-templates
+}
+```
+
+Families: `cv`, `coverletter`, `invoice`, `proposal` — each a layered stack (data / components
+/ widgets / presets) over the shared `core` layer (`BrandTheme`, identity, text, widgets).
+See the [layered-template guides](../docs/templates/v2-layered/README.md).
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

testing/README.md

@@ -0,0 +1,31 @@
+# GraphCompose Testing
+
+`io.github.demchaav:graph-compose-testing`
+
+Consumer testing support: deterministic **layout-snapshot assertions** and **PDF visual
+regression** (pixel-diff of rendered pages). Add it at **test scope** to lock the output of
+documents you generate.
+
+## When to depend on it
+
+Add it (test scope) when you want to catch layout/visual regressions in your own documents.
+Not needed at runtime; not bundled by any published artifact.
+
+## Usage
+
+```java
+// Layout snapshot — asserts the renderer-neutral layout graph is unchanged.
+LayoutSnapshotAssertions.assertMatches(session.layoutSnapshot(), "invoice-basic");
+
+// Visual regression — pixel-diffs the rendered pages against a committed baseline.
+PdfVisualRegression.standard().assertMatchesBaseline("invoice-basic", pdfBytes);
+```
+
+Update baselines deliberately with the documented system properties
+(`LayoutSnapshotAssertions.UPDATE_PROPERTY` / `PdfVisualRegression.APPROVE_PROPERTY`).
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).

wrapper/README.md

@@ -0,0 +1,23 @@
+# GraphCompose (compat wrapper)
+
+`io.github.demchaav:graph-compose`
+
+The `graph-compose` coordinate — an **empty jar** that depends on `graph-compose-core` +
+`graph-compose-render-pdf`. It exists so the 1.x coordinate keeps meaning "PDF out of the
+box": a caller who upgrades to 2.0 with `graph-compose` on their classpath renders PDF with
+**no code and no dependency change**.
+
+## When to depend on it
+
+This is the **default**. Depend on `graph-compose` for the drop-in PDF experience. Reach past
+it only to go leaner (`graph-compose-core`, bring your own backend) or fuller
+(`graph-compose-bundle`, batteries included). Templates are opt-in — add `graph-compose-templates`
+if you used the built-in presets through the 1.x single jar.
+
+Packaging stays `jar` (never `pom`) so existing `<dependency>` declarations need no `<type>`.
+
+## Install
+
+Same version as the rest of the GraphCompose train (lockstep). Copy-paste snippet and the
+full "which artifact?" table: [root README → Installation](../README.md#installation).
+Upgrading from 1.x: [modules migration guide](../docs/migration/v2.0.0-modules.md).