Phase 7.5: Doxygen infrastructure + Phase 8 design freeze

Adds the Doxygen documentation pipeline as the bridge from Phase 7 (porting complete) to Phase 8 (CGAL package). Also captures the strategic Phase 8 decisions taken on 2026-05-19. Infrastructure ────────────── * Doxyfile — CGAL-style minimal configuration, HTML-only, INPUT=code/include + doc/, excludes deps/ and macOS Finder duplicates * code/CMakeLists — `doc` target via find_package(Doxygen QUIET); silently disabled if Doxygen is not installed * README — `cmake --build build --target doc` instructions * .gitignore — exclude doc/doxygen/ output Phase 8 strategic decisions (recorded in doc/api/cgal-package.md) ──────────────────────────────────────────────────────────────── * Submission to CGAL: pre-submission-ready, 12+ months horizon, MIT preserved * Mesh-type flexibility: generic FaceGraph + HalfedgeGraph * Parameter style: CGAL Named Parameters * Default kernel: Simple_cartesian<double> (status quo) * Architecture: 3-layer wrapper, no algorithm duplication * Acceptance test: Phase 9a (Inversive-Distance) as first new client CLAUDE.md updated with a compact Phase 8 decision table. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-19 19:55:50 +02:00
parent e958afbd19
commit 02fb80ee3e
6 changed files with 434 additions and 103 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,7 @@ Testing/

 # Claude Code worktrees
 .claude/
+
+# Doxygen output
+doc/doxygen/
+*.dox.tmp
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -249,7 +249,23 @@ Expected results: **36 non-CGAL tests pass**, **176 CGAL tests pass, 0 skipped**
 ## Release state

 Current release: **v0.7.0** (tag on `origin/dev`, PR to `main` open).  
-Phase 7 is complete. Phase 8 (CGAL package) is next.
+Phase 7 is complete. Phase 7.5 (Doxygen) and Phase 8 (CGAL package) are next.
+
+## Phase 8 strategic decisions (2026-05-19)
+
+The CGAL-package architecture was frozen on 2026-05-19 after the end-of-Phase-7
+docstring audit.  Full design: [`doc/api/cgal-package.md`](doc/api/cgal-package.md).
+Key decisions:
+
+| Decision | Choice |
+|---|---|
+| Submission to upstream CGAL | **Pre-submission-ready, not bound.** 12+ months horizon. |
+| License | **MIT preserved** (no LGPL switch). |
+| Mesh-type flexibility | **Generic `FaceGraph + HalfedgeGraph`** — Surface_mesh, Polyhedron_3, OpenMesh-adapter, pmp. |
+| Parameter style | **Named Parameters** (`CGAL::parameters::...`). |
+| Default kernel | **`Simple_cartesian<double>`** (status quo). |
+| Backward compatibility | **Dual-layer wrapper** — `code/include/*.hpp` stays as implementation, `include/CGAL/*.h` is thin wrapper. No algorithm duplication. |
+| Phase-8a acceptance test | **Phase 9a (Inversive-Distance)** as the first new client of the new traits API. |

 Root-level files added at v0.7.0:
 - `CITATION.cff` — machine-readable citation (Sechelmann 2016, Springborn 2020, Bobenko–Springborn 2004)
