docs: restructure documentation into focused files

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

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

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

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

doc/api/cgal-package.md

@@ -0,0 +1,163 @@
+# 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
+
+---
+
+## Goal
+
+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.
+
+---
+
+## 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:
+
+```cpp
+// TODO(Phase 8a): implement this header
+// include/CGAL/Conformal_map_traits.h
+
+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 checks will ensure any user-provided mesh satisfies the halfedge mesh concept.
+
+---
+
+## 8b — Public header hierarchy
+
+A clean public API separate from the internal implementation:
+
+```
+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
+```
+
+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
+```
+
+All public functions and concepts require Doxygen comments following the CGAL style.
+
+---
+
+## 8d — CGAL test format
+
+```
+test/Conformal_map/
+  CMakeLists.txt                  ← CGAL-format, uses find_package(CGAL)
+  test_euclidean_functional.cpp
+  test_newton_solver.cpp
+  ...
+```
+
+The existing GTest suite remains. CGAL-format tests are added alongside as a separate
+target, following the CGAL test infrastructure conventions.
+
+---
+
+## 8e — Declarative YAML pipeline
+
+A lightweight YAML format for reproducible experiments. The CLI accepts
+`--pipeline experiment.yml`; the validator checks `require`/`provide` tokens
+before execution.
+
+Example:
+
+```yaml
+pipeline:
+  name: flat_torus_period
+  geometry: euclidean
+
+  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]
+
+  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
+
+- [ ] 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)