diff --git a/doc/reviewer/api-performance-audit-2026-05-31.md b/doc/reviewer/api-performance-audit-2026-05-31.md
new file mode 100644
index 0000000..b788d37
--- /dev/null
+++ b/doc/reviewer/api-performance-audit-2026-05-31.md
@@ -0,0 +1,420 @@
+# API-Consistency & Performance Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Low-level API (`code/include/*.hpp`), high-level CGAL API (`code/include/CGAL/`), Newton-solver performance
+**Focus:** Public-API naming consistency and runtime performance — NOT port-faithfulness or test coverage.
+
+This document is self-contained. A new session can pick up any finding below and
+act on it without prior context. Each finding includes:
+- exact file path + line numbers (verified by direct file read)
+- a minimal reproduction of the problematic code
+- the recommended fix
+- acceptance criteria for "done"
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Hint / nice-to-have
+
+> **Companion documents (no overlap in findings):**
+> - `external-audit-2026-05-30.md` — port-faithfulness bugs
+> - `test-coverage-error-handling-audit-2026-05-31.md` — test gaps + error handling
+> - **this file** — API consistency + performance
+>
+> Cross-reference: performance findings B2/B3/B5 below share root cause with
+> `FINDING-H2` ("five near-identical Newton loops") in the test-coverage audit.
+> A single `newton_core` refactor can resolve all of them together.
+
+---
+
+## How to read this document in a new session
+
+```bash
+# Build the CGAL suite (the API + solvers live behind WITH_CGAL_TESTS)
+cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON
+cmake --build build-cgal --target conformallab_cgal_tests -j$(nproc)
+
+# Baseline before any change
+ctest --test-dir build-cgal -R '^cgal\.' --output-on-failure
+# Expected: 246 passed, 0 failed
+```
+
+For performance findings, the smoke meshes used by the project are:
+- `cathead.obj` (open, F≈248)
+- `brezel.obj` (genus-1, F≈13824)
+- `brezel2.obj` (genus-2)
+exercised by `code/tests/cgal/test_scalability_smoke.cpp`.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Primary location |
+|----|-----|-------|------------------|
+| B1 | 🔴 | `newton_hyper_ideal` uses full-FD Hessian; the 96–1166× faster block-FD exists but is unused. Inversive-Distance has no fast path at all | `newton_solver.hpp:433`, `:580` |
+| A1 | 🔴 | `assign_*_dof_indices`: three different naming conventions across the 5 functionals | 5 functional headers |
+| B2 | 🟡 | `line_search` discards the gradient at the accepted point → ~1 redundant full gradient eval per Newton iteration (×5 solvers) | `newton_solver.hpp` |
+| B3 | 🟡 | `has_edge_dof` O(E) scan runs every Newton iteration (layout is loop-invariant) | `newton_solver.hpp:264` |
+| A4 | 🟡 | High-level CGAL entry points have inconsistent suffix (`_map` only on one) | `code/include/CGAL/*.h` |
+| A5 | 🟡 | The two circle-packing models return different result types | `Discrete_circle_packing.h`, `Discrete_inversive_distance.h` |
+| A2 | 🟡 | `compute_*_from_mesh`: inconsistent prefix + verb (`lambda0` vs `init`) | 3 functional headers |
+| A3 | 🟡 | `gradient_check` (HyperIdeal) lacks the `_<geom>` suffix the other 4 have | `hyper_ideal_functional.hpp:470` |
+| B4 | 🟡 | SimplicialLDLT symbolic factorization rebuilt every iteration (sparsity pattern is constant) | `newton_solver.hpp:73` |
+| B5 | 🔵 | Dead `SimplicialLDLT solver;` variable + per-call gradient heap allocation | `newton_solver.hpp:244`, `euclidean_functional.hpp:193` |
+
+---
+
+# Part A — API consistency
+
+> Context: the project has two API layers. The **high-level CGAL layer**
+> (`CGAL::discrete_*` + named parameters) intentionally follows CGAL conventions —
+> that is correct and not a finding by itself. The **low-level free-function layer**
+> (`setup_*`, `assign_*`, `*_gradient`) is the one used directly by tests and
+> internal callers, and it is internally inconsistent. `setup_<geom>_maps` IS
+> uniform across all five functionals, which proves the convention is achievable —
+> it simply was not held for the other verbs.
+
+## FINDING-A1 — 🔴 `assign_*_dof_indices`: three conventions for one operation
+
+### Location
+- `euclidean_functional.hpp:107,132`
+- `spherical_functional.hpp:99,123`
+- `hyper_ideal_functional.hpp:107`
+- `cp_euclidean_functional.hpp:140`
+- `inversive_distance_functional.hpp:133`
+
+### Problem
+| Functional | Vertex variant | All variant |
+|---|---|---|
+| Euclidean | `assign_euclidean_vertex_dof_indices` | `assign_euclidean_all_dof_indices` |
+| Spherical | `assign_vertex_dof_indices` ⚠️ no prefix | `assign_all_spherical_dof_indices` ⚠️ infix |
+| HyperIdeal | — | `assign_all_dof_indices` ⚠️ no prefix |
+| CP-Euclidean | `assign_cp_euclidean_face_dof_indices` | — |
+| InversiveDist | `assign_inversive_distance_vertex_dof_indices` | — |
+
+Three patterns: `assign_<geom>_<scope>_dof_indices`, `assign_<scope>_dof_indices`
+(no geometry), and `assign_all_<geom>_dof_indices` (geometry in the **middle**).
+The prefix-less `assign_vertex_dof_indices` (spherical) and `assign_all_dof_indices`
+(hyper-ideal) read as generic but are geometry-specific, which is misleading at
+the call site (e.g. `test_newton_solver.cpp:81` calls `assign_vertex_dof_indices`).
+
+### Fix — DECIDED (2026-05-31)
+Standardize on `assign_<geom>_<scope>_dof_indices` (matches the already-consistent
+`setup_<geom>_maps`). Confirmed renames:
+
+| Old | New |
+|---|---|
+| `assign_vertex_dof_indices` (spherical) | `assign_spherical_vertex_dof_indices` |
+| `assign_all_spherical_dof_indices` | `assign_spherical_all_dof_indices` |
+| `assign_all_dof_indices` (hyper-ideal) | `assign_hyper_ideal_all_dof_indices` |
+| `assign_euclidean_vertex_dof_indices` | unchanged ✓ |
+| `assign_euclidean_all_dof_indices` | unchanged ✓ |
+| `assign_cp_euclidean_face_dof_indices` | unchanged ✓ |
+| `assign_inversive_distance_vertex_dof_indices` | unchanged ✓ |
+
+Keep the old names as `[[deprecated]]` inline wrappers for one release so existing
+call sites (tests, examples) keep compiling, then update all call sites.
+
+### Acceptance criteria
+- All five functionals follow `assign_<geom>_<scope>_dof_indices`.
+- Old names exist as `[[deprecated]]` aliases (or all call sites updated in the same PR).
+- Full CGAL suite still 246/246.
+
+---
+
+## FINDING-A2 — 🟡 `compute_*_from_mesh`: inconsistent prefix and verb
+
+### Location
+- `euclidean_functional.hpp:152` — `compute_euclidean_lambda0_from_mesh`
+- `spherical_functional.hpp:148` — `compute_lambda0_from_mesh` ⚠️ no prefix
+- `inversive_distance_functional.hpp:187` — `compute_inversive_distance_init_from_mesh` ⚠️ `init` not `lambda0`
+
+### Problem
+`compute_lambda0_from_mesh` (spherical) has no geometry prefix and is used directly
+in `test_newton_solver.cpp:80,99`. Inversive-Distance uses the verb `init` instead
+of `lambda0` for the conceptually parallel step.
+
+### Fix — DECIDED (2026-05-31)
+- `compute_lambda0_from_mesh` → `compute_spherical_lambda0_from_mesh` (add prefix).
+- `compute_inversive_distance_init_from_mesh` → **keep `init`**. Rationale: this step
+  initializes `I_e` and `r0`, i.e. genuinely more than just λ₀, so `init` is the
+  honest verb. The distinction (`lambda0` vs `init`) will be documented in
+  `doc/api/extending.md`.
+- `compute_euclidean_lambda0_from_mesh` → unchanged ✓.
+- `[[deprecated]]` alias for the spherical rename.
+
+### Acceptance criteria
+- Spherical compute fn carries the `spherical` prefix.
+- Naming rationale for `init` vs `lambda0` documented in `doc/api/extending.md`.
+
+---
+
+## FINDING-A3 — 🟡 `gradient_check` (HyperIdeal) breaks the `_<geom>` suffix pattern
+
+### Location
+- `euclidean_functional.hpp:324` — `gradient_check_euclidean`
+- `spherical_functional.hpp:367` — `gradient_check_spherical`
+- `cp_euclidean_functional.hpp:331` — `gradient_check_cp_euclidean`
+- `inversive_distance_functional.hpp:346` — `gradient_check_inversive_distance`
+- `hyper_ideal_functional.hpp:470` — `gradient_check` ⚠️ no suffix
+
+### Fix — DECIDED (2026-05-31)
+Rename `gradient_check` → `gradient_check_hyper_ideal` with a `[[deprecated]]` alias.
+The other four (`gradient_check_euclidean/_spherical/_cp_euclidean/_inversive_distance`)
+are unchanged ✓.
+
+### Acceptance criteria
+- All five follow `gradient_check_<geom>`.
+
+---
+
+## FINDING-A4 — 🟡 High-level CGAL entry points: inconsistent suffix
+
+### Location
+`code/include/CGAL/Discrete_conformal_map.h`, `Discrete_circle_packing.h`,
+`Discrete_inversive_distance.h`
+
+### Problem
+```cpp
+CGAL::discrete_conformal_map_euclidean       // no trailing word
+CGAL::discrete_conformal_map_spherical
+CGAL::discrete_conformal_map_hyper_ideal
+CGAL::discrete_circle_packing_euclidean      // no _map
+CGAL::discrete_inversive_distance_map        // ⚠️ trailing _map
+```
+`discrete_inversive_distance_map` ends in `_map`; `discrete_circle_packing_euclidean`
+does not — yet both are circle-packing models.
+
+### Fix — DECIDED (2026-05-31)
+`discrete_inversive_distance_map` → **`discrete_inversive_distance_euclidean`** (drop
+the trailing `_map`, add the geometry word), so it matches
+`discrete_circle_packing_euclidean`. Because this is the **public CGAL API**, treat
+it as a breaking change: add the new name, mark the old `[[deprecated]]`, announce in
+`CHANGELOG.md`.
+
+> ⚠️ Sequencing: A4 touches the **public CGAL surface**. Do this rename only after the
+> G0/G1 license/provenance outcome is known (see CGAL audit) — there is no point
+> stabilizing a public API on a package whose release status is unresolved. A1–A3 are
+> internal and can proceed now.
+
+### Acceptance criteria
+- The two circle-packing entry points share a naming shape
+  (`discrete_*_euclidean`).
+- CHANGELOG documents the rename; deprecated alias provided.
+
+---
+
+## FINDING-A5 — 🟡 The two circle-packing models return different result types
+
+### Location
+- `Discrete_circle_packing.h:100` → returns `Circle_packing_result<FT>`
+- `Discrete_inversive_distance.h:133,146` → returns `Conformal_map_result<FT>`
+
+### Problem
+CP-Euclidean and Inversive-Distance are both circle-packing models, but
+`discrete_circle_packing_euclidean` returns `Circle_packing_result` while
+`discrete_inversive_distance_map` returns `Conformal_map_result`. A user switching
+between the two packers must rewrite their result-handling code, even though the
+semantics (per-element radii + Newton diagnostics) are the same.
+
+### Fix — DECIDED (2026-05-31)
+**Option (a):** both circle-packing entry points return `Circle_packing_result`.
+`discrete_inversive_distance_*` switches from `Conformal_map_result` to
+`Circle_packing_result` (semantically truthful — both produce circle radii). The
+unified-result option (b) is rejected as over-engineered.
+
+> ⚠️ Same sequencing as A4 — public-API change, do after the G0/G1 outcome.
+
+### Acceptance criteria
+- The two packing entry points return `Circle_packing_result`.
+- If a field is renamed (e.g. `u_per_vertex` → `radius_per_*`), document it in CHANGELOG.
+
+---
+
+# Part B — Performance
+
+## FINDING-B1 — 🔴 Fast Hessian paths exist but the solvers don't use them
+
+### Location
+- `newton_solver.hpp:433` — `newton_hyper_ideal` calls `hyper_ideal_hessian_sym(...)`
+  (the **full-FD** O(n·F) version)
+- `hyper_ideal_hessian.hpp:220` — `hyper_ideal_hessian_block_fd_sym(...)` (the fast
+  block-FD version) **exists and is tested** but is never called by the solver
+- `newton_solver.hpp:580-608` — `newton_inversive_distance` builds a **full-FD**
+  Hessian inline (2 gradient evals per DOF), with no fast path at all
+
+### Problem
+**HyperIdeal:** the solver uses the slow full-FD Hessian even though a block-FD
+version with a documented **33× speedup on cathead, ~1166× on brezel** already
+exists (`hyper_ideal_hessian.hpp:130-136`). The fast code is implemented, tested
+(`test_hyper_ideal_hessian.cpp`), and simply not wired into the solver.
+
+```cpp
+// newton_solver.hpp:433 — current (slow):
+auto H  = hyper_ideal_hessian_sym(mesh, x, m, hess_eps);          // full-FD, O(n·F)
+// available (fast, same result up to FD noise):
+auto H  = hyper_ideal_hessian_block_fd_sym(mesh, x, m, hess_eps); // block-FD
+```
+
+**Inversive-Distance:** the inline `build_hessian` lambda runs `2n` full gradient
+evaluations per Hessian (each O(F)), i.e. **O(n·F) per Newton iteration** — quadratic
+in mesh size. No block-FD or analytic path exists yet.
+
+```cpp
+// newton_solver.hpp:585-601 — current:
+for (int j = 0; j < n; ++j) {
+    auto Gp = inversive_distance_gradient(mesh, xp, m);   // O(F)
+    auto Gm = inversive_distance_gradient(mesh, xm, m);   // O(F)  → 2n total per Hessian
+    ...
+}
+```
+
+### Fix
+1. **HyperIdeal (cheap win):** switch line 433 to `hyper_ideal_hessian_block_fd_sym`.
+   Verify the existing convergence tests (`test_newton_solver.cpp` HyperIdeal cases,
+   `test_newton_phase9a.cpp`) still pass within tolerance — block-FD is mathematically
+   equivalent up to FD rounding (locality lemma, documented at `hyper_ideal_hessian.hpp:120-128`).
+2. **Inversive-Distance:** port a block-FD Hessian mirroring the HyperIdeal one
+   (the gradient is also face-decomposable). Track the analytic Glickenstein-2011
+   Hessian separately as already noted in `doc/roadmap/research-track.md`.
+
+### Acceptance criteria
+- `newton_hyper_ideal` uses block-FD; HyperIdeal convergence tests still pass.
+- A timing assertion or smoke test demonstrates the speedup on `brezel.obj`
+  (or at minimum, the change is benchmarked and recorded in `doc/architecture/`).
+- Inversive-Distance has a block-FD path; `test_newton_phase9a.cpp` still passes.
+
+---
+
+## FINDING-B2 — 🟡 line_search discards the gradient at the accepted point
+
+### Location
+`newton_solver.hpp` — `detail::line_search` (lines 140-201) and all 5 solver loops
+(e.g. Euclidean lines 248, 277-280, 287)
+
+### Problem
+Per Newton iteration the gradient over the whole mesh is computed redundantly:
+1. line 248 — gradient for the convergence check
+2. inside `line_search` — gradient at each trial point; the **vector is discarded**,
+   only its norm is kept
+3. next iteration's line 248 — recomputes the gradient at the just-accepted point
+   (already computed in step 2)
+4. line 287 (`G_final`) — recomputes once more after the loop
+
+That is roughly **one redundant full-mesh gradient per iteration** plus one at the end.
+
+### Fix
+Have `line_search` return (via out-param) the gradient vector at the accepted point,
+and feed it into the next iteration's convergence check instead of recomputing. The
+end-of-loop `G_final` can reuse the last accepted gradient too.
+
+> Best done as part of the `newton_core` template refactor (test-coverage audit
+> FINDING-H2) so the fix lands once instead of five times.
+
+### Acceptance criteria
+- Gradient evaluations per iteration drop by ~1 (instrument with a counter in a test).
+- All convergence tests pass unchanged.
+
+---
+
+## FINDING-B3 — 🟡 has_edge_dof scan runs every Newton iteration
+
+### Location
+`newton_solver.hpp:264-268` (inside the `newton_euclidean` iteration loop)
+
+### Problem
+```cpp
+bool has_edge_dof = false;
+for (auto e : mesh.edges())          // O(E), runs EVERY iteration
+    if (m.e_idx[e] >= 0) { has_edge_dof = true; break; }
+```
+The DOF layout (`m.e_idx`) does not change during the solve, so this scan is
+loop-invariant. Over up to 200 iterations the mesh edge set is scanned 200× for no
+reason.
+
+### Fix
+Hoist the scan above the `for (iter...)` loop; compute `has_edge_dof` once.
+
+### Acceptance criteria
+- `has_edge_dof` computed exactly once per `newton_euclidean` call.
+- Euclidean tests pass unchanged.
+
+---
+
+## FINDING-B4 — 🟡 Symbolic factorization rebuilt every iteration
+
+### Location
+`newton_solver.hpp:73` (`detail::solve_with_fallback`)
+
+### Problem
+```cpp
+Eigen::SimplicialLDLT<Eigen::SparseMatrix<double>> ldlt(A);  // analyze + factorize
+```
+A fresh `SimplicialLDLT` is constructed each iteration, which re-runs the symbolic
+analysis (fill-reducing reordering / COLAMD). But the **sparsity pattern of the
+Hessian is constant across iterations** (only the numeric values change). Eigen
+supports `analyzePattern()` once + `factorize()` per iteration, skipping the
+repeated symbolic step.
+
+### Fix
+This needs a structural change: `solve_with_fallback` is stateless, so it cannot
+cache the analysis. Either:
+- thread a persistent solver object through the Newton loop (cleanest with the
+  `newton_core` refactor), calling `analyzePattern` on the first iteration and
+  `factorize` thereafter, or
+- key a cached symbolic factorization on the matrix sparsity pattern.
+
+Keep the SparseQR fallback for the singular-pattern case (the pattern there is
+also constant, so the same caching applies).
+
+### Acceptance criteria
+- Symbolic analysis runs once per solve, not once per iteration.
+- All Newton + fallback tests (incl. the 3 SparseQR tests) pass.
+- Benchmarked on `brezel.obj`; improvement recorded.
+
+---
+
+## FINDING-B5 — 🔵 Dead variable + per-call gradient allocation
+
+### Location
+- `newton_solver.hpp:244` — `Eigen::SimplicialLDLT<...> solver;` declared in
+  `newton_euclidean`, **never used** (the solve goes through `solve_with_fallback`)
+- `euclidean_functional.hpp:193,197` — each `euclidean_gradient` call freshly
+  allocates `std::vector<double> G(n)` and `std::vector<double> h_alpha(nh)`
+
+### Problem
+- The dead `solver` variable is harmless but misleading (suggests reuse that
+  doesn't happen — directly relevant once B4 is addressed).
+- In the FD Hessian (B1) the per-call allocation means `2n × 2` fresh heap
+  allocations per Hessian build.
+
+### Fix
+- Remove the dead `solver` declaration.
+- When addressing B1/B2, pass reusable scratch buffers (`G`, `h_alpha`) into the
+  gradient functions, or provide an overload that writes into a caller-owned buffer.
+
+### Acceptance criteria
+- Dead variable removed (compiles clean with `-Wunused`).
+- (Optional, with B1/B2) gradient functions support buffer reuse; allocation count
+  in the FD Hessian path drops measurably.
+
+---
+
+## Suggested order of work
+
+1. **B1 (HyperIdeal half)** — one-line switch to `hyper_ideal_hessian_block_fd_sym`;
+   biggest win for the smallest change. Verify tests, benchmark.
+2. **B3** — trivial loop hoist.
+3. **A1, A2, A3** — low-level renames with `[[deprecated]]` aliases; do together.
+4. **A4, A5** — high-level CGAL API politur; coordinate with CHANGELOG (breaking).
+5. **newton_core refactor** (test-coverage audit FINDING-H2) — then fold in **B2,
+   B4, B5** in the same pass.
+6. **B1 (Inversive-Distance half)** — port a block-FD Hessian; larger effort.
+
+## What is already good (do not "fix")
+
+- `setup_<geom>_maps` is uniform across all five functionals — the consistency
+  target is proven achievable.
+- The block-FD HyperIdeal Hessian is correct, tested, and well-documented — it
+  just needs to be wired into the solver (B1).
+- The high-level CGAL API correctly uses CGAL named parameters and `Kernel_traits` —
+  idiomatic for a CGAL package.
+- `Conformal_map_result` carries `sparse_qr_fallback_used` — good observability.
diff --git a/doc/reviewer/cgal-submission-readiness-audit-2026-05-31.md b/doc/reviewer/cgal-submission-readiness-audit-2026-05-31.md
new file mode 100644
index 0000000..f011aa7
--- /dev/null
+++ b/doc/reviewer/cgal-submission-readiness-audit-2026-05-31.md
@@ -0,0 +1,473 @@
+# CGAL Submission-Readiness Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Readiness of the `code/include/CGAL/` package for submission to the
+CGAL project (editorial-board review + integration into the CGAL release).
+**Reference:** CGAL Developer Manual — "Adding a new package", CGAL coding
+conventions, and the CGAL package directory structure.
+
+This document is self-contained. A new session can pick up any finding below and
+act on it without prior context.
+
+Status legend: ⛔ Blocker (submission rejected on sight) · 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Companion documents:**
+> - `external-audit-2026-05-30.md` — port-faithfulness bugs
+> - `test-coverage-error-handling-audit-2026-05-31.md` — test gaps + error handling
+> - `api-performance-audit-2026-05-31.md` — API consistency + performance
+> - **this file** — CGAL submission readiness
+>
+> **Bottom line:** the *algorithmic* maturity is strong, but the package is **not
+> submittable as-is**. There are **three** hard blockers — **provenance/porting
+> rights (G0)**, licensing (G1), and directory layout (G2) — plus several
+> CGAL-convention gaps. G0 is a legal precondition that gates everything else:
+> until the right to port the original Varylab/TU-Berlin code is clarified with
+> its authors, no license decision (G1) can be made and no public release or
+> submission should happen. The remaining items are packaging and
+> documentation-format work — substantial but mechanical, no research required.
+
+---
+
+## Verdict at a glance
+
+| # | Sev | Title |
+|---|-----|-------|
+| G0 | ⛔ | **Porting rights unclear** — the original Varylab/TU-Berlin project has *no license* (all rights reserved); the C++ code is a documented *port* (derivative work). Must clarify with the authors whether porting + (re)licensing is permitted **before** any license/release decision |
+| G1 | ⛔ | **License is MIT** — CGAL requires GPLv3+ (algorithmic) or LGPLv3+. Moot until G0 is resolved |
+| G2 | ⛔ | **Directory layout is not CGAL package layout** — no `package_info/`, no `doc/<Pkg>/`, tests/examples not in CGAL harness |
+| G3 | 🔴 | **CGAL is vendored** (`code/deps/CGAL-6.1.1`) — a CGAL package must not bundle CGAL |
+| G4 | 🔴 | **Concept not in a Doxygen block** — `\cgalConcept` is in `//` comments, won't render; no `doc/<Pkg>/Concepts/` file |
+| G5 | 🔴 | **No user manual** — CGAL requires `<Pkg>.txt` (\mainpage) + `PackageDescription.txt` |
+| G6 | 🔴 | **Test suite uses GoogleTest + FetchContent** — CGAL uses its own test harness; external network deps are disallowed |
+| G7 | 🟡 | **Primary template `Default_conformal_map_traits` is undefined** — only `Surface_mesh` works; concept claims `FaceGraph` genericity |
+| G8 | 🟡 | **`.hpp` extension for implementation headers** — CGAL convention is `.h` |
+| G9 | 🟡 | **Single-header monolith risk** — heavy `inline` free functions in headers; CGAL prefers `internal/` split + documented public surface |
+| G10 | 🟡 | **No demo, no benchmark dir** — recommended for a numeric package |
+| G11 | 🔵 | **Naming inconsistencies** carry into the public API (see api-performance-audit A1–A5) |
+| G12 | 🔵 | **Copyright line** — CGAL files carry an `INRIA/GeometryFactory` style header + the CGAL license boilerplate, not a bare MIT line |
+
+---
+
+## G0 — ⛔ Porting rights: the original is unlicensed and this is a derivative work
+
+> **This is the precondition for everything else in this audit (and for the license
+> finding G1). It must be resolved with the original authors before any public
+> release, relicensing, or CGAL submission.**
+>
+> *Disclaimer: the auditor is not a lawyer. This is a practical risk assessment,
+> not legal advice. Confirm with the project owner / institutional legal counsel.*
+
+### Evidence
+The original project (`gitlab.discretization.de:varylab/conformallab.git`,
+mirrored to `git.eulernest.eu`) is the **Varylab / TU-Berlin** discrete-conformal
+codebase (DFG SFB/Transregio "Discretization in Geometry and Dynamics"; author
+circle around Stefan Sechelmann, Boris Springborn).
+
+```
+$ find /Users/tarikmoussa/Desktop/conformallab -maxdepth 2 \
+       \( -iname 'license*' -o -iname 'copying*' \)
+# → (nothing)
+# Java sources carry NO license header; only build.xml + .project exist.
+```
+
+- The original has **no LICENSE file and no per-file license headers** → under
+  default copyright law this means **all rights reserved** by the TU-Berlin/Varylab
+  authors. "Publicly visible on an academic GitLab" is **not** a license grant.
+- `ConformalLabpp` describes itself as a **port**: source comments say
+  *"Ported from de.varylab.discreteconformal.functional.EuclideanCyclicFunctional"*,
+  and the test suite asserts "Java golden-oracle parity". That makes the C++ code a
+  **derivative work of the original source code**, not merely an independent
+  implementation of the published papers.
+
+### Why it blocks
+A derivative work of all-rights-reserved code **cannot be licensed by the porter
+alone** — neither as MIT (the current state) nor as GPL (the CGAL requirement) —
+without permission from the original copyright holders. The existing MIT header on
+`ConformalLabpp` is therefore on shaky ground today, independent of CGAL.
+
+Crucial distinction:
+
+| What was actually reproduced | Legal status |
+|---|---|
+| The **published algorithms** (Springborn 2020, Bobenko-Pinkall-Springborn 2010, Luo 2004) | Free to reimplement — mathematical methods are not copyrightable, only their concrete code expression |
+| The **source code** of the Varylab Java project, line-by-line | Derivative work → requires the authors' permission to port and (re)license |
+
+The "Ported from …" comments currently document a code derivation in writing, which
+is the principal risk.
+
+### Action (owner-level, before any code/license change)
+1. **Determine provenance honestly:** is `ConformalLabpp` a clean-room
+   reimplementation *from the papers*, or a translation *of the Varylab code*?
+   The current comments assert the latter.
+2. **Contact the original authors** (Sechelmann / Springborn, TU Berlin / Varylab)
+   to either (a) obtain written permission to port and relicense (ideally under
+   GPLv3+ so CGAL submission stays open), or (b) confirm the original is intended to
+   be freely reusable and get that in writing / as an added LICENSE upstream.
+3. **Pause public releases and CGAL submission** until 1–2 are settled.
+4. If permission cannot be obtained, the only clean path is a genuine clean-room
+   reimplementation from the published papers, with the "Ported from …" provenance
+   comments removed and replaced by paper citations.
+
+### Done when
+- Written clarity exists on the right to port + (re)license the original code;
+  the provenance comments in the source match that reality.
+
+---
+
+## G1 — ⛔ License: MIT is incompatible with CGAL submission
+
+> Blocked by **G0** — do not act on G1 until porting/relicensing rights are clear.
+
+### Evidence
+All 41 headers carry:
+```cpp
+// SPDX-License-Identifier: MIT
+```
+(`grep -rh "SPDX-License-Identifier" code/include/` → 41× MIT, 0× anything else.)
+
+### Why it blocks
+CGAL is dual-licensed: the **algorithmic** packages are **GPLv3+**, the foundational
+ones **LGPLv3+**, with a commercial license sold by GeometryFactory. A new package
+must be contributed under the **same dual GPL/LGPL scheme**, with copyright assigned
+or licensed appropriately. A package licensed MIT cannot be merged into the CGAL
+tree — the editorial board will reject it at intake.
+
+### Action
+This is a **licensing/legal decision for the project owner**, not a code change:
+1. Decide whether to relicense the contributed package as GPLv3+ (the normal choice
+   for a new algorithmic CGAL package).
+2. Replace every header's `SPDX-License-Identifier: MIT` with the CGAL license
+   header boilerplate (see `Installation/LICENSE*` in the CGAL tree for the exact
+   text and the `$URL$ $Id$ SPDX-License-Identifier: GPL-3.0-or-later` form).
+3. Keep a separate MIT-licensed standalone build if a permissive standalone
+   distribution is also desired (dual-distribution is possible but must be explicit).
+
+> ⚠️ Do not auto-rewrite license headers without the owner's explicit decision —
+> relicensing is irreversible for contributed copies and may involve other authors.
+
+### Done when
+- Owner has chosen the license; headers carry the CGAL-conformant boilerplate.
+
+---
+
+## G2 — ⛔ Directory layout is not a CGAL package
+
+### Evidence
+Current layout:
+```
+code/include/CGAL/...        ← headers (good location)
+code/examples/*.cpp          ← flat, not per-package
+code/tests/cgal/*.cpp        ← GoogleTest, not CGAL harness
+code/deps/CGAL-6.1.1         ← vendored CGAL (see G3)
+(no package_info/ anywhere)
+(no doc/<Pkg>/ with PackageDescription.txt)
+```
+
+CGAL expects a package rooted at a top-level package directory mirroring the CGAL
+source tree:
+```
+Discrete_conformal_map/
+  include/CGAL/Discrete_conformal_map.h
+  include/CGAL/Conformal_map/...
+  doc/Discrete_conformal_map/
+      Discrete_conformal_map.txt          (user manual, \mainpage)
+      PackageDescription.txt              (\package_listing entries)
+      Concepts/ConformalMapTraits.h       (the concept, doxygen-only)
+      examples.txt, fig/
+  examples/Discrete_conformal_map/*.cpp   (+ CMakeLists using CGAL macros)
+  test/Discrete_conformal_map/*.cpp       (CGAL test harness)
+  benchmark/Discrete_conformal_map/       (optional but recommended)
+  package_info/Discrete_conformal_map/
+      copyright  description.txt  dependencies  license.txt  maintainer
+```
+
+### Action
+Restructure into the CGAL package layout. This is mechanical but touches every file
+location and the build. Recommended approach:
+1. Create the `package_info/Discrete_conformal_map/` metadata files first (small).
+2. Move headers under the package's `include/CGAL/` (already close).
+3. Re-home examples → `examples/Discrete_conformal_map/`, tests → `test/Discrete_conformal_map/`.
+4. Build the `doc/Discrete_conformal_map/` tree (G5).
+
+### Done when
+- Layout matches an existing CGAL package (use e.g. `Surface_mesh_parameterization`
+  or `Heat_method_3` as a template — both are close in spirit).
+
+---
+
+## G3 — 🔴 CGAL is vendored inside the repo
+
+### Evidence
+```
+code/deps/CGAL-6.1.1     ← full CGAL 6.1.1 source tree bundled
+```
+
+### Why it matters
+A package being submitted *into* CGAL must build against the surrounding CGAL tree,
+not bundle its own copy. The vendored `CGAL-6.1.1` (and the standalone build wiring
+around it) is appropriate for the current standalone distribution, but must be
+removed from the submitted package — the package's `dependencies` file declares CGAL
+package dependencies instead.
+
+### Action
+- For the CGAL-submission branch: drop `code/deps/CGAL-*`; rely on the host CGAL tree.
+- Keep the vendored copy only on the standalone-distribution branch.
+- List actual dependencies (`Surface_mesh`, `BGL`, `Property_map`, `Solver_interface`,
+  `Number_types`, plus the external `Eigen`) in `package_info/.../dependencies`.
+
+### Done when
+- The submission branch contains no bundled CGAL; it builds inside a CGAL checkout.
+
+---
+
+## G4 — 🔴 The concept is not a documented CGAL concept
+
+### Evidence
+`code/include/CGAL/Conformal_map_traits.h:36-76` declares the concept with
+`\cgalConcept`, `\concept ConformalMapTraits`, `\cgalHasModelsBegin/End` — but the
+whole block uses **plain `//` comments**, not a Doxygen `/*! ... */` block:
+
+```cpp
+// ════════════════════════════════════════════════════════════════════════════
+// \cgalConcept
+//
+// \concept ConformalMapTraits
+...
+```
+
+Doxygen only parses `/*! */` (or `///`) blocks, so none of this renders. There is
+also no `doc/<Pkg>/Concepts/ConformalMapTraits.h` — in CGAL, concepts live as
+doxygen-only header files under the package `doc/.../Concepts/` directory, separate
+from the model.
+
+### Action
+1. Create `doc/Discrete_conformal_map/Concepts/ConformalMapTraits.h` containing the
+   concept as a `/*! \cgalConcept ... */`-documented (empty) class, following the
+   CGAL concept-file pattern.
+2. Reference it via `\cgalHasModels` from `Default_conformal_map_traits`.
+3. Convert the in-source `//` concept block to either a proper `/*! */` block or
+   remove it in favor of the doc/Concepts file.
+
+### Done when
+- `ConformalMapTraits` appears in the generated reference manual under
+  `PkgConformalMapConcepts` with its model linked.
+
+---
+
+## G5 — 🔴 No CGAL user manual / PackageDescription
+
+### Evidence
+`find . -name PackageDescription.txt -o -path '*doc*' -name '*.txt'` → none (outside `deps/`).
+The project has rich Markdown docs under `doc/` (api/, math/, architecture/), but
+CGAL requires its own doxygen-driven manual files:
+- `doc/<Pkg>/<Pkg>.txt` — the user manual with `\mainpage`-style narrative,
+  `\cgalExample` references, figures.
+- `doc/<Pkg>/PackageDescription.txt` — the `\cgalPkgDescriptionBegin` listing
+  (authors, intro, license, dependencies, demo/example links) that populates the
+  CGAL "Packages" overview.
+
+### Action
+- Author `Discrete_conformal_map.txt` (user manual). Much of the content can be
+  adapted from the existing `doc/api/pipeline.md` and `doc/math/*.md`.
+- Author `PackageDescription.txt` with the standard CGAL macros.
+- Wire both into a package `doc/Doxyfile.in` consistent with CGAL's doc build.
+
+### Done when
+- `cgal_create_package` doc build produces a reference + user manual without warnings.
+
+---
+
+## G6 — 🔴 Test suite is GoogleTest + FetchContent
+
+### Evidence
+`code/tests/cgal/CMakeLists.txt`:
+```cmake
+target_link_libraries(conformallab_cgal_tests PRIVATE GTest::gtest_main)
+gtest_discover_tests(conformallab_cgal_tests ...)
+```
+(plus FetchContent for GoogleTest elsewhere in the build).
+
+### Why it matters
+CGAL's test infrastructure uses its own harness (`create_single_source_cgal_program`,
+the `test/` programs return 0/non-0, driven by the CGAL testsuite scripts). External
+network dependencies (FetchContent pulling GoogleTest) are not allowed in the CGAL
+tree, and the GoogleTest dependency would need vendoring or removal.
+
+### Action
+This is the largest mechanical task. Options:
+- **(a)** Port the assertions to CGAL's plain-`assert` + `return EXIT_FAILURE` test
+  style, one program per test file under `test/Discrete_conformal_map/`. This is the
+  canonical CGAL approach and removes the GoogleTest dependency entirely.
+- **(b)** Keep GoogleTest for the standalone branch; maintain a parallel CGAL-style
+  `test/` tree for the submission branch.
+
+The 272 existing tests are an asset — the assertions translate directly; only the
+framework scaffolding changes.
+
+### Done when
+- `test/Discrete_conformal_map/` runs under the CGAL testsuite with no GoogleTest.
+
+---
+
+## G7 — 🟡 Genericity claimed but not delivered
+
+### Evidence
+`Conformal_map_traits.h:80-92`: the primary template
+`Default_conformal_map_traits<TriangleMesh, Kernel_>` is **declared but undefined**;
+only the `Surface_mesh` partial specialization (`:113`) is implemented. The concept
+docstring (`:13-21`) advertises *"can run on any CGAL halfedge mesh — Surface_mesh,
+Polyhedron_3, OpenMesh-adapter, pmp — without changes"*, and the API takes a
+`TriangleMesh` template parameter, implying BGL-generic support.
+
+### Why it matters
+CGAL reviewers scrutinize generic-programming claims. Shipping a `TriangleMesh`
+template that compiles only for `Surface_mesh` is a documentation/implementation
+mismatch: a user passing a `Polyhedron_3` gets a hard template error against an
+undefined primary template, not a clean diagnostic.
+
+### Action
+Either:
+- **(a)** Implement a generic `FaceGraph`/`HalfedgeGraph` path using `boost::graph_traits`
+  + dynamic property maps (CGAL's `dynamic_vertex_property_t`), removing the
+  `Surface_mesh`-only restriction — this is the "Phase 8a.2" already on the roadmap; or
+- **(b)** Until then, narrow the documented contract: state explicitly that only
+  `Surface_mesh` is supported, and `static_assert` a friendly message in the primary
+  template instead of leaving it undefined.
+
+### Done when
+- The advertised mesh-type support matches what compiles; unsupported types yield a
+  `static_assert` message, not a raw template error.
+
+---
+
+## G8 — 🟡 Header extension `.hpp` vs CGAL `.h`
+
+### Evidence
+The implementation headers use `.hpp` (`euclidean_functional.hpp`, `newton_solver.hpp`,
+…), while the CGAL-facing headers correctly use `.h` (`Discrete_conformal_map.h`).
+CGAL's convention is `.h` for all headers.
+
+### Action
+Rename the implementation headers to `.h` when they move under the package
+`include/CGAL/Conformal_map/internal/` tree (G9), updating `#include` directives.
+Low-risk, mechanical; do it as part of the G2 restructure.
+
+### Done when
+- All package headers use `.h`.
+
+---
+
+## G9 — 🟡 Public/internal header surface is undivided
+
+### Evidence
+The 26 `code/include/*.hpp` headers are all effectively public (flat in `include/`),
+mixing the user-facing CGAL entry points with low-level functional/geometry/solver
+internals (`hyper_ideal_geometry.hpp`, `projective_math.hpp`, `clausen.hpp`, …).
+
+### Why it matters
+CGAL packages keep a small documented public API and move implementation into
+`include/CGAL/<Pkg>/internal/`. Exposing every helper as a top-level header makes
+the supported API surface ambiguous and the package harder to evolve without
+breaking users.
+
+### Action
+- Designate the public surface (the `CGAL/Discrete_*` entry points, the traits, the
+  layout/result types).
+- Move everything else under `include/CGAL/Conformal_map/internal/`.
+- Mark internal headers `\internal` for Doxygen (the parameters header already does
+  this correctly — `Conformal_map/internal/parameters.h` is the right pattern).
+
+### Done when
+- Only the intended public headers are documented; the rest are under `internal/`.
+
+---
+
+## G10 — 🟡 No demo / benchmark directory
+
+### Evidence
+No `demo/` and no `benchmark/` directory. For a numerical package, CGAL reviewers
+appreciate (and for some packages expect) a benchmark establishing performance
+characteristics, and a small demo is a strong plus.
+
+### Action
+- Add `benchmark/Discrete_conformal_map/` measuring solve time / iteration counts on
+  the existing smoke meshes (cathead/brezel/brezel2) — this also dovetails with the
+  performance findings in `api-performance-audit-2026-05-31.md` (B1/B4).
+- A demo is optional; skip if time-constrained.
+
+### Done when
+- A benchmark program exists and its numbers are referenced in the user manual.
+
+---
+
+## G11 — 🔵 Public-API naming inconsistencies (cross-ref)
+
+The naming inconsistencies documented in `api-performance-audit-2026-05-31.md`
+(findings A1–A5: `assign_*`, `compute_*`, `gradient_check`, the `_map` suffix, and
+the split result types) become **public-API-stability concerns** once the package is
+in CGAL, because CGAL APIs are expected to be stable across releases. Resolve A1–A5
+**before** submission, not after — renaming a shipped CGAL API requires a deprecation
+cycle.
+
+### Done when
+- A1–A5 resolved; the public names are the ones intended to be permanent.
+
+---
+
+## G12 — 🔵 File header boilerplate
+
+### Evidence
+Headers begin with `// Copyright (c) 2024-2026 Tarik Moussa.` + a bare SPDX line.
+CGAL files use a standardized header including the `$URL$`/`$Id$` SVN/git keywords,
+the SPDX line in CGAL's form, and the copyright holder convention used in the tree.
+
+### Action
+Adopt the CGAL file-header template (tied to the G1 license decision). Mechanical
+once G1 is settled.
+
+### Done when
+- Headers match the CGAL file-header template.
+
+---
+
+## What is already strong (genuine assets for submission)
+
+- **Named-parameter API** is idiomatic: `CGAL::parameters::gradient_tolerance(...)
+  .max_iterations(...)`, with the tag machinery correctly placed in
+  `Conformal_map/internal/parameters.h` and marked `\internal`. This is the hard part
+  done right.
+- **Doxygen group hierarchy** (`PkgConformalMap` / `Ref` / `Concepts` /
+  `NamedParameters`) is set up correctly in `doxygen_groups.h`.
+- **The `\internal` discipline** on the parameters header shows the author knows the
+  public/internal distinction — it just needs to be applied to the other helpers (G9).
+- **Result types carry observability** (`sparse_qr_fallback_used`, iteration counts).
+- **Algorithmic breadth + validation**: five DCE models with Java golden-oracle
+  parity and FD-gradient checks — a strong scientific basis, which is ultimately what
+  the editorial board cares most about.
+- **Traits-based design intent** is correct CGAL architecture; it only needs the
+  genericity actually implemented (G7) and the concept properly documented (G4).
+
+---
+
+## Suggested order of work (submission track)
+
+0. **G0 (porting rights)** — owner-level legal precondition; contact the
+   Varylab/TU-Berlin authors. **Nothing below should ship publicly until this is
+   resolved.**
+1. **G1 (license decision)** — follows directly from G0; pick GPLv3+ if submission stays the goal.
+2. **G2 + G3 + G8 (restructure)** — do the layout move and header rename together;
+   drop vendored CGAL on the submission branch.
+3. **G9 (public/internal split)** — naturally part of the restructure.
+4. **G11 / A1–A5 (lock the public names)** — before any docs are written against them.
+   *(A1–A3 are internal-API renames and are safe to do independently of G0; A4–A5
+   touch the public CGAL surface and should wait for the G0/G1 outcome.)*
+5. **G4 + G5 (concept file + user manual + PackageDescription)** — the doc deliverables.
+6. **G6 (CGAL test harness)** — port the 272 tests off GoogleTest.
+7. **G7 (deliver or narrow genericity)**.
+8. **G10 (benchmark)** + **G12 (headers)** — polish.
+
+> Realistic framing for the owner: the **science is submission-grade**; the gap is
+> **packaging + licensing + doc-format**. None of items G2–G12 require new research,
+> but collectively they are a significant, mostly-mechanical effort. G1 is a decision,
+> not work.
diff --git a/doc/reviewer/dependency-license-audit-2026-05-31.md b/doc/reviewer/dependency-license-audit-2026-05-31.md
new file mode 100644
index 0000000..42a2458
--- /dev/null
+++ b/doc/reviewer/dependency-license-audit-2026-05-31.md
@@ -0,0 +1,167 @@
+# Dependency & License-Compatibility Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Vendored/auto-fetched dependencies, their license compatibility, and the
+provenance/license of bundled **data assets** (test meshes).
+**Focus:** Is the dependency + data licensing coherent — especially in light of the
+unresolved provenance/license blocker (CGAL audit **G0/G1**)?
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Good news up front:** a `code/deps/THIRD-PARTY-LICENSES.md` already exists and is
+> a genuinely good per-dependency compatibility matrix (CGAL, Eigen, libigl, GLFW,
+> nlohmann/json). This audit does **not** redo that work. It flags two things that
+> matrix cannot see: (D1) it is built on the MIT premise that G0 undermines, and
+> (D2) the bundled **test meshes have no provenance or license at all**.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| D1 | 🔴 | The dependency-license matrix is predicated on "conformallab++ is MIT" — a premise CGAL-audit G0 shows is unfounded; the whole compatibility conclusion is conditional on the unresolved license decision | `code/deps/THIRD-PARTY-LICENSES.md` |
+| D2 | 🔴 | Bundled test meshes (`cathead.obj`, `brezel*.obj`, torus OFFs) have **no provenance and no license** — likely third-party / Varylab-origin, redistributed without attribution | `code/data/` |
+| D3 | 🟡 | No per-dependency license *files* under most vendored trees (only GLFW ships one); the matrix is the only record | `code/deps/*/` |
+| D4 | 🔵 | Vendored-tarball integrity is asserted ("bit-for-bit identical") but not checksum-verified in-repo | `code/deps/tarballs/` |
+
+---
+
+## D1 — 🔴 License matrix is conditional on the unresolved MIT premise
+
+### Evidence
+`code/deps/THIRD-PARTY-LICENSES.md` opens its analysis with:
+> *"## conformallab++ itself … **MIT** … Every C++ source file carries
+> `SPDX-License-Identifier: MIT`"*
+
+and every dependency row evaluates "**Compatibility with MIT distribution**".
+
+### Problem
+The matrix's central column — and therefore its conclusion that everything is
+distributable — assumes conformallab++ *is* MIT-licensed and *may* be distributed as
+MIT. CGAL-audit **G0** establishes that this premise is unfounded: the code is a
+documented port (derivative work) of the unlicensed Varylab/TU-Berlin project, so the
+MIT grant itself is on shaky ground. Two consequences cascade:
+
+1. If porting rights are **not** granted, there is no valid MIT (or any) license to
+   be "compatible with" — the matrix evaluates compatibility against a license the
+   project may not be entitled to use.
+2. If the project relicenses to **GPLv3+** for CGAL submission (G1), the entire
+   "compatible with MIT distribution" analysis must be **redone against GPLv3+**
+   (e.g. the CGAL LGPL/GPL split, Eigen's MPL-2.0, libigl's MPL-2.0 are all
+   GPL-compatible — but that needs stating, not assuming).
+
+### Fix
+- Resolve G0/G1 first (owner-level).
+- Then re-run the matrix against the *actual* outbound license. Add a column
+  "compatibility with GPLv3+ distribution" if the CGAL path is taken.
+- Until resolved, annotate `THIRD-PARTY-LICENSES.md` with a banner that its
+  conclusions are conditional on the pending G0/G1 decision.
+
+### Acceptance criteria
+- The matrix's outbound-license assumption matches the resolved G0/G1 outcome and is
+  re-evaluated against it.
+
+---
+
+## D2 — 🔴 Bundled test meshes have no provenance or license
+
+### Evidence
+```
+code/data/obj:  brezel.obj  brezel2.obj  cathead.obj  tetraflat.obj
+code/data/off:  simple_cupe.off  torus_4x4.off  torus_8x8.off  torus_hex_6x6.off  torus_skewed_4x4.off
+```
+`find code/data -iname '*readme*' -o -iname '*licen*' -o -iname '*source*'` → **nothing.**
+
+### Problem
+These meshes are committed and redistributed with the project, used by the smoke and
+parity tests (`test_scalability_smoke.cpp`, `test_geometry_utils.cpp` references
+`brezel2.obj`, etc.). But:
+
+- `cathead.obj` is a **well-known third-party mesh** that circulates in graphics
+  courses/datasets — it is almost certainly not original to this project and carries
+  whoever's terms.
+- `brezel.obj` / `brezel2.obj` ("Brezel" = pretzel; genus-1/genus-2) are the exact
+  example surfaces used in the **Varylab/TU-Berlin** discrete-conformal work — i.e.
+  likely the *same* upstream as the G0 code-provenance problem.
+
+Redistributing third-party data assets without attribution or a license is the same
+class of issue as the code port (G0), and CGAL submission would flag it: CGAL example
+data must have clear redistribution rights.
+
+### Fix
+- Establish each mesh's origin and license. For `cathead.obj`, identify the standard
+  source and its terms. For the `brezel*` meshes, this is part of the **same
+  conversation with the Varylab/TU-Berlin authors** as G0.
+- Add `code/data/PROVENANCE.md` listing each file: source, author, license, URL.
+- Replace any mesh whose redistribution rights cannot be confirmed with a
+  cleanly-licensed or self-generated equivalent (the torus OFFs look procedurally
+  generated — confirm and document that, which would make them safe).
+
+### Acceptance criteria
+- Every file under `code/data/` has documented provenance + redistribution rights;
+  unconfirmed assets are replaced.
+
+---
+
+## D3 — 🟡 Most vendored trees ship no license file
+
+### Evidence
+```
+eigen-3.4.0:  NONE FOUND        CGAL-6.1.1: NONE FOUND
+libigl-2.6.0: NONE FOUND        glfw-3.4:   LICENSE.md  ✓
+```
+Only GLFW retains its upstream license file; the others rely solely on the central
+`THIRD-PARTY-LICENSES.md`.
+
+### Problem
+When vendoring source trees, the upstream LICENSE/COPYING file should travel with the
+code (it is usually a license *requirement* — MPL-2.0 and LGPL both require preserving
+license notices). A central summary is good practice but does not substitute for the
+upstream notice files inside each tree.
+
+### Fix
+Restore each upstream license file into its vendored tree (`eigen-3.4.0/COPYING.*`,
+`CGAL-6.1.1/LICENSE*`, `libigl-2.6.0/LICENSE*`). They were likely stripped during
+trimming of the vendored copies.
+
+### Acceptance criteria
+- Each vendored dependency tree contains its upstream license notice file.
+
+---
+
+## D4 — 🔵 Vendored tarball integrity not checksum-verified
+
+### Evidence
+`THIRD-PARTY-LICENSES.md` states the cached tarballs are "bit-for-bit identical to the
+upstream releases", but no checksum manifest is committed.
+
+### Problem
+The reproducibility claim (the stated rationale for vendoring) rests on an unverified
+assertion. A corrupted or substituted tarball would not be detected.
+
+### Fix
+Commit a `code/deps/tarballs/SHA256SUMS` and verify it in the extraction step of the
+CMake/deps logic.
+
+---
+
+## What is already good
+
+- `THIRD-PARTY-LICENSES.md` is a thorough, honest per-dependency matrix with real
+  compatibility reasoning (the CGAL LGPL/GPL split, Eigen's NonMPL2 gating, the
+  viewer-only scope of libigl/GLFW) — excellent practice, just built on a premise
+  (D1) that G0 destabilizes.
+- The dependency choices themselves are clean: Eigen (MPL-2.0), libigl (MPL-2.0),
+  GLFW (zlib), nlohmann/json (MIT) are all permissive; only CGAL carries copyleft, and
+  its header-only LGPL consumption is correctly reasoned.
+- Vendoring at fixed versions for build reproducibility is a defensible choice and is
+  documented.
+
+## Suggested order
+1. **D2** (data provenance) — couple with the G0 conversation; CGAL-blocking and the
+   most clearly missing piece.
+2. **D1** (re-base the matrix on the resolved license) — after G0/G1.
+3. **D3** (restore upstream license files) — quick, and likely a license requirement.
+4. **D4** (checksum manifest) — polish.
diff --git a/doc/reviewer/input-validation-audit-2026-05-31.md b/doc/reviewer/input-validation-audit-2026-05-31.md
new file mode 100644
index 0000000..e3d63a7
--- /dev/null
+++ b/doc/reviewer/input-validation-audit-2026-05-31.md
@@ -0,0 +1,197 @@
+# Input-Validation & Malformed-Input Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Robustness of the library's input boundaries — mesh I/O (OFF/OBJ/PLY) and
+result (de)serialization (JSON/XML) — against malformed, adversarial, or
+out-of-domain input.
+**Focus:** What happens with *bad* input. Distinct from the error-handling audit,
+which covered *internal* error propagation and the deliberate `throw` paths.
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Threat model:** this is a scientific library, not a network service, so the bar
+> is "fail cleanly and diagnosably", not "resist attackers". But meshes and result
+> files routinely come from other tools, other people, and older versions of this
+> code — so malformed input is a *when*, not an *if*.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| V1 | 🟡 | JSON deserialization has no error handling — nlohmann exceptions leak the abstraction, not the library's `runtime_error` | `serialization.hpp:96-110` |
+| V2 | 🟡 | XML parser uses unchecked `std::stoi`/`std::stod` on attributes → uncaught `std::invalid_argument` on garbage | `serialization.hpp:258-261` |
+| V3 | 🟡 | No validation of vertex coordinate values on load — NaN/Inf coordinates flow silently into the solver | `mesh_io.hpp:56-66` |
+| V4 | 🟡 | JSON loader accesses nested keys (`j["solver"]["converged"]`) without `contains` checks → throws `type_error`/creates nulls on schema drift | `serialization.hpp:104-108` |
+| V5 | 🔵 | Hand-rolled XML parser assumes one element per line and no escaping — silently mis-reads valid-but-reformatted XML | `serialization.hpp:248-270` |
+| V6 | 🔵 | No upper bound / sanity check on DOF-vector length vs mesh size when loading | `serialization.hpp` |
+
+---
+
+## V1 — 🟡 JSON deserialization leaks nlohmann exceptions
+
+### Evidence
+`serialization.hpp:96-108`:
+```cpp
+std::ifstream ifs(path);
+if (!ifs) throw std::runtime_error("Cannot open: " + path);
+json j; ifs >> j;                       // ← malformed JSON → nlohmann::parse_error
+...
+res->converged = j["solver"]["converged"].get<bool>();   // ← wrong type → type_error
+```
+
+### Problem
+The "file missing" case is handled with the library's own `std::runtime_error`
+(consistent with `mesh_io.hpp`). But the moment the file *exists and is malformed*,
+`ifs >> j` throws `nlohmann::json::parse_error` and the typed accessors throw
+`nlohmann::json::type_error` — neither is the library's documented error type, and
+neither carries the file path. A caller writing `catch (const std::runtime_error&)`
+(the pattern the examples use) will **miss** these. (`nlohmann` exceptions derive from
+`std::exception`, not `std::runtime_error`.)
+
+### Fix
+Wrap the parse + extraction in `try { ... } catch (const json::exception& e)` and
+rethrow as `std::runtime_error("conformallab: malformed JSON in " + path + ": " + e.what())`,
+matching the `mesh_io.hpp` boundary convention.
+
+### Acceptance criteria
+- Loading a truncated/garbage JSON throws `std::runtime_error` with the path.
+- A negative test (`EXPECT_THROW(..., std::runtime_error)`) covers it.
+
+---
+
+## V2 — 🟡 XML parser: unchecked stoi/stod on attributes
+
+### Evidence
+`serialization.hpp:258-261`:
+```cpp
+res->iterations    = std::stoi(detail_xml::xml_get_attr(line, "iterations"));
+res->grad_inf_norm = std::stod(detail_xml::xml_get_attr(line, "grad_inf_norm"));
+```
+
+### Problem
+If the attribute is missing or non-numeric (`xml_get_attr` returns `""` or garbage),
+`std::stoi("")` throws `std::invalid_argument` and out-of-range values throw
+`std::out_of_range` — both uncaught, both not the library's `runtime_error`, neither
+carrying the path. Same abstraction leak as V1, different exception family.
+
+### Fix
+Parse defensively: check the attribute is non-empty and numeric, or wrap in
+try/catch and rethrow as `std::runtime_error` with context (path + attribute name).
+
+### Acceptance criteria
+- An XML file with a non-numeric `iterations` attribute throws `std::runtime_error`,
+  not `std::invalid_argument`.
+
+---
+
+## V3 — 🟡 No validation of vertex coordinates on load
+
+### Evidence
+`mesh_io.hpp:56-66` — `load_mesh` checks read success and `is_triangle_mesh`, but
+does **not** inspect the vertex coordinate values.
+
+### Problem
+A mesh file containing `nan`/`inf` coordinates (common from a crashed upstream tool,
+or `1e308`-style overflow) reads in cleanly. The NaN then propagates: edge lengths
+→ `lambda0` → gradient → Hessian → the Newton solver, where it silently poisons the
+result (`converged` may even read `true` if `NaN < tol` evaluates falsely in a way
+that exits the loop). This is the worst kind of failure: silent, late, and
+hard to trace back to the input.
+
+### Fix
+After `read_mesh`, scan vertex coordinates for finiteness
+(`std::isfinite`) and throw `std::runtime_error("conformallab: non-finite vertex
+coordinate in " + filename)` on the first offender. O(V), negligible cost at the I/O
+boundary — the same philosophy as the existing `is_triangle_mesh` guard.
+
+### Acceptance criteria
+- Loading a mesh with a NaN/Inf coordinate throws `std::runtime_error`.
+- Covered by a negative test.
+
+---
+
+## V4 — 🟡 JSON loader assumes schema without checking
+
+### Evidence
+`serialization.hpp:104-108` reads `j["solver"]["converged"]`, `["iterations"]`,
+`["grad_inf_norm"]` and `j.at("dof_vector")` — only `geometry` is guarded with
+`j.contains(...)` (`:99`).
+
+### Problem
+`operator[]` on a missing key in nlohmann **inserts a null** (for non-const json) or
+throws; `.get<bool>()` on null throws `type_error`. So a result file written by a
+*future or older* schema version fails with an opaque nlohmann error rather than a
+clear "missing field X" message. (`dof_vector` correctly uses `.at()`, which throws a
+clear `out_of_range` — but still not the library's type.)
+
+### Fix
+Validate the expected keys up front (or use `.at()` uniformly + the V1 try/catch),
+producing a single `std::runtime_error("conformallab: result JSON missing field
+'solver.converged'")`-style message.
+
+### Acceptance criteria
+- A JSON missing `solver.iterations` yields a `runtime_error` naming the field.
+
+---
+
+## V5 — 🔵 Hand-rolled XML parser is format-fragile
+
+### Evidence
+`serialization.hpp:248-270` parses line-by-line with `line.find("<Solver")` etc. and
+assumes each element (and the `<DOFVector>…</DOFVector>` text) fits patterns on one
+line.
+
+### Problem
+This is not an XML parser — it is a line-pattern matcher. A semantically identical
+file that pretty-prints elements across multiple lines, or adds an XML declaration /
+namespace / attribute reordering, will be **silently mis-read** (fields default to
+zero/empty) rather than rejected. Round-trips written by this same code work; nothing
+else is guaranteed.
+
+### Fix
+Either (a) document the XML format as a strict internal-only subset (and reject input
+that doesn't match, rather than mis-reading it), or (b) if interop matters, use a real
+XML parser. Given JSON is the primary format, (a) is the pragmatic choice — but the
+"silently mis-read" behavior must become "explicitly reject".
+
+### Acceptance criteria
+- Reformatted-but-valid XML is either parsed correctly or rejected with an error —
+  never silently mis-read into zeros.
+
+---
+
+## V6 — 🔵 No DOF-vector vs mesh sanity check
+
+### Evidence
+`load_result_json` returns `x = j.at("dof_vector")` with no check that `x.size()`
+matches the DOF count of the mesh it will be applied to.
+
+### Problem
+A result file from a *different* mesh loads happily; the size mismatch only surfaces
+later (out-of-bounds or wrong-answer) when `x` is indexed against the new mesh.
+
+### Fix
+Where the loaded `x` is paired with a mesh, assert/throw on a size mismatch with a
+clear message. (May belong at the call site rather than the loader.)
+
+---
+
+## What is already good
+
+- The **file-missing** path is handled correctly and consistently
+  (`runtime_error` + path) in both `mesh_io.hpp` and `serialization.hpp`.
+- `load_mesh` already enforces the triangle-mesh precondition at the boundary — the
+  right place and the right philosophy; V3 just extends it to coordinate finiteness.
+- `dof_vector` uses `.at()` (throwing) rather than `operator[]` — partial good
+  practice that V4 asks to make uniform.
+- JSON (nlohmann) is a robust, well-tested parser — the gap is only the missing
+  try/catch *around* it (V1), not the parser itself.
+
+## Suggested order
+1. **V3** (NaN/Inf coordinate guard) — highest impact, prevents silent solver poisoning.
+2. **V1 + V4** (JSON error handling + schema checks) — do together.
+3. **V2** (XML stoi/stod) — same pattern as V1.
+4. **V5 + V6** (XML strictness, size check) — polish.
diff --git a/doc/reviewer/math-derivation-citation-audit-2026-05-31.md b/doc/reviewer/math-derivation-citation-audit-2026-05-31.md
new file mode 100644
index 0000000..2db1ba5
--- /dev/null
+++ b/doc/reviewer/math-derivation-citation-audit-2026-05-31.md
@@ -0,0 +1,192 @@
+# Math-Derivation & Citation Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Correctness of the mathematical derivations in `doc/math/` and the
+integrity/consistency of the literature citations in code comments and docs.
+**Focus:** Are the derivations sound and are the citations accurate, complete, and
+consistent? Distinct from `java-port-audit.md` (which checks code vs. Java) — this
+checks code/docs vs. *the published mathematics*.
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Good news up front:** `doc/math/references.md` is unusually scholarly and already
+> contains several *self-corrections* (the Glickenstein "eq. (4.6)" numbering fix →
+> §5.2 parametrization; the Schläfli boundary-term re-attribution to Rivin–Schlenker
+> 1999; the Bowers–Stephenson formula-vs-theory clarification). That is exemplary and
+> rare. The findings below are the gaps that remain *despite* this strong baseline.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| M1 | 🟡 | Kolpakov–Mednykh volume formula is used in code but **absent from `references.md`** | `hyper_ideal_utility.hpp:80`, `hyper_ideal_functional.hpp:321` |
+| M2 | 🟡 | BPS circle-packing paper cited as **"2010"** in code but **"2015"** in `references.md` — inconsistent year for a load-bearing reference of an *implemented* phase | `cp_euclidean_functional.hpp`, `newton_solver.hpp`, `Discrete_circle_packing.h` vs `references.md` |
+| M3 | 🟡 | Future-dated / arXiv-only citations (2025, 2026) back *unimplemented* phases but sit alongside implemented ones — re-verify against published versions before submission | `references.md` |
+| M4 | 🔵 | No canonical citation-key convention — the same work appears as `Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004` etc. | code + docs |
+| M5 | 🔵 | The large hand-derivations (notably `hyperideal-hessian-derivation.md`, 34 KB) have their *results* numerically validated but the *prose derivations* are unreviewed by a domain expert | `doc/math/*-derivation.md` |
+
+---
+
+## M1 — 🟡 Kolpakov–Mednykh volume formula not in references.md
+
+### Evidence
+```cpp
+// hyper_ideal_utility.hpp:80
+/// the Kolpakov-Mednykh formula (arxiv math/0603097).  Same as Java …
+// hyper_ideal_functional.hpp:321
+///   * Exactly one vertex ideal (…) → Kolpakov-Mednykh volume
+```
+`grep -c Kolpakov doc/math/references.md` → **0**.
+
+### Problem
+The hyper-ideal **volume** computation — a core ingredient of the Springborn-2020
+functional and the energy itself — rests on the Kolpakov–Mednykh formula (and a
+Meyerhoff/Ushijima component, cited 6× elsewhere). The code cites it inline by arXiv
+ID, but `references.md`, the stated "citation source of truth", omits it entirely. A
+reviewer auditing the math foundation against the references file would find a
+load-bearing formula with no entry.
+
+### Fix
+Add a `references.md` row: Kolpakov, Mednykh — *(full title)*, arXiv `math/0603097`,
+mapped to `hyper_ideal_utility.hpp`. Likewise confirm the Meyerhoff / Ushijima 2006
+volume reference (cited in code) has a row.
+
+### Acceptance criteria
+- Every formula cited inline in `code/include/` has a matching `references.md` entry.
+
+---
+
+## M2 — 🟡 BPS paper: "2010" in code vs "2015" in references.md
+
+### Evidence
+- Code/docs cite it as **2010** (e.g. `cp_euclidean_functional.hpp`,
+  `newton_solver.hpp`, `CGAL/Discrete_circle_packing.h`, plus 26 doc hits of
+  "Bobenko-Pinkall-Springborn 2010").
+- `references.md` lists it as **2015**: *"Discrete conformal maps and ideal hyperbolic
+  polyhedra, Geometry & Topology 19(4) (2015), arXiv 1005.2698."*
+
+### Problem
+Both are "correct" in a sense — the arXiv preprint (`1005.2698`) is **2010**, the
+published Geometry & Topology version is **2015** — but the project uses the two years
+interchangeably for the *same* paper, including in the public CGAL header
+(`Discrete_circle_packing.h`) and the `phase-9a-validation.md` mapping. This is the
+reference for an **implemented, shipped** phase (9a.1 CP-Euclidean), so the
+inconsistency is user-visible and would be flagged in CGAL review.
+
+### Fix
+Pick one canonical citation (recommend the **published 2015** Geometry & Topology
+version, with the arXiv 2010 ID noted) and use it everywhere. Update the code comments
+and docs that say "2010" to match `references.md`, or vice-versa — but make them agree.
+
+### Acceptance criteria
+- The BPS circle-packing paper is cited with a single, consistent year across code and
+  docs (matching `references.md`).
+
+---
+
+## M3 — 🟡 Future-dated / preprint citations must be re-verified before submission
+
+### Evidence
+`references.md` cites, among others:
+- Bobenko, Lutz **2025** (arXiv 2310.17529) — Phase 9d.2 (🔜 planned)
+- Bowers, Bowers, Lutz **2026** (arXiv 2601.22903) — Phase 9b-analytic / 10c′
+- Lutz **2024** PhD thesis; Bobenko-Lutz 2024 IMRN
+
+### Problem
+Two issues:
+1. **Verification:** arXiv-only and future-dated (2025/2026) references can change
+   (version bumps, final published venue, even withdrawal). Before any public release
+   or CGAL submission, each should be re-checked against its final published form. The
+   arXiv ID `2601.22903` in particular (Jan 2026) is very recent relative to this
+   audit and warrants a manual confirmation that it resolves.
+2. **Scope confusion:** these back **unimplemented "future research"** phases (🔜),
+   but the Bowers-Bowers-Lutz 2026 row claims it "supports correctness of the analytic
+   Hessian" — which *is* implemented (Phase 9b-analytic, ✅). A reader could conclude
+   the shipped analytic Hessian *depends* on a 2026 preprint. Clarify that the
+   implemented derivation stands on its own (it is numerically validated, see M5) and
+   the 2026 paper is corroborating, not foundational.
+
+### Fix
+- Re-verify every 2024–2026 / arXiv-only citation against its published version; add
+  DOIs once available.
+- Sharpen the wording so implemented-phase correctness is never described as resting
+  on an unpublished/future reference.
+
+### Acceptance criteria
+- All post-2023 citations are confirmed to resolve; no implemented-phase correctness
+  claim depends solely on a preprint/future reference.
+
+---
+
+## M4 — 🔵 No canonical citation-key convention
+
+### Evidence
+The same works appear in many surface forms across code and docs:
+`Luo 2004` / `Luo-2004` / `Luo (2004)` / `Luo's 2004`; `Springborn 2020` /
+`Springborn (2020)` / `Springborn-2020`; `Bowers-Stephenson` vs `Bowers, Stephenson`.
+
+### Problem
+Cosmetic but it defeats grep-ability and cross-referencing (cf. the false-negative in
+this audit's own tooling: `Bowers-Bowers-Lutz 2026` did not match the comma-form
+`Bowers, Bowers, Lutz`). For a library aiming at CGAL, a consistent citation key
+(e.g. `[SpringbornDCG2020]`) referenced from both code and `references.md` is the
+clean solution.
+
+### Fix
+Define short citation keys in `references.md` and use them verbatim in code comments
+and docs.
+
+### Acceptance criteria
+- One canonical key per reference; code/docs cite the key, not free-form variants.
+
+---
+
+## M5 — 🔵 Large derivations: results validated, prose unreviewed
+
+### Evidence
+`doc/math/hyperideal-hessian-derivation.md` (34 KB) derives the analytic HyperIdeal
+Hessian; `validation.md` and the FD-vs-analytic tests (`test_hyper_ideal_hessian.cpp`,
+block-FD vs full-FD) check the *result* numerically.
+
+### Problem
+The derivation **result** is well-protected — the analytic Hessian is tested against
+finite differences, so an algebra error would surface as a test failure. But the
+**prose derivation itself** (the step-by-step algebra a reader would follow to trust
+or extend it) has not been reviewed by a domain expert, and a derivation that "happens
+to match FD at the tested points" can still contain a sign/indexing slip that the
+specific test meshes don't excite.
+
+### Fix
+- Have a discrete-differential-geometry expert read `hyperideal-hessian-derivation.md`
+  and `discrete-conformal-theory.md` for derivational soundness (this is naturally
+  part of the planned reviewer meeting — see `briefing.md`).
+- Strengthen confidence cheaply by adding a randomized/property-based FD check (random
+  valid DOF vectors on several genera) so the numerical safety net covers more than the
+  fixed smoke meshes.
+
+### Acceptance criteria
+- The key derivations are signed off by a domain reviewer, and/or the FD validation is
+  randomized rather than fixed-mesh-only.
+
+---
+
+## What is already good
+
+- `references.md` is **scholarly and self-correcting** — it explicitly fixes its own
+  earlier over-citations (Glickenstein equation numbering, Schläfli→Rivin–Schlenker,
+  Bowers–Stephenson). This is well above typical project hygiene.
+- Implemented vs. planned references are marked ✅ / 🔜 — the reader can tell which
+  citations underpin shipped code (M3 only asks to keep that discipline airtight).
+- The primary source (Sechelmann 2016 PhD thesis, CC BY-SA 4.0) is correctly
+  identified, and the Java provenance is linked — directly relevant to CGAL audit G0.
+- Derivation results are numerically validated (FD vs analytic) — the right safety net
+  (M5 just asks to widen it and get a human sign-off).
+
+## Suggested order
+1. **M2** (BPS year) + **M1** (Kolpakov–Mednykh) — quick citation fixes, user-visible.
+2. **M3** (re-verify post-2023 refs; fix scope wording) — before any submission.
+3. **M5** (expert sign-off + randomized FD) — fold into the reviewer meeting.
+4. **M4** (citation keys) — polish.
diff --git a/doc/reviewer/numerical-stability-audit-2026-05-31.md b/doc/reviewer/numerical-stability-audit-2026-05-31.md
new file mode 100644
index 0000000..71d957c
--- /dev/null
+++ b/doc/reviewer/numerical-stability-audit-2026-05-31.md
@@ -0,0 +1,234 @@
+# Numerical-Stability Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Tolerance hierarchy, conditioning, catastrophic cancellation, and the
+hard-coded "magic" constants across `code/include/`.
+**Focus:** Floating-point robustness of a numerical library — distinct from
+port-faithfulness (`java-port-audit.md`) and from internal error propagation
+(`test-coverage-error-handling-audit-2026-05-31.md`).
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Relationship to existing audits:** `java-port-audit.md` already verified several
+> per-formula numerical edge cases (degenerate triangles #1, overflow centring #10).
+> This audit takes the *cross-cutting* view those miss: how the tolerances relate to
+> each other, where constants are hard-coded vs. centralized, and where the formulas
+> can lose precision. No finding here duplicates java-port-audit.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| N1 | 🔴 | FD-Hessian step (`1e-5`) sets an accuracy floor (~`1e-10`) too close to the Newton tol (`1e-8`) — can stall quadratic convergence | `newton_solver.hpp:408,569` |
+| N2 | 🟡 | Tolerance hierarchy is undocumented and uncoordinated — 7+ independent literals with no stated relationship | many headers |
+| N3 | 🟡 | Discontinuous clamp `b<0 → 0.01` breaks gradient/Hessian continuity at the domain boundary | `hyper_ideal_functional.hpp:179,274` |
+| N4 | 🟡 | Magic constants (`-30.0`, `0.01`, `1e-15`, `1.0-1e-15`) are unnamed, undocumented, and scattered | `spherical_functional.hpp`, `spherical_geometry.hpp`, `hyper_ideal_functional.hpp` |
+| N5 | 🟡 | Cotangent/area formula is cancellation-prone for needle/cap triangles | `euclidean_hessian.hpp:81-93` |
+| N6 | 🔵 | `constants.hpp` holds only π/2π — all tolerances live as bare literals | `constants.hpp` |
+| N7 | 🔵 | No conditioning diagnostic on the Hessian before the linear solve | `newton_solver.hpp` |
+
+---
+
+## N1 — 🔴 FD-Hessian step size fights the convergence tolerance
+
+### Evidence
+- `newton_hyper_ideal` and `newton_inversive_distance` build the Hessian by **finite
+  differences** with `hess_eps = 1e-5` (`newton_solver.hpp:408`, `:569`).
+- Both solvers converge against `tol = 1e-8` on `‖G‖∞` (`:406`, `:567`).
+
+### Problem
+A central-difference Hessian with step `h = 1e-5` has error `O(h²) + O(ε_machine/h)`.
+With `h = 1e-5` the truncation term is ~`1e-10` and the round-off term is
+~`1e-16/1e-5 = 1e-11`; the achievable Hessian accuracy floor is therefore
+**~`1e-10`–`1e-11`**. That is only ~2–3 decades below the convergence target
+`tol = 1e-8`. Near the solution, where Newton should converge quadratically, an
+inaccurate Hessian degrades the step to linear convergence and can **stall** the
+iteration just above `tol` — exactly the regime `test_newton_phase9a.cpp` exercises.
+
+This is also why the line-search "stall" exit (FINDING-H1 / error-handling audit)
+can trigger on otherwise well-posed problems: the FD Hessian, not the geometry, is
+the limiting factor.
+
+### Fix
+- Primary: replace the FD Hessian with the analytic / block-FD paths (cross-ref
+  `api-performance-audit` B1 — the HyperIdeal block-FD already exists and is more
+  accurate as well as faster).
+- Until then: document the coupling, and consider a richer FD stencil or
+  Richardson extrapolation if FD must stay. A relative step `h = 1e-6·(1+|x_i|)`
+  is more robust than an absolute `1e-5`.
+
+### Acceptance criteria
+- The FD-step/tol relationship is documented, or the analytic/block-FD Hessian
+  replaces FD so the floor drops well below `tol`.
+- A test demonstrates quadratic (not stalled) convergence near the solution.
+
+---
+
+## N2 — 🟡 Tolerance hierarchy is undocumented and uncoordinated
+
+### Evidence (the full set of independent literals)
+| Constant | Value | Location | Meaning |
+|---|---|---|---|
+| Newton `tol` | `1e-8` | `newton_solver.hpp` (all 5 solvers) | convergence on `‖G‖∞` |
+| FD `hess_eps` | `1e-5` | `newton_solver.hpp:408,569`, `hyper_ideal_hessian.hpp:67` | Hessian FD step |
+| `gradient_check` `eps`/`tol` | `1e-5` / `1e-4` | `hyper_ideal_functional.hpp:474-475` | test-only FD check |
+| Armijo `c1` | `1e-4` | `newton_solver.hpp:149` | sufficient-decrease |
+| sparsity drop | `1e-15` | `newton_solver.hpp:599` | triplet prune threshold |
+| Gauss-Bonnet `tol` | `1e-8` | `gauss_bonnet.hpp:134,154` | χ residual |
+| spherical clamp | `1e-15` | `spherical_geometry.hpp:34` | `asin` domain guard |
+
+### Problem
+These seven thresholds were each chosen locally (several "to match the Java
+`FunctionalTest`"), with **no documented relationship**. Yet they interact: N1 shows
+`hess_eps` vs `tol`; the sparsity drop `1e-15` interacts with `hess_eps` (FD values
+below `1e-15` are pruned, but FD noise is ~`1e-11`, so the prune threshold is
+effectively never the limiting factor — possibly dead). A reviewer cannot tell
+which are load-bearing and which are arbitrary.
+
+### Fix
+Add a short `doc/math/tolerances.md` (or a section in `constants.hpp`) that states
+each tolerance, its role, and the constraints between them (e.g. "FD floor must be
+≪ Newton tol", "Armijo c1 ∈ [1e-4, 1e-1]"). Centralize them as named `constexpr`.
+
+### Acceptance criteria
+- Every numerical threshold is named, documented, and its relationship to the
+  others stated.
+
+---
+
+## N3 — 🟡 Discontinuous clamp breaks gradient/Hessian continuity
+
+### Evidence
+`hyper_ideal_functional.hpp:179-181` and `:274-276`:
+```cpp
+if (v1b && b1 < 0.0) b1 = 0.01;   // negative scale → snap to 0.01
+```
+
+### Problem
+This snaps any negative `b` to a constant `0.01`. The map `b ↦ max(b, 0.01)` is
+continuous but **not differentiable** at `b = 0`, and the snap-to-constant makes the
+*returned angles* locally independent of `b` for `b < 0` — so the analytic gradient
+and the FD Hessian disagree across the boundary, and Newton steps that cross `b = 0`
+get an inconsistent local model. The comment says it "mirrors the Java original",
+but the Java code is a reference, not a correctness proof: a hard clamp inside the
+function being differentiated is a known source of Newton stalls.
+
+### Fix
+- Prefer keeping iterates in the feasible region via the line search (reject steps
+  that drive `b < b_min`) rather than clamping inside the energy evaluation.
+- If clamping must stay, use a smooth barrier / softplus so the derivative is
+  continuous, and make `b_min` a named constant (N4).
+
+### Acceptance criteria
+- The energy/gradient used by Newton is C¹ across the feasibility boundary, or the
+  line search keeps iterates strictly feasible so the clamp never fires.
+
+---
+
+## N4 — 🟡 Unnamed magic constants
+
+### Evidence
+- `spherical_functional.hpp`: `m.lambda0[e] = -30.0;` (very-short-edge floor)
+- `spherical_geometry.hpp:34`: `if (half >= 1.0) half = 1.0 - 1e-15;`
+- `hyper_ideal_functional.hpp`: `0.01` clamp (N3), `b < 0.0` thresholds
+- `newton_solver.hpp:599`: `if (std::abs(val) > 1e-15)`
+
+### Problem
+Each is a bare literal with at most an inline comment. `-30.0` (≈ `exp(-15)`, i.e.
+edge length ~`3e-7`) and `1.0 - 1e-15` (the `asin`/`acos` domain guard) encode real
+numerical reasoning that is invisible to the next maintainer and impossible to tune
+consistently.
+
+### Fix
+Promote to named `constexpr` in `constants.hpp` with a one-line rationale each, e.g.
+`constexpr double LOG_LENGTH_FLOOR = -30.0;  // exp(-15): edge below ~3e-7 treated as 0`.
+
+### Acceptance criteria
+- No bare numeric tolerance/floor literals remain in the math headers; each is a
+  documented named constant.
+
+---
+
+## N5 — 🟡 Cotangent/area formula is cancellation-prone
+
+### Evidence
+`euclidean_hessian.hpp:81-93`:
+```cpp
+const double t12 = -l12 + l23 + l31;
+const double t23 = +l12 - l23 + l31;
+const double t31 = +l12 + l23 - l31;
+...
+const double denom2 = 2.0 * std::sqrt(t12 * t23 * t31 * l123);   // = 8·Area
+```
+
+### Problem
+For a needle triangle (one edge ≈ sum of the other two), one of `t12/t23/t31` is the
+difference of nearly-equal lengths → **catastrophic cancellation**, and the area via
+`sqrt` of the product loses precision. The cotangent weights then carry large relative
+error, which feeds directly into the Hessian and the linear solve. The `<= 0` guard
+catches the fully-degenerate case but not the *ill-conditioned-but-valid* one.
+
+### Fix
+Use a numerically stable area formula (Kahan's formula for triangle area from sorted
+side lengths) instead of the raw product-under-sqrt. This is a well-known, drop-in
+improvement for cotangent-Laplacian assembly.
+
+### Acceptance criteria
+- A sliver-triangle test shows the cotangent weights match a high-precision
+  (e.g. `long double` / Kahan) reference to acceptable relative error.
+
+---
+
+## N6 — 🔵 constants.hpp holds only π
+
+### Evidence
+`constants.hpp` defines exactly `PI` and `TWO_PI`. Every tolerance from N2 lives
+elsewhere as a literal.
+
+### Fix
+Extend `constants.hpp` (or a sibling `tolerances.hpp`) to be the single source of
+truth for the N2/N4 constants. Tie to N2's documentation.
+
+---
+
+## N7 — 🔵 No conditioning diagnostic before the linear solve
+
+### Evidence
+`solve_with_fallback` (`newton_solver.hpp:65`) tries LDLT then SparseQR but never
+reports the conditioning of `H`.
+
+### Problem
+On an ill-conditioned-but-non-singular Hessian, LDLT "succeeds" and returns a
+low-accuracy step with no signal. The `sparse_qr_fallback_used` flag only fires on
+outright LDLT failure, not on near-singularity.
+
+### Fix
+Optionally expose an estimate (e.g. smallest pivot magnitude from LDLT, or a cheap
+condition estimate) in the diagnostics, so callers/tests can flag near-singular
+solves. Low priority; pairs naturally with the FINDING-I1 status enum
+(error-handling audit).
+
+---
+
+## What is already good
+
+- `constants.hpp` centralizes π at 30 digits — the right instinct, just not applied
+  to tolerances (N6).
+- The spherical `asin` domain guard (`spherical_geometry.hpp:34`) exists at all —
+  many implementations forget it (it just needs a named constant, N4).
+- Central differences (not forward) are used for FD gradients/Hessians — the correct
+  O(h²) choice.
+- `java-port-audit.md` #10 already flagged the inversive-distance edge-length overflow
+  centring — consistent with this audit's spirit; coordinate the two.
+
+## Suggested order
+
+1. **N1** (FD step vs tol) — highest correctness impact; largely subsumed by the
+   `api-performance-audit` B1 analytic/block-FD work.
+2. **N3** (discontinuous clamp) — fixes a real Newton-stall source.
+3. **N5** (stable area) — drop-in robustness for the Euclidean Hessian.
+4. **N2 + N4 + N6** (document + centralize tolerances/constants) — do together.
+5. **N7** (conditioning diagnostic) — polish, pairs with I1.
diff --git a/doc/reviewer/test-coverage-error-handling-audit-2026-05-31.md b/doc/reviewer/test-coverage-error-handling-audit-2026-05-31.md
new file mode 100644
index 0000000..05743ea
--- /dev/null
+++ b/doc/reviewer/test-coverage-error-handling-audit-2026-05-31.md
@@ -0,0 +1,489 @@
+# Test-Coverage & Error-Handling Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** `code/include/` (31 headers), `code/tests/` (26 fast + 246 CGAL tests)
+**Focus:** Test coverage gaps and error-handling correctness — NOT a port-faithfulness review.
+
+This document is self-contained. A new session can pick up any finding below and
+act on it without prior context. Each finding includes:
+- exact file path + line numbers (verified by direct file read)
+- a minimal reproduction of the problematic code
+- the recommended fix
+- acceptance criteria for "done"
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Hint / nice-to-have
+
+> **Note:** This audit is complementary to `external-audit-2026-05-30.md` (which
+> covers port-faithfulness bugs). There is no overlap in findings — this one is
+> strictly about *test coverage* and *error-handling robustness*.
+
+---
+
+## How to read this document in a new session
+
+```bash
+# 1. Build the CGAL test suite (needed to verify test-related findings)
+cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON
+cmake --build build-cgal --target conformallab_cgal_tests -j$(nproc)
+
+# 2. Run the full suite before making any change (establish baseline)
+ctest --test-dir build-cgal -R '^cgal\.' --output-on-failure
+# Expected: 246 passed, 0 failed
+
+# 3. Fast suite (for coverage-script findings)
+cmake -S code -B build && cmake --build build --target conformallab_tests
+ctest --test-dir build --output-on-failure   # Expected: 26 passed
+
+# 4. Pick a finding below, apply the fix, re-run ctest, then commit.
+```
+
+The Java reference implementation (for any "what should the behavior be" question):
+```
+/Users/tarikmoussa/Desktop/conformallab/src/de/varylab/discreteconformal/
+```
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Primary file |
+|----|-----|-------|--------------|
+| C1 | 🔴 | `solve_linear_system` discards its `ok` flag — double solver failure is invisible | `code/include/newton_solver.hpp:107` |
+| C2 | 🔴 | `coverage.sh` uses `\|\| true` on every lcov command — script can never fail | `scripts/quality/coverage.sh` |
+| C3 | 🔴 | Coverage not CI-gated — no enforcement mechanism exists | CI config |
+| I1 | 🟡 | `NewtonResult` cannot distinguish MaxIter / LinearSolverFailed / LineSearchStalled | `code/include/newton_solver.hpp:51` |
+| I2 | 🟡 | `serialization.hpp`: 4 throw statements, 0 negative tests | `code/include/serialization.hpp` |
+| I3 | 🟡 | `load_mesh` non-triangle-mesh throw path untested | `code/tests/cgal/test_mesh_io.cpp` |
+| I4 | 🟡 | `spherical_hessian.hpp:114` throw has no `EXPECT_THROW` test | `code/tests/cgal/test_spherical_hessian.cpp` |
+| I5 | 🟡 | Coverage measures only the 26 fast tests (~9.6% of suite) | `scripts/quality/coverage.sh` |
+| H1 | 🔵 | `res.iterations` is wrong/stale when solver breaks on `!ok` | `code/include/newton_solver.hpp` (×5) |
+| H2 | 🔵 | 5 near-identical Newton loops — maintenance risk | `code/include/newton_solver.hpp` |
+| H3 | 🔵 | `enforce_gauss_bonnet` does not report magnitude of applied correction | `code/include/gauss_bonnet.hpp` |
+| H4 | 🔵 | `reduce_to_fundamental_domain`: boundary `Im(τ)==0.0` untested | `code/tests/cgal/test_phase7.cpp` |
+| H5 | 🔵 | Degenerate-triangle path in Newton solver not integration-tested | `code/include/euclidean_hessian.hpp:85` |
+| H6 | 🔵 | 2 ARM64 tests marked `@Ignore` — platform-specific coverage gap | test suite |
+
+---
+
+## FINDING-C1 — 🔴 `solve_linear_system` silently discards its failure flag
+
+### Location
+`code/include/newton_solver.hpp` lines 107–114
+
+### Problem
+The public linear-system solver computes `ok` from `solve_with_fallback` but never
+returns or surfaces it. On double solver failure (both LDLT and SparseQR fail),
+the function returns `Eigen::VectorXd::Zero(n)` — indistinguishable from a genuine
+zero solution.
+
+```cpp
+inline Eigen::VectorXd solve_linear_system(
+    const Eigen::SparseMatrix<double>& A,
+    const Eigen::VectorXd&             rhs,
+    bool*                              fallback_used = nullptr)
+{
+    bool ok = false;
+    return detail::solve_with_fallback(A, rhs, ok, fallback_used);
+    //                                            ^^ `ok` computed, then dropped
+}
+```
+
+This function is documented as a *public* primitive ("Exposing it publicly lets
+callers reuse the logic"). A downstream caller has no way to detect that the
+solve failed.
+
+### Fix
+Add an optional `bool* ok` out-parameter (mirroring `fallback_used`), or return a
+small struct `{ VectorXd x; bool ok; }`. Prefer the out-parameter to preserve the
+existing return type and call sites.
+
+```cpp
+inline Eigen::VectorXd solve_linear_system(
+    const Eigen::SparseMatrix<double>& A,
+    const Eigen::VectorXd&             rhs,
+    bool*                              fallback_used = nullptr,
+    bool*                              ok            = nullptr)
+{
+    bool ok_local = false;
+    auto x = detail::solve_with_fallback(A, rhs, ok_local, fallback_used);
+    if (ok) *ok = ok_local;
+    return x;
+}
+```
+
+### Acceptance criteria
+- A new test in `test_newton_solver.cpp` constructs a genuinely unsolvable system
+  (e.g. an inconsistent over-determined sparse system that defeats both LDLT and QR)
+  and asserts `ok == false`.
+- Existing 3 SparseQR-fallback tests still pass.
+
+---
+
+## FINDING-C2 — 🔴 Coverage script can never fail
+
+### Location
+`scripts/quality/coverage.sh` lines 95–112
+
+### Problem
+Every lcov/genhtml invocation is suffixed with `|| true`:
+
+```bash
+lcov --capture ... >/dev/null 2>&1 || true
+lcov --extract ... --output-file "$BUILD_DIR/coverage.info" ... || true
+genhtml ... || true
+```
+
+If lcov fails completely, `coverage.info` is empty, but the script still exits 0.
+The script is documented as a future CI quality gate ("once a coverage threshold
+is agreed … the gate can be a single line in cpp-tests.yml") — but as written it
+would always pass, defeating the purpose of a gate.
+
+### Fix
+- Remove `|| true` from the `--capture` and `--extract` steps; let real failures
+  propagate (the `set -euo pipefail` at the top will then catch them).
+- Keep tolerance ONLY for the known-noisy `genhtml` cosmetic step if necessary,
+  but verify `coverage.info` is non-empty explicitly:
+  ```bash
+  [ -s "$BUILD_DIR/coverage.info" ] || { echo "FAIL: empty coverage trace" >&2; exit 1; }
+  ```
+
+### Acceptance criteria
+- Running the script with a deliberately broken lcov (e.g. `PATH` without gcov data)
+  exits non-zero.
+- A successful run still produces a non-empty `coverage.info` and exits 0.
+
+---
+
+## FINDING-C3 — 🔴 Coverage is not CI-gated
+
+### Location
+CI configuration (`.gitea/workflows/cpp-tests.yml`) + `scripts/quality/coverage.sh:12-14`
+
+### Problem
+The script header states verbatim: *"Local-only. Not gated in CI yet; once a
+coverage threshold is agreed with the reviewer (e.g. 80 %)…"*. There is no
+enforcement: coverage can silently regress to 0% with no signal.
+
+### Decision — agreed thresholds (2026-05-31)
+For a numerical, header-only library the agreed gate is:
+
+| Metric | Gate | Rationale |
+|---|---|---|
+| **Line coverage** | **80 %** | Industry-standard, defensible, not punitive |
+| **Branch coverage** | **70 %** | Numerical code has legitimately hard-to-hit branches (degeneracy checks, solver fallbacks, NaN paths) |
+| **Function coverage** | **90 %** | Header-only → an untested function is an obvious gap |
+
+100 % is explicitly **not** the target — the degenerate-triangle and solver-failure
+branches are expected to be only partially covered.
+
+### Fix
+1. **First fix C2** (so the gate is trustworthy) **and I5** (so it measures the right
+   thing — a percentage over only the 26 fast tests is meaningless).
+2. Establish a baseline by running the corrected script once.
+3. If the measured baseline is **below** these gates, ratchet up: set the gate a few
+   points below baseline now and raise it as coverage improves — do not block work on
+   day one. If baseline already exceeds them, set the gates as above.
+4. Add a `--fail-under` style check and wire it into the `/quality-gates` workflow.
+
+### Acceptance criteria
+- `coverage.sh` accepts `COVERAGE_MIN_LINE` / `COVERAGE_MIN_BRANCH` /
+  `COVERAGE_MIN_FUNC` env vars (defaults 80 / 70 / 90) and exits 1 when any is missed.
+- The quality-gates workflow invokes it with these thresholds.
+
+---
+
+## FINDING-I1 — 🟡 NewtonResult cannot tell *why* it failed
+
+### Location
+`code/include/newton_solver.hpp` lines 51–56 (struct) + the 5 solver loops
+(`newton_euclidean`, `newton_spherical`, `newton_hyper_ideal`,
+`newton_cp_euclidean`, `newton_inversive_distance`)
+
+### Problem
+All five solvers collapse three distinct failure modes into `converged = false`:
+
+```cpp
+if (!ok) break;          // linear solver failed (numerically degenerate)
+...
+if (!improved) break;    // line search stalled (bad start / non-convex region)
+...
+// loop exits normally    // max_iter reached (might converge with more iterations)
+```
+
+A caller seeing `converged == false` cannot tell which happened, so cannot choose
+an appropriate recovery (re-seed start point vs. raise max_iter vs. report
+ill-posed problem).
+
+### Fix
+Add to `NewtonResult`:
+```cpp
+enum class Status { Converged, MaxIterReached, LinearSolverFailed, LineSearchStalled };
+Status status = Status::MaxIterReached;
+```
+Set it at each exit point. Keep the existing `converged` bool for backward
+compatibility (`converged == (status == Status::Converged)`).
+
+### Acceptance criteria
+- Each of the 4 statuses is asserted by at least one test (the existing
+  convergence tests cover `Converged`; add targeted tests for the 3 failure modes).
+
+---
+
+## FINDING-I2 — 🟡 serialization.hpp: 4 throws, 0 negative tests
+
+### Location
+`code/include/serialization.hpp` lines 82, 96, 198, 245 (all `throw std::runtime_error`)
+Tests: `code/tests/cgal/test_layout.cpp` (only `ASSERT_NO_THROW` happy-path cases)
+
+### Problem
+```cpp
+if (!ofs) throw std::runtime_error("Cannot write: " + path);   // L82, L198
+if (!ifs) throw std::runtime_error("Cannot open: " + path);    // L96, L245
+```
+None of the four failure paths is exercised by a test.
+
+### Fix
+Add to `test_layout.cpp`:
+```cpp
+TEST(Serialization, ThrowsOnUnwritablePath) {
+    EXPECT_THROW(save_result_json("/nonexistent_dir/x.json", res, ...), std::runtime_error);
+}
+TEST(Serialization, ThrowsOnMissingFileRead) {
+    EXPECT_THROW(load_result_json("/tmp/does_not_exist_conflab.json"), std::runtime_error);
+}
+```
+(Repeat for the XML variants to cover all four sites.)
+
+### Acceptance criteria
+- All four throw sites are covered by `EXPECT_THROW`.
+
+---
+
+## FINDING-I3 — 🟡 load_mesh non-triangle path untested
+
+### Location
+`code/include/mesh_io.hpp` lines 61–64 (the `!is_triangle_mesh` throw)
+Test file: `code/tests/cgal/test_mesh_io.cpp`
+
+### Problem
+`test_mesh_io.cpp:111` tests the missing-file throw, but NOT the
+"file exists but is a quad/polygon mesh" throw — which is the more interesting
+guard (it protects every downstream functional from silent mis-handling).
+
+### Fix
+Write a quad-only OFF file to `/tmp`, then:
+```cpp
+TEST(MeshIO, LoadMeshThrowsOnNonTriangleMesh) {
+    // write a single quad face OFF to a temp path ...
+    EXPECT_THROW(load_mesh(quad_path), std::runtime_error);
+}
+```
+
+### Acceptance criteria
+- The non-triangle branch in `load_mesh` is covered and asserts the runtime_error.
+
+---
+
+## FINDING-I4 — 🟡 spherical_hessian throw untested
+
+### Location
+`code/include/spherical_hessian.hpp` line 114 (`throw std::logic_error`)
+Test file: `code/tests/cgal/test_spherical_hessian.cpp`
+
+### Problem
+The Euclidean analogue (`euclidean_hessian.hpp:124`) IS tested via
+`test_euclidean_hessian.cpp:237` (`EXPECT_THROW(..., std::logic_error)`).
+The spherical equivalent has no such test.
+
+### Fix
+Mirror the Euclidean test: assign an edge DOF (or whatever triggers the
+`logic_error` at L114 — read the surrounding code to confirm the precondition)
+and assert the throw.
+
+### Acceptance criteria
+- `EXPECT_THROW(spherical_hessian(mesh, x, maps), std::logic_error)` present and passing.
+
+---
+
+## FINDING-I5 — 🟡 Coverage measures only ~9.6% of the test suite
+
+### Location
+`scripts/quality/coverage.sh` line 73
+
+### Problem
+```bash
+ctest -E "^cgal\." --output-on-failure   # excludes ALL 246 CGAL tests
+```
+Coverage is computed from the 26 fast tests only. The core solvers
+(`newton_solver.hpp`, `euclidean_functional.hpp`, `gauss_bonnet.hpp`,
+`layout.hpp`, …) are exercised almost exclusively by the CGAL suite, so the
+reported number does not reflect coverage of the project's actual core.
+
+The script's rationale is legitimate (CGAL tests under coverage instrumentation
+need ~6 GB RAM). But the consequence — a coverage number that excludes the core —
+should at minimum be made explicit, and ideally addressed.
+
+### Fix options
+- **(a) Document loudly:** rename the metric to "fast-suite coverage" everywhere it
+  is reported, so nobody mistakes it for whole-project coverage.
+- **(b) Tiered coverage:** add an opt-in `WITH_CGAL_COVERAGE=1` mode that runs the
+  CGAL suite under coverage on a high-memory machine (not the Pi runner), producing
+  a separate `coverage-cgal.info`.
+- **(c) Merge traces:** if (b) is run, `lcov --add-tracefile` can combine fast +
+  CGAL into one report.
+
+### Acceptance criteria
+- Decision recorded; if (a), the script + docs no longer imply whole-project coverage.
+
+---
+
+## FINDING-H1 — 🔵 res.iterations stale on `!ok` break
+
+### Location
+`code/include/newton_solver.hpp` — all 5 solver loops (e.g. lines 269–284 for Euclidean)
+
+### Problem
+```cpp
+Eigen::VectorXd dx = detail::solve_with_fallback(H, -G, ok);
+if (!ok) break;          // res.iterations still holds the PREVIOUS iteration's value
+...
+res.iterations = iter + 1;   // only reached if the solve + line search succeed
+```
+On a linear-solver break, `res.iterations` does not reflect the iteration at which
+the failure occurred (it's the prior value, or 0 on the first iteration).
+
+### Fix
+Set `res.iterations = iter + 1;` immediately at the top of the loop body (or before
+each `break`), so it always reflects the iteration count attempted.
+
+### Acceptance criteria
+- After a forced solver failure, `res.iterations` equals the iteration index at failure.
+
+---
+
+## FINDING-H2 — 🔵 Five near-identical Newton loops
+
+### Location
+`code/include/newton_solver.hpp` — `newton_euclidean`, `newton_spherical`,
+`newton_hyper_ideal`, `newton_cp_euclidean`, `newton_inversive_distance`
+
+### Problem
+The five solvers share an identical loop skeleton (gradient → convergence check →
+Hessian → solve_with_fallback → line_search → break logic). Differences are only:
+the gradient fn, the Hessian fn, and the sign handling (spherical negates H).
+Any fix to the shared logic (e.g. H1 above) must be applied five times.
+
+### Fix
+Extract a template `newton_core(grad_fn, hessian_fn, x0, tol, max_iter)` and have
+the five public functions become thin wrappers. The spherical sign flip can be a
+parameter or handled inside its `hessian_fn` lambda.
+
+### Acceptance criteria
+- All existing Newton tests (11 + 3 fallback) pass unchanged after refactor.
+- The five public signatures are preserved (no caller changes).
+
+---
+
+## FINDING-H3 — 🔵 enforce_gauss_bonnet correction magnitude is silent
+
+### Location
+`code/include/gauss_bonnet.hpp` (the `enforce_gauss_bonnet` function near L160)
+
+### Problem
+`enforce_gauss_bonnet` adjusts cone angles so `check_gauss_bonnet` will subsequently
+pass. If the input geometry is far from satisfying Gauss-Bonnet, a large silent
+correction is applied with no signal to the caller.
+
+### Fix
+Return (or log) the total/max applied correction so callers can detect
+pathological input. Optionally warn above a configurable threshold.
+
+### Acceptance criteria
+- A test feeds intentionally bad cone angles and asserts the reported correction is large.
+
+---
+
+## FINDING-H4 — 🔵 reduce_to_fundamental_domain boundary case
+
+### Location
+`code/include/period_matrix.hpp` line 89 (`if (tau.imag() <= 0.0)`)
+Test: `code/tests/cgal/test_phase7.cpp:315`
+
+### Problem
+The guard is `<= 0.0`, but the existing test uses a clearly-negative `Im(τ)`.
+The exact-boundary case `Im(τ) == 0.0` (on the real axis) is the more numerically
+interesting trigger and is untested.
+
+### Fix
+Add `EXPECT_THROW(reduce_to_fundamental_domain({1.0, 0.0}), std::domain_error);`
+
+### Acceptance criteria
+- The `Im(τ)==0` boundary throws and is asserted.
+
+---
+
+## FINDING-H5 — 🔵 Degenerate-triangle path not integration-tested
+
+### Location
+`code/include/euclidean_hessian.hpp` lines 85–90 (`euclidean_cot_weights` returns
+`{0,0,0,false}` for degenerate triangles)
+
+### Problem
+Degenerate faces yield zero cotangent weights, which can make the assembled Hessian
+singular. The QR fallback will then "solve" it, but with undefined solution quality.
+There is no test feeding a mesh with degenerate faces through `newton_euclidean`
+to characterize the behavior.
+
+### Fix
+Add a test with a near-degenerate (sliver) triangle mesh and assert either:
+- the solver reports a meaningful non-converged status (after I1), or
+- the result is documented as best-effort.
+
+### Acceptance criteria
+- Behavior on degenerate input is characterized by an explicit test, not left undefined.
+
+---
+
+## FINDING-H6 — 🔵 Two ARM64 tests marked @Ignore
+
+### Location
+Test suite (introduced in commit `e2b0cdf`: "mark 2 known ARM64 failures as @Ignore")
+
+### Problem
+The primary CI runner is ARM64 (Raspberry Pi). Two tests are skipped there, so
+those code paths run unverified on the production CI platform.
+
+### Fix / Action
+- Locate the two `@Ignore`/`GTEST_SKIP`-guarded tests (grep for `ARM64`, `aarch64`,
+  `GTEST_SKIP`, `DISABLED_`).
+- Document the root cause (numeric tolerance? CGAL kernel difference?) in this file.
+- Either widen tolerances to make them pass on ARM64, or run them on an x86 CI lane.
+
+### Acceptance criteria
+- Root cause documented; tests either re-enabled or moved to an x86 lane that runs them.
+
+---
+
+## What is already good (do not "fix")
+
+- Consistent exception taxonomy: `std::runtime_error` at I/O boundaries,
+  `std::logic_error` for programmer errors, `std::domain_error` for math domain
+  violations — idiomatic and correct.
+- `NewtonResult.converged` flag exists (many implementations omit it).
+- Finite-difference gradient checks for every functional — the right validation style.
+- Java golden-oracle parity tests — high value for a port.
+- LDLT→SparseQR fallback is itself unit-tested (tests #12–14 in `test_newton_solver.cpp`).
+- Header-only design keeps the coverage scope (`code/include/`) clean.
+
+---
+
+## Suggested order of work
+
+1. **C2** (make the coverage script honest) — small, unblocks C3 and C5.
+2. **I5** (decide what coverage measures) — decision, then small script change.
+3. **C3** (gate it) — needs owner's threshold decision.
+4. **C1 + I1 + H1** (Newton error-reporting) — do together; they touch the same code.
+5. **H2** (refactor the 5 loops) — do *after* C1/I1/H1 so you refactor the fixed version.
+6. **I2, I3, I4, H4** (missing negative tests) — independent, parallelizable, low-risk.
+7. **H3, H5, H6** (robustness characterization) — lower priority.
diff --git a/doc/reviewer/thread-safety-audit-2026-05-31.md b/doc/reviewer/thread-safety-audit-2026-05-31.md
new file mode 100644
index 0000000..1d14a92
--- /dev/null
+++ b/doc/reviewer/thread-safety-audit-2026-05-31.md
@@ -0,0 +1,139 @@
+# Thread-Safety & Reentrancy Audit — ConformalLabpp
+
+**Date:** 2026-05-31
+**Auditor:** External reviewer (Claude Opus 4.8)
+**Scope:** Concurrency contract of the header-only library — reentrancy, hidden
+mutable global state, and safety of parallel solves.
+**Focus:** Can two threads use this library at the same time, and is that contract
+documented? Currently undocumented everywhere.
+
+Status legend: 🔴 Critical · 🟡 Important · 🔵 Polish
+
+> **Good news up front:** a scan for mutable function-local `static` variables (the
+> classic hidden-shared-state hazard) found **none**. All `static` in the headers are
+> stateless factory/accessor functions (`MobiusMap::identity`,
+> `Default_conformal_map_traits::theta_map`, etc.). So the library is *close* to
+> trivially reentrant — the findings below are about the mesh-mutation contract and
+> the missing documentation, not about data races in hidden globals.
+
+---
+
+## Summary table
+
+| ID | Sev | Title | Location |
+|----|-----|-------|----------|
+| T1 | 🟡 | No documented threading contract anywhere — users cannot know what is safe | all public headers |
+| T2 | 🟡 | The solve pipeline mutates the mesh via property maps → concurrent solves on the *same* mesh are unsafe and silently so | `*_functional.hpp`, `newton_solver.hpp` |
+| T3 | 🔵 | Property-map *creation* (`add_property_map`) on a shared mesh from two threads is a data race on CGAL's internal map registry | `setup_*_maps`, traits accessors |
+| T4 | 🔵 | Eigen threading not pinned — relies on Eigen's defaults; undocumented | `newton_solver.hpp` |
+
+---
+
+## T1 — 🟡 No documented threading contract
+
+### Evidence
+No header, no `doc/` file, and no README section states whether the API is
+thread-safe, reentrant, or single-threaded-only. `briefing.md` positions the library
+as potential "infrastructure for your work" — which invites multi-threaded use it
+never characterizes.
+
+### Problem
+Without a stated contract, a user must read the implementation to discover (T2) that
+distinct meshes are safe but a shared mesh is not. The safe pattern is real and
+simple — it just needs to be written down.
+
+### Fix
+Add a short "Thread safety" section to the main API doc (and a sentence in the key
+headers) stating the contract, e.g.:
+> *The library performs no synchronization and uses no shared mutable global state.
+> Operations on **distinct** `ConformalMesh` objects are independent and may run
+> concurrently. Operations on a **single** mesh (including any `setup_*_maps`,
+> `assign_*`, gradient, Hessian, or `newton_*` call) mutate that mesh's property maps
+> and must not run concurrently on the same mesh.*
+
+### Acceptance criteria
+- A "Thread safety" subsection exists in the public API documentation and matches the
+  actual behavior described in T2/T3.
+
+---
+
+## T2 — 🟡 Solve pipeline mutates the mesh; same-mesh concurrency is unsafe
+
+### Evidence
+- `setup_*_maps(mesh)` adds property maps to `mesh`.
+- `assign_*_dof_indices(mesh, m)` writes `m.v_idx` / `m.e_idx` into the mesh.
+- `compute_*_lambda0_from_mesh(mesh, m)` writes `m.lambda0`.
+- `newton_*` reads those maps and (via the gradient/Hessian) reads the mesh
+  repeatedly; the functions take `ConformalMesh& mesh` (non-const).
+
+### Problem
+Two threads calling `newton_euclidean(mesh, …)` on the **same** `mesh` race on the
+shared property maps — a silent data race, not a clean error. Because the signature
+is `ConformalMesh&` (mutable) this is technically "expected", but nothing warns the
+user, and the natural-looking "solve the same input mesh under two geometries in
+parallel" is exactly the unsafe case.
+
+### Fix
+- Document the contract (T1).
+- Optionally, offer a value-semantics convenience overload that takes the mesh by
+  `const&` and operates on an internal copy, for users who want fire-and-forget
+  parallel solves. (Larger change; document first.)
+
+### Acceptance criteria
+- The same-mesh hazard is documented; if a const/copying overload is added, a test
+  runs two concurrent solves on copies without a race (clean under ThreadSanitizer).
+
+---
+
+## T3 — 🔵 Concurrent property-map creation races CGAL's registry
+
+### Evidence
+`setup_*_maps` and the traits accessors call `mesh.add_property_map<…>(name, default)`.
+
+### Problem
+CGAL's `Surface_mesh::add_property_map` mutates the mesh's internal property
+container. Two threads creating maps on the same mesh concurrently is undefined
+behavior at the CGAL level — a sub-case of T2 but worth calling out because the
+traits accessors (`Conformal_map_traits.h:158-179`) create-on-demand, so even a
+"read-only-looking" first access mutates.
+
+### Fix
+Covered by the T1 contract ("any `setup_*` … on the same mesh must not run
+concurrently"). No code change beyond documentation unless the const overload (T2) is
+pursued.
+
+---
+
+## T4 — 🔵 Eigen threading is unpinned and undocumented
+
+### Evidence
+`newton_solver.hpp` uses `SimplicialLDLT` / `SparseQR` without calling
+`Eigen::setNbThreads(…)` or documenting OpenMP behavior.
+
+### Problem
+Eigen may use OpenMP threads internally depending on build flags. For a library that
+might itself be called from parallel user code, the nesting behavior (and whether
+`EIGEN_DONT_PARALLELIZE` is wanted) is unspecified. Distinct Eigen objects are
+thread-safe, so this is low risk — but it should be a documented choice.
+
+### Fix
+State the intended Eigen threading mode in the build/threading docs; consider pinning
+it explicitly (`EIGEN_DONT_PARALLELIZE` for predictability, or document that callers
+control it).
+
+---
+
+## What is already good
+
+- **No mutable static locals** anywhere in the headers — the single most important
+  reentrancy property holds.
+- All `static` members are pure functions (factories/accessors) — no shared state.
+- The header-only, value-oriented design (results returned by value as
+  `NewtonResult` / `Conformal_map_result`) means outputs are not shared.
+- Distinct-mesh concurrency genuinely *is* safe today — the contract just needs
+  documenting (T1), not implementing.
+
+## Suggested order
+1. **T1** (write the contract) — trivial, unblocks safe parallel use immediately.
+2. **T2/T3** (covered by the contract; optional const overload later).
+3. **T4** (pin/document Eigen threading) — polish.