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/getting-started.md

@@ -0,0 +1,142 @@
+# Getting Started
+
+## Prerequisites
+
+| Tool | Minimum | Notes |
+|---|---|---|
+| C++ compiler (GCC or Clang) | C++17 | GCC 11+ or Clang 14+ recommended |
+| CMake | 3.20 | |
+| Boost headers | 1.70 | Only for `-DWITH_CGAL_TESTS=ON` or `-DWITH_CGAL=ON` |
+| Wayland/X11 dev headers | — | Only for `-DWITH_CGAL=ON` (viewer) |
+
+All other dependencies (Eigen 3.4, CGAL 6.1.1, libigl 2.6, GLFW 3.4, GTest 1.14)
+are bundled as tarballs in `code/deps/tarballs/` and extracted automatically at CMake
+configure time. No internet access is required at build time (except GTest, fetched via
+`FetchContent` from GitHub).
+
+Install Boost on your system:
+```bash
+# Ubuntu / Debian
+apt install libboost-dev
+
+# macOS
+brew install boost
+```
+
+---
+
+## Clone
+
+```bash
+git clone https://codeberg.org/TMoussa/ConformalLabpp
+cd ConformalLabpp
+```
+
+---
+
+## Build modes
+
+Three modes with increasing dependencies:
+
+### Mode 1 — Fast tests (default, no system dependencies)
+
+Pure-math tests: Clausen functions, hyper-ideal geometry, matrix utilities.
+
+```bash
+cmake -S code -B build
+cmake --build build --target conformallab_tests -j$(nproc)
+ctest --test-dir build --output-on-failure
+```
+
+Expected: **36 tests pass**.
+
+### Mode 2 — CGAL tests, headless (recommended for CI and development)
+
+Full CGAL test suite. Requires Boost headers only — no display, no Wayland, no GLFW.
+
+```bash
+cmake -S code -B build -DWITH_CGAL_TESTS=ON
+cmake --build build --target conformallab_cgal_tests -j$(nproc)
+ctest --test-dir build -R "^cgal\." --output-on-failure
+```
+
+Expected: **158 tests pass, 2 skipped** (intentional stubs for Phase 9 items).
+
+### Mode 3 — Full local build (CLI app + interactive viewer)
+
+Requires Wayland or X11 development packages (`wayland-scanner`, `libx11-dev`, etc.).
+Automatically enables the viewer library (GLFW + libigl).
+
+```bash
+cmake -S code -B build -DWITH_CGAL=ON
+cmake --build build -j$(nproc)
+```
+
+> **Note:** `-DWITH_CGAL=ON` implies `-DWITH_VIEWER=ON`. Do not use this in headless
+> environments — it will fail with `Failed to find wayland-scanner`.
+
+---
+
+## Running a single test
+
+```bash
+# By GTest filter (fastest, full output)
+./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*"
+./build/conformallab_tests       --gtest_filter="Clausen*"
+
+# By CTest regex
+ctest --test-dir build -R "cgal.NewtonSolver" --output-on-failure
+```
+
+All CGAL tests have the prefix `cgal.` in CTest (set in `tests/cgal/CMakeLists.txt`
+via `TEST_PREFIX "cgal."`).
+
+---
+
+## First run — CLI app
+
+After a full build (`-DWITH_CGAL=ON`):
+
+```bash
+# Euclidean conformal layout
+./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
+
+# Spherical layout
+./bin/conformallab_core -i input.off -g spherical -o sphere.off
+
+# Hyperbolic layout (HyperIdeal)
+./bin/conformallab_core -i input.off -g hyper_ideal -o hyperbolic.off
+
+# Show input mesh in interactive viewer
+./bin/conformallab_core -i input.off -s
+
+# All options
+./bin/conformallab_core --help
+```
+
+## Example programs
+
+```bash
+./build/examples/example_layout    [input.off] [layout.off] [result.json]
+./build/examples/example_euclidean [input.off] [output.off]
+./build/examples/example_hyper_ideal [input.off] [output.off]
+./build/examples/example_viewer    [input.off]   # interactive, requires WITH_VIEWER
+```
+
+`example_layout.cpp` is the best starting point — it shows the complete pipeline in ~120 lines.
+
+---
+
+## Rebuilding the CI Docker image
+
+The CI runner is a self-hosted Raspberry Pi (ARM64). After changes to
+`.gitea/docker/Dockerfile.ci-cpp`:
+
+```bash
+docker buildx build \
+  --platform linux/arm64 \
+  -f .gitea/docker/Dockerfile.ci-cpp \
+  -t git.eulernest.eu/conformallab/ci-cpp:latest \
+  --push \
+  .gitea/docker/
+```