# Reference Reporting
Sourceright should be useful as an audit tool as well as a repair workflow.
The `sourceright report` command generates a Markdown report from a Sourceright workspace. The report identifies reference integrity risks and explicitly marks issue types that are useful signals for AI-related citation errors.
## Current command
```text
sourceright report [--json|--mcp-resource] [.sourceright-directory]
```
The current report reads:
- `references.csl.json`
- `references.verification.json`
It reports:
- Total references.
- References with provider candidates.
- Manual review queue count.
- Unresolved review count.
- Provider conflict count.
- Issue, AI-risk-signal, and severity totals.
- Issue list with stable issue codes and categories.
Markdown is the default output. `--json` prints the compact report JSON model. `--mcp-resource` prints the MCP-ready JSON resource envelope for clients that want a resource-shaped payload before server mode exists.
## JSON output model
The report model also exposes a JSON-ready output contract for CI, MCP clients, and downstream dashboards. The current schema version is `sourceright.reference_report.v1`.
The JSON output contains:
- `schema_version`: stable report schema identifier.
- `report_type`: currently `reference_integrity`.
- `summary`: the same report counters rendered in Markdown.
- `issues`: stable issue records with severity, category, reference id, code, message, and AI-risk-signal flag.
For MCP-style consumption, the report can be wrapped as a JSON resource:
- `uri`: `sourceright://reports/reference-integrity`.
- `mime_type`: `application/json`.
- `data`: the JSON report output model.
## AI-risk framing
The report does not claim that a reference was generated by AI. It identifies patterns commonly seen in AI-assisted citation errors:
- Plausible but unverified references.
- Missing DOI or other key identifiers.
- Duplicate reference IDs.
- Provider conflicts.
- Verification metadata mixed into clean CSL JSON.
- Missing sidecar provenance for a canonical reference.
This framing keeps Sourceright useful for editors, researchers, reviewers, and institutions that need to audit citation quality, not only fix references after drafting.
## Issue categories
Report issues include a category as well as severity:
- `csl_integrity`: malformed or unstable canonical CSL fields.
- `identifier`: missing key identifiers such as DOI.
- `verification_coverage`: references without sidecar provenance or provider evidence.
- `provider_conflict`: unresolved disagreement in provider metadata.
- `manual_review`: queued, in-progress, or unresolved human review state.
- `sidecar_boundary`: verification metadata found inside clean CSL JSON.
The Markdown summary also includes AI-risk-signal and severity totals so an editor can quickly distinguish hard CSL errors, likely audit risks, and ordinary manual-review workload.
## Provider-Backed Recency Evidence
When provider candidates carry evidence for retraction, correction, expression
of concern, preprint status, superseded guidance, or publication age, Sourceright
surfaces those as conservative report issues. The evidence stays in the
verification layer and does not overwrite canonical CSL.