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_layout.cpp

@@ -37,6 +37,11 @@
 using namespace conformallab;
 
 // ── Helper: natural target angles so x* = 0 is the equilibrium ───────────────
+//
+// ⚠  TESTING CONVENTION — NOT A REAL CONFORMAL MAP
+// Natural theta sets Θ_v = actual angle sum at x=0, making x* = 0 trivially
+// the equilibrium (u_v ≈ 0, no deformation).  For real conformal flattening,
+// see example_flatten.cpp which uses Θ_v = 2π (flat interior target).
 static void set_natural_theta(ConformalMesh& mesh, EuclideanMaps& maps, int n)
 {
     std::vector<double> x0(static_cast<std::size_t>(n), 0.0);