docs: Doxygen-API + Validierungsprotokoll + Porting-Tutorial

Für einen Mathematiker der unabhängig validieren und eigene Forschung
einbringen möchte.

Doxygen-Kommentare (code/include/):
  newton_solver.hpp — newton_euclidean(), newton_spherical(), newton_hyper_ideal()
    je mit \param, \return, \note, \see inkl. mathematischer Begründung
    (Konvexität, Vorzeichenkonvention, SparseQR-Fallback-Erklärung)
  layout.hpp — euclidean_layout(), spherical_layout(), hyper_ideal_layout()
    mit vollständiger Parameter-Doku, halfedge_uv-Semantik, Poincaré-Disk-Note

Neues Dokument:
  doc/math/validation-protocol.md
    7 reproduzierbare Checks mit konkreten Befehlen und erwartetem Output:
    0. 170 Tests, 1 Skip
    1. Gauss–Bonnet exakt (1e-10)
    2. FD-Gradientencheck < 1e-6 für alle 3 Geometrien
    3. Newton-Konvergenz < 50 Iterationen
    4. τ ∈ SL(2,ℤ)-Fundamentaldomäne (3 Invarianten)
    5. Möbius-Arithmetik (Inverse, Compose, from_three)
    6. End-to-End-Pipeline
    7. Manueller τ-Check für torus_4x4.off (Codebeispiel)

Neues Tutorial:
  doc/tutorials/add-inversive-distance.md
    Vollständiger Step-by-Step-Port von Phase 9a (Luo 2004):
    Header anlegen, Energie/Gradient implementieren, FD-Check,
    Newton-Wrapper, CMakeLists, Java-Referenzvergleich, Checkliste.

doc/getting-started.md:
  Abschnitt "Known issues": macOS-Finder-Duplikate (rm-Befehl),
  Warnung "First build 30–90s" (Tarball-Extraktion)

README.md:
  Zwei neue Links in der Dokumentationstabelle (validation-protocol,
  tutorial)

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

doc/math/validation-protocol.md

