docs: stop offering an examples-local type, and drop the counts that keep rotting (#482)

* docs: stop offering an examples-local type, and drop the counts that keep rotting

The example catalogue introduced the cover letter as a `BusinessTheme.modern()`
document. That record lives in the examples module and ships in no artifact, so a
reader who adds the dependency and reaches for it finds nothing to import. The
rows and prose now describe what the examples demonstrate; the advanced section
that quotes the helper says it is examples-local and names `BrandTheme` as the
shipping equivalent.

ExamplesLocalTypeGuardTest bans the factory-call form on any README and leaves
the fence alone — a fence quotes an example's own source, and editing the type
out of a quotation would make it false.

Four counts are removed rather than corrected: the catalogue was "~53 PDFs" with
a "curated 39-PDF subset" where it generates 91 and commits 62, the banner
caption stated a line count for the example it links, and it named the module
graph by a version the image no longer shows. Each had been reconciled before.

The commit-message examples pointed at the 1.5 line while the pull-request
template requires a conventional subject and 26 of the last 30 commits are one.

* docs: say what the cover letter actually uses, and police the form that misled

The replacement sentence was as untrue as the one it replaced: it said the
palette and fonts come from a record the example declares, and the example
imports the shared examples-module helper and calls it. The section now says
the colours come from a helper local to this module and names BrandTheme as
the shipping equivalent.

Three defects in the rule:

- it matched any dot after the type name, so a markdown link to the type's own
  source would have failed the build citing a call that was never written. It
  now matches a call.
- the bare name in a table row passed, which is the form the defect was
  actually written in. A row naming the type is now rejected too; elsewhere in
  prose the bare name stays legal, because these pages describe those examples.
- one of the package's five types was listed. The set is read from the source
  tree, so the next helper is covered without anyone remembering this file.

The guard-the-guard compared prose against a fixed floor that the fenced
content clears on its own — an inverted split would have passed it. It compares
the two halves instead.

* docs: scan every published page, and every code block that is not a quotation

The rule read one README per module and skipped every fenced block, which left
the two forms most likely to mislead outside it: a nested page under docs/, and
a tutorial snippet — the thing a reader copies rather than reads.

- The scan covers the published documentation, historical records aside: pages
  under docs/adr, docs/archive, docs/migration, docs/roadmaps and the v1-classic
  templates exist to record what a past release contained, and the decision guide
  between the removed and layered surfaces names the old one beside its
  replacement on purpose.
- Code blocks are scanned. The one exemption is a fence introduced by a
  doc-example-ignore marker, which already carries a written reason and is how a
  page quotes an example's own source verbatim. A test asserts that path is still
  exercised, so the escape hatch cannot quietly become dead code.
- Construction, method references and member access join the call form. Three
  unguarded ways to make the same offer is not a rule.
- An unclosed fence is caught per page. It exempts everything below it, and the
  totals cannot see one file going quiet.

The entry describing the removed counts had itself acquired five of them, in a
bullet titled "the last hardcoded counts are gone"; every figure that can drift
before the release is out.

Author: DemchaAV

CHANGELOG.md

@@ -127,6 +127,25 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Documentation
 
+- **The example catalogue stops offering a type that ships nowhere.** Its entry-point
+  table introduced the cover letter as a `BusinessTheme.modern()` document, and
+  `BusinessTheme` is a record local to the examples module — a reader adding the
+  dependency and reaching for it finds nothing to import. The rows and prose now say
+  what the examples demonstrate, the advanced section that quotes the helper says
+  plainly that it is examples-local and names `BrandTheme` as the shipping equivalent,
+  and a guard rejects the factory-call form on any README while leaving the quotation
+  of an example's own source alone.
+- **The last hardcoded counts are gone.** The example catalogue named a number of
+  generated documents and a number of committed previews; both sat well below the real
+  inventory, having been reconciled by hand once already and drifted again since. The
+  banner caption stated a line count for the example it links, and named the module graph
+  by a version the image itself no longer shows. All four are removed rather than
+  corrected — a count in prose has no owner and nothing to keep it true, so correcting
+  one only resets the clock.
+- **The contributing guide's commit examples match the convention it asks for.** It
+  pointed at two subjects from the 1.5 line as the shape to copy, while the repository
+  has moved to Conventional Commits and the pull-request template requires that shape in
+  a title. The examples are two real recent subjects instead.
 - **Documented headings render bold, and say why.** Six snippets across the
   getting-started guide, the root README and the theme, timeline, rich-text and
   preset-authoring recipes set `fontName(FontName.HELVETICA_BOLD)` without a

CONTRIBUTING.md

@@ -59,7 +59,7 @@ Almost all work targets **`develop`**, the ongoing 2.x line. The `1.x` branch ta
    git checkout -b feature/short-description
    ```
    Use `feature/...` for new functionality, `fix/...` for bug fixes, and `docs/...` for documentation-only changes. Issue-prefixed names (`42/fix/short-description`) are also welcome — convenient when the branch closes a specific issue.
-3. **Commit small, focused changes.** Each commit message should describe the *why*, not just the *what*. Recent commits on `develop` (`Prepare v1.5.0 release`, `Align public docs with the canonical surface`) are reasonable length and structure templates.
+3. **Commit small, focused changes.** Subjects follow Conventional Commits — `type(scope): the concrete effect` — the same shape the [pull request template](.github/pull_request_template.md) asks of a PR title. Say the *why*, not only the *what*. `git log --oneline -20` on `develop` is the reference; `fix(font): the donut-centre KPI renders the weight it declares` and `ci(guards): run every guard the job names, and compile docs-only pull requests` are the shape.
 4. **Run the validation gate locally** before opening a PR:
    ```bash
    ./mvnw -B -ntp clean verify

README.md

@@ -41,7 +41,7 @@
 </p>
 
 <p align="center">
-  <sub>☝ This banner is itself a GraphCompose document — <a href="./assets/readme/examples/engine-deck-v2.pdf"><b>view the full module-first deck (PDF)</b></a>, rendered by <a href="./examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java"><code>EngineDeckV2Example</code></a>: the 2.0 module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.</sub>
+  <sub>☝ This banner is itself a GraphCompose document — <a href="./assets/readme/examples/engine-deck-v2.pdf"><b>view the full module-first deck (PDF)</b></a>, rendered by <a href="./examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java"><code>EngineDeckV2Example</code></a>: the module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.</sub>
 </p>
 
 ## One source → a PDF <i>and</i> an editable PowerPoint deck
@@ -77,7 +77,7 @@ try (DocumentSession doc = GraphCompose.document(Path.of("twin-output.pdf"))
   <img src="./assets/readme/twin-output-editing.png" alt="The generated deck open in PowerPoint with the headline text frame selected for editing" width="820"/>
 </p>
 <p align="center">
-  <sub>☝ The generated deck open in PowerPoint — the headline is a selected, editable text frame, and the ribbon is live because the slide is built from native shapes. Artifacts: <a href="./assets/readme/examples/twin-output.pdf"><b>PDF</b></a> · <a href="./assets/readme/examples/twin-output.pptx"><b>PPTX</b></a> · <a href="./examples/src/main/java/com/demcha/examples/flagships/TwinOutputExample.java"><b>source</b></a> (<code>TwinOutputExample</code>, ~370 lines, page included).</sub>
+  <sub>☝ The generated deck open in PowerPoint — the headline is a selected, editable text frame, and the ribbon is live because the slide is built from native shapes. Artifacts: <a href="./assets/readme/examples/twin-output.pdf"><b>PDF</b></a> · <a href="./assets/readme/examples/twin-output.pptx"><b>PPTX</b></a> · <a href="./examples/src/main/java/com/demcha/examples/flagships/TwinOutputExample.java"><b>source</b></a> (<code>TwinOutputExample</code>, one page, source included).</sub>
 </p>
 
 ## Why GraphCompose

examples/README.md

@@ -34,10 +34,10 @@ Generated PDFs land in `examples/target/generated-pdfs/`. The same
 
 `GenerateAllExamples` renders the whole catalogue in one pass — the CV and
 cover-letter presets plus invoices, proposals, a schedule, the feature
-demos, and the flagships. The showcase site surfaces the full generated
-catalogue (~53 PDFs); a curated 39-PDF subset is committed under
-[`assets/readme/examples/`](../assets/readme/examples/) for the previews
-linked below.
+demos, and the flagships. The showcase site publishes the whole generated
+catalogue; a curated subset is committed under
+[`assets/readme/examples/`](../assets/readme/examples/) so the previews
+linked below open straight from GitHub.
 
 ## Gallery — pick by your goal
 
@@ -58,7 +58,7 @@ are with the canonical DSL, then jump to its detailed section below.
 |---|---|---|
 | [CV — single template](#cv-single-template) | One CV via `ModernProfessional.create()` on a `CvDocument` | [PDF](../assets/readme/examples/cv-modern-professional.pdf) · [Source](src/main/java/com/demcha/examples/templates/cv/CvFileExample.java) |
 | [Invoice — cinematic V2](#invoice-cinematic-v2) | `ModernInvoice + BrandTheme.invoiceModern()` — the recommended invoice path | [PDF](../assets/readme/examples/invoice-cinematic.pdf) · [Source](src/main/java/com/demcha/examples/templates/invoice/InvoiceCinematicFileExample.java) |
-| [Cover Letter](#cover-letter) | One-page `BusinessTheme.modern()` cover letter with section presets | [PDF](../assets/readme/examples/cover-letter.pdf) · [Source](src/main/java/com/demcha/examples/templates/coverletter/CoverLetterFileExample.java) |
+| [Cover Letter](#cover-letter) | One-page cover letter composed in the canonical DSL, section presets carrying the hierarchy | [PDF](../assets/readme/examples/cover-letter.pdf) · [Source](src/main/java/com/demcha/examples/templates/coverletter/CoverLetterFileExample.java) |
 | [Module-first Profile](#module-first-profile) | Authoring directly against `DocumentSession.module(...).paragraph(...)` — DSL-direct, no template | [PDF](../assets/readme/examples/module-first-profile.pdf) · [Source](src/main/java/com/demcha/examples/flagships/ModuleFirstFileExample.java) |
 | **Engine Showcase** | Single-page cinematic brand promo — semantic-graph → polished-PDFs visual metaphor with rounded clip frame, magazine headline lockup, KPI cards, capability columns; source of the README hero image | [Source](src/main/java/com/demcha/examples/flagships/EngineShowcase.java) |
 | **Engine Deck** | Multi-page **landscape** capability deck — page 1 is a banner infographic (DSL code → engine → backends → **real rendered-document thumbnails**), then an authoring-pipeline walkthrough, and two pages of **real benchmark data** (GraphCompose vs iText 9 vs JasperReports) loaded from a bundled result file and drawn as tables + native charts; the landscape companion to Engine Showcase. The same composition also renders as a **geometry-identical PowerPoint deck** (one page = one editable slide) through `buildPptx(Path)` | [PDF](../assets/readme/examples/engine-deck.pdf) · [Source](src/main/java/com/demcha/examples/flagships/EngineDeckExample.java) · [PPTX source](src/main/java/com/demcha/examples/flagships/EngineDeckPptxExample.java) |
@@ -138,10 +138,11 @@ are with the canonical DSL, then jump to its detailed section below.
 
 ### Cover letter
 
-A one-page modern cover letter — `BusinessTheme.modern()` drives every
-colour and font choice; section presets (`softPanel`, `accentLeft`,
-`accentTop`) carry the visual hierarchy; opening rich-text strip
-highlights the candidate's headline.
+A one-page modern cover letter composed straight in the canonical DSL.
+Section presets (`softPanel`, `accentLeft`, `accentTop`) carry the visual
+hierarchy and an opening rich-text strip highlights the candidate's
+headline. Its colours come from a theme helper local to this module, not
+from library API — the shipping equivalent is `BrandTheme`.
 
 <!-- doc-example-ignore: quotes a runnable example; the source it is taken from is compiled and executed by the examples module -->
 ```java
@@ -1130,11 +1131,15 @@ The same composition also emits an editable PowerPoint deck (`BusinessReportPptx
 ### Master showcase
 
 Fictional "Q2 sample report" combining the canonical surface
-end-to-end: `BusinessTheme` + page background + hero with rotated
+end-to-end: a theme record + page background + hero with rotated
 shape container + branded QR + executive summary + zebra-striped
 totals table + accent-bordered highlight cards + Code 128 footer
 barcode. Reference it when composing your own multi-page documents.
 
+The `BusinessTheme` record it uses is a helper local to this module, not
+library API — the shipping equivalent is `BrandTheme` and the layered
+presets. Declare your own record the same way, or start from `BrandTheme`.
+
 The same composition also emits an editable PowerPoint deck (`MasterShowcasePptxExample` — each page becomes one slide; rich text, the advanced table, and chrome stay native shapes, and only the rotated clip-masked seal and the barcodes rasterise).
 
 [📄 View PDF](../assets/readme/examples/master-showcase.pdf) ·