docs: restructure documentation into focused files

README.md: reduced from 703 to ~75 lines — what/why, status, quick
start, minimal usage example, navigation table to doc/ files.

doc/architecture/overall_pipeline.md: trimmed — roadmap, extension
points, declarative pipeline YAML, and references sections removed
(each now has its own dedicated file). Replaced with a link table.

New files:
  doc/getting-started.md       — build modes, single-test invocation, CLI
  doc/api/pipeline.md          — full pipeline API with code for all 3 geometries
  doc/api/extending.md         — new functionals, geometry modes, Java porting guide
  doc/api/contracts.md         — processing unit preconditions/provides table
  doc/api/cgal-package.md      — Phase 8 CGAL package design + YAML pipeline (TODO)
  doc/math/geometry-modes.md   — Euclidean/Spherical/HyperIdeal comparison
  doc/math/references.md       — all papers by module
  doc/roadmap/phases.md        — Phases 1–10 with porting/research boundary
  doc/roadmap/java-parity.md   — Java vs C++ feature parity table
  doc/contributing.md          — language policy, test standards, release flow

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

doc/roadmap/java-parity.md

@@ -0,0 +1,86 @@
+# Java ConformalLab vs. conformallab++ — Feature Parity
+
+Reference: [github.com/varylab/conformallab](https://github.com/varylab/conformallab)  
+Java package root: `de.varylab.discreteconformal`
+
+When porting a Java class, locate the original in the Java repository and use it
+as the reference implementation for expected behaviour, edge cases, and test cases.
+
+---
+
+## Algorithm parity
+
+| Mathematical layer | Java ConformalLab | conformallab++ | Notes |
+|---|---|---|---|
+| Euclidean functional — energy, gradient | ✅ | ✅ | |
+| Spherical functional — energy, gradient, gauge-fix | ✅ | ✅ | |
+| HyperIdeal functional — energy, gradient | ✅ | ✅ | |
+| Inversive-distance functional (Luo 2004) | ✅ | ❌ Phase 9a | `InversiveDistanceFunctional.java` |
+| Euclidean Hessian — cotangent Laplacian | ✅ analytic | ✅ analytic | Pinkall–Polthier (1993) |
+| Spherical Hessian — ∂α/∂u via law of cosines | ✅ analytic | ✅ analytic | |
+| HyperIdeal Hessian — ζ → lᵢⱼ → β/α chain | ✅ analytic | ⚠️ symmetric FD | Phase 9b |
+| Newton solver | ✅ | ✅ | |
+| SparseQR fallback for gauge modes | unknown | ✅ | New in C++ |
+| Cone metrics — prescribed Θᵥ ≠ 2π | ✅ fully | ⚠️ data structure only | |
+| Layout / embedding — ℝ² / H² / S² | ✅ | ✅ priority-BFS all three | |
+| Exact hyperbolic trilateration | ✅ Möbius | ✅ Möbius + law of cosines | |
+| halfedge_uv — seam-aware UV (texture atlas) | ✅ | ✅ | |
+| Gauss–Bonnet consistency check | ✅ | ✅ | |
+| Tree-cotree cut graph (2g edges) | ✅ | ✅ Erickson–Whittlesey (2005) | |
+| Holonomy — Euclidean (translations) | ✅ | ✅ | |
+| Holonomy — Hyperbolic (SU(1,1) Möbius maps) | ✅ | ✅ | |
+| Period matrix τ — genus 1, SL(2,ℤ)-reduced | ✅ | ✅ | |
+| Fundamental domain — genus 1 | ✅ | ✅ CCW parallelogram | |
+| 4g-polygon boundary walk — genus g > 1 | ✅ | ❌ Phase 9c | `FundamentalDomainUtility.java` |
+| Siegel period matrix Ω — genus g ≥ 2 | ✅ | ❌ Phase 10b | |
+| Global uniformization — genus g ≥ 2 | ✅ | ❌ Phase 10c | |
+| Clausen / Lobachevsky / ImLi₂ | ✅ | ✅ | |
+| Poincaré disk / Lorentz boost visualisation | ✅ | ✅ | |
+| Mesh I/O + serialisation | ✅ XML/CoHDS | ✅ OFF/OBJ/PLY + JSON/XML | |
+| Interactive viewer | ✅ jReality | ✅ libigl/GLFW | |
+
+---
+
+## Java utility classes not yet ported
+
+These exist in `de.varylab.discreteconformal.util` in the Java library.
+They are candidates for Phase 9 or Phase 10.
+
+| Java class | Description | Phase |
+|---|---|---|
+| `InversiveDistanceFunctional` | Inversive-distance conformal energy | 9a |
+| `DiscreteHarmonicFormUtility` | Discrete harmonic 1-forms | 10a prerequisite |
+| `DiscreteHolomorphicFormUtility` | Holomorphic differentials on discrete surfaces | 10a |
+| `DiscreteRiemannUtility` | Discrete Riemann surfaces | 10 |
+| `CanonicalBasisUtility` | Canonical homology basis for genus g | 9c / 10 |
+| `HomologyUtility` | Homology computation | 9c |
+| `HomotopyUtility` | Homotopy generators | 9c |
+| `SpanningTreeUtility` | Spanning tree algorithms | 8 / infrastructure |
+| `SurgeryUtility` | Mesh surgery (cut/glue) | — |
+| `StitchingUtility` | Seam stitching | — |
+| `CuttingUtility` | Advanced cutting (beyond tree-cotree) | 9c |
+| `HyperellipticUtility` | Hyperelliptic surfaces | 10 |
+| `LaplaceUtility` | Discrete Laplace operators | 9 / infrastructure |
+| `ConformalStructureUtility` | Conformal structure extraction | 10 |
+
+---
+
+## HyperIdeal Hessian: FD vs. analytic
+
+The Java library computes the HyperIdeal Hessian analytically through the chain:
+
+```
+(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ
+```
+
+conformallab++ uses a **symmetric finite-difference approximation**:
+
+```
+H[i,j] = ( G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i] ) / (2ε),   ε = 1e-5
+```
+
+Accuracy: O(ε²) ≈ 10⁻¹⁰ relative error. PSD guaranteed by strict convexity (Springborn 2020).
+Cost: n extra gradient evaluations per Newton step.
+Impact: negligible for meshes < 500 DOFs; measurable for larger meshes.
+
+The analytic Hessian is deferred to Phase 9b.