doc/reviewer/agenda.md

@@ -36,35 +36,50 @@ Goal: they leave §1 with a mental map of what's where.
 
 **Cue to move on**: when they have no more "where is X?" questions.
 
-## §2 The five questions — 30 min
+## §2 The seven questions — 35 min
 
-Goal: get clear answers to as many of the 5 questions in
-[`questions.md`](questions.md) as possible.  Order matters:
+Goal: get clear answers to as many of the 7 questions in
+[`questions.md`](questions.md) as possible.  Order is chosen so the
+research-relevant questions come *first* (their answer has the largest
+downstream effect on the roadmap):
 
-1. **Q4 first** (CGAL submission strategy — single package vs five).
-   This sets the framing for the rest.  ~5 min.
-2. **Q1** (Phase 9c port-literal vs re-derive).  ~5 min.
-3. **Q2** (Phase 9b-analytic — is the 6× speedup worth ~2 weeks?).
-   May trigger longer math discussion; cap at 10 min and offer to
-   continue async.
-4. **Q5** (GC-1 cross-validation co-authorship).  ~5 min.
-5. **Q3** (CP-Euclidean output_uv_map).  ~5 min.
+1. **Q1 — research-track alignment** (which of 9d.2 / 9f / 10c / 10c′
+   would unblock concrete experiments?).  ~8 min.  Most likely to
+   make them feel the project is genuinely *for* their work, not just
+   adjacent to it.
+2. **Q2 — decorated-DCE API surface** (A/B/C named parameter vs new
+   solver vs property-map auto-detect).  ~7 min.  Sets a concrete
+   shape we can sketch in code right after the meeting.
+3. **Q3 — Phase 9b-analytic** (Schläfli Hessian — implement now?).
+   ~8 min.  May trigger longer math discussion; cap at 10 min and
+   offer to continue async via the derivation note.
+4. **Q5 — GC-1 cross-validation co-authorship**.  ~4 min.  Read the
+   room: if they're warm, push; if cool, leave as "let me follow up
+   in writing".
+5. **Q4 — Phase 9c port-literal vs re-derive** (algorithm choice).
+   ~4 min.  Less critical than Q1–Q3 because we have a viable default
+   either way.
+6. **Q6 — CGAL submission packaging** (one package vs several).
+   ~4 min.  Project-management question; their answer is *advisory*
+   even if it's confident.
 
 **Trap to avoid**: don't relitigate any of the already-made decisions
 (e.g. Surface_mesh as default, Eigen as backend) unless they bring it
 up under "anything you'd say no to".  Move forward, not sideways.
+Keep Q4/Q6 *short* — they are project management; Q1–Q3 are the
+research-flavoured ones their time is best spent on.
 
-## §3 The "no" question — 5 min
+## §3 Q7 — the "no" question — 5 min
 
-Last paragraph of [`questions.md`](questions.md): *"Is there one
-architecture decision where you think 'no, that's the wrong call'?"*
+[`questions.md`](questions.md) §Q7: *"Is there one architecture
+decision where you think 'no, that's the wrong call'?"*
 
 Ask explicitly. Wait.  Don't fill silence.  Negative feedback at this
 phase is the highest-value information of the entire meeting.
 
 ## §4 Wrap-up — 5 min
 
-- **Summarise**: 1 sentence per Q1–Q5 answer.
+- **Summarise**: 1 sentence per Q1–Q7 answer.
 - **Next steps**: 
   - Items they offered to help on (if any) → I'll send a follow-up
     email within 48 h.
@@ -97,12 +112,13 @@ phase is the highest-value information of the entire meeting.
   Reviewer:  ____
   Duration:  ____ min
   
-  Q1 answer:  ____
-  Q2 answer:  ____
-  Q3 answer:  ____
-  Q4 answer:  ____
-  Q5 answer:  ____
-  "No" pointer:  ____
+  Q1 answer (research-track alignment):  ____
+  Q2 answer (decorated-DCE API):         ____
+  Q3 answer (Phase 9b-analytic):         ____
+  Q4 answer (Phase 9c port choice):      ____
+  Q5 answer (GC-1 co-authorship):        ____
+  Q6 answer (CGAL packaging):            ____
+  Q7 "no" pointer:                       ____
   
   Action items:
     [ ] (within 48 h)  ____

doc/reviewer/briefing.md

@@ -33,6 +33,42 @@ The landing page is a hand-curated reviewer hub, not an auto-generated
 index. It links to the Doxygen API, the key markdown documents, and
 shows static quality-gate status.
 
