flonat-research 0.1.0

package/skills/bib-validate/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: bib-validate
+description: "Cross-reference \\cite{} keys against .bib files or embedded \\bibitem entries. Finds missing, unused, and typo'd citation keys. Deep verification mode spawns parallel agents for DOI/metadata validation at scale. Fix mode auto-adds missing entries to Zotero."
+allowed-tools: Read, Glob, Grep, Task, Write, Bash(mkdir*), Bash(ls*), Bash(rm*), mcp__refpile__add_item, mcp__refpile__add_to_collection, mcp__refpile__search_library, mcp__paperpile__search_library, mcp__paperpile__export_bib
+argument-hint: [project-path or tex-file]
+---
+
+# Bibliography Validation
+
+**LIBRARY-FIRST RULE: ALWAYS cross-reference cited keys against both Zotero (`mcp__refpile__search_library`) and Paperpile (`mcp__paperpile__search_library`) during validation.** This catches drift between the `.bib` file and reference managers. See the Reference Manager Cross-Reference section.
+
+**Citation key rule:** Existing keys in the project always take precedence. They come from the user's reference management system and are canonical. When suggesting replacements (typo corrections, preprint upgrades, metadata fixes), always keep the user's key and update the `.bib` entry metadata around it — never suggest renaming a key to match some "standard" format.
+
+## When to Use
+
+- Before compiling a final version of a paper
+- After adding new citations to check nothing was missed
+- When `biber`/`bibtex` reports undefined citations
+- As part of a pre-submission checklist (pair with `/proofread`)
+
+## When NOT to Use
+
+- **Finding new references** — use `/literature` for discovery
+- **Building a bibliography from scratch** — use `/literature` with `.bib` generation
+- **General proofreading** — use `/proofread` (which also flags citation format issues)
+
+## Phase 0: Session Log (Suggested)
+
+Bibliography validation with preprint staleness checks can be context-heavy (OpenAlex lookups, web searches for published versions). Before starting, **suggest** running `/session-log` to capture prior work as a recovery checkpoint. If the user declines, proceed without it.
+
+## Convention
+
+**Default bibliography file is `references.bib`** — this is the standard across all projects (per the `/latex` skill convention). However, the skill also supports:
+
+- Any `.bib` file found in the same directory as the `.tex` files being audited
+- Embedded bibliographies using `\begin{thebibliography}` / `\bibitem{key}` blocks
+- Both external and embedded simultaneously (rare but possible)
+
+## Bibliography Detection
+
+At the start of validation, detect which bibliography method the project uses:
+
+### 1. External `.bib` file (standard)
+
+Look for `.bib` files in the project directory. Priority order:
+1. `references.bib` (preferred — standard naming convention across all projects)
+2. Any other `.bib` file in the same directory as the `.tex` files
+
+If **multiple `.bib` files** are found, validate all of them and produce a combined report. Note which file each issue belongs to. If a legacy-named `.bib` file (e.g., `paperpile.bib`) exists alongside `references.bib`, flag it as a potential cleanup opportunity (the project may have migrated from Paperpile).
+
+Full validation applies: cross-reference checks **and** quality checks.
+
+### 2. Embedded `\begin{thebibliography}` / `\bibitem{key}`
+
+Some LaTeX documents define references inline rather than using an external `.bib` file. Detect by scanning `.tex` files for `\begin{thebibliography}`.
+
+Extract keys from `\bibitem` entries:
+- `\bibitem{key}` — standard form, key is the argument in braces
+- `\bibitem[label]{key}` — optional label form (e.g., `\bibitem[Smith et al., 2020]{smith2020}`), key is in the **second** set of braces
+
+Only **cross-reference checks** apply (missing keys, unused keys, typos). Quality checks (required fields, year, author formatting) are **skipped** because embedded bibliographies don't have structured metadata.
+
+### 3. Both (rare)
+
+If a project has both a `.bib` file and `\begin{thebibliography}` blocks, validate both:
+- Run full validation on the `.bib` file
+- Run cross-reference checks on `\bibitem` entries
+- Merge both key sets when checking for missing citations
+
+## Workflow
+
+1. **Find files**: Locate all `.tex` files in the project
+2. **Detect bibliography type**: Check for `.bib` files and/or `\begin{thebibliography}` blocks
+3. **Extract citation keys from .tex**: Scan for all citation commands
+4. **Extract entry keys from bibliography source(s)**:
+   - External: Parse all `@type{key,` entries from `.bib` file(s)
+   - Embedded: Parse all `\bibitem{key}` and `\bibitem[label]{key}` entries
+5. **Cross-reference**: Compare the two sets
+6. **Quality checks**: Validate `.bib` entry completeness (external only)
+7. **Produce report**: Write results to stdout (or save if requested)
+
+## Citation Commands to Scan
+
+Scan `.tex` files for all of these patterns:
+
+| Command | Example |
+|---------|---------|
+| `\cite{key}` | Basic citation |
+| `\citet{key}` | Textual: Author (Year) |
+| `\citep{key}` | Parenthetical: (Author, Year) |
+| `\textcite{key}` | biblatex textual |
+| `\autocite{key}` | biblatex auto |
+| `\parencite{key}` | biblatex parenthetical |
+| `\citeauthor{key}` | Author name only |
+| `\citeyear{key}` | Year only |
+| `\nocite{key}` | Include in bibliography without in-text citation |
+
+Also handle **multi-key citations**: `\citep{key1, key2, key3}`
+
+## Cross-Reference Checks
+
+### Critical: Missing Entries
+
+Citation keys used in `.tex` but not defined in the bibliography source (`.bib` file or `\bibitem` entries).
+
+These will cause compilation errors.
+
+### Warning: Unused Entries
+
+Keys defined in the bibliography source but never cited in any `.tex` file.
+
+Not errors, but may indicate:
+- Forgotten citations (should they be `\nocite`?)
+- Leftover entries from earlier drafts
+- Entries intended for a different paper
+
+### Warning: Possible Typos (Fuzzy Match)
+
+For each missing key, check if a similar key exists in the bibliography using edit distance:
+- Edit distance = 1: Very likely a typo
+- Edit distance = 2: Possibly a typo
+- Flag these with the suggested correction
+
+Common typo patterns:
+- Year off by one: `smith2020` vs `smith2021`
+- Missing/extra letter: `santanna` vs `sant'anna` vs `santana`
+- Underscore vs camelCase: `smith_jones` vs `smithjones`
+
+## Reference Manager Cross-Reference
+
+After the disk-based cross-reference, check each cited key against Zotero (via RefPile MCP) and Paperpile (read-only). Produces a combined status table (HEALTHY / MIGRATE_TO_ZOTERO / DRIFT / EXPORT_GAP / MISSING).
+
+Full steps, MCP calls, and status categories: [`references/ref-manager-crossref.md`](references/ref-manager-crossref.md)
+
+## Quality Checks on .bib Entries
+
+**These checks apply only to external `.bib` files.** Embedded bibliographies lack structured metadata, so quality checks are skipped for them.
+
+### Required Fields by Entry Type
+
+| Entry Type | Required Fields |
+|-----------|----------------|
+| `@article` | author, title, journal, year |
+| `@book` | author/editor, title, publisher, year |
+| `@incollection` | author, title, booktitle, publisher, year |
+| `@inproceedings` | author, title, booktitle, year |
+| `@techreport` | author, title, institution, year |
+| `@unpublished` | author, title, note, year |
+| `@phdthesis` | author, title, school, year |
+
+### Year Reasonableness
+
+- Flag entries with year < 1900 or year > current year + 1
+- Flag entries with no year at all
+
+### Author Formatting
+
+- Check for inconsistent author formats within the file
+- **Flag entries where author field contains "and others" or "et al."** — this is never valid in BibTeX. All authors must be listed explicitly. Severity: **Warning**.
+- Flag entries with organisation names that might need `{{braces}}` to prevent splitting
+
+### DOI Resolution (optional — triggered by `--verify-dois` flag or when issues are suspected)
+
+**Preferred method: bibliography MCP `scholarly_verify_dois`.** Collect all DOIs from the `.bib` file and call `scholarly_verify_dois` (up to 50 per call). This batch-verifies each DOI against all enabled sources (OpenAlex, Scopus, WoS). Results:
+- **VERIFIED** (2+ sources confirm) — DOI is valid, metadata can be trusted
+- **SINGLE_SOURCE** (1 source only) — DOI exists but warrants a manual spot-check
+- **NOT_FOUND** — DOI not found in any source; resolve manually via WebFetch
+
+**Fallback for NOT_FOUND DOIs:** Resolve via `https://doi.org/[DOI]` and confirm the returned metadata matches the entry:
+
+1. **Title match**: Does the DOI landing page title match the `.bib` title?
+2. **Author match**: Does the first author on the landing page match the `.bib` first author?
+3. **Journal match**: Does the venue match?
+
+Flag mismatches as:
+- **Warning: DOI mismatch** — DOI resolves to a different paper than claimed. This usually means the DOI is wrong (adjacent DOI in the same journal volume) or the authors are wrong (conflation of researchers in the same subfield).
+
+This check catches:
+- Wrong DOIs (e.g., off-by-one in the DOI suffix)
+- Author conflation (real researchers incorrectly attributed to a paper)
+- Metadata copied from secondary sources without verification
+
+For manual WebFetch resolution, process in batches of 5 to avoid rate limiting. Only flag confirmed mismatches — if the DOI cannot be resolved (404, timeout), note it as "unresolvable" at Info level.
+
+### Preprint Staleness Check
+
+**For every entry that looks like a preprint**, check whether a peer-reviewed version has since been published. Full detection signals, lookup protocol, and classification: [`references/preprint-check.md`](references/preprint-check.md)
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| **Critical** | Missing entry for a cited key — will cause compilation error |
+| **Warning** | Unused entry, possible typo, missing required field |
+| **Info** | Year oddity, formatting suggestion, bibliography type note |
+
+## Bibliography Output
+
+After validation, offer these actions if applicable:
+
+- **Embedded bibliography → offer to create `references.bib`**: If the project uses `\begin{thebibliography}`, offer to extract the references into a proper `references.bib` file (one `@misc` entry per `\bibitem`, with the full text as a `note` field). The author can then enrich the entries with proper metadata.
+- **Non-standard `.bib` name → offer to rename**: If the existing `.bib` file is not named `references.bib`, offer to rename it to `references.bib` and update the `\bibliography{}` command in the `.tex` file.
+
+These are **offers only** — do not make changes without explicit confirmation.
+
+## Report Format
+
+Full report template with all sections: [`references/report-template.md`](references/report-template.md)
+
+Sections: Summary table → Critical (missing entries) → Warning (typos, unused, missing fields, DOI mismatches, stale preprints) → Info (year issues) → Limitations (for embedded bibliographies).
+
+## Optional: Metadata Verification via MCP Tools
+
+When missing entries or suspicious metadata are flagged, check these sources in order:
+
+1. **Paperpile** (paperpile MCP) — call `mcp__paperpile__search_library` by title. If found, use `mcp__paperpile__export_bib` to get correct BibTeX.
+2. **Zotero library** (refpile MCP) — call `search_library` by title. The user may already have the reference but with a different key.
+3. **Bibliography MCP** (scholarly sources):
+   - **`scholarly_search`** — search by title to find the correct entry across OpenAlex + S2 + Scopus + WoS
+   - **`scholarly_verify_dois`** — batch-verify DOIs across all sources (preferred over manual DOI resolution)
+   - **`scholarly_paper_detail`** — get full metadata including pre-formatted BibTeX (via S2 `citationStyles`), TLDR summary, and open access PDF link. Use for auto-generating BibTeX entries for missing references.
+   - **`scholarly_citations`** / **`scholarly_references`** — check citation context (how many papers cite this? what does it cite?) to assess relevance when deciding whether to keep or drop questionable entries
+   - **`openalex_lookup_doi`** — look up full metadata for a specific DOI
+
+For Python client fallback (citation networks, institution analysis): [`references/openalex-verification.md`](references/openalex-verification.md)
+
+## Deep Verification Mode (Parallel, Disk-Based)
+
+Triggered by: `--deep-verify` flag, 40+ entries, or "deep verify" / "verify all references". Spawns parallel sub-agents that verify batches and write results to disk. Full architecture, batch JSON format, and assembly: [references/deep-verify.md](references/deep-verify.md)
+
+## Council Mode (Optional)
+
+For high-stakes submissions. Trigger: "council bib-validate", "thorough bib check". Full details: [references/council-mode.md](references/council-mode.md)
+
+## Fix Mode
+
+After producing the validation report, automatically fix resolvable issues (DRIFT → add to Zotero, MISSING → search + add, MIGRATE → auto-add, metadata → correct BibTeX).
+
+Full auto-fix actions, post-fix maintenance, and skip conditions: [`references/fix-mode.md`](references/fix-mode.md)
+
+## Quality Scoring
+
+When producing a full validation report, apply numeric quality scoring using the shared framework:
+
+- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
+
+Map validation findings to the framework tiers:
+- **Critical** (-15 to -25): Missing entry for a cited key (compilation error)
+- **Major** (-5 to -14): DOI mismatch, stale preprint with published version available, "et al." in author field
+- **Minor** (-1 to -4): Missing optional fields, year oddities, unused entries
+
+Compute the score and include the Score Block in the report after the summary table.
+
+## Cross-References
+
+- **`/proofread`** — For overall paper quality including citation format
+- **`/literature`** — For finding and adding new references (includes full OpenAlex workflows)
+- **`/bib-coverage`** — Compare project `.bib` vs Zotero topic collection — find uncited papers and unfiled references
+- **`/latex`** — For compilation with reference checking
+- **`/latex-autofix`** — For compilation and error resolution. Run after fixing bibliography issues to verify citations compile cleanly.
+- **`shared/reference-resolution.md`** — Canonical lookup + filing sequence used by Ref Manager Cross-Reference and Fix Mode

