Document the website integration / results pipeline

[mmcdermott]

Background

The end-to-end pipeline that takes a benchmark result from a contributor and surfaces it on the MEDS website involves several moving pieces:

• An issue template (.github/ISSUE_TEMPLATE/benchmark-result.yml) drives result submission
• upload_benchmark_result.yaml validates the JSON, commits to _results branch, closes the issue
• aggregate_benchmark_results.yaml runs _web/scripts/aggregate_results.py on push to _results
• _web/entities/*.json (manually maintained, see We need to export a code-endpoint releasing the information about supported datasets in a friendly format. #186/We need to export a code-endpoint releasing the information about supported tasks in a friendly format. #187/We need to export a code-endpoint releasing the information about supported models in a friendly format. #188) provides the dataset/task/model catalog
• The website fetches _web/results/all_results.json and _web/entities/*.json at runtime

This is documented nowhere outside individual workflow YAML files. New contributors and maintainers can't trace what happens after an issue is filed, and several integration points have already broken silently (#238).

What needs to be done

Add docs (docs/website-integration.md or similar) covering:

1. Architecture diagram: producers (CI workflows, issue handlers) → consumers (_results / _web orphan branches) → website fetch path.
2. Branches:
   • main — code, tasks, datasets, models
   • _results — orphan branch with _results/<issue#>/result.json per benchmark submission
   • _web — orphan branch with entities/*.json (manifests) and results/all_results.json (aggregated leaderboard)
3. Workflows and what triggers each, including known limitations (e.g., GITHUB_TOKEN not triggering downstream workflows — see aggregate benchmark results workflow is not triggering on new result submissions #238).
4. Manual interventions: when and how to run workflow_dispatch (currently the only working way to refresh _web/results/all_results.json until aggregate benchmark results workflow is not triggering on new result submissions #238 is fixed).
5. Schema docs: shape of result.json, of the entities files, and how the website consumes them. Link to website-side parsers (src/lib/MEDS-DEV/{load,entities,parse_tree}.ts).
6. Adding a new dataset/task/model: the contributor checklist, including what to expect on the website afterward.

Acceptance criteria

• A new contributor can read the doc and understand "I labeled my issue, why isn't it on the website?" without grepping workflows.
• A maintainer can read the doc and know how to manually unblock the pipeline if a workflow fails.

Related

• Cross-cuts aggregate benchmark results workflow is not triggering on new result submissions #238 (auto-aggregation), We need to export a code-endpoint releasing the information about supported datasets in a friendly format. #186/We need to export a code-endpoint releasing the information about supported tasks in a friendly format. #187/We need to export a code-endpoint releasing the information about supported models in a friendly format. #188 (entity manifests), Promote web tooling (collate_entities, aggregate_results) into the package #280/Add workflow to auto-regenerate _web entity manifests on source changes #281 (proposed automation work).