docs, comments: describe downstream consumers by capability

[transfix]

Summary

Docs, docstrings and comments now describe GRL-SNAM's extension seams by what they do, not by which project uses them, and the repo no longer carries workstation-local paths. Runtime code is unchanged apart from one value: the material-raster provenance string now matches the C++ generator byte for byte. Two test literals are renamed. The weight payloads' metadata now names the training SDF by a scene-relative path. The weights themselves do not change.

Companion to transfix/libcvc#538, which made the same change on the C++ side.

Changes

1. docs, comments: describe downstream consumers by capability

• Reworded the extension seams by capability: the generic ext_force_fn hook (sdf_nav, nav), the route_cost_fn seam (scenario), and the second layer of the nav-stats design. That second layer is where a downstream extension adds its own domain-specific metrics, keyed by vehicle index. The base scorecard, selection and scorecard_eval are now described as domain-neutral.
• The scorecard reader's docstrings and comments (scorecard, selection, tests/test_scorecard.py) now name the C++ producer as cvc::nav::nav_scorecard::to_json(). Its keys match NavScorecard.to_dict field for field.
• material_palette: documented as positional with the public cvc::nav material_id enum (inc/cvc/nav/material_raster.h) and kNumMaterials. Its scorecard cross-reference now names cvc::nav::nav_scorecard.
• material_raster provenance parity: to_material_json()["provenance"] now equals the C++ cvc::nav::material_raster::to_json value exactly:
  scene land cover (cvc::nav material_raster: masks if present, else satellite); ids = the 13-class material palette.
  Checked by parsing the C++ string literals out of src/cvc/nav/material_raster.cpp on docs, comments: describe downstream consumers by capability transfix/libcvc#538. The {"schema":…,"provenance":…, prefix the two generators emit is byte-identical. The rest of the document is not, because the two writers format floats differently (C++ writes 0 and 2048.12 where Python writes 0.0 and 2048.125). The comment now says this.
• tests/test_scorecard.py: two literal changes.
  • The partial-reader test now uses a generic extension sub-object ("ext": {"extra_metric": …}) as the key it ignores, and is renamed test_scorecard_reader_tolerates_partial_and_ignores_extension. Its assertions are unchanged.
  • In test_scorecard_json_keys, the absent-key guard changes from assert "rf" not in d to assert "ext" not in d. to_dict emits neither key, so the guard is as weak as before. A follow-up should assert the exact base key set instead.
• grl-snam-weights: PROVENANCE.md and the recipe description now say "geometry only". PROVENANCE.md ships under share/, so cvc_revision goes from 1 to 2, as the recipe's own comment requires.
• The scope note in pypi-publishing-roadmap.md and the .cvcnav home question in CVCNAV_CPP_PORT_ROADMAP.md are simplified the same way.
• Smaller doc wording fixes in the README, NAV_STATS.md, VEHICLE_REFINEMENTS.md, the cvc::nav guide, selftest, austin and planner.

2. docs: drop workstation-local paths from the roadmaps

• In CVCNAV_CPP_PORT_ROADMAP.md, CVCNAV_CUDA_ASSESSMENT.md and CVCNAV_MATERIAL_PORT_ROADMAP.md, absolute paths into one developer's checkouts are replaced with paths relative to the libcvc root or to this repo.

3. docs: regenerate the cvc::nav guide and quickstart PDFs

• docs/cvc-nav-and-grl-snam-guide.pdf was re-rendered from the updated Markdown with the same python-markdown + WeasyPrint 70.0 pipeline and stylesheet that made the original. Re-rendering the previous Markdown with that pipeline reproduces the committed PDF pixel for pixel. The only text change is the weights note in section 8, and the page count is still 18.
• In both PDFs, the cross-links to the other doc's Markdown were file:// URIs into a local checkout, because WeasyPrint resolved the relative links against the render directory. Both PDFs are now rendered with https://github.com/CVC-Lab/GRL-SNAM/blob/main/docs/ as the base URL, so those links point at the copies on GitHub. The quickstart Markdown is unchanged, and its PDF renders identically page for page; only its link targets differ.

4. grl-snam-weights: record the training SDF by a scene-relative path

• coef_sdf.pt's meta["sdf_npz"] and the .cvcnav provenance trailer held an absolute path into the trainer's checkout. tools/train.py stores os.path.abspath(sdf_npz), and the trailer is json.dumps of the same meta. Both now say austin_south/nav_sdf.npz. The .cvcnav was rewritten with coef_export.write_coef_mlp from the edited meta.
• The weights are unchanged. Every checkpoint tensor is equal and its storage records are byte-identical. The .cvcnav blob is byte-identical up to the meta trailer: same header, arch_hash and weight floats. cvc_revision 2 from change 1 covers the byte change, and PROVENANCE.md notes it.

Behaviour

• ast.dump of every touched .py file was compared old vs new:
  • All files except two are identical, or differ only in docstrings.
  • material_raster.py differs only in the provenance constant.
  • test_scorecard.py differs only in the renamed test and its ignored-key literals (now "ext"/"extra_metric").
  • With those literals mapped, both trees are structurally identical.
• publish-weights-cvc.yml parses to the same data as before (comment-only change). recipe.yaml differs only in cvc_revision and description.

Testing

• Full suite on Python 3.12 / torch 2.14 CPU without pycvc: 384 passed, 27 skipped, the same as main. The skip set is identical: the native parity tests skip without pycvc.
• black --check (26.5.1) and ruff check pass on the touched files. py_compile passes on the touched files.
• Path scan over the binaries as well as the text: strings over every tracked binary, the .pt pickle, the .cvcnav trailer, and the PDFs' link annotations and decompressed streams. The only link targets left in the PDFs are https://cvcpkg.org/guide, https://transfix.github.io/libcvc/ and the two GitHub doc links.

After merge

• Run publish-weights-cvc with dry_run=false so the published grl-snam-weights gets the updated PROVENANCE.md, description and metadata. The workflow packs with --bump.

Follow-ups (not in this PR)

• tools/train.py still records os.path.abspath(sdf_npz) in new checkpoints. It should store a path that does not depend on the training machine before the next weights are trained.
• test_scorecard_json_keys: assert the exact base key set.