package/skills/bib-validate/references/council-mode.md

@@ -0,0 +1,34 @@
+# Council Mode for Bibliography Validation
+
+> For high-stakes submissions, run bibliography validation in council mode. Different models have different knowledge of the academic literature -- one model may know a paper's correct DOI while another catches a metadata mismatch that the first misses.
+
+## When to Trigger
+
+- "Council bib-validate"
+- "Thorough bib check"
+
+## How It Works
+
+1. The main session collects all `\cite{}` keys and `.bib` entries
+2. The prompt is sent to 3 models via `cli-council`
+3. Each model independently cross-references keys, checks for typos, and verifies metadata
+4. Cross-review catches false positives (flagged entries that are actually correct) and surfaces additional issues
+5. Chairman synthesis produces a single `VALIDATION-REPORT.md`
+
+## Invocation (CLI backend -- free)
+
+```bash
+cd packages/cli-council
+uv run python -m cli_council \
+    --prompt-file /tmp/bib-validate-prompt.txt \
+    --context-file /tmp/bib-and-tex-content.txt \
+    --output-md /tmp/bib-validate-council.md \
+    --chairman claude \
+    --timeout 180
+```
+
+See the shared council protocol documentation for the full orchestration protocol.
+
+## Value
+
+Moderate to high -- most valuable in deep verification mode where DOI/metadata accuracy matters. Different models have genuinely different bibliographic knowledge.