@@ -0,0 +1,213 @@
+# Validation Protocol
+
+Concrete, reproducible steps to verify the mathematical correctness of
+conformallab++.  Every check below has a deterministic expected outcome.
+
+---
+
+## Prerequisites
+
+```bash
+cmake -S code -B build -DWITH_CGAL=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build --target conformallab_cgal_tests -j$(nproc)
+```
+
+---
+
+## Check 0 — All tests pass
+
+```bash
+ctest --test-dir build -R "^cgal\." --output-on-failure
+```
+
+**Expected output (last lines):**
+```
+100% tests passed, 0 tests failed out of 170
+
+The following tests did not run:
+    206 - cgal.HomologyGenerators.Genus2_FourGeneratorPaths_BLOCKED (Skipped)
+```
+
+If any test fails, stop — the implementation is broken.
+
+---
+
+## Check 1 — Gauss–Bonnet (topological identity, error < 1e-10)
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="GaussBonnet.*" -v
+```
+
+**Expected:** all 8 tests `[  PASSED  ]`
+
+What is verified: for each test mesh (tetrahedron χ=2, torus χ=0, open mesh χ=1):
+
+```
+Σᵥ (2π − Θᵥ)   =   2π · χ(M)   ± 1e-10
+```
+
+This is a **pure topology check** — it fails only if vertex/face counts or
+property-map assignments are wrong.  It does not depend on the Newton solver.
+
+---
+
+## Check 2 — Euclidean gradient consistency (FD vs. analytic, error < 1e-6)
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="EuclideanFunctional.GradientCheck*" -v
+```
+
+**Expected:** all `GradientCheck_*` tests `[  PASSED  ]`
+
+What is verified: for ε = 1e-5,
+
+```
+|G(u)ᵢ  −  (E(u + εeᵢ) − E(u − εeᵢ)) / (2ε)| < 1e-6
+```
+
+This check **proves that the energy and its gradient are mathematically consistent**.
+A failing FD check means Newton will converge to the wrong point — it is the most
+important correctness check for any new functional.
+
+Also run for Spherical and HyperIdeal:
+```bash
+./build/conformallab_cgal_tests --gtest_filter="SphericalFunctional.GradientCheck*" -v
+./build/conformallab_cgal_tests --gtest_filter="HyperIdealFunctional.GradientCheck*" -v
+```
+
+---
+
+## Check 3 — Newton convergence on canonical test meshes
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="NewtonSolver.*" -v
+```
+
+**Expected:** all 11 tests `[  PASSED  ]`
+
+Each test verifies:
+- `res.converged == true`
+- `res.grad_inf_norm < 1e-8`
+- `res.iterations < 50`  (typically 5–20 for the small test meshes)
+
+---
+
+## Check 4 — Period matrix: SL(2,ℤ)-reduction invariants
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="PeriodMatrix.*" -v
+```
+
+**Expected:** all 7 tests `[  PASSED  ]`
+
+The three mathematical invariants checked for **any** genus-1 output τ:
+
+| Property | Condition | Why |
+|---|---|---|
+| Upper half-plane | `Im(τ) > 0` | τ encodes a positive-area lattice |
+| Outside unit disk | `|τ| ≥ 1 − 1e-10` | SL(2,ℤ) reduction step |
+| Vertical strip | `|Re(τ)| ≤ 0.5 + 1e-10` | SL(2,ℤ) reduction step |
+
+These hold for **any** well-formed genus-1 mesh — they are topology, not geometry.
+
+---
+
+## Check 5 — Möbius arithmetic (complex analysis correctness)
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="MobiusMap.*" -v
+```
+
+**Expected:** all 8 tests `[  PASSED  ]`
+
+What is verified:
+- `T ∘ T⁻¹ = Id` (inverse is correct)
+- `(T₁ ∘ T₂)(z) = T₁(T₂(z))` (composition is associative)
+- `from_three(z₁, z₂, z₃)` maps z₁→0, z₂→1, z₃→∞ (unique Möbius transformation)
+
+A bug here would corrupt **all** hyperbolic holonomy computation.
+
+---
+
+## Check 6 — End-to-end pipeline (build + solve + layout)
+
+```bash
+./build/conformallab_cgal_tests --gtest_filter="Pipeline.*" -v
+```
+
+**Expected:** all 5 tests `[  PASSED  ]`
+
+What is verified: starting from a mesh file, the full pipeline
+(setup → Gauss-Bonnet → Newton → layout → serialise → reload)
+produces a consistent result.
+
+---
+
+## Check 7 — Manual torus τ verification
+
+This check requires adding a small program (or modifying an existing test).
+It validates that `torus_4x4.off` produces τ in the fundamental domain:
+
+```cpp
+#include "conformal_mesh.hpp"
+#include "euclidean_functional.hpp"
+#include "newton_solver.hpp"
+#include "cut_graph.hpp"
+#include "layout.hpp"
+#include "period_matrix.hpp"
+#include "mesh_io.hpp"
+#include <iostream>
+
+int main() {
+    conformallab::ConformalMesh mesh;
+    conformallab::load_mesh(mesh, "code/data/off/torus_4x4.off");
+
+    auto maps = conformallab::setup_euclidean_maps(mesh);
+    conformallab::compute_euclidean_lambda0_from_mesh(mesh, maps);
+    conformallab::enforce_gauss_bonnet(mesh, maps);
+
+    auto res = conformallab::newton_euclidean(mesh, std::vector<double>(maps.n_dof, 0.0), maps);
+    std::cout << "Converged: " << res.converged
+              << "  iterations: " << res.iterations
+              << "  |G|∞: " << res.grad_inf_norm << "\n";
+
+    auto cg  = conformallab::compute_cut_graph(mesh);
+    conformallab::HolonomyData hol;
+    conformallab::euclidean_layout(mesh, res.x, maps, &cg, &hol, true);
+    auto pd  = conformallab::compute_period_matrix(hol);
+
+    std::cout << "τ = " << pd.tau_reduced.real()
+              << " + " << pd.tau_reduced.imag() << "i\n";
+    std::cout << "|τ| = " << std::abs(pd.tau_reduced) << "\n";
+    std::cout << "|Re(τ)| = " << std::abs(pd.tau_reduced.real()) << "\n";
+}
+```
+
+**Expected output (torus_4x4.off, R=2, r=1 torus of revolution):**
+```
+Converged: 1   iterations: <30   |G|∞: <1e-8
+τ = [small]  + [positive]i        (Re close to 0 by 4-fold symmetry)
+|τ| ≥ 1.0                          (fundamental domain)
+|Re(τ)| ≤ 0.5                      (fundamental domain)
+```
+
+The exact value of Im(τ) depends on the 3D embedding (R=2, r=1 gives unequal
+inner/outer edge lengths).  Use `torus_8x8.off` for a finer approximation.
+
+---
+
+## Summary checklist
+
+```
+[ ] Check 0: 170 tests pass, 1 skip
+[ ] Check 1: Gauss–Bonnet exact (1e-10)
+[ ] Check 2: FD gradient < 1e-6 for all 3 geometries
+[ ] Check 3: Newton convergence < 50 iterations
+[ ] Check 4: τ in SL(2,ℤ) fundamental domain
+[ ] Check 5: Möbius arithmetic (inverse, compose, from_three)
+[ ] Check 6: End-to-end pipeline
+[ ] Check 7: Torus τ in upper half-plane with correct symmetry
+```
+
+All checks are deterministic and do not depend on random initialization or
+floating-point non-determinism beyond standard IEEE-754.