# Trust Lens — Epistemic Markup Authoring Guide

Making the epistemic status and confidence of each claim explicit is a step toward more honest scientific writing. The Trust Lens feature lets readers toggle between a plain reading view and a highlighted view that shows, for every marked sentence, *what kind of claim it is* and *how well-supported it is numerically*. Authors tag claims once; the reader-side script does the rest.

---

## The 5 Categories (`data-epi`)

| Value | Label | Definition | Use when |
|---|---|---|---|
| `cited` | Cited fact | Directly supported by a cited source | The sentence restates or closely paraphrases something a source states explicitly |
| `inference` | Inference | Reasoned from one or more sources; not stated verbatim | You draw a conclusion the source implies but does not state |
| `hypothesis` | Hypothesis | Forward-looking or speculative claim about mechanisms or outcomes | You predict something that has not yet been tested or confirmed |
| `consensus` | Established consensus | Widely accepted domain knowledge; textbook-level | The claim is standard background that any specialist would accept; citation optional |
| `view` | Neuronautix view | Explicit interpretation or position | You are stating Neuronautix's analytical stance or recommendation |

Category and trust are **independent axes**. A `view` can be sincere but low-evidence (trust 25); a `cited` fact from a landmark RCT can be very high trust (trust 95).

---

## Trust Band Rubric (`data-trust`, 0–100)

| Range | Level | When to use |
|---|---|---|
| 90–100 | Very high | Directly stated in a peer-reviewed primary source or regulatory document; unambiguous |
| 70–89 | High | Stated in a cited source but secondary / minor interpretation; or strong multi-source support |
| 50–69 | Moderate | Reasonable inference from sources, or consensus without a single citation |
| 30–49 | Tentative | Plausible hypothesis with partial support |
| 0–29 | Speculative | Opinion or vision with little direct evidence |

Pick the band first, then choose a specific integer that reflects how strong the support feels within that band. Avoid fake precision — round to the nearest 5 if unsure.

---

## Exact Span Syntax

```html
<span
  class="nnx-claim"
  data-epi="cited"
  data-trust="92"
  data-claim-note="Directly stated in Smith et al. 2023 Table 2; unambiguous quantitative finding."
  data-refs="1"
>Claim text visible to the reader [1].</span>
```

**All four attributes are required** (omit `data-refs` only if the claim is a consensus with no specific citation).

- `class="nnx-claim"` — required; activates the feature
- `data-epi` — one of the five values above, exactly as written
- `data-trust` — integer 0–100
- `data-claim-note` — one concise clause explaining the score rationale (shown in the reader tooltip)
- `data-refs` — space-separated citation numbers matching the `[n]` labels in your References section (e.g. `data-refs="1 3"`)

The inline `[n]` label after the claim text is still part of the prose; it is **not** replaced by `data-refs` — both coexist.

---

## Reader Display Modes (for context only — authors do not configure these)

The reader-side script (`trust-lens.js`) mounts a toggle bar and offers three modes:

- **Gradient** — continuous colour highlight scaled 0–100, with the numeric score shown on hover. Gives a fine-grained visual sense of certainty gradients within a paragraph.
- **Bands** — discrete pastel bands keyed to the five trust levels (Very high / High / Moderate / Tentative / Speculative), plus a category badge. Easier to read at a glance.
- **Margin** — leaves the prose completely un-highlighted and moves the trust signal into the right-hand gutter. For each claim a vertical colour bar (same trust colour code) spans the vertical extent of the sentence, and a small box beside it shows the category, trust score and band; hovering the box reveals the rationale and refs, and tints the matching sentence. Desktop only — below ~1100px there is no gutter, so Margin mode automatically falls back to the Gradient highlight.

The bar also offers a **colour palette** switch:

- **Color-blind safe** (default) — an Okabe–Ito-derived scale running vermillion → orange → yellow → sky → blue (low → high trust), distinguishable under deuteranopia, protanopia and tritanopia. Meaning is never carried by colour alone: every claim also shows a numeric score / band label and a category dot, and the legend maps both axes.
- **Classic** — the original red → green trust scale.

The selected mode and palette persist across pages (localStorage). Authors only write `data-epi` + `data-trust`; all display choices are reader-side.

---

## Authoring Checklist

- [ ] Every non-trivial factual or interpretive sentence is wrapped in `<span class="nnx-claim" …>`
- [ ] Trivial connective sentences ("This section introduces…", "In summary…") are left unwrapped
- [ ] `data-refs` reuses the same `[n]` numbers used in the inline prose citation and the References list
- [ ] `data-claim-note` is one clause — no full paragraphs, no redundancy with the visible text
- [ ] `data-epi` is chosen before `data-trust` (category first, score second)
- [ ] The `<div class="nnx-trust-bar" data-nnx-trust></div>` mount is present immediately before `<div class="nnx-note-body nnx-content">` in the HTML
- [ ] If a note has **no** `.nnx-claim` markup at all, remove the trust-bar mount to avoid rendering an empty control

---

## Worked Example

> Home-cage monitoring systems can passively record behavioural data across the full light/dark cycle without experimenter interference [1].
> The richness of that continuous stream means activity rhythms can be reconstructed at sub-minute resolution, enabling detection of subtle welfare indicators that acute observation misses.
> If combined with real-time AI alerting, such systems could flag anomalous behaviour within hours of onset rather than at the next scheduled check.

Marked up:

```html
<p>
  <span class="nnx-claim" data-epi="cited" data-trust="91"
    data-claim-note="Stated explicitly in Endo et al. 2021 describing DVC system design."
    data-refs="1">Home-cage monitoring systems can passively record behavioural data
    across the full light/dark cycle without experimenter interference [1].</span>
  <span class="nnx-claim" data-epi="inference" data-trust="65"
    data-claim-note="Follows from continuous sampling rates reported in [1]; sub-minute resolution is the author's framing, not verbatim."
    data-refs="1">The richness of that continuous stream means activity rhythms can
    be reconstructed at sub-minute resolution, enabling detection of subtle welfare
    indicators that acute observation misses.</span>
  <span class="nnx-claim" data-epi="hypothesis" data-trust="38"
    data-claim-note="Technically plausible given current ML pipeline speeds; no published trial of real-time alerting thresholds exists yet.">If
    combined with real-time AI alerting, such systems could flag anomalous behaviour
    within hours of onset rather than at the next scheduled check.</span>
</p>
```

Three claims, three categories, three trust scores — the reader can immediately see what rests on primary evidence, what is the author's synthesis, and what is still a prediction.