package/skills/bib-validate/references/deep-verify.md

@@ -0,0 +1,79 @@
+# Deep Verification Mode
+
+> Triggered by: `--deep-verify` flag, or when the .bib has 40+ entries, or when the user says "deep verify" / "verify all references".
+
+This mode spawns parallel sub-agents that each verify a batch of entries and write structured results to disk -- bypassing context window limits entirely.
+
+## Architecture
+
+**MCP constraint:** MCP tools (`scholarly_verify_dois`, `scholarly_search`, etc.) are NOT available inside sub-agents — they are permission-scoped to the main conversation context only. The orchestrator must handle all MCP calls, and sub-agents must use Crossref REST API and WebFetch for DOI verification.
+
+```
+You (orchestrator)
++-- Read .bib file, extract all entries
++-- **Pre-verify all DOIs via MCP (main context):**
+|   +-- Call `scholarly_verify_dois` with all DOIs (max 50 per call)
+|   +-- Write results to verification_results/mcp_preverify.json
++-- Create verification_results/ directory in project root
++-- Batch entries into groups of 5
++-- Spawn parallel agents (max 5 concurrent), each:
+|   +-- Read mcp_preverify.json for pre-verified DOI status
+|   +-- For each entry in batch:
+|   |   +-- If DOI pre-verified as VERIFIED: check title match only
+|   |   +-- If DOI NOT_FOUND or SINGLE_SOURCE: verify via Crossref API (curl)
+|   |   +-- Check title matches DOI metadata
+|   |   +-- Check author consistency
+|   |   +-- Check year correctness
+|   |   +-- Check for published version if preprint (via WebSearch, NOT MCP)
+|   +-- Write results to verification_results/batch_N.json
++-- Wait for all agents to complete
++-- Read all batch JSON files
++-- Merge into verification_results/full_report.json
++-- Generate markdown summary highlighting entries needing attention
+```
+
+## Batch JSON Format
+
+Each agent writes a file `verification_results/batch_N.json`:
+
+```json
+[
+  {
+    "cite_key": "Author2020-ab",
+    "doi_valid": true,
+    "title_match": true,
+    "author_match": true,
+    "year_correct": true,
+    "preprint_status": "published_version_exists",
+    "published_doi": "10.1234/...",
+    "issues": [],
+    "suggested_fixes": {}
+  }
+]
+```
+
+## Agent Prompt Template
+
+Each sub-agent receives:
+- The batch of .bib entries (raw text)
+- The batch number
+- The output path: `verification_results/batch_N.json`
+- The path to `verification_results/mcp_preverify.json` (pre-verified DOI results from orchestrator)
+- Instructions to use **Crossref REST API** (`curl -sL "https://api.crossref.org/works?query.bibliographic=..."`) and **WebFetch** for DOI verification — **NOT** MCP tools (MCP is unavailable in sub-agents)
+- Instruction to write results to disk only -- never return large payloads
+
+## Assembly & Report
+
+After all agents complete:
+1. Read all `verification_results/batch_*.json` files
+2. Merge into `verification_results/full_report.json`
+3. Generate `verification_results/summary.md` with:
+   - Total entries verified
+   - Entries with issues (grouped by issue type)
+   - Suggested fixes
+   - Entries needing manual attention
+4. Print the summary to the user
+
+## Cleanup
+
+After the report is delivered, offer to delete `verification_results/` or keep it for reference.

