DemchaAV · DemchaAV · Jul 31, 2026
@@ -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
 

@@ -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.
@@ -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.
 

@@ -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>
@@ -69,6 +69,36 @@ 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 described 2.1.1 with 2.1.0's headline.
+- **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