+## Research alignments — where this library could be infrastructure for your work
+
+The current snapshot already contains, or has roadmap entries for,
+the following:
+
+| Your research thread | What this snapshot has | Phase |
+|---|---|---|
+| **Decorated DCE in non-Euclidean geometries** (Bobenko–Lutz 2025, *DCG*) | five DCE solvers + traits scaffolding; non-Euclidean cone extension scoped in research-track with acceptance criteria | **9d.2** RESEARCH (planned) |
+| **Canonical Delaunay tessellations of decorated hyperbolic surfaces** (Lutz 2023, *Geom. Dedicata*; Lutz 2024 PhD thesis) | cut-graph + period matrix + hyperbolic-disk layout as scaffolding; canonical-tessellation algorithm itself outlined | **10c** planned |
+| **Hyperideal polyhedra rigidity** (Bowers–Bowers–Lutz 2026) | HyperIdeal functional + analytic Hessian derivation (805-line LaTeX note) | **9b-analytic** derived; **10c′** KAT planned |
+| **Optimal cone placement / non-Euclidean cone metrics** (Crane et al. 2018) | Cone-singularity port via `ConesUtility` scoped; the *non-Euclidean* extension is the research delta | **9d.1** port + **9d.2** RESEARCH |
+| **Polygon Laplacian on general meshes** (Alexa–Wardetzky 2011; Alexa 2020) | no Java parent; first phase a reviewer can shape at design stage | **9f** RESEARCH (planned) |
+| **Schläfli-based variational machinery** (Rivin–Springborn 1999) | derivation done, implementation gated on your view of whether the ~6× speedup over our block-FD path matters at your mesh sizes | **9b-analytic** ready to implement |
+
+See [`doc/roadmap/research-track.md`](../roadmap/research-track.md)
+for the per-phase acceptance criteria and
+[`doc/roadmap/phases.md`](../roadmap/phases.md) for the porting plan.
+
+## What's new on this snapshot (since the previous publish)
+
+- **+6 new porting-roadmap phases** (9d cones / 9e circle-pattern
+  layout / 10d Koebe circle-domain / 10e quasi-isothermic / 10f Koebe
+  polyhedra / 10g cyclic-symmetry quotients) derived from a full
+  Java-library scan.
+- **+9 literature citations** integrated into the roadmap, all
+  Tier-1/2 in the research line above (Bobenko–Lutz 2024 IMRN;
+  Bobenko–Lutz 2025 DCG; Lutz 2023 Geom. Dedicata; Lutz 2024 PhD;
+  Bowers–Bowers–Lutz 2026; Crane et al. 2018; Alexa–Wardetzky 2011;
+  Alexa 2020; Rivin–Springborn 1999).
+- **Phase 9f** (polygon Laplacian on general meshes) added as
+  RESEARCH-only — no Java parent — so you can influence its design
+  before it exists.
+- **`output_uv_map`** now covers 4 of 5 DCE solvers (Inversive-Distance
+  added; CP-Euclidean deferred to Phase 9c with a clear runtime error
+  rather than silent failure).
+
 ## What's true about this snapshot
 
 | Claim | Concrete evidence |
@@ -47,20 +83,32 @@ shows static quality-gate status.
 
 ## What we want from you
 
-Five concrete questions are in
+Seven concrete questions are in
 [`doc/reviewer/questions.md`](questions.md) — please skim them
 beforehand. They are deliberately scoped: each can be answered with
 "go this way" / "no, go that way" / "either is fine".
 
-The high-stakes ones:
+Ordered by reviewer-value (the first two are the ones your research
+profile makes you best-positioned to answer):
 