--- a/126
+++ b/126
@@ -0,0 +1,126 @@
+# Doxyfile for conformallab++
+#
+# Phase 7.5 — minimal CGAL-style Doxygen configuration.
+# Only non-default values are set; Doxygen ≥ 1.9.5 supplies the rest.
+#
+# Usage:
+#   doxygen Doxyfile           # generates HTML into doc/doxygen/html/
+#   open doc/doxygen/html/index.html
+#
+# Or via CMake:
+#   cmake --build build --target doc
+
+# ── Project identity ─────────────────────────────────────────────────────────
+PROJECT_NAME           = "conformallab++"
+PROJECT_NUMBER         = 0.7.0
+PROJECT_BRIEF          = "Discrete conformal maps on triangle meshes — C++17 reimplementation of ConformalLab (TU Berlin)"
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = doc/doxygen
+USE_MDFILE_AS_MAINPAGE = README.md
+
+# ── Input ────────────────────────────────────────────────────────────────────
+INPUT                  = README.md \
+                         CLAUDE.md \
+                         code/include \
+                         doc/api \
+                         doc/architecture \
+                         doc/math
+FILE_PATTERNS          = *.hpp *.h *.cpp *.md
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */build*/* \
+                         */deps/* \
+                         */.git/* \
+                         */test-reports/* \
+                         */* 2.hpp
+EXCLUDE_SYMBOLS        = Eigen::* boost::* std::*
+
+# ── Source browsing ──────────────────────────────────────────────────────────
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+HIDE_UNDOC_MEMBERS     = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+
+# ── Build options ────────────────────────────────────────────────────────────
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = YES
+DISTRIBUTE_GROUP_DOC   = YES
+GROUP_NESTED_COMPOUNDS = YES
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+EXTENSION_MAPPING      = h=C++ hpp=C++
+
+# ── Warnings ─────────────────────────────────────────────────────────────────
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = doc/doxygen/doxygen-warnings.log
+
+# ── HTML output ──────────────────────────────────────────────────────────────
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_COLORSTYLE        = LIGHT
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_SECTIONS  = YES
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 1
+TREEVIEW_WIDTH         = 280
+EXT_LINKS_IN_WINDOW    = NO
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+
+# ── Disabled outputs (we only want HTML) ─────────────────────────────────────
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+
+# ── Preprocessor ─────────────────────────────────────────────────────────────
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = code/include
+PREDEFINED             = CGAL_DISABLE_GMP \
+                         CGAL_DISABLE_MPFR \
+                         DOXYGEN_RUNNING
+
+# ── Diagrams ─────────────────────────────────────────────────────────────────
+HAVE_DOT               = NO
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = NO
+GROUP_GRAPHS           = YES
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+
+# ── Aliases (CGAL-style) ─────────────────────────────────────────────────────
+ALIASES               += "concept{1}=\xrefitem concept \"Concept\" \"Concepts\" \1"
+ALIASES               += "models{1}=\xrefitem models \"Models\" \"Models\" \1"
+ALIASES               += "cgalRequires{1}=\par Requirements: \n\1"
+ALIASES               += "cgalParam{2}=\param \1 \2"
--- a/README.md
+++ b/README.md
@@ -34,6 +34,10 @@ ctest --test-dir build -R "^cgal\." --output-on-failure
 # Full build with CLI + viewer (requires Wayland/X11 dev headers)
 cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -j$(nproc)
 ./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
