# Reading the report

Source: https://saer.app/docs/reading-the-report
Updated: 2026-10-30

**Short answer.** A Saer report keeps three kinds of statement apart: facts it can prove (exact findings), inferences it labels with a distance and a confidence (experimental findings), and things it could not establish (unknown and unresolved). Read them in that order.

## Your report files

- `report.html`: the report to read. Open this.
- `report.md`: the report as plain text, for diffs and pull requests.
- `reference.md`: a compact, evidence-based design-system reference for you and your coding agent. Unknowns and capped lists are marked explicitly.
- `proposals/`: local review plans and, where appropriate, foundation starter files linked from the report. Custom output folders use `.saer-proposals/` instead.
- `system.json`: the full machine-readable reconstruction: every entity, its value per context, its evidence and its derivation chain. The schema is versioned and explicitly experimental.

## Choose your next move

Start with Your next move in the full report or agent overview. It offers up to three ordered actions from the same scan evidence, with links to relevant findings. Coverage and unknowns stay visible.

Existing token declarations lead to an adoption plan. If completed analysis establishes no declarations, Saer offers a local foundation starter with light and dark previews, proposed scales and optional React primitives when appropriate. Starter choices and observed raw colours are labelled separately. Review the proposed files before asking your agent to adapt chosen parts; run your ordinary tests and Saer change checks afterwards.

The report links directly to the proposal. It stays beside the report in a generated namespace that Saer excludes from future scans. Edited proposal files and additional review notes are preserved in separate versions. Nothing is applied to your source or uploaded.

## Exact findings

Exact drift is a string-identical match between a raw value and a declared token's resolved value. No inference is involved. Findings distinguish authored UI usage from tests, tooling and unclassified source contexts. Generated output, build artefacts and vendored dependencies cannot create an actionable finding by themselves. Check the cited files and context before replacing a value.

## Experimental findings

Near-match drift and conflicts are inferences. Each carries a perceptual distance (OKLab for colour) and a confidence from a simple, disclosed formula. They are shown separately so they are never mistaken for exact findings.

## Unknown and unresolved

- Unknown: the repository does not contain enough static evidence to answer. More analysis of the same code would not help.
- Unresolved: Saer met something it does not yet know how to read. That is a Saer limitation, not a fact about your system, and it is never turned into a question for you.

## Human decisions

A small number of questions only you can answer, such as whether a group of similar unlabelled colours should become a token. In the Lunary scan, 28,798 observations became 115 findings and 14 questions.