-1. **Phase 9c (4g-polygon)** — port the Java implementation literally,
-   or re-derive from Springborn 2020 §5?
-2. **Phase 9b-analytic** — is the ~6× speedup over our current block-FD
-   Hessian (full Schläfli-based analytic) worth ~2 weeks? Working-mesh
-   size that justifies it?
-3. **CGAL submission strategy** — submit as a single package or split
-   the five DCE solvers into separate packages?
+1. **Q1 — Research-track alignment** — of the three RESEARCH-track
+   phases (9d.2 non-Euclidean cones, 9f polygon Laplacian, 10c
+   canonical tessellations + 10c′ Koebe polyhedra), which would
+   unblock concrete experiments you have wanted to run?
+2. **Q2 — Decorated-DCE API surface** — what's the minimum public
+   API for Penner-coordinate / decorated-DCE work?  Named parameter
+   on the existing Euclidean entry, separate `decorated_*` solvers,
+   or per-edge decoration weights via property maps?
+3. **Q3 — Phase 9b-analytic** — is the ~6× speedup over the current
+   block-FD Hessian worth ~2 weeks of implementation, at the mesh
+   sizes you typically work with?
+4. **Q4 — Phase 9c (4g-polygon)** — port the Java implementation
+   literally, or re-derive from Springborn 2020 §5?
+5. **Q5 — geometry-central cross-validation (GC-1)** — would you
+   be interested in co-authoring a Newton-vs-Ptolemy-flips comparison?
+6. **Q6 — CGAL submission strategy** — one package or several?
+7. **Q7 — The "no" question** — looking at our 12 architecture
+   decisions, is there one you would push back on?
 
 ## What's deliberately deferred (so we can discuss with you first)
 

doc/reviewer/questions.md

@@ -4,13 +4,111 @@
 > "do A" / "do B" / "either is fine" is a sufficient answer; deeper
 > dives are welcome but not required.
 
-These are the five decisions that would benefit most from a second
-opinion.  Items 1-3 affect the porting roadmap directly; 4-5 affect
-the long-term goal (CGAL submission).
+These are the seven items that would benefit most from a second opinion.
+
+* **Q1–Q2** are research-track questions — your active publication line
+  in **decorated DCE / Penner coordinates / canonical tessellations /
+  hyperideal polyhedra** makes you the best-positioned reader for them.
+  They ask whether conformallab++ could become *infrastructure for your
+  own future numerical experiments*, and what the minimum API surface
+  would be.
+* **Q3–Q4** are porting decisions in our roadmap where your view of the
+  underlying mathematics would change the answer.
+* **Q5–Q6** are project-management questions where peer input is
+  valuable but not blocking.
+* **Q7** is an open invitation to push back on any architecture
+  decision you think we got wrong.
 
 ---
 
