linkml-reference-validator 0.3.1rc1__tar.gz → 0.4.0__tar.gz

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkml_reference_validator
-Version: 0.3.1rc1
+Version: 0.4.0
 Summary: Validation of supporting text from references and publications
 Author-email: Chris Mungall <cjmungall@lbl.gov>
 License-Expression: Apache-2.0
@@ -58,6 +58,28 @@ linkml-validate -s schema.yaml data.yaml \
 
 ---
 
+## Agent skill
+
+Install the [linkml-reference-validator workflow skill](skills/linkml-reference-validator/SKILL.md) with the
+[skills CLI](https://skills.sh/) (requires Node.js). Preview available skills first:
+
+```bash
+npx skills add linkml/linkml-reference-validator --list
+npx skills add linkml/linkml-reference-validator --skill linkml-reference-validator
+```
+
+Installation defaults to the current project. Use `-a codex` or
+`-a claude-code` to select an agent; add `-g` for your user-wide skills directory:
+
+```bash
+npx skills add linkml/linkml-reference-validator --skill linkml-reference-validator -a codex -g
+```
+
+The skill helps agents configure reference QC, interpret failures and coverage,
+and set up repository hooks and CI using bundled reference guides. Install the
+runtime separately as described above; installing the skill does not activate
+hooks or configure CI, credentials, or data sources.
+
 ## Why Use This Tool?
 
 Scientific data often includes claims supported by quotes from publications. But how do you know the quotes are accurate?

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/README.md

@@ -37,6 +37,28 @@ linkml-validate -s schema.yaml data.yaml \
 
 ---
 
+## Agent skill
+
+Install the [linkml-reference-validator workflow skill](skills/linkml-reference-validator/SKILL.md) with the
+[skills CLI](https://skills.sh/) (requires Node.js). Preview available skills first:
+
+```bash
+npx skills add linkml/linkml-reference-validator --list
+npx skills add linkml/linkml-reference-validator --skill linkml-reference-validator
+```
+
+Installation defaults to the current project. Use `-a codex` or
+`-a claude-code` to select an agent; add `-g` for your user-wide skills directory:
+
+```bash
+npx skills add linkml/linkml-reference-validator --skill linkml-reference-validator -a codex -g
+```
+
+The skill helps agents configure reference QC, interpret failures and coverage,
+and set up repository hooks and CI using bundled reference guides. Install the
+runtime separately as described above; installing the skill does not activate
+hooks or configure CI, credentials, or data sources.
+
 ## Why Use This Tool?
 
 Scientific data often includes claims supported by quotes from publications. But how do you know the quotes are accurate?

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/concepts/content-types.md

@@ -12,6 +12,7 @@ When fetching references, the validator tracks what type of content was retrieve
 | `summary` | GEO, BioProject, BioSample, ClinicalTrials | Database summary/description field |
 | `local_file` | file: | Content read from local filesystem |
 | `local_svg` | file: (`.svg`) | Text an SVG figure renders, a blank line between labels; a quote must fall within one label |
+| `local_drawio` | file: (`.drawio`) | Labels a drawio diagram draws, read like `local_svg` |
 | `url` | url: | Content fetched from web URL |
 | `unavailable` | Any | No content could be retrieved |
 

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/how-to/fetch-full-text-and-pdfs.md

@@ -21,17 +21,34 @@ The validator tries providers in order until one returns usable full text.
 The default order is:
 
 ```
-pmc → epmc_preprint → unpaywall → openalex
+pmc → bookshelf → epmc_preprint → unpaywall → openalex
 ```
 
 - **`pmc`** — PubMed Central open-access subset (XML/HTML full text for many
   biomedical articles).
+- **`bookshelf`** — NCBI Bookshelf chapters, such as GeneReviews, read from a
+  local copy of NCBI's archive (see [NCBI Bookshelf](#ncbi-bookshelf-genereviews)
+  below). Does nothing until `bookshelf_archive_dir` is set.
 - **`epmc_preprint`** — Europe PMC preprint body text via the `fulltextRepo`
   PDF route (see [Preprints](#preprints) below).
 - **`unpaywall`** — Unpaywall open-access lookup by DOI (often a publisher or
   repository PDF).
 - **`openalex`** — OpenAlex open-access location (PDF/HTML).
 
+Two more built-in providers are available but not in the default chain; add
+them to `full_text_providers` to use them:
+
+- **`bioc`** — PMC Open Access articles as BioC passages, from NCBI's BioNLP
+  BioC API, by PMID. The reference list and the competing-interest,
+  author-contribution and funding statements are left out, so a snippet quoting
+  a cited paper cannot validate against the paper citing it.
+- **`epmc`** — Europe PMC's `fullTextXML` for open-access articles, by PMID.
+  This is the same JATS that `pmc` reads, served by Europe PMC rather than
+  NCBI, so after `pmc` it rarely finds anything new. It is useful as a second
+  route when NCBI is down or rate-limiting, or in place of `pmc` to avoid
+  depending on Entrez. Not to be confused with `epmc_preprint`, which handles
+  preprints only.
+
 Providers are skipped silently if they have nothing for a given reference, so
 the chain degrades gracefully: a miss in `pmc` simply moves on to `unpaywall`,
 and so on. If no provider yields full text, the reference keeps whatever
@@ -45,7 +62,8 @@ your config YAML or on the `ReferenceValidationConfig` object):
 | Key | Default | Description |
 |-----|---------|-------------|
 | `fetch_full_text` | `true` | Attempt to obtain full text via the provider chain when a metadata source does not already return full text. |
-| `full_text_providers` | `[pmc, epmc_preprint, unpaywall, openalex]` | Ordered list of provider names to try until one yields usable full text. |
+| `full_text_providers` | `[pmc, bookshelf, epmc_preprint, unpaywall, openalex]` | Ordered list of provider names to try until one yields usable full text. `bioc` and `epmc` are also built in but must be added explicitly. |
+| `bookshelf_archive_dir` | `null` | Directory of unpacked NCBI Bookshelf books, read by the `bookshelf` provider. |
 | `private_cache_dir` | `~/.cache/linkml-reference-validator/private` | Separate research cache for closed/user-library full text; never read by validation. |
 | `pdf_backend` | `pypdf` | Name of the PDF text-extraction backend. |
 | `download_pdfs` | `true` | If true, persist downloaded PDFs to the files cache directory. |
@@ -66,6 +84,7 @@ email: you@example.org
 fetch_full_text: true
 full_text_providers:
   - pmc
+  - bookshelf
   - epmc_preprint
   - unpaywall
   - openalex
@@ -73,6 +92,91 @@ pdf_backend: pypdf
 download_pdfs: true
 ```
 
+## NCBI Bookshelf (GeneReviews)
+
+A PMID can point to a chapter on NCBI Bookshelf rather than a journal article.
+Every [GeneReviews](https://www.ncbi.nlm.nih.gov/books/NBK1116/) entry is one
+of these. Such a chapter has no PMC copy, so without help the reference keeps
+only its PubMed summary, and a quote from the chapter body fails as
+abstract-only.
+
+The archive described below is for **caching** a chapter, not for validating
+against it. Validate quotes against the cached document. Once a chapter has
+been fetched, its full text is in the reference cache (`PMID_31536184.md`),
+and every later validation reads that file. There's no archive and no network
+call. So the large download is a one-time step on the machine that builds the
+cache, not something every run or every collaborator needs. See
+[Validate against the cache, not the archive](#validate-against-the-cache-not-the-archive).
+
+Bookshelf's web pages can't be fetched by a script: NCBI answers with a
+reCAPTCHA page. Instead, the `bookshelf` provider reads chapters from NCBI's
+[litarch archive](https://ftp.ncbi.nlm.nih.gov/pub/litarch/), which you
+download once per book:
+
+```bash
+linkml-reference-validator cache bookshelf-download NBK1116 --archive-dir bookshelf
+```
+
+GeneReviews (`NBK1116`) is a 640 MB download. Only the chapter XML is kept,
+about 200 MB. Then point the config at the same directory:
+
+```yaml
+bookshelf_archive_dir: bookshelf
+```
+
+The PubMed record names the chapter, so no extra lookup is needed:
+`PMID:31536184` is `gene/glutaric-a1`, read from
+`bookshelf/gene_NBK1116/glutaric-a1.nxml`. The cached entry records
+`full_text_provider: bookshelf`, and `full_text_url` holds the chapter's
+Bookshelf page.
+
+A chapter is used only when its own `<license>` is `open-access`. GeneReviews
+allows copying for noncommercial research with credit and no modification. A
+cache holds a verbatim copy, and its `full_text_url` links back to the
+chapter, so the text goes into the public cache like PMC full text does.
+
+To refresh a book, run the download again: it replaces the book's folder. Do
+this to pick up new or revised chapters.
+
+**References cached before the archive was set up** keep their abstract. The
+chain recorded that it couldn't read the chapter (`full_text_declined`, or
+`full_text_attempted` on a cache from an older version), and it doesn't retry
+on its own. Re-fetch them:
+
+```bash
+linkml-reference-validator cache reference PMID:31536184 --force
+```
+
+### Validate against the cache, not the archive
+
+The archive is only read when a chapter is **fetched**. That happens the first
+time a reference is seen, and on an explicit `--force`. Validation reads the
+cached document like any other cached reference. In practice:
+
+1. On one machine, download the book, set `bookshelf_archive_dir`, and cache
+   the chapters you cite (`cache reference PMID:...`, or a validation run).
+2. Commit the reference cache: the `PMID_*.md` files, which hold the chapter
+   text. Don't commit the archive.
+3. Everywhere else, including CI and collaborators, validate as usual. No
+   archive is needed, `bookshelf_archive_dir` can stay unset, and nothing is
+   downloaded from NCBI.
+
+What happens when the archive is missing:
+
+- **A cached chapter is never lost to a refresh that can't reach it.** If a
+  newer version of this tool marks the entry stale and re-fetches it, the
+  refresh gets only the abstract. The cached chapter is then kept and still
+  used, with a warning, and the entry stays stale until a run with the
+  archive refreshes it. For a committed cache you'd rather not re-fetch at
+  all, set `trust_cached_entries: true`.
+- **`--force` is the exception.** It replaces the entry with whatever the
+  fetch returns, so forcing a Bookshelf reference without the archive swaps
+  the chapter for its abstract (it warns as it does). Only force these
+  references where the archive is available.
+- **A reference that was never cached** still needs the archive once.
+  Without it, the reference is cached with its abstract only.
+  `full_text_declined: bookshelf_archive_not_configured` records why.
+
 ## Private manuscripts in Zotero
 
 The opt-in **`zotero`** provider can find non-open manuscripts that are already
@@ -270,7 +374,7 @@ the text came from. These provenance fields are written alongside the content:
 
 | Field | Description |
 |-------|-------------|
-| `full_text_provider` | Name of the provider that supplied the full text (e.g. `pmc`, `epmc_preprint`, `unpaywall`, or a custom name). |
+| `full_text_provider` | Name of the provider that supplied the full text (e.g. `pmc`, `bioc`, `epmc`, `epmc_preprint`, `unpaywall`, or a custom name). |
 | `oa_status` | Open-access status reported by the provider (e.g. `gold`, `green`, `bronze`). |
 | `license` | License of the open-access copy, when known. |
 | `local_pdf_path` | Path (relative to the cache directory) to the downloaded PDF, when one was persisted. |

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/how-to/repair-validation-errors.md

@@ -28,6 +28,21 @@ Validation uses an explicit ligature table instead of broad Unicode NFKC
 normalization so this change does not equate scientific notation such as `H₂O`
 with `H2O`, `10⁶` with `106`, or the micro sign `µ` with Greek `μ`.
 
+### Unmapped PDF glyphs do not match
+
+Some PDFs draw a glyph without saying which character it is, so text extraction
+gets no character at all. This is common for `fi`/`fl` ligatures, and sometimes
+happens for digits or minus signs. PDF extraction writes U+FFFD (`�`) in its
+place and logs a warning with the count, so cached text reads `in�ammation`.
+Validation does not guess the missing character: a quote containing
+`inflammation` will not match that text. Check the cached file for `�` and
+quote around the damaged word or supply better full text.
+
+Matching treats `�` like punctuation, so the damaged word splits in two: the
+cached text above reads as `in ammation`. A quote that starts or ends inside
+the damaged word still matches, so `ammation of the gut` matches
+`in�ammation of the gut`.
+
 ## Quick Start
 
 ### Repair a Single Quote
@@ -121,6 +136,22 @@ Suggested fix (85%): "Haemophilus influenzae type b" → "H. influenzae type b"
 
 Use with caution - verify the suggestion preserves the intended meaning.
 
+A correction that would change what the quote claims is reported, but never
+offered or applied as the fix:
+
+- **It drops a word of the quote,** such as "no" or "in mice".
+- **It swaps a word for one that differs only in a prefix,** such as
+  "unaffected" for "affected", "hyperphosphorylated" for
+  "hypophosphorylated", or "intracellular" for "extracellular". This holds
+  even when the quote also has a typo ("unaffectd").
+- **It adds a negation** the quote doesn't have, such as "not", "never",
+  "without" or "failed to".
+
+Words of three letters or fewer must match exactly, so "in" is never
+corrected to "on". These checks err towards caution, so some real typos go
+unfixed and need fixing by hand: a typo in a word's first few letters can look
+like a changed prefix ("ctivation" reads as "activation" without its "a").
+
 ### 4. Removal Recommendation (Very Low Confidence)
 
 Flags text that appears fabricated or hallucinated:

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/how-to/use-local-files-and-urls.md

@@ -141,14 +141,95 @@ linkml-reference-validator validate text \
   `-webkit-text-security`, a `unicode-bidi` override, `<bdo>`, or a bidi
   control character in the text.
 
+**Edges.** A connector between two labelled nodes also gives an edge line,
+`"<source> <edge label> <target>"`, so a relational quote such as
+`"PTEN inhibits AKT"` can be checked. The connector is an element (usually a
+`<g>` holding the line and its label) whose `data-source` and `data-target`
+attributes name the two nodes' ids:
+
+```xml
+<defs><marker id="arrow"><path d="M0 0 L10 5 L0 10 z"/></marker></defs>
+<g id="pten"><rect x="0" y="0" width="60" height="30"/><text x="10" y="20">PTEN</text></g>
+<g id="akt"><rect x="200" y="0" width="60" height="30"/><text x="210" y="20">AKT</text></g>
+<g data-source="pten" data-target="akt">
+  <path d="M60 15 L200 15" stroke="black" marker-end="url(#arrow)"/>
+  <text x="110" y="10">inhibits</text>
+</g>
+```
+
+The attributes are not drawn, so they are only believed when the drawing
+agrees: the connector's stroked path must join the two nodes' shapes, one end
+on each (transforms applied, with a little slack for an arrowhead), and the
+connector, its label and both nodes and their labels must all be visible.
+
+Arrowheads drawn as markers give the direction:
+
+- **One arrowhead** (a `marker-start` or `marker-end`, set on the path or
+  inherited) points at the node at that end, and the line reads from the other
+  node to it. This holds even when it's the reverse of `data-source` →
+  `data-target`: the drawing wins, as in drawio.
+- **Arrowheads at both ends** make the line quotable both ways.
+- **No arrowhead** (a plain line, or a marker that draws nothing) reads in the
+  attributes' order, `data-source` first. This is a known limitation: nothing
+  drawn gives that order, so swapping the two attributes reverses the line
+  for the same picture.
+- **An arrowhead drawn as a separate shape** gives no edge line: which way
+  such a shape points can't be read, and the attributes' order could
+  contradict it. This is any other `<polygon>`, `<polyline>`, `<path>` or
+  `<line>` in the connector, wherever it sits; any `<use>` or `<image>`; and a
+  `<rect>`, `<circle>` or `<ellipse>` at an end of the line or on a node. A
+  `<rect>`, `<circle>` or `<ellipse>` in mid-line, such as a label's
+  background, is not taken for an arrowhead.
+- **Arrowheads at a bent line's inner vertices** (`marker-mid`, or the
+  `marker` shorthand) give no edge line, since each may point either way.
+
+A marker counts as an arrowhead when it names a `<marker>` in the figure that
+draws something: a shape that paints, at a size above zero. When that can't be
+told from the markup (a `var()` value, or a `<use>`, text or image inside the
+marker), the connector gives no edge line, since neither direction is safe. The
+marker's `orient` is not read: a marker drawn at a fixed angle is taken to
+point along the path. A node is the shapes it draws inside the
+element its id names; its text, and shapes that are hidden or paint nothing,
+do not count towards its box. Geometry the extractor cannot place from
+attributes gives no edge line either: CSS `transform` or other CSS geometry,
+`clip-path`, `mask` or `filter`, or an animation that moves shapes. A node drawn only through `<use>`, inside a
+nested `<svg>`, or sized in `%` or `em` gives no edge line.
+
 Known limits: a label drawn as several `<text>` elements, one per line, is
 read as several labels, so quote its lines with `...` between them. Text
 clipped by `clip-path` or `mask`, placed outside the
 `viewBox`, scaled to nothing, covered by another shape, drawn in the
 background colour, or cut short by CSS `text-overflow` or `-webkit-line-clamp`
 is still read. Text converted to outlines is not text and
-cannot be quoted. Native `.drawio` files and connector (edge) labels between
-nodes are not yet supported.
+cannot be quoted.
+
+## Diagrams as References (drawio)
+
+A `file:` reference can also point at a native drawio diagram, `.drawio` or
+`.drawio.xml`, compressed or not. It is read the same way as an SVG: one label
+per drawn cell, quotes held to one label, and an edge line
+`"<source> <edge label> <target>"` for each drawn edge between two labelled
+cells. In drawio an edge's source and target are what it is drawn between, so
+no geometry check is needed; its line and both cells' labels must still be
+visible. The arrows give the direction, as for SVG: an edge drawn pointing
+back at its source reads target first, one with arrows at both ends reads both
+ways, and one with no arrow reads source first. Only markers that point count
+as arrows: arrowheads (`classic`, `block`, `open`, `async` and their thin or
+double forms) and the inhibition T-bar `baseDash`. An oval, diamond, dash or
+ER symbol at an end is not an arrow. A marker drawio doesn't list as either
+gives no edge line. Every page of the file is read.
+
+A `.drawio.svg` file (drawio's editable SVG export) is read as an SVG: its
+labels are quotable, but it carries no `data-source`/`data-target`, so it
+gives no edge lines. Point at the `.drawio` source to quote its edges.
+
+Not read: cells marked invisible, in a hidden layer, or inside a collapsed
+group; labels switched off (`noLabel`) or drawn with zero `opacity`,
+`textOpacity` or `fontSize`, or with no `fontColor`; layer and page names,
+tooltips, styles and other attributes. HTML labels follow the same visibility
+rules as SVG `<foreignObject>` labels. A label computed from placeholders
+(`placeholders="1"`), or HTML that cannot be read statically, makes the
+reference `unavailable`.
 
 ## Using in Data Files
 
@@ -190,7 +271,8 @@ Both file and URL references work in LinkML data files:
 
 ## Limitations
 
-- **Local files are read as text**, apart from `.svg` figures (see above).
+- **Local files are read as text**, apart from `.svg`, `.drawio` and `.drawio.xml` figures
+  (see above).
   An `.html` file is matched against its raw markup.
 - **Local PDF files**: Not yet supported as `file:` references. PDFs fetched by `url:` are supported.
 - **Authentication**: URLs requiring login are not supported

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/how-to/validate-urls.md

@@ -227,7 +227,22 @@ Ensure the cached content contains the text you're referencing.
 - Use `linkml-reference-validator cache reference url:https://... --force` to update cached content when pages change
 - Periodically review cached URLs to ensure they're still accessible
 
-### 4. Mix Reference Types
+### 4. Cite Pages With Fragments
+
+A fragment such as `#page=54` is never sent to the server, so it isn't part of
+the cache key. `url:https://example.com/report.pdf#page=54` and
+`...report.pdf#page=55` share one cache file, `url_https___example.com_report.pdf.md`,
+and the document is fetched and extracted once. Each reference still carries
+its own page-anchored URL, and quotes are matched against the whole document,
+not the cited page. Query strings (`?v=2`) do stay part of the key.
+
+Caches written before this change hold one file per fragment, such as
+`url_https___example.com_report.pdf#page_54.md`. These are still read, until
+the reference is next fetched (for example with `cache reference ... --force`);
+the fresh entry goes to the shared file, after which the per-fragment files can
+be deleted.
+
+### 5. Mix Reference Types
 
 URL references work alongside PMIDs and DOIs:
 

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/reference/cli.md

@@ -689,6 +689,7 @@ linkml-reference-validator cache COMMAND [ARGS]...
 
 - `reference` - Cache a reference for offline use
 - `lookup` - Show the cache path for a reference (or print file contents)
+- `bookshelf-download` - Download an NCBI Bookshelf book for chapter full text
 
 ---
 
@@ -883,6 +884,40 @@ the research cache private.
 
 ---
 
+## cache bookshelf-download
+
+Download one NCBI Bookshelf book from NCBI's litarch archive and unpack its
+chapter XML, so the `bookshelf` full-text provider can read chapters such as
+GeneReviews entries. See
+[Fetch full text](../how-to/fetch-full-text-and-pdfs.md#ncbi-bookshelf-genereviews).
+
+```bash
+linkml-reference-validator cache bookshelf-download ACCESSION [OPTIONS]
+```
+
+**Arguments:**
+
+- `ACCESSION` - The book's NBK accession, e.g. `NBK1116` for GeneReviews
+
+**Options:**
+
+- `--archive-dir PATH` - Where to unpack the book (default: `bookshelf_archive_dir` from the config)
+- `--mirror URL` - Base URL of the litarch archive (default: `https://ftp.ncbi.nlm.nih.gov/pub/litarch`)
+- `--config PATH` - Validation configuration file
+- `--verbose, -v` - Enable detailed logging
+
+```bash
+linkml-reference-validator cache bookshelf-download NBK1116 --archive-dir bookshelf
+```
+
+Running it again replaces the book's folder with the current release.
+
+The archive is only needed on the machine that caches chapters. Validation
+reads the cached reference (`PMID_*.md`), so a committed cache validates
+without the archive or any NCBI call.
+
+---
+
 ## Reference ID Formats
 
 ### PubMed (PMID)

{linkml_reference_validator-0.3.1rc1 → linkml_reference_validator-0.4.0}/docs/troubleshooting.md

@@ -446,6 +446,28 @@ reference_title: "Role of JAK1"
 actual_title: "Role of JAK1 in Cell Signaling"
 ```
 
+### Title mismatch against "Checking your browser - reCAPTCHA"
+
+**Symptom** (older versions):
+```
+Title mismatch: expected 'MELAS - GeneReviews® - NCBI Bookshelf'
+but got 'Checking your browser - reCAPTCHA'
+```
+
+**Cause:** the host (NCBI does this for Bookshelf and PMC pages) answered a
+`url:` fetch with a bot check instead of the document. It sends the check with
+HTTP 200, so older versions took it for the document and cached it.
+
+The `url:` source now treats a page with a known challenge title as a failed
+fetch: a cached entry is used instead, and nothing is written. A challenge page
+cached by an older version is ignored, as if absent, and replaced by the next
+good fetch.
+
+**Solution:** upgrade, and leave the curated title alone; it is probably
+correct. While the host keeps challenging, a reference with no good cached
+entry reports `Could not fetch reference` rather than a title mismatch.
+Retrying during the block gets the challenge again.
+
 ## Schema Issues
 
 ### No reference or supporting_text fields found
@@ -815,8 +837,9 @@ permission. An unrecognised or missing status is **not** assumed open: an
 unknown licence is not a grant.
 
 This governs files found by asking an OA *index* (OpenAlex, Unpaywall). It does
-not govern the `pmc` and `epmc_preprint` providers, which ask an archive's own
-API for a document it serves for machine retrieval — a stronger warrant than an
+not govern the `pmc`, `bioc`, `epmc` and `epmc_preprint` providers, which ask an
+archive's own API (PMC, its BioC rendering, or Europe PMC) for a document it
+serves for machine retrieval — a stronger warrant than an
 index's summary of a third-party host. The same green deposit can therefore be
 declined from OpenAlex and admitted from PMC.
 
@@ -915,7 +938,7 @@ the old entry is still served and is not rewritten, so a later run retries.
 Other sources are unaffected. With `trust_cached_entries` set, old entries are
 served as they are and are not refreshed.
 
-`file:` references to `.svg` figures carry their own stamp,
+`file:` references to `.svg` and `.drawio` figures carry their own stamp,
 `svg_extraction_version`. Version 1 reads a figure as the text it renders
 (issue #104); before it, the file was cached as raw markup, so a quote could
 match a `<desc>`, an attribute value or hidden text. Such an entry is re-read
@@ -926,6 +949,8 @@ read: not when the file has moved, not when the new read finds no rendered
 text, and not with `trust_cached_entries`. The file is the source, and its raw
 markup is not evidence. Version 2 separates a figure's labels, so a quote is
 matched within one label; version 1 entries are re-read once for it.
+Version 3 adds edge lines for connectors the drawing confirms; older entries
+are re-read once to gain them.
 
 **A quote that verified against a `url:` page can fail after that refresh.**
 Sanitizing removes `<noscript>` and `<template>` elements with their text.

linkml_reference_validator-0.4.0/skills/linkml-reference-validator/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: linkml-reference-validator
+description: Set up, configure, and troubleshoot LinkML Reference Validator (LRV) as deterministic reference QC in repository hooks and CI. Use when interpreting quote or title failures, diagnosing unchecked evidence and cache coverage, or configuring schema extraction, sources, and matching policy.
+---
+
+# Work with reference QC
+
+LRV performs deterministic quote and title checks against retrieved source
+content. Run those checks through repository automation. The agent's role is to
+integrate the checker, explain findings, and make evidence-based corrections.
+Maintainers define required coverage and exception policy; curators decide
+whether the evidence supports the scientific claim. A matching quote settles
+neither its relevance nor the truth of the claim.
+
+A passing automated check needs no agent reenactment. Apply scientific review
+when curating or reviewing evidence, rather than rereading every source on each
+QC run.
+
+## Establish the validation context
+
+Read the project's guidance, validation recipe or wrapper, schema, explicit
+config, dependency lock, and existing hook/CI output. Identify the affected
+files, target class, source cache, and whether this check is blocking or
+advisory. Use the existing project command: a wrapper may encode policy absent
+from a bare CLI invocation. Reproduce a finding on the affected file with the
+same inputs before changing data; avoid repeated whole-corpus retrieval.
+
+- For a new gate or hook/CI changes, read [Guardrail setup](references/guardrails.md).
+- For extraction, retrieval, cache, or matching changes, read
+  [Configuration and targeted diagnosis](references/configuration.md).
+
+Installing this skill supplies instructions; it does not activate a hook,
+install LRV, or establish a required CI check.
+
+## Interpret the result before repairing it
+
+| Finding | Agent's next step |
+| --- | --- |
+| Quote matched | Report source matching as passed. During evidence review, assess the attached claim, population, and direction of effect separately. |
+| Quote did not match | Compare the exact input with the retrieved content. Distinguish paraphrase, wrong citation, normalization, and missing full text. |
+| Title mismatch | Check identifier and source metadata together; changing the title to fit the wrong paper hides the real error. |
+| Source unavailable or prefix skipped | Report evidence as unchecked. Diagnose retrieval or source configuration; do not label the quote fabricated. |
+| Zero comparisons or unexpectedly low coverage | Inspect schema annotations, target class, missing evidence, file selection, and skip policy. Exit 0 does not establish coverage. |
+| Crash or invocation error | Repair the execution/configuration problem before drawing conclusions about the evidence. |
+
+An abstract-only record cannot establish that a quotation is absent from the
+full paper. Keep matched, failed, skipped, and unavailable evidence distinct;
+read coverage diagnostics alongside the exit status. Advisory output from a
+hook is not completion of the repository's required checks.
+
+## Correct the cause and close the loop
+
+When fixing evidence, inspect the source and the intended claim together.
+Transcribe a supported quote accurately; never invent wording or swap citations
+solely to obtain a pass. Preserve the source cache as evidence rather than
+editing it to match the submitted quote. Review any automated repair suggestion
+against the paper and schema before applying it.
+
+For configuration work, explain which records become checked or unchecked and
+demonstrate the intended behavior with representative passing and failing
+examples. Preserve established policy during routine repairs: adding a skipped
+prefix or lowering retrieval severity changes the QC contract.
+
+Rerun the affected check after corrections and the required repository checks
+before delivery. Report the file/field, reference ID, diagnosis, correction,
+command and outcome, source coverage, and any evidence still unchecked. Surface
+unresolved scientific interpretation or policy choices to the human curator.