package/skills/bib-validate/references/fix-mode.md

@@ -0,0 +1,36 @@
+# Fix Mode
+
+> Referenced from: `bib-validate/SKILL.md`
+
+After producing the validation report, automatically fix resolvable issues using the filing sequence from [`../shared/reference-resolution.md`](../../shared/reference-resolution.md).
+
+## Auto-Fix Actions
+
+1. **`DRIFT` entries** (in .bib but not in any reference manager):
+   - Add to Zotero via `mcp__refpile__add_item` using metadata from the `.bib` entry.
+   - File into topic collection + `_Needs Review` per the filing sequence.
+
+2. **`MISSING` entries** (cited in .tex but not found anywhere):
+   - Search via the resolution order (Zotero → Paperpile → bibliography MCP → Crossref → web).
+   - If found, export correct BibTeX and add the entry to the `.bib` file.
+   - Add to Zotero and file per the filing sequence.
+
+3. **`MIGRATE_TO_ZOTERO` entries** (in Paperpile but not Zotero):
+   - Auto-add to Zotero using Paperpile metadata.
+   - File into topic collection + `_Needs Review`.
+
+4. **Metadata issues** (DOI mismatch, stale preprint, missing fields):
+   - Export correct BibTeX from Paperpile (`mcp__paperpile__export_bib`) or bibliography MCP (`scholarly_search`) for entries with metadata problems.
+   - Present corrected entries for confirmation before overwriting.
+
+## Post-Fix Maintenance
+
+1. **Update `zotero-collections.md`** — increment item counts for affected collections.
+2. **Report summary** — show a table of all fixes applied: entry key, issue, action taken, status.
+
+## Skip Fix Mode
+
+Fix mode is skipped when:
+- The skill is invoked with `--report-only` or `--dry-run`
+- No actionable issues are found (all entries are `HEALTHY`)
+- Both refpile MCP and paperpile MCP are unavailable

