diff --git a/doc/reviewer/usability-audit-2026-05-31.md b/doc/reviewer/usability-audit-2026-05-31.md index d66a12a..df760e6 100644 --- a/doc/reviewer/usability-audit-2026-05-31.md +++ b/doc/reviewer/usability-audit-2026-05-31.md @@ -434,6 +434,104 @@ auto& p = layout.uv[v.idx()]; --- +## FINDING-U10 — 🟠 MISSING: CLI parameter reference not in README or getting-started + +### Location +- `README.md` (has CLI examples but no parameter table) +- `doc/getting-started.md` (same) +- `code/src/apps/v0/conformallab_cli.cpp` lines 333–340 (source of truth) + +### Problem + +The CLI app (`conformallab_core`) is the primary non-programmatic entry point +for the library. The README shows a few usage examples but no parameter +reference. A user running `--help` gets CLI11's auto-generated output, but +that output is not reproduced anywhere in the documentation. + +Current parameters (from `conformallab_cli.cpp`): + +| Flag | Default | Description | +|------|---------|-------------| +| `-i / --input` | *required* | Input mesh (OFF / OBJ / PLY) | +| `-o / --output` | *(none)* | Output layout OFF file | +| `-j / --json` | *(none)* | Serialise result to JSON | +| `-x / --xml` | *(none)* | Serialise result to XML | +| `-g / --geometry` | `euclidean` | Target geometry: `euclidean` \| `spherical` \| `hyper_ideal` | +| `-s / --show` | `false` | Open input mesh in interactive viewer | +| `-v / --verbose` | `false` | Print topology / DOF stats | + +### Fix + +Add a concise parameter table to `doc/getting-started.md` in the +"First run — CLI app" section. The README already shows the most common +invocations; the table can live in getting-started to avoid README bloat. + +### Acceptance criteria +- [ ] `doc/getting-started.md` has a parameter table matching the source +- [ ] Each flag has a one-line description and notes the default +- [ ] Cross-reference to `--help` for the canonical up-to-date list + +--- + +## FINDING-U11 — 🟠 ROADMAP: CLI missing three useful parameters + two models + +### Location +`code/src/apps/v0/conformallab_cli.cpp` + +### Problem (not a bug — a gap for a future session to fill) + +**Missing solver-tuning parameters** (low effort, high value): + +The Newton tolerance and iteration limit are hardcoded at their defaults +(`tol=1e-8`, `max_iter=200`). Any user who wants to solve a stiff mesh +more carefully or stop early has to recompile. + +```bash +# Not yet possible: +./conformallab_core -i hard_mesh.off -g euclidean --tol 1e-12 --max-iter 1000 +./conformallab_core -i quick_check.off --tol 1e-4 --max-iter 20 +``` + +**Missing geometry modes** (medium effort): + +The two Phase-9a functionals are not reachable from the CLI at all: + +```bash +# Not yet possible — needs run_cp_euclidean() + run_inversive_distance() helpers: +./conformallab_core -i mesh.off -g cp_euclidean +./conformallab_core -i mesh.off -g inversive_distance +``` + +CP-Euclidean (`Discrete_circle_packing.h`) and Inversive-Distance +(`Discrete_inversive_distance.h`) are fully implemented in the library and +exposed via the CGAL public API, but a CLI user cannot reach them. + +### Suggested implementation (for a future session) + +1. **`--tol ` and `--max-iter `:** one `app.add_option` each, + thread through all three `run_*` functions. ~15 lines. + +2. **`-g cp_euclidean` and `-g inversive_distance`:** add two new + `run_cp_euclidean()` / `run_inversive_distance()` helpers following + the existing `run_euclidean()` pattern. ~60 lines each. Add to the + `-g` `CLI::IsMember` list. Register the two new geometry strings in + the dispatch block. + +3. **Update README + getting-started** to list all five geometry modes. + +### Effort estimate +- `--tol` + `--max-iter`: ~30 min +- Phase-9a CLI exposure: ~2 hours (mostly copy-paste + adaptation) +- Tests: add two CLI smoke tests (geometry converges on tetrahedron) + +### Acceptance criteria (when implemented) +- [ ] `--tol` and `--max-iter` are accepted and forwarded to all three/five solvers +- [ ] `./conformallab_core -i mesh.off -g cp_euclidean -o out.off` works +- [ ] `./conformallab_core -i mesh.off -g inversive_distance -o out.off` works +- [ ] `--help` output lists all five geometry modes + +--- + ## Summary table | ID | File | Type | Severity | Status | @@ -447,9 +545,12 @@ auto& p = layout.uv[v.idx()]; | U7 | `getting-started.md` | Missing | 🟠 Minor | 🟡 Open | | U8 | `README.md` | Missing | 🟠 Minor | 🟡 Open | | U9 | `layout.hpp` + example | Missing | 🟠 Minor | 🟡 Open | +| U10 | `getting-started.md` | Missing | 🟠 Minor | 🟡 Open | +| U11 | `conformallab_cli.cpp` | Roadmap | 🟠 Minor | 🟡 Open | **Priority order for fixing:** -1. U1 + U2 (new examples — most impactful for new users) +1. ~~U1 + U2~~ ✅ done 2. U3 (correctness — contracts.md wrong after Finding-B) 3. U4 + U5 + U6 (stale content — quick fixes) -4. U7 + U8 + U9 (missing docs — minor) +4. U7 + U8 + U9 + U10 (missing docs — minor) +5. U11 (roadmap — CLI extensions, not urgent)