Clarify builder API asymmetry

[charles-turner-bot]

Summary

• keep the public builder surface explicitly intake-esm-catalog-first for now
• document the virtual-vs-real asymmetry rather than freezing premature alternate-source entrypoints
• clarify the two builder roles in the README and API reference

Notes

• GroupEntry remains an internal seam for future experimentation
• a virtual builder alternate-source API would likely need source paths plus parser/provenance context
• a real-data builder dataset convenience path may still make sense later, but this PR intentionally does not add it yet

Testing

• pixi run python -m pytest -q tests/test_source_build.py -k 'group_entry_from_esm_group or group_entry_requirements or test_iter_esm_groups'

Closes #76

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.37%. Comparing base (1fc1e11) to head (87ba518).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #82   +/-   ##
=======================================
  Coverage   95.37%   95.37%           
=======================================
  Files           9        9           
  Lines         713      713           
=======================================
  Hits          680      680           
  Misses         33       33           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.