docs(landing): make quick starts executable

[EvenSol]

D052 — landing-page quick starts and navigation contracts

Refs #2499. This is the single active documentation-quality campaign PR for the frozen D052 rotation-1 batch.

Frozen scope

• docs/index.md
• docs/README.md
• docs/test_landing_page_documentation.py

src/test/java/neqsim/DocExamplesCompilationTest.java was inspected and left unchanged because its existing testDocumentationLandingPageQuickStart() already exercises every NeqSim call and asserts physical density/compressibility ranges. No production Java, API, notebook, dependency, global navigation design, or unrelated documentation is changed.

Confirmed defects and evidence

• High: both landing pages presented their shared Java quick start as top-level statements, so it was not a complete compilable program.
• High: those examples used System.out.println, prohibited by the repository’s root instructions even in documentation snippets.
• High: docs/index.md used the legacy high-level neqsim.thermo wrapper instead of the documentation agent’s required public from neqsim import jneqsim gateway.
• Medium: no source-level regression contract kept the duplicated Java blocks identical or guarded their completeness, output policy, Python gateway, front matter, fences, internal destinations, and fragments.

Fixes

• Convert both Java snippets to the same complete Java 8-compatible NeqSimQuickStart class with main, Log4j2 output, the current SRK/TP-flash API, and explicit kg/m3 access.
• Route the Python example through jneqsim.thermo.system.SystemSrkEos and jneqsim.thermodynamicoperations.ThermodynamicOperations.
• Add a four-test hermetic documentation contract covering structure, all internal links/fragments, exact shared-Java equality and completeness, forbidden Java output, and supported Python gateway usage.

Validation performed

Authoritative base: 12b0e2fab3c4ea244a810e8058ca57c08e72631f. Branch head before PR creation: ebce9e9217627445e12df413dbcbb60781433cc2; GitHub reports three commits ahead, zero behind, and exactly the three frozen paths. All three remote blobs exactly match the locally reviewed payload.

• python -m unittest docs/test_landing_page_documentation.py -v: 4/4 passed
• python -m py_compile docs/test_landing_page_documentation.py: passed
• python devtools/check_documentation_search.py: passed — 649 Markdown pages and one standalone HTML page
• internal navigation: 118 link occurrences resolve; all six fragments resolve
• external links: all 12 unique URLs resolve; GitHub repositories/workflow were verified through the connector, and the Javadoc plus two Shields endpoints returned HTTP 200 after retry
• equation scan: no equations or math delimiters occur in the changed pages; equation rendering is not applicable
• images/notebooks/generated pages: none changed

Fresh resilient validation environment:

• resolution: online-new-snapshot
• immutable public-PyPI snapshot: 48 verified wheels
• NeqSim 3.17.0, Python 3.12.13, OpenJDK 17.0.19
• exact Python fence: executed successfully, density 39.17 kg/m³
• exact Java fence: source identity verified, then compiled and executed successfully with Java’s source launcher against the NeqSim 3.17.0 shaded artifact from the verified public-PyPI environment
• existing focused current-source JUnit covers the same NeqSim calls and checks density 35–50 kg/m3 and compressibility 0.8–1.0

Documentation impact: this PR directly repairs the two public landing pages and adds a focused regression contract; no other behavior is user-visible.

LOCAL VALIDATION BLOCKED BY INFRASTRUCTURE

The canonical Maven endpoint was configured, but this runner could not resolve repo.maven.apache.org. Therefore the following exact commands were attempted and are not claimed as passed:

• ./mvnw -Dmaven.repo.local=/workspace/.cache/maven-d052/repository -Dtest=DocExamplesCompilationTest#testDocumentationLandingPageQuickStart test — blocked resolving maven-enforcer-plugin:3.6.3
• python devtools/run_spotless.py apply — blocked resolving the Spotless Maven plugin
• python devtools/run_spotless.py check — blocked resolving the Spotless Maven plugin
• pre-commit run --all-files --hook-stage pre-commit — pre-commit installed in a fresh 57-wheel verified environment, then blocked only at the Spotless hook
• pre-commit run --all-files --hook-stage pre-push — documentation-search hook passed; Spotless hook was blocked by the same Maven DNS failure

A local Ruby/Jekyll renderer is unavailable, so bundle exec jekyll build, generated search-index verification, and rendered browser inspection were not run locally; the hosted build/search result is recorded below. No blocked check is reported as successful. The changed files contain no Java source, equations, images, or layout/CSS changes; the Markdown/HTML continuity and destination contracts pass statically.

One inherited baseline defect was discovered outside the frozen paths: docs/test_optimizer_documentation.py uses \\s in a raw heading regex and its anchor subtests fail on unchanged master. This PR neither causes nor masks that failure; it is deferred to a separate bounded batch to avoid mixing optimizer scope into D052.

Hosted exact-head validation

All workflows triggered for exact head ebce9e9217627445e12df413dbcbb60781433cc2 completed successfully:

• documentation search coverage built the Jekyll site and verified the generated search index
• pre-commit checks passed
• Spotless completed successfully and its uploaded spotless.patch is exactly zero bytes
• CodeQL passed
• build workflow’s agent/skill and change-detection jobs passed; Java tests/Javadoc were correctly skipped by the repository’s docs-only path filter

The hosted Jekyll build proves source rendering completes, but it did not publish a browsable artifact for visual inspection. The current-source focused JUnit is also not claimed because the docs-only workflow intentionally skipped Java jobs; the exact snippet was instead compiled/executed against the verified public NeqSim 3.17.0 artifact as recorded above.

Exclusions and next scope

docs/REFERENCE_MANUAL_INDEX.md remains excluded because open PRs #2086 and #2632 overlap it. docs/quickstart/index.md and docs/_config.yml were scanned without a confirmed D052 defect. No global HTML redesign, unrelated link normalization, optimizer documentation change, or production-code change is included.

D052 remains in progress pending final human/Copilot disposition and, if a compatible artifact becomes available, visual inspection. Current-source focused JUnit execution remains explicitly unclaimed; all hosted checks applicable to this docs-only diff are green.