DemchaAV
diff --git a/‎docs/SHOWCASE.md‎
Lines changed: 72 additions & 38 deletions b/‎docs/SHOWCASE.md‎
Lines changed: 72 additions & 38 deletions
@@ -1,51 +1,85 @@
 # GraphCompose GitHub Pages Showcase
 
-This folder contains the lightweight static showcase site for GraphCompose. It is intentionally plain HTML, CSS, JavaScript, and JSON so GitHub Pages can publish it directly from the main repository without a build step.
+This folder is the static showcase site for GraphCompose. It is plain HTML,
+CSS, JavaScript, and a generated JSON manifest, so GitHub Pages publishes it
+directly from the main repository with no build step.
 
 ## Files
 
-- `index.html` is the single-page showcase.
-- `styles.css` contains the visual system and responsive layout.
-- `examples.json` is the gallery data source.
-- `assets/logo/` contains the showcase logo asset.
-- `assets/screenshots/` contains PNG previews for generated PDFs.
-- `assets/pdf/` contains the generated PDF examples linked from the gallery.
-
-## Add A New Showcase Item
-
-1. Generate the PDF from the examples module.
-2. Copy the PDF into `docs/assets/pdf/`.
-3. Add a PNG screenshot into `docs/assets/screenshots/`.
-4. Add a new object to `docs/examples.json`.
-5. Commit and push.
-
-Each `examples.json` object uses this shape:
-
-```json
-{
-  "title": "Cinematic Invoice",
-  "description": "A short description of the generated document.",
-  "tags": ["Template", "Tables", "Theme"],
-  "image": "assets/screenshots/invoice-v2.png",
-  "pdf": "assets/pdf/invoice-v2.pdf",
-  "code": "https://github.com/DemchaAV/GraphCompose/blob/main/examples/src/main/java/com/demcha/examples/InvoiceCinematicFileExample.java"
-}
-```
+- `index.html` — the single-page showcase. Holds the hero, install snippets,
+  feature/architecture sections, and the searchable gallery shell.
+- `styles.css` — the visual system and responsive layout.
+- `examples.js` — client script that fetches the manifest and renders the
+  gallery (search, category filters, highlights strip, lightbox).
+- `examples.json` — **generated** gallery manifest. Do **not** hand-edit it;
+  it is rewritten by `ShowcaseSync` (see below).
+- `assets/logo/` — the showcase logo asset.
+- `showcase/pdf/<category>/<group>/…` — generated PDF examples linked from the
+  gallery.
+- `showcase/screenshots/<category>/<group>/…` — PNG previews auto-rendered from
+  those PDFs.
 
-## Local Preview
+> Older revisions of this doc referenced `docs/assets/screenshots` and
+> `docs/assets/pdf` plus a manual "copy the PDF, add a PNG, edit examples.json"
+> flow. That is no longer accurate — previews and the manifest are generated
+> under `docs/showcase/**` by `ShowcaseSync`.
 
-Open `docs/index.html` directly in a browser for a quick visual check. If your browser blocks `fetch("examples.json")` for local `file://` pages, run any tiny static server from the repository root and open the `/docs/` path. No build step is required.
+## Add a new showcase item
 
-## GitHub Pages
+The gallery is driven by code, not by hand-editing JSON. Source of truth:
+`examples/src/main/java/com/demcha/examples/support/ShowcaseMetadata.java`.
+
+1. Add the example `.java` under the right category sub-package in
+   `examples/src/main/java/com/demcha/examples/`.
+2. Make it write its PDF via `ExampleOutputPaths.prepare(category, fileName)`
+   so the output lands under the matching `examples/target/generated-pdfs/`
+   subfolder.
+3. Wire it into `GenerateAllExamples.main`.
+4. Register a metadata entry in `ShowcaseMetadata.java` (title, one-line
+   description, search tags, source link) keyed by the generated PDF basename.
+5. Regenerate, then sync:
+
+   ```bash
+   ./mvnw -f examples/pom.xml exec:java -Dexec.mainClass=com.demcha.examples.GenerateAllExamples
+   ./mvnw -f examples/pom.xml exec:java -Dexec.mainClass=com.demcha.examples.support.ShowcaseSync
+   ```
+
+   `ShowcaseSync` copies each PDF into `docs/showcase/pdf/…`, rasterises a PNG
+   into `docs/showcase/screenshots/…`, and rewrites `docs/examples.json`.
+6. Commit the regenerated `docs/showcase/**` assets and `docs/examples.json`.
+
+## Version and source links
 
-To publish this site with GitHub Pages:
+- The displayed version lives **only** in `index.html` (JSON-LD
+  `softwareVersion`, the JitPack download URL, the hero badge, and the Maven +
+  Gradle install snippets). It does not inherit from the pom.
+- `scripts/cut-release.ps1` flips all of those — plus the README and poms — to
+  the release tag in the release commit, and `VersionConsistencyGuardTest`
+  fails the `verify` gate if any of them drift out of sync with the library
+  `pom.xml`. Do not hand-bump the site version ahead of a release.
+- "View source" links resolve through `ShowcaseMetadata.GH_BASE`, which
+  `cut-release.ps1` flips between `/blob/develop` (while developing) and
+  `/blob/v<tag>` (at release) so the deployed site points at the exact source
+  that produced each artefact.
 
-1. Open repository Settings.
-2. Go to Pages.
-3. Set Source to "Deploy from a branch".
-4. Select the main branch and `/docs` folder.
-5. Save.
+## Local preview
+
+The gallery uses `fetch("examples.json")`, which browsers block for local
+`file://` pages. Run any tiny static server from the repository root and open
+the `/docs/` path:
+
+```bash
+python -m http.server 8000
+# then open http://localhost:8000/docs/
+```
+
+Opening `docs/index.html` directly still renders everything except the
+JS-driven gallery (the `<noscript>` static index lists every PDF as a
+fallback). No build step is required.
+
+## GitHub Pages
 
-The site should become available at:
+Published from the `main` branch `/docs` folder (Settings → Pages → Deploy from
+a branch → `main` / `/docs`). Live at:
 
 https://demchaav.github.io/GraphCompose/