# Graphics bindings and operator acceptance checklist

This guide describes the files shipped in this historical package. The website is
an illustrative preview; a tested XPression scene is still required for acceptance.
The live API behavior described in API_CONTRACT.md requires separate verification.

## Files and reporting month

Each cohort folder (bc-mlas/ or bc-mps/) contains:

| File | JSON array | Purpose |
| --- | --- | --- |
| member-name-graphics.json | lower_third | Flat name-and-one-stat rows |
| member-topic-bars.json | lbar | Flat six-topic rows with ranks and bar scales |
| members.json | members | Selected roster, structured names and graph-ID mapping |

Graphics have CSV and XML equivalents with the same basename. Root graphics use
May 2026. For any reporting month use COHORT/months/YYYY-MM/member-name-graphics.json
or COHORT/months/YYYY-MM/member-topic-bars.json, with .csv or .xml as needed.
The website defaults to May and updates graphic download links with the month.

## Select a member by key

Never bind a saved selection to an array position. The identifiers have different
purposes:

| Field | Location | Meaning |
| --- | --- | --- |
| id | Graphic row | Package roster key, such as bc-mla-12; joins members.json.member_id |
| member_key | Graphic row | Source-derived selection key; not an approved permanent public ID |
| member_id | members.json | The package roster key shared with graphic id |
| graph_id | members.json | Numeric Person lookup ID for the live API |
| operator_key | Evidence summary's members array | Readable name key with a hash suffix; absent from lean graphics |

For a live API lookup, find the members.json row where member_id equals the selected
graphic id, then use its graph_id. Do not pass bc-mla-12 or a source-derived member_key
as the numeric legislator ID. members.json does not contain member_key; use the
selected graphic row for that field.

The summaries at COHORT/evidence/MEMBER_ID/YYYY-MM/summary.json include operator_key,
member_key_basis and review_roster_key for inspection. Their members array contains
one member. The exact DataLinq key-selection configuration must be confirmed by an
operator in the installed Ross version. Missing keys must produce an explicit
unavailable state; never silently select another person. Keep API credentials out
of published files and URLs.

## Lower third

Use member-name-graphics.json -> lower_third (or its CSV/XML equivalent).
Bind name_display, role_title, district_short, party_short and party_color. Bind
top_1_label_short, top_1_value_text and top_1_color only when activity_eligible is
true. Otherwise hide the statistic and display fallback_text. Keep period,
metric_label and historical/sample context visible. Show review_status in the
producer preview; eligibility does not mean editorial approval.

The lean lower third shows one statistic and does not expose a tie flag. Inspect
the same member/month's L-bar top_1_rank_text before describing its first topic as
an outright leader. T-prefixed ranks indicate ties. The top_1_topic_id in that L-bar
identifies the Concept behind the lower-third statistic; analysis_id should match.

role_title currently supplies only MLA or MP. Cabinet/critic titles need a verified,
dated source. name_first and name_last are in members.json; display formatting is
not independently approved. headshot_url references a stored database asset, not a
redistributed image file; the offline reviewer renders cached portraits. Availability,
rights and template fallback behavior still need acceptance.

## L-bar and comparison defaults

Use member-topic-bars.json -> lbar. Bind top_N_label_short, top_N_value_text,
top_N_color, top_N_visible and top_N_rank_text for slots 1 through 6.

The website defaults to top_N_bar_cohort: all members in the same selected cohort
and month use the same denominator, the highest single-topic count. Read
cohort_scope, cohort_size and cohort_bar_denominator. Compare like cohorts and
months. The alternative top_N_bar_member scales to the individual member's largest
topic and is suitable for a labelled member profile, not comparing bar widths
between members.

Ranks compare topics within one member, not members against peers. T1 means a tie
for that member's highest topic count; competition ranks may skip numbers after
ties. Never label either scaled bar as share of attention. top_N_share_recorded is
a separate percentage of all captured contributions by that member in the month,
including unclassified records in its denominator. Concepts overlap, so these shares
can sum above 100%. They are not speaking time or effectiveness. The website preview
shows counts and scaled bars, not this share metric or peer rankings.

The demo displays every positive topic count and labels counts below 3 as Small sample. Templates must honor activity_eligible and top_N_visible. Eligibility is not editorial approval; proposed colours and riding aliases still require acceptance.

## Evidence and taxonomy

Open COHORT/evidence/MEMBER_ID/YYYY-MM/summary.json for the captured overview.
Evidence pages start at page-0000.json; follow evidence.next_offset, padded to four
digits, for subsequent filenames (for example page-0050.json). Keep analysis_id
consistent across the graphic, summary and pages. preview/COHORT/MEMBER_ID/YYYY-MM.html
provides a browser review page with stored text and source references.

This package contains the 14 product categories. Social Services is an offline reviewed projection with product ID product-SOC, not a new database node. Do not infer the current live database taxonomy from this export. Counts matching captured records do not certify classifications or sources.

## Acceptance in the actual Ross environment

These checks remain to be run in the installed template and output environment.
Local JSON/CSV/XML validation and browser tests do not establish Ross acceptance.

1. Select Anne Kang by key; verify singular wording and hidden low activity.
2. Select Bowinn Ma and Brenda Bailey; check ties and different cohort bar widths.
3. Reorder source rows and confirm the selected member remains unchanged.
4. Remove a selected member and confirm an unavailable state instead of another person.
5. Inspect Indigenous names and glyphs; confirm approved formatting and font coverage.
6. Confirm proposed riding aliases fit at output size and obtain editorial approval.
7. Confirm unused slots, false visibility and fallback text hide the correct objects.
8. Keep reporting period and historical context visible for JSON/CSV/XML sources.
9. Verify unchanged revisions do not cause unintended re-takes in the Ross setup.
10. Match a Concept count to the captured analysis and review its source document.
11. Test colours, headshot availability/fallbacks and text on the actual display chain.
12. Confirm no API key is embedded in shared links or graphics.
13. For a live integration, separately test authentication, polling, pinned evidence
    and expired/missing captures using the deployed API; static files do not poll it.