package/skills/bib-validate/references/openalex-verification.md

@@ -0,0 +1,45 @@
+# Metadata Verification
+
+> Reference file for `/bib-validate`. Use when missing entries or suspicious metadata are found.
+
+## Preferred: Biblio MCP Tools
+
+**Always prefer MCP tools over the Python client** — they're faster, require no boilerplate, and query multiple sources.
+
+| Tool | Use for |
+|------|---------|
+| `scholarly_verify_dois` | Batch-verify DOIs across OpenAlex + Scopus + WoS (up to 50 per call) |
+| `scholarly_search` | Find a paper by title across all sources — useful when a cited key is missing |
+| `openalex_lookup_doi` | Look up full metadata for a single DOI |
+| `scholarly_similar_works` | Find related papers when a title search doesn't match exactly |
+
+## Fallback: Python Client
+
+**Python:** Always use `uv run python`. Never bare `python`, `python3`, `pip`, or `pip3`.
+
+Use the Python client only for workflows not exposed via MCP (citation networks, institution analysis):
+
+```bash
+uv run python -c "
+import sys
+sys.path.insert(0, '.scripts/openalex')
+from openalex_client import OpenAlexClient
+
+client = OpenAlexClient(email='user@example.edu')
+
+# Look up a specific DOI
+result = client.get_entity('works', 'doi:10.1016/j.ejor.2024.01.001')
+
+# Search by title to find the correct entry
+results = client.search_works(search='decision making under uncertainty', per_page=5)
+"
+```
+
+## When to use:
+
+- A cited key is missing and you want to confirm whether the paper exists
+- Year or author formatting looks suspicious and you want to cross-check
+- The user asks to enrich `.bib` entries with verified metadata
+- Batch DOI verification (use `scholarly_verify_dois` first)
+
+Do NOT use this by default — only when the report flags issues worth verifying.

