examples: add real conformal-flattening + CGAL-API examples (U1+U2)

Finding-U1 and Finding-U2 from doc/reviewer/usability-audit-2026-05-31.md.

The existing examples (example_euclidean, example_layout, example_hyper_ideal)
all used the "natural theta" pattern which makes x*=0 trivially the
equilibrium — u_v ≈ 0 everywhere, no deformation. A new user following
these examples saw solver output but not conformal geometry.

New: example_flatten.cpp
  - PRIMARY USE CASE: conformally flatten a mesh to the plane
  - Sets Θ_v = 2π for all interior vertices (flat target)
  - Pins boundary vertices (no Gauss-Bonnet check for open meshes)
  - Demonstrates non-trivial u_v (cathead.obj: range ≈ 2.96, 5 Newton iters)
  - Documents the difference from "natural theta" explicitly

New: example_cgal_api.cpp
  - Demonstrates CGAL::discrete_conformal_map_euclidean (Discrete_conformal_map.h)
  - First runnable CGAL public API example; contrast with internal API
  - Documents the "natural theta" default behaviour and explains why u_v=0
  - Explains when to use CGAL API vs internal API

Both examples registered in code/examples/CMakeLists.txt and compile
cleanly with -DWITH_CGAL=ON.

Updated:
  - example_euclidean.cpp: prominent "TESTING CONVENTION" warning
  - example_layout.cpp: same warning on set_natural_theta helper
  - doc/getting-started.md: example_flatten is now the recommended
    "start here" example; note on natural-theta behaviour added

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

code/examples/example_euclidean.cpp

@@ -70,9 +70,17 @@ int main(int argc, char* argv[])
     std::cout << "[example_euclidean] DOFs: " << n << " (1 vertex pinned).\n";
 
     // ── Step 4: natural equilibrium — set theta_v = actual angle sum at x=0 ─
-    //    After this step x* = 0 is the equilibrium (no deformation).
-    //    In a real application you would set theta_v = desired angle (e.g. 2π
-    //    for flat disks, or the cone angles for a cone metric).
+    //
+    // ⚠  TESTING CONVENTION — NOT A REAL CONFORMAL MAP
+    //
+    // "Natural theta" sets Θ_v = actual angle sum at x = 0, so x* = 0 is the
+    // equilibrium by construction.  The solver converges in 0–1 iterations and
+    // u_v ≈ 0 everywhere.  This is useful for testing the solver pipeline but
+    // produces NO conformal deformation.
+    //
+    // For a REAL conformal flattening (the primary use case):
+    //   → see example_flatten.cpp
+    //   which sets Θ_v = 2π (flat interior target) and produces non-trivial u_v.
     {
         std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
         auto G0 = euclidean_gradient(mesh, x0, maps);