doc/api/contracts.md

@@ -13,11 +13,11 @@ of all preceding units.
 | `load_mesh()` | Valid file path, supported format (OFF/OBJ/PLY) | Manifold, oriented, triangulated `ConformalMesh` |
 | `setup_*_maps()` | Triangulated mesh | Initialised property maps; `lambda0` zeroed |
 | `compute_*_lambda0_from_mesh()` | `setup_*_maps()` called | `lambda0[e]` set from 3-D edge lengths |
-| `check_gauss_bonnet()` | `theta_v[v]` set for all vertices | Throws `std::runtime_error` if Σ(2π−Θᵥ) ≠ 2π·χ(M) |
-| `enforce_gauss_bonnet()` | `theta_v[v]` set | Σ(2π−Θᵥ) = 2π·χ(M) guaranteed; `theta_v` modified |
+| `check_gauss_bonnet()` | `theta_v[v]` set · **EuclideanMaps or SphericalMaps only** | Throws `std::runtime_error` if Σ(2π−Θᵥ) ≠ 2π·χ(M). Deleted overload for `HyperIdealMaps` — see note below. |
+| `enforce_gauss_bonnet()` | `theta_v[v]` set · **EuclideanMaps or SphericalMaps only** | Σ(2π−Θᵥ) = 2π·χ(M) guaranteed; `theta_v` modified. Deleted overload for `HyperIdealMaps` — see note below. |
 | `newton_euclidean()` | GB satisfied · DOFs assigned · `lambda0` initialised | `NewtonResult.x` — converged scale factors; `.converged`, `.iterations`, `.grad_inf_norm` |
 | `newton_spherical()` | GB satisfied · DOFs assigned · gauge vertex pinned | Same as above |
-| `newton_hyper_ideal()` | `assign_all_dof_indices()` called · `lambda0` initialised | Same as above |
+| `newton_hyper_ideal()` | `assign_all_dof_indices()` called · **no `lambda0` needed** · **no GB pre-check** | Same as above. HyperIdeal computes lengths internally from b_v, a_e (via ζ₁₃/ζ₁₄/ζ₁₅); `lambda0` is irrelevant. Energy is strictly convex → Newton converges for any targets without a pre-check. |
 | `compute_cut_graph()` | Closed, orientable, triangulated mesh | `CutGraph.cut_edge_flags` — 2g seam edges; `.genus` |
 | `euclidean_layout()` | `newton_euclidean()` converged | `Layout2D.uv[v]` · `.halfedge_uv[h]` · `HolonomyData.translations` |
 | `spherical_layout()` | `newton_spherical()` converged | `Layout3D.xyz[v]` |
@@ -53,17 +53,28 @@ The solver never writes to pinned DOFs. All indexing is 0-based and contiguous.
 
 ---
 
-## Gauss–Bonnet — the most common source of failure
+## Gauss–Bonnet — the most common source of failure for Euclidean and Spherical
 
 Prescribing angles that violate Gauss–Bonnet means no conformal factor can realise the
 target metric — the Newton solver will iterate indefinitely without converging.
 
 ```cpp
-// Option A: verify before solving (throws on violation)
-check_gauss_bonnet(mesh, maps);
+// Option A: verify before solving — throws std::runtime_error on violation.
+// Works with EuclideanMaps and SphericalMaps only.
+check_gauss_bonnet(mesh, euclidean_maps);  // or spherical_maps
+check_gauss_bonnet(mesh, spherical_maps);
 
-// Option B: auto-correct (redistributes defect uniformly across all vertices)
-enforce_gauss_bonnet(mesh, maps);
+// Option B: auto-correct — redistributes the defect uniformly across all vertices.
+enforce_gauss_bonnet(mesh, euclidean_maps);
+enforce_gauss_bonnet(mesh, spherical_maps);
+
+// ⚠  HyperIdealMaps: both functions have deleted overloads — calling them is a
+// compile error.  Reason: the correct hyperbolic Gauss–Bonnet identity includes
+// a surface area term: Σ(2π−Θᵥ) − Area(M) = 2π·χ(M), not Σ(2π−Θᵥ) = 2π·χ(M).
+// No pre-check is needed for HyperIdeal: the energy is strictly convex
+// (Springborn 2020 Theorem 1.3), so newton_hyper_ideal converges for any targets.
 ```
 
 The target violation is `|Σ(2π−Θᵥ) − 2π·χ(M)| > tol`. Default tolerance: `1e-10`.
+Applicable to closed meshes only — for open meshes, pin the boundary directly
+and skip the Gauss–Bonnet check (the identity does not hold for meshes with boundary).

doc/reviewer/usability-audit-2026-05-31.md

@@ -538,7 +538,7 @@ exposed via the CGAL public API, but a CLI user cannot reach them.
 |----|------|------|----------|--------|
 | U1 | README + 4 examples | Usability | 🔴 Critical | ✅ Fixed 2026-05-31 |
 | U2 | examples/ (missing) | Usability | 🔴 Critical | ✅ Fixed 2026-05-31 |
-| U3 | `contracts.md:16` | Doc error | 🟡 Medium | 🟡 Open |
+| U3 | `contracts.md:16` | Doc error | 🟡 Medium | ✅ Fixed 2026-05-31 |
 | U4 | `README.md:17` | Stale | 🟡 Medium | 🟡 Open |
 | U5 | `Discrete_conformal_map.h:14` | Stale | 🟡 Medium | 🟡 Open |
 | U6 | README + 2 examples | Stale | 🟡 Medium | 🟡 Open |