package/skills/bib-validate/references/preprint-check.md

@@ -0,0 +1,31 @@
+# Preprint Staleness Check
+
+> Reference file for `/bib-validate`. Protocol for checking whether preprints have been published.
+
+## Detection — identify preprint entries by any of:
+
+| Signal | Examples |
+|--------|----------|
+| URL/DOI contains preprint host | `arxiv.org`, `ssrn.com`, `nber.org`, `repec.org`, `econpapers`, `ideas.repec` |
+| Journal/howpublished field | "arXiv preprint", "SSRN", "NBER Working Paper", "Working Paper", "mimeo" |
+| Entry type | `@techreport`, `@unpublished`, `@misc` with working-paper-like metadata |
+| Note field | Contains "preprint", "working paper", "wp", "discussion paper" |
+
+## Lookup — find the published version:
+
+1. **Biblio MCP `scholarly_search` first** (preferred — queries OpenAlex + Scopus + WoS with dedup):
+   Call `scholarly_search` with the paper title as query. Check if any result has a journal/venue and is not itself a preprint. Cross-source search increases the chance of finding the published version.
+2. **DOI resolution fallback**: If the preprint has a DOI, check if it redirects to or links to a published version.
+3. **Web search last resort**: Search for the paper title + "published" or "journal" if MCP returns nothing.
+
+## Classification:
+
+| Finding | Severity | Message |
+|---------|----------|---------|
+| Published version exists | **Warning** | "Preprint `key` appears published in *Journal Name* (Year). Consider updating the .bib entry." |
+| Published version exists with different title/authors | **Warning** | "Preprint `key` may have been published as '*new title*' in *Journal*. Verify and update." |
+| No published version found | **Info** | "Preprint `key` — no published version found (checked YYYY-MM-DD)." |
+
+## Report section:
+
+Add a `## Warning: Stale Preprints` section to the report listing all preprints where a published version was found, with the suggested replacement metadata (journal, year, DOI).

package/skills/bib-validate/references/ref-manager-crossref.md

@@ -0,0 +1,41 @@
+# Reference Manager Cross-Reference
+
+> Referenced from: `bib-validate/SKILL.md`
+
+After the disk-based cross-reference, check each cited key against the user's reference libraries using the resolution order from [`../shared/reference-resolution.md`](../../shared/reference-resolution.md). Two sources are available — check both when possible.
+
+## Zotero (Active Write Target — via RefPile MCP)
+
+Cross-reference via the `refpile` MCP server. For each citation key:
+
+1. Call `mcp__refpile__search_library` with the citation key as query
+2. Match on the `citationKey` field in results
+
+## Paperpile (Read-Only Cross-Reference)
+
+Cross-reference via the `paperpile` MCP server. For each citation key found in the `.tex` files:
+
+1. Call `mcp__paperpile__search_library` with the citation key as query
+2. Match on the citekey field in results
+3. For entries with issues, call `mcp__paperpile__get_item` for full metadata
+4. Use `mcp__paperpile__export_bib` to generate correct BibTeX for missing/outdated entries
+
+**Additional checks:**
+- Call `mcp__paperpile__get_labels` to verify folder organisation matches project themes
+- For projects with a known Paperpile label, call `mcp__paperpile__get_items_by_label` to find papers in the folder but not cited (potential missing citations)
+
+## Combined Status Categories
+
+| .bib | Zotero | Paperpile | Status | Report |
+|------|--------|-----------|--------|--------|
+| Yes | Yes | Yes | `HEALTHY` | `✓ In sync across all` |
+| Yes | Yes | No | `HEALTHY` | `✓ Zotero ↔ .bib in sync (not in Paperpile)` |
+| Yes | No | Yes | `MIGRATE_TO_ZOTERO` | `⚠ In Paperpile + .bib but not Zotero — auto-add?` |
+| Yes | No | No | `DRIFT` | `⚠ In local .bib but not in any reference manager` |
+| No | Yes | — | `EXPORT_GAP` | `ℹ In Zotero but not exported to local .bib` |
+| No | No | Yes | `EXPORT_GAP` | `ℹ In Paperpile but not exported to local .bib` |
+| No | No | No | `MISSING` | `✗ Missing from all — will add to Zotero in Fix Mode` |
+
+Include this as a "Reference Manager Sync" section in the report, after cross-reference results and before quality checks.
+
+**Graceful degradation:** If either MCP is unavailable, skip that source with a warning and continue with whatever is available. If both are unavailable, continue with disk-only validation.

