docs+ci: post-release polish for v1.6.0 (audit P0+P1)

Closes the actionable items from the post-release audit:

- README — adds CI/Latest-release/JitPack badges, a Distribution
  status block (current: JitPack, planned: Maven Central in v1.7,
  tracking issue #7), an "Upgrading from v1.5?" warning under
  Installation that calls out the Templates v2 breaking surface
  explicitly (legacy CV / cover-letter classes deleted, not
  deprecated), and a "v1.6 primitives in 30 lines" section with one
  short snippet per new primitive (nested list, composed table cell,
  canvas layer placement).

- docs/templates-v2.md — new landing page for the CV / cover-letter
  / invoice / proposal preset library: four-layer architecture, 14
  CV preset table with palette/layout notes, 14 paired cover-letter
  presets, quick-start snippet, visual parity / regression coverage
  summary, and a pointer to the v1 -> v2 migration table.

- .github/workflows/ci.yml — new examples-generation job that
  runs after build-and-test: installs the root artifact, recompiles
  the examples module, runs GenerateAllExamples, and uploads the 26
  generated PDFs as a CI artifact. Examples are part of the product
  surface (live showcase, README install previews); a CI smoke test
  catches regressions in the runnable surface before they ship.

DocumentationCoverageTest, CanonicalSurfaceGuardTest, and the rest
of the architecture + documentation guard suite stay green
(30 / 0 / 0 / 0) under the new README content.

Author: DemchaAV

.github/workflows/ci.yml

@@ -64,6 +64,44 @@ jobs:
       - name: Generate Javadoc
         run: ./mvnw -B -ntp javadoc:javadoc
 
+  examples-generation:
+    name: Examples Generation Smoke Test
+    if: github.event_name != 'schedule'
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    env:
+      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Temurin JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Install root artifact
+        run: ./mvnw -B -ntp -DskipTests install -pl .
+
+      - name: Compile examples module
+        run: ./mvnw -B -ntp -f examples/pom.xml clean compile
+
+      - name: Run GenerateAllExamples
+        run: |
+          ./mvnw -B -ntp -f examples/pom.xml exec:java \
+            "-Dexec.mainClass=com.demcha.examples.GenerateAllExamples"
+
+      - name: Upload generated PDFs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: examples-pdfs-${{ github.run_id }}
+          path: examples/target/generated-pdfs/**
+          if-no-files-found: error
+
   perf-smoke:
     name: Performance Smoke Check
     if: github.event_name == 'pull_request'

README.md

@@ -10,12 +10,12 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/DemchaAV/GraphCompose/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/DemchaAV/GraphCompose/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI"/></a>
+  <a href="https://github.com/DemchaAV/GraphCompose/releases/latest"><img src="https://img.shields.io/github/v/release/DemchaAV/GraphCompose?style=for-the-badge&label=Release" alt="Latest release"/></a>
+  <a href="https://jitpack.io/#DemchaAV/GraphCompose"><img src="https://img.shields.io/jitpack/v/github/DemchaAV/GraphCompose?style=for-the-badge&label=JitPack" alt="JitPack"/></a>
   <img src="https://img.shields.io/badge/Java-21-orange?style=for-the-badge&logo=openjdk" alt="Java 21"/>
-  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="MIT License"/>
   <img src="https://img.shields.io/badge/PDFBox-3.0-red?style=for-the-badge" alt="PDFBox 3.0"/>
-  <a href="https://jitpack.io/#DemchaAV/GraphCompose">
-    <img src="https://img.shields.io/jitpack/v/github/DemchaAV/GraphCompose?style=for-the-badge&label=JitPack" alt="JitPack"/>
-  </a>
+  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="MIT License"/>
 </p>
 
 <p align="center">
@@ -58,7 +58,9 @@ repositories { maven("https://jitpack.io") }
 dependencies { implementation("com.github.demchaav:GraphCompose:v1.6.0") }
 ```
 
-> Latest published tag: **v1.6.0** &mdash; the "expressive" release. Full notes in [`CHANGELOG.md`](./CHANGELOG.md).
+> **Distribution status** &mdash; currently **JitPack**. Maven Central is planned for v1.7 ([tracking issue](https://github.com/DemchaAV/GraphCompose/issues/7)).
+
+> **Upgrading from v1.5?** Core document authoring stays source-compatible &mdash; engine, DSL, themes, and backend-neutral records carry v1.5 callers unchanged. **Templates v2** replaces the legacy CV / cover-letter template classes; legacy classes were **deleted**, not deprecated. Read the [migration guide](./docs/migration-v1-5-to-v1-6.md) before upgrading template-heavy code.
 
 ## Hello world
 
@@ -98,15 +100,51 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response,
 
 ## What's in v1.6 &mdash; "expressive"
 
-- **Templates v2** &mdash; 14 CV and 14 paired cover-letter presets, theme-driven via `BusinessTheme`, one-liner `create(theme)` factories. Inline markdown, slot-based multi-column layouts.
+- **Templates v2** &mdash; 14 CV and 14 paired cover-letter presets, theme-driven via `BusinessTheme`, one-liner `create(theme)` factories. Inline markdown, slot-based multi-column layouts. See [`docs/templates-v2.md`](./docs/templates-v2.md).
 - **Composed primitives** &mdash; `ListBuilder.addItem(label, Consumer)` (nested lists), `DocumentTableCell.node(...)` (any node inside a cell), `CanvasLayerNode` (pixel-precise free-canvas placement).
 - **Architecture hardening** &mdash; `@Internal` API stability marker, public `PdfFragmentRenderHandler` SPI, `DocumentRenderingException` on the convenience render path, documented thread-safety contract.
 
 Full notes in [`CHANGELOG.md`](./CHANGELOG.md). Upgrade guide: [`docs/migration-v1-5-to-v1-6.md`](./docs/migration-v1-5-to-v1-6.md).
 
+## v1.6 primitives in 30 lines
+
+Three snippets, one per new primitive. Full runnable versions live in the [examples gallery](./examples/README.md).
+
+**Nested list** &mdash; builder-callback child scopes with a per-depth marker cascade.
+
+```java
+document.pageFlow().addList(list -> list
+    .addItem("Backend platform", row -> row
+        .addItem("Java 21, Spring Boot, PostgreSQL")
+        .addItem("REST APIs and event-driven services"))
+    .addItem("Document generation", row -> row
+        .addItem("PDF rendering pipeline")
+        .addItem("Layout snapshot tests")));
+```
+
+**Composed table cell** &mdash; any composable node inside a cell, two-pass row measurement.
+
+```java
+DocumentTableCell richSummary = DocumentTableCell.node(
+        new ParagraphNode("Summary",
+                "**Q3 results** were *strong* — revenue grew 18% YoY.",
+                bodyStyle, TextAlign.LEFT, 1.0,
+                DocumentInsets.zero(), DocumentInsets.zero()));
+```
+
+**Canvas layer** &mdash; pixel-precise `(x, y)` placement inside a fixed bounding box.
+
+```java
+document.pageFlow().addCanvas(523, 360, canvas -> canvas
+        .clipPolicy(ClipPolicy.CLIP_BOUNDS)
+        .position(headline, 0, 60)
+        .position(rule(503, 1.4, accent), 10, 32));
+```
+
 ## Documentation
 
 - [Template authoring cheatsheet](./docs/template-authoring.md) &mdash; read this once before writing your own template
+- [Templates v2 landing](./docs/templates-v2.md) &mdash; CV / cover-letter / invoice / proposal preset library
 - [Examples gallery](./examples/README.md) &mdash; every runnable example with PDF preview
 - [Architecture](./docs/architecture.md) · [Lifecycle](./docs/lifecycle.md) · [Production rendering](./docs/production-rendering.md)
 - Recipes: [shape-as-container](./docs/recipes/shape-as-container.md) · [transforms](./docs/recipes/transforms.md) · [tables](./docs/recipes/tables.md) · [themes](./docs/recipes/themes.md) · [streaming](./docs/recipes/streaming.md) · [extending](./docs/recipes/extending.md)

docs/templates-v2.md

@@ -0,0 +1,133 @@
+# Templates v2 — CV, cover letter, invoice, proposal
+
+GraphCompose v1.6 ships a rebuilt canonical template surface for the four
+business document shapes: **CV, cover letter, invoice, proposal**. Every
+preset is one final class with one `create(BusinessTheme)` factory, and
+the spec / preset / theme split is the same across all four domains so a
+caller learns it once and reuses it everywhere.
+
+This page is a landing reference. For a full conceptual walk-through
+(four-layer architecture, when to extend a preset vs. write your own,
+how rendering decisions cascade through theme tokens), read
+[`docs/template-authoring.md`](./template-authoring.md). For the v1 → v2
+upgrade table (every old class → its v2 replacement, with before/after
+code), read [`docs/migration-v1-5-to-v1-6.md`](./migration-v1-5-to-v1-6.md).
+
+---
+
+## Architecture in four layers
+
+Every Templates v2 preset is composed in four layers, top-to-bottom:
+
+1. **Theme tokens** — `BusinessTheme` + `Spacing` + `Typography`. Colours, type scale, gutters, accent rules.
+2. **Layout slots** — `SingleColumn`, `TwoColumnSidebar`, `ThreeColumnMagazine`, `LetterFormat`. The page geometry strategy.
+3. **Components + blocks** — `Header`, `Module`, `MarkdownText`; sealed `Block` hierarchy (`ParagraphBlock`, `BulletListBlock`, `KeyValueBlock`, `IndentedBlock`, `MultiParagraphBlock`).
+4. **Spec data** — `CvSpec`, `CoverLetterSpec`, `InvoiceSpec`, `ProposalSpec`. The plain-Java record carrying the document's content.
+
+Presets glue 1+2+3 together; a caller hands them 4. Adjusting one visual
+decision is one method on one preset, never a fork of a 600-line composer.
+
+---
+
+## Quick start
+
+```java
+import com.demcha.compose.document.templates.cv.presets.ModernProfessional;
+import com.demcha.compose.document.templates.cv.spec.CvSpec;
+import com.demcha.compose.document.templates.api.DocumentTemplate;
+import com.demcha.compose.document.theme.BusinessTheme;
+
+DocumentTemplate<CvSpec> template = ModernProfessional.create(BusinessTheme.modern());
+template.compose(session, mySpec);
+```
+
+Same shape for cover letters, invoices, and proposals &mdash; swap the
+package, the spec type, and the preset class.
+
+---
+
+## CV preset gallery (14)
+
+Each preset is a one-class final type with `RECOMMENDED_MARGIN` and
+`create(BusinessTheme)`. Visual baselines are pixel-diff verified against
+v1 reference renders.
+
+| Preset | Layout | Notes |
+|---|---|---|
+| `ModernProfessional` | Single column | Slate-blue name + royal-blue underlined links; canonical default |
+| `NordicClean` | Two-column sidebar | Soft-tinted profile panel on the left |
+| `ClassicSerif` | Two-page editorial | Serif-only typography, restrained accents |
+| `CompactMono` | Single column | Tight grid for technical CVs |
+| `Executive` | Two-column sidebar | Larger accent rule + uppercase section heads |
+| `EngineeringResume` | Two-column sidebar | Dense skill stack, code-friendly mono |
+| `TimelineMinimal` | Single column | Vertical rule + dot timeline along the left margin |
+| `BoxedSections` | Single column | Section headers in tinted boxes with full-width rule |
+| `CenteredHeadline` | Single column | Centered name + bullet & key-value sections |
+| `BlueBanner` | Single column | Full-width section banners in theme accent |
+| `EditorialBlue` | Single column | Slab subtitle + jobTitle line + uppercase rule |
+| `Panel` | Two-column sidebar | Soft-tinted panel for sidebar; project-leader shape |
+| `SidebarPortrait` | Two-column sidebar | Portrait + sidebar fill to page bottom |
+| `MonogramSidebar` | Two-column sidebar | Monogram badge + sidebar fill |
+
+## Cover-letter preset gallery (14, paired)
+
+Each cover-letter preset pairs visually with its same-named CV preset
+(palette, header rhythm, accent rule). Mix-and-match is supported but the
+default pairing produces the cleanest visual.
+
+`ModernProfessional` · `NordicClean` · `ClassicSerif` · `CompactMono`
+· `Executive` · `EngineeringResume` · `TimelineMinimal` · `BoxedSections`
+· `CenteredHeadline` · `BlueBanner` · `EditorialBlue` · `Panel`
+· `SidebarPortrait` · `MonogramSidebar`
+
+Render any preset against a sample spec to inspect the output:
+
+```bash
+./mvnw -f examples/pom.xml exec:java \
+    -Dexec.mainClass=com.demcha.examples.templates.cv.CvTemplateGalleryFileExample
+```
+
+The runnable gallery writes one PDF per preset under
+`examples/target/generated-pdfs/templates/cv/`. The cover-letter gallery
+mirrors the layout under `templates/coverletter/`.
+
+---
+
+## Invoice + proposal (minimal v2 surface)
+
+`ModernInvoice` and `ModernProposal` ship as the canonical builder seam
+for invoices and proposals respectively. Cinematic feature parity
+(rich hero blocks, accent-driven section bands) lives in
+`InvoiceTemplateV2` / `ProposalTemplateV2` under
+`templates/builtins/` &mdash; those remain the recommended path when full
+visual styling is required, while the v2 builders provide a smaller,
+copy-and-tweak entry point for callers extending their own branding.
+
+---
+
+## Authoring features built into every preset
+
+- **Inline markdown** &mdash; body strings carrying `**bold**` and `*italic*` markers render with proper `DocumentTextDecoration` via `templates.components.MarkdownText`.
+- **Active hyperlinks** &mdash; header email + LinkedIn / GitHub labels become clickable `mailto:` / `https:` runs via `DocumentLinkOptions`.
+- **Slot-based layouts** &mdash; multi-column presets (`Panel`, `SidebarPortrait`, `MonogramSidebar`) declare named slots (`MAIN`, `SIDEBAR`); custom presets rearrange modules via `.place(slot, "Module Name", ...)`.
+- **Adaptive sidebar fill** &mdash; sidebar layouts size the trailing spacer dynamically from `canvas().innerHeight()` so background panels reach the page bottom on A4 / Letter / smaller fixtures without overflow.
+- **`CvHeader.jobTitle` subtitle** &mdash; presets that surface a subtitle (`EditorialBlue`, `Panel`, `SidebarPortrait`, `MonogramSidebar`) read it from the spec; an empty value falls back to a placeholder.
+
+---
+
+## Visual parity & regression coverage
+
+- **28 layout-snapshot baselines** under `src/test/resources/layout-snapshots/canonical-templates/{cv-v2,coverletter-v2}/` lock the rendered tree of every preset.
+- **29 pixel-diff baselines** under `src/test/resources/visual-baselines/{cv-v2,coverletter-v2}/` enforce per-channel rendering parity against the v1 reference renders. The gate runs on every CI build with a calibrated `mismatchedPixelBudget` for cross-platform PDFBox font drift.
+- Re-bless after a deliberate visual change with `-Dgraphcompose.visual.approve=true`.
+
+---
+
+## Migration from v1 templates
+
+Legacy CV / cover-letter classes (`CvTemplateV1`, `NordicCleanCvTemplate`,
+`MonogramSidebarCvTemplate`, ...) are **deleted**, not deprecated, in
+v1.6. Any code constructing those classes must switch to the matching v2
+preset's `create(BusinessTheme)` factory. The full mapping (every old
+class → its v2 replacement, with side-by-side code) is documented in
+[`docs/migration-v1-5-to-v1-6.md`](./migration-v1-5-to-v1-6.md).