-## Q1 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive?
+## Q1 — Research-track alignment: which RESEARCH phase would unblock concrete experiments you want to run?
+
+Three phases in `doc/roadmap/research-track.md` are research-only
+(no Java parent, no immediate user request), but each maps onto a
+recognised live research line and each has explicit acceptance
+criteria:
+
+| Phase | What it would add | Closest published line |
+|---|---|---|
+| **9d.2** | Decorated DCE in non-Euclidean (spherical + hyperbolic) geometries; Penner coordinates as first-class DOF; automatic cone placement for non-Euclidean targets | Decorated DCE in non-Euclidean geometries (2025, *Discrete Comput. Geom.*); optimal cone singularities for Euclidean flattening (2018, *SIGGRAPH*) |
+| **9f** | Discrete Laplace–Beltrami on **non-triangular** polygonal meshes (virtual-node / generalised cotangent), making DCE work on quad / Voronoi tessellations without re-triangulation | Polygon Laplacians (2011 *SIGGRAPH* + 2020 *TOG*) |
+| **10c + 10c′** | Canonical Delaunay tessellations of decorated hyperbolic surfaces; Koebe polyhedron realisation (KAT) with rigidity-aware Newton | Canonical tessellations of decorated hyperbolic surfaces (2023, *Geom. Dedicata*); rigidity of circle / hyperideal polyhedra (2026, preprint) |
+
+**Question A:** which of these (if any) would unblock concrete
+numerical experiments you have wanted to run but currently have no
+reference implementation for?
+
+**Question B:** for the one(s) you would use, would you want us to
+target the *next* milestone after Phase 9c, or is there a different
+order that would serve your research better?
+
+Context:
+[`research-track.md`](../roadmap/research-track.md) §"Non-Euclidean
+cone extensions" and §"Polygon Laplacian"; the integrated literature
+sits in [`math/references.md`](../math/references.md).
+
+---
+
+## Q2 — Decorated-DCE API surface: what would you need from us to use the library for Penner-coordinate work?
+
+If you wanted to compute the variational energy + Newton update for
+**decorated discrete conformal equivalence** (vertex `u`-DOFs plus
+per-edge Penner decoration `λ_e`), the existing five-solver scaffold
+gives us three plausible API directions:
+
+- **(A) Named parameter on the existing Euclidean entry.**
+  `discrete_conformal_map_euclidean(mesh, parameters::penner_decoration_map(λ))`.
+  Smallest change; preserves the single-entry-per-geometry pattern;
+  hides the decoration as "just another property map".
+- **(B) Separate `decorated_*` solver headers.**
+  New entry `CGAL::decorated_discrete_conformal_map_{euclidean,
+  spherical, hyperbolic}` with its own `Default_decorated_*_traits`.
+  Cleaner separation of concerns; mirrors the way CP-Euclidean and
+  Inversive-Distance are their own headers.
+- **(C) Per-edge decoration as just another property map** that the
+  existing solvers consume when present (zero-decoration = current
+  behaviour by construction).  Minimal API expansion; risk of
+  surprising convergence behaviour when decoration is silently zero
+  vs explicitly zero.
+
+**Question:** which of A / B / C matches what you would expect from
+a CGAL-style header?  If "none of the above" — what would you write
+in our place?
+
+Context: Phase 9d.2 in
+[`research-track.md`](../roadmap/research-track.md); the existing
+named-parameter helpers in
+[`code/include/CGAL/Conformal_map/internal/parameters.h`](../../code/include/CGAL/Conformal_map/internal/parameters.h).
+
+---
+
+## Q3 — Phase 9b-analytic Hessian: implement now or later?
+
+We have:
+
+- **Done**: per-face block-FD Hessian (96× faster than naive full-FD).
+- **Derived but not implemented**: analytic Hessian via the Schläfli
+  identity, expected ~6× further speedup over block-FD.
+- **Derivation document**:
+  [`doc/math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
+  (805 lines, all sign pitfalls covered, references Schläfli 1858,
+  Milnor 1982, Vinberg 1993, Cho–Kim 1999, Glickenstein 2011,
+  Springborn 2020, Rivin–Springborn 1999).
+
+**Question:**
+
+- At what mesh size does the ~6× become user-visible enough to
+  justify ~2 weeks of implementation work, given the typical sizes
+  in your work?
+- Are you aware of subtleties in the Schläfli-based derivation our
+  document might be missing?
+
+If the answer is "implement", we'd target Phase 9b-analytic right
+after the meeting.
+
+---
+
+## Q4 — Phase 9c (4g-polygon canonical form): port-literal vs re-derive?
 
 The Java original has two utility classes:
 
@@ -38,48 +136,30 @@ Context: `doc/roadmap/phases.md` §Phase 9c, `doc/roadmap/porting-status.md`.
 
 ---
 
-## Q2 — Phase 9b-analytic Hessian: implement now or later?
+## Q5 — geometry-central cross-validation (GC-1): would you co-author?
 
-We have:
+Two libraries solve the DCE problem from opposite algorithmic
+directions:
 
-- **Done**: per-face block-FD Hessian (96× faster than naive full-FD).
-- **Derived but not implemented**: analytic Hessian via the Schläfli
-  identity, expected ~6× further speedup over block-FD.
-- **Derivation document**:
-  [`doc/math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md)
-  (805 lines, all sign pitfalls covered, references Schläfli 1858,
-  Milnor 1982, Vinberg 1993, Cho-Kim 1999, Glickenstein 2011,
-  Springborn 2020).
+- **conformallab++**: Newton on the fixed mesh (no intrinsic flips).
+- **geometry-central**: Ptolemy flips on an intrinsic triangulation.
 
-**Question**:
+An automated comparison on common meshes would be:
 
-- At what mesh size does the ~6× become user-visible enough to
-  justify ~2 weeks of implementation work?
-- Are you aware of subtleties in the Schläfli-based derivation our
-  document might be missing?
+- A short paper (the disagreement modes are interesting in their own
+  right and connect to the decorated-DCE framework via canonical
+  tessellation invariants).
+- A confidence-building tool for both libraries.
+- ~3 days of plumbing (CMake-fetch geometry-central, write 5 common
+  test meshes, compare `u_per_vertex` to a tolerance).
 
-If the answer is "implement", we'd target Phase 9b-analytic right
-after the meeting.
+**Question:** would you be interested in co-authoring such a comparison
+note (with us doing the implementation)?  Or do you know someone in a
+neighbouring group who would be a natural co-author?
 
 ---
 