package/skills/bib-validate/references/report-template.md

@@ -0,0 +1,82 @@
+# Bibliography Validation Report Template
+
+> Reference file for `/bib-validate`. Use this format for all validation reports.
+
+```markdown
+# Bibliography Validation Report
+
+**Project:** [path]
+**Date:** YYYY-MM-DD
+**Files scanned:** [list of .tex files]
+**Bibliography type:** External .bib / Embedded / Both
+**Bibliography:** [filename] ([N] entries) | Embedded ([N] \bibitem entries) | Both ([N] .bib + [N] \bibitem)
+**Citations found:** [N] unique keys across [N] citation commands
+
+## Summary
+
+| Check | Count |
+|-------|-------|
+| Missing entries (Critical) | 0 |
+| Possible typos (Warning) | 0 |
+| Unused entries (Warning) | 0 |
+| Missing required fields (Warning) | 0 |
+| DOI mismatches (Warning) | 0 |
+| Stale preprints (Warning) | 0 |
+| Year issues (Info) | 0 |
+
+## Critical: Missing Entries
+
+| Cited Key | File | Line | Suggested Match |
+|-----------|------|------|-----------------|
+| `smith2020` | main.tex | 42 | `smith2021` (edit dist: 1) |
+
+## Warning: Possible Typos
+
+[Keys with close fuzzy matches]
+
+## Warning: Unused Entries
+
+[Keys in bibliography not cited anywhere — listed for review]
+
+## Warning: Missing Required Fields
+
+*External .bib only — skipped for embedded bibliographies.*
+
+| Key | Type | Missing Fields |
+|-----|------|---------------|
+| `jones2019` | article | journal |
+
+## Warning: Stale Preprints
+
+| Key | Current Source | Published In | Year | DOI |
+|-----|---------------|--------------|------|-----|
+| `smith2020arxiv` | arXiv:2020.12345 | *J. of ML Research* | 2022 | 10.xxxx/yyyy |
+
+## Info: Year Issues
+
+[Entries with suspicious years]
+
+## Reference Manager Cross-Reference
+
+| Key | .bib | Zotero | Paperpile | Status |
+|-----|------|--------|-----------|--------|
+| `smith2020` | Yes | Yes | Yes | HEALTHY |
+| `jones2019` | Yes | No | Yes | MIGRATE_TO_ZOTERO |
+| `doe2021` | Yes | No | No | MISSING |
+
+## Fix Mode Actions
+
+*Omit this section if `--no-fix` was passed or no fixable issues were found.*
+
+| Action | Key | Result |
+|--------|-----|--------|
+| Added to Zotero | `doe2021` | Filed → [Topic Collection] + _Needs Review |
+| Migrated to Zotero | `jones2019` | Copied from Paperpile → [Topic Collection] + _Needs Review |
+| Metadata corrected | `smith2020` | Updated year: 2019 → 2020 |
+
+**Post-fix:** Updated `zotero-collections.md` item counts for [collection].
+
+## Limitations
+
+*If embedded:* Embedded bibliographies (`\bibitem`) lack structured metadata (author, year, journal as separate fields). Only cross-reference checks were performed. Quality checks (required fields, year reasonableness, author formatting) require an external `.bib` file.
+```