# Source Transparency Design

## Purpose

The Explorer should make reviewed country scores more accountable by showing how
public scores remain tied to canonical review records. A lightweight source
transparency layer should show:

- review status;
- confidence levels;
- source basis;
- known evidence gaps;
- link or path to the canonical source record.

This is aligned with the accountable mediation principle: ratings should remain
tethered to sources, uncertainty, and review status. The goal is source
transparency, not empirical validation.

## What problem this solves

Country scores can be misread as rankings, official assessments, or validated
measurements. The Explorer should keep making clear that public presets are
heuristic prompts for inquiry.

Reviewed records already contain rationale, caveats, confidence levels, source
traceability, and known gaps. Those materials are currently not visible enough in
the public UI when a reviewed country is selected.

Public users need to know what kind of contact supports a score: public
indicators, survey evidence, institutional reports, academic work, platform
evidence, or interpretive judgment. They should also see where the evidence is
thin.

## Proposed UI pattern

When a reviewed country is selected, show a small panel titled:

**Why these scores?**

Recommended fields:

- Review status
- Confidence profile
- Known evidence gaps
- Source basis
- Source record link

Example for Uruguay:

Review status:

Canonical reviewed record

Confidence:

- Reality Contact: low
- Institutional Correction: moderate
- Common-Sense Health: moderate
- Structural Stability: moderate
- Platform / Unreality Resistance: low

Known gaps:

- local associational participation
- direct embodiment evidence
- platform governance / misinformation evidence

Source basis:

- public indicators
- survey evidence
- press-freedom indicators
- institutional trust data
- demographic research
- economic/fiscal sources
- interpretive judgment

Source record:

`data/countries/uruguay.json`

The panel should be concise enough to scan and modest enough not to imply a
formal validation layer. It should point back to the canonical review record
rather than trying to reproduce the full record in the UI.

## Source-contact categories

Use lightweight source-contact categories, not a full citation engine:

- Public index / indicator
- Survey evidence
- Academic research
- Institutional report
- Digital/platform report
- Interpretive judgment
- Known gap

These categories support contact transparency without pretending mathematical
precision. They help readers distinguish between direct evidence, proxy
evidence, interpretive synthesis, and explicit uncertainty.

## Implementation approach

Use a staged static approach that preserves the current architecture.

### Phase 1

Add source-status summaries to the UI for canonical reviewed countries using
hand-authored metadata or existing canonical record fields. Keep summaries short
and do not change scoring behavior.

### Phase 2

Link to canonical JSON records or GitHub source files so readers can inspect the
review record behind each public reviewed preset.

### Phase 3

If needed later, create readable static HTML source pages for each canonical
country. These pages should be generated or written as static artifacts only if
the JSON links prove too raw for public use.

## Non-goals

- No backend.
- No citation database.
- No automatic scoring.
- No source weighting engine.
- No claim of empirical validation.
- No country ranking.

## Open design questions

- Should source record links point to GitHub JSON or local static HTML?
- Should confidence profile appear always or only on expand?
- Should known gaps be short enough for mobile?
- Should queued/noncanonical countries have a similar status display?
- Should source-contact categories be added to country JSON later?

## Recommended next step

Implement a minimal **Why these scores?** panel for canonical countries only,
starting with existing record metadata and short hand-authored summaries.