-## Q3 — `output_uv_map` for CP-Euclidean: build now or defer?
-
-For CP-Euclidean (face-based DOFs, BPS 2010) the natural output is a
-**per-face circle packing** in ℝ² — not a per-vertex `Point_2` map
-the way the other four DCE entries produce.
-
-Today the entry throws `std::runtime_error` with a helpful pointer if
-the caller passes `output_uv_map(...)`.  A faithful layout would be
-~150 lines implementing BPS-2010 §6.
-
-**Question**: do *your* CP-Euclidean use cases need a UV-like output,
-or are the face circle radii themselves the deliverable?  The answer
-shapes whether Phase 9c gets it now or later.
-
----
-
-## Q4 — CGAL submission strategy: one package or five?
+## Q6 — CGAL submission strategy: one package or several?
 
 For the long-term CGAL submission:
 
@@ -94,34 +174,31 @@ Today the code is structured per-functional (Strategy C — see
 [`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md) §7).
 Either submission packaging is achievable from this base.
 
-**Question**: what's the CGAL editor convention for related-but-distinct
-algorithms — Polygon_mesh_processing as one example (one package, many
-algorithms), vs Triangulation_2/Triangulation_3/Periodic_*/Hyperbolic_*
-as another (multiple packages for related algorithms)?
+**Question:** what's the CGAL editor convention for related-but-distinct
+algorithms — `Polygon_mesh_processing` as one example (one package, many
+algorithms), vs `Triangulation_2`/`Triangulation_3`/`Periodic_*`/
+`Hyperbolic_*` as another (multiple packages for related algorithms)?
 
 ---
 
-## Q5 — geometry-central cross-validation (GC-1)
+## Q7 — The "no" question (this is the highest-value answer)
 
-Two libraries solve the DCE problem from opposite algorithmic
-directions:
+Looking at any of the 12 architecture decisions in
+[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md), is
+there one where you think *"no, that's the wrong call, here's why"*?
 
-- **conformallab++**: Newton on the fixed mesh (no intrinsic flips).
-- **geometry-central**: Ptolemy flips on an intrinsic triangulation.
+This is a deliberately blunt question because positive feedback is
+nice but negative feedback is rarer and more valuable.  The 🔴
+load-bearing decisions are the most consequential to revisit, because
+waiting longer makes them more expensive:
 
-An automated comparison on common meshes would be:
+- **#1** `CGAL::Surface_mesh<P>` as default mesh
+- **#3** header-only, no compiled library
+- **#6** Eigen as linear-algebra back-end
+- **#11** MIT license (only relevant if it conflicts with a CGAL-
+  submission constraint)
 
-- A nice paper (the disagreement modes are interesting in their own
-  right).
-- A confidence-building tool for both libraries (we benefit from
-  catching corner-case bugs, they benefit from cross-validation
-  against a Newton baseline).
-- ~3 days of plumbing (CMake-fetch geometry-central, write 5 common
-  test meshes, compare `u_per_vertex` to a tolerance).
-
-**Question**: would you be interested in co-authoring such a comparison
-note (with us doing the implementation)?  Or do you know someone in
-the Crane group who would?
+"No" is the most useful answer.
 
 ---
 
@@ -133,21 +210,24 @@ the Crane group who would?
   [`code/deps/THIRD-PARTY-LICENSES.md`](../../code/deps/THIRD-PARTY-LICENSES.md)).
 - Build system (CMake ≥ 3.20, header-only consumer + optional
   CLI/Viewer).
+- Documentation tooling (Doxygen with auto-generated `headers.md`).
 
-These are conscious decisions matched to CGAL conventions and aren't
-load-bearing in the sense that revisiting them later is cheap.
+These are conscious decisions matched to CGAL conventions and are
+not load-bearing in the sense that revisiting them later is cheap.
 
 ---
 
-## What I'm hoping you'll say "no" to
+## After the meeting — would you collaborate?
 
-This is a deliberately blunt question because positive feedback is
-nice but negative feedback is rarer and more valuable:
+A separate "after the meeting" conversation, but flagged here so it
+does not surprise you on the day:
 
-**Looking at any of the 12 architecture decisions in
-[`locked-vs-flexible.md`](../architecture/locked-vs-flexible.md), is
-there one where you think "no, that's the wrong call, here's why"?**
-
-The 🔴 load-bearing decisions are the most consequential to revisit,
-because waiting longer makes them more expensive.  No is the most
-useful answer.
+- **Acknowledgement** in any future CGAL submission / paper would be
+  the default, and we would ask first.
+- **Co-authorship** on Q5 (the GC-1 cross-validation note) is on the
+  table if you said yes there.
+- **Periodic update cadence** (quarterly? per-milestone?) — open
+  question, no expectation.
+- **Pull requests** from your side are welcome and reviewable on the
+  Codeberg repo.  We would not expect them — but we would not turn
+  them away either.