[peterkir]

Add versioned release docs, p2 sites, and Java compatibility CI

Summary

Publish reproducible user guides, API references, and independently selectable p2 features alongside future tagged Maven releases. Expand cross-platform Java compatibility validation while keeping Ubuntu/Java 21 as the minimum canonical release environment.

This commit includes all 37 changed and newly added workspace files. Existing public Java signatures and exported package versions remain unchanged; library classfiles continue targeting Java 17, but the pinned Eclipse/SWT dependencies require Java 21 at runtime.

API Documentation and Build Gates

• Document public screenshot APIs, records, enum values, constructors, methods, and JUnit adapter lifecycle behavior, including package-level documentation for all three libraries.
• Explain explicit existing-Display ownership, UI-thread suppliers, bounded dispatch, native resource cleanup, capture outcomes, and preservation of original test failures.
• Add compiler-backed ApiDoclet validation for missing explicit public/protected API documentation, including overrides whose inherited documentation would otherwise hide omissions.
• Generate linked API references with -Xdoclint:all -Werror; wire per-library Javadoc checks into check and expose verifyJavadoc.
• Track injected release versions and tags as JAR task inputs to prevent stale release metadata across builds.

User Guides and p2 Packaging

• Add overview, installation, screenshot, JUnit adapter, and troubleshooting guides with release-version substitution and responsive static styling.
• Introduce the io.klib.swtbot.p2 packaging project and bnd p2 exporter configuration.
• Produce separate core, JUnit 4, and Jupiter features; adapters require core, and third-party SWT/Eclipse/JUnit dependencies remain supplied by consumer target platforms.
• Add :io.klib.swtbot.p2:exportP2 and export the exact tag-derived library versions.
• Package versioned documentation/API references and p2 repositories as downloadable release ZIP assets.

Release Integrity and GitHub Pages

• Add locked Node tooling for Markdown rendering, ZIP processing, XML validation, SemVer ordering, and Playwright browser checks; ignore generated Node dependencies.
• Generate a release manifest with tag, commit, Maven/OSGi versions, prerelease identity, and per-file SHA-256 hashes.
• Validate archive paths, reject symlinks/duplicate paths, bound archive/site sizes, and fail closed on corrupt checksums or inconsistent release metadata.
• Validate p2 units, artifacts, feature dependencies, and byte identity against generated library bundles; verify Maven/p2 library identity before remote release upload.
• Reuse published site payloads unchanged on same-tag reruns and reject payloads from a different tag commit.
• Extend tagged releases with validated site/p2 assets and checksums while preserving existing Maven publication and GitHub Release behavior.
• Add a trusted-default-branch Pages workflow triggered after successful Release runs or manually; reconstruct complete release history from validated GitHub release assets.
• Retain versioned docs/repositories, select the highest stable SemVer for latest, exclude prereleases from stable aliases, and prevent older reruns from rolling aliases back.
• Serialize Pages deployments and scope deployment permissions to the relevant jobs; historical releases without site assets are not backfilled.

Canonical Build and Compatibility Matrix

• Cover Linux, Windows, and macOS with Java 21, Java 25, and dynamically selected latest stable Temurin supported by pinned Gradle (>=21 <26, check-latest: true). Gradle 9.2.0 supports Java through 25; the upper bound prevents Java 26+ from being selected and must be reviewed with wrapper upgrades.
• Split out Ubuntu/Java 21 as the canonical build and exclude that entry from the compatibility matrix: one canonical plus eight compatibility entries.
• Keep snapshot and tagged publication pinned to Ubuntu/Java 21; compatibility jobs only build/test and never publish.
• Preserve tag-derived version inputs in every matrix entry and give test-report artifacts unique OS/JDK names.
• Omit Java 17 runtime compatibility, as requested, because the pinned SWT classes require Java 21.
• Add documentation/p2 CI validation, desktop/mobile browser checks, preview artifacts, and relevant workflow/tooling path triggers.

Documentation and Operations

• Update README and CHANGELOG for Pages URLs, stable/versioned p2 consumption, local previews, release assets, canonical builds, and compatibility coverage.
• Document one-time GitHub Pages setup, environment approvals, rerun/recovery behavior, durable release asset retention, size limits, and the separation from Maven Central approval.

Validation

• Java 21: all three library unit suites passed (11 tests); strict verifyJavadoc passed.
• Java 21: full canonical ci-build.sh build and tagged :io.klib.swtbot.p2:exportP2 passed using local 0.2.0 release-version inputs, without publication credentials.
• Prepared, verified, and assembled a local tagged site/p2 payload successfully.
• Playwright using installed Edge: desktop 1280x900 and mobile 390x844 guides/API pages passed heading, overflow, local-link, and JavaScript-error checks.
• Site tooling: 9 regression tests passed, covering stable-version selection, release identity, p2 composites, unsafe archives, retained history, prereleases, corruption, immutable reuse, and Javadoc failures.
• Java 25: all three library unit suites passed (11 tests).
• All four workflow YAML files parsed; bash -n .github/scripts/ci-publish.sh and staged git diff --check passed.
• Native SWT/OSGi UI gate, hosted Linux/macOS matrix, actual Sonatype publication, and live GitHub Pages deployment were not executed locally.

Deployment Notes

Enable GitHub Pages with GitHub Actions as the source before the first deployment. Existing Maven signing/publication secrets remain required for remote releases. No Maven artifacts or Pages content were published during local validation.