From 736aed30ed1f1e8d4a2404fdfd3d9b14bebce366 Mon Sep 17 00:00:00 2001
From: xmap <16776958+xmap@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:39:47 -0500
Subject: [PATCH] Note where a catalog graduation note's cited evidence now
 lives

Family and Role graduation notes in catalog.yaml cite the specific real
beamlines that justified them ("graduated across Diamond i22, i03,
i11"), and those notes render verbatim onto the public docs/catalog/
pages. Every beamline named in a citation like that moved to the
private xmap/descriptors repo in the last two PRs; only 2-BM has a
descriptor in cora now. The claims are still accurate, just no longer
independently checkable from inside this repo the way they used to be.

Added one line each to catalog.yaml's header and docs/catalog/index.md's
"Source of truth" section: the evidence is real, just not reproduced
here, and checkable on demand in xmap/research (draft) and
xmap/descriptors (promoted).

Verified: mkdocs build --strict clean, catalog.yaml still parses,
apps/api/tests/unit/deployments (110 tests) green.
---
 catalog/catalog.yaml  | 4 ++++
 docs/catalog/index.md | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/catalog/catalog.yaml b/catalog/catalog.yaml
index dbc13687f4a..7b36d8528f7 100644
--- a/catalog/catalog.yaml
+++ b/catalog/catalog.yaml
@@ -13,6 +13,10 @@
 #     equality (the graduated device-class roster), same as roles.
 #   - capabilities, methods, models have no global code seed; this file is
 #     their consolidated source, guarded by the round-trip test.
+#   - a note's cited beamlines (e.g. "graduated across Diamond i22, i03, i11")
+#     are not reproduced here; only 2-BM has a descriptor in this repo. Their
+#     device data is checkable on demand in the private xmap/research (draft)
+#     and xmap/descriptors (promoted) repos.
 #
 # An affordance is a Family property: it declares what the device CAN DO at the
 # physics layer. A Role declares required_affordances (the contract), and a
diff --git a/docs/catalog/index.md b/docs/catalog/index.md
index 42dce8a59a3..fb8c85f9869 100644
--- a/docs/catalog/index.md
+++ b/docs/catalog/index.md
@@ -46,3 +46,5 @@ Some apparent new families are settings axes, not family axes. A high-framerate
 ## Source of truth
 
 Roles and the closed affordance / executor-shape vocabularies are code-defined and validated against the code by drift-guard tests. Families, Capabilities, Methods, and Models are authored in `catalog.yaml`, which supersedes the scenario fixtures as the consolidated source. Until the seeder inversion lands, the code seeds remain authoritative for what CORA actually registers; `catalog.yaml` is the docs projection, kept honest by the round-trip and roles drift-guard tests.
+
+A graduation note (a Family or Role reaching the rule-of-three, "graduated across Diamond i22, i03, i11") cites the real beamlines that justified it, but does not reproduce their device data here: only CORA's one live deployment, 2-BM, has a descriptor in this repo. The beamlines a graduation note names are modeled from public source, checkable on demand, in the private `xmap/research` (draft surveys and candidates) and `xmap/descriptors` (self-validated, promoted) repos.