docs, comments: describe downstream consumers by capability

[transfix]

Summary

Rewords comments, docs and a few test/example strings that referred to downstream consumers by name, so they describe those consumers by capability instead: a WebGL2 app with heavy per-frame overlays, a wasm app that installs the catalog bundles, or an extension layer on top of nav_stats. Profile figures that were not measured on a libcvc gallery demo are now stated qualitatively.

Almost all of it is comment or doc text. The exceptions are a few renamed test literals, one provenance string, and two dropped bundle-autodetect paths in the Austin nav demos. The autodetect change is the only behaviour change, so it has its own commit and can be reverted by itself. Three commits:

1. docs, comments: describe downstream consumers by capability
2. nav demos: drop the sibling-checkout bundle autodetect paths (behaviour change, see below)
3. docs: drop workstation-local paths from the roadmaps

What changed

• nav_stats (docs/NAV_STATS.md, docs/roadmap/NAV-STATS-INTRINSIC-ROADMAP.md, inc/cvc/nav/nav_stats.h, inc/cvc/gl/nav_stats_publish.h, src/cvcGL/nav_stats_publish.cpp)
  • The design is now described as two layers: a domain-neutral core, and an extension seam where a downstream layer keeps its own record, joined by veh_index.
  • The roadmap keeps the libcvc and grl-snam tracks and describes the extension track generically.
  • Track 3b-2 is now marked merged (cvcGL: belief/fog raster bridge for realtime nav-stats viz (Track 3b-2) #426).
  • The arrival-debugging guidance in NAV_STATS.md covers the same per-vehicle signals but no longer depends on a specific scenario.
• External-force comments (drive.h, sim_world.h, material.h, drive.cpp, sim_world.cpp, NAV_VEHICLE.md, NAV_MATERIAL.md): the examples of an ext_force are now neutral.
• Material vocabulary seam (world/surface.h, world/surface.cpp, lsys/interp.h, nav/material_raster.h, world_surface_test.cpp): these comments now describe a consumer keyed on the shared physical-material names.
• material_raster::to_json(): the provenance text now names the 13-class palette. No test or reader parses this field. nav_material_raster_test checks only schema.
• async_lane: the example chroot and channel prefix is now "app", both in the header docs and in async_lane_test. One test case is renamed to ProcessChrootedToAppReceivesCrossThreadHashPosts to match. Nothing else referred to its old name.
• cvcGL (CameraController.cpp, Viewport.h, ViewportManager.h, DrapedLinkNode.h, the cvcgl test headers, nav_city_drive / nav_city_swarm / terrain_lab): same rewording. Per-frame costs are now stated qualitatively.
• Austin nav demo bundle autodetect (nav_city_drive.cpp, nav_city_swarm.cpp, commit 2): the native fallback probes no longer include two dev-checkout paths into a sibling repository. The deps/share/cvc-scenes, share/cvc-scenes and in-tree scenes/ fallbacks remain, and those cover every public layout: the Pages and wasm publish workflows and cvcgl-examples/build-wasm.sh all resolve share/cvc-scenes/austin_south. --bundle and $CVC_NAV_BUNDLE are unchanged.
  • Behaviour change: a native run with no --bundle, started from a directory next to such a checkout, now gets the synthetic city instead of the Austin scene. Pass --bundle or set $CVC_NAV_BUNDLE to get Austin. No CI, wasm or recipe path used the dropped probes.
• Packaging comments (cvcpkg/recipes/{cvcgl,libcvc}/recipe.yaml, .github/workflows/publish-cvcgl-wasm.yml, CMake/cvcConfig.cmake.in): same rewording. A comment-only recipe edit needs no cvc_revision bump:
  • The CI recipe check compares only upstream_version.
  • publish-cvcpkg computes the next revision itself.
  • Packed bundles embed their recipe directory, so the new text reaches the catalog at the next publish of each package.
• Docs (STATE_LIFETIME_AND_ATOMICITY.md, RENDER_PERF_ROADMAP.md, CVCGL-UI-DSL-ROADMAP.md): example names and asset lists are now generic. The DSL roadmap's visible_when, on_change and tiled-layout examples now use the public nav demos' sim.fog state and a generic stats_panel include. Its §12.1 load: example mounts panels/stats_panel.ari as stats, so it matches the tiled-layout example in §3.9. The matching inc/cvc/ariadne/widget.h comments (the mount-scope example and the with_text_color example) use the same generic names.
• Third commit: replaces absolute paths into a developer checkout with repo-relative names in four roadmap docs.

Not in this PR

• The imgui comment in publish-cvcpkg.yml is reworded by open PR publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531, which this branch cannot repeat without a conflict: publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531 also edits the adjacent lines. This branch leaves that file alone. Until publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531 merges, that comment keeps its old wording. See Merge order.
• Generic uses of "RF" / "comm" that are part of the public API or the test fixtures are unchanged. Examples are the rf_material field, the RF slots in the L-system registry, and the includes.rf mount in the Ariadne tests.

Verification

• Tree sweep: no consumer-specific names or out-of-repo checkout paths remain. The only matches are debug-build identifiers (a debug macro in the vendored contour code, debug log lines, a debug flag local) and the publish-cvcpkg.yml comment that open PR publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531 rewords.
• Format: git clang-format (clang-format 18) is clean on the changed lines.
• YAML: the touched YAML files parse with yaml.safe_load.
• Python: bindings/pycvc/pymod_gl/scenes.py passes py_compile.
• CMake configure: CMake 3.31 configures with CVC_BUILD_CVCGL=ON CVC_BUILD_EXAMPLES=ON CVC_BUILD_TESTS=ON.
• Package config: the generated cvcConfig.cmake is byte-identical to the one in a working installed bundle, apart from the reworded comment. A small consumer project's find_package(cvc CONFIG) loads it cleanly.
• Compile: all 26 changed translation units (or the TU that implements each changed header) compile with -fsyntax-only.
• Tests: built and ran async_lane_test, nav_stats_test, nav_material_deploy_test, world_surface_test and nav_material_raster_test (20 + 9 + 14 + 7 + 4 cases), plus ariadne_loader_test and ariadne_runtime_test (160 + 119 cases) after the widget.h comment edit. All pass.
• Nav demos: nav_city_drive and nav_city_swarm build and link cleanly at the branch head (full build, not only -fsyntax-only).
• Merges: the branch merges cleanly with current master, with publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531, and with publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531 + cvcGL: fast-draw low-memory mapper (~2/3 fewer GL calls per frame on WebGL2) + reship cvc.16 #522 + cvcGL tests: GL tests hold one resource lock; shadow_casters D prints its macOS numbers #529 together.

Merge order

• publish-cvcpkg: fix the pycvc-gl opt-in lanes (CUDA -lX11, Windows imgui export) #531: land it with or before this PR. It carries the matching rewording of the imgui comment in publish-cvcpkg.yml, which this PR leaves to it.
• Next publish: the libcvc and cvcgl bundles ship include/cvc/ and lib/cmake/cvc/, and published variants are immutable. Land this before the next libcvc/cvcgl publish so the new variants carry the reworded headers and package config.