+
+# API documentation (requires doxygen: brew/apt install doxygen)
+cmake --build build --target doc
+open doc/doxygen/html/index.html
 ```

 ---
--- a/code/CMakeLists.txt
+++ b/code/CMakeLists.txt
@@ -140,3 +140,25 @@ install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
 install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/../LICENSE
              ${CMAKE_CURRENT_SOURCE_DIR}/../CITATION.cff
        DESTINATION ${CMAKE_INSTALL_DATADIR}/conformallab)
+
+# ── Doxygen documentation target (Phase 7.5) ──────────────────────────────────
+# Generates HTML API documentation into doc/doxygen/html/.
+# Usage:
+#   cmake --build build --target doc
+#   open doc/doxygen/html/index.html
+#
+# Optional dependency: install Doxygen via `brew install doxygen` (macOS) or
+# `apt install doxygen graphviz` (Linux). The target is silently disabled
+# if Doxygen is not found.
+find_package(Doxygen QUIET)
+if(DOXYGEN_FOUND)
+    set(DOXYGEN_PROJECT_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/..)
+    add_custom_target(doc
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_PROJECT_ROOT}/Doxyfile
+        WORKING_DIRECTORY ${DOXYGEN_PROJECT_ROOT}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM)
+    message(STATUS "Doxygen found: target 'doc' available (cmake --build build --target doc)")
+else()
+    message(STATUS "Doxygen not found — 'doc' target unavailable (install: brew/apt install doxygen)")
+endif()
--- a/doc/api/cgal-package.md
+++ b/doc/api/cgal-package.md
@@ -1,77 +1,211 @@
 # Phase 8 — CGAL Package Design

-> **Status: planned.** This document describes the target architecture for Phase 8.
-> No code has been written yet. The design is informed by the CGAL package submission
-> guidelines at https://www.cgal.org/developers.html
+> **Status: design frozen, implementation planned.**
+> This document captures the strategic decisions taken before the first
+> line of Phase 8 code is written.  The decisions were taken on 2026-05-19
+> after the docstring/architecture audit at the end of Phase 7.
+>
+> The design is informed by the CGAL package submission guidelines at
+> https://www.cgal.org/developers.html and by reading the existing
+> `Polygon_mesh_processing` and `Surface_mesh_parameterization` packages.

 ---

-## Goal
+## Strategic position

-Integrate conformallab++ into the CGAL library as a proper CGAL package:
-`Discrete_conformal_map`. The package must satisfy all CGAL submission requirements:
-traits-class design, Doxygen documentation, CGAL-format test suite, and coverage of
-the CGAL coding conventions.
+| Question | Decision | Rationale |
+|---|---|---|
+| Submission to CGAL? | **Pre-submission-ready, not submission-bound.** 12+ months horizon, optional. | Keep design freedom, no editor-review pressure. Structure is valuable on its own. |
+| License | **MIT preserved.** | CGAL submission would require LGPL — deferred. Current users (academic + industrial) profit from MIT. |
+| Mesh-type flexibility | **Generic `FaceGraph + HalfedgeGraph`.** | Maximum CGAL value: works with `Surface_mesh`, `Polyhedron_3`, OpenMesh-adapter, pmp. |
+| Parameter style | **Named Parameters** (`CGAL::parameters::vertex_curvature_map(...).max_iterations(50)`). | CGAL standard; identical UX to `PMP::triangulate_*`. |
+| Default kernel | **`CGAL::Simple_cartesian<double>`.** | Status quo. Conformal geometry does not require exact predicates. |
+| Backward compatibility | **Dual-layer wrapper.** `code/include/*.hpp` stays as implementation; `include/CGAL/*.h` is thin wrapper. | Existing 176 + 36 tests unchanged. New API gets new tests. |
+| Algorithm code | **No duplication.** New CGAL headers delegate to existing code via property-map adapters. | Single source of truth; no parallel maintenance. |
+
+---
+
+## Architecture
+
+### Three-layer model
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Layer 3: Public CGAL API           include/CGAL/*.h              │
+│  ─────────────────────────                                         │
+│  • Conformal_map_traits.h           ← concept + default model     │
+│  • Discrete_conformal_map.h         ← user-facing entry           │
+│  • Conformal_layout.h, ...                                         │
+│  Named parameters, generic over FaceGraph, Doxygen-documented.     │
+└──────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ thin wrapper, no algorithm code
+                              │
+┌──────────────────────────────────────────────────────────────────┐
+│  Layer 2: Adapter / Traits          include/CGAL/Conformal_map/   │
+│  ─────────────────────────                                         │
+│  • Default_traits.h                 ← maps generic FaceGraph to   │
+│                                       Surface_mesh property maps  │
+│  • Property_map_adapter.h           ← read/write u, θ, α via      │
+│                                       boost::property_map traits  │
+└──────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ uses existing algorithms as-is
+                              │
+┌──────────────────────────────────────────────────────────────────┐
+│  Layer 1: Implementation            code/include/*.hpp            │
+│  ─────────────────────────                                         │
+│  euclidean_functional.hpp, layout.hpp, newton_solver.hpp, ...     │
+│  Hardcoded to Surface_mesh + Simple_cartesian — unchanged.        │
+└──────────────────────────────────────────────────────────────────┘
+```

 ---

 ## 8a — Traits class & concepts

-The current code is tightly coupled to `CGAL::Surface_mesh<Point3>`. Phase 8a introduces
-a traits class that separates the mesh type from the algorithm:
+### `ConformalMapTraits` concept
+
+The concept lists the types and operations every Traits model must provide.

 ```cpp
-// TODO(Phase 8a): implement this header
-// include/CGAL/Conformal_map_traits.h
+namespace CGAL {

-template<
-    typename MeshType,      // any CGAL halfedge mesh
-    typename KernelType,    // CGAL kernel
-    typename ScalarType = double
->
-struct Conformal_map_traits {
-    using Mesh   = MeshType;
-    using Kernel = KernelType;
-    using FT     = ScalarType;
-    // ... vertex/edge/face descriptor types
-    // ... property map access
+// Concept (documentation only; no code):
+struct ConformalMapTraits {
+    // Types
+    using Triangle_mesh = ...;            // model of FaceGraph + HalfedgeGraph
+    using FT            = ...;            // typically double
+    using Vertex_descriptor = boost::graph_traits<Triangle_mesh>::vertex_descriptor;
+    using Halfedge_descriptor = ...;
+    using Face_descriptor    = ...;
+
+    // Read access (input geometry)
+    using Vertex_point_map = ...;         // model of ReadablePropertyMap
+                                           //   key:   Vertex_descriptor
+                                           //   value: K::Point_3
+
+    // Read/write access (conformal data)
+    using Lambda_pmap       = ...;        // u_v   (scale factor)         RW
+    using Theta_pmap        = ...;        // Θ_v   (target curvature)     R
+    using Vertex_index_pmap = ...;        // DOF index (−1 = pinned)      RW
+    using Edge_alpha_pmap   = ...;        // α_e   (hyperbolic only)      RW
+    using Face_type_pmap    = ...;        // geometry tag per face        R
+
+    // Optional output
+    using UV_pmap           = ...;        // halfedge → (u, v) ∈ ℝ²       W
+    using Holonomy_pmap     = ...;        // seam edge → ω ∈ ℂ            W
+};
+
+}
+```
+
+### `Default_conformal_map_traits<TM>`
+
+The default model wraps `Surface_mesh` property maps so existing code keeps
+working through the new public API.
+
+```cpp
+template <class TriangleMesh,
+          class K = CGAL::Simple_cartesian<double>>
+struct Default_conformal_map_traits;
+
+// Specialisation for Surface_mesh:
+template <class K>
+struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K> {
+    using Triangle_mesh    = CGAL::Surface_mesh<typename K::Point_3>;
+    using FT               = typename K::FT;
+    using Vertex_point_map = typename Triangle_mesh::Point_property_map;
+    using Lambda_pmap      = typename Triangle_mesh::template Property_map<vertex_descriptor, FT>;
+    // ... etc, using "conformal:lambda" property names
+};
+
+// Generic specialisation for other FaceGraph models will be added in 8a.2.
+```
+
+### Concept-checks
+
+```cpp
+// include/CGAL/Conformal_map_concept_checks.h
+template <class Traits>
+struct Conformal_map_traits_check {
+    static_assert(boost::is_same<...>::value, "Traits::FT must be a floating-point type");
+    static_assert(is_face_graph<Traits::Triangle_mesh>::value);
+    // ...
 };
 ```

-Concept checks will ensure any user-provided mesh satisfies the halfedge mesh concept.
-
 ---

-## 8b — Public header hierarchy
+## 8b — Public CGAL header hierarchy

-A clean public API separate from the internal implementation:
+### User-facing entry
+
+```cpp
+// include/CGAL/Discrete_conformal_map.h
+namespace CGAL {
+
+template <class TriangleMesh, class NamedParameters = parameters::Default_named_parameters>
+bool discrete_conformal_map_euclidean(TriangleMesh& mesh,
+                                       const NamedParameters& np = parameters::default_values());
+
+template <class TriangleMesh, class NamedParameters = ...>
+bool discrete_conformal_map_spherical(TriangleMesh& mesh,
+                                       const NamedParameters& np = ...);
+
+template <class TriangleMesh, class NamedParameters = ...>
+bool discrete_conformal_map_hyperbolic(TriangleMesh& mesh,
+                                        const NamedParameters& np = ...);
+
+} // namespace CGAL
+```
+
+### Named parameter vocabulary
+
+| Parameter | Type | Default | Meaning |
+|---|---|---|---|
+| `vertex_curvature_map(pmap)` | ReadablePropertyMap | `2π` at interior, `π` at boundary | Θᵥ values |
+| `fixed_vertex_pmap(pmap)` | ReadablePropertyMap<bool> | First vertex pinned | Which vertices are pinned (gauge) |
+| `max_iterations(n)` | int | 200 | Newton iteration limit |
+| `gradient_tolerance(eps)` | FT | 1e-10 | `‖G‖∞` threshold |
+| `vertex_index_map(pmap)` | LvaluePropertyMap | DOF auto-assigned | Allows user to override DOF assignment |
+| `output_uv_map(pmap)` | WritablePropertyMap | none | If set, writes UV layout into pmap |
+| `cut_graph(cg)` | `Conformal_cut_graph` | auto-computed | Pre-computed seam edges (mandatory for closed surfaces) |
+| `geom_traits(t)` | model of ConformalMapTraits | `Default_*` | Custom traits |
+
+### Modular headers

 ```
 include/CGAL/
-  Discrete_conformal_map.h        ← single user-facing include
-  Conformal_map_traits.h
-  Conformal_newton_solver.h
-  Conformal_layout.h
-  Conformal_cut_graph.h
-  conformal_map_package.h         ← PackageDescription
+├── Discrete_conformal_map.h          ← user-facing entry (1 include for casual use)
+├── Conformal_map_traits.h            ← concept + Default_conformal_map_traits
+├── Conformal_map_concept_checks.h
+├── Conformal_newton_solver.h         ← standalone Newton (advanced users)
+├── Conformal_layout.h                ← layout + holonomy
+├── Conformal_cut_graph.h             ← orthogonal algorithm
+├── Conformal_period_matrix.h         ← genus-1 τ (conformallab++ unique)
+├── Conformal_holonomy.h              ← Möbius holonomy (conformallab++ unique)
+└── Conformal_map/                    ← CGAL convention: implementation details
+    ├── Default_traits.h
+    ├── Property_map_adapter.h
+    ├── Newton_iteration.h
+    └── Internal_helpers.h
 ```

-All existing `include/*.hpp` headers remain as internal implementation details,
-not part of the public CGAL API.
-
 ---

 ## 8c — CGAL-style documentation

 ```
 doc/Conformal_map/
-  PackageDescription.txt
-  User_manual.md
-  Reference_manual.md
-  fig/                            ← pipeline diagrams, mathematical figures
+├── PackageDescription.txt            ← CGAL Doxygen package file
+├── Conformal_map.txt                 ← Doxygen User_manual
+├── examples.txt                      ← linkable example code
+├── dependencies                       ← textual list
+└── fig/                              ← pipeline diagrams, math figures
 ```

-All public functions and concepts require Doxygen comments following the CGAL style.
+All public functions, concepts, and types require Doxygen.  See **Phase 7.5** (below).

 ---

@@ -79,88 +213,113 @@ All public functions and concepts require Doxygen comments following the CGAL st

 ```
 test/Conformal_map/
-  CMakeLists.txt                  ← CGAL-format, uses find_package(CGAL)
-  test_euclidean_functional.cpp
-  test_newton_solver.cpp
-  ...
+├── CMakeLists.txt                    ← CGAL-format, uses find_package(CGAL)
+├── test_euclidean_traits.cpp         ← traits concept checks
+├── test_polyhedron_3_backend.cpp     ← tests with Polyhedron_3 as mesh
+├── test_named_parameters.cpp
+└── data/                             ← test meshes
 ```

-The existing GTest suite remains. CGAL-format tests are added alongside as a separate
-target, following the CGAL test infrastructure conventions.
+The existing GTest suite at `code/tests/cgal/` remains; CGAL-format tests are
+added alongside as a separate target.  CI runs both.

 ---

 ## 8e — Declarative YAML pipeline

-A lightweight YAML format for reproducible experiments. The CLI accepts
+A lightweight YAML format for reproducible experiments.  CLI accepts
 `--pipeline experiment.yml`; the validator checks `require`/`provide` tokens
 before execution.

-**Full concept & design specification:** [doc/concepts/declarative-pipeline.md](../concepts/declarative-pipeline.md)
-— token vocabulary, validation algorithm, 5 complete examples, implementation plan.
-
-Abbreviated example:
+**Full spec:** [doc/concepts/declarative-pipeline.md](../concepts/declarative-pipeline.md)
+— token vocabulary, validation algorithm, 5 complete examples.

 ```yaml
 pipeline:
  name: flat_torus_period
  geometry: euclidean
-
-  input:
-    source: data/torus.off
-
+  input:  { source: data/torus.off }
  steps:
-    - id: setup
-      unit: setup_euclidean_maps
-      provide: [maps_initialised]
-
-    - id: gauss_bonnet
-      unit: enforce_gauss_bonnet
-      require: [maps_initialised]
-      provide: [gauss_bonnet_satisfied]
-
-    - id: solve
-      unit: newton_euclidean
-      require: [gauss_bonnet_satisfied]
-      params:
-        tol: 1.0e-10
-        max_iter: 200
-      provide: [x_converged]
-
-    - id: cut
-      unit: compute_cut_graph
-      require: [mesh_closed]
-      provide: [cut_graph]
-
-    - id: layout
-      unit: euclidean_layout
-      require: [x_converged, cut_graph]
-      params:
-        normalise: true
-      provide: [layout_uv, holonomy]
-
-    - id: period
-      unit: compute_period_matrix
-      require: [holonomy]
-      provide: [tau]
-
+    - { id: setup,  unit: setup_euclidean_maps,        provide: [maps_initialised] }
+    - { id: gb,     unit: enforce_gauss_bonnet,        require: [maps_initialised], provide: [gauss_bonnet_satisfied] }
+    - { id: solve,  unit: newton_euclidean,            require: [gauss_bonnet_satisfied], provide: [x_converged] }
+    - { id: cut,    unit: compute_cut_graph,           require: [mesh_closed],            provide: [cut_graph] }
+    - { id: layout, unit: euclidean_layout,            require: [x_converged, cut_graph], provide: [layout_uv, holonomy] }
+    - { id: period, unit: compute_period_matrix,       require: [holonomy],               provide: [tau] }
  output:
    layout: out/torus_layout.off
    json:   out/torus_result.json
-    tau:    out/torus_tau.txt
 ```

-The contract table in [contracts.md](contracts.md) defines the valid `require`/`provide`
-token vocabulary.
-
 ---

-## TODO
+## Phase 7.5 — Doxygen infrastructure (prerequisite)

- [ ] Design `Conformal_map_traits.h` interface (8a)
- [ ] Define concept requirements for `MeshType` (8a)
- [ ] Create `include/CGAL/` header skeleton (8b)
- [ ] Write `PackageDescription.txt` (8c)
- [ ] Port GTest tests to CGAL format (8d)
- [ ] Implement YAML validator (8e)
- [ ] CLI: `--pipeline` flag (8e)
+Before any Phase 8 code, the existing API surface must be extractable.
+This is the prerequisite that bridges Phase 7 → Phase 8.
+
+```
+Phase 7.5 — Doxygen infrastructure
+──────────────────────────────────
+  • Doxyfile (CGAL-conform: INPUT=code/include + include/CGAL,
+    EXCLUDE_PATTERNS="* 2.hpp")
+  • doxygen-awesome-css as theme (matches CGAL house style)
+  • CMake target:  cmake --build build --target doc
+  • CI job:  doc-build → publishes to Codeberg Pages or gitea-pages
+  • Extract baseline once → snapshot what is actually exported today
+  • Top-5 central headers (3 functional + conformal_mesh + layout)
+    upgraded to Doxygen comments; the rest follows during Phase 8 implementation
+```
+
+The baseline snapshot doubles as the API-design review tool: before designing
+the public CGAL wrapper, we see exactly which functions, classes and free
+operators exist and need to be wrapped or hidden.
+
+---
+
+## Validation criteria
+
+Phase 8a is "done" when:
+
+1. `cgal.ConformalTraits.Polyhedron_3_works` passes.
+2. `cgal.ConformalTraits.Surface_mesh_default_works` passes — identical results to the legacy API.
+3. The Inversive-Distance functional (Phase 9a) is implementable as the *first* new client of the traits API without architectural changes — no breaking changes to the trait concept.
+4. A user can write `#include <CGAL/Discrete_conformal_map.h>` and call `discrete_conformal_map_euclidean(mesh, parameters::vertex_curvature_map(theta))` against a `Polyhedron_3` and get a valid layout.
+
+If any of these fail, the design is iterated before continuing.
+
+---
+
+## Implementation order
+
+```
+1.  Phase 7.5  Doxygen infrastructure + duplicate cleanup        (½–1 day)
+2.  Phase 8a.1 ConformalMapTraits concept + Default_traits        (2–3 days)
+3.  Phase 8a.2 Generic FaceGraph specialisation                    (2 days)
+4.  Phase 8b.1 Discrete_conformal_map.h entry point                (2 days)
+5.  Phase 8b.2 Layout + cut graph wrappers                         (2 days)
+6.  Phase 9a   Inversive-Distance against new traits = API test    (3–5 days)
+7.  Phase 8c   PackageDescription.txt + User_manual.md             (2 days)
+8.  Phase 8d   CGAL-format test directory                          (1–2 days)
+9.  Phase 8e   YAML pipeline + CLI flag                            (3 days)
+```
+
+**Total budget: 3–4 weeks net work, 6–8 weeks calendar.**
+
+---
+
+## TODO checklist
+
+- [ ] Phase 7.5: Doxyfile + CMake doc target + duplicate cleanup
+- [ ] 8a.1: `ConformalMapTraits` concept header
+- [ ] 8a.1: `Default_conformal_map_traits<Surface_mesh, K>`
+- [ ] 8a.2: Generic `FaceGraph` specialisation
+- [ ] 8a.2: `Conformal_map_concept_checks.h`
+- [ ] 8b.1: `Discrete_conformal_map.h` (3 entry functions)
+- [ ] 8b.1: Named-parameter vocabulary header
+- [ ] 8b.2: `Conformal_layout.h`, `Conformal_cut_graph.h` wrappers
+- [ ] 9a: `inversive_distance_functional.hpp` written against new traits
+- [ ] 8c: `doc/Conformal_map/PackageDescription.txt`
+- [ ] 8c: User_manual + Reference_manual
+- [ ] 8d: `test/Conformal_map/` CGAL-style tests
+- [ ] 8e: YAML validator + CLI `--pipeline` flag