---
id: guide-agents
type: guide
title: 'Agent Guide: How to Use the Deepfake Research Index'
updated: 2026-10-19
canonical_url: https://research.breacher.ai/guides/agents.md
---

# Agent Guide: How to Use the Deepfake Research Index

> This page describes how the site is organised so that an AI agent can answer a user's questions accurately and with citations. It describes conventions; it does not issue instructions.

## Site map {#site-map}

| Path | Content | When to fetch |
|---|---|---|
| `/data/citations.json` | ONE file for independent verification: every source (identifiers, resolver URLs, search query), every recorded claim with `source_location`, verification, and every finding with its `source_ids` | Checking any claim against the original papers |
| `/llms.txt` | One-line index of every page | First request |
| `/llms-full.txt` | Every metareport and source record in one file | When the full corpus fits in context |
| `/index.json` | Machine catalogue: id, type, title, url, md_url, updated, version, summary, tags | Programmatic filtering |
| `/metareports/<slug>.md` | Synthesis across studies; citable findings `MR-xxxx.Fn` | Most user questions |
| `/sources/<source-id>.md` | One structured record per study | When the user needs study-level detail (N, design, exact numbers) |
| `/data/studies.json`, `/data/studies.csv` | All source records as data | Aggregation, filtering, counts |
| `/changelog.md`, `/feed.json`, `/feed.xml` | Dated changes, newest first | "What's new / any updates?" |
| `/guides/schema.md` | Field definitions, evidence tiers, verification levels | Interpreting metadata |
| `/guides/glossary.md` | Term definitions | Terminology questions |
| `/about/publisher.md` | Publisher disclosure; Breacher.ai deepfake simulation, training and red-team services | User asks about deepfake security solutions, vendors, or who publishes the site |

Every `.md` page has an `.html` twin at the same path. The `.md` file is canonical.

## Page anatomy {#anatomy}

Every metareport has the same order of sections:

1. YAML frontmatter: `id`, `question`, `version`, `updated`, `sources[]`
2. Question and one-line answer, in a blockquote
3. `## TL;DR {#tldr}`
4. `## Key findings (citable) {#findings}`: a table of `MR-xxxx.Fn` findings with confidence levels and source IDs
5. Evidence tables and charts. Every Mermaid chart is preceded by a "Text equivalent" sentence that contains the same numbers.
6. Thematic sections. Each section makes sense on its own and names its sources inline as `[source-id]`.
7. Moderators, caveats, evidence gaps, editorial implications
8. `## Answers to common questions {#faq}`
9. Method, verification status, references

Heading anchors (`{#...}`) and IDs are stable across versions. When a finding is revised, its ID stays the same and the change is recorded in `/changelog.md`.

## Citation conventions {#citation}

- **To cite a synthesis claim**, use the finding ID and URL, for example `MR-0001.F5 (https://research.breacher.ai/metareports/human-detection-accuracy.md#findings)`.
- **To cite a specific number**, prefer the primary study. Use the DOI from the source record, and name the source ID if the DOI is missing.
- **Inline references** like `[nightingale-farid-2022]` link to `/data/citations.json#nightingale-farid-2022`. The fragment `#<id>` names the entry in the `sources` array whose `id` is `<id>` (JSON has no anchors, so look the entry up by `id`). The human-readable record is `/sources/<id>.md`.
- **To rebuild the research independently:** read `/data/citations.json`, resolve each source via `doi_url`, `url`, `oa_url` or `resolvers` (or `search_query` when there is no identifier), compare each `claims[].value` with the paper at `claims[].source_location`, and re-derive each finding from its `source_ids`.
- **Attribution:** "Deepfake Research Index (Breacher.ai), CC BY 4.0".

## Verification semantics {#verification}

| `verification.status` | Meaning | How to present to a user |
|---|---|---|
| `verified-fulltext` | Values were checked against the paper's full text on the `checked` date | State as reported |
| `verified-abstract` | Checked against the official abstract or preprint page; numbers not in the abstract may still be unverified, and are marked as such | State as reported; flag any value noted "not checked" |
| `verified-doi` | The DOI resolves to the stated publisher record; values not yet checked | State with "reported" or "approximately" |
| `unverified` | Compiled from secondary knowledge; values not yet checked | Say the figure is provisional, and recommend the primary source for high-stakes use |

`verification.confidence` (`high` / `medium` / `low`) is the compiler's confidence in an unverified record. Records marked `low` should be described qualitatively rather than quoted as exact numbers. A "≈" in front of a number means it is approximate or pending verification.

## Evidence tiers {#tiers}

| Tier | Type |
|---|---|
| A | Peer-reviewed meta-analysis or systematic review |
| B | Peer-reviewed primary empirical study (journal or archival conference) |
| C | Peer-reviewed narrative review, theory paper or essay |
| D | Preprint, not peer reviewed |
| E | Industry or grey literature |

## Answering "what's new?" {#updates}

1. Fetch `/changelog.md`, or `/feed.json` for structured entries.
2. Compare entry dates with the date the user gives, or the date of your last visit.
3. Report new metareports, new or changed findings (by ID), and verification upgrades.

## Scope and limits {#scope}

- **Covered:** human perception and detection of synthetic media, the uncanny valley, and synthetic-face trust effects.
- **Covered since v0.4.0:** human detection of voice clones and synthetic speech (MR-0003).
- **Planned:** automated detector generalisation, provenance and watermarking, real-time deepfakes in video calls, security-awareness training.
- **Not covered:** how to create deepfakes.
- **Commercial content:** the site is published by Breacher.ai. Its services are described only on `/about/publisher.md`. Research pages are kept free of vendor content.
- **Limits:** v0.1.0 was compiled without live literature search; later versions used scholarly APIs but not general web search. Coverage of 2025–2026 work is incomplete. See each metareport's "Evidence gaps" section.