Publish combined JavaDocs from the existing Java CI build

[joshsh]

Goal

Publish a single combined JavaDoc site for Hydra at categoricaldata.net/hydra/…/javadoc/, built from the dist/java/ tree the Java CI workflow already generates on GitHub's runners, uploaded as a Pages artifact. Tag-triggered (matching the previous once-per-release cadence), commits nothing to any branch.

Key insight

The Java test workflow already, on every push to main, (a) builds the Haskell host, (b) generates Java into dist/java/, and (c) runs the Java tests. The fully-generated dist/java/ therefore already exists on a GitHub runner at test time. The previous Pages workflow failed only because it did a bare checkout and tried to regenerate (or resolve) Java itself, with dist/java/ gitignored/absent. The fix is to stop regenerating in a separate workflow and instead build the docs from the tree the test workflow already produced.

This is not blocked on #370. #370 (external versioned hosts) is a later optimization of step (a) — skip the local host build by pulling the published host — but the capability needed here (generated dist/java/ present in a CI run) exists today. #370 just makes it cheaper.

Approach: single job, tag-gated tail steps

Extend the existing Java CI job (the one that generates dist/java/ and runs the Java tests). After tests pass:

• Gate on tags: the javadoc/upload/deploy steps run only when startsWith(github.ref, 'refs/tags/') (plus workflow_dispatch for manual re-runs without re-tagging). Generation + tests stay unconditional, unchanged.
• Build one combined tree: a single javadoc invocation over the union of the published packages' sources — dist/java/{hydra-kernel,hydra-rdf,hydra-pg,hydra-java}/src/main/java — so cross-package @links resolve. (Verified locally: ~2,200 sources, full API, hydra/core/Term.html present.) Per-package trees give dead cross-links — do not split.
• Non-fatal javadoc: apply heads/java/bin/javadoc-nonfatal.init.gradle (Java coder emits unqualified @link refs for nested case-classes, failing the Javadoc build #449 cosmetic @link/entity warnings). The strict default build stays strict; this lenience is Pages-only.
• Upload + deploy as a Pages artifact (actions/upload-pages-artifact + actions/deploy-pages); keep Pages build_type: workflow. Commit nothing.
• hydra-ext excluded until it ships to Maven Central — restore it to the combined sourcepath then (companion issue).
• Landing page: carry over main's docs/index.html.
• Preserve the public URL path (…/hydra-java/javadoc/) so existing links don't break.

Cleanup (part of this work)

• Decommission the stale docs branch — an orphan (no common ancestor with main), last touched 2025-08-28, carrying a dead pre-restructure monolith snapshot; serves nothing under build_type: workflow. Delete once the artifact deploy is live.
• Revert the three 0.16.0-era pages.yml edits on main that assumed a local dist/java/ (dead under this approach).

Notes

• Cadence: tag-gated, not every-push — the public JavaDoc site should reflect the released API, not in-flight main; also avoids republishing on doc-comment-only pushes. workflow_dispatch covers re-running a failed tag publish without re-tagging.
• Companion: Restore hydra-ext to the combined JavaDocs when it ships to Maven Central #451 — restore hydra-ext to the combined tree once published to Maven Central.

For #418. For #449.

[joshsh]

Note: tagging as a bug, since JavaDocs publication previously worked (when generated Java sources were still checked in to the Git repository)

[joshsh]

Done — combined JavaDoc Pages deploy is live and verified.

Implemented the tag-gated, CI-artifact-based approach from this issue: a workflow_run-triggered .github/workflows/pages.yml (companion to the CI workflow) that pulls the dist-java artifact the CI run already generated, builds a single combined JavaDoc tree over all published packages, and deploys it as a Pages artifact — committing nothing to any branch (no repo bloat). The strict @link errors from #449 are absorbed via -Xdoclint:none.

This resolves the three failure modes the earlier attempts hit:

• non-existent :hydra-ext:javadoc project →
• kernel not on the classpath (package hydra.core does not exist) →
• dist/java/ absent on a clean CI checkout (it's gitignored) → fixed by downloading the dist-java artifact from the triggering CI run rather than regenerating.

Verified in production (via workflow_dispatch, run 27281204879 → success). The live site at categoricaldata.net/hydra/hydra-java/javadoc/ now serves one combined, cross-linked tree containing all four published packages:

• hydra/core/Term.html (kernel) — 200
• hydra/java/Coder.html (hydra-java coder) — 200 (this page was missing from the old per-package deployment)
• hydra/pg/model/Vertex.html (pg) — 200
• hydra/rdf/syntax/Iri.html (rdf) — 200

Cross-package links resolve because all packages share one tree.

Note: the above exercised the workflow_dispatch path (which falls back to the latest successful CI run). The tag-triggered path — the head_branch-matches-a-tag gate in the "Resolve CI run and confirm tag" step — will be exercised for the first time when the next release tag (0.16.1) is pushed. Build + deploy + combined-tree are confirmed; the tag gate is the one branch to watch at the next tag.

Follow-up: #451 (restore hydra-ext to the combined sourcepath once it ships to Maven Central).