docs: put the contributor surfaces on the 2.x vocabulary (#476)

* docs: put the contributor surfaces on the 2.x vocabulary

Several documents still described an architecture that shipped out of the
repository in 2.0, and a contributor following them wrote code that does not
compile.

CONTRIBUTING routed template authors to BusinessTheme, InvoiceTemplateV2 and
ProposalTemplateV2, and its engine-primitive section described entities,
container-growth markers and Breakable. None of those seven types exist in
src/main. Both sections now describe what is there: the layered preset stack
with create(BrandTheme), and the NodeDefinition pipeline where pagination is
declared by the definition and a splittable node compiles through
SplittableLeafCompiler. A dead link to ComputedPositionTest points at a test
that exists.

CONTRIBUTING, SECURITY and the architecture overview called the pptx module a
semantic exporter. Its primary backend is fixed-layout, in
document.backend.fixed.pptx, alongside the older semantic manifest — and a new
fragment kind has to register a handler with both fixed-layout backends, or it
renders in one output and silently vanishes from the other. The semantic
wording is left in place everywhere it is still accurate.

ROADMAP described 2.1 as in development and 2.0 as current stable, four days
after 2.1.0 shipped. The README release-status block described 2.1.1 with
2.1.0's headline. docs/README listed five superseded 1.x upgrade guides on the
main path and omitted the 2.0 migration guide entirely.

The bug-report template asked for a v1.6-era version and offered a reproduction
with no try-with-resources and no render call, so a repro pasted from it
produced nothing. It now asks for the backend, the classpath, the font source
and the generated artifact or layout snapshot. The feature-request template
pointed at BusinessTheme; the pull-request template offered a lane that does not
exist and required updating a count by hand. A new issue-template config routes
usage questions to Discussions.

Four places stated four different example totals — 63, 63, 54 and "26+" — where
the runner invokes 94. The numbers are removed rather than synchronised; they
have drifted every release since June.

The release runbook grepped the README for a test-count claim the README does
not make, so that gate always passed; it compared the gallery row count against
the example file count, two numbers long diverged; and three items pointed at a
migration path that moved. The gallery check is now a ShowcaseMetadata coverage
check, and a new item covers ROADMAP.

canonical-legacy-parity.md is refreshed rather than archived: eight live
documents link it, and its three "Planned for v1.6" rows had all shipped.

In the README, the comparison block moves below Architecture so it stops
separating the first example from the next step, What's new in 2.0 compresses to
its links, and the documentation catalogue collapses to four routes.

* docs: give the release status one source of truth

The README advertised v2.1.1 as latest stable behind a release link that 404s,
while the changelog carried v2.1.1 as Planned, the roadmap named 2.1.0 as the
current stable line, and the showcase metadata said 2.1.0. Four surfaces, three
answers.

The false one was the README, and it was false on purpose. cut-release.ps1 did
not rewrite the release-status block, so the post-release commit that would fix
it lives on develop and never reaches main — the v1.6.9 lesson recorded in the
runbook. The mitigation was a pre-cut hand-edit, enforced by a Step 0 gate that
demanded the block already name the version being cut. To leave main correct
after the tag, develop had to be wrong for the whole cycle.

The block is script-owned now. Step 1 promotes the in-development half to latest
stable, rewriting both the link text and the tag URL, and opens the next patch
line; Assert-ReleaseMetadata verifies the result after the mutation. Step 0 no
longer demands a hand-edit — it checks the block still exists in the shape the
rewrite matches, so a reflowed blockquote aborts loudly instead of being skipped
in silence. What the maintainer owns is the prose, not the version tokens.

SECURITY.md's supported-versions table jumped from 2.1.x straight to 1.9.x,
leaving 2.0.x uncovered — a regression introduced when the 1.9.x row was added.

The showcase page still stated a count in three places while the JSON-LD beside
them declared numberOfItems: 51 and the visible heading said "50+ generated
PDFs". Replacing one number with another moves the problem to the next release,
so the counts are gone; the page loads its catalogue from examples.json and can
say what it renders without claiming how many.

The runbook still told the maintainer that PackageMapGuardTest scans the
gitignored docs/private/ and can fail a local run CI cannot reproduce. That
stopped being true when the exclusion landed; its guard list was also missing
CiGuardListGuardTest.

The README API table sent anyone adding a visual primitive to
PdfFragmentRenderHandler alone, while CONTRIBUTING now requires registering with
both fixed-layout backends — a handler registered with one renders in one output
and vanishes from the other.

Author: DemchaAV

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,25 +11,39 @@ labels: bug
 
 ## What actually happened
 
-<!-- Stack trace, rendered output, layout snapshot diff, mismatched pixel count, etc. Attach the produced PDF if relevant. -->
+<!-- Stack trace, layout snapshot diff, mismatched pixel count, or a description of the wrong render. -->
 
 ## How to reproduce
 
 ```java
-// Minimal, runnable Java code that triggers the issue.
-// Prefer the canonical `GraphCompose.document(...)` API.
-DocumentSession document = GraphCompose.document(Path.of("repro.pdf"))
+// Minimal, runnable Java that triggers the issue. Close the session and produce
+// the output — a repro that never renders shows nothing.
+try (DocumentSession document = GraphCompose.document(Path.of("repro.pdf"))
         .pageSize(DocumentPageSize.A4)
-        .create();
-// ...
+        .margin(24, 24, 24, 24)
+        .create()) {
+
+    document.pageFlow(page -> page
+            .module("Repro", module -> module.paragraph("...")));
+
+    document.buildPdf();   // or buildPptx(Path) / toPdfBytes()
+}
 ```
 
+## Generated artifact
+
+<!-- Attach the produced PDF / PPTX / DOCX, or paste document.layoutSnapshot().
+     The snapshot is renderer-neutral and usually pins a layout bug faster
+     than the file does. -->
+
 ## Environment
 
-- GraphCompose version: <!-- e.g. v1.6.1 -->
+- GraphCompose version: <!-- e.g. 2.1.0 -->
+- Output backend: <!-- PDF (render-pdf) / PPTX (render-pptx) / DOCX (render-docx) -->
+- Modules on the classpath: <!-- e.g. graph-compose; or core + render-pdf + templates. Note graph-compose-fonts / -emoji if present -->
 - Java: <!-- e.g. Temurin 17.0.10 -->
 - OS: <!-- e.g. Windows 11 / macOS 14 / Ubuntu 24.04 -->
-- PDFBox: <!-- 3.0.7 unless overridden -->
+- Font source: <!-- bundled graph-compose-fonts / registerFontFamily(...) / the PDF standard 14 -->
 
 ## Additional context
 

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+# Routes everything that is not a bug or a feature request away from the
+# issue tracker, so Issues stay a list of actionable defects and requests.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Usage question
+    url: https://github.com/DemchaAV/GraphCompose/discussions
+    about: How do I render X, which artifact do I need, why does my layout do this — ask in Discussions.
+  - name: Where to go for what
+    url: https://github.com/DemchaAV/GraphCompose/blob/main/SUPPORT.md
+    about: Channels, what to read first, and what response to expect.
+  - name: Security vulnerability
+    url: https://github.com/DemchaAV/GraphCompose/security/advisories/new
+    about: Report privately through a GitHub security advisory. Never in a public issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -16,9 +16,13 @@ labels: enhancement
 ## Proposed API
 
 ```java
-// Sketch the public-API shape you'd like to use.
-// Stick to the canonical surface: GraphCompose.document(...), DocumentSession,
-// document.pageFlow(...), DocumentNode + NodeDefinition, BusinessTheme.
+// Sketch the public-API shape you'd like to use. Stick to the canonical surface:
+//   authoring        GraphCompose.document(...) -> DocumentSession, document.pageFlow(...)
+//   new visual node  DocumentNode (com.demcha.compose.document.node)
+//                    + NodeDefinition (com.demcha.compose.document.layout)
+//   theming          BrandTheme (com.demcha.compose.document.templates.core.theme)
+//   new output kind  FixedLayoutBackendProvider (…document.backend.fixed)
+//                    or SemanticBackend (…document.backend.semantic)
 document.pageFlow().add???(...);
 ```
 
@@ -28,6 +32,9 @@ document.pageFlow().add???(...);
 
 ## Would this be a breaking change?
 
+Classify the surface it touches against [docs/api-stability.md](../../docs/api-stability.md)
+(§1 defines the tiers, §4 maps each package onto one).
+
 - [ ] No — additive only (new node, new builder method, new template preset).
 - [ ] Possibly — affects public-record shape, deprecates an existing API, or changes default rendering behaviour.
 

.github/pull_request_template.md

@@ -25,7 +25,7 @@ Delete any heading you have nothing real to put under — never ship an empty pl
      - command run + result, e.g.  `./mvnw -B -ntp clean verify` → BUILD SUCCESS, <N> tests, 0 failures
      - the new tests and what each asserts; regenerate renders if the change is visual -->
 
-**Lane:** <!-- canonical | shared-engine | legacy | test --> — <one-line scope note>
+**Lane:** <!-- canonical | shared-engine | templates | build | docs | test --> — <one-line scope note>
 
 Closes #<!-- issue number; delete this line if none -->
 
@@ -38,6 +38,6 @@ Closes #<!-- issue number; delete this line if none -->
 - [ ] `./mvnw -B -ntp clean verify` passes locally — this is the **Verification** proof above.
 - [ ] **Java 17 compatible** — no `getFirst()`/`getLast()`, `Thread.threadId()`, type/deconstruction `switch`, `case null, default`. (CI runs Temurin 17 / 21 / 25.)
 - [ ] **Public API changed** → `CHANGELOG.md` entry under the next `## v<X.Y.Z> — Planned` heading.
-- [ ] **README / examples touched** → `DocumentationCoverageTest` stays green; a new example is wired into `GenerateAllExamples` + the `examples/README.md` gallery count.
+- [ ] **README / examples touched** → `DocumentationCoverageTest` stays green; a new example is wired into `GenerateAllExamples` and given a gallery row in `examples/README.md`.
 
 </details>

CHANGELOG.md

@@ -22,6 +22,12 @@ follow semantic versioning; release dates are ISO 8601.
 - **`graph-compose-render-pptx` declares PDFBox.** It compiles against
   `org.apache.pdfbox` types while declaring only `fontbox`, taking the rest
   transitively; the resolved version is unchanged.
+- **The release script owns the README release-status block.** It was a
+  hand-edit the script only validated, and the validation demanded the *target*
+  version — so between releases `develop` had to advertise an unpublished version
+  as "latest stable", behind a release link that 404s. `cut-release.ps1` now
+  promotes the in-development half to latest stable and opens the next patch line
+  as part of the release commit, and verifies the result after the mutation.
 
 ### Fixed
 
@@ -69,6 +75,40 @@ follow semantic versioning; release dates are ISO 8601.
   snippet produces, where it fails.
 - **Every published module README is reachable** from the module list in the root
   README; eight of the ten had no inbound link from anywhere.
+- **The release surface names the release that shipped.** `ROADMAP.md` described
+  2.1 as in development and 2.0 as the current stable line; 2.1 is now current,
+  2.0 is history, and `## Now` points at what follows. The README release-status
+  block, the changelog, the roadmap and the showcase metadata now agree on which
+  version is published and which is in development.
+- **`SECURITY.md` covers every 2.x line.** The supported-versions table jumped
+  from `2.1.x` to `1.9.x`, so a 2.0.x user could not tell whether their version
+  was supported.
+- **The documentation index carries the migration guide that applies.**
+  `docs/README.md` listed five superseded 1.x minor-to-minor upgrade guides on the
+  main path and omitted `migration/v2.0.0-modules.md` entirely. The current
+  guides are listed; the historical ones moved behind a fold.
+- **The PPTX backend is documented where it lives.** `CONTRIBUTING.md`,
+  `SECURITY.md` and the architecture overview described the pptx module as a
+  semantic exporter. Its primary backend is fixed-layout
+  (`document.backend.fixed.pptx`), alongside the older semantic manifest; a new
+  fragment kind must register a handler with both fixed-layout backends or it
+  renders in one output and vanishes from the other.
+- **Contributor instructions compile.** The "new built-in template" section
+  routed authors to `BusinessTheme`, `InvoiceTemplateV2` and `ProposalTemplateV2`
+  — none of which exist since 2.0 — and the engine-primitive section described
+  the entity/marker execution layer that 2.0 removed. Both now describe the
+  layered preset stack and the `NodeDefinition` pipeline. The bug-report template
+  asked for a 1.6-era version and carried a reproduction that never rendered; the
+  feature-request template pointed at a removed theme type; the pull-request
+  template offered a lane that no longer exists.
+- **Usage questions route to Discussions** through a new issue-template
+  `config.yml`, instead of being filed as labelled issues.
+- **Hand-maintained example counts are gone.** Four places stated four different
+  totals, none matching the catalogue.
+- **The release runbook checks things that exist.** One gate grepped the README
+  for a test-count claim the README does not make, so it always passed; another
+  compared the gallery row count against the example file count, two numbers that
+  had long diverged; three references pointed at a migration path that moved.
 - **A gallery entry for a deleted example is gone.** `examples/README.md`
   documented rethemeing through `InvoiceTemplateV2`, a type removed in 2.0, linked
   a source file that no longer exists, and carried a committed preview for it. The