Committed README assets have no regeneration path — 1 of 82 is refreshed on release

[DemchaAV]

Expands #454 with the actual inventory, after the same defect had to be fixed three times in a row across three files.

The gap

cut-release.ps1 regenerates exactly one file under assets/readme/:

step	regenerates
Run-ShowcaseSync	web/showcase/** — the site gallery
Render-ReadmeBanner	assets/readme/repository_showcase_render.png
—	nothing else under assets/readme/

There are 82 committed files there (68 under examples/, 13 images, one logo). Every one except the hero banner is frozen at whatever commit last touched it by hand. They are linked from the root README and the examples gallery, so a reader clicking through gets whatever was true that day.

What is actually stale, and what only looks stale

I scanned every committed PDF for embedded versions and codenames. The results split three ways, and conflating them would overstate the problem.

1. A live version stamp that was wrong — fixed in #460.

assets/readme/examples/engine-deck-v2.pdf rendered the build version. Its page one is the hero banner, so it carried v2.0.0, GRAPHCOMPOSE 2.0 / MODULE-FIRST and a module row with no render-pptx — the same defect #458 fixed in the source and the PNG, surviving in a third file.

Currently correct after the release: engine-deck.pdf (v2.1.0 / twinned), maven-banner.pdf (v2.1.0), repository_showcase_render.png. All three were refreshed by hand, one per incident.

2. Example content that names an old version — not a stamp, but it dates the demo.

These are fictional documents whose text happens to mention a release. Nothing renders them wrong; they simply read oddly on a 2.1 project:

• master-showcase.pdf — the kitchen-sink flagship is a mock release plan for "v1.5 — 'intuitive' release", complete with "Tag v1.5.0 on main once develop is merged". Six releases old, and it is one of the most-linked examples.
• canvas-layer-showcase.pdf — "Issued for shipping the v1.6 expressive release".
• inline-highlight-chips.pdf — "Run ./mvnw verify then tag v1.9.0 to publish graph-compose-emoji".

3. Not a problem at all.

• inline-code-column-wrap.pdf shows io.github.demchaav:graph-compose:1.9.0 and org.junit.jupiter:junit-jupiter:5.10.2 — those are the demo table's cells, illustrating inline-code chips in a narrow column. The versions are the subject matter.
• cv-modern-professional.pdf / cv-classic-serif.pdf match "cinematic", but it is résumé prose ("cinematic covers, pull quotes"), not a release codename.

Why it recurs

Two separate things have to be true, and neither is enforced:

1. Nothing regenerates the assets, so a source fix does not reach the file a reader opens.
2. A version-stamping asset can only be rendered correctly during a cut. develop sits on X.Y.(Z+1)-SNAPSHOT between releases, so regenerating at any other moment bakes a -SNAPSHOT string into a public file. Every refresh in this release had to override the filtered banner.properties by hand to get 2.1.0.

Directions

• Add an assets/readme/** refresh step to cut-release.ps1, beside Render-ReadmeBanner, which already solves this for one file. It runs after the version bump, which is the only moment a version-stamped asset renders correctly. Verify under -DryRun, -PostReleaseOnly and -SkipShowcase — the v1.6.5 lesson.
• Or stop stamping the build version into assets. The pill is the only place it earns its keep; the kicker and graph label could drop the number entirely and never rot again.
• Guard it: a test that renders the version-bearing examples and asserts the committed copy matches would turn this into a red build instead of a reader noticing.
• Separately, refresh the category-2 demo content so the flagship example is not a 1.5-era release plan.

[DemchaAV]

Still open, and the mechanism is worth writing down precisely — it is not only that a regeneration step is missing, but that the one path which does refresh the site silently depends on a manual step nobody is told to run.

How the showcase is actually filled at a cut

ShowcaseSync does not render. It copies from examples/target/generated-pdfs and aborts if that directory is absent:

// ShowcaseSync.java:71-74
if (!Files.isDirectory(generatedPdfs)) {
    throw new IllegalStateException("No generated PDFs found at " + generatedPdfs
            + ". Run GenerateAllExamples first.");
}

grep -n "GenerateAllExamples" scripts/cut-release.ps1 returns nothing — the release script never runs it. So whatever sits in examples/target at Step 4 is what reaches web/showcase, and Step 6 commits it. On a fresh clone the cut aborts; with a stale target it publishes stale content and says nothing.

I hit the stale case while checking this: running exec:java GenerateAllExamples without compile executed classes built before the newest example was merged, so that example was silently absent from the output while the source clearly registers it. The safe invocation is

./mvnw -f examples/pom.xml clean compile exec:java -Dexec.mainClass=com.demcha.examples.GenerateAllExamples

Two smaller findings from the same pass

• ShowcaseSync never deletes. Three files remain published from ef135bd2 (2026-06-29) although nothing generates them any more: features/themes/invoice-custom-theme.pdf, templates/invoice/invoice.pdf, templates/proposal/proposal.pdf.
• EngineDeckV2Example is not in GenerateAllExamples — only EngineDeckExample and its PPTX twin are. The v2 deck is published on the site and linked from the README, but the standard regeneration path does not produce it; it has only ever been refreshed by hand.

Not attempted before the 2.1.1 cut

Adding an assets/readme/** step to the release script is new release behaviour and needs re-verification under -DryRun, -PostReleaseOnly and -SkipShowcase. Debuting it on the cut itself is the wrong trade. The acute symptom this gap produced — decks publishing a -SNAPSHOT coordinate — is fixed separately in 35e853e; see #454 for that half.

[DemchaAV]

Closed by #484, #485, #487 and #488.

Against the directions above

The refresh step exists. A cut renders the catalogue at the version it is tagging and copies every committed preview from it, before the verify step — because that is where the gate compares them, and scheduled after it a cut would fail on exactly the files it was about to bring up to date. Verified under all three modes, as the v1.6.5 lesson asks, and asserted in release-script-check.yml rather than left to a maintainer's memory: a final cut moves the version and re-renders; a pre-release and -PostReleaseOnly leave both alone, since X.Y.Z-rc.N and X.Y.(Z+1)-SNAPSHOT are values the examples module rejects, and the qualifier-stripped form of an -rc names a release that does not exist yet.

The moment problem is solved by recording the moment. graphcompose.examples.assetVersion in examples/pom.xml says which version the committed previews were rendered at, the release script moves it with the tag, and the module's tests render at it. No more overriding banner.properties by hand — that override is now the mechanism rather than a workaround.

It is guarded. CommittedAssetDriftTest compares all 67 committed previews against a fresh render on every build, and assets/readme/** is a change-detection input so editing one by hand runs the job that checks it. The comparison is exact: rendering the catalogue on both platforms at one version put 99 of 104 documents byte-identical once a PDF's clock-seeded /ID, an OOXML package's zip and creation stamps and the platform's line separator are dropped, so no tolerance was needed. The two remaining differences — one watermark's antialiasing and two freeform shapes' bounding boxes — are exempted by the pixel and shape digest of each machine's render, never by path, so an image or a shape swapped for another still fails.

Twenty-three of the sixty-seven were already behind and are re-rendered. The twenty-two PDFs among them rasterise to the same pixels as before, so nothing visible had been carrying the drift; the one DOCX now marks bold as <w:b/> instead of asking for a font named Helvetica-Bold, which Word honours only if that font is installed.

What this does not cover

The dated demo content. The last direction above — "refresh the category-2 demo content" — is example prose, not drift, and no gate can catch it. master-showcase.pdf no longer reads as a v1.5 release plan, but two are still dated:

• canvas-layer-showcase.pdf — "v1.6 Phase C — CanvasLayerNode", "GraphCompose v1.6"
• inline-highlight-chips.pdf — "Run ./mvnw verify then tag v1.9.0 to publish graph-compose-emoji"

Worth its own issue: it is a writing task with no mechanism behind it, and it would have sat unfinished inside this one.

The eight rasterised figures beside the preview folder. They are pages rasterised to PNG, and rasterising text is where two machines disagree — comparing them would take a pixel budget, which is a number nobody can defend a year later. They are written down and asserted as a set, so a ninth cannot arrive unnoticed; the hero among them is still re-rendered at every cut.

[DemchaAV]

The demo-content half is #490 — seven previews, not the two named above; scanning all sixty